@github/copilot-sdk 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/index.d.ts

@@ -6,4 +6,5 @@
 export { CopilotClient } from "./client.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
 export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, SYSTEM_PROMPT_SECTIONS, } from "./types.js";
-export type { CommandContext, CommandDefinition, CommandHandler, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, ConnectionState, CopilotClientOptions, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, InputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type * from "./generated/session-events.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, ConnectionState, CopilotClientOptions, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, InputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/session.d.ts

@@ -216,8 +216,8 @@ export declare class CopilotSession {
     /**
      * Registers custom tool handlers for this session.
      *
-     * Tools allow the assistant to execute custom functions. When the assistant
-     * invokes a tool, the corresponding handler is called with the tool arguments.
+     * Tools with handlers allow the assistant to execute custom functions automatically.
+     * Declaration-only tools are surfaced as events and left pending for the consumer.
      *
      * @param tools - An array of tool definitions with their handlers, or undefined to clear all tools
      * @internal This method is typically called internally when creating a session with tools.

package/dist/session.js

@@ -373,8 +373,8 @@ class CopilotSession {
   /**
    * Registers custom tool handlers for this session.
    *
-   * Tools allow the assistant to execute custom functions. When the assistant
-   * invokes a tool, the corresponding handler is called with the tool arguments.
+   * Tools with handlers allow the assistant to execute custom functions automatically.
+   * Declaration-only tools are surfaced as events and left pending for the consumer.
    *
    * @param tools - An array of tool definitions with their handlers, or undefined to clear all tools
    * @internal This method is typically called internally when creating a session with tools.
@@ -385,7 +385,9 @@ class CopilotSession {
       return;
     }
     for (const tool of tools) {
-      this.toolHandlers.set(tool.name, tool.handler);
+      if (tool.handler) {
+        this.toolHandlers.set(tool.name, tool.handler);
+      }
     }
   }
   /**

package/dist/sessionFsProvider.d.ts

@@ -1,10 +1,35 @@
-import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry } from "./generated/rpc.js";
+import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry, SessionFsSqliteQueryResult as GeneratedSqliteQueryResult, SessionFsSqliteQueryType } from "./generated/rpc.js";
+export type { SessionFsSqliteQueryType };
 /**
  * File metadata returned by {@link SessionFsProvider.stat}.
  * Same shape as the generated {@link SessionFsStatResult} but without the
  * `error` field, since providers signal errors by throwing.
  */
 export type SessionFsFileInfo = Omit<SessionFsStatResult, "error">;
+/**
+ * Result of a SQLite query execution via {@link SessionFsSqliteProvider.query}.
+ * Same shape as the generated {@link GeneratedSqliteQueryResult} but without the
+ * `error` field, since providers signal errors by throwing.
+ */
+export type SessionFsSqliteQueryResult = Omit<GeneratedSqliteQueryResult, "error">;
+/**
+ * SQLite operations for the per-session database.
+ * Implementers provide query execution and existence checking.
+ */
+export interface SessionFsSqliteProvider {
+    /**
+     * Execute a SQLite query against the per-session database.
+     *
+     * @param queryType - How to execute: `"exec"` for DDL/multi-statement, `"query"` for SELECT, `"run"` for INSERT/UPDATE/DELETE.
+     * @param query - SQL query to execute.
+     * @param params - Optional named bind parameters.
+     */
+    query(queryType: SessionFsSqliteQueryType, query: string, params?: Record<string, string | number | null>): Promise<SessionFsSqliteQueryResult | undefined>;
+    /**
+     * Check whether the per-session database already exists, without creating it.
+     */
+    exists(): Promise<boolean>;
+}
 /**
  * Interface for session filesystem providers. Implementers use idiomatic
  * TypeScript patterns: throw on error, return values directly. Use
@@ -35,6 +60,8 @@ export interface SessionFsProvider {
     rm(path: string, recursive: boolean, force: boolean): Promise<void>;
     /** Renames/moves a file or directory. */
     rename(src: string, dest: string): Promise<void>;
+    /** Per-session SQLite database operations. Optional — omit if the provider does not support SQLite. */
+    sqlite?: SessionFsSqliteProvider;
 }
 /**
  * Wraps a {@link SessionFsProvider} into the {@link SessionFsHandler}

package/dist/sessionFsProvider.js

@@ -1,3 +1,15 @@
+function normalizeSqliteParams(params) {
+  if (!params) {
+    return void 0;
+  }
+  const normalized = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0) {
+      normalized[key] = value;
+    }
+  }
+  return normalized;
+}
 function createSessionFsAdapter(provider) {
   return {
     readFile: async ({ path }) => {
@@ -84,6 +96,28 @@ function createSessionFsAdapter(provider) {
       } catch (err) {
         return toSessionFsError(err);
       }
+    },
+    // Unlike the FS methods above, SQLite methods let errors propagate to the JSON-RPC layer
+    // rather than catching and mapping via toSessionFsError. The FS error mapping is specifically
+    // for translating Node.js errno codes (e.g., ENOENT) into SessionFsError, which isn't
+    // meaningful for SQL errors. Letting exceptions propagate preserves the original error
+    // message in the JSON-RPC error response.
+    sqliteQuery: async ({ queryType, query, params: bindParams }) => {
+      if (!provider.sqlite) {
+        throw new Error("SQLite is not supported by this provider");
+      }
+      const result = await provider.sqlite.query(
+        queryType,
+        query,
+        normalizeSqliteParams(bindParams)
+      );
+      return result ?? { rows: [], columns: [], rowsAffected: 0 };
+    },
+    sqliteExists: async () => {
+      if (!provider.sqlite) {
+        throw new Error("SQLite is not supported by this provider");
+      }
+      return { exists: await provider.sqlite.exists() };
     }
   };
 }

package/dist/types.d.ts

@@ -4,10 +4,15 @@
 import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
+import type { RemoteSessionMode } from "./generated/rpc.js";
+export type { RemoteSessionMode } from "./generated/rpc.js";
 export type SessionEvent = GeneratedSessionEvent;
 export type { SessionFsProvider } from "./sessionFsProvider.js";
 export { createSessionFsAdapter } from "./sessionFsProvider.js";
 export type { SessionFsFileInfo } from "./sessionFsProvider.js";
+export type { SessionFsSqliteQueryResult } from "./sessionFsProvider.js";
+export type { SessionFsSqliteQueryType } from "./sessionFsProvider.js";
+export type { SessionFsSqliteProvider } from "./sessionFsProvider.js";
 /**
  * Options for creating a CopilotClient
  */
@@ -199,7 +204,7 @@ export type ToolResultType = "success" | "failure" | "rejected" | "denied" | "ti
 export type ToolBinaryResult = {
     data: string;
     mimeType: string;
-    type: string;
+    type: "image" | "resource";
     description?: string;
 };
 export type ToolResultObject = {
@@ -211,6 +216,20 @@ export type ToolResultObject = {
     toolTelemetry?: Record<string, unknown>;
 };
 export type ToolResult = string | ToolResultObject;
+/**
+ * GitHub repository metadata to associate with a cloud session.
+ */
+export interface CloudSessionRepository {
+    owner: string;
+    name: string;
+    branch?: string;
+}
+/**
+ * Options for creating a remote session in the cloud.
+ */
+export interface CloudSessionOptions {
+    repository?: CloudSessionRepository;
+}
 /**
  * Content block types within an MCP CallToolResult.
  */
@@ -269,12 +288,16 @@ export interface ZodSchema<T = unknown> {
  * - A Zod schema (provides type inference for handler)
  * - A raw JSON schema object
  * - Omitted (no parameters)
+ *
+ * If `handler` is omitted, the SDK exposes the declaration but does not
+ * automatically invoke the tool. Consumers can resolve tool calls by observing
+ * external tool request events and calling the pending-tool RPC.
  */
 export interface Tool<TArgs = unknown> {
     name: string;
     description?: string;
     parameters?: ZodSchema<TArgs> | Record<string, unknown>;
-    handler: ToolHandler<TArgs>;
+    handler?: ToolHandler<TArgs>;
     /**
      * When true, explicitly indicates this tool is intended to override a built-in tool
      * of the same name. If not set and the name clashes with a built-in tool, the runtime
@@ -293,7 +316,7 @@ export interface Tool<TArgs = unknown> {
 export declare function defineTool<T = unknown>(name: string, config: {
     description?: string;
     parameters?: ZodSchema<T> | Record<string, unknown>;
-    handler: ToolHandler<T>;
+    handler?: ToolHandler<T>;
     overridesBuiltInTool?: boolean;
     skipPermission?: boolean;
 }): Tool<T>;
@@ -703,6 +726,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`. */
+    sessionId: string;
     timestamp: number;
     cwd: string;
 }
@@ -889,7 +915,7 @@ interface MCPServerConfigBase {
 export interface MCPStdioServerConfig extends MCPServerConfigBase {
     type?: "local" | "stdio";
     command: string;
-    args: string[];
+    args?: string[];
     /**
      * Environment variables to pass to the server.
      */
@@ -956,6 +982,12 @@ export interface CustomAgentConfig {
      * When omitted, no skills are injected (opt-in model).
      */
     skills?: string[];
+    /**
+     * Model identifier for this agent (e.g. "claude-haiku-4.5").
+     * When set, the runtime will attempt to use this model for the agent,
+     * falling back to the parent session model if unavailable.
+     */
+    model?: string;
 }
 /**
  * Configuration for the default agent (the built-in agent that handles
@@ -1040,7 +1072,8 @@ export interface SessionConfig {
      */
     enableConfigDiscovery?: boolean;
     /**
-     * Tools exposed to the CLI server
+     * Tools exposed to the CLI server. Tools without a handler are declaration-only
+     * and must be resolved by the consumer via pending external tool request RPCs.
      */
     tools?: Tool<any>[];
     /**
@@ -1079,10 +1112,11 @@ export interface SessionConfig {
      */
     enableSessionTelemetry?: boolean;
     /**
-     * Handler for permission requests from the server.
-     * When provided, the server will call this handler to request permission for operations.
+     * Optional handler for permission requests from the server.
+     * When omitted, permission requests are surfaced as events and left pending for
+     * the consumer to resolve via the pending permission RPC.
      */
-    onPermissionRequest: PermissionHandler;
+    onPermissionRequest?: PermissionHandler;
     /**
      * Handler for user input requests from the agent.
      * When provided, enables the ask_user tool allowing the agent to ask questions.
@@ -1176,6 +1210,18 @@ export interface SessionConfig {
      * the identity used for content exclusion, model routing, and quota checks.
      */
     gitHubToken?: string;
+    /**
+     * Per-session remote behavior control:
+     * - `"off"` — local only, no remote export (default)
+     * - `"export"` — export session events to GitHub without enabling remote steering
+     * - `"on"` — export to GitHub AND enable remote steering
+     */
+    remoteSession?: RemoteSessionMode;
+    /**
+     * Creates a remote session in the cloud instead of a local session.
+     * The optional repository is associated with the cloud session.
+     */
+    cloud?: CloudSessionOptions;
     /**
      * Optional event handler that is registered on the session before the
      * session.create RPC is issued. This guarantees that early events emitted
@@ -1195,7 +1241,7 @@ export interface SessionConfig {
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "enableSessionTelemetry" | "modelCapabilities" | "streaming" | "includeSubAgentStreamingEvents" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "onElicitationRequest" | "onExitPlanMode" | "onAutoModeSwitch" | "hooks" | "workingDirectory" | "configDir" | "enableConfigDiscovery" | "mcpServers" | "customAgents" | "defaultAgent" | "agent" | "skillDirectories" | "instructionDirectories" | "disabledSkills" | "infiniteSessions" | "gitHubToken" | "onEvent" | "createSessionFsHandler"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "enableSessionTelemetry" | "modelCapabilities" | "streaming" | "includeSubAgentStreamingEvents" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "onElicitationRequest" | "onExitPlanMode" | "onAutoModeSwitch" | "hooks" | "workingDirectory" | "configDir" | "enableConfigDiscovery" | "mcpServers" | "customAgents" | "defaultAgent" | "agent" | "skillDirectories" | "instructionDirectories" | "disabledSkills" | "infiniteSessions" | "gitHubToken" | "remoteSession" | "onEvent" | "createSessionFsHandler"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.
@@ -1384,6 +1430,19 @@ export interface SessionFsConfig {
      * Path conventions used by this filesystem provider.
      */
     conventions: "windows" | "posix";
+    /**
+     * Optional capabilities declared by this provider.
+     * The runtime uses these to determine which features are available.
+     */
+    capabilities?: {
+        /**
+         * Whether this provider supports SQLite query/exists operations.
+         * When false or omitted, the runtime will not offer SQL tools or
+         * todo tracking for sessions using this provider.
+         * @default false
+         */
+        sqlite?: boolean;
+    };
 }
 /**
  * Filter options for listing sessions
@@ -1470,7 +1529,7 @@ export interface ModelPolicy {
  * Model billing information
  */
 export interface ModelBilling {
-    multiplier: number;
+    multiplier?: number;
 }
 /**
  * Information about an available model

package/docs/examples.md

@@ -561,12 +561,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" };
     },
 });
 ```

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -40,7 +40,7 @@
     "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",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.44-2",
+    "@github/copilot": "^1.0.51",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },