@openwop/openwop-conformance 1.2.0 → 1.4.0

package/schemas/run-event.schema.json

@@ -101,16 +101,32 @@
         "lease.lost",
         "lease.handed-off",
         "replay.diverged",
+        "replay.divergedAtRefusal",
         "agent.reasoned",
+        "agent.reasoning.delta",
+        "provider.usage",
+        "prompt.composed",
+        "agent.promptResolved",
+        "model.capability.substituted",
+        "model.capability.insufficient",
+        "envelope.retry.attempted",
+        "envelope.retry.exhausted",
+        "envelope.refusal",
+        "envelope.truncated",
+        "envelope.nlToFormat.engaged",
+        "envelope.recovery.applied",
         "agent.toolCalled",
         "agent.toolReturned",
         "agent.handoff",
         "agent.decided",
         "runOrchestrator.decided",
+        "node.dispatched",
         "conversation.opened",
         "conversation.exchanged",
         "conversation.closed",
-        "memory.compacted"
+        "memory.compacted",
+        "core.workflowChain.event",
+        "core.workflowChain.confidence-escalated"
       ]
     }
   }

package/schemas/run-snapshot.schema.json

@@ -25,15 +25,16 @@
         "paused",
         "waiting-approval",
         "waiting-input",
+        "waiting-external",
         "completed",
         "failed",
         "cancelled"
       ],
-      "description": "Current run state. Forward-compat: future statuses MAY be added; readers SHOULD treat unknown values as terminal-unknown rather than throw."
+      "description": "Current run state. `waiting-external` MUST be used when the suspended interrupt's `kind` is `external-event` per `interrupt-profiles.md §openwop-interrupt-external-event` — distinguishes external-event waits from HITL waits at the wire level. Forward-compat: future statuses MAY be added; readers SHOULD treat unknown values as terminal-unknown rather than throw."
     },
     "currentNodeId": {
       "type": "string",
-      "description": "Set when the run is suspended at a specific node (`waiting-approval` / `waiting-input`) — identifies which node holds the interrupt."
+      "description": "Set when the run is suspended at a specific node (`waiting-approval` / `waiting-input` / `waiting-external`) — identifies which node holds the interrupt."
     },
     "startedAt": { "type": "string", "format": "date-time" },
     "completedAt": { "type": "string", "format": "date-time" },

package/schemas/workflow-definition.schema.json

@@ -77,6 +77,24 @@
       "description": "Optional JSON Schema 2020-12 declaring which RunOptions.configurable keys this workflow accepts. When present, hosts MUST validate POST /v1/runs `configurable` payloads against this schema and reject mismatches with `validation_error`. Hosts MUST surface this schema on GET /v1/workflows/{workflowId} so clients can pre-flight-validate. See run-options.md §'Per-workflow configurableSchema'. Additive in v1.1.",
       "type": "object"
     },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "RFC 0029 §B. Workflow-author-controlled per-kind fallback values that apply at resolution chain layer 3 (`workflow-defaults`) per `spec/v1/prompts.md` §\"Resolution chain (normative)\". Applied when neither the node (layer 1) nor the node's bound agent (layer 2) specifies a value for the kind. Future RFCs MAY add sibling defaults (e.g., `defaults.temperature`, `defaults.modelClass`) without colliding.",
