anima-core 1.0.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54229e4195de8d0b5aefbe45627d6fba58f7ff1820963dfb9cea07c03bdc0eaf
-  data.tar.gz: 413bd51de98ebbe98e79f161a90af96fef3615befc32917682e8bac7e152c9ee
+  metadata.gz: 161b7dfde73fa61f7656427c0af3c5919e1a1cc50d6b1a2d201f5a45ce79c561
+  data.tar.gz: 880538d54fbc682b61bbeb6d63b38aa066e86327c778fefce8e60091c6ad816d
 SHA512:
-  metadata.gz: 0a2d14ae33ef2f130e2b429b9f92740833e855c6b7b5bfec43a54110751af1769868d4b37cefd0906d76230e7e01ce166f573abf1a8c547abc8c247143306a42
-  data.tar.gz: 226a6eb5db2027255b76d077a91fdd4aaeb857195790a4ed0d71e74ddad25bb41b9e0ecfb8e753441d955fb5bd98115ea31e7455f2a1f47554cd3207af898212
+  metadata.gz: f0ee765c1a125e26b9f10b5cc97f41e857ec17562ef4ba116dd53bf97b9b26fb3781d9f292c6296c1c408089d155d9d8a24e4165d58f57ead64e72595f833ae8
+  data.tar.gz: 86c95c9f103cb0c6c4b37ef3452662274205da97ef04d3f846f7f2d041ff0c94f375208b60d245f454aa73abb2c144113f9d6691cc99a0124f43971fcfb62ae1

data/.gitattributes

@@ -0,0 +1 @@
+spec/cassettes/**/* -diff linguist-generated=true

data/.reek.yml

@@ -17,20 +17,46 @@ detectors:
   # EnvironmentProbe assembles output from local data structures — not envy.
   # Brain transcript builds from event collection — the method's entire purpose.
   # ConfigMigrator text processing methods naturally reference local line arrays.
+  # ToolDecorator subclasses operate on the tool result — that's the pattern.
+  # Tool rescue blocks naturally reference the error object.
   FeatureEnvy:
     exclude:
       - "AnalyticalBrainJob#perform"
       - "EnvironmentProbe"
       - "AnalyticalBrain::Runner#build_messages"
       - "Anima::ConfigMigrator"
+      - "WebGetToolDecorator"
+      - "Tools::WebGet#validate_and_fetch"
+      # Remember tool renders events from other objects — formatting IS the job.
+      - "Tools::Remember"
+      # Event subscribers extract payload fields — inherent to the pattern.
+      - "Events::Subscribers::SubagentMessageRouter"
+      # Spawn tools orchestrate child session creation — references are the job.
+      - "Tools::SpawnSubagent#spawn_child"
+      - "Tools::SpawnSpecialist#spawn_child"
+      - "Tools::SpawnSpecialist#execute"
+      # Nickname assignment operates on child session and parent's children — inherent.
+      - "Tools::SubagentPrompts#assign_nickname_via_brain"
+      # Validation methods naturally reference the validated value more than self.
+      - "AnalyticalBrain::Tools::AssignNickname#validate"
+      # Delivery method orchestrates session, event, and agent_loop — inherent.
+      - "AgentRequestJob#deliver_persisted_event"
   # Private helpers don't need instance state to be valid.
   # ActiveJob#perform is always a utility function by design.
   # No-op tools (Think, EverythingIsReady) don't need instance state — by design.
+  # method_missing is a Ruby dispatch method, not a regular public method.
+  # Content-Type dispatch targets are stateless by design — they transform input,
+  # not instance state.
   UtilityFunction:
     public_methods_only: true
     exclude:
       - "AnalyticalBrainJob#perform"
+      - "PassiveRecallJob#perform"
       - "Tools::Think#execute"
+      - "TUI::Formatting"
+      - "WebGetToolDecorator#method_missing"
+      - "WebGetToolDecorator#application_json"
+      - "WebGetToolDecorator#text_html"
   # Session model is the core domain object — methods grow naturally.
   # Mcp CLI accumulates subcommand helpers across add/remove/list/secrets.
   # EnvironmentProbe probes multiple orthogonal facets (OS, Git, project files).
@@ -40,14 +66,39 @@ detectors:
       - "Session"
       - "Anima::CLI::Mcp"
       - "EnvironmentProbe"
+      # Runner composes system prompt from modular sections — methods grow with responsibilities.
+      - "AnalyticalBrain::Runner"
   # Decorators branch on tool type across 4 render modes — inherent to the pattern.
