@parcha/agentrun-kernel 0.0.0-stage → 0.1.0-beta.29

package/dist/types.d.ts

@@ -0,0 +1,237 @@
+import type { WorkflowDeps } from "@parcha/agentrun-dsl";
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** What a node runner is asked, with the step it runs as under recovery and the node's own turn limit (#1061). */
+export type NodeRequest = Parameters<NonNullable<WorkflowDeps["runNode"]>>[0] & {
+    step?: {
+        sessionId: string;
+        attempt: number;
+        earlierSessionIds: readonly string[];
+    };
+    /** An `agent` node's `max_turns`; applied within the runner's own cap. */
+    maxTurns?: number;
+};
+/** An image a tool answers with: its media type (`image/png`) and its bytes, base64. */
+export interface ToolImage {
+    mimeType: string;
+    data: string;
+}
+/**
+ * The most characters a host tool's result reaches a harness with: its text as the model reads it (`text.length`). The
+ * kernel's tool bridge, which every host tool's result passes on its way to a harness, cuts every result past it: its
+ * start, cut where a character ends, then a line saying where it was cut (`[cut at N of M characters]`), the call's end
+ * flagged `truncated`; the call's record keeps it whole. Each harness tells its CLI to pass a result this long to the
+ * model whole: the Claude Agent CLI otherwise saves one past 50,000 characters to a file and tells the model to read it
+ * (which a confined session cannot), and Codex cuts the middle of one past its truncation policy. The Claude Agent CLI
+ * takes at most 500,000 here.
+ */
+export declare const HOST_RESULT_MAX_CHARS = 120000;
+/** A tool the host gives a session. */
+export interface HostTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** `safe`: may run again after a crash. `never`: at most once; a call a crash cut off is reported, never repeated. */
+    replay: "safe" | "never";
+    /** The tool's answer: its text (cut at HOST_RESULT_MAX_CHARS on its way to the harness), and any images it shows (a
+     *  screenshot), which a harness that can show them sends the model with the text. `sessionDir` is the runner's own,
+     *  when it has one: a tool that runs a node of its own (the delegate) gives its child a private directory the same
+     *  way, by the child's key. */
+    call(args: unknown, context: {
+        callId: string;
+        signal: AbortSignal;
+        sessionDir?: (key: string) => string;
+    }): Promise<{
+        text: string;
+        isError?: boolean;
+        images?: readonly ToolImage[];
+    }>;
+}
+/** One durable record of a session, in the order it was appended. */
+export interface SessionRecord {
+    kind: string;
+    data: JsonValue;
+}
+/** Where a session's records live: the run's store, written through whoever owns it. A key is one session for its
+ *  whole life, across processes. Records are written only through a writer, and one writer holds a session at a time:
+ *  `open` takes the session, and from the moment it resolves every writer opened earlier for that key is fenced, whether
+ *  or not the new one has written anything. A process whose lease lapsed while it was still alive therefore cannot write
+ *  into a session a newer process holds. */
+export interface SessionStore {
+    read(key: string): Promise<SessionRecord[]>;
+    /** Take the session. Resolves once the new holder is durable: every earlier writer of `key` is fenced from then on. */
+    open(key: string): Promise<SessionWriter>;
+}
+/** The one holder that may write a session. */
+export interface SessionWriter {
+    readonly key: string;
+    read(): Promise<SessionRecord[]>;
+    /** Resolves once the records are durable, in order. Rejects with `SessionFenced`, writing none of them, once a newer
+     *  `open` of the key has resolved. */
+    append(records: readonly SessionRecord[]): Promise<void>;
+}
+/** What one session is. */
+export interface SessionSpec {
+    /** The session's durable identity: a node step's `sessionId`, or a key of the runner's own for a call with no step. */
+    key: string;
+    label: string;
+    executionPath?: string;
+    system: string[];
+    /** Exactly these tools; the harness's own stay off. */
+    tools: HostTool[];
+    context: "fresh" | "fork";
+    tier?: NodeRequest["tier"];
+    effort?: NodeRequest["effort"];
+    thinking?: NodeRequest["thinking"];
+}
+/** A paid model request, as the session is about to send it. */
+export interface ModelRequest {
+    model: string;
+    /** The most input tokens the request can be billed for (the model proxy's `inputTokensMaxOf`: the body's UTF-8 bytes
+     *  plus what the provider adds), undefined when it was not measured. */
+    inputTokensMax?: number;
+    /** The most output tokens the request asks for, when its body says (the proxy's policy reads it). */
+    outputTokensAsked?: number;
+    /** The least output it may be limited to and still answer: its answer's 1,024 tokens, plus the least thinking its
+     *  provider takes when it thinks (the proxy's policy says). Absent: 1,024. */
+    outputTokensLeast?: number;
+}
+/** What a paid request cost, once it completed. */
+export interface ModelUsage {
+    input: number;
+    output: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    /** Null when the price is unknown; `estimated` when it is not the provider's own figure (the host's price table's). */
+    usd: number | null;
+    estimated?: boolean;
+    /** Beside the provider's own figure, what the host's price table makes of the same usage: kept to audit the table. */
+    tableUsd?: number | null;
+    /** A request a crash cut off: it left, and no answer came back to this run. Its tokens are unknown (0 here) and its
+     *  price is null; the provider may have billed it. */
+    cut?: boolean;
+    /** The ids the provider's response gave the request, by header name (the provider's `request-id`, a gateway's call
+     *  id such as LiteLLM's `x-litellm-call-id`): what joins this booking to the provider's own log. A cut request has
+     *  them only if its response had begun. */
+    providerIds?: Record<string, string>;
+    /** A response its client stopped part way, its cost unknown, with the bytes of it the client was sent (the model
+     *  proxy's `stoppedAfterBytes`): the host counts it by what streamed (`Admission.stoppedUsd`), never more than its hold. */
+    stoppedAfterBytes?: number;
+}
+/** The session's model requests, through the runner: every paid request is announced before it is sent, and may be
+ *  refused there (a turn cap, the host's budget); its usage is reported when it completes. */
+export interface ModelPort {
+    /** Admits a paid request, or throws to refuse it. It may return the request's ticket, which names the turn it was admitted as. */
+    beforeRequest(request: ModelRequest): Promise<ModelTicket | void>;
+    /** Books a completed request. `ticket` is what its own `beforeRequest` returned: requests may be in flight together, so
+     *  an answer is booked under the turn it was admitted as, not the latest one. */
+    afterRequest(usage: ModelUsage, ticket?: ModelTicket): Promise<void>;
+    /** Records the ids a paid request's response gave it, as its headers arrive and before its answer is read. */
+    responded?(ids: Record<string, string>, ticket?: ModelTicket): Promise<void>;
+}
+/** A paid request's admission: the turn it was admitted as, which its answer is booked under. */
+export interface ModelTicket {
+    turn: number;
+    /** The most output tokens, thinking included, the request may be sent with: what is left of its host's spend cap can
+     *  buy. The session's model proxy writes it into the body; absent, the request goes as asked. */
+    outputTokensMax?: number;
+}
+/** What the host lends a session. */
+export interface SessionIO {
+    /** The session's writer, opened by the runner for this attempt. The adapter writes through it and never opens the
+     *  session itself, so a drive it restarts cannot take the session back from a newer process. */
+    writer: SessionWriter;
+    models: ModelPort;
+    signal: AbortSignal;
+    /** The session's private directory, when the host gives one: its HOME and the harness's own files. */
+    dir?: string;
+    /** The session's working directory, when the host gives one: the workspace its file tools confine to, absolute. A
+     *  harness runs there, so a path the model builds from its working directory is one the host's tools take. Without it,
+     *  a harness works in an empty directory of its own. */
+    cwd?: string;
+    onEvent(event: AdapterEvent): void;
+}
+/** An event of a session, as the adapter reports it. The runner adds the node it belongs to. A call's `tool_end` is sent
+ *  only once its outcome is durable in the session's records, so a host never shows a result its store does not have;
+ *  `result` is the text recorded, when the adapter reports it. A call stopped before its outcome was recorded gets no
+ *  `tool_end`: its turn's `turn_end` closes it. */
+export type AdapterEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "tool_start";
+    callId: string;
+    name: string;
+    args: unknown;
+    parent?: string;
+} | {
+    type: "tool_end";
+    callId: string;
+    name: string;
+    isError: boolean;
+    result?: string;
+    truncated?: true;
+} | {
+    type: "turn_end";
+    status: TurnStatus;
+};
+/** An event as a host receives it: the adapter's, the runner's own, and the node each belongs to. */
+export type HarnessEvent = (AdapterEvent | {
+    type: "request_start";
+    turn: number;
+    model: string;
+} | {
+    type: "request_end";
+    turn: number;
+    usage: ModelUsage;
+}) & {
+    key: string;
+    label: string;
+    executionPath?: string;
+};
+export type TurnStatus = "completed" | "interrupted" | "failed";
+/** A session as `open` found it: new, cut off inside a turn (the adapter owes a recovery turn), or between turns. */
+export type SessionState = "new" | "open_turn" | "idle";
+export interface AdapterSession {
+    readonly state: SessionState;
+    /** Place the input, then send it: a new turn. */
+    send(text: string): Promise<void>;
+    /** Resume the turn a crash cut off, from the session's records. Only when `state` is `open_turn`. */
+    recover(): Promise<void>;
+    /** Record the open turn as ended, interrupted, and send nothing: the turn is not to be resumed (a person stopped it, and
+     *  an interrupt writes no end in the session). Only when `state` is `open_turn`; the session is `idle` after, here and
+     *  when a later process opens it, and the next `send` is a turn of its own. A follow-up closes a cut turn the same way
+     *  (kernel/follow-up.ts, FollowUpTarget.settleOpenTurn). */
+    settleOpenTurn(): Promise<void>;
+    /** Resolves when the turn in flight ends. */
+    turnEnd(): Promise<{
+        status: TurnStatus;
+        error?: string;
+    }>;
+    /** Stop the turn in flight; calls it left open end interrupted. With `drainMs`, a pause: no new turn is sent, and the
+     *  calls in flight run on until their outcomes are recorded, for at most `drainMs`, before the turn stops; the host
+     *  refuses new calls and paid requests meanwhile (the runner's `stop` does). An adapter that cannot drain stops at
+     *  once, as with no `drainMs`. It only stops the turn: the turn stays open in the session's records, and an adapter
+     *  whose session can tell reads `open_turn` after it while it does, so a host that is done with the turn (a person's
+     *  stop) settles it with `settleOpenTurn()`, and one that is not (a pause) leaves it for the next process. */
+    interrupt(options?: {
+        drainMs?: number;
+    }): Promise<void>;
+    /** Stop the harness's processes and let go of the session. */
+    close(): Promise<void>;
+}
+export interface AdapterCapabilities {
+    /** Whether the adapter can start a session from another's transcript. */
+    fork: boolean;
+}
+export interface AgentAdapter {
+    readonly id: string;
+    /** The harness version the adapter is pinned to. */
+    readonly version: string;
+    capabilities(): AdapterCapabilities;
+    /** Problems with a session before anything is spent; an empty list opens it. */
+    check(spec: SessionSpec): string[];
+    /** Opens the session, restoring it from `io.writer` when its key has records. */
+    open(spec: SessionSpec, io: SessionIO): Promise<AdapterSession>;
+}

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * The most characters a host tool's result reaches a harness with: its text as the model reads it (`text.length`). The
+ * kernel's tool bridge, which every host tool's result passes on its way to a harness, cuts every result past it: its
+ * start, cut where a character ends, then a line saying where it was cut (`[cut at N of M characters]`), the call's end
+ * flagged `truncated`; the call's record keeps it whole. Each harness tells its CLI to pass a result this long to the
+ * model whole: the Claude Agent CLI otherwise saves one past 50,000 characters to a file and tells the model to read it
+ * (which a confined session cannot), and Codex cuts the middle of one past its truncation policy. The Claude Agent CLI
+ * takes at most 500,000 here.
+ */
+export const HOST_RESULT_MAX_CHARS = 120_000;

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@parcha/agentrun-kernel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.29",
+  "description": "Agent harnesses other than Pi, starting with Codex, behind one seam: a DSL node's runNode and an AgentRun run on a harness adapter, durable in AgentRun's own store.",
+  "keywords": [
+    "agentrun",
+    "agent",
+    "harness",
+    "durable",
+    "workflow"
+  ],
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Parcha Labs, Inc.",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    },
+    "./kernel": {
+      "types": "./dist/kernel/index.d.ts",
+      "default": "./dist/kernel/index.js"
+    },
+    "./process": {
+      "types": "./dist/process/index.d.ts",
+      "default": "./dist/process/index.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "default": "./dist/host/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE",
+    "vendor/durable-harness/UPSTREAM.json"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test --test-concurrency=8 'test/*.test.mjs'"
+  },
+  "dependencies": {
+    "@parcha/agentrun-dsl": "0.1.0-beta.29",
+    "ajv": "8.18.0",
+    "typebox": "1.3.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Parcha-ai/agentrun.git",
+    "directory": "packages/run-adapters"
+  },
+  "bugs": {
+    "url": "https://github.com/Parcha-ai/agentrun/issues"
+  },
+  "homepage": "https://agentrun.ai",
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  }
+}

