@namzu/sdk 43.0.0 → 44.0.0

package/dist/types/session/turn-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-state.js","sourceRoot":"","sources":["../../../src/types/session/turn-state.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,cAAc,EACd,WAAW,EACX,WAAW,EACX,UAAU,EACV,SAAS,EACT,QAAQ,GACR,MAAM,mBAAmB,CAAA;AAgE1B;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAErC;IACA;IAFV,YACU,KAAc,EACd,QAAgB,EACzB,OAAgB;QAEhB,KAAK,CACJ,OAAO;YACN,iDAAiD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,oBAAoB,QAAQ,kGAAkG,CACrM,CAAA;QAPQ,UAAK,GAAL,KAAK,CAAS;QACd,aAAQ,GAAR,QAAQ,CAAQ;QAOzB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACpC,CAAC;CACD;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAU,CAAA;AAE5C,SAAS,gBAAgB,CAAC,MAA+B;IACxD,MAAM,UAAU,GAAG;QAClB,SAAS,EAAE,WAAW;QACtB,MAAM,EAAE,QAAQ;QAChB,eAAe,EAAE,WAAW;QAC5B,YAAY,EAAE,QAAQ;QACtB,SAAS,EAAE,WAAW;QACtB,QAAQ,EAAE,UAAU;QACpB,OAAO,EAAE,SAAS;QAClB,YAAY,EAAE,cAAc;KAC5B,CAAA;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QAC3B,IAAI,KAAK,KAAK,SAAS;YAAE,QAAQ,CAAC,KAAe,CAAC,CAAA;IACnD,CAAC;IACD,OAAO,MAAM,CAAA;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAsB;IACpD,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,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAA;IACzD,CAAC;IACD,MAAM,MAAM,GAAG,GAA8B,CAAA;IAC7C,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,IAAI,qBAAqB,CAC9B,MAAM,CAAC,OAAO,EACd,kBAAkB,EAClB,+BAA+B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,oIAAoI,CACjM,CAAA;IACF,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,kBAAkB,EAAE,CAAC;QAC3C,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAA;IACpE,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,CAAyB,CAAA;AACxD,CAAC"}

package/dist/types/session/turn.d.ts

@@ -0,0 +1,215 @@
+import type { SessionTokenBudgetSummary } from '../../store/budget/index.js';
+import type { CostInfo, TokenUsage } from '../common/index.js';
+import type { CheckpointId, MessageId, ProjectId, SessionId, TenantId, TurnId } from '../ids/index.js';
+import type { Message } from '../message/index.js';
+import type { ProviderErrorInfo } from '../provider/index.js';
+import type { TurnConfig } from './config.js';
+import type { StepResult } from './step.js';
+import type { StopReason } from './stop-reason.js';
+export type { TurnId };
+/**
+ * Where a turn is in its lifecycle. Six members, unchanged from the type it
+ * replaces. `Turn.status` and `TurnSettlement.status` use it.
+ */
+export type TurnExecutionStatus = 'idle' | 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * The domain status a session log's fold derives for a turn.
+ *
+ *  - `queued` — the turn exists and has not started.
+ *  - `running` — the iteration loop is in flight, or the turn is paused on a
+ *    provider wait with no decision open.
+ *  - `awaiting_hitl` — synchronously waiting on a human (user present).
+ *  - `awaiting_hitl_resolution` — paused with a decision open; the user is
+ *    absent and the turn persists until the decision is resolved or the turn
+ *    is abandoned.
+ *  - `awaiting_subsession` — delegated to a child session and suspended until
+ *    it settles. Session-level fan-in treats this as active.
+ *  - `succeeded`, `failed`, `cancelled` — terminal.
+ *
+ * The wire form (`WireTurnStatus`) maps both `awaiting_hitl*` members to
+ * `awaiting_input`.
+ */
+export type TurnStatus = 'queued' | 'running' | 'awaiting_hitl' | 'awaiting_hitl_resolution' | 'awaiting_subsession' | 'succeeded' | 'failed' | 'cancelled';
+/** The durable subset of {@link TurnConfig} recorded in `turn_started.config`. */
+export interface TurnConfigSnapshot {
+    model: string;
+    tokenBudget: number;
+    timeoutMs: number;
+    streamIdleTimeoutMs?: number;
+    maxRequestRichContentBytes?: number;
+    maxIterations?: number;
+    temperature?: number;
+    maxResponseTokens?: number;
+    costLimitUsd?: number;
+}
+/**
+ * The token ledger a turn spends from.
+ *
+ * Keyed by the ROOT session and the root turn: a root turn opens its own
+ * ledger with its own limit, a child session's turns bind to the key of the
+ * root turn that spawned them, and a resumed paused turn reuses its key. So a
+ * limit that changes between two turns of one session is two ledgers, never a
+ * mismatch.
+ */
+export interface TurnBudgetBinding {
+    readonly rootSessionId: SessionId;
+    readonly rootTurnId: TurnId;
+    readonly accountId: string;
+}
+/** Which surface opened a session or a turn, and the caller-side ids it used. */
+export type OriginProtocol = 'cli' | 'sdk' | 'ag-ui' | 'a2a' | 'acp' | 'http' | 'desktop' | 'resident';
+/** What kind of work a turn is. A prompt, a goal round, a resident step and a verification step are each a new turn. */
+export type TurnOriginKind = 'prompt' | 'goal-round' | 'resident-step' | 'verification';
+export interface Origin {
+    readonly protocol: OriginProtocol;
+    /** The caller's own session, thread or context id. Any string; not required to be a UUID. */
+    readonly externalSessionId?: string;
+    /** The caller's own id for this unit of work, such as the id an AG-UI client gives its turn. Echoed back verbatim. */
+    readonly externalTurnId?: string;
+    readonly kind?: TurnOriginKind;
+    readonly goalId?: string;
+    readonly round?: number;
+}
+/**
+ * A caller-side name for a session. The index's `external_refs` table is
+ * derived from these (and from `origin`), never written directly, so it
+ * survives a rebuild.
+ */
+export interface ExternalRef {
+    readonly protocol: string;
+    readonly kind: 'session' | 'thread' | 'context';
+    /** Any string; no UUID requirement. */
+    readonly externalId: string;
+}
+/** Which override, if any, decided a turn's `result`. `model` means the model's own text. */
+export type TurnResultSource = 'model' | 'guardrail_blocked' | 'guardrail_rewritten' | 'review' | 'outstanding_work' | 'structured_output';
+/** How a turn ended: carried on `turn_completed` and `turn_failed`. */
+export interface TurnSettlement {
+    /** `completed` or `cancelled` on `turn_completed`; `failed` on `turn_failed`. */
+    readonly status: TurnExecutionStatus;
+    readonly iterations: number;
+    /** Usage of this turn only; descendant spend is in the budget summary. */
+    readonly usage: TokenUsage;
+    readonly cost: CostInfo;
+    readonly durationMs: number;
+    /** The assistant message holding the answer, after any `message_replaced`. */
+    readonly resultMessageId?: MessageId;
+    readonly resultSource: TurnResultSource;
+    readonly structuredOutput?: unknown;
+    /** The provider-chain member that served the end of the turn, when it was not the configured one. */
+    readonly servingProvider?: string;
+    /** Delegated tasks still running when the turn ended. Not cancelled; named. */
+    readonly abandonedTaskIds: readonly string[];
+    /** Background jobs the model was waiting on that were still running. Not stopped; named. */
+    readonly abandonedJobIds: readonly string[];
+}
+/** Metadata of one turn: who ran it, with what, and where it sits in the session tree. */
+export interface TurnMetadata {
+    /** This turn's owner, independent of a shared ancestor token account. */
+    readonly scope?: {
+        readonly tenantId: TenantId;
+        readonly projectId: ProjectId;
+        readonly sessionId: SessionId;
+        readonly turnId: TurnId;
+    };
+    agentId: string;
+    agentName: string;
+    config: TurnConfig;
+    /** The provider the turn was configured with: the head of the chain. */
+    provider: string;
+    /** The chain member the turn was routed to at the end, when not the configured one. */
+    servingProvider?: string;
+    /** Present on a child session's turn: the parent session that delegated it. */
+    parentSessionId?: SessionId;
+    /** Present on a child session's turn: the parent turn whose tool call spawned the child. */
+    parentTurnId?: TurnId;
+    /** Child sessions this turn spawned. */
+    childSessionIds?: SessionId[];
+}
+/** Where a replayed turn was forked from. A fork is always a NEW session. */
+export interface TurnForkOrigin {
+    readonly sessionId: SessionId;
+    readonly turnId: TurnId;
+    readonly checkpointId: CheckpointId;
+}
+/**
+ * One turn of a session, as `query()`, `drainQuery()` and `runAgent()`
+ * return it.
+ *
+ * `messages` is the session's context at settle: the fold of the log, with
+ * every `message_replaced` applied. `result` is the authoritative answer,
+ * after guardrail, review, outstanding-work and structured-output overrides.
+ */
+export interface Turn {
+    id: TurnId;
+    sessionId: SessionId;
+    status: TurnExecutionStatus;
+    metadata: TurnMetadata;
+    messages: Message[];
+    /** Usage of this turn only; descendant spend is in `budget`. */
+    tokenUsage: TokenUsage;
+    budget?: SessionTokenBudgetSummary;
+    budgetBinding?: TurnBudgetBinding;
+    costInfo: CostInfo;
+    currentIteration: number;
+    startedAt: number;
+    endedAt?: number;
+    stopReason?: StopReason;
+    lastError?: string;
+    lastProviderError?: ProviderErrorInfo;
+    result?: string;
+    /** Per-iteration record of what the loop did. Absent on a turn that never entered the loop. */
+    steps?: readonly StepResult[];
+    /** Schema-validated final output, when one was requested and produced. */
+    structuredOutput?: unknown;
+    /** Delegated tasks still running when this turn ended. */
+    abandonedTaskIds?: readonly string[];
+    /** Background jobs the model awaited that were still running when this turn ended. */
+    abandonedJobIds?: readonly string[];
+    /** Present on a child session's turn. */
+    parentSessionId?: SessionId;
+    /** Present on a child session's turn. */
+    parentTurnId?: TurnId;
+    depth?: number;
+    /** Present when this turn's session was forked from another session's checkpoint. */
+    forkedFrom?: TurnForkOrigin;
+}
+/** @see Turn */
+export type AgentTurn = Turn;
+/**
+ * The state of a session's active turn: the last `turn_started` whose
+ * `turnId` has no `turn_completed` or `turn_failed` yet.
+ *
+ *  - `paused` — its last segment record is `turn_paused`. Only
+ *    `resumeSession` (same `turnId`) or `abandonTurn` ends it.
+ *  - `running` — a live lease on the session is held.
+ *  - `interrupted` — no live lease and not paused: the process that ran it
+ *    is gone.
+ */
+export type ActiveTurnState = 'running' | 'paused' | 'interrupted';
+/**
+ * A session has at most one active turn. Starting another while one is
+ * running, paused or interrupted is refused with this error.
+ *
+ * Only an `interrupted` turn can be closed automatically, and only when the
+ * caller opts in (`beginTurn({ abandonInterrupted: true })`). A paused turn is
+ * never closed implicitly. Parallel work uses child sessions or separate
+ * sessions.
+ */
+export declare class TurnInProgressError extends Error {
+    readonly name: "TurnInProgressError";
+    readonly sessionId: SessionId;
+    readonly activeTurnId: TurnId;
+    readonly state: ActiveTurnState;
+    constructor(params: {
+        sessionId: SessionId;
+        activeTurnId: TurnId;
+        state: ActiveTurnState;
+    });
+}
+/**
+ * Recognises a {@link TurnInProgressError}, including one from another copy
+ * of this package, so a host protocol server can map it to its own error.
+ */
+export declare function isTurnInProgressError(value: unknown): value is TurnInProgressError;
+//# sourceMappingURL=turn.d.ts.map

