tai/taicpp/plan.md

# detz — C++23 port of `tai.py` — Plan (v1)

> App name: `detz`. Future: subcommand of `molo` (moloapp framework).
> Source of truth to port: `../tai.py` (~40k lines) + tests `../test_tai.py`, `../tai_test.py`.
> Original must remain untouched — no downgrades in functionality.
> Coding standard / reuse: `moloapp` (`/home/retoor/projects/moloapp`) — components, providers, clients (HTTP client w/ streaming), header-only style, per-part `.mk` files, root Makefile, `build/` outputs only.

## 1. Goals & non-goals

Goals:
- Full-featured structured C++23 port of tai.py as `detz` binary in this dir (`taicpp/`).
- Max depth/layering in file structure; maximally object-oriented.
- argparse/CLI done well so it later plugs in as `molo detz ...` subcommand.
- Reuse moloapp: HTTP client (+SSE streaming), LLM provider types (`src/llm`, `src/clients`), app errors/middleware patterns where applicable.
- Docs: README.md, AGENTS.md, SPEC per module, workflow + versioning/tagging/git automation via AGENTS.md + Makefile targets.

Non-goals: modifying `../tai.py`; rewriting moloapp itself (vendor/link only).

## 2. Source inventory (from `../tai.py`)

~40k lines. Key classes/functions to port (grouped):

| Group | Symbols |
|---|---|
| Constants/config | `Consts`, `Config`, settings fns (`validate_setting_scope`, `normalize_setting_value`, `parse_setting_env/stored`, `export_settings_to_env`, `boot_settings`), `dir_key`, `orientation_block`, `capability_block` |
| Text/ANSI/utils | `Ansi`, `paint`, `now_iso`, `short_error`, `truncate`, `capped_text`, `read_capped`, `chunk_lines`, `collapse_repeated_lines`, `split_leading_tags`, `expand_file_mentions`, `complete_files`, `known_model_ids`, `resolve_tag` |
| Shell/sandbox | `Sandbox`, `ShellSession`, `shell_target_paths`, `segment_targets`, `curl_hint`, `speak`, `Spinner`, `LiveStream`, `PtyProc`, `LaneBoard`, `Glow` |
| Crypto/vault | `SealError`, `Seal` |
| Persistence | `Store` (sqlite+FTS5), `spill_output`, `spilled_view`, `spill_or_truncate`, `DebugLog`, `ensure_column`, `fts_*` |
| LLM backends | `BackendError`, `Opencode`, `ModelHealth`, `ChatClient`, providers (openai/anthropic/google/deepseek/xai/openrouter via moloapp), streaming SSE |
| Agents/tools | `Tools`, `Agent`, `Approval`, `Denied`, `AgentsFull`, `GoalFailure`, `GoalVerdict`, `GoalVerifier`, `RetrievalEval`, `RagStats` |
| Comms/ops | `Telegram`, `Install`, `SysInfo`, plexer (`PlexerError`, `PlexerController`, `Native/TmuxPlexerController`), TUI (`TuiTheme/Watched/Style/Span/Event/Key/Click`, see `tui.md`), MCP server (`mcp.md`, `--serve-mcp`), cap orchestrator (`cap.md`) |
| CLI | argparse tree (~`--cap`, `--serve-mcp`, `--mcp-port`, …) → port to structured CLI layer |

Full class list: extract with `grep -n "^class " ../../tai.py` during milestone M0 and pin counts in SPEC.

## 3. Target structure (deep, layered)

```
taicpp/
  plan.md  README.md  AGENTS.md  SPEC.md  CHANGELOG.md  VERSION
  Makefile  (includes src/*/[*.mk])  .clang-format
  src/
    cli/        arg parser tree, detz_main, future molo_subcommand.{h,cpp}
    config/     consts, settings, env, boot
    util/       ansi, text, time, truncate, files_mention, complete
    shell/      sandbox, session, pty, spinner, livestream, lanaboard, glow
    seal/       seal (vault crypto)
    store/      sqlite store, fts, spill, debuglog, migrations
    llm/        thin adapters over moloapp src/llm + src/clients (streaming); model_health, chat_client, backends
    agent/      tools registry, approvals, agent loop, goal_verifier, retrieval_eval, rag
    comms/      telegram, install, sysinfo, speak
    plexer/     controller iface, native, tmux
    tui/        theme/style/span/events/keys/render (per tui.md)
    mcp/        serve-mcp http (per mcp.md), auth bearer
    cap/        orchestrator (per cap.md)
  tests/  README.md + per-module *_test.cpp mirroring ../test_tai.py + ../tai_test.py cases
  docs/   specs per module (cli.md, store.md, llm.md, agent.md, tui.md, mcp.md, cap.md), workflow.md, versioning.md
  tools/  version-bump.sh, tag.sh, changelog.sh
  build/  (generated only)
```

