@namzu/sdk 2.0.0 → 3.0.0

package/dist/runtime/query/run-state.d.ts

@@ -0,0 +1,52 @@
+import type { RunPersistence } from '../../manager/run/persistence.js';
+import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js';
+import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js';
+import { type RunState } from '../../types/run/state.js';
+import type { ThreadId } from '../../types/session/ids.js';
+/**
+ * A {@link CheckpointRunScope} plus the one attribution field checkpoints
+ * do not record.
+ *
+ * `threadId` is denormalized onto a run at `query()` time and never written
+ * into a checkpoint, so a snapshot rebuilt from the store alone cannot
+ * derive it. Requiring the caller to supply it is better than inventing one
+ * or widening `RunState` to make it optional: the field is required by
+ * `query()` on the way back in, so an absent value would only fail later
+ * and less clearly.
+ */
+export interface RunStateScope extends CheckpointRunScope {
+    threadId: ThreadId;
+}
+/**
+ * Build a JSON-safe snapshot of a live run.
+ *
+ * Every field is copied, not referenced: the caller is about to serialize
+ * this, and a snapshot that aliased the run's own message array would keep
+ * mutating after it was taken.
+ */
+export declare function captureRunState(runMgr: RunPersistence, scope: RunStateScope, extra?: {
+    elapsedMs?: number;
+    checkpoint?: IterationCheckpoint | null;
+}): RunState;
+/**
+ * Rebuild a run's snapshot from durable state alone, with no live run
+ * object — the read a DIFFERENT process performs.
+ *
+ * With no `checkpointId` this prefers the run's outstanding park over its
+ * newest checkpoint, because "what is this run waiting on" is the question
+ * a resuming process is actually asking; it falls back to the newest
+ * checkpoint when nothing is parked.
+ *
+ * Returns `null` when the run has no checkpoints. That is the honest
+ * answer: a run that never checkpointed left nothing to resume from, and
+ * synthesizing a snapshot from an empty store would produce a run that
+ * restarts from zero while claiming to be a continuation.
+ *
+ * `status`/`stopReason` are absent from a checkpoint by construction — a
+ * checkpoint is written mid-flight — so a rebuilt snapshot always reports
+ * `running`, and the host's own record remains the authority on a run that
+ * already finished. Read `pending` to tell a parked run from a live one:
+ * it is outstanding when set with no `resolvedAt`.
+ */
+export declare function loadRunState(store: CheckpointStore, scope: RunStateScope, checkpointId?: CheckpointId): Promise<RunState | null>;
+//# sourceMappingURL=run-state.d.ts.map

package/dist/runtime/query/run-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/run-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAClF,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AAC9F,OAAO,EAAqB,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AAG1D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAc,SAAQ,kBAAkB;IACxD,QAAQ,EAAE,QAAQ,CAAA;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,aAAa,EACpB,KAAK,CAAC,EAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;CACvC,GACC,QAAQ,CA2BV;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CACjC,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,aAAa,EACpB,YAAY,CAAC,EAAE,YAAY,GACzB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA0B1B"}

package/dist/runtime/query/run-state.js

