@namzu/sdk 2.0.0 → 3.1.0

package/dist/types/errors/catalog.js

@@ -0,0 +1,148 @@
+import { ProviderError } from '../provider/errors.js';
+import { isNamzuError } from './index.js';
+/**
+ * A hint attached at the throw site.
+ *
+ * Infrastructure code knows things the classifier cannot infer — that a
+ * daemon is not running, that a socket path is wrong — and had no channel
+ * to say so except by baking prose into the message, where it cannot be
+ * separated from the failure again. An own-property survives every
+ * `instanceof` check and every rethrow, and rules can pass it through
+ * under a stable id.
+ */
+export function readHint(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const hint = err.hint;
+    return typeof hint === 'string' && hint.length > 0 ? hint : undefined;
+}
+/** Attach a hint to a throwable without changing its message or type. */
+export function withHint(err, hint) {
+    if (typeof err === 'object' && err !== null) {
+        Object.defineProperty(err, 'hint', { value: hint, enumerable: false, configurable: true });
+    }
+    return err;
+}
+/** Flatten a throwable into the shape rules match on. */
+export function factsOf(err) {
+    const hint = readHint(err);
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof ProviderError) {
+        return {
+            code: err.code,
+            message,
+            name: err.name,
+            ...(err.status !== undefined ? { status: err.status } : {}),
+            ...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+            ...(hint !== undefined ? { hint } : {}),
+        };
+    }
+    if (isNamzuError(err)) {
+        const status = err.details?.status;
+        return {
+            code: err.code,
+            message,
+            name: err.name,
+            ...(typeof status === 'number' ? { status } : {}),
+            ...(hint !== undefined ? { hint } : {}),
+        };
+    }
+    return {
+        message,
+        ...(err instanceof Error ? { name: err.name } : {}),
+        ...(hint !== undefined ? { hint } : {}),
+    };
+}
+/**
+ * The seed rules.
+ *
+ * Ordered, first match wins — so a rule may be as specific as it likes
+ * without having to exclude everything below it. Three to start, chosen
+ * because they are the failures an operator hits first and the ones where
+ * the vendor's own words help least.
+ */
+export const DEFAULT_ERROR_RULES = [
+    {
+        id: 'hint.from_throw_site',
+        // Highest precedence on purpose: code that raised the failure knows
+        // more about it than a rule matching on a status code ever will.
+        when: (facts) => facts.hint !== undefined,
+        message: '',
+        hint: '',
+    },
+    {
+        // Before the generic auth rule: the codes collapse 401 and 403 into
+        // one, but the two call for different actions and the status still
+        // separates them when the provider sent it.
+        id: 'provider.permission',
+        when: (facts) => facts.status === 403,
+        message: 'The credentials are valid but not permitted to use this model.',
+        hint: 'The key authenticated, so this is an entitlement rather than a secret problem: check the model name and whether the account has access to it.',
+    },
+    {
+        id: 'provider.auth',
+        when: (facts) => facts.code === 'auth' || facts.status === 401,
+        message: 'The provider rejected the credentials for this run.',
+        hint: 'Check that the API key is set, is not expired, and belongs to the account the model is billed to. Retrying will not help until it changes.',
+    },
+    {
+        id: 'provider.rate_limit',
+        when: (facts) => facts.code === 'rate_limit' || facts.status === 429,
+        message: 'The provider is rate limiting this run.',
+        hint: 'Automatic retries with backoff have already been exhausted. Lower concurrency, or wait for the quota window to reset before resuming.',
+    },
+    {
+        id: 'provider.context_overflow',
+        when: (facts) => facts.code === 'context_length_exceeded',
+        message: 'The prompt is larger than the model can accept.',
+        hint: 'Compaction ran and could not make enough room. Lower `compactionConfig.triggerThreshold`, reduce `keepRecentMessages`, or cap large tool outputs so history stops growing faster than it can be shed.',
+    },
+    {
+        id: 'provider.unavailable',
+        when: (facts) => facts.code === 'server_error' ||
+            facts.code === 'overloaded' ||
+            (facts.status !== undefined && facts.status >= 500),
+        message: 'The provider is failing on its own side.',
+        hint: 'Nothing in the run is wrong. Resume from the last checkpoint once the provider recovers.',
+    },
+    {
+        id: 'provider.network',
+        when: (facts) => facts.code === 'network' || facts.code === 'timeout',
+        message: 'The provider could not be reached.',
+        hint: 'Check network reachability and any proxy or firewall between this host and the provider endpoint, then resume from the last checkpoint.',
+    },
+    {
+        id: 'provider.model_not_found',
+        when: (facts) => facts.code === 'not_found' || facts.status === 404,
+        message: 'The provider does not recognise the model or endpoint requested.',
+        hint: "Check `runConfig.model` against the provider's current model list — a model id that was valid can be retired, and a deployment-scoped provider needs the deployment name rather than the base model name.",
+    },
+    {
+        id: 'provider.content_filter',
+        when: (facts) => facts.code === 'content_filter',
+        message: 'The provider refused the request on safety grounds.',
+        hint: "This is the provider's policy decision, not a namzu one, and resending the same prompt cannot change it. The refusal usually names the category it triggered.",
+    },
+];
+/**
+ * Explain a failure, or return `null` when no rule claims it.
+ *
+ * `null` rather than a generic fallback: inventing advice for a failure
+ * nobody has characterised is worse than saying nothing, because it sends
+ * the reader somewhere specific and wrong.
+ */
+export function explainError(err, rules = DEFAULT_ERROR_RULES) {
+    const facts = factsOf(err);
+    for (const rule of rules) {
+        if (!rule.when(facts))
+            continue;
+        // The throw-site rule carries no copy of its own — it exists to give
+        // a hint written at the raise point precedence over a generic one.
+        if (rule.id === 'hint.from_throw_site') {
+            return { id: rule.id, message: facts.message, hint: facts.hint ?? '' };
+        }
+        return { id: rule.id, message: rule.message, hint: rule.hint };
+    }
+    return null;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/types/errors/catalog.js.map

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

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

@@ -0,0 +1,73 @@
+import type { PlatformError } from '../common/index.js';
+/**
+ * What went wrong, at the granularity a HOST actually branches on.
+ *
+ * `PlatformError` was declared and never constructed — a shape nothing
+ * produced and nothing consumed. Meanwhile the runtime threw bare `Error`
+ * everywhere, so a caller catching a failure from `query()` could not tell
+ * "the model rate-limited us" from "the run was configured wrong" from
+ * "that checkpoint does not exist". The only recourse was matching on
+ * message text, which is not an interface.
+ *
+ * The union stays small on purpose: each member exists because a caller
+ * does something DIFFERENT about it. `provider_error` carries the finer
+ * {@link ProviderErrorCode} in `details` rather than being fanned out
+ * here, because that taxonomy answers the runtime's questions, not a
+ * host's.
+ */
+export type NamzuErrorCode = 
+/** The run was set up wrong — missing model, contradictory options. Retrying cannot help. */
+'invalid_config'
+/** The upstream model call failed. `details.providerCode` narrows it. */
+ | 'provider_error'
+/** A tool could not be executed or resolved. */
+ | 'tool_error'
+/** A referenced checkpoint, run or emergency dump does not exist. */
+ | 'not_found'
+/** A plugin hook failed or refused. */
+ | 'plugin_error'
+/** The provider or environment cannot do what the run requires. */
+ | 'capability_unavailable'
+/** Persistence (checkpoint store, run store, workspace) failed. */
+ | 'storage_error'
+/** Unclassified. Treated as non-retryable. */
+ | 'unknown';
+export interface NamzuErrorInit {
+    readonly code: NamzuErrorCode;
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+    /** Defaults per code; pass explicitly to override. */
+    readonly retryable?: boolean;
+    readonly cause?: unknown;
+}
+/**
+ * A runtime failure a host can branch on.
+ *
+ * Implements {@link PlatformError} so the declared shape finally has a
+ * producer, and extends `Error` so it still behaves like one everywhere
+ * that only knows about `Error` — stack, `instanceof`, `cause`.
+ */
+export declare class NamzuError extends Error implements PlatformError {
+    readonly code: NamzuErrorCode;
+    readonly details: Record<string, unknown> | undefined;
+    readonly retryable: boolean;
+    constructor(init: NamzuErrorInit);
+}
+export declare function isNamzuError(err: unknown): err is NamzuError;
+/**
+ * Normalize ANYTHING thrown into the declared shape.
+ *
+ * This is what makes `PlatformError` worth having: a host wraps one call
+ * and gets a consistent `{ code, message, details, retryable }` no matter
+ * what came out — a `NamzuError`, a `ProviderError`, a plain `Error` from
+ * a dependency, or a thrown string. Without it, "handle errors from the
+ * SDK" means writing the same defensive `instanceof` ladder in every
+ * caller.
+ *
+ * A `ProviderError` keeps its classification: its code lands in
+ * `details.providerCode` and its `retryable` verdict is preserved rather
+ * than recomputed, because that verdict already encodes what the provider
+ * taxonomy knows and this one does not.
+ */
+export declare function toPlatformError(err: unknown): PlatformError;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAGvD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,cAAc;AACzB,6FAA6F;AAC3F,gBAAgB;AAClB,yEAAyE;GACvE,gBAAgB;AAClB,gDAAgD;GAC9C,YAAY;AACd,qEAAqE;GACnE,WAAW;AACb,uCAAuC;GACrC,cAAc;AAChB,mEAAmE;GACjE,wBAAwB;AAC1B,mEAAmE;GACjE,eAAe;AACjB,8CAA8C;GAC5C,SAAS,CAAA;AAEZ,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACxB;AAKD;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,KAAM,YAAW,aAAa;IAC7D,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACrD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;gBAEf,IAAI,EAAE,cAAc;CAOhC;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU,CAE5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA+B3D"}

package/dist/types/errors/index.js

@@ -0,0 +1,70 @@
+import { ProviderError } from '../provider/errors.js';
+/** Codes for which the same operation may succeed if repeated. */
+const RETRYABLE = new Set(['storage_error']);
+/**
+ * A runtime failure a host can branch on.
+ *
+ * Implements {@link PlatformError} so the declared shape finally has a
+ * producer, and extends `Error` so it still behaves like one everywhere
+ * that only knows about `Error` — stack, `instanceof`, `cause`.
+ */
+export class NamzuError extends Error {
+    code;
+    details;
+    retryable;
+    constructor(init) {
+        super(init.message, init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = 'NamzuError';
+        this.code = init.code;
+        this.details = init.details;
+        this.retryable = init.retryable ?? RETRYABLE.has(init.code);
+    }
+}
+export function isNamzuError(err) {
+    return err instanceof NamzuError;
+}
+/**
+ * Normalize ANYTHING thrown into the declared shape.
+ *
+ * This is what makes `PlatformError` worth having: a host wraps one call
+ * and gets a consistent `{ code, message, details, retryable }` no matter
+ * what came out — a `NamzuError`, a `ProviderError`, a plain `Error` from
+ * a dependency, or a thrown string. Without it, "handle errors from the
+ * SDK" means writing the same defensive `instanceof` ladder in every
+ * caller.
+ *
+ * A `ProviderError` keeps its classification: its code lands in
+ * `details.providerCode` and its `retryable` verdict is preserved rather
+ * than recomputed, because that verdict already encodes what the provider
+ * taxonomy knows and this one does not.
+ */
+export function toPlatformError(err) {
+    if (isNamzuError(err)) {
+        return {
+            code: err.code,
+            message: err.message,
+            ...(err.details ? { details: err.details } : {}),
+            retryable: err.retryable,
+        };
+    }
+    if (err instanceof ProviderError) {
+        return {
+            code: 'provider_error',
+            message: err.message,
+            details: {
+                providerCode: err.code,
+                ...(err.providerId !== undefined ? { providerId: err.providerId } : {}),
+                ...(err.status !== undefined ? { status: err.status } : {}),
+                ...(err.retryAfterMs !== undefined ? { retryAfterMs: err.retryAfterMs } : {}),
+            },
+            retryable: err.retryable,
+        };
+    }
+    if (err instanceof Error) {
+        return { code: 'unknown', message: err.message, retryable: false };
+    }
+    // A thrown non-Error is rare and usually a bug elsewhere, but losing it
+    // entirely is worse than reporting it as-is.
+    return { code: 'unknown', message: String(err), retryable: false };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/errors/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AA6CrD,kEAAkE;AAClE,MAAM,SAAS,GAAgC,IAAI,GAAG,CAAiB,CAAC,eAAe,CAAC,CAAC,CAAA;AAEzF;;;;;;GAMG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAC3B,IAAI,CAAgB;IACpB,OAAO,CAAqC;IAC5C,SAAS,CAAS;IAE3B,YAAY,IAAoB;QAC/B,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QACjF,IAAI,CAAC,IAAI,GAAG,YAAY,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;QACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC5D,CAAC;CACD;AAED,MAAM,UAAU,YAAY,CAAC,GAAY;IACxC,OAAO,GAAG,YAAY,UAAU,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC3C,IAAI,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;YACN,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChD,SAAS,EAAE,GAAG,CAAC,SAAS;SACxB,CAAA;IACF,CAAC;IAED,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;QAClC,OAAO;YACN,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,OAAO,EAAE;gBACR,YAAY,EAAE,GAAG,CAAC,IAAI;gBACtB,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvE,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3D,GAAG,CAAC,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7E;YACD,SAAS,EAAE,GAAG,CAAC,SAAS;SACxB,CAAA;IACF,CAAC;IAED,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;IACnE,CAAC;IAED,wEAAwE;IACxE,6CAA6C;IAC7C,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAA;AACnE,CAAC"}

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

@@ -0,0 +1,57 @@
+import type { RunId } from '../ids/index.js';
+import type { Message } from '../message/index.js';
+/**
+ * Guardrails inspect what goes INTO a run and what comes OUT of it.
+ *
+ * namzu had three good gates on tool calls — probe veto, `VerificationGate`,
+ * HITL review — and they all point the same way: they protect the world
+ * from the agent. Nothing protected the user from the agent's own output,
+ * and nothing looked at the prompt before the run started.
+ *
+ * The concrete failure: an agent reads a credential file, the read is
+ * allowed (it is a legitimate file), the secret enters context, and it is
+ * repeated in the final answer. Every existing gate is upstream of that
+ * and none of them fire.
+ */
+export interface InputGuardrailContext {
+    readonly runId: RunId;
+    /** The messages the run is about to start with. */
+    readonly messages: readonly Message[];
+    /** The assembled system prompt, when there is one. */
+    readonly systemPrompt?: string;
+}
+export interface OutputGuardrailContext {
+    readonly runId: RunId;
+    /** The run's final assistant text. */
+    readonly output: string;
+    /** Full message history, for a guardrail that needs the conversation. */
+    readonly messages: readonly Message[];
+}
+/**
+ * What a guardrail decided.
+ *
+ * `rewrite` matters as much as `tripwire`: a PII policy usually wants to
+ * redact an account number, not throw the whole answer away. A gate that
+ * can only abort forces every redaction use case to be implemented
+ * somewhere else.
+ */
+export type GuardrailVerdict = {
+    readonly action: 'pass';
+} | {
+    readonly action: 'block';
+    readonly reason: string;
+} | {
+    readonly action: 'rewrite';
+    readonly output: string;
+    readonly reason?: string;
+};
+export type InputGuardrail = (ctx: InputGuardrailContext) => GuardrailVerdict | Promise<GuardrailVerdict>;
+export type OutputGuardrail = (ctx: OutputGuardrailContext) => GuardrailVerdict | Promise<GuardrailVerdict>;
+/** Convenience: a named guardrail, so a block can say which rule tripped. */
+export interface NamedGuardrail<T> {
+    readonly name: string;
+    readonly check: T;
+}
+export type InputGuardrailSpec = InputGuardrail | NamedGuardrail<InputGuardrail>;
+export type OutputGuardrailSpec = OutputGuardrail | NamedGuardrail<OutputGuardrail>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/guardrail/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;IACrC,sDAAsD;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAA;CACrC;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpF,MAAM,MAAM,cAAc,GAAG,CAC5B,GAAG,EAAE,qBAAqB,KACtB,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAEjD,MAAM,MAAM,eAAe,GAAG,CAC7B,GAAG,EAAE,sBAAsB,KACvB,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAEjD,6EAA6E;AAC7E,MAAM,WAAW,cAAc,CAAC,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CACjB;AAED,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG,cAAc,CAAC,cAAc,CAAC,CAAA;AAChF,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,cAAc,CAAC,eAAe,CAAC,CAAA"}

package/dist/types/guardrail/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/guardrail/index.ts"],"names":[],"mappings":""}

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

@@ -1,3 +1,5 @@
+import type { WorkingStateSnapshot } from '../../compaction/wire.js';
+import type { SerializedSpanContext } from '../../telemetry/attributes.js';
 import type { CostInfo, TokenUsage } from '../common/index.js';
 import type { CheckpointId, PlanId, RunId } from '../ids/index.js';
 import type { Message } from '../message/index.js';
@@ -13,6 +15,24 @@ export type HITLResumeDecision = {
     feedback: string;
 } | {
     action: 'approve_tools';
+    /**
+     * Grant keys to remember, so calls covered by them are not asked
+     * about again for the rest of the run.
+     *
+     * Nothing is remembered unless this says so, and only an explicit
+     * approval can say it — a denial or a non-response leaves nothing
+     * behind. Non-reuse was deliberate ("consent is not
+     * transferable"); what changes is that the SCOPE becomes the
+     * approver's to choose rather than being fixed at "this one call"
+     * or, in the only escape available, "everything for the session".
+     *
+     * Keys come from {@link ToolGrantKeys}, so a grant can be as
+     * narrow as one exact invocation or as wide as a whole tool.
+     * `bash` is unconditionally non-read-only and in no allowlist, so
+     * `bash: git status` re-prompted on every batch forever and the
+     * only way out was a blanket grant that also covered `rm -rf`.
+     */
+    remember?: readonly string[];
 } | {
     action: 'modify_tools';
     modifications: ToolModification[];
@@ -114,18 +134,54 @@ export interface CheckpointSummary {
     costInfo: CostInfo;
     lastAssistantMessage?: string;
 }
-export interface ActiveNodeInfo {
-    agentId: string;
-    agentType: 'reactive' | 'pipeline' | 'router' | 'supervisor';
-    nodeRef?: string;
-    parentAgentId?: string;
-    depth: number;
-}
-export interface BranchStackEntry {
-    agentId: string;
-    decision: string;
-    confidence: number;
-    timestamp: number;
+/**
+ * A decision the run is parked on, recorded durably.
+ *
+ * Without this the park exists only as a suspended `await` inside one
+ * process: a checkpoint written at a tool-review gate looks identical to a
+ * checkpoint written mid-run, so nothing on disk says "a human owes this
+ * run an answer". Kill the process and the request is gone — the approval
+ * queue a host would build from durable state has nothing to read, and a
+ * resumed run silently re-asks the model instead of honoring the approval
+ * that was already granted.
+ *
+ * `request` is stored verbatim so a fresh process can render exactly what
+ * the human was shown, and apply the answer to exactly those tool calls.
+ */
+export interface PendingDecision {
+    /** The request the run parked on, as the `resumeHandler` received it. */
+    readonly request: HITLDecisionRequest;
+    /** Epoch ms at which the run parked. */
+    readonly parkedAt: number;
+    /**
+     * Epoch ms after which this park is no longer worth serving.
+     *
+     * Absolute, not a duration, so it survives the process that set it —
+     * every timer in the SDK is an in-process `setTimeout` and the
+     * park-record delay is deliberately `unref`'d, so nothing in-memory can
+     * outlive a redeploy. Without it a run parks for approval, the worker is
+     * replaced, nobody answers, and the checkpoint stays outstanding
+     * forever: every approval-queue reader keeps serving it and its
+     * workspace is never reclaimed.
+     *
+     * The run timeout cannot cover this. `checkLimitsDetailed` is only
+     * reached between iterations and a park suspends mid-iteration, so a
+     * long-lived process hard-stops the run immediately AFTER the human
+     * finally approves, while across a restart the restored elapsed time
+     * excludes parked time entirely — the same configuration giving two
+     * opposite outcomes.
+     *
+     * Absent means no deadline, which is today's behaviour.
+     */
+    readonly deadlineAt?: number;
+    /**
+     * Set once the decision arrives, so a resolved checkpoint stays
+     * distinguishable from one that was never parked. A checkpoint is
+     * outstanding when `pending` is set and `resolvedAt` is not.
+     */
+    readonly resolvedAt?: number;
+    /** The answer, when one arrived. Kept as evidence of who decided what. */
+    readonly decision?: HITLResumeDecision;
 }
 export interface IterationCheckpoint {
     id: CheckpointId;
@@ -135,14 +191,41 @@ export interface IterationCheckpoint {
     tokenUsage: TokenUsage;
     costInfo: CostInfo;
     planStatus?: PlanStatus;
+    /**
+     * Present when the run parked at this checkpoint awaiting a human.
+     * See {@link PendingDecision}.
+     */
+    pending?: PendingDecision;
     guardState: {
         iterationCount: number;
         elapsedMs: number;
     };
     createdAt: number;
     toolResultHashes?: Record<string, string>;
-    branchStack?: BranchStackEntry[];
-    activeNode?: ActiveNodeInfo;
+    /**
+     * Compaction's accumulated working state at the moment of the
+     * checkpoint.
+     *
+     * Absent on checkpoints written before this existed, and absent when
+     * compaction is disabled — in both cases the resumed run starts with an
+     * empty manager, which is exactly today's behaviour.
+     */
+    workingState?: WorkingStateSnapshot;
+    /**
+     * The trace this checkpoint was taken inside.
+     *
+     * A resumed run used to mint a fresh root span with a new trace id and
+     * no link to the one that crashed, so the failure and its recovery could
+     * not be reconstructed as one timeline. Every span carries the run id,
+     * which is enough to find both traces by query and not enough to see one
+     * waterfall — and even that goes away for a replay fork, which mints a
+     * new run id.
+     *
+     * Absent on checkpoints written before this existed, and on runs with no
+     * telemetry registered; in both cases the resumed run starts its own
+     * trace, which is exactly today's behaviour.
+     */
+    traceContext?: SerializedSpanContext;
 }
 export declare function autoApproveHandler(request: HITLDecisionRequest): Promise<HITLResumeDecision>;
 //# sourceMappingURL=index.d.ts.map

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AA8IA,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,eAAe;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;QACnD,KAAK,aAAa;YACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;QACpD,KAAK,sBAAsB;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;QAC/C,KAAK,eAAe;YACnB,2DAA2D;YAC3D,yDAAyD;YACzD,6DAA6D;YAC7D,uCAAuC;YACvC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,EAAE,iBAAiB;gBACzB,iBAAiB,EAAE,EAAE;gBACrB,QAAQ,EAAE,mEAAmE;gBAC7E,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU;aACvC,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,OAAO,CAAA;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAiC,WAAmC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7F,CAAC;IACF,CAAC;AACF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AAgOA,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,eAAe;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;QACnD,KAAK,aAAa;YACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;QACpD,KAAK,sBAAsB;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;QAC/C,KAAK,eAAe;YACnB,2DAA2D;YAC3D,yDAAyD;YACzD,6DAA6D;YAC7D,uCAAuC;YACvC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,EAAE,iBAAiB;gBACzB,iBAAiB,EAAE,EAAE;gBACrB,QAAQ,EAAE,mEAAmE;gBAC7E,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU;aACvC,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,OAAO,CAAA;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAiC,WAAmC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7F,CAAC;IACF,CAAC;AACF,CAAC"}

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

@@ -4,11 +4,11 @@ export type SessionId = `ses_${string}`;
 export type ToolCallId = `call_${string}`;
 /**
  * Provider-issued tool-use identifier surfaced on the streaming event bus.
- * Providers emit different prefixes (Anthropic: `toolu_*`, OpenAI: `call_*`,
+ * Providers emit different prefixes (`toolu_*`, `call_*`,
  * others vary), so this type intentionally stays unbranded — we accept the
  * provider's verbatim string and use it solely as a correlation key across
  * `tool_input_*`, `tool_executing`, and `tool_completed` events. Distinct
- * from {@link ToolCallId} which is the OpenAI-format identifier carried in
+ * from {@link ToolCallId} which is the wire-format identifier carried in
  * persisted assistant messages and replay records.
  */
 export type ToolUseId = string;

package/dist/types/message/content.d.ts

@@ -0,0 +1,22 @@
+import type { ToolResultBlock, ToolResultContent } from './index.js';
+/**
+ * Normalize tool-result content to blocks.
+ *
+ * A plain string is the common case and stays first-class; this is the
+ * adapter for drivers that want to walk blocks uniformly.
+ */
+export declare function toToolResultBlocks(content: ToolResultContent): readonly ToolResultBlock[];
+/**
+ * Flatten tool-result content to text.
+ *
+ * For drivers that cannot express non-text tool results, and for every
+ * host-facing surface (transcript, compaction, UI) that reasons over
+ * strings. Non-text blocks become a short, honest placeholder rather than
+ * their base64 payload: dumping the bytes is what made `computer-use`
+ * send megabytes of undecodable characters as text, and silently dropping
+ * them would let the model believe it saw something it did not.
+ */
+export declare function toolResultToText(content: ToolResultContent): string;
+/** True when the content needs a driver that can carry non-text blocks. */
+export declare function hasNonTextBlocks(content: ToolResultContent): boolean;
+//# sourceMappingURL=content.d.ts.map

package/dist/types/message/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../src/types/message/content.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEpE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,eAAe,EAAE,CAEzF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAcnE;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAEpE"}

package/dist/types/message/content.js

@@ -0,0 +1,49 @@
+/**
+ * Normalize tool-result content to blocks.
+ *
+ * A plain string is the common case and stays first-class; this is the
+ * adapter for drivers that want to walk blocks uniformly.
+ */
+export function toToolResultBlocks(content) {
+    return typeof content === 'string' ? [{ type: 'text', text: content }] : content;
+}
+/**
+ * Flatten tool-result content to text.
+ *
+ * For drivers that cannot express non-text tool results, and for every
+ * host-facing surface (transcript, compaction, UI) that reasons over
+ * strings. Non-text blocks become a short, honest placeholder rather than
+ * their base64 payload: dumping the bytes is what made `computer-use`
+ * send megabytes of undecodable characters as text, and silently dropping
+ * them would let the model believe it saw something it did not.
+ */
+export function toolResultToText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .map((block) => {
+        switch (block.type) {
+            case 'text':
+                return block.text;
+            case 'image':
+                return `[image: ${block.mediaType}, ${describeSize(block.data)} — not renderable by this provider]`;
+            case 'document':
+                return `[document${block.name ? ` "${block.name}"` : ''}: ${block.mediaType}, ${describeSize(block.data)} — not renderable by this provider]`;
+        }
+    })
+        .join('\n');
+}
+/** True when the content needs a driver that can carry non-text blocks. */
+export function hasNonTextBlocks(content) {
+    return typeof content !== 'string' && content.some((b) => b.type !== 'text');
+}
+/** Approximate decoded byte count of a base64 payload, for a human-readable note. */
+function describeSize(base64) {
+    const bytes = Math.floor((base64.length * 3) / 4);
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+//# sourceMappingURL=content.js.map

package/dist/types/message/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../../../src/types/message/content.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA0B;IAC5D,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAA;AACjF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IAC1D,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAA;IAC/C,OAAO,OAAO;SACZ,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACd,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,MAAM;gBACV,OAAO,KAAK,CAAC,IAAI,CAAA;YAClB,KAAK,OAAO;gBACX,OAAO,WAAW,KAAK,CAAC,SAAS,KAAK,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,qCAAqC,CAAA;YACpG,KAAK,UAAU;gBACd,OAAO,YAAY,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,CAAC,SAAS,KAAK,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,qCAAqC,CAAA;QAC/I,CAAC;IACF,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAA;AACb,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IAC1D,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAA;AAC7E,CAAC;AAED,qFAAqF;AACrF,SAAS,YAAY,CAAC,MAAc;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IACjD,IAAI,KAAK,GAAG,IAAI;QAAE,OAAO,GAAG,KAAK,IAAI,CAAA;IACrC,IAAI,KAAK,GAAG,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IAChE,OAAO,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;AAClD,CAAC"}