@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.
Files changed (91) hide show
  1. package/README.md +2531 -2
  2. package/dist/canvas.d.ts +135 -0
  3. package/dist/canvas.js +51 -0
  4. package/dist/cjs/canvas.js +77 -0
  5. package/dist/cjs/cliVersion.js +31 -0
  6. package/dist/cjs/client.js +3941 -0
  7. package/dist/cjs/copilotRequestHandler.js +815 -0
  8. package/dist/cjs/decisions.js +139 -0
  9. package/dist/cjs/entra.js +83 -0
  10. package/dist/cjs/extension.js +79 -0
  11. package/dist/cjs/ffiRuntimeHost.js +400 -0
  12. package/dist/cjs/generated/lifecycle-diagnostics.js +16 -0
  13. package/dist/cjs/generated/rpc.js +5883 -0
  14. package/dist/cjs/generated/session-events.js +16 -0
  15. package/dist/cjs/host.js +83 -0
  16. package/dist/cjs/index.js +100 -0
  17. package/dist/cjs/installationConfirmation.js +98 -0
  18. package/dist/cjs/jsonrpcTypes.js +41 -0
  19. package/dist/cjs/localModelJson.js +103 -0
  20. package/dist/cjs/package.json +1 -0
  21. package/dist/cjs/providerConfiguration.js +39 -0
  22. package/dist/cjs/rpcCancellation.js +49 -0
  23. package/dist/cjs/runtimeArtifacts.js +255 -0
  24. package/dist/cjs/schema.js +40 -0
  25. package/dist/cjs/sdkProtocolVersion.js +33 -0
  26. package/dist/cjs/session.js +2764 -0
  27. package/dist/cjs/sessionFsProvider.js +283 -0
  28. package/dist/cjs/taskAnalyticsJson.js +47 -0
  29. package/dist/cjs/telemetry.js +35 -0
  30. package/dist/cjs/toolSet.js +107 -0
  31. package/dist/cjs/types.js +204 -0
  32. package/dist/cjs/workflow.js +278 -0
  33. package/dist/cliVersion.d.ts +2 -0
  34. package/dist/cliVersion.js +6 -0
  35. package/dist/client.d.ts +576 -0
  36. package/dist/client.js +3924 -0
  37. package/dist/copilotRequestHandler.d.ts +91 -0
  38. package/dist/copilotRequestHandler.js +787 -0
  39. package/dist/decisions.d.ts +65 -0
  40. package/dist/decisions.js +113 -0
  41. package/dist/entra.d.ts +3 -0
  42. package/dist/entra.js +59 -0
  43. package/dist/extension.d.ts +69 -0
  44. package/dist/extension.js +59 -0
  45. package/dist/ffiRuntimeHost.d.ts +44 -0
  46. package/dist/ffiRuntimeHost.js +366 -0
  47. package/dist/generated/lifecycle-diagnostics.d.ts +232 -0
  48. package/dist/generated/lifecycle-diagnostics.js +0 -0
  49. package/dist/generated/rpc.d.ts +47706 -0
  50. package/dist/generated/rpc.js +5854 -0
  51. package/dist/generated/session-events.d.ts +17349 -0
  52. package/dist/generated/session-events.js +0 -0
  53. package/dist/host.d.ts +143 -0
  54. package/dist/host.js +59 -0
  55. package/dist/index.d.ts +23 -0
  56. package/dist/index.js +74 -0
  57. package/dist/installationConfirmation.d.ts +19 -0
  58. package/dist/installationConfirmation.js +74 -0
  59. package/dist/jsonrpcTypes.d.ts +16 -0
  60. package/dist/jsonrpcTypes.js +17 -0
  61. package/dist/localModelJson.d.ts +1 -0
  62. package/dist/localModelJson.js +69 -0
  63. package/dist/providerConfiguration.d.ts +3 -0
  64. package/dist/providerConfiguration.js +15 -0
  65. package/dist/rpcCancellation.d.ts +3 -0
  66. package/dist/rpcCancellation.js +25 -0
  67. package/dist/runtimeArtifacts.d.ts +18 -0
  68. package/dist/runtimeArtifacts.js +233 -0
  69. package/dist/schema.d.ts +4 -0
  70. package/dist/schema.js +14 -0
  71. package/dist/sdkProtocolVersion.d.ts +10 -0
  72. package/dist/sdkProtocolVersion.js +8 -0
  73. package/dist/session.d.ts +524 -0
  74. package/dist/session.js +2751 -0
  75. package/dist/sessionFsProvider.d.ts +130 -0
  76. package/dist/sessionFsProvider.js +257 -0
  77. package/dist/taskAnalyticsJson.d.ts +8 -0
  78. package/dist/taskAnalyticsJson.js +12 -0
  79. package/dist/telemetry.d.ts +14 -0
  80. package/dist/telemetry.js +11 -0
  81. package/dist/toolSet.d.ts +75 -0
  82. package/dist/toolSet.js +82 -0
  83. package/dist/types.d.ts +3864 -0
  84. package/dist/types.js +169 -0
  85. package/dist/workflow.d.ts +413 -0
  86. package/dist/workflow.js +248 -0
  87. package/docs/agent-author.md +372 -0
  88. package/docs/examples.md +747 -0
  89. package/docs/extensions.md +121 -0
  90. package/docs/workflows.md +303 -0
  91. 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
+ }