Add Rust SDK (technical preview)

.github/copilot-instructions.md

@@ -48,7 +48,7 @@
 
 ## Where to add new code or tests 🧭
 
-- SDK code: `nodejs/src`, `python/copilot`, `go`, `dotnet/src`
-- Unit tests: `nodejs/test`, `python/*`, `go/*`, `dotnet/test`
+- SDK code: `nodejs/src`, `python/copilot`, `go`, `dotnet/src`, `rust/src`
+- Unit tests: `nodejs/test`, `python/*`, `go/*`, `dotnet/test`, `rust/tests`
 - E2E tests: `*/e2e/` folders that use the shared replay proxy and `test/snapshots/`
 - Generated types: update schema in `@github/copilot` then run `cd nodejs && npm run generate:session-types` and commit generated files in `src/generated` or language generated location.

.github/skills/rust-coding-skill/examples.md

@@ -0,0 +1,184 @@
+# Rust Coding Skill — Examples
+
+Patterns specific to the Rust SDK in this repo (`rust/`) that aren't obvious
+from general Rust knowledge.
+
+## Defining a tool
+
+### Anti-pattern — building the wire payload by hand
+
+```rust
+let raw = serde_json::json!({
+    "name": "get_weather",
+    "description": "...",
+    "parameters": { "type": "object", ... },
+});
+config.tools = Some(vec![serde_json::from_value(raw)?]);
+```
+
+### Preferred — implement `ToolHandler`, route via `ToolHandlerRouter`
+
+```rust
+use copilot::tool::{Tool, ToolHandler, ToolHandlerRouter, ToolInvocation, ToolResult};
+use copilot::Error;
+
+struct GetWeatherTool;
+
+#[async_trait::async_trait]
+impl ToolHandler for GetWeatherTool {
+    fn tool(&self) -> Tool {
+        Tool {
+            name: "get_weather".to_string(),
+            description: "Get the current weather for a city.".to_string(),
+            // ..Default::default() — leaves namespaced_name, instructions,
+            // overrides_built_in_tool, skip_permission at their defaults.
+            ..Default::default()
+        }
+    }
+
+    async fn call(&self, invocation: ToolInvocation) -> Result<ToolResult, Error> {
+        // ...
+        Ok(ToolResult::Text("...".into()))
+    }
+}
+
+use copilot::handler::ApproveAllHandler;
+use std::sync::Arc;
+
+let router = ToolHandlerRouter::new(
+    vec![Box::new(GetWeatherTool)],
+    Arc::new(ApproveAllHandler),
+);
+```
+
+## Spans for spawned event loops
+
+The session event loop is spawned per session. Always attach a span so events
+emitted inside it correlate.
+
+### Anti-pattern — losing parent context
+
+```rust
+tokio::spawn(async move {
+    while let Some(event) = rx.recv().await {
+        info!("event {:?}", event);  // No span — can't filter by session
+    }
+});
+```
+
+### Preferred — `error_span!` + `.instrument()`
+
+```rust
+use tracing::Instrument;
+
+let span = tracing::error_span!("session_event_loop", session_id = %id);
+tokio::spawn(async move {
+    while let Some(event) = rx.recv().await {
+        info!(event_type = ?event.kind, "session event");
+    }
+}.instrument(span));
+```
+
+## Concurrent permission handlers
+
+`HandlerEvent::PermissionRequest` and `HandlerEvent::ExternalTool` are dispatched
+on spawned tasks (see `rust/src/session.rs:973` and `:1022`). Implementations
+must be safe for concurrent invocation.
+
+The `SessionHandler` trait declares `Send + Sync + 'static`, so the compiler
+enforces this — handlers with non-`Sync` state (e.g. `RefCell`, `Cell`,
+`Rc`) won't compile. The examples below make the rejection mechanism explicit.
+
+### Won't compile — non-`Sync` state
+
+```rust
+struct MyHandler {
+    last_request: std::cell::RefCell<Option<String>>,  // RefCell: !Sync
+}
+
+#[async_trait]
+impl SessionHandler for MyHandler {
+//   ^^^^^^^^^^^^^^ the trait `Sync` is not implemented for `RefCell<...>`
+    async fn on_event(&self, event: HandlerEvent) -> HandlerResponse { /* ... */ }
+}
+```
+
+The error surfaces at the `impl` site, not at use site, because the trait's
+`Send + Sync` bound makes `RefCell` ineligible for any field of any type that
+implements `SessionHandler`.
+
+### Preferred — `parking_lot::Mutex` or atomics
+
+```rust
+struct MyHandler {
+    last_request: parking_lot::Mutex<Option<String>>,  // Mutex<T>: Sync if T: Send
+}
+```
+
+## Adding a field to a public struct
+
+Adding a field to a public, non-exhaustive struct is a breaking change because
+existing callers' struct literals stop compiling. Two patterns soften this:
+
+### Pattern 1 — `Default` + `..Default::default()` in docs
+
+```rust
+#[derive(Default)]
+pub struct Tool {
+    pub name: String,
+    pub description: String,
+    // new field
+    pub overrides_built_in_tool: bool,
+}
+
+// In docs and examples:
+let t = Tool {
+    name: "x".into(),
+    description: "y".into(),
+    ..Default::default()
+};
+```
+
+### Pattern 2 — `#[non_exhaustive]` for types callers shouldn't construct
+
+Use sparingly — only for types that are *only* meant to be received from the
+SDK, never built by users.
+
+```rust
+#[non_exhaustive]
+pub struct CreateSessionResult {
+    pub session_id: SessionId,
+    // ...
+}
+```
+
+## Test handler for non-permission scenarios
+
+When a test doesn't exercise the permission flow, use the SDK's built-in
+`ApproveAllHandler` instead of writing a custom one:
+
+```rust
+use copilot::handler::ApproveAllHandler;
+use copilot::types::SessionConfig;
+use std::sync::Arc;
+
+let session = client
+    .create_session(SessionConfig::default().with_handler(Arc::new(ApproveAllHandler)))
+    .await?;
+```
+
+## Regenerating types after a schema bump
+
+```bash
+# 1. Update schema (usually arrives with @github/copilot package update)
+cd nodejs && npm install @github/copilot@latest && cd ..
+
+# 2. Regenerate Rust types
+cd scripts/codegen && npm run generate:rust
+
+# 3. Verify
+cd ../../rust && cargo check --all-features
+```
+
+If a generated type changes shape, hand-fix any user-facing wrappers in
+`rust/src/types.rs` rather than monkey-patching the generated file.

