copilot-sdk git:20260524.78cd692C

Immutable. This exact content never changes and is served at /api/v1/blob/159fbc8261450fcb.

# GitHub Copilot SDK Skill

## Overview

The `@github/copilot-sdk` package provides programmatic access to GitHub Copilot's agentic workflows. It exposes the same production-tested agent runtime behind Copilot CLI with support for custom tools, **MCP servers**, streaming responses, and custom agents.

**Repository**: https://github.com/github/copilot-sdk  
**NPM Package**: `@github/copilot-sdk`  
**Current Version**: `1.0.0-beta.4` (see `package.json`)

## Architecture

```
Your Application
     ↓
SDK Client (CopilotClient)
     ↓ JSON-RPC
Copilot CLI (server mode)
     ↓
MCP Servers (optional)
```

## How This Project Uses the SDK

**Server-side** — sessions are constructed per request, **never** with
`useLoggedInUser: true`. The per-request user's GitHub token flows into
every `createSession` call. The CopilotClient itself is constructed inside
the per-user runtime pool (`src/lib/copilot/runtime/`) and Copilot
execution is routed through the mandatory worker boundary at
`src/lib/copilot/execution/`. **Web/API never imports the SDK directly —
see [`copilot-sdk-worker-only`](../copilot-sdk-worker-only/SKILL.md) for
the boundary contract.** See
[`src/lib/copilot/sessions.ts`](../../../src/lib/copilot/sessions.ts) and
[`docs/architecture-multitenant.md`](../../../docs/architecture-multitenant.md).

```typescript
import { CopilotClient } from '@github/copilot-sdk';

const client = new CopilotClient({ logLevel: 'warning', useLoggedInUser: false });
await client.start();

const session = await client.createSession({
  model: 'gpt-5-mini',
  systemMessage: { mode: 'append', content: buildSystemMessage() },
  gitHubToken,
});

// Synchronous chat
const response = await session.sendAndWait({ prompt });

// Streaming chat (event-based)
session.on('assistant.message', (event) => { /* chunk */ });
session.on('session.idle', () => { /* done */ });
session.on('session.error', (event) => { /* error */ });
await session.send({ prompt });
```

**Key patterns in this codebase**:
- System prompt built dynamically from tool definitions (`lib/copilot/system-prompt.ts`)
- Session auto-recovery on `"Session not found"` errors
- Tool definitions in `lib/tools/` generate LLM documentation automatically
- Actions extracted from LLM JSON responses via `lib/copilot/actionParser.ts`

## Custom Tools via `defineTool`

```typescript
import { defineTool } from '@github/copilot-sdk';

const myTool = defineTool('tool_name', {
  description: 'What this tool does',
  parameters: {
    type: 'object',
    properties: { city: { type: 'string', description: 'City name' } },
    required: ['city'],
  },
  handler: async (args: { city: string }) => {
    return { result: `Data for ${args.city}` };
  },
});

const session = await client.createSession({
  model: 'gpt-4.1',
  tools: [myTool],
});
```

## MCP Server Integration

Built-in support via `mcpServers` config — no separate MCP client needed.

| Type | Description | Use Case |
|------|-------------|----------|
| **local/stdio** | Subprocess via stdin/stdout | Local tools, npm packages |
| **http/sse** | Remote HTTP server | Cloud services, shared tools |

```typescript
const session = await client.createSession({
  mcpServers: {
    "github": {
      type: "http",
      url: "https://api.githubcopilot.com/mcp/",
      tools: ["*"],
    },
    "filesystem": {
      type: "local",
      command: "npx",
      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      tools: ["*"],
    },
  },
});
```

## Custom Agents

Define specialized AI personas with focused prompts. This project uses `customAgents` to create analysis specialists (SWOT, Risk, Blockers, etc.):

```typescript
import { toCustomAgentConfigs } from './copilot/agents';

const session = await client.createSession({
  model: 'gpt-5-mini',
  systemMessage: { mode: 'append', content: buildSystemMessage() },
  customAgents: toCustomAgentConfigs(), // 8 analysis agents
});
```

Agent definitions live in `lib/copilot/agents.ts`. Each has:
- `name` — SDK identifier (e.g. `canvas-swot-analyst`)
- `displayName` — Human label
- `prompt` — Specialized workflow instructions
- `id` — App-level key matching quick start template IDs

## Event Subscription

```typescript
// Subscribe to specific event type
const unsub = session.on('assistant.message_delta', (event) => {
  process.stdout.write(event.data.deltaContent);
});

// Unsubscribe when done
unsub();
```

| Event | When |
|-------|------|
| `assistant.message` | Full message received |
| `assistant.message_delta` | Streaming chunk |
| `session.idle` | Response complete |
| `session.error` | Error occurred |

## Resources

- **GitHub Repo**: https://github.com/github/copilot-sdk
- **Getting Started**: https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md
- **MCP Documentation**: https://github.com/github/copilot-sdk/blob/main/docs/mcp
- **Cookbook**: https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk