Skip to content

Rust SDK: add typed SessionCapability enum and ClientOptions builders #1455

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Morabbin wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Rust SDK: add typed SessionCapability enum and ClientOptions builders #1455

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions rust/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,9 +77,77 @@ client.stop().await?;
| `env_remove` | `Vec<OsString>` | Environment variables to remove |
| `extra_args` | `Vec<String>` | Extra CLI flags |
| `transport` | `Transport` | `Stdio` (default), `Tcp { port }`, or `External { host, port }` |
| `enabled_capabilities` | `Vec<SessionCapability>` | Capabilities to opt into at spawn time (e.g. `Memory`, `Elicitation`) |
| `disabled_capabilities` | `Vec<SessionCapability>` | Capabilities to opt out of at spawn time; disable wins on overlap |

With the default `CliProgram::Resolve`, `Client::start()` resolves the CLI in this order: an explicit `CliProgram::Path(path)`, the `COPILOT_CLI_PATH` env var, then the bundled CLI that was embedded at build time. There is no PATH scanning — if you've opted out of bundling (`default-features = false`) you must supply either `CliProgram::Path` or `COPILOT_CLI_PATH`.

### Session capabilities

`SessionCapability` is a typed enum of CLI feature toggles passed to the
spawned process via `--enable-capability` / `--disable-capability`. Use
`ClientOptions::with_enable_capability` or `with_disable_capability` (and their
plural counterparts) to build up the opt-in / opt-out lists:

```rust,ignore
use github_copilot_sdk::{Client, ClientOptions, SessionCapability};

let client = Client::start(
ClientOptions::new()
.with_enable_capability(SessionCapability::Memory)
.with_enable_capability(SessionCapability::Elicitation),
).await?;
```

**Variants:**

| Variant | Wire name | Description |
| -------------------- | ----------------------- | ----------------------------------------------------- |
| `TuiHints` | `tui-hints` | TUI keyboard shortcuts |
| `PlanMode` | `plan-mode` | `[[PLAN]]` handling and plan-mode instructions |
| `Memory` | `memory` | `store_memory` tool and `<memories>` system-prompt section |
| `CliDocumentation` | `cli-documentation` | `fetch_copilot_cli_documentation` tool and `<self_documentation>` section |
| `AskUser` | `ask-user` | `ask_user` tool for interactive clarification |
| `InteractiveMode` | `interactive-mode` | Interactive-CLI identity (vs headless) |
| `SystemNotifications`| `system-notifications` | Automatic batched system notifications to the agent |
| `Elicitation` | `elicitation` | Elicitation prompts (confirm / select / input) |
| `McpApps` | `mcp-apps` | MCP-Apps `ui://` resource passthrough (SEP-1865) |
| `CanvasRenderer` | `canvas-renderer` | Host-rendered extension canvases |
| `Other(String)` | *(verbatim)* | Forward-compat escape hatch for unknown future names |

**Disable-wins semantics.** If the same capability appears in both
`enabled_capabilities` and `disabled_capabilities`, the disable wins. The SDK
emits all enable flags first, then all disable flags, in insertion order, so
the resulting `argv` is deterministic.

**Forward compatibility.** The enum is `#[non_exhaustive]` and carries an
`Other(String)` variant so callers on older SDK builds can opt into
capabilities that the runtime adds ahead of a new SDK release, without any
recompile-blocking enum-variant additions:

```rust,ignore
use github_copilot_sdk::{ClientOptions, SessionCapability};

// Opt into a capability the SDK doesn't know about yet.
let opts = ClientOptions::new()
.with_enable_capability(SessionCapability::Other("future-cap".to_string()));
```

`&str` and `String` implement `Into<SessionCapability>`, so you can also pass
string literals directly to the builders:

```rust,ignore
use github_copilot_sdk::ClientOptions;

let opts = ClientOptions::new()
.with_enable_capability("memory") // &str coerces to SessionCapability
.with_disable_capability("plan-mode");
```

> Pairs with [github/copilot-agent-runtime#8029](https://github.com/github/copilot-agent-runtime/pull/8029)
> (CLI flag plumbing) and [github/agents#981](https://github.com/github/agents/issues/981)
> (Desktop app missing memory capability).

### Session

Created via `Client::create_session` or `Client::resume_session`. Owns an internal event loop that dispatches CLI callbacks to the focused handler traits you install on `SessionConfig`, and broadcasts session events through `subscribe()`.
Expand Down Expand Up @@ -716,6 +784,11 @@ gets to be Rust here — cross-SDK parity for these is a post-release
conversation, not a release blocker. None of these are deprecated and
none of them are scheduled for removal.

- **`SessionCapability` enum** — typed, `#[non_exhaustive]` enum for capability
opt-in / opt-out toggles passed to the CLI at spawn time, with an
`Other(String)` escape hatch for forward compatibility. See
[Session capabilities](#session-capabilities) above.
Node/Python/Go/.NET accept stringly-typed flags.
- **Typed newtypes** — `SessionId` and `RequestId` are `#[serde(transparent)]`
newtypes around `String`, so the type system distinguishes a session
identifier from an arbitrary `String` at compile time. Node/Python/Go
Expand Down
Loading
Loading