RomanNum3ral
/
claw-code
mirror of https://github.com/instructkr/claw-code.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' of https://github.com/dowlingwong/claw-code

This commit is contained in:
Dowling_Wong 2026-04-07 16:13:01 +02:00
parent 54adf9f2ba 092d8b6e21
commit c55c56e24a
75 changed files with 14257 additions and 1755 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/FUNDING.yml vendored
View File

@ -1 +1,3 @@
github: instructkr
github:
- ultraworkers
- Yeachan-Heo

45
.github/scripts/check_doc_source_of_truth.py vendored Executable file
View File

@ -0,0 +1,45 @@
#!/usr/bin/env python3
from __future__ import annotations
from pathlib import Path
import re
import sys
ROOT = Path(__file__).resolve().parents[2]
FILES = [
ROOT / 'README.md',
ROOT / 'USAGE.md',
ROOT / 'PARITY.md',
ROOT / 'PHILOSOPHY.md',
ROOT / 'ROADMAP.md',
ROOT / '.github' / 'FUNDING.yml',
]
FILES.extend(sorted((ROOT / 'docs').rglob('*.md')) if (ROOT / 'docs').exists() else [])
FORBIDDEN = {
r'github\.com/Yeachan-Heo/claw-code(?!-parity)': 'replace old claw-code GitHub links with ultraworkers/claw-code',
r'github\.com/code-yeongyu/claw-code': 'replace stale alternate claw-code GitHub links with ultraworkers/claw-code',
r'discord\.gg/6ztZB9jvWq': 'replace the stale UltraWorkers Discord invite with the current invite',
r'api\.star-history\.com/svg\?repos=Yeachan-Heo/claw-code': 'update star-history embeds to ultraworkers/claw-code',
r'star-history\.com/#Yeachan-Heo/claw-code': 'update star-history links to ultraworkers/claw-code',
r'assets/clawd-hero\.jpeg': 'rename stale hero asset references to assets/claw-hero.jpeg',
r'assets/instructkr\.png': 'remove stale instructkr image references',
}
errors: list[str] = []
for path in FILES:
if not path.exists():
continue
text = path.read_text(encoding='utf-8')
for pattern, message in FORBIDDEN.items():
for match in re.finditer(pattern, text):
line = text.count('\n', 0, match.start()) + 1
errors.append(f'{path.relative_to(ROOT)}:{line}: {message}')
if errors:
print('doc source-of-truth check failed:', file=sys.stderr)
for error in errors:
print(f' - {error}', file=sys.stderr)
sys.exit(1)
print('doc source-of-truth check passed')

68
.github/workflows/release.yml vendored Normal file
View File

@ -0,0 +1,68 @@
name: Release binaries
on:
push:
tags:
- 'v*'
workflow_dispatch:
permissions:
contents: write
concurrency:
group: release-${{ github.ref }}
cancel-in-progress: false
env:
CARGO_TERM_COLOR: always
jobs:
build:
name: build-${{ matrix.name }}
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
include:
- name: linux-x64
os: ubuntu-latest
bin: claw
artifact_name: claw-linux-x64
- name: macos-arm64
os: macos-14
bin: claw
artifact_name: claw-macos-arm64
defaults:
run:
working-directory: rust
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
with:
workspaces: rust -> target
- name: Build release binary
run: cargo build --release -p rusty-claude-cli
- name: Package artifact
shell: bash
run: |
mkdir -p dist
cp "target/release/${{ matrix.bin }}" "dist/${{ matrix.artifact_name }}"
chmod +x "dist/${{ matrix.artifact_name }}"
- name: Upload workflow artifact
uses: actions/upload-artifact@v4
with:
name: ${{ matrix.artifact_name }}
path: rust/dist/${{ matrix.artifact_name }}
- name: Upload release asset
if: startsWith(github.ref, 'refs/tags/')
uses: softprops/action-gh-release@v2
with:
files: rust/dist/${{ matrix.artifact_name }}
fail_on_unmatched_files: true

52
.github/workflows/rust-ci.yml vendored
View File

@ -8,12 +8,28 @@ on:
- 'omx-issue-*'
paths:
- .github/workflows/rust-ci.yml
- .github/scripts/check_doc_source_of_truth.py
- .github/FUNDING.yml
- README.md
- USAGE.md
- PARITY.md
- PHILOSOPHY.md
- ROADMAP.md
- docs/**
- rust/**
pull_request:
branches:
- main
paths:
- .github/workflows/rust-ci.yml
- .github/scripts/check_doc_source_of_truth.py
- .github/FUNDING.yml
- README.md
- USAGE.md
- PARITY.md
- PHILOSOPHY.md
- ROADMAP.md
- docs/**
- rust/**
workflow_dispatch:
@ -29,6 +45,20 @@ env:
CARGO_TERM_COLOR: always
jobs:
doc-source-of-truth:
name: docs source-of-truth
runs-on: ubuntu-latest
defaults:
run:
working-directory: .
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Check docs and metadata for stale branding
run: python .github/scripts/check_doc_source_of_truth.py
fmt:
name: cargo fmt
runs-on: ubuntu-latest
@ -43,8 +73,8 @@ jobs:
- name: Check formatting
run: cargo fmt --all --check
test-rusty-claude-cli:
name: cargo test -p rusty-claude-cli
test-workspace:
name: cargo test --workspace
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
@ -52,5 +82,19 @@ jobs:
- uses: Swatinem/rust-cache@v2
with:
workspaces: rust -> target
- name: Run crate tests
run: cargo test -p rusty-claude-cli
- name: Run workspace tests
run: cargo test --workspace
clippy-workspace:
name: cargo clippy --workspace
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
with:
components: clippy
- uses: Swatinem/rust-cache@v2
with:
workspaces: rust -> target
- name: Run workspace clippy
run: cargo clippy --workspace

13
Containerfile Normal file
View File

@ -0,0 +1,13 @@
FROM rust:bookworm
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
ca-certificates \
git \
libssl-dev \
pkg-config \
&& rm -rf /var/lib/apt/lists/*
ENV CARGO_TERM_COLOR=always
WORKDIR /workspace
CMD ["bash"]

207
README.md
View File

@ -1,7 +1,17 @@
# Rewriting Project Claw Code
# Claw Code
<p align="center">
<strong>⭐ The fastest repo in history to surpass 50K stars, reaching the milestone in just 2 hours after publication ⭐</strong>
<a href="https://github.com/ultraworkers/claw-code">ultraworkers/claw-code</a>
·
<a href="./USAGE.md">Usage</a>
·
<a href="./rust/README.md">Rust workspace</a>
·
<a href="./PARITY.md">Parity</a>
·
<a href="./ROADMAP.md">Roadmap</a>
·
<a href="https://discord.gg/5TUQKqFWd">UltraWorkers Discord</a>
</p>
<p align="center">
@ -9,188 +19,75 @@
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" width="600" />
<img alt="Star history for ultraworkers/claw-code" src="https://api.star-history.com/svg?repos=ultraworkers/claw-code&type=Date" width="600" />
</picture>
</a>
</p>
<p align="center">
<img src="assets/clawd-hero.jpeg" alt="Claw" width="300" />
<img src="assets/claw-hero.jpeg" alt="Claw Code" width="300" />
</p>
<p align="center">
<strong>Autonomously maintained by lobsters/claws — not by human hands</strong>
</p>
<p align="center">
<a href="https://github.com/Yeachan-Heo/clawhip">clawhip</a> ·
<a href="https://github.com/code-yeongyu/oh-my-openagent">oh-my-openagent</a> ·
<a href="https://github.com/Yeachan-Heo/oh-my-claudecode">oh-my-claudecode</a> ·
<a href="https://github.com/Yeachan-Heo/oh-my-codex">oh-my-codex</a> ·
<a href="https://discord.gg/6ztZB9jvWq">UltraWorkers Discord</a>
</p>
Claw Code is the public Rust implementation of the `claw` CLI agent harness.
The canonical implementation lives in [`rust/`](./rust), and the current source of truth for this repository is **ultraworkers/claw-code**.
> [!IMPORTANT]
> The active Rust workspace now lives in [`rust/`](./rust). Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows, then use [`rust/README.md`](./rust/README.md) for crate-level details.
> Start with [`USAGE.md`](./USAGE.md) for build, auth, CLI, session, and parity-harness workflows. Make `claw doctor` your first health check after building, use [`rust/README.md`](./rust/README.md) for crate-level details, read [`PARITY.md`](./PARITY.md) for the current Rust-port checkpoint, and see [`docs/container.md`](./docs/container.md) for the container-first workflow.
> Want the bigger idea behind this repo? Read [`PHILOSOPHY.md`](./PHILOSOPHY.md) and Sigrid Jin's public explanation: https://x.com/realsigridjin/status/2039472968624185713
## Current repository shape
> Shout-out to the UltraWorkers ecosystem powering this repo: [clawhip](https://github.com/Yeachan-Heo/clawhip), [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent), [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex), and the [UltraWorkers Discord](https://discord.gg/6ztZB9jvWq).
- **`rust/`** — canonical Rust workspace and the `claw` CLI binary
- **`USAGE.md`** — task-oriented usage guide for the current product surface
- **`PARITY.md`** — Rust-port parity status and migration notes
- **`ROADMAP.md`** — active roadmap and cleanup backlog
- **`PHILOSOPHY.md`** — project intent and system-design framing
- **`src/` + `tests/`** — companion Python/reference workspace and audit helpers; not the primary runtime surface
---
## Backstory
This repo is maintained by **lobsters/claws**, not by a conventional human-only dev team.
The people behind the system are [Bellman / Yeachan Heo](https://github.com/Yeachan-Heo) and friends like [Yeongyu](https://github.com/code-yeongyu), but the repo itself is being pushed forward by autonomous claw workflows: parallel coding sessions, event-driven orchestration, recovery loops, and machine-readable lane state.
In practice, that means this project is not just *about* coding agents — it is being **actively built by them**. Features, tests, telemetry, docs, and workflow hardening are landed through claw-driven loops using [clawhip](https://github.com/Yeachan-Heo/clawhip), [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent), [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode), and [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex).
This repository exists to prove that an open coding harness can be built **autonomously, in public, and at high velocity** — with humans setting direction and claws doing the grinding.
See the public build story here:
https://x.com/realsigridjin/status/2039472968624185713
![Tweet screenshot](assets/tweet-screenshot.png)
---
## Porting Status
The main source tree is now Python-first.
- `src/` contains the active Python porting workspace
- `tests/` verifies the current Python workspace
- the exposed snapshot is no longer part of the tracked repository state
The current Python workspace is not yet a complete one-to-one replacement for the original system, but the primary implementation surface is now Python.
## Why this rewrite exists
I originally studied the exposed codebase to understand its harness, tool wiring, and agent workflow. After spending more time with the legal and ethical questions—and after reading the essay linked below—I did not want the exposed snapshot itself to remain the main tracked source tree.
This repository now focuses on Python porting work instead.
## Repository Layout
```text
.
├── src/ # Python porting workspace
│ ├── __init__.py
│ ├── commands.py
│ ├── main.py
│ ├── models.py
│ ├── port_manifest.py
│ ├── query_engine.py
│ ├── task.py
│ └── tools.py
├── tests/ # Python verification
├── assets/omx/ # OmX workflow screenshots
├── 2026-03-09-is-legal-the-same-as-legitimate-ai-reimplementation-and-the-erosion-of-copyleft.md
└── README.md
```
## Python Workspace Overview
The new Python `src/` tree currently provides:
- **`port_manifest.py`** — summarizes the current Python workspace structure
- **`models.py`** — dataclasses for subsystems, modules, and backlog state
- **`commands.py`** — Python-side command port metadata
- **`tools.py`** — Python-side tool port metadata
- **`query_engine.py`** — renders a Python porting summary from the active workspace
- **`main.py`** — a CLI entrypoint for manifest and summary output
## Quickstart
Render the Python porting summary:
## Quick start
```bash
python3 -m src.main summary
cd rust
cargo build --workspace
./target/debug/claw --help
./target/debug/claw prompt "summarize this repository"
```
Print the current Python workspace manifest:
Authenticate with either an API key or the built-in OAuth flow:
```bash
python3 -m src.main manifest
export ANTHROPIC_API_KEY="sk-ant-..."
# or
cd rust
./target/debug/claw login
```
List the current Python modules:
Run the workspace test suite:
```bash
python3 -m src.main subsystems --limit 16
cd rust
cargo test --workspace
```
Run verification:
## Documentation map
```bash
python3 -m unittest discover -s tests -v
```
- [`USAGE.md`](./USAGE.md) — quick commands, auth, sessions, config, parity harness
- [`rust/README.md`](./rust/README.md) — crate map, CLI surface, features, workspace layout
- [`PARITY.md`](./PARITY.md) — parity status for the Rust port
- [`rust/MOCK_PARITY_HARNESS.md`](./rust/MOCK_PARITY_HARNESS.md) — deterministic mock-service harness details
- [`ROADMAP.md`](./ROADMAP.md) — active roadmap and open cleanup work
- [`PHILOSOPHY.md`](./PHILOSOPHY.md) — why the project exists and how it is operated
Run the parity audit against the local ignored archive (when present):
## Ecosystem
```bash
python3 -m src.main parity-audit
```
Claw Code is built in the open alongside the broader UltraWorkers toolchain:
Inspect mirrored command/tool inventories:
- [clawhip](https://github.com/Yeachan-Heo/clawhip)
- [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent)
- [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
- [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- [UltraWorkers Discord](https://discord.gg/5TUQKqFWd)
```bash
python3 -m src.main commands --limit 10
python3 -m src.main tools --limit 10
```
Run a local Ollama-backed chat prompt:
```bash
ollama run qwen2.5-coder:7b
python3 -m src.main chat "write a hello world in python"
```
The local chat path uses Ollama at `http://localhost:11434` by default and sends a single non-streaming `/api/chat` request to `qwen2.5-coder:7b`.
For the current local agent/tool integration, request features, and command examples, see [`OLLAMA_INTEGRATION.md`](./OLLAMA_INTEGRATION.md).
## Current Parity Checkpoint
The port now mirrors the archived root-entry file surface, top-level subsystem names, and command/tool inventories much more closely than before. However, it is **not yet** a full runtime-equivalent replacement for the original TypeScript system; the Python tree still contains fewer executable runtime slices than the archived source.
## Built with `oh-my-codex`
The restructuring and documentation work on this repository was AI-assisted and orchestrated with Yeachan Heo's [oh-my-codex (OmX)](https://github.com/Yeachan-Heo/oh-my-codex), layered on top of Codex.
- **`$team` mode:** used for coordinated parallel review and architectural feedback
- **`$ralph` mode:** used for persistent execution, verification, and completion discipline
- **Codex-driven workflow:** used to turn the main `src/` tree into a Python-first porting workspace
### OmX workflow screenshots
![OmX workflow screenshot 1](assets/omx/omx-readme-review-1.png)
*Ralph/team orchestration view while the README and essay context were being reviewed in terminal panes.*
![OmX workflow screenshot 2](assets/omx/omx-readme-review-2.png)
*Split-pane review and verification flow during the final README wording pass.*
## Community
<p align="center">
<a href="https://discord.gg/6ztZB9jvWq"><img src="https://img.shields.io/badge/UltraWorkers-Discord-5865F2?logo=discord&style=for-the-badge" alt="UltraWorkers Discord" /></a>
</p>
Join the [**UltraWorkers Discord**](https://discord.gg/6ztZB9jvWq) — the community around clawhip, oh-my-openagent, oh-my-claudecode, oh-my-codex, and claw-code. Come chat about LLMs, harness engineering, agent workflows, and autonomous software development.
[![Discord](https://img.shields.io/badge/Join%20Discord-UltraWorkers-5865F2?logo=discord&style=for-the-badge)](https://discord.gg/6ztZB9jvWq)
## Star History
See the chart at the top of this README.
## Ownership / Affiliation Disclaimer
## Ownership / affiliation disclaimer
- This repository does **not** claim ownership of the original Claude Code source material.
- This repository is **not affiliated with, endorsed by, or maintained by Anthropic**.

54
ROADMAP.md
View File

@ -271,15 +271,18 @@ Acceptance:
Priority order: P0 = blocks CI/green state, P1 = blocks integration wiring, P2 = clawability hardening, P3 = swarm-efficiency improvements.
**P0 — Fix first (CI reliability)**
1. Isolate `render_diff_report` tests into tmpdir — flaky under `cargo test --workspace`; reads real working-tree state; breaks CI during active worktree ops
2. Expand GitHub CI from single-crate coverage to workspace-grade verification — current `rust-ci.yml` runs `cargo fmt` and `cargo test -p rusty-claude-cli`, but misses broader `cargo test --workspace` coverage that already passes locally
3. Add release-grade binary workflow — repo has a Rust CLI and release intent, but no GitHub Actions path that builds tagged artifacts / checks release packaging before a publish step
4. Add container-first test/run docs — runtime detects Docker/Podman/container state, but docs do not show a canonical container workflow for `cargo test --workspace`, binary execution, or bind-mounted repo usage
5. Surface `doctor` / preflight diagnostics in onboarding docs and help — the CLI already has setup-diagnosis commands and branch preflight machinery, but they are not prominent enough in README/USAGE, so new users still ask manual setup questions instead of running a built-in health check first
6. Add branding/source-of-truth residue checks for docs — after repo migration, old org names can survive in badges, star-history URLs, and copied snippets; docs need a consistency pass or CI lint to catch stale branding automatically
7. Reconcile README product narrative with current repo reality — top-level docs now say the active workspace is Rust, but later sections still describe the repo as Python-first; users should not have to infer which implementation is canonical
8. Eliminate warning spam from first-run help/build path — `cargo run -p rusty-claude-cli -- --help` currently prints a wall of compile warnings before the actual help text, which pollutes the first-touch UX and hides the product surface behind unrelated noise
9. Promote `doctor` from slash-only to top-level CLI entrypoint — users naturally try `claw doctor`, but today it errors and tells them to enter a REPL or resume path first; healthcheck flows should be callable directly from the shell
1. Isolate `render_diff_report` tests into tmpdir — **done**: `render_diff_report_for()` tests run in temp git repos instead of the live working tree, and targeted `cargo test -p rusty-claude-cli render_diff_report -- --nocapture` now stays green during branch/worktree activity
2. Expand GitHub CI from single-crate coverage to workspace-grade verification — **done**: `.github/workflows/rust-ci.yml` now runs `cargo test --workspace` plus fmt/clippy at the workspace level
3. Add release-grade binary workflow — **done**: `.github/workflows/release.yml` now builds tagged Rust release artifacts for the CLI
4. Add container-first test/run docs — **done**: `Containerfile` + `docs/container.md` document the canonical Docker/Podman workflow for build, bind-mount, and `cargo test --workspace` usage
5. Surface `doctor` / preflight diagnostics in onboarding docs and help — **done**: README + USAGE now put `claw doctor` / `/doctor` in the first-run path and point at the built-in preflight report
6. Automate branding/source-of-truth residue checks in CI — **done**: `.github/scripts/check_doc_source_of_truth.py` and the `doc-source-of-truth` CI job now block stale repo/org/invite residue in tracked docs and metadata
7. Eliminate warning spam from first-run help/build path — **done**: current `cargo run -q -p rusty-claude-cli -- --help` renders clean help output without a warning wall before the product surface
8. Promote `doctor` from slash-only to top-level CLI entrypoint — **done**: `claw doctor` is now a local shell entrypoint with regression coverage for direct help and health-report output
9. Make machine-readable status commands actually machine-readable — **done**: `claw --output-format json status` and `claw --output-format json sandbox` now emit structured JSON snapshots instead of prose tables
10. Unify legacy config/skill namespaces in user-facing output — **done**: skills/help JSON/text output now present `.claw` as the canonical namespace and collapse legacy roots behind `.claw`-shaped source ids/labels
11. Honor JSON output on inventory commands like `skills` and `mcp` — **done**: direct CLI inventory commands now honor `--output-format json` with structured payloads for both skills and MCP inventory
12. Audit `--output-format` contract across the whole CLI surface — **done**: direct CLI commands now honor deterministic JSON/text handling across help/version/status/sandbox/agents/mcp/skills/bootstrap-plan/system-prompt/init/doctor, with regression coverage in `output_format_contract.rs` and resumed `/status` JSON coverage
**P1 — Next (integration wiring, unblocks verification)**
2. Add cross-module integration tests — **done**: 12 integration tests covering worker→recovery→policy, stale_branch→policy, green_contract→policy, reconciliation flows
@ -297,11 +300,38 @@ Priority order: P0 = blocks CI/green state, P1 = blocks integration wiring, P2 =
12. Lane board / machine-readable status API — **done**: Lane completion hardening + `LaneContext::completed` auto-detection + MCP degraded reporting surface machine-readable state
13. **Session completion failure classification** — **done**: `WorkerFailureKind::Provider` + `observe_completion()` + recovery recipe bridge landed
14. **Config merge validation gap** — **done**: `config.rs` hook validation before deep-merge (+56 lines), malformed entries fail with source-path context instead of merged parse errors
15. **MCP manager discovery flaky test** — `manager_discovery_report_keeps_healthy_servers_when_one_server_fails` has intermittent timing issues in CI; temporarily ignored, needs root cause fix
15. **MCP manager discovery flaky test** — **done**: `manager_discovery_report_keeps_healthy_servers_when_one_server_fails` now runs as a normal workspace test again after repeated stable passes, so degraded-startup coverage is no longer hidden behind `#[ignore]`
16. **Commit provenance / worktree-aware push events** — **done**: `LaneCommitProvenance` now carries branch/worktree/canonical-commit/supersession metadata in lane events, and `dedupe_superseded_commit_events()` is applied before agent manifests are written so superseded commit events collapse to the latest canonical lineage
17. **Orphaned module integration audit** — **done**: `runtime` now keeps `session_control` and `trust_resolver` behind `#[cfg(test)]` until they are wired into a real non-test execution path, so normal builds no longer advertise dead clawability surface area.
18. **Context-window preflight gap** — **done**: provider request sizing now emits `context_window_blocked` before oversized requests leave the process, using a model-context registry instead of the old naive max-token heuristic.
19. **Subcommand help falls through into runtime/API path** — **done**: `claw doctor --help`, `claw status --help`, `claw sandbox --help`, and nested `mcp`/`skills` help are now intercepted locally without runtime/provider startup, with regression tests covering the direct CLI paths.
20. **Session state classification gap (working vs blocked vs finished vs truly stale)** — **done**: agent manifests now derive machine states such as `working`, `blocked_background_job`, `blocked_merge_conflict`, `degraded_mcp`, `interrupted_transport`, `finished_pending_report`, and `finished_cleanable`, and terminal-state persistence records commit provenance plus derived state so downstream monitoring can distinguish quiet progress from truly idle sessions.
21. **Resumed `/status` JSON parity gap** — dogfooding shows fresh `claw status --output-format json` now emits structured JSON, but resumed slash-command status still leaks through a text-shaped path in at least one dispatch path. Local CI-equivalent repro fails `rust/crates/rusty-claude-cli/tests/resume_slash_commands.rs::resumed_status_command_emits_structured_json_when_requested` with `expected value at line 1 column 1`, so resumed automation can receive text where JSON was explicitly requested. **Action:** unify fresh vs resumed `/status` rendering through one output-format contract and add regression coverage so resumed JSON output is guaranteed valid.
22. **Opaque failure surface for session/runtime crashes** — repeated dogfood-facing failures can currently collapse to generic wrappers like `Something went wrong while processing your request. Please try again, or use /new to start a fresh session.` without exposing whether the fault was provider auth, session corruption, slash-command dispatch, render failure, or transport/runtime panic. This blocks fast self-recovery and turns actionable clawability bugs into blind retries. **Action:** preserve a short user-safe failure class (`provider_auth`, `session_load`, `command_dispatch`, `render`, `runtime_panic`, etc.), attach a local trace/session id, and ensure operators can jump from the chat-visible error to the exact failure log quickly.
23. **`doctor --output-format json` check-level structure gap** — **done**: `claw doctor --output-format json` now keeps the human-readable `message`/`report` while also emitting structured per-check diagnostics (`name`, `status`, `summary`, `details`, plus typed fields like workspace paths and sandbox fallback data), with regression coverage in `output_format_contract.rs`.
24. **Plugin lifecycle init/shutdown test flakes under workspace-parallel execution** — dogfooding surfaced that `build_runtime_runs_plugin_lifecycle_init_and_shutdown` can fail under `cargo test --workspace` while passing in isolation because sibling tests race on tempdir-backed shell init script paths. This is test brittleness rather than a code-path regression, but it still destabilizes CI confidence and wastes diagnosis cycles. **Action:** isolate temp resources per test robustly (unique dirs + no shared cwd assumptions), audit cleanup timing, and add a regression guard so the plugin lifecycle test remains stable under parallel workspace execution.
26. **Resumed local-command JSON parity gap** — **done**: direct `claw --output-format json` already had structured renderers for `sandbox`, `mcp`, `skills`, `version`, and `init`, but resumed `claw --output-format json --resume <session> /…` paths still fell back to prose because resumed slash dispatch only emitted JSON for `/status`. Resumed `/sandbox`, `/mcp`, `/skills`, `/version`, and `/init` now reuse the same JSON envelopes as their direct CLI counterparts, with regression coverage in `rust/crates/rusty-claude-cli/tests/resume_slash_commands.rs` and `rust/crates/rusty-claude-cli/tests/output_format_contract.rs`.
41. **Phantom completions root cause: global session store has no per-worktree isolation** —
**Root cause.** The session store under `~/.local/share/opencode` is global to the host. Every `opencode serve` instance — including the parallel lane workers spawned per worktree — reads and writes the same on-disk session directory. Sessions are keyed only by id and timestamp, not by the workspace they were created in, so there is no structural barrier between a session created in worktree `/tmp/b4-phantom-diag` and one created in `/tmp/b4-omc-flat`. Whichever serve instance picks up a given session id can drive it from whatever CWD that serve happens to be running in.
**Impact.** Parallel lanes silently cross wires. A lane reports a clean run — file edits, builds, tests — and the orchestrator marks the lane green, but the writes were applied against another worktree's CWD because a sibling `opencode serve` won the session race. The originating worktree shows no diff, the *other* worktree gains unexplained edits, and downstream consumers (clawhip lane events, PR pushes, merge gates) treat the empty originator as a successful no-op. These are the "phantom completions" we keep chasing: success messaging without any landed changes in the lane that claimed them, plus stray edits in unrelated lanes whose own runs never touched those files. Because the report path is happy, retries and recovery recipes never fire, so the lane silently wedges until a human notices the diff is empty.
**Proposed fix.** Bind every session to its workspace root + branch at creation time and refuse to drive it from any other CWD.
- At session creation, capture the canonical workspace root (resolved git worktree path) and the active branch and persist them on the session record.
- On every load (`opencode serve`, slash-command resume, lane recovery), validate that the current process CWD matches the persisted workspace root before any tool with side effects (file_ops, bash, git) is allowed to run. Mismatches surface as a typed `WorkspaceMismatch` failure class instead of silently writing to the wrong tree.
- Namespace the on-disk session path under the workspace fingerprint (e.g. `<session_store>/<workspace_hash>/<session_id>`) so two parallel `opencode serve` instances physically cannot collide on the same session id.
- Forks inherit the parent's workspace root by default; an explicit re-bind is required to move a session to a new worktree, and that re-bind is itself recorded as a structured event so the orchestrator can audit cross-worktree handoffs.
- Surface a `branch.workspace_mismatch` lane event so clawhip stops counting wrong-CWD writes as lane completions.
**Status.** A `workspace_root` field has been added to `Session` in `rust/crates/runtime/src/session.rs` (with builder, accessor, JSON + JSONL round-trip, fork inheritance, and given/when/then test coverage in `persists_workspace_root_round_trip_and_forks_inherit_it`). The CWD validation, the namespaced on-disk path, and the `branch.workspace_mismatch` lane event are still outstanding and tracked under this item.
**P3 — Swarm efficiency**
13. Swarm branch-lock protocol — detect same-module/same-branch collision before parallel workers drift into duplicate implementation
14. Commit provenance / worktree-aware push events — emit branch, worktree, superseded-by, and canonical commit lineage so parallel sessions stop producing duplicate-looking push summaries
13. Swarm branch-lock protocol — **done**: `branch_lock::detect_branch_lock_collisions()` now detects same-branch/same-scope and nested-module collisions before parallel lanes drift into duplicate implementation
14. Commit provenance / worktree-aware push events — **done**: lane event provenance now includes branch/worktree/superseded/canonical lineage metadata, and manifest persistence de-dupes superseded commit events before downstream consumers render them
## Suggested Session Split

179
USAGE.md
View File

@ -1,6 +1,20 @@
# Claw Code Usage
This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary.
This guide covers the current Rust workspace under `rust/` and the `claw` CLI binary. If you are brand new, make the doctor health check your first run: start `claw`, then run `/doctor`.
## Quick-start health check
Run this before prompts, sessions, or automation:
```bash
cd rust
cargo build --workspace
./target/debug/claw
# first command inside the REPL
/doctor
```
`/doctor` is the built-in setup and preflight diagnostic. Once you have a saved session, you can rerun it with `./target/debug/claw --resume latest /doctor`.
## Prerequisites
@ -10,17 +24,25 @@ This guide covers the current Rust workspace under `rust/` and the `claw` CLI bi
- `claw login` for OAuth-based auth
- Optional: `ANTHROPIC_BASE_URL` when targeting a proxy or local service
## Build the workspace
## Install / build the workspace
```bash
cd rust
cargo build --workspace
```
The CLI binary is available at `rust/target/debug/claw` after a debug build.
The CLI binary is available at `rust/target/debug/claw` after a debug build. Make the doctor check above your first post-build step.
## Quick start
### First-run doctor check
```bash
cd rust
./target/debug/claw
/doctor
```
### Interactive REPL
```bash
@ -87,6 +109,157 @@ cd rust
./target/debug/claw logout
```
## Local Models
`claw` can talk to local servers and provider gateways through either Anthropic-compatible or OpenAI-compatible endpoints. Use `ANTHROPIC_BASE_URL` with `ANTHROPIC_AUTH_TOKEN` for Anthropic-compatible services, or `OPENAI_BASE_URL` with `OPENAI_API_KEY` for OpenAI-compatible services. OAuth is Anthropic-only, so when `OPENAI_BASE_URL` is set you should use API-key style auth instead of `claw login`.
### Anthropic-compatible endpoint
```bash
export ANTHROPIC_BASE_URL="http://127.0.0.1:8080"
export ANTHROPIC_AUTH_TOKEN="local-dev-token"
cd rust
./target/debug/claw --model "claude-sonnet-4-6" prompt "reply with the word ready"
```
### OpenAI-compatible endpoint
```bash
export OPENAI_BASE_URL="http://127.0.0.1:8000/v1"
export OPENAI_API_KEY="local-dev-token"
cd rust
./target/debug/claw --model "qwen2.5-coder" prompt "reply with the word ready"
```
### Ollama
```bash
export OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
unset OPENAI_API_KEY
cd rust
./target/debug/claw --model "llama3.2" prompt "summarize this repository in one sentence"
```
### OpenRouter
```bash
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_API_KEY="sk-or-v1-..."
cd rust
./target/debug/claw --model "openai/gpt-4.1-mini" prompt "summarize this repository in one sentence"
```
## Supported Providers & Models
`claw` has three built-in provider backends. The provider is selected automatically based on the model name, falling back to whichever credential is present in the environment.
### Provider matrix
| Provider | Protocol | Auth env var(s) | Base URL env var | Default base URL |
|---|---|---|---|---|
| **Anthropic** (direct) | Anthropic Messages API | `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` or OAuth (`claw login`) | `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` |
| **xAI** | OpenAI-compatible | `XAI_API_KEY` | `XAI_BASE_URL` | `https://api.x.ai/v1` |
| **OpenAI-compatible** | OpenAI Chat Completions | `OPENAI_API_KEY` | `OPENAI_BASE_URL` | `https://api.openai.com/v1` |
The OpenAI-compatible backend also serves as the gateway for **OpenRouter**, **Ollama**, and any other service that speaks the OpenAI `/v1/chat/completions` wire format — just point `OPENAI_BASE_URL` at the service.
### Tested models and aliases
These are the models registered in the built-in alias table with known token limits:
| Alias | Resolved model name | Provider | Max output tokens | Context window |
|---|---|---|---|---|
| `opus` | `claude-opus-4-6` | Anthropic | 32 000 | 200 000 |
| `sonnet` | `claude-sonnet-4-6` | Anthropic | 64 000 | 200 000 |
| `haiku` | `claude-haiku-4-5-20251213` | Anthropic | 64 000 | 200 000 |
| `grok` / `grok-3` | `grok-3` | xAI | 64 000 | 131 072 |
| `grok-mini` / `grok-3-mini` | `grok-3-mini` | xAI | 64 000 | 131 072 |
| `grok-2` | `grok-2` | xAI | — | — |
Any model name that does not match an alias is passed through verbatim. This is how you use OpenRouter model slugs (`openai/gpt-4.1-mini`), Ollama tags (`llama3.2`), or full Anthropic model IDs (`claude-sonnet-4-20250514`).
### User-defined aliases
You can add custom aliases in any settings file (`~/.claw/settings.json`, `.claw/settings.json`, or `.claw/settings.local.json`):
```json
{
"aliases": {
"fast": "claude-haiku-4-5-20251213",
"smart": "claude-opus-4-6",
"cheap": "grok-3-mini"
}
}
```
Local project settings override user-level settings. Aliases resolve through the built-in table, so `"fast": "haiku"` also works.
### How provider detection works
1. If the resolved model name starts with `claude` → Anthropic.
2. If it starts with `grok` → xAI.
3. Otherwise, `claw` checks which credential is set: `ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN` first, then `OPENAI_API_KEY`, then `XAI_API_KEY`.
4. If nothing matches, it defaults to Anthropic.
## FAQ
### What about Codex?
The name "codex" appears in the Claw Code ecosystem but it does **not** refer to OpenAI Codex (the code-generation model). Here is what it means in this project:
- **`oh-my-codex` (OmX)** is the workflow and plugin layer that sits on top of `claw`. It provides planning modes, parallel multi-agent execution, notification routing, and other automation features. See [PHILOSOPHY.md](./PHILOSOPHY.md) and the [oh-my-codex repo](https://github.com/Yeachan-Heo/oh-my-codex).
- **`.codex/` directories** (e.g. `.codex/skills`, `.codex/agents`, `.codex/commands`) are legacy lookup paths that `claw` still scans alongside the primary `.claw/` directories.
- **`CODEX_HOME`** is an optional environment variable that points to a custom root for user-level skill and command lookups.
`claw` does **not** support OpenAI Codex sessions, the Codex CLI, or Codex session import/export. If you need to use OpenAI models (like GPT-4.1), configure the OpenAI-compatible provider as shown above in the [OpenAI-compatible endpoint](#openai-compatible-endpoint) and [OpenRouter](#openrouter) sections.
## HTTP proxy support
`claw` honours the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables (both upper- and lower-case spellings are accepted) when issuing outbound requests to Anthropic, OpenAI-, and xAI-compatible endpoints. Set them before launching the CLI and the underlying `reqwest` client will be configured automatically.
### Environment variables
```bash
export HTTPS_PROXY="http://proxy.corp.example:3128"
export HTTP_PROXY="http://proxy.corp.example:3128"
export NO_PROXY="localhost,127.0.0.1,.corp.example"
cd rust
./target/debug/claw prompt "hello via the corporate proxy"
```
### Programmatic `proxy_url` config option
As an alternative to per-scheme environment variables, the `ProxyConfig` type exposes a `proxy_url` field that acts as a single catch-all proxy for both HTTP and HTTPS traffic. When `proxy_url` is set it takes precedence over the separate `http_proxy` and `https_proxy` fields.
```rust
use api::{build_http_client_with, ProxyConfig};
// From a single unified URL (config file, CLI flag, etc.)
let config = ProxyConfig::from_proxy_url("http://proxy.corp.example:3128");
let client = build_http_client_with(&config).expect("proxy client");
// Or set the field directly alongside NO_PROXY
let config = ProxyConfig {
proxy_url: Some("http://proxy.corp.example:3128".to_string()),
no_proxy: Some("localhost,127.0.0.1".to_string()),
..ProxyConfig::default()
};
let client = build_http_client_with(&config).expect("proxy client");
```
### Notes
- When both `HTTPS_PROXY` and `HTTP_PROXY` are set, the secure proxy applies to `https://` URLs and the plain proxy applies to `http://` URLs.
- `proxy_url` is a unified alternative: when set, it applies to both `http://` and `https://` destinations, overriding the per-scheme fields.
- `NO_PROXY` accepts a comma-separated list of host suffixes (for example `.corp.example`) and IP literals.
- Empty values are treated as unset, so leaving `HTTPS_PROXY=""` in your shell will not enable a proxy.
- If a proxy URL cannot be parsed, `claw` falls back to a direct (no-proxy) client so existing workflows keep working; double-check the URL if you expected the request to be tunnelled.
## Common operational commands
```bash

0
assets/clawd-hero.jpeg → assets/claw-hero.jpeg
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 233 KiB

After

Width:  |  Height:  |  Size: 233 KiB

BIN
assets/instructkr.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.8 KiB

BIN
assets/sigrid-photo.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 73 KiB

132
docs/container.md Normal file
View File

@ -0,0 +1,132 @@
# Container-first claw-code workflows
This repo already had **container detection** in the Rust runtime before this document was added:
- `rust/crates/runtime/src/sandbox.rs` detects Docker/Podman/container markers such as `/.dockerenv`, `/run/.containerenv`, matching env vars, and `/proc/1/cgroup` hints.
- `rust/crates/rusty-claude-cli/src/main.rs` exposes that state through the `claw sandbox` / `cargo run -p rusty-claude-cli -- sandbox` report.
- `.github/workflows/rust-ci.yml` runs on `ubuntu-latest`, but it does **not** define a Docker or Podman container job.
- Before this change, the repo did **not** have a checked-in `Dockerfile`, `Containerfile`, or `.devcontainer/` config.
This document adds a small checked-in `Containerfile` so Docker and Podman users have one canonical container workflow.
## What the checked-in container image is for
The root [`../Containerfile`](../Containerfile) gives you a reusable Rust build/test shell with the extra packages this workspace commonly needs (`git`, `pkg-config`, `libssl-dev`, certificates).
It does **not** copy the repository into the image. Instead, the recommended flow is to bind-mount your checkout into `/workspace` so edits stay on the host.
## Build the image
From the repository root:
### Docker
```bash
docker build -t claw-code-dev -f Containerfile .
```
### Podman
```bash
podman build -t claw-code-dev -f Containerfile .
```
## Run `cargo test --workspace` in the container
These commands mount the repo, keep Cargo build artifacts out of the working tree, and run from the Rust workspace at `rust/`.
### Docker
```bash
docker run --rm -it \
-v "$PWD":/workspace \
-e CARGO_TARGET_DIR=/tmp/claw-target \
-w /workspace/rust \
claw-code-dev \
cargo test --workspace
```
### Podman
```bash
podman run --rm -it \
-v "$PWD":/workspace:Z \
-e CARGO_TARGET_DIR=/tmp/claw-target \
-w /workspace/rust \
claw-code-dev \
cargo test --workspace
```
If you want a fully clean rebuild, add `cargo clean &&` before `cargo test --workspace`.
## Open a shell in the container
### Docker
```bash
docker run --rm -it \
-v "$PWD":/workspace \
-e CARGO_TARGET_DIR=/tmp/claw-target \
-w /workspace/rust \
claw-code-dev
```
### Podman
```bash
podman run --rm -it \
-v "$PWD":/workspace:Z \
-e CARGO_TARGET_DIR=/tmp/claw-target \
-w /workspace/rust \
claw-code-dev
```
Inside the shell:
```bash
cargo build --workspace
cargo test --workspace
cargo run -p rusty-claude-cli -- --help
cargo run -p rusty-claude-cli -- sandbox
```
The `sandbox` command is a useful sanity check: inside Docker or Podman it should report `In container true` and list the markers the runtime detected.
## Bind-mount this repo and another repo at the same time
If you want to run `claw` against a second checkout while keeping `claw-code` itself mounted read-write:
### Docker
```bash
docker run --rm -it \
-v "$PWD":/workspace \
-v "$HOME/src/other-repo":/repo \
-e CARGO_TARGET_DIR=/tmp/claw-target \
-w /workspace/rust \
claw-code-dev
```
### Podman
```bash
podman run --rm -it \
-v "$PWD":/workspace:Z \
-v "$HOME/src/other-repo":/repo:Z \
-e CARGO_TARGET_DIR=/tmp/claw-target \
-w /workspace/rust \
claw-code-dev
```
Then, for example:
```bash
cargo run -p rusty-claude-cli -- prompt "summarize /repo"
```
## Notes
- Docker and Podman use the same checked-in `Containerfile`.
- The `:Z` suffix in the Podman examples is for SELinux relabeling; keep it on Fedora/RHEL-class hosts.
- Running with `CARGO_TARGET_DIR=/tmp/claw-target` avoids leaving container-owned `target/` artifacts in your bind-mounted checkout.
- For non-container local development, keep using [`../USAGE.md`](../USAGE.md) and [`../rust/README.md`](../rust/README.md).

394
install.sh Executable file
View File

@ -0,0 +1,394 @@
#!/usr/bin/env bash
# Claw Code installer
#
# Detects the host OS, verifies the Rust toolchain (rustc + cargo),
# builds the `claw` binary from the `rust/` workspace, and runs a
# post-install verification step. Supports Linux, macOS, and WSL.
#
# Usage:
# ./install.sh # debug build (fast, default)
# ./install.sh --release # optimized release build
# ./install.sh --no-verify # skip post-install verification
# ./install.sh --help # print usage
#
# Environment overrides:
# CLAW_BUILD_PROFILE=debug|release same as --release toggle
# CLAW_SKIP_VERIFY=1 same as --no-verify
set -euo pipefail
# ---------------------------------------------------------------------------
# Pretty printing
# ---------------------------------------------------------------------------
if [ -t 1 ] && command -v tput >/dev/null 2>&1 && [ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]; then
COLOR_RESET="$(tput sgr0)"
COLOR_BOLD="$(tput bold)"
COLOR_DIM="$(tput dim)"
COLOR_RED="$(tput setaf 1)"
COLOR_GREEN="$(tput setaf 2)"
COLOR_YELLOW="$(tput setaf 3)"
COLOR_BLUE="$(tput setaf 4)"
COLOR_CYAN="$(tput setaf 6)"
else
COLOR_RESET=""
COLOR_BOLD=""
COLOR_DIM=""
COLOR_RED=""
COLOR_GREEN=""
COLOR_YELLOW=""
COLOR_BLUE=""
COLOR_CYAN=""
fi
CURRENT_STEP=0
TOTAL_STEPS=6
step() {
CURRENT_STEP=$((CURRENT_STEP + 1))
printf '\n%s[%d/%d]%s %s%s%s\n' \
"${COLOR_BLUE}" "${CURRENT_STEP}" "${TOTAL_STEPS}" "${COLOR_RESET}" \
"${COLOR_BOLD}" "$1" "${COLOR_RESET}"
}
info() { printf '%s ->%s %s\n' "${COLOR_CYAN}" "${COLOR_RESET}" "$1"; }
ok() { printf '%s ok%s %s\n' "${COLOR_GREEN}" "${COLOR_RESET}" "$1"; }
warn() { printf '%s warn%s %s\n' "${COLOR_YELLOW}" "${COLOR_RESET}" "$1"; }
error() { printf '%s error%s %s\n' "${COLOR_RED}" "${COLOR_RESET}" "$1" 1>&2; }
print_banner() {
printf '%s' "${COLOR_BOLD}"
cat <<'EOF'
____ _ ____ _
/ ___|| | __ _ __ __ / ___|___ __| | ___
| | | | / _` |\ \ /\ / /| | / _ \ / _` |/ _ \
| |___ | || (_| | \ V V / | |__| (_) | (_| | __/
\____||_| \__,_| \_/\_/ \____\___/ \__,_|\___|
EOF
printf '%s\n' "${COLOR_RESET}"
printf '%sClaw Code installer%s\n' "${COLOR_DIM}" "${COLOR_RESET}"
}
print_usage() {
cat <<'EOF'
Usage: ./install.sh [options]
Options:
--release Build the optimized release profile (slower, smaller binary).
--debug Build the debug profile (default, faster compile).
--no-verify Skip the post-install verification step.
-h, --help Show this help text and exit.
Environment overrides:
CLAW_BUILD_PROFILE debug | release
CLAW_SKIP_VERIFY set to 1 to skip verification
EOF
}
# ---------------------------------------------------------------------------
# Argument parsing
# ---------------------------------------------------------------------------
BUILD_PROFILE="${CLAW_BUILD_PROFILE:-debug}"
SKIP_VERIFY="${CLAW_SKIP_VERIFY:-0}"
while [ "$#" -gt 0 ]; do
case "$1" in
--release)
BUILD_PROFILE="release"
;;
--debug)
BUILD_PROFILE="debug"
;;
--no-verify)
SKIP_VERIFY="1"
;;
-h|--help)
print_usage
exit 0
;;
*)
error "unknown argument: $1"
print_usage
exit 2
;;
esac
shift
done
case "${BUILD_PROFILE}" in
debug|release) ;;
*)
error "invalid build profile: ${BUILD_PROFILE} (expected debug or release)"
exit 2
;;
esac
# ---------------------------------------------------------------------------
# Troubleshooting hints
# ---------------------------------------------------------------------------
print_troubleshooting() {
cat <<EOF
${COLOR_BOLD}Troubleshooting${COLOR_RESET}
${COLOR_DIM}---------------${COLOR_RESET}
${COLOR_BOLD}1. Rust toolchain missing${COLOR_RESET}
Install Rust via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Then reload your shell or run:
source "\$HOME/.cargo/env"
${COLOR_BOLD}2. Linux: missing system packages${COLOR_RESET}
The build needs git, pkg-config, and OpenSSL headers.
Debian/Ubuntu:
sudo apt-get update && sudo apt-get install -y \\
git pkg-config libssl-dev ca-certificates build-essential
Fedora/RHEL:
sudo dnf install -y git pkgconf-pkg-config openssl-devel gcc
Arch:
sudo pacman -S --needed git pkgconf openssl base-devel
${COLOR_BOLD}3. macOS: missing Xcode CLT${COLOR_RESET}
Install the command line tools:
xcode-select --install
${COLOR_BOLD}4. Windows users${COLOR_RESET}
Run this script from inside a WSL distro (Ubuntu/Debian recommended).
Native Windows builds are not supported by this installer.
${COLOR_BOLD}5. Build fails partway through${COLOR_RESET}
Try a clean build:
cd rust && cargo clean && cargo build --workspace
If the failure mentions ring/openssl, double check step 2.
${COLOR_BOLD}6. 'claw' not found after install${COLOR_RESET}
The binary lives at:
rust/target/${BUILD_PROFILE}/claw
Add it to your PATH or invoke it with the full path.
EOF
}
trap 'rc=$?; if [ "$rc" -ne 0 ]; then error "installation failed (exit ${rc})"; print_troubleshooting; fi' EXIT
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
require_cmd() {
command -v "$1" >/dev/null 2>&1
}
# ---------------------------------------------------------------------------
# Step 1: detect OS / arch / WSL
# ---------------------------------------------------------------------------
print_banner
step "Detecting host environment"
UNAME_S="$(uname -s 2>/dev/null || echo unknown)"
UNAME_M="$(uname -m 2>/dev/null || echo unknown)"
OS_FAMILY="unknown"
IS_WSL="0"
case "${UNAME_S}" in
Linux*)
OS_FAMILY="linux"
if grep -qiE 'microsoft|wsl' /proc/version 2>/dev/null; then
IS_WSL="1"
fi
;;
Darwin*)
OS_FAMILY="macos"
;;
MINGW*|MSYS*|CYGWIN*)
OS_FAMILY="windows-shell"
;;
esac
info "uname: ${UNAME_S} ${UNAME_M}"
info "os family: ${OS_FAMILY}"
if [ "${IS_WSL}" = "1" ]; then
info "wsl: yes"
fi
case "${OS_FAMILY}" in
linux|macos)
ok "supported platform detected"
;;
windows-shell)
error "Detected a native Windows shell (MSYS/Cygwin/MinGW)."
error "Please re-run this script from inside a WSL distribution."
exit 1
;;
*)
error "Unsupported or unknown OS: ${UNAME_S}"
error "Supported: Linux, macOS, and Windows via WSL."
exit 1
;;
esac
# ---------------------------------------------------------------------------
# Step 2: locate the Rust workspace
# ---------------------------------------------------------------------------
step "Locating the Rust workspace"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
RUST_DIR="${SCRIPT_DIR}/rust"
if [ ! -d "${RUST_DIR}" ]; then
error "Could not find rust/ workspace next to install.sh"
error "Expected: ${RUST_DIR}"
exit 1
fi
if [ ! -f "${RUST_DIR}/Cargo.toml" ]; then
error "Missing ${RUST_DIR}/Cargo.toml — repository layout looks unexpected."
exit 1
fi
ok "workspace at ${RUST_DIR}"
# ---------------------------------------------------------------------------
# Step 3: prerequisite checks
# ---------------------------------------------------------------------------
step "Checking prerequisites"
MISSING_PREREQS=0
if require_cmd rustc; then
RUSTC_VERSION="$(rustc --version 2>/dev/null || echo 'unknown')"
ok "rustc found: ${RUSTC_VERSION}"
else
error "rustc not found in PATH"
MISSING_PREREQS=1
fi
if require_cmd cargo; then
CARGO_VERSION="$(cargo --version 2>/dev/null || echo 'unknown')"
ok "cargo found: ${CARGO_VERSION}"
else
error "cargo not found in PATH"
MISSING_PREREQS=1
fi
if require_cmd git; then
ok "git found: $(git --version 2>/dev/null || echo 'unknown')"
else
warn "git not found — some workflows (login, session export) may degrade"
fi
if [ "${OS_FAMILY}" = "linux" ]; then
if require_cmd pkg-config; then
ok "pkg-config found"
else
warn "pkg-config not found — may be required for OpenSSL-linked crates"
fi
fi
if [ "${OS_FAMILY}" = "macos" ]; then
if ! require_cmd cc && ! xcode-select -p >/dev/null 2>&1; then
warn "Xcode command line tools not detected — run: xcode-select --install"
fi
fi
if [ "${MISSING_PREREQS}" -ne 0 ]; then
error "Missing required tools. See troubleshooting below."
exit 1
fi
# ---------------------------------------------------------------------------
# Step 4: build the workspace
# ---------------------------------------------------------------------------
step "Building the claw workspace (${BUILD_PROFILE})"
CARGO_FLAGS=("build" "--workspace")
if [ "${BUILD_PROFILE}" = "release" ]; then
CARGO_FLAGS+=("--release")
fi
info "running: cargo ${CARGO_FLAGS[*]}"
info "this may take a few minutes on the first build"
(
cd "${RUST_DIR}"
CARGO_TERM_COLOR="${CARGO_TERM_COLOR:-always}" cargo "${CARGO_FLAGS[@]}"
)
CLAW_BIN="${RUST_DIR}/target/${BUILD_PROFILE}/claw"
if [ ! -x "${CLAW_BIN}" ]; then
error "Expected binary not found at ${CLAW_BIN}"
error "The build reported success but the binary is missing — check cargo output above."
exit 1
fi
ok "built ${CLAW_BIN}"
# ---------------------------------------------------------------------------
# Step 5: post-install verification
# ---------------------------------------------------------------------------
step "Verifying the installed binary"
if [ "${SKIP_VERIFY}" = "1" ]; then
warn "verification skipped (--no-verify or CLAW_SKIP_VERIFY=1)"
else
info "running: claw --version"
if VERSION_OUT="$("${CLAW_BIN}" --version 2>&1)"; then
ok "claw --version -> ${VERSION_OUT}"
else
error "claw --version failed:"
printf '%s\n' "${VERSION_OUT}" 1>&2
exit 1
fi
info "running: claw --help (smoke test)"
if "${CLAW_BIN}" --help >/dev/null 2>&1; then
ok "claw --help responded"
else
error "claw --help failed"
exit 1
fi
fi
# ---------------------------------------------------------------------------
# Step 6: next steps
# ---------------------------------------------------------------------------
step "Next steps"
cat <<EOF
${COLOR_GREEN}Claw Code is built and ready.${COLOR_RESET}
Binary: ${COLOR_BOLD}${CLAW_BIN}${COLOR_RESET}
Profile: ${BUILD_PROFILE}
Try it out:
${COLOR_DIM}# interactive REPL${COLOR_RESET}
${CLAW_BIN}
${COLOR_DIM}# one-shot prompt${COLOR_RESET}
${CLAW_BIN} prompt "summarize this repository"
${COLOR_DIM}# health check (run /doctor inside the REPL)${COLOR_RESET}
${CLAW_BIN}
/doctor
Authentication:
export ANTHROPIC_API_KEY="sk-ant-..."
${COLOR_DIM}# or use OAuth:${COLOR_RESET}
${CLAW_BIN} login
For deeper docs, see USAGE.md and rust/README.md.
EOF
# clear the failure trap on clean exit
trap - EXIT

2
rust/.claw/sessions/session-1775386832313-0.jsonl Normal file
View File

@ -0,0 +1,2 @@
{"created_at_ms":1775386832313,"session_id":"session-1775386832313-0","type":"session_meta","updated_at_ms":1775386832313,"version":1}
{"message":{"blocks":[{"text":"status --help","type":"text"}],"role":"user"},"type":"message"}

2
rust/.claw/sessions/session-1775386842352-0.jsonl Normal file
View File

@ -0,0 +1,2 @@
{"created_at_ms":1775386842352,"session_id":"session-1775386842352-0","type":"session_meta","updated_at_ms":1775386842352,"version":1}
{"message":{"blocks":[{"text":"doctor --help","type":"text"}],"role":"user"},"type":"message"}

2
rust/.claw/sessions/session-1775386852257-0.jsonl Normal file
View File

@ -0,0 +1,2 @@
{"created_at_ms":1775386852257,"session_id":"session-1775386852257-0","type":"session_meta","updated_at_ms":1775386852257,"version":1}
{"message":{"blocks":[{"text":"doctor --help","type":"text"}],"role":"user"},"type":"message"}

2
rust/.claw/sessions/session-1775386853666-0.jsonl Normal file
View File

@ -0,0 +1,2 @@
{"created_at_ms":1775386853666,"session_id":"session-1775386853666-0","type":"session_meta","updated_at_ms":1775386853666,"version":1}
{"message":{"blocks":[{"text":"status --help","type":"text"}],"role":"user"},"type":"message"}

2
rust/Cargo.lock generated
View File

@ -1579,6 +1579,8 @@ name = "tools"
version = "0.1.0"
dependencies = [
"api",
"commands",
"flate2",
"plugins",
"reqwest",
"runtime",

138
rust/README.md
View File

@ -79,28 +79,29 @@ Primary artifacts:
| Feature | Status |
|---------|--------|
| Anthropic API + streaming | ✅ |
| Anthropic / OpenAI-compatible provider flows + streaming | ✅ |
| OAuth login/logout | ✅ |
| Interactive REPL (rustyline) | ✅ |
| Tool system (bash, read, write, edit, grep, glob) | ✅ |
| Web tools (search, fetch) | ✅ |
| Sub-agent orchestration | ✅ |
| Sub-agent / agent surfaces | ✅ |
| Todo tracking | ✅ |
| Notebook editing | ✅ |
| CLAUDE.md / project memory | ✅ |
| Config file hierarchy (.claude.json) | ✅ |
| Config file hierarchy (`.claw.json` + merged config sections) | ✅ |
| Permission system | ✅ |
| MCP server lifecycle | ✅ |
| MCP server lifecycle + inspection | ✅ |
| Session persistence + resume | ✅ |
| Extended thinking (thinking blocks) | ✅ |
| Cost tracking + usage display | ✅ |
| Cost / usage / stats surfaces | ✅ |
| Git integration | ✅ |
| Markdown terminal rendering (ANSI) | ✅ |
| Model aliases (opus/sonnet/haiku) | ✅ |
| Slash commands (/status, /compact, /clear, etc.) | ✅ |
| Hooks (PreToolUse/PostToolUse) | 🔧 Config only |
| Plugin system | 📋 Planned |
| Skills registry | 📋 Planned |
| Direct CLI subcommands (`status`, `sandbox`, `agents`, `mcp`, `skills`, `doctor`) | ✅ |
| Slash commands (including `/skills`, `/agents`, `/mcp`, `/doctor`, `/plugin`, `/subagent`) | ✅ |
| Hooks (`/hooks`, config-backed lifecycle hooks) | ✅ |
| Plugin management surfaces | ✅ |
| Skills inventory / install surfaces | ✅ |
| Machine-readable JSON output across core CLI surfaces | ✅ |
## Model Aliases
@ -112,87 +113,96 @@ Short names resolve to the latest model versions:
| `sonnet` | `claude-sonnet-4-6` |
| `haiku` | `claude-haiku-4-5-20251213` |
## CLI Flags
## CLI Flags and Commands
```
Representative current surface:
```text
claw [OPTIONS] [COMMAND]
Options:
--model MODEL Override the active model
--dangerously-skip-permissions Skip all permission checks
--permission-mode MODE Set read-only, workspace-write, or danger-full-access
--allowedTools TOOLS Restrict enabled tools
--output-format FORMAT Non-interactive output format (text or json)
--resume SESSION Re-open a saved session or inspect it with slash commands
--version, -V Print version and build information locally
Flags:
--model MODEL
--output-format text|json
--permission-mode MODE
--dangerously-skip-permissions
--allowedTools TOOLS
--resume [SESSION.jsonl|session-id|latest]
--version, -V
Commands:
prompt <text> One-shot prompt (non-interactive)
login Authenticate via OAuth
logout Clear stored credentials
init Initialize project config
status Show the current workspace status snapshot
sandbox Show the current sandbox isolation snapshot
agents Inspect agent definitions
mcp Inspect configured MCP servers
skills Inspect installed skills
system-prompt Render the assembled system prompt
Top-level commands:
prompt <text>
help
version
status
sandbox
dump-manifests
bootstrap-plan
agents
mcp
skills
system-prompt
login
logout
init
```
For the current canonical help text, run `cargo run -p rusty-claude-cli -- --help`.
The command surface is moving quickly. For the canonical live help text, run:
```bash
cargo run -p rusty-claude-cli -- --help
```
## Slash Commands (REPL)
Tab completion expands slash commands, model aliases, permission modes, and recent session IDs.
| Command | Description |
|---------|-------------|
| `/help` | Show help |
| `/status` | Show session status (model, tokens, cost) |
| `/cost` | Show cost breakdown |
| `/compact` | Compact conversation history |
| `/clear` | Clear conversation |
| `/model [name]` | Show or switch model |
| `/permissions` | Show or switch permission mode |
| `/config [section]` | Show config (env, hooks, model) |
| `/memory` | Show CLAUDE.md contents |
| `/diff` | Show git diff |
| `/export [path]` | Export conversation |
| `/resume [id]` | Resume a saved conversation |
| `/session [id]` | Resume a previous session |
| `/version` | Show version |
The REPL now exposes a much broader surface than the original minimal shell:
See [`../USAGE.md`](../USAGE.md) for examples covering interactive use, JSON automation, sessions, permissions, and the mock parity harness.
- session / visibility: `/help`, `/status`, `/sandbox`, `/cost`, `/resume`, `/session`, `/version`, `/usage`, `/stats`
- workspace / git: `/compact`, `/clear`, `/config`, `/memory`, `/init`, `/diff`, `/commit`, `/pr`, `/issue`, `/export`, `/hooks`, `/files`, `/branch`, `/release-notes`, `/add-dir`
- discovery / debugging: `/mcp`, `/agents`, `/skills`, `/doctor`, `/tasks`, `/context`, `/desktop`, `/ide`
- automation / analysis: `/review`, `/advisor`, `/insights`, `/security-review`, `/subagent`, `/team`, `/telemetry`, `/providers`, `/cron`, and more
- plugin management: `/plugin` (with aliases `/plugins`, `/marketplace`)
Notable claw-first surfaces now available directly in slash form:
- `/skills [list|install <path>|help]`
- `/agents [list|help]`
- `/mcp [list|show <server>|help]`
- `/doctor`
- `/plugin [list|install <path>|enable <name>|disable <name>|uninstall <id>|update <id>]`
- `/subagent [list|steer <target> <msg>|kill <id>]`
See [`../USAGE.md`](../USAGE.md) for usage examples and run `cargo run -p rusty-claude-cli -- --help` for the live canonical command list.
## Workspace Layout
```
```text
rust/
├── Cargo.toml # Workspace root
├── Cargo.lock
└── crates/
├── api/ # Anthropic API client + SSE streaming
├── commands/ # Shared slash-command registry
├── api/ # Provider clients + streaming + request preflight
├── commands/ # Shared slash-command registry + help rendering
├── compat-harness/ # TS manifest extraction harness
├── mock-anthropic-service/ # Deterministic local Anthropic-compatible mock
├── plugins/ # Plugin registry and hook wiring primitives
├── runtime/ # Session, config, permissions, MCP, prompts
├── plugins/ # Plugin metadata, manager, install/enable/disable surfaces
├── runtime/ # Session, config, permissions, MCP, prompts, auth/runtime loop
├── rusty-claude-cli/ # Main CLI binary (`claw`)
├── telemetry/ # Session tracing and usage telemetry types
└── tools/ # Built-in tool implementations
└── tools/ # Built-in tools, skill resolution, tool search, agent runtime surfaces
```
### Crate Responsibilities
- **api** — HTTP client, SSE stream parser, request/response types, auth (API key + OAuth bearer)
- **commands** — Slash command definitions and help text generation
- **compat-harness** — Extracts tool/prompt manifests from upstream TS source
- **mock-anthropic-service** — Deterministic `/v1/messages` mock for CLI parity tests and local harness runs
- **plugins** — Plugin metadata, registries, and hook integration surfaces
- **runtime** — `ConversationRuntime` agentic loop, `ConfigLoader` hierarchy, `Session` persistence, permission policy, MCP client, system prompt assembly, usage tracking
- **rusty-claude-cli** — REPL, one-shot prompt, streaming display, tool call rendering, CLI argument parsing
- **telemetry** — Session trace events and supporting telemetry payloads
- **tools** — Tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, REPL runtimes
- **api** — provider clients, SSE streaming, request/response types, auth (API key + OAuth bearer), request-size/context-window preflight
- **commands** — slash command definitions, parsing, help text generation, JSON/text command rendering
- **compat-harness** — extracts tool/prompt manifests from upstream TS source
- **mock-anthropic-service** — deterministic `/v1/messages` mock for CLI parity tests and local harness runs
- **plugins** — plugin metadata, install/enable/disable/update flows, plugin tool definitions, hook integration surfaces
- **runtime** — `ConversationRuntime`, config loading, session persistence, permission policy, MCP client lifecycle, system prompt assembly, usage tracking
- **rusty-claude-cli** — REPL, one-shot prompt, direct CLI subcommands, streaming display, tool call rendering, CLI argument parsing
- **telemetry** — session trace events and supporting telemetry payloads
- **tools** — tool specs + execution: Bash, ReadFile, WriteFile, EditFile, GlobSearch, GrepSearch, WebSearch, WebFetch, Agent, TodoWrite, NotebookEdit, Skill, ToolSearch, and runtime-facing tool discovery
## Stats

12
rust/TUI-ENHANCEMENT-PLAN.md
View File

@ -20,12 +20,14 @@ This plan covers a comprehensive analysis of the current terminal user interface
### Current TUI Components
> Note: The legacy prototype files `app.rs` and `args.rs` were removed on 2026-04-05.
> References below describe future extraction targets, not current tracked source files.
| Component | File | What It Does Today | Quality |
|---|---|---|---|
| **Input** | `input.rs` (269 lines) | `rustyline`-based line editor with slash-command tab completion, Shift+Enter newline, history | ✅ Solid |
| **Rendering** | `render.rs` (641 lines) | Markdown→terminal rendering (headings, lists, tables, code blocks with syntect highlighting, blockquotes), spinner widget | ✅ Good |
| **App/REPL loop** | `main.rs` (3,159 lines) | The monolithic `LiveCli` struct: REPL loop, all slash command handlers, streaming output, tool call display, permission prompting, session management | ⚠️ Monolithic |
| **Alt App** | `app.rs` (398 lines) | An earlier `CliApp` prototype with `ConversationClient`, stream event handling, `TerminalRenderer`, output format support | ⚠️ Appears unused/legacy |
### Key Dependencies
@ -56,7 +58,7 @@ This plan covers a comprehensive analysis of the current terminal user interface
8. **Streaming is char-by-char with artificial delay** — `stream_markdown` sleeps 8ms per whitespace-delimited chunk
9. **No color theme customization** — hardcoded `ColorTheme::default()`
10. **No resize handling** — no terminal size awareness for wrapping, truncation, or layout
11. **Dual app structs** — `app.rs` has a separate `CliApp` that duplicates `LiveCli` from `main.rs`
11. **Historical dual app split** — the repo previously carried a separate `CliApp` prototype alongside `LiveCli`; the prototype is gone, but the monolithic `main.rs` still needs extraction
12. **No pager for long outputs** — `/status`, `/config`, `/memory` can overflow the viewport
13. **Tool results not collapsible** — large bash outputs flood the screen
14. **No thinking/reasoning indicator** — when the model is in "thinking" mode, no visual distinction
@ -73,8 +75,8 @@ This plan covers a comprehensive analysis of the current terminal user interface
| Task | Description | Effort |
|---|---|---|
| 0.1 | **Extract `LiveCli` into `app.rs`** — Move the entire `LiveCli` struct, its impl, and helpers (`format_*`, `render_*`, session management) out of `main.rs` into focused modules: `app.rs` (core), `format.rs` (report formatting), `session_manager.rs` (session CRUD) | M |
| 0.2 | **Remove or merge the legacy `CliApp`** — The existing `app.rs` has an unused `CliApp` with its own `ConversationClient`-based rendering. Either delete it or merge its unique features (stream event handler pattern) into the active `LiveCli` | S |
| 0.3 | **Extract `main.rs` arg parsing** — The current `parse_args()` is a hand-rolled parser that duplicates the clap-based `args.rs`. Consolidate on the hand-rolled parser (it's more feature-complete) and move it to `args.rs`, or adopt clap fully | S |
| 0.2 | **Keep the legacy `CliApp` removed** — The old `CliApp` prototype has already been deleted; if any unique ideas remain valuable (for example stream event handler patterns), reintroduce them intentionally inside the active `LiveCli` extraction rather than restoring the old file wholesale | S |
| 0.3 | **Extract `main.rs` arg parsing** — The current `parse_args()` is still a hand-rolled parser in `main.rs`. If parsing is extracted later, do it into a newly-introduced module intentionally rather than reviving the removed prototype `args.rs` by accident | S |
| 0.4 | **Create a `tui/` module** — Introduce `crates/rusty-claude-cli/src/tui/mod.rs` as the namespace for all new TUI components: `status_bar.rs`, `layout.rs`, `tool_panel.rs`, etc. | S |
### Phase 1: Status Bar & Live HUD
@ -214,7 +216,7 @@ crates/rusty-claude-cli/src/
| Terminal compatibility issues (tmux, SSH, Windows) | Rely on crossterm's abstraction; test in degraded environments |
| Performance regression with rich rendering | Profile before/after; keep the fast path (raw streaming) always available |
| Scope creep into Phase 6 | Ship Phases 0–3 as a coherent release before starting Phase 6 |
| `app.rs` vs `main.rs` confusion | Phase 0.2 explicitly resolves this by removing the legacy `CliApp` |
| Historical `app.rs` vs `main.rs` confusion | Keep the legacy prototype removed and avoid reintroducing a second app surface accidentally during extraction |
---

375
rust/crates/api/src/error.rs
View File

@ -2,22 +2,50 @@ use std::env::VarError;
use std::fmt::{Display, Formatter};
use std::time::Duration;
const GENERIC_FATAL_WRAPPER_MARKERS: &[&str] = &[
"something went wrong while processing your request",
"please try again, or use /new to start a fresh session",
];
const CONTEXT_WINDOW_ERROR_MARKERS: &[&str] = &[
"maximum context length",
"context window",
"context length",
"too many tokens",
"prompt is too long",
"input is too long",
"request is too large",
];
#[derive(Debug)]
pub enum ApiError {
MissingCredentials {
provider: &'static str,
env_vars: &'static [&'static str],
},
ContextWindowExceeded {
model: String,
estimated_input_tokens: u32,
requested_output_tokens: u32,
estimated_total_tokens: u32,
context_window_tokens: u32,
},
ExpiredOAuthToken,
Auth(String),
InvalidApiKeyEnv(VarError),
Http(reqwest::Error),
Io(std::io::Error),
Json(serde_json::Error),
Json {
provider: String,
model: String,
body_snippet: String,
source: serde_json::Error,
},
Api {
status: reqwest::StatusCode,
error_type: Option<String>,
message: Option<String>,
request_id: Option<String>,
body: String,
retryable: bool,
},
@ -41,6 +69,25 @@ impl ApiError {
Self::MissingCredentials { provider, env_vars }
}
/// Build a `Self::Json` enriched with the provider name, the model that
/// was requested, and the first 200 characters of the raw response body so
/// that callers can diagnose deserialization failures without re-running
/// the request.
#[must_use]
pub fn json_deserialize(
provider: impl Into<String>,
model: impl Into<String>,
body: &str,
source: serde_json::Error,
) -> Self {
Self::Json {
provider: provider.into(),
model: model.into(),
body_snippet: truncate_body_snippet(body, 200),
source,
}
}
#[must_use]
pub fn is_retryable(&self) -> bool {
match self {
@ -48,11 +95,106 @@ impl ApiError {
Self::Api { retryable, .. } => *retryable,
Self::RetriesExhausted { last_error, .. } => last_error.is_retryable(),
Self::MissingCredentials { .. }
| Self::ContextWindowExceeded { .. }
| Self::ExpiredOAuthToken
| Self::Auth(_)
| Self::InvalidApiKeyEnv(_)
| Self::Io(_)
| Self::Json(_)
| Self::Json { .. }
| Self::InvalidSseFrame(_)
| Self::BackoffOverflow { .. } => false,
}
}
#[must_use]
pub fn request_id(&self) -> Option<&str> {
match self {
Self::Api { request_id, .. } => request_id.as_deref(),
Self::RetriesExhausted { last_error, .. } => last_error.request_id(),
Self::MissingCredentials { .. }
| Self::ContextWindowExceeded { .. }
| Self::ExpiredOAuthToken
| Self::Auth(_)
| Self::InvalidApiKeyEnv(_)
| Self::Http(_)
| Self::Io(_)
| Self::Json { .. }
| Self::InvalidSseFrame(_)
| Self::BackoffOverflow { .. } => None,
}
}
#[must_use]
pub fn safe_failure_class(&self) -> &'static str {
match self {
Self::RetriesExhausted { .. } if self.is_context_window_failure() => "context_window",
Self::RetriesExhausted { .. } if self.is_generic_fatal_wrapper() => {
"provider_retry_exhausted"
}
Self::RetriesExhausted { last_error, .. } => last_error.safe_failure_class(),
Self::MissingCredentials { .. } | Self::ExpiredOAuthToken | Self::Auth(_) => {
"provider_auth"
}
Self::Api { status, .. } if matches!(status.as_u16(), 401 | 403) => "provider_auth",
Self::ContextWindowExceeded { .. } => "context_window",
Self::Api { .. } if self.is_context_window_failure() => "context_window",
Self::Api { status, .. } if status.as_u16() == 429 => "provider_rate_limit",
Self::Api { .. } if self.is_generic_fatal_wrapper() => "provider_internal",
Self::Api { .. } => "provider_error",
Self::Http(_) | Self::InvalidSseFrame(_) | Self::BackoffOverflow { .. } => {
"provider_transport"
}
Self::InvalidApiKeyEnv(_) | Self::Io(_) | Self::Json { .. } => "runtime_io",
}
}
#[must_use]
pub fn is_generic_fatal_wrapper(&self) -> bool {
match self {
Self::Api { message, body, .. } => {
message
.as_deref()
.is_some_and(looks_like_generic_fatal_wrapper)
|| looks_like_generic_fatal_wrapper(body)
}
Self::RetriesExhausted { last_error, .. } => last_error.is_generic_fatal_wrapper(),
Self::MissingCredentials { .. }
| Self::ContextWindowExceeded { .. }
| Self::ExpiredOAuthToken
| Self::Auth(_)
| Self::InvalidApiKeyEnv(_)
| Self::Http(_)
| Self::Io(_)
| Self::Json { .. }
| Self::InvalidSseFrame(_)
| Self::BackoffOverflow { .. } => false,
}
}
#[must_use]
pub fn is_context_window_failure(&self) -> bool {
match self {
Self::ContextWindowExceeded { .. } => true,
Self::Api {
status,
message,
body,
..
} => {
matches!(status.as_u16(), 400 | 413 | 422)
&& (message
.as_deref()
.is_some_and(looks_like_context_window_error)
|| looks_like_context_window_error(body))
}
Self::RetriesExhausted { last_error, .. } => last_error.is_context_window_failure(),
Self::MissingCredentials { .. }
| Self::ExpiredOAuthToken
| Self::Auth(_)
| Self::InvalidApiKeyEnv(_)
| Self::Http(_)
| Self::Io(_)
| Self::Json { .. }
| Self::InvalidSseFrame(_)
| Self::BackoffOverflow { .. } => false,
}
@ -62,10 +204,36 @@ impl ApiError {
impl Display for ApiError {
fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
match self {
Self::MissingCredentials { provider, env_vars } => write!(
Self::MissingCredentials { provider, env_vars } => {
write!(
f,
"missing {provider} credentials; export {} before calling the {provider} API",
env_vars.join(" or ")
)?;
if cfg!(target_os = "windows") {
if let Some(primary) = env_vars.first() {
write!(
f,
" (on Windows, environment variables set in PowerShell only persist for the current session; use `setx {primary} <value>` to make it permanent, then open a new terminal, or place a `.env` file containing `{primary}=<value>` in the current working directory)"
)?;
} else {
write!(
f,
" (on Windows, environment variables set in PowerShell only persist for the current session; use `setx` to make them permanent, then open a new terminal, or place a `.env` file in the current working directory)"
)?;
}
}
Ok(())
}
Self::ContextWindowExceeded {
model,
estimated_input_tokens,
requested_output_tokens,
estimated_total_tokens,
context_window_tokens,
} => write!(
f,
"missing {provider} credentials; export {} before calling the {provider} API",
env_vars.join(" or ")
"context_window_blocked for {model}: estimated input {estimated_input_tokens} + requested output {requested_output_tokens} = {estimated_total_tokens} tokens exceeds the {context_window_tokens}-token context window; compact the session or reduce request size before retrying"
),
Self::ExpiredOAuthToken => {
write!(
@ -79,19 +247,37 @@ impl Display for ApiError {
}
Self::Http(error) => write!(f, "http error: {error}"),
Self::Io(error) => write!(f, "io error: {error}"),
Self::Json(error) => write!(f, "json error: {error}"),
Self::Json {
provider,
model,
body_snippet,
source,
} => write!(
f,
"failed to parse {provider} response for model {model}: {source}; first 200 chars of body: {body_snippet}"
),
Self::Api {
status,
error_type,
message,
request_id,
body,
..
} => match (error_type, message) {
(Some(error_type), Some(message)) => {
write!(f, "api returned {status} ({error_type}): {message}")
} => {
if let (Some(error_type), Some(message)) = (error_type, message) {
write!(f, "api returned {status} ({error_type})")?;
if let Some(request_id) = request_id {
write!(f, " [trace {request_id}]")?;
}
write!(f, ": {message}")
} else {
write!(f, "api returned {status}")?;
if let Some(request_id) = request_id {
write!(f, " [trace {request_id}]")?;
}
write!(f, ": {body}")
}
_ => write!(f, "api returned {status}: {body}"),
},
}
Self::RetriesExhausted {
attempts,
last_error,
@ -124,7 +310,12 @@ impl From<std::io::Error> for ApiError {
impl From<serde_json::Error> for ApiError {
fn from(value: serde_json::Error) -> Self {
Self::Json(value)
Self::Json {
provider: "unknown".to_string(),
model: "unknown".to_string(),
body_snippet: String::new(),
source: value,
}
}
}
@ -133,3 +324,163 @@ impl From<VarError> for ApiError {
Self::InvalidApiKeyEnv(value)
}
}
fn looks_like_generic_fatal_wrapper(text: &str) -> bool {
let lowered = text.to_ascii_lowercase();
GENERIC_FATAL_WRAPPER_MARKERS
.iter()
.any(|marker| lowered.contains(marker))
}
fn looks_like_context_window_error(text: &str) -> bool {
let lowered = text.to_ascii_lowercase();
CONTEXT_WINDOW_ERROR_MARKERS
.iter()
.any(|marker| lowered.contains(marker))
}
/// Truncate `body` so the resulting snippet contains at most `max_chars`
/// characters (counted by Unicode scalar values, not bytes), preserving the
/// leading slice of the body that the caller most often needs to inspect.
fn truncate_body_snippet(body: &str, max_chars: usize) -> String {
let mut taken_chars = 0;
let mut byte_end = 0;
for (offset, character) in body.char_indices() {
if taken_chars >= max_chars {
break;
}
taken_chars += 1;
byte_end = offset + character.len_utf8();
}
if taken_chars >= max_chars && byte_end < body.len() {
format!("{}…", &body[..byte_end])
} else {
body[..byte_end].to_string()
}
}
#[cfg(test)]
mod tests {
use super::{truncate_body_snippet, ApiError};
#[test]
fn json_deserialize_error_includes_provider_model_and_truncated_body_snippet() {
let raw_body = format!("{}{}", "x".repeat(190), "_TAIL_PAST_200_CHARS_MARKER_");
let source = serde_json::from_str::<serde_json::Value>("{not json")
.expect_err("invalid json should fail to parse");
let error = ApiError::json_deserialize("Anthropic", "claude-opus-4-6", &raw_body, source);
let rendered = error.to_string();
assert!(
rendered.starts_with("failed to parse Anthropic response for model claude-opus-4-6: "),
"rendered error should lead with provider and model: {rendered}"
);
assert!(
rendered.contains("first 200 chars of body: "),
"rendered error should label the body snippet: {rendered}"
);
let snippet = rendered
.split("first 200 chars of body: ")
.nth(1)
.expect("snippet section should be present");
assert!(
snippet.starts_with(&"x".repeat(190)),
"snippet should preserve the leading characters of the body: {snippet}"
);
assert!(
snippet.ends_with('…'),
"snippet should signal truncation with an ellipsis: {snippet}"
);
assert!(
!snippet.contains("_TAIL_PAST_200_CHARS_MARKER_"),
"snippet should drop characters past the 200-char cap: {snippet}"
);
assert_eq!(error.safe_failure_class(), "runtime_io");
assert_eq!(error.request_id(), None);
assert!(!error.is_retryable());
}
#[test]
fn truncate_body_snippet_keeps_short_bodies_intact() {
assert_eq!(truncate_body_snippet("hello", 200), "hello");
assert_eq!(truncate_body_snippet("", 200), "");
}
#[test]
fn truncate_body_snippet_caps_long_bodies_at_max_chars() {
let body = "a".repeat(250);
let snippet = truncate_body_snippet(&body, 200);
assert_eq!(snippet.chars().count(), 201, "200 chars + ellipsis");
assert!(snippet.ends_with('…'));
assert!(snippet.starts_with(&"a".repeat(200)));
}
#[test]
fn truncate_body_snippet_does_not_split_multibyte_characters() {
let body = "한글한글한글한글한글한글";
let snippet = truncate_body_snippet(body, 4);
assert_eq!(snippet, "한글한글…");
}
#[test]
fn detects_generic_fatal_wrapper_and_classifies_it_as_provider_internal() {
let error = ApiError::Api {
status: reqwest::StatusCode::INTERNAL_SERVER_ERROR,
error_type: Some("api_error".to_string()),
message: Some(
"Something went wrong while processing your request. Please try again, or use /new to start a fresh session."
.to_string(),
),
request_id: Some("req_jobdori_123".to_string()),
body: String::new(),
retryable: true,
};
assert!(error.is_generic_fatal_wrapper());
assert_eq!(error.safe_failure_class(), "provider_internal");
assert_eq!(error.request_id(), Some("req_jobdori_123"));
assert!(error.to_string().contains("[trace req_jobdori_123]"));
}
#[test]
fn retries_exhausted_preserves_nested_request_id_and_failure_class() {
let error = ApiError::RetriesExhausted {
attempts: 3,
last_error: Box::new(ApiError::Api {
status: reqwest::StatusCode::BAD_GATEWAY,
error_type: Some("api_error".to_string()),
message: Some(
"Something went wrong while processing your request. Please try again, or use /new to start a fresh session."
.to_string(),
),
request_id: Some("req_nested_456".to_string()),
body: String::new(),
retryable: true,
}),
};
assert!(error.is_generic_fatal_wrapper());
assert_eq!(error.safe_failure_class(), "provider_retry_exhausted");
assert_eq!(error.request_id(), Some("req_nested_456"));
}
#[test]
fn classifies_provider_context_window_errors() {
let error = ApiError::Api {
status: reqwest::StatusCode::BAD_REQUEST,
error_type: Some("invalid_request_error".to_string()),
message: Some(
"This model's maximum context length is 200000 tokens, but your request used 230000 tokens."
.to_string(),
),
request_id: Some("req_ctx_123".to_string()),
body: String::new(),
retryable: false,
};
assert!(error.is_context_window_failure());
assert_eq!(error.safe_failure_class(), "context_window");
assert_eq!(error.request_id(), Some("req_ctx_123"));
}
}

344
rust/crates/api/src/http_client.rs Normal file
View File

@ -0,0 +1,344 @@
use crate::error::ApiError;
const HTTP_PROXY_KEYS: [&str; 2] = ["HTTP_PROXY", "http_proxy"];
const HTTPS_PROXY_KEYS: [&str; 2] = ["HTTPS_PROXY", "https_proxy"];
const NO_PROXY_KEYS: [&str; 2] = ["NO_PROXY", "no_proxy"];
/// Snapshot of the proxy-related environment variables that influence the
/// outbound HTTP client. Captured up front so callers can inspect, log, and
/// test the resolved configuration without re-reading the process environment.
///
/// When `proxy_url` is set it acts as a single catch-all proxy for both
/// HTTP and HTTPS traffic, taking precedence over the per-scheme fields.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ProxyConfig {
pub http_proxy: Option<String>,
pub https_proxy: Option<String>,
pub no_proxy: Option<String>,
/// Optional unified proxy URL that applies to both HTTP and HTTPS.
/// When set, this takes precedence over `http_proxy` and `https_proxy`.
pub proxy_url: Option<String>,
}
impl ProxyConfig {
/// Read proxy settings from the live process environment, honouring both
/// the upper- and lower-case spellings used by curl, git, and friends.
#[must_use]
pub fn from_env() -> Self {
Self::from_lookup(|key| std::env::var(key).ok())
}
/// Create a proxy configuration from a single URL that applies to both
/// HTTP and HTTPS traffic. This is the config-file alternative to setting
/// `HTTP_PROXY` and `HTTPS_PROXY` environment variables separately.
#[must_use]
pub fn from_proxy_url(url: impl Into<String>) -> Self {
Self {
proxy_url: Some(url.into()),
..Self::default()
}
}
fn from_lookup<F>(mut lookup: F) -> Self
where
F: FnMut(&str) -> Option<String>,
{
Self {
http_proxy: first_non_empty(&HTTP_PROXY_KEYS, &mut lookup),
https_proxy: first_non_empty(&HTTPS_PROXY_KEYS, &mut lookup),
no_proxy: first_non_empty(&NO_PROXY_KEYS, &mut lookup),
proxy_url: None,
}
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.proxy_url.is_none() && self.http_proxy.is_none() && self.https_proxy.is_none()
}
}
/// Build a `reqwest::Client` that honours the standard `HTTP_PROXY`,
/// `HTTPS_PROXY`, and `NO_PROXY` environment variables. When no proxy is
/// configured the client behaves identically to `reqwest::Client::new()`.
pub fn build_http_client() -> Result<reqwest::Client, ApiError> {
build_http_client_with(&ProxyConfig::from_env())
}
/// Infallible counterpart to [`build_http_client`] for constructors that
/// historically returned `Self` rather than `Result<Self, _>`. When the proxy
/// configuration is malformed we fall back to a default client so that
/// callers retain the previous behaviour and the failure surfaces on the
/// first outbound request instead of at construction time.
#[must_use]
pub fn build_http_client_or_default() -> reqwest::Client {
build_http_client().unwrap_or_else(|_| reqwest::Client::new())
}
/// Build a `reqwest::Client` from an explicit [`ProxyConfig`]. Used by tests
/// and by callers that want to override process-level environment lookups.
///
/// When `config.proxy_url` is set it overrides the per-scheme `http_proxy`
/// and `https_proxy` fields and is registered as both an HTTP and HTTPS
/// proxy so a single value can route every outbound request.
pub fn build_http_client_with(config: &ProxyConfig) -> Result<reqwest::Client, ApiError> {
let mut builder = reqwest::Client::builder().no_proxy();
let no_proxy = config
.no_proxy
.as_deref()
.and_then(reqwest::NoProxy::from_string);
let (http_proxy_url, https_proxy_url) = match config.proxy_url.as_deref() {
Some(unified) => (Some(unified), Some(unified)),
None => (config.http_proxy.as_deref(), config.https_proxy.as_deref()),
};
if let Some(url) = https_proxy_url {
let mut proxy = reqwest::Proxy::https(url)?;
if let Some(filter) = no_proxy.clone() {
proxy = proxy.no_proxy(Some(filter));
}
builder = builder.proxy(proxy);
}
if let Some(url) = http_proxy_url {
let mut proxy = reqwest::Proxy::http(url)?;
if let Some(filter) = no_proxy.clone() {
proxy = proxy.no_proxy(Some(filter));
}
builder = builder.proxy(proxy);
}
Ok(builder.build()?)
}
fn first_non_empty<F>(keys: &[&str], lookup: &mut F) -> Option<String>
where
F: FnMut(&str) -> Option<String>,
{
keys.iter()
.find_map(|key| lookup(key).filter(|value| !value.is_empty()))
}
#[cfg(test)]
mod tests {
use std::collections::HashMap;
use super::{build_http_client_with, ProxyConfig};
fn config_from_map(pairs: &[(&str, &str)]) -> ProxyConfig {
let map: HashMap<String, String> = pairs
.iter()
.map(|(key, value)| ((*key).to_string(), (*value).to_string()))
.collect();
ProxyConfig::from_lookup(|key| map.get(key).cloned())
}
#[test]
fn proxy_config_is_empty_when_no_env_vars_are_set() {
// given
let config = config_from_map(&[]);
// when
let empty = config.is_empty();
// then
assert!(empty);
assert_eq!(config, ProxyConfig::default());
}
#[test]
fn proxy_config_reads_uppercase_http_https_and_no_proxy() {
// given
let pairs = [
("HTTP_PROXY", "http://proxy.internal:3128"),
("HTTPS_PROXY", "http://secure.internal:3129"),
("NO_PROXY", "localhost,127.0.0.1,.corp"),
];
// when
let config = config_from_map(&pairs);
// then
assert_eq!(
config.http_proxy.as_deref(),
Some("http://proxy.internal:3128")
);
assert_eq!(
config.https_proxy.as_deref(),
Some("http://secure.internal:3129")
);
assert_eq!(
config.no_proxy.as_deref(),
Some("localhost,127.0.0.1,.corp")
);
assert!(!config.is_empty());
}
#[test]
fn proxy_config_falls_back_to_lowercase_keys() {
// given
let pairs = [
("http_proxy", "http://lower.internal:3128"),
("https_proxy", "http://lower-secure.internal:3129"),
("no_proxy", ".lower"),
];
// when
let config = config_from_map(&pairs);
// then
assert_eq!(
config.http_proxy.as_deref(),
Some("http://lower.internal:3128")
);
assert_eq!(
config.https_proxy.as_deref(),
Some("http://lower-secure.internal:3129")
);
assert_eq!(config.no_proxy.as_deref(), Some(".lower"));
}
#[test]
fn proxy_config_prefers_uppercase_over_lowercase_when_both_set() {
// given
let pairs = [
("HTTP_PROXY", "http://upper.internal:3128"),
("http_proxy", "http://lower.internal:3128"),
];
// when
let config = config_from_map(&pairs);
// then
assert_eq!(
config.http_proxy.as_deref(),
Some("http://upper.internal:3128")
);
}
#[test]
fn proxy_config_treats_empty_strings_as_unset() {
// given
let pairs = [("HTTP_PROXY", ""), ("http_proxy", "")];
// when
let config = config_from_map(&pairs);
// then
assert!(config.http_proxy.is_none());
}
#[test]
fn build_http_client_succeeds_when_no_proxy_is_configured() {
// given
let config = ProxyConfig::default();
// when
let result = build_http_client_with(&config);
// then
assert!(result.is_ok());
}
#[test]
fn build_http_client_succeeds_with_valid_http_and_https_proxies() {
// given
let config = ProxyConfig {
http_proxy: Some("http://proxy.internal:3128".to_string()),
https_proxy: Some("http://secure.internal:3129".to_string()),
no_proxy: Some("localhost,127.0.0.1".to_string()),
proxy_url: None,
};
// when
let result = build_http_client_with(&config);
// then
assert!(result.is_ok());
}
#[test]
fn build_http_client_returns_http_error_for_invalid_proxy_url() {
// given
let config = ProxyConfig {
http_proxy: None,
https_proxy: Some("not a url".to_string()),
no_proxy: None,
proxy_url: None,
};
// when
let result = build_http_client_with(&config);
// then
let error = result.expect_err("invalid proxy URL must be reported as a build failure");
assert!(
matches!(error, crate::error::ApiError::Http(_)),
"expected ApiError::Http for invalid proxy URL, got: {error:?}"
);
}
#[test]
fn from_proxy_url_sets_unified_field_and_leaves_per_scheme_empty() {
// given / when
let config = ProxyConfig::from_proxy_url("http://unified.internal:3128");
// then
assert_eq!(
config.proxy_url.as_deref(),
Some("http://unified.internal:3128")
);
assert!(config.http_proxy.is_none());
assert!(config.https_proxy.is_none());
assert!(!config.is_empty());
}
#[test]
fn build_http_client_succeeds_with_unified_proxy_url() {
// given
let config = ProxyConfig {
proxy_url: Some("http://unified.internal:3128".to_string()),
no_proxy: Some("localhost".to_string()),
..ProxyConfig::default()
};
// when
let result = build_http_client_with(&config);
// then
assert!(result.is_ok());
}
#[test]
fn proxy_url_takes_precedence_over_per_scheme_fields() {
// given – both per-scheme and unified are set
let config = ProxyConfig {
http_proxy: Some("http://per-scheme.internal:1111".to_string()),
https_proxy: Some("http://per-scheme.internal:2222".to_string()),
no_proxy: None,
proxy_url: Some("http://unified.internal:3128".to_string()),
};
// when – building succeeds (the unified URL is valid)
let result = build_http_client_with(&config);
// then
assert!(result.is_ok());
}
#[test]
fn build_http_client_returns_error_for_invalid_unified_proxy_url() {
// given
let config = ProxyConfig::from_proxy_url("not a url");
// when
let result = build_http_client_with(&config);
// then
assert!(
matches!(result, Err(crate::error::ApiError::Http(_))),
"invalid unified proxy URL should fail: {result:?}"
);
}
}

7
rust/crates/api/src/lib.rs
View File

@ -1,5 +1,6 @@
mod client;
mod error;
mod http_client;
mod prompt_cache;
mod providers;
mod sse;
@ -10,6 +11,9 @@ pub use client::{
resolve_startup_auth_source, MessageStream, OAuthTokenSet, ProviderClient,
};
pub use error::ApiError;
pub use http_client::{
build_http_client, build_http_client_or_default, build_http_client_with, ProxyConfig,
};
pub use prompt_cache::{
CacheBreakEvent, PromptCache, PromptCacheConfig, PromptCachePaths, PromptCacheRecord,
PromptCacheStats,
@ -17,7 +21,8 @@ pub use prompt_cache::{
pub use providers::anthropic::{AnthropicClient, AnthropicClient as ApiClient, AuthSource};
pub use providers::openai_compat::{OpenAiCompatClient, OpenAiCompatConfig};
pub use providers::{
detect_provider_kind, max_tokens_for_model, resolve_model_alias, ProviderKind,
detect_provider_kind, max_tokens_for_model, max_tokens_for_model_with_override,
resolve_model_alias, ProviderKind,
};
pub use sse::{parse_frame, SseParser};
pub use types::{

282
rust/crates/api/src/providers/anthropic.rs
View File

@ -1,4 +1,5 @@
use std::collections::VecDeque;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use std::time::{Duration, SystemTime, UNIX_EPOCH};
@ -12,18 +13,19 @@ use serde_json::{Map, Value};
use telemetry::{AnalyticsEvent, AnthropicRequestProfile, ClientIdentity, SessionTracer};
use crate::error::ApiError;
use crate::http_client::build_http_client_or_default;
use crate::prompt_cache::{PromptCache, PromptCacheRecord, PromptCacheStats};
use super::{Provider, ProviderFuture};
use super::{model_token_limit, resolve_model_alias, Provider, ProviderFuture};
use crate::sse::SseParser;
use crate::types::{MessageDeltaEvent, MessageRequest, MessageResponse, StreamEvent, Usage};
pub const DEFAULT_BASE_URL: &str = "https://api.anthropic.com";
const REQUEST_ID_HEADER: &str = "request-id";
const ALT_REQUEST_ID_HEADER: &str = "x-request-id";
const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_millis(200);
const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(2);
const DEFAULT_MAX_RETRIES: u32 = 2;
const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_secs(1);
const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(128);
const DEFAULT_MAX_RETRIES: u32 = 8;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AuthSource {
@ -127,7 +129,7 @@ impl AnthropicClient {
#[must_use]
pub fn new(api_key: impl Into<String>) -> Self {
Self {
http: reqwest::Client::new(),
http: build_http_client_or_default(),
auth: AuthSource::ApiKey(api_key.into()),
base_url: DEFAULT_BASE_URL.to_string(),
max_retries: DEFAULT_MAX_RETRIES,
@ -143,7 +145,7 @@ impl AnthropicClient {
#[must_use]
pub fn from_auth(auth: AuthSource) -> Self {
Self {
http: reqwest::Client::new(),
http: build_http_client_or_default(),
auth,
base_url: DEFAULT_BASE_URL.to_string(),
max_retries: DEFAULT_MAX_RETRIES,
@ -294,12 +296,14 @@ impl AnthropicClient {
}
}
let response = self.send_with_retry(&request).await?;
let request_id = request_id_from_headers(response.headers());
let mut response = response
.json::<MessageResponse>()
.await
.map_err(ApiError::from)?;
self.preflight_message_request(&request).await?;
let http_response = self.send_with_retry(&request).await?;
let request_id = request_id_from_headers(http_response.headers());
let body = http_response.text().await.map_err(ApiError::from)?;
let mut response = serde_json::from_str::<MessageResponse>(&body).map_err(|error| {
ApiError::json_deserialize("Anthropic", &request.model, &body, error)
})?;
if response.request_id.is_none() {
response.request_id = request_id;
}
@ -337,13 +341,14 @@ impl AnthropicClient {
&self,
request: &MessageRequest,
) -> Result<MessageStream, ApiError> {
self.preflight_message_request(request).await?;
let response = self
.send_with_retry(&request.clone().with_streaming())
.await?;
Ok(MessageStream {
request_id: request_id_from_headers(response.headers()),
response,
parser: SseParser::new(),
parser: SseParser::new().with_context("Anthropic", request.model.clone()),
pending: VecDeque::new(),
done: false,
request: request.clone(),
@ -368,10 +373,10 @@ impl AnthropicClient {
.await
.map_err(ApiError::from)?;
let response = expect_success(response).await?;
response
.json::<OAuthTokenSet>()
.await
.map_err(ApiError::from)
let body = response.text().await.map_err(ApiError::from)?;
serde_json::from_str::<OAuthTokenSet>(&body).map_err(|error| {
ApiError::json_deserialize("Anthropic OAuth (exchange)", "n/a", &body, error)
})
}
pub async fn refresh_oauth_token(
@ -388,10 +393,10 @@ impl AnthropicClient {
.await
.map_err(ApiError::from)?;
let response = expect_success(response).await?;
response
.json::<OAuthTokenSet>()
.await
.map_err(ApiError::from)
let body = response.text().await.map_err(ApiError::from)?;
serde_json::from_str::<OAuthTokenSet>(&body).map_err(|error| {
ApiError::json_deserialize("Anthropic OAuth (refresh)", "n/a", &body, error)
})
}
async fn send_with_retry(
@ -449,7 +454,7 @@ impl AnthropicClient {
break;
}
tokio::time::sleep(self.backoff_for_attempt(attempts)?).await;
tokio::time::sleep(self.jittered_backoff_for_attempt(attempts)?).await;
}
Err(ApiError::RetriesExhausted {
@ -463,18 +468,74 @@ impl AnthropicClient {
request: &MessageRequest,
) -> Result<reqwest::Response, ApiError> {
let request_url = format!("{}/v1/messages", self.base_url.trim_end_matches('/'));
let mut request_body = self.request_profile.render_json_body(request)?;
strip_unsupported_beta_body_fields(&mut request_body);
let request_builder = self.build_request(&request_url).json(&request_body);
request_builder.send().await.map_err(ApiError::from)
}
fn build_request(&self, request_url: &str) -> reqwest::RequestBuilder {
let request_builder = self
.http
.post(&request_url)
.post(request_url)
.header("content-type", "application/json");
let mut request_builder = self.auth.apply(request_builder);
for (header_name, header_value) in self.request_profile.header_pairs() {
request_builder = request_builder.header(header_name, header_value);
}
request_builder
}
let request_body = self.request_profile.render_json_body(request)?;
request_builder = request_builder.json(&request_body);
request_builder.send().await.map_err(ApiError::from)
async fn preflight_message_request(&self, request: &MessageRequest) -> Result<(), ApiError> {
let Some(limit) = model_token_limit(&request.model) else {
return Ok(());
};
let counted_input_tokens = match self.count_tokens(request).await {
Ok(count) => count,
Err(_) => return Ok(()),
};
let estimated_total_tokens = counted_input_tokens.saturating_add(request.max_tokens);
if estimated_total_tokens > limit.context_window_tokens {
return Err(ApiError::ContextWindowExceeded {
model: resolve_model_alias(&request.model),
estimated_input_tokens: counted_input_tokens,
requested_output_tokens: request.max_tokens,
estimated_total_tokens,
context_window_tokens: limit.context_window_tokens,
});
}
Ok(())
}
async fn count_tokens(&self, request: &MessageRequest) -> Result<u32, ApiError> {
#[derive(serde::Deserialize)]
struct CountTokensResponse {
input_tokens: u32,
}
let request_url = format!("{}/v1/messages/count_tokens", self.base_url.trim_end_matches('/'));
let mut request_body = self.request_profile.render_json_body(request)?;
strip_unsupported_beta_body_fields(&mut request_body);
let response = self
.build_request(&request_url)
.json(&request_body)
.send()
.await
.map_err(ApiError::from)?;
let response = expect_success(response).await?;
let body = response.text().await.map_err(ApiError::from)?;
let parsed = serde_json::from_str::<CountTokensResponse>(&body).map_err(|error| {
ApiError::json_deserialize(
"Anthropic count_tokens",
&request.model,
&body,
error,
)
})?;
Ok(parsed.input_tokens)
}
fn record_request_failure(&self, attempt: u32, error: &ApiError) {
@ -509,6 +570,40 @@ impl AnthropicClient {
.checked_mul(multiplier)
.map_or(self.max_backoff, |delay| delay.min(self.max_backoff)))
}
fn jittered_backoff_for_attempt(&self, attempt: u32) -> Result<Duration, ApiError> {
let base = self.backoff_for_attempt(attempt)?;
Ok(base + jitter_for_base(base))
}
}
/// Process-wide counter that guarantees distinct jitter samples even when
/// the system clock resolution is coarser than consecutive retry sleeps.
static JITTER_COUNTER: AtomicU64 = AtomicU64::new(0);
/// Returns a random additive jitter in `[0, base]` to decorrelate retries
/// from multiple concurrent clients. Entropy is drawn from the nanosecond
/// wall clock mixed with a monotonic counter and run through a splitmix64
/// finalizer; adequate for retry jitter (no cryptographic requirement).
fn jitter_for_base(base: Duration) -> Duration {
let base_nanos = u64::try_from(base.as_nanos()).unwrap_or(u64::MAX);
if base_nanos == 0 {
return Duration::ZERO;
}
let raw_nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|elapsed| u64::try_from(elapsed.as_nanos()).unwrap_or(u64::MAX))
.unwrap_or(0);
let tick = JITTER_COUNTER.fetch_add(1, Ordering::Relaxed);
// splitmix64 finalizer — mixes the low bits so large bases still see
// jitter across their full range instead of being clamped to subsec nanos.
let mut mixed = raw_nanos.wrapping_add(tick).wrapping_add(0x9E37_79B9_7F4A_7C15);
mixed = (mixed ^ (mixed >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
mixed = (mixed ^ (mixed >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
mixed ^= mixed >> 31;
// Inclusive upper bound: jitter may equal `base`, matching "up to base".
let jitter_nanos = mixed % base_nanos.saturating_add(1);
Duration::from_nanos(jitter_nanos)
}
impl AuthSource {
@ -673,7 +768,7 @@ fn now_unix_timestamp() -> u64 {
fn read_env_non_empty(key: &str) -> Result<Option<String>, ApiError> {
match std::env::var(key) {
Ok(value) if !value.is_empty() => Ok(Some(value)),
Ok(_) | Err(std::env::VarError::NotPresent) => Ok(None),
Ok(_) | Err(std::env::VarError::NotPresent) => Ok(super::dotenv_value(key)),
Err(error) => Err(ApiError::from(error)),
}
}
@ -805,6 +900,7 @@ async fn expect_success(response: reqwest::Response) -> Result<reqwest::Response
return Ok(response);
}
let request_id = request_id_from_headers(response.headers());
let body = response.text().await.unwrap_or_else(|_| String::new());
let parsed_error = serde_json::from_str::<AnthropicErrorEnvelope>(&body).ok();
let retryable = is_retryable_status(status);
@ -817,6 +913,7 @@ async fn expect_success(response: reqwest::Response) -> Result<reqwest::Response
message: parsed_error
.as_ref()
.map(|error| error.error.message.clone()),
request_id,
body,
retryable,
})
@ -826,6 +923,16 @@ const fn is_retryable_status(status: reqwest::StatusCode) -> bool {
matches!(status.as_u16(), 408 | 409 | 429 | 500 | 502 | 503 | 504)
}
/// Remove beta-only body fields that the standard `/v1/messages` and
/// `/v1/messages/count_tokens` endpoints reject as `Extra inputs are not
/// permitted`. The `betas` opt-in is communicated via the `anthropic-beta`
/// HTTP header on these endpoints, never as a JSON body field.
fn strip_unsupported_beta_body_fields(body: &mut Value) {
if let Some(object) = body.as_object_mut() {
object.remove("betas");
}
}
#[derive(Debug, Deserialize)]
struct AnthropicErrorEnvelope {
error: AnthropicErrorBody,
@ -1178,6 +1285,58 @@ mod tests {
);
}
#[test]
fn jittered_backoff_stays_within_additive_bounds_and_varies() {
let client = AnthropicClient::new("test-key").with_retry_policy(
8,
Duration::from_secs(1),
Duration::from_secs(128),
);
let mut samples = Vec::with_capacity(64);
for _ in 0..64 {
let base = client.backoff_for_attempt(3).expect("base attempt 3");
let jittered = client
.jittered_backoff_for_attempt(3)
.expect("jittered attempt 3");
assert!(
jittered >= base,
"jittered delay {jittered:?} must be at least the base {base:?}"
);
assert!(
jittered <= base * 2,
"jittered delay {jittered:?} must not exceed base*2 {:?}",
base * 2
);
samples.push(jittered);
}
let distinct: std::collections::HashSet<_> = samples.iter().collect();
assert!(
distinct.len() > 1,
"jitter should produce varied delays across samples, got {samples:?}"
);
}
#[test]
fn default_retry_policy_matches_exponential_schedule() {
let client = AnthropicClient::new("test-key");
assert_eq!(
client.backoff_for_attempt(1).expect("attempt 1"),
Duration::from_secs(1)
);
assert_eq!(
client.backoff_for_attempt(2).expect("attempt 2"),
Duration::from_secs(2)
);
assert_eq!(
client.backoff_for_attempt(3).expect("attempt 3"),
Duration::from_secs(4)
);
assert_eq!(
client.backoff_for_attempt(8).expect("attempt 8"),
Duration::from_secs(128)
);
}
#[test]
fn retryable_statuses_are_detected() {
assert!(super::is_retryable_status(
@ -1242,4 +1401,73 @@ mod tests {
Some("Bearer proxy-token")
);
}
#[test]
fn strip_unsupported_beta_body_fields_removes_betas_array() {
let mut body = serde_json::json!({
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"betas": ["claude-code-20250219", "prompt-caching-scope-2026-01-05"],
"metadata": {"source": "test"},
});
super::strip_unsupported_beta_body_fields(&mut body);
assert!(
body.get("betas").is_none(),
"betas body field must be stripped before sending to /v1/messages"
);
assert_eq!(
body.get("model").and_then(serde_json::Value::as_str),
Some("claude-sonnet-4-6")
);
assert_eq!(body["max_tokens"], serde_json::json!(1024));
assert_eq!(body["metadata"]["source"], serde_json::json!("test"));
}
#[test]
fn strip_unsupported_beta_body_fields_is_a_noop_when_betas_absent() {
let mut body = serde_json::json!({
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
});
let original = body.clone();
super::strip_unsupported_beta_body_fields(&mut body);
assert_eq!(body, original);
}
#[test]
fn rendered_request_body_strips_betas_for_standard_messages_endpoint() {
let client = AnthropicClient::new("test-key").with_beta("tools-2026-04-01");
let request = MessageRequest {
model: "claude-sonnet-4-6".to_string(),
max_tokens: 64,
messages: vec![],
system: None,
tools: None,
tool_choice: None,
stream: false,
};
let mut rendered = client
.request_profile()
.render_json_body(&request)
.expect("body should render");
assert!(
rendered.get("betas").is_some(),
"render_json_body still emits betas; the strip helper guards the wire format",
);
super::strip_unsupported_beta_body_fields(&mut rendered);
assert!(
rendered.get("betas").is_none(),
"betas must not appear in /v1/messages request bodies"
);
assert_eq!(
rendered.get("model").and_then(serde_json::Value::as_str),
Some("claude-sonnet-4-6")
);
}
}

367
rust/crates/api/src/providers/mod.rs
View File

@ -1,14 +1,19 @@
#![allow(clippy::cast_possible_truncation)]
use std::future::Future;
use std::pin::Pin;
use serde::Serialize;
use crate::error::ApiError;
use crate::types::{MessageRequest, MessageResponse};
pub mod anthropic;
pub mod openai_compat;
#[allow(dead_code)]
pub type ProviderFuture<'a, T> = Pin<Box<dyn Future<Output = Result<T, ApiError>> + Send + 'a>>;
#[allow(dead_code)]
pub trait Provider {
type Stream;
@ -38,6 +43,12 @@ pub struct ProviderMetadata {
pub default_base_url: &'static str,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ModelTokenLimit {
pub max_output_tokens: u32,
pub context_window_tokens: u32,
}
const MODEL_REGISTRY: &[(&str, ProviderMetadata)] = &[
(
"opus",
@ -180,17 +191,150 @@ pub fn detect_provider_kind(model: &str) -> ProviderKind {
#[must_use]
pub fn max_tokens_for_model(model: &str) -> u32 {
model_token_limit(model).map_or_else(
|| {
let canonical = resolve_model_alias(model);
if canonical.contains("opus") {
32_000
} else {
64_000
}
},
|limit| limit.max_output_tokens,
)
}
/// Returns the effective max output tokens for a model, preferring a plugin
/// override when present. Falls back to [`max_tokens_for_model`] when the
/// override is `None`.
#[must_use]
pub fn max_tokens_for_model_with_override(model: &str, plugin_override: Option<u32>) -> u32 {
plugin_override.unwrap_or_else(|| max_tokens_for_model(model))
}
#[must_use]
pub fn model_token_limit(model: &str) -> Option<ModelTokenLimit> {
let canonical = resolve_model_alias(model);
if canonical.contains("opus") {
32_000
} else {
64_000
match canonical.as_str() {
"claude-opus-4-6" => Some(ModelTokenLimit {
max_output_tokens: 32_000,
context_window_tokens: 200_000,
}),
"claude-sonnet-4-6" | "claude-haiku-4-5-20251213" => Some(ModelTokenLimit {
max_output_tokens: 64_000,
context_window_tokens: 200_000,
}),
"grok-3" | "grok-3-mini" => Some(ModelTokenLimit {
max_output_tokens: 64_000,
context_window_tokens: 131_072,
}),
_ => None,
}
}
pub fn preflight_message_request(request: &MessageRequest) -> Result<(), ApiError> {
let Some(limit) = model_token_limit(&request.model) else {
return Ok(());
};
let estimated_input_tokens = estimate_message_request_input_tokens(request);
let estimated_total_tokens = estimated_input_tokens.saturating_add(request.max_tokens);
if estimated_total_tokens > limit.context_window_tokens {
return Err(ApiError::ContextWindowExceeded {
model: resolve_model_alias(&request.model),
estimated_input_tokens,
requested_output_tokens: request.max_tokens,
estimated_total_tokens,
context_window_tokens: limit.context_window_tokens,
});
}
Ok(())
}
fn estimate_message_request_input_tokens(request: &MessageRequest) -> u32 {
let mut estimate = estimate_serialized_tokens(&request.messages);
estimate = estimate.saturating_add(estimate_serialized_tokens(&request.system));
estimate = estimate.saturating_add(estimate_serialized_tokens(&request.tools));
estimate = estimate.saturating_add(estimate_serialized_tokens(&request.tool_choice));
estimate
}
fn estimate_serialized_tokens<T: Serialize>(value: &T) -> u32 {
serde_json::to_vec(value)
.ok()
.map_or(0, |bytes| (bytes.len() / 4 + 1) as u32)
}
/// Parse a `.env` file body into key/value pairs using a minimal `KEY=VALUE`
/// grammar. Lines that are blank, start with `#`, or do not contain `=` are
/// ignored. Surrounding double or single quotes are stripped from the value.
/// An optional leading `export ` prefix on the key is also stripped so files
/// shared with shell `source` workflows still parse cleanly.
pub(crate) fn parse_dotenv(content: &str) -> std::collections::HashMap<String, String> {
let mut values = std::collections::HashMap::new();
for raw_line in content.lines() {
let line = raw_line.trim();
if line.is_empty() || line.starts_with('#') {
continue;
}
let Some((raw_key, raw_value)) = line.split_once('=') else {
continue;
};
let trimmed_key = raw_key.trim();
let key = trimmed_key
.strip_prefix("export ")
.map_or(trimmed_key, str::trim)
.to_string();
if key.is_empty() {
continue;
}
let trimmed_value = raw_value.trim();
let unquoted = if (trimmed_value.starts_with('"') && trimmed_value.ends_with('"')
|| trimmed_value.starts_with('\'') && trimmed_value.ends_with('\''))
&& trimmed_value.len() >= 2
{
&trimmed_value[1..trimmed_value.len() - 1]
} else {
trimmed_value
};
values.insert(key, unquoted.to_string());
}
values
}
/// Load and parse a `.env` file from the given path. Missing files yield
/// `None` instead of an error so callers can use this as a soft fallback.
pub(crate) fn load_dotenv_file(
path: &std::path::Path,
) -> Option<std::collections::HashMap<String, String>> {
let content = std::fs::read_to_string(path).ok()?;
Some(parse_dotenv(&content))
}
/// Look up `key` in a `.env` file located in the current working directory.
/// Returns `None` when the file is missing, the key is absent, or the value
/// is empty.
pub(crate) fn dotenv_value(key: &str) -> Option<String> {
let cwd = std::env::current_dir().ok()?;
let values = load_dotenv_file(&cwd.join(".env"))?;
values.get(key).filter(|value| !value.is_empty()).cloned()
}
#[cfg(test)]
mod tests {
use super::{detect_provider_kind, max_tokens_for_model, resolve_model_alias, ProviderKind};
use serde_json::json;
use crate::error::ApiError;
use crate::types::{
InputContentBlock, InputMessage, MessageRequest, ToolChoice, ToolDefinition,
};
use super::{
detect_provider_kind, load_dotenv_file, max_tokens_for_model,
max_tokens_for_model_with_override, model_token_limit, parse_dotenv,
preflight_message_request, resolve_model_alias, ProviderKind,
};
#[test]
fn resolves_grok_aliases() {
@ -213,4 +357,217 @@ mod tests {
assert_eq!(max_tokens_for_model("opus"), 32_000);
assert_eq!(max_tokens_for_model("grok-3"), 64_000);
}
#[test]
fn plugin_config_max_output_tokens_overrides_model_default() {
// given
let nanos = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.expect("time should be after epoch")
.as_nanos();
let root = std::env::temp_dir().join(format!("api-plugin-max-tokens-{nanos}"));
let cwd = root.join("project");
let home = root.join("home").join(".claw");
std::fs::create_dir_all(cwd.join(".claw")).expect("project config dir");
std::fs::create_dir_all(&home).expect("home config dir");
std::fs::write(
home.join("settings.json"),
r#"{
"plugins": {
"maxOutputTokens": 12345
}
}"#,
)
.expect("write plugin settings");
// when
let loaded = runtime::ConfigLoader::new(&cwd, &home)
.load()
.expect("config should load");
let plugin_override = loaded.plugins().max_output_tokens();
let effective = max_tokens_for_model_with_override("claude-opus-4-6", plugin_override);
// then
assert_eq!(plugin_override, Some(12345));
assert_eq!(effective, 12345);
assert_ne!(effective, max_tokens_for_model("claude-opus-4-6"));
std::fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn max_tokens_for_model_with_override_falls_back_when_plugin_unset() {
// given
let plugin_override: Option<u32> = None;
// when
let effective = max_tokens_for_model_with_override("claude-opus-4-6", plugin_override);
// then
assert_eq!(effective, max_tokens_for_model("claude-opus-4-6"));
assert_eq!(effective, 32_000);
}
#[test]
fn returns_context_window_metadata_for_supported_models() {
assert_eq!(
model_token_limit("claude-sonnet-4-6")
.expect("claude-sonnet-4-6 should be registered")
.context_window_tokens,
200_000
);
assert_eq!(
model_token_limit("grok-mini")
.expect("grok-mini should resolve to a registered model")
.context_window_tokens,
131_072
);
}
#[test]
fn preflight_blocks_requests_that_exceed_the_model_context_window() {
let request = MessageRequest {
model: "claude-sonnet-4-6".to_string(),
max_tokens: 64_000,
messages: vec![InputMessage {
role: "user".to_string(),
content: vec![InputContentBlock::Text {
text: "x".repeat(600_000),
}],
}],
system: Some("Keep the answer short.".to_string()),
tools: Some(vec![ToolDefinition {
name: "weather".to_string(),
description: Some("Fetches weather".to_string()),
input_schema: json!({
"type": "object",
"properties": { "city": { "type": "string" } },
}),
}]),
tool_choice: Some(ToolChoice::Auto),
stream: true,
};
let error = preflight_message_request(&request)
.expect_err("oversized request should be rejected before the provider call");
match error {
ApiError::ContextWindowExceeded {
model,
estimated_input_tokens,
requested_output_tokens,
estimated_total_tokens,
context_window_tokens,
} => {
assert_eq!(model, "claude-sonnet-4-6");
assert!(estimated_input_tokens > 136_000);
assert_eq!(requested_output_tokens, 64_000);
assert!(estimated_total_tokens > context_window_tokens);
assert_eq!(context_window_tokens, 200_000);
}
other => panic!("expected context-window preflight failure, got {other:?}"),
}
}
#[test]
fn preflight_skips_unknown_models() {
let request = MessageRequest {
model: "unknown-model".to_string(),
max_tokens: 64_000,
messages: vec![InputMessage {
role: "user".to_string(),
content: vec![InputContentBlock::Text {
text: "x".repeat(600_000),
}],
}],
system: None,
tools: None,
tool_choice: None,
stream: false,
};
preflight_message_request(&request)
.expect("models without context metadata should skip the guarded preflight");
}
#[test]
fn parse_dotenv_extracts_keys_handles_comments_quotes_and_export_prefix() {
// given
let body = "\
# this is a comment
ANTHROPIC_API_KEY=plain-value
XAI_API_KEY=\"quoted-value\"
OPENAI_API_KEY='single-quoted'
export GROK_API_KEY=exported-value
PADDED_KEY = padded-value
EMPTY_VALUE=
NO_EQUALS_LINE
";
// when
let values = parse_dotenv(body);
// then
assert_eq!(
values.get("ANTHROPIC_API_KEY").map(String::as_str),
Some("plain-value")
);
assert_eq!(
values.get("XAI_API_KEY").map(String::as_str),
Some("quoted-value")
);
assert_eq!(
values.get("OPENAI_API_KEY").map(String::as_str),
Some("single-quoted")
);
assert_eq!(
values.get("GROK_API_KEY").map(String::as_str),
Some("exported-value")
);
assert_eq!(
values.get("PADDED_KEY").map(String::as_str),
Some("padded-value")
);
assert_eq!(values.get("EMPTY_VALUE").map(String::as_str), Some(""));
assert!(!values.contains_key("NO_EQUALS_LINE"));
assert!(!values.contains_key("# this is a comment"));
}
#[test]
fn load_dotenv_file_reads_keys_from_disk_and_returns_none_when_missing() {
// given
let temp_root = std::env::temp_dir().join(format!(
"api-dotenv-test-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map_or(0, |duration| duration.as_nanos())
));
std::fs::create_dir_all(&temp_root).expect("create temp dir");
let env_path = temp_root.join(".env");
std::fs::write(
&env_path,
"ANTHROPIC_API_KEY=secret-from-file\n# comment\nXAI_API_KEY=\"xai-secret\"\n",
)
.expect("write .env");
let missing_path = temp_root.join("does-not-exist.env");
// when
let loaded = load_dotenv_file(&env_path).expect("file should load");
let missing = load_dotenv_file(&missing_path);
// then
assert_eq!(
loaded.get("ANTHROPIC_API_KEY").map(String::as_str),
Some("secret-from-file")
);
assert_eq!(
loaded.get("XAI_API_KEY").map(String::as_str),
Some("xai-secret")
);
assert!(missing.is_none());
let _ = std::fs::remove_dir_all(&temp_root);
}
}

90
rust/crates/api/src/providers/openai_compat.rs
View File

@ -1,10 +1,12 @@
use std::collections::{BTreeMap, VecDeque};
use std::time::Duration;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{Duration, SystemTime, UNIX_EPOCH};
use serde::Deserialize;
use serde_json::{json, Value};
use crate::error::ApiError;
use crate::http_client::build_http_client_or_default;
use crate::types::{
ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent,
InputContentBlock, InputMessage, MessageDelta, MessageDeltaEvent, MessageRequest,
@ -12,15 +14,15 @@ use crate::types::{
ToolChoice, ToolDefinition, ToolResultContentBlock, Usage,
};
use super::{Provider, ProviderFuture};
use super::{preflight_message_request, Provider, ProviderFuture};
pub const DEFAULT_XAI_BASE_URL: &str = "https://api.x.ai/v1";
pub const DEFAULT_OPENAI_BASE_URL: &str = "https://api.openai.com/v1";
const REQUEST_ID_HEADER: &str = "request-id";
const ALT_REQUEST_ID_HEADER: &str = "x-request-id";
const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_millis(200);
const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(2);
const DEFAULT_MAX_RETRIES: u32 = 2;
const DEFAULT_INITIAL_BACKOFF: Duration = Duration::from_secs(1);
const DEFAULT_MAX_BACKOFF: Duration = Duration::from_secs(128);
const DEFAULT_MAX_RETRIES: u32 = 8;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OpenAiCompatConfig {
@ -81,7 +83,7 @@ impl OpenAiCompatClient {
#[must_use]
pub fn new(api_key: impl Into<String>, config: OpenAiCompatConfig) -> Self {
Self {
http: reqwest::Client::new(),
http: build_http_client_or_default(),
api_key: api_key.into(),
config,
base_url: read_base_url(config),
@ -128,9 +130,18 @@ impl OpenAiCompatClient {
stream: false,
..request.clone()
};
preflight_message_request(&request)?;
let response = self.send_with_retry(&request).await?;
let request_id = request_id_from_headers(response.headers());
let payload = response.json::<ChatCompletionResponse>().await?;
let body = response.text().await.map_err(ApiError::from)?;
let payload = serde_json::from_str::<ChatCompletionResponse>(&body).map_err(|error| {
ApiError::json_deserialize(
self.config.provider_name,
&request.model,
&body,
error,
)
})?;
let mut normalized = normalize_response(&request.model, payload)?;
if normalized.request_id.is_none() {
normalized.request_id = request_id;
@ -142,13 +153,17 @@ impl OpenAiCompatClient {
&self,
request: &MessageRequest,
) -> Result<MessageStream, ApiError> {
preflight_message_request(request)?;
let response = self
.send_with_retry(&request.clone().with_streaming())
.await?;
Ok(MessageStream {
request_id: request_id_from_headers(response.headers()),
response,
parser: OpenAiSseParser::new(),
parser: OpenAiSseParser::with_context(
self.config.provider_name,
request.model.clone(),
),
pending: VecDeque::new(),
done: false,
state: StreamState::new(request.model.clone()),
@ -177,7 +192,7 @@ impl OpenAiCompatClient {
break retryable_error;
}
tokio::time::sleep(self.backoff_for_attempt(attempts)?).await;
tokio::time::sleep(self.jittered_backoff_for_attempt(attempts)?).await;
};
Err(ApiError::RetriesExhausted {
@ -213,6 +228,37 @@ impl OpenAiCompatClient {
.checked_mul(multiplier)
.map_or(self.max_backoff, |delay| delay.min(self.max_backoff)))
}
fn jittered_backoff_for_attempt(&self, attempt: u32) -> Result<Duration, ApiError> {
let base = self.backoff_for_attempt(attempt)?;
Ok(base + jitter_for_base(base))
}
}
/// Process-wide counter that guarantees distinct jitter samples even when
/// the system clock resolution is coarser than consecutive retry sleeps.
static JITTER_COUNTER: AtomicU64 = AtomicU64::new(0);
/// Returns a random additive jitter in `[0, base]` to decorrelate retries
/// from multiple concurrent clients. Entropy is drawn from the nanosecond
/// wall clock mixed with a monotonic counter and run through a splitmix64
/// finalizer; adequate for retry jitter (no cryptographic requirement).
fn jitter_for_base(base: Duration) -> Duration {
let base_nanos = u64::try_from(base.as_nanos()).unwrap_or(u64::MAX);
if base_nanos == 0 {
return Duration::ZERO;
}
let raw_nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|elapsed| u64::try_from(elapsed.as_nanos()).unwrap_or(u64::MAX))
.unwrap_or(0);
let tick = JITTER_COUNTER.fetch_add(1, Ordering::Relaxed);
let mut mixed = raw_nanos.wrapping_add(tick).wrapping_add(0x9E37_79B9_7F4A_7C15);
mixed = (mixed ^ (mixed >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
mixed = (mixed ^ (mixed >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
mixed ^= mixed >> 31;
let jitter_nanos = mixed % base_nanos.saturating_add(1);
Duration::from_nanos(jitter_nanos)
}
impl Provider for OpenAiCompatClient {
@ -280,11 +326,17 @@ impl MessageStream {
#[derive(Debug, Default)]
struct OpenAiSseParser {
buffer: Vec<u8>,
provider: String,
model: String,
}
impl OpenAiSseParser {
fn new() -> Self {
Self::default()
fn with_context(provider: impl Into<String>, model: impl Into<String>) -> Self {
Self {
buffer: Vec::new(),
provider: provider.into(),
model: model.into(),
}
}
fn push(&mut self, chunk: &[u8]) -> Result<Vec<ChatCompletionChunk>, ApiError> {
@ -292,7 +344,7 @@ impl OpenAiSseParser {
let mut events = Vec::new();
while let Some(frame) = next_sse_frame(&mut self.buffer) {
if let Some(event) = parse_sse_frame(&frame)? {
if let Some(event) = parse_sse_frame(&frame, &self.provider, &self.model)? {
events.push(event);
}
}
@ -833,7 +885,11 @@ fn next_sse_frame(buffer: &mut Vec<u8>) -> Option<String> {
Some(String::from_utf8_lossy(&frame[..frame_len]).into_owned())
}
fn parse_sse_frame(frame: &str) -> Result<Option<ChatCompletionChunk>, ApiError> {
fn parse_sse_frame(
frame: &str,
provider: &str,
model: &str,
) -> Result<Option<ChatCompletionChunk>, ApiError> {
let trimmed = frame.trim();
if trimmed.is_empty() {
return Ok(None);
@ -855,15 +911,15 @@ fn parse_sse_frame(frame: &str) -> Result<Option<ChatCompletionChunk>, ApiError>
if payload == "[DONE]" {
return Ok(None);
}
serde_json::from_str(&payload)
serde_json::from_str::<ChatCompletionChunk>(&payload)
.map(Some)
.map_err(ApiError::from)
.map_err(|error| ApiError::json_deserialize(provider, model, &payload, error))
}
fn read_env_non_empty(key: &str) -> Result<Option<String>, ApiError> {
match std::env::var(key) {
Ok(value) if !value.is_empty() => Ok(Some(value)),
Ok(_) | Err(std::env::VarError::NotPresent) => Ok(None),
Ok(_) | Err(std::env::VarError::NotPresent) => Ok(super::dotenv_value(key)),
Err(error) => Err(ApiError::from(error)),
}
}
@ -904,6 +960,7 @@ async fn expect_success(response: reqwest::Response) -> Result<reqwest::Response
return Ok(response);
}
let request_id = request_id_from_headers(response.headers());
let body = response.text().await.unwrap_or_default();
let parsed_error = serde_json::from_str::<ErrorEnvelope>(&body).ok();
let retryable = is_retryable_status(status);
@ -916,6 +973,7 @@ async fn expect_success(response: reqwest::Response) -> Result<reqwest::Response
message: parsed_error
.as_ref()
.and_then(|error| error.error.message.clone()),
request_id,
body,
retryable,
})

57
rust/crates/api/src/sse.rs
View File

@ -4,6 +4,8 @@ use crate::types::StreamEvent;
#[derive(Debug, Default)]
pub struct SseParser {
buffer: Vec<u8>,
provider: Option<String>,
model: Option<String>,
}
impl SseParser {
@ -12,12 +14,23 @@ impl SseParser {
Self::default()
}
/// Attach the provider name and model to this parser so that JSON
/// deserialization failures within streamed frames carry enough context
/// for callers to understand which upstream produced the unparseable
/// payload.
#[must_use]
pub fn with_context(mut self, provider: impl Into<String>, model: impl Into<String>) -> Self {
self.provider = Some(provider.into());
self.model = Some(model.into());
self
}
pub fn push(&mut self, chunk: &[u8]) -> Result<Vec<StreamEvent>, ApiError> {
self.buffer.extend_from_slice(chunk);
let mut events = Vec::new();
while let Some(frame) = self.next_frame() {
if let Some(event) = parse_frame(&frame)? {
if let Some(event) = self.parse_frame_with_context(&frame)? {
events.push(event);
}
}
@ -31,12 +44,18 @@ impl SseParser {
}
let trailing = std::mem::take(&mut self.buffer);
match parse_frame(&String::from_utf8_lossy(&trailing))? {
match self.parse_frame_with_context(&String::from_utf8_lossy(&trailing))? {
Some(event) => Ok(vec![event]),
None => Ok(Vec::new()),
}
}
fn parse_frame_with_context(&self, frame: &str) -> Result<Option<StreamEvent>, ApiError> {
let provider = self.provider.as_deref().unwrap_or("unknown");
let model = self.model.as_deref().unwrap_or("unknown");
parse_frame_with_provider(frame, provider, model)
}
fn next_frame(&mut self) -> Option<String> {
let separator = self
.buffer
@ -61,6 +80,14 @@ impl SseParser {
}
pub fn parse_frame(frame: &str) -> Result<Option<StreamEvent>, ApiError> {
parse_frame_with_provider(frame, "unknown", "unknown")
}
pub(crate) fn parse_frame_with_provider(
frame: &str,
provider: &str,
model: &str,
) -> Result<Option<StreamEvent>, ApiError> {
let trimmed = frame.trim();
if trimmed.is_empty() {
return Ok(None);
@ -97,7 +124,7 @@ pub fn parse_frame(frame: &str) -> Result<Option<StreamEvent>, ApiError> {
serde_json::from_str::<StreamEvent>(&payload)
.map(Some)
.map_err(ApiError::from)
.map_err(|error| ApiError::json_deserialize(provider, model, &payload, error))
}
#[cfg(test)]
@ -276,4 +303,28 @@ mod tests {
))
);
}
#[test]
fn given_message_delta_frame_with_empty_usage_when_parsed_then_usage_defaults_to_zero() {
// given
let frame = concat!(
"event: message_delta\n",
"data: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\",\"stop_sequence\":null},\"usage\":{}}\n\n"
);
// when
let event = parse_frame(frame).expect("frame should parse");
// then
assert_eq!(
event,
Some(StreamEvent::MessageDelta(crate::types::MessageDeltaEvent {
delta: MessageDelta {
stop_reason: Some("end_turn".to_string()),
stop_sequence: None,
},
usage: Usage::default(),
}))
);
}
}

6
rust/crates/api/src/types.rs
View File

@ -113,6 +113,7 @@ pub struct MessageResponse {
pub stop_reason: Option<String>,
#[serde(default)]
pub stop_sequence: Option<String>,
#[serde(default)]
pub usage: Usage,
#[serde(default)]
pub request_id: Option<String>,
@ -147,13 +148,15 @@ pub enum OutputContentBlock {
},
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct Usage {
#[serde(default)]
pub input_tokens: u32,
#[serde(default)]
pub cache_creation_input_tokens: u32,
#[serde(default)]
pub cache_read_input_tokens: u32,
#[serde(default)]
pub output_tokens: u32,
}
@ -194,6 +197,7 @@ pub struct MessageStartEvent {
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct MessageDeltaEvent {
pub delta: MessageDelta,
#[serde(default)]
pub usage: Usage,
}

154
rust/crates/api/tests/client_integration.rs
View File

@ -97,9 +97,44 @@ async fn send_message_posts_json_and_parses_response() {
assert!(body.get("stream").is_none());
assert_eq!(body["tools"][0]["name"], json!("get_weather"));
assert_eq!(body["tool_choice"]["type"], json!("auto"));
assert_eq!(
body["betas"],
json!(["claude-code-20250219", "prompt-caching-scope-2026-01-05"])
assert!(
body.get("betas").is_none(),
"betas must travel via the anthropic-beta header, not the request body"
);
}
#[tokio::test]
async fn send_message_blocks_oversized_requests_before_the_http_call() {
let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
let server = spawn_server(
state.clone(),
vec![http_response("200 OK", "application/json", "{}")],
)
.await;
let client = AnthropicClient::new("test-key").with_base_url(server.base_url());
let error = client
.send_message(&MessageRequest {
model: "claude-sonnet-4-6".to_string(),
max_tokens: 64_000,
messages: vec![InputMessage {
role: "user".to_string(),
content: vec![InputContentBlock::Text {
text: "x".repeat(600_000),
}],
}],
system: Some("Keep the answer short.".to_string()),
tools: None,
tool_choice: None,
stream: false,
})
.await
.expect_err("oversized request should fail local context-window preflight");
assert!(matches!(error, ApiError::ContextWindowExceeded { .. }));
assert!(
state.lock().await.is_empty(),
"preflight failure should avoid any upstream HTTP request"
);
}
@ -156,13 +191,9 @@ async fn send_message_applies_request_profile_and_records_telemetry() {
let body: serde_json::Value =
serde_json::from_str(&request.body).expect("request body should be json");
assert_eq!(body["metadata"]["source"], json!("clawd-code"));
assert_eq!(
body["betas"],
json!([
"claude-code-20250219",
"prompt-caching-scope-2026-01-05",
"tools-2026-04-01"
])
assert!(
body.get("betas").is_none(),
"betas must travel via the anthropic-beta header, not the request body"
);
let events = sink.events();
@ -241,6 +272,44 @@ async fn send_message_parses_prompt_cache_token_usage_from_response() {
assert_eq!(response.usage.output_tokens, 4);
}
#[tokio::test]
async fn given_empty_usage_object_when_send_message_parses_response_then_usage_defaults_to_zero() {
// given
let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
let body = concat!(
"{",
"\"id\":\"msg_empty_usage\",",
"\"type\":\"message\",",
"\"role\":\"assistant\",",
"\"content\":[{\"type\":\"text\",\"text\":\"Hello from Claude\"}],",
"\"model\":\"claude-3-7-sonnet-latest\",",
"\"stop_reason\":\"end_turn\",",
"\"stop_sequence\":null,",
"\"usage\":{}",
"}"
);
let server = spawn_server(
state,
vec![http_response("200 OK", "application/json", body)],
)
.await;
let client = AnthropicClient::new("test-key").with_base_url(server.base_url());
// when
let response = client
.send_message(&sample_request(false))
.await
.expect("response with empty usage object should still parse");
// then
assert_eq!(response.id, "msg_empty_usage");
assert_eq!(response.total_tokens(), 0);
assert_eq!(response.usage.input_tokens, 0);
assert_eq!(response.usage.cache_creation_input_tokens, 0);
assert_eq!(response.usage.cache_read_input_tokens, 0);
assert_eq!(response.usage.output_tokens, 0);
}
#[tokio::test]
#[allow(clippy::await_holding_lock)]
async fn stream_message_parses_sse_events_with_tool_use() {
@ -476,6 +545,71 @@ async fn surfaces_retry_exhaustion_for_persistent_retryable_errors() {
}
}
#[tokio::test]
async fn retries_multiple_retryable_failures_with_exponential_backoff_and_jitter() {
let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
let server = spawn_server(
state.clone(),
vec![
http_response(
"429 Too Many Requests",
"application/json",
"{\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"slow down\"}}",
),
http_response(
"500 Internal Server Error",
"application/json",
"{\"type\":\"error\",\"error\":{\"type\":\"api_error\",\"message\":\"boom\"}}",
),
http_response(
"503 Service Unavailable",
"application/json",
"{\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"busy\"}}",
),
http_response(
"429 Too Many Requests",
"application/json",
"{\"type\":\"error\",\"error\":{\"type\":\"rate_limit_error\",\"message\":\"slow down again\"}}",
),
http_response(
"503 Service Unavailable",
"application/json",
"{\"type\":\"error\",\"error\":{\"type\":\"overloaded_error\",\"message\":\"still busy\"}}",
),
http_response(
"200 OK",
"application/json",
"{\"id\":\"msg_exp_retry\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"Recovered after 5\"}],\"model\":\"claude-3-7-sonnet-latest\",\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"usage\":{\"input_tokens\":3,\"output_tokens\":2}}",
),
],
)
.await;
let client = ApiClient::new("test-key")
.with_base_url(server.base_url())
.with_retry_policy(8, Duration::from_millis(1), Duration::from_millis(4));
let started_at = std::time::Instant::now();
let response = client
.send_message(&sample_request(false))
.await
.expect("8-retry policy should absorb 5 retryable failures");
let elapsed = started_at.elapsed();
assert_eq!(response.total_tokens(), 5);
assert_eq!(
state.lock().await.len(),
6,
"client should issue 1 original + 5 retry requests before the 200"
);
// Jittered sleeps are bounded by 2 * max_backoff per retry (base + jitter),
// so 5 sleeps fit comfortably below this upper bound with generous slack.
assert!(
elapsed < Duration::from_secs(5),
"retries should complete promptly, took {elapsed:?}"
);
}
#[tokio::test]
#[allow(clippy::await_holding_lock)]
async fn send_message_reuses_recent_completion_cache_entries() {

44
rust/crates/api/tests/openai_compat_integration.rs
View File

@ -4,10 +4,10 @@ use std::sync::Arc;
use std::sync::{Mutex as StdMutex, OnceLock};
use api::{
ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent, ContentBlockStopEvent,
InputContentBlock, InputMessage, MessageDeltaEvent, MessageRequest, OpenAiCompatClient,
OpenAiCompatConfig, OutputContentBlock, ProviderClient, StreamEvent, ToolChoice,
ToolDefinition,
ApiError, ContentBlockDelta, ContentBlockDeltaEvent, ContentBlockStartEvent,
ContentBlockStopEvent, InputContentBlock, InputMessage, MessageDeltaEvent, MessageRequest,
OpenAiCompatClient, OpenAiCompatConfig, OutputContentBlock, ProviderClient, StreamEvent,
ToolChoice, ToolDefinition,
};
use serde_json::json;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
@ -63,6 +63,42 @@ async fn send_message_uses_openai_compatible_endpoint_and_auth() {
assert_eq!(body["tools"][0]["type"], json!("function"));
}
#[tokio::test]
async fn send_message_blocks_oversized_xai_requests_before_the_http_call() {
let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));
let server = spawn_server(
state.clone(),
vec![http_response("200 OK", "application/json", "{}")],
)
.await;
let client = OpenAiCompatClient::new("xai-test-key", OpenAiCompatConfig::xai())
.with_base_url(server.base_url());
let error = client
.send_message(&MessageRequest {
model: "grok-3".to_string(),
max_tokens: 64_000,
messages: vec![InputMessage {
role: "user".to_string(),
content: vec![InputContentBlock::Text {
text: "x".repeat(300_000),
}],
}],
system: Some("Keep the answer short.".to_string()),
tools: None,
tool_choice: None,
stream: false,
})
.await
.expect_err("oversized request should fail local context-window preflight");
assert!(matches!(error, ApiError::ContextWindowExceeded { .. }));
assert!(
state.lock().await.is_empty(),
"preflight failure should avoid any upstream HTTP request"
);
}
#[tokio::test]
async fn send_message_accepts_full_chat_completions_endpoint_override() {
let state = Arc::new(Mutex::new(Vec::<CapturedRequest>::new()));

173
rust/crates/api/tests/proxy_integration.rs Normal file
View File

@ -0,0 +1,173 @@
use std::ffi::OsString;
use std::sync::{Mutex, OnceLock};
use api::{build_http_client_with, ProxyConfig};
fn env_lock() -> std::sync::MutexGuard<'static, ()> {
static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
LOCK.get_or_init(|| Mutex::new(()))
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
}
struct EnvVarGuard {
key: &'static str,
original: Option<OsString>,
}
impl EnvVarGuard {
fn set(key: &'static str, value: Option<&str>) -> Self {
let original = std::env::var_os(key);
match value {
Some(value) => std::env::set_var(key, value),
None => std::env::remove_var(key),
}
Self { key, original }
}
}
impl Drop for EnvVarGuard {
fn drop(&mut self) {
match &self.original {
Some(value) => std::env::set_var(self.key, value),
None => std::env::remove_var(self.key),
}
}
}
#[test]
fn proxy_config_from_env_reads_uppercase_proxy_vars() {
// given
let _lock = env_lock();
let _http = EnvVarGuard::set("HTTP_PROXY", Some("http://proxy.corp:3128"));
let _https = EnvVarGuard::set("HTTPS_PROXY", Some("http://secure.corp:3129"));
let _no = EnvVarGuard::set("NO_PROXY", Some("localhost,127.0.0.1"));
let _http_lower = EnvVarGuard::set("http_proxy", None);
let _https_lower = EnvVarGuard::set("https_proxy", None);
let _no_lower = EnvVarGuard::set("no_proxy", None);
// when
let config = ProxyConfig::from_env();
// then
assert_eq!(config.http_proxy.as_deref(), Some("http://proxy.corp:3128"));
assert_eq!(
config.https_proxy.as_deref(),
Some("http://secure.corp:3129")
);
assert_eq!(config.no_proxy.as_deref(), Some("localhost,127.0.0.1"));
assert!(config.proxy_url.is_none());
assert!(!config.is_empty());
}
#[test]
fn proxy_config_from_env_reads_lowercase_proxy_vars() {
// given
let _lock = env_lock();
let _http = EnvVarGuard::set("HTTP_PROXY", None);
let _https = EnvVarGuard::set("HTTPS_PROXY", None);
let _no = EnvVarGuard::set("NO_PROXY", None);
let _http_lower = EnvVarGuard::set("http_proxy", Some("http://lower.corp:3128"));
let _https_lower = EnvVarGuard::set("https_proxy", Some("http://lower-secure.corp:3129"));
let _no_lower = EnvVarGuard::set("no_proxy", Some(".internal"));
// when
let config = ProxyConfig::from_env();
// then
assert_eq!(config.http_proxy.as_deref(), Some("http://lower.corp:3128"));
assert_eq!(
config.https_proxy.as_deref(),
Some("http://lower-secure.corp:3129")
);
assert_eq!(config.no_proxy.as_deref(), Some(".internal"));
assert!(!config.is_empty());
}
#[test]
fn proxy_config_from_env_is_empty_when_no_vars_set() {
// given
let _lock = env_lock();
let _http = EnvVarGuard::set("HTTP_PROXY", None);
let _https = EnvVarGuard::set("HTTPS_PROXY", None);
let _no = EnvVarGuard::set("NO_PROXY", None);
let _http_lower = EnvVarGuard::set("http_proxy", None);
let _https_lower = EnvVarGuard::set("https_proxy", None);
let _no_lower = EnvVarGuard::set("no_proxy", None);
// when
let config = ProxyConfig::from_env();
// then
assert!(config.is_empty());
assert!(config.http_proxy.is_none());
assert!(config.https_proxy.is_none());
assert!(config.no_proxy.is_none());
}
#[test]
fn proxy_config_from_env_treats_empty_values_as_unset() {
// given
let _lock = env_lock();
let _http = EnvVarGuard::set("HTTP_PROXY", Some(""));
let _https = EnvVarGuard::set("HTTPS_PROXY", Some(""));
let _http_lower = EnvVarGuard::set("http_proxy", Some(""));
let _https_lower = EnvVarGuard::set("https_proxy", Some(""));
let _no = EnvVarGuard::set("NO_PROXY", Some(""));
let _no_lower = EnvVarGuard::set("no_proxy", Some(""));
// when
let config = ProxyConfig::from_env();
// then
assert!(config.is_empty());
}
#[test]
fn build_client_with_env_proxy_config_succeeds() {
// given
let _lock = env_lock();
let _http = EnvVarGuard::set("HTTP_PROXY", Some("http://proxy.corp:3128"));
let _https = EnvVarGuard::set("HTTPS_PROXY", Some("http://secure.corp:3129"));
let _no = EnvVarGuard::set("NO_PROXY", Some("localhost"));
let _http_lower = EnvVarGuard::set("http_proxy", None);
let _https_lower = EnvVarGuard::set("https_proxy", None);
let _no_lower = EnvVarGuard::set("no_proxy", None);
let config = ProxyConfig::from_env();
// when
let result = build_http_client_with(&config);
// then
assert!(result.is_ok());
}
#[test]
fn build_client_with_proxy_url_config_succeeds() {
// given
let config = ProxyConfig::from_proxy_url("http://unified.corp:3128");
// when
let result = build_http_client_with(&config);
// then
assert!(result.is_ok());
}
#[test]
fn proxy_config_from_env_prefers_uppercase_over_lowercase() {
// given
let _lock = env_lock();
let _http_upper = EnvVarGuard::set("HTTP_PROXY", Some("http://upper.corp:3128"));
let _http_lower = EnvVarGuard::set("http_proxy", Some("http://lower.corp:3128"));
let _https = EnvVarGuard::set("HTTPS_PROXY", None);
let _https_lower = EnvVarGuard::set("https_proxy", None);
let _no = EnvVarGuard::set("NO_PROXY", None);
let _no_lower = EnvVarGuard::set("no_proxy", None);
// when
let config = ProxyConfig::from_env();
// then
assert_eq!(config.http_proxy.as_deref(), Some("http://upper.corp:3128"));
}

1381
rust/crates/commands/src/lib.rs
View File

File diff suppressed because it is too large Load Diff

100
rust/crates/plugins/src/lib.rs
View File

@ -920,6 +920,9 @@ pub enum PluginManifestValidationError {
tool_name: String,
permission: String,
},
UnsupportedManifestContract {
detail: String,
},
}
impl Display for PluginManifestValidationError {
@ -965,6 +968,7 @@ impl Display for PluginManifestValidationError {
f,
"plugin tool `{tool_name}` requiredPermission `{permission}` must be read-only, workspace-write, or danger-full-access"
),
Self::UnsupportedManifestContract { detail } => f.write_str(detail),
}
}
}
@ -1594,10 +1598,73 @@ fn load_manifest_from_path(
manifest_path.display()
))
})?;
let raw_manifest: RawPluginManifest = serde_json::from_str(&contents)?;
let raw_json: Value = serde_json::from_str(&contents)?;
let compatibility_errors = detect_claude_code_manifest_contract_gaps(&raw_json);
if !compatibility_errors.is_empty() {
return Err(PluginError::ManifestValidation(compatibility_errors));
}
let raw_manifest: RawPluginManifest = serde_json::from_value(raw_json)?;
build_plugin_manifest(root, raw_manifest)
}
fn detect_claude_code_manifest_contract_gaps(
raw_manifest: &Value,
) -> Vec<PluginManifestValidationError> {
let Some(root) = raw_manifest.as_object() else {
return Vec::new();
};
let mut errors = Vec::new();
for (field, detail) in [
(
"skills",
"plugin manifest field `skills` uses the Claude Code plugin contract; `claw` does not load plugin-managed skills and instead discovers skills from local roots such as `.claw/skills`, `.omc/skills`, `.agents/skills`, `~/.omc/skills`, and `~/.claude/skills/omc-learned`.",
),
(
"mcpServers",
"plugin manifest field `mcpServers` uses the Claude Code plugin contract; `claw` does not import MCP servers from plugin manifests.",
),
(
"agents",
"plugin manifest field `agents` uses the Claude Code plugin contract; `claw` does not load plugin-managed agent markdown catalogs from plugin manifests.",
),
] {
if root.contains_key(field) {
errors.push(PluginManifestValidationError::UnsupportedManifestContract {
detail: detail.to_string(),
});
}
}
if root
.get("commands")
.and_then(Value::as_array)
.is_some_and(|commands| commands.iter().any(Value::is_string))
{
errors.push(PluginManifestValidationError::UnsupportedManifestContract {
detail: "plugin manifest field `commands` uses Claude Code-style directory globs; `claw` slash dispatch is still built-in and does not load plugin slash command markdown files.".to_string(),
});
}
if let Some(hooks) = root.get("hooks").and_then(Value::as_object) {
for hook_name in hooks.keys() {
if !matches!(
hook_name.as_str(),
"PreToolUse" | "PostToolUse" | "PostToolUseFailure"
) {
errors.push(PluginManifestValidationError::UnsupportedManifestContract {
detail: format!(
"plugin hook `{hook_name}` uses the Claude Code lifecycle contract; `claw` plugins currently support only PreToolUse, PostToolUse, and PostToolUseFailure."
),
});
}
}
}
errors
}
fn plugin_manifest_path(root: &Path) -> Result<PathBuf, PluginError> {
let direct_path = root.join(MANIFEST_FILE_NAME);
if direct_path.exists() {
@ -2517,6 +2584,37 @@ mod tests {
let _ = fs::remove_dir_all(root);
}
#[test]
fn load_plugin_from_directory_rejects_claude_code_manifest_contracts_with_guidance() {
let root = temp_dir("manifest-claude-code-contract");
write_file(
root.join(MANIFEST_FILE_NAME).as_path(),
r#"{
"name": "oh-my-claudecode",
"version": "4.10.2",
"description": "Claude Code plugin manifest",
"hooks": {
"SessionStart": ["scripts/session-start.mjs"]
},
"agents": ["agents/*.md"],
"commands": ["commands/**/*.md"],
"skills": "./skills/",
"mcpServers": "./.mcp.json"
}"#,
);
let error = load_plugin_from_directory(&root)
.expect_err("Claude Code plugin manifest should fail with guidance");
let rendered = error.to_string();
assert!(rendered.contains("field `skills` uses the Claude Code plugin contract"));
assert!(rendered.contains("field `mcpServers` uses the Claude Code plugin contract"));
assert!(rendered.contains("field `agents` uses the Claude Code plugin contract"));
assert!(rendered.contains("field `commands` uses Claude Code-style directory globs"));
assert!(rendered.contains("hook `SessionStart` uses the Claude Code lifecycle contract"));
let _ = fs::remove_dir_all(root);
}
#[test]
fn load_plugin_from_directory_rejects_missing_tool_or_command_paths() {
let root = temp_dir("manifest-paths");

2
rust/crates/runtime/Cargo.toml
View File

@ -13,7 +13,7 @@ regex = "1"
serde = { version = "1", features = ["derive"] }
serde_json.workspace = true
telemetry = { path = "../telemetry" }
tokio = { version = "1", features = ["io-util", "macros", "process", "rt", "rt-multi-thread", "time"] }
tokio = { version = "1", features = ["io-std", "io-util", "macros", "process", "rt", "rt-multi-thread", "time"] }
walkdir = "2"
[lints]

144
rust/crates/runtime/src/branch_lock.rs Normal file
View File

@ -0,0 +1,144 @@
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BranchLockIntent {
#[serde(rename = "laneId")]
pub lane_id: String,
pub branch: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub worktree: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub modules: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BranchLockCollision {
pub branch: String,
pub module: String,
#[serde(rename = "laneIds")]
pub lane_ids: Vec<String>,
}
#[must_use]
pub fn detect_branch_lock_collisions(intents: &[BranchLockIntent]) -> Vec<BranchLockCollision> {
let mut collisions = Vec::new();
for (index, left) in intents.iter().enumerate() {
for right in &intents[index + 1..] {
if left.branch != right.branch {
continue;
}
for module in overlapping_modules(&left.modules, &right.modules) {
collisions.push(BranchLockCollision {
branch: left.branch.clone(),
module,
lane_ids: vec![left.lane_id.clone(), right.lane_id.clone()],
});
}
}
}
collisions.sort_by(|a, b| {
a.branch
.cmp(&b.branch)
.then(a.module.cmp(&b.module))
.then(a.lane_ids.cmp(&b.lane_ids))
});
collisions.dedup();
collisions
}
fn overlapping_modules(left: &[String], right: &[String]) -> Vec<String> {
let mut overlaps = Vec::new();
for left_module in left {
for right_module in right {
if modules_overlap(left_module, right_module) {
overlaps.push(shared_scope(left_module, right_module));
}
}
}
overlaps.sort();
overlaps.dedup();
overlaps
}
fn modules_overlap(left: &str, right: &str) -> bool {
left == right
|| left.starts_with(&format!("{right}/"))
|| right.starts_with(&format!("{left}/"))
}
fn shared_scope(left: &str, right: &str) -> String {
if left.starts_with(&format!("{right}/")) || left == right {
right.to_string()
} else {
left.to_string()
}
}
#[cfg(test)]
mod tests {
use super::{detect_branch_lock_collisions, BranchLockIntent};
#[test]
fn detects_same_branch_same_module_collisions() {
let collisions = detect_branch_lock_collisions(&[
BranchLockIntent {
lane_id: "lane-a".to_string(),
branch: "feature/lock".to_string(),
worktree: Some("wt-a".to_string()),
modules: vec!["runtime/mcp".to_string()],
},
BranchLockIntent {
lane_id: "lane-b".to_string(),
branch: "feature/lock".to_string(),
worktree: Some("wt-b".to_string()),
modules: vec!["runtime/mcp".to_string()],
},
]);
assert_eq!(collisions.len(), 1);
assert_eq!(collisions[0].branch, "feature/lock");
assert_eq!(collisions[0].module, "runtime/mcp");
}
#[test]
fn detects_nested_module_scope_collisions() {
let collisions = detect_branch_lock_collisions(&[
BranchLockIntent {
lane_id: "lane-a".to_string(),
branch: "feature/lock".to_string(),
worktree: None,
modules: vec!["runtime".to_string()],
},
BranchLockIntent {
lane_id: "lane-b".to_string(),
branch: "feature/lock".to_string(),
worktree: None,
modules: vec!["runtime/mcp".to_string()],
},
]);
assert_eq!(collisions[0].module, "runtime");
}
#[test]
fn ignores_different_branches() {
let collisions = detect_branch_lock_collisions(&[
BranchLockIntent {
lane_id: "lane-a".to_string(),
branch: "feature/a".to_string(),
worktree: None,
modules: vec!["runtime/mcp".to_string()],
},
BranchLockIntent {
lane_id: "lane-b".to_string(),
branch: "feature/b".to_string(),
worktree: None,
modules: vec!["runtime/mcp".to_string()],
},
]);
assert!(collisions.is_empty());
}
}

426
rust/crates/runtime/src/config.rs
View File

@ -9,6 +9,27 @@ use crate::sandbox::{FilesystemIsolationMode, SandboxConfig};
/// Schema name advertised by generated settings files.
pub const CLAW_SETTINGS_SCHEMA_NAME: &str = "SettingsSchema";
/// Top-level settings keys recognized by the runtime configuration loader.
const KNOWN_TOP_LEVEL_KEYS: &[&str] = &[
"$schema",
"enabledPlugins",
"env",
"hooks",
"mcpServers",
"model",
"oauth",
"permissionMode",
"permissions",
"plugins",
"sandbox",
];
/// Deprecated top-level keys mapped to their replacement guidance.
const DEPRECATED_TOP_LEVEL_KEYS: &[(&str, &str)] = &[
("allowedTools", "permissions.allow"),
("ignorePatterns", "permissions.deny"),
];
/// Origin of a loaded settings file in the configuration precedence chain.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum ConfigSource {
@ -48,6 +69,7 @@ pub struct RuntimePluginConfig {
install_root: Option<String>,
registry_path: Option<String>,
bundled_root: Option<String>,
max_output_tokens: Option<u32>,
}
/// Structured feature configuration consumed by runtime subsystems.
@ -58,9 +80,20 @@ pub struct RuntimeFeatureConfig {
mcp: McpConfigCollection,
oauth: Option<OAuthConfig>,
model: Option<String>,
aliases: BTreeMap<String, String>,
permission_mode: Option<ResolvedPermissionMode>,
permission_rules: RuntimePermissionRuleConfig,
sandbox: SandboxConfig,
provider_fallbacks: ProviderFallbackConfig,
}
/// Ordered chain of fallback model identifiers used when the primary
/// provider returns a retryable failure (429/500/503/etc.). The chain is
/// strict: each entry is tried in order until one succeeds.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct ProviderFallbackConfig {
primary: Option<String>,
fallbacks: Vec<String>,
}
/// Hook command lists grouped by lifecycle stage.
@ -259,17 +292,33 @@ impl ConfigLoader {
let mut merged = BTreeMap::new();
let mut loaded_entries = Vec::new();
let mut mcp_servers = BTreeMap::new();
let mut all_warnings = Vec::new();
for entry in self.discover() {
let Some(value) = read_optional_json_object(&entry.path)? else {
crate::config_validate::check_unsupported_format(&entry.path)?;
let Some(parsed) = read_optional_json_object(&entry.path)? else {
continue;
};
validate_optional_hooks_config(&value, &entry.path)?;
merge_mcp_servers(&mut mcp_servers, entry.source, &value, &entry.path)?;
deep_merge_objects(&mut merged, &value);
let validation = crate::config_validate::validate_config_file(
&parsed.object,
&parsed.source,
&entry.path,
);
if !validation.is_ok() {
let first_error = &validation.errors[0];
return Err(ConfigError::Parse(first_error.to_string()));
}
all_warnings.extend(validation.warnings);
validate_optional_hooks_config(&parsed.object, &entry.path)?;
merge_mcp_servers(&mut mcp_servers, entry.source, &parsed.object, &entry.path)?;
deep_merge_objects(&mut merged, &parsed.object);
loaded_entries.push(entry);
}
for warning in &all_warnings {
eprintln!("warning: {warning}");
}
let merged_value = JsonValue::Object(merged.clone());
let feature_config = RuntimeFeatureConfig {
@ -280,9 +329,11 @@ impl ConfigLoader {
},
oauth: parse_optional_oauth_config(&merged_value, "merged settings.oauth")?,
model: parse_optional_model(&merged_value),
aliases: parse_optional_aliases(&merged_value)?,
permission_mode: parse_optional_permission_mode(&merged_value)?,
permission_rules: parse_optional_permission_rules(&merged_value)?,
sandbox: parse_optional_sandbox_config(&merged_value)?,
provider_fallbacks: parse_optional_provider_fallbacks(&merged_value)?,
};
Ok(RuntimeConfig {
@ -353,6 +404,11 @@ impl RuntimeConfig {
self.feature_config.model.as_deref()
}
#[must_use]
pub fn aliases(&self) -> &BTreeMap<String, String> {
&self.feature_config.aliases
}
#[must_use]
pub fn permission_mode(&self) -> Option<ResolvedPermissionMode> {
self.feature_config.permission_mode
@ -367,6 +423,11 @@ impl RuntimeConfig {
pub fn sandbox(&self) -> &SandboxConfig {
&self.feature_config.sandbox
}
#[must_use]
pub fn provider_fallbacks(&self) -> &ProviderFallbackConfig {
&self.feature_config.provider_fallbacks
}
}
impl RuntimeFeatureConfig {
@ -407,6 +468,11 @@ impl RuntimeFeatureConfig {
self.model.as_deref()
}
#[must_use]
pub fn aliases(&self) -> &BTreeMap<String, String> {
&self.aliases
}
#[must_use]
pub fn permission_mode(&self) -> Option<ResolvedPermissionMode> {
self.permission_mode
@ -421,6 +487,33 @@ impl RuntimeFeatureConfig {
pub fn sandbox(&self) -> &SandboxConfig {
&self.sandbox
}
#[must_use]
pub fn provider_fallbacks(&self) -> &ProviderFallbackConfig {
&self.provider_fallbacks
}
}
impl ProviderFallbackConfig {
#[must_use]
pub fn new(primary: Option<String>, fallbacks: Vec<String>) -> Self {
Self { primary, fallbacks }
}
#[must_use]
pub fn primary(&self) -> Option<&str> {
self.primary.as_deref()
}
#[must_use]
pub fn fallbacks(&self) -> &[String] {
&self.fallbacks
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.fallbacks.is_empty()
}
}
impl RuntimePluginConfig {
@ -449,6 +542,15 @@ impl RuntimePluginConfig {
self.bundled_root.as_deref()
}
#[must_use]
pub fn max_output_tokens(&self) -> Option<u32> {
self.max_output_tokens
}
pub fn set_max_output_tokens(&mut self, max_output_tokens: Option<u32>) {
self.max_output_tokens = max_output_tokens;
}
pub fn set_plugin_state(&mut self, plugin_id: String, enabled: bool) {
self.enabled_plugins.insert(plugin_id, enabled);
}
@ -572,9 +674,13 @@ impl McpServerConfig {
}
}
fn read_optional_json_object(
path: &Path,
) -> Result<Option<BTreeMap<String, JsonValue>>, ConfigError> {
/// Parsed JSON object paired with its raw source text for validation.
struct ParsedConfigFile {
object: BTreeMap<String, JsonValue>,
source: String,
}
fn read_optional_json_object(path: &Path) -> Result<Option<ParsedConfigFile>, ConfigError> {
let is_legacy_config = path.file_name().and_then(|name| name.to_str()) == Some(".claw.json");
let contents = match fs::read_to_string(path) {
Ok(contents) => contents,
@ -583,7 +689,10 @@ fn read_optional_json_object(
};
if contents.trim().is_empty() {
return Ok(Some(BTreeMap::new()));
return Ok(Some(ParsedConfigFile {
object: BTreeMap::new(),
source: contents,
}));
}
let parsed = match JsonValue::parse(&contents) {
@ -600,7 +709,10 @@ fn read_optional_json_object(
path.display()
)));
};
Ok(Some(object.clone()))
Ok(Some(ParsedConfigFile {
object: object.clone(),
source: contents,
}))
}
fn merge_mcp_servers(
@ -637,6 +749,13 @@ fn parse_optional_model(root: &JsonValue) -> Option<String> {
.map(ToOwned::to_owned)
}
fn parse_optional_aliases(root: &JsonValue) -> Result<BTreeMap<String, String>, ConfigError> {
let Some(object) = root.as_object() else {
return Ok(BTreeMap::new());
};
Ok(optional_string_map(object, "aliases", "merged settings")?.unwrap_or_default())
}
fn parse_optional_hooks_config(root: &JsonValue) -> Result<RuntimeHookConfig, ConfigError> {
let Some(object) = root.as_object() else {
return Ok(RuntimeHookConfig::default());
@ -714,6 +833,7 @@ fn parse_optional_plugin_config(root: &JsonValue) -> Result<RuntimePluginConfig,
optional_string(plugins, "registryPath", "merged settings.plugins")?.map(str::to_string);
config.bundled_root =
optional_string(plugins, "bundledRoot", "merged settings.plugins")?.map(str::to_string);
config.max_output_tokens = optional_u32(plugins, "maxOutputTokens", "merged settings.plugins")?;
Ok(config)
}
@ -776,6 +896,23 @@ fn parse_optional_sandbox_config(root: &JsonValue) -> Result<SandboxConfig, Conf
})
}
fn parse_optional_provider_fallbacks(
root: &JsonValue,
) -> Result<ProviderFallbackConfig, ConfigError> {
let Some(object) = root.as_object() else {
return Ok(ProviderFallbackConfig::default());
};
let Some(value) = object.get("providerFallbacks") else {
return Ok(ProviderFallbackConfig::default());
};
let entry = expect_object(value, "merged settings.providerFallbacks")?;
let primary =
optional_string(entry, "primary", "merged settings.providerFallbacks")?.map(str::to_string);
let fallbacks = optional_string_array(entry, "fallbacks", "merged settings.providerFallbacks")?
.unwrap_or_default();
Ok(ProviderFallbackConfig { primary, fallbacks })
}
fn parse_filesystem_mode_label(value: &str) -> Result<FilesystemIsolationMode, ConfigError> {
match value {
"off" => Ok(FilesystemIsolationMode::Off),
@ -957,6 +1094,27 @@ fn optional_u16(
}
}
fn optional_u32(
object: &BTreeMap<String, JsonValue>,
key: &str,
context: &str,
) -> Result<Option<u32>, ConfigError> {
match object.get(key) {
Some(value) => {
let Some(number) = value.as_i64() else {
return Err(ConfigError::Parse(format!(
"{context}: field {key} must be a non-negative integer"
)));
};
let number = u32::try_from(number).map_err(|_| {
ConfigError::Parse(format!("{context}: field {key} is out of range"))
})?;
Ok(Some(number))
}
None => Ok(None),
}
}
fn optional_u64(
object: &BTreeMap<String, JsonValue>,
key: &str,
@ -1247,6 +1405,66 @@ mod tests {
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn parses_provider_fallbacks_chain_with_primary_and_ordered_fallbacks() {
// given
let root = temp_dir();
let cwd = root.join("project");
let home = root.join("home").join(".claw");
fs::create_dir_all(cwd.join(".claw")).expect("project config dir");
fs::create_dir_all(&home).expect("home config dir");
fs::write(
home.join("settings.json"),
r#"{
"providerFallbacks": {
"primary": "claude-opus-4-6",
"fallbacks": ["grok-3", "grok-3-mini"]
}
}"#,
)
.expect("write provider fallback settings");
// when
let loaded = ConfigLoader::new(&cwd, &home)
.load()
.expect("config should load");
// then
let chain = loaded.provider_fallbacks();
assert_eq!(chain.primary(), Some("claude-opus-4-6"));
assert_eq!(
chain.fallbacks(),
&["grok-3".to_string(), "grok-3-mini".to_string()]
);
assert!(!chain.is_empty());
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn provider_fallbacks_default_is_empty_when_unset() {
// given
let root = temp_dir();
let cwd = root.join("project");
let home = root.join("home").join(".claw");
fs::create_dir_all(&home).expect("home config dir");
fs::create_dir_all(&cwd).expect("project dir");
fs::write(home.join("settings.json"), "{}").expect("write empty settings");
// when
let loaded = ConfigLoader::new(&cwd, &home)
.load()
.expect("config should load");
// then
let chain = loaded.provider_fallbacks();
assert_eq!(chain.primary(), None);
assert!(chain.fallbacks().is_empty());
assert!(chain.is_empty());
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn parses_typed_mcp_and_oauth_config() {
let root = temp_dir();
@ -1493,6 +1711,49 @@ mod tests {
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn parses_user_defined_model_aliases_from_settings() {
// given
let root = temp_dir();
let cwd = root.join("project");
let home = root.join("home").join(".claw");
fs::create_dir_all(cwd.join(".claw")).expect("project config dir");
fs::create_dir_all(&home).expect("home config dir");
fs::write(
home.join("settings.json"),
r#"{"aliases":{"fast":"claude-haiku-4-5-20251213","smart":"claude-opus-4-6"}}"#,
)
.expect("write user settings");
fs::write(
cwd.join(".claw").join("settings.local.json"),
r#"{"aliases":{"smart":"claude-sonnet-4-6","cheap":"grok-3-mini"}}"#,
)
.expect("write local settings");
// when
let loaded = ConfigLoader::new(&cwd, &home)
.load()
.expect("config should load");
// then
let aliases = loaded.aliases();
assert_eq!(
aliases.get("fast").map(String::as_str),
Some("claude-haiku-4-5-20251213")
);
assert_eq!(
aliases.get("smart").map(String::as_str),
Some("claude-sonnet-4-6")
);
assert_eq!(
aliases.get("cheap").map(String::as_str),
Some("grok-3-mini")
);
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn empty_settings_file_loads_defaults() {
// given
@ -1574,12 +1835,13 @@ mod tests {
.load()
.expect_err("config should fail");
// then
// then — config validation now catches the mixed array before the hooks parser
let rendered = error.to_string();
assert!(rendered.contains(&format!(
"{}: hooks: field PreToolUse must contain only strings",
project_settings.display()
)));
assert!(
rendered.contains("hooks.PreToolUse")
&& rendered.contains("must be an array of strings"),
"expected validation error for hooks.PreToolUse, got: {rendered}"
);
assert!(!rendered.contains("merged settings.hooks"));
fs::remove_dir_all(root).expect("cleanup temp dir");
@ -1645,4 +1907,140 @@ mod tests {
assert!(config.state_for("missing", true));
assert!(!config.state_for("missing", false));
}
#[test]
fn validates_unknown_top_level_keys_with_line_and_field_name() {
// given
let root = temp_dir();
let cwd = root.join("project");
let home = root.join("home").join(".claw");
let user_settings = home.join("settings.json");
fs::create_dir_all(&home).expect("home config dir");
fs::create_dir_all(&cwd).expect("project dir");
fs::write(
&user_settings,
"{\n \"model\": \"opus\",\n \"telemetry\": true\n}\n",
)
.expect("write user settings");
// when
let error = ConfigLoader::new(&cwd, &home)
.load()
.expect_err("config should fail");
// then
let rendered = error.to_string();
assert!(
rendered.contains(&format!("{}:3:", user_settings.display())),
"error should include file path and line number, got: {rendered}"
);
assert!(
rendered.contains("unknown field telemetry"),
"error should name the offending field, got: {rendered}"
);
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn validates_deprecated_top_level_keys_with_replacement_guidance() {
// given
let root = temp_dir();
let cwd = root.join("project");
let home = root.join("home").join(".claw");
let user_settings = home.join("settings.json");
fs::create_dir_all(&home).expect("home config dir");
fs::create_dir_all(&cwd).expect("project dir");
fs::write(
&user_settings,
"{\n \"model\": \"opus\",\n \"allowedTools\": [\"Read\"]\n}\n",
)
.expect("write user settings");
// when
let error = ConfigLoader::new(&cwd, &home)
.load()
.expect_err("config should fail");
// then
let rendered = error.to_string();
assert!(
rendered.contains(&format!("{}:3:", user_settings.display())),
"error should include file path and line number, got: {rendered}"
);
assert!(
rendered.contains("deprecated field allowedTools"),
"error should call out the deprecated field, got: {rendered}"
);
assert!(
rendered.contains("permissions.allow"),
"error should mention the replacement field, got: {rendered}"
);
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn validates_wrong_type_for_known_field_with_field_path() {
// given
let root = temp_dir();
let cwd = root.join("project");
let home = root.join("home").join(".claw");
let user_settings = home.join("settings.json");
fs::create_dir_all(&home).expect("home config dir");
fs::create_dir_all(&cwd).expect("project dir");
fs::write(
&user_settings,
"{\n \"hooks\": {\n \"PreToolUse\": \"not-an-array\"\n }\n}\n",
)
.expect("write user settings");
// when
let error = ConfigLoader::new(&cwd, &home)
.load()
.expect_err("config should fail");
// then
let rendered = error.to_string();
assert!(
rendered.contains(&format!("{}: hooks", user_settings.display())),
"error should include file path and field path, got: {rendered}"
);
assert!(
rendered.contains("PreToolUse must be an array"),
"error should describe the type mismatch, got: {rendered}"
);
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn unknown_top_level_key_suggests_closest_match() {
// given
let root = temp_dir();
let cwd = root.join("project");
let home = root.join("home").join(".claw");
let user_settings = home.join("settings.json");
fs::create_dir_all(&home).expect("home config dir");
fs::create_dir_all(&cwd).expect("project dir");
fs::write(&user_settings, "{\n \"modle\": \"opus\"\n}\n").expect("write user settings");
// when
let error = ConfigLoader::new(&cwd, &home)
.load()
.expect_err("config should fail");
// then
let rendered = error.to_string();
assert!(
rendered.contains("unknown field modle"),
"error should name the offending field, got: {rendered}"
);
assert!(
rendered.contains("did you mean model?"),
"error should suggest the closest known key, got: {rendered}"
);
fs::remove_dir_all(root).expect("cleanup temp dir");
}
}

887
rust/crates/runtime/src/config_validate.rs Normal file
View File

@ -0,0 +1,887 @@
use std::collections::BTreeMap;
use std::path::Path;
use crate::config::ConfigError;
use crate::json::JsonValue;
/// Diagnostic emitted when a config file contains a suspect field.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConfigDiagnostic {
pub path: String,
pub field: String,
pub line: Option<usize>,
pub kind: DiagnosticKind,
}
/// Classification of the diagnostic.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DiagnosticKind {
UnknownKey {
suggestion: Option<String>,
},
WrongType {
expected: &'static str,
got: &'static str,
},
Deprecated {
replacement: &'static str,
},
}
impl std::fmt::Display for ConfigDiagnostic {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let location = self
.line
.map_or_else(String::new, |line| format!(" (line {line})"));
match &self.kind {
DiagnosticKind::UnknownKey { suggestion: None } => {
write!(f, "{}: unknown key \"{}\"{location}", self.path, self.field)
}
DiagnosticKind::UnknownKey {
suggestion: Some(hint),
} => {
write!(
f,
"{}: unknown key \"{}\"{location}. Did you mean \"{}\"?",
self.path, self.field, hint
)
}
DiagnosticKind::WrongType { expected, got } => {
write!(
f,
"{}: field \"{}\" must be {expected}, got {got}{location}",
self.path, self.field
)
}
DiagnosticKind::Deprecated { replacement } => {
write!(
f,
"{}: field \"{}\" is deprecated{location}. Use \"{replacement}\" instead",
self.path, self.field
)
}
}
}
}
/// Result of validating a single config file.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ValidationResult {
pub errors: Vec<ConfigDiagnostic>,
pub warnings: Vec<ConfigDiagnostic>,
}
impl ValidationResult {
#[must_use]
pub fn is_ok(&self) -> bool {
self.errors.is_empty()
}
fn merge(&mut self, other: Self) {
self.errors.extend(other.errors);
self.warnings.extend(other.warnings);
}
}
// ---- known-key schema ----
/// Expected type for a config field.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum FieldType {
String,
Bool,
Object,
StringArray,
Number,
}
impl FieldType {
fn label(self) -> &'static str {
match self {
Self::String => "a string",
Self::Bool => "a boolean",
Self::Object => "an object",
Self::StringArray => "an array of strings",
Self::Number => "a number",
}
}
fn matches(self, value: &JsonValue) -> bool {
match self {
Self::String => value.as_str().is_some(),
Self::Bool => value.as_bool().is_some(),
Self::Object => value.as_object().is_some(),
Self::StringArray => value
.as_array()
.is_some_and(|arr| arr.iter().all(|v| v.as_str().is_some())),
Self::Number => value.as_i64().is_some(),
}
}
}
fn json_type_label(value: &JsonValue) -> &'static str {
match value {
JsonValue::Null => "null",
JsonValue::Bool(_) => "a boolean",
JsonValue::Number(_) => "a number",
JsonValue::String(_) => "a string",
JsonValue::Array(_) => "an array",
JsonValue::Object(_) => "an object",
}
}
struct FieldSpec {
name: &'static str,
expected: FieldType,
}
struct DeprecatedField {
name: &'static str,
replacement: &'static str,
}
const TOP_LEVEL_FIELDS: &[FieldSpec] = &[
FieldSpec {
name: "$schema",
expected: FieldType::String,
},
FieldSpec {
name: "model",
expected: FieldType::String,
},
FieldSpec {
name: "hooks",
expected: FieldType::Object,
},
FieldSpec {
name: "permissions",
expected: FieldType::Object,
},
FieldSpec {
name: "permissionMode",
expected: FieldType::String,
},
FieldSpec {
name: "mcpServers",
expected: FieldType::Object,
},
FieldSpec {
name: "oauth",
expected: FieldType::Object,
},
FieldSpec {
name: "enabledPlugins",
expected: FieldType::Object,
},
FieldSpec {
name: "plugins",
expected: FieldType::Object,
},
FieldSpec {
name: "sandbox",
expected: FieldType::Object,
},
FieldSpec {
name: "env",
expected: FieldType::Object,
},
];
const HOOKS_FIELDS: &[FieldSpec] = &[
FieldSpec {
name: "PreToolUse",
expected: FieldType::StringArray,
},
FieldSpec {
name: "PostToolUse",
expected: FieldType::StringArray,
},
FieldSpec {
name: "PostToolUseFailure",
expected: FieldType::StringArray,
},
];
const PERMISSIONS_FIELDS: &[FieldSpec] = &[
FieldSpec {
name: "defaultMode",
expected: FieldType::String,
},
FieldSpec {
name: "allow",
expected: FieldType::StringArray,
},
FieldSpec {
name: "deny",
expected: FieldType::StringArray,
},
FieldSpec {
name: "ask",
expected: FieldType::StringArray,
},
];
const PLUGINS_FIELDS: &[FieldSpec] = &[
FieldSpec {
name: "enabled",
expected: FieldType::Object,
},
FieldSpec {
name: "externalDirectories",
expected: FieldType::StringArray,
},
FieldSpec {
name: "installRoot",
expected: FieldType::String,
},
FieldSpec {
name: "registryPath",
expected: FieldType::String,
},
FieldSpec {
name: "bundledRoot",
expected: FieldType::String,
},
FieldSpec {
name: "maxOutputTokens",
expected: FieldType::Number,
},
];
const SANDBOX_FIELDS: &[FieldSpec] = &[
FieldSpec {
name: "enabled",
expected: FieldType::Bool,
},
FieldSpec {
name: "namespaceRestrictions",
expected: FieldType::Bool,
},
FieldSpec {
name: "networkIsolation",
expected: FieldType::Bool,
},
FieldSpec {
name: "filesystemMode",
expected: FieldType::String,
},
FieldSpec {
name: "allowedMounts",
expected: FieldType::StringArray,
},
];
const OAUTH_FIELDS: &[FieldSpec] = &[
FieldSpec {
name: "clientId",
expected: FieldType::String,
},
FieldSpec {
name: "authorizeUrl",
expected: FieldType::String,
},
FieldSpec {
name: "tokenUrl",
expected: FieldType::String,
},
FieldSpec {
name: "callbackPort",
expected: FieldType::Number,
},
FieldSpec {
name: "manualRedirectUrl",
expected: FieldType::String,
},
FieldSpec {
name: "scopes",
expected: FieldType::StringArray,
},
];
const DEPRECATED_FIELDS: &[DeprecatedField] = &[
DeprecatedField {
name: "permissionMode",
replacement: "permissions.defaultMode",
},
DeprecatedField {
name: "enabledPlugins",
replacement: "plugins.enabled",
},
];
// ---- line-number resolution ----
/// Find the 1-based line number where a JSON key first appears in the raw source.
fn find_key_line(source: &str, key: &str) -> Option<usize> {
// Search for `"key"` followed by optional whitespace and a colon.
let needle = format!("\"{key}\"");
let mut search_start = 0;
while let Some(offset) = source[search_start..].find(&needle) {
let absolute = search_start + offset;
let after = absolute + needle.len();
// Verify the next non-whitespace char is `:` to confirm this is a key, not a value.
if source[after..].chars().find(|ch| !ch.is_ascii_whitespace()) == Some(':') {
return Some(source[..absolute].chars().filter(|&ch| ch == '\n').count() + 1);
}
search_start = after;
}
None
}
// ---- core validation ----
fn validate_object_keys(
object: &BTreeMap<String, JsonValue>,
known_fields: &[FieldSpec],
prefix: &str,
source: &str,
path_display: &str,
) -> ValidationResult {
let mut result = ValidationResult {
errors: Vec::new(),
warnings: Vec::new(),
};
let known_names: Vec<&str> = known_fields.iter().map(|f| f.name).collect();
for (key, value) in object {
let field_path = if prefix.is_empty() {
key.clone()
} else {
format!("{prefix}.{key}")
};
if let Some(spec) = known_fields.iter().find(|f| f.name == key) {
// Type check.
if !spec.expected.matches(value) {
result.errors.push(ConfigDiagnostic {
path: path_display.to_string(),
field: field_path,
line: find_key_line(source, key),
kind: DiagnosticKind::WrongType {
expected: spec.expected.label(),
got: json_type_label(value),
},
});
}
} else {
// Unknown key.
let suggestion = suggest_field(key, &known_names);
result.errors.push(ConfigDiagnostic {
path: path_display.to_string(),
field: field_path,
line: find_key_line(source, key),
kind: DiagnosticKind::UnknownKey { suggestion },
});
}
}
result
}
fn suggest_field(input: &str, candidates: &[&str]) -> Option<String> {
let input_lower = input.to_ascii_lowercase();
candidates
.iter()
.filter_map(|candidate| {
let distance = simple_edit_distance(&input_lower, &candidate.to_ascii_lowercase());
(distance <= 3).then_some((distance, *candidate))
})
.min_by_key(|(distance, _)| *distance)
.map(|(_, name)| name.to_string())
}
fn simple_edit_distance(left: &str, right: &str) -> usize {
if left.is_empty() {
return right.len();
}
if right.is_empty() {
return left.len();
}
let right_chars: Vec<char> = right.chars().collect();
let mut previous: Vec<usize> = (0..=right_chars.len()).collect();
let mut current = vec![0; right_chars.len() + 1];
for (left_index, left_char) in left.chars().enumerate() {
current[0] = left_index + 1;
for (right_index, right_char) in right_chars.iter().enumerate() {
let cost = usize::from(left_char != *right_char);
current[right_index + 1] = (previous[right_index + 1] + 1)
.min(current[right_index] + 1)
.min(previous[right_index] + cost);
}
previous.clone_from(&current);
}
previous[right_chars.len()]
}
/// Validate a parsed config file's keys and types against the known schema.
///
/// Returns diagnostics (errors and deprecation warnings) without blocking the load.
pub fn validate_config_file(
object: &BTreeMap<String, JsonValue>,
source: &str,
file_path: &Path,
) -> ValidationResult {
let path_display = file_path.display().to_string();
let mut result = validate_object_keys(object, TOP_LEVEL_FIELDS, "", source, &path_display);
// Check deprecated fields.
for deprecated in DEPRECATED_FIELDS {
if object.contains_key(deprecated.name) {
result.warnings.push(ConfigDiagnostic {
path: path_display.clone(),
field: deprecated.name.to_string(),
line: find_key_line(source, deprecated.name),
kind: DiagnosticKind::Deprecated {
replacement: deprecated.replacement,
},
});
}
}
// Validate known nested objects.
if let Some(hooks) = object.get("hooks").and_then(JsonValue::as_object) {
result.merge(validate_object_keys(
hooks,
HOOKS_FIELDS,
"hooks",
source,
&path_display,
));
}
if let Some(permissions) = object.get("permissions").and_then(JsonValue::as_object) {
result.merge(validate_object_keys(
permissions,
PERMISSIONS_FIELDS,
"permissions",
source,
&path_display,
));
}
if let Some(plugins) = object.get("plugins").and_then(JsonValue::as_object) {
result.merge(validate_object_keys(
plugins,
PLUGINS_FIELDS,
"plugins",
source,
&path_display,
));
}
if let Some(sandbox) = object.get("sandbox").and_then(JsonValue::as_object) {
result.merge(validate_object_keys(
sandbox,
SANDBOX_FIELDS,
"sandbox",
source,
&path_display,
));
}
if let Some(oauth) = object.get("oauth").and_then(JsonValue::as_object) {
result.merge(validate_object_keys(
oauth,
OAUTH_FIELDS,
"oauth",
source,
&path_display,
));
}
result
}
/// Check whether a file path uses an unsupported config format (e.g. TOML).
pub fn check_unsupported_format(file_path: &Path) -> Result<(), ConfigError> {
if let Some(ext) = file_path.extension().and_then(|e| e.to_str()) {
if ext.eq_ignore_ascii_case("toml") {
return Err(ConfigError::Parse(format!(
"{}: TOML config files are not supported. Use JSON (settings.json) instead",
file_path.display()
)));
}
}
Ok(())
}
/// Format all diagnostics into a human-readable report.
#[must_use]
pub fn format_diagnostics(result: &ValidationResult) -> String {
let mut lines = Vec::new();
for warning in &result.warnings {
lines.push(format!("warning: {warning}"));
}
for error in &result.errors {
lines.push(format!("error: {error}"));
}
lines.join("\n")
}
#[cfg(test)]
mod tests {
use super::*;
use std::path::PathBuf;
fn test_path() -> PathBuf {
PathBuf::from("/test/settings.json")
}
#[test]
fn detects_unknown_top_level_key() {
// given
let source = r#"{"model": "opus", "unknownField": true}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].field, "unknownField");
assert!(matches!(
result.errors[0].kind,
DiagnosticKind::UnknownKey { .. }
));
}
#[test]
fn detects_wrong_type_for_model() {
// given
let source = r#"{"model": 123}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].field, "model");
assert!(matches!(
result.errors[0].kind,
DiagnosticKind::WrongType {
expected: "a string",
got: "a number"
}
));
}
#[test]
fn detects_deprecated_permission_mode() {
// given
let source = r#"{"permissionMode": "plan"}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.warnings.len(), 1);
assert_eq!(result.warnings[0].field, "permissionMode");
assert!(matches!(
result.warnings[0].kind,
DiagnosticKind::Deprecated {
replacement: "permissions.defaultMode"
}
));
}
#[test]
fn detects_deprecated_enabled_plugins() {
// given
let source = r#"{"enabledPlugins": {"tool-guard@builtin": true}}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.warnings.len(), 1);
assert_eq!(result.warnings[0].field, "enabledPlugins");
assert!(matches!(
result.warnings[0].kind,
DiagnosticKind::Deprecated {
replacement: "plugins.enabled"
}
));
}
#[test]
fn reports_line_number_for_unknown_key() {
// given
let source = "{\n \"model\": \"opus\",\n \"badKey\": true\n}";
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].line, Some(3));
assert_eq!(result.errors[0].field, "badKey");
}
#[test]
fn reports_line_number_for_wrong_type() {
// given
let source = "{\n \"model\": 42\n}";
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].line, Some(2));
}
#[test]
fn validates_nested_hooks_keys() {
// given
let source = r#"{"hooks": {"PreToolUse": ["cmd"], "BadHook": ["x"]}}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].field, "hooks.BadHook");
}
#[test]
fn validates_nested_permissions_keys() {
// given
let source = r#"{"permissions": {"allow": ["Read"], "denyAll": true}}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].field, "permissions.denyAll");
}
#[test]
fn validates_nested_sandbox_keys() {
// given
let source = r#"{"sandbox": {"enabled": true, "containerMode": "strict"}}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].field, "sandbox.containerMode");
}
#[test]
fn validates_nested_plugins_keys() {
// given
let source = r#"{"plugins": {"installRoot": "/tmp", "autoUpdate": true}}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].field, "plugins.autoUpdate");
}
#[test]
fn validates_nested_oauth_keys() {
// given
let source = r#"{"oauth": {"clientId": "abc", "secret": "hidden"}}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].field, "oauth.secret");
}
#[test]
fn valid_config_produces_no_diagnostics() {
// given
let source = r#"{
"model": "opus",
"hooks": {"PreToolUse": ["guard"]},
"permissions": {"defaultMode": "plan", "allow": ["Read"]},
"mcpServers": {},
"sandbox": {"enabled": false}
}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert!(result.is_ok());
assert!(result.warnings.is_empty());
}
#[test]
fn suggests_close_field_name() {
// given
let source = r#"{"modle": "opus"}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
match &result.errors[0].kind {
DiagnosticKind::UnknownKey {
suggestion: Some(s),
} => assert_eq!(s, "model"),
other => panic!("expected suggestion, got {other:?}"),
}
}
#[test]
fn format_diagnostics_includes_all_entries() {
// given
let source = r#"{"permissionMode": "plan", "badKey": 1}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
let result = validate_config_file(object, source, &test_path());
// when
let output = format_diagnostics(&result);
// then
assert!(output.contains("warning:"));
assert!(output.contains("error:"));
assert!(output.contains("badKey"));
assert!(output.contains("permissionMode"));
}
#[test]
fn check_unsupported_format_rejects_toml() {
// given
let path = PathBuf::from("/home/.claw/settings.toml");
// when
let result = check_unsupported_format(&path);
// then
assert!(result.is_err());
let message = result.unwrap_err().to_string();
assert!(message.contains("TOML"));
assert!(message.contains("settings.toml"));
}
#[test]
fn check_unsupported_format_allows_json() {
// given
let path = PathBuf::from("/home/.claw/settings.json");
// when / then
assert!(check_unsupported_format(&path).is_ok());
}
#[test]
fn wrong_type_in_nested_sandbox_field() {
// given
let source = r#"{"sandbox": {"enabled": "yes"}}"#;
let parsed = JsonValue::parse(source).expect("valid json");
let object = parsed.as_object().expect("object");
// when
let result = validate_config_file(object, source, &test_path());
// then
assert_eq!(result.errors.len(), 1);
assert_eq!(result.errors[0].field, "sandbox.enabled");
assert!(matches!(
result.errors[0].kind,
DiagnosticKind::WrongType {
expected: "a boolean",
got: "a string"
}
));
}
#[test]
fn display_format_unknown_key_with_line() {
// given
let diag = ConfigDiagnostic {
path: "/test/settings.json".to_string(),
field: "badKey".to_string(),
line: Some(5),
kind: DiagnosticKind::UnknownKey { suggestion: None },
};
// when
let output = diag.to_string();
// then
assert_eq!(
output,
r#"/test/settings.json: unknown key "badKey" (line 5)"#
);
}
#[test]
fn display_format_wrong_type_with_line() {
// given
let diag = ConfigDiagnostic {
path: "/test/settings.json".to_string(),
field: "model".to_string(),
line: Some(2),
kind: DiagnosticKind::WrongType {
expected: "a string",
got: "a number",
},
};
// when
let output = diag.to_string();
// then
assert_eq!(
output,
r#"/test/settings.json: field "model" must be a string, got a number (line 2)"#
);
}
#[test]
fn display_format_deprecated_with_line() {
// given
let diag = ConfigDiagnostic {
path: "/test/settings.json".to_string(),
field: "permissionMode".to_string(),
line: Some(3),
kind: DiagnosticKind::Deprecated {
replacement: "permissions.defaultMode",
},
};
// when
let output = diag.to_string();
// then
assert_eq!(
output,
r#"/test/settings.json: field "permissionMode" is deprecated (line 3). Use "permissions.defaultMode" instead"#
);
}
}

5
rust/crates/runtime/src/conversation.rs
View File

@ -504,6 +504,10 @@ where
&self.session
}
pub fn session_mut(&mut self) -> &mut Session {
&mut self.session
}
#[must_use]
pub fn fork_session(&self, branch_name: Option<String>) -> Session {
self.session.fork(branch_name)
@ -890,6 +894,7 @@ mod tests {
current_date: "2026-03-31".to_string(),
git_status: None,
git_diff: None,
git_context: None,
instruction_files: Vec::new(),
})
.with_os("linux", "6.8")

5
rust/crates/runtime/src/file_ops.rs
View File

@ -28,6 +28,7 @@ fn is_binary_file(path: &Path) -> io::Result<bool> {
/// Validate that a resolved path stays within the given workspace root.
/// Returns the canonical path on success, or an error if the path escapes
/// the workspace boundary (e.g. via `../` traversal or symlink).
#[allow(dead_code)]
fn validate_workspace_boundary(resolved: &Path, workspace_root: &Path) -> io::Result<()> {
if !resolved.starts_with(workspace_root) {
return Err(io::Error::new(
@ -557,6 +558,7 @@ fn normalize_path_allow_missing(path: &str) -> io::Result<PathBuf> {
}
/// Read a file with workspace boundary enforcement.
#[allow(dead_code)]
pub fn read_file_in_workspace(
path: &str,
offset: Option<usize>,
@ -572,6 +574,7 @@ pub fn read_file_in_workspace(
}
/// Write a file with workspace boundary enforcement.
#[allow(dead_code)]
pub fn write_file_in_workspace(
path: &str,
content: &str,
@ -586,6 +589,7 @@ pub fn write_file_in_workspace(
}
/// Edit a file with workspace boundary enforcement.
#[allow(dead_code)]
pub fn edit_file_in_workspace(
path: &str,
old_string: &str,
@ -602,6 +606,7 @@ pub fn edit_file_in_workspace(
}
/// Check whether a path is a symlink that resolves outside the workspace.
#[allow(dead_code)]
pub fn is_symlink_escape(path: &Path, workspace_root: &Path) -> io::Result<bool> {
let metadata = fs::symlink_metadata(path)?;
if !metadata.is_symlink() {

324
rust/crates/runtime/src/git_context.rs Normal file
View File

@ -0,0 +1,324 @@
use std::path::Path;
use std::process::Command;
/// A single git commit entry from the log.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GitCommitEntry {
pub hash: String,
pub subject: String,
}
/// Git-aware context gathered at startup for injection into the system prompt.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GitContext {
pub branch: Option<String>,
pub recent_commits: Vec<GitCommitEntry>,
pub staged_files: Vec<String>,
}
const MAX_RECENT_COMMITS: usize = 5;
impl GitContext {
/// Detect the git context from the given working directory.
///
/// Returns `None` when the directory is not inside a git repository.
#[must_use]
pub fn detect(cwd: &Path) -> Option<Self> {
// Quick gate: is this a git repo at all?
let rev_parse = Command::new("git")
.args(["rev-parse", "--is-inside-work-tree"])
.current_dir(cwd)
.output()
.ok()?;
if !rev_parse.status.success() {
return None;
}
Some(Self {
branch: read_branch(cwd),
recent_commits: read_recent_commits(cwd),
staged_files: read_staged_files(cwd),
})
}
/// Render a human-readable summary suitable for system-prompt injection.
#[must_use]
pub fn render(&self) -> String {
let mut lines = Vec::new();
if let Some(branch) = &self.branch {
lines.push(format!("Git branch: {branch}"));
}
if !self.recent_commits.is_empty() {
lines.push(String::new());
lines.push("Recent commits:".to_string());
for entry in &self.recent_commits {
lines.push(format!(" {} {}", entry.hash, entry.subject));
}
}
if !self.staged_files.is_empty() {
lines.push(String::new());
lines.push("Staged files:".to_string());
for file in &self.staged_files {
lines.push(format!(" {file}"));
}
}
lines.join("\n")
}
}
fn read_branch(cwd: &Path) -> Option<String> {
let output = Command::new("git")
.args(["rev-parse", "--abbrev-ref", "HEAD"])
.current_dir(cwd)
.output()
.ok()?;
if !output.status.success() {
return None;
}
let branch = String::from_utf8(output.stdout).ok()?;
let trimmed = branch.trim();
if trimmed.is_empty() || trimmed == "HEAD" {
None
} else {
Some(trimmed.to_string())
}
}
fn read_recent_commits(cwd: &Path) -> Vec<GitCommitEntry> {
let output = Command::new("git")
.args([
"--no-optional-locks",
"log",
"--oneline",
"-n",
&MAX_RECENT_COMMITS.to_string(),
"--no-decorate",
])
.current_dir(cwd)
.output()
.ok();
let Some(output) = output else {
return Vec::new();
};
if !output.status.success() {
return Vec::new();
}
let stdout = String::from_utf8(output.stdout).unwrap_or_default();
stdout
.lines()
.filter_map(|line| {
let line = line.trim();
if line.is_empty() {
return None;
}
let (hash, subject) = line.split_once(' ')?;
Some(GitCommitEntry {
hash: hash.to_string(),
subject: subject.to_string(),
})
})
.collect()
}
fn read_staged_files(cwd: &Path) -> Vec<String> {
let output = Command::new("git")
.args(["--no-optional-locks", "diff", "--cached", "--name-only"])
.current_dir(cwd)
.output()
.ok();
let Some(output) = output else {
return Vec::new();
};
if !output.status.success() {
return Vec::new();
}
let stdout = String::from_utf8(output.stdout).unwrap_or_default();
stdout
.lines()
.filter(|line| !line.trim().is_empty())
.map(|line| line.trim().to_string())
.collect()
}
#[cfg(test)]
mod tests {
use super::{GitCommitEntry, GitContext};
use std::fs;
use std::process::Command;
use std::time::{SystemTime, UNIX_EPOCH};
fn temp_dir(label: &str) -> std::path::PathBuf {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.expect("time should be after epoch")
.as_nanos();
std::env::temp_dir().join(format!("runtime-git-context-{label}-{nanos}"))
}
fn env_lock() -> std::sync::MutexGuard<'static, ()> {
crate::test_env_lock()
}
fn ensure_valid_cwd() {
if std::env::current_dir().is_err() {
std::env::set_current_dir(env!("CARGO_MANIFEST_DIR"))
.expect("test cwd should be recoverable");
}
}
#[test]
fn returns_none_for_non_git_directory() {
// given
let _guard = env_lock();
ensure_valid_cwd();
let root = temp_dir("non-git");
fs::create_dir_all(&root).expect("create dir");
// when
let context = GitContext::detect(&root);
// then
assert!(context.is_none());
fs::remove_dir_all(root).expect("cleanup");
}
#[test]
fn detects_branch_name_and_commits() {
// given
let _guard = env_lock();
ensure_valid_cwd();
let root = temp_dir("branch-commits");
fs::create_dir_all(&root).expect("create dir");
git(&root, &["init", "--quiet", "--initial-branch=main"]);
git(&root, &["config", "user.email", "tests@example.com"]);
git(&root, &["config", "user.name", "Git Context Tests"]);
fs::write(root.join("a.txt"), "a\n").expect("write a");
git(&root, &["add", "a.txt"]);
git(&root, &["commit", "-m", "first commit", "--quiet"]);
fs::write(root.join("b.txt"), "b\n").expect("write b");
git(&root, &["add", "b.txt"]);
git(&root, &["commit", "-m", "second commit", "--quiet"]);
// when
let context = GitContext::detect(&root).expect("should detect git repo");
// then
assert_eq!(context.branch.as_deref(), Some("main"));
assert_eq!(context.recent_commits.len(), 2);
assert_eq!(context.recent_commits[0].subject, "second commit");
assert_eq!(context.recent_commits[1].subject, "first commit");
assert!(context.staged_files.is_empty());
fs::remove_dir_all(root).expect("cleanup");
}
#[test]
fn detects_staged_files() {
// given
let _guard = env_lock();
ensure_valid_cwd();
let root = temp_dir("staged");
fs::create_dir_all(&root).expect("create dir");
git(&root, &["init", "--quiet", "--initial-branch=main"]);
git(&root, &["config", "user.email", "tests@example.com"]);
git(&root, &["config", "user.name", "Git Context Tests"]);
fs::write(root.join("init.txt"), "init\n").expect("write init");
git(&root, &["add", "init.txt"]);
git(&root, &["commit", "-m", "initial", "--quiet"]);
fs::write(root.join("staged.txt"), "staged\n").expect("write staged");
git(&root, &["add", "staged.txt"]);
// when
let context = GitContext::detect(&root).expect("should detect git repo");
// then
assert_eq!(context.staged_files, vec!["staged.txt"]);
fs::remove_dir_all(root).expect("cleanup");
}
#[test]
fn render_formats_all_sections() {
// given
let context = GitContext {
branch: Some("feat/test".to_string()),
recent_commits: vec![
GitCommitEntry {
hash: "abc1234".to_string(),
subject: "add feature".to_string(),
},
GitCommitEntry {
hash: "def5678".to_string(),
subject: "fix bug".to_string(),
},
],
staged_files: vec!["src/main.rs".to_string()],
};
// when
let rendered = context.render();
// then
assert!(rendered.contains("Git branch: feat/test"));
assert!(rendered.contains("abc1234 add feature"));
assert!(rendered.contains("def5678 fix bug"));
assert!(rendered.contains("src/main.rs"));
}
#[test]
fn render_omits_empty_sections() {
// given
let context = GitContext {
branch: Some("main".to_string()),
recent_commits: Vec::new(),
staged_files: Vec::new(),
};
// when
let rendered = context.render();
// then
assert!(rendered.contains("Git branch: main"));
assert!(!rendered.contains("Recent commits:"));
assert!(!rendered.contains("Staged files:"));
}
#[test]
fn limits_to_five_recent_commits() {
// given
let _guard = env_lock();
ensure_valid_cwd();
let root = temp_dir("five-commits");
fs::create_dir_all(&root).expect("create dir");
git(&root, &["init", "--quiet", "--initial-branch=main"]);
git(&root, &["config", "user.email", "tests@example.com"]);
git(&root, &["config", "user.name", "Git Context Tests"]);
for i in 1..=8 {
let name = format!("file{i}.txt");
fs::write(root.join(&name), format!("{i}\n")).expect("write file");
git(&root, &["add", &name]);
git(&root, &["commit", "-m", &format!("commit {i}"), "--quiet"]);
}
// when
let context = GitContext::detect(&root).expect("should detect git repo");
// then
assert_eq!(context.recent_commits.len(), 5);
assert_eq!(context.recent_commits[0].subject, "commit 8");
assert_eq!(context.recent_commits[4].subject, "commit 4");
fs::remove_dir_all(root).expect("cleanup");
}
fn git(cwd: &std::path::Path, args: &[&str]) {
let status = Command::new("git")
.args(args)
.current_dir(cwd)
.output()
.unwrap_or_else(|_| panic!("git {args:?} should run"))
.status;
assert!(status.success(), "git {args:?} failed");
}
}

158
rust/crates/runtime/src/lane_events.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::similar_names)]
use serde::{Deserialize, Serialize};
use serde_json::Value;
@ -76,6 +77,20 @@ pub struct LaneEventBlocker {
pub detail: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LaneCommitProvenance {
pub commit: String,
pub branch: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub worktree: Option<String>,
#[serde(rename = "canonicalCommit", skip_serializing_if = "Option::is_none")]
pub canonical_commit: Option<String>,
#[serde(rename = "supersededBy", skip_serializing_if = "Option::is_none")]
pub superseded_by: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub lineage: Vec<String>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LaneEvent {
pub event: LaneEventName,
@ -114,8 +129,42 @@ impl LaneEvent {
#[must_use]
pub fn finished(emitted_at: impl Into<String>, detail: Option<String>) -> Self {
Self::new(LaneEventName::Finished, LaneEventStatus::Completed, emitted_at)
.with_optional_detail(detail)
Self::new(
LaneEventName::Finished,
LaneEventStatus::Completed,
emitted_at,
)
.with_optional_detail(detail)
}
#[must_use]
pub fn commit_created(
emitted_at: impl Into<String>,
detail: Option<String>,
provenance: LaneCommitProvenance,
) -> Self {
Self::new(
LaneEventName::CommitCreated,
LaneEventStatus::Completed,
emitted_at,
)
.with_optional_detail(detail)
.with_data(serde_json::to_value(provenance).expect("commit provenance should serialize"))
}
#[must_use]
pub fn superseded(
emitted_at: impl Into<String>,
detail: Option<String>,
provenance: LaneCommitProvenance,
) -> Self {
Self::new(
LaneEventName::Superseded,
LaneEventStatus::Superseded,
emitted_at,
)
.with_optional_detail(detail)
.with_data(serde_json::to_value(provenance).expect("commit provenance should serialize"))
}
#[must_use]
@ -157,12 +206,53 @@ impl LaneEvent {
}
}
#[must_use]
pub fn dedupe_superseded_commit_events(events: &[LaneEvent]) -> Vec<LaneEvent> {
let mut keep = vec![true; events.len()];
let mut latest_by_key = std::collections::BTreeMap::<String, usize>::new();
for (index, event) in events.iter().enumerate() {
if event.event != LaneEventName::CommitCreated {
continue;
}
let Some(data) = event.data.as_ref() else {
continue;
};
let key = data
.get("canonicalCommit")
.or_else(|| data.get("commit"))
.and_then(serde_json::Value::as_str)
.map(str::to_string);
let superseded = data
.get("supersededBy")
.and_then(serde_json::Value::as_str)
.is_some();
if superseded {
keep[index] = false;
continue;
}
if let Some(key) = key {
if let Some(previous) = latest_by_key.insert(key, index) {
keep[previous] = false;
}
}
}
events
.iter()
.cloned()
.zip(keep)
.filter_map(|(event, retain)| retain.then_some(event))
.collect()
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::{
LaneEvent, LaneEventBlocker, LaneEventName, LaneEventStatus, LaneFailureClass,
dedupe_superseded_commit_events, LaneCommitProvenance, LaneEvent, LaneEventBlocker,
LaneEventName, LaneEventStatus, LaneFailureClass,
};
#[test]
@ -170,10 +260,7 @@ mod tests {
let cases = [
(LaneEventName::Started, "lane.started"),
(LaneEventName::Ready, "lane.ready"),
(
LaneEventName::PromptMisdelivery,
"lane.prompt_misdelivery",
),
(LaneEventName::PromptMisdelivery, "lane.prompt_misdelivery"),
(LaneEventName::Blocked, "lane.blocked"),
(LaneEventName::Red, "lane.red"),
(LaneEventName::Green, "lane.green"),
@ -193,7 +280,10 @@ mod tests {
];
for (event, expected) in cases {
assert_eq!(serde_json::to_value(event).expect("serialize event"), json!(expected));
assert_eq!(
serde_json::to_value(event).expect("serialize event"),
json!(expected)
);
}
}
@ -238,4 +328,56 @@ mod tests {
assert_eq!(failed.status, LaneEventStatus::Failed);
assert_eq!(failed.detail.as_deref(), Some("broken server"));
}
#[test]
fn commit_events_can_carry_worktree_and_supersession_metadata() {
let event = LaneEvent::commit_created(
"2026-04-04T00:00:00Z",
Some("commit created".to_string()),
LaneCommitProvenance {
commit: "abc123".to_string(),
branch: "feature/provenance".to_string(),
worktree: Some("wt-a".to_string()),
canonical_commit: Some("abc123".to_string()),
superseded_by: None,
lineage: vec!["abc123".to_string()],
},
);
let event_json = serde_json::to_value(&event).expect("lane event should serialize");
assert_eq!(event_json["event"], "lane.commit.created");
assert_eq!(event_json["data"]["branch"], "feature/provenance");
assert_eq!(event_json["data"]["worktree"], "wt-a");
}
#[test]
fn dedupes_superseded_commit_events_by_canonical_commit() {
let retained = dedupe_superseded_commit_events(&[
LaneEvent::commit_created(
"2026-04-04T00:00:00Z",
Some("old".to_string()),
LaneCommitProvenance {
commit: "old123".to_string(),
branch: "feature/provenance".to_string(),
worktree: Some("wt-a".to_string()),
canonical_commit: Some("canon123".to_string()),
superseded_by: Some("new123".to_string()),
lineage: vec!["old123".to_string(), "new123".to_string()],
},
),
LaneEvent::commit_created(
"2026-04-04T00:00:01Z",
Some("new".to_string()),
LaneCommitProvenance {
commit: "new123".to_string(),
branch: "feature/provenance".to_string(),
worktree: Some("wt-b".to_string()),
canonical_commit: Some("canon123".to_string()),
superseded_by: None,
lineage: vec!["old123".to_string(), "new123".to_string()],
},
),
]);
assert_eq!(retained.len(), 1);
assert_eq!(retained[0].detail.as_deref(), Some("new"));
}
}

30
rust/crates/runtime/src/lib.rs
View File

@ -7,10 +7,13 @@
mod bash;
pub mod bash_validation;
mod bootstrap;
pub mod branch_lock;
mod compact;
mod config;
pub mod config_validate;
mod conversation;
mod file_ops;
mod git_context;
pub mod green_contract;
mod hooks;
mod json;
@ -19,6 +22,7 @@ pub mod lsp_client;
mod mcp;
mod mcp_client;
pub mod mcp_lifecycle_hardened;
pub mod mcp_server;
mod mcp_stdio;
pub mod mcp_tool_bridge;
mod oauth;
@ -32,28 +36,36 @@ mod remote;
pub mod sandbox;
mod session;
pub mod session_control;
pub use session_control::SessionStore;
mod sse;
pub mod stale_base;
pub mod stale_branch;
pub mod summary_compression;
pub mod task_packet;
pub mod task_registry;
pub mod team_cron_registry;
pub mod trust_resolver;
#[cfg(test)]
mod trust_resolver;
mod usage;
pub mod worker_boot;
pub use bash::{execute_bash, BashCommandInput, BashCommandOutput};
pub use bootstrap::{BootstrapPhase, BootstrapPlan};
pub use branch_lock::{detect_branch_lock_collisions, BranchLockCollision, BranchLockIntent};
pub use compact::{
compact_session, estimate_session_tokens, format_compact_summary,
get_compact_continuation_message, should_compact, CompactionConfig, CompactionResult,
};
pub use config_validate::{
check_unsupported_format, format_diagnostics, validate_config_file, ConfigDiagnostic,
DiagnosticKind, ValidationResult,
};
pub use config::{
ConfigEntry, ConfigError, ConfigLoader, ConfigSource, McpConfigCollection,
McpManagedProxyServerConfig, McpOAuthConfig, McpRemoteServerConfig, McpSdkServerConfig,
McpServerConfig, McpStdioServerConfig, McpTransport, McpWebSocketServerConfig, OAuthConfig,
ResolvedPermissionMode, RuntimeConfig, RuntimeFeatureConfig, RuntimeHookConfig,
RuntimePermissionRuleConfig, RuntimePluginConfig, ScopedMcpServerConfig,
ProviderFallbackConfig, ResolvedPermissionMode, RuntimeConfig, RuntimeFeatureConfig,
RuntimeHookConfig, RuntimePermissionRuleConfig, RuntimePluginConfig, ScopedMcpServerConfig,
CLAW_SETTINGS_SCHEMA_NAME,
};
pub use conversation::{
@ -61,6 +73,7 @@ pub use conversation::{
ConversationRuntime, PromptCacheEvent, RuntimeError, StaticToolExecutor, ToolError,
ToolExecutor, TurnSummary,
};
pub use git_context::{GitCommitEntry, GitContext};
pub use file_ops::{
edit_file, glob_search, grep_search, read_file, write_file, EditFileOutput, GlobSearchOutput,
GrepSearchInput, GrepSearchOutput, ReadFileOutput, StructuredPatchHunk, TextFilePayload,
@ -70,7 +83,8 @@ pub use hooks::{
HookAbortSignal, HookEvent, HookProgressEvent, HookProgressReporter, HookRunResult, HookRunner,
};
pub use lane_events::{
LaneEvent, LaneEventBlocker, LaneEventName, LaneEventStatus, LaneFailureClass,
dedupe_superseded_commit_events, LaneCommitProvenance, LaneEvent, LaneEventBlocker,
LaneEventName, LaneEventStatus, LaneFailureClass,
};
pub use mcp::{
mcp_server_signature, mcp_tool_name, mcp_tool_prefix, normalize_name_for_mcp,
@ -84,6 +98,7 @@ pub use mcp_lifecycle_hardened::{
McpDegradedReport, McpErrorSurface, McpFailedServer, McpLifecyclePhase, McpLifecycleState,
McpLifecycleValidator, McpPhaseResult,
};
pub use mcp_server::{McpServer, McpServerSpec, ToolCallHandler, MCP_SERVER_PROTOCOL_VERSION};
pub use mcp_stdio::{
spawn_mcp_stdio_process, JsonRpcError, JsonRpcId, JsonRpcRequest, JsonRpcResponse,
ManagedMcpTool, McpDiscoveryFailure, McpInitializeClientInfo, McpInitializeParams,
@ -133,14 +148,19 @@ pub use sandbox::{
};
pub use session::{
ContentBlock, ConversationMessage, MessageRole, Session, SessionCompaction, SessionError,
SessionFork,
SessionFork, SessionPromptEntry,
};
pub use sse::{IncrementalSseParser, SseEvent};
pub use stale_base::{
check_base_commit, format_stale_base_warning, read_claw_base_file, resolve_expected_base,
BaseCommitSource, BaseCommitState,
};
pub use stale_branch::{
apply_policy, check_freshness, BranchFreshness, StaleBranchAction, StaleBranchEvent,
StaleBranchPolicy,
};
pub use task_packet::{validate_packet, TaskPacket, TaskPacketValidationError, ValidatedPacket};
#[cfg(test)]
pub use trust_resolver::{TrustConfig, TrustDecision, TrustEvent, TrustPolicy, TrustResolver};
pub use usage::{
format_usd, pricing_for_model, ModelPricing, TokenUsage, UsageCostEstimate, UsageTracker,

1
rust/crates/runtime/src/lsp_client.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::should_implement_trait, clippy::must_use_candidate)]
//! LSP (Language Server Protocol) client registry for tool dispatch.
use std::collections::HashMap;

6
rust/crates/runtime/src/mcp_lifecycle_hardened.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::unnested_or_patterns, clippy::map_unwrap_or)]
use std::collections::{BTreeMap, BTreeSet};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
@ -599,7 +600,10 @@ mod tests {
));
match result {
McpPhaseResult::Failure { phase: failed_phase, error } => {
McpPhaseResult::Failure {
phase: failed_phase,
error,
} => {
assert_eq!(failed_phase, phase);
assert_eq!(error.phase, phase);
assert_eq!(

442
rust/crates/runtime/src/mcp_server.rs Normal file
View File

@ -0,0 +1,442 @@
//! Minimal Model Context Protocol (MCP) server.
//!
//! Implements a newline-safe, LSP-framed JSON-RPC server over stdio that
//! answers `initialize`, `tools/list`, and `tools/call` requests. The framing
//! matches the client transport implemented in [`crate::mcp_stdio`] so this
//! server can be driven by either an external MCP client (e.g. Claude
//! Desktop) or `claw`'s own [`McpServerManager`](crate::McpServerManager).
//!
//! The server is intentionally small: it exposes a list of pre-built
//! [`McpTool`] descriptors and delegates `tools/call` to a caller-supplied
//! handler. Tool execution itself lives in the `tools` crate; this module is
//! purely the transport + dispatch loop.
//!
//! [`McpTool`]: crate::mcp_stdio::McpTool
use std::io;
use serde_json::{json, Value as JsonValue};
use tokio::io::{
stdin, stdout, AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader, Stdin, Stdout,
};
use crate::mcp_stdio::{
JsonRpcError, JsonRpcId, JsonRpcRequest, JsonRpcResponse, McpInitializeResult,
McpInitializeServerInfo, McpListToolsResult, McpTool, McpToolCallContent, McpToolCallParams,
McpToolCallResult,
};
/// Protocol version the server advertises during `initialize`.
///
/// Matches the version used by the built-in client in
/// [`crate::mcp_stdio`], so the two stay in lockstep.
pub const MCP_SERVER_PROTOCOL_VERSION: &str = "2025-03-26";
/// Synchronous handler invoked for every `tools/call` request.
///
/// Returning `Ok(text)` yields a single `text` content block and
/// `isError: false`. Returning `Err(message)` yields a `text` block with the
/// error and `isError: true`, mirroring the error-surfacing convention used
/// elsewhere in claw.
pub type ToolCallHandler =
Box<dyn Fn(&str, &JsonValue) -> Result<String, String> + Send + Sync + 'static>;
/// Configuration for an [`McpServer`] instance.
///
/// Named `McpServerSpec` rather than `McpServerConfig` to avoid colliding
/// with the existing client-side [`crate::config::McpServerConfig`] that
/// describes *remote* MCP servers the runtime connects to.
pub struct McpServerSpec {
/// Name advertised in the `serverInfo` field of the `initialize` response.
pub server_name: String,
/// Version advertised in the `serverInfo` field of the `initialize`
/// response.
pub server_version: String,
/// Tool descriptors returned for `tools/list`.
pub tools: Vec<McpTool>,
/// Handler invoked for `tools/call`.
pub tool_handler: ToolCallHandler,
}
/// Minimal MCP stdio server.
///
/// The server runs a blocking read/dispatch/write loop over the current
/// process's stdin/stdout, terminating cleanly when the peer closes the
/// stream.
pub struct McpServer {
spec: McpServerSpec,
stdin: BufReader<Stdin>,
stdout: Stdout,
}
impl McpServer {
#[must_use]
pub fn new(spec: McpServerSpec) -> Self {
Self {
spec,
stdin: BufReader::new(stdin()),
stdout: stdout(),
}
}
/// Runs the server until the client closes stdin.
///
/// Returns `Ok(())` on clean EOF; any other I/O error is propagated so
/// callers can log and exit non-zero.
pub async fn run(&mut self) -> io::Result<()> {
loop {
let Some(payload) = read_frame(&mut self.stdin).await? else {
return Ok(());
};
// Requests and notifications share a wire format; the absence of
// `id` distinguishes notifications, which must never receive a
// response.
let message: JsonValue = match serde_json::from_slice(&payload) {
Ok(value) => value,
Err(error) => {
// Parse error with null id per JSON-RPC 2.0 §4.2.
let response = JsonRpcResponse::<JsonValue> {
jsonrpc: "2.0".to_string(),
id: JsonRpcId::Null,
result: None,
error: Some(JsonRpcError {
code: -32700,
message: format!("parse error: {error}"),
data: None,
}),
};
write_response(&mut self.stdout, &response).await?;
continue;
}
};
if message.get("id").is_none() {
// Notification: dispatch for side effects only (e.g. log),
// but send no reply.
continue;
}
let request: JsonRpcRequest<JsonValue> = match serde_json::from_value(message) {
Ok(request) => request,
Err(error) => {
let response = JsonRpcResponse::<JsonValue> {
jsonrpc: "2.0".to_string(),
id: JsonRpcId::Null,
result: None,
error: Some(JsonRpcError {
code: -32600,
message: format!("invalid request: {error}"),
data: None,
}),
};
write_response(&mut self.stdout, &response).await?;
continue;
}
};
let response = self.dispatch(request);
write_response(&mut self.stdout, &response).await?;
}
}
fn dispatch(&self, request: JsonRpcRequest<JsonValue>) -> JsonRpcResponse<JsonValue> {
let id = request.id.clone();
match request.method.as_str() {
"initialize" => self.handle_initialize(id),
"tools/list" => self.handle_tools_list(id),
"tools/call" => self.handle_tools_call(id, request.params),
other => JsonRpcResponse {
jsonrpc: "2.0".to_string(),
id,
result: None,
error: Some(JsonRpcError {
code: -32601,
message: format!("method not found: {other}"),
data: None,
}),
},
}
}
fn handle_initialize(&self, id: JsonRpcId) -> JsonRpcResponse<JsonValue> {
let result = McpInitializeResult {
protocol_version: MCP_SERVER_PROTOCOL_VERSION.to_string(),
capabilities: json!({ "tools": {} }),
server_info: McpInitializeServerInfo {
name: self.spec.server_name.clone(),
version: self.spec.server_version.clone(),
},
};
JsonRpcResponse {
jsonrpc: "2.0".to_string(),
id,
result: serde_json::to_value(result).ok(),
error: None,
}
}
fn handle_tools_list(&self, id: JsonRpcId) -> JsonRpcResponse<JsonValue> {
let result = McpListToolsResult {
tools: self.spec.tools.clone(),
next_cursor: None,
};
JsonRpcResponse {
jsonrpc: "2.0".to_string(),
id,
result: serde_json::to_value(result).ok(),
error: None,
}
}
fn handle_tools_call(
&self,
id: JsonRpcId,
params: Option<JsonValue>,
) -> JsonRpcResponse<JsonValue> {
let Some(params) = params else {
return invalid_params_response(id, "missing params for tools/call");
};
let call: McpToolCallParams = match serde_json::from_value(params) {
Ok(value) => value,
Err(error) => {
return invalid_params_response(id, &format!("invalid tools/call params: {error}"));
}
};
let arguments = call.arguments.unwrap_or_else(|| json!({}));
let tool_result = (self.spec.tool_handler)(&call.name, &arguments);
let (text, is_error) = match tool_result {
Ok(text) => (text, false),
Err(message) => (message, true),
};
let mut data = std::collections::BTreeMap::new();
data.insert("text".to_string(), JsonValue::String(text));
let call_result = McpToolCallResult {
content: vec![McpToolCallContent {
kind: "text".to_string(),
data,
}],
structured_content: None,
is_error: Some(is_error),
meta: None,
};
JsonRpcResponse {
jsonrpc: "2.0".to_string(),
id,
result: serde_json::to_value(call_result).ok(),
error: None,
}
}
}
fn invalid_params_response(id: JsonRpcId, message: &str) -> JsonRpcResponse<JsonValue> {
JsonRpcResponse {
jsonrpc: "2.0".to_string(),
id,
result: None,
error: Some(JsonRpcError {
code: -32602,
message: message.to_string(),
data: None,
}),
}
}
/// Reads a single LSP-framed JSON-RPC payload from `reader`.
///
/// Returns `Ok(None)` on clean EOF before any header bytes have been read,
/// matching how [`crate::mcp_stdio::McpStdioProcess`] treats stream closure.
async fn read_frame(reader: &mut BufReader<Stdin>) -> io::Result<Option<Vec<u8>>> {
let mut content_length: Option<usize> = None;
let mut first_header = true;
loop {
let mut line = String::new();
let bytes_read = reader.read_line(&mut line).await?;
if bytes_read == 0 {
if first_header {
return Ok(None);
}
return Err(io::Error::new(
io::ErrorKind::UnexpectedEof,
"MCP stdio stream closed while reading headers",
));
}
first_header = false;
if line == "\r\n" || line == "\n" {
break;
}
let header = line.trim_end_matches(['\r', '\n']);
if let Some((name, value)) = header.split_once(':') {
if name.trim().eq_ignore_ascii_case("Content-Length") {
let parsed = value
.trim()
.parse::<usize>()
.map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
content_length = Some(parsed);
}
}
}
let content_length = content_length.ok_or_else(|| {
io::Error::new(io::ErrorKind::InvalidData, "missing Content-Length header")
})?;
let mut payload = vec![0_u8; content_length];
reader.read_exact(&mut payload).await?;
Ok(Some(payload))
}
async fn write_response(
stdout: &mut Stdout,
response: &JsonRpcResponse<JsonValue>,
) -> io::Result<()> {
let body = serde_json::to_vec(response)
.map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
let header = format!("Content-Length: {}\r\n\r\n", body.len());
stdout.write_all(header.as_bytes()).await?;
stdout.write_all(&body).await?;
stdout.flush().await
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn dispatch_initialize_returns_server_info() {
let server = McpServer {
spec: McpServerSpec {
server_name: "test".to_string(),
server_version: "9.9.9".to_string(),
tools: Vec::new(),
tool_handler: Box::new(|_, _| Ok(String::new())),
},
stdin: BufReader::new(stdin()),
stdout: stdout(),
};
let request = JsonRpcRequest::<JsonValue> {
jsonrpc: "2.0".to_string(),
id: JsonRpcId::Number(1),
method: "initialize".to_string(),
params: None,
};
let response = server.dispatch(request);
assert_eq!(response.id, JsonRpcId::Number(1));
assert!(response.error.is_none());
let result = response.result.expect("initialize result");
assert_eq!(result["protocolVersion"], MCP_SERVER_PROTOCOL_VERSION);
assert_eq!(result["serverInfo"]["name"], "test");
assert_eq!(result["serverInfo"]["version"], "9.9.9");
}
#[test]
fn dispatch_tools_list_returns_registered_tools() {
let tool = McpTool {
name: "echo".to_string(),
description: Some("Echo".to_string()),
input_schema: Some(json!({"type": "object"})),
annotations: None,
meta: None,
};
let server = McpServer {
spec: McpServerSpec {
server_name: "test".to_string(),
server_version: "0.0.0".to_string(),
tools: vec![tool.clone()],
tool_handler: Box::new(|_, _| Ok(String::new())),
},
stdin: BufReader::new(stdin()),
stdout: stdout(),
};
let request = JsonRpcRequest::<JsonValue> {
jsonrpc: "2.0".to_string(),
id: JsonRpcId::Number(2),
method: "tools/list".to_string(),
params: None,
};
let response = server.dispatch(request);
assert!(response.error.is_none());
let result = response.result.expect("tools/list result");
assert_eq!(result["tools"][0]["name"], "echo");
}
#[test]
fn dispatch_tools_call_wraps_handler_output() {
let server = McpServer {
spec: McpServerSpec {
server_name: "test".to_string(),
server_version: "0.0.0".to_string(),
tools: Vec::new(),
tool_handler: Box::new(|name, args| {
Ok(format!("called {name} with {args}"))
}),
},
stdin: BufReader::new(stdin()),
stdout: stdout(),
};
let request = JsonRpcRequest::<JsonValue> {
jsonrpc: "2.0".to_string(),
id: JsonRpcId::Number(3),
method: "tools/call".to_string(),
params: Some(json!({
"name": "echo",
"arguments": {"text": "hi"}
})),
};
let response = server.dispatch(request);
assert!(response.error.is_none());
let result = response.result.expect("tools/call result");
assert_eq!(result["isError"], false);
assert_eq!(result["content"][0]["type"], "text");
assert!(result["content"][0]["text"]
.as_str()
.unwrap()
.starts_with("called echo"));
}
#[test]
fn dispatch_tools_call_surfaces_handler_error() {
let server = McpServer {
spec: McpServerSpec {
server_name: "test".to_string(),
server_version: "0.0.0".to_string(),
tools: Vec::new(),
tool_handler: Box::new(|_, _| Err("boom".to_string())),
},
stdin: BufReader::new(stdin()),
stdout: stdout(),
};
let request = JsonRpcRequest::<JsonValue> {
jsonrpc: "2.0".to_string(),
id: JsonRpcId::Number(4),
method: "tools/call".to_string(),
params: Some(json!({"name": "broken"})),
};
let response = server.dispatch(request);
let result = response.result.expect("tools/call result");
assert_eq!(result["isError"], true);
assert_eq!(result["content"][0]["text"], "boom");
}
#[test]
fn dispatch_unknown_method_returns_method_not_found() {
let server = McpServer {
spec: McpServerSpec {
server_name: "test".to_string(),
server_version: "0.0.0".to_string(),
tools: Vec::new(),
tool_handler: Box::new(|_, _| Ok(String::new())),
},
stdin: BufReader::new(stdin()),
stdout: stdout(),
};
let request = JsonRpcRequest::<JsonValue> {
jsonrpc: "2.0".to_string(),
id: JsonRpcId::Number(5),
method: "nonsense".to_string(),
params: None,
};
let response = server.dispatch(request);
let error = response.error.expect("error payload");
assert_eq!(error.code, -32601);
}
}

64
rust/crates/runtime/src/mcp_stdio.rs
View File

@ -360,8 +360,10 @@ impl McpServerManagerError {
}
fn recoverable(&self) -> bool {
!matches!(self.lifecycle_phase(), McpLifecyclePhase::InitializeHandshake)
&& matches!(self, Self::Transport { .. } | Self::Timeout { .. })
!matches!(
self.lifecycle_phase(),
McpLifecyclePhase::InitializeHandshake
) && matches!(self, Self::Transport { .. } | Self::Timeout { .. })
}
fn discovery_failure(&self, server_name: &str) -> McpDiscoveryFailure {
@ -417,10 +419,9 @@ impl McpServerManagerError {
("method".to_string(), (*method).to_string()),
("timeout_ms".to_string(), timeout_ms.to_string()),
]),
Self::UnknownTool { qualified_name } => BTreeMap::from([(
"qualified_tool".to_string(),
qualified_name.clone(),
)]),
Self::UnknownTool { qualified_name } => {
BTreeMap::from([("qualified_tool".to_string(), qualified_name.clone())])
}
Self::UnknownServer { server_name } => {
BTreeMap::from([("server".to_string(), server_name.clone())])
}
@ -1425,11 +1426,10 @@ mod tests {
use crate::mcp_client::McpClientBootstrap;
use super::{
spawn_mcp_stdio_process, JsonRpcId, JsonRpcRequest, JsonRpcResponse,
McpInitializeClientInfo, McpInitializeParams, McpInitializeResult, McpInitializeServerInfo,
McpListToolsResult, McpReadResourceParams, McpReadResourceResult, McpServerManager,
McpServerManagerError, McpStdioProcess, McpTool, McpToolCallParams,
unsupported_server_failed_server,
spawn_mcp_stdio_process, unsupported_server_failed_server, JsonRpcId, JsonRpcRequest,
JsonRpcResponse, McpInitializeClientInfo, McpInitializeParams, McpInitializeResult,
McpInitializeServerInfo, McpListToolsResult, McpReadResourceParams, McpReadResourceResult,
McpServerManager, McpServerManagerError, McpStdioProcess, McpTool, McpToolCallParams,
};
use crate::McpLifecyclePhase;
@ -2652,8 +2652,37 @@ mod tests {
});
}
fn write_initialize_disconnect_script() -> PathBuf {
let root = temp_dir();
fs::create_dir_all(&root).expect("temp dir");
let script_path = root.join("initialize-disconnect.py");
let script = [
"#!/usr/bin/env python3",
"import sys",
"header = b''",
r"while not header.endswith(b'\r\n\r\n'):",
" chunk = sys.stdin.buffer.read(1)",
" if not chunk:",
" raise SystemExit(1)",
" header += chunk",
"length = 0",
r"for line in header.decode().split('\r\n'):",
r" if line.lower().startswith('content-length:'):",
r" length = int(line.split(':', 1)[1].strip())",
"if length:",
" sys.stdin.buffer.read(length)",
"raise SystemExit(0)",
"",
]
.join("\n");
fs::write(&script_path, script).expect("write script");
let mut permissions = fs::metadata(&script_path).expect("metadata").permissions();
permissions.set_mode(0o755);
fs::set_permissions(&script_path, permissions).expect("chmod");
script_path
}
#[test]
#[ignore = "flaky: intermittent timing issues in CI, see ROADMAP P2.15"]
fn manager_discovery_report_keeps_healthy_servers_when_one_server_fails() {
let runtime = Builder::new_current_thread()
.enable_all()
@ -2663,6 +2692,7 @@ mod tests {
let script_path = write_manager_mcp_server_script();
let root = script_path.parent().expect("script parent");
let alpha_log = root.join("alpha.log");
let broken_script_path = write_initialize_disconnect_script();
let servers = BTreeMap::from([
(
"alpha".to_string(),
@ -2673,8 +2703,8 @@ mod tests {
ScopedMcpServerConfig {
scope: ConfigSource::Local,
config: McpServerConfig::Stdio(McpStdioServerConfig {
command: "python3".to_string(),
args: vec!["-c".to_string(), "import sys; sys.exit(0)".to_string()],
command: broken_script_path.display().to_string(),
args: Vec::new(),
env: BTreeMap::new(),
tool_call_timeout_ms: None,
}),
@ -2698,7 +2728,10 @@ mod tests {
);
assert!(!report.failed_servers[0].recoverable);
assert_eq!(
report.failed_servers[0].context.get("method").map(String::as_str),
report.failed_servers[0]
.context
.get("method")
.map(String::as_str),
Some("initialize")
);
assert!(report.failed_servers[0].error.contains("initialize"));
@ -2734,6 +2767,7 @@ mod tests {
manager.shutdown().await.expect("shutdown");
cleanup_script(&script_path);
cleanup_script(&broken_script_path);
});
}

8
rust/crates/runtime/src/mcp_tool_bridge.rs
View File

@ -1,3 +1,11 @@
#![allow(
clippy::await_holding_lock,
clippy::doc_markdown,
clippy::match_same_arms,
clippy::must_use_candidate,
clippy::uninlined_format_args,
clippy::unnested_or_patterns
)]
//! Bridge between MCP tool surface (ListMcpResources, ReadMcpResource, McpAuth, MCP)
//! and the existing McpServerManager runtime.
//!

5
rust/crates/runtime/src/permission_enforcer.rs
View File

@ -1,3 +1,8 @@
#![allow(
clippy::match_wildcard_for_single_variants,
clippy::must_use_candidate,
clippy::uninlined_format_args
)]
//! Permission enforcement layer that gates tool execution based on the
//! active `PermissionPolicy`.

1
rust/crates/runtime/src/plugin_lifecycle.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::redundant_closure_for_method_calls)]
use std::time::{SystemTime, UNIX_EPOCH};
use serde::{Deserialize, Serialize};

119
rust/crates/runtime/src/prompt.rs
View File

@ -4,6 +4,7 @@ use std::path::{Path, PathBuf};
use std::process::Command;
use crate::config::{ConfigError, ConfigLoader, RuntimeConfig};
use crate::git_context::GitContext;
/// Errors raised while assembling the final system prompt.
#[derive(Debug)]
@ -56,6 +57,7 @@ pub struct ProjectContext {
pub current_date: String,
pub git_status: Option<String>,
pub git_diff: Option<String>,
pub git_context: Option<GitContext>,
pub instruction_files: Vec<ContextFile>,
}
@ -71,6 +73,7 @@ impl ProjectContext {
current_date: current_date.into(),
git_status: None,
git_diff: None,
git_context: None,
instruction_files,
})
}
@ -82,6 +85,7 @@ impl ProjectContext {
let mut context = Self::discover(cwd, current_date)?;
context.git_status = read_git_status(&context.cwd);
context.git_diff = read_git_diff(&context.cwd);
context.git_context = GitContext::detect(&context.cwd);
Ok(context)
}
}
@ -249,6 +253,31 @@ fn read_git_status(cwd: &Path) -> Option<String> {
}
}
fn read_git_recent_commits(cwd: &Path) -> Option<String> {
let output = Command::new("git")
.args([
"--no-optional-locks",
"log",
"--oneline",
"--no-decorate",
"-n",
"5",
])
.current_dir(cwd)
.output()
.ok()?;
if !output.status.success() {
return None;
}
let stdout = String::from_utf8(output.stdout).ok()?;
let trimmed = stdout.trim();
if trimmed.is_empty() {
None
} else {
Some(trimmed.to_string())
}
}
fn read_git_diff(cwd: &Path) -> Option<String> {
let mut sections = Vec::new();
@ -299,11 +328,27 @@ fn render_project_context(project_context: &ProjectContext) -> String {
lines.push("Git status snapshot:".to_string());
lines.push(status.clone());
}
if let Some(ref gc) = project_context.git_context {
if !gc.recent_commits.is_empty() {
lines.push(String::new());
lines.push("Recent commits (last 5):".to_string());
for c in &gc.recent_commits {
lines.push(format!(" {} {}", c.hash, c.subject));
}
}
}
if let Some(diff) = &project_context.git_diff {
lines.push(String::new());
lines.push("Git diff snapshot:".to_string());
lines.push(diff.clone());
}
if let Some(git_context) = &project_context.git_context {
let rendered = git_context.render();
if !rendered.is_empty() {
lines.push(String::new());
lines.push(rendered);
}
}
lines.join("\n")
}
@ -639,6 +684,80 @@ mod tests {
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn discover_with_git_includes_recent_commits_and_renders_them() {
// given: a git repo with three commits and a current branch
let _guard = env_lock();
ensure_valid_cwd();
let root = temp_dir();
fs::create_dir_all(&root).expect("root dir");
std::process::Command::new("git")
.args(["init", "--quiet", "-b", "main"])
.current_dir(&root)
.status()
.expect("git init should run");
std::process::Command::new("git")
.args(["config", "user.email", "tests@example.com"])
.current_dir(&root)
.status()
.expect("git config email should run");
std::process::Command::new("git")
.args(["config", "user.name", "Runtime Prompt Tests"])
.current_dir(&root)
.status()
.expect("git config name should run");
for (file, message) in [
("a.txt", "first commit"),
("b.txt", "second commit"),
("c.txt", "third commit"),
] {
fs::write(root.join(file), "x\n").expect("write commit file");
std::process::Command::new("git")
.args(["add", file])
.current_dir(&root)
.status()
.expect("git add should run");
std::process::Command::new("git")
.args(["commit", "-m", message, "--quiet"])
.current_dir(&root)
.status()
.expect("git commit should run");
}
fs::write(root.join("d.txt"), "staged\n").expect("write staged file");
std::process::Command::new("git")
.args(["add", "d.txt"])
.current_dir(&root)
.status()
.expect("git add staged should run");
// when: discovering project context with git auto-include
let context =
ProjectContext::discover_with_git(&root, "2026-03-31").expect("context should load");
let rendered = SystemPromptBuilder::new()
.with_os("linux", "6.8")
.with_project_context(context.clone())
.render();
// then: branch, recent commits and staged files are present in context
let gc = context.git_context.as_ref().expect("git context should be present");
let commits: String = gc.recent_commits.iter().map(|c| c.subject.clone()).collect::<Vec<_>>().join("\n");
assert!(commits.contains("first commit"));
assert!(commits.contains("second commit"));
assert!(commits.contains("third commit"));
assert_eq!(gc.recent_commits.len(), 3);
let status = context.git_status.as_deref().expect("status snapshot");
assert!(status.contains("## main"));
assert!(status.contains("A d.txt"));
assert!(rendered.contains("Recent commits (last 5):"));
assert!(rendered.contains("first commit"));
assert!(rendered.contains("Git status snapshot:"));
assert!(rendered.contains("## main"));
fs::remove_dir_all(root).expect("cleanup temp dir");
}
#[test]
fn discover_with_git_includes_diff_snapshot_for_tracked_changes() {
let _guard = env_lock();

1
rust/crates/runtime/src/recovery_recipes.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::cast_possible_truncation, clippy::uninlined_format_args)]
//! Recovery recipes for common failure scenarios.
//!
//! Encodes known automatic recoveries for the six failure scenarios

199
rust/crates/runtime/src/session.rs
View File

@ -65,12 +65,26 @@ pub struct SessionFork {
pub branch_name: Option<String>,
}
/// A single user prompt recorded with a timestamp for history tracking.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionPromptEntry {
pub timestamp_ms: u64,
pub text: String,
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct SessionPersistence {
path: PathBuf,
}
/// Persisted conversational state for the runtime and CLI session manager.
///
/// `workspace_root` binds the session to the worktree it was created in. The
/// global session store under `~/.local/share/opencode` is shared across every
/// `opencode serve` instance, so without an explicit workspace root parallel
/// lanes can race and report success while writes land in the wrong CWD. See
/// ROADMAP.md item 41 (Phantom completions root cause) for the full
/// background.
#[derive(Debug, Clone)]
pub struct Session {
pub version: u32,
@ -80,6 +94,8 @@ pub struct Session {
pub messages: Vec<ConversationMessage>,
pub compaction: Option<SessionCompaction>,
pub fork: Option<SessionFork>,
pub workspace_root: Option<PathBuf>,
pub prompt_history: Vec<SessionPromptEntry>,
persistence: Option<SessionPersistence>,
}
@ -92,6 +108,8 @@ impl PartialEq for Session {
&& self.messages == other.messages
&& self.compaction == other.compaction
&& self.fork == other.fork
&& self.workspace_root == other.workspace_root
&& self.prompt_history == other.prompt_history
}
}
@ -141,6 +159,8 @@ impl Session {
messages: Vec::new(),
compaction: None,
fork: None,
workspace_root: None,
prompt_history: Vec::new(),
persistence: None,
}
}
@ -151,6 +171,22 @@ impl Session {
self
}
/// Bind this session to the workspace root it was created in.
///
/// This is the per-worktree counterpart to the global session store and
/// lets downstream tooling reject writes that drift to the wrong CWD when
/// multiple `opencode serve` instances share `~/.local/share/opencode`.
#[must_use]
pub fn with_workspace_root(mut self, workspace_root: impl Into<PathBuf>) -> Self {
self.workspace_root = Some(workspace_root.into());
self
}
#[must_use]
pub fn workspace_root(&self) -> Option<&Path> {
self.workspace_root.as_deref()
}
#[must_use]
pub fn persistence_path(&self) -> Option<&Path> {
self.persistence.as_ref().map(|value| value.path.as_path())
@ -225,6 +261,8 @@ impl Session {
parent_session_id: self.session_id.clone(),
branch_name: normalize_optional_string(branch_name),
}),
workspace_root: self.workspace_root.clone(),
prompt_history: self.prompt_history.clone(),
persistence: None,
}
}
@ -262,6 +300,23 @@ impl Session {
if let Some(fork) = &self.fork {
object.insert("fork".to_string(), fork.to_json());
}
if let Some(workspace_root) = &self.workspace_root {
object.insert(
"workspace_root".to_string(),
JsonValue::String(workspace_root_to_string(workspace_root)?),
);
}
if !self.prompt_history.is_empty() {
object.insert(
"prompt_history".to_string(),
JsonValue::Array(
self.prompt_history
.iter()
.map(SessionPromptEntry::to_jsonl_record)
.collect(),
),
);
}
Ok(JsonValue::Object(object))
}
@ -302,6 +357,20 @@ impl Session {
.map(SessionCompaction::from_json)
.transpose()?;
let fork = object.get("fork").map(SessionFork::from_json).transpose()?;
let workspace_root = object
.get("workspace_root")
.and_then(JsonValue::as_str)
.map(PathBuf::from);
let prompt_history = object
.get("prompt_history")
.and_then(JsonValue::as_array)
.map(|entries| {
entries
.iter()
.filter_map(SessionPromptEntry::from_json_opt)
.collect()
})
.unwrap_or_default();
Ok(Self {
version,
session_id,
@ -310,6 +379,8 @@ impl Session {
messages,
compaction,
fork,
workspace_root,
prompt_history,
persistence: None,
})
}
@ -322,6 +393,8 @@ impl Session {
let mut messages = Vec::new();
let mut compaction = None;
let mut fork = None;
let mut workspace_root = None;
let mut prompt_history = Vec::new();
for (line_number, raw_line) in contents.lines().enumerate() {
let line = raw_line.trim();
@ -356,6 +429,10 @@ impl Session {
created_at_ms = Some(required_u64(object, "created_at_ms")?);
updated_at_ms = Some(required_u64(object, "updated_at_ms")?);
fork = object.get("fork").map(SessionFork::from_json).transpose()?;
workspace_root = object
.get("workspace_root")
.and_then(JsonValue::as_str)
.map(PathBuf::from);
}
"message" => {
let message_value = object.get("message").ok_or_else(|| {
@ -371,6 +448,13 @@ impl Session {
object.clone(),
))?);
}
"prompt_history" => {
if let Some(entry) =
SessionPromptEntry::from_json_opt(&JsonValue::Object(object.clone()))
{
prompt_history.push(entry);
}
}
other => {
return Err(SessionError::Format(format!(
"unsupported JSONL record type at line {}: {other}",
@ -389,15 +473,37 @@ impl Session {
messages,
compaction,
fork,
workspace_root,
prompt_history,
persistence: None,
})
}
/// Record a user prompt with the current wall-clock timestamp.
///
/// The entry is appended to the in-memory history and, when a persistence
/// path is configured, incrementally written to the JSONL session file.
pub fn push_prompt_entry(&mut self, text: impl Into<String>) -> Result<(), SessionError> {
let timestamp_ms = current_time_millis();
let entry = SessionPromptEntry {
timestamp_ms,
text: text.into(),
};
self.prompt_history.push(entry);
let entry_ref = self.prompt_history.last().expect("entry was just pushed");
self.append_persisted_prompt_entry(entry_ref)
}
fn render_jsonl_snapshot(&self) -> Result<String, SessionError> {
let mut lines = vec![self.meta_record()?.render()];
if let Some(compaction) = &self.compaction {
lines.push(compaction.to_jsonl_record()?.render());
}
lines.extend(
self.prompt_history
.iter()
.map(|entry| entry.to_jsonl_record().render()),
);
lines.extend(
self.messages
.iter()
@ -424,6 +530,25 @@ impl Session {
Ok(())
}
fn append_persisted_prompt_entry(
&self,
entry: &SessionPromptEntry,
) -> Result<(), SessionError> {
let Some(path) = self.persistence_path() else {
return Ok(());
};
let needs_bootstrap = !path.exists() || fs::metadata(path)?.len() == 0;
if needs_bootstrap {
self.save_to_path(path)?;
return Ok(());
}
let mut file = OpenOptions::new().append(true).open(path)?;
writeln!(file, "{}", entry.to_jsonl_record().render())?;
Ok(())
}
fn meta_record(&self) -> Result<JsonValue, SessionError> {
let mut object = BTreeMap::new();
object.insert(
@ -449,6 +574,12 @@ impl Session {
if let Some(fork) = &self.fork {
object.insert("fork".to_string(), fork.to_json());
}
if let Some(workspace_root) = &self.workspace_root {
object.insert(
"workspace_root".to_string(),
JsonValue::String(workspace_root_to_string(workspace_root)?),
);
}
Ok(JsonValue::Object(object))
}
@ -734,6 +865,33 @@ impl SessionFork {
}
}
impl SessionPromptEntry {
#[must_use]
pub fn to_jsonl_record(&self) -> JsonValue {
let mut object = BTreeMap::new();
object.insert(
"type".to_string(),
JsonValue::String("prompt_history".to_string()),
);
object.insert(
"timestamp_ms".to_string(),
JsonValue::Number(i64::try_from(self.timestamp_ms).unwrap_or(i64::MAX)),
);
object.insert("text".to_string(), JsonValue::String(self.text.clone()));
JsonValue::Object(object)
}
fn from_json_opt(value: &JsonValue) -> Option<Self> {
let object = value.as_object()?;
let timestamp_ms = object
.get("timestamp_ms")
.and_then(JsonValue::as_i64)
.and_then(|value| u64::try_from(value).ok())?;
let text = object.get("text").and_then(JsonValue::as_str)?.to_string();
Some(Self { timestamp_ms, text })
}
}
fn message_record(message: &ConversationMessage) -> JsonValue {
let mut object = BTreeMap::new();
object.insert("type".to_string(), JsonValue::String("message".to_string()));
@ -825,6 +983,15 @@ fn i64_from_usize(value: usize, key: &str) -> Result<i64, SessionError> {
.map_err(|_| SessionError::Format(format!("{key} out of range for JSON number")))
}
fn workspace_root_to_string(path: &Path) -> Result<String, SessionError> {
path.to_str().map(ToOwned::to_owned).ok_or_else(|| {
SessionError::Format(format!(
"workspace_root is not valid UTF-8: {}",
path.display()
))
})
}
fn normalize_optional_string(value: Option<String>) -> Option<String> {
value.and_then(|value| {
let trimmed = value.trim();
@ -1206,6 +1373,29 @@ mod tests {
assert!(error.to_string().contains("unsupported block type"));
}
#[test]
fn persists_workspace_root_round_trip_and_forks_inherit_it() {
// given
let path = temp_session_path("workspace-root");
let workspace_root = PathBuf::from("/tmp/b4-phantom-diag");
let mut session = Session::new().with_workspace_root(workspace_root.clone());
session
.push_user_text("write to the right cwd")
.expect("user message should append");
// when
session
.save_to_path(&path)
.expect("workspace-bound session should save");
let restored = Session::load_from_path(&path).expect("session should load");
let forked = restored.fork(Some("phantom-diag".to_string()));
fs::remove_file(&path).expect("temp file should be removable");
// then
assert_eq!(restored.workspace_root(), Some(workspace_root.as_path()));
assert_eq!(forked.workspace_root(), Some(workspace_root.as_path()));
}
fn temp_session_path(label: &str) -> PathBuf {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
@ -1244,3 +1434,12 @@ mod tests {
.collect()
}
}
/// Per-worktree session isolation: returns a session directory namespaced
/// by the workspace fingerprint of the given working directory.
/// This prevents parallel `opencode serve` instances from colliding.
pub fn workspace_sessions_dir(cwd: &std::path::Path) -> Result<std::path::PathBuf, SessionError> {
let store = crate::session_control::SessionStore::from_cwd(cwd)
.map_err(|e| SessionError::Io(std::io::Error::new(std::io::ErrorKind::Other, e.to_string())))?;
Ok(store.sessions_dir().to_path_buf())
}

420
rust/crates/runtime/src/session_control.rs
View File

@ -1,13 +1,257 @@
#![allow(dead_code)]
use std::env;
use std::fmt::{Display, Formatter};
use std::fs;
use std::path::{Path, PathBuf};
use std::time::UNIX_EPOCH;
use serde::{Deserialize, Serialize};
use crate::session::{Session, SessionError};
use crate::worker_boot::{Worker, WorkerReadySnapshot, WorkerRegistry, WorkerStatus};
/// Per-worktree session store that namespaces on-disk session files by
/// workspace fingerprint so that parallel `opencode serve` instances never
/// collide.
///
/// Create via [`SessionStore::from_cwd`] (derives the store path from the
/// server's working directory) or [`SessionStore::from_data_dir`] (honours an
/// explicit `--data-dir` flag). Both constructors produce a directory layout
/// of `<data_dir>/sessions/<workspace_hash>/` where `<workspace_hash>` is a
/// stable hex digest of the canonical workspace root.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionStore {
/// Resolved root of the session namespace, e.g.
/// `/home/user/project/.claw/sessions/a1b2c3d4e5f60718/`.
sessions_root: PathBuf,
/// The canonical workspace path that was fingerprinted.
workspace_root: PathBuf,
}
impl SessionStore {
/// Build a store from the server's current working directory.
///
/// The on-disk layout becomes `<cwd>/.claw/sessions/<workspace_hash>/`.
pub fn from_cwd(cwd: impl AsRef<Path>) -> Result<Self, SessionControlError> {
let cwd = cwd.as_ref();
let sessions_root = cwd
.join(".claw")
.join("sessions")
.join(workspace_fingerprint(cwd));
fs::create_dir_all(&sessions_root)?;
Ok(Self {
sessions_root,
workspace_root: cwd.to_path_buf(),
})
}
/// Build a store from an explicit `--data-dir` flag.
///
/// The on-disk layout becomes `<data_dir>/sessions/<workspace_hash>/`
/// where `<workspace_hash>` is derived from `workspace_root`.
pub fn from_data_dir(
data_dir: impl AsRef<Path>,
workspace_root: impl AsRef<Path>,
) -> Result<Self, SessionControlError> {
let workspace_root = workspace_root.as_ref();
let sessions_root = data_dir
.as_ref()
.join("sessions")
.join(workspace_fingerprint(workspace_root));
fs::create_dir_all(&sessions_root)?;
Ok(Self {
sessions_root,
workspace_root: workspace_root.to_path_buf(),
})
}
/// The fully resolved sessions directory for this namespace.
#[must_use]
pub fn sessions_dir(&self) -> &Path {
&self.sessions_root
}
/// The workspace root this store is bound to.
#[must_use]
pub fn workspace_root(&self) -> &Path {
&self.workspace_root
}
pub fn create_handle(&self, session_id: &str) -> SessionHandle {
let id = session_id.to_string();
let path = self
.sessions_root
.join(format!("{id}.{PRIMARY_SESSION_EXTENSION}"));
SessionHandle { id, path }
}
pub fn resolve_reference(&self, reference: &str) -> Result<SessionHandle, SessionControlError> {
if is_session_reference_alias(reference) {
let latest = self.latest_session()?;
return Ok(SessionHandle {
id: latest.id,
path: latest.path,
});
}
let direct = PathBuf::from(reference);
let candidate = if direct.is_absolute() {
direct.clone()
} else {
self.workspace_root.join(&direct)
};
let looks_like_path = direct.extension().is_some() || direct.components().count() > 1;
let path = if candidate.exists() {
candidate
} else if looks_like_path {
return Err(SessionControlError::Format(
format_missing_session_reference(reference),
));
} else {
self.resolve_managed_path(reference)?
};
Ok(SessionHandle {
id: session_id_from_path(&path).unwrap_or_else(|| reference.to_string()),
path,
})
}
pub fn resolve_managed_path(&self, session_id: &str) -> Result<PathBuf, SessionControlError> {
for extension in [PRIMARY_SESSION_EXTENSION, LEGACY_SESSION_EXTENSION] {
let path = self.sessions_root.join(format!("{session_id}.{extension}"));
if path.exists() {
return Ok(path);
}
}
Err(SessionControlError::Format(
format_missing_session_reference(session_id),
))
}
pub fn list_sessions(&self) -> Result<Vec<ManagedSessionSummary>, SessionControlError> {
let mut sessions = Vec::new();
let read_result = fs::read_dir(&self.sessions_root);
let entries = match read_result {
Ok(entries) => entries,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(sessions),
Err(err) => return Err(err.into()),
};
for entry in entries {
let entry = entry?;
let path = entry.path();
if !is_managed_session_file(&path) {
continue;
}
let metadata = entry.metadata()?;
let modified_epoch_millis = metadata
.modified()
.ok()
.and_then(|time| time.duration_since(UNIX_EPOCH).ok())
.map(|duration| duration.as_millis())
.unwrap_or_default();
let (id, message_count, parent_session_id, branch_name) =
match Session::load_from_path(&path) {
Ok(session) => {
let parent_session_id = session
.fork
.as_ref()
.map(|fork| fork.parent_session_id.clone());
let branch_name = session
.fork
.as_ref()
.and_then(|fork| fork.branch_name.clone());
(
session.session_id,
session.messages.len(),
parent_session_id,
branch_name,
)
}
Err(_) => (
path.file_stem()
.and_then(|value| value.to_str())
.unwrap_or("unknown")
.to_string(),
0,
None,
None,
),
};
sessions.push(ManagedSessionSummary {
id,
path,
modified_epoch_millis,
message_count,
parent_session_id,
branch_name,
});
}
sessions.sort_by(|left, right| {
right
.modified_epoch_millis
.cmp(&left.modified_epoch_millis)
.then_with(|| right.id.cmp(&left.id))
});
Ok(sessions)
}
pub fn latest_session(&self) -> Result<ManagedSessionSummary, SessionControlError> {
self.list_sessions()?
.into_iter()
.next()
.ok_or_else(|| SessionControlError::Format(format_no_managed_sessions()))
}
pub fn load_session(
&self,
reference: &str,
) -> Result<LoadedManagedSession, SessionControlError> {
let handle = self.resolve_reference(reference)?;
let session = Session::load_from_path(&handle.path)?;
Ok(LoadedManagedSession {
handle: SessionHandle {
id: session.session_id.clone(),
path: handle.path,
},
session,
})
}
pub fn fork_session(
&self,
session: &Session,
branch_name: Option<String>,
) -> Result<ForkedManagedSession, SessionControlError> {
let parent_session_id = session.session_id.clone();
let forked = session.fork(branch_name);
let handle = self.create_handle(&forked.session_id);
let branch_name = forked
.fork
.as_ref()
.and_then(|fork| fork.branch_name.clone());
let forked = forked.with_persistence_path(handle.path.clone());
forked.save_to_path(&handle.path)?;
Ok(ForkedManagedSession {
parent_session_id,
handle,
session: forked,
branch_name,
})
}
}
/// Stable hex fingerprint of a workspace path.
///
/// Uses FNV-1a (64-bit) to produce a 16-char hex string that partitions the
/// on-disk session directory per workspace root.
#[must_use]
pub fn workspace_fingerprint(workspace_root: &Path) -> String {
let input = workspace_root.to_string_lossy();
let mut hash = 0xcbf2_9ce4_8422_2325_u64;
for byte in input.as_bytes() {
hash ^= u64::from(*byte);
hash = hash.wrapping_mul(0x0100_0000_01b3);
}
format!("{hash:016x}")
}
pub const PRIMARY_SESSION_EXTENSION: &str = "jsonl";
pub const LEGACY_SESSION_EXTENSION: &str = "json";
@ -335,7 +579,7 @@ mod tests {
use super::{
create_managed_session_handle_for, fork_managed_session_for, is_session_reference_alias,
list_managed_sessions_for, load_managed_session_for, resolve_session_reference_for,
ManagedSessionSummary, LATEST_SESSION_REFERENCE,
workspace_fingerprint, ManagedSessionSummary, SessionStore, LATEST_SESSION_REFERENCE,
};
use crate::session::Session;
use std::fs;
@ -458,4 +702,172 @@ mod tests {
);
fs::remove_dir_all(root).expect("temp dir should clean up");
}
// ------------------------------------------------------------------
// Per-worktree session isolation (SessionStore) tests
// ------------------------------------------------------------------
fn persist_session_via_store(store: &SessionStore, text: &str) -> Session {
let mut session = Session::new();
session
.push_user_text(text)
.expect("session message should save");
let handle = store.create_handle(&session.session_id);
let session = session.with_persistence_path(handle.path.clone());
session
.save_to_path(&handle.path)
.expect("session should persist");
session
}
#[test]
fn workspace_fingerprint_is_deterministic_and_differs_per_path() {
// given
let path_a = Path::new("/tmp/worktree-alpha");
let path_b = Path::new("/tmp/worktree-beta");
// when
let fp_a1 = workspace_fingerprint(path_a);
let fp_a2 = workspace_fingerprint(path_a);
let fp_b = workspace_fingerprint(path_b);
// then
assert_eq!(fp_a1, fp_a2, "same path must produce the same fingerprint");
assert_ne!(
fp_a1, fp_b,
"different paths must produce different fingerprints"
);
assert_eq!(fp_a1.len(), 16, "fingerprint must be a 16-char hex string");
}
#[test]
fn session_store_from_cwd_isolates_sessions_by_workspace() {
// given
let base = temp_dir();
let workspace_a = base.join("repo-alpha");
let workspace_b = base.join("repo-beta");
fs::create_dir_all(&workspace_a).expect("workspace a should exist");
fs::create_dir_all(&workspace_b).expect("workspace b should exist");
let store_a = SessionStore::from_cwd(&workspace_a).expect("store a should build");
let store_b = SessionStore::from_cwd(&workspace_b).expect("store b should build");
// when
let session_a = persist_session_via_store(&store_a, "alpha work");
let _session_b = persist_session_via_store(&store_b, "beta work");
// then — each store only sees its own sessions
let list_a = store_a.list_sessions().expect("list a");
let list_b = store_b.list_sessions().expect("list b");
assert_eq!(list_a.len(), 1, "store a should see exactly one session");
assert_eq!(list_b.len(), 1, "store b should see exactly one session");
assert_eq!(list_a[0].id, session_a.session_id);
assert_ne!(
store_a.sessions_dir(),
store_b.sessions_dir(),
"session directories must differ across workspaces"
);
fs::remove_dir_all(base).expect("temp dir should clean up");
}
#[test]
fn session_store_from_data_dir_namespaces_by_workspace() {
// given
let base = temp_dir();
let data_dir = base.join("global-data");
let workspace_a = PathBuf::from("/tmp/project-one");
let workspace_b = PathBuf::from("/tmp/project-two");
fs::create_dir_all(&data_dir).expect("data dir should exist");
let store_a =
SessionStore::from_data_dir(&data_dir, &workspace_a).expect("store a should build");
let store_b =
SessionStore::from_data_dir(&data_dir, &workspace_b).expect("store b should build");
// when
persist_session_via_store(&store_a, "work in project-one");
persist_session_via_store(&store_b, "work in project-two");
// then
assert_ne!(
store_a.sessions_dir(),
store_b.sessions_dir(),
"data-dir stores must namespace by workspace"
);
assert_eq!(store_a.list_sessions().expect("list a").len(), 1);
assert_eq!(store_b.list_sessions().expect("list b").len(), 1);
assert_eq!(store_a.workspace_root(), workspace_a.as_path());
assert_eq!(store_b.workspace_root(), workspace_b.as_path());
fs::remove_dir_all(base).expect("temp dir should clean up");
}
#[test]
fn session_store_create_and_load_round_trip() {
// given
let base = temp_dir();
fs::create_dir_all(&base).expect("base dir should exist");
let store = SessionStore::from_cwd(&base).expect("store should build");
let session = persist_session_via_store(&store, "round-trip message");
// when
let loaded = store
.load_session(&session.session_id)
.expect("session should load via store");
// then
assert_eq!(loaded.handle.id, session.session_id);
assert_eq!(loaded.session.messages.len(), 1);
fs::remove_dir_all(base).expect("temp dir should clean up");
}
#[test]
fn session_store_latest_and_resolve_reference() {
// given
let base = temp_dir();
fs::create_dir_all(&base).expect("base dir should exist");
let store = SessionStore::from_cwd(&base).expect("store should build");
let _older = persist_session_via_store(&store, "older");
wait_for_next_millisecond();
let newer = persist_session_via_store(&store, "newer");
// when
let latest = store.latest_session().expect("latest should resolve");
let handle = store
.resolve_reference("latest")
.expect("latest alias should resolve");
// then
assert_eq!(latest.id, newer.session_id);
assert_eq!(handle.id, newer.session_id);
fs::remove_dir_all(base).expect("temp dir should clean up");
}
#[test]
fn session_store_fork_stays_in_same_namespace() {
// given
let base = temp_dir();
fs::create_dir_all(&base).expect("base dir should exist");
let store = SessionStore::from_cwd(&base).expect("store should build");
let source = persist_session_via_store(&store, "parent work");
// when
let forked = store
.fork_session(&source, Some("bugfix".to_string()))
.expect("fork should succeed");
let sessions = store.list_sessions().expect("list sessions");
// then
assert_eq!(
sessions.len(),
2,
"forked session must land in the same namespace"
);
assert_eq!(forked.parent_session_id, source.session_id);
assert_eq!(forked.branch_name.as_deref(), Some("bugfix"));
assert!(
forked.handle.path.starts_with(store.sessions_dir()),
"forked session path must be inside the store namespace"
);
fs::remove_dir_all(base).expect("temp dir should clean up");
}
}

429
rust/crates/runtime/src/stale_base.rs Normal file
View File

@ -0,0 +1,429 @@
#![allow(clippy::must_use_candidate)]
use std::path::Path;
use std::process::Command;
/// Outcome of comparing the worktree HEAD against the expected base commit.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BaseCommitState {
/// HEAD matches the expected base commit.
Matches,
/// HEAD has diverged from the expected base.
Diverged { expected: String, actual: String },
/// No expected base was supplied (neither flag nor file).
NoExpectedBase,
/// The working directory is not inside a git repository.
NotAGitRepo,
}
/// Where the expected base commit originated from.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum BaseCommitSource {
Flag(String),
File(String),
}
/// Read the `.claw-base` file from the given directory and return the trimmed
/// commit hash, or `None` when the file is absent or empty.
pub fn read_claw_base_file(cwd: &Path) -> Option<String> {
let path = cwd.join(".claw-base");
let content = std::fs::read_to_string(path).ok()?;
let trimmed = content.trim();
if trimmed.is_empty() {
None
} else {
Some(trimmed.to_string())
}
}
/// Resolve the expected base commit: prefer the `--base-commit` flag value,
/// fall back to reading `.claw-base` from `cwd`.
pub fn resolve_expected_base(flag_value: Option<&str>, cwd: &Path) -> Option<BaseCommitSource> {
if let Some(value) = flag_value {
let trimmed = value.trim();
if !trimmed.is_empty() {
return Some(BaseCommitSource::Flag(trimmed.to_string()));
}
}
read_claw_base_file(cwd).map(BaseCommitSource::File)
}
/// Verify that the worktree HEAD matches `expected_base`.
///
/// Returns [`BaseCommitState::NoExpectedBase`] when no expected commit is
/// provided (the check is effectively a no-op in that case).
pub fn check_base_commit(cwd: &Path, expected_base: Option<&BaseCommitSource>) -> BaseCommitState {
let Some(source) = expected_base else {
return BaseCommitState::NoExpectedBase;
};
let expected_raw = match source {
BaseCommitSource::Flag(value) | BaseCommitSource::File(value) => value.as_str(),
};
let Some(head_sha) = resolve_head_sha(cwd) else {
return BaseCommitState::NotAGitRepo;
};
let Some(expected_sha) = resolve_rev(cwd, expected_raw) else {
// If the expected ref cannot be resolved, compare raw strings as a
// best-effort fallback (e.g. partial SHA provided by the caller).
return if head_sha.starts_with(expected_raw) || expected_raw.starts_with(&head_sha) {
BaseCommitState::Matches
} else {
BaseCommitState::Diverged {
expected: expected_raw.to_string(),
actual: head_sha,
}
};
};
if head_sha == expected_sha {
BaseCommitState::Matches
} else {
BaseCommitState::Diverged {
expected: expected_sha,
actual: head_sha,
}
}
}
/// Format a human-readable warning when the base commit has diverged.
///
/// Returns `None` for non-warning states (`Matches`, `NoExpectedBase`).
pub fn format_stale_base_warning(state: &BaseCommitState) -> Option<String> {
match state {
BaseCommitState::Diverged { expected, actual } => Some(format!(
"warning: worktree HEAD ({actual}) does not match expected base commit ({expected}). \
Session may run against a stale codebase."
)),
BaseCommitState::NotAGitRepo => {
Some("warning: stale-base check skipped — not inside a git repository.".to_string())
}
BaseCommitState::Matches | BaseCommitState::NoExpectedBase => None,
}
}
fn resolve_head_sha(cwd: &Path) -> Option<String> {
resolve_rev(cwd, "HEAD")
}
fn resolve_rev(cwd: &Path, rev: &str) -> Option<String> {
let output = Command::new("git")
.args(["rev-parse", rev])
.current_dir(cwd)
.output()
.ok()?;
if !output.status.success() {
return None;
}
let sha = String::from_utf8(output.stdout).ok()?;
let trimmed = sha.trim();
if trimmed.is_empty() {
None
} else {
Some(trimmed.to_string())
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::fs;
use std::process::Command;
use std::time::{SystemTime, UNIX_EPOCH};
fn temp_dir() -> std::path::PathBuf {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.expect("time should be after epoch")
.as_nanos();
std::env::temp_dir().join(format!("runtime-stale-base-{nanos}"))
}
fn init_repo(path: &std::path::Path) {
fs::create_dir_all(path).expect("create repo dir");
run(path, &["init", "--quiet", "-b", "main"]);
run(path, &["config", "user.email", "tests@example.com"]);
run(path, &["config", "user.name", "Stale Base Tests"]);
fs::write(path.join("init.txt"), "initial\n").expect("write init file");
run(path, &["add", "."]);
run(path, &["commit", "-m", "initial commit", "--quiet"]);
}
fn run(cwd: &std::path::Path, args: &[&str]) {
let status = Command::new("git")
.args(args)
.current_dir(cwd)
.status()
.unwrap_or_else(|e| panic!("git {} failed to execute: {e}", args.join(" ")));
assert!(
status.success(),
"git {} exited with {status}",
args.join(" ")
);
}
fn commit_file(repo: &std::path::Path, name: &str, msg: &str) {
fs::write(repo.join(name), format!("{msg}\n")).expect("write file");
run(repo, &["add", name]);
run(repo, &["commit", "-m", msg, "--quiet"]);
}
fn head_sha(repo: &std::path::Path) -> String {
let output = Command::new("git")
.args(["rev-parse", "HEAD"])
.current_dir(repo)
.output()
.expect("git rev-parse HEAD");
String::from_utf8(output.stdout)
.expect("valid utf8")
.trim()
.to_string()
}
#[test]
fn matches_when_head_equals_expected_base() {
// given
let root = temp_dir();
init_repo(&root);
let sha = head_sha(&root);
let source = BaseCommitSource::Flag(sha);
// when
let state = check_base_commit(&root, Some(&source));
// then
assert_eq!(state, BaseCommitState::Matches);
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn diverged_when_head_moved_past_expected_base() {
// given
let root = temp_dir();
init_repo(&root);
let old_sha = head_sha(&root);
commit_file(&root, "extra.txt", "move head forward");
let new_sha = head_sha(&root);
let source = BaseCommitSource::Flag(old_sha.clone());
// when
let state = check_base_commit(&root, Some(&source));
// then
assert_eq!(
state,
BaseCommitState::Diverged {
expected: old_sha,
actual: new_sha,
}
);
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn no_expected_base_when_source_is_none() {
// given
let root = temp_dir();
init_repo(&root);
// when
let state = check_base_commit(&root, None);
// then
assert_eq!(state, BaseCommitState::NoExpectedBase);
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn not_a_git_repo_when_outside_repo() {
// given
let root = temp_dir();
fs::create_dir_all(&root).expect("create dir");
let source = BaseCommitSource::Flag("abc1234".to_string());
// when
let state = check_base_commit(&root, Some(&source));
// then
assert_eq!(state, BaseCommitState::NotAGitRepo);
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn reads_claw_base_file() {
// given
let root = temp_dir();
fs::create_dir_all(&root).expect("create dir");
fs::write(root.join(".claw-base"), "abc1234def5678\n").expect("write .claw-base");
// when
let value = read_claw_base_file(&root);
// then
assert_eq!(value, Some("abc1234def5678".to_string()));
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn returns_none_for_missing_claw_base_file() {
// given
let root = temp_dir();
fs::create_dir_all(&root).expect("create dir");
// when
let value = read_claw_base_file(&root);
// then
assert!(value.is_none());
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn returns_none_for_empty_claw_base_file() {
// given
let root = temp_dir();
fs::create_dir_all(&root).expect("create dir");
fs::write(root.join(".claw-base"), " \n").expect("write empty .claw-base");
// when
let value = read_claw_base_file(&root);
// then
assert!(value.is_none());
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn resolve_expected_base_prefers_flag_over_file() {
// given
let root = temp_dir();
fs::create_dir_all(&root).expect("create dir");
fs::write(root.join(".claw-base"), "from_file\n").expect("write .claw-base");
// when
let source = resolve_expected_base(Some("from_flag"), &root);
// then
assert_eq!(
source,
Some(BaseCommitSource::Flag("from_flag".to_string()))
);
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn resolve_expected_base_falls_back_to_file() {
// given
let root = temp_dir();
fs::create_dir_all(&root).expect("create dir");
fs::write(root.join(".claw-base"), "from_file\n").expect("write .claw-base");
// when
let source = resolve_expected_base(None, &root);
// then
assert_eq!(
source,
Some(BaseCommitSource::File("from_file".to_string()))
);
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn resolve_expected_base_returns_none_when_nothing_available() {
// given
let root = temp_dir();
fs::create_dir_all(&root).expect("create dir");
// when
let source = resolve_expected_base(None, &root);
// then
assert!(source.is_none());
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn format_warning_returns_message_for_diverged() {
// given
let state = BaseCommitState::Diverged {
expected: "abc1234".to_string(),
actual: "def5678".to_string(),
};
// when
let warning = format_stale_base_warning(&state);
// then
let message = warning.expect("should produce warning");
assert!(message.contains("abc1234"));
assert!(message.contains("def5678"));
assert!(message.contains("stale codebase"));
}
#[test]
fn format_warning_returns_none_for_matches() {
// given
let state = BaseCommitState::Matches;
// when
let warning = format_stale_base_warning(&state);
// then
assert!(warning.is_none());
}
#[test]
fn format_warning_returns_none_for_no_expected_base() {
// given
let state = BaseCommitState::NoExpectedBase;
// when
let warning = format_stale_base_warning(&state);
// then
assert!(warning.is_none());
}
#[test]
fn matches_with_claw_base_file_in_real_repo() {
// given
let root = temp_dir();
init_repo(&root);
let sha = head_sha(&root);
fs::write(root.join(".claw-base"), format!("{sha}\n")).expect("write .claw-base");
let source = resolve_expected_base(None, &root);
// when
let state = check_base_commit(&root, source.as_ref());
// then
assert_eq!(state, BaseCommitState::Matches);
fs::remove_dir_all(&root).expect("cleanup");
}
#[test]
fn diverged_with_claw_base_file_after_new_commit() {
// given
let root = temp_dir();
init_repo(&root);
let old_sha = head_sha(&root);
fs::write(root.join(".claw-base"), format!("{old_sha}\n")).expect("write .claw-base");
commit_file(&root, "new.txt", "advance head");
let new_sha = head_sha(&root);
let source = resolve_expected_base(None, &root);
// when
let state = check_base_commit(&root, source.as_ref());
// then
assert_eq!(
state,
BaseCommitState::Diverged {
expected: old_sha,
actual: new_sha,
}
);
fs::remove_dir_all(&root).expect("cleanup");
}
}

1
rust/crates/runtime/src/stale_branch.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::must_use_candidate)]
use std::path::Path;
use std::process::Command;

12
rust/crates/runtime/src/task_packet.rs
View File

@ -66,11 +66,7 @@ pub fn validate_packet(packet: TaskPacket) -> Result<ValidatedPacket, TaskPacket
&packet.reporting_contract,
&mut errors,
);
validate_required(
"escalation_policy",
&packet.escalation_policy,
&mut errors,
);
validate_required("escalation_policy", &packet.escalation_policy, &mut errors);
for (index, test) in packet.acceptance_tests.iter().enumerate() {
if test.trim().is_empty() {
@ -146,9 +142,9 @@ mod tests {
assert!(error
.errors()
.contains(&"repo must not be empty".to_string()));
assert!(error.errors().contains(
&"acceptance_tests contains an empty value at index 1".to_string()
));
assert!(error
.errors()
.contains(&"acceptance_tests contains an empty value at index 1".to_string()));
}
#[test]

7
rust/crates/runtime/src/task_registry.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::must_use_candidate, clippy::unnecessary_map_or)]
//! In-memory task registry for sub-agent task lifecycle management.
use std::collections::HashMap;
@ -76,11 +77,7 @@ impl TaskRegistry {
}
pub fn create(&self, prompt: &str, description: Option<&str>) -> Task {
self.create_task(
prompt.to_owned(),
description.map(str::to_owned),
None,
)
self.create_task(prompt.to_owned(), description.map(str::to_owned), None)
}
pub fn create_from_packet(

1
rust/crates/runtime/src/team_cron_registry.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::must_use_candidate)]
//! In-memory registries for Team and Cron lifecycle management.
//!
//! Provides TeamCreate/Delete and CronCreate/Delete/List runtime backing

20
rust/crates/runtime/src/worker_boot.rs
View File

@ -1,3 +1,10 @@
#![allow(
clippy::struct_excessive_bools,
clippy::too_many_lines,
clippy::question_mark,
clippy::redundant_closure,
clippy::map_unwrap_or
)]
//! In-memory worker-boot state machine and control registry.
//!
//! This provides a foundational control plane for reliable worker startup:
@ -257,7 +264,9 @@ impl WorkerRegistry {
let prompt_preview = prompt_preview(worker.last_prompt.as_deref().unwrap_or_default());
let message = match observation.target {
WorkerPromptTarget::Shell => {
format!("worker prompt landed in shell instead of coding agent: {prompt_preview}")
format!(
"worker prompt landed in shell instead of coding agent: {prompt_preview}"
)
}
WorkerPromptTarget::WrongTarget => format!(
"worker prompt landed in the wrong target instead of {}: {}",
@ -312,7 +321,9 @@ impl WorkerRegistry {
worker.last_error = None;
}
if detect_ready_for_prompt(screen_text, &lowered) && worker.status != WorkerStatus::ReadyForPrompt {
if detect_ready_for_prompt(screen_text, &lowered)
&& worker.status != WorkerStatus::ReadyForPrompt
{
worker.status = WorkerStatus::ReadyForPrompt;
worker.prompt_in_flight = false;
if matches!(
@ -412,7 +423,10 @@ impl WorkerRegistry {
worker_id: worker.worker_id.clone(),
status: worker.status,
ready: worker.status == WorkerStatus::ReadyForPrompt,
blocked: matches!(worker.status, WorkerStatus::TrustRequired | WorkerStatus::Failed),
blocked: matches!(
worker.status,
WorkerStatus::TrustRequired | WorkerStatus::Failed
),
replay_prompt_ready: worker.replay_prompt.is_some(),
last_error: worker.last_error.clone(),
})

1
rust/crates/runtime/tests/integration_tests.rs
View File

@ -1,3 +1,4 @@
#![allow(clippy::doc_markdown, clippy::uninlined_format_args, unused_imports)]
//! Integration tests for cross-module wiring.
//!
//! These tests verify that adjacent modules in the runtime crate actually

1
rust/crates/rusty-claude-cli/Cargo.toml
View File

@ -31,3 +31,4 @@ workspace = true
mock-anthropic-service = { path = "../mock-anthropic-service" }
serde_json.workspace = true
tokio = { version = "1", features = ["rt-multi-thread"] }

567
rust/crates/rusty-claude-cli/src/app.rs
View File

@ -1,567 +0,0 @@
use std::io::{self, Write};
use std::path::PathBuf;
use crate::args::{OutputFormat, PermissionMode};
use crate::input::{LineEditor, ReadOutcome};
use crate::render::{Spinner, TerminalRenderer};
use runtime::{ConversationClient, ConversationMessage, RuntimeError, StreamEvent, UsageSummary};
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionConfig {
pub model: String,
pub permission_mode: PermissionMode,
pub config: Option<PathBuf>,
pub output_format: OutputFormat,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionState {
pub turns: usize,
pub compacted_messages: usize,
pub last_model: String,
pub last_usage: UsageSummary,
}
impl SessionState {
#[must_use]
pub fn new(model: impl Into<String>) -> Self {
Self {
turns: 0,
compacted_messages: 0,
last_model: model.into(),
last_usage: UsageSummary::default(),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CommandResult {
Continue,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SlashCommand {
Help,
Status,
Compact,
Model { model: Option<String> },
Permissions { mode: Option<String> },
Config { section: Option<String> },
Memory,
Clear { confirm: bool },
Unknown(String),
}
impl SlashCommand {
#[must_use]
pub fn parse(input: &str) -> Option<Self> {
let trimmed = input.trim();
if !trimmed.starts_with('/') {
return None;
}
let mut parts = trimmed.trim_start_matches('/').split_whitespace();
let command = parts.next().unwrap_or_default();
Some(match command {
"help" => Self::Help,
"status" => Self::Status,
"compact" => Self::Compact,
"model" => Self::Model {
model: parts.next().map(ToOwned::to_owned),
},
"permissions" => Self::Permissions {
mode: parts.next().map(ToOwned::to_owned),
},
"config" => Self::Config {
section: parts.next().map(ToOwned::to_owned),
},
"memory" => Self::Memory,
"clear" => Self::Clear {
confirm: parts.next() == Some("--confirm"),
},
other => Self::Unknown(other.to_string()),
})
}
}
struct SlashCommandHandler {
command: SlashCommand,
summary: &'static str,
}
const SLASH_COMMAND_HANDLERS: &[SlashCommandHandler] = &[
SlashCommandHandler {
command: SlashCommand::Help,
summary: "Show command help",
},
SlashCommandHandler {
command: SlashCommand::Status,
summary: "Show current session status",
},
SlashCommandHandler {
command: SlashCommand::Compact,
summary: "Compact local session history",
},
SlashCommandHandler {
command: SlashCommand::Model { model: None },
summary: "Show or switch the active model",
},
SlashCommandHandler {
command: SlashCommand::Permissions { mode: None },
summary: "Show or switch the active permission mode",
},
SlashCommandHandler {
command: SlashCommand::Config { section: None },
summary: "Inspect current config path or section",
},
SlashCommandHandler {
command: SlashCommand::Memory,
summary: "Inspect loaded memory/instruction files",
},
SlashCommandHandler {
command: SlashCommand::Clear { confirm: false },
summary: "Start a fresh local session",
},
];
pub struct CliApp {
config: SessionConfig,
renderer: TerminalRenderer,
state: SessionState,
conversation_client: ConversationClient,
conversation_history: Vec<ConversationMessage>,
}
impl CliApp {
pub fn new(config: SessionConfig) -> Result<Self, RuntimeError> {
let state = SessionState::new(config.model.clone());
let conversation_client = ConversationClient::from_env(config.model.clone())?;
Ok(Self {
config,
renderer: TerminalRenderer::new(),
state,
conversation_client,
conversation_history: Vec::new(),
})
}
pub fn run_repl(&mut self) -> io::Result<()> {
let mut editor = LineEditor::new("› ", Vec::new());
println!("Rusty Claude CLI interactive mode");
println!("Type /help for commands. Shift+Enter or Ctrl+J inserts a newline.");
loop {
match editor.read_line()? {
ReadOutcome::Submit(input) => {
if input.trim().is_empty() {
continue;
}
self.handle_submission(&input, &mut io::stdout())?;
}
ReadOutcome::Cancel => continue,
ReadOutcome::Exit => break,
}
}
Ok(())
}
pub fn run_prompt(&mut self, prompt: &str, out: &mut impl Write) -> io::Result<()> {
self.render_response(prompt, out)
}
pub fn handle_submission(
&mut self,
input: &str,
out: &mut impl Write,
) -> io::Result<CommandResult> {
if let Some(command) = SlashCommand::parse(input) {
return self.dispatch_slash_command(command, out);
}
self.state.turns += 1;
self.render_response(input, out)?;
Ok(CommandResult::Continue)
}
fn dispatch_slash_command(
&mut self,
command: SlashCommand,
out: &mut impl Write,
) -> io::Result<CommandResult> {
match command {
SlashCommand::Help => Self::handle_help(out),
SlashCommand::Status => self.handle_status(out),
SlashCommand::Compact => self.handle_compact(out),
SlashCommand::Model { model } => self.handle_model(model.as_deref(), out),
SlashCommand::Permissions { mode } => self.handle_permissions(mode.as_deref(), out),
SlashCommand::Config { section } => self.handle_config(section.as_deref(), out),
SlashCommand::Memory => self.handle_memory(out),
SlashCommand::Clear { confirm } => self.handle_clear(confirm, out),
SlashCommand::Unknown(name) => {
writeln!(out, "Unknown slash command: /{name}")?;
Ok(CommandResult::Continue)
}
}
}
fn handle_help(out: &mut impl Write) -> io::Result<CommandResult> {
writeln!(out, "Available commands:")?;
for handler in SLASH_COMMAND_HANDLERS {
let name = match handler.command {
SlashCommand::Help => "/help",
SlashCommand::Status => "/status",
SlashCommand::Compact => "/compact",
SlashCommand::Model { .. } => "/model [model]",
SlashCommand::Permissions { .. } => "/permissions [mode]",
SlashCommand::Config { .. } => "/config [section]",
SlashCommand::Memory => "/memory",
SlashCommand::Clear { .. } => "/clear [--confirm]",
SlashCommand::Unknown(_) => continue,
};
writeln!(out, " {name:<9} {}", handler.summary)?;
}
Ok(CommandResult::Continue)
}
fn handle_status(&mut self, out: &mut impl Write) -> io::Result<CommandResult> {
writeln!(
out,
"status: turns={} model={} permission-mode={:?} output-format={:?} last-usage={} in/{} out config={}",
self.state.turns,
self.state.last_model,
self.config.permission_mode,
self.config.output_format,
self.state.last_usage.input_tokens,
self.state.last_usage.output_tokens,
self.config
.config
.as_ref()
.map_or_else(|| String::from("<none>"), |path| path.display().to_string())
)?;
Ok(CommandResult::Continue)
}
fn handle_compact(&mut self, out: &mut impl Write) -> io::Result<CommandResult> {
self.state.compacted_messages += self.state.turns;
self.state.turns = 0;
self.conversation_history.clear();
writeln!(
out,
"Compacted session history into a local summary ({} messages total compacted).",
self.state.compacted_messages
)?;
Ok(CommandResult::Continue)
}
fn handle_model(
&mut self,
model: Option<&str>,
out: &mut impl Write,
) -> io::Result<CommandResult> {
match model {
Some(model) => {
self.config.model = model.to_string();
self.state.last_model = model.to_string();
writeln!(out, "Active model set to {model}")?;
}
None => {
writeln!(out, "Active model: {}", self.config.model)?;
}
}
Ok(CommandResult::Continue)
}
fn handle_permissions(
&mut self,
mode: Option<&str>,
out: &mut impl Write,
) -> io::Result<CommandResult> {
match mode {
None => writeln!(out, "Permission mode: {:?}", self.config.permission_mode)?,
Some("read-only") => {
self.config.permission_mode = PermissionMode::ReadOnly;
writeln!(out, "Permission mode set to read-only")?;
}
Some("workspace-write") => {
self.config.permission_mode = PermissionMode::WorkspaceWrite;
writeln!(out, "Permission mode set to workspace-write")?;
}
Some("danger-full-access") => {
self.config.permission_mode = PermissionMode::DangerFullAccess;
writeln!(out, "Permission mode set to danger-full-access")?;
}
Some(other) => {
writeln!(out, "Unknown permission mode: {other}")?;
}
}
Ok(CommandResult::Continue)
}
fn handle_config(
&mut self,
section: Option<&str>,
out: &mut impl Write,
) -> io::Result<CommandResult> {
match section {
None => writeln!(
out,
"Config path: {}",
self.config
.config
.as_ref()
.map_or_else(|| String::from("<none>"), |path| path.display().to_string())
)?,
Some(section) => writeln!(
out,
"Config section `{section}` is not fully implemented yet; current config path is {}",
self.config
.config
.as_ref()
.map_or_else(|| String::from("<none>"), |path| path.display().to_string())
)?,
}
Ok(CommandResult::Continue)
}
fn handle_memory(&mut self, out: &mut impl Write) -> io::Result<CommandResult> {
writeln!(
out,
"Loaded memory/config file: {}",
self.config
.config
.as_ref()
.map_or_else(|| String::from("<none>"), |path| path.display().to_string())
)?;
Ok(CommandResult::Continue)
}
fn handle_clear(&mut self, confirm: bool, out: &mut impl Write) -> io::Result<CommandResult> {
if !confirm {
writeln!(out, "Refusing to clear without confirmation. Re-run as /clear --confirm")?;
return Ok(CommandResult::Continue);
}
self.state.turns = 0;
self.state.compacted_messages = 0;
self.state.last_usage = UsageSummary::default();
self.conversation_history.clear();
writeln!(out, "Started a fresh local session.")?;
Ok(CommandResult::Continue)
}
fn handle_stream_event(
renderer: &TerminalRenderer,
event: StreamEvent,
stream_spinner: &mut Spinner,
tool_spinner: &mut Spinner,
saw_text: &mut bool,
turn_usage: &mut UsageSummary,
out: &mut impl Write,
) {
match event {
StreamEvent::TextDelta(delta) => {
if !*saw_text {
let _ =
stream_spinner.finish("Streaming response", renderer.color_theme(), out);
*saw_text = true;
}
let _ = write!(out, "{delta}");
let _ = out.flush();
}
StreamEvent::ToolCallStart { name, input } => {
if *saw_text {
let _ = writeln!(out);
}
let _ = tool_spinner.tick(
&format!("Running tool `{name}` with {input}"),
renderer.color_theme(),
out,
);
}
StreamEvent::ToolCallResult {
name,
output,
is_error,
} => {
let label = if is_error {
format!("Tool `{name}` failed")
} else {
format!("Tool `{name}` completed")
};
let _ = tool_spinner.finish(&label, renderer.color_theme(), out);
let rendered_output = format!("### Tool `{name}`\n\n```text\n{output}\n```\n");
let _ = renderer.stream_markdown(&rendered_output, out);
}
StreamEvent::Usage(usage) => {
*turn_usage = usage;
}
}
}
fn write_turn_output(
&self,
summary: &runtime::TurnSummary,
out: &mut impl Write,
) -> io::Result<()> {
match self.config.output_format {
OutputFormat::Text => {
writeln!(
out,
"\nToken usage: {} input / {} output",
self.state.last_usage.input_tokens, self.state.last_usage.output_tokens
)?;
}
OutputFormat::Json => {
writeln!(
out,
"{}",
serde_json::json!({
"message": summary.assistant_text,
"usage": {
"input_tokens": self.state.last_usage.input_tokens,
"output_tokens": self.state.last_usage.output_tokens,
}
})
)?;
}
OutputFormat::Ndjson => {
writeln!(
out,
"{}",
serde_json::json!({
"type": "message",
"text": summary.assistant_text,
"usage": {
"input_tokens": self.state.last_usage.input_tokens,
"output_tokens": self.state.last_usage.output_tokens,
}
})
)?;
}
}
Ok(())
}
fn render_response(&mut self, input: &str, out: &mut impl Write) -> io::Result<()> {
let mut stream_spinner = Spinner::new();
stream_spinner.tick(
"Opening conversation stream",
self.renderer.color_theme(),
out,
)?;
let mut turn_usage = UsageSummary::default();
let mut tool_spinner = Spinner::new();
let mut saw_text = false;
let renderer = &self.renderer;
let result =
self.conversation_client
.run_turn(&mut self.conversation_history, input, |event| {
Self::handle_stream_event(
renderer,
event,
&mut stream_spinner,
&mut tool_spinner,
&mut saw_text,
&mut turn_usage,
out,
);
});
let summary = match result {
Ok(summary) => summary,
Err(error) => {
stream_spinner.fail(
"Streaming response failed",
self.renderer.color_theme(),
out,
)?;
return Err(io::Error::other(error));
}
};
self.state.last_usage = summary.usage.clone();
if saw_text {
writeln!(out)?;
} else {
stream_spinner.finish("Streaming response", self.renderer.color_theme(), out)?;
}
self.write_turn_output(&summary, out)?;
let _ = turn_usage;
Ok(())
}
}
#[cfg(test)]
mod tests {
use std::path::PathBuf;
use crate::args::{OutputFormat, PermissionMode};
use super::{CommandResult, SessionConfig, SlashCommand};
#[test]
fn parses_required_slash_commands() {
assert_eq!(SlashCommand::parse("/help"), Some(SlashCommand::Help));
assert_eq!(SlashCommand::parse(" /status "), Some(SlashCommand::Status));
assert_eq!(
SlashCommand::parse("/compact now"),
Some(SlashCommand::Compact)
);
assert_eq!(
SlashCommand::parse("/model claude-sonnet"),
Some(SlashCommand::Model {
model: Some("claude-sonnet".into()),
})
);
assert_eq!(
SlashCommand::parse("/permissions workspace-write"),
Some(SlashCommand::Permissions {
mode: Some("workspace-write".into()),
})
);
assert_eq!(
SlashCommand::parse("/config hooks"),
Some(SlashCommand::Config {
section: Some("hooks".into()),
})
);
assert_eq!(SlashCommand::parse("/memory"), Some(SlashCommand::Memory));
assert_eq!(
SlashCommand::parse("/clear --confirm"),
Some(SlashCommand::Clear { confirm: true })
);
}
#[test]
fn help_output_lists_commands() {
let mut out = Vec::new();
let result = super::CliApp::handle_help(&mut out).expect("help succeeds");
assert_eq!(result, CommandResult::Continue);
let output = String::from_utf8_lossy(&out);
assert!(output.contains("/help"));
assert!(output.contains("/status"));
assert!(output.contains("/compact"));
assert!(output.contains("/model [model]"));
assert!(output.contains("/permissions [mode]"));
assert!(output.contains("/config [section]"));
assert!(output.contains("/memory"));
assert!(output.contains("/clear [--confirm]"));
}
#[test]
fn session_state_tracks_config_values() {
let config = SessionConfig {
model: "claude".into(),
permission_mode: PermissionMode::DangerFullAccess,
config: Some(PathBuf::from("settings.toml")),
output_format: OutputFormat::Text,
};
assert_eq!(config.model, "claude");
assert_eq!(config.permission_mode, PermissionMode::DangerFullAccess);
assert_eq!(config.config, Some(PathBuf::from("settings.toml")));
}
}

108
rust/crates/rusty-claude-cli/src/args.rs
View File

@ -1,108 +0,0 @@
use std::path::PathBuf;
use clap::{Parser, Subcommand, ValueEnum};
#[derive(Debug, Clone, Parser, PartialEq, Eq)]
#[command(
name = "rusty-claude-cli",
version,
about = "Rust Claude CLI prototype"
)]
pub struct Cli {
#[arg(long, default_value = "claude-opus-4-6")]
pub model: String,
#[arg(long, value_enum, default_value_t = PermissionMode::DangerFullAccess)]
pub permission_mode: PermissionMode,
#[arg(long)]
pub config: Option<PathBuf>,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
pub output_format: OutputFormat,
#[command(subcommand)]
pub command: Option<Command>,
}
#[derive(Debug, Clone, Subcommand, PartialEq, Eq)]
pub enum Command {
/// Read upstream TS sources and print extracted counts
DumpManifests,
/// Print the current bootstrap phase skeleton
BootstrapPlan,
/// Start the OAuth login flow
Login,
/// Clear saved OAuth credentials
Logout,
/// Run a non-interactive prompt and exit
Prompt { prompt: Vec<String> },
}
#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
pub enum PermissionMode {
ReadOnly,
WorkspaceWrite,
DangerFullAccess,
}
#[derive(Debug, Clone, Copy, ValueEnum, PartialEq, Eq)]
pub enum OutputFormat {
Text,
Json,
Ndjson,
}
#[cfg(test)]
mod tests {
use clap::Parser;
use super::{Cli, Command, OutputFormat, PermissionMode};
#[test]
fn parses_requested_flags() {
let cli = Cli::parse_from([
"rusty-claude-cli",
"--model",
"claude-3-5-haiku",
"--permission-mode",
"read-only",
"--config",
"/tmp/config.toml",
"--output-format",
"ndjson",
"prompt",
"hello",
"world",
]);
assert_eq!(cli.model, "claude-3-5-haiku");
assert_eq!(cli.permission_mode, PermissionMode::ReadOnly);
assert_eq!(
cli.config.as_deref(),
Some(std::path::Path::new("/tmp/config.toml"))
);
assert_eq!(cli.output_format, OutputFormat::Ndjson);
assert_eq!(
cli.command,
Some(Command::Prompt {
prompt: vec!["hello".into(), "world".into()]
})
);
}
#[test]
fn parses_login_and_logout_commands() {
let login = Cli::parse_from(["rusty-claude-cli", "login"]);
assert_eq!(login.command, Some(Command::Login));
let logout = Cli::parse_from(["rusty-claude-cli", "logout"]);
assert_eq!(logout.command, Some(Command::Logout));
}
#[test]
fn defaults_to_danger_full_access_permission_mode() {
let cli = Cli::parse_from(["rusty-claude-cli"]);
assert_eq!(cli.permission_mode, PermissionMode::DangerFullAccess);
}
}

45
rust/crates/rusty-claude-cli/src/init.rs
View File

@ -1,7 +1,7 @@
use std::fs;
use std::path::{Path, PathBuf};
const STARTER_CLAUDE_JSON: &str = concat!(
const STARTER_CLAW_JSON: &str = concat!(
"{\n",
" \"permissions\": {\n",
" \"defaultMode\": \"dontAsk\"\n",
@ -9,7 +9,7 @@ const STARTER_CLAUDE_JSON: &str = concat!(
"}\n",
);
const GITIGNORE_COMMENT: &str = "# Claw Code local artifacts";
const GITIGNORE_ENTRIES: [&str; 2] = [".claude/settings.local.json", ".claude/sessions/"];
const GITIGNORE_ENTRIES: [&str; 2] = [".claw/settings.local.json", ".claw/sessions/"];
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum InitStatus {
@ -80,16 +80,16 @@ struct RepoDetection {
pub(crate) fn initialize_repo(cwd: &Path) -> Result<InitReport, Box<dyn std::error::Error>> {
let mut artifacts = Vec::new();
let claude_dir = cwd.join(".claude");
let claw_dir = cwd.join(".claw");
artifacts.push(InitArtifact {
name: ".claude/",
status: ensure_dir(&claude_dir)?,
name: ".claw/",
status: ensure_dir(&claw_dir)?,
});
let claude_json = cwd.join(".claude.json");
let claw_json = cwd.join(".claw.json");
artifacts.push(InitArtifact {
name: ".claude.json",
status: write_file_if_missing(&claude_json, STARTER_CLAUDE_JSON)?,
name: ".claw.json",
status: write_file_if_missing(&claw_json, STARTER_CLAW_JSON)?,
});
let gitignore = cwd.join(".gitignore");
@ -209,7 +209,7 @@ pub(crate) fn render_init_claude_md(cwd: &Path) -> String {
lines.push("## Working agreement".to_string());
lines.push("- Prefer small, reviewable changes and keep generated bootstrap files aligned with actual repo workflows.".to_string());
lines.push("- Keep shared defaults in `.claude.json`; reserve `.claude/settings.local.json` for machine-local overrides.".to_string());
lines.push("- Keep shared defaults in `.claw.json`; reserve `.claw/settings.local.json` for machine-local overrides.".to_string());
lines.push("- Do not overwrite existing `CLAUDE.md` content automatically; update it intentionally when repo workflows change.".to_string());
lines.push(String::new());
@ -354,15 +354,16 @@ mod tests {
let report = initialize_repo(&root).expect("init should succeed");
let rendered = report.render();
assert!(rendered.contains(".claude/ created"));
assert!(rendered.contains(".claude.json created"));
assert!(rendered.contains(".claw/"));
assert!(rendered.contains(".claw.json"));
assert!(rendered.contains("created"));
assert!(rendered.contains(".gitignore created"));
assert!(rendered.contains("CLAUDE.md created"));
assert!(root.join(".claude").is_dir());
assert!(root.join(".claude.json").is_file());
assert!(root.join(".claw").is_dir());
assert!(root.join(".claw.json").is_file());
assert!(root.join("CLAUDE.md").is_file());
assert_eq!(
fs::read_to_string(root.join(".claude.json")).expect("read claude json"),
fs::read_to_string(root.join(".claw.json")).expect("read claw json"),
concat!(
"{\n",
" \"permissions\": {\n",
@ -372,8 +373,8 @@ mod tests {
)
);
let gitignore = fs::read_to_string(root.join(".gitignore")).expect("read gitignore");
assert!(gitignore.contains(".claude/settings.local.json"));
assert!(gitignore.contains(".claude/sessions/"));
assert!(gitignore.contains(".claw/settings.local.json"));
assert!(gitignore.contains(".claw/sessions/"));
let claude_md = fs::read_to_string(root.join("CLAUDE.md")).expect("read claude md");
assert!(claude_md.contains("Languages: Rust."));
assert!(claude_md.contains("cargo clippy --workspace --all-targets -- -D warnings"));
@ -386,8 +387,7 @@ mod tests {
let root = temp_dir();
fs::create_dir_all(&root).expect("create root");
fs::write(root.join("CLAUDE.md"), "custom guidance\n").expect("write existing claude md");
fs::write(root.join(".gitignore"), ".claude/settings.local.json\n")
.expect("write gitignore");
fs::write(root.join(".gitignore"), ".claw/settings.local.json\n").expect("write gitignore");
let first = initialize_repo(&root).expect("first init should succeed");
assert!(first
@ -395,8 +395,9 @@ mod tests {
.contains("CLAUDE.md skipped (already exists)"));
let second = initialize_repo(&root).expect("second init should succeed");
let second_rendered = second.render();
assert!(second_rendered.contains(".claude/ skipped (already exists)"));
assert!(second_rendered.contains(".claude.json skipped (already exists)"));
assert!(second_rendered.contains(".claw/"));
assert!(second_rendered.contains(".claw.json"));
assert!(second_rendered.contains("skipped (already exists)"));
assert!(second_rendered.contains(".gitignore skipped (already exists)"));
assert!(second_rendered.contains("CLAUDE.md skipped (already exists)"));
assert_eq!(
@ -404,8 +405,8 @@ mod tests {
"custom guidance\n"
);
let gitignore = fs::read_to_string(root.join(".gitignore")).expect("read gitignore");
assert_eq!(gitignore.matches(".claude/settings.local.json").count(), 1);
assert_eq!(gitignore.matches(".claude/sessions/").count(), 1);
assert_eq!(gitignore.matches(".claw/settings.local.json").count(), 1);
assert_eq!(gitignore.matches(".claw/sessions/").count(), 1);
fs::remove_dir_all(root).expect("cleanup temp dir");
}

3929
rust/crates/rusty-claude-cli/src/main.rs
View File

File diff suppressed because it is too large Load Diff

284
rust/crates/rusty-claude-cli/src/render.rs
View File

@ -249,13 +249,14 @@ impl TerminalRenderer {
#[must_use]
pub fn render_markdown(&self, markdown: &str) -> String {
let normalized = normalize_nested_fences(markdown);
let mut output = String::new();
let mut state = RenderState::default();
let mut code_language = String::new();
let mut code_buffer = String::new();
let mut in_code_block = false;
for event in Parser::new_ext(markdown, Options::all()) {
for event in Parser::new_ext(&normalized, Options::all()) {
self.render_event(
event,
&mut state,
@ -634,8 +635,180 @@ fn apply_code_block_background(line: &str) -> String {
format!("\u{1b}[48;5;236m{with_background}\u{1b}[0m{trailing_newline}")
}
/// Pre-process raw markdown so that fenced code blocks whose body contains
/// fence markers of equal or greater length are wrapped with a longer fence.
///
/// LLMs frequently emit triple-backtick code blocks that contain triple-backtick
/// examples. CommonMark (and pulldown-cmark) treats the inner marker as the
/// closing fence, breaking the render. This function detects the situation and
/// upgrades the outer fence to use enough backticks (or tildes) that the inner
/// markers become ordinary content.
fn normalize_nested_fences(markdown: &str) -> String {
// A fence line is either "labeled" (has an info string ⇒ always an opener)
// or "bare" (no info string ⇒ could be opener or closer).
#[derive(Debug, Clone)]
struct FenceLine {
char: char,
len: usize,
has_info: bool,
indent: usize,
}
fn parse_fence_line(line: &str) -> Option<FenceLine> {
let trimmed = line.trim_end_matches('\n').trim_end_matches('\r');
let indent = trimmed.chars().take_while(|c| *c == ' ').count();
if indent > 3 {
return None;
}
let rest = &trimmed[indent..];
let ch = rest.chars().next()?;
if ch != '`' && ch != '~' {
return None;
}
let len = rest.chars().take_while(|c| *c == ch).count();
if len < 3 {
return None;
}
let after = &rest[len..];
if ch == '`' && after.contains('`') {
return None;
}
let has_info = !after.trim().is_empty();
Some(FenceLine {
char: ch,
len,
has_info,
indent,
})
}
let lines: Vec<&str> = markdown.split_inclusive('\n').collect();
// Handle final line that may lack trailing newline.
// split_inclusive already keeps the original chunks, including a
// final chunk without '\n' if the input doesn't end with one.
// First pass: classify every line.
let fence_info: Vec<Option<FenceLine>> = lines.iter().map(|l| parse_fence_line(l)).collect();
// Second pass: pair openers with closers using a stack, recording
// (opener_idx, closer_idx) pairs plus the max fence length found between
// them.
struct StackEntry {
line_idx: usize,
fence: FenceLine,
}
let mut stack: Vec<StackEntry> = Vec::new();
// Paired blocks: (opener_line, closer_line, max_inner_fence_len)
let mut pairs: Vec<(usize, usize, usize)> = Vec::new();
for (i, fi) in fence_info.iter().enumerate() {
let Some(fl) = fi else { continue };
if fl.has_info {
// Labeled fence ⇒ always an opener.
stack.push(StackEntry {
line_idx: i,
fence: fl.clone(),
});
} else {
// Bare fence ⇒ try to close the top of the stack if compatible.
let closes_top = stack
.last()
.is_some_and(|top| top.fence.char == fl.char && fl.len >= top.fence.len);
if closes_top {
let opener = stack.pop().unwrap();
// Find max fence length of any fence line strictly between
// opener and closer (these are the nested fences).
let inner_max = fence_info[opener.line_idx + 1..i]
.iter()
.filter_map(|fi| fi.as_ref().map(|f| f.len))
.max()
.unwrap_or(0);
pairs.push((opener.line_idx, i, inner_max));
} else {
// Treat as opener.
stack.push(StackEntry {
line_idx: i,
fence: fl.clone(),
});
}
}
}
// Determine which lines need rewriting. A pair needs rewriting when
// its opener length <= max inner fence length.
struct Rewrite {
char: char,
new_len: usize,
indent: usize,
}
let mut rewrites: std::collections::HashMap<usize, Rewrite> = std::collections::HashMap::new();
for (opener_idx, closer_idx, inner_max) in &pairs {
let opener_fl = fence_info[*opener_idx].as_ref().unwrap();
if opener_fl.len <= *inner_max {
let new_len = inner_max + 1;
let info_part = {
let trimmed = lines[*opener_idx]
.trim_end_matches('\n')
.trim_end_matches('\r');
let rest = &trimmed[opener_fl.indent..];
rest[opener_fl.len..].to_string()
};
rewrites.insert(
*opener_idx,
Rewrite {
char: opener_fl.char,
new_len,
indent: opener_fl.indent,
},
);
let closer_fl = fence_info[*closer_idx].as_ref().unwrap();
rewrites.insert(
*closer_idx,
Rewrite {
char: closer_fl.char,
new_len,
indent: closer_fl.indent,
},
);
// Store info string only in the opener; closer keeps the trailing
// portion which is already handled through the original line.
// Actually, we rebuild both lines from scratch below, including
// the info string for the opener.
let _ = info_part; // consumed in rebuild
}
}
if rewrites.is_empty() {
return markdown.to_string();
}
// Rebuild.
let mut out = String::with_capacity(markdown.len() + rewrites.len() * 4);
for (i, line) in lines.iter().enumerate() {
if let Some(rw) = rewrites.get(&i) {
let fence_str: String = std::iter::repeat(rw.char).take(rw.new_len).collect();
let indent_str: String = std::iter::repeat(' ').take(rw.indent).collect();
// Recover the original info string (if any) and trailing newline.
let trimmed = line.trim_end_matches('\n').trim_end_matches('\r');
let fi = fence_info[i].as_ref().unwrap();
let info = &trimmed[fi.indent + fi.len..];
let trailing = &line[trimmed.len()..];
out.push_str(&indent_str);
out.push_str(&fence_str);
out.push_str(info);
out.push_str(trailing);
} else {
out.push_str(line);
}
}
out
}
fn find_stream_safe_boundary(markdown: &str) -> Option<usize> {
let mut in_fence = false;
let mut open_fence: Option<FenceMarker> = None;
let mut last_boundary = None;
for (offset, line) in markdown.split_inclusive('\n').scan(0usize, |cursor, line| {
@ -643,20 +816,21 @@ fn find_stream_safe_boundary(markdown: &str) -> Option<usize> {
*cursor += line.len();
Some((start, line))
}) {
let trimmed = line.trim_start();
if trimmed.starts_with("```") || trimmed.starts_with("~~~") {
in_fence = !in_fence;
if !in_fence {
let line_without_newline = line.trim_end_matches('\n');
if let Some(opener) = open_fence {
if line_closes_fence(line_without_newline, opener) {
open_fence = None;
last_boundary = Some(offset + line.len());
}
continue;
}
if in_fence {
if let Some(opener) = parse_fence_opener(line_without_newline) {
open_fence = Some(opener);
continue;
}
if trimmed.is_empty() {
if line_without_newline.trim().is_empty() {
last_boundary = Some(offset + line.len());
}
}
@ -664,6 +838,46 @@ fn find_stream_safe_boundary(markdown: &str) -> Option<usize> {
last_boundary
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct FenceMarker {
character: char,
length: usize,
}
fn parse_fence_opener(line: &str) -> Option<FenceMarker> {
let indent = line.chars().take_while(|c| *c == ' ').count();
if indent > 3 {
return None;
}
let rest = &line[indent..];
let character = rest.chars().next()?;
if character != '`' && character != '~' {
return None;
}
let length = rest.chars().take_while(|c| *c == character).count();
if length < 3 {
return None;
}
let info_string = &rest[length..];
if character == '`' && info_string.contains('`') {
return None;
}
Some(FenceMarker { character, length })
}
fn line_closes_fence(line: &str, opener: FenceMarker) -> bool {
let indent = line.chars().take_while(|c| *c == ' ').count();
if indent > 3 {
return false;
}
let rest = &line[indent..];
let length = rest.chars().take_while(|c| *c == opener.character).count();
if length < opener.length {
return false;
}
rest[length..].chars().all(|c| c == ' ' || c == '\t')
}
fn visible_width(input: &str) -> usize {
strip_ansi(input).chars().count()
}
@ -778,6 +992,60 @@ mod tests {
assert!(strip_ansi(&code).contains("fn main()"));
}
#[test]
fn streaming_state_holds_outer_fence_with_nested_inner_fence() {
let renderer = TerminalRenderer::new();
let mut state = MarkdownStreamState::default();
assert_eq!(
state.push(&renderer, "````markdown\n```rust\nfn inner() {}\n"),
None,
"inner triple backticks must not close the outer four-backtick fence"
);
assert_eq!(
state.push(&renderer, "```\n"),
None,
"closing the inner fence must not flush the outer fence"
);
let flushed = state
.push(&renderer, "````\n")
.expect("closing the outer four-backtick fence flushes the buffered block");
let plain_text = strip_ansi(&flushed);
assert!(plain_text.contains("fn inner()"));
assert!(plain_text.contains("```rust"));
}
#[test]
fn streaming_state_distinguishes_backtick_and_tilde_fences() {
let renderer = TerminalRenderer::new();
let mut state = MarkdownStreamState::default();
assert_eq!(state.push(&renderer, "~~~text\n"), None);
assert_eq!(
state.push(&renderer, "```\nstill inside tilde fence\n"),
None,
"a backtick fence cannot close a tilde-opened fence"
);
assert_eq!(state.push(&renderer, "```\n"), None);
let flushed = state
.push(&renderer, "~~~\n")
.expect("matching tilde marker closes the fence");
let plain_text = strip_ansi(&flushed);
assert!(plain_text.contains("still inside tilde fence"));
}
#[test]
fn renders_nested_fenced_code_block_preserves_inner_markers() {
let terminal_renderer = TerminalRenderer::new();
let markdown_output =
terminal_renderer.markdown_to_ansi("````markdown\n```rust\nfn nested() {}\n```\n````");
let plain_text = strip_ansi(&markdown_output);
assert!(plain_text.contains("╭─ markdown"));
assert!(plain_text.contains("```rust"));
assert!(plain_text.contains("fn nested()"));
}
#[test]
fn spinner_advances_frames() {
let terminal_renderer = TerminalRenderer::new();

98
rust/crates/rusty-claude-cli/tests/cli_flags_and_config_defaults.rs
View File

@ -104,6 +104,31 @@ fn slash_command_names_match_known_commands_and_suggest_nearby_unknown_ones() {
fs::remove_dir_all(temp_dir).expect("cleanup temp dir");
}
#[test]
fn omc_namespaced_slash_commands_surface_a_targeted_compatibility_hint() {
let temp_dir = unique_temp_dir("slash-dispatch-omc");
fs::create_dir_all(&temp_dir).expect("temp dir should exist");
let output = Command::new(env!("CARGO_BIN_EXE_claw"))
.current_dir(&temp_dir)
.arg("/oh-my-claudecode:hud")
.output()
.expect("claw should launch");
assert!(
!output.status.success(),
"stdout:\n{}\n\nstderr:\n{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
let stderr = String::from_utf8(output.stderr).expect("stderr should be utf8");
assert!(stderr.contains("unknown slash command outside the REPL: /oh-my-claudecode:hud"));
assert!(stderr.contains("Claude Code/OMC plugin command"));
assert!(stderr.contains("does not yet load plugin slash commands"));
fs::remove_dir_all(temp_dir).expect("cleanup temp dir");
}
#[test]
fn config_command_loads_defaults_from_standard_config_locations() {
// given
@ -160,6 +185,79 @@ fn config_command_loads_defaults_from_standard_config_locations() {
fs::remove_dir_all(temp_dir).expect("cleanup temp dir");
}
#[test]
fn doctor_command_runs_as_a_local_shell_entrypoint() {
// given
let temp_dir = unique_temp_dir("doctor-entrypoint");
let config_home = temp_dir.join("home").join(".claw");
fs::create_dir_all(&config_home).expect("config home should exist");
// when
let output = command_in(&temp_dir)
.env("CLAW_CONFIG_HOME", &config_home)
.env_remove("ANTHROPIC_API_KEY")
.env_remove("ANTHROPIC_AUTH_TOKEN")
.env("ANTHROPIC_BASE_URL", "http://127.0.0.1:9")
.arg("doctor")
.output()
.expect("claw doctor should launch");
// then
assert_success(&output);
let stdout = String::from_utf8(output.stdout).expect("stdout should be utf8");
assert!(stdout.contains("Doctor"));
assert!(stdout.contains("Auth"));
assert!(stdout.contains("Config"));
assert!(stdout.contains("Workspace"));
assert!(stdout.contains("Sandbox"));
assert!(!stdout.contains("Thinking"));
fs::remove_dir_all(temp_dir).expect("cleanup temp dir");
}
#[test]
fn local_subcommand_help_does_not_fall_through_to_runtime_or_provider_calls() {
let temp_dir = unique_temp_dir("subcommand-help");
let config_home = temp_dir.join("home").join(".claw");
fs::create_dir_all(&config_home).expect("config home should exist");
let doctor_help = command_in(&temp_dir)
.env("CLAW_CONFIG_HOME", &config_home)
.env_remove("ANTHROPIC_API_KEY")
.env_remove("ANTHROPIC_AUTH_TOKEN")
.env("ANTHROPIC_BASE_URL", "http://127.0.0.1:9")
.args(["doctor", "--help"])
.output()
.expect("doctor help should launch");
let status_help = command_in(&temp_dir)
.env("CLAW_CONFIG_HOME", &config_home)
.env_remove("ANTHROPIC_API_KEY")
.env_remove("ANTHROPIC_AUTH_TOKEN")
.env("ANTHROPIC_BASE_URL", "http://127.0.0.1:9")
.args(["status", "--help"])
.output()
.expect("status help should launch");
assert_success(&doctor_help);
let doctor_stdout = String::from_utf8(doctor_help.stdout).expect("stdout should be utf8");
assert!(doctor_stdout.contains("Usage claw doctor"));
assert!(doctor_stdout.contains("local-only health report"));
assert!(!doctor_stdout.contains("Thinking"));
assert_success(&status_help);
let status_stdout = String::from_utf8(status_help.stdout).expect("stdout should be utf8");
assert!(status_stdout.contains("Usage claw status"));
assert!(status_stdout.contains("local workspace snapshot"));
assert!(!status_stdout.contains("Thinking"));
let doctor_stderr = String::from_utf8(doctor_help.stderr).expect("stderr should be utf8");
let status_stderr = String::from_utf8(status_help.stderr).expect("stderr should be utf8");
assert!(!doctor_stderr.contains("auth_unavailable"));
assert!(!status_stderr.contains("auth_unavailable"));
fs::remove_dir_all(temp_dir).expect("cleanup temp dir");
}
fn command_in(cwd: &Path) -> Command {
let mut command = Command::new(env!("CARGO_BIN_EXE_claw"));
command.current_dir(cwd);

159
rust/crates/rusty-claude-cli/tests/compact_output.rs Normal file
View File

@ -0,0 +1,159 @@
use std::fs;
use std::path::PathBuf;
use std::process::{Command, Output};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};
use mock_anthropic_service::{MockAnthropicService, SCENARIO_PREFIX};
static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
#[test]
fn compact_flag_prints_only_final_assistant_text_without_tool_call_details() {
// given a workspace pointed at the mock Anthropic service and a fixture file
// that the read_file_roundtrip scenario will fetch through a tool call
let runtime = tokio::runtime::Runtime::new().expect("tokio runtime should build");
let server = runtime
.block_on(MockAnthropicService::spawn())
.expect("mock service should start");
let base_url = server.base_url();
let workspace = unique_temp_dir("compact-read-file");
let config_home = workspace.join("config-home");
let home = workspace.join("home");
fs::create_dir_all(&workspace).expect("workspace should exist");
fs::create_dir_all(&config_home).expect("config home should exist");
fs::create_dir_all(&home).expect("home should exist");
fs::write(workspace.join("fixture.txt"), "alpha parity line\n").expect("fixture should write");
// when we run claw in compact text mode against a tool-using scenario
let prompt = format!("{SCENARIO_PREFIX}read_file_roundtrip");
let output = run_claw(
&workspace,
&config_home,
&home,
&base_url,
&[
"--model",
"sonnet",
"--permission-mode",
"read-only",
"--allowedTools",
"read_file",
"--compact",
&prompt,
],
);
// then the command exits successfully and stdout contains exactly the final
// assistant text with no tool call IDs, JSON envelopes, or spinner output
assert!(
output.status.success(),
"compact run should succeed\nstdout:\n{}\n\nstderr:\n{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr),
);
let stdout = String::from_utf8(output.stdout).expect("stdout should be utf8");
let trimmed = stdout.trim_end_matches('\n');
assert_eq!(
trimmed, "read_file roundtrip complete: alpha parity line",
"compact stdout should contain only the final assistant text"
);
assert!(
!stdout.contains("toolu_"),
"compact stdout must not leak tool_use_id ({stdout:?})"
);
assert!(
!stdout.contains("\"tool_uses\""),
"compact stdout must not leak json envelopes ({stdout:?})"
);
assert!(
!stdout.contains("Thinking"),
"compact stdout must not include the spinner banner ({stdout:?})"
);
fs::remove_dir_all(&workspace).expect("workspace cleanup should succeed");
}
#[test]
fn compact_flag_streaming_text_only_emits_final_message_text() {
// given a workspace pointed at the mock Anthropic service running the
// streaming_text scenario which only emits a single assistant text block
let runtime = tokio::runtime::Runtime::new().expect("tokio runtime should build");
let server = runtime
.block_on(MockAnthropicService::spawn())
.expect("mock service should start");
let base_url = server.base_url();
let workspace = unique_temp_dir("compact-streaming-text");
let config_home = workspace.join("config-home");
let home = workspace.join("home");
fs::create_dir_all(&workspace).expect("workspace should exist");
fs::create_dir_all(&config_home).expect("config home should exist");
fs::create_dir_all(&home).expect("home should exist");
// when we invoke claw with --compact for the streaming text scenario
let prompt = format!("{SCENARIO_PREFIX}streaming_text");
let output = run_claw(
&workspace,
&config_home,
&home,
&base_url,
&[
"--model",
"sonnet",
"--permission-mode",
"read-only",
"--compact",
&prompt,
],
);
// then stdout should be exactly the assistant text followed by a newline
assert!(
output.status.success(),
"compact streaming run should succeed\nstdout:\n{}\n\nstderr:\n{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr),
);
let stdout = String::from_utf8(output.stdout).expect("stdout should be utf8");
assert_eq!(
stdout, "Mock streaming says hello from the parity harness.\n",
"compact streaming stdout should contain only the final assistant text"
);
fs::remove_dir_all(&workspace).expect("workspace cleanup should succeed");
}
fn run_claw(
cwd: &std::path::Path,
config_home: &std::path::Path,
home: &std::path::Path,
base_url: &str,
args: &[&str],
) -> Output {
let mut command = Command::new(env!("CARGO_BIN_EXE_claw"));
command
.current_dir(cwd)
.env_clear()
.env("ANTHROPIC_API_KEY", "test-compact-key")
.env("ANTHROPIC_BASE_URL", base_url)
.env("CLAW_CONFIG_HOME", config_home)
.env("HOME", home)
.env("NO_COLOR", "1")
.env("PATH", "/usr/bin:/bin")
.args(args);
command.output().expect("claw should launch")
}
fn unique_temp_dir(label: &str) -> PathBuf {
let millis = SystemTime::now()
.duration_since(UNIX_EPOCH)
.expect("clock should be after epoch")
.as_millis();
let counter = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
std::env::temp_dir().join(format!(
"claw-compact-{label}-{}-{millis}-{counter}",
std::process::id()
))
}

3
rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs
View File

@ -729,8 +729,7 @@ fn assert_token_cost_reporting(_: &HarnessWorkspace, run: &ScenarioRun) {
assert!(
run.response["estimated_cost"]
.as_str()
.map(|cost| cost.starts_with('$'))
.unwrap_or(false),
.is_some_and(|cost| cost.starts_with('$')),
"estimated_cost should be a dollar-prefixed string"
);
}

428
rust/crates/rusty-claude-cli/tests/output_format_contract.rs Normal file
View File

@ -0,0 +1,428 @@
use std::fs;
use std::path::{Path, PathBuf};
use std::process::{Command, Output};
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::{SystemTime, UNIX_EPOCH};
use serde_json::Value;
static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
#[test]
fn help_emits_json_when_requested() {
let root = unique_temp_dir("help-json");
fs::create_dir_all(&root).expect("temp dir should exist");
let parsed = assert_json_command(&root, &["--output-format", "json", "help"]);
assert_eq!(parsed["kind"], "help");
assert!(parsed["message"]
.as_str()
.expect("help text")
.contains("Usage:"));
}
#[test]
fn version_emits_json_when_requested() {
let root = unique_temp_dir("version-json");
fs::create_dir_all(&root).expect("temp dir should exist");
let parsed = assert_json_command(&root, &["--output-format", "json", "version"]);
assert_eq!(parsed["kind"], "version");
assert_eq!(parsed["version"], env!("CARGO_PKG_VERSION"));
}
#[test]
fn status_and_sandbox_emit_json_when_requested() {
let root = unique_temp_dir("status-sandbox-json");
fs::create_dir_all(&root).expect("temp dir should exist");
let status = assert_json_command(&root, &["--output-format", "json", "status"]);
assert_eq!(status["kind"], "status");
assert!(status["workspace"]["cwd"].as_str().is_some());
let sandbox = assert_json_command(&root, &["--output-format", "json", "sandbox"]);
assert_eq!(sandbox["kind"], "sandbox");
assert!(sandbox["filesystem_mode"].as_str().is_some());
}
#[test]
fn inventory_commands_emit_structured_json_when_requested() {
let root = unique_temp_dir("inventory-json");
fs::create_dir_all(&root).expect("temp dir should exist");
let isolated_home = root.join("home");
let isolated_config = root.join("config-home");
let isolated_codex = root.join("codex-home");
fs::create_dir_all(&isolated_home).expect("isolated home should exist");
let agents = assert_json_command_with_env(
&root,
&["--output-format", "json", "agents"],
&[
("HOME", isolated_home.to_str().expect("utf8 home")),
(
"CLAW_CONFIG_HOME",
isolated_config.to_str().expect("utf8 config home"),
),
(
"CODEX_HOME",
isolated_codex.to_str().expect("utf8 codex home"),
),
],
);
assert_eq!(agents["kind"], "agents");
assert_eq!(agents["action"], "list");
assert_eq!(agents["count"], 0);
assert_eq!(agents["summary"]["active"], 0);
assert!(agents["agents"]
.as_array()
.expect("agents array")
.is_empty());
let mcp = assert_json_command(&root, &["--output-format", "json", "mcp"]);
assert_eq!(mcp["kind"], "mcp");
assert_eq!(mcp["action"], "list");
let skills = assert_json_command(&root, &["--output-format", "json", "skills"]);
assert_eq!(skills["kind"], "skills");
assert_eq!(skills["action"], "list");
}
#[test]
fn agents_command_emits_structured_agent_entries_when_requested() {
let root = unique_temp_dir("agents-json-populated");
let workspace = root.join("workspace");
let project_agents = workspace.join(".codex").join("agents");
let home = root.join("home");
let user_agents = home.join(".codex").join("agents");
let isolated_config = root.join("config-home");
let isolated_codex = root.join("codex-home");
fs::create_dir_all(&workspace).expect("workspace should exist");
write_agent(
&project_agents,
"planner",
"Project planner",
"gpt-5.4",
"medium",
);
write_agent(
&project_agents,
"verifier",
"Verification agent",
"gpt-5.4-mini",
"high",
);
write_agent(
&user_agents,
"planner",
"User planner",
"gpt-5.4-mini",
"high",
);
let parsed = assert_json_command_with_env(
&workspace,
&["--output-format", "json", "agents"],
&[
("HOME", home.to_str().expect("utf8 home")),
(
"CLAW_CONFIG_HOME",
isolated_config.to_str().expect("utf8 config home"),
),
(
"CODEX_HOME",
isolated_codex.to_str().expect("utf8 codex home"),
),
],
);
assert_eq!(parsed["kind"], "agents");
assert_eq!(parsed["action"], "list");
assert_eq!(parsed["count"], 3);
assert_eq!(parsed["summary"]["active"], 2);
assert_eq!(parsed["summary"]["shadowed"], 1);
assert_eq!(parsed["agents"][0]["name"], "planner");
assert_eq!(parsed["agents"][0]["source"]["id"], "project_claw");
assert_eq!(parsed["agents"][0]["active"], true);
assert_eq!(parsed["agents"][1]["name"], "verifier");
assert_eq!(parsed["agents"][2]["name"], "planner");
assert_eq!(parsed["agents"][2]["active"], false);
assert_eq!(parsed["agents"][2]["shadowed_by"]["id"], "project_claw");
}
#[test]
fn bootstrap_and_system_prompt_emit_json_when_requested() {
let root = unique_temp_dir("bootstrap-system-prompt-json");
fs::create_dir_all(&root).expect("temp dir should exist");
let plan = assert_json_command(&root, &["--output-format", "json", "bootstrap-plan"]);
assert_eq!(plan["kind"], "bootstrap-plan");
assert!(plan["phases"].as_array().expect("phases").len() > 1);
let prompt = assert_json_command(&root, &["--output-format", "json", "system-prompt"]);
assert_eq!(prompt["kind"], "system-prompt");
assert!(prompt["message"]
.as_str()
.expect("prompt text")
.contains("interactive agent"));
}
#[test]
fn dump_manifests_and_init_emit_json_when_requested() {
let root = unique_temp_dir("manifest-init-json");
fs::create_dir_all(&root).expect("temp dir should exist");
let upstream = write_upstream_fixture(&root);
let manifests = assert_json_command_with_env(
&root,
&["--output-format", "json", "dump-manifests"],
&[(
"CLAUDE_CODE_UPSTREAM",
upstream.to_str().expect("utf8 upstream"),
)],
);
assert_eq!(manifests["kind"], "dump-manifests");
assert_eq!(manifests["commands"], 1);
assert_eq!(manifests["tools"], 1);
let workspace = root.join("workspace");
fs::create_dir_all(&workspace).expect("workspace should exist");
let init = assert_json_command(&workspace, &["--output-format", "json", "init"]);
assert_eq!(init["kind"], "init");
assert!(workspace.join("CLAUDE.md").exists());
}
#[test]
fn doctor_and_resume_status_emit_json_when_requested() {
let root = unique_temp_dir("doctor-resume-json");
fs::create_dir_all(&root).expect("temp dir should exist");
let doctor = assert_json_command(&root, &["--output-format", "json", "doctor"]);
assert_eq!(doctor["kind"], "doctor");
assert!(doctor["message"].is_string());
let summary = doctor["summary"].as_object().expect("doctor summary");
assert!(summary["ok"].as_u64().is_some());
assert!(summary["warnings"].as_u64().is_some());
assert!(summary["failures"].as_u64().is_some());
let checks = doctor["checks"].as_array().expect("doctor checks");
assert_eq!(checks.len(), 5);
let check_names = checks
.iter()
.map(|check| {
assert!(check["status"].as_str().is_some());
assert!(check["summary"].as_str().is_some());
assert!(check["details"].is_array());
check["name"].as_str().expect("doctor check name")
})
.collect::<Vec<_>>();
assert_eq!(
check_names,
vec!["auth", "config", "workspace", "sandbox", "system"]
);
let workspace = checks
.iter()
.find(|check| check["name"] == "workspace")
.expect("workspace check");
assert!(workspace["cwd"].as_str().is_some());
assert!(workspace["in_git_repo"].is_boolean());
let sandbox = checks
.iter()
.find(|check| check["name"] == "sandbox")
.expect("sandbox check");
assert!(sandbox["filesystem_mode"].as_str().is_some());
assert!(sandbox["enabled"].is_boolean());
assert!(sandbox["fallback_reason"].is_null() || sandbox["fallback_reason"].is_string());
let session_path = root.join("session.jsonl");
fs::write(
&session_path,
"{\"type\":\"session_meta\",\"version\":3,\"session_id\":\"resume-json\",\"created_at_ms\":0,\"updated_at_ms\":0}\n{\"type\":\"message\",\"message\":{\"role\":\"user\",\"blocks\":[{\"type\":\"text\",\"text\":\"hello\"}]}}\n",
)
.expect("session should write");
let resumed = assert_json_command(
&root,
&[
"--output-format",
"json",
"--resume",
session_path.to_str().expect("utf8 session path"),
"/status",
],
);
assert_eq!(resumed["kind"], "status");
assert_eq!(resumed["model"], "restored-session");
assert_eq!(resumed["usage"]["messages"], 1);
assert!(resumed["workspace"]["cwd"].as_str().is_some());
assert!(resumed["sandbox"]["filesystem_mode"].as_str().is_some());
}
#[test]
fn resumed_inventory_commands_emit_structured_json_when_requested() {
let root = unique_temp_dir("resume-inventory-json");
let config_home = root.join("config-home");
let home = root.join("home");
fs::create_dir_all(&config_home).expect("config home should exist");
fs::create_dir_all(&home).expect("home should exist");
let session_path = root.join("session.jsonl");
fs::write(
&session_path,
"{\"type\":\"session_meta\",\"version\":3,\"session_id\":\"resume-inventory-json\",\"created_at_ms\":0,\"updated_at_ms\":0}\n{\"type\":\"message\",\"message\":{\"role\":\"user\",\"blocks\":[{\"type\":\"text\",\"text\":\"inventory\"}]}}\n",
)
.expect("session should write");
let mcp = assert_json_command_with_env(
&root,
&[
"--output-format",
"json",
"--resume",
session_path.to_str().expect("utf8 session path"),
"/mcp",
],
&[
(
"CLAW_CONFIG_HOME",
config_home.to_str().expect("utf8 config home"),
),
("HOME", home.to_str().expect("utf8 home")),
],
);
assert_eq!(mcp["kind"], "mcp");
assert_eq!(mcp["action"], "list");
assert!(mcp["servers"].is_array());
let skills = assert_json_command_with_env(
&root,
&[
"--output-format",
"json",
"--resume",
session_path.to_str().expect("utf8 session path"),
"/skills",
],
&[
(
"CLAW_CONFIG_HOME",
config_home.to_str().expect("utf8 config home"),
),
("HOME", home.to_str().expect("utf8 home")),
],
);
assert_eq!(skills["kind"], "skills");
assert_eq!(skills["action"], "list");
assert!(skills["summary"]["total"].is_number());
assert!(skills["skills"].is_array());
}
#[test]
fn resumed_version_and_init_emit_structured_json_when_requested() {
let root = unique_temp_dir("resume-version-init-json");
fs::create_dir_all(&root).expect("temp dir should exist");
let session_path = root.join("session.jsonl");
fs::write(
&session_path,
"{\"type\":\"session_meta\",\"version\":3,\"session_id\":\"resume-version-init-json\",\"created_at_ms\":0,\"updated_at_ms\":0}\n",
)
.expect("session should write");
let version = assert_json_command(
&root,
&[
"--output-format",
"json",
"--resume",
session_path.to_str().expect("utf8 session path"),
"/version",
],
);
assert_eq!(version["kind"], "version");
assert_eq!(version["version"], env!("CARGO_PKG_VERSION"));
let init = assert_json_command(
&root,
&[
"--output-format",
"json",
"--resume",
session_path.to_str().expect("utf8 session path"),
"/init",
],
);
assert_eq!(init["kind"], "init");
assert!(root.join("CLAUDE.md").exists());
}
fn assert_json_command(current_dir: &Path, args: &[&str]) -> Value {
assert_json_command_with_env(current_dir, args, &[])
}
fn assert_json_command_with_env(current_dir: &Path, args: &[&str], envs: &[(&str, &str)]) -> Value {
let output = run_claw(current_dir, args, envs);
assert!(
output.status.success(),
"stdout:\n{}\n\nstderr:\n{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
serde_json::from_slice(&output.stdout).expect("stdout should be valid json")
}
fn run_claw(current_dir: &Path, args: &[&str], envs: &[(&str, &str)]) -> Output {
let mut command = Command::new(env!("CARGO_BIN_EXE_claw"));
command.current_dir(current_dir).args(args);
for (key, value) in envs {
command.env(key, value);
}
command.output().expect("claw should launch")
}
fn write_upstream_fixture(root: &Path) -> PathBuf {
let upstream = root.join("claw-code");
let src = upstream.join("src");
let entrypoints = src.join("entrypoints");
fs::create_dir_all(&entrypoints).expect("upstream entrypoints dir should exist");
fs::write(
src.join("commands.ts"),
"import FooCommand from './commands/foo'\n",
)
.expect("commands fixture should write");
fs::write(
src.join("tools.ts"),
"import ReadTool from './tools/read'\n",
)
.expect("tools fixture should write");
fs::write(
entrypoints.join("cli.tsx"),
"if (args[0] === '--version') {}\nstartupProfiler()\n",
)
.expect("cli fixture should write");
upstream
}
fn write_agent(root: &Path, name: &str, description: &str, model: &str, reasoning: &str) {
fs::create_dir_all(root).expect("agent root should exist");
fs::write(
root.join(format!("{name}.toml")),
format!(
"name = \"{name}\"\ndescription = \"{description}\"\nmodel = \"{model}\"\nmodel_reasoning_effort = \"{reasoning}\"\n"
),
)
.expect("agent fixture should write");
}
fn unique_temp_dir(label: &str) -> PathBuf {
let millis = SystemTime::now()
.duration_since(UNIX_EPOCH)
.expect("clock should be after epoch")
.as_millis();
let counter = TEMP_COUNTER.fetch_add(1, Ordering::Relaxed);
std::env::temp_dir().join(format!(
"claw-output-format-{label}-{}-{millis}-{counter}",
std::process::id()
))
}

97
rust/crates/rusty-claude-cli/tests/resume_slash_commands.rs
View File

@ -7,6 +7,7 @@ use std::time::{SystemTime, UNIX_EPOCH};
use runtime::ContentBlock;
use runtime::Session;
use serde_json::Value;
static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0);
@ -221,6 +222,102 @@ fn resume_latest_restores_the_most_recent_managed_session() {
assert!(stdout.contains(newer_path.to_str().expect("utf8 path")));
}
#[test]
fn resumed_status_command_emits_structured_json_when_requested() {
// given
let temp_dir = unique_temp_dir("resume-status-json");
fs::create_dir_all(&temp_dir).expect("temp dir should exist");
let session_path = temp_dir.join("session.jsonl");
let mut session = Session::new();
session
.push_user_text("resume status json fixture")
.expect("session write should succeed");
session
.save_to_path(&session_path)
.expect("session should persist");
// when
let output = run_claw(
&temp_dir,
&[
"--output-format",
"json",
"--resume",
session_path.to_str().expect("utf8 path"),
"/status",
],
);
// then
assert!(
output.status.success(),
"stdout:\n{}\n\nstderr:\n{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
let stdout = String::from_utf8(output.stdout).expect("stdout should be utf8");
let parsed: Value =
serde_json::from_str(stdout.trim()).expect("resume status output should be json");
assert_eq!(parsed["kind"], "status");
assert_eq!(parsed["model"], "restored-session");
assert_eq!(parsed["permission_mode"], "danger-full-access");
assert_eq!(parsed["usage"]["messages"], 1);
assert!(parsed["usage"]["turns"].is_number());
assert!(parsed["workspace"]["cwd"].as_str().is_some());
assert_eq!(
parsed["workspace"]["session"],
session_path.to_str().expect("utf8 path")
);
assert!(parsed["workspace"]["changed_files"].is_number());
assert_eq!(parsed["workspace"]["loaded_config_files"].as_u64(), Some(0));
assert!(parsed["sandbox"]["filesystem_mode"].as_str().is_some());
}
#[test]
fn resumed_sandbox_command_emits_structured_json_when_requested() {
// given
let temp_dir = unique_temp_dir("resume-sandbox-json");
fs::create_dir_all(&temp_dir).expect("temp dir should exist");
let session_path = temp_dir.join("session.jsonl");
Session::new()
.save_to_path(&session_path)
.expect("session should persist");
// when
let output = run_claw(
&temp_dir,
&[
"--output-format",
"json",
"--resume",
session_path.to_str().expect("utf8 path"),
"/sandbox",
],
);
// then
assert!(
output.status.success(),
"stdout:\n{}\n\nstderr:\n{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
let stdout = String::from_utf8(output.stdout).expect("stdout should be utf8");
let parsed: Value =
serde_json::from_str(stdout.trim()).expect("resume sandbox output should be json");
assert_eq!(parsed["kind"], "sandbox");
assert!(parsed["enabled"].is_boolean());
assert!(parsed["active"].is_boolean());
assert!(parsed["supported"].is_boolean());
assert!(parsed["filesystem_mode"].as_str().is_some());
assert!(parsed["allowed_mounts"].is_array());
assert!(parsed["markers"].is_array());
}
fn run_claw(current_dir: &Path, args: &[&str]) -> Output {
run_claw_with_env(current_dir, args, &[])
}

2
rust/crates/tools/Cargo.toml
View File

@ -7,6 +7,8 @@ publish.workspace = true
[dependencies]
api = { path = "../api" }
commands = { path = "../commands" }
flate2 = "1"
plugins = { path = "../plugins" }
runtime = { path = "../runtime" }
reqwest = { version = "0.12", default-features = false, features = ["blocking", "rustls-tls"] }

47
rust/crates/tools/src/lane_completion.rs
View File

@ -16,9 +16,10 @@ use runtime::{
use crate::AgentOutput;
/// Detects if a lane should be automatically marked as completed.
///
///
/// Returns `Some(LaneContext)` with `completed = true` if all conditions met,
/// `None` if lane should remain active.
#[allow(dead_code)]
pub(crate) fn detect_lane_completion(
output: &AgentOutput,
test_green: bool,
@ -28,29 +29,29 @@ pub(crate) fn detect_lane_completion(
if output.error.is_some() {
return None;
}
// Must have finished status
if !output.status.eq_ignore_ascii_case("completed")
&& !output.status.eq_ignore_ascii_case("finished")
{
return None;
}
// Must have no current blocker
if output.current_blocker.is_some() {
return None;
}
// Must have green tests
if !test_green {
return None;
}
// Must have pushed code
if !has_pushed {
return None;
}
// All conditions met — create completed context
Some(LaneContext {
lane_id: output.agent_id.clone(),
@ -65,9 +66,8 @@ pub(crate) fn detect_lane_completion(
}
/// Evaluates policy actions for a completed lane.
pub(crate) fn evaluate_completed_lane(
context: &LaneContext,
) -> Vec<PolicyAction> {
#[allow(dead_code)]
pub(crate) fn evaluate_completed_lane(context: &LaneContext) -> Vec<PolicyAction> {
let engine = PolicyEngine::new(vec![
PolicyRule::new(
"closeout-completed-lane",
@ -85,7 +85,7 @@ pub(crate) fn evaluate_completed_lane(
5,
),
]);
evaluate(&engine, context)
}
@ -108,57 +108,58 @@ mod tests {
started_at: Some("2024-01-01T00:00:00Z".to_string()),
completed_at: Some("2024-01-01T00:00:00Z".to_string()),
lane_events: vec![],
derived_state: "working".to_string(),
current_blocker: None,
error: None,
}
}
#[test]
fn detects_completion_when_all_conditions_met() {
let output = test_output();
let result = detect_lane_completion(&output, true, true);
assert!(result.is_some());
let context = result.unwrap();
assert!(context.completed);
assert_eq!(context.green_level, 3);
assert_eq!(context.blocker, LaneBlocker::None);
}
#[test]
fn no_completion_when_error_present() {
let mut output = test_output();
output.error = Some("Build failed".to_string());
let result = detect_lane_completion(&output, true, true);
assert!(result.is_none());
}
#[test]
fn no_completion_when_not_finished() {
let mut output = test_output();
output.status = "Running".to_string();
let result = detect_lane_completion(&output, true, true);
assert!(result.is_none());
}
#[test]
fn no_completion_when_tests_not_green() {
let output = test_output();
let result = detect_lane_completion(&output, false, true);
assert!(result.is_none());
}
#[test]
fn no_completion_when_not_pushed() {
let output = test_output();
let result = detect_lane_completion(&output, true, false);
assert!(result.is_none());
}
#[test]
fn evaluate_triggers_closeout_for_completed_lane() {
let context = LaneContext {
@ -171,9 +172,9 @@ mod tests {
completed: true,
reconciled: false,
};
let actions = evaluate_completed_lane(&context);
assert!(actions.contains(&PolicyAction::CloseoutLane));
assert!(actions.contains(&PolicyAction::CleanupSession));
}

1290
rust/crates/tools/src/lib.rs
View File

File diff suppressed because it is too large Load Diff

548
rust/crates/tools/src/pdf_extract.rs Normal file
View File

@ -0,0 +1,548 @@
//! Minimal PDF text extraction.
//!
//! Reads a PDF file, locates `/Contents` stream objects, decompresses with
//! flate2 when the stream uses `/FlateDecode`, and extracts text operators
//! found between `BT` / `ET` markers.
use std::io::Read as _;
use std::path::Path;
/// Extract all readable text from a PDF file.
///
/// Returns the concatenated text found inside BT/ET operators across all
/// content streams. Non-text pages or encrypted PDFs yield an empty string
/// rather than an error.
pub fn extract_text(path: &Path) -> Result<String, String> {
let data = std::fs::read(path).map_err(|e| format!("failed to read PDF: {e}"))?;
Ok(extract_text_from_bytes(&data))
}
/// Core extraction from raw PDF bytes — useful for testing without touching the
/// filesystem.
pub(crate) fn extract_text_from_bytes(data: &[u8]) -> String {
let mut all_text = String::new();
let mut offset = 0;
while offset < data.len() {
let Some(stream_start) = find_subsequence(&data[offset..], b"stream") else {
break;
};
let abs_start = offset + stream_start;
// Determine the byte offset right after "stream\r\n" or "stream\n".
let content_start = skip_stream_eol(data, abs_start + b"stream".len());
let Some(end_rel) = find_subsequence(&data[content_start..], b"endstream") else {
break;
};
let content_end = content_start + end_rel;
// Look backwards from "stream" for a FlateDecode hint in the object
// dictionary. We scan at most 512 bytes before the stream keyword.
let dict_window_start = abs_start.saturating_sub(512);
let dict_window = &data[dict_window_start..abs_start];
let is_flate = find_subsequence(dict_window, b"FlateDecode").is_some();
// Only process streams whose parent dictionary references /Contents or
// looks like a page content stream (contains /Length). We intentionally
// keep this loose to cover both inline and referenced content streams.
let raw = &data[content_start..content_end];
let decompressed;
let stream_bytes: &[u8] = if is_flate {
if let Ok(buf) = inflate(raw) {
decompressed = buf;
&decompressed
} else {
offset = content_end;
continue;
}
} else {
raw
};
let text = extract_bt_et_text(stream_bytes);
if !text.is_empty() {
if !all_text.is_empty() {
all_text.push('\n');
}
all_text.push_str(&text);
}
offset = content_end;
}
all_text
}
/// Inflate (zlib / deflate) compressed data via `flate2`.
fn inflate(data: &[u8]) -> Result<Vec<u8>, String> {
let mut decoder = flate2::read::ZlibDecoder::new(data);
let mut buf = Vec::new();
decoder
.read_to_end(&mut buf)
.map_err(|e| format!("flate2 inflate error: {e}"))?;
Ok(buf)
}
/// Extract text from PDF content-stream operators between BT and ET markers.
///
/// Handles the common text-showing operators:
/// - `Tj` — show a string
/// - `TJ` — show an array of strings/numbers
/// - `'` — move to next line and show string
/// - `"` — set spacing, move to next line and show string
fn extract_bt_et_text(stream: &[u8]) -> String {
let text = String::from_utf8_lossy(stream);
let mut result = String::new();
let mut in_bt = false;
for line in text.lines() {
let trimmed = line.trim();
if trimmed == "BT" {
in_bt = true;
continue;
}
if trimmed == "ET" {
in_bt = false;
continue;
}
if !in_bt {
continue;
}
// Tj operator: (text) Tj
if trimmed.ends_with("Tj") {
if let Some(s) = extract_parenthesized_string(trimmed) {
if !result.is_empty() && !result.ends_with('\n') {
result.push(' ');
}
result.push_str(&s);
}
}
// TJ operator: [ (text) 123 (text) ] TJ
else if trimmed.ends_with("TJ") {
let extracted = extract_tj_array(trimmed);
if !extracted.is_empty() {
if !result.is_empty() && !result.ends_with('\n') {
result.push(' ');
}
result.push_str(&extracted);
}
}
// ' operator: (text) ' and " operator: aw ac (text) "
else if is_newline_show_operator(trimmed) {
if let Some(s) = extract_parenthesized_string(trimmed) {
if !result.is_empty() {
result.push('\n');
}
result.push_str(&s);
}
}
}
result
}
/// Returns `true` when `trimmed` looks like a `'` or `"` text-show operator.
fn is_newline_show_operator(trimmed: &str) -> bool {
(trimmed.ends_with('\'') && trimmed.len() > 1)
|| (trimmed.ends_with('"') && trimmed.contains('('))
}
/// Pull the text from the first `(…)` group, handling escaped parens and
/// common PDF escape sequences.
fn extract_parenthesized_string(input: &str) -> Option<String> {
let open = input.find('(')?;
let bytes = input.as_bytes();
let mut depth = 0;
let mut result = String::new();
let mut i = open;
while i < bytes.len() {
match bytes[i] {
b'(' => {
if depth > 0 {
result.push('(');
}
depth += 1;
}
b')' => {
depth -= 1;
if depth == 0 {
return Some(result);
}
result.push(')');
}
b'\\' if i + 1 < bytes.len() => {
i += 1;
match bytes[i] {
b'n' => result.push('\n'),
b'r' => result.push('\r'),
b't' => result.push('\t'),
b'\\' => result.push('\\'),
b'(' => result.push('('),
b')' => result.push(')'),
// Octal sequences — up to 3 digits.
d @ b'0'..=b'7' => {
let mut octal = u32::from(d - b'0');
for _ in 0..2 {
if i + 1 < bytes.len()
&& bytes[i + 1].is_ascii_digit()
&& bytes[i + 1] <= b'7'
{
i += 1;
octal = octal * 8 + u32::from(bytes[i] - b'0');
} else {
break;
}
}
if let Some(ch) = char::from_u32(octal) {
result.push(ch);
}
}
other => result.push(char::from(other)),
}
}
ch => result.push(char::from(ch)),
}
i += 1;
}
None // unbalanced
}
/// Extract concatenated strings from a TJ array like `[ (Hello) -120 (World) ] TJ`.
fn extract_tj_array(input: &str) -> String {
let mut result = String::new();
let Some(bracket_start) = input.find('[') else {
return result;
};
let Some(bracket_end) = input.rfind(']') else {
return result;
};
let inner = &input[bracket_start + 1..bracket_end];
let mut i = 0;
let bytes = inner.as_bytes();
while i < bytes.len() {
if bytes[i] == b'(' {
// Reconstruct the parenthesized string and extract it.
if let Some(s) = extract_parenthesized_string(&inner[i..]) {
result.push_str(&s);
// Skip past the closing paren.
let mut depth = 0u32;
for &b in &bytes[i..] {
i += 1;
if b == b'(' {
depth += 1;
} else if b == b')' {
depth -= 1;
if depth == 0 {
break;
}
}
}
continue;
}
}
i += 1;
}
result
}
/// Skip past the end-of-line marker that immediately follows the `stream`
/// keyword. Per the PDF spec this is either `\r\n` or `\n`.
fn skip_stream_eol(data: &[u8], pos: usize) -> usize {
if pos < data.len() && data[pos] == b'\r' {
if pos + 1 < data.len() && data[pos + 1] == b'\n' {
return pos + 2;
}
return pos + 1;
}
if pos < data.len() && data[pos] == b'\n' {
return pos + 1;
}
pos
}
/// Simple byte-subsequence search.
fn find_subsequence(haystack: &[u8], needle: &[u8]) -> Option<usize> {
haystack
.windows(needle.len())
.position(|window| window == needle)
}
/// Check if a user-supplied path looks like a PDF file reference.
#[must_use]
pub fn looks_like_pdf_path(text: &str) -> Option<&str> {
for token in text.split_whitespace() {
let cleaned = token.trim_matches(|c: char| c == '\'' || c == '"' || c == '`');
if let Some(dot_pos) = cleaned.rfind('.') {
if cleaned[dot_pos + 1..].eq_ignore_ascii_case("pdf") && dot_pos > 0 {
return Some(cleaned);
}
}
}
None
}
/// Auto-extract text from a PDF path mentioned in a user prompt.
///
/// Returns `Some((path, extracted_text))` when a `.pdf` path is detected and
/// the file exists, otherwise `None`.
#[must_use]
pub fn maybe_extract_pdf_from_prompt(prompt: &str) -> Option<(String, String)> {
let pdf_path = looks_like_pdf_path(prompt)?;
let path = Path::new(pdf_path);
if !path.exists() {
return None;
}
let text = extract_text(path).ok()?;
if text.is_empty() {
return None;
}
Some((pdf_path.to_string(), text))
}
#[cfg(test)]
mod tests {
use super::*;
/// Build a minimal valid PDF with a single page containing uncompressed
/// text. This is the smallest PDF structure that exercises the BT/ET
/// extraction path.
fn build_simple_pdf(text: &str) -> Vec<u8> {
let content_stream = format!("BT\n/F1 12 Tf\n({text}) Tj\nET");
let stream_bytes = content_stream.as_bytes();
let mut pdf = Vec::new();
// Header
pdf.extend_from_slice(b"%PDF-1.4\n");
// Object 1 — Catalog
let obj1_offset = pdf.len();
pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
// Object 2 — Pages
let obj2_offset = pdf.len();
pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n");
// Object 3 — Page
let obj3_offset = pdf.len();
pdf.extend_from_slice(
b"3 0 obj\n<< /Type /Page /Parent 2 0 R /Contents 4 0 R >>\nendobj\n",
);
// Object 4 — Content stream (uncompressed)
let obj4_offset = pdf.len();
let length = stream_bytes.len();
let header = format!("4 0 obj\n<< /Length {length} >>\nstream\n");
pdf.extend_from_slice(header.as_bytes());
pdf.extend_from_slice(stream_bytes);
pdf.extend_from_slice(b"\nendstream\nendobj\n");
// Cross-reference table
let xref_offset = pdf.len();
pdf.extend_from_slice(b"xref\n0 5\n");
pdf.extend_from_slice(b"0000000000 65535 f \n");
pdf.extend_from_slice(format!("{obj1_offset:010} 00000 n \n").as_bytes());
pdf.extend_from_slice(format!("{obj2_offset:010} 00000 n \n").as_bytes());
pdf.extend_from_slice(format!("{obj3_offset:010} 00000 n \n").as_bytes());
pdf.extend_from_slice(format!("{obj4_offset:010} 00000 n \n").as_bytes());
// Trailer
pdf.extend_from_slice(b"trailer\n<< /Size 5 /Root 1 0 R >>\n");
pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF\n").as_bytes());
pdf
}
/// Build a minimal PDF with flate-compressed content stream.
fn build_flate_pdf(text: &str) -> Vec<u8> {
use flate2::write::ZlibEncoder;
use flate2::Compression;
use std::io::Write as _;
let content_stream = format!("BT\n/F1 12 Tf\n({text}) Tj\nET");
let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default());
encoder
.write_all(content_stream.as_bytes())
.expect("compress");
let compressed = encoder.finish().expect("finish");
let mut pdf = Vec::new();
pdf.extend_from_slice(b"%PDF-1.4\n");
let obj1_offset = pdf.len();
pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
let obj2_offset = pdf.len();
pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n");
let obj3_offset = pdf.len();
pdf.extend_from_slice(
b"3 0 obj\n<< /Type /Page /Parent 2 0 R /Contents 4 0 R >>\nendobj\n",
);
let obj4_offset = pdf.len();
let length = compressed.len();
let header = format!("4 0 obj\n<< /Length {length} /Filter /FlateDecode >>\nstream\n");
pdf.extend_from_slice(header.as_bytes());
pdf.extend_from_slice(&compressed);
pdf.extend_from_slice(b"\nendstream\nendobj\n");
let xref_offset = pdf.len();
pdf.extend_from_slice(b"xref\n0 5\n");
pdf.extend_from_slice(b"0000000000 65535 f \n");
pdf.extend_from_slice(format!("{obj1_offset:010} 00000 n \n").as_bytes());
pdf.extend_from_slice(format!("{obj2_offset:010} 00000 n \n").as_bytes());
pdf.extend_from_slice(format!("{obj3_offset:010} 00000 n \n").as_bytes());
pdf.extend_from_slice(format!("{obj4_offset:010} 00000 n \n").as_bytes());
pdf.extend_from_slice(b"trailer\n<< /Size 5 /Root 1 0 R >>\n");
pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF\n").as_bytes());
pdf
}
#[test]
fn extracts_uncompressed_text_from_minimal_pdf() {
// given
let pdf_bytes = build_simple_pdf("Hello World");
// when
let text = extract_text_from_bytes(&pdf_bytes);
// then
assert_eq!(text, "Hello World");
}
#[test]
fn extracts_text_from_flate_compressed_stream() {
// given
let pdf_bytes = build_flate_pdf("Compressed PDF Text");
// when
let text = extract_text_from_bytes(&pdf_bytes);
// then
assert_eq!(text, "Compressed PDF Text");
}
#[test]
fn handles_tj_array_operator() {
// given
let stream = b"BT\n/F1 12 Tf\n[ (Hello) -120 ( World) ] TJ\nET";
// Build a raw PDF with TJ array operator instead of simple Tj.
let content_stream = std::str::from_utf8(stream).unwrap();
let raw = format!(
"%PDF-1.4\n1 0 obj\n<< /Type /Catalog >>\nendobj\n\
2 0 obj\n<< /Length {} >>\nstream\n{}\nendstream\nendobj\n%%EOF\n",
content_stream.len(),
content_stream
);
let pdf_bytes = raw.into_bytes();
// when
let text = extract_text_from_bytes(&pdf_bytes);
// then
assert_eq!(text, "Hello World");
}
#[test]
fn handles_escaped_parentheses() {
// given
let content = b"BT\n(Hello \\(World\\)) Tj\nET";
let raw = format!(
"%PDF-1.4\n1 0 obj\n<< /Length {} >>\nstream\n",
content.len()
);
let mut pdf_bytes = raw.into_bytes();
pdf_bytes.extend_from_slice(content);
pdf_bytes.extend_from_slice(b"\nendstream\nendobj\n%%EOF\n");
// when
let text = extract_text_from_bytes(&pdf_bytes);
// then
assert_eq!(text, "Hello (World)");
}
#[test]
fn returns_empty_for_non_pdf_data() {
// given
let data = b"This is not a PDF file at all";
// when
let text = extract_text_from_bytes(data);
// then
assert!(text.is_empty());
}
#[test]
fn extracts_text_from_file_on_disk() {
// given
let pdf_bytes = build_simple_pdf("Disk Test");
let dir = std::env::temp_dir().join("clawd-pdf-extract-test");
std::fs::create_dir_all(&dir).unwrap();
let pdf_path = dir.join("test.pdf");
std::fs::write(&pdf_path, &pdf_bytes).unwrap();
// when
let text = extract_text(&pdf_path).unwrap();
// then
assert_eq!(text, "Disk Test");
// cleanup
let _ = std::fs::remove_dir_all(&dir);
}
#[test]
fn looks_like_pdf_path_detects_pdf_references() {
// given / when / then
assert_eq!(
looks_like_pdf_path("Please read /tmp/report.pdf"),
Some("/tmp/report.pdf")
);
assert_eq!(looks_like_pdf_path("Check file.PDF now"), Some("file.PDF"));
assert_eq!(looks_like_pdf_path("no pdf here"), None);
}
#[test]
fn maybe_extract_pdf_from_prompt_returns_none_for_missing_file() {
// given
let prompt = "Read /tmp/nonexistent-abc123.pdf please";
// when
let result = maybe_extract_pdf_from_prompt(prompt);
// then
assert!(result.is_none());
}
#[test]
fn maybe_extract_pdf_from_prompt_extracts_existing_file() {
// given
let pdf_bytes = build_simple_pdf("Auto Extracted");
let dir = std::env::temp_dir().join("clawd-pdf-auto-extract-test");
std::fs::create_dir_all(&dir).unwrap();
let pdf_path = dir.join("auto.pdf");
std::fs::write(&pdf_path, &pdf_bytes).unwrap();
let prompt = format!("Summarize {}", pdf_path.display());
// when
let result = maybe_extract_pdf_from_prompt(&prompt);
// then
let (path, text) = result.expect("should extract");
assert_eq!(path, pdf_path.display().to_string());
assert_eq!(text, "Auto Extracted");
// cleanup
let _ = std::fs::remove_dir_all(&dir);
}
}