@relayflows/sdk 2.0.9 → 2.0.11

package/src/named-gate-lowering.ts

@@ -0,0 +1,147 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { deflateRawSync } from 'node:zlib';
+import { bindingDependencies } from './input-binding.js';
+import { isNamedGate, regexFlags } from './named-gates.js';
+import type { NamedDataGate, StepSpec, VerificationSpec } from './spec.js';
+
+const quote = (text: string): string => `'${text.replaceAll("'", "'\\''")}'`;
+let re2Source: string | undefined;
+
+/** Embed the pinned engine in the command: execution does not resolve npm or SDK paths. */
+function embeddedRE2(): string {
+  re2Source ??= deflateRawSync(readFileSync(createRequire(import.meta.url).resolve('re2js'))).toString('base64');
+  return `const re2={};new Function('exports',require('node:zlib').inflateRawSync(Buffer.from(${JSON.stringify(re2Source)},'base64')).toString())(re2);`;
+}
+
+/**
+ * A gate is a nested deterministic step in the same journal/DAG. Keep the
+ * producer's identity/output, and add a barrier to every dependent (including
+ * implicit input edges). Internal bindings select the whole envelope so no
+ * invented output-path schema is needed. Missing paths fail in the gate.
+ */
+export function lowerNamedGates(steps: readonly StepSpec[]): StepSpec[] {
+  const used = new Set(steps.map(step => step.id));
+  const barriers = new Map<string, string>();
+  for (const step of steps) {
+    if (!isNamedGate(step.verification)) continue;
+    let id = `${step.id}.gate`;
+    while (used.has(id)) id += '.gate';
+    used.add(id);
+    barriers.set(step.id, id);
+  }
+  if (barriers.size === 0) return [...steps];
+  const output: StepSpec[] = [];
+  for (const step of steps) {
+    const dependencies = [...new Set([...(step.dependsOn ?? []), ...bindingDependencies(step.input)])];
+    const dependsOn = [...new Set([...dependencies, ...dependencies.flatMap(id => barriers.get(id) ?? [])])];
+    const producer = dependsOn.length ? { ...step, dependsOn } : step;
+    const gate = step.verification;
+    if (!isNamedGate(gate)) {
+      output.push(producer);
+      continue;
+    }
+    // The original output is still checked for a successful process/worker
+    // completion. This schema permits an internal whole-output binding.
+    output.push({ ...producer, verification: { type: 'json_schema', schema: true } });
+    const input = {
+      output: { step: step.id },
+      ...(gate.type === 'references_input' ? { reference: step.input![gate.input_key]! } : {}),
+    };
+    output.push({
+      id: barriers.get(step.id)!, type: 'deterministic',
+      dependsOn: [...new Set([step.id, ...bindingDependencies(input)])], input,
+      command: gateCommand(gate, step.type === 'deterministic'),
+      verification: gateVerification(gate), maxIterations: step.maxIterations ?? 1,
+      ...(step.requirements === undefined ? {} : { requirements: step.requirements }),
+    });
+  }
+  return output;
+}
+
+function gateCommand(gate: NamedDataGate, deterministic: boolean): string {
+  const path = gate.type === 'subprocess_gate' ? gate.from_output
+    : gate.type === 'word_count_bounds' ? undefined : gate.in_output_at;
+  // Only compiler-owned code is serialized. Author strings are JSON literals;
+  // upstream output travels exclusively through FLOWS_INPUT, never shell text.
+  const setup = `const cp=require('node:child_process');
+const input=JSON.parse(process.env.FLOWS_INPUT);
+let value=input.output;
+const path=${JSON.stringify(path ?? null)};
+if(path!==null){for(const key of path){
+if(value===null||typeof value!=='object'||!Object.hasOwn(value,key)||
+(typeof key==='number'?!Array.isArray(value):Array.isArray(value)))process.exit(1);
+value=value[key];
+}}else if(${deterministic})value=value.stdout_tail;
+const text=typeof value==='string'?value:JSON.stringify(value);
+if(typeof text!=='string')process.exit(1);
+`;
+  let body: string;
+  switch (gate.type) {
+    case 'references_input':
+      body = `const reference=input.reference;
+if(typeof reference!=='string'||reference.length===0||!text.includes(reference))process.exit(1);
+process.stdout.write('references_input:pass');`;
+      break;
+    case 'subprocess_gate':
+      body = `if(text.includes('\\0'))process.exit(1);
+const result=cp.spawnSync('/bin/sh',['-c',${JSON.stringify(gate.command)}],{
+env:{...process.env,INPUT:text},stdio:'inherit'});
+process.exit(result.status===0?0:1);`;
+      break;
+    case 'word_count_bounds':
+      body = `const result=cp.spawnSync('wc',['-w'],{input:text,encoding:'utf8',env:{...process.env,LC_ALL:'C'}});
+if(result.status!==0)process.exit(1);
+const count=result.stdout.trim();
+if(!/^[0-9]+$/.test(count))process.exit(1);
+process.stdout.write(BigInt(count).toString());`;
+      break;
+    case 'regex_match':
+      body = `${embeddedRE2()}
+process.exit(re2.RE2JS.compile(${JSON.stringify(gate.pattern)},${regexFlags(gate.flags ?? '')}).matcher(text).find()?0:1);`;
+      break;
+  }
+  return `node -e ${quote(setup + body)}`;
+}
+
+function gateVerification(gate: NamedDataGate): VerificationSpec {
+  if (gate.type === 'references_input') {
+    // output_contains cannot carry a runtime binding. The command resolves and
+    // checks the literal substring, then emits this fixed, unforgeable receipt.
+    return { type: 'output_contains', value: 'references_input:pass' };
+  }
+  if (gate.type === 'word_count_bounds') {
+    // Deterministic output is an envelope with STRING stdout, not parsed JSON.
+    // A bounded decimal language enforces the same inclusive numeric range
+    // with the existing json_schema primitive and retains the actual count.
+    return { type: 'json_schema', schema: {
+      type: 'object', required: ['stdout_tail'], properties: {
+        stdout_tail: { type: 'string', pattern: decimalRange(gate.min ?? 0, gate.max ?? Number.MAX_SAFE_INTEGER) },
+      },
+    } };
+  }
+  return { type: 'exit_code' };
+}
+
+/** Compact decimal range, bounded by 16 digits rather than by range width. */
+function decimalRange(min: number, max: number): string {
+  const patterns: string[] = [];
+  function between(low: string, high: string, prefix: string): void {
+    if (low === high) { patterns.push(prefix + low); return; }
+    if (/^0+$/.test(low) && /^9+$/.test(high)) {
+      patterns.push(`${prefix}[0-9]{${low.length}}`); return;
+    }
+    const a = Number(low[0]), b = Number(high[0]);
+    if (a === b) { between(low.slice(1), high.slice(1), prefix + a); return; }
+    const rest = low.length - 1;
+    between(low.slice(1), '9'.repeat(rest), prefix + a);
+    if (a + 1 <= b - 1) patterns.push(`${prefix}[${a + 1}-${b - 1}]${rest ? `[0-9]{${rest}}` : ''}`);
+    between('0'.repeat(rest), high.slice(1), prefix + b);
+  }
+  for (let digits = String(min).length; digits <= String(max).length; digits++) {
+    const low = digits === String(min).length ? String(min) : '1' + '0'.repeat(digits - 1);
+    const high = digits === String(max).length ? String(max) : '9'.repeat(digits);
+    between(low, high, '');
+  }
+  return `^(?:${patterns.join('|')})$`;
+}

