src/vs/platform/agentHost/common/agentService.ts
2261 LOC · 2239 covered · 22 uncovered · 84 ranges · 4006 concepts · 35 introducers · 1934 tests
File neighbourhood
The centred file is linked to every concept that introduces one of its ranges, every test that runs code from the file, and the gray connector concepts standing between those tests and the file's own introducer concepts. Undirected links join concepts to every file where they introduce source and concepts to the tests they introduce; arrows show specialization between the displayed concepts and bridge only concepts omitted from this view. Concept colors match the source ranges below; connector concepts have no source color and are shown in gray.
Focused file, its introducer and connector concepts, their introduced files, and tests that run code from the file
In the embedded map, ordinary wheel input scrolls the page; use the visible controls to zoom and drag to pan. Open the full-screen map for canvas navigation: wheel pans, Ctrl/Command plus wheel zooms, and arrow keys pan when this region is focused. On touch screens, open the full-screen map to pan or pinch. If JavaScript or WebGL is unavailable, use the related-file, concept, and source links on this page.
Graph controls are ready.
Interactive rendering requires JavaScript and WebGL. Use the related-file, concept, and source links on this page while the interactive map is unavailable.
1
>
/*---------------------------------------------------------------------------------------------
agentService.ts ×15
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import type { CancellationToken } from '../../../base/common/cancellation.js';
7
>
import { Event } from '../../../base/common/event.js';
8
>
import { IReference } from '../../../base/common/lifecycle.js';
9
>
import { truncate } from '../../../base/common/strings.js';
10
>
import { IAuthorizationProtectedResourceMetadata } from '../../../base/common/oauth.js';
11
>
import type { IObservable } from '../../../base/common/observable.js';
12
>
import { URI } from '../../../base/common/uri.js';
13
>
import type { IConfigurationChangeEvent, IConfigurationService } from '../../configuration/common/configuration.js';
14
>
import { createDecorator } from '../../instantiation/common/instantiation.js';
15
>
import type { IAgentServerToolHost } from './agentServerTools.js';
16
>
import type { IActiveSubscriptionInfo, IAgentSubscription } from './state/agentSubscription.js';
17
>
import type { IRemoteWatchHandle } from './agentHostFileSystemProvider.js';
18
>
import type { CompletionsParams, CompletionsResult, CreateTerminalParams, ResolveSessionConfigResult, SessionConfigCompletionsResult } from './state/protocol/commands.js';
19
>
import type { InitializeResult } from './state/protocol/common/commands.js';
20
>
import type { InvokeChangesetOperationParams, InvokeChangesetOperationResult } from './state/protocol/channels-changeset/commands.js';
21
>
import { ProtectedResourceMetadata, type Changeset, type ConfigSchema, type MessageAttachment, type ModelSelection, type AgentSelection, type SessionActiveClient, type ToolCallPendingConfirmationState, type ToolDefinition, ChangesSummary } from './state/protocol/state.js';
22
>
import type { ActionEnvelope, AuthRequiredParams, INotification, IRootConfigChangedAction, SessionAction, ChatAction, TerminalAction, ClientAnnotationsAction, ClientChangesetAction } from './state/sessionActions.js';
23
>
import type { ResourceCopyParams, ResourceCopyResult, ResourceDeleteParams, ResourceDeleteResult, ResourceListResult, ResourceMkdirParams, ResourceMkdirResult, ResourceMoveParams, ResourceMoveResult, ResourceReadResult, ResourceResolveParams, ResourceResolveResult, ResourceWatchState, ResourceWriteParams, ResourceWriteResult, CreateResourceWatchParams, CreateResourceWatchResult, IStateSnapshot } from './state/sessionProtocol.js';
24
>
import { ComponentToState, ChatInputResponseKind, SessionStatus, StateComponents, buildSubagentChatUri, parseRequiredSessionUriFromChatUri, type AgentCapabilities, type ClientPluginCustomization, type Customization, type PendingMessage, type RootState, type ChatInputAnswer, type SessionMeta, type ToolCallResult, type Turn, type PolicyState } from './state/sessionState.js';
25
>
26
>
// IPC contract between the renderer and the agent host utility process.
27
>
// Defines all serializable event types, the IAgent provider interface,
28
>
// and the IAgentService / IAgentHostService service decorators.
29
>
30
>
export const enum AgentHostIpcChannels {
31
>
/** Channel for the agent host service on the main-process side */
32
>
AgentHost = 'agentHost',
33
>
/** Channel for log forwarding from the agent host process */
34
>
Logger = 'agentHostLogger',
35
>
/** Channel for WebSocket client connection count (server process management only) */
36
>
ConnectionTracker = 'agentHostConnectionTracker',
37
>
/** Channel carrying raw Agent Host Protocol frames over a MessagePort. */
38
>
Protocol = 'agentHostProtocol',
39
>
/** Narrow local management channel that remains outside of the AHP data plane. */
40
>
Management = 'agentHostManagement',
41
>
/**
42
>
* Channel registered by the remote server that proxies AHP JSON-RPC
43
>
* frames between a renderer and the agent host running on the server.
44
>
* Pairs with `AgentHostIpcChannelTransport` on the renderer side.
45
>
*/
46
>
RemoteProxy = 'agentHostProxy',
47
>
}
48
>
49
>
/** Configuration key that controls whether AHP JSONL logs are written for agent host transports. */
50
>
export const AgentHostAhpJsonlLoggingSettingId = 'chat.agentHost.ahpJsonlLoggingEnabled';
51
>
52
>
/** Configuration key controlling automatic OS system proxy discovery for agent-host Copilot sessions. */
53
>
export const AgentHostSystemProxyEnabledSettingId = 'chat.agentHost.systemProxy.enabled';
54
>
55
>
// The Copilot-CLI-specific setting IDs (`customTerminalTool`, `opus48Prompt`,
56
>
// `reasoningEffortOverride`, `modelCapabilityOverrides`) live with their
57
>
// root-config keys in `copilotCliConfig.ts`.
58
>
59
>
/**
60
>
* Configuration key controlling whether the Claude provider is registered in
61
>
* the agent host process. When `false`, the agent host skips registering the
62
>
* Claude provider regardless of SDK availability. Defaults to `true`.
63
>
*
64
>
* Independent of {@link ClaudePreferAgentHostAgentsSettingId} /
65
>
* {@link ClaudePreferAgentHostEditorSettingId}, which control whether the
66
>
* workbench surfaces the agent host's Claude provider (vs. the GitHub Copilot
67
>
* Chat extension's). This setting is strictly about whether the agent host
68
>
* advertises Claude at all. The agent host process must be restarted for
69
>
* changes to take effect.
70
>
*/
71
>
export const AgentHostClaudeAgentEnabledSettingId = 'chat.agentHost.claudeAgent.enabled';
72
>
73
>
/**
74
>
* Configuration key controlling whether the Codex provider is registered in
75
>
* the agent host process. When `false` (the default), the agent host skips
76
>
* registering the Codex provider regardless of SDK availability. The agent
77
>
* host process must be restarted for changes to take effect.
78
>
*/
79
>
export const AgentHostCodexAgentEnabledSettingId = 'chat.agentHost.codexAgent.enabled';
80
>
81
>
/**
82
>
* Configuration key controlling whether the agent host *wires up* the BYOK
83
>
* ("bring your own key") language-model bridge: the renderer LM handler, the
84
>
* reverse-RPC channel, and the per-connection link to the node-side OpenAI
85
>
* proxy + bridge registry. When `true` (the default), the renderer's BYOK
86
>
* server channel and the per-connection bridge are wired so extension-provided
87
>
* BYOK models are reachable from agent-host sessions. When `false`, the proxy
88
>
* and registry are still constructed but stay inert — the BYOK server channel
89
>
* and the per-connection bridge are not wired, so the registry stays empty and
90
>
* extension-provided BYOK models are never reachable from agent-host sessions.
91
>
* The agent host process must be restarted for changes to take effect.
92
>
*/
93
>
export const AgentHostByokModelsEnabledSettingId = 'chat.agentHost.byokModels.enabled';
94
>
95
>
/**
96
>
* Optional override that points at an **SDK root directory** containing a
97
>
* `node_modules/@anthropic-ai/claude-agent-sdk` subtree. When set, the agent
98
>
* host loads the Claude SDK from that path instead of the bare import (which
99
>
* resolves via this repo's `node_modules` in dev) or the on-demand download
100
>
* from `product.agentSdks.claude` (built products). Mainly exists for the
101
>
* remote server's `--claude-sdk-root` CLI flag and for one-off developer
102
>
* overrides pointing at an out-of-tree SDK build.
103
>
*/
104
>
export const AgentHostClaudeSdkRootEnvVar = 'VSCODE_AGENT_HOST_CLAUDE_SDK_ROOT';
105
>
106
>
/**
107
>
* Environment variable form of {@link AgentHostClaudeAgentEnabledSettingId}.
108
>
* Set by the agent host starters from the setting. Accepts `'true'` /
109
>
* `'false'`; absent means "default" (`true` for Claude, `false` for Codex).
110
>
*/
111
>
export const AgentHostClaudeAgentEnabledEnvVar = 'VSCODE_AGENT_HOST_CLAUDE_AGENT_ENABLED';
112
>
113
>
/**
114
>
* Environment variable form of {@link AgentHostCodexAgentEnabledSettingId}.
115
>
* Set by the agent host starters from the setting. Accepts `'true'` /
116
>
* `'false'`; absent means "default" (`false`).
117
>
*/
118
>
export const AgentHostCodexAgentEnabledEnvVar = 'VSCODE_AGENT_HOST_CODEX_AGENT_ENABLED';
119
>
120
>
/**
121
>
* Environment variable form of {@link AgentHostByokModelsEnabledSettingId}.
122
>
* Set by the agent host starters from the setting. Accepts `'true'` /
123
>
* `'false'`; absent means "default" (`true`).
124
>
*/
125
>
export const AgentHostByokModelsEnabledEnvVar = 'VSCODE_AGENT_HOST_BYOK_MODELS_ENABLED';
126
>
127
>
/**
128
>
* Overrides the grace period (in milliseconds) before an idle, fully
129
>
* unsubscribed session is released from memory. Defaults to 30_000. Primarily a
130
>
* test hook so real-SDK integration tests can force a prompt release without
131
>
* waiting the full production grace; production does not set it.
132
>
*/
133
>
export const AgentHostSessionReleaseGraceMsEnvVar = 'VSCODE_AGENT_HOST_SESSION_RELEASE_GRACE_MS';
134
>
135
>
/**
136
>
* Resolves the effective enable state for a Claude/Codex provider from the
137
>
* env-var value forwarded by the starter. Recognized values (case- and
138
>
* whitespace-insensitive):
139
>
*
140
>
* - `'true'` / `'1'` → enabled
141
>
* - `'false'` / `'0'` → disabled
142
>
* - `undefined`, empty string, or any other value → falls through to
143
>
* {@link defaultEnabled}
144
>
*/
145
>
export function isAgentEnabled(envValue: string | undefined, defaultEnabled: boolean): boolean {
148
>
}
152
>
}
155
>
}
157
>
}
159
>
/**
160
>
* Configuration key that controls the sandbox mode for the Copilot SDK's built-in
161
>
* shell tool (the path taken when `AgentHostCustomTerminalToolEnabledSettingId`
162
>
* is `false`). Values mirror {@link AgentSandboxEnabledValue}:
163
>
*
164
>
* - `'off'` (the default): no sandbox policy is forwarded for the SDK shell
165
>
* path \u2014 commands run unsandboxed.
166
>
* - `'on'`: the Agent Host runs the SDK\u2019s shell tool inside a sandbox
167
>
* using the user's `chat.agent.sandbox.fileSystem.*` filesystem policy.
168
>
* Outbound network is enforced via the user's allow/deny host lists.
169
>
* - `'allowNetwork'`: same as `'on'` but with unrestricted outbound network.
170
>
*
171
>
* Has no effect when `AgentHostCustomTerminalToolEnabledSettingId` is
172
>
* `true` \u2014 the host\u2019s own terminal sandbox engine then handles shell
173
>
* commands and reads `chat.agent.sandbox.enabled` directly.
174
>
*/
175
>
export const AgentHostSdkSandboxEnabledSettingId = 'chat.agentHost.sdkSandbox.enabled';
176
>
177
>
/**
178
>
* Selects which Claude integration fulfills Claude sessions opened from the
179
>
* **Agents Window**:
180
>
* - `true` — Claude is provided by the agent host process.
181
>
* - `false` (default) — Claude is provided by the GitHub Copilot Chat extension.
182
>
*
183
>
* The agent host always registers Claude when its SDK is reachable; this
184
>
* setting only controls whether the per-window bridge in
185
>
* `AgentHostContribution` actually surfaces the AH provider in the Agents
186
>
* Window. The extension's `chatSessions` contribution mirrors the rule
187
>
* declaratively (its `when` clause hides the EH provider when this is `true`),
188
>
* so flipping the setting takes effect live without a window reload.
189
>
*
190
>
* Paired with {@link ClaudePreferAgentHostEditorSettingId} which governs the
191
>
* regular workbench (sidebar). EXP-backed (`experiment: { mode: 'startup' }`).
192
>
*/
193
>
export const ClaudePreferAgentHostAgentsSettingId = 'chat.agents.claude.preferAgentHost';
194
>
195
>
/**
196
>
* Sibling of {@link ClaudePreferAgentHostAgentsSettingId} that selects the
197
>
* Claude implementation for the **regular workbench** (sidebar chat in a
198
>
* non-Agents-Window window). Same shape, same semantics — just a different
199
>
* surface scope.
200
>
*/
201
>
export const ClaudePreferAgentHostEditorSettingId = 'chat.editor.claude.preferAgentHost';
202
>
203
>
/**
204
>
* Selects whether the regular workbench surfaces Codex from the agent host
205
>
* instead of the OpenAI extension.
206
>
*/
207
>
export const CodexPreferAgentHostEditorSettingId = 'chat.editor.codex.preferAgentHost';
208
>
209
>
export function claudePreferAgentHostSettingId(isSessionsWindow: boolean): string {
211
>
? ClaudePreferAgentHostAgentsSettingId
212
>
: ClaudePreferAgentHostEditorSettingId;
213
>
}
215
>
export function affectsAgentHostProviderPreference(event: IConfigurationChangeEvent, isSessionsWindow: boolean): boolean {
216
return event.affectsConfiguration(claudePreferAgentHostSettingId(isSessionsWindow))
217
|| event.affectsConfiguration(isSessionsWindow ? AgentHostCodexAgentEnabledSettingId : CodexPreferAgentHostEditorSettingId);
218
}
220
>
export function shouldSurfaceLocalAgentHostProvider(provider: AgentProvider, configurationService: IConfigurationService, isSessionsWindow: boolean): boolean {
222
>
case CLAUDE_AGENT_PROVIDER_ID:
223
>
return configurationService.getValue<boolean>(claudePreferAgentHostSettingId(isSessionsWindow)) === true;
agentService.ts ×3
225
>
return configurationService.getValue<boolean>(isSessionsWindow ? AgentHostCodexAgentEnabledSettingId : CodexPreferAgentHostEditorSettingId) === true;
226
>
default:
229
>
}
231
>
// -- Codex agent settings --------------------------------------------------------
232
>
//
233
>
// Codex is opt-in via `chat.agentHost.codexAgent.sdkRoot`. The setting points
234
>
// at an absolute path to a directory containing a `node_modules/@openai/codex`
235
>
// subtree (the same shape `npm install @openai/codex` produces, and the same
236
>
// shape the agent host downloads on demand from `product.agentSdks.codex`).
237
>
// The agent host spawns the native codex binary from inside that tree as a
238
>
// long-lived child process and speaks JSON-RPC over stdio. The binary is not
239
>
// bundled with VS Code; users either install codex themselves (typically via
240
>
// `npm install -g @openai/codex` or a platform package manager) or rely on
241
>
// the on-demand download.
242
>
243
>
/**
244
>
* Absolute path to the **SDK root directory** containing a
245
>
* `node_modules/@openai/codex` subtree. When non-empty, the agent host treats
246
>
* it as a dev override and skips the on-demand download from
247
>
* `product.agentSdks.codex`. Empty (the default) falls through to product
248
>
* config; if neither is present, the provider is not registered.
249
>
*/
250
>
export const AgentHostCodexAgentSdkRootSettingId = 'chat.agentHost.codexAgent.sdkRoot';
251
>
252
>
/**
253
>
* Optional override for `$CODEX_HOME`. When set, the codex app-server child
254
>
* process inherits this value, controlling where rollouts and config live.
255
>
*/
256
>
export const AgentHostCodexAgentCodexHomeSettingId = 'chat.agentHost.codexAgent.codexHome';
257
>
258
>
/**
259
>
* Additional command-line arguments passed to `codex app-server`. Mainly for
260
>
* debugging (e.g. `--log-level=debug`).
261
>
*/
262
>
export const AgentHostCodexAgentBinaryArgsSettingId = 'chat.agentHost.codexAgent.binaryArgs';
263
>
264
>
/**
265
>
* Environment variable form of {@link AgentHostCodexAgentSdkRootSettingId}.
266
>
* Forwarded by the starters from the setting.
267
>
*/
268
>
export const AgentHostCodexAgentSdkRootEnvVar = 'VSCODE_AGENT_HOST_CODEX_SDK_ROOT';
269
>
270
>
/** Forwarded `$CODEX_HOME`. */
271
>
export const AgentHostCodexAgentCodexHomeEnvVar = 'CODEX_HOME';
272
>
273
>
/** Forwarded extra args for `codex app-server` (JSON-encoded string[]). */
274
>
export const AgentHostCodexAgentBinaryArgsEnvVar = 'VSCODE_AGENT_HOST_CODEX_APP_SERVER_ARGS';
275
>
276
>
// -- OpenTelemetry settings ------------------------------------------------------
277
>
//
278
>
// The `chat.agentHost.otel.*` namespace surfaces the same exporter knobs the CLI
279
>
// runtime documents in `extensions/copilot/docs/monitoring/agent_monitoring.md`,
280
>
// but routes them through the agent host process so the user's settings stay in
281
>
// VS Code instead of leaking via shell env.
282
>
//
283
>
// `chat.agentHost.otel.dbSpanExporter.enabled` switches on the in-process
284
>
// loopback receiver + persistent SQLite span store; the other settings still
285
>
// apply because the user's external sink (when configured) is then fed by an
286
>
// outbound forwarder rather than by the SDK directly.
287
>
288
>
/** Master toggle for agent-host OTel. Explicit opt-in; other settings imply this when set. */
289
>
export const AgentHostOTelEnabledSettingId = 'chat.agentHost.otel.enabled';
290
>
/** Exporter type for the SDK's OTel pipeline. One of: `otlp-http`, `otlp-grpc`, `console`, `file`. */
291
>
export const AgentHostOTelExporterTypeSettingId = 'chat.agentHost.otel.exporterType';
292
>
/**
293
>
* OTLP wire protocol (`http/json`, `http/protobuf`, `grpc`). Policy-only delivery slot (no user UI):
294
>
* carries the enterprise-managed `telemetry.protocol` so it can be threaded into the agent host's
295
>
* `OTEL_EXPORTER_OTLP_PROTOCOL` env, which the runtime needs to distinguish protobuf from json
296
>
* (the `exporterType` setting only models transport, not the HTTP wire encoding).
297
>
*/
298
>
export const AgentHostOTelOtlpProtocolSettingId = 'chat.agentHost.otel.otlpProtocol';
299
>
/** OTLP endpoint URL when `exporterType` is `otlp-http` or `otlp-grpc`. */
300
>
export const AgentHostOTelOtlpEndpointSettingId = 'chat.agentHost.otel.otlpEndpoint';
301
>
/** Whether to include prompt/response content in span attributes (privacy-sensitive). */
302
>
export const AgentHostOTelCaptureContentSettingId = 'chat.agentHost.otel.captureContent';
303
>
/** Output path when `exporterType` is `file`. */
304
>
export const AgentHostOTelOutfileSettingId = 'chat.agentHost.otel.outfile';
305
>
/** Policy-only delivery slot for the enterprise-managed OTel `service.name` (no user UI). */
306
>
export const AgentHostOTelServiceNameSettingId = 'chat.agentHost.otel.serviceName';
307
>
/** Policy-only delivery slot for enterprise-managed OTel resource attributes (no user UI). */
308
>
export const AgentHostOTelResourceAttributesSettingId = 'chat.agentHost.otel.resourceAttributes';
309
>
/** When true, ALL spans are persisted to a local SQLite store regardless of `exporterType`. */
310
>
export const AgentHostOTelDbSpanExporterEnabledSettingId = 'chat.agentHost.otel.dbSpanExporter.enabled';
311
>
312
>
/**
313
>
* Path of the local SQLite span database, relative to `INativeEnvironmentService.userDataPath`.
314
>
* Kept here so both the renderer-side export action and the agent-host-side service
315
>
* use the same on-disk location.
316
>
*/
317
>
export const AgentHostOTelSpansDbSubPath = 'agent-host/otel/agent-host-traces.db';
318
>
319
>
/**
320
>
* Environment variables consumed by `AgentHostOTelService` inside the agent host
321
>
* process. The workbench-side agent-host starters translate the corresponding
322
>
* `chat.agentHost.otel.*` settings into these variables (settings → env), while
323
>
* any value already present on the parent process's env wins (developer override).
324
>
*
325
>
* These names match the conventions documented in
326
>
* `extensions/copilot/docs/monitoring/agent_monitoring.md` so the same external
327
>
* tooling and `OTEL_EXPORTER_OTLP_*` config recipes work unchanged.
328
>
*/
329
>
export const AgentHostOTelEnvVars = Object.freeze({
330
>
Enabled: 'COPILOT_OTEL_ENABLED',
331
>
ExporterType: 'COPILOT_OTEL_EXPORTER_TYPE',
332
>
OtlpEndpoint: 'OTEL_EXPORTER_OTLP_ENDPOINT',
333
>
OtlpEndpointAlt: 'COPILOT_OTEL_ENDPOINT',
334
>
OtlpProtocol: 'OTEL_EXPORTER_OTLP_PROTOCOL',
335
>
OtlpTracesProtocol: 'OTEL_EXPORTER_OTLP_TRACES_PROTOCOL',
336
>
OtlpMetricsProtocol: 'OTEL_EXPORTER_OTLP_METRICS_PROTOCOL',
337
>
OtlpHeaders: 'OTEL_EXPORTER_OTLP_HEADERS',
338
>
CaptureContent: 'OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT',
339
>
FilePath: 'COPILOT_OTEL_FILE_EXPORTER_PATH',
340
>
SourceName: 'COPILOT_OTEL_SOURCE_NAME',
341
>
ServiceName: 'OTEL_SERVICE_NAME',
342
>
ResourceAttributes: 'OTEL_RESOURCE_ATTRIBUTES',
343
>
DbSpanExporterEnabled: 'COPILOT_OTEL_DB_SPAN_EXPORTER_ENABLED',
344
>
} as const);
345
>
346
>
/**
347
>
* Snapshot of the `chat.agentHost.otel.*` settings; produced by the workbench-side
348
>
* starters and merged with the parent process's env (env wins on key collision).
349
>
*/
350
>
export interface IAgentHostOTelSettings {
351
>
readonly enabled?: boolean;
352
>
readonly exporterType?: string;
353
>
readonly otlpProtocol?: string;
354
>
readonly otlpEndpoint?: string;
355
>
readonly captureContent?: boolean;
356
>
readonly outfile?: string;
357
>
readonly serviceName?: string;
358
>
readonly resourceAttributes?: Record<string, string>;
359
>
readonly dbSpanExporterEnabled?: boolean;
360
>
}
361
>
362
>
/**
363
>
* IPC channel (renderer -> main) the desktop agent-host path uses to hand the
364
>
* enterprise-resolved `chat.agentHost.otel.*` policy to `ElectronAgentHostStarter`.
365
>
*
366
>
* The main-process configuration service does NOT include the renderer-only
367
>
* `AccountPolicyService` (managed settings: server / native-MDM / file channels), so a
368
>
* starter running in the main process sees `policyValue === undefined` for these keys.
369
>
* The renderer — whose policy layer does include managed settings — forwards the resolved
370
>
* values here just before requesting the agent-host connection, so the host is spawned with
371
>
* the managed OTel env. See {@link readAgentHostOTelPolicySettings}.
372
>
*/
373
>
export const AgentHostOTelPolicyIpcChannel = 'vscode:agentHostOTelPolicy';
374
>
375
>
/**
376
>
* Resolve the enterprise-policy values for the `chat.agentHost.otel.*` settings from a
377
>
* configuration service whose policy layer includes managed settings (i.e. the renderer's).
378
>
* Each field is `undefined` when no policy is set. Intended as the `policySettings` argument
379
>
* of {@link buildAgentHostOTelEnv}.
380
>
*/
381
>
export function readAgentHostOTelPolicySettings(configurationService: IConfigurationService): IAgentHostOTelSettings {
382
>
const policyValue = <T>(key: string): T | undefined => configurationService.inspect<T>(key).policyValue;
agentService.ts ×1
383
>
return {
384
>
enabled: policyValue<boolean>(AgentHostOTelEnabledSettingId),
385
>
exporterType: policyValue<string>(AgentHostOTelExporterTypeSettingId),
386
>
otlpProtocol: policyValue<string>(AgentHostOTelOtlpProtocolSettingId),
387
>
otlpEndpoint: policyValue<string>(AgentHostOTelOtlpEndpointSettingId),
388
>
captureContent: policyValue<boolean>(AgentHostOTelCaptureContentSettingId),
389
>
outfile: policyValue<string>(AgentHostOTelOutfileSettingId),
390
>
serviceName: policyValue<string>(AgentHostOTelServiceNameSettingId),
391
>
resourceAttributes: policyValue<Record<string, string>>(AgentHostOTelResourceAttributesSettingId),
392
>
};
393
>
}
395
>
/**
396
>
* Validate/normalize an {@link IAgentHostOTelSettings} received over IPC, keeping only
397
>
* well-typed fields. Defends the main process against a malformed payload before the values
398
>
* are turned into agent-host process env vars.
399
>
*/
400
>
export function sanitizeAgentHostOTelPolicySettings(raw: unknown): IAgentHostOTelSettings {
403
>
}
405
>
const asString = (value: unknown): string | undefined => typeof value === 'string' ? value : undefined;
406
>
const asBoolean = (value: unknown): boolean | undefined => typeof value === 'boolean' ? value : undefined;
407
>
const asStringRecord = (value: unknown): Record<string, string> | undefined => {
408
>
if (!value || typeof value !== 'object' || Array.isArray(value)) {
410
>
}
412
>
for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
413
>
if (k === '__proto__' || k === 'constructor' || k === 'prototype') {
415
>
}
417
>
out[k] = v;
418
>
}
419
>
}
420
>
return out;
422
>
return {
423
>
enabled: asBoolean(record.enabled),
424
>
exporterType: asString(record.exporterType),
425
>
otlpProtocol: asString(record.otlpProtocol),
426
>
otlpEndpoint: asString(record.otlpEndpoint),
427
>
captureContent: asBoolean(record.captureContent),
428
>
outfile: asString(record.outfile),
429
>
serviceName: asString(record.serviceName),
430
>
resourceAttributes: asStringRecord(record.resourceAttributes),
431
>
};
432
>
}
434
>
/**
435
>
* Serialize an OTel resource-attribute map into the `OTEL_RESOURCE_ATTRIBUTES` env-var format
436
>
* (`key1=value1,key2=value2`, W3C Baggage style). Returns `undefined` for an empty/absent map so
437
>
* callers can skip emitting the env var. Empty keys and non-string values are dropped.
438
>
*/
439
>
function serializeResourceAttributes(attributes: Record<string, string> | undefined): string | undefined {
agentService.ts ×16
440
>
if (!attributes) {
441
>
return undefined;
442
>
}
444
>
.filter(([key, value]) => key !== '' && typeof value === 'string')
445
>
.map(([key, value]) => `${key}=${value}`);
447
>
}
449
>
/**
450
>
* Build the env-var overlay for the agent host process from user settings and
451
>
* inherited env. Settings are translated to env vars, but if the same env var is
452
>
* already present on `inheritedEnv` it wins (developer override).
453
>
*
454
>
* Only sets a key when the underlying setting was explicitly configured — empty
455
>
* string / undefined settings are dropped so they don't shadow inherited env.
456
>
*/
457
>
export function buildAgentHostOTelEnv(
459
>
inheritedEnv: Readonly<Record<string, string | undefined>>,
460
>
policySettings: IAgentHostOTelSettings = {},
461
>
): Record<string, string> {
462
>
const out: Record<string, string> = {};
463
>
const setIfMissing = (key: string, value: string | undefined): void => {
464
>
if (value === undefined || value === '' || inheritedEnv[key] !== undefined) {
465
>
return;
466
>
}
469
>
// Enterprise policy wins over inherited env (managed settings cannot be overridden by a
470
>
// user-set env var), unlike user settings which yield to env via `setIfMissing`.
471
>
const setPolicy = (key: string, value: string | undefined): void => {
473
>
out[key] = value;
474
>
}
475
>
};
478
>
}
480
>
setIfMissing(AgentHostOTelEnvVars.OtlpEndpoint, settings.otlpEndpoint);
481
>
setIfMissing(AgentHostOTelEnvVars.ServiceName, settings.serviceName);
482
>
setIfMissing(AgentHostOTelEnvVars.ResourceAttributes, serializeResourceAttributes(settings.resourceAttributes));
483
>
setIfMissing(AgentHostOTelEnvVars.FilePath, settings.outfile);
484
>
if (settings.captureContent !== undefined) {
485
setIfMissing(AgentHostOTelEnvVars.CaptureContent, settings.captureContent ? 'true' : 'false');
486
}
488
setIfMissing(AgentHostOTelEnvVars.DbSpanExporterEnabled, 'true');
489
}
491
>
if (policySettings.enabled !== undefined) {
492
>
setPolicy(AgentHostOTelEnvVars.Enabled, policySettings.enabled ? 'true' : 'false');
agentService.ts ×2
493
>
if (!policySettings.enabled) {
495
>
setPolicy(AgentHostOTelEnvVars.OtlpEndpointAlt, '');
496
>
setPolicy(AgentHostOTelEnvVars.FilePath, '');
497
>
}
500
setPolicy(AgentHostOTelEnvVars.ExporterType, policySettings.exporterType);
501
setPolicy(AgentHostOTelEnvVars.FilePath, '');
502
}
503
>
if (policySettings.otlpProtocol !== undefined && policySettings.otlpProtocol !== '') {
agentService.ts ×16
504
>
// Mirror the CLI: thread the managed protocol into the generic AND per-signal protocol
agentService.ts ×1
505
>
// env vars so it wins over any user-provided OTEL_EXPORTER_OTLP_{,TRACES_,METRICS_}PROTOCOL.
506
>
setPolicy(AgentHostOTelEnvVars.OtlpProtocol, policySettings.otlpProtocol);
507
>
setPolicy(AgentHostOTelEnvVars.OtlpTracesProtocol, policySettings.otlpProtocol);
508
>
setPolicy(AgentHostOTelEnvVars.OtlpMetricsProtocol, policySettings.otlpProtocol);
509
>
}
512
>
setPolicy(AgentHostOTelEnvVars.FilePath, '');
513
>
}
515
setPolicy(AgentHostOTelEnvVars.FilePath, policySettings.outfile);
516
}
518
setPolicy(AgentHostOTelEnvVars.CaptureContent, policySettings.captureContent ? 'true' : 'false');
519
}
520
>
if (policySettings.serviceName !== undefined && policySettings.serviceName !== '') {
agentService.ts ×16
522
>
}
523
>
const policyResourceAttributes = serializeResourceAttributes(policySettings.resourceAttributes);
agentService.ts ×16
524
>
if (policyResourceAttributes !== undefined) {
525
>
setPolicy(AgentHostOTelEnvVars.ResourceAttributes, policyResourceAttributes);
agentService.ts ×1
526
>
}
528
>
}
530
>
/**
531
>
* Settings -> env-var fan-out for the Claude/Codex SDK overrides that the
532
>
* agent host process consumes. Shared by both starters
533
>
* (`nodeAgentHostStarter.ts`, `electronAgentHostStarter.ts`) so they don't
534
>
* drift the next time someone adds a setting.
535
>
*
536
>
* The shape mirrors {@link buildAgentHostOTelEnv}: only set a key when the
537
>
* underlying setting has a non-empty value AND the inherited env doesn't
538
>
* already define it (developer override wins). Returns a partial env map
539
>
* the caller spreads into the spawned child's environment.
540
>
*/
541
>
export interface IAgentSdkStarterSettings {
542
>
readonly codexSdkRoot?: string;
543
>
readonly codexHome?: string;
544
>
readonly codexBinaryArgs?: readonly string[];
545
>
readonly claudeAgentEnabled?: boolean;
546
>
readonly codexAgentEnabled?: boolean;
547
>
readonly byokModelsEnabled?: boolean;
548
>
}
549
>
550
>
export function buildAgentSdkEnv(
552
>
inheritedEnv: Readonly<Record<string, string | undefined>>,
553
>
): Record<string, string> {
554
>
const out: Record<string, string> = {};
555
>
const setIfMissing = (key: string, value: string | undefined): void => {
556
>
if (value === undefined || value === '' || inheritedEnv[key] !== undefined) {
557
>
return;
558
>
}
561
>
setIfMissing(AgentHostCodexAgentSdkRootEnvVar, settings.codexSdkRoot);
562
>
setIfMissing(AgentHostCodexAgentCodexHomeEnvVar, settings.codexHome);
563
>
if (Array.isArray(settings.codexBinaryArgs) && settings.codexBinaryArgs.length > 0) {
564
setIfMissing(AgentHostCodexAgentBinaryArgsEnvVar, JSON.stringify(settings.codexBinaryArgs));
565
}
567
setIfMissing(AgentHostClaudeAgentEnabledEnvVar, settings.claudeAgentEnabled ? 'true' : 'false');
568
}
570
setIfMissing(AgentHostCodexAgentEnabledEnvVar, settings.codexAgentEnabled ? 'true' : 'false');
571
}
573
>
setIfMissing(AgentHostByokModelsEnabledEnvVar, settings.byokModelsEnabled ? 'true' : 'false');
agentService.ts ×1
574
>
}
576
>
}
578
>
/** Result of starting the agent host WebSocket server on-demand. */
579
>
export interface IAgentHostSocketInfo {
580
>
readonly socketPath: string;
581
>
}
582
>
583
>
/** Inspector listener information for the agent host process. */
584
>
export interface IAgentHostInspectInfo {
585
>
readonly host: string;
586
>
readonly port: number;
587
>
/** A `devtools://` URL that can be opened with `INativeHostService.openDevToolsWindow`. */
588
>
readonly devtoolsUrl: string;
589
>
}
590
>
591
>
/** A network endpoint the agent host suggests probing, listed on {@link IAgentHostNetworkDiagnosticsInfo.endpoints}. */
592
>
export interface IAgentHostNetworkEndpoint {
593
>
/** Human-readable name of the endpoint (e.g. "GitHub API"). */
594
>
readonly name: string;
595
>
/** The URL to probe. */
596
>
readonly url: string;
597
>
/** Substring the response body is expected to contain; when set, the probe reads the body and fails the check if it is absent. */
598
>
readonly expectedContent?: string;
599
>
/** HTTP status code the probe treats as success. Defaults to `200` when omitted. */
600
>
readonly expectedStatus?: number;
601
>
}
602
>
603
>
/** Host-level network context for diagnostics, produced by {@link IAgentConnection.getNetworkDiagnosticsInfo}. */
604
>
export interface IAgentHostNetworkDiagnosticsInfo {
605
>
/** Agent host product version. */
606
>
readonly version: string;
607
>
/** Operating system platform of the agent host process (`process.platform`). */
608
>
readonly os: string;
609
>
/** CPU architecture of the agent host process (`process.arch`). */
610
>
readonly arch: string;
611
>
/** Authenticated GitHub account login, when known. */
612
>
readonly account?: string;
613
>
/** VS Code `http.*` proxy settings observed by the agent host, keyed by setting id (only those that are set). */
614
>
readonly proxySettings: Readonly<Record<string, string>>;
615
>
/** Proxy-related environment variables observed by the agent host process, keyed by name (only those that are set). */
616
>
readonly proxyEnv: Readonly<Record<string, string>>;
617
>
/** Endpoints the agent host suggests probing via {@link IAgentConnection.diagnosticsFetch}. */
618
>
readonly endpoints: readonly IAgentHostNetworkEndpoint[];
619
>
}
620
>
621
>
export interface IAgentHostManagedSettingsSnapshot {
622
>
readonly account?: string;
623
>
readonly source: 'server' | 'device' | 'none';
624
>
readonly serverManaged: boolean;
625
>
readonly deviceManaged: boolean;
626
>
readonly failClosed: boolean;
627
>
readonly bypassPermissionsDisabled: boolean;
628
>
readonly permissionsAllowIntersected?: boolean;
629
>
readonly managedKeys: readonly string[];
630
>
readonly settings?: Readonly<Record<string, unknown>>;
631
>
}
632
>
633
>
export interface IAgentHostManagedSettingsDiagnostics {
634
>
readonly provider: AgentProvider;
635
>
readonly snapshot?: IAgentHostManagedSettingsSnapshot;
636
>
readonly error?: string;
637
>
}
638
>
639
>
/** Result of a DNS lookup for a single address family, part of {@link IAgentHostNetworkFetchResult}. */
640
>
export interface IAgentHostDnsResult {
641
>
/** The resolved address, when the lookup succeeded. */
642
>
readonly address?: string;
643
>
/** Time taken by the lookup, in milliseconds. */
644
>
readonly durationMs?: number;
645
>
/** Lookup error message, when it failed. */
646
>
readonly error?: string;
647
>
}
648
>
649
>
/** Result of a single connectivity probe, produced by {@link IAgentConnection.diagnosticsFetch}. */
650
>
export interface IAgentHostNetworkFetchResult {
651
>
/** The URL that was probed. */
652
>
readonly url: string;
653
>
/** The resolved proxy URL for this endpoint, or `undefined` for a direct connection. */
654
>
readonly proxyUrl?: string;
655
>
/** IPv4 DNS lookup result for the host. */
656
>
readonly dnsIpv4?: IAgentHostDnsResult;
657
>
/** IPv6 DNS lookup result for the host. */
658
>
readonly dnsIpv6?: IAgentHostDnsResult;
659
>
/** HTTP status code from the probe, when a response arrived. */
660
>
readonly statusCode?: number;
661
>
/** HTTP status message from the probe, when a response arrived. */
662
>
readonly statusMessage?: string;
663
>
/** Response body text (possibly truncated), when a response arrived. Callers use it to check expected content. */
664
>
readonly body?: string;
665
>
/** Time taken by the reachability probe, in milliseconds. */
666
>
readonly durationMs?: number;
667
>
/** Probe error message, when the connection failed. */
668
>
readonly error?: string;
669
>
}
670
>
671
>
/**
672
>
* IPC service exposed on the {@link AgentHostIpcChannels.ConnectionTracker}
673
>
* channel. Used by the server process for lifetime management and by the
674
>
* shared process to request a local WebSocket listener on-demand.
675
>
*/
676
>
export interface IConnectionTrackerService {
677
>
readonly onDidChangeConnectionCount: Event<number>;
678
>
679
>
/**
680
>
* Request the agent host to start a WebSocket server on a local
681
>
* pipe/socket. Returns the socket path.
682
>
* If a server is already running, returns the existing info.
683
>
*/
684
>
startWebSocketServer(): Promise<IAgentHostSocketInfo>;
685
>
686
>
/**
687
>
* Get inspector listener info for the agent host process. If the inspector
688
>
* is not currently active and `tryEnable` is true, opens the inspector on
689
>
* a random local port. Returns `undefined` if the inspector cannot be
690
>
* enabled (e.g. running in an environment without `node:inspector`).
691
>
*/
692
>
getInspectInfo(tryEnable: boolean): Promise<IAgentHostInspectInfo | undefined>;
693
>
}
694
>
695
>
/**
696
>
* Narrow renderer-to-local-agent-host control surface. All stateful agent
697
>
* operations travel over {@link AgentHostIpcChannels.Protocol}.
698
>
*/
699
>
export interface IAgentHostManagementService {
700
>
readonly _serviceBrand: undefined;
701
>
702
>
/**
703
>
* Local-only compatibility path for session fields not yet represented by
704
>
* AHP `createSession` (`model`, `agent`, and `importConversation`).
705
>
*/
706
>
createSessionWithExtensions(config: IAgentCreateSessionConfig): Promise<URI>;
707
>
/**
708
>
* Local-only compatibility path for chat fields not yet represented by AHP
709
>
* `createChat` (`title` and `model`).
710
>
*/
711
>
createChatWithExtensions(session: URI, chat: URI, options: IAgentCreateChatOptions): Promise<void>;
712
>
shutdown(): Promise<void>;
713
>
getNetworkDiagnosticsInfo(): Promise<IAgentHostNetworkDiagnosticsInfo>;
714
>
getManagedSettingsDiagnostics(): Promise<readonly IAgentHostManagedSettingsDiagnostics[]>;
715
>
diagnosticsFetch(url: string): Promise<IAgentHostNetworkFetchResult>;
716
>
startWebSocketServer(): Promise<IAgentHostSocketInfo>;
717
>
getInspectInfo(tryEnable: boolean): Promise<IAgentHostInspectInfo | undefined>;
718
>
}
719
>
720
>
// ---- IPC data types (serializable across MessagePort) -----------------------
721
>
722
>
export interface IAgentSessionMetadata {
723
>
readonly session: URI;
724
>
readonly startTime: number;
725
>
readonly modifiedTime: number;
726
>
readonly project?: IAgentSessionProjectInfo;
727
>
readonly summary?: string;
728
>
readonly status?: SessionStatus;
729
>
/** Human-readable description of what the session is currently doing. */
730
>
readonly activity?: string;
731
>
readonly workingDirectory?: URI;
732
>
readonly isRead?: boolean;
733
>
readonly isArchived?: boolean;
734
>
/**
735
>
* Aggregate counts (additions / deletions / files) describing the
736
>
* `changeKind: 'session'` changeset for this session — the chip
737
>
* aggregate previously embedded in the catalogue entry. Mirrors
738
>
* `SessionSummary.changes`.
739
>
*/
740
>
readonly changes?: ChangesSummary;
741
>
/**
742
>
* Catalogue of changesets the agent can produce for this session — the
743
>
* {@link Changeset | catalogue} that travels on
744
>
* `SessionSummary.changesets`. Lightweight summary entries (id / label /
745
>
* URI template / aggregate counts) without per-file detail; clients
746
>
* subscribe to a specific expanded changeset URI when they need the full
747
>
* file list.
748
>
*/
749
>
readonly changesets?: readonly Changeset[];
750
>
/**
751
>
* Side-channel metadata mirroring {@link SessionState._meta}, propagated
752
>
* to clients via per-session state subscriptions and the root-channel
753
>
* session summary (the host treats the session-state and session-summary
754
>
* `_meta` as the same bag). Producers SHOULD use namespaced keys; consumers
755
>
* MUST ignore unknown keys. Use the typed accessors in `sessionState.ts`
756
>
* (e.g. `readSessionGitState`, `readSessionGitHubState`) for well-known
757
>
* slots.
758
>
*/
759
>
readonly _meta?: SessionMeta;
760
>
}
761
>
762
>
export interface IAgentSessionProjectInfo {
763
>
readonly uri: URI;
764
>
readonly displayName: string;
765
>
}
766
>
767
>
export interface IAgentCreateSessionResult {
768
>
readonly session: URI;
769
>
readonly project?: IAgentSessionProjectInfo;
770
>
/** The resolved working directory, which may differ from the requested one (e.g. worktree). */
771
>
readonly workingDirectory?: URI;
772
>
/**
773
>
* `true` when the agent only allocated an in-memory placeholder for this
774
>
* session (no SDK session, no worktree, no on-disk state). Materialization
775
>
* happens lazily on the first {@link IAgentChats.sendMessage}, at which point
776
>
* the agent fires {@link IAgent.onDidMaterializeSession}. The
777
>
* {@link IAgentService} uses this flag to defer the `sessionAdded` protocol
778
>
* notification so observers don't see the session in their list until it
779
>
* has been persisted.
780
>
*/
781
>
readonly provisional?: boolean;
782
>
}
783
>
784
>
/**
785
>
* Payload of {@link IAgent.onDidMaterializeSession}. Fired once per session
786
>
* when a previously {@link IAgentCreateSessionResult.provisional} session has
787
>
* its SDK session, worktree (if any), and on-disk metadata in place.
788
>
*/
789
>
export interface IAgentMaterializeSessionEvent {
790
>
readonly session: URI;
791
>
readonly workingDirectory: URI | undefined;
792
>
readonly project: IAgentSessionProjectInfo | undefined;
793
>
}
794
>
795
>
export type AgentProvider = string;
796
>
797
>
/** Well-known agent provider id for the Claude agent-host backend. */
798
>
export const CLAUDE_AGENT_PROVIDER_ID = 'claude' as const;
799
>
800
>
/** Well-known agent provider id for the Codex agent-host backend. */
801
>
export const CODEX_AGENT_PROVIDER_ID = 'codex' as const;
802
>
803
>
/**
804
>
* Static capability facts an agent backend advertises about itself. Each flag
805
>
* is opt-in (absent means unsupported) so single-chat agents (e.g. Codex) can omit
806
>
* the bag entirely. Discovered over IPC alongside the rest of
807
>
* {@link IAgentDescriptor} and surfaced to the sessions UI so features are
808
>
* capability-gated instead of switched on the provider id.
809
>
*
810
>
* This is the IPC contract alias of the protocol-visible {@link AgentCapabilities}
811
>
* type (defined in the root-state protocol); both share a single canonical shape
812
>
* so a new flag added in one place is automatically reflected in the other.
813
>
*/
814
>
export type IAgentCapabilities = AgentCapabilities;
815
>
816
>
/** Metadata describing an agent backend, discovered over IPC. */
817
>
export interface IAgentDescriptor {
818
>
readonly provider: AgentProvider;
819
>
readonly displayName: string;
820
>
readonly description: string;
821
>
/** Static capability flags the agent advertises (see {@link IAgentCapabilities}). */
822
>
readonly capabilities?: IAgentCapabilities;
823
>
}
824
>
825
>
826
>
// ---- Auth types (RFC 9728 / RFC 6750 inspired) -----------------------------
827
>
828
>
/**
829
>
* Parameters for the `authenticate` command.
830
>
* Analogous to sending `Authorization: Bearer <token>` (RFC 6750 section 2.1).
831
>
*/
832
>
export interface AuthenticateParams {
833
>
/**
834
>
* The `resource` identifier from the server's
835
>
* {@link IAuthorizationProtectedResourceMetadata} that this token targets.
836
>
*/
837
>
readonly resource: string;
838
>
/**
839
>
* Scopes that were used to acquire the token. Omitted for legacy clients
840
>
* that can only identify tokens by protected resource.
841
>
*/
842
>
readonly scopes?: readonly string[];
843
>
844
>
/** The bearer token value (RFC 6750). */
845
>
readonly token: string;
846
>
}
847
>
848
>
/** Request for a previously accepted bearer token. */
849
>
export interface IAgentHostAuthTokenRequest {
850
>
/** Protected resource identifier from {@link ProtectedResourceMetadata.resource}. */
851
>
readonly resource: string;
852
>
/** Required token scopes, when the caller needs a scope-specific token. */
853
>
readonly scopes?: readonly string[];
854
>
}
855
>
856
>
/**
857
>
* Result of the `authenticate` command.
858
>
*/
859
>
export interface AuthenticateResult {
860
>
/** Whether the token was accepted. */
861
>
readonly authenticated: boolean;
862
>
}
863
>
864
>
/**
865
>
* Canonical {@link ProtectedResourceMetadata} for the GitHub Copilot
866
>
* resource. Shared between every agent provider that consumes a GitHub
867
>
* Copilot bearer token (e.g. Copilot CLI, Claude) so they advertise an
868
>
* identical resource identifier to the auth flow — clients dispatch by
869
>
* `resource`, and divergent metadata would silently route the same
870
>
* token down separate code paths.
871
>
*/
872
>
export const GITHUB_COPILOT_PROTECTED_RESOURCE: ProtectedResourceMetadata = {
873
>
resource: 'https://api.github.com',
874
>
resource_name: 'GitHub Copilot',
875
>
authorization_servers: ['https://github.com/login/oauth'],
876
>
scopes_supported: ['read:user', 'user:email'],
877
>
required: true,
878
>
};
879
>
880
>
/**
881
>
* Canonical {@link ProtectedResourceMetadata} for GitHub repository write
882
>
* operations (e.g. creating a pull request). Distinct from
883
>
* {@link GITHUB_COPILOT_PROTECTED_RESOURCE} so that the broader `repo`
884
>
* scope is only requested when a session actually needs it (e.g. when a
885
>
* changeset operation handler throws `AHP_AUTH_REQUIRED` with this
886
>
* resource), rather than at session create for every agent.
887
>
*
888
>
* `required: false` reflects that the resource is only needed on demand —
889
>
* agents do not have to advertise it eagerly. The workbench-side auth
890
>
* contributor resolves it lazily in response to operation invocations.
891
>
*/
892
>
export const GITHUB_REPO_PROTECTED_RESOURCE: ProtectedResourceMetadata = {
893
>
resource: 'https://api.github.com/repos',
894
>
resource_name: 'GitHub Repository',
895
>
authorization_servers: ['https://github.com/login/oauth'],
896
>
scopes_supported: ['repo'],
897
>
required: false,
898
>
};
899
>
900
>
export interface IAgentCreateSessionConfig {
901
>
readonly provider?: AgentProvider;
902
>
readonly model?: ModelSelection;
903
>
/**
904
>
* Initial custom agent selection for the new session. Omit to start with
905
>
* no custom agent selected (provider default behavior).
906
>
*/
907
>
readonly agent?: AgentSelection;
908
>
readonly session?: URI;
909
>
readonly workingDirectory?: URI;
910
>
readonly config?: Record<string, unknown>;
911
>
/**
912
>
* Eagerly claim the active client role for the new session. When provided,
913
>
* the server initializes the session with this client as the active
914
>
* client, equivalent to dispatching a `session/activeClientSet`
915
>
* action immediately after creation. The `clientId` MUST match the
916
>
* connection's own `clientId`.
917
>
*/
918
>
readonly activeClient?: SessionActiveClient;
919
>
/** Fork from an existing session at a specific turn. */
920
>
readonly fork?: {
921
>
readonly session: URI;
922
>
readonly turnIndex: number;
923
>
readonly turnId: string;
924
>
/**
925
>
* Maps old protocol turn IDs to new protocol turn IDs.
926
>
* Populated by the service layer after generating fresh UUIDs
927
>
* for the forked session's turns. Used by the agent to remap
928
>
* per-turn data (e.g. SDK event ID mappings) in the session database.
929
>
*/
930
>
readonly turnIdMapping?: ReadonlyMap<string, string>;
931
>
};
932
>
/**
933
>
* Import an existing (e.g. local) conversation into a brand-new session as
934
>
* real, editable turns. The provider translates {@link turns} into a
935
>
* Copilot event log seeded on disk and resumes the session so the turns are
936
>
* reconstituted as genuine backend events (editable / forkable / truncatable).
937
>
*
938
>
* The service layer assigns fresh UUID turn ids before handing the turns to
939
>
* the provider so the seeded event ids and the seeded protocol turns stay
940
>
* aligned. Mutually exclusive with {@link fork}.
941
>
*/
942
>
readonly importConversation?: {
943
>
readonly turns: readonly Turn[];
944
>
readonly model?: ModelSelection;
945
>
};
946
>
/**
947
>
* MCP-style opt-in progress token from the client's `createSession`. When
948
>
* set, the service reports any long-running session bring-up work — chiefly
949
>
* the lazy first-use SDK download — as `progress` notifications carrying
950
>
* this token, so the client can correlate them to this call.
951
>
*/
952
>
readonly progressToken?: string;
953
>
}
954
>
955
>
/** Options for creating an additional chat within a session. */
956
>
export interface IAgentCreateChatOptions {
957
>
/** Optional display title for the new chat. */
958
>
readonly title?: string;
959
>
/** Optional model override; defaults to the session's model. */
960
>
readonly model?: ModelSelection;
961
>
/**
962
>
* Fork an existing chat into this new chat. The new chat starts
963
>
* pre-populated with the source chat's turns up to and including
964
>
* {@link IAgentCreateChatForkSource.turnId}, and its backing chat
965
>
* is forked from the source so it can continue independently.
966
>
*/
967
>
readonly fork?: IAgentCreateChatForkSource;
968
>
/**
969
>
* Create this new chat as a side chat branching from a turn in an existing
970
>
* chat (via `/btw`). Unlike {@link fork}, inherited context is provider-owned
971
>
* and must not appear in the chat's visible history.
972
>
*/
973
>
readonly sideChat?: IAgentCreateChatSideChatSource;
974
>
}
975
>
976
>
/** Identifies a source chat and turn to fork a new chat from. */
977
>
export interface IAgentCreateChatForkSource {
978
>
/** URI of the existing chat to fork from. */
979
>
readonly source: URI;
980
>
/** Turn ID in the source chat; content up to and including this turn is copied. */
981
>
readonly turnId: string;
982
>
/**
983
>
* Maps old source turn IDs to fresh turn IDs for the forked chat. Populated
984
>
* by the agent service so the agent can remap per-turn data (e.g. SDK event
985
>
* ID mappings) in the forked chat's database.
986
>
*/
987
>
readonly turnIdMapping?: ReadonlyMap<string, string>;
988
>
}
989
>
990
>
/** Immutable selected-text snapshot captured when a side chat is created. */
991
>
export interface IAgentCreateChatSideChatSelection {
992
>
/** Exact selected-text snapshot captured at side-chat creation time. */
993
>
readonly text: string;
994
>
/** Optional provenance for the response part that contained {@link text}. */
995
>
readonly responsePartId?: string;
996
>
}
997
>
998
>
/** Identifies a source chat and turn a side chat (`/btw`) branches from. */
999
>
export interface IAgentCreateChatSideChatSource {
1000
>
/** URI of the existing chat the side chat branches from. */
1001
>
readonly source: URI;
1002
>
/** Turn ID in the source chat the side chat records as its provenance. */
1003
>
readonly turnId: string;
1004
>
/** Optional selected-text snapshot captured from the source chat transcript. */
1005
>
readonly selection?: IAgentCreateChatSideChatSelection;
1006
>
/** Concrete provider turn ID to fork/resume from when `turnId` names a host-only local turn. */
1007
>
readonly providerAnchorTurnId?: string;
1008
>
/** Bounded source-chat context captured from host state when the provider transcript lags. */
1009
>
readonly sourceContext?: string;
1010
>
/** User-visible assistant text captured while the source turn was active. */
1011
>
readonly partialResponse?: string;
1012
>
}
1013
>
1014
>
/** Result of {@link IAgentChats.createChat}: the opaque blob to persist for restore. */
1015
>
export interface IAgentCreateChatResult {
1016
>
/**
1017
>
* Opaque, agent-owned token the orchestrator persists verbatim in the chat
1018
>
* catalog and hands back to {@link IAgent.materializeChat} on
1019
>
* restore. The orchestrator never parses it. `undefined` means nothing to
1020
>
* persist (e.g. the agent keeps no resumable backing).
1021
>
*/
1022
>
readonly providerData?: string;
1023
>
/**
1024
>
* The SDK-level session URI that backs this peer chat, when the agent mints
1025
>
* one in the same session store its own {@link IAgent.listSessions} enumerates
1026
>
* (e.g. Claude). First-class and non-opaque — unlike {@link providerData} the
1027
>
* orchestrator reads it to correlate and suppress the backing session so it
1028
>
* never surfaces as a top-level session. `undefined` when the agent keeps no
1029
>
* separately-enumerable backing session.
1030
>
*/
1031
>
readonly backingSession?: URI;
1032
>
}
1033
>
1034
>
/** Payload of {@link IAgent.onDidChangeChatData}. */
1035
>
export interface IAgentChatDataChange {
1036
>
/** The peer chat whose backing chat's blob changed. */
1037
>
readonly chat: URI;
1038
>
/** The new opaque blob to persist (replaces any previously stored value). */
1039
>
readonly providerData: string;
1040
>
}
1041
>
1042
>
/** A legacy peer chat enumerated by {@link IAgent.listLegacyChats} for one-time migration. */
1043
>
export interface IAgentLegacyChat {
1044
>
/** The peer chat's channel URI (see {@link buildChatUri}). */
1045
>
readonly uri: URI;
1046
>
/** The opaque, agent-owned backing blob, encoded as {@link materializeChat} expects. */
1047
>
readonly providerData?: string;
1048
>
}
1049
>
1050
>
/**
1051
>
* Identifies the parent that spawned a chat. The orchestrator records
1052
>
* it as the spawned chat's {@link ChatOriginKind.Tool} origin so clients can
1053
>
* render the parent/child relationship (e.g. a sub-agent "team" member spawned
1054
>
* by a tool call in the parent chat).
1055
>
*/
1056
>
export interface IAgentSpawnedChatParent {
1057
>
/** The parent chat (chat) URI whose tool call performed the spawn. */
1058
>
readonly chat: URI;
1059
>
/** The id of the tool call in the parent that spawned this chat. */
1060
>
readonly toolCallId: string;
1061
>
}
1062
>
1063
>
/**
1064
>
* Payload of {@link IAgent.onDidSpawnChat}: a new chat the
1065
>
* agent spawned itself (e.g. a sub-agent delegated by a tool call), as opposed
1066
>
* to a user-driven chat created via
1067
>
* {@link IAgentChats.createChat}.
1068
>
*/
1069
>
export interface IAgentSpawnChatEvent {
1070
>
/** The session URI the spawned chat belongs to. */
1071
>
readonly session: URI;
1072
>
/** The spawned chat's channel URI (the new chat). */
1073
>
readonly chat: URI;
1074
>
/**
1075
>
* The parent that spawned it, when the spawn was delegated by a tool call.
1076
>
* Recorded as the chat's tool origin in the catalog. Absent for a
1077
>
* top-level, agent-initiated chat with no spawning tool call.
1078
>
*/
1079
>
readonly parent?: IAgentSpawnedChatParent;
1080
>
/** Optional display title for the spawned chat. */
1081
>
readonly title?: string;
1082
>
}
1083
>
1084
>
/** Max characters for a subagent tab title before it is ellipsized. */
1085
>
const SUBAGENT_CHAT_TITLE_MAX_LENGTH = 60;
1086
>
1087
>
/**
1088
>
* Builds the tab title for a subagent peer chat. Prefers the concise
1089
>
* per-task description (so two subagents of the same type still get
1090
>
* distinct, meaningful names), truncating it so an over-long value never
1091
>
* blows out the tab strip or the Subagents dropdown; falls back to the
1092
>
* agent type's display name, then a generic label. Shared by the live
1093
>
* spawn path and the restore path so both name subagent tabs identically.
1094
>
*/
1095
>
export function subagentChatTitle(taskDescription: string | undefined, agentDisplayName: string | undefined): string {
1097
>
if (task) {
1099
>
}
1101
>
}
1103
>
/**
1104
>
* Maps agent `subagent_*` signals to the unified chat catalog's
1105
>
* spawn/end events. Shared by the agents' spawn bridges and the orchestrator so
1106
>
* subagent membership has one derivation.
1107
>
*/
1108
>
export namespace SubagentChatSignal {
1109
>
1110
>
/**
1111
>
* Derives the {@link IAgentSpawnChatEvent} for a `subagent_started` signal,
1112
>
* addressing the subagent by the stable {@link buildSubagentChatUri} and
1113
>
* recording the spawning tool call as its parent edge. Returns `undefined`
1114
>
* for any other signal (or an unmappable chat URI).
1115
>
*/
1116
>
export function toSpawnEvent(signal: AgentSignal): IAgentSpawnChatEvent | undefined {
1119
>
}
1121
>
try {
1122
>
session = parseRequiredSessionUriFromChatUri(signal.chat);
1123
>
} catch {
1124
return undefined;
1125
}
1127
>
session: URI.parse(session),
1128
>
chat: URI.parse(buildSubagentChatUri(session, signal.toolCallId)),
1129
>
parent: { chat: signal.chat, toolCallId: signal.toolCallId },
1130
>
// Prefer the concise per-task description so two subagents of the same
1131
>
// type still get distinct, meaningful tab names; fall back to the agent
1132
>
// type's display name. Truncate so an over-long description never blows
1133
>
// out the tab strip or the Subagents dropdown.
1134
>
title: subagentChatTitle(signal.taskDescription, signal.agentDisplayName),
1135
>
};
1138
>
1139
>
// ---- Chat surface --------------------------------------------------
1140
>
1141
>
/**
1142
>
* The chat-addressed operation surface an agent exposes for the chats
1143
>
* within a session.
1144
>
*
1145
>
* Every operation method addresses a chat by a concrete chat channel URI:
1146
>
* the default chat channel for a session's DEFAULT chat, or an additional
1147
>
* chat's own channel URI. The orchestrator ({@link IAgentService}) owns the
1148
>
* feature-level `(session, chat)` to chat-channel mapping and only ever calls
1149
>
* these operations with a concrete chat URI. This replaces the legacy
1150
>
* `(session, chat?)` parameter pairs and the per-agent default-chat handling on
1151
>
* {@link IAgent}.
1152
>
*
1153
>
* Optional on {@link IAgent}: agents implement this incrementally (waves
1154
>
* C2/C3/C4). Until an agent exposes it, {@link IAgentService} falls back to the
1155
>
* agent's legacy `(session, chat?)` methods via a thin adapter.
1156
>
*/
1157
>
export interface IAgentChats {
1158
>
/**
1159
>
* Create a fresh additional chat within the session the `chat` URI belongs
1160
>
* to, sharing the session's working directory, model, agent, and
1161
>
* customizations. `chat` is the client-chosen channel URI the new chat is
1162
>
* addressed by; its parent session is derived from it.
1163
>
* Returns the opaque {@link IAgentCreateChatResult} blob to persist for
1164
>
* restore (or `void` when the agent keeps no resumable backing).
1165
>
*/
1166
>
createChat(chat: URI, options?: IAgentCreateChatOptions): Promise<IAgentCreateChatResult | void>;
1167
>
1168
>
/**
1169
>
* Fork a new chat from an existing one. The new `chat`
1170
>
* inherits `source`'s backing up to and including
1171
>
* {@link IAgentCreateChatForkSource.turnId} and then continues
1172
>
* independently. The new chat's parent session is derived from its URI.
1173
>
*/
1174
>
fork(chat: URI, source: IAgentCreateChatForkSource, options?: IAgentCreateChatOptions): Promise<IAgentCreateChatResult | void>;
1175
>
1176
>
/**
1177
>
* Dispose an additional chat created via
1178
>
* {@link createChat}/{@link fork}, freeing its backing. A session's
1179
>
* default chat cannot be disposed in isolation; it lives and dies
1180
>
* with the session.
1181
>
*/
1182
>
disposeChat(chat: URI): Promise<void>;
1183
>
1184
>
/**
1185
>
* Send a user message into `chat`; on first send, the host passes the resolved
1186
>
* working directory (or `undefined` for workspace-less sessions).
1187
>
*/
1188
>
sendMessage(chat: URI, prompt: string, workingDirectory: URI | undefined, attachments?: readonly MessageAttachment[], turnId?: string, senderClientId?: string): Promise<void>;
1189
>
1190
>
/** Abort the in-flight turn for `chat`. */
1191
>
abort(chat: URI): Promise<void>;
1192
>
1193
>
/** Change the model for `chat`. */
1194
>
changeModel(chat: URI, model: ModelSelection): Promise<void>;
1195
>
1196
>
/**
1197
>
* Change (or clear) the selected custom agent for `chat`. Passing
1198
>
* `undefined` clears the selection (provider default behavior).
1199
>
*/
1200
>
changeAgent(chat: URI, agent: AgentSelection | undefined): Promise<void>;
1201
>
1202
>
/** Reconstruct the turns for `chat` (used on restore). */
1203
>
getMessages(chat: URI): Promise<readonly Turn[]>;
1204
>
}
1205
>
1206
>
export interface IAgentResolveSessionConfigParams {
1207
>
readonly provider?: AgentProvider;
1208
>
readonly workingDirectory?: URI;
1209
>
readonly config?: Record<string, unknown>;
1210
>
}
1211
>
1212
>
export interface IAgentSessionConfigCompletionsParams extends IAgentResolveSessionConfigParams {
1213
>
readonly property: string;
1214
>
readonly query?: string;
1215
>
}
1216
>
1217
>
/** Serializable model information from the agent host. */
1218
>
export interface IAgentModelInfo {
1219
>
readonly provider: AgentProvider;
1220
>
readonly id: string;
1221
>
readonly name: string;
1222
>
readonly maxContextWindow?: number;
1223
>
readonly maxOutputTokens?: number;
1224
>
readonly maxPromptTokens?: number;
1225
>
readonly supportsVision: boolean;
1226
>
readonly configSchema?: ConfigSchema;
1227
>
readonly policyState?: PolicyState;
1228
>
readonly _meta?: Record<string, unknown>;
1229
>
}
1230
>
1231
>
// ---- Agent signals (sent via IAgent.onDidSessionProgress) -------------------
1232
>
1233
>
/**
1234
>
* A signal emitted by an agent during session execution.
1235
>
*
1236
>
* Most signals carry a protocol {@link SessionAction} directly via the
1237
>
* `kind: 'action'` shape, eliminating a parallel event ontology. A small
1238
>
* number of cases that have no clean protocol action (permission
1239
>
* auto-approval, subagent session creation, steering message
1240
>
* acknowledgment) remain as discriminated non-action signals so the host
1241
>
* can perform side effects before — or instead of — dispatching an action.
1242
>
*/
1243
>
export type AgentSignal =
1244
>
| IAgentActionSignal
1245
>
| IAgentToolPendingConfirmationSignal
1246
>
| IAgentSubagentStartedSignal
1247
>
| IAgentSubagentCompletedSignal
1248
>
| IAgentSteeringConsumedSignal;
1249
>
1250
>
/**
1251
>
* Carries a protocol {@link SessionAction} produced by an agent. The host
1252
>
* dispatches the action through the state manager after routing via
1253
>
* {@link IAgentActionSignal.parentToolCallId} (if set).
1254
>
*
1255
>
* Agents are responsible for populating the target channel and any `turnId` /
1256
>
* `partId` fields on the action.
1257
>
*/
1258
>
export interface IAgentActionSignal {
1259
>
readonly kind: 'action';
1260
>
/** Target session or chat channel URI. For inner subagent events this is the parent session — see {@link parentToolCallId}. */
1261
>
readonly resource: URI;
1262
>
/** Protocol action to dispatch. */
1263
>
readonly action: SessionAction | ChatAction;
1264
>
/** If set, route the action to the subagent session belonging to this tool call. */
1265
>
readonly parentToolCallId?: string;
1266
>
}
1267
>
1268
>
/**
1269
>
* A tool has finished collecting parameters and needs the host to decide
1270
>
* whether it should run (or, mid-execution, re-confirm). The host applies
1271
>
* auto-approval logic over {@link permissionKind} / {@link permissionPath}
1272
>
* (see `SessionPermissionManager.getAutoApproval`) and then dispatches the
1273
>
* appropriate `ChatToolCallReady` action — with confirmation options
1274
>
* baked in when the user must approve, or with `confirmed: NotNeeded` when
1275
>
* the host auto-approved.
1276
>
*
1277
>
* Kept as a non-action signal because the host owns this approval policy;
1278
>
* the agent only describes the tool call and the kind of permission being
1279
>
* requested. The {@link state} field carries the protocol-shaped tool-call
1280
>
* state and is dispatched verbatim into the action.
1281
>
*/
1282
>
export interface IAgentToolPendingConfirmationSignal {
1283
>
readonly kind: 'pending_confirmation';
1284
>
/** Target chat channel URI containing the tool call. */
1285
>
readonly chat: URI;
1286
>
/** Protocol-shaped pending-confirmation state, dispatched verbatim into `ChatToolCallReady`. */
1287
>
readonly state: ToolCallPendingConfirmationState;
1288
>
/** Host-only auto-approval kind (not part of the dispatched action). */
1289
>
readonly permissionKind?: 'shell' | 'write' | 'mcp' | 'read' | 'url' | 'skill' | 'custom-tool' | 'hook' | 'memory' | 'extension-management' | 'extension-permission-access';
1290
>
/** Host-only auto-approval path target (not part of the dispatched action). */
1291
>
readonly permissionPath?: string;
1292
>
/**
1293
>
* Host-only flag (not part of the dispatched action): the model requested
1294
>
* this shell command run OUTSIDE the sandbox (and the host opted in via
1295
>
* `sandbox.allowBypass`).
1296
>
*/
1297
>
readonly requestSandboxBypass?: boolean;
1298
>
/**
1299
>
* If set, the tool call belongs to the subagent rooted at this
1300
>
* parent tool call. Used by the host to route the resulting
1301
>
* `ChatToolCallReady` to the subagent session — otherwise the
1302
>
* action would land on the parent session, where there is no
1303
>
* matching `ChatToolCallStart`.
1304
>
*/
1305
>
readonly parentToolCallId?: string;
1306
>
}
1307
>
1308
>
/**
1309
>
* A subagent was spawned by a tool call. The host creates a child session
1310
>
* silently and routes subsequent inner-tool events to it.
1311
>
*
1312
>
* Kept as a non-action signal because subagent session creation has no
1313
>
* protocol action — it's a host-side composition primitive.
1314
>
*/
1315
>
export interface IAgentSubagentStartedSignal {
1316
>
readonly kind: 'subagent_started';
1317
>
readonly chat: URI;
1318
>
readonly toolCallId: string;
1319
>
readonly agentName: string;
1320
>
readonly agentDisplayName: string;
1321
>
readonly agentDescription?: string;
1322
>
/**
1323
>
* The spawning Task tool's short (typically 3-5 word) `description`
1324
>
* input, e.g. "Review package.json structure". Distinct from
1325
>
* {@link agentDescription} (the agent *type*'s long role blurb) and
1326
>
* {@link agentDisplayName} (the agent type's name). Preferred as the
1327
>
* peer chat's tab title because it is concise and per-task, so two
1328
>
* subagents of the same type still get distinct, meaningful names.
1329
>
* Absent when the harness does not surface a task description.
1330
>
*/
1331
>
readonly taskDescription?: string;
1332
>
/**
1333
>
* The full delegated instruction the parent handed the subagent (the
1334
>
* spawning tool's `prompt` input). Populated by each provider at emit
1335
>
* time from its own native source, so the shared orchestrator never
1336
>
* parses a provider-specific tool-input shape. Seeds the subagent peer
1337
>
* chat's opening request. Distinct from {@link taskDescription} (a short
1338
>
* tab-title label). Absent when the harness does not surface a prompt.
1339
>
*/
1340
>
readonly taskPrompt?: string;
1341
>
/**
1342
>
* If set, the spawning tool call ({@link toolCallId}) itself lives
1343
>
* inside another subagent's chat — this is the tool call **one level up**
1344
>
* from the spawning tool (its parent), i.e. the tool that spawned the
1345
>
* immediate parent chat. The host uses it to route the
1346
>
* subagent-discovery side effect (the `ChatToolCallContentChanged`
1347
>
* block that lets clients find the child chat) to that immediate parent
1348
>
* chat rather than the top-level {@link chat}. Because subagent chats
1349
>
* are flat (all keyed off the root session + the spawning tool id),
1350
>
* this single one-hop reference resolves the correct parent chat at
1351
>
* ANY nesting depth — no per-level chain is needed. Absent for a
1352
>
* top-level subagent, whose spawning tool call lives directly in
1353
>
* {@link chat}.
1354
>
*/
1355
>
readonly parentToolCallId?: string;
1356
>
}
1357
>
1358
>
/**
1359
>
* A subagent has finished — either successfully or with an error. The host
1360
>
* uses this to tear down the child session after all of its events have been
1361
>
* routed. The parent tool call completing is not a reliable signal for this
1362
>
* because background subagents (e.g. Copilot's `mode: background` task) keep
1363
>
* emitting events after their parent tool call returns immediately.
1364
>
*/
1365
>
export interface IAgentSubagentCompletedSignal {
1366
>
readonly kind: 'subagent_completed';
1367
>
readonly chat: URI;
1368
>
readonly toolCallId: string;
1369
>
}
1370
>
1371
>
/** A steering message was consumed (sent to the model). */
1372
>
export interface IAgentSteeringConsumedSignal {
1373
>
readonly kind: 'steering_consumed';
1374
>
readonly chat: URI;
1375
>
readonly id: string;
1376
>
}
1377
>
1378
>
// ---- Session URI helpers ----------------------------------------------------
1379
>
1380
>
export namespace AgentSession {
1381
>
1382
>
/**
1383
>
* Creates a session URI from a provider name and raw session ID.
1384
>
* The URI scheme is the provider name (e.g., `copilot:/<rawId>`).
1385
>
*/
1386
>
export function uri(provider: AgentProvider, rawSessionId: string): URI {
1388
>
}
1390
>
/**
1391
>
* Extracts the raw session ID from a session URI (the path without leading slash).
1392
>
* Accepts both a URI object and a URI string.
1393
>
*/
1394
>
export function id(session: URI | string): string {
1395
>
const parsed = typeof session === 'string' ? URI.parse(session) : session;
agentService.ts ×1
1396
>
return parsed.path.substring(1);
1397
>
}
1399
>
/**
1400
>
* Extracts the provider name from a session URI scheme.
1401
>
* Accepts both a URI object and a URI string.
1402
>
*/
1403
>
export function provider(session: URI | string): AgentProvider | undefined {
1404
>
const parsed = typeof session === 'string' ? URI.parse(session) : session;
agentService.ts ×1
1405
>
return parsed.scheme || undefined;
1406
>
}
1408
>
1409
>
// ---- Agent provider interface -----------------------------------------------
1410
>
1411
>
/**
1412
>
* A notification originating from an MCP server, routed back to the AHP
1413
>
* client through the `mcp://` side channel. `channel` is the channel
1414
>
* URI advertised on the owning
1415
>
* {@link McpServerCustomization.channel | McpServerCustomization}; the
1416
>
* client uses it to fan the notification out to the appropriate App.
1417
>
* `method` and `params` follow the underlying MCP notification spec
1418
>
* (e.g. `notifications/tools/list_changed`).
1419
>
*/
1420
>
export interface IMcpNotification {
1421
>
readonly channel: string;
1422
>
readonly method: string;
1423
>
readonly params?: Record<string, unknown>;
1424
>
}
1425
>
1426
>
/**
1427
>
* A subagent child session discovered in a parent session's event log,
1428
>
* returned by {@link IAgent.getSubagentSessions} so a parent restore can
1429
>
* register the child's state up-front.
1430
>
*/
1431
>
export interface IRestoredSubagentSession {
1432
>
/** Child subagent session URI (subscribable by clients). */
1433
>
readonly resource: URI;
1434
>
/** Parent tool call id that spawned the subagent. */
1435
>
readonly toolCallId: string;
1436
>
/** Display title for the subagent session. */
1437
>
readonly title: string;
1438
>
/** Reconstructed turns for the subagent's transcript. */
1439
>
readonly turns: readonly Turn[];
1440
>
}
1441
>
1442
>
/**
1443
>
* A per-session handle for one active client's contributions (tools and
1444
>
* plugin customizations) to an agent session, obtained via
1445
>
* {@link IAgent.getOrCreateActiveClient}.
1446
>
*
1447
>
* `tools` and `customizations` are mutable accessor properties: assigning a
1448
>
* new array replaces this client's contribution wholesale and triggers the
1449
>
* agent's internal reaction (refreshing the merged tool set exposed to the
1450
>
* model, or kicking off an asynchronous customization sync). The arrays are
1451
>
* `readonly` so callers cannot mutate them in place and silently bypass the
1452
>
* setter. The agent merges the contributions of all active clients on a
1453
>
* session, deduplicating as needed.
1454
>
*/
1455
>
export interface IActiveClient {
1456
>
/** Client identifier (matches `clientId` from `initialize`). */
1457
>
readonly clientId: string;
1458
>
/** Human-readable client name (e.g. `"VS Code"`), if provided. */
1459
>
readonly displayName: string | undefined;
1460
>
/** This client's tools. Assigning replaces the set (full replacement). */
1461
>
tools: readonly ToolDefinition[];
1462
>
/** This client's plugin customizations. Assigning replaces the set and starts an internal sync. */
1463
>
customizations: readonly ClientPluginCustomization[];
1464
>
}
1465
>
1466
>
/**
1467
>
* Implemented by each agent backend (e.g. Copilot SDK).
1468
>
* The {@link IAgentService} dispatches to the appropriate agent based on
1469
>
* the agent id.
1470
>
*/
1471
>
export interface IAgent {
1472
>
/** Unique identifier for this provider (e.g. `'copilot'`). */
1473
>
readonly id: AgentProvider;
1474
>
1475
>
/** Fires when the provider streams progress for a session. */
1476
>
readonly onDidSessionProgress: Event<AgentSignal>;
1477
>
1478
>
/**
1479
>
* Fires once when a previously
1480
>
* {@link IAgentCreateSessionResult.provisional} session has been
1481
>
* materialized — i.e. its SDK session, worktree (if any), and on-disk
1482
>
* metadata are all in place. The {@link IAgentService} uses this event
1483
>
* to fire the deferred `sessionAdded` notification with the now-final
1484
>
* summary.
1485
>
*/
1486
>
readonly onDidMaterializeSession?: Event<IAgentMaterializeSessionEvent>;
1487
>
1488
>
/**
1489
>
* Provides the agent host's server-tool host so the provider can advertise
1490
>
* and execute the agent host's server tools (feedback "comments" today, more
1491
>
* in the future) against a session's state. Optional: providers that do not
1492
>
* support server-side tools simply omit it. Called once during registration
1493
>
* with the {@link IAgentService}.
1494
>
*/
1495
>
setServerToolHost?(host: IAgentServerToolHost): void;
1496
>
1497
>
// ---- Chat surface ------------------------------------------------------
1498
>
//
1499
>
// `chats` is the chat-addressed operation surface. Its chats are addressed
1500
>
// by concrete chat channel URIs. The orchestrator ({@link IAgentService})
1501
>
// owns the feature-level `(session, chat)` to chat-channel mapping.
1502
>
1503
>
/**
1504
>
* Chat-addressed surface for the chats within a session (send/abort/
1505
>
* change model/agent, create/fork/dispose chats, read history).
1506
>
*/
1507
>
readonly chats: IAgentChats;
1508
>
1509
>
// ---- Session lifecycle / configuration ---------------------------------
1510
>
1511
>
/** Create a new session. Host-owned worktree fields are omitted from `config.config`. */
1512
>
createSession(config?: IAgentCreateSessionConfig): Promise<IAgentCreateSessionResult>;
1513
>
1514
>
/** Resolve provider-owned session configuration; host-owned worktree fields are omitted. */
1515
>
resolveSessionConfig(params: IAgentResolveSessionConfigParams): Promise<ResolveSessionConfigResult>;
1516
>
1517
>
/** Return dynamic completions for a provider-owned session configuration property. */
1518
>
sessionConfigCompletions(params: IAgentSessionConfigCompletionsParams): Promise<SessionConfigCompletionsResult>;
1519
>
1520
>
/**
1521
>
* Re-attach an agent's in-memory backing for a peer chat on session
1522
>
* restore, decoding the opaque `providerData` produced earlier by
1523
>
* {@link IAgentChats.createChat} (or the latest
1524
>
* {@link onDidChangeChatData}). After this resolves the agent MUST
1525
>
* be able to serve {@link getSessionMessages}/
1526
>
* {@link IAgentChats.sendMessage} for `chat`.
1527
>
* Best-effort: implementations SHOULD NOT throw on a corrupt/unknown blob —
1528
>
* log and no-op so the orchestrator restores the chat with history but no
1529
>
* live backing. `providerData` is `undefined` only for legacy entries with
1530
>
* no stored blob, in which case the agent MAY consult its own legacy
1531
>
* persistence once to recover the backing.
1532
>
*/
1533
>
materializeChat?(chat: URI, providerData: string | undefined): Promise<void>;
1534
>
1535
>
/**
1536
>
* Migration-only enumeration of a session's peer chats persisted in the
1537
>
* agent's OWN legacy format (predating the orchestrator-owned catalog). The
1538
>
* orchestrator calls this once, when its own catalog is absent, to drain the
1539
>
* legacy chats into {@link PEER_CHATS_METADATA_KEY}; subsequent restores read
1540
>
* the orchestrator catalog and never consult this again. Each entry's
1541
>
* `providerData` uses the same encoding {@link IAgentChats.createChat}
1542
>
* produces and {@link materializeChat} decodes. Agents with no legacy
1543
>
* format (e.g. Codex) omit this method.
1544
>
*/
1545
>
listLegacyChats?(session: URI): Promise<readonly IAgentLegacyChat[]>;
1546
>
1547
>
/**
1548
>
* Fires when a peer chat's opaque `providerData` changes after creation
1549
>
* (e.g. per-chat model switch, fork remap). The orchestrator re-persists the
1550
>
* blob. Agents whose blob is immutable never fire this.
1551
>
*/
1552
>
readonly onDidChangeChatData?: Event<IAgentChatDataChange>;
1553
>
1554
>
// ---- Spawned chat (membership) channel -------------------------
1555
>
//
1556
>
// First-class membership channel for chats the agent spawns itself
1557
>
// (e.g. sub-agent / "team" member chats delegated by a tool call),
1558
>
// as opposed to user-driven chats created via
1559
>
// {@link IAgentChats.createChat}. The orchestrator
1560
>
// ({@link IAgentService}) routes these straight into the chat catalog
1561
>
// (addChat/removeChat) so harness-spawned and user-driven chats share ONE
1562
>
// membership path. Agents that never spawn chats omit both events.
1563
>
1564
>
/**
1565
>
* Fires when the agent spawns a new chat within a session (e.g. a
1566
>
* sub-agent delegated by a tool call). The orchestrator records it in the
1567
>
* chat catalog, preserving the {@link IAgentSpawnChatEvent.parent}
1568
>
* spawn edge as the chat's {@link ChatOriginKind.Tool} origin.
1569
>
*/
1570
>
readonly onDidSpawnChat?: Event<IAgentSpawnChatEvent>;
1571
>
1572
>
/**
1573
>
* Called when a chat's pending (steering) message changes.
1574
>
* The agent harness decides how to react — e.g. inject steering
1575
>
* mid-turn via `mode: 'immediate'`. Steering is always addressed by a
1576
>
* concrete chat channel URI — the session's default chat or an additional
1577
>
* peer chat — so it never leaks into a sibling chat of the same session.
1578
>
*
1579
>
* Queued messages are consumed on the server side and are not
1580
>
* forwarded to the agent; `queuedMessages` will always be empty.
1581
>
*/
1582
>
setPendingMessages?(chat: URI, steeringMessage: PendingMessage | undefined, queuedMessages: readonly PendingMessage[]): void;
1583
>
1584
>
/**
1585
>
* Retrieve the reconstructed turns for a session, used when restoring
1586
>
* sessions from persistent storage. Each agent owns the conversion from
1587
>
* its SDK-specific event log to protocol {@link Turn}s, including
1588
>
* subagent sessions (callers pass the subagent URI to retrieve the
1589
>
* child session's turns).
1590
>
*/
1591
>
getSessionMessages(session: URI): Promise<readonly Turn[]>;
1592
>
1593
>
/**
1594
>
* Returns the subagent child sessions discoverable in a session's event
1595
>
* log so a parent restore can eagerly register them in a single pass.
1596
>
* Without this, every child is restored separately by re-fetching and
1597
>
* re-reconstructing the full parent event log (one pass per subagent).
1598
>
* Agents that serve this from the same reconstruction they already
1599
>
* produced for the parent turns avoid that redundant work entirely.
1600
>
* Optional; agents without subagents omit it.
1601
>
*/
1602
>
getSubagentSessions?(session: URI): Promise<readonly IRestoredSubagentSession[]>;
1603
>
1604
>
/** Dispose a session, freeing resources. */
1605
>
disposeSession(session: URI): Promise<void>;
1606
>
1607
>
/**
1608
>
* Release a session's in-memory resources (SDK session/connection, cached
1609
>
* per-session state) without deleting any durable data. Unlike
1610
>
* {@link disposeSession}, this is non-destructive: the on-disk session log,
1611
>
* session database, and worktree are all preserved so the session can be
1612
>
* transparently resumed later. Used by idle-session eviction to bound
1613
>
* memory in long-lived host processes. Optional; providers that hold no
1614
>
* releasable in-memory state simply omit it.
1615
>
*/
1616
>
releaseSession?(session: URI): Promise<void>;
1617
>
1618
>
/** Respond to a pending permission request from the SDK. */
1619
>
respondToPermissionRequest(requestId: string, approved: boolean): void;
1620
>
1621
>
/** Respond to a pending user input request from the SDK's ask_user tool. */
1622
>
respondToUserInputRequest(requestId: string, response: ChatInputResponseKind, answers?: Record<string, ChatInputAnswer>): void;
1623
>
1624
>
/** Return the descriptor for this agent. */
1625
>
getDescriptor(): IAgentDescriptor;
1626
>
1627
>
/** Available models from this provider. */
1628
>
readonly models: IObservable<readonly IAgentModelInfo[]>;
1629
>
1630
>
/**
1631
>
* Re-enumerate this provider's model list and publish the result to
1632
>
* {@link models}. Called both on provider-owned triggers (authentication,
1633
>
* transport changes) and periodically by the host's model-refresh
1634
>
* scheduler, so implementations MUST coalesce concurrent calls into a
1635
>
* single backend request and MUST NOT reject: a failed refresh is logged
1636
>
* and leaves the last known-good list in place.
1637
>
*
1638
>
* Optional so providers without a dynamic model catalog (mocks, test
1639
>
* agents) need not implement it.
1640
>
*/
1641
>
refreshModels?(): Promise<void>;
1642
>
1643
>
/** List persisted sessions from this provider. */
1644
>
listSessions(): Promise<IAgentSessionMetadata[]>;
1645
>
1646
>
/** Retrieve metadata for a single persisted session, without enumerating the provider catalog. */
1647
>
getSessionMetadata?(session: URI): Promise<IAgentSessionMetadata | undefined>;
1648
>
1649
>
/** Declare protected resources this agent requires auth for (RFC 9728). */
1650
>
getProtectedResources(): ProtectedResourceMetadata[];
1651
>
1652
>
/**
1653
>
* Endpoints this provider uses and recommends probing in network
1654
>
* diagnostics. Optional.
1655
>
*/
1656
>
getNetworkDiagnosticsEndpoints?(): Promise<readonly IAgentHostNetworkEndpoint[]>;
1657
>
1658
>
/** Authenticated account name to display in network diagnostics, when known. */
1659
>
getNetworkDiagnosticsAccount?(): Promise<string | undefined>;
1660
>
1661
>
/** Resolve the provider's own effective enterprise managed-settings snapshot. */
1662
>
getManagedSettingsDiagnostics?(): Promise<IAgentHostManagedSettingsSnapshot>;
1663
>
1664
>
/**
1665
>
* Fires when the agent's host-owned customizations change
1666
>
* (loading state, resolution results, etc.), so infrastructure
1667
>
* can republish {@link AgentInfo} and session customization state.
1668
>
*/
1669
>
readonly onDidCustomizationsChange?: Event<void>;
1670
>
1671
>
/**
1672
>
* Fires when this agent needs the client to (re-)authenticate a
1673
>
* protected resource — for example after a runtime transport-mode flip
1674
>
* makes a previously-unneeded credential required. The host stamps the
1675
>
* root channel and forwards it verbatim as an `auth/required`
1676
>
* notification; clients respond via {@link authenticate}.
1677
>
*/
1678
>
readonly onDidRequireAuth?: Event<Omit<AuthRequiredParams, 'channel'>>;
1679
>
1680
>
/**
1681
>
* Returns the host-owned customizations this agent currently exposes.
1682
>
*
1683
>
* Used to publish baseline customization metadata on {@link AgentInfo}.
1684
>
* Always container customizations ({@link PluginCustomization} or
1685
>
* {@link DirectoryCustomization}).
1686
>
*/
1687
>
getCustomizations?(): readonly Customization[];
1688
>
1689
>
/**
1690
>
* Returns the effective customization list for a session, including
1691
>
* source, enablement, and loading/error status.
1692
>
*/
1693
>
getSessionCustomizations?(session: URI): Promise<readonly Customization[]>;
1694
>
1695
>
/**
1696
>
* Authenticate for a specific resource. Returns true if accepted.
1697
>
* The `resource` matches {@link IAuthorizationProtectedResourceMetadata.resource}.
1698
>
*/
1699
>
authenticate(resource: string, token: string): Promise<boolean>;
1700
>
1701
>
/**
1702
>
* Optional hook for provider-owned session resources that are not advertised
1703
>
* as root agent protected resources, such as MCP server OAuth challenges.
1704
>
*/
1705
>
handleAuthenticationToken?(params: AuthenticateParams): Promise<boolean>;
1706
>
1707
>
/**
1708
>
* Truncate a chat's history. If `turnId` is provided, keeps turns up to
1709
>
* and including that turn. If omitted, all turns are removed.
1710
>
*
1711
>
* `chat` identifies which chat to truncate: the session's default chat
1712
>
* (addressed by the session's default chat URI) or a peer (non-default)
1713
>
* chat, which has its own backing.
1714
>
*
1715
>
* Optional — not all providers support truncation.
1716
>
*/
1717
>
truncateSession?(session: URI, turnId: string | undefined, chat: URI): Promise<void>;
1718
>
1719
>
/**
1720
>
* Notifies the provider that a session's archived state has changed.
1721
>
* Providers may use this to clean up or restore per-session resources
1722
>
* (for example, removing a session-owned worktree on archive and
1723
>
* recreating it on unarchive). Optional.
1724
>
*/
1725
>
onArchivedChanged?(session: URI, isArchived: boolean): Promise<void>;
1726
>
1727
>
/**
1728
>
* Notifies the provider that a **client** (user) changed this session's
1729
>
* config — e.g. via an approvals/model picker. `values` is the post-reducer
1730
>
* merged config. Lets the provider propagate a session-mutable change (such
1731
>
* as Claude's `permissionMode`) to a running SDK mid-turn. Fires only for
1732
>
* client-originated changes; internal server-side config writes (e.g. a tool
1733
>
* persisting a mode) do NOT trigger it, so a provider can forward freely
1734
>
* without re-entering its own SDK callbacks. Optional.
1735
>
*/
1736
>
onSessionConfigChanged?(session: URI, values: Record<string, unknown>): void;
1737
>
1738
>
/**
1739
>
* Get (or lazily create) the per-session handle for an active client,
1740
>
* identified by `clientId`. Mutating the returned {@link IActiveClient}'s
1741
>
* `tools` / `customizations` updates only that client's contribution; the
1742
>
* agent merges the contributions of all active clients when exposing them
1743
>
* to the model. A session MAY have several active clients at once.
1744
>
*
1745
>
* @param session The session URI this client contributes to.
1746
>
* @param client The client's `clientId` and optional human-readable name.
1747
>
*/
1748
>
getOrCreateActiveClient(session: URI, client: { readonly clientId: string; readonly displayName?: string }): IActiveClient;
1749
>
1750
>
/**
1751
>
* Remove an active client from a session, clearing its tool and
1752
>
* customization contributions. No-op when no active client matches
1753
>
* `clientId`.
1754
>
*
1755
>
* @param session The session the client is leaving.
1756
>
* @param clientId The client to remove.
1757
>
*/
1758
>
removeActiveClient(session: URI, clientId: string): void;
1759
>
1760
>
/**
1761
>
* Called when a client completes a client-provided tool call.
1762
>
* Resolves the tool handler's deferred promise so the SDK can continue.
1763
>
*
1764
>
* @param session The session the tool call belongs to.
1765
>
* @param chat The chat channel the tool call was issued on, when known.
1766
>
* Agents that track peer chats separately from the default chat (e.g.
1767
>
* copilot) use this to route the completion to the right chat;
1768
>
* agents without peer chats ignore it and resolve by `session`.
1769
>
* @param toolCallId The id of the tool call being completed.
1770
>
* @param result The result of the tool call.
1771
>
*/
1772
>
onClientToolCallComplete(session: URI, chat: URI, toolCallId: string, result: ToolCallResult): void;
1773
>
1774
>
/** Request a session MCP server start/restart by customization id. */
1775
>
startMcpServer?(session: URI, id: string): Promise<void>;
1776
>
1777
>
/** Request a session MCP server stop by customization id. */
1778
>
stopMcpServer?(session: URI, id: string): Promise<void>;
1779
>
1780
>
/** Gracefully shut down all sessions. */
1781
>
shutdown(): Promise<void>;
1782
>
1783
>
/**
1784
>
* Routes a request received on an `mcp://` side channel to the agent's
1785
>
* MCP server implementation. The channel carries raw MCP JSON-RPC
1786
>
* methods (e.g. `tools/list`, `tools/call`, `resources/read`) tagged
1787
>
* with the routing envelope; the protocol server decodes the envelope
1788
>
* and forwards `(session, serverName, method, params)` here.
1789
>
*
1790
>
* The agent MUST reject unknown methods with an error whose message
1791
>
* begins with `Method not found` so the protocol server can map it to
1792
>
* a JSON-RPC `-32601`.
1793
>
*
1794
>
* Optional — agents that don't surface any MCP servers (or don't
1795
>
* advertise `mcpApp` capabilities) can omit this.
1796
>
*/
1797
>
handleMcpRequest?(session: URI, serverName: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
1798
>
1799
>
/**
1800
>
* Fires when an MCP server owned by this agent emits a notification
1801
>
* that should be forwarded to AHP clients over the `mcp://` side
1802
>
* channel. Today this is exclusively
1803
>
* `notifications/tools/list_changed` and
1804
>
* `notifications/resources/list_changed`. The protocol server
1805
>
* fans the notification out to every connected client.
1806
>
*
1807
>
* Optional — agents that don't expose MCP servers can omit this.
1808
>
*/
1809
>
readonly onMcpNotification?: Event<IMcpNotification>;
1810
>
1811
>
/** Dispose this provider and all its resources. */
1812
>
dispose(): void;
1813
>
}
1814
>
1815
>
// ---- Service interfaces -----------------------------------------------------
1816
>
1817
>
export const IAgentService = createDecorator<IAgentService>('agentService');
1818
>
1819
>
/**
1820
>
* Service contract for communicating with the agent host process. Methods here
1821
>
* are proxied across MessagePort via `ProxyChannel`.
1822
>
*
1823
>
* State is synchronized via the subscribe/unsubscribe/dispatchAction protocol.
1824
>
* Clients observe root state (agents, models) and session state via subscriptions,
1825
>
* and mutate state by dispatching actions (e.g. session/turnStarted, session/turnCancelled).
1826
>
*/
1827
>
export interface IAgentService {
1828
>
readonly _serviceBrand: undefined;
1829
>
1830
>
/**
1831
>
* Authenticate for a protected resource on the server.
1832
>
* The {@link AuthenticateParams.resource} must match a resource from
1833
>
* the agent's protectedResources in root state. Analogous to RFC 6750
1834
>
* bearer token delivery.
1835
>
*/
1836
>
authenticate(params: AuthenticateParams): Promise<AuthenticateResult>;
1837
>
1838
>
/** Return a bearer token previously supplied via {@link authenticate}. */
1839
>
getAuthToken(request: IAgentHostAuthTokenRequest): string | undefined;
1840
>
1841
>
/** List all available sessions from the Copilot CLI. */
1842
>
listSessions(): Promise<IAgentSessionMetadata[]>;
1843
>
1844
>
/** Create a new session. Returns the session URI. */
1845
>
createSession(config?: IAgentCreateSessionConfig): Promise<URI>;
1846
>
1847
>
/**
1848
>
* Create an additional chat within an existing session. Spins up the
1849
>
* backing chat in the harness (sharing the session's session) and
1850
>
* registers the chat in the session's catalog so subscribers observe a
1851
>
* `session/chatAdded` action. The `chat` URI is the client-chosen channel.
1852
>
*/
1853
>
createChat(session: URI, chat: URI, options?: IAgentCreateChatOptions): Promise<void>;
1854
>
1855
>
/** Dispose an additional chat created via {@link createChat}. */
1856
>
disposeChat(session: URI, chat: URI): Promise<void>;
1857
>
1858
>
/** Resolve the dynamic configuration schema for creating a session. */
1859
>
resolveSessionConfig(params: IAgentResolveSessionConfigParams): Promise<ResolveSessionConfigResult>;
1860
>
1861
>
/** Return dynamic completions for a session configuration property. */
1862
>
sessionConfigCompletions(params: IAgentSessionConfigCompletionsParams): Promise<SessionConfigCompletionsResult>;
1863
>
1864
>
/**
1865
>
* Return completion items for a partially-typed input (e.g. an `@`-mention
1866
>
* inside a user message the user is composing). Delegates to a pluggable
1867
>
* set of {@link IAgentHostCompletionItemProvider}s registered with the
1868
>
* agent host.
1869
>
*
1870
>
* Note: this method does not accept a {@link CancellationToken} because
1871
>
* `CancellationToken`s do not round-trip through the IPC boundary today
1872
>
* (the deserialised value lacks the prototype methods used by
1873
>
* subscribers). Callers that need cancellation should race the returned
1874
>
* promise on their own side.
1875
>
*/
1876
>
completions(params: CompletionsParams): Promise<CompletionsResult>;
1877
>
1878
>
/**
1879
>
* Returns the set of characters that, when typed in a {@link UserMessage}
1880
>
* input, SHOULD cause the client to issue a `completions` request.
1881
>
* Aggregated from every registered {@link IAgentHostCompletionItemProvider}.
1882
>
*/
1883
>
getCompletionTriggerCharacters(): Promise<readonly string[]>;
1884
>
1885
>
/** Dispose a session in the agent host, freeing SDK resources. */
1886
>
disposeSession(session: URI): Promise<void>;
1887
>
1888
>
/** Create a new terminal on the agent host. */
1889
>
createTerminal(params: CreateTerminalParams): Promise<void>;
1890
>
1891
>
/** Dispose a terminal and kill its process if still running. */
1892
>
disposeTerminal(terminal: URI): Promise<void>;
1893
>
1894
>
/** Invoke a server-defined changeset operation. */
1895
>
invokeChangesetOperation(params: InvokeChangesetOperationParams): Promise<InvokeChangesetOperationResult>;
1896
>
1897
>
/**
1898
>
* Routes a request received on an `mcp://` AHP side channel to the
1899
>
* MCP server implementation owned by the appropriate agent. The
1900
>
* channel URI shape is `mcp://<providerId>/<sessionId>/<serverName>`
1901
>
* (the latter two segments URL-encoded), matching the
1902
>
* {@link McpServerCustomization.channel | channel} the agent host
1903
>
* advertises while the server is in
1904
>
* {@link McpServerStatus.Ready | `Ready`}.
1905
>
*
1906
>
* `method` is the raw MCP JSON-RPC method (e.g. `tools/list`,
1907
>
* `tools/call`, `resources/read`); `params` are the JSON-RPC params
1908
>
* (still carrying the routing envelope's `channel` field, which the
1909
>
* agent may ignore). Rejects with an `Error` whose message begins
1910
>
* with `Method not found` when the channel is unknown or the agent
1911
>
* doesn't recognise the method — the protocol server translates that
1912
>
* into a JSON-RPC `-32601`.
1913
>
*/
1914
>
handleMcpRequest(channel: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
1915
>
1916
>
/**
1917
>
* Aggregated stream of MCP notifications across every agent. The
1918
>
* protocol server subscribes once and broadcasts each notification as
1919
>
* a JSON-RPC notification to all connected clients (the routing
1920
>
* envelope's `channel` field is sufficient for client-side dispatch,
1921
>
* so no per-subscription fanout is required).
1922
>
*/
1923
>
readonly onMcpNotification: Event<IMcpNotification>;
1924
>
1925
>
/** Gracefully shut down all sessions and the underlying client. */
1926
>
shutdown(): Promise<void>;
1927
>
1928
>
/**
1929
>
* Host-level network context for diagnostics — agent host version, OS/arch,
1930
>
* account, proxy settings/env, and the endpoints worth probing (which
1931
>
* callers probe via {@link diagnosticsFetch}, plus any additional URLs).
1932
>
*/
1933
>
getNetworkDiagnosticsInfo(): Promise<IAgentHostNetworkDiagnosticsInfo>;
1934
>
1935
>
/** Resolve managed settings through each provider's native SDK/runtime implementation. */
1936
>
getManagedSettingsDiagnostics(): Promise<readonly IAgentHostManagedSettingsDiagnostics[]>;
1937
>
1938
>
/**
1939
>
* Probe connectivity from the agent host process to a single `url`,
1940
>
* resolving the proxy and timing DNS + reachability. Used by the "Network
1941
>
* Diagnostics" developer command.
1942
>
*/
1943
>
diagnosticsFetch(url: string): Promise<IAgentHostNetworkFetchResult>;
1944
>
1945
>
// ---- Protocol methods (sessions process protocol) ----------------------
1946
>
1947
>
/**
1948
>
* Subscribe to state at the given URI. Returns a snapshot of the current
1949
>
* state and the serverSeq at snapshot time. Subsequent actions for this
1950
>
* resource arrive via {@link onDidAction}. Registers `clientId` against
1951
>
* the resource so the server-side refcount knows who is watching, so the
1952
>
* caller does not need to invoke {@link addSubscriber} separately. Pair
1953
>
* with {@link unsubscribe} when the subscription is released.
1954
>
*/
1955
>
subscribe(resource: URI, clientId: string): Promise<IStateSnapshot>;
1956
>
1957
>
/**
1958
>
* Counterpart to {@link subscribe}. Drops `clientId` from the refcount
1959
>
* for `resource`; when the last subscriber is removed, idle session state
1960
>
* for `resource` may be evicted from the server.
1961
>
*/
1962
>
unsubscribe(resource: URI, clientId: string): void;
1963
>
1964
>
/**
1965
>
* Register `clientId` against `resource` without going through
1966
>
* {@link subscribe}. Only needed by callers that hand out snapshots
1967
>
* synchronously (e.g. the JSON-RPC handshake serving `initialSubscriptions`
1968
>
* out of the in-memory state cache); regular subscribers should call
1969
>
* {@link subscribe} instead. Counterpart cleanup is {@link unsubscribe}.
1970
>
*/
1971
>
addSubscriber(resource: URI, clientId: string): void;
1972
>
1973
>
/**
1974
>
* Fires when the server applies an action to subscribable state.
1975
>
* Clients use this alongside {@link subscribe} to keep their local
1976
>
* state in sync.
1977
>
*/
1978
>
readonly onDidAction: Event<ActionEnvelope>;
1979
>
1980
>
/**
1981
>
* Fires when the server broadcasts an ephemeral notification
1982
>
* (e.g. sessionAdded, sessionRemoved).
1983
>
*/
1984
>
readonly onDidNotification: Event<INotification>;
1985
>
1986
>
/**
1987
>
* Dispatch a client-originated action to the server. The server applies
1988
>
* it to state, triggers side effects, and echoes it back via
1989
>
* {@link onDidAction} with the client's origin for reconciliation.
1990
>
*
1991
>
* `channel` is the protocol URI string identifying the channel the action
1992
>
* targets (a session URI for session actions, terminal URI for terminal
1993
>
* actions, or {@link ROOT_STATE_URI} for root actions). Strings are used
1994
>
* rather than {@link URI} objects so that authority-less scheme URIs
1995
>
* like `ahp-root://` survive the wire format without normalization.
1996
>
*/
1997
>
dispatchAction(channel: string, action: SessionAction | ChatAction | TerminalAction | ClientChangesetAction | ClientAnnotationsAction | IRootConfigChangedAction, clientId: string, clientSeq: number): void;
1998
>
1999
>
/**
2000
>
* List the contents of a directory on the agent host's filesystem.
2001
>
* Used by the client to drive a remote folder picker before session creation.
2002
>
*/
2003
>
resourceList(uri: URI): Promise<ResourceListResult>;
2004
>
2005
>
/**
2006
>
* Read stored content by URI from the agent host (e.g. file edit snapshots,
2007
>
* or reading files from the remote filesystem).
2008
>
*/
2009
>
resourceRead(uri: URI): Promise<ResourceReadResult>;
2010
>
2011
>
/**
2012
>
* Write content to a file on the agent host's filesystem.
2013
>
* Used for undo/redo operations on file edits.
2014
>
*/
2015
>
resourceWrite(params: ResourceWriteParams): Promise<ResourceWriteResult>;
2016
>
2017
>
/**
2018
>
* Copy a resource from one URI to another on the agent host's filesystem.
2019
>
*/
2020
>
resourceCopy(params: ResourceCopyParams): Promise<ResourceCopyResult>;
2021
>
2022
>
/**
2023
>
* Delete a resource at a URI on the agent host's filesystem.
2024
>
*/
2025
>
resourceDelete(params: ResourceDeleteParams): Promise<ResourceDeleteResult>;
2026
>
2027
>
/**
2028
>
* Move (rename) a resource from one URI to another on the agent host's filesystem.
2029
>
*/
2030
>
resourceMove(params: ResourceMoveParams): Promise<ResourceMoveResult>;
2031
>
2032
>
/**
2033
>
* Resolve a resource (stat + realpath) on the agent host's filesystem.
2034
>
*/
2035
>
resourceResolve(params: ResourceResolveParams): Promise<ResourceResolveResult>;
2036
>
2037
>
/**
2038
>
* Create a directory (mkdir -p semantics) on the agent host's filesystem.
2039
>
*/
2040
>
resourceMkdir(params: ResourceMkdirParams): Promise<ResourceMkdirResult>;
2041
>
2042
>
/**
2043
>
* Create a resource watcher on the agent host's filesystem. Returns the
2044
>
* `ahp-resource-watch:/<id>` channel URI the caller subscribes to in
2045
>
* order to receive `resourceWatch/changed` events. The watcher is
2046
>
* tied to the subscriber refcount on that channel — the implementation
2047
>
* MUST hold the underlying file-system watcher for a short grace
2048
>
* period after the last unsubscribe so reconnects don't drop events.
2049
>
*/
2050
>
createResourceWatch(params: CreateResourceWatchParams): Promise<CreateResourceWatchResult>;
2051
>
2052
>
/**
2053
>
* Notify the agent service that a client subscribed to the given
2054
>
* `ahp-resource-watch:` channel so the per-watch refcount is bumped
2055
>
* (and the underlying {@link IFileService} watcher attached on the
2056
>
* first subscriber). Returns the decoded watch descriptor when the
2057
>
* channel parses successfully and the watcher is live; returns
2058
>
* `undefined` for unknown channels so the caller can surface a
2059
>
* not-found error.
2060
>
*/
2061
>
onResourceWatchSubscribed(channel: string): ResourceWatchState | undefined;
2062
>
2063
>
/**
2064
>
* Counterpart to {@link onResourceWatchSubscribed}. Decrements the
2065
>
* per-watch refcount; on the last drop the watcher is held for a
2066
>
* short grace period before disposal.
2067
>
*/
2068
>
onResourceWatchUnsubscribed(channel: string): boolean;
2069
>
}
2070
>
2071
>
/**
2072
>
* Consumer-facing connection to an agent host. Session handlers, terminal
2073
>
* contributions, and other features program against this interface.
2074
>
*
2075
>
* Implementations wrap an {@link IAgentService} and layer subscription
2076
>
* management and optimistic write-ahead on top.
2077
>
*/
2078
>
export interface IAgentConnection {
2079
>
2080
>
readonly clientId: string;
2081
>
2082
>
// ---- State subscriptions ------------------------------------------------
2083
>
readonly rootState: IAgentSubscription<RootState>;
2084
>
/**
2085
>
* Acquire a refcounted subscription to `resource`. `owner` names the
2086
>
* caller holding the reference so inspection surfaces can attribute who
2087
>
* is retaining a subscription; use a stable identifier such as the
2088
>
* acquiring class name.
2089
>
*/
2090
>
getSubscription<T extends StateComponents>(kind: T, resource: URI, owner: string): IReference<IAgentSubscription<ComponentToState[T]>>;
2091
>
getSubscriptionUnmanaged<T extends StateComponents>(kind: T, resource: URI): IAgentSubscription<ComponentToState[T]> | undefined;
2092
>
2093
>
/**
2094
>
* Returns the in-flight `createSession` Promise for `resource`, or `undefined` if no create is pending. Callers
2095
>
* that need to gate work on a racing eager `createSession` (e.g. before deciding whether to fall through to a
2096
>
* duplicate create) should await this first.
2097
>
*/
2098
>
getInflightSessionCreate(resource: URI): Promise<unknown> | undefined;
2099
>
2100
>
/**
2101
>
* Read-only descriptors of every active resource subscription on this
2102
>
* connection, for inspection/debug surfaces. Excludes the always-live
2103
>
* {@link rootState}.
2104
>
*/
2105
>
getActiveSubscriptions(): readonly IActiveSubscriptionInfo[];
2106
>
2107
>
// ---- Action dispatch ----------------------------------------------------
2108
>
/**
2109
>
* Dispatch a client-originated action. `channel` is the protocol URI
2110
>
* string identifying the channel the action targets (a session URI for
2111
>
* session actions, terminal URI for terminal actions, or
2112
>
* `ROOT_STATE_URI` for root-config actions). Strings are used rather
2113
>
* than {@link URI} objects so authority-less scheme URIs like
2114
>
* `ahp-root://` survive the wire format without normalization.
2115
>
*/
2116
>
dispatch(channel: string, action: SessionAction | ChatAction | TerminalAction | ClientChangesetAction | ClientAnnotationsAction | IRootConfigChangedAction): void;
2117
>
2118
>
// ---- Events (connection-level) ------------------------------------------
2119
>
readonly onDidNotification: Event<INotification>;
2120
>
readonly onDidAction: Event<ActionEnvelope>;
2121
>
/**
2122
>
* Fires when the host forwards an MCP server notification (e.g.
2123
>
* `notifications/tools/list_changed`) over the `mcp://` side channel.
2124
>
* The `channel` field on the notification routes the payload to the
2125
>
* matching {@link McpServerCustomization}.
2126
>
*/
2127
>
readonly onMcpNotification: Event<IMcpNotification>;
2128
>
2129
>
// ---- MCP side-channel ---------------------------------------------------
2130
>
/**
2131
>
* Send a request on an `mcp://` AHP side channel. `channel` is the
2132
>
* `mcp://` URI advertised by the matching {@link McpServerCustomization}
2133
>
* (only available while the server is `ready`). `method` is the raw MCP
2134
>
* JSON-RPC method (e.g. `tools/call`, `resources/read`,
2135
>
* `sampling/createMessage`); `params` are the JSON-RPC params (the
2136
>
* connection adds the routing envelope's `channel` field automatically).
2137
>
*
2138
>
* Rejects with an `Error` whose message begins with `Method not found`
2139
>
* when the channel is unknown or the host doesn't recognise the method.
2140
>
*/
2141
>
handleMcpRequest(channel: string, method: string, params: Record<string, unknown> | undefined): Promise<unknown>;
2142
>
2143
>
// ---- Session lifecycle --------------------------------------------------
2144
>
authenticate(params: AuthenticateParams): Promise<AuthenticateResult>;
2145
>
listSessions(): Promise<IAgentSessionMetadata[]>;
2146
>
createSession(config?: IAgentCreateSessionConfig): Promise<URI>;
2147
>
resolveSessionConfig(params: IAgentResolveSessionConfigParams): Promise<ResolveSessionConfigResult>;
2148
>
sessionConfigCompletions(params: IAgentSessionConfigCompletionsParams): Promise<SessionConfigCompletionsResult>;
2149
>
completions(params: CompletionsParams): Promise<CompletionsResult>;
2150
>
2151
>
/**
2152
>
* Trigger characters announced by the connected agent host that should
2153
>
* cause the client to issue a `completions` request when typed in a
2154
>
* user-message input. Resolves once on first request and is cached.
2155
>
*/
2156
>
getCompletionTriggerCharacters(): Promise<readonly string[]>;
2157
>
2158
>
/**
2159
>
* The host's `initialize` handshake result, exposed observably so callers
2160
>
* can derive advertised capabilities (e.g. {@link InitializeResult.terminalCommandPrefix},
2161
>
* {@link InitializeResult.completionTriggerCharacters}). `undefined` until
2162
>
* the handshake completes.
2163
>
*/
2164
>
readonly initializeResult: IObservable<InitializeResult | undefined>;
2165
>
disposeSession(session: URI): Promise<void>;
2166
>
2167
>
/**
2168
>
* Host-level network context for diagnostics (version, OS/arch, account,
2169
>
* proxy settings/env, endpoints). Runs on the agent host process (local or
2170
>
* remote), so the result reflects the environment the Copilot SDK actually
2171
>
* runs in.
2172
>
*/
2173
>
getNetworkDiagnosticsInfo(): Promise<IAgentHostNetworkDiagnosticsInfo>;
2174
>
2175
>
/** Resolve managed settings through each provider's native SDK/runtime implementation. */
2176
>
getManagedSettingsDiagnostics(): Promise<readonly IAgentHostManagedSettingsDiagnostics[]>;
2177
>
2178
>
/**
2179
>
* Probe connectivity from the agent host to a single `url`. Runs on the
2180
>
* agent host process (local or remote), so the result reflects the
2181
>
* environment the Copilot SDK actually runs in.
2182
>
*/
2183
>
diagnosticsFetch(url: string): Promise<IAgentHostNetworkFetchResult>;
2184
>
2185
>
/**
2186
>
* Create an additional peer chat inside an existing session. `chat` is a
2187
>
* client-chosen chat URI (see {@link buildChatUri}). The host adds the
2188
>
* chat to the session's catalog and publishes `session/chatAdded`.
2189
>
*/
2190
>
createChat(session: URI, chat: URI, options?: IAgentCreateChatOptions): Promise<void>;
2191
>
/** Dispose an additional chat created via {@link createChat}. */
2192
>
disposeChat(chat: URI): Promise<void>;
2193
>
2194
>
// ---- Terminal lifecycle -------------------------------------------------
2195
>
createTerminal(params: CreateTerminalParams): Promise<void>;
2196
>
disposeTerminal(terminal: URI): Promise<void>;
2197
>
2198
>
// ---- Changeset operations -----------------------------------------------
2199
>
invokeChangesetOperation(params: InvokeChangesetOperationParams): Promise<InvokeChangesetOperationResult>;
2200
>
2201
>
// ---- Filesystem operations ----------------------------------------------
2202
>
resourceList(uri: URI): Promise<ResourceListResult>;
2203
>
resourceRead(uri: URI): Promise<ResourceReadResult>;
2204
>
resourceWrite(params: ResourceWriteParams): Promise<ResourceWriteResult>;
2205
>
resourceCopy(params: ResourceCopyParams): Promise<ResourceCopyResult>;
2206
>
resourceDelete(params: ResourceDeleteParams): Promise<ResourceDeleteResult>;
2207
>
resourceMove(params: ResourceMoveParams): Promise<ResourceMoveResult>;
2208
>
resourceResolve(params: ResourceResolveParams): Promise<ResourceResolveResult>;
2209
>
resourceMkdir(params: ResourceMkdirParams): Promise<ResourceMkdirResult>;
2210
>
createResourceWatch(params: CreateResourceWatchParams): Promise<CreateResourceWatchResult>;
2211
>
/**
2212
>
* Convenience method that bundles
2213
>
* {@link createResourceWatch} + {@link subscribe} + a typed
2214
>
* {@link IFileChange}[] event stream, so consumers (notably
2215
>
* `AHPFileSystemProvider.watch`) can drive a watcher without
2216
>
* understanding the underlying channel protocol. Disposing the
2217
>
* returned handle unsubscribes.
2218
>
*/
2219
>
watchResource(params: CreateResourceWatchParams): Promise<IRemoteWatchHandle>;
2220
>
}
2221
>
2222
>
export const IAgentHostService = createDecorator<IAgentHostService>('agentHostService');
2223
>
2224
>
/**
2225
>
* The local wrapper around the agent host process (manages lifecycle, restart,
2226
>
* exposes the proxied service). Consumed by the main process and workbench.
2227
>
*/
2228
>
export interface IAgentHostService extends IAgentConnection {
2229
>
2230
>
readonly _serviceBrand: undefined;
2231
>
2232
>
readonly onAgentHostExit: Event<number>;
2233
>
readonly onAgentHostStart: Event<void>;
2234
>
2235
>
/**
2236
>
* `true` while we are in the middle of authenticating against the local
2237
>
* agent host (resolving tokens for any advertised `protectedResources` and
2238
>
* pushing them via {@link authenticate}). Defaults to `true` at startup so
2239
>
* that the period before the first auth pass is also covered.
2240
>
*
2241
>
* Producers (the workbench `AgentHostContribution`) flip this around their
2242
>
* auth pass; consumers (e.g. the local sessions provider) read it to mark
2243
>
* sessions as still loading.
2244
>
*/
2245
>
readonly authenticationPending: IObservable<boolean>;
2246
>
2247
>
/** Update {@link authenticationPending}. Internal — only the auth driver should call this. */
2248
>
setAuthenticationPending(pending: boolean): void;
2249
>
2250
>
restartAgentHost(): Promise<void>;
2251
>
2252
>
startWebSocketServer(): Promise<IAgentHostSocketInfo>;
2253
>
2254
>
/**
2255
>
* Get inspector listener info for the agent host process. If the inspector
2256
>
* is not currently active and `tryEnable` is true, opens the inspector on
2257
>
* a random local port. Returns `undefined` if the inspector cannot be
2258
>
* enabled.
2259
>
*/
2260
>
getInspectInfo(tryEnable: boolean): Promise<IAgentHostInspectInfo | undefined>;
2261
>
}