@microsoft/copilot-sdk 0.0.0-stage → 2.0.0-preview.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2531 -2
- package/dist/canvas.d.ts +135 -0
- package/dist/canvas.js +51 -0
- package/dist/cjs/canvas.js +77 -0
- package/dist/cjs/cliVersion.js +31 -0
- package/dist/cjs/client.js +3941 -0
- package/dist/cjs/copilotRequestHandler.js +815 -0
- package/dist/cjs/decisions.js +139 -0
- package/dist/cjs/entra.js +83 -0
- package/dist/cjs/extension.js +79 -0
- package/dist/cjs/ffiRuntimeHost.js +400 -0
- package/dist/cjs/generated/lifecycle-diagnostics.js +16 -0
- package/dist/cjs/generated/rpc.js +5883 -0
- package/dist/cjs/generated/session-events.js +16 -0
- package/dist/cjs/host.js +83 -0
- package/dist/cjs/index.js +100 -0
- package/dist/cjs/installationConfirmation.js +98 -0
- package/dist/cjs/jsonrpcTypes.js +41 -0
- package/dist/cjs/localModelJson.js +103 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/providerConfiguration.js +39 -0
- package/dist/cjs/rpcCancellation.js +49 -0
- package/dist/cjs/runtimeArtifacts.js +255 -0
- package/dist/cjs/schema.js +40 -0
- package/dist/cjs/sdkProtocolVersion.js +33 -0
- package/dist/cjs/session.js +2764 -0
- package/dist/cjs/sessionFsProvider.js +283 -0
- package/dist/cjs/taskAnalyticsJson.js +47 -0
- package/dist/cjs/telemetry.js +35 -0
- package/dist/cjs/toolSet.js +107 -0
- package/dist/cjs/types.js +204 -0
- package/dist/cjs/workflow.js +278 -0
- package/dist/cliVersion.d.ts +2 -0
- package/dist/cliVersion.js +6 -0
- package/dist/client.d.ts +576 -0
- package/dist/client.js +3924 -0
- package/dist/copilotRequestHandler.d.ts +91 -0
- package/dist/copilotRequestHandler.js +787 -0
- package/dist/decisions.d.ts +65 -0
- package/dist/decisions.js +113 -0
- package/dist/entra.d.ts +3 -0
- package/dist/entra.js +59 -0
- package/dist/extension.d.ts +69 -0
- package/dist/extension.js +59 -0
- package/dist/ffiRuntimeHost.d.ts +44 -0
- package/dist/ffiRuntimeHost.js +366 -0
- package/dist/generated/lifecycle-diagnostics.d.ts +232 -0
- package/dist/generated/lifecycle-diagnostics.js +0 -0
- package/dist/generated/rpc.d.ts +47706 -0
- package/dist/generated/rpc.js +5854 -0
- package/dist/generated/session-events.d.ts +17349 -0
- package/dist/generated/session-events.js +0 -0
- package/dist/host.d.ts +143 -0
- package/dist/host.js +59 -0
- package/dist/index.d.ts +23 -0
- package/dist/index.js +74 -0
- package/dist/installationConfirmation.d.ts +19 -0
- package/dist/installationConfirmation.js +74 -0
- package/dist/jsonrpcTypes.d.ts +16 -0
- package/dist/jsonrpcTypes.js +17 -0
- package/dist/localModelJson.d.ts +1 -0
- package/dist/localModelJson.js +69 -0
- package/dist/providerConfiguration.d.ts +3 -0
- package/dist/providerConfiguration.js +15 -0
- package/dist/rpcCancellation.d.ts +3 -0
- package/dist/rpcCancellation.js +25 -0
- package/dist/runtimeArtifacts.d.ts +18 -0
- package/dist/runtimeArtifacts.js +233 -0
- package/dist/schema.d.ts +4 -0
- package/dist/schema.js +14 -0
- package/dist/sdkProtocolVersion.d.ts +10 -0
- package/dist/sdkProtocolVersion.js +8 -0
- package/dist/session.d.ts +524 -0
- package/dist/session.js +2751 -0
- package/dist/sessionFsProvider.d.ts +130 -0
- package/dist/sessionFsProvider.js +257 -0
- package/dist/taskAnalyticsJson.d.ts +8 -0
- package/dist/taskAnalyticsJson.js +12 -0
- package/dist/telemetry.d.ts +14 -0
- package/dist/telemetry.js +11 -0
- package/dist/toolSet.d.ts +75 -0
- package/dist/toolSet.js +82 -0
- package/dist/types.d.ts +3864 -0
- package/dist/types.js +169 -0
- package/dist/workflow.d.ts +413 -0
- package/dist/workflow.js +248 -0
- package/docs/agent-author.md +372 -0
- package/docs/examples.md +747 -0
- package/docs/extensions.md +121 -0
- package/docs/workflows.md +303 -0
- package/package.json +135 -5
|
@@ -0,0 +1,524 @@
|
|
|
1
|
+
import { createSessionRpc } from "./generated/rpc.js";
|
|
2
|
+
import type { ModelSwitchAutoTierResult, PermissionsSetModeResult, SessionManagementPolicy } from "./generated/rpc.js";
|
|
3
|
+
import type { OpenCanvasInstance } from "./generated/rpc.js";
|
|
4
|
+
import type { TrajectoryJsonValue } from "./generated/rpc.js";
|
|
5
|
+
import type { MessageOptions, ResponseSchema, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, FusionTier, ModelCapabilitiesOverride, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, SessionCreationHandler, TranscriptRecovery, TypedSessionEventHandler } from "./types.js";
|
|
6
|
+
import { type SessionWorkflowApi } from "./workflow.js";
|
|
7
|
+
/** Assistant message event - the final response from the assistant. */
|
|
8
|
+
export type AssistantMessageEvent = Extract<SessionEvent, {
|
|
9
|
+
type: "assistant.message";
|
|
10
|
+
}>;
|
|
11
|
+
/**
|
|
12
|
+
* Represents a single conversation session with the Copilot CLI.
|
|
13
|
+
*
|
|
14
|
+
* A session maintains conversation state, handles events, and manages tool execution.
|
|
15
|
+
* Sessions are created via {@link CopilotClient.createSession} or resumed via
|
|
16
|
+
* {@link CopilotClient.resumeSession}.
|
|
17
|
+
*
|
|
18
|
+
* @example
|
|
19
|
+
* ```typescript
|
|
20
|
+
* const session = await client.createSession({ model: "gpt-5.4" });
|
|
21
|
+
*
|
|
22
|
+
* // Subscribe to events
|
|
23
|
+
* session.on((event) => {
|
|
24
|
+
* if (event.type === "assistant.message") {
|
|
25
|
+
* console.log(event.data.content);
|
|
26
|
+
* }
|
|
27
|
+
* });
|
|
28
|
+
*
|
|
29
|
+
* // Send a message and wait for completion
|
|
30
|
+
* await session.sendAndWait({ prompt: "Hello, world!" });
|
|
31
|
+
*
|
|
32
|
+
* // Clean up
|
|
33
|
+
* await session.disconnect();
|
|
34
|
+
* ```
|
|
35
|
+
*/
|
|
36
|
+
/**
|
|
37
|
+
* Fixed name of the runtime's built-in tool-search tool. A client can replace
|
|
38
|
+
* its behavior by registering a {@link Tool} with this exact name and
|
|
39
|
+
* `overridesBuiltInTool: true`.
|
|
40
|
+
*/
|
|
41
|
+
export declare class CopilotSession {
|
|
42
|
+
private _sessionId;
|
|
43
|
+
private connection;
|
|
44
|
+
private _workspacePath?;
|
|
45
|
+
private _transcriptRecovery?;
|
|
46
|
+
private _permissionModeResult?;
|
|
47
|
+
private eventHandlers;
|
|
48
|
+
private typedEventHandlers;
|
|
49
|
+
private toolHandlers;
|
|
50
|
+
/** Settles once every earlier `setTools` call has finished. */
|
|
51
|
+
private setToolsQueue;
|
|
52
|
+
private pendingExternalTools;
|
|
53
|
+
private pendingSessionCreations;
|
|
54
|
+
private canvases;
|
|
55
|
+
private bearerTokenProviders;
|
|
56
|
+
private commandHandlers;
|
|
57
|
+
private workflows;
|
|
58
|
+
private workflowAbortControllers;
|
|
59
|
+
private permissionHandler?;
|
|
60
|
+
private mcpAuthHandler?;
|
|
61
|
+
private userInputHandler?;
|
|
62
|
+
private shellAuthenticationHandler?;
|
|
63
|
+
private pendingShellAuthenticationRequests;
|
|
64
|
+
private elicitationHandler?;
|
|
65
|
+
private exitPlanModeHandler?;
|
|
66
|
+
private autoModeSwitchHandler?;
|
|
67
|
+
private skillProvider?;
|
|
68
|
+
private sessionCreationHandler?;
|
|
69
|
+
private memoryStoreHandler?;
|
|
70
|
+
private hooks?;
|
|
71
|
+
private transformCallbacks?;
|
|
72
|
+
private _rpc;
|
|
73
|
+
private _internalRpc;
|
|
74
|
+
private traceContextProvider?;
|
|
75
|
+
private readonly managedSettingsEnabled;
|
|
76
|
+
private _capabilities;
|
|
77
|
+
private openCanvasInstances;
|
|
78
|
+
private disconnected;
|
|
79
|
+
private readonly pendingResponseWaits;
|
|
80
|
+
private readonly pendingStructuredWaits;
|
|
81
|
+
private completionRpcUnsupported;
|
|
82
|
+
private disconnecting;
|
|
83
|
+
private onDisconnected?;
|
|
84
|
+
private releaseFromClient?;
|
|
85
|
+
/**
|
|
86
|
+
* Friendly workflow API for running registered workflows by name or handle.
|
|
87
|
+
*
|
|
88
|
+
* @experimental Part of the experimental Dynamic Workflows surface and may
|
|
89
|
+
* change or be removed in future SDK or CLI releases.
|
|
90
|
+
*/
|
|
91
|
+
readonly workflow: SessionWorkflowApi;
|
|
92
|
+
private settleWorkflowRun;
|
|
93
|
+
/**
|
|
94
|
+
* Resolve when a workflow run reaches a terminal status.
|
|
95
|
+
*
|
|
96
|
+
* The subscription is installed *before* the first read so a transition
|
|
97
|
+
* landing between the two cannot be missed, and re-reads are serialized so
|
|
98
|
+
* overlapping invalidation events cannot interleave — the run's revision
|
|
99
|
+
* advances once per operation, so a burst of events is common and must
|
|
100
|
+
* collapse into a single in-flight read. A bounded periodic re-read keeps a
|
|
101
|
+
* dropped invalidation from leaving the wait pending forever.
|
|
102
|
+
*/
|
|
103
|
+
private waitForWorkflowRun;
|
|
104
|
+
get sessionId(): string;
|
|
105
|
+
/**
|
|
106
|
+
* Typed session-scoped RPC methods.
|
|
107
|
+
*/
|
|
108
|
+
get rpc(): ReturnType<typeof createSessionRpc>;
|
|
109
|
+
/**
|
|
110
|
+
* Path to the session workspace directory when infinite sessions are enabled.
|
|
111
|
+
* Contains checkpoints/, plan.md, and files/ subdirectories.
|
|
112
|
+
* Undefined if infinite sessions are disabled.
|
|
113
|
+
*/
|
|
114
|
+
get workspacePath(): string | undefined;
|
|
115
|
+
/** Recovery observed while loading this session; undefined on a clean resume. */
|
|
116
|
+
get transcriptRecovery(): TranscriptRecovery | undefined;
|
|
117
|
+
/**
|
|
118
|
+
* Outcome of the `permissionMode` requested when this session was created
|
|
119
|
+
* or resumed: whether it was applied, and the authoritative mode the
|
|
120
|
+
* session started in. Undefined when no mode was requested.
|
|
121
|
+
*/
|
|
122
|
+
get permissionModeResult(): PermissionsSetModeResult | undefined;
|
|
123
|
+
/**
|
|
124
|
+
* Host capabilities reported when the session was created or resumed.
|
|
125
|
+
* Use this to check feature support before calling capability-gated APIs.
|
|
126
|
+
*/
|
|
127
|
+
get capabilities(): SessionCapabilities;
|
|
128
|
+
/**
|
|
129
|
+
* Interactive UI methods for showing dialogs to the user.
|
|
130
|
+
* Only available when the CLI host supports elicitation
|
|
131
|
+
* (`session.capabilities.ui?.elicitation === true`).
|
|
132
|
+
*
|
|
133
|
+
* @example
|
|
134
|
+
* ```typescript
|
|
135
|
+
* if (session.capabilities.ui?.elicitation) {
|
|
136
|
+
* const ok = await session.ui.confirm("Deploy to production?");
|
|
137
|
+
* }
|
|
138
|
+
* ```
|
|
139
|
+
*/
|
|
140
|
+
get ui(): SessionUiApi;
|
|
141
|
+
/**
|
|
142
|
+
* Sends a message to this session and returns once it is admitted.
|
|
143
|
+
*
|
|
144
|
+
* The message is processed asynchronously. Subscribe to events via {@link on}
|
|
145
|
+
* to receive streaming responses and other session events.
|
|
146
|
+
*
|
|
147
|
+
* @param options - The message options including the prompt and optional attachments
|
|
148
|
+
* @returns The submitted user message's ID, not an assistant response ID.
|
|
149
|
+
* When this send starts a run, root assistant messages carry it as originatingMessageId.
|
|
150
|
+
* @throws Error if the session has been disconnected or the connection fails
|
|
151
|
+
*
|
|
152
|
+
* @example
|
|
153
|
+
* ```typescript
|
|
154
|
+
* const messageId = await session.send({
|
|
155
|
+
* prompt: "Explain this code",
|
|
156
|
+
* attachments: [{ type: "file", path: "./src/index.ts" }]
|
|
157
|
+
* });
|
|
158
|
+
* ```
|
|
159
|
+
*/
|
|
160
|
+
send(prompt: string): Promise<string>;
|
|
161
|
+
send(options: MessageOptions): Promise<string>;
|
|
162
|
+
private sendMessage;
|
|
163
|
+
private createSendParams;
|
|
164
|
+
/**
|
|
165
|
+
* Sends a message and waits for its response to complete.
|
|
166
|
+
*
|
|
167
|
+
* Supported local runtimes correlate completion and the response with this
|
|
168
|
+
* message. Unsupported runtimes retain the legacy non-Autopilot `session.idle`
|
|
169
|
+
* or request-correlated `session.autopilot_stopped` wait. Autopilot completion
|
|
170
|
+
* does not wait for or stop attached shells.
|
|
171
|
+
*
|
|
172
|
+
* Events are still delivered to handlers registered via {@link on} while waiting.
|
|
173
|
+
* Sub-agent events with a non-empty `agentId` do not complete the wait or supply its reply.
|
|
174
|
+
* With a schema as the second argument, returns its parsed, validated result.
|
|
175
|
+
* Provider schema restrictions apply to that schema; see {@link MessageOptions.responseSchema}.
|
|
176
|
+
* Structured waits select only root-agent output originating from this send;
|
|
177
|
+
* other queued work may delay session.idle but cannot replace the result.
|
|
178
|
+
*
|
|
179
|
+
* @param options - The message options including the prompt and optional attachments
|
|
180
|
+
* @param timeout - Timeout in milliseconds (default: 60000). Controls how long to wait; does not abort in-flight agent work.
|
|
181
|
+
* @returns A promise that resolves with this message's final assistant response,
|
|
182
|
+
* or undefined if no assistant message was received
|
|
183
|
+
* @throws Error if the run is aborted before completion
|
|
184
|
+
* @throws Error if the timeout is reached before completion
|
|
185
|
+
* @throws Error if the session has been disconnected or the connection fails
|
|
186
|
+
*
|
|
187
|
+
* @example
|
|
188
|
+
* ```typescript
|
|
189
|
+
* // Send and wait for completion with default 60s timeout
|
|
190
|
+
* const response = await session.sendAndWait({ prompt: "What is 2+2?" });
|
|
191
|
+
* console.log(response?.data.content); // "4"
|
|
192
|
+
* ```
|
|
193
|
+
*/
|
|
194
|
+
sendAndWait(prompt: string, timeout?: number): Promise<AssistantMessageEvent | undefined>;
|
|
195
|
+
sendAndWait<TResult>(options: MessageOptions | string, responseSchema: ResponseSchema<TResult>, timeout?: number): Promise<TResult>;
|
|
196
|
+
sendAndWait(options: MessageOptions, timeout?: number): Promise<AssistantMessageEvent | undefined>;
|
|
197
|
+
private sendWithCompletion;
|
|
198
|
+
private sendAndWaitForStructuredMessage;
|
|
199
|
+
private assertConnected;
|
|
200
|
+
/**
|
|
201
|
+
* Subscribes to events from this session.
|
|
202
|
+
*
|
|
203
|
+
* Events include assistant messages, tool executions, errors, and session state changes.
|
|
204
|
+
* Multiple handlers can be registered and will all receive events.
|
|
205
|
+
*
|
|
206
|
+
* @param eventType - The specific event type to listen for (e.g., "assistant.message", "session.idle")
|
|
207
|
+
* @param handler - A callback function that receives events of the specified type
|
|
208
|
+
* @returns A function that, when called, unsubscribes the handler
|
|
209
|
+
*
|
|
210
|
+
* @example
|
|
211
|
+
* ```typescript
|
|
212
|
+
* // Listen for a specific event type
|
|
213
|
+
* const unsubscribe = session.on("assistant.message", (event) => {
|
|
214
|
+
* console.log("Assistant:", event.data.content);
|
|
215
|
+
* });
|
|
216
|
+
*
|
|
217
|
+
* // Later, to stop receiving events:
|
|
218
|
+
* unsubscribe();
|
|
219
|
+
* ```
|
|
220
|
+
*/
|
|
221
|
+
on<K extends SessionEventType>(eventType: K, handler: TypedSessionEventHandler<K>): () => void;
|
|
222
|
+
/**
|
|
223
|
+
* Subscribes to all events from this session.
|
|
224
|
+
*
|
|
225
|
+
* @param handler - A callback function that receives all session events
|
|
226
|
+
* @returns A function that, when called, unsubscribes the handler
|
|
227
|
+
*
|
|
228
|
+
* @example
|
|
229
|
+
* ```typescript
|
|
230
|
+
* const unsubscribe = session.on((event) => {
|
|
231
|
+
* switch (event.type) {
|
|
232
|
+
* case "assistant.message":
|
|
233
|
+
* console.log("Assistant:", event.data.content);
|
|
234
|
+
* break;
|
|
235
|
+
* case "session.error":
|
|
236
|
+
* console.error("Error:", event.data.message);
|
|
237
|
+
* break;
|
|
238
|
+
* }
|
|
239
|
+
* });
|
|
240
|
+
*
|
|
241
|
+
* // Later, to stop receiving events:
|
|
242
|
+
* unsubscribe();
|
|
243
|
+
* ```
|
|
244
|
+
*/
|
|
245
|
+
on(handler: SessionEventHandler): () => void;
|
|
246
|
+
private upsertOpenCanvasFromEvent;
|
|
247
|
+
private removeOpenCanvasFromEvent;
|
|
248
|
+
private removeOpenCanvas;
|
|
249
|
+
private upsertOpenCanvas;
|
|
250
|
+
private _claimExternalTool;
|
|
251
|
+
/**
|
|
252
|
+
* Snapshot of canvas instances currently known to be open for this session.
|
|
253
|
+
* Populated from the `session.resume` response and live `session.canvas.opened`
|
|
254
|
+
* and `session.canvas.closed` events. Returns a defensive copy — mutating the
|
|
255
|
+
* returned array has no effect on the session.
|
|
256
|
+
*/
|
|
257
|
+
get openCanvases(): OpenCanvasInstance[];
|
|
258
|
+
private assertElicitation;
|
|
259
|
+
private _elicitation;
|
|
260
|
+
private _confirm;
|
|
261
|
+
private _select;
|
|
262
|
+
private _input;
|
|
263
|
+
/**
|
|
264
|
+
* Registers the host's creation callback without enabling the tool group.
|
|
265
|
+
* Enable it separately with `session.rpc.management.configure({ enabled: true })`.
|
|
266
|
+
*/
|
|
267
|
+
setSessionCreationHandler(handler?: SessionCreationHandler): Promise<SessionManagementPolicy>;
|
|
268
|
+
private requireSkillProvider;
|
|
269
|
+
/**
|
|
270
|
+
* Runs a provider call with an abort signal tied to the runtime's request
|
|
271
|
+
* cancellation. Failures are logged locally and reported generically.
|
|
272
|
+
*/
|
|
273
|
+
private callSkillProvider;
|
|
274
|
+
/**
|
|
275
|
+
* Retrieves all events and messages from this session's history.
|
|
276
|
+
*
|
|
277
|
+
* This returns the complete conversation history including user messages,
|
|
278
|
+
* assistant responses, tool executions, and other session events.
|
|
279
|
+
* Use getRawEvents for archives containing integers outside JavaScript's safe range.
|
|
280
|
+
*
|
|
281
|
+
* @returns A promise that resolves with an array of all session events
|
|
282
|
+
* @throws Error if the session has been disconnected or the connection fails
|
|
283
|
+
*
|
|
284
|
+
* @example
|
|
285
|
+
* ```typescript
|
|
286
|
+
* const events = await session.getEvents();
|
|
287
|
+
* for (const event of events) {
|
|
288
|
+
* if (event.type === "assistant.message") {
|
|
289
|
+
* console.log("Assistant:", event.data.content);
|
|
290
|
+
* }
|
|
291
|
+
* }
|
|
292
|
+
* ```
|
|
293
|
+
*/
|
|
294
|
+
getEvents(): Promise<SessionEvent[]>;
|
|
295
|
+
/**
|
|
296
|
+
* Retrieves history with unsafe integers preserved as bigint values.
|
|
297
|
+
* Timestamp strings, explicit nulls, and unknown fields are retained.
|
|
298
|
+
* Pass the result directly to taskAnalytics.classifyTrajectory; JSON.stringify
|
|
299
|
+
* does not support bigint, but that RPC's encoder does.
|
|
300
|
+
*/
|
|
301
|
+
getRawEvents(): Promise<TrajectoryJsonValue[]>;
|
|
302
|
+
/**
|
|
303
|
+
* Disconnects this session and releases all in-memory resources (event handlers,
|
|
304
|
+
* tool handlers, permission handlers).
|
|
305
|
+
*
|
|
306
|
+
* Session state on disk (conversation history, planning state, artifacts) is
|
|
307
|
+
* preserved, so the conversation can be resumed later by calling
|
|
308
|
+
* {@link CopilotClient.resumeSession} with the session ID. To permanently
|
|
309
|
+
* remove all session data including files on disk, use
|
|
310
|
+
* {@link CopilotClient.deleteSession} instead.
|
|
311
|
+
*
|
|
312
|
+
* After calling this method, the session object can no longer be used.
|
|
313
|
+
*
|
|
314
|
+
* @returns A promise that resolves when the session is disconnected
|
|
315
|
+
* @throws Error if the connection fails
|
|
316
|
+
*
|
|
317
|
+
* @example
|
|
318
|
+
* ```typescript
|
|
319
|
+
* // Clean up when done — session can still be resumed later
|
|
320
|
+
* await session.disconnect();
|
|
321
|
+
* ```
|
|
322
|
+
*/
|
|
323
|
+
disconnect(): Promise<void>;
|
|
324
|
+
/** Enables `await using session = ...` syntax for automatic cleanup. */
|
|
325
|
+
[Symbol.asyncDispose](): Promise<void>;
|
|
326
|
+
/**
|
|
327
|
+
* Aborts the currently processing message in this session.
|
|
328
|
+
*
|
|
329
|
+
* Use this to cancel a long-running request. The session remains valid
|
|
330
|
+
* and can continue to be used for new messages.
|
|
331
|
+
*
|
|
332
|
+
* @returns A promise that resolves when the abort request is acknowledged
|
|
333
|
+
* @throws Error if the session has been disconnected or the connection fails
|
|
334
|
+
*
|
|
335
|
+
* @example
|
|
336
|
+
* ```typescript
|
|
337
|
+
* // Start a long-running request
|
|
338
|
+
* const messagePromise = session.send({ prompt: "Write a very long story..." });
|
|
339
|
+
*
|
|
340
|
+
* // Abort after 5 seconds
|
|
341
|
+
* setTimeout(async () => {
|
|
342
|
+
* await session.abort();
|
|
343
|
+
* }, 5000);
|
|
344
|
+
* ```
|
|
345
|
+
*/
|
|
346
|
+
abort(): Promise<void>;
|
|
347
|
+
/**
|
|
348
|
+
* Change the model for this session.
|
|
349
|
+
* The new model takes effect for the next message. Conversation history is preserved.
|
|
350
|
+
*
|
|
351
|
+
* @param model - Model ID to switch to
|
|
352
|
+
* @param options - Optional settings for the new model
|
|
353
|
+
*
|
|
354
|
+
* @example
|
|
355
|
+
* ```typescript
|
|
356
|
+
* await session.setModel("gpt-5.4");
|
|
357
|
+
* await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
|
|
358
|
+
*
|
|
359
|
+
* // Select Copilot Fusion and its tier in one call, like
|
|
360
|
+
* // `copilot --model fusion --fusion-tier high`.
|
|
361
|
+
* await session.setModel("fusion", { fusionTier: "high" });
|
|
362
|
+
* ```
|
|
363
|
+
*/
|
|
364
|
+
setModel(model: string, options?: {
|
|
365
|
+
reasoningEffort?: ReasoningEffort;
|
|
366
|
+
reasoningSummary?: ReasoningSummary;
|
|
367
|
+
contextTier?: ContextTier;
|
|
368
|
+
modelCapabilities?: ModelCapabilitiesOverride;
|
|
369
|
+
/**
|
|
370
|
+
* Routing preference to apply when `model` is `auto`.
|
|
371
|
+
*
|
|
372
|
+
* Pass `null` to return to the provider's default Auto routing. The
|
|
373
|
+
* runtime rejects this option when `model` is anything other than
|
|
374
|
+
* `auto`; use {@link setAutoTier} to change the preference without
|
|
375
|
+
* changing the selected model.
|
|
376
|
+
*
|
|
377
|
+
* For Copilot Fusion, prefer `fusionTier`. The `balance`,
|
|
378
|
+
* `hydrafusion` and `hydrafusion-max` identifiers it replaces
|
|
379
|
+
* remain accepted but are deprecated.
|
|
380
|
+
*
|
|
381
|
+
* @experimental Part of an experimental Auto routing surface and may
|
|
382
|
+
* change or be removed in a future release.
|
|
383
|
+
*/
|
|
384
|
+
autoTier?: AutoTier | null;
|
|
385
|
+
/**
|
|
386
|
+
* Copilot Fusion tier to apply when `model` is `fusion` or `auto`,
|
|
387
|
+
* matching the CLI's `--fusion-tier`.
|
|
388
|
+
*
|
|
389
|
+
* The runtime resolves the tier to the Auto routing preference it
|
|
390
|
+
* stands for and stages it exactly like `autoTier`. Cannot be
|
|
391
|
+
* combined with `autoTier`; use {@link setFusionTier} to change the
|
|
392
|
+
* tier without changing the selected model.
|
|
393
|
+
*
|
|
394
|
+
* @experimental Part of an experimental Auto routing surface and may
|
|
395
|
+
* change or be removed in a future release.
|
|
396
|
+
*/
|
|
397
|
+
fusionTier?: FusionTier;
|
|
398
|
+
}): Promise<void>;
|
|
399
|
+
/**
|
|
400
|
+
* Change the Auto routing preference without changing the selected model.
|
|
401
|
+
*
|
|
402
|
+
* The runtime does not apply the preference immediately. It records the
|
|
403
|
+
* request and commits it only when a later user turn using the `auto` model
|
|
404
|
+
* successfully obtains a usable model from the provider. A `pending` status
|
|
405
|
+
* therefore confirms that the request was accepted, not that it took effect.
|
|
406
|
+
*
|
|
407
|
+
* Watch for the outcome through the `session.model_change` event on success,
|
|
408
|
+
* or the ephemeral `session.auto_tier_switch_failed` event on failure. You
|
|
409
|
+
* can also read the current committed and in-flight state at any time with
|
|
410
|
+
* `session.rpc.model.getCurrent()`.
|
|
411
|
+
*
|
|
412
|
+
* Only the most recent request survives: issuing a new request replaces any
|
|
413
|
+
* earlier one that has not yet been claimed by a turn.
|
|
414
|
+
*
|
|
415
|
+
* For Copilot Fusion, prefer {@link setFusionTier}. The `balance`,
|
|
416
|
+
* `hydrafusion` and `hydrafusion-max` identifiers it replaces remain
|
|
417
|
+
* accepted but are deprecated.
|
|
418
|
+
*
|
|
419
|
+
* @param autoTier - Routing preference to activate, or `null` to return to
|
|
420
|
+
* the provider's default Auto routing
|
|
421
|
+
* @returns The runtime's immediate acknowledgement and Auto preference snapshot
|
|
422
|
+
*
|
|
423
|
+
* @experimental Part of an experimental Auto routing surface and may change
|
|
424
|
+
* or be removed in a future release.
|
|
425
|
+
*
|
|
426
|
+
* @example
|
|
427
|
+
* ```typescript
|
|
428
|
+
* const result = await session.setAutoTier("intelligence");
|
|
429
|
+
* if (result.status === "pending") {
|
|
430
|
+
* // Takes effect on a later turn that uses the `auto` model.
|
|
431
|
+
* }
|
|
432
|
+
* ```
|
|
433
|
+
*/
|
|
434
|
+
setAutoTier(autoTier: AutoTier | null): Promise<ModelSwitchAutoTierResult>;
|
|
435
|
+
/**
|
|
436
|
+
* Change the Copilot Fusion tier without changing the selected model,
|
|
437
|
+
* naming the tier as the CLI's `--fusion-tier` does.
|
|
438
|
+
*
|
|
439
|
+
* The runtime resolves the tier to the Auto routing preference it stands
|
|
440
|
+
* for and then handles the request exactly like {@link setAutoTier}: it
|
|
441
|
+
* takes effect on a later user turn that uses the `fusion` or `auto`
|
|
442
|
+
* model. To return to the provider's default routing, call
|
|
443
|
+
* `setAutoTier(null)`.
|
|
444
|
+
*
|
|
445
|
+
* @param fusionTier - Copilot Fusion tier to activate
|
|
446
|
+
* @returns The runtime's immediate acknowledgement and Auto preference snapshot
|
|
447
|
+
*
|
|
448
|
+
* @experimental Part of an experimental Auto routing surface and may change
|
|
449
|
+
* or be removed in a future release.
|
|
450
|
+
*
|
|
451
|
+
* @example
|
|
452
|
+
* ```typescript
|
|
453
|
+
* const result = await session.setFusionTier("max");
|
|
454
|
+
* if (result.status === "pending") {
|
|
455
|
+
* // Takes effect on a later turn that uses Copilot Fusion.
|
|
456
|
+
* }
|
|
457
|
+
* ```
|
|
458
|
+
*/
|
|
459
|
+
setFusionTier(fusionTier: FusionTier): Promise<ModelSwitchAutoTierResult>;
|
|
460
|
+
/**
|
|
461
|
+
* Replace the tools this client supplies to the session.
|
|
462
|
+
*
|
|
463
|
+
* `tools` becomes the complete set of tools this client implements,
|
|
464
|
+
* replacing the ones it supplied when the session was created or resumed,
|
|
465
|
+
* or in an earlier call. Built-in, MCP, and plugin tools, and tools other
|
|
466
|
+
* connected clients supply, are unaffected. Pass an empty array to remove
|
|
467
|
+
* all of this client's tools.
|
|
468
|
+
*
|
|
469
|
+
* Tools are defined the same way as for `createSession`: calls to tools
|
|
470
|
+
* with a `handler` are dispatched to it, and tools without one are
|
|
471
|
+
* declaration-only. Once the runtime accepts the replacement, every tool
|
|
472
|
+
* call this session dispatches uses the new handlers; calls already
|
|
473
|
+
* running finish on their original handlers. If the runtime rejects the
|
|
474
|
+
* replacement, this rejects and the previous tools and handlers stay in
|
|
475
|
+
* place. Concurrent calls on the same session are applied one at a time,
|
|
476
|
+
* in the order they are made.
|
|
477
|
+
*
|
|
478
|
+
* The agent sees the new tools from its next model request, which can fall
|
|
479
|
+
* within a turn in progress. A model request already in flight was made
|
|
480
|
+
* with the previous tools, so the agent can still call a tool you removed.
|
|
481
|
+
* If no connected client supplies a tool with that name any more, the call
|
|
482
|
+
* fails with an error that tells the agent the tool is no longer available,
|
|
483
|
+
* and the turn continues. If you don't want the agent to see that failure,
|
|
484
|
+
* replace tools while the session is idle.
|
|
485
|
+
*
|
|
486
|
+
* @param tools - The complete set of tools this client supplies
|
|
487
|
+
* @throws Error if the session disconnects before the replacement is applied
|
|
488
|
+
*
|
|
489
|
+
* @experimental Wraps the experimental `session.tools.set` RPC and may change
|
|
490
|
+
* or be removed in a future release.
|
|
491
|
+
*
|
|
492
|
+
* @example
|
|
493
|
+
* ```typescript
|
|
494
|
+
* await session.setTools([
|
|
495
|
+
* defineTool("search_issues", {
|
|
496
|
+
* description: "Search the issues shown on the current page",
|
|
497
|
+
* parameters: z.object({ query: z.string() }),
|
|
498
|
+
* handler: async ({ query }) => searchIssues(query),
|
|
499
|
+
* }),
|
|
500
|
+
* ]);
|
|
501
|
+
* ```
|
|
502
|
+
*/
|
|
503
|
+
setTools(tools: NonNullable<SessionConfig["tools"]>): Promise<void>;
|
|
504
|
+
/**
|
|
505
|
+
* Log a message to the session timeline.
|
|
506
|
+
* The message appears in the session event stream and is visible to SDK consumers
|
|
507
|
+
* and (for non-ephemeral messages) persisted to the session event log on disk.
|
|
508
|
+
*
|
|
509
|
+
* @param message - Human-readable message text
|
|
510
|
+
* @param options - Optional log level and ephemeral flag
|
|
511
|
+
*
|
|
512
|
+
* @example
|
|
513
|
+
* ```typescript
|
|
514
|
+
* await session.log("Processing started");
|
|
515
|
+
* await session.log("Disk usage high", { level: "warning" });
|
|
516
|
+
* await session.log("Connection failed", { level: "error" });
|
|
517
|
+
* await session.log("Debug info", { ephemeral: true });
|
|
518
|
+
* ```
|
|
519
|
+
*/
|
|
520
|
+
log(message: string, options?: {
|
|
521
|
+
level?: "info" | "warning" | "error";
|
|
522
|
+
ephemeral?: boolean;
|
|
523
|
+
}): Promise<void>;
|
|
524
|
+
}
|