@namzu/sdk 1.4.0 → 3.0.0

package/dist/types/run/state.d.ts

@@ -0,0 +1,85 @@
+import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js';
+import type { CheckpointId, PendingDecision } from '../hitl/index.js';
+import type { RunId, SessionId, TenantId } from '../ids/index.js';
+import type { Message } from '../message/index.js';
+import type { ProjectId, ThreadId } from '../session/ids.js';
+import type { StopReason } from './stop-reason.js';
+/**
+ * Everything needed to pick a run back up in a DIFFERENT process.
+ *
+ * A run's live state was spread across objects that only exist in memory —
+ * `RunPersistence`, `GuardCoordinator`, the suspended `await` inside a HITL
+ * gate. `IterationCheckpoint` carries the history and the budgets, but it
+ * is keyed by a store scope the reader has to already know, and it says
+ * nothing about the run's status or why it stopped. So "resume this run"
+ * meant "the original process is still alive and holding it".
+ *
+ * That is the constraint this removes. `RunState` is a flat, JSON-safe
+ * snapshot: a serverless handler writes one when a run parks, returns, and
+ * a later invocation — a different container — reads it back and continues.
+ *
+ * It is a SNAPSHOT, not a live handle. Nothing in it points at a socket, a
+ * sandbox, a provider client, or an open file. Re-establishing those is the
+ * host's job on the way back in, which is exactly why they are absent.
+ */
+export interface RunState {
+    /**
+     * Schema version. Bumped when the shape changes incompatibly, so a
+     * host that stored a snapshot with an older SDK gets a clear failure
+     * from {@link parseRunState} instead of a partial restore.
+     */
+    readonly version: 1;
+    readonly runId: RunId;
+    readonly sessionId: SessionId;
+    readonly threadId: ThreadId;
+    readonly projectId: ProjectId;
+    readonly tenantId: TenantId;
+    /** Present for sub-runs, so a hierarchical store can key the snapshot. */
+    readonly parentRunId?: RunId;
+    readonly agentId?: string;
+    readonly agentName?: string;
+    readonly status: AgentStatus;
+    readonly stopReason?: StopReason;
+    readonly lastError?: string;
+    readonly messages: Message[];
+    readonly tokenUsage: TokenUsage;
+    readonly costInfo: CostInfo;
+    readonly currentIteration: number;
+    readonly startedAt: number;
+    /**
+     * Wall-clock the run has already consumed. Restored into the guard so a
+     * resumed run does not get a fresh timeout budget — the timeout is a
+     * property of the RUN, not of the process hosting it.
+     */
+    readonly elapsedMs: number;
+    /**
+     * The checkpoint this snapshot corresponds to, when one was written.
+     * Pass it as `resumeFromCheckpoint`.
+     */
+    readonly checkpointId?: CheckpointId;
+    /**
+     * The decision the run is parked on, if any. A host reads this to know
+     * what to ask a human, and feeds the answer back as
+     * `QueryParams.pendingDecision`.
+     */
+    readonly pending?: PendingDecision;
+    readonly capturedAt: number;
+}
+/** Thrown by {@link parseRunState} when a snapshot cannot be trusted. */
+export declare class RunStateVersionError extends Error {
+    readonly found: unknown;
+    readonly expected: number;
+    constructor(found: unknown, expected: number);
+}
+export declare const RUN_STATE_VERSION: 1;
+/**
+ * Parse a serialized snapshot, refusing anything this SDK cannot fully
+ * restore.
+ *
+ * The version guard is the point. A snapshot is written by one deployment
+ * and read by another, possibly weeks later and possibly after an SDK
+ * upgrade; a silent partial restore there produces a run that looks healthy
+ * and has lost its budgets. Failing loudly is the only honest option.
+ */
+export declare function parseRunState(json: string | unknown): RunState;
+//# sourceMappingURL=state.d.ts.map

package/dist/types/run/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/types/run/state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,QAAQ;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IAEnB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAA;IAE5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAE3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAE3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAE1B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAA;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAA;IAElC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B;AAED,yEAAyE;AACzE,qBAAa,oBAAqB,SAAQ,KAAK;IAE7C,QAAQ,CAAC,KAAK,EAAE,OAAO;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM;gBADhB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM;CAO1B;AAED,eAAO,MAAM,iBAAiB,EAAG,CAAU,CAAA;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAU9D"}

