@insitue/agent-core
v0.3.1
Published
The InSitue edit-engine seam: provider-agnostic agent loop, proposal parsing, changeset/diff, atomic sandboxed file mutation, git checkpoint/commit, source resolution. Pure of transport/UI — reused by @insitue/companion (local) and the cloud autopilot.
Readme
@insitue/agent-core
The orchestration + edit engine shared by the InSitue companion (local dev loop) and the cloud autopilot (production). Pure of HTTP and DOM; the host (companion / cloud) wires transports + storage.
What's inside
| Subtree | Purpose |
|---|---|
| agent/orchestrator.ts | Turn lifecycle — pick → propose → approve → write → undo, with checkpointing |
| agent/claude-code/transport-*.ts | Three pluggable Claude transports: cli-headless (default), mcp, sdk |
| agent/claude-code/normalize.ts | Single parity core that converts every transport's stream into our AgentEvent protocol |
| agent/claude-code/mcp-server.ts | Standalone stdio MCP that exposes the insitue_context tool to a spawned Claude |
| agent/proposals.ts | Validates + reduces a model's proposed edits into a sandboxed changeset |
| edit/gateway.ts | Single chokepoint for filesystem writes — realpath-sandboxed to the project root, never escapes |
| edit/mutator.ts | Atomic apply (write all-or-nothing), with byte-exact git-checkpoint preservation for undo |
| edit/git.ts | Per-turn git checkpoints (.insitue/checkpoints/<ref>/) — restore on undo, surgical commit on session close |
Install
pnpm add @insitue/agent-coreDepends on @insitue/capture-core (the shared protocol),
@modelcontextprotocol/sdk, diff, and execa. Claude Agent SDK
is an optional peer — host installs it only when wiring the
sdk transport.
Safety boundaries
- Edit gateway never escapes the project root. Every write
path is
realpath'd and rejected if it falls outside the configured root. This is the moral equivalent of a chroot for agent edits — the model can't write to/etc/passwdeven with a hostile prompt. - Atomic apply. A multi-file changeset writes all-or-nothing, with prior-state checkpoints so undo restores byte-exact.
- No HTTP. No DOM. This package never reaches the network or the browser; transports do that, and they're swappable.
Stability
Internal to the InSitue ecosystem. Consumed by @insitue/companion
(dev) and the cloud agent (prod) — both shipped from this monorepo
in lockstep with capture-core. Not intended for direct user import.
License
MIT. © InSitue.