@@ -0,0 +1,87 @@
+import { RUN_STATE_VERSION } from '../../types/run/state.js';
+import { findPendingCheckpoint } from './checkpoint.js';
+/**
+ * Build a JSON-safe snapshot of a live run.
+ *
+ * Every field is copied, not referenced: the caller is about to serialize
+ * this, and a snapshot that aliased the run's own message array would keep
+ * mutating after it was taken.
+ */
+export function captureRunState(runMgr, scope, extra) {
+    const session = runMgr.getSession();
+    const startedAt = session.startedAt;
+    return {
+        version: RUN_STATE_VERSION,
+        runId: runMgr.id,
+        sessionId: scope.sessionId,
+        threadId: scope.threadId,
+        projectId: scope.projectId,
+        tenantId: scope.tenantId,
+        ...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+        ...(session.metadata?.agentId ? { agentId: session.metadata.agentId } : {}),
+        ...(session.metadata?.agentName ? { agentName: session.metadata.agentName } : {}),
+        status: runMgr.status,
+        ...(runMgr.stopReason ? { stopReason: runMgr.stopReason } : {}),
+        ...(session.lastError ? { lastError: session.lastError } : {}),
+        messages: structuredClone(runMgr.messages),
+        tokenUsage: { ...runMgr.tokenUsage },
+        costInfo: { ...runMgr.costInfo },
+        currentIteration: runMgr.currentIteration,
+        startedAt,
+        elapsedMs: extra?.elapsedMs ?? Date.now() - startedAt,
+        ...(extra?.checkpoint ? { checkpointId: extra.checkpoint.id } : {}),
+        ...(extra?.checkpoint?.pending ? { pending: extra.checkpoint.pending } : {}),
+        capturedAt: Date.now(),
+    };
+}
+/**
+ * Rebuild a run's snapshot from durable state alone, with no live run
+ * object — the read a DIFFERENT process performs.
+ *
+ * With no `checkpointId` this prefers the run's outstanding park over its
+ * newest checkpoint, because "what is this run waiting on" is the question
+ * a resuming process is actually asking; it falls back to the newest
+ * checkpoint when nothing is parked.
+ *
+ * Returns `null` when the run has no checkpoints. That is the honest
+ * answer: a run that never checkpointed left nothing to resume from, and
+ * synthesizing a snapshot from an empty store would produce a run that
+ * restarts from zero while claiming to be a continuation.
+ *
+ * `status`/`stopReason` are absent from a checkpoint by construction — a
+ * checkpoint is written mid-flight — so a rebuilt snapshot always reports
+ * `running`, and the host's own record remains the authority on a run that
+ * already finished. Read `pending` to tell a parked run from a live one:
+ * it is outstanding when set with no `resolvedAt`.
+ */
+export async function loadRunState(store, scope, checkpointId) {
+    const checkpoint = checkpointId
+        ? await store.readCheckpoint(scope, checkpointId)
+        : ((await findPendingCheckpoint(store, scope)) ?? (await newest(store, scope)));
+    if (!checkpoint)
+        return null;
+    return {
+        version: RUN_STATE_VERSION,
+        runId: checkpoint.runId,
+        sessionId: scope.sessionId,
+        threadId: scope.threadId,
+        projectId: scope.projectId,
+        tenantId: scope.tenantId,
+        ...(scope.parentRunId ? { parentRunId: scope.parentRunId } : {}),
+        status: 'running',
+        messages: checkpoint.messages,
+        tokenUsage: checkpoint.tokenUsage,
+        costInfo: checkpoint.costInfo,
+        currentIteration: checkpoint.guardState.iterationCount,
+        startedAt: checkpoint.createdAt - checkpoint.guardState.elapsedMs,
+        elapsedMs: checkpoint.guardState.elapsedMs,
+        checkpointId: checkpoint.id,
+        ...(checkpoint.pending ? { pending: checkpoint.pending } : {}),
+        capturedAt: Date.now(),
+    };
+}
+async function newest(store, scope) {
+    const all = await store.listCheckpoints(scope);
+    return all.length > 0 ? (all[all.length - 1] ?? null) : null;
+}
+//# sourceMappingURL=run-state.js.map

package/dist/runtime/query/run-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-state.js","sourceRoot":"","sources":["../../../src/runtime/query/run-state.ts"],"names":[],"mappings":"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"}

package/dist/runtime/query/tool-grants.d.ts

