@namzu/sdk 43.0.0 → 44.0.0

package/dist/runtime/query/index.d.ts

@@ -2,8 +2,10 @@ import type { ContextReducer } from '../../compaction/reducer.js';
 import { type CompactionConfig } from '../../config/runtime.js';
 import type { ProviderChainMember } from '../../provider/fallback.js';
 import type { ProviderRetryConfig } from '../../provider/retry.js';
-import type { TokenBudget } from '../../run/token-budget.js';
-import type { PathBuilder } from '../../session/workspace/path-builder.js';
+import type { SessionPaths } from '../../session/paths.js';
+import type { SessionTokenBudget, SessionTokenBudgetStore } from '../../store/budget/index.js';
+import type { SessionCheckpointStore } from '../../store/checkpoint/index.js';
+import type { SessionLease, SessionLog } from '../../store/session-log/index.js';
 import type { AdvisoryConfig } from '../../types/advisory/index.js';
 import type { AgentRuntimeContext, RuntimeToolOverrides } from '../../types/agent/base.js';
 import type { AgentContextLevel } from '../../types/agent/factory.js';
@@ -11,22 +13,19 @@ import type { WorkingMemoryProvider } from '../../types/agent/working-memory.js'
 import type { AuthorizationGateConfig } from '../../types/authorization/index.js';
 import type { InputGuardrailSpec, OutputGuardrailSpec } from '../../types/guardrail/index.js';
 import { type HITLResumeDecision, type ResumeHandler } from '../../types/hitl/index.js';
-import type { CheckpointId, RunId, SessionId, TenantId } from '../../types/ids/index.js';
+import type { CheckpointId, SessionId, TenantId } from '../../types/ids/index.js';
 import type { InvocationState } from '../../types/invocation/index.js';
 import type { MemoryStore } from '../../types/memory/index.js';
 import { type Message } from '../../types/message/index.js';
 import type { AgentPersona } from '../../types/persona/index.js';
 import type { LLMProvider } from '../../types/provider/index.js';
 import type { TaskRouterConfig } from '../../types/router/index.js';
-import type { ReviewAnswer } from '../../types/run/answer-review.js';
-import type { CheckpointStore, FencingToken } from '../../types/run/checkpoint-store.js';
-import type { RunEventCursor, RunEventReplay } from '../../types/run/event-cursor.js';
-import type { AgentRunConfig, BeforeStep, PrepareStepChain, Run, RunEvent, RunEventListener, StepResult, StopCondition } from '../../types/run/index.js';
-import type { PromoteMemory } from '../../types/run/memory-promotion.js';
-import type { RunStore } from '../../types/run/store.js';
-import type { TokenBudgetStore } from '../../types/run/token-budget-store.js';
 import type { SandboxProvider } from '../../types/sandbox/index.js';
+import type { ReviewAnswer } from '../../types/session/answer-review.js';
 import type { ProjectId, TopicId } from '../../types/session/ids.js';
+import type { BeforeStep, PrepareStepChain, StepResult, StopCondition } from '../../types/session/index.js';
+import { type Origin, type SessionEvent, type SessionEventListener, type SessionLogCursor, type SessionLogReplay, type Turn, type TurnConfig, type TurnForkOrigin, type TurnId } from '../../types/session/index.js';
+import type { PromoteMemory } from '../../types/session/memory-promotion.js';
 import type { Skill } from '../../types/skills/index.js';
 import type { StructuredOutputConfig } from '../../types/structured-output/index.js';
 import type { TaskStore } from '../../types/task/index.js';
@@ -35,7 +34,7 @@ import type { RepairToolCall } from '../../types/tool/repair.js';
 import type { BackoffPolicy } from '../../utils/backoff.js';
 import type { ModelPricing } from '../../utils/cost.js';
 import type { BackgroundJobRegistry } from '../jobs/registry.js';
-import { type SelectedResumeState } from './prepare-run.js';
+import { type SelectedResumeState } from './prepare-turn.js';
 import type { ProjectInstructionContext } from './project-instructions.js';
 import type { PromptCache } from './prompt-cache.js';
 import { PendingAnswers, QuestionParkBinding } from './question-park.js';