+  # Installer methods each guard idempotency with config_path.exist? — by design.
   RepeatedConditional:
     exclude:
       - "ToolCallDecorator"
+      - "Anima::Installer"
+      # Runner checks session type to compose responsibilities — the core dispatch.
+      - "AnalyticalBrain::Runner"
   # EventDecorator holds shared rendering constants (icons, markers, dispatch maps).
   TooManyConstants:
     exclude:
       - "EventDecorator"
+  # Abstract base class methods declare parameters for the subclass contract.
+  UnusedParameters:
+    exclude:
+      - "ToolDecorator#call"
+  # Rescue blocks naturally call error.message in multiple catch clauses.
+  DuplicateMethodCall:
+    exclude:
+      - "Tools::WebGet#validate_and_fetch"
+      # Remember tool accesses event data for formatting — inherent to rendering.
+      - "Tools::Remember"
+      # Nickname validation checks parent_session for existence then queries — two calls, one guard.
+      - "AnalyticalBrain::Tools::AssignNickname#sibling_nickname_taken?"
+      # Delivery method references session.id for lookup, BounceBack, and auth broadcast.
+      - "AgentRequestJob#deliver_persisted_event"
+  # Method length is enforced by code review, not arbitrary line counts
+  # build_sections passes context through to sub-methods — inherent to assembly.
+  LongParameterList:
+    exclude:
+      - "Tools::Remember#build_sections"
   # Method length is enforced by code review, not arbitrary line counts
   TooManyStatements:
     enabled: false

data/README.md

@@ -10,7 +10,9 @@ Anima is different. It's built on the premise that if you want an agent — a re
 
 **A brain modeled after biology, not chat.** The human brain isn't one process — it's specialized subsystems on a shared signal bus. Anima's [analytical brain](https://blog.promptmaster.pro/posts/llms-have-adhd/) runs as a separate subconscious process, managing context, skills, and goals so the main agent can stay in flow. Not two brains — a microservice architecture where each process does one job well. More subsystems are coming.
 