@@ -0,0 +1,44 @@
+import type { ToolCallSummary } from '../../types/hitl/index.js';
+/**
+ * The keys under which a tool call can be granted.
+ *
+ * Ordered widest-last, so a grant list read by a human says what it covers.
+ * A call is pre-approved if ANY of its keys has been granted, which is what
+ * lets one mechanism express both "this exact invocation" and "this tool,
+ * whatever the arguments".
+ */
+export interface ToolGrantKeys {
+    /** This exact invocation: the tool and these arguments. */
+    readonly call: string;
+    /** The tool, whatever the arguments. */
+    readonly tool: string;
+}
+/**
+ * Derive both grant keys for a call.
+ *
+ * The arguments are serialized with sorted keys, so two calls that differ
+ * only in property order produce the same key. Without that, a grant for
+ * `{path, mode}` would not cover `{mode, path}` and the same approval would
+ * be asked for twice — which reads to the approver as the mechanism not
+ * working, and teaches them to grant the wide key instead.
+ */
+export declare function toolGrantKeys(call: Pick<ToolCallSummary, 'name' | 'input'>): ToolGrantKeys;
+/**
+ * Grants recorded during one run.
+ *
+ * Run-scoped, not persisted: an approval is a statement about this run's
+ * work, and carrying it into a later run would be reuse nobody agreed to.
+ * The durable half is the checkpointed decision, which is evidence of what
+ * was approved, not a standing permission.
+ */
+export declare class ToolGrantSet {
+    private readonly granted;
+    /** Record keys from an explicit approval. Ignores empty input. */
+    grant(keys: readonly string[] | undefined): void;
+    /** Whether this call is already covered by a recorded grant. */
+    covers(call: Pick<ToolCallSummary, 'name' | 'input'>): boolean;
+    get size(): number;
+    /** The recorded keys, for a host rendering what it has already granted. */
+    list(): string[];
+}
+//# sourceMappingURL=tool-grants.d.ts.map

package/dist/runtime/query/tool-grants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-grants.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/tool-grants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAEhE;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,aAAa,CAK1F;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAE5C,kEAAkE;IAClE,KAAK,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI;IAMhD,gEAAgE;IAChE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,OAAO;IAK9D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,2EAA2E;IAC3E,IAAI,IAAI,MAAM,EAAE;CAGhB"}

package/dist/runtime/query/tool-grants.js

