diff --git a/AGENTS.md b/AGENTS.md index ac603b1..73e6eec 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 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. @@ -32,11 +32,16 @@ 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 +├── 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 +├── 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!) @@ -47,9 +52,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 @@ -91,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: 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 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]`. @@ -101,7 +106,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`. @@ -124,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()`; 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`/`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 6beeb49..32cdb38 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -41,8 +41,15 @@ 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. 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 points (loop top, turn end, run head). The steer queue owns queueing semantics — id generation, FIFO, and the cancel boundary (an @@ -60,6 +67,49 @@ 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 + +- **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), 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 + 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 `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` + 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). + ## 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/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/admission.rs b/src/admission.rs new file mode 100644 index 0000000..2cd728b --- /dev/null +++ b/src/admission.rs @@ -0,0 +1,129 @@ +//! 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::capability::Provider; +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() + } + pub fn provider(&self) -> Provider { + self.tool.provider() + } +} + +/// 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/agent.rs b/src/agent.rs index 7d9a3ca..c319ea4 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -30,17 +30,21 @@ 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::capability::Provider; use crate::compaction::{ self, build_summary_prompt, find_split_point, is_summary_message, make_summary_message, summary_body, }; 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}; 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; @@ -64,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 { @@ -312,7 +318,7 @@ impl Agent { meta, messages, compactions, - intents, + actions, queue, raw_message_ids, } = session::load_session_full(path)?; @@ -334,17 +340,14 @@ 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; - 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; @@ -564,14 +567,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 +626,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. @@ -778,6 +775,23 @@ 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 + }; + let cap = self.registry.capability(tc.name()); + self.journal_action(&tool_action(tc, phase).with_capability(cap)); + } + // -- token accounting ------------------------------------------------------ fn estimated_next_prompt_tokens(&self) -> u64 { @@ -921,6 +935,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()), } } @@ -1236,27 +1251,34 @@ impl Agent { tx: &EventTx, cancel: &CancellationToken, ) { - // Commit each call's intent before any side effect runs. - 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) - }) - .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 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_capability(cap).to_line()); + } 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(); @@ -1277,6 +1299,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(), @@ -1295,6 +1320,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(), @@ -1463,9 +1491,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 } @@ -1513,9 +1539,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)); @@ -1537,13 +1561,16 @@ 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); } } +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(); @@ -1702,7 +1729,12 @@ pub(crate) mod tests { )]); agent.messages.push(a); agent.checkpoint(); - agent.journal(&[session::tool_intent_record("w1", "write", false)]); + agent.journal_action(&ActionRecord::new( + ActionKind::Tool, + "w1", + "write", + ActionPhase::Started, + )); // "crash" here, then resume let resumed = Agent::resume( test_config("http://127.0.0.1:9/v1"), diff --git a/src/capability.rs b/src/capability.rs new file mode 100644 index 0000000..515d18f --- /dev/null +++ b/src/capability.rs @@ -0,0 +1,106 @@ +//! 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, + /// 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. +#[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 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); + assert_eq!(c.provider, Provider::Human); + assert!(!c.effect.mutates()); + } +} 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/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/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/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..e20df99 --- /dev/null +++ b/src/journal.rs @@ -0,0 +1,197 @@ +//! 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::capability::{Capability, Provider}; +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, + /// 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, + #[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, + provider: None, + parent: None, + detail: None, + at: crate::session::now_iso(), + } + } + pub fn with_effect(mut self, effect: Option) -> Self { + 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); + self.provider = cap.map(|c| c.provider); + 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) + } +} + +/// 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 { + 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_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(); + 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/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/main.rs b/src/main.rs index ef5c253..db6eef2 100644 --- a/src/main.rs +++ b/src/main.rs @@ -11,22 +11,27 @@ //! - `tui` — the ratatui + tachyonfx interface //! - `headless` — plain-terminal and JSON frontends +mod admission; mod agent; mod attachments; mod auth; mod background; +mod capability; mod cli_auth; mod commands; mod compaction; mod config; +mod effect; mod goal; mod headless; mod history; mod integrations; +mod journal; 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..ad4d886 100644 --- a/src/pump.rs +++ b/src/pump.rs @@ -18,11 +18,15 @@ 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, 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; /// Run one task to completion (or interruption). @@ -206,6 +210,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; }; @@ -218,6 +226,13 @@ 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)) + .with_provider(Provider::Runtime) + }; + agent.journal_action(&verify_action(ActionPhase::Started)); let result = run_verify( &state.verify_command, &agent.workdir, @@ -225,6 +240,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 3b081e7..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,6 +140,8 @@ 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, @@ -185,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). @@ -202,18 +207,6 @@ 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 { - record( - "tool_intent", - ToolIntentRecord { - call_id: call_id.into(), - name: name.into(), - replay: if replay_safe { "safe" } else { "unsafe" }.into(), - created_at: now_iso(), - }, - ) -} - pub fn compaction_record(c: &CompactionRecord) -> Value { record("compaction", c) } @@ -396,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?; @@ -430,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) { @@ -478,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, }) @@ -656,7 +661,8 @@ mod tests { meta_patch_record(&patched), queued_record(&q), json!({"type": "future_thing", "x": 1}), - tool_intent_record("c1", "bash", false), + json!({"type": "tool_intent", "call_id": "c1", "name": "bash", "replay": "unsafe"}), + ActionRecord::new(ActionKind::Tool, "c2", "read", ActionPhase::Completed).to_line(), ], ) .unwrap(); @@ -671,7 +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.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/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 59% rename from src/subagents/hooks.rs rename to src/subagents/policies.rs index fff9f62..6c6f278 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; @@ -14,47 +14,51 @@ use std::sync::Weak; 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}; +use crate::capability::Provider; -pub struct ReadOnlyHook; +pub struct ReadOnlyPolicy; -impl ToolHook for ReadOnlyHook { - fn before_tool(&self, tool: &dyn Tool, _args: &Value) -> Result<(), String> { - if SUBAGENT_TOOL_NAMES.contains(&tool.name()) || !tool.mutates() { - return Ok(()); +impl Policy for ReadOnlyPolicy { + fn admit(&self, req: &ActionRequest) -> Verdict { + let tool = req.tool; + // The board's own capabilities (checkpoint, need, finish, …) stay callable. + if req.provider() == Provider::Subagent || !tool.mutates() { + 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 +110,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 +137,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 +156,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/subagents/tools.rs b/src/subagents/tools.rs index f738a56..eaa3607 100644 --- a/src/subagents/tools.rs +++ b/src/subagents/tools.rs @@ -47,11 +47,19 @@ 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 provider(&self) -> crate::capability::Provider { + crate::capability::Provider::Subagent + } + 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..ab4f68e 100644 --- a/src/tools/ask_user.rs +++ b/src/tools/ask_user.rs @@ -49,8 +49,16 @@ impl Tool for AskUserTool { "required": ["question"], }) } - fn replay_safe(&self) -> bool { - true + 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 } 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..cd8c30a 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,7 +37,11 @@ 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::capability::{Capability, Provider}; +use crate::effect::{Effect, Recovery}; use crate::models::ToolResult; +use crate::posture::Posture; /// Everything a tool call may need besides its arguments. #[derive(Clone)] @@ -51,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 { @@ -63,6 +71,7 @@ impl ToolContext { call_id: "call".into(), events: None, registry: None, + journal: None, } } pub fn progress(&self, line: impl Into) { @@ -81,13 +90,27 @@ 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() + } + /// 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`. @@ -97,16 +120,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", @@ -120,11 +133,14 @@ 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, - pub hooks: Vec>, + /// 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. + pub policies: Vec>, /// Set when the `memory` tool ran (daily memory nudge bookkeeping). pub memory_written: Arc, /// Where `session_search` looks. @@ -152,10 +168,8 @@ impl ToolRegistry { tools.push(Arc::new(run_code::RunCodeTool)); Self { tools, - plan_mode: false, - daily_mode: false, - code_mode: false, - hooks: Vec::new(), + posture: Posture::default(), + policies: Vec::new(), memory_written: Arc::new(AtomicBool::new(false)), session_dir: crate::config::limbo_home().join("sessions"), } @@ -174,9 +188,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; @@ -223,18 +257,39 @@ 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() } + /// 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> { 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" @@ -264,23 +319,27 @@ impl ToolRegistry { .collect() } - /// Run one call. Unknown tools, plan-mode and hook blocks become error - /// results the model can read and react to. + /// 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 Verdict::Deny(format!("Unknown tool: {name}")); + }; + let req = ActionRequest { + tool: tool.as_ref(), + args, + }; + 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 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); - } - } 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." @@ -383,10 +442,27 @@ 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); - reg.plan_mode = true; + reg.posture = reg.posture.with_plan(true); assert!(!reg.names().contains(&"write")); let ctx = ToolContext::simple("/tmp"); let r = reg 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..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![ @@ -264,8 +300,11 @@ 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 provider(&self) -> crate::capability::Provider { + crate::capability::Provider::Program } fn program_callable(&self) -> bool { false @@ -358,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) }); @@ -465,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/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() } 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}"); + } +}