@agentcompose/coding-agent

A configurable, spec-compliant coding worker for AgentCompose.

It wraps the pi coding-agent loop (read / edit / write / bash over a scoped, disposable workspace) behind the capability code, and returns a summary plus the diffs it made. Authored with the AgentCompose SDK only — no engine dependency — so it's an independent component any host can register, and its internals are swappable behind the spec descriptor.

npm install @agentcompose/coding-agent

Use

import { makeCodingAgent } from "@agentcompose/coding-agent";
import { inProcess } from "@agentcompose/sdk";

const coding = makeCodingAgent({
  defaults: { baseUrl: "http://localhost:4000/v1", model: "gpt-4o-mini" },
});

const client = inProcess(coding);
const task = await client.submit([
  { kind: "text", text: "Add a /health route to server.js that returns { ok: true }." },
]);

for await (const ev of client.events(task.id)) {
  if (ev.type === "result" || ev.type === "error") break;
}
const final = await client.get(task.id);
// final.result.parts → [ { kind:"text", summary+files }, { kind:"json", CodingResult } ]

The model is bring-your-own: any OpenAI-compatible chat gateway (OpenAI, LiteLLM, Ollama, vLLM, a proxy). The API key resolves from the environment via a secretRef (default OPENAI_API_KEY), and is injected into pi at runtime — never written to disk.

What it returns

Every run produces a structured CodingResult (the json part) alongside a human summary:

interface CodingResult {
  summary: string;        // the agent's closing summary
  changes: FileChange[];  // { path, status: added|modified|deleted, diff }
  patch: string;          // one combined unified diff across all changes
  toolsUsed: string[];    // tools invoked, in order
  workspace: string;      // absolute path the run used
}

The combined patch is also emitted as a changes.patch artifact.

Configuration

Key	Default	Description
workspace	(temp)	Directory to edit in place. Omitted → a fresh disposable temp dir per run.
keepWorkspace	false	Keep a temp workspace after the run (for inspection). Ignored when workspace is set.
tools	all	Built-in tools the agent may use: read, write, edit, bash, grep, find, ls.
maxTurns	30	Stop after this many turns (one model response + its tool calls).
instructions	—	Extra project guidance appended to the coding system prompt.
provider	—	BYO-model: { baseUrl, model, apiKey } (OpenAI Chat Completions compatible).

Workspace & change capture

A coding agent runs bash and edits a real filesystem, so where it runs is the load-bearing production concern. This worker gives each run a scoped, disposable, diffable workspace:

• explicit workspace → edits that directory in place; never deleted.
• otherwise → a fresh temp dir per run, cleaned up afterwards (unless keepWorkspace).

Changes are captured with a git snapshot (write-tree at start, diff at end). This is tool-agnostic — it yields a real unified patch no matter which tools the agent used — and it never touches your branches or HEAD. When git is unavailable, the run still succeeds and simply reports no diff.

Swappable internals

pi sits behind an injectable session factory (opts.sessionFactory). Production wiring builds a pi session from config; tests/embedding inject a stub. Because the worker's spec descriptor (capability: "code") is identical regardless, the body can later move to a different coding engine or a sandboxed subprocess without changing the contract.

License

Apache-2.0