nodejs — TypeScript / Node.js SDK

🎯 Why This Module Exists

The Node.js SDK exists because the Copilot CLI itself is a Node.js binary. That means (a) @github/copilot is already the dependency graph of any TypeScript project using the SDK, so bundling adds zero new runtime; (b) the maintainers of the SDK and the CLI work in the same language daily, so fixes roundtrip fast; (c) VS Code extensions and the massive Node ecosystem get first-class support immediately. Without this SDK, every TypeScript agent developer would shell out to copilot and parse stdout — losing the event stream, tool callbacks, permission flow, and streaming responses.

Because it's the reference, it tends to pioneer features. Commands and UI elicitation shipped in Node first (v0.2.0), then landed in Python/Go/.NET in v0.2.1. The enableConfigDiscovery flag, system-message transforms, and traceContextProvider all debuted here. A consequence: occasionally the Node SDK has capabilities no other SDK does yet — check CHANGELOG.md before relying on parity.

🏗️ Design Decisions

Architecture

classDiagram
  class CopilotClient {
    +options: CopilotClientOptions
    -process: ChildProcess
    -connection: MessageConnection
    -sessions: Map~string, CopilotSession~
    +start()
    +stop()
    +createSession(cfg)
    +resumeSession(id)
    +listSessions()
    +listModels()
    +getAuthStatus()
    +getStatus()
  }
  class CopilotSession {
    +sessionId: string
    +capabilities: SessionCapabilities
    -eventHandlers: Set~Handler~
    -toolHandlers: Map~name, Handler~
    -permissionHandler?
    -elicitationHandler?
    -hooks?: SessionHooks
    +on(handler) Unsub
    +send(opts) Promise~messageId~
    +sendAndWait(opts, timeout)
    +disconnect()
    +ui SessionUiApi
  }
  class SessionFsProvider
  class Tool {
    +name: string
    +description: string
    +parameters: JSONSchema | ZodSchema
    +handler: ToolHandler
  }
  class SessionEvent {
    <>
    assistant.message
    session.idle
    session.error
    tool.call_started
    permission.requested
    ...40+ variants
  }
  CopilotClient "1" o-- "*" CopilotSession : manages
  CopilotSession "1" o-- "*" Tool : invokes
  CopilotSession ..> SessionEvent : emits
  CopilotClient ..> SessionFsProvider : wraps via adapter

Session Lifecycle & Event Pump

sequenceDiagram
    participant App
    participant Client as CopilotClient
    participant CLI as copilot subprocess
    participant Session as CopilotSession

    App->>Client: new CopilotClient(opts)
    App->>Client: await client.createSession(cfg)
    Client->>CLI: spawn if needed
    Client->>CLI: JSON-RPC: getStatus
    CLI-->>Client: protocolVersion=3, capabilities
    Client->>CLI: JSON-RPC: session.create
    CLI-->>Client: sessionId + session capabilities
    Client-->>App: Session instance
    App->>Session: session.on(handler)
    App->>Session: await session.sendAndWait({prompt})
    Session->>Session: pre-register idle/error listener
    Session->>CLI: session.send
    loop agent turn
      CLI-->>Session: event: assistant.message (partial)
      Session-->>App: handler fires
      CLI->>Session: RPC: session/toolInvoke
      Session->>App: tool handler runs
      App-->>Session: result
      Session-->>CLI: RPC reply
    end
    CLI-->>Session: event: session.idle
    Session-->>App: resolve sendAndWait promise
    App->>Client: await client.stop()
    Client->>CLI: JSON-RPC: shutdown
    Client->>CLI: SIGTERM if no graceful exit

Key Components

⚡ Algorithm Spotlight

sendAndWait race-free idle detection

Problem. A fast-returning LLM can emit session.idle before the caller attaches a listener. Pre-registering the listener before sending the RPC closes the gap.