package/vendor/durable-harness/UPSTREAM.json

@@ -0,0 +1,67 @@
+{
+  "repo": "github.com/vercel-labs/durable-harness",
+  "commit": "ea8aa4060cf4fb8cd39737ce8ab21c4e0f40c741",
+  "license": "Apache-2.0",
+  "copyright": "Copyright 2026 Vercel Inc.",
+  "notice": null,
+  "files": {
+    "src/process/records.ts": {
+      "upstream": "packages/harness-process/src/records.ts",
+      "blob": "8ce81fe33c7bc8a563030f021e5f2bcdcc2b9597",
+      "sha256": "53b1ed7e60756835e112e7387e483d3baf92385c50b1906d69f5c3e55f5879bc"
+    },
+    "src/process/recovery.ts": {
+      "upstream": "packages/harness-process/src/recovery.ts",
+      "blob": "57e495656f63dde58d11c7775601132dd99d09e6",
+      "sha256": "16fcd724a3646b1218833ba8aad4141b757ae992cb55ac523aa2690b34e00640"
+    },
+    "src/process/journal.ts": {
+      "upstream": "packages/harness-process/src/journal.ts",
+      "blob": "a86848a6ce7962f1325b2b73fed47772ca16e6a3",
+      "sha256": "73e0f451d008d82692462e66719f51686bf92898b9d0088e8658450fffdfd182"
+    },
+    "src/process/tools.ts": {
+      "upstream": "packages/harness-process/src/tools.ts",
+      "blob": "f0dab38d2440513c84e442dfed8d6a8a5d654616",
+      "sha256": "e8f811beffb7eab60fc245f28cd6082228bbe11d1d0260d3f1946c67c1fbfe14"
+    },
+    "src/process/builtins.ts": {
+      "upstream": "packages/harness-process/src/builtins.ts",
+      "blob": "602487d768314e68eca215fd582e9d2e4cd37482",
+      "sha256": "62750338eb34974b22ee8de74783fe2b373adfdcad57f882b032cc8941e722dd"
+    },
+    "src/process/inbox.ts": {
+      "upstream": "packages/harness-process/src/inbox.ts",
+      "blob": "0f588d2d9f9d5e35882a09b6a921a72a80058ad7",
+      "sha256": "59d2a96779b065dfcb90868c4a7216bbdc98d90663fd45b9953a48c0b4c9ceae"
+    },
+    "src/process/tail.ts": {
+      "upstream": "packages/harness-process/src/tail.ts",
+      "blob": "0c9f118023f7e7122621c84c4766b478fe8a73ca",
+      "sha256": "8814035a33a55916306f2e91f9fb582389556da858a94085449f0a66aba4846d"
+    },
+    "src/kernel/types.ts": {
+      "upstream": "packages/harness-world/src/types.ts",
+      "blob": "d12a050e7395a6a4d5319acf88ba3d728b783443",
+      "sha256": "775a12d0c7737dad58ac8b5e8a9695c559762a8196b7cd78b48fa284803a9a3f",
+      "kind": "interfaces matched",
+      "declarations": [
+        "EffectRecord"
+      ]
+    },
+    "src/kernel/errors.ts": {
+      "upstream": "packages/harness-world/src/errors.ts",
+      "blob": "f778e8b800281227c9b005865a02e1026cc1fefd",
+      "sha256": "672cd4afb4caa648737f74b0ea71c0fc4bba53fb518de7c3e6303648de2c8d2f",
+      "kind": "interfaces matched",
+      "declarations": [
+        "EffectFailure"
+      ]
+    },
+    "src/process/zod.ts": {
+      "upstream": "packages/harness-process/src/zod.ts",
+      "blob": "67c50b6ede18d73a8edd7006a301e22d10580242",
+      "sha256": "3a1cac6ac89608ae63cbd8ef5ceeccd46cf6aff184c62011a4d9966f85b4b92f"
+    }
+  }
+}