@github/copilot-sdk 0.3.0-preview.0 → 0.3.0-preview.1

package/dist/generated/session-events.d.ts

@@ -2,7 +2,7 @@
  * AUTO-GENERATED FILE - DO NOT EDIT
  * Generated from: session-events.schema.json
  */
-export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | PlanChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantUsageEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | ExtensionsLoadedEvent;
+export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | PlanChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | ContextChangedEvent | UsageInfoEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantUsageEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | ExtensionsLoadedEvent;
 /**
  * Hosting platform type of the repository (github or ado)
  */
@@ -75,10 +75,26 @@ export type PermissionRequestMemoryAction = "store" | "vote";
  * Vote direction (vote only)
  */
 export type PermissionRequestMemoryDirection = "upvote" | "downvote";
+/**
+ * Derived user-facing permission prompt details for UI consumers
+ */
+export type PermissionPromptRequest = PermissionPromptRequestCommands | PermissionPromptRequestWrite | PermissionPromptRequestRead | PermissionPromptRequestMcp | PermissionPromptRequestUrl | PermissionPromptRequestMemory | PermissionPromptRequestCustomTool | PermissionPromptRequestPath | PermissionPromptRequestHook;
+/**
+ * Whether this is a store or vote memory operation
+ */
+export type PermissionPromptRequestMemoryAction = "store" | "vote";
+/**
+ * Vote direction (vote only)
+ */
+export type PermissionPromptRequestMemoryDirection = "upvote" | "downvote";
+/**
+ * Underlying permission kind that needs path approval
+ */
+export type PermissionPromptRequestPathAccessKind = "read" | "shell" | "write";
 /**
  * The outcome of the permission request
  */
-export type PermissionCompletedKind = "approved" | "denied-by-rules" | "denied-no-approval-rule-and-could-not-request-from-user" | "denied-interactively-by-user" | "denied-by-content-exclusion-policy" | "denied-by-permission-request-hook";
+export type PermissionCompletedKind = "approved" | "approved-for-session" | "approved-for-location" | "denied-by-rules" | "denied-no-approval-rule-and-could-not-request-from-user" | "denied-interactively-by-user" | "denied-by-content-exclusion-policy" | "denied-by-permission-request-hook";
 /**
  * Elicitation mode; "form" for structured input, "url" for browser-based. Defaults to "form" when absent.
  */
