kodingo-agent

Purpose

This package is the local agentic execution engine behind Kortex Build. It replaces Build's old fixed pipeline (plan once → generate once per file → test once → one retry) with a real turn-by-turn tool-use loop: on every turn the model sees the transcript so far and either calls a tool or reports it's done, and the loop executes that tool call for real against the developer's own machine before the next turn starts. Looking around — reading one more file, grepping for a symbol — is just another turn, not a one-time precomputed step.

The loop itself runs locally, in whichever process embeds it (kodingo-cli or the kodingo-vscode extension host) — not on the server. Every turn still calls back to kodingo-api for the actual model decision (model routing, quota, and billing stay server-side, unchanged), but every tool the model can call executes against real local files and a real local shell, because that's where the filesystem and shell actually live.

What This Repo Owns

• The turn loop itself (src/loop)
• The tool set: read_file, glob, list_directory, grep, edit_file, write_file, run_command (src/tools)
• Safety controls: turn budget, token/cost budget, wall-clock timeout, and a real kill switch that aborts mid-flight, not just at the next turn boundary (src/safety)
• The local, per-machine, per-project trust store (~/.kodingo/build-trust.json) governing when the loop may act without asking again (src/trust)
• The ModelCallPort / ProgressReporterPort interfaces each consumer implements for its own environment (src/ports)

What This Repo Does NOT Do

• No model calls of its own — it calls out through ModelCallPort, implemented by each consumer (today: an HTTP call to kodingo-api, which owns model routing, quota, and cost)
• No WebSocket client, no persistence, no UI — those live in kodingo-cli and kodingo-vscode, which render ProgressReporterPort events however fits their surface
• No filesystem watching — tools act once per call, on request, they don't observe

Architecture Notes

• Every tool call and every model call is threaded with an AbortSignal so cancellation is real and immediate wherever the underlying primitive supports it (child process kill, aborted HTTP request), and cooperative (checked between steps) everywhere else.
• edit_file's verification is mechanical, not model-trusted: oldString must be an exact, unique, verbatim substring of the real file, no single edit may touch more than half the file, and no set of edits across a run may touch more than 65% of it — either rule alone was proven insufficient in production dogfooding; both are kept together.
• run_command favors a project's own package.json scripts (test/build/lint) over arbitrary shell strings — arbitrary execution is a distinct, more dangerous capability that requires its own explicit trust grant, not bundled into general build trust.

Dependencies

• No runtime dependency on kodingo-core yet — nothing in this package's current scope (a fully local tool-use loop) needs its domain types. That may change once a consumer's pre-loop context injection needs a shared shape.
• Consumed by kodingo-cli and kodingo-vscode, linked locally via npm link during active development; published to npm with a real semver bump once stable, matching the release model already used by kodingo-core.

Change Discipline

Every tool executes exactly what it's asked, mechanically verified where verification is possible (edit_file's size guard, run_command's allowlist) — it does not use an LLM call to decide whether its own actions are safe. If a check can be expressed as plain code, it must be, not delegated back to the model that's already being supervised.