+      "properties": {
+        "promptRefs": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Per-kind PromptRef fallbacks for layer 3 of the resolution chain.",
+          "properties": {
+            "system": { "$ref": "./prompt-ref.schema.json" },
+            "user": { "$ref": "./prompt-ref.schema.json" },
+            "few-shot": { "$ref": "./prompt-ref.schema.json" },
+            "schema-hint": { "$ref": "./prompt-ref.schema.json" }
+          }
+        }
+      }
+    },
     "metadata": { "$ref": "#/$defs/WorkflowMetadata" },
     "settings": { "$ref": "#/$defs/WorkflowSettings" },
     "acceptsInheritedArtifacts": {
@@ -111,7 +129,7 @@
         },
         "config": {
           "type": "object",
-          "description": "Node configuration (pre-execution constants)."
+          "description": "Node configuration (pre-execution constants). The shape is per-typeId — node-pack manifests declare each typeId's `configSchema` for install-time validation. By convention, the keys `systemPromptRef`, `userPromptRef`, and `additionalPromptRefs` MAY hold PromptRef values per `spec/v1/prompts.md` §\"PromptRef\" (RFC 0027). Hosts advertising `capabilities.prompts.supported: true` MUST resolve these keys; hosts without the capability MAY treat them as opaque strings. When both an inline body (e.g., `config.systemPrompt`) and a `*PromptRef` are present, the ref wins and the host MUST emit a `log.appended` warning with `code: \"prompt_ref_supersedes_inline\"` per RFC 0027 §C."
         },
         "inputs": {
           "type": "object",

package/src/lib/driver.ts

@@ -78,6 +78,21 @@ class OpenWOPDriver {
     return this.request('POST', path, { ...init, body });
   }
 
+  /** PUT helper. The body is JSON-stringified by default; pass a string
+   *  Content-Type header for raw-body PUTs (e.g. tarball uploads).
+   *  Production hosts that accept tarball PUTs on /v1/packs/* expect
+   *  `Content-Type: application/octet-stream`; callers MUST set the
+   *  header explicitly when uploading non-JSON. */
+  put(path: string, body: unknown, init: OpenWOPRequestInit = {}): Promise<OpenWOPResponse> {
+    return this.request('PUT', path, { ...init, body });
+  }
+
+  /** DELETE alias for the canonical name. Keeps the call-site shorter
+   *  for scenarios that delete via `driver.del(...)`. */
+  del(path: string, init: OpenWOPRequestInit = {}): Promise<OpenWOPResponse> {
+    return this.request('DELETE', path, init);
+  }
+
   delete(path: string, init: OpenWOPRequestInit = {}): Promise<OpenWOPResponse> {
     return this.request('DELETE', path, init);
   }

package/src/lib/env.ts

@@ -25,6 +25,28 @@
  *     hosts go strict-mode green without falsifying capability claims.
  *     Example for SQLite:
  *       OPENWOP_OPTED_OUT_PROFILES=openwop-production,openwop-auth-mtls
+ *
+ *   OPENWOP_OPTED_OUT_FIXTURES — comma-separated fixture ids (or
+ *     trailing-`*` globs) the host operator has DELIBERATELY chosen
+ *     not to honor. Applied in `lib/fixtures.ts` by filtering matching
+ *     entries out of the cached advertised-fixture set, so any
+ *     scenario gated via `isFixtureAdvertised(...)` skips cleanly.
+ *     Use when a host auto-loads every `conformance-*.json` on disk
+ *     (so the fixture id IS in the discovery doc) but the host doesn't
+ *     implement the gated feature. Symmetric to `OPENWOP_OPTED_OUT_
+ *     PROFILES` for the fixture-id axis. Example for SQLite:
+ *       OPENWOP_OPTED_OUT_FIXTURES=conformance-dispatch-*,conformance-subworkflow-input-mapping*
+ *
+ *   OPENWOP_OPTED_OUT_SCENARIOS — comma-separated scenario ids that
+ *     individual tests consult to skip themselves where neither
+ *     profile-opt-out nor fixture-opt-out is fine-grained enough
+ *     (e.g., OTel trace-inheritance across `core.subWorkflow` —
+ *     `conformance-subworkflow-parent` is correctly advertised because
+ *     non-OTel subworkflow scenarios pass, but the host doesn't
+ *     propagate traceparent across the dispatch boundary). Use
+ *     `isScenarioOptedOut(scenarioId)` from `env.ts` in the test's
+ *     skip predicate. Reserved for cases where the suite-wide
+ *     skip mechanisms can't carry the granularity.
  */
 
 export interface ConformanceEnv {
@@ -84,3 +106,32 @@ export function loadEnv(): ConformanceEnv {
   };
   return cached;
 }
+
+/**
+ * Returns true when the operator has listed `scenarioId` in
+ * `OPENWOP_OPTED_OUT_SCENARIOS`. Use inside a test's `describe.skipIf`
+ * predicate when neither profile-opt-out nor fixture-opt-out is
+ * granular enough. Logs the skip reason via the caller — this helper
+ * is silent so callers can format their own message.
+ *
+ * Re-reads `process.env` on every call (single env access + split, no
+ * cache). Symmetric with `lib/fixtures.ts:loadOptedOutPredicate` which
+ * re-reads on every `setAdvertisedFixtures(...)` call — so unit tests
+ * can mutate `process.env.OPENWOP_OPTED_OUT_SCENARIOS` between cases
+ * without having to invalidate a memoization.
+ */
+export function isScenarioOptedOut(scenarioId: string): boolean {
+  const raw = process.env.OPENWOP_OPTED_OUT_SCENARIOS?.trim() ?? '';
+  if (raw.length === 0) return false;
+  for (const entry of raw.split(',')) {
+    if (entry.trim() === scenarioId) return true;
+  }
+  return false;
+}
+
+/** Test-only: clear the `loadEnv()` memoization so subsequent calls
+ * re-read `process.env`. Required for any test that mutates the env
+ * vars consumed by `loadEnv()` mid-suite. */
+export function __resetEnvCacheForTests(): void {
+  cached = null;
+}

package/src/lib/event-log-query.ts

@@ -0,0 +1,62 @@
+/**
+ * Driver helpers for the test-only event-log query seam
+ * (`GET /v1/host/sample/test/runs/:runId/events`).
+ *
+ * Used by aiEnvelope engine-projection scenarios that verify the
+ * spec-prescribed events the host MUST emit on each envelope outcome
+ * (per RFC 0021 §A point 1-7 + interrupt.md + capabilities.md
+ * §"cap.breached"). All operations soft-skip on HTTP 404 — hosts
+ * without the seam keep the existing advertisement-shape coverage.
+ *
+ * Reset semantics: callers SHOULD `resetTestSeam()` in their test's
+ * `afterEach` (or scope each test to a unique runId) to keep state
+ * from leaking across scenarios.
+ */
+
+import { driver } from './driver.js';
+
+export interface TestEvent {
+  readonly eventId: string;
+  readonly runId: string;
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+  readonly timestamp: string;
+  readonly sequence: number;
+  readonly causationId?: string;
+  readonly nodeId?: string;
+  readonly contentTrust?: 'trusted' | 'untrusted';
+}
+
+export type QueryOutcome =
+  | { ok: true; events: TestEvent[] }
+  | { ok: false; reason: 'seam_unavailable' }
+  | { ok: false; reason: 'http_error'; status: number };
+
+/** Query the test-only event log for a run, with optional filters. */
+export async function queryTestEvents(
+  runId: string,
+  filter: { type?: string; correlationId?: string; causationId?: string; nodeId?: string } = {},
+): Promise<QueryOutcome> {
+  const qs = new URLSearchParams();
+  if (filter.type) qs.set('type', filter.type);
+  if (filter.correlationId) qs.set('correlationId', filter.correlationId);
+  if (filter.causationId) qs.set('causationId', filter.causationId);
+  if (filter.nodeId) qs.set('nodeId', filter.nodeId);
+  const url = `/v1/host/sample/test/runs/${encodeURIComponent(runId)}/events${qs.toString() ? '?' + qs.toString() : ''}`;
+  const res = await driver.get(url);
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { events?: TestEvent[] };
+  return { ok: true, events: body.events ?? [] };
+}
+
+/** Reset the test-only event log + capability overlay (suite teardown). */
+export async function resetTestSeam(): Promise<void> {
+  await driver.post('/v1/host/sample/test/reset', {});
+}
+
+/** Probe whether the seam is exposed. Use to soft-skip early. */
+export async function isEventLogSeamAvailable(): Promise<boolean> {
+  const res = await queryTestEvents('__probe__');
+  return res.ok;
+}

package/src/lib/fixtures.ts

@@ -26,6 +26,16 @@
  * This module is sync. The async fetch lives in `setup.ts` which calls
  * `setAdvertisedFixtures(...)` from a top-level `await`.
  *
+ * Honest opt-out (symmetric to `OPENWOP_OPTED_OUT_PROFILES`):
+ *   `OPENWOP_OPTED_OUT_FIXTURES` (CSV, supports trailing `*` glob)
+ *   subtracts matching fixture-ids from the cached set even when the
+ *   host advertises them. Operators use this when the host happens to
+ *   carry a fixture file (e.g., it auto-loads every `conformance-*.json`
+ *   on disk) but does NOT implement the underlying feature — so the
+ *   gated scenario should skip instead of running and failing. The
+ *   subtraction happens at cache-population time, so the predicate
+ *   remains a single sync set lookup at scenario-evaluation time.
+ *
  * @see spec/v1/capabilities.md §`fixtures`
  * @see spec/v1/profiles.md §`openwop-fixtures`
  * @see RFCS/0003-fixture-gating.md
@@ -35,19 +45,46 @@ import type { DiscoveryPayload } from './profiles.js';
 
 let _advertisedFixtures: ReadonlySet<string> | null = null;
 
+/**
+ * Parse `OPENWOP_OPTED_OUT_FIXTURES` into a match predicate. Each entry
+ * is either an exact id or a glob with a trailing `*`. Returns a
+ * function that answers "is this fixture-id opted out?" — empty / unset
+ * env reduces to "always false."
+ */
+function loadOptedOutPredicate(): (id: string) => boolean {
+  const raw = process.env.OPENWOP_OPTED_OUT_FIXTURES?.trim() ?? '';
+  if (raw.length === 0) return () => false;
+  const exact = new Set<string>();
+  const prefixes: string[] = [];
+  for (const entry of raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0)) {
+    if (entry.endsWith('*')) {
+      prefixes.push(entry.slice(0, -1));
+    } else {
+      exact.add(entry);
+    }
+  }
+  return (id) => exact.has(id) || prefixes.some((p) => id.startsWith(p));
+}
+
 /**
  * Populate the cache from a discovery-doc payload. The function is
  * tolerant of malformed inputs — anything other than a string array
  * collapses to "no fixtures advertised" rather than throwing, so the
  * suite remains resilient against host bugs in the discovery surface.
+ *
+ * Applies `OPENWOP_OPTED_OUT_FIXTURES` at this step: opted-out ids are
+ * filtered out of the cache before storage so downstream lookups can
+ * stay a single sync set-membership test.
  */
 export function setAdvertisedFixtures(c: DiscoveryPayload | null | undefined): void {
   if (c == null || !Array.isArray(c.fixtures)) {
     _advertisedFixtures = new Set();
     return;
   }
+  const isOptedOut = loadOptedOutPredicate();
   const ids = c.fixtures.filter(
-    (entry): entry is string => typeof entry === 'string' && entry.length > 0,
+    (entry): entry is string =>
+      typeof entry === 'string' && entry.length > 0 && !isOptedOut(entry),
   );
   _advertisedFixtures = new Set(ids);
 }

