Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 "<prompt>"` 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.

Expand Down Expand Up @@ -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 (<session dir>/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!)
Expand All @@ -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 + <project_facts> scan), hooks.rs (read-only/no-edit/
│ # profiles.rs (agent profiles + <project_facts> 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
Expand Down Expand Up @@ -91,7 +96,7 @@ Providers/models live in `llm/catalog.rs`; unknown models get generic OpenAI-com
[providers.<id>] # 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 <note>` 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 <note>` starts a clean linked session from a note; both record `parent_session` and leave the parent untouched.

Skills: `~/.agents/skills/<name>/SKILL.md` (global, shared with other agents; lowest of the non-bundled), `~/.limbo/skills/<name>/SKILL.md` (user) and `<workdir>/.agents/skills/<name>/SKILL.md` (project, wins collisions); daily sessions also see the bundled pack (lowest, unpacked to `~/.limbo/daily/bundled/<version>/`) and `~/.limbo/daily/skills/` (highest), coding sessions never do — injected as an `<available_skills>` catalog in the system prompt and invocable via `/<name> [args]`.

Expand All @@ -101,7 +106,7 @@ Single column: status bar (state/elapsed/tokens/model/workdir/queue + goal and C

`/goal <text>` starts closed-loop mode: the first round proposes acceptance command(s) in a `<verify_proposal>` 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`.

Expand All @@ -124,6 +129,6 @@ CI (`.github/workflows/ci.yml`) runs exactly these three.

## Adding Things

- **Tool**: implement `Tool` in `src/tools/<name>.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/<name>.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.<id>]` config, not the catalog
52 changes: 51 additions & 1 deletion CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 4 additions & 2 deletions docs/session-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 排序、标题为空

Expand Down Expand Up @@ -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 仅作展示
Expand Down
Loading
Loading