package/dist/types/run/state.js

@@ -0,0 +1,33 @@
+/** Thrown by {@link parseRunState} when a snapshot cannot be trusted. */
+export class RunStateVersionError extends Error {
+    found;
+    expected;
+    constructor(found, expected) {
+        super(`RunState version mismatch: snapshot declares ${JSON.stringify(found)}, this SDK reads ${expected}. Restoring across an incompatible version would silently drop fields; re-run instead.`);
+        this.found = found;
+        this.expected = expected;
+        this.name = 'RunStateVersionError';
+    }
+}
+export const RUN_STATE_VERSION = 1;
+/**
+ * Parse a serialized snapshot, refusing anything this SDK cannot fully
+ * restore.
+ *
+ * The version guard is the point. A snapshot is written by one deployment
+ * and read by another, possibly weeks later and possibly after an SDK
+ * upgrade; a silent partial restore there produces a run that looks healthy
+ * and has lost its budgets. Failing loudly is the only honest option.
+ */
+export function parseRunState(json) {
+    const raw = typeof json === 'string' ? JSON.parse(json) : json;
+    if (typeof raw !== 'object' || raw === null) {
+        throw new RunStateVersionError(raw, RUN_STATE_VERSION);
+    }
+    const version = raw.version;
+    if (version !== RUN_STATE_VERSION) {
+        throw new RunStateVersionError(version, RUN_STATE_VERSION);
+    }
+    return raw;
+}
+//# sourceMappingURL=state.js.map

package/dist/types/run/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/types/run/state.ts"],"names":[],"mappings":"AA4EA,yEAAyE;AACzE,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAEpC;IACA;IAFV,YACU,KAAc,EACd,QAAgB;QAEzB,KAAK,CACJ,gDAAgD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,oBAAoB,QAAQ,wFAAwF,CACzL,CAAA;QALQ,UAAK,GAAL,KAAK,CAAS;QACd,aAAQ,GAAR,QAAQ,CAAQ;QAKzB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACnC,CAAC;CACD;AAED,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAU,CAAA;AAE3C;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,IAAsB;IACnD,MAAM,GAAG,GAAY,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IACvE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC7C,MAAM,IAAI,oBAAoB,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAA;IACvD,CAAC;IACD,MAAM,OAAO,GAAI,GAA6B,CAAC,OAAO,CAAA;IACtD,IAAI,OAAO,KAAK,iBAAiB,EAAE,CAAC;QACnC,MAAM,IAAI,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAA;IAC3D,CAAC;IACD,OAAO,GAAe,CAAA;AACvB,CAAC"}

package/dist/types/run/step.d.ts