@@ -1133,21 +1149,68 @@ export interface CompactionCompleteData {
     toolDefinitionsTokens?: number;
 }
 /**
- * Token usage breakdown for the compaction LLM call
+ * Token usage breakdown for the compaction LLM call (aligned with assistant.usage format)
  */
 export interface CompactionCompleteCompactionTokensUsed {
     /**
      * Cached input tokens reused in the compaction LLM call
      */
-    cachedInput: number;
+    cacheReadTokens?: number;
+    /**
+     * Tokens written to prompt cache in the compaction LLM call
+     */
+    cacheWriteTokens?: number;
+    copilotUsage?: CompactionCompleteCompactionTokensUsedCopilotUsage;
+    /**
+     * Duration of the compaction LLM call in milliseconds
+     */
+    duration?: number;
     /**
      * Input tokens consumed by the compaction LLM call
      */
-    input: number;
+    inputTokens?: number;
+    /**
+     * Model identifier used for the compaction LLM call
+     */
+    model?: string;
     /**
      * Output tokens produced by the compaction LLM call
      */
-    output: number;
+    outputTokens?: number;
+}
+/**
+ * Per-request cost and usage data from the CAPI copilot_usage response field
+ */
+export interface CompactionCompleteCompactionTokensUsedCopilotUsage {
+    /**
+     * Itemized token usage breakdown
+     */
+    tokenDetails: CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail[];
+    /**
+     * Total cost in nano-AIU (AI Units) for this request
+     */
+    totalNanoAiu: number;
+}
+/**
+ * Token usage detail for a single billing category
+ */
+export interface CompactionCompleteCompactionTokensUsedCopilotUsageTokenDetail {
+    /**
+     * Number of tokens in this billing batch
+     */
+    batchSize: number;
+    /**
+     * Cost per batch of tokens
+     */
+    costPerBatch: number;
+    /**
+     * Total token count for this entry
+     */
+    tokenCount: number;
+    /**
+     * Token category (e.g., "input", "output")
+     */
+    tokenType: string;
 }
 export interface TaskCompleteEvent {
     /**
@@ -2966,6 +3029,7 @@ export interface PermissionRequestedEvent {
  */
 export interface PermissionRequestedData {
     permissionRequest: PermissionRequest;
+    promptRequest?: PermissionPromptRequest;
     /**
      * Unique identifier for this permission request; used to respond via session.respondToPermission()
      */
@@ -3231,6 +3295,243 @@ export interface PermissionRequestHook {
      */
     toolName: string;
 }
+/**
+ * Shell command permission prompt
+ */
+export interface PermissionPromptRequestCommands {
+    /**
+     * Whether the UI can offer session-wide approval for this command pattern
+     */
+    canOfferSessionApproval: boolean;
+    /**
+     * Command identifiers covered by this approval prompt
+     */
+    commandIdentifiers: string[];
+    /**
+     * The complete shell command text to be executed
+     */
+    fullCommandText: string;
+    /**
+     * Human-readable description of what the command intends to do
+     */
+    intention: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "commands";
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+    /**
+     * Optional warning message about risks of running this command
+     */
+    warning?: string;
+}
+/**
+ * File write permission prompt
+ */
+export interface PermissionPromptRequestWrite {
+    /**
+     * Whether the UI can offer session-wide approval for file write operations
+     */
+    canOfferSessionApproval: boolean;
+    /**
+     * Unified diff showing the proposed changes
+     */
+    diff: string;
+    /**
+     * Path of the file being written to
+     */
+    fileName: string;
+    /**
+     * Human-readable description of the intended file change
+     */
+    intention: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "write";
+    /**
+     * Complete new file contents for newly created files
+     */
+    newFileContents?: string;
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
+/**
+ * File read permission prompt
+ */
+export interface PermissionPromptRequestRead {
+    /**
+     * Human-readable description of why the file is being read
+     */
+    intention: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "read";
+    /**
+     * Path of the file or directory being read
+     */
+    path: string;
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
+/**
+ * MCP tool invocation permission prompt
+ */
+export interface PermissionPromptRequestMcp {
+    args?: unknown;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "mcp";
+    /**
+     * Name of the MCP server providing the tool
+     */
+    serverName: string;
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+    /**
+     * Internal name of the MCP tool
+     */
+    toolName: string;
+    /**
+     * Human-readable title of the MCP tool
+     */
+    toolTitle: string;
+}
+/**
+ * URL access permission prompt
+ */
+export interface PermissionPromptRequestUrl {
+    /**
+     * Human-readable description of why the URL is being accessed
+     */
+    intention: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "url";
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+    /**
+     * URL to be fetched
+     */
+    url: string;
+}
+/**
+ * Memory operation permission prompt
+ */
+export interface PermissionPromptRequestMemory {
+    action?: PermissionPromptRequestMemoryAction;
+    /**
+     * Source references for the stored fact (store only)
+     */
+    citations?: string;
+    direction?: PermissionPromptRequestMemoryDirection;
+    /**
+     * The fact being stored or voted on
+     */
+    fact: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "memory";
+    /**
+     * Reason for the vote (vote only)
+     */
+    reason?: string;
+    /**
+     * Topic or subject of the memory (store only)
+     */
+    subject?: string;
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
+/**
+ * Custom tool invocation permission prompt
+ */
+export interface PermissionPromptRequestCustomTool {
+    /**
+     * Arguments to pass to the custom tool
+     */
+    args?: {
+        [k: string]: unknown;
+    };
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "custom-tool";
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+    /**
+     * Description of what the custom tool does
+     */
+    toolDescription: string;
+    /**
+     * Name of the custom tool
+     */
+    toolName: string;
+}
+/**
+ * Path access permission prompt
+ */
+export interface PermissionPromptRequestPath {
+    accessKind: PermissionPromptRequestPathAccessKind;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "path";
+    /**
+     * File paths that require explicit approval
+     */
+    paths: string[];
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+}
+/**
+ * Hook confirmation permission prompt
+ */
+export interface PermissionPromptRequestHook {
+    /**
+     * Optional message from the hook explaining why confirmation is needed
+     */
+    hookMessage?: string;
+    /**
+     * Prompt kind discriminator
+     */
+    kind: "hook";
+    /**
+     * Arguments of the tool call being gated
+     */
+    toolArgs?: {
+        [k: string]: unknown;
+    };
+    /**
+     * Tool call ID that triggered this permission request
+     */
+    toolCallId?: string;
+    /**
+     * Name of the tool the hook is gating
+     */
+    toolName: string;
+}
 export interface PermissionCompletedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
@@ -3261,6 +3562,10 @@ export interface PermissionCompletedData {
      */
     requestId: string;
     result: PermissionCompletedResult;
+    /**
+     * Optional tool call ID associated with this permission prompt; clients may use it to correlate UI created from tool-scoped prompts
+     */
+    toolCallId?: string;
 }
 /**
  * The result of the permission request
@@ -3800,6 +4105,74 @@ export interface CommandCompletedData {
      */
     requestId: string;
 }
+export interface AutoModeSwitchRequestedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: AutoModeSwitchRequestedData;
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    type: "auto_mode_switch.requested";
+}
+/**
+ * Auto mode switch request notification requiring user approval
+ */
+export interface AutoModeSwitchRequestedData {
+    /**
+     * The rate limit error code that triggered this request
+     */
+    errorCode?: string;
+    /**
+     * Unique identifier for this request; used to respond via session.respondToAutoModeSwitch()
+     */
+    requestId: string;
+}
+export interface AutoModeSwitchCompletedEvent {
+    /**
+     * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.
+     */
+    agentId?: string;
+    data: AutoModeSwitchCompletedData;
+    ephemeral: true;
+    /**
+     * Unique event identifier (UUID v4), generated when the event is emitted
+     */
+    id: string;
+    /**
+     * ID of the chronologically preceding event in the session, forming a linked chain. Null for the first event.
+     */
+    parentId: string | null;
+    /**
+     * ISO 8601 timestamp when the event was created
+     */
+    timestamp: string;
+    type: "auto_mode_switch.completed";
+}
+/**
+ * Auto mode switch completion notification
+ */
+export interface AutoModeSwitchCompletedData {
+    /**
+     * Request ID of the resolved request; clients should dismiss any UI for this request
+     */
+    requestId: string;
+    /**
+     * The user's choice: 'yes', 'yes_always', or 'no'
+     */
+    response: string;
+}
 export interface CommandsChangedEvent {
     /**
      * Sub-agent instance identifier. Absent for events from the root/main agent and session-level events.

package/dist/session.js

@@ -325,7 +325,7 @@ class CopilotSession {
         await this.rpc.permissions.handlePendingPermissionRequest({
           requestId,
           result: {
-            kind: "denied-no-approval-rule-and-could-not-request-from-user"
+            kind: "user-not-available"
           }
         });
       } catch (rpcError) {
@@ -603,7 +603,7 @@ class CopilotSession {
    */
   async _handlePermissionRequestV2(request) {
     if (!this.permissionHandler) {
-      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+      return { kind: "user-not-available" };
     }
     try {
       const result = await this.permissionHandler(request, {
@@ -617,7 +617,7 @@ class CopilotSession {
       if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
         throw error;
       }
-      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+      return { kind: "user-not-available" };
     }
   }
   /**

package/dist/types.d.ts

@@ -105,12 +105,12 @@ export interface CopilotClientOptions {
      * When provided, the token is passed to the CLI server via environment variable.
      * This takes priority over other authentication methods.
      */
-    githubToken?: string;
+    gitHubToken?: string;
     /**
      * Whether to use the logged-in user for authentication.
      * When true, the CLI server will attempt to use stored OAuth tokens or gh CLI auth.
-     * When false, only explicit tokens (githubToken or environment variables) are used.
-     * @default true (but defaults to false when githubToken is provided)
+     * When false, only explicit tokens (gitHubToken or environment variables) are used.
+     * @default true (but defaults to false when gitHubToken is provided)
      */
     useLoggedInUser?: boolean;
     /**
@@ -158,6 +158,15 @@ export interface CopilotClientOptions {
      * instead of the server's default local filesystem storage.
      */
     sessionFs?: SessionFsConfig;
+    /**
+     * Server-wide idle timeout for sessions in seconds.
+     * Sessions without activity for this duration are automatically cleaned up.
+     * Set to 0 or omit to disable (sessions live indefinitely).
+     * This option is only used when the SDK spawns the CLI process; it is ignored
+     * when connecting to an external server via {@link cliUrl}.
+     * @default undefined (disabled)
+     */
+    sessionIdleTimeoutSeconds?: number;
 }
 /**
  * Configuration for creating a session
@@ -1060,6 +1069,17 @@ export interface SessionConfig {
      * Set to `{ enabled: false }` to disable.
      */
     infiniteSessions?: InfiniteSessionConfig;
+    /**
+     * GitHub token for per-session authentication.
+     * When provided, the runtime resolves this token into a full GitHub identity
+     * (login, Copilot plan, endpoints) and stores it on the session. This enables
+     * multitenancy — different sessions can have different GitHub identities.
+     *
+     * This is independent of the client-level `gitHubToken` in {@link CopilotClientOptions},
+     * which authenticates the CLI process itself. The session-level token determines
+     * the identity used for content exclusion, model routing, and quota checks.
+     */
+    gitHubToken?: string;
     /**
      * Optional event handler that is registered on the session before the
      * session.create RPC is issued. This guarantees that early events emitted
@@ -1079,7 +1099,7 @@ export interface SessionConfig {
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "modelCapabilities" | "streaming" | "includeSubAgentStreamingEvents" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "onElicitationRequest" | "hooks" | "workingDirectory" | "configDir" | "enableConfigDiscovery" | "mcpServers" | "customAgents" | "defaultAgent" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "onEvent" | "createSessionFsHandler"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "modelCapabilities" | "streaming" | "includeSubAgentStreamingEvents" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "onElicitationRequest" | "hooks" | "workingDirectory" | "configDir" | "enableConfigDiscovery" | "mcpServers" | "customAgents" | "defaultAgent" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "gitHubToken" | "onEvent" | "createSessionFsHandler"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.

package/dist/types.js

@@ -57,7 +57,7 @@ const SYSTEM_PROMPT_SECTIONS = {
     description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
   }
 };
-const approveAll = () => ({ kind: "approved" });
+const approveAll = () => ({ kind: "approve-once" });
 const defaultJoinSessionPermissionHandler = () => ({
   kind: "no-result"
 });

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "0.3.0-preview.0",
+  "version": "0.3.0-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.35-0",
+    "@github/copilot": "^1.0.36-0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },