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

package/dist/process/zod.js

@@ -0,0 +1,109 @@
+// Copyright 2026 Vercel Inc. Licensed under the Apache License, Version 2.0; see LICENSE in this package.
+// From github.com/vercel-labs/durable-harness, packages/harness-process/src/zod.ts at ea8aa4060c (UPSTREAM.json records its blob and sha256).
+// Changed by Parcha, patches: 005-comments-name-the-agent-sdk
+/**
+ * JSON Schema to zod, for harness SDKs whose tool APIs take zod (the Claude
+ * Agent SDK's in-process MCP tools, OpenCode's plugin tools). `HostTool`s carry
+ * JSON Schema; this converts the subset tool schemas use.
+ *
+ * zod is passed in (`import { z } from 'zod'`, v3 or v4) so this package
+ * does not pin one: use the one the harness SDK was built against.
+ *
+ * Adapted from the AI SDK's bridge (vercel/ai cbb6b49,
+ * `packages/harness-claude-code/src/bridge/json-schema-to-zod.ts`,
+ * Apache-2.0); changed to take `z` as a parameter and to export the shape.
+ */
+/** A zod object for a JSON Schema object (extra properties allowed unless `additionalProperties: false`). */
+export function zodFromJsonSchema(schema, z) {
+    return toZodObject(isSchema(schema) ? schema : {}, z);
+}
+/** The raw shape (`{ key: zodType }`) of a JSON Schema object, for APIs that take a shape. */
+export function zodShapeFromJsonSchema(schema, z) {
+    return toZodShape(isSchema(schema) ? schema : undefined, z);
+}
+function toZodObject(schema, z) {
+    const object = z.object(toZodShape(schema, z));
+    if (schema.additionalProperties === false)
+        return object.strict();
+    // JSON Schema allows additional properties by default; zod strips them.
+    return object.catchall(isSchema(schema.additionalProperties) ? toZodType(schema.additionalProperties, z) : z.unknown());
+}
+function toZodShape(schema, z) {
+    if (!schema?.properties)
+        return {};
+    const required = new Set(schema.required);
+    const shape = {};
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        let type = toZodType(prop, z);
+        if (!required.has(key))
+            type = type.optional();
+        if (prop.description)
+            type = type.describe(prop.description);
+        shape[key] = type;
+    }
+    return shape;
+}
+function toZodType(schema, z) {
+    if (!schema)
+        return z.any();
+    let type = forConst(schema, z) ?? forEnum(schema, z) ?? forUnion(schema, z) ?? forType(schema, z);
+    if (schema.nullable === true || (Array.isArray(schema.type) && schema.type.includes('null')))
+        type = type.nullable();
+    if (schema.description)
+        type = type.describe(schema.description);
+    return type;
+}
+function forType(schema, z) {
+    const types = Array.isArray(schema.type) ? schema.type.filter((t) => t !== 'null') : [schema.type].filter(Boolean);
+    if (types.length > 1)
+        return z.any();
+    if (Array.isArray(schema.type) && types.length === 0)
+        return z.null();
+    switch (types[0] ?? (schema.properties ? 'object' : undefined)) {
+        case 'string':
+            return z.string();
+        case 'number':
+            return z.number();
+        case 'integer':
+            return z.number().int();
+        case 'boolean':
+            return z.boolean();
+        case 'array':
+            return z.array(Array.isArray(schema.items) ? z.any() : toZodType(schema.items, z));
+        case 'object':
+            return toZodObject(schema, z);
+        case 'null':
+            return z.null();
+        default:
+            return z.any();
+    }
+}
+function forConst(schema, z) {
+    if (!('const' in schema))
+        return undefined;
+    return isLiteral(schema.const) ? z.literal(schema.const) : z.any();
+}
+function forEnum(schema, z) {
+    if (!Array.isArray(schema.enum))
+        return undefined;
+    if (!schema.enum.every(isLiteral))
+        return z.any();
+    const values = schema.enum;
+    if (values.length === 0)
+        return z.any();
+    if (values.length === 1)
+        return z.literal(values[0]);
+    return z.union(values.map((v) => z.literal(v)));
+}
+function forUnion(schema, z) {
+    const options = schema.anyOf ?? schema.oneOf;
+    if (!options || options.length < 2)
+        return undefined;
+    return z.union(options.map((o) => toZodType(o, z)));
+}
+function isSchema(input) {
+    return input != null && typeof input === 'object' && !Array.isArray(input);
+}
+function isLiteral(value) {
+    return value === null || typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+}