package/src/lib/host-toggle.ts

@@ -0,0 +1,54 @@
+/**
+ * Capability-toggle harness primitive — driver helper for the
+ * env-gated test-seam endpoint at
+ * `POST /v1/host/sample/test/capability-toggle`.
+ *
+ * Lets refusal-case scenarios (RFC 0022 §C HVMAP-1a-refusal,
+ * HVMAP-2-refusal, etc.) flip a capability flag off temporarily,
+ * exercise the host's refusal path, then restore the default.
+ *
+ * All operations soft-skip on HTTP 404 — hosts that don't expose the
+ * seam keep the existing advertisement-shape coverage intact.
+ *
+ * Reset semantics: callers MUST `resetHostCapabilities()` in their
+ * test's `afterEach` (or equivalent) to keep state from leaking
+ * across scenarios.
+ */
+
+import { driver } from './driver.js';
+
+export type ToggleOutcome =
+  | { ok: true; overlay: Record<string, boolean> }
+  | { ok: false; reason: 'seam_unavailable' }
+  | { ok: false; reason: 'http_error'; status: number };
+
+/** Set a capability flag's overlay value. `value: null` removes the
+ *  overlay entry (restoring the host's hard-coded default). */
+export async function setHostCapability(
+  name: string,
+  value: boolean | null,
+): Promise<ToggleOutcome> {
+  const res = await driver.post('/v1/host/sample/test/capability-toggle', { name, value });
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { overlay?: Record<string, boolean> };
+  return { ok: true, overlay: body.overlay ?? {} };
+}
+
+/** Clear ALL capability overlay entries on the host. */
+export async function resetHostCapabilities(): Promise<ToggleOutcome> {
+  const res = await driver.post('/v1/host/sample/test/capability-toggle', { reset: true });
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { overlay?: Record<string, boolean> };
+  return { ok: true, overlay: body.overlay ?? {} };
+}
+
+/** Probe whether the host exposes the capability-toggle seam at all.
+ *  Use this to soft-skip a scenario early when the host lacks the
+ *  toggle (the refusal contract is still spec-normative; the test just
+ *  can't drive it from outside). */
+export async function isToggleAvailable(): Promise<boolean> {
+  const probe = await setHostCapability('__probe__', null);
+  return probe.ok;
+}

