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)

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.

7.4 KiB Raw Blame History

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