@@ -0,0 +1,63 @@
+/**
+ * Derive both grant keys for a call.
+ *
+ * The arguments are serialized with sorted keys, so two calls that differ
+ * only in property order produce the same key. Without that, a grant for
+ * `{path, mode}` would not cover `{mode, path}` and the same approval would
+ * be asked for twice — which reads to the approver as the mechanism not
+ * working, and teaches them to grant the wide key instead.
+ */
+export function toolGrantKeys(call) {
+    return {
+        call: `${call.name}:${stableStringify(call.input)}`,
+        tool: call.name,
+    };
+}
+/**
+ * Grants recorded during one run.
+ *
+ * Run-scoped, not persisted: an approval is a statement about this run's
+ * work, and carrying it into a later run would be reuse nobody agreed to.
+ * The durable half is the checkpointed decision, which is evidence of what
+ * was approved, not a standing permission.
+ */
+export class ToolGrantSet {
+    granted = new Set();
+    /** Record keys from an explicit approval. Ignores empty input. */
+    grant(keys) {
+        for (const key of keys ?? []) {
+            if (key.length > 0)
+                this.granted.add(key);
+        }
+    }
+    /** Whether this call is already covered by a recorded grant. */
+    covers(call) {
+        const keys = toolGrantKeys(call);
+        return this.granted.has(keys.call) || this.granted.has(keys.tool);
+    }
+    get size() {
+        return this.granted.size;
+    }
+    /** The recorded keys, for a host rendering what it has already granted. */
+    list() {
+        return [...this.granted];
+    }
+}
+/**
+ * `JSON.stringify` with object keys sorted at every depth.
+ *
+ * Arrays keep their order, which is meaningful; object key order is not,
+ * and letting it into the key would make the same call hash two ways.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+    return `{${entries.join(',')}}`;
+}
+//# sourceMappingURL=tool-grants.js.map

package/dist/runtime/query/tool-grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-grants.js","sourceRoot":"","sources":["../../../src/runtime/query/tool-grants.ts"],"names":[],"mappings":"AAiBA;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,IAA6C;IAC1E,OAAO;QACN,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;QACnD,IAAI,EAAE,IAAI,CAAC,IAAI;KACf,CAAA;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACP,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IAE5C,kEAAkE;IAClE,KAAK,CAAC,IAAmC;QACxC,KAAK,MAAM,GAAG,IAAI,IAAI,IAAI,EAAE,EAAE,CAAC;YAC9B,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;gBAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC1C,CAAC;IACF,CAAC;IAED,gEAAgE;IAChE,MAAM,CAAC,IAA6C;QACnD,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClE,CAAC;IAED,IAAI,IAAI;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IACzB,CAAC;IAED,2EAA2E;IAC3E,IAAI;QACH,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAA;IACzB,CAAC;CACD;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACtC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAA;IACvF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;IAE5E,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SAC9D,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC;SAClC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAC/D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAA;AAChC,CAAC"}

package/dist/runtime/query/tool-output-budget.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Model-visible size cap for a single tool result.
+ *
+ * ~40k characters is roughly 10k tokens: large enough that ordinary reads,
+ * greps and command output pass through untouched, small enough that one
+ * oversized result cannot consume a fifth of a 200k window.
+ *
+ * Nothing capped tool output before this. `read` returned a whole file when
+ * `limit` was omitted, `bash` allowed a 100 MB buffer, and the MCP adapter
+ * joined every text block uncapped — so a 2 MB lockfile became ~500k tokens
+ * in a single `tool_result` and the run died on a provider error with
+ * everything lost.
+ */
+export declare const DEFAULT_MAX_TOOL_OUTPUT_CHARS = 40000;
+/**
+ * Opening of the line that points at a spilled output.
+ *
+ * A constant rather than a phrase repeated in two files, because the line
+ * has to survive later editing: compaction clears stale tool results, and
+ * clearing a spilled one destroys the only route back to the content this
+ * budget deliberately kept. Whatever clears a result has to be able to
+ * recognise this line and keep it.
+ */
+export declare const SPILL_MARKER = "The full output was written to:";
+export interface ToolOutputBudgetResult {
+    /** What the model sees. */
+    readonly output: string;
+    /** Size before any reduction, for telemetry. */
+    readonly originalLength: number;
+    readonly truncated: boolean;
+    /** Where the full output was written, when it was. */
+    readonly spillPath?: string;
+}
+/**
+ * Name what a truncated result took with it.
+ *
+ * Returns `undefined` when there was nothing but text to lose, so the
+ * ordinary case adds no noise.
+ *
+ * The model is the reader here, and it is reasoning about a result it can
+ * no longer fully see. "An image was returned and is not shown" is a fact
+ * it can act on — ask for a smaller region, re-run against a file — where
+ * silence looks exactly like a tool that only ever returns text.
+ */
+export declare function describeDroppedContent(content: readonly {
+    type?: string;
+}[] | unknown): string | undefined;
+/**
+ * Total size of the rich channel, in base64 characters.
+ *
+ * Measured on the payload rather than the block count, because one block
+ * is the whole cost: a single screenshot is the largest thing a tool
+ * result can carry.
+ */
+export declare function measureContentBytes(content: readonly unknown[] | unknown): number;
+export interface ApplyToolOutputBudgetOptions {
+    readonly toolName: string;
+    readonly toolUseId: string;
+    readonly output: string;
+    readonly maxChars: number;
+    /**
+     * Directory to spill overflow into. When absent the output is
+     * middle-elided instead — degraded, but never unbounded.
+     */
+    readonly spillDir?: string | undefined;
+    readonly onError?: (message: string) => void;
+}
+/**
+ * Bound a tool result to the model-visible budget.
+ *
+ * Spilling beats truncating on every axis that matters: nothing is lost,
+ * tokens are paid only if the agent decides the rest is worth re-reading,
+ * and retrieval uses `read`/`grep` — tools it already has — rather than a
+ * new affordance. A hosted agent runtime does the same thing above 100k
+ * characters. Middle-elision is the fallback for a run with no directory
+ * to write to.
+ *
+ * The preview keeps head AND tail because the two ends carry different
+ * information: the head has the schema/opening of a document, the tail has
+ * the error a command died on.
+ */
+export declare function applyToolOutputBudget(opts: ApplyToolOutputBudgetOptions): ToolOutputBudgetResult;
+//# sourceMappingURL=tool-output-budget.d.ts.map

package/dist/runtime/query/tool-output-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-output-budget.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/tool-output-budget.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAA;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,oCAAoC,CAAA;AAY7D,MAAM,WAAW,sBAAsB;IACtC,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gDAAgD;IAChD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,OAAO,GAC7C,MAAM,GAAG,SAAS,CAapB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,GAAG,MAAM,CAQjF;AAED,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,4BAA4B,GAAG,sBAAsB,CAyChG"}

package/dist/runtime/query/tool-output-budget.js

