@claxedo/agent-event-runtime

@claxedo/agent-event-runtime owns harness event normalization and projection. It turns harness-native event frames from external agent harnesses (Claude Agent SDK, Codex app-server, Cursor SDK, ACP) into canonical AgentRuntimeEvent values, then lets host packages project those events into UI, compatibility, replay, or diagnostic formats. The package is intentionally browser-safe: hosts still own process management, stdio, WebSockets, storage, and persistence.

Install

npm install @claxedo/agent-event-runtime

pnpm add @claxedo/agent-event-runtime

bun add @claxedo/agent-event-runtime

Quickstart

Create a runtime for one harness/thread pair using a harness adapter:

import { createAgentEventRuntime } from "@claxedo/agent-event-runtime"
import { claudeSdkAdapter } from "@claxedo/agent-event-runtime/harnesses/claude"

const runtime = createAgentEventRuntime({
  harness: "claude",
  threadId: "thread-1",
  adapter: claudeSdkAdapter(),
})

// Feed a harness-native frame; get back canonical AgentRuntimeEvent[]
const { events, snapshot } = runtime.ingest({
  source: "claude",
  payload: rawClaudeSdkMessage,
})

createAgentEventRuntime() owns one adapter state value for one harness/thread pair and stamps emitted events with harness, threadId, and raw. translateRawHarnessEvent() is the pure reducer variant for replay and tests. Adapter exceptions are converted into diagnostic events, so a bad frame never tears down the host stream.

Key capabilities

Contracts (/contracts) — RawHarnessEvent, AgentRuntimeEvent, agentRuntimeEvent factories, and harness-neutral ToolDisplay/ToolIntent metadata.
Harness adapters (/harnesses/{acp,claude,codex,cursor}) — translate harness-native payloads into canonical events.
Projections (/projections/opencode-compat, /projections/debug-trace) — render canonical events into OpenCode-compatible envelopes or compact trace rows.
Snapshots — RuntimeSnapshot and ProjectionSnapshot are explicit, serializable restore boundaries; injected clock/createId give deterministic replay.

Stability

Entry-point status per the README: Stable for the root and /contracts; Integration for the harness subpaths and /projections/debug-trace; Compatibility for /projections/opencode-compat.

Full API

See the README on GitHub for the complete layer breakdown, the full API table, and the adapter/projection authoring guides.