Package entrypoints

Install the runtime and remote client separately

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

npm install @roackb2/heddle

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

npm install @roackb2/heddle-remote

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

Entrypoint map

@roackb2/heddle: 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 hosted process code, import ConversationRunService from the explicit /hosted 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.

@roackb2/heddle/hosted: 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 '@roackb2/heddle/hosted'

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

@roackb2/heddle/hosted/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.

@roackb2/heddle-remote: 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.

@roackb2/heddle-remote/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.

@roackb2/heddle/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 /hosted, HTTP/SSE, or the remote package.

Selection rules

1. Start with @roackb2/heddle for a Node product host.
2. Add /hosted only when work outlives one caller or needs addressable replay, cancellation, or approval resolution.
3. Add /hosted/http-sse only for a Node HTTP/SSE adapter.
4. Install @roackb2/heddle-remote only in a remote consumer.
5. Add its /http-sse subpath only when the API actually uses the conventional REST/SSE contract.
6. Reach for /advanced only when curated SDK exports cannot express the required runtime customization.
7. 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 the Node runtime and remote package on compatible release lines when they exchange the canonical run envelope. Validate both directions at the public protocol boundary.

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;
• the chosen subpath exists in the installed package's exports map.