@@ -0,0 +1,77 @@
+import type { CostInfo, TokenUsage } from '../common/index.js';
+import type { MessageId } from '../ids/index.js';
+import type { ToolCall } from '../message/index.js';
+/**
+ * What one iteration of the agent loop did.
+ *
+ * None of this was reachable before. `Run` and `BaseAgentResult` have no
+ * `steps[]`, so a host that persisted the returned `Run` — the natural
+ * thing — permanently lost per-step attribution: answering "which step
+ * cost the most" meant correlating raw `RunEvent`s by iteration number and
+ * diffing cumulative counters, and per-tool duration was never emitted at
+ * all. Every field here was already computed somewhere in the loop.
+ */
+export interface StepResult {
+    /** 1-based, matching `iteration` on the run events. */
+    stepNumber: number;
+    model: string;
+    messageId: MessageId;
+    /** Assistant text for this step, if any. */
+    content: string | null;
+    toolCalls: readonly ToolCall[];
+    /** Tool outcomes, in the same order as `toolCalls`. */
+    toolResults: readonly StepToolResult[];
+    finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter';
+    /** Usage for THIS step, not the run's cumulative total. */
+    usage: TokenUsage;
+    /** Cost delta attributable to this step. Zero without a pricing table. */
+    costDelta: CostInfo;
+    startedAt: number;
+    /** Wall-clock for the whole step, including tool execution. */
+    durationMs: number;
+    /** Portion of `durationMs` spent inside tools. */
+    toolExecutionMs: number;
+}
+export interface StepToolResult {
+    toolCallId: string;
+    toolName: string;
+    /** Text form, after the model-visible output budget was applied. */
+    output: string;
+    isError: boolean;
+    durationMs: number;
+}
+/**
+ * A programmable halt condition, evaluated after each step's tools have
+ * run.
+ *
+ * `GuardCoordinator` — the only halt before this — consumes
+ * `{aborted, totalTokens, totalCost, currentIteration, startTime}` and
+ * never sees messages, tool calls or results. So "stop after three steps
+ * with no progress" and "stop once the plan is complete" were
+ * inexpressible, and a terminal `submit_answer` tool could not end the
+ * run: the model had to be prompt-begged to stop, with `maxIterations:
+ * 200` as the only backstop.
+ *
+ * Returning `true` ends the run with `stop_reason: 'stop_condition'`.
+ */
+export type StopCondition = (state: StopConditionState) => boolean | Promise<boolean>;
+export interface StopConditionState {
+    /** Every step so far, most recent last. */
+    readonly steps: readonly StepResult[];
+    readonly latestStep: StepResult;
+    readonly totalUsage: TokenUsage;
+    readonly totalCost: CostInfo;
+}
+/** Stop once `n` steps have completed. */
+export declare function stepCountIs(n: number): StopCondition;
+/**
+ * Stop when the latest step called any of `names`.
+ *
+ * The tool still executes and its result is still recorded — the run ends
+ * after, not instead. That is what makes a `submit_answer` / `verify` tool
+ * usable as a terminator without losing its output.
+ */
+export declare function hasToolCall(...names: string[]): StopCondition;
+/** Stop when any of the given conditions does. */
+export declare function anyOf(...conditions: StopCondition[]): StopCondition;
+//# sourceMappingURL=step.d.ts.map

package/dist/types/run/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../../src/types/run/step.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAEnD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IAC1B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,SAAS,CAAA;IACpB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAA;IAC9B,uDAAuD;IACvD,WAAW,EAAE,SAAS,cAAc,EAAE,CAAA;IACtC,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAA;IACjE,2DAA2D;IAC3D,KAAK,EAAE,UAAU,CAAA;IACjB,0EAA0E;IAC1E,SAAS,EAAE,QAAQ,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,eAAe,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAErF,MAAM,WAAW,kBAAkB;IAClC,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAA;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAA;CAC5B;AAED,0CAA0C;AAC1C,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,CAEpD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,CAG7D;AAED,kDAAkD;AAClD,wBAAgB,KAAK,CAAC,GAAG,UAAU,EAAE,aAAa,EAAE,GAAG,aAAa,CAOnE"}

package/dist/types/run/step.js

@@ -0,0 +1,26 @@
+/** Stop once `n` steps have completed. */
+export function stepCountIs(n) {
+    return ({ steps }) => steps.length >= n;
+}
+/**
+ * Stop when the latest step called any of `names`.
+ *
+ * The tool still executes and its result is still recorded — the run ends
+ * after, not instead. That is what makes a `submit_answer` / `verify` tool
+ * usable as a terminator without losing its output.
+ */
+export function hasToolCall(...names) {
+    const wanted = new Set(names);
+    return ({ latestStep }) => latestStep.toolCalls.some((tc) => wanted.has(tc.function.name));
+}
+/** Stop when any of the given conditions does. */
+export function anyOf(...conditions) {
+    return async (state) => {
+        for (const condition of conditions) {
+            if (await condition(state))
+                return true;
+        }
+        return false;
+    };
+}
+//# sourceMappingURL=step.js.map

package/dist/types/run/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../../src/types/run/step.ts"],"names":[],"mappings":"AAqEA,0CAA0C;AAC1C,MAAM,UAAU,WAAW,CAAC,CAAS;IACpC,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAG,KAAe;IAC7C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAA;IAC7B,OAAO,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,KAAK,CAAC,GAAG,UAA2B;IACnD,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACtB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACpC,IAAI,MAAM,SAAS,CAAC,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAA;QACxC,CAAC;QACD,OAAO,KAAK,CAAA;IACb,CAAC,CAAA;AACF,CAAC"}

package/dist/types/run/stop-reason.d.ts

