@namzu/sdk 27.1.0 → 29.0.0

package/dist/types/provider/interface.d.ts

@@ -15,6 +15,21 @@ export interface LLMProvider {
      * i.e. today's behavior (assume everything works, never warn).
      */
     readonly capabilities?: ProviderCapabilities;
+    /**
+     * Retry behaviour this DRIVER wants, when the generic default is wrong
+     * for the vendor behind it.
+     *
+     * One config was applied to every member of a chain, so an operator
+     * running [expensive primary, cheap self-hosted backup] could not give
+     * the backup a shorter budget — the two have different failure shapes
+     * and different costs per attempt, and only the driver knows which.
+     *
+     * Merged UNDER a caller's config, never over it: the host asked for
+     * something specific and the driver is expressing a default. Absent
+     * means the generic default, which is what every driver had before this
+     * existed.
+     */
+    readonly retryDefaults?: Partial<import('../../provider/retry.js').ProviderRetryConfig>;
     /**
      * The single LLM entry point. Returns an async iterable of
      * {@link StreamChunk} carrying text deltas, tool-call argument
@@ -22,8 +37,8 @@ export interface LLMProvider {
      *
      * Consumers that need an aggregated response (legacy
      * `ChatCompletionResponse` shape) call
-     * `collect(provider.chatStream(params))` from
-     * `@namzu/sdk/provider/collect`. The kernel's iteration
+     * `collectChatCompletion(provider.chatStream(params))` from
+     * `@namzu/sdk/provider/collect-chat-completion`. The kernel's iteration
      * orchestrator consumes the stream directly so it can emit
      * per-delta `RunEvent`s.
      *
@@ -132,5 +147,31 @@ export interface LLMProvider {
      * a vendor rejection rather than a failing build.
      */
     effortLevelsFor?(model: string, thinking?: import('./chat.js').ThinkingConfig): readonly import('./chat.js').ReasoningEffort[];
+    /**
+     * How large a context this model actually has, if the vendor says.
+     *
+     * The kernel's only source below an explicit host config is a
+     * hand-maintained prefix table, and its own header records what that
+     * costs: one vendor family's entries all carried 200k including the
+     * models whose window is 1M, so those runs compacted at roughly 14% full
+     * and threw away the prompt-cache prefix to do it. Every model release drifts the table
+     * again until somebody edits it. Meanwhile at least one driver already
+     * parses a real per-model `context_length` off the vendor listing and
+     * throws it away, because there was no member to return it through.
+     *
+     * Three states, exactly like {@link LLMProvider.effortLevelsFor}: the
+     * member ABSENT means this driver cannot answer at all; a resolved
+     * `undefined` means it asked and does not know; a number is the answer.
+     * The three are different facts and collapsing any two of them turns
+     * "I do not know" into a confident wrong number, which is the failure
+     * the table already made once.
+     *
+     * Resolved ONCE per run, not per iteration — the two consumers are
+     * synchronous and in the hot loop, so this must never become an await
+     * inside it. A rejection or a hang here is not a run failure: the table
+     * is still there, and a driver that cannot answer must not take down a
+     * run that would otherwise work.
+     */
+    resolveContextWindow?(model: string, signal?: AbortSignal): Promise<number | undefined>;
 }
 //# sourceMappingURL=interface.d.ts.map

package/dist/types/provider/interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../../src/types/provider/interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;IAE5C;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,MAAM,EAAE,oBAAoB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAA;IAEpE,UAAU,CAAC,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAA;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,eAAe,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE9C;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,eAAe,CAAC,CACf,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,OAAO,WAAW,EAAE,cAAc,GAC3C,SAAS,OAAO,WAAW,EAAE,eAAe,EAAE,CAAA;CACjD"}
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../../src/types/provider/interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;IAE5C;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC,OAAO,yBAAyB,EAAE,mBAAmB,CAAC,CAAA;IAEvF;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,MAAM,EAAE,oBAAoB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAA;IAEpE,UAAU,CAAC,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC,CAAA;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,eAAe,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE9C;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,eAAe,CAAC,CACf,KAAK,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,OAAO,WAAW,EAAE,cAAc,GAC3C,SAAS,OAAO,WAAW,EAAE,eAAe,EAAE,CAAA;IAEjD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,oBAAoB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CACvF"}

