@codingame/monaco-vscode-api 36.2.7 → 37.1.0

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

@@ -0,0 +1,1100 @@
+import { Event } from "../../../base/common/event.js";
+import { CancellationToken } from "../../../base/common/cancellation.js";
+import { DisposableStore, IDisposable } from "../../../base/common/lifecycle.js";
+import { IChannelClient } from "../../../base/parts/ipc/common/ipc.js";
+import type { IObservable } from "../../../base/common/observable.js";
+import { URI } from "../../../base/common/uri.js";
+import type { IAgentServerToolHost } from "./agentServerTools.js";
+import type { AgentHostClientType } from "@codingame/monaco-vscode-chat-service-override/vscode/vs/platform/agentHost/common/agentHostClientInfo";
+import type { IAgentHostClientTelemetryContext } from "./agentHostTelemetry.js";
+import type { ResolveSessionConfigResult, SessionConfigCompletionsResult } from "./state/protocol/commands.js";
+import { ProtectedResourceMetadata, type Changeset, type ChatOrigin, type ConfigSchema, type MessageAttachment, type ModelSelection, type AgentSelection, type SessionActiveClient, type ToolCallPendingConfirmationState, type ToolDefinition, ChangesSummary } from "./state/protocol/state.js";
+import type { AuthRequiredParams, SessionAction, ChatAction } from "@codingame/monaco-vscode-chat-service-override/vscode/vs/platform/agentHost/common/state/sessionActions";
+import { ChatInputResponseKind, SessionStatus, type AgentCapabilities, type ClientPluginCustomization, type Customization, type ISessionFolderPickerDecision, type Message, type PendingMessage, type ChatInputAnswer, type SessionMeta, type ToolCallResult, type Turn, type PolicyState } from "./state/sessionState.js";
+/** Error returned when the Agent Host process cannot be started. */
+export declare class AgentHostStartError extends Error {
+    readonly fatal: boolean;
+    constructor(message: string, fatal?: boolean);
+}
+/** Reports a provider CWD error after the new directory became irreversible and authoritative. */
+export declare class AgentWorkingDirectoryChangedError extends Error {
+    readonly workingDirectory: URI;
+    constructor(workingDirectory: URI, message: string);
+}
+export declare function isInvalidUtilityProcessConfigurationMessage(message: string): boolean;
+export declare function isFatalAgentHostStartError(error: unknown): error is TypeError;
+export declare function toFatalAgentHostStartError(error: Error): AgentHostStartError;
+export interface IAgentHostConnection {
+    readonly client: IChannelClient;
+    readonly store: DisposableStore;
+    readonly onDidProcessExit: Event<{
+        code: number;
+        signal: string;
+    }>;
+    /** Gracefully shuts down Agent Host providers before the process is disposed. */
+    shutdown(): Promise<void>;
+}
+/** Allows a connection request to join the shared process startup. */
+export interface IAgentHostStartRequest {
+    waitUntil(promise: Promise<void>): void;
+}
+/** Allows the Agent Host process to join application shutdown. */
+export interface IAgentHostShutdownRequest {
+    join(promise: Promise<void>): void;
+}
+export interface IAgentHostStarter extends IDisposable {
+    readonly onRequestConnection?: Event<IAgentHostStartRequest>;
+    readonly onRequestRestart?: Event<void>;
+    readonly onWillShutdown?: Event<IAgentHostShutdownRequest>;
+    start(): Promise<IAgentHostConnection>;
+}
+/** A network endpoint the agent host suggests probing, listed on {@link IAgentHostNetworkDiagnosticsInfo.endpoints}. */
+export interface IAgentHostNetworkEndpoint {
+    readonly name: string;
+    readonly url: string;
+    /** Substring the response body is expected to contain; when set, the probe reads the body and fails the check if it is absent. */
+    readonly expectedContent?: string;
+    /** HTTP status code the probe treats as success. Defaults to `200` when omitted. */
+    readonly expectedStatus?: number;
+}
+export interface IAgentHostManagedSettingsSnapshot {
+    readonly account?: string;
+    readonly source: "server" | "device" | "client" | "policyHelper" | "mixed" | "none";
+    readonly serverManaged: boolean;
+    readonly deviceManaged: boolean;
+    readonly clientManaged?: boolean;
+    readonly policyHelperManaged?: boolean;
+    readonly failClosed: boolean;
+    readonly bypassPermissionsDisabled: boolean;
+    readonly permissionsAllowIntersected?: boolean;
+    readonly sandboxEnabledByUndeterminedPolicy?: boolean;
+    readonly managedKeys: readonly string[];
+    readonly settings?: unknown;
+}
+export interface IAgentChatMetadata {
+    readonly chat: URI;
+    readonly startTime: number;
+    readonly modifiedTime: number;
+    readonly project?: IAgentSessionProjectInfo;
+    readonly summary?: string;
+    /** Provider model that should be selected when this chat is restored. */
+    readonly model?: ModelSelection;
+    /** Activity bits plus the session-scoped {@link SessionStatus.IsRead} / {@link SessionStatus.IsArchived} flags. */
+    readonly status?: SessionStatus;
+    /** Human-readable description of what the session is currently doing. */
+    readonly activity?: string;
+    /** All working directories available to the session (index 0 = primary). */
+    readonly workingDirectories?: readonly URI[];
+    /**
+     * Aggregate counts (additions / deletions / files) for this session's
+     * changes. Single-folder sessions derive this from the branch changeset;
+     * multi-folder sessions aggregate it across all folders. 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;
+}
+/** Identifies metadata reads that may initialize an otherwise lazy provider. */
+export interface IAgentChatMetadataOptions {
+    /** A session restore needs authoritative provider data and may start its runtime. */
+    readonly activation?: "restore";
+    /** Stable host-owned timestamps a lazy provider may use for passive catalogue metadata. */
+    readonly registryFallback?: Pick<IAgentChatMetadata, "startTime" | "modifiedTime">;
+}
+/** A provider chat ready to be registered as an Agent Host session. */
+export interface IAgentDiscoveredChat extends IAgentChatMetadata {
+    readonly external: boolean;
+}
+/** Returns the candidate session URI keys already present in the host registry. */
+export type IAgentKnownSessionsFilter = (sessions: readonly URI[]) => Promise<ReadonlySet<string>>;
+export interface IAgentSessionMetadata extends Omit<IAgentChatMetadata, "chat"> {
+    readonly session: URI;
+}
+export interface IAgentSessionProjectInfo {
+    readonly uri: URI;
+    readonly displayName: string;
+}
+export interface IAgentCreateSessionResult extends IAgentCreateChatResult {
+    readonly session: URI;
+    readonly project?: IAgentSessionProjectInfo;
+    /** Opaque provider backing for the session's initial chat, when it has one. */
+    readonly chat?: IAgentCreateChatResult;
+    /**
+     * The single working directory the provider resolved for this session — its
+     * process root. This may differ from the requested primary (e.g. a
+     * workspace-less session runs in a provider-assigned scratch dir). It is NOT
+     * the full multi-root set: a provider only resolves the one directory its
+     * subprocess launches in. The host assembles the session's set by replacing
+     * the requested primary (index 0) with this value while keeping the requested
+     * tail. Worktree remaps and the fully-resolved set land later, on the first
+     * send, via {@link IAgentMaterializeSessionEvent.workingDirectories}.
+     * `undefined` means the provider did not resolve a directory (the host keeps
+     * the requested set as-is).
+     */
+    readonly resolvedWorkingDirectory?: 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.onDidMaterializeChat}. 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.onDidMaterializeChat}. Fired when a previously
+ * {@link IAgentCreateSessionResult.provisional} chat has its SDK session,
+ * worktree (if any), and on-disk metadata in place. A provider may fire the
+ * event again when it replaces or rematerializes an already-backed chat;
+ * consumers must treat each event as the chat's latest materialization receipt.
+ */
+export interface IAgentMaterializeChatEvent {
+    readonly chat: URI;
+    /** Updated opaque backing for the session chat, when materialization minted it. */
+    readonly result?: IAgentCreateChatResult;
+    /**
+     * The complete resolved working-directory set (index 0 = the resolved process
+     * root, e.g. a worktree). The host replaces index 0 of the current session set
+     * with this set's index 0 while preserving the rest of the current set — the
+     * resume path can only report the single process cwd, so its tail is owned
+     * by the restored session state.
+     */
+    readonly workingDirectories: readonly URI[] | undefined;
+    readonly project: IAgentSessionProjectInfo | undefined;
+}
+export type AgentProvider = string;
+export type AgentTurnProviderCallState = "notStarted" | "pending" | "resolved" | "rejected";
+export type AgentTurnProviderSessionState = "active" | "disconnecting" | "disconnected" | "shutdown";
+/** Provider-observed records, not an assertion that every network call reported usage. */
+export interface IAgentTokenUsageSummary {
+    readonly model?: string;
+    readonly reasoningEffort?: string;
+    readonly usageScope: "direct-model" | "compaction";
+    readonly usageStatus: "known" | "partial" | "notReported";
+    readonly usageRecordCount: number;
+    readonly inputKnownRecordCount: number;
+    readonly outputKnownRecordCount: number;
+    readonly cacheKnownRecordCount: number;
+    readonly knownInputTokens?: number;
+    readonly knownOutputTokens?: number;
+    readonly knownCacheReadTokens?: number;
+}
+/** A point-in-time snapshot; missing counters and missing snapshots remain unknown. */
+export interface IAgentTurnTokenUsage {
+    readonly summaries: readonly IAgentTokenUsageSummary[];
+}
+export type IAgentTurnDiagnosticSnapshot = {
+    readonly state: "available";
+    readonly providerCallState: AgentTurnProviderCallState;
+    readonly providerTurnStarted: boolean;
+    readonly providerSessionState: AgentTurnProviderSessionState;
+} | {
+    readonly state: "missingChat" | "missingTurn";
+};
+/** Well-known agent provider id for the Claude agent-host backend. */
+export declare const CLAUDE_AGENT_PROVIDER_ID: "claude";
+/** Well-known agent provider id for the Codex agent-host backend. */
+export declare const CODEX_AGENT_PROVIDER_ID: "codex";
+/**
+ * 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;
+/** Agent Host-only capabilities that are not serialized to protocol clients. */
+export interface IAgentHostCapabilities {
+    readonly workspaceConversion: boolean;
+}
+/** 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;
+    /** The access token's remaining lifetime in seconds, when known. */
+    readonly expiresIn?: number;
+}
+/** 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;
+/**
+ * Pure decision: does this set of advertised protected resources require the
+ * user to be signed in to GitHub Copilot right now?
+ *
+ * Returns `true` iff the agent advertises the canonical GitHub Copilot
+ * protected resource ({@link GITHUB_COPILOT_PROTECTED_RESOURCE}) with
+ * `required !== false`. Provider-agnostic by design: an agent that drops the
+ * resource entirely (e.g. Claude in native mode) or advertises it with
+ * `required: false` (e.g. Codex on OpenAI) does not require a GitHub sign-in.
+ *
+ * An absent `required` field is treated the same as `true` (see
+ * {@link ProtectedResourceMetadata.required}).
+ */
+export declare function protectedResourcesRequireGitHubCopilotSignIn(resources: readonly ProtectedResourceMetadata[]): boolean;
+export interface IAgentCreateSessionConfig {
+    readonly provider?: AgentProvider;
+    readonly model?: ModelSelection;
+    readonly _meta?: Record<string, unknown>;
+    /**
+     * 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;
+    /**
+     * The working directories the session's agent is granted tool access to,
+     * ordered so that index 0 is the intended process root (the "primary").
+     *
+     * Distinct values:
+     * - `undefined` — no directories requested (workspace-less inference applies);
+     * - `[]` — explicitly no directories;
+     * - `[dir, …]` — the ordered set (index 0 = primary/process root).
+     *
+     * A client MUST NOT supply more than one entry unless the agent advertises
+     * the `multipleWorkingDirectories` capability (not advertised yet). During
+     * the compatibility phase callers supply exactly one directory (`[dir]`).
+     */
+    readonly workingDirectories?: readonly 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;
+    /**
+     * Import an existing (e.g. local) conversation into a brand-new session as
+     * real, editable turns. The provider translates {@link turns} into a
+     * Copilot event log seeded on disk and resumes the session so the turns are
+     * reconstituted as genuine backend events (editable / forkable / truncatable).
+     *
+     * The service layer assigns fresh UUID turn ids before handing the turns to
+     * the provider so the seeded event ids and the seeded protocol turns stay
+     * aligned. Mutually exclusive with {@link fork}.
+     */
+    readonly importConversation?: {
+        readonly turns: readonly Turn[];
+        readonly model?: ModelSelection;
+    };
+    /**
+     * 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;
+}
+/**
+ * Host-owned transient context for an addressed chat operation.
+ *
+ * `resource` is the provider-owned persistence scope for this exact chat.
+ * `configurationResource` is the opaque scope for configuration and other
+ * resources shared by the host across related chats. Providers must not derive
+ * either value from `chat` themselves.
+ *
+ * Agent Host populates {@link origin} and {@link customizations} on every
+ * context it hands to a provider (create, materialize, send, and every other
+ * addressed chat operation).
+ */
+export interface IAgentChatContext {
+    readonly resource: URI;
+    readonly configurationResource: URI;
+    readonly clientTelemetryContext?: IAgentHostClientTelemetryContext;
+    /**
+     * The addressed chat's origin, taken verbatim from the host-owned chat
+     * catalog, and exhaustive across every way a chat comes into existence:
+     * a plainly user-created peer chat and the session-backed default chat
+     * carry {@link ChatOriginKind.User}; a fork carries
+     * {@link ChatOriginKind.Fork} with the exact source chat and turn; a side
+     * chat carries {@link ChatOriginKind.SideChat}; and a subagent chat always
+     * carries its {@link ChatOriginKind.Tool} spawn edge, so providers never
+     * have to recover it from state or URI shape. Absent only when the host has
+     * no catalog entry for the chat yet — the narrow window during restore
+     * before the chat is registered, where the caller supplies the origin it is
+     * restoring with.
+     */
+    readonly origin?: ChatOrigin;
+    /**
+     * The owning session's last host-published customization snapshot — the
+     * same list clients observe on `SessionState.customizations`, including
+     * user enablement toggles. Supplied at the create, materialize, send, and
+     * update boundaries so providers never read them back out of shared host
+     * state, and reconciled against the provider's own view rather than
+     * replacing it. Absent when the host has not published a snapshot for the
+     * session yet, which is deliberately distinct from an empty list.
+     */
+    readonly customizations?: readonly Customization[];
+    /** Per-operation host instructions that providers add to model context without persisting as user content. */
+    readonly hostInstructions?: readonly string[];
+    /** Whether the current turn is an automated Agent Merge repair turn. */
+    readonly agentMergeTurn?: boolean;
+}
+export type AgentChatOperationContext = URI | IAgentChatContext;
+/**
+ * Normalize a legacy session-only chat context into the explicit
+ * {@link IAgentChatContext} shape by attaching the host-supplied `resource`.
+ */
+export declare function resolveAgentChatContext(configurationResourceOrContext: AgentChatOperationContext, resource: URI): IAgentChatContext;
+/**
+ * Reads the host-supplied {@link IAgentChatContext.origin} for an addressed
+ * chat operation. See {@link IAgentChatContext.origin} for absence semantics.
+ */
+export declare function resolveAgentChatOrigin(context?: URI | IAgentChatContext): ChatOrigin | undefined;
+/**
+ * Reads the tool-call spawn edge of a subagent chat from its host-supplied
+ * origin. Returns `undefined` when the chat was not spawned by a tool call.
+ * Providers use this to route inner tool completions and transcript filtering
+ * to the spawning chat without consulting shared host state.
+ */
+export declare function resolveSubagentChatParent(context?: URI | IAgentChatContext): IAgentSpawnedChatParent | undefined;
+/**
+ * Reads the last host-published customization snapshot carried by an
+ * addressed chat operation's context. See {@link IAgentChatContext.customizations}
+ * for absence semantics.
+ */
+export declare function resolveAgentHostCustomizations(context?: URI | IAgentChatContext): readonly Customization[] | undefined;
+export declare function resolveAgentHostInstructions(context?: URI | IAgentChatContext): readonly string[] | undefined;
+/** Fully resolved options for creating one chat. */
+export interface IAgentCreateChatOptions {
+    /** Whether the owning session is transient and should skip durable-only provider work. */
+    readonly isEphemeral?: boolean;
+    /**
+     * Whether the owning chat surface is scoped to editing a single file (editor
+     * inline chat). Blanket shell auto-approvals must not apply to such a
+     * session, because a shell command can write anywhere the sandbox allows and
+     * carries no destination the permission layer can check against the scope.
+     */
+    readonly hasScopedEditSurface?: boolean;
+    /** Optional display title for the new chat. */
+    readonly title?: string;
+    /** Optional model override; defaults to the session's model. */
+    readonly model?: ModelSelection;
+    /** Optional custom agent selection. */
+    readonly agent?: AgentSelection;
+    /** Complete ordered working-directory set resolved by Agent Host. */
+    readonly workingDirectories?: readonly URI[];
+    /** Project metadata resolved by Agent Host. */
+    readonly project?: IAgentSessionProjectInfo;
+    /** Provider-specific configuration resolved by Agent Host. */
+    readonly config?: Record<string, unknown>;
+    /** Active client to seed before the first turn. */
+    readonly activeClient?: SessionActiveClient;
+    /** Defer creating the provider SDK backing until the chat's first send. */
+    readonly deferBacking?: boolean;
+    /** Existing conversation turns to import into this chat. */
+    readonly importConversation?: IAgentCreateSessionConfig["importConversation"];
+    /**
+     * 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;
+}
+/**
+ * Host-facing chat creation options. Providers receive the resolved
+ * {@link IAgentCreateChatOptions} and never receive side-chat provenance.
+ */
+export interface IAgentCreateChatRequestOptions extends IAgentCreateChatOptions {
+    /**
+     * Create this new chat as a side chat branching from a turn in an existing
+     * chat (via `/btw`). The host resolves this into {@link fork} before calling
+     * the provider, while retaining the side-chat provenance itself.
+     */
+    readonly sideChat?: IAgentCreateChatSideChatSource;
+}
+/** Identifies the exact source chat and turn to fork from. */
+export interface IAgentCreateChatForkSource {
+    readonly source: URI;
+    /** Turn ID in the source chat; content up to and including this turn is copied. */
+    readonly turnId: string;
+    /**
+     * Allows a fork to start without waiting for the source chat's queue.
+     * Side chats branch from potentially active source turns and use this to
+     * avoid blocking their own creation behind that turn.
+     */
+    readonly independentQueue?: boolean;
+    /** Zero-based source turn index, when the provider needs it for import/fork mapping. */
+    readonly turnIndex?: number;
+    /**
+     * 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>;
+}
+/** Immutable selected-text snapshot captured when a side chat is created. */
+export interface IAgentCreateChatSideChatSelection {
+    readonly text: string;
+    /** Optional provenance for the response part that contained {@link text}. */
+    readonly responsePartId?: string;
+}
+/** Identifies a source chat and turn a side chat (`/btw`) branches from. */
+export interface IAgentCreateChatSideChatSource {
+    readonly source: URI;
+    /** Turn ID in the source chat the side chat records as its provenance. */
+    readonly turnId: string;
+    /** Optional selected-text snapshot captured from the source chat transcript. */
+    readonly selection?: IAgentCreateChatSideChatSelection;
+}
+/** Result of {@link IAgentChats.createChat}: the opaque blob to persist for restore. */
+export interface IAgentCreateChatResult {
+    readonly project?: IAgentSessionProjectInfo;
+    readonly resolvedWorkingDirectory?: URI;
+    readonly provisional?: boolean;
+    /** Id of the last provider turn copied into a newly created fork, when known. */
+    readonly inheritedTurnId?: string;
+    /**
+     * 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 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 {
+    readonly chat: URI;
+    /** The new opaque blob to persist (replaces any previously stored value). */
+    readonly providerData: string;
+}
+/** A legacy concrete chat backing enumerated by {@link IAgent.listLegacyChatBackings} for migration. */
+export interface IAgentLegacyChat {
+    /** The concrete chat's channel URI (see {@link buildChatUri}). */
+    readonly uri: URI;
+    /** The opaque, agent-owned backing blob, encoded as {@link materializeChat} expects. */
+    readonly providerData?: string;
+}
+/** The native chat catalog requires an external readiness action before it can be enumerated. */
+export declare const AgentChatMigrationDeferred: unique symbol;
+/** Provider-native chat catalog result used by registry migration. */
+export type AgentChatMigrationResult = readonly IAgentChatMetadata[] | undefined | typeof AgentChatMigrationDeferred;
+/**
+ * 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 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;
+    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;
+    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_started` signals to the unified chat catalog's spawn
+ * 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
+ * orchestrator ({@link IAgentService}) owns the `(session, chat)` mapping and
+ * calls these operations with a concrete chat URI plus transient context when
+ * the provider needs the owning session or storage scope.
+ */
+export interface IAgentChats {
+    /**
+     * Create a fresh additional chat within an already-provisioned `session`,
+     * using the complete working directory and config supplied in
+     * {@link IAgentCreateChatOptions}. `chat` is the client-chosen channel URI.
+     * The orchestrator supplies provider-owned persistence and configuration
+     * scopes via `context`, so the agent never has to recover either by parsing
+     * `chat`.
+     */
+    createChat(chat: URI, context: AgentChatOperationContext, options?: IAgentCreateChatOptions): Promise<IAgentCreateChatResult | void>;
+    /** Dispose the addressed chat and free its backing. */
+    disposeChat(chat: URI, context: AgentChatOperationContext): Promise<void>;
+    /** Return whether the addressed chat can currently release its in-memory backing. */
+    canReleaseChat?(chat: URI, context: AgentChatOperationContext): Promise<boolean>;
+    /** Release the addressed chat's in-memory backing without deleting durable data. */
+    releaseChat(chat: URI, context: AgentChatOperationContext): Promise<void>;
+    /**
+     * Send a user message into `chat`. On every send, the host passes the complete
+     * resolved, ordered working-directory snapshot (index 0 = the process root /
+     * resolved worktree, followed by any additional roots), or `undefined` for
+     * workspace-less sessions. Providers must make that snapshot effective before
+     * the prompt enters their runtime. `context` is transient operation context;
+     * providers must not retain it as chat membership state.
+     */
+    sendMessage(chat: URI, prompt: string, workingDirectoriesOrDirectory: readonly URI[] | URI | undefined, attachments?: readonly MessageAttachment[], turnId?: string, senderClientId?: string, clientTypeOrContext?: AgentHostClientType | URI | IAgentChatContext, context?: URI | IAgentChatContext): Promise<void>;
+    /** Resume a failed turn without adding another user message. */
+    resumeTurn?(chat: URI, turnId: string, context: AgentChatOperationContext, senderClientId?: string, clientType?: AgentHostClientType): Promise<void>;
+    /** Abort the in-flight turn for `chat`. */
+    abort(chat: URI, context: AgentChatOperationContext): Promise<void>;
+    /** Return the model currently bound to `chat`, when the provider knows it. */
+    getModel?(chat: URI, context: AgentChatOperationContext): ModelSelection | undefined;
+    changeModel(chat: URI, model: ModelSelection, context: AgentChatOperationContext): 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, context: AgentChatOperationContext): Promise<void>;
+    /** Reconstruct the turns for `chat` (used on restore). */
+    getMessages(chat: URI, context: AgentChatOperationContext): Promise<readonly Turn[]>;
+}
+export interface IAgentResolveChatConfigParams {
+    readonly provider?: AgentProvider;
+    readonly workingDirectory?: URI;
+    readonly config?: Record<string, unknown>;
+}
+export interface IAgentChatConfigCompletionsParams extends IAgentResolveChatConfigParams {
+    readonly property: string;
+    readonly query?: string;
+}
+export type IAgentResolveSessionConfigParams = IAgentResolveChatConfigParams;
+export type IAgentSessionConfigCompletionsParams = IAgentChatConfigCompletionsParams;
+/** 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 acknowledgment, and
+ * host-owned model-call telemetry) remain as discriminated non-action signals.
+ */
+export type AgentSignal = IAgentActionSignal | IAgentModelCallCompletedSignal | IAgentModelCallFinishedSignal | IAgentToolPendingConfirmationSignal | IAgentSubagentStartedSignal | IAgentSubagentResumedSignal | 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;
+}
+/** Reports one completed upstream model response for host-owned turn telemetry. */
+export interface IAgentModelCallCompletedSignal {
+    readonly kind: "model_call_completed";
+    /** Target chat channel URI. For inner subagent calls this is the parent chat channel. */
+    readonly resource: URI;
+    /** Provider-reported turn identifier. The host remaps it when routing to a subagent chat. */
+    readonly turnId: string;
+    /** Stable provider message or response identifier used to suppress duplicate notifications. */
+    readonly modelCallId: string;
+    /** If set, route the model call to the subagent session belonging to this tool call. */
+    readonly parentToolCallId?: string;
+}
+export type AgentModelCallFinishedOutcome = "success" | "error" | "cancelled" | "rejected";
+/** Reports the final lifecycle outcome of one dispatched model-call attempt. */
+export interface IAgentModelCallFinishedSignal {
+    readonly kind: "model_call_finished";
+    /** Target chat channel URI. For inner subagent calls this is the parent chat channel. */
+    readonly resource: URI;
+    /** Host turn identifier owning this model-call attempt. */
+    readonly turnId: string;
+    /** Stable SDK event identifier used to suppress duplicate notifications. */
+    readonly modelCallId: string;
+    /** Monotonic provider-dispatch duration in milliseconds. */
+    readonly dispatchDurationMs: number;
+    readonly outcome: AgentModelCallFinishedOutcome;
+    /** Present only for accepted successful responses. */
+    readonly containsBuiltInFileEditRequest?: boolean;
+    readonly editClassifierVersion: number;
+    /** If set, route the model call 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" | "skill" | "custom-tool" | "hook" | "memory" | "factory" | "extension-management" | "extension-permission-access" | "extension-env-access";
+    /** Host-only auto-approval path target (not part of the dispatched action). */
+    readonly permissionPath?: string;
+    /**
+     * Host-only flag requiring the client to show a confirmation instead of applying host auto-approval.
+     * The runtime currently sets it for managed Shell, Read, Edit, and Domain selector asks.
+     */
+    readonly managedApprovalRequired?: boolean;
+    /**
+     * 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;
+    /**
+     * Host-only shell language for terminal auto-approval.
+     * Only `bash` and `powershell` are eligible for terminal-rule analysis;
+     * missing requires explicit confirmation.
+     */
+    readonly shellLanguage?: "bash" | "powershell";
+    /**
+     * 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;
+}
+export type AgentSubagentTaskModelSource = "task_argument" | "subagent_configuration" | "custom_agent_definition" | "unset";
+/**
+ * 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;
+    readonly taskModelSource?: AgentSubagentTaskModelSource;
+    /**
+     * 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;
+    /**
+     * The full delegated instruction the parent handed the subagent (the
+     * spawning tool's `prompt` input). Populated by each provider at emit
+     * time from its own native source, so the shared orchestrator never
+     * parses a provider-specific tool-input shape. Seeds the subagent peer
+     * chat's opening request. Distinct from {@link taskDescription} (a short
+     * tab-title label). Absent when the harness does not surface a prompt.
+     */
+    readonly taskPrompt?: 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 previously completed subagent started another turn after being steered.
+ */
+export interface IAgentSubagentResumedSignal {
+    readonly kind: "subagent_resumed";
+    readonly chat: URI;
+    readonly toolCallId: string;
+    readonly message?: Message;
+}
+/**
+ * A subagent turn has finished — either successfully or with an error. The
+ * child chat and its routing remain live because the same subagent can be
+ * steered into another turn.
+ */
+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 per-chat handle for one active client's contributions (tools and
+ * plugin customizations), 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
+ * exact chat, 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[];
+}
+/** Worktree identity a predecessor recorded for a chat, so a missing checkout can be recreated on resume. */
+export interface IAgentAdoptedWorktree {
+    readonly branchName: string;
+    readonly baseBranch: string | undefined;
+    readonly worktreePath: URI;
+    readonly repositoryRoot: URI;
+}
+/**
+ * Why an adoption attempt ended the way it did. Reported in logs and telemetry so
+ * a session that did not migrate can be diagnosed without reproducing it.
+ */
+export type AgentChatAdoptionReason = 
+/** Already has Agent Host metadata — native or previously adopted. */
+"alreadyNative"
+/** Not a legacy extension-host Copilot CLI chat (e.g. standalone CLI, Local agent). */
+ | "notLegacyChat"
+/** A legacy chat whose recorded working directory no longer exists and could not be resolved. */
+ | "workingDirectoryMissing"
+/** A legacy chat whose extension-host marker could not be re-read, leaving its archived state unknown. */
+ | "markerUnavailable"
+/** Newly adopted. */
+ | "adopted";
+/** Outcome of attempting to adopt a legacy provider-native chat. */
+export interface IAgentChatAdoptionResult {
+    /** Whether this call newly seeded Agent Host metadata. */
+    readonly adopted: boolean;
+    /** Whether the chat was a genuine legacy adoption candidate. */
+    readonly eligible: boolean;
+    /** Whether the chat already has Agent Host metadata, i.e. it is ours regardless of adoption. */
+    readonly native?: boolean;
+    /** Set when the adopted chat ran in a worktree that no longer exists and can be recreated. */
+    readonly worktree?: IAgentAdoptedWorktree;
+    /** Diagnostic reason behind {@link adopted}. */
+    readonly reason?: AgentChatAdoptionReason;
+}
+/**
+ * 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 provider identifier. */
+    readonly id: AgentProvider;
+    /** Capabilities consumed only inside the Agent Host process. */
+    readonly agentHostCapabilities: IAgentHostCapabilities;
+    /** Provider descriptor and capabilities. */
+    getDescriptor(): IAgentDescriptor;
+    /** Available provider models. */
+    readonly models: IObservable<readonly IAgentModelInfo[]>;
+    /** Optional refresh for providers whose model catalog can change at runtime. */
+    refreshModels?(): Promise<void>;
+    /** Streamed progress for an exact chat. */
+    readonly onDidChatProgress: Event<AgentSignal>;
+    /** Fires when a provisional chat acquires its SDK backing and durable metadata. */
+    readonly onDidMaterializeChat: Event<IAgentMaterializeChatEvent>;
+    /** Fires when an opaque chat backing changes and must be persisted again. */
+    readonly onDidChangeChatData: Event<IAgentChatDataChange>;
+    /** Fires when the provider creates a chat, such as a delegated subagent. */
+    readonly onDidSpawnChat: Event<IAgentSpawnChatEvent>;
+    /** Exact-chat operations: create, send, abort, mutate, restore history, release, and dispose. */
+    readonly chats: IAgentChats;
+    /** Re-attach an exact chat from opaque provider data without inferring its role. */
+    materializeChat(chat: URI, context: URI | IAgentChatContext, providerData: string | undefined): Promise<IAgentCreateChatResult | void>;
+    /** Optional steering hook for providers that can accept messages during an active turn. */
+    setPendingMessages?(chat: URI, steeringMessage: PendingMessage | undefined, queuedMessages: readonly PendingMessage[]): void;
+    /** Optional history mutation for providers with a native truncation operation. */
+    truncateChat?(chat: URI, turnId: string | undefined, context?: URI | IAgentChatContext): Promise<void>;
+    /**
+     * Changes the working directory of an exact chat's existing provider-native
+     * backing. Callers MUST gate this operation on
+     * {@link IAgentHostCapabilities.workspaceConversion}; implementations that do
+     * not advertise the capability MUST reject the call.
+     */
+    setWorkingDirectory(chat: URI, context: URI | IAgentChatContext, workingDirectory: URI): Promise<void>;
+    /** Return bounded diagnostics for an in-flight turn when supported. */
+    getTurnDiagnosticSnapshot?(chat: URI, turnId: string): IAgentTurnDiagnosticSnapshot | undefined;
+    /** Read observed usage at terminal dispatch for this exact owning turn, excluding descendants and later delivery. */
+    getTurnTokenUsage?(chat: URI, turnId: string, parentToolCallId?: string): IAgentTurnTokenUsage | undefined;
+    /** Record the host-remapped turn for a completed provider model call. */
+    recordModelCallTurnCorrelation?(chat: URI, modelCallId: string, turnId: string): void;
+    /** Get or create one client's contribution handle for an exact chat. */
+    getOrCreateActiveClient(chat: URI, context: URI | IAgentChatContext, client: {
+        readonly clientId: string;
+        readonly displayName?: string;
+    }, hostCustomizations?: readonly Customization[]): IActiveClient;
+    /** Remove one client's contributions from an exact chat. */
+    removeActiveClient(chat: URI, context: URI | IAgentChatContext, clientId: string): void;
+    /** Complete a client tool call on its host-resolved provider chat. */
+    onClientToolCallComplete(chat: URI, toolCallId: string, result: ToolCallResult, context?: IAgentChatContext): 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;
+    /** Resolve provider-owned chat configuration; host-owned worktree fields are omitted. */
+    resolveChatConfig(params: IAgentResolveChatConfigParams): Promise<ResolveSessionConfigResult>;
+    /** Select provider-owned configuration inherited by a newly created chat. */
+    getInheritedChatConfig(config: Readonly<Record<string, unknown>>): Record<string, unknown> | undefined;
+    /** Select provider-owned configuration for an unattended autonomous turn. */
+    getAutonomousSessionConfig?(config: Readonly<Record<string, unknown>>): Record<string, unknown> | undefined;
+    /** Return dynamic completions for a provider-owned chat configuration property. */
+    chatConfigCompletions(params: IAgentChatConfigCompletionsParams): Promise<SessionConfigCompletionsResult>;
+    /** Optional push signal; providers with pull-only customization discovery omit it. */
+    readonly onDidCustomizationsChange?: Event<void>;
+    /** Optional provider-wide catalog; providers with only per-chat discovery omit it. */
+    getCustomizations?(): readonly Customization[];
+    /** Return the effective customization projection for an exact chat. */
+    getChatCustomizations(chat: URI, context: URI | IAgentChatContext, hostCustomizations?: readonly Customization[]): Promise<readonly Customization[]>;
+    /** Returns host-internal plugin owners for MCP servers temporarily published top-level. */
+    getMcpServerOwners?(session: URI): ReadonlyMap<string, string> | undefined;
+    /**
+     * Optional provider-owned decision about the multi-root new-session Folder
+     * picker, computed from the ordered working-directory set (index 0 = the
+     * current primary) and seeded into the session's `_meta` at creation for the
+     * client. Returns `undefined` when the provider has no opinion: nothing is
+     * seeded and the client keeps the picker hidden by default, so a provider
+     * that wants it shown must say so with `{ hidden: false }`. The optional
+     * {@link token} aborts the (possibly filesystem-bound) computation.
+     */
+    computeFolderPickerDecision?(workingDirectories: readonly URI[], token?: CancellationToken): Promise<ISessionFolderPickerDecision | undefined>;
+    /** Provides chats that are ready to be registered as Agent Host sessions. */
+    readonly onDidDiscoverChats: Event<readonly IAgentDiscoveredChat[]>;
+    /** Starts the provider's memoized native chat discovery pass. */
+    startChatDiscovery?(): Promise<void>;
+    /** Lets discovery drop registered candidates before per-session I/O. */
+    setKnownSessionsFilter?(filter: IAgentKnownSessionsFilter): void;
+    /** Optional adoption hook for providers with a predecessor-owned on-disk format. */
+    ensureChatAdopted?(chat: URI, context: URI | IAgentChatContext): Promise<IAgentChatAdoptionResult>;
+    /** Optional recovery hook for providers with historical backings but no persisted provider data. */
+    recoverLegacyChat?(chat: URI, context: URI | IAgentChatContext): Promise<IAgentCreateChatResult | void>;
+    /** Enumerate provider-native chats for registry migration. */
+    listChatsToMigrate(): Promise<AgentChatMigrationResult>;
+    /** Optional migration codec for providers that persisted peer backings before the host catalog. */
+    listLegacyChatBackings?(configurationResource: URI): Promise<readonly IAgentLegacyChat[]>;
+    /**
+     * Warms a short-lived, in-memory cache of per-session metadata from a single
+     * bulk provider call, so a subsequent burst of {@link getChatMetadata} calls
+     * (e.g. a `listSessions` pass over a large catalogue) can be served without
+     * one provider round-trip per session. Returns a disposable that clears the
+     * cache; callers dispose it once the burst is complete. Optional: providers
+     * without a cheap bulk read simply omit it and pay per session.
+     */
+    prewarmSessionMetadata?(): Promise<IDisposable>;
+    /** Retrieve metadata for an exact registered chat. Ambient catalogue reads never set {@link IAgentChatMetadataOptions.activation}. */
+    getChatMetadata(chat: URI, context: URI | IAgentChatContext, providerData?: string, options?: IAgentChatMetadataOptions): Promise<IAgentChatMetadata | undefined>;
+    getProtectedResources(): ProtectedResourceMetadata[];
+    /** An empty token revokes the credential previously forwarded for this resource. */
+    authenticate(resource: string, token: string, expiresIn?: number): Promise<boolean>;
+    /** Optional token consumer for provider-owned resources such as MCP servers. */
+    handleAuthenticationToken?(params: AuthenticateParams): Promise<boolean>;
+    /** Optional current authentication requirement for providers that can require re-authentication after startup. */
+    readonly authenticationRequired?: IObservable<Omit<AuthRequiredParams, "channel"> | undefined>;
+    /** Optional endpoint list when the provider owns probeable network traffic. */
+    getNetworkDiagnosticsEndpoints?(): Promise<readonly IAgentHostNetworkEndpoint[]>;
+    /** Optional account label when the provider can resolve one. */
+    getNetworkDiagnosticsAccount?(): Promise<string | undefined>;
+    /** Optional managed-settings snapshot for providers with an enterprise policy surface. */
+    getManagedSettingsDiagnostics?(): Promise<IAgentHostManagedSettingsSnapshot>;
+    /** Return the provider-owned state file for a session, when one exists. */
+    getSessionStateFile?(session: URI, chat?: URI): Promise<URI | undefined>;
+    /** Add provider-owned diagnostics to an Agent Host debug-log staging directory. */
+    collectDebugLogs?(session: URI | undefined, outputDirectory: URI, chat?: URI): Promise<boolean>;
+    /** Optional host wiring for providers that advertise Agent Host server tools. */
+    setServerToolHost?(host: IAgentServerToolHost): void;
+    /** Optional lifecycle operation for providers exposing controllable MCP servers. */
+    startMcpServer?(session: URI, id: string): Promise<void>;
+    /** Optional lifecycle operation paired with {@link startMcpServer}. */
+    stopMcpServer?(session: URI, id: string): Promise<void>;
+    /** Optional `mcp://` router for providers that advertise chat-scoped MCP side-channel resources. */
+    handleMcpRequest?(chat: URI, serverName: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
+    /** Optional notification stream paired with {@link handleMcpRequest}. */
+    readonly onMcpNotification?: Event<IMcpNotification>;
+    /** Optional lifecycle hook for providers whose resources react to archived state. */
+    onArchivedChanged?(session: URI, isArchived: boolean): Promise<void>;
+    shutdown(): Promise<void>;
+    dispose(): void;
+}