@openwop/openwop-conformance 1.0.0

package/src/lib/otel-collector.ts

@@ -0,0 +1,312 @@
+/**
+ * In-process OTLP/HTTP receiver for OTel conformance verification (Track 11).
+ *
+ * Purpose: the conformance suite is otherwise black-box (HTTP + SSE). To
+ * verify that hosts emit the canonical `openwop.*` OTel spans + metrics
+ * documented in `spec/v1/observability.md`, we need an inbound channel
+ * that captures what the host's OTLP exporter emits.
+ *
+ * Approach: stand up a minimal HTTP server (Node stdlib only — no
+ * `@opentelemetry/*` deps) that accepts POST to `/v1/traces` and
+ * `/v1/metrics` in OTLP/HTTP-JSON encoding, parses the payloads, and
+ * exposes them via a query API. Scenarios assert on the captured data.
+ *
+ * Operator contract: when running the OTel conformance scenarios, the
+ * host MUST be configured to export to `OTEL_EXPORTER_OTLP_ENDPOINT`
+ * pointing at the collector started here. The suite reads
+ * `OPENWOP_OTEL_COLLECTOR_PORT` (default `4318`, OTLP/HTTP convention) to
+ * determine where to bind. The operator sets `OTEL_EXPORTER_OTLP_ENDPOINT`
+ * on the host process to the matching `http://localhost:<port>` value.
+ *
+ * Wire format: OTLP/HTTP-JSON per
+ *   https://opentelemetry.io/docs/specs/otlp/#otlphttp-json-encoded-payload
+ * Shape (simplified):
+ *   { resourceSpans: [{ resource, scopeSpans: [{ scope, spans: [...] }] }] }
+ *   { resourceMetrics: [{ resource, scopeMetrics: [{ scope, metrics: [...] }] }] }
+ *
+ * Span attribute encoding (OTLP): each attribute is
+ *   { key: string, value: { stringValue | intValue | doubleValue | boolValue | arrayValue | kvlistValue } }
+ *
+ * @see spec/v1/observability.md
+ */
+
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+export interface OtelAttribute {
+  readonly key: string;
+  readonly value: string | number | boolean | null | readonly unknown[];
+}
+
+export interface CapturedSpan {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId: string | undefined;
+  readonly name: string;
+  readonly startTimeUnixNano: string;
+  readonly endTimeUnixNano: string;
+  readonly attributes: ReadonlyMap<string, string | number | boolean | null | readonly unknown[]>;
+  readonly resourceAttributes: ReadonlyMap<string, string | number | boolean | null | readonly unknown[]>;
+}
+
+export interface CapturedMetric {
+  readonly name: string;
+  readonly description: string | undefined;
+  readonly unit: string | undefined;
+  readonly kind: 'sum' | 'gauge' | 'histogram' | 'unknown';
+  /** First captured data point — sufficient for shape assertions. */
+  readonly dataPoint: {
+    readonly attributes: ReadonlyMap<string, string | number | boolean | null | readonly unknown[]>;
+    readonly value: number | undefined;
+  };
+}
+
+/**
+ * Decode an OTLP attribute-value object into a primitive. Returns `null`
+ * when the value shape is unrecognized.
+ */
+function decodeAttrValue(v: unknown): string | number | boolean | null | readonly unknown[] {
+  if (v === null || typeof v !== 'object') return null;
+  const obj = v as Record<string, unknown>;
+  if (typeof obj.stringValue === 'string') return obj.stringValue;
+  if (typeof obj.intValue === 'string') return Number(obj.intValue);
+  if (typeof obj.intValue === 'number') return obj.intValue;
+  if (typeof obj.doubleValue === 'number') return obj.doubleValue;
+  if (typeof obj.boolValue === 'boolean') return obj.boolValue;
+  if (obj.arrayValue && typeof obj.arrayValue === 'object') {
+    const av = (obj.arrayValue as { values?: unknown[] }).values ?? [];
+    return av.map(decodeAttrValue);
+  }
+  return null;
+}
+
+function decodeAttributes(
+  attrs: ReadonlyArray<{ key: unknown; value: unknown }> | undefined,
+): Map<string, string | number | boolean | null | readonly unknown[]> {
+  const out = new Map<string, string | number | boolean | null | readonly unknown[]>();
+  if (!attrs) return out;
+  for (const a of attrs) {
+    if (typeof a.key !== 'string') continue;
+    out.set(a.key, decodeAttrValue(a.value));
+  }
+  return out;
+}
+
+export class OtelCollector {
+  private readonly _spans: CapturedSpan[] = [];
+  private readonly _metrics: CapturedMetric[] = [];
+  private _server: Server | null = null;
+  private _boundPort: number = 0;
+
+  /**
+   * Start the collector. If `port` is `0` (or unset), an ephemeral port
+   * is assigned and exposed via `boundPort()`.
+   */
+  async start(port: number = 0): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const server = createServer((req, res) => this._handle(req, res));
+      server.on('error', reject);
+      server.listen(port, '127.0.0.1', () => {
+        const addr = server.address() as AddressInfo;
+        this._server = server;
+        this._boundPort = addr.port;
+        resolve();
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (!this._server) return;
+    const server = this._server;
+    this._server = null;
+    return new Promise((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  boundPort(): number {
+    return this._boundPort;
+  }
+
+  endpoint(): string {
+    return `http://127.0.0.1:${this._boundPort}`;
+  }
+
+  reset(): void {
+    this._spans.length = 0;
+    this._metrics.length = 0;
+  }
+
+  /** All captured spans, in capture (arrival) order. */
+  spans(): readonly CapturedSpan[] {
+    return this._spans;
+  }
+
+  /** Spans filtered by an attribute equality. Use for run-scoping. */
+  spansWithAttribute(key: string, value: unknown): readonly CapturedSpan[] {
+    return this._spans.filter((s) => s.attributes.get(key) === value);
+  }
+
+  spansByName(name: string): readonly CapturedSpan[] {
+    return this._spans.filter((s) => s.name === name);
+  }
+
+  metrics(): readonly CapturedMetric[] {
+    return this._metrics;
+  }
+
+  metricByName(name: string): CapturedMetric | undefined {
+    return this._metrics.find((m) => m.name === name);
+  }
+
+  private async _handle(
+    req: import('node:http').IncomingMessage,
+    res: import('node:http').ServerResponse,
+  ): Promise<void> {
+    if (req.method !== 'POST') {
+      res.writeHead(405).end();
+      return;
+    }
+    const chunks: Buffer[] = [];
+    for await (const c of req) {
+      chunks.push(c as Buffer);
+    }
+    const body = Buffer.concat(chunks).toString('utf8');
+    let payload: Record<string, unknown> = {};
+    try {
+      payload = body.length > 0 ? (JSON.parse(body) as Record<string, unknown>) : {};
+    } catch {
+      // Protobuf-encoded OTLP arrives as binary; we currently support JSON only.
+      // Hosts that emit protobuf-encoded OTLP need to be configured for
+      // `OTEL_EXPORTER_OTLP_PROTOCOL=http/json`.
+      res.writeHead(415).end('OTLP/HTTP-JSON only');
+      return;
+    }
+
+    if (req.url?.includes('/v1/traces')) {
+      this._ingestTraces(payload);
+    } else if (req.url?.includes('/v1/metrics')) {
+      this._ingestMetrics(payload);
+    } else {
+      // Ignore /v1/logs and unknown paths; respond OK so the exporter doesn't retry.
+    }
+
+    res.writeHead(200, { 'Content-Type': 'application/json' }).end('{}');
+  }
+
+  private _ingestTraces(payload: Record<string, unknown>): void {
+    const rs = (payload.resourceSpans ?? []) as ReadonlyArray<Record<string, unknown>>;
+    for (const r of rs) {
+      const resourceAttrs = decodeAttributes(
+        ((r.resource ?? {}) as { attributes?: ReadonlyArray<{ key: unknown; value: unknown }> })
+          .attributes,
+      );
+      const ss = (r.scopeSpans ?? []) as ReadonlyArray<Record<string, unknown>>;
+      for (const s of ss) {
+        const spans = (s.spans ?? []) as ReadonlyArray<Record<string, unknown>>;
+        for (const sp of spans) {
+          this._spans.push({
+            traceId: String(sp.traceId ?? ''),
+            spanId: String(sp.spanId ?? ''),
+            parentSpanId: sp.parentSpanId ? String(sp.parentSpanId) : undefined,
+            name: String(sp.name ?? ''),
+            startTimeUnixNano: String(sp.startTimeUnixNano ?? '0'),
+            endTimeUnixNano: String(sp.endTimeUnixNano ?? '0'),
+            attributes: decodeAttributes(
+              sp.attributes as ReadonlyArray<{ key: unknown; value: unknown }> | undefined,
+            ),
+            resourceAttributes: resourceAttrs,
+          });
+        }
+      }
+    }
+  }
+
+  private _ingestMetrics(payload: Record<string, unknown>): void {
+    const rm = (payload.resourceMetrics ?? []) as ReadonlyArray<Record<string, unknown>>;
+    for (const r of rm) {
+      const sm = (r.scopeMetrics ?? []) as ReadonlyArray<Record<string, unknown>>;
+      for (const s of sm) {
+        const metrics = (s.metrics ?? []) as ReadonlyArray<Record<string, unknown>>;
+        for (const m of metrics) {
+          let kind: CapturedMetric['kind'] = 'unknown';
+          let dp:
+            | {
+                attributes: Map<string, string | number | boolean | null | readonly unknown[]>;
+                value: number | undefined;
+              }
+            | undefined;
+
+          for (const k of ['sum', 'gauge', 'histogram'] as const) {
+            const slot = m[k] as { dataPoints?: ReadonlyArray<Record<string, unknown>> } | undefined;
+            if (!slot?.dataPoints?.length) continue;
+            kind = k;
+            const first = slot.dataPoints[0];
+            const attrs = decodeAttributes(
+              first.attributes as
+                | ReadonlyArray<{ key: unknown; value: unknown }>
+                | undefined,
+            );
+            const value =
+              typeof first.asDouble === 'number'
+                ? first.asDouble
+                : typeof first.asInt === 'string'
+                  ? Number(first.asInt)
+                  : typeof first.asInt === 'number'
+                    ? first.asInt
+                    : undefined;
+            dp = { attributes: attrs, value };
+            break;
+          }
+
+          if (!dp) continue;
+
+          this._metrics.push({
+            name: String(m.name ?? ''),
+            description: typeof m.description === 'string' ? m.description : undefined,
+            unit: typeof m.unit === 'string' ? m.unit : undefined,
+            kind,
+            dataPoint: dp,
+          });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Module-scope collector instance. Vitest setup file starts it; scenarios
+ * call `getCollector()` to fetch the running instance.
+ */
+let _instance: OtelCollector | null = null;
+
+export function setCollector(c: OtelCollector | null): void {
+  _instance = c;
+}
+
+export function getCollector(): OtelCollector | null {
+  return _instance;
+}
+
+/**
+ * Convenience: poll the collector for spans matching a run-id, with a
+ * timeout. Hosts emit OTel spans asynchronously after run terminal, so
+ * scenarios MUST poll rather than read once.
+ */
+export async function waitForRunSpans(
+  runId: string,
+  options: { timeoutMs?: number; pollIntervalMs?: number; minCount?: number } = {},
+): Promise<readonly CapturedSpan[]> {
+  const collector = getCollector();
+  if (!collector) return [];
+  const timeoutMs = options.timeoutMs ?? 5_000;
+  const pollIntervalMs = options.pollIntervalMs ?? 100;
+  const minCount = options.minCount ?? 1;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const matching = collector.spansWithAttribute('openwop.run_id', runId);
+    if (matching.length >= minCount) return matching;
+    await new Promise((r) => setTimeout(r, pollIntervalMs));
+  }
+  return collector.spansWithAttribute('openwop.run_id', runId);
+}

package/src/lib/paths.ts

@@ -0,0 +1,198 @@
+/**
+ * Layout-aware path resolver for the offline subset.
+ *
+ * The same suite source runs in two layouts:
+ *
+ *   1. Repo checkout — `openwop/conformance/src/scenarios/X.test.ts`. Schemas,
+ *      api/, and prose docs live one level above the conformance package
+ *      at the repo root.
+ *
+ *   2. Published tarball — `node_modules/@openwop/openwop-conformance/src/...`.
+ *      The `prepack` script vendors `api/` and `schemas/` INTO the package,
+ *      so they resolve relative to the package root instead of a parent.
+ *      Spec prose (`spec/v1/*.md`) is NOT bundled — those tests skip.
+ *
+ * Earlier offline scenarios computed `__dirname/../../..` to find
+ * the repo root. That works in a checkout but lands in `node_modules/@openwop/`
+ * after npx-style install, breaking `npx -y @openwop/openwop-conformance --offline`
+ * with `ENOENT: ... node_modules/@openwop/schemas/workflow-definition.schema.json`.
+ *
+ * This module centralises the resolution. Strategy:
+ *
+ *   - If `OPENWOP_CONFORMANCE_ROOT` is set, treat its value as the layout root
+ *     (the directory that contains `schemas/`, `api/`, and either
+ *     `conformance/fixtures/` (repo) or `fixtures/` directly (vendored)).
+ *     Used by integrators who put the suite in an unusual location.
+ *
+ *   - Otherwise compute the package root from `import.meta.url` (= the
+ *     directory containing `package.json`) and probe whether the schemas
+ *     are vendored at the package root (published) or at the parent (repo).
+ *
+ * Exported paths are non-null for the materials always present in both
+ * layouts; the prose-doc and fixtures.md catalog dirs may resolve to
+ * `null` under the published layout, in which case the corresponding
+ * scenarios skip cleanly (see `spec-corpus-validity.test.ts`).
+ */
+
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve as pathResolve } from 'node:path';
+
+// `dirname(fileURLToPath(import.meta.url))` for an ESM module compiled or
+// run from `src/lib/paths.ts` returns `<pkg>/src/lib/`. The conformance
+// package root is therefore two directories above this file in BOTH the
+// repo checkout and the published tarball — the source layout is
+// identical between the two; only the parent of `<pkg>` differs.
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = pathResolve(HERE, '..', '..');
+
+interface ResolvedLayout {
+  /** Conformance package directory (where `package.json` lives). */
+  readonly pkgRoot: string;
+  /** Directory containing JSON Schemas. */
+  readonly schemasDir: string;
+  /** Directory containing the OpenAPI/AsyncAPI specs. */
+  readonly apiDir: string;
+  /** Directory containing the conformance fixtures (top-level + sub-dirs). */
+  readonly fixturesDir: string;
+  /** Directory containing scenario test files, if present in this layout. */
+  readonly scenariosDir: string | null;
+  /** Path to the conformance package README, if present in this layout. */
+  readonly conformanceReadmePath: string | null;
+  /** Path to `fixtures.md` catalog, if present in this layout. */
+  readonly fixturesDocPath: string | null;
+  /** Path to `coverage.md` operation-coverage map, if present in this layout. */
+  readonly coverageDocPath: string | null;
+  /** Directory containing v1 prose docs (`*.md`), if present in this layout. */
+  readonly v1Dir: string | null;
+  /** Path to repository README.md, if present in this layout. */
+  readonly readmePath: string | null;
+  /** Path to the TypeScript SDK run-helper source, if present in this layout. */
+  readonly typescriptRunHelpersPath: string | null;
+  /** Path to the Python SDK types source, if present in this layout. */
+  readonly pythonTypesPath: string | null;
+  /** Path to the Go SDK types source, if present in this layout. */
+  readonly goTypesPath: string | null;
+  /** Discriminator — which layout did we resolve to? */
+  readonly layout: 'env-override' | 'repo' | 'published';
+}
+
+function resolveFromRoot(root: string, layout: ResolvedLayout['layout']): ResolvedLayout {
+  // Two on-disk shapes for the layout root:
+  //   - Repo: <root>/schemas, <root>/api, <root>/conformance/fixtures,
+  //           <root>/conformance/{fixtures.md,coverage.md}, <root>/spec/v1/*.md
+  //     (Where `<root>` = the repo root, e.g. `openwop/`.)
+  //   - Vendored / published: <root>/schemas, <root>/api, <root>/fixtures,
+  //           <root>/fixtures.md (when bundled), no spec/v1.
+  // Probe by checking whether `schemas/` lives at the conformance pkg root
+  // (vendored) vs one level up (repo).
+  const schemasDir = join(root, 'schemas');
+  const apiDir = join(root, 'api');
+  const repoFixturesDir = join(root, 'conformance', 'fixtures');
+  const vendoredFixturesDir = join(root, 'fixtures');
+  const fixturesDir = existsSync(repoFixturesDir) ? repoFixturesDir : vendoredFixturesDir;
+  const repoScenariosDir = join(root, 'conformance', 'src', 'scenarios');
+  const vendoredScenariosDir = join(PKG_ROOT, 'src', 'scenarios');
+  const scenariosDir = existsSync(repoScenariosDir)
+    ? repoScenariosDir
+    : existsSync(vendoredScenariosDir)
+      ? vendoredScenariosDir
+      : null;
+  const repoConformanceReadme = join(root, 'conformance', 'README.md');
+  const vendoredConformanceReadme = join(PKG_ROOT, 'README.md');
+  const conformanceReadmePath = existsSync(repoConformanceReadme)
+    ? repoConformanceReadme
+    : existsSync(vendoredConformanceReadme)
+      ? vendoredConformanceReadme
+      : null;
+  const repoFixturesDoc = join(root, 'conformance', 'fixtures.md');
+  const vendoredFixturesDoc = join(root, 'fixtures.md');
+  const fixturesDocPath = existsSync(repoFixturesDoc)
+    ? repoFixturesDoc
+    : existsSync(vendoredFixturesDoc)
+      ? vendoredFixturesDoc
+      : null;
+  const repoCoverageDoc = join(root, 'conformance', 'coverage.md');
+  const vendoredCoverageDoc = join(root, 'coverage.md');
+  const coverageDocPath = existsSync(repoCoverageDoc)
+    ? repoCoverageDoc
+    : existsSync(vendoredCoverageDoc)
+      ? vendoredCoverageDoc
+      : null;
+  const v1Probe = join(root, 'spec', 'v1');
+  const v1Dir = existsSync(v1Probe) ? v1Probe : null;
+  const readmeProbe = join(root, 'README.md');
+  const readmePath = existsSync(readmeProbe) ? readmeProbe : null;
+  const typescriptRunHelpersProbe = join(root, 'sdk', 'typescript', 'src', 'run-helpers.ts');
+  const typescriptRunHelpersPath = existsSync(typescriptRunHelpersProbe) ? typescriptRunHelpersProbe : null;
+  const pythonTypesProbe = join(root, 'sdk', 'python', 'src', 'openwop_client', 'types.py');
+  const pythonTypesPath = existsSync(pythonTypesProbe) ? pythonTypesProbe : null;
+  const goTypesProbe = join(root, 'sdk', 'go', 'types.go');
+  const goTypesPath = existsSync(goTypesProbe) ? goTypesProbe : null;
+  return {
+    pkgRoot: PKG_ROOT,
+    schemasDir,
+    apiDir,
+    fixturesDir,
+    scenariosDir,
+    conformanceReadmePath,
+    fixturesDocPath,
+    coverageDocPath,
+    v1Dir,
+    readmePath,
+    typescriptRunHelpersPath,
+    pythonTypesPath,
+    goTypesPath,
+    layout,
+  };
+}
+
+function resolveLayout(): ResolvedLayout {
+  const override = process.env.OPENWOP_CONFORMANCE_ROOT?.trim();
+  if (override && override.length > 0) {
+    return resolveFromRoot(pathResolve(override), 'env-override');
+  }
+  // Vendored / published-tarball layout: `prepack` copies `schemas/` +
+  // `api/` to the package root. Repo layout: schemas live one level
+  // above the conformance package.
+  //
+  // Edge case: a developer running `npm pack` locally without a
+  // postpack cleanup leaves schemas/ in BOTH places transiently. When
+  // both exist, prefer the parent (repo layout) so prose-doc tests
+  // continue to run — the parent is the canonical source.
+  const parent = pathResolve(PKG_ROOT, '..');
+  const parentHasSchemas = existsSync(join(parent, 'schemas'));
+  const pkgHasSchemas = existsSync(join(PKG_ROOT, 'schemas'));
+  if (parentHasSchemas) {
+    return resolveFromRoot(parent, 'repo');
+  }
+  if (pkgHasSchemas) {
+    return resolveFromRoot(PKG_ROOT, 'published');
+  }
+  // Neither — return the published-style resolution rooted at PKG_ROOT
+  // so error messages name a concrete directory rather than a
+  // computed-from-undefined path.
+  return resolveFromRoot(PKG_ROOT, 'published');
+}
+
+const _layout = resolveLayout();
+
+export const PKG_ROOT_PATH: string = _layout.pkgRoot;
+export const SCHEMAS_DIR: string = _layout.schemasDir;
+export const API_DIR: string = _layout.apiDir;
+export const FIXTURES_DIR: string = _layout.fixturesDir;
+export const SCENARIOS_DIR: string | null = _layout.scenariosDir;
+export const CONFORMANCE_README_PATH: string | null = _layout.conformanceReadmePath;
+export const FIXTURES_DOC_PATH: string | null = _layout.fixturesDocPath;
+export const COVERAGE_DOC_PATH: string | null = _layout.coverageDocPath;
+export const V1_DIR: string | null = _layout.v1Dir;
+export const README_PATH: string | null = _layout.readmePath;
+export const TYPESCRIPT_RUN_HELPERS_PATH: string | null = _layout.typescriptRunHelpersPath;
+export const PYTHON_TYPES_PATH: string | null = _layout.pythonTypesPath;
+export const GO_TYPES_PATH: string | null = _layout.goTypesPath;
+export const LAYOUT: ResolvedLayout['layout'] = _layout.layout;
+
+/** Test-only — re-resolve in case env var or filesystem changed. */
+export function __resolveLayoutForTests(): ResolvedLayout {
+  return resolveLayout();
+}

package/src/lib/polling.ts

@@ -0,0 +1,81 @@
+/**
+ * Polling helpers for run-state assertions.
+ *
+ * The conformance suite uses `GET /v1/runs/{runId}` polling rather than
+ * SSE because SSE termination semantics vary across implementations.
+ * Polling is the lowest-common-denominator wire; SSE-specific scenarios
+ * live in stream-modes.test.ts.
+ *
+ * Bound long polls with OPENWOP_LIFECYCLE_TIMEOUT_MS env var (default 10s).
+ */
+
+import { driver } from './driver.js';
+
+export interface RunSnapshot {
+  readonly runId: string;
+  readonly status: string;
+  readonly workflowId?: string;
+  readonly currentNodeId?: string;
+  readonly nodeStates?: Record<string, unknown>;
+  readonly variables?: Record<string, unknown>;
+  readonly error?: { code?: string; message?: string };
+  readonly metrics?: {
+    readonly openwopCost?: {
+      readonly usd?: number;
+      readonly tokens?: { readonly input?: number; readonly output?: number };
+      readonly model?: string;
+      readonly provider?: string;
+      readonly duration_ms?: number;
+    };
+  };
+}
+
+const POLL_INTERVAL_MS = 250;
+const DEFAULT_TIMEOUT_MS = Number(process.env.OPENWOP_LIFECYCLE_TIMEOUT_MS ?? 10_000);
+
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+export async function getRun(runId: string): Promise<RunSnapshot> {
+  const res = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+  if (res.status !== 200) {
+    throw new Error(`GET /v1/runs/${runId} returned ${res.status}: ${res.text.slice(0, 200)}`);
+  }
+  return res.json as RunSnapshot;
+}
+
+export async function pollUntil(
+  runId: string,
+  predicate: (snap: RunSnapshot) => boolean,
+  opts: { timeoutMs?: number; label?: string } = {},
+): Promise<RunSnapshot> {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const deadline = Date.now() + timeoutMs;
+  let last: RunSnapshot | null = null;
+  while (Date.now() < deadline) {
+    try {
+      last = await getRun(runId);
+      if (predicate(last)) return last;
+    } catch {
+      // 404 right after POST is plausible while the run is being committed —
+      // swallow and retry. Other errors will retry too; they'll surface via
+      // the timeout message if persistent.
+    }
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+  }
+  const label = opts.label ?? 'predicate';
+  throw new Error(
+    `Run ${runId} did not satisfy ${label} within ${timeoutMs}ms (last status: ${last?.status ?? 'unknown'})`,
+  );
+}
+
+export function pollUntilTerminal(runId: string, opts: { timeoutMs?: number } = {}): Promise<RunSnapshot> {
+  return pollUntil(runId, (s) => TERMINAL.has(s.status), { ...opts, label: 'terminal status' });
+}
+
+export function pollUntilStatus(
+  runId: string,
+  expected: string,
+  opts: { timeoutMs?: number } = {},
+): Promise<RunSnapshot> {
+  return pollUntil(runId, (s) => s.status === expected, { ...opts, label: `status === ${expected}` });
+}