npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@paraharness/core

v0.2.11

Published

Declarative pure-AST agent orchestration DSL (P.*), capability-tiered isolation scope ports, and durable continuation-stack execution runtime.

Readme

@paraharness/core

Declarative multi-agent orchestration and durable execution for TypeScript. → API Documentation

Paraharness is a TypeScript framework for building autonomous LLM agent systems that run over isolated workspaces. Instead of writing ad-hoc prompt loops and unguarded shell tools, you declare agents, capability policies, verification loops, and multi-step flows with the P.* DSL, compile them into a pure passive AST, and execute them on a crash-recoverable runtime (@paraharness/core/runtime).

Installation

With npm:

npm install @paraharness/core zod

With yarn:

yarn add @paraharness/core zod

With pnpm:

pnpm add @paraharness/core zod

Quick Start

import { P, z } from '@paraharness/core';
import { createRuntime, runFlow, runStep } from '@paraharness/core/runtime';
import { claude, claudeExecutors } from '@paraharness/claude';
import { fs, fsExecutors } from '@paraharness/fs';
import { git, gitExecutors } from '@paraharness/git';
import { local, nodeExecutors } from '@paraharness/node';
import { sqlite, sqliteExecutors } from '@paraharness/sqlite';

const TaskInput = z.object({
  taskId: z.string(),
  prompt: z.string(),
});

const runner = local.runner({ slots: 4, maxDaemons: 2 });
const sonnet = claude.model('claude-sonnet-4-6');

const verifySuite = local
  .streamCheck('verify-suite')
  .runner(runner)
  .argv(['pnpm', 'test', '--run'])
  .circuitBreakWhenStdout(/FAIL/);

const worker = P.agent('worker')
  .model(sonnet)
  .tools(fs.codingTools(), verifySuite.asTool())
  .instructions('Implement the requested change and keep all checks passing.')
  .beforeStop(verifySuite)
  .input(TaskInput)
  .output(z.object({ summary: z.string() }));

const stepOut = await runStep(
  worker,
  { taskId: 'task-1', prompt: 'Add input validation' },
  {
    registry: [claudeExecutors, fsExecutors, nodeExecutors],
    env: process.env,
  },
);

const deliveryFlow = P.flow('delivery-flow')
  .input(TaskInput)
  .scope(git.cowWorktree())
  .step('implement', worker)
  .exit('done');

const flowResult = await runFlow(
  deliveryFlow,
  { taskId: 'task-1', prompt: 'Add input validation' },
  {
    registry: [claudeExecutors, fsExecutors, gitExecutors, nodeExecutors, sqliteExecutors],
    ledger: sqlite.ledger('.harness/state.sqlite'),
    env: process.env,
  },
);

const harness = P.harness('engineering-harness')
  .ledger(sqlite.ledger('.harness/state.sqlite'))
  .pools(runner)
  .lanes(
    P.lane('main-lane')
      .input(TaskInput)
      .key((item) => item.taskId)
      .runs(deliveryFlow)
      .concurrency(2)
      .priority('normal'),
  );

const runtime = createRuntime(harness, {
  registry: [claudeExecutors, fsExecutors, gitExecutors, nodeExecutors, sqliteExecutors],
  env: process.env,
});
await runtime.start();

Usage

Policy Guardrails & Post-Flight Rollbacks

Attach P.policy masks to restrict what files an agent can mutate, intercept edits to existing tests via typed P.interrupt escalations, and enforce turn and budget ceilings with automatic workspace rollback if a subprocess mutates protected paths:

import { P, z } from '@paraharness/core';
import { fs } from '@paraharness/fs';
import { git } from '@paraharness/git';

const leaseRequest = P.interrupt(
  'lease-request',
  z.object({
    requestedPaths: z.array(z.string()),
    justification: z.string(),
  }),
);

const workerPolicy = P.policy('worker-policy')
  .guard(fs.protect(['packages/*/src/index.ts', 'PRODUCT_SPEC.md', '.harness/**']))
  .onViolation('deny-with-error')
  .guard(
    fs.writeGuard({
      denyGlobs: ['**/*.test.ts', '**/*.test.tsx'],
      onlyExistingAtBaseRef: true,
    }),
  )
  .onViolation('raise-interrupt', leaseRequest, (violation) => ({
    requestedPaths: fs.violatedPaths(violation),
    justification: violation.violationSummary,
  }))
  .tripwire(fs.maxFilesMutated(6))
  .maxTurns(12)
  .maxCostUsd(2.0)
  .onAbort(git.snapshotAndReset());

