@microsoft/copilot-sdk 0.0.0-stage → 2.0.0-preview.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2531 -2
- package/dist/canvas.d.ts +135 -0
- package/dist/canvas.js +51 -0
- package/dist/cjs/canvas.js +77 -0
- package/dist/cjs/cliVersion.js +31 -0
- package/dist/cjs/client.js +3941 -0
- package/dist/cjs/copilotRequestHandler.js +815 -0
- package/dist/cjs/decisions.js +139 -0
- package/dist/cjs/entra.js +83 -0
- package/dist/cjs/extension.js +79 -0
- package/dist/cjs/ffiRuntimeHost.js +400 -0
- package/dist/cjs/generated/lifecycle-diagnostics.js +16 -0
- package/dist/cjs/generated/rpc.js +5883 -0
- package/dist/cjs/generated/session-events.js +16 -0
- package/dist/cjs/host.js +83 -0
- package/dist/cjs/index.js +100 -0
- package/dist/cjs/installationConfirmation.js +98 -0
- package/dist/cjs/jsonrpcTypes.js +41 -0
- package/dist/cjs/localModelJson.js +103 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/providerConfiguration.js +39 -0
- package/dist/cjs/rpcCancellation.js +49 -0
- package/dist/cjs/runtimeArtifacts.js +255 -0
- package/dist/cjs/schema.js +40 -0
- package/dist/cjs/sdkProtocolVersion.js +33 -0
- package/dist/cjs/session.js +2764 -0
- package/dist/cjs/sessionFsProvider.js +283 -0
- package/dist/cjs/taskAnalyticsJson.js +47 -0
- package/dist/cjs/telemetry.js +35 -0
- package/dist/cjs/toolSet.js +107 -0
- package/dist/cjs/types.js +204 -0
- package/dist/cjs/workflow.js +278 -0
- package/dist/cliVersion.d.ts +2 -0
- package/dist/cliVersion.js +6 -0
- package/dist/client.d.ts +576 -0
- package/dist/client.js +3924 -0
- package/dist/copilotRequestHandler.d.ts +91 -0
- package/dist/copilotRequestHandler.js +787 -0
- package/dist/decisions.d.ts +65 -0
- package/dist/decisions.js +113 -0
- package/dist/entra.d.ts +3 -0
- package/dist/entra.js +59 -0
- package/dist/extension.d.ts +69 -0
- package/dist/extension.js +59 -0
- package/dist/ffiRuntimeHost.d.ts +44 -0
- package/dist/ffiRuntimeHost.js +366 -0
- package/dist/generated/lifecycle-diagnostics.d.ts +232 -0
- package/dist/generated/lifecycle-diagnostics.js +0 -0
- package/dist/generated/rpc.d.ts +47706 -0
- package/dist/generated/rpc.js +5854 -0
- package/dist/generated/session-events.d.ts +17349 -0
- package/dist/generated/session-events.js +0 -0
- package/dist/host.d.ts +143 -0
- package/dist/host.js +59 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +74 -0
- package/dist/installationConfirmation.d.ts +19 -0
- package/dist/installationConfirmation.js +74 -0
- package/dist/jsonrpcTypes.d.ts +16 -0
- package/dist/jsonrpcTypes.js +17 -0
- package/dist/localModelJson.d.ts +1 -0
- package/dist/localModelJson.js +69 -0
- package/dist/providerConfiguration.d.ts +3 -0
- package/dist/providerConfiguration.js +15 -0
- package/dist/rpcCancellation.d.ts +3 -0
- package/dist/rpcCancellation.js +25 -0
- package/dist/runtimeArtifacts.d.ts +18 -0
- package/dist/runtimeArtifacts.js +233 -0
- package/dist/schema.d.ts +4 -0
- package/dist/schema.js +14 -0
- package/dist/sdkProtocolVersion.d.ts +10 -0
- package/dist/sdkProtocolVersion.js +8 -0
- package/dist/session.d.ts +524 -0
- package/dist/session.js +2751 -0
- package/dist/sessionFsProvider.d.ts +130 -0
- package/dist/sessionFsProvider.js +257 -0
- package/dist/taskAnalyticsJson.d.ts +8 -0
- package/dist/taskAnalyticsJson.js +12 -0
- package/dist/telemetry.d.ts +14 -0
- package/dist/telemetry.js +11 -0
- package/dist/toolSet.d.ts +75 -0
- package/dist/toolSet.js +82 -0
- package/dist/types.d.ts +3864 -0
- package/dist/types.js +169 -0
- package/dist/workflow.d.ts +413 -0
- package/dist/workflow.js +248 -0
- package/docs/agent-author.md +372 -0
- package/docs/examples.md +747 -0
- package/docs/extensions.md +121 -0
- package/docs/workflows.md +303 -0
- package/package.json +135 -5
package/dist/types.d.ts
ADDED
|
@@ -0,0 +1,3864 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Type definitions for the Copilot SDK
|
|
3
|
+
*/
|
|
4
|
+
import type { Canvas } from "./canvas.js";
|
|
5
|
+
import type { SessionFsProvider } from "./sessionFsProvider.js";
|
|
6
|
+
import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
|
|
7
|
+
import type { InstallationConfirmationHandler } from "./installationConfirmation.js";
|
|
8
|
+
export type { InstallationConfirmationHandler } from "./installationConfirmation.js";
|
|
9
|
+
import type { AgentModelPolicy, AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, ModelProviderRef, PermissionMode, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
|
|
10
|
+
import type { CopilotSession } from "./session.js";
|
|
11
|
+
import type { JsonValue } from "./workflow.js";
|
|
12
|
+
import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, FusionTier, AutopilotOptions, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, HostDiagnostics, ModelBillingTokenPrices, DiagnosticsConfiguration, OpenCanvasInstance, NamedProviderConfig as GeneratedNamedProviderConfig, ProviderConfigType, ProtocolExternalToolNamespace, CurrentToolMetadata, NetworkAuthenticateBasicRequest, NetworkAuthenticateBasicResult, NetworkAuthenticateNegotiateRequest, NetworkResolveProxyRequest, NetworkScope, SandboxConfig, SessionManagementCreateHostRequest, SessionManagementCreateResult } from "./generated/rpc.js";
|
|
13
|
+
import type { ToolSet } from "./toolSet.js";
|
|
14
|
+
export type { NetworkAuthenticateBasicRequest, NetworkAuthenticateBasicResult, NetworkAuthenticateNegotiateRequest, NetworkResolveProxyRequest, NetworkScope, } from "./generated/rpc.js";
|
|
15
|
+
export type { RemoteSessionMode } from "./generated/rpc.js";
|
|
16
|
+
export type { AutopilotOptions } from "./generated/rpc.js";
|
|
17
|
+
export type { CurrentToolMetadata } from "./generated/rpc.js";
|
|
18
|
+
export type { SandboxConfig, SandboxConfigSource } from "./generated/rpc.js";
|
|
19
|
+
export type { ManagedSessionInfo, SessionManagementCloseRequest, SessionManagementCloseResult, SessionManagementConfigureRequest, SessionManagementCreateHostRequest, SessionManagementCreateRequest, SessionManagementCreateResult, SessionManagementListRequest, SessionManagementListResult, SessionManagementMessageRequest, SessionManagementMessageResult, SessionManagementPolicy, SessionManagementScope, SessionManagementToolOverrides, } from "./generated/rpc.js";
|
|
20
|
+
/**
|
|
21
|
+
* Creates and supervises a separate session for this session's management tools.
|
|
22
|
+
* Use newSessionId as the child's exact identity and apply the requested launch
|
|
23
|
+
* options and permission ceiling. Route approvals independently, retain the new
|
|
24
|
+
* session, and dispose it with the host. Do not copy the parent's conversation.
|
|
25
|
+
*/
|
|
26
|
+
export type SessionCreationHandler = (request: SessionManagementCreateHostRequest, options: {
|
|
27
|
+
signal: AbortSignal;
|
|
28
|
+
}) => SessionManagementCreateResult | Promise<SessionManagementCreateResult>;
|
|
29
|
+
export type { AuthIdentityMetadata, AuthInfoType, ConnectorAccountRequest, ConnectorAvailability, ConnectorCapabilities, ConnectorCatalogEntry, ConnectorCatalogResult, ConnectorCatalogStatus, ConnectorConnectRequest, ConnectorConnectResult, ConnectorContinueRequest, ConnectorDisconnectResult, ConnectorMcpStatus, ConnectorReconcileRequest, ConnectorRuntimeStatus, ConnectorSessionAccount, ConnectorSessionAccountResult, ConnectorStatus, ExtensionLaunchProfile, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, HostDiagnostics, HostErrorReportingStatus, InstallationConfirmationRequest, InstallationConfirmationResponse, InstallationDecision, InstallationReview, McpInstallationReview, } from "./generated/rpc.js";
|
|
30
|
+
/**
|
|
31
|
+
* Arguments passed to a session's {@link GitHubTokenProvider}.
|
|
32
|
+
*
|
|
33
|
+
* The callback registration identifier is intentionally kept inside the SDK.
|
|
34
|
+
*/
|
|
35
|
+
export type GitHubTokenProviderArgs = Pick<GitHubTokenAcquireRequest, "host" | "sessionId" | "reason">;
|
|
36
|
+
/** Tagged token or cancellation returned by a {@link GitHubTokenProvider}. */
|
|
37
|
+
export type GitHubTokenProviderResult = GitHubTokenAcquireResult;
|
|
38
|
+
/**
|
|
39
|
+
* Acquires a GitHub token for one session.
|
|
40
|
+
*
|
|
41
|
+
* A token result must include `expiresIn`: the number of seconds of remaining
|
|
42
|
+
* lifetime when the callback completes. More than one hour must still remain
|
|
43
|
+
* after the runtime validates the token. Production GitHub tokens
|
|
44
|
+
* typically last eight hours. Initial cancellation, callback errors, and
|
|
45
|
+
* invalid token responses reject session creation or resume instead of falling
|
|
46
|
+
* back to ambient authentication.
|
|
47
|
+
*/
|
|
48
|
+
export type GitHubTokenProvider = (args: GitHubTokenProviderArgs) => GitHubTokenProviderResult | Promise<GitHubTokenProviderResult>;
|
|
49
|
+
export type { ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, } from "./generated/rpc.js";
|
|
50
|
+
export type SessionEvent = Exclude<GeneratedSessionEvent, {
|
|
51
|
+
type: "permission.requested";
|
|
52
|
+
}> | PermissionRequestedEvent;
|
|
53
|
+
export type { AutoTier, ReasoningSummary } from "./generated/session-events.js";
|
|
54
|
+
export type { CurrentModel, FusionTier, ModelSwitchAutoTierResult, ModelSwitchAutoTierStatus, } from "./generated/rpc.js";
|
|
55
|
+
export type { SessionFsProvider } from "./sessionFsProvider.js";
|
|
56
|
+
export { createSessionFsAdapter } from "./sessionFsProvider.js";
|
|
57
|
+
export type { SessionFsFileInfo } from "./sessionFsProvider.js";
|
|
58
|
+
export type { SessionFsByteRange } from "./sessionFsProvider.js";
|
|
59
|
+
export type { SessionFsSqliteQueryResult } from "./sessionFsProvider.js";
|
|
60
|
+
export type { SessionFsSqliteQueryType } from "./sessionFsProvider.js";
|
|
61
|
+
export type { SessionFsSqliteProvider } from "./sessionFsProvider.js";
|
|
62
|
+
export type { SessionFsSqliteStatement } from "./sessionFsProvider.js";
|
|
63
|
+
export type { SessionFsSqliteTransactionErrorClass } from "./sessionFsProvider.js";
|
|
64
|
+
export { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
|
|
65
|
+
export { SessionFsWriteFailure } from "./sessionFsProvider.js";
|
|
66
|
+
export type { LlmInferenceHeaders } from "./generated/rpc.js";
|
|
67
|
+
import type { SkillProviderDescriptor } from "./generated/rpc.js";
|
|
68
|
+
export type { SkillProviderDescriptor };
|
|
69
|
+
export type { PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSurface, PermissionResponseCapability, } from "./generated/rpc.js";
|
|
70
|
+
export type { PermissionDecisionSource } from "./generated/session-events.js";
|
|
71
|
+
export type { CopilotRequestContext } from "./copilotRequestHandler.js";
|
|
72
|
+
export { CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, } from "./copilotRequestHandler.js";
|
|
73
|
+
/**
|
|
74
|
+
* Options for creating a CopilotClient
|
|
75
|
+
*/
|
|
76
|
+
/**
|
|
77
|
+
* W3C Trace Context headers used for distributed trace propagation.
|
|
78
|
+
*/
|
|
79
|
+
export interface TraceContext {
|
|
80
|
+
traceparent?: string;
|
|
81
|
+
tracestate?: string;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Callback that returns the current W3C Trace Context.
|
|
85
|
+
* Wire this up to your OpenTelemetry (or other tracing) SDK to enable
|
|
86
|
+
* distributed trace propagation between your app and the Copilot CLI.
|
|
87
|
+
*/
|
|
88
|
+
export type TraceContextProvider = () => TraceContext | Promise<TraceContext>;
|
|
89
|
+
/**
|
|
90
|
+
* Configuration for OpenTelemetry instrumentation.
|
|
91
|
+
*
|
|
92
|
+
* When provided via {@link CopilotClientOptions.telemetry}, the SDK sets
|
|
93
|
+
* the corresponding startup configuration on the owned runtime, including
|
|
94
|
+
* in-process hosts, without changing the application's environment.
|
|
95
|
+
*/
|
|
96
|
+
export interface TelemetryConfig {
|
|
97
|
+
/** OTLP HTTP endpoint URL for trace/metric export. Sets OTEL_EXPORTER_OTLP_ENDPOINT. */
|
|
98
|
+
otlpEndpoint?: string;
|
|
99
|
+
/** OTLP HTTP protocol for all signals. Sets OTEL_EXPORTER_OTLP_PROTOCOL. */
|
|
100
|
+
otlpProtocol?: "http/json" | "http/protobuf";
|
|
101
|
+
/** File path for JSON-lines trace output. Sets COPILOT_OTEL_FILE_EXPORTER_PATH. */
|
|
102
|
+
filePath?: string;
|
|
103
|
+
/** Exporter backend type: "otlp-http" or "file". Sets COPILOT_OTEL_EXPORTER_TYPE. */
|
|
104
|
+
exporterType?: string;
|
|
105
|
+
/** Instrumentation scope name. Sets COPILOT_OTEL_SOURCE_NAME. */
|
|
106
|
+
sourceName?: string;
|
|
107
|
+
/** Whether to capture span content. Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_CONTENT and its legacy boolean alias. */
|
|
108
|
+
captureContent?: boolean;
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Configures how a {@link CopilotClient} connects to the Copilot runtime.
|
|
112
|
+
* Construct via the factory functions on {@link RuntimeConnection}.
|
|
113
|
+
*/
|
|
114
|
+
export type RuntimeConnection = StdioRuntimeConnection | InProcessRuntimeConnection | TcpRuntimeConnection | UriRuntimeConnection;
|
|
115
|
+
/**
|
|
116
|
+
* Shared shape for the transports that spawn a runtime **child process**
|
|
117
|
+
* ({@link StdioRuntimeConnection} and {@link TcpRuntimeConnection}).
|
|
118
|
+
*/
|
|
119
|
+
export interface ChildProcessRuntimeConnection {
|
|
120
|
+
/** Path to the runtime executable. When omitted, the bundled runtime is used. */
|
|
121
|
+
readonly path?: string;
|
|
122
|
+
/** Extra command-line arguments to pass to the runtime process. */
|
|
123
|
+
readonly args?: readonly string[];
|
|
124
|
+
/**
|
|
125
|
+
* Environment variables for the spawned runtime child process, replacing the
|
|
126
|
+
* inherited environment. Cannot be combined with
|
|
127
|
+
* {@link CopilotClientOptions.env}; setting both throws when the client is
|
|
128
|
+
* constructed. When omitted, the client-level env (or `process.env`) is used.
|
|
129
|
+
*/
|
|
130
|
+
readonly env?: Record<string, string>;
|
|
131
|
+
}
|
|
132
|
+
/**
|
|
133
|
+
* Spawns a runtime child process and communicates over its stdin/stdout.
|
|
134
|
+
* Select this explicitly when the runtime needs a separate process.
|
|
135
|
+
*/
|
|
136
|
+
export interface StdioRuntimeConnection extends ChildProcessRuntimeConnection {
|
|
137
|
+
readonly kind: "stdio";
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Hosts the runtime in-process by loading the native runtime library and speaking
|
|
141
|
+
* JSON-RPC over its C ABI (FFI), instead of spawning a runtime child process. The
|
|
142
|
+
* native runtime runs in the application's process. Construct via
|
|
143
|
+
* {@link RuntimeConnection.forInProcess}.
|
|
144
|
+
*
|
|
145
|
+
* This is the default transport. Typed authentication, {@link CopilotClientOptions.telemetry} and
|
|
146
|
+
* {@link CopilotClientOptions.baseDirectory} are host-scoped.
|
|
147
|
+
* `env` and `workingDirectory` are unsupported; use
|
|
148
|
+
* per-session working directories.
|
|
149
|
+
*/
|
|
150
|
+
export interface InProcessRuntimeConnection {
|
|
151
|
+
readonly kind: "inprocess";
|
|
152
|
+
/**
|
|
153
|
+
* Schedule the supplied native action exactly once on the host's UI thread
|
|
154
|
+
* (the process main thread on macOS), completing only after it returns.
|
|
155
|
+
* The action can block while native UI is open. No authentication data crosses
|
|
156
|
+
* this callback. Other in-process clients can share this process-wide capability.
|
|
157
|
+
*
|
|
158
|
+
* Required for OneAuth interactive authentication on macOS. This general-purpose
|
|
159
|
+
* scheduler may also be used for other runtime-owned native UI operations.
|
|
160
|
+
* Temporary OneAuth workaround; this API may be removed if no longer needed.
|
|
161
|
+
* @experimental
|
|
162
|
+
*/
|
|
163
|
+
readonly runOnUiThread?: (action: () => void) => void | Promise<void>;
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* Spawns a runtime child process that listens on a TCP socket and connects to it.
|
|
167
|
+
*/
|
|
168
|
+
export interface TcpRuntimeConnection extends ChildProcessRuntimeConnection {
|
|
169
|
+
readonly kind: "tcp";
|
|
170
|
+
/**
|
|
171
|
+
* TCP port to listen on. `0` (the default) auto-allocates a free port.
|
|
172
|
+
* If the chosen port is already in use, startup fails.
|
|
173
|
+
*/
|
|
174
|
+
readonly port?: number;
|
|
175
|
+
/**
|
|
176
|
+
* Optional shared secret the SDK sends to the spawned runtime to authenticate
|
|
177
|
+
* the TCP connection. When omitted, a UUID is generated automatically so the
|
|
178
|
+
* loopback listener is safe by default.
|
|
179
|
+
*/
|
|
180
|
+
readonly connectionToken?: string;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Connects to an already-running runtime at the specified URL. The SDK does not
|
|
184
|
+
* spawn a process in this mode.
|
|
185
|
+
*/
|
|
186
|
+
export interface UriRuntimeConnection {
|
|
187
|
+
readonly kind: "uri";
|
|
188
|
+
/**
|
|
189
|
+
* URL of the runtime to connect to. Accepts `"port"`, `"host:port"`, or a
|
|
190
|
+
* full URL (`"http://host:port"`).
|
|
191
|
+
*/
|
|
192
|
+
readonly url: string;
|
|
193
|
+
/** Optional shared secret to authenticate the connection. */
|
|
194
|
+
readonly connectionToken?: string;
|
|
195
|
+
}
|
|
196
|
+
/** Factory functions for constructing {@link RuntimeConnection} instances. */
|
|
197
|
+
export declare const RuntimeConnection: {
|
|
198
|
+
/**
|
|
199
|
+
* Spawn a runtime child process and communicate over its stdin/stdout.
|
|
200
|
+
*/
|
|
201
|
+
readonly forStdio: (opts?: {
|
|
202
|
+
path?: string;
|
|
203
|
+
args?: readonly string[];
|
|
204
|
+
env?: Record<string, string>;
|
|
205
|
+
}) => StdioRuntimeConnection;
|
|
206
|
+
/**
|
|
207
|
+
* Spawn a runtime child process that listens on a TCP socket and connect to it.
|
|
208
|
+
*/
|
|
209
|
+
readonly forTcp: (opts?: {
|
|
210
|
+
port?: number;
|
|
211
|
+
connectionToken?: string;
|
|
212
|
+
path?: string;
|
|
213
|
+
args?: readonly string[];
|
|
214
|
+
env?: Record<string, string>;
|
|
215
|
+
}) => TcpRuntimeConnection;
|
|
216
|
+
/**
|
|
217
|
+
* Connect to an already-running runtime at the given URL. The SDK does not
|
|
218
|
+
* spawn a process in this mode.
|
|
219
|
+
*/
|
|
220
|
+
readonly forUri: (url: string, opts?: {
|
|
221
|
+
connectionToken?: string;
|
|
222
|
+
}) => UriRuntimeConnection;
|
|
223
|
+
/**
|
|
224
|
+
* Host the runtime in-process over the native runtime library's C ABI (FFI).
|
|
225
|
+
*
|
|
226
|
+
* The default when no connection or environment override is supplied.
|
|
227
|
+
* Runtime configuration from `gitHubToken`, `telemetry` and
|
|
228
|
+
* `baseDirectory` is scoped to this host, not the process environment.
|
|
229
|
+
* Client-level `env` and `workingDirectory` are unsupported.
|
|
230
|
+
*/
|
|
231
|
+
readonly forInProcess: (options?: Pick<InProcessRuntimeConnection, "runOnUiThread">) => InProcessRuntimeConnection;
|
|
232
|
+
};
|
|
233
|
+
/**
|
|
234
|
+
* Controls SDK defaults for ambient features.
|
|
235
|
+
*
|
|
236
|
+
* - `"coding-agent"`: Defaults equivalent to Copilot CLI. Useful when
|
|
237
|
+
* building a coding agent that shares sessions with Copilot CLI. Do not use
|
|
238
|
+
* this mode for server-based multi-user applications — the default coding
|
|
239
|
+
* agent has tools and capabilities that operate across sessions and can
|
|
240
|
+
* access the host OS environment.
|
|
241
|
+
* - `"empty"`: Disables optional features by default. The app must explicitly
|
|
242
|
+
* opt into anything it needs. Required for any scenario where CLI-like
|
|
243
|
+
* ambient behavior is unsafe (e.g. multi-user servers).
|
|
244
|
+
*/
|
|
245
|
+
export type CopilotClientMode = "empty" | "coding-agent";
|
|
246
|
+
/**
|
|
247
|
+
* Identity of the integrating application, declared once on the `server.connect`
|
|
248
|
+
* handshake so the telemetry the runtime emits on this connection is attributed
|
|
249
|
+
* to a single, consistent surface rather than to the runtime's own build.
|
|
250
|
+
*
|
|
251
|
+
* All fields are optional; omit any of them (or the whole object) to keep the
|
|
252
|
+
* runtime's default attribution. Version fields are ignored by the runtime
|
|
253
|
+
* unless they look like a version string.
|
|
254
|
+
*/
|
|
255
|
+
export interface CopilotClientInfo {
|
|
256
|
+
/**
|
|
257
|
+
* Name of the application using the SDK, e.g. `"acme-developer-portal"`.
|
|
258
|
+
*/
|
|
259
|
+
applicationName?: string;
|
|
260
|
+
/**
|
|
261
|
+
* Version of the application using the SDK, e.g. `"2.4.0"`.
|
|
262
|
+
*/
|
|
263
|
+
applicationVersion?: string;
|
|
264
|
+
/**
|
|
265
|
+
* Optional name of a specific integration within the application, such as an extension or plugin.
|
|
266
|
+
*/
|
|
267
|
+
integrationName?: string;
|
|
268
|
+
/**
|
|
269
|
+
* Optional version of the integration identified by `integrationName`.
|
|
270
|
+
*/
|
|
271
|
+
integrationVersion?: string;
|
|
272
|
+
}
|
|
273
|
+
/** Host application's Microsoft Entra registration. @experimental */
|
|
274
|
+
export type EntraAuthConfig = Pick<import("./generated/rpc.js").EntraAuthConfig, "clientId" | "matsAppName">;
|
|
275
|
+
/** Host-owned Entra identity or resource acquisition. @experimental */
|
|
276
|
+
export type EntraTokenProviderArgs = import("./generated/rpc.js").EntraTokenAcquireRequest;
|
|
277
|
+
/** Response matching the requested acquisition kind and pinned account. @experimental */
|
|
278
|
+
export type EntraTokenProviderResult = import("./generated/rpc.js").EntraTokenAcquireResult;
|
|
279
|
+
/**
|
|
280
|
+
* Selects/revalidates an identity or acquires its resource token. Renewal must be
|
|
281
|
+
* silent and account-pinned. Cancellation and unavailability never open runtime sign-in.
|
|
282
|
+
* The cancellation token fires when the request or original connection ends.
|
|
283
|
+
* @experimental
|
|
284
|
+
*/
|
|
285
|
+
export type EntraTokenProvider = (request: EntraTokenProviderArgs, cancellation: import("./jsonrpcTypes.js").CancellationToken) => EntraTokenProviderResult | Promise<EntraTokenProviderResult>;
|
|
286
|
+
/** Entra application and optional host-owned acquisition. @experimental */
|
|
287
|
+
export interface EntraAuthOptions extends EntraAuthConfig {
|
|
288
|
+
/** Host-owned acquisition; omission retains built-in runtime authentication. @experimental */
|
|
289
|
+
tokenProvider?: EntraTokenProvider;
|
|
290
|
+
}
|
|
291
|
+
export interface CopilotClientOptions {
|
|
292
|
+
/**
|
|
293
|
+
* Host application's Microsoft Entra registration, shared by its sessions.
|
|
294
|
+
* Required for built-in Entra sign-in and token renewal; other authentication methods remain available.
|
|
295
|
+
* @experimental
|
|
296
|
+
*/
|
|
297
|
+
entra?: EntraAuthOptions;
|
|
298
|
+
/**
|
|
299
|
+
* How to connect to the Copilot runtime. When omitted, defaults to
|
|
300
|
+
* {@link RuntimeConnection.forStdio} with the bundled runtime.
|
|
301
|
+
*/
|
|
302
|
+
connection?: RuntimeConnection;
|
|
303
|
+
/**
|
|
304
|
+
* Selects the SDK defaulting strategy. See {@link CopilotClientMode}.
|
|
305
|
+
*
|
|
306
|
+
* When set to `"empty"`, the SDK validates that the app has supplied the
|
|
307
|
+
* required configuration ({@link CopilotClientOptions.baseDirectory} or
|
|
308
|
+
* {@link CopilotClientOptions.sessionFs}, plus
|
|
309
|
+
* {@link SessionConfigBase.availableTools} on each session).
|
|
310
|
+
*
|
|
311
|
+
* Required; select `"coding-agent"` or `"empty"` explicitly.
|
|
312
|
+
*/
|
|
313
|
+
mode: CopilotClientMode;
|
|
314
|
+
/**
|
|
315
|
+
* Working directory for the runtime process.
|
|
316
|
+
* If not set, inherits the current process's working directory.
|
|
317
|
+
*/
|
|
318
|
+
workingDirectory?: string;
|
|
319
|
+
/**
|
|
320
|
+
* Base directory for Copilot data (session state, config, etc.).
|
|
321
|
+
* Sets the COPILOT_HOME environment variable on the spawned runtime.
|
|
322
|
+
* In-process hosts also keep their runtime cache in this directory's `cache` subdirectory.
|
|
323
|
+
* When not set, the runtime defaults to ~/.copilot.
|
|
324
|
+
* Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
|
|
325
|
+
*/
|
|
326
|
+
baseDirectory?: string;
|
|
327
|
+
/**
|
|
328
|
+
* Absolute paths to trusted plugin directories bundled by the host.
|
|
329
|
+
* When non-empty, the complete set is registered with the runtime during
|
|
330
|
+
* startup before any sessions can be created.
|
|
331
|
+
*/
|
|
332
|
+
builtinPluginDirectories?: readonly string[];
|
|
333
|
+
/**
|
|
334
|
+
* Connection-level extension launch profile provider.
|
|
335
|
+
* When set, the client registers the provider during startup before any
|
|
336
|
+
* session can be created.
|
|
337
|
+
*
|
|
338
|
+
* @experimental
|
|
339
|
+
*/
|
|
340
|
+
extensionLaunchProvider?: ExtensionLaunchProvider;
|
|
341
|
+
/**
|
|
342
|
+
* Network callbacks through which the SDK host decides the runtime's proxies and supplies its
|
|
343
|
+
* Kerberos tokens. Registered before sessions start.
|
|
344
|
+
* @experimental
|
|
345
|
+
*/
|
|
346
|
+
network?: NetworkConfig;
|
|
347
|
+
/**
|
|
348
|
+
* Connection-global human review for experimental installation operations.
|
|
349
|
+
* Does not register or enable installation capabilities on the runtime.
|
|
350
|
+
* @experimental
|
|
351
|
+
*/
|
|
352
|
+
installationConfirmationHandler?: InstallationConfirmationHandler;
|
|
353
|
+
/**
|
|
354
|
+
* Log level for the Copilot runtime. When omitted, the runtime uses its
|
|
355
|
+
* own default (currently `"info"`).
|
|
356
|
+
*/
|
|
357
|
+
logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
|
|
358
|
+
/**
|
|
359
|
+
* Environment variables to pass to the runtime process. If not set, inherits process.env.
|
|
360
|
+
* Unsupported with {@link RuntimeConnection.forInProcess}; use typed client/session options.
|
|
361
|
+
*/
|
|
362
|
+
env?: Record<string, string | undefined>;
|
|
363
|
+
/**
|
|
364
|
+
* GitHub token to use for authentication.
|
|
365
|
+
* When provided, the token is passed to the runtime via environment variable.
|
|
366
|
+
* This takes priority over other authentication methods.
|
|
367
|
+
*/
|
|
368
|
+
gitHubToken?: string;
|
|
369
|
+
/**
|
|
370
|
+
* Whether to use the logged-in user for authentication.
|
|
371
|
+
* When true, the runtime will attempt to use stored OAuth tokens or gh CLI auth.
|
|
372
|
+
* When false, only explicit tokens such as gitHubToken are used; environment variable
|
|
373
|
+
* tokens (COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN) are ignored.
|
|
374
|
+
* @default true (but defaults to false when gitHubToken is provided)
|
|
375
|
+
*/
|
|
376
|
+
useLoggedInUser?: boolean;
|
|
377
|
+
/**
|
|
378
|
+
* Custom handler for listing available models.
|
|
379
|
+
* When provided, client.listModels() calls this handler instead of
|
|
380
|
+
* querying the runtime. Useful in BYOK mode to return models
|
|
381
|
+
* available from your custom provider.
|
|
382
|
+
*/
|
|
383
|
+
onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
|
|
384
|
+
/**
|
|
385
|
+
* OpenTelemetry startup configuration for the owned runtime.
|
|
386
|
+
* Supports child-process and in-process hosts; omitted settings inherit
|
|
387
|
+
* the application environment and runtime policy still takes precedence.
|
|
388
|
+
*/
|
|
389
|
+
telemetry?: TelemetryConfig;
|
|
390
|
+
/**
|
|
391
|
+
* Advanced: callback that returns the current W3C Trace Context for distributed
|
|
392
|
+
* trace propagation. Most users do not need this — the {@link telemetry} config
|
|
393
|
+
* alone is sufficient to collect traces from the CLI.
|
|
394
|
+
*
|
|
395
|
+
* This callback is only useful when your application creates its own
|
|
396
|
+
* OpenTelemetry spans and you want them to appear in the **same** distributed
|
|
397
|
+
* trace as the CLI's spans. The SDK calls this before `session.create`,
|
|
398
|
+
* `session.resume`, and `session.send` RPCs to inject `traceparent`/`tracestate`
|
|
399
|
+
* into the request.
|
|
400
|
+
*
|
|
401
|
+
* @example
|
|
402
|
+
* ```typescript
|
|
403
|
+
* import { propagation, context } from "@opentelemetry/api";
|
|
404
|
+
*
|
|
405
|
+
* const client = new CopilotClient({
|
|
406
|
+
* mode: "coding-agent",
|
|
407
|
+
* onGetTraceContext: () => {
|
|
408
|
+
* const carrier: Record<string, string> = {};
|
|
409
|
+
* propagation.inject(context.active(), carrier);
|
|
410
|
+
* return carrier;
|
|
411
|
+
* },
|
|
412
|
+
* });
|
|
413
|
+
* ```
|
|
414
|
+
*/
|
|
415
|
+
onGetTraceContext?: TraceContextProvider;
|
|
416
|
+
/**
|
|
417
|
+
* Custom session filesystem provider.
|
|
418
|
+
* When provided, the client registers as the session filesystem provider
|
|
419
|
+
* on connection, routing all session-scoped file I/O through these callbacks
|
|
420
|
+
* instead of the server's default local filesystem storage.
|
|
421
|
+
*/
|
|
422
|
+
sessionFs?: SessionFsConfig;
|
|
423
|
+
/**
|
|
424
|
+
* Custom handler for outbound model-layer requests (experimental).
|
|
425
|
+
*
|
|
426
|
+
* When provided, the client registers as the runtime's request handler
|
|
427
|
+
* on connection: every outbound model-layer request the runtime would
|
|
428
|
+
* otherwise have issued itself — plain HTTP, streaming SSE, and
|
|
429
|
+
* WebSocket — is dispatched back to the handler over JSON-RPC. The
|
|
430
|
+
* handler returns the response verbatim, exactly as if the runtime had
|
|
431
|
+
* issued the request itself.
|
|
432
|
+
*
|
|
433
|
+
* Subclass {@link CopilotRequestHandler} and override the hooks you need;
|
|
434
|
+
* an instance that overrides nothing is a transparent pass-through.
|
|
435
|
+
*
|
|
436
|
+
* v1 notes:
|
|
437
|
+
* - HTTP (buffered and streaming SSE) and WebSocket transports are all
|
|
438
|
+
* intercepted. The handler receives a `transport` discriminator on the
|
|
439
|
+
* {@link CopilotRequestContext} for both.
|
|
440
|
+
* - The handler is set process-globally on the runtime; the same
|
|
441
|
+
* handler is invoked for every session created on this client.
|
|
442
|
+
*
|
|
443
|
+
* @experimental
|
|
444
|
+
*/
|
|
445
|
+
requestHandler?: CopilotRequestHandler;
|
|
446
|
+
/**
|
|
447
|
+
* Experimental. Receives GitHub telemetry events the runtime forwards to
|
|
448
|
+
* this connection. When set, the client opts each session it creates or
|
|
449
|
+
* resumes into telemetry forwarding and dispatches each
|
|
450
|
+
* `gitHubTelemetry.event` notification to this connection-global handler;
|
|
451
|
+
* each {@link GitHubTelemetryNotification} carries its originating
|
|
452
|
+
* `sessionId`.
|
|
453
|
+
*
|
|
454
|
+
* @experimental
|
|
455
|
+
*/
|
|
456
|
+
onGitHubTelemetry?: (notification: GitHubTelemetryNotification) => void | Promise<void>;
|
|
457
|
+
/**
|
|
458
|
+
* Server-wide idle timeout for sessions in seconds.
|
|
459
|
+
* Sessions without activity for this duration are automatically cleaned up.
|
|
460
|
+
* Set to 0 or omit to disable (sessions live indefinitely).
|
|
461
|
+
* Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
|
|
462
|
+
* @default undefined (disabled)
|
|
463
|
+
*/
|
|
464
|
+
sessionIdleTimeoutSeconds?: number;
|
|
465
|
+
/**
|
|
466
|
+
* Identity of the integrating application, forwarded to the runtime on the
|
|
467
|
+
* `server.connect` handshake. Declaring it lets the telemetry the runtime
|
|
468
|
+
* emits on this connection be attributed to a single, consistent surface
|
|
469
|
+
* (e.g. the application and its Copilot integration) instead of the
|
|
470
|
+
* runtime's own build. All fields are optional; omit it to keep the default
|
|
471
|
+
* attribution.
|
|
472
|
+
*/
|
|
473
|
+
clientInfo?: CopilotClientInfo;
|
|
474
|
+
}
|
|
475
|
+
/** Resolves launch profiles for extension entrypoints discovered by the runtime. */
|
|
476
|
+
export type ExtensionLaunchProvider = GeneratedExtensionLaunchProvider;
|
|
477
|
+
/**
|
|
478
|
+
* Network callbacks through which the SDK host takes over parts of the runtime's networking, for
|
|
479
|
+
* example when the runtime runs in WSL or a container and should use VS Code's proxy settings, proxy
|
|
480
|
+
* credentials and the host's Kerberos tickets. Each registered callback replaces the runtime's own
|
|
481
|
+
* handling for the traffic in {@link NetworkConfig.scope}; without it, the runtime handles that part
|
|
482
|
+
* itself.
|
|
483
|
+
*
|
|
484
|
+
* Each callback receives a `signal` that aborts when the runtime stops waiting: it cancels the
|
|
485
|
+
* request (for example when its wait times out) or the connection closes. The SDK then stops
|
|
486
|
+
* awaiting the callback and ignores any later result.
|
|
487
|
+
* @experimental
|
|
488
|
+
*/
|
|
489
|
+
export interface NetworkConfig {
|
|
490
|
+
/**
|
|
491
|
+
* `connection` (the default) serves only requests made for sessions this client creates or resumes;
|
|
492
|
+
* `runtime` also serves the runtime's shared background traffic. Only one connection at a time can
|
|
493
|
+
* hold `runtime` scope, so startup fails if another client holds it. The registration ends when the
|
|
494
|
+
* connection closes.
|
|
495
|
+
*/
|
|
496
|
+
scope?: NetworkScope;
|
|
497
|
+
/**
|
|
498
|
+
* Returns the proxies for `request.url` as a PAC-style list such as
|
|
499
|
+
* `PROXY proxy.example:8080; HTTPS proxy.example:443; DIRECT` (the format of Electron's
|
|
500
|
+
* `session.resolveProxy`); return `DIRECT` for a direct connection, or `undefined` to let the runtime
|
|
501
|
+
* resolve the proxy itself, as if no callback were registered. Entry types the runtime doesn't
|
|
502
|
+
* support, such as SOCKS and QUIC, are skipped.
|
|
503
|
+
* `request.url` is the request target as a PAC script sees it: without credentials or fragment, and for
|
|
504
|
+
* `https` and `wss` also without path and query.
|
|
505
|
+
*
|
|
506
|
+
* The callback decides every request that would otherwise follow ambient proxy settings: proxy
|
|
507
|
+
* environment variables, `NO_PROXY` and operating-system proxy settings are not consulted unless it
|
|
508
|
+
* returns `undefined`, and a failing callback fails the request rather than connecting directly.
|
|
509
|
+
* Requests to loopback targets, and requests with an explicitly configured proxy, never consult it. The
|
|
510
|
+
* runtime caches answers, including `undefined`, for a few seconds.
|
|
511
|
+
*/
|
|
512
|
+
resolveProxy?: (request: NetworkResolveProxyRequest, signal: AbortSignal) => Promise<string | undefined>;
|
|
513
|
+
/**
|
|
514
|
+
* Returns a fresh, single-use base64 SPNEGO token without the `Negotiate ` prefix for a proxy's Negotiate
|
|
515
|
+
* challenge, or `undefined` when unavailable. The runtime then does not look up Kerberos credentials
|
|
516
|
+
* itself, so a missing token or a failing callback fails the request, unless the proxy also offers
|
|
517
|
+
* Basic and {@link NetworkConfig.authenticateBasic} supplies credentials.
|
|
518
|
+
* The SPN uses the platform-independent `service/host[@REALM]` form; validate it before issuing
|
|
519
|
+
* credentials. Never log or persist tokens.
|
|
520
|
+
*/
|
|
521
|
+
authenticateNegotiate?: (request: NetworkAuthenticateNegotiateRequest, signal: AbortSignal) => Promise<string | undefined>;
|
|
522
|
+
/**
|
|
523
|
+
* Returns credentials for a proxy's Basic challenge, or `undefined` when unavailable, which fails the
|
|
524
|
+
* request with the proxy's challenge. Applies to requests the runtime tunnels through the proxy
|
|
525
|
+
* (`https` and `wss`). The runtime remembers the answer for that proxy and uses it for later
|
|
526
|
+
* connections, until the proxy rejects it; then it calls again with `request.previousRejected` set,
|
|
527
|
+
* so answer with different credentials, for example by asking the user, or with `undefined`. A later
|
|
528
|
+
* connection sends the answer without waiting for a challenge, unless the runtime may try Negotiate
|
|
529
|
+
* with that proxy first. A connection submits at most three sets of credentials. While a call is
|
|
530
|
+
* pending, other requests through that proxy wait for its answer.
|
|
531
|
+
* When a proxy offers both Negotiate and Basic, the runtime prefers Negotiate and answers with Basic
|
|
532
|
+
* when Negotiate is unavailable or the proxy rejects it.
|
|
533
|
+
* `request.realm` comes from the proxy, so treat it as untrusted text. An empty user name also counts
|
|
534
|
+
* as unavailable; the user name must not contain a colon, neither the user name nor the password may
|
|
535
|
+
* contain control characters, and an omitted password means an empty one. The runtime does not time
|
|
536
|
+
* the callback out: a request whose own deadline passes stops waiting, but the answer is still
|
|
537
|
+
* remembered. Never log or persist credentials.
|
|
538
|
+
*/
|
|
539
|
+
authenticateBasic?: (request: NetworkAuthenticateBasicRequest, signal: AbortSignal) => Promise<NetworkAuthenticateBasicResult | undefined>;
|
|
540
|
+
}
|
|
541
|
+
/**
|
|
542
|
+
* Configuration for creating a session
|
|
543
|
+
*/
|
|
544
|
+
export type ToolResultType = "success" | "failure" | "rejected" | "denied" | "timeout";
|
|
545
|
+
export type ToolBinaryResult = {
|
|
546
|
+
data: string;
|
|
547
|
+
mimeType: string;
|
|
548
|
+
type: "image" | "resource";
|
|
549
|
+
description?: string;
|
|
550
|
+
};
|
|
551
|
+
export type ToolTelemetry = Record<string, Record<string, JsonValue> | undefined>;
|
|
552
|
+
export type ToolResultObject = {
|
|
553
|
+
textResultForLlm: string;
|
|
554
|
+
binaryResultsForLlm?: ToolBinaryResult[];
|
|
555
|
+
resultType: ToolResultType;
|
|
556
|
+
error?: string;
|
|
557
|
+
sessionLog?: string;
|
|
558
|
+
toolTelemetry?: ToolTelemetry;
|
|
559
|
+
/**
|
|
560
|
+
* Names of tools returned by a tool-search tool.
|
|
561
|
+
*/
|
|
562
|
+
toolReferences?: string[];
|
|
563
|
+
};
|
|
564
|
+
export type ToolResult = string | ToolResultObject;
|
|
565
|
+
/**
|
|
566
|
+
* GitHub repository metadata to associate with a cloud session.
|
|
567
|
+
*/
|
|
568
|
+
export interface CloudSessionRepository {
|
|
569
|
+
owner: string;
|
|
570
|
+
name: string;
|
|
571
|
+
branch?: string;
|
|
572
|
+
}
|
|
573
|
+
/**
|
|
574
|
+
* Options for creating a remote session in the cloud.
|
|
575
|
+
*/
|
|
576
|
+
export interface CloudSessionOptions {
|
|
577
|
+
repository?: CloudSessionRepository;
|
|
578
|
+
}
|
|
579
|
+
/**
|
|
580
|
+
* Content block types within an MCP CallToolResult.
|
|
581
|
+
*/
|
|
582
|
+
type McpCallToolResultTextContent = {
|
|
583
|
+
type: "text";
|
|
584
|
+
text: string;
|
|
585
|
+
};
|
|
586
|
+
type McpCallToolResultImageContent = {
|
|
587
|
+
type: "image";
|
|
588
|
+
data: string;
|
|
589
|
+
mimeType: string;
|
|
590
|
+
};
|
|
591
|
+
type McpCallToolResultResourceContent = {
|
|
592
|
+
type: "resource";
|
|
593
|
+
resource: {
|
|
594
|
+
uri: string;
|
|
595
|
+
mimeType?: string;
|
|
596
|
+
text?: string;
|
|
597
|
+
blob?: string;
|
|
598
|
+
};
|
|
599
|
+
};
|
|
600
|
+
type McpCallToolResultContent = McpCallToolResultTextContent | McpCallToolResultImageContent | McpCallToolResultResourceContent;
|
|
601
|
+
/**
|
|
602
|
+
* MCP-compatible CallToolResult type. Can be passed to
|
|
603
|
+
* {@link convertMcpCallToolResult} to produce a {@link ToolResultObject}.
|
|
604
|
+
*/
|
|
605
|
+
type McpCallToolResult = {
|
|
606
|
+
content: McpCallToolResultContent[];
|
|
607
|
+
isError?: boolean;
|
|
608
|
+
};
|
|
609
|
+
/**
|
|
610
|
+
* Converts an MCP CallToolResult into the SDK's ToolResultObject format.
|
|
611
|
+
*/
|
|
612
|
+
export declare function convertMcpCallToolResult(callResult: McpCallToolResult): ToolResultObject;
|
|
613
|
+
export interface ToolInvocation {
|
|
614
|
+
sessionId: string;
|
|
615
|
+
toolCallId: string;
|
|
616
|
+
toolName: string;
|
|
617
|
+
arguments: unknown;
|
|
618
|
+
/**
|
|
619
|
+
* Snapshot of the session's currently initialized tools. Populated by the
|
|
620
|
+
* SDK only when this invocation targets the built-in tool-search tool
|
|
621
|
+
* (`tool_search_tool`), so a tool-search override can rank/filter the live
|
|
622
|
+
* catalog — including MCP tools configured in settings — without issuing its
|
|
623
|
+
* own RPC. `undefined` for every other tool invocation.
|
|
624
|
+
*/
|
|
625
|
+
availableTools?: CurrentToolMetadata[];
|
|
626
|
+
/** W3C Trace Context traceparent from the CLI's execute_tool span. */
|
|
627
|
+
traceparent?: string;
|
|
628
|
+
/** W3C Trace Context tracestate from the CLI's execute_tool span. */
|
|
629
|
+
tracestate?: string;
|
|
630
|
+
/** Aborted when the runtime completes this request or the session disconnects. */
|
|
631
|
+
signal?: AbortSignal;
|
|
632
|
+
/**
|
|
633
|
+
* Sub-agent instance that issued this call (the `agentId` of its session
|
|
634
|
+
* events). `undefined` for a root-agent call, and for every call when the
|
|
635
|
+
* runtime does not attribute sub-agent tool calls.
|
|
636
|
+
*
|
|
637
|
+
* @experimental
|
|
638
|
+
*/
|
|
639
|
+
agentId?: string;
|
|
640
|
+
/**
|
|
641
|
+
* Runtime request id of this call: the key
|
|
642
|
+
* `session.tools.handlePendingToolCall` and `session.tools.listPendingRequests`
|
|
643
|
+
* use. A root-agent call stays answerable after the session is resumed with
|
|
644
|
+
* pending work continued; a sub-agent's call can be answered only while that
|
|
645
|
+
* sub-agent is still running.
|
|
646
|
+
*
|
|
647
|
+
* @experimental
|
|
648
|
+
*/
|
|
649
|
+
requestId?: string;
|
|
650
|
+
}
|
|
651
|
+
export type ToolHandler<TArgs = unknown> = (args: TArgs, invocation: ToolInvocation) => Promise<unknown> | unknown;
|
|
652
|
+
/**
|
|
653
|
+
* Zod-like schema interface for type inference.
|
|
654
|
+
* Any object with `toJSONSchema()` method is treated as a Zod schema.
|
|
655
|
+
*/
|
|
656
|
+
export interface ZodSchema<T = unknown> {
|
|
657
|
+
_output: T;
|
|
658
|
+
toJSONSchema(): Record<string, unknown>;
|
|
659
|
+
}
|
|
660
|
+
/**
|
|
661
|
+
* A Zod-compatible output schema that both describes and parses a typed result.
|
|
662
|
+
* TypeScript types are erased at runtime, so typed output requires a schema value.
|
|
663
|
+
*/
|
|
664
|
+
export interface ResponseSchema<T = unknown> extends ZodSchema<T> {
|
|
665
|
+
parse(value: unknown): T;
|
|
666
|
+
}
|
|
667
|
+
/**
|
|
668
|
+
* Tool definition. Parameters can be either:
|
|
669
|
+
* - A Zod schema (provides type inference for handler)
|
|
670
|
+
* - A raw JSON schema object
|
|
671
|
+
* - Omitted (no parameters)
|
|
672
|
+
*
|
|
673
|
+
* If `handler` is omitted, the SDK exposes the declaration but does not
|
|
674
|
+
* automatically invoke the tool. Consumers can resolve tool calls by observing
|
|
675
|
+
* external tool request events and calling the pending-tool RPC.
|
|
676
|
+
*/
|
|
677
|
+
export interface Tool<TArgs = unknown> {
|
|
678
|
+
name: string;
|
|
679
|
+
title?: string;
|
|
680
|
+
description?: string;
|
|
681
|
+
parameters?: ZodSchema<TArgs> | Record<string, unknown>;
|
|
682
|
+
handler?: ToolHandler<TArgs>;
|
|
683
|
+
/**
|
|
684
|
+
* When true, explicitly indicates this tool is intended to override a built-in tool
|
|
685
|
+
* of the same name. If not set and the name clashes with a built-in tool, the runtime
|
|
686
|
+
* will return an error.
|
|
687
|
+
*/
|
|
688
|
+
overridesBuiltInTool?: boolean;
|
|
689
|
+
/**
|
|
690
|
+
* When true, the tool can execute without a permission prompt.
|
|
691
|
+
*/
|
|
692
|
+
skipPermission?: boolean;
|
|
693
|
+
/**
|
|
694
|
+
* Controls whether the tool may be deferred (loaded lazily via tool search)
|
|
695
|
+
* rather than always pre-loaded. When `"auto"`, the tool can be deferred and
|
|
696
|
+
* surfaced through tool search. When `"never"`, the tool is always pre-loaded.
|
|
697
|
+
* Optional; defaults to `"auto"`.
|
|
698
|
+
*/
|
|
699
|
+
defer?: "auto" | "never";
|
|
700
|
+
/**
|
|
701
|
+
* Opaque, host-defined metadata associated with the tool definition.
|
|
702
|
+
*
|
|
703
|
+
* Keys are namespaced and are not part of the stable public API. Values are
|
|
704
|
+
* not interpreted and may be recognized to inform host-specific behavior.
|
|
705
|
+
* Unknown keys are preserved and round-tripped untouched.
|
|
706
|
+
*/
|
|
707
|
+
metadata?: Record<string, unknown>;
|
|
708
|
+
/**
|
|
709
|
+
* When true, a successful call to this tool ends the agent turn: the runtime's
|
|
710
|
+
* tool phase halts instead of feeding the tool result back to the model for
|
|
711
|
+
* another round. A failed call (for example input validation) leaves the loop
|
|
712
|
+
* running so the model can read the error and retry.
|
|
713
|
+
*
|
|
714
|
+
* Use this for tools whose whole purpose is to terminate the turn, such as a
|
|
715
|
+
* context clear that replaces the conversation the model would otherwise
|
|
716
|
+
* continue from.
|
|
717
|
+
*/
|
|
718
|
+
isTerminal?: boolean;
|
|
719
|
+
/**
|
|
720
|
+
* When true, declares that repeating a call with the same arguments has no
|
|
721
|
+
* additional effect beyond the first call, as is true of any tool without
|
|
722
|
+
* side effects. The runtime may use this to decide that a call whose outcome
|
|
723
|
+
* was lost can be safely repeated. It does not affect permission checks.
|
|
724
|
+
*/
|
|
725
|
+
idempotent?: boolean;
|
|
726
|
+
/**
|
|
727
|
+
* Groups this tool with related tools for model tool discovery.
|
|
728
|
+
*
|
|
729
|
+
* On models and providers that support native tool namespaces, deferred
|
|
730
|
+
* tools sharing a namespace are presented to the model as one group with
|
|
731
|
+
* this name and description, like the tools of an MCP server. Elsewhere,
|
|
732
|
+
* and for tools that are always loaded, the tool stays a flat function.
|
|
733
|
+
* The tool keeps its own name, so calls still reach this tool's handler
|
|
734
|
+
* by name.
|
|
735
|
+
*
|
|
736
|
+
* @experimental
|
|
737
|
+
*/
|
|
738
|
+
namespace?: ToolNamespace;
|
|
739
|
+
}
|
|
740
|
+
/**
|
|
741
|
+
* A namespace that groups related {@link Tool}s for model tool discovery.
|
|
742
|
+
* Tools sharing a name share a namespace. An invalid namespace is reported as a
|
|
743
|
+
* session warning and the tool is presented without it; a missing description
|
|
744
|
+
* defaults to a generic description of the namespace.
|
|
745
|
+
*
|
|
746
|
+
* @experimental
|
|
747
|
+
*/
|
|
748
|
+
export type ToolNamespace = ProtocolExternalToolNamespace;
|
|
749
|
+
/**
|
|
750
|
+
* Helper to define a tool with Zod schema and get type inference for the handler.
|
|
751
|
+
* Without this helper, TypeScript cannot infer handler argument types from Zod schemas.
|
|
752
|
+
*/
|
|
753
|
+
export declare function defineTool<T = unknown>(name: string, config: {
|
|
754
|
+
title?: string;
|
|
755
|
+
description?: string;
|
|
756
|
+
parameters?: ZodSchema<T> | Record<string, unknown>;
|
|
757
|
+
handler?: ToolHandler<T>;
|
|
758
|
+
overridesBuiltInTool?: boolean;
|
|
759
|
+
skipPermission?: boolean;
|
|
760
|
+
defer?: "auto" | "never";
|
|
761
|
+
metadata?: Record<string, unknown>;
|
|
762
|
+
isTerminal?: boolean;
|
|
763
|
+
idempotent?: boolean;
|
|
764
|
+
namespace?: ToolNamespace;
|
|
765
|
+
}): Tool<T>;
|
|
766
|
+
/**
|
|
767
|
+
* Non-persisted opt-in to image generation.
|
|
768
|
+
* @experimental This API may change or be removed in a future release.
|
|
769
|
+
*/
|
|
770
|
+
export interface ImageGenerationConfig {
|
|
771
|
+
/**
|
|
772
|
+
* Opt in to image generation through an authorized Copilot image model.
|
|
773
|
+
* False disables it; omission defaults to disabled on create/cold resume and
|
|
774
|
+
* preserves the setting on resident resume. Not persisted: re-supply after
|
|
775
|
+
* runtime restart. Policy, permissions, offline mode, and tool filters still
|
|
776
|
+
* apply. BYOK image generation is not supported.
|
|
777
|
+
*/
|
|
778
|
+
enabled?: boolean;
|
|
779
|
+
/**
|
|
780
|
+
* Request a visible "Made with AI" label on generated and edited images.
|
|
781
|
+
* Overrides the user's imageGenerationWatermark preference, which defaults
|
|
782
|
+
* to false. Re-supply after cold resume. Does not enable image generation
|
|
783
|
+
* or enforce enterprise policy.
|
|
784
|
+
*/
|
|
785
|
+
watermark?: boolean;
|
|
786
|
+
/**
|
|
787
|
+
* Experimental. Save generated and edited images under the session-state
|
|
788
|
+
* directory's `images` folder and give the model each path as a
|
|
789
|
+
* `saved_to:` line in the tool result. Defaults to true; set false to opt
|
|
790
|
+
* out. Subagents follow
|
|
791
|
+
* their parent's value unless they set their own. A failed save still
|
|
792
|
+
* returns the image. Sessions without a local session-state directory never
|
|
793
|
+
* save. Re-supply after cold resume. Does not enable image generation.
|
|
794
|
+
*/
|
|
795
|
+
saveToDisk?: boolean;
|
|
796
|
+
}
|
|
797
|
+
/**
|
|
798
|
+
* SDK-supplied override for the runtime's built-in tool-search behavior.
|
|
799
|
+
*
|
|
800
|
+
* Tool search lets the model discover tools on demand instead of loading every
|
|
801
|
+
* tool definition up front. When the total tool count exceeds the deferral
|
|
802
|
+
* threshold, MCP and external tools are marked as deferred and surfaced through
|
|
803
|
+
* the built-in `tool_search_tool`.
|
|
804
|
+
*
|
|
805
|
+
* To override the tool-search tool's model-facing definition and/or its
|
|
806
|
+
* execution, register a {@link Tool} named `tool_search_tool` with
|
|
807
|
+
* `overridesBuiltInTool: true`. To customize the in-prompt tool-search
|
|
808
|
+
* guidance, use the `tool_instructions` section of {@link SystemMessageConfig}
|
|
809
|
+
* in `"customize"` mode.
|
|
810
|
+
*/
|
|
811
|
+
export interface ToolSearchConfig {
|
|
812
|
+
/**
|
|
813
|
+
* Toggle to enable/disable tool search. When disabled, all tools are pre-loaded
|
|
814
|
+
* and the model's active tool set is not deferred.
|
|
815
|
+
*/
|
|
816
|
+
enabled?: boolean;
|
|
817
|
+
/**
|
|
818
|
+
* Overrides the total tool count at which MCP and external tools are
|
|
819
|
+
* automatically deferred behind tool search. Defaults to the built-in
|
|
820
|
+
* threshold (30) when omitted.
|
|
821
|
+
*/
|
|
822
|
+
deferThreshold?: number;
|
|
823
|
+
}
|
|
824
|
+
/**
|
|
825
|
+
* Context passed to a command handler when a command is executed.
|
|
826
|
+
*/
|
|
827
|
+
export interface CommandContext {
|
|
828
|
+
/** Session ID where the command was invoked */
|
|
829
|
+
sessionId: string;
|
|
830
|
+
/** The full command text (e.g. "/deploy production") */
|
|
831
|
+
command: string;
|
|
832
|
+
/** Command name without leading / */
|
|
833
|
+
commandName: string;
|
|
834
|
+
/** Raw argument string after the command name */
|
|
835
|
+
args: string;
|
|
836
|
+
}
|
|
837
|
+
/**
|
|
838
|
+
* Handler invoked when a registered command is executed by a user.
|
|
839
|
+
*/
|
|
840
|
+
export type CommandHandler = (context: CommandContext) => Promise<void> | void;
|
|
841
|
+
/**
|
|
842
|
+
* Definition of a slash command registered with the session.
|
|
843
|
+
* When the CLI is running with a TUI, registered commands appear as
|
|
844
|
+
* `/commandName` for the user to invoke.
|
|
845
|
+
*/
|
|
846
|
+
export interface CommandDefinition {
|
|
847
|
+
/** Command name (without leading /). */
|
|
848
|
+
name: string;
|
|
849
|
+
/** Human-readable description shown in command completion UI. */
|
|
850
|
+
description?: string;
|
|
851
|
+
/** Handler invoked when the command is executed. */
|
|
852
|
+
handler: CommandHandler;
|
|
853
|
+
}
|
|
854
|
+
/**
|
|
855
|
+
* Capabilities reported by the CLI host for this session.
|
|
856
|
+
*/
|
|
857
|
+
export interface SessionCapabilities {
|
|
858
|
+
ui?: {
|
|
859
|
+
/** Whether the host supports interactive elicitation dialogs. */
|
|
860
|
+
elicitation?: boolean;
|
|
861
|
+
/**
|
|
862
|
+
* Whether the runtime has accepted the session's MCP Apps (SEP-1865)
|
|
863
|
+
* opt-in. `true` when the consumer set `enableMcpApps: true` on
|
|
864
|
+
* create/resume **and** the runtime's `MCP_APPS` feature flag (or
|
|
865
|
+
* `COPILOT_MCP_APPS=true` env override) is on. Otherwise absent or
|
|
866
|
+
* `false`, indicating the runtime silently dropped the opt-in.
|
|
867
|
+
*
|
|
868
|
+
* @experimental This property is part of an experimental wire-protocol surface
|
|
869
|
+
* (SEP-1865) and may change or be removed in a future release.
|
|
870
|
+
*/
|
|
871
|
+
mcpApps?: boolean;
|
|
872
|
+
/** Whether the host supports canvas rendering. */
|
|
873
|
+
canvases?: boolean;
|
|
874
|
+
/** Whether the runtime acknowledges retained-request Auto recovery. Absence means unsupported. */
|
|
875
|
+
autoModeRecovery?: boolean;
|
|
876
|
+
};
|
|
877
|
+
}
|
|
878
|
+
/**
|
|
879
|
+
* A single field in an elicitation schema — matches the MCP SDK's
|
|
880
|
+
* `PrimitiveSchemaDefinition` union.
|
|
881
|
+
*/
|
|
882
|
+
export type ElicitationSchemaField = {
|
|
883
|
+
type: "string";
|
|
884
|
+
title?: string;
|
|
885
|
+
description?: string;
|
|
886
|
+
enum: string[];
|
|
887
|
+
enumNames?: string[];
|
|
888
|
+
default?: string;
|
|
889
|
+
} | {
|
|
890
|
+
type: "string";
|
|
891
|
+
title?: string;
|
|
892
|
+
description?: string;
|
|
893
|
+
oneOf: {
|
|
894
|
+
const: string;
|
|
895
|
+
title: string;
|
|
896
|
+
}[];
|
|
897
|
+
default?: string;
|
|
898
|
+
} | {
|
|
899
|
+
type: "array";
|
|
900
|
+
title?: string;
|
|
901
|
+
description?: string;
|
|
902
|
+
minItems?: number;
|
|
903
|
+
maxItems?: number;
|
|
904
|
+
items: {
|
|
905
|
+
type: "string";
|
|
906
|
+
enum: string[];
|
|
907
|
+
};
|
|
908
|
+
default?: string[];
|
|
909
|
+
} | {
|
|
910
|
+
type: "array";
|
|
911
|
+
title?: string;
|
|
912
|
+
description?: string;
|
|
913
|
+
minItems?: number;
|
|
914
|
+
maxItems?: number;
|
|
915
|
+
items: {
|
|
916
|
+
anyOf: {
|
|
917
|
+
const: string;
|
|
918
|
+
title: string;
|
|
919
|
+
}[];
|
|
920
|
+
};
|
|
921
|
+
default?: string[];
|
|
922
|
+
} | {
|
|
923
|
+
type: "boolean";
|
|
924
|
+
title?: string;
|
|
925
|
+
description?: string;
|
|
926
|
+
default?: boolean;
|
|
927
|
+
} | {
|
|
928
|
+
type: "string";
|
|
929
|
+
title?: string;
|
|
930
|
+
description?: string;
|
|
931
|
+
minLength?: number;
|
|
932
|
+
maxLength?: number;
|
|
933
|
+
format?: "email" | "uri" | "date" | "date-time";
|
|
934
|
+
default?: string;
|
|
935
|
+
} | {
|
|
936
|
+
type: "number" | "integer";
|
|
937
|
+
title?: string;
|
|
938
|
+
description?: string;
|
|
939
|
+
minimum?: number;
|
|
940
|
+
maximum?: number;
|
|
941
|
+
default?: number;
|
|
942
|
+
};
|
|
943
|
+
/**
|
|
944
|
+
* Schema describing the form fields for an elicitation request.
|
|
945
|
+
*/
|
|
946
|
+
export interface ElicitationSchema {
|
|
947
|
+
type: "object";
|
|
948
|
+
properties: Record<string, ElicitationSchemaField>;
|
|
949
|
+
required?: string[];
|
|
950
|
+
}
|
|
951
|
+
/**
|
|
952
|
+
* Primitive field value in an elicitation result.
|
|
953
|
+
* Matches MCP SDK's `ElicitResult.content` value type.
|
|
954
|
+
*/
|
|
955
|
+
export type ElicitationFieldValue = string | number | boolean | string[];
|
|
956
|
+
/**
|
|
957
|
+
* Result returned from an elicitation request.
|
|
958
|
+
*/
|
|
959
|
+
export interface ElicitationResult {
|
|
960
|
+
/** User action: "accept" (submitted), "decline" (rejected), or "cancel" (dismissed). */
|
|
961
|
+
action: "accept" | "decline" | "cancel";
|
|
962
|
+
/** Form values submitted by the user (present when action is "accept"). */
|
|
963
|
+
content?: Record<string, ElicitationFieldValue | undefined>;
|
|
964
|
+
}
|
|
965
|
+
/**
|
|
966
|
+
* Result an {@link ElicitationHandler} returns: the {@link ElicitationResult},
|
|
967
|
+
* optionally labeled with who answered (see {@link createAttributedResult}).
|
|
968
|
+
*/
|
|
969
|
+
export interface ElicitationHandlerResult extends ElicitationResult {
|
|
970
|
+
/**
|
|
971
|
+
* Who answered and how. When it says a person answered interactively
|
|
972
|
+
* (`source: "human_response"`, `responseCapability: "interactive"`), the
|
|
973
|
+
* runtime counts the answer as the person's own authority for Assisted
|
|
974
|
+
* Permissions, but only from the session's owning connection.
|
|
975
|
+
*/
|
|
976
|
+
decisionContext?: PermissionDecisionContext;
|
|
977
|
+
}
|
|
978
|
+
/**
|
|
979
|
+
* Parameters for a raw elicitation request.
|
|
980
|
+
*/
|
|
981
|
+
export interface ElicitationParams {
|
|
982
|
+
/** Message describing what information is needed from the user. */
|
|
983
|
+
message: string;
|
|
984
|
+
/** JSON Schema describing the form fields to present. */
|
|
985
|
+
requestedSchema: ElicitationSchema;
|
|
986
|
+
}
|
|
987
|
+
/**
|
|
988
|
+
* Context for an elicitation handler invocation, combining the request data
|
|
989
|
+
* with session context. Mirrors the single-argument pattern of {@link CommandContext}.
|
|
990
|
+
*/
|
|
991
|
+
export interface ElicitationContext {
|
|
992
|
+
/** Identifier of the session that triggered the elicitation request. */
|
|
993
|
+
sessionId: string;
|
|
994
|
+
/** Message describing what information is needed from the user. */
|
|
995
|
+
message: string;
|
|
996
|
+
/** JSON Schema describing the form fields to present. */
|
|
997
|
+
requestedSchema?: ElicitationSchema;
|
|
998
|
+
/** Elicitation mode: "form" for structured input, "url" for browser redirect. */
|
|
999
|
+
mode?: "form" | "url";
|
|
1000
|
+
/** The source that initiated the request (e.g. MCP server name). */
|
|
1001
|
+
elicitationSource?: string;
|
|
1002
|
+
/** URL to open in the user's browser (url mode only). */
|
|
1003
|
+
url?: string;
|
|
1004
|
+
}
|
|
1005
|
+
/**
|
|
1006
|
+
* Handler invoked when the server dispatches an elicitation request to this client.
|
|
1007
|
+
* Return an {@link ElicitationHandlerResult} with the user's response.
|
|
1008
|
+
*/
|
|
1009
|
+
export type ElicitationHandler = (context: ElicitationContext) => Promise<ElicitationHandlerResult> | ElicitationHandlerResult;
|
|
1010
|
+
/**
|
|
1011
|
+
* Options for the `input()` convenience method.
|
|
1012
|
+
*/
|
|
1013
|
+
export interface UiInputOptions {
|
|
1014
|
+
/** Title label for the input field. */
|
|
1015
|
+
title?: string;
|
|
1016
|
+
/** Descriptive text shown below the field. */
|
|
1017
|
+
description?: string;
|
|
1018
|
+
/** Minimum character length. */
|
|
1019
|
+
minLength?: number;
|
|
1020
|
+
/** Maximum character length. */
|
|
1021
|
+
maxLength?: number;
|
|
1022
|
+
/** Semantic format hint. */
|
|
1023
|
+
format?: "email" | "uri" | "date" | "date-time";
|
|
1024
|
+
/** Default value pre-populated in the field. */
|
|
1025
|
+
default?: string;
|
|
1026
|
+
}
|
|
1027
|
+
/**
|
|
1028
|
+
* The `session.ui` API object providing interactive UI methods.
|
|
1029
|
+
* Only usable when the CLI host supports elicitation.
|
|
1030
|
+
*/
|
|
1031
|
+
export interface SessionUiApi {
|
|
1032
|
+
/**
|
|
1033
|
+
* Shows a generic elicitation dialog with a custom schema.
|
|
1034
|
+
* @throws Error if the host does not support elicitation.
|
|
1035
|
+
*/
|
|
1036
|
+
elicitation(params: ElicitationParams): Promise<ElicitationResult>;
|
|
1037
|
+
/**
|
|
1038
|
+
* Shows a confirmation dialog and returns the user's boolean answer.
|
|
1039
|
+
* Returns `false` if the user declines or cancels.
|
|
1040
|
+
* @throws Error if the host does not support elicitation.
|
|
1041
|
+
*/
|
|
1042
|
+
confirm(message: string): Promise<boolean>;
|
|
1043
|
+
/**
|
|
1044
|
+
* Shows a selection dialog with the given options.
|
|
1045
|
+
* Returns the selected value, or `null` if the user declines/cancels.
|
|
1046
|
+
* @throws Error if the host does not support elicitation.
|
|
1047
|
+
*/
|
|
1048
|
+
select(message: string, options: string[]): Promise<string | null>;
|
|
1049
|
+
/**
|
|
1050
|
+
* Shows a text input dialog.
|
|
1051
|
+
* Returns the entered text, or `null` if the user declines/cancels.
|
|
1052
|
+
* @throws Error if the host does not support elicitation.
|
|
1053
|
+
*/
|
|
1054
|
+
input(message: string, options?: UiInputOptions): Promise<string | null>;
|
|
1055
|
+
}
|
|
1056
|
+
export interface ToolCallRequestPayload {
|
|
1057
|
+
sessionId: string;
|
|
1058
|
+
toolCallId: string;
|
|
1059
|
+
toolName: string;
|
|
1060
|
+
arguments: unknown;
|
|
1061
|
+
}
|
|
1062
|
+
export interface ToolCallResponsePayload {
|
|
1063
|
+
result: ToolResult;
|
|
1064
|
+
}
|
|
1065
|
+
/**
|
|
1066
|
+
* Known system message section identifiers for the "customize" mode.
|
|
1067
|
+
* Each section corresponds to a distinct part of the system prompt.
|
|
1068
|
+
*/
|
|
1069
|
+
export type SystemMessageSection = "preamble" | "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "runtime_instructions" | "last_instructions";
|
|
1070
|
+
/** Section metadata for documentation and tooling. */
|
|
1071
|
+
export declare const SYSTEM_MESSAGE_SECTIONS: Record<SystemMessageSection, {
|
|
1072
|
+
description: string;
|
|
1073
|
+
}>;
|
|
1074
|
+
/**
|
|
1075
|
+
* Transform callback for a single section: receives current content, returns new content.
|
|
1076
|
+
*/
|
|
1077
|
+
export type SectionTransformFn = (currentContent: string) => string | Promise<string>;
|
|
1078
|
+
/**
|
|
1079
|
+
* Override action: a string literal for static overrides, or a callback for transforms.
|
|
1080
|
+
*
|
|
1081
|
+
* - `"replace"`: Replace section content entirely
|
|
1082
|
+
* - `"remove"`: Remove the section
|
|
1083
|
+
* - `"append"`: Append to existing section content
|
|
1084
|
+
* - `"prepend"`: Prepend to existing section content
|
|
1085
|
+
* - `"preserve"`: No-op marker that opts an individually-addressable section out of a
|
|
1086
|
+
* group-level `"remove"` (e.g. keep `tone` when removing the `identity` group)
|
|
1087
|
+
* - `function`: Transform callback — receives current section content, returns new content
|
|
1088
|
+
*/
|
|
1089
|
+
export type SectionOverrideAction = "replace" | "remove" | "append" | "prepend" | "preserve" | SectionTransformFn;
|
|
1090
|
+
/**
|
|
1091
|
+
* Override operation for a single system message section.
|
|
1092
|
+
*/
|
|
1093
|
+
export interface SectionOverride {
|
|
1094
|
+
/**
|
|
1095
|
+
* The operation to perform on this section.
|
|
1096
|
+
* Can be a string action or a transform callback function.
|
|
1097
|
+
*/
|
|
1098
|
+
action: SectionOverrideAction;
|
|
1099
|
+
/**
|
|
1100
|
+
* Content for the override. Optional for all actions.
|
|
1101
|
+
* - For replace, omitting content replaces with an empty string.
|
|
1102
|
+
* - For append/prepend, content is added before/after the existing section.
|
|
1103
|
+
* - Ignored for the remove action.
|
|
1104
|
+
*/
|
|
1105
|
+
content?: string;
|
|
1106
|
+
}
|
|
1107
|
+
/**
|
|
1108
|
+
* Append mode: Use CLI foundation with optional appended content (default).
|
|
1109
|
+
*/
|
|
1110
|
+
export interface SystemMessageAppendConfig {
|
|
1111
|
+
mode?: "append";
|
|
1112
|
+
/**
|
|
1113
|
+
* Additional instructions appended after SDK-managed sections.
|
|
1114
|
+
*/
|
|
1115
|
+
content?: string;
|
|
1116
|
+
}
|
|
1117
|
+
/**
|
|
1118
|
+
* Replace mode: Use caller-provided system message entirely.
|
|
1119
|
+
* Removes all SDK guardrails including security restrictions.
|
|
1120
|
+
*/
|
|
1121
|
+
export interface SystemMessageReplaceConfig {
|
|
1122
|
+
mode: "replace";
|
|
1123
|
+
/**
|
|
1124
|
+
* Complete system message content.
|
|
1125
|
+
* Replaces the entire SDK-managed system message.
|
|
1126
|
+
*/
|
|
1127
|
+
content: string;
|
|
1128
|
+
}
|
|
1129
|
+
/**
|
|
1130
|
+
* Customize mode: Override individual sections of the system prompt.
|
|
1131
|
+
* Keeps the SDK-managed prompt structure while allowing targeted modifications.
|
|
1132
|
+
* The `last_instructions` section includes configured subagent-model guidance.
|
|
1133
|
+
* Its overrides and transforms control that prose, not runtime model selection or tool availability.
|
|
1134
|
+
*/
|
|
1135
|
+
export interface SystemMessageCustomizeConfig {
|
|
1136
|
+
mode: "customize";
|
|
1137
|
+
/**
|
|
1138
|
+
* Override specific sections of the system prompt by section ID.
|
|
1139
|
+
* Unknown section IDs gracefully fall back: content-bearing overrides are appended
|
|
1140
|
+
* to additional instructions, and "remove" on unknown sections is a silent no-op.
|
|
1141
|
+
*/
|
|
1142
|
+
sections?: Partial<Record<SystemMessageSection, SectionOverride>>;
|
|
1143
|
+
/**
|
|
1144
|
+
* Additional content appended after all sections.
|
|
1145
|
+
* Equivalent to append mode's content field — provided for convenience.
|
|
1146
|
+
*/
|
|
1147
|
+
content?: string;
|
|
1148
|
+
}
|
|
1149
|
+
/**
|
|
1150
|
+
* System message configuration for session creation.
|
|
1151
|
+
* - Append mode (default): SDK foundation + optional custom content
|
|
1152
|
+
* - Replace mode: Full control, caller provides entire system message
|
|
1153
|
+
* - Customize mode: Section-level overrides with graceful fallback
|
|
1154
|
+
*/
|
|
1155
|
+
export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig | SystemMessageCustomizeConfig;
|
|
1156
|
+
import type { PermissionDecisionRequest, PermissionDecisionContext } from "./generated/rpc.js";
|
|
1157
|
+
/**
|
|
1158
|
+
* Permission request types from the server. This is the generated
|
|
1159
|
+
* discriminated union from the runtime schema — switch on `kind` to
|
|
1160
|
+
* access the variant-specific fields (e.g. shell `commands`, write
|
|
1161
|
+
* `fileName`/`diff`, mcp `toolName`/`args`).
|
|
1162
|
+
*
|
|
1163
|
+
* On the raw `permissionRequest`, `managedApprovalRequired` preserves managed
|
|
1164
|
+
* policy provenance and one-shot restrictions. To determine whether a human
|
|
1165
|
+
* response is still required, hosts should prefer
|
|
1166
|
+
* `event.data.promptRequest?.managedApprovalRequired` when `promptRequest` is
|
|
1167
|
+
* present, and fall back to the raw marker for older runtimes.
|
|
1168
|
+
*/
|
|
1169
|
+
export type PermissionRequest = GeneratedPermissionRequest & {
|
|
1170
|
+
readonly managedApprovalRequired?: boolean;
|
|
1171
|
+
};
|
|
1172
|
+
export type PermissionRequestedData = Omit<GeneratedPermissionRequestedData, "permissionRequest"> & {
|
|
1173
|
+
permissionRequest: PermissionRequest;
|
|
1174
|
+
};
|
|
1175
|
+
export type PermissionRequestedEvent = Omit<GeneratedPermissionRequestedEvent, "data"> & {
|
|
1176
|
+
data: PermissionRequestedData;
|
|
1177
|
+
};
|
|
1178
|
+
/**
|
|
1179
|
+
* Permission decision result returned from a {@link PermissionHandler}.
|
|
1180
|
+
* The discriminated `kind` field selects the decision. Variant-specific
|
|
1181
|
+
* fields (e.g. `feedback` on `{ kind: "reject" }`) come from the generated
|
|
1182
|
+
* `PermissionDecisionRequest["result"]` union.
|
|
1183
|
+
*/
|
|
1184
|
+
export type PermissionRequestResult = PermissionDecisionRequest["result"] | {
|
|
1185
|
+
kind: "no-result";
|
|
1186
|
+
};
|
|
1187
|
+
/**
|
|
1188
|
+
* A {@link PermissionRequestResult} annotated with the
|
|
1189
|
+
* {@link PermissionDecisionContext} describing who decided and how. When the
|
|
1190
|
+
* context says a person decided, the runtime records the decision as the
|
|
1191
|
+
* person's (`permission.completed.decisionSource = "human_response"`), but only
|
|
1192
|
+
* from the session's owning connection; an answer from any other connection
|
|
1193
|
+
* settles without that authority.
|
|
1194
|
+
*/
|
|
1195
|
+
export interface AttributedPermissionResult {
|
|
1196
|
+
kind: "attributed";
|
|
1197
|
+
result: PermissionRequestResult;
|
|
1198
|
+
decisionContext: PermissionDecisionContext;
|
|
1199
|
+
}
|
|
1200
|
+
/**
|
|
1201
|
+
* Narrows a {@link PermissionHandler} return value to an attributed result.
|
|
1202
|
+
*/
|
|
1203
|
+
export declare function isAttributedPermissionResult(result: PermissionRequestResult | AttributedPermissionResult): result is AttributedPermissionResult;
|
|
1204
|
+
/**
|
|
1205
|
+
* Pair a permission decision with the context describing who decided and how.
|
|
1206
|
+
* Equivalent to {@link createAttributedResult} for permission decisions.
|
|
1207
|
+
*
|
|
1208
|
+
* Passing an already-attributed result replaces the previous context rather
|
|
1209
|
+
* than nesting it.
|
|
1210
|
+
*/
|
|
1211
|
+
export declare function createAttributedPermissionResult(result: PermissionRequestResult | AttributedPermissionResult, decisionContext: PermissionDecisionContext): AttributedPermissionResult;
|
|
1212
|
+
/**
|
|
1213
|
+
* Label any prompt handler's result with who answered and how: a permission
|
|
1214
|
+
* decision, a user-input answer, a plan review, or an elicitation answer.
|
|
1215
|
+
*
|
|
1216
|
+
* Label a person's answer with `source: "human_response"` and
|
|
1217
|
+
* `responseCapability: "interactive"`, including when they decline or dismiss
|
|
1218
|
+
* the prompt, so the runtime can count it as their own authority for Assisted
|
|
1219
|
+
* Permissions. The runtime decides which answers carry authority, and accepts
|
|
1220
|
+
* the label only from the session's owning connection; any other answer still
|
|
1221
|
+
* settles, without it. Leave automated answers unlabeled or label them with a
|
|
1222
|
+
* non-human `source`.
|
|
1223
|
+
*
|
|
1224
|
+
* Passing an already-labeled result replaces the previous label.
|
|
1225
|
+
*
|
|
1226
|
+
* @example
|
|
1227
|
+
* ```typescript
|
|
1228
|
+
* onUserInputRequest: async (request) =>
|
|
1229
|
+
* createAttributedResult(
|
|
1230
|
+
* { answer: await askPerson(request.question), wasFreeform: true },
|
|
1231
|
+
* { source: "human_response", responseCapability: "interactive", surface: "sdk", outcome: "prompted_user" }
|
|
1232
|
+
* ),
|
|
1233
|
+
* ```
|
|
1234
|
+
*/
|
|
1235
|
+
export declare function createAttributedResult(result: PermissionRequestResult | AttributedPermissionResult, decisionContext: PermissionDecisionContext): AttributedPermissionResult;
|
|
1236
|
+
export declare function createAttributedResult<T extends UserInputResponse | ExitPlanModeResult | ElicitationHandlerResult>(result: T, decisionContext: PermissionDecisionContext): T & PromptDecisionLabel;
|
|
1237
|
+
/** The label {@link createAttributedResult} adds to a non-permission prompt answer. */
|
|
1238
|
+
export interface PromptDecisionLabel {
|
|
1239
|
+
decisionContext: PermissionDecisionContext;
|
|
1240
|
+
}
|
|
1241
|
+
/**
|
|
1242
|
+
* Context supplied with a permission request callback.
|
|
1243
|
+
*/
|
|
1244
|
+
export interface PermissionHandlerInvocation {
|
|
1245
|
+
sessionId: string;
|
|
1246
|
+
managedSettingsEnabled?: boolean;
|
|
1247
|
+
/**
|
|
1248
|
+
* Program invocation owning this permission request; absent for ordinary requests.
|
|
1249
|
+
* @experimental
|
|
1250
|
+
*/
|
|
1251
|
+
programToolCallId?: string;
|
|
1252
|
+
/**
|
|
1253
|
+
* Canonical runtime-owned Assisted Permissions assessment.
|
|
1254
|
+
*
|
|
1255
|
+
* This explains the assisted review only; `permission.completed` remains
|
|
1256
|
+
* authoritative for the final permission result. It is absent with older
|
|
1257
|
+
* runtimes and legacy direct permission callbacks.
|
|
1258
|
+
*
|
|
1259
|
+
* @experimental
|
|
1260
|
+
*/
|
|
1261
|
+
assistedApprovalAssessment?: PermissionRequestedData["assistedApprovalAssessment"];
|
|
1262
|
+
/**
|
|
1263
|
+
* Derived user-facing prompt context when supplied by the runtime.
|
|
1264
|
+
*
|
|
1265
|
+
* Managed requests retain their raw `managedApprovalRequired` marker. Only
|
|
1266
|
+
* standard prompt kinds (`commands`, `read`, `write`, `url`, and
|
|
1267
|
+
* `workflow`) can clear that human requirement after Assisted approval.
|
|
1268
|
+
* For missing or other prompt kinds, keep the raw marker authoritative.
|
|
1269
|
+
*/
|
|
1270
|
+
promptRequest?: PermissionRequestedData["promptRequest"];
|
|
1271
|
+
}
|
|
1272
|
+
export type PermissionHandler = (request: PermissionRequest, invocation: PermissionHandlerInvocation) => Promise<PermissionRequestResult | AttributedPermissionResult> | PermissionRequestResult | AttributedPermissionResult;
|
|
1273
|
+
/**
|
|
1274
|
+
* Approves permission requests when managed settings are disabled.
|
|
1275
|
+
*/
|
|
1276
|
+
export declare const approveAll: PermissionHandler;
|
|
1277
|
+
export declare const defaultJoinSessionPermissionHandler: PermissionHandler;
|
|
1278
|
+
/**
|
|
1279
|
+
* Legacy question-and-answer request from the `ask_user` tool.
|
|
1280
|
+
*/
|
|
1281
|
+
export interface UserInputRequest {
|
|
1282
|
+
/**
|
|
1283
|
+
* The question to ask the user
|
|
1284
|
+
*/
|
|
1285
|
+
question: string;
|
|
1286
|
+
/**
|
|
1287
|
+
* Optional choices for multiple choice questions
|
|
1288
|
+
*/
|
|
1289
|
+
choices?: string[];
|
|
1290
|
+
/**
|
|
1291
|
+
* Whether to allow freeform text input in addition to choices
|
|
1292
|
+
* @default true
|
|
1293
|
+
*/
|
|
1294
|
+
allowFreeform?: boolean;
|
|
1295
|
+
/**
|
|
1296
|
+
* Runtime ID of the pending `user_input.requested` request. Pass it as `requestId`
|
|
1297
|
+
* to answer this exact request through the session's UI RPCs. Absent when the
|
|
1298
|
+
* runtime predates this field.
|
|
1299
|
+
*/
|
|
1300
|
+
requestId?: string;
|
|
1301
|
+
}
|
|
1302
|
+
/**
|
|
1303
|
+
* Response to a user input request
|
|
1304
|
+
*/
|
|
1305
|
+
export interface UserInputResponse {
|
|
1306
|
+
/**
|
|
1307
|
+
* The user's answer
|
|
1308
|
+
*/
|
|
1309
|
+
answer: string;
|
|
1310
|
+
/**
|
|
1311
|
+
* Whether the answer was freeform (not from choices)
|
|
1312
|
+
*/
|
|
1313
|
+
wasFreeform: boolean;
|
|
1314
|
+
/**
|
|
1315
|
+
* Who answered and how (see {@link createAttributedResult}). When it says a
|
|
1316
|
+
* person answered interactively, the runtime counts the answer as the
|
|
1317
|
+
* person's own authority for Assisted Permissions, but only from the
|
|
1318
|
+
* session's owning connection.
|
|
1319
|
+
*/
|
|
1320
|
+
decisionContext?: PermissionDecisionContext;
|
|
1321
|
+
}
|
|
1322
|
+
/**
|
|
1323
|
+
* Handler for user input requests from the agent
|
|
1324
|
+
*/
|
|
1325
|
+
export type UserInputHandler = (request: UserInputRequest, invocation: {
|
|
1326
|
+
sessionId: string;
|
|
1327
|
+
}) => Promise<UserInputResponse> | UserInputResponse;
|
|
1328
|
+
/**
|
|
1329
|
+
* A password or other answer that a shell command run by the agent asks for,
|
|
1330
|
+
* for example `sudo -A`, `ssh`, or `git` over HTTPS. The answer goes only to
|
|
1331
|
+
* the program that asked: it is not shown to the model and is not recorded in
|
|
1332
|
+
* session events.
|
|
1333
|
+
*/
|
|
1334
|
+
export interface ShellAuthenticationRequest {
|
|
1335
|
+
/** Identifies the request. A cancellation for it carries the same id. */
|
|
1336
|
+
requestId: string;
|
|
1337
|
+
/** The program that asked: `sudo`, `ssh`, or `git`. */
|
|
1338
|
+
program: string;
|
|
1339
|
+
/** The prompt text the program supplied. */
|
|
1340
|
+
prompt: string;
|
|
1341
|
+
/**
|
|
1342
|
+
* `secret` for a password or passphrase (mask the input), `text` for a
|
|
1343
|
+
* visible answer such as a user name, or `confirm` for a yes/no question
|
|
1344
|
+
* such as an ssh host-key check.
|
|
1345
|
+
*/
|
|
1346
|
+
inputKind: "secret" | "text" | "confirm";
|
|
1347
|
+
/** The shell command that triggered the prompt. */
|
|
1348
|
+
command: string;
|
|
1349
|
+
/** The command's working directory. */
|
|
1350
|
+
cwd: string;
|
|
1351
|
+
}
|
|
1352
|
+
/**
|
|
1353
|
+
* Answer to a {@link ShellAuthenticationRequest}. Answer a `confirm` request with
|
|
1354
|
+
* `"yes"`, or cancel it to decline.
|
|
1355
|
+
*/
|
|
1356
|
+
export type ShellAuthenticationResponse = {
|
|
1357
|
+
action: "accept";
|
|
1358
|
+
value: string;
|
|
1359
|
+
} | {
|
|
1360
|
+
action: "cancel";
|
|
1361
|
+
};
|
|
1362
|
+
/**
|
|
1363
|
+
* Handler for shell authentication requests. `signal` aborts when the answer is no
|
|
1364
|
+
* longer needed, for example because the command ended or the prompt timed
|
|
1365
|
+
* out; close the input when it does.
|
|
1366
|
+
*/
|
|
1367
|
+
export type ShellAuthenticationHandler = (request: ShellAuthenticationRequest, invocation: {
|
|
1368
|
+
sessionId: string;
|
|
1369
|
+
signal: AbortSignal;
|
|
1370
|
+
}) => Promise<ShellAuthenticationResponse> | ShellAuthenticationResponse;
|
|
1371
|
+
/**
|
|
1372
|
+
* Request to exit plan mode and continue with a selected action.
|
|
1373
|
+
*/
|
|
1374
|
+
export interface ExitPlanModeRequest {
|
|
1375
|
+
/** Summary of the plan or proposed next step. */
|
|
1376
|
+
summary: string;
|
|
1377
|
+
/** Full plan content, when available. */
|
|
1378
|
+
planContent?: string;
|
|
1379
|
+
/** Available actions the user can select. */
|
|
1380
|
+
actions: string[];
|
|
1381
|
+
/** The action recommended by the runtime. */
|
|
1382
|
+
recommendedAction: string;
|
|
1383
|
+
/**
|
|
1384
|
+
* Runtime ID of the pending `exit_plan_mode.requested` request. Pass it as
|
|
1385
|
+
* `requestId` to answer this exact request through the session's UI RPCs. Absent
|
|
1386
|
+
* when the runtime predates this field.
|
|
1387
|
+
*/
|
|
1388
|
+
requestId?: string;
|
|
1389
|
+
}
|
|
1390
|
+
/**
|
|
1391
|
+
* Response to an exit-plan-mode request.
|
|
1392
|
+
*/
|
|
1393
|
+
export interface ExitPlanModeResult {
|
|
1394
|
+
/** Whether the user approved exiting plan mode. */
|
|
1395
|
+
approved: boolean;
|
|
1396
|
+
/** Selected action, if the user chose one. */
|
|
1397
|
+
selectedAction?: string;
|
|
1398
|
+
/** Optional feedback provided by the user. */
|
|
1399
|
+
feedback?: string;
|
|
1400
|
+
/**
|
|
1401
|
+
* Who answered and how (see {@link createAttributedResult}). When it says a
|
|
1402
|
+
* person answered interactively, the runtime counts the review as the
|
|
1403
|
+
* person's own for Assisted Permissions, but only from the session's
|
|
1404
|
+
* owning connection.
|
|
1405
|
+
*/
|
|
1406
|
+
decisionContext?: PermissionDecisionContext;
|
|
1407
|
+
}
|
|
1408
|
+
/**
|
|
1409
|
+
* Handler for exit-plan-mode requests from the agent.
|
|
1410
|
+
*/
|
|
1411
|
+
export type ExitPlanModeHandler = (request: ExitPlanModeRequest, invocation: {
|
|
1412
|
+
sessionId: string;
|
|
1413
|
+
}) => Promise<ExitPlanModeResult> | ExitPlanModeResult;
|
|
1414
|
+
/**
|
|
1415
|
+
* Context for an offer to recover the active request using Auto.
|
|
1416
|
+
*/
|
|
1417
|
+
export interface AutoModeRecoveryContext {
|
|
1418
|
+
requestId: string;
|
|
1419
|
+
originalModel: string;
|
|
1420
|
+
/** Whether this offer permits remembering consent. Currently true only for per-model rate limits. */
|
|
1421
|
+
allowAlways: boolean;
|
|
1422
|
+
interactionId?: string;
|
|
1423
|
+
originatingMessageId?: string;
|
|
1424
|
+
}
|
|
1425
|
+
/**
|
|
1426
|
+
* Request to switch to Auto after a rate limit or recover an eligible active request.
|
|
1427
|
+
*/
|
|
1428
|
+
export interface AutoModeSwitchRequest {
|
|
1429
|
+
/** The upstream error code that triggered the request. */
|
|
1430
|
+
errorCode?: string;
|
|
1431
|
+
/** Seconds until the rate limit resets, when known. */
|
|
1432
|
+
retryAfterSeconds?: number;
|
|
1433
|
+
/** Present only for retained-request recovery, not legacy future-message switching. */
|
|
1434
|
+
autoModeRecovery?: AutoModeRecoveryContext;
|
|
1435
|
+
}
|
|
1436
|
+
/**
|
|
1437
|
+
* Response to an auto-mode-switch request.
|
|
1438
|
+
*/
|
|
1439
|
+
export type AutoModeSwitchResponse = "yes" | "yes_always" | "no";
|
|
1440
|
+
/**
|
|
1441
|
+
* Handler for auto-mode-switch requests from the agent.
|
|
1442
|
+
*/
|
|
1443
|
+
export type AutoModeSwitchHandler = (request: AutoModeSwitchRequest, invocation: {
|
|
1444
|
+
sessionId: string;
|
|
1445
|
+
}) => Promise<AutoModeSwitchResponse> | AutoModeSwitchResponse;
|
|
1446
|
+
/**
|
|
1447
|
+
* Base interface for all hook inputs
|
|
1448
|
+
*/
|
|
1449
|
+
export interface BaseHookInput {
|
|
1450
|
+
/** Subagent actor ID, absent for root hooks and older runtimes. */
|
|
1451
|
+
agentId?: string;
|
|
1452
|
+
/** Subagent type, when known by the runtime. */
|
|
1453
|
+
agentType?: string;
|
|
1454
|
+
/** Immediate parent actor ID, when available. */
|
|
1455
|
+
parentAgentId?: string;
|
|
1456
|
+
/** W3C trace context for the runtime span associated with this hook, when available. */
|
|
1457
|
+
traceparent?: string;
|
|
1458
|
+
/** W3C vendor trace state associated with traceparent, when available. */
|
|
1459
|
+
tracestate?: string;
|
|
1460
|
+
/** The runtime session ID associated with the hook. Child tool hooks use
|
|
1461
|
+
* the child session ID; sub-agent lifecycle hooks use the parent session ID,
|
|
1462
|
+
* which can differ from `invocation.sessionId`. */
|
|
1463
|
+
sessionId: string;
|
|
1464
|
+
/** Time at which the hook event was emitted by the runtime. */
|
|
1465
|
+
timestamp: Date;
|
|
1466
|
+
workingDirectory: string;
|
|
1467
|
+
}
|
|
1468
|
+
/**
|
|
1469
|
+
* Input for pre-tool-use hook
|
|
1470
|
+
*/
|
|
1471
|
+
export interface PreToolUseHookInput extends BaseHookInput {
|
|
1472
|
+
/** Existing tool-call ID; correlate using (sessionId, toolCallId). Absent on older runtimes. */
|
|
1473
|
+
toolCallId?: string;
|
|
1474
|
+
toolName: string;
|
|
1475
|
+
toolArgs: unknown;
|
|
1476
|
+
}
|
|
1477
|
+
/**
|
|
1478
|
+
* Output for pre-tool-use hook
|
|
1479
|
+
*/
|
|
1480
|
+
export interface PreToolUseHookOutput {
|
|
1481
|
+
permissionDecision?: "allow" | "deny" | "ask";
|
|
1482
|
+
permissionDecisionReason?: string;
|
|
1483
|
+
modifiedArgs?: unknown;
|
|
1484
|
+
additionalContext?: string;
|
|
1485
|
+
suppressOutput?: boolean;
|
|
1486
|
+
}
|
|
1487
|
+
/**
|
|
1488
|
+
* Handler for pre-tool-use hook
|
|
1489
|
+
*/
|
|
1490
|
+
export type PreToolUseHandler = (input: PreToolUseHookInput, invocation: {
|
|
1491
|
+
sessionId: string;
|
|
1492
|
+
}) => Promise<PreToolUseHookOutput | void> | PreToolUseHookOutput | void;
|
|
1493
|
+
/**
|
|
1494
|
+
* Input for pre-MCP-tool-call hook
|
|
1495
|
+
*/
|
|
1496
|
+
export interface PreMcpToolCallHookInput extends BaseHookInput {
|
|
1497
|
+
toolCallId?: string;
|
|
1498
|
+
serverName: string;
|
|
1499
|
+
toolName: string;
|
|
1500
|
+
arguments: unknown;
|
|
1501
|
+
_meta?: Record<string, unknown>;
|
|
1502
|
+
}
|
|
1503
|
+
/**
|
|
1504
|
+
* Output for pre-MCP-tool-call hook
|
|
1505
|
+
*/
|
|
1506
|
+
export interface PreMcpToolCallHookOutput {
|
|
1507
|
+
/**
|
|
1508
|
+
* Hook-controlled metadata to use for the outgoing MCP request.
|
|
1509
|
+
* - undefined/absent: preserve the current request `_meta`
|
|
1510
|
+
* - object: use this object as request `_meta`
|
|
1511
|
+
* - null: drop hook-controlled `_meta`; the runtime still sends its own keys,
|
|
1512
|
+
* `com.github.copilot/toolCallId` and `com.github.copilot/turnId` (present only
|
|
1513
|
+
* when the turn was started with a `clientTurnId`)
|
|
1514
|
+
*/
|
|
1515
|
+
metaToUse?: Record<string, unknown> | null;
|
|
1516
|
+
}
|
|
1517
|
+
/**
|
|
1518
|
+
* Handler for pre-MCP-tool-call hook
|
|
1519
|
+
*/
|
|
1520
|
+
export type PreMcpToolCallHandler = (input: PreMcpToolCallHookInput, invocation: {
|
|
1521
|
+
sessionId: string;
|
|
1522
|
+
}) => Promise<PreMcpToolCallHookOutput | void> | PreMcpToolCallHookOutput | void;
|
|
1523
|
+
/**
|
|
1524
|
+
* Input for post-tool-use hook
|
|
1525
|
+
*/
|
|
1526
|
+
export interface PostToolUseHookInput extends BaseHookInput {
|
|
1527
|
+
/** Existing tool-call ID; correlate using (sessionId, toolCallId). Absent on older runtimes. */
|
|
1528
|
+
toolCallId?: string;
|
|
1529
|
+
toolName: string;
|
|
1530
|
+
toolArgs: unknown;
|
|
1531
|
+
toolResult: ToolResultObject;
|
|
1532
|
+
}
|
|
1533
|
+
/**
|
|
1534
|
+
* Output for post-tool-use hook
|
|
1535
|
+
*/
|
|
1536
|
+
export interface PostToolUseHookOutput {
|
|
1537
|
+
modifiedResult?: ToolResultObject;
|
|
1538
|
+
additionalContext?: string;
|
|
1539
|
+
suppressOutput?: boolean;
|
|
1540
|
+
}
|
|
1541
|
+
/**
|
|
1542
|
+
* Handler for post-tool-use hook
|
|
1543
|
+
*/
|
|
1544
|
+
export type PostToolUseHandler = (input: PostToolUseHookInput, invocation: {
|
|
1545
|
+
sessionId: string;
|
|
1546
|
+
}) => Promise<PostToolUseHookOutput | void> | PostToolUseHookOutput | void;
|
|
1547
|
+
/**
|
|
1548
|
+
* Input for post-tool-use-failure hook.
|
|
1549
|
+
*
|
|
1550
|
+
* Dispatched after a tool execution whose `resultType` is `"failure"`.
|
|
1551
|
+
* The input differs from {@link PostToolUseHookInput}: the host CLI does not
|
|
1552
|
+
* forward the full `ToolResultObject` to failure hooks — only `error`, the
|
|
1553
|
+
* stringified failure message extracted from the tool's result, is provided.
|
|
1554
|
+
*/
|
|
1555
|
+
export interface PostToolUseFailureHookInput extends BaseHookInput {
|
|
1556
|
+
/** Existing tool-call ID; correlate using (sessionId, toolCallId). Absent on older runtimes. */
|
|
1557
|
+
toolCallId?: string;
|
|
1558
|
+
toolName: string;
|
|
1559
|
+
toolArgs: unknown;
|
|
1560
|
+
/**
|
|
1561
|
+
* Failure message from the tool's result (the `error` field of the
|
|
1562
|
+
* underlying `ToolResultObject`, falling back to its text/log fields).
|
|
1563
|
+
*/
|
|
1564
|
+
error: string;
|
|
1565
|
+
}
|
|
1566
|
+
/**
|
|
1567
|
+
* Output for post-tool-use-failure hook.
|
|
1568
|
+
*
|
|
1569
|
+
* Only `additionalContext` is consumed by the host CLI — it is appended as
|
|
1570
|
+
* hidden guidance to the model alongside the failed tool result. Other fields
|
|
1571
|
+
* such as `modifiedResult` or `suppressOutput` are not honored for failure
|
|
1572
|
+
* hooks (see {@link PostToolUseHookOutput} for the success-only hook).
|
|
1573
|
+
*/
|
|
1574
|
+
export interface PostToolUseFailureHookOutput {
|
|
1575
|
+
additionalContext?: string;
|
|
1576
|
+
}
|
|
1577
|
+
/**
|
|
1578
|
+
* Handler for post-tool-use-failure hook.
|
|
1579
|
+
*
|
|
1580
|
+
* Fires after a tool execution whose result was `"failure"`. `onPostToolUse`
|
|
1581
|
+
* only fires for successful results, so register this handler to observe or
|
|
1582
|
+
* react to failed tool outcomes.
|
|
1583
|
+
*
|
|
1584
|
+
* Note: `"rejected"`, `"denied"`, and `"timeout"` results do not currently
|
|
1585
|
+
* trigger this hook either — only `"failure"` does.
|
|
1586
|
+
*/
|
|
1587
|
+
export type PostToolUseFailureHandler = (input: PostToolUseFailureHookInput, invocation: {
|
|
1588
|
+
sessionId: string;
|
|
1589
|
+
}) => Promise<PostToolUseFailureHookOutput | void> | PostToolUseFailureHookOutput | void;
|
|
1590
|
+
/**
|
|
1591
|
+
* Input for user-prompt-submitted hook
|
|
1592
|
+
*/
|
|
1593
|
+
export interface UserPromptSubmittedHookInput extends BaseHookInput {
|
|
1594
|
+
prompt: string;
|
|
1595
|
+
}
|
|
1596
|
+
/**
|
|
1597
|
+
* Output for user-prompt-submitted hook
|
|
1598
|
+
*/
|
|
1599
|
+
export interface UserPromptSubmittedHookOutput {
|
|
1600
|
+
modifiedPrompt?: string;
|
|
1601
|
+
additionalContext?: string;
|
|
1602
|
+
suppressOutput?: boolean;
|
|
1603
|
+
/**
|
|
1604
|
+
* `"block"` refuses the prompt: no model turn runs, no user message is
|
|
1605
|
+
* recorded, and the session emits an ephemeral `session.warning`
|
|
1606
|
+
* (`warningType: "policy_blocked"`) carrying {@link reason}.
|
|
1607
|
+
*/
|
|
1608
|
+
decision?: "block";
|
|
1609
|
+
/** Why the prompt was blocked, carried by the `session.warning`. */
|
|
1610
|
+
reason?: string;
|
|
1611
|
+
}
|
|
1612
|
+
/**
|
|
1613
|
+
* Handler for user-prompt-submitted hook
|
|
1614
|
+
*/
|
|
1615
|
+
export type UserPromptSubmittedHandler = (input: UserPromptSubmittedHookInput, invocation: {
|
|
1616
|
+
sessionId: string;
|
|
1617
|
+
}) => Promise<UserPromptSubmittedHookOutput | void> | UserPromptSubmittedHookOutput | void;
|
|
1618
|
+
/**
|
|
1619
|
+
* Input for the user-prompt-transformed hook.
|
|
1620
|
+
*
|
|
1621
|
+
* This hook runs after the runtime has transformed the submitted prompt with
|
|
1622
|
+
* generated context, but before it is persisted to session history or sent to
|
|
1623
|
+
* the model.
|
|
1624
|
+
*/
|
|
1625
|
+
export interface UserPromptTransformedHookInput extends BaseHookInput {
|
|
1626
|
+
prompt: string;
|
|
1627
|
+
transformedPrompt: string;
|
|
1628
|
+
}
|
|
1629
|
+
/**
|
|
1630
|
+
* Output for the user-prompt-transformed hook.
|
|
1631
|
+
*/
|
|
1632
|
+
export interface UserPromptTransformedHookOutput {
|
|
1633
|
+
modifiedTransformedPrompt?: string;
|
|
1634
|
+
}
|
|
1635
|
+
/**
|
|
1636
|
+
* Handler for the user-prompt-transformed hook.
|
|
1637
|
+
*/
|
|
1638
|
+
export type UserPromptTransformedHandler = (input: UserPromptTransformedHookInput, invocation: {
|
|
1639
|
+
sessionId: string;
|
|
1640
|
+
}) => Promise<UserPromptTransformedHookOutput | void> | UserPromptTransformedHookOutput | void;
|
|
1641
|
+
/**
|
|
1642
|
+
* Input for session-start hook
|
|
1643
|
+
*/
|
|
1644
|
+
export interface SessionStartHookInput extends BaseHookInput {
|
|
1645
|
+
source: "startup" | "resume" | "new";
|
|
1646
|
+
initialPrompt?: string;
|
|
1647
|
+
}
|
|
1648
|
+
/**
|
|
1649
|
+
* Output for session-start hook
|
|
1650
|
+
*/
|
|
1651
|
+
export interface SessionStartHookOutput {
|
|
1652
|
+
additionalContext?: string;
|
|
1653
|
+
modifiedConfig?: Record<string, unknown>;
|
|
1654
|
+
}
|
|
1655
|
+
/**
|
|
1656
|
+
* Handler for session-start hook
|
|
1657
|
+
*/
|
|
1658
|
+
export type SessionStartHandler = (input: SessionStartHookInput, invocation: {
|
|
1659
|
+
sessionId: string;
|
|
1660
|
+
}) => Promise<SessionStartHookOutput | void> | SessionStartHookOutput | void;
|
|
1661
|
+
/**
|
|
1662
|
+
* Input for session-end hook
|
|
1663
|
+
*/
|
|
1664
|
+
export interface SessionEndHookInput extends BaseHookInput {
|
|
1665
|
+
reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
|
|
1666
|
+
finalMessage?: string;
|
|
1667
|
+
error?: string;
|
|
1668
|
+
}
|
|
1669
|
+
/**
|
|
1670
|
+
* Output for session-end hook
|
|
1671
|
+
*/
|
|
1672
|
+
export interface SessionEndHookOutput {
|
|
1673
|
+
suppressOutput?: boolean;
|
|
1674
|
+
cleanupActions?: string[];
|
|
1675
|
+
sessionSummary?: string;
|
|
1676
|
+
}
|
|
1677
|
+
/**
|
|
1678
|
+
* Handler for session-end hook
|
|
1679
|
+
*/
|
|
1680
|
+
export type SessionEndHandler = (input: SessionEndHookInput, invocation: {
|
|
1681
|
+
sessionId: string;
|
|
1682
|
+
}) => Promise<SessionEndHookOutput | void> | SessionEndHookOutput | void;
|
|
1683
|
+
/**
|
|
1684
|
+
* Input for error-occurred hook
|
|
1685
|
+
*/
|
|
1686
|
+
export interface ErrorOccurredHookInput extends BaseHookInput {
|
|
1687
|
+
error: string;
|
|
1688
|
+
errorContext: "model_call" | "tool_execution" | "system" | "user_input";
|
|
1689
|
+
recoverable: boolean;
|
|
1690
|
+
}
|
|
1691
|
+
/**
|
|
1692
|
+
* Output for error-occurred hook
|
|
1693
|
+
*/
|
|
1694
|
+
export interface ErrorOccurredHookOutput {
|
|
1695
|
+
suppressOutput?: boolean;
|
|
1696
|
+
errorHandling?: "retry" | "skip" | "abort";
|
|
1697
|
+
retryCount?: number;
|
|
1698
|
+
userNotification?: string;
|
|
1699
|
+
}
|
|
1700
|
+
/**
|
|
1701
|
+
* Handler for error-occurred hook
|
|
1702
|
+
*/
|
|
1703
|
+
export type ErrorOccurredHandler = (input: ErrorOccurredHookInput, invocation: {
|
|
1704
|
+
sessionId: string;
|
|
1705
|
+
}) => Promise<ErrorOccurredHookOutput | void> | ErrorOccurredHookOutput | void;
|
|
1706
|
+
/**
|
|
1707
|
+
* Input for the agent-stop hook.
|
|
1708
|
+
*
|
|
1709
|
+
* Fires for the top-level (main) agent when it reaches a natural terminal stop
|
|
1710
|
+
* — i.e. the agent has gone idle without a pending non-terminal tool call and
|
|
1711
|
+
* was not aborted or blocked by a rejected tool. (For sub-agents, the runtime
|
|
1712
|
+
* fires a separate sub-agent stop lifecycle.)
|
|
1713
|
+
*/
|
|
1714
|
+
export interface AgentStopHookInput extends BaseHookInput {
|
|
1715
|
+
/** Why the agent stopped (for example, `"end_turn"`). */
|
|
1716
|
+
stopReason?: string;
|
|
1717
|
+
/** Path to the on-disk session transcript, when available. */
|
|
1718
|
+
transcriptPath?: string;
|
|
1719
|
+
/**
|
|
1720
|
+
* True when this stop is a re-entry triggered by a previous agent-stop
|
|
1721
|
+
* `block` decision (Claude-compatible `stop_hook_active` semantics). Lets a
|
|
1722
|
+
* handler avoid blocking indefinitely.
|
|
1723
|
+
*/
|
|
1724
|
+
stopHookActive?: boolean;
|
|
1725
|
+
}
|
|
1726
|
+
/**
|
|
1727
|
+
* Output for the agent-stop hook.
|
|
1728
|
+
*
|
|
1729
|
+
* Return `{ decision: "block", reason }` to keep the agent running: the
|
|
1730
|
+
* `reason` is enqueued as a follow-up user message so the agent continues
|
|
1731
|
+
* working (for example, to remediate findings surfaced by the hook). The
|
|
1732
|
+
* runtime caps consecutive blocks to prevent runaway loops. Returning nothing
|
|
1733
|
+
* (or omitting `decision`) lets the agent stop normally.
|
|
1734
|
+
*/
|
|
1735
|
+
export interface AgentStopHookOutput {
|
|
1736
|
+
decision?: "block";
|
|
1737
|
+
reason?: string;
|
|
1738
|
+
}
|
|
1739
|
+
/**
|
|
1740
|
+
* Handler for the agent-stop hook.
|
|
1741
|
+
*/
|
|
1742
|
+
export type AgentStopHandler = (input: AgentStopHookInput, invocation: {
|
|
1743
|
+
sessionId: string;
|
|
1744
|
+
}) => Promise<AgentStopHookOutput | void> | AgentStopHookOutput | void;
|
|
1745
|
+
/**
|
|
1746
|
+
* Input for the hook fired before a sub-agent's first turn.
|
|
1747
|
+
*
|
|
1748
|
+
* The session metadata belongs to the parent session, not the child.
|
|
1749
|
+
*/
|
|
1750
|
+
export interface SubagentStartHookInput extends BaseHookInput {
|
|
1751
|
+
transcriptPath: string;
|
|
1752
|
+
agentName: string;
|
|
1753
|
+
agentDisplayName?: string;
|
|
1754
|
+
agentDescription?: string;
|
|
1755
|
+
}
|
|
1756
|
+
/** Output for the sub-agent start hook. Context is prepended to the child's initial prompt. */
|
|
1757
|
+
export interface SubagentStartHookOutput {
|
|
1758
|
+
additionalContext?: string;
|
|
1759
|
+
}
|
|
1760
|
+
/** Handler for the sub-agent start hook. */
|
|
1761
|
+
export type SubagentStartHandler = (input: SubagentStartHookInput, invocation: {
|
|
1762
|
+
sessionId: string;
|
|
1763
|
+
}) => Promise<SubagentStartHookOutput | void> | SubagentStartHookOutput | void;
|
|
1764
|
+
/**
|
|
1765
|
+
* Input for the hook fired after a sub-agent completes a turn.
|
|
1766
|
+
*
|
|
1767
|
+
* The response is the child's last assistant message before any hook rewrite.
|
|
1768
|
+
*/
|
|
1769
|
+
export interface SubagentStopHookInput extends SubagentStartHookInput {
|
|
1770
|
+
agentId?: string;
|
|
1771
|
+
agentType: string;
|
|
1772
|
+
stopReason: "end_turn";
|
|
1773
|
+
response: string;
|
|
1774
|
+
}
|
|
1775
|
+
/**
|
|
1776
|
+
* Output for the sub-agent stop hook. `"block"` with a nonempty `reason` continues
|
|
1777
|
+
* the child; otherwise `modifiedResponse` replaces the response reported to the parent.
|
|
1778
|
+
* When both are supplied, a valid block takes precedence over the rewrite.
|
|
1779
|
+
*/
|
|
1780
|
+
export type SubagentStopHookOutput = {
|
|
1781
|
+
decision: "block";
|
|
1782
|
+
reason: string;
|
|
1783
|
+
modifiedResponse?: string;
|
|
1784
|
+
} | {
|
|
1785
|
+
decision?: "allow";
|
|
1786
|
+
reason?: never;
|
|
1787
|
+
modifiedResponse?: string;
|
|
1788
|
+
};
|
|
1789
|
+
/** Handler for the sub-agent stop hook. */
|
|
1790
|
+
export type SubagentStopHandler = (input: SubagentStopHookInput, invocation: {
|
|
1791
|
+
sessionId: string;
|
|
1792
|
+
}) => Promise<SubagentStopHookOutput | void> | SubagentStopHookOutput | void;
|
|
1793
|
+
/**
|
|
1794
|
+
* Configuration for session hooks
|
|
1795
|
+
*/
|
|
1796
|
+
export interface SessionHooks {
|
|
1797
|
+
/**
|
|
1798
|
+
* Called before a tool is executed
|
|
1799
|
+
*/
|
|
1800
|
+
onPreToolUse?: PreToolUseHandler;
|
|
1801
|
+
/**
|
|
1802
|
+
* Called before an MCP tool is called
|
|
1803
|
+
*/
|
|
1804
|
+
onPreMcpToolCall?: PreMcpToolCallHandler;
|
|
1805
|
+
/**
|
|
1806
|
+
* Called after a tool is executed with a successful result.
|
|
1807
|
+
*
|
|
1808
|
+
* For failed tool executions, register {@link onPostToolUseFailure} instead;
|
|
1809
|
+
* this handler does not fire for non-success results.
|
|
1810
|
+
*/
|
|
1811
|
+
onPostToolUse?: PostToolUseHandler;
|
|
1812
|
+
/**
|
|
1813
|
+
* Called after a tool execution whose result was `"failure"`.
|
|
1814
|
+
*
|
|
1815
|
+
* Register this handler alongside {@link onPostToolUse} to observe failed
|
|
1816
|
+
* tool calls — `onPostToolUse` only fires for successful results, so
|
|
1817
|
+
* without this hook failed tool calls are invisible to extensions.
|
|
1818
|
+
*/
|
|
1819
|
+
onPostToolUseFailure?: PostToolUseFailureHandler;
|
|
1820
|
+
/**
|
|
1821
|
+
* Called when the user submits a prompt
|
|
1822
|
+
*/
|
|
1823
|
+
onUserPromptSubmitted?: UserPromptSubmittedHandler;
|
|
1824
|
+
/**
|
|
1825
|
+
* Called after the runtime transforms a submitted prompt and before it is stored.
|
|
1826
|
+
*/
|
|
1827
|
+
onUserPromptTransformed?: UserPromptTransformedHandler;
|
|
1828
|
+
/**
|
|
1829
|
+
* Called when a session starts
|
|
1830
|
+
*/
|
|
1831
|
+
onSessionStart?: SessionStartHandler;
|
|
1832
|
+
/**
|
|
1833
|
+
* Called when a session ends
|
|
1834
|
+
*/
|
|
1835
|
+
onSessionEnd?: SessionEndHandler;
|
|
1836
|
+
/**
|
|
1837
|
+
* Called when an error occurs
|
|
1838
|
+
*/
|
|
1839
|
+
onErrorOccurred?: ErrorOccurredHandler;
|
|
1840
|
+
/**
|
|
1841
|
+
* Called when the top-level agent reaches a natural terminal stop (it went
|
|
1842
|
+
* idle without pending work and was not aborted). Return
|
|
1843
|
+
* `{ decision: "block", reason }` to keep the agent running with `reason`
|
|
1844
|
+
* enqueued as a follow-up message — for example, to have the agent
|
|
1845
|
+
* remediate findings the handler surfaced. Returning nothing lets the
|
|
1846
|
+
* agent stop.
|
|
1847
|
+
*/
|
|
1848
|
+
onAgentStop?: AgentStopHandler;
|
|
1849
|
+
/** Called before a sub-agent's first turn. Return context to prepend to its prompt. */
|
|
1850
|
+
onSubagentStart?: SubagentStartHandler;
|
|
1851
|
+
/**
|
|
1852
|
+
* Called after a sub-agent completes a turn. Return a block reason to
|
|
1853
|
+
* continue the child, or a replacement response to report to the parent.
|
|
1854
|
+
*/
|
|
1855
|
+
onSubagentStop?: SubagentStopHandler;
|
|
1856
|
+
}
|
|
1857
|
+
/**
|
|
1858
|
+
* Base interface for MCP server configuration.
|
|
1859
|
+
*/
|
|
1860
|
+
interface MCPServerConfigBase {
|
|
1861
|
+
/**
|
|
1862
|
+
* List of tools to include from this server.
|
|
1863
|
+
* `undefined` (the default) or `["*"]` means include all tools.
|
|
1864
|
+
* `[]` means include none.
|
|
1865
|
+
*/
|
|
1866
|
+
tools?: string[];
|
|
1867
|
+
/**
|
|
1868
|
+
* Indicates the server type: "stdio" for local/subprocess servers, "http"/"sse" for remote servers.
|
|
1869
|
+
* If not specified, defaults to "stdio".
|
|
1870
|
+
*/
|
|
1871
|
+
type?: string;
|
|
1872
|
+
/**
|
|
1873
|
+
* Optional timeout in milliseconds for tool calls to this server.
|
|
1874
|
+
*/
|
|
1875
|
+
timeout?: number;
|
|
1876
|
+
}
|
|
1877
|
+
/**
|
|
1878
|
+
* Configuration for a local/stdio MCP server.
|
|
1879
|
+
*/
|
|
1880
|
+
export interface MCPStdioServerConfig extends MCPServerConfigBase {
|
|
1881
|
+
type?: "local" | "stdio";
|
|
1882
|
+
command: string;
|
|
1883
|
+
args?: string[];
|
|
1884
|
+
/**
|
|
1885
|
+
* Environment variables to pass to the server.
|
|
1886
|
+
*/
|
|
1887
|
+
env?: Record<string, string>;
|
|
1888
|
+
/**
|
|
1889
|
+
* Working directory for the server process.
|
|
1890
|
+
*/
|
|
1891
|
+
workingDirectory?: string;
|
|
1892
|
+
}
|
|
1893
|
+
/**
|
|
1894
|
+
* Configuration for a remote MCP server (HTTP or SSE).
|
|
1895
|
+
*/
|
|
1896
|
+
export interface MCPHTTPServerConfig extends MCPServerConfigBase {
|
|
1897
|
+
type: "http" | "sse";
|
|
1898
|
+
/**
|
|
1899
|
+
* URL of the remote server.
|
|
1900
|
+
*/
|
|
1901
|
+
url: string;
|
|
1902
|
+
/**
|
|
1903
|
+
* Optional HTTP headers to include in requests.
|
|
1904
|
+
*/
|
|
1905
|
+
headers?: Record<string, string>;
|
|
1906
|
+
}
|
|
1907
|
+
/**
|
|
1908
|
+
* Union type for MCP server configurations.
|
|
1909
|
+
*/
|
|
1910
|
+
export type MCPServerConfig = MCPStdioServerConfig | MCPHTTPServerConfig;
|
|
1911
|
+
/**
|
|
1912
|
+
* Configuration for a custom agent.
|
|
1913
|
+
*/
|
|
1914
|
+
export interface CustomAgentConfig {
|
|
1915
|
+
/** Declarative hook actions keyed by event name, active only for this agent. */
|
|
1916
|
+
hooks?: Record<string, Record<string, unknown>[]>;
|
|
1917
|
+
/**
|
|
1918
|
+
* Unique name of the custom agent.
|
|
1919
|
+
*/
|
|
1920
|
+
name: string;
|
|
1921
|
+
/**
|
|
1922
|
+
* Display name for UI purposes.
|
|
1923
|
+
*/
|
|
1924
|
+
displayName?: string;
|
|
1925
|
+
/**
|
|
1926
|
+
* Description of what the agent does.
|
|
1927
|
+
*/
|
|
1928
|
+
description?: string;
|
|
1929
|
+
/**
|
|
1930
|
+
* List of tool names the agent can use.
|
|
1931
|
+
* Use null or undefined for all tools.
|
|
1932
|
+
*/
|
|
1933
|
+
tools?: string[] | null;
|
|
1934
|
+
/**
|
|
1935
|
+
* The prompt content for the agent.
|
|
1936
|
+
*/
|
|
1937
|
+
prompt: string;
|
|
1938
|
+
/**
|
|
1939
|
+
* MCP servers specific to this agent.
|
|
1940
|
+
*/
|
|
1941
|
+
mcpServers?: Record<string, MCPServerConfig>;
|
|
1942
|
+
/**
|
|
1943
|
+
* Whether the agent should be available for model inference.
|
|
1944
|
+
* @default true
|
|
1945
|
+
*/
|
|
1946
|
+
infer?: boolean;
|
|
1947
|
+
/**
|
|
1948
|
+
* List of skill names to preload into this agent's context.
|
|
1949
|
+
* When set, the full content of each listed skill is eagerly injected into
|
|
1950
|
+
* the agent's context at startup. Skills are resolved by name from the
|
|
1951
|
+
* session's configured skill directories (`skillDirectories`).
|
|
1952
|
+
* When omitted, no skills are injected (opt-in model).
|
|
1953
|
+
*/
|
|
1954
|
+
skills?: string[];
|
|
1955
|
+
/**
|
|
1956
|
+
* Model identifier for this agent (e.g. "claude-haiku-4.5").
|
|
1957
|
+
* When set, the runtime will attempt to use this model for the agent,
|
|
1958
|
+
* falling back to the parent session model if unavailable unless
|
|
1959
|
+
* `modelPolicy` is `"required"`.
|
|
1960
|
+
*/
|
|
1961
|
+
model?: string;
|
|
1962
|
+
/**
|
|
1963
|
+
* Whether the authored model is a preference or a requirement for this agent.
|
|
1964
|
+
* Defaults to `"preferred"` when omitted.
|
|
1965
|
+
*/
|
|
1966
|
+
modelPolicy?: AgentModelPolicy;
|
|
1967
|
+
/**
|
|
1968
|
+
* Reasoning effort level for this agent's model.
|
|
1969
|
+
* When omitted, the runtime resolves the effort from model configuration,
|
|
1970
|
+
* then inherits the parent effort only if this agent uses the same model.
|
|
1971
|
+
*/
|
|
1972
|
+
reasoningEffort?: ReasoningEffort;
|
|
1973
|
+
}
|
|
1974
|
+
/**
|
|
1975
|
+
* Configuration for the default agent (the built-in agent that handles
|
|
1976
|
+
* turns when no custom agent is selected).
|
|
1977
|
+
* Use this to control tool visibility for the default agent independently of custom sub-agents.
|
|
1978
|
+
*/
|
|
1979
|
+
export interface DefaultAgentConfig {
|
|
1980
|
+
/**
|
|
1981
|
+
* List of tool names to exclude from the default agent.
|
|
1982
|
+
* These tools remain available to custom sub-agents that reference them in their `tools` array.
|
|
1983
|
+
* Use this to register tools that should only be accessed via delegation to sub-agents,
|
|
1984
|
+
* keeping the default agent's context clean.
|
|
1985
|
+
*/
|
|
1986
|
+
excludedTools?: string[];
|
|
1987
|
+
}
|
|
1988
|
+
/**
|
|
1989
|
+
* Configuration for infinite sessions with automatic context compaction and workspace persistence.
|
|
1990
|
+
* When enabled, sessions automatically manage context window limits through background compaction
|
|
1991
|
+
* and persist state to a workspace directory.
|
|
1992
|
+
*/
|
|
1993
|
+
export interface InfiniteSessionConfig {
|
|
1994
|
+
/**
|
|
1995
|
+
* Whether infinite sessions are enabled.
|
|
1996
|
+
* @default true
|
|
1997
|
+
*/
|
|
1998
|
+
enabled?: boolean;
|
|
1999
|
+
/**
|
|
2000
|
+
* Context utilization threshold (0.0-1.0) at which background compaction starts.
|
|
2001
|
+
* Compaction runs asynchronously, allowing the session to continue processing.
|
|
2002
|
+
* @default 0.80
|
|
2003
|
+
*/
|
|
2004
|
+
backgroundCompactionThreshold?: number;
|
|
2005
|
+
/**
|
|
2006
|
+
* Context utilization threshold (0.0-1.0) at which the session blocks until compaction completes.
|
|
2007
|
+
* This prevents context overflow when compaction hasn't finished in time.
|
|
2008
|
+
* @default 0.95
|
|
2009
|
+
*/
|
|
2010
|
+
bufferExhaustionThreshold?: number;
|
|
2011
|
+
}
|
|
2012
|
+
/**
|
|
2013
|
+
* Configuration for the memory feature, which lets the agent persist and recall
|
|
2014
|
+
* information across turns.
|
|
2015
|
+
*/
|
|
2016
|
+
export interface MemoryConfiguration {
|
|
2017
|
+
/**
|
|
2018
|
+
* Whether the memory feature is enabled for this session.
|
|
2019
|
+
*/
|
|
2020
|
+
enabled: boolean;
|
|
2021
|
+
/**
|
|
2022
|
+
* "system-prompt" (default) places memories in the system prompt.
|
|
2023
|
+
* "user-prompt" places memories in generated user-role messages.
|
|
2024
|
+
* @experimental This option may change or be removed in a future release.
|
|
2025
|
+
*/
|
|
2026
|
+
mode?: "system-prompt" | "user-prompt";
|
|
2027
|
+
/**
|
|
2028
|
+
* Stores memories in the app instead of the built-in memory backends.
|
|
2029
|
+
*
|
|
2030
|
+
* The runtime validates the memory, filters secrets and requests approval,
|
|
2031
|
+
* then calls this callback. `store_memory` succeeds only after the returned
|
|
2032
|
+
* promise resolves; a rejection fails the tool call with a generic message
|
|
2033
|
+
* and nothing is stored elsewhere. `options.signal` aborts when the runtime
|
|
2034
|
+
* stops waiting, for example after its 60-second timeout. While set, the
|
|
2035
|
+
* runtime retrieves no memories and `vote_memory` is unavailable, so supply
|
|
2036
|
+
* recall yourself, for example through `systemMessage`.
|
|
2037
|
+
* @experimental This option may change or be removed in a future release.
|
|
2038
|
+
*/
|
|
2039
|
+
storeMemory?: (memory: StoredMemory, options: MemoryStoreCallOptions) => Promise<void>;
|
|
2040
|
+
}
|
|
2041
|
+
/**
|
|
2042
|
+
* Per-call options passed to {@link MemoryConfiguration.storeMemory}.
|
|
2043
|
+
* @experimental This type may change or be removed in a future release.
|
|
2044
|
+
*/
|
|
2045
|
+
export interface MemoryStoreCallOptions {
|
|
2046
|
+
/**
|
|
2047
|
+
* Aborted when the runtime cancels the call, for example when it times out
|
|
2048
|
+
* or the session disconnects. The runtime ignores any later result.
|
|
2049
|
+
*/
|
|
2050
|
+
signal: AbortSignal;
|
|
2051
|
+
}
|
|
2052
|
+
/**
|
|
2053
|
+
* A memory the agent asked to store, after validation, secret filtering and approval.
|
|
2054
|
+
* @experimental This type may change or be removed in a future release.
|
|
2055
|
+
*/
|
|
2056
|
+
export interface StoredMemory {
|
|
2057
|
+
/** ID of the session that stored the memory. */
|
|
2058
|
+
sessionId: string;
|
|
2059
|
+
/** Short topic the memory is about. */
|
|
2060
|
+
subject: string;
|
|
2061
|
+
/** The fact to remember. */
|
|
2062
|
+
fact: string;
|
|
2063
|
+
/** Sources supporting the fact, such as file paths with line numbers. */
|
|
2064
|
+
citations: string;
|
|
2065
|
+
/** Why the agent considers the fact worth remembering. */
|
|
2066
|
+
reason: string;
|
|
2067
|
+
}
|
|
2068
|
+
/**
|
|
2069
|
+
* Configuration for handling large tool outputs.
|
|
2070
|
+
*
|
|
2071
|
+
* When a tool produces output exceeding the configured size, the output is
|
|
2072
|
+
* written to a temp file and a reference is returned to the model instead of
|
|
2073
|
+
* the full payload.
|
|
2074
|
+
*/
|
|
2075
|
+
export interface LargeToolOutputConfig {
|
|
2076
|
+
/**
|
|
2077
|
+
* Whether large output handling is enabled.
|
|
2078
|
+
* @default true
|
|
2079
|
+
*/
|
|
2080
|
+
enabled?: boolean;
|
|
2081
|
+
/**
|
|
2082
|
+
* Maximum size in bytes before output is written to a temp file.
|
|
2083
|
+
* Uses the runtime's configured threshold when unset.
|
|
2084
|
+
* @default 20480
|
|
2085
|
+
*/
|
|
2086
|
+
maxSizeBytes?: number;
|
|
2087
|
+
/**
|
|
2088
|
+
* Directory to write temp files to. Defaults to the OS temp directory.
|
|
2089
|
+
*/
|
|
2090
|
+
outputDirectory?: string;
|
|
2091
|
+
}
|
|
2092
|
+
/**
|
|
2093
|
+
* Model-defined reasoning effort for models that support it.
|
|
2094
|
+
* Use client.listModels() to discover supported values; BYOK providers can define additional levels.
|
|
2095
|
+
*/
|
|
2096
|
+
export type ReasoningEffort = string;
|
|
2097
|
+
/**
|
|
2098
|
+
* Context window tier for the session. "long_context" pins the session to the
|
|
2099
|
+
* long-context tier when the selected model supports it.
|
|
2100
|
+
*/
|
|
2101
|
+
export type ContextTier = "default" | "long_context";
|
|
2102
|
+
/**
|
|
2103
|
+
* Scope of a working-directory trust grant made during session creation.
|
|
2104
|
+
*/
|
|
2105
|
+
export type WorkingDirectoryTrust = "session" | "user";
|
|
2106
|
+
/** Parsed parameters from an MCP server's WWW-Authenticate response. */
|
|
2107
|
+
export interface McpAuthWwwAuthenticateParams {
|
|
2108
|
+
/** Parsed resource_metadata URL used for protected-resource metadata discovery, if present. */
|
|
2109
|
+
resourceMetadataUrl?: string;
|
|
2110
|
+
/** Parsed OAuth scope, if present. */
|
|
2111
|
+
scope?: string;
|
|
2112
|
+
/** Parsed OAuth error, if present. */
|
|
2113
|
+
error?: string;
|
|
2114
|
+
}
|
|
2115
|
+
/** Static OAuth client configuration supplied by the MCP server, if available. */
|
|
2116
|
+
export interface McpAuthStaticClientConfig {
|
|
2117
|
+
/** OAuth client ID for the server. */
|
|
2118
|
+
clientId: string;
|
|
2119
|
+
/** Optional OAuth client secret for confidential static clients. */
|
|
2120
|
+
clientSecret?: string;
|
|
2121
|
+
/** Optional non-default OAuth grant type. */
|
|
2122
|
+
grantType?: "client_credentials";
|
|
2123
|
+
/** Whether this is a public OAuth client. */
|
|
2124
|
+
publicClient?: boolean;
|
|
2125
|
+
/** Configured OAuth scope string used when the server challenge omits scope. */
|
|
2126
|
+
scope?: string;
|
|
2127
|
+
}
|
|
2128
|
+
/** MCP OAuth request that the SDK host can satisfy with a host-acquired token. */
|
|
2129
|
+
export interface McpAuthRequest {
|
|
2130
|
+
/** Unique request identifier used by the SDK when responding. */
|
|
2131
|
+
requestId: string;
|
|
2132
|
+
/** Display name of the MCP server that requires OAuth. */
|
|
2133
|
+
serverName: string;
|
|
2134
|
+
/** URL of the MCP server that requires OAuth. */
|
|
2135
|
+
serverUrl: string;
|
|
2136
|
+
/** Why the runtime is requesting host-provided OAuth credentials. */
|
|
2137
|
+
reason: "initial" | "refresh" | "reauth" | "upscope";
|
|
2138
|
+
/** Whether this Refresh request supports noninteractive runtime handoff. Missing means false. */
|
|
2139
|
+
runtimeRefreshSupported?: boolean;
|
|
2140
|
+
/** Parsed WWW-Authenticate parameters from the MCP server. */
|
|
2141
|
+
wwwAuthenticateParams?: McpAuthWwwAuthenticateParams;
|
|
2142
|
+
/** Raw RFC 9728 protected-resource metadata JSON fetched by the runtime, if available. */
|
|
2143
|
+
resourceMetadata?: string;
|
|
2144
|
+
/** Static OAuth client configuration, if the server specifies one. */
|
|
2145
|
+
staticClientConfig?: McpAuthStaticClientConfig;
|
|
2146
|
+
}
|
|
2147
|
+
/** Host-provided OAuth token data for a pending MCP OAuth request. */
|
|
2148
|
+
export interface McpAuthToken {
|
|
2149
|
+
/** Access token acquired by the SDK host. */
|
|
2150
|
+
accessToken: string;
|
|
2151
|
+
/** OAuth token type. Defaults to Bearer when omitted. */
|
|
2152
|
+
tokenType?: string;
|
|
2153
|
+
/** Token lifetime in seconds, if known. */
|
|
2154
|
+
expiresIn?: number;
|
|
2155
|
+
}
|
|
2156
|
+
/**
|
|
2157
|
+
* Result returned by an MCP auth request handler.
|
|
2158
|
+
*
|
|
2159
|
+
* Return `null`/`undefined` or `{ kind: "cancelled" }` to cancel the pending
|
|
2160
|
+
* OAuth request. Return `{ kind: "token", ... }` to provide host-acquired
|
|
2161
|
+
* OAuth token data. Return `{ kind: "runtimeRefresh" }` only for a Refresh
|
|
2162
|
+
* request advertising `runtimeRefreshSupported`; acceptance is not reconnect completion.
|
|
2163
|
+
*/
|
|
2164
|
+
export type McpAuthResult = ({
|
|
2165
|
+
kind: "token";
|
|
2166
|
+
} & McpAuthToken) | {
|
|
2167
|
+
kind: "cancelled";
|
|
2168
|
+
} | {
|
|
2169
|
+
kind: "runtimeRefresh";
|
|
2170
|
+
};
|
|
2171
|
+
/** Callback invoked when an MCP server requires OAuth and the SDK host opted in. */
|
|
2172
|
+
export type McpAuthHandler = (request: McpAuthRequest, context: {
|
|
2173
|
+
sessionId: string;
|
|
2174
|
+
}) => McpAuthResult | McpAuthToken | null | undefined | Promise<McpAuthResult | McpAuthToken | null | undefined>;
|
|
2175
|
+
/**
|
|
2176
|
+
* Stable extension identity for session participants that provide canvases.
|
|
2177
|
+
*/
|
|
2178
|
+
export interface ExtensionInfo {
|
|
2179
|
+
/** Extension namespace/source, e.g. "github-app". */
|
|
2180
|
+
source: string;
|
|
2181
|
+
/** Stable provider name within the source namespace. */
|
|
2182
|
+
name: string;
|
|
2183
|
+
}
|
|
2184
|
+
/**
|
|
2185
|
+
* Stable identity for a host/SDK connection that supplies built-in canvases.
|
|
2186
|
+
*
|
|
2187
|
+
* When set on session create or resume, the runtime uses {@link id} verbatim
|
|
2188
|
+
* as the agent-facing canvas extension id, so canvases declared on a control
|
|
2189
|
+
* connection survive stdio reconnect and CLI process restart instead of being
|
|
2190
|
+
* re-keyed to a per-connection id. The id is opaque to the runtime; a
|
|
2191
|
+
* per-window-stable value such as `app:builtin:<windowId>` is recommended. An
|
|
2192
|
+
* id beginning with `connection:` is reserved and ignored by the runtime.
|
|
2193
|
+
*/
|
|
2194
|
+
export interface CanvasProviderIdentity {
|
|
2195
|
+
/** Opaque, stable provider id used verbatim as the canvas extension id. */
|
|
2196
|
+
id: string;
|
|
2197
|
+
/** Optional display name surfaced as the canvas extension name. */
|
|
2198
|
+
name?: string;
|
|
2199
|
+
}
|
|
2200
|
+
/**
|
|
2201
|
+
* Provider-scoped options for the Copilot API (CAPI).
|
|
2202
|
+
*
|
|
2203
|
+
* These settings apply to the built-in Copilot API provider only. They live
|
|
2204
|
+
* under their own namespace because a single session can host multiple
|
|
2205
|
+
* providers (CAPI alongside BYOK via {@link ProviderConfig}), so transport and
|
|
2206
|
+
* provider-level choices are conceptually per-provider rather than global.
|
|
2207
|
+
*/
|
|
2208
|
+
export interface CapiSessionOptions {
|
|
2209
|
+
/**
|
|
2210
|
+
* Routing preference used when the session model is `auto`.
|
|
2211
|
+
* Requires a runtime with Auto tier support and V2 Auto routing.
|
|
2212
|
+
*
|
|
2213
|
+
* When omitted on create, the runtime uses its default routing behavior.
|
|
2214
|
+
* The runtime persists this preference across cold resume; when omitted on
|
|
2215
|
+
* cold resume, it restores the last committed preference. On resident
|
|
2216
|
+
* resume, a different tier requests a safe switch that takes effect after
|
|
2217
|
+
* resume succeeds, and never disturbs a turn that is already running.
|
|
2218
|
+
*
|
|
2219
|
+
* To change the preference on a live session, call
|
|
2220
|
+
* {@link CopilotSession.setAutoTier} instead.
|
|
2221
|
+
*
|
|
2222
|
+
* For Copilot Fusion, prefer {@link fusionTier}. The `balance`,
|
|
2223
|
+
* `hydrafusion` and `hydrafusion-max` identifiers it replaces remain
|
|
2224
|
+
* accepted but are deprecated.
|
|
2225
|
+
*/
|
|
2226
|
+
autoTier?: AutoTier;
|
|
2227
|
+
/**
|
|
2228
|
+
* Copilot Fusion tier used when the session model is `fusion` or `auto`,
|
|
2229
|
+
* matching the CLI's `--fusion-tier`: `standard`, `high` or `max`.
|
|
2230
|
+
*
|
|
2231
|
+
* The runtime resolves the tier to the Auto routing preference it stands
|
|
2232
|
+
* for, using the same runtime-owned bindings as the CLI, and then applies it
|
|
2233
|
+
* exactly like {@link autoTier}, so `session.rpc.model.getCurrent()` and
|
|
2234
|
+
* `session.model_change` events report that preference as `autoTier`;
|
|
2235
|
+
* `getCurrent()` also reports the resolved tier as `fusionTier` once the
|
|
2236
|
+
* session's Auto tier metadata is known.
|
|
2237
|
+
* Cannot be combined with {@link autoTier}.
|
|
2238
|
+
*
|
|
2239
|
+
* To change the tier on a live session, call
|
|
2240
|
+
* {@link CopilotSession.setFusionTier} instead.
|
|
2241
|
+
*
|
|
2242
|
+
* @experimental Part of an experimental Auto routing surface and may
|
|
2243
|
+
* change or be removed in a future release.
|
|
2244
|
+
*/
|
|
2245
|
+
fusionTier?: FusionTier;
|
|
2246
|
+
/**
|
|
2247
|
+
* Whether to use the WebSocket transport for the CAPI Responses API.
|
|
2248
|
+
*
|
|
2249
|
+
* WebSocket transport is enabled by default whenever the selected model
|
|
2250
|
+
* advertises the `ws:/responses` endpoint. Set this to `false` to fall back
|
|
2251
|
+
* to the HTTP Responses transport instead — useful for users behind proxies
|
|
2252
|
+
* where WebSocket connections fail.
|
|
2253
|
+
*
|
|
2254
|
+
* Setting this to `false` is equivalent to setting the
|
|
2255
|
+
* `COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES` environment variable.
|
|
2256
|
+
*
|
|
2257
|
+
* @default true
|
|
2258
|
+
*/
|
|
2259
|
+
enableWebSocketResponses?: boolean;
|
|
2260
|
+
}
|
|
2261
|
+
/**
|
|
2262
|
+
* A single ExP (Experiment Platform) flag value. ExP assignments resolve to a
|
|
2263
|
+
* string, number, boolean, or `null`.
|
|
2264
|
+
*/
|
|
2265
|
+
export type ExpFlagValue = string | number | boolean | null;
|
|
2266
|
+
/**
|
|
2267
|
+
* A single configuration entry in a {@link CopilotExpAssignmentResponse}. Each
|
|
2268
|
+
* entry carries an identifier and a bag of typed parameter values.
|
|
2269
|
+
*/
|
|
2270
|
+
export interface ExpConfigEntry {
|
|
2271
|
+
/** Identifier of the configuration entry. */
|
|
2272
|
+
Id: string;
|
|
2273
|
+
/** Parameter values keyed by parameter name. */
|
|
2274
|
+
Parameters: Record<string, ExpFlagValue>;
|
|
2275
|
+
}
|
|
2276
|
+
/**
|
|
2277
|
+
* ExP ("flight") assignment data, in the same JSON shape the Copilot CLI
|
|
2278
|
+
* fetches from the experimentation service. Field names are PascalCase to match
|
|
2279
|
+
* the on-the-wire contract consumed by the runtime.
|
|
2280
|
+
*/
|
|
2281
|
+
export interface CopilotExpAssignmentResponse {
|
|
2282
|
+
/** Enabled feature names. */
|
|
2283
|
+
Features: string[];
|
|
2284
|
+
/** Assigned flights keyed by flight name. */
|
|
2285
|
+
Flights: Record<string, string>;
|
|
2286
|
+
/** Configuration entries carrying typed parameter values. */
|
|
2287
|
+
Configs: ExpConfigEntry[];
|
|
2288
|
+
/** Opaque parameter-group payload passed through untouched. */
|
|
2289
|
+
ParameterGroups?: unknown;
|
|
2290
|
+
/** Version of the flighting configuration. */
|
|
2291
|
+
FlightingVersion?: number;
|
|
2292
|
+
/** Impression identifier for the assignment. */
|
|
2293
|
+
ImpressionId?: string;
|
|
2294
|
+
/** Assignment context string forwarded to CAPI and telemetry. */
|
|
2295
|
+
AssignmentContext: string;
|
|
2296
|
+
}
|
|
2297
|
+
/**
|
|
2298
|
+
* Configuration for the built-in GitHub MCP server.
|
|
2299
|
+
*
|
|
2300
|
+
* `disableFormDeferral` only applies to the built-in GitHub MCP server and
|
|
2301
|
+
* only has an effect when MCP Apps and form-backed GitHub tools are enabled.
|
|
2302
|
+
*/
|
|
2303
|
+
export interface GitHubMcpToolConfig {
|
|
2304
|
+
enableAllTools?: boolean;
|
|
2305
|
+
additionalToolsets?: string[];
|
|
2306
|
+
additionalTools?: string[];
|
|
2307
|
+
enableInsidersMode?: boolean;
|
|
2308
|
+
disableFormDeferral?: boolean;
|
|
2309
|
+
}
|
|
2310
|
+
/** Well-known managed bypass-permissions policies. */
|
|
2311
|
+
export declare const DisableBypassPermissionsModes: {
|
|
2312
|
+
/** Turn off bypass-permissions mode entirely. */
|
|
2313
|
+
readonly Disable: "disable";
|
|
2314
|
+
/** Permit automatic bypass but block full allow-all. */
|
|
2315
|
+
readonly AllowAutoOnly: "allow-auto-only";
|
|
2316
|
+
};
|
|
2317
|
+
/**
|
|
2318
|
+
* Permissions-only managed policy injected by the host via
|
|
2319
|
+
* {@link SessionConfigBase.managedSettings}.
|
|
2320
|
+
*
|
|
2321
|
+
* Rule strings use the same vocabulary the runtime accepts for fetched managed
|
|
2322
|
+
* policy (e.g. `"Read(**)"`, `"Shell(git push *)"`); malformed rules are
|
|
2323
|
+
* rejected at session creation.
|
|
2324
|
+
*/
|
|
2325
|
+
export interface ManagedSettingsPermissions {
|
|
2326
|
+
/**
|
|
2327
|
+
* Restricts bypass-permissions mode for the session. See
|
|
2328
|
+
* {@link DisableBypassPermissionsModes} for well-known values. Unknown
|
|
2329
|
+
* values are forwarded so newer runtime policies fail closed.
|
|
2330
|
+
*/
|
|
2331
|
+
disableBypassPermissionsMode?: string;
|
|
2332
|
+
/**
|
|
2333
|
+
* When true, prevents Assisted Permissions from being activated. Omit or
|
|
2334
|
+
* set to false to impose no restriction.
|
|
2335
|
+
*/
|
|
2336
|
+
disableAssistedPermissionsMode?: boolean;
|
|
2337
|
+
/** Operations that must always be denied. Unioned across managed layers. */
|
|
2338
|
+
deny?: string[];
|
|
2339
|
+
/**
|
|
2340
|
+
* Operations that must prompt for approval. Unioned across managed layers.
|
|
2341
|
+
*/
|
|
2342
|
+
ask?: string[];
|
|
2343
|
+
/**
|
|
2344
|
+
* Operations permitted without prompting. Every declared `allow` list
|
|
2345
|
+
* (across managed layers) must admit an operation for it to be allowed.
|
|
2346
|
+
*/
|
|
2347
|
+
allow?: string[];
|
|
2348
|
+
/**
|
|
2349
|
+
* Closed-world host boundary expressed as `Domain(hostname)`, `Domain(IP)`,
|
|
2350
|
+
* or `Domain(*.example.com)` rules. Schemes, ports, paths, queries, and
|
|
2351
|
+
* fragments are rejected. Multiple managed layers intersect their lists;
|
|
2352
|
+
* an empty list denies all hosts.
|
|
2353
|
+
*/
|
|
2354
|
+
limitTo?: string[];
|
|
2355
|
+
}
|
|
2356
|
+
/**
|
|
2357
|
+
* Host-injected enterprise managed settings. The first supported contract is
|
|
2358
|
+
* permissions-only; unknown sibling keys are rejected by the runtime.
|
|
2359
|
+
*
|
|
2360
|
+
* @see {@link SessionConfigBase.managedSettings}
|
|
2361
|
+
*/
|
|
2362
|
+
export interface ManagedSettings {
|
|
2363
|
+
/** Managed permission policy for the session. */
|
|
2364
|
+
permissions?: ManagedSettingsPermissions;
|
|
2365
|
+
}
|
|
2366
|
+
/** Selects the model-facing shape of the built-in `ask_user` tool. */
|
|
2367
|
+
export type AskUserVariant = "legacy" | "elicitation";
|
|
2368
|
+
/**
|
|
2369
|
+
* Supplies session-scoped skills from the host's own storage, such as a
|
|
2370
|
+
* database, instead of `SKILL.md` files on disk.
|
|
2371
|
+
*
|
|
2372
|
+
* The runtime calls {@link SkillProvider.listSkills} when it builds the
|
|
2373
|
+
* session's skill catalog, and {@link SkillProvider.readSkill} each time it
|
|
2374
|
+
* needs a skill's instructions: when the model loads the skill through the
|
|
2375
|
+
* `skill` tool, when a user runs `/skill-name`, or when a custom agent lists
|
|
2376
|
+
* the skill. Calls may run concurrently, including on behalf of sub-agents, and
|
|
2377
|
+
* each call must finish within 30 seconds. Errors thrown by a provider are
|
|
2378
|
+
* never shown to the model.
|
|
2379
|
+
*
|
|
2380
|
+
* Supply a provider with {@link SessionConfigBase.skillProvider}. Providers
|
|
2381
|
+
* aren't supported for cloud sessions.
|
|
2382
|
+
*
|
|
2383
|
+
* @experimental Session-scoped skill providers are experimental and may change
|
|
2384
|
+
* or be removed in future SDK or CLI releases.
|
|
2385
|
+
*/
|
|
2386
|
+
export interface SkillProvider {
|
|
2387
|
+
/**
|
|
2388
|
+
* Returns catalog metadata for every skill the provider supplies. The
|
|
2389
|
+
* descriptors are authoritative: names must be unique ignoring case, and
|
|
2390
|
+
* the runtime validates their limits.
|
|
2391
|
+
*/
|
|
2392
|
+
listSkills(options: SkillProviderCallOptions): SkillProviderDescriptor[] | Promise<SkillProviderDescriptor[]>;
|
|
2393
|
+
/**
|
|
2394
|
+
* Returns the `SKILL.md` text for the named skill, or `null`/`undefined`
|
|
2395
|
+
* when the skill no longer exists.
|
|
2396
|
+
*
|
|
2397
|
+
* YAML frontmatter is optional. Fields it omits come from the skill's
|
|
2398
|
+
* descriptor, fields it declares must match the descriptor, and
|
|
2399
|
+
* `allowed-tools` can only be set there. Text whose first line is `---` is
|
|
2400
|
+
* parsed as frontmatter.
|
|
2401
|
+
*
|
|
2402
|
+
* @param name - The skill's name, as listed by {@link SkillProvider.listSkills}.
|
|
2403
|
+
*/
|
|
2404
|
+
readSkill(name: string, options: SkillProviderCallOptions): string | null | undefined | Promise<string | null | undefined>;
|
|
2405
|
+
}
|
|
2406
|
+
/**
|
|
2407
|
+
* Per-call options passed to {@link SkillProvider} methods.
|
|
2408
|
+
*
|
|
2409
|
+
* @experimental Session-scoped skill providers are experimental and may change
|
|
2410
|
+
* or be removed in future SDK or CLI releases.
|
|
2411
|
+
*/
|
|
2412
|
+
export interface SkillProviderCallOptions {
|
|
2413
|
+
/**
|
|
2414
|
+
* Aborted when the runtime cancels the call, for example when it times out
|
|
2415
|
+
* or the session disconnects. The runtime ignores any later result.
|
|
2416
|
+
*/
|
|
2417
|
+
signal: AbortSignal;
|
|
2418
|
+
}
|
|
2419
|
+
/**
|
|
2420
|
+
* Shared configuration fields used by both {@link SessionConfig} (for
|
|
2421
|
+
* creating a new session) and {@link ResumeSessionConfig} (for resuming
|
|
2422
|
+
* an existing one).
|
|
2423
|
+
*/
|
|
2424
|
+
export interface SessionConfigBase {
|
|
2425
|
+
/**
|
|
2426
|
+
* Whether the model may request multiple tool calls per response. Defaults to true.
|
|
2427
|
+
* False sends a provider hint, not an execution guarantee: all returned calls
|
|
2428
|
+
* are still handled and handlers may run concurrently. Re-supply on cold resume.
|
|
2429
|
+
*/
|
|
2430
|
+
allowMultipleToolCalls?: boolean;
|
|
2431
|
+
/** Exact model IDs allowed by the host. Omission preserves runtime policy. */
|
|
2432
|
+
allowedModels?: string[];
|
|
2433
|
+
/**
|
|
2434
|
+
* Client name to identify the application using the SDK.
|
|
2435
|
+
* Included in the User-Agent header for API requests.
|
|
2436
|
+
*/
|
|
2437
|
+
clientName?: string;
|
|
2438
|
+
/**
|
|
2439
|
+
* Model to use for this session
|
|
2440
|
+
*/
|
|
2441
|
+
model?: string;
|
|
2442
|
+
/**
|
|
2443
|
+
* Reasoning effort level for models that support it.
|
|
2444
|
+
* Only valid for models where capabilities.supports.reasoningEffort is true.
|
|
2445
|
+
* Use client.listModels() to check supported values for each model.
|
|
2446
|
+
*/
|
|
2447
|
+
reasoningEffort?: ReasoningEffort;
|
|
2448
|
+
/**
|
|
2449
|
+
* Reasoning summary mode for models that support configurable reasoning summaries.
|
|
2450
|
+
* Use "none" to suppress summary output regardless of whether reasoning is enabled.
|
|
2451
|
+
*/
|
|
2452
|
+
reasoningSummary?: ReasoningSummary;
|
|
2453
|
+
/**
|
|
2454
|
+
* Controls whether the session enables experimental features.
|
|
2455
|
+
* Defaults to `false` in `"empty"` mode; otherwise the runtime decides when unset.
|
|
2456
|
+
*/
|
|
2457
|
+
enableExperimentalMode?: boolean;
|
|
2458
|
+
/**
|
|
2459
|
+
* Context window tier for models that support it. Use "long_context" to pin
|
|
2460
|
+
* the session to the long-context tier; omit or use "default" otherwise.
|
|
2461
|
+
*/
|
|
2462
|
+
contextTier?: ContextTier;
|
|
2463
|
+
/**
|
|
2464
|
+
* Enables session-scoped MCP diagnostic capture at the requested level.
|
|
2465
|
+
*
|
|
2466
|
+
* Diagnostics are off by default. At `"debug"` and `"trace"` levels, entries
|
|
2467
|
+
* can contain MCP payloads, tool arguments, paths, and server stderr. Do not
|
|
2468
|
+
* upload entries as telemetry or export them without deliberate host action.
|
|
2469
|
+
* Omit this option when resuming a resident session to preserve its current
|
|
2470
|
+
* diagnostic level.
|
|
2471
|
+
*/
|
|
2472
|
+
diagnostics?: DiagnosticsConfiguration;
|
|
2473
|
+
/** Per-property overrides for model capabilities, deep-merged over runtime defaults. */
|
|
2474
|
+
modelCapabilities?: ModelCapabilitiesOverride;
|
|
2475
|
+
/**
|
|
2476
|
+
* Configuration for handling large tool outputs. When a tool produces
|
|
2477
|
+
* output exceeding the configured size, the output is written to a temp
|
|
2478
|
+
* file and a reference is returned to the model instead of the full
|
|
2479
|
+
* payload.
|
|
2480
|
+
*/
|
|
2481
|
+
largeOutput?: LargeToolOutputConfig;
|
|
2482
|
+
/**
|
|
2483
|
+
* Override the default configuration directory location.
|
|
2484
|
+
* When specified, the session will use this directory for storing config and state.
|
|
2485
|
+
*/
|
|
2486
|
+
configDirectory?: string;
|
|
2487
|
+
/**
|
|
2488
|
+
* Enables runtime discovery of supported configuration. Explicitly supplied
|
|
2489
|
+
* configuration takes precedence over discovered values.
|
|
2490
|
+
*
|
|
2491
|
+
* @default false
|
|
2492
|
+
*/
|
|
2493
|
+
enableConfigDiscovery?: boolean;
|
|
2494
|
+
/**
|
|
2495
|
+
* Tools exposed to the CLI server. Tools without a handler are declaration-only
|
|
2496
|
+
* and must be resolved by the consumer via pending external tool request RPCs.
|
|
2497
|
+
*/
|
|
2498
|
+
tools?: Tool<any>[];
|
|
2499
|
+
/**
|
|
2500
|
+
* Canvases contributed by this session participant. The declaring
|
|
2501
|
+
* connection becomes the live provider for `canvas.open|focus|close|reload`
|
|
2502
|
+
* and `canvas.action.invoke` dispatches targeting each canvas's `id` for
|
|
2503
|
+
* the lifetime of the connection. Re-declaring the same id on resume
|
|
2504
|
+
* replaces the prior declaration.
|
|
2505
|
+
*/
|
|
2506
|
+
canvases?: Canvas[];
|
|
2507
|
+
/**
|
|
2508
|
+
* Renderer-side opt-in: when true, the runtime surfaces canvas agent tools
|
|
2509
|
+
* (`list_canvas_capabilities`, `open_canvas`, `invoke_canvas_action`) to
|
|
2510
|
+
* the model for this connection. Default off so SDK callers that cannot
|
|
2511
|
+
* display canvases stay clean.
|
|
2512
|
+
*/
|
|
2513
|
+
requestCanvasRenderer?: boolean;
|
|
2514
|
+
/**
|
|
2515
|
+
* Extension surface opt-in: when true, the runtime wires extension
|
|
2516
|
+
* management tools and per-extension tool dispatch onto the session for
|
|
2517
|
+
* this connection. Default off so callers that do not expose extensions
|
|
2518
|
+
* stay clean.
|
|
2519
|
+
*/
|
|
2520
|
+
requestExtensions?: boolean;
|
|
2521
|
+
/**
|
|
2522
|
+
* Optional override path to a `copilot-sdk/` folder to inject into
|
|
2523
|
+
* extension subprocesses for this session in place of the bundled SDK.
|
|
2524
|
+
* When unset or invalid (missing folder or missing `index.js` /
|
|
2525
|
+
* `extension.js`), the runtime falls back to the bundled SDK without
|
|
2526
|
+
* throwing. Takes precedence over any server-level default.
|
|
2527
|
+
*
|
|
2528
|
+
* Only honored on session create and resume — extensions joining via
|
|
2529
|
+
* `joinSession` cannot override the SDK path, because the extension
|
|
2530
|
+
* subprocess has already been forked by the host with the SDK the host
|
|
2531
|
+
* chose. `JoinSessionConfig` omits this field for that reason.
|
|
2532
|
+
*/
|
|
2533
|
+
extensionSdkPath?: string;
|
|
2534
|
+
/**
|
|
2535
|
+
* Stable extension identity for canvas providers on this connection. When
|
|
2536
|
+
* set, the runtime uses `${source}:${name}` as the agent-facing extension
|
|
2537
|
+
* id instead of a reconnect-specific connection id.
|
|
2538
|
+
*/
|
|
2539
|
+
extensionInfo?: ExtensionInfo;
|
|
2540
|
+
/**
|
|
2541
|
+
* Stable identity for a host/SDK connection that supplies built-in
|
|
2542
|
+
* canvases. When set, the runtime uses `id` verbatim as the agent-facing
|
|
2543
|
+
* canvas extension id, so canvases declared on a control connection survive
|
|
2544
|
+
* reconnect and CLI restart. Honored on session create and resume.
|
|
2545
|
+
*/
|
|
2546
|
+
canvasProvider?: CanvasProviderIdentity;
|
|
2547
|
+
/**
|
|
2548
|
+
* Slash commands registered for this session.
|
|
2549
|
+
* When the CLI has a TUI, each command appears as `/name` for the user to invoke.
|
|
2550
|
+
* The handler is called when the user executes the command.
|
|
2551
|
+
*/
|
|
2552
|
+
commands?: CommandDefinition[];
|
|
2553
|
+
/**
|
|
2554
|
+
* System message configuration
|
|
2555
|
+
* Controls how the system prompt is constructed
|
|
2556
|
+
*/
|
|
2557
|
+
systemMessage?: SystemMessageConfig;
|
|
2558
|
+
/**
|
|
2559
|
+
* Override for the runtime's built-in tool-search behavior.
|
|
2560
|
+
*
|
|
2561
|
+
* To also override the tool-search tool's implementation, register a
|
|
2562
|
+
* {@link Tool} named `tool_search_tool` with `overridesBuiltInTool: true` in
|
|
2563
|
+
* {@link SessionConfigBase.tools}.
|
|
2564
|
+
*/
|
|
2565
|
+
toolSearch?: ToolSearchConfig;
|
|
2566
|
+
/**
|
|
2567
|
+
* Image generation opt-in. Re-supply after runtime restart.
|
|
2568
|
+
* @experimental This API may change or be removed in a future release.
|
|
2569
|
+
*/
|
|
2570
|
+
imageGeneration?: ImageGenerationConfig;
|
|
2571
|
+
/**
|
|
2572
|
+
* List of tool names to allow. When specified, only these tools will be available.
|
|
2573
|
+
*
|
|
2574
|
+
* Supports source-qualified filter patterns (`builtin:*`, `builtin:<name>`,
|
|
2575
|
+
* `mcp:*`, `mcp:<name>`, `custom:*`, `custom:<name>`) as well as the bare
|
|
2576
|
+
* name form (exact match across any source). Build this list with
|
|
2577
|
+
* {@link ToolSet} for type safety and readable intent.
|
|
2578
|
+
*
|
|
2579
|
+
* Composes with {@link excludedTools}: a tool is enabled when it matches
|
|
2580
|
+
* `availableTools` (or `availableTools` is unset) AND it does not match
|
|
2581
|
+
* `excludedTools`. This lets you express "everything matching X except Y".
|
|
2582
|
+
*/
|
|
2583
|
+
availableTools?: string[] | ToolSet;
|
|
2584
|
+
/**
|
|
2585
|
+
* List of tool names to disable. Supports the same pattern syntax as
|
|
2586
|
+
* {@link availableTools}.
|
|
2587
|
+
*
|
|
2588
|
+
* Always takes precedence over {@link availableTools}: a tool listed here
|
|
2589
|
+
* is disabled even if it also matches `availableTools`.
|
|
2590
|
+
*/
|
|
2591
|
+
excludedTools?: string[] | ToolSet;
|
|
2592
|
+
/**
|
|
2593
|
+
* Names of built-in agents to exclude from the session. Excluded built-in
|
|
2594
|
+
* agents are hidden from discovery and cannot be selected or invoked unless
|
|
2595
|
+
* a custom agent with the same name is configured.
|
|
2596
|
+
*/
|
|
2597
|
+
excludedBuiltinAgents?: string[];
|
|
2598
|
+
/**
|
|
2599
|
+
* Built-in subagent names to allow, subject to availability and
|
|
2600
|
+
* {@link excludedBuiltinAgents}. An empty array disables all built-in
|
|
2601
|
+
* subagents; custom agents remain available, including same-name agents.
|
|
2602
|
+
* Omission uses defaults on create or cold resume and preserves the current
|
|
2603
|
+
* allowlist on warm resume. Not persisted; re-supply on resume after restart.
|
|
2604
|
+
*/
|
|
2605
|
+
includedBuiltinAgents?: string[];
|
|
2606
|
+
/**
|
|
2607
|
+
* Built-in skill names to include in the session. In `mode: "empty"`,
|
|
2608
|
+
* omitting this option excludes all runtime-bundled skills; specifying names
|
|
2609
|
+
* opts those built-ins back in. Skills from other sources remain eligible.
|
|
2610
|
+
*/
|
|
2611
|
+
includedBuiltinSkills?: string[];
|
|
2612
|
+
/**
|
|
2613
|
+
* Custom provider configuration (BYOK - Bring Your Own Key).
|
|
2614
|
+
* When specified, uses the provided API endpoint instead of the Copilot API.
|
|
2615
|
+
*/
|
|
2616
|
+
provider?: ProviderConfig;
|
|
2617
|
+
/**
|
|
2618
|
+
* Provider-scoped options for the built-in Copilot API (CAPI), such as
|
|
2619
|
+
* opting out of the WebSocket Responses transport. See
|
|
2620
|
+
* {@link CapiSessionOptions}.
|
|
2621
|
+
*/
|
|
2622
|
+
capi?: CapiSessionOptions;
|
|
2623
|
+
/**
|
|
2624
|
+
* Named BYOK provider connections (transport + credentials), referenced by
|
|
2625
|
+
* {@link models} entries via {@link NamedProviderConfig.name}.
|
|
2626
|
+
*
|
|
2627
|
+
* Unlike the singular {@link provider} — which makes the entire session BYOK
|
|
2628
|
+
* and bypasses Copilot API authentication — named providers are **additive**:
|
|
2629
|
+
* they coexist with Copilot API auth so models from CAPI and one or more BYOK
|
|
2630
|
+
* providers can be mixed within a single session and across sub-agents.
|
|
2631
|
+
* Combining `providers`/`models` with {@link provider} is rejected.
|
|
2632
|
+
*
|
|
2633
|
+
* @experimental This is part of an experimental multi-provider BYOK surface
|
|
2634
|
+
* and may change or be removed in future SDK or CLI releases.
|
|
2635
|
+
*/
|
|
2636
|
+
providers?: NamedProviderConfig[];
|
|
2637
|
+
/**
|
|
2638
|
+
* BYOK model definitions added to the session's selectable model list, each
|
|
2639
|
+
* referencing a `providers[].name`. Each model surfaces under the
|
|
2640
|
+
* provider-qualified selection id `providerName/id`, so BYOK ids never collide
|
|
2641
|
+
* with — and cannot shadow — bare CAPI ids; duplicate selection ids are rejected.
|
|
2642
|
+
*
|
|
2643
|
+
* @experimental This is part of an experimental multi-provider BYOK surface
|
|
2644
|
+
* and may change or be removed in future SDK or CLI releases.
|
|
2645
|
+
*/
|
|
2646
|
+
models?: ProviderModelConfig[];
|
|
2647
|
+
/**
|
|
2648
|
+
* Enables or disables internal session telemetry for this session.
|
|
2649
|
+
* `false` disables it; `true` enables it for eligible GitHub-authenticated sessions,
|
|
2650
|
+
* including custom {@link provider} (BYOK) sessions. Omission preserves a resident
|
|
2651
|
+
* session's choice; otherwise defaults to enabled. Host and account policies still
|
|
2652
|
+
* determine whether telemetry can be uploaded.
|
|
2653
|
+
* This is independent of the OpenTelemetry configuration in {@link CopilotClientOptions.telemetry}.
|
|
2654
|
+
*/
|
|
2655
|
+
enableSessionTelemetry?: boolean;
|
|
2656
|
+
/**
|
|
2657
|
+
* Enables native model citations for supported providers.
|
|
2658
|
+
*
|
|
2659
|
+
* @experimental
|
|
2660
|
+
*/
|
|
2661
|
+
enableCitations?: boolean;
|
|
2662
|
+
/**
|
|
2663
|
+
* Opt in to capturing file changes for session rewind and cumulative session
|
|
2664
|
+
* diff. On create, capture starts with the first turn. On resume, this can
|
|
2665
|
+
* enable tracking only when the session still has a valid baseline; it cannot
|
|
2666
|
+
* reconstruct changes from earlier untracked turns.
|
|
2667
|
+
*/
|
|
2668
|
+
enableFileChangeTracking?: boolean;
|
|
2669
|
+
/**
|
|
2670
|
+
* Limits applied to this session's current accounting window.
|
|
2671
|
+
*
|
|
2672
|
+
* @experimental
|
|
2673
|
+
*/
|
|
2674
|
+
sessionLimits?: SessionLimitsConfig;
|
|
2675
|
+
/**
|
|
2676
|
+
* Autopilot policy. Omitted fields preserve resident values on warm resume;
|
|
2677
|
+
* new sessions default to continuation enabled and at most five continuations.
|
|
2678
|
+
* Does not change the session mode. Re-supply on cold resume.
|
|
2679
|
+
*
|
|
2680
|
+
* @experimental
|
|
2681
|
+
*/
|
|
2682
|
+
autopilot?: AutopilotOptions;
|
|
2683
|
+
/**
|
|
2684
|
+
* When true, the runtime skips loading custom-instruction sources
|
|
2685
|
+
* (e.g. `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`).
|
|
2686
|
+
*
|
|
2687
|
+
* Defaults to `false` (custom instructions are loaded). Under
|
|
2688
|
+
* {@link CopilotClientOptions.mode} = `"empty"`, defaults to `true`; apps
|
|
2689
|
+
* can pass `false` here to opt back in.
|
|
2690
|
+
*/
|
|
2691
|
+
skipCustomInstructions?: boolean;
|
|
2692
|
+
/**
|
|
2693
|
+
* When true, custom agents default to local-only execution and are not
|
|
2694
|
+
* dispatched to remote workers.
|
|
2695
|
+
*
|
|
2696
|
+
* Defaults to `false`. Under {@link CopilotClientOptions.mode} = `"empty"`,
|
|
2697
|
+
* defaults to `true`; apps can pass `false` here to opt back in.
|
|
2698
|
+
*/
|
|
2699
|
+
customAgentsLocalOnly?: boolean;
|
|
2700
|
+
/**
|
|
2701
|
+
* When true, the runtime instructs the agent to include a `Co-authored-by`
|
|
2702
|
+
* trailer in commit messages it composes. Subagents inherit this setting.
|
|
2703
|
+
*
|
|
2704
|
+
* Defaults to `true`. Under {@link CopilotClientOptions.mode} = `"empty"`,
|
|
2705
|
+
* defaults to `false`; apps can pass `true` here to opt back in.
|
|
2706
|
+
*/
|
|
2707
|
+
coauthorEnabled?: boolean;
|
|
2708
|
+
/**
|
|
2709
|
+
* When true, the `manage_schedule` tool is exposed to the agent.
|
|
2710
|
+
*
|
|
2711
|
+
* Defaults to whatever the runtime exposes (typically gated to staff
|
|
2712
|
+
* users). Under {@link CopilotClientOptions.mode} = `"empty"`, defaults to
|
|
2713
|
+
* `false`; apps can pass `true` here to opt back in.
|
|
2714
|
+
*/
|
|
2715
|
+
manageScheduleEnabled?: boolean;
|
|
2716
|
+
/**
|
|
2717
|
+
* Optional handler for permission requests from the server.
|
|
2718
|
+
* When omitted, permission requests are surfaced as events and left pending for
|
|
2719
|
+
* the consumer to resolve via the pending permission RPC.
|
|
2720
|
+
*/
|
|
2721
|
+
onPermissionRequest?: PermissionHandler;
|
|
2722
|
+
/**
|
|
2723
|
+
* Optional handler for MCP OAuth requests from MCP servers.
|
|
2724
|
+
* When provided, the SDK can satisfy MCP server OAuth requests with
|
|
2725
|
+
* host-provided token data or cancellation.
|
|
2726
|
+
*/
|
|
2727
|
+
onMcpAuthRequest?: McpAuthHandler;
|
|
2728
|
+
/**
|
|
2729
|
+
* Handler for user input requests from the agent.
|
|
2730
|
+
* When provided with the default `legacy` {@link AskUserVariant}, enables the
|
|
2731
|
+
* question-and-answer form of the `ask_user` tool.
|
|
2732
|
+
*/
|
|
2733
|
+
onUserInputRequest?: UserInputHandler;
|
|
2734
|
+
/**
|
|
2735
|
+
* Handler for passwords and other answers that shell commands run by the
|
|
2736
|
+
* agent ask for. When provided, `sudo -A`, `ssh`, and `git` prompts reach
|
|
2737
|
+
* this handler instead of failing for lack of a terminal. Cancel requests
|
|
2738
|
+
* when nobody can answer, for example in autopilot.
|
|
2739
|
+
*/
|
|
2740
|
+
onShellAuthenticationRequest?: ShellAuthenticationHandler;
|
|
2741
|
+
/**
|
|
2742
|
+
* Selects the model-facing shape of the built-in `ask_user` tool.
|
|
2743
|
+
*
|
|
2744
|
+
* The default is `"legacy"`. To use `"elicitation"`, also provide
|
|
2745
|
+
* {@link onElicitationRequest} so the host can answer structured forms.
|
|
2746
|
+
* The runtime resolves this option when it creates or cold-resumes the session.
|
|
2747
|
+
*/
|
|
2748
|
+
askUserVariant?: AskUserVariant;
|
|
2749
|
+
/**
|
|
2750
|
+
* Handler for elicitation requests from the agent.
|
|
2751
|
+
* When provided, the server calls back to this client for form-based UI dialogs.
|
|
2752
|
+
* Also enables the `elicitation` capability on the session.
|
|
2753
|
+
*/
|
|
2754
|
+
onElicitationRequest?: ElicitationHandler;
|
|
2755
|
+
/**
|
|
2756
|
+
* Enable MCP Apps (SEP-1865) UI passthrough on this session.
|
|
2757
|
+
*
|
|
2758
|
+
* When `true` **and** the runtime has MCP Apps enabled (via the
|
|
2759
|
+
* `MCP_APPS` feature flag or `COPILOT_MCP_APPS=true` environment
|
|
2760
|
+
* override), the runtime adds the `mcp-apps` capability to the session,
|
|
2761
|
+
* which causes it to advertise the `extensions.io.modelcontextprotocol/ui`
|
|
2762
|
+
* extension to MCP servers (so they expose `_meta.ui.resourceUri` on
|
|
2763
|
+
* tools) and to expose the `session.rpc.mcp.apps.{listTools,callTool,
|
|
2764
|
+
* readResource,setHostContext,getHostContext,diagnose}` JSON-RPC methods.
|
|
2765
|
+
*
|
|
2766
|
+
* If the runtime gate is off, the opt-in is silently dropped server-side
|
|
2767
|
+
* (the runtime logs a warning); the session is created normally but the
|
|
2768
|
+
* MCP Apps surface is unavailable. Inspect the runtime's
|
|
2769
|
+
* `capabilities.ui.mcpApps` on the create/resume response to detect this.
|
|
2770
|
+
*
|
|
2771
|
+
* SDK consumers MUST set this to `true` only when they have an iframe
|
|
2772
|
+
* renderer that can display `ui://` MCP App bundles. Setting it without a
|
|
2773
|
+
* renderer will cause MCP servers to register UI-enabled tool variants
|
|
2774
|
+
* the consumer cannot display.
|
|
2775
|
+
*
|
|
2776
|
+
* @experimental This option is part of an experimental wire-protocol surface
|
|
2777
|
+
* (SEP-1865) and may change or be removed in a future release.
|
|
2778
|
+
*
|
|
2779
|
+
* @default false
|
|
2780
|
+
*/
|
|
2781
|
+
enableMcpApps?: boolean;
|
|
2782
|
+
/**
|
|
2783
|
+
* Configuration for the built-in GitHub MCP server.
|
|
2784
|
+
*
|
|
2785
|
+
* `disableFormDeferral` only applies to the built-in GitHub MCP server and
|
|
2786
|
+
* only has an effect when MCP Apps and form-backed GitHub tools are enabled.
|
|
2787
|
+
*/
|
|
2788
|
+
githubMcpToolConfig?: GitHubMcpToolConfig;
|
|
2789
|
+
/**
|
|
2790
|
+
* Handler for exit-plan-mode requests from the agent.
|
|
2791
|
+
* When provided, enables `exitPlanMode.request` callbacks.
|
|
2792
|
+
*/
|
|
2793
|
+
onExitPlanModeRequest?: ExitPlanModeHandler;
|
|
2794
|
+
/**
|
|
2795
|
+
* Handler for auto-mode-switch requests from the agent.
|
|
2796
|
+
* When provided, enables `autoModeSwitch.request` callbacks.
|
|
2797
|
+
*/
|
|
2798
|
+
onAutoModeSwitchRequest?: AutoModeSwitchHandler;
|
|
2799
|
+
/**
|
|
2800
|
+
* Opt in to runtime-owned recovery of an eligible active request using Auto.
|
|
2801
|
+
* Requires `onAutoModeSwitchRequest` and a runtime acknowledgment in
|
|
2802
|
+
* `session.capabilities.ui.autoModeRecovery`; unsupported enrollment rejects
|
|
2803
|
+
* create/resume and detaches the session. Re-supply when resuming.
|
|
2804
|
+
* Consent has no runtime deadline. The handler must not resend or rewind.
|
|
2805
|
+
* @default false
|
|
2806
|
+
*/
|
|
2807
|
+
autoModeRecovery?: boolean;
|
|
2808
|
+
/**
|
|
2809
|
+
* Hook handlers for intercepting session lifecycle events.
|
|
2810
|
+
* When provided, enables hooks callback allowing custom logic at various points.
|
|
2811
|
+
*/
|
|
2812
|
+
hooks?: SessionHooks;
|
|
2813
|
+
/**
|
|
2814
|
+
* Working directory for the session.
|
|
2815
|
+
* Tool operations will be relative to this directory.
|
|
2816
|
+
*/
|
|
2817
|
+
workingDirectory?: string;
|
|
2818
|
+
/**
|
|
2819
|
+
* Additional directories the agent may access beyond the working directory.
|
|
2820
|
+
* Relative paths are resolved against the session's working directory.
|
|
2821
|
+
* Re-supply these directories when resuming a session.
|
|
2822
|
+
*/
|
|
2823
|
+
additionalDirectories?: string[];
|
|
2824
|
+
/**
|
|
2825
|
+
* Enable streaming of assistant message and reasoning chunks.
|
|
2826
|
+
* When true, ephemeral assistant.message_delta and assistant.reasoning_delta
|
|
2827
|
+
* events are sent as the response is generated. Clients should accumulate
|
|
2828
|
+
* deltaContent values to build the full response.
|
|
2829
|
+
* @default false
|
|
2830
|
+
*/
|
|
2831
|
+
streaming?: boolean;
|
|
2832
|
+
/**
|
|
2833
|
+
* Include sub-agent streaming events in the event stream. When true, streaming
|
|
2834
|
+
* delta events from sub-agents (e.g., `assistant.message_delta`,
|
|
2835
|
+
* `assistant.reasoning_delta`, `assistant.streaming_delta` with `agentId` set)
|
|
2836
|
+
* are forwarded to this connection. When false, only non-streaming sub-agent
|
|
2837
|
+
* events and `subagent.*` lifecycle events are forwarded; streaming deltas from
|
|
2838
|
+
* sub-agents are suppressed.
|
|
2839
|
+
* @default true
|
|
2840
|
+
*/
|
|
2841
|
+
includeSubAgentStreamingEvents?: boolean;
|
|
2842
|
+
/**
|
|
2843
|
+
* Controls how MCP OAuth tokens are stored for this session.
|
|
2844
|
+
* - `"persistent"` — tokens are stored in the OS keychain (shared across sessions)
|
|
2845
|
+
* - `"in-memory"` — tokens are stored in memory and discarded when the session ends
|
|
2846
|
+
*
|
|
2847
|
+
* @default "in-memory"
|
|
2848
|
+
*/
|
|
2849
|
+
mcpOAuthTokenStorage?: "persistent" | "in-memory";
|
|
2850
|
+
/**
|
|
2851
|
+
* OAuth Client ID Metadata Document URL identifying the host for MCP authorization.
|
|
2852
|
+
* When unset, no host identity is supplied.
|
|
2853
|
+
*/
|
|
2854
|
+
authClientIdMetadataUrl?: string;
|
|
2855
|
+
/**
|
|
2856
|
+
* MCP server configurations for the session.
|
|
2857
|
+
* Keys are server names, values are server configurations.
|
|
2858
|
+
*/
|
|
2859
|
+
mcpServers?: Record<string, MCPServerConfig>;
|
|
2860
|
+
/**
|
|
2861
|
+
* Custom agent configurations for the session.
|
|
2862
|
+
*/
|
|
2863
|
+
customAgents?: CustomAgentConfig[];
|
|
2864
|
+
/**
|
|
2865
|
+
* Configuration for the default agent (the built-in agent that handles
|
|
2866
|
+
* turns when no custom agent is selected).
|
|
2867
|
+
* Use `excludedTools` to hide specific tools from the default agent while keeping
|
|
2868
|
+
* them available to custom sub-agents.
|
|
2869
|
+
*/
|
|
2870
|
+
defaultAgent?: DefaultAgentConfig;
|
|
2871
|
+
/**
|
|
2872
|
+
* Name of the custom agent to activate when the session starts.
|
|
2873
|
+
* Must match the `name` of one of the agents in `customAgents`.
|
|
2874
|
+
* Equivalent to calling `session.rpc.agent.select({ name })` after creation.
|
|
2875
|
+
*/
|
|
2876
|
+
agent?: string;
|
|
2877
|
+
/**
|
|
2878
|
+
* Explicit discovery-only skill roots. No general filesystem access is granted.
|
|
2879
|
+
* Available without `enableConfigDiscovery`; skill and managed disables still apply.
|
|
2880
|
+
* Relative paths resolve once when supplied against the request's effective
|
|
2881
|
+
* `workingDirectory`, and retained roots do not move when it changes.
|
|
2882
|
+
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
2883
|
+
*/
|
|
2884
|
+
skillDirectories?: string[];
|
|
2885
|
+
/**
|
|
2886
|
+
* Supplies skills from the host's own storage instead of `SKILL.md` files on
|
|
2887
|
+
* disk. Provider skills join the session's skill catalog alongside file-based
|
|
2888
|
+
* skills. See {@link SkillProvider}.
|
|
2889
|
+
*
|
|
2890
|
+
* Supplying a provider enables skills unless `enableSkills` is set explicitly,
|
|
2891
|
+
* so set `enableSkills: true` when the client runs in `"empty"` mode. With
|
|
2892
|
+
* `enableSkills: false` the provider stays bound but receives no calls.
|
|
2893
|
+
*
|
|
2894
|
+
* The provider isn't persisted. Pass it again when resuming the session;
|
|
2895
|
+
* resuming without one removes the provider's skills.
|
|
2896
|
+
*
|
|
2897
|
+
* @experimental Session-scoped skill providers are experimental and may change
|
|
2898
|
+
* or be removed in future SDK or CLI releases.
|
|
2899
|
+
*/
|
|
2900
|
+
skillProvider?: SkillProvider;
|
|
2901
|
+
/**
|
|
2902
|
+
* Explicit discovery-only agent roots, separate from `customAgents` objects.
|
|
2903
|
+
* No general filesystem access is granted. Available without `enableConfigDiscovery`;
|
|
2904
|
+
* source and managed disables still apply.
|
|
2905
|
+
* Relative paths resolve once when supplied against the request's effective
|
|
2906
|
+
* `workingDirectory`, and retained roots do not move when it changes.
|
|
2907
|
+
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
2908
|
+
*/
|
|
2909
|
+
agentDirectories?: string[];
|
|
2910
|
+
/**
|
|
2911
|
+
* Explicit discovery-only file-hook roots, separate from callback `hooks`.
|
|
2912
|
+
* No general filesystem access is granted. Available without `enableConfigDiscovery`
|
|
2913
|
+
* or `enableFileHooks` (which controls repository-origin hooks only);
|
|
2914
|
+
* hook and managed disables still apply.
|
|
2915
|
+
* Relative paths resolve once when supplied against the request's effective
|
|
2916
|
+
* `workingDirectory`, and retained roots do not move when it changes.
|
|
2917
|
+
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
2918
|
+
*/
|
|
2919
|
+
hookDirectories?: string[];
|
|
2920
|
+
/**
|
|
2921
|
+
* Local filesystem paths to Open Plugins-format directories
|
|
2922
|
+
* (https://open-plugins.com/) to load for this session.
|
|
2923
|
+
*
|
|
2924
|
+
* Relative paths resolve against `workingDirectory` (or the runtime cwd if
|
|
2925
|
+
* unset); absolute paths are recommended. Invalid entries are logged and
|
|
2926
|
+
* skipped.
|
|
2927
|
+
*
|
|
2928
|
+
* Treated as an explicit opt-in: plugin agents and rules load even when
|
|
2929
|
+
* {@link SessionConfigBase.enableConfigDiscovery} is false. Loaded assets
|
|
2930
|
+
* slot between project (cwd) sources and personal/home sources in the
|
|
2931
|
+
* session-wide precedence order.
|
|
2932
|
+
*/
|
|
2933
|
+
pluginDirectories?: string[];
|
|
2934
|
+
/**
|
|
2935
|
+
* Explicit discovery-only instruction roots using the existing SDK instruction formats.
|
|
2936
|
+
* No general filesystem access is granted. Available without `enableConfigDiscovery`;
|
|
2937
|
+
* instruction and managed disables still apply.
|
|
2938
|
+
* Relative paths resolve once when supplied against the request's effective
|
|
2939
|
+
* `workingDirectory`, and retained roots do not move when it changes.
|
|
2940
|
+
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
2941
|
+
*/
|
|
2942
|
+
instructionDirectories?: string[];
|
|
2943
|
+
/**
|
|
2944
|
+
* List of skill names to disable.
|
|
2945
|
+
*/
|
|
2946
|
+
disabledSkills?: string[];
|
|
2947
|
+
/**
|
|
2948
|
+
* Exact MCP server names to disable for this session. Disabled servers are not
|
|
2949
|
+
* started or authenticated when creating or cold-resuming a session. Supplying
|
|
2950
|
+
* this on a resident resume cannot stop servers that are already running.
|
|
2951
|
+
*/
|
|
2952
|
+
disabledMcpServers?: string[];
|
|
2953
|
+
/**
|
|
2954
|
+
* Sandbox configuration applied before MCP servers or session tools start.
|
|
2955
|
+
* Uses the same direct-host semantics and managed-policy validation as
|
|
2956
|
+
* `session.rpc.options.update({ sandboxConfig })`. A policy conflict fails
|
|
2957
|
+
* create or resume; an identical later update does not restart MCP servers.
|
|
2958
|
+
* Re-supply on cold resume. Requires runtime-version support.
|
|
2959
|
+
*/
|
|
2960
|
+
sandboxConfig?: SandboxConfig;
|
|
2961
|
+
/**
|
|
2962
|
+
* Infinite session configuration for persistent workspaces and automatic compaction.
|
|
2963
|
+
* When enabled (default), sessions automatically manage context limits and persist state.
|
|
2964
|
+
* Set to `{ enabled: false }` to disable.
|
|
2965
|
+
*/
|
|
2966
|
+
infiniteSessions?: InfiniteSessionConfig;
|
|
2967
|
+
/**
|
|
2968
|
+
* Memory configuration for the session. When omitted, the runtime default applies.
|
|
2969
|
+
*/
|
|
2970
|
+
memory?: MemoryConfiguration;
|
|
2971
|
+
/**
|
|
2972
|
+
* GitHub token for per-session authentication.
|
|
2973
|
+
* When provided, the runtime resolves this token into a full GitHub identity
|
|
2974
|
+
* (login, Copilot plan, endpoints) and stores it on the session. This enables
|
|
2975
|
+
* multitenancy — different sessions can have different GitHub identities.
|
|
2976
|
+
*
|
|
2977
|
+
* This is independent of the client-level `gitHubToken` in {@link CopilotClientOptions},
|
|
2978
|
+
* which authenticates the CLI process itself. The session-level token determines
|
|
2979
|
+
* the identity used for content exclusion, model routing, and quota checks.
|
|
2980
|
+
*/
|
|
2981
|
+
gitHubToken?: string;
|
|
2982
|
+
/**
|
|
2983
|
+
* Acquires short-lived GitHub credentials for this session on demand.
|
|
2984
|
+
*
|
|
2985
|
+
* Mutually exclusive with {@link SessionConfigBase.gitHubToken}. The
|
|
2986
|
+
* callback receives the effective GitHub host, the session ID when known,
|
|
2987
|
+
* and whether this is the initial acquisition or a refresh. Its opaque
|
|
2988
|
+
* registration ID remains internal to the SDK.
|
|
2989
|
+
*/
|
|
2990
|
+
gitHubTokenProvider?: GitHubTokenProvider;
|
|
2991
|
+
/**
|
|
2992
|
+
* Opt-in: when true, the runtime self-fetches enterprise managed settings
|
|
2993
|
+
* (bypass-permissions policy) at session bootstrap using the session's
|
|
2994
|
+
* `gitHubToken`. Requires {@link SessionConfigBase.gitHubToken} to be set;
|
|
2995
|
+
* if omitted, the runtime is expected to reject session creation (fail-closed).
|
|
2996
|
+
*/
|
|
2997
|
+
enableManagedSettings?: boolean;
|
|
2998
|
+
/**
|
|
2999
|
+
* Managed-setting paths this trusted host handles externally or does not
|
|
3000
|
+
* support. Exact dotted paths exclude a setting and its descendants from
|
|
3001
|
+
* fetched, device, and policy-helper policy (for example `"sandbox"` or
|
|
3002
|
+
* `"permissions.disableBypassPermissionsMode"`). MCP allow/deny controls
|
|
3003
|
+
* are `"allowedMcpServers"` and `"deniedMcpServers"`, not an `"mcp"` subtree.
|
|
3004
|
+
* Wildcards and array indices are unsupported. Unknown paths are accepted
|
|
3005
|
+
* for forward compatibility. Host-injected `managedSettings` and policy
|
|
3006
|
+
* availability checks are unaffected.
|
|
3007
|
+
*
|
|
3008
|
+
* Not persisted: re-supply on resume; omission restores full enforcement.
|
|
3009
|
+
* This does not enable self-fetching; use `enableManagedSettings: true`.
|
|
3010
|
+
*/
|
|
3011
|
+
excludedManagedSettings?: string[];
|
|
3012
|
+
/**
|
|
3013
|
+
* When true, locked managed model controls are enforced for this session.
|
|
3014
|
+
* Conflicting model changes are rejected, and locked startup values replace
|
|
3015
|
+
* conflicting session options. Overridable managed defaults remain mutable.
|
|
3016
|
+
*/
|
|
3017
|
+
enforceManagedModelDefaults?: boolean;
|
|
3018
|
+
/**
|
|
3019
|
+
* Declares that a human drives this session's conversation, enabling
|
|
3020
|
+
* user-message analysis telemetry for user-authored messages. Automated
|
|
3021
|
+
* messages remain excluded. Defaults to false for SDK sessions; ignored
|
|
3022
|
+
* for cloud sessions and when resuming a session that is already active.
|
|
3023
|
+
*/
|
|
3024
|
+
interactiveUser?: boolean;
|
|
3025
|
+
/**
|
|
3026
|
+
* Permission mode applied before the session's first turn: before
|
|
3027
|
+
* `createSession` returns, and before a resume continues pending work.
|
|
3028
|
+
* Uses the same checks as `session.rpc.permissions.setMode`; a mode that
|
|
3029
|
+
* managed policy or session capabilities refuse leaves the current mode in
|
|
3030
|
+
* place. `session.permissionModeResult` reports whether it was applied and
|
|
3031
|
+
* the authoritative mode. Omit to keep the default mode on create, or the
|
|
3032
|
+
* restored mode on resume. Not supported for cloud sessions.
|
|
3033
|
+
*/
|
|
3034
|
+
permissionMode?: PermissionMode;
|
|
3035
|
+
/**
|
|
3036
|
+
* Host-injected enterprise managed settings for this session.
|
|
3037
|
+
*
|
|
3038
|
+
* Unlike {@link SessionConfigBase.enableManagedSettings} — which asks the
|
|
3039
|
+
* runtime to *self-fetch* account/org and device policy — this field lets
|
|
3040
|
+
* the host supply the managed policy directly. The runtime validates it
|
|
3041
|
+
* with the same managed-permission parser it uses for fetched policy and
|
|
3042
|
+
* composes it restrictively with any self-fetched (server) and
|
|
3043
|
+
* device-managed (MDM) layers: `deny`/`ask` rules are unioned, every
|
|
3044
|
+
* declared `allow` list must admit an operation, and bypass-mode
|
|
3045
|
+
* restrictions are composed fail-closed.
|
|
3046
|
+
*
|
|
3047
|
+
* This is startup-only. It is **not** persisted: it must be re-supplied on
|
|
3048
|
+
* {@link CopilotClient.resumeSession | resume}, where it replaces the prior
|
|
3049
|
+
* injected layer (omitting it clears the layer, so warm and cold resume
|
|
3050
|
+
* behave identically). It may be combined with `enableManagedSettings`;
|
|
3051
|
+
* when both are supplied the injected, server, and device restrictions all
|
|
3052
|
+
* apply.
|
|
3053
|
+
*
|
|
3054
|
+
* Requires a Copilot runtime whose RPC schema includes `managedSettings`.
|
|
3055
|
+
* Older runtimes may ignore this additive field, so hosts must not rely on
|
|
3056
|
+
* injected policy until they ship a compatible runtime.
|
|
3057
|
+
*/
|
|
3058
|
+
managedSettings?: ManagedSettings;
|
|
3059
|
+
/**
|
|
3060
|
+
* When true, skips embedding-based retrieval for this session.
|
|
3061
|
+
* Use in multitenant deployments to prevent cross-session information leakage
|
|
3062
|
+
* through the shared embedding cache.
|
|
3063
|
+
*/
|
|
3064
|
+
skipEmbeddingRetrieval?: boolean;
|
|
3065
|
+
/**
|
|
3066
|
+
* Controls how the embedding cache is stored for this session.
|
|
3067
|
+
* - `"persistent"`: Embeddings are cached on disk and shared across sessions/restarts.
|
|
3068
|
+
* - `"in-memory"`: Embeddings are cached in memory only and discarded when the session ends.
|
|
3069
|
+
*/
|
|
3070
|
+
embeddingCacheStorage?: "persistent" | "in-memory";
|
|
3071
|
+
/**
|
|
3072
|
+
* Organization-level custom instructions to include in the system prompt.
|
|
3073
|
+
* Allows hosts to inject organization-specific guidance without relying on
|
|
3074
|
+
* filesystem-based instruction discovery.
|
|
3075
|
+
*/
|
|
3076
|
+
organizationCustomInstructions?: string;
|
|
3077
|
+
/**
|
|
3078
|
+
* When true, enables on-demand discovery of instruction files (AGENTS.md,
|
|
3079
|
+
* .github/copilot-instructions.md, etc.) after successful file views.
|
|
3080
|
+
*/
|
|
3081
|
+
enableOnDemandInstructionDiscovery?: boolean;
|
|
3082
|
+
/**
|
|
3083
|
+
* When true, enables repository-origin file hooks from `.github/hooks/` and
|
|
3084
|
+
* trusted repository-configured roots. Does not control explicit `hookDirectories`
|
|
3085
|
+
* or the `hooks` callback parameter.
|
|
3086
|
+
*/
|
|
3087
|
+
enableFileHooks?: boolean;
|
|
3088
|
+
/**
|
|
3089
|
+
* When true, enables git operations on the host filesystem (branch detection,
|
|
3090
|
+
* file status, commit history). When false, no git context is surfaced in
|
|
3091
|
+
* the system prompt.
|
|
3092
|
+
*/
|
|
3093
|
+
enableHostGitOperations?: boolean;
|
|
3094
|
+
/**
|
|
3095
|
+
* When true, enables the cross-session store for search and retrieval
|
|
3096
|
+
* across sessions. When false, session content is not written to or
|
|
3097
|
+
* read from the shared session store.
|
|
3098
|
+
*/
|
|
3099
|
+
enableSessionStore?: boolean;
|
|
3100
|
+
/**
|
|
3101
|
+
* When true, enables skill loading (including builtin skills and discovered
|
|
3102
|
+
* skill directories). When false, no skills are loaded regardless of
|
|
3103
|
+
* `skillDirectories` or `enableConfigDiscovery` settings.
|
|
3104
|
+
*/
|
|
3105
|
+
enableSkills?: boolean;
|
|
3106
|
+
/**
|
|
3107
|
+
* Optional event handler that is registered on the session before the
|
|
3108
|
+
* session.create RPC is issued. This guarantees that early events emitted
|
|
3109
|
+
* by the CLI during session creation (e.g. session.start) are delivered to
|
|
3110
|
+
* the handler.
|
|
3111
|
+
*
|
|
3112
|
+
* Equivalent to calling `session.on(handler)` immediately after creation,
|
|
3113
|
+
* but executes earlier in the lifecycle so no events are missed.
|
|
3114
|
+
*/
|
|
3115
|
+
onEvent?: SessionEventHandler;
|
|
3116
|
+
/**
|
|
3117
|
+
* Supplies a handler for session filesystem operations. This takes effect
|
|
3118
|
+
* only if {@link CopilotClientOptions.sessionFs} is configured.
|
|
3119
|
+
*/
|
|
3120
|
+
createSessionFsProvider?: (session: CopilotSession) => SessionFsProvider;
|
|
3121
|
+
/**
|
|
3122
|
+
* Feature-flag values resolved by the host for this session.
|
|
3123
|
+
* Re-supply them when resuming after a runtime restart.
|
|
3124
|
+
*/
|
|
3125
|
+
featureFlags?: Record<string, boolean>;
|
|
3126
|
+
}
|
|
3127
|
+
/**
|
|
3128
|
+
* Configuration for creating a new session via {@link CopilotClient.createSession}.
|
|
3129
|
+
*/
|
|
3130
|
+
export interface SessionConfig extends SessionConfigBase {
|
|
3131
|
+
/**
|
|
3132
|
+
* Optional custom session ID. If not provided, the server generates one.
|
|
3133
|
+
*/
|
|
3134
|
+
sessionId?: string;
|
|
3135
|
+
/**
|
|
3136
|
+
* Names the session at creation, as `session.name.set` would, and is validated the
|
|
3137
|
+
* same way: non-empty, no leading or trailing whitespace, at most 100 UTF-16 units,
|
|
3138
|
+
* no control characters, and no double quotes. A name also makes the session persist
|
|
3139
|
+
* from the start, so it can be listed and resumed without ever running a turn.
|
|
3140
|
+
* Local sessions only: cloud creation rejects it.
|
|
3141
|
+
*/
|
|
3142
|
+
name?: string;
|
|
3143
|
+
/**
|
|
3144
|
+
* Grants trust to the canonical working directory during session creation.
|
|
3145
|
+
* "session" applies only to this session; "user" persists the grant for later
|
|
3146
|
+
* sessions. Omit to leave directory trust unchanged. Not available on resume.
|
|
3147
|
+
*/
|
|
3148
|
+
trustWorkingDirectory?: WorkingDirectoryTrust;
|
|
3149
|
+
/**
|
|
3150
|
+
* Invalidates the process-wide custom-instruction discovery cache before
|
|
3151
|
+
* creating this session. Use when instruction files changed in the same runtime.
|
|
3152
|
+
* Other sessions in this runtime may observe updated instructions on later turns
|
|
3153
|
+
* or discovery. This does not watch files or enable disabled instruction loading.
|
|
3154
|
+
* @default false
|
|
3155
|
+
*/
|
|
3156
|
+
refreshCustomInstructions?: boolean;
|
|
3157
|
+
/**
|
|
3158
|
+
* Creates a remote session in the cloud instead of a local session.
|
|
3159
|
+
* The optional repository is associated with the cloud session.
|
|
3160
|
+
*/
|
|
3161
|
+
cloud?: CloudSessionOptions;
|
|
3162
|
+
}
|
|
3163
|
+
/**
|
|
3164
|
+
* Configuration for resuming an existing session via
|
|
3165
|
+
* {@link CopilotClient.resumeSession}.
|
|
3166
|
+
*/
|
|
3167
|
+
export interface ResumeSessionConfig extends SessionConfigBase {
|
|
3168
|
+
/**
|
|
3169
|
+
* Allow the runtime to recover a damaged transcript during resume.
|
|
3170
|
+
* Defaults to true in all modes. Set false to reject recovery.
|
|
3171
|
+
*/
|
|
3172
|
+
allowTranscriptRecovery?: boolean;
|
|
3173
|
+
/**
|
|
3174
|
+
* When true, skips emitting the session.resume event.
|
|
3175
|
+
* Useful for reconnecting to a session without triggering resume-related side effects.
|
|
3176
|
+
* @default false
|
|
3177
|
+
*/
|
|
3178
|
+
suppressResumeEvent?: boolean;
|
|
3179
|
+
/**
|
|
3180
|
+
* When true, the runtime continues any tool calls or permission prompts that were
|
|
3181
|
+
* still pending when the session was last suspended. When false (the default), the
|
|
3182
|
+
* runtime treats pending work as interrupted on resume. Completed tool results
|
|
3183
|
+
* already durably recorded by the runtime are preserved.
|
|
3184
|
+
*
|
|
3185
|
+
* When true, pending permission requests and external tool calls wait for
|
|
3186
|
+
* caller-supplied results via the corresponding low-level RPC methods. Resuming
|
|
3187
|
+
* does not re-emit restored permission requests or re-invoke permission handlers
|
|
3188
|
+
* or already-dispatched external tool callbacks.
|
|
3189
|
+
* If a pending call was recorded as SDK-handler-backed and resume registers a
|
|
3190
|
+
* handler for that tool, the abandoned callback is interrupted, never replayed.
|
|
3191
|
+
* Handlerless calls remain pending. To supply an abandoned callback's result
|
|
3192
|
+
* manually, resume without a handler for it. Older requests without recorded
|
|
3193
|
+
* callback ownership also remain pending.
|
|
3194
|
+
* @default false
|
|
3195
|
+
*/
|
|
3196
|
+
continuePendingWork?: boolean;
|
|
3197
|
+
/**
|
|
3198
|
+
* Snapshot of canvases that were already open when the session was suspended.
|
|
3199
|
+
* When provided on resume, the runtime can rehydrate canvas state so consumers
|
|
3200
|
+
* do not need to re-open canvases that were active before the previous shutdown.
|
|
3201
|
+
*/
|
|
3202
|
+
openCanvases?: OpenCanvasInstance[];
|
|
3203
|
+
}
|
|
3204
|
+
/** Transcript repair proposed during the most recent resume. */
|
|
3205
|
+
export interface TranscriptRecovery {
|
|
3206
|
+
/** Planned backup path; the backup is written on the next append. */
|
|
3207
|
+
plannedBackupPath: string;
|
|
3208
|
+
/** One-based physical line numbers removed from the transcript. */
|
|
3209
|
+
invalidLineNumbers: number[];
|
|
3210
|
+
/** Whether an existing session.start event was moved to the beginning. */
|
|
3211
|
+
sessionStartMoved: boolean;
|
|
3212
|
+
}
|
|
3213
|
+
/**
|
|
3214
|
+
* Arguments passed to a {@link BearerTokenProvider} callback when the runtime needs a
|
|
3215
|
+
* fresh bearer token for a BYOK provider.
|
|
3216
|
+
*
|
|
3217
|
+
* @experimental Part of the experimental managed-identity / bearer-token-provider
|
|
3218
|
+
* surface and may change or be removed in future SDK or CLI releases.
|
|
3219
|
+
*/
|
|
3220
|
+
export interface ProviderTokenArgs {
|
|
3221
|
+
/**
|
|
3222
|
+
* Name of the BYOK provider needing a token. For the singular, whole-session
|
|
3223
|
+
* {@link ProviderConfig} this is the implicit provider name (`"default"`); for
|
|
3224
|
+
* {@link NamedProviderConfig} entries it is {@link NamedProviderConfig.name}.
|
|
3225
|
+
*
|
|
3226
|
+
* The callback closes over its own token scope/audience; the runtime is
|
|
3227
|
+
* provider-agnostic and forwards only the provider name.
|
|
3228
|
+
*/
|
|
3229
|
+
readonly providerName: string;
|
|
3230
|
+
/**
|
|
3231
|
+
* Id of the session that triggered this token request. A client-level shared
|
|
3232
|
+
* callback registered for many sessions can use this to resolve the owning
|
|
3233
|
+
* session (e.g. via the client's session lookup) to scope token acquisition
|
|
3234
|
+
* or caching per session.
|
|
3235
|
+
*/
|
|
3236
|
+
readonly sessionId: string;
|
|
3237
|
+
}
|
|
3238
|
+
/**
|
|
3239
|
+
* Per-provider callback that resolves a bearer token on demand, returning the
|
|
3240
|
+
* raw token string (without the `Bearer ` prefix). The Copilot SDK itself takes
|
|
3241
|
+
* no Azure dependency: the consumer supplies this callback backed by their own
|
|
3242
|
+
* identity library (for example `@azure/identity`'s
|
|
3243
|
+
* `DefaultAzureCredential.getToken(scope)`), and the runtime calls it once before
|
|
3244
|
+
* each outbound model request. The runtime does no caching of its own, so the
|
|
3245
|
+
* callback (or the identity library it wraps) owns token caching and refresh.
|
|
3246
|
+
*
|
|
3247
|
+
* @experimental Part of the experimental managed-identity / bearer-token-provider
|
|
3248
|
+
* surface and may change or be removed in future SDK or CLI releases.
|
|
3249
|
+
*/
|
|
3250
|
+
export type BearerTokenProvider = (args: ProviderTokenArgs) => Promise<string>;
|
|
3251
|
+
/**
|
|
3252
|
+
* Product serving a configured provider's model. Allowed values are
|
|
3253
|
+
* "openai", "anthropic", "azure_openai", "ollama", "lm_studio",
|
|
3254
|
+
* "foundry_local", and "llama_cpp".
|
|
3255
|
+
*/
|
|
3256
|
+
export type ProviderConfigModelProvider = "openai" | "anthropic" | "azure_openai" | "ollama" | "lm_studio" | "foundry_local" | "llama_cpp";
|
|
3257
|
+
/**
|
|
3258
|
+
* Configuration for a custom API provider.
|
|
3259
|
+
*/
|
|
3260
|
+
export interface ProviderConfig {
|
|
3261
|
+
/**
|
|
3262
|
+
* Provider type. Defaults to "openai" for generic OpenAI-compatible APIs.
|
|
3263
|
+
*/
|
|
3264
|
+
type?: ProviderConfigType;
|
|
3265
|
+
/**
|
|
3266
|
+
* API format (openai/azure only). Defaults to "completions".
|
|
3267
|
+
*/
|
|
3268
|
+
wireApi?: "completions" | "responses";
|
|
3269
|
+
/**
|
|
3270
|
+
* Transport for OpenAI Responses requests. Defaults to "http".
|
|
3271
|
+
*
|
|
3272
|
+
* Set to "websockets" to deliver Responses API requests over a persistent
|
|
3273
|
+
* WebSocket connection instead of HTTP. Useful for long-running,
|
|
3274
|
+
* tool-call-heavy sessions that benefit from incremental
|
|
3275
|
+
* `previous_response_id` continuations. Applies to OpenAI-compatible
|
|
3276
|
+
* providers using `wireApi: "responses"`.
|
|
3277
|
+
*/
|
|
3278
|
+
transport?: "http" | "websockets";
|
|
3279
|
+
/**
|
|
3280
|
+
* Product serving the model, such as "ollama" or "lm_studio", reported in
|
|
3281
|
+
* telemetry as `model_provider`. Only affects telemetry.
|
|
3282
|
+
*/
|
|
3283
|
+
modelProvider?: ProviderConfigModelProvider;
|
|
3284
|
+
/**
|
|
3285
|
+
* API endpoint URL
|
|
3286
|
+
*/
|
|
3287
|
+
baseUrl: string;
|
|
3288
|
+
/**
|
|
3289
|
+
* API key. Optional for local providers like Ollama.
|
|
3290
|
+
*/
|
|
3291
|
+
apiKey?: string;
|
|
3292
|
+
/**
|
|
3293
|
+
* Command run by the runtime before each provider request to obtain a fresh API key.
|
|
3294
|
+
* Command failures fail the turn before sending a model request.
|
|
3295
|
+
* Bearer authentication takes precedence; use {@link apiKey} for a static key.
|
|
3296
|
+
*/
|
|
3297
|
+
apiKeyCommand?: string;
|
|
3298
|
+
/**
|
|
3299
|
+
* Bearer token for authentication. Sets the Authorization header directly.
|
|
3300
|
+
* Use this for services requiring bearer token auth instead of API key.
|
|
3301
|
+
* Takes precedence over apiKey when both are set.
|
|
3302
|
+
*/
|
|
3303
|
+
bearerToken?: string;
|
|
3304
|
+
/**
|
|
3305
|
+
* Per-request bearer-token provider for managed-identity / on-demand auth.
|
|
3306
|
+
* When set, the SDK keeps this function client-side (it is never serialized)
|
|
3307
|
+
* and the runtime calls back into this client to acquire a token before each
|
|
3308
|
+
* outbound request. The runtime does no caching of its own, so the callback
|
|
3309
|
+
* owns token caching and refresh. When set alongside {@link apiKey},
|
|
3310
|
+
* {@link apiKeyCommand}, or {@link bearerToken}, this callback takes precedence:
|
|
3311
|
+
* the runtime applies its token as the `Authorization: Bearer` header for each
|
|
3312
|
+
* request, without sending the static credential or running the command.
|
|
3313
|
+
*
|
|
3314
|
+
* @experimental
|
|
3315
|
+
*/
|
|
3316
|
+
bearerTokenProvider?: BearerTokenProvider;
|
|
3317
|
+
/**
|
|
3318
|
+
* Azure-specific options
|
|
3319
|
+
*/
|
|
3320
|
+
azure?: {
|
|
3321
|
+
/**
|
|
3322
|
+
* API version. When omitted, the runtime uses the GA versionless v1 route.
|
|
3323
|
+
*/
|
|
3324
|
+
apiVersion?: string;
|
|
3325
|
+
};
|
|
3326
|
+
/**
|
|
3327
|
+
* Custom HTTP headers to include in outbound provider requests.
|
|
3328
|
+
*/
|
|
3329
|
+
headers?: Record<string, string>;
|
|
3330
|
+
/**
|
|
3331
|
+
* Well-known model name used by the runtime to look up agent configuration
|
|
3332
|
+
* (tools, prompts, reasoning behavior) and default token limits. Also used
|
|
3333
|
+
* as the wire model when {@link wireModel} is not set.
|
|
3334
|
+
* Falls back to {@link SessionConfig.model}.
|
|
3335
|
+
*/
|
|
3336
|
+
modelId?: string;
|
|
3337
|
+
/**
|
|
3338
|
+
* Model name sent to the provider API for inference. Use this when the
|
|
3339
|
+
* provider's model name (e.g. an Azure deployment name or a custom
|
|
3340
|
+
* fine-tune name) differs from {@link modelId}.
|
|
3341
|
+
* Falls back to {@link modelId}, then {@link SessionConfig.model}.
|
|
3342
|
+
*/
|
|
3343
|
+
wireModel?: string;
|
|
3344
|
+
/**
|
|
3345
|
+
* Overrides the resolved model's default max prompt tokens. The runtime
|
|
3346
|
+
* triggers conversation compaction before sending a request when the
|
|
3347
|
+
* prompt (system message, history, tool definitions, user message) would
|
|
3348
|
+
* exceed this limit.
|
|
3349
|
+
*/
|
|
3350
|
+
maxPromptTokens?: number;
|
|
3351
|
+
/**
|
|
3352
|
+
* Overrides the resolved model's default max output tokens. When hit, the
|
|
3353
|
+
* model stops generating and returns a truncated response.
|
|
3354
|
+
*/
|
|
3355
|
+
maxOutputTokens?: number;
|
|
3356
|
+
}
|
|
3357
|
+
/**
|
|
3358
|
+
* A named BYOK provider connection (transport + credentials only), referenced by
|
|
3359
|
+
* {@link ProviderModelConfig} entries via {@link NamedProviderConfig.name}.
|
|
3360
|
+
*
|
|
3361
|
+
* Unlike the singular, whole-session {@link ProviderConfig} — which bypasses
|
|
3362
|
+
* Copilot API authentication — named providers are **additive** and coexist with
|
|
3363
|
+
* Copilot API auth, so CAPI and BYOK models can be mixed within one session and
|
|
3364
|
+
* across sub-agents. See {@link SessionConfigBase.providers}.
|
|
3365
|
+
*
|
|
3366
|
+
* @experimental This type is part of an experimental multi-provider BYOK surface
|
|
3367
|
+
* and may change or be removed in future SDK or CLI releases.
|
|
3368
|
+
*/
|
|
3369
|
+
export interface NamedProviderConfig {
|
|
3370
|
+
/**
|
|
3371
|
+
* Stable identifier referenced by {@link ProviderModelConfig.provider}.
|
|
3372
|
+
* Must not contain `/`.
|
|
3373
|
+
*/
|
|
3374
|
+
name: string;
|
|
3375
|
+
/**
|
|
3376
|
+
* Provider type. Defaults to "openai" for generic OpenAI-compatible APIs.
|
|
3377
|
+
*/
|
|
3378
|
+
type?: ProviderConfigType;
|
|
3379
|
+
/**
|
|
3380
|
+
* Runtime options for a local model. The SDK forwards these options unchanged.
|
|
3381
|
+
*/
|
|
3382
|
+
localModel?: GeneratedNamedProviderConfig["localModel"];
|
|
3383
|
+
/**
|
|
3384
|
+
* Wire API format (openai/azure only). Defaults to "completions".
|
|
3385
|
+
*/
|
|
3386
|
+
wireApi?: "completions" | "responses";
|
|
3387
|
+
/**
|
|
3388
|
+
* Product serving this provider's models, such as "ollama" or "lm_studio",
|
|
3389
|
+
* reported in telemetry as `model_provider`. Only affects telemetry.
|
|
3390
|
+
*/
|
|
3391
|
+
modelProvider?: ProviderConfigModelProvider;
|
|
3392
|
+
/**
|
|
3393
|
+
* API endpoint URL.
|
|
3394
|
+
*/
|
|
3395
|
+
baseUrl: string;
|
|
3396
|
+
/**
|
|
3397
|
+
* API key. Optional for local providers like Ollama.
|
|
3398
|
+
*/
|
|
3399
|
+
apiKey?: string;
|
|
3400
|
+
/**
|
|
3401
|
+
* Bearer token for authentication. Sets the Authorization header directly.
|
|
3402
|
+
* Takes precedence over {@link apiKey} when both are set.
|
|
3403
|
+
*/
|
|
3404
|
+
bearerToken?: string;
|
|
3405
|
+
/**
|
|
3406
|
+
* Per-request bearer-token provider for managed-identity / on-demand auth.
|
|
3407
|
+
* When set, the SDK keeps this function client-side (it is never serialized)
|
|
3408
|
+
* and the runtime calls back into this client to acquire a token before each
|
|
3409
|
+
* outbound request. The runtime does no caching of its own, so the callback
|
|
3410
|
+
* owns token caching and refresh. When set alongside {@link apiKey} /
|
|
3411
|
+
* {@link bearerToken}, this callback takes precedence: the runtime applies
|
|
3412
|
+
* the token it returns as the `Authorization: Bearer` header for each
|
|
3413
|
+
* request and does not send the static credential.
|
|
3414
|
+
*
|
|
3415
|
+
* @experimental
|
|
3416
|
+
*/
|
|
3417
|
+
bearerTokenProvider?: BearerTokenProvider;
|
|
3418
|
+
/**
|
|
3419
|
+
* Azure-specific options.
|
|
3420
|
+
*/
|
|
3421
|
+
azure?: {
|
|
3422
|
+
/**
|
|
3423
|
+
* API version. When set, uses the versioned deployment route. When
|
|
3424
|
+
* omitted, uses the GA versionless v1 route.
|
|
3425
|
+
*/
|
|
3426
|
+
apiVersion?: string;
|
|
3427
|
+
};
|
|
3428
|
+
/**
|
|
3429
|
+
* Custom HTTP headers to include in all outbound requests to the provider.
|
|
3430
|
+
*/
|
|
3431
|
+
headers?: GeneratedNamedProviderConfig["headers"];
|
|
3432
|
+
}
|
|
3433
|
+
/**
|
|
3434
|
+
* A BYOK model definition that references a {@link NamedProviderConfig} by name
|
|
3435
|
+
* and is added to the session's selectable model list.
|
|
3436
|
+
*
|
|
3437
|
+
* Each model has three identities:
|
|
3438
|
+
* - {@link id}: the provider-local model id, unique within its provider. The
|
|
3439
|
+
* session-wide selection id (shown in the model list and passed to model
|
|
3440
|
+
* switching) is the provider-qualified `provider/id`.
|
|
3441
|
+
* - {@link modelId}: the well-known behavior base model used for
|
|
3442
|
+
* capability/config lookup. Defaults to {@link id}.
|
|
3443
|
+
* - {@link wireModel}: the model name actually sent to the provider API for
|
|
3444
|
+
* inference. Defaults to {@link id}.
|
|
3445
|
+
*
|
|
3446
|
+
* @experimental This type is part of an experimental multi-provider BYOK surface
|
|
3447
|
+
* and may change or be removed in future SDK or CLI releases.
|
|
3448
|
+
*/
|
|
3449
|
+
export interface ProviderModelConfig {
|
|
3450
|
+
/**
|
|
3451
|
+
* Forward-compatible persisted on-device Auto annotation.
|
|
3452
|
+
*/
|
|
3453
|
+
autoLocal?: JsonValue;
|
|
3454
|
+
/**
|
|
3455
|
+
* Provider-published model metadata, including live Auto routing annotations.
|
|
3456
|
+
*/
|
|
3457
|
+
metadata?: Record<string, JsonValue | undefined>;
|
|
3458
|
+
/**
|
|
3459
|
+
* Provider-local model id, unique within its provider. The session-wide
|
|
3460
|
+
* selection id is the provider-qualified `provider/id`.
|
|
3461
|
+
*/
|
|
3462
|
+
id: string;
|
|
3463
|
+
/**
|
|
3464
|
+
* Name of the {@link NamedProviderConfig} that serves this model.
|
|
3465
|
+
*/
|
|
3466
|
+
provider: string;
|
|
3467
|
+
/**
|
|
3468
|
+
* The model name sent to the provider API for inference. Defaults to {@link id}.
|
|
3469
|
+
*/
|
|
3470
|
+
wireModel?: string;
|
|
3471
|
+
/**
|
|
3472
|
+
* Well-known base model id used for behavior/capability/config lookup.
|
|
3473
|
+
* Defaults to {@link id}.
|
|
3474
|
+
*/
|
|
3475
|
+
modelId?: string;
|
|
3476
|
+
/**
|
|
3477
|
+
* Display name for model pickers. Defaults to the provider-qualified
|
|
3478
|
+
* selection id (`provider/id`).
|
|
3479
|
+
*/
|
|
3480
|
+
name?: string;
|
|
3481
|
+
/**
|
|
3482
|
+
* Maximum prompt/input tokens for the model.
|
|
3483
|
+
*/
|
|
3484
|
+
maxPromptTokens?: number;
|
|
3485
|
+
/**
|
|
3486
|
+
* Maximum context window tokens for the model.
|
|
3487
|
+
*/
|
|
3488
|
+
maxContextWindowTokens?: number;
|
|
3489
|
+
/**
|
|
3490
|
+
* Maximum output tokens for the model.
|
|
3491
|
+
*/
|
|
3492
|
+
maxOutputTokens?: number;
|
|
3493
|
+
/**
|
|
3494
|
+
* Optional capability overrides (vision, tool_calls, reasoning, etc.) for
|
|
3495
|
+
* the synthesized model.
|
|
3496
|
+
*/
|
|
3497
|
+
capabilities?: ModelCapabilitiesOverride;
|
|
3498
|
+
}
|
|
3499
|
+
/**
|
|
3500
|
+
* Message provenance, independent of delivery mode.
|
|
3501
|
+
*/
|
|
3502
|
+
export type MessageSource = "user" | "system" | `agent-${string}` | `automation-${string}`;
|
|
3503
|
+
/** Structured context contributed by an extension. */
|
|
3504
|
+
export type ExtensionContextAttachment = GeneratedExtensionContextAttachment;
|
|
3505
|
+
export interface MessageOptions {
|
|
3506
|
+
/**
|
|
3507
|
+
* The prompt/message to send
|
|
3508
|
+
*/
|
|
3509
|
+
prompt: string;
|
|
3510
|
+
/**
|
|
3511
|
+
* Optional message provenance. Omitted by default to preserve the runtime's
|
|
3512
|
+
* default for user messages. Use "system" for application-generated context,
|
|
3513
|
+
* `agent-${id}` for messages originating from an identified agent, or
|
|
3514
|
+
* `automation-${id}` for turns sent on behalf of an automation the user
|
|
3515
|
+
* configured, with a non-empty ID. An automation turn defines the session's
|
|
3516
|
+
* task like a user message but carries no human authority.
|
|
3517
|
+
*/
|
|
3518
|
+
source?: MessageSource;
|
|
3519
|
+
/**
|
|
3520
|
+
* File, directory, selection, blob, or extension context attachments
|
|
3521
|
+
*/
|
|
3522
|
+
attachments?: Array<{
|
|
3523
|
+
type: "file";
|
|
3524
|
+
path: string;
|
|
3525
|
+
displayName?: string;
|
|
3526
|
+
} | {
|
|
3527
|
+
type: "directory";
|
|
3528
|
+
path: string;
|
|
3529
|
+
displayName?: string;
|
|
3530
|
+
} | {
|
|
3531
|
+
type: "selection";
|
|
3532
|
+
filePath: string;
|
|
3533
|
+
displayName: string;
|
|
3534
|
+
selection?: {
|
|
3535
|
+
start: {
|
|
3536
|
+
line: number;
|
|
3537
|
+
character: number;
|
|
3538
|
+
};
|
|
3539
|
+
end: {
|
|
3540
|
+
line: number;
|
|
3541
|
+
character: number;
|
|
3542
|
+
};
|
|
3543
|
+
};
|
|
3544
|
+
text?: string;
|
|
3545
|
+
} | {
|
|
3546
|
+
type: "blob";
|
|
3547
|
+
data: string;
|
|
3548
|
+
mimeType: string;
|
|
3549
|
+
displayName?: string;
|
|
3550
|
+
} | ExtensionContextAttachment>;
|
|
3551
|
+
/**
|
|
3552
|
+
* Message delivery mode
|
|
3553
|
+
* - "enqueue": Add to queue (default)
|
|
3554
|
+
* - "immediate": Send immediately
|
|
3555
|
+
*/
|
|
3556
|
+
mode?: "enqueue" | "immediate";
|
|
3557
|
+
/**
|
|
3558
|
+
* The UI mode the agent was in when this message was sent (for example "plan" or "autopilot").
|
|
3559
|
+
* Defaults to the session's current mode when unset.
|
|
3560
|
+
*/
|
|
3561
|
+
agentMode?: "interactive" | "plan" | "autopilot" | "shell";
|
|
3562
|
+
/**
|
|
3563
|
+
* Custom HTTP headers to include in outbound model requests for this turn.
|
|
3564
|
+
*/
|
|
3565
|
+
requestHeaders?: Record<string, string>;
|
|
3566
|
+
/**
|
|
3567
|
+
* If provided, this is shown in the timeline instead of `prompt`.
|
|
3568
|
+
*/
|
|
3569
|
+
displayPrompt?: string;
|
|
3570
|
+
/**
|
|
3571
|
+
* Opaque caller-chosen ID for the turn this message starts. The runtime copies it unchanged
|
|
3572
|
+
* into `_meta["com.github.copilot/turnId"]` on every MCP `tools/call` made while serving that
|
|
3573
|
+
* turn, including calls from sub-agents and Autopilot continuations. When a running turn
|
|
3574
|
+
* consumes the message as visible user steering, the value (or its absence) replaces the
|
|
3575
|
+
* turn's ID from the next model call onward. The `user.message` event for the message echoes
|
|
3576
|
+
* it as `clientTurnId` and is persisted like other events; the value stamped on MCP calls is
|
|
3577
|
+
* held in memory only and is not restored on resume.
|
|
3578
|
+
*/
|
|
3579
|
+
clientTurnId?: string;
|
|
3580
|
+
/**
|
|
3581
|
+
* JSON Schema or a Zod schema for this run's output, including requests after tool calls.
|
|
3582
|
+
* Independent sends do not inherit it. Ordinary immediate steering retains the active
|
|
3583
|
+
* schema and origin, even when promoted to a follow-up after the model request finishes.
|
|
3584
|
+
* Specifying a schema with mode "immediate" is rejected, even while idle.
|
|
3585
|
+
* This is not a persisted session default and does not survive a context reset.
|
|
3586
|
+
*
|
|
3587
|
+
* sendAndWait still returns an assistant message event. For a typed result, pass a
|
|
3588
|
+
* Zod-compatible schema as sendAndWait's second argument instead.
|
|
3589
|
+
* Streaming events remain text and may include intermediate messages.
|
|
3590
|
+
* Sent with strict: true and not rewritten, so provider schema restrictions apply: strict
|
|
3591
|
+
* OpenAI output needs an object root with every property required (use Zod's .nullable()
|
|
3592
|
+
* rather than .optional()).
|
|
3593
|
+
* Use rpc.send's responseFormat for provider-specific name, description and strict options.
|
|
3594
|
+
*/
|
|
3595
|
+
responseSchema?: ZodSchema | Record<string, unknown>;
|
|
3596
|
+
}
|
|
3597
|
+
/**
|
|
3598
|
+
* All possible event type strings from SessionEvent
|
|
3599
|
+
*/
|
|
3600
|
+
export type SessionEventType = SessionEvent["type"];
|
|
3601
|
+
/**
|
|
3602
|
+
* Extract the specific event payload for a given event type
|
|
3603
|
+
*/
|
|
3604
|
+
export type SessionEventPayload<T extends SessionEventType> = Extract<SessionEvent, {
|
|
3605
|
+
type: T;
|
|
3606
|
+
}>;
|
|
3607
|
+
/**
|
|
3608
|
+
* Event handler for a specific event type
|
|
3609
|
+
*/
|
|
3610
|
+
export type TypedSessionEventHandler<T extends SessionEventType> = (event: SessionEventPayload<T>) => void;
|
|
3611
|
+
/**
|
|
3612
|
+
* Event handler callback type (for all events)
|
|
3613
|
+
*/
|
|
3614
|
+
export type SessionEventHandler = (event: SessionEvent) => void;
|
|
3615
|
+
/**
|
|
3616
|
+
* Working directory context for a session
|
|
3617
|
+
*/
|
|
3618
|
+
export interface SessionContext {
|
|
3619
|
+
/** Working directory where the session was created */
|
|
3620
|
+
workingDirectory: string;
|
|
3621
|
+
/** Git repository root (if in a git repo) */
|
|
3622
|
+
gitRoot?: string;
|
|
3623
|
+
/** GitHub repository in "owner/repo" format */
|
|
3624
|
+
repository?: string;
|
|
3625
|
+
/** Current git branch */
|
|
3626
|
+
branch?: string;
|
|
3627
|
+
}
|
|
3628
|
+
/**
|
|
3629
|
+
* Configuration for a custom session filesystem provider.
|
|
3630
|
+
*/
|
|
3631
|
+
export interface SessionFsConfig {
|
|
3632
|
+
/**
|
|
3633
|
+
* Initial working directory for sessions (user's project directory).
|
|
3634
|
+
*/
|
|
3635
|
+
initialCwd: string;
|
|
3636
|
+
/**
|
|
3637
|
+
* Path within each session's SessionFs where the runtime stores
|
|
3638
|
+
* session-scoped files (events, workspace, checkpoints, etc.).
|
|
3639
|
+
*/
|
|
3640
|
+
sessionStatePath: string;
|
|
3641
|
+
/**
|
|
3642
|
+
* Path conventions used by this filesystem provider.
|
|
3643
|
+
*/
|
|
3644
|
+
conventions: "windows" | "posix";
|
|
3645
|
+
/**
|
|
3646
|
+
* Optional capabilities declared by this provider.
|
|
3647
|
+
* The runtime uses these to determine which features are available.
|
|
3648
|
+
*/
|
|
3649
|
+
capabilities?: {
|
|
3650
|
+
/**
|
|
3651
|
+
* Whether this provider supports SQLite query/exists operations.
|
|
3652
|
+
* When false or omitted, the runtime will not offer SQL tools or
|
|
3653
|
+
* todo tracking for sessions using this provider.
|
|
3654
|
+
* @default false
|
|
3655
|
+
*/
|
|
3656
|
+
sqlite?: boolean;
|
|
3657
|
+
/**
|
|
3658
|
+
* Whether this provider supports exact binary reads and writes through readFileBytes and writeFileBytes.
|
|
3659
|
+
* Required to view images stored only in the provider.
|
|
3660
|
+
* @default false
|
|
3661
|
+
*/
|
|
3662
|
+
binary?: boolean;
|
|
3663
|
+
/** Whether every session provider supports bounded byte-range reads, independently of binary support. */
|
|
3664
|
+
readFileRange?: boolean;
|
|
3665
|
+
};
|
|
3666
|
+
}
|
|
3667
|
+
/**
|
|
3668
|
+
* Filter options for listing sessions
|
|
3669
|
+
*/
|
|
3670
|
+
export interface SessionListFilter {
|
|
3671
|
+
/** Filter by exact working directory match */
|
|
3672
|
+
workingDirectory?: string;
|
|
3673
|
+
/** Filter by git root */
|
|
3674
|
+
gitRoot?: string;
|
|
3675
|
+
/** Filter by repository (owner/repo format) */
|
|
3676
|
+
repository?: string;
|
|
3677
|
+
/** Filter by branch */
|
|
3678
|
+
branch?: string;
|
|
3679
|
+
}
|
|
3680
|
+
/**
|
|
3681
|
+
* Metadata about a session
|
|
3682
|
+
*/
|
|
3683
|
+
export interface SessionMetadata {
|
|
3684
|
+
sessionId: string;
|
|
3685
|
+
startTime: Date;
|
|
3686
|
+
modifiedTime: Date;
|
|
3687
|
+
summary?: string;
|
|
3688
|
+
isRemote: boolean;
|
|
3689
|
+
/** Working directory context (working directory, git info) from session creation */
|
|
3690
|
+
context?: SessionContext;
|
|
3691
|
+
/**
|
|
3692
|
+
* Name of the client that created the session (for example `github/cli`). Omitted when
|
|
3693
|
+
* unknown.
|
|
3694
|
+
*/
|
|
3695
|
+
clientName?: string;
|
|
3696
|
+
/**
|
|
3697
|
+
* Name of the client that most recently ran the session: the client that created it, or a
|
|
3698
|
+
* client that resumed it and then ran it. Resuming a session only to observe it does not
|
|
3699
|
+
* change this. Omitted when unknown, such as for sessions persisted before this field
|
|
3700
|
+
* existed.
|
|
3701
|
+
*/
|
|
3702
|
+
lastClientName?: string;
|
|
3703
|
+
}
|
|
3704
|
+
/**
|
|
3705
|
+
* Response from status.get
|
|
3706
|
+
*/
|
|
3707
|
+
export interface GetStatusResponse {
|
|
3708
|
+
/** Package version (e.g., "1.0.0") */
|
|
3709
|
+
version: string;
|
|
3710
|
+
/** Protocol version for SDK compatibility */
|
|
3711
|
+
protocolVersion: number;
|
|
3712
|
+
/** Host diagnostics, when supplied by the runtime. */
|
|
3713
|
+
hostDiagnostics?: HostDiagnostics;
|
|
3714
|
+
}
|
|
3715
|
+
/**
|
|
3716
|
+
* Response from auth.getStatus
|
|
3717
|
+
*/
|
|
3718
|
+
export interface GetAuthStatusResponse {
|
|
3719
|
+
/** Whether the user is authenticated */
|
|
3720
|
+
isAuthenticated: boolean;
|
|
3721
|
+
/** Authentication type */
|
|
3722
|
+
authType?: "user" | "env" | "gh-cli" | "hmac" | "api-key" | "token";
|
|
3723
|
+
/** GitHub host URL */
|
|
3724
|
+
host?: string;
|
|
3725
|
+
/** User login name */
|
|
3726
|
+
login?: string;
|
|
3727
|
+
/** Human-readable status message */
|
|
3728
|
+
statusMessage?: string;
|
|
3729
|
+
}
|
|
3730
|
+
/**
|
|
3731
|
+
* Model capabilities and limits
|
|
3732
|
+
*/
|
|
3733
|
+
export interface ModelCapabilities {
|
|
3734
|
+
supports: {
|
|
3735
|
+
vision: boolean;
|
|
3736
|
+
/** Whether this model supports reasoning effort configuration */
|
|
3737
|
+
reasoningEffort: boolean;
|
|
3738
|
+
};
|
|
3739
|
+
limits: {
|
|
3740
|
+
max_prompt_tokens?: number;
|
|
3741
|
+
max_output_tokens?: number;
|
|
3742
|
+
max_context_window_tokens: number;
|
|
3743
|
+
vision?: {
|
|
3744
|
+
supported_media_types: string[];
|
|
3745
|
+
max_prompt_images: number;
|
|
3746
|
+
max_prompt_image_size: number;
|
|
3747
|
+
};
|
|
3748
|
+
};
|
|
3749
|
+
}
|
|
3750
|
+
/** Recursively makes all properties optional, preserving arrays as-is. */
|
|
3751
|
+
type DeepPartial<T> = T extends readonly (infer U)[] ? DeepPartial<U>[] : T extends object ? {
|
|
3752
|
+
[K in keyof T]?: DeepPartial<T[K]>;
|
|
3753
|
+
} : T;
|
|
3754
|
+
/** Deep-partial override for model capabilities — every property at any depth is optional. */
|
|
3755
|
+
export type ModelCapabilitiesOverride = DeepPartial<ModelCapabilities>;
|
|
3756
|
+
/**
|
|
3757
|
+
* Model policy state
|
|
3758
|
+
*/
|
|
3759
|
+
export interface ModelPolicy {
|
|
3760
|
+
state: "enabled" | "disabled" | "unconfigured";
|
|
3761
|
+
terms: string;
|
|
3762
|
+
}
|
|
3763
|
+
/**
|
|
3764
|
+
* Model billing information
|
|
3765
|
+
*/
|
|
3766
|
+
export interface ModelBilling {
|
|
3767
|
+
/** Billing cost multiplier relative to the base rate */
|
|
3768
|
+
multiplier?: number;
|
|
3769
|
+
/** Token-level pricing information for this model */
|
|
3770
|
+
tokenPrices?: ModelBillingTokenPrices;
|
|
3771
|
+
}
|
|
3772
|
+
/**
|
|
3773
|
+
* Information about an available model
|
|
3774
|
+
*/
|
|
3775
|
+
export interface ModelInfo {
|
|
3776
|
+
/** Model identifier (e.g., "claude-sonnet-4.5") */
|
|
3777
|
+
id: string;
|
|
3778
|
+
/** Display name */
|
|
3779
|
+
name: string;
|
|
3780
|
+
/** Native serving provider, when attributed by the runtime. Absent for configured BYOK models. */
|
|
3781
|
+
provider?: ModelProviderRef;
|
|
3782
|
+
/** Model capabilities and limits */
|
|
3783
|
+
capabilities: ModelCapabilities;
|
|
3784
|
+
/** Policy state */
|
|
3785
|
+
policy?: ModelPolicy;
|
|
3786
|
+
/** Billing information */
|
|
3787
|
+
billing?: ModelBilling;
|
|
3788
|
+
/** Supported reasoning effort levels (only present if model supports reasoning effort) */
|
|
3789
|
+
supportedReasoningEfforts?: ReasoningEffort[];
|
|
3790
|
+
/** Default reasoning effort level (only present if model supports reasoning effort) */
|
|
3791
|
+
defaultReasoningEffort?: ReasoningEffort;
|
|
3792
|
+
}
|
|
3793
|
+
/**
|
|
3794
|
+
* Types of session lifecycle events.
|
|
3795
|
+
*/
|
|
3796
|
+
export type SessionLifecycleEventType = "session.created" | "session.deleted" | "session.updated" | "session.foreground" | "session.background";
|
|
3797
|
+
/**
|
|
3798
|
+
* Metadata payload for session lifecycle events. Not present on
|
|
3799
|
+
* `session.deleted` events.
|
|
3800
|
+
*/
|
|
3801
|
+
export interface SessionLifecycleEventMetadata {
|
|
3802
|
+
/** Time the session was created. */
|
|
3803
|
+
startTime: Date;
|
|
3804
|
+
/** Time the session was last modified. */
|
|
3805
|
+
modifiedTime: Date;
|
|
3806
|
+
/** Human-readable summary of the session, if available. */
|
|
3807
|
+
summary?: string;
|
|
3808
|
+
}
|
|
3809
|
+
/** Base shape shared by every lifecycle event variant. */
|
|
3810
|
+
interface SessionLifecycleEventBase {
|
|
3811
|
+
/** ID of the session this event relates to. */
|
|
3812
|
+
sessionId: string;
|
|
3813
|
+
/** Session metadata (not included for `session.deleted`). */
|
|
3814
|
+
metadata?: SessionLifecycleEventMetadata;
|
|
3815
|
+
}
|
|
3816
|
+
/** Emitted when a new session is created. */
|
|
3817
|
+
export interface SessionCreatedEvent extends SessionLifecycleEventBase {
|
|
3818
|
+
type: "session.created";
|
|
3819
|
+
metadata: SessionLifecycleEventMetadata;
|
|
3820
|
+
}
|
|
3821
|
+
/** Emitted when a session is deleted. The metadata field is omitted. */
|
|
3822
|
+
export interface SessionDeletedEvent extends SessionLifecycleEventBase {
|
|
3823
|
+
type: "session.deleted";
|
|
3824
|
+
metadata?: undefined;
|
|
3825
|
+
}
|
|
3826
|
+
/** Emitted when a session's metadata is updated. */
|
|
3827
|
+
export interface SessionUpdatedEvent extends SessionLifecycleEventBase {
|
|
3828
|
+
type: "session.updated";
|
|
3829
|
+
metadata: SessionLifecycleEventMetadata;
|
|
3830
|
+
}
|
|
3831
|
+
/** Emitted when a session is brought to the foreground (TUI+server mode). */
|
|
3832
|
+
export interface SessionForegroundEvent extends SessionLifecycleEventBase {
|
|
3833
|
+
type: "session.foreground";
|
|
3834
|
+
metadata: SessionLifecycleEventMetadata;
|
|
3835
|
+
}
|
|
3836
|
+
/** Emitted when a session is moved to the background (TUI+server mode). */
|
|
3837
|
+
export interface SessionBackgroundEvent extends SessionLifecycleEventBase {
|
|
3838
|
+
type: "session.background";
|
|
3839
|
+
metadata: SessionLifecycleEventMetadata;
|
|
3840
|
+
}
|
|
3841
|
+
/**
|
|
3842
|
+
* Discriminated union of all session lifecycle events emitted in TUI+server mode.
|
|
3843
|
+
* Switch on `type` to access the variant-specific metadata.
|
|
3844
|
+
*/
|
|
3845
|
+
export type SessionLifecycleEvent = SessionCreatedEvent | SessionDeletedEvent | SessionUpdatedEvent | SessionForegroundEvent | SessionBackgroundEvent;
|
|
3846
|
+
/**
|
|
3847
|
+
* Handler for session lifecycle events.
|
|
3848
|
+
*/
|
|
3849
|
+
export type SessionLifecycleHandler = (event: SessionLifecycleEvent) => void;
|
|
3850
|
+
/**
|
|
3851
|
+
* Typed handler for specific session lifecycle event types.
|
|
3852
|
+
*/
|
|
3853
|
+
export type TypedSessionLifecycleHandler<K extends SessionLifecycleEventType> = (event: Extract<SessionLifecycleEvent, {
|
|
3854
|
+
type: K;
|
|
3855
|
+
}>) => void;
|
|
3856
|
+
/**
|
|
3857
|
+
* Information about the foreground session in TUI+server mode
|
|
3858
|
+
*/
|
|
3859
|
+
export interface ForegroundSessionInfo {
|
|
3860
|
+
/** ID of the foreground session, or undefined if none */
|
|
3861
|
+
sessionId?: string;
|
|
3862
|
+
/** Workspace path of the foreground session */
|
|
3863
|
+
workspacePath?: string;
|
|
3864
|
+
}
|