@github/copilot-sdk 1.0.29-preview.7 → 1.0.29-preview.9

package/dist/session.d.ts

@@ -16,7 +16,7 @@ export type AssistantMessageEvent = Extract<SessionEvent, {
  *
  * @example
  * ```typescript
- * const session = await client.createSession({ model: "gpt-4" });
+ * const session = await client.createSession({ model: "gpt-5.4" });
  *
  * // Subscribe to events
  * session.on((event) => {

package/dist/session.js

@@ -1164,6 +1164,13 @@ class CopilotSession {
       } else if (typeof rawResult === "string") {
         result = rawResult;
       } else if (isToolResultObject(rawResult)) {
+        try {
+          JSON.stringify(rawResult.toolTelemetry);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          throw new Error(`failed to serialize tool telemetry: ${message}`);
+        }
+        JSON.stringify(rawResult);
         result = rawResult;
       } else {
         result = JSON.stringify(rawResult);

package/dist/types.d.ts

@@ -142,14 +142,10 @@ export interface StdioRuntimeConnection extends ChildProcessRuntimeConnection {
  * {@link RuntimeConnection.forInProcess}.
  *
  * @experimental The in-process (FFI) transport is experimental and its behavior may
- * change. Per-client options that are lowered to environment variables — including
- * {@link CopilotClientOptions.env}, {@link CopilotClientOptions.telemetry},
- * {@link CopilotClientOptions.gitHubToken}, and
- * {@link CopilotClientOptions.baseDirectory} — are **not** honored with this
- * transport, because the native runtime loads into the shared host process and its
- * worker inherits that process's ambient environment. To configure the in-process
- * runtime, set the corresponding environment variables on the host process before
- * constructing the client. See https://github.com/github/copilot-sdk/issues/1934.
+ * change. Typed authentication and {@link CopilotClientOptions.baseDirectory}
+ * are scoped to this host. Client-level `env`, `workingDirectory` and
+ * `telemetry` are unsupported; set working directories
+ * on individual sessions.
  */
 export interface InProcessRuntimeConnection {
     readonly kind: "inprocess";
@@ -228,11 +224,9 @@ export declare const RuntimeConnection: {
     /**
      * Host the runtime in-process over the native runtime library's C ABI (FFI).
      *
-     * @experimental Per-client options lowered to environment variables (`env`,
-     * `telemetry`, `gitHubToken`, `baseDirectory`) are **not** honored in-process;
-     * the worker inherits the host process's ambient environment. Set the
-     * corresponding environment variables on the host process instead. See
-     * https://github.com/github/copilot-sdk/issues/1934.
+     * @experimental Runtime configuration from `gitHubToken` and
+     * `baseDirectory` is scoped to this host, not the process environment.
+     * Client-level `env`, `telemetry` and `workingDirectory` are unsupported.
      */
     readonly forInProcess: (options?: Pick<InProcessRuntimeConnection, "runOnUiThread">) => InProcessRuntimeConnection;
 };
@@ -327,6 +321,7 @@ export interface CopilotClientOptions {
     /**
      * Base directory for Copilot data (session state, config, etc.).
      * Sets the COPILOT_HOME environment variable on the spawned runtime.
+     * In-process hosts also keep their runtime cache in this directory's `cache` subdirectory.
      * When not set, the runtime defaults to ~/.copilot.
      * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
      */
@@ -362,6 +357,7 @@ export interface CopilotClientOptions {
     logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
     /**
      * Environment variables to pass to the runtime process. If not set, inherits process.env.
+     * Unsupported with {@link RuntimeConnection.forInProcess}; use typed client/session options.
      */
     env?: Record<string, string | undefined>;
     /**

package/dist/types.js

@@ -38,11 +38,9 @@ const RuntimeConnection = {
   /**
    * Host the runtime in-process over the native runtime library's C ABI (FFI).
    *
-   * @experimental Per-client options lowered to environment variables (`env`,
-   * `telemetry`, `gitHubToken`, `baseDirectory`) are **not** honored in-process;
-   * the worker inherits the host process's ambient environment. Set the
-   * corresponding environment variables on the host process instead. See
-   * https://github.com/github/copilot-sdk/issues/1934.
+   * @experimental Runtime configuration from `gitHubToken` and
+   * `baseDirectory` is scoped to this host, not the process environment.
+   * Client-level `env`, `telemetry` and `workingDirectory` are unsupported.
    */
   forInProcess(options = {}) {
     return { kind: "inprocess", ...options };

package/docs/agent-author.md

@@ -95,7 +95,7 @@ tools: [
             // Return value: string or ToolResultObject
             //   string → treated as success
             //   { textResultForLlm, resultType } → structured result
-            //     resultType: "success" | "failure" | "rejected" | "denied"
+            //     resultType: "success" | "failure" | "rejected" | "denied" | "timeout"
             return `Result: ${args.arg1}`;
         },
     },
@@ -105,7 +105,7 @@ tools: [
 **Constraints:**
 
 - Tool names must be unique across ALL loaded extensions. Collisions cause the second extension to fail to load.
-- Handler must return a string or `{ textResultForLlm: string, resultType?: string }`.
+- Handler must return a string or `{ textResultForLlm: string, resultType: "success" | "failure" | "rejected" | "denied" | "timeout" }`. `resultType` is required: an object without a recognized `resultType` is not a structured result, and the model receives it serialized as JSON text.
 - Handler receives `(args, invocation)` — the second argument has `sessionId`, `toolCallId`, `toolName`.
 - Use `session.log()` to surface messages to the user. Don't use `console.log()` (stdout is reserved for JSON-RPC).
 
@@ -116,12 +116,15 @@ tools: [
 ```js
 hooks: {
     onUserPromptSubmitted: async (input, invocation) => { ... },
+    onUserPromptTransformed: async (input, invocation) => { ... },
     onPreToolUse: async (input, invocation) => { ... },
+    onPreMcpToolCall: async (input, invocation) => { ... },
     onPostToolUse: async (input, invocation) => { ... },
     onPostToolUseFailure: async (input, invocation) => { ... },
     onSessionStart: async (input, invocation) => { ... },
     onSessionEnd: async (input, invocation) => { ... },
     onErrorOccurred: async (input, invocation) => { ... },
+    onAgentStop: async (input, invocation) => { ... },
     onSubagentStart: async (input, invocation) => { ... },
     onSubagentStop: async (input, invocation) => { ... },
 }
@@ -143,6 +146,20 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 | `decision` | `"block"` | Refuses the prompt: no model turn runs and no user message is recorded |
 | `reason` | `string` | Why the prompt was blocked, carried by the ephemeral `session.warning` (`warningType: "policy_blocked"`) |
 
+### onUserPromptTransformed
+
+Fires after the runtime adds generated context to the submitted prompt, before
+the result is stored in session history or sent to the model. `prompt` is the
+prompt after `onUserPromptSubmitted`; `transformedPrompt` also carries the
+runtime-generated context.
+
+**Input:** `{ prompt: string, transformedPrompt: string, timestamp, workingDirectory }`
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `modifiedTransformedPrompt` | `string` | Replaces the content stored in session history and sent to the model |
+
 ### onPreToolUse
 
 **Input:** `{ toolName: string, toolArgs: unknown, timestamp, workingDirectory }`
@@ -155,6 +172,19 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 | `modifiedArgs` | `unknown` | Replaces the tool arguments |
 | `additionalContext` | `string` | Injected into the conversation |
 
+### onPreMcpToolCall
+
+Fires before a tool call is sent to an MCP server. It controls only the `_meta`
+object sent with the request; to allow, deny or change the call itself, use
+`onPreToolUse`.
+
+**Input:** `{ toolCallId?: string, serverName: string, toolName: string, arguments: unknown, _meta?: Record<string, unknown>, timestamp, workingDirectory }`
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `metaToUse` | `Record<string, unknown> \| null` | An object becomes the request's `_meta`; `null` omits it; leaving it out keeps the current `_meta` |
+
 ### onPostToolUse
 
 **Input:** `{ toolName: string, toolArgs: unknown, toolResult: ToolResultObject, timestamp, workingDirectory }`
@@ -218,6 +248,23 @@ fire it.
 | `retryCount` | `number` | Max retries (when errorHandling is "retry") |
 | `userNotification` | `string` | Message shown to the user |
 
+### onAgentStop
+
+Fires when the top-level agent reaches a natural terminal stop: it went idle
+without pending work and was not aborted. Sub-agents fire `onSubagentStop`
+instead.
+
+**Input:** `{ stopReason?: string, transcriptPath?: string, stopHookActive?: boolean, timestamp, workingDirectory }`
+
+`stopHookActive` is `true` when this stop follows an earlier `"block"` from this
+hook; check it to avoid blocking indefinitely. The runtime also caps
+consecutive blocks.
+
+**Output (optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `decision` and `reason` | `"block"` and `string` | Keep the agent running; `reason` is enqueued as its next user message |
+
 ### onSubagentStart
 
 Fires before a sub-agent's first turn. The input's `sessionId` and the

package/docs/examples.md

@@ -152,15 +152,20 @@ 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 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)  |
+| Hook                      | Fires When                                   | Can Modify                                  |
+| ------------------------- | -------------------------------------------- | ------------------------------------------- |
+| `onUserPromptSubmitted`   | User sends a message                         | The prompt text, add context                |
+| `onUserPromptTransformed` | Runtime has transformed the submitted prompt | The transformed prompt                      |
+| `onPreToolUse`            | Before a tool executes                       | Tool args, permission decision, add context |
+| `onPreMcpToolCall`        | Before an MCP tool call is sent              | The request's `_meta`                       |
+| `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)  |
+| `onAgentStop`             | Top-level agent naturally stops              | Block the stop and request another turn     |
+| `onSubagentStart`         | Before a sub-agent's first turn              | Add context to its prompt                   |
+| `onSubagentStop`          | After a sub-agent completes a turn           | Request another turn, replace its response  |
 
 All hook inputs include `timestamp` (`Date`) and `workingDirectory`.
 

package/docs/workflows.md

@@ -225,7 +225,6 @@ Observation does not restore execution eligibility. Starting, resuming, pausing,
 ```ts
 const runs = await session.workflow.listRuns();
 const runsPage = await session.workflow.listRuns({
-    afterSeq,
     beforeSeq,
     limit,
 });
@@ -233,15 +232,15 @@ const detail = await session.workflow.getRunDetail(runId);
 const progressPage = await session.workflow.getRunProgress(runId, {
     phaseId,
     afterSeq,
-    beforeSeq,
     limit,
 });
 ```
 
 - `listRuns()` returns only the runs array from the newest default page of this session's durable workflow runs. This overload preserves the original convenience API.
-- `listRuns({ afterSeq, beforeSeq, limit })` returns the full page. Its `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` fields let callers continue paging without raw RPC calls.
+- `listRuns({ afterSeq, limit })` or `listRuns({ beforeSeq, limit })` returns the full page. Its `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` fields let callers continue paging without raw RPC calls.
 - `getRunDetail(runId)` returns phases, prompt-safe agent summaries, and the latest progress page. Each current-runtime agent summary includes `consumedNanoAiu`, the known spend from that direct agent and its descendants. Older runtimes omit the field, and historical agents without attributable charge rows also omit it when the run contains unattributed spend.
 - `getRunProgress(runId, options?)` pages progress forward, backward, by phase, or from the latest tail.
+- Both paging calls take at most one cursor: `afterSeq` pages forward and `beforeSeq` pages backward, each exclusive of the given sequence number. A request with both fails with JSON-RPC `-32602` and `data.code: "workflow_runs_invalid_cursor"` from `listRuns`, or `"workflow_progress_invalid_cursor"` from `getRunProgress`.
 
 `getRun(runId)` reads the latest run envelope. `pause(runId)` pauses a running attempt and returns its `paused` envelope. `cancel(runId)` cancels a run and returns its terminal envelope.
 

package/package.json

@@ -5,8 +5,8 @@
         "url": "https://github.com/github/copilot-agent-runtime.git",
         "directory": "src/sdk/nodejs"
     },
-    "version": "1.0.29-preview.7",
-    "copilotCliVersion": "1.0.106-8",
+    "version": "1.0.29-preview.9",
+    "copilotCliVersion": "1.0.106-10",
     "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
     "main": "./dist/cjs/index.js",
     "types": "./dist/index.d.ts",
@@ -68,7 +68,7 @@
     "author": "GitHub",
     "license": "MIT",
     "dependencies": {
-        "koffi": "3.3.3",
+        "koffi": "3.3.4",
         "vscode-jsonrpc": "10.0.0",
         "zod": "4.6.7"
     },
@@ -117,18 +117,18 @@
         "README.md"
     ],
     "copilotRuntime": {
-        "sourceSha": "fc20da543d03b6522fc0ac5fefc724be82045156",
-        "version": "1.0.106-8",
+        "sourceSha": "b3da66080b3d00711a816a990fdaf6308ff17a1f",
+        "version": "1.0.106-10",
         "visibility": "public"
     },
     "optionalDependencies": {
-        "@github/copilot-sdk-darwin-arm64": "1.0.29-preview.7",
-        "@github/copilot-sdk-darwin-x64": "1.0.29-preview.7",
-        "@github/copilot-sdk-linux-arm64": "1.0.29-preview.7",
-        "@github/copilot-sdk-linux-x64": "1.0.29-preview.7",
-        "@github/copilot-sdk-linuxmusl-arm64": "1.0.29-preview.7",
-        "@github/copilot-sdk-linuxmusl-x64": "1.0.29-preview.7",
-        "@github/copilot-sdk-win32-arm64": "1.0.29-preview.7",
-        "@github/copilot-sdk-win32-x64": "1.0.29-preview.7"
+        "@github/copilot-sdk-darwin-arm64": "1.0.29-preview.9",
+        "@github/copilot-sdk-darwin-x64": "1.0.29-preview.9",
+        "@github/copilot-sdk-linux-arm64": "1.0.29-preview.9",
+        "@github/copilot-sdk-linux-x64": "1.0.29-preview.9",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.29-preview.9",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.29-preview.9",
+        "@github/copilot-sdk-win32-arm64": "1.0.29-preview.9",
+        "@github/copilot-sdk-win32-x64": "1.0.29-preview.9"
     }
 }