From cd6fa07aba5edeae83255e842349a9c49204ae63 Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 01:54:05 +0800 Subject: [PATCH 01/10] chore: ignore .DS_Store Finder metadata kept showing up as an untracked file in this macOS checkout. (cherry picked from commit 868a8ac29abab5127e7d5e4b3532a9e2cb9b3e21) --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 5def5d5d7f..acc4f731bf 100644 --- a/.gitignore +++ b/.gitignore @@ -19,3 +19,4 @@ status-help.txt .envrc.local result result-* +.DS_Store From 765c2f54afb67807a3c9b7ac1e52b6ad711824b5 Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 01:59:58 +0800 Subject: [PATCH 02/10] test(cli): assert parallel tool results pair on the wire Drives the real `claw` binary against the mock Anthropic service for the `multi_tool_turn_roundtrip` scenario and asserts on the payload the provider would receive: every `tool_use` of an assistant message must be answered by `tool_result` blocks in the message immediately after it, and a turn with two tool calls must still produce exactly one tool-result message. This lives in `tests/` rather than beside `convert_messages` so it can be reverted independently of the fix. Run against the pre-fix implementation it fails with the payload that caused the live 400: request 1: ["user[text]", "assistant[tool_use, tool_use]", "user[tool_result]", "user[tool_result]"] left: ["toolu_multi_read"] right: ["toolu_multi_read", "toolu_multi_grep"] The mock service does not validate pairing itself, which is why the contract is asserted here. `cargo test -p rusty-claude-cli --test parallel_tool_result_pairing` passes with the fix and fails without it. (cherry picked from commit 4eba1e2c784602ee4693570b11a435dace18a2af) --- .../tests/parallel_tool_result_pairing.rs | 231 ++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 rust/crates/rusty-claude-cli/tests/parallel_tool_result_pairing.rs diff --git a/rust/crates/rusty-claude-cli/tests/parallel_tool_result_pairing.rs b/rust/crates/rusty-claude-cli/tests/parallel_tool_result_pairing.rs new file mode 100644 index 0000000000..da450f4f5e --- /dev/null +++ b/rust/crates/rusty-claude-cli/tests/parallel_tool_result_pairing.rs @@ -0,0 +1,231 @@ +//! Wire contract for turns that issue several tool calls at once. +//! +//! The Anthropic Messages API requires every `tool_use` of an assistant message +//! to be answered by `tool_result` blocks in the message that immediately +//! follows it. A turn with two tool calls used to emit one result message per +//! call, so the second result arrived one message too late and the provider +//! rejected the request with `messages.N: tool_use ids were found without +//! tool_result blocks immediately after`. +//! +//! This test drives the real `claw` binary against the mock Anthropic service +//! and asserts on the payload the provider would receive, so it fails against +//! the pre-fix implementation without depending on any private helper. The +//! mock service does not validate pairing itself, which is why the assertion +//! lives here. + +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}; +use serde_json::{json, Value}; + +static TEMP_COUNTER: AtomicU64 = AtomicU64::new(0); + +const SCENARIO: &str = "multi_tool_turn_roundtrip"; + +#[test] +fn parallel_tool_calls_are_answered_in_one_following_message() { + let runtime = tokio::runtime::Runtime::new().expect("tokio runtime should build"); + let workspace = unique_temp_dir("parallel-tool-pairing"); + let config_home = workspace.join("config-home"); + let home = workspace.join("home"); + 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\nbeta line\ngamma parity line\n", + ) + .expect("fixture should write"); + prepare_config_home(&config_home); + + let server = runtime + .block_on(MockAnthropicService::spawn()) + .expect("mock service should start"); + let output = run_claw(&workspace, &config_home, &home, &server.base_url()); + assert!( + output.status.success(), + "claw should complete the parallel tool turn\nstdout:\n{}\n\nstderr:\n{}", + String::from_utf8_lossy(&output.stdout), + String::from_utf8_lossy(&output.stderr), + ); + + let requests = runtime + .block_on(server.captured_requests()) + .into_iter() + .filter(|request| request.path == "/v1/messages") + .map(|request| { + serde_json::from_str::(&request.raw_body).expect("request body should be json") + }) + .collect::>(); + + // The turn issued two tool calls, so the follow-up request must carry their + // results. Asserting the count also catches a split into two messages. + let tool_result_requests = requests + .iter() + .filter(|body| messages_have_tool_result(body)) + .count(); + assert_eq!( + tool_result_requests, + 1, + "tool results must reach the provider in one message; requests were:\n{}", + describe_requests(&requests), + ); + + let mut inspected_tool_uses = 0_u64; + for body in &requests { + let messages = body + .get("messages") + .and_then(Value::as_array) + .unwrap_or_else(|| panic!("request should carry messages: {body}")); + for (index, message) in messages.iter().enumerate() { + let calls = tool_use_ids(message); + if calls.is_empty() { + continue; + } + inspected_tool_uses += calls.len() as u64; + let answered = messages + .get(index + 1) + .map(tool_result_ids) + .unwrap_or_default(); + assert_eq!( + answered, + calls, + "messages.{index} tool_use {calls:?} must be answered by the next message; \ + requests were:\n{}", + describe_requests(&requests), + ); + } + } + assert!( + inspected_tool_uses >= 2, + "the scenario should exercise parallel tool calls, saw {inspected_tool_uses}: {}", + describe_requests(&requests), + ); + + fs::remove_dir_all(&workspace).expect("workspace cleanup should succeed"); +} + +/// Writes the permission preset the mock harness runs with. +fn prepare_config_home(config_home: &PathBuf) { + fs::write( + config_home.join("settings.json"), + json!({ "permissions": { "defaultMode": "read-only" } }).to_string(), + ) + .expect("settings should write"); +} + +fn run_claw(workspace: &PathBuf, config_home: &PathBuf, home: &PathBuf, base_url: &str) -> Output { + Command::new(env!("CARGO_BIN_EXE_claw")) + .current_dir(workspace) + .env_clear() + .env("ANTHROPIC_API_KEY", "test-parallel-tool-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([ + "--model", + "sonnet", + "--permission-mode", + "read-only", + "--output-format=json", + "--allowedTools", + "read_file,grep_search", + ]) + .arg(format!("{SCENARIO_PREFIX}{SCENARIO}")) + .output() + .expect("claw should launch") +} + +fn messages_have_tool_result(body: &Value) -> bool { + body.get("messages") + .and_then(Value::as_array) + .is_some_and(|messages| { + messages + .iter() + .any(|message| !tool_result_ids(message).is_empty()) + }) +} + +fn tool_use_ids(message: &Value) -> Vec { + block_ids(message, "tool_use", "id") +} + +fn tool_result_ids(message: &Value) -> Vec { + block_ids(message, "tool_result", "tool_use_id") +} + +fn block_ids(message: &Value, block_type: &str, id_field: &str) -> Vec { + message + .get("content") + .and_then(Value::as_array) + .map(|blocks| { + blocks + .iter() + .filter(|block| block.get("type").and_then(Value::as_str) == Some(block_type)) + .filter_map(|block| block.get(id_field).and_then(Value::as_str)) + .map(ToString::to_string) + .collect() + }) + .unwrap_or_default() +} + +/// Renders the message role/block shape of every captured request for failures. +fn describe_requests(requests: &[Value]) -> String { + requests + .iter() + .enumerate() + .map(|(index, body)| { + let shape = body + .get("messages") + .and_then(Value::as_array) + .map(|messages| { + messages + .iter() + .map(|message| { + let role = message + .get("role") + .and_then(Value::as_str) + .unwrap_or("unknown"); + let blocks = message + .get("content") + .and_then(Value::as_array) + .map(|blocks| { + blocks + .iter() + .map(|block| { + block + .get("type") + .and_then(Value::as_str) + .unwrap_or("unknown") + .to_string() + }) + .collect::>() + }) + .unwrap_or_default(); + format!("{role}{blocks:?}") + }) + .collect::>() + }) + .unwrap_or_default(); + format!(" request {index}: {shape:?}") + }) + .collect::>() + .join("\n") +} + +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-{label}-{}-{millis}-{counter}", + std::process::id() + )) +} From ade98a7f09922aadc47ec1daddbc51c4e57164ec Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 02:21:09 +0800 Subject: [PATCH 03/10] fix(cli): pair parallel tool-call results in one message `convert_messages` emitted one wire message per `MessageRole::Tool` record. The Anthropic Messages API requires every `tool_use` of an assistant message to be answered by `tool_result` blocks in the single message that follows it, so the second and later results of a parallel tool-call turn landed one message too late and the provider rejected the whole request: api returned 400 Bad Request (invalid_request_error): messages.3: `tool_use` ids were found without `tool_result` blocks immediately after: call_01_4QJqcZ0075kla1ILwra75582 Single-call turns were unaffected, which is why the defect only surfaced when the model requested several tools at once. Evidence: `.claw/sessions/ e49619b247aa3fce/session-1792170907799-0.jsonl`, whose step-1 assistant message carries two `tool_use` blocks followed by two separate tool-result messages. Fix: `convert_messages` is split into a per-message `convert_message` plus a folding accumulator `absorb_tool_result_message`, which merges a run of adjacent tool-result messages into the one `user` message that follows the assistant turn. The merge only extends a message whose content is tool results and nothing else, so user text and assistant turns can never be joined. `converts_tool_roundtrip_messages` keeps its previous single-call contract. Verification: `cargo test -p rusty-claude-cli` (224 unit tests plus the integration targets); `scripts/fmt.sh --check`. (cherry picked from commit 1c0ba66dc1ca128ba27c6a6cb63db81a6e8a92c5) --- rust/crates/rusty-claude-cli/src/main.rs | 181 +++++++++++++++++------ 1 file changed, 133 insertions(+), 48 deletions(-) diff --git a/rust/crates/rusty-claude-cli/src/main.rs b/rust/crates/rusty-claude-cli/src/main.rs index 934fce0a1c..fa555b5309 100644 --- a/rust/crates/rusty-claude-cli/src/main.rs +++ b/rust/crates/rusty-claude-cli/src/main.rs @@ -14720,55 +14720,97 @@ fn permission_policy( fn convert_messages(messages: &[ConversationMessage]) -> Vec { messages .iter() - .filter_map(|message| { - let role = match message.role { - MessageRole::System | MessageRole::User | MessageRole::Tool => "user", - MessageRole::Assistant => "assistant", - }; - let content = message - .blocks - .iter() - .filter_map(|block| match block { - ContentBlock::Text { text } => { - Some(InputContentBlock::Text { text: text.clone() }) - } - ContentBlock::Thinking { - thinking, - signature, - } => { - // 保留 Thinking 块：OpenAI 兼容协议会把它转成 reasoning_content 字段 - // 回传给 DeepSeek V4（避免 400 "reasoning_content must be passed back" 错误） - Some(InputContentBlock::Thinking { - thinking: thinking.clone(), - signature: signature.clone(), - }) - } - ContentBlock::ToolUse { id, name, input } => Some(InputContentBlock::ToolUse { - id: id.clone(), - name: name.clone(), - input: serde_json::from_str(input) - .unwrap_or_else(|_| serde_json::json!({ "raw": input })), - }), - ContentBlock::ToolResult { - tool_use_id, - output, - is_error, - .. - } => Some(InputContentBlock::ToolResult { - tool_use_id: tool_use_id.clone(), - content: vec![ToolResultContentBlock::Text { - text: output.clone(), - }], - is_error: *is_error, - }), + .filter_map(convert_message) + .fold(Vec::new(), absorb_tool_result_message) +} + +/// Converts one conversation message into its wire form. +fn convert_message(message: &ConversationMessage) -> Option { + let role = match message.role { + MessageRole::System | MessageRole::User | MessageRole::Tool => "user", + MessageRole::Assistant => "assistant", + }; + let content = message + .blocks + .iter() + .filter_map(|block| match block { + ContentBlock::Text { text } => Some(InputContentBlock::Text { text: text.clone() }), + ContentBlock::Thinking { + thinking, + signature, + } => { + // 保留 Thinking 块：OpenAI 兼容协议会把它转成 reasoning_content 字段 + // 回传给 DeepSeek V4（避免 400 "reasoning_content must be passed back" 错误） + Some(InputContentBlock::Thinking { + thinking: thinking.clone(), + signature: signature.clone(), }) - .collect::>(); - (!content.is_empty()).then(|| InputMessage { - role: role.to_string(), - content, - }) + } + ContentBlock::ToolUse { id, name, input } => Some(InputContentBlock::ToolUse { + id: id.clone(), + name: name.clone(), + input: serde_json::from_str(input) + .unwrap_or_else(|_| serde_json::json!({ "raw": input })), + }), + ContentBlock::ToolResult { + tool_use_id, + output, + is_error, + .. + } => Some(InputContentBlock::ToolResult { + tool_use_id: tool_use_id.clone(), + content: vec![ToolResultContentBlock::Text { + text: output.clone(), + }], + is_error: *is_error, + }), }) - .collect() + .collect::>(); + (!content.is_empty()).then(|| InputMessage { + role: role.to_string(), + content, + }) +} + +/// Appends a message to the wire history, merging a *run* of pure tool-result +/// messages into one message. +/// +/// `runtime` records one `MessageRole::Tool` message per tool call, but the +/// Anthropic Messages API requires *every* `tool_use` of an assistant turn to be +/// answered by `tool_result` blocks **in the same following message**. Emitting +/// one message per result leaves the second and later results of a parallel +/// tool-call turn one message too late, and the request is rejected with +/// `messages.N: tool_use ids were found without tool_result blocks immediately +/// after`. +/// +/// Only the first message of a run can extend the accumulated message: the +/// assistant turn that issued the calls must keep exactly one following user +/// message, and a single tool result must never be appended to an assistant +/// message, because the API expects `tool_result` blocks only in user turns. +fn absorb_tool_result_message( + mut messages: Vec, + message: InputMessage, +) -> Vec { + // Every tool result reaches the wire as its own `user` message; a *run* of + // them belongs to the single user message that follows the assistant turn + // issuing the calls, so keep extending it while it still holds only results. + if let Some(previous) = messages.last_mut() { + if previous.role == "user" && is_tool_result_only(previous) { + previous.content.extend(message.content); + return messages; + } + } + messages.push(message); + messages +} + +/// Reports whether a wire message carries tool results and nothing else. +fn is_tool_result_only(message: &InputMessage) -> bool { + !message.content.is_empty() + && message + .content + .iter() + .all(|block| matches!(block, InputContentBlock::ToolResult { .. })) } #[allow(clippy::too_many_lines)] @@ -15013,7 +15055,7 @@ mod tests { SessionLifecycleSummary, SlashCommand, StatusUsage, TerminalTail, TmuxPaneSnapshot, DEFAULT_MODEL, LATEST_SESSION_REFERENCE, STUB_COMMANDS, }; - use api::{ApiError, MessageResponse, OutputContentBlock, Usage}; + use api::{ApiError, InputContentBlock, MessageResponse, OutputContentBlock, Usage}; use plugins::{ PluginManager, PluginManagerConfig, PluginTool, PluginToolDefinition, PluginToolPermission, }; @@ -19384,6 +19426,49 @@ UU conflicted.rs", assert_eq!(converted[1].role, "assistant"); assert_eq!(converted[2].role, "user"); } + + #[test] + fn converts_parallel_tool_call_results_into_one_paired_message() { + let tool_use = |id: &str| ContentBlock::ToolUse { + id: id.to_string(), + name: "bash".to_string(), + input: "{\"command\":\"pwd\"}".to_string(), + }; + let tool_result = |id: &str| ConversationMessage { + role: MessageRole::Tool, + blocks: vec![ContentBlock::ToolResult { + tool_use_id: id.to_string(), + tool_name: "bash".to_string(), + output: "ok".to_string(), + is_error: false, + }], + usage: None, + }; + let messages = vec![ + ConversationMessage::user_text("hello"), + ConversationMessage::assistant(vec![tool_use("tool-1"), tool_use("tool-2")]), + tool_result("tool-1"), + tool_result("tool-2"), + ]; + + let converted = super::convert_messages(&messages); + + // one user turn, one assistant turn, and ONE user message carrying both + // results: the API requires every tool_use of a turn to be answered in + // the message immediately after it. + assert_eq!(converted.len(), 3, "converted messages: {converted:?}"); + assert_eq!(converted[1].role, "assistant"); + assert_eq!(converted[2].role, "user"); + let answered = converted[2] + .content + .iter() + .filter_map(|block| match block { + InputContentBlock::ToolResult { tool_use_id, .. } => Some(tool_use_id.as_str()), + _ => None, + }) + .collect::>(); + assert_eq!(answered, vec!["tool-1", "tool-2"]); + } #[test] fn repl_help_mentions_history_completion_and_multiline() { let help = render_repl_help(); From 2c119daae12f85e5a25743b4fdd8e6459363af74 Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 02:21:10 +0800 Subject: [PATCH 04/10] docs(roadmap): file pinpoint 835 for the parallel tool-result pairing fix Records the reported symptom, the root cause, the fix, and the verification that fails against the pre-fix code. Id 835 is the next free id from `scripts/roadmap-next-id.sh`. (cherry picked from commit 9af3c77090df85f0ac35ad5603091732099e4db1) --- ROADMAP.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ROADMAP.md b/ROADMAP.md index 39f8cd4748..307fc4432d 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -8018,3 +8018,7 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed) 834. **DONE — Local-model syntax bypass only covered Ollama-shaped tags, not bare LM Studio/llama.cpp aliases** — follow-up to #833/PR #3213. `is_local_openai_model_syntax()` waived strict `provider/model` syntax under `OPENAI_BASE_URL` only when the model name contained a `.` or `:` (Ollama-tag-shaped). A local server registering a model under a bare alias with none of those characters — for example an LM Studio custom name or a llama.cpp `--alias` value like `mistral` — still failed CLI-parse-time validation unless the user discovered the `local/` prefix workaround. Fix: (1) `is_local_openai_compatible_base_url()` in `openai_compat.rs`, already used to waive the API-key requirement for loopback/private-network base URLs, is now `pub` and re-exported from the `api` crate root; (2) `is_local_openai_model_syntax()` in `rusty-claude-cli`'s `main.rs` calls it against the configured `OPENAI_BASE_URL` and accepts any non-empty model name when the host is local/private, matching the existing `OLLAMA_HOST` bypass; (3) remote/hosted `OPENAI_BASE_URL` gateways keep the stricter dot/colon-tag heuristic so a mistyped bare name doesn't silently route to a paid hosted API; (4) `local/` remains the explicit escape hatch for slash-containing IDs regardless of host; (5) added an LM Studio section and updated routing notes in `docs/local-openai-compatible-providers.md`. [SCOPE: claw-code] **Verification.** `scripts/fmt.sh --check`; `cargo clippy --manifest-path rust/Cargo.toml --workspace --all-targets -- -D warnings`; `cargo test --manifest-path rust/Cargo.toml --workspace`; new tests `local_openai_base_url_bypasses_bare_model_names`, `private_network_openai_base_url_bypasses_bare_model_names`, and `remote_openai_base_url_still_requires_provider_model_or_tag_syntax` in `rusty-claude-cli`'s `alias_resolution_tests` module; `is_local_openai_compatible_base_url_is_reachable_via_crate_root` in `api`'s `client.rs` confirming the re-export. + +835. **DONE — Parallel tool-call turns sent `tool_result` blocks one message too late** — found while investigating a live `claw` REPL failure that returned `api returned 400 Bad Request (invalid_request_error): messages.3: tool_use ids were found without tool_result blocks immediately after: call_01_4QJqcZ0075kla1ILwra75582`. `runtime` records one `MessageRole::Tool` message per tool call, and `convert_messages()` in `rusty-claude-cli`'s `main.rs` turned each of them into its own wire message. The Anthropic Messages API requires *every* `tool_use` of an assistant message to be answered by `tool_result` blocks **in the single message immediately after it**, so when a turn issued two tool calls at once the first result was paired and the second arrived one message late — the provider rejected the whole request. Single-call turns were unaffected, which is why the defect only showed up when the model requested parallel tools. Fix: (1) `convert_messages()` is split into a per-message `convert_message()` plus a folding accumulator `absorb_tool_result_message()`; (2) a run of adjacent tool-result messages now merges into the one `user` message that follows the assistant turn, matching what the API requires; (3) the merge only extends a message that carries tool results and nothing else, so user text and assistant turns can never be joined; (4) `converts_tool_roundtrip_messages` keeps its previous single-call contract. Evidence for the reported failure: `.claw/sessions/e49619b247aa3fce/session-1792170907799-0.jsonl`, whose step-1 assistant message carries two `tool_use` blocks followed by two separate tool-result messages. [SCOPE: claw-code] + + **Verification.** New unit test `converts_parallel_tool_call_results_into_one_paired_message` in `rusty-claude-cli`'s `main.rs` asserts both ids are answered in one message and in call order; new integration test `rust/crates/rusty-claude-cli/tests/parallel_tool_result_pairing.rs` drives the real `claw` binary against the mock Anthropic service for the `multi_tool_turn_roundtrip` scenario and asserts the wire contract on the captured request bodies. Run against the pre-fix implementation that integration test fails with the payload behind the live 400 (`assistant["tool_use", "tool_use"]` followed by `user["tool_result"]`, `user["tool_result"]`; only `toolu_multi_read` answered). It lives in `tests/` rather than unit-test scope so it can be reverted independently of the fix. `scripts/fmt.sh --check`; `cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli`; `cargo clippy --manifest-path rust/Cargo.toml --workspace --all-targets -- -D warnings` reports no findings in the changed crates. From 2ce1a7b61696cc9b0d3fbf223e76c756dbeb89b5 Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 02:21:26 +0800 Subject: [PATCH 05/10] fix(sdk): name terminal-scope records from a bounded path component MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `TerminalScopeStore::record_path` expanded the correlation key into full hex and chunked it into 180-byte path components. A maximal 512-byte key expands to 1024 hex characters, so the generated path ran past the 1024-byte total-path limit enforced by APFS and `set`/`get` failed with ENAMETOOLONG: read terminal scope '…/6b6b…(1024 hex chars)….json': File name too long (os error 63) The misleading part is where the limit lives: every component stayed within the 255-byte filename limit (five 180-byte directories plus a 129-byte leaf), so the errno named a generated leaf name the caller never chose, and shrinking the chunk cannot help because the hex expansion stays 1024 characters however it is split. The same code passes on Linux, where `PATH_MAX` is 4096, so the `cargo test --workspace` job on ubuntu-latest could not catch it. Fix: records are named from a fixed-width SHA-256 digest (`<32 hex>.json`) and the multi-level chunking is gone. The full key still lives in `TerminalScopeRecord::correlation_key` and is still checked on read, so `encoded_keys_are_isolated_and_cannot_traverse_paths` keeps holding. `sha2` joins the crate's dependencies, reusing the version `runtime` already pulls, so `Cargo.lock` gains one line. The regression test now asserts on the path shape (longest component ≤ 255 bytes, total path < 1024 bytes) instead of only round-tripping, because a round trip inside a short temporary root succeeds even when the generated path is unusable in practice. Verification: `cargo test -p sdk` (119 unit tests, 12 + 109 integration); `scripts/fmt.sh --check`; the new assertion fails against the pre-fix code. (cherry picked from commit 07f020f252e83da3b1190a4fea06809a5085af76) --- rust/Cargo.lock | 1 + rust/crates/sdk/Cargo.toml | 1 + rust/crates/sdk/src/session/terminal_scope.rs | 68 +++++++++++++++---- 3 files changed, 55 insertions(+), 15 deletions(-) diff --git a/rust/Cargo.lock b/rust/Cargo.lock index f1a614a40c..2373a86d9a 100644 --- a/rust/Cargo.lock +++ b/rust/Cargo.lock @@ -2340,6 +2340,7 @@ dependencies = [ "runtime", "serde", "serde_json", + "sha2", "tempfile", "tokio", "tokio-tungstenite", diff --git a/rust/crates/sdk/Cargo.toml b/rust/crates/sdk/Cargo.toml index f542a96cde..d23aeba4f6 100644 --- a/rust/crates/sdk/Cargo.toml +++ b/rust/crates/sdk/Cargo.toml @@ -14,6 +14,7 @@ uuid = { version = "1", features = ["v4", "serde"] } tracing = "0.1" url = "2" runtime = { path = "../runtime" } +sha2 = "0.10" [dev-dependencies] tempfile = "3" diff --git a/rust/crates/sdk/src/session/terminal_scope.rs b/rust/crates/sdk/src/session/terminal_scope.rs index d15acaf8c0..821076040e 100644 --- a/rust/crates/sdk/src/session/terminal_scope.rs +++ b/rust/crates/sdk/src/session/terminal_scope.rs @@ -8,6 +8,7 @@ use std::{ }; use serde::{Deserialize, Serialize}; +use sha2::{Digest, Sha256}; use crate::error::{SdkError, SdkResult}; @@ -135,18 +136,17 @@ impl TerminalScopeStore { Ok(Some(record)) } + /// Builds the record path for a correlation key. + /// + /// Files are named from a fixed-width digest instead of the key's hex + /// expansion: a maximal 512-byte key expands to 1024 hex characters, which + /// overflows the 1024-byte total-path limit enforced by APFS before any + /// chunking can help, and `File name too long` would be reported for a + /// generated leaf name the caller never chose. The key itself is still + /// stored in `TerminalScopeRecord::correlation_key` and checked on read. fn record_path(&self, correlation_key: &str) -> PathBuf { - const MAX_COMPONENT_BYTES: usize = 180; - let encoded = encode_key_as_hex(correlation_key); - let mut path = self.root.clone(); - let mut remaining = encoded.as_str(); - while remaining.len() > MAX_COMPONENT_BYTES { - let (component, tail) = remaining.split_at(MAX_COMPONENT_BYTES); - path.push(component); - remaining = tail; - } - path.push(format!("{remaining}.json")); - path + self.root + .join(format!("{}.json", encode_key_for_path(correlation_key))) } } @@ -158,10 +158,14 @@ fn validate_correlation_key(correlation_key: &str) -> SdkResult<()> { } } -fn encode_key_as_hex(key: &str) -> String { +/// Encodes a correlation key as a fixed-width filesystem-safe path component. +fn encode_key_for_path(key: &str) -> String { const HEX_DIGITS: &[u8; 16] = b"0123456789abcdef"; - let mut encoded = String::with_capacity(key.len() * 2); - for byte in key.as_bytes() { + let digest = Sha256::digest(key.as_bytes()); + // The first 16 bytes are far more than the number of records one store + // holds, and the full key survives in the record for exact matching. + let mut encoded = String::with_capacity(32); + for byte in digest.iter().take(16) { encoded.push(char::from(HEX_DIGITS[usize::from(*byte >> 4)])); encoded.push(char::from(HEX_DIGITS[usize::from(*byte & 0x0f)])); } @@ -180,6 +184,7 @@ fn current_timestamp_ms() -> u64 { mod tests { use super::*; use std::fs; + use std::path::Component; use uuid::Uuid; struct TestDirectory(PathBuf); @@ -279,7 +284,7 @@ mod tests { let store = TerminalScopeStore::new(&root.0); let path = root .0 - .join(format!("{}.json", encode_key_as_hex("request"))); + .join(format!("{}.json", encode_key_for_path("request"))); fs::write(path, "{").expect("write malformed scope"); assert!(store.get("request").is_err()); } @@ -296,6 +301,39 @@ mod tests { store.get(&key).expect("get long key").unwrap().session_id, "session-long" ); + + // A maximum-length key is 1024 hex characters. Expanding it into the + // path used to exceed the filesystem's total-path limit, so assert on + // the path shape rather than only on the round trip: the store works in + // a short temporary root even when the generated path is unusable. + let record_path = single_record_path(&root.0); + let longest_component = record_path + .components() + .filter_map(|component| match component { + Component::Normal(part) => Some(part.to_string_lossy().len()), + _ => None, + }) + .max() + .expect("record path has a component"); + assert!( + longest_component <= 255, + "path component must stay within the filesystem filename limit, got {longest_component}" + ); + assert!( + record_path.as_os_str().len() < 1024, + "record path must stay within the APFS total-path limit, got {} bytes", + record_path.as_os_str().len() + ); + } + + /// Returns the single record file under a store root. + fn single_record_path(root: &std::path::Path) -> PathBuf { + let entries = fs::read_dir(root) + .expect("read store root") + .collect::, _>>() + .expect("read store entries"); + assert_eq!(entries.len(), 1, "store should hold exactly one record"); + entries[0].path() } #[test] From 49dcedd5959d1d2403326b528a68caa6ad160f48 Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 02:21:27 +0800 Subject: [PATCH 06/10] docs(roadmap): file pinpoint 836 for the terminal-scope path fix Records the symptom, why the errno pointed at a harmless-looking leaf name, why CI could not see it, and the verification that fails against the pre-fix code. (cherry picked from commit 1a66aadbcdf43392842c716b3899f7e33f3fd960) --- ROADMAP.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ROADMAP.md b/ROADMAP.md index 307fc4432d..511ed77ce8 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -8022,3 +8022,7 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed) 835. **DONE — Parallel tool-call turns sent `tool_result` blocks one message too late** — found while investigating a live `claw` REPL failure that returned `api returned 400 Bad Request (invalid_request_error): messages.3: tool_use ids were found without tool_result blocks immediately after: call_01_4QJqcZ0075kla1ILwra75582`. `runtime` records one `MessageRole::Tool` message per tool call, and `convert_messages()` in `rusty-claude-cli`'s `main.rs` turned each of them into its own wire message. The Anthropic Messages API requires *every* `tool_use` of an assistant message to be answered by `tool_result` blocks **in the single message immediately after it**, so when a turn issued two tool calls at once the first result was paired and the second arrived one message late — the provider rejected the whole request. Single-call turns were unaffected, which is why the defect only showed up when the model requested parallel tools. Fix: (1) `convert_messages()` is split into a per-message `convert_message()` plus a folding accumulator `absorb_tool_result_message()`; (2) a run of adjacent tool-result messages now merges into the one `user` message that follows the assistant turn, matching what the API requires; (3) the merge only extends a message that carries tool results and nothing else, so user text and assistant turns can never be joined; (4) `converts_tool_roundtrip_messages` keeps its previous single-call contract. Evidence for the reported failure: `.claw/sessions/e49619b247aa3fce/session-1792170907799-0.jsonl`, whose step-1 assistant message carries two `tool_use` blocks followed by two separate tool-result messages. [SCOPE: claw-code] **Verification.** New unit test `converts_parallel_tool_call_results_into_one_paired_message` in `rusty-claude-cli`'s `main.rs` asserts both ids are answered in one message and in call order; new integration test `rust/crates/rusty-claude-cli/tests/parallel_tool_result_pairing.rs` drives the real `claw` binary against the mock Anthropic service for the `multi_tool_turn_roundtrip` scenario and asserts the wire contract on the captured request bodies. Run against the pre-fix implementation that integration test fails with the payload behind the live 400 (`assistant["tool_use", "tool_use"]` followed by `user["tool_result"]`, `user["tool_result"]`; only `toolu_multi_read` answered). It lives in `tests/` rather than unit-test scope so it can be reverted independently of the fix. `scripts/fmt.sh --check`; `cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli`; `cargo clippy --manifest-path rust/Cargo.toml --workspace --all-targets -- -D warnings` reports no findings in the changed crates. + +836. **DONE — Terminal-scope record paths exceeded the filesystem path limit for long correlation keys** — `TerminalScopeStore::record_path()` in the `sdk` crate expanded the correlation key into full hex and chunked it into 180-byte path components. A maximal 512-byte key expands to 1024 hex characters, so the generated path ran past the 1024-byte total-path limit enforced by APFS and `set()`/`get()` failed with `File name too long (os error 63)`. The misleading part is where the limit lives: every component stayed within the 255-byte filename limit (five 180-byte directories plus a 129-byte leaf), so the errno named a generated leaf name the caller never chose, and lowering the chunk size cannot help because the hex expansion stays 1024 characters however it is split. The same code passes on Linux, where `PATH_MAX` is 4096, so `cargo test --workspace` on the ubuntu-latest CI job could not catch it. Fix: (1) `record_path()` now names records from a fixed-width SHA-256 digest (`<32 hex>.json`) and the multi-level chunking is gone; (2) the full key still lives in `TerminalScopeRecord::correlation_key` and is still checked on read, so `encoded_keys_are_isolated_and_cannot_traverse_paths` keeps holding; (3) `encode_key_as_hex()` is replaced by `encode_key_for_path()`; (4) `sha2` joins the `sdk` dependencies, reusing the version `runtime` already pulls so `Cargo.lock` gains one line. [SCOPE: claw-code] + + **Verification.** `long_hex_keys_use_safe_path_components` now asserts on the path shape (longest component ≤ 255 bytes, total path < 1024 bytes) instead of only round-tripping, because a round trip inside a short temporary root succeeds even when the generated path is unusable in practice. That assertion fails against the pre-fix implementation with the recorded error above. `cargo test --manifest-path rust/Cargo.toml -p sdk`; `scripts/fmt.sh --check`; `cargo clippy --manifest-path rust/Cargo.toml --workspace --all-targets -- -D warnings` reports no findings in the changed crates. From 891e4ba79a17daa0b60f25e5dbff8984a838db03 Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 02:21:44 +0800 Subject: [PATCH 07/10] docs(runtime): document the test-only MCP handshake budgets The `#[cfg(test)]` budgets (200ms/300ms against production 10s/30s) are deliberately short so the scripted stdio fixtures finish quickly, but they are also why the default parallel `cargo test --workspace` reports failures in `mcp_stdio::tests` and `mcp_tool_bridge::tests`: the fixtures are real `python3` children (cold start measured at 18-21ms here), and a dozen of them starting at once spends the budget on process startup alone. The comment records the shape of the failure, the `--test-threads=1` workaround, and why the budgets stay short, so the next reader does not misread a scheduling artifact as a product defect. (cherry picked from commit f058e845196fdb2f8c33eef7b94dd6056c00c6f3) --- rust/crates/runtime/src/mcp_stdio.rs | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/rust/crates/runtime/src/mcp_stdio.rs b/rust/crates/runtime/src/mcp_stdio.rs index b05ea44717..35efa7eecd 100644 --- a/rust/crates/runtime/src/mcp_stdio.rs +++ b/rust/crates/runtime/src/mcp_stdio.rs @@ -18,11 +18,24 @@ use crate::mcp_lifecycle_hardened::{ McpDegradedReport, McpErrorSurface, McpFailedServer, McpLifecyclePhase, }; +// Test builds shrink the production handshake budgets (10s/30s) so that cases +// using the scripted stdio fixture finish quickly. The fixture is a real +// `python3` child, whose cold start measures 18-21ms here, so 200ms/300ms is +// roughly 10x headroom and enough when these tests run serially +// (`--test-threads=1`); under the default parallel run a dozen fixture children +// start at once and the budget runs out, which shows up as +// `Timeout { method: "initialize", timeout_ms: 200 }` failures across +// `mcp_stdio::tests` and `mcp_tool_bridge::tests` (ROADMAP #837). Re-run with +// `--test-threads=1` before treating those failures as a regression: the suite +// is green that way. Keep the budgets short rather than generous so a real +// handshake slowdown still fails fast; production keeps its own values. #[cfg(test)] const MCP_INITIALIZE_TIMEOUT_MS: u64 = 200; #[cfg(not(test))] const MCP_INITIALIZE_TIMEOUT_MS: u64 = 10_000; +// `MCP_LIST_TOOLS_TIMEOUT_MS` below shares the test-only shrink and the parallel +// caveat described here. #[cfg(test)] const MCP_LIST_TOOLS_TIMEOUT_MS: u64 = 300; #[cfg(not(test))] From 9a55803d7deb95c89f71ab4c266c10e5acf345a7 Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 02:21:44 +0800 Subject: [PATCH 08/10] docs(roadmap): file 837 for the MCP fixture flake and its serial workaround KNOWN FLAKE (not fixed): records the cause, the measured numbers, why only the two in-crate unit-test modules go red, and the deliberate decision to keep the budgets short rather than widen them for parallel tolerance. This branch also carries pinpoints 835 and 836, which document fixes landing on their own branches: the roadmap is append-only, so the three entries are filed together to keep ROADMAP.md touched by a single PR. (cherry picked from commit 7cb24826ff23f2c1bd8e8a6518363ffe205d36db) --- ROADMAP.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/ROADMAP.md b/ROADMAP.md index 511ed77ce8..13f35b1a3f 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -8026,3 +8026,9 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed) 836. **DONE — Terminal-scope record paths exceeded the filesystem path limit for long correlation keys** — `TerminalScopeStore::record_path()` in the `sdk` crate expanded the correlation key into full hex and chunked it into 180-byte path components. A maximal 512-byte key expands to 1024 hex characters, so the generated path ran past the 1024-byte total-path limit enforced by APFS and `set()`/`get()` failed with `File name too long (os error 63)`. The misleading part is where the limit lives: every component stayed within the 255-byte filename limit (five 180-byte directories plus a 129-byte leaf), so the errno named a generated leaf name the caller never chose, and lowering the chunk size cannot help because the hex expansion stays 1024 characters however it is split. The same code passes on Linux, where `PATH_MAX` is 4096, so `cargo test --workspace` on the ubuntu-latest CI job could not catch it. Fix: (1) `record_path()` now names records from a fixed-width SHA-256 digest (`<32 hex>.json`) and the multi-level chunking is gone; (2) the full key still lives in `TerminalScopeRecord::correlation_key` and is still checked on read, so `encoded_keys_are_isolated_and_cannot_traverse_paths` keeps holding; (3) `encode_key_as_hex()` is replaced by `encode_key_for_path()`; (4) `sha2` joins the `sdk` dependencies, reusing the version `runtime` already pulls so `Cargo.lock` gains one line. [SCOPE: claw-code] **Verification.** `long_hex_keys_use_safe_path_components` now asserts on the path shape (longest component ≤ 255 bytes, total path < 1024 bytes) instead of only round-tripping, because a round trip inside a short temporary root succeeds even when the generated path is unusable in practice. That assertion fails against the pre-fix implementation with the recorded error above. `cargo test --manifest-path rust/Cargo.toml -p sdk`; `scripts/fmt.sh --check`; `cargo clippy --manifest-path rust/Cargo.toml --workspace --all-targets -- -D warnings` reports no findings in the changed crates. + +837. **KNOWN FLAKE (not fixed) — MCP stdio fixtures exceed their test-only handshake budget under the default parallel test run** — found while establishing a green baseline for #835/#836. `cargo test --workspace` (the command [rust-ci.yml](.github/workflows/rust-ci.yml) runs, with no thread limit) reports 10-11 failures in `runtime`'s `mcp_stdio::tests` and `mcp_tool_bridge::tests` on this machine, all of the shape `Timeout { server_name: "alpha", method: "initialize", timeout_ms: 200 }`. Cause: `mcp_stdio.rs` halves the production handshake budgets for test builds only — `MCP_INITIALIZE_TIMEOUT_MS` 200ms vs 10_000ms, `MCP_LIST_TOOLS_TIMEOUT_MS` 300ms vs 30_000ms — while the tests drive a real `python3` stdio fixture whose cold start measures 18-21ms (`min=18 max=21 avg=20` over 10 runs). That is ~10x headroom when the tests run serially, but the default run starts a dozen fixture children at once and the budget is consumed by process startup alone. The `#[cfg(test)]` gate is why the impact is bounded: integration targets such as `runtime/tests/*.rs` link the non-test library and therefore use the production budgets, which is why only the two in-crate unit-test modules go red — no production path is affected, and no CLI or harness behavior depends on these values. [SCOPE: claw-code] + + **Disposition.** The budget constants were deliberately left unchanged: shortening them is what makes a real handshake regression fail fast, so widening them to buy parallel tolerance trades away the guard those cases exist for. Instead the cause is documented where the numbers are read, and this item records it for claws that hit the failures and misread them as a product defect. This mirrors the existing documented-but-unfixed items in this roadmap (for example the `clippy` job running without `-D warnings`). + + **How to read it.** Re-run with `--test-threads=1` before treating those failures as a regression. On the same machine and commit: `cargo test --workspace` (parallel) = 11 failed / 1792 passed; `cargo test --workspace -- --test-threads=1` = **0 failed / 1803 passed / 1 ignored**; `cargo test -p runtime --lib -- --test-threads=1` = 721 passed; `cargo test -p runtime --lib mcp_stdio:: -- --test-threads=1` = 22 passed. The failure set also moves between runs (`mcp_tool_bridge::tests::call_tool_payload_structure` and `manager_times_out_slow_tool_calls` each fail in one run and pass in the next), and libtest aborts in-flight cases when one panics, so the reported `passed` count itself varies between parallel runs — another sign that these are scheduling artifacts rather than deterministic defects. The single `ignored` case is `api/tests/client_integration.rs::live_stream_smoke_test`, which is marked `requires ANTHROPIC_API_KEY and network access`. From 272b2529eff80ee73f45bcfbe9566bfa0f1ab74b Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 02:24:40 +0800 Subject: [PATCH 09/10] fix(api): explain a configured non-Anthropic endpoint in the credential error MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `claw prompt "say hello"` with `ANTHROPIC_BASE_URL=https://api.deepseek.com/ anthropic` and no credential exported reported: missing Anthropic credentials; export ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY before calling the Anthropic API Truthful but misleading. Third-party Anthropic-compatible endpoints accept the `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` names purely as a wire-compatibility convention — the value has to be a credential the endpoint itself issued, and an `sk-ant-` key is rejected — so the message reads as "obtain an Anthropic key" while never mentioning the endpoint the user had already configured. `anthropic_missing_credentials_hint()` sniffed only `FOREIGN_PROVIDER_ENV_VARS` and ignored `ANTHROPIC_BASE_URL`, so users who had already pointed claw at a gateway got the generic wall. Fix: a `custom_anthropic_base_url_hint()` branch fires whenever `ANTHROPIC_BASE_URL` differs from `anthropic::DEFAULT_BASE_URL` (empty and whitespace-only values are ignored), names the configured URL, and explains the variable-name convention. It runs before the foreign-provider loop: a configured endpoint is a fact about what the user asked for, while a presence check on another provider's key only guesses at intent. Base-url resolution reuses `anthropic::read_base_url()` so the hint cannot disagree with the client's own endpoint. Seven pre-existing hint/error tests depended on the ambient `ANTHROPIC_BASE_URL` and failed under a shell that sets it; they now pin the variable explicitly. Verification: `cargo test -p api` (172 unit tests plus four integration targets); `scripts/fmt.sh --check`; the exact failing command now reports the endpoint it was configured with. (cherry picked from commit ae0765758c9a0f91668c3eacf255eae4cdd8a686) --- rust/crates/api/src/providers/mod.rs | 128 +++++++++++++++++++++++++-- 1 file changed, 123 insertions(+), 5 deletions(-) diff --git a/rust/crates/api/src/providers/mod.rs b/rust/crates/api/src/providers/mod.rs index 993a4e7d23..5cf57b617b 100644 --- a/rust/crates/api/src/providers/mod.rs +++ b/rust/crates/api/src/providers/mod.rs @@ -773,12 +773,14 @@ fn env_or_dotenv_present(key: &str) -> bool { } } -/// Produce a hint string describing the first foreign provider credential -/// that is present in the environment when Anthropic auth resolution has -/// just failed. Returns `None` when no foreign credential is set, in which -/// case the caller should fall back to the plain `missing_credentials` -/// error without a hint. +/// Produce a hint string describing the most probable reason Anthropic auth +/// resolution just failed. Returns `None` when nothing in the environment +/// explains the failure, in which case the caller should fall back to the +/// plain `missing_credentials` error without a hint. pub(crate) fn anthropic_missing_credentials_hint() -> Option { + if let Some(hint) = custom_anthropic_base_url_hint() { + return Some(hint); + } for (env_var, provider_label, fix_hint) in FOREIGN_PROVIDER_ENV_VARS { if env_or_dotenv_present(env_var) { return Some(format!( @@ -789,6 +791,34 @@ pub(crate) fn anthropic_missing_credentials_hint() -> Option { None } +/// Hint for the case where `ANTHROPIC_BASE_URL` points at something other than +/// the Anthropic API. +/// +/// Third-party Anthropic-compatible endpoints (DeepSeek's `/anthropic` path, +/// corporate gateways, local proxies) authenticate with the `ANTHROPIC_API_KEY` +/// and `ANTHROPIC_AUTH_TOKEN` variable names purely by wire-compatibility +/// convention, so the standard missing-credential message reads as "go get an +/// Anthropic key" when the user in fact needs a credential issued by the +/// endpoint they already configured. Nothing in that message mentions the base +/// URL, which is the one piece of configuration the user deliberately set. +/// +/// This takes precedence over the foreign-provider hints: a configured endpoint +/// is a fact about what the user asked for, while a presence check on another +/// provider's key only guesses at intent. +fn custom_anthropic_base_url_hint() -> Option { + let base_url = anthropic::read_base_url(); + let base_url = base_url.trim(); + if base_url.is_empty() || base_url == anthropic::DEFAULT_BASE_URL { + return None; + } + Some(format!( + "ANTHROPIC_BASE_URL is set to {base_url}, which is not the Anthropic API. \ + The ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN variable names are a \ + compatibility convention — this endpoint expects a credential it issued \ + itself, not an Anthropic key." + )) +} + /// Build an Anthropic-specific `MissingCredentials` error, attaching a /// hint suggesting the probable fix whenever a different provider's /// credentials are already present in the environment. Anthropic call @@ -1688,6 +1718,7 @@ NO_EQUALS_LINE let _openai = EnvVarGuard::set("OPENAI_API_KEY", None); let _xai = EnvVarGuard::set("XAI_API_KEY", None); let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set("ANTHROPIC_BASE_URL", None); // when let hint = anthropic_missing_credentials_hint(); @@ -1699,6 +1730,86 @@ NO_EQUALS_LINE ); } + #[test] + fn anthropic_missing_credentials_hint_names_a_custom_base_url() { + // given + let _lock = env_lock(); + let _openai = EnvVarGuard::set("OPENAI_API_KEY", None); + let _xai = EnvVarGuard::set("XAI_API_KEY", None); + let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set( + "ANTHROPIC_BASE_URL", + Some("https://api.deepseek.com/anthropic"), + ); + + // when + let hint = anthropic_missing_credentials_hint() + .expect("a configured non-Anthropic endpoint should produce a hint"); + + // then + assert!( + hint.contains("https://api.deepseek.com/anthropic"), + "hint should name the configured endpoint so the user recognizes their own setting: {hint}" + ); + assert!( + hint.contains("not the Anthropic API"), + "hint should state that the endpoint is not Anthropic: {hint}" + ); + assert!( + hint.contains("ANTHROPIC_API_KEY") && hint.contains("ANTHROPIC_AUTH_TOKEN"), + "hint should keep naming the env vars that carry the credential: {hint}" + ); + } + + #[test] + fn anthropic_missing_credentials_hint_prefers_custom_base_url_over_foreign_creds() { + // given + let _lock = env_lock(); + let _openai = EnvVarGuard::set("OPENAI_API_KEY", Some("sk-openrouter-varleg")); + let _xai = EnvVarGuard::set("XAI_API_KEY", None); + let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set( + "ANTHROPIC_BASE_URL", + Some("https://api.deepseek.com/anthropic"), + ); + + // when + let hint = anthropic_missing_credentials_hint() + .expect("a configured non-Anthropic endpoint should produce a hint"); + + // then + assert!( + hint.contains("ANTHROPIC_BASE_URL"), + "the endpoint the user configured is a fact and should win over a guess about intent: {hint}" + ); + assert!( + !hint.contains("openai/"), + "the foreign-provider routing hint should not displace the base-url hint: {hint}" + ); + } + + #[test] + fn anthropic_missing_credentials_hint_is_none_for_the_default_base_url() { + // given + let _lock = env_lock(); + let _openai = EnvVarGuard::set("OPENAI_API_KEY", None); + let _xai = EnvVarGuard::set("XAI_API_KEY", None); + let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set( + "ANTHROPIC_BASE_URL", + Some(super::anthropic::DEFAULT_BASE_URL), + ); + + // when + let hint = anthropic_missing_credentials_hint(); + + // then + assert!( + hint.is_none(), + "pointing at the real Anthropic API should not produce a base-url hint, got {hint:?}" + ); + } + #[test] fn anthropic_missing_credentials_hint_detects_openai_api_key_and_recommends_openai_prefix() { // given @@ -1706,6 +1817,7 @@ NO_EQUALS_LINE let _openai = EnvVarGuard::set("OPENAI_API_KEY", Some("sk-openrouter-varleg")); let _xai = EnvVarGuard::set("XAI_API_KEY", None); let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set("ANTHROPIC_BASE_URL", None); // when let hint = anthropic_missing_credentials_hint() @@ -1737,6 +1849,7 @@ NO_EQUALS_LINE let _openai = EnvVarGuard::set("OPENAI_API_KEY", None); let _xai = EnvVarGuard::set("XAI_API_KEY", Some("xai-test-key")); let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set("ANTHROPIC_BASE_URL", None); // when let hint = anthropic_missing_credentials_hint() @@ -1764,6 +1877,7 @@ NO_EQUALS_LINE let _openai = EnvVarGuard::set("OPENAI_API_KEY", None); let _xai = EnvVarGuard::set("XAI_API_KEY", None); let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", Some("sk-dashscope-test")); + let _base_url = EnvVarGuard::set("ANTHROPIC_BASE_URL", None); // when let hint = anthropic_missing_credentials_hint() @@ -1791,6 +1905,7 @@ NO_EQUALS_LINE let _openai = EnvVarGuard::set("OPENAI_API_KEY", Some("sk-openrouter-varleg")); let _xai = EnvVarGuard::set("XAI_API_KEY", Some("xai-test-key")); let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", Some("sk-dashscope-test")); + let _base_url = EnvVarGuard::set("ANTHROPIC_BASE_URL", None); // when let hint = anthropic_missing_credentials_hint() @@ -1814,6 +1929,7 @@ NO_EQUALS_LINE let _openai = EnvVarGuard::set("OPENAI_API_KEY", None); let _xai = EnvVarGuard::set("XAI_API_KEY", None); let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set("ANTHROPIC_BASE_URL", None); // when let error = anthropic_missing_credentials(); @@ -1848,6 +1964,7 @@ NO_EQUALS_LINE let _openai = EnvVarGuard::set("OPENAI_API_KEY", Some("sk-openrouter-varleg")); let _xai = EnvVarGuard::set("XAI_API_KEY", None); let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set("ANTHROPIC_BASE_URL", None); // when let error = anthropic_missing_credentials(); @@ -1896,6 +2013,7 @@ NO_EQUALS_LINE let _openai = EnvVarGuard::set("OPENAI_API_KEY", Some("")); let _xai = EnvVarGuard::set("XAI_API_KEY", None); let _dashscope = EnvVarGuard::set("DASHSCOPE_API_KEY", None); + let _base_url = EnvVarGuard::set("ANTHROPIC_BASE_URL", None); // when let hint = anthropic_missing_credentials_hint(); From 1d236ec41b9e612cfa9091939e631e728c669610 Mon Sep 17 00:00:00 2001 From: c01dsummer Date: Sat, 17 Oct 2026 02:24:40 +0800 Subject: [PATCH 10/10] docs(roadmap): file pinpoint 838 for the credential-hint fix Pre-registered as 838 because branches for 835/836/837 are already open against the same append-only section. (cherry picked from commit ff347ce6286a926b841d6d80f93f51323b51f7ac) --- ROADMAP.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ROADMAP.md b/ROADMAP.md index 13f35b1a3f..c60a2ee2d0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -8032,3 +8032,7 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed) **Disposition.** The budget constants were deliberately left unchanged: shortening them is what makes a real handshake regression fail fast, so widening them to buy parallel tolerance trades away the guard those cases exist for. Instead the cause is documented where the numbers are read, and this item records it for claws that hit the failures and misread them as a product defect. This mirrors the existing documented-but-unfixed items in this roadmap (for example the `clippy` job running without `-D warnings`). **How to read it.** Re-run with `--test-threads=1` before treating those failures as a regression. On the same machine and commit: `cargo test --workspace` (parallel) = 11 failed / 1792 passed; `cargo test --workspace -- --test-threads=1` = **0 failed / 1803 passed / 1 ignored**; `cargo test -p runtime --lib -- --test-threads=1` = 721 passed; `cargo test -p runtime --lib mcp_stdio:: -- --test-threads=1` = 22 passed. The failure set also moves between runs (`mcp_tool_bridge::tests::call_tool_payload_structure` and `manager_times_out_slow_tool_calls` each fail in one run and pass in the next), and libtest aborts in-flight cases when one panics, so the reported `passed` count itself varies between parallel runs — another sign that these are scheduling artifacts rather than deterministic defects. The single `ignored` case is `api/tests/client_integration.rs::live_stream_smoke_test`, which is marked `requires ANTHROPIC_API_KEY and network access`. + +838. **DONE — Missing-credential message ignored a configured non-Anthropic `ANTHROPIC_BASE_URL`** — dogfooded while running `./target/debug/claw prompt "say hello"` with `ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic` and no credential exported. The error was truthful but misleading: `missing Anthropic credentials; export ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY before calling the Anthropic API` names two env vars that a DeepSeek user does need to set, yet reads as "go obtain an Anthropic key" and never mentions the endpoint the user had already configured. Third-party Anthropic-compatible endpoints (DeepSeek's `/anthropic` path, corporate gateways, local proxies) accept those two variable names only as a wire-compatibility convention: the value must be a credential the endpoint itself issued, and an `sk-ant-` key will be rejected. `anthropic_missing_credentials_hint()` only sniffed `FOREIGN_PROVIDER_ENV_VARS` (`OPENAI_API_KEY` / `XAI_API_KEY` / `DASHSCOPE_API_KEY`) and never looked at `ANTHROPIC_BASE_URL`, so this whole class of user — someone who already knows what to configure — fell through to the generic wall. Fix: (1) a new `custom_anthropic_base_url_hint()` branch returns a hint whenever `ANTHROPIC_BASE_URL` is set to anything other than `anthropic::DEFAULT_BASE_URL` (empty or whitespace-only values are ignored); (2) the hint names the configured URL, states it is not the Anthropic API, and explains the variable-name convention; (3) the branch runs before the foreign-provider loop, because a configured endpoint is a fact about what the user asked for while a presence check on another provider's key only guesses at intent; (4) base-url resolution reuses `anthropic::read_base_url()` so the hint can never disagree with the client's own endpoint. [SCOPE: claw-code] + + **Verification.** Reproduced the exact command with the fix: the error now carries a third line naming `https://api.deepseek.com/anthropic`. New tests `anthropic_missing_credentials_hint_names_a_custom_base_url` (asserts the URL, the "not the Anthropic API" claim, and that both credential variable names survive), `anthropic_missing_credentials_hint_prefers_custom_base_url_over_foreign_creds` (pins the precedence rule against a regression, since both hints can apply at once), and `anthropic_missing_credentials_hint_is_none_for_the_default_base_url`. Seven pre-existing hint/error tests previously depended on the ambient `ANTHROPIC_BASE_URL` and now pin it explicitly, so they no longer pass or fail according to the developer's shell. `cargo test -p api` (172 unit tests plus the four integration targets); `scripts/fmt.sh --check`.