@@ -0,0 +1,147 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Model-visible size cap for a single tool result.
+ *
+ * ~40k characters is roughly 10k tokens: large enough that ordinary reads,
+ * greps and command output pass through untouched, small enough that one
+ * oversized result cannot consume a fifth of a 200k window.
+ *
+ * Nothing capped tool output before this. `read` returned a whole file when
+ * `limit` was omitted, `bash` allowed a 100 MB buffer, and the MCP adapter
+ * joined every text block uncapped — so a 2 MB lockfile became ~500k tokens
+ * in a single `tool_result` and the run died on a provider error with
+ * everything lost.
+ */
+export const DEFAULT_MAX_TOOL_OUTPUT_CHARS = 40_000;
+/**
+ * Opening of the line that points at a spilled output.
+ *
+ * A constant rather than a phrase repeated in two files, because the line
+ * has to survive later editing: compaction clears stale tool results, and
+ * clearing a spilled one destroys the only route back to the content this
+ * budget deliberately kept. Whatever clears a result has to be able to
+ * recognise this line and keep it.
+ */
+export const SPILL_MARKER = 'The full output was written to:';
+/**
+ * Share of the budget spent on the head. The rest goes to the tail.
+ *
+ * Weighted toward the head because that is where a document's structure
+ * lives, but never all of it: the tail is where a command's error message
+ * is, and a preview that drops it is useless for the most common reason a
+ * result is being read at all.
+ */
+const HEAD_SHARE = 0.75;
+/**
+ * Name what a truncated result took with it.
+ *
+ * Returns `undefined` when there was nothing but text to lose, so the
+ * ordinary case adds no noise.
+ *
+ * The model is the reader here, and it is reasoning about a result it can
+ * no longer fully see. "An image was returned and is not shown" is a fact
+ * it can act on — ask for a smaller region, re-run against a file — where
+ * silence looks exactly like a tool that only ever returns text.
+ */
+export function describeDroppedContent(content) {
+    if (!Array.isArray(content))
+        return undefined;
+    const counts = new Map();
+    for (const block of content) {
+        const kind = typeof block?.type === 'string' ? block.type : 'content';
+        if (kind === 'text')
+            continue;
+        counts.set(kind, (counts.get(kind) ?? 0) + 1);
+    }
+    if (counts.size === 0)
+        return undefined;
+    const parts = [...counts].map(([kind, n]) => (n === 1 ? `1 ${kind}` : `${n} ${kind} blocks`));
+    return `[${parts.join(', ')} omitted: this result was truncated, and the preview above no longer describes them.]`;
+}
+/**
+ * Total size of the rich channel, in base64 characters.
+ *
+ * Measured on the payload rather than the block count, because one block
+ * is the whole cost: a single screenshot is the largest thing a tool
+ * result can carry.
+ */
+export function measureContentBytes(content) {
+    if (!Array.isArray(content))
+        return 0;
+    let total = 0;
+    for (const block of content) {
+        if (typeof block?.data === 'string')
+            total += block.data.length;
+        else if (typeof block?.text === 'string')
+            total += block.text.length;
+    }
+    return total;
+}
+/**
+ * Bound a tool result to the model-visible budget.
+ *
+ * Spilling beats truncating on every axis that matters: nothing is lost,
+ * tokens are paid only if the agent decides the rest is worth re-reading,
+ * and retrieval uses `read`/`grep` — tools it already has — rather than a
+ * new affordance. A hosted agent runtime does the same thing above 100k
+ * characters. Middle-elision is the fallback for a run with no directory
+ * to write to.
+ *
+ * The preview keeps head AND tail because the two ends carry different
+ * information: the head has the schema/opening of a document, the tail has
+ * the error a command died on.
+ */
+export function applyToolOutputBudget(opts) {
+    const { output, maxChars } = opts;
+    const originalLength = output.length;
+    if (!Number.isFinite(maxChars) || maxChars <= 0 || originalLength <= maxChars) {
+        return { output, originalLength, truncated: false };
+    }
+    // Both slices are derived from `maxChars` so the preview honours the
+    // budget it is enforcing. `slice(-0)` returns the WHOLE string, so the
+    // zero-tail case must be branched, not computed.
+    const headChars = Math.max(1, Math.floor(maxChars * HEAD_SHARE));
+    const tailChars = Math.max(0, maxChars - headChars);
+    const head = output.slice(0, headChars);
+    const tail = tailChars > 0 ? output.slice(-tailChars) : '';
+    const omitted = originalLength - head.length - tail.length;
+    const spillPath = opts.spillDir
+        ? spill(opts.spillDir, opts.toolUseId, output, opts.onError)
+        : undefined;
+    const recovery = spillPath
+        ? [
+            `${SPILL_MARKER} ${spillPath}`,
+            'Read a specific window with `read` (offset/limit) or search it with `grep`. Do NOT read it whole — that is what exceeded the budget.',
+        ].join('\n')
+        : 'The full output was not retained. Re-run with a narrower query, a line range, or a filter.';
+    return {
+        output: [
+            head,
+            '',
+            `[... ${omitted.toLocaleString()} characters omitted — "${opts.toolName}" returned ${originalLength.toLocaleString()} characters, over the ${maxChars.toLocaleString()}-character budget ...]`,
+            recovery,
+            '',
+            tail,
+        ].join('\n'),
+        originalLength,
+        truncated: true,
+        ...(spillPath ? { spillPath } : {}),
+    };
+}
+function spill(dir, toolUseId, content, onError) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        // The tool_use id is already unique per call and safe as a filename.
+        const path = join(dir, `${toolUseId}.txt`);
+        writeFileSync(path, content, 'utf-8');
+        return path;
+    }
+    catch (err) {
+        // A spill failure must never fail the tool call — the model still
+        // gets the preview, just without a path to recover the rest.
+        onError?.(err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+}
+//# sourceMappingURL=tool-output-budget.js.map

package/dist/runtime/query/tool-output-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-output-budget.js","sourceRoot":"","sources":["../../../src/runtime/query/tool-output-budget.ts"],"names":[],"mappings":"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"}

package/dist/runtime/query/tool-pause.d.ts

@@ -0,0 +1,41 @@
+import type { ResumeHandler } from '../../types/hitl/index.js';
+import type { RunId } from '../../types/ids/index.js';
+import type { RequestToolPause } from '../../types/tool/index.js';
+import type { PendingAnswers, QuestionParkRecorder } from './question-park.js';
+/**
+ * The durable pause, made reachable from any tool.
+ *
+ * The machinery was excellent and reachable from exactly four
+ * kernel-owned points: the plan gate, the tool-review gate, the iteration
+ * cadence, and one built-in question tool. A host-authored tool — the
+ * spend, the outbound post, the destructive migration, the operations
+ * that most want their OWN confirmation with their OWN wording — had no
+ * seam to it. The only route was to hand-thread a recorder and a resume
+ * callback into a private tool builder, mirroring what the coordinator
+ * does, and nothing in the type a tool author is handed suggested that
+ * was possible.
+ *
+ * This is that same machinery behind a function on `ToolContext`. Nothing
+ * new is invented: the park is a real checkpoint, the answer routes back
+ * on resume, and a pause is inert outside a run that supports one.
+ */
+/**
+ * Identity of one pause.
+ *
+ * `<toolUseId>:<name>` rather than the tool-use id alone, because the id
+ * identifies the CALL and a call may pause more than once — "which
+ * environment" then "are you sure". Keying on the call would make the
+ * second answer arrive against the first question. The name is the tool
+ * author's, so a resume payload can name what it is answering.
+ */
+export declare const pauseId: (toolUseId: string, name: string) => string;
+interface ToolPauseDeps {
+    readonly runId: RunId;
+    readonly toolUseId: string;
+    readonly parkHandler: ResumeHandler;
+    readonly recorder?: QuestionParkRecorder;
+    readonly pendingAnswers?: PendingAnswers;
+}
+export declare function createToolPause(deps: ToolPauseDeps): RequestToolPause;
+export {};
+//# sourceMappingURL=tool-pause.d.ts.map

package/dist/runtime/query/tool-pause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-pause.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/tool-pause.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAsB,aAAa,EAAoB,MAAM,2BAA2B,CAAA;AACpG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,2BAA2B,CAAA;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE9E;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,WAAW,MAAM,EAAE,MAAM,MAAM,KAAG,MAAgC,CAAA;AAE1F,UAAU,aAAa;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAA;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;CACxC;AA0BD,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,gBAAgB,CAoDrE"}

package/dist/runtime/query/tool-pause.js

@@ -0,0 +1,94 @@
+/**
+ * The durable pause, made reachable from any tool.
+ *
+ * The machinery was excellent and reachable from exactly four
+ * kernel-owned points: the plan gate, the tool-review gate, the iteration
+ * cadence, and one built-in question tool. A host-authored tool — the
+ * spend, the outbound post, the destructive migration, the operations
+ * that most want their OWN confirmation with their OWN wording — had no
+ * seam to it. The only route was to hand-thread a recorder and a resume
+ * callback into a private tool builder, mirroring what the coordinator
+ * does, and nothing in the type a tool author is handed suggested that
+ * was possible.
+ *
+ * This is that same machinery behind a function on `ToolContext`. Nothing
+ * new is invented: the park is a real checkpoint, the answer routes back
+ * on resume, and a pause is inert outside a run that supports one.
+ */
+/**
+ * Identity of one pause.
+ *
+ * `<toolUseId>:<name>` rather than the tool-use id alone, because the id
+ * identifies the CALL and a call may pause more than once — "which
+ * environment" then "are you sure". Keying on the call would make the
+ * second answer arrive against the first question. The name is the tool
+ * author's, so a resume payload can name what it is answering.
+ */
+export const pauseId = (toolUseId, name) => `${toolUseId}:${name}`;
+function toQuestion(request, id) {
+    return {
+        questionId: id,
+        question: request.prompt,
+        ...(request.header !== undefined ? { header: request.header } : {}),
+        options: (request.options ?? []).map((option) => ({
+            id: option.id,
+            label: option.label,
+            ...(option.description !== undefined ? { description: option.description } : {}),
+        })),
+        multiSelect: request.multiSelect ?? false,
+        allowFreeText: request.allowFreeText ?? true,
+    };
+}
+/**
+ * An unanswered pause is NOT consent.
+ *
+ * The same rule the built-in question tool follows, and for the same
+ * reason: a tool that pauses to ask "may I charge this card" and reads
+ * silence as yes is worse than one that never asked.
+ */
+const unanswered = (reason) => ({ status: 'unanswered', reason });
+export function createToolPause(deps) {
+    return async (request) => {
+        const id = pauseId(deps.toolUseId, request.name);
+        // An answer carried in from a resumed run, checked BEFORE parking.
+        // Re-entering the tool is how the answer gets delivered — the batch
+        // re-executes — so without this the resume would ask a human
+        // something they already answered, or headlessly discard it.
+        const carried = deps.pendingAnswers?.take(id);
+        const question = toQuestion(request, id);
+        const parkedAt = carried === undefined && deps.recorder ? await deps.recorder.record(question) : null;
+        const decision = carried ??
+            (await deps.parkHandler({
+                type: 'user_question',
+                runId: deps.runId,
+                checkpointId: parkedAt ?? `cp_pause_${id}`,
+                question,
+            }));
+        if (parkedAt !== null && deps.recorder) {
+            await deps.recorder.resolve(parkedAt, decision);
+        }
+        if (decision.action === 'abort')
+            return { status: 'aborted' };
+        if (decision.action !== 'answer_question') {
+            return unanswered('the pause was resolved without an answer');
+        }
+        if (decision.questionId !== undefined && decision.questionId !== id) {
+            // Misdirection guard. Host queues are keyed by run, so a stale
+            // client can answer pause N after pause N+1 opened under the same
+            // run. Answering the wrong question is worse than not answering.
+            return unanswered('the answer was addressed to a different pause');
+        }
+        const known = new Set((request.options ?? []).map((option) => option.id));
+        const selectedOptionIds = decision.selectedOptionIds.filter((selected) => known.has(selected));
+        const freeText = decision.freeText;
+        if (selectedOptionIds.length === 0 && (freeText === undefined || freeText.length === 0)) {
+            return unanswered('the answer selected nothing and said nothing');
+        }
+        return {
+            status: 'answered',
+            selectedOptionIds,
+            ...(freeText !== undefined && freeText.length > 0 ? { text: freeText } : {}),
+        };
+    };
+}
+//# sourceMappingURL=tool-pause.js.map