Add Agent Run Management without moving the runtime

Direct execution and managed execution can both run in the background

A direct embedded call can continue after an HTTP response if your host starts it in a worker or keeps the promise alive. The difference is not duration. The difference is whether your product wants to invent and maintain the surrounding lifecycle itself.

With a direct conversation-engine call:

product code -> submit turn -> model and tools -> result

Your product decides whether it needs a separate execution ID, event buffer, reconnect cursor, cancel route, approval route, retained handle, and terminal state machine.

With Agent Run Management:

product code -> start managed run -> runId
                                  |
                                  +-> ordered event stream
                                  +-> replay from sequence
                                  +-> cancel exact run
                                  +-> resolve exact approval
                                  +-> one terminal outcome

The Heddle runtime still executes in the same adopter-operated server or worker. @heddleagent/runtime/runs adds a reusable application lifecycle around it; it is not a separate cloud service or deployment target.

What the layer provides

• a stable runId for one exact execution;
• one active run per host-defined conversation address;
• monotonically ordered activity and terminal events;
• bounded replay for a client that disconnects and returns;
• cancellation bound to the exact run rather than whichever execution happens to be current later;
• approval resolution bound to the exact run and approval request;
• awaited product projection before a successful terminal is published;
• one explicit result, cancelled, or error terminal; and
• browser-safe client validation and reconnect helpers through optional packages.

Lower-level architecture documents may call a run with a stable identity addressable. The public product meaning is simpler: the product can reliably refer to the same execution again.

What it deliberately does not provide

Agent Run Management is process-local. Its retained handles and replay buffer do not survive a process crash and do not route across multiple instances. It does not create a queue, scheduler, distributed broker, durable active-work database, isolated workstation, or managed cloud service.

A product that needs restart recovery or multi-worker ownership must add an appropriate durable work system. A product that needs a separate process or trust boundary should evaluate the Separate Execution Host.

When to add it

Add Agent Run Management when at least one of these is part of the product contract:

• the initial request returns before the execution settles;
• another request or client must find the same active execution;
• users may disconnect and resume ordered progress;
• cancellation or approval arrives through a later interaction;
• the product must distinguish accepted, active, cancelled, failed, and successful execution; or
• product state must be committed before success is visible.

Skip it when one application call can simply await the turn result and no other actor needs to observe or control that execution. You can add the layer later without moving the runtime to another deployment.

Continue to the API tutorial

The conceptual layer is implemented by ConversationRunService from @heddleagent/runtime/runs. Continue to the ConversationRunService API guide for construction, start, subscribe, replay, cancel, approval, projection, and limitation details. Add Node HTTP/SSE only when that transport matches your server, and Remote client only when events cross an untrusted client boundary.