@codingame/monaco-vscode-chat-service-override 36.2.7 → 37.0.0

package/vscode/src/vs/platform/agentHost/common/agentService.d.ts

@@ -1,1294 +0,0 @@
-import { Event } from "@codingame/monaco-vscode-api/vscode/vs/base/common/event";
-import { IReference } from "@codingame/monaco-vscode-api/vscode/vs/base/common/lifecycle";
-import type { IObservable } from "@codingame/monaco-vscode-api/vscode/vs/base/common/observable";
-import { URI } from "@codingame/monaco-vscode-api/vscode/vs/base/common/uri";
-import { IConfigurationService } from "@codingame/monaco-vscode-api/vscode/vs/platform/configuration/common/configuration.service";
-import type { IAgentServerToolHost } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/agentServerTools";
-import type { IActiveSubscriptionInfo, IAgentSubscription } from "./state/agentSubscription.js";
-import type { IRemoteWatchHandle } from "./agentHostFileSystemProvider.js";
-import type { CompletionsParams, CompletionsResult, CreateTerminalParams, ResolveSessionConfigResult, SessionConfigCompletionsResult } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/commands";
-import type { InvokeChangesetOperationParams, InvokeChangesetOperationResult } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/channels-changeset/commands";
-import { ProtectedResourceMetadata, type Changeset, type ConfigSchema, type MessageAttachment, type ModelSelection, type AgentSelection, type SessionActiveClient, type ToolCallPendingConfirmationState, type ToolDefinition, ChangesSummary } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/protocol/state";
-import type { ActionEnvelope, AuthRequiredParams, INotification, IRootConfigChangedAction, SessionAction, ChatAction, TerminalAction, ClientAnnotationsAction } from "./state/sessionActions.js";
-import type { ResourceCopyParams, ResourceCopyResult, ResourceDeleteParams, ResourceDeleteResult, ResourceListResult, ResourceMkdirParams, ResourceMkdirResult, ResourceMoveParams, ResourceMoveResult, ResourceReadResult, ResourceResolveParams, ResourceResolveResult, ResourceWriteParams, ResourceWriteResult, CreateResourceWatchParams, CreateResourceWatchResult } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/sessionProtocol";
-import { ComponentToState, ChatInputResponseKind, SessionStatus, StateComponents, type AgentCapabilities, type ClientPluginCustomization, type Customization, type PendingMessage, type RootState, type ChatInputAnswer, type SessionMeta, type ToolCallResult, type Turn, type PolicyState } from "@codingame/monaco-vscode-api/vscode/vs/platform/agentHost/common/state/sessionState";
-export declare enum AgentHostIpcChannels {
-    /** Channel for the agent host service on the main-process side */
-    AgentHost = "agentHost",
-    /** Channel for log forwarding from the agent host process */
-    Logger = "agentHostLogger",
-    /** Channel for WebSocket client connection count (server process management only) */
-    ConnectionTracker = "agentHostConnectionTracker",
-    /**
-     * Channel registered by the remote server that proxies AHP JSON-RPC
-     * frames between a renderer and the agent host running on the server.
-     * Pairs with `AgentHostIpcChannelTransport` on the renderer side.
-     */
-    RemoteProxy = "agentHostProxy"
-}
-/** Configuration key that controls whether the local agent host process is spawned. */
-export declare const AgentHostEnabledSettingId = "chat.agentHost.enabled";
-/** Whether the local/process-backed agent host is enabled in this runtime. */
-export declare function isAgentHostEnabled(configurationService: IConfigurationService): boolean;
-/** Configuration key that controls whether AHP JSONL logs are written for agent host transports. */
-export declare const AgentHostAhpJsonlLoggingSettingId = "chat.agentHost.ahpJsonlLoggingEnabled";
-/** Configuration key that controls whether Agent Host uses its terminal tool override for Copilot SDK sessions. */
-export declare const AgentHostCustomTerminalToolEnabledSettingId = "chat.agentHost.customTerminalTool.enabled";
-/**
- * Configuration key that controls whether Copilot SDK sessions running a Claude
- * Opus 4.8 model apply the Opus 4.8-tuned system-prompt section overrides.
- * Forwarded into the agent host's root config (`opus48Prompt`) by
- * `AgentHostCopilotPromptContribution`.
- */
-export declare const AgentHostOpus48PromptEnabledSettingId = "chat.agentHost.opus48Prompt.enabled";
-/**
- * Configuration key controlling whether the Claude provider is registered in
- * the agent host process. When `false`, the agent host skips registering the
- * Claude provider regardless of SDK availability. Defaults to `true`.
- *
- * Independent of {@link ClaudePreferAgentHostAgentsSettingId} /
- * {@link ClaudePreferAgentHostEditorSettingId}, which control whether the
- * workbench surfaces the agent host's Claude provider (vs. the GitHub Copilot
- * Chat extension's). This setting is strictly about whether the agent host
- * advertises Claude at all. The agent host process must be restarted for
- * changes to take effect.
- */
-export declare const AgentHostClaudeAgentEnabledSettingId = "chat.agentHost.claudeAgent.enabled";
-/**
- * Configuration key controlling whether the Codex provider is registered in
- * the agent host process. When `false` (the default), the agent host skips
- * registering the Codex provider regardless of SDK availability. The agent
- * host process must be restarted for changes to take effect.
- */
-export declare const AgentHostCodexAgentEnabledSettingId = "chat.agentHost.codexAgent.enabled";
-/**
- * Configuration key controlling whether the agent host *wires up* the BYOK
- * ("bring your own key") language-model bridge: the renderer LM handler, the
- * reverse-RPC channel, and the per-connection link to the node-side OpenAI
- * proxy + bridge registry. When `false` (the default), the proxy and registry
- * are still constructed but stay inert — the renderer's BYOK server channel and
- * the per-connection bridge are not wired, so the registry stays empty and
- * extension-provided BYOK models are never reachable from agent-host sessions.
- * The agent host process must be restarted for changes to take effect.
- */
-export declare const AgentHostByokModelsEnabledSettingId = "chat.agentHost.byokModels.enabled";
-/**
- * Optional override that points at an **SDK root directory** containing a
- * `node_modules/@anthropic-ai/claude-agent-sdk` subtree. When set, the agent
- * host loads the Claude SDK from that path instead of the bare import (which
- * resolves via this repo's `node_modules` in dev) or the on-demand download
- * from `product.agentSdks.claude` (built products). Mainly exists for the
- * remote server's `--claude-sdk-root` CLI flag and for one-off developer
- * overrides pointing at an out-of-tree SDK build.
- */
-export declare const AgentHostClaudeSdkRootEnvVar = "VSCODE_AGENT_HOST_CLAUDE_SDK_ROOT";
-/**
- * Environment variable form of {@link AgentHostClaudeAgentEnabledSettingId}.
- * Set by the agent host starters from the setting. Accepts `'true'` /
- * `'false'`; absent means "default" (`true` for Claude, `false` for Codex).
- */
-export declare const AgentHostClaudeAgentEnabledEnvVar = "VSCODE_AGENT_HOST_CLAUDE_AGENT_ENABLED";
-/**
- * Environment variable form of {@link AgentHostCodexAgentEnabledSettingId}.
- * Set by the agent host starters from the setting. Accepts `'true'` /
- * `'false'`; absent means "default" (`false`).
- */
-export declare const AgentHostCodexAgentEnabledEnvVar = "VSCODE_AGENT_HOST_CODEX_AGENT_ENABLED";
-/**
- * Environment variable form of {@link AgentHostByokModelsEnabledSettingId}.
- * Set by the agent host starters from the setting. Accepts `'true'` /
- * `'false'`; absent means "default" (`false`).
- */
-export declare const AgentHostByokModelsEnabledEnvVar = "VSCODE_AGENT_HOST_BYOK_MODELS_ENABLED";
-/**
- * Resolves the effective enable state for a Claude/Codex provider from the
- * env-var value forwarded by the starter. Recognized values (case- and
- * whitespace-insensitive):
- *
- *  - `'true'`  / `'1'` → enabled
- *  - `'false'` / `'0'` → disabled
- *  - `undefined`, empty string, or any other value → falls through to
- *    {@link defaultEnabled}
- */
-export declare function isAgentEnabled(envValue: string | undefined, defaultEnabled: boolean): boolean;
-/**
- * Configuration key that controls the sandbox mode for the Copilot SDK's built-in
- * shell tool (the path taken when {@link AgentHostCustomTerminalToolEnabledSettingId}
- * is `false`). Values mirror {@link AgentSandboxEnabledValue}:
- *
- *  - `'off'` (the default): no sandbox policy is forwarded for the SDK shell
- *    path \u2014 commands run unsandboxed.
- *  - `'on'`: the Agent Host runs the SDK\u2019s shell tool inside a sandbox
- *    using the user's `chat.agent.sandbox.fileSystem.*` filesystem policy.
- *    Outbound network is enforced via the user's allow/deny host lists.
- *  - `'allowNetwork'`: same as `'on'` but with unrestricted outbound network.
- *
- * Has no effect when {@link AgentHostCustomTerminalToolEnabledSettingId} is
- * `true` \u2014 the host\u2019s own terminal sandbox engine then handles shell
- * commands and reads `chat.agent.sandbox.enabled` directly.
- */
-export declare const AgentHostSdkSandboxEnabledSettingId = "chat.agentHost.sdkSandbox.enabled";
-/**
- * Selects which Claude integration fulfills Claude sessions opened from the
- * **Agents Window**:
- *  - `true` — Claude is provided by the agent host process.
- *  - `false` (default) — Claude is provided by the GitHub Copilot Chat extension.
- *
- * The agent host always registers Claude when its SDK is reachable; this
- * setting only controls whether the per-window bridge in
- * `AgentHostContribution` actually surfaces the AH provider in the Agents
- * Window. The extension's `chatSessions` contribution mirrors the rule
- * declaratively (its `when` clause hides the EH provider when this is `true`),
- * so flipping the setting takes effect live without a window reload.
- *
- * Paired with {@link ClaudePreferAgentHostEditorSettingId} which governs the
- * regular workbench (sidebar). EXP-backed (`experiment: { mode: 'startup' }`).
- */
-export declare const ClaudePreferAgentHostAgentsSettingId = "chat.agents.claude.preferAgentHost";
-/**
- * Sibling of {@link ClaudePreferAgentHostAgentsSettingId} that selects the
- * Claude implementation for the **regular workbench** (sidebar chat in a
- * non-Agents-Window window). Same shape, same semantics — just a different
- * surface scope.
- */
-export declare const ClaudePreferAgentHostEditorSettingId = "chat.editor.claude.preferAgentHost";
-/**
- * The per-window setting that selects which Claude implementation surfaces:
- * the Agents Window reads {@link ClaudePreferAgentHostAgentsSettingId}, every
- * other window reads {@link ClaudePreferAgentHostEditorSettingId}. Callers that
- * observe the gate (to react to live flips) watch the id returned here; callers
- * that evaluate it use {@link shouldSurfaceLocalAgentHostProvider}.
- */
-export declare function claudePreferAgentHostSettingId(isSessionsWindow: boolean): string;
-/**
- * Whether this window should surface the agent host's implementation of
- * `provider`, given the per-window AH/EH preference settings. Today only the
- * `claude` provider has dual implementations (the GitHub Copilot Chat
- * extension's extension-host provider vs. the agent host's in-process
- * provider) and a corresponding preference; every other provider is AH-only
- * and unconditionally surfaced.
- *
- * Mirrors the EH-side gate declared in the extension's `chatSessions`
- * contribution `when` clause:
- *   - Agents Window  → {@link ClaudePreferAgentHostAgentsSettingId}
- *   - Editor Window  → {@link ClaudePreferAgentHostEditorSettingId}
- *
- * When the relevant setting is `false`, the extension-host Claude is the one
- * that surfaces in this window, so every agent-host surface (the chat session
- * contribution and the sessions-window picker) suppresses its own Claude to
- * avoid two identical entries.
- *
- * TODO: Remove this gate (and the `claude` special-case below) once the
- * extension-host Claude implementation is retired. With only the agent host
- * providing Claude there is no dual implementation to disambiguate, so this
- * should unconditionally return `true` and callers can drop the gate entirely.
- */
-export declare function shouldSurfaceLocalAgentHostProvider(provider: AgentProvider, configurationService: IConfigurationService, isSessionsWindow: boolean): boolean;
-/**
- * Absolute path to the **SDK root directory** containing a
- * `node_modules/@openai/codex` subtree. When non-empty, the agent host treats
- * it as a dev override and skips the on-demand download from
- * `product.agentSdks.codex`. Empty (the default) falls through to product
- * config; if neither is present, the provider is not registered.
- */
-export declare const AgentHostCodexAgentSdkRootSettingId = "chat.agentHost.codexAgent.sdkRoot";
-/**
- * Optional override for `$CODEX_HOME`. When set, the codex app-server child
- * process inherits this value, controlling where rollouts and config live.
- */
-export declare const AgentHostCodexAgentCodexHomeSettingId = "chat.agentHost.codexAgent.codexHome";
-/**
- * Additional command-line arguments passed to `codex app-server`. Mainly for
- * debugging (e.g. `--log-level=debug`).
- */
-export declare const AgentHostCodexAgentBinaryArgsSettingId = "chat.agentHost.codexAgent.binaryArgs";
-/**
- * Environment variable form of {@link AgentHostCodexAgentSdkRootSettingId}.
- * Forwarded by the starters from the setting.
- */
-export declare const AgentHostCodexAgentSdkRootEnvVar = "VSCODE_AGENT_HOST_CODEX_SDK_ROOT";
-/** Forwarded `$CODEX_HOME`. */
-export declare const AgentHostCodexAgentCodexHomeEnvVar = "CODEX_HOME";
-/** Forwarded extra args for `codex app-server` (JSON-encoded string[]). */
-export declare const AgentHostCodexAgentBinaryArgsEnvVar = "VSCODE_AGENT_HOST_CODEX_APP_SERVER_ARGS";
-/** Master toggle for agent-host OTel. Explicit opt-in; other settings imply this when set. */
-export declare const AgentHostOTelEnabledSettingId = "chat.agentHost.otel.enabled";
-/** Exporter type for the SDK's OTel pipeline. One of: `otlp-http`, `otlp-grpc`, `console`, `file`. */
-export declare const AgentHostOTelExporterTypeSettingId = "chat.agentHost.otel.exporterType";
-/**
- * OTLP wire protocol (`http/json`, `http/protobuf`, `grpc`). Policy-only delivery slot (no user UI):
- * carries the enterprise-managed `telemetry.protocol` so it can be threaded into the agent host's
- * `OTEL_EXPORTER_OTLP_PROTOCOL` env, which the runtime needs to distinguish protobuf from json
- * (the `exporterType` setting only models transport, not the HTTP wire encoding).
- */
-export declare const AgentHostOTelOtlpProtocolSettingId = "chat.agentHost.otel.otlpProtocol";
-/** OTLP endpoint URL when `exporterType` is `otlp-http` or `otlp-grpc`. */
-export declare const AgentHostOTelOtlpEndpointSettingId = "chat.agentHost.otel.otlpEndpoint";
-/** Whether to include prompt/response content in span attributes (privacy-sensitive). */
-export declare const AgentHostOTelCaptureContentSettingId = "chat.agentHost.otel.captureContent";
-/** Output path when `exporterType` is `file`. */
-export declare const AgentHostOTelOutfileSettingId = "chat.agentHost.otel.outfile";
-/** Policy-only delivery slot for the enterprise-managed OTel `service.name` (no user UI). */
-export declare const AgentHostOTelServiceNameSettingId = "chat.agentHost.otel.serviceName";
-/** Policy-only delivery slot for enterprise-managed OTel resource attributes (no user UI). */
-export declare const AgentHostOTelResourceAttributesSettingId = "chat.agentHost.otel.resourceAttributes";
-/** When true, ALL spans are persisted to a local SQLite store regardless of `exporterType`. */
-export declare const AgentHostOTelDbSpanExporterEnabledSettingId = "chat.agentHost.otel.dbSpanExporter.enabled";
-/**
- * Path of the local SQLite span database, relative to `INativeEnvironmentService.userDataPath`.
- * Kept here so both the renderer-side export action and the agent-host-side service
- * use the same on-disk location.
- */
-export declare const AgentHostOTelSpansDbSubPath = "agent-host/otel/agent-host-traces.db";
-/**
- * Environment variables consumed by `AgentHostOTelService` inside the agent host
- * process. The workbench-side agent-host starters translate the corresponding
- * `chat.agentHost.otel.*` settings into these variables (settings → env), while
- * any value already present on the parent process's env wins (developer override).
- *
- * These names match the conventions documented in
- * `extensions/copilot/docs/monitoring/agent_monitoring.md` so the same external
- * tooling and `OTEL_EXPORTER_OTLP_*` config recipes work unchanged.
- */
-export declare const AgentHostOTelEnvVars: Readonly<{
-    readonly Enabled: "COPILOT_OTEL_ENABLED";
-    readonly ExporterType: "COPILOT_OTEL_EXPORTER_TYPE";
-    readonly OtlpEndpoint: "OTEL_EXPORTER_OTLP_ENDPOINT";
-    readonly OtlpEndpointAlt: "COPILOT_OTEL_ENDPOINT";
-    readonly OtlpProtocol: "OTEL_EXPORTER_OTLP_PROTOCOL";
-    readonly OtlpTracesProtocol: "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL";
-    readonly OtlpMetricsProtocol: "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL";
-    readonly OtlpHeaders: "OTEL_EXPORTER_OTLP_HEADERS";
-    readonly CaptureContent: "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT";
-    readonly FilePath: "COPILOT_OTEL_FILE_EXPORTER_PATH";
-    readonly SourceName: "COPILOT_OTEL_SOURCE_NAME";
-    readonly ServiceName: "OTEL_SERVICE_NAME";
-    readonly ResourceAttributes: "OTEL_RESOURCE_ATTRIBUTES";
-    readonly DbSpanExporterEnabled: "COPILOT_OTEL_DB_SPAN_EXPORTER_ENABLED";
-}>;
-/**
- * Snapshot of the `chat.agentHost.otel.*` settings; produced by the workbench-side
- * starters and merged with the parent process's env (env wins on key collision).
- */
-export interface IAgentHostOTelSettings {
-    readonly enabled?: boolean;
-    readonly exporterType?: string;
-    readonly otlpProtocol?: string;
-    readonly otlpEndpoint?: string;
-    readonly captureContent?: boolean;
-    readonly outfile?: string;
-    readonly serviceName?: string;
-    readonly resourceAttributes?: Record<string, string>;
-    readonly dbSpanExporterEnabled?: boolean;
-}
-/**
- * IPC channel (renderer -> main) the desktop agent-host path uses to hand the
- * enterprise-resolved `chat.agentHost.otel.*` policy to `ElectronAgentHostStarter`.
- *
- * The main-process configuration service does NOT include the renderer-only
- * `AccountPolicyService` (managed settings: server / native-MDM / file channels), so a
- * starter running in the main process sees `policyValue === undefined` for these keys.
- * The renderer — whose policy layer does include managed settings — forwards the resolved
- * values here just before requesting the agent-host connection, so the host is spawned with
- * the managed OTel env. See {@link readAgentHostOTelPolicySettings}.
- */
-export declare const AgentHostOTelPolicyIpcChannel = "vscode:agentHostOTelPolicy";
-/**
- * Resolve the enterprise-policy values for the `chat.agentHost.otel.*` settings from a
- * configuration service whose policy layer includes managed settings (i.e. the renderer's).
- * Each field is `undefined` when no policy is set. Intended as the `policySettings` argument
- * of {@link buildAgentHostOTelEnv}.
- */
-export declare function readAgentHostOTelPolicySettings(configurationService: IConfigurationService): IAgentHostOTelSettings;
-/**
- * Validate/normalize an {@link IAgentHostOTelSettings} received over IPC, keeping only
- * well-typed fields. Defends the main process against a malformed payload before the values
- * are turned into agent-host process env vars.
- */
-export declare function sanitizeAgentHostOTelPolicySettings(raw: unknown): IAgentHostOTelSettings;
-/**
- * Build the env-var overlay for the agent host process from user settings and
- * inherited env. Settings are translated to env vars, but if the same env var is
- * already present on `inheritedEnv` it wins (developer override).
- *
- * Only sets a key when the underlying setting was explicitly configured — empty
- * string / undefined settings are dropped so they don't shadow inherited env.
- */
-export declare function buildAgentHostOTelEnv(settings: IAgentHostOTelSettings, inheritedEnv: Readonly<Record<string, string | undefined>>, policySettings?: IAgentHostOTelSettings): Record<string, string>;
-/**
- * Settings -> env-var fan-out for the Claude/Codex SDK overrides that the
- * agent host process consumes. Shared by both starters
- * (`nodeAgentHostStarter.ts`, `electronAgentHostStarter.ts`) so they don't
- * drift the next time someone adds a setting.
- *
- * The shape mirrors {@link buildAgentHostOTelEnv}: only set a key when the
- * underlying setting has a non-empty value AND the inherited env doesn't
- * already define it (developer override wins). Returns a partial env map
- * the caller spreads into the spawned child's environment.
- */
-export interface IAgentSdkStarterSettings {
-    readonly codexSdkRoot?: string;
-    readonly codexHome?: string;
-    readonly codexBinaryArgs?: readonly string[];
-    readonly claudeAgentEnabled?: boolean;
-    readonly codexAgentEnabled?: boolean;
-    readonly byokModelsEnabled?: boolean;
-}
-export declare function buildAgentSdkEnv(settings: IAgentSdkStarterSettings, inheritedEnv: Readonly<Record<string, string | undefined>>): Record<string, string>;
-/** Result of starting the agent host WebSocket server on-demand. */
-export interface IAgentHostSocketInfo {
-    readonly socketPath: string;
-}
-/** Inspector listener information for the agent host process. */
-export interface IAgentHostInspectInfo {
-    readonly host: string;
-    readonly port: number;
-    /** A `devtools://` URL that can be opened with `INativeHostService.openDevToolsWindow`. */
-    readonly devtoolsUrl: string;
-}
-/**
- * IPC service exposed on the {@link AgentHostIpcChannels.ConnectionTracker}
- * channel. Used by the server process for lifetime management and by the
- * shared process to request a local WebSocket listener on-demand.
- */
-export interface IConnectionTrackerService {
-    readonly onDidChangeConnectionCount: Event<number>;
-    /**
-     * Request the agent host to start a WebSocket server on a local
-     * pipe/socket. Returns the socket path.
-     * If a server is already running, returns the existing info.
-     */
-    startWebSocketServer(): Promise<IAgentHostSocketInfo>;
-    /**
-     * Get inspector listener info for the agent host process. If the inspector
-     * is not currently active and `tryEnable` is true, opens the inspector on
-     * a random local port. Returns `undefined` if the inspector cannot be
-     * enabled (e.g. running in an environment without `node:inspector`).
-     */
-    getInspectInfo(tryEnable: boolean): Promise<IAgentHostInspectInfo | undefined>;
-}
-export interface IAgentSessionMetadata {
-    readonly session: URI;
-    readonly startTime: number;
-    readonly modifiedTime: number;
-    readonly project?: IAgentSessionProjectInfo;
-    readonly summary?: string;
-    readonly status?: SessionStatus;
-    /** Human-readable description of what the session is currently doing. */
-    readonly activity?: string;
-    readonly workingDirectory?: URI;
-    readonly customizationDirectory?: URI;
-    readonly isRead?: boolean;
-    readonly isArchived?: boolean;
-    /**
-     * Aggregate counts (additions / deletions / files) describing the
-     * `changeKind: 'session'` changeset for this session — the chip
-     * aggregate previously embedded in the catalogue entry. Mirrors
-     * `SessionSummary.changes`.
-     */
-    readonly changes?: ChangesSummary;
-    /**
-     * Catalogue of changesets the agent can produce for this session — the
-     * {@link Changeset | catalogue} that travels on
-     * `SessionSummary.changesets`. Lightweight summary entries (id / label /
-     * URI template / aggregate counts) without per-file detail; clients
-     * subscribe to a specific expanded changeset URI when they need the full
-     * file list.
-     */
-    readonly changesets?: readonly Changeset[];
-    /**
-     * Side-channel metadata mirroring {@link SessionState._meta}, propagated
-     * to clients via per-session state subscriptions and the root-channel
-     * session summary (the host treats the session-state and session-summary
-     * `_meta` as the same bag). Producers SHOULD use namespaced keys; consumers
-     * MUST ignore unknown keys. Use the typed accessors in `sessionState.ts`
-     * (e.g. `readSessionGitState`, `readSessionGitHubState`) for well-known
-     * slots.
-     */
-    readonly _meta?: SessionMeta;
-}
-export interface IAgentSessionProjectInfo {
-    readonly uri: URI;
-    readonly displayName: string;
-}
-export interface IAgentCreateSessionResult {
-    readonly session: URI;
-    readonly project?: IAgentSessionProjectInfo;
-    /** The resolved working directory, which may differ from the requested one (e.g. worktree). */
-    readonly workingDirectory?: URI;
-    /**
-     * `true` when the agent only allocated an in-memory placeholder for this
-     * session (no SDK session, no worktree, no on-disk state). Materialization
-     * happens lazily on the first {@link IAgentChats.sendMessage}, at which point
-     * the agent fires {@link IAgent.onDidMaterializeSession}. The
-     * {@link IAgentService} uses this flag to defer the `sessionAdded` protocol
-     * notification so observers don't see the session in their list until it
-     * has been persisted.
-     */
-    readonly provisional?: boolean;
-}
-/**
- * Payload of {@link IAgent.onDidMaterializeSession}. Fired once per session
- * when a previously {@link IAgentCreateSessionResult.provisional} session has
- * its SDK session, worktree (if any), and on-disk metadata in place.
- */
-export interface IAgentMaterializeSessionEvent {
-    readonly session: URI;
-    readonly workingDirectory: URI | undefined;
-    readonly project: IAgentSessionProjectInfo | undefined;
-}
-export type AgentProvider = string;
-/** Well-known agent provider id for the Claude agent-host backend. */
-export declare const CLAUDE_AGENT_PROVIDER_ID: "claude";
-/**
- * Static capability facts an agent backend advertises about itself. Each flag
- * is opt-in (absent means unsupported) so single-chat agents (e.g. Codex) can omit
- * the bag entirely. Discovered over IPC alongside the rest of
- * {@link IAgentDescriptor} and surfaced to the sessions UI so features are
- * capability-gated instead of switched on the provider id.
- *
- * This is the IPC contract alias of the protocol-visible {@link AgentCapabilities}
- * type (defined in the root-state protocol); both share a single canonical shape
- * so a new flag added in one place is automatically reflected in the other.
- */
-export type IAgentCapabilities = AgentCapabilities;
-/** Metadata describing an agent backend, discovered over IPC. */
-export interface IAgentDescriptor {
-    readonly provider: AgentProvider;
-    readonly displayName: string;
-    readonly description: string;
-    /** Static capability flags the agent advertises (see {@link IAgentCapabilities}). */
-    readonly capabilities?: IAgentCapabilities;
-}
-/**
- * Parameters for the `authenticate` command.
- * Analogous to sending `Authorization: Bearer <token>` (RFC 6750 section 2.1).
- */
-export interface AuthenticateParams {
-    /**
-     * The `resource` identifier from the server's
-     * {@link IAuthorizationProtectedResourceMetadata} that this token targets.
-     */
-    readonly resource: string;
-    /**
-     * Scopes that were used to acquire the token. Omitted for legacy clients
-     * that can only identify tokens by protected resource.
-     */
-    readonly scopes?: readonly string[];
-    /** The bearer token value (RFC 6750). */
-    readonly token: string;
-}
-/** Request for a previously accepted bearer token. */
-export interface IAgentHostAuthTokenRequest {
-    /** Protected resource identifier from {@link ProtectedResourceMetadata.resource}. */
-    readonly resource: string;
-    /** Required token scopes, when the caller needs a scope-specific token. */
-    readonly scopes?: readonly string[];
-}
-/**
- * Result of the `authenticate` command.
- */
-export interface AuthenticateResult {
-    /** Whether the token was accepted. */
-    readonly authenticated: boolean;
-}
-/**
- * Canonical {@link ProtectedResourceMetadata} for the GitHub Copilot
- * resource. Shared between every agent provider that consumes a GitHub
- * Copilot bearer token (e.g. Copilot CLI, Claude) so they advertise an
- * identical resource identifier to the auth flow — clients dispatch by
- * `resource`, and divergent metadata would silently route the same
- * token down separate code paths.
- */
-export declare const GITHUB_COPILOT_PROTECTED_RESOURCE: ProtectedResourceMetadata;
-/**
- * Canonical {@link ProtectedResourceMetadata} for GitHub repository write
- * operations (e.g. creating a pull request). Distinct from
- * {@link GITHUB_COPILOT_PROTECTED_RESOURCE} so that the broader `repo`
- * scope is only requested when a session actually needs it (e.g. when a
- * changeset operation handler throws `AHP_AUTH_REQUIRED` with this
- * resource), rather than at session create for every agent.
- *
- * `required: false` reflects that the resource is only needed on demand —
- * agents do not have to advertise it eagerly. The workbench-side auth
- * contributor resolves it lazily in response to operation invocations.
- */
-export declare const GITHUB_REPO_PROTECTED_RESOURCE: ProtectedResourceMetadata;
-export interface IAgentCreateSessionConfig {
-    readonly provider?: AgentProvider;
-    readonly model?: ModelSelection;
-    /**
-     * Initial custom agent selection for the new session. Omit to start with
-     * no custom agent selected (provider default behavior).
-     */
-    readonly agent?: AgentSelection;
-    readonly session?: URI;
-    readonly workingDirectory?: URI;
-    readonly config?: Record<string, unknown>;
-    /**
-     * Eagerly claim the active client role for the new session. When provided,
-     * the server initializes the session with this client as the active
-     * client, equivalent to dispatching a `session/activeClientSet`
-     * action immediately after creation. The `clientId` MUST match the
-     * connection's own `clientId`.
-     */
-    readonly activeClient?: SessionActiveClient;
-    /** Fork from an existing session at a specific turn. */
-    readonly fork?: {
-        readonly session: URI;
-        readonly turnIndex: number;
-        readonly turnId: string;
-        /**
-         * Maps old protocol turn IDs to new protocol turn IDs.
-         * Populated by the service layer after generating fresh UUIDs
-         * for the forked session's turns. Used by the agent to remap
-         * per-turn data (e.g. SDK event ID mappings) in the session database.
-         */
-        readonly turnIdMapping?: ReadonlyMap<string, string>;
-    };
-    /**
-     * MCP-style opt-in progress token from the client's `createSession`. When
-     * set, the service reports any long-running session bring-up work — chiefly
-     * the lazy first-use SDK download — as `progress` notifications carrying
-     * this token, so the client can correlate them to this call.
-     */
-    readonly progressToken?: string;
-}
-/** Options for creating an additional chat within a session. */
-export interface IAgentCreateChatOptions {
-    /** Optional display title for the new chat. */
-    readonly title?: string;
-    /** Optional model override; defaults to the session's model. */
-    readonly model?: ModelSelection;
-    /**
-     * Fork an existing chat into this new chat. The new chat starts
-     * pre-populated with the source chat's turns up to and including
-     * {@link IAgentCreateChatForkSource.turnId}, and its backing chat
-     * is forked from the source so it can continue independently.
-     */
-    readonly fork?: IAgentCreateChatForkSource;
-}
-/** Identifies a source chat and turn to fork a new chat from. */
-export interface IAgentCreateChatForkSource {
-    /** URI of the existing chat to fork from. */
-    readonly source: URI;
-    /** Turn ID in the source chat; content up to and including this turn is copied. */
-    readonly turnId: string;
-    /**
-     * Maps old source turn IDs to fresh turn IDs for the forked chat. Populated
-     * by the agent service so the agent can remap per-turn data (e.g. SDK event
-     * ID mappings) in the forked chat's database.
-     */
-    readonly turnIdMapping?: ReadonlyMap<string, string>;
-}
-/** Result of {@link IAgentChats.createChat}: the opaque blob to persist for restore. */
-export interface IAgentCreateChatResult {
-    /**
-     * Opaque, agent-owned token the orchestrator persists verbatim in the chat
-     * catalog and hands back to {@link IAgent.materializeChat} on
-     * restore. The orchestrator never parses it. `undefined` means nothing to
-     * persist (e.g. the agent keeps no resumable backing).
-     */
-    readonly providerData?: string;
-    /**
-     * The SDK-level session URI that backs this peer chat, when the agent mints
-     * one in the same session store its own {@link IAgent.listSessions} enumerates
-     * (e.g. Claude). First-class and non-opaque — unlike {@link providerData} the
-     * orchestrator reads it to correlate and suppress the backing session so it
-     * never surfaces as a top-level session. `undefined` when the agent keeps no
-     * separately-enumerable backing session.
-     */
-    readonly backingSession?: URI;
-}
-/** Payload of {@link IAgent.onDidChangeChatData}. */
-export interface IAgentChatDataChange {
-    /** The peer chat whose backing chat's blob changed. */
-    readonly chat: URI;
-    /** The new opaque blob to persist (replaces any previously stored value). */
-    readonly providerData: string;
-}
-/** A legacy peer chat enumerated by {@link IAgent.listLegacyChats} for one-time migration. */
-export interface IAgentLegacyChat {
-    /** The peer chat's channel URI (see {@link buildChatUri}). */
-    readonly uri: URI;
-    /** The opaque, agent-owned backing blob, encoded as {@link materializeChat} expects. */
-    readonly providerData?: string;
-}
-/**
- * Identifies the parent that spawned a chat. The orchestrator records
- * it as the spawned chat's {@link ChatOriginKind.Tool} origin so clients can
- * render the parent/child relationship (e.g. a sub-agent "team" member spawned
- * by a tool call in the parent chat).
- */
-export interface IAgentSpawnedChatParent {
-    /** The parent chat (chat) URI whose tool call performed the spawn. */
-    readonly chat: URI;
-    /** The id of the tool call in the parent that spawned this chat. */
-    readonly toolCallId: string;
-}
-/**
- * Payload of {@link IAgent.onDidSpawnChat}: a new chat the
- * agent spawned itself (e.g. a sub-agent delegated by a tool call), as opposed
- * to a user-driven chat created via
- * {@link IAgentChats.createChat}.
- */
-export interface IAgentSpawnChatEvent {
-    /** The session URI the spawned chat belongs to. */
-    readonly session: URI;
-    /** The spawned chat's channel URI (the new chat). */
-    readonly chat: URI;
-    /**
-     * The parent that spawned it, when the spawn was delegated by a tool call.
-     * Recorded as the chat's tool origin in the catalog. Absent for a
-     * top-level, agent-initiated chat with no spawning tool call.
-     */
-    readonly parent?: IAgentSpawnedChatParent;
-    /** Optional display title for the spawned chat. */
-    readonly title?: string;
-}
-/**
- * Builds the tab title for a subagent peer chat. Prefers the concise
- * per-task description (so two subagents of the same type still get
- * distinct, meaningful names), truncating it so an over-long value never
- * blows out the tab strip or the Subagents dropdown; falls back to the
- * agent type's display name, then a generic label. Shared by the live
- * spawn path and the restore path so both name subagent tabs identically.
- */
-export declare function subagentChatTitle(taskDescription: string | undefined, agentDisplayName: string | undefined): string;
-/**
- * Maps agent `subagent_*` signals to the unified chat catalog's
- * spawn/end events. Shared by the agents' spawn bridges and the orchestrator so
- * subagent membership has one derivation.
- */
-export declare namespace SubagentChatSignal {
-    /**
-     * Derives the {@link IAgentSpawnChatEvent} for a `subagent_started` signal,
-     * addressing the subagent by the stable {@link buildSubagentChatUri} and
-     * recording the spawning tool call as its parent edge. Returns `undefined`
-     * for any other signal (or an unmappable chat URI).
-     */
-    function toSpawnEvent(signal: AgentSignal): IAgentSpawnChatEvent | undefined;
-}
-/**
- * The chat-addressed operation surface an agent exposes for the chats
- * within a session.
- *
- * Every operation method addresses a chat by a concrete chat channel URI:
- * the default chat channel for a session's DEFAULT chat, or an additional
- * chat's own channel URI. The orchestrator ({@link IAgentService}) owns the
- * feature-level `(session, chat)` to chat-channel mapping and only ever calls
- * these operations with a concrete chat URI. This replaces the legacy
- * `(session, chat?)` parameter pairs and the per-agent default-chat handling on
- * {@link IAgent}.
- *
- * Optional on {@link IAgent}: agents implement this incrementally (waves
- * C2/C3/C4). Until an agent exposes it, {@link IAgentService} falls back to the
- * agent's legacy `(session, chat?)` methods via a thin adapter.
- */
-export interface IAgentChats {
-    /**
-     * Create a fresh additional chat within the session the `chat` URI belongs
-     * to, sharing the session's working directory, model, agent, and
-     * customizations. `chat` is the client-chosen channel URI the new chat is
-     * addressed by; its parent session is derived from it.
-     * Returns the opaque {@link IAgentCreateChatResult} blob to persist for
-     * restore (or `void` when the agent keeps no resumable backing).
-     */
-    createChat(chat: URI, options?: IAgentCreateChatOptions): Promise<IAgentCreateChatResult | void>;
-    /**
-     * Fork a new chat from an existing one. The new `chat`
-     * inherits `source`'s backing up to and including
-     * {@link IAgentCreateChatForkSource.turnId} and then continues
-     * independently. The new chat's parent session is derived from its URI.
-     */
-    fork(chat: URI, source: IAgentCreateChatForkSource, options?: IAgentCreateChatOptions): Promise<IAgentCreateChatResult | void>;
-    /**
-     * Dispose an additional chat created via
-     * {@link createChat}/{@link fork}, freeing its backing. A session's
-     * default chat cannot be disposed in isolation; it lives and dies
-     * with the session.
-     */
-    disposeChat(chat: URI): Promise<void>;
-    /** Send a user message into `chat`. */
-    sendMessage(chat: URI, prompt: string, attachments?: readonly MessageAttachment[], turnId?: string, senderClientId?: string): Promise<void>;
-    /** Abort the in-flight turn for `chat`. */
-    abort(chat: URI): Promise<void>;
-    /** Change the model for `chat`. */
-    changeModel(chat: URI, model: ModelSelection): Promise<void>;
-    /**
-     * Change (or clear) the selected custom agent for `chat`. Passing
-     * `undefined` clears the selection (provider default behavior).
-     */
-    changeAgent(chat: URI, agent: AgentSelection | undefined): Promise<void>;
-    /** Reconstruct the turns for `chat` (used on restore). */
-    getMessages(chat: URI): Promise<readonly Turn[]>;
-}
-export interface IAgentResolveSessionConfigParams {
-    readonly provider?: AgentProvider;
-    readonly workingDirectory?: URI;
-    readonly config?: Record<string, unknown>;
-}
-export interface IAgentSessionConfigCompletionsParams extends IAgentResolveSessionConfigParams {
-    readonly property: string;
-    readonly query?: string;
-}
-/** Serializable model information from the agent host. */
-export interface IAgentModelInfo {
-    readonly provider: AgentProvider;
-    readonly id: string;
-    readonly name: string;
-    readonly maxContextWindow?: number;
-    readonly maxOutputTokens?: number;
-    readonly maxPromptTokens?: number;
-    readonly supportsVision: boolean;
-    readonly configSchema?: ConfigSchema;
-    readonly policyState?: PolicyState;
-    readonly _meta?: Record<string, unknown>;
-}
-/**
- * A signal emitted by an agent during session execution.
- *
- * Most signals carry a protocol {@link SessionAction} directly via the
- * `kind: 'action'` shape, eliminating a parallel event ontology. A small
- * number of cases that have no clean protocol action (permission
- * auto-approval, subagent session creation, steering message
- * acknowledgment) remain as discriminated non-action signals so the host
- * can perform side effects before — or instead of — dispatching an action.
- */
-export type AgentSignal = IAgentActionSignal | IAgentToolPendingConfirmationSignal | IAgentSubagentStartedSignal | IAgentSubagentCompletedSignal | IAgentSteeringConsumedSignal;
-/**
- * Carries a protocol {@link SessionAction} produced by an agent. The host
- * dispatches the action through the state manager after routing via
- * {@link IAgentActionSignal.parentToolCallId} (if set).
- *
- * Agents are responsible for populating the target channel and any `turnId` /
- * `partId` fields on the action.
- */
-export interface IAgentActionSignal {
-    readonly kind: "action";
-    /** Target session or chat channel URI. For inner subagent events this is the parent session — see {@link parentToolCallId}. */
-    readonly resource: URI;
-    /** Protocol action to dispatch. */
-    readonly action: SessionAction | ChatAction;
-    /** If set, route the action to the subagent session belonging to this tool call. */
-    readonly parentToolCallId?: string;
-}
-/**
- * A tool has finished collecting parameters and needs the host to decide
- * whether it should run (or, mid-execution, re-confirm). The host applies
- * auto-approval logic over {@link permissionKind} / {@link permissionPath}
- * (see `SessionPermissionManager.getAutoApproval`) and then dispatches the
- * appropriate `ChatToolCallReady` action — with confirmation options
- * baked in when the user must approve, or with `confirmed: NotNeeded` when
- * the host auto-approved.
- *
- * Kept as a non-action signal because the host owns this approval policy;
- * the agent only describes the tool call and the kind of permission being
- * requested. The {@link state} field carries the protocol-shaped tool-call
- * state and is dispatched verbatim into the action.
- */
-export interface IAgentToolPendingConfirmationSignal {
-    readonly kind: "pending_confirmation";
-    /** Target chat channel URI containing the tool call. */
-    readonly chat: URI;
-    /** Protocol-shaped pending-confirmation state, dispatched verbatim into `ChatToolCallReady`. */
-    readonly state: ToolCallPendingConfirmationState;
-    /** Host-only auto-approval kind (not part of the dispatched action). */
-    readonly permissionKind?: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool" | "hook" | "memory" | "extension-management" | "extension-permission-access";
-    /** Host-only auto-approval path target (not part of the dispatched action). */
-    readonly permissionPath?: string;
-    /**
-     * Host-only flag (not part of the dispatched action): the model requested
-     * this shell command run OUTSIDE the sandbox (and the host opted in via
-     * `sandbox.allowBypass`).
-     */
-    readonly requestSandboxBypass?: boolean;
-    /**
-     * If set, the tool call belongs to the subagent rooted at this
-     * parent tool call. Used by the host to route the resulting
-     * `ChatToolCallReady` to the subagent session — otherwise the
-     * action would land on the parent session, where there is no
-     * matching `ChatToolCallStart`.
-     */
-    readonly parentToolCallId?: string;
-}
-/**
- * A subagent was spawned by a tool call. The host creates a child session
- * silently and routes subsequent inner-tool events to it.
- *
- * Kept as a non-action signal because subagent session creation has no
- * protocol action — it's a host-side composition primitive.
- */
-export interface IAgentSubagentStartedSignal {
-    readonly kind: "subagent_started";
-    readonly chat: URI;
-    readonly toolCallId: string;
-    readonly agentName: string;
-    readonly agentDisplayName: string;
-    readonly agentDescription?: string;
-    /**
-     * The spawning Task tool's short (typically 3-5 word) `description`
-     * input, e.g. "Review package.json structure". Distinct from
-     * {@link agentDescription} (the agent *type*'s long role blurb) and
-     * {@link agentDisplayName} (the agent type's name). Preferred as the
-     * peer chat's tab title because it is concise and per-task, so two
-     * subagents of the same type still get distinct, meaningful names.
-     * Absent when the harness does not surface a task description.
-     */
-    readonly taskDescription?: string;
-    /**
-     * If set, the spawning tool call ({@link toolCallId}) itself lives
-     * inside another subagent's chat — this is the tool call **one level up**
-     * from the spawning tool (its parent), i.e. the tool that spawned the
-     * immediate parent chat. The host uses it to route the
-     * subagent-discovery side effect (the `ChatToolCallContentChanged`
-     * block that lets clients find the child chat) to that immediate parent
-     * chat rather than the top-level {@link chat}. Because subagent chats
-     * are flat (all keyed off the root session + the spawning tool id),
-     * this single one-hop reference resolves the correct parent chat at
-     * ANY nesting depth — no per-level chain is needed. Absent for a
-     * top-level subagent, whose spawning tool call lives directly in
-     * {@link chat}.
-     */
-    readonly parentToolCallId?: string;
-}
-/**
- * A subagent has finished — either successfully or with an error. The host
- * uses this to tear down the child session after all of its events have been
- * routed. The parent tool call completing is not a reliable signal for this
- * because background subagents (e.g. Copilot's `mode: background` task) keep
- * emitting events after their parent tool call returns immediately.
- */
-export interface IAgentSubagentCompletedSignal {
-    readonly kind: "subagent_completed";
-    readonly chat: URI;
-    readonly toolCallId: string;
-}
-/** A steering message was consumed (sent to the model). */
-export interface IAgentSteeringConsumedSignal {
-    readonly kind: "steering_consumed";
-    readonly chat: URI;
-    readonly id: string;
-}
-export declare namespace AgentSession {
-    /**
-     * Creates a session URI from a provider name and raw session ID.
-     * The URI scheme is the provider name (e.g., `copilot:/<rawId>`).
-     */
-    function uri(provider: AgentProvider, rawSessionId: string): URI;
-    /**
-     * Extracts the raw session ID from a session URI (the path without leading slash).
-     * Accepts both a URI object and a URI string.
-     */
-    function id(session: URI | string): string;
-    /**
-     * Extracts the provider name from a session URI scheme.
-     * Accepts both a URI object and a URI string.
-     */
-    function provider(session: URI | string): AgentProvider | undefined;
-}
-/**
- * A notification originating from an MCP server, routed back to the AHP
- * client through the `mcp://` side channel. `channel` is the channel
- * URI advertised on the owning
- * {@link McpServerCustomization.channel | McpServerCustomization}; the
- * client uses it to fan the notification out to the appropriate App.
- * `method` and `params` follow the underlying MCP notification spec
- * (e.g. `notifications/tools/list_changed`).
- */
-export interface IMcpNotification {
-    readonly channel: string;
-    readonly method: string;
-    readonly params?: Record<string, unknown>;
-}
-/**
- * A subagent child session discovered in a parent session's event log,
- * returned by {@link IAgent.getSubagentSessions} so a parent restore can
- * register the child's state up-front.
- */
-export interface IRestoredSubagentSession {
-    /** Child subagent session URI (subscribable by clients). */
-    readonly resource: URI;
-    /** Parent tool call id that spawned the subagent. */
-    readonly toolCallId: string;
-    /** Display title for the subagent session. */
-    readonly title: string;
-    /** Reconstructed turns for the subagent's transcript. */
-    readonly turns: readonly Turn[];
-}
-/**
- * A per-session handle for one active client's contributions (tools and
- * plugin customizations) to an agent session, obtained via
- * {@link IAgent.getOrCreateActiveClient}.
- *
- * `tools` and `customizations` are mutable accessor properties: assigning a
- * new array replaces this client's contribution wholesale and triggers the
- * agent's internal reaction (refreshing the merged tool set exposed to the
- * model, or kicking off an asynchronous customization sync). The arrays are
- * `readonly` so callers cannot mutate them in place and silently bypass the
- * setter. The agent merges the contributions of all active clients on a
- * session, deduplicating as needed.
- */
-export interface IActiveClient {
-    /** Client identifier (matches `clientId` from `initialize`). */
-    readonly clientId: string;
-    /** Human-readable client name (e.g. `"VS Code"`), if provided. */
-    readonly displayName: string | undefined;
-    /** This client's tools. Assigning replaces the set (full replacement). */
-    tools: readonly ToolDefinition[];
-    /** This client's plugin customizations. Assigning replaces the set and starts an internal sync. */
-    customizations: readonly ClientPluginCustomization[];
-}
-/**
- * Implemented by each agent backend (e.g. Copilot SDK).
- * The {@link IAgentService} dispatches to the appropriate agent based on
- * the agent id.
- */
-export interface IAgent {
-    /** Unique identifier for this provider (e.g. `'copilot'`). */
-    readonly id: AgentProvider;
-    /** Fires when the provider streams progress for a session. */
-    readonly onDidSessionProgress: Event<AgentSignal>;
-    /**
-     * Fires once when a previously
-     * {@link IAgentCreateSessionResult.provisional} session has been
-     * materialized — i.e. its SDK session, worktree (if any), and on-disk
-     * metadata are all in place. The {@link IAgentService} uses this event
-     * to fire the deferred `sessionAdded` notification with the now-final
-     * summary.
-     */
-    readonly onDidMaterializeSession?: Event<IAgentMaterializeSessionEvent>;
-    /**
-     * Provides the agent host's server-tool host so the provider can advertise
-     * and execute the agent host's server tools (feedback "comments" today, more
-     * in the future) against a session's state. Optional: providers that do not
-     * support server-side tools simply omit it. Called once during registration
-     * with the {@link IAgentService}.
-     */
-    setServerToolHost?(host: IAgentServerToolHost): void;
-    /**
-     * Chat-addressed surface for the chats within a session (send/abort/
-     * change model/agent, create/fork/dispose chats, read history).
-     */
-    readonly chats: IAgentChats;
-    /** Create a new session. Returns server-owned session metadata. */
-    createSession(config?: IAgentCreateSessionConfig): Promise<IAgentCreateSessionResult>;
-    /** Resolve the dynamic configuration schema for creating a session. */
-    resolveSessionConfig(params: IAgentResolveSessionConfigParams): Promise<ResolveSessionConfigResult>;
-    /** Return dynamic completions for a session configuration property. */
-    sessionConfigCompletions(params: IAgentSessionConfigCompletionsParams): Promise<SessionConfigCompletionsResult>;
-    /**
-     * Re-attach an agent's in-memory backing for a peer chat on session
-     * restore, decoding the opaque `providerData` produced earlier by
-     * {@link IAgentChats.createChat} (or the latest
-     * {@link onDidChangeChatData}). After this resolves the agent MUST
-     * be able to serve {@link getSessionMessages}/
-     * {@link IAgentChats.sendMessage} for `chat`.
-     * Best-effort: implementations SHOULD NOT throw on a corrupt/unknown blob —
-     * log and no-op so the orchestrator restores the chat with history but no
-     * live backing. `providerData` is `undefined` only for legacy entries with
-     * no stored blob, in which case the agent MAY consult its own legacy
-     * persistence once to recover the backing.
-     */
-    materializeChat?(chat: URI, providerData: string | undefined): Promise<void>;
-    /**
-     * Migration-only enumeration of a session's peer chats persisted in the
-     * agent's OWN legacy format (predating the orchestrator-owned catalog). The
-     * orchestrator calls this once, when its own catalog is absent, to drain the
-     * legacy chats into {@link PEER_CHATS_METADATA_KEY}; subsequent restores read
-     * the orchestrator catalog and never consult this again. Each entry's
-     * `providerData` uses the same encoding {@link IAgentChats.createChat}
-     * produces and {@link materializeChat} decodes. Agents with no legacy
-     * format (e.g. Codex) omit this method.
-     */
-    listLegacyChats?(session: URI): Promise<readonly IAgentLegacyChat[]>;
-    /**
-     * Fires when a peer chat's opaque `providerData` changes after creation
-     * (e.g. per-chat model switch, fork remap). The orchestrator re-persists the
-     * blob. Agents whose blob is immutable never fire this.
-     */
-    readonly onDidChangeChatData?: Event<IAgentChatDataChange>;
-    /**
-     * Fires when the agent spawns a new chat within a session (e.g. a
-     * sub-agent delegated by a tool call). The orchestrator records it in the
-     * chat catalog, preserving the {@link IAgentSpawnChatEvent.parent}
-     * spawn edge as the chat's {@link ChatOriginKind.Tool} origin.
-     */
-    readonly onDidSpawnChat?: Event<IAgentSpawnChatEvent>;
-    /**
-     * Called when the session's pending (steering) message changes.
-     * The agent harness decides how to react — e.g. inject steering
-     * mid-turn via `mode: 'immediate'`. When `chat` is provided (an additional
-     * peer chat's URI), the steering targets that chat's chat rather
-     * than the session's default chat.
-     *
-     * Queued messages are consumed on the server side and are not
-     * forwarded to the agent; `queuedMessages` will always be empty.
-     */
-    setPendingMessages?(session: URI, steeringMessage: PendingMessage | undefined, queuedMessages: readonly PendingMessage[], chat?: URI): void;
-    /**
-     * Retrieve the reconstructed turns for a session, used when restoring
-     * sessions from persistent storage. Each agent owns the conversion from
-     * its SDK-specific event log to protocol {@link Turn}s, including
-     * subagent sessions (callers pass the subagent URI to retrieve the
-     * child session's turns).
-     */
-    getSessionMessages(session: URI): Promise<readonly Turn[]>;
-    /**
-     * Returns the subagent child sessions discoverable in a session's event
-     * log so a parent restore can eagerly register them in a single pass.
-     * Without this, every child is restored separately by re-fetching and
-     * re-reconstructing the full parent event log (one pass per subagent).
-     * Agents that serve this from the same reconstruction they already
-     * produced for the parent turns avoid that redundant work entirely.
-     * Optional; agents without subagents omit it.
-     */
-    getSubagentSessions?(session: URI): Promise<readonly IRestoredSubagentSession[]>;
-    /** Dispose a session, freeing resources. */
-    disposeSession(session: URI): Promise<void>;
-    /** Respond to a pending permission request from the SDK. */
-    respondToPermissionRequest(requestId: string, approved: boolean): void;
-    /** Respond to a pending user input request from the SDK's ask_user tool. */
-    respondToUserInputRequest(requestId: string, response: ChatInputResponseKind, answers?: Record<string, ChatInputAnswer>): void;
-    /** Return the descriptor for this agent. */
-    getDescriptor(): IAgentDescriptor;
-    /** Available models from this provider. */
-    readonly models: IObservable<readonly IAgentModelInfo[]>;
-    /** List persisted sessions from this provider. */
-    listSessions(): Promise<IAgentSessionMetadata[]>;
-    /** Retrieve metadata for a single persisted session, without enumerating the provider catalog. */
-    getSessionMetadata?(session: URI): Promise<IAgentSessionMetadata | undefined>;
-    /** Declare protected resources this agent requires auth for (RFC 9728). */
-    getProtectedResources(): ProtectedResourceMetadata[];
-    /**
-     * Fires when the agent's host-owned customizations change
-     * (loading state, resolution results, etc.), so infrastructure
-     * can republish {@link AgentInfo} and session customization state.
-     */
-    readonly onDidCustomizationsChange?: Event<void>;
-    /**
-     * Fires when this agent needs the client to (re-)authenticate a
-     * protected resource — for example after a runtime transport-mode flip
-     * makes a previously-unneeded credential required. The host stamps the
-     * root channel and forwards it verbatim as an `auth/required`
-     * notification; clients respond via {@link authenticate}.
-     */
-    readonly onDidRequireAuth?: Event<Omit<AuthRequiredParams, "channel">>;
-    /**
-     * Returns the host-owned customizations this agent currently exposes.
-     *
-     * Used to publish baseline customization metadata on {@link AgentInfo}.
-     * Always container customizations ({@link PluginCustomization} or
-     * {@link DirectoryCustomization}).
-     */
-    getCustomizations?(): readonly Customization[];
-    /**
-     * Returns the effective customization list for a session, including
-     * source, enablement, and loading/error status.
-     */
-    getSessionCustomizations?(session: URI): Promise<readonly Customization[]>;
-    /**
-     * Authenticate for a specific resource. Returns true if accepted.
-     * The `resource` matches {@link IAuthorizationProtectedResourceMetadata.resource}.
-     */
-    authenticate(resource: string, token: string): Promise<boolean>;
-    /**
-     * Optional hook for provider-owned session resources that are not advertised
-     * as root agent protected resources, such as MCP server OAuth challenges.
-     */
-    handleAuthenticationToken?(params: AuthenticateParams): Promise<boolean>;
-    /**
-     * Truncate a chat's history. If `turnId` is provided, keeps turns up to
-     * and including that turn. If omitted, all turns are removed.
-     *
-     * `chat` identifies which chat to truncate: the session's default chat
-     * (addressed by the session's default chat URI) or a peer (non-default)
-     * chat, which has its own backing.
-     *
-     * Optional — not all providers support truncation.
-     */
-    truncateSession?(session: URI, turnId: string | undefined, chat: URI): Promise<void>;
-    /**
-     * Notifies the provider that a session's archived state has changed.
-     * Providers may use this to clean up or restore per-session resources
-     * (for example, removing a session-owned worktree on archive and
-     * recreating it on unarchive). Optional.
-     */
-    onArchivedChanged?(session: URI, isArchived: boolean): Promise<void>;
-    /**
-     * Get (or lazily create) the per-session handle for an active client,
-     * identified by `clientId`. Mutating the returned {@link IActiveClient}'s
-     * `tools` / `customizations` updates only that client's contribution; the
-     * agent merges the contributions of all active clients when exposing them
-     * to the model. A session MAY have several active clients at once.
-     *
-     * @param session The session URI this client contributes to.
-     * @param client The client's `clientId` and optional human-readable name.
-     */
-    getOrCreateActiveClient(session: URI, client: {
-        readonly clientId: string;
-        readonly displayName?: string;
-    }): IActiveClient;
-    /**
-     * Remove an active client from a session, clearing its tool and
-     * customization contributions. No-op when no active client matches
-     * `clientId`.
-     *
-     * @param session The session the client is leaving.
-     * @param clientId The client to remove.
-     */
-    removeActiveClient(session: URI, clientId: string): void;
-    /**
-     * Called when a client completes a client-provided tool call.
-     * Resolves the tool handler's deferred promise so the SDK can continue.
-     *
-     * @param session The session the tool call belongs to.
-     * @param chat The chat channel the tool call was issued on, when known.
-     * Agents that track peer chats separately from the default chat (e.g.
-     * copilot) use this to route the completion to the right chat;
-     * agents without peer chats ignore it and resolve by `session`.
-     * @param toolCallId The id of the tool call being completed.
-     * @param result The result of the tool call.
-     */
-    onClientToolCallComplete(session: URI, chat: URI, toolCallId: string, result: ToolCallResult): void;
-    /**
-     * Notifies the agent that a customization has been toggled on or off.
-     * The agent MAY restart its client before the next message is sent.
-     *
-     * @param id The opaque session-unique customization id.
-     */
-    setCustomizationEnabled(id: string, enabled: boolean): void;
-    /** Gracefully shut down all sessions. */
-    shutdown(): Promise<void>;
-    /**
-     * Routes a request received on an `mcp://` side channel to the agent's
-     * MCP server implementation. The channel carries raw MCP JSON-RPC
-     * methods (e.g. `tools/list`, `tools/call`, `resources/read`) tagged
-     * with the routing envelope; the protocol server decodes the envelope
-     * and forwards `(session, serverName, method, params)` here.
-     *
-     * The agent MUST reject unknown methods with an error whose message
-     * begins with `Method not found` so the protocol server can map it to
-     * a JSON-RPC `-32601`.
-     *
-     * Optional — agents that don't surface any MCP servers (or don't
-     * advertise `mcpApp` capabilities) can omit this.
-     */
-    handleMcpRequest?(session: URI, serverName: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
-    /**
-     * Fires when an MCP server owned by this agent emits a notification
-     * that should be forwarded to AHP clients over the `mcp://` side
-     * channel. Today this is exclusively
-     * `notifications/tools/list_changed` and
-     * `notifications/resources/list_changed`. The protocol server
-     * fans the notification out to every connected client.
-     *
-     * Optional — agents that don't expose MCP servers can omit this.
-     */
-    readonly onMcpNotification?: Event<IMcpNotification>;
-    /** Dispose this provider and all its resources. */
-    dispose(): void;
-}
-/**
- * Consumer-facing connection to an agent host. Session handlers, terminal
- * contributions, and other features program against this interface.
- *
- * Implementations wrap an {@link IAgentService} and layer subscription
- * management and optimistic write-ahead on top.
- */
-export interface IAgentConnection {
-    readonly clientId: string;
-    readonly rootState: IAgentSubscription<RootState>;
-    /**
-     * Acquire a refcounted subscription to `resource`. `owner` names the
-     * caller holding the reference so inspection surfaces can attribute who
-     * is retaining a subscription; use a stable identifier such as the
-     * acquiring class name.
-     */
-    getSubscription<T extends StateComponents>(kind: T, resource: URI, owner: string): IReference<IAgentSubscription<ComponentToState[T]>>;
-    getSubscriptionUnmanaged<T extends StateComponents>(kind: T, resource: URI): IAgentSubscription<ComponentToState[T]> | undefined;
-    /**
-     * Returns the in-flight `createSession` Promise for `resource`, or `undefined` if no create is pending. Callers
-     * that need to gate work on a racing eager `createSession` (e.g. before deciding whether to fall through to a
-     * duplicate create) should await this first.
-     */
-    getInflightSessionCreate(resource: URI): Promise<unknown> | undefined;
-    /**
-     * Read-only descriptors of every active resource subscription on this
-     * connection, for inspection/debug surfaces. Excludes the always-live
-     * {@link rootState}.
-     */
-    getActiveSubscriptions(): readonly IActiveSubscriptionInfo[];
-    /**
-     * Dispatch a client-originated action. `channel` is the protocol URI
-     * string identifying the channel the action targets (a session URI for
-     * session actions, terminal URI for terminal actions, or
-     * `ROOT_STATE_URI` for root-config actions). Strings are used rather
-     * than {@link URI} objects so authority-less scheme URIs like
-     * `ahp-root://` survive the wire format without normalization.
-     */
-    dispatch(channel: string, action: SessionAction | ChatAction | TerminalAction | ClientAnnotationsAction | IRootConfigChangedAction): void;
-    readonly onDidNotification: Event<INotification>;
-    readonly onDidAction: Event<ActionEnvelope>;
-    /**
-     * Fires when the host forwards an MCP server notification (e.g.
-     * `notifications/tools/list_changed`) over the `mcp://` side channel.
-     * The `channel` field on the notification routes the payload to the
-     * matching {@link McpServerCustomization}.
-     */
-    readonly onMcpNotification: Event<IMcpNotification>;
-    /**
-     * Send a request on an `mcp://` AHP side channel. `channel` is the
-     * `mcp://` URI advertised by the matching {@link McpServerCustomization}
-     * (only available while the server is `ready`). `method` is the raw MCP
-     * JSON-RPC method (e.g. `tools/call`, `resources/read`,
-     * `sampling/createMessage`); `params` are the JSON-RPC params (the
-     * connection adds the routing envelope's `channel` field automatically).
-     *
-     * Rejects with an `Error` whose message begins with `Method not found`
-     * when the channel is unknown or the host doesn't recognise the method.
-     */
-    handleMcpRequest(channel: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
-    authenticate(params: AuthenticateParams): Promise<AuthenticateResult>;
-    listSessions(): Promise<IAgentSessionMetadata[]>;
-    createSession(config?: IAgentCreateSessionConfig): Promise<URI>;
-    resolveSessionConfig(params: IAgentResolveSessionConfigParams): Promise<ResolveSessionConfigResult>;
-    sessionConfigCompletions(params: IAgentSessionConfigCompletionsParams): Promise<SessionConfigCompletionsResult>;
-    completions(params: CompletionsParams): Promise<CompletionsResult>;
-    /**
-     * Trigger characters announced by the connected agent host that should
-     * cause the client to issue a `completions` request when typed in a
-     * user-message input. Resolves once on first request and is cached.
-     */
-    getCompletionTriggerCharacters(): Promise<readonly string[]>;
-    disposeSession(session: URI): Promise<void>;
-    /**
-     * Create an additional peer chat inside an existing session. `chat` is a
-     * client-chosen chat URI (see {@link buildChatUri}). The host adds the
-     * chat to the session's catalog and publishes `session/chatAdded`.
-     */
-    createChat(session: URI, chat: URI, options?: IAgentCreateChatOptions): Promise<void>;
-    /** Dispose an additional chat created via {@link createChat}. */
-    disposeChat(chat: URI): Promise<void>;
-    createTerminal(params: CreateTerminalParams): Promise<void>;
-    disposeTerminal(terminal: URI): Promise<void>;
-    invokeChangesetOperation(params: InvokeChangesetOperationParams): Promise<InvokeChangesetOperationResult>;
-    resourceList(uri: URI): Promise<ResourceListResult>;
-    resourceRead(uri: URI): Promise<ResourceReadResult>;
-    resourceWrite(params: ResourceWriteParams): Promise<ResourceWriteResult>;
-    resourceCopy(params: ResourceCopyParams): Promise<ResourceCopyResult>;
-    resourceDelete(params: ResourceDeleteParams): Promise<ResourceDeleteResult>;
-    resourceMove(params: ResourceMoveParams): Promise<ResourceMoveResult>;
-    resourceResolve(params: ResourceResolveParams): Promise<ResourceResolveResult>;
-    resourceMkdir(params: ResourceMkdirParams): Promise<ResourceMkdirResult>;
-    createResourceWatch(params: CreateResourceWatchParams): Promise<CreateResourceWatchResult>;
-    /**
-     * Convenience method that bundles
-     * {@link createResourceWatch} + {@link subscribe} + a typed
-     * {@link IFileChange}[] event stream, so consumers (notably
-     * `AHPFileSystemProvider.watch`) can drive a watcher without
-     * understanding the underlying channel protocol. Disposing the
-     * returned handle unsubscribes.
-     */
-    watchResource(params: CreateResourceWatchParams): Promise<IRemoteWatchHandle>;
-}