package/dist/types/session/turn.d.ts.map

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

package/dist/types/session/turn.js

@@ -0,0 +1,44 @@
+/**
+ * A session has at most one active turn. Starting another while one is
+ * running, paused or interrupted is refused with this error.
+ *
+ * Only an `interrupted` turn can be closed automatically, and only when the
+ * caller opts in (`beginTurn({ abandonInterrupted: true })`). A paused turn is
+ * never closed implicitly. Parallel work uses child sessions or separate
+ * sessions.
+ */
+export class TurnInProgressError extends Error {
+    name = 'TurnInProgressError';
+    sessionId;
+    activeTurnId;
+    state;
+    constructor(params) {
+        const remedy = params.state === 'paused'
+            ? 'Resume it with resumeSession or close it with abandonTurn.'
+            : params.state === 'interrupted'
+                ? 'Its process is gone: resume it, abandon it, or begin the next turn with abandonInterrupted.'
+                : 'Wait for it to end, or cancel it.';
+        super(`Session ${params.sessionId} already has an active turn ${params.activeTurnId} (${params.state}). ${remedy}`);
+        this.sessionId = params.sessionId;
+        this.activeTurnId = params.activeTurnId;
+        this.state = params.state;
+    }
+}
+/**
+ * Recognises a {@link TurnInProgressError}, including one from another copy
+ * of this package, so a host protocol server can map it to its own error.
+ */
+export function isTurnInProgressError(value) {
+    if (value instanceof TurnInProgressError)
+        return true;
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (candidate.name === 'TurnInProgressError' &&
+        typeof candidate.sessionId === 'string' &&
+        typeof candidate.activeTurnId === 'string' &&
+        (candidate.state === 'running' ||
+            candidate.state === 'paused' ||
+            candidate.state === 'interrupted'));
+}
+//# sourceMappingURL=turn.js.map

