@agentprodready/runtime

Operational execution engine for AgentProdReady — run work, cancel it, checkpoint it, recover it, and stream results.

This is the core execution abstraction behind createAgent: Runtime owns timeout, retry, cancellation, checkpoints, recovery, and streaming — not a graph engine. See What is AgentProdReady?.

| | | |---|---| | Status | Production contracts published (1.1.x) | | Install | npm install @agentprodready/runtime | | Module | ESM | | License | MIT | | Repository | ameenmari/agentprodready |

Usually installed automatically with @agentprodready/agent-framework.

Installation

npm install @agentprodready/runtime

# Typical stack
npm install @agentprodready/agent-framework @agentprodready/composition @agentprodready/foundation

Features

| Feature | Description | |---|---| | Execution orchestration | Coordinate capability invocations end-to-end | | Cancellation | Cooperative cancel with terminal results | | Checkpoints | Durable ExecutionCheckpointPort for restart safety | | Recovery | recoverIncomplete with resume-if-safe defaults | | Streaming | executeStream → deltas + exactly one terminal event | | Tool-loop checkpoints | Optional multi-turn tool state (pre-tool / post-tool / awaiting-approval) | | Stream event log | Durable StreamEventLog for Simple replay (resumeFrom / replayStream) | | Provider failover ledger | Attempt tracking for multi-provider routing (host-wired) | | Ports, not vendors | No OpenAI / Postgres imports in this package |

What Runtime owns vs does not own

| Owns | Does not own | |---|---| | Start / complete / fail / cancel | Choosing which AI vendor (Capability Resolution) | | Checkpoints & recovery | Instantiating adapters (Composition) | | Stream delivery semantics | Authorization allow/deny (Security) | | Operational timeouts / retries (policy) | Agent identity / lifecycle (Agent Framework) |

Usage overview

import type { RuntimeOrchestrator } from '@agentprodready/runtime';

// Obtained from Composition in a real host — not constructed ad hoc in apps.
declare const runtime: RuntimeOrchestrator;

// Non-stream
const result = await runtime.execute(/* ExecutionRequest */);

// Stream
for await (const event of runtime.executeStream(/* ExecutionRequest */)) {
  if (event.type === 'delta') {
    // process chunk
  } else {
    // terminal: completed | failed | cancelled
    console.log(event.type, event.result);
  }
}

Agent Framework handoff:

// AgentFramework.invoke  → AgentRuntimePort.accept
// AgentFramework.invokeStream → AgentRuntimePort.acceptStream

Your host implements AgentRuntimePort by forwarding into RuntimeOrchestrator.

Checkpoints & recovery

store(checkpoint) → process crash → recoverIncomplete() → resume-if-safe

| Piece | Role | |---|---| | ExecutionCheckpointPort | store / load / listIncomplete | | InMemoryExecutionCheckpointPort | Tests / local | | Host Postgres adapter | Durable (via Persistence in platform-host) |

Guide: Runtime recovery

Streaming rules

• Chunks are not individually checkpointed
• Final capability result remains post-invoke
• Exactly one terminal stream event

Guide: Streaming

Tool-loop checkpoints

Additive ExecutionCheckpoint.toolLoop for multi-turn tool calling (pre-tool / post-tool / awaiting-approval).
Guide: Tools · HITL Approval

Stream event log

StreamEventLog appends normalized stream events during execution. Simple stream({ resumeFrom }) and replayStream(executionId) read from this log.

Guide: Stream Replay

Related packages

| Package | Role | |---|---| | @agentprodready/agent-framework | Agent identity + invoke handoff | | @agentprodready/capability-resolution | Implementation selection | | @agentprodready/composition | Wiring | | @agentprodready/ai-provider | AI contracts |

Documentation

• Blueprint 04
• Repository README
• Changelog

License

MIT © 2026 ameenmari