Rules: headers `.h` + impl `.cpp`; one class per file pair where feasible; no outputs outside `build/`; `-std=c++23 -Wall -Wextra`, warning-free.

## 4. moloapp reuse map

- HTTP/SSE streaming: `moloapp/src/clients/*` (`client.h`, `sse.h`, transports) — use directly, do not reimplement.
- Provider/model types: `moloapp/src/llm/*`, `src/openai|anthropic|google|deepseek|xai|openrouter/*`.
- App patterns (errors, middleware, routing) for MCP HTTP serve: `moloapp/src/app/**/*`.
- CLI conventions: `moloapp` CLI part (`tests/...cli`, `src/cli`) + `audit/MOLO-CLI-001`.
- Build pattern: per-part `*.mk` + root Makefile; `example/example.mk` as template.

## 5. CLI design (molo-ready)

- `detz` binary with same flags as tai.py argparse tree (parity table in `docs/cli.md`).
- Implementation: `src/cli::{Parser, Command, DetzCli}` returning a `Command` value object; `main.cpp` only wires DI + dispatches. Future `molo detz` = register `DetzCommand` as subcommand (adapter header `molo_subcommand.h` stubbed in M1).
- Golden test: `--help` output diff vs `python ../tai.py --help`.

## 6. Milestones & acceptance

- M0 scaffold: dirs, root Makefile + `src/*/[*.mk]`, `main.cpp` printing version, `make`, `make test` green, AGENTS.md workflow live. Accept: warning-free build, outputs only in `build/`.
- M1 CLI parity: full argparse tree ported + `--help` golden test + molo subcommand stub. Accept: flag-for-flag table complete.
- M2 util+config: consts/settings/ansi/text/files. Accept: unit tests mirror python edge cases.
- M3 store: sqlite+FTS5, spill, debuglog, migrations. Accept: CRUD/FTS tests pass.
- M4 shell: sandbox/session/pty/speak. Accept: sandboxed exec tests.
- M5 llm: adapters over moloapp clients + streaming + health. Accept: mocked-transport chat/stream tests, no real network.
- M6 agent/tools: registry, approvals, loop, goal verifier, rag eval. Accept: ported `test_tai.py` scenarios (mocked backends).
- M7 plexer/tui/comms: native+tmux controllers, TUI render, telegram/install/sysinfo. Accept: headless render + controller tests.
- M8 mcp+cap: serve-mcp (bearer), cap orchestrator. Accept: route-level tests through real stack.
- M9 docs/release automation: README, SPECs, CHANGELOG, version bump/tag targets. Accept: `make release` path documented & dry-runnable.

Order per AGENTS.md workflow: spec delta → code → tests → changelog, per milestone.

## 7. Build/test/lint (mirrors moloapp AGENTS.md)

```sh
g++ --version   # need C++23 (g++ ≥ 13, moloapp expects 15.2)
make            # whole repo
make test
make lint       # -Wall -Wextra clean; zero findings
make release PART=patch|minor|major MSG="..."
```

## 8. Versioning/tagging/git automation

- `VERSION` file (`0.1.0` start, semver); `src/cli/version.hpp` generated from it at build.
- Targets: `make version-bump PART=x`, `make tag` (annotated `detz-vX.Y.Z`), `make changelog` (prepend CHANGELOG entry), `make release PART=x MSG=...` = bump+changelog+commit+tag. Never push unless asked.
- First: write root `AGENTS.md` (workflow above) before M1 code — per original request.

## 9. Risks

- tai.py size (~40k lines): mitigate by module-by-module parity tables + ported test counts per milestone.
- moloapp API drift: pin moloapp commit in SPEC; thin adapter layer in `src/llm/`.
- sqlite/FTS5 + pty in C++: reuse system sqlite3, forkpty; isolate in `store/` + `shell/`.

## 10. Next action

Write `AGENTS.md` (workflow + commands), then M0 scaffold.