Skip to content

README.md

Latest commit

 

History

History
106 lines (97 loc) · 6.33 KB

README.md

File metadata and controls

106 lines (97 loc) · 6.33 KB
Raw

Programmatic Hosts

Heddle is an agent SDK: import it to add an agentic experience to your product without shelling out to the CLI. The main path is the conversation engine — it owns durable sessions, turn execution, compaction, traces, artifacts, default tools, host extensions, and approval callbacks.

These guides follow a progressive-disclosure ladder. Start at rung 1 and go deeper only when you need to. This mirrors how the public API is organized.

The public entry points span two independent axes: customization depth and hosting assumptions.

  • @heddleagent/runtime — the curated default surface (rungs 1–5): everything a product host needs to build an agentic experience.
  • @heddleagent/runtime/runs — process-local run identity, replay, cancellation, and approvals for a long-lived host process.
  • @heddleagent/runtime/runs/http-sse — opt-in Node HTTP/SSE framing, backpressure, replay-cursor, and subscriber-disconnect correctness.
  • @heddleagent/run-client — an independently installable, browser-safe package with runtime contracts plus transport-neutral cursor, duplicate, gap, terminal, and reconnect correctness.
  • @heddleagent/run-client/http-sse — opt-in browser-safe fetch/SSE parsing and transport validation for the conventional REST run resource.
  • @heddleagent/execution-host-client — an independently installable backend SDK for invoking a separate Execution Host: v1 contracts, ES256 authority, hosted-turn orchestration, durable lifecycle semantics, product-MCP verification, a provider-neutral client port, optional Node HTTP/key conveniences, and canonical OpenAPI/JSON Schema/golden artifacts for other languages. The former @roackb2/heddle-adopter@5.13.0 coordinate is deprecated and remains installable only for existing consumers.
  • @heddleagent/runtime/advanced — the deep core customization surface: the curated exports plus lower-level building blocks (LLM adapters, individual tools, trace, memory, models, awareness) and specialized runtimes (agent loop, heartbeat, integrations). It does not implicitly opt into remote hosting or a transport.

Before choosing an API, read the Heddle Component and Deployment Model, then Choose a Programmatic Integration Layer. They map common host stacks to the smallest useful Heddle boundary and make the responsibility split between Heddle and the host explicit for developers and coding agents. When you already know the host shape, use the starter recipes for the smallest copyable path and its product-owned TODOs.

  1. Start here — stand up a conversation agent.
    • Quickstart: a headless persisted conversation with structured activities/results in a few lines, plus an optional terminal loop.
    • Starter recipes: copy the transparent headless, hosted, or HTTP/SSE shape without adopting a generated framework.
  2. Add capabilities — give the agent your own tools, MCP servers, skills.
  3. Shape input/output — control how activity/text renders and where it goes.
    • Text host: default console-style output and custom text destinations.
    • Turn results: consume trace file, artifacts, and tool-call summaries after each turn.
  4. Advanced: lifecycle — own the engine, sessions, and approvals yourself.
    • Conversation engine: engine setup, state roots, and persisted sessions.
    • Approvals: own policy decisions in the host.
    • Remote conversation runs: consume reconnectable runs through any transport with runtime-validated public payloads.
    • Hosted agent stack: compose a transport-neutral run service, Express/SSE API, browser client, and optional React reference product while keeping each layer replaceable.
    • Execution Host adopter backend: keep Heddle in an isolated external host while the adopter backend owns product identity, capability policy, MCP tools, and result application.
  5. Advanced: storage — back Heddle with your own persistence.
    • Durability support matrix: choose between local, completed-conversation, and durable in-flight promises, and see which state surfaces must follow a replica.
    • Result artifacts: save large generated values as reusable artifacts.
    • Artifact and conversation storage are injectable: implement ArtifactRepository, plus the paired ChatSessionRepository and ChatArchiveRepository. Pass artifacts independently and group the two conversation ports under persistence.conversations (see Conversation engine → Bring your own artifact storage and Durable session storage for local JSON and PostgreSQL adapter guidance). The runnable local JSON recovery example covers one durable host, while the runnable PostgreSQL + Drizzle reference includes migrations, both repository implementations, public conformance, and fresh-service recovery. The engine exposes a lightweight conversation-readiness report; real infrastructure verification remains with the host. Traces and memory still persist under a local state root. They have different authority and lifecycle requirements and are not implied by session/archive repository injection.

Runnable versions of the first few rungs live in examples/sdk/.

Heartbeat is a specialized background runtime rather than a conversation rung. For a progressive embedded-worker path, see the heartbeat SDK examples: one cycle, long-lived lifecycle, domain handler, and event-driven durable wake-up.

For contributor-facing module boundaries, see Core Layering.