package/dist/types/session/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","sourceRoot":"","sources":["../../../src/types/session/turn.ts"],"names":[],"mappings":"AAiPA;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC3B,IAAI,GAAG,qBAA8B,CAAA;IAC9C,SAAS,CAAW;IACpB,YAAY,CAAQ;IACpB,KAAK,CAAiB;IAE/B,YAAY,MAA8E;QACzF,MAAM,MAAM,GACX,MAAM,CAAC,KAAK,KAAK,QAAQ;YACxB,CAAC,CAAC,4DAA4D;YAC9D,CAAC,CAAC,MAAM,CAAC,KAAK,KAAK,aAAa;gBAC/B,CAAC,CAAC,6FAA6F;gBAC/F,CAAC,CAAC,mCAAmC,CAAA;QACxC,KAAK,CACJ,WAAW,MAAM,CAAC,SAAS,+BAA+B,MAAM,CAAC,YAAY,KAAK,MAAM,CAAC,KAAK,MAAM,MAAM,EAAE,CAC5G,CAAA;QACD,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;QACjC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAA;QACvC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAA;IAC1B,CAAC;CACD;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IACnD,IAAI,KAAK,YAAY,mBAAmB;QAAE,OAAO,IAAI,CAAA;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAC7D,MAAM,SAAS,GAAG,KAAqC,CAAA;IACvD,OAAO,CACN,SAAS,CAAC,IAAI,KAAK,qBAAqB;QACxC,OAAO,SAAS,CAAC,SAAS,KAAK,QAAQ;QACvC,OAAO,SAAS,CAAC,YAAY,KAAK,QAAQ;QAC1C,CAAC,SAAS,CAAC,KAAK,KAAK,SAAS;YAC7B,SAAS,CAAC,KAAK,KAAK,QAAQ;YAC5B,SAAS,CAAC,KAAK,KAAK,aAAa,CAAC,CACnC,CAAA;AACF,CAAC"}

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

@@ -21,8 +21,8 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
      * than iterating against `maxIterations`.
      */
     maxRetries?: number;
-    /** Review the JSON-decoded result before settlement. Narrow the value before use: serialization may change schema output types. Exceptions fail the run; cancellation is propagated. */
-    review?: (output: unknown, context: import('../run/answer-review.js').AnswerReviewContext) => import('../run/answer-review.js').AnswerReview | Promise<import('../run/answer-review.js').AnswerReview>;
+    /** Review the JSON-decoded result before settlement. Narrow the value before use: serialization may change schema output types. Exceptions fail the turn; cancellation is propagated. */
+    review?: (output: unknown, context: import('../session/answer-review.js').AnswerReviewContext) => import('../session/answer-review.js').AnswerReview | Promise<import('../session/answer-review.js').AnswerReview>;
     /** Corrections allowed after host rejection, separate from schema retries. Default 3; zero allows no correction. */
     maxReviews?: number;
 }

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,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAExB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,wLAAwL;IACxL,MAAM,CAAC,EAAE,CACR,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,yBAAyB,EAAE,mBAAmB,KAE5D,OAAO,yBAAyB,EAAE,YAAY,GAC9C,OAAO,CAAC,OAAO,yBAAyB,EAAE,YAAY,CAAC,CAAA;IAC1D,oHAAoH;IACpH,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"}
+{"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,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAExB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,yLAAyL;IACzL,MAAM,CAAC,EAAE,CACR,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,OAAO,6BAA6B,EAAE,mBAAmB,KAEhE,OAAO,6BAA6B,EAAE,YAAY,GAClD,OAAO,CAAC,OAAO,6BAA6B,EAAE,YAAY,CAAC,CAAA;IAC9D,oHAAoH;IACpH,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/summary/deliverable.d.ts

@@ -16,7 +16,7 @@
  * Convention #6: this is a discriminated union on `kind`; any consumer must
  * handle all variants exhaustively.
  */
-import type { RunId, SessionId } from '../ids/index.js';
+import type { SessionId, TurnId } from '../ids/index.js';
 import type { DeliverableId, SummaryId } from '../session/ids.js';
 /** Discriminator for {@link DeliverableRef}. */
 export type DeliverableKind = 'file' | 'session_summary' | 'message' | 'artifact_blob';
@@ -47,15 +47,15 @@ export interface SessionSummaryDeliverable {
     readonly at: Date;
 }
 /**
- * A specific persisted message within a session run — useful for referencing
+ * A specific persisted message within a session turn — useful for referencing
  * a single LLM turn as an artifact (e.g. a decision record).
  */
 export interface MessageDeliverable {
     readonly id: DeliverableId;
     readonly kind: 'message';
     readonly sessionId: SessionId;
-    readonly runId: RunId;
-    /** Opaque identifier bound to the run's persisted message log. */
+    readonly turnId: TurnId;
+    /** The message's id in the session log. */
     readonly messageId: string;
 }
 /**

package/dist/types/summary/deliverable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deliverable.d.ts","sourceRoot":"","sources":["../../../src/types/summary/deliverable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAEjE,gDAAgD;AAChD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,iBAAiB,GAAG,SAAS,GAAG,eAAe,CAAA;AAEtF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAA;IAC9B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,MAAM,cAAc,GACvB,eAAe,GACf,yBAAyB,GACzB,kBAAkB,GAClB,uBAAuB,CAAA"}
+{"version":3,"file":"deliverable.d.ts","sourceRoot":"","sources":["../../../src/types/summary/deliverable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAEjE,gDAAgD;AAChD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,iBAAiB,GAAG,SAAS,GAAG,eAAe,CAAA;AAEtF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAA;IAC9B,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,MAAM,cAAc,GACvB,eAAe,GACf,yBAAyB,GACzB,kBAAkB,GAClB,uBAAuB,CAAA"}

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

@@ -1,4 +1,4 @@
-import type { RunId, TaskId, TenantId } from '../ids/index.js';
+import type { SessionId, TaskId, TenantId, TurnId } from '../ids/index.js';
 /**
  * `failed` exists because a unit that did not succeed had nowhere to say so.
  *
@@ -22,7 +22,10 @@ export declare function isTerminalTaskStatus(status: TaskStatus): boolean;
 export declare function assertTaskStatus(status: TaskStatus): void;
 export interface Task {
     readonly id: TaskId;
-    readonly runId: RunId;
+    /** The session the task belongs to (`<session-id>/tasks/`). */
+    readonly sessionId: SessionId;
+    /** The turn that created the task. */
+    readonly turnId: TurnId;
     readonly tenantId?: TenantId;
     subject: string;
     description?: string;
@@ -46,7 +49,8 @@ export interface TaskEvent {
 }
 export type TaskEventListener = (event: TaskEvent) => void;
 export interface CreateTaskParams {
-    runId: RunId;
+    sessionId: SessionId;
+    turnId: TurnId;
     tenantId?: TenantId;
     subject: string;
     description?: string;
@@ -71,7 +75,7 @@ export interface TaskStore {
     list(filter?: {
         status?: TaskStatus;
         owner?: string;
-        runId?: RunId;
+        sessionId?: SessionId;
     }): Promise<Task[]>;
     claim(id: TaskId, owner: string): Promise<Task | undefined>;
     block(blockerId: TaskId, blockedId: TaskId): Promise<void>;

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

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

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

@@ -2,7 +2,7 @@ import type { z } from 'zod';
 import type { Logger } from '../../utils/logger.js';
 import type { CodeNavigationProvider } from '../code-navigation/index.js';
 import type { ToolResultGuardrailSpec } from '../guardrail/index.js';
-import type { RunId } from '../ids/index.js';
+import type { SessionId, TurnId } from '../ids/index.js';
 import type { InvocationState } from '../invocation/index.js';
 import type { PermissionMode } from '../permission/index.js';
 import type { Sandbox } from '../sandbox/index.js';
@@ -78,7 +78,7 @@ export interface SkillRegistryRef {
  * `ToolRegistryRef` exists: this type file is imported by everything, and
  * naming the implementation here would drag a `node:child_process` module
  * into every consumer's type graph. `owner` is not on this surface at all —
- * the executor binds it to the run, so a tool cannot start a job that
+ * the executor binds it to the turn, so a tool cannot start a job that
  * outlives, or is billed to, somebody else's run.
  */
 export interface BackgroundJobRegistryRef {
@@ -127,12 +127,12 @@ export interface BackgroundJobRegistryRef {
         exitCode?: number;
     }>;
     /**
-     * Say that the model is waiting on this job, so the run stays open for it
+     * Say that the model is waiting on this job, so the turn stays open for it
      * when the model stops calling tools.
      *
      * Called by `wait_for_job` and nothing else. The kernel holds a finishing
      * run open — bounded, and for no model tokens — only for a job marked
-     * here; a job nobody marked never delays a run, which is what a dev server
+     * here; a job nobody marked never delays a turn, which is what a dev server
      * or a watcher needs. Optional for the reason `waitForExit` is: a host
      * implementing this interface directly may have nowhere to record the
      * intent, and then there is simply no hold.
@@ -140,7 +140,7 @@ export interface BackgroundJobRegistryRef {
     markAwaited?(id: string): void;
 }
 /**
- * Tracks which files the agent has read in the current run.
+ * Tracks which files the agent has read in the current turn.
  * Write tool consults this to enforce the "read before overwrite" invariant
  * an existing file must be read first or the write fails.
  * Keys are the resolved path used by the tool — sandbox-relative when a sandbox
@@ -340,22 +340,48 @@ export interface ToolContext {
      * deadline; an optional signal can cancel capture earlier. Never replays
      * effects. Unsupported stores return undefined.
      */
-    captureRunEvidence?: (maxReadBytes?: number, signal?: AbortSignal) => Promise<import('../../store/evidence/types.js').RunTextEvidenceSource | undefined>;
-    runId: RunId;
+    captureSessionEvidence?: (maxReadBytes?: number, signal?: AbortSignal) => Promise<import('../../store/evidence/types.js').SessionTextEvidenceSource | undefined>;
+    /** The session this call belongs to. */
+    sessionId: SessionId;
+    /** The turn this call belongs to. */
+    turnId: TurnId;
     workingDirectory: string;
     /**
      * Directories besides the working directory the file tools may reach,
-     * absolute. A host adds one for a session (`/add-dir`); a sandboxed run
+     * absolute. A host adds one for a session (`/add-dir`); a sandboxed turn
      * binds each. Relative paths still resolve against the working
      * directory; an absolute path inside any of these is accepted.
      */
     additionalDirectories?: readonly string[];
+    /**
+     * Absolute paths outside the working directory and the added directories
+     * that THIS call was approved to reach.
+     *
+     * Set by the executor only for a call a review approved after the
+     * kernel named these paths in it (`ToolCallSummary.escalation`), and only
+     * when the turn asked for that (`QueryParams.outsideRootAccess:
+     * 'review'`). The file tools treat each as one more root for this call
+     * alone; nothing here widens the next call. Absent is the ordinary case:
+     * a path outside the roots is refused.
+     */
+    approvedPaths?: readonly string[];
+    /**
+     * This call was approved to run outside the turn's sandbox.
+     *
+     * Set by the executor only when a reviewer CONFIRMED the escape for this
+     * call by id (`HITLResumeDecision.confirmedEscalations`) and the turn
+     * allows escapes at all (`QueryParams.sandboxEscape: 'review'`). A tool
+     * that offers an escape honours it only when this is `true`, and refuses
+     * the request otherwise.
+     */
+    sandboxEscapeApproved?: boolean;
     abortSignal: AbortSignal;
     env: Record<string, string>;
     log: (level: 'info' | 'warn' | 'error', message: string) => void;
     permissionContext?: {
         mode: PermissionMode;
-        runId: string;
+        sessionId: string;
+        turnId: string;
         workingDirectory: string;
     };
     invocationState?: InvocationState;
@@ -376,7 +402,7 @@ export interface ToolContext {
     allowedTools?: readonly string[];
     sandbox?: Sandbox;
     /**
-     * Symbol resolution for this run, when a host wired one up.
+     * Symbol resolution for this turn, when a host wired one up.
      *
      * Absent means the `lsp` tool is not registered at all — see
      * `tools/builtins/lsp.ts` for why a tool that is always present and
@@ -401,13 +427,13 @@ export interface ToolContext {
     /**
      * Where the `skill` tool reads from.
      *
-     * Absent means the run has no skills, and the tool says so rather than
+     * Absent means the turn has no skills, and the tool says so rather than
      * reporting an empty list — "no skills here" and "no registry" are
      * different answers.
      */
     skills?: SkillRegistryRef;
     /**
-     * How this run reaches the web.
+     * How this turn reaches the web.
      *
      * Two independent halves, and either may be absent. This kernel ships a
      * guarded fetch provider and NO search backend, so `search` missing is
@@ -465,9 +491,9 @@ export interface ToolContext {
      */
     maxToolOutputChars?: number;
     /**
-     * Screens the RUN asked for, applied to results this call produces.
+     * Screens the TURN asked for, applied to results this call produces.
      *
-     * Worth having because a run usually does not build its registry: a host
+     * Worth having because a turn usually does not build its registry: a host
      * assembles one and hands it to `runAgent`, so a registry-construction
      * option alone is the host's to write and the kernel's default reaches
      * nobody.
@@ -476,9 +502,9 @@ export interface ToolContext {
      * the registry was built with them — including an empty array, which means
      * none — because a registry that stated its policy has stated it. These
      * apply to a registry that declared none, which is the ordinary case: a
-     * host assembles a registry and hands it to a run it does not own.
+     * host assembles a registry and hands it to a turn it does not own.
      *
-     * `undefined` means the run declared none; an empty array means the run
+     * `undefined` means the turn declared none; an empty array means the turn
      * declared none ON PURPOSE, which is how a caller turns off a screen the
      * executor would otherwise install by default.
      */
@@ -499,7 +525,7 @@ export interface ToolContext {
      *
      * Tools are host-installed code — the model cannot add one — so the trust
      * boundary this protects is the MODEL's reach. `allowedTools` is enforced
-     * again at dispatch. When the run has an operator authorization gate, a
+     * again at dispatch. When the turn has an operator authorization gate, a
      * nested call must be explicitly allowed by that gate; a deny or an
      * undecided call fails closed because another durable human review cannot
      * be opened from inside the already-executing parent.
@@ -515,13 +541,13 @@ export interface ToolContext {
      */
     toolUseId?: string;
     /**
-     * Stable, run-scoped identity shared by every direct tool call the model
+     * Stable, turn-scoped identity shared by every direct tool call the model
      * issued in the same response batch.
      *
      * `toolUseId` answers "which call is this?"; this answers "which sibling
      * calls were launched together?". Hosts use it to keep a concurrent group
      * visible while one sibling is still running without accidentally reviving
-     * terminal work from an older batch or another run whose provider reused a
+     * terminal work from an older batch or another turn whose provider reused a
      * call id. Optional because a host may invoke a tool directly, outside the
      * query executor.
      */
@@ -530,7 +556,7 @@ export interface ToolContext {
      * How this execution entered the tool registry.
      *
      * Present on executor-owned calls. Optional because a host may invoke a
-     * tool directly outside a run and construct its own minimal context.
+     * tool directly outside a turn and construct its own minimal context.
      */
     source?: ToolCallSource;
     /**
@@ -551,7 +577,7 @@ export interface ToolContext {
      * own, and one tool may pause more than once.
      *
      * Absent when whatever is driving the tool provides no route to a
-     * human — a host calling a tool directly, outside a run. A tool must
+     * human — a host calling a tool directly, outside a turn. A tool must
      * treat it as optional and decide what to do without one, and must
      * never read an unanswered pause as consent; the outcome says which it
      * was, in its own shape, so silence cannot be destructured into a yes.
@@ -624,7 +650,7 @@ export interface ToolResult {
      */
     retryable?: boolean;
     /**
-     * Facts this result pins into the run's working memory, by key. The
+     * Facts this result pins into the turn's working memory, by key. The
      * kernel keeps them in the working-memory slot — in front of the model
      * every iteration, across compaction — and a later pin under the same
      * key replaces the earlier one. For what a tool knows and the model
@@ -691,12 +717,33 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
      * chaining — has nothing to decompose and must not claim otherwise.
      */
     commandArgument?: string;
+    /**
+     * The argument that holds a filesystem path the tool resolves against the
+     * turn's roots (the working directory and the added directories).
+     *
+     * Declared so the kernel can see, BEFORE the call runs, that it names a
+     * path outside those roots and turn it into an approval request instead
+     * of a refusal (`QueryParams.outsideRootAccess: 'review'`). A tool that
+     * does not declare it keeps refusing such a path at execution, which is
+     * the safe direction to be wrong in.
+     */
+    pathArgument?: string;
+    /**
+     * The boolean argument by which a call asks to run outside the turn's
+     * sandbox, when the tool offers that at all (the shipped `bash` does).
+     *
+     * A call that sets it under a sandbox is always reviewed, is never
+     * approved by a mode, a remembered grant or an `allow` rule, and runs
+     * unconfined only when a reviewer confirmed it by id. See
+     * `ToolContext.sandboxEscapeApproved`.
+     */
+    sandboxEscapeArgument?: string;
     execute(input: TInput, context: ToolContext): Promise<ToolResult>;
     tier?: string;
     permissions?: ToolPermission[];
     category?: 'filesystem' | 'shell' | 'network' | 'analysis' | 'custom';
     /**
-     * Deadline for a single execution, overriding the run-level default.
+     * Deadline for a single execution, overriding the turn-level default.
      *
      * On expiry the executor stops waiting and returns a model-visible
      * error result, so a slow dependency becomes something the agent can
@@ -724,21 +771,21 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
      */
     maxRetries?: number;
     /**
-     * This tool's output IS the run's answer: settle with it instead of
+     * This tool's output IS the turn's answer: settle with it instead of
      * asking the model to restate it.
      *
      * Every delegation path is blocking and returns the worker's final
      * text as the dispatching call's result, after which the loop went
      * round again — so a router agent, whose entire job is to pick a
      * specialist, paid one extra model call per request at the parent's
-     * full context size, the most expensive call in the run. The relay is
+     * full context size, the most expensive call in the turn. The relay is
      * also LOSSY: the parent paraphrases the worker's answer through its
      * own (compacted) context, so what the caller receives is not what the
      * worker produced.
      *
      * Honoured only when the terminal call is the ONLY call in the turn
      * and it did not fail. A model that asked for other work in the same
-     * turn meant to see those results, and ending the run would discard
+     * turn meant to see those results, and ending the turn would discard
      * answers it requested; that turn takes the ordinary path and the
      * reason is logged. A failed terminal call is not an answer either —
      * the error goes back to the model, which is the point of returning