Start here · Architecture chooser
Choose an integration layer
Keep your existing architecture. Adopt the lowest Heddle layer that already owns the runtime mechanics your product needs.
Customization depth
Independent levels 1–5
Hosting depth
Independent levels A–F
Documentation status
Canonical reference
Assumptions
- You know which server, transport, and UI layers your product already owns
- You want Heddle to own reusable agent mechanics without becoming your application framework
- Conversation semantics, tools, traces, artifacts, and approval lifecycle
- Optional process-local run identity, replay, cancellation, and remote protocol correctness
- Existing server and client framework choices
- Identity, authorization, public API, persistence policy, deployment, and UI
Choose by what your host already has
| Existing product shape | Start with | Status |
|---|---|---|
| Nothing beyond a TypeScript process | runQuickstartConversationCli | Supported SDK boundary and runnable example |
| A local process that needs product tools or MCP | Quickstart plus host extensions | Runnable examples |
| A process that owns output or a local UI | createConversationEngine | Supported SDK boundary |
| A server, worker, or Electron backend | @roackb2/heddle/hosted | Supported boundary and runnable service example |
| Express with REST + SSE | @roackb2/heddle/hosted/http-sse | Supported helper and runnable Express example |
| A remote JavaScript client over any transport | @roackb2/heddle-remote | Supported browser-safe protocol package |
| A browser using the conventional REST/SSE contract | @roackb2/heddle-remote/http-sse | Supported helper and runnable client example |
| A React/Vite product | Remote client plus the React reference | Runnable reference, not a React SDK |
| Fastify, Hono, Nest, tRPC, WebSocket, or IPC | Hosted service plus a host adapter | Adaptation guide |
| Multi-process or serverless active runs | Hosted service plus shared routing or delivery | Architecture guidance |
Customization and hosting are different decisions
The root @roackb2/heddle package exposes a progressive customization ladder:
- stand up a persisted conversation;
- add tools, MCP, and capability-specific context;
- shape output and consume results;
- own sessions, approvals, and lifecycle;
- inject production session and artifact storage.
Hosting is an optional second axis. Add /hosted only when execution must be independently addressable, cancellable, or reconnectable. Add the remote package only when events cross a transport boundary.
Entry-point boundaries
| Import | Assumption it adds |
|---|---|
@roackb2/heddle | A Node host wants the curated conversation SDK |
@roackb2/heddle/hosted | One long-lived process owns active runs and bounded replay |
@roackb2/heddle/hosted/http-sse | The host chose conventional Node HTTP/SSE framing |
@roackb2/heddle-remote | A JavaScript client consumes validated run envelopes |
@roackb2/heddle-remote/http-sse | That client chose the conventional REST/SSE resource |
@roackb2/heddle/advanced | A Node host needs lower-level runtime assembly |
The advanced entrypoint does not implicitly opt into hosting or remote transport.
Stop at the neutral boundary
For tRPC, Fastify, Hono, Nest, WebSocket, Electron IPC, or queues, stop at the transport-neutral run service and implement the adapter inside the framework your product already uses. Preserve stable run identity, ordered sequences, cursor replay, explicit cancellation, and exactly one terminal event.
Continue to Responsibility boundary before implementation, or start the first-agent tutorial if you are evaluating from scratch.