package/dist/runner.d.ts

@@ -0,0 +1,154 @@
+import type { AgentAdapter, HarnessEvent, HostTool, ModelPort, ModelUsage, NodeRequest, SessionRecord, SessionStore, SessionWriter } from "./types.js";
+/** Exactly the interpreter's `runNode`, plus `stop`: a pause of every node it is running. With `drainMs`, each node
+ *  starts no new turn, call or paid request, its calls in flight run on until their outcomes are recorded (for at most
+ *  `drainMs`, on an adapter that can drain), and then it stops, failing `aborted`; its session resumes from its records
+ *  when the node runs again. A node started after `stop` fails `aborted` at once. Resolves once every node has stopped. */
+export type HarnessRunner = ((request: NodeRequest) => Promise<unknown>) & {
+    stop(options?: {
+        drainMs?: number;
+    }): Promise<void>;
+};
+/** The tool the runner injects; a host tool may not take its name. */
+export declare const SUBMIT_TOOL = "submit";
+/** The records the runner keeps beside the adapter's own, in each session. */
+/** `request` is written before a paid request leaves, `turn` when it has answered with its usage: a request a crash cut off
+ *  keeps its `request` and has no `turn`. */
+export declare const RUNNER_RECORDS: {
+    readonly request: "runner.request";
+    readonly response: "runner.response";
+    readonly turn: "runner.turn";
+    readonly submit: "runner.submit";
+    readonly accepted: "runner.accepted";
+};
+/** What the host is asked before each paid request. A `refuse` ends the node, final. A `holdUsd` (a finite amount, 0
+ *  or more) is what the host holds for the request, its cap's worst case: written on the request's record before it
+ *  leaves, it is what the request counts at in the spend the host is shown when the request's own cost never comes in
+ *  (a response cut short, booked at an unknown cost, or a request a crash cut off, read by a later process). Without
+ *  one, such a request leaves the spend unknown. The cost booked for the request is unknown either way. */
+export type BeforeRequest = (request: {
+    key: string;
+    label: string;
+    executionPath?: string;
+    model: string;
+    /** The turn this request would be, counting from 1; `maxTurns` is the node's limit. */
+    turn: number;
+    maxTurns: number | null;
+    /** The node's `budget_usd`, if it set one, and what its session has spent so far: a request whose cost is unknown at
+     *  the figure its host held for it (`holdUsd`), and null when one has no such figure. */
+    budgetUsd?: number;
+    spentUsd: number | null;
+    /** The most input tokens this request can be billed for (the body's UTF-8 bytes plus what the provider adds, as the
+     *  model proxy measured it), undefined when it was not measured: a budget treats that input as unknown, never 0. */
+    inputTokensMax?: number;
+    /** The most output tokens it asks for, and the least it may be limited to and still answer, as the model proxy read
+     *  them from its body (ModelRequest). */
+    outputTokensAsked?: number;
+    outputTokensLeast?: number;
+    /** This session's paid requests admitted and not yet answered (in this process), oldest first, each with its own
+     *  `inputTokensMax` and the output limit it was admitted with (`outputTokensMax`): a budget holds each one's
+     *  worst case until it answers, since `spentUsd` counts answered requests only. Requests are admitted one at a time,
+     *  so each check sees every request admitted before it. */
+    inFlight: readonly InFlight[];
+}) => void | {
+    refuse: string;
+} | Admission | Promise<void | {
+    refuse: string;
+} | Admission>;
+/** A request admitted and not yet answered, as a budget holds it. */
+export type InFlight = {
+    turn: number;
+    model: string;
+    inputTokensMax?: number;
+    outputTokensMax?: number;
+};
+/** A host's admission: what it holds for the request (`holdUsd`), and the most output tokens, thinking included, it may
+ *  be sent with (`outputTokensMax`, what is left of a cap can buy), which its ticket carries to the model proxy. A
+ *  request its client stops part way (`ModelUsage.stoppedAfterBytes`), its cost unknown, counts at `stoppedUsd` of what
+ *  streamed, in tokens (one a byte), never more than `holdUsd`; without it, at `holdUsd`. */
+export type Admission = {
+    holdUsd?: number;
+    outputTokensMax?: number;
+    stoppedUsd?: (streamedTokens: number) => number;
+};
+export interface HarnessRunnerOptions {
+    /** The run's store, through whoever owns it. */
+    store: SessionStore;
+    /** The tools a node may name. A node that names none gets all of them; `tools: []` gets none. */
+    tools?: HostTool[];
+    /** The most turns (paid model requests) a node gets per attempt (default 8; null for no limit). A node's own
+     *  `max_turns` applies within it; one that asks for more is refused, final. */
+    maxTurns?: number | null;
+    /** The most turns sent to a node per attempt when its turn limit is null (default 100). With a limit, sends are
+     *  bounded by it instead. */
+    maxSends?: number;
+    /** The most `submit` calls a node gets per attempt (default 5; null for no limit). */
+    maxSubmissions?: number | null;
+    /** Each call's limit in milliseconds (default 120 s; null for none). */
+    timeoutMs?: number | null;
+    signal?: AbortSignal;
+    /** The host's check before each paid request: its budget, `max_cost_usd`. */
+    beforeRequest?: BeforeRequest;
+    /** Every event, with the node it belongs to. */
+    onEvent?: (event: HarnessEvent) => void;
+    /** The private directory of a session, when the adapter needs one. */
+    sessionDir?: (key: string) => string;
+}
+/** Turns in a row that may end with no paid request and no accepted submission before a node ends `no_progress`. The
+ *  turn limit counts paid requests only, so without this bound a harness whose turns never reach its model (a cached or
+ *  refused answer, a misconfigured model) would be sent turns forever, on microtasks no timer can interrupt. */
+export declare const NO_PROGRESS_TURNS = 3;
+/** What a paid request tells a host, beside its session's key and label. */
+export type ModelPortEvent = {
+    type: "request_start";
+    turn: number;
+    model: string;
+} | {
+    type: "request_end";
+    turn: number;
+    usage: ModelUsage;
+};
+export interface ModelPortOptions {
+    /** The session's key: what `beforeRequest` and every event carry. */
+    key: string;
+    label?: string;
+    executionPath?: string;
+    /** The most paid requests (turns) the session may make in this attempt; null (the default) for no limit. */
+    maxTurns?: number | null;
+    budgetUsd?: number;
+    /** Asked before every paid request; a `refuse` ends the attempt. */
+    beforeRequest?: BeforeRequest;
+    onEvent?: (event: ModelPortEvent & {
+        key: string;
+        label: string;
+        executionPath?: string;
+    }) => void;
+    /** The session's records, as already read (default: read from the writer). */
+    records?: readonly SessionRecord[];
+    /** How a record is written (default: the writer's append, which a newer open fences). */
+    append?: (records: SessionRecord[]) => Promise<void>;
+    /** The attempt has stopped: the error a new paid request is refused with. */
+    stopped?: () => Error | undefined;
+    /** A pause is draining the attempt: the error a new paid request is refused with, while the attempt itself goes on. A
+     *  request is refused if the pause began before its record is written, even while the host's check of it was running. */
+    draining?: () => Error | undefined;
+    /** The port ends the attempt (the turn limit, the host's refusal, a cost it could not record): the error it throws. */
+    stop?: (reason: "turn_limit" | "refused" | "model_error", message?: string) => Error;
+}
+/** A session's booking of paid model requests: the adapter's model port, and what it has counted. */
+export interface ModelBooking {
+    /** The port the adapter's session reports every paid request to (`SessionIO.models`). */
+    readonly models: ModelPort;
+    /** Paid requests that left in this session, one a crash cut off included. */
+    turns(): number;
+    /** What they cost; null once one's price is unknown. */
+    spentUsd(): number | null;
+    /** Books, once, each paid request a crash cut off (a `runner.request` with no `runner.turn`): a `runner.turn` marked
+     *  `cut` at an unknown price, and a `request_end` saying so. A booked request is answered, so this is idempotent.
+     *  Call it before the session sends anything. */
+    bookCut(): Promise<void>;
+}
+/** The runner's booking of paid model requests, for a host that drives an adapter session itself (a chat run): the same
+ *  records (`runner.request` before a request leaves, `runner.turn` with its cost when it answers), the same turn limit
+ *  and `beforeRequest`, the same events. `createHarnessRunner` is built on it. */
+export declare function modelPortFor(writer: SessionWriter, options: ModelPortOptions): Promise<ModelBooking>;
+export declare function createHarnessRunner(adapter: AgentAdapter, options: HarnessRunnerOptions): HarnessRunner;