package/src/named-gates.ts

@@ -0,0 +1,76 @@
+import { RE2JS } from 're2js';
+import type { NamedDataGate, VerificationSpec } from './spec.js';
+
+export const NAMED_GATE_FAILURE_KINDS = [
+  'unknown_gate_kind', 'gate_pattern_invalid', 'gate_command_missing', 'gate_bound_invalid',
+] as const;
+export type NamedGateFailureKind = typeof NAMED_GATE_FAILURE_KINDS[number];
+
+export const NAMED_GATE_KEYS: Record<NamedDataGate['type'], readonly string[]> = {
+  references_input: ['type', 'input_key', 'in_output_at'],
+  subprocess_gate: ['type', 'command', 'from_output'],
+  word_count_bounds: ['type', 'min', 'max'],
+  regex_match: ['type', 'pattern', 'in_output_at', 'flags'],
+};
+
+export function isNamedGate(gate: VerificationSpec | undefined): gate is NamedDataGate {
+  return gate !== undefined && Object.hasOwn(NAMED_GATE_KEYS, gate.type);
+}
+
+export function regexFlags(flags: string): number {
+  return (flags.includes('i') ? RE2JS.CASE_INSENSITIVE : 0)
+    | (flags.includes('m') ? RE2JS.MULTILINE : 0)
+    | (flags.includes('s') ? RE2JS.DOTALL : 0);
+}
+
+/** Called only on snapshotted data, including by the public validator. */
+export function namedGateErrors(gate: Record<string, unknown>, input: unknown, at: string): string[] {
+  const errors: string[] = [];
+  for (const key of ['in_output_at', 'from_output']) {
+    const path = gate[key];
+    if (path !== undefined && (!Array.isArray(path) || !path.every(segment =>
+      typeof segment === 'string' || (Number.isSafeInteger(segment) && (segment as number) >= 0)))) {
+      errors.push(`${at}.${key}: expected an array of object keys or non-negative integer indices`);
+    }
+  }
+  switch (gate.type) {
+    case 'references_input':
+      if (typeof gate.input_key !== 'string' || !gate.input_key.trim()
+        || input === null || typeof input !== 'object' || !Object.hasOwn(input, gate.input_key)) {
+        errors.push(`${at}.input_key: must name a declared input binding`);
+      }
+      break;
+    case 'subprocess_gate':
+      if (typeof gate.command !== 'string' || !gate.command.trim() || gate.command.includes('\0')) {
+        errors.push(`${at}.command: gate_command_missing: expected a non-empty shell command`);
+      }
+      break;
+    case 'word_count_bounds': {
+      const { min, max } = gate;
+      if ([min, max].some(n => n !== undefined && (!Number.isSafeInteger(n) || (n as number) < 0))
+        || (typeof min === 'number' && typeof max === 'number' && min > max)) {
+        errors.push(`${at}: gate_bound_invalid: min and max must be non-negative safe integers with min <= max`);
+      }
+      break;
+    }
+    case 'regex_match':
+      try {
+        if (typeof gate.pattern !== 'string' || gate.pattern.length > 8192) {
+          throw new Error('pattern must be a string of at most 8192 characters');
+        }
+        const flags = gate.flags ?? '';
+        if (typeof flags !== 'string' || !/^(?!.*(.).*\1)[ims]*$/.test(flags)) {
+          throw new Error('flags must be a non-repeating subset of i, m, s');
+        }
+        RE2JS.compile(gate.pattern, regexFlags(flags));
+      } catch (error) {
+        errors.push(`${at}: gate_pattern_invalid: ${error instanceof Error ? error.message : 'invalid RE2 pattern'}`);
+      }
+      break;
+  }
+  return errors;
+}
+
+export function namedGateFailure(errors: readonly string[]): NamedGateFailureKind | undefined {
+  return NAMED_GATE_FAILURE_KINDS.find(kind => errors.some(error => error.includes(`${kind}:`)));
+}

