Streaming and clients

Compatibility: Pactmark 0.1.x. The HTTP adapter exposes typed JSON commands and Server-Sent Events over Web-standard handlers.

Replay is the whole design

Figure 1. The client keeps the last sequence it saw. On reconnect, the store replays persisted events from that point and then tails new ones. Nothing is lost, and nothing has to be buffered forever.

Consuming the stream

const source = new EventSource("/api/agent/v1/runs/run_01J.../events", {
  withCredentials: true,
});

let lastSequence = 0;

source.onmessage = (message) => {
  const event = JSON.parse(message.data);
  lastSequence = event.sequence;
  render(event);
};

source.onerror = () => {
  source.close();
  // Reconnect from the last sequence you actually processed.
  reconnect(`/api/agent/v1/runs/run_01J.../events?afterSequence=${lastSequence}`);
};

From the runtime directly:

for await (const event of runtime.events(authority, runId, {
  afterSequence: lastSequence,
  signal: abortController.signal,
})) {
  lastSequence = event.sequence;
}

Persist lastSequence where your reconnect logic can reach it. A client that reconnects from zero will replay the entire run, which is correct but wasteful; a client that reconnects from a sequence it never processed has a gap it will not notice.

A disconnect is not an answer

This is the single most common client bug:

What happened	What it means	What it does not mean
The SSE connection dropped	Transport was lost	The run stopped
The HTTP request timed out	Your client gave up waiting	The work was cancelled
The page was closed	A viewer went away	Anything at all about the run

To learn the terminal state, ask:

const projection = await runtime.getRun(authority, runId);
// projection.status, projection.terminalErrorCode

To actually stop work, cancel it explicitly:

await runtime.cancel(authority, runId, { reasonCode: "user_abandoned" }, command);

Backpressure is bounded on purpose

Slow consumers are bounded. The runtime is never required to hold a complete stream in memory waiting for a client that has stopped reading — a design property that matters more as run volume grows. If a consumer falls too far behind, it reconnects with afterSequence and the store replays from persisted events. The durable log is the buffer.

Authenticate every request

Every command and every inspection request is authenticated. There is no “public run view”.

Commands

Start, resume, submit input, decide, reconcile, compensate, cancel — each with a validated CommandContext and idempotency key.

Inspection

Run state, events, artifacts, verification and evidence — each scoped by the authority you pass.

Map your idempotency keys into the CommandContext rather than inventing a parallel mechanism:

const command = createCommandContext({
  commandId: createCommandId(),
  operation: "run.start",
  payload: request,
});

Reusing a commandId with different content raises KAF_HTTP_IDEMPOTENCY_CONFLICT. Reusing it with the same content returns the same result — which is exactly what you want behind a flaky network.

Errors on the wire

HTTP errors use Problem Details with a stable KAF_* code. Branch on the code, never on the message:

{
  "type": "https://pactmark.dev/errors/policy-denied",
  "title": "KAF_POLICY_DENIED",
  "status": 403,
  "code": "KAF_POLICY_DENIED"
}

Response bodies use a different disclosure level from logs. A not-found response deliberately does not tell you whether another tenant’s resource exists — see Error reference.

Host-owned configuration

CORS, credential mode, CSRF, request and body size limits, time limits, admission and disclosure behaviour are all host configuration. The adapter does not pick defaults for you, because the right answer depends on whether your client is a first-party dashboard or a third-party integration.

HTTP reference

Every route, with its command and inspection semantics.

Vercel deployment

Wiring the route adapter, and why an open response is not a background worker.

Getting started

Core concepts

Guides

Deployment

Production

Security

Streaming and clients

Replay is the whole design

Consuming the stream

A disconnect is not an answer

Backpressure is bounded on purpose

Authenticate every request

Commands

Inspection

Errors on the wire

Host-owned configuration

HTTP reference

Vercel deployment

​Replay is the whole design

​Consuming the stream

​A disconnect is not an answer

​Backpressure is bounded on purpose

​Authenticate every request

Commands

Inspection

​Errors on the wire

​Host-owned configuration

HTTP reference

Vercel deployment

Replay is the whole design

Consuming the stream

A disconnect is not an answer

Backpressure is bounded on purpose

Authenticate every request

Errors on the wire

Host-owned configuration