@microsoft/copilot-sdk 2.0.0-preview.0 → 2.0.0-preview.1
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 +525 -374
- package/dist/cjs/cliVersion.js +1 -1
- package/dist/cjs/client.js +814 -559
- package/dist/cjs/extension.js +11 -9
- package/dist/cjs/generated/rpc.js +7 -7
- package/dist/cjs/sdkProtocolVersion.js +1 -1
- package/dist/cjs/session.js +2 -2
- package/dist/cjs/toolSet.js +1 -1
- package/dist/cjs/types.js +41 -13
- package/dist/cliVersion.d.ts +1 -1
- package/dist/cliVersion.js +1 -1
- package/dist/client.d.ts +46 -45
- package/dist/client.js +825 -562
- package/dist/extension.d.ts +7 -5
- package/dist/extension.js +11 -9
- package/dist/generated/rpc.d.ts +833 -436
- package/dist/generated/rpc.js +7 -7
- package/dist/generated/session-events.d.ts +16 -0
- package/dist/host.d.ts +7 -3
- package/dist/index.d.ts +2 -1
- package/dist/sdkProtocolVersion.d.ts +1 -1
- package/dist/sdkProtocolVersion.js +1 -1
- package/dist/session.d.ts +6 -6
- package/dist/session.js +2 -2
- package/dist/toolSet.d.ts +6 -5
- package/dist/toolSet.js +1 -1
- package/dist/types.d.ts +1252 -1293
- package/dist/types.js +41 -13
- package/docs/examples.md +1 -1
- package/package.json +12 -12
package/dist/types.d.ts
CHANGED
|
@@ -6,10 +6,10 @@ import type { SessionFsProvider } from "./sessionFsProvider.js";
|
|
|
6
6
|
import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
|
|
7
7
|
import type { InstallationConfirmationHandler } from "./installationConfirmation.js";
|
|
8
8
|
export type { InstallationConfirmationHandler } from "./installationConfirmation.js";
|
|
9
|
-
import type { AgentModelPolicy, AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier,
|
|
9
|
+
import type { AgentModelPolicy, AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, PermissionMode, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
|
|
10
10
|
import type { CopilotSession } from "./session.js";
|
|
11
11
|
import type { JsonValue } from "./workflow.js";
|
|
12
|
-
import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, FusionTier, AutopilotOptions, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, HostDiagnostics,
|
|
12
|
+
import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, FusionTier, AutopilotOptions, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, HostDiagnostics, Model, ModelCapabilitiesOverride, DiagnosticsConfiguration, OpenCanvasInstance, NamedProviderConfig as GeneratedNamedProviderConfig, ProviderConfigType, ProtocolExternalToolNamespace, CurrentToolMetadata, NetworkAuthenticateBasicRequest, NetworkAuthenticateBasicResult, NetworkAuthenticateNegotiateRequest, NetworkResolveProxyRequest, NetworkScope, SandboxConfig, SessionManagementCreateHostRequest, SessionManagementCreateResult } from "./generated/rpc.js";
|
|
13
13
|
import type { ToolSet } from "./toolSet.js";
|
|
14
14
|
export type { NetworkAuthenticateBasicRequest, NetworkAuthenticateBasicResult, NetworkAuthenticateNegotiateRequest, NetworkResolveProxyRequest, NetworkScope, } from "./generated/rpc.js";
|
|
15
15
|
export type { RemoteSessionMode } from "./generated/rpc.js";
|
|
@@ -46,7 +46,7 @@ export type GitHubTokenProviderResult = GitHubTokenAcquireResult;
|
|
|
46
46
|
* back to ambient authentication.
|
|
47
47
|
*/
|
|
48
48
|
export type GitHubTokenProvider = (args: GitHubTokenProviderArgs) => GitHubTokenProviderResult | Promise<GitHubTokenProviderResult>;
|
|
49
|
-
export type { ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, } from "./generated/rpc.js";
|
|
49
|
+
export type { Model, AdaptiveThinkingSupport, ModelCapabilities, ModelCapabilitiesSupports, ModelCapabilitiesLimits, ModelCapabilitiesLimitsVision, ModelCapabilitiesOverride, ModelCapabilitiesOverrideSupports, ModelCapabilitiesOverrideLimits, ModelCapabilitiesOverrideLimitsVision, ModelPolicy, ModelPolicyState, ModelBilling, ModelBillingPromo, ModelPickerCategory, ModelPickerPriceCategory, ModelMessage, ModelWarningText, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, } from "./generated/rpc.js";
|
|
50
50
|
export type SessionEvent = Exclude<GeneratedSessionEvent, {
|
|
51
51
|
type: "permission.requested";
|
|
52
52
|
}> | PermissionRequestedEvent;
|
|
@@ -89,7 +89,7 @@ export type TraceContextProvider = () => TraceContext | Promise<TraceContext>;
|
|
|
89
89
|
/**
|
|
90
90
|
* Configuration for OpenTelemetry instrumentation.
|
|
91
91
|
*
|
|
92
|
-
* When provided via {@link CopilotClientOptions.telemetry}, the SDK sets
|
|
92
|
+
* When provided via {@link CopilotClientOptions.observability.telemetry}, the SDK sets
|
|
93
93
|
* the corresponding startup configuration on the owned runtime, including
|
|
94
94
|
* in-process hosts, without changing the application's environment.
|
|
95
95
|
*/
|
|
@@ -111,30 +111,30 @@ export interface TelemetryConfig {
|
|
|
111
111
|
* Configures how a {@link CopilotClient} connects to the Copilot runtime.
|
|
112
112
|
* Construct via the factory functions on {@link RuntimeConnection}.
|
|
113
113
|
*/
|
|
114
|
-
export type RuntimeConnection =
|
|
114
|
+
export type RuntimeConnection = SpawnedStdioRuntimeConnection | InProcessRuntimeConnection | SpawnedTcpRuntimeConnection | TcpRuntimeConnection;
|
|
115
115
|
/**
|
|
116
116
|
* Shared shape for the transports that spawn a runtime **child process**
|
|
117
|
-
* ({@link
|
|
117
|
+
* ({@link SpawnedStdioRuntimeConnection} and {@link SpawnedTcpRuntimeConnection}).
|
|
118
118
|
*/
|
|
119
|
-
export interface ChildProcessRuntimeConnection {
|
|
120
|
-
/** Path to the runtime executable. When omitted, the bundled runtime is used. */
|
|
119
|
+
export interface ChildProcessRuntimeConnection extends OwnedRuntimeOptions {
|
|
121
120
|
readonly path?: string;
|
|
122
121
|
/** Extra command-line arguments to pass to the runtime process. */
|
|
123
122
|
readonly args?: readonly string[];
|
|
124
123
|
/**
|
|
125
124
|
* Environment variables for the spawned runtime child process, replacing the
|
|
126
|
-
* inherited environment.
|
|
127
|
-
*
|
|
128
|
-
* constructed. When omitted, the client-level env (or `process.env`) is used.
|
|
125
|
+
* inherited environment. Omit to inherit `process.env`; an empty map starts
|
|
126
|
+
* with no inherited variables. The SDK still adds its managed runtime settings.
|
|
129
127
|
*/
|
|
130
|
-
readonly env?: Record<string, string>;
|
|
128
|
+
readonly env?: Record<string, string | undefined>;
|
|
129
|
+
/** Working directory for the child process. Omit to inherit the current directory. */
|
|
130
|
+
readonly workingDirectory?: string;
|
|
131
131
|
}
|
|
132
132
|
/**
|
|
133
133
|
* Spawns a runtime child process and communicates over its stdin/stdout.
|
|
134
134
|
* Select this explicitly when the runtime needs a separate process.
|
|
135
135
|
*/
|
|
136
|
-
export interface
|
|
137
|
-
readonly kind: "stdio";
|
|
136
|
+
export interface SpawnedStdioRuntimeConnection extends ChildProcessRuntimeConnection {
|
|
137
|
+
readonly kind: "spawned-stdio";
|
|
138
138
|
}
|
|
139
139
|
/**
|
|
140
140
|
* Hosts the runtime in-process by loading the native runtime library and speaking
|
|
@@ -142,54 +142,38 @@ export interface StdioRuntimeConnection extends ChildProcessRuntimeConnection {
|
|
|
142
142
|
* native runtime runs in the application's process. Construct via
|
|
143
143
|
* {@link RuntimeConnection.forInProcess}.
|
|
144
144
|
*
|
|
145
|
-
* This is the default transport. Typed authentication, {@link CopilotClientOptions.telemetry} and
|
|
146
|
-
* {@link
|
|
145
|
+
* This is the default transport. Typed authentication, {@link CopilotClientOptions.observability.telemetry} and
|
|
146
|
+
* {@link OwnedRuntimeOptions.baseDirectory} are host-scoped.
|
|
147
147
|
* `env` and `workingDirectory` are unsupported; use
|
|
148
148
|
* per-session working directories.
|
|
149
149
|
*/
|
|
150
|
-
export interface InProcessRuntimeConnection {
|
|
150
|
+
export interface InProcessRuntimeConnection extends OwnedRuntimeOptions {
|
|
151
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
152
|
readonly runOnUiThread?: (action: () => void) => void | Promise<void>;
|
|
164
153
|
}
|
|
165
154
|
/**
|
|
166
155
|
* Spawns a runtime child process that listens on a TCP socket and connects to it.
|
|
167
156
|
*/
|
|
168
|
-
export interface
|
|
169
|
-
readonly kind: "tcp";
|
|
157
|
+
export interface SpawnedTcpRuntimeConnection extends ChildProcessRuntimeConnection {
|
|
158
|
+
readonly kind: "spawned-tcp";
|
|
170
159
|
/**
|
|
171
160
|
* TCP port to listen on. `0` (the default) auto-allocates a free port.
|
|
172
161
|
* If the chosen port is already in use, startup fails.
|
|
173
162
|
*/
|
|
174
163
|
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
164
|
readonly connectionToken?: string;
|
|
181
165
|
}
|
|
182
166
|
/**
|
|
183
|
-
* Connects to an already-running runtime
|
|
184
|
-
* spawn a process in this mode.
|
|
167
|
+
* Connects to an already-running runtime over plaintext TCP without owning its lifetime.
|
|
185
168
|
*/
|
|
186
|
-
export interface
|
|
187
|
-
readonly kind: "
|
|
169
|
+
export interface TcpRuntimeConnection {
|
|
170
|
+
readonly kind: "tcp";
|
|
188
171
|
/**
|
|
189
|
-
*
|
|
190
|
-
* full URL (`"http://host:port"`).
|
|
172
|
+
* Hostname or IP address, without a scheme, port, path, or IPv6 brackets.
|
|
191
173
|
*/
|
|
192
|
-
readonly
|
|
174
|
+
readonly host: string;
|
|
175
|
+
/** TCP port, from 1 through 65535. */
|
|
176
|
+
readonly port: number;
|
|
193
177
|
/** Optional shared secret to authenticate the connection. */
|
|
194
178
|
readonly connectionToken?: string;
|
|
195
179
|
}
|
|
@@ -198,37 +182,36 @@ export declare const RuntimeConnection: {
|
|
|
198
182
|
/**
|
|
199
183
|
* Spawn a runtime child process and communicate over its stdin/stdout.
|
|
200
184
|
*/
|
|
201
|
-
readonly
|
|
202
|
-
path?: string;
|
|
203
|
-
args?: readonly string[];
|
|
204
|
-
env?: Record<string, string>;
|
|
205
|
-
}) => StdioRuntimeConnection;
|
|
185
|
+
readonly forSpawnedStdio: (opts?: ChildProcessRuntimeConnection) => SpawnedStdioRuntimeConnection;
|
|
206
186
|
/**
|
|
207
187
|
* Spawn a runtime child process that listens on a TCP socket and connect to it.
|
|
208
188
|
*/
|
|
209
|
-
readonly
|
|
189
|
+
readonly forSpawnedTcp: (opts?: ChildProcessRuntimeConnection & {
|
|
210
190
|
port?: number;
|
|
211
191
|
connectionToken?: string;
|
|
212
|
-
|
|
213
|
-
args?: readonly string[];
|
|
214
|
-
env?: Record<string, string>;
|
|
215
|
-
}) => TcpRuntimeConnection;
|
|
192
|
+
}) => SpawnedTcpRuntimeConnection;
|
|
216
193
|
/**
|
|
217
|
-
* Connect to an already-running runtime
|
|
218
|
-
* spawn a process in this mode.
|
|
194
|
+
* Connect to an already-running runtime over plaintext TCP without owning its lifetime.
|
|
219
195
|
*/
|
|
220
|
-
readonly
|
|
196
|
+
readonly forTcp: (host: string, port: number, opts?: {
|
|
221
197
|
connectionToken?: string;
|
|
222
|
-
}) =>
|
|
198
|
+
}) => TcpRuntimeConnection;
|
|
223
199
|
/**
|
|
224
200
|
* Host the runtime in-process over the native runtime library's C ABI (FFI).
|
|
225
201
|
*
|
|
226
202
|
* The default when no connection or environment override is supplied.
|
|
227
|
-
* Runtime configuration from `
|
|
203
|
+
* Runtime configuration from `github.token`, `observability.telemetry` and
|
|
228
204
|
* `baseDirectory` is scoped to this host, not the process environment.
|
|
229
205
|
* Client-level `env` and `workingDirectory` are unsupported.
|
|
230
206
|
*/
|
|
231
|
-
readonly forInProcess: (options?: Pick<InProcessRuntimeConnection, "runOnUiThread">) => InProcessRuntimeConnection;
|
|
207
|
+
readonly forInProcess: (options?: Pick<InProcessRuntimeConnection, "runOnUiThread" | "baseDirectory" | "sessionIdleTimeoutSeconds">) => InProcessRuntimeConnection;
|
|
208
|
+
/**
|
|
209
|
+
* Resolves the SDK/deployment default at factory-call time, without starting a runtime.
|
|
210
|
+
* Honors COPILOT_SDK_DEFAULT_CONNECTION (stdio/inprocess, case-insensitive);
|
|
211
|
+
* unset or empty uses the installed SDK's default. Invalid values throw.
|
|
212
|
+
* Use a concrete factory when the hosting mode must be fixed.
|
|
213
|
+
*/
|
|
214
|
+
readonly forDefault: (options?: OwnedRuntimeOptions) => SpawnedStdioRuntimeConnection | InProcessRuntimeConnection;
|
|
232
215
|
};
|
|
233
216
|
/**
|
|
234
217
|
* Controls SDK defaults for ambient features.
|
|
@@ -271,7 +254,7 @@ export interface CopilotClientInfo {
|
|
|
271
254
|
integrationVersion?: string;
|
|
272
255
|
}
|
|
273
256
|
/** Host application's Microsoft Entra registration. @experimental */
|
|
274
|
-
export type EntraAuthConfig = Pick<import("./generated/rpc.js").EntraAuthConfig, "clientId" | "matsAppName">;
|
|
257
|
+
export type EntraAuthConfig = Pick<import("./generated/rpc.js").EntraAuthConfig, "clientId" | "matsAppName" | "oneAuthApplicationId">;
|
|
275
258
|
/** Host-owned Entra identity or resource acquisition. @experimental */
|
|
276
259
|
export type EntraTokenProviderArgs = import("./generated/rpc.js").EntraTokenAcquireRequest;
|
|
277
260
|
/** Response matching the requested acquisition kind and pinned account. @experimental */
|
|
@@ -297,122 +280,32 @@ export interface CopilotClientOptions {
|
|
|
297
280
|
entra?: EntraAuthOptions;
|
|
298
281
|
/**
|
|
299
282
|
* How to connect to the Copilot runtime. When omitted, defaults to
|
|
300
|
-
* {@link RuntimeConnection.
|
|
283
|
+
* {@link RuntimeConnection.forDefault}, which uses in-process hosting unless overridden.
|
|
301
284
|
*/
|
|
302
|
-
|
|
285
|
+
runtime?: RuntimeConnection;
|
|
303
286
|
/**
|
|
304
287
|
* Selects the SDK defaulting strategy. See {@link CopilotClientMode}.
|
|
305
288
|
*
|
|
306
289
|
* When set to `"empty"`, the SDK validates that the app has supplied the
|
|
307
|
-
* required configuration ({@link CopilotClientOptions.baseDirectory} or
|
|
290
|
+
* required configuration ({@link CopilotClientOptions.runtime.baseDirectory} or
|
|
308
291
|
* {@link CopilotClientOptions.sessionFs}, plus
|
|
309
|
-
* {@link
|
|
292
|
+
* {@link SessionOptionsBase.tools.availableTools} on each session).
|
|
310
293
|
*
|
|
311
294
|
* Required; select `"coding-agent"` or `"empty"` explicitly.
|
|
312
295
|
*/
|
|
313
296
|
mode: CopilotClientMode;
|
|
314
|
-
|
|
315
|
-
|
|
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;
|
|
297
|
+
plugins?: ClientPluginOptions;
|
|
298
|
+
extensions?: ClientExtensionOptions;
|
|
341
299
|
/**
|
|
342
300
|
* Network callbacks through which the SDK host decides the runtime's proxies and supplies its
|
|
343
301
|
* Kerberos tokens. Registered before sessions start.
|
|
344
302
|
* @experimental
|
|
345
303
|
*/
|
|
346
304
|
network?: NetworkConfig;
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
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;
|
|
305
|
+
installations?: ClientInstallationOptions;
|
|
306
|
+
observability?: ClientObservabilityOptions;
|
|
307
|
+
github?: ClientGitHubOptions;
|
|
308
|
+
models?: ClientModelOptions;
|
|
416
309
|
/**
|
|
417
310
|
* Custom session filesystem provider.
|
|
418
311
|
* When provided, the client registers as the session filesystem provider
|
|
@@ -420,48 +313,6 @@ export interface CopilotClientOptions {
|
|
|
420
313
|
* instead of the server's default local filesystem storage.
|
|
421
314
|
*/
|
|
422
315
|
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
316
|
/**
|
|
466
317
|
* Identity of the integrating application, forwarded to the runtime on the
|
|
467
318
|
* `server.connect` handshake. Declaring it lets the telemetry the runtime
|
|
@@ -1948,7 +1799,7 @@ export interface CustomAgentConfig {
|
|
|
1948
1799
|
* List of skill names to preload into this agent's context.
|
|
1949
1800
|
* When set, the full content of each listed skill is eagerly injected into
|
|
1950
1801
|
* the agent's context at startup. Skills are resolved by name from the
|
|
1951
|
-
* session's configured skill directories (`
|
|
1802
|
+
* session's configured skill directories (`skills.directories`).
|
|
1952
1803
|
* When omitted, no skills are injected (opt-in model).
|
|
1953
1804
|
*/
|
|
1954
1805
|
skills?: string[];
|
|
@@ -2202,10 +2053,12 @@ export interface CanvasProviderIdentity {
|
|
|
2202
2053
|
*
|
|
2203
2054
|
* These settings apply to the built-in Copilot API provider only. They live
|
|
2204
2055
|
* under their own namespace because a single session can host multiple
|
|
2205
|
-
* providers (CAPI alongside BYOK via {@link
|
|
2056
|
+
* providers (CAPI alongside BYOK via {@link NamedProviderConfig}), so transport and
|
|
2206
2057
|
* provider-level choices are conceptually per-provider rather than global.
|
|
2207
2058
|
*/
|
|
2208
2059
|
export interface CapiSessionOptions {
|
|
2060
|
+
/** Enables Copilot API models independently of GitHub identity. */
|
|
2061
|
+
enabled?: boolean;
|
|
2209
2062
|
/**
|
|
2210
2063
|
* Routing preference used when the session model is `auto`.
|
|
2211
2064
|
* Requires a runtime with Auto tier support and V2 Auto routing.
|
|
@@ -2316,7 +2169,7 @@ export declare const DisableBypassPermissionsModes: {
|
|
|
2316
2169
|
};
|
|
2317
2170
|
/**
|
|
2318
2171
|
* Permissions-only managed policy injected by the host via
|
|
2319
|
-
* {@link
|
|
2172
|
+
* {@link SessionOptionsBase.policy.managedSettings}.
|
|
2320
2173
|
*
|
|
2321
2174
|
* Rule strings use the same vocabulary the runtime accepts for fetched managed
|
|
2322
2175
|
* policy (e.g. `"Read(**)"`, `"Shell(git push *)"`); malformed rules are
|
|
@@ -2357,7 +2210,7 @@ export interface ManagedSettingsPermissions {
|
|
|
2357
2210
|
* Host-injected enterprise managed settings. The first supported contract is
|
|
2358
2211
|
* permissions-only; unknown sibling keys are rejected by the runtime.
|
|
2359
2212
|
*
|
|
2360
|
-
* @see {@link
|
|
2213
|
+
* @see {@link SessionOptionsBase.policy.managedSettings}
|
|
2361
2214
|
*/
|
|
2362
2215
|
export interface ManagedSettings {
|
|
2363
2216
|
/** Managed permission policy for the session. */
|
|
@@ -2377,7 +2230,7 @@ export type AskUserVariant = "legacy" | "elicitation";
|
|
|
2377
2230
|
* each call must finish within 30 seconds. Errors thrown by a provider are
|
|
2378
2231
|
* never shown to the model.
|
|
2379
2232
|
*
|
|
2380
|
-
* Supply a provider with {@link
|
|
2233
|
+
* Supply a provider with {@link SessionOptionsBase.skills.provider}. Providers
|
|
2381
2234
|
* aren't supported for cloud sessions.
|
|
2382
2235
|
*
|
|
2383
2236
|
* @experimental Session-scoped skill providers are experimental and may change
|
|
@@ -2417,19 +2270,13 @@ export interface SkillProviderCallOptions {
|
|
|
2417
2270
|
signal: AbortSignal;
|
|
2418
2271
|
}
|
|
2419
2272
|
/**
|
|
2420
|
-
* Shared configuration fields used by both {@link
|
|
2421
|
-
* creating a new session) and {@link
|
|
2273
|
+
* Shared configuration fields used by both {@link CreateSessionOptions} (for
|
|
2274
|
+
* creating a new session) and {@link ResumeSessionOptions} (for resuming
|
|
2422
2275
|
* an existing one).
|
|
2423
2276
|
*/
|
|
2424
|
-
export interface
|
|
2425
|
-
|
|
2426
|
-
|
|
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[];
|
|
2277
|
+
export interface SessionOptionsBase {
|
|
2278
|
+
inference?: SessionInferenceOptions;
|
|
2279
|
+
policy?: SessionPolicyOptions;
|
|
2433
2280
|
/**
|
|
2434
2281
|
* Client name to identify the application using the SDK.
|
|
2435
2282
|
* Included in the User-Agent header for API requests.
|
|
@@ -2439,27 +2286,7 @@ export interface SessionConfigBase {
|
|
|
2439
2286
|
* Model to use for this session
|
|
2440
2287
|
*/
|
|
2441
2288
|
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;
|
|
2289
|
+
experiments?: SessionExperimentOptions;
|
|
2463
2290
|
/**
|
|
2464
2291
|
* Enables session-scoped MCP diagnostic capture at the requested level.
|
|
2465
2292
|
*
|
|
@@ -2470,15 +2297,7 @@ export interface SessionConfigBase {
|
|
|
2470
2297
|
* diagnostic level.
|
|
2471
2298
|
*/
|
|
2472
2299
|
diagnostics?: DiagnosticsConfiguration;
|
|
2473
|
-
|
|
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;
|
|
2300
|
+
tools?: SessionToolOptions;
|
|
2482
2301
|
/**
|
|
2483
2302
|
* Override the default configuration directory location.
|
|
2484
2303
|
* When specified, the session will use this directory for storing config and state.
|
|
@@ -2486,515 +2305,817 @@ export interface SessionConfigBase {
|
|
|
2486
2305
|
configDirectory?: string;
|
|
2487
2306
|
/**
|
|
2488
2307
|
* Enables runtime discovery of supported configuration. Explicitly supplied
|
|
2489
|
-
* configuration takes precedence over discovered values.
|
|
2308
|
+
* configuration takes precedence over discovered values. Explicit feature roots
|
|
2309
|
+
* retain their independent discovery rules.
|
|
2490
2310
|
*
|
|
2491
2311
|
* @default false
|
|
2492
2312
|
*/
|
|
2493
2313
|
enableConfigDiscovery?: boolean;
|
|
2314
|
+
canvases?: SessionCanvasOptions;
|
|
2315
|
+
extensions?: SessionExtensionOptions;
|
|
2316
|
+
interaction?: SessionInteractionOptions;
|
|
2494
2317
|
/**
|
|
2495
|
-
*
|
|
2496
|
-
*
|
|
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.
|
|
2318
|
+
* System message configuration
|
|
2319
|
+
* Controls how the system prompt is constructed
|
|
2512
2320
|
*/
|
|
2513
|
-
|
|
2321
|
+
systemMessage?: SystemMessageConfig;
|
|
2322
|
+
agents?: SessionAgentOptions;
|
|
2323
|
+
skills?: SessionSkillOptions;
|
|
2324
|
+
github?: SessionGitHubOptions;
|
|
2325
|
+
filesystem?: SessionFilesystemOptions;
|
|
2326
|
+
execution?: SessionExecutionOptions;
|
|
2327
|
+
instructions?: SessionInstructionOptions;
|
|
2328
|
+
git?: SessionGitOptions;
|
|
2329
|
+
permissions?: SessionPermissionOptions;
|
|
2330
|
+
mcp?: SessionMcpOptions;
|
|
2331
|
+
hooks?: SessionHookOptions;
|
|
2514
2332
|
/**
|
|
2515
|
-
*
|
|
2516
|
-
*
|
|
2517
|
-
* this connection. Default off so callers that do not expose extensions
|
|
2518
|
-
* stay clean.
|
|
2333
|
+
* Working directory for the session.
|
|
2334
|
+
* Tool operations will be relative to this directory.
|
|
2519
2335
|
*/
|
|
2520
|
-
|
|
2336
|
+
workingDirectory?: string;
|
|
2337
|
+
events?: SessionEventOptions;
|
|
2338
|
+
plugins?: SessionPluginOptions;
|
|
2339
|
+
state?: SessionStateOptions;
|
|
2340
|
+
}
|
|
2341
|
+
/**
|
|
2342
|
+
* Configuration for creating a new session via {@link CopilotClient.createSession}.
|
|
2343
|
+
*/
|
|
2344
|
+
export interface CreateSessionOptions extends SessionOptionsBase {
|
|
2521
2345
|
/**
|
|
2522
|
-
* Optional
|
|
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.
|
|
2346
|
+
* Optional custom session ID. If not provided, the server generates one.
|
|
2532
2347
|
*/
|
|
2533
|
-
|
|
2348
|
+
sessionId?: string;
|
|
2534
2349
|
/**
|
|
2535
|
-
*
|
|
2536
|
-
*
|
|
2537
|
-
*
|
|
2350
|
+
* Names the session at creation, as `session.name.set` would, and is validated the
|
|
2351
|
+
* same way: non-empty, no leading or trailing whitespace, at most 100 UTF-16 units,
|
|
2352
|
+
* no control characters, and no double quotes. A name also makes the session persist
|
|
2353
|
+
* from the start, so it can be listed and resumed without ever running a turn.
|
|
2354
|
+
* Local sessions only: cloud creation rejects it.
|
|
2538
2355
|
*/
|
|
2539
|
-
|
|
2356
|
+
name?: string;
|
|
2357
|
+
filesystem?: CreateSessionFilesystemOptions;
|
|
2358
|
+
instructions?: CreateSessionInstructionOptions;
|
|
2540
2359
|
/**
|
|
2541
|
-
*
|
|
2542
|
-
*
|
|
2543
|
-
* canvas extension id, so canvases declared on a control connection survive
|
|
2544
|
-
* reconnect and CLI restart. Honored on session create and resume.
|
|
2360
|
+
* Creates a remote session in the cloud instead of a local session.
|
|
2361
|
+
* The optional repository is associated with the cloud session.
|
|
2545
2362
|
*/
|
|
2546
|
-
|
|
2363
|
+
cloud?: CloudSessionOptions;
|
|
2364
|
+
}
|
|
2365
|
+
/**
|
|
2366
|
+
* Configuration for resuming an existing session via
|
|
2367
|
+
* {@link CopilotClient.resumeSession}.
|
|
2368
|
+
*/
|
|
2369
|
+
export interface ResumeSessionOptions extends SessionOptionsBase {
|
|
2547
2370
|
/**
|
|
2548
|
-
*
|
|
2549
|
-
*
|
|
2550
|
-
* The handler is called when the user executes the command.
|
|
2371
|
+
* Allow the runtime to recover a damaged transcript during resume.
|
|
2372
|
+
* Defaults to true in all modes. Set false to reject recovery.
|
|
2551
2373
|
*/
|
|
2552
|
-
|
|
2374
|
+
allowTranscriptRecovery?: boolean;
|
|
2553
2375
|
/**
|
|
2554
|
-
*
|
|
2555
|
-
*
|
|
2376
|
+
* When true, skips emitting the session.resume event.
|
|
2377
|
+
* Useful for reconnecting to a session without triggering resume-related side effects.
|
|
2378
|
+
* @default false
|
|
2556
2379
|
*/
|
|
2557
|
-
|
|
2380
|
+
suppressResumeEvent?: boolean;
|
|
2558
2381
|
/**
|
|
2559
|
-
*
|
|
2382
|
+
* When true, the runtime continues any tool calls or permission prompts that were
|
|
2383
|
+
* still pending when the session was last suspended. When false (the default), the
|
|
2384
|
+
* runtime treats pending work as interrupted on resume. Completed tool results
|
|
2385
|
+
* already durably recorded by the runtime are preserved.
|
|
2560
2386
|
*
|
|
2561
|
-
*
|
|
2562
|
-
*
|
|
2563
|
-
*
|
|
2387
|
+
* When true, pending permission requests and external tool calls wait for
|
|
2388
|
+
* caller-supplied results via the corresponding low-level RPC methods. Resuming
|
|
2389
|
+
* does not re-emit restored permission requests or re-invoke permission handlers
|
|
2390
|
+
* or already-dispatched external tool callbacks.
|
|
2391
|
+
* If a pending call was recorded as SDK-handler-backed and resume registers a
|
|
2392
|
+
* handler for that tool, the abandoned callback is interrupted, never replayed.
|
|
2393
|
+
* Handlerless calls remain pending. To supply an abandoned callback's result
|
|
2394
|
+
* manually, resume without a handler for it. Older requests without recorded
|
|
2395
|
+
* callback ownership also remain pending.
|
|
2396
|
+
* @default false
|
|
2564
2397
|
*/
|
|
2565
|
-
|
|
2566
|
-
|
|
2567
|
-
|
|
2568
|
-
|
|
2569
|
-
|
|
2570
|
-
|
|
2398
|
+
continuePendingWork?: boolean;
|
|
2399
|
+
canvases?: ResumeSessionCanvasOptions;
|
|
2400
|
+
}
|
|
2401
|
+
/** Transcript repair proposed during the most recent resume. */
|
|
2402
|
+
export interface TranscriptRecovery {
|
|
2403
|
+
/** Planned backup path; the backup is written on the next append. */
|
|
2404
|
+
plannedBackupPath: string;
|
|
2405
|
+
/** One-based physical line numbers removed from the transcript. */
|
|
2406
|
+
invalidLineNumbers: number[];
|
|
2407
|
+
/** Whether an existing session.start event was moved to the beginning. */
|
|
2408
|
+
sessionStartMoved: boolean;
|
|
2409
|
+
}
|
|
2410
|
+
/**
|
|
2411
|
+
* Arguments passed to a {@link BearerTokenProvider} callback when the runtime needs a
|
|
2412
|
+
* fresh bearer token for a BYOK provider.
|
|
2413
|
+
*
|
|
2414
|
+
* @experimental Part of the experimental managed-identity / bearer-token-provider
|
|
2415
|
+
* surface and may change or be removed in future SDK or CLI releases.
|
|
2416
|
+
*/
|
|
2417
|
+
export interface ProviderTokenArgs {
|
|
2571
2418
|
/**
|
|
2572
|
-
*
|
|
2419
|
+
* Configured {@link NamedProviderConfig.name} of the BYOK provider needing a token.
|
|
2573
2420
|
*
|
|
2574
|
-
*
|
|
2575
|
-
*
|
|
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".
|
|
2421
|
+
* The callback closes over its own token scope/audience; the runtime is
|
|
2422
|
+
* provider-agnostic and forwards only the provider name.
|
|
2582
2423
|
*/
|
|
2583
|
-
|
|
2424
|
+
readonly providerName: string;
|
|
2584
2425
|
/**
|
|
2585
|
-
*
|
|
2586
|
-
*
|
|
2587
|
-
*
|
|
2588
|
-
*
|
|
2589
|
-
|
|
2426
|
+
* Id of the session that triggered this token request. A client-level shared
|
|
2427
|
+
* callback registered for many sessions can use this to resolve the owning
|
|
2428
|
+
* session (e.g. via the client's session lookup) to scope token acquisition
|
|
2429
|
+
* or caching per session.
|
|
2430
|
+
*/
|
|
2431
|
+
readonly sessionId: string;
|
|
2432
|
+
}
|
|
2433
|
+
/**
|
|
2434
|
+
* Per-provider callback that resolves a bearer token on demand, returning the
|
|
2435
|
+
* raw token string (without the `Bearer ` prefix). The Copilot SDK itself takes
|
|
2436
|
+
* no Azure dependency: the consumer supplies this callback backed by their own
|
|
2437
|
+
* identity library (for example `@azure/identity`'s
|
|
2438
|
+
* `DefaultAzureCredential.getToken(scope)`), and the runtime calls it once before
|
|
2439
|
+
* each outbound model request. The runtime does no caching of its own, so the
|
|
2440
|
+
* callback (or the identity library it wraps) owns token caching and refresh.
|
|
2441
|
+
*
|
|
2442
|
+
* @experimental Part of the experimental managed-identity / bearer-token-provider
|
|
2443
|
+
* surface and may change or be removed in future SDK or CLI releases.
|
|
2444
|
+
*/
|
|
2445
|
+
export type BearerTokenProvider = (args: ProviderTokenArgs) => Promise<string>;
|
|
2446
|
+
/**
|
|
2447
|
+
* Product serving a configured provider's model. Allowed values are
|
|
2448
|
+
* "openai", "anthropic", "azure_openai", "ollama", "lm_studio",
|
|
2449
|
+
* "foundry_local", and "llama_cpp".
|
|
2450
|
+
*/
|
|
2451
|
+
export type ProviderConfigModelProvider = "openai" | "anthropic" | "azure_openai" | "ollama" | "lm_studio" | "foundry_local" | "llama_cpp";
|
|
2452
|
+
/**
|
|
2453
|
+
* A named BYOK provider connection (transport + credentials only), referenced by
|
|
2454
|
+
* {@link ProviderModelConfig} entries via {@link NamedProviderConfig.name}.
|
|
2455
|
+
*
|
|
2456
|
+
* Connections coexist with GitHub identity. Copilot model availability is
|
|
2457
|
+
* controlled independently by {@link CapiSessionOptions.enabled}.
|
|
2458
|
+
*
|
|
2459
|
+
* @experimental This type is part of an experimental multi-provider BYOK surface
|
|
2460
|
+
* and may change or be removed in future SDK or CLI releases.
|
|
2461
|
+
*/
|
|
2462
|
+
export interface NamedProviderConfig {
|
|
2463
|
+
/**
|
|
2464
|
+
* Stable identifier referenced by {@link ProviderModelConfig.provider}.
|
|
2465
|
+
* Must not contain `/`.
|
|
2590
2466
|
*/
|
|
2591
|
-
|
|
2467
|
+
name: string;
|
|
2592
2468
|
/**
|
|
2593
|
-
*
|
|
2594
|
-
* agents are hidden from discovery and cannot be selected or invoked unless
|
|
2595
|
-
* a custom agent with the same name is configured.
|
|
2469
|
+
* Provider type. Defaults to "openai" for generic OpenAI-compatible APIs.
|
|
2596
2470
|
*/
|
|
2597
|
-
|
|
2471
|
+
type?: ProviderConfigType;
|
|
2598
2472
|
/**
|
|
2599
|
-
*
|
|
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.
|
|
2473
|
+
* Runtime options for a local model. The SDK forwards these options unchanged.
|
|
2604
2474
|
*/
|
|
2605
|
-
|
|
2475
|
+
localModel?: GeneratedNamedProviderConfig["localModel"];
|
|
2606
2476
|
/**
|
|
2607
|
-
*
|
|
2608
|
-
* omitting this option excludes all runtime-bundled skills; specifying names
|
|
2609
|
-
* opts those built-ins back in. Skills from other sources remain eligible.
|
|
2477
|
+
* Wire API format (openai/azure only). Defaults to "completions".
|
|
2610
2478
|
*/
|
|
2611
|
-
|
|
2479
|
+
wireApi?: "completions" | "responses";
|
|
2480
|
+
/** Transport. WebSockets require the OpenAI Responses API. Defaults to HTTP. */
|
|
2481
|
+
transport?: "http" | "websockets";
|
|
2612
2482
|
/**
|
|
2613
|
-
*
|
|
2614
|
-
*
|
|
2483
|
+
* Product serving this provider's models, such as "ollama" or "lm_studio",
|
|
2484
|
+
* reported in telemetry as `model_provider`. Only affects telemetry.
|
|
2615
2485
|
*/
|
|
2616
|
-
|
|
2486
|
+
modelProvider?: ProviderConfigModelProvider;
|
|
2617
2487
|
/**
|
|
2618
|
-
*
|
|
2619
|
-
* opting out of the WebSocket Responses transport. See
|
|
2620
|
-
* {@link CapiSessionOptions}.
|
|
2488
|
+
* API endpoint URL.
|
|
2621
2489
|
*/
|
|
2622
|
-
|
|
2490
|
+
baseUrl: string;
|
|
2623
2491
|
/**
|
|
2624
|
-
*
|
|
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.
|
|
2492
|
+
* API key. Optional for local providers like Ollama.
|
|
2635
2493
|
*/
|
|
2636
|
-
|
|
2494
|
+
apiKey?: string;
|
|
2637
2495
|
/**
|
|
2638
|
-
*
|
|
2639
|
-
*
|
|
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.
|
|
2496
|
+
* Command run before each request to obtain a fresh API key. Failure fails the
|
|
2497
|
+
* request without static-key fallback. Bearer authentication takes precedence.
|
|
2645
2498
|
*/
|
|
2646
|
-
|
|
2499
|
+
apiKeyCommand?: string;
|
|
2647
2500
|
/**
|
|
2648
|
-
*
|
|
2649
|
-
*
|
|
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}.
|
|
2501
|
+
* Bearer token for authentication. Sets the Authorization header directly.
|
|
2502
|
+
* Takes precedence over {@link apiKey} when both are set.
|
|
2654
2503
|
*/
|
|
2655
|
-
|
|
2504
|
+
bearerToken?: string;
|
|
2656
2505
|
/**
|
|
2657
|
-
*
|
|
2506
|
+
* Per-request bearer-token provider for managed-identity / on-demand auth.
|
|
2507
|
+
* When set, the SDK keeps this function client-side (it is never serialized)
|
|
2508
|
+
* and the runtime calls back into this client to acquire a token before each
|
|
2509
|
+
* outbound request. The runtime does no caching of its own, so the callback
|
|
2510
|
+
* owns token caching and refresh. When set alongside {@link apiKey}, {@link apiKeyCommand}, or
|
|
2511
|
+
* {@link bearerToken}, this callback takes precedence: the runtime applies
|
|
2512
|
+
* the token it returns as the `Authorization: Bearer` header for each
|
|
2513
|
+
* request and does not send the static credential or run the command.
|
|
2514
|
+
* Callback failures fail the request without credential fallback.
|
|
2658
2515
|
*
|
|
2659
2516
|
* @experimental
|
|
2660
2517
|
*/
|
|
2661
|
-
|
|
2518
|
+
bearerTokenProvider?: BearerTokenProvider;
|
|
2662
2519
|
/**
|
|
2663
|
-
*
|
|
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.
|
|
2520
|
+
* Azure-specific options.
|
|
2667
2521
|
*/
|
|
2668
|
-
|
|
2522
|
+
azure?: {
|
|
2523
|
+
/**
|
|
2524
|
+
* API version. When set, uses the versioned deployment route. When
|
|
2525
|
+
* omitted, uses the GA versionless v1 route.
|
|
2526
|
+
*/
|
|
2527
|
+
apiVersion?: string;
|
|
2528
|
+
};
|
|
2669
2529
|
/**
|
|
2670
|
-
*
|
|
2671
|
-
*
|
|
2672
|
-
* @experimental
|
|
2530
|
+
* Custom HTTP headers to include in all outbound requests to the provider.
|
|
2673
2531
|
*/
|
|
2674
|
-
|
|
2532
|
+
headers?: GeneratedNamedProviderConfig["headers"];
|
|
2533
|
+
}
|
|
2534
|
+
/**
|
|
2535
|
+
* A BYOK model definition that references a {@link NamedProviderConfig} by name
|
|
2536
|
+
* and is added to the session's selectable model list.
|
|
2537
|
+
*
|
|
2538
|
+
* Each model has three identities:
|
|
2539
|
+
* - {@link id}: the provider-local model id, unique within its provider. The
|
|
2540
|
+
* session-wide selection id (shown in the model list and passed to model
|
|
2541
|
+
* switching) is the provider-qualified `provider/id`.
|
|
2542
|
+
* - {@link modelId}: the well-known behavior base model used for
|
|
2543
|
+
* capability/config lookup. Defaults to {@link id}.
|
|
2544
|
+
* - {@link wireModel}: the model name actually sent to the provider API for
|
|
2545
|
+
* inference. Defaults to {@link id}.
|
|
2546
|
+
*
|
|
2547
|
+
* @experimental This type is part of an experimental multi-provider BYOK surface
|
|
2548
|
+
* and may change or be removed in future SDK or CLI releases.
|
|
2549
|
+
*/
|
|
2550
|
+
export interface ProviderModelConfig {
|
|
2675
2551
|
/**
|
|
2676
|
-
*
|
|
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
|
|
2552
|
+
* Forward-compatible persisted on-device Auto annotation.
|
|
2681
2553
|
*/
|
|
2682
|
-
|
|
2554
|
+
autoLocal?: JsonValue;
|
|
2683
2555
|
/**
|
|
2684
|
-
*
|
|
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.
|
|
2556
|
+
* Provider-published model metadata, including live Auto routing annotations.
|
|
2690
2557
|
*/
|
|
2691
|
-
|
|
2558
|
+
metadata?: Record<string, JsonValue | undefined>;
|
|
2692
2559
|
/**
|
|
2693
|
-
*
|
|
2694
|
-
*
|
|
2695
|
-
*
|
|
2696
|
-
* Defaults to `false`. Under {@link CopilotClientOptions.mode} = `"empty"`,
|
|
2697
|
-
* defaults to `true`; apps can pass `false` here to opt back in.
|
|
2560
|
+
* Provider-local model id, unique within its provider. The session-wide
|
|
2561
|
+
* selection id is the provider-qualified `provider/id`.
|
|
2698
2562
|
*/
|
|
2699
|
-
|
|
2563
|
+
id: string;
|
|
2700
2564
|
/**
|
|
2701
|
-
*
|
|
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.
|
|
2565
|
+
* Name of the {@link NamedProviderConfig} that serves this model.
|
|
2706
2566
|
*/
|
|
2707
|
-
|
|
2567
|
+
provider: string;
|
|
2708
2568
|
/**
|
|
2709
|
-
*
|
|
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.
|
|
2569
|
+
* The model name sent to the provider API for inference. Defaults to {@link id}.
|
|
2714
2570
|
*/
|
|
2715
|
-
|
|
2571
|
+
wireModel?: string;
|
|
2716
2572
|
/**
|
|
2717
|
-
*
|
|
2718
|
-
*
|
|
2719
|
-
* the consumer to resolve via the pending permission RPC.
|
|
2573
|
+
* Well-known base model id used for behavior/capability/config lookup.
|
|
2574
|
+
* Defaults to {@link id}.
|
|
2720
2575
|
*/
|
|
2721
|
-
|
|
2576
|
+
modelId?: string;
|
|
2722
2577
|
/**
|
|
2723
|
-
*
|
|
2724
|
-
*
|
|
2725
|
-
* host-provided token data or cancellation.
|
|
2578
|
+
* Display name for model pickers. Defaults to the provider-qualified
|
|
2579
|
+
* selection id (`provider/id`).
|
|
2726
2580
|
*/
|
|
2727
|
-
|
|
2581
|
+
name?: string;
|
|
2728
2582
|
/**
|
|
2729
|
-
*
|
|
2730
|
-
* When provided with the default `legacy` {@link AskUserVariant}, enables the
|
|
2731
|
-
* question-and-answer form of the `ask_user` tool.
|
|
2583
|
+
* Maximum prompt/input tokens for the model.
|
|
2732
2584
|
*/
|
|
2733
|
-
|
|
2585
|
+
maxPromptTokens?: number;
|
|
2734
2586
|
/**
|
|
2735
|
-
*
|
|
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.
|
|
2587
|
+
* Maximum context window tokens for the model.
|
|
2739
2588
|
*/
|
|
2740
|
-
|
|
2589
|
+
maxContextWindowTokens?: number;
|
|
2741
2590
|
/**
|
|
2742
|
-
*
|
|
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.
|
|
2591
|
+
* Maximum output tokens for the model.
|
|
2747
2592
|
*/
|
|
2748
|
-
|
|
2593
|
+
maxOutputTokens?: number;
|
|
2749
2594
|
/**
|
|
2750
|
-
*
|
|
2751
|
-
*
|
|
2752
|
-
* Also enables the `elicitation` capability on the session.
|
|
2595
|
+
* Optional capability overrides (vision, tool_calls, reasoning, etc.) for
|
|
2596
|
+
* the synthesized model.
|
|
2753
2597
|
*/
|
|
2754
|
-
|
|
2755
|
-
|
|
2756
|
-
|
|
2757
|
-
|
|
2758
|
-
|
|
2759
|
-
|
|
2760
|
-
|
|
2761
|
-
|
|
2762
|
-
|
|
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;
|
|
2598
|
+
capabilities?: ModelCapabilitiesOverride;
|
|
2599
|
+
}
|
|
2600
|
+
/**
|
|
2601
|
+
* Message provenance, independent of delivery mode.
|
|
2602
|
+
*/
|
|
2603
|
+
export type MessageSource = "user" | "system" | `agent-${string}` | `automation-${string}`;
|
|
2604
|
+
/** Structured context contributed by an extension. */
|
|
2605
|
+
export type ExtensionContextAttachment = GeneratedExtensionContextAttachment;
|
|
2606
|
+
export interface MessageOptions {
|
|
2789
2607
|
/**
|
|
2790
|
-
*
|
|
2791
|
-
* When provided, enables `exitPlanMode.request` callbacks.
|
|
2608
|
+
* The prompt/message to send
|
|
2792
2609
|
*/
|
|
2793
|
-
|
|
2610
|
+
prompt: string;
|
|
2794
2611
|
/**
|
|
2795
|
-
*
|
|
2796
|
-
*
|
|
2612
|
+
* Optional message provenance. Omitted by default to preserve the runtime's
|
|
2613
|
+
* default for user messages. Use "system" for application-generated context,
|
|
2614
|
+
* `agent-${id}` for messages originating from an identified agent, or
|
|
2615
|
+
* `automation-${id}` for turns sent on behalf of an automation the user
|
|
2616
|
+
* configured, with a non-empty ID. An automation turn defines the session's
|
|
2617
|
+
* task like a user message but carries no human authority.
|
|
2797
2618
|
*/
|
|
2798
|
-
|
|
2619
|
+
source?: MessageSource;
|
|
2799
2620
|
/**
|
|
2800
|
-
*
|
|
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
|
|
2621
|
+
* File, directory, selection, blob, or extension context attachments
|
|
2806
2622
|
*/
|
|
2807
|
-
|
|
2623
|
+
attachments?: Array<{
|
|
2624
|
+
type: "file";
|
|
2625
|
+
path: string;
|
|
2626
|
+
displayName?: string;
|
|
2627
|
+
} | {
|
|
2628
|
+
type: "directory";
|
|
2629
|
+
path: string;
|
|
2630
|
+
displayName?: string;
|
|
2631
|
+
} | {
|
|
2632
|
+
type: "selection";
|
|
2633
|
+
filePath: string;
|
|
2634
|
+
displayName: string;
|
|
2635
|
+
selection?: {
|
|
2636
|
+
start: {
|
|
2637
|
+
line: number;
|
|
2638
|
+
character: number;
|
|
2639
|
+
};
|
|
2640
|
+
end: {
|
|
2641
|
+
line: number;
|
|
2642
|
+
character: number;
|
|
2643
|
+
};
|
|
2644
|
+
};
|
|
2645
|
+
text?: string;
|
|
2646
|
+
} | {
|
|
2647
|
+
type: "blob";
|
|
2648
|
+
data: string;
|
|
2649
|
+
mimeType: string;
|
|
2650
|
+
displayName?: string;
|
|
2651
|
+
} | ExtensionContextAttachment>;
|
|
2808
2652
|
/**
|
|
2809
|
-
*
|
|
2810
|
-
*
|
|
2653
|
+
* Message delivery mode
|
|
2654
|
+
* - "enqueue": Add to queue (default)
|
|
2655
|
+
* - "immediate": Send immediately
|
|
2811
2656
|
*/
|
|
2812
|
-
|
|
2657
|
+
mode?: "enqueue" | "immediate";
|
|
2813
2658
|
/**
|
|
2814
|
-
*
|
|
2815
|
-
*
|
|
2659
|
+
* The UI mode the agent was in when this message was sent (for example "plan" or "autopilot").
|
|
2660
|
+
* Defaults to the session's current mode when unset.
|
|
2816
2661
|
*/
|
|
2817
|
-
|
|
2662
|
+
agentMode?: "interactive" | "plan" | "autopilot" | "shell";
|
|
2818
2663
|
/**
|
|
2819
|
-
*
|
|
2820
|
-
* Relative paths are resolved against the session's working directory.
|
|
2821
|
-
* Re-supply these directories when resuming a session.
|
|
2664
|
+
* Custom HTTP headers to include in outbound model requests for this turn.
|
|
2822
2665
|
*/
|
|
2823
|
-
|
|
2666
|
+
requestHeaders?: Record<string, string>;
|
|
2824
2667
|
/**
|
|
2825
|
-
*
|
|
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
|
|
2668
|
+
* If provided, this is shown in the timeline instead of `prompt`.
|
|
2830
2669
|
*/
|
|
2831
|
-
|
|
2670
|
+
displayPrompt?: string;
|
|
2832
2671
|
/**
|
|
2833
|
-
*
|
|
2834
|
-
*
|
|
2835
|
-
*
|
|
2836
|
-
*
|
|
2837
|
-
*
|
|
2838
|
-
*
|
|
2839
|
-
*
|
|
2672
|
+
* Opaque caller-chosen ID for the turn this message starts. The runtime copies it unchanged
|
|
2673
|
+
* into `_meta["com.github.copilot/turnId"]` on every MCP `tools/call` made while serving that
|
|
2674
|
+
* turn, including calls from sub-agents and Autopilot continuations. When a running turn
|
|
2675
|
+
* consumes the message as visible user steering, the value (or its absence) replaces the
|
|
2676
|
+
* turn's ID from the next model call onward. The `user.message` event for the message echoes
|
|
2677
|
+
* it as `clientTurnId` and is persisted like other events; the value stamped on MCP calls is
|
|
2678
|
+
* held in memory only and is not restored on resume.
|
|
2840
2679
|
*/
|
|
2841
|
-
|
|
2680
|
+
clientTurnId?: string;
|
|
2842
2681
|
/**
|
|
2843
|
-
*
|
|
2844
|
-
*
|
|
2845
|
-
*
|
|
2682
|
+
* JSON Schema or a Zod schema for this run's output, including requests after tool calls.
|
|
2683
|
+
* Independent sends do not inherit it. Ordinary immediate steering retains the active
|
|
2684
|
+
* schema and origin, even when promoted to a follow-up after the model request finishes.
|
|
2685
|
+
* Specifying a schema with mode "immediate" is rejected, even while idle.
|
|
2686
|
+
* This is not a persisted session default and does not survive a context reset.
|
|
2846
2687
|
*
|
|
2847
|
-
*
|
|
2688
|
+
* sendAndWait still returns an assistant message event. For a typed result, pass a
|
|
2689
|
+
* Zod-compatible schema as sendAndWait's second argument instead.
|
|
2690
|
+
* Streaming events remain text and may include intermediate messages.
|
|
2691
|
+
* Sent with strict: true and not rewritten, so provider schema restrictions apply: strict
|
|
2692
|
+
* OpenAI output needs an object root with every property required (use Zod's .nullable()
|
|
2693
|
+
* rather than .optional()).
|
|
2694
|
+
* Use rpc.send's responseFormat for provider-specific name, description and strict options.
|
|
2848
2695
|
*/
|
|
2849
|
-
|
|
2696
|
+
responseSchema?: ZodSchema | Record<string, unknown>;
|
|
2697
|
+
}
|
|
2698
|
+
/**
|
|
2699
|
+
* All possible event type strings from SessionEvent
|
|
2700
|
+
*/
|
|
2701
|
+
export type SessionEventType = SessionEvent["type"];
|
|
2702
|
+
/**
|
|
2703
|
+
* Extract the specific event payload for a given event type
|
|
2704
|
+
*/
|
|
2705
|
+
export type SessionEventPayload<T extends SessionEventType> = Extract<SessionEvent, {
|
|
2706
|
+
type: T;
|
|
2707
|
+
}>;
|
|
2708
|
+
/**
|
|
2709
|
+
* Event handler for a specific event type
|
|
2710
|
+
*/
|
|
2711
|
+
export type TypedSessionEventHandler<T extends SessionEventType> = (event: SessionEventPayload<T>) => void;
|
|
2712
|
+
/**
|
|
2713
|
+
* Event handler callback type (for all events)
|
|
2714
|
+
*/
|
|
2715
|
+
export type SessionEventHandler = (event: SessionEvent) => void;
|
|
2716
|
+
/**
|
|
2717
|
+
* Working directory context for a session
|
|
2718
|
+
*/
|
|
2719
|
+
export interface SessionContext {
|
|
2720
|
+
/** Working directory where the session was created */
|
|
2721
|
+
workingDirectory: string;
|
|
2722
|
+
/** Git repository root (if in a git repo) */
|
|
2723
|
+
gitRoot?: string;
|
|
2724
|
+
/** GitHub repository in "owner/repo" format */
|
|
2725
|
+
repository?: string;
|
|
2726
|
+
/** Current git branch */
|
|
2727
|
+
branch?: string;
|
|
2728
|
+
}
|
|
2729
|
+
/**
|
|
2730
|
+
* Configuration for a custom session filesystem provider.
|
|
2731
|
+
*/
|
|
2732
|
+
export interface SessionFsConfig {
|
|
2850
2733
|
/**
|
|
2851
|
-
*
|
|
2852
|
-
* When unset, no host identity is supplied.
|
|
2734
|
+
* Initial working directory for sessions (user's project directory).
|
|
2853
2735
|
*/
|
|
2854
|
-
|
|
2736
|
+
initialCwd: string;
|
|
2855
2737
|
/**
|
|
2856
|
-
*
|
|
2857
|
-
*
|
|
2738
|
+
* Path within each session's SessionFs where the runtime stores
|
|
2739
|
+
* session-scoped files (events, workspace, checkpoints, etc.).
|
|
2858
2740
|
*/
|
|
2859
|
-
|
|
2741
|
+
sessionStatePath: string;
|
|
2860
2742
|
/**
|
|
2861
|
-
*
|
|
2743
|
+
* Path conventions used by this filesystem provider.
|
|
2862
2744
|
*/
|
|
2863
|
-
|
|
2745
|
+
conventions: "windows" | "posix";
|
|
2864
2746
|
/**
|
|
2865
|
-
*
|
|
2866
|
-
*
|
|
2867
|
-
* Use `excludedTools` to hide specific tools from the default agent while keeping
|
|
2868
|
-
* them available to custom sub-agents.
|
|
2747
|
+
* Optional capabilities declared by this provider.
|
|
2748
|
+
* The runtime uses these to determine which features are available.
|
|
2869
2749
|
*/
|
|
2870
|
-
|
|
2750
|
+
capabilities?: {
|
|
2751
|
+
/**
|
|
2752
|
+
* Whether this provider supports SQLite query/exists operations.
|
|
2753
|
+
* When false or omitted, the runtime will not offer SQL tools or
|
|
2754
|
+
* todo tracking for sessions using this provider.
|
|
2755
|
+
* @default false
|
|
2756
|
+
*/
|
|
2757
|
+
sqlite?: boolean;
|
|
2758
|
+
/**
|
|
2759
|
+
* Whether this provider supports exact binary reads and writes through readFileBytes and writeFileBytes.
|
|
2760
|
+
* Required to view images stored only in the provider.
|
|
2761
|
+
* @default false
|
|
2762
|
+
*/
|
|
2763
|
+
binary?: boolean;
|
|
2764
|
+
/** Whether every session provider supports bounded byte-range reads, independently of binary support. */
|
|
2765
|
+
readFileRange?: boolean;
|
|
2766
|
+
};
|
|
2767
|
+
}
|
|
2768
|
+
/**
|
|
2769
|
+
* Filter options for listing sessions
|
|
2770
|
+
*/
|
|
2771
|
+
export interface SessionListFilter {
|
|
2772
|
+
/** Filter by exact working directory match */
|
|
2773
|
+
workingDirectory?: string;
|
|
2774
|
+
/** Filter by git root */
|
|
2775
|
+
gitRoot?: string;
|
|
2776
|
+
/** Filter by repository (owner/repo format) */
|
|
2777
|
+
repository?: string;
|
|
2778
|
+
/** Filter by branch */
|
|
2779
|
+
branch?: string;
|
|
2780
|
+
}
|
|
2781
|
+
/**
|
|
2782
|
+
* Metadata about a session
|
|
2783
|
+
*/
|
|
2784
|
+
export interface SessionMetadata {
|
|
2785
|
+
sessionId: string;
|
|
2786
|
+
startTime: Date;
|
|
2787
|
+
modifiedTime: Date;
|
|
2788
|
+
summary?: string;
|
|
2789
|
+
isRemote: boolean;
|
|
2790
|
+
/** Working directory context (working directory, git info) from session creation */
|
|
2791
|
+
context?: SessionContext;
|
|
2871
2792
|
/**
|
|
2872
|
-
* Name of the
|
|
2873
|
-
*
|
|
2874
|
-
* Equivalent to calling `session.rpc.agent.select({ name })` after creation.
|
|
2793
|
+
* Name of the client that created the session (for example `github/cli`). Omitted when
|
|
2794
|
+
* unknown.
|
|
2875
2795
|
*/
|
|
2876
|
-
|
|
2796
|
+
clientName?: string;
|
|
2877
2797
|
/**
|
|
2878
|
-
*
|
|
2879
|
-
*
|
|
2880
|
-
*
|
|
2881
|
-
*
|
|
2882
|
-
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
2798
|
+
* Name of the client that most recently ran the session: the client that created it, or a
|
|
2799
|
+
* client that resumed it and then ran it. Resuming a session only to observe it does not
|
|
2800
|
+
* change this. Omitted when unknown, such as for sessions persisted before this field
|
|
2801
|
+
* existed.
|
|
2883
2802
|
*/
|
|
2884
|
-
|
|
2803
|
+
lastClientName?: string;
|
|
2804
|
+
}
|
|
2805
|
+
/**
|
|
2806
|
+
* Response from status.get
|
|
2807
|
+
*/
|
|
2808
|
+
export interface GetStatusResponse {
|
|
2809
|
+
/** Package version (e.g., "1.0.0") */
|
|
2810
|
+
version: string;
|
|
2811
|
+
/** Protocol version for SDK compatibility */
|
|
2812
|
+
protocolVersion: number;
|
|
2813
|
+
/** Host diagnostics, when supplied by the runtime. */
|
|
2814
|
+
hostDiagnostics?: HostDiagnostics;
|
|
2815
|
+
}
|
|
2816
|
+
/**
|
|
2817
|
+
* Response from auth.getStatus
|
|
2818
|
+
*/
|
|
2819
|
+
export interface GetAuthStatusResponse {
|
|
2820
|
+
/** Whether the user is authenticated */
|
|
2821
|
+
isAuthenticated: boolean;
|
|
2822
|
+
/** Authentication type */
|
|
2823
|
+
authType?: "user" | "env" | "gh-cli" | "hmac" | "api-key" | "token";
|
|
2824
|
+
/** GitHub host URL */
|
|
2825
|
+
host?: string;
|
|
2826
|
+
/** User login name */
|
|
2827
|
+
login?: string;
|
|
2828
|
+
/** Human-readable status message */
|
|
2829
|
+
statusMessage?: string;
|
|
2830
|
+
}
|
|
2831
|
+
/**
|
|
2832
|
+
* Types of session lifecycle events.
|
|
2833
|
+
*/
|
|
2834
|
+
export type SessionLifecycleEventType = "session.created" | "session.deleted" | "session.updated" | "session.foreground" | "session.background";
|
|
2835
|
+
/**
|
|
2836
|
+
* Metadata payload for session lifecycle events. Not present on
|
|
2837
|
+
* `session.deleted` events.
|
|
2838
|
+
*/
|
|
2839
|
+
export interface SessionLifecycleEventMetadata {
|
|
2840
|
+
/** Time the session was created. */
|
|
2841
|
+
startTime: Date;
|
|
2842
|
+
/** Time the session was last modified. */
|
|
2843
|
+
modifiedTime: Date;
|
|
2844
|
+
/** Human-readable summary of the session, if available. */
|
|
2845
|
+
summary?: string;
|
|
2846
|
+
}
|
|
2847
|
+
/** Base shape shared by every lifecycle event variant. */
|
|
2848
|
+
interface SessionLifecycleEventBase {
|
|
2849
|
+
/** ID of the session this event relates to. */
|
|
2850
|
+
sessionId: string;
|
|
2851
|
+
/** Session metadata (not included for `session.deleted`). */
|
|
2852
|
+
metadata?: SessionLifecycleEventMetadata;
|
|
2853
|
+
}
|
|
2854
|
+
/** Emitted when a new session is created. */
|
|
2855
|
+
export interface SessionCreatedEvent extends SessionLifecycleEventBase {
|
|
2856
|
+
type: "session.created";
|
|
2857
|
+
metadata: SessionLifecycleEventMetadata;
|
|
2858
|
+
}
|
|
2859
|
+
/** Emitted when a session is deleted. The metadata field is omitted. */
|
|
2860
|
+
export interface SessionDeletedEvent extends SessionLifecycleEventBase {
|
|
2861
|
+
type: "session.deleted";
|
|
2862
|
+
metadata?: undefined;
|
|
2863
|
+
}
|
|
2864
|
+
/** Emitted when a session's metadata is updated. */
|
|
2865
|
+
export interface SessionUpdatedEvent extends SessionLifecycleEventBase {
|
|
2866
|
+
type: "session.updated";
|
|
2867
|
+
metadata: SessionLifecycleEventMetadata;
|
|
2868
|
+
}
|
|
2869
|
+
/** Emitted when a session is brought to the foreground (TUI+server mode). */
|
|
2870
|
+
export interface SessionForegroundEvent extends SessionLifecycleEventBase {
|
|
2871
|
+
type: "session.foreground";
|
|
2872
|
+
metadata: SessionLifecycleEventMetadata;
|
|
2873
|
+
}
|
|
2874
|
+
/** Emitted when a session is moved to the background (TUI+server mode). */
|
|
2875
|
+
export interface SessionBackgroundEvent extends SessionLifecycleEventBase {
|
|
2876
|
+
type: "session.background";
|
|
2877
|
+
metadata: SessionLifecycleEventMetadata;
|
|
2878
|
+
}
|
|
2879
|
+
/**
|
|
2880
|
+
* Discriminated union of all session lifecycle events emitted in TUI+server mode.
|
|
2881
|
+
* Switch on `type` to access the variant-specific metadata.
|
|
2882
|
+
*/
|
|
2883
|
+
export type SessionLifecycleEvent = SessionCreatedEvent | SessionDeletedEvent | SessionUpdatedEvent | SessionForegroundEvent | SessionBackgroundEvent;
|
|
2884
|
+
/**
|
|
2885
|
+
* Handler for session lifecycle events.
|
|
2886
|
+
*/
|
|
2887
|
+
export type SessionLifecycleHandler = (event: SessionLifecycleEvent) => void;
|
|
2888
|
+
/**
|
|
2889
|
+
* Typed handler for specific session lifecycle event types.
|
|
2890
|
+
*/
|
|
2891
|
+
export type TypedSessionLifecycleHandler<K extends SessionLifecycleEventType> = (event: Extract<SessionLifecycleEvent, {
|
|
2892
|
+
type: K;
|
|
2893
|
+
}>) => void;
|
|
2894
|
+
/**
|
|
2895
|
+
* Information about the foreground session in TUI+server mode
|
|
2896
|
+
*/
|
|
2897
|
+
export interface ForegroundSessionInfo {
|
|
2898
|
+
/** ID of the foreground session, or undefined if none */
|
|
2899
|
+
sessionId?: string;
|
|
2900
|
+
/** Workspace path of the foreground session */
|
|
2901
|
+
workspacePath?: string;
|
|
2902
|
+
}
|
|
2903
|
+
/** Host-bundled plugins registered before sessions start; not limited to extensions. */
|
|
2904
|
+
export interface ClientPluginOptions {
|
|
2885
2905
|
/**
|
|
2886
|
-
*
|
|
2887
|
-
*
|
|
2888
|
-
*
|
|
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.
|
|
2906
|
+
* Absolute paths to trusted plugin directories bundled by the host.
|
|
2907
|
+
* When non-empty, the complete set is registered with the runtime during
|
|
2908
|
+
* startup before any sessions can be created.
|
|
2899
2909
|
*/
|
|
2900
|
-
|
|
2910
|
+
builtinDirectories?: readonly string[];
|
|
2911
|
+
}
|
|
2912
|
+
/** Connection-level extension launch integration. */
|
|
2913
|
+
export interface ClientExtensionOptions {
|
|
2901
2914
|
/**
|
|
2902
|
-
*
|
|
2903
|
-
*
|
|
2904
|
-
*
|
|
2905
|
-
*
|
|
2906
|
-
*
|
|
2907
|
-
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
2915
|
+
* Connection-level extension launch profile provider.
|
|
2916
|
+
* When set, the client registers the provider during startup before any
|
|
2917
|
+
* session can be created.
|
|
2918
|
+
*
|
|
2919
|
+
* @experimental
|
|
2908
2920
|
*/
|
|
2909
|
-
|
|
2921
|
+
launchProvider?: ExtensionLaunchProvider;
|
|
2922
|
+
}
|
|
2923
|
+
/** @experimental App-initiated, runtime-managed installation workflows for MCP servers, skills, and plugins. */
|
|
2924
|
+
export interface ClientInstallationOptions {
|
|
2910
2925
|
/**
|
|
2911
|
-
*
|
|
2912
|
-
*
|
|
2913
|
-
*
|
|
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.
|
|
2926
|
+
* Connection-global human review for experimental installation operations.
|
|
2927
|
+
* Does not register or enable installation capabilities on the runtime.
|
|
2928
|
+
* @experimental
|
|
2918
2929
|
*/
|
|
2919
|
-
|
|
2930
|
+
confirmationHandler?: InstallationConfirmationHandler;
|
|
2931
|
+
}
|
|
2932
|
+
/** Logs and OpenTelemetry; a trace-context callback does not enable an exporter. */
|
|
2933
|
+
export interface ClientObservabilityOptions {
|
|
2920
2934
|
/**
|
|
2921
|
-
*
|
|
2922
|
-
*
|
|
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.
|
|
2935
|
+
* Log level for the Copilot runtime. When omitted, the runtime uses its
|
|
2936
|
+
* own default (currently `"info"`).
|
|
2932
2937
|
*/
|
|
2933
|
-
|
|
2938
|
+
logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
|
|
2934
2939
|
/**
|
|
2935
|
-
*
|
|
2936
|
-
*
|
|
2937
|
-
*
|
|
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.
|
|
2940
|
+
* OpenTelemetry startup configuration for the owned runtime.
|
|
2941
|
+
* Supports child-process and in-process hosts; omitted settings inherit
|
|
2942
|
+
* the application environment and runtime policy still takes precedence.
|
|
2941
2943
|
*/
|
|
2942
|
-
|
|
2944
|
+
telemetry?: TelemetryConfig;
|
|
2943
2945
|
/**
|
|
2944
|
-
*
|
|
2946
|
+
* Advanced: callback that returns the current W3C Trace Context for distributed
|
|
2947
|
+
* trace propagation. Most users do not need this — the {@link telemetry} config
|
|
2948
|
+
* alone is sufficient to collect traces from the CLI.
|
|
2949
|
+
*
|
|
2950
|
+
* This callback is only useful when your application creates its own
|
|
2951
|
+
* OpenTelemetry spans and you want them to appear in the **same** distributed
|
|
2952
|
+
* trace as the CLI's spans. The SDK calls this before `session.create`,
|
|
2953
|
+
* `session.resume`, and `session.send` RPCs to inject `traceparent`/`tracestate`
|
|
2954
|
+
* into the request.
|
|
2955
|
+
*
|
|
2956
|
+
* @example
|
|
2957
|
+
* ```typescript
|
|
2958
|
+
* import { propagation, context } from "@opentelemetry/api";
|
|
2959
|
+
*
|
|
2960
|
+
* const client = new CopilotClient({
|
|
2961
|
+
* observability: {
|
|
2962
|
+
* onGetTraceContext: () => {
|
|
2963
|
+
* const carrier: Record<string, string> = {};
|
|
2964
|
+
* propagation.inject(context.active(), carrier);
|
|
2965
|
+
* return carrier;
|
|
2966
|
+
* },
|
|
2967
|
+
* },
|
|
2968
|
+
* });
|
|
2969
|
+
* ```
|
|
2945
2970
|
*/
|
|
2946
|
-
|
|
2971
|
+
onGetTraceContext?: TraceContextProvider;
|
|
2972
|
+
}
|
|
2973
|
+
/** Owned-runtime GitHub authentication and first-party telemetry forwarding; not per-session identity. */
|
|
2974
|
+
export interface ClientGitHubOptions {
|
|
2947
2975
|
/**
|
|
2948
|
-
*
|
|
2949
|
-
*
|
|
2950
|
-
*
|
|
2976
|
+
* GitHub token to use for authentication.
|
|
2977
|
+
* When provided, the token is passed to the runtime via environment variable.
|
|
2978
|
+
* This takes priority over other authentication methods.
|
|
2951
2979
|
*/
|
|
2952
|
-
|
|
2980
|
+
token?: string;
|
|
2953
2981
|
/**
|
|
2954
|
-
*
|
|
2955
|
-
*
|
|
2956
|
-
*
|
|
2957
|
-
*
|
|
2958
|
-
*
|
|
2982
|
+
* Whether to use the logged-in user for authentication.
|
|
2983
|
+
* When true, the runtime will attempt to use stored OAuth tokens or gh CLI auth.
|
|
2984
|
+
* When false, only explicit tokens such as github.token are used; environment variable
|
|
2985
|
+
* tokens (COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN) are ignored.
|
|
2986
|
+
* @default true (but defaults to false when github.token is provided)
|
|
2959
2987
|
*/
|
|
2960
|
-
|
|
2988
|
+
useLoggedInUser?: boolean;
|
|
2961
2989
|
/**
|
|
2962
|
-
*
|
|
2963
|
-
* When
|
|
2964
|
-
*
|
|
2990
|
+
* Experimental. Receives GitHub telemetry events the runtime forwards to
|
|
2991
|
+
* this connection. When set, the client opts each session it creates or
|
|
2992
|
+
* resumes into telemetry forwarding and dispatches each
|
|
2993
|
+
* `gitHubTelemetry.event` notification to this connection-global handler;
|
|
2994
|
+
* each {@link GitHubTelemetryNotification} carries its originating
|
|
2995
|
+
* `sessionId`.
|
|
2996
|
+
*
|
|
2997
|
+
* @experimental
|
|
2965
2998
|
*/
|
|
2966
|
-
|
|
2999
|
+
onTelemetry?: (notification: GitHubTelemetryNotification) => void | Promise<void>;
|
|
3000
|
+
}
|
|
3001
|
+
/** Host overrides for model discovery and model-request transport. */
|
|
3002
|
+
export interface ClientModelOptions {
|
|
2967
3003
|
/**
|
|
2968
|
-
*
|
|
3004
|
+
* Custom handler for listing available models.
|
|
3005
|
+
* When provided, client.listModels() calls this handler instead of
|
|
3006
|
+
* querying the runtime. Useful in BYOK mode to return models
|
|
3007
|
+
* available from your custom provider.
|
|
2969
3008
|
*/
|
|
2970
|
-
|
|
3009
|
+
onListModels?: () => Promise<Model[]> | Model[];
|
|
2971
3010
|
/**
|
|
2972
|
-
*
|
|
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.
|
|
3011
|
+
* Custom handler for outbound model-layer requests (experimental).
|
|
2976
3012
|
*
|
|
2977
|
-
*
|
|
2978
|
-
*
|
|
2979
|
-
*
|
|
3013
|
+
* When provided, the client registers as the runtime's request handler
|
|
3014
|
+
* on connection: every outbound model-layer request the runtime would
|
|
3015
|
+
* otherwise have issued itself — plain HTTP, streaming SSE, and
|
|
3016
|
+
* WebSocket — is dispatched back to the handler over JSON-RPC. The
|
|
3017
|
+
* handler returns the response verbatim, exactly as if the runtime had
|
|
3018
|
+
* issued the request itself.
|
|
3019
|
+
*
|
|
3020
|
+
* Subclass {@link CopilotRequestHandler} and override the hooks you need;
|
|
3021
|
+
* an instance that overrides nothing is a transparent pass-through.
|
|
3022
|
+
*
|
|
3023
|
+
* v1 notes:
|
|
3024
|
+
* - HTTP (buffered and streaming SSE) and WebSocket transports are all
|
|
3025
|
+
* intercepted. The handler receives a `transport` discriminator on the
|
|
3026
|
+
* {@link CopilotRequestContext} for both.
|
|
3027
|
+
* - The handler is set process-globally on the runtime; the same
|
|
3028
|
+
* handler is invoked for every session created on this client.
|
|
3029
|
+
*
|
|
3030
|
+
* @experimental
|
|
2980
3031
|
*/
|
|
2981
|
-
|
|
3032
|
+
requestHandler?: CopilotRequestHandler;
|
|
3033
|
+
}
|
|
3034
|
+
/** Settings for runtimes owned by this client. Attached TCP connections use the existing server's configuration. */
|
|
3035
|
+
export interface OwnedRuntimeOptions {
|
|
2982
3036
|
/**
|
|
2983
|
-
*
|
|
2984
|
-
*
|
|
2985
|
-
*
|
|
2986
|
-
*
|
|
2987
|
-
*
|
|
2988
|
-
* registration ID remains internal to the SDK.
|
|
3037
|
+
* Base directory for Copilot data (session state, config, etc.).
|
|
3038
|
+
* Sets the COPILOT_HOME environment variable on the spawned runtime.
|
|
3039
|
+
* In-process hosts also keep their runtime cache in this directory's `cache` subdirectory.
|
|
3040
|
+
* When not set, the runtime defaults to ~/.copilot.
|
|
3041
|
+
* Unavailable when attaching to an existing runtime via {@link RuntimeConnection.forTcp}.
|
|
2989
3042
|
*/
|
|
2990
|
-
|
|
3043
|
+
readonly baseDirectory?: string;
|
|
2991
3044
|
/**
|
|
2992
|
-
*
|
|
2993
|
-
*
|
|
2994
|
-
*
|
|
2995
|
-
*
|
|
3045
|
+
* Server-wide idle timeout for sessions in seconds.
|
|
3046
|
+
* Sessions without activity for this duration are automatically cleaned up.
|
|
3047
|
+
* Set to 0 or omit to disable (sessions live indefinitely).
|
|
3048
|
+
* Unavailable when attaching to an existing runtime via {@link RuntimeConnection.forTcp}.
|
|
3049
|
+
* @default undefined (disabled)
|
|
2996
3050
|
*/
|
|
2997
|
-
|
|
3051
|
+
readonly sessionIdleTimeoutSeconds?: number;
|
|
3052
|
+
}
|
|
3053
|
+
/** Model tuning and provider catalog. The selected model ID stays top-level. */
|
|
3054
|
+
export interface SessionInferenceOptions {
|
|
3055
|
+
/**
|
|
3056
|
+
* Whether the model may request multiple tool calls per response. Defaults to true.
|
|
3057
|
+
* False sends a provider hint, not an execution guarantee: all returned calls
|
|
3058
|
+
* are still handled and handlers may run concurrently. Re-supply on cold resume.
|
|
3059
|
+
*/
|
|
3060
|
+
allowMultipleToolCalls?: boolean;
|
|
3061
|
+
/**
|
|
3062
|
+
* Reasoning effort level for models that support it.
|
|
3063
|
+
* Only valid for models where capabilities.supports.reasoningEffort is true.
|
|
3064
|
+
* Use client.listModels() to check supported values for each model.
|
|
3065
|
+
*/
|
|
3066
|
+
reasoningEffort?: ReasoningEffort;
|
|
3067
|
+
/**
|
|
3068
|
+
* Reasoning summary mode for models that support configurable reasoning summaries.
|
|
3069
|
+
* Use "none" to suppress summary output regardless of whether reasoning is enabled.
|
|
3070
|
+
*/
|
|
3071
|
+
reasoningSummary?: ReasoningSummary;
|
|
3072
|
+
/**
|
|
3073
|
+
* Context window tier for models that support it. Use "long_context" to pin
|
|
3074
|
+
* the session to the long-context tier; omit or use "default" otherwise.
|
|
3075
|
+
*/
|
|
3076
|
+
contextTier?: ContextTier;
|
|
3077
|
+
/** Per-property overrides for model capabilities, deep-merged over runtime defaults. */
|
|
3078
|
+
capabilities?: ModelCapabilitiesOverride;
|
|
3079
|
+
/**
|
|
3080
|
+
* Named BYOK provider connections (transport + credentials), referenced by
|
|
3081
|
+
* {@link models} entries via {@link NamedProviderConfig.name}.
|
|
3082
|
+
*
|
|
3083
|
+
* Connections do not disable GitHub identity. Copilot model availability is
|
|
3084
|
+
* controlled separately by {@link CapiSessionOptions.enabled}.
|
|
3085
|
+
*
|
|
3086
|
+
* @experimental This is part of an experimental multi-provider BYOK surface
|
|
3087
|
+
* and may change or be removed in future SDK or CLI releases.
|
|
3088
|
+
*/
|
|
3089
|
+
providers?: readonly NamedProviderConfig[];
|
|
3090
|
+
/**
|
|
3091
|
+
* BYOK model definitions added to the session's selectable model list, each
|
|
3092
|
+
* referencing a `providers[].name`. Each model surfaces under the
|
|
3093
|
+
* provider-qualified selection id `providerName/id`, so BYOK ids never collide
|
|
3094
|
+
* with — and cannot shadow — bare CAPI ids; duplicate selection ids are rejected.
|
|
3095
|
+
*
|
|
3096
|
+
* @experimental This is part of an experimental multi-provider BYOK surface
|
|
3097
|
+
* and may change or be removed in future SDK or CLI releases.
|
|
3098
|
+
*/
|
|
3099
|
+
models?: readonly ProviderModelConfig[];
|
|
3100
|
+
/**
|
|
3101
|
+
* Named connection for unqualified BYOK selections; requires github.capi.enabled=false.
|
|
3102
|
+
* Does not select the initial model: use the direct session model option.
|
|
3103
|
+
* Unregistered aliases use inferred metadata and session processing, without
|
|
3104
|
+
* provider-wide model defaults. Omission creates no default and preserves it
|
|
3105
|
+
* on resume; null clears it.
|
|
3106
|
+
*/
|
|
3107
|
+
defaultProvider?: string | null;
|
|
3108
|
+
/**
|
|
3109
|
+
* Enables native model citations for supported providers.
|
|
3110
|
+
*
|
|
3111
|
+
* @experimental
|
|
3112
|
+
*/
|
|
3113
|
+
enableCitations?: boolean;
|
|
3114
|
+
}
|
|
3115
|
+
/** Provider-neutral host/device policy. GitHub policy self-fetch is configured under github. */
|
|
3116
|
+
export interface SessionPolicyOptions {
|
|
3117
|
+
/** Exact model IDs allowed by the host. Omission preserves runtime policy. */
|
|
3118
|
+
allowedModels?: readonly string[];
|
|
2998
3119
|
/**
|
|
2999
3120
|
* Managed-setting paths this trusted host handles externally or does not
|
|
3000
3121
|
* support. Exact dotted paths exclude a setting and its descendants from
|
|
@@ -3002,40 +3123,23 @@ export interface SessionConfigBase {
|
|
|
3002
3123
|
* `"permissions.disableBypassPermissionsMode"`). MCP allow/deny controls
|
|
3003
3124
|
* are `"allowedMcpServers"` and `"deniedMcpServers"`, not an `"mcp"` subtree.
|
|
3004
3125
|
* Wildcards and array indices are unsupported. Unknown paths are accepted
|
|
3005
|
-
* for forward compatibility. Host-injected `managedSettings` and policy
|
|
3126
|
+
* for forward compatibility. Host-injected `policy.managedSettings` and policy
|
|
3006
3127
|
* availability checks are unaffected.
|
|
3007
3128
|
*
|
|
3008
3129
|
* Not persisted: re-supply on resume; omission restores full enforcement.
|
|
3009
3130
|
* This does not enable self-fetching; use `enableManagedSettings: true`.
|
|
3010
3131
|
*/
|
|
3011
|
-
excludedManagedSettings?: string[];
|
|
3132
|
+
excludedManagedSettings?: readonly string[];
|
|
3012
3133
|
/**
|
|
3013
3134
|
* When true, locked managed model controls are enforced for this session.
|
|
3014
3135
|
* Conflicting model changes are rejected, and locked startup values replace
|
|
3015
3136
|
* conflicting session options. Overridable managed defaults remain mutable.
|
|
3016
3137
|
*/
|
|
3017
3138
|
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
3139
|
/**
|
|
3036
3140
|
* Host-injected enterprise managed settings for this session.
|
|
3037
3141
|
*
|
|
3038
|
-
* Unlike {@link
|
|
3142
|
+
* Unlike {@link SessionOptionsBase.github.fetchManagedSettings} — which asks the
|
|
3039
3143
|
* runtime to *self-fetch* account/org and device policy — this field lets
|
|
3040
3144
|
* the host supply the managed policy directly. The runtime validates it
|
|
3041
3145
|
* with the same managed-permission parser it uses for fetched policy and
|
|
@@ -3047,818 +3151,673 @@ export interface SessionConfigBase {
|
|
|
3047
3151
|
* This is startup-only. It is **not** persisted: it must be re-supplied on
|
|
3048
3152
|
* {@link CopilotClient.resumeSession | resume}, where it replaces the prior
|
|
3049
3153
|
* injected layer (omitting it clears the layer, so warm and cold resume
|
|
3050
|
-
* behave identically). It may be combined with `
|
|
3154
|
+
* behave identically). It may be combined with `github.fetchManagedSettings`;
|
|
3051
3155
|
* when both are supplied the injected, server, and device restrictions all
|
|
3052
3156
|
* apply.
|
|
3053
3157
|
*
|
|
3054
|
-
* Requires a Copilot runtime whose RPC schema includes `managedSettings`.
|
|
3158
|
+
* Requires a Copilot runtime whose RPC schema includes `policy.managedSettings`.
|
|
3055
3159
|
* Older runtimes may ignore this additive field, so hosts must not rely on
|
|
3056
3160
|
* injected policy until they ship a compatible runtime.
|
|
3057
3161
|
*/
|
|
3058
3162
|
managedSettings?: ManagedSettings;
|
|
3163
|
+
}
|
|
3164
|
+
/** Feature experimentation. Trusted ExP assignment injection remains internal. */
|
|
3165
|
+
export interface SessionExperimentOptions {
|
|
3059
3166
|
/**
|
|
3060
|
-
*
|
|
3061
|
-
*
|
|
3062
|
-
* through the shared embedding cache.
|
|
3167
|
+
* Controls whether the session enables experimental features.
|
|
3168
|
+
* Defaults to `false` in `"empty"` mode; otherwise the runtime decides when unset.
|
|
3063
3169
|
*/
|
|
3064
|
-
|
|
3170
|
+
enableExperimentalMode?: boolean;
|
|
3065
3171
|
/**
|
|
3066
|
-
*
|
|
3067
|
-
* -
|
|
3068
|
-
* - `"in-memory"`: Embeddings are cached in memory only and discarded when the session ends.
|
|
3172
|
+
* Feature-flag values resolved by the host for this session.
|
|
3173
|
+
* Re-supply them when resuming after a runtime restart.
|
|
3069
3174
|
*/
|
|
3070
|
-
|
|
3175
|
+
flags?: Record<string, boolean>;
|
|
3176
|
+
}
|
|
3177
|
+
/** Tool definitions, exposure filters, discovery, and tool-specific behavior. Filters are not permission grants. */
|
|
3178
|
+
export interface SessionToolOptions {
|
|
3071
3179
|
/**
|
|
3072
|
-
*
|
|
3073
|
-
*
|
|
3074
|
-
*
|
|
3180
|
+
* Configuration for handling large tool outputs. When a tool produces
|
|
3181
|
+
* output exceeding the configured size, the output is written to a temp
|
|
3182
|
+
* file and a reference is returned to the model instead of the full
|
|
3183
|
+
* payload.
|
|
3075
3184
|
*/
|
|
3076
|
-
|
|
3185
|
+
largeOutput?: LargeToolOutputConfig;
|
|
3077
3186
|
/**
|
|
3078
|
-
*
|
|
3079
|
-
*
|
|
3187
|
+
* Tools exposed to the CLI server. Tools without a handler are declaration-only
|
|
3188
|
+
* and must be resolved by the consumer via pending external tool request RPCs.
|
|
3080
3189
|
*/
|
|
3081
|
-
|
|
3190
|
+
definitions?: readonly Tool<any>[];
|
|
3082
3191
|
/**
|
|
3083
|
-
*
|
|
3084
|
-
*
|
|
3085
|
-
*
|
|
3192
|
+
* Override for the runtime's built-in tool-search behavior.
|
|
3193
|
+
*
|
|
3194
|
+
* To also override the tool-search tool's implementation, register a
|
|
3195
|
+
* {@link Tool} named `tool_search_tool` with `overridesBuiltInTool: true` in
|
|
3196
|
+
* {@link SessionOptionsBase.tools.definitions}.
|
|
3086
3197
|
*/
|
|
3087
|
-
|
|
3198
|
+
search?: ToolSearchConfig;
|
|
3088
3199
|
/**
|
|
3089
|
-
*
|
|
3090
|
-
*
|
|
3091
|
-
* the system prompt.
|
|
3200
|
+
* Image generation opt-in. Re-supply after runtime restart.
|
|
3201
|
+
* @experimental This API may change or be removed in a future release.
|
|
3092
3202
|
*/
|
|
3093
|
-
|
|
3203
|
+
imageGeneration?: ImageGenerationConfig;
|
|
3094
3204
|
/**
|
|
3095
|
-
* When
|
|
3096
|
-
*
|
|
3097
|
-
*
|
|
3205
|
+
* List of tool names to allow. When specified, only these tools will be available.
|
|
3206
|
+
*
|
|
3207
|
+
* Supports source-qualified filter patterns (`builtin:*`, `builtin:<name>`,
|
|
3208
|
+
* `mcp:*`, `mcp:<name>`, `custom:*`, `custom:<name>`) as well as the bare
|
|
3209
|
+
* name form (exact match across any source). Build this list with
|
|
3210
|
+
* {@link ToolSet} for type safety and readable intent.
|
|
3211
|
+
*
|
|
3212
|
+
* Composes with {@link excludedTools}: a tool is enabled when it matches
|
|
3213
|
+
* `tools.availableTools` (or `tools.availableTools` is unset) AND it does not match
|
|
3214
|
+
* `tools.excludedTools`. This lets you express "everything matching X except Y".
|
|
3098
3215
|
*/
|
|
3099
|
-
|
|
3216
|
+
availableTools?: readonly string[] | ToolSet;
|
|
3100
3217
|
/**
|
|
3101
|
-
*
|
|
3102
|
-
*
|
|
3103
|
-
*
|
|
3218
|
+
* List of tool names to disable. Supports the same pattern syntax as
|
|
3219
|
+
* {@link availableTools}.
|
|
3220
|
+
*
|
|
3221
|
+
* Always takes precedence over {@link availableTools}: a tool listed here
|
|
3222
|
+
* is disabled even if it also matches `tools.availableTools`.
|
|
3104
3223
|
*/
|
|
3105
|
-
|
|
3224
|
+
excludedTools?: readonly string[] | ToolSet;
|
|
3106
3225
|
/**
|
|
3107
|
-
*
|
|
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.
|
|
3226
|
+
* When true, the `manage_schedule` tool is exposed to the agent.
|
|
3111
3227
|
*
|
|
3112
|
-
*
|
|
3113
|
-
*
|
|
3228
|
+
* Defaults to whatever the runtime exposes (typically gated to staff
|
|
3229
|
+
* users). Under {@link CopilotClientOptions.mode} = `"empty"`, defaults to
|
|
3230
|
+
* `false`; apps can pass `true` here to opt back in.
|
|
3114
3231
|
*/
|
|
3115
|
-
|
|
3232
|
+
manageScheduleEnabled?: boolean;
|
|
3233
|
+
}
|
|
3234
|
+
/** Canvas declarations, renderer opt-in, and stable provider identity. */
|
|
3235
|
+
export interface SessionCanvasOptions {
|
|
3116
3236
|
/**
|
|
3117
|
-
*
|
|
3118
|
-
*
|
|
3237
|
+
* Canvases contributed by this session participant. The declaring
|
|
3238
|
+
* connection becomes the live provider for `canvas.open|focus|close|reload`
|
|
3239
|
+
* and `canvas.action.invoke` dispatches targeting each canvas's `id` for
|
|
3240
|
+
* the lifetime of the connection. Re-declaring the same id on resume
|
|
3241
|
+
* replaces the prior declaration.
|
|
3119
3242
|
*/
|
|
3120
|
-
|
|
3243
|
+
definitions?: readonly Canvas[];
|
|
3121
3244
|
/**
|
|
3122
|
-
*
|
|
3123
|
-
*
|
|
3245
|
+
* Renderer-side opt-in: when true, the runtime surfaces canvas agent tools
|
|
3246
|
+
* (`list_canvas_capabilities`, `open_canvas`, `invoke_canvas_action`) to
|
|
3247
|
+
* the model for this connection. Default off so SDK callers that cannot
|
|
3248
|
+
* display canvases stay clean.
|
|
3124
3249
|
*/
|
|
3125
|
-
|
|
3126
|
-
}
|
|
3127
|
-
/**
|
|
3128
|
-
* Configuration for creating a new session via {@link CopilotClient.createSession}.
|
|
3129
|
-
*/
|
|
3130
|
-
export interface SessionConfig extends SessionConfigBase {
|
|
3250
|
+
requestRenderer?: boolean;
|
|
3131
3251
|
/**
|
|
3132
|
-
*
|
|
3252
|
+
* Stable identity for a host/SDK connection that supplies built-in
|
|
3253
|
+
* canvases. When set, the runtime uses `id` verbatim as the agent-facing
|
|
3254
|
+
* canvas extension id, so canvases declared on a control connection survive
|
|
3255
|
+
* reconnect and CLI restart. Honored on session create and resume.
|
|
3133
3256
|
*/
|
|
3134
|
-
|
|
3257
|
+
provider?: CanvasProviderIdentity;
|
|
3258
|
+
}
|
|
3259
|
+
/** Extension opt-in, SDK path, and identity; plugin loading is configured separately. */
|
|
3260
|
+
export interface SessionExtensionOptions {
|
|
3135
3261
|
/**
|
|
3136
|
-
*
|
|
3137
|
-
*
|
|
3138
|
-
*
|
|
3139
|
-
*
|
|
3140
|
-
* Local sessions only: cloud creation rejects it.
|
|
3262
|
+
* Extension surface opt-in: when true, the runtime wires extension
|
|
3263
|
+
* management tools and per-extension tool dispatch onto the session for
|
|
3264
|
+
* this connection. Default off so callers that do not expose extensions
|
|
3265
|
+
* stay clean.
|
|
3141
3266
|
*/
|
|
3142
|
-
|
|
3267
|
+
enabled?: boolean;
|
|
3143
3268
|
/**
|
|
3144
|
-
*
|
|
3145
|
-
*
|
|
3146
|
-
*
|
|
3269
|
+
* Optional override path to a `copilot-sdk/` folder to inject into
|
|
3270
|
+
* extension subprocesses for this session in place of the bundled SDK.
|
|
3271
|
+
* When unset or invalid (missing folder or missing `index.js` /
|
|
3272
|
+
* `extension.js`), the runtime falls back to the bundled SDK without
|
|
3273
|
+
* throwing. Takes precedence over any server-level default.
|
|
3274
|
+
*
|
|
3275
|
+
* Only honored on session create and resume — extensions joining via
|
|
3276
|
+
* `joinSession` cannot override the SDK path, because the extension
|
|
3277
|
+
* subprocess has already been forked by the host with the SDK the host
|
|
3278
|
+
* chose. `JoinSessionOptions` omits this field for that reason.
|
|
3147
3279
|
*/
|
|
3148
|
-
|
|
3280
|
+
sdkPath?: string;
|
|
3149
3281
|
/**
|
|
3150
|
-
*
|
|
3151
|
-
*
|
|
3152
|
-
*
|
|
3153
|
-
* or discovery. This does not watch files or enable disabled instruction loading.
|
|
3154
|
-
* @default false
|
|
3282
|
+
* Stable extension identity for canvas providers on this connection. When
|
|
3283
|
+
* set, the runtime uses `${source}:${name}` as the agent-facing extension
|
|
3284
|
+
* id instead of a reconnect-specific connection id.
|
|
3155
3285
|
*/
|
|
3156
|
-
|
|
3286
|
+
identity?: ExtensionInfo;
|
|
3287
|
+
}
|
|
3288
|
+
/** Human input, slash commands, and mode-switch interactions. */
|
|
3289
|
+
export interface SessionInteractionOptions {
|
|
3157
3290
|
/**
|
|
3158
|
-
*
|
|
3159
|
-
*
|
|
3291
|
+
* Handler for passwords and other answers that shell commands run by the
|
|
3292
|
+
* agent ask for. When provided, `sudo -A`, `ssh`, and `git` prompts reach
|
|
3293
|
+
* this handler instead of failing for lack of a terminal. Cancel requests
|
|
3294
|
+
* when nobody can answer, for example in autopilot.
|
|
3160
3295
|
*/
|
|
3161
|
-
|
|
3162
|
-
}
|
|
3163
|
-
/**
|
|
3164
|
-
* Configuration for resuming an existing session via
|
|
3165
|
-
* {@link CopilotClient.resumeSession}.
|
|
3166
|
-
*/
|
|
3167
|
-
export interface ResumeSessionConfig extends SessionConfigBase {
|
|
3296
|
+
onShellAuthenticationRequest?: ShellAuthenticationHandler;
|
|
3168
3297
|
/**
|
|
3169
|
-
*
|
|
3170
|
-
*
|
|
3298
|
+
* Slash commands registered for this session.
|
|
3299
|
+
* When the CLI has a TUI, each command appears as `/name` for the user to invoke.
|
|
3300
|
+
* The handler is called when the user executes the command.
|
|
3171
3301
|
*/
|
|
3172
|
-
|
|
3302
|
+
commands?: readonly CommandDefinition[];
|
|
3173
3303
|
/**
|
|
3174
|
-
*
|
|
3175
|
-
*
|
|
3176
|
-
*
|
|
3304
|
+
* Handler for user input requests from the agent.
|
|
3305
|
+
* When provided with the default `legacy` {@link AskUserVariant}, enables the
|
|
3306
|
+
* question-and-answer form of the `ask_user` tool.
|
|
3177
3307
|
*/
|
|
3178
|
-
|
|
3308
|
+
onUserInputRequest?: UserInputHandler;
|
|
3179
3309
|
/**
|
|
3180
|
-
*
|
|
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.
|
|
3310
|
+
* Selects the model-facing shape of the built-in `ask_user` tool.
|
|
3184
3311
|
*
|
|
3185
|
-
*
|
|
3186
|
-
*
|
|
3187
|
-
*
|
|
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
|
|
3312
|
+
* The default is `"legacy"`. To use `"elicitation"`, also provide
|
|
3313
|
+
* {@link onElicitationRequest} so the host can answer structured forms.
|
|
3314
|
+
* The runtime resolves this option when it creates or cold-resumes the session.
|
|
3195
3315
|
*/
|
|
3196
|
-
|
|
3316
|
+
askUserVariant?: AskUserVariant;
|
|
3197
3317
|
/**
|
|
3198
|
-
*
|
|
3199
|
-
* When provided
|
|
3200
|
-
*
|
|
3318
|
+
* Handler for elicitation requests from the agent.
|
|
3319
|
+
* When provided, the server calls back to this client for form-based UI dialogs.
|
|
3320
|
+
* Also enables the `elicitation` capability on the session.
|
|
3201
3321
|
*/
|
|
3202
|
-
|
|
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 {
|
|
3322
|
+
onElicitationRequest?: ElicitationHandler;
|
|
3221
3323
|
/**
|
|
3222
|
-
*
|
|
3223
|
-
*
|
|
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.
|
|
3324
|
+
* Handler for exit-plan-mode requests from the agent.
|
|
3325
|
+
* When provided, enables `exitPlanMode.request` callbacks.
|
|
3228
3326
|
*/
|
|
3229
|
-
|
|
3327
|
+
onExitPlanModeRequest?: ExitPlanModeHandler;
|
|
3230
3328
|
/**
|
|
3231
|
-
*
|
|
3232
|
-
*
|
|
3233
|
-
* session (e.g. via the client's session lookup) to scope token acquisition
|
|
3234
|
-
* or caching per session.
|
|
3329
|
+
* Handler for auto-mode-switch requests from the agent.
|
|
3330
|
+
* When provided, enables `autoModeSwitch.request` callbacks.
|
|
3235
3331
|
*/
|
|
3236
|
-
|
|
3332
|
+
onAutoModeSwitchRequest?: AutoModeSwitchHandler;
|
|
3333
|
+
/**
|
|
3334
|
+
* Opt in to runtime-owned recovery of an eligible active request using Auto.
|
|
3335
|
+
* Requires `interaction.onAutoModeSwitchRequest` and a runtime acknowledgment in
|
|
3336
|
+
* `session.capabilities.ui.autoModeRecovery`; unsupported enrollment rejects
|
|
3337
|
+
* create/resume and detaches the session. Re-supply when resuming.
|
|
3338
|
+
* Consent has no runtime deadline. The handler must not resend or rewind.
|
|
3339
|
+
* @default false
|
|
3340
|
+
*/
|
|
3341
|
+
autoModeRecovery?: boolean;
|
|
3237
3342
|
}
|
|
3238
|
-
/**
|
|
3239
|
-
|
|
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 {
|
|
3343
|
+
/** Agent definitions, selection, and source filters. */
|
|
3344
|
+
export interface SessionAgentOptions {
|
|
3261
3345
|
/**
|
|
3262
|
-
*
|
|
3346
|
+
* Names of built-in agents to exclude from the session. Excluded built-in
|
|
3347
|
+
* agents are hidden from discovery and cannot be selected or invoked unless
|
|
3348
|
+
* a custom agent with the same name is configured.
|
|
3263
3349
|
*/
|
|
3264
|
-
|
|
3350
|
+
excludedBuiltinAgents?: readonly string[];
|
|
3265
3351
|
/**
|
|
3266
|
-
*
|
|
3352
|
+
* Built-in subagent names to allow, subject to availability and
|
|
3353
|
+
* {@link excludedBuiltinAgents}. An empty array disables all built-in
|
|
3354
|
+
* subagents; custom agents remain available, including same-name agents.
|
|
3355
|
+
* Omission uses defaults on create or cold resume and preserves the current
|
|
3356
|
+
* allowlist on warm resume. Not persisted; re-supply on resume after restart.
|
|
3267
3357
|
*/
|
|
3268
|
-
|
|
3358
|
+
includedBuiltinAgents?: readonly string[];
|
|
3269
3359
|
/**
|
|
3270
|
-
*
|
|
3360
|
+
* When true, custom agents default to local-only execution and are not
|
|
3361
|
+
* dispatched to remote workers.
|
|
3271
3362
|
*
|
|
3272
|
-
*
|
|
3273
|
-
*
|
|
3274
|
-
* tool-call-heavy sessions that benefit from incremental
|
|
3275
|
-
* `previous_response_id` continuations. Applies to OpenAI-compatible
|
|
3276
|
-
* providers using `wireApi: "responses"`.
|
|
3363
|
+
* Defaults to `false`. Under {@link CopilotClientOptions.mode} = `"empty"`,
|
|
3364
|
+
* defaults to `true`; apps can pass `false` here to opt back in.
|
|
3277
3365
|
*/
|
|
3278
|
-
|
|
3366
|
+
localDiscoveryOnly?: boolean;
|
|
3279
3367
|
/**
|
|
3280
|
-
*
|
|
3281
|
-
* telemetry as `model_provider`. Only affects telemetry.
|
|
3368
|
+
* Custom agent configurations for the session.
|
|
3282
3369
|
*/
|
|
3283
|
-
|
|
3370
|
+
definitions?: readonly CustomAgentConfig[];
|
|
3284
3371
|
/**
|
|
3285
|
-
*
|
|
3372
|
+
* Configuration for the default agent (the built-in agent that handles
|
|
3373
|
+
* turns when no custom agent is selected).
|
|
3374
|
+
* Use `tools.excludedTools` to hide specific tools from the default agent while keeping
|
|
3375
|
+
* them available to custom sub-agents.
|
|
3286
3376
|
*/
|
|
3287
|
-
|
|
3377
|
+
default?: DefaultAgentConfig;
|
|
3288
3378
|
/**
|
|
3289
|
-
*
|
|
3379
|
+
* Name of the custom agent to activate when the session starts.
|
|
3380
|
+
* Must match the `name` of one of the agents in `agents.definitions`.
|
|
3381
|
+
* Equivalent to calling `session.rpc.agent.select({ name })` after creation.
|
|
3290
3382
|
*/
|
|
3291
|
-
|
|
3383
|
+
selected?: string;
|
|
3292
3384
|
/**
|
|
3293
|
-
*
|
|
3294
|
-
*
|
|
3295
|
-
*
|
|
3385
|
+
* Explicit discovery-only agent roots, separate from `agents.definitions` objects.
|
|
3386
|
+
* No general filesystem access is granted. Available without `enableConfigDiscovery`;
|
|
3387
|
+
* source and managed disables still apply.
|
|
3388
|
+
* Relative paths resolve once when supplied against the request's effective
|
|
3389
|
+
* `workingDirectory`, and retained roots do not move when it changes.
|
|
3390
|
+
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
3296
3391
|
*/
|
|
3297
|
-
|
|
3392
|
+
directories?: readonly string[];
|
|
3393
|
+
}
|
|
3394
|
+
/** Skill loading, sources, and provider callbacks. Reattach the provider on resume. */
|
|
3395
|
+
export interface SessionSkillOptions {
|
|
3298
3396
|
/**
|
|
3299
|
-
*
|
|
3300
|
-
*
|
|
3301
|
-
*
|
|
3397
|
+
* Built-in skill names to include in the session. In `mode: "empty"`,
|
|
3398
|
+
* omitting this option excludes all runtime-bundled skills; specifying names
|
|
3399
|
+
* opts those built-ins back in. Skills from other sources remain eligible.
|
|
3302
3400
|
*/
|
|
3303
|
-
|
|
3401
|
+
includedBuiltinSkills?: readonly string[];
|
|
3304
3402
|
/**
|
|
3305
|
-
*
|
|
3306
|
-
*
|
|
3307
|
-
*
|
|
3308
|
-
*
|
|
3309
|
-
*
|
|
3310
|
-
|
|
3311
|
-
|
|
3312
|
-
|
|
3403
|
+
* Explicit discovery-only skill roots. No general filesystem access is granted.
|
|
3404
|
+
* Available without `enableConfigDiscovery`; skill and managed disables still apply.
|
|
3405
|
+
* Relative paths resolve once when supplied against the request's effective
|
|
3406
|
+
* `workingDirectory`, and retained roots do not move when it changes.
|
|
3407
|
+
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
3408
|
+
*/
|
|
3409
|
+
directories?: readonly string[];
|
|
3410
|
+
/**
|
|
3411
|
+
* Supplies skills from the host's own storage instead of `SKILL.md` files on
|
|
3412
|
+
* disk. Provider skills join the session's skill catalog alongside file-based
|
|
3413
|
+
* skills. See {@link SkillProvider}.
|
|
3313
3414
|
*
|
|
3314
|
-
*
|
|
3415
|
+
* Supplying a provider enables skills unless `skills.enabled` is set explicitly,
|
|
3416
|
+
* so set `skills.enabled: true` when the client runs in `"empty"` mode. With
|
|
3417
|
+
* `skills.enabled: false` the provider stays bound but receives no calls.
|
|
3418
|
+
*
|
|
3419
|
+
* The provider isn't persisted. Pass it again when resuming the session;
|
|
3420
|
+
* resuming without one removes the provider's skills.
|
|
3421
|
+
*
|
|
3422
|
+
* @experimental Session-scoped skill providers are experimental and may change
|
|
3423
|
+
* or be removed in future SDK or CLI releases.
|
|
3315
3424
|
*/
|
|
3316
|
-
|
|
3425
|
+
provider?: SkillProvider;
|
|
3317
3426
|
/**
|
|
3318
|
-
*
|
|
3427
|
+
* List of skill names to disable.
|
|
3319
3428
|
*/
|
|
3320
|
-
|
|
3321
|
-
/**
|
|
3322
|
-
* API version. When omitted, the runtime uses the GA versionless v1 route.
|
|
3323
|
-
*/
|
|
3324
|
-
apiVersion?: string;
|
|
3325
|
-
};
|
|
3429
|
+
disabledSkills?: readonly string[];
|
|
3326
3430
|
/**
|
|
3327
|
-
*
|
|
3431
|
+
* When true, enables skill loading (including builtin skills and discovered
|
|
3432
|
+
* skill directories). When false, no skills are loaded regardless of
|
|
3433
|
+
* `skills.directories` or `enableConfigDiscovery` settings.
|
|
3328
3434
|
*/
|
|
3329
|
-
|
|
3435
|
+
enabled?: boolean;
|
|
3436
|
+
}
|
|
3437
|
+
/** Optional GitHub integrations and identity. Supply token or tokenProvider, or neither; never both. */
|
|
3438
|
+
export type SessionGitHubOptions = {
|
|
3330
3439
|
/**
|
|
3331
|
-
*
|
|
3332
|
-
*
|
|
3333
|
-
*
|
|
3334
|
-
* Falls back to {@link SessionConfig.model}.
|
|
3440
|
+
* Provider-scoped options for the built-in Copilot API (CAPI), such as
|
|
3441
|
+
* opting out of the WebSocket Responses transport. See
|
|
3442
|
+
* {@link CapiSessionOptions}.
|
|
3335
3443
|
*/
|
|
3336
|
-
|
|
3444
|
+
capi?: CapiSessionOptions;
|
|
3337
3445
|
/**
|
|
3338
|
-
*
|
|
3339
|
-
*
|
|
3340
|
-
*
|
|
3341
|
-
*
|
|
3446
|
+
* Enables or disables internal session telemetry for this session.
|
|
3447
|
+
* `false` disables it; `true` enables it for eligible GitHub-authenticated sessions,
|
|
3448
|
+
* including custom {@link provider} (BYOK) sessions. Omission preserves a resident
|
|
3449
|
+
* session's choice; otherwise defaults to enabled. Host and account policies still
|
|
3450
|
+
* determine whether telemetry can be uploaded.
|
|
3451
|
+
* This is independent of the OpenTelemetry configuration in {@link CopilotClientOptions.observability.telemetry}.
|
|
3342
3452
|
*/
|
|
3343
|
-
|
|
3453
|
+
telemetryEnabled?: boolean;
|
|
3344
3454
|
/**
|
|
3345
|
-
*
|
|
3346
|
-
*
|
|
3347
|
-
*
|
|
3348
|
-
*
|
|
3455
|
+
* Configuration for the built-in GitHub MCP server.
|
|
3456
|
+
*
|
|
3457
|
+
* `disableFormDeferral` only applies to the built-in GitHub MCP server and
|
|
3458
|
+
* only has an effect when MCP Apps and form-backed GitHub tools are enabled.
|
|
3349
3459
|
*/
|
|
3350
|
-
|
|
3460
|
+
mcp?: GitHubMcpToolConfig;
|
|
3351
3461
|
/**
|
|
3352
|
-
*
|
|
3353
|
-
*
|
|
3462
|
+
* GitHub token for per-session authentication.
|
|
3463
|
+
* When provided, the runtime resolves this token into a full GitHub identity
|
|
3464
|
+
* (login, Copilot plan, endpoints) and stores it on the session. This enables
|
|
3465
|
+
* multitenancy — different sessions can have different GitHub identities.
|
|
3466
|
+
*
|
|
3467
|
+
* This is independent of the client-level `github.token` in {@link CopilotClientOptions},
|
|
3468
|
+
* which authenticates the CLI process itself. The session-level token determines
|
|
3469
|
+
* the identity used for content exclusion, model routing, and quota checks.
|
|
3354
3470
|
*/
|
|
3355
|
-
|
|
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 {
|
|
3471
|
+
token?: string;
|
|
3370
3472
|
/**
|
|
3371
|
-
*
|
|
3372
|
-
*
|
|
3473
|
+
* Acquires short-lived GitHub credentials for this session on demand.
|
|
3474
|
+
*
|
|
3475
|
+
* Mutually exclusive with {@link SessionOptionsBase.github.token}. The
|
|
3476
|
+
* callback receives the effective GitHub host, the session ID when known,
|
|
3477
|
+
* and whether this is the initial acquisition or a refresh. Its opaque
|
|
3478
|
+
* registration ID remains internal to the SDK.
|
|
3373
3479
|
*/
|
|
3374
|
-
|
|
3480
|
+
tokenProvider?: GitHubTokenProvider;
|
|
3375
3481
|
/**
|
|
3376
|
-
*
|
|
3482
|
+
* Opt-in: when true, the runtime self-fetches enterprise managed settings
|
|
3483
|
+
* (bypass-permissions policy) at session bootstrap using the session's
|
|
3484
|
+
* `github.token`. Requires {@link SessionOptionsBase.github.token} to be set;
|
|
3485
|
+
* if omitted, the runtime is expected to reject session creation (fail-closed).
|
|
3377
3486
|
*/
|
|
3378
|
-
|
|
3487
|
+
fetchManagedSettings?: boolean;
|
|
3379
3488
|
/**
|
|
3380
|
-
*
|
|
3489
|
+
* Declares that a human drives this session's conversation, enabling
|
|
3490
|
+
* user-message analysis telemetry for user-authored messages. Automated
|
|
3491
|
+
* messages remain excluded. Defaults to false for SDK sessions; ignored
|
|
3492
|
+
* for cloud sessions and when resuming a session that is already active.
|
|
3381
3493
|
*/
|
|
3382
|
-
|
|
3494
|
+
interactiveUser?: boolean;
|
|
3495
|
+
} & ({
|
|
3383
3496
|
/**
|
|
3384
|
-
*
|
|
3497
|
+
* Acquires short-lived GitHub credentials for this session on demand.
|
|
3498
|
+
*
|
|
3499
|
+
* Mutually exclusive with {@link SessionOptionsBase.github.token}. The
|
|
3500
|
+
* callback receives the effective GitHub host, the session ID when known,
|
|
3501
|
+
* and whether this is the initial acquisition or a refresh. Its opaque
|
|
3502
|
+
* registration ID remains internal to the SDK.
|
|
3385
3503
|
*/
|
|
3386
|
-
|
|
3504
|
+
tokenProvider?: never;
|
|
3505
|
+
} | {
|
|
3387
3506
|
/**
|
|
3388
|
-
*
|
|
3389
|
-
*
|
|
3507
|
+
* GitHub token for per-session authentication.
|
|
3508
|
+
* When provided, the runtime resolves this token into a full GitHub identity
|
|
3509
|
+
* (login, Copilot plan, endpoints) and stores it on the session. This enables
|
|
3510
|
+
* multitenancy — different sessions can have different GitHub identities.
|
|
3511
|
+
*
|
|
3512
|
+
* This is independent of the client-level `github.token` in {@link CopilotClientOptions},
|
|
3513
|
+
* which authenticates the CLI process itself. The session-level token determines
|
|
3514
|
+
* the identity used for content exclusion, model routing, and quota checks.
|
|
3390
3515
|
*/
|
|
3391
|
-
|
|
3516
|
+
token?: never;
|
|
3517
|
+
});
|
|
3518
|
+
/** Directory access and tracking changes to project files; not session-state storage. */
|
|
3519
|
+
export interface SessionFilesystemOptions {
|
|
3392
3520
|
/**
|
|
3393
|
-
*
|
|
3521
|
+
* Opt in to capturing file changes for session rewind and cumulative session
|
|
3522
|
+
* diff. On create, capture starts with the first turn. On resume, this can
|
|
3523
|
+
* enable tracking only when the session still has a valid baseline; it cannot
|
|
3524
|
+
* reconstruct changes from earlier untracked turns.
|
|
3394
3525
|
*/
|
|
3395
|
-
|
|
3526
|
+
trackFileChanges?: boolean;
|
|
3396
3527
|
/**
|
|
3397
|
-
*
|
|
3528
|
+
* Additional directories the agent may access beyond the working directory.
|
|
3529
|
+
* Relative paths are resolved against the session's working directory.
|
|
3530
|
+
* Re-supply these directories when resuming a session.
|
|
3398
3531
|
*/
|
|
3399
|
-
|
|
3532
|
+
additionalDirectories?: readonly string[];
|
|
3533
|
+
}
|
|
3534
|
+
/** Accounting limits and autonomous continuation; autopilot policy does not select a session mode. */
|
|
3535
|
+
export interface SessionExecutionOptions {
|
|
3400
3536
|
/**
|
|
3401
|
-
*
|
|
3402
|
-
*
|
|
3537
|
+
* Limits applied to this session's current accounting window.
|
|
3538
|
+
*
|
|
3539
|
+
* @experimental
|
|
3403
3540
|
*/
|
|
3404
|
-
|
|
3541
|
+
limits?: SessionLimitsConfig;
|
|
3405
3542
|
/**
|
|
3406
|
-
*
|
|
3407
|
-
*
|
|
3408
|
-
*
|
|
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.
|
|
3543
|
+
* Autopilot policy. Omitted fields preserve resident values on warm resume;
|
|
3544
|
+
* new sessions default to continuation enabled and at most five continuations.
|
|
3545
|
+
* Does not change the session mode. Re-supply on cold resume.
|
|
3414
3546
|
*
|
|
3415
3547
|
* @experimental
|
|
3416
3548
|
*/
|
|
3417
|
-
|
|
3549
|
+
autopilot?: AutopilotOptions;
|
|
3550
|
+
}
|
|
3551
|
+
/** Instruction sources and discovery; the already-structured systemMessage stays top-level. */
|
|
3552
|
+
export interface SessionInstructionOptions {
|
|
3418
3553
|
/**
|
|
3419
|
-
*
|
|
3554
|
+
* When true, the runtime skips loading custom-instruction sources
|
|
3555
|
+
* (e.g. `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`).
|
|
3556
|
+
*
|
|
3557
|
+
* Defaults to `false` (custom instructions are loaded). Under
|
|
3558
|
+
* {@link CopilotClientOptions.mode} = `"empty"`, defaults to `true`; apps
|
|
3559
|
+
* can pass `false` here to opt back in.
|
|
3420
3560
|
*/
|
|
3421
|
-
|
|
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
|
-
};
|
|
3561
|
+
skipCustomInstructions?: boolean;
|
|
3428
3562
|
/**
|
|
3429
|
-
*
|
|
3563
|
+
* Explicit discovery-only instruction roots using the existing SDK instruction formats.
|
|
3564
|
+
* No general filesystem access is granted. Available without `enableConfigDiscovery`;
|
|
3565
|
+
* instruction and managed disables still apply.
|
|
3566
|
+
* Relative paths resolve once when supplied against the request's effective
|
|
3567
|
+
* `workingDirectory`, and retained roots do not move when it changes.
|
|
3568
|
+
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
3430
3569
|
*/
|
|
3431
|
-
|
|
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 {
|
|
3570
|
+
directories?: readonly string[];
|
|
3450
3571
|
/**
|
|
3451
|
-
*
|
|
3572
|
+
* Organization-level custom instructions to include in the system prompt.
|
|
3573
|
+
* Allows hosts to inject organization-specific guidance without relying on
|
|
3574
|
+
* filesystem-based instruction discovery.
|
|
3452
3575
|
*/
|
|
3453
|
-
|
|
3576
|
+
organizationText?: string;
|
|
3454
3577
|
/**
|
|
3455
|
-
*
|
|
3578
|
+
* When true, enables on-demand discovery of instruction files (AGENTS.md,
|
|
3579
|
+
* .github/copilot-instructions.md, etc.) after successful file views.
|
|
3456
3580
|
*/
|
|
3457
|
-
|
|
3581
|
+
onDemandDiscovery?: boolean;
|
|
3582
|
+
}
|
|
3583
|
+
/** Host Git context and commit attribution; independent of GitHub services. */
|
|
3584
|
+
export interface SessionGitOptions {
|
|
3458
3585
|
/**
|
|
3459
|
-
*
|
|
3460
|
-
*
|
|
3586
|
+
* When true, the runtime instructs the agent to include a `Co-authored-by`
|
|
3587
|
+
* trailer in commit messages it composes. Subagents inherit this setting.
|
|
3588
|
+
*
|
|
3589
|
+
* Defaults to `true`. Under {@link CopilotClientOptions.mode} = `"empty"`,
|
|
3590
|
+
* defaults to `false`; apps can pass `true` here to opt back in.
|
|
3461
3591
|
*/
|
|
3462
|
-
|
|
3592
|
+
coauthorEnabled?: boolean;
|
|
3463
3593
|
/**
|
|
3464
|
-
*
|
|
3594
|
+
* When true, enables git operations on the host filesystem (branch detection,
|
|
3595
|
+
* file status, commit history). When false, no git context is surfaced in
|
|
3596
|
+
* the system prompt.
|
|
3465
3597
|
*/
|
|
3466
|
-
|
|
3598
|
+
enableHostGitOperations?: boolean;
|
|
3599
|
+
}
|
|
3600
|
+
/** Permission decisions and sandboxing. Omitting onRequest preserves pending-request behavior. */
|
|
3601
|
+
export interface SessionPermissionOptions {
|
|
3467
3602
|
/**
|
|
3468
|
-
*
|
|
3603
|
+
* Optional handler for permission requests from the server.
|
|
3604
|
+
* When omitted, permission requests are surfaced as events and left pending for
|
|
3605
|
+
* the consumer to resolve via the pending permission RPC.
|
|
3469
3606
|
*/
|
|
3470
|
-
|
|
3607
|
+
onRequest?: PermissionHandler;
|
|
3471
3608
|
/**
|
|
3472
|
-
*
|
|
3473
|
-
*
|
|
3609
|
+
* Sandbox configuration applied before MCP servers or session tools start.
|
|
3610
|
+
* Uses the same direct-host semantics and managed-policy validation as
|
|
3611
|
+
* `session.rpc.options.update({ sandboxConfig })`. A policy conflict fails
|
|
3612
|
+
* create or resume; an identical later update does not restart MCP servers.
|
|
3613
|
+
* Re-supply on cold resume. Requires runtime-version support.
|
|
3474
3614
|
*/
|
|
3475
|
-
|
|
3615
|
+
sandbox?: SandboxConfig;
|
|
3476
3616
|
/**
|
|
3477
|
-
*
|
|
3478
|
-
*
|
|
3617
|
+
* Permission mode applied before the session's first turn: before
|
|
3618
|
+
* `createSession` returns, and before a resume continues pending work.
|
|
3619
|
+
* Uses the same checks as `session.rpc.permissions.setMode`; a mode that
|
|
3620
|
+
* managed policy or session capabilities refuse leaves the current mode in
|
|
3621
|
+
* place. `session.permissionModeResult` reports whether it was applied and
|
|
3622
|
+
* the authoritative mode. Omit to keep the default mode on create, or the
|
|
3623
|
+
* restored mode on resume. Not supported for cloud sessions.
|
|
3479
3624
|
*/
|
|
3480
|
-
|
|
3625
|
+
mode?: PermissionMode;
|
|
3626
|
+
}
|
|
3627
|
+
/** General MCP servers, OAuth, and renderer opt-in; built-in GitHub MCP tuning is under github.mcp. */
|
|
3628
|
+
export interface SessionMcpOptions {
|
|
3481
3629
|
/**
|
|
3482
|
-
*
|
|
3630
|
+
* Optional handler for MCP OAuth requests from MCP servers.
|
|
3631
|
+
* When provided, the SDK can satisfy MCP server OAuth requests with
|
|
3632
|
+
* host-provided token data or cancellation.
|
|
3483
3633
|
*/
|
|
3484
|
-
|
|
3634
|
+
onAuthRequest?: McpAuthHandler;
|
|
3485
3635
|
/**
|
|
3486
|
-
*
|
|
3636
|
+
* Enable MCP Apps (SEP-1865) UI passthrough on this session.
|
|
3637
|
+
*
|
|
3638
|
+
* When `true` **and** the runtime has MCP Apps enabled (via the
|
|
3639
|
+
* `MCP_APPS` feature flag or `COPILOT_MCP_APPS=true` environment
|
|
3640
|
+
* override), the runtime adds the `mcp-apps` capability to the session,
|
|
3641
|
+
* which causes it to advertise the `extensions.io.modelcontextprotocol/ui`
|
|
3642
|
+
* extension to MCP servers (so they expose `_meta.ui.resourceUri` on
|
|
3643
|
+
* tools) and to expose the `session.rpc.mcp.apps.{listTools,callTool,
|
|
3644
|
+
* readResource,setHostContext,getHostContext,diagnose}` JSON-RPC methods.
|
|
3645
|
+
*
|
|
3646
|
+
* If the runtime gate is off, the opt-in is silently dropped server-side
|
|
3647
|
+
* (the runtime logs a warning); the session is created normally but the
|
|
3648
|
+
* MCP Apps surface is unavailable. Inspect the runtime's
|
|
3649
|
+
* `capabilities.ui.mcpApps` on the create/resume response to detect this.
|
|
3650
|
+
*
|
|
3651
|
+
* SDK consumers MUST set this to `true` only when they have an iframe
|
|
3652
|
+
* renderer that can display `ui://` MCP App bundles. Setting it without a
|
|
3653
|
+
* renderer will cause MCP servers to register UI-enabled tool variants
|
|
3654
|
+
* the consumer cannot display.
|
|
3655
|
+
*
|
|
3656
|
+
* @experimental This option is part of an experimental wire-protocol surface
|
|
3657
|
+
* (SEP-1865) and may change or be removed in a future release.
|
|
3658
|
+
*
|
|
3659
|
+
* @default false
|
|
3487
3660
|
*/
|
|
3488
|
-
|
|
3661
|
+
enableApps?: boolean;
|
|
3489
3662
|
/**
|
|
3490
|
-
*
|
|
3663
|
+
* Controls how MCP OAuth tokens are stored for this session.
|
|
3664
|
+
* - `"persistent"` — tokens are stored in the OS keychain (shared across sessions)
|
|
3665
|
+
* - `"in-memory"` — tokens are stored in memory and discarded when the session ends
|
|
3666
|
+
*
|
|
3667
|
+
* @default "in-memory"
|
|
3491
3668
|
*/
|
|
3492
|
-
|
|
3669
|
+
oauthTokenStorage?: "persistent" | "in-memory";
|
|
3493
3670
|
/**
|
|
3494
|
-
*
|
|
3495
|
-
*
|
|
3671
|
+
* OAuth Client ID Metadata Document URL identifying the host for MCP authorization.
|
|
3672
|
+
* When unset, no host identity is supplied.
|
|
3496
3673
|
*/
|
|
3497
|
-
|
|
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 {
|
|
3674
|
+
authClientIdMetadataUrl?: string;
|
|
3506
3675
|
/**
|
|
3507
|
-
*
|
|
3676
|
+
* MCP server configurations for the session.
|
|
3677
|
+
* Keys are server names, values are server configurations.
|
|
3508
3678
|
*/
|
|
3509
|
-
|
|
3679
|
+
servers?: Record<string, MCPServerConfig>;
|
|
3510
3680
|
/**
|
|
3511
|
-
*
|
|
3512
|
-
*
|
|
3513
|
-
*
|
|
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.
|
|
3681
|
+
* Exact MCP server names to disable for this session. Disabled servers are not
|
|
3682
|
+
* started or authenticated when creating or cold-resuming a session. Supplying
|
|
3683
|
+
* this on a resident resume cannot stop servers that are already running.
|
|
3517
3684
|
*/
|
|
3518
|
-
|
|
3685
|
+
disabledServers?: readonly string[];
|
|
3686
|
+
}
|
|
3687
|
+
/** Callback hooks and file-hook sources remain distinct; repository enablement does not gate explicit roots. */
|
|
3688
|
+
export interface SessionHookOptions {
|
|
3519
3689
|
/**
|
|
3520
|
-
*
|
|
3690
|
+
* Hook handlers for intercepting session lifecycle events.
|
|
3691
|
+
* When provided, enables hooks callback allowing custom logic at various points.
|
|
3521
3692
|
*/
|
|
3522
|
-
|
|
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>;
|
|
3693
|
+
handlers?: SessionHooks;
|
|
3551
3694
|
/**
|
|
3552
|
-
*
|
|
3553
|
-
*
|
|
3554
|
-
* -
|
|
3695
|
+
* Explicit discovery-only file-hook roots, separate from callback `hooks`.
|
|
3696
|
+
* No general filesystem access is granted. Available without `enableConfigDiscovery`
|
|
3697
|
+
* or `hooks.enableRepositoryHooks` (which controls repository-origin hooks only);
|
|
3698
|
+
* hook and managed disables still apply.
|
|
3699
|
+
* Relative paths resolve once when supplied against the request's effective
|
|
3700
|
+
* `workingDirectory`, and retained roots do not move when it changes.
|
|
3701
|
+
* Null and omission are equivalent; `[]` clears only the explicit SDK contribution.
|
|
3555
3702
|
*/
|
|
3556
|
-
|
|
3703
|
+
directories?: readonly string[];
|
|
3557
3704
|
/**
|
|
3558
|
-
*
|
|
3559
|
-
*
|
|
3705
|
+
* When true, enables repository-origin file hooks from `.github/hooks/` and
|
|
3706
|
+
* trusted repository-configured roots. Does not control explicit `hooks.directories`
|
|
3707
|
+
* or the `hooks` callback parameter.
|
|
3560
3708
|
*/
|
|
3561
|
-
|
|
3709
|
+
enableRepositoryHooks?: boolean;
|
|
3710
|
+
}
|
|
3711
|
+
/** Event delivery and streaming. Register onEvent before issuing create/resume. */
|
|
3712
|
+
export interface SessionEventOptions {
|
|
3562
3713
|
/**
|
|
3563
|
-
*
|
|
3714
|
+
* Enable streaming of assistant message and reasoning chunks.
|
|
3715
|
+
* When true, ephemeral assistant.message_delta and assistant.reasoning_delta
|
|
3716
|
+
* events are sent as the response is generated. Clients should accumulate
|
|
3717
|
+
* deltaContent values to build the full response.
|
|
3718
|
+
* @default false
|
|
3564
3719
|
*/
|
|
3565
|
-
|
|
3720
|
+
streaming?: boolean;
|
|
3566
3721
|
/**
|
|
3567
|
-
*
|
|
3722
|
+
* Include sub-agent streaming events in the event stream. When true, streaming
|
|
3723
|
+
* delta events from sub-agents (e.g., `assistant.message_delta`,
|
|
3724
|
+
* `assistant.reasoning_delta`, `assistant.streaming_delta` with `agentId` set)
|
|
3725
|
+
* are forwarded to this connection. When false, only non-streaming sub-agent
|
|
3726
|
+
* events and `subagent.*` lifecycle events are forwarded; streaming deltas from
|
|
3727
|
+
* sub-agents are suppressed.
|
|
3728
|
+
* @default true
|
|
3568
3729
|
*/
|
|
3569
|
-
|
|
3730
|
+
includeSubAgentStreamingEvents?: boolean;
|
|
3570
3731
|
/**
|
|
3571
|
-
*
|
|
3572
|
-
*
|
|
3573
|
-
*
|
|
3574
|
-
*
|
|
3575
|
-
*
|
|
3576
|
-
*
|
|
3577
|
-
*
|
|
3732
|
+
* Optional event handler that is registered on the session before the
|
|
3733
|
+
* session.create RPC is issued. This guarantees that early events emitted
|
|
3734
|
+
* by the CLI during session creation (e.g. session.start) are delivered to
|
|
3735
|
+
* the handler.
|
|
3736
|
+
*
|
|
3737
|
+
* Equivalent to calling `session.on(handler)` immediately after creation,
|
|
3738
|
+
* but executes earlier in the lifecycle so no events are missed.
|
|
3578
3739
|
*/
|
|
3579
|
-
|
|
3740
|
+
onEvent?: SessionEventHandler;
|
|
3741
|
+
}
|
|
3742
|
+
/** Explicit plugin directories for this session; plugin assets are not limited to extensions. */
|
|
3743
|
+
export interface SessionPluginOptions {
|
|
3580
3744
|
/**
|
|
3581
|
-
*
|
|
3582
|
-
*
|
|
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.
|
|
3745
|
+
* Local filesystem paths to Open Plugins-format directories
|
|
3746
|
+
* (https://open-plugins.com/) to load for this session.
|
|
3586
3747
|
*
|
|
3587
|
-
*
|
|
3588
|
-
*
|
|
3589
|
-
*
|
|
3590
|
-
*
|
|
3591
|
-
*
|
|
3592
|
-
*
|
|
3593
|
-
*
|
|
3748
|
+
* Relative paths resolve against `workingDirectory` (or the runtime cwd if
|
|
3749
|
+
* unset); absolute paths are recommended. Invalid entries are logged and
|
|
3750
|
+
* skipped.
|
|
3751
|
+
*
|
|
3752
|
+
* Treated as an explicit opt-in: plugin agents and rules load even when
|
|
3753
|
+
* {@link SessionOptionsBase.enableConfigDiscovery} is false. Loaded assets
|
|
3754
|
+
* slot between project (cwd) sources and personal/home sources in the
|
|
3755
|
+
* session-wide precedence order.
|
|
3594
3756
|
*/
|
|
3595
|
-
|
|
3757
|
+
directories?: readonly string[];
|
|
3596
3758
|
}
|
|
3597
|
-
/**
|
|
3598
|
-
|
|
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 {
|
|
3759
|
+
/** Context retention, retrieval, and session-state storage. Group membership does not imply persistence. */
|
|
3760
|
+
export interface SessionStateOptions {
|
|
3632
3761
|
/**
|
|
3633
|
-
*
|
|
3762
|
+
* Infinite session configuration for persistent workspaces and automatic compaction.
|
|
3763
|
+
* When enabled (default), sessions automatically manage context limits and persist state.
|
|
3764
|
+
* Set to `{ enabled: false }` to disable.
|
|
3634
3765
|
*/
|
|
3635
|
-
|
|
3766
|
+
infiniteSessions?: InfiniteSessionConfig;
|
|
3636
3767
|
/**
|
|
3637
|
-
*
|
|
3638
|
-
* session-scoped files (events, workspace, checkpoints, etc.).
|
|
3768
|
+
* Memory configuration for the session. When omitted, the runtime default applies.
|
|
3639
3769
|
*/
|
|
3640
|
-
|
|
3770
|
+
memory?: MemoryConfiguration;
|
|
3641
3771
|
/**
|
|
3642
|
-
*
|
|
3772
|
+
* When true, skips embedding-based retrieval for this session.
|
|
3773
|
+
* Use in multitenant deployments to prevent cross-session information leakage
|
|
3774
|
+
* through the shared embedding cache.
|
|
3643
3775
|
*/
|
|
3644
|
-
|
|
3776
|
+
skipEmbeddingRetrieval?: boolean;
|
|
3645
3777
|
/**
|
|
3646
|
-
*
|
|
3647
|
-
*
|
|
3778
|
+
* Controls how the embedding cache is stored for this session.
|
|
3779
|
+
* - `"persistent"`: Embeddings are cached on disk and shared across sessions/restarts.
|
|
3780
|
+
* - `"in-memory"`: Embeddings are cached in memory only and discarded when the session ends.
|
|
3648
3781
|
*/
|
|
3649
|
-
|
|
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;
|
|
3782
|
+
embeddingCacheStorage?: "persistent" | "in-memory";
|
|
3691
3783
|
/**
|
|
3692
|
-
*
|
|
3693
|
-
*
|
|
3784
|
+
* When true, enables the cross-session store for search and retrieval
|
|
3785
|
+
* across sessions. When false, session content is not written to or
|
|
3786
|
+
* read from the shared session store.
|
|
3694
3787
|
*/
|
|
3695
|
-
|
|
3788
|
+
enableCrossSessionStore?: boolean;
|
|
3696
3789
|
/**
|
|
3697
|
-
*
|
|
3698
|
-
*
|
|
3699
|
-
* change this. Omitted when unknown, such as for sessions persisted before this field
|
|
3700
|
-
* existed.
|
|
3790
|
+
* Supplies a handler for session filesystem operations. This takes effect
|
|
3791
|
+
* only if {@link CopilotClientOptions.sessionFs} is configured.
|
|
3701
3792
|
*/
|
|
3702
|
-
|
|
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;
|
|
3793
|
+
createSessionFsProvider?: (session: CopilotSession) => SessionFsProvider;
|
|
3830
3794
|
}
|
|
3831
|
-
/**
|
|
3832
|
-
export interface
|
|
3833
|
-
|
|
3834
|
-
|
|
3795
|
+
/** Create-only directory trust alongside shared filesystem options. */
|
|
3796
|
+
export interface CreateSessionFilesystemOptions extends SessionFilesystemOptions {
|
|
3797
|
+
/**
|
|
3798
|
+
* Grants trust to the canonical working directory during session creation.
|
|
3799
|
+
* "session" applies only to this session; "user" persists the grant for later
|
|
3800
|
+
* sessions. Omit to leave directory trust unchanged. Not available on resume.
|
|
3801
|
+
*/
|
|
3802
|
+
trustWorkingDirectory?: WorkingDirectoryTrust;
|
|
3835
3803
|
}
|
|
3836
|
-
/**
|
|
3837
|
-
export interface
|
|
3838
|
-
|
|
3839
|
-
|
|
3804
|
+
/** Create-only instruction-cache refresh. */
|
|
3805
|
+
export interface CreateSessionInstructionOptions extends SessionInstructionOptions {
|
|
3806
|
+
/**
|
|
3807
|
+
* Invalidates the process-wide custom-instruction discovery cache before
|
|
3808
|
+
* creating this session. Use when instruction files changed in the same runtime.
|
|
3809
|
+
* Other sessions in this runtime may observe updated instructions on later turns
|
|
3810
|
+
* or discovery. This does not watch files or enable disabled instruction loading.
|
|
3811
|
+
* @default false
|
|
3812
|
+
*/
|
|
3813
|
+
refreshCustomInstructions?: boolean;
|
|
3840
3814
|
}
|
|
3841
|
-
/**
|
|
3842
|
-
|
|
3843
|
-
|
|
3844
|
-
|
|
3845
|
-
|
|
3846
|
-
|
|
3847
|
-
|
|
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;
|
|
3815
|
+
/** Rehydration of previously open canvases. */
|
|
3816
|
+
export interface ResumeSessionCanvasOptions extends SessionCanvasOptions {
|
|
3817
|
+
/**
|
|
3818
|
+
* Snapshot of canvases that were already open when the session was suspended.
|
|
3819
|
+
* When provided on resume, the runtime can rehydrate canvas state so consumers
|
|
3820
|
+
* do not need to re-open canvases that were active before the previous shutdown.
|
|
3821
|
+
*/
|
|
3822
|
+
open?: readonly OpenCanvasInstance[];
|
|
3864
3823
|
}
|