Stream events

runtime.executeMessage() is an async generator. Every yielded value is a StreamEvent — a discriminated union keyed on type. Browser UIs render from these; server consumers forward them over SSE. See SessionRuntime for the generator's signature and Event log for how these shapes persist as durable rows.

import type { StreamEvent } from "@pleach/core";

for await (const event of runtime.executeMessage(sessionId, prompt)) {
  // event is a StreamEvent — switch on event.type
}

Every event also carries an optional namespace: string[] field — empty for the root orchestrator, populated for events emitted from inside a subagent. Use it to route subagent output into its own UI surface.

Session lifecycle

Message stream

The main user-facing surface — what gets rendered into the chat viewport.

Render message.delta and thinking.delta as they arrive; treat message.complete as the authoritative final text.

Reasoning traces (reasoning.delta)

Reasoning models (DeepSeek-R1, etc.) stream a chain-of-thought before the answer. Pleach surfaces that as reasoning.delta events — a provider-agnostic side-channel that is never concatenated into the answer text. Two reasons it exists:

1. Liveness. A long reasoning phase (tens of seconds with no answer token) would otherwise look like a stalled stream. reasoning.delta keeps the no-content watchdog from false-firing while the model thinks.
2. UX. Render a "Thinking…" indicator, or accumulate the deltas into a collapsible trace next to the final answer.

This is distinct from the reasoning call class (a type-level routing invariant on the seam — see Seams). reasoning.delta is runtime trace content; the reasoning call class is which seam a node consumes. The @pleach/react useSessionMessageStream hook exposes isReasoning + reasoningText so you don't have to accumulate the deltas yourself — see React.

Tool calls

Pair tool.started with tool.completed / tool.failed on toolCall.id to render per-tool spinners and result cards.

A worked sequence for a single search_corpus call in a knowledge-base assistant:

1. tool.started — { toolCall: { id: "tc-018f-7a-1", name: "search_corpus", args: { query: "indexing strategies" } } }
2. tool.delta × N — streaming arg assembly while the model emits JSON; concatenate into a per-toolCallId buffer
3. tool.completed — { toolCall: { id: "tc-018f-7a-1", … }, result: [{ id: "doc-abc123", score: 0.91 }, …] }
4. message.entities — { toolCallId: "tc-018f-7a-1", toolName: "search_corpus", entities: [{ kind: "document", id: "doc-abc123" }] }
5. message.citations — citations attached to the synthesized answer's body section once the LLM references the hits

Steps 1 and 3 are the spinner bracket; step 4 is what hydrates a "sources" sidebar; step 5 is what underlines the cited sentence in the rendered transcript.

Async jobs

For tools that dispatch work to a queue and return later.

progress is 0–1. Use phaseProgress for multi-phase jobs (e.g. download then process then upload).

Interrupts (human-in-the-loop)

The interrupt.requested event is when you'd surface an approval modal in your UI; the runtime pauses until decision lands.

Execution lifecycle

Agnostic signals an external @pleach/core consumer subscribes to via useChat({ onEvent }) (or any StreamEvent driver) to observe how a turn ran — stage transitions, recovery, retries, stream timing — without inheriting the host's console-grep idiom. They fire from graph-internal sites alongside the runtime's own diagnostics; the values reuse the canonical core unions (StageId, RecoveryDispatchArm) and carry no domain concepts.

Use stage.transition to reconstruct the per-turn lattice walk (anchor-plan → tool-loop → synthesize → post-turn); a stage.lattice_violation is your signal that execution diverged from the advertised lattice (see Architecture for the nine-pattern lattice the same ALLOWED_EDGE_PATTERNS constant defines). stream.first_chunk / turn.completed give you TTFB and total latency without a separate metrics pipeline.

import { observeSink } from "@pleach/observe";

runtime.events.on("model.called", observeSink({ destinations: [store] }));

Artifacts

Checkpoints and sync

Subagents

