@namzu/sdk 43.0.0 → 44.1.0

package/src/types/agent/base.ts

@@ -1,15 +1,18 @@
-import type { TokenBudget } from '../../run/token-budget.js'
 import type { ProjectInstructionContext } from '../../runtime/query/project-instructions.js'
-import type { PathBuilder } from '../../session/workspace/path-builder.js'
+import type { SessionPaths } from '../../session/paths.js'
+import type { SessionTokenBudget } from '../../store/budget/index.js'
+import type { SessionCheckpointStore } from '../../store/checkpoint/index.js'
+import type { SessionLog } from '../../store/session-log/index.js'
 import type { Logger } from '../../utils/logger.js'
-import type { CostInfo, RunExecutionStatus, TokenUsage } from '../common/index.js'
+import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { ResumeHandler } from '../hitl/index.js'
-import type { RunId, SessionId, TenantId } from '../ids/index.js'
+import type { SessionId, TenantId, TurnId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { Message } from '../message/index.js'
 import type { PermissionMode } from '../permission/index.js'
-import type { StopReason } from '../run/stop-reason.js'
 import type { ProjectId, TopicId } from '../session/ids.js'
+import type { StopReason } from '../session/stop-reason.js'
+import type { TurnExecutionStatus } from '../session/turn.js'
 import type { TaskStore } from '../task/index.js'
 import type { ToolAvailability } from '../tool/index.js'
 
@@ -21,11 +24,11 @@ export interface BaseAgentConfig {
 	model: string
 	tokenBudget: number
 	/** Aggregate authority inherited by descendants; supplied independently of the numeric local cap. */
-	budget?: TokenBudget
+	budget?: SessionTokenBudget
 	timeoutMs: number
-	/** See {@link import('../run/config.js').AgentRunConfig.streamIdleTimeoutMs}. */
+	/** See {@link import('../session/config.js').TurnConfig.streamIdleTimeoutMs}. */
 	streamIdleTimeoutMs?: number
-	/** See {@link import('../run/config.js').AgentRunConfig.maxRequestRichContentBytes}. */
+	/** See {@link import('../session/config.js').TurnConfig.maxRequestRichContentBytes}. */
 	maxRequestRichContentBytes?: number
 	/** Maximum stored-attachment materialization time; defaults to one minute. `0` disables. */
 	attachmentResolveTimeoutMs?: number
@@ -34,27 +37,49 @@ export interface BaseAgentConfig {
 	maxResponseTokens?: number
 	costLimitUsd?: number
 	permissionMode?: PermissionMode
+	/**
+	 * Checkpoint retention for this agent's turn. See
+	 * {@link import('../session/config.js').TurnConfig.pruneKeepLast}; absent
+	 * keeps every checkpoint, as before.
+	 */
+	pruneKeepLast?: number
+
+	/**
+	 * The durable layout for this agent invocation: where its session log,
+	 * checkpoints, ledgers and tasks live (`~/.namzu/projects/<slug>/…`).
+	 *
+	 * Absent: `SessionPaths` under `resolveNamzuHome()`, unless
+	 * {@link BaseAgentConfig.sessionLog} is an `InMemorySessionLog`, in which
+	 * case the session writes nothing to disk.
+	 */
+	paths?: SessionPaths
 
 	/**
-	 * Durable run/checkpoint layout for this agent invocation.
+	 * The session log this agent's turns append to. See `QueryParams.sessionLog`.
 	 *
-	 * Absent preserves the kernel default rooted at the run's working
-	 * directory. Hosts with a central application home pass one builder here;
-	 * every concrete agent forwards it to the same `query()` boundary.
+	 * An `InMemorySessionLog` with no `paths` keeps the whole session in
+	 * memory: its checkpoints and its token ledger too, and every child
+	 * session it delegates to (`AgentTaskContext.childStorage`).
 	 */
-	pathBuilder?: PathBuilder
+	sessionLog?: SessionLog
 
 	/**
-	 * Run-level sandbox limits and workspace ownership.
+	 * Where this agent's turns keep their checkpoints. See
+	 * `QueryParams.checkpointStore`.
+	 */
+	checkpointStore?: SessionCheckpointStore
+
+	/**
+	 * Turn-level sandbox limits and workspace ownership.
 	 *
 	 * A provider alone only says HOW commands are confined. This field says
 	 * WHAT it is rooted at; `working-directory` makes sandbox-aware tools act
-	 * on the run's declared workspace instead of a disposable empty tree.
+	 * on the turn's declared workspace instead of a disposable empty tree.
 	 */
-	sandbox?: import('../run/config.js').AgentRunConfig['sandbox']
+	sandbox?: import('../session/config.js').TurnConfig['sandbox']
 
 	/**
-	 * The tools this run may use, narrowing whatever its registry holds.
+	 * The tools this turn may use, narrowing whatever its registry holds.
 	 *
 	 * `allowedTools` existed on `QueryParams` and on `ToolContext` and
 	 * nowhere on the path a delegation takes — so a supervisor handing a
@@ -68,12 +93,12 @@ export interface BaseAgentConfig {
 	 * tools and let it call any of them by name.
 	 */
 	/**
-	 * 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 rather than an array, because the queue is owned by
 	 * whoever accepts the messages — `AgentManager` for a delegated child, a
-	 * host for a top-level run — and an array captured at config time would
-	 * be whatever was queued before the run started.
+	 * host for a top-level turn — and an array captured at config time would
+	 * be whatever was queued before the turn started.
 	 *
 	 * It exists because two public APIs could accept text and silently never
 	 * deliver it. `AgentManager.continueTask` and `queueMessage` pushed onto
@@ -82,7 +107,7 @@ export interface BaseAgentConfig {
 	 * unmounted from the coordinator tools because of it. The steering
 	 * channel had the mirror-image hole: it can only ride on a tool result,
 	 * so guidance queued during a turn that called no tools stayed pending
-	 * until the run ended.
+	 * until the turn ended.
 	 */
 	inboundMessages?: () => import('../message/index.js').Message[]
 
@@ -97,7 +122,7 @@ export interface BaseAgentConfig {
 	 *
 	 * See {@link import('../../runtime/query/index.js').QueryParams.toolResultGuardrails}.
 	 * On the BASE config rather than one agent's, because a delegated child is
-	 * a fresh run with its own executor: a switch that reached this agent and
+	 * a fresh turn with its own executor: a switch that reached this agent and
 	 * not its children would leave the default on in exactly the half a host
 	 * would be trying to change. Absent installs the shipped default; an empty
 	 * array installs none.
@@ -109,14 +134,14 @@ export interface BaseAgentConfig {
 	 * shape as `parentSpan`, `resumeHandler` and `env`. The value it stamps is
 	 * the spawning context's (`AgentTaskContext.toolResultGuardrails`), which
 	 * `SupervisorAgent` fills from this field and the delegation tools fill
-	 * from the run's own `ToolContext`; a spawn that supplies
+	 * from the turn's own `ToolContext`; a spawn that supplies
 	 * `configOverrides.toolResultGuardrails` replaces it rather than merging,
 	 * so a host can still hand one child a different set — including none.
 	 */
 	toolResultGuardrails?: readonly import('../guardrail/index.js').ToolResultGuardrailSpec[]
 
 	/**
-	 * Tools this run may NOT use, subtracted from whatever it would
+	 * Tools this turn may NOT use, subtracted from whatever it would
 	 * otherwise have.
 	 *
 	 * Separate from `allowedTools` because they answer different
@@ -128,15 +153,15 @@ export interface BaseAgentConfig {
 	 */
 	deniedTools?: readonly string[]
 
-	/** Persona for this run, overriding what the agent's definition supplies. */
+	/** Persona for this turn, overriding what the agent's definition supplies. */
 	persona?: import('../persona/index.js').AgentPersona
 
 	/**
-	 * Override the logger this run's `AbstractAgent.bindRun` uses instead of
-	 * the logger the agent was CONSTRUCTED with. Same reason `thinking` and
-	 * `effort` are declared here rather than per-config: every concrete agent
-	 * builds its `runConfig` by hand-listing fields, and a field absent from a
-	 * hand-listed literal is dropped in silence. A host that wants one run's
+	 * Override the logger this turn uses instead of the logger the agent was
+	 * CONSTRUCTED with. Same reason `thinking` and `effort` are declared here
+	 * rather than per-config: every concrete agent builds its `turnConfig` by
+	 * hand-listing fields, and a field absent from a hand-listed literal is
+	 * dropped in silence. A host that wants one turn's
 	 * output routed differently — without reconstructing the agent — sets this.
 	 */
 	logger?: Logger
@@ -149,7 +174,7 @@ export interface BaseAgentConfig {
 	 * **Configuration, not credentials** — and that is a property of the
 	 * CHANNEL rather than a judgement about any particular value. This map is
 	 * copied into every child, is readable by any tool that can run a command,
-	 * and enters a model's context and the run transcript the moment something
+	 * and enters a model's context and the turn transcript the moment something
 	 * echoes it. Nothing here is scoped, redacted, or revocable.
 	 *
 	 * A value that authenticates to a host belongs on the brokered credential
@@ -167,11 +192,11 @@ export interface BaseAgentConfig {
 
 	/**
 	 * Thinking mode and response-effort level for every model call this agent
-	 * makes. See {@link import('../run/config.js').AgentRunConfig} for what
+	 * makes. See {@link import('../session/config.js').TurnConfig} for what
 	 * each one controls and why they are siblings.
 	 *
 	 * They are declared HERE, on the shared base, rather than on each agent
-	 * config that happens to want them. Every agent builds its `AgentRunConfig`
+	 * config that happens to want them. Every agent builds its `TurnConfig`
 	 * by hand-listing fields, and a field absent from a hand-listed literal is
 	 * dropped in silence — which is exactly how `thinking` came to be settable
 	 * only through the raw kernel entry point while every ergonomic one quietly
@@ -200,7 +225,7 @@ export interface BaseAgentConfig {
 	idempotencyKey?: string
 
 	/**
-	 * Long-lived goal scope for the run. Required at runtime — agents reject
+	 * Long-lived goal scope for the turn. Required at runtime — agents reject
 	 * configs missing this (`'X requires sessionId, projectId, and tenantId
 	 * in config'`).
 	 *
@@ -212,7 +237,7 @@ export interface BaseAgentConfig {
 	projectId?: ProjectId
 
 	/**
-	 * Topic the run belongs to. Optional at the TYPE level for the same
+	 * Topic the turn belongs to. Optional at the TYPE level for the same
 	 * reason as `projectId` — {@link AgentManager} stamps this field after
 	 * `configBuilder` returns so `configBuilder` implementations do not
 	 * need to be updated before this tightens. Tightening to required
@@ -220,13 +245,17 @@ export interface BaseAgentConfig {
 	 */
 	topicId?: TopicId
 
-	/** Session under which the run executes. See `projectId` for the tightening plan. */
+	/** Session under which the turn executes. See `projectId` for the tightening plan. */
 	sessionId?: SessionId
 
 	/** Isolation boundary (Convention #17). See `projectId` for the tightening plan. */
 	tenantId?: TenantId
 
-	parentRunId?: RunId
+	/** 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
 
@@ -235,7 +264,7 @@ export interface BaseAgentConfig {
 	/** Shared invocation state passed through agent hierarchies */
 	invocationState?: InvocationState
 
-	/** Span a delegated run hangs off. Absent for a top-level run. */
+	/** Span a delegated session hangs off. Absent for a top-level turn. */
 	parentSpan?: import('@opentelemetry/api').Span
 
 	/**
@@ -299,10 +328,11 @@ export interface AgentInput {
 
 export interface BaseAgentResult {
 	/** Aggregate tree accounting, separate from this invocation's own usage. */
-	budget?: ReturnType<TokenBudget['summary']>
+	budget?: ReturnType<SessionTokenBudget['summary']>
 
-	runId: RunId
-	status: RunExecutionStatus
+	sessionId: SessionId
+	turnId: TurnId
+	status: TurnExecutionStatus
 	stopReason?: StopReason
 	usage: TokenUsage
 	cost: CostInfo
@@ -311,9 +341,9 @@ export interface BaseAgentResult {
 	messages: Message[]
 	result?: string
 	/**
-	 * The schema-validated answer, when the run was configured to produce one.
+	 * The schema-validated answer, when the turn was configured to produce one.
 	 *
-	 * `Run.structuredOutput` has carried this all along and every ergonomic
+	 * `Turn.structuredOutput` has carried this all along and every ergonomic
 	 * boundary above it dropped the value three lines from its caller: an
 	 * archetype's result literal did not copy it, `runAgent` did not even
 	 * forward the config that produces it, and both delegation tools handed a
@@ -322,7 +352,7 @@ export interface BaseAgentResult {
 	 * model re-parse what it had just caused to be serialized.
 	 *
 	 * `unknown` rather than a generic, deliberately. The schema lives on the
-	 * run's config and a result type parameter would have to be threaded
+	 * turn's config and a result type parameter would have to be threaded
 	 * through every archetype, both delegation tools and the task record to
 	 * reach here — and at the delegation boundary the parent does not hold the
 	 * child's schema anyway, so the parameter would be `unknown` again at the

package/src/types/agent/core.ts

@@ -1,4 +1,4 @@
-import type { RunEventListener } from '../run/index.js'
+import type { SessionEventListener } from '../session/events.js'
 import type {
 	AgentCapabilities,
 	AgentInput,
@@ -15,20 +15,20 @@ export interface Agent<
 	readonly type: AgentType
 	readonly metadata: AgentMetadata
 
-	run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>
+	run(input: AgentInput, config: TConfig, listener?: SessionEventListener): Promise<TResult>
 
 	/**
-	 * A shell of this agent that one run may have to itself.
+	 * A shell of this agent that one turn may have to itself.
 	 *
-	 * An agent instance holds per-run state — an abort controller, the id of
-	 * the run in flight — and refuses a second concurrent `run` because of it.
-	 * That refusal is correct for a host calling `run` twice on purpose: two
-	 * overlapping runs would share one abort controller, so cancelling either
-	 * kills both.
+	 * An agent instance holds per-turn state — an abort controller, the id of
+	 * the turn in flight — and refuses a second concurrent `run` call because
+	 * of it. That refusal is correct for a host calling `run` twice on purpose:
+	 * two overlapping turns would share one abort controller, so cancelling
+	 * either kills both.
 	 *
 	 * It is wrong for delegation, which is why this exists. `AgentRegistry`
 	 * hands out ONE instance per registered id, so a fan-out naming the same
-	 * `agent_id` four times drove four runs at one shell: one worked and three
+	 * `agent_id` four times drove four turns at one shell: one worked and three
 	 * died with `ConcurrentInvocationError`. The prescribed remedy — "construct
 	 * a second instance" — was unreachable from there, because the definition
 	 * owns the instance and the caller only has an id.
@@ -37,7 +37,7 @@ export interface Agent<
 	 * falls back to the shared one and the refusal stands, which is loud rather
 	 * than wrong. `AbstractAgent` implements it for every agent built on it.
 	 */
-	forRun?(): Agent<TConfig, TResult>
+	forTurn?(): Agent<TConfig, TResult>
 
 	cancel(): Promise<void>
 	getCapabilities(): AgentCapabilities

package/src/types/agent/delegate.ts

@@ -34,7 +34,7 @@ export interface DelegateRequest {
 	 *
 	 * Forwarded for the reason the `Agent` tool gives for forwarding it to a
 	 * local child: a delegate that cannot see it runs against different
-	 * services than the run that launched it, silently. A remote delegate
+	 * services than the turn that launched it, silently. A remote delegate
 	 * may well ignore it, which is its business.
 	 */
 	readonly env?: Readonly<Record<string, string>>
@@ -45,7 +45,7 @@ export interface DelegateRequest {
  *
  * `status` is the delegate's own answer and is the only authority a foreign
  * delegate has — there is no second layer to cross-check it against the way
- * a local run's `TaskHandle.state` and `BaseAgentResult.status` check each
+ * a local turn's `TaskHandle.state` and `BaseAgentResult.status` check each
  * other. `DelegatingTaskScheduler` maps this onto BOTH so that
  * `taskSucceeded` and `taskFailed` keep working unchanged; that mapping is
  * the whole reason this type is this small.

package/src/types/agent/factory.ts

@@ -13,14 +13,14 @@ export interface AgentDefinition {
 	 * Build a fresh agent for a single spawn.
 	 *
 	 * `typedAgent` is ONE instance, and an instance refuses a second
-	 * concurrent run because it holds per-run state. So a delegation fan-out
+	 * concurrent run because it holds per-turn state. So a delegation fan-out
 	 * naming the same `agent_id` four times ran one child and lost three to
 	 * `ConcurrentInvocationError` — while `create_task`'s own description tells
 	 * a model that exactly this fan-out is the thing to do.
 	 *
 	 * The manager prefers this over `typedAgent` for every spawn. Supply it
 	 * when your agent needs real construction arguments; agents built on
-	 * `AbstractAgent` already get a working default from `Agent.forRun`, so
+	 * `AbstractAgent` already get a working default from `Agent.forTurn`, so
 	 * most hosts need nothing here.
 	 *
 	 * `configBuilder` is not a substitute: it produces a fresh CONFIG per
@@ -76,9 +76,13 @@ export interface AgentFactoryOptions {
 
 	taskRouter?: TaskRouterConfig
 
-	runId?: string
+	sessionId?: string
 
-	parentRunId?: string
+	turnId?: string
+
+	parentSessionId?: string
+
+	parentTurnId?: string
 
 	depth?: number
 }

package/src/types/agent/manager.ts

@@ -1,7 +1,7 @@
-import type { RunId, TaskId } from '../ids/index.js'
+import type { SessionId, TaskId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
-import type { CancelCause } from '../run/cancel-cause.js'
-import type { RunEventListener } from '../run/events.js'
+import type { CancelCause } from '../session/cancel-cause.js'
+import type { SessionEventListener } from '../session/events.js'
 import type { AgentLifecycleListener } from './lifecycle-event.js'
 import type { AgentTask, AgentTaskContext, AgentTaskState, SendMessageOptions } from './task.js'
 
@@ -13,7 +13,7 @@ export interface AgentManagerContract {
 	sendMessage(
 		options: SendMessageOptions,
 		context: AgentTaskContext,
-		listener?: RunEventListener,
+		listener?: SessionEventListener,
 	): Promise<AgentTask>
 
 	cancel(taskId: TaskId, cause?: CancelCause): void
@@ -22,7 +22,7 @@ export interface AgentManagerContract {
 	 * site IS a parent abandoning its children — unlike `AbstractAgent.cancel`,
 	 * where the caller could be anyone.
 	 */
-	cancelAll(parentRunId: RunId, cause?: CancelCause): void
+	cancelAll(parentSessionId: SessionId, cause?: CancelCause): void
 
 	/**
 	 * Queue a message for a running task.
@@ -56,7 +56,7 @@ export interface AgentManagerContract {
 
 	waitForCompletion(taskId: TaskId): Promise<void>
 	getInstance(taskId: TaskId): AgentTask | undefined
-	listByParent(parentRunId: RunId): AgentTask[]
+	listByParent(parentSessionId: SessionId): AgentTask[]
 	listActive(): AgentTask[]
 	getState(taskId: TaskId): AgentTaskState | undefined
 

package/src/types/agent/pipeline.ts

@@ -1,12 +1,13 @@
-import type { TokenBudget } from '../../run/token-budget.js'
-import type { RunId } from '../ids/index.js'
+import type { SessionTokenBudget } from '../../store/budget/index.js'
+import type { SessionId, TurnId } from '../ids/index.js'
 import type { LLMProvider } from '../provider/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 
 export interface StepContext {
 	/** Shared authority; reserve a child scope before invoking another agent. */
-	budget: TokenBudget
-	runId: RunId
+	budget: SessionTokenBudget
+	sessionId: SessionId
+	turnId: TurnId
 	stepIndex: number
 	totalSteps: number
 	previousResults: Map<string, unknown>

package/src/types/agent/reactive.ts

@@ -7,9 +7,8 @@ import type { InputGuardrailSpec, OutputGuardrailSpec } from '../guardrail/index
 import type { ResumeHandler } from '../hitl/index.js'
 import type { AgentPersona } from '../persona/index.js'
 import type { LLMProvider } from '../provider/index.js'
-import type { CheckpointStore } from '../run/checkpoint-store.js'
-import type { BeforeStep, PrepareStepChain, StepResult, StopCondition } from '../run/index.js'
 import type { SandboxProvider } from '../sandbox/index.js'
+import type { BeforeStep, PrepareStepChain, StepResult, StopCondition } from '../session/index.js'
 import type { Skill } from '../skills/index.js'
 import type { StructuredOutputConfig } from '../structured-output/index.js'
 import type { ToolRegistryContract } from '../tool/index.js'
@@ -19,13 +18,13 @@ import type { WorkingMemoryProvider } from './working-memory.js'
 
 export interface ReactiveAgentConfig extends BaseAgentConfig {
 	systemPrompt?: string
-	/** Provider-hosted search for this run; the selected driver must support it. */
+	/** Provider-hosted search for this turn; the selected driver must support it. */
 	webSearch?: { mode: 'live' | 'cached' }
 
 	persona?: AgentPersona
 
 	/**
-	 * Channel a host uses to hand guidance to this run's current turn.
+	 * Channel a host uses to hand guidance to this turn's current turn.
 	 *
 	 * Present here for the same reason it is on `SupervisorAgentConfig`, and
 	 * the reason that file gives twice already: a capability the kernel
@@ -59,7 +58,7 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	/**
 	 * Optional ephemeral sandbox provider. When set, drainQuery creates
 	 * a sandbox via `provider.create()` before the iteration loop and
-	 * routes filesystem / shell tool calls through it; on run end the
+	 * routes filesystem / shell tool calls through it; on turn end the
 	 * SDK calls `sandbox.destroy()`. Hosts that want a per-task
 	 * container shared across supervisor + every child specialist run
 	 * pass the SAME provider instance to all of them — caching layered
@@ -68,6 +67,10 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	sandboxProvider?: SandboxProvider
 	/** See {@link QueryParams.sandboxTeardownTimeoutMs}. */
 	sandboxTeardownTimeoutMs?: number
+	/** See {@link QueryParams.outsideRootAccess}. Default `'refuse'`. */
+	outsideRootAccess?: 'refuse' | 'review'
+	/** See {@link QueryParams.sandboxEscape}. Default `'refuse'`. */
+	sandboxEscape?: 'refuse' | 'review'
 
 	/**
 	 * Optional structured-compaction config. Omitted ⇒ byte-identical run path
@@ -92,7 +95,7 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	 * `AgentManager` spawns and what the estate's own applications call —
 	 * and it forwarded none of them. So a per-tool deadline, a provider
 	 * retry policy, a guardrail, a stop condition: all of it was reachable
-	 * only by dropping down to `query()` and rebuilding the run wiring by
+	 * only by dropping down to `query()` and rebuilding the turn wiring by
 	 * hand. Features that a consumer cannot reach are features that do not
 	 * exist for them.
 	 *
@@ -101,7 +104,6 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	 */
 	resumeHandler?: ResumeHandler
 	retry?: QueryParams['retry']
-	emergencySave?: boolean
 	toolTimeoutMs?: number
 	toolRetryBackoff?: QueryParams['toolRetryBackoff']
 	maxToolConcurrency?: number
@@ -127,11 +129,10 @@ export interface ReactiveAgentConfig extends BaseAgentConfig {
 	structuredOutput?: StructuredOutputConfig
 	inputGuardrails?: readonly InputGuardrailSpec[]
 	outputGuardrails?: readonly OutputGuardrailSpec[]
-	checkpointStore?: CheckpointStore
 
 	/**
-	 * Span this run should hang off, when it is a delegated one. Absent for
-	 * a top-level run, which correctly starts its own root trace.
+	 * Span this turn should hang off, when it is a delegated one. Absent for
+	 * a top-level turn, which correctly starts its own root trace.
 	 */
 	parentSpan?: import('@opentelemetry/api').Span
 }

package/src/types/agent/router.ts

@@ -14,7 +14,7 @@ export interface RoutingDecision {
 	 * Tokens the routing call itself spent, summed over any retries.
 	 *
 	 * Routing runs before the delegate's run exists, so it has no
-	 * `RunPersistence` to accumulate into. Reporting it here lets the
+	 * `TurnRecorder` to accumulate into. Reporting it here lets the
 	 * router report its own model usage. The separate budget summary includes
 	 * both routing and every delegated descendant.
 	 */

package/src/types/agent/scheduler.ts

@@ -1,8 +1,8 @@
-import type { TokenBudget } from '../../run/token-budget.js'
+import type { SessionTokenBudget } from '../../store/budget/index.js'
 import type { TaskId } from '../ids/index.js'
 import type { AgentPersona } from '../persona/index.js'
-import type { CancelCause } from '../run/cancel-cause.js'
-import type { RunEventListener } from '../run/events.js'
+import type { CancelCause } from '../session/cancel-cause.js'
+import type { ChildSessionLifecycleEvent, SessionEventListener } from '../session/events.js'
 import type { AgentRuntimeContext, BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentTaskState } from './task.js'
 
@@ -36,16 +36,16 @@ export interface CreateTaskOptions {
 	readonly beforeStart?: () => Promise<void>
 
 	/**
-	 * Observe events from this one delegated run when the scheduler can expose
+	 * Observe events from this one delegated session when the scheduler can expose
 	 * them.
 	 *
 	 * The built-in local scheduler supports this without replacing its
 	 * scheduler-wide listener. Delivery is observational and must not
-	 * backpressure or decide the child run; a remote/custom scheduler may omit
+	 * backpressure or decide the child session; a remote/custom scheduler may omit
 	 * it when that transport has no event stream. Callers must therefore settle
 	 * their task view from the returned {@link TaskHandle} as well.
 	 */
-	readonly onEvent?: RunEventListener
+	readonly onEvent?: SessionEventListener
 
 	/**
 	 * Span the spawned run should hang off — normally the executing tool's
@@ -62,9 +62,9 @@ export interface CreateTaskOptions {
 	 * Display grouping for the delegated child, carried onto its
 	 * `agent_pending` event so a consumer watching from outside this process
 	 * can group the child the way this caller meant. Reach, not durability:
-	 * that event goes straight to a host's listener and enters no run's log,
+	 * that event goes straight to a host's listener and enters no session log,
 	 * so nothing here is persisted by the kernel. See the `agent_pending`
-	 * variant in `types/run/events.ts` for the full contract.
+	 * variant in `types/session/events.ts` for the full contract.
 	 *
 	 * These fields are display annotations only; they do not create
 	 * dependencies, barriers, or serial execution. The kernel reads none of
@@ -119,7 +119,7 @@ export interface CreateTaskOptions {
 	 *
 	 * **This was accepted and dropped.** `LocalTaskScheduler.createTask` built
 	 * its own `configOverrides` object out of `parentSpan` alone and never
-	 * read this field, so a caller pinning a delegated run to a cheaper model
+	 * read this field, so a caller pinning a delegated session to a cheaper model
 	 * got the agent's default model and no indication otherwise. It is
 	 * forwarded now, with the dedicated {@link parentSpan} option winning if
 	 * both name a span, since that one is the specific field for the job.
@@ -134,7 +134,7 @@ export interface CreateTaskOptions {
 
 export interface TaskScheduler {
 	/** Authority under which this scheduler reserves and meters child execution. */
-	readonly budget?: TokenBudget
+	readonly budget?: SessionTokenBudget
 
 	createTask(options: CreateTaskOptions): Promise<TaskHandle>
 
@@ -144,7 +144,7 @@ export interface TaskScheduler {
 
 	/**
 	 * Stop one task. A cause is relative to the child: a blocking delegation
-	 * abandoned by the run that launched it is cancelled by its `parent`.
+	 * abandoned by the turn that launched it is cancelled by its `parent`.
 	 *
 	 * Optional so existing host schedulers remain structurally compatible. A
 	 * scheduler that can preserve the cause should carry it to the task's abort
@@ -199,4 +199,21 @@ export interface TaskScheduler {
 	 * about it is not the child speaking.
 	 */
 	onTaskProgress?(callback: (taskId: TaskId) => void): () => void
+
+	/**
+	 * Tell me when a child session this gateway launched starts, messages or
+	 * goes idle, as the `child_session_*` events its manager emits.
+	 *
+	 * The parent turn records these into its own session log — the
+	 * `child_session_spawned` record, and `child_session_ended` when the
+	 * child goes idle — so a finished delegation can be listed and replayed
+	 * from the parent's log after the process is gone. A host listener given
+	 * to the gateway sees the same events for display; this is the channel
+	 * the kernel reads them on.
+	 *
+	 * OPTIONAL for the same reason as {@link onTaskProgress}: a host gateway
+	 * that cannot observe its children still works, and its parent log simply
+	 * names no children.
+	 */
+	onChildSessionEvent?(callback: (event: ChildSessionLifecycleEvent) => void): () => void
 }