.github/workflows/codegen-check.yml

@@ -13,6 +13,7 @@ on:
       - 'python/copilot/generated/**'
       - 'go/generated_*.go'
       - 'go/rpc/**'
+      - 'rust/src/generated/**'
       - '.github/workflows/codegen-check.yml'
   workflow_dispatch:
 
@@ -34,6 +35,24 @@ jobs:
         with:
           go-version: '1.22'
 
+      # Rust generator runs `cargo fmt` on the output, so we need a toolchain with rustfmt.
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: "1.94.0"
+          components: rustfmt
+
+      # Nightly rustfmt for unstable format options (group_imports,
+      # imports_granularity, reorder_impl_items) — pinned in
+      # `rust/.rustfmt.nightly.toml`. The Rust generator emits unconsolidated
+      # imports under stable rustfmt; nightly fmt consolidates them to match
+      # the canonical committed form.
+      - name: Install nightly rustfmt
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: nightly-2026-04-14
+          components: rustfmt
+
       - name: Install nodejs SDK dependencies
         working-directory: ./nodejs
         run: npm ci
@@ -46,6 +65,10 @@ jobs:
         working-directory: ./scripts/codegen
         run: npm run generate
 
+      - name: Apply nightly rustfmt to generated Rust output
+        working-directory: ./rust
+        run: cargo +nightly-2026-04-14 fmt --all -- --config-path .rustfmt.nightly.toml
+
       - name: Check for uncommitted changes
         run: |
           if [ -n "$(git status --porcelain)" ]; then

.github/workflows/rust-publish-release.yml

@@ -0,0 +1,54 @@
+name: "Rust SDK: Publish Release"
+
+# Publishes the `copilot-sdk` crate to crates.io when a release-plz
+# version-bump PR is merged to `main`. See rust/RELEASING.md for the
+# full release process and one-time setup (CARGO_REGISTRY_TOKEN, etc).
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'rust/Cargo.toml'
+      - 'rust/Cargo.lock'
+      - 'rust/release-plz.toml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: rust-release-plz-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish to crates.io
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./rust
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: "1.94.0"
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: "rust"
+
+      - name: Run release-plz release
+        uses: release-plz/action@v0.5
+        with:
+          command: release
+          manifest_path: rust/Cargo.toml
+          config: rust/release-plz.toml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

.github/workflows/rust-release-pr.yml

@@ -0,0 +1,56 @@
+name: "Rust SDK: Create Release PR"
+
+# release-plz opens a PR that bumps the `copilot-sdk` version in
+# `rust/Cargo.toml` and updates `rust/CHANGELOG.md` based on
+# conventional-commit history since the last `rust-vX.Y.Z` tag.
+#
+# Review and merge that PR on the maintainer's schedule. Publishing to
+# crates.io happens separately in `rust-publish-release.yml` once the
+# version bump lands on `main`.
+#
+# Runs manually only — we don't want a PR to race with every push.
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: rust-release-plz-pr
+  cancel-in-progress: false
+
+jobs:
+  release-pr:
+    name: Create Release PR
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./rust
+    steps:
+      - uses: actions/checkout@v6.0.2
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: "1.94.0"
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: "rust"
+
+      - name: Run release-plz release-pr
+        uses: release-plz/action@v0.5
+        with:
+          command: release-pr
+          manifest_path: rust/Cargo.toml
+          config: rust/release-plz.toml
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # CARGO_REGISTRY_TOKEN is not required for release-pr (no publish),
+          # but release-plz inspects the crate on crates.io to compute the
+          # next version. Public crate inspection doesn't need auth.