When enableSubagentConcurrency: true and the orchestrator spawns parallel workers.

Subagent-emitted events carry namespace so a UI can route them into a separate panel.

Sandbox

For tools that allocate a sandboxed execution environment. The event shapes below are stable contracts in @pleach/core. @pleach/sandbox@0.1.0 ships the SandboxProvider canonical adapter and @pleach/coding-agent@0.1.0 consumes these events — its start() / stop() / executeStep() bodies all land at the 0.1.0 cut; executeStep() throws PACK_270_D3_EXECUTE_STEP_NOT_STARTED_MESSAGE only when called before start(). Hosts can implement their own sandbox adapter against the same event surface.

Stream control

For content.correction, the renderer should treat correctedContent as the authoritative final text — replace the last assistant message wholesale. A common case: the model streamed a sentence claiming it had called fetch_document when no such tool call landed in the turn; the fabrication guard fires content.correction with reason: "phantom_tool_reference" and a correctedContent payload that drops the false claim. The UI's message buffer for that messageId is replaced wholesale, not appended to.

Provider cascade and LLM turn

Emitted by the fallback executor and the graph LLM node — surface per-model progress, model transitions, and token usage.

modelSwitchReason discriminates "provider_fallback", "zero_tool_recovery", "forceSynthesis_escalation", "forceSynthesis_garble_cascade". Use llm.turn.depth to attribute spend across subagent depth levels — depth: 0 is the root turn, depth: 1 is a direct subagent, depth: 2 is a grandchild, and the hard ceiling is SUBAGENT_LIMITS.maxDepth = 3 (see Subagents). A GROUP BY depth on the per-call ledger gives you "how much did fan-out cost relative to the root turn."

Domain events

Plugins emit domain.event to surface arbitrary structured events to the consumer without inventing a new variant per plugin. The domain namespaces the plugin (e.g. compliance.audit, gateway.cost), kind is the event kind, payload carries the data.

Step lifecycle

Errors

The code field is the structured error code (1xxx–7xxx) — see Error codes for the catalog.

Forwarding over SSE

The stream maps directly onto Server-Sent Events. The reference Next.js route in the package looks roughly like:

export async function POST(req: Request) {
  const { sessionId, content } = await req.json();
  const stream = new ReadableStream({
    async start(controller) {
      for await (const event of runtime.executeMessage(sessionId, content)) {
        controller.enqueue(`data: ${JSON.stringify(event)}\n\n`);
      }
      controller.close();
    },
  });
  return new Response(stream, {
    headers: { "Content-Type": "text/event-stream" },
  });
}

Each event becomes one SSE data: line. Clients re-hydrate the union by parsing JSON.parse(line) and switching on type.

Mode-filtered subscription

SessionRuntime also exposes a non-iterator subscription that filters by StreamMode. Use this for cross-cutting subscribers that don't own the turn loop.

const unsubscribe = runtime.subscribeToStream("messages", (event) => {
  // only message.delta / message.complete / thinking.* land here
});

"values", "updates", "messages", "custom", "debug", and "all" are the legal modes — see SessionRuntime → Stream subscription for the per-mode event sets.

content.delta

content.delta is the canonical streaming-chunk event type. The substrate emits one per token-or-chunk during model output for a turn.

It pairs with the chunk-loop that folds deltas into a terminal message at end-of-turn. See Event log § content.delta streaming chunks for the persisted row shape, and Event log projections for the fold that reconstructs the final message.

Consumers subscribing to content.delta should treat each chunk as forward-only. Don't try to "undo" a delta — the terminal message is the canonical reconstructed state.

tool.execution span emit

The substrate emits a tool.execution OTel span per tool dispatch. The span brackets the same lifecycle moment as the tool.completed stream event above.

The two are paired surfaces for the same dispatch: the span feeds traces and observability backends; the stream event feeds in-process subscribers rendering the turn.

See OTel observability for the full span surface and attribute catalog.

Where to go next