-**Context that never degrades.** Other agents fill a static array until the model gets dumb. Anima assembles a fresh viewport over an event bus every iteration. No compaction. No summarization. Endless sessions. The [dumb zone](https://www.humanlayer.dev/blog/the-dumb-zone) never arrives — and the analytical brain curates what the agent sees, in real time.
+**Context that never degrades.** Other agents fill a static array until the model gets dumb. Anima assembles a fresh viewport over an event bus every iteration. No compaction. No lossy rewriting. Endless sessions. The [dumb zone](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md) never arrives — the analytical brain curates what the agent sees in real time.
+
+**Memory that works like memory.** Other systems bolt on memory as an afterthought — filing cabinets the agent has to consciously open mid-task. It never does; the truck is already moving. Anima's memory department ([Mneme](#semantic-memory-mneme)) runs as a third brain process on the event bus. It summarizes what's about to leave the viewport. It compresses short-term into long-term, like biological memory consolidating during sleep. It pins critical moments to active goals so exact instructions survive where summaries would lose nuance. And it recalls — automatically, passively — surfacing relevant older memories right after the soul, right before the present. The agent doesn't decide to remember. It just remembers.
 
 **Sub-agents that already know everything.** When Anima spawns a sub-agent, it inherits the parent's full event stream — every file read, every decision, every user message. No "let me summarize what I know." Lossless context. Zero wasted tool calls on rediscovery.
 
@@ -34,9 +36,9 @@ Your agent. Your machine. Your rules. Anima runs locally as a headless Rails 8.1
   - [Event-Driven Design](#event-driven-design)
   - [Context as Viewport](#context-as-viewport-not-tape)
   - [Brain as Microservices](#brain-as-microservices-on-a-shared-event-bus)
-  - [TUI View Modes](#tui-view-modes)
-  - [Plugin Architecture](#plugin-architecture)
   - [Semantic Memory](#semantic-memory-mneme)
+  - [TUI HUD & View Modes](#tui-hud--view-modes)
+  - [Plugin Architecture](#plugin-architecture-planned)
 - [The Vision](#the-vision)
   - [The Problem](#the-problem)
   - [The Insight](#the-insight)
@@ -62,10 +64,10 @@ Anima (Ruby, Rails 8.1 headless)
 ├── Workflows    — operational recipes for multi-step tasks
 ├── MCP          — external tool integration (Model Context Protocol)
 ├── Sub-agents   — autonomous child sessions with lossless context inheritance
+├── Mneme        — memory department (summarization, compression, pinning, recall)
 │
 │ Designed:
 ├── Thymos       — hormonal/desire system (stimulus → hormone vector)
-├── Mneme        — semantic memory (viewport pinning, associative recall)
 └── Psyche       — soul matrix (coefficient table, evolving individuality)
 ```
 
@@ -76,6 +78,7 @@ Brain Server (Rails + Puma)              TUI Client (RatatuiRuby)
 ├── LLM integration (Anthropic)          ├── WebSocket client
 ├── Agent loop + tool execution          ├── Terminal rendering
 ├── Analytical brain (background)        └── User input capture
+├── Mneme memory department (background)
 ├── Skills registry + activation
 ├── Workflow registry + activation
 ├── MCP client (HTTP + stdio)
@@ -129,8 +132,7 @@ State directory (`~/.anima/`):
 ├── config.toml      # Main settings (hot-reloadable)
 ├── mcp.toml         # MCP server configuration
 ├── config/
-│   ├── credentials/ # Rails encrypted credentials per environment
-│   └── anima.yml    # Placeholder config
+│   └── credentials/ # Rails encrypted credentials per environment
 ├── agents/          # User-defined specialist agents (override built-ins)
 ├── skills/          # User-defined skills (override built-ins)
 ├── workflows/       # User-defined workflows (override built-ins)
@@ -139,7 +141,7 @@ State directory (`~/.anima/`):
 └── tmp/
 ```
 
-Updates: `anima update` — upgrades the gem and merges new config settings into your existing `config.toml` without overwriting customized values. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
+Updates: `anima update` — upgrades the gem, merges new config settings into your existing `config.toml` without overwriting customized values, and restarts the systemd service if it's running. Use `anima update --migrate-only` to skip the gem upgrade and only add missing config keys.
 
 ### Authentication Setup
 
@@ -163,10 +165,9 @@ The agent has access to these built-in tools:
 | `read` | Read files with smart truncation and offset/limit paging |
 | `write` | Create or overwrite files |
 | `edit` | Surgical text replacement with uniqueness constraint |
-| `web_get` | Fetch content from HTTP/HTTPS URLs |
+| `web_get` | Fetch content from HTTP/HTTPS URLs (HTML → Markdown, JSON → TOON) |
 | `spawn_specialist` | Spawn a named specialist sub-agent from the registry |
 | `spawn_subagent` | Spawn a generic child session with custom tool grants |
-| `return_result` | Sub-agents only — deliver results back to parent |
 
 Plus dynamic tools from configured MCP servers, namespaced as `server_name__tool_name`.
 
@@ -186,9 +187,9 @@ Two types:
 | `thoughts-analyzer` | Extract decisions from project history |
 | `web-search-researcher` | Research questions via web search |
 
-**Generic Sub-agents** — child sessions with custom tool grants for ad-hoc tasks.
+**Generic Sub-agents** — child sessions with custom tool grants for ad-hoc tasks. Each generic sub-agent gets a Haiku-generated nickname (e.g. `@loop-sleuth`, `@api-scout`) for @mention addressing.
 
-Sub-agents run as background jobs and appear in the TUI session picker under their parent. Next: [@mention communication](https://github.com/hoblin/anima/issues/124) — sub-agent text messages route to the parent automatically, parent replies via `@name`. Workers become colleagues.
+Sub-agents communicate through natural text — their `agent_message` events route to the parent session automatically, and the parent replies via `@name` mentions. No special tools needed; when a sub-agent writes text, the parent sees it. When the parent @mentions a sub-agent, the message arrives in that child's session. Workers become colleagues.
 
 ### Skills
 
@@ -199,7 +200,7 @@ Domain knowledge bundles loaded from Markdown files. Skills provide specialized
 - **Override:** User skills with the same name replace built-in ones
 - **Format:** Flat files (`skill-name.md`) or directories (`skill-name/SKILL.md` with `examples/` and `references/`)
 
-Active skills are displayed in the TUI info panel.
+Active skills are displayed in the TUI HUD panel (toggle with `C-a → h`).
 
 ### Workflows
 
@@ -223,7 +224,7 @@ description: "Capture findings or context as a persistent note."
 You are tasked with capturing content as a persistent note...
 ```
 
-The active workflow is shown in the TUI info panel with a 🔄 indicator. The full lifecycle — activation, goal creation, execution, deactivation — is managed by the analytical brain using judgment, not hardcoded triggers.
+The active workflow is shown in the TUI HUD panel with a 📜 indicator. The full lifecycle — activation, goal creation, execution, deactivation — is managed by the analytical brain using judgment, not hardcoded triggers.
 
 ### MCP Integration
 
@@ -298,6 +299,7 @@ blocking_on_user_message = true
 event_window = 20
 
 [session]
+default_view_mode = "basic"
 name_generation_interval = 30
 ```
 
@@ -337,7 +339,7 @@ Most agents treat context as an append-only array — messages go in, they never
 
 The viewport is a live query, not a log. It walks events newest-first until the token budget is exhausted. Events that fall out of the viewport aren't deleted — they're still in the database, just not visible to the model right now. The context can shrink, grow, or change composition between any two iterations. If the analytical brain marks a large accidental file read as irrelevant, it's gone from the next viewport — tokens recovered instantly.
 
-This means sessions are endless. No compaction. No summarization. No degradation. The model always operates in fresh, high-quality context. The [dumb zone](https://www.humanlayer.dev/blog/the-dumb-zone) never arrives.
+This means sessions are endless. No compaction. No lossy rewriting. The model always operates in fresh, high-quality context. The [dumb zone](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md) never arrives. Meanwhile, Mneme runs as a background department — summarizing evicted events into persistent snapshots so past context is preserved, not destroyed.
 
 Sub-agent viewports compose from two event scopes — their own events (prioritized) and parent events (filling remaining budget). Same mechanism, no special handling. The bus is the architecture.
 
@@ -351,22 +353,50 @@ Anima mirrors this with an event-driven architecture. The analytical brain is th
 Event: "tool_call_failed"
   │
   ├── Analytical brain: update goals, check if workflow needs changing
+  ├── Mneme: summarize evicted context into snapshot
   ├── Thymos subscriber: frustration += 10 [planned]
-  ├── Mneme subscriber: log failure context for future recall [planned]
   └── Psyche subscriber: update coefficient (this agent handles errors calmly) [planned]
 
 Event: "user_sent_message"
   │
   ├── Analytical brain: activate relevant skills, name session
+  ├── Mneme: check viewport eviction, fire if boundary left viewport
   ├── Thymos subscriber: oxytocin += 5 (bonding signal) [planned]
-  └── Mneme subscriber: associate emotional state with topic [planned]
+  └── Psyche subscriber: associate emotional state with topic [planned]
 ```
 
 Each subscriber is a microservice — independent, stateless, reacting to the same event bus. No orchestrator decides what to do. The architecture IS the nervous system.
 
-### TUI View Modes
+### Semantic Memory (Mneme)
+
+Every AI agent today has the same disability: amnesia. Context fills up, gets compacted, gets destroyed. The agent gets dumber as the conversation gets longer. When the session ends, everything is gone. Some systems bolt on memory as an afterthought — markdown files with procedures for when to save and what format to use. Filing cabinets the agent has to consciously decide to open, mid-task, while in flow. It never does. The truck is already moving.
+
+Mneme is not a filing cabinet. It's *remembering* — the way biological memory works. Continuous, automatic, layered. A third brain department running on the same event bus as the analytical brain, specializing in one job: making sure nothing important is ever truly lost.
+
+**Eviction-triggered summarization** — Mneme tracks a boundary event on each session. When that event leaves the viewport, Mneme fires: it builds a compressed view of the conversation (full text for messages, `[N tools called]` counters for tool work), sends it to a fast model, and persists a snapshot. The boundary advances after each run — a self-regulating cycle that fires exactly when context is about to be lost, no sooner or later. No timer. No manual trigger. The architecture itself knows when to remember.
+
+**Two-level snapshot compression** — once source events evict from the sliding window, their snapshots appear in the viewport as memory context. When enough Level 1 snapshots accumulate, Mneme compresses them into a single Level 2 snapshot — recursive summarization that mirrors how human memory consolidates short-term into long-term. Token budget splits across layers (L2: 5%, L1: 15%, recall: 5%, sliding: 75%), creating natural pressure: more memories means less live context, same principle as video compression keyframes. The viewport layout reads like geological strata — deep past at the top, recent past below, live present at the bottom:
+
+```
+[Soul — who I am]
+[L2 snapshots — weeks ago, compressed]
+[L1 snapshots — hours ago, detailed]
+[Associative recall — relevant older memories]
+[Pinned events — critical moments from active goals]
+[Sliding window — the present]
+```
+
+**Goal-scoped event pinning** — some moments are too important for summaries. Exact user instructions. Key decisions. Critical corrections. Mneme pins these events to active Goals — they float above the sliding window, protected from eviction, surviving intact where compression would lose the nuance that matters. Pins are goal-scoped and many-to-many: one event can attach to multiple Goals, and cleanup is automatic via reference counting. When the last active Goal completes, the pin releases. No manual unpin, no stale pins accumulating forever.
+
+**Associative recall** — FTS5 full-text search across the entire event history, across all sessions. Two modes: *passive* recall triggers automatically when goals change — Mneme searches for relevant older context and injects it into the viewport between snapshots and the sliding window. Memories surface on their own, right after the soul, right before the present. The agent doesn't have to decide to remember — the remembering happens around it. *Active* recall via the `remember(event_id:)` tool returns a fractal-resolution window centered on a target event — full detail at the center, compressed snapshots at the edges, like eye focus with sharp fovea and blurry periphery.
 
-Three switchable view modes let you control how much detail the TUI shows. Cycle with `Ctrl+a → v`:
+The difference from every other system: memory isn't a tool the agent uses. It's the substrate the agent thinks in. Every LLM call assembles a fresh viewport where identity comes first, then memories, then the present — the agent always knows who it is, always has access to what it learned, and never has to break flow to make that happen.
+
+### TUI HUD & View Modes
+
+The right-side HUD panel shows session state at a glance: session name, goals (with status icons), active skills, workflow, and sub-agents. Toggle with `C-a → h`; when hidden, the input border shows `C-a → h HUD` as a reminder.
+
+Three switchable view modes let you control how much detail the TUI shows. Cycle with `C-a → v`:
 
 | Mode | What you see |
 |------|-------------|
@@ -374,7 +404,13 @@ Three switchable view modes let you control how much detail the TUI shows. Cycle
 | **Verbose** | Everything in Basic, plus timestamps `[HH:MM:SS]`, tool call previews (`🔧 bash` / `$ command` / `↩ response`), and system messages |
 | **Debug** | Full X-ray view — timestamps, token counts per message (`[14 tok]`), full tool call args, full tool responses, tool use IDs |
 
-View modes are implemented via Draper decorators that operate at the transport layer. Each event type has a dedicated decorator (`UserMessageDecorator`, `ToolCallDecorator`, etc.) that returns structured data — the TUI renders it. Mode is stored on the `Session` model server-side, so it persists across reconnections.
+View modes are implemented as a three-layer decorator architecture:
+
+- **ToolDecorator** (server-side, pre-event) — transforms raw tool responses for LLM consumption. Content-Type dispatch converts HTML → Markdown, JSON → TOON. Sits between tool execution and the event stream.
+- **EventDecorator** (server-side, Draper) — uniform per event type (`UserMessageDecorator`, `ToolCallDecorator`, etc.). Decides WHAT structured data enters the wire for each view mode.
+- **TUI Decorator** (client-side) — unique per tool name (`BashDecorator`, `ReadDecorator`, `EditDecorator`, etc.). Decides HOW each tool looks on screen — tool-specific icons, colors, and formatting.
+
+Mode is stored on the `Session` model server-side, so it persists across reconnections.
 
 ### Plugin Architecture [planned]
 
@@ -388,14 +424,6 @@ anima-memory-*       → recall and association (Mneme subscribers)
 
 Currently tools are built-in. Plugin extraction into distributable gems comes later.
 
-### Semantic Memory (Mneme) [planned]
-
-The viewport solves context degradation but creates a new question: what do we lose when events fall off the conveyor belt? Mneme is the answer — memory systems built on top of the viewport.
-
-**Viewport pinning** (next) — the analytical brain watches events approaching eviction and pins critical ones (the original user goal, key decisions). Pinned events float above the sliding window, protected from eviction. Same mental model as pinning a message in Discord or Slack. Pins consume budget, so the brain must be judicious — natural pressure toward minimalism.
-
-**Associative recall** (future) — inspired by [QMD](https://github.com/tobi/qmd). The endocrine system can recall: "Last time this topic came up, curiosity was at 95 and we had a great evening." Hormonal reactions colored by the full history of experiences — like smelling mom's baking and feeling a wave of oxytocin. Not because of the smell, but because of the memory attached to it.
-
 ## The Vision
 
 ### The Problem
@@ -553,10 +581,12 @@ This single example demonstrates every core principle:
 - Event-driven architecture on a shared event bus
 - Dynamic viewport context assembly (endless sessions, no compaction)
 - Analytical brain (skills, workflows, goals, session naming)
-- 8 built-in tools + MCP integration (HTTP + stdio transports)
+- Mneme memory department (eviction-triggered summarization, persistent snapshots, goal-scoped event pinning, associative recall)
+- 9 built-in tools + MCP integration (HTTP + stdio transports)
 - 7 built-in skills + 13 built-in workflows (user-extensible)
 - Sub-agents with lossless context inheritance (5 specialists + generic)
 - Client-server architecture with WebSocket transport + graceful reconnection
+- Collapsible HUD panel with goals, skills, workflow, and sub-agent tracking
 - Three TUI view modes (Basic / Verbose / Debug)
 - Hot-reloadable TOML configuration
 - Self-authored soul (agent writes its own system prompt)
@@ -564,7 +594,7 @@ This single example demonstrates every core principle:
 **Designed, not yet implemented:**
 
 - Hormonal system (Thymos) — desires as behavioral drivers
-- Semantic memory (Mneme) — viewport pinning, associative recall
+- Semantic recall (Mneme) — embedding-based search + re-ranking over FTS5
 - Soul matrix (Psyche) — evolving coefficient table for individuality
 
 ## Development
@@ -585,6 +615,10 @@ bin/dev
 
 # Terminal 2: Connect the TUI to the dev brain
 ./exe/anima tui --host localhost:42135
+
+# Optional: enable performance logging for render profiling
+./exe/anima tui --host localhost:42135 --debug
+# Frame timing data written to log/tui_performance.log
 ```
 
 Development uses port **42135** so it doesn't conflict with the production brain (port 42134) running via systemd. On first run, `bin/dev` runs `db:prepare` automatically.

data/anima-core.gemspec

@@ -21,13 +21,14 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
     ls.readlines("\x0", chomp: true).reject do |f|
-      f.start_with?(*%w[bin/console bin/dev bin/setup .gitignore .rspec spec/ .github/ .standard.yml thoughts/ CLAUDE.md .mise.toml])
+      f.start_with?(*%w[bin/console bin/dev bin/setup Gemfile .gitignore .rspec spec/ .github/ .standard.yml thoughts/ CLAUDE.md .mise.toml])
     end
   end
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "certifi"
   spec.add_dependency "draper", "~> 4.0"
   spec.add_dependency "faraday", "~> 2.0"
   spec.add_dependency "foreman", "~> 0.88"
@@ -36,9 +37,11 @@ Gem::Specification.new do |spec|
   spec.add_dependency "puma", "~> 6.0"
   spec.add_dependency "rails", "~> 8.1"
   spec.add_dependency "ratatui_ruby", "~> 1.4"
+  spec.add_dependency "reverse_markdown", "~> 3.0"
   spec.add_dependency "solid_cable", "~> 3.0"
   spec.add_dependency "solid_queue", "~> 1.1"
   spec.add_dependency "sqlite3", "~> 2.0"
   spec.add_dependency "toml-rb", "~> 4.0"
+  spec.add_dependency "toon-ruby", "~> 0.1"
   spec.add_dependency "websocket-client-simple", "~> 0.8"
 end

data/app/channels/session_channel.rb

@@ -42,9 +42,13 @@ class SessionChannel < ApplicationCable::Channel
     ActionCable.server.broadcast(stream_name, data)
   end
 
-  # Processes user input: persists the message and enqueues LLM processing.
-  # When the session is actively processing an agent request, the message
-  # is queued as "pending" and picked up after the current loop completes.
+  # Processes user input. For idle sessions, persists the event immediately
+  # so the message appears in the TUI without waiting for the background
+  # job, then schedules {AgentRequestJob} for LLM delivery. If delivery
+  # fails, the job deletes the event and emits a {Events::BounceBack}.
+  #
+  # For busy sessions, emits a pending {Events::UserMessage} that queues
+  # until the current agent loop completes.
   #
   # @param data [Hash] must include "content" with the user's message text
   def speak(data)
@@ -57,8 +61,8 @@ class SessionChannel < ApplicationCable::Channel
     if session.processing?
       Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id, status: Event::PENDING_STATUS))
     else
-      Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id))
-      AgentRequestJob.perform_later(@current_session_id)
+      event = session.create_user_event(content)
+      AgentRequestJob.perform_later(session.id, event_id: event.id)
     end
   end
 
@@ -141,10 +145,18 @@ class SessionChannel < ApplicationCable::Channel
     token = data["token"].to_s.strip
 
     Providers::Anthropic.validate_token_format!(token)
-    Providers::Anthropic.validate_token_api!(token)
-    write_anthropic_token(token)
 
-    transmit({"action" => "token_saved"})
+    warning = begin
+      Providers::Anthropic.validate_token_api!(token)
+      nil
+    rescue Providers::Anthropic::TransientError => transient
+      # Token format is valid but API is temporarily unavailable (500, timeout, etc.).
+      # Save the token to break the prompt loop — it will work once the API recovers.
+      "Token saved but could not be verified — #{transient.message}"
+    end
+
+    write_anthropic_token(token)
+    transmit({"action" => "token_saved", "warning" => warning}.compact)
   rescue Providers::Anthropic::TokenFormatError, Providers::Anthropic::AuthenticationError => error
     transmit({"action" => "token_error", "message" => error.message})
   end
@@ -189,12 +201,12 @@ class SessionChannel < ApplicationCable::Channel
   # client can handle both paths with a single code path.
   #
   # Payload: session_id, name, parent_session_id, message_count,
-  # view_mode, active_skills, goals.
+  # view_mode, active_skills, goals, children (when present).
   #
   # @param session [Session] the session to announce
   # @return [void]
   def transmit_session_changed(session)
-    transmit({
+    payload = {
       "action" => "session_changed",
       "session_id" => session.id,
       "name" => session.name,
@@ -204,7 +216,14 @@ class SessionChannel < ApplicationCable::Channel
       "active_skills" => session.active_skills,
       "active_workflow" => session.active_workflow,
       "goals" => session.goals_summary
-    })
+    }
+
+    children = session.child_sessions.order(:created_at).select(:id, :name, :processing)
+    if children.any?
+      payload["children"] = children.map { |child| {"id" => child.id, "name" => child.name, "processing" => child.processing?} }
+    end
+
+    transmit(payload)
   end
 
   # Switches the channel to a different session: stops current stream,

data/app/decorators/tool_call_decorator.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
+require "toon"
+
 # Decorates tool_call events for display in the TUI.
 # Hidden in basic mode — tool activity is represented by the
 # aggregated tool counter instead. Verbose mode returns tool name
 # and a formatted preview of the input arguments. Debug mode shows
-# full untruncated input as pretty-printed JSON with tool_use_id.
+# full untruncated input with tool_use_id — TOON format for most
+# tools, but write tool content preserves actual newlines.
 #
 # Think tool calls are special: "aloud" thoughts are shown in all
 # view modes (with a thought bubble), while "inner" thoughts are
@@ -39,7 +42,7 @@ class ToolCallDecorator < EventDecorator
     {
       role: :tool_call,
       tool: payload["tool_name"],
-      input: JSON.pretty_generate(payload["tool_input"] || {}),
+      input: format_debug_input,
       tool_use_id: payload["tool_use_id"],
       timestamp: timestamp
     }
@@ -88,6 +91,30 @@ class ToolCallDecorator < EventDecorator
     {role: :think, content: thoughts, visibility: visibility, tool_use_id: payload["tool_use_id"], timestamp: timestamp}
   end
 
+  # Full tool input for debug mode. Write tool content is shown with
+  # preserved newlines instead of TOON-escaping them into literal \n.
+  # @return [String] formatted debug input
+  def format_debug_input
+    input = tool_input
+    case payload["tool_name"]
+    when "write" then format_write_content(input)
+    else Toon.encode(input)
+    end
+  end
+
+  # Formats write tool input with file path header and content body.
+  # Content newlines are preserved so the TUI can render them as
+  # separate lines, matching how read tool responses display file content.
+  # @param input [Hash] tool input hash with "file_path" and "content" keys
+  # @return [String] path + content with real newlines, or TOON-encoded hash when content is empty
+  def format_write_content(input)
+    path = input.dig("file_path").to_s
+    content = input.dig("content").to_s
+    return Toon.encode(input) if content.empty?
+
+    "#{path}\n#{content}"
+  end
+
   # Formats tool input for display, with tool-specific formatting for
   # known tools and generic JSON fallback for others.
   # @return [String] formatted input preview
@@ -98,8 +125,10 @@ class ToolCallDecorator < EventDecorator
       "$ #{input&.dig("command")}"
     when "web_get"
       "GET #{input&.dig("url")}"
+    when "read", "edit", "write"
+      input&.dig("file_path").to_s
     else
-      truncate_lines(input.to_json, max_lines: 2)
+      truncate_lines(Toon.encode(input), max_lines: 2)
     end
   end
 end

data/app/decorators/tool_decorator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Base class for server-side tool response decoration. Transforms raw tool
+# results into LLM-optimized formats before they enter the event stream.
+#
+# This is a separate decorator type from {EventDecorator}: EventDecorator
+# formats events for clients (TUI/web), while ToolDecorator formats tool
+# responses for the LLM. They sit at different points in the pipeline:
+#
+#   Tool executes → ToolDecorator transforms → event stream → EventDecorator renders
+#
+# Subclasses implement {#call} to transform a tool's raw result into an
+# LLM-friendly string. Each tool can have its own ToolDecorator subclass
+# (e.g. {WebGetToolDecorator}) registered in {DECORATOR_MAP}.
+#
+# @example Decorating a tool result
+#   ToolDecorator.call("web_get", {body: html, content_type: "text/html"})
+#   #=> "[Converted: HTML → Markdown]\n\n# Page Title\n..."
+class ToolDecorator
+  DECORATOR_MAP = {
+    "web_get" => "WebGetToolDecorator"
+  }.freeze
+
+  # Factory: dispatches to the tool-specific decorator or passes through.
+  #
+  # @param tool_name [String] registered tool name
+  # @param result [String, Hash] raw tool execution result
+  # @return [String, Hash] decorated result (String) or original error Hash
+  def self.call(tool_name, result)
+    return result if result.is_a?(Hash) && result.key?(:error)
+
+    klass_name = DECORATOR_MAP[tool_name]
+    return result unless klass_name
+
+    klass_name.constantize.new.call(result)
+  end
+
+  # Subclasses override to transform the raw tool result.
+  #
+  # @param result [String, Hash] raw tool execution result
+  # @return [String] LLM-optimized content
+  def call(result)
+    raise NotImplementedError, "#{self.class} must implement #call"
+  end
+
+  private
+
+  # Combines decorated text with an optional metadata tag so the LLM
+  # knows the content was transformed.
+  #
+  # @param text [String] the transformed content
+  # @param meta [String, nil] conversion tag (e.g. "[Converted: HTML → Markdown]")
+  # @return [String]
+  def assemble(text:, meta:)
+    meta ? "#{meta}\n\n#{text}" : text
+  end
+end

data/app/decorators/tool_response_decorator.rb

@@ -3,8 +3,9 @@
 # Decorates tool_response events for display in the TUI.
 # Hidden in basic mode — tool activity is represented by the
 # aggregated tool counter instead. Verbose mode returns truncated
-# output with a success/failure indicator. Debug mode shows full
-# untruncated output with tool_use_id and estimated token count.
+# output with a success/failure indicator and tool name for per-tool
+# client-side rendering. Debug mode shows full untruncated output
+# with tool_use_id and estimated token count.
 #
 # Think tool responses ("OK") are hidden in basic and verbose modes
 # because the value is in the tool_call (the thoughts), not the response.
@@ -18,11 +19,13 @@ class ToolResponseDecorator < EventDecorator
 
   # Think responses are hidden in verbose mode — the "OK" adds no information.
   # @return [Hash, nil] structured tool response data, nil for think responses
+  #   `{role: :tool_response, tool: String, content: String, success: Boolean, timestamp: Integer|nil}`
   def render_verbose
     return if think?
 
     {
       role: :tool_response,
+      tool: tool_name,
       content: truncate_lines(content, max_lines: 3),
       success: payload["success"] != false,
       timestamp: timestamp
@@ -30,11 +33,12 @@ class ToolResponseDecorator < EventDecorator
   end
 
   # @return [Hash] full tool response data with untruncated content, tool_use_id, and token estimate
-  #   `{role: :tool_response, content: String, success: Boolean, tool_use_id: String|nil,
+  #   `{role: :tool_response, tool: String, content: String, success: Boolean, tool_use_id: String|nil,
   #     timestamp: Integer|nil, tokens: Integer, estimated: Boolean}`
   def render_debug
     {
       role: :tool_response,
+      tool: tool_name,
       content: content,
       success: payload["success"] != false,
       tool_use_id: payload["tool_use_id"],
@@ -53,7 +57,11 @@ class ToolResponseDecorator < EventDecorator
 
   private
 
+  def tool_name
+    payload["tool_name"]
+  end
+
   def think?
-    payload["tool_name"] == THINK_TOOL
+    tool_name == THINK_TOOL
   end
 end