Act-Evaluate Verification Loops

Pair a write-capable implementation agent with a read-only adversarial evaluator inside P.loop. Rejected iterations append structured deficits directly onto the actor's preserved session until all checks and review criteria pass:

import { P, z } from '@paraharness/core';
import { fs } from '@paraharness/fs';
import { git } from '@paraharness/git';

const readOnlyPolicy = P.policy('read-only')
  .guard(fs.readOnly())
  .onViolation('deny-with-error');

const evaluator = P.agent('evaluator')
  .model(sonnet)
  .policy(readOnlyPolicy)
  .tools(fs.readOnlyTools(runner))
  .instructions('Audit the candidate diff and reject if any edge cases or tests are missing.')
  .input(
    z.object({
      task: TaskInput,
      candidate: z.object({ summary: z.string() }),
      scopeReceipt: git.ScopeReceiptSchema,
    }),
  )
  .output(
    z.object({
      accepted: z.boolean(),
      deficits: z.array(z.string()),
    }),
  );

const verifiedWorkerLoop = P.loop('verified-worker-loop')
  .maxIterations(3)
  .preserveActorSession(true)
  .act('execute', worker.withPolicy(workerPolicy))
  .evaluate('audit', evaluator, {
    mapInput: (task, candidate, scopeReceipt) => ({ task, candidate, scopeReceipt }),
    acceptWhen: (ev) => ev.accepted && ev.deficits.length === 0,
    feedbackMapper: (ev) => `Resolve these deficits:\n- ${ev.deficits.join('\n- ')}`,
  });

Parallel Subagent Forks & Speculative Tournaments

Equip coordinator agents with .fork() for isolated child worktree delegation and .speculate() to race competing implementation strategies across parallel Copy-on-Write worktrees judged by an arbiter:

import { P, z } from '@paraharness/core';
import { git } from '@paraharness/git';

const candidateArbiter = P.agent('candidate-arbiter')
  .model(sonnet)
  .tools(fs.readOnlyTools(runner), git.candidateComparisonTools(runner))
  .instructions('Select the strongest candidate branch or reject all.')
  .input(
    P.SpeculationInputSchema(
      TaskInput,
      z.object({ summary: z.string() }),
      git.ScopeReceiptSchema,
    ),
  )
  .output(
    z.discriminatedUnion('decision', [
      z.object({
        decision: z.literal('select-winner'),
        winnerBranchIndex: z.union([z.literal(0), z.literal(1)]),
        rationale: z.string(),
      }),
      z.object({
        decision: z.literal('reject-all'),
        rationale: z.string(),
      }),
    ]),
  );

const coordinator = P.agent('coordinator')
  .model(sonnet)
  .tools(fs.codingTools(runner), git.refReaderTools(runner))
  .instructions('Decompose tasks across partitions or run speculative tournaments for high-risk changes.')
  .input(TaskInput)
  .output(z.object({ summary: z.string() }))
  .capabilities(($cap) =>
    $cap
      .fork('delegate-subtask', verifiedWorkerLoop, ($f) =>
        $f
          .historyMode('shared-prefix-only')
          .requestSchema(z.object({ subtaskPrompt: z.string() }))
          .mapInput((parent, req) => ({
            taskId: parent.taskId,
            prompt: req.subtaskPrompt,
          })),
      )
      .speculate('explore-candidates', ($s) =>
        $s
          .requestSchema(
            z.object({
              strategyA: z.string(),
              strategyB: z.string(),
            }),
          )
          .worker(verifiedWorkerLoop)
          .branches(2, (parent, req) => [
            { taskId: parent.taskId, prompt: req.strategyA },
            { taskId: parent.taskId, prompt: req.strategyB },
          ])
          .arbiter(candidateArbiter),
      ),
  );

Warm-Fork Prefix Caching, Topology & Empirical Lessons

Pin byte-identical system prompts across agent roles with P.prefixGroup, declare partition dependency graphs with P.topology, and distill empirical lessons from loop and gate recoveries with P.lessons:

import { P } from '@paraharness/core';
import { fs } from '@paraharness/fs';
import { md } from '@paraharness/markdown';
import { sqlite } from '@paraharness/sqlite';

const repoTopology = P.topology('repo-topology')
  .store(sqlite.topologyStore('.harness/state.sqlite'))
  .partitions({
    db: {},
    api: { dependsOn: ['db'] },
    web: { dependsOn: ['api'] },
  });

