文档

这一层是怎么搭起来的，以及怎么驱动它。文档就写在它描述的代码旁边。

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.

文档以英文维护：参考部分描述的是一套标识符本身就是英文的 API。