@github/copilot-sdk 1.0.17-preview.3 → 1.0.17-preview.5

package/dist/sessionFsProvider.d.ts

@@ -37,6 +37,10 @@ export declare class SessionFsSqliteTransactionFailure extends Error {
     readonly errorClass: SessionFsSqliteTransactionErrorClass;
     constructor(message: string, errorClass?: SessionFsSqliteTransactionErrorClass);
 }
+/** Throw from `writeFile` only when the provider changed the target before failing. */
+export declare class SessionFsWriteFailure extends Error {
+    readonly writeChanged = true;
+}
 /**
  * SQLite operations for the per-session database.
  * Implementers provide query execution and existence checking.
@@ -78,7 +82,11 @@ export interface SessionFsSqliteProvider {
 export interface SessionFsProvider {
     /** Reads the full content of a file. Throw if the file does not exist. */
     readFile(path: string): Promise<string>;
-    /** Writes content to a file, creating parent directories if needed. */
+    /** Read exact file bytes. Required when capabilities.binary is enabled. */
+    readFileBytes?(path: string): Promise<Uint8Array>;
+    /** Write exact file bytes. Required when capabilities.binary is enabled. */
+    writeFileBytes?(path: string, content: Uint8Array, mode?: number): Promise<void>;
+    /** Writes content to a file, creating parent directories if needed. Throw {@link SessionFsWriteFailure} if a failed write changed the target. */
     writeFile(path: string, content: string, mode?: number): Promise<void>;
     /** Appends content to a file, creating parent directories if needed. */
     appendFile(path: string, content: string, mode?: number): Promise<void>;

package/dist/sessionFsProvider.js

@@ -1,3 +1,5 @@
+const MAX_BINARY_BYTES = (64 * 1024 * 1024 - 1024) / 4 * 3;
+const MAX_BINARY_CONTENT_LENGTH = Math.ceil(MAX_BINARY_BYTES / 3) * 4;
 class SessionFsSqliteTransactionFailure extends Error {
   /** Failure classification reported to the runtime. */
   errorClass;
@@ -7,6 +9,9 @@ class SessionFsSqliteTransactionFailure extends Error {
     this.errorClass = errorClass;
   }
 }
