@kpanks/coding-agent

@kpanks/coding-agent

Praetor's coding agent. A NativePraetorEngine preconfigured with a curated tool subset and a system prompt focused on disciplined code changes.

Tool surface

All tools are gated by the coding role and tagged ["coding", "free"] because none of them call a paid API.

Tool	What it does
read_file	Read a UTF-8 file relative to repoRoot.
write_file	Create or overwrite a UTF-8 file. Creates parent dirs.
edit_file	Replace every literal occurrence of find with replace.
list_files	List immediate children of a directory inside the repo.
grep_codebase	Regex over all text files (skips node_modules, .git, dist).
git_status	Working-tree status (added/modified/deleted/staged).
git_diff	Unstaged diff, optionally for a single path.
git_commit	Stage and commit. Will not push or rebase.
git_branch	List local branches and report the current one.
git_log	Recent commits (default 20).
run_tests	Auto-detect (npm test, pytest, cargo test, go test) and run.
run_command	Spawn an arbitrary command; cwd pinned to repoRoot, 30s timeout.

Path safety

Every file path supplied to a file tool is resolved against the configured repoRoot and rejected if it escapes the root (the same containment pattern as the world-gen scene server in the API).

Free vs. paid model routing

The agent constructs its inner NativePraetorEngine with { quality: "balanced", preferTags: ["coding"] }. With the default catalogue this lands on Claude Sonnet (paid) or Xiaomi MiMo-V2.5 (open weight, sovereign-mode eligible) — pass an explicit route requirement to force one or the other:

new CodingAgent({
  ...,
  route: { quality: "balanced", sovereign: true }, // open-weight only
});

Usage

import { CodingAgent } from "@kpanks/coding-agent";
import { LlmRouter } from "@kpanks/router";
import { ToolRegistry } from "@kpanks/tools";

const router = new LlmRouter();
const tools = new ToolRegistry();
const agent = new CodingAgent({
  repoRoot: "/abs/path/to/repo",
  router,
  tools,
  toolContext: {},
});

const result = await agent.run({
  goal: "Add a /healthz route to the API and a test that asserts 200",
  outputs: [],
  budgetUsd: 1,
});