package/dist/types/provider/model.d.ts

@@ -1,8 +1,22 @@
 export interface ModelInfo {
     id: string;
     name: string;
-    contextWindow: number;
-    maxOutputTokens: number;
+    /**
+     * Tokens the model's context holds, when the driver knows.
+     *
+     * OPTIONAL, and the optionality is the fix. Four drivers filled this
+     * with `0` where the vendor listing carries no value — and zero is not
+     * a window, it is "I do not know" written as a number, which reads to
+     * every consumer as a real measurement of a model that can hold
+     * nothing. A caller dividing by it gets `Infinity`; one comparing
+     * against it concludes every prompt is too long.
+     *
+     * Absent says the same thing honestly, and a consumer can then fall
+     * back to its own table instead of trusting a zero.
+     */
+    contextWindow?: number;
+    /** Same, and absent for the same reason. */
+    maxOutputTokens?: number;
     inputPrice: number;
     outputPrice: number;
     supportsToolUse: boolean;

package/dist/types/provider/model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/types/provider/model.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,OAAO,CAAA;IACxB,iBAAiB,EAAE,OAAO,CAAA;CAC1B"}
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/types/provider/model.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,OAAO,CAAA;IACxB,iBAAiB,EAAE,OAAO,CAAA;CAC1B"}

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

@@ -0,0 +1,150 @@
+import type { CostInfo, RunExecutionStatus } from '../common/index.js';
+import type { AuditEventId, RunId, TenantId } from '../ids/index.js';
+/**
+ * What happened to the thing this event describes.
+ *
+ * `'refused'` is a VALUE, not an absent record — the whole reason this type
+ * exists rather than reusing whatever shape {@link import('./events.js').RunEvent}
+ * already had. Before this, a permission denial (the `AuthorizationGate`) and
+ * a guardrail block each produced nothing durable with cost/outcome/identity
+ * attached — the one outcome an auditor most needs was the one absent from
+ * the trail. See ses_020's logging design §5.
+ */
+export type AuditOutcome = 'success' | 'failure' | 'refused';
+/**
+ * Who acted, in the compliance-audit sense: the actor's identity and the
+ * tenant it acted under.
+ *
+ * `persona` is the label a host assigned the agent for THIS run — absent
+ * when the run was not configured with one (most runs today), and nothing
+ * here invents a value for it. Populated only at call sites that actually
+ * have a persona in scope (`runtime/query/index.ts`'s guardrail-block
+ * branches, via `params.persona?.identity.role`); a call site with no
+ * persona in scope (the verification-gate denial inside `tool-review.ts`)
+ * legitimately omits it rather than guessing.
+ */
+export interface AuditActor {
+    readonly agentId: string;
+    readonly tenantId: TenantId;
+    readonly persona?: string;
+}
+/**
+ * What was attempted. `tool` is present for a tool-scoped action; absent for
+ * a run-level one (an input/output guardrail, the run's own completion or
+ * failure). `resource` names the thing the action targeted when that is
+ * narrower than the tool itself — a guardrail's own name, for instance.
+ *
+ * `action` is deliberately a free-text label, not a closed union: unlike
+ * `RunEvent['type']` (which a switch must exhaustively handle, per
+ * Convention #16), nothing here switches on `action` today, and closing it
+ * prematurely would be inventing a vocabulary nobody has asked to enumerate
+ * yet.
+ */
+export interface AuditAction {
+    readonly action: string;
+    readonly tool?: string;
+    readonly resource?: string;
+}
+/**
+ * One entry in a run's audit trail — durable evidence of what the agent
+ * did, under whose identity, at what cost, and whether it was allowed.
+ *
+ * ## Why this is a SEPARATE trail from `RunEvent`
+ *
+ * See {@link import('./store.js').RunStore.appendAuditEvent}'s own doc and
+ * ses_020's logging design §5 for the full reasoning. In short: an
+ * operational log is level-filtered, sampled, rotatable and legitimately
+ * absent when no host installed a sink. None of that is acceptable for the
+ * kernel's own claim — "an auditable trail of what it did and what it
+ * cost", the README's sentence about itself.
+ *
+ * ## `seq` is this trail's OWN sequence space
+ *
+ * Independent of {@link import('./events.js').RunEvent}'s envelope `seq`,
+ * which numbers the (much higher-volume) operational transcript. Two logs,
+ * two cursors, and forcing them to share one counter would make an
+ * unrelated burst on one trail move the other's cursor — see
+ * `manager/run/persistence.ts`'s `_lastAuditSeq` for where this is held.
+ *
+ * ## `cost` is NON-OPTIONAL
+ *
+ * "What it did and what it cost" is the kernel's own sentence about itself
+ * (README) — an audit entry that cannot say what something cost has not
+ * answered the question it exists to answer. It carries the run's
+ * CUMULATIVE total AT THIS MOMENT, matching `Run.costInfo`'s own semantics
+ * (see `utils/cost.ts`'s `accumulateCost`: the field IS the running total,
+ * not a delta, so "the most recent entry carries the answer whole" is
+ * already how the derived summary treats it — see {@link replayRun}).
+ */
+export interface AuditEvent {
+    readonly id: AuditEventId;
+    readonly runId: RunId;
+    readonly seq: number;
+    /** Epoch ms at which the store recorded the event. */
+    readonly timestamp: number;
+    readonly who: AuditActor;
+    readonly what: AuditAction;
+    readonly outcome: AuditOutcome;
+    readonly cost: CostInfo;
+    /** Present on `'refused'` and `'failure'` — the reason a reader needs. */
+    readonly reason?: string;
+    /**
+     * The active span's identity at the moment this entry was recorded —
+     * resolved the same way `utils/log/create-logger.ts`'s `emit` resolves
+     * `LogRecord.traceId`/`spanId`: fresh per record, off the live
+     * `@opentelemetry/api` global, never captured once and reused. Genuinely
+     * absent — not `''`, not `'unknown'` — whenever nothing is active. See
+     * `telemetry/runtime-accessors.ts`'s `getActiveSpanContext` for why.
+     */
+    readonly traceId?: string;
+    readonly spanId?: string;
+}
+/**
+ * What a caller hands
+ * {@link import('../../manager/run/persistence.js').RunPersistence.recordAudit} —
+ * the fields ONLY the call site knows. `id`, `runId`, `seq`, `timestamp`,
+ * `who.agentId`/`who.tenantId` and `cost` are filled in by `recordAudit`
+ * itself from the run it is bound to; a caller supplying them would be
+ * asserting facts about identity and cost that only the run-persistence
+ * layer is positioned to know, and could disagree with what the run
+ * actually holds.
+ */
+export interface AuditEventInput {
+    readonly what: AuditAction;
+    readonly outcome: AuditOutcome;
+    readonly reason?: string;
+    readonly persona?: string;
+}
+/** What {@link replayRun} reconstructs from the trail alone. */
+export interface RunSummary {
+    readonly costInfo: CostInfo;
+    readonly status: Extract<RunExecutionStatus, 'completed' | 'failed'>;
+}
+/**
+ * Reconstruct a completed run's cost and status from its audit trail alone,
+ * with no read of the derived `Run` record.
+ *
+ * This is the verification ses_020's design promises (§5): `Run.costInfo`
+ * and `Run.status`, persisted through `RunStore.writeRunMeta`
+ * (`manager/run/persistence.ts:221`/`:569`), are a full-record overwrite
+ * with no `seq` and no prior-value retention — a DERIVED summary cache, not
+ * the evidence. The audit trail is the evidence, and a divergence between
+ * what this returns and what `Run.costInfo`/`Run.status` actually hold is a
+ * defect in the summary, never in the trail.
+ *
+ * Walks from the END rather than folding forward: `cost` on each entry is
+ * already the run's cumulative total (see {@link AuditEvent.cost}), so the
+ * most recent entry that actually SETTLES the run — `'success'` or
+ * `'failure'` — carries the answer whole. A `'refused'` entry is a single
+ * action inside a still-open run, never the run's own verdict, and is
+ * skipped rather than treated as terminal: otherwise a refusal that
+ * happened to be the last write before a crash would replay as the run's
+ * final status, which is not what it means.
+ *
+ * `undefined` when no terminal entry exists — a run still in progress, or
+ * one that crashed before a terminal write landed. Callers that need "no
+ * answer yet" and "diverges from the derived summary" to read differently
+ * should treat `undefined` as the former.
+ */
+export declare function replayRun(events: readonly AuditEvent[]): RunSummary | undefined;
+//# sourceMappingURL=audit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/types/run/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,EAAE,EAAE,YAAY,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,gEAAgE;AAChE,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,EAAE,WAAW,GAAG,QAAQ,CAAC,CAAA;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,GAAG,SAAS,CAQ/E"}

package/dist/types/run/audit.js

@@ -0,0 +1,39 @@
+/**
+ * Reconstruct a completed run's cost and status from its audit trail alone,
+ * with no read of the derived `Run` record.
+ *
+ * This is the verification ses_020's design promises (§5): `Run.costInfo`
+ * and `Run.status`, persisted through `RunStore.writeRunMeta`
+ * (`manager/run/persistence.ts:221`/`:569`), are a full-record overwrite
+ * with no `seq` and no prior-value retention — a DERIVED summary cache, not
+ * the evidence. The audit trail is the evidence, and a divergence between
+ * what this returns and what `Run.costInfo`/`Run.status` actually hold is a
+ * defect in the summary, never in the trail.
+ *
+ * Walks from the END rather than folding forward: `cost` on each entry is
+ * already the run's cumulative total (see {@link AuditEvent.cost}), so the
+ * most recent entry that actually SETTLES the run — `'success'` or
+ * `'failure'` — carries the answer whole. A `'refused'` entry is a single
+ * action inside a still-open run, never the run's own verdict, and is
+ * skipped rather than treated as terminal: otherwise a refusal that
+ * happened to be the last write before a crash would replay as the run's
+ * final status, which is not what it means.
+ *
+ * `undefined` when no terminal entry exists — a run still in progress, or
+ * one that crashed before a terminal write landed. Callers that need "no
+ * answer yet" and "diverges from the derived summary" to read differently
+ * should treat `undefined` as the former.
+ */
+export function replayRun(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event === undefined)
+            continue;
+        if (event.outcome === 'success')
+            return { costInfo: event.cost, status: 'completed' };
+        if (event.outcome === 'failure')
+            return { costInfo: event.cost, status: 'failed' };
+    }
+    return undefined;
+}
+//# sourceMappingURL=audit.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../../src/types/run/audit.ts"],"names":[],"mappings":"AAiIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,SAAS,CAAC,MAA6B;IACtD,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAA;QACvB,IAAI,KAAK,KAAK,SAAS;YAAE,SAAQ;QACjC,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;QACrF,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;IACnF,CAAC;IACD,OAAO,SAAS,CAAA;AACjB,CAAC"}

