tai/taicpp/docs/agent.md

# agent: Agent core, Tools, goal verifier, RAG stats, scheduler

Literal port of tai.py 1.44.2 (lines 9016-9335, 17071-20640, 40391-40460). Namespace `detz::agent`, sources in `src/agent`.

## Layout

| File | tai.py origin |
|---|---|
| `data.cpp` (generated) | `TOOL_SCHEMAS`, `TOOL_TAGS`, `CORE_TOOLS`, `LAZY_NAME_STOP`, prompt texts. Regenerate: `python3 -I src/agent/gen/gen_data.py > src/agent/data.cpp` |
| `data_html.cpp` (generated) | `html.entities.html5` for `html.unescape` |
| `agent.cpp/.h` | `Agent`, `select_tools`, `tool_catalog`, `compact_messages`, `resume_turn`, `update_models_command`, `default_runner`, mentions |
| `tools_*.cpp`, `tools.h` | `Tools` (63 handlers, `dispatch`, secrets, audit, box helpers) |
| `goal.cpp` | `Denied`, `AgentsFull`, `Approval`, `GoalFailure`, `GoalVerdict`, `GoalVerifier` |
| `rag.cpp` | `RetrievalEval`, `RagStats` |
| `registry.cpp` | `spawn_agent`, `poll_agent`, `list_agents`, `clear_agents`, `running_agents` |
| `scheduler.cpp` | `note_schedule_result`, `watch_schedule`, `schedule_running`, `scheduler_tick`, `run_scheduler_loop`/`start_scheduler` (class `Scheduler`) |
| `text.cpp` | `truncate`-family helpers, tags, `chunk_lines`, `spill_*`, tmux/history helpers, `html.unescape`, schedule helpers |
| `tui_control.cpp` | `grr_control_path`, `grr_control_call` (client only) |
| `zipfile.cpp` | `zipfile.extractall` (stored + deflate) for `install_skill` |
| `ports.h` | the narrow interfaces to everything this module does not own |

## Ports (declared here, implemented elsewhere)

`StorePort` (mirrors Python `Store` method names), `RuntimePort` (worker store), `ShellPort` (run_live, LiveStream, LaneBoard, box), `UiPort` (Spinner, Glow, markdown, diff; optional, plain fallbacks exist), `McpPort`, `SkillsPort`, `PlexerPort`, `TuiControlPort` (optional, built-in client otherwise), `OpsPort` (install, release, sysinfo, speech), `SchedulerDbPort`. Unwired required ports raise `PortNotWired`, shown to the model as `error: port not wired: X`. Plexer unwired means "no session", exactly like no tmux.

## Behaviour notes

- All string lengths and slices are code points (`detz::py`, `src/llm/py.h`).
- Integers beyond int64 clamp in `int()` conversions (Python is unbounded); JSON keeps big ints verbatim.
- `html.unescape`, `str.lower/upper` (including final sigma) use tables generated from Python.

## Verification (what was actually run)

- `tests/agent_diff.py`: 7604 cases per seed (seeds 1-4 run, 0 mismatches). Includes the full `json.dumps(TOOL_SCHEMAS)` byte comparison, `select_tools` on 24 prompts plus fuzz, `tool_catalog`, all prompt texts, goal verdicts, CLI output parsers, history cleanup, tag helpers, html/url helpers, schedule helpers, candidate ordering of `ChatClient`, `sessions_block` byte comparison.
- `tests/agent_e2e.py`: 43 scripted conversations through the real Agent loop in both programs (messages, HTTP request bodies, store events, audit rows identical). Covers file tools, shell, secrets, schedules, bots/mentions, compaction, retries, 400 tool fallback, ask_user, approval deny, verify loop, remember, web_fetch/search, fork/poll, streaming quirks, deadline.
- `tests/agent_sched.py`: `scheduler_tick` against a real sqlite vault.
- Build for these tests: compile `src/llm/*.cpp src/agent/*.cpp tests/agent_*.cpp` with `-lcurl -lpthread` (see wiring doc).

## Not verified / gaps (honest list)

- Tools needing FTS or other modules were only checked on argument validation paths: `search`, `record_search`, `graph_*`, `tags`, `recall`, `audit` search, `export_terminal_log`.
- Port-backed tools (MCP, skills install/create, plexer, install, release, sysinfo, speak, listen, sandbox `box_*` paths, LaneBoard) are ported but no test drives a real implementation: the ports are fakes or unwired.
- `RagStats`/`RetrievalEval` compile and follow the Python line by line but have no differential test (needs a real vault).
- Interactive tty paths (`ask_approval` console branch with `Denied` guidance, `shell_ask` getpass) are unexercised.
- urllib error strings are approximated from libcurl codes (`<urlopen error [Errno 111] Connection refused>` etc.).
- Muse session map/locking and CLI runners (`muse_run`, grok, claude, codex, gemini, opencode) are ported; only their output parsers are differentially tested, the process runners were not run against the real CLIs.
- `zipfile`: bzip2/lzma members unsupported.
- `str.lower` final-sigma uses derived property sets; `repr` printable test is approximated for exotic code points.