First use the component and deployment model to decide whether Heddle belongs inside your backend or behind a separate Execution Host. This guide then selects the narrowest public API within that deployment shape.
Heddle's curated SDK assumes a Node.js 20+ TypeScript host that wants to build a conversational agent experience. It intentionally does not assume how that host is deployed, which server framework it uses, how events are transported, or which client renders the conversation.
Use this guide before copying an example. The goal is to adopt the lowest layer that does the needed heavy lifting while leaving existing product architecture in control.
Heddle supplies two small conversation hosts as adoption shortcuts:
ConversationAgentServiceis a structured in-process application service for products that already own input and output.runQuickstartConversationCliis a temporary console host for evaluation, examples, smoke runs, and very small terminal integrations.
They share runtime defaults and credential preflight, but they intentionally do
not share the same session or output contract. Both live above the core
conversation engine and are distinct from Heddle's heddle CLI/TUI, server,
and web control plane. When a host outgrows either shortcut, it keeps the same
engine contracts and moves down the ladder instead of migrating to a different
runtime.
HOST-OWNED PRODUCT
UI state and rendering
|
@heddleagent/run-client consumer + optional HTTP/SSE client
|
host transport adapter + optional Node SSE helper
|
application service and composition root
(product session IDs, tools, config, repositories, policy)
======================== HEDDLE SDK BOUNDARY ========================
ConversationRunService
(active run ID, ordered events, bounded replay, cancel, approvals)
|
ConversationEngine
(persisted sessions, turns, compaction, traces, artifacts)
|
agent loop, models, tools, host extensions, MCP
The application service above the boundary is host code. The
HostedAgentService
example shows one useful shape, but it is not a required Heddle wrapper and is
not transport infrastructure.
| Concern | Heddle owns | Host owns |
|---|---|---|
| Conversation semantics | Messages, turns, continuation, compaction, leases, and persisted session behavior | Stable product conversation ID and access policy |
| Agent execution | Model/tool loop, tool registry/execution, host-extension composition, traces, and artifacts | Product tools, system context, model choice, credentials, and capability policy |
| Approvals | Approval request/resolution lifecycle and run integration | Whether an action is allowed, authenticated approver, and approval UI/policy |
| Active runs | Run ID, ordered sequence, process-local replay, subscription, cancellation, and terminal result | Lifetime of the run service, address scope, process routing, draining, and multi-process delivery |
| Remote consumption | Cursor advancement, duplicate suppression, sequence-gap failure, terminal detection, bounded reconnect timing, and runtime envelope validation | Public activity/result schemas, actual transport timer/handle, and error UX |
| Persistence | File-backed defaults plus injectable session/archive/artifact repository ports | Production repository implementations, retention, encryption, backup, and tenancy |
| Identity and authorization | No identity-provider assumption | Authentication, tenant/user mapping, authorization for start/subscribe/cancel |
| Transport/API | Optional fetch/SSE client and Node SSE streaming correctness when that preset is selected | Framework, routes/procedures, wire schemas, auth, errors, limits, CORS, and rate limiting |
| Client experience | Semantic activities, terminal run events, and remote cursor/retry calculations | Messages, tool rendering, UI state, transport timers, retry UX, notifications, and product-specific result presentation |
Do not rebuild Heddle-owned conversation or run behavior in the host. In particular, avoid replaying product chat history into every prompt, generating a second run ID, adding another in-process event bus, or treating subscriber disconnect as implicit cancellation.
| What the host already has | Heddle entrypoint | Example to follow |
|---|---|---|
| A TypeScript process that owns input/output | ConversationAgentService |
01-headless-conversation.ts |
| A terminal evaluation with no host loop | runQuickstartConversationCli |
01-interactive-chat.ts |
| A local loop that needs product tools or MCP | Quickstart plus tools/host extensions | 02-add-a-tool.ts, 03-add-an-mcp-server.ts |
| Its own output sink or local UI | createConversationEngine + createConversationTextHost or host callbacks |
04-custom-output.ts |
| A server/worker that owns transport | @heddleagent/runtime + @heddleagent/runtime/runs |
05-hosted-agent/01-hosted-service |
| Express with REST + SSE | Core plus @heddleagent/runtime/runs/http-sse |
05-hosted-agent/02-http-sse-api |
| A remote client over any transport | @heddleagent/run-client plus a host transport |
Remote conversation runs |
| A browser using the conventional REST/SSE contract | @heddleagent/run-client/http-sse |
05-hosted-agent/03-browser-client |
| A React/Vite product needing an end-to-end reference | Same remote client plus host UI/session state | 05-hosted-agent/04-react-ui |
| A backend invoking a separately deployed Execution Host | @heddleagent/execution-host-client plus a direct or AgentCore transport |
Execution Host adopter backend |
| That backend needs the generic lifecycle in PostgreSQL | @heddleagent/postgres/execution-host/conversations plus the lifecycle service |
Execution Host adopter backend |
The former @roackb2/heddle-adopter@5.13.0 coordinate is deprecated and
remains installable only for existing consumers.
For tRPC, Fastify, Hono, Nest, WebSocket, Electron IPC, queues, or another transport, stop at the hosted-service layer and implement the adapter in the host's existing framework. Preserve the run lifecycle contract—start, sequence-based subscribe/replay, explicit cancel, and a terminal event—without copying Express-specific code.
Use ConversationAgentService when the host owns input/output but wants Heddle
to resolve runtime defaults, ensure one stable session, capture structured
activities, and return the normal turn result. The underlying engine remains
available for progressive customization.
Use runQuickstartConversationCli when Heddle may own the prompt loop and
plain-text terminal experience. The host supplies configuration and optional
capabilities. It adds a terminal host around the same generic starter defaults.
Use createConversationEngine when the host owns presentation, commands,
approval UI, or session browsing. Heddle still owns the durable conversation
model. Call engine.turns.submit(...) for an in-process turn.
Add one host-long-lived ConversationRunService when request and subscription
lifetimes differ, clients can reconnect, or a turn needs a separately
addressable cancel/approval lifecycle. It is a process-local coordinator above
the engine, not a transport or durable message broker.
Import it from @heddleagent/runtime/runs so the hosted-process assumption is
visible. The root export remains available for compatibility.
Use ConversationRunProtocolCodec and ConversationRunConsumerService from
@heddleagent/run-client when events cross an untrusted transport boundary or a
client can reconnect. The independent package keeps the Node runtime, server,
CLI, model providers, and control-plane dependencies out of remote clients.
The host supplies public activity/result schemas; Heddle owns envelope
validation, JSON safety, cursor advancement, duplicate/gap handling, terminal
detection, and retry calculation.
This base layer does not own HTTP, SSE, tRPC, timers, auth, or UI state. Add
@heddleagent/run-client/http-sse only when the host uses the conventional REST
run resource and authenticated streaming fetch. See
Remote conversation runs.
Add a host-owned adapter when a remote client needs start, subscribe, cancel, or approval operations. Validate all untrusted wire data and project internal run results into an explicitly public schema. Authentication and authorization must happen before resolving the Heddle run address.
For Node HTTP/SSE, @heddleagent/runtime/runs/http-sse owns strict replay cursor
parsing, canonical frames, backpressure, and subscriber disconnect cleanup.
The host still owns route registration, authentication/authorization, public
schemas, JSON error policy, CORS, and limits. Express and other Node frameworks
can share the helper because it targets IncomingMessage and ServerResponse.
tRPC, WebSocket, native bridges, and other transports stay on the neutral base
layer.
Add a transport client only when it matches the host's API. Keep protocol parsing, cursors, and abort propagation below product UI state. Keep messages, tool rendering, retry UX, and product result handling in the application's normal client architecture.
Use @heddleagent/execution-host-client when Heddle runs in a separate Execution Host
rather than inside the product backend. The package owns v1 validation, short-
lived execution authority, independent MCP capability verification, and the
ExecutionHost outbound port. Its optional conversation and Node surfaces also
own generic turn orchestration, JWKS/conversation HTTP mechanics, and safe
local key-file loading. It also owns durable lifecycle ordering over an
injected store. The adopter retains product
authentication, tenant mapping, production key
storage/rotation, invocation-ID selection, product MCP behavior, the database
adapter and schema, retention, and product result application. The Execution
Host alone imports Heddle and receives no adopter database credential. See
Build an Execution Host adopter backend.
| Requirement | Extend here |
|---|---|
| Domain actions or data access | ToolDefinition, toolkits, or host extensions |
| MCP-backed capabilities | prepareMcpHostExtension |
| Prompt/system behavior | Engine systemContext, turn prompt formatting, or host extensions |
| Model and credentials | Host composition root / createConversationEngine config |
| Approval behavior | ConversationEngineHost.approvals and the product's policy/UI |
| Session/artifact storage | ChatSessionRepository and ArtifactRepository |
| Public API fields | Host-owned validation schemas and terminal result/error projection |
| Remote cursor/retry correctness | ConversationRunConsumerService |
| Runtime run-envelope validation | ConversationRunProtocolCodec with host activity/result schemas |
| Conventional Node HTTP/SSE | @heddleagent/runtime/runs/http-sse plus host routes and policy |
| Conventional browser REST/SSE | @heddleagent/run-client/http-sse plus host schemas and headers |
| tRPC, WebSocket, or IPC | Host transport adapter above the application service |
| React or other UI state | Product client/application layer above the protocol client |
| Multi-process live delivery | Host-selected shared routing/broker infrastructure |
Before implementation, discover and state:
- the host's server framework and transport;
- how identity and tenancy are authenticated;
- how product conversation IDs are persisted;
- which UI/state layer consumes run events;
- whether one process owns a run for its lifetime;
- which repositories, approval policy, tools, and telemetry are production requirements.
Then select the lowest matching layer, copy only the relevant example stages, and preserve the dependency direction shown above. Prefer adapting the host's existing framework over installing the sample stack. Do not move transport, auth, or UI decisions into Heddle core.
Before handoff, verify at minimum:
- a second turn reuses the same durable Heddle session;
- disconnecting one subscriber does not cancel the run;
- reconnecting after sequence N does not restart the turn or duplicate earlier events;
- a different authenticated scope cannot subscribe to or cancel the run;
- explicit cancellation reaches a terminal cancelled event;
- only intended public result fields cross the transport boundary.
Continue with the programmatic guide index for API details or the numbered SDK examples for runnable code.