skarmy-dev-agent

Skarmy's dev agent (the Engineering Lead) — the container agent that builds a real Next.js web app inside a sandbox. This repo owns the agent's source and the sandbox image it runs in; the Skarmy hub pins that image by name and never imports this code.

The agent's protocol key inside the hub is still builder (its manifest, entrypoint builder.cjs, and the skarmy-sandbox image name are the stable wire contract) — this repo is just named for what it is: the dev agent.

It doesn't write code itself — it drives opencode (an open-source coding agent) and wraps it in a real quality gate: bring up a live dev preview, build from the spec, then verify → fix → re-verify (typecheck, dev server, headless-browser console, production build) until the build is genuinely stable, polish against a screenshot, snapshot the workspace, and write a /BUILD.md.

Layout

| Path | What it is | |---|---| | agents/builder/entry.ts | The supervisor — opencode lifecycle, the verify/fix loop, snapshot, deliverable. Bundled to builder.cjs. | | agents/builder/opencode-map.ts | Pure opencode-event → protocol-event mapping (unit-tested). | | agents/builder/sandbox-agents.ts | The AGENTS.md system prompt written into the workspace. | | agents/heartbeat/entry.ts | A tiny reference container agent (the hub's container-pipeline smoke) — rides the same image. | | sandbox/driver/{verify,snapshot,mcp-search}.ts | Verification gate, workspace snapshot, and the web-search MCP server. | | sandbox/template/ | The Dockerfile + opencode pin the image is built from. | | .github/workflows/build-image.yml | CI: build + push the GHCR image, republish the E2B template on release. |

Its only runtime dependency on Skarmy is @skarmy/agent-sdk — the shared agent protocol.

Develop

Prereqs: Node 22+, Docker (for building/running the image locally).

npm install        # @skarmy/agent-sdk resolves from npm (^0.2.1)
npm run typecheck
npm test           # driver unit tests

npm run build:drivers        # esbuild → sandbox/template/driver/*.cjs
npm run build:image:local    # docker build -t skarmy-sandbox:local  (the tag the hub's local dev uses)

Working across both repos

Open ../skarmy.code-workspace (at the GitHub/ folder level, above the repos) — a VS Code multi-root workspace that shows the hub and all seven agent repos, this one included, in one window. Everything stays a separate git repo; the workspace just makes the sibling checkouts convenient (you can run the hub's live smoke without switching windows). Which commands run where:

| Task | Repo | Command | |---|---|---| | Edit the agent + drivers, type-check, unit-test | dev-agent | npm run typecheck · npm test | | Rebuild the sandbox image after a driver change | dev-agent | npm run build:image:local | | Drive a real end-to-end build (rents a sandbox, runs your driver) | hub | bun run smoke:builder | | Exercise snapshot save + reopen | hub | bun run verify:reopen |

The inner loop (edit → typecheck → unit test → rebuild image) is entirely in this repo. The live proof needs the hub because the smokes call createAgentSession and the hub is what a sandbox phones home to — they need the hub's Docker Postgres + MinIO running and consume the skarmy-sandbox:local image you build here.

How the hub uses the image

The hub's agent registry names this image (OPENCODE_SANDBOX_TEMPLATE, defaulting to skarmy-sandbox:local) and launches /opt/skarmy/driver/builder.cjs inside it. So:

• Local dev: run npm run build:image:local here → the hub's smoke:builder / verify:reopen find skarmy-sandbox:local on your Docker.
• Prod: the CI republishes the E2B template skarmy-sandbox on a release; the hub picks it up on the next sandbox it creates (never on a hub deploy).

A sandbox-image change only takes effect after the image is rebuilt/republished — editing this code does not reach a running hub until then.

Contract

The agent speaks the @skarmy/agent-sdk protocol (PROTOCOL_VERSION). To prove conformance in CI you can add the SDK's contract checks (@skarmy/agent-sdk/contract-tests); today the drivers are covered by their own unit tests (opencode-map, verify, snapshot).

License

MIT