agent

Overview ¶

Approval broker — routes tool-approval prompts to whatever interface can actually answer them.

Mutating commands and tools prompt for approval (y/N/a). Historically that prompt was a terminal read (askLine), which works for the REPL but hangs headless (no terminal) and can't reach the web UI. The broker abstracts "ask the user to approve X" so it can be answered from the terminal OR the browser, depending on which front-end is driving.

• Terminal mode (default, plain REPL): prompts via askLine as before.
• Web mode (headless, or -serve-write when chosen): emits an EvApproval event the dashboard renders as Approve/Deny/Always buttons, and blocks on a response delivered via POST /api/approve.

Session budgets — a gentle ceiling on time and tokens.

The per-turn iteration cap stops ONE runaway turn. This stops the other failure mode: twenty reasonable turns that quietly add up to ninety minutes and a novel's worth of generated tokens before you notice. On a local box the cost isn't dollars, it's your afternoon and your GPU — so the budget is a WARNING, never a hard stop. Aborting a session mid-thought to even enforce a ceiling would be worse than the overrun.

Config: "budget_minutes" and/or "budget_ktokens" (thousands of generated + reasoning tokens — reasoning counts because on a reasoning model it's most of the spend). Zero/unset = that dimension is off. Crossing a threshold prints one warning; every further 50% prints a reminder. /budget shows current usage against the ceilings anytime.

Git checkpointing — repo-level protection where .bak is file-level.

Before every model turn, `git stash create` snapshots the working tree into an unreferenced commit WITHOUT touching the worktree or the stash list — the cheapest possible checkpoint. /rewind restores any turn's state with `git checkout <hash> -- .`.

Honest limitations, stated because they matter: `git stash create` only records TRACKED files, so a brand-new untracked file the model created after a checkpoint is not deleted by rewinding (its content is simply not managed); and the snapshot commits are unreferenced, so git gc can eventually collect them — checkpoints are session-scale protection, not history. /commit is the durable path, and its message generation enforces the Conventional Commits standard the system prompt already mandates.

Command tools — user-defined tools without recompiling.

MCP is the heavyweight plugin path (a running server, its own protocol); this is the lightweight one: drop a manifest in .agent/tools/<name>.json describing a tool and the executable that backs it, and it joins the registry at startup. Wrap a PowerShell deploy script, a curl one-liner, a Python analyzer — anything runnable — as a first-class tool the model can call, with typed arguments it can't typo.

.agent/tools/deploy_status.json
{
  "name": "deploy_status",
  "description": "Check the deploy status of a service in an environment.",
  "command": ["pwsh", "-File", "scripts/DeployStatus.ps1"],
  "parameters": {
    "service": {"type": "string", "description": "Service name", "required": true},
    "env":     {"type": "string", "description": "dev|stage|prod"}
  },
  "read_only": true,
  "timeout_sec": 60
}

The model's typed arguments are passed to the executable two ways, so the script can consume whichever is convenient: as --key value flags appended to the command, AND as a JSON object on stdin. The command runs in the workdir; stdout+stderr (capped) come back as the tool result.

Safety: read_only tools skip the approval prompt and may run in plan mode (declare it only for genuinely side-effect-free scripts). Everything else goes through the same y/N approval as run_command. Manifests are the user's own files under their repo — trusted like a Makefile, not like model output.

Custom slash commands — prompt templates as files.

Your recurring runbook-style prompts become commands: a markdown file at <repo>/.agent/commands/<name>.md (or ~/.agent/commands/<name>.md for personal ones) turns into /<name>. The file body is the prompt; the placeholder $ARGUMENTS is replaced with whatever follows the command:

.agent/commands/migrate.md:
  Migrate $ARGUMENTS to the reusable build workflow. Read the current
  workflow first, keep OTCOM versioning intact, and verify with a dry run.

> /migrate proj5

Repo-local commands shadow personal ones of the same name. Built-in commands always win — a template can't override /verify. Discovered at startup; shown in /help and Tab-completed like any other command.

Shared slash-command dispatch for the read-only / informational commands.

The REPL historically handled every slash command inline in its input loop, printing directly. That's fine for the REPL but leaves the TUI unable to run any command (it has no access to that loop). This file extracts the SAFE subset — commands that only READ and report state — into runInfoCommand, which returns its output as a string instead of printing. The REPL prints the string; the TUI emits it to the bus. One source of truth, and the TUI gains real slash-command support for everything that doesn't mutate session state.

STATEFUL commands (/plan, /commit, /rewind, /compact, /fork, /reload, /model, /init, /undo, /allow, /ctx, /resume, /diff, /verify) are NOT here: they mutate messages/session/tree and are entangled with the REPL loop. Routing those through a shared dispatcher safely is a larger refactor; they remain REPL-only, and the TUI reports as much for them.

Context construction v2 — relevance over recency, opt-in.

v1 (the default) sends the whole transcript, append-only, and trims with pruning/shrinking/compaction. Its virtue is KV-cache prefix reuse: within and across turns the server reprocesses only new suffixes (~25s measured for a cold 13k prompt, near-zero warm). Its vice is accumulation: a long session drags every stale tool output behind it forever.

v2 REBUILDS the wire context at each turn boundary from what matters now:

[system prompt]
[session state: modified files, checklist, elision note]
[the session's original goal, if it scrolled out of the window]
[recent dialogue: user messages + final assistant replies only]
[the new user instruction]

Old tool outputs are deliberately absent — the model re-reads what it needs, and reads are cheap. The trade is a full prompt reprocess once per turn (bounded, small prompt) versus v1's growing-but-cached prompt. Which wins depends on session length and hardware; that's why this is a live toggle (/ctx v2, /ctx v1) and the per-turn cost prints dim — measure, then decide.

INVARIANTS the distiller guarantees: never emits tool-role messages or assistant messages carrying tool_calls (so the wire can't contain orphaned halves of a call/result pair), always includes the newest user message, and never touches the canonical transcript — sessions persist full fidelity regardless of mode. One honest cost: mid-turn crash persistence is weaker in v2 (the turn's messages land in the session file at turn end, not per-iteration).

A real diff engine — first-class change display.

The previous "diff preview" printed all old lines then all new lines: a six-line struct edit showed twelve lines of which eleven were identical noise, and the actual String→string change was a spot-the-difference puzzle. This produces proper unified-style hunks: unchanged context dim, removals red, additions green, and — for modified line pairs — the changed SPAN inside the line highlighted, so a one-token edit reads at a glance.

Used by: edit_file and write_file previews (terminal AND the tool result, so the model sees exactly what its edit did), and the /diff command (session changes per file, current content vs the pre-session .bak).

Algorithm: trim common prefix/suffix lines, LCS-align the middle when it's small enough (the overwhelmingly common case for tool edits — a single contiguous region), degrade to one replace-hunk when it isn't. O(n) for the trim, bounded DP for the middle, no dependencies.

One-shot mode (-p) and the eval harness (-eval).

One-shot makes the agent pipeable and scriptable:

agent -p "fix the failing test" -yes ~/proj && go test ./...

The eval harness is how harness changes stop being judged by vibes: a JSON file of cases, each a prompt plus a shell check, run N times against the current model and harness. "Did the loop breaker help" and "is Gemma better than Qwen at this" become pass rates instead of impressions.

Eval file format (JSON array):

[
  {"name": "add-position", "prompt": "set the position column on insert in cmd/add.go",
   "check": "go build ./... && grep -q position cmd/add.go"},
  ...
]

Each run gets a FRESH context (system prompt rebuilt, empty history) and a fresh Sandbox, but shares the working directory — checks that mutate state should clean up after themselves (e.g. via git checkout in the check).

stdout subscriber — renders bus events to the terminal.

This is the first (and during migration, primary) event subscriber. It reproduces the exact terminal styling the direct fmt.Println sites use, so when a print site is migrated from fmt.Println("x") to emitLine("x") the visible output is unchanged. The TUI and dashboard are alternate subscribers that will render the same events differently.

The color hint on an event maps to the same ANSI codes tint() uses. A subscriber may be silenced (the TUI installs itself and silences stdout, since it owns the screen).

In-place lines (EvOverwrite, e.g. a spinner or progress counter) are a special case: at most one is "open" at a time. Opening one erases and replaces whatever was there before; any OTHER event first erases it, the same way term.go's spinner erases itself the moment real output starts, so a fast-moving status line never leaves stale text mixed into the transcript.

A tool-calling coding agent in pure Go (stdlib only), speaking the OpenAI-compatible chat completions API. Works with LM Studio, llama.cpp's llama-server, vLLM, Ollama's /v1 endpoint, or any other OpenAI-compatible server.

v7 design philosophy — built for a capable model (Gemma 4 12B class):

• Trust the model: minimal system prompt (identity, workdir, hard rules), no sampling overrides, no iteration cap, no call-pattern babysitting.
• Guards are tripwires, not walls: backups, empty-write rejection, the repeat-call loop breaker, and y/N gating on mutating commands protect against consequences without distorting what the model attempts.
• Close the loop against reality: a configured verify command runs after any turn that modified files, and failures are fed back automatically. Hooks enforce user invariants (gofmt, lint gates) without model turns.
• Repo-level safety: a git checkpoint before every turn, /rewind to any of them, /commit with a model-written Conventional Commits message.
• Plan mode (/plan): read-only exploration → numbered plan → your approval → execution. Cheaper to review a plan than flailed edits.
• Context is managed, not just accumulated: stale reads are pruned and old tool outputs elided — in rare big batches, because history edits invalidate the server's KV-cache prefix (see session.go).
• Streaming: tokens print as they generate — no dead air.

Layout:

main.go     flags, config, system prompt, REPL
loop.go     the agent loop (runTurn), verify loop, spawn_task
tools.go    tool registry + handlers, command approval
session.go  session persistence, /compact, context management
api.go      OpenAI-compatible types, streaming chat, SSE parsing
mcp.go      MCP client (stdio transport) — external tool servers
eval.go     one-shot mode (-p) and the eval harness (-eval)
term.go     stdin ownership, colors, spinner, input reading

Usage:

go run . [flags] [working-dir]
go run . -url http://172.22.208.1:1235 -model google/gemma-4-12b ~/myproject
go run . -p "fix the failing test" -yes ~/myproject     (one-shot)
go run . -eval evals.json -runs 3 ~/myproject           (benchmark)

Flags:

-url     base URL of the server (default: auto-detect Windows host in WSL2)
-model   model id (default: first non-embedding model from GET /v1/models)
-resume  resume a session: 'latest' or a name from /sessions
-p       run one prompt non-interactively and exit
-yes     auto-approve mutating commands and fetches (for -p / scripts)
-eval    run an eval file (JSON array of {name,prompt,check}) and report
-runs    runs per eval case (default 1)

~/.agent/config.json (all optional): url, model, compact_tokens, command_timeout_sec, verify_command, mcp_servers.

Input: single lines as usual; type """ alone to start a multi-line block (paste code freely), and """ alone again to send it.

Trace legend:

⚙  tool call requested by the model
✏  file written or edited (absolute path shown)
✗  write/edit rejected by a guard (nothing touched disk)
$  command executed (auto-approved) or awaiting your y/N
⧉  subtask running in a fresh context
✓  verify command passed

MCP (Model Context Protocol) client — built on the official Go SDK (github.com/modelcontextprotocol/go-sdk/mcp).

This used to be a hand-rolled JSON-RPC client. It now delegates to the canonical SDK, which tracks the spec (protocol version negotiation, both transports, session management, notifications, cancellation) so we don't chase it by hand. The config surface and registry behavior are unchanged: each configured server's tools/list result is registered alongside the built-ins, calls proxy through as tools/call, and the model can't tell an MCP tool from a native one.

Config (~/.agent/config.json):

"mcp_servers": {
  "pg":    {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgres://..."]},
  "engram": {"url": "http://localhost:8088/mcp/", "no_prefix": true, "prefer": true},
  "sbx":   {"command": "sandbox", "args": ["mcp", "-image", "python:3-alpine"], "prefer": true,
           "prefer_hint": "a locked-down, network-less sandbox. Run untrusted or unfamiliar code here (sbx_run_script / sbx_run_sandbox) before running it on the host."}
}

Two transports: "command" (stdio child process) or "url" (Streamable HTTP). Tool names are prefixed with the server name (pg_query) unless "no_prefix" is set. "prefer" surfaces the server in the system prompt; "prefer_hint" overrides the default notes-server wording for non-notes servers (e.g. a sandbox).

Notifications — because at local token rates a turn can take minutes, and the worst UX in this agent is alt-tabbing away and missing a y/N prompt.

Two layers: a terminal BEL (\a — Windows Terminal flashes/badges the tab) and a Windows toast via powershell.exe interop, WSL's bridge to the host. The toast uses a NotifyIcon balloon — no modules to install, works on a stock Windows box. It's fired async and best-effort: a notification is never worth blocking the agent for, and never worth an error message.

Config: "notify_sec" — a turn longer than this notifies on completion (default 10; 0 disables everything including approval pings). Quick turns stay silent: you're still looking at the terminal anyway.

Prompt construction — every model-facing prompt string lives here, separate from the execution loop that decides WHEN to send it. Extracted from loop.go, session.go, context.go, and checkpoint.go as a pure text-building layer: no I/O, no globals mutated, explicit inputs. See docs/PHASE4_LOGIC_DECOUPLING.md for the rationale and rollout plan.

buildSystemPrompt (main.go) stays where it is — it was already its own function and moving it would be pure churn.

Named agent roles + auxiliary model routing.

ROLES — .agent/agents/<name>.md (repo) or ~/.agent/agents/<name>.md (personal; repo shadows personal) define specialists the model can delegate to via spawn_task's "role" argument:

.agent/agents/reviewer.md:
  model: qwen2.5-coder-14b-instruct

  You are a strict code reviewer. Point out bugs, race conditions, and
  deviations from the repo's conventions. Do not fix anything — report.

The optional "model: <id>" header routes the subtask to a different model on the same server; the rest of the file is appended to the subtask's system prompt. /agents lists what's loaded.

AUX MODEL — "aux_model" in config routes housekeeping (compaction summaries, session titles, commit messages) to a smaller/faster model. None of those need the 12B, and every VRAM-second they don't take is one the main model gets.

/stats — throughput made visible.

You're tuning VRAM, speculative decoding, and KV-cache behavior by feel; this turns feel into numbers. Everything here is measured at the harness (token counts are the same chars/4 estimate the context budget uses, so they're consistent with /context), because local servers are inconsistent about reporting usage on streamed responses.

The number that matters most on local hardware: TTFB (time to first byte of generation) ≈ prompt processing time. Append-only turns keep it small via KV-cache prefix reuse; anything that edited history (shrink, prune, compact, resume) shows up here as a spike. When /stats says the last request spent 90 seconds before the first token, that was the cache-invalidation bill.