package/dist/types/run/cancel-cause.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Why a run stopped, when it stopped because somebody stopped it.
+ *
+ * `stopReason: 'cancelled'` says the run was cancelled and nothing more,
+ * and the four cases behind it want four different responses. An operator
+ * pressing cancel is not a defect. A parent abandoning its children is a
+ * fact about the parent, and looking for the child's problem wastes the
+ * reader's time. A budget stop is a configuration question. A hook's
+ * refusal is a policy one.
+ *
+ * The gap was not that the information was thrown away — it was never
+ * carried. `AbstractAgent.cancel()` aborted with no argument at all, and
+ * `AgentManager` aborted a child with the bare string `'canceled'`, which
+ * `abortReasonText` deliberately renders as no reason (it would otherwise
+ * print "was cancelled: canceled"). So both paths arrived at the run loop
+ * indistinguishable.
+ */
+export type CancelCause = 'user' | 'parent' | 'budget' | 'hook';
+/**
+ * The abort reason a cancellation carries.
+ *
+ * An `Error` subclass rather than a bare value, because `AbortController`
+ * reasons cross package boundaries and a plain object gives a reader
+ * nothing in a stack trace. `name` is checked rather than `instanceof`,
+ * the answer this codebase already settled on for provider errors: two
+ * copies of a package defeat `instanceof` and nothing announces it.
+ */
+export declare class RunCancelled extends Error {
+    readonly name = "RunCancelled";
+    /**
+     * Named `cancelCause`, not `cause`. `Error.cause` already exists and
+     * means "the error this one wrapped", so reusing it would put two
+     * unrelated meanings on one property name and silently change what
+     * anything reading `err.cause` gets.
+     */
+    readonly cancelCause: CancelCause;
+    constructor(cancelCause: CancelCause);
+}
+/**
+ * The cause an abort reason carries, or `undefined` for one that carries
+ * none.
+ *
+ * `undefined` is a real answer and not a fallback. A cancellation whose
+ * origin nobody recorded is not a user cancellation, and substituting
+ * `'user'` would put a confident wrong value where an honest absence
+ * belongs.
+ */
+export declare function cancelCauseOf(reason: unknown): CancelCause | undefined;
+//# sourceMappingURL=cancel-cause.d.ts.map