package/src/lib/llm-cache-key-recipe.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared helpers for the LLM cache-key recipe per `spec/v1/replay.md`
+ * §"LLM cache-key recipe" §A + §B.
+ *
+ * Used by:
+ *   - `conformance/src/scenarios/replay-llm-cache-key.test.ts` — single-host
+ *     recipe assertions + non-recipe-field invariance + (gated)
+ *     cross-host parity via OPENWOP_BASE_URL_B.
+ *   - `conformance/src/scenarios/replay-llm-cache-key-portable.test.ts` —
+ *     RFC 0041 §E SECURITY-invariant probe (intra-host reproducibility +
+ *     non-recipe-field invariance + Phase 4 advertisement alignment).
+ *
+ * `canonicalize` mirrors RFC 8785 JCS-style output (sorted keys, no
+ * whitespace, preserved array order). Hosts that have a real JCS library
+ * available SHOULD prefer it; this helper is for the conformance side,
+ * not the host side. Keep in sync with `spec/v1/replay.md` §B.
+ */
+
+import { createHash } from 'node:crypto';
+import { driver } from './driver.js';
+
+/** RFC 8785 JCS-style canonicalization (subset suitable for the recipe
+ *  fields). Sorted keys recursively; no whitespace; preserved array order;
+ *  strings JSON-encoded verbatim (no NFC normalization — the recipe
+ *  inputs in our test seam are ASCII). */
+export function canonicalize(value: unknown): string {
+  if (value === null) return 'null';
+  if (typeof value === 'boolean' || typeof value === 'number') return JSON.stringify(value);
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map((v) => canonicalize(v)).join(',') + ']';
+  if (typeof value === 'object') {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj).sort();
+    return '{' + keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+/** Project a raw recipe-input object to the closed set of fields per
+ *  `replay.md` §A — omit absent optionals (do NOT emit null/default
+ *  placeholders), sort tools[] by name. */
+export function projectRecipe(raw: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = { provider: raw.provider, model: raw.model, messages: raw.messages };
+  if (Array.isArray(raw.tools) && raw.tools.length > 0) {
+    out.tools = [...(raw.tools as Array<{ name: string }>)].sort((a, b) => a.name.localeCompare(b.name));
+  }
+  if (typeof raw.temperature === 'number') out.temperature = raw.temperature;
+  if (typeof raw.topP === 'number') out.topP = raw.topP;
+  if (typeof raw.topK === 'number') out.topK = raw.topK;
+  if (raw.responseFormat && typeof raw.responseFormat === 'object') out.responseFormat = raw.responseFormat;
+  return out;
+}
+
+/** Compute the canonical LLM cache key per `replay.md` §B:
+ *  SHA-256(canonicalize(projectRecipe(input))) → lowercase hex. */
+export function expectedCacheKey(input: Record<string, unknown>): string {
+  return createHash('sha256').update(canonicalize(projectRecipe(input)), 'utf8').digest('hex');
+}
+
+/** Drive the host's `POST /v1/host/sample/test/llm-cache-key` test seam.
+ *  Returns the host's emitted cacheKey when the seam responds 200; status
+ *  alone when the seam returns 404 (host doesn't expose the seam → caller
+ *  soft-skips). */
+export async function callCacheKeySeam(input: Record<string, unknown>): Promise<{ status: number; cacheKey?: string }> {
+  const res = await driver.post('/v1/host/sample/test/llm-cache-key', input);
+  const cacheKey = (res.json as { cacheKey?: string }).cacheKey;
+  return cacheKey !== undefined ? { status: res.status, cacheKey } : { status: res.status };
+}

package/src/lib/multi-agent-capabilities.ts

@@ -37,6 +37,9 @@ interface AgentCaps {
     | {
         verbosity: 'summary' | 'full' | 'off' | undefined;
         tokenLimit: number | undefined;
+        /** RFC 0024. When true, host may emit `agent.reasoning.delta`
+         *  events in addition to the closing `agent.reasoned`. */
+        streaming: boolean;
       }
     | undefined;
 }
@@ -84,6 +87,7 @@ export function setMultiAgentCapabilities(c: DiscoveryPayload | null | undefined
               typeof (reasoningRaw as Record<string, unknown>).tokenLimit === 'number'
                 ? ((reasoningRaw as Record<string, unknown>).tokenLimit as number)
                 : undefined,
+            streaming: asBoolean((reasoningRaw as Record<string, unknown>).streaming),
           }
         : undefined;
     _agentCaps = {
@@ -113,6 +117,12 @@ export function getReasoningVerbosity(): 'summary' | 'full' | 'off' | undefined
   return _agentCaps?.reasoning?.verbosity;
 }
 
+/** RFC 0024 — host emits incremental `agent.reasoning.delta` events
+ *  while a reasoning block is still open. */
+export function isReasoningStreamingSupported(): boolean {
+  return _agentCaps?.reasoning?.streaming === true;
+}
+
 /** Phase 2 — host supports the named modelClass. */
 export function hasModelClass(modelClass: string): boolean {
   return _agentCaps?.modelClasses.has(modelClass) === true;

package/src/lib/otel-scrape.ts

@@ -0,0 +1,59 @@
+/**
+ * Driver helpers for the OTel + debug-bundle test seams (E.2 + E.3).
+ *
+ * Used by aiEnvelope + cost-attribution scenarios that need to verify
+ * span-attribute redaction (no BYOK canary in OTel attributes) and
+ * debug-bundle export shape.
+ */
+
+import { driver } from './driver.js';
+
+export interface TestSpan {
+  readonly spanId: string;
+  readonly name: string;
+  readonly attributes: Record<string, string | number | boolean>;
+  readonly envelopeId?: string;
+  readonly runId?: string;
+  readonly timestamp: string;
+}
+
+export interface DebugBundle {
+  readonly runId: string;
+  readonly events: unknown[];
+  readonly spans: TestSpan[];
+  readonly exportedAt: string;
+}
+
+export type ScrapeOutcome<T> =
+  | { ok: true; data: T }
+  | { ok: false; reason: 'seam_unavailable' }
+  | { ok: false; reason: 'http_error'; status: number };
+
+export async function queryTestSpans(
+  filter: { envelopeId?: string; runId?: string; name?: string } = {},
+): Promise<ScrapeOutcome<TestSpan[]>> {
+  const qs = new URLSearchParams();
+  if (filter.envelopeId) qs.set('envelopeId', filter.envelopeId);
+  if (filter.runId) qs.set('runId', filter.runId);
+  if (filter.name) qs.set('name', filter.name);
+  const url = `/v1/host/sample/test/otel/spans${qs.toString() ? '?' + qs.toString() : ''}`;
+  const res = await driver.get(url);
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { spans?: TestSpan[] };
+  return { ok: true, data: body.spans ?? [] };
+}
+
+export async function exportDebugBundle(runId: string): Promise<ScrapeOutcome<DebugBundle>> {
+  const res = await driver.post('/v1/host/sample/test/debug-bundle/export', { runId });
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { bundle?: DebugBundle };
+  if (!body.bundle) return { ok: false, reason: 'http_error', status: 500 };
+  return { ok: true, data: body.bundle };
+}
+
+export async function isOtelSeamAvailable(): Promise<boolean> {
+  const res = await queryTestSpans({ runId: '__probe__' });
+  return res.ok;
+}