@namzu/cli 26.3.0 → 28.0.0

package/dist/tui/agent.d.ts

@@ -11,26 +11,29 @@
  * Unlike the earlier `chatStream()`-only adapter, this drives the full
  * tool-execution loop: the model can call tools, their results are fed
  * back, and the loop iterates until the turn settles. We translate the
- * SDK's `RunEvent` stream into the TUI's smaller `AgentEvent` vocabulary
+ * SDK's `SessionEvent` stream into the TUI's smaller `AgentEvent` vocabulary
  * (text deltas + tool start/end + done/error).
  *
- * The TUI owns conversation history and passes the full `Message[]` on
- * every turn (stateless session). Empty / partial states (no
+ * The TUI holds the conversation it renders and passes the full `Message[]`
+ * on every turn; the session's log, which the kernel appends to while the
+ * turn runs, is what a later resume folds back. Empty / partial states (no
  * credentials, no preferences, no matching detected provider) return an
  * `emptySession()` whose `send()` yields a single error event so the UI
  * renders an actionable hint rather than crashing.
  */
-import { type AuthorizationRule, type BackgroundJob, type CheckpointStore, type CompactionResult, type CostInfo, type DurableRunEntry, type FencingToken, type GoalRoundAuthority, type LLMProvider, type Message, type ModelInfo, type PrepareStep, type ProjectId, type ReasoningEffort, type ResidentHistorySource, type ResidentStepPromptOptions, type ResidentToolEvidenceSource, type ResumeHandler, type ResumeOutcome, type ReviewAnswer, type RunEvent, type RunId, type SessionGoalStore, type SessionId, type StopReason, type StructuredOutputConfig, type TaskStore, type TenantId, type TokenBudgetSummary, type ToolCallView, type ToolPresenter, ToolRegistry, type ToolResultView, type ToolReviewAnswer, type ToolReviewPrompt, type ToolReviewRequest, type TopicId, batchNeedsReview } from '@namzu/sdk';
+import { type AuthorizationRule, type BackgroundJob, type CompactionResult, type CostInfo, type GoalRoundAuthority, type LLMProvider, type MemoryType, type Message, type ModelInfo, type Origin, type PrepareStep, type ProjectId, type ReasoningEffort, type RenderedMemoryIndex, type ResidentHistorySource, type ResidentStepPromptOptions, type ResidentToolEvidenceSource, type ResumeHandler, type ResumeOutcome, type ReviewAnswer, type SessionCheckpointStore, type SessionEvent, type SessionGoalStore, type SessionId, type SessionLease, type SessionLog, type SessionStartedRecord, type SessionTokenBudgetSummary, type StopReason, type StructuredOutputConfig, type TaskStore, type TenantId, type ToolCallEscalation, type ToolCallView, type ToolPresenter, ToolRegistry, type ToolResultView, type ToolReviewAnswer, type ToolReviewPrompt, type ToolReviewRequest, type TopicId, type TurnId, batchNeedsReview } from '@namzu/sdk';
 import { FileCheckpointStore } from '../checkpoints/store.js';
-import type { CompactionCliConfig, HooksConfig, MemoryCliConfig, PluginConfig, RunLimitsConfig, SandboxConfig, WebConfig } from '../config/schema.js';
+import type { CompactionCliConfig, HooksConfig, MemoryCliConfig, PluginConfig, SandboxConfig, TurnLimitsConfig, WebConfig } from '../config/schema.js';
 import { type ToolResultScreenConfig } from '../config/tool-result-screens.js';
+import { type SessionDirectories } from '../context/directories.js';
 import { type SandboxSummary } from '../context/sandbox.js';
 import { type ConnectedMcpServer, type FailedMcpServer, type McpServersConfig } from '../integrations/mcp/servers.js';
 import { type CliPluginRuntime } from '../integrations/plugins/runtime.js';
 import { type DetectedProvider, type Preferences, type ProviderId } from '../integrations/providers/index.js';
-import type { ConversationContext } from '../integrations/sessions/store.js';
+import { type ConversationContext } from '../integrations/sessions/store.js';
 import type { SubagentActivity, SubagentActivitySource } from '../integrations/subagents/activity.js';
-import { type OrchestrationRun } from '../integrations/subagents/runs.js';
+import { type Batch } from '../integrations/subagents/batches.js';
+import { type TypedNoteResult } from '../memory/typed.js';
 import type { PermissionMode } from '../permissions/mode.js';
 import { type ModelSwitchOutcome } from './model-switch-tool.js';
 import { type ModelSwitchRequest } from './model-switch.js';
@@ -48,15 +51,15 @@ export type AgentEvent = {
      * way to name the answer it was looking at.
      */
     readonly messageId?: string;
-    /** The run that produced it — a rating names both. */
-    readonly runId?: string;
+    /** The turn that produced it — a rating names both. */
+    readonly turnId?: string;
 } | {
     readonly kind: 'tool-start';
     readonly activity?: 'exploration';
     /** Exact task identity for host-owned wait presentation. */
     readonly taskId?: string;
-    /** Run-scopes provider tool ids, which are not globally unique. */
-    readonly runId?: string;
+    /** Turn-scopes provider tool ids, which are not globally unique. */
+    readonly turnId?: string;
     /** SDK tool-use id — stable across this call's start/end (for tracking). */
     readonly toolUseId: string;
     readonly toolName: string;
@@ -67,7 +70,7 @@ export type AgentEvent = {
     readonly detail?: readonly string[];
 } | {
     readonly kind: 'tool-progress';
-    readonly runId?: string;
+    readonly turnId?: string;
     readonly toolUseId: string;
     readonly toolName: string;
     /** Bounded latest-state text from the executing tool. */
@@ -77,7 +80,7 @@ export type AgentEvent = {
     readonly kind: 'tool-end';
     /** Verbatim retained output, before terminal preview projection. */
     readonly output?: string;
-    readonly runId?: string;
+    readonly turnId?: string;
     readonly toolUseId: string;
     readonly toolName: string;
     readonly isError: boolean;
@@ -101,9 +104,12 @@ export type AgentEvent = {
     readonly done?: boolean;
 } | {
     readonly kind: 'usage';
+    /** The session and turn this spend belongs to. */
+    readonly sessionId?: string;
+    readonly turnId?: string;
     /** Parent and all descendants, reported separately from own usage. */
-    readonly budget?: TokenBudgetSummary;
-    /** CUMULATIVE run spend. Grows every turn; never a context size. */
+    readonly budget?: SessionTokenBudgetSummary;
+    /** CUMULATIVE turn spend. Never a context size. */
     readonly totalTokens: number;
     /**
      * The kernel's cost record, carried whole.
@@ -111,7 +117,7 @@ export type AgentEvent = {
      * This was `costUsd: number`, narrowed from the same object at the
      * mapping site, and the number on its own cannot answer the
      * question the screen asks. A total of zero means two different
-     * things — the run cost nothing, or nobody could price it — and
+     * things — the turn cost nothing, or nobody could price it — and
      * `unpricedTokens` is what separates them. Passing only the total
      * left every surface downstream to guess, and both of them guessed
      * "free".
@@ -131,7 +137,7 @@ export type AgentEvent = {
      * cannot mark an estimated numerator honestly while silently
      * treating an assumed window as measured.
      *
-     * All four absent when the run resolved no window — then there is
+     * All four absent when the turn resolved no window — then there is
      * no proportion to show, only the spend.
      */
     readonly contextTokens?: number;
@@ -142,8 +148,8 @@ export type AgentEvent = {
 /**
  * Context was discarded, or an attempt to discard it declined.
  *
- * Everything else this session fixed was the run quietly not doing what the
- * operator asked. This is the same class with the opposite sign: the run
+ * Everything else this session fixed was the turn quietly not doing what the
+ * operator asked. This is the same class with the opposite sign: the turn
  * quietly doing something they did not ask for. Compaction deletes messages
  * irrecoverably, and the first time a user learned it existed was when the
  * agent had forgotten something they were relying on — which reads as the
@@ -185,16 +191,16 @@ export type AgentEvent = {
     readonly text: string;
 } | {
     readonly kind: 'capability-warning';
-    readonly capability: Extract<RunEvent, {
+    readonly capability: Extract<SessionEvent, {
         type: 'capability_warning';
     }>['capability'];
-    readonly contentSource?: Extract<RunEvent, {
+    readonly contentSource?: Extract<SessionEvent, {
         type: 'capability_warning';
     }>['contentSource'];
     readonly text: string;
 } | {
     readonly kind: 'history-repair';
-    readonly source: Extract<RunEvent, {
+    readonly source: Extract<SessionEvent, {
         type: 'message_history_repaired';
     }>['source'];
     readonly text: string;
@@ -218,45 +224,58 @@ export type AgentEvent = {
  * no reader anywhere in this package. The name was also wrong for what is
  * needed here: a "finish reason" in this codebase is `MessageStopReason`,
  * reported per model message, while the question a caller has at the end of
- * a turn is the run-level `StopReason` — did it answer, or did it run out
+ * a turn is the turn-level `StopReason` — did it answer, or did it run out
  * of budget, iterations, time, or permission to say what it produced.
  */
  | {
     readonly kind: 'done';
+    /** The session and turn that settled. */
+    readonly sessionId?: string;
+    readonly turnId?: string;
     /** Settled kernel result, including an intentionally empty guarded result. */
     readonly text?: string;
     readonly stopReason?: StopReason;
-    readonly budget?: TokenBudgetSummary;
+    readonly budget?: SessionTokenBudgetSummary;
 } | {
-    /** A recoverable run stopped with an addressable checkpoint. */
+    /** A recoverable turn stopped with an addressable checkpoint. */
     readonly kind: 'paused';
-    readonly budget?: TokenBudgetSummary;
-    /** The run that paused: with the checkpoint, what `resumePaused` needs. */
-    readonly runId: string;
+    readonly budget?: SessionTokenBudgetSummary;
+    /** The turn that paused: with the checkpoint, what `resumePaused` needs. */
+    readonly turnId: string;
     readonly checkpointId: string;
     readonly reason: string;
-    readonly failure?: Extract<RunEvent, {
-        type: 'run_paused';
+    readonly failure?: Extract<SessionEvent, {
+        type: 'turn_paused';
     }>['failure'];
-    readonly providerError?: Extract<RunEvent, {
-        type: 'run_paused';
+    readonly providerError?: Extract<SessionEvent, {
+        type: 'turn_paused';
     }>['providerError'];
-    readonly explanation?: Extract<RunEvent, {
-        type: 'run_paused';
+    readonly explanation?: Extract<SessionEvent, {
+        type: 'turn_paused';
     }>['explanation'];
 } | {
     readonly kind: 'error';
-    readonly budget?: TokenBudgetSummary;
+    readonly budget?: SessionTokenBudgetSummary;
     readonly message: string;
-    readonly failure?: Extract<RunEvent, {
-        type: 'run_failed';
+    readonly failure?: Extract<SessionEvent, {
+        type: 'turn_failed';
     }>['failure'];
-    readonly providerError?: Extract<RunEvent, {
-        type: 'run_failed';
+    readonly providerError?: Extract<SessionEvent, {
+        type: 'turn_failed';
     }>['providerError'];
-    readonly explanation?: Extract<RunEvent, {
-        type: 'run_failed';
+    readonly explanation?: Extract<SessionEvent, {
+        type: 'turn_failed';
     }>['explanation'];
+    /**
+     * The conversation already has an active turn, so this one was not
+     * started (`TurnInProgressError`). A paused turn is left to
+     * `resumePaused` or `abandonTurn`; nothing is closed implicitly.
+     */
+    readonly turnInProgress?: {
+        readonly sessionId: string;
+        readonly activeTurnId: string;
+        readonly state: 'running' | 'paused' | 'interrupted';
+    };
 };
 /** A single tool the model wants to run, surfaced to the user for approval. */
 export interface PermissionToolCall {
@@ -265,6 +284,8 @@ export interface PermissionToolCall {
     /** Exact detached input the kernel prepared and the approval covers. */
     readonly input: unknown;
     readonly isDestructive: boolean;
+    /** What the call reaches past the turn's boundary; see `ToolCallSummary.escalation`. */
+    readonly escalation?: ToolCallEscalation;
 }
 /** The batch a person is asked about — the kernel's `ToolReviewRequest`. */
 export type PermissionRequest = ToolReviewRequest;
@@ -290,8 +311,8 @@ export type QuestionAnswer = {
 };
 export type QuestionFn = (question: UserQuestion) => Promise<QuestionAnswer>;
 export interface SendOptions {
-    /** Overrides for this new run and its built-in children; does not change a parked run. */
-    readonly limits?: RunLimitsConfig;
+    /** Overrides for this new turn and its built-in children; does not change a parked turn. */
+    readonly limits?: TurnLimitsConfig;
     readonly signal?: AbortSignal;
     /**
      * Who answers `ask_user_question` this turn. Absent means nobody: the
@@ -326,10 +347,22 @@ export interface SendOptions {
      * Overrides the session default for this turn only.
      */
     readonly permissionMode?: PermissionMode;
-    /** Caller-reserved identity used to correlate this turn before it starts. */
-    readonly runId?: RunId;
-    /** Exact durable admission that makes goal tools visible for this one run. */
+    /**
+     * Caller-reserved identity for this new turn, for a host that has to name
+     * the turn before it starts (a resident step's verifier). Absent: the
+     * kernel mints one, and the session learns it from the turn's first event.
+     */
+    readonly turnId?: TurnId;
+    /** Why this turn exists (a prompt, a goal round, a resident step), recorded on `turn_started`. */
+    readonly origin?: Origin;
+    /** Exact durable admission that makes goal tools visible for this one turn. */
     readonly goalRound?: GoalRoundAuthority;
+    /**
+     * Close an `interrupted` active turn (its process is gone) before this one
+     * begins, as `turn_failed{ interrupted }`. The interactive TUI passes it: it
+     * never resumed an interrupted turn. A paused turn is never closed this way.
+     */
+    readonly abandonInterrupted?: boolean;
     /**
      * Called before a batch of non-read-only tools runs. Resolves with the
      * user's decision. When omitted, prompt mode auto-approves because nobody
@@ -348,7 +381,7 @@ export interface SendOptions {
      * Receives the settled conversation projection exactly as the kernel will
      * replay it on a later turn.
      *
-     * Kept out of `AgentEvent`: `run-stream` writes every event to NDJSON, while
+     * Kept out of `AgentEvent`: `exec --json` writes every event to NDJSON, while
      * this history may contain opaque reasoning signatures/encrypted blocks that
      * belong in provider context and durable state, never a rendered stream.
      */
@@ -356,31 +389,33 @@ export interface SendOptions {
 }
 /** What {@link AgentSession.resumeDurable} needs that the session does not hold. */
 export interface ResumeDurableParams {
+    /** The paused or interrupted turn to continue, and the session it belongs to. */
+    readonly entry: {
+        readonly tenantId: TenantId;
+        readonly projectId: ProjectId;
+        readonly sessionId: SessionId;
+        readonly turnId: TurnId;
+    };
+    /** The session's log; the resumed turn appends to it. */
+    readonly sessionLog: SessionLog;
+    /** Where the turn's checkpoints are. Absent: `<session-id>/checkpoints/` beside the log. */
+    readonly checkpointStore?: SessionCheckpointStore;
     /**
-     * The run to continue, straight out of a durable listing.
-     *
-     * A `DurableRunEntry` IS an addressable run scope, which is why it can be
-     * passed here unreassembled — and why there is no chance of assembling it
-     * wrong.
-     */
-    readonly entry: DurableRunEntry;
-    /** The backend the entry came from. */
-    readonly checkpointStore: CheckpointStore;
-    /**
-     * The fence of the claim this process holds on the run.
-     *
-     * Omit it only for a single-writer host. Present, it rides every durable
-     * write the resumed run makes, so a worker that stalled past its lease
-     * cannot overwrite the record of whoever took the run over.
+     * The lease this process holds on the session (`claimSession`). Present,
+     * every record the resumed turn appends carries its fence, so a worker that
+     * stalled past its lease cannot write over whoever took the session over.
      */
-    readonly claimFence?: FencingToken;
+    readonly lease?: SessionLease;
     readonly signal?: AbortSignal;
 }
 export interface ResumePausedParams {
-    /** The run the `paused` event named. */
-    readonly runId: string;
-    /** The checkpoint the `paused` event named. */
-    readonly checkpointId: string;
+    /** The turn the `paused` event named. */
+    readonly turnId: string;
+    /**
+     * The checkpoint the `paused` event named. Absent: the one an open
+     * decision references, else the newest.
+     */
+    readonly checkpointId?: string;
     readonly signal?: AbortSignal;
 }
 export interface AgentSession {
@@ -393,7 +428,7 @@ export interface AgentSession {
      *
      * Carried on the session rather than re-resolved by whoever asks, because
      * resolving builds a provider — and a second one would answer about a
-     * different sandbox than the one the run is using.
+     * different sandbox than the one the turn is using.
      */
     readonly sandbox: SandboxSummary;
     readonly providerSummary: string | null;
@@ -526,15 +561,15 @@ export interface AgentSession {
      * the runtime to find out.
      */
     readonly agentIds: readonly string[];
-    /** Actual task store of this conversation's current/latest run; absent before a run starts. */
+    /** Task store of this conversation (`<session-id>/tasks/`); absent before a turn starts. */
     readonly currentTaskStore?: () => TaskStore | undefined;
-    /** Forget the selected run when the operator leaves its conversation. Does not delete tasks. */
+    /** Forget the selected store when the operator leaves its conversation. Does not delete tasks. */
     readonly resetTaskStore?: () => void;
     /** Children created in this process, available for the TUI's observational view. */
     readonly subagents?: SubagentActivitySource;
     /**
-     * Children of this conversation's earlier runs, rebuilt from the evidence
-     * they left on disk.
+     * Children of this conversation's earlier turns, rebuilt from their own
+     * session logs.
      *
      * The counterpart of {@link subagents}, which only ever holds what THIS
      * process launched and only until its eighty-agent bound evicts it. Both
@@ -549,17 +584,13 @@ export interface AgentSession {
      */
     readonly savedChildren?: () => Promise<readonly SubagentActivity[]>;
     /**
-     * Finished parent turns this conversation delegated work under, read from
-     * disk — the counterpart of {@link savedChildren} for `/agents runs`,
-     * grouped by parent run rather than flattened to one row per child.
-     *
-     * A run still in flight is never reported here: it belongs to
-     * `liveOrchestrationRuns` over the live monitor's own snapshot instead, the
-     * same split {@link savedChildren} draws against `subagents`. Optional for
-     * the same reason that one is — an embedded session with no evidence on
-     * disk has none to offer.
+     * Batches of delegated work this conversation's turns launched, read from
+     * the session index — the counterpart of {@link savedChildren} for
+     * `/agents batches`, grouped by parent turn rather than flattened to one row
+     * per child. The live half comes from the monitor; `agentsSlashCommand`
+     * merges the two. Optional because a session with no durable log has none.
      */
-    readonly listOrchestrationRuns?: () => Promise<readonly OrchestrationRun[]>;
+    readonly listSavedBatches?: () => Promise<readonly Batch[]>;
     /**
      * Things about this session's configuration the operator must be told, every
      * launch — today, an accepted capability disagreement in the provider chain,
@@ -572,6 +603,29 @@ export interface AgentSession {
      * shown.
      */
     readonly configNotices: readonly string[];
+    /**
+     * Save an operator note (`#note`, `/memory add`) as a typed memory file in
+     * this session's stored memory, default type `project`. Absent on a session
+     * with no store, where notes go to the curated project file as before.
+     */
+    readonly rememberNote?: (text: string, type?: MemoryType) => Promise<TypedNoteResult>;
+    /**
+     * Copy the project's curated bullets into stored memory
+     * (`/memory import-notes`), returning the operator's report. The curated
+     * file is never changed.
+     */
+    readonly importCuratedNotes?: () => Promise<string>;
+    /**
+     * What `/memory` shows of stored memory, and where the files are: `index`,
+     * the always-loaded index uncapped — every active memory someone chose to
+     * keep — and `derived`, the active records runs recorded on their own (the
+     * run promoter, consolidation), which the prompt's index leaves out.
+     */
+    readonly storedMemoryIndex?: () => Promise<{
+        readonly directory: string;
+        readonly index: RenderedMemoryIndex;
+        readonly derived: RenderedMemoryIndex;
+    }>;
     /**
      * Whether "approve all" has been chosen at a prompt during this session.
      *
@@ -605,41 +659,42 @@ export interface AgentSession {
     readonly promptExemptTools: () => readonly string[];
     send(messages: readonly Message[], opts?: SendOptions): AsyncIterable<AgentEvent>;
     /**
-     * Continue a run some OTHER process started, from its durable state.
+     * Continue a turn some OTHER process started, from its session log.
      *
-     * The kernel could always do this — `resumeRun` joins a checkpoint back
-     * to a running loop — and nothing in this package could reach it, because
-     * the half a snapshot cannot carry (the provider client, the tool
-     * registry, the working directory) lives inside this session and had no
-     * way out. So `namzu` could produce durable runs and never pick one up.
+     * The half a checkpoint cannot carry (the provider client, the tool
+     * registry, the working directory) lives inside this session, so this is
+     * the way a drainer continues a parked turn: the SAME session and the SAME
+     * `turnId`, through the kernel's `resumeSession`.
      *
-     * Returns the outcome rather than a stream: `resumeRun` drains the loop
-     * and hands back a settled run, so there is nothing to render as it
-     * happens. A parked run comes back as `awaiting-decision` and is NOT
-     * resumed past — the answer is a human's, not a drainer's.
+     * Returns the outcome rather than a stream: the resumed turn is drained to
+     * settlement. A turn parked on a decision comes back as
+     * `awaiting-decision` and is NOT resumed past — the answer is a human's,
+     * not a drainer's.
      */
     resumeDurable(params: ResumeDurableParams): Promise<ResumeOutcome>;
     /**
-     * Continue THIS session's own run after the provider paused it, from the
-     * checkpoint the pause named, streaming events as the resumed run makes
-     * them.
+     * Continue THIS session's own turn after the provider paused it, from the
+     * checkpoint the pause named, streaming events as the resumed turn makes
+     * them — the same turn id, the same session log.
      *
-     * `resumeDurable` is for a run some other process started and takes the
-     * listing and the store the caller found it in. A pause inside this
-     * session already knows both: the run's scope is this session's and its
-     * checkpoints are in the store the turn wrote to. What a headless caller
-     * lacked was a way to say "wait, then go on" — it could only exit and be
-     * re-prompted from whatever notes the run left behind, losing the run's
-     * own context. A run parked on a human decision is not resumed past: it
-     * comes back as an error naming the fact, because the answer is a
-     * person's.
+     * What a headless caller lacked was a way to say "wait, then go on" — it
+     * could only exit and be re-prompted from whatever notes the turn left
+     * behind, losing its own context. A turn parked on a human decision is not
+     * resumed past: it comes back as an error naming the fact, because the
+     * answer is a person's.
      */
     resumePaused(params: ResumePausedParams): AsyncIterable<AgentEvent>;
+    /**
+     * Close this conversation's paused or interrupted turn without resuming it
+     * (`turn_failed{ error.code: 'abandoned' }`), so the next prompt can begin a
+     * turn. What `/abandon` does. A running turn is refused by the kernel.
+     */
+    abandonTurn?(turnId: TurnId, reason: string): Promise<void>;
     /**
      * Cancel and settle live sends, compactions and durable resumes, then release
      * what the session holds — today, the external tool servers.
      *
-     * A stdio server is a CHILD PROCESS, and closing it while a live run still
+     * A stdio server is a CHILD PROCESS, and closing it while a live turn still
      * owns one of its tools is a use-after-close race. Idempotent, waits for the
      * operations it cancelled, and safe to call on a session that connected
      * nothing. Calls made after close refuse before provider work starts.
@@ -659,7 +714,7 @@ export interface AgentSessionContext {
      *
      *  - the TUI routes into the picker, where the operator can enter a
      *    credential or choose something else;
-     *  - `run`, `run-stream` and `drain` do `probe.preferences ?? defaultPrefs(...)`,
+     *  - `exec`, `exec --json` and `drain` do `probe.preferences ?? defaultPrefs(...)`,
      *    so nulling preferences here would silently move a scripted run onto
      *    whatever else happened to be detected — the opposite of a refusal;
      *  - `createAgentSession` refuses again on its own, which is what keeps those
@@ -717,8 +772,25 @@ export interface AgentSessionOptions {
      * registry and does not restore this fork's activation snapshot.
      */
     readonly toolLoading?: 'eager' | 'deferred';
-    /** Session/thread/project/tenant identity for this run. Minted when absent. */
-    readonly scope?: RunScope;
+    /**
+     * Session/topic/project/tenant identity for this session's turns. Minted
+     * when absent, with the project the working directory's checkout stands
+     * for (`projects/<slug>/project.json`), so the same directory keeps the
+     * same project across sessions.
+     */
+    readonly scope?: SessionScope;
+    /**
+     * The session this agent's turns are recorded into when {@link scope} is
+     * absent: a protocol gateway (ACP) resolves its client's id to a session
+     * first and hands the result here. Ignored when `scope` is given.
+     */
+    readonly sessionId?: SessionId;
+    /**
+     * Who started the session, written into its `session_started` record the
+     * first time a turn runs in it: the protocol and, for a gateway, the
+     * client's own id for it. Absent: `{ protocol: 'cli' }`.
+     */
+    readonly origin?: SessionStartedRecord['origin'];
     /**
      * The directory the agent works in: what every filesystem tool resolves a
      * relative path against and where sub-agents run. Generated task and memory
@@ -727,25 +799,34 @@ export interface AgentSessionOptions {
      * Taken as an argument rather than read from `process.cwd()` at each of
      * those four points, which is what let `--cwd` reach the session store and
      * the skill search and stop there: the caller parsed a directory, the agent
-     * globbed a different one, and the run reported finding nothing rather than
+     * globbed a different one, and the turn reported finding nothing rather than
      * having looked in the wrong place.
      */
     readonly cwd?: string;
     /**
-     * Injected SDK hierarchy root for this host session. When present, runs use
-     * this exact path builder and generated memory/tasks live inside the scoped
-     * Project. Absent preserves the embedded API's historical cwd-local layout.
+     * The application home (`NAMZU_HOME`) this session files its state under:
+     * `projects/<slug>/` for the working directory's checkout. Absent means
+     * `resolveNamzuHome()`. Never the working directory.
      */
     readonly stateRoot?: string;
-    /** Host-owned durable conversations, for run-scoped original evidence retrieval. */
+    /**
+     * Host-owned durable conversations: the layout and index the session's
+     * logs live in, for turn-scoped original evidence retrieval and the
+     * delegation views. Absent: the layout of the working directory's project
+     * under {@link stateRoot}.
+     */
     readonly conversationSessions?: ConversationContext;
+    /**
+     * Keep every turn in memory: an in-memory session log per send, nothing
+     * written under `NAMZU_HOME`. For a stateless host (`exec --json` without
+     * `--session`), whose history arrives with each call.
+     */
+    readonly ephemeral?: boolean;
     /** Earlier settled steps of one resident pursuit, bound before this session starts. */
     readonly residentHistory?: ResidentHistorySource;
     readonly residentToolEvidence?: ResidentToolEvidenceSource;
     /** Host-bound to this resident admission; fresh sends only, never checkpoint resume. */
     readonly residentEvidenceRecall?: PrepareStep;
-    /** False when an enclosing host owns signals and must drain before exiting. */
-    readonly emergencySave?: boolean;
     /**
      * Operator-authored tool rules, already compiled to the kernel's vocabulary.
      *
@@ -768,12 +849,12 @@ export interface AgentSessionOptions {
      * feedback when it is not good enough.
      *
      * A SESSION option rather than a `SendOptions` one, because a gate is a
-     * standing condition on the run — "don't finish until the build passes" —
+     * standing condition on the turn — "don't finish until the build passes" —
      * not a property of one message. Absent leaves the loop byte-identical.
      */
     readonly reviewAnswer?: ReviewAnswer;
     /**
-     * Rejections the reviewer is allowed before the run stops with
+     * Rejections the reviewer is allowed before the turn stops with
      * `answer_rejected`. Absent uses the kernel's default.
      */
     readonly maxAnswerReviews?: number;
@@ -811,22 +892,22 @@ export interface AgentSessionOptions {
     /** See `NamzuCliConfig.compaction`. Absent means the kernel's structured strategy. */
     readonly compaction?: CompactionCliConfig;
     readonly memory?: MemoryCliConfig;
-    /** See `NamzuCliConfig.limits`: how many model calls and tokens one run may spend. */
-    readonly limits?: RunLimitsConfig;
+    /** See `NamzuCliConfig.limits`: how many model calls and tokens one turn may spend. */
+    readonly limits?: TurnLimitsConfig;
     /**
-     * Where this session's run events are recorded, if anywhere.
+     * Where this session's events are recorded, if anywhere.
      *
      * A listener rather than a config: the CLI resolves `@namzu/telemetry`,
      * builds the sink and the redaction chain, and hands the result here
      * already assembled — so this file has no opinion about optional
      * packages, redactors, or what a destination is.
      */
-    readonly onRunEvent?: (event: RunEvent) => void;
+    readonly onSessionEvent?: (event: SessionEvent) => void;
     /** Durable goal authority for the main TUI session; omitted on headless surfaces. */
     readonly sessionGoals?: SessionGoalStore;
     /**
      * Mount host desktop control for a surface that owns an interactive
-     * permission callback. False by default: `run`, `run-stream` and `drain`
+     * permission callback. False by default: `exec`, `exec --json` and `drain`
      * have no human prompt to guard pointer/keyboard input and must not inherit
      * this capability merely because the package is installed.
      */
@@ -921,7 +1002,7 @@ export declare function listProviderModels(id: ProviderId, det: DetectedProvider
     id: string;
     name: string;
 }>>;
-export interface RunScope {
+export interface SessionScope {
     /**
      * The active conversation. Chosen before the conversation is written
      * and never replaced by a provisional value; it changes only when the
@@ -934,14 +1015,7 @@ export interface RunScope {
     readonly tenantId: TenantId;
 }
 /** What `/add-dir` talks to. */
-export interface SessionDirectories {
-    list(): readonly string[];
-    add(path: string): Promise<{
-        readonly added: boolean;
-        readonly path: string;
-        readonly reason?: string;
-    }>;
-}
+export type { SessionDirectories } from '../context/directories.js';
 /**
  * The kernel's review policy with the TUI's prompt behind it.
  *
@@ -951,7 +1025,9 @@ export interface SessionDirectories {
  */
 export declare function makeResumeHandler(approval: {
     all: boolean;
-}, onPermission: PermissionFn | undefined, mode?: PermissionMode, exempt?: (name: string, input: unknown) => boolean): ResumeHandler;
+}, onPermission: PermissionFn | undefined, mode?: PermissionMode, exempt?: (name: string, input: unknown) => boolean, escapePolicy?: {
+    readonly unattendedSandboxEscape?: 'refuse' | 'allow';
+}): ResumeHandler;
 /**
  * Whether a call runs without asking. The kernel's rule: a trusted read-only
  * declaration or a named bookkeeping write, never a fetch, never a tool the
@@ -963,11 +1039,11 @@ export declare function promptExemptToolNames(registry: ToolRegistry): readonly
 /** A batch needs explicit approval when any call mutates state. */
 export declare const batchNeedsPrompt: typeof batchNeedsReview;
 /**
- * Translate one SDK `RunEvent` into the TUI's `AgentEvent` vocabulary, or
+ * Translate one SDK `SessionEvent` into the TUI's `AgentEvent` vocabulary, or
  * `null` for events the chat surface doesn't render (iteration markers,
- * token usage, checkpoints, plan/task lifecycle, …). Pure — unit-tested.
+ * checkpoints, plan lifecycle, …). Pure — unit-tested.
  */
-export declare function toAgentEvent(event: RunEvent, presenter: ToolPresenter): AgentEvent | null;
+export declare function toAgentEvent(event: SessionEvent, presenter: ToolPresenter): AgentEvent | null;
 /**
  * The one presentation function this host keeps.
  *