Architecture guide

Choose how Heddle fits into your product

Task duration does not decide the integration shape. An embedded Heddle runtime can work for seconds or hours; the real questions are where execution belongs and who should own its lifecycle.

Customization depth

Runtime and lifecycle ownership

Hosting depth

Embedded or separate host

Documentation status

Architecture guidance

Assumptions

Your product owns user identity, authorization, canonical data, policy, external effects, and UI.
You want to reuse Heddle without turning Heddle into the product's application framework.
You will choose isolation and lifecycle depth independently rather than using task duration as a proxy.

Heddle owns

The reusable model, tool, conversation, approval, artifact, and activity runtime.
Optional Agent Run Management for stable run identity, streaming, replay, cancellation, approvals, reconnection, and terminal settlement.
A public adopter contract for invoking a separately deployed compatible Execution Host.

Your product owns

The trusted mapping from a signed-in user to tenant, conversation, project, and capability scope.
The process and deployment topology when Heddle remains embedded, or the decision to introduce a separate host.
Canonical product transactions, history queries, retention, user-facing status, and the meaning of success.

Do not choose by task duration

An embedded Heddle runtime is ordinary application code. Your backend may await one turn inside an HTTP request, start it from a queue worker, or let it continue after the request that initiated it has returned. Nothing about @heddleagent/runtime requires the execution to end with the original request.

The optional layers solve different problems:

Agent Run Management standardizes how the product identifies, observes, controls, and settles one execution.
A Separate Execution Host changes where the runtime executes and establishes another deployment and trust boundary.

Those choices are related, but they are not the same axis.

Two independent decisions

1. Where does the runtime execute?

Placement	Meaning
Embedded	`@heddleagent/runtime` runs inside a TypeScript or Node.js backend, server, worker, or desktop process your product operates.
Separate host	A compatible Execution Host imports Heddle and runs it in an independently deployed environment. The adopter backend invokes it through the public network contract.

2. Who owns the lifecycle around one execution?

Lifecycle	Meaning
Direct execution	Your application calls the conversation engine and owns any surrounding run IDs, event delivery, cancellation routes, approval routing, and reconnect behavior it needs.
Agent Run Management	`@heddleagent/runtime/runs` supplies a stable run identity and reusable lifecycle for ordered events, replay, cancellation, approvals, reconnection, product result projection, and one terminal outcome.

A common progression is:

Text

Embedded Runtime
  call Heddle directly inside your backend
            |
            | add reusable execution lifecycle when needed
            v
Agent Run Management
  Heddle still runs in your server or worker
            |
            | introduce a separate deployment and trust boundary when needed
            v
Separate Execution Host
  the same runtime runs in an isolated environment

This is a progressive adoption path, not three mutually exclusive products. A separate host may itself expose managed run workflows; Agent Run Management is still the lifecycle concept, while the Execution Host is the placement and authority boundary.

Choose the smallest shape that solves the actual problem

Your need	Recommended starting point
Call a model and tools from a Node backend with product-owned output	Embedded Runtime
Run work in a queue or background worker, while the product already owns all control and delivery semantics	Embedded Runtime
Let multiple requests or clients find, stream, replay, cancel, approve, or reconnect to the same execution	Embedded Runtime + Agent Run Management
Keep the agent workstation away from the application process and product database credentials	Separate Execution Host
Invoke the Heddle runtime from a Python, Go, Java, or other non-Node backend	Separate Execution Host contract
Independently deploy, isolate, replace, or scale the execution environment	Separate Execution Host
Simply make a task run for a long time	Duration alone does not require either optional layer

Keep the product authoritative

None of these shapes moves product ownership into Heddle. The product still authenticates the user, derives tenant and project scope, decides which capabilities exist, owns canonical data and external effects, and presents the outcome. Heddle owns reusable execution mechanics; the product decides what the work means.

Public availability

The embedded runtime and Agent Run Management packages are public and open source. The separate-host adopter contract, language-neutral artifacts, and integration helpers are public. The current compatible Execution Host implementation and managed AgentCore deployment remain private research. Heddle does not currently operate a public managed Execution Host or cloud service.

Continue to Agent Run Management when clients need a stable execution lifecycle, or Separate Execution Host when execution needs a new placement, authority, or isolation boundary.