+class SessionFsWriteFailure extends Error {
+  writeChanged = true;
+}
 function normalizeSqliteParams(params) {
   if (!params) {
     return void 0;
@@ -29,10 +34,60 @@ function createSessionFsAdapter(provider) {
         return { content: "", error: toSessionFsError(err) };
       }
     },
+    readFileBytes: async ({ path }) => {
+      if (!provider.readFileBytes) {
+        return {
+          content: "",
+          error: { code: "UNKNOWN", message: "Binary reads are not supported" }
+        };
+      }
+      try {
+        const bytes = await provider.readFileBytes(path);
+        if (bytes.length > MAX_BINARY_BYTES) {
+          return {
+            content: "",
+            error: {
+              code: "UNKNOWN",
+              message: "sessionFs.readFileBytes content exceeds the binary read limit"
+            }
+          };
+        }
+        return {
+          content: Buffer.from(bytes).toString("base64")
+        };
+      } catch (err) {
+        return { content: "", error: toSessionFsError(err) };
+      }
+    },
     writeFile: async ({ path, content, mode }) => {
       try {
         await provider.writeFile(path, content, mode);
         return void 0;
+      } catch (err) {
+        const error = toSessionFsError(err);
+        return err instanceof SessionFsWriteFailure ? { ...error, writeChanged: true } : error;
+      }
+    },
+    writeFileBytes: async ({ path, content, mode }) => {
+      if (!provider.writeFileBytes) {
+        return { code: "UNKNOWN", message: "Binary writes are not supported" };
+      }
+      if (content.length > MAX_BINARY_CONTENT_LENGTH) {
+        return {
+          code: "UNKNOWN",
+          message: "sessionFs.writeFileBytes content exceeds the binary write limit"
+        };
+      }
+      const bytes = Buffer.from(content, "base64");
+      if (bytes.toString("base64") !== content || bytes.length > MAX_BINARY_BYTES) {
+        return {
+          code: "UNKNOWN",
+          message: "invalid sessionFs.writeFileBytes base64 content"
+        };
+      }
+      try {
+        await provider.writeFileBytes(path, bytes, mode);
+        return void 0;
       } catch (err) {
         return toSessionFsError(err);
       }
@@ -169,5 +224,6 @@ function toSqliteTransactionError(err) {
 }
 export {
   SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure,
   createSessionFsAdapter
 };

package/dist/types.d.ts

@@ -48,6 +48,7 @@ export type { SessionFsSqliteProvider } from "./sessionFsProvider.js";
 export type { SessionFsSqliteStatement } from "./sessionFsProvider.js";
 export type { SessionFsSqliteTransactionErrorClass } from "./sessionFsProvider.js";
 export { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
+export { SessionFsWriteFailure } from "./sessionFsProvider.js";
 export type { LlmInferenceHeaders } from "./generated/rpc.js";
 export type { PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSurface, PermissionResponseCapability, } from "./generated/rpc.js";
 export type { PermissionDecisionSource } from "./generated/session-events.js";
@@ -922,6 +923,8 @@ export interface SystemMessageReplaceConfig {
 /**
  * Customize mode: Override individual sections of the system prompt.
  * Keeps the SDK-managed prompt structure while allowing targeted modifications.
+ * The `last_instructions` section includes configured subagent-model guidance.
+ * Its overrides and transforms control that prose, not runtime model selection or tool availability.
  */
 export interface SystemMessageCustomizeConfig {
     mode: "customize";
@@ -1098,8 +1101,9 @@ export type AutoModeSwitchHandler = (request: AutoModeSwitchRequest, invocation:
  * Base interface for all hook inputs
  */
 export interface BaseHookInput {
-    /** The runtime session ID of the session that triggered the hook.
-     * For sub-agent hooks this differs from `invocation.sessionId`. */
+    /** The runtime session ID associated with the hook. Child tool hooks use
+     * the child session ID; sub-agent lifecycle hooks use the parent session ID,
+     * matching `invocation.sessionId`. */
     sessionId: string;
     /** Time at which the hook event was emitted by the runtime. */
     timestamp: Date;
@@ -1366,6 +1370,54 @@ export interface AgentStopHookOutput {
 export type AgentStopHandler = (input: AgentStopHookInput, invocation: {
     sessionId: string;
 }) => Promise<AgentStopHookOutput | void> | AgentStopHookOutput | void;
+/**
+ * Input for the hook fired before a sub-agent's first turn.
+ *
+ * The session metadata belongs to the parent session, not the child.
+ */
+export interface SubagentStartHookInput extends BaseHookInput {
+    transcriptPath: string;
+    agentName: string;
+    agentDisplayName?: string;
+    agentDescription?: string;
+}
+/** Output for the sub-agent start hook. Context is prepended to the child's initial prompt. */
+export interface SubagentStartHookOutput {
+    additionalContext?: string;
+}
+/** Handler for the sub-agent start hook. */
+export type SubagentStartHandler = (input: SubagentStartHookInput, invocation: {
+    sessionId: string;
+}) => Promise<SubagentStartHookOutput | void> | SubagentStartHookOutput | void;
+/**
+ * Input for the hook fired after a sub-agent completes a turn.
+ *
+ * The response is the child's last assistant message before any hook rewrite.
+ */
+export interface SubagentStopHookInput extends SubagentStartHookInput {
+    agentId?: string;
+    agentType: string;
+    stopReason: "end_turn";
+    response: string;
+}
+/**
+ * Output for the sub-agent stop hook. `"block"` with a nonempty `reason` continues
+ * the child; otherwise `modifiedResponse` replaces the response reported to the parent.
+ * When both are supplied, a valid block takes precedence over the rewrite.
+ */
+export type SubagentStopHookOutput = {
+    decision: "block";
+    reason: string;
+    modifiedResponse?: string;
+} | {
+    decision?: "allow";
+    reason?: never;
+    modifiedResponse?: string;
+};
+/** Handler for the sub-agent stop hook. */
+export type SubagentStopHandler = (input: SubagentStopHookInput, invocation: {
+    sessionId: string;
+}) => Promise<SubagentStopHookOutput | void> | SubagentStopHookOutput | void;
 /**
  * Configuration for session hooks
  */
@@ -1422,6 +1474,13 @@ export interface SessionHooks {
      * agent stop.
      */
     onAgentStop?: AgentStopHandler;
+    /** Called before a sub-agent's first turn. Return context to prepend to its prompt. */
+    onSubagentStart?: SubagentStartHandler;
+    /**
+     * Called after a sub-agent completes a turn. Return a block reason to
+     * continue the child, or a replacement response to report to the parent.
+     */
+    onSubagentStop?: SubagentStopHandler;
 }
 /**
  * Base interface for MCP server configuration.
@@ -2894,6 +2953,12 @@ export interface SessionFsConfig {
          * @default false
          */
         sqlite?: boolean;
+        /**
+         * Whether this provider supports exact binary reads and writes through readFileBytes and writeFileBytes.
+         * Required to view images stored only in the provider.
+         * @default false
+         */
+        binary?: boolean;
     };
 }
 /**

package/dist/types.js

@@ -1,5 +1,6 @@
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
 import { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
+import { SessionFsWriteFailure } from "./sessionFsProvider.js";
 import {
   CopilotRequestHandler,
   CopilotWebSocketHandler,
@@ -106,10 +107,10 @@ const SYSTEM_MESSAGE_SECTIONS = {
   tool_instructions: { description: "Per-tool usage instructions" },
   custom_instructions: { description: "Repository and organization custom instructions" },
   runtime_instructions: {
-    description: "Runtime-provided context and instructions (e.g. system notifications, memories, workspace context, mode-specific instructions, content-exclusion policy)"
+    description: "Runtime-provided system-prompt context and instructions, such as system notifications, memories, workspace context, and content-exclusion policy. Mode-specific instructions can travel in transition messages instead."
   },
   last_instructions: {
-    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
+    description: "End-of-prompt instructions: parallel tool calling, persistence, task completion, and configured subagent-model guidance when the task tool is available"
   }
 };
 function isAttributedPermissionResult(result) {
@@ -149,6 +150,7 @@ export {
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
   SessionFsSqliteTransactionFailure,
+  SessionFsWriteFailure,
   approveAll,
   convertMcpCallToolResult,
   createAttributedPermissionResult,

package/docs/agent-author.md

@@ -122,10 +122,12 @@ hooks: {
     onSessionStart: async (input, invocation) => { ... },
     onSessionEnd: async (input, invocation) => { ... },
     onErrorOccurred: async (input, invocation) => { ... },
+    onSubagentStart: async (input, invocation) => { ... },
+    onSubagentStop: async (input, invocation) => { ... },
 }
 ```
 
-All hook inputs include `timestamp` (`Date`) and `workingDirectory`.
+All hook inputs include `sessionId`, `timestamp` (`Date`) and `workingDirectory`.
 All handlers receive `invocation: { sessionId: string }` as the second argument.
 All handlers may return `void`/`undefined` (no-op) or an output object.
 
@@ -214,7 +216,32 @@ fire it.
 | `retryCount` | `number` | Max retries (when errorHandling is "retry") |
 | `userNotification` | `string` | Message shown to the user |
 
----
+### onSubagentStart
+
+Fires before a sub-agent's first turn. The input's `sessionId` and the
+invocation's `sessionId` identify the parent session, not the child.
+
+**Input:** `{ sessionId: string, transcriptPath: string, agentName: string, agentDisplayName?: string, agentDescription?: string, timestamp, workingDirectory }`
+
+**Output (optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `additionalContext` | `string` | Prepended to the child's initial prompt |
+
+### onSubagentStop
+
+Fires after a sub-agent completes a turn. The input includes the child's last
+assistant `response` and the parent's session metadata. `agentId` is available
+when the task registry supplies one. This is distinct from `onAgentStop`, which
+only runs for the top-level agent.
+
+**Input:** `{ sessionId: string, transcriptPath: string, agentName: string, agentDisplayName?: string, agentDescription?: string, agentId?: string, agentType: string, stopReason: "end_turn", response: string, timestamp, workingDirectory }`
+
+**Output (choose one, or return nothing):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `decision` and `reason` | `"block"` and `string` | Continue the child for another turn using `reason` |
+| `modifiedResponse` | `string` | Replace the child's response reported to the parent |
 
 ## Session Object
 

package/package.json

@@ -5,8 +5,8 @@
         "url": "https://github.com/github/copilot-agent-runtime.git",
         "directory": "src/sdk/nodejs"
     },
-    "version": "1.0.17-preview.3",
-    "copilotCliVersion": "1.0.92-3",
+    "version": "1.0.17-preview.5",
+    "copilotCliVersion": "1.0.92-5",
     "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
     "main": "./dist/cjs/index.js",
     "types": "./dist/index.d.ts",
@@ -98,22 +98,23 @@
     },
     "files": [
         "dist/**/*",
+        "!dist/tsconfig.tsbuildinfo",
         "docs/**/*",
         "README.md"
     ],
     "copilotRuntime": {
-        "sourceSha": "7a09ab7e985d69cf9f6d446d5c83ae897c7f7daa",
-        "version": "1.0.92-3",
+        "sourceSha": "6d9037e403e4fac0cc65be349f6ab0d9c9351564",
+        "version": "1.0.92-5",
         "visibility": "public"
     },
     "optionalDependencies": {
-        "@github/copilot-sdk-darwin-arm64": "1.0.17-preview.3",
-        "@github/copilot-sdk-darwin-x64": "1.0.17-preview.3",
-        "@github/copilot-sdk-linux-arm64": "1.0.17-preview.3",
-        "@github/copilot-sdk-linux-x64": "1.0.17-preview.3",
-        "@github/copilot-sdk-linuxmusl-arm64": "1.0.17-preview.3",
-        "@github/copilot-sdk-linuxmusl-x64": "1.0.17-preview.3",
-        "@github/copilot-sdk-win32-arm64": "1.0.17-preview.3",
-        "@github/copilot-sdk-win32-x64": "1.0.17-preview.3"
+        "@github/copilot-sdk-darwin-arm64": "1.0.17-preview.5",
+        "@github/copilot-sdk-darwin-x64": "1.0.17-preview.5",
+        "@github/copilot-sdk-linux-arm64": "1.0.17-preview.5",
+        "@github/copilot-sdk-linux-x64": "1.0.17-preview.5",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.17-preview.5",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.17-preview.5",
+        "@github/copilot-sdk-win32-arm64": "1.0.17-preview.5",
+        "@github/copilot-sdk-win32-x64": "1.0.17-preview.5"
     }
 }