From 108cbd1a8a5675725749b8168e59d0e70c0c59b5 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 10:26:54 +0000 Subject: [PATCH 1/7] tools: declare an Effect per tool and derive replay/mutation from it First step of the capability architecture upgrade. Each tool now declares one Effect (read/fetch/session/write/mutate/exec) and a Recovery (replay/inspect); replay_safe() and mutates() are derived from them, so plan mode, subagent hooks and crash recovery behave exactly as before. tool_intent records also carry the effect (older files load unchanged). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014BrrmT45MDfJYo6atYUqsd --- AGENTS.md | 5 +- CONTEXT.md | 12 +++++ Cargo.lock | 2 +- src/agent.rs | 13 +++--- src/effect.rs | 92 +++++++++++++++++++++++++++++++++++++ src/main.rs | 1 + src/session.rs | 17 ++++++- src/subagents/tools.rs | 13 ++++-- src/tools/ask_user.rs | 8 +++- src/tools/bash.rs | 3 ++ src/tools/edit.rs | 3 ++ src/tools/find.rs | 4 +- src/tools/grep.rs | 4 +- src/tools/ls.rs | 4 +- src/tools/memory.rs | 3 ++ src/tools/mod.rs | 36 +++++++++++++-- src/tools/read.rs | 4 +- src/tools/run_code.rs | 4 +- src/tools/session_search.rs | 4 +- src/tools/skill_manage.rs | 3 ++ src/tools/web_fetch.rs | 4 +- src/tools/web_search.rs | 4 +- src/tools/write.rs | 3 ++ 23 files changed, 209 insertions(+), 37 deletions(-) create mode 100644 src/effect.rs diff --git a/AGENTS.md b/AGENTS.md index ac603b1..ef12b38 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,6 +32,7 @@ src/ ├── goal.rs # /goal state machine, prompt templates, verify runner ├── compaction.rs # Context compaction decision and summary prompt ├── history.rs # tool_call↔result pairing + resume repair +├── effect.rs # Effect (read/fetch/session/write/mutate/exec) + Recovery (replay/inspect) per tool ├── attachments.rs # Vision gate: images inline for vision models, path references otherwise ├── prompt.rs # System-prompt assembly (tools section derived from the registry) ├── session.rs # Session JSONL journal: records, append/rewrite, list, export, fork/handoff @@ -91,7 +92,7 @@ Providers/models live in `llm/catalog.rs`; unknown models get generic OpenAI-com [providers.] # base_url / api_key / api_key_env / headers ``` -`/model` rebuilds the client mid-session (refused while busy) and persists via `toml_edit`. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls: each call commits a `tool_intent` record before it runs, so a crashed call is re-run on the next turn if its tool is `replay_safe` (read/grep/find/ls), otherwise marked "may have partially run" (intent committed) or "did not run" (no intent). `/export [path]` merges meta + trace + messages (Markdown if `.md`). `/fork [n]` copies the active history (first n user turns) into a new session, `/handoff ` starts a clean linked session from a note; both record `parent_session` and leave the parent untouched. +`/model` rebuilds the client mid-session (refused while busy) and persists via `toml_edit`. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls: each call commits a `tool_intent` record before it runs, so a crashed call is re-run on the next turn if its tool's recovery is `replay` (read/fetch effects: read/grep/find/ls, web tools), otherwise marked "may have partially run" (intent committed) or "did not run" (no intent). `/export [path]` merges meta + trace + messages (Markdown if `.md`). `/fork [n]` copies the active history (first n user turns) into a new session, `/handoff ` starts a clean linked session from a note; both record `parent_session` and leave the parent untouched. Skills: `~/.agents/skills//SKILL.md` (global, shared with other agents; lowest of the non-bundled), `~/.limbo/skills//SKILL.md` (user) and `/.agents/skills//SKILL.md` (project, wins collisions); daily sessions also see the bundled pack (lowest, unpacked to `~/.limbo/daily/bundled//`) and `~/.limbo/daily/skills/` (highest), coding sessions never do — injected as an `` catalog in the system prompt and invocable via `/ [args]`. @@ -124,6 +125,6 @@ CI (`.github/workflows/ci.yml`) runs exactly these three. ## Adding Things -- **Tool**: implement `Tool` in `src/tools/.rs` (`name`/`description`/`parameters` + `run()`; override `replay_safe`/`mutates`/`program_callable` when needed; resolve paths with `resolve_path`, take `mutation_lock(path)` around writes), add it to `ToolRegistry::core` or `set_daily`, and add tests in the same file +- **Tool**: implement `Tool` in `src/tools/.rs` (`name`/`description`/`parameters` + `run()`; declare its `effect()` (`effect.rs`: read/fetch/session/write/mutate/exec — `replay_safe`/`mutates` derive from it; the default is `exec`), override `recovery`/`program_callable` when needed; resolve paths with `resolve_path`, take `mutation_lock(path)` around writes), add it to `ToolRegistry::core` or `set_daily`, and add tests in the same file - **Web-search backend**: extend `src/tools/web_search.rs`; users pick it with `[web_search] provider` - **Provider/model**: add specs in `llm/catalog.rs`; a new wire format → a new `Dialect` variant plus a module implementing `Decoder` and the request body. User-specific endpoint/key tweaks belong in `[providers.]` config, not the catalog diff --git a/CONTEXT.md b/CONTEXT.md index 6beeb49..b61a318 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -60,6 +60,18 @@ proposals should name modules with these terms. (converging on the latest config model), persist to config.toml. The UI screen is an adapter translating verdicts into chat messages. +## Execution + +- **Effect** — what running a tool does (`effect.rs`): `read` (local + reads), `fetch` (network reads), `session` (only this session's live + state: task board, questions, the `run_code` transport), `write` + (repeatable local writes), `mutate` (other local changes), `exec` + (arbitrary commands). Plan mode and read-only profiles block the + mutating ones (`write`/`mutate`/`exec`). Journaled on each `tool_intent`. +- **Recovery** — what resume does with a call a crash interrupted: + `replay` (re-run it; the default for read/fetch) or `inspect` (do not + re-run; the model is told it may have partially run). + ## Subagents - **Task board** — the delegated work of one main session diff --git a/Cargo.lock b/Cargo.lock index 0cd4933..13e28fa 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1244,7 +1244,7 @@ dependencies = [ [[package]] name = "limbo" -version = "0.4.1" +version = "0.4.2" dependencies = [ "anyhow", "async-trait", diff --git a/src/agent.rs b/src/agent.rs index 7d9a3ca..b96fb82 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -1240,11 +1240,8 @@ impl Agent { let intents: Vec = calls .iter() .map(|tc| { - let safe = self - .registry - .get(tc.name()) - .is_some_and(|t| t.replay_safe()); - session::tool_intent_record(&tc.id, tc.name(), safe) + let tool = self.registry.get(tc.name()); + session::tool_intent_record(&tc.id, tc.name(), tool.as_deref()) }) .collect(); self.journal(&intents); @@ -1702,7 +1699,11 @@ pub(crate) mod tests { )]); agent.messages.push(a); agent.checkpoint(); - agent.journal(&[session::tool_intent_record("w1", "write", false)]); + agent.journal(&[session::tool_intent_record( + "w1", + "write", + Some(&crate::tools::write::WriteTool), + )]); // "crash" here, then resume let resumed = Agent::resume( test_config("http://127.0.0.1:9/v1"), diff --git a/src/effect.rs b/src/effect.rs new file mode 100644 index 0000000..b560618 --- /dev/null +++ b/src/effect.rs @@ -0,0 +1,92 @@ +//! Effect semantics: what running an action does to the world, and how a +//! crashed run of it is recovered. +//! +//! Every tool declares one [`Effect`]. Plan mode, subagent profiles and the +//! session journal all read it instead of asking each tool a yes/no +//! question of their own, and crash recovery picks its [`Recovery`] +//! strategy from it. +//! +//! 🦀 Rust notes +//! - `#[derive(Clone, Copy)]` on a fieldless enum makes it a plain value +//! (like an integer): passing it around copies it, no borrowing needed. +//! - `#[serde(rename_all = "snake_case")]` writes `Effect::Fetch` as +//! `"fetch"` in the session file. + +use serde::{Deserialize, Serialize}; + +/// What an action does when it runs, from harmless to arbitrary. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Effect { + /// Reads local state only (read, grep, find, ls, session_search). + Read, + /// Reads from the network; nothing outside changes (web_fetch, web_search). + Fetch, + /// Changes only this session's own live state: the task board, a + /// question to the user, a `run_code` transport whose sub-calls are + /// gated one by one. + Session, + /// Writes local files, with the same result when repeated (write). + Write, + /// Changes local files or stores in ways a repeat may not undo + /// (edit, memory, skill_manage). + Mutate, + /// Runs arbitrary commands: anything may happen (bash). + Exec, +} + +/// What resume does with a call that was interrupted by a crash. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Recovery { + /// Run it again: repeating it is harmless. + Replay, + /// Do not re-run; the model is told it may have partially run and + /// checks its effects first. + Inspect, +} + +impl Effect { + /// Whether the action can change files or state outside the session + /// (plan mode and read-only profiles block these). + pub fn mutates(self) -> bool { + matches!(self, Effect::Write | Effect::Mutate | Effect::Exec) + } + + /// The recovery an action with this effect gets unless its tool says + /// otherwise: reads replay, everything else is inspected. + pub fn default_recovery(self) -> Recovery { + match self { + Effect::Read | Effect::Fetch => Recovery::Replay, + _ => Recovery::Inspect, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn only_reads_replay_by_default() { + for e in [Effect::Read, Effect::Fetch] { + assert_eq!(e.default_recovery(), Recovery::Replay); + assert!(!e.mutates()); + } + assert!(!Effect::Session.mutates()); + assert_eq!(Effect::Session.default_recovery(), Recovery::Inspect); + for e in [Effect::Write, Effect::Mutate, Effect::Exec] { + assert!(e.mutates()); + assert_eq!(e.default_recovery(), Recovery::Inspect); + } + } + + #[test] + fn serializes_snake_case() { + assert_eq!(serde_json::to_value(Effect::Fetch).unwrap(), "fetch"); + assert_eq!( + serde_json::from_value::("replay".into()).unwrap(), + Recovery::Replay + ); + } +} diff --git a/src/main.rs b/src/main.rs index ef5c253..00c7d04 100644 --- a/src/main.rs +++ b/src/main.rs @@ -19,6 +19,7 @@ mod cli_auth; mod commands; mod compaction; mod config; +mod effect; mod goal; mod headless; mod history; diff --git a/src/session.rs b/src/session.rs index 3b081e7..a949e92 100644 --- a/src/session.rs +++ b/src/session.rs @@ -145,6 +145,9 @@ pub struct ToolIntentRecord { pub name: String, #[serde(default = "unsafe_replay")] pub replay: String, + /// The tool's declared effect (absent in files written before effects). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub effect: Option, #[serde(default)] pub created_at: String, } @@ -202,13 +205,21 @@ fn record(kind: &str, value: impl Serialize) -> Value { Value::Object(out) } -pub fn tool_intent_record(call_id: &str, name: &str, replay_safe: bool) -> Value { +/// The intent a call commits before it runs. `tool` is `None` for a name +/// the registry does not know (recorded as unsafe, no effect). +pub fn tool_intent_record( + call_id: &str, + name: &str, + tool: Option<&dyn crate::tools::Tool>, +) -> Value { + let replay_safe = tool.is_some_and(|t| t.replay_safe()); record( "tool_intent", ToolIntentRecord { call_id: call_id.into(), name: name.into(), replay: if replay_safe { "safe" } else { "unsafe" }.into(), + effect: tool.map(|t| t.effect()), created_at: now_iso(), }, ) @@ -656,7 +667,7 @@ mod tests { meta_patch_record(&patched), queued_record(&q), json!({"type": "future_thing", "x": 1}), - tool_intent_record("c1", "bash", false), + tool_intent_record("c1", "bash", Some(&crate::tools::bash::BashTool)), ], ) .unwrap(); @@ -672,6 +683,8 @@ mod tests { assert_eq!(loaded.messages.len(), 3); assert_eq!(loaded.queue.len(), 1); assert_eq!(loaded.intents[0].call_id, "c1"); + assert_eq!(loaded.intents[0].replay, "unsafe"); + assert_eq!(loaded.intents[0].effect, Some(crate::effect::Effect::Exec)); } #[test] diff --git a/src/subagents/tools.rs b/src/subagents/tools.rs index f738a56..c26777e 100644 --- a/src/subagents/tools.rs +++ b/src/subagents/tools.rs @@ -47,11 +47,16 @@ macro_rules! task_tool { fn parameters(&self) -> Value { $params } - fn replay_safe(&self) -> bool { - $safe + /// Board state only: plan mode may still manage the board. + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Session } - fn mutates(&self) -> bool { - false // plan mode may still manage the board + fn recovery(&self) -> crate::effect::Recovery { + if $safe { + crate::effect::Recovery::Replay + } else { + crate::effect::Recovery::Inspect + } } fn program_callable(&self) -> bool { false diff --git a/src/tools/ask_user.rs b/src/tools/ask_user.rs index bbfa948..8e648c0 100644 --- a/src/tools/ask_user.rs +++ b/src/tools/ask_user.rs @@ -49,8 +49,12 @@ impl Tool for AskUserTool { "required": ["question"], }) } - fn replay_safe(&self) -> bool { - true + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Session + } + /// Asking again after a crash is harmless. + fn recovery(&self) -> crate::effect::Recovery { + crate::effect::Recovery::Replay } async fn run(&self, args: Value, _ctx: &ToolContext) -> ToolResult { if arg_str(&args, "question").is_none_or(|q| q.trim().is_empty()) { diff --git a/src/tools/bash.rs b/src/tools/bash.rs index a6a91b5..a67b337 100644 --- a/src/tools/bash.rs +++ b/src/tools/bash.rs @@ -31,6 +31,9 @@ impl Tool for BashTool { fn name(&self) -> &'static str { "bash" } + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Exec + } fn description(&self) -> String { format!( "Execute a bash command in the current working directory. Returns stdout and stderr. Output is \ diff --git a/src/tools/edit.rs b/src/tools/edit.rs index 1975c9f..9a74fd5 100644 --- a/src/tools/edit.rs +++ b/src/tools/edit.rs @@ -118,6 +118,9 @@ impl Tool for EditTool { fn name(&self) -> &'static str { "edit" } + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Mutate + } fn description(&self) -> String { "Edit a single file using exact text replacement. Every edits[].old_text must match a unique, \ non-overlapping region of the original file. If two changes affect the same block or nearby lines, \ diff --git a/src/tools/find.rs b/src/tools/find.rs index 575d453..ea4376a 100644 --- a/src/tools/find.rs +++ b/src/tools/find.rs @@ -32,8 +32,8 @@ impl Tool for FindTool { "required": ["pattern"], }) } - fn replay_safe(&self) -> bool { - true + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Read } async fn run(&self, args: Value, ctx: &ToolContext) -> ToolResult { diff --git a/src/tools/grep.rs b/src/tools/grep.rs index 954e791..b9c99c8 100644 --- a/src/tools/grep.rs +++ b/src/tools/grep.rs @@ -35,8 +35,8 @@ impl Tool for GrepTool { "required": ["pattern"], }) } - fn replay_safe(&self) -> bool { - true + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Read } async fn run(&self, args: Value, ctx: &ToolContext) -> ToolResult { diff --git a/src/tools/ls.rs b/src/tools/ls.rs index ebf2bbd..60dae6b 100644 --- a/src/tools/ls.rs +++ b/src/tools/ls.rs @@ -32,8 +32,8 @@ impl Tool for LsTool { "required": [], }) } - fn replay_safe(&self) -> bool { - true + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Read } async fn run(&self, args: Value, ctx: &ToolContext) -> ToolResult { diff --git a/src/tools/memory.rs b/src/tools/memory.rs index efb817f..cf9ff91 100644 --- a/src/tools/memory.rs +++ b/src/tools/memory.rs @@ -27,6 +27,9 @@ impl Tool for MemoryTool { fn name(&self) -> &'static str { "memory" } + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Mutate + } fn description(&self) -> String { DESCRIPTION.into() } diff --git a/src/tools/mod.rs b/src/tools/mod.rs index 273ae21..407a6b0 100644 --- a/src/tools/mod.rs +++ b/src/tools/mod.rs @@ -36,6 +36,7 @@ use async_trait::async_trait; use serde_json::{Value, json}; use tokio_util::sync::CancellationToken; +use crate::effect::{Effect, Recovery}; use crate::models::ToolResult; /// Everything a tool call may need besides its arguments. @@ -81,13 +82,23 @@ pub trait Tool: Send + Sync { fn description(&self) -> String; /// JSON Schema of the arguments. fn parameters(&self) -> Value; - /// Read-only tools are re-run after a crash; everything else is not. + /// What running the tool does (see [`crate::effect`]). Unknown tools + /// are treated as arbitrary execution. + fn effect(&self) -> Effect { + Effect::Exec + } + /// What resume does with a call a crash interrupted. + fn recovery(&self) -> Recovery { + self.effect().default_recovery() + } + /// Re-run after a crash (derived from [`Tool::recovery`]). fn replay_safe(&self) -> bool { - false + self.recovery() == Recovery::Replay } - /// Whether the tool can change files or state (blocked in plan mode). + /// Whether the tool can change files or state (blocked in plan mode; + /// derived from [`Tool::effect`]). fn mutates(&self) -> bool { - !self.replay_safe() + self.effect().mutates() } /// Whether a `run_code` program may call it. Tools that drive live /// session state (the task board) stay native tools beside `run_code`. @@ -383,6 +394,23 @@ mod tests { assert_eq!(resolve_path(wd, "/etc/hosts"), PathBuf::from("/etc/hosts")); } + /// The effect table: replay and plan-mode gating follow from it. + #[test] + fn core_tool_effects() { + let reg = ToolRegistry::core(true); + let row = |n: &str| { + let t = reg.get(n).unwrap(); + (t.effect(), t.replay_safe(), t.mutates()) + }; + for n in ["read", "grep", "find", "ls"] { + assert_eq!(row(n), (Effect::Read, true, false), "{n}"); + } + assert_eq!(row("write"), (Effect::Write, false, true)); + assert_eq!(row("edit"), (Effect::Mutate, false, true)); + assert_eq!(row("bash"), (Effect::Exec, false, true)); + assert_eq!(row("run_code"), (Effect::Session, false, false)); + } + #[tokio::test] async fn plan_mode_blocks_mutations() { let mut reg = ToolRegistry::core(true); diff --git a/src/tools/read.rs b/src/tools/read.rs index 250e9eb..5089985 100644 --- a/src/tools/read.rs +++ b/src/tools/read.rs @@ -63,8 +63,8 @@ impl Tool for ReadTool { "required": ["path"], }) } - fn replay_safe(&self) -> bool { - true + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Read } async fn run(&self, args: Value, ctx: &ToolContext) -> ToolResult { diff --git a/src/tools/run_code.rs b/src/tools/run_code.rs index 4d23456..c5a395a 100644 --- a/src/tools/run_code.rs +++ b/src/tools/run_code.rs @@ -264,8 +264,8 @@ impl Tool for RunCodeTool { } /// Its sub-calls go through the registry, which applies plan mode to /// each of them; the transport itself changes nothing. - fn mutates(&self) -> bool { - false + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Session } fn program_callable(&self) -> bool { false diff --git a/src/tools/session_search.rs b/src/tools/session_search.rs index c8600aa..49d4f2e 100644 --- a/src/tools/session_search.rs +++ b/src/tools/session_search.rs @@ -219,8 +219,8 @@ impl Tool for SessionSearchTool { }, }) } - fn replay_safe(&self) -> bool { - true + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Read } async fn run(&self, args: Value, _ctx: &ToolContext) -> ToolResult { if let Some(id) = arg_str(&args, "session_id") diff --git a/src/tools/skill_manage.rs b/src/tools/skill_manage.rs index 2eac0cf..7d4a587 100644 --- a/src/tools/skill_manage.rs +++ b/src/tools/skill_manage.rs @@ -203,6 +203,9 @@ impl Tool for SkillManageTool { fn name(&self) -> &'static str { "skill_manage" } + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Mutate + } fn description(&self) -> String { DESCRIPTION.into() } diff --git a/src/tools/web_fetch.rs b/src/tools/web_fetch.rs index 7dfaf3c..5ceef92 100644 --- a/src/tools/web_fetch.rs +++ b/src/tools/web_fetch.rs @@ -84,8 +84,8 @@ impl Tool for WebFetchTool { "required": ["url"], }) } - fn replay_safe(&self) -> bool { - true + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Fetch } async fn run(&self, args: Value, ctx: &ToolContext) -> ToolResult { let url = arg_str(&args, "url").unwrap_or("").trim().to_string(); diff --git a/src/tools/web_search.rs b/src/tools/web_search.rs index 6347733..8ee8d04 100644 --- a/src/tools/web_search.rs +++ b/src/tools/web_search.rs @@ -206,8 +206,8 @@ impl Tool for WebSearchTool { "required": ["query"], }) } - fn replay_safe(&self) -> bool { - true + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Fetch } async fn run(&self, args: Value, _ctx: &ToolContext) -> ToolResult { let Some(query) = arg_str(&args, "query") diff --git a/src/tools/write.rs b/src/tools/write.rs index 38c8aeb..75da691 100644 --- a/src/tools/write.rs +++ b/src/tools/write.rs @@ -13,6 +13,9 @@ impl Tool for WriteTool { fn name(&self) -> &'static str { "write" } + fn effect(&self) -> crate::effect::Effect { + crate::effect::Effect::Write + } fn description(&self) -> String { "Create or overwrite a file. Use only for new files or complete rewrites.".into() } From 9ed82d5b312c4c41e0eec5463c058a1e6994b726 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 10:32:49 +0000 Subject: [PATCH 2/7] admission: replace ToolHook with an Admission layer of Policies Every call now goes resolve -> admit -> run. Plan mode becomes PlanPolicy (blocks by effect), and the four subagent profile hooks become policies in subagents/policies.rs. Denial texts and visibility are unchanged. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014BrrmT45MDfJYo6atYUqsd --- AGENTS.md | 9 +- CONTEXT.md | 6 ++ src/admission.rs | 125 ++++++++++++++++++++++++ src/main.rs | 1 + src/subagents/mod.rs | 2 +- src/subagents/{hooks.rs => policies.rs} | 86 ++++++++++------ src/subagents/supervisor.rs | 18 ++-- src/tools/mod.rs | 52 +++++----- 8 files changed, 228 insertions(+), 71 deletions(-) create mode 100644 src/admission.rs rename src/subagents/{hooks.rs => policies.rs} (62%) diff --git a/AGENTS.md b/AGENTS.md index ef12b38..8a1db77 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ **Limbo** is a minimal terminal AI coding agent, written in Rust (edition 2024, ratatui + tachyonfx). Users converse with an LLM in a TUI to explore, read, edit, and write code via a small set of tools. `--headless` runs a plain-terminal REPL frontend instead of the TUI (Herdr/script control), `--json` prints one JSON event per line, and `-p ""` runs one turn and exits. -**Tools execute immediately — no confirmation flow, no safety fences.** File tools are not scoped to the workdir (absolute paths and symlinks are honored as-is), there is no sensitive-file skip list, and `bash` runs every command as given (no dangerous-command filter). `ToolRegistry` runs a list of `ToolHook`s before every call (`before_tool` returns `Err` to block; `visible` hides a tool) — empty for the main agent, filled from the profile for subagents. `/plan` is a registry flag (`plan_mode`): only non-mutating tools and read-only bash run, also enforced on Code Mode sub-calls, persisted as `SessionMeta.plan_mode`. +**Tools execute immediately — no confirmation flow, no safety fences.** File tools are not scoped to the workdir (absolute paths and symlinks are honored as-is), there is no sensitive-file skip list, and `bash` runs every command as given (no dangerous-command filter). Every call passes admission (`admission.rs`): `ToolRegistry` runs its `Policy` list in order (`admit` returns `Deny(reason)` to block; `visible` hides a tool) — empty for the main agent, filled from the profile for subagents. `/plan` is a registry flag (`plan_mode`) that puts `PlanPolicy` first: only tools whose effect does not mutate run (bash is blocked), also enforced on Code Mode sub-calls, persisted as `SessionMeta.plan_mode`. The source is commented for people learning Rust (`🦀 Rust notes` blocks); keep that style when adding code. `docs/learning-rust.md` has the reading order. @@ -32,6 +32,7 @@ src/ ├── goal.rs # /goal state machine, prompt templates, verify runner ├── compaction.rs # Context compaction decision and summary prompt ├── history.rs # tool_call↔result pairing + resume repair +├── admission.rs # ActionRequest → Policy → Verdict (Allow/Deny); PlanPolicy ├── effect.rs # Effect (read/fetch/session/write/mutate/exec) + Recovery (replay/inspect) per tool ├── attachments.rs # Vision gate: images inline for vision models, path references otherwise ├── prompt.rs # System-prompt assembly (tools section derived from the registry) @@ -48,9 +49,9 @@ src/ ├── headless.rs # --headless / --json / -p frontends on the same pump ├── subagents/ # mod.rs (task board), supervisor.rs (scheduler, runners, notices), │ # tools.rs (plan_tasks/task_*/answer; child: checkpoint/need/ask_main/finish/propose_task), -│ # profiles.rs (agent profiles + scan), hooks.rs (read-only/no-edit/ +│ # profiles.rs (agent profiles + scan), policies.rs (read-only/no-edit/ │ # allow-list/path claims), worktree.rs (git worktree isolation) -├── tools/ # mod.rs (Tool + ToolHook traits, ToolRegistry, path helpers, per-file mutation locks), +├── tools/ # mod.rs (Tool trait, ToolRegistry, path helpers, per-file mutation locks), │ # truncate.rs, read/write/edit/bash/grep/find/ls, run_code (Code Mode transport), │ # web_search (only when its provider has a key), daily mode only: web_fetch, │ # memory, session_search, ask_user (ends the turn), skill_manage @@ -102,7 +103,7 @@ Single column: status bar (state/elapsed/tokens/model/workdir/queue + goal and C `/goal ` starts closed-loop mode: the first round proposes acceptance command(s) in a `` block; the user confirms (accept / edit / skip), then each round is a full agent turn followed by the verify command. Exit 0 ends the loop; otherwise the failure output is fed back into the next round until `max_rounds`, when a no-tool wrap-up turn summarizes. Goal state persists on `SessionMeta.goal`. Esc during verify kills the subprocess. -Subagents (docs/subagents.md): the main agent's `plan_tasks` creates tasks on the board (suggest mode asks the user first); the supervisor runs each as a child agent with its own session file, gated by profile hooks. Child tools that end the turn (`need`, `ask_main`, `finish`) return `end_turn`. Notices reach the main agent as one subagent steer item; an idle main agent is woken through the background channel. Board records live in the main session file (`type: "task"`), so the board survives restarts; tasks running at exit come back paused. +Subagents (docs/subagents.md): the main agent's `plan_tasks` creates tasks on the board (suggest mode asks the user first); the supervisor runs each as a child agent with its own session file, gated by profile policies. Child tools that end the turn (`need`, `ask_main`, `finish`) return `end_turn`. Notices reach the main agent as one subagent steer item; an idle main agent is woken through the background channel. Board records live in the main session file (`type: "task"`), so the board survives restarts; tasks running at exit come back paused. Daily mode (`limbo daily` / `--daily` / `/daily-mode on|off`, docs/daily-mode.md): a session posture like Code Mode — same loop, a general-assistant system prompt, plus the daily tools; persisted as `SessionMeta.daily_mode`. Memory is a snapshot taken when the agent is built: `USER.md` and `NOTES.md` enter daily prompts only; `memory` writes reach disk at once but the prompt changes only next session (prefix cache stays intact). `/learn` (and the automatic trigger in `learn.rs`) runs a `skill-reviewer` fork subagent whose only write tool is `skill_manage`. diff --git a/CONTEXT.md b/CONTEXT.md index b61a318..007050f 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -68,6 +68,12 @@ proposals should name modules with these terms. (repeatable local writes), `mutate` (other local changes), `exec` (arbitrary commands). Plan mode and read-only profiles block the mutating ones (`write`/`mutate`/`exec`). Journaled on each `tool_intent`. +- **Admission** — the gate every action passes before it runs + (`admission.rs`): an **action request** (tool, arguments, effect) goes + through the registry's **policies** in order and the first `Deny` + wins; its reason is the error result the model reads. Plan mode is + `PlanPolicy`; subagent profiles add read-only / no-edit / allow-list / + path-claim policies (`subagents/policies.rs`). - **Recovery** — what resume does with a call a crash interrupted: `replay` (re-run it; the default for read/fetch) or `inspect` (do not re-run; the model is told it may have partially run). diff --git a/src/admission.rs b/src/admission.rs new file mode 100644 index 0000000..a70ee1e --- /dev/null +++ b/src/admission.rs @@ -0,0 +1,125 @@ +//! Admission: the one gate every action passes before it runs. +//! +//! A [`Policy`] looks at an [`ActionRequest`] (which tool, its arguments, +//! its declared [`Effect`]) and admits or denies it. Plan mode is a policy +//! ([`PlanPolicy`]), and so is every subagent profile restriction +//! (`subagents/policies.rs`). The tool registry runs the policies in order +//! and the first denial wins; the denial text goes back to the model as an +//! error result it can read and react to. +//! +//! 🦀 Rust notes +//! - `ActionRequest<'a>` borrows the tool and its arguments for the +//! duration of the check (`'a` is that borrow's lifetime): nothing is +//! cloned just to ask a question. +//! - `Policy: Send + Sync` lets one policy object be shared by calls +//! running concurrently on different tasks. + +use serde_json::Value; + +use crate::effect::Effect; +use crate::tools::Tool; + +/// One proposed action, as the policies see it. +pub struct ActionRequest<'a> { + pub tool: &'a dyn Tool, + pub args: &'a Value, +} + +impl ActionRequest<'_> { + pub fn name(&self) -> &'static str { + self.tool.name() + } + pub fn effect(&self) -> Effect { + self.tool.effect() + } +} + +/// A policy's answer. +#[derive(Debug, Clone, PartialEq, Eq)] +pub enum Verdict { + Allow, + /// Blocked; the message is what the model reads. + Deny(String), +} + +/// A rule in front of every action. +pub trait Policy: Send + Sync { + fn admit(&self, req: &ActionRequest) -> Verdict; + /// Whether the tool is listed to the model at all (hidden tools are + /// still checked by [`Policy::admit`] when called). + fn visible(&self, _tool: &dyn Tool) -> bool { + true + } +} + +/// Run `policies` in order; the first denial wins. +pub fn admit<'p>( + policies: impl IntoIterator, + req: &ActionRequest, +) -> Verdict { + for p in policies { + if let v @ Verdict::Deny(_) = p.admit(req) { + return v; + } + } + Verdict::Allow +} + +/// `/plan`: nothing that mutates runs or is listed. +pub struct PlanPolicy; + +impl Policy for PlanPolicy { + fn admit(&self, req: &ActionRequest) -> Verdict { + if !req.effect().mutates() { + return Verdict::Allow; + } + Verdict::Deny(format!( + "Plan mode is on (read-only): {} is blocked. Keep exploring with read-only tools, then \ + present the plan; the user leaves plan mode with /plan off before anything is changed.", + req.name() + )) + } + fn visible(&self, tool: &dyn Tool) -> bool { + !tool.mutates() + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::tools::{bash::BashTool, read::ReadTool}; + use serde_json::json; + + struct DenyAll(&'static str); + impl Policy for DenyAll { + fn admit(&self, _req: &ActionRequest) -> Verdict { + Verdict::Deny(self.0.into()) + } + } + + #[test] + fn first_denial_wins() { + let args = json!({}); + let req = ActionRequest { + tool: &BashTool, + args: &args, + }; + let (a, b) = (DenyAll("a"), DenyAll("b")); + let ps: [&dyn Policy; 3] = [&PlanPolicy, &a, &b]; + assert!(matches!(admit(ps, &req), Verdict::Deny(m) if m.contains("Plan mode"))); + let ps: [&dyn Policy; 2] = [&a, &b]; + assert_eq!(admit(ps, &req), Verdict::Deny("a".into())); + } + + #[test] + fn plan_admits_reads_only() { + let args = json!({}); + let read = ActionRequest { + tool: &ReadTool, + args: &args, + }; + assert_eq!(PlanPolicy.admit(&read), Verdict::Allow); + assert!(PlanPolicy.visible(&ReadTool)); + assert!(!PlanPolicy.visible(&BashTool)); + } +} diff --git a/src/main.rs b/src/main.rs index 00c7d04..a770036 100644 --- a/src/main.rs +++ b/src/main.rs @@ -11,6 +11,7 @@ //! - `tui` — the ratatui + tachyonfx interface //! - `headless` — plain-terminal and JSON frontends +mod admission; mod agent; mod attachments; mod auth; diff --git a/src/subagents/mod.rs b/src/subagents/mod.rs index 499aaaa..3d35107 100644 --- a/src/subagents/mod.rs +++ b/src/subagents/mod.rs @@ -9,7 +9,7 @@ //! This module also holds the user-side verbs shared by the frontends: //! `/task`, `/agents` and `@name` routing. -pub mod hooks; +pub mod policies; pub mod profiles; pub mod supervisor; pub mod tools; diff --git a/src/subagents/hooks.rs b/src/subagents/policies.rs similarity index 62% rename from src/subagents/hooks.rs rename to src/subagents/policies.rs index fff9f62..31d44a0 100644 --- a/src/subagents/hooks.rs +++ b/src/subagents/policies.rs @@ -1,11 +1,11 @@ -//! Tool hooks a subagent's registry gets from its profile. +//! Admission policies a subagent's registry gets from its profile. //! -//! - [`ReadOnlyHook`] — `tools: read_only`: state-changing tools are +//! - [`ReadOnlyPolicy`] — `tools: read_only`: state-changing tools are //! blocked, the subagent's own task tools stay callable. -//! - [`NoEditHook`] — `tools: no_edit` (verifier): no `edit`/`write`. -//! - [`ClaimHook`] — writers on a shared workdir: `edit`/`write` refuse a +//! - [`NoEditPolicy`] — `tools: no_edit` (verifier): no `edit`/`write`. +//! - [`ClaimPolicy`] — writers on a shared workdir: `edit`/`write` refuse a //! path another live task claimed in `scope_paths`. -//! - [`AllowListHook`] — cache-parity fork children see the main tool +//! - [`AllowListPolicy`] — cache-parity fork children see the main tool //! list but may only call their profile's tools. use std::path::PathBuf; @@ -15,46 +15,49 @@ use serde_json::Value; use super::supervisor::Supervisor; use super::tools::SUBAGENT_TOOL_NAMES; -use crate::tools::{Tool, ToolHook}; +use crate::admission::{ActionRequest, Policy, Verdict}; -pub struct ReadOnlyHook; +pub struct ReadOnlyPolicy; -impl ToolHook for ReadOnlyHook { - fn before_tool(&self, tool: &dyn Tool, _args: &Value) -> Result<(), String> { +impl Policy for ReadOnlyPolicy { + fn admit(&self, req: &ActionRequest) -> Verdict { + let tool = req.tool; if SUBAGENT_TOOL_NAMES.contains(&tool.name()) || !tool.mutates() { - return Ok(()); + return Verdict::Allow; } - Err(format!( + Verdict::Deny(format!( "This subagent is read-only: {} is blocked. Report what should change in your finish() summary instead.", tool.name() )) } } -pub struct NoEditHook; +pub struct NoEditPolicy; -impl ToolHook for NoEditHook { - fn before_tool(&self, tool: &dyn Tool, _args: &Value) -> Result<(), String> { +impl Policy for NoEditPolicy { + fn admit(&self, req: &ActionRequest) -> Verdict { + let tool = req.tool; if matches!(tool.name(), "edit" | "write" | "run_code") { - return Err(format!( + return Verdict::Deny(format!( "This subagent does not edit files: {} is blocked. Report the fix in your finish() summary instead.", tool.name() )); } - Ok(()) + Verdict::Allow } } -pub struct AllowListHook { +pub struct AllowListPolicy { pub allowed: Vec, } -impl ToolHook for AllowListHook { - fn before_tool(&self, tool: &dyn Tool, _args: &Value) -> Result<(), String> { +impl Policy for AllowListPolicy { + fn admit(&self, req: &ActionRequest) -> Verdict { + let tool = req.tool; if self.allowed.is_empty() || self.allowed.iter().any(|a| a == tool.name()) { - Ok(()) + Verdict::Allow } else { - Err(format!( + Verdict::Deny(format!( "{} is not available to this subagent; it may only call: {}.", tool.name(), self.allowed.join(", ") @@ -106,23 +109,24 @@ fn glob_match(pattern: &str, text: &str) -> bool { pi == p.len() } -pub struct ClaimHook { +pub struct ClaimPolicy { pub task_id: String, pub sup: Weak, pub workdir: PathBuf, } -impl ToolHook for ClaimHook { - fn before_tool(&self, tool: &dyn Tool, args: &Value) -> Result<(), String> { +impl Policy for ClaimPolicy { + fn admit(&self, req: &ActionRequest) -> Verdict { + let (tool, args) = (req.tool, req.args); if !matches!(tool.name(), "edit" | "write") { - return Ok(()); + return Verdict::Allow; } let Some(raw) = args .get("path") .and_then(Value::as_str) .filter(|s| !s.is_empty()) else { - return Ok(()); + return Verdict::Allow; }; let path = crate::tools::resolve_path(&self.workdir, raw); let root = self.workdir.canonicalize().unwrap_or(self.workdir.clone()); @@ -132,17 +136,17 @@ impl ToolHook for ClaimHook { .map(|p| p.join(path.file_name().unwrap_or_default())) .unwrap_or(path); let Ok(rel) = full.strip_prefix(&root) else { - return Ok(()); + return Verdict::Allow; }; let rel = rel.to_string_lossy().replace('\\', "/"); let Some(sup) = self.sup.upgrade() else { - return Ok(()); + return Verdict::Allow; }; match sup.claimed_by(&self.task_id, &rel) { - Some((id, agent, title)) => Err(format!( + Some((id, agent, title)) => Verdict::Deny(format!( "{rel} 由任务 {id}({agent}:{title})认领。不要直接改它:用 need(on=[\"{id}\"]) 等它完成,或用 ask_main 说明你为什么需要改。" )), - None => Ok(()), + None => Verdict::Allow, } } } @@ -151,6 +155,28 @@ impl ToolHook for ClaimHook { mod tests { use super::*; + #[test] + fn profile_policies() { + use crate::tools::{bash::BashTool, read::ReadTool, write::WriteTool}; + let args = serde_json::json!({}); + let req = |tool: &'static dyn crate::tools::Tool| ActionRequest { tool, args: &args }; + assert_eq!(ReadOnlyPolicy.admit(&req(&ReadTool)), Verdict::Allow); + assert!(matches!( + ReadOnlyPolicy.admit(&req(&BashTool)), + Verdict::Deny(_) + )); + assert!(matches!( + NoEditPolicy.admit(&req(&WriteTool)), + Verdict::Deny(_) + )); + assert_eq!(NoEditPolicy.admit(&req(&BashTool)), Verdict::Allow); + let only_read = AllowListPolicy { + allowed: vec!["read".into()], + }; + assert_eq!(only_read.admit(&req(&ReadTool)), Verdict::Allow); + assert!(matches!(only_read.admit(&req(&BashTool)), Verdict::Deny(m) if m.contains("read"))); + } + #[test] fn claim_patterns() { let p = vec!["src/db/**".to_string(), "*.md".to_string()]; diff --git a/src/subagents/supervisor.rs b/src/subagents/supervisor.rs index d510be7..20a04ff 100644 --- a/src/subagents/supervisor.rs +++ b/src/subagents/supervisor.rs @@ -27,7 +27,7 @@ use serde_json::{Value, json}; use tokio::sync::mpsc; use tokio_util::sync::CancellationToken; -use super::hooks::{AllowListHook, ClaimHook, NoEditHook, ReadOnlyHook}; +use super::policies::{AllowListPolicy, ClaimPolicy, NoEditPolicy, ReadOnlyPolicy}; use super::profiles::{ NO_EDIT, Profile, ProjectFacts, READ_ONLY, discover_profiles, format_facts, format_profiles_for_prompt, resolve_profile, scan_project, @@ -755,7 +755,7 @@ impl Supervisor { if let Some(r) = self.runners.lock().unwrap().get(&task.id) { let _ = r; // the runner keeps the steer handle registered in start() } - // -- tools & hooks per profile + // -- tools & policies per profile let names = profile.tool_names(); let remove: Vec = match &names { Some(allowed) => agent @@ -768,12 +768,12 @@ impl Supervisor { None => MAIN_ONLY_TOOLS.iter().map(|s| s.to_string()).collect(), }; if profile.tools == READ_ONLY { - agent.registry.hooks.push(Arc::new(ReadOnlyHook)); + agent.registry.policies.push(Arc::new(ReadOnlyPolicy)); } else if profile.tools == NO_EDIT { - agent.registry.hooks.push(Arc::new(NoEditHook)); + agent.registry.policies.push(Arc::new(NoEditPolicy)); } if profile.writes() && task.isolation == "shared" { - agent.registry.hooks.push(Arc::new(ClaimHook { + agent.registry.policies.push(Arc::new(ClaimPolicy { task_id: task.id.clone(), sup: self.me.clone(), workdir: workdir.clone(), @@ -781,8 +781,8 @@ impl Supervisor { } if self.inherits_prompt(task, &profile) { // Advertising is not permission: the main tool list is shown, - // the hook decides what runs. - agent.registry.hooks.push(Arc::new(AllowListHook { + // the policy decides what runs. + agent.registry.policies.push(Arc::new(AllowListPolicy { allowed: names.unwrap_or_default(), })); agent.system_override = main @@ -2204,14 +2204,14 @@ impl Supervisor { } } - /// Whether a ClaimHook should block `rel` for task `me`. + /// Whether a ClaimPolicy should block `rel` for task `me`. pub fn claimed_by(&self, me: &str, rel: &str) -> Option<(String, String, String)> { let b = self.board.lock().unwrap(); for t in b.live() { if t.id == me || t.isolation == "worktree" { continue; } - if !t.scope_paths.is_empty() && super::hooks::matches(rel, &t.scope_paths) { + if !t.scope_paths.is_empty() && super::policies::matches(rel, &t.scope_paths) { return Some((t.id.clone(), t.agent_name().to_string(), t.title.clone())); } } diff --git a/src/tools/mod.rs b/src/tools/mod.rs index 407a6b0..9a18e26 100644 --- a/src/tools/mod.rs +++ b/src/tools/mod.rs @@ -1,8 +1,9 @@ //! Tools the model can call, and the registry that dispatches them. //! //! Like the Python version there are no safety fences: absolute paths are -//! honored, and `bash` runs whatever it is given. The only gate is plan -//! mode, which hides and blocks every tool that can change things. +//! honored, and `bash` runs whatever it is given. The only gates are +//! admission policies (`admission.rs`): plan mode, which hides and blocks +//! every tool that can change things, and subagent profile restrictions. //! //! 🦀 Rust notes //! - [`Tool`] is an async trait. `#[async_trait]` rewrites `async fn` in a @@ -36,6 +37,7 @@ use async_trait::async_trait; use serde_json::{Value, json}; use tokio_util::sync::CancellationToken; +use crate::admission::{self, ActionRequest, PlanPolicy, Policy, Verdict}; use crate::effect::{Effect, Recovery}; use crate::models::ToolResult; @@ -108,16 +110,6 @@ pub trait Tool: Send + Sync { async fn run(&self, args: Value, ctx: &ToolContext) -> ToolResult; } -/// A gate in front of every call (subagent profiles: read-only, no-edit, -/// path claims). `Err` blocks the call with that message. -pub trait ToolHook: Send + Sync { - fn before_tool(&self, tool: &dyn Tool, args: &Value) -> Result<(), String>; - /// Whether the tool is listed at all (hidden tools are also blocked). - fn visible(&self, _tool: &dyn Tool) -> bool { - true - } -} - /// Tools only daily mode registers. pub const DAILY_TOOLS: [&str; 5] = [ "web_fetch", @@ -135,7 +127,10 @@ pub struct ToolRegistry { pub daily_mode: bool, /// Code Mode: the model sees only `run_code` (plus non-programmable tools). pub code_mode: bool, - pub hooks: Vec>, + /// Admission policies in front of every call (subagent profiles: + /// read-only, no-edit, allow-list, path claims); plan mode adds + /// [`PlanPolicy`] ahead of them. + pub policies: Vec>, /// Set when the `memory` tool ran (daily memory nudge bookkeeping). pub memory_written: Arc, /// Where `session_search` looks. @@ -166,7 +161,7 @@ impl ToolRegistry { plan_mode: false, daily_mode: false, code_mode: false, - hooks: Vec::new(), + policies: Vec::new(), memory_written: Arc::new(AtomicBool::new(false)), session_dir: crate::config::limbo_home().join("sessions"), } @@ -239,8 +234,15 @@ impl ToolRegistry { self.tools.iter().map(|t| t.name()).collect() } + /// The active policies, in order: plan mode first, then the registry's own. + fn active_policies(&self) -> impl Iterator { + let plan: Option<&dyn Policy> = self.plan_mode.then_some(&PlanPolicy); + plan.into_iter() + .chain(self.policies.iter().map(|p| p.as_ref())) + } + fn allowed(&self, t: &Arc) -> bool { - (!self.plan_mode || !t.mutates()) && self.hooks.iter().all(|h| h.visible(t.as_ref())) + self.active_policies().all(|p| p.visible(t.as_ref())) } fn model_facing(&self) -> impl Iterator> { @@ -275,22 +277,18 @@ impl ToolRegistry { .collect() } - /// Run one call. Unknown tools, plan-mode and hook blocks become error - /// results the model can read and react to. + /// Run one call: resolve → admit → run. Unknown tools and denials + /// become error results the model can read and react to. pub async fn execute(&self, name: &str, args: Value, ctx: &ToolContext) -> ToolResult { let Some(tool) = self.get(name) else { return ToolResult::err(format!("Unknown tool: {name}")); }; - if self.plan_mode && tool.mutates() { - return ToolResult::err(format!( - "Plan mode is on (read-only): {name} is blocked. Keep exploring with read-only tools, then \ - present the plan; the user leaves plan mode with /plan off before anything is changed." - )); - } - for h in &self.hooks { - if let Err(e) = h.before_tool(tool.as_ref(), &args) { - return ToolResult::err(e); - } + let req = ActionRequest { + tool: tool.as_ref(), + args: &args, + }; + if let Verdict::Deny(reason) = admission::admit(self.active_policies(), &req) { + return ToolResult::err(reason); } if let Some(err) = args.get("parse_error").and_then(Value::as_str) { return ToolResult::err(format!( From 7fb1d9763943c6fd2ec00fa3aaa36f0ac7f2baa2 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 10:34:47 +0000 Subject: [PATCH 3/7] posture: model plan/daily/code/goal as orthogonal posture dimensions ToolRegistry's three mode flags become one Posture (policy x capability set x presentation); the goal loop's continuation is the goal Strategy. The set_*_mode verbs are sugar over Agent::set_posture. Session files keep the legacy plan_mode/daily_mode/code_mode fields. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014BrrmT45MDfJYo6atYUqsd --- AGENTS.md | 3 +- CONTEXT.md | 13 ++++ src/agent.rs | 69 ++++++++------------ src/main.rs | 1 + src/posture.rs | 164 +++++++++++++++++++++++++++++++++++++++++++++++ src/prompt.rs | 10 +-- src/pump.rs | 5 ++ src/tools/mod.rs | 41 ++++++++---- 8 files changed, 248 insertions(+), 58 deletions(-) create mode 100644 src/posture.rs diff --git a/AGENTS.md b/AGENTS.md index 8a1db77..26e9ab8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ **Limbo** is a minimal terminal AI coding agent, written in Rust (edition 2024, ratatui + tachyonfx). Users converse with an LLM in a TUI to explore, read, edit, and write code via a small set of tools. `--headless` runs a plain-terminal REPL frontend instead of the TUI (Herdr/script control), `--json` prints one JSON event per line, and `-p ""` runs one turn and exits. -**Tools execute immediately — no confirmation flow, no safety fences.** File tools are not scoped to the workdir (absolute paths and symlinks are honored as-is), there is no sensitive-file skip list, and `bash` runs every command as given (no dangerous-command filter). Every call passes admission (`admission.rs`): `ToolRegistry` runs its `Policy` list in order (`admit` returns `Deny(reason)` to block; `visible` hides a tool) — empty for the main agent, filled from the profile for subagents. `/plan` is a registry flag (`plan_mode`) that puts `PlanPolicy` first: only tools whose effect does not mutate run (bash is blocked), also enforced on Code Mode sub-calls, persisted as `SessionMeta.plan_mode`. +**Tools execute immediately — no confirmation flow, no safety fences.** File tools are not scoped to the workdir (absolute paths and symlinks are honored as-is), there is no sensitive-file skip list, and `bash` runs every command as given (no dangerous-command filter). Every call passes admission (`admission.rs`): `ToolRegistry` runs its `Policy` list in order (`admit` returns `Deny(reason)` to block; `visible` hides a tool) — empty for the main agent, filled from the profile for subagents. `/plan` is the posture's policy dimension (`ToolRegistry.posture`, see `posture.rs`), which puts `PlanPolicy` first: only tools whose effect does not mutate run (bash is blocked), also enforced on Code Mode sub-calls, persisted as `SessionMeta.plan_mode`. The source is commented for people learning Rust (`🦀 Rust notes` blocks); keep that style when adding code. `docs/learning-rust.md` has the reading order. @@ -35,6 +35,7 @@ src/ ├── admission.rs # ActionRequest → Policy → Verdict (Allow/Deny); PlanPolicy ├── effect.rs # Effect (read/fetch/session/write/mutate/exec) + Recovery (replay/inspect) per tool ├── attachments.rs # Vision gate: images inline for vision models, path references otherwise +├── posture.rs # Posture = policy (plan) × capability set (coding/daily) × presentation (direct/code); strategy (single/goal) ├── prompt.rs # System-prompt assembly (tools section derived from the registry) ├── session.rs # Session JSONL journal: records, append/rewrite, list, export, fork/handoff ├── trace.rs # Append-only JSONL run log (/traces/) diff --git a/CONTEXT.md b/CONTEXT.md index 007050f..6f7eb3a 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -60,6 +60,19 @@ proposals should name modules with these terms. (converging on the latest config model), persist to config.toml. The UI screen is an adapter translating verdicts into chat messages. +## Posture + +- **Posture** — how a session works, as independent dimensions + (`posture.rs`) instead of modes: **policy** (`default` | `plan`, what + admission lets through), **capability set** (`coding` | `daily`, which + tools and system prompt), **presentation** (`direct` | `code`, tools one + by one or behind `run_code`) and **strategy** (`single` | `goal`, how the + Turn pump drives turns; follows from a live goal). `/plan`, + `/daily-mode`, `/code-mode` and `/goal` are sugar over one dimension + each. The session file keeps the legacy `plan_mode` / `daily_mode` / + `code_mode` meta fields. `/new` keeps the capability set and + presentation, not the policy or goal. + ## Execution - **Effect** — what running a tool does (`effect.rs`): `read` (local diff --git a/src/agent.rs b/src/agent.rs index b96fb82..99605f9 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -41,6 +41,7 @@ use crate::llm::usage::{estimate_tokens, normalize_usage}; use crate::llm::{LlmClient, LlmError}; use crate::memory::{MEMORY_NUDGE, MemorySnapshot, MemoryStore, memory_dir}; use crate::models::{Attachment, LlmEvent, Message, Role, ToolCall, ToolResult, new_id}; +use crate::posture::Posture; use crate::prompt::{PromptExtras, build_system_prompt_with}; use crate::session::{self, CompactionRecord, LoadedSession, QueuedMessageRecord, SessionMeta}; use crate::subagents::Supervisor; @@ -334,11 +335,8 @@ impl Agent { meta.clone(), path.to_path_buf(), ); - agent.registry.plan_mode = meta.plan_mode; - if meta.daily_mode { - agent.registry.set_daily(true, &agent.config); - } - agent.registry.code_mode = meta.code_mode; + let cfg = agent.config.clone(); + agent.registry.set_posture(Posture::from_meta(&meta), &cfg); agent.file_created = true; agent.persisted = raw_message_ids.into_iter().collect(); agent.compactions = compactions; @@ -564,14 +562,17 @@ impl Agent { pub fn session_total_tokens(&self) -> u64 { self.meta.usage.values().map(|u| u.total_tokens).sum() } + pub fn posture(&self) -> Posture { + self.registry.posture + } pub fn plan_mode(&self) -> bool { - self.registry.plan_mode + self.posture().plan() } pub fn daily_mode(&self) -> bool { - self.registry.daily_mode + self.posture().daily() } pub fn code_mode(&self) -> bool { - self.registry.code_mode + self.posture().code() } /// The memory store `/memory` shows (None when `[daily] memory = false`). pub fn memory_store(&self) -> Option { @@ -620,45 +621,36 @@ impl Agent { } } + /// `/plan`: the read-only policy. pub fn set_plan_mode(&mut self, on: bool) -> bool { - if self.registry.plan_mode == on { - return false; - } - self.registry.plan_mode = on; - self.meta.plan_mode = on; - self.mode_changed("plan_mode", on); - true + self.set_posture(self.posture().with_plan(on), "plan_mode", on) } - /// Daily mode: swap the daily tools and the assistant prompt. + /// Daily mode: the daily capability set (tools + assistant prompt). pub fn set_daily_mode(&mut self, on: bool) -> bool { - if self.registry.daily_mode == on { - return false; - } - let cfg = self.config.clone(); - self.registry.set_daily(on, &cfg); - self.meta.daily_mode = on; - self.mode_changed("daily_mode", on); - true + self.set_posture(self.posture().with_daily(on), "daily_mode", on) } - /// Code Mode: collapse the catalog to `run_code` (+ the SDK prompt). + /// Code Mode: present the catalog as `run_code` (+ the SDK prompt). pub fn set_code_mode(&mut self, on: bool) -> bool { - if self.registry.code_mode == on { - return false; - } - self.registry.code_mode = on; - self.meta.code_mode = on; - self.mode_changed("code_mode", on); - true + self.set_posture(self.posture().with_code(on), "code_mode", on) } - fn mode_changed(&mut self, kind: &str, on: bool) { + /// Change one posture dimension; false when nothing changed. `kind` + /// and `on` name the change in the trace. + fn set_posture(&mut self, posture: Posture, kind: &str, on: bool) -> bool { + if posture == self.posture() { + return false; + } + let cfg = self.config.clone(); + self.registry.set_posture(posture, &cfg); + posture.write_meta(&mut self.meta); self.init_system_message(); self.needs_rewrite = true; // system prompt changed in place self.persist_meta(); self.trace .log(kind, json!({"turn": self.turn_count, "enabled": on})); + true } /// Daily mode: a memory reminder every N quiet turns. @@ -1460,9 +1452,7 @@ impl Agent { let mut meta = SessionMeta::new(new_session_id(), &self.workdir, &self.meta.model); meta.title = title; meta.parent_session = Some(self.meta.id.clone()); - meta.plan_mode = self.meta.plan_mode; - meta.daily_mode = self.meta.daily_mode; - meta.code_mode = self.meta.code_mode; + Posture::from_meta(&self.meta).write_meta(&mut meta); meta } @@ -1510,9 +1500,7 @@ impl Agent { let path = self.session_dir.join(format!("{}.jsonl", meta.id)); self.client.prompt_cache_key = Some(meta.id.clone()); let cfg = self.config.clone(); - self.registry.plan_mode = meta.plan_mode; - self.registry.set_daily(meta.daily_mode, &cfg); - self.registry.code_mode = meta.code_mode; + self.registry.set_posture(Posture::from_meta(&meta), &cfg); self.meta = meta; if !cfg!(test) { self.trace = TraceLogger::open(trace_path_for(&path)); @@ -1534,8 +1522,7 @@ impl Agent { pub fn new_session(&mut self) { let mut meta = SessionMeta::new(new_session_id(), &self.workdir, &self.meta.model); // The posture survives /new; plan mode and the goal do not. - meta.daily_mode = self.meta.daily_mode; - meta.code_mode = self.meta.code_mode; + self.posture().carried_over().write_meta(&mut meta); self.reset_to(meta); self.log_session_start(false); } diff --git a/src/main.rs b/src/main.rs index a770036..c71d690 100644 --- a/src/main.rs +++ b/src/main.rs @@ -29,6 +29,7 @@ mod learn; mod llm; mod memory; mod models; +mod posture; mod prompt; mod pump; mod recent_models; diff --git a/src/posture.rs b/src/posture.rs new file mode 100644 index 0000000..4d4e270 --- /dev/null +++ b/src/posture.rs @@ -0,0 +1,164 @@ +//! Posture: how a session works, as independent dimensions instead of a +//! growing list of modes. +//! +//! | dimension | values | slash command | +//! |-----------------|---------------------|----------------| +//! | policy | default, plan | `/plan` | +//! | capability set | coding, daily | `/daily-mode` | +//! | presentation | direct, code | `/code-mode` | +//! | strategy | single, goal | `/goal` | +//! +//! Each dimension changes one thing: the policy decides what is admitted +//! (`admission.rs`), the capability set decides which tools and prompt the +//! session has, the presentation decides how the tools are shown to the +//! model (one by one, or behind `run_code`), and the strategy decides how +//! turns are driven (`pump.rs`). The slash commands are sugar over these. +//! +//! The session file keeps the old `plan_mode` / `daily_mode` / `code_mode` +//! fields, so files stay readable by older versions; [`Posture::from_meta`] +//! and [`Posture::write_meta`] translate. +//! +//! 🦀 Rust notes +//! - `#[derive(Default)]` with `#[default]` on a variant picks that variant +//! for `Posture::default()`. + +use crate::session::SessionMeta; + +/// What is admitted. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum PolicyProfile { + #[default] + Default, + /// Read-only: nothing whose effect mutates runs (`PlanPolicy`). + Plan, +} + +/// Which tools and system prompt the session has. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum CapabilitySet { + #[default] + Coding, + /// The general-assistant prompt plus the daily tools (web_fetch, + /// memory, session_search, ask_user, skill_manage). + Daily, +} + +/// How the tools are presented to the model. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum Presentation { + /// One function definition per tool. + #[default] + Direct, + /// Code Mode: the catalog collapses to `run_code` and a Python SDK. + Code, +} + +/// How turns are driven. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Strategy { + /// One user input, one turn. + Single, + /// `/goal`: repeat turns until the verify command passes. + Goal, +} + +/// The policy, capability set and presentation of a session. The strategy +/// is not stored here: it follows from whether a goal is live +/// ([`Posture::strategy`]). +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub struct Posture { + pub policy: PolicyProfile, + pub capabilities: CapabilitySet, + pub presentation: Presentation, +} + +impl Posture { + pub fn plan(&self) -> bool { + self.policy == PolicyProfile::Plan + } + pub fn daily(&self) -> bool { + self.capabilities == CapabilitySet::Daily + } + pub fn code(&self) -> bool { + self.presentation == Presentation::Code + } + + pub fn with_plan(mut self, on: bool) -> Self { + self.policy = if on { + PolicyProfile::Plan + } else { + PolicyProfile::Default + }; + self + } + pub fn with_daily(mut self, on: bool) -> Self { + self.capabilities = if on { + CapabilitySet::Daily + } else { + CapabilitySet::Coding + }; + self + } + pub fn with_code(mut self, on: bool) -> Self { + self.presentation = if on { + Presentation::Code + } else { + Presentation::Direct + }; + self + } + + /// What a fresh session started from this one keeps (`/new`): the + /// capability set and presentation, not the policy. + pub fn carried_over(self) -> Self { + self.with_plan(false) + } + + pub fn from_meta(meta: &SessionMeta) -> Self { + Self::default() + .with_plan(meta.plan_mode) + .with_daily(meta.daily_mode) + .with_code(meta.code_mode) + } + + pub fn write_meta(self, meta: &mut SessionMeta) { + meta.plan_mode = self.plan(); + meta.daily_mode = self.daily(); + meta.code_mode = self.code(); + } + + /// The strategy a session with this meta runs. + pub fn strategy(meta: &SessionMeta) -> Strategy { + if meta.goal.as_ref().is_some_and(|g| g.is_live()) { + Strategy::Goal + } else { + Strategy::Single + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::path::Path; + + #[test] + fn meta_round_trip() { + let mut meta = SessionMeta::new("s".into(), Path::new("/w"), "m"); + let p = Posture::default().with_plan(true).with_code(true); + p.write_meta(&mut meta); + assert!(meta.plan_mode && meta.code_mode && !meta.daily_mode); + assert_eq!(Posture::from_meta(&meta), p); + assert_eq!(Posture::strategy(&meta), Strategy::Single); + } + + #[test] + fn new_session_drops_plan_only() { + let p = Posture::default() + .with_plan(true) + .with_daily(true) + .with_code(true); + let q = p.carried_over(); + assert!(!q.plan() && q.daily() && q.code()); + } +} diff --git a/src/prompt.rs b/src/prompt.rs index 97255fc..f7869cb 100644 --- a/src/prompt.rs +++ b/src/prompt.rs @@ -56,7 +56,7 @@ pub fn build_system_prompt_with( workdir: &Path, extras: &PromptExtras, ) -> String { - let daily = registry.daily_mode; + let daily = registry.daily_mode(); let mut s = String::from(if daily { DAILY_INTRO } else { BASE_INTRO }); s.push_str("Available tools:"); for def in registry.definitions() { @@ -107,13 +107,13 @@ pub fn build_system_prompt_with( } else { GUIDELINES_TAIL }); - if registry.code_mode { + if registry.code_mode() { s.push_str("\n\n"); s.push_str(crate::tools::run_code::CODE_ONLY_INSTRUCTION); s.push_str("\n\n"); s.push_str(&crate::tools::run_code::render_tools_sdk(registry)); } - if registry.plan_mode { + if registry.plan_mode() { s.push_str("\n\n"); s.push_str(PLAN_MODE_INSTRUCTION); } @@ -131,7 +131,7 @@ pub fn build_system_prompt_with( if let Some(ctx) = context_block(workdir) { s.push_str(&ctx); } - if has("read") || registry.code_mode { + if has("read") || registry.code_mode() { s.push_str(&format_skills(&discover_skills(workdir, daily))); } s @@ -173,7 +173,7 @@ mod tests { #[test] fn daily_prompt_answers_directly_and_names_only_registered_search() { let mut reg = ToolRegistry::core(true); - reg.daily_mode = true; + reg.posture = reg.posture.with_daily(true); let p = build_system_prompt(®, Path::new("/nonexistent")); assert!(p.contains("directly, without tools")); assert!(p.contains("independent calls together in one step")); diff --git a/src/pump.rs b/src/pump.rs index 8a69bac..f412c23 100644 --- a/src/pump.rs +++ b/src/pump.rs @@ -23,6 +23,7 @@ use crate::goal::{ build_goal_prompt, build_wrapup_prompt, next_state, run_verify, }; use crate::models::Attachment; +use crate::posture::{Posture, Strategy}; use crate::session::QueuedMessageRecord; /// Run one task to completion (or interruption). @@ -206,6 +207,10 @@ async fn run_once( next = batch; continue; } + // Only the goal strategy continues past a quiet turn boundary. + if Posture::strategy(&agent.meta) != Strategy::Goal { + return; + } let Some(state) = agent.meta.goal.clone() else { return; }; diff --git a/src/tools/mod.rs b/src/tools/mod.rs index 9a18e26..f313b57 100644 --- a/src/tools/mod.rs +++ b/src/tools/mod.rs @@ -40,6 +40,7 @@ use tokio_util::sync::CancellationToken; use crate::admission::{self, ActionRequest, PlanPolicy, Policy, Verdict}; use crate::effect::{Effect, Recovery}; use crate::models::ToolResult; +use crate::posture::Posture; /// Everything a tool call may need besides its arguments. #[derive(Clone)] @@ -123,10 +124,10 @@ pub const DAILY_TOOLS: [&str; 5] = [ #[derive(Clone)] pub struct ToolRegistry { tools: Vec>, - pub plan_mode: bool, - pub daily_mode: bool, - /// Code Mode: the model sees only `run_code` (plus non-programmable tools). - pub code_mode: bool, + /// Policy, capability set and presentation (`posture.rs`). Change the + /// capability set through [`ToolRegistry::set_daily`], which also swaps + /// the daily tools. + pub posture: Posture, /// Admission policies in front of every call (subagent profiles: /// read-only, no-edit, allow-list, path claims); plan mode adds /// [`PlanPolicy`] ahead of them. @@ -158,9 +159,7 @@ impl ToolRegistry { tools.push(Arc::new(run_code::RunCodeTool)); Self { tools, - plan_mode: false, - daily_mode: false, - code_mode: false, + posture: Posture::default(), policies: Vec::new(), memory_written: Arc::new(AtomicBool::new(false)), session_dir: crate::config::limbo_home().join("sessions"), @@ -180,9 +179,29 @@ impl ToolRegistry { r } + pub fn plan_mode(&self) -> bool { + self.posture.plan() + } + pub fn daily_mode(&self) -> bool { + self.posture.daily() + } + /// Code Mode: the model sees only `run_code` (plus non-programmable tools). + pub fn code_mode(&self) -> bool { + self.posture.code() + } + + /// Switch to `posture`, swapping the daily tools when the capability + /// set changes. + pub fn set_posture(&mut self, posture: Posture, config: &crate::config::Config) { + if posture.daily() != self.daily_mode() { + self.set_daily(posture.daily(), config); + } + self.posture = posture; + } + /// Add or remove the daily tools. pub fn set_daily(&mut self, enabled: bool, config: &crate::config::Config) { - self.daily_mode = enabled; + self.posture = self.posture.with_daily(enabled); self.tools.retain(|t| !DAILY_TOOLS.contains(&t.name())); if !enabled { return; @@ -236,7 +255,7 @@ impl ToolRegistry { /// The active policies, in order: plan mode first, then the registry's own. fn active_policies(&self) -> impl Iterator { - let plan: Option<&dyn Policy> = self.plan_mode.then_some(&PlanPolicy); + let plan: Option<&dyn Policy> = self.plan_mode().then_some(&PlanPolicy); plan.into_iter() .chain(self.policies.iter().map(|p| p.as_ref())) } @@ -247,7 +266,7 @@ impl ToolRegistry { fn model_facing(&self) -> impl Iterator> { self.tools.iter().filter(move |t| { - let shown = if self.code_mode { + let shown = if self.code_mode() { t.name() == "run_code" || !t.program_callable() } else { t.name() != "run_code" @@ -412,7 +431,7 @@ mod tests { #[tokio::test] async fn plan_mode_blocks_mutations() { let mut reg = ToolRegistry::core(true); - reg.plan_mode = true; + reg.posture = reg.posture.with_plan(true); assert!(!reg.names().contains(&"write")); let ctx = ToolContext::simple("/tmp"); let r = reg From 12875df0ca968cb607d8ba3afc56970509047630 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 10:38:19 +0000 Subject: [PATCH 4/7] journal: generalize tool intents into an execution journal of action records Every tool call appends an action record (started or denied) before it runs and completed/failed once its result is in; goal verify runs are journaled the same way. Resume uses the log to tell 'did not run', 'may have partially run' and the new 'ran to the end, result lost' apart. Legacy tool_intent records load as started. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014BrrmT45MDfJYo6atYUqsd --- AGENTS.md | 3 +- CONTEXT.md | 10 ++- docs/session-management.md | 6 +- src/agent.rs | 61 ++++++++++---- src/history.rs | 28 ++++--- src/journal.rs | 167 +++++++++++++++++++++++++++++++++++++ src/main.rs | 1 + src/pump.rs | 18 ++++ src/session.rs | 61 +++++++------- src/tools/mod.rs | 20 +++-- 10 files changed, 307 insertions(+), 68 deletions(-) create mode 100644 src/journal.rs diff --git a/AGENTS.md b/AGENTS.md index 26e9ab8..c331cd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,6 +37,7 @@ src/ ├── attachments.rs # Vision gate: images inline for vision models, path references otherwise ├── posture.rs # Posture = policy (plan) × capability set (coding/daily) × presentation (direct/code); strategy (single/goal) ├── prompt.rs # System-prompt assembly (tools section derived from the registry) +├── journal.rs # Execution journal: `action` records (started/denied/completed/failed) + ActionLog for recovery ├── session.rs # Session JSONL journal: records, append/rewrite, list, export, fork/handoff ├── trace.rs # Append-only JSONL run log (/traces/) ├── trace_viewer.rs # /tracing-viewer: loopback HTTP server (std::net + threads) + assets/trace_viewer.html @@ -94,7 +95,7 @@ Providers/models live in `llm/catalog.rs`; unknown models get generic OpenAI-com [providers.] # base_url / api_key / api_key_env / headers ``` -`/model` rebuilds the client mid-session (refused while busy) and persists via `toml_edit`. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls: each call commits a `tool_intent` record before it runs, so a crashed call is re-run on the next turn if its tool's recovery is `replay` (read/fetch effects: read/grep/find/ls, web tools), otherwise marked "may have partially run" (intent committed) or "did not run" (no intent). `/export [path]` merges meta + trace + messages (Markdown if `.md`). `/fork [n]` copies the active history (first n user turns) into a new session, `/handoff ` starts a clean linked session from a note; both record `parent_session` and leave the parent untouched. +`/model` rebuilds the client mid-session (refused while busy) and persists via `toml_edit`. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls from the execution journal (`journal.rs`): each call appends an `action` record `started` (or `denied`) before it runs and `completed`/`failed` once its result is in (goal verify runs too, kind `verify`), so a crashed call is re-run on the next turn if its tool's recovery is `replay` (read/fetch effects: read/grep/find/ls, web tools), otherwise marked "ran to the end, result lost" (finished), "may have partially run" (started only) or "did not run" (nothing). Legacy `tool_intent` records load as `started`. `/export [path]` merges meta + trace + messages (Markdown if `.md`). `/fork [n]` copies the active history (first n user turns) into a new session, `/handoff ` starts a clean linked session from a note; both record `parent_session` and leave the parent untouched. Skills: `~/.agents/skills//SKILL.md` (global, shared with other agents; lowest of the non-bundled), `~/.limbo/skills//SKILL.md` (user) and `/.agents/skills//SKILL.md` (project, wins collisions); daily sessions also see the bundled pack (lowest, unpacked to `~/.limbo/daily/bundled//`) and `~/.limbo/daily/skills/` (highest), coding sessions never do — injected as an `` catalog in the system prompt and invocable via `/ [args]`. diff --git a/CONTEXT.md b/CONTEXT.md index 6f7eb3a..bff9cb9 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -41,8 +41,14 @@ proposals should name modules with these terms. that keeps a crash recoverable (summarized messages before their compaction record, `dequeued` after the message carrying the item). The Agent calls its verbs (`checkpoint`, `queued`/`dequeued`, - `record_intents`, `compacted`, `patch_meta`); `session.rs` owns the + `journal_action`, `compacted`, `patch_meta`); `session.rs` owns the file format and loading. +- **Execution journal** — the `action` records in the session file + (`journal.rs`): every tool call (and `/goal` verify run) appends + `started` or `denied` before it runs and `completed` / `failed` when + its result is in. Resume reads them as an **action log**: a call with + no result message is "did not run" (nothing), "may have partially + run" (started only) or "result lost" (finished). - **Steer** — a user message queued mid-turn, injected at consistency points (loop top, turn end, run head). The steer queue owns queueing semantics — id generation, FIFO, and the cancel boundary (an @@ -80,7 +86,7 @@ proposals should name modules with these terms. state: task board, questions, the `run_code` transport), `write` (repeatable local writes), `mutate` (other local changes), `exec` (arbitrary commands). Plan mode and read-only profiles block the - mutating ones (`write`/`mutate`/`exec`). Journaled on each `tool_intent`. + mutating ones (`write`/`mutate`/`exec`). Journaled on each `started` action record. - **Admission** — the gate every action passes before it runs (`admission.rs`): an **action request** (tool, arguments, effect) goes through the registry's **policies** in order and the first `Deny` diff --git a/docs/session-management.md b/docs/session-management.md index fb8df1b..f5706e2 100644 --- a/docs/session-management.md +++ b/docs/session-management.md @@ -34,7 +34,7 @@ JSONL,首行为 meta,后续为消息行。**向后兼容**:无 meta 行的 ``` - `id` 即文件名 stem(不含 `.jsonl`),`--resume` 支持 id 前缀匹配 -- 增量追加:一轮内每个一致性点追加新消息和类型化记录(`meta_patch`、`tool_intent`、`queue`、`compaction`);只有首次保存、追加失败后或恢复时修复了悬空调用才原子重写全量(写入顺序与回退规则见 `src/session.rs` 和 `src/agent.rs`) +- 增量追加:一轮内每个一致性点追加新消息和类型化记录(`meta_patch`、`action`(执行日志,旧文件为 `tool_intent`)、`queue`、`compaction`);只有首次保存、追加失败后或恢复时修复了悬空调用才原子重写全量(写入顺序与回退规则见 `src/session.rs` 和 `src/agent.rs`) - `title` 取首条 user 消息(折叠空白、截断 50 字符) - `list_sessions` 只读每个文件的首行,O(1)/文件;旧文件回退用 mtime 排序、标题为空 @@ -63,7 +63,9 @@ src/ (AGENTS.md 可能已变更) - **悬空 tool_calls 修复**:旧会话末尾若有未配对的 `tool_calls`(崩溃导致), 加载时补占位 tool 消息(`[session restored: tool call interrupted]`), - 避免 OpenAI API 报 400 + 避免 OpenAI API 报 400。占位内容按执行日志(`action` 记录)区分:没有记录 = 没运行, + 只有 `started` = 可能部分执行,已有 `completed`/`failed` = 已执行完但结果丢失; + recovery 为 `replay` 的只读工具会直接重跑 - **沿用原文件**:resume 不产生新 session 文件,继续写同一文件 - **workdir 跟随会话**:CLI resume 时若 meta 中的 workdir 仍存在,切换过去 - **model 用当前配置**:meta 中记录的原 model 仅作展示 diff --git a/src/agent.rs b/src/agent.rs index 99605f9..ea4e478 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -30,6 +30,7 @@ use serde_json::{Value, json}; use tokio::sync::mpsc; use tokio_util::sync::CancellationToken; +use crate::admission::Verdict; use crate::attachments::build_user_content; use crate::compaction::{ self, build_summary_prompt, find_split_point, is_summary_message, make_summary_message, @@ -37,6 +38,7 @@ use crate::compaction::{ }; use crate::config::Config; use crate::history; +use crate::journal::{ActionKind, ActionLog, ActionPhase, ActionRecord}; use crate::llm::usage::{estimate_tokens, normalize_usage}; use crate::llm::{LlmClient, LlmError}; use crate::memory::{MEMORY_NUDGE, MemorySnapshot, MemoryStore, memory_dir}; @@ -313,7 +315,7 @@ impl Agent { meta, messages, compactions, - intents, + actions, queue, raw_message_ids, } = session::load_session_full(path)?; @@ -340,9 +342,9 @@ impl Agent { agent.file_created = true; agent.persisted = raw_message_ids.into_iter().collect(); agent.compactions = compactions; - let started: HashSet = intents.iter().map(|i| i.call_id.clone()).collect(); + let journal = ActionLog::from_records(&actions); let registry = agent.registry.clone(); - let rec = history::recover(messages, meta.tool_intents.then_some(&started), |name| { + let rec = history::recover(messages, meta.tool_intents.then_some(&journal), |name| { registry.get(name).is_some_and(|t| t.replay_safe()) }); agent.messages = rec.messages; @@ -770,6 +772,22 @@ impl Agent { } } + /// Append one execution-journal record (goal verify runs use this). + pub fn journal_action(&self, record: &ActionRecord) { + self.journal(&[record.to_line()]); + } + + /// A call's result is in: journal it before the result message is + /// checkpointed, so a crash in between is told apart from one mid-run. + fn journal_finished(&self, tc: &ToolCall, r: &ToolResult) { + let phase = if r.success { + ActionPhase::Completed + } else { + ActionPhase::Failed + }; + self.journal_action(&tool_action(tc, phase)); + } + // -- token accounting ------------------------------------------------------ fn estimated_next_prompt_tokens(&self) -> u64 { @@ -1228,14 +1246,18 @@ impl Agent { tx: &EventTx, cancel: &CancellationToken, ) { - // Commit each call's intent before any side effect runs. - let intents: Vec = calls - .iter() - .map(|tc| { - let tool = self.registry.get(tc.name()); - session::tool_intent_record(&tc.id, tc.name(), tool.as_deref()) - }) - .collect(); + // Journal each call as started (or denied) before any side effect runs. + let mut admitted = Vec::with_capacity(calls.len()); + let mut intents: Vec = Vec::with_capacity(calls.len()); + for tc in calls { + let effect = self.registry.get(tc.name()).map(|t| t.effect()); + let rec = match self.registry.admit(tc.name(), &tc.function.arguments) { + Verdict::Allow => tool_action(tc, ActionPhase::Started), + Verdict::Deny(reason) => tool_action(tc, ActionPhase::Denied).with_detail(reason), + }; + admitted.push(rec.phase == ActionPhase::Started); + intents.push(rec.with_effect(effect).to_line()); + } self.journal(&intents); for tc in calls { let _ = tx.send(AgentEvent::ToolCall { @@ -1266,6 +1288,9 @@ impl Agent { } while let Some((i, r)) = running.next().await { let tc = &calls[i]; + if admitted[i] { + self.journal_finished(tc, &r); + } let _ = tx.send(AgentEvent::ToolResult { id: tc.id.clone(), name: tc.name().into(), @@ -1284,6 +1309,9 @@ impl Agent { .execute(tc.name(), tc.function.arguments.clone(), &ctx) .await }; + if admitted[i] { + self.journal_finished(tc, &r); + } let _ = tx.send(AgentEvent::ToolResult { id: tc.id.clone(), name: tc.name().into(), @@ -1528,6 +1556,10 @@ impl Agent { } } +fn tool_action(tc: &ToolCall, phase: ActionPhase) -> ActionRecord { + ActionRecord::new(ActionKind::Tool, &tc.id, tc.name(), phase) +} + /// `20261102-021814-ab12cd` — sortable and readable. pub fn new_session_id() -> String { let short: String = new_id().chars().take(6).collect(); @@ -1686,11 +1718,12 @@ pub(crate) mod tests { )]); agent.messages.push(a); agent.checkpoint(); - agent.journal(&[session::tool_intent_record( + agent.journal_action(&ActionRecord::new( + ActionKind::Tool, "w1", "write", - Some(&crate::tools::write::WriteTool), - )]); + ActionPhase::Started, + )); // "crash" here, then resume let resumed = Agent::resume( test_config("http://127.0.0.1:9/v1"), diff --git a/src/history.rs b/src/history.rs index 355f441..cd35ff8 100644 --- a/src/history.rs +++ b/src/history.rs @@ -1,14 +1,14 @@ //! Keeps the "every tool call has exactly one result" invariant, and repairs //! history after a crash. -use std::collections::HashSet; - +use crate::journal::ActionLog; use crate::models::{Message, Role, ToolCall}; pub const INTERRUPTED_CONTENT: &str = "[session restored: tool call interrupted]"; pub const NOT_STARTED_CONTENT: &str = "[session restored: tool call interrupted before it started; it did not run]"; pub const PARTIAL_CONTENT: &str = "[session restored: tool call interrupted while running; it may have partially run. Check its effects before retrying.]"; +pub const LOST_RESULT_CONTENT: &str = "[session restored: tool call ran to the end but its result was lost. Check its effects instead of re-running it.]"; pub struct Recovery { pub messages: Vec, @@ -19,11 +19,11 @@ pub struct Recovery { } /// Drop the leading system message and insert placeholder results for -/// dangling tool calls. `started` = calls whose intent was journaled -/// (`None` for legacy sessions without intents). +/// dangling tool calls. `journal` = what the execution journal recorded +/// (`None` for legacy sessions that journaled nothing). pub fn recover( messages: Vec, - started: Option<&HashSet>, + journal: Option<&ActionLog>, is_safe: impl Fn(&str) -> bool, ) -> Recovery { let mut history = messages; @@ -43,9 +43,10 @@ pub fn recover( rerun.push(tc.clone()); INTERRUPTED_CONTENT } else { - match started { + match journal { None => INTERRUPTED_CONTENT, - Some(s) if s.contains(&tc.id) => PARTIAL_CONTENT, + Some(j) if j.finished(&tc.id) => LOST_RESULT_CONTENT, + Some(j) if j.started(&tc.id) => PARTIAL_CONTENT, Some(_) => NOT_STARTED_CONTENT, } }; @@ -90,17 +91,24 @@ mod tests { ToolCall::new("r", "read", json!({})), ToolCall::new("b", "bash", json!({})), ToolCall::new("w", "write", json!({})), + ToolCall::new("e", "edit", json!({})), + ]); + use crate::journal::{ActionKind::Tool, ActionPhase::*, ActionRecord}; + let log = ActionLog::from_records(&[ + ActionRecord::new(Tool, "b", "bash", Started), + ActionRecord::new(Tool, "e", "edit", Started), + ActionRecord::new(Tool, "e", "edit", Completed), ]); - let started: HashSet = ["b".to_string()].into(); let rec = recover( vec![Message::system("s"), Message::user("u"), a], - Some(&started), + Some(&log), |n| n == "read", ); - assert_eq!(rec.messages.len(), 5); + assert_eq!(rec.messages.len(), 6); assert_eq!(rec.messages[2].text(), INTERRUPTED_CONTENT); assert_eq!(rec.messages[3].text(), PARTIAL_CONTENT); assert_eq!(rec.messages[4].text(), NOT_STARTED_CONTENT); + assert_eq!(rec.messages[5].text(), LOST_RESULT_CONTENT); assert_eq!(rec.rerun.len(), 1); assert!(rec.repaired); } diff --git a/src/journal.rs b/src/journal.rs new file mode 100644 index 0000000..0dab76f --- /dev/null +++ b/src/journal.rs @@ -0,0 +1,167 @@ +//! The execution journal: one `action` record per step of every action a +//! session runs, appended to the session file next to its messages. +//! +//! A tool call writes `started` (or `denied`) before anything runs, then +//! `completed` or `failed` as soon as its result is in. A goal verify run +//! does the same with kind `verify`. On resume the pair tells crash +//! recovery what happened to a call whose result message never reached +//! the file: +//! +//! | journal | meaning | +//! |-------------------------|----------------------------------------------| +//! | nothing | it never started | +//! | `started` only | unknown: it may have partially run | +//! | `started` + finished | it ran to the end; only the result was lost | +//! +//! Files written before this journal carry `tool_intent` records instead; +//! they load as `started`. +//! +//! 🦀 Rust notes +//! - `#[serde(rename_all = "snake_case")]` on an enum writes its variants +//! as lowercase strings (`"completed"`), which keeps the JSONL readable. + +use std::collections::HashSet; + +use serde::{Deserialize, Serialize}; +use serde_json::Value; + +use crate::effect::Effect; + +/// What kind of action a record is about. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ActionKind { + /// A model tool call (`id` = the tool call id). + Tool, + /// A `/goal` verify command run (`id` = `verify-`). + Verify, +} + +/// One step in an action's life. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum ActionPhase { + /// Admitted and about to run: any side effect happens after this. + Started, + /// Refused by admission (or an unknown tool); it never ran. + Denied, + Completed, + Failed, +} + +impl ActionPhase { + pub fn is_finished(self) -> bool { + matches!(self, ActionPhase::Completed | ActionPhase::Failed) + } +} + +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] +pub struct ActionRecord { + pub id: String, + pub kind: ActionKind, + pub name: String, + pub phase: ActionPhase, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub effect: Option, + /// A short note: the denial reason, a verify exit code. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub detail: Option, + #[serde(default)] + pub at: String, +} + +impl ActionRecord { + pub fn new(kind: ActionKind, id: &str, name: &str, phase: ActionPhase) -> Self { + Self { + id: id.into(), + kind, + name: name.into(), + phase, + effect: None, + detail: None, + at: crate::session::now_iso(), + } + } + pub fn with_effect(mut self, effect: Option) -> Self { + self.effect = effect; + self + } + pub fn with_detail(mut self, detail: impl Into) -> Self { + self.detail = Some(detail.into()); + self + } + /// The JSONL line (`"type": "action"`). + pub fn to_line(&self) -> Value { + let mut v = serde_json::to_value(self).expect("action serializes"); + let mut out = serde_json::Map::new(); + out.insert("type".into(), "action".into()); + if let Some(obj) = v.as_object_mut() { + out.extend(std::mem::take(obj)); + } + Value::Object(out) + } +} + +/// What the journal knows about the tool calls of one session. +#[derive(Debug, Default)] +pub struct ActionLog { + started: HashSet, + finished: HashSet, +} + +impl ActionLog { + pub fn from_records(records: &[ActionRecord]) -> Self { + let mut log = Self::default(); + for r in records.iter().filter(|r| r.kind == ActionKind::Tool) { + match r.phase { + ActionPhase::Started => { + log.started.insert(r.id.clone()); + } + p if p.is_finished() => { + log.finished.insert(r.id.clone()); + } + _ => {} + } + } + log + } + pub fn started(&self, id: &str) -> bool { + self.started.contains(id) + } + pub fn finished(&self, id: &str) -> bool { + self.finished.contains(id) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn line_round_trip() { + let r = ActionRecord::new(ActionKind::Tool, "c1", "bash", ActionPhase::Started) + .with_effect(Some(Effect::Exec)); + let line = r.to_line(); + assert_eq!(line["type"], "action"); + assert_eq!(line["phase"], "started"); + assert_eq!(line["effect"], "exec"); + let mut obj = line.as_object().unwrap().clone(); + obj.remove("type"); + let back: ActionRecord = serde_json::from_value(Value::Object(obj)).unwrap(); + assert_eq!(back, r); + } + + #[test] + fn log_tracks_tool_phases_only() { + let recs = [ + ActionRecord::new(ActionKind::Tool, "a", "bash", ActionPhase::Started), + ActionRecord::new(ActionKind::Tool, "a", "bash", ActionPhase::Failed), + ActionRecord::new(ActionKind::Tool, "b", "edit", ActionPhase::Started), + ActionRecord::new(ActionKind::Verify, "v", "cargo test", ActionPhase::Started), + ]; + let log = ActionLog::from_records(&recs); + assert!(log.started("a") && log.finished("a")); + assert!(log.started("b") && !log.finished("b")); + assert!(!log.started("v")); + } +} diff --git a/src/main.rs b/src/main.rs index c71d690..7019cc3 100644 --- a/src/main.rs +++ b/src/main.rs @@ -25,6 +25,7 @@ mod goal; mod headless; mod history; mod integrations; +mod journal; mod learn; mod llm; mod memory; diff --git a/src/pump.rs b/src/pump.rs index f412c23..238b997 100644 --- a/src/pump.rs +++ b/src/pump.rs @@ -18,10 +18,12 @@ use serde_json::json; use tokio_util::sync::CancellationToken; use crate::agent::{Agent, AgentEvent, EventTx, FOLLOW_UP, STEER}; +use crate::effect::Effect; use crate::goal::{ self, GoalState, STATUS_ACTIVE, STATUS_CLEARED, STATUS_EXHAUSTED, STATUS_PASSED, build_goal_prompt, build_wrapup_prompt, next_state, run_verify, }; +use crate::journal::{ActionKind, ActionPhase, ActionRecord}; use crate::models::Attachment; use crate::posture::{Posture, Strategy}; use crate::session::QueuedMessageRecord; @@ -223,6 +225,12 @@ async fn run_once( round, max_rounds: state.max_rounds, }); + let action_id = format!("verify-{round}"); + let verify_action = |phase| { + ActionRecord::new(ActionKind::Verify, &action_id, &state.verify_command, phase) + .with_effect(Some(Effect::Exec)) + }; + agent.journal_action(&verify_action(ActionPhase::Started)); let result = run_verify( &state.verify_command, &agent.workdir, @@ -230,6 +238,16 @@ async fn run_once( cancel, ) .await; + let finished = match (result.exit_code, result.cancelled, result.timed_out) { + (Some(0), ..) => verify_action(ActionPhase::Completed).with_detail("exit 0"), + (_, true, _) => verify_action(ActionPhase::Failed).with_detail("cancelled"), + (_, _, true) => verify_action(ActionPhase::Failed).with_detail("timed out"), + (code, ..) => verify_action(ActionPhase::Failed).with_detail(format!( + "exit {}", + code.map_or("?".into(), |c| c.to_string()) + )), + }; + agent.journal_action(&finished); agent.trace.log( "goal_verify", json!({"command": state.verify_command, "exit_code": result.exit_code, "round": round, diff --git a/src/session.rs b/src/session.rs index a949e92..990c109 100644 --- a/src/session.rs +++ b/src/session.rs @@ -3,7 +3,7 @@ //! Layout of `~/.limbo/sessions/.jsonl`: //! - line 1: `{"type": "meta", ...}` //! - then, in the order they happened: message lines (no `type` key), -//! `compaction`, `tool_intent`, `meta_patch`, `queue` and `task` records. +//! `compaction`, `action` (execution journal, see `journal.rs`; legacy `tool_intent`), `meta_patch`, `queue` and `task` records. //! //! Steady state only *appends*; a full atomic rewrite (temp file + rename, //! mode 0600) happens on first save or when history changed shape. @@ -18,6 +18,7 @@ use serde::{Deserialize, Serialize}; use serde_json::{Map, Value, json}; use crate::compaction::{is_summary_message, make_summary_message}; +use crate::journal::{ActionKind, ActionPhase, ActionRecord}; use crate::models::{Message, Role}; pub fn now_iso() -> String { @@ -139,15 +140,14 @@ fn auto() -> String { "auto".into() } +/// The legacy pre-run record (files written before the execution journal); +/// loaded as an `action` with phase `started`. #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] pub struct ToolIntentRecord { pub call_id: String, pub name: String, #[serde(default = "unsafe_replay")] pub replay: String, - /// The tool's declared effect (absent in files written before effects). - #[serde(default, skip_serializing_if = "Option::is_none")] - pub effect: Option, #[serde(default)] pub created_at: String, } @@ -188,7 +188,9 @@ pub struct LoadedSession { /// History with the latest compaction applied. pub messages: Vec, pub compactions: Vec, - pub intents: Vec, + /// The execution journal (`action` records, legacy `tool_intent`s + /// converted), in file order. + pub actions: Vec, /// Messages still queued when the file was last written. pub queue: Vec, /// Every message line in the file (before compaction selection). @@ -205,26 +207,6 @@ fn record(kind: &str, value: impl Serialize) -> Value { Value::Object(out) } -/// The intent a call commits before it runs. `tool` is `None` for a name -/// the registry does not know (recorded as unsafe, no effect). -pub fn tool_intent_record( - call_id: &str, - name: &str, - tool: Option<&dyn crate::tools::Tool>, -) -> Value { - let replay_safe = tool.is_some_and(|t| t.replay_safe()); - record( - "tool_intent", - ToolIntentRecord { - call_id: call_id.into(), - name: name.into(), - replay: if replay_safe { "safe" } else { "unsafe" }.into(), - effect: tool.map(|t| t.effect()), - created_at: now_iso(), - }, - ) -} - pub fn compaction_record(c: &CompactionRecord) -> Value { record("compaction", c) } @@ -407,7 +389,7 @@ pub fn load_session_full(path: &Path) -> std::io::Result { let mut patches: Vec = Vec::new(); let mut messages = Vec::new(); let mut compactions = Vec::new(); - let mut intents = Vec::new(); + let mut actions = Vec::new(); let mut queued: Vec = Vec::new(); for line in reader.lines() { let line = line?; @@ -441,9 +423,21 @@ pub fn load_session_full(path: &Path) -> std::io::Result { compactions.push(c); } } + Some("action") => { + if let Ok(a) = serde_json::from_value(v) { + actions.push(a); + } + } Some("tool_intent") => { - if let Ok(i) = serde_json::from_value(v) { - intents.push(i); + if let Ok(i) = serde_json::from_value::(v) { + let mut a = ActionRecord::new( + ActionKind::Tool, + &i.call_id, + &i.name, + ActionPhase::Started, + ); + a.at = i.created_at; + actions.push(a); } } Some("queue") => match obj.get("op").and_then(Value::as_str) { @@ -489,7 +483,7 @@ pub fn load_session_full(path: &Path) -> std::io::Result { meta, messages: apply_compactions(messages, &compactions), compactions, - intents, + actions, queue: queued, raw_message_ids, }) @@ -667,7 +661,8 @@ mod tests { meta_patch_record(&patched), queued_record(&q), json!({"type": "future_thing", "x": 1}), - tool_intent_record("c1", "bash", Some(&crate::tools::bash::BashTool)), + json!({"type": "tool_intent", "call_id": "c1", "name": "bash", "replay": "unsafe"}), + ActionRecord::new(ActionKind::Tool, "c2", "read", ActionPhase::Completed).to_line(), ], ) .unwrap(); @@ -682,9 +677,9 @@ mod tests { assert_eq!(loaded.meta.goal.as_ref().unwrap().text, "keep me"); assert_eq!(loaded.messages.len(), 3); assert_eq!(loaded.queue.len(), 1); - assert_eq!(loaded.intents[0].call_id, "c1"); - assert_eq!(loaded.intents[0].replay, "unsafe"); - assert_eq!(loaded.intents[0].effect, Some(crate::effect::Effect::Exec)); + assert_eq!(loaded.actions[0].id, "c1"); + assert_eq!(loaded.actions[0].phase, ActionPhase::Started); + assert_eq!(loaded.actions[1].phase, ActionPhase::Completed); } #[test] diff --git a/src/tools/mod.rs b/src/tools/mod.rs index f313b57..3d60607 100644 --- a/src/tools/mod.rs +++ b/src/tools/mod.rs @@ -296,19 +296,27 @@ impl ToolRegistry { .collect() } - /// Run one call: resolve → admit → run. Unknown tools and denials - /// become error results the model can read and react to. - pub async fn execute(&self, name: &str, args: Value, ctx: &ToolContext) -> ToolResult { + /// Whether a call would be admitted (unknown tools are denied). + pub fn admit(&self, name: &str, args: &Value) -> Verdict { let Some(tool) = self.get(name) else { - return ToolResult::err(format!("Unknown tool: {name}")); + return Verdict::Deny(format!("Unknown tool: {name}")); }; let req = ActionRequest { tool: tool.as_ref(), - args: &args, + args, }; - if let Verdict::Deny(reason) = admission::admit(self.active_policies(), &req) { + admission::admit(self.active_policies(), &req) + } + + /// Run one call: resolve → admit → run. Unknown tools and denials + /// become error results the model can read and react to. + pub async fn execute(&self, name: &str, args: Value, ctx: &ToolContext) -> ToolResult { + if let Verdict::Deny(reason) = self.admit(name, &args) { return ToolResult::err(reason); } + let Some(tool) = self.get(name) else { + return ToolResult::err(format!("Unknown tool: {name}")); + }; if let Some(err) = args.get("parse_error").and_then(Value::as_str) { return ToolResult::err(format!( "Tool arguments were not valid JSON ({err}). Re-issue the call with valid JSON arguments." From bb3e8a37f7552ad79b0b2f7f46f6731a5523cb91 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 10:40:06 +0000 Subject: [PATCH 5/7] capability: describe every tool as a Capability with a Provider Tools declare who carries them out: a local tool, a run_code program, the subagent task board, or the human (ask_user). Admission requests and action records carry the provider, and the read-only subagent policy now admits the board's own capabilities by provider instead of by name. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014BrrmT45MDfJYo6atYUqsd --- AGENTS.md | 3 +- CONTEXT.md | 9 +++++ src/admission.rs | 4 ++ src/agent.rs | 4 +- src/capability.rs | 78 +++++++++++++++++++++++++++++++++++++++ src/journal.rs | 14 ++++++- src/main.rs | 1 + src/subagents/policies.rs | 5 ++- src/subagents/tools.rs | 3 ++ src/tools/ask_user.rs | 4 ++ src/tools/mod.rs | 19 ++++++++++ src/tools/run_code.rs | 3 ++ 12 files changed, 141 insertions(+), 6 deletions(-) create mode 100644 src/capability.rs diff --git a/AGENTS.md b/AGENTS.md index c331cd9..39c4df2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,6 +41,7 @@ src/ ├── session.rs # Session JSONL journal: records, append/rewrite, list, export, fork/handoff ├── trace.rs # Append-only JSONL run log (/traces/) ├── trace_viewer.rs # /tracing-viewer: loopback HTTP server (std::net + threads) + assets/trace_viewer.html +├── capability.rs # Capability (name + effect + recovery + Provider: tool/program/subagent/human) per registered tool ├── commands.rs # Frontend-neutral slash-command pieces (toggles, notices, /btw) ├── background.rs # Process-wide channel for events outside a turn (subagents, skill reviews) ├── skills.rs # SKILL.md discovery; the bundled daily pack (assets/daily_skills, include_dir!) @@ -128,6 +129,6 @@ CI (`.github/workflows/ci.yml`) runs exactly these three. ## Adding Things -- **Tool**: implement `Tool` in `src/tools/.rs` (`name`/`description`/`parameters` + `run()`; declare its `effect()` (`effect.rs`: read/fetch/session/write/mutate/exec — `replay_safe`/`mutates` derive from it; the default is `exec`), override `recovery`/`program_callable` when needed; resolve paths with `resolve_path`, take `mutation_lock(path)` around writes), add it to `ToolRegistry::core` or `set_daily`, and add tests in the same file +- **Tool**: implement `Tool` in `src/tools/.rs` (`name`/`description`/`parameters` + `run()`; declare its `effect()` (`effect.rs`: read/fetch/session/write/mutate/exec — `replay_safe`/`mutates` derive from it; the default is `exec`), override `recovery`/`provider`/`program_callable` when needed; resolve paths with `resolve_path`, take `mutation_lock(path)` around writes), add it to `ToolRegistry::core` or `set_daily`, and add tests in the same file - **Web-search backend**: extend `src/tools/web_search.rs`; users pick it with `[web_search] provider` - **Provider/model**: add specs in `llm/catalog.rs`; a new wire format → a new `Dialect` variant plus a module implementing `Decoder` and the request body. User-specific endpoint/key tweaks belong in `[providers.]` config, not the catalog diff --git a/CONTEXT.md b/CONTEXT.md index bff9cb9..489ce1d 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -81,6 +81,15 @@ proposals should name modules with these terms. ## Execution +- **Capability** — one thing a session can do (`capability.rs`): a + registered tool seen as name + effect + recovery + **provider**. The + model still calls tools by name; admission and the execution journal + work with capabilities. +- **Provider** — who carries a capability out: `tool` (local, in + process), `program` (`run_code`; its sub-calls are capabilities of + their own), `subagent` (the task board and its children) or `human` + (`ask_user`: the answer is the user's next message). + - **Effect** — what running a tool does (`effect.rs`): `read` (local reads), `fetch` (network reads), `session` (only this session's live state: task board, questions, the `run_code` transport), `write` diff --git a/src/admission.rs b/src/admission.rs index a70ee1e..2cd728b 100644 --- a/src/admission.rs +++ b/src/admission.rs @@ -16,6 +16,7 @@ use serde_json::Value; +use crate::capability::Provider; use crate::effect::Effect; use crate::tools::Tool; @@ -32,6 +33,9 @@ impl ActionRequest<'_> { pub fn effect(&self) -> Effect { self.tool.effect() } + pub fn provider(&self) -> Provider { + self.tool.provider() + } } /// A policy's answer. diff --git a/src/agent.rs b/src/agent.rs index ea4e478..5e5d9c0 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -1250,13 +1250,13 @@ impl Agent { let mut admitted = Vec::with_capacity(calls.len()); let mut intents: Vec = Vec::with_capacity(calls.len()); for tc in calls { - let effect = self.registry.get(tc.name()).map(|t| t.effect()); + let cap = self.registry.capability(tc.name()); let rec = match self.registry.admit(tc.name(), &tc.function.arguments) { Verdict::Allow => tool_action(tc, ActionPhase::Started), Verdict::Deny(reason) => tool_action(tc, ActionPhase::Denied).with_detail(reason), }; admitted.push(rec.phase == ActionPhase::Started); - intents.push(rec.with_effect(effect).to_line()); + intents.push(rec.with_capability(cap).to_line()); } self.journal(&intents); for tc in calls { diff --git a/src/capability.rs b/src/capability.rs new file mode 100644 index 0000000..bb6bc9a --- /dev/null +++ b/src/capability.rs @@ -0,0 +1,78 @@ +//! Capabilities: what a session can do, and who provides each one. +//! +//! The model still calls tools by name (its tool list does not change, so +//! the prompt cache stays intact). Underneath, every registered tool is a +//! [`Capability`]: a name, the [`Effect`] it has, how a crashed run is +//! recovered, and the [`Provider`] that carries it out. Admission and the +//! execution journal work in these terms, so a capability served by a +//! subagent or by the user is gated and recorded like any local tool. +//! +//! 🦀 Rust notes +//! - `Capability` is a plain value snapshot (`Copy`): reading it out of +//! the registry does not keep the tool borrowed. + +use serde::{Deserialize, Serialize}; + +use crate::effect::{Effect, Recovery}; +use crate::tools::Tool; + +/// Who carries a capability out. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)] +#[serde(rename_all = "snake_case")] +pub enum Provider { + /// A local tool run in this process (read, edit, bash, …). + #[default] + Tool, + /// A program the model writes (`run_code`): its sub-calls are + /// capabilities of their own, admitted one by one. + Program, + /// The task board and the subagents behind it (plan_tasks, task_*, + /// and a child's checkpoint / need / ask_main / finish). + Subagent, + /// The user: the answer arrives as their next message (ask_user). + Human, +} + +/// One capability as admission and the journal see it. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Capability { + pub name: &'static str, + pub effect: Effect, + pub recovery: Recovery, + pub provider: Provider, +} + +impl Capability { + pub fn of(tool: &dyn Tool) -> Self { + Self { + name: tool.name(), + effect: tool.effect(), + recovery: tool.recovery(), + provider: tool.provider(), + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::tools::ToolRegistry; + + #[test] + fn core_catalog_providers() { + let reg = ToolRegistry::core(true); + let caps = reg.capabilities(); + let cap = |n: &str| *caps.iter().find(|c| c.name == n).unwrap(); + assert_eq!(cap("read").provider, Provider::Tool); + assert_eq!(cap("read").recovery, Recovery::Replay); + assert_eq!(cap("run_code").provider, Provider::Program); + assert_eq!(cap("bash").effect, Effect::Exec); + } + + #[test] + fn ask_user_is_human() { + let c = Capability::of(&crate::tools::ask_user::AskUserTool); + assert_eq!(c.provider, Provider::Human); + assert!(!c.effect.mutates()); + } +} diff --git a/src/journal.rs b/src/journal.rs index 0dab76f..86c5122 100644 --- a/src/journal.rs +++ b/src/journal.rs @@ -25,6 +25,7 @@ use std::collections::HashSet; use serde::{Deserialize, Serialize}; use serde_json::Value; +use crate::capability::{Capability, Provider}; use crate::effect::Effect; /// What kind of action a record is about. @@ -63,6 +64,9 @@ pub struct ActionRecord { pub phase: ActionPhase, #[serde(default, skip_serializing_if = "Option::is_none")] pub effect: Option, + /// Who carried it out (absent for unknown tools and legacy records). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub provider: Option, /// A short note: the denial reason, a verify exit code. #[serde(default, skip_serializing_if = "Option::is_none")] pub detail: Option, @@ -78,6 +82,7 @@ impl ActionRecord { name: name.into(), phase, effect: None, + provider: None, detail: None, at: crate::session::now_iso(), } @@ -86,6 +91,12 @@ impl ActionRecord { self.effect = effect; self } + /// Effect and provider of a capability (`None` = an unknown tool). + pub fn with_capability(mut self, cap: Option) -> Self { + self.effect = cap.map(|c| c.effect); + self.provider = cap.map(|c| c.provider); + self + } pub fn with_detail(mut self, detail: impl Into) -> Self { self.detail = Some(detail.into()); self @@ -140,11 +151,12 @@ mod tests { #[test] fn line_round_trip() { let r = ActionRecord::new(ActionKind::Tool, "c1", "bash", ActionPhase::Started) - .with_effect(Some(Effect::Exec)); + .with_capability(Some(Capability::of(&crate::tools::bash::BashTool))); let line = r.to_line(); assert_eq!(line["type"], "action"); assert_eq!(line["phase"], "started"); assert_eq!(line["effect"], "exec"); + assert_eq!(line["provider"], "tool"); let mut obj = line.as_object().unwrap().clone(); obj.remove("type"); let back: ActionRecord = serde_json::from_value(Value::Object(obj)).unwrap(); diff --git a/src/main.rs b/src/main.rs index 7019cc3..db6eef2 100644 --- a/src/main.rs +++ b/src/main.rs @@ -16,6 +16,7 @@ mod agent; mod attachments; mod auth; mod background; +mod capability; mod cli_auth; mod commands; mod compaction; diff --git a/src/subagents/policies.rs b/src/subagents/policies.rs index 31d44a0..6c6f278 100644 --- a/src/subagents/policies.rs +++ b/src/subagents/policies.rs @@ -14,15 +14,16 @@ use std::sync::Weak; use serde_json::Value; use super::supervisor::Supervisor; -use super::tools::SUBAGENT_TOOL_NAMES; use crate::admission::{ActionRequest, Policy, Verdict}; +use crate::capability::Provider; pub struct ReadOnlyPolicy; impl Policy for ReadOnlyPolicy { fn admit(&self, req: &ActionRequest) -> Verdict { let tool = req.tool; - if SUBAGENT_TOOL_NAMES.contains(&tool.name()) || !tool.mutates() { + // The board's own capabilities (checkpoint, need, finish, …) stay callable. + if req.provider() == Provider::Subagent || !tool.mutates() { return Verdict::Allow; } Verdict::Deny(format!( diff --git a/src/subagents/tools.rs b/src/subagents/tools.rs index c26777e..eaa3607 100644 --- a/src/subagents/tools.rs +++ b/src/subagents/tools.rs @@ -51,6 +51,9 @@ macro_rules! task_tool { fn effect(&self) -> crate::effect::Effect { crate::effect::Effect::Session } + fn provider(&self) -> crate::capability::Provider { + crate::capability::Provider::Subagent + } fn recovery(&self) -> crate::effect::Recovery { if $safe { crate::effect::Recovery::Replay diff --git a/src/tools/ask_user.rs b/src/tools/ask_user.rs index 8e648c0..ab4f68e 100644 --- a/src/tools/ask_user.rs +++ b/src/tools/ask_user.rs @@ -52,6 +52,10 @@ impl Tool for AskUserTool { fn effect(&self) -> crate::effect::Effect { crate::effect::Effect::Session } + /// The answer comes from the user (their next message). + fn provider(&self) -> crate::capability::Provider { + crate::capability::Provider::Human + } /// Asking again after a crash is harmless. fn recovery(&self) -> crate::effect::Recovery { crate::effect::Recovery::Replay diff --git a/src/tools/mod.rs b/src/tools/mod.rs index 3d60607..2124469 100644 --- a/src/tools/mod.rs +++ b/src/tools/mod.rs @@ -38,6 +38,7 @@ use serde_json::{Value, json}; use tokio_util::sync::CancellationToken; use crate::admission::{self, ActionRequest, PlanPolicy, Policy, Verdict}; +use crate::capability::{Capability, Provider}; use crate::effect::{Effect, Recovery}; use crate::models::ToolResult; use crate::posture::Posture; @@ -103,6 +104,10 @@ pub trait Tool: Send + Sync { fn mutates(&self) -> bool { self.effect().mutates() } + /// Who carries the call out (`capability.rs`); local tools by default. + fn provider(&self) -> Provider { + Provider::Tool + } /// Whether a `run_code` program may call it. Tools that drive live /// session state (the task board) stay native tools beside `run_code`. fn program_callable(&self) -> bool { @@ -248,6 +253,20 @@ impl ToolRegistry { self.model_facing().map(|t| t.name()).collect() } + /// Every registered tool as a capability (hidden ones included). + #[cfg(test)] + pub fn capabilities(&self) -> Vec { + self.tools + .iter() + .map(|t| Capability::of(t.as_ref())) + .collect() + } + + /// One registered tool as a capability. + pub fn capability(&self, name: &str) -> Option { + self.get(name).map(|t| Capability::of(t.as_ref())) + } + /// Every registered tool name (programmable ones included). pub fn all_names(&self) -> Vec<&'static str> { self.tools.iter().map(|t| t.name()).collect() diff --git a/src/tools/run_code.rs b/src/tools/run_code.rs index c5a395a..688431a 100644 --- a/src/tools/run_code.rs +++ b/src/tools/run_code.rs @@ -267,6 +267,9 @@ impl Tool for RunCodeTool { fn effect(&self) -> crate::effect::Effect { crate::effect::Effect::Session } + fn provider(&self) -> crate::capability::Provider { + crate::capability::Provider::Program + } fn program_callable(&self) -> bool { false } From 35b27b8f8d03731b3d25b5c959ad6710b6f86c4f Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 11:03:44 +0000 Subject: [PATCH 6/7] capability: journal verify and run_code sub-calls with a provider, show it in the TUI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - goal verify actions carry the new runtime provider - run_code sub-calls are journaled as their own actions (parent = the run_code call) through ToolContext.journal - AgentEvent::ToolCall carries the provider: TUI tool cards show it (read · tool), as do headless lines, --json events and the trace Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014BrrmT45MDfJYo6atYUqsd --- AGENTS.md | 4 +- CONTEXT.md | 8 +++- src/agent.rs | 12 +++++- src/capability.rs | 28 ++++++++++++++ src/commands.rs | 2 +- src/headless.rs | 12 ++++-- src/journal.rs | 18 +++++++++ src/learn.rs | 1 + src/pump.rs | 2 + src/tools/mod.rs | 4 ++ src/tools/run_code.rs | 87 ++++++++++++++++++++++++++++++++++++++++++- src/tui/app.rs | 10 ++++- src/tui/chat.rs | 44 +++++++++++++++++++++- 13 files changed, 217 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 39c4df2..73e6eec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,7 +41,7 @@ src/ ├── session.rs # Session JSONL journal: records, append/rewrite, list, export, fork/handoff ├── trace.rs # Append-only JSONL run log (/traces/) ├── trace_viewer.rs # /tracing-viewer: loopback HTTP server (std::net + threads) + assets/trace_viewer.html -├── capability.rs # Capability (name + effect + recovery + Provider: tool/program/subagent/human) per registered tool +├── capability.rs # Capability (name + effect + recovery + Provider: tool/program/subagent/human/runtime) per registered tool; tool cards show the provider ├── commands.rs # Frontend-neutral slash-command pieces (toggles, notices, /btw) ├── background.rs # Process-wide channel for events outside a turn (subagents, skill reviews) ├── skills.rs # SKILL.md discovery; the bundled daily pack (assets/daily_skills, include_dir!) @@ -96,7 +96,7 @@ Providers/models live in `llm/catalog.rs`; unknown models get generic OpenAI-com [providers.] # base_url / api_key / api_key_env / headers ``` -`/model` rebuilds the client mid-session (refused while busy) and persists via `toml_edit`. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls from the execution journal (`journal.rs`): each call appends an `action` record `started` (or `denied`) before it runs and `completed`/`failed` once its result is in (goal verify runs too, kind `verify`), so a crashed call is re-run on the next turn if its tool's recovery is `replay` (read/fetch effects: read/grep/find/ls, web tools), otherwise marked "ran to the end, result lost" (finished), "may have partially run" (started only) or "did not run" (nothing). Legacy `tool_intent` records load as `started`. `/export [path]` merges meta + trace + messages (Markdown if `.md`). `/fork [n]` copies the active history (first n user turns) into a new session, `/handoff ` starts a clean linked session from a note; both record `parent_session` and leave the parent untouched. +`/model` rebuilds the client mid-session (refused while busy) and persists via `toml_edit`. Sessions resume via `--continue` / `--resume` / `/sessions`; resume repairs dangling tool calls from the execution journal (`journal.rs`): each call appends an `action` record `started` (or `denied`) before it runs and `completed`/`failed` once its result is in (goal verify runs too, kind `verify`, provider `runtime`; `run_code` sub-calls get their own records with `parent`), so a crashed call is re-run on the next turn if its tool's recovery is `replay` (read/fetch effects: read/grep/find/ls, web tools), otherwise marked "ran to the end, result lost" (finished), "may have partially run" (started only) or "did not run" (nothing). Legacy `tool_intent` records load as `started`. `/export [path]` merges meta + trace + messages (Markdown if `.md`). `/fork [n]` copies the active history (first n user turns) into a new session, `/handoff ` starts a clean linked session from a note; both record `parent_session` and leave the parent untouched. Skills: `~/.agents/skills//SKILL.md` (global, shared with other agents; lowest of the non-bundled), `~/.limbo/skills//SKILL.md` (user) and `/.agents/skills//SKILL.md` (project, wins collisions); daily sessions also see the bundled pack (lowest, unpacked to `~/.limbo/daily/bundled//`) and `~/.limbo/daily/skills/` (highest), coding sessions never do — injected as an `` catalog in the system prompt and invocable via `/ [args]`. diff --git a/CONTEXT.md b/CONTEXT.md index 489ce1d..32cdb38 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -46,7 +46,8 @@ proposals should name modules with these terms. - **Execution journal** — the `action` records in the session file (`journal.rs`): every tool call (and `/goal` verify run) appends `started` or `denied` before it runs and `completed` / `failed` when - its result is in. Resume reads them as an **action log**: a call with + its result is in. A `run_code` program's sub-calls get records of + their own, with `parent` = the `run_code` call id. Resume reads them as an **action log**: a call with no result message is "did not run" (nothing), "may have partially run" (started only) or "result lost" (finished). - **Steer** — a user message queued mid-turn, injected at consistency @@ -88,7 +89,10 @@ proposals should name modules with these terms. - **Provider** — who carries a capability out: `tool` (local, in process), `program` (`run_code`; its sub-calls are capabilities of their own), `subagent` (the task board and its children) or `human` - (`ask_user`: the answer is the user's next message). + (`ask_user`: the answer is the user's next message), or `runtime` (the + harness itself: `/goal` verify commands). Shown on TUI tool cards + (`read · tool`), in headless output, the trace's `tool_call` events and + every `action` record. - **Effect** — what running a tool does (`effect.rs`): `read` (local reads), `fetch` (network reads), `session` (only this session's live diff --git a/src/agent.rs b/src/agent.rs index 5e5d9c0..21c15a6 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -32,6 +32,7 @@ use tokio_util::sync::CancellationToken; use crate::admission::Verdict; use crate::attachments::build_user_content; +use crate::capability::Provider; use crate::compaction::{ self, build_summary_prompt, find_split_point, is_summary_message, make_summary_message, summary_body, @@ -67,6 +68,8 @@ pub enum AgentEvent { id: String, name: String, arguments: Value, + /// Who carries the call out (`tool` for unknown names). + provider: Provider, }, /// A line of live progress from a long-running tool (subagents). ToolProgress { @@ -931,6 +934,7 @@ impl Agent { call_id: call_id.to_string(), events: Some(tx.clone()), registry: Some(self.registry.clone()), + journal: self.file_created.then(|| self.session_path.clone()), } } @@ -1260,14 +1264,20 @@ impl Agent { } self.journal(&intents); for tc in calls { + let provider = self + .registry + .capability(tc.name()) + .map(|c| c.provider) + .unwrap_or_default(); let _ = tx.send(AgentEvent::ToolCall { id: tc.id.clone(), name: tc.name().into(), arguments: tc.function.arguments.clone(), + provider, }); self.trace.log( "tool_call", - json!({"turn": self.turn_count, "iteration": self.iteration, "id": tc.id, "name": tc.name(), "arguments": tc.function.arguments}), + json!({"turn": self.turn_count, "iteration": self.iteration, "id": tc.id, "name": tc.name(), "arguments": tc.function.arguments, "provider": provider}), ); } let started_at = utc_now_iso(); diff --git a/src/capability.rs b/src/capability.rs index bb6bc9a..515d18f 100644 --- a/src/capability.rs +++ b/src/capability.rs @@ -31,6 +31,21 @@ pub enum Provider { Subagent, /// The user: the answer arrives as their next message (ask_user). Human, + /// The harness itself, not a model call: `/goal` verify commands. + Runtime, +} + +impl Provider { + /// The word shown in tool cards, the trace and the journal. + pub fn label(self) -> &'static str { + match self { + Provider::Tool => "tool", + Provider::Program => "program", + Provider::Subagent => "subagent", + Provider::Human => "human", + Provider::Runtime => "runtime", + } + } } /// One capability as admission and the journal see it. @@ -69,6 +84,19 @@ mod tests { assert_eq!(cap("bash").effect, Effect::Exec); } + #[test] + fn labels_match_serde() { + for p in [ + Provider::Tool, + Provider::Program, + Provider::Subagent, + Provider::Human, + Provider::Runtime, + ] { + assert_eq!(serde_json::to_value(p).unwrap(), p.label()); + } + } + #[test] fn ask_user_is_human() { let c = Capability::of(&crate::tools::ask_user::AskUserTool); diff --git a/src/commands.rs b/src/commands.rs index 91ed69f..b392576 100644 --- a/src/commands.rs +++ b/src/commands.rs @@ -115,7 +115,7 @@ pub fn goal_event_line(ev: &crate::agent::AgentEvent) -> Option { command, round, max_rounds, - } => format!("🔍 第 {round}/{max_rounds} 轮验收:`{command}`"), + } => format!("🔍 第 {round}/{max_rounds} 轮验收:`{command}` · runtime"), GoalVerifyResult { exit_code, cancelled, diff --git a/src/headless.rs b/src/headless.rs index cae5f76..1a6f983 100644 --- a/src/headless.rs +++ b/src/headless.rs @@ -42,7 +42,10 @@ fn event_json(ev: &AgentEvent) -> serde_json::Value { id, name, arguments, - } => json!({"type": "tool_call", "id": id, "name": name, "arguments": arguments}), + provider, + } => { + json!({"type": "tool_call", "id": id, "name": name, "arguments": arguments, "provider": provider}) + } AgentEvent::ToolProgress { id, line } => { json!({"type": "tool_progress", "id": id, "line": line}) } @@ -151,7 +154,10 @@ impl Printer { } AgentEvent::Thinking(_) | AgentEvent::TurnStart | AgentEvent::Usage { .. } => {} AgentEvent::ToolCall { - name, arguments, .. + name, + arguments, + provider, + .. } => { let desc = if name == "run_code" { arguments @@ -162,7 +168,7 @@ impl Printer { } else { describe_call(name, arguments) }; - self.line(&format!("⚙ {desc}")); + self.line(&format!("⚙ {desc} · {}", provider.label())); } AgentEvent::ToolProgress { line, .. } => self.line(&format!(" │ {line}")), AgentEvent::ToolResult { diff --git a/src/journal.rs b/src/journal.rs index 86c5122..e20df99 100644 --- a/src/journal.rs +++ b/src/journal.rs @@ -67,6 +67,9 @@ pub struct ActionRecord { /// Who carried it out (absent for unknown tools and legacy records). #[serde(default, skip_serializing_if = "Option::is_none")] pub provider: Option, + /// The call this one ran inside (a `run_code` program's sub-calls). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub parent: Option, /// A short note: the denial reason, a verify exit code. #[serde(default, skip_serializing_if = "Option::is_none")] pub detail: Option, @@ -83,6 +86,7 @@ impl ActionRecord { phase, effect: None, provider: None, + parent: None, detail: None, at: crate::session::now_iso(), } @@ -91,6 +95,14 @@ impl ActionRecord { self.effect = effect; self } + pub fn with_provider(mut self, provider: Provider) -> Self { + self.provider = Some(provider); + self + } + pub fn with_parent(mut self, parent: &str) -> Self { + self.parent = Some(parent.into()); + self + } /// Effect and provider of a capability (`None` = an unknown tool). pub fn with_capability(mut self, cap: Option) -> Self { self.effect = cap.map(|c| c.effect); @@ -113,6 +125,12 @@ impl ActionRecord { } } +/// Append records to a session file (a no-op until the file exists). +pub fn append(path: &std::path::Path, records: &[ActionRecord]) { + let lines: Vec = records.iter().map(ActionRecord::to_line).collect(); + let _ = crate::session::append_lines(path, &lines); +} + /// What the journal knows about the tool calls of one session. #[derive(Debug, Default)] pub struct ActionLog { diff --git a/src/learn.rs b/src/learn.rs index a5fb81e..126e2bb 100644 --- a/src/learn.rs +++ b/src/learn.rs @@ -232,6 +232,7 @@ mod tests { id: "1".into(), name: "bash".into(), arguments: json!({}), + provider: crate::capability::Provider::Tool, } } fn result(name: &str, ok: bool) -> AgentEvent { diff --git a/src/pump.rs b/src/pump.rs index 238b997..ad4d886 100644 --- a/src/pump.rs +++ b/src/pump.rs @@ -18,6 +18,7 @@ use serde_json::json; use tokio_util::sync::CancellationToken; use crate::agent::{Agent, AgentEvent, EventTx, FOLLOW_UP, STEER}; +use crate::capability::Provider; use crate::effect::Effect; use crate::goal::{ self, GoalState, STATUS_ACTIVE, STATUS_CLEARED, STATUS_EXHAUSTED, STATUS_PASSED, @@ -229,6 +230,7 @@ async fn run_once( let verify_action = |phase| { ActionRecord::new(ActionKind::Verify, &action_id, &state.verify_command, phase) .with_effect(Some(Effect::Exec)) + .with_provider(Provider::Runtime) }; agent.journal_action(&verify_action(ActionPhase::Started)); let result = run_verify( diff --git a/src/tools/mod.rs b/src/tools/mod.rs index 2124469..cd8c30a 100644 --- a/src/tools/mod.rs +++ b/src/tools/mod.rs @@ -56,6 +56,9 @@ pub struct ToolContext { pub events: Option, /// The registry running this call (`run_code` dispatches through it). pub registry: Option, + /// The session file, for journaling nested calls (`run_code`'s + /// sub-calls); `None` outside a session. + pub journal: Option, } impl ToolContext { @@ -68,6 +71,7 @@ impl ToolContext { call_id: "call".into(), events: None, registry: None, + journal: None, } } pub fn progress(&self, line: impl Into) { diff --git a/src/tools/run_code.rs b/src/tools/run_code.rs index 688431a..8a77290 100644 --- a/src/tools/run_code.rs +++ b/src/tools/run_code.rs @@ -102,6 +102,42 @@ fn parameter_list(parameters: &Value) -> String { .join(", ") } +/// One program sub-call: admitted and run through the registry like any +/// call, and journaled as its own action (`parent` = the `run_code` call). +async fn run_sub_call( + registry: &ToolRegistry, + name: &str, + args: Value, + sub: &ToolContext, +) -> ToolResult { + use crate::journal::{ActionKind, ActionPhase, ActionRecord, append}; + let parent = sub.call_id.rsplit_once('.').map_or("", |(p, _)| p); + let record = |phase| { + ActionRecord::new(ActionKind::Tool, &sub.call_id, name, phase) + .with_capability(registry.capability(name)) + .with_parent(parent) + }; + let admitted = registry.admit(name, &args) == crate::admission::Verdict::Allow; + if let Some(path) = &sub.journal { + let phase = if admitted { + ActionPhase::Started + } else { + ActionPhase::Denied + }; + append(path, &[record(phase)]); + } + let r = registry.execute(name, args, sub).await; + if let (true, Some(path)) = (admitted, &sub.journal) { + let phase = if r.success { + ActionPhase::Completed + } else { + ActionPhase::Failed + }; + append(path, &[record(phase)]); + } + r +} + /// The SDK section of the system prompt, derived from the registry. pub fn render_tools_sdk(registry: &ToolRegistry) -> String { let mut lines = vec![ @@ -361,12 +397,13 @@ async fn run_program( let registry = registry.clone(); let mut sub = ctx.clone(); sub.call_id = format!("{}.{}", ctx.call_id, &crate::models::new_id()[..6]); - ctx.progress(format!("tools.{name}(…)")); + let provider = registry.capability(&name).map(|c| c.provider).unwrap_or_default(); + ctx.progress(format!("tools.{name}(…) · {}", provider.label())); running.push(async move { let r = if registry.get(&name).is_some_and(|t| !t.program_callable()) { ToolResult::err(format!("{name} cannot be called from a program; call it as a tool")) } else { - registry.execute(&name, call_args, &sub).await + run_sub_call(®istry, &name, call_args, &sub).await }; (id, r) }); @@ -468,6 +505,52 @@ mod tests { assert!(out.contains("{\"n\": 2}"), "{out}"); } + #[tokio::test] + async fn sub_calls_are_journaled() { + if !has_python() { + return; + } + let dir = tempfile::tempdir().unwrap(); + let journal = dir.path().join("s.jsonl"); + std::fs::write(&journal, "").unwrap(); + struct NoWrite; + impl crate::admission::Policy for NoWrite { + fn admit(&self, req: &crate::admission::ActionRequest) -> crate::admission::Verdict { + match req.name() { + "write" => crate::admission::Verdict::Deny("no".into()), + _ => crate::admission::Verdict::Allow, + } + } + } + let mut reg = ToolRegistry::core(true); + reg.policies.push(std::sync::Arc::new(NoWrite)); + let mut ctx = ToolContext::simple(dir.path()); + ctx.call_id = "rc1".into(); + ctx.journal = Some(journal.clone()); + let code = "await tools.ls(path='.')\ntry:\n await tools.write(path='x', content='y')\nexcept ToolCallError:\n pass"; + let r = reg + .execute("run_code", json!({"code": code, "description": "t"}), &ctx) + .await; + assert!(r.success, "{:?}", r.error); + let recs: Vec = std::fs::read_to_string(&journal) + .unwrap() + .lines() + .map(|l| serde_json::from_str(l).unwrap()) + .collect(); + let phases: Vec<(&str, &str)> = recs + .iter() + .map(|r| (r["name"].as_str().unwrap(), r["phase"].as_str().unwrap())) + .collect(); + assert_eq!( + phases, + [("ls", "started"), ("ls", "completed"), ("write", "denied")] + ); + assert!( + recs.iter() + .all(|r| r["parent"] == "rc1" && r["provider"] == "tool") + ); + } + #[tokio::test] async fn exceptions_and_timeouts() { if !has_python() { diff --git a/src/tui/app.rs b/src/tui/app.rs index 512edb8..a9af3d2 100644 --- a/src/tui/app.rs +++ b/src/tui/app.rs @@ -331,7 +331,9 @@ impl App { .motion .clone() .or_else(|| std::env::var("LIMBO_MOTION").ok()); - let entries = entries_from_history(&agent.messages); + let entries = entries_from_history(&agent.messages, |n| { + agent.registry.capability(n).map(|c| c.provider) + }); let skills = discover_skills(&agent.workdir, agent.daily_mode()); let skills_scope = (agent.workdir.clone(), agent.daily_mode()); let sup = agent.supervisor.clone(); @@ -845,12 +847,14 @@ impl App { id, name, arguments, + provider, } => { self.close_live(); self.activity = Activity::Tool(name.clone()); self.entries.push(Entry::new(EntryKind::Tool { id, name, + provider: Some(provider), args: arguments, status: ToolStatus::Running, output: String::new(), @@ -2030,7 +2034,9 @@ impl App { } self.steer = agent.steer.clone(); self.sup = agent.supervisor.clone(); - self.entries = entries_from_history(&agent.messages); + self.entries = entries_from_history(&agent.messages, |n| { + agent.registry.capability(n).map(|c| c.provider) + }); // The target may be in the other mode: skills and the Dawn // look follow the session that is now live. self.skills = discover_skills(&agent.workdir, agent.daily_mode()); diff --git a/src/tui/chat.rs b/src/tui/chat.rs index 7a991bf..acf1b08 100644 --- a/src/tui/chat.rs +++ b/src/tui/chat.rs @@ -13,6 +13,7 @@ use serde_json::Value; use super::markdown; use super::text::{ellipsize, str_width, wrap_line}; use super::theme::{SPINNER, Theme, gradient_spans}; +use crate::capability::Provider; use crate::compaction::is_summary_message; use crate::models::{Message, Role}; use crate::subagents::describe_call; @@ -50,6 +51,8 @@ pub enum EntryKind { Tool { id: String, name: String, + /// Who carried the call out; `None` for a tool no longer registered. + provider: Option, args: Value, status: ToolStatus, output: String, @@ -268,6 +271,7 @@ fn render_entry( } EntryKind::Tool { name, + provider, args, status, output, @@ -293,7 +297,10 @@ fn render_entry( _ => String::new(), }; let right = format!(" {mark} {elapsed}"); - let label_w = str_width(name) + 4; + let tag = provider + .map(|p| format!(" · {}", p.label())) + .unwrap_or_default(); + let label_w = str_width(name) + str_width(&tag) + 4; let avail = width.saturating_sub(label_w + str_width(&right) + 2); let detail = ellipsize(&detail, avail); let pad = width.saturating_sub(label_w + str_width(&detail) + str_width(&right) + 1); @@ -306,6 +313,7 @@ fn render_entry( name.clone(), Style::default().fg(t.accent3).add_modifier(Modifier::BOLD), ), + Span::styled(tag, Style::default().fg(t.faint)), Span::raw(" "), Span::styled(detail, Style::default().fg(t.dim)), Span::styled(" ".repeat(pad), Style::default()), @@ -407,7 +415,11 @@ fn render_entry( } /// Rebuild transcript entries from a loaded history. -pub fn entries_from_history(messages: &[Message]) -> Vec { +/// `provider` names who carries a tool out (from the live registry). +pub fn entries_from_history( + messages: &[Message], + provider: impl Fn(&str) -> Option, +) -> Vec { let mut out: Vec = Vec::new(); for m in messages { match m.role { @@ -438,6 +450,7 @@ pub fn entries_from_history(messages: &[Message]) -> Vec { out.push(Entry::new(EntryKind::Tool { id: c.id.clone(), name: c.function.name.clone(), + provider: provider(&c.function.name), args: c.function.arguments.clone(), status: ToolStatus::Running, output: String::new(), @@ -478,3 +491,30 @@ pub fn entries_from_history(messages: &[Message]) -> Vec { } out } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn tool_card_shows_provider() { + let mut e = Entry::new(EntryKind::Tool { + id: "1".into(), + name: "run_code".into(), + provider: Some(Provider::Program), + args: serde_json::json!({"code": "print(1)", "description": "count"}), + status: ToolStatus::Ok, + output: String::new(), + progress: vec![], + started: Instant::now(), + secs: Some(1.0), + }); + let theme = super::super::theme::by_name(None); + let head: String = e.lines(&theme, 80, false, false, 0)[0] + .spans + .iter() + .map(|s| s.content.as_ref()) + .collect(); + assert!(head.contains("run_code · program"), "{head}"); + } +} From 5bb0c664629e3e9f0873ac3890f62c1d0f16dc6d Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 6 Nov 2026 11:09:29 +0000 Subject: [PATCH 7/7] journal: completed/failed tool records carry effect and provider too Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_014BrrmT45MDfJYo6atYUqsd --- src/agent.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/agent.rs b/src/agent.rs index 21c15a6..c319ea4 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -788,7 +788,8 @@ impl Agent { } else { ActionPhase::Failed }; - self.journal_action(&tool_action(tc, phase)); + let cap = self.registry.capability(tc.name()); + self.journal_action(&tool_action(tc, phase).with_capability(cap)); } // -- token accounting ------------------------------------------------------