package/dist/types/run/cancel-cause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel-cause.d.ts","sourceRoot":"","sources":["../../../src/types/run/cancel-cause.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE/D;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACtC,SAAkB,IAAI,kBAAiB;IAEvC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;gBAErB,WAAW,EAAE,WAAW;CAIpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAKtE"}

package/dist/types/run/cancel-cause.js

@@ -0,0 +1,39 @@
+/**
+ * The abort reason a cancellation carries.
+ *
+ * An `Error` subclass rather than a bare value, because `AbortController`
+ * reasons cross package boundaries and a plain object gives a reader
+ * nothing in a stack trace. `name` is checked rather than `instanceof`,
+ * the answer this codebase already settled on for provider errors: two
+ * copies of a package defeat `instanceof` and nothing announces it.
+ */
+export class RunCancelled extends Error {
+    name = 'RunCancelled';
+    /**
+     * Named `cancelCause`, not `cause`. `Error.cause` already exists and
+     * means "the error this one wrapped", so reusing it would put two
+     * unrelated meanings on one property name and silently change what
+     * anything reading `err.cause` gets.
+     */
+    cancelCause;
+    constructor(cancelCause) {
+        super(`run cancelled by ${cancelCause}`);
+        this.cancelCause = cancelCause;
+    }
+}
+/**
+ * The cause an abort reason carries, or `undefined` for one that carries
+ * none.
+ *
+ * `undefined` is a real answer and not a fallback. A cancellation whose
+ * origin nobody recorded is not a user cancellation, and substituting
+ * `'user'` would put a confident wrong value where an honest absence
+ * belongs.
+ */
+export function cancelCauseOf(reason) {
+    if (reason instanceof Error && reason.name === 'RunCancelled') {
+        return reason.cancelCause;
+    }
+    return undefined;
+}
+//# sourceMappingURL=cancel-cause.js.map

