Adapter overview
Extend Brain with custom harness runners, external tool services, and persistence backends.
Brain keeps its session coordinator (internal/session) small by delegating model execution, tool execution, and external storage to explicit extension boundaries.
Harness adapters
Implement a custom agent loop over harness.Factory / harness.Runner or the stdio JSON protocol.
Persistence adapters
Store immutable checkpoint blocks and session discovery indexes via persistence.Objects and persistence.Metadata.
Go interfaces
Read the generated Go interface and struct definitions from internal/harness and internal/persistence.
Extension boundaries at a glance
| Boundary | Go interface / protocol | When to build one | Built-in implementations |
|---|---|---|---|
| Harness | harness.Factory and harness.Runner (internal/harness), or newline-delimited JSON over stdin/stdout (harness.ProcessFactory). | You want to run a different agent loop, prompt compaction strategy, or runtime behind Brain's session API. | pi (runners/pi, a Node.js child process wrapping @earendil-works/pi-coding-agent via harness.ProcessFactory). |
| Tool service | HTTP JSON / SSE tool protocol and MCP Streamable HTTP (internal/tools). | You want to expose external tools, sandboxes, resource gates, or operator approvals in any language without changing Brain. | tools.Registry (internal/tools/registry.go, with HTTP and MCP transports), plus reference services in examples/tools, services/sandbox, and services/resources. |
| Persistence | persistence.Objects and persistence.Metadata (internal/persistence). | You want to publish checkpoint blocks or index session metadata in a storage backend not covered by the built-in drivers. | Checkpoint object stores (persistence.Objects): filesystem, s3, r2, and gcs.External metadata index ( persistence.Metadata): PostgreSQL (postgres_env). |
Coordinator contracts
session.Repository, session.ToolExecutor, and session.Checkpoints contain only
operations used by the session owner. cmd/brain constructs concrete implementations
and owns their shutdown. The HTTP API depends only on api.Catalog for tool discovery.
These Go extension points live under internal/ and require a source build.
tools.Registry owns authorization, schemas, deadlines, inspection delegation,
and output policy. tools.Transport owns one call's wire protocol and connection
cleanup. tools.NewWithTransports accepts compiled transport implementations;
adding a protocol does not change scheduling. External tools still use HTTP/SSE/MCP
without changing Go code.
How each boundary plugs in
- External tool services run out of process over HTTP JSON,
text/event-stream, or MCP Streamable HTTP (mcp_tool). You bind them directly in the"tools"array of your configuration file without modifying or recompiling Brain. - Harness runners can be plugged in as external child processes under
"harnesses"(speaking theRunnerFramestdio protocol implemented byharness.ProcessFactory) or compiled into the binary by implementingharness.Factoryininternal/harness. - Persistence adapters live in
internal/persistenceand are wired intopersistence.NewObjectsandpersistence.NewPostgresfrom the"persistence"configuration block. The default local database is SQLite (store.SQLite); a compiled replacement implementsstore.Metadataand is supplied throughstore.New. Append-onlyevents.jsonlandnative/files remain in the localdata_dir.
See Harness adapters, Persistence adapters, and Go interfaces for implementation details and contract requirements.