tai/taicpp/docs/wiring/agent.md

Wiring for the agent core (integrator checklist)

I did not touch main.cpp, Makefile, src/cli, src/store, src/config, PARITY.md.

Build

• Add to the link line: -lcurl -lpthread (already -lcurl; -lpthread for threads). Static target needs nothing extra (zlib not used).
• src/llm/py.cpp etc. include "unicode_data.h", "json.h" relatively; no new include dirs needed beyond the existing -I per src dir. Note consts.h, text.h exist in several src dirs: my files include their own directory first.
• Removed legacy files: src/agent/{exec,loop}.{h,cpp}, src/agent/tools.cpp, src/llm/llm.{h,cpp}. main.cpp (ToolRegistry, RegisterAll, RunTurn) and tests/test_main.cpp (llm::ChatClient("openai", ...), ModelHealth, Opencode, feed_sse, provider_info) use that removed placeholder API: replace the run command with agent::Agent and drop those test sections. src/agent/agent.mk and src/llm/llm.mk are stale (unused by the Makefile).
• Test targets (my files): tests/agent_diff.cpp, agent_e2e.cpp, agent_sched.cpp (+ agent_memstore.h) built with all of src/llm/*.cpp src/agent/*.cpp, driven by tests/agent_diff.py, agent_e2e.py, agent_sched.py (binaries expected at build/agent_diff, build/agent_e2e, build/agent_sched).

Hooks to apply at startup

1. agent::ports().store is per-Agent (pass StorePort* to Agent); set the rest once: ports().runtime, shell, ui, mcp, skills, plexer, tui (optional), ops, scheduler_db.
2. llm::set_log_sink(&debuglog) (DebugLog adapter: enabled(), event(level, area, kind, message, profile, bot, meta)).
3. llm::set_box_port(&sandbox) for the opencode-in-box fallback.
4. llm::ChatClient::set_tool_catalog(natives, core) with the 61 tool names and data::CoreTools() so log_completion counts match.
5. Build AgentConfig from Config (fields in agent_config.h, llm/ports.h::LlmConfig); ChatClient and Agent keep a reference, so mutate that same object when settings change.
6. --update-models -> agent::update_models_command(cfg); --resume -> agent::resume_turn(agent); one-shot -> Agent::run_verified; scheduler mode -> agent::Scheduler(cfg, db).start().
7. REPL/TUI set agent.prompter, agent.stream_factory, agent.on_phase as in Python; Agent::total_step_cap() is the live-patchable Consts.TOTAL_STEP_CAP.

Port contracts the other owners must satisfy (see src/agent/ports.h)

• StorePort: same semantics as the Python Store methods of the same name; rows are json::Value objects with the Python key names; get_chunks_by_ids returns an object keyed by the id as a string; sql_rows is a read-only SELECT for RagStats.
• ShellPort: run_live_shell = run_live(command, shell=True, cwd, env=environ+extra_env, stream, ask); shell_target_paths = tai.py shell_target_paths.
• McpPort, SkillsPort, OpsPort, PlexerPort: mirror the named tai.py functions (comments in ports.h).
• UiPort is optional; without it replies print raw and the non-Glow ┌─/└─ call frames are used.