package/src/observer-link.ts

@@ -0,0 +1,368 @@
+/**
+ * Observer-link support for `flows run`: mint a scoped read-only observer token
+ * from a Relaycast workspace admin key, then print
+ * `Observer: <url>?key=<ot_live_...>` on stdout so an operator can drop into the
+ * Relaycast observer dashboard with the live-stream credential pre-filled.
+ *
+ * The workspace admin key (`rk_live_*`) is refused by the realtime endpoint —
+ * only an `ot_live_*` observer token with `stream:read` may open the workspace
+ * stream. So we do the same thing the Relaycast observer dashboard does when a
+ * workspace admin logs in with their admin key: mint a fresh, uniquely-named,
+ * scoped, short-lived observer token on their behalf and hand *that* to the
+ * URL. The workspace admin key never leaves the operator's machine.
+ *
+ * Everything here is best-effort. A missing workspace key means "no observer
+ * link, silently" — this is a parity feature relaying v1's convenience, not a
+ * requirement of a local run. A mint failure emits a labeled diagnostic to
+ * stderr and continues; a run must never fail because the observer link failed.
+ */
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Scopes the minted token carries. Mirrors the observer dashboard's set. */
+const OBSERVER_SCOPES = [
+  'stream:read',
+  'messages:read',
+  'threads:read',
+  'dms:read',
+  'channels:read',
+  'search:read',
+  'agents:read',
+  'nodes:read',
+  'deliveries:read',
+  'activity:read',
+  'files:read',
+  'reactions:read',
+] as const;
+
+/** Token lifetime for a `flows run` session. 24h is well past the longest run. */
+const OBSERVER_TOKEN_TTL_MS = 60 * 60 * 24 * 1000;
+
+/**
+ * Default hosts for the two axes of the observer link. They are DIFFERENT
+ * subdomains and must not be conflated (empirically verified 2026-09-10):
+ *
+ * - Mint API: `POST cast.agentrelay.com/v1/observer-tokens`. `agentrelay.com`
+ *   returns 404 for this path. Overridable via `RELAYCAST_API_URL`.
+ * - Observer dashboard: `agentrelay.com/observer?key=<ot_live_...>`.
+ *   `cast.agentrelay.com/observer` returns 404. Overridable via
+ *   `RELAYCAST_DASHBOARD_URL`.
+ *
+ * An earlier fix collapsed both to `cast.agentrelay.com` and closed #278 for
+ * the mint half only; a demo verification then landed on the 404 dashboard
+ * URL. Keep the two constants distinct.
+ */
+const DEFAULT_RELAYCAST_MINT_URL = 'https://cast.agentrelay.com';
+const DEFAULT_RELAYCAST_DASHBOARD_URL = 'https://agentrelay.com';
+
+/** Bounded so a stalled Relaycast API cannot delay the RUN summary. */
+const MINT_TIMEOUT_MS = 5_000;
+
+export interface ObserverLinkEnv {
+  workspaceKey?: string;
+  /** Base URL for the mint API (`POST /v1/observer-tokens`). */
+  baseUrl?: string;
+  /** Base URL for the observer dashboard the emitted link points at. */
+  dashboardUrl?: string;
+  /** `FLOWS_NO_OBSERVER=1` suppresses the mint even when a key is present. */
+  suppressed: boolean;
+}
+
+/**
+ * Path to the `agent-relay` local workspace-key store. Structure:
+ * `{ active: string, workspaces: { [name]: { key: string } } }`. Written
+ * by `agent-relay workspace set_key` / `agent-relay workspace join`; the
+ * canonical file the `@agent-relay/cloud` package reads via
+ * `resolveActiveWorkspaceKey`. Verified against
+ * `packages/cloud/src/workspace-store.ts` in `AgentWorkforce/relay`.
+ *
+ * Respects `AGENT_RELAY_HOME` so a caller can point at a different store
+ * for tests without touching the real one. Falls back to
+ * `~/.agentworkforce/relay/workspaces.json` -- the same default that
+ * package uses.
+ */
+export function agentRelayWorkspaceStorePath(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const dir = env['AGENT_RELAY_HOME'] ?? join(homedir(), '.agentworkforce/relay');
+  return join(dir, 'workspaces.json');
+}
+
+/**
+ * Shape of the `workspaces.json` file. Only the fields we depend on are
+ * declared; other keys are ignored. Kept structural so a type mismatch on
+ * an untrusted disk read falls into the "no cloud key readable" branch
+ * rather than throwing.
+ */
+interface AgentRelayWorkspaceStore {
+  active?: string;
+  workspaces?: Record<string, { key?: string } | undefined>;
+}
+
+/**
+ * Read the active workspace key from the `agent-relay cloud login` /
+ * `agent-relay workspace set_key` store. Returns `undefined` on every
+ * failure mode -- file absent, unreadable, malformed JSON, no active
+ * workspace, active workspace has no key, key is empty -- so the caller
+ * can silently fall through to "no observer link" the same way an unset
+ * `RELAYCAST_WORKSPACE_KEY` does.
+ *
+ * A file-shape mismatch is INTENTIONALLY not a hard error: `agent-relay`
+ * may extend this file in future without warning, and refusing a flow
+ * because a fallback credential store looked odd would be strictly worse
+ * than falling back to the explicit env var (which is the primary path).
+ */
+export function readAgentRelayWorkspaceKey(
+  env: NodeJS.ProcessEnv = process.env,
+  readFile: (path: string) => string = defaultReadFile,
+): string | undefined {
+  let raw: string;
+  try {
+    raw = readFile(agentRelayWorkspaceStorePath(env));
+  } catch {
+    return undefined;
+  }
+  let parsed: AgentRelayWorkspaceStore;
+  try {
+    parsed = JSON.parse(raw) as AgentRelayWorkspaceStore;
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return undefined;
+  const activeName = parsed.active;
+  if (typeof activeName !== 'string' || activeName === '') return undefined;
+  const workspaces = parsed.workspaces;
+  if (typeof workspaces !== 'object' || workspaces === null) return undefined;
+  const entry = workspaces[activeName];
+  if (typeof entry !== 'object' || entry === null) return undefined;
+  const key = entry.key;
+  if (typeof key !== 'string') return undefined;
+  const trimmed = key.trim();
+  return trimmed === '' ? undefined : trimmed;
+}
+
+function defaultReadFile(filePath: string): string {
+  return readFileSync(filePath, 'utf8');
+}
+
+/**
+ * Options controlling `resolveObserverLinkEnv`'s fallback behavior. The
+ * `readWorkspaceKey` seam is what the tests inject to simulate presence,
+ * absence, and malformed shapes of the on-disk store without touching the
+ * real home directory.
+ */
+export interface ResolveObserverLinkEnvOptions {
+  readWorkspaceKey?: (env: NodeJS.ProcessEnv) => string | undefined;
+}
+
+/**
+ * Env-first observer link resolution with an `agent-relay` cloud fallback.
+ *
+ * Priority (from the task spec, explicit beats implicit):
+ * 1. `RELAYCAST_WORKSPACE_KEY` if set and non-empty.
+ * 2. Active workspace key from `~/.agentworkforce/relay/workspaces.json`
+ *    (populated by `agent-relay cloud login` + `agent-relay workspace
+ *    set_key`), when readable.
+ * 3. Nothing -- silent skip, same as an unset primary env var.
+ *
+ * `FLOWS_NO_OBSERVER=1` still suppresses regardless of source.
+ */
+export function resolveObserverLinkEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  options: ResolveObserverLinkEnvOptions = {},
+): ObserverLinkEnv {
+  const primary = readObserverLinkEnv(env);
+  if (primary.workspaceKey !== undefined || primary.suppressed) {
+    return primary;
+  }
+  const readWorkspaceKey = options.readWorkspaceKey ?? readAgentRelayWorkspaceKey;
+  const fallback = readWorkspaceKey(env);
+  if (fallback === undefined) return primary;
+  return {
+    ...primary,
+    workspaceKey: fallback,
+  };
+}
+
+/**
+ * Read the observer-link config from the environment. Both trims and
+ * emptiness-checks the workspace key so a `RELAYCAST_WORKSPACE_KEY=` with no
+ * value reads the same as unset (no observer link, silently).
+ */
+export function readObserverLinkEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): ObserverLinkEnv {
+  const rawKey = env['RELAYCAST_WORKSPACE_KEY'];
+  const workspaceKey = typeof rawKey === 'string' ? rawKey.trim() : '';
+  const rawApi = env['RELAYCAST_API_URL'];
+  const baseUrl = typeof rawApi === 'string' && rawApi.trim() !== ''
+    ? rawApi.trim()
+    : undefined;
+  const rawDashboard = env['RELAYCAST_DASHBOARD_URL'];
+  const dashboardUrl = typeof rawDashboard === 'string' && rawDashboard.trim() !== ''
+    ? rawDashboard.trim()
+    : undefined;
+  return {
+    ...(workspaceKey !== '' ? { workspaceKey } : {}),
+    ...(baseUrl !== undefined ? { baseUrl } : {}),
+    ...(dashboardUrl !== undefined ? { dashboardUrl } : {}),
+    suppressed: env['FLOWS_NO_OBSERVER'] === '1',
+  };
+}
+
+/**
+ * Minimal `fetch` shape we depend on. Kept structural so tests can inject a
+ * mock without pulling in a fetch replacement library.
+ */
+export type ObserverFetch = (
+  url: string,
+  init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+  },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  json: () => Promise<unknown>;
+}>;
+
+export interface MintObserverOptions {
+  workspaceKey: string;
+  /** Base URL of the mint API (default `https://cast.agentrelay.com`). */
+  baseUrl?: string;
+  /** Base URL of the observer dashboard the returned URL points at
+   * (default `https://agentrelay.com`). Separate axis from `baseUrl` — the
+   * mint API lives on a different subdomain from the dashboard. */
+  dashboardUrl?: string;
+  fetch?: ObserverFetch;
+  now?: () => number;
+  /** Called for the token's uniquely-suffixed name; injectable for tests. */
+  uuid?: () => string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface MintObserverOutcome {
+  observerUrl?: string;
+  /**
+   * A short diagnostic to log when mint failed. `undefined` on success or on
+   * "no observer link is possible" (missing key/suppressed) so the caller can
+   * distinguish silent-skip from "warn about the miss".
+   */
+  warning?: string;
+}
+
+/**
+ * Mint an `ot_live_*` observer token via `POST /v1/observer-tokens` and return
+ * the observer dashboard URL that pre-fills it. Any failure — 4xx/5xx from the
+ * engine, malformed response, network error, timeout — returns a `warning`
+ * string and no URL. The caller must not fail the run on `warning`.
+ */
+export async function mintObserverUrl(
+  options: MintObserverOptions,
+): Promise<MintObserverOutcome> {
+  const doFetch: ObserverFetch = options.fetch ?? ((globalThis as unknown as {
+    fetch: ObserverFetch;
+  }).fetch);
+  if (typeof doFetch !== 'function') {
+    return { warning: 'no fetch implementation available' };
+  }
+
+  const rawApi = options.baseUrl ?? DEFAULT_RELAYCAST_MINT_URL;
+  const rawDashboard = options.dashboardUrl ?? DEFAULT_RELAYCAST_DASHBOARD_URL;
+  let mintUrl: URL;
+  let observerBase: URL;
+  try {
+    mintUrl = new URL('/v1/observer-tokens', rawApi);
+  } catch {
+    return { warning: `invalid RELAYCAST_API_URL "${rawApi}"` };
+  }
+  try {
+    observerBase = new URL('/observer', rawDashboard);
+  } catch {
+    return { warning: `invalid RELAYCAST_DASHBOARD_URL "${rawDashboard}"` };
+  }
+
+  const uuid = (options.uuid ?? defaultUuid)();
+  const now = options.now ?? (() => Date.now());
+  const timeoutMs = options.timeoutMs ?? MINT_TIMEOUT_MS;
+  const deadline = AbortSignal.timeout(timeoutMs);
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, deadline])
+    : deadline;
+
+  const payload = {
+    name: `flows-run-${uuid}`,
+    description: 'Auto-minted by `flows run` for the observer dashboard link.',
+    scopes: OBSERVER_SCOPES,
+    filters: { include_dms: true },
+    expires_at: new Date(now() + OBSERVER_TOKEN_TTL_MS).toISOString(),
+  };
+
+  let response: Awaited<ReturnType<ObserverFetch>>;
+  try {
+    response = await doFetch(mintUrl.toString(), {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${options.workspaceKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+      signal,
+    });
+  } catch (error) {
+    return { warning: `network error: ${errorMessage(error)}` };
+  }
+
+  if (!response.ok) {
+    return { warning: `mint API returned HTTP ${response.status}` };
+  }
+
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch (error) {
+    return { warning: `malformed response: ${errorMessage(error)}` };
+  }
+
+  const token = pickToken(body);
+  if (token === undefined) {
+    return { warning: 'mint API response missing ot_live_ token' };
+  }
+
+  // `URL.searchParams.set` percent-encodes any exotic characters the token
+  // could carry. It also collapses the leading `/observer` path correctly.
+  observerBase.searchParams.set('key', token);
+  return { observerUrl: observerBase.toString() };
+}
+
+/**
+ * Pick `data.token` from a `POST /v1/observer-tokens` response, refusing any
+ * shape that is not a plain `ot_live_*` string. Anything else is treated as
+ * "response too weird to trust" and produces no URL.
+ */
+function pickToken(body: unknown): string | undefined {
+  if (typeof body !== 'object' || body === null) return undefined;
+  const data = (body as Record<string, unknown>)['data'];
+  if (typeof data !== 'object' || data === null) return undefined;
+  const token = (data as Record<string, unknown>)['token'];
+  if (typeof token !== 'string' || !token.startsWith('ot_live_')) return undefined;
+  return token;
+}
+
+function defaultUuid(): string {
+  // `crypto.randomUUID()` is available on every Node 20+ target the SDK
+  // supports. The token name is not a security surface — it only has to be
+  // unique per (workspace, name) — so the fallback is a plain timestamp.
+  const c = (globalThis as unknown as { crypto?: { randomUUID?: () => string } }).crypto;
+  return c?.randomUUID?.() ?? String(Date.now());
+}
+
+function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return 'unknown error';
+}

