@github/copilot-sdk 1.0.21 → 1.0.22-preview.0

package/README.md

@@ -375,6 +375,7 @@ Create a new conversation session.
 - `workingDirectory?: string` - Working directory for the session (default: runtime process cwd).
 - `refreshCustomInstructions?: boolean` - Invalidates the process-wide custom-instruction discovery cache before creating this session, so instruction-file edits made in the same runtime are read again. Defaults to `false` (cache reuse). Other sessions in this runtime may observe updated instructions on later turns or discovery. This does not watch files or enable disabled instruction loading. Available on `SessionConfig`, not `ResumeSessionConfig`.
 - `enableSessionStore?: boolean` - Enables the cross-session store for search and retrieval across sessions. When unset in `"copilot-cli"` mode, the runtime default applies (enabled). In `"empty"` mode, defaults to disabled.
+- `enableGitHubCacheStore?: boolean` - Requests the read-only GitHub cache store (`github-cache-store` capability) on create or resume. The runtime registers the `github_sql` tool only when its `GITHUB_CACHE_STORE` feature flag is also on. Defaults to disabled in every mode.
 - `gitHubTokenProvider?: GitHubTokenProvider` - Acquires rotating, session-scoped GitHub tokens. Token results require a positive `expiresIn` value in seconds remaining when the callback completes; production tokens typically last eight hours. Cannot be combined with `gitHubToken`.
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
 - `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. `approveAll` approves requests when managed settings are disabled and throws when `enableManagedSettings` is true. Custom handlers can inspect `managedApprovalRequired` for human-facing confirmation logic. See [Permission Handling](#permission-handling) section.

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.97";
+const COPILOT_CLI_VERSION = "1.0.98-0";
 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

@@ -1375,6 +1375,7 @@ class CopilotClient {
         enableFileHooks: config.enableFileHooks,
         enableHostGitOperations: config.enableHostGitOperations,
         enableSessionStore: config.enableSessionStore,
+        enableGitHubCacheStore: config.enableGitHubCacheStore,
         enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
         ...config.skillProvider ? { hasSkillProvider: true } : {},
@@ -1633,6 +1634,7 @@ class CopilotClient {
         enableFileHooks: config.enableFileHooks,
         enableHostGitOperations: config.enableHostGitOperations,
         enableSessionStore: config.enableSessionStore,
+        enableGitHubCacheStore: config.enableGitHubCacheStore,
         enableSkills: config.enableSkills,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,

package/dist/cjs/generated/rpc.js

@@ -265,6 +265,17 @@ function createServerRpc(connection) {
       getBuiltInCatalog: async () => connection.sendRequest("models.getBuiltInCatalog", {})
     },
     /** @experimental */
+    contentExclusion: {
+      /**
+       * Validates candidate content-exclusion policies and returns them normalized, without starting a session. This runs the same parser the runtime's own policy enforcement uses, so a host cannot accept a policy set the runtime would later reject, nor reject one it would have honored. Call it when policies arrive from outside the runtime — a command-line flag, a configuration file, a host's own settings — and must be checked before a session exists to apply them to. A malformed document fails with a message prefixed `Invalid JSON: `; a well-formed document that violates the policy schema fails with the offending field paths.
+       *
+       * @param params Candidate content-exclusion policies to validate, as the raw JSON text a host received. The text is supplied unparsed so that a syntax error and a schema violation are both reported by the runtime's own validator rather than by the caller's JSON parser.
+       *
+       * @returns The accepted policies, parsed and normalized. A rejected input is reported as an error rather than in this result.
+       */
+      validatePolicies: async (params) => connection.sendRequest("contentExclusion.validatePolicies", params)
+    },
+    /** @experimental */
     tools: {
       /**
        * Lists built-in tools available for a model.

package/dist/cjs/session.js

@@ -75,6 +75,20 @@ function deserializeHookInput(raw) {
     ...stop_hook_active === void 0 ? {} : { stopHookActive: stop_hook_active }
   };
 }
+function normalizeHookError(hookType, input) {
+  if (hookType !== "errorOccurred" && hookType !== "sessionEnd") {
+    return input;
+  }
+  if (!input || typeof input !== "object" || !("error" in input)) {
+    return input;
+  }
+  const { error } = input;
+  if (!error || typeof error !== "object" || Array.isArray(error)) {
+    return input;
+  }
+  const { message } = error;
+  return { ...input, error: typeof message === "string" ? message : JSON.stringify(error) };
+}
 function isOpenCanvasInstance(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -1793,7 +1807,7 @@ class CopilotSession {
     if (!this.hooks) {
       return void 0;
     }
-    const normalized = deserializeHookInput(input);
+    const normalized = normalizeHookError(hookType, deserializeHookInput(input));
     const handlerMap = {
       preToolUse: this.hooks.onPreToolUse,
       preMcpToolCall: this.hooks.onPreMcpToolCall,

package/dist/cliVersion.d.ts

@@ -1,2 +1,2 @@
-export declare const COPILOT_CLI_VERSION = "1.0.97";
+export declare const COPILOT_CLI_VERSION = "1.0.98-0";
 export declare const COPILOT_CLI_USE_NPM_PACKAGE = false;

package/dist/cliVersion.js

@@ -1,4 +1,4 @@
-const COPILOT_CLI_VERSION = "1.0.97";
+const COPILOT_CLI_VERSION = "1.0.98-0";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 export {
   COPILOT_CLI_USE_NPM_PACKAGE,

package/dist/client.js

@@ -1355,6 +1355,7 @@ class CopilotClient {
         enableFileHooks: config.enableFileHooks,
         enableHostGitOperations: config.enableHostGitOperations,
         enableSessionStore: config.enableSessionStore,
+        enableGitHubCacheStore: config.enableGitHubCacheStore,
         enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
         ...config.skillProvider ? { hasSkillProvider: true } : {},
@@ -1613,6 +1614,7 @@ class CopilotClient {
         enableFileHooks: config.enableFileHooks,
         enableHostGitOperations: config.enableHostGitOperations,
         enableSessionStore: config.enableSessionStore,
+        enableGitHubCacheStore: config.enableGitHubCacheStore,
         enableSkills: config.enableSkills,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,

package/dist/generated/rpc.d.ts

@@ -622,6 +622,80 @@ export type CatalogAgentPluginCompatibilityTag =
  | "canvas-only"
 /** The plugin targets GitHub Copilot. */
  | "github-copilot";
+/**
+ * Typed installability state for an Agent Plugin candidate
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginInstallability".
+ */
+/** @experimental */
+export type CatalogAgentPluginInstallability = 
+/** The candidate carries complete, verified install data and the selected session may install it. Its install plan is present. */
+"installable"
+/** The catalogue supplied no complete, verified install data, so no install target is offered. */
+ | "install-data-unavailable"
+/** Plugin installation is understood but disabled for the selected session. */
+ | "feature-disabled"
+/** Reserved for plugin formats this runtime cannot install. Every format surfaced today installs through a marketplace. */
+ | "not-installable-kind";
+/**
+ * One place an Agent Plugin can install from: Agent Finder's materialisation, a marketplace, or a GitHub repository. Each variant carries only its own fields.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginInstallSource".
+ */
+/** @experimental */
+export type CatalogAgentPluginInstallSource = CatalogAgentPluginMaterializationSource | CatalogAgentPluginMarketplaceSource | CatalogAgentPluginRepositorySource;
+/**
+ * Discriminator for a materialisation install source
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginMaterializationSourceKind".
+ */
+/** @experimental */
+export type CatalogAgentPluginMaterializationSourceKind = 
+/** Install from Agent Finder's verified materialisation. */
+"materialization";
+/**
+ * Discriminator for a marketplace install source
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginMarketplaceSourceKind".
+ */
+/** @experimental */
+export type CatalogAgentPluginMarketplaceSourceKind = "marketplace";
+/**
+ * Discriminator for a repository install source
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginRepositorySourceKind".
+ */
+/** @experimental */
+export type CatalogAgentPluginRepositorySourceKind = "repository";
+/**
+ * A kind of component an Agent Plugin contributes
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginComponent".
+ */
+/** @experimental */
+export type CatalogAgentPluginComponent = 
+/** Custom agents. */
+"agent"
+/** Slash commands. */
+ | "command"
+/** Skills. */
+ | "skill"
+/** Hooks. */
+ | "hook"
+/** Bundled MCP servers. */
+ | "mcp-server"
+/** Bundled LSP servers. */
+ | "lsp-server"
+/** Extensions. */
+ | "extension"
+/** Canvases. */
+ | "canvas";
 /**
  * A versioned, bounded trust observation carried unchanged with a catalog candidate and its private handle context. Current observations require a recognised T1/T2 tier; every non-current state structurally forbids a tier. Eligibility remains `unknown` while Agent Finder supplies no exposure decision, and states absent from its current wire are never inferred from age, relevance, popularity, or a tier transition.
  *
@@ -887,7 +961,9 @@ export type CatalogCapability =
 /** Extends mcp-confirmed-remote-installation to declared non-secret header and URL values and receipt-owned header secrets for personal remote MCP choices. Requires mcp-confirmed-remote-installation and bound session authority. Secret values are written only to the reviewed backend after confirmation and are never returned; package and stdio choices remain unsupported. Advertised only when owned secret effects and owned secret activation are linked. */
  | "mcp-configured-remote-installation"
 /** Understands verified Agent Finder Skill install, uninstall, recovery and installation-scoped enablement APIs. Advertised only by runtimes with the Skill installation engine linked; acquisition may still be refused as feature-disabled per selected session. */
- | "skill-confirmed-installation";
+ | "skill-confirmed-installation"
+/** Understands `installability` and the reviewable `installPlan` on Agent Plugin candidates. Requires agent-plugin-discovery; without it, plugin candidates are unchanged. A plugin is installable only with complete, verified catalogue install data, and may still be reported as feature-disabled per selected session. */
+ | "agent-plugin-confirmed-installation";
 /**
  * Bounded extensible wire-feature identifier. Known values are described by `CatalogCapability`; newer callers may send future identifiers so an older runtime can return a typed negotiation refusal instead of failing schema validation. Capability negotiation establishes contract understanding, while each operation's result separately reports runtime availability.
  *
@@ -4394,6 +4470,8 @@ export type SessionCapability =
  | "elicitation"
 /** Cross-session history tools and session-store SQL prompt/tool metadata. */
  | "session-store"
+/** Read-only GitHub cache SQL tool (github_sql). */
+ | "github-cache-store"
 /** MCP Apps UI passthrough. */
  | "mcp-apps"
 /** Host-provided canvas rendering support. */
@@ -8214,6 +8292,8 @@ export interface CatalogAgentPluginCandidate {
     compatibilityTags: ({
         [k: string]: unknown | undefined;
     } & []) | [CatalogAgentPluginCompatibilityTag] | [CatalogAgentPluginCompatibilityTag, CatalogAgentPluginCompatibilityTag] | [CatalogAgentPluginCompatibilityTag, CatalogAgentPluginCompatibilityTag, CatalogAgentPluginCompatibilityTag];
+    installability?: CatalogAgentPluginInstallability;
+    installPlan?: CatalogAgentPluginInstallPlan;
     provenance: CatalogAgentPluginCandidateProvenance;
     trust?: CatalogTrustSnapshot;
 }
@@ -8234,6 +8314,99 @@ export interface CatalogPluginRepositorySource {
      */
     path: string;
 }
+/**
+ * What installing an Agent Plugin would do, for the user to review and confirm. Provisional: the catalogue install data it is built from is not final.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginInstallPlan".
+ */
+/** @experimental */
+export interface CatalogAgentPluginInstallPlan {
+    /**
+     * Every valid install source, in preference order: materialization, then marketplace, then repository. Each kind appears at most once.
+     *
+     * @minItems 1
+     * @maxItems 3
+     */
+    sources: [CatalogAgentPluginInstallSource] | [CatalogAgentPluginInstallSource, CatalogAgentPluginInstallSource] | [CatalogAgentPluginInstallSource, CatalogAgentPluginInstallSource, CatalogAgentPluginInstallSource];
+    /**
+     * The plugin's name, as named in its marketplace or manifest.
+     */
+    pluginName: string;
+    version?: CatalogResourceVersion;
+    /**
+     * Exact full commit ID to install, in lowercase hex. Always present when the plan has a repository source; a plan with a marketplace source carries at least one of version and commit.
+     */
+    commit?: string;
+    /**
+     * Components the plugin contributes, in canonical order.
+     *
+     * @minItems 1
+     */
+    components: [CatalogAgentPluginComponent, ...CatalogAgentPluginComponent[]];
+    /**
+     * Canvas IDs the plugin contributes. Non-empty exactly when components include `canvas`.
+     */
+    canvasIds: string[];
+    /**
+     * Extension IDs the plugin contributes. Non-empty exactly when components include `extension`.
+     */
+    extensionIds: string[];
+    /**
+     * MCP servers the plugin depends on but does not bundle.
+     */
+    mcpDependencies: string[];
+    /**
+     * Connectors the plugin depends on.
+     */
+    connectorDependencies: string[];
+}
+/**
+ * Agent Finder's verified materialisation of the plugin. Present only when the candidate carries a complete materialisation reference; the reference itself stays runtime-private.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginMaterializationSource".
+ */
+/** @experimental */
+export interface CatalogAgentPluginMaterializationSource {
+    kind: CatalogAgentPluginMaterializationSourceKind;
+}
+/**
+ * A plugin marketplace named by verified catalogue install data, installed as `pluginName@name`.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginMarketplaceSource".
+ */
+/** @experimental */
+export interface CatalogAgentPluginMarketplaceSource {
+    kind: CatalogAgentPluginMarketplaceSourceKind;
+    /**
+     * Marketplace name.
+     */
+    name: string;
+    /**
+     * Canonical lowercase GitHub owner/repository hosting the marketplace.
+     */
+    repository: string;
+}
+/**
+ * A GitHub repository holding the plugin, installed directly as `owner/repo[:path]` at the plan's commit, without a marketplace.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogAgentPluginRepositorySource".
+ */
+/** @experimental */
+export interface CatalogAgentPluginRepositorySource {
+    kind: CatalogAgentPluginRepositorySourceKind;
+    /**
+     * Canonical lowercase GitHub owner/repository holding the plugin.
+     */
+    repository: string;
+    /**
+     * Relative POSIX path of the plugin directory in the repository. Omitted when the plugin is at the repository root.
+     */
+    path?: string;
+}
 /**
  * Where and when an Agent Plugin catalog reference was observed. Discovery provenance deliberately carries no descriptor URL, raw data, candidate handle, or content digest.
  *
@@ -9973,6 +10146,32 @@ export interface ContentExclusionPathCheck {
      */
     excluded: boolean;
 }
+/**
+ * Candidate content-exclusion policies to validate, as the raw JSON text a host received. The text is supplied unparsed so that a syntax error and a schema violation are both reported by the runtime's own validator rather than by the caller's JSON parser.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "ContentExclusionValidatePoliciesRequest".
+ */
+/** @experimental */
+export interface ContentExclusionValidatePoliciesRequest {
+    /**
+     * Unparsed JSON text expected to hold an array of content-exclusion policies.
+     */
+    policiesJson: string;
+}
+/**
+ * The accepted policies, parsed and normalized. A rejected input is reported as an error rather than in this result.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "ContentExclusionValidatePoliciesResult".
+ */
+/** @experimental */
+export interface ContentExclusionValidatePoliciesResult {
+    /**
+     * Validated policy objects in input order. Raw JSON preserves every field returned by the runtime's policy parser.
+     */
+    policies: JsonValue[];
+}
 /**
  * A single large message currently in context.
  *
@@ -31735,6 +31934,17 @@ export declare function createServerRpc(connection: MessageConnection): {
         getBuiltInCatalog: () => Promise<BuiltInModelCatalog>;
     };
     /** @experimental */
+    contentExclusion: {
+        /**
+         * Validates candidate content-exclusion policies and returns them normalized, without starting a session. This runs the same parser the runtime's own policy enforcement uses, so a host cannot accept a policy set the runtime would later reject, nor reject one it would have honored. Call it when policies arrive from outside the runtime — a command-line flag, a configuration file, a host's own settings — and must be checked before a session exists to apply them to. A malformed document fails with a message prefixed `Invalid JSON: `; a well-formed document that violates the policy schema fails with the offending field paths.
+         *
+         * @param params Candidate content-exclusion policies to validate, as the raw JSON text a host received. The text is supplied unparsed so that a syntax error and a schema violation are both reported by the runtime's own validator rather than by the caller's JSON parser.
+         *
+         * @returns The accepted policies, parsed and normalized. A rejected input is reported as an error rather than in this result.
+         */
+        validatePolicies: (params: ContentExclusionValidatePoliciesRequest) => Promise<ContentExclusionValidatePoliciesResult>;
+    };
+    /** @experimental */
     tools: {
         /**
          * Lists built-in tools available for a model.

package/dist/generated/rpc.js

@@ -237,6 +237,17 @@ function createServerRpc(connection) {
       getBuiltInCatalog: async () => connection.sendRequest("models.getBuiltInCatalog", {})
     },
     /** @experimental */
+    contentExclusion: {
+      /**
+       * Validates candidate content-exclusion policies and returns them normalized, without starting a session. This runs the same parser the runtime's own policy enforcement uses, so a host cannot accept a policy set the runtime would later reject, nor reject one it would have honored. Call it when policies arrive from outside the runtime — a command-line flag, a configuration file, a host's own settings — and must be checked before a session exists to apply them to. A malformed document fails with a message prefixed `Invalid JSON: `; a well-formed document that violates the policy schema fails with the offending field paths.
+       *
+       * @param params Candidate content-exclusion policies to validate, as the raw JSON text a host received. The text is supplied unparsed so that a syntax error and a schema violation are both reported by the runtime's own validator rather than by the caller's JSON parser.
+       *
+       * @returns The accepted policies, parsed and normalized. A rejected input is reported as an error rather than in this result.
+       */
+      validatePolicies: async (params) => connection.sendRequest("contentExclusion.validatePolicies", params)
+    },
+    /** @experimental */
     tools: {
       /**
        * Lists built-in tools available for a model.

package/dist/session.js

@@ -57,6 +57,20 @@ function deserializeHookInput(raw) {
     ...stop_hook_active === void 0 ? {} : { stopHookActive: stop_hook_active }
   };
 }
+function normalizeHookError(hookType, input) {
+  if (hookType !== "errorOccurred" && hookType !== "sessionEnd") {
+    return input;
+  }
+  if (!input || typeof input !== "object" || !("error" in input)) {
+    return input;
+  }
+  const { error } = input;
+  if (!error || typeof error !== "object" || Array.isArray(error)) {
+    return input;
+  }
+  const { message } = error;
+  return { ...input, error: typeof message === "string" ? message : JSON.stringify(error) };
+}
 function isOpenCanvasInstance(value) {
   if (!value || typeof value !== "object") {
     return false;
@@ -1775,7 +1789,7 @@ class CopilotSession {
     if (!this.hooks) {
       return void 0;
     }
-    const normalized = deserializeHookInput(input);
+    const normalized = normalizeHookError(hookType, deserializeHookInput(input));
     const handlerMap = {
       preToolUse: this.hooks.onPreToolUse,
       preMcpToolCall: this.hooks.onPreMcpToolCall,

package/dist/types.d.ts

@@ -2596,6 +2596,13 @@ export interface SessionConfigBase {
      * read from the shared session store.
      */
     enableSessionStore?: boolean;
+    /**
+     * When true, requests the read-only GitHub cache store for this session
+     * (the `github-cache-store` capability). The runtime registers the
+     * `github_sql` tool only when its `GITHUB_CACHE_STORE` feature flag is
+     * also on. Defaults to disabled.
+     */
+    enableGitHubCacheStore?: boolean;
     /**
      * When true, enables skill loading (including builtin skills and discovered
      * skill directories). When false, no skills are loaded regardless of

package/package.json

@@ -5,8 +5,8 @@
         "url": "https://github.com/github/copilot-agent-runtime.git",
         "directory": "src/sdk/nodejs"
     },
-    "version": "1.0.21",
-    "copilotCliVersion": "1.0.97",
+    "version": "1.0.22-preview.0",
+    "copilotCliVersion": "1.0.98-0",
     "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
     "main": "./dist/cjs/index.js",
     "types": "./dist/index.d.ts",
@@ -103,18 +103,18 @@
         "README.md"
     ],
     "copilotRuntime": {
-        "sourceSha": "0ce88c5486a1e6a9c08b8ed708aa86abc9af25cf",
-        "version": "1.0.97",
+        "sourceSha": "8f6dbb8fcdc7c2f25291088a43d0755763269588",
+        "version": "1.0.98-0",
         "visibility": "public"
     },
     "optionalDependencies": {
-        "@github/copilot-sdk-darwin-arm64": "1.0.21",
-        "@github/copilot-sdk-darwin-x64": "1.0.21",
-        "@github/copilot-sdk-linux-arm64": "1.0.21",
-        "@github/copilot-sdk-linux-x64": "1.0.21",
-        "@github/copilot-sdk-linuxmusl-arm64": "1.0.21",
-        "@github/copilot-sdk-linuxmusl-x64": "1.0.21",
-        "@github/copilot-sdk-win32-arm64": "1.0.21",
-        "@github/copilot-sdk-win32-x64": "1.0.21"
+        "@github/copilot-sdk-darwin-arm64": "1.0.22-preview.0",
+        "@github/copilot-sdk-darwin-x64": "1.0.22-preview.0",
+        "@github/copilot-sdk-linux-arm64": "1.0.22-preview.0",
+        "@github/copilot-sdk-linux-x64": "1.0.22-preview.0",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.22-preview.0",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.22-preview.0",
+        "@github/copilot-sdk-win32-arm64": "1.0.22-preview.0",
+        "@github/copilot-sdk-win32-x64": "1.0.22-preview.0"
     }
 }