@robota-sdk/agent-cli 3.0.0-beta.79 → 3.0.0-beta.81

package/dist/node/index.d.cts

@@ -0,0 +1,3421 @@
+import "zod";
+import "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import "@modelcontextprotocol/sdk/shared/auth.js";
+import "@modelcontextprotocol/sdk/types.js";
+import "@modelcontextprotocol/sdk/shared/transport.js";
+//#region ../agent-core/dist/node/types-gNrckgFE.d.ts
+//#region src/interfaces/universal-value.d.ts
+/**
+ * Universal value type axis (recursive, JSON-like + Date).
+ *
+ * Extracted from `types.ts` into its own leaf module: several foundational modules (e.g.
+ * `provider.ts`) need only this axis, not the rest of `types.ts` (which itself depends on
+ * plugin-execution types) — importing the whole barrel there created a module-level import
+ * cycle. `types.ts` re-exports these names, so existing `from './types'` imports are unaffected.
+ *
+ * IMPORTANT:
+ * - This axis is the single source of truth for payload/context/result values.
+ * - It must support nested objects/arrays without `any`/`unknown`.
+ */
+/**
+ * Primitive value types - foundation for all other types
+ * Extended to include null/undefined for agent contexts
+ */
+type TPrimitiveValue = string | number | boolean | null | undefined;
+type TUniversalValue = TPrimitiveValue | Date | TUniversalArrayValue | IUniversalObjectValue;
+type TUniversalArrayValue = TUniversalValue[];
+interface IUniversalObjectValue {
+  [key: string]: TUniversalValue;
+}
+//#endregion
+//#region src/interfaces/model-effort-capability.d.ts
+/** Provider-neutral native effort controls. `auto` is selection state, not a control. */
+type TModelEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/** A caller can preserve provider-default selection without serializing a native control. */
+type TModelEffortSelection = TModelEffort | 'auto';
+/** The verified effort facts an adapter declares for one exact model identifier. */
+interface IModelEffortCapability {
+  supportedEfforts: readonly TModelEffort[];
+  defaultEffort: TModelEffort;
+  /** Adapter-owned opaque identity for the verified native control. */
+  nativeControlId: string;
+}
+/** Source-dated provider data. Core owns the shape but never provides the data. */
+interface IProviderModelEffortTable {
+  verifiedAt: string;
+  sourceUrl: string;
+  models: Readonly<Record<string, IModelEffortCapability>>;
+}
+type TModelEffortDisposition = 'exact' | 'clamped' | 'model-default' | 'not-applied';
+/** Serializable output of resolving a selection against a verified provider table. */
+interface IModelEffortResolution$1 {
+  selection: TModelEffortSelection;
+  effective: TModelEffort | null;
+  disposition: TModelEffortDisposition;
+  fingerprint: string;
+}
+/** Whether the adapter serialized a verified native effort control. */
+type TModelEffortNativeControl = {
+  readonly state: 'sent';
+  readonly id: string;
+} | {
+  readonly state: 'omitted';
+  readonly reason: string;
+};
+/** Whether an endpoint dispatch occurred after the effort decision. */
+type TModelEffortProviderDispatch = {
+  readonly state: 'sent';
+} | {
+  readonly state: 'not-dispatched';
+  readonly reason: string;
+};
+/** Serializable terminal result of one effort-bearing provider request. */
+interface IModelEffortOutcome {
+  readonly resolution: IModelEffortResolution$1;
+  readonly nativeControl: TModelEffortNativeControl;
+  readonly providerDispatch: TModelEffortProviderDispatch;
+}
+/** Local observer for a request's one terminal provider effort outcome. */
+type TModelEffortOutcomeCallback = (outcome: IModelEffortOutcome) => void;
+/** What one child process receives: exactly one environment variable, never `TRACESTATE`. */
+interface ISubprocessTraceEnv {
+  readonly TRACEPARENT: string;
+}
+/** What one invoked provider call carries: the header value and where it may go. */
+interface IOutboundTraceContext {
+  /** `00-<trace-id>-<provider-call-span-id>-01`. */
+  readonly traceparent: string;
+  /** Exact origins the adapter may send `traceparent` to; any other origin gets nothing. */
+  readonly allowedOrigins: readonly string[];
+}
+/** Claude Code compatible session end reasons. */
+type TSessionEndReason = 'clear' | 'resume' | 'logout' | 'prompt_input_exit' | 'bypass_permissions_disabled' | 'other';
+//#endregion
+//#region ../agent-core/dist/node/index-DFlMw376.d.ts
+/**
+ * Context data type - for execution contexts
+ */
+type TContextData = Record<string, TUniversalValue>;
+/**
+ * Logger data type - for logging contexts
+ */
+type TLoggerData = Record<string, TUniversalValue | Date | Error>;
+/**
+ * Tool parameter value type - specific for tool parameters
+ */
+type TToolParameters = Record<string, TUniversalValue>;
+//#endregion
+//#region src/interfaces/interaction.d.ts
+/**
+ * UI-agnostic "ask the user" contract (CMD-004).
+ *
+ * The SSOT for the interaction action lives in agent-core so every interaction *source* can reach it:
+ * command execution (`ICommandHostContext`, agent-framework) AND tool execution
+ * (`IToolExecutionContext`, agent-core, for model-issued questions — CMD-005). These are pure types
+ * with no runtime dependency, so the contract crosses a serialization/transport boundary unchanged
+ * (no function-valued fields).
+ *
+ * A single shape covers every interaction kind, parameterised by fields rather than split into
+ * variants:
+ * - confirm    → two options, `maxSelect` 1
+ * - single     → options, `maxSelect` 1
+ * - multi      → options, `maxSelect` > 1
+ * - free text  → no options, `allowFreeText` true
+ * - secret     → free text with `masked` true
+ */
+/** One predefined option the user can choose. */
+interface IActionOption {
+  value: string;
+  label: string;
+  description?: string;
+}
+/** Pre-selected option values and/or prefilled free text for an action request. */
+interface IActionDefault {
+  values?: readonly string[];
+  text?: string;
+}
+/** One request for the user to answer. See the module doc for how the fields encode each kind. */
+interface IActionRequest {
+  /** Correlation key; the ask port resolves a given id exactly once (idempotent, first-answer wins). */
+  id: string;
+  title: string;
+  description?: string;
+  /** Predefined options. Empty/omitted ⇒ pure free-text entry. */
+  options?: readonly IActionOption[];
+  /** Minimum selections required (default 1). */
+  minSelect?: number;
+  /** Maximum selections allowed (default 1 ⇒ single; > 1 ⇒ multi). */
+  maxSelect?: number;
+  /** Allow a typed custom answer in addition to / instead of the options. */
+  allowFreeText?: boolean;
+  /** Free-text entry is masked (secret entry such as an API key); the renderer hides input. */
+  masked?: boolean;
+  /** Allow submitting empty free text. */
+  allowEmpty?: boolean;
+  /** Placeholder shown in the free-text field. */
+  placeholder?: string;
+  /** Maximum options shown before scrolling (renderer hint). */
+  maxVisible?: number;
+  /** Pre-selected option values and/or prefilled free text. */
+  default?: IActionDefault;
+}
+/**
+ * The user's answer to an {@link IActionRequest}. `answer` carries the selected option values and/or
+ * the typed text; `cancelled` means the user dismissed the request, or no interactive renderer was
+ * available to answer it.
+ */
+type TActionResponse = {
+  type: 'answer';
+  values: readonly string[];
+  text?: string;
+} | {
+  type: 'cancelled';
+};
+/**
+ * The injected "ask the user" port — a single seam reachable by every interaction source (command
+ * execution now; tool execution for model-issued questions later) and rendered per-environment by each
+ * transport. The concurrency model (broadcast to attached interactive channels, first answer wins,
+ * later answers for an already-resolved `id` ignored) is owned by the port implementation, not the
+ * contract.
+ */
+interface IUserInteraction {
+  ask(request: IActionRequest): Promise<TActionResponse>;
+}
+/**
+ * Message metadata used across conversation history and provider adapters.
+ */
+type TUniversalMessageMetadata = Record<string, string | number | boolean | Date | string[] | number[] | Record<string, number>>;
+/**
+ * Universal multimodal message part contracts.
+ */
+interface ITextMessagePart {
+  type: 'text';
+  text: string;
+}
+interface IInlineImageMessagePart {
+  type: 'image_inline';
+  mimeType: string;
+  data: string;
+}
+interface IUriImageMessagePart {
+  type: 'image_uri';
+  uri: string;
+  mimeType?: string;
+}
+type TUniversalMessagePart = ITextMessagePart | IInlineImageMessagePart | IUriImageMessagePart;
+/**
+ * Tool call (OpenAI tool calling format).
+ */
+interface IToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+/** State of a message in conversation history */
+type TMessageState = 'complete' | 'interrupted';
+/**
+ * Base message contract shared by all message variants.
+ */
+interface IBaseMessage {
+  /** Unique message identifier */
+  id: string;
+  /** Message creation timestamp */
+  timestamp: Date;
+  /** Whether this message is complete or was interrupted */
+  state: TMessageState;
+  /** Additional metadata */
+  metadata?: TUniversalMessageMetadata;
+}
+interface IUserMessage extends IBaseMessage {
+  role: 'user';
+  content: string;
+  parts?: TUniversalMessagePart[];
+  name?: string;
+}
+interface IAssistantMessage extends IBaseMessage {
+  role: 'assistant';
+  /** Assistant response content (can be null when making tool calls) */
+  content: string | null;
+  parts?: TUniversalMessagePart[];
+  toolCalls?: IToolCall[];
+}
+interface ISystemMessage extends IBaseMessage {
+  role: 'system';
+  content: string;
+  parts?: TUniversalMessagePart[];
+  name?: string;
+}
+interface IToolMessage extends IBaseMessage {
+  role: 'tool';
+  content: string;
+  parts?: TUniversalMessagePart[];
+  toolCallId: string;
+  name?: string;
+}
+/**
+ * Universal message union used across the SDK as the canonical contract.
+ * Used for AI provider communication. Extracted from IHistoryEntry[] via filtering.
+ */
+type TUniversalMessage = IUserMessage | IAssistantMessage | ISystemMessage | IToolMessage;
+/**
+ * Universal history entry — the base type for all records in conversation history.
+ *
+ * History is a universal timeline that records everything: AI chat messages,
+ * system events, skill invocations, permission decisions, etc.
+ * AI provider receives only chat entries (filtered and converted to TUniversalMessage).
+ * TUI can render any range of entries.
+ *
+ * - append-only, read-only
+ * - category + type for classification (free-form strings, no pre-defined enum)
+ * - data holds type-specific structured content
+ */
+interface IHistoryEntry<T = unknown> {
+  /** Unique entry identifier */
+  id: string;
+  /** Entry creation timestamp */
+  timestamp: Date;
+  /** Top-level classification: 'chat', 'event', etc. */
+  category: string;
+  /** Sub-classification within category. Free-form, not pre-defined. */
+  type: string;
+  /** Type-specific structured data */
+  data?: T;
+}
+//#endregion
+//#region src/interfaces/provider-model-capability-kind.d.ts
+/**
+ * The vocabulary of per-model capability flags (PROV-006 / PROV-008).
+ *
+ * Extracted from `provider-definition.ts` into its own leaf module: `model-capability.ts` needs
+ * only this vocabulary, not the rest of `provider-definition.ts` (which itself depends on
+ * `IAIProvider` from `provider.ts`) — importing the whole module there created a module-level
+ * import cycle (`provider.ts` -> `model-capability.ts` -> `provider-definition.ts` ->
+ * `provider.ts`). `provider-definition.ts` re-exports this name, so existing
+ * `from './provider-definition'` imports are unaffected.
+ */
+type TProviderModelCapability = 'tools' | 'vision' |
+/** A first-class schema parameter the endpoint enforces. */
+'json_schema' |
+/**
+ * JSON is guaranteed, the SHAPE is not (CORE-043).
+ *
+ * Without this DeepSeek is unrepresentable: the vocabulary offered only `json_schema`, which
+ * DeepSeek does not support, so its catalog entry was wrong and DELETING the entry would have left
+ * it wrong in the other direction — silent about a real capability.
+ */
+'json_object' | 'reasoning' | 'native_web' | 'streaming' |
+/**
+ * CLI-1990: the vendor documents a server-side tool search — deferred definitions the API expands
+ * on demand. Declaration-only in v1: Robota runs its own client-side catalog on every provider
+ * and emits no vendor block. The member exists so a later offload can be capability-gated in this
+ * table rather than by provider name.
+ */
+'tool_search';
+//#endregion
+//#region src/interfaces/model-capability.d.ts
+/** One model that verifiably differs from its vendor's default, and when that was checked. */
+interface IModelCapabilityDeviation {
+  /** The complete capability set for this model — not a delta against the default. */
+  capabilities: readonly TProviderModelCapability[];
+  /** ISO date this deviation was verified against the vendor's documentation. */
+  verifiedAt: string;
+  sourceUrl?: string;
+}
+/**
+ * What a provider package declares about its own models.
+ *
+ * A package with no verified source for its vendor's baseline declares NO TABLE rather than an empty
+ * one: an empty default would resolve every capability to "false", which is the silence-read-as-denial
+ * inversion this contract exists to forbid.
+ */
+interface IProviderCapabilityTable {
+  /** What this vendor's models can do unless a model below says otherwise. */
+  vendorDefault: readonly TProviderModelCapability[];
+  /** Only models that verifiably differ. Absent means none do. */
+  deviations?: Readonly<Record<string, IModelCapabilityDeviation>>;
+  /** ISO date the vendor default was verified. */
+  verifiedAt: string;
+  sourceUrl?: string;
+}
+//#endregion
+//#region src/interfaces/role-model.d.ts
+/**
+ * SELFHOST-006 — per-role model routing contract (type-only, neutral).
+ *
+ * A role→model mapping keyed by an OPAQUE `string` role id — deliberately NOT a fixed
+ * `planner|editor|reviewer` union and NOT a TS `enum`: a fixed vocabulary would embed an
+ * app-workflow opinion into a neutral library. The concrete role set lives in the product/default
+ * layer (`agent-builtin-providers` / `agent-cli`), never here. Mirrors the existing subagent
+ * opaque-key model resolution (`resolveModelId` → `MODEL_SHORTCUTS[x] ?? x`).
+ *
+ * Each role maps to an ORDERED fallback chain: the first entry is the primary; the rest are
+ * fallbacks in order. Each entry carries BOTH provider identity AND model — mirroring the global
+ * `defaultModel: { provider, model }` — so "fall back to an alternate provider" is expressible (a
+ * model id alone cannot express it).
+ */
+/** One provider+model target in a role's fallback chain. */
+interface IModelRef {
+  provider: string;
+  model: string;
+}
+//#endregion
+//#region src/utils/provider-failure.d.ts
+/** Why a provider call failed, as far as switching models is concerned. */
+type TProviderFailureReason = 'overloaded' | 'service-unavailable' | 'server-error' | 'model-unavailable' | 'authentication' | 'billing' | 'rate-limit' | 'invalid-request' | 'network' | 'aborted' | 'unknown';
+//#endregion
+//#region src/interfaces/model-fallback.d.ts
+/** A request moved to another model because the one it was on failed in a way another could serve. */
+interface IModelFallbackNotice {
+  /** The model that failed. */
+  from: IModelRef;
+  /** The model the request moved to. */
+  to: IModelRef;
+  /** Why `from` could not serve it. */
+  reason: TProviderFailureReason;
+}
+type TModelFallbackCallback = (notice: IModelFallbackNotice) => void;
+//#endregion
+//#region src/interfaces/provider-capabilities.d.ts
+interface IProviderFunctionCallingCapability {
+  supported: boolean;
+  reason?: string;
+}
+interface IProviderNativeWebToolCapability {
+  supported: boolean;
+  enabled: boolean;
+  source?: string;
+  reason?: string;
+}
+interface IProviderNativeWebToolCapabilities {
+  webSearch: IProviderNativeWebToolCapability;
+  webFetch: IProviderNativeWebToolCapability;
+}
+interface IProviderCapabilities {
+  functionCalling: IProviderFunctionCallingCapability;
+  nativeWebTools: IProviderNativeWebToolCapabilities;
+}
+/**
+ * Hosted web tools asked of one call: `true` requires the tool (a provider without it throws),
+ * `false` withholds it from this call even when the provider is configured with it, and absent
+ * leaves the provider's own configuration.
+ */
+interface IProviderNativeWebToolRequest {
+  webSearch?: boolean;
+  webFetch?: boolean;
+}
+//#endregion
+//#region src/interfaces/provider-specific-options.d.ts
+/**
+ * Vendor-specific request options, kept out of `provider.ts`.
+ *
+ * Split by responsibility rather than shaved: `provider.ts` is long past the size ceiling, and these
+ * are the one part of it that describes particular VENDORS rather than the neutral contract every
+ * provider implements. They are re-exported from `provider.ts`, so no consumer sees a difference.
+ */
+/**
+ * Provider-specific configuration options
+ */
+interface IProviderSpecificOptions {
+  /** OpenAI specific options */
+  openai?: {
+    organization?: string;
+    user?: string;
+    stop?: string | string[];
+    presencePenalty?: number;
+    frequencyPenalty?: number;
+    logitBias?: Record<string, number>;
+    topP?: number;
+    n?: number;
+    stream?: boolean;
+    suffix?: string;
+    echo?: boolean;
+    bestOf?: number;
+    logprobs?: number;
+  };
+  /** Anthropic specific options */
+  anthropic?: {
+    stopSequences?: string[];
+    topP?: number;
+    topK?: number;
+    metadata?: {
+      userId?: string;
+    };
+  };
+  /** Google specific options */
+  google?: {
+    candidateCount?: number;
+    stopSequences?: string[];
+    safetySettings?: Array<{
+      category: string;
+      threshold: string;
+    }>;
+    responseModalities?: Array<'TEXT' | 'IMAGE'>;
+    topP?: number;
+    topK?: number;
+  };
+}
+/**
+ * Callback for receiving text deltas during streaming.
+ * Called for each text chunk as the model generates output.
+ */
+//#endregion
+//#region src/interfaces/tool-schema.d.ts
+/**
+ * The universal JSON-schema subset (CORE-039 SSOT).
+ *
+ * Every tool schema and every structured-output schema in the repo is expressed in these types.
+ * They live in their own module rather than inside `provider.ts` because they are their own
+ * concept: producers (the Zod converter), validators, and four provider adapters all reach them,
+ * and only some of those care about the rest of the provider contract.
+ *
+ * The full contract — which member means what, and what a walk over it must do — is in
+ * agent-core `docs/SPEC.md` § Universal JSON-Schema Subset. `provider.ts` re-exports everything
+ * here, so existing `from './provider'` imports keep resolving.
+ */
+/**
+ * JSON Schema parameter default value type
+ * Used for default values in parameter schemas
+ */
+type TParameterDefaultValue = string | number | boolean | null;
+/**
+ * JSON Schema primitive types
+ */
+type TJSONSchemaKind = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+/**
+ * JSON Schema enum values
+ */
+type TJSONSchemaEnum = string[] | number[] | boolean[] | (string | number | boolean)[];
+/**
+ * Parameter schema — one shape for a root object and every node inside it.
+ *
+ * `required` and `anyOf` are members at every level, so a nested object states its own requirements
+ * rather than losing them. Splitting root from nested is what let a nested object be treated as a
+ * leaf: the root named its fields while everything below it reached the model as
+ * `{ "type": "object" }` and nothing else.
+ *
+ * `type` is optional because a union node carries `anyOf` INSTEAD of a type — emitting both is
+ * invalid JSON Schema, since a provider applies the two constraints together and rejects the branch
+ * that does not match the type. A node with neither is not valid: every walk over this subset
+ * refuses it rather than passing it silently.
+ *
+ * `additionalProperties` declares closure relative to a declared `properties` set — a node that
+ * declares no `properties` permits any, exactly as JSON Schema does. See the SPEC section above for
+ * why the rule is keyed on member presence.
+ */
+interface IParameterSchema {
+  type?: TJSONSchemaKind;
+  description?: string;
+  enum?: TJSONSchemaEnum;
+  items?: IParameterSchema;
+  properties?: Record<string, IParameterSchema>;
+  required?: string[];
+  /** Union node: the value must match at least one member. Carried instead of `type`. */
+  anyOf?: IParameterSchema[];
+  additionalProperties?: boolean | IParameterSchema;
+  minimum?: number;
+  maximum?: number;
+  pattern?: string;
+  format?: string;
+  default?: TParameterDefaultValue;
+}
+/**
+ * An {@link IParameterSchema} narrowed to an object node that names its properties — the shape a
+ * tool's `parameters` root must take.
+ */
+interface IObjectParameterSchema extends IParameterSchema {
+  type: 'object';
+  properties: Record<string, IParameterSchema>;
+}
+/**
+ * Tool schema definition
+ */
+interface IToolSchema {
+  name: string;
+  description: string;
+  parameters: IObjectParameterSchema;
+  /**
+   * SELFHOST-005: optional schema the tool's OUTPUT (`result.data`) must match. When present, the
+   * tool-registry validates the returned value against it in `FunctionTool.execute` (beside the
+   * tool-INPUT `parameter-validator`) and throws on mismatch before the result returns. Absent =
+   * no output validation (backward-compatible). Model-output validation is separate (CORE-015).
+   *
+   * An object output is declared as an {@link IObjectParameterSchema} (so it names its properties);
+   * a non-object output is a bare {@link IParameterSchema}. Both are the same subset — CORE-039
+   * removed the second, structurally identical root shape that used to be spelled out here purely
+   * to regain `required`, which `IParameterSchema` now carries at every level.
+   */
+  outputSchema?: IParameterSchema;
+  /**
+   * CLI-1990: withheld from the model's tool list until loaded; omission means resident.
+   *
+   * A CLIENT-SIDE marker — the schema leaves the request entirely, not merely the context window,
+   * which is what the vendor's `defer_loading` does. Deferral engages only when the tool-search
+   * policy says so (`resolveToolSearchMode`); until then a deferred tool is offered like any other,
+   * so declaring it costs nothing at today's tool counts. Loaded by the search tool (by query or by
+   * name) or by a `toolChoice` that forces the tool, and it stays loaded for the session. Provider
+   * adapters never emit it: it is not part of any vendor wire format.
+   */
+  deferLoading?: boolean;
+}
+//#endregion
+//#region src/interfaces/provider.d.ts
+/**
+ * Reusable type definitions for provider layer
+ */
+/**
+ * Provider configuration value type
+ * Used for storing provider-specific configuration values
+ */
+type TProviderConfigValue = string | number | boolean;
+/**
+ * Token usage statistics
+ */
+interface ITokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+/**
+ * Raw provider response interface
+ */
+interface IRawProviderResponse {
+  content: string | null;
+  toolCalls?: IToolCall[];
+  usage?: ITokenUsage;
+  finishReason?: string;
+  model?: string;
+  metadata?: Record<string, TProviderConfigValue>;
+  /** One terminal effort result for generic raw non-streaming calls or the explicit stream envelope. */
+  modelEffortOutcome?: IModelEffortOutcome;
+}
+/**
+ * Provider request payload
+ */
+interface IProviderRequest {
+  messages: TUniversalMessage[];
+  model?: string;
+  /** Caller selection retained until the adapter resolves its verified model table. */
+  effort?: TModelEffortSelection;
+  /** Immutable adapter-bound resolution handoff for this request. */
+  effortResolution?: IModelEffortResolution$1;
+  /** Local-only observer for the terminal serializable outcome. */
+  onModelEffortOutcome?: TModelEffortOutcomeCallback;
+  temperature?: number;
+  maxTokens?: number;
+  tools?: IToolSchema[];
+  systemMessage?: string;
+  metadata?: Record<string, string | number | boolean>;
+}
+type TTextDeltaCallback = (delta: string) => void;
+type TProviderNativeRawPayloadKind = 'request' | 'response' | 'stream_event';
+type TProviderNativeRawPayload = string | number | boolean | object | null | undefined;
+interface IProviderNativeRawPayloadEvent {
+  provider: string;
+  apiSurface?: string;
+  payloadKind: TProviderNativeRawPayloadKind;
+  payload: TProviderNativeRawPayload;
+  sequence?: number;
+  metadata?: Record<string, TProviderConfigValue>;
+}
+type TProviderNativeRawPayloadCallback = (event: IProviderNativeRawPayloadEvent) => void;
+/**
+ * Tool-invocation directive threaded per model invocation (CORE-017).
+ *
+ * Canonical SSOT for the union. `'auto'` lets the model decide (provider default),
+ * `'none'` suppresses tool calls for the invocation, `'required'` forces the model to call
+ * some tool, and `{ tool: name }` forces a call to the named tool. Core validates that a
+ * named tool exists in the invocation's tool list and that `'required'`/named forcing is
+ * only used when tools are present — a violation throws instead of degrading silently.
+ * Within a multi-round run, forcing directives apply to the FIRST model call only; rounds
+ * after tool results revert to `'auto'` so the model can consume the results and finish.
+ */
+type TToolChoice = 'auto' | 'none' | 'required' | {
+  tool: string;
+};
+/**
+ * Options for AI provider chat requests
+ */
+interface IChatOptions extends IProviderSpecificOptions {
+  /** Tool schemas to provide to the AI provider */
+  tools?: IToolSchema[];
+  /** Maximum number of tokens to generate */
+  maxTokens?: number;
+  /** Temperature for response randomness (0-1) */
+  temperature?: number;
+  /**
+   * Reasoning-effort dial for this invocation. Native-effort providers map it to their
+   * request parameter; providers without native effort ignore it (documented no-op).
+   * Threaded from session/model options; `auto` remains provider-default selection until resolution.
+   */
+  effort?: TModelEffortSelection;
+  /** Immutable adapter-bound resolution handoff for this request. */
+  effortResolution?: IModelEffortResolution$1;
+  /** Local-only observer for this request's terminal model-effort outcome. */
+  onModelEffortOutcome?: TModelEffortOutcomeCallback;
+  /** Model to use for the request */
+  model?: string;
+  /** Callback for text deltas during streaming. When provided, the provider
+   *  should use streaming internally and call this for each text chunk,
+   *  while still returning the complete assembled message. */
+  onTextDelta?: TTextDeltaCallback;
+  /** Callback for provider-owned native SDK request/response/stream payload capture. */
+  onProviderNativeRawPayload?: TProviderNativeRawPayloadCallback;
+  /** AbortSignal for cancelling the provider call */
+  signal?: AbortSignal;
+  /**
+   * Trusted trace context for THIS invoked call. Core sets it only on a call it actually hands to the
+   * adapter, and only for a provider that answers `canPropagateTraceContext()` with true. An adapter
+   * adds `traceparent` (via `traceHeadersFor`) to its per-request headers when its effective origin
+   * is listed, after raw-payload capture, and never copies this into any captured payload.
+   */
+  outboundTraceContext?: IOutboundTraceContext;
+  /**
+   * Tool-invocation directive for this call. Adapters map it onto their wire format
+   * (`tool_choice` / `functionCallingConfig`); omitted = provider default ('auto').
+   */
+  toolChoice?: TToolChoice;
+  /** Provider-native hosted web tools requested for this call */
+  nativeWebTools?: IProviderNativeWebToolRequest;
+  /** Request structured output from the provider (CORE-015: `json_schema` carries the schema). */
+  responseFormat?: {
+    type: 'text' | 'json_object';
+  } | {
+    type: 'json_schema';
+    name?: string;
+    schema: Record<string, TUniversalValue>;
+  };
+  /**
+   * The run this call belongs to: the same for every call of one run and different for the next.
+   * A provider that can answer on another model keys its per-run choice on it; a call without one
+   * belongs to no run and starts from the requested model.
+   */
+  executionId?: string;
+  /** Told when this request moved to another model, so the caller can attribute the answer. */
+  onModelFallback?: TModelFallbackCallback;
+  /**
+   * Any other model this request moves to must offer at least the requested model's context
+   * window; a model whose window is unknown counts as smaller. Set by compaction, whose input was
+   * sized to the requested model.
+   */
+  preserveContextWindow?: boolean;
+}
+/**
+ * Provider-agnostic AI Provider interface
+ * This interface uses only TUniversalMessage types and avoids provider-specific types
+ */
+interface IAIProvider {
+  /** Provider identifier */
+  readonly name: string;
+  /** Provider version */
+  readonly version: string;
+  /**
+   * Generate response from AI model using TUniversalMessage
+   * @param messages - Array of TUniversalMessage from conversation history
+   * @param options - Chat options including tools, model settings, etc.
+   * @returns Promise resolving to a TUniversalMessage response
+   */
+  chat(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
+  /**
+   * Generate streaming response from AI model using TUniversalMessage
+   * @param messages - Array of TUniversalMessage from conversation history
+   * @param options - Chat options including tools, model settings, etc.
+   * @returns AsyncIterable of TUniversalMessage chunks
+   */
+  chatStream?(messages: TUniversalMessage[], options?: IChatOptions): AsyncIterable<TUniversalMessage>;
+  /**
+   * Generate response from AI model (raw provider response)
+   * @param payload - Provider request payload
+   * @returns Promise resolving to raw provider response
+   */
+  generateResponse(payload: IProviderRequest): Promise<IRawProviderResponse>;
+  /**
+   * Generate streaming response from AI model (raw provider response)
+   * @param payload - Provider request payload
+   * @returns AsyncIterable of raw provider response chunks
+   */
+  generateStreamingResponse?(payload: IProviderRequest): AsyncIterable<IRawProviderResponse>;
+  /**
+   * Check if the provider supports tool calling
+   * @returns true if tool calling is supported
+   */
+  supportsTools(): boolean;
+  /**
+   * Report provider-neutral capability state.
+   * Providers without native web support can omit this and use default capability helpers.
+   */
+  getCapabilities?(): IProviderCapabilities;
+  /**
+   * What this provider's models can do (PROV-006/PROV-008).
+   *
+   * `supportsTools()` answers for the vendor, which is the wrong granularity when models differ.
+   * This is the per-MODEL answer, declared by the package that ships the adapter and reachable from
+   * the instance — the catalog on `IProviderDefinition` is discovery, which the instance never
+   * holds. Optional, and silence is NOT denial: see `interfaces/model-capability.ts`.
+   */
+  capabilityTable?(): IProviderCapabilityTable | undefined;
+  /**
+   * Source-dated effort data for exact models this adapter can verify. Optional: a missing table is
+   * a visible `not-applied` result, never a vendor-wide inferred default.
+   */
+  effortTable?(): IProviderModelEffortTable | undefined;
+  /**
+   * Whether this provider instance is pointed at its vendor's own endpoint. CORE-043.
+   *
+   * A provider configured with a custom `baseURL` still speaks the vendor's protocol, but the
+   * vendor's guarantees are no longer the ones in force — a gateway can accept a structured-output
+   * parameter and forward a request that ignores it, so the runtime would claim enforcement the
+   * endpoint does not provide.
+   *
+   * Separate from `capabilityTable()` deliberately. Endpoint identity and capability declaration are
+   * independent facts, and coupling them would force a provider with no verified table to invent one
+   * in order to report its endpoint. Silence means the provider did not say, which is not a claim
+   * that the endpoint is the vendor's.
+   */
+  endpointIsVendorDefault?(): boolean;
+  /**
+   * Whether this instance can put a trusted `traceparent` on its own HTTP requests: it knows its
+   * effective origin and sends through a transport it controls. Optional, and silence means it
+   * cannot — core then sends it no trace context and tells the host which provider could not.
+   */
+  canPropagateTraceContext?(): boolean;
+  /**
+   * Where a request for `model` in the run `executionId` will go first. Only a provider that can
+   * answer on another model implements it; absent, the request goes to this provider and `model`.
+   */
+  resolveModelRoute?(model: string, executionId?: string): IModelRef;
+  /**
+   * Optional generic hook for enabling provider-native hosted web behavior.
+   */
+  configureNativeWebTools?(request: IProviderNativeWebToolRequest): IProviderCapabilities;
+  /**
+   * Validate provider configuration
+   * @returns true if configuration is valid
+   */
+  validateConfig(): boolean;
+  /**
+   * Clean up resources when provider is no longer needed
+   */
+  dispose?(): Promise<void>;
+  /**
+   * Close provider connections and cleanup resources
+   */
+  close?(): Promise<void>;
+}
+/**
+ * The catalog a search tool loads through — the port `IToolExecutionContext.deferredTools` carries.
+ *
+ * Narrow on purpose: a tool that can list and load must not be able to register, remove or execute.
+ */
+interface IDeferredToolCatalog {
+  /**
+   * Deferred tools not yet loaded — the population a search can still discover. Empty while
+   * deferral is not engaged, because nothing is withheld then.
+   */
+  listDeferredTools(): IToolSchema[];
+  /**
+   * Mark the named deferred tools loaded for the rest of the session and return their schemas. A
+   * resident name is returned as it is (it was never withheld); an unknown name throws, naming the
+   * entry, and then nothing is loaded — the check runs over every name before the first load.
+   */
+  loadDeferredTools(names: readonly string[]): IToolSchema[];
+}
+//#endregion
+//#region src/event-service/interfaces.d.ts
+/**
+ * @fileoverview Event service interface definitions.
+ *
+ * These interfaces are the single source of truth for event-related contracts
+ * within @robota-sdk/agent-core.
+ */
+/**
+ * Primitive value types for event payloads.
+ */
+type TEventPrimitiveValue = string | number | boolean | null | undefined;
+/**
+ * Recursive universal value type for event payloads (JSON-like + Date).
+ */
+type TEventUniversalValue = TEventPrimitiveValue | Date | TEventUniversalValue[] | IEventObjectValue;
+interface IEventObjectValue {
+  [key: string]: TEventUniversalValue;
+}
+/**
+ * Logger data type for event metadata.
+ */
+type TEventLoggerData = Record<string, TEventUniversalValue | Date | Error>;
+/**
+ * A single segment in an explicit ownerPath.
+ *
+ * Path-only rule:
+ * - Relationships must be derived from these explicit segments, not from parsing IDs.
+ */
+interface IOwnerPathSegment {
+  type: string;
+  id: string;
+}
+/**
+ * Event context that accompanies an emitted event.
+ * This is the single source of truth for deterministic linking in subscribers.
+ */
+interface IEventContext {
+  ownerType: string;
+  ownerId: string;
+  ownerPath: IOwnerPathSegment[];
+  /** Depth of the current execution in the hierarchy (0 = root) */
+  depth?: number;
+  /** Unique span identifier for distributed tracing correlation */
+  spanId?: string;
+  /** Optional structured metadata for debugging/observability */
+  metadata?: TEventLoggerData;
+}
+/**
+ * Allowed extension values for event payloads.
+ */
+type TEventExtensionValue = TEventUniversalValue | TEventLoggerData | Error | IEventContext | IOwnerPathSegment[];
+/**
+ * Base event payload shape.
+ * Emitters may add additional fields, but MUST keep linkage information explicit.
+ */
+interface IBaseEventData {
+  /** Timestamp when the event was emitted. This is required for deterministic ordering. */
+  timestamp: Date;
+  /** Optional structured metadata */
+  metadata?: TEventLoggerData;
+  /** Extensible fields for event-specific payloads */
+  [key: string]: TEventExtensionValue | undefined;
+}
+type TEventListener = (eventType: string, data: IBaseEventData, context?: IEventContext) => void;
+/**
+ * Minimal EventService contract for emitting events.
+ */
+interface IEventService {
+  emit(eventType: string, data: IBaseEventData, context?: IEventContext): void;
+  subscribe(listener: TEventListener): void;
+  unsubscribe(listener: TEventListener): void;
+}
+//#endregion
+//#region src/interfaces/tool.d.ts
+type TToolContextExtensionValue = TUniversalValue | Date | Error | TLoggerData | TContextData | TToolParameters | TToolMetadata;
+/**
+ * Tool metadata structure - specific type definition
+ */
+type TToolMetadata = Record<string, string | number | boolean | string[] | number[] | boolean[] | TToolParameters>;
+/**
+ * Tool execution data - domain payload for tool results.
+ *
+ * IMPORTANT:
+ * - This must support structured tool outputs without resorting to `any`.
+ * - Prefer `ToolResultData` (derived from the canonical `UniversalValue` axis).
+ */
+/**
+ * Tool execution result - extended for ToolExecutionData compatibility
+ */
+interface IToolResult {
+  success: boolean;
+  data?: TUniversalValue;
+  error?: string;
+  metadata?: TToolMetadata;
+  [key: string]: TToolContextExtensionValue | undefined;
+}
+/**
+ * Tool execution context - type-safe context for tool execution
+ * Enhanced with hierarchical execution tracking support
+ */
+interface IToolExecutionContext {
+  toolName: string;
+  parameters: TToolParameters;
+  /**
+   * Run-scoped cancellation signal (CORE-018). Long-running tools MUST honor it: terminate
+   * the underlying work (kill the child process, abort the network request) and return an
+   * interrupted/failed result. Completing silently after an abort is a contract violation.
+   */
+  signal?: AbortSignal;
+  /** Direct remote calls deny decisions that would require human interaction. */
+  permissionInteraction?: 'interactive' | 'deny';
+  executionId?: string;
+  userId?: string;
+  sessionId?: string;
+  metadata?: TToolMetadata;
+  /** Parent execution ID for hierarchical tool execution tracking */
+  parentExecutionId?: string;
+  /** Root execution ID (Team/Agent level) for complete execution tree tracking */
+  rootExecutionId?: string;
+  /** Execution depth level (0: Team, 1: Agent, 2: Tool, etc.) */
+  executionLevel?: number;
+  /** Execution path array showing the complete execution hierarchy */
+  executionPath?: string[];
+  /** Real-time execution data for accurate tracking (no simulation) */
+  realTimeData?: {
+    /** Actual execution start time */
+    startTime: Date;
+    /** Actual input parameters passed to the tool */
+    actualParameters: TToolParameters;
+    /** Tool-provided estimated duration (optional) */
+    estimatedDuration?: number;
+  };
+  /**
+   * Additional tool execution context extensions.
+   *
+   * IMPORTANT:
+   * - Avoid ad-hoc top-level fields to keep the contract stable.
+   * - Use this map for forward-compatible extra data with constrained value types.
+   */
+  extensions?: Record<string, TToolContextExtensionValue>;
+  /** Owner context propagated from EventService */
+  ownerType?: string;
+  ownerId?: string;
+  ownerPath?: IOwnerPathSegment[];
+  sourceId?: string;
+  /**
+   * Tool-call scoped EventService instance.
+   * Caller (ExecutionService/ToolExecutionService) is responsible for providing
+   * an ownerPath-bound EventService for this tool call.
+   */
+  eventService?: IEventService;
+  /**
+   * Unbound base EventService instance.
+   *
+   * Required when a tool needs to create another owner-bound EventService
+   * for a different owner (e.g., creating an agent from a tool call).
+   *
+   * NOTE: Do not wrap an already owner-bound EventService to bind a different owner.
+   * Owner-bound instances must not be layered across different owners.
+   */
+  baseEventService?: IEventService;
+  /**
+   * Injected "ask the user" port (CMD-004). Present when an interactive renderer is attached, letting
+   * a tool solicit a structured answer from the user (the model-issued question seam consumed by
+   * CMD-005). Absent in non-interactive contexts; a tool that asks must treat absence as "no human
+   * available" (never a silent guess).
+   */
+  ask?: IUserInteraction['ask'];
+  /**
+   * CLI-1990: the deferred-tool catalog the runtime injects (`ToolExecutionService`), so a search
+   * tool can list what is withheld and load it for the rest of the session. Present on every tool
+   * call the execution loop issues; a tool other than the search tool has no reason to read it.
+   */
+  deferredTools?: IDeferredToolCatalog;
+  /**
+   * The ID core mints for this one tool body, unique even when a vendor reuses its tool call ID.
+   * The body's exported span is derived from it, so it is also what a propagated parent names.
+   */
+  toolBodyId?: string;
+  /**
+   * Present only when the run carries trusted trace context: the `traceparent` naming this body's
+   * span and the exact origins it may be sent to. A tool that makes outbound requests sends it only
+   * to a listed origin.
+   */
+  outboundTraceContext?: IOutboundTraceContext;
+  /**
+   * Present only when the host lets shell children inherit the trace: the environment naming this
+   * body's span. Only the foreground shell tool applies it, to its own child.
+   */
+  shellTraceEnv?: ISubprocessTraceEnv;
+  /**
+   * Present only when the host lets command hooks inherit the trace: the environment naming the
+   * prompt root, for the hooks fired around this body. Separate from {@link shellTraceEnv}, whose
+   * span is the body's own.
+   */
+  hookTraceEnv?: ISubprocessTraceEnv;
+}
+/**
+ * Parameter validation result
+ */
+interface IParameterValidationResult {
+  /** Whether parameters are valid */
+  isValid: boolean;
+  /** Validation error messages */
+  errors: string[];
+}
+/**
+ * Type-safe tool interface with type parameters
+ *
+ * @template TParameters - Tool parameters type (defaults to AbstractToolParameters for backward compatibility)
+ * @template TResult - Tool result type (defaults to ToolResult for backward compatibility)
+ */
+interface IToolContract<TParameters = TToolParameters, TResult = IToolResult> {
+  readonly schema: IToolSchema;
+  execute(parameters: TParameters, context: IToolExecutionContext): Promise<TResult>;
+  validate(parameters: TParameters): boolean;
+  validateParameters(parameters: TParameters): IParameterValidationResult;
+  getDescription(): string;
+  getName(): string;
+}
+/**
+ * Runtime tool instance contract used by Robota internals.
+ *
+ * Tools passed into Agent configuration must support EventService injection
+ * so Robota can emit unified tool lifecycle events.
+ */
+interface IToolWithEventService<TParameters = TToolParameters, TResult = IToolResult> extends IToolContract<TParameters, TResult> {
+  setEventService(eventService: IEventService | undefined): void;
+}
+//#endregion
+//#region src/interfaces/provider-definition.d.ts
+interface IProviderDefinitionConfig {
+  name: string;
+  model: string;
+  apiKey?: string;
+  /**
+   * Name of the environment variable `apiKey` was resolved FROM, when the stored settings value
+   * was a `$ENV:` reference (SEC-009). Config loading resolves such a reference into the secret
+   * itself, which is correct for an in-process provider and wrong for anything that has to
+   * SERIALIZE the config — the resolved value then crosses a boundary the credential's owner
+   * never opted into. Keeping the variable name lets a serializing caller carry the reference and
+   * leave the secret behind; `ISerializableProviderProfile` already declares the same field, and
+   * `resolveProfileApiKey` already reads it.
+   *
+   * Distinct from `sourceEnvVar`, which is set only for a synthesized `'env-default'` config.
+   */
+  apiKeyEnv?: string;
+  baseURL?: string;
+  timeout?: number;
+  options?: Record<string, TUniversalValue>;
+  /**
+   * Resolution origin. `'env-default'` means no settings profile existed and the config
+   * was synthesized from a provider definition's defaults because its `$ENV:` apiKey
+   * reference resolved — callers surface a startup notice for this case.
+   */
+  source?: 'env-default';
+  /**
+   * Name of the environment variable the env-default key was resolved from
+   * (set only when `source` is `'env-default'`) — lets callers name the variable in the
+   * startup notice without exposing the key value.
+   */
+  sourceEnvVar?: string;
+}
+interface IProviderProfileDefaults {
+  model?: string;
+  apiKey?: string;
+  baseURL?: string;
+  timeout?: number;
+  options?: Record<string, TUniversalValue>;
+}
+interface IProviderProfileConfig {
+  type?: string;
+  model?: string;
+  apiKey?: string;
+  baseURL?: string;
+  timeout?: number;
+  options?: Record<string, TUniversalValue>;
+}
+interface IProviderProbeResult {
+  ok: boolean;
+  message: string;
+  models?: string[];
+}
+type TProviderCredentialField = 'apiKey';
+type TProviderSetupField = 'baseURL' | 'model' | TProviderCredentialField;
+type TProviderSetupHelpLinkKind = 'api-key' | 'console' | 'official';
+interface IProviderCredentialRequirement {
+  anyOf: readonly TProviderCredentialField[];
+}
+interface IProviderSetupHelpLink {
+  kind: TProviderSetupHelpLinkKind;
+  label: string;
+  url: string;
+  sourceUrl?: string;
+  lastVerifiedAt?: string;
+}
+type TProviderModelCatalogStatus = 'live' | 'generated' | 'fallback' | 'unavailable';
+type TProviderModelLifecycle = 'active' | 'preview' | 'deprecated' | 'unavailable';
+interface IProviderModelCatalogEntry {
+  id: string;
+  displayName: string;
+  aliases?: readonly string[];
+  contextWindow?: number;
+  capabilities?: readonly TProviderModelCapability[];
+  lifecycle?: TProviderModelLifecycle;
+  lastVerifiedAt?: string;
+  sourceUrl?: string;
+  /**
+   * Per-model USD cost per input/output token (ARCH-PROVIDER-003). This is the correct SSOT home for
+   * cost — it is a per-**model** attribute, not per-provider — consumed by cost-estimating nodes/commands
+   * so pricing is not hardcoded in the execution layer. Both optional; absent means cost is unknown for
+   * this model and estimators must degrade explicitly rather than assume a default price.
+   */
+  costPerInputToken?: number;
+  costPerOutputToken?: number;
+}
+interface IProviderModelCatalog {
+  status: TProviderModelCatalogStatus;
+  entries?: readonly IProviderModelCatalogEntry[];
+  lastVerifiedAt?: string;
+  sourceUrl?: string;
+  message?: string;
+}
+interface IProviderSetupStepDefinition {
+  key: TProviderSetupField;
+  title: string;
+  defaultValue?: string;
+  required?: boolean;
+  masked?: boolean;
+}
+type TProviderCategory = 'cloud-paid' | 'cloud-free' | 'local-free';
+/**
+ * Passive reachability declaration for diagnostics (OBSERVABILITY-1991).
+ *
+ * The host and port a pre-session doctor may TCP-probe when a profile declares no `baseURL` and the
+ * definition declares no `defaults.baseURL` — the case for vendors whose SDK embeds its endpoint. It
+ * is deliberately not a URL and not part of `defaults`: nothing in setup, persistence or provider
+ * construction reads it, so declaring it cannot switch an API surface or persist a base URL. It is
+ * distinct from `probeProfile`, which is an active HTTP probe.
+ */
+interface IProviderEndpoint {
+  readonly host: string;
+  readonly port: number;
+}
+interface IProviderDefinition {
+  type: string;
+  aliases?: readonly string[];
+  displayName?: string;
+  description?: string;
+  /** Billing/hosting category shown as a badge in provider selection UI. */
+  category?: TProviderCategory;
+  defaults?: IProviderProfileDefaults;
+  /**
+   * Optional enforced model allowlist (ARCH-PROVIDER-003). Distinct from {@link modelCatalog}: the catalog
+   * is the *descriptive* model inventory (often `status:'unavailable'` with no entries), whereas
+   * `allowedModels` is the *enforced* execution allowlist — a node rejects a requested model outside it.
+   * When present it should be a subset/override consistent with `modelCatalog.entries[].id`, not a second
+   * drifting inventory. Absent means no allowlist enforcement (any model the provider accepts is allowed).
+   */
+  allowedModels?: readonly string[];
+  /**
+   * INTERIM provider-level cost per token in USD (ARCH-PROVIDER-003), migrated verbatim from the per-vendor
+   * LLM nodes' single `COST_PER_TOKEN_USD` scalar. The correct long-term home is the per-model
+   * {@link IProviderModelCatalogEntry.costPerInputToken}/`costPerOutputToken`; this flat scalar is a
+   * fidelity-preserving interim used only while model catalogs are `status:'unavailable'` (no per-model
+   * entries to attach cost to). Consumed by the collapsed `llm-text` node's `maxCostUsd` estimation. Absent
+   * means cost is unknown for this provider and estimators must degrade explicitly.
+   */
+  costPerTokenUsd?: number;
+  modelCatalog?: IProviderModelCatalog;
+  setupHelpLinks?: readonly IProviderSetupHelpLink[];
+  setupSteps?: readonly IProviderSetupStepDefinition[];
+  credentialRequirement?: IProviderCredentialRequirement;
+  requiresApiKey?: boolean;
+  /**
+   * The environment variables this provider's client reads to decide where it connects or which
+   * credential it sends, beyond its configuration (for example a base-URL variable the SDK falls
+   * back to). A process that builds this provider from another process's configuration must see
+   * the same values, or the credential goes somewhere its owner did not choose.
+   */
+  destinationEnvironment?: readonly string[];
+  createProvider: (config: IProviderDefinitionConfig) => IAIProvider;
+  probeProfile?: (profile: IProviderProfileConfig) => Promise<IProviderProbeResult>;
+  /** Diagnostic-only reachability declaration; read by no setup, persistence or runtime path. */
+  endpoint?: IProviderEndpoint;
+}
+/** The host owns secure persistence; core only admits its opaque reference. */
+interface IToolResultSpillStore {
+  write(content: string): Promise<{
+    readonly reference: string;
+  }>;
+}
+interface IToolResultAdmissionOptions {
+  readonly warningChars?: number;
+  readonly hardChars?: number;
+  readonly repositoryMaxChars?: number;
+  readonly spillStore?: IToolResultSpillStore;
+  readonly onWarning?: (event: {
+    readonly toolName: string;
+    readonly resultChars: number;
+    readonly warningChars: number;
+  }) => void;
+}
+//#endregion
+//#region src/permissions/types.d.ts
+/**
+ * Permission system types — Claude Code compatible permission model.
+ */
+/**
+ * Permission modes (Claude Code compatible)
+ * - plan: read-only tools only
+ * - default: reads auto, writes/bash need approval
+ * - acceptEdits: reads + writes auto, bash needs approval
+ * - bypassPermissions: all tools auto
+ * - auto: reads and in-workspace edits auto; anything else a model classifier decides, and a person
+ *   when the classifier keeps refusing
+ */
+type TPermissionMode = 'plan' | 'default' | 'acceptEdits' | 'bypassPermissions' | 'auto';
+/** Context window state snapshot */
+interface IContextWindowState {
+  /** Max tokens for the current model */
+  maxTokens: number;
+  /** Current estimated token usage (input + cache, excludes output) */
+  usedTokens: number;
+  /** Usage percentage (0-100) */
+  usedPercentage: number;
+  /** Remaining percentage (0-100) */
+  remainingPercentage: number;
+}
+//#endregion
+//#region ../agent-interface-analytics/dist/node/index.d.ts
+//#region src/usage-contracts.d.ts
+/**
+ * @robota-sdk/agent-interface-analytics — usage and run-trace contracts.
+ *
+ * Extracted from `agent-interface-transport`'s `session-contracts.ts` by ARCH-105 (issue #2112).
+ *
+ * This family was declared INSIDE another module rather than as a file of its own, which is why the
+ * extraction split declarations rather than moving a whole file.
+ *
+ * LAYER 0, with an EMPTY dependency set — every field below is a primitive or another declaration in
+ * this file, so the package needs nothing, not even `agent-core`. Consumers compose it downward.
+ */
+/**
+ * ANALYTICS-001: the execution unit a usage snapshot is attributed to, so session-log usage can be
+ * reported and asserted per source (main thread vs a specific subagent / background task). A minimal
+ * contract-layer descriptor — the framework's `IExecutionOrigin` lives a layer up and cannot be
+ * imported here; the two stay aligned by `scope`/`id`.
+ */
+interface IUsageSource {
+  scope: 'main' | 'subagent' | 'background' | 'tool' | 'command' | 'skill';
+  /** Stable id of the source (e.g. the subagent / background-task id); omitted for the main thread. */
+  id?: string;
+  /** Human label for reports (e.g. the agent type or task title). */
+  label?: string;
+}
+//#endregion
+//#region ../agent-interface-command/dist/node/index.d.ts
+//#region src/capability-contracts.d.ts
+/**
+ * Capability descriptor contracts — model-visible capability metadata.
+ *
+ * SSOT for the capability-safety taxonomy shared by command modules and transports.
+ */
+type TCapabilityKind = 'builtin-command' | 'skill' | 'agent' | 'tool';
+type TCapabilitySafety = 'read-only' | 'write' | 'process' | 'network' | 'background-agent';
+interface ICapabilityDescriptor {
+  readonly name: string;
+  readonly kind: TCapabilityKind;
+  readonly description: string;
+  readonly userInvocable: boolean;
+  readonly modelInvocable: boolean;
+  readonly argumentHint?: string;
+  readonly safety?: TCapabilitySafety;
+  /** When false, the projected tool is auto-approved without prompting the user. */
+  readonly requiresPermission?: boolean;
+}
+//#endregion
+//#region src/command-contracts.d.ts
+/**
+ * Origin of a command invocation. `'user'` = the local operator; `'model'` = a model-invoked command;
+ * `'remote'` = a command arriving over a transport (WebSocket / WebRTC) from an untrusted remote peer.
+ * SSOT lives here (the transport-facing `IInteractiveSession.executeCommand` carries it); `agent-framework`
+ * re-exports it. A transport-origin command runs as a local one by default; an optional policy may restrict (REMOTE-006).
+ */
+type TCommandInvocationSource = 'user' | 'model' | 'remote';
+/** A command entry */
+interface ICommand {
+  /** Command name without slash (e.g., "mode") — used for invocation */
+  name: string;
+  /** User-friendly display label (e.g., "Interaction Mode"). Falls back to `name` if not set. */
+  displayName?: string;
+  /** Short description shown in autocomplete */
+  description: string;
+  /** Optional usage example shown in /help output (e.g., "/compact Summarize the context"). */
+  example?: string;
+  /** Source identifier (e.g., "builtin", "skill") */
+  source: string;
+  /** Subcommands for hierarchical menus */
+  subcommands?: ICommand[];
+  /**
+   * When true, the bare command is a complete action of its own (a default view), so choosing it
+   * from a menu runs it rather than opening its subcommands. Declaring subcommands (for example to
+   * narrow what the model may run) then does not change what the user's Enter does.
+   */
+  runsBare?: boolean;
+  /** Execute the command. Args is everything after the command name. */
+  execute?: (args: string) => void | Promise<void>;
+  /** Full SKILL.md content (only for skill commands) */
+  skillContent?: string;
+  /** Hint for the expected argument (Claude Code frontmatter) */
+  argumentHint?: string;
+  /** When true, models cannot invoke this skill autonomously */
+  disableModelInvocation?: boolean;
+  /**
+   * When true, models may invoke this command through the SDK-projected command tool.
+   *
+   * On a SUBCOMMAND entry it narrows what the model may run: once any subcommand of a
+   * model-invocable command declares this flag, the model may run only the bare command and the
+   * subcommands declared `true` — every other first argument, including an alias or a subcommand
+   * added later without the flag, is refused. That is how a command that mixes read-only views with
+   * trust, credential or permission-widening actions offers the model only the safe subset.
+   */
+  modelInvocable?: boolean;
+  /**
+   * What the model is told about this command, when it differs from the short `description` shown
+   * in `/help`: what it does, when to use it, and what it returns. Absent → `description`.
+   */
+  modelDescription?: string;
+  /** When false, users cannot invoke this skill directly */
+  userInvocable?: boolean;
+  /** Safety category for model-visible capability descriptors */
+  safety?: TCapabilitySafety;
+  /** List of tools this skill is allowed to use */
+  allowedTools?: string[];
+  /** Preferred model for executing this skill */
+  model?: string;
+  /** Effort level hint for the skill */
+  effort?: TModelEffort;
+  /** Context scope for the skill (e.g., "project") */
+  context?: string;
+  /** Agent identity to use when executing this skill */
+  agent?: string;
+  /** Plugin installation directory (plugin skills/commands only) */
+  pluginDir?: string;
+}
+/** A source that provides commands */
+interface ICommandSource {
+  name: string;
+  getCommands(): ICommand[];
+}
+/** Status-line command settings persisted in the settings document. */
+interface IStatusLineCommandSettings {
+  enabled: boolean;
+  gitBranch: boolean;
+}
+type TStatusLineCommandSettingsPatch = Partial<IStatusLineCommandSettings> & Record<string, TUniversalValue>;
+/**
+ * SCREEN-2002: the appearance a run renders with, persisted as three FLAT keys in the settings
+ * document (`theme`, `syntaxHighlighting`, `reducedMotion`) rather than one nested object — the
+ * shape `screenReader` and `outputStyle` already use, and the shape a user editing the file by hand
+ * expects. The theme is named by ID, not by value: the settings document never holds a colour, so a
+ * theme that is renamed or removed degrades to a notice instead of persisting stale colours.
+ */
+interface IAppearanceSettings {
+  /** A theme id the registry holds. An unknown id resolves to the default WITH a visible notice. */
+  theme: string;
+  /** Whether fenced code blocks are syntax-highlighted. Orthogonal to the theme. */
+  syntaxHighlighting: boolean;
+  /** Whether animation is suppressed. A flag or the environment can override this for one run. */
+  reducedMotion: boolean;
+}
+type TAppearanceSettingsPatch = Partial<IAppearanceSettings> & Record<string, TUniversalValue>;
+/**
+ * CMD-004 Phase 2: host-executed command ACTIONS — semantic operations the SESSION layer (the host)
+ * executes via `ICommandHostAdapters` or directly on the session, BEFORE the command result is
+ * returned. They execute with zero surfaces attached (headless parity — the LSP
+ * `workspace/executeCommand` model); surfaces observe the outcome via session events / the result,
+ * never by executing the semantics themselves.
+ */
+type TCommandHostAction = {
+  type: 'provider-hot-swap';
+  profileName: string;
+} | {
+  type: 'output-style-change';
+  styleId: string;
+} | {
+  type: 'language-change';
+  language: string;
+} | {
+  type: 'settings-reset';
+} | {
+  type: 'session-exit';
+  reason?: TSessionEndReason;
+  message?: string;
+} | {
+  type: 'session-restart';
+  reason: TSessionEndReason;
+  message: string;
+} | {
+  type: 'session-rename';
+  name: string;
+} |
+/** Move the session to another working directory (`/cd`); `path` is as the user typed it. */
+{
+  type: 'workspace-move';
+  path: string;
+} | {
+  type: 'statusline-settings-patch';
+  patch: TStatusLineCommandSettingsPatch;
+} | {
+  type: 'appearance-settings-patch';
+  patch: TAppearanceSettingsPatch;
+} | {
+  type: 'remote-control-enable';
+} | {
+  type: 'remote-control-stop';
+};
+/**
+ * CMD-004 Phase 2: surface-rendered UI INTENTS — presentation requests (full-screen navigation)
+ * rendered by the surface that issued the command (requester-routed via
+ * `IUiIntentEvent.requesterDriverId`), fire-and-forget. Names are UI-neutral (LSP `window/show*`
+ * style — never a UI-technology token); a surface that cannot render an intent reports an explicit
+ * "not available on this surface" notice, never a silent drop.
+ */
+type TCommandUiIntent = {
+  type: 'show-plugin-manager';
+} | {
+  type: 'show-settings';
+} | {
+  type: 'show-session-picker';
+} | {
+  type: 'show-agent-switcher';
+} | {
+  type: 'show-theme-picker';
+};
+/** Result of a system command execution. */
+interface ICommandResult {
+  /** Human-readable output message */
+  message: string;
+  /** Command completed successfully */
+  success: boolean;
+  /** Additional structured data (command-specific diagnostics only) */
+  data?: Record<string, unknown>;
+  /** CMD-004 Phase 2: host-executed actions — applied by the session layer before the result returns. */
+  hostActions?: readonly TCommandHostAction[];
+  /** CMD-004 Phase 2: UI intents — emitted as `ui_intent` session events routed to the requesting surface. */
+  uiIntents?: readonly TCommandUiIntent[];
+}
+/** Minimal command projection surfaced to host UIs and autocomplete. */
+interface ICommandListEntry {
+  name: string;
+  /** User-friendly display label. Falls back to `name` if not set. */
+  displayName?: string;
+  description: string;
+  /** Optional usage example shown in /help output (e.g., "/compact Summarize the context"). */
+  example?: string;
+  /**
+   * SEC-008: whether a MODEL may invoke this command, carried through instead of dropped.
+   *
+   * The list used to stop at name/description, so every consumer received a flat catalogue with no
+   * way to tell an operator-only command from a model-callable one. The MCP adapter read that list
+   * and registered all of it as callable tools, which turned commands explicitly marked
+   * `modelInvocable: false` — `plugin` installs and enables code — into things a remote peer's model
+   * could call.
+   *
+   * REQUIRED rather than optional, because an optional flag would let a consumer read `undefined`
+   * for two unrelated situations: "this command may not be model-invoked" and "the producer of this
+   * list does not say". Those need different handling and the first must not be reached by accident.
+   */
+  modelInvocable: boolean;
+}
+type TPluginInstallScope = 'user' | 'project';
+interface ICommandInstalledPlugin {
+  name: string;
+  description: string;
+  enabled: boolean;
+}
+interface ICommandAvailablePlugin {
+  name: string;
+  description: string;
+  installed: boolean;
+}
+interface ICommandMarketplaceSource {
+  name: string;
+  type: string;
+}
+interface ICommandPluginReloadResult {
+  loadedPluginCount: number;
+}
+interface ICommandPluginAdapter {
+  listInstalled(): Promise<readonly ICommandInstalledPlugin[]>;
+  listAvailablePlugins(marketplace: string): Promise<readonly ICommandAvailablePlugin[]>;
+  install(pluginId: string, scope?: TPluginInstallScope): Promise<void>;
+  uninstall(pluginId: string): Promise<void>;
+  enable(pluginId: string): Promise<void>;
+  disable(pluginId: string): Promise<void>;
+  marketplaceAdd(source: string): Promise<string>;
+  marketplaceRemove(name: string): Promise<void>;
+  marketplaceUpdate(name: string): Promise<void>;
+  marketplaceList(): Promise<readonly ICommandMarketplaceSource[]>;
+  reloadPlugins(): Promise<ICommandPluginReloadResult>;
+}
+//#endregion
+//#region ../agent-interface-execution/dist/node/index.d.ts
+//#region src/background-task-contracts.d.ts
+type TBackgroundTaskKind = 'agent' | 'process' | 'scheduled' | 'tool-invocation';
+type TBackgroundTaskMode = 'foreground' | 'background';
+type TBackgroundTaskIsolation = 'none' | 'worktree';
+type TBackgroundTaskStatus = 'queued' | 'running' | 'waiting_permission' | 'sleeping' | 'paused' | 'completed' | 'failed' | 'cancelled';
+type TBackgroundTaskTimeoutReason = 'idle' | 'max_runtime' | 'output_limit' | 'repetition' | 'stale_worker';
+type TBackgroundTaskErrorCategory = 'validation' | 'capacity' | 'permission' | 'timeout' | 'runner' | 'crash' | 'provider' | 'process';
+type TBackgroundPrimitive = string | number | boolean;
+interface IBackgroundTaskError {
+  category: TBackgroundTaskErrorCategory;
+  message: string;
+  recoverable: boolean;
+}
+/**
+ * ANALYTICS-001 (Phase 2): token usage a completed task/subagent consumed, for source attribution.
+ * TYPE-003: alias of the `agent-core` usage-triple SSOT (`ITokenUsage`) — derived, not re-declared.
+ */
+type IBackgroundTaskUsage = ITokenUsage;
+interface IBaseBackgroundTaskResult {
+  taskId: string;
+  output: string;
+  metadata?: Record<string, TBackgroundPrimitive>;
+}
+interface IAgentBackgroundTaskResult extends IBaseBackgroundTaskResult {
+  kind: 'agent';
+  /** ANALYTICS-001 (Phase 2): total token usage of an agent task, attributed to it in the parent log. */
+  usage?: IBackgroundTaskUsage;
+}
+interface IProcessBackgroundTaskResult extends IBaseBackgroundTaskResult {
+  kind: 'process';
+  exitCode?: number;
+  signalCode?: string;
+}
+interface IScheduledBackgroundTaskResult extends IBaseBackgroundTaskResult {
+  kind: 'scheduled';
+}
+interface IToolInvocationBackgroundTaskResult extends IBaseBackgroundTaskResult {
+  kind: 'tool-invocation';
+}
+/**
+ * #2079: the outcome hop discriminates by kind exactly as the request hop
+ * (`TBackgroundTaskRequest`) does — `exitCode`/`signalCode` are producible only by the process
+ * runner and `usage` only by the agent runner (`ISubagentJobResult` is now
+ * `Omit<IBackgroundTaskResult<'agent'>, 'kind'>`, not a hand-maintained `Omit` off the flat shape).
+ * `IBackgroundTaskResult<K>` narrows to the kind-specific member for a caller that knows `K`
+ * statically (a runner's `start()`, the decoder once it has
+ * checked `kind`); called with no type argument it stays the full union. `IBackgroundTaskState<K>`
+ * is discriminated the same way, and its `result` field is `IBackgroundTaskResult<K>` — correlated
+ * with `state.kind`, not the free-standing full union.
+ */
+type TBackgroundTaskResult = IAgentBackgroundTaskResult | IProcessBackgroundTaskResult | IScheduledBackgroundTaskResult | IToolInvocationBackgroundTaskResult;
+type IBackgroundTaskResult<K extends TBackgroundTaskKind = TBackgroundTaskKind> = Extract<TBackgroundTaskResult, {
+  kind: K;
+}>;
+/**
+ * #2079: the persisted/live state hop discriminates by kind exactly as the request and result hops
+ * do. Fields a single runner alone can produce — `agentType`/`isolation`/`resumeSessionId`/
+ * `promptPreview`/the worktree-isolation fields (agent), `schedule`/`nextFireAt` (scheduled) — live
+ * only on that kind's member. `commandPreview` is produced by every runner except the agent one (a
+ * process command, a tool-invocation summary, or a schedule's shell command / wake instruction), so
+ * it stays on the three non-agent members, not the base. `pid`/`logPath`/`transcriptPath` stay on
+ * the shared base: the handle SPI (`IBackgroundTaskHandle`) already reports them generically for
+ * whichever runner's process happens to produce them, and a subagent run as a child process (the
+ * worktree-isolation runner) carries a `pid` exactly as a `process`-kind task does — an audit of
+ * every producer (`background-task-manager-helpers.ts`, `subagent-manager.ts`,
+ * `worktree-subagent-runner.ts`) found no case of an agent/process pid being kind-exclusive.
+ * `timeoutReason` is likewise base: `interactive-session-restore.ts` sets `'stale_worker'` on ANY
+ * non-terminal, non-rearmable task regardless of kind, not only on agent tasks.
+ */
+interface IBaseBackgroundTaskState<K extends TBackgroundTaskKind> {
+  id: string;
+  kind: K;
+  label: string;
+  status: TBackgroundTaskStatus;
+  mode: TBackgroundTaskMode;
+  parentSessionId: string;
+  parentTaskId?: string;
+  depth: number;
+  cwd: string;
+  pid?: number;
+  startedAt?: string;
+  updatedAt: string;
+  lastActivityAt?: string;
+  completedAt?: string;
+  currentAction?: string;
+  unread: boolean;
+  result?: IBackgroundTaskResult<K>;
+  error?: IBackgroundTaskError;
+  logPath?: string;
+  transcriptPath?: string;
+  timeoutReason?: TBackgroundTaskTimeoutReason;
+  metadata?: Record<string, TBackgroundPrimitive>;
+}
+interface IAgentBackgroundTaskState extends IBaseBackgroundTaskState<'agent'> {
+  agentType?: string;
+  promptPreview?: string;
+  isolation?: TBackgroundTaskIsolation;
+  /**
+   * CLI-1994: carried from `IAgentBackgroundTaskRequest.resumeSessionId` so a surface can offer to
+   * ATTACH to the forked session — a view switch onto that record, never a merge with the parent.
+   */
+  resumeSessionId?: string;
+  worktreePath?: string;
+  branchName?: string;
+  worktreeStatus?: string;
+  worktreeNextAction?: string;
+  worktreeBaseRevision?: string;
+  parentWorktreeStatus?: string;
+}
+interface IProcessBackgroundTaskState extends IBaseBackgroundTaskState<'process'> {
+  commandPreview?: string;
+}
+interface IScheduledBackgroundTaskState extends IBaseBackgroundTaskState<'scheduled'> {
+  commandPreview?: string;
+  nextFireAt?: string;
+  /**
+   * FLOW-003: for `kind: 'scheduled'` tasks, the reconstructable schedule definition.
+   * Persisted with the task so a resumed session can re-arm the croner job.
+   */
+  schedule?: IBackgroundTaskSchedule;
+}
+interface IToolInvocationBackgroundTaskState extends IBaseBackgroundTaskState<'tool-invocation'> {
+  commandPreview?: string;
+}
+type TBackgroundTaskState = IAgentBackgroundTaskState | IProcessBackgroundTaskState | IScheduledBackgroundTaskState | IToolInvocationBackgroundTaskState;
+type IBackgroundTaskState<K extends TBackgroundTaskKind = TBackgroundTaskKind> = Extract<TBackgroundTaskState, {
+  kind: K;
+}>;
+/** FLOW-003: the persisted, reconstructable definition of a scheduled wake. */
+interface IBackgroundTaskSchedule {
+  cronExpression: string;
+  agentInstruction?: string;
+  command?: string;
+  shell?: string;
+  env?: Record<string, string>;
+}
+interface IBackgroundTaskLogCursor {
+  offset: number;
+}
+interface IBackgroundTaskLogPage {
+  taskId: string;
+  cursor?: IBackgroundTaskLogCursor;
+  nextCursor?: IBackgroundTaskLogCursor;
+  lines: string[];
+}
+interface IBackgroundTaskListFilter {
+  kind?: TBackgroundTaskKind;
+  status?: TBackgroundTaskStatus;
+  mode?: TBackgroundTaskMode;
+  includeClosed?: boolean;
+}
+type TBackgroundTaskEvent = {
+  type: 'background_task_created';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_started';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_updated';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_text_delta';
+  taskId: string;
+  delta: string;
+} | {
+  type: 'background_task_tool_start';
+  taskId: string;
+  toolName: string;
+  firstArg?: string;
+} | {
+  type: 'background_task_tool_end';
+  taskId: string;
+  toolName: string;
+  success: boolean;
+  error?: string;
+} | {
+  type: 'background_task_permission_request';
+  taskId: string;
+  requestId: string;
+  toolName: string;
+  toolArgs: Record<string, TBackgroundPrimitive>;
+} | {
+  type: 'background_task_completed';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_failed';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_cancelled';
+  task: IBackgroundTaskState;
+} | {
+  type: 'background_task_closed';
+  taskId: string;
+} | {
+  type: 'background_task_waking';
+  taskId: string;
+  instruction?: string;
+};
+//#endregion
+//#region src/background-group-contracts.d.ts
+type TBackgroundJobWaitPolicy = 'detached' | 'wait_all' | 'wait_any' | 'manual';
+type TBackgroundJobGroupStatus = 'running' | 'completed';
+interface IBackgroundJobResultEnvelope {
+  taskId: string;
+  label: string;
+  status: TBackgroundTaskStatus;
+  summary?: string;
+  outputRef?: string;
+  error?: IBackgroundTaskError;
+  startedAt?: string;
+  completedAt?: string;
+}
+interface IBackgroundJobGroupState {
+  id: string;
+  parentSessionId: string;
+  waitPolicy: TBackgroundJobWaitPolicy;
+  taskIds: string[];
+  status: TBackgroundJobGroupStatus;
+  createdAt: string;
+  updatedAt: string;
+  label?: string;
+  completedAt?: string;
+  results: IBackgroundJobResultEnvelope[];
+}
+interface IBackgroundJobGroupCreateRequest {
+  parentSessionId: string;
+  waitPolicy: TBackgroundJobWaitPolicy;
+  taskIds: string[];
+  label?: string;
+}
+type TBackgroundJobGroupEvent = {
+  type: 'background_job_group_created';
+  group: IBackgroundJobGroupState;
+} | {
+  type: 'background_job_group_updated';
+  group: IBackgroundJobGroupState;
+} | {
+  type: 'background_job_group_completed';
+  group: IBackgroundJobGroupState;
+};
+//#endregion
+//#region src/subagent-contracts.d.ts
+/**
+ * TYPE-003: derived from the background-task status SSOT ({@link TBackgroundTaskStatus}) instead of
+ * a second hand-maintained union — a status added to the SSOT now flows here mechanically (the
+ * prior manual copy silently missed `paused` when SELFHOST-012 added it). `paused` is excluded on
+ * purpose: it is a scheduled-task-only status and a subagent is never a scheduled task
+ * (`SubagentManager.toSubagentState` maps it to `sleeping`).
+ */
+type TSubagentJobStatus = Exclude<TBackgroundTaskStatus, 'paused'>;
+/**
+ * Subagent-job projection of {@link IBackgroundTaskState}.
+ *
+ * TYPE-003: every field a subagent job shares with the background-task SSOT is derived via `Pick`
+ * (previously a ~20-field manual mirror that could drift silently). Only the genuinely
+ * subagent-specific fields are declared here:
+ * - `type` — the agent-definition type (the task-side counterpart is the optional `agentType`);
+ * - `status` — the derived {@link TSubagentJobStatus} (no `paused`);
+ * - `promptPreview` — required here (every subagent job is created from a prompt; optional on tasks);
+ * - `currentTool` — the job-level projection of the task's free-form `currentAction`;
+ * - `result`/`error` — flattened display strings (the task carries structured
+ *   `IBackgroundTaskResult`/`IBackgroundTaskError` objects).
+ */
+interface ISubagentJobState extends Pick<IBackgroundTaskState<'agent'>, 'id' | 'label' | 'parentSessionId' | 'mode' | 'depth' | 'pid' | 'cwd' | 'isolation' | 'resumeSessionId' | 'worktreePath' | 'branchName' | 'worktreeStatus' | 'worktreeNextAction' | 'worktreeBaseRevision' | 'parentWorktreeStatus' | 'logPath' | 'transcriptPath' | 'startedAt' | 'updatedAt' | 'completedAt' | 'timeoutReason' | 'metadata'> {
+  type: string;
+  status: TSubagentJobStatus;
+  promptPreview: string;
+  currentTool?: string;
+  result?: string;
+  error?: string;
+}
+//#endregion
+//#region ../agent-interface-session/dist/node/session-contracts-BVCzd3uY.d.ts
+//#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/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;
+}
+/**
+ * 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;
+}
+/**
+ * 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[];
+}
+/** 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;
+}
+/** 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
+//#region ../agent-executor/dist/node/index.d.ts
+/** SELFHOST-012: an in-place schedule edit — any provided field replaces the current value; identity is kept. */
+interface IScheduleEditPatch {
+  cronExpression?: string;
+  agentInstruction?: string;
+  command?: string;
+  /** CMD-009: the list-view label summarizes the instruction, so an edit may refresh it too. */
+  label?: string;
+}
+//#endregion
+//#region ../agent-core/dist/node/node.d.ts
+//#endregion
+//#region src/utils/egress-policy.d.ts
+type TEgressLookup = (hostname: string) => Promise<readonly string[]>;
+interface IEgressPolicy {
+  /** Exact lowercase hostnames that may be reached even when they resolve to a private address. */
+  readonly allowedHosts?: readonly string[];
+  /** Explicit enterprise opt-out from private/loopback/metadata blocking. Default `false`. */
+  readonly allowPrivateAddresses?: boolean;
+  /** Redirect hops followed before refusing. Default 5. */
+  readonly maxRedirects?: number;
+}
+//#endregion
+//#region ../agent-session/dist/node/index.d.ts
+type TAutoCompactThreshold = number | false;
+//#endregion
+//#region src/permission-denial-log.d.ts
+/**
+ * Why a call was refused:
+ * - `policy`      — the gate answered deny: a deny rule, a background ceiling, or plan mode;
+ * - `user`        — a person was asked and declined, or the turn was cancelled while asking;
+ * - `no-approver` — the call needed a person and none was attached;
+ * - `classifier`  — in `auto` mode, the classifier blocked the call or gave no usable verdict.
+ */
+type TPermissionDenialReason = 'policy' | 'user' | 'no-approver' | 'classifier';
+interface IPermissionDenial {
+  readonly toolName: string;
+  /** The argument the tool's permission profile names (command, path, URL), when it has one. */
+  readonly argument?: string;
+  readonly reason: TPermissionDenialReason;
+  /** The classifier's reason, for a `classifier` denial. */
+  readonly detail?: string;
+  /** Epoch milliseconds. */
+  readonly at: number;
+}
+//#endregion
+//#region src/session-log-validation.d.ts
+interface ISessionReplayValidationIssue {
+  code: 'PROVIDER_RESPONSE_RAW_MISSING' | 'PROVIDER_NATIVE_RAW_PAYLOAD_MISSING' | 'PROVIDER_RESPONSE_NORMALIZED_MISSING' | 'TOOL_RESULT_MISSING' | 'PAYLOAD_REFERENCE_INVALID' | 'UNRESOLVED_REPLAY_PAYLOAD';
+  message: string;
+  eventIndex?: number;
+  executionId?: string;
+  round?: number;
+  toolCallId?: string;
+}
+interface ISessionReplayValidationResult {
+  ok: boolean;
+  issues: ISessionReplayValidationIssue[];
+}
+//#endregion
+//#region ../agent-interface-session-mobility/dist/node/index.d.ts
+/**
+ * How two sessions' workspaces relate. `unknown` covers a session outside git, one that published no
+ * claim, and a claim whose path did not read back as claimed — a claim is checked, never taken as
+ * written.
+ */
+type TWorkspaceRelation = 'same-worktree' | 'same-repo' | 'different-repo' | 'unknown';
+//#endregion
+//#region ../agent-framework/dist/node/createInteractiveRuntime-GD7gJ7ig.d.ts
+//#region src/effort/effort-resolution.d.ts
+type TEffortSelection = TModelEffort | 'auto';
+type TEffortSource = 'command' | 'flag' | 'environment' | 'settings' | 'preset' | 'model-default';
+type TEffortDisposition = 'applied' | 'model-default' | 'clamped' | 'not-applied';
+interface IModelEffortResolution {
+  readonly requested: TEffortSelection;
+  readonly effective: TModelEffort;
+  readonly source: TEffortSource;
+  readonly disposition: TEffortDisposition;
+  readonly modelDefault: TModelEffort;
+  readonly reason?: string;
+}
+interface IEditCheckpointSummary {
+  id: string;
+  sessionId: string;
+  sequence: number;
+  prompt: string;
+  createdAt: string;
+  fileCount: number;
+}
+type TEditCheckpointFileRestoreAction = 'restore-preimage' | 'delete-created-file';
+interface IEditCheckpointFileInspection {
+  originalPath: string;
+  relativePath: string;
+  existed: boolean;
+  restoreAction: TEditCheckpointFileRestoreAction;
+  snapshotAvailable: boolean;
+  snapshotSizeBytes?: number;
+}
+interface IEditCheckpointInspectionPlan {
+  checkpointIds: string[];
+  fileCount: number;
+}
+interface IEditCheckpointInspection {
+  target: IEditCheckpointSummary;
+  capturedFiles: IEditCheckpointFileInspection[];
+  restoreToCheckpoint: IEditCheckpointInspectionPlan;
+  rollbackThroughCheckpoint: IEditCheckpointInspectionPlan;
+}
+interface IEditCheckpointRestoreResult {
+  target: IEditCheckpointSummary;
+  restoredCheckpointCount: number;
+  restoredFileCount: number;
+  removedCheckpointCount: number;
+}
+//#endregion
+//#region src/command-api/host-context-types.d.ts
+interface ICommandSkillListEntry {
+  readonly name: string;
+  readonly description: string;
+  readonly source: string;
+  readonly modelInvocable: boolean;
+  readonly userInvocable: boolean;
+  readonly argumentHint?: string;
+  readonly context?: string;
+  readonly agent?: string;
+}
+interface ICommandSkillActivationRequest {
+  readonly invocationSource: TCommandInvocationSource;
+  readonly displayInput?: string;
+  readonly rawInput?: string;
+}
+type TAutoCompactThresholdSource = 'default' | 'settings' | 'session';
+/**
+ * Live model re-application options (PRESET-013). Carries the model group a preset switch may
+ * re-apply to a running session; `maxOutputTokens` maps to the agent's `maxTokens` channel.
+ */
+interface IModelReapplyOptions {
+  model?: string;
+  effort?: TModelEffortSelection;
+  temperature?: number;
+  maxOutputTokens?: number;
+}
+/**
+ * A preset `enabledCommandModules`/`disabledCommandModules` name that matched no built command
+ * module (INFRA-032). Surfaced as a non-fatal notice on both the startup `--preset` path and the
+ * in-session `/preset` path instead of being silently dropped. `kind` records which list the
+ * unmatched name came from.
+ */
+interface IUnknownCommandModuleName {
+  readonly name: string;
+  readonly kind: 'enabled' | 'disabled';
+}
+interface ICommandSessionReplayValidationReport {
+  logFile: string;
+  entryCount: number;
+  validation: ISessionReplayValidationResult;
+}
+//#endregion
+//#region src/command-api/session-roles.d.ts
+/** Reading and clearing the conversation the session holds. */
+interface ICommandSessionHistory {
+  clearHistory(): void;
+  getMessageCount(): number;
+  getFullHistory(): IHistoryEntry[];
+  getHistory(): TUniversalMessage[];
+}
+/** The session's context window and its compaction policy. */
+interface ICommandSessionContextWindow {
+  compact(instructions?: string): Promise<void>;
+  getContextState(): IContextWindowState;
+  getAutoCompactThreshold(): number | false;
+  setAutoCompactThreshold(threshold: TAutoCompactThreshold): void;
+}
+/** What the session is currently permitted to do. */
+interface ICommandSessionPermissions {
+  getPermissionMode(): TPermissionMode;
+  setPermissionMode(mode: TPermissionMode): void;
+  getSessionAllowedTools(): readonly string[];
+  /** The allow/deny/ask rules the gate reads right now, whatever layer or preset supplied them. */
+  getPermissionRules(): {
+    readonly allow: readonly string[];
+    readonly deny: readonly string[];
+    readonly ask: readonly string[];
+  };
+  /** The calls this session refused, most recent first. */
+  getRecentPermissionDenials(): readonly IPermissionDenial[];
+  /** Let the call behind a classifier denial (0-based) run once; `undefined` when there is none. */
+  retryPermissionDenial(index: number): IPermissionDenial | undefined;
+  /**
+   * ARCH-040 Group C (issue #1934): re-apply a preset's tool lists to the LIVE enforcer.
+   *
+   * REQUIRED, not optional. An optional member would let every consumer invent its own answer for an
+   * absent one, and the answer here governs permissions — a runtime that quietly did nothing would
+   * be the startup/live divergence this seam exists to close, wearing a different hat.
+   *
+   * Without it the startup path could apply a preset's tool lists and `/preset` could not: one
+   * session holding two answers for the same preset depending on WHEN it was chosen.
+   */
+  applyPresetToolLists(preset: {
+    allowedTools?: readonly string[];
+    deniedTools?: readonly string[];
+  }): void;
+}
+/**
+ * The tool schemas this session puts in front of the model (CLI-1990).
+ *
+ * The OFFERED set, not the registered one: with deferral engaged, a withheld tool's schema never
+ * reaches the request, and `/context` reports what the request actually costs. Reading it is how the
+ * saving deferral produces becomes observable at all — before this, no surface separated the tool
+ * schemas from the system prompt they are billed alongside.
+ */
+interface ICommandSessionTools {
+  getOfferedToolSchemas(): IToolSchema[];
+  /**
+   * Offer tools that became usable mid-session — an MCP server connected after its sign-in — from
+   * the next turn on (never within a running turn), under the same wrappers and permission gate as
+   * the session's own. A name the session already has is left out, never replaced. Resolves to the
+   * names that will be offered.
+   */
+  addTools(tools: readonly IToolWithEventService[]): Promise<readonly string[]>;
+}
+/** Who this session is, and what it has spent. */
+interface ICommandSessionIdentity {
+  getSessionId(): string;
+  getSessionTokenUsage(): {
+    inputTokens: number;
+    outputTokens: number;
+  } | undefined;
+  getModelId(): string | undefined;
+}
+/** Live model reconfiguration. */
+interface ICommandSessionModel {
+  /**
+   * Re-apply model/effort/temperature/maxOutputTokens to the live session (PRESET-013).
+   * May be async: the runtime ensures the agent is fully initialized before mutating its model
+   * configuration, so callers must await the result.
+   */
+  applyModelOptions(options: IModelReapplyOptions): void | Promise<void>;
+  /** Read the model-effort selection for the next model call. */
+  getModelEffort(): TModelEffortSelection;
+  /**
+   * ARCH-040 — re-apply the preset's `agentName` to the live agent.
+   *
+   * REQUIRED, like every other member of this role port: an optional one would make each consumer
+   * decide what "no rename seam" means, and `/preset` would decide it alone.
+   */
+  applyAgentName(name: string): void | Promise<void>;
+}
+/** Live preset state carried by the session. */
+interface ICommandSessionPreset {
+  /** Read the active preset id (PRESET-011 runtime state). */
+  getActivePresetId(): string;
+  /** Set the active preset id (PRESET-011 runtime state — pure state, no option re-application). */
+  setActivePresetId(id: string): void;
+  /** Toggle subagent dispatch live for the running session (PRESET-016 runtime gate). */
+  setParallelSubagentsEnabled(enabled: boolean): void;
+}
+/** Aggregate: every member remains source-compatible. Declare a role port instead of this. */
+interface ICommandSessionRuntime extends ICommandSessionHistory, ICommandSessionContextWindow, ICommandSessionPermissions, ICommandSessionIdentity, ICommandSessionModel, ICommandSessionPreset, ICommandSessionTools {}
+//#endregion
+//#region src/command-api/session/session-usage.d.ts
+interface ISessionUsageRecord {
+  readonly promptTokens: number;
+  readonly completionTokens: number;
+  /** Present when the usage was priced on the model that produced it. */
+  readonly costUsd?: number;
+  /** Who spent it; absent for the main thread. */
+  readonly source?: IUsageSource;
+}
+//#endregion
+//#region src/command-api/agent-job-roles.d.ts
+/** Starting, steering and ending subagent jobs. */
+interface IAgentJobDispatch {
+  listAgentDefinitions(): Array<{
+    name: string;
+    description: string;
+  }>;
+  listAgentJobs(): ISubagentJobState[];
+  spawnAgentJob(input: {
+    agentType: string;
+    label: string;
+    mode: 'foreground' | 'background';
+    prompt: string;
+    model?: string;
+    isolation?: TBackgroundTaskIsolation;
+    /** CLI-1994: the forked session record the job restores before its first turn (id only). */
+    resumeSessionId?: string;
+  }): Promise<ISubagentJobState>;
+  sendAgentJob(taskId: string, prompt: string): Promise<void>;
+  cancelAgentJob(taskId: string, reason?: string): Promise<void>;
+  closeAgentJob(taskId: string): Promise<void>;
+}
+/** Fanning jobs out as a group and waiting on it. */
+interface IAgentJobGroups {
+  createBackgroundJobGroup(input: Omit<IBackgroundJobGroupCreateRequest, 'parentSessionId'>): IBackgroundJobGroupState;
+  waitBackgroundJobGroup(groupId: string): Promise<IBackgroundJobGroupState>;
+}
+/** Cron-driven wakes and their lifecycle. */
+interface IAgentJobSchedules {
+  /** Optional for hosts without a persisted interactive session. */
+  createSelfPacedLoop?(instruction: string, options?: {
+    useDefaultPrompt?: boolean;
+  }): Promise<ISessionLoopState>;
+  listSelfPacedLoops?(): readonly ISessionLoopState[];
+  stopSelfPacedLoop?(loopId: string, reason?: string): Promise<void>;
+  /**
+   * FLOW-005: schedule a recurring/one-shot agent wake. On each cron fire the agent loop
+   * re-enters with `agentInstruction` (FLOW-001/002). `cronExpression` may be a standard cron
+   * string or an ISO timestamp (one-shot).
+   */
+  spawnScheduledWake(input: {
+    label: string;
+    cronExpression: string;
+    agentInstruction: string;
+    /** Session-loop identity marker; kept apart from the editable display label. */
+    sessionLoop?: boolean;
+    /** Stable loop id carried in persisted task metadata across runtime task-id remapping. */
+    sessionLoopId?: string;
+    /** Re-resolve the product-owned default prompt before each fixed-loop iteration. */
+    sessionLoopDefaultPrompt?: boolean;
+    /** Earliest instant at which the first scheduled loop wake may enter the session. */
+    sessionLoopFirstAllowedAt?: string;
+    /** Absolute expiry for a session loop; persisted with its stable identity. */
+    sessionLoopExpiresAt?: string;
+  }): Promise<IBackgroundTaskState>;
+  /** SELFHOST-012: list the caller's scheduled tasks (each carries cadence, `nextFireAt`, and status). */
+  listSchedules(): IBackgroundTaskState[];
+  /** SELFHOST-012: non-destructively pause a scheduled task — it stops firing until `resumeSchedule`. */
+  pauseSchedule(taskId: string): Promise<void>;
+  /** SELFHOST-012: resume a paused scheduled task, re-armed with the same identity. */
+  resumeSchedule(taskId: string): Promise<void>;
+  /** SELFHOST-012: edit a scheduled task's cron / instruction in place (same task id). */
+  editSchedule(taskId: string, patch: IScheduleEditPatch): Promise<void>;
+}
+/** Output-driven wakes. */
+interface IAgentJobMonitors {
+  /**
+   * FLOW-005: monitor a process's output and wake the agent with `agentInstruction` when a
+   * line matches `matchPattern` (FLOW-004). When the model asked for it, the command is first
+   * decided by the shell tool's gate; a refusal rejects with {@link MonitorCommandRefusedError}.
+   */
+  spawnMonitorWake(input: {
+    label: string;
+    command: string;
+    matchPattern: string;
+    agentInstruction: string;
+  }): Promise<IBackgroundTaskState>;
+}
+/** Reading a job's output. */
+interface IAgentJobLogs {
+  readBackgroundTaskLog(taskId: string, cursor?: IBackgroundTaskLogCursor): Promise<IBackgroundTaskLogPage>;
+}
+/** Aggregate: all 15 members remain source-compatible. Declare a role port instead of this. */
+interface IAgentJobHostContext extends IAgentJobDispatch, IAgentJobGroups, IAgentJobSchedules, IAgentJobMonitors, IAgentJobLogs {}
+//#endregion
+//#region src/command-api/preset/preset-application-types.d.ts
+/**
+ * Resolved-preset option subset that can be re-applied to a *live* session.
+ *
+ * This is a framework-owned shape. The agent-preset package's `IResolvedPresetOptions` satisfies it
+ * structurally, so a consumer can hand a `resolvePreset(...)` result straight to
+ * {@link applyPresetToSession} without framework importing agent-preset (no dependency cycle).
+ *
+ * PRESET-012 carries the permission/trust group (`permissionMode`); PRESET-013 adds the model group
+ * (`model`, `effort`, `temperature`, `maxOutputTokens`); PRESET-014 adds the `persona` block,
+ * re-applied to the live system prompt; PRESET-015 adds the command-module selection group
+ * (`enabledCommandModules`/`disabledCommandModules`), re-filtered against the session-start set.
+ */
+interface IPresetApplicationOptions {
+  permissionMode?: TPermissionMode;
+  model?: string;
+  effort?: TModelEffortSelection;
+  temperature?: number;
+  maxOutputTokens?: number;
+  /** PRESET-014 — preset persona re-applied to the live system prompt. */
+  persona?: string;
+  /** ARCH-040 — the agent's identity label, re-applied to the live agent. */
+  agentName?: string;
+  /** ARCH-040 — response language, re-applied as a prompt section. */
+  language?: string;
+  /** ARCH-040 — a preset-supplied system prompt that SEEDS the composed prompt (priority 4). */
+  systemPrompt?: string;
+  /**
+   * ARCH-040 Group C — the preset's tool lists, re-applied to the live enforcer.
+   *
+   * An allowlist REPLACES what the preset layer previously contributed; a denylist UNIONS, because a
+   * denial is not weakened by a later layer that forgot to repeat it. Both halves ship together: an
+   * allowlist that replaces while its paired denylist stayed behind would widen what the session
+   * permits, which is the failure the pairing exists to prevent.
+   */
+  allowedTools?: readonly string[];
+  deniedTools?: readonly string[];
+  /** PRESET-015 — allowlist of command-module names to keep on the live session. */
+  enabledCommandModules?: readonly string[];
+  /** PRESET-015 — denylist of command-module names to remove from the live session. */
+  disabledCommandModules?: readonly string[];
+  /** PRESET-016 — runtime gate toggle for subagent dispatch on the live session. */
+  enableParallelSubagents?: boolean;
+  /** PRESET-017 — toggle the verify-before-done self-verification section on the live prompt. */
+  selfVerification?: boolean;
+}
+//#endregion
+//#region src/context/output-style-prompt.d.ts
+/** Prompt-only projection of an output style. The preset package's richer value satisfies this shape. */
+interface IOutputStylePrompt {
+  readonly id: string;
+  readonly name: string;
+  readonly instructions: string;
+  readonly keepCodingInstructions: boolean;
+  readonly tokenCost?: string;
+}
+//#endregion
+//#region src/workspace-trust/types.d.ts
+declare const workspaceProjectAuthorityType: unique symbol;
+declare const workspaceProjectSettingsWriterType: unique symbol;
+declare const workspaceProjectMutationType: unique symbol;
+/**
+ * Opaque proof that the host granted project access for the currently resolved workspace identity.
+ * Runtime acceptance is stricter than this type: only an exact service-minted object is accepted.
+ */
+interface IWorkspaceProjectAuthority {
+  readonly [workspaceProjectAuthorityType]: true;
+}
+type TWorkspaceTrustState = 'trusted' | 'untrusted' | 'revoked' | 'stale/replaced' | 'identity-unavailable' | 'store-unavailable';
+interface IWorkspaceIdentity {
+  readonly repositoryKey: string;
+  readonly displayPath: string;
+  readonly worktreeRoot: string;
+}
+type TWorkspaceProjectSettingsTarget = 'project' | 'project-local';
+interface IWorkspaceProjectSettingsWriter {
+  readonly [workspaceProjectSettingsWriterType]: true;
+  readonly target: TWorkspaceProjectSettingsTarget;
+  readonly relativePath: string;
+  writeText(content: string): void;
+}
+/** Root-bounded mutation authority minted separately from trusted project reads. */
+interface IWorkspaceProjectMutation {
+  readonly [workspaceProjectMutationType]: true;
+  writeBytes(relativePath: string, content: Uint8Array, purpose: string): void;
+  deleteFile(relativePath: string, purpose: string): boolean;
+}
+interface ITrustedWorkspaceProjectAccess {
+  readonly status: 'trusted';
+  readonly authority: IWorkspaceProjectAuthority;
+  readonly identity: IWorkspaceIdentity;
+  readonly grantedAt?: string;
+}
+/**
+ * The owner error behind an `identity-unavailable` or `store-unavailable` trust state
+ * (OBSERVABILITY-1991). Name and message only — never file content.
+ */
+interface IWorkspaceTrustCause {
+  readonly name: string;
+  readonly message: string;
+}
+interface IRestrictedWorkspaceProjectAccess {
+  readonly status: 'restricted';
+  readonly reason: 'WorkspaceAuthorityRequired';
+  readonly trustState: Exclude<TWorkspaceTrustState, 'trusted'>;
+  readonly displayPath?: string;
+  /**
+   * SCREEN-1993: the identity the trust service resolved before deciding the state — present for
+   * every state except `identity-unavailable`, so a consumer that needs the worktree root (the
+   * prompt-history project key) reads the one resolution already made instead of resolving again.
+   */
+  readonly identity?: IWorkspaceIdentity;
+  /** Present when the state was caused by a swallowed identity/store error a diagnostic should name. */
+  readonly cause?: IWorkspaceTrustCause;
+}
+type TWorkspaceProjectAccess = ITrustedWorkspaceProjectAccess | IRestrictedWorkspaceProjectAccess;
+interface IAdvisorStatus {
+  /** The target, as `profile` or `profile:model`; absent when none is set. */
+  readonly target?: string;
+  readonly enabled: boolean;
+  /** Whether this session has the Advisor tool (decided at session start). */
+  readonly registered: boolean;
+  readonly killSwitch: boolean;
+  readonly sessionCalls: number;
+  readonly maxCallsPerSession: number;
+}
+interface IAdvisorSetResult {
+  readonly success: boolean;
+  readonly message: string;
+  /** The spec to save as the default, or `'off'`; absent when nothing changed. */
+  readonly saved?: string;
+}
+/** What `/advisor` reads and changes on the live session. */
+interface ICommandAdvisorAdapter {
+  status(): IAdvisorStatus;
+  set(value: string): IAdvisorSetResult;
+}
+//#endregion
+//#region src/command-api/host-adapters.d.ts
+interface ICommandSettingsDocument {
+  [key: string]: TUniversalValue;
+}
+interface ICommandSettingsAdapter<TSettings extends ICommandSettingsDocument = ICommandSettingsDocument> {
+  read(): TSettings;
+  write(settings: TSettings): void;
+  /**
+   * CMD-004 Phase 2: delete the settings document (the host-executed `settings-reset` action).
+   * Returns `true` when a document existed and was removed. Optional — a composition that does not
+   * wire it makes the reset action fail EXPLICITLY in the command result (no-fallback), never a
+   * silent skip.
+   */
+  delete?(): boolean;
+}
+interface ICommandProcessAdapter {
+  requestExit(reason?: TSessionEndReason): void;
+  requestRestart(reason: TSessionEndReason, message: string): void;
+}
+interface ICommandPermissionModeAdapter {
+  getPermissionMode(): TPermissionMode;
+  setPermissionMode(mode: TPermissionMode): void;
+  listSessionAllowedTools(): readonly string[];
+  /** The allow/deny/ask rules the gate reads right now. */
+  getPermissionRules(): {
+    readonly allow: readonly string[];
+    readonly deny: readonly string[];
+    readonly ask: readonly string[];
+  };
+  /** The calls the session refused, most recent first. */
+  listRecentDenials(): readonly IPermissionDenial[];
+  /** Let the call behind a classifier denial (0-based) run once; `undefined` when there is none. */
+  retryDenial(index: number): IPermissionDenial | undefined;
+}
+/** The permission rules one settings layer declares, named the way the user would find the file. */
+interface IPermissionRuleLayer {
+  /** The file as the user would find it, e.g. `~/.robota/settings.json`. */
+  readonly source: string;
+  readonly scope: string;
+  readonly allow: readonly string[];
+  readonly deny: readonly string[];
+  readonly ask: readonly string[];
+}
+/** Where each configured permission rule comes from, read fresh on every call. */
+interface ICommandPermissionRulesAdapter {
+  readLayers(): readonly IPermissionRuleLayer[];
+}
+/** How shell commands are confined: not at all, confined without prompts, or confined and asked. */
+type TSandboxCommandMode = 'off' | 'auto-allow' | 'regular';
+interface ICommandSandboxStatus {
+  readonly mode: TSandboxCommandMode;
+  /** `bubblewrap` or `seatbelt`; absent where the platform has none. */
+  readonly backend?: string;
+  /** Why confinement cannot run here, when it cannot: what to install, or the platform. */
+  readonly unavailable?: string;
+  readonly network: boolean;
+  readonly excludedCommands: readonly string[];
+}
+/** The OS sandbox, live: `/sandbox` reads it and changes the mode for the next command. */
+interface ICommandSandboxAdapter {
+  status(): ICommandSandboxStatus;
+  /** Apply the mode now and save it in the user settings. */
+  setMode(mode: TSandboxCommandMode): void;
+}
+/** Live model-effort state and application seam supplied by the composition root. */
+interface ICommandEffortAdapter {
+  getResolution(): IModelEffortResolution;
+  apply(selection: TEffortSelection, session: ICommandSessionModel): IModelEffortResolution | Promise<IModelEffortResolution>;
+}
+/**
+ * REMOTE-008: view of `/remote-control` state, so the command can report status without touching the
+ * transport. CMD-004 Phase 2 supersedes the original status-only design: the enable/stop ACTIONS are
+ * now host-executed through this adapter (wired at the composition root) instead of surface-rendered
+ * legacy command effects, so they work on every surface (remote/headless included).
+ */
+type TRemoteControlStatus = {
+  readonly state: 'off';
+} | {
+  readonly state: 'no-relay';
+} | {
+  readonly state: 'awaiting-pairing';
+  readonly pairingUrl: string;
+} | {
+  readonly state: 'paired';
+};
+/** A trusted device summary for `/remote-control devices` (public data only; REMOTE-012 E3). */
+interface IRemoteTrustedDeviceSummary {
+  readonly deviceId: string;
+  readonly label: string;
+  readonly lastSeenAt: string;
+}
+interface ICommandRemoteControlAdapter {
+  getStatus(): TRemoteControlStatus;
+  /** REMOTE-012 E3: enrolled trusted devices (for `/remote-control devices`). Absent → TOFU not available. */
+  listDevices?(): IRemoteTrustedDeviceSummary[];
+  /** REMOTE-012 E3: revoke a trusted device by id (for `/remote-control revoke <id>`); returns true if removed. */
+  revokeDevice?(deviceId: string): boolean;
+  /**
+   * Where the host keeps its identity key, in one line for the operator (for `/remote-control
+   * status`), or `undefined` while no key has been needed yet. Absent ⇒ the host keeps no key.
+   */
+  describeKeyStorage?(): string | undefined;
+  /**
+   * CMD-004 Phase 2: enable remote control (host-executed `remote-control-enable` action). Resolves
+   * to the user-facing message (pairing QR/link, or a fail-closed notice) which the host folds into
+   * the command result. Absent ⇒ the action fails explicitly in the result (no-fallback).
+   */
+  enable?(): string | Promise<string>;
+  /** CMD-004 Phase 2: stop remote control; resolves to the user-facing message (see {@link enable}). */
+  stop?(): string | Promise<string>;
+}
+/**
+ * MCP-2520 — public, secret-free view of one resolved MCP definition. The command layer can show
+ * this value and request a decision, but it cannot construct or connect an MCP client.
+ */
+interface ICommandMCPActivationSummary {
+  readonly serverId: string;
+  readonly displayName?: string;
+  readonly source: 'managed' | 'user' | 'project' | 'plugin' | 'local';
+  readonly status: 'approved' | 'pending' | 'rejected' | 'revoked' | 'stale' | 'untrusted';
+  readonly allowed: boolean;
+  readonly reason: string;
+  readonly provenanceId: string;
+  readonly definitionFingerprint: string;
+  readonly securityIdentity: string;
+}
+/**
+ * A definition-source-level problem — issue #2794: a configuration root that is not an object, no
+ * `mcpServers` key, `mcpServers` not an object, or a source that could not be parsed at all. It
+ * names no server, so it cannot be an `ICommandMCPActivationSummary`; this is its own carrier so
+ * `/mcp status` can say which source could not be read, beside the servers that did resolve.
+ *
+ * `blockedServerNames` (PR #3076 review): when this problem is in the MANAGED tier, `agent-mcp`'s
+ * `resolveByPrecedence` fails closed and blocks every name that would otherwise have resolved from a
+ * lower tier — those names would otherwise vanish from `/mcp status` with no explanation, since a
+ * blocked entry is `unresolved` and `ICommandMCPActivationAdapter.list()` only ever offers resolved
+ * candidates. Optional and empty for a non-managed-tier problem, which blocks nothing.
+ */
+interface ICommandMCPSourceProblem {
+  readonly source: 'managed' | 'user' | 'project' | 'plugin' | 'local';
+  readonly origin: string;
+  readonly reason: string;
+  readonly blockedServerNames?: readonly string[];
+}
+/**
+ * One OAuth server's sign-in state as `/mcp` may show it: a fixed word, never a token, scope, expiry
+ * time or anything else derived from a credential.
+ */
+interface ICommandMCPOAuthStatus {
+  readonly serverId: string;
+  readonly state: 'signed-in' | 'expired-refreshable' | 'sign-in-required' | 'signed-out';
+}
+/** What signing out did, by fixed reasons only. */
+interface ICommandMCPOAuthLogoutResult {
+  readonly serverId: string;
+  /** Whether a credential was stored before the sign-out. */
+  readonly removed: boolean;
+  readonly revocation: 'revoked' | 'partial' | 'unsupported' | 'failed' | 'not-attempted';
+  /** The first step that refused, when a revocation was not confirmed. */
+  readonly revocationFailure?: string;
+  /** Each token a revocation was asked for, by kind — never its value. */
+  readonly tokens?: readonly {
+    readonly token: 'refresh_token' | 'access_token';
+    readonly revoked: boolean;
+    readonly failure?: string;
+  }[];
+}
+/** Where the user signs in, shown when they paste the redirect back rather than a listener receiving it. */
+interface ICommandMCPOAuthRedirectPrompt {
+  readonly authorizationUrl: string;
+  /** Where the browser is sent after approval; that page may not load. */
+  readonly redirectUri: string;
+}
+/** One in-session sign-in, as the command asks for it. */
+interface ICommandMCPOAuthLoginRequest {
+  readonly serverId: string;
+  /** Open no browser: the user opens the authorization URL and pastes the redirect back. */
+  readonly noBrowser: boolean;
+  /**
+   * Asks the user, through the session's own prompt, for the redirect URL their browser was sent
+   * to — with `noBrowser`, or when no browser could be opened. Absent: no one can be asked, and a
+   * sign-in that needs a paste is refused before it starts or fails as `browser-failed`.
+   */
+  readonly readRedirect?: (prompt: ICommandMCPOAuthRedirectPrompt, signal: AbortSignal) => Promise<string>;
+  /**
+   * Without `noBrowser`: shows the user the authorization URL before the browser is opened, so a
+   * browser that opens silently or not at all never leaves them waiting on nothing. `paste` switches
+   * to reading the pasted redirect; `cancel` ends the sign-in. Absent: the browser opens directly.
+   */
+  readonly confirmBrowser?: (prompt: ICommandMCPOAuthRedirectPrompt, signal: AbortSignal) => Promise<'open' | 'paste' | 'cancel'>;
+  /** Cancels the sign-in; it then fails as `cancelled` and changes nothing. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * What an in-session sign-in did, by fixed words and reasons only — never a code, token or
+ * authorization-server text.
+ */
+interface ICommandMCPOAuthLoginResult {
+  readonly serverId: string;
+  /** Present when the sign-in did not complete; the session was then left unchanged. */
+  readonly failure?: string;
+  /** Whether the definition names a pre-registered client, which may need a client secret. */
+  readonly preRegisteredClient: boolean;
+  /**
+   * After a sign-in, the server in this session: `connected` with the tools it now offers,
+   * `recovered` when its tools were already offered and its connection works again,
+   * `not-admitted` when admission refused it, `not-connected` when it still could not connect.
+   */
+  readonly connection?: 'connected' | 'recovered' | 'not-admitted' | 'not-connected';
+  /** The tools a newly connected server offers, for the session to add. */
+  readonly tools: readonly IToolWithEventService[];
+}
+/** MCP activation lifecycle port. Implemented by the composition root over the MCP policy service. */
+interface ICommandMCPActivationAdapter {
+  list(): readonly ICommandMCPActivationSummary[];
+  /**
+   * Where the user acts on a command the model suggests: `session` when they can type a `/mcp`
+   * command, `terminal` for a run with no such prompt (sign-in is then the terminal command).
+   * Absent → `session`.
+   */
+  readonly userActionSurface?: 'session' | 'terminal';
+  /**
+   * Every source-level problem from the most recent resolution (issue #2794). Optional so an older
+   * or narrower adapter implementation still satisfies this interface; a caller that wants to render
+   * source problems treats a missing method the same as an empty list.
+   */
+  sourceProblems?(): readonly ICommandMCPSourceProblem[];
+  approve(serverId: string): ICommandMCPActivationSummary | Promise<ICommandMCPActivationSummary>;
+  reject(serverId: string): ICommandMCPActivationSummary | Promise<ICommandMCPActivationSummary>;
+  revoke(serverId: string): ICommandMCPActivationSummary | Promise<ICommandMCPActivationSummary>;
+  /** Sign-in state of every server that declares OAuth. Absent: the host offers no OAuth. */
+  oauthStatus?(): Promise<readonly ICommandMCPOAuthStatus[]>;
+  /** Sign out of one OAuth server. Rejects for a server that does not declare OAuth. */
+  oauthLogout?(serverId: string): Promise<ICommandMCPOAuthLogoutResult>;
+  /**
+   * Sign in to one OAuth server, then connect it in this session through the normal admission.
+   * Never rejects for a failed sign-in: it names the failure. Absent: the host offers no in-session
+   * sign-in.
+   */
+  oauthLogin?(request: ICommandMCPOAuthLoginRequest): Promise<ICommandMCPOAuthLoginResult>;
+  /**
+   * Which of the tools `oauthLogin` returned the session actually took; any other was left out for
+   * a name it already had. Called once per sign-in that returned tools.
+   */
+  oauthToolsAdded?(serverId: string, added: readonly string[]): void;
+}
+/**
+ * PEER-004 (#1863): a live session this one can address, as the operator sees it.
+ *
+ * Display data only. `sessionId` names the peer for a later `send`; `liveness` is carried rather
+ * than filtered so the operator can tell "I could not determine" from "not running" — a host with no
+ * way to read process start times answers `unknown`, and collapsing that into either verdict would
+ * be the guess the registry refuses to make.
+ */
+interface ILocalPeerSummary {
+  readonly sessionId: string;
+  readonly name?: string;
+  readonly liveness: 'alive' | 'dead' | 'unknown';
+  /** Content-free observed activity; unknown when stale or unverified. */
+  readonly status?: 'working' | 'needs-input' | 'idle' | 'unknown';
+  /** How the peer's workspace relates to this one's, judged from what this session read at the claimed path. */
+  readonly workspaceRelation?: TWorkspaceRelation;
+  /** `mismatched` when the peer's claim disagreed with what this session read; it is not believed. */
+  readonly workspaceClaim?: 'verified' | 'mismatched' | 'absent';
+}
+/**
+ * PEER-004: what `/peers` reads. The registry, the guarded directory and the liveness rule all live
+ * in the composition root — a command never touches the filesystem, for the same reason it never
+ * constructs a transport.
+ */
+interface ICommandLocalPeersAdapter {
+  /** Every announced session, this one included. Ordering is the adapter's. */
+  list(): readonly ILocalPeerSummary[];
+  /**
+   * The same rows with each other peer's workspace relation filled in. Separate and asynchronous
+   * because judging a relation reads git; `list` stays cheap for callers that only need liveness.
+   */
+  listWithWorkspace?(): Promise<readonly ILocalPeerSummary[]>;
+  /** This session's own id, so the command can mark which row is the reader. */
+  ownSessionId(): string;
+  /**
+   * PEER-006: hand `text` to another announced session, and report what came back.
+   *
+   * Returns a delivery state rather than throwing, because "the peer refused it" and "the carrier
+   * broke" are both answers the operator needs, and an exception would flatten them into one.
+   * Absent on a host that can discover peers but cannot address them.
+   *
+   * `inReplyTo` names the received message this answers, which threads a conversation; the host
+   * refuses a reply that would run a conversation past its limits, and tells the operator.
+   */
+  send?(targetSessionId: string, text: string, options?: {
+    readonly inReplyTo?: string;
+  }): Promise<ILocalPeerSendResult>;
+}
+/**
+ * PEER-006: what the sender learns, in the vocabulary the operator reads.
+ *
+ * Deliberately not the transport's ack type: the command layer must not import the wire contract to
+ * print a sentence, and `pending` — the honest answer while a message waits behind a running turn —
+ * is a state the operator has to be able to see named.
+ */
+interface ILocalPeerSendResult {
+  readonly state: 'pending' | 'delivered' | 'acknowledged' | 'duplicate' | 'refused' | 'failed';
+  readonly reason?: string;
+}
+/**
+ * ARCH-009 — the discovery half of a preset registry, named HERE rather than imported.
+ *
+ * `agent-preset` depends on `agent-framework`, not the other way round, so importing its
+ * `IPresetRegistry` would invert the layering to describe a value this package only hands to a
+ * command. Structural typing means the registry `agent-preset` builds satisfies this without either
+ * package naming the other.
+ *
+ * Only the three members `/preset` actually calls are named. A port that mirrors a whole contract it
+ * does not use is a second copy of that contract waiting to drift.
+ *
+ * It is an ADAPTER and not a host-role member, because that is what it is: a capability the
+ * composition root supplies, reached the way `/permission-mode` and `/plugin` already reach theirs.
+ * Absent ⇒ the host loaded no external presets, and `/preset` lists the built-ins.
+ */
+interface ICommandPresetRegistryAdapter {
+  /**
+   * `title` and `description` are REQUIRED, because `/preset list` renders both. Optional members
+   * here would let a conforming host typecheck and then print `id — undefined: undefined`; review of
+   * ARCH-009 reported exactly that. A port requires what its consumer needs, and variation belongs in
+   * the VALUE, not in whether the member exists.
+   */
+  listPresets(): readonly {
+    id: string;
+    title: string;
+    description: string;
+  }[];
+  /** PRESENCE only — `/preset` asks whether the id is known, never what it holds. */
+  getPreset(id: string): unknown;
+  /**
+   * The re-appliable option subset. `IPresetApplicationOptions` is framework-owned and
+   * `agent-preset`'s `IResolvedPresetOptions` satisfies it structurally, so naming it here crosses no
+   * layer and leaves nothing for a consumer to assert about a value it did not check.
+   */
+  resolvePreset(id: string, context?: unknown): IPresetApplicationOptions;
+}
+/** CLI-1988: the command-facing projection of the host's provider-neutral output-style registry. */
+interface ICommandOutputStyleSummary {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly tokenCost?: string;
+  readonly source?: string;
+}
+/** CLI-1988: discovery and resolution only; commands never read style files or own persistence. */
+interface ICommandOutputStyleRegistryAdapter {
+  listOutputStyles(): readonly ICommandOutputStyleSummary[];
+  getOutputStyle(id: string): IOutputStylePrompt | undefined;
+}
+/**
+ * HANDOFF-001 (issue #1864): what a hand-off looks like to the operator, in the operator's words.
+ *
+ * Deliberately not the wire package's `THandoffPhase`. The command layer must not import the wire
+ * contract to print a sentence, and the two vocabularies answer different questions — `staged` is a
+ * protocol state, while "the other machine has it and is not running it yet" is what the person
+ * standing at the keyboard needs to be told.
+ */
+interface IHandoffProgress {
+  readonly state: 'offered' | 'sending' | 'awaiting-confirmation' | 'done' | 'stopped';
+  /** Present when the transfer stopped without completing. Named so the operator can act on it. */
+  readonly reason?: string;
+  /** Is THIS machine still in charge of the session? The single question the whole design answers. */
+  readonly stillMine: boolean;
+}
+/** What stays behind, surfaced BEFORE the operator confirms, because it is their choice to lose it. */
+interface IHandoffStaysBehind {
+  readonly uncommittedChanges: boolean;
+  readonly subprocesses: number;
+}
+/** A `/cd` the session has already checked and prepared; the host carries it out. */
+interface IWorkspaceMoveRequest {
+  /** The directory the session runs in now. */
+  readonly fromCwd: string;
+  /** The canonical absolute directory to move to. */
+  readonly targetCwd: string;
+  /** The conversation, copied for the target — its `cwd` is already `targetCwd`. */
+  readonly record: IInteractiveSessionRecord;
+  /**
+   * The session is Restricted. A move never widens access, so the target stays Restricted whatever
+   * its own trust decision; a trusted session takes the target's own decision.
+   */
+  readonly restricted: boolean;
+}
+/**
+ * What `/cd` hands the host. A move is a NEW session in the target directory, composed the way the
+ * host composes any session there — its settings, trust decision, tools and instructions — resuming
+ * this conversation. Absent on a host that cannot start one; `/cd` then says so.
+ */
+interface ICommandWorkspaceAdapter {
+  move(request: IWorkspaceMoveRequest): Promise<void>;
+}
+/**
+ * What `/handoff` reads. The carrier, the wire composition and the device identity all live in the
+ * composition root — a command never constructs a transport.
+ */
+interface ICommandHandoffAdapter {
+  /** The machines this session could be moved to. Empty is an answer, not an error. */
+  destinations(): Promise<readonly {
+    readonly deviceId: string;
+    readonly name?: string;
+  }[]>;
+  /**
+   * What will not travel, so the operator is asked with the facts in front of them.
+   *
+   * Read before the confirmation prompt rather than after: uncommitted work and running
+   * subprocesses stay on this machine by design, and a consent that did not mention them is not
+   * consent to lose them.
+   */
+  staysBehind(): Promise<IHandoffStaysBehind>;
+  /**
+   * Move this session to `deviceId`, reporting progress as it goes.
+   *
+   * Returns the final progress rather than throwing: "the destination cannot run it" and "the link
+   * broke" are both answers the operator needs, and an exception would flatten them into one. In
+   * every non-`done` outcome `stillMine` is true — that is the invariant the command prints.
+   */
+  transfer(deviceId: string, onProgress?: (progress: IHandoffProgress) => void): Promise<IHandoffProgress>;
+  /** Is this machine still authoritative? Asked without starting anything. */
+  status(): IHandoffProgress;
+}
+/** The persisted `/cost budget` document. */
+interface ICommandCostBudget {
+  monthly: number;
+}
+/**
+ * CMD-007 (issue #2058): the narrow storage port `/cost budget` reads and writes through.
+ *
+ * The command used to own the budget file's location and the filesystem calls itself, which made a
+ * reusable command package responsible for a product's storage location and symlink policy. The
+ * shell now composes an adapter (agent-cli: a file under the workspace, written atomically and never
+ * through a symlink); the command sees `read/write/clear` and nothing else, so another product can
+ * store the budget wherever it likes. `write`/`clear` throw a typed failure the command renders.
+ */
+interface ICommandCostBudgetAdapter {
+  /** `undefined` when no budget is set (absent, empty or unreadable document alike). */
+  read(): ICommandCostBudget | undefined;
+  write(budget: ICommandCostBudget): void;
+  clear(): void;
+}
+interface ICommandHostAdapters {
+  settings?: ICommandSettingsAdapter;
+  effort?: ICommandEffortAdapter;
+  /** The live advisor: `/advisor` changes its target without touching the session's tools. */
+  advisor?: ICommandAdvisorAdapter;
+  /** CMD-007 (issue #2058). Absent on a host with no budget storage — `/cost budget` then says so. */
+  costBudget?: ICommandCostBudgetAdapter;
+  process?: ICommandProcessAdapter;
+  permissionMode?: ICommandPermissionModeAdapter;
+  /** Absent on a host that cannot name its settings layers — `/permissions` then lists rules unattributed. */
+  permissionRules?: ICommandPermissionRulesAdapter;
+  plugin?: ICommandPluginAdapter;
+  remoteControl?: ICommandRemoteControlAdapter;
+  mcpActivation?: ICommandMCPActivationAdapter;
+  localPeers?: ICommandLocalPeersAdapter;
+  /**
+   * ARCH-009 — the instance registry the host resolved with, so in-session `/preset` discovers THIS
+   * product's presets. Its absence is why `agent-preset` had to keep a module-global registry: a
+   * command runs with an `ICommandHostContext` and nothing else, so this bag is the path from the
+   * shell to the command.
+   */
+  presetRegistry?: ICommandPresetRegistryAdapter;
+  /** CLI-1988 — the instance-scoped output-style catalog resolved by the composition root. */
+  outputStyleRegistry?: ICommandOutputStyleRegistryAdapter;
+  /**
+   * HANDOFF-001 (issue #1864). Absent on a host with no carrier — `/handoff` then says so rather
+   * than offering a transfer it cannot perform.
+   */
+  handoff?: ICommandHandoffAdapter;
+  /** Absent on a host that cannot start a session elsewhere — `/cd` then says so. */
+  workspace?: ICommandWorkspaceAdapter;
+  /** Absent on a host with no OS sandbox — `/sandbox` then says so. */
+  sandbox?: ICommandSandboxAdapter;
+}
+interface IContextReferenceAddResult {
+  reference?: IContextReferenceItem;
+  evicted: IContextReferenceItem[];
+  diagnostics: string[];
+}
+interface IContextReferenceRemoveResult {
+  removed?: IContextReferenceItem;
+}
+interface IContextReferenceClearResult {
+  removed: IContextReferenceItem[];
+}
+/** Options for {@link GoalController.start}. */
+interface IGoalStartOptions {
+  maxIterations?: number;
+  noProgressLimit?: number;
+}
+interface IStartupMemory {
+  content: string;
+  path: string;
+  lineCount: number;
+  truncated: boolean;
+}
+interface IMemoryTopicSummary {
+  name: string;
+  path: string;
+}
+interface IProjectMemorySummary {
+  indexPath: string;
+  topicsPath: string;
+  topics: IMemoryTopicSummary[];
+}
+interface IAppendMemoryInput {
+  type: TMemoryType;
+  topic: string;
+  text: string;
+}
+interface IAppendMemoryResult {
+  indexPath: string;
+  topicPath: string;
+  topic: string;
+  deduplicated: boolean;
+}
+type TMemoryCandidateStatus = 'pending' | 'approved' | 'rejected' | 'saved' | 'skipped';
+interface IMemoryCandidate {
+  id: string;
+  type: TMemoryType;
+  topic: string;
+  text: string;
+  sourceMessageIds: string[];
+  confidence: number;
+  createdAt: string;
+  reason: string;
+}
+interface IMemoryPendingRecord extends IMemoryCandidate {
+  status: TMemoryCandidateStatus;
+  updatedAt: string;
+  decisionReason?: string;
+}
+interface IMemoryRetrievalResult {
+  content: string;
+  references: IMemoryReference[];
+  truncated: boolean;
+}
+//#endregion
+//#region src/memory/types.d.ts
+/** A recall budget: at most `maxTopics` topics, each truncated to `maxTopicChars` characters. */
+interface IMemoryBudget {
+  maxTopics: number;
+  maxTopicChars: number;
+}
+/**
+ * Segregated role interfaces (ISP). The durable-memory capability is four distinct client roles —
+ * a reader (startup injection needs only this), a writer, a recaller, and a curation queue. `IMemoryStore`
+ * composes all four; a consumer depends only on the slice it uses. Every method is **async**
+ * (`Promise`-returning), matching the repo's I/O-capability port precedents (`ISandboxClient`,
+ * `IRetrievalAdapter`) so a remote/heavy backend — including the async `ISemanticMemoryAdapter` — fits
+ * behind the same port without a breaking migration. The fs reference adapter wraps its synchronous `fs`
+ * calls in already-resolved Promises (zero behavior change).
+ */
+interface IDurableMemoryReader {
+  /** The startup-memory index (budget-limited), injected into the system prompt. */
+  loadStartupMemory(): Promise<IStartupMemory>;
+  /** Summarize the memory index + topic files. */
+  list(): Promise<IProjectMemorySummary>;
+  /** Read a single topic's content ('' if absent). */
+  readTopic(topic: string): Promise<string>;
+}
+interface IMemoryWriter {
+  /** Append a durable memory entry (deduplicated). */
+  append(input: IAppendMemoryInput): Promise<IAppendMemoryResult>;
+}
+interface IMemoryRecaller {
+  /** Recall the most relevant topics for `query`, never exceeding `budget`. */
+  recall(query: string, budget: IMemoryBudget): Promise<IMemoryRetrievalResult>;
+}
+interface IMemoryCurationQueue {
+  /** A pending candidate by id (undefined if absent). */
+  getPending(id: string): Promise<IMemoryPendingRecord | undefined>;
+  /** Pending candidates, optionally filtered by status. */
+  listPending(status?: TMemoryCandidateStatus): Promise<IMemoryPendingRecord[]>;
+  /** Transition a pending candidate to a new status with a reason. */
+  markPending(id: string, status: TMemoryCandidateStatus, reason: string): Promise<IMemoryPendingRecord>;
+  /** Insert or update a pending candidate with a status + reason. */
+  upsertPending(candidate: IMemoryCandidate, status: TMemoryCandidateStatus, reason: string): Promise<void>;
+}
+/**
+ * The neutral durable-memory port — the composition of the four role interfaces above. It is the single
+ * DIP seam a surface swaps to change the whole backend (fs, FTS, or a semantic/vector store behind
+ * `ISemanticMemoryAdapter`); startup injection, the `/memory` command path, and the post-turn capture
+ * controller ALL read/write through it, so an injected store is authoritative everywhere (no split-brain).
+ */
+interface IMemoryStore extends IDurableMemoryReader, IMemoryWriter, IMemoryRecaller, IMemoryCurationQueue {}
+//#endregion
+//#region src/command-api/host-roles.d.ts
+/** Reaching the live session, and the whole-conversation operations that sit beside it. */
+interface ICommandHostSessionAccess {
+  getSession(): ICommandSessionRuntime;
+  /** Read the active response style id for the command listing. */
+  getActiveOutputStyleId(): string;
+  clearConversationHistory(): void;
+  /**
+   * CLI-1994 — write a COPY of the live conversation as a new session record (fresh id, distinct
+   * name, the parent's messages and assembled system message) and return its identity. A role-port
+   * member rather than an `ICommandHostAdapters` entry because the session store is owned by the
+   * session, not by the shell. The copy is not started here: `/fork` spawns the background job that
+   * resumes it, carrying only the returned id.
+   */
+  forkSession(input?: {
+    name?: string;
+  }): Promise<{
+    sessionId: string;
+    name: string;
+  }>;
+  /**
+   * ARCH-029 TC-08 — required, and the host delegates to `computeSessionReplayValidationReport`.
+   * It was an optional override with a framework-computed default and no implementor, which is
+   * two declared paths with only one live. One owner, one path.
+   */
+  validateCurrentSessionReplayLog(): ICommandSessionReplayValidationReport;
+  /**
+   * Every usage record the session has persisted — its turns and any other model it consulted —
+   * so a total read from here is the whole session's spend, each part priced on its own model.
+   */
+  getSessionUsage(): readonly ISessionUsageRecord[];
+}
+/** Reaching the agent-job capability, when the host has one. */
+interface ICommandHostAgentJobs {
+  getAgentJobCapability(): IAgentJobHostContext | undefined;
+}
+/** Asking the user a question. */
+interface ICommandHostUserInteraction {
+  /**
+   * CMD-004: the injected "ask the user" port, or undefined when no interactive renderer is attached.
+   * A command solicits a structured answer via `getUserInteraction()?.ask(request)`; absence means no
+   * human is available (headless/automation, or a model-invoked command) — the command must handle it
+   * as a cancellation, never a silent guess.
+   */
+  getUserInteraction(): IUserInteraction | undefined;
+}
+/** Re-applying preset-owned configuration to the live session. */
+interface ICommandHostPresetApplication {
+  /** Apply an additive response style to the live system prompt. */
+  applyOutputStyle(style: IOutputStylePrompt): void;
+  /** PRESET-014 — re-apply a preset persona to the live system prompt. */
+  applyPersona(persona: string): void;
+  /** PRESET-017 — toggle the verify-before-done self-verification section on the live prompt. */
+  applySelfVerification(enabled: boolean): void;
+  /** ARCH-040 — re-apply the preset's response language to the live system prompt. */
+  applyResponseLanguage(language: string): void;
+  /** ARCH-040 — re-apply the preset's seeding system prompt to the live system prompt. */
+  applyPresetSystemPrompt(text: string): void;
+  /**
+   * PRESET-015 — re-apply command-module selection to the live session. Returns any
+   * `enabled`/`disabled` names that matched no live command module (INFRA-032) so the `/preset`
+   * command can surface them as a non-fatal notice; an empty array means every name matched.
+   */
+  applyCommandModuleSelection(enabled: readonly string[] | undefined, disabled: readonly string[] | undefined): readonly IUnknownCommandModuleName[];
+}
+/** The host's view of the context window and its compaction. */
+interface ICommandHostContextWindow {
+  getContextState(): IContextWindowState;
+  getAutoCompactThreshold(): TAutoCompactThreshold;
+  getAutoCompactThresholdSource(): TAutoCompactThresholdSource;
+  setAutoCompactThreshold(threshold: TAutoCompactThreshold, source?: TAutoCompactThresholdSource): void;
+  compactContext(instructions?: string): Promise<void>;
+}
+/** The files pinned into context by reference. */
+interface ICommandHostContextReferences {
+  listContextReferences(): IContextReferenceItem[];
+  addContextReference(path: string): Promise<IContextReferenceAddResult>;
+  removeContextReference(path: string): IContextReferenceRemoveResult;
+  clearContextReferences(): IContextReferenceClearResult;
+}
+/** Where the command is running, and how it was invoked. */
+interface ICommandHostWorkspace {
+  getCwd(): string;
+  getCommandInvocationSource(): TCommandInvocationSource;
+}
+/** What commands and skills this host can dispatch. */
+interface ICommandHostCatalog {
+  listCommands(): ICommandListEntry[];
+  listSkills(): ICommandSkillListEntry[];
+  executeSkillCommandByName(name: string, args: string, request: ICommandSkillActivationRequest): Promise<ICommandResult | null>;
+}
+/** The edit-checkpoint tree: inspection, restore, and branching. */
+interface ICommandHostCheckpoints {
+  listEditCheckpoints(): IEditCheckpointSummary[];
+  inspectEditCheckpoint(checkpointId: string): IEditCheckpointInspection;
+  restoreEditCheckpoint(checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+  rollbackEditCheckpoint(checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+  /** SELFHOST-007: list the checkpoint branch tips (leaf ids) via the neutral tree. */
+  listCheckpointBranches(): string[];
+  /** SELFHOST-007: fork a new branch from a past checkpoint (non-destructive restore). */
+  forkCheckpointBranch(checkpointId: string): Promise<IEditCheckpointRestoreResult>;
+  /** SELFHOST-007: switch the active branch to an existing checkpoint/branch tip. */
+  switchCheckpointBranch(checkpointId: string): void;
+}
+/** Durable memory: what was used, what happened, and the store behind it. */
+interface ICommandHostMemory {
+  getUsedMemoryReferences(): IMemoryReference[];
+  recordMemoryEvent(event: IMemoryEvent): void;
+  /**
+   * SELFHOST-008 P1R — the injected durable-memory port the `/memory` command reads/writes through, so a
+   * surface that swaps the store is authoritative for command operations too (no split-brain). Must
+   * return the SAME instance the session injected (SSOT for a stateful store). ARCH-029 TC-09: the
+   * "when absent, default to the neutral fs store over `getCwd()`" fallback is GONE — the one
+   * production host already built and cached that store itself, so the framework was re-deriving
+   * what the host owned.
+   */
+  getMemoryStore(): IMemoryStore;
+}
+/** Observing and ending background tasks. */
+interface ICommandHostBackgroundTasks {
+  listBackgroundTasks(filter?: IBackgroundTaskListFilter): IBackgroundTaskState[];
+  readBackgroundTaskLog(taskId: string, cursor?: IBackgroundTaskLogCursor): Promise<IBackgroundTaskLogPage>;
+  cancelBackgroundTask(taskId: string, reason?: string): Promise<void>;
+  closeBackgroundTask(taskId: string): Promise<void>;
+}
+/** The autonomous-goal lifecycle. */
+interface ICommandHostGoal {
+  /** GOAL-001 — assign and begin pursuing an autonomous goal. */
+  setGoal(objective: string, options?: IGoalStartOptions): Promise<IGoalState>;
+  /** GOAL-001 — the current goal state, or null when no goal has been set. */
+  getGoalState(): IGoalState | null;
+  /** GOAL-001 — cancel an in-flight goal; returns the stopped state or null. */
+  cancelGoal(): IGoalState | null;
+}
+/** The plan lifecycle, including the mode flip approval performs. */
+interface ICommandHostPlan {
+  /** SELFHOST-002 — start a plan (draft for review; keeps `plan` mode). */
+  setPlan(objective: string, steps?: readonly string[]): Promise<IPlanArtifact>;
+  /** SELFHOST-002 — the current plan artifact, or null when none started. */
+  getPlanState(): IPlanArtifact | null;
+  /** SELFHOST-002 — approve the plan; applies the `plan → acceptEdits` mode flip. */
+  approvePlan(): IPlanArtifact;
+  /** SELFHOST-002 — revert the plan to drafting; returns mode to `plan`. */
+  revertPlan(): IPlanArtifact;
+}
+/** Handing the real terminal to a child process. */
+interface ICommandHostTerminalHandoff {
+  /**
+   * TERM-001 — whether the active transport can hand the real terminal to a child process. `false`
+   * when there is no interactive TTY (e.g. headless). `runWithTerminal` is required and present
+   * either way; whether a handoff is possible is a VALUE this returns, not a member that is missing.
+   */
+  canHandoffTerminal(): boolean;
+  /**
+   * TERM-001 — suspend the display, run `fn` (which spawns a child with inherited stdio), then
+   * restore the display. Exclusive (one handoff at a time) and abort-safe; rejects without running
+   * `fn` when a handoff is not possible. The framework owns this orchestration; the transport
+   * implements the underlying suspend/resume.
+   */
+  runWithTerminal<T>(fn: () => Promise<T>): Promise<T>;
+}
+/** The injected adapter bag — genuinely variational, and the named zero-optional carve-out. */
+interface ICommandHostAdapterAccess {
+  getCommandHostAdapters?(): ICommandHostAdapters;
+}
+/** Aggregate: all 47 members remain source-compatible. Declare a role port instead of this. */
+interface ICommandHostContext extends ICommandHostSessionAccess, ICommandHostAgentJobs, ICommandHostUserInteraction, ICommandHostPresetApplication, ICommandHostContextWindow, ICommandHostContextReferences, ICommandHostWorkspace, ICommandHostCatalog, ICommandHostCheckpoints, ICommandHostMemory, ICommandHostBackgroundTasks, ICommandHostGoal, ICommandHostPlan, ICommandHostTerminalHandoff, ICommandHostAdapterAccess {}
+//#endregion
+//#region src/command-api/contracts.d.ts
+type TSystemCommandLifecycle = 'inline' | 'blocking' | 'background';
+type TSystemCommandSemanticRole = 'skillActivation' | 'contextReduction' | 'subagentSpawn';
+/** A user-visible command with descriptor metadata and execute logic. */
+interface ISystemCommand {
+  name: string;
+  /** Optional framework-owned behavior role; command owners declare it beside the real command id. */
+  semanticRole?: TSystemCommandSemanticRole;
+  /** User-friendly display label (e.g., "Interaction Mode"). Falls back to `name` if not set. */
+  displayName?: string;
+  description: string;
+  /** Optional usage example shown in /help output (e.g., "/compact Summarize the context"). */
+  example?: string;
+  modelInvocable?: boolean;
+  /** What the model is told about this command; absent → `description`. See `ICommand.modelDescription`. */
+  modelDescription?: string;
+  userInvocable?: boolean;
+  argumentHint?: string;
+  safety?: TCapabilitySafety;
+  subcommands?: readonly ICommand[];
+  lifecycle?: TSystemCommandLifecycle;
+  /**
+   * Whether executing this command requires explicit user permission/confirmation.
+   * - `false`: runs immediately without any approval gate
+   * - `true`: user confirmation is required before execution
+   * - `undefined` (default): derived from `safety` — `'read-only'` → false, others → true
+   */
+  requiresPermission?: boolean;
+  /**
+   * Whether the MODEL's call to this command is asked about by name, when that differs from
+   * `requiresPermission`. It may be `false` only when everything the model can reach through the
+   * command (its model subcommand allowlist) is read-only, or when the command decides each
+   * model call through the gate of the tool whose effect it has — never merely to skip a prompt.
+   * Absent → `requiresPermission`'s resolution. It never changes the user or remote path.
+   */
+  modelRequiresPermission?: boolean;
+  execute(context: ICommandHostContext, args: string): Promise<ICommandResult> | ICommandResult;
+}
+//#endregion
+//#region src/command-api/command-module.d.ts
+/**
+ * CMD-008: a session requirement is a DEMAND SWITCH, not a registration gate. Declaring one does
+ * not gate the module on runtime capability being available; it makes the session projection
+ * enable that facility (`'agent-runtime'` → `enableAgentRuntime: true`) so the module's commands
+ * can rely on it. Pinned by `interactive/__tests__/command-module-session-requirements.test.ts`.
+ */
+type TCommandModuleSessionRequirement = 'agent-runtime';
+/** Composable command capability module. */
+interface ICommandModule {
+  /** Stable module id for diagnostics and duplicate handling. */
+  readonly name: string;
+  /** Slash palette/autocomplete command sources contributed by this module. */
+  readonly commandSources?: readonly ICommandSource[];
+  /** Executable system commands contributed by this module. */
+  readonly systemCommands?: readonly ISystemCommand[];
+  /** Additional model-visible descriptors not derived from executable commands. */
+  readonly commandDescriptors?: readonly ICapabilityDescriptor[];
+  /** Runtime facilities this module DEMANDS — the session enables each one when the module is composed. */
+  readonly sessionRequirements?: readonly TCommandModuleSessionRequirement[];
+  /** Stop and join module-owned work before its host session closes. */
+  readonly shutdown?: (host: ICommandHostWorkspace) => Promise<void>;
+}
+//#endregion
+//#region ../agent-preset/dist/node/index.d.ts
+//#endregion
+//#region src/output-style-types.d.ts
+type TOutputStyleSource = 'built-in' | 'managed' | 'user' | 'project';
+interface IOutputStyleFile {
+  readonly fileName: string;
+  readonly content: string;
+}
+/** A source is already bounded by its owner; this package only decodes the supplied Markdown. */
+interface IOutputStyleSource {
+  readonly scope: Exclude<TOutputStyleSource, 'built-in'>;
+  readonly displayName: string;
+  /** Lower values are applied first. The last scope with an id wins. */
+  readonly precedence: number;
+  readonly files: readonly IOutputStyleFile[];
+}
+//#endregion
+//#region ../agent-mcp/dist/node/index.d.ts
+//#region src/mcp-activation.d.ts
+/**
+ * MCP activation is a policy boundary, not a transport concern.
+ *
+ * The request deliberately contains only public identity material. Connection secrets such as
+ * API keys and arbitrary headers stay in IMCPServerDefinition(Resolved) and are never persisted in
+ * this ledger.
+ */
+type TMCPActivationSource = 'managed' | 'user' | 'project' | 'plugin' | 'local';
+interface IMCPActivationProvenance {
+  readonly kind: TMCPActivationSource;
+  readonly id: string;
+  readonly version?: string;
+}
+type TMCPActivationStatus = 'approved' | 'pending' | 'rejected' | 'revoked' | 'stale' | 'untrusted';
+type TMCPApprovalAuthority = 'managed' | 'user' | 'local' | 'project' | 'plugin';
+interface IMCPActivationApprovalRecord {
+  readonly serverId: string;
+  readonly source: TMCPActivationSource;
+  readonly provenance: IMCPActivationProvenance;
+  readonly definitionFingerprint: string;
+  readonly securityIdentity: string;
+  readonly approvalAuthority: TMCPApprovalAuthority;
+  readonly decision: Extract<TMCPActivationStatus, 'approved' | 'rejected' | 'revoked'>;
+  readonly repositoryKey?: string;
+  readonly workspaceGeneration?: number;
+  readonly decidedAt: string;
+}
+/** Public audit data. It intentionally has no endpoint, API key, or arbitrary request headers. */
+interface IMCPActivationAuditEvent {
+  readonly action: 'approve' | 'reject' | 'revoke';
+  readonly serverId: string;
+  readonly source: TMCPActivationSource;
+  readonly provenanceId: string;
+  readonly definitionFingerprint: string;
+  readonly securityIdentity: string;
+  readonly decision: Extract<TMCPActivationStatus, 'approved' | 'rejected' | 'revoked'>;
+  readonly at: string;
+}
+interface IMCPActivationApprovalStore {
+  list(): readonly IMCPActivationApprovalRecord[];
+  put(record: IMCPActivationApprovalRecord): void;
+  listAudit(): readonly IMCPActivationAuditEvent[];
+  appendAudit(event: IMCPActivationAuditEvent): void;
+}
+interface IMCPHttpTransportDeps {
+  /** Egress policy; default refuses private, loopback and metadata destinations. */
+  readonly policy?: IEgressPolicy;
+  /** Hostname resolver injected so tests never touch DNS. */
+  readonly lookup?: TEgressLookup;
+  /** Fetch used by the SDK transport; default is the global one. */
+  readonly fetch?: typeof globalThis.fetch;
+}
+//#endregion
+//#region src/client/stdio-types.d.ts
+interface IMCPStdioExecutable {
+  readonly command: string;
+  /** Every vector is one exact command line the host permits. */
+  readonly args: readonly (readonly string[])[];
+}
+interface IMCPStdioAuthority {
+  readonly allowedRoot: string;
+  /** Changing this value invalidates every existing admitted snapshot. */
+  readonly generation: string;
+  readonly executables: readonly IMCPStdioExecutable[];
+  /** Only host-selected values are passed to the child. */
+  readonly environment?: Readonly<Record<string, string>>;
+  /** Definition env keys must be explicitly allowed and their values match host-selected values. */
+  readonly allowedEnvironmentKeys?: readonly string[];
+  readonly startupMs?: number;
+  readonly cleanupMs?: number;
+}
+//#endregion
+//#region src/startup/cli-options-types.d.ts
+/**
+ * Leaf type module: holds {@link IStartCliOptions} so it can be imported by both
+ * `command-setup.ts` and `doctor-inputs.ts` without creating an import cycle between them.
+ * Re-exported from `command-setup.ts` so existing imports keep working.
+ */
+interface IStartCliOptions {
+  commandModules?: readonly ICommandModule[];
+  providerDefinitions?: readonly IProviderDefinition[];
+  /** Initial trusted-or-restricted workspace decision. Absence is Restricted. */
+  projectAccess?: TWorkspaceProjectAccess;
+  /** `--safe-mode`: every customization off — see `SAFE_MODE_FLAG`. */
+  safeMode?: boolean;
+  /** Separately approved project-settings write capability. */
+  projectSettingsWriter?: IWorkspaceProjectSettingsWriter;
+  /** Separately approved bounded project mutation capability. */
+  projectMutation?: IWorkspaceProjectMutation;
+  /** Host-composed MCP definition registry and trust-admission controller. */
+  mcpActivationAdapter?: ICommandMCPActivationAdapter;
+  /** Host-owned per-server subprocess capabilities; never inferred from settings. */
+  mcpStdioAuthorities?: Readonly<Record<string, IMCPStdioAuthority>>;
+  /** Host-owned approval state, shared with the canonical MCP activation controller. */
+  mcpApprovalStore?: IMCPActivationApprovalStore;
+  /** Host-owned HTTP transport policy; never supplied by MCP settings or a remote caller. */
+  mcpHttpTransportDeps?: IMCPHttpTransportDeps;
+  /** Host-configured character limits; generic admission validates the ordering and ceiling. */
+  mcpResultAdmissionLimits?: Pick<IToolResultAdmissionOptions, 'warningChars' | 'hardChars' | 'repositoryMaxChars'>;
+  /** Host-composed managed output styles, applied above user/project style sources. */
+  managedOutputStyleSources?: readonly IOutputStyleSource[];
+}
+//#endregion
+//#region src/cli.d.ts
+/** Full CLI entry: supplies its terminal presentation to the shared serve/bootstrap path. */
+declare function startCli(options?: IStartCliOptions): Promise<void>;
+//#endregion
+export { type IStartCliOptions, startCli };
+//# sourceMappingURL=index.d.cts.map