package/dist/types/run/cancel-cause.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel-cause.js","sourceRoot":"","sources":["../../../src/types/run/cancel-cause.ts"],"names":[],"mappings":"AAmBA;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACpB,IAAI,GAAG,cAAc,CAAA;IAEvC;;;;;OAKG;IACM,WAAW,CAAa;IAEjC,YAAY,WAAwB;QACnC,KAAK,CAAC,oBAAoB,WAAW,EAAE,CAAC,CAAA;QACxC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAA;IAC/B,CAAC;CACD;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe;IAC5C,IAAI,MAAM,YAAY,KAAK,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QAC/D,OAAQ,MAAuB,CAAC,WAAW,CAAA;IAC5C,CAAC;IACD,OAAO,SAAS,CAAA;AACjB,CAAC"}

package/dist/types/run/checkpoint-store.d.ts

@@ -176,7 +176,7 @@ export interface DurableRunEntry extends CheckpointRunScope {
      * neither, or either, and the state a queue worker needs most is parked
      * AND unclaimed, which one union cannot say.
      */
-    readonly claim?: ClaimSummary;
+    readonly claim?: LeaseSummary;
 }
 /**
  * Which order a listing comes back in.
@@ -223,13 +223,13 @@ export type DurableRunOrder =
  * Not a random token, deliberately: randomness proves identity and cannot
  * establish *order*, and order is the entire mechanism.
  */
