Package entrypoints

Install only the boundary you need

Install the finished coding-agent product globally when you want the heddle command:

npm install --global @heddleagent/cli

The Node runtime package requires Node.js 20 or newer:

npm install @heddleagent/runtime

Install the independent remote package only in applications that consume a hosted run without embedding the Node agent runtime:

npm install @heddleagent/run-client

TypeScript control planes that call a separately deployed compatible Execution Host install the adopter package:

npm install @heddleagent/execution-host-client

Add the official PostgreSQL adapter only when that backend persists the generic Execution Host conversation lifecycle:

npm install @heddleagent/postgres @heddleagent/execution-host-client drizzle-orm pg

Non-TypeScript control planes consume the versioned OpenAPI, JSON Schema, and golden fixtures without installing or porting the Heddle runtime. The former @roackb2/* coordinates are deprecated and remain installable only for existing consumers. New heartbeat integrations use the official @heddleagent/postgres/heartbeat adapter.

The JavaScript packages use ESM. Import from documented package and subpath entrypoints rather than reaching into dist or internal src paths.

Entrypoint map

@heddleagent/runtime: curated product-host SDK

The default entrypoint is organized as a five-rung progressive-disclosure ladder.

1. Start a conversation

Primary exports:

• runQuickstartConversationCli;
• resolveQuickstartConversationCliDefaults;
• QuickstartConversationCliRunnerService;
• createConversationEngine;
• built-in default model constants.

Use the quickstart runner when Heddle may own a small terminal prompt loop. Use the conversation engine when your product owns presentation, session browsing, approvals, or lifecycle.

Core contracts

The root exports common types such as RunInput, RunResult, RunFailure, ModelRunFailureCode, ToolDefinition, ToolCall, ToolResult, TraceEvent, and StopReason.

These are host-facing contracts. Import them from the package root instead of duplicating shapes.

2. Add capabilities

Primary exports include:

• defineHostExtension and ConversationEngineHostExtensionService;
• prepareMcpHostExtension, prepareMcpHostExtensionCatalog, and MCP option/result types;
• ToolRegistry, ToolExecutionService, ToolBundleComposer, and RuntimeToolService;
• artifact and Agent Skills toolkits and services.

The older top-level tools engine option remains deprecated; new product hosts should compose product tools through hostExtensions.tools.

3. Shape input and output

Primary exports include:

• createConversationTextHost and ConversationTextHostService;
• ConversationActivity and its handler/correlation types;
• HeddleEventType and HeddleEventTypeValue;
• ConversationTurnResultSummary and ConversationTurnToolResult;
• ToolActivitySummarizer.

Use these contracts to build custom terminal, API, telemetry, or UI adapters without importing internal runtime modules.

4. Own lifecycle and approvals

The root exports conversation engine types, session and turn service contracts, turn inputs/results, run-service contracts for compatibility, approval services and policies, remembered project rules, runtime tool-selection profiles, and EngineConversationTurnService for hosts that already own lower-level session paths.

For new hosts, prefer createConversationEngine. For long-lived process code, import ConversationRunService from the explicit /runs entrypoint even though the root compatibility export remains available.

5. Supply storage

Primary exports include:

• ArtifactRepository, ArtifactService, FileArtifactRepository, and artifact record types;
• ChatSessionRepository, FileChatSessionRepository, revision/conflict errors, catalog inputs/results, and ChatSession;
• RuntimeCredentialService and credential-source types.

Session and artifact repositories can be replaced independently. Traces and memory remain path-oriented through stateRoot today.

@heddleagent/runtime/runs: process-local active runs

Import ConversationRunService and its run address, handle, replay, stream-item, approval, projection, and error contracts here when request and subscription lifetimes differ.

import {
  ConversationRunService,
  ConversationRunConflictError,
  ConversationRunReplayUnavailableError,
} from '@heddleagent/runtime/runs'

This subpath adds no transport and no durable broker. It makes the long-lived-process assumption explicit.

@heddleagent/runtime/runs/http-sse: Node SSE correctness

Exports:

• parseConversationRunSseReplayCursor;
• streamConversationRunSse;
• ConversationRunSseReplayCursorError;
• SSE event, protocol, cursor-input, and streaming option types.

These helpers target Node request/response primitives, so Express and other Node frameworks can use them without making Express part of Heddle core.

@heddleagent/run-client: browser-safe run protocol

Primary exports:

• ConversationRunProtocolCodec and ConversationRunProtocolValidationError;
• ConversationRunConsumerService;
• ConversationRunSequenceGapError and ConversationRunTerminalViolationError;
• reference, envelope, event, subscription, acceptance, retry, and codec types;
• ConversationRunReferenceSchema and ConversationRunReplayCursorSchema.

The codec accepts synchronous Standard Schema validators. Zod, Valibot, ArkType, and other compatible validators can define the host's public activity and result projection. This package intentionally excludes Heddle's Node runtime, model providers, server, CLI, and web control plane.

@heddleagent/run-client/http-sse: conventional REST/SSE client

Exports ConversationRunHttpSseClient, ConversationRunHttpSseClientError, and its option/input/error-payload types.

Use it when the host API follows the conventional start, event-subscription, and cancellation resource shape. The client owns URL/header composition, response schema validation, incremental event parsing, reader cleanup, and envelope/SSE identity agreement. The product supplies auth headers, public schemas, abort lifecycle, retry timing, and UI behavior.

@heddleagent/execution-host-client: separate Execution Host boundary

This package is for a product control plane that invokes a separately deployed compatible Execution Host. Its subpaths separate contracts, execution authority, conversation orchestration, MCP capability verification, transport, Node edges, and testing.

The conversation surface includes a reusable durable lifecycle service. Heddle decides what requested, accepted, terminal, cancelled, interrupted, and expired transitions mean, and commits them before the matching public event. The adopter injects an atomic store and still owns IDs, schema, migrations, retention, user-scoped queries, and presentation. This prevents each product from reimplementing the generic state machine without turning Heddle into the owner of product records.

The canonical spec/v1 OpenAPI, JSON Schema, lifecycle profile, and golden fixtures shipped in the public package are the language-neutral authority. A Python implementation in the permissioned canonical source proves a clean-room adopter can satisfy those artifacts; it is not a published or supported Python SDK and does not promise TypeScript-helper parity. The compatible Execution Host remains permissioned, and Heddle does not currently offer a public hosted service.

@heddleagent/postgres/execution-host/conversations: official lifecycle storage

This adapter implements the durable lifecycle port owned by @heddleagent/execution-host-client/conversation. It ships ordered SQL migrations and an atomic, scope-fenced store while leaving the PostgreSQL service, pool, authenticated scope, product records, history queries, retention, and migration execution with the application.

Copy every shipped SQL file, in exported order, into the application's checked-in migration sequence and apply it before constructing the store. The published package README explains why libraries do not mutate production schemas at runtime and shows the exact copy command.

Deprecated @roackb2/heddle-postgres: legacy heartbeat durability

This deprecated package supplies PostgreSQL authority for existing Heddle heartbeat deployments. It owns row locking, claims, stale-writer fencing, leases, recovery, checkpoints, run history, and atomic operator controls. It deliberately does not provide product tables or an Execution Host conversation-lifecycle adapter. New package-family work should not treat it as a general database layer.

@heddleagent/runtime/advanced: deep core customization

The advanced entrypoint re-exports the curated root and adds lower-level building blocks:

• LLM adapters, provider registry, OpenAI-compatible discovery, and model catalogs;
• individual coding, shell, browser-research, and external-context tools;
• trace recording, review parsing, observability, and system-prompt construction;
• memory catalogs, maintenance, notes, visibility, and knowledge tools;
• awareness providers and coding-workspace snapshots;
• the lower-level agent loop and checkpoints;
• heartbeat runners, storage, scheduler, and presenters;
• optional integrations such as semantic-drift observers;
• budgets, loggers, and runtime errors.

Use this surface only when the product needs to replace or assemble lower-level runtime mechanics. Importing /advanced does not opt into /runs, HTTP/SSE, or the run-client package.

Selection rules

1. Start with @heddleagent/runtime for a Node product host.
2. Add /runs only when work outlives one caller or needs addressable replay, cancellation, or approval resolution.
3. Add /runs/http-sse only for a Node HTTP/SSE adapter.
4. Install @heddleagent/run-client only in a remote consumer.
5. Add its /http-sse subpath only when the API actually uses the conventional REST/SSE contract.
6. Use @heddleagent/execution-host-client only when a product control plane calls a separate compatible Execution Host; non-TypeScript adopters implement the canonical v1 artifacts.
7. Use @heddleagent/postgres/execution-host/conversations only for the generic Execution Host lifecycle, not product conversation history.
8. Use @heddleagent/postgres/heartbeat for new heartbeat persistence; treat @roackb2/heddle-postgres only as a deprecated existing-consumer coordinate.
9. Reach for /advanced only when curated SDK exports cannot express the required runtime customization.
10. Never import internal build paths; if a required contract is not public, open an SDK API request instead of coupling the product to implementation files.

Versioning and verification

Keep packages on compatible release lines when they exchange public contracts. Pin the adopter v1 artifact version independently of implementation language, and run the published conformance fixtures against every store or clean-room adopter.

After changing versions, verify:

• a persisted session can be reopened and continued;
• public activity and result schemas still accept the intended fields and strip the rest;
• reconnect after a known sequence neither duplicates nor skips events;
• cancel and error settlement remain terminal;
• browser bundles do not include the Node runtime package;
• durable adopter transitions pass the shared store and terminal-projection fixtures;
• heartbeat PostgreSQL migrations precede code that requires them;
• the chosen subpath exists in the installed package's exports map.