limbo-code 0.3__tar.gz → 0.3.5__tar.gz

{limbo_code-0.3 → limbo_code-0.3.5}/AGENTS.md

@@ -39,7 +39,8 @@ src/limbo/
 │                     # same TurnPump seam as the TUI, no textual import
 ├── conversation.py   # Conversation: the live agent+pump pair both frontends drive —
 │                     # new/switch/fork/handoff (load before close), lifecycle reporting
-│                     # (drive), /goal verify-proposal flow
+│                     # (drive), /goal verify-proposal flow, the subagent supervisor
+│                     # (subscribe/start_background/take_wake_input)
 ├── sessions.py       # Session JSONL file format: records, save/load/list/export
 ├── journal.py        # SessionJournal: when/in what order records reach the file
 │                     # (watermark, rewrite fallback, queue re-journal, meta patches)
@@ -51,6 +52,19 @@ src/limbo/
 │                     # osc7501.py (terminal program status; TTY only, LIMBO_PROGRAM_STATUS=0
 │                     # opts out, tmux passthrough); create_reporters() fans out
 ├── skills.py         # SKILL.md discovery (user + project dirs)
+├── daily_skills/     # Bundled daily starter skills (ported from hermes-agent, MIT; excluded
+│                     # from ruff/mypy)
+├── daily.py          # Daily mode notices (docs/daily-mode.md); the posture itself is
+│                     # ToolRegistry.daily_mode + prompt.py + SessionMeta.daily_mode
+├── memory.py         # Persistent memory (~/.limbo/memory/USER.md, NOTES.md): MemoryStore
+│                     # (capped, atomic batch ops, .bak), frozen per-session MemorySnapshot
+├── subagents/        # Background subagents (docs/subagents.md): board.py (event-sourced
+│                     # task board + pure reconcile()), supervisor.py (scheduler, runners,
+│                     # notice delivery, user/main verbs), tools.py (main: plan_tasks/
+│                     # task_status/task_send/answer/task_control; child: checkpoint/need/
+│                     # ask_main/finish/propose_task), profiles.py (agent profiles),
+│                     # project_scan.py (<project_facts>), hooks.py (read-only/no-edit/path
+│                     # claims), worktree.py, commands.py (/task /agents @name), events.py
 ├── llm/              # catalog.py (provider/model specs), factory.py (dialect→client),
 │                     # openai_client.py, anthropic_client.py, responses_client.py, retry.py, sse.py,
 │                     # usage.py (token accounting: usage normalization + prompt-size estimation),
@@ -58,9 +72,15 @@ src/limbo/
 ├── tools/            # base.py (BaseTool + path resolution + truncation), registry.py (dispatch;
 │                     # code_mode flag filters definitions() to [run_code], all_definitions() feeds
 │                     # the SDK), hooks.py (before/after tool hook chain + plan mode), mutation_queue.py (per-file locks), ignore.py (.gitignore),
-│                     # read/bash/edit/write/grep/find/ls/run_code.py (the Code Mode transport)
+│                     # read/bash/edit/write/grep/find/ls/run_code.py (the Code Mode transport),
+│                     # web_search.py (registered only when the search provider has a key),
+│                     # daily mode only: web_fetch.py, memory.py, session_search.py,
+│                     # ask_user.py (end_turn), skill_manage.py (writes ~/.limbo/daily/skills)
+├── websearch/        # pluggable web-search backends: base.py (SearchProvider/SearchResult),
+│                     # deepseek.py (+ key inheritance from the deepseek model provider), PROVIDERS
 └── ui/               # app.py + app.tcss (ALL styles here; theme vars only, no bare hex),
-                      # theme.py (limbo-dark/-light, RFC LIM-16), commands.py (slash registry
+                      # theme.py (limbo-dark/-light, RFC LIM-16), daily_look.py (daily mode
+                      # "Limbo Dawn": <theme>+daily warm variant, app.set_daily_look), commands.py (slash registry
                       # + resolve(): the single builtin-vs-skill collision site), path_input.py
                       # ('/'-path fallback), paste_store.py (pure paste/attachment marker
                       # state machine; the input widget is its adapter),
@@ -91,20 +111,28 @@ Providers/models live in `llm/catalog.py`; unknown models get generic OpenAI-com
 [goal]       # max_rounds = 10, verify_timeout_ms = 600000
 [queue]      # after_failed_run = "continue" | "keep" | "withdraw" (queued
              # messages after an LLM-error turn; keep/withdraw end the task)
