@github/copilot-sdk 1.0.17-preview.1 → 1.0.17-preview.10

package/README.md

@@ -270,6 +270,19 @@ new CopilotClient(options?: CopilotClientOptions)
 - `telemetry?: TelemetryConfig` - OpenTelemetry configuration for the runtime process. Providing this object enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
 - `onGetTraceContext?: TraceContextProvider` - Advanced: callback for linking your application's own OpenTelemetry spans into the same distributed trace as the runtime's spans. Not needed for normal telemetry collection. See [Telemetry](#telemetry) below.
 - `sessionFs?: SessionFsConfig` - Custom session filesystem provider.
+
+For a custom provider to serve images to the `view` tool, declare
+`sessionFs.capabilities.binary: true` and implement
+`readFileBytes(path): Promise<Uint8Array>` and
+`writeFileBytes(path, content: Uint8Array, mode?: number): Promise<void>` on each session's provider. The
+adapter transmits exact bytes as standard base64; text-only providers still
+support text operations, but image reads fail rather than falling back to the
+runtime machine's filesystem. A missing binary implementation is rejected
+when a session is created.
+
+Binary reads and writes are limited to 50,330,880 raw bytes (approximately 48 MiB);
+larger results return a filesystem error before encoding or decoding.
+
 - `sessionIdleTimeoutSeconds?: number` - Server-wide idle timeout for sessions in seconds. Ignored when connecting via `RuntimeConnection.forUri`.
 - `enableRemoteSessions?: boolean` - Enable Mission Control remote session support. Ignored when connecting via `RuntimeConnection.forUri`.
 
@@ -356,6 +369,7 @@ Create a new conversation session.
 - `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`.
 - `onElicitationRequest?: ElicitationHandler` - Handler for elicitation requests dispatched by the server. Enables this client to present form-based UI dialogs on behalf of the agent or other session participants. See [Elicitation Requests](#elicitation-requests) section.
 - `hooks?: SessionHooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
+- `skillProvider?: SkillProvider` - **Experimental.** Serves skills from host storage instead of skill directories. Not persisted; pass it again on resume. See [Skill providers](#skill-providers-experimental).
 
 ```typescript
 const session = await client.createSession({
@@ -644,6 +658,24 @@ if (result.status === "pending") {
 
 See [Auto tier persistence](../docs/features/session-persistence.md#auto-tier-persistence) for the full lifecycle rules.
 
+##### `setTools(tools: Tool[]): Promise<void>`
+
+Replace the tools this client supplies to the session, together with the handlers that serve them (experimental). `tools` takes the same definitions as `createSession` and becomes this client's complete tool set; pass `[]` to remove all of this client's tools. Built-in, MCP, and plugin tools, and tools other connected clients supply, are unaffected.
+
+Once the runtime accepts the replacement, every tool call this session dispatches uses the new handlers; calls already running finish on their original handlers. If the runtime rejects it, the promise rejects and the previous tools and handlers stay in place. Concurrent calls are applied one at a time, in call order.
+
+```typescript
+await session.setTools([
+    defineTool("search_issues", {
+        description: "Search the issues shown on the current page",
+        parameters: z.object({ query: z.string() }),
+        handler: async ({ query }) => searchIssues(query),
+    }),
+]);
+```
+
+The agent sees the new tools from its next model request, which can fall within a turn in progress, so a model request already in flight can still call a tool you removed. See [Changing tools during a session](../docs/features/changing-tools.md) for the details.
+
 ##### `abort(): Promise<void>`
 
 Abort the currently processing message in this session.
@@ -839,6 +871,22 @@ defineTool("edit_file", {
 });
 ```
 
+An `apply_patch` override can declare a string schema. The model sees a required
+`input` property, but the runtime restores the declared scalar shape before
+dispatching to any SDK. Both a Zod-inferred Node handler and
+`invocation.arguments` receive the patch text as a string:
+
+```ts
+defineTool("apply_patch", {
+    parameters: z.string(),
+    overridesBuiltInTool: true,
+    handler: (patch) => patch.trim(),
+});
+```
+
+String-schema `apply_patch` overrides cannot contain JSON Schema references;
+use an object schema if references are needed.
+
 #### Skipping Permission Prompts
 
 Set `skipPermission: true` on a tool definition to allow it to execute without triggering a permission prompt:
@@ -988,6 +1036,8 @@ Available section IDs: `preamble`, `identity`, `tone`, `tool_efficiency`, `envir
 
 `identity` and `tool_instructions` are section _groups_ that target a collection of related sub-sections as a unit. Use `preamble` to target just the identity preamble without affecting its sibling sub-sections.
 
+`last_instructions` includes configured subagent-model guidance when the `task` tool is available. Removing or replacing this section also removes that guidance; a transform callback receives the complete section, including the guidance, and its returned content is authoritative. Append, prepend, and preserve retain their usual section semantics. These overrides change prompt prose only, not configured subagent models, tool availability, or runtime dispatch policy. `runtime_instructions` is a separate section: removing it does not remove `last_instructions`.
+
 Each section override supports five actions:
 
 - **`replace`** — Replace the section content entirely
@@ -996,6 +1046,8 @@ Each section override supports five actions:
 - **`prepend`** — Add content before the existing section
 - **`preserve`** — No-op that opts an individually-addressable section out of a group-level `remove`
 
+An `action` can also be a callback that receives the current section content and returns the replacement content, synchronously or asynchronously.
+
 Unknown section IDs are handled gracefully: content from `replace`/`append`/`prepend` overrides is appended to additional instructions, and `remove` overrides are silently ignored.
 
 #### Replace Mode
@@ -1069,6 +1121,46 @@ const session = await client.createSession({
 });
 ```
 
+### Skill providers (experimental)
+
+A skill provider serves skills from your own storage, such as a database, instead of `SKILL.md`
+files on disk. Provider skills join the session's skill catalog and load on demand through the
+`skill` tool, just like file-based skills.
+
+```typescript
+import type { SkillProvider } from "@github/copilot-sdk";
+
+const skillProvider: SkillProvider = {
+    listSkills: async () => [
+        { name: "release-notes", description: "Writes release notes in the team's format." },
+    ],
+    readSkill: async (name, { signal }) => (await db.findSkill(name, { signal }))?.markdown ?? null,
+};
+
+const session = await client.createSession({
+    onPermissionRequest: approveAll,
+    skillProvider,
+});
+```
+
+- `listSkills()` returns the catalog metadata. `readSkill(name)` returns the skill's markdown, or
+  `null`/`undefined` if the skill no longer exists. The markdown may omit YAML frontmatter; when
+  frontmatter is present, its fields must agree with the listed metadata, and `allowed-tools` is
+  read only from frontmatter.
+- Each call receives `{ signal }`, an `AbortSignal` that fires when the runtime cancels the call,
+  for example after its 30-second limit or when the session disconnects. It doesn't fire when the
+  connection closes or the client is force-stopped; a running call then continues until it returns.
+- The provider is never persisted. Pass it again to `resumeSession`; resuming without it unbinds
+  the provider.
+- A provider enables skills unless you set `enableSkills: false`, which keeps it bound but unused.
+  In `mode: "empty"`, skills stay disabled until you set `enableSkills: true`.
+- Errors thrown by the provider are reported to the model as a generic load failure; their
+  messages are not forwarded.
+- The runtime may call the provider concurrently, so both methods must be safe for concurrent use.
+- Skill providers are not supported for cloud sessions.
+
+See [Custom skills](../docs/features/skills.md#skill-providers-experimental) for limits and details.
+
 ### Multiple Sessions
 
 ```typescript
@@ -1443,6 +1535,20 @@ const session = await client.createSession({
                 };
             }
         },
+
+        // Called before a sub-agent's first turn (the input identifies the parent session)
+        onSubagentStart: (input, invocation) => {
+            console.log(`Starting ${input.agentDisplayName ?? input.agentName}`);
+            return { additionalContext: "Check the requested file before reporting back." };
+        },
+
+        // Called when a sub-agent completes a turn
+        onSubagentStop: (input, invocation) => {
+            console.log(`${input.agentName} replied: ${input.response}`);
+            // Return { decision: "block", reason: "Continue checking the file." }
+            // to request another child turn instead.
+            return { modifiedResponse: `Reviewed: ${input.response}` };
+        },
     },
 });
 ```
@@ -1457,6 +1563,8 @@ const session = await client.createSession({
 - `onSessionEnd` - Cleanup or logging when session ends.
 - `onErrorOccurred` - Handle errors with retry/skip/abort strategies.
 - `onAgentStop` - Observe natural top-level agent completion. Return `{ decision: "block", reason }` to request another turn; use `stopHookActive` to avoid repeated blocks.
+- `onSubagentStart` - Observe a sub-agent before its first turn and prepend `additionalContext` to the child's prompt.
+- `onSubagentStop` - Observe a sub-agent's final response. Return `{ decision: "block", reason }` to request another child turn, or `{ modifiedResponse }` to replace the response reported to the parent.
 
 ## Error Handling
 

package/dist/canvas.d.ts

@@ -32,7 +32,12 @@ export interface CanvasAction {
     description?: string;
     /** Optional JSON Schema for the action's `input` payload. */
     inputSchema?: CanvasJsonSchema;
-    /** Required per-action dispatch handler. */
+    /**
+     * Required per-action dispatch handler. The returned value becomes the
+     * `invoke_canvas_action` tool result. Return a `ToolResultObject`
+     * (with `binaryResultsForLlm`) to send text and images to the model, as a
+     * tool handler would; any other value is rendered to the model as JSON text.
+     */
     handler: (ctx: CanvasProviderInvokeActionRequest) => Promise<unknown> | unknown;
 }
 /**

package/dist/cjs/cliVersion.js

@@ -22,7 +22,7 @@ __export(cliVersion_exports, {
   COPILOT_CLI_VERSION: () => COPILOT_CLI_VERSION
 });
 module.exports = __toCommonJS(cliVersion_exports);
-const COPILOT_CLI_VERSION = "1.0.92-1";
+const COPILOT_CLI_VERSION = "1.0.93-4";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cjs/client.js

@@ -52,6 +52,7 @@ var import_toolSet = require("./toolSet.js");
 var import_types = require("./types.js");
 const MIN_PROTOCOL_VERSION = 3;
 const RUNTIME_SHUTDOWN_TIMEOUT_MS = 1e4;
+const CLOUD_SESSION_CLEANUP_TIMEOUT_MS = 1e4;
 function createMessageConnection(reader, writer) {
   let dispatch;
   let finishDrain;
@@ -580,6 +581,11 @@ class CopilotClient {
         "SessionFsConfig declares capabilities.sqlite but the provider does not implement sqlite."
       );
     }
+    if (this.sessionFsConfig.capabilities?.binary && (!provider.readFileBytes || !provider.writeFileBytes)) {
+      throw new Error(
+        "SessionFsConfig declares capabilities.binary but the provider does not implement readFileBytes and writeFileBytes."
+      );
+    }
     session.clientSessionApis.sessionFs = (0, import_sessionFsProvider.createSessionFsAdapter)(provider);
   }
   setupClientGlobalHandlers() {
@@ -1198,6 +1204,9 @@ class CopilotClient {
     if (config.gitHubToken !== void 0 && config.gitHubTokenProvider !== void 0) {
       throw new Error("gitHubToken and gitHubTokenProvider are mutually exclusive");
     }
+    if (config.cloud != null && config.skillProvider) {
+      throw new Error("Skill providers are not supported for cloud sessions.");
+    }
     if (!this.connection) {
       await this.start();
     }
@@ -1257,18 +1266,22 @@ class CopilotClient {
       if (config.hooks) {
         s.registerHooks(config.hooks);
       }
+      if (config.skillProvider) {
+        s.registerSkillProvider(config.skillProvider);
+      }
       if (transformCallbacks) {
         s.registerTransformCallbacks(transformCallbacks);
       }
       if (config.onEvent) {
         s.on(config.onEvent);
       }
-      this.sessions.set(sessionId, s);
       this.setupSessionFs(s, config);
+      this.sessions.set(sessionId, s);
       return s;
     };
     let session;
     let registeredId;
+    let uninitializedCloudSessionId;
     if (localSessionId !== void 0) {
       try {
         session = initializeSession(localSessionId);
@@ -1362,6 +1375,7 @@ class CopilotClient {
         enableSessionStore: config.enableSessionStore,
         enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
+        ...config.skillProvider ? { hasSkillProvider: true } : {},
         pluginDirectories: config.pluginDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
@@ -1391,7 +1405,9 @@ class CopilotClient {
         );
       }
       if (session === void 0) {
+        uninitializedCloudSessionId = returnedSessionId;
         session = initializeSession(returnedSessionId);
+        uninitializedCloudSessionId = void 0;
         registeredId = returnedSessionId;
       }
       this.assignGitHubTokenProvider(gitHubTokenProviderRegistrationId, returnedSessionId);
@@ -1413,6 +1429,20 @@ class CopilotClient {
       if (gitHubTokenProviderRegistrationId !== void 0) {
         this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
       }
+      if (uninitializedCloudSessionId !== void 0) {
+        try {
+          await withTimeout(
+            this.deleteSession(uninitializedCloudSessionId),
+            CLOUD_SESSION_CLEANUP_TIMEOUT_MS,
+            `session.delete timed out after ${CLOUD_SESSION_CLEANUP_TIMEOUT_MS}ms`
+          );
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [e, cleanupError],
+            "Failed to initialize and delete cloud session"
+          );
+        }
+      }
       throw e;
     }
     for (const entry of this.hostHandoffs.values()) {
@@ -1499,6 +1529,9 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    if (config.skillProvider) {
+      session.registerSkillProvider(config.skillProvider);
+    }
     const modeDefaults = this.configDefaultsForMode();
     config = { ...modeDefaults, ...config };
     config.customAgentsLocalOnly ??= modeDefaults.customAgentsLocalOnly;
@@ -1512,9 +1545,10 @@ class CopilotClient {
     if (config.onEvent) {
       session.on(config.onEvent);
     }
-    this.sessions.set(sessionId, session);
-    this.setupSessionFs(session, config);
     const toolFilterOptions = this.resolveToolFilterOptions(config);
+    this.setupSessionFs(session, config);
+    const replacedSession = this.sessions.get(sessionId);
+    this.sessions.set(sessionId, session);
     const gitHubTokenProviderRegistrationId = this.registerGitHubTokenProvider(
       config.gitHubTokenProvider,
       sessionId
@@ -1607,6 +1641,7 @@ class CopilotClient {
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
+        ...config.skillProvider ? { hasSkillProvider: true } : {},
         pluginDirectories: config.pluginDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
@@ -1651,7 +1686,13 @@ class CopilotClient {
       this.commitGitHubTokenProvider(sessionId, gitHubTokenProviderRegistrationId);
     } catch (e) {
       session._markDisconnected();
-      this.sessions.delete(sessionId);
+      if (this.sessions.get(sessionId) === session) {
+        if (replacedSession) {
+          this.sessions.set(sessionId, replacedSession);
+        } else {
+          this.sessions.delete(sessionId);
+        }
+      }
       if (gitHubTokenProviderRegistrationId !== void 0) {
         this.githubTokenProviders.delete(gitHubTokenProviderRegistrationId);
       }
@@ -2627,6 +2668,20 @@ stderr: ${stderrOutput}` : ""}`
         return await this.handleHooksInvoke(params);
       }
     );
+    this.connection.onRequest(
+      "skillProvider.list",
+      async (params, token) => await this.resolveSkillProviderSession(params)._handleSkillProviderList(token)
+    );
+    this.connection.onRequest(
+      "skillProvider.read",
+      async (params, token) => {
+        const session = this.resolveSkillProviderSession(params);
+        if (typeof params.name !== "string") {
+          throw new Error("Invalid skillProvider.read payload");
+        }
+        return await session._handleSkillProviderRead(params.name, token);
+      }
+    );
     const connection = this.connection;
     const messageWriter = this.messageWriter;
     const cliProcess = this.isExternalServer ? null : this.cliProcess;
@@ -2783,6 +2838,16 @@ stderr: ${stderrOutput}` : ""}`
     });
     return { response };
   }
+  resolveSkillProviderSession(params) {
+    if (!params || typeof params.sessionId !== "string") {
+      throw new Error("Invalid skillProvider payload");
+    }
+    const session = this.sessions.get(params.sessionId);
+    if (!session) {
+      throw new Error(`Session not found: ${params.sessionId}`);
+    }
+    return session;
+  }
   async handleHooksInvoke(params) {
     if (!params || typeof params.sessionId !== "string" || typeof params.hookType !== "string") {
       throw new Error("Invalid hooks invoke payload");

package/dist/cjs/extension.js

@@ -41,11 +41,13 @@ async function joinSession(config = {}) {
   const client = new import_client.CopilotClient({ _internalConnection: { kind: "parent-process" } });
   const {
     extensionSdkPath: _stripped,
+    skillProvider: _strippedSkillProvider,
     workflows,
     requestedEnvironmentVariables,
     ...rest
   } = config;
   void _stripped;
+  void _strippedSkillProvider;
   return client.resumeSessionForExtension(
     sessionId,
     {