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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/types.d.ts CHANGED
@@ -48,80 +48,120 @@ export interface TelemetryConfig {
48
48
  /** Whether to capture message content (prompts, responses). Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT. */
49
49
  captureContent?: boolean;
50
50
  }
51
- export interface CopilotClientOptions {
52
- /**
53
- * Path to the CLI executable or JavaScript entry point.
54
- * If not specified, uses the bundled CLI from the @github/copilot package.
55
- */
56
- cliPath?: string;
51
+ /**
52
+ * Configures how a {@link CopilotClient} connects to the Copilot runtime.
53
+ * Construct via the factory functions on {@link RuntimeConnection}.
54
+ */
55
+ export type RuntimeConnection = StdioRuntimeConnection | TcpRuntimeConnection | UriRuntimeConnection;
56
+ /**
57
+ * Spawns a runtime child process and communicates over its stdin/stdout.
58
+ * This is the default if no {@link CopilotClientOptions.connection} is set.
59
+ */
60
+ export interface StdioRuntimeConnection {
61
+ readonly kind: "stdio";
62
+ /** Path to the runtime executable. When omitted, the bundled runtime is used. */
63
+ readonly path?: string;
64
+ /** Extra command-line arguments to pass to the runtime process. */
65
+ readonly args?: readonly string[];
66
+ }
67
+ /**
68
+ * Spawns a runtime child process that listens on a TCP socket and connects to it.
69
+ */
70
+ export interface TcpRuntimeConnection {
71
+ readonly kind: "tcp";
57
72
  /**
58
- * Extra arguments to pass to the CLI executable (inserted before SDK-managed args)
73
+ * TCP port to listen on. `0` (the default) auto-allocates a free port.
74
+ * If the chosen port is already in use, startup fails.
59
75
  */
60
- cliArgs?: string[];
76
+ readonly port?: number;
61
77
  /**
62
- * Working directory for the CLI process
63
- * If not set, inherits the current process's working directory
78
+ * Optional shared secret the SDK sends to the spawned runtime to authenticate
79
+ * the TCP connection. When omitted, a UUID is generated automatically so the
80
+ * loopback listener is safe by default.
64
81
  */
65
- cwd?: string;
82
+ readonly connectionToken?: string;
83
+ /** Path to the runtime executable. When omitted, the bundled runtime is used. */
84
+ readonly path?: string;
85
+ /** Extra command-line arguments to pass to the runtime process. */
86
+ readonly args?: readonly string[];
87
+ }
88
+ /**
89
+ * Connects to an already-running runtime at the specified URL. The SDK does not
90
+ * spawn a process in this mode.
91
+ */
92
+ export interface UriRuntimeConnection {
93
+ readonly kind: "uri";
66
94
  /**
67
- * Base directory for Copilot data (session state, config, etc.).
68
- * Sets the COPILOT_HOME environment variable on the spawned CLI process.
69
- * When not set, the CLI defaults to ~/.copilot.
70
- * This option is only used when the SDK spawns the CLI process; it is ignored
71
- * when connecting to an external server via {@link cliUrl}.
95
+ * URL of the runtime to connect to. Accepts `"port"`, `"host:port"`, or a
96
+ * full URL (`"http://host:port"`).
72
97
  */
73
- copilotHome?: string;
98
+ readonly url: string;
99
+ /** Optional shared secret to authenticate the connection. */
100
+ readonly connectionToken?: string;
101
+ }
102
+ /** Factory functions for constructing {@link RuntimeConnection} instances. */
103
+ export declare const RuntimeConnection: {
74
104
  /**
75
- * Port for the CLI server (TCP mode only)
76
- * @default 0 (random available port)
105
+ * Spawn a runtime child process and communicate over its stdin/stdout.
106
+ * This is the default if no {@link CopilotClientOptions.connection} is set.
77
107
  */
78
- port?: number;
108
+ readonly forStdio: (opts?: {
109
+ path?: string;
110
+ args?: readonly string[];
111
+ }) => StdioRuntimeConnection;
79
112
  /**
80
- * Use stdio transport instead of TCP
81
- * When true, communicates with CLI via stdin/stdout pipes
82
- * @default true
113
+ * Spawn a runtime child process that listens on a TCP socket and connect to it.
83
114
  */
84
- useStdio?: boolean;
115
+ readonly forTcp: (opts?: {
116
+ port?: number;
117
+ connectionToken?: string;
118
+ path?: string;
119
+ args?: readonly string[];
120
+ }) => TcpRuntimeConnection;
85
121
  /**
86
- * When true, indicates the SDK is running as a child process of the Copilot CLI server, and should
87
- * use its own stdio for communicating with the existing parent process. Can only be used in combination
88
- * with useStdio: true.
122
+ * Connect to an already-running runtime at the given URL. The SDK does not
123
+ * spawn a process in this mode.
89
124
  */
90
- isChildProcess?: boolean;
125
+ readonly forUri: (url: string, opts?: {
126
+ connectionToken?: string;
127
+ }) => UriRuntimeConnection;
128
+ };
129
+ export interface CopilotClientOptions {
91
130
  /**
92
- * URL of an existing Copilot CLI server to connect to over TCP
93
- * When provided, the client will not spawn a CLI process
94
- * Format: "host:port" or "http://host:port" or just "port" (defaults to localhost)
95
- * Examples: "localhost:8080", "http://127.0.0.1:9000", "8080"
96
- * Mutually exclusive with cliPath, useStdio
131
+ * How to connect to the Copilot runtime. When omitted, defaults to
132
+ * {@link RuntimeConnection.forStdio} with the bundled runtime.
97
133
  */
98
- cliUrl?: string;
134
+ connection?: RuntimeConnection;
99
135
  /**
100
- * Log level for the CLI server
136
+ * Working directory for the runtime process.
137
+ * If not set, inherits the current process's working directory.
101
138
  */
102
- logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
139
+ workingDirectory?: string;
103
140
  /**
104
- * Auto-start the CLI server on first use
105
- * @default true
141
+ * Base directory for Copilot data (session state, config, etc.).
142
+ * Sets the COPILOT_HOME environment variable on the spawned runtime.
143
+ * When not set, the runtime defaults to ~/.copilot.
144
+ * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
106
145
  */
107
- autoStart?: boolean;
146
+ baseDirectory?: string;
108
147
  /**
109
- * @deprecated This option has no effect and will be removed in a future release.
148
+ * Log level for the Copilot runtime. When omitted, the runtime uses its
149
+ * own default (currently `"info"`).
110
150
  */
111
- autoRestart?: boolean;
151
+ logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all";
112
152
  /**
113
- * Environment variables to pass to the CLI process. If not set, inherits process.env.
153
+ * Environment variables to pass to the runtime process. If not set, inherits process.env.
114
154
  */
115
155
  env?: Record<string, string | undefined>;
116
156
  /**
117
157
  * GitHub token to use for authentication.
118
- * When provided, the token is passed to the CLI server via environment variable.
158
+ * When provided, the token is passed to the runtime via environment variable.
119
159
  * This takes priority over other authentication methods.
120
160
  */
121
161
  gitHubToken?: string;
122
162
  /**
123
163
  * Whether to use the logged-in user for authentication.
124
- * When true, the CLI server will attempt to use stored OAuth tokens or gh CLI auth.
164
+ * When true, the runtime will attempt to use stored OAuth tokens or gh CLI auth.
125
165
  * When false, only explicit tokens (gitHubToken or environment variables) are used.
126
166
  * @default true (but defaults to false when gitHubToken is provided)
127
167
  */
@@ -129,14 +169,14 @@ export interface CopilotClientOptions {
129
169
  /**
130
170
  * Custom handler for listing available models.
131
171
  * When provided, client.listModels() calls this handler instead of
132
- * querying the CLI server. Useful in BYOK mode to return models
172
+ * querying the runtime. Useful in BYOK mode to return models
133
173
  * available from your custom provider.
134
174
  */
135
175
  onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
136
176
  /**
137
- * OpenTelemetry configuration for the CLI process.
177
+ * OpenTelemetry configuration for the runtime process.
138
178
  * When provided, the corresponding OTel environment variables are set
139
- * on the spawned CLI server.
179
+ * on the spawned runtime.
140
180
  */
141
181
  telemetry?: TelemetryConfig;
142
182
  /**
@@ -175,27 +215,18 @@ export interface CopilotClientOptions {
175
215
  * Server-wide idle timeout for sessions in seconds.
176
216
  * Sessions without activity for this duration are automatically cleaned up.
177
217
  * Set to 0 or omit to disable (sessions live indefinitely).
178
- * This option is only used when the SDK spawns the CLI process; it is ignored
179
- * when connecting to an external server via {@link cliUrl}.
218
+ * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
180
219
  * @default undefined (disabled)
181
220
  */
182
221
  sessionIdleTimeoutSeconds?: number;
183
- /**
184
- * Connection token for the headless CLI server (TCP only). When the SDK
185
- * spawns its own CLI in TCP mode and this is omitted, a UUID is generated
186
- * automatically so the loopback listener is safe by default. Rejected with
187
- * `useStdio: true` (stdio is pre-authenticated by transport).
188
- */
189
- tcpConnectionToken?: string;
190
222
  /**
191
223
  * Enable remote session support (Mission Control integration).
192
224
  * When true, sessions in a GitHub repository working directory are
193
225
  * accessible from GitHub web and mobile.
194
- * This option is only used when the SDK spawns the CLI process; it is ignored
195
- * when connecting to an external server via {@link cliUrl}.
226
+ * Ignored when connecting to an existing runtime via {@link RuntimeConnection.forUri}.
196
227
  * @default false
197
228
  */
198
- remote?: boolean;
229
+ enableRemoteSessions?: boolean;
199
230
  }
200
231
  /**
201
232
  * Configuration for creating a session
@@ -207,13 +238,14 @@ export type ToolBinaryResult = {
207
238
  type: "image" | "resource";
208
239
  description?: string;
209
240
  };
241
+ export type ToolTelemetry = Record<string, Record<string, unknown> | undefined>;
210
242
  export type ToolResultObject = {
211
243
  textResultForLlm: string;
212
244
  binaryResultsForLlm?: ToolBinaryResult[];
213
245
  resultType: ToolResultType;
214
246
  error?: string;
215
247
  sessionLog?: string;
216
- toolTelemetry?: Record<string, unknown>;
248
+ toolTelemetry?: ToolTelemetry;
217
249
  };
218
250
  export type ToolResult = string | ToolResultObject;
219
251
  /**
@@ -481,7 +513,7 @@ export type ElicitationHandler = (context: ElicitationContext) => Promise<Elicit
481
513
  /**
482
514
  * Options for the `input()` convenience method.
483
515
  */
484
- export interface InputOptions {
516
+ export interface UiInputOptions {
485
517
  /** Title label for the input field. */
486
518
  title?: string;
487
519
  /** Descriptive text shown below the field. */
@@ -522,7 +554,7 @@ export interface SessionUiApi {
522
554
  * Returns the entered text, or `null` if the user declines/cancels.
523
555
  * @throws Error if the host does not support elicitation.
524
556
  */
525
- input(message: string, options?: InputOptions): Promise<string | null>;
557
+ input(message: string, options?: UiInputOptions): Promise<string | null>;
526
558
  }
527
559
  export interface ToolCallRequestPayload {
528
560
  sessionId: string;
@@ -621,13 +653,20 @@ export interface SystemMessageCustomizeConfig {
621
653
  */
622
654
  export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageReplaceConfig | SystemMessageCustomizeConfig;
623
655
  /**
624
- * Permission request types from the server
656
+ * Permission request types from the server. This is the generated
657
+ * discriminated union from the runtime schema — switch on `kind` to
658
+ * access the variant-specific fields (e.g. shell `commands`, write
659
+ * `fileName`/`diff`, mcp `toolName`/`args`).
625
660
  */
626
- export interface PermissionRequest {
627
- kind: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool" | "memory" | "hook";
628
- toolCallId?: string;
629
- }
661
+ export type { PermissionRequest } from "./generated/session-events.js";
662
+ import type { PermissionRequest } from "./generated/session-events.js";
630
663
  import type { PermissionDecisionRequest } from "./generated/rpc.js";
664
+ /**
665
+ * Permission decision result returned from a {@link PermissionHandler}.
666
+ * The discriminated `kind` field selects the decision. Variant-specific
667
+ * fields (e.g. `feedback` on `{ kind: "reject" }`) come from the generated
668
+ * `PermissionDecisionRequest["result"]` union.
669
+ */
631
670
  export type PermissionRequestResult = PermissionDecisionRequest["result"] | {
632
671
  kind: "no-result";
633
672
  };
@@ -729,8 +768,9 @@ export interface BaseHookInput {
729
768
  /** The runtime session ID of the session that triggered the hook.
730
769
  * For sub-agent hooks this differs from `invocation.sessionId`. */
731
770
  sessionId: string;
732
- timestamp: number;
733
- cwd: string;
771
+ /** Time at which the hook event was emitted by the runtime. */
772
+ timestamp: Date;
773
+ workingDirectory: string;
734
774
  }
735
775
  /**
736
776
  * Input for pre-tool-use hook
@@ -755,6 +795,34 @@ export interface PreToolUseHookOutput {
755
795
  export type PreToolUseHandler = (input: PreToolUseHookInput, invocation: {
756
796
  sessionId: string;
757
797
  }) => Promise<PreToolUseHookOutput | void> | PreToolUseHookOutput | void;
798
+ /**
799
+ * Input for pre-MCP-tool-call hook
800
+ */
801
+ export interface PreMcpToolCallHookInput extends BaseHookInput {
802
+ toolCallId?: string;
803
+ serverName: string;
804
+ toolName: string;
805
+ arguments: unknown;
806
+ _meta?: Record<string, unknown>;
807
+ }
808
+ /**
809
+ * Output for pre-MCP-tool-call hook
810
+ */
811
+ export interface PreMcpToolCallHookOutput {
812
+ /**
813
+ * Hook-controlled metadata to use for the outgoing MCP request.
814
+ * - undefined/absent: preserve the current request `_meta`
815
+ * - object: use this object as request `_meta`
816
+ * - null: omit `_meta`
817
+ */
818
+ metaToUse?: Record<string, unknown> | null;
819
+ }
820
+ /**
821
+ * Handler for pre-MCP-tool-call hook
822
+ */
823
+ export type PreMcpToolCallHandler = (input: PreMcpToolCallHookInput, invocation: {
824
+ sessionId: string;
825
+ }) => Promise<PreMcpToolCallHookOutput | void> | PreMcpToolCallHookOutput | void;
758
826
  /**
759
827
  * Input for post-tool-use hook
760
828
  */
@@ -870,6 +938,10 @@ export interface SessionHooks {
870
938
  * Called before a tool is executed
871
939
  */
872
940
  onPreToolUse?: PreToolUseHandler;
941
+ /**
942
+ * Called before an MCP tool is called
943
+ */
944
+ onPreMcpToolCall?: PreMcpToolCallHandler;
873
945
  /**
874
946
  * Called after a tool is executed
875
947
  */
@@ -896,9 +968,11 @@ export interface SessionHooks {
896
968
  */
897
969
  interface MCPServerConfigBase {
898
970
  /**
899
- * List of tools to include from this server. [] means none. "*" means all.
971
+ * List of tools to include from this server.
972
+ * `undefined` (the default) or `["*"]` means include all tools.
973
+ * `[]` means include none.
900
974
  */
901
- tools: string[];
975
+ tools?: string[];
902
976
  /**
903
977
  * Indicates the server type: "stdio" for local/subprocess servers, "http"/"sse" for remote servers.
904
978
  * If not specified, defaults to "stdio".
@@ -920,7 +994,10 @@ export interface MCPStdioServerConfig extends MCPServerConfigBase {
920
994
  * Environment variables to pass to the server.
921
995
  */
922
996
  env?: Record<string, string>;
923
- cwd?: string;
997
+ /**
998
+ * Working directory for the server process.
999
+ */
1000
+ workingDirectory?: string;
924
1001
  }
925
1002
  /**
926
1003
  * Configuration for a remote MCP server (HTTP or SSE).
@@ -1031,12 +1108,12 @@ export interface InfiniteSessionConfig {
1031
1108
  * Valid reasoning effort levels for models that support it.
1032
1109
  */
1033
1110
  export type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
1034
- export interface SessionConfig {
1035
- /**
1036
- * Optional custom session ID
1037
- * If not provided, server will generate one
1038
- */
1039
- sessionId?: string;
1111
+ /**
1112
+ * Shared configuration fields used by both {@link SessionConfig} (for
1113
+ * creating a new session) and {@link ResumeSessionConfig} (for resuming
1114
+ * an existing one).
1115
+ */
1116
+ export interface SessionConfigBase {
1040
1117
  /**
1041
1118
  * Client name to identify the application using the SDK.
1042
1119
  * Included in the User-Agent header for API requests.
@@ -1132,12 +1209,12 @@ export interface SessionConfig {
1132
1209
  * Handler for exit-plan-mode requests from the agent.
1133
1210
  * When provided, enables `exitPlanMode.request` callbacks.
1134
1211
  */
1135
- onExitPlanMode?: ExitPlanModeHandler;
1212
+ onExitPlanModeRequest?: ExitPlanModeHandler;
1136
1213
  /**
1137
1214
  * Handler for auto-mode-switch requests from the agent.
1138
1215
  * When provided, enables `autoModeSwitch.request` callbacks.
1139
1216
  */
1140
- onAutoModeSwitch?: AutoModeSwitchHandler;
1217
+ onAutoModeSwitchRequest?: AutoModeSwitchHandler;
1141
1218
  /**
1142
1219
  * Hook handlers for intercepting session lifecycle events.
1143
1220
  * When provided, enables hooks callback allowing custom logic at various points.
@@ -1148,6 +1225,13 @@ export interface SessionConfig {
1148
1225
  * Tool operations will be relative to this directory.
1149
1226
  */
1150
1227
  workingDirectory?: string;
1228
+ /**
1229
+ * Enable streaming of assistant message and reasoning chunks.
1230
+ * When true, ephemeral assistant.message_delta and assistant.reasoning_delta
1231
+ * events are sent as the response is generated. Clients should accumulate
1232
+ * deltaContent values to build the full response.
1233
+ * @default false
1234
+ */
1151
1235
  streaming?: boolean;
1152
1236
  /**
1153
1237
  * Include sub-agent streaming events in the event stream. When true, streaming
@@ -1217,11 +1301,6 @@ export interface SessionConfig {
1217
1301
  * - `"on"` — export to GitHub AND enable remote steering
1218
1302
  */
1219
1303
  remoteSession?: RemoteSessionMode;
1220
- /**
1221
- * Creates a remote session in the cloud instead of a local session.
1222
- * The optional repository is associated with the cloud session.
1223
- */
1224
- cloud?: CloudSessionOptions;
1225
1304
  /**
1226
1305
  * Optional event handler that is registered on the session before the
1227
1306
  * session.create RPC is issued. This guarantees that early events emitted
@@ -1236,18 +1315,33 @@ export interface SessionConfig {
1236
1315
  * Supplies a handler for session filesystem operations. This takes effect
1237
1316
  * only if {@link CopilotClientOptions.sessionFs} is configured.
1238
1317
  */
1239
- createSessionFsHandler?: (session: CopilotSession) => SessionFsProvider;
1318
+ createSessionFsProvider?: (session: CopilotSession) => SessionFsProvider;
1240
1319
  }
1241
1320
  /**
1242
- * Configuration for resuming a session
1321
+ * Configuration for creating a new session via {@link CopilotClient.createSession}.
1243
1322
  */
1244
- 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"> & {
1323
+ export interface SessionConfig extends SessionConfigBase {
1324
+ /**
1325
+ * Optional custom session ID. If not provided, the server generates one.
1326
+ */
1327
+ sessionId?: string;
1328
+ /**
1329
+ * Creates a remote session in the cloud instead of a local session.
1330
+ * The optional repository is associated with the cloud session.
1331
+ */
1332
+ cloud?: CloudSessionOptions;
1333
+ }
1334
+ /**
1335
+ * Configuration for resuming an existing session via
1336
+ * {@link CopilotClient.resumeSession}.
1337
+ */
1338
+ export interface ResumeSessionConfig extends SessionConfigBase {
1245
1339
  /**
1246
1340
  * When true, skips emitting the session.resume event.
1247
1341
  * Useful for reconnecting to a session without triggering resume-related side effects.
1248
1342
  * @default false
1249
1343
  */
1250
- disableResume?: boolean;
1344
+ suppressResumeEvent?: boolean;
1251
1345
  /**
1252
1346
  * When true, the runtime continues any tool calls or permission prompts that were
1253
1347
  * still pending when the session was last suspended. When false (the default), the
@@ -1260,7 +1354,7 @@ export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "
1260
1354
  * @default false
1261
1355
  */
1262
1356
  continuePendingWork?: boolean;
1263
- };
1357
+ }
1264
1358
  /**
1265
1359
  * Configuration for a custom API provider.
1266
1360
  */
@@ -1320,7 +1414,7 @@ export interface ProviderConfig {
1320
1414
  * prompt (system message, history, tool definitions, user message) would
1321
1415
  * exceed this limit.
1322
1416
  */
1323
- maxInputTokens?: number;
1417
+ maxPromptTokens?: number;
1324
1418
  /**
1325
1419
  * Overrides the resolved model's default max output tokens. When hit, the
1326
1420
  * model stops generating and returns a truncated response.
@@ -1405,7 +1499,7 @@ export type ConnectionState = "disconnected" | "connecting" | "connected" | "err
1405
1499
  */
1406
1500
  export interface SessionContext {
1407
1501
  /** Working directory where the session was created */
1408
- cwd: string;
1502
+ workingDirectory: string;
1409
1503
  /** Git repository root (if in a git repo) */
1410
1504
  gitRoot?: string;
1411
1505
  /** GitHub repository in "owner/repo" format */
@@ -1448,8 +1542,8 @@ export interface SessionFsConfig {
1448
1542
  * Filter options for listing sessions
1449
1543
  */
1450
1544
  export interface SessionListFilter {
1451
- /** Filter by exact cwd match */
1452
- cwd?: string;
1545
+ /** Filter by exact working directory match */
1546
+ workingDirectory?: string;
1453
1547
  /** Filter by git root */
1454
1548
  gitRoot?: string;
1455
1549
  /** Filter by repository (owner/repo format) */
@@ -1466,7 +1560,7 @@ export interface SessionMetadata {
1466
1560
  modifiedTime: Date;
1467
1561
  summary?: string;
1468
1562
  isRemote: boolean;
1469
- /** Working directory context (cwd, git info) from session creation */
1563
+ /** Working directory context (working directory, git info) from session creation */
1470
1564
  context?: SessionContext;
1471
1565
  }
1472
1566
  /**
@@ -1551,35 +1645,68 @@ export interface ModelInfo {
1551
1645
  defaultReasoningEffort?: ReasoningEffort;
1552
1646
  }
1553
1647
  /**
1554
- * Types of session lifecycle events
1648
+ * Types of session lifecycle events.
1555
1649
  */
1556
1650
  export type SessionLifecycleEventType = "session.created" | "session.deleted" | "session.updated" | "session.foreground" | "session.background";
1557
1651
  /**
1558
- * Session lifecycle event notification
1559
- * Sent when sessions are created, deleted, updated, or change foreground/background state
1652
+ * Metadata payload for session lifecycle events. Not present on
1653
+ * `session.deleted` events.
1560
1654
  */
1561
- export interface SessionLifecycleEvent {
1562
- /** Type of lifecycle event */
1563
- type: SessionLifecycleEventType;
1564
- /** ID of the session this event relates to */
1655
+ export interface SessionLifecycleEventMetadata {
1656
+ /** Time the session was created. */
1657
+ startTime: Date;
1658
+ /** Time the session was last modified. */
1659
+ modifiedTime: Date;
1660
+ /** Human-readable summary of the session, if available. */
1661
+ summary?: string;
1662
+ }
1663
+ /** Base shape shared by every lifecycle event variant. */
1664
+ interface SessionLifecycleEventBase {
1665
+ /** ID of the session this event relates to. */
1565
1666
  sessionId: string;
1566
- /** Session metadata (not included for deleted sessions) */
1567
- metadata?: {
1568
- startTime: string;
1569
- modifiedTime: string;
1570
- summary?: string;
1571
- };
1667
+ /** Session metadata (not included for `session.deleted`). */
1668
+ metadata?: SessionLifecycleEventMetadata;
1669
+ }
1670
+ /** Emitted when a new session is created. */
1671
+ export interface SessionCreatedEvent extends SessionLifecycleEventBase {
1672
+ type: "session.created";
1673
+ metadata: SessionLifecycleEventMetadata;
1674
+ }
1675
+ /** Emitted when a session is deleted. The metadata field is omitted. */
1676
+ export interface SessionDeletedEvent extends SessionLifecycleEventBase {
1677
+ type: "session.deleted";
1678
+ metadata?: undefined;
1572
1679
  }
1680
+ /** Emitted when a session's metadata is updated. */
1681
+ export interface SessionUpdatedEvent extends SessionLifecycleEventBase {
1682
+ type: "session.updated";
1683
+ metadata: SessionLifecycleEventMetadata;
1684
+ }
1685
+ /** Emitted when a session is brought to the foreground (TUI+server mode). */
1686
+ export interface SessionForegroundEvent extends SessionLifecycleEventBase {
1687
+ type: "session.foreground";
1688
+ metadata: SessionLifecycleEventMetadata;
1689
+ }
1690
+ /** Emitted when a session is moved to the background (TUI+server mode). */
1691
+ export interface SessionBackgroundEvent extends SessionLifecycleEventBase {
1692
+ type: "session.background";
1693
+ metadata: SessionLifecycleEventMetadata;
1694
+ }
1695
+ /**
1696
+ * Discriminated union of all session lifecycle events emitted in TUI+server mode.
1697
+ * Switch on `type` to access the variant-specific metadata.
1698
+ */
1699
+ export type SessionLifecycleEvent = SessionCreatedEvent | SessionDeletedEvent | SessionUpdatedEvent | SessionForegroundEvent | SessionBackgroundEvent;
1573
1700
  /**
1574
- * Handler for session lifecycle events
1701
+ * Handler for session lifecycle events.
1575
1702
  */
1576
1703
  export type SessionLifecycleHandler = (event: SessionLifecycleEvent) => void;
1577
1704
  /**
1578
- * Typed handler for specific session lifecycle event types
1705
+ * Typed handler for specific session lifecycle event types.
1579
1706
  */
1580
- export type TypedSessionLifecycleHandler<K extends SessionLifecycleEventType> = (event: SessionLifecycleEvent & {
1707
+ export type TypedSessionLifecycleHandler<K extends SessionLifecycleEventType> = (event: Extract<SessionLifecycleEvent, {
1581
1708
  type: K;
1582
- }) => void;
1709
+ }>) => void;
1583
1710
  /**
1584
1711
  * Information about the foreground session in TUI+server mode
1585
1712
  */
package/dist/types.js CHANGED
@@ -1,4 +1,32 @@
1
1
  import { createSessionFsAdapter } from "./sessionFsProvider.js";
2
+ const RuntimeConnection = {
3
+ /**
4
+ * Spawn a runtime child process and communicate over its stdin/stdout.
5
+ * This is the default if no {@link CopilotClientOptions.connection} is set.
6
+ */
7
+ forStdio(opts = {}) {
8
+ return { kind: "stdio", path: opts.path, args: opts.args };
9
+ },
10
+ /**
11
+ * Spawn a runtime child process that listens on a TCP socket and connect to it.
12
+ */
13
+ forTcp(opts = {}) {
14
+ return {
15
+ kind: "tcp",
16
+ port: opts.port,
17
+ connectionToken: opts.connectionToken,
18
+ path: opts.path,
19
+ args: opts.args
20
+ };
21
+ },
22
+ /**
23
+ * Connect to an already-running runtime at the given URL. The SDK does not
24
+ * spawn a process in this mode.
25
+ */
26
+ forUri(url, opts = {}) {
27
+ return { kind: "uri", url, connectionToken: opts.connectionToken };
28
+ }
29
+ };
2
30
  function convertMcpCallToolResult(callResult) {
3
31
  const textParts = [];
4
32
  const binaryResults = [];
@@ -63,6 +91,7 @@ const defaultJoinSessionPermissionHandler = () => ({
63
91
  kind: "no-result"
64
92
  });
65
93
  export {
94
+ RuntimeConnection,
66
95
  SYSTEM_PROMPT_SECTIONS,
67
96
  approveAll,
68
97
  convertMcpCallToolResult,
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "type": "git",
5
5
  "url": "https://github.com/github/copilot-sdk.git"
6
6
  },
7
- "version": "1.0.0-beta.5",
7
+ "version": "1.0.0-beta.6",
8
8
  "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
9
9
  "main": "./dist/cjs/index.js",
10
10
  "types": "./dist/index.d.ts",
@@ -56,7 +56,7 @@
56
56
  "author": "GitHub",
57
57
  "license": "MIT",
58
58
  "dependencies": {
59
- "@github/copilot": "^1.0.51",
59
+ "@github/copilot": "^1.0.52-1",
60
60
  "vscode-jsonrpc": "^8.2.1",
61
61
  "zod": "^4.3.6"
62
62
  },