@@ -1,11 +1,39 @@
-export type StopReason = 'end_turn' | 'token_budget' | 'cost_limit' | 'timeout' | 'max_iterations' | 'cancelled' | 'plan_rejected' | 'paused' | 'error';
+export type StopReason = 'end_turn' | 'token_budget' | 'cost_limit' | 'timeout' | 'max_iterations' | 'cancelled' | 'plan_rejected'
+/** A caller-supplied `stopWhen` predicate returned true. */
+ | 'stop_condition'
+/** The model never produced a valid structured output within its retries. */
+ | 'structured_output_failed'
+/**
+ * A host reviewer kept rejecting the answer and the run ran out of
+ * attempts.
+ *
+ * Distinct from a budget stop on purpose: without it the run would end
+ * on `max_iterations` or a token cap, naming the resource it exhausted
+ * rather than the judgement that exhausted it — and the reader would go
+ * looking for a loop instead of at the reviewer.
+ */
+ | 'answer_rejected'
+/** An input guardrail refused the run before it started. */
+ | 'input_guardrail'
+/** An output guardrail refused the produced result. */
+ | 'output_guardrail' | 'paused' | 'error';
 /**
  * Per-LLM-message stop reason — distinct from the run-level {@link StopReason}.
  *
- * Mirrors the union of Anthropic and OpenAI finish reasons normalised into a
+ * The union of the finish reasons providers report, normalised into a
  * provider-agnostic vocabulary. `forced_finalize` is a Namzu-specific value
  * emitted by the orchestrator when iteration limits force a final response
  * without a model-issued stop reason.
  */
-export type MessageStopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'pause_turn' | 'refusal' | 'forced_finalize';
+export type MessageStopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence' | 'pause_turn' | 'refusal' | 'forced_finalize'
+/**
+ * The turn was cancelled mid-stream.
+ *
+ * Also Namzu-specific, and added because the cancel path had no way to
+ * close the message it had opened: it re-threw from inside the chunk
+ * loop, so the terminal event never fired and a host consuming the
+ * message lifecycle saw a message begin and never end. A turn that
+ * stops is still a turn that finished streaming, whatever stopped it.
+ */
+ | 'cancelled';
 //# sourceMappingURL=stop-reason.d.ts.map

package/dist/types/run/stop-reason.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stop-reason.d.ts","sourceRoot":"","sources":["../../../src/types/run/stop-reason.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GACnB,UAAU,GACV,cAAc,GACd,YAAY,GACZ,SAAS,GACT,gBAAgB,GAChB,WAAW,GACX,eAAe,GACf,QAAQ,GACR,OAAO,CAAA;AAEV;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAC1B,UAAU,GACV,UAAU,GACV,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,SAAS,GACT,iBAAiB,CAAA"}
+{"version":3,"file":"stop-reason.d.ts","sourceRoot":"","sources":["../../../src/types/run/stop-reason.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GACnB,UAAU,GACV,cAAc,GACd,YAAY,GACZ,SAAS,GACT,gBAAgB,GAChB,WAAW,GACX,eAAe;AACjB,4DAA4D;GAC1D,gBAAgB;AAClB,6EAA6E;GAC3E,0BAA0B;AAC5B;;;;;;;;GAQG;GACD,iBAAiB;AACnB,4DAA4D;GAC1D,iBAAiB;AACnB,uDAAuD;GACrD,kBAAkB,GAClB,QAAQ,GACR,OAAO,CAAA;AAEV;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAC1B,UAAU,GACV,UAAU,GACV,YAAY,GACZ,eAAe,GACf,YAAY,GACZ,SAAS,GACT,iBAAiB;AACnB;;;;;;;;GAQG;GACD,WAAW,CAAA"}

package/dist/types/sandbox/index.d.ts

@@ -3,6 +3,25 @@ import type { SandboxId } from '../ids/index.js';
 export type SandboxStatus = 'creating' | 'ready' | 'busy' | 'destroyed';
 export declare function assertSandboxStatus(status: SandboxStatus): void;
 export type SandboxEnvironment = 'linux-namespace' | 'macos-seatbelt' | 'basic';
+/**
+ * A security control a sandbox tier either provides or does not.
+ *
+ * The environment name alone does not say what a caller actually gets:
+ * one tier denies the network outright while another leaves the host
+ * filesystem fully visible, and both used to answer to the same provider
+ * name. A caller that turned isolation on for a reason needs to state
+ * which control it is relying on, so a host that cannot supply it can
+ * refuse instead of quietly handing back less.
+ *
+ *  - `filesystem` — the spawned process cannot read or write outside the
+ *    sandbox root.
+ *  - `network` — the spawned process cannot reach the network.
+ *  - `process` — the spawned process cannot see or signal host processes.
+ */
+export type SandboxIsolationControl = 'filesystem' | 'network' | 'process';
+export declare const SANDBOX_ISOLATION_CONTROLS: readonly SandboxIsolationControl[];
+/** What a tier actually enforces, per control. */
+export type SandboxIsolationReport = Readonly<Record<SandboxIsolationControl, boolean>>;
 export declare function assertSandboxEnvironment(env: SandboxEnvironment): void;
 export interface SandboxExecResult {
     readonly exitCode: number;
@@ -11,11 +30,31 @@ export interface SandboxExecResult {
     readonly signal?: string;
     readonly timedOut: boolean;
     readonly durationMs: number;
+    /**
+     * Set when the backend clipped the stream at its output cap.
+     *
+     * The firecracker protocol already computed these, but they had no slot
+     * in this contract, so they were dropped at the type boundary and the
+     * model saw a complete-looking result that had silently lost its tail —
+     * against the kernel's own convention that it does not truncate
+     * silently.
+     */
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
 }
 export interface SandboxExecOptions {
     readonly timeout?: number;
     readonly env?: Record<string, string>;
     readonly cwd?: string;
+    /**
+     * Cancellation for the command. A backend that honours it kills the
+     * process; one that does not simply ignores it, so this is additive.
+     *
+     * Without it a Stop (or a per-tool deadline) could only ever abandon
+     * the *wait* — the sandboxed process kept running after the host
+     * believed the run had been cancelled.
+     */
+    readonly signal?: AbortSignal;
 }
 /**
  * One regular file inside the sandbox filesystem. Backends return
@@ -26,12 +65,42 @@ export interface SandboxFileEntry {
     readonly path: string;
     readonly size: number;
 }
+/**
+ * A network policy applied to a LIVE sandbox.
+ *
+ * The whole point is that it can change mid-life. The common shape —
+ * "fetch the repository with a token, then drop to deny-all before running
+ * anything the repository contains" — was not expressible at all: the
+ * policy was frozen at provider construction, so a host had to build a
+ * second provider and a second sandbox, copying the work across.
+ */
+export interface SandboxNetworkPolicy {
+    /**
+     * Hosts the sandbox may reach. Empty denies everything.
+     *
+     * `api.example.com` matches that host; `.example.com` matches the
+     * domain and its subdomains. Substring matching is deliberately not
+     * offered — `example.com` as a substring would admit
+     * `example.com.attacker.net`.
+     */
+    readonly allowedHosts: readonly string[];
+}
 export interface Sandbox {
     readonly id: SandboxId;
     readonly status: SandboxStatus;
     readonly rootDir: string;
     readonly environment: SandboxEnvironment;
     exec(command: string, args?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>;
+    /**
+     * Narrow or widen what this sandbox can reach, while it is running.
+     *
+     * Optional, and a backend that cannot enforce it must **throw** rather
+     * than accept and ignore. A network policy that is accepted and not
+     * applied is worse than one that was never offered: the caller stops
+     * looking, and the run proceeds believing it is confined. That is the
+     * same rule the tiered sandbox provider follows, for the same reason.
+     */
+    setNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
     writeFile(path: string, content: string | Buffer): Promise<void>;
     readFile(path: string): Promise<Buffer>;
     /**
@@ -117,9 +186,9 @@ export interface ContainerSandboxLayoutMount {
     readonly containerPath?: string;
 }
 /**
- * Declarative multi-mount taxonomy for a CONTAINER sandbox. Mirrors
- * the layout Anthropic's container architecture exposes to the model
- * (Claude container blueprint, Code Interpreter, "skills"):
+ * Declarative multi-mount taxonomy for a CONTAINER sandbox. A container
+ * needs one place the user will see and several the user will not, and
+ * the difference has to be legible to the model from the path alone:
  *
  *  - `outputs` — RW bind. User-visible output surface that the
  *    user consumes after the run. Default container path
@@ -162,7 +231,7 @@ export interface ContainerSandboxLayout {
      * not a child of it: the output collector / output watcher
      * scans `outputs` only, so anything the agent writes under
      * `scratch` is invisible to the user by construction. Mirrors the
-     * Anthropic Cowork pattern (`/home/claude` as scratch vs.
+     * separation between scratch space (invisible to the collector) and
      * `/mnt/user-data/outputs` as the user-visible output area).
      * Hosts that don't need a separate scratch mount may omit this.
      */
@@ -222,7 +291,7 @@ export interface SandboxCreateConfig {
  * Putting layout on `SandboxCreateConfig` would let the SDK runtime
  * (`drainQuery`) call `provider.create()` without it and trigger a
  * runtime validation failure that the type system cannot catch — a
- * trap Codex flagged in the second review round. Hosts spawning a
+ * trap flagged in the second review round. Hosts spawning a
  * sandbox per task construct one provider per task too; the same
  * closure that knows the per-task `hostPath`s is the one that calls
  * `createSandboxProvider`.
@@ -239,21 +308,28 @@ export declare const SandboxConfigSchema: z.ZodObject<{
     timeoutMs: z.ZodDefault<z.ZodNumber>;
     memoryLimitMb: z.ZodDefault<z.ZodNumber>;
     maxProcesses: z.ZodDefault<z.ZodNumber>;
-    cleanupOnDestroy: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Controls the run depends on. Provider construction throws when the
+     * host cannot enforce one of them. Empty by default, which keeps
+     * best-effort behaviour for callers that never asked for a guarantee —
+     * but a caller that did ask now gets it or gets an error, never a
+     * quiet downgrade.
+     */
+    requireIsolation: z.ZodDefault<z.ZodArray<z.ZodEnum<["filesystem", "network", "process"]>, "many">>;
 }, "strip", z.ZodTypeAny, {
     enabled: boolean;
     provider: "local";
     timeoutMs: number;
     memoryLimitMb: number;
     maxProcesses: number;
-    cleanupOnDestroy: boolean;
+    requireIsolation: ("filesystem" | "network" | "process")[];
 }, {
     enabled?: boolean | undefined;
     provider?: "local" | undefined;
     timeoutMs?: number | undefined;
     memoryLimitMb?: number | undefined;
     maxProcesses?: number | undefined;
-    cleanupOnDestroy?: boolean | undefined;
+    requireIsolation?: ("filesystem" | "network" | "process")[] | undefined;
 }>;
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
 //# sourceMappingURL=index.d.ts.map

package/dist/types/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"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"}

package/dist/types/sandbox/index.js

@@ -13,6 +13,11 @@ export function assertSandboxStatus(status) {
         }
     }
 }
+export const SANDBOX_ISOLATION_CONTROLS = [
+    'filesystem',
+    'network',
+    'process',
+];
 export function assertSandboxEnvironment(env) {
     switch (env) {
         case 'linux-namespace':
@@ -34,6 +39,13 @@ export const SandboxConfigSchema = z.object({
     timeoutMs: z.number().positive().default(SANDBOX_DEFAULT_TIMEOUT_MS),
     memoryLimitMb: z.number().positive().default(SANDBOX_DEFAULT_MEMORY_LIMIT_MB),
     maxProcesses: z.number().positive().default(SANDBOX_DEFAULT_MAX_PROCESSES),
-    cleanupOnDestroy: z.boolean().default(true),
+    /**
+     * Controls the run depends on. Provider construction throws when the
+     * host cannot enforce one of them. Empty by default, which keeps
+     * best-effort behaviour for callers that never asked for a guarantee —
+     * but a caller that did ask now gets it or gets an error, never a
+     * quiet downgrade.
+     */
+    requireIsolation: z.array(z.enum(['filesystem', 'network', 'process'])).default([]),
 });
 //# sourceMappingURL=index.js.map

package/dist/types/sandbox/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACN,6BAA6B,EAC7B,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAA;AASzC,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACxD,QAAQ,MAAM,EAAE,CAAC;QAChB,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,WAAW;YACf,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,MAAM,CAAA;YACjC,MAAM,IAAI,KAAK,CAAC,0BAA0B,WAAW,EAAE,CAAC,CAAA;QACzD,CAAC;IACF,CAAC;AACF,CAAC;AAQD,MAAM,UAAU,wBAAwB,CAAC,GAAuB;IAC/D,QAAQ,GAAG,EAAE,CAAC;QACb,KAAK,iBAAiB,CAAC;QACvB,KAAK,gBAAgB,CAAC;QACtB,KAAK,OAAO;YACX,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,GAAG,CAAA;YAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,WAAW,EAAE,CAAC,CAAA;QAC9D,CAAC;IACF,CAAC;AACF,CAAC;AA0RD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC;IACpE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC;IAC7E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,6BAA6B,CAAC;IAC1E,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;CAC3C,CAAC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EACN,6BAA6B,EAC7B,+BAA+B,EAC/B,0BAA0B,GAC1B,MAAM,kCAAkC,CAAA;AASzC,MAAM,UAAU,mBAAmB,CAAC,MAAqB;IACxD,QAAQ,MAAM,EAAE,CAAC;QAChB,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,WAAW;YACf,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,MAAM,CAAA;YACjC,MAAM,IAAI,KAAK,CAAC,0BAA0B,WAAW,EAAE,CAAC,CAAA;QACzD,CAAC;IACF,CAAC;AACF,CAAC;AAyBD,MAAM,CAAC,MAAM,0BAA0B,GAAuC;IAC7E,YAAY;IACZ,SAAS;IACT,SAAS;CACT,CAAA;AAKD,MAAM,UAAU,wBAAwB,CAAC,GAAuB;IAC/D,QAAQ,GAAG,EAAE,CAAC;QACb,KAAK,iBAAiB,CAAC;QACvB,KAAK,gBAAgB,CAAC;QACtB,KAAK,OAAO;YACX,OAAM;QACP,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,GAAG,CAAA;YAC9B,MAAM,IAAI,KAAK,CAAC,+BAA+B,WAAW,EAAE,CAAC,CAAA;QAC9D,CAAC;IACF,CAAC;AACF,CAAC;AA8UD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC;IACpE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC;IAC7E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,6BAA6B,CAAC;IAC1E;;;;;;OAMG;IACH,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACnF,CAAC,CAAA"}

package/dist/types/structured-output/index.d.ts

@@ -12,12 +12,13 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
      */
     schema: TSchema;
     /**
-     * Whether to force the model to use the structured_output tool.
-     * When true, sets tool_choice to force the tool.
-     * When false, the model may choose to call it or not.
-     * Default: true
+     * Turns spent re-prompting when the model answers in prose or fails
+     * validation. Defaults to {@link DEFAULT_STRUCTURED_OUTPUT_RETRIES}.
+     *
+     * Bounded so a model that cannot satisfy the schema fails loudly rather
+     * than iterating against `maxIterations`.
      */
-    enforceToolChoice?: boolean;
+    maxRetries?: number;
 }
 /**
  * Result from structured output tool execution.

package/dist/types/structured-output/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/structured-output/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAC5E;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAA;IAEf;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,GAAG,OAAO;IAClD;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,CAAA;IAER;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/structured-output/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,OAAO,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAC5E;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAA;IAEf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,CAAC,GAAG,OAAO;IAClD;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,CAAA;IAER;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB"}

package/dist/types/thread/entity.d.ts

@@ -42,9 +42,8 @@ export type ThreadStatus = 'open' | 'archived';
  * - **Sessions are the immediate work unit.** A user or agent enters a
  *   Thread and opens/resumes Sessions for the concrete interval of work.
  *
- * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). Industry
- * frameworks (OpenAI Responses, LangGraph, Claude Agent SDK, Temporal) do
- * not have an exact analogue for the Thread layer — it is Namzu's answer to
+ * This is the mental model ses_001 ratified (Phase 0, 2026-04-18). The
+ * Thread layer has no counterpart elsewhere — it is Namzu's answer to
  * the question "how do you expose a multi-session topic to A2A without
  * coupling it to the Project's filesystem identity?".
  *

package/dist/types/thread/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/types/thread/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,QAAQ,CAAA;IACZ,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/types/thread/entity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,QAAQ,CAAA;IACZ,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,YAAY,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,SAAS,EAAE,IAAI,CAAA;IACf,SAAS,EAAE,IAAI,CAAA;CACf"}