+[subagents]  # enabled, auto = "off"|"suggest"|"on", max_parallel = 3, max_tasks = 12,
+             # task_token_budget, cheap_model, wake_main_on, on_dep_fail, on_resume
+[daily]      # workdir = "~/limbo-daily", model, memory, user_chars, notes_chars,
+             # memory_nudge_turns, learn_after_tool_calls, fetch_max_chars, fetch_timeout
 [ui]         # theme, show_banner
 [providers.<id>]  # base_url / api_key / api_key_env / headers
 ```
 
 `/model` rebuilds the client mid-session (refused while busy) and persists via tomlkit. 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); legacy sessions without `meta.tool_intents` get the generic placeholder. Trace events: `session_start`, `user_message`, `llm_request` (full body), `llm_response`, `tool_call`, `tool_result`, `tool_recovery`, `compaction*`, `error`, `turn_end`. `/export [path]` merges meta + trace + message snapshot (Markdown if `.md`). `/fork [n]` copies the active history (first n user turns) into a new self-contained session, `/handoff <note>` starts a clean linked session from a note; both record `parent_session`/`fork_at` and leave the parent untouched. Code Mode sub-calls are traced as `tool_call`/`tool_result` with `parent_call_id`. `limbo --json` (implies `--headless`) prints every event as one JSON object per line.
 
-Skills: `~/.limbo/skills/<name>/SKILL.md` (user) and `<workdir>/.agents/skills/<name>/SKILL.md` (project, wins collisions) — injected as a `<available_skills>` catalog in the system prompt and invocable via `/<name> [args]`.
+Skills: `~/.limbo/skills/<name>/SKILL.md` (user) and `<workdir>/.agents/skills/<name>/SKILL.md` (project, wins collisions); daily sessions also see the bundled `src/limbo/daily_skills/` (lowest) and `~/.limbo/daily/skills/` (highest), coding sessions never do — injected as a `<available_skills>` catalog in the system prompt and invocable via `/<name> [args]`.
 
 ## UI
 
-Single column: status bar (state/elapsed/tokens/model/workdir/queued + rainbow 🎯GOAL badge while a goal loop runs + ⌨code badge while Code Mode is on) → scrolling chat flow (user `❯`, streaming Markdown, tool cards, errors) → input box (Enter submits, Shift+Enter newline, Alt+Enter queues a follow-up while busy (`ui/key_fixes.py` maps its modifyOtherKeys/kitty/ESC forms), paste markers, `ctrl+v` image attach) → hint line. Slash commands: `/sessions /new /fork /handoff /export /tracing-viewer /compact /model /code-mode /plan /help /2048 /goal` + skill commands. '/'-leading input that matches no command but looks like a path is sent as a normal message with existing files auto-attached (`ui/path_input.py`); a leading space forces plain text. After palette changes run `python scripts/check_contrast.py` (≥ 4.5:1).
+Single column: status bar (state/elapsed/tokens/model/workdir/queued + rainbow 🎯GOAL badge while a goal loop runs + ⌨code badge while Code Mode is on) → scrolling chat flow (user `❯`, streaming Markdown, tool cards, errors) → input box (Enter submits, Shift+Enter newline, Alt+Enter queues a follow-up while busy (`ui/key_fixes.py` maps its modifyOtherKeys/kitty/ESC forms), paste markers, `ctrl+v` image attach) → hint line. Slash commands: `/sessions /new /fork /handoff /export /tracing-viewer /compact /model /code-mode /plan /daily-mode /memory /learn /help /2048 /goal /agents /task` + skill commands; `@<agent> text` messages a subagent. '/'-leading input that matches no command but looks like a path is sent as a normal message with existing files auto-attached (`ui/path_input.py`); a leading space forces plain text. After palette changes run `python scripts/check_contrast.py` (≥ 4.5:1).
 
 `/goal <text>` starts closed-loop mode (LIM-40): the first round is a proposal round — the model explores the repo and proposes acceptance command(s) in a `<verify_proposal>` block; the user confirms in a picker (accept / edit / skip), then the goal branch of the `TurnPump` (non-UI, shared by any frontend) runs each round as a complete `Agent.run()` turn and executes the verify command; exit 0 ends the loop, otherwise the failure output is fed back verbatim into the next round until `max_rounds`, when a no-tool wrap-up turn summarizes and any user message resumes with a fresh budget. Goal state persists on `SessionMeta.goal`. Esc during verify cancels the subprocess.
 
+Subagents (`subagents/`, docs/subagents.md): the main agent's `plan_tasks` creates tasks on the board (suggest mode: `PlanPicker` 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 `ToolResult(end_turn=True)`. Notices reach the main agent as one `source="subagent"` steer item; an idle main agent is woken through `MainWake` → `Conversation.take_wake_input()`. Board records live in the main session file (`type: "task"`), so the board survives restarts; tasks running at exit come back paused (`on_resume`).
+
+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 `web_fetch` and `memory` tools; persisted as `SessionMeta.daily_mode`, `/new` keeps the current mode. Memory is a snapshot taken when the Agent is built: `USER.md` and `NOTES.md` enter daily-mode prompts only (coding sessions never see memory); `memory` tool writes reach disk at once but the prompt changes only next session (prefix cache stays intact). `/learn` (and auto after `learn_after_tool_calls` tool calls) plans a `skill-reviewer` fork subagent whose only write tool is `skill_manage`; daily children inherit daily mode minus `MAIN_ONLY_TOOLS`.
+
 ## Key Decisions
 
 - Async agent, sync tools via `asyncio.to_thread()`
@@ -136,4 +164,5 @@ uv run python -m pytest --snapshot-update  # after intentional visual changes; r
 ## Adding Things
 
 - **Tool**: subclass `BaseTool` in `tools/<name>.py` (`name`/`description`/`parameters` + `run()`; use `resolve_existing()`/`resolve_creatable()`, raise `ToolError`), register in `ToolRegistry.__init__()`, wrap mutations in `mutation_lock_for(path)`, add `tests/tools/test_<name>.py`
+- **Web-search backend**: subclass `SearchProvider` in `websearch/<id>.py` with a `build(config)` factory (None when it has no key), add it to `websearch.PROVIDERS`; users pick it with `[web_search] provider`
 - **Provider/model**: add specs in `llm/catalog.py`; new wire format → implement `LLMClient` + `register_client()` in `llm/factory.py`. User-specific endpoint/key tweaks belong in `[providers.<id>]` config, not the catalog

{limbo_code-0.3 → limbo_code-0.3.5}/CONTEXT.md

@@ -60,6 +60,26 @@ 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.
 
+## Subagents
+
+- **Task board** — the delegated work of one main session
+  (`subagents/board.py`): tasks with status, `depends_on` (dependency
+  edges: a failure notifies by default), `owner` (ownership edges: a
+  failure cascades), waits, checkpoints, questions and outcomes.
+  Event-sourced into the main session file; `reconcile()` is the pure
+  scheduling rule.
+- **Subagent** — a child Agent working on one task with its own context and
+  session file. It reports through checkpoint / need / ask_main / finish
+  and never plans tasks itself (depth 1).
+- **Profile** — what kind of subagent a task gets (tools, model, prompt);
+  built-in, user (`~/.limbo/agents`) or project (`.agents/agents`).
+- **Supervisor** — owns the board, the running subagents and notice
+  delivery for one Conversation (`subagents/supervisor.py`).
+- **Notice** — a subagent event for the main agent: result, question,
+  alert, info (delivered, at most once) or progress (UI only). Delivered as
+  one `<subagent_updates>` steer item; questions and alerts wake an idle
+  main agent, results wait until the wave is done.
+
 ## Safety
 
 Limbo has no safety fences: file tools are not scoped to the workdir,

{limbo_code-0.3 → limbo_code-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: limbo-code
-Version: 0.3
+Version: 0.3.5
 Summary: A minimal terminal AI coding agent
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27
@@ -10,6 +10,8 @@ Requires-Dist: pygments>=2.17
 Requires-Dist: textual>=8.0
 Requires-Dist: toml>=0.10
 Requires-Dist: tomlkit>=0.13
+Provides-Extra: daily
+Requires-Dist: pypdf>=4.0; extra == 'daily'
 Description-Content-Type: text/markdown
 
 # Limbo
@@ -60,6 +62,11 @@ you can branch, hand off, or replay any session.
   confirm it, and Limbo iterates until it passes.
 - **Steer while it works.** Type while a turn is running to redirect it;
   `Alt+Enter` queues a follow-up for after the task; `Esc` interrupts.
+- **Background subagents.** The agent can split work into tasks that run in
+  parallel with their own context: they checkpoint, wait on each other when
+  they discover a dependency, and report back. You approve the plan, watch
+  the board in `/agents`, and pause, cancel or talk to any of them with
+  `/task` or `@name`, or just ask the main agent.
 - **Side channels.** `/btw <question>` asks something quick without polluting
   the history; `!<command>` runs a shell command yourself, never sent to the
   model.
@@ -106,6 +113,24 @@ you can branch, hand off, or replay any session.
 - `Ctrl+P` command palette, image and file paste with `Ctrl+V`, collapsible
   tool output with `Ctrl+O`.
 
+### Daily mode for everything else
+
+`limbo daily` (or `/daily-mode on`) turns Limbo into an everyday assistant for
+non-coding work, in its own working directory:
+
+- **Memory.** `USER.md` (who you are) and `NOTES.md` (what it learned) under
+  `~/.limbo/memory/`, loaded into daily sessions only, never into coding ones.
+- **More tools.** `web_fetch` reads pages and PDFs, `session_search` recalls
+  past conversations, and `ask_user` asks you a multiple-choice question.
+- **A starter pack of skills** for PDFs, Word, Excel, slides, citations,
+  meeting notes, weekly reviews, YouTube and arXiv. Daily mode has its own
+  skill directory (`~/.limbo/daily/skills/`) that coding sessions never see.
+- **It learns.** `/learn`, or an automatic review after a long stretch of
+  work, has a background subagent write what it learned into skills. Every
+  write lands in the daily skill directory and keeps a `.bak`.
+
+See [docs/daily-mode.md](docs/daily-mode.md).
+
 ### Scriptable
 
 `limbo --headless` gives the same agent as a line-oriented REPL, and
@@ -155,6 +180,7 @@ Then just describe the task: *"find why the login test is flaky and fix it"*.
 | `/goal <task>` | iterate until a confirmed verify command passes |
 | `/code-mode [on\|off]` | one `run_code` tool: a Python program, many tool calls |
 | `/btw <question>` | side question that stays out of history |
+| `/agents` `/task` `@name` | background subagents: the task board, direct control, talk to one |
 | `/compact` | compact the conversation now |
 | `/sessions` `/new` | switch to a past session, or start fresh |
 | `/fork [n]` | branch into a new session (optionally keep only the first n turns) |
@@ -194,6 +220,23 @@ theme = "auto"                      # Omarchy if installed, else limbo-dusk
 motion = "full"                     # full | reduced | off
 ```
 
