Docs

How the harness is put together, and how to drive it. Written beside the code it describes.

Overview

A model-agnostic agent harness: the agent loop, tool execution, context management and permissions as one layer, with the model as a replaceable backend.

Getting started

Node 22.6 or newer. The project uses Node's native TypeScript type stripping, so there is no build step for development.

Dependencies run one way: **a frontend consumes the engine, never the reverse.** Since the split into packages, the resolver enforces most of that on its own — an undeclared import simply fails — but a relative path that climbs out of one package into another would still resolve, so the layering test also checks for that. The engine contains no console.*, no process.stdout, and never touches the TTY. When it needs to ask the user something it calls an injected permissionPrompt; when it has progress to report it yields an AgentEvent. Who renders is the frontend's business.

Providers and models

Vendor model ids change faster than this package ships, so compiling them into TypeScript guarantees they are wrong within weeks. The catalog is a JSON file: packages/engine/src/providers/catalog.json.

Permissions

| Mode | Shown as | Behaviour | | --- | --- | --- | | default | Manual | Ask before anything that changes state | | acceptEdits | Accept edits | File edits pass, everything else asks | | plan | Plan | Read-only; refuse every change | | auto | Auto | Edits and routine commands pass, risky ones ask | | bypassPermissions | Bypass | Approve everything |

Frontends

Three consumers of the same AgentEvent stream, plus a desktop shell around the third. Adding each of them required no engine change, which is the whole point of the split.

Documentation is maintained in English; the reference describes an API whose identifiers are English.