@robota-sdk/agent-interface-session 3.0.0-beta.81

package/dist/node/session-contracts-BVCzd3uY.d.ts

@@ -0,0 +1,669 @@
+import { IActionRequest, IContextWindowState, IHistoryEntry, IToolExecutionResult, IToolSchema, TActionResponse, TToolArgs, TToolParameters, TUniversalMessage, TUniversalValue } from "@robota-sdk/agent-core";
+import { IUsageSnapshot, TUsageSurface } from "@robota-sdk/agent-interface-analytics";
+import { ICommandListEntry, ICommandResult, TCommandInvocationSource, TCommandUiIntent } from "@robota-sdk/agent-interface-command";
+import { IBackgroundJobGroupCreateRequest, IBackgroundJobGroupState, IBackgroundTaskInput, IBackgroundTaskListFilter, IBackgroundTaskLogCursor, IBackgroundTaskLogPage, IBackgroundTaskState, IExecutionWorkspaceEvent, IExecutionWorkspaceSnapshot, IExecutionWorkspaceSnapshotOptions, ISubagentJobState, TBackgroundJobGroupEvent, TBackgroundTaskEvent, TBackgroundTaskIsolation } from "@robota-sdk/agent-interface-execution";
+//#region src/compact-contracts.d.ts
+type TCompactTrigger = 'manual' | 'auto';
+interface ICompactEvent {
+  trigger: TCompactTrigger;
+  before: IContextWindowState;
+  after: IContextWindowState;
+}
+//#endregion
+//#region src/session-loop-contracts.d.ts
+/** A self-paced loop's durable lifecycle, independent of its disposable wake timer. */
+type TSessionLoopPhase = 'waiting' | 'pending' | 'running' | 'stopped' | 'expired';
+/** Session-owned state needed to resume without replaying an uncertain iteration. */
+interface ISessionLoopState {
+  loopId: string;
+  instruction: string;
+  /** Omitted prompts are re-resolved by the host before each iteration. */
+  useDefaultPrompt?: boolean;
+  createdAt: string;
+  expiresAt: string;
+  /** Monotonic change counter, used to reconcile an ambiguous store write. */
+  revision: number;
+  /** Incremented whenever a new opportunity to run is committed. */
+  generation: number;
+  phase: TSessionLoopPhase;
+  /** Required while waiting; absent once that opportunity has been consumed. */
+  nextAllowedAt?: string;
+  /** Last committed choice, in the 1 minute–1 hour self-paced range. */
+  delaySeconds?: number;
+  reason?: string;
+  /** Once consumed, an omitted decision cannot produce another fallback. */
+  fallbackUsed: boolean;
+  terminalReason?: string;
+}
+//#endregion
+//#region src/prompt-file-reference-types.d.ts
+/**
+ * Leaf type module for {@link IPromptFileReferenceRecord}.
+ *
+ * Split out of `event-contracts.ts` so `turn-contracts.ts` can depend on this type without
+ * importing the whole of `event-contracts.ts` (which imports from `session-contracts.ts`, which in
+ * turn imports from `turn-contracts.ts`) — that previously created an import cycle.
+ */
+type TPromptFileReferenceReason = 'manual' | 'prompt-reference';
+interface IPromptFileReferenceRecord {
+  originalReference: string;
+  sourcePath: string;
+  relativePath: string;
+  reason: TPromptFileReferenceReason;
+  depth: number;
+  byteLength: number;
+}
+//#endregion
+//#region src/event-contracts.d.ts
+type TSkillActivationSource = 'skill' | 'plugin';
+type TSkillActivationInvocation = 'user-slash' | 'model-tool';
+type TSkillActivationMode = 'inject' | 'fork';
+type TSkillActivationStatus = 'started' | 'completed' | 'failed';
+interface ISkillActivationEvent {
+  readonly type: 'skill-activation';
+  readonly skillName: string;
+  readonly source: TSkillActivationSource;
+  readonly invocation: TSkillActivationInvocation;
+  readonly mode: TSkillActivationMode;
+  readonly status: TSkillActivationStatus;
+  readonly timestamp: string;
+  readonly qualifiedName?: string;
+  readonly error?: string;
+}
+type TMemoryType = 'user' | 'feedback' | 'project' | 'reference';
+interface IMemoryReference {
+  topic: string;
+  path: string;
+  score: number;
+  truncated: boolean;
+}
+interface IMemoryEvent {
+  type: 'memory_candidate_extracted' | 'memory_candidate_queued' | 'memory_candidate_saved' | 'memory_candidate_skipped' | 'memory_candidate_approved' | 'memory_candidate_rejected' | 'memory_retrieved';
+  at: string;
+  candidateId?: string;
+  topic?: string;
+  reason?: string;
+  data?: Record<string, TUniversalValue>;
+}
+type TContextReferenceLoadType = 'manual' | 'prompt-reference' | 'system';
+type TContextReferenceStatus = 'active' | 'observed';
+interface IContextReferenceItem {
+  id: string;
+  sourcePath: string;
+  relativePath: string;
+  originalReference: string;
+  loadType: TContextReferenceLoadType;
+  status: TContextReferenceStatus;
+  byteLength: number;
+  loadedAt: string;
+  lastUsedAt?: string;
+}
+//#endregion
+//#region src/tool-summary-types.d.ts
+/**
+ * Leaf type module for {@link IToolSummary}.
+ *
+ * Split out of `session-contracts.ts` so `turn-contracts.ts` can depend on this type without
+ * importing back from `session-contracts.ts` (which imports `IExecutionResult`/`TTurnSource` from
+ * `turn-contracts.ts`) — that previously created an import cycle between the two.
+ */
+interface IToolSummary {
+  name: string;
+  args: string;
+}
+//#endregion
+//#region src/turn-contracts.d.ts
+/**
+ * RUNTIME-003: the identity of one submission, handed back to whoever made it.
+ *
+ * Without this a subscriber has only the session-global `complete` / `interrupted` / `error` events,
+ * which say that A turn ended and never which one. Two callers listening at once are answered by
+ * whichever fires first — measured in the MCP adapter, where the second `submit` was handed the
+ * running turn's response as its own.
+ *
+ * `completed` ALWAYS settles, and that is the part worth stating. A session runs one turn at a time
+ * and queues the rest, and a queued submission does not always get to run: the co-drive queue
+ * coalesces a same-driver entry into the one behind it and drops at capacity. A handle that only
+ * settled for submissions that ran would leave the others waiting forever, which is the hang this
+ * type exists to make impossible — so a submission that never runs REJECTS with `TurnNotRunError`
+ * and says which of those happened.
+ */
+interface ITurnHandle {
+  /** Minted when the submission is accepted, and kept if it waits in the queue before running. */
+  readonly turnId: string;
+  /** Resolves with THIS submission's result; rejects with `TurnNotRunError` if it never ran. */
+  readonly completed: Promise<IExecutionResult>;
+}
+/** Why a submission never became a turn. */
+type TTurnNotRunReason =
+/** A later same-driver input replaced it in the queue (tail-coalesce). */
+'coalesced' |
+/** The queue was at capacity when it arrived. */
+'dropped' |
+/**
+ * The queue was cleared before it ran — abort, cancel, or session shutdown.
+ *
+ * A separate `'shutdown'` member was declared here and never produced: shutdown clears the queue
+ * through the same `clearPendingQueue`, so every entry it discards is already reported as
+ * cancelled. Review found it, and a vocabulary member no code path can emit is a promise to the
+ * consumer that nothing keeps — it would have them writing a branch that never runs.
+ */
+'cancelled';
+/**
+ * The error a rejected `ITurnHandle.completed` carries.
+ *
+ * Declared as a SHAPE here and constructed in `@robota-sdk/agent-framework`, because an interface
+ * package is inert by rule — no classes, no runtime dependency edges. A consumer narrows on `name`
+ * and reads `reason`; it does not need the constructor to do that.
+ */
+interface ITurnNotRunError extends Error {
+  readonly name: 'TurnNotRunError';
+  readonly turnId: string;
+  readonly reason: TTurnNotRunReason;
+}
+/**
+ * Is this rejection the declared "the turn never ran" outcome, or a real failure?
+ *
+ * The narrowing the comment above prescribes, written ONCE. A consumer that catches
+ * `completed`'s rejection has two different things in hand: an ordinary refusal, which it should
+ * report to its caller as an outcome, and an exception from inside a turn, which it should let
+ * surface. Review found the MCP adapter flattening both into a soft tool error and so hiding real
+ * bugs behind a message that reads like a queue decision.
+ *
+ * A pure predicate over a shape — no class, no runtime dependency edge, the same category as the
+ * event readers this package already exports. Each consumer spelling `error.name ===
+ * 'TurnNotRunError'` for itself is how a second spelling of the same question appears, and then
+ * disagrees.
+ */
+declare function isTurnNotRunError(error: unknown): error is ITurnNotRunError;
+/** Result of a completed prompt execution. */
+interface IExecutionResult {
+  response: string;
+  /** Present only when an aborted turn resolved with a partial result; never a successful reply. */
+  interrupted?: true;
+  history: IHistoryEntry[];
+  toolSummaries: IToolSummary[];
+  contextState: IContextWindowState;
+  usage?: IUsageSnapshot;
+  promptFileReferences?: IPromptFileReferenceRecord[];
+}
+/**
+ * Origin of a turn — a human prompt, an agent-wakeup re-entry (FLOW-002), another session's
+ * message (PEER-002, #1809), or a host-admitted external event (#1997).
+ *
+ * `'peer'` is a MEMBER rather than something a caller encodes into the prompt text, because #1809
+ * requires a peer message to reach the runtime with EXPLICIT origin: an agent answering a peer must
+ * be able to tell that it is answering a peer rather than its own operator, and prose inside the
+ * input is not something code can branch on. WHICH peer it was travels in `driverId`, which stays
+ * display attribution and never becomes an authorization input.
+ *
+ * Declared here rather than in `session-contracts.ts`, where it used to live: that file is at its
+ * size ratchet and the rule is to split rather than extend, and turn origin belongs to turn identity
+ * — the same reasoning that created this file.
+ */
+type TTurnSource = 'user' | 'agent-wakeup' | 'peer' | 'external';
+//#endregion
+//#region src/driver-contracts.d.ts
+/**
+ * REMOTE-014 E5 co-drive attribution: a stable, SERVER-ASSIGNED id for the driver of an input/turn. It is
+ * DISPLAY/ATTRIBUTION ONLY — never an authorization input (the OWNER PRINCIPLE, REMOTE-006, governs
+ * authorization; remote == local). Remote = the E3 `deviceId`; local = {@link OWNER_DRIVER_ID}; an
+ * agent-wakeup/goal turn = {@link AGENT_DRIVER_ID}.
+ */
+type TDriverId = string;
+/** The local operator ("owner") driver id — the default for a human turn with no explicit driver. */
+declare const OWNER_DRIVER_ID: TDriverId;
+/** The reserved driver id for an autonomous (wakeup/goal/agent-initiated) turn — never the owner. */
+declare const AGENT_DRIVER_ID: TDriverId;
+/** REMOTE-014 E5: options for `submit` — carries the SERVER-ASSIGNED driver id for co-drive attribution. */
+interface ISubmitOptions {
+  /** Cancels only this submission, including while queued or preparing its turn. */
+  readonly signal?: AbortSignal;
+  readonly driverId?: TDriverId;
+  /** Trusted product surface that accepted this turn; independent from the driver's identity. */
+  readonly surface?: TUsageSurface;
+  /**
+   * PEER-002 (#1809): where this turn came from, when it is not an ordinary user prompt.
+   *
+   * Carried here beside `driverId` because it is the same KIND of fact and travels with it: both
+   * describe the turn's origin, both are set by whoever accepted the submission, and neither is an
+   * authorization input. What stops a caller from simply declaring itself a peer is not this field
+   * — it is that a `'peer'` turn is REFUSED unless it also names the peer's driver id, so the
+   * origin cannot be claimed without also being attributed.
+   */
+  readonly turnSource?: TTurnSource;
+  /**
+   * Called once, synchronously, the moment the submission is accepted — queued behind a running
+   * turn or about to run — with the handle `submit` will later resolve to.
+   *
+   * `submit` on an idle session resolves only after the turn it started has finished, so a caller
+   * that must answer as soon as the input is taken (a peer's delivery ack) cannot learn acceptance
+   * from the returned promise. It must not throw: the turn is already accepted when it runs.
+   */
+  readonly onAccepted?: (handle: ITurnHandle) => void;
+  /** A `'peer'` turn only: which message it answers and where an answer to it goes. */
+  readonly peer?: IPeerTurnContext;
+}
+/**
+ * What a peer turn needs beyond who sent it: the route of the answer. Set by the host that admitted
+ * the message, never taken from it. A reply goes to `replyTo` and names `messageId`, so the model can
+ * answer only the session that asked, and the asker can thread the answer. It grants nothing: what
+ * the turn may do is the session's ordinary permissions' to decide.
+ */
+interface IPeerTurnContext {
+  /** The id of the message this turn answers. */
+  readonly messageId: string;
+  /** The session id a reply goes to: the sender's. */
+  readonly replyTo: string;
+}
+/**
+ * CMD-004 Phase 2: a command-issued UI intent, emitted as a fire-and-forget `ui_intent` session
+ * event. Routed to the REQUESTING surface: `requesterDriverId` is stamped from the command-origin
+ * driver id passed into `executeCommand` (the REMOTE-014 E5 server-assigned id for remote surfaces;
+ * the active turn's driver only as a fallback for model-invoked commands). Other surfaces ignore it;
+ * an intent needs no answer (no parking, no response promise). Serializable.
+ */
+interface IUiIntentEvent {
+  intent: TCommandUiIntent;
+  /** The server-assigned driver id of the surface that issued the command (routing/display-only). */
+  requesterDriverId?: TDriverId;
+}
+/**
+ * CMD-004 Phase 2: the session was renamed (host-executed `session-rename` action). Broadcast so
+ * every attached surface — including co-driving ones — updates its title. Serializable.
+ */
+interface ISessionRenamedEvent {
+  name: string;
+}
+//#endregion
+//#region src/session-event-map.d.ts
+/** Permission handler result — SDK-owned type (mirrors agent-sessions TPermissionResult).
+ *  true = allow, false = deny, 'allow-session' = allow and remember for this session,
+ *  'allow-project' = allow and persist to the project's local settings (location owned by the consuming layer). */
+type TPermissionResultValue = boolean | 'allow-session' | 'allow-project';
+/** A single diff line for Edit tool display. */
+interface IDiffLine {
+  type: 'add' | 'remove' | 'context' | 'hunk';
+  text: string;
+  lineNumber: number;
+}
+/** Tool execution state visible to clients. */
+interface IToolState {
+  toolName: string;
+  firstArg: string;
+  isRunning: boolean;
+  result?: 'success' | 'error' | 'denied';
+  diffLines?: IDiffLine[];
+  diffFile?: string;
+  toolResultData?: string;
+  executionId?: string;
+}
+/** Permission handler delegate — clients provide their own UI. */
+type TInteractivePermissionHandler = (toolName: string, toolArgs: TToolArgs) => Promise<TPermissionResultValue>;
+/**
+ * REMOTE-007 (B4-2a) — transport-neutral permission/ask.
+ *
+ * The session emits a pending-prompt event and awaits a `resolve*(id)` reply instead of invoking a
+ * single injected callback, so ANY attached surface (local TUI, a WS/WebRTC driver, a web UI) can
+ * render + answer the SAME prompt. `id` correlates the emit with its resolve; the session parks the
+ * awaiting promise and the first `resolvePermission`/`resolveAsk(id, …)` settles it (later resolves for
+ * a settled id are no-ops). `prompt_resolved` lets a co-driving second surface dismiss a prompt the
+ * first already answered.
+ */
+/** A tool call awaiting a permission decision. Serializable — crosses the transport boundary unchanged. */
+interface IPermissionRequestEvent {
+  id: string;
+  toolName: string;
+  toolArgs: TToolArgs;
+  /** Whether this session can durably persist a project-scoped approval. */
+  canPersistProjectPermission?: boolean;
+  /** REMOTE-014 E5: the driver whose turn raised this prompt (display-only). */
+  requesterDriverId?: TDriverId;
+}
+/** An "ask the user" request (command- or tool-issued) awaiting an answer. Serializable. */
+interface IAskRequestEvent {
+  id: string;
+  request: IActionRequest;
+  /** REMOTE-014 E5: the driver whose turn raised this prompt (display-only). */
+  requesterDriverId?: TDriverId;
+}
+/** A pending prompt (permission or ask) that has been settled — attached surfaces dismiss it. */
+interface IPromptResolvedEvent {
+  id: string;
+  /** REMOTE-014 E5: the driver who answered the prompt (server-assigned; display-only). */
+  answererDriverId?: TDriverId;
+}
+/** Emitted when a context file is found stale and re-read before a turn. */
+interface IContextFileRefreshedEvent {
+  filePath: string;
+}
+/** SELFHOST-007: a checkpoint/branch lifecycle transition a surface renders. */
+type TCheckpointEventKind = `checkpoint_${'created' | 'restored' | 'rolled_back'}`;
+type TBranchEventKind = `branch_${'forked' | 'switched'}`;
+interface IBranchEvent {
+  kind: TCheckpointEventKind | TBranchEventKind;
+  /** The checkpoint id the transition concerns. */
+  checkpointId: string;
+  /** The branch the checkpoint belongs to (or was switched/forked to). */
+  branchId: string;
+}
+/**
+ * SELFHOST-007: the persisted active-branch pointer — added to the resumable session record (beside
+ * `goal`) so a branch survives `--resume`. Pure data. The branch TREE persists in the agent-framework
+ * checkpoint manifest; a resume whose pointer references a `branchId`/`checkpointId` absent from that
+ * manifest store must degrade gracefully (fall back to the linear HEAD), not crash.
+ */
+interface IActiveBranchPointer {
+  branchId: string;
+  checkpointId: string;
+}
+/** Events emitted by InteractiveSession. */
+interface IInteractiveSessionEvents {
+  text_delta: (delta: string) => void;
+  tool_start: (state: IToolState) => void;
+  tool_end: (state: IToolState) => void;
+  thinking: (isThinking: boolean) => void;
+  complete: (result: IExecutionResult) => void;
+  error: (error: Error) => void;
+  context_update: (state: IContextWindowState) => void;
+  compact: (event: ICompactEvent) => void;
+  interrupted: (result: IExecutionResult) => void;
+  skill_activation: (event: ISkillActivationEvent) => void;
+  background_task_event: (event: TBackgroundTaskEvent) => void;
+  background_job_group_event: (event: TBackgroundJobGroupEvent) => void;
+  execution_workspace_event: (event: IExecutionWorkspaceEvent) => void;
+  user_message: (content: string) => void;
+  /** Emitted at the start of each turn with its origin (human prompt vs agent-wakeup, FLOW-002). */
+  turn_source: (source: TTurnSource) => void;
+  /** Emitted when a context file (AGENTS.md or CLAUDE.md) is refreshed due to staleness. */
+  context_file_refreshed: (event: IContextFileRefreshedEvent) => void;
+  /** Emitted for every automatic-memory pipeline event (capture, approval, retrieval). */
+  memory_event: (event: IMemoryEvent) => void;
+  /** Emitted on every autonomous goal lifecycle transition (start, per-iteration, stop) — GOAL-001. */
+  goal_event: (event: IGoalEvent) => void;
+  /** Emitted on every plan-mode lifecycle transition (created, approved, reverted) — SELFHOST-002. */
+  plan_event: (event: IPlanApprovalEvent) => void;
+  /** Emitted after every persisted checkpoint/branch transition — SELFHOST-007. */
+  branch_event: (event: IBranchEvent) => void;
+  /** REMOTE-007: a tool call awaits a permission decision; answer via `resolvePermission(id, …)`. */
+  permission_request: (event: IPermissionRequestEvent) => void;
+  /** REMOTE-007: an "ask the user" request awaits an answer; answer via `resolveAsk(id, …)`. */
+  ask_request: (event: IAskRequestEvent) => void;
+  /** REMOTE-007: a pending prompt was settled (by any surface); attached surfaces dismiss it. */
+  prompt_resolved: (event: IPromptResolvedEvent) => void;
+  /** CMD-004 Phase 2: a command-issued UI intent — the requesting surface renders it (fire-and-forget). */
+  ui_intent: (event: IUiIntentEvent) => void;
+  /** CMD-004 Phase 2: the session was renamed host-side — all surfaces update their titles. */
+  session_renamed: (event: ISessionRenamedEvent) => void;
+  /** CMD-004 Phase 2: the conversation history was cleared host-side — all surfaces refresh transcripts. */
+  history_cleared: () => void;
+}
+type TInteractiveEventName = keyof IInteractiveSessionEvents;
+/**
+ * Lifecycle status of an autonomous goal (GOAL-001).
+ * `active` while the agent is pursuing it; terminal otherwise.
+ */
+type TGoalStatus = 'active' | 'satisfied' | 'stopped';
+/**
+ * Why an autonomous goal stopped (GOAL-001). `satisfied` = the agent signalled completion;
+ * `max-iterations` = the turn budget was exhausted; `cancelled` = the user stopped it;
+ * `no-progress` = consecutive idle turns detected a stall (convergence guard).
+ */
+type TGoalStopReason = 'satisfied' | 'max-iterations' | 'cancelled' | 'no-progress';
+/** One recorded iteration of goal pursuit (GOAL-001). */
+interface IGoalProgressEntry {
+  iteration: number;
+  signal: 'continue' | 'satisfied';
+  reason: string;
+}
+/**
+ * Persisted state of an autonomous objective-pursuit loop (GOAL-001). Stored in the session
+ * record so an in-flight goal survives `--resume`.
+ */
+interface IGoalState {
+  id: string;
+  objective: string;
+  status: TGoalStatus;
+  stopReason?: TGoalStopReason;
+  iterations: number;
+  maxIterations: number;
+  startedAt: string;
+  progress: IGoalProgressEntry[];
+}
+/** Observability event for the goal loop (GOAL-001). */
+interface IGoalEvent {
+  type: 'goal_started' | 'goal_progress' | 'goal_stopped';
+  goal: IGoalState;
+}
+/** Execution status of one plan step (SELFHOST-002 plan-mode). */
+type TPlanStepStatus = 'pending' | 'in-progress' | 'done';
+/** One reviewable step in a plan artifact (SELFHOST-002 plan-mode). */
+interface IPlanStep {
+  /** Stable id within the plan. */
+  id: string;
+  /** Human-readable description of the step. */
+  description: string;
+  /** Step status as the plan is executed. */
+  status: TPlanStepStatus;
+}
+/**
+ * Lifecycle phase of a plan artifact (SELFHOST-002). `planning` = drafted in `plan` mode (read-only
+ * tools); `awaiting-approval` = presented for review; `executing` = approved, edits unblocked per
+ * `acceptEdits` (shell still per-call confirmed); `completed` = finished (mode reverts to `plan`).
+ */
+type TPlanPhase = 'planning' | 'awaiting-approval' | 'executing' | 'completed';
+/**
+ * A reviewable plan/todo artifact produced during plan mode (SELFHOST-002). Persisted in the
+ * session record beside {@link IGoalState} so an in-flight plan survives resume. Pure data — the
+ * mutation block stays the existing `plan` permission mode (no artifact-carried enforcement).
+ */
+interface IPlanArtifact {
+  id: string;
+  /** The objective the plan addresses. */
+  objective: string;
+  /** The ordered plan steps. */
+  steps: IPlanStep[];
+  /** Current lifecycle phase. */
+  phase: TPlanPhase;
+  createdAt: string;
+  /** Set when the plan was approved (phase → `executing`). */
+  approvedAt?: string;
+}
+/**
+ * Plan-mode lifecycle event (SELFHOST-002): emitted as a plan artifact is created, approved
+ * (mode flips `plan → acceptEdits`), or reverted (`→ plan`). Carries the artifact snapshot,
+ * mirroring how {@link IGoalEvent} carries the goal state. The event only OBSERVES the phase
+ * transition — the mutation gate stays the existing `plan` permission mode.
+ *
+ * Declared here (rather than `event-contracts.ts`, where it used to live) because it carries
+ * {@link IPlanArtifact}, declared in this file; `event-contracts.ts` re-exports it for
+ * compatibility.
+ */
+interface IPlanApprovalEvent {
+  type: 'plan_created' | 'plan_approved' | 'plan_reverted';
+  plan: IPlanArtifact;
+}
+//#endregion
+//#region src/session-capability-contracts.d.ts
+interface ISessionLifecycle {
+  /** True once the underlying session has been initialized. */
+  readonly isInitialized: boolean;
+  shutdown(options?: {
+    reason?: string;
+    message?: string;
+  }): Promise<void>;
+}
+interface ISessionTurnSubmission {
+  submit(input: string, displayInput?: string, rawInput?: string, options?: ISubmitOptions): Promise<ITurnHandle>;
+}
+interface ISessionTurnControl {
+  abort(): void;
+  cancelQueue(): void;
+}
+interface ISessionGoal {
+  setGoal(objective: string, options?: {
+    maxIterations?: number;
+    noProgressLimit?: number;
+  }): Promise<IGoalState>;
+  getGoalState(): IGoalState | null;
+  cancelGoal(): IGoalState | null;
+}
+interface ISessionExecutionState {
+  isExecuting(): boolean;
+  getPendingPrompt(): string | null;
+  getPendingCount(): number;
+}
+interface ISessionDriverAttribution {
+  getActiveDriverId(): TDriverId | null;
+}
+interface ISessionConversationRead {
+  getMessages(): TUniversalMessage[];
+  getContextState(): IContextWindowState;
+}
+interface ISessionIdentity {
+  getSession(): {
+    getSessionId(): string;
+  };
+}
+interface ISessionWorkspaceLocation {
+  getCwd(): string;
+}
+/** Direct execution uses the same permission-wrapped runtime as model tool calls. */
+interface ISessionRuntimeTools {
+  listRuntimeTools(): Promise<IToolSchema[]>;
+  invokeRuntimeTool(name: string, parameters: TToolParameters, options?: {
+    signal?: AbortSignal;
+  }): Promise<IToolExecutionResult>;
+}
+interface ISessionCommands {
+  executeCommand(name: string, args: string, source?: TCommandInvocationSource, originDriverId?: TDriverId): Promise<ICommandResult | null>;
+  listCommands(): ICommandListEntry[];
+}
+interface ISessionEvents {
+  on<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+  off<E extends TInteractiveEventName>(event: E, handler: IInteractiveSessionEvents[E]): void;
+}
+interface ISessionPromptResolution {
+  resolvePermission(id: string, result: TPermissionResultValue, answererDriverId?: TDriverId): void;
+  resolveAsk(id: string, response: TActionResponse, answererDriverId?: TDriverId): void;
+}
+interface ISessionBackgroundTasks {
+  listBackgroundTasks(filter?: IBackgroundTaskListFilter): IBackgroundTaskState[];
+  getBackgroundTask(taskId: string): IBackgroundTaskState | undefined;
+  cancelBackgroundTask(taskId: string, reason?: string): Promise<void>;
+  closeBackgroundTask(taskId: string): Promise<void>;
+  sendBackgroundTask(taskId: string, input: IBackgroundTaskInput): Promise<void>;
+  readBackgroundTaskLog(taskId: string, cursor?: IBackgroundTaskLogCursor): Promise<IBackgroundTaskLogPage>;
+}
+interface ISessionBackgroundGroups {
+  listBackgroundJobGroups(): IBackgroundJobGroupState[];
+  getBackgroundJobGroup(groupId: string): IBackgroundJobGroupState | undefined;
+  createBackgroundJobGroup(input: Omit<IBackgroundJobGroupCreateRequest, 'parentSessionId'>): IBackgroundJobGroupState;
+  waitBackgroundJobGroup(groupId: string): Promise<IBackgroundJobGroupState>;
+}
+interface ISessionExecutionWorkspace {
+  getExecutionWorkspaceSnapshot(options?: IExecutionWorkspaceSnapshotOptions): IExecutionWorkspaceSnapshot;
+}
+interface ISessionAgentJobs {
+  listAgentDefinitions(): Array<{
+    name: string;
+    description: string;
+  }>;
+  listAgentJobs(): ISubagentJobState[];
+  spawnAgentJob(input: {
+    agentType: string;
+    label: string;
+    mode: 'foreground' | 'background';
+    prompt: string;
+    model?: string;
+    isolation?: TBackgroundTaskIsolation;
+  }): Promise<ISubagentJobState>;
+  sendAgentJob(taskId: string, prompt: string): Promise<void>;
+  cancelAgentJob(taskId: string, reason?: string): Promise<void>;
+  closeAgentJob(taskId: string): Promise<void>;
+}
+interface ISessionCapabilityMap {
+  lifecycle: ISessionLifecycle;
+  turnSubmission: ISessionTurnSubmission;
+  turnControl: ISessionTurnControl;
+  goal: ISessionGoal;
+  executionState: ISessionExecutionState;
+  driverAttribution: ISessionDriverAttribution;
+  conversationRead: ISessionConversationRead;
+  identity: ISessionIdentity;
+  workspaceLocation: ISessionWorkspaceLocation;
+  commands: ISessionCommands;
+  runtimeTools: ISessionRuntimeTools;
+  events: ISessionEvents;
+  promptResolution: ISessionPromptResolution;
+  backgroundTasks: ISessionBackgroundTasks;
+  backgroundGroups: ISessionBackgroundGroups;
+  executionWorkspace: ISessionExecutionWorkspace;
+  agentJobs: ISessionAgentJobs;
+}
+declare const SESSION_CAPABILITY_MEMBER_KEYS: Readonly<{
+  lifecycle: readonly ["isInitialized", "shutdown"];
+  turnSubmission: readonly ["submit"];
+  turnControl: readonly ["abort", "cancelQueue"];
+  goal: readonly ["setGoal", "getGoalState", "cancelGoal"];
+  executionState: readonly ["isExecuting", "getPendingPrompt", "getPendingCount"];
+  driverAttribution: readonly ["getActiveDriverId"];
+  conversationRead: readonly ["getMessages", "getContextState"];
+  identity: readonly ["getSession"];
+  workspaceLocation: readonly ["getCwd"];
+  commands: readonly ["executeCommand", "listCommands"];
+  runtimeTools: readonly ["listRuntimeTools", "invokeRuntimeTool"];
+  events: readonly ["on", "off"];
+  promptResolution: readonly ["resolvePermission", "resolveAsk"];
+  backgroundTasks: readonly ["listBackgroundTasks", "getBackgroundTask", "cancelBackgroundTask", "closeBackgroundTask", "sendBackgroundTask", "readBackgroundTaskLog"];
+  backgroundGroups: readonly ["listBackgroundJobGroups", "getBackgroundJobGroup", "createBackgroundJobGroup", "waitBackgroundJobGroup"];
+  executionWorkspace: readonly ["getExecutionWorkspaceSnapshot"];
+  agentJobs: readonly ["listAgentDefinitions", "listAgentJobs", "spawnAgentJob", "sendAgentJob", "cancelAgentJob", "closeAgentJob"];
+}>;
+type TUnionToIntersection<T> = (T extends T ? (value: T) => void : never) extends ((value: infer TIntersection) => void) ? TIntersection : never;
+type TSelectedSessionPorts<TCapabilities extends Partial<ISessionCapabilityMap>> = TUnionToIntersection<Exclude<TCapabilities[keyof TCapabilities], undefined>>;
+interface ISessionCapabilityHost<TCapabilities extends Partial<ISessionCapabilityMap> = Partial<ISessionCapabilityMap>> {
+  readonly capabilities: Readonly<TCapabilities>;
+}
+type TSessionCapabilityHost<TCapabilities extends Partial<ISessionCapabilityMap>> = ISessionCapabilityHost<TCapabilities> & TSelectedSessionPorts<TCapabilities>;
+type TSessionCapabilityReadResult<TCapability> = Readonly<{
+  provided: false;
+}> | Readonly<{
+  provided: true;
+  value: TCapability;
+}>;
+//#endregion
+//#region src/session-contracts.d.ts
+/** Aggregate session interface composed from its named capability ports. */
+interface IInteractiveSession extends ISessionLifecycle, ISessionTurnSubmission, ISessionTurnControl, ISessionGoal, ISessionExecutionState, ISessionDriverAttribution, ISessionConversationRead, ISessionIdentity, ISessionWorkspaceLocation, ISessionCommands, ISessionRuntimeTools, ISessionEvents, ISessionPromptResolution, ISessionBackgroundTasks, ISessionBackgroundGroups, ISessionExecutionWorkspace, ISessionAgentJobs {}
+/** Persisted record for a resumable interactive session. */
+interface IInteractiveSessionRecord {
+  id: string;
+  name?: string;
+  cwd: string;
+  createdAt: string;
+  updatedAt: string;
+  messages: TUniversalMessage[];
+  history?: IHistoryEntry[];
+  systemPrompt?: string;
+  toolSchemas?: IToolSchema[];
+  backgroundTasks?: IBackgroundTaskState[];
+  backgroundTaskEvents?: TBackgroundTaskEvent[];
+  backgroundJobGroups?: IBackgroundJobGroupState[];
+  backgroundJobGroupEvents?: TBackgroundJobGroupEvent[];
+  sessionLoops?: ISessionLoopState[];
+  skillActivationEvents?: ISkillActivationEvent[];
+  memoryEvents?: IMemoryEvent[];
+  usedMemoryReferences?: IMemoryReference[];
+  contextReferences?: IContextReferenceItem[];
+  sandboxSnapshotId?: string;
+  /** In-flight autonomous goal, persisted so it survives resume (GOAL-001). */
+  goal?: IGoalState;
+  /** In-flight plan artifact, persisted so it survives resume (SELFHOST-002 plan-mode). */
+  plan?: IPlanArtifact;
+  /** Active checkpoint branch pointer, persisted so a branch survives resume (SELFHOST-007). */
+  activeBranch?: IActiveBranchPointer;
+}
+//#endregion
+export { TDriverId as $, IGoalEvent as A, TGoalStatus as B, TSessionCapabilityHost as C, TCompactTrigger as Ct, IBranchEvent as D, IAskRequestEvent as E, IPlanApprovalEvent as F, TPlanPhase as G, TInteractiveEventName as H, IPlanArtifact as I, IPeerTurnContext as J, TPlanStepStatus as K, IPlanStep as L, IGoalState as M, IInteractiveSessionEvents as N, IContextFileRefreshedEvent as O, IPermissionRequestEvent as P, OWNER_DRIVER_ID as Q, IPromptResolvedEvent as R, SESSION_CAPABILITY_MEMBER_KEYS as S, ICompactEvent as St, IActiveBranchPointer as T, TInteractivePermissionHandler as U, TGoalStopReason as V, TPermissionResultValue as W, ISubmitOptions as X, ISessionRenamedEvent as Y, IUiIntentEvent as Z, ISessionPromptResolution as _, TSkillActivationStatus as _t, ISessionBackgroundTasks as a, isTurnNotRunError as at, ISessionTurnSubmission as b, ISessionLoopState as bt, ISessionCommands as c, IMemoryEvent as ct, ISessionEvents as d, TContextReferenceLoadType as dt, IExecutionResult as et, ISessionExecutionState as f, TContextReferenceStatus as ft, ISessionLifecycle as g, TSkillActivationSource as gt, ISessionIdentity as h, TSkillActivationMode as ht, ISessionBackgroundGroups as i, TTurnSource as it, IGoalProgressEntry as j, IDiffLine as k, ISessionConversationRead as l, IMemoryReference as lt, ISessionGoal as m, TSkillActivationInvocation as mt, IInteractiveSessionRecord as n, ITurnNotRunError as nt, ISessionCapabilityHost as o, IToolSummary as ot, ISessionExecutionWorkspace as p, TMemoryType as pt, AGENT_DRIVER_ID as q, ISessionAgentJobs as r, TTurnNotRunReason as rt, ISessionCapabilityMap as s, IContextReferenceItem as st, IInteractiveSession as t, ITurnHandle as tt, ISessionDriverAttribution as u, ISkillActivationEvent as ut, ISessionRuntimeTools as v, IPromptFileReferenceRecord as vt, TSessionCapabilityReadResult as w, ISessionWorkspaceLocation as x, TSessionLoopPhase as xt, ISessionTurnControl as y, TPromptFileReferenceReason as yt, IToolState as z };
+//# sourceMappingURL=session-contracts-BVCzd3uY.d.ts.map