package/src/plugin-loader.ts

@@ -0,0 +1,88 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Ajv } from 'ajv';
+import type { Step } from '@relayflows/surface';
+import { snapshotJsonValue } from './json-value.js';
+import { assertSupportedPlugin, PluginError, pluginPackageName, validatePluginManifest, type PluginManifest, type PluginVerb } from './plugin-manifest.js';
+
+export interface LoadedPlugin { readonly directory: string; readonly manifest: PluginManifest }
+export function findPluginProject(start: string): string | undefined {
+  let current = resolve(start);
+  for (;;) {
+    if (existsSync(join(current, 'flows.json'))) return current;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+export function readPlugin(directory: string, packageName: string): LoadedPlugin {
+  const path = join(directory, 'flows-plugin.json');
+  if (!existsSync(path)) throw new PluginError('plugin_manifest_missing', `${packageName} has no flows-plugin.json.`);
+  let input: unknown;
+  try { input = JSON.parse(readFileSync(path, 'utf8')); }
+  catch { throw new PluginError('plugin_manifest_invalid', `${packageName} manifest is unreadable or invalid JSON.`); }
+  const manifest = validatePluginManifest(input, packageName);
+  assertSupportedPlugin(manifest);
+  return Object.freeze({ directory, manifest });
+}
+export async function probePlugin(plugin: LoadedPlugin, env: NodeJS.ProcessEnv = process.env): Promise<void> {
+  for (const credential of plugin.manifest.preflight.credentials) {
+    if (!env[credential]?.trim()) throw new PluginError('plugin_credential_missing', `${plugin.manifest.name} requires ${credential}.`);
+  }
+  for (const server of plugin.manifest.preflight.servers) {
+    try {
+      const response = await fetch(server, { method: 'HEAD', signal: AbortSignal.timeout(5000) });
+      await response.body?.cancel();
+      if (!response.ok) throw new Error('unsuccessful response');
+    } catch { throw new PluginError('plugin_server_unreachable', `${plugin.manifest.name} cannot reach ${server}.`); }
+  }
+}
+export async function loadPlugins(start: string): Promise<readonly LoadedPlugin[]> {
+  const root = findPluginProject(start);
+  if (root === undefined) return Object.freeze([]);
+  let config: { plugins?: unknown };
+  try { config = JSON.parse(readFileSync(join(root, 'flows.json'), 'utf8')); }
+  catch { throw new PluginError('plugin_manifest_invalid', 'Invalid flows.json.'); }
+  if (config === null || typeof config !== 'object' || (config.plugins !== undefined && (!Array.isArray(config.plugins) || !config.plugins.every(p => typeof p === 'string')))) {
+    throw new PluginError('plugin_manifest_invalid', 'flows.json plugins must be package names.');
+  }
+  const scope = join(root, 'node_modules/@flows');
+  const names = new Set<string>((config.plugins as string[] | undefined)?.map(pluginPackageName));
+  if (existsSync(scope)) for (const name of readdirSync(scope).sort()) {
+    if (name.startsWith('helper-') && !names.has(`@flows/${name}`)) {
+      throw new PluginError('plugin_unlisted', `@flows/${name} is installed but not declared in flows.json plugins. Run flows add ${name}.`);
+    }
+  }
+  const plugins = [...names].sort().map(name => readPlugin(join(root, 'node_modules', name), name));
+  const namespaces = new Set<string>();
+  for (const plugin of plugins) {
+    for (const namespace of new Set(plugin.manifest.verbs.map(v => v.namespace))) {
+      if (namespaces.has(namespace)) throw new PluginError('plugin_manifest_invalid', `Duplicate plugin namespace ${namespace}.`);
+      namespaces.add(namespace);
+    }
+    await probePlugin(plugin);
+    if (!existsSync(join(plugin.directory, 'src/index.js'))) throw new PluginError('plugin_manifest_invalid', `${plugin.manifest.name} requires src/index.js.`);
+  }
+  return Object.freeze(plugins);
+}
+export function pluginHelpers(plugins: readonly LoadedPlugin[], invoke: (plugin: LoadedPlugin, verb: PluginVerb, args: unknown) => Step<unknown>): Record<string, unknown> {
+  const helpers: Record<string, Record<string, (args: unknown) => Step<unknown>>> = Object.create(null);
+  const ajv = new Ajv({ strict: false });
+  for (const plugin of plugins) for (const verb of plugin.manifest.verbs) {
+    const validate = ajv.compile(verb.args);
+    const namespace = helpers[verb.namespace] ??= Object.create(null);
+    namespace[verb.method] = args => {
+      const snapshot = snapshotJsonValue(args, `f.${verb.namespace}.${verb.method} arguments`);
+      if (!validate(snapshot)) throw new PluginError('plugin_manifest_invalid', `Invalid arguments for ${verb.namespace}.${verb.method}: ${ajv.errorsText(validate.errors)}`);
+      return invoke(plugin, verb, snapshot);
+    };
+  }
+  for (const helper of Object.values(helpers)) Object.freeze(helper);
+  return Object.freeze(helpers);
+}
+export async function invokePlugin(plugin: LoadedPlugin, verb: PluginVerb, args: unknown, idempotencyKey: string): Promise<unknown> {
+  const module = await import(pathToFileURL(join(plugin.directory, 'src/index.js')).href);
+  if (typeof module.execute !== 'function') throw new Error('plugin_runtime_invalid: expected execute export');
+  return snapshotJsonValue(await module.execute(verb.namespace, verb.method, args, Object.freeze({ idempotencyKey })), 'plugin output');
+}