const repoRules = P.rules('repo-rules')
  .global(md.globalRules('.harness/rules/global/*.md'))
  .scoped(md.scopedRules('.harness/rules/scoped/*.md'));

const sharedPrefix = P.prefixGroup('engineering-prefix')
  .toolsMode('role-scoped')
  .sharedGrounding(fs.text('PRODUCT_SPEC.md'), fs.text('TECH_DESIGN.md'))
  .sharedInstructions(fs.text('.harness/prompts/base-posture.md'))
  .sharedRules(repoRules);

const repoLessons = P.lessons('repo-lessons')
  .store(sqlite.lessonStore('.harness/state.sqlite'))
  .queryFrom(TaskInput, (item) => item.prompt)
  .distillWith(sonnet, ($d) => $d.onLoopRecovery().onGateRecovery({ minFailedChecks: 1 }));

Custom Domain AST Extensions (CustomDomainASTRegistry)

Third-party adapter packages extend @paraharness/core AST unions without casting via module augmentation on CustomDomainASTRegistry and the exported Base*ASTNode interfaces (BaseAbortHookASTNode, BaseAccountSeatASTNode, BaseCheckASTNode, BaseControlPlaneASTNode, BaseCrossVerifierASTNode, BaseDomainStepASTNode, BaseEffectMatcherASTNode, BaseHumanChannelASTNode, BaseIsolationScopeASTNode, BaseLedgerStoreASTNode, BaseLessonStoreASTNode, BaseModelASTNode, BasePolicyGuardASTNode, BaseQuotaTripwireASTNode, BaseRunnerPoolASTNode, BaseScopeRewindHookASTNode, BaseServiceASTNode, BaseSourceASTNode, BaseStepASTNode, BaseStreamSourceASTNode, BaseTelemetryCollectorASTNode, BaseToolASTNode, BaseTopologyStoreASTNode, BaseTrackerASTNode):

import type { BaseToolASTNode } from '@paraharness/core';

export interface CustomSearchToolNode extends BaseToolASTNode<'custom:search-tool', 'declared'> {
  readonly type: 'custom:search-tool';
  readonly indexName: string;
}

declare module '@paraharness/core' {
  interface CustomDomainASTRegistry {
    readonly tool: CustomSearchToolNode;
  }
}

Packages

| Package | Description | | :--- | :--- | | @paraharness/core | Core declarative P.* DSL builders, AST contracts, port interfaces, and durable execution runtime (@paraharness/core/runtime) | | @paraharness/node | Local OS subprocess runner pools, one-shot commands, circuit-breaking stream checks, PTY daemons, and MCP control planes (local.*, mcp.*) | | @paraharness/git | Copy-on-Write Git worktree isolation scope, git-index checkpoints, 3-way merge-tree reconciliation, and candidate comparison tools (git.*) | | @paraharness/fs | Workspace-jailed file tools, glob matchers, pre/post-flight write guards, quota tripwires, and atomic JSONL lesson store (fs.*) | | @paraharness/markdown | Frontmatter and section-aware Markdown loaders for global rules, scoped rules, and on-demand skills (md.*) | | @paraharness/sqlite | WAL-mode SQLite drivers for LedgerStore, Copy-on-Write TopologyStore, LessonStore, and global rules (sqlite.*) | | @paraharness/postgres | Distributed PostgreSQL drivers for LedgerStore, Copy-on-Write TopologyStore, LessonStore, and global rules (postgres.*) | | @paraharness/lockfile | Cross-process advisory lockfile utility with p-queue in-process serialization, heartbeat, and stale lock reclamation (withFileLock) | | @paraharness/unified-memory | Unified memory ledger, MCP server, and just-in-time file-interaction hook for rules, empirical lessons, and operational notes (MemoryHarness, MemoryMcpServer, mem) | | @paraharness/claude | Anthropic Claude /v1/messages ModelDriver and AST builders (claude.cliAccount, claude.model) | | @paraharness/openai | OpenAI Responses API & Codex CLI ModelDriver and AST builders (openai.account, openai.cliAccount, openai.model) | | @paraharness/gemini | Google Gemini generateContent ModelDriver and AST builders (gemini.account, gemini.cliAccount, gemini.model) | | @paraharness/github | GitHub Issues tracker adapter, HMAC-SHA256 webhook event stream source, and idempotent pull-request step executor (github.*) | | @paraharness/slack | Slack Socket Mode interactive human approval / control-plane adapter and incoming webhook notifier (slack.*) |

Documentation

License

MIT © Tornike Tsomaia