@github/copilot-sdk 1.0.9 → 1.0.11-preview.1

package/dist/session.js

@@ -1,14 +1,30 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { ConnectionError, ErrorCodes, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
 import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./telemetry.js";
 import {
+  FACTORY_AGENT_OPTION_KEYS,
   getFactoryDefinition,
   FactoryResumeError,
   isFactoryRunTerminal
 } from "./factory.js";
 function isFactoryResumeErrorCode(value) {
-  return value === "not_found" || value === "non_resumable" || value === "already_active" || value === "reapproval_declined" || value === "no_approval_provider";
+  return value === "not_found" || value === "non_resumable" || value === "already_active" || value === "factory_already_running" || value === "factory_limits_invalid" || value === "factory_session_disposed" || value === "factory_storage_unavailable" || value === "factory_storage_corrupt";
+}
+function copyDefinedFactoryAgentOption(source, target, key) {
+  const value = source[key];
+  if (value !== void 0) {
+    target[key] = value;
+  }
+}
+const factoryExecutionStore = new AsyncLocalStorage();
+function throwIfFactoryExecutionIsActive() {
+  if (factoryExecutionStore.getStore()?.active) {
+    throw new Error(
+      "factory.run and factory.resume are not allowed while a factory body is running on this call path."
+    );
+  }
 }
 function deserializeHookInput(raw) {
   if (!raw || typeof raw !== "object" || typeof raw.timestamp !== "number") {
@@ -129,7 +145,10 @@ class FactoryProgressBuffer {
     const lines = this.pending.splice(0);
     await this.flushTail;
     if (this.flushFailed) {
-      throw this.flushError;
+      console.warn(
+        "Ignoring a background factory progress flush failure after the factory body settled",
+        this.flushError
+      );
     }
     if (lines.length > 0) {
       try {
@@ -160,9 +179,6 @@ class FactoryProgressBuffer {
     }
   }
 }
-function toPublicFactoryRunResult(envelope) {
-  return envelope;
-}
 async function awaitFactoryOperation(operation, signal) {
   let rejectAbort;
   const abortPromise = new Promise((_resolve, reject) => {
@@ -242,6 +258,7 @@ class CopilotSession {
    */
   factory = {
     run: (async (nameOrHandle, options) => {
+      throwIfFactoryExecutionIsActive();
       const name = typeof nameOrHandle === "string" ? nameOrHandle : getFactoryDefinition(nameOrHandle).meta.name;
       if (options?.resumeFromRunId !== void 0) {
         return this.factory.resume(options.resumeFromRunId, {
@@ -258,6 +275,7 @@ class CopilotSession {
       return this.settleFactoryRun(envelope);
     }),
     resume: (async (runId, options) => {
+      throwIfFactoryExecutionIsActive();
       let response;
       try {
         response = await this.rpc.factory.resume({
@@ -275,12 +293,12 @@ class CopilotSession {
       }
       return this.settleFactoryRun(response.run);
     }),
-    getRun: async (runId) => toPublicFactoryRunResult(await this.rpc.factory.getRun({ runId })),
+    getRun: async (runId) => this.rpc.factory.getRun({ runId }),
     waitForRun: (runId, options) => this.waitForFactoryRun(runId, options?.signal),
-    listRuns: async () => (await this.rpc.factory.listRuns()).runs,
+    listRuns: async () => (await this.rpc.factory.listRuns({})).runs,
     getRunDetail: (runId) => this.rpc.factory.getRunDetail({ runId }),
     getRunProgress: (runId, options = {}) => this.rpc.factory.getRunProgress({ runId, ...options }),
-    cancel: async (runId) => toPublicFactoryRunResult(await this.rpc.factory.cancel({ runId }))
+    cancel: async (runId) => this.rpc.factory.cancel({ runId })
   };
   /**
    * Resolve a start/resume envelope into the terminal envelope callers expect.
@@ -291,7 +309,7 @@ class CopilotSession {
    */
   settleFactoryRun(envelope) {
     if (isFactoryRunTerminal(envelope.status)) {
-      return Promise.resolve(toPublicFactoryRunResult(envelope));
+      return Promise.resolve(envelope);
     }
     return this.waitForFactoryRun(envelope.runId);
   }
@@ -345,7 +363,7 @@ class CopilotSession {
             rereadRequested = false;
             const envelope = await this.rpc.factory.getRun({ runId });
             if (isFactoryRunTerminal(envelope.status)) {
-              finish(() => resolve(toPublicFactoryRunResult(envelope)));
+              finish(() => resolve(envelope));
               return;
             }
           } while (rereadRequested && !settled);
@@ -945,16 +963,16 @@ class CopilotSession {
             },
             agent: async (prompt, options = {}) => {
               await progress.flush();
+              const opts = {};
+              for (const key of FACTORY_AGENT_OPTION_KEYS) {
+                copyDefinedFactoryAgentOption(options, opts, key);
+              }
               const response = await awaitFactoryOperation(
                 () => self.rpc.factory.agent({
                   factoryRunId: params.runId,
                   executionToken: params.executionToken,
                   prompt,
-                  opts: {
-                    label: options.label,
-                    schema: options.schema,
-                    model: options.model
-                  }
+                  opts
                 }),
                 controller.signal
               );
@@ -1002,7 +1020,14 @@ class CopilotSession {
               throw new Error("nested factories are not supported");
             }
           };
-          const result = await definition.run(context);
+          const execution = { active: true };
+          const result = await factoryExecutionStore.run(execution, async () => {
+            try {
+              return await definition.run(context);
+            } finally {
+              execution.active = false;
+            }
+          });
           if (result === void 0) {
             return {};
           }

package/dist/types.d.ts

@@ -6,6 +6,7 @@ import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
 import type { PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
+import type { JsonValue } from "./factory.js";
 import type { GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
@@ -355,7 +356,7 @@ export type ToolBinaryResult = {
     type: "image" | "resource";
     description?: string;
 };
-export type ToolTelemetry = Record<string, Record<string, unknown> | undefined>;
+export type ToolTelemetry = Record<string, Record<string, JsonValue> | undefined>;
 export type ToolResultObject = {
     textResultForLlm: string;
     binaryResultsForLlm?: ToolBinaryResult[];
@@ -484,6 +485,17 @@ export interface Tool<TArgs = unknown> {
      * Unknown keys are preserved and round-tripped untouched.
      */
     metadata?: Record<string, unknown>;
+    /**
+     * When true, a successful call to this tool ends the agent turn: the runtime's
+     * tool phase halts instead of feeding the tool result back to the model for
+     * another round. A failed call (for example input validation) leaves the loop
+     * running so the model can read the error and retry.
+     *
+     * Use this for tools whose whole purpose is to terminate the turn, such as a
+     * context clear that replaces the conversation the model would otherwise
+     * continue from.
+     */
+    isTerminal?: boolean;
 }
 /**
  * Helper to define a tool with Zod schema and get type inference for the handler.
@@ -497,6 +509,7 @@ export declare function defineTool<T = unknown>(name: string, config: {
     skipPermission?: boolean;
     defer?: "auto" | "never";
     metadata?: Record<string, unknown>;
+    isTerminal?: boolean;
 }): Tool<T>;
 /**
  * SDK-supplied override for the runtime's built-in tool-search behavior.
@@ -1682,6 +1695,43 @@ export interface GitHubMcpToolConfig {
     enableInsidersMode?: boolean;
     disableFormDeferral?: boolean;
 }
+/**
+ * Permissions-only managed policy injected by the host via
+ * {@link SessionConfigBase.managedSettings}.
+ *
+ * Rule strings use the same vocabulary the runtime accepts for fetched managed
+ * policy (e.g. `"Read(**)"`, `"Shell(git push *)"`); malformed rules are
+ * rejected at session creation.
+ */
+export interface ManagedSettingsPermissions {
+    /**
+     * When set to `"disable"`, bypass-permissions ("yolo") mode is turned off
+     * for the session. This is deny-wins: it cannot be re-enabled by any other
+     * layer.
+     */
+    disableBypassPermissionsMode?: "disable";
+    /** Operations that must always be denied. Unioned across managed layers. */
+    deny?: string[];
+    /**
+     * Operations that must prompt for approval. Unioned across managed layers.
+     */
+    ask?: string[];
+    /**
+     * Operations permitted without prompting. Every declared `allow` list
+     * (across managed layers) must admit an operation for it to be allowed.
+     */
+    allow?: string[];
+}
+/**
+ * Host-injected enterprise managed settings. The first supported contract is
+ * permissions-only; unknown sibling keys are rejected by the runtime.
+ *
+ * @see {@link SessionConfigBase.managedSettings}
+ */
+export interface ManagedSettings {
+    /** Managed permission policy for the session. */
+    permissions?: ManagedSettingsPermissions;
+}
 /**
  * Shared configuration fields used by both {@link SessionConfig} (for
  * creating a new session) and {@link ResumeSessionConfig} (for resuming
@@ -1888,6 +1938,13 @@ export interface SessionConfigBase {
      * @experimental
      */
     enableCitations?: boolean;
+    /**
+     * Opt in to capturing file changes for session rewind and cumulative session
+     * diff. On create, capture starts with the first turn. On resume, this can
+     * enable tracking only when the session still has a valid baseline; it cannot
+     * reconstruct changes from earlier untracked turns.
+     */
+    enableFileChangeTracking?: boolean;
     /**
      * Limits applied to this session's current accounting window.
      *
@@ -2118,6 +2175,30 @@ export interface SessionConfigBase {
      * if omitted, the runtime is expected to reject session creation (fail-closed).
      */
     enableManagedSettings?: boolean;
+    /**
+     * Host-injected enterprise managed settings for this session.
+     *
+     * Unlike {@link SessionConfigBase.enableManagedSettings} — which asks the
+     * runtime to *self-fetch* account/org and device policy — this field lets
+     * the host supply the managed policy directly. The runtime validates it
+     * with the same managed-permission parser it uses for fetched policy and
+     * composes it restrictively with any self-fetched (server) and
+     * device-managed (MDM) layers: `deny`/`ask` rules are unioned, every
+     * declared `allow` list must admit an operation, and
+     * `disableBypassPermissionsMode: "disable"` is deny-wins.
+     *
+     * This is startup-only. It is **not** persisted: it must be re-supplied on
+     * {@link CopilotClient.resumeSession | resume}, where it replaces the prior
+     * injected layer (omitting it clears the layer, so warm and cold resume
+     * behave identically). It may be combined with `enableManagedSettings`;
+     * when both are supplied the injected, server, and device restrictions all
+     * apply.
+     *
+     * Requires a Copilot runtime whose RPC schema includes `managedSettings`.
+     * Older runtimes may ignore this additive field, so hosts must not rely on
+     * injected policy until they ship a compatible runtime.
+     */
+    managedSettings?: ManagedSettings;
     /**
      * When true, skips embedding-based retrieval for this session.
      * Use in multitenant deployments to prevent cross-session information leakage

package/docs/factories.md

@@ -53,7 +53,7 @@ The `run()` context provides:
 
 - `ctx.runId`: Stable ID reused across resumed attempts.
 - `ctx.args`: Invocation arguments, forwarded verbatim. When the caller omits `args`, this is `{}` rather than `undefined`.
-- `ctx.agent(prompt, options?)`: Runs one factory-owned subagent. Options are exactly `label`, `schema`, and `model`. See [Subagent calls](#subagent-calls).
+- `ctx.agent(prompt, options?)`: Runs one factory-owned subagent. Options are exactly `label`, `schema`, `model`, `agent`, `reasoningEffort`, and `contextTier`. See [Subagent calls](#subagent-calls).
 - `ctx.parallel(thunks)`: Runs thunks concurrently and awaits all of them (a barrier). A thunk that throws becomes `null` in the result array, so one failed item does not lose the rest. Cancellation and hard runtime failures (`ResponseError`, `ConnectionError`) are the exception — those propagate and reject the whole call, because they mean the run itself is in trouble rather than one item having failed. Handle them at run level; do not assume every failure arrives as a `null`. Rejects above 4096 items.
 - `ctx.pipeline(items, ...stages)`: Flows each item through every stage without a barrier between stages, so one item can be in a later stage while another is still in an earlier one. Each stage is called as `(previous, item, index)`, where `previous` is the prior stage's result and `item` is the original input. A stage that throws drops that item to `null` and skips its remaining stages, with the same exception for cancellation and hard runtime failures. Rejects above 4096 items.
 - `ctx.phase(title)`: Starts a named progress phase. This sets a single run-global value, so calling it from inside concurrent `parallel`/`pipeline` stages races. Call it at run-level transitions and distinguish concurrent work by `label` instead.
@@ -61,7 +61,7 @@ The `run()` context provides:
 - `ctx.step(key, producer, options?)`: Journals the producer's JSON result under a stable key so a resume replays it without re-running the producer. A journaled (default) producer must return a JSON-serializable value; `undefined` or a non-JSON value is rejected. Pass `{ volatile: true }` to bypass the journal and run the producer every time.
 
   The key is the *sole* identity: neither the producer body nor its inputs contribute to it. A resume replays the cached value for a matching key even if the producer has since changed, so version the key (`"scan-v2"`) whenever its inputs or meaning change. Journaled producers are best-effort at-least-once and may run again across crashes or concurrent same-key callers, so keep side effects idempotent.
-- `ctx.session`: The full session returned by `joinSession`.
+- `ctx.session`: The session returned by `joinSession`. It refuses calls that start or resume a factory run. Call `extensions_manage` with `operation: "guide"` to read more about the session APIs.
 - `ctx.signal`: Cooperative cancellation signal for extension work and subprocesses.
 - `ctx.factory(...)`: Always rejects because nested factories are not supported.
 
@@ -156,7 +156,7 @@ session.factory.resume(
 ): Promise<FactoryRunResult>;
 ```
 
-Both resolve with the run envelope (`FactoryRunResult`) for **every** outcome — `completed`, `error`, `halted`, and `cancelled` alike. Inspect `status` and read `result` only when the run completed; a limit breach carries a typed `failure`. A declined fresh run is not a pre-execution failure: the run row already exists by the time the prompt is answered, so it resolves with a terminal `cancelled` envelope carrying the run ID. Only failures that occur *before* a run exists reject: an unknown factory name or an already-active session. Pre-execution resume failures, including a declined reapproval, throw `FactoryResumeError`, whose `code` is one of `not_found`, `non_resumable`, `already_active`, `reapproval_declined`, or `no_approval_provider`.
+Both resolve with the run envelope (`FactoryRunResult`) for **every** outcome — `completed`, `error`, `halted`, and `cancelled` alike. Inspect `status` and read `result` only when the run completed; a limit breach carries a typed `failure`. SDK-initiated `run` and `resume` do not request permission, so they have no declined outcome. The model's `run_factory` tool requests permission before the durable row exists; declining it creates no run row. An SDK-initiated run is refused only when the session already has its maximum number of active top-level runs. Pre-execution resume failures throw `FactoryResumeError`, whose `code` is one of `not_found`, `non_resumable`, `already_active`, `factory_already_running`, `factory_limits_invalid`, `factory_session_disposed`, `factory_storage_unavailable`, or `factory_storage_corrupt`.
 
 An agent that no longer has a prior run's ID in context can recover it with `factories_manage` and `operation: "runs"`, which lists the session's factory runs with their IDs and statuses. This matters for resume: a run that reached a limit keeps its journal, so resuming it replays completed work for free, while restarting it from scratch pays for that work twice.
 
@@ -210,7 +210,7 @@ const page = await session.factory.getRunProgress(runId, {
 });
 ```
 
-- `listRuns()` returns summaries in durable creation order.
+- `listRuns()` returns the newest default page of this session's durable factory runs.
 - `getRunDetail(runId)` returns phases, prompt-safe agent summaries, and the latest progress page.
 - `getRunProgress(runId, options?)` pages progress forward, backward, by phase, or from the latest tail.
 

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.9",
+  "version": "1.0.11-preview.1",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.78",
+    "@github/copilot": "^1.0.79",
     "koffi": "^3.1.0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"