@github/copilot-sdk 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/types.js

@@ -1,4 +1,32 @@
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
+const RuntimeConnection = {
+  /**
+   * Spawn a runtime child process and communicate over its stdin/stdout.
+   * This is the default if no {@link CopilotClientOptions.connection} is set.
+   */
+  forStdio(opts = {}) {
+    return { kind: "stdio", path: opts.path, args: opts.args };
+  },
+  /**
+   * Spawn a runtime child process that listens on a TCP socket and connect to it.
+   */
+  forTcp(opts = {}) {
+    return {
+      kind: "tcp",
+      port: opts.port,
+      connectionToken: opts.connectionToken,
+      path: opts.path,
+      args: opts.args
+    };
+  },
+  /**
+   * Connect to an already-running runtime at the given URL. The SDK does not
+   * spawn a process in this mode.
+   */
+  forUri(url, opts = {}) {
+    return { kind: "uri", url, connectionToken: opts.connectionToken };
+  }
+};
 function convertMcpCallToolResult(callResult) {
   const textParts = [];
   const binaryResults = [];
@@ -23,9 +51,10 @@ function convertMcpCallToolResult(callResult) {
           textParts.push(block.resource.text);
         }
         if (block.resource?.blob) {
+          const mimeType = block.resource.mimeType;
           binaryResults.push({
             data: block.resource.blob,
-            mimeType: block.resource.mimeType ?? "application/octet-stream",
+            mimeType: typeof mimeType === "string" && mimeType ? mimeType : "application/octet-stream",
             type: "resource",
             description: block.resource.uri
           });
@@ -43,7 +72,7 @@ function convertMcpCallToolResult(callResult) {
 function defineTool(name, config) {
   return { name, ...config };
 }
-const SYSTEM_PROMPT_SECTIONS = {
+const SYSTEM_MESSAGE_SECTIONS = {
   identity: { description: "Agent identity preamble and mode statement" },
   tone: { description: "Response style, conciseness rules, output formatting preferences" },
   tool_efficiency: { description: "Tool usage patterns, parallel calling, batching guidelines" },
@@ -53,6 +82,9 @@ const SYSTEM_PROMPT_SECTIONS = {
   safety: { description: "Environment limitations, prohibited actions, security policies" },
   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)"
+  },
   last_instructions: {
     description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
   }
@@ -62,7 +94,8 @@ const defaultJoinSessionPermissionHandler = () => ({
   kind: "no-result"
 });
 export {
-  SYSTEM_PROMPT_SECTIONS,
+  RuntimeConnection,
+  SYSTEM_MESSAGE_SECTIONS,
   approveAll,
   convertMcpCallToolResult,
   createSessionFsAdapter,

package/docs/agent-author.md

@@ -118,19 +118,20 @@ hooks: {
     onUserPromptSubmitted: async (input, invocation) => { ... },
     onPreToolUse: async (input, invocation) => { ... },
     onPostToolUse: async (input, invocation) => { ... },
+    onPostToolUseFailure: async (input, invocation) => { ... },
     onSessionStart: async (input, invocation) => { ... },
     onSessionEnd: async (input, invocation) => { ... },
     onErrorOccurred: async (input, invocation) => { ... },
 }
 ```
 
-All hook inputs include `timestamp` (unix ms) and `cwd` (working directory).
+All hook inputs include `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.
 
 ### onUserPromptSubmitted
 
-**Input:** `{ prompt: string, timestamp, cwd }`
+**Input:** `{ prompt: string, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -140,7 +141,7 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ### onPreToolUse
 
-**Input:** `{ toolName: string, toolArgs: unknown, timestamp, cwd }`
+**Input:** `{ toolName: string, toolArgs: unknown, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -152,7 +153,10 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ### onPostToolUse
 
-**Input:** `{ toolName: string, toolArgs: unknown, toolResult: ToolResultObject, timestamp, cwd }`
+**Input:** `{ toolName: string, toolArgs: unknown, toolResult: ToolResultObject, timestamp, workingDirectory }`
+
+Fires only when the tool returned a successful result. To observe non-success
+outcomes, register `onPostToolUseFailure` as well.
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -160,9 +164,29 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 | `modifiedResult` | `ToolResultObject` | Replaces the tool result |
 | `additionalContext` | `string` | Injected into the conversation |
 
+### onPostToolUseFailure
+
+**Input:** `{ toolName: string, toolArgs: unknown, error: string, timestamp, workingDirectory }`
+
+Fires after a tool execution whose result was `"failure"`. `onPostToolUse`
+does **not** fire for these outcomes, so register this handler to observe or
+react to them — useful for telemetry, replay buffers, fault-injection tests,
+or pairing pre/post tool tracking that would otherwise leak when the tool
+fails. Note the input shape differs from `onPostToolUse`: only `error` (the
+stringified failure message) is provided, not the full `toolResult`.
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `additionalContext` | `string` | Appended as hidden guidance the model sees alongside the failed tool result |
+
+Note: only `"failure"` results trigger this hook. Other non-success
+`resultType` values (`"rejected"`, `"denied"`, `"timeout"`) do not currently
+fire it.
+
 ### onSessionStart
 
-**Input:** `{ source: "startup" \| "resume" \| "new", initialPrompt?: string, timestamp, cwd }`
+**Input:** `{ source: "startup" \| "resume" \| "new", initialPrompt?: string, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -171,7 +195,7 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ### onSessionEnd
 
-**Input:** `{ reason: "complete" \| "error" \| "abort" \| "timeout" \| "user_exit", finalMessage?: string, error?: string, timestamp, cwd }`
+**Input:** `{ reason: "complete" \| "error" \| "abort" \| "timeout" \| "user_exit", finalMessage?: string, error?: string, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |
@@ -181,7 +205,7 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ### onErrorOccurred
 
-**Input:** `{ error: string, errorContext: "model_call" \| "tool_execution" \| "system" \| "user_input", recoverable: boolean, timestamp, cwd }`
+**Input:** `{ error: string, errorContext: "model_call" \| "tool_execution" \| "system" \| "user_input", recoverable: boolean, timestamp, workingDirectory }`
 
 **Output (all fields optional):**
 | Field | Type | Effect |

package/docs/examples.md

@@ -152,16 +152,17 @@ Hooks intercept and modify behavior at key lifecycle points. Register them in th
 
 ### Available Hooks
 
-| Hook                    | Fires When                | Can Modify                                  |
-| ----------------------- | ------------------------- | ------------------------------------------- |
-| `onUserPromptSubmitted` | User sends a message      | The prompt text, add context                |
-| `onPreToolUse`          | Before a tool executes    | Tool args, permission decision, add context |
-| `onPostToolUse`         | After a tool executes     | Tool result, add context                    |
-| `onSessionStart`        | Session starts or resumes | Add context, modify config                  |
-| `onSessionEnd`          | Session ends              | Cleanup actions, summary                    |
-| `onErrorOccurred`       | An error occurs           | Error handling strategy (retry/skip/abort)  |
-
-All hook inputs include `timestamp` (unix ms) and `cwd` (working directory).
+| Hook                    | Fires When                               | Can Modify                                  |
+| ----------------------- | ---------------------------------------- | ------------------------------------------- |
+| `onUserPromptSubmitted` | User sends a message                     | The prompt text, add context                |
+| `onPreToolUse`          | Before a tool executes                   | Tool args, permission decision, add context |
+| `onPostToolUse`         | After a tool executes successfully       | Tool result, add context                    |
+| `onPostToolUseFailure`  | After a tool execution returns a failure | Add hidden guidance to the model            |
+| `onSessionStart`        | Session starts or resumes                | Add context                                 |
+| `onSessionEnd`          | Session ends                             | Cleanup actions, summary                    |
+| `onErrorOccurred`       | An error occurs                          | Error handling strategy (retry/skip/abort)  |
+
+All hook inputs include `timestamp` (`Date`) and `workingDirectory`.
 
 ### Modifying the user's message
 
@@ -267,12 +268,18 @@ hooks: {
 }
 ```
 
-### Augmenting tool results with extra context
+### Reacting when a tool fails
+
+`onPostToolUse` only fires for successful tool executions. To observe or react
+to failures, register `onPostToolUseFailure`. The input includes
+`input.error` (the stringified failure message); only `additionalContext` on
+the return value is consumed by the runtime, and it is appended as hidden
+guidance alongside the failed tool result.
 
 ```js
 hooks: {
-    onPostToolUse: async (input) => {
-        if (input.toolName === "bash" && input.toolResult?.resultType === "failure") {
+    onPostToolUseFailure: async (input) => {
+        if (input.toolName === "bash") {
             return {
                 additionalContext: "The command failed. Try a different approach.",
             };
@@ -408,7 +415,7 @@ session.on("assistant.message", (event) => {
 | Event Type                  | Description                                      | Key Data Fields                                        |
 | --------------------------- | ------------------------------------------------ | ------------------------------------------------------ |
 | `assistant.message`         | Agent's final response                           | `content`, `messageId`, `toolRequests`                 |
-| `assistant.streaming_delta` | Token-by-token streaming (ephemeral)             | `totalResponseSizeBytes`                               |
+| `assistant.message_delta`   | Message content chunks (ephemeral)               | `deltaContent`                                         |
 | `tool.execution_start`      | A tool is about to run                           | `toolCallId`, `toolName`, `arguments`                  |
 | `tool.execution_complete`   | A tool finished running                          | `toolCallId`, `toolName`, `success`, `result`, `error` |
 | `user.message`              | User sent a message                              | `content`, `attachments`, `source`                     |
@@ -561,12 +568,12 @@ const session = await joinSession({
     onPermissionRequest: async (request) => {
         if (request.kind === "shell") {
             // request.fullCommandText has the shell command
-            return { kind: "approved" };
+            return { kind: "approve-once" };
         }
         if (request.kind === "write") {
-            return { kind: "approved" };
+            return { kind: "approve-once" };
         }
-        return { kind: "denied-by-rules" };
+        return { kind: "reject" };
     },
 });
 ```
@@ -622,8 +629,11 @@ const session = await joinSession({
         onPreToolUse: async (input) => {
             if (input.toolName === "bash") {
                 const cmd = String(input.toolArgs?.command || "");
-                if (/rm\\s+-rf\\s+\\/ / i.test(cmd) || /Remove-Item\\s+.*-Recurse/i.test(cmd)) {
-                    return { permissionDecision: "deny" };
+                if (/rm\\s+-rf\\s+\//i.test(cmd) || /Remove-Item\\s+.*-Recurse/i.test(cmd)) {
+                    return {
+                        permissionDecision: "deny",
+                        permissionDecisionReason: "Destructive commands are not allowed.",
+                    };
                 }
             }
         },

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.11",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -40,11 +40,11 @@
     "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\" --ignore-path .prettierignore",
     "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
     "lint:fix": "eslint --fix \"src/**/*.ts\" \"test/**/*.ts\"",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "generate": "cd ../scripts/codegen && npm run generate",
     "update:protocol-version": "tsx scripts/update-protocol-version.ts",
     "prepublishOnly": "npm run build",
-    "package": "npm run clean && npm run build && node scripts/set-version.js && npm pack && npm version 0.1.0 --no-git-tag-version --allow-same-version"
+    "package": "npm run clean && npm run build && node scripts/set-version.js && npm pack && npm version 0.0.0-dev --no-git-tag-version --allow-same-version"
   },
   "keywords": [
     "github",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.41-0",
+    "@github/copilot": "^1.0.57",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },