@vzn/vx 0.0.0 → 0.0.12

package/src/graph/task-graph.ts

@@ -0,0 +1,325 @@
+import type { TaskConfig } from '../config.js'
+import { UserError } from '../util/index.js'
+import type { PackageGraph, ProjectEntry } from '../workspace/index.js'
+import { DependencySpecError, parseDependencySpec, type DependencySpec } from './dependency-spec.js'
+
+// Re-exported so existing importers keep working while the type's home
+// moves to workspace (it's the joint product of discovery + loading).
+export type { ProjectEntry } from '../workspace/index.js'
+
+export interface TaskNode {
+  /** Stable id: `${projectName}#${taskName}`. */
+  id: string
+  projectName: string
+  projectDir: string
+  taskName: string
+  config: TaskConfig
+  /** Ids of tasks that must complete before this one runs. */
+  deps: string[]
+  /**
+   * True for the tasks the user actually asked for (via cwd, `-r`, `-F`,
+   * or `pkg#task`). False for dependencies pulled in by `dependsOn`
+   * expansion. Used by the orchestrator to scope `forwardArgs` so trailing
+   * CLI args don't leak into upstream tasks the user didn't address.
+   */
+  requested: boolean
+  /**
+   * Display-only: a same-project, non-group, direct `dependsOn` task of
+   * a REQUESTED GROUP. A group produces no output of its own, so in
+   * focused flow we surface the work it stands for one level down (no
+   * recursion, no `^`/cross-project deps — see `markSurfacedDeps`). The
+   * focused logger shows these like requested tasks; it does NOT make
+   * them `requested`, so `forwardArgs` scoping is unaffected.
+   */
+  surfaced?: boolean
+}
+
+export function taskId(project: string, task: string): string {
+  return `${project}#${task}`
+}
+
+/**
+ * A task is a "group" if it has no `exec` — it exists only to chain
+ * `dependsOn` (an umbrella for `vx run ci`). Group tasks:
+ *   - never spawn a process,
+ *   - never read/write the cache (it's a config error to declare one),
+ *   - never appear in the run summary or `runs` analytics table,
+ *   - render no framed block in the live output.
+ * Six call sites used to repeat `node.config.exec === undefined`;
+ * centralising the predicate prevents that check from drifting.
+ */
+export function isGroupTask(node: TaskNode): boolean {
+  return node.config.exec === undefined
+}
+
+/**
+ * Mark, for focused-flow display, the real tasks a requested GROUP
+ * stands for. A group has no output of its own, so `vx run build`
+ * (where `build` is a group) would otherwise print nothing.
+ *
+ * Walk `dependsOn` from the requested group, DESCENDING THROUGH nested
+ * same-project groups (e.g. `build` → `build.bun` → `build.bun.*`), and
+ * surface the first non-group task on each path. Two hard limits:
+ *   - never leave the requested project — `^`/cross-project deps are
+ *     not entered (the user asked to run THIS project's group),
+ *   - never descend past a real task — its own `dependsOn` is its
+ *     implementation detail, not work the group "is".
+ *
+ * Display-only: it never flips `requested`, so `forwardArgs` scoping
+ * stays put. Returns the count of newly surfaced nodes.
+ */
+export function markSurfacedDeps(nodes: Map<string, TaskNode>): number {
+  let surfaced = 0
+  for (const node of nodes.values()) {
+    if (!node.requested || !isGroupTask(node)) continue
+    const project = node.projectName
+    const stack = [...node.deps]
+    const visited = new Set<string>()
+    while (stack.length > 0) {
+      const depId = stack.pop()!
+      if (visited.has(depId)) continue
+      visited.add(depId)
+      const dep = nodes.get(depId)
+      // Stay inside the requested project; `^`/cross-project deps are
+      // neither surfaced nor traversed.
+      if (!dep || dep.projectName !== project) continue
+      if (isGroupTask(dep)) {
+        // A nested group: keep descending, don't surface the group.
+        for (const next of dep.deps) stack.push(next)
+        continue
+      }
+      if (dep.surfaced !== true) {
+        dep.surfaced = true
+        surfaced++
+      }
+    }
+  }
+  return surfaced
+}
+
+/**
+ * Expand the user-requested task list into concrete `{project, task}`
+ * pairs the graph builder consumes.
+ *
+ *   - Bare task names (`'build'`) → one entry per project in
+ *     `candidates` that declares the task. Missing in a given project
+ *     is silent (sparse tasks are normal across a workspace).
+ *   - Anchored entries (`'pkg#task'`) → one entry exactly, ignoring
+ *     `candidates`. Silently dropped if pkg/task doesn't exist (the
+ *     CLI's pre-validation catches malformed strings).
+ *
+ * Duplicates are deduped (a user might pass `vx run build pkg#build`).
+ */
+export function expandRequested(
+  tasks: readonly string[],
+  candidates: readonly string[],
+  projects: Map<string, ProjectEntry>,
+): Array<{ project: string; task: string }> {
+  const seen = new Set<string>()
+  const out: Array<{ project: string; task: string }> = []
+  const push = (project: string, task: string): void => {
+    const key = `${project}#${task}`
+    if (seen.has(key)) return
+    seen.add(key)
+    out.push({ project, task })
+  }
+  for (const spec of tasks) {
+    const idx = spec.indexOf('#')
+    if (idx >= 0) {
+      const project = spec.slice(0, idx)
+      const task = spec.slice(idx + 1)
+      if (projects.get(project)?.config.tasks?.[task]) push(project, task)
+      continue
+    }
+    for (const name of candidates) {
+      if (projects.get(name)?.config.tasks?.[spec]) push(name, spec)
+    }
+  }
+  return out
+}
+
+export interface BuildGraphOptions {
+  projects: Map<string, ProjectEntry>
+  packageGraph: PackageGraph
+  /** Initial set: `{ project, task }` pairs the user asked to run. */
+  requested: Array<{ project: string; task: string }>
+  /**
+   * Filter `dependsOn` expansion.
+   *   - `undefined` → every dependsOn entry is followed (default).
+   *   - `'all'`     → no expansion; only the requested nodes are added.
+   *   - `string[]`  → expand normally, but drop edges whose target
+   *                   task name is in the list. `dependsOn.self` and
+   *                   `dependsOn.dependencies` are both filtered.
+   */
+  excludeDependencies?: 'all' | readonly string[]
+}
+
+export function buildTaskGraph(options: BuildGraphOptions): Map<string, TaskNode> {
+  const { projects, packageGraph, requested, excludeDependencies } = options
+  const skipAll = excludeDependencies === 'all'
+  const skipNames =
+    Array.isArray(excludeDependencies) && excludeDependencies.length > 0
+      ? new Set(excludeDependencies)
+      : null
+  const nodes = new Map<string, TaskNode>()
+
+  function addNode(projectName: string, taskName: string, requested: boolean): TaskNode | null {
+    const id = taskId(projectName, taskName)
+    const existing = nodes.get(id)
+    if (existing) {
+      // Promote an already-added node to requested if any caller asked
+      // for it directly. Once requested, never demoted.
+      if (requested) existing.requested = true
+      return existing
+    }
+
+    const project = projects.get(projectName)
+    if (!project) return null
+    const taskConfig = project.config.tasks?.[taskName]
+    if (!taskConfig) return null
+
+    const node: TaskNode = {
+      id,
+      projectName,
+      projectDir: project.dir,
+      taskName,
+      config: taskConfig,
+      deps: [],
+      requested,
+    }
+    nodes.set(id, node)
+
+    if (skipAll) return node
+
+    const rawSpecs = taskConfig.dependsOn ?? []
+    for (const raw of rawSpecs) {
+      let spec: DependencySpec
+      try {
+        spec = parseDependencySpec(raw)
+      } catch (err) {
+        if (err instanceof DependencySpecError) {
+          throw new UserError(`Task ${id}: ${err.message}`)
+        }
+        throw err
+      }
+
+      // dependsOn is about which tasks to ADD to the graph, not which
+      // to filter. Wildcards and negation aren't meaningful here —
+      // they're cache.inputs.tasks operations.
+      if (spec.kind === 'wildcardSelf' || spec.kind === 'wildcardDeps') {
+        throw new UserError(`Task ${id}: dependsOn does not accept wildcards (got "${raw}")`)
+      }
+      if (spec.negated) {
+        throw new UserError(`Task ${id}: dependsOn does not accept negation (got "${raw}")`)
+      }
+      // CLI `--excludeDependencies=name1,name2` drops edges whose target
+      // task name matches, regardless of bucket (self / deps / cross).
+      if (skipNames?.has(spec.task)) continue
+
+      if (spec.kind === 'self') {
+        // Missing target is a hard error — the user typed a name that
+        // doesn't resolve in this project.
+        const child = addNode(projectName, spec.task, false)
+        if (!child) {
+          throw new UserError(
+            `Task ${id} depends on ${taskId(projectName, spec.task)} but no such task is declared`,
+          )
+        }
+        node.deps.push(child.id)
+      } else if (spec.kind === 'deps') {
+        // Nearest-holder frontier (Turbo/Nx direct-deps parity +
+        // sparse bridging): walk the package dep graph from this
+        // project's direct deps; each path stops at the FIRST package
+        // declaring the task — a holder's own dependsOn is responsible
+        // for anything deeper. Packages without the task are passed
+        // through so a sparse dep doesn't break ordering to deeper
+        // holders. The visited set both dedupes shared subtrees and
+        // terminates on package-graph cycles (legal in PMs).
+        const visited = new Set<string>()
+        const frontier = [...packageGraph.directDeps(projectName)]
+        while (frontier.length > 0) {
+          const target = frontier.pop()!
+          if (visited.has(target)) continue
+          visited.add(target)
+          const child = addNode(target, spec.task, false)
+          if (child) node.deps.push(child.id)
+          else frontier.push(...packageGraph.directDeps(target))
+        }
+      } else {
+        // Cross-project edge: pkg#task. Missing target is a hard error
+        // because the user named the package + task explicitly.
+        const child = addNode(spec.project, spec.task, false)
+        if (!child) {
+          throw new UserError(
+            `Task ${id} depends on ${taskId(spec.project, spec.task)} but no such project or task is declared`,
+          )
+        }
+        node.deps.push(child.id)
+      }
+    }
+
+    // Stable ordering for deterministic scheduling and cache keys.
+    node.deps.sort()
+    return node
+  }
+
+  for (const { project, task } of requested) {
+    addNode(project, task, true)
+  }
+
+  detectCycle(nodes)
+  return nodes
+}
+
+function detectCycle(nodes: Map<string, TaskNode>): void {
+  // Iterative DFS over dense-indexed colors. Recursion + `Map<string,
+  // number>` worked, but deep workspaces (long chains of `dependsOn`)
+  // can blow V8's frame budget, and per-node Map lookups dominate the
+  // pass. A Uint8Array indexed by node-position is allocation-free
+  // and ~2× faster on cycle detection itself.
+  // 0 = WHITE (unvisited) — the typed array's zero-init default.
+  const GRAY = 1
+  const BLACK = 2
+  const idsArr = [...nodes.keys()]
+  const idIdx = new Map<string, number>()
+  for (let i = 0; i < idsArr.length; i++) idIdx.set(idsArr[i]!, i)
+  const color = new Uint8Array(idsArr.length)
+
+  // Each stack frame is `[idIndex, nextChildIdx]`. We mutate the
+  // child index in place as children are visited so we know which one
+  // to resume on when the leaf returns control here.
+  const stack: number[] = []
+  for (let start = 0; start < idsArr.length; start++) {
+    if (color[start] === BLACK) continue
+    stack.push(start, 0)
+    color[start] = GRAY
+    while (stack.length > 0) {
+      const childIdx = stack[stack.length - 1]!
+      const idx = stack[stack.length - 2]!
+      const node = nodes.get(idsArr[idx]!)
+      const deps = node ? node.deps : []
+      if (childIdx < deps.length) {
+        stack[stack.length - 1] = childIdx + 1
+        const depIdx = idIdx.get(deps[childIdx]!)
+        if (depIdx === undefined) continue
+        const c = color[depIdx]!
+        if (c === BLACK) continue
+        if (c === GRAY) {
+          // Reconstruct the cycle by walking the open stack until we
+          // hit the id that triggered the GRAY-on-GRAY hit.
+          const path: string[] = []
+          for (let i = 0; i < stack.length; i += 2) path.push(idsArr[stack[i]!]!)
+          const startInPath = path.indexOf(idsArr[depIdx]!)
+          const cycle = [...path.slice(startInPath), idsArr[depIdx]!].join(' -> ')
+          throw new UserError(`Cycle detected in task graph: ${cycle}`)
+        }
+        color[depIdx] = GRAY
+        stack.push(depIdx, 0)
+      } else {
+        color[idx] = BLACK
+        stack.pop()
+        stack.pop()
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,197 @@
+// Public API for @vzn/vx.
+//
+// This is the stable cross-package contract — any plugin or integration
+// package imports everything it needs from here via the bare
+// `'@vzn/vx'` specifier (never a deep `src/...` path). The surface is pinned
+// by tests/package-boundaries.test.ts; a widening updates that snapshot
+// deliberately. See docs/design/core-cloud-split-2026-06.md §3.5.
+
+export { VERSION } from './version.js'
+
+// Clean error type — user-input failures print a message without a stack.
+export { UserError } from './util/index.js'
+
+// Schema types and helpers (used by user vx.config files and presets).
+export type {
+  WorkspaceConfig,
+  ProjectConfig,
+  TaskConfig,
+  ExecConfig,
+  ExecEnv,
+  CacheConfig,
+  CacheInputs,
+  CacheOutputs,
+  SandboxConfig,
+  SandboxNetworkConfig,
+} from './config.js'
+export { defineProject, defineWorkspace } from './config.js'
+
+// Programmatic engine API (run / plan / prepare) + the graph primitives a
+// distribution submitter/agent reasons over + the cache-key hashing seam.
+// `deriveStableKeys` is THE shared stable-key derivation (remote-prefetch,
+// the local short-circuit, and the distributed submitter must never drift
+// on the stability gate); `captureGitContext`/`captureWorkspaceIdentity`
+// give agents + the submitter identity before/without a telemetry run.
+export { run, planRun, prepareRun } from './orchestrator/index.js'
+export type { PreparedRun } from './orchestrator/index.js'
+export { computeTaskHash, createHashCache, deriveStableKeys } from './orchestrator/index.js'
+export type { DeriveStableKeysArgs, HashCache, StableKey } from './orchestrator/index.js'
+export {
+  captureGitContext,
+  captureWorkspaceIdentity,
+  resolveCacheScope,
+} from './orchestrator/index.js'
+export type { GitContext, WorkspaceIdentity } from './orchestrator/index.js'
+export { FULL_CACHE_POLICY, parseCachePolicy } from './orchestrator/index.js'
+export type {
+  CachePolicy,
+  Logger,
+  OutputView,
+  RunOptions,
+  RunSummary,
+} from './orchestrator/index.js'
+export { defaultLogger, resolveOutputView } from './orchestrator/index.js'
+export { buildTaskGraph, expandRequested, isGroupTask, markSurfacedDeps } from './graph/index.js'
+export type { TaskNode, TaskOutcome, TaskStatus, VerifyVerdict } from './graph/index.js'
+
+// Cache classes + the layer interface (the `cache` capability's currency)
+// and input-output resolution. The blob-CAS/digest substrate
+// (cas-backend.ts / digest.ts) stays module-internal until it has a
+// consumer — no speculative public API. `cleanOutputs` is public for the
+// distributed submitter's targeted output materialization (wipe declared
+// outputs, then `restoreOutputs` the artifact — never a naive re-run).
+export {
+  Cache,
+  LayeredCache,
+  RemoteCache,
+  GitFilesCache,
+  cleanOutputs,
+  resolveInputs,
+  resolveOutputs,
+} from './cache/index.js'
+export type { CacheLayer, RunRecord, InvocationRecord } from './cache/index.js'
+
+// Workspace discovery — an out-of-process service/CLI needs these.
+export { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from './workspace/index.js'
+
+// Plugin API — the run-level extension points. Behavior capabilities
+// (backend / cache) change WHAT/HOW work runs; the observe-only `telemetry`
+// capability is the canonical data-export path and cannot change behavior.
+// A plugin is declared in vx.workspace.ts via defineWorkspace({ plugins }).
+// See docs/design/observability-architecture-2026-06.md.
+export type {
+  VxPlugin,
+  EventSink,
+  BackendContext,
+  CacheContext,
+  EventSinkContext,
+  PluginSetupContext,
+} from './orchestrator/index.js'
+
+// Telemetry — THE canonical, versioned data-export contract every exporter
+// (an OTel exporter, an HTTP sink, or any third-party consumer) reads. A sink implements TelemetrySink and is
+// returned from VxPlugin.telemetry(); it receives immutable records and holds
+// no run handle (observe-only by construction).
+export { TELEMETRY_SCHEMA_VERSION, deriveCacheSource } from './orchestrator/index.js'
+export type {
+  CacheSource,
+  RunContextRecord,
+  RunSummaryRecord,
+  TaskTelemetry,
+  TelemetryContext,
+  TelemetryRecord,
+  TelemetrySink,
+} from './orchestrator/index.js'
+
+// The submitter wire contract + backend interface (the `backend`
+// capability's currency) and the serializable event projection.
+export {
+  optionsToRequest,
+  requestToOptions,
+  projectNode,
+  projectOutcome,
+  createWireRenderer,
+} from './orchestrator/index.js'
+export type {
+  RunBackend,
+  RunRequest,
+  RunResult,
+  ClientMessage,
+  ServerMessage,
+} from './orchestrator/index.js'
+
+// Event bus + wire form — adapters (otel-bridge, custom subscribers) ride this.
+export {
+  createEventBus,
+  wireForwarder,
+  toWireEvent,
+  createVxSurface,
+} from './orchestrator/index.js'
+export type {
+  EventBus,
+  RunEvent,
+  RunEventSubscriber,
+  WireEvent,
+  TaskView,
+  OutcomeView,
+} from './orchestrator/index.js'
+
+// The JSON-RPC 2.0 wire envelope — an out-of-process serve/agent speaks this framing.
+export {
+  clientMessageToEnvelope,
+  decodeEnvelope,
+  encodeForNDJSON,
+  encodeForSSE,
+  encodeForWS,
+  ENVELOPE_ERRORS,
+  envelopeToClientMessage,
+  envelopeToServerMessage,
+  isEnvelope,
+  isNotification,
+  isRequest,
+  makeError,
+  makeNotification,
+  makeRequest,
+  makeResponse,
+  serverMessageToEnvelope,
+  WIRE_CHANNELS,
+  WIRE_PROTOCOL_VERSION,
+} from './orchestrator/index.js'
+export type {
+  Envelope,
+  ErrorResponse,
+  Notification,
+  WireRequest,
+  WireResponse,
+  WireChannel,
+} from './orchestrator/index.js'
+
+// Metrics / analytics query layer over cache.db — a service plugin's HTTP
+// surface reads from these (the queries stay in core; a serve exposes them over HTTP).
+export {
+  cacheKeyDiff,
+  compareRuns,
+  explainCacheKeyQuery,
+  getBottlenecks,
+  getCacheBreakdown,
+  getCacheSavings,
+  getCacheStatsSql,
+  getFlakiestTasks,
+  getHistory,
+  getHitRateSplit,
+  getInvocation,
+  getParallelismHistory,
+  getPrunableEntries,
+  getRecentFailures,
+  getRun,
+  getRunHeatmap,
+  getRunTrends,
+  getStorageGrowth,
+  getTaskDetail,
+  getTopTimeBurners,
+  listCacheEntries,
+  listInvocations,
+  listProjects,
+  listRuns,
+  whyDidThisRerunQuery,
+} from './orchestrator/index.js'

package/src/orchestrator/colors.ts

@@ -0,0 +1,63 @@
+// Tiny color helper — gates Bun.color through a `ColorSupport` token
+// so the formatters stay pure. The token is computed once at logger
+// construction; tests pass `{ enabled: false }` so assertions match
+// plain strings.
+//
+// Bun.color('red', 'ansi') is broken in current Bun versions (emits
+// the color number as a raw byte instead of decimal text), so we use
+// 'ansi-16m' which emits 24-bit truecolor sequences. Every modern
+// terminal supports them, and the `tput colors`-style downgrade isn't
+// worth the complexity for our handful of UI accents.
+
+const RESET = '\x1b[0m'
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+
+export interface ColorSupport {
+  enabled: boolean
+}
+
+export interface PaintOptions {
+  bold?: boolean
+  dim?: boolean
+}
+
+/**
+ * Standard env precedence:
+ *   NO_COLOR=anything   → off (overrides FORCE_COLOR)
+ *   FORCE_COLOR=anything → on
+ *   else: on iff stdout is a TTY.
+ */
+export function detectColors(stream: NodeJS.WriteStream = process.stdout): ColorSupport {
+  if (process.env['NO_COLOR']) return { enabled: false }
+  if (process.env['FORCE_COLOR']) return { enabled: true }
+  return { enabled: stream.isTTY === true }
+}
+
+// Bun.color() is pure for a given (hex, mode) pair but does FFI work
+// on each call. The framed-output renderer paints the same handful of
+// accent colors thousands of times per run; memoizing here turns those
+// into hash-map hits.
+const ansiCache = new Map<string, string>()
+function ansiFor(color: string): string {
+  const cached = ansiCache.get(color)
+  if (cached !== undefined) return cached
+  const v = Bun.color(color, 'ansi-16m') ?? ''
+  ansiCache.set(color, v)
+  return v
+}
+
+export function paint(
+  color: string,
+  text: string,
+  colors: ColorSupport,
+  opts: PaintOptions = {},
+): string {
+  if (!colors.enabled) return text
+  let prefix = ''
+  if (opts.bold) prefix += BOLD
+  if (opts.dim) prefix += DIM
+  if (color) prefix += ansiFor(color)
+  if (prefix.length === 0) return text
+  return `${prefix}${text}${RESET}`
+}

package/src/orchestrator/devframe-surface.ts

@@ -0,0 +1,74 @@
+// The devframe surface for a vx run: one definition that exposes the run
+// as a live streaming channel (`vx:events`, the raw WireEvent feed) plus a
+// patch-synced shared state (`vx:run`, the reduced RunState aggregate).
+// A host adapter (dev server / MCP — see cli wiring) mounts this same
+// definition; this module owns only the translation from our in-process
+// event bus into devframe's streaming + shared-state primitives.
+//
+// devframe is touched ONLY through type-only imports here, so core `vx`
+// never gains a runtime dependency on it — the host that actually boots a
+// devframe server imports the runtime adapter dynamically and is the
+// optional, opt-in path. See docs/design/event-stream-2026-06.md.
+
+import type { DevframeDefinition, DevframeNodeContext, RpcStreamingChannel } from 'devframe'
+import { VERSION } from '../version.js'
+import { toWireEvent, type EventBus, type WireEvent } from './events.js'
+import { initRunState, reduce, type RunState } from './run-state.js'
+
+// Type the `vx:run` shared-state key so `ctx.rpc.sharedState.get` is
+// checked against our aggregate shape.
+declare module 'devframe' {
+  interface DevframeRpcSharedStates {
+    'vx:run': RunState
+  }
+}
+
+export interface VxSurfaceOptions {
+  /** Stream id for the run's event feed. One run → one stream. */
+  streamId?: string
+}
+
+/**
+ * Build a devframe definition that mirrors a single run's bus onto
+ * devframe's wire. `setup` runs at host boot (before the run emits), so
+ * it subscribes to the bus, forwards every event onto the `vx:events`
+ * stream, and folds it into the `vx:run` shared state. The host syncs
+ * both to any connected client (web SPA, MCP resource).
+ */
+export function createVxSurface(bus: EventBus, options: VxSurfaceOptions = {}): DevframeDefinition {
+  const streamId = options.streamId ?? 'run'
+  return {
+    id: 'vx',
+    name: 'vx',
+    version: VERSION,
+    async setup(ctx: DevframeNodeContext) {
+      const channel: RpcStreamingChannel<WireEvent> = ctx.rpc.streaming.create('vx:events')
+      const stream = channel.start({ id: streamId })
+      const state = await ctx.rpc.sharedState.get('vx:run', { initialValue: initRunState() })
+
+      // Local snapshot fed to `reduce`; the shared state is updated by
+      // assigning the new snapshot onto its draft (pure reduce → diffable
+      // patch). Kept beside the shared state rather than read back from it
+      // so reduction never depends on devframe's immutable accessors.
+      let snapshot = initRunState()
+      // `run()` emits `run:end` more than once (the normal end + a `finally`
+      // safety call) plus summary `run:status` lines AFTER the first
+      // `run:end`. Once the stream is closed, ignore everything — writing
+      // to a closed stream throws (StreamClosedError), and the run is over.
+      let closed = false
+
+      bus.subscribe((event) => {
+        if (closed) return
+        stream.write(toWireEvent(event))
+        snapshot = reduce(snapshot, event)
+        state.mutate((draft) => {
+          Object.assign(draft, snapshot)
+        })
+        if (event.kind === 'run:end') {
+          stream.close()
+          closed = true
+        }
+      })
+    },
+  }
+}