Chosen over: polling isIdle (misses transient states); synchronous subscribe inside the send RPC (vscode-jsonrpc doesn't cleanly support this). Complexity: O(1) per event.

// Register event handler BEFORE calling send to avoid race condition
// where session.idle fires before we start listening
const unsubscribe = this.on((event) => {
    if (event.type === "assistant.message") {
        lastAssistantMessage = event;
    } else if (event.type === "session.idle") {
        resolveIdle();
    } else if (event.type === "session.error") {
        const error = new Error(event.data.message);
        error.stack = event.data.stack;
        rejectWithError(error);
    }
});
// ... now safe to send
await this.send(options);

System-message transform wire trick

User-supplied functions can't cross JSON-RPC. So extractTransformCallbacks replaces each function with {action:"transform"}, stores the originals in a Map, and when the server round-trips a sections.transform RPC, the stored callback runs and the result is returned.

Protocol version negotiation

On connect, getStatus returns {protocolVersion, capabilities}. Client checks protocolVersion >= MIN_PROTOCOL_VERSION (2); lower rejects with an error. Cached negotiatedProtocolVersion drives capability gates like NO_RESULT_PERMISSION_V2_ERROR (the no-result permission return value is only legal on v2+).

⚠ What Could Go Wrong

📊 Performance Profile

The hot path is the event pump: a single Set.forEach(h => h(event)) per event, O(handlers) per dispatch. No allocation beyond the event object itself. Session creation is one RPC round-trip (~10ms localhost) plus subprocess spawn on first call (~50-100ms, amortised across later sessions on the same client). The bottleneck for large workloads is JSON serialisation of tool results — no streaming-tool-results protocol exists (would require a protocol extension). Memory per idle session is ~1 MB (event handler sets + tools map + capability cache); 10 sessions with 20 tools each = 200 handler closures but still well under 10 MB total.

What was optimised for: correctness and type safety. What was sacrificed: throughput for tool-heavy workloads (each tool invocation is a JSON-RPC round trip, so ~100 tool calls/sec is the practical ceiling per session).

Deep-Dive Highlights

Core mechanisms extracted into dedicated focus pages.

Configuration Reference

Code Examples

Minimal client & session

import { CopilotClient, approveAll } from "@github/copilot-sdk";

const client = new CopilotClient({ model: "gpt-4" });

const session = await client.createSession({
    onPermissionRequest: approveAll,
});

session.on((event) => {
    if (event.type === "assistant.message") {
        console.log(event.data.content);
    }
});

const final = await session.sendAndWait({ prompt: "Hello, world!" });
console.log("final:", final?.data.content);

await client.stop();

Custom tool with Zod

import { defineTool } from "@github/copilot-sdk";
import { z } from "zod";

const getWeather = defineTool({
    name: "get_weather",
    description: "Get current weather for a city",
    parameters: z.object({
        city: z.string(),
        unit: z.enum(["C", "F"]).optional(),
    }),
    handler: async ({ city, unit }) => {
        return `Cloudy, 62°${unit ?? "F"} in ${city}`;
    },
});

const session = await client.createSession({
    tools: [getWeather],
    onPermissionRequest: approveAll,
});

sendAndWait signature (from session.ts)

async sendAndWait(
    options: MessageOptions,
    timeout?: number
): Promise<AssistantMessageEvent | undefined> {
    const effectiveTimeout = timeout ?? 60_000;
    // ... pre-registers idle/error listener before send (race fix)
    await this.send(options);
    await Promise.race([idlePromise, timeoutPromise]);
    // ...
    return lastAssistantMessage;
}

Public surface (from index.ts)

export { CopilotClient } from "./client.js";
export { CopilotSession, type AssistantMessageEvent } from "./session.js";
export {
    defineTool,
    approveAll,
    convertMcpCallToolResult,
    createSessionFsAdapter,
    SYSTEM_PROMPT_SECTIONS,
} from "./types.js";
// + 80 individual type re-exports

Directory Map

nodejs/
├── src/
│   ├── client.ts                 ← CopilotClient — process & connection lifecycle
│   ├── session.ts                ← CopilotSession — one conversation + event pump
│   ├── types.ts                  ← All public types (1735 lines)
│   ├── sessionFsProvider.ts      ← SessionFs adapter + error translation
│   ├── telemetry.ts              ← W3C Trace Context plumbing
│   ├── sdkProtocolVersion.ts     ← Embedded protocol version constant
│   ├── extension.ts              ← VS Code extension seed
│   ├── index.ts                  ← Public re-exports
│   └── generated/
│       ├── rpc.ts                ← Codegen'd RPC client/server factories
│       └── session-events.ts     ← Codegen'd SessionEvent union (40+ types)
├── samples/
│   └── chat.ts                   ← Interactive chat demo
├── examples/
│   └── basic-example.ts          ← Minimal walkthrough
├── scripts/
│   └── update-protocol-version.ts← Sync sdk-protocol-version.json
├── test/e2e/                     ← End-to-end tests
├── docs/                         ← Per-SDK docs fragments
├── esbuild-copilotsdk-nodejs.ts  ← Build pipeline
└── package.json