@@ -43,10 +42,14 @@ import { type SteeringChannel } from './steering.js';
 export interface QueryParams {
     /** Share observations across turns of one conversation and filesystem; otherwise run-local. */
     fileReadTracker?: import('../../types/tool/index.js').FileReadTracker;
-    /** One account shared with the task scheduler and descendant runs. */
-    budget?: TokenBudget;
-    /** Canonical tree ledger; defaults to disk beside the root run. */
-    tokenBudgetStore?: TokenBudgetStore;
+    /** One ledger shared with the task scheduler and descendant child sessions, keyed by (rootSessionId, rootTurnId). */
+    budget?: SessionTokenBudget;
+    /**
+     * Where root-turn ledgers are kept (`<root-session-id>/budgets/<root-turn-id>.json`).
+     * Absent: beside the session under {@link QueryParams.paths}, or in memory
+     * for an in-memory {@link QueryParams.sessionLog}.
+     */
+    tokenBudgetStore?: SessionTokenBudgetStore;
     /**
      * Notice when the model issues the identical tool call repeatedly, and
      * say so on the next `tool_result`. Defaults on.
@@ -57,7 +60,7 @@ export interface QueryParams {
      */
     repeatCallAdvisory?: boolean;
     /**
-     * Tool names this run may not use, subtracted from its effective list.
+     * Tool names this turn may not use, subtracted from its effective list.
      * See {@link import('../../types/agent/base.js').BaseAgentConfig.deniedTools}.
      */
     deniedTools?: readonly string[];
@@ -68,7 +71,7 @@ export interface QueryParams {
     provider: LLMProvider;
     /**
      * Transient-failure policy for model calls. A single 429 or 503 used to
-     * terminate a run outright — no driver in the estate retries. Defaults
+     * terminate a turn outright — no driver in the estate retries. Defaults
      * to {@link DEFAULT_PROVIDER_RETRY}; pass `false` to opt out (e.g. when
      * the host already wraps the provider with its own policy).
      *
@@ -92,37 +95,18 @@ export interface QueryParams {
      * at full price.
      */
     fallbackProviders?: readonly ProviderChainMember[];
-    /**
-     * Install process-level crash handlers that dump this run's state to
-     * `<runDir>/../emergency/<runId>.json` on SIGINT, SIGTERM or an
-     * uncaught exception. `replay({ fromCheckpoint: 'emergency' })` reads
-     * that file.
-     *
-     * **Off by default, and it must stay that way.** `attach` registers
-     * `process.on(...)` handlers that call `process.exit()`. A library
-     * seizing a host's termination path is an overreach in any embedded
-     * context (an API server has its own drain sequence), and the manager
-     * is a singleton whose `attach` detaches whoever held it before — so
-     * with concurrent runs the last one to start would silently become the
-     * only one that gets saved.
-     *
-     * Turn it on for a process the run owns end-to-end: a CLI, a worker
-     * that handles one run at a time. The handlers are removed when the
-     * run settles.
-     */
-    emergencySave?: boolean;
     /**
      * Durability for questions raised by a tool that closed over its
-     * binding before the run existed.
+     * binding before the turn existed.
      *
      * The built-in `ask_user_question` is built with the agent's tool
      * registry, so only whoever builds the tools can hand it one — that is
-     * what lets a single tool instance be durable inside a run and inert
+     * what lets a single tool instance be durable inside a turn and inert
      * outside one. Without it, THAT tool's park is only a suspended
      * `await`: kill the process while somebody is looking at the card and
      * the answer can never be applied.
      *
-     * Not required for `ToolContext.requestPause`. The run builds that
+     * Not required for `ToolContext.requestPause`. The turn builds that
      * seam per call and binds its own recorder when none is passed, so a
      * pause raised from a host-authored tool is durable on every surface
      * rather than only on the one agent class that supplies this.
@@ -141,37 +125,37 @@ export interface QueryParams {
      * The registry a re-entered `ask_user_question` reads its answer from.
      *
      * Same shape, same reason and same limit as {@link questionParks}: it
-     * exists for a tool that closed over the instance before the run did,
-     * and without it a resumed run re-asks that tool's question. A pause
-     * from `ToolContext.requestPause` needs none, because the run fills
+     * exists for a tool that closed over the instance before the turn did,
+     * and without it a resumed turn re-asks that tool's question. A pause
+     * from `ToolContext.requestPause` needs none, because the turn fills
      * its own on the resume path.
      */
     pendingAnswers?: PendingAnswers;
     /** Default per-tool execution deadline. See {@link ToolDefinition.timeoutMs}. */
     toolTimeoutMs?: number;
     /**
-     * Where background jobs this run starts are held, and killed.
+     * Where background jobs this turn starts are held, and killed.
      *
-     * Host-owned so it can outlive one run — a registry built per run could
-     * never be the thing that kills a run's jobs when the run is already
-     * gone. This run's jobs are torn down in the `finally` below; another
-     * run's are untouched. The registry launches host processes, so a run
+     * Host-owned so it can outlive one turn — a registry built per turn could
+     * never be the thing that kills a turn's jobs when the turn is already
+     * gone. This turn's jobs are torn down in the `finally` below; another
+     * run's are untouched. The registry launches host processes, so a turn
      * that also supplies a {@link sandboxProvider} does not expose it to tools:
      * background execution is refused rather than silently bypassing the sandbox.
      */
     backgroundJobs?: BackgroundJobRegistry;
     /**
-     * Which owner the run's background jobs belong to. Absent, the run id:
-     * jobs are stopped when the run ends. A host that wants a job to
+     * Which owner the turn's background jobs belong to. Absent, the turn id:
+     * jobs are stopped when the turn ends. A host that wants a job to
      * outlive the turn that started it — a dev server started in one turn
      * and read in the next — passes its session id here and calls
-     * `backgroundJobs.killOwner(sessionId)` when the session ends; the run
+     * `backgroundJobs.killOwner(sessionId)` when the session ends; the turn
      * then stops nothing at its end and still tells the model when a job
      * finishes.
      */
     backgroundJobOwner?: string;
     /**
-     * What else goes in this run's prompt.
+     * What else goes in this turn's prompt.
      *
      * `static` and `dynamic` contributions reach the system prompt through
      * `PromptBuilder`; `turn` contributions reach the ephemeral trailing
@@ -183,8 +167,8 @@ export interface QueryParams {
      * Where the `skill` tool loads from.
      *
      * Separate from `skills`, which is the LIST that goes in the prompt
-     * manifest. A run can have the manifest without the tool — that is what
-     * every run did before the tool existed — and the two are wired
+     * manifest. A turn can have the manifest without the tool — that is what
+     * every turn did before the tool existed — and the two are wired
      * independently on purpose: a host may want the guidance visible without
      * granting a way to pull bodies in mid-run.
      */
@@ -192,18 +176,18 @@ export interface QueryParams {
     /**
      * Where a message's stored attachments are resolved from.
      *
-     * Absent is fine for every run whose attachments are inline, which is
-     * every run that existed before this. A message carrying a ref with no
+     * Absent is fine for every turn whose attachments are inline, which is
+     * every turn that existed before this. A message carrying a ref with no
      * store REFUSES rather than dropping the attachment.
      */
     attachmentStore?: import('../../store/attachment/index.js').AttachmentStore;
     /**
-     * Maximum wall-clock time for resolving the run's stored attachments.
+     * Maximum wall-clock time for resolving the turn's stored attachments.
      * Defaults to one minute; `0` retains the prior unbounded wait.
      */
     attachmentResolveTimeoutMs?: number;
     /**
-     * How this run reaches the web.
+     * How this turn reaches the web.
      *
      * `fetch` and `search` are independent, and this kernel ships only the
      * first — see `connector/web` for why choosing a search backend here
@@ -222,11 +206,11 @@ export interface QueryParams {
     toolRetryBackoff?: Partial<BackoffPolicy>;
     /** Max concurrently-executing concurrency-safe tools in one batch. */
     maxToolConcurrency?: number;
-    /** Per-run cumulative tool attempt limit, including nested calls and retries. Unset is unlimited. Re-supply on resume; durable reservations are never refunded. */
+    /** Per-turn cumulative tool attempt limit, including nested calls and retries. Unset is unlimited. Re-supply on resume; durable reservations are never refunded. */
     maxToolCalls?: number;
     /**
      * Model-visible size cap for a single tool result. Over-budget output is
-     * spilled to the run directory and replaced with a head+tail preview
+     * spilled to the turn directory and replaced with a head+tail preview
      * naming the path, so nothing is lost and tokens are paid only if the
      * agent decides the rest is worth re-reading. Set `0` to disable.
      */
@@ -235,9 +219,9 @@ export interface QueryParams {
      * Screens to run against every tool result, where the registry was not
      * built with its own.
      *
-     * This is the run's half of a boundary whose only other door is the
+     * This is the turn's half of a boundary whose only other door is the
      * registry constructor — and a registry is usually the HOST's, assembled
-     * before the run exists, so a run-config option is the only way a run
+     * before the turn exists, so a turn-config option is the only way a turn
      * screens a registry it did not build. A registry built WITH
      * `resultGuardrails` states its own policy and wins, `[]` included.
      *
@@ -280,35 +264,35 @@ export interface QueryParams {
      *
      * Before this the only halt was `GuardCoordinator`, which sees four
      * numeric budgets and never the messages — so a terminal
-     * `submit_answer` tool could not end a run, and the model had to be
+     * `submit_answer` tool could not end a turn, and the model had to be
      * prompt-begged to stop with `maxIterations: 200` as the only backstop.
      *
      * Helpers: `stepCountIs`, `hasToolCall`, `anyOf`.
      */
     stopWhen?: StopCondition;
     /**
-     * Judge the answer the run is about to settle with, and hand it back
+     * Judge the answer the turn is about to settle with, and hand it back
      * with feedback when it is not good enough.
      *
      * `stopWhen` is only consulted after tools have run, so there was no
-     * seam at the point the model stops calling them: the run finalized
+     * seam at the point the model stops calling them: the turn finalized
      * with whatever it had. Verify-then-fix — run the build, feed the
-     * failure back, let it try again — meant starting a new run and
+     * failure back, let it try again — meant starting a new turn and
      * re-supplying the context the first one had already assembled.
      *
      * Bounded by {@link maxAnswerReviews}. Never called on the forced-final
      * turn, which exists to extract a closing summary under pressure.
-     * Exceptions or malformed verdicts fail the run; cancellation stops waiting.
+     * Exceptions or malformed verdicts fail the turn; cancellation stops waiting.
      */
     reviewAnswer?: ReviewAnswer;
     /**
-     * Decide what this run should leave behind when it settles.
+     * Decide what this turn should leave behind when it settles.
      *
      * See {@link PromoteMemory}. Absent means nothing is offered and the
      * run behaves exactly as it did.
      */
     promoteMemory?: PromoteMemory;
-    /** Corrections allowed before the run stops. Nonnegative safe integer; default 3. Consumed rejections survive checkpoints. */
+    /** Corrections allowed before the turn stops. Nonnegative safe integer; default 3. Consumed rejections survive checkpoints. */
     maxAnswerReviews?: number;
     /** Called with each completed step, as it completes. */
     onStepFinish?: (step: StepResult) => void;
@@ -316,11 +300,11 @@ export interface QueryParams {
      * Shape each step before the model is called: narrow the tool surface,
      * swap the model, add one-step guidance, change sampling.
      *
-     * `stopWhen` let a run decide TO STOP from what its steps produced;
+     * `stopWhen` let a turn decide TO STOP from what its steps produced;
      * this is the other half — deciding how the next step should look.
      * Without it, the tool surface and model are fixed at `query()` time,
      * so a phased agent (research with search tools, write with file tools,
-     * verify with a cheaper model) had to be three separate runs, each
+     * verify with a cheaper model) had to be three separate turns, each
      * starting blind to the last one's context.
      *
      * Narrowing `activeTools` costs a prompt-cache prefix, since tools
@@ -329,7 +313,7 @@ export interface QueryParams {
      * `allowed_tools`, and moving `tool_choice` invalidates cached MESSAGE
      * blocks too, which is a strictly worse trade for the same effect.
      *
-     * Fails open — a throw leaves the step with the run's configuration.
+     * Fails open — a throw leaves the step with the turn's configuration.
      */
     prepareStep?: PrepareStepChain;
     /**
@@ -344,7 +328,7 @@ export interface QueryParams {
      */
     structuredOutput?: StructuredOutputConfig;
     /**
-     * Checks run BEFORE the first model call. A block settles the run as
+     * Checks run BEFORE the first model call. A block settles the turn as
      * `input_guardrail` having spent nothing.
      *
      * namzu's three tool gates all point one way — they protect the world
@@ -352,7 +336,7 @@ export interface QueryParams {
      */
     inputGuardrails?: readonly InputGuardrailSpec[];
     /**
-     * Checks run against the FINAL result. A block settles the run as
+     * Checks run against the FINAL result. A block settles the turn as
      * `output_guardrail`; a `rewrite` replaces the text (so a PII policy
      * can redact rather than discard the whole answer).
      *
@@ -362,17 +346,46 @@ export interface QueryParams {
      */
     outputGuardrails?: readonly OutputGuardrailSpec[];
     tools: ToolRegistryContract;
-    runConfig: AgentRunConfig;
+    turnConfig: TurnConfig;
     allowedTools?: string[];
     agentId: string;
     agentName: string;
     workingDirectory?: string;
     /**
      * Directories besides the working directory the file tools may reach,
-     * absolute; a sandboxed run binds each read-write. See
+     * absolute; a sandboxed turn binds each read-write. See
      * `ToolContext.additionalDirectories`.
      */
     additionalDirectories?: readonly string[];
+    /**
+     * What a file tool's path outside `workingDirectory` and
+     * `additionalDirectories` becomes, on a turn with no sandbox.
+     *
+     * `'refuse'` (the default) keeps the boundary a refusal the tool returns.
+     * `'review'` makes it a question asked before the call runs: the call is
+     * marked (`ToolCallSummary.escalation.outsidePaths`), routed to the
+     * turn's review even when its tool only reads and even where an `allow`
+     * rule or a remembered grant would have covered it, and — once approved
+     * — reaches exactly the named paths for that call alone. A `deny` rule
+     * still refuses it. The review's own mode decides it, so a turn whose
+     * policy approves everything approves these too, on the audit record.
+     *
+     * Only tools that declare `pathArgument` are looked at; a sandboxed turn
+     * is never, because the path is not mounted there to be reached.
+     */
+    outsideRootAccess?: 'refuse' | 'review';
+    /**
+     * Whether a call may ask to run outside the turn's sandbox (the shipped
+     * `bash` tool's `dangerously_disable_sandbox`).
+     *
+     * `'refuse'` (the default) refuses every such request. `'review'` routes
+     * it to the turn's review every time; it runs unconfined only when the
+     * decision confirms its id (`HITLResumeDecision.confirmedEscalations`),
+     * which `createReviewHandler` does only after asking a person, or with
+     * `unattendedSandboxEscape: 'allow'`. Every confirmation and refusal is
+     * written to the audit trail.
+     */
+    sandboxEscape?: 'refuse' | 'review';
     pricing?: ModelPricing;
     enableActivityTracking?: boolean;
     messages: Message[];
@@ -384,7 +397,7 @@ export interface QueryParams {
      * out-of-band — typically in a different process.
      *
      * Recording a park makes the request survive a restart; this is what
-     * makes the ANSWER survive one. Without it a resumed run repairs the
+     * makes the ANSWER survive one. Without it a resumed turn repairs the
      * unanswered `tool_use` blocks away and lets the model re-decide, so a
      * human's "yes, delete that row" degrades into "ask the model again and
      * hope it asks for the same thing".
@@ -403,115 +416,125 @@ export interface QueryParams {
      * A park is only worth persisting if a human is actually looking at it:
      * a programmatic handler answers in microseconds, and the iteration
      * gate runs on every iteration, so recording every park unconditionally
-     * would take a long run from one full-history checkpoint write per
+     * would take a long turn from one full-history checkpoint write per
      * iteration to three. Set `0` to record every park (tests, or a host
      * that wants an unconditional audit trail).
      */
     parkRecordDelayMs?: number;
     /**
-     * Span this run should hang off, when it is a delegated one.
+     * Span this turn should hang off, when it is a delegated one.
      *
      * A spawned sub-agent is part of its parent's work, and a trace that
      * shows the delegation is the whole reason to trace a supervisor at
-     * all. Absent for a top-level run, which correctly starts its own root.
+     * all. Absent for a top-level turn, which correctly starts its own root.
      */
     parentSpan?: import('@opentelemetry/api').Span;
-    /** Session scope for the run. Required — every run is attributed to a Session. */
+    /** Session scope for the turn. Required — every turn is attributed to a Session. */
     sessionId: SessionId;
     /**
-     * Topic the Session lives under. Required — every run carries the full
-     * five-layer scope (Tenant → Project → Topic → Session → Run).
+     * Topic the Session lives under. Required — every turn carries the full
+     * five-layer scope (Tenant → Project → Topic → Session → Turn).
      * Denormalized from `session.topicId`; callers build this alongside
      * `sessionId` so the query pipeline never needs a second SessionStore
      * round-trip to recover it.
      */
     topicId: TopicId;
-    /** Long-lived goal scope for the run. Required. */
+    /** Long-lived goal scope for the turn. Required. */
     projectId: ProjectId;
     /** Isolation boundary (Convention #17). Required. */
     tenantId: TenantId;
     /**
-     * Optional path layout override. Defaults to a {@link DefaultPathBuilder}
-     * rooted at `{workingDirectory}/.namzu`. First-call filesystem migration
-     * runs against this builder's root too, so an injected layout never touches
-     * the fallback working-directory store as a side effect.
+     * Where the session lives on disk (`<NAMZU_HOME>/projects/<slug>/…`).
+     * Defaults to `SessionPaths` under `resolveNamzuHome()`. Namzu never writes
+     * under the working directory.
      */
-    pathBuilder?: PathBuilder;
+    paths?: SessionPaths;
     /**
-     * Optional checkpoint persistence override. Absent ⇒ iteration
-     * checkpoints go to the disk layout under the run's output directory
-     * (today's behavior). A host injects a scope-keyed
-     * {@link CheckpointStore} (e.g. Postgres-backed) so mid-turn resume
-     * survives machines that lose their local disk.
+     * Optional checkpoint persistence override. Absent: checkpoint documents go
+     * to `<session-id>/checkpoints/`, or stay in memory for an in-memory
+     * {@link QueryParams.sessionLog}.
      */
-    checkpointStore?: CheckpointStore;
+    checkpointStore?: SessionCheckpointStore;
     /**
-     * The fence of the claim this worker holds on the run, from `claimRun`.
-     *
-     * Presented on every checkpoint the run writes, so a worker that stalled
-     * past its lease is refused rather than writing into a run somebody else
-     * has taken over. Omit it for single-writer deployments, which is what
-     * every run did before claims existed.
-     *
-     * This hop did not exist for a release. The claim, the fence and the
-     * store-side refusal were all built and tested, and no path between a run
-     * and its store carried the number — so every checkpoint a RUN wrote went
-     * out unfenced while the tests, which called the store directly, all
-     * passed. A capability complete except for the wire between its halves
-     * reads exactly like a working one.
-     *
-     * It fences checkpoints and nothing else. {@link QueryParams.runStore}
-     * takes no fence, so two workers that both took one run still overwrite
-     * each other's run record, transcript and report — see the changeset.
+     * The lease this worker holds on the session, from `claimSession`. Every
+     * record the turn appends carries its fence (`gen`), so a worker that
+     * stalled past its lease is refused rather than writing into a session
+     * somebody else has taken over. Absent: `query()` claims the lease itself
+     * and releases it when the turn settles or parks.
      */
-    claimFence?: FencingToken;
+    lease?: SessionLease;
     /**
-     * Where this run records its own evidence — the run record, its messages,
-     * its transcript and its report. Defaults to the disk layout under the
-     * resolved output directory.
-     *
-     * The sibling of {@link QueryParams.checkpointStore}, and it should always
-     * have been one: checkpoints could be pointed at durable storage and the
-     * evidence could not.
+     * The session log this turn appends to. Defaults to the log at
+     * {@link QueryParams.paths}. An `InMemorySessionLog` with no `paths` keeps
+     * the whole session in memory: its checkpoints, its ledger and its child
+     * sessions.
      */
-    runStore?: RunStore;
+    sessionLog?: SessionLog;
     /**
-     * Where a reconnecting consumer left off, so this run's stream can start by
+     * Where a reconnecting consumer left off, so this turn's stream can start by
      * handing back what it missed.
      *
      * The case this serves is the one that exists without a network hop: the
-     * process holding the run died, and the consumer watching it is coming back
-     * to a run that has to be resumed. Pair it with `resumeFromCheckpoint` — or
-     * reach it through {@link import('./resume-run.js').resumeRun}, which is the
+     * process holding the turn died, and the consumer watching it is coming back
+     * to a turn that has to be resumed. Pair it with `resumeFromCheckpoint` — or
+     * reach it through {@link import('./resume-session.js').resumeSession}, which is the
      * surface that does both — and the missed durable events are yielded, in
-     * order, before the resumed run emits anything of its own.
+     * order, before the resumed turn emits anything of its own.
      *
-     * On a run with no log to catch up on the cursor is answered honestly rather
+     * On a turn with no log to catch up on the cursor is answered honestly rather
      * than ignored: a `sinceSeq` above what exists is `cursor_ahead`, not
      * silence.
      *
      * What comes back is message-granular. Streaming deltas are never persisted
-     * — see {@link import('../../types/run/store.js').RunStore.appendEvent} —
+     * — see {@link import('../../types/session/events.js').isEphemeralEvent} —
      * so a late subscriber recovers the assistant text, the tool results and the
      * lifecycle, not the keystroke cadence that produced them.
      */
-    eventCursor?: RunEventCursor;
+    eventCursor?: SessionLogCursor;
     /**
      * What became of {@link QueryParams.eventCursor}.
      *
      * A callback rather than an event on the stream, because the answer is about
-     * the SUBSCRIPTION and not about the run — and rather than a throw, because
-     * a stale cursor is a client's problem and must not be able to stop a run
+     * the SUBSCRIPTION and not about the turn — and rather than a throw, because
+     * a stale cursor is a client's problem and must not be able to stop a turn
      * from continuing. A host that receives `unavailable` re-derives from the
      * transcript; one that receives nothing at all would splice a hole into its
      * state and never know.
      *
-     * Called once, before the run's first event, and only when a cursor was
+     * Called once, before the turn's first event, and only when a cursor was
      * supplied.
      */
-    onEventReplay?: (replay: RunEventReplay) => void;
-    runId?: RunId;
-    parentRunId?: RunId;
+    onEventReplay?: (replay: SessionLogReplay) => void;
+    /**
+     * Continue this turn (with `resumeFromCheckpoint`). Absent: a new turn is
+     * begun, and refused with `TurnInProgressError` when the session already
+     * has an active one.
+     */
+    turnId?: TurnId;
+    /**
+     * Close an `interrupted` active turn — one whose process is gone — with
+     * `turn_failed{interrupted}` before this turn begins, instead of refusing
+     * with `TurnInProgressError`. A running or paused turn is never closed
+     * this way. An interactive host that never resumes an interrupted turn
+     * sets it.
+     */
+    abandonInterrupted?: boolean;
+    /**
+     * Which protocol opened this turn, and the caller-side ids it used
+     * (`turn_started.origin`). A protocol adapter records the client's own
+     * turn id here (`externalTurnId`) rather than making it a namzu id.
+     */
+    origin?: Origin;
+    /**
+     * Present when this session was forked from another session's checkpoint:
+     * written into `session_started.forkedFrom` when the log is started, and
+     * carried on the returned turn. See `prepareForkState`.
+     */
+    forkedFrom?: TurnForkOrigin;
+    /** Present on a child session: the session that delegated it. */
+    parentSessionId?: SessionId;
+    /** Present on a child session: the parent turn whose tool call spawned it. */
+    parentTurnId?: TurnId;
     depth?: number;
     promptCache?: PromptCache;
     contextLevel?: AgentContextLevel;
@@ -521,10 +544,10 @@ export interface QueryParams {
     runtimeContext?: AgentRuntimeContext;
     taskScheduler?: import('../../types/agent/scheduler.js').TaskScheduler;
     /**
-     * Text queued for this run since its last turn, drained at the boundary.
+     * Text queued for this turn since its last turn, drained at the boundary.
      *
      * A callback because the queue belongs to whoever accepts the messages,
-     * and an array captured here would be whatever was queued before the run
+     * and an array captured here would be whatever was queued before the turn
      * started. See `BaseAgentConfig.inboundMessages` for what it closes.
      */
     inboundMessages?: () => import('../../types/message/index.js').Message[];
@@ -536,16 +559,16 @@ export interface QueryParams {
      */
     waitForInbound?: (signal: AbortSignal) => Promise<void>;
     /**
-     * Live project policy for this run. Unlike `inboundMessages`, snapshot
+     * Live project policy for this turn. Unlike `inboundMessages`, snapshot
      * replacement is durable state and never implies another model turn.
      */
     projectInstructionContext?: ProjectInstructionContext;
     /**
      * Where this conversation's durable state lives.
      *
-     * Supplies the permission mode when `runConfig.permissionMode` names
+     * Supplies the permission mode when `turnConfig.permissionMode` names
      * none, and receives the flip when a plan is approved. Absent is the
-     * ordinary case: a run with no topic state behaves exactly as it did.
+     * ordinary case: a turn with no topic state behaves exactly as it did.
      */
     topicStateStore?: import('../../store/topic/state.js').TopicStateStore;
     /**
@@ -567,15 +590,15 @@ export interface QueryParams {
      */
     approvalPolicyName?: string;
     /**
-     * Receive this run's approval-policy box, so it can be swapped mid-run.
+     * Receive this turn's approval-policy box, so it can be swapped mid-run.
      *
      * The box is built HERE rather than passed in, unlike
      * {@link permissionModeRef}, because changing the policy emits a durable
-     * event and only the run holds the emitter. A host that constructed its
+     * event and only the turn holds the emitter. A host that constructed its
      * own box would be able to change the policy without recording it, which
      * is the one thing this must not allow.
      */
-    onApprovalPolicy?: (policy: import('../../types/hitl/policy.js').RunApprovalPolicy) => void;
+    onApprovalPolicy?: (policy: import('../../types/hitl/policy.js').SessionApprovalPolicy) => void;
     /**
      * Where a worker completion goes when no tool call is waiting for it.
      *
@@ -592,23 +615,23 @@ export interface QueryParams {
     advisory?: AdvisoryConfig;
     compactionConfig?: CompactionConfig;
     /**
-     * Where what the run learned is written when it ends: its decisions,
+     * Where what the turn learned is written when it ends: its decisions,
      * discoveries and failures, as one entry tagged `learning`. Episodic
-     * memory (the working state) dies with the run; this is the bridge to
-     * the semantic store a later run searches. Absent means nothing is
-     * written. A store that fails is logged and never fails the run.
+     * memory (the working state) dies with the turn; this is the bridge to
+     * the semantic store a later turn searches. Absent means nothing is
+     * written. A store that fails is logged and never fails the turn.
      */
     consolidateInto?: MemoryStore;
     /**
      * Optional neutral working-memory seam. When set, the iteration loop
      * re-renders the provider's string into a single pinned leading system
      * message every turn (the primacy-edge, compaction-preserved slot).
-     * Absent ⇒ `refreshWorkingMemory` early-returns and the run path is
+     * Absent ⇒ `refreshWorkingMemory` early-returns and the turn path is
      * byte-identical.
      */
     workingMemoryProvider?: WorkingMemoryProvider;
     /**
-     * Replace context reduction for this run.
+     * Replace context reduction for this turn.
      *
      * Outranks `compactionConfig.strategy`, and the built-in structured pass
      * does not also run: two mechanisms editing one history in the same pass
@@ -621,10 +644,10 @@ export interface QueryParams {
     pluginManager?: import('../../plugin/lifecycle.js').PluginLifecycleManager;
     sandboxProvider?: SandboxProvider;
     /**
-     * Maximum time the run waits for sandbox teardown, in milliseconds.
+     * Maximum time the turn waits for sandbox teardown, in milliseconds.
      *
      * Defaults to 30 seconds. A fresh private signal is passed to `destroy()`;
-     * the run also races the returned promise so an implementation that ignores
+     * the turn also races the returned promise so an implementation that ignores
      * cancellation cannot pin `drainQuery()`. Set `0` to retain an unbounded
      * teardown wait.
      */
@@ -639,19 +662,19 @@ export interface QueryParams {
      * explicitly (tool surfaces stripped from prompt + request;
      * attachments left unmapped by the driver). The same policy is checked
      * immediately before every request for image/document blocks produced by a
-     * tool, because those do not exist at run setup. `true`: throw instead of
+     * tool, because those do not exist at turn setup. `true`: throw instead of
      * degrading.
      */
     strictCapabilities?: boolean;
 }
-export declare function query(params: QueryParams): AsyncGenerator<RunEvent, Run>;
+export declare function query(params: QueryParams): AsyncGenerator<SessionEvent, Turn>;
 type DrainQueryParams = Omit<QueryParams, 'resumeHandler'> & {
     resumeHandler?: ResumeHandler;
 };
 export declare function drainQuery(params: Omit<QueryParams, 'resumeHandler'> & {
     resumeHandler?: ResumeHandler;
-}, listener?: RunEventListener): Promise<Run>;
-/** @internal Canonical resume state already selected by `resumeRun`. */
-export declare function drainQueryWithSelectedResumeState(params: DrainQueryParams, state: SelectedResumeState, listener?: RunEventListener): Promise<Run>;
+}, listener?: SessionEventListener): Promise<Turn>;
+/** @internal Canonical resume state already selected by `resumeSession`. */
+export declare function drainQueryWithSelectedResumeState(params: DrainQueryParams, state: SelectedResumeState, listener?: SessionEventListener): Promise<Turn>;
 export {};
 //# sourceMappingURL=index.d.ts.map