+### Web search
+
+The `web_search` tool is offered whenever its provider has a key. The only
+provider today is DeepSeek
+([search API](https://api-docs.deepseek.com/guides/search)); without its own
+key it reuses the DeepSeek model key (`[providers.deepseek]`, `limbo auth
+login`, `$DEEPSEEK_API_KEY`, or `[llm] api_key` while a DeepSeek model is
+active).
+
+```toml
+[web_search]
+provider = "deepseek"    # backends live in limbo.websearch.PROVIDERS
+api_key = "sk-..."       # optional: a separate key just for search
+count = 10               # default results per search
+enabled = true
+```
+
 ## Make it yours
 
 - **Project instructions.** Limbo reads `AGENTS.md` from the working directory
@@ -235,6 +278,31 @@ The screenshot above is rendered from the real UI by
 `scripts/readme_hero.py` (`uv run python scripts/readme_hero.py`), so it can't
 drift from what ships.
 
+## Acknowledgements
+
+Limbo borrows openly from other agents. Thank you to:
+
+- **[pi](https://github.com/badlogic/pi-mono) and pi-durable.** The durable
+  session design comes from pi-durable: the "commit the intent, then the
+  effect" journal, the replay policy for tool calls interrupted by a crash,
+  the placeholders that say what is known about an unfinished call, the
+  steer and follow-up inbox (`Alt+Enter`), the task graph edges behind
+  background subagents, and context overflow detection. From the pi coding
+  agent itself: the built-in tool behavior (output limits, multi-edit,
+  process-tree kill, ripgrep), the provider conventions and model catalog,
+  compaction and the session entry model, and collapsing large pastes.
+- **[Crush](https://github.com/charmbracelet/crush)** by Charm. The Limbo
+  Dusk TUI was designed after Crush: the gradient wordmark, `╱` dialog rules,
+  Limbo Motion (its staggered entrance is borrowed directly), the `Ctrl+P`
+  command palette and the `Ctrl+S` session picker.
+- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** by Nous
+  Research. Daily mode is modeled on Hermes: the `USER.md` / `NOTES.md`
+  memory with its frozen per-session snapshot and the memory nudge,
+  `session_search`, `ask_user`, and skill self-learning (the skill reviewer's
+  prompt is adapted from Hermes). The bundled daily skills in
+  `src/limbo/daily_skills/` are ported from Hermes under the MIT license, and
+  each keeps its `LICENSE`.
+
 ## Learn more
 
 - [`AGENTS.md`](AGENTS.md): architecture and design decisions
@@ -242,4 +310,8 @@ drift from what ships.
 - [`docs/session-management.md`](docs/session-management.md): sessions,
   recovery, fork and handoff, tracing viewer
 - [`docs/skills.md`](docs/skills.md): writing skills
+- [`docs/daily-mode.md`](docs/daily-mode.md): daily mode, memory and
+  self-learning skills
+- [`docs/subagents.md`](docs/subagents.md): background subagents, the task
+  board and how to steer them
 - [`design/`](design/): RFCs for headless mode, bang commands, and the UI

{limbo_code-0.3 → limbo_code-0.3.5}/README.md

@@ -46,6 +46,11 @@ you can branch, hand off, or replay any session.
   confirm it, and Limbo iterates until it passes.
 - **Steer while it works.** Type while a turn is running to redirect it;
   `Alt+Enter` queues a follow-up for after the task; `Esc` interrupts.
+- **Background subagents.** The agent can split work into tasks that run in
+  parallel with their own context: they checkpoint, wait on each other when
+  they discover a dependency, and report back. You approve the plan, watch
+  the board in `/agents`, and pause, cancel or talk to any of them with
+  `/task` or `@name`, or just ask the main agent.
 - **Side channels.** `/btw <question>` asks something quick without polluting
   the history; `!<command>` runs a shell command yourself, never sent to the
   model.
@@ -92,6 +97,24 @@ you can branch, hand off, or replay any session.
 - `Ctrl+P` command palette, image and file paste with `Ctrl+V`, collapsible
   tool output with `Ctrl+O`.
 
+### Daily mode for everything else
+
+`limbo daily` (or `/daily-mode on`) turns Limbo into an everyday assistant for
+non-coding work, in its own working directory:
+
+- **Memory.** `USER.md` (who you are) and `NOTES.md` (what it learned) under
+  `~/.limbo/memory/`, loaded into daily sessions only, never into coding ones.
+- **More tools.** `web_fetch` reads pages and PDFs, `session_search` recalls
+  past conversations, and `ask_user` asks you a multiple-choice question.
+- **A starter pack of skills** for PDFs, Word, Excel, slides, citations,
+  meeting notes, weekly reviews, YouTube and arXiv. Daily mode has its own
+  skill directory (`~/.limbo/daily/skills/`) that coding sessions never see.
+- **It learns.** `/learn`, or an automatic review after a long stretch of
+  work, has a background subagent write what it learned into skills. Every
+  write lands in the daily skill directory and keeps a `.bak`.
+
+See [docs/daily-mode.md](docs/daily-mode.md).
+
 ### Scriptable
 
 `limbo --headless` gives the same agent as a line-oriented REPL, and
@@ -141,6 +164,7 @@ Then just describe the task: *"find why the login test is flaky and fix it"*.
 | `/goal <task>` | iterate until a confirmed verify command passes |
 | `/code-mode [on\|off]` | one `run_code` tool: a Python program, many tool calls |
 | `/btw <question>` | side question that stays out of history |
+| `/agents` `/task` `@name` | background subagents: the task board, direct control, talk to one |
 | `/compact` | compact the conversation now |
 | `/sessions` `/new` | switch to a past session, or start fresh |
 | `/fork [n]` | branch into a new session (optionally keep only the first n turns) |
@@ -180,6 +204,23 @@ theme = "auto"                      # Omarchy if installed, else limbo-dusk
 motion = "full"                     # full | reduced | off
 ```
 
+### Web search
+
+The `web_search` tool is offered whenever its provider has a key. The only
+provider today is DeepSeek
+([search API](https://api-docs.deepseek.com/guides/search)); without its own
+key it reuses the DeepSeek model key (`[providers.deepseek]`, `limbo auth
+login`, `$DEEPSEEK_API_KEY`, or `[llm] api_key` while a DeepSeek model is
+active).
+
+```toml
+[web_search]
+provider = "deepseek"    # backends live in limbo.websearch.PROVIDERS
+api_key = "sk-..."       # optional: a separate key just for search
+count = 10               # default results per search
+enabled = true
+```
+
 ## Make it yours
 
 - **Project instructions.** Limbo reads `AGENTS.md` from the working directory
@@ -221,6 +262,31 @@ The screenshot above is rendered from the real UI by
 `scripts/readme_hero.py` (`uv run python scripts/readme_hero.py`), so it can't
 drift from what ships.
 
+## Acknowledgements
+
+Limbo borrows openly from other agents. Thank you to:
+
+- **[pi](https://github.com/badlogic/pi-mono) and pi-durable.** The durable
+  session design comes from pi-durable: the "commit the intent, then the
+  effect" journal, the replay policy for tool calls interrupted by a crash,
+  the placeholders that say what is known about an unfinished call, the
+  steer and follow-up inbox (`Alt+Enter`), the task graph edges behind
+  background subagents, and context overflow detection. From the pi coding
+  agent itself: the built-in tool behavior (output limits, multi-edit,
+  process-tree kill, ripgrep), the provider conventions and model catalog,
+  compaction and the session entry model, and collapsing large pastes.
+- **[Crush](https://github.com/charmbracelet/crush)** by Charm. The Limbo
+  Dusk TUI was designed after Crush: the gradient wordmark, `╱` dialog rules,
+  Limbo Motion (its staggered entrance is borrowed directly), the `Ctrl+P`
+  command palette and the `Ctrl+S` session picker.
+- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** by Nous
+  Research. Daily mode is modeled on Hermes: the `USER.md` / `NOTES.md`
+  memory with its frozen per-session snapshot and the memory nudge,
+  `session_search`, `ask_user`, and skill self-learning (the skill reviewer's
+  prompt is adapted from Hermes). The bundled daily skills in
+  `src/limbo/daily_skills/` are ported from Hermes under the MIT license, and
+  each keeps its `LICENSE`.
+
 ## Learn more
 
 - [`AGENTS.md`](AGENTS.md): architecture and design decisions
@@ -228,4 +294,8 @@ drift from what ships.
 - [`docs/session-management.md`](docs/session-management.md): sessions,
   recovery, fork and handoff, tracing viewer
 - [`docs/skills.md`](docs/skills.md): writing skills
+- [`docs/daily-mode.md`](docs/daily-mode.md): daily mode, memory and
+  self-learning skills
+- [`docs/subagents.md`](docs/subagents.md): background subagents, the task
+  board and how to steer them
 - [`design/`](design/): RFCs for headless mode, bang commands, and the UI

limbo_code-0.3.5/docs/daily-mode.md

@@ -0,0 +1,103 @@
+# Daily mode
+
+日常非 coding 工作（调研、读网页、写东西、整理笔记）用的会话姿态。内核和
+coding 模式完全一样（agent loop、会话、压缩、子代理、/goal、skills），只换三样：
+
+- **系统提示词**：通用个人助理口吻，先搜后答、给出处、产出落到文件。
+- **工具**：在原有工具之上加 `web_fetch`（读网页/PDF）、`memory`（长期记忆）、
+  `session_search`（翻过往会话）、`ask_user`（向你提问）、`skill_manage`（自己改进 skill）。
+- **记忆注入**：会话开始时把 `~/.limbo/memory/` 的快照放进提示词。
+
+## 进入和切换
+
+```bash
+limbo daily              # = limbo --daily：工作目录切到 [daily] workdir，新会话直接是 daily
+limbo daily --continue   # 接上一个 daily 会话
+```
+
+会话内 `/daily-mode on|off`（无参切换），状态栏显示 `☀daily`。模式随会话保存，
+恢复时还原；`/new` 沿用当前模式。切换会重建系统提示词（前缀缓存失效一次，和 `/model` 一样）。
+
+## 记忆
+
+两个纯文本文件，可以直接打开编辑，条目之间用单独一行 `§` 分隔：
+
+| 文件 | 内容 |
+|---|---|
+| `~/.limbo/memory/USER.md` | 你是谁：身份、偏好、风格 |
+| `~/.limbo/memory/NOTES.md` | agent 的笔记：稳定事实、约定、你纠正过的事 |
+
+记忆只进 daily 会话的提示词，coding 会话完全读不到。
+
+- 模型用 `memory` 工具写入（add / patch / remove，一次调用可批量、原子执行），超过字符上限时整批拒绝。
+- 写入立刻落盘（上一版留在 `*.bak`），但本会话的提示词不变，从下一个会话起生效。
+- `/memory` 查看内容和用量；`/memory edit [user|notes]` 用 `$VISUAL`/`$EDITOR` 打开（headless 下只显示路径）。
+- `/memory` 和 `/learn` 只在 daily 会话里出现；coding 会话的命令菜单、命令面板和 `/help` 里都没有，直接输入会提示先 `/daily-mode on`。
+
+- 每 `memory_nudge_turns` 轮（默认 10）没写过记忆时，会在你的消息后附一句提醒，让模型考虑要不要存。
+
+## Skills
+
+daily 会话按这个顺序收集 skill，同名时后者覆盖前者：
+
+1. **内置起步包**（`src/limbo/daily_skills/`，从 Hermes 移植，MIT）：pdf、docx、xlsx、powerpoint、
+   grounded-citations、blocked-page-recovery、meeting-action-items、document-to-action-items、
+   weekly-review-planning、youtube-content、arxiv。文档类 skill 需要的 Python 包按 skill 里的说明装。
+2. 用户 skill `~/.limbo/skills`、项目 skill `<workdir>/.agents/skills`
+3. **daily skill** `~/.limbo/daily/skills/<name>/SKILL.md`
+
+coding 会话只看 2，看不到起步包和 daily skill。
+
+## 自学习（/learn）
+
+- 模型可以用 `skill_manage` 新建或修改 skill（create / patch / write_file，一次批量、全成或全不成）。
+  所有写入都落在 `~/.limbo/daily/skills`：改内置或用户 skill 时先把它复制过来再改，原文件不动；改前留 `.bak`。
+- `/learn` 在后台开一个 `skill-reviewer` 子代理（带上当前对话、只能读 skill 和调 `skill_manage`、用 cheap_model），
+  把这次对话里的纠正、偏好和新技巧写进 skill，结果作为子代理通知回到对话里。
+- 自动触发：一轮结束时，如果距上次改 skill 已经有 `learn_after_tool_calls`（默认 10）次工具调用，就自动开一次复盘；设 0 关掉。
+- 需要子代理开着（`[subagents] enabled = true`）。
+
+## 其他工具
+
+- `session_search`：不带索引地扫描会话文件，按关键词找过往 daily 会话（`include_coding` 也搜 coding），
+  再用 `session_id` + `around` 读上下文。
+- `ask_user`：模型给出问题和最多 6 个选项后本轮结束，你回复编号或直接回答。
+- 子代理角色 `researcher`：只读调研，daily 模式下能读网页正文，交回带出处的结论。daily 会话里的子代理
+  也是 daily 姿态，但 `memory`、`ask_user`、`skill_manage`、`session_search` 只留给主 agent。
+
+## 界面：Limbo Dawn
+
+daily mode 下 TUI 换成当前主题的暖色变体 Limbo Dawn：coding 是 Dusk（蓝 → 黄的黄昏渐变），
+daily 是 Dawn（红 → 杏橙 → 黄的日出渐变）。布局、`╱` 纹理、吉祥物黄和成功/错误/diff 语义色不变。
+
+- 输入框边框上常驻 `☀ daily` 徽标，右下角是记忆条数；窄屏状态栏的字标旁有 `☀ DAILY` 色块
+- 侧栏把「修改的文件」换成「读过的网页」和「记忆」（本会话有改动时「修改的文件」照常出现）
+- 启动页、底部快捷键提示换成 daily 场景的用法
+- `/daily-mode` 切换时聊天里插一条模式分隔线，一道光扫过（`[ui] motion` 为 reduced/off 时静态）
+
+limbo 自带的三个主题用手调色板；Omarchy 和 Textual 内置主题按规则派生（渐变取 error → warning →
+accent，primary 取 warning，对比度不足时向前景推）；ANSI 主题不换色，只显示徽标。
+`[daily] look = "badge"` 关掉换色、只保留徽标。
+
+## web_fetch
+
+打开 http(s) 链接，返回正文的 Markdown（标题、列表、链接；导航、脚本、页脚去掉，
+有 `<article>`/`<main>` 时只取正文）。长页面按 `fetch_max_chars` 分段，带 `offset` 继续读。
+PDF 链接在装了 `pypdf` 时直接转成文本（`pip install 'limbo-code[daily]'`）。超长页面除了分段返回，
+全文还会存到 `<workdir>/fetched/`，可以用 read 翻。
+
+## 配置
+
+```toml
+[daily]
+workdir = "~/limbo-daily"
+model = ""                    # 留空沿用 [llm] model；只对 limbo daily 启动生效
+memory = true
+user_chars = 1500
+notes_chars = 2500
+memory_nudge_turns = 10
+learn_after_tool_calls = 10
+fetch_max_chars = 20000
+fetch_timeout = 30.0
+look = "dawn"                 # "badge"：只显示 ☀ 徽标，不换暖色主题
+```

{limbo_code-0.3 → limbo_code-0.3.5}/docs/skills.md

@@ -37,8 +37,10 @@ description: Test-driven development workflow.
 
 | 来源 | 路径 |
 |------|------|
+| 内置 daily 起步包（仅 daily 会话） | `src/limbo/daily_skills/`（随包分发，从 Hermes 移植） |
 | 用户级 | `~/.limbo/skills/<name>/SKILL.md` |
 | 项目级 | `<workdir>/.agents/skills/<name>/SKILL.md` |
+| Daily（仅 daily 会话） | `~/.limbo/daily/skills/<name>/SKILL.md` |
 
 内置斜杠命令（`/sessions` 等）优先于同名 skill。
 

limbo_code-0.3.5/docs/subagents.md

@@ -0,0 +1,132 @@
+# 子代理（Subagents）
+
+主 agent 可以把工作拆成任务，交给后台子代理并行完成；你继续和主 agent
+对话，子代理的结果、提问和失败会回到主 agent 那里。你也可以随时直接查看
+和控制每个子任务。
+
+## 一眼看懂
+
+```
+你 ──对话──▶ 主 agent ──plan_tasks──▶ 任务板（t1 t2 t3 …）
+                ▲                         │ reconcile：依赖就绪 → 派发
+                │ <subagent_updates>      ▼
+                └──── 结果 / 提问 / 告警 ── 子代理（各自独立上下文与会话文件）
+你 ──/task、/agents、@名字──▶ 任务板 / 子代理（主 agent 会被告知）
+```
+
+- **任务板**（`subagents/board.py`）是唯一真相：任务、依赖、等待、打点、
+  提问和结果。每次变更都作为 `{"type":"task",...}` 记录追加进主会话文件，
+  重启时重放；会话重写时写一条 `snapshot` 折叠历史。
+- **Supervisor**（`subagents/supervisor.py`）根据任务板做调度：依赖都结束
+  的任务变为就绪，按优先级 / 已有进度 / 关键路径派发到空闲槽位
+  （`max_parallel`），并把通知投递给主 agent。
+- **子代理**是同进程里的另一个 `Agent`，有自己的会话文件
+  `<sessions>/<主会话>.agents/<任务id>-<名字>.jsonl`，崩溃后可以接着跑。
+
+## 自动创建
+
+- 启动时对工作区做一次不调用模型的扫描（语言、文件数、workspace 子包、
+  检测到的验证命令、git 状态），作为 `<project_facts>` 写进主 agent 的
+  system prompt，和可用角色列表 `<available_agents>` 一起引导它判断什么时候
+  值得拆分。
+- 默认 `auto = "suggest"`：主 agent 调 `plan_tasks` 后，计划会弹出给你确认
+  （TUI 弹窗；headless 里用 `/task approve all`），确认前不会开始。
+  `auto = "on"` 直接开始，`auto = "off"` 不给主 agent 任务工具。
+- 角色（profile）决定子代理的工具、模型和提示：内置 `explore`（只读）、
+  `worker`、`reviewer`（只读）、`verifier`（不改文件）。用户级
+  `~/.limbo/agents/<name>.md` 和项目级 `.agents/agents/<name>.md` 可以覆盖或
+  新增；`/agents init` 会根据扫描结果为每个 workspace 子包生成一个
+  `<包名>-worker`，并生成跑验证命令的 `project-verifier`。
+
+角色文件格式：
+
+```markdown
+---
+name: api-worker
+description: 只改 packages/api/ 下的代码
+when_to_use: 任务只涉及 API 时
+tools: all            # read_only | all | no_edit | read,grep,bash（白名单）
+model: inherit        # inherit | cheap | 具体模型 id
+max_iterations: 40
+isolation: shared     # shared | worktree
+context: brief        # brief（只看任务说明）| fork（带上主对话）
+scope_paths: packages/api/**
+---
+给子代理的额外指令。
+```
+
+## 打点与任务编排
+
+子代理有五个工具：
+
+| 工具 | 作用 |
+|------|------|
+| `checkpoint(phase, summary)` | 打点：进入新阶段时记录进度（每 8 次工具调用也会自动打点） |
+| `need(on=[…] \| new={…}, reason, policy)` | 发现依赖：`wait` 挂起直到依赖结束，带着结果继续；`cancel_self` 判断自己已无必要；`ask_main` 交给主 agent 决定 |
+| `ask_main(question)` | 需要主 agent / 用户决定的问题，挂起直到回答 |
+| `finish(summary, files_changed)` | 交付，摘要就是主 agent 读到的全部 |
+| `propose_task(title, brief)` | 建议新任务，由主 agent 批准（子代理不能自己再拆，深度固定为 1） |
+
+规则：
+
+- **依赖边**（`depends_on` / `need`）：依赖失败时默认 `notify`——等待方照常
+  继续并收到失败原因，自己决定；`on_dep_fail = "cascade"` 改为连带取消。
+  `join = "fail_fast"` 让等待方在第一个依赖失败时就醒来。
+- **归属边**（`owner`）：父任务取消或失败，它名下的任务一律取消。
+- 加依赖时检测环，形成循环会被拒绝；所有任务互相等待（死锁）时，主 agent
+  会收到告警。
+- 共享工作区时，写任务用 `scope_paths` 认领路径，其他子代理 `edit`/`write`
+  被认领的文件会被拦下并提示用 `need` 等待。需要更强隔离时用
+  `isolation: worktree`（独立 git worktree 和分支，完成后
+  `task_control merge` 合并）。
+
+## 通讯
+
+- **子代理 → 主 agent**：通知合并成一条 `<subagent_updates>` 插话。主 agent
+  忙时在下一个一致点注入；空闲时：提问和告警立即唤醒主 agent，结果等这一波
+  子代理都结束后一起交付（`wake_main_on` 可调）。每条通知只交付一次，崩溃
+  后不会重复。
+- **主 agent → 子代理**：`task_status`、`task_send`（运行中的子代理以插话收到，
+  其他状态进收件箱、继续时送达）、`answer`、`task_control`（pause / resume /
+  cancel / retry / reprioritize / edit / approve / reject / merge）。所以你可以
+  直接对主 agent 说"先暂停前端那个任务"。
+- **你 → 子代理**：
+
+| 输入 | 作用 |
+|------|------|
+| `/agents` | 子代理面板：实时任务板、打点、最近记录；`p` 暂停 `r` 恢复 `c` 取消 `t` 重试 `a`/`x` 批准/拒绝 `m` 发消息 |
+| `/task` · `/task <id>` | 任务板 / 某个任务详情 |
+| `/task <pause\|resume\|cancel\|retry\|approve\|reject\|merge> <id\|all> [说明]` | 直接控制；`/task retry <id> fresh` 丢弃旧上下文重来 |
+| `/task prio <id> <n>` · `/task edit <id> <新说明>` · `/task send <id> <消息>` | 调优先级、改说明、发消息 |
+| `@worker-1 <消息>` | 直接对某个子代理说话 |
+| `/agents scan` · `/agents init` | 项目画像与可用角色 / 写入建议的项目角色 |
+
+  这些命令忙时也可用，你的每个直接操作都会以 `info` 通知告诉主 agent。
+
+## 重启与恢复
+
+进程退出时运行中的任务不写结果。下次打开会话时，它们被标为"已暂停（进程
+重启时中断）"并提示 `/task resume all`（`on_resume = "auto"` 则直接继续）。
+恢复的子代理从自己的会话文件接着跑，并被告知先检查工作区现状。
+
+headless 模式下输入关闭（EOF）后，会等后台子代理和随之而来的主 agent 总结
+轮次结束再退出；暂停和待确认的任务不等。`--json` 输出额外的 `task`、
+`subagent_notice`、`plan_proposed` 行。
+
+## 配置
+
+```toml
+[subagents]
+enabled = true                 # false：完全关闭
+auto = "suggest"               # off | suggest | on
+max_parallel = 3               # 同时运行的子代理
+max_tasks = 12                 # 未结束任务上限
+task_token_budget = 400000     # 单任务 token 预算，超出即失败（0 = 不限）
+cheap_model = ""               # model: cheap 的角色用它（空 = 主模型）
+wake_main_on = ["question", "alert", "wave_done"]
+on_dep_fail = "notify"         # notify | cascade
+on_resume = "ask"              # ask | auto | pause
+default_isolation = "shared"   # shared | worktree
+result_chars = 2000            # 交给主 agent 的结果摘要长度
+auto_checkpoint_every = 8      # 每 N 次工具调用自动打点（0 = 关）
+```

{limbo_code-0.3 → limbo_code-0.3.5}/pyproject.toml

@@ -16,6 +16,10 @@ dependencies = [
     "pygments>=2.17",
 ]
 
+[project.optional-dependencies]
+# Daily mode: web_fetch reads PDF links when pypdf is present.
+daily = ["pypdf>=4.0"]
+
 [dependency-groups]
 # Dev tools live in a PEP 735 dependency group (not an extra) so `uv sync`
 # installs them by default — no `--extra`/`--group` flag needed. Always run
@@ -29,6 +33,7 @@ dev = [
     "ruff>=0.4",
     "mypy>=1.10",
     "types-Pygments>=2.17",
+    "pypdf>=4.0",
 ]
 
 [project.scripts]
@@ -50,6 +55,9 @@ packages = ["src/limbo"]
 [tool.ruff]
 line-length = 100
 src = ["src", "tests"]
+# Bundled daily-mode skills ported from hermes-agent: third-party scripts
+# kept as upstream wrote them.
+extend-exclude = ["src/limbo/daily_skills"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "W"]
@@ -59,3 +67,4 @@ python_version = "3.11"
 strict = false
 warn_return_any = true
 warn_unused_ignores = true
+exclude = ["src/limbo/daily_skills/"]