@microsoft/copilot-sdk 1.0.29-unstable.42916223485.gfff36db → 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 +80 -62
- package/dist/canvas.d.ts +4 -0
- package/dist/canvas.js +1 -0
- package/dist/cjs/canvas.js +1 -0
- package/dist/cjs/cliVersion.js +1 -1
- package/dist/cjs/client.js +294 -107
- package/dist/cjs/copilotRequestHandler.js +24 -1
- package/dist/cjs/extension.js +4 -1
- package/dist/cjs/generated/rpc.js +295 -16
- package/dist/cjs/index.js +12 -2
- package/dist/cjs/localModelJson.js +103 -0
- package/dist/cjs/providerConfiguration.js +39 -0
- package/dist/cjs/rpcCancellation.js +49 -0
- package/dist/cjs/session.js +155 -10
- package/dist/cjs/taskAnalyticsJson.js +47 -0
- package/dist/cjs/types.js +14 -3
- package/dist/cjs/workflow.js +145 -1
- package/dist/cliVersion.d.ts +1 -1
- package/dist/cliVersion.js +1 -1
- package/dist/client.d.ts +33 -14
- package/dist/client.js +294 -107
- package/dist/copilotRequestHandler.js +24 -1
- package/dist/extension.d.ts +12 -2
- package/dist/extension.js +4 -1
- package/dist/generated/lifecycle-diagnostics.d.ts +48 -40
- package/dist/generated/rpc.d.ts +3668 -500
- package/dist/generated/rpc.js +295 -16
- package/dist/generated/session-events.d.ts +358 -115
- package/dist/index.d.ts +9 -5
- package/dist/index.js +14 -2
- 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/session.d.ts +64 -5
- package/dist/session.js +156 -10
- package/dist/taskAnalyticsJson.d.ts +8 -0
- package/dist/taskAnalyticsJson.js +12 -0
- package/dist/types.d.ts +223 -43
- package/dist/types.js +13 -3
- package/dist/workflow.d.ts +60 -14
- package/dist/workflow.js +143 -1
- package/docs/agent-author.md +11 -11
- package/docs/extensions.md +41 -2
- package/docs/workflows.md +52 -17
- package/package.json +16 -15
package/README.md
CHANGED
|
@@ -53,10 +53,11 @@ the model source, not the agent harness, an account, or a new routing/selection
|
|
|
53
53
|
|
|
54
54
|
## Network callbacks (experimental)
|
|
55
55
|
|
|
56
|
-
Provide `network` in `CopilotClientOptions` when the SDK host should take over parts of the runtime's networking, for example when the runtime runs in WSL or a container and should use VS Code's proxy settings and the host's Kerberos tickets. Registration happens during `start()`, before sessions can be created. Without this option, or for a callback you leave out, the runtime handles that part itself.
|
|
56
|
+
Provide `network` in `CopilotClientOptions` when the SDK host should take over parts of the runtime's networking, for example when the runtime runs in WSL or a container and should use VS Code's proxy settings, proxy credentials and the host's Kerberos tickets. Registration happens during `start()`, before sessions can be created. Without this option, or for a callback you leave out, the runtime handles that part itself.
|
|
57
57
|
|
|
58
58
|
- `resolveProxy({ url }, signal)` decides the proxies for every request the runtime would otherwise route by ambient proxy settings: proxy environment variables, `NO_PROXY` and operating-system proxy settings are not consulted unless it returns `undefined`. `url` is the request target as a PAC script sees it: without credentials or fragment, and for `https` and `wss` also without path and query. Return a PAC-style list such as `PROXY proxy.example:8080; HTTPS proxy.example:443; DIRECT` (the format of Electron's `session.resolveProxy`); return `DIRECT` for a direct connection, or `undefined` to let the runtime resolve the proxy itself, as if no callback were registered. Entry types the runtime doesn't support, such as SOCKS and QUIC, are skipped. If the callback fails, the request fails rather than connecting directly. Requests to loopback targets, and requests with an explicitly configured proxy, never consult it. The runtime caches answers, including `undefined`, for 5 seconds and waits at most 10 seconds for the callback.
|
|
59
|
-
- `authenticateNegotiate({ spn }, signal)` supplies the Kerberos token for a proxy's Negotiate challenge instead of the runtime's native credential lookup. `spn` is a service principal in the platform-independent `service/host[@REALM]` form; validate it before issuing credentials. Return a fresh base64 SPNEGO token without the `Negotiate ` prefix, or `undefined` when credentials are unavailable, which fails the request. The runtime waits at most 30 seconds for the callback (less when the request's own deadline is sooner). Tokens are not cached and must not be logged or persisted. The callback supplies the initial SPNEGO token only; exchanges requiring continuation tokens are not supported. Proxies chosen by `resolveProxy` are authenticated the same way.
|
|
59
|
+
- `authenticateNegotiate({ spn }, signal)` supplies the Kerberos token for a proxy's Negotiate challenge instead of the runtime's native credential lookup. `spn` is a service principal in the platform-independent `service/host[@REALM]` form; validate it before issuing credentials. Return a fresh base64 SPNEGO token without the `Negotiate ` prefix, or `undefined` when credentials are unavailable, which fails the request unless the proxy also offers Basic and `authenticateBasic` supplies credentials. The runtime waits at most 30 seconds for the callback (less when the request's own deadline is sooner). Tokens are not cached and must not be logged or persisted. The callback supplies the initial SPNEGO token only; exchanges requiring continuation tokens are not supported. Proxies chosen by `resolveProxy` are authenticated the same way.
|
|
60
|
+
- `authenticateBasic({ proxy, realm, previousRejected }, signal)` supplies the credentials for a proxy's Basic challenge on requests the runtime tunnels through the proxy (`https` and `wss`). `proxy` is the proxy as `http://host:port` or `https://host:port`; `realm` comes from the proxy, so treat it as untrusted text. Return `{ username, password }`, or `undefined` when credentials are unavailable, which fails the request with the proxy's challenge; an empty user name counts as unavailable, the user name must not contain a colon, neither the user name nor the password may contain control characters, and an omitted password means an empty one. The runtime remembers the answer for that proxy and uses it for later connections, until the proxy rejects it; then it calls again with `previousRejected` set, so return different credentials, for example by asking the user, or `undefined`. A later connection sends the answer without waiting for a challenge, unless the runtime may try Negotiate with that proxy first. A connection submits at most three sets of credentials. While a call is pending, other requests through that proxy wait for its answer. When a proxy offers both Negotiate and Basic, the runtime prefers Negotiate and answers with Basic when Negotiate is unavailable or the proxy rejects it. The runtime does not time the callback out: a request whose own deadline passes stops waiting, but the answer is still remembered. Credentials must not be logged or persisted.
|
|
60
61
|
|
|
61
62
|
Each callback's `signal` aborts when the runtime stops waiting (it cancels the request, for example after its timeout, or the connection closes); the SDK then stops awaiting the callback and ignores any later result.
|
|
62
63
|
|
|
@@ -68,6 +69,8 @@ const client = new CopilotClient({ mode: "coding-agent",
|
|
|
68
69
|
scope: "runtime",
|
|
69
70
|
resolveProxy: async ({ url }) => session.resolveProxy(url),
|
|
70
71
|
authenticateNegotiate: async ({ spn }, signal) => acquireToken(spn, signal),
|
|
72
|
+
authenticateBasic: async ({ proxy, realm }, signal) =>
|
|
73
|
+
promptForCredentials(proxy, realm, signal),
|
|
71
74
|
},
|
|
72
75
|
});
|
|
73
76
|
```
|
|
@@ -291,6 +294,26 @@ the raw `mcp:<server-key>-<tool-name>` form. For `customAgents[].tools` and
|
|
|
291
294
|
|
|
292
295
|
## API Reference
|
|
293
296
|
|
|
297
|
+
### HTTP requests (experimental)
|
|
298
|
+
|
|
299
|
+
Use `client.rpc.fetch.create()` to allocate a handle. Call `fetch.send()` with a required `responseMode`:
|
|
300
|
+
|
|
301
|
+
- `"text"` returns HTTP metadata and complete UTF-8 text, with a default 1 MiB decoded body limit.
|
|
302
|
+
- `"stream"` returns headers immediately. Call `fetch.read()` for base64 chunks until `done`, or `fetch.cancel()` for headers only.
|
|
303
|
+
- `"file"` writes to `destinationPath` on the runtime host. It returns metadata, path, and size; an existing destination fails.
|
|
304
|
+
|
|
305
|
+
Streaming chunks cross JSON-RPC. Prefer file mode for large bodies. Stream and file modes have no default limit; `bodyLimitBytes` accepts zero.
|
|
306
|
+
|
|
307
|
+
All four methods are public to SDK clients, including extension connections. They do not require CLI admission.
|
|
308
|
+
|
|
309
|
+
Only the connection that creates a handle can use it. Use `fetch.cancel()` to cancel a pending request or abandon a stream.
|
|
310
|
+
Completed files survive cancellation and disconnect; the caller deletes them. Failures remove only incomplete request-created files. Remote clients cannot read host paths locally.
|
|
311
|
+
Optional credential contexts retain their original connection and credential authority. Public fetch access does not grant access to another caller's credentials.
|
|
312
|
+
|
|
313
|
+
The [runnable fetch example](examples/fetch.mjs) demonstrates all modes, file survival after disconnect, and caller cleanup against a local fixture.
|
|
314
|
+
|
|
315
|
+
Import `FetchSendParams`, `FetchSendResult`, `FetchTransportErrorData`, `FetchFileErrorData`, and `CredentialContextErrorData` from `@microsoft/copilot-sdk`.
|
|
316
|
+
|
|
294
317
|
### CopilotClient
|
|
295
318
|
|
|
296
319
|
#### Constructor
|
|
@@ -302,10 +325,10 @@ new CopilotClient(options: CopilotClientOptions)
|
|
|
302
325
|
**Options:**
|
|
303
326
|
|
|
304
327
|
- `connection?: RuntimeConnection` - How to connect to the Copilot runtime. Construct via the factory functions on `RuntimeConnection`:
|
|
305
|
-
- `RuntimeConnection.forStdio({ path?, args?, env? })`
|
|
328
|
+
- `RuntimeConnection.forStdio({ path?, args?, env? })` — spawn the runtime and communicate over its stdin/stdout.
|
|
306
329
|
- `RuntimeConnection.forTcp({ port?, connectionToken?, path?, args?, env? })` — spawn the runtime as a TCP server.
|
|
307
330
|
- `RuntimeConnection.forUri(url, { connectionToken? })` — connect to an already-running runtime (mutually exclusive with `gitHubToken`/`useLoggedInUser`). There is no top-level `cliUrl` shortcut; use this factory for URL-based connections.
|
|
308
|
-
- `RuntimeConnection.forInProcess()` — host the runtime in-process over its native C ABI (FFI).
|
|
331
|
+
- `RuntimeConnection.forInProcess()` (default) — host the runtime in-process over its native C ABI (FFI). Typed `telemetry` is host-scoped; client-level `env` and `workingDirectory` are rejected. Configure working directories per session.
|
|
309
332
|
- The child-process transports (`forStdio`/`forTcp`) also accept a per-connection `env`. Set it there or via the top-level `env` option — not both (setting both throws).
|
|
310
333
|
- Managed child-process connections materialize the bundled `copilot-runtime` and adjacent `runtime.node`, then launch the wrapper by default. An explicit connection `path` or `COPILOT_CLI_PATH` overrides the bundled runtime.
|
|
311
334
|
- `mode: "empty" | "coding-agent"` - Required defaulting strategy. Use `"empty"` for multi-user server mode or explicitly select `"coding-agent"` for CLI-like behavior.
|
|
@@ -394,7 +417,7 @@ transport tests do not establish a working installer, live OAuth or restart safe
|
|
|
394
417
|
|
|
395
418
|
##### `start(): Promise<void>`
|
|
396
419
|
|
|
397
|
-
Start the
|
|
420
|
+
Start the runtime host and establish a connection.
|
|
398
421
|
|
|
399
422
|
##### `stop(): Promise<Error[]>`
|
|
400
423
|
|
|
@@ -420,7 +443,7 @@ Create a new conversation session.
|
|
|
420
443
|
|
|
421
444
|
- `sessionId?: string` - Custom session ID.
|
|
422
445
|
- `model?: string` - Model to use ("gpt-5", "claude-sonnet-4.5", etc.). **Required when using custom provider.**
|
|
423
|
-
- `capi?: CapiSessionOptions` - Copilot API options. With `model: "auto"`, set `autoTier` to `"efficiency"`, `"balance"`, `"intelligence"`, or `"fast"` to choose a routing preference. `"fast"` is an integrator-only latency preset, not a first-party GitHub Copilot product preference. Requires a runtime with Auto tier support and V2 Auto routing. Omission preserves default behavior. See [Auto tier persistence](../docs/features/session-persistence.md#auto-tier-persistence) for resume semantics.
|
|
446
|
+
- `capi?: CapiSessionOptions` - Copilot API options. With `model: "auto"`, set `autoTier` to `"efficiency"`, `"balance"`, `"intelligence"`, or `"fast"` to choose a routing preference. `"fast"` is an integrator-only latency preset, not a first-party GitHub Copilot product preference. Requires a runtime with Auto tier support and V2 Auto routing. Omission preserves default behavior. See [Auto tier persistence](../docs/features/session-persistence.md#auto-tier-persistence) for resume semantics. For Copilot Fusion, use `model: "fusion"` and set `fusionTier` to `"standard"`, `"high"`, or `"max"`, like the CLI's `--model fusion --fusion-tier <tier>`; the `autoTier` values `"balance"`, `"hydrafusion"`, and `"hydrafusion-max"` that these replace are deprecated. See [Copilot Fusion names](../docs/features/session-persistence.md#copilot-fusion-names).
|
|
424
447
|
- `reasoningEffort?: "low" | "medium" | "high" | "xhigh" | "max"` - Reasoning effort level for models that support it. Use `listModels()` to check which models support this option.
|
|
425
448
|
- `tools?: Tool[]` - Custom tools exposed to the CLI. Tools without `handler` are declaration-only and must be resolved via pending tool-call RPCs.
|
|
426
449
|
- `systemMessage?: SystemMessageConfig` - System message customization (see below)
|
|
@@ -430,10 +453,11 @@ Create a new conversation session.
|
|
|
430
453
|
- `refreshCustomInstructions?: boolean` - Invalidates the process-wide custom-instruction discovery cache before creating this session, so instruction-file edits made in the same runtime are read again. Defaults to `false` (cache reuse). Other sessions in this runtime may observe updated instructions on later turns or discovery. This does not watch files or enable disabled instruction loading. Available on `SessionConfig`, not `ResumeSessionConfig`.
|
|
431
454
|
- `enableSessionStore?: boolean` - Enables the cross-session store for search and retrieval across sessions. When unset in `"coding-agent"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled.
|
|
432
455
|
- `enableSessionTelemetry?: boolean` - Disables internal session telemetry only when set to `false`. Omission or `true` enables it for eligible GitHub-authenticated sessions, including custom-provider (BYOK) sessions. Host and account policies still control uploads; this is separate from OpenTelemetry configuration.
|
|
433
|
-
- `gitHubTokenProvider?: GitHubTokenProvider` - Acquires rotating, session-scoped GitHub tokens. Token results require
|
|
456
|
+
- `gitHubTokenProvider?: GitHubTokenProvider` - Acquires rotating, session-scoped GitHub tokens. Token results require an `expiresIn` value in seconds remaining when the callback completes, of which more than one hour must still remain after the runtime validates the token; production tokens typically last eight hours. Cannot be combined with `gitHubToken`.
|
|
434
457
|
- `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
|
|
435
458
|
- `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. `approveAll` approves requests when managed settings are disabled and throws when `enableManagedSettings` is true. Custom handlers can inspect `managedApprovalRequired` for human-facing confirmation logic. See [Permission Handling](#permission-handling) section.
|
|
436
459
|
- `onUserInputRequest?: UserInputHandler` - Handler for legacy question-and-answer requests from the agent. Enables the legacy `ask_user` tool. See [User Input Requests](#user-input-requests) section.
|
|
460
|
+
- `onShellAuthenticationRequest?: ShellAuthenticationHandler` - Handler for passwords and other answers that shell commands run by the agent ask for, such as `sudo -A`, `ssh`, and `git` over HTTPS. The answer goes only to the program that asked; the model never sees it. Without a handler, those commands fail as they do without a terminal. See [Shell password prompts](../docs/features/shell-password-prompts.md).
|
|
437
461
|
- `askUserVariant?: "legacy" | "elicitation"` - Selects the model-facing `ask_user` tool shape when creating or cold-resuming a session. Defaults to `"legacy"`; use `"elicitation"` with `onElicitationRequest`.
|
|
438
462
|
- `interactiveUser?: boolean` - Declares that a person types this session's messages, as in an editor chat panel. Enables the runtime's user-message analysis telemetry for user-authored messages; automated messages stay excluded. Defaults to `false`. Ignored for cloud sessions. Re-supply it when cold-resuming a session; it is ignored when resuming a session that is already active.
|
|
439
463
|
- `permissionMode?: PermissionMode` - Applies `"manual"`, `"assisted"`, or `"allow-all"` before the session's first turn: before `createSession` returns, and before a resume continues pending work. Uses the same checks as `session.rpc.permissions.setMode`; `session.permissionModeResult` reports whether it was applied and the authoritative mode. Not supported for cloud sessions.
|
|
@@ -580,7 +604,7 @@ Send a message to the session. Returns immediately after the message is queued;
|
|
|
580
604
|
**Options:**
|
|
581
605
|
|
|
582
606
|
- `prompt: string` - The message/prompt to send
|
|
583
|
-
- `source?: MessageSource` - `"user"`, `"system"`, or `` `
|
|
607
|
+
- `source?: MessageSource` - `"user"`, `"system"`, `` `agent-${string}` ``, or `` `automation-${string}` `` provenance; omitted by default. An automation turn defines the session's task like a user message but carries no human authority; see [Message provenance](../docs/features/steering-and-queueing.md#message-provenance).
|
|
584
608
|
- `attachments?: Array<{type, path, displayName}>` - File attachments
|
|
585
609
|
- `mode?: "enqueue" | "immediate"` - Delivery mode
|
|
586
610
|
- `clientTurnId?: string` - Opaque turn ID the runtime adds to MCP `tools/call` requests in this turn as `_meta["com.github.copilot/turnId"]` and echoes on this message's `user.message` event as `clientTurnId` (see [Tool call and turn IDs in `_meta`](../docs/hooks/pre-mcp-tool-call.md#tool-call-and-turn-ids-in-_meta))
|
|
@@ -840,6 +864,7 @@ Change the model for this session. The new model takes effect for the next messa
|
|
|
840
864
|
|
|
841
865
|
- `reasoningEffort?: string` - Reasoning effort level
|
|
842
866
|
- `autoTier?: AutoTier | null` - Auto routing preference to stage together with selecting `auto`. Pass `null` to return to the provider's default Auto routing; omit it to leave the current preference unchanged.
|
|
867
|
+
- `fusionTier?: FusionTier` - Copilot Fusion tier (`"standard"`, `"high"`, or `"max"`) to stage together with selecting `fusion` or `auto`, for example `setModel("fusion", { fusionTier: "high" })`. Cannot be combined with `autoTier`.
|
|
843
868
|
|
|
844
869
|
##### `setAutoTier(autoTier: AutoTier | null): Promise<ModelSwitchAutoTierResult>`
|
|
845
870
|
|
|
@@ -871,6 +896,14 @@ if (result.status === "pending") {
|
|
|
871
896
|
|
|
872
897
|
See [Auto tier persistence](../docs/features/session-persistence.md#auto-tier-persistence) for the full lifecycle rules.
|
|
873
898
|
|
|
899
|
+
##### `setFusionTier(fusionTier: FusionTier): Promise<ModelSwitchAutoTierResult>`
|
|
900
|
+
|
|
901
|
+
Change the Copilot Fusion tier without changing the selected model, naming the tier as the CLI's `--fusion-tier` does: `"standard"`, `"high"`, or `"max"`. The runtime resolves the tier to the Auto routing preference it stands for and then handles the request exactly like `setAutoTier`. Use `setAutoTier(null)` to return to the provider's default routing.
|
|
902
|
+
|
|
903
|
+
```typescript
|
|
904
|
+
const result = await session.setFusionTier("max");
|
|
905
|
+
```
|
|
906
|
+
|
|
874
907
|
##### `rpc.model.getReasoningSummaries(params)` (experimental)
|
|
875
908
|
|
|
876
909
|
Read the current model's reasoning-summary presentation policy without changing session state. Call `session.rpc.model.list()` first to load the model catalog; otherwise the result may have `ready: false`. The request and result types are exported from `@microsoft/copilot-sdk`.
|
|
@@ -1088,52 +1121,6 @@ await session.send({ prompt: "What does the most recent jpg in this directory po
|
|
|
1088
1121
|
Enable streaming to receive assistant response chunks as they're generated:
|
|
1089
1122
|
|
|
1090
1123
|
<!-- docs-validate: strict -->
|
|
1091
|
-
<!-- docs-validate: hidden -->
|
|
1092
|
-
|
|
1093
|
-
```typescript
|
|
1094
|
-
import { approveAll } from "@microsoft/copilot-sdk";
|
|
1095
|
-
|
|
1096
|
-
const session = await client.createSession({
|
|
1097
|
-
model: "gpt-5",
|
|
1098
|
-
streaming: true,
|
|
1099
|
-
onPermissionRequest: approveAll,
|
|
1100
|
-
});
|
|
1101
|
-
|
|
1102
|
-
// Wait for completion using typed event handlers
|
|
1103
|
-
const done = new Promise<void>((resolve) => {
|
|
1104
|
-
session.on("assistant.message_delta", (event) => {
|
|
1105
|
-
// Streaming message chunk - print incrementally
|
|
1106
|
-
process.stdout.write(event.data.deltaContent);
|
|
1107
|
-
});
|
|
1108
|
-
|
|
1109
|
-
session.on("assistant.reasoning_delta", (event) => {
|
|
1110
|
-
// Streaming reasoning chunk (if model supports reasoning)
|
|
1111
|
-
process.stdout.write(event.data.deltaContent);
|
|
1112
|
-
});
|
|
1113
|
-
|
|
1114
|
-
session.on("assistant.message", (event) => {
|
|
1115
|
-
// Final message - complete content
|
|
1116
|
-
console.log("\n--- Final message ---");
|
|
1117
|
-
console.log(event.data.content);
|
|
1118
|
-
});
|
|
1119
|
-
|
|
1120
|
-
session.on("assistant.reasoning", (event) => {
|
|
1121
|
-
// Final reasoning content (if model supports reasoning)
|
|
1122
|
-
console.log("--- Reasoning ---");
|
|
1123
|
-
console.log(event.data.content);
|
|
1124
|
-
});
|
|
1125
|
-
|
|
1126
|
-
session.on("session.idle", () => {
|
|
1127
|
-
// Session finished processing
|
|
1128
|
-
resolve();
|
|
1129
|
-
});
|
|
1130
|
-
});
|
|
1131
|
-
|
|
1132
|
-
await session.send({ prompt: "Tell me a short story" });
|
|
1133
|
-
await done; // Wait for streaming to complete
|
|
1134
|
-
```
|
|
1135
|
-
|
|
1136
|
-
<!-- /docs-validate: hidden -->
|
|
1137
1124
|
|
|
1138
1125
|
```typescript
|
|
1139
1126
|
const session = await client.createSession({
|
|
@@ -1238,7 +1225,7 @@ const session = await client.createSession({
|
|
|
1238
1225
|
|
|
1239
1226
|
```ts
|
|
1240
1227
|
import { z } from "zod";
|
|
1241
|
-
import {
|
|
1228
|
+
import { defineTool } from "@microsoft/copilot-sdk";
|
|
1242
1229
|
|
|
1243
1230
|
const session = await client.createSession({
|
|
1244
1231
|
model: "gpt-5",
|
|
@@ -1869,7 +1856,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K
|
|
|
1869
1856
|
|
|
1870
1857
|
**ProviderConfig:**
|
|
1871
1858
|
|
|
1872
|
-
- `type?: "openai" | "azure" | "anthropic"` - Provider type (default: "openai")
|
|
1859
|
+
- `type?: "openai" | "azure" | "anthropic" | "google"` - Provider type (default: "openai"). `"google"` (experimental) uses Google's native Gemini Interactions API.
|
|
1873
1860
|
- `baseUrl: string` - API endpoint URL (required)
|
|
1874
1861
|
- `apiKey?: string` - API key (optional for local providers like Ollama)
|
|
1875
1862
|
- `bearerToken?: string` - Bearer token for authentication (takes precedence over apiKey)
|
|
@@ -1934,7 +1921,7 @@ const session = await client.createSession({
|
|
|
1934
1921
|
|
|
1935
1922
|
## Telemetry
|
|
1936
1923
|
|
|
1937
|
-
The SDK supports OpenTelemetry for distributed tracing. Provide a `telemetry` config to enable trace export from the
|
|
1924
|
+
The SDK supports OpenTelemetry for distributed tracing. Provide a `telemetry` config to enable trace export from the runtime — this is all most users need:
|
|
1938
1925
|
|
|
1939
1926
|
<!-- docs-validate: strict -->
|
|
1940
1927
|
|
|
@@ -1949,7 +1936,7 @@ const client = new CopilotClient({
|
|
|
1949
1936
|
});
|
|
1950
1937
|
```
|
|
1951
1938
|
|
|
1952
|
-
With just this configuration, the
|
|
1939
|
+
With just this configuration, the runtime emits spans for every session, message, and tool call to your collector. No additional dependencies or setup required.
|
|
1953
1940
|
|
|
1954
1941
|
**TelemetryConfig options:**
|
|
1955
1942
|
|
|
@@ -1962,7 +1949,7 @@ With just this configuration, the CLI emits spans for every session, message, an
|
|
|
1962
1949
|
|
|
1963
1950
|
### Advanced: Trace Context Propagation
|
|
1964
1951
|
|
|
1965
|
-
> **You don't need this for normal telemetry collection.** The `telemetry` config above is sufficient to get full traces from the
|
|
1952
|
+
> **You don't need this for normal telemetry collection.** The `telemetry` config above is sufficient to get full traces from the runtime.
|
|
1966
1953
|
|
|
1967
1954
|
`onGetTraceContext` is only needed if your application creates its own OpenTelemetry spans and you want them to appear in the **same distributed trace** as the CLI's spans — for example, to nest a "handle tool call" span inside the CLI's "execute tool" span, or to show the SDK call as a child of your application's request-handling span.
|
|
1968
1955
|
|
|
@@ -2212,6 +2199,33 @@ const session = await client.createSession({
|
|
|
2212
2199
|
});
|
|
2213
2200
|
```
|
|
2214
2201
|
|
|
2202
|
+
### Reporting a person's answers
|
|
2203
|
+
|
|
2204
|
+
When a person answers a prompt in your UI, label the result with `createAttributedResult` so Assisted Permissions can treat the answer as the person's own authority. The same label works for permission, user-input, plan-review, and elicitation handlers:
|
|
2205
|
+
|
|
2206
|
+
<!-- docs-validate: strict -->
|
|
2207
|
+
|
|
2208
|
+
```typescript
|
|
2209
|
+
import { createAttributedResult, type PermissionDecisionContext } from "@microsoft/copilot-sdk";
|
|
2210
|
+
|
|
2211
|
+
const personAnswered: PermissionDecisionContext = {
|
|
2212
|
+
source: "human_response",
|
|
2213
|
+
responseCapability: "interactive",
|
|
2214
|
+
surface: "sdk",
|
|
2215
|
+
outcome: "prompted_user",
|
|
2216
|
+
};
|
|
2217
|
+
|
|
2218
|
+
const session = await client.createSession({
|
|
2219
|
+
model: "gpt-5",
|
|
2220
|
+
onUserInputRequest: async (request) =>
|
|
2221
|
+
createAttributedResult({ answer: "Only src/app.ts", wasFreeform: true }, personAnswered),
|
|
2222
|
+
onExitPlanModeRequest: async () =>
|
|
2223
|
+
createAttributedResult({ approved: true, selectedAction: "interactive" }, personAnswered),
|
|
2224
|
+
});
|
|
2225
|
+
```
|
|
2226
|
+
|
|
2227
|
+
Label a person's declines and dismissals too; the runtime decides which answers carry authority. It accepts the label only from the connection that owns the session, so other connections' answers still settle, without it. Leave automated answers unlabeled.
|
|
2228
|
+
|
|
2215
2229
|
## Elicitation Requests
|
|
2216
2230
|
|
|
2217
2231
|
Register an `onElicitationRequest` handler to let your client act as an elicitation provider — presenting form-based UI dialogs on behalf of the agent. When provided, the server notifies your client whenever a tool or MCP server needs structured user input.
|
|
@@ -2492,10 +2506,13 @@ npm test
|
|
|
2492
2506
|
### Internal feature-flag example
|
|
2493
2507
|
|
|
2494
2508
|
[`examples/internal-feature-flags.ts`](examples/internal-feature-flags.ts) uses
|
|
2495
|
-
the generated
|
|
2509
|
+
the generated RPC factories against a real runtime over stdio.
|
|
2496
2510
|
It lists the catalog and shows environment, settings, and explicit-override
|
|
2497
2511
|
precedence. It also checks that static resolution does not apply `COPILOT_EXP_*`
|
|
2498
|
-
experiment assignments. It creates
|
|
2512
|
+
experiment assignments. It then creates a session with a feature-flag
|
|
2513
|
+
configuration, checks that the session's `githubIqEnabled` setting predicate
|
|
2514
|
+
keeps its value after `options.update` changes `enabledFeatureFlags`, and
|
|
2515
|
+
destroys the session. It sends no model request.
|
|
2499
2516
|
|
|
2500
2517
|
After you prepare matching runtime artifacts, run this from the runtime repository root:
|
|
2501
2518
|
|
|
@@ -2507,7 +2524,8 @@ COPILOT_RUNTIME_PROVIDER_LIB="$PWD/bazel-bin/src/native/runtime/runtime.node" \
|
|
|
2507
2524
|
```
|
|
2508
2525
|
|
|
2509
2526
|
The JSON output includes `staticResolution` values of `false`, `true`, `false`,
|
|
2510
|
-
and `true`, in that order
|
|
2527
|
+
and `true`, in that order, and `lifecycleViaExistingMethods` of `[true, true]`.
|
|
2528
|
+
The feature-flag and settings-predicate methods are internal, not public SDK APIs.
|
|
2511
2529
|
|
|
2512
2530
|
## License
|
|
2513
2531
|
|
package/dist/canvas.d.ts
CHANGED
|
@@ -54,6 +54,8 @@ export interface CanvasDeclaration {
|
|
|
54
54
|
displayName: string;
|
|
55
55
|
/** Short, single-sentence description shown to the agent in canvas catalogs. */
|
|
56
56
|
description: string;
|
|
57
|
+
/** Optional icon path, resolved relative to the extension entrypoint. */
|
|
58
|
+
icon?: string;
|
|
57
59
|
/** Optional JSON Schema for the `input` payload accepted by `canvas.open`. */
|
|
58
60
|
inputSchema?: CanvasJsonSchema;
|
|
59
61
|
/** Agent-invocable actions exposed via `invoke_canvas_action`. */
|
|
@@ -85,6 +87,8 @@ export interface CanvasOptions {
|
|
|
85
87
|
displayName: string;
|
|
86
88
|
/** @see CanvasDeclaration.description */
|
|
87
89
|
description: string;
|
|
90
|
+
/** @see CanvasDeclaration.icon */
|
|
91
|
+
icon?: string;
|
|
88
92
|
/** @see CanvasDeclaration.inputSchema */
|
|
89
93
|
inputSchema?: CanvasJsonSchema;
|
|
90
94
|
/**
|
package/dist/canvas.js
CHANGED
package/dist/cjs/canvas.js
CHANGED
package/dist/cjs/cliVersion.js
CHANGED
|
@@ -22,7 +22,7 @@ __export(cliVersion_exports, {
|
|
|
22
22
|
COPILOT_CLI_VERSION: () => COPILOT_CLI_VERSION
|
|
23
23
|
});
|
|
24
24
|
module.exports = __toCommonJS(cliVersion_exports);
|
|
25
|
-
const COPILOT_CLI_VERSION = "1.0.
|
|
25
|
+
const COPILOT_CLI_VERSION = "1.0.106-9.unstable.r43755488033.g11df7b2";
|
|
26
26
|
const COPILOT_CLI_USE_NPM_PACKAGE = false;
|
|
27
27
|
// Annotate the CommonJS export names for ESM import in node:
|
|
28
28
|
0 && (module.exports = {
|