Skip to content

Commit 6195e3e

Browse files
patnikoCopilot
patniko
and
Copilot
authored
docs: update compatibility matrix with missing SDK and CLI features (#727)
Add missing SDK features to the Available section: - Session-scoped RPC APIs (model, mode, plan, workspace) - Experimental APIs (fleet, agent management, compaction) - Message delivery modes (steering/queueing) - File and directory attachments - Ping and foreground session management - Session config options (configDir, clientName, disabledSkills) Update CLI-Only section with comprehensive slash commands: - /fleet, /research, /chronicle, /context, /copy, /diagnose - /instructions, /model, /skills, /tasks, /session, /rename - /resume, /reindex, /streamer-mode, /collect-debug-logs, etc. Add missing CLI flags: - Permission flags (--allow-tool, --deny-tool, --allow-url, etc.) - Non-interactive mode (-p, -i, -s, --continue, --agent) - Terminal options (--alt-screen, --mouse, --bash-env) Add workaround sections for plan management and message steering. Update version compatibility table with actual protocol version negotiation details (v2-v3 range, automatic v2 adapters). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 7766b1a commit 6195e3e

File tree

1 file changed

+118
-16
lines changed

1 file changed

+118
-16
lines changed

‎docs/troubleshooting/compatibility.md‎

Lines changed: 118 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,15 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
2020
| Delete session | `deleteSession()` | Remove from storage |
2121
| List sessions | `listSessions()` | All stored sessions |
2222
| Get last session | `getLastSessionId()` | For quick resume |
23+
| Get foreground session | `getForegroundSessionId()` | Multi-session coordination |
24+
| Set foreground session | `setForegroundSessionId()` | Multi-session coordination |
2325
| **Messaging** | | |
2426
| Send message | `send()` | With attachments |
2527
| Send and wait | `sendAndWait()` | Blocks until complete |
28+
| Steering (immediate mode) | `send({ mode: "immediate" })` | Inject mid-turn without aborting |
29+
| Queueing (enqueue mode) | `send({ mode: "enqueue" })` | Buffer for sequential processing (default) |
30+
| File attachments | `send({ attachments: [{ type: "file", path }] })` | Images auto-encoded and resized |
31+
| Directory attachments | `send({ attachments: [{ type: "directory", path }] })` | Attach directory context |
2632
| Get history | `getMessages()` | All session events |
2733
| Abort | `abort()` | Cancel in-flight request |
2834
| **Tools** | | |
@@ -31,32 +37,56 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
3137
| Tool result modification | `onPostToolUse` hook | Transform results |
3238
| Available/excluded tools | `availableTools`, `excludedTools` config | Filter tools |
3339
| **Models** | | |
34-
| List models | `listModels()` | With capabilities |
35-
| Set model | `model` in session config | Per-session |
40+
| List models | `listModels()` | With capabilities, billing, policy |
41+
| Set model (at creation) | `model` in session config | Per-session |
42+
| Switch model (mid-session) | `session.setModel()` | Also via `session.rpc.model.switchTo()` |
43+
| Get current model | `session.rpc.model.getCurrent()` | Query active model |
3644
| Reasoning effort | `reasoningEffort` config | For supported models |
45+
| **Agent Mode** | | |
46+
| Get current mode | `session.rpc.mode.get()` | Returns current mode |
47+
| Set mode | `session.rpc.mode.set()` | Switch between modes |
48+
| **Plan Management** | | |
49+
| Read plan | `session.rpc.plan.read()` | Get plan.md content and path |
50+
| Update plan | `session.rpc.plan.update()` | Write plan.md content |
51+
| Delete plan | `session.rpc.plan.delete()` | Remove plan.md |
52+
| **Workspace Files** | | |
53+
| List workspace files | `session.rpc.workspace.listFiles()` | Files in session workspace |
54+
| Read workspace file | `session.rpc.workspace.readFile()` | Read file content |
55+
| Create workspace file | `session.rpc.workspace.createFile()` | Create file in workspace |
3756
| **Authentication** | | |
3857
| Get auth status | `getAuthStatus()` | Check login state |
3958
| Use token | `githubToken` option | Programmatic auth |
59+
| **Connectivity** | | |
60+
| Ping | `client.ping()` | Health check with server timestamp |
61+
| Get server status | `client.getStatus()` | Protocol version and server info |
4062
| **MCP Servers** | | |
4163
| Local/stdio servers | `mcpServers` config | Spawn processes |
4264
| Remote HTTP/SSE | `mcpServers` config | Connect to services |
4365
| **Hooks** | | |
4466
| Pre-tool use | `onPreToolUse` | Permission, modify args |
4567
| Post-tool use | `onPostToolUse` | Modify results |
4668
| User prompt | `onUserPromptSubmitted` | Modify prompts |
47-
| Session start/end | `onSessionStart`, `onSessionEnd` | Lifecycle |
69+
| Session start/end | `onSessionStart`, `onSessionEnd` | Lifecycle with source/reason |
4870
| Error handling | `onErrorOccurred` | Custom handling |
4971
| **Events** | | |
5072
| All session events | `on()`, `once()` | 40+ event types |
5173
| Streaming | `streaming: true` | Delta events |
52-
| **Advanced** | | |
53-
| Custom agents | `customAgents` config | Load agent definitions |
74+
| **Session Config** | | |
75+
| Custom agents | `customAgents` config | Define specialized agents |
5476
| System message | `systemMessage` config | Append or replace |
5577
| Custom provider | `provider` config | BYOK support |
5678
| Infinite sessions | `infiniteSessions` config | Auto-compaction |
5779
| Permission handler | `onPermissionRequest` | Approve/deny requests |
5880
| User input handler | `onUserInputRequest` | Handle ask_user |
5981
| Skills | `skillDirectories` config | Custom skills |
82+
| Disabled skills | `disabledSkills` config | Disable specific skills |
83+
| Config directory | `configDir` config | Override default config location |
84+
| Client name | `clientName` config | Identify app in User-Agent |
85+
| Working directory | `workingDirectory` config | Set session cwd |
86+
| **Experimental** | | |
87+
| Agent management | `session.rpc.agent.*` | List, select, deselect, get current agent |
88+
| Fleet mode | `session.rpc.fleet.start()` | Parallel sub-agent execution |
89+
| Manual compaction | `session.rpc.compaction.compact()` | Trigger compaction on demand |
6090

6191
### ❌ Not Available in SDK (CLI-Only)
6292

@@ -66,20 +96,32 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
6696
| Export to file | `--share`, `/share` | Not in protocol |
6797
| Export to gist | `--share-gist`, `/share gist` | Not in protocol |
6898
| **Interactive UI** | | |
69-
| Slash commands | `/help`, `/clear`, etc. | TUI-only |
99+
| Slash commands | `/help`, `/clear`, `/exit`, etc. | TUI-only |
70100
| Agent picker dialog | `/agent` | Interactive UI |
71101
| Diff mode dialog | `/diff` | Interactive UI |
72102
| Feedback dialog | `/feedback` | Interactive UI |
73103
| Theme picker | `/theme` | Terminal UI |
104+
| Model picker | `/model` | Interactive UI (use SDK `setModel()` instead) |
105+
| Copy to clipboard | `/copy` | Terminal-specific |
106+
| Context management | `/context` | Interactive UI |
107+
| **Research & History** | | |
108+
| Deep research | `/research` | TUI workflow with web search |
109+
| Session history tools | `/chronicle` | Standup, tips, improve, reindex |
74110
| **Terminal Features** | | |
75111
| Color output | `--no-color` | Terminal-specific |
76112
| Screen reader mode | `--screen-reader` | Accessibility |
77113
| Rich diff rendering | `--plain-diff` | Terminal rendering |
78114
| Startup banner | `--banner` | Visual element |
115+
| Streamer mode | `/streamer-mode` | TUI display mode |
116+
| Alternate screen buffer | `--alt-screen`, `--no-alt-screen` | Terminal rendering |
117+
| Mouse support | `--mouse`, `--no-mouse` | Terminal input |
79118
| **Path/Permission Shortcuts** | | |
80119
| Allow all paths | `--allow-all-paths` | Use permission handler |
81120
| Allow all URLs | `--allow-all-urls` | Use permission handler |
82-
| YOLO mode | `--yolo` | Use permission handler |
121+
| Allow all permissions | `--yolo`, `--allow-all`, `/allow-all` | Use permission handler |
122+
| Granular tool permissions | `--allow-tool`, `--deny-tool` | Use `onPreToolUse` hook |
123+
| URL access control | `--allow-url`, `--deny-url` | Use permission handler |
124+
| Reset allowed tools | `/reset-allowed-tools` | TUI command |
83125
| **Directory Management** | | |
84126
| Add directory | `/add-dir`, `--add-dir` | Configure in session |
85127
| List directories | `/list-dirs` | TUI command |
@@ -93,8 +135,13 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
93135
| User info | `/user` | TUI command |
94136
| **Session Operations** | | |
95137
| Clear conversation | `/clear` | TUI-only |
96-
| Compact context | `/compact` | Use `infiniteSessions` config |
97-
| Plan view | `/plan` | TUI-only |
138+
| Plan view | `/plan` | TUI-only (use SDK `session.rpc.plan.*` instead) |
139+
| Session management | `/session`, `/resume`, `/rename` | TUI workflow |
140+
| Fleet mode (interactive) | `/fleet` | TUI-only (use SDK `session.rpc.fleet.start()` instead) |
141+
| **Skills Management** | | |
142+
| Manage skills | `/skills` | Interactive UI |
143+
| **Task Management** | | |
144+
| View background tasks | `/tasks` | TUI command |
98145
| **Usage & Stats** | | |
99146
| Token usage | `/usage` | Subscribe to usage events |
100147
| **Code Review** | | |
@@ -103,8 +150,20 @@ The Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must b
103150
| Delegate to PR | `/delegate` | TUI workflow |
104151
| **Terminal Setup** | | |
105152
| Shell integration | `/terminal-setup` | Shell-specific |
106-
| **Experimental** | | |
107-
| Toggle experimental | `/experimental` | Runtime flag |
153+
| **Development** | | |
154+
| Toggle experimental | `/experimental`, `--experimental` | Runtime flag |
155+
| Custom instructions control | `--no-custom-instructions` | CLI flag |
156+
| Diagnose session | `/diagnose` | TUI command |
157+
| View/manage instructions | `/instructions` | TUI command |
158+
| Collect debug logs | `/collect-debug-logs` | Diagnostic tool |
159+
| Reindex workspace | `/reindex` | TUI command |
160+
| IDE integration | `/ide` | IDE-specific workflow |
161+
| **Non-interactive Mode** | | |
162+
| Prompt mode | `-p`, `--prompt` | Single-shot execution |
163+
| Interactive prompt | `-i`, `--interactive` | Auto-execute then interactive |
164+
| Silent output | `-s`, `--silent` | Script-friendly |
165+
| Continue session | `--continue` | Resume most recent |
166+
| Agent selection | `--agent <agent>` | CLI flag |
108167

109168
## Workarounds
110169

@@ -150,20 +209,55 @@ session.on("assistant.usage", (event) => {
150209

151210
### Context Compaction
152211

153-
Instead of `/compact`, configure automatic compaction:
212+
Instead of `/compact`, configure automatic compaction or trigger it manually:
154213

155214
```typescript
215+
// Automatic compaction via config
156216
const session = await client.createSession({
157217
infiniteSessions: {
158218
enabled: true,
159219
backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization
160220
bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization
161221
},
162222
});
223+
224+
// Manual compaction (experimental)
225+
const result = await session.rpc.compaction.compact();
226+
console.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);
163227
```
164228

165229
> **Note:** Thresholds are context utilization ratios (0.0-1.0), not absolute token counts.
166230
231+
### Plan Management
232+
233+
Read and write session plans programmatically:
234+
235+
```typescript
236+
// Read the current plan
237+
const plan = await session.rpc.plan.read();
238+
if (plan.exists) {
239+
console.log(plan.content);
240+
}
241+
242+
// Update the plan
243+
await session.rpc.plan.update({ content: "# My Plan\n- Step 1\n- Step 2" });
244+
245+
// Delete the plan
246+
await session.rpc.plan.delete();
247+
```
248+
249+
### Message Steering
250+
251+
Inject a message into the current LLM turn without aborting:
252+
253+
```typescript
254+
// Steer the agent mid-turn
255+
await session.send({ prompt: "Focus on error handling first", mode: "immediate" });
256+
257+
// Default: enqueue for next turn
258+
await session.send({ prompt: "Next, add tests" });
259+
```
260+
167261
## Protocol Limitations
168262

169263
The SDK can only access features exposed through the CLI's JSON-RPC protocol. If you need a CLI feature that's not available:
@@ -174,11 +268,19 @@ The SDK can only access features exposed through the CLI's JSON-RPC protocol. If
174268

175269
## Version Compatibility
176270

177-
| SDK Version | CLI Version | Protocol Version |
178-
|-------------|-------------|------------------|
179-
| Check `package.json` | `copilot --version` | `getStatus().protocolVersion` |
271+
| SDK Protocol Range | CLI Protocol Version | Compatibility |
272+
|--------------------|---------------------|---------------|
273+
| v2–v3 | v3 | Full support |
274+
| v2–v3 | v2 | Supported with automatic v2 adapters |
275+
276+
The SDK negotiates protocol versions with the CLI at startup. The SDK supports protocol versions 2 through 3. When connecting to a v2 CLI server, the SDK automatically adapts `tool.call` and `permission.request` messages to the v3 event model — no code changes required.
277+
278+
Check versions at runtime:
180279

181-
The SDK and CLI must have compatible protocol versions. The SDK will log warnings if versions are mismatched.
280+
```typescript
281+
const status = await client.getStatus();
282+
console.log("Protocol version:", status.protocolVersion);
283+
```
182284

183285
## See Also
184286

0 commit comments

Comments
 (0)