-export type ClaimFence = number;
+export type FencingToken = number;
 /** A holding of a run's claim, as issued to the process that took it. */
-export interface RunClaim {
+export interface RunLease {
     /** Opaque caller-supplied identity — a worker id, a pod name. Evidence, not authority. */
     readonly holder: string;
-    /** See {@link ClaimFence}. Present it on every durable write. */
-    readonly fence: ClaimFence;
+    /** See {@link FencingToken}. Present it on every durable write. */
+    readonly fence: FencingToken;
     /**
      * Absolute epoch ms after which the claim may be taken by somebody else.
      *
@@ -240,9 +240,9 @@ export interface RunClaim {
     readonly expiresAt: number;
 }
 /** A run's claim as a listing reports it. */
-export interface ClaimSummary {
+export interface LeaseSummary {
     readonly holder: string;
-    readonly fence: ClaimFence;
+    readonly fence: FencingToken;
     readonly expiresAt: number;
     /**
      * Whether the claim had expired at the instant the listing was taken.
@@ -254,6 +254,18 @@ export interface ClaimSummary {
      */
     readonly expired: boolean;
 }
+/**
+ * Old spellings of the three above, live for one deprecation window.
+ *
+ * These are types with no runtime value, so a plain `export type` carries
+ * the `@deprecated` tag fine — the `const`+`type` pair the SDK barrel uses
+ * for renamed CLASSES is not needed here and would not compile.
+ *
+ * The verbs did NOT move with them. `claimRun`, `releaseRun` and
+ * `toClaimSummary` keep their names: "claim a lease" is idiomatic, and
+ * renaming the methods would break every `CheckpointStore` implementor for
+ * no reading gain — the opposite of the point.
+ */
 /** What a caller asks for when taking a run. */
 export interface ClaimRunOptions {
     /** Who is taking it. Recorded so an operator can see what holds a stuck run. */
@@ -344,7 +356,7 @@ export interface CheckpointStore {
     /**
      * Persist one checkpoint. Overwrites an existing checkpoint with the same id.
      *
-     * @param fence the {@link ClaimFence} of the holding this write belongs
+     * @param fence the {@link FencingToken} of the holding this write belongs
      *   to, when the run is claimed. A store that supports claims REFUSES a
      *   write whose fence is below the run's current one — that refusal is
      *   what makes a claim a lease rather than a suggestion, because a holder
@@ -357,7 +369,7 @@ export interface CheckpointStore {
      *   that would make adding a claim to one worker break every worker that
      *   has not adopted it yet.
      */
-    writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint, fence?: ClaimFence): Promise<void>;
+    writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint, fence?: FencingToken): Promise<void>;
     /** Load a single checkpoint by id. Returns `null` when it does not exist. */
     readCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<IterationCheckpoint | null>;
     /**
@@ -479,7 +491,7 @@ export interface CheckpointStore {
      *     claim from each other instantly. Use something per-process, not a
      *     per-deployment name.
      */
-    claimRun?(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunClaim | null>;
+    claimRun?(scope: CheckpointRunScope, options: ClaimRunOptions): Promise<RunLease | null>;
     /**
      * Give a claim up early. Idempotent: releasing a claim that already
      * expired, was superseded, or never existed succeeds as a no-op.
@@ -494,6 +506,6 @@ export interface CheckpointStore {
      * difference, never a correctness one, which is the property that lets a
      * crashed worker be indistinguishable from a slow one.
      */
-    releaseRun?(scope: CheckpointRunScope, fence: ClaimFence): Promise<void>;
+    releaseRun?(scope: CheckpointRunScope, fence: FencingToken): Promise<void>;
 }
 //# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/types/run/checkpoint-store.d.ts.map

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

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

@@ -2,7 +2,7 @@ import type { ModelPricing } from '../../utils/cost.js';
 import type { Logger } from '../../utils/logger.js';
 import type { RunId, SessionId, TenantId } from '../ids/index.js';
 import type { PermissionMode } from '../permission/index.js';
-import type { ProjectId, ThreadId } from '../session/ids.js';
+import type { ProjectId, TopicId } from '../session/ids.js';
 import type { CheckpointStore } from './checkpoint-store.js';
 export interface AgentRunConfig {
     model: string;
@@ -51,6 +51,12 @@ export interface AgentRunConfig {
         timeoutMs?: number;
         memoryLimitMb?: number;
         maxProcesses?: number;
+        /**
+         * What the sandbox is rooted at — see `SandboxConfigSchema.workspace`.
+         * Absent means `'ephemeral'`: a fresh temp directory, which is the
+         * behaviour every sandboxed run had before this existed.
+         */
+        workspace?: 'ephemeral' | 'working-directory';
     };
     /**
      * Iteration-checkpoint cadence: create a checkpoint on every Nth
@@ -96,11 +102,25 @@ export interface AgentRunConfig {
      * Default `undefined` — no deadline, today's behaviour.
      */
     hitlParkTtlMs?: number;
+    /**
+     * Override the logger a run's log lines derive from.
+     *
+     * This is an override of the SOURCE, not a substitute for correlation:
+     * `RunContextFactory.buildLogger` always calls `.child()` on whichever
+     * logger this resolves to, so a host-supplied logger still gains
+     * `namzu.run.id`, `sessionId`, `threadId`, `projectId` and `tenantId` —
+     * the same binding the process default gets. A host that wants its own
+     * sink, format or destination threaded through every record a run
+     * produces sets this once; a host that wants the process default
+     * (`getRootLogger()`) sets nothing, which is what absent has always
+     * meant.
+     */
+    logger?: Logger;
 }
 /**
- * Config for {@link RunPersistence}. `sessionId`, `threadId`, `tenantId`,
+ * Config for {@link RunPersistence}. `sessionId`, `topicId`, `tenantId`,
  * and `projectId` are required — every Run is attributed across the full
- * five-layer scope (Tenant → Project → Thread → Session → Run,
+ * five-layer scope (Tenant → Project → Topic → Session → Run,
  * Convention #17).
  */
 export interface RunPersistenceConfig {
@@ -113,7 +133,7 @@ export interface RunPersistenceConfig {
     pricing?: ModelPricing;
     log: Logger;
     sessionId: SessionId;
-    threadId: ThreadId;
+    topicId: TopicId;
     tenantId: TenantId;
     projectId: ProjectId;
     parentRunId?: RunId;

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/run/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,sBAAsB,EAAE,cAAc,CAAA;IAExD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,EAAE,OAAO,sBAAsB,EAAE,eAAe,CAAA;IACvD,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,OAAO,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,YAAY,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,KAAK,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,cAAc,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,GAAG,EAAE,MAAM,CAAA;IAEX,SAAS,EAAE,SAAS,CAAA;IACpB,QAAQ,EAAE,QAAQ,CAAA;IAClB,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,SAAS,CAAA;IAEpB,WAAW,CAAC,EAAE,KAAK,CAAA;IAEnB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;;OAKG;IACH,eAAe,CAAC,EAAE,eAAe,CAAA;IAEjC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAA;CACxC;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,sBAAsB,EAAE,MAAM,CAAA;CAC9B"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/run/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC5D,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,sBAAsB,EAAE,cAAc,CAAA;IAExD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,EAAE,OAAO,sBAAsB,EAAE,eAAe,CAAA;IACvD,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAA;IAC/B,OAAO,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB;;;;WAIG;QACH,SAAS,CAAC,EAAE,WAAW,GAAG,mBAAmB,CAAA;KAC7C,CAAA;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,KAAK,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,cAAc,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,GAAG,EAAE,MAAM,CAAA;IAEX,SAAS,EAAE,SAAS,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,QAAQ,CAAA;IAClB,SAAS,EAAE,SAAS,CAAA;IAEpB,WAAW,CAAC,EAAE,KAAK,CAAA;IAEnB,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;;OAKG;IACH,eAAe,CAAC,EAAE,eAAe,CAAA;IAEjC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,YAAY,EAAE,QAAQ,CAAA;CACxC;AAED,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,kBAAkB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,sBAAsB,EAAE,MAAM,CAAA;CAC9B"}

package/dist/types/run/derive-status.d.ts

@@ -1,11 +1,11 @@
-import type { AgentStatus } from '../common/index.js';
+import type { RunExecutionStatus } from '../common/index.js';
 import type { PendingDecision } from '../hitl/index.js';
 import type { RunStatus } from './status.js';
 /**
  * Project what the SDK records about a run onto the session-layer
  * {@link RunStatus}.
  *
- * `Run.status` is an {@link AgentStatus} — six values, none of which can
+ * `Run.status` is an {@link RunExecutionStatus} — six values, none of which can
  * say "a human owes this run an answer". `RunStatus` has the vocabulary for
  * that and is consumed by session-status derivation and by handoff gating,
  * but nothing in the repo ever produced it: a host implementing a resolver
@@ -20,7 +20,7 @@ import type { RunStatus } from './status.js';
  */
 export declare function deriveRunStatus(input: {
     /** What the run itself recorded. */
-    readonly status: AgentStatus;
+    readonly status: RunExecutionStatus;
     /** The run's outstanding park, if it has one. */
     readonly park?: PendingDecision;
     /** Injectable for tests; defaults to now. */

package/dist/types/run/derive-status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"derive-status.d.ts","sourceRoot":"","sources":["../../../src/types/run/derive-status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACtC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAA;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,SAAS,CAiCZ"}
+{"version":3,"file":"derive-status.d.ts","sourceRoot":"","sources":["../../../src/types/run/derive-status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACtC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;IACnC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAA;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,SAAS,CAiCZ"}

package/dist/types/run/derive-status.js

@@ -2,7 +2,7 @@
  * Project what the SDK records about a run onto the session-layer
  * {@link RunStatus}.
  *
- * `Run.status` is an {@link AgentStatus} — six values, none of which can
+ * `Run.status` is an {@link RunExecutionStatus} — six values, none of which can
  * say "a human owes this run an answer". `RunStatus` has the vocabulary for
  * that and is consumed by session-status derivation and by handoff gating,
  * but nothing in the repo ever produced it: a host implementing a resolver