@openwop/openwop 1.0.0

package/src/run-helpers.ts

@@ -0,0 +1,235 @@
+/**
+ * Run-status + error-code helpers — additive utilities over the wire-format
+ * `RunStatus` union, HTTP error envelopes, and run-level error shape
+ * declared in `types.ts`.
+ *
+ * **Why these live here.** `types.ts` declares the canonical wire shapes
+ * (mirroring `api/openapi.yaml` + `schemas/run-snapshot.schema.json`).
+ * This module adds the constants + predicates SDK consumers need to act
+ * on those shapes without redefining them locally. Pulling them into the
+ * SDK makes the protocol vocabulary single-sourced for application,
+ * integration, and test code.
+ *
+ * **Forward-compatibility design.** The spec's `RunStatus` enum is
+ * intentionally narrower than what host engines may emit: the schema
+ * declares *"future statuses MAY be added; readers SHOULD treat unknown
+ * values as terminal-unknown rather than throw"*. So `isTerminalRunStatus`
+ * accepts `string` and uses a **negative-set** check — anything NOT in
+ * the small known-non-terminal set is treated as terminal. This keeps
+ * the helper correct against:
+ *
+ *   - the canonical 8-member spec union (`pending` / `running` / `paused`
+ *     / `waiting-approval` / `waiting-input` / `completed` / `failed` /
+ *     `cancelled`)
+ *   - host extensions like `'planned'`, `'executing'`, `'waiting-external'`,
+ *     `'timed-out'`, `'interrupted'` which the OpenWOP engine emits
+ *   - any future spec additions before the SDK ships an updated minor
+ *
+ * @module @openwop/openwop/run-helpers
+ */
+
+import type { RunStatus } from './types.js';
+
+// ─── Run statuses ────────────────────────────────────────────────────────
+
+/**
+ * Run statuses considered active — the run MAY still transition. A reader
+ * who does not recognize a status string MUST treat it as terminal-unknown
+ * (per the spec's forward-compat clause). This list is the narrow,
+ * spec-stable enumeration used to derive that decision.
+ */
+export const ACTIVE_RUN_STATUSES = [
+  'pending',
+  'running',
+  'paused',
+  'waiting-approval',
+  'waiting-input',
+] as const;
+
+/**
+ * Spec-known terminal statuses. Hosts MAY emit additional terminal values
+ * (e.g., `'timed-out'`, `'interrupted'`); use {@link isTerminalRunStatus}
+ * for forward-compatible checks instead of literal-set membership.
+ */
+export const TERMINAL_RUN_STATUSES = [
+  'completed',
+  'failed',
+  'cancelled',
+] as const;
+
+export type ActiveRunStatus = (typeof ACTIVE_RUN_STATUSES)[number];
+export type TerminalRunStatus = (typeof TERMINAL_RUN_STATUSES)[number];
+
+/**
+ * Returns true if the status indicates the run will not transition further.
+ *
+ * Implemented as a negative check against {@link ACTIVE_RUN_STATUSES}: any
+ * value NOT in the spec's known-active set is treated as terminal. This
+ * implements the schema's forward-compat clause — a host that emits a
+ * status the SDK doesn't know about is assumed to be reporting a terminal
+ * state, NOT that the run is still active. The alternative (positive check
+ * against {@link TERMINAL_RUN_STATUSES}) would loop polling forever on any
+ * unknown value, which is the documented worst-case the clause prevents.
+ *
+ * Accepts `string` (not just `RunStatus`) so callers can pass values from
+ * extended host emissions without casting.
+ */
+export function isTerminalRunStatus(status: RunStatus | string): boolean {
+  return !(ACTIVE_RUN_STATUSES as readonly string[]).includes(status);
+}
+
+// ─── HTTP error-envelope codes ───────────────────────────────────────────
+
+/**
+ * Canonical REST/MCP error-envelope codes from `auth.md`,
+ * `rest-endpoints.md`, and adjacent v1 specs. The HTTP envelope's `error`
+ * field remains string-typed for forward compatibility, but this list
+ * gives SDK consumers a stable set for common branching.
+ *
+ * Codes here describe request/transport failures. Run execution failures
+ * live in `RUN_ERROR_CODES` below as `RunSnapshot.error.code`.
+ */
+export const HTTP_ERROR_CODES = [
+  // Auth / access
+  'unauthenticated',
+  'forbidden',
+  'key_expired',
+  'key_revoked',
+
+  // Request / routing
+  'validation_error',
+  'not_found',
+  'rate_limited',
+
+  // Idempotency / run creation conflicts
+  'run_already_active',
+  'idempotency_in_flight',
+  'idempotency_key_mismatch',
+
+  // Streaming / protocol negotiation
+  'unsupported_stream_mode',
+  'force_engine_version_forbidden',
+  'mock_provider_forbidden',
+
+  // Capability / credential negotiation
+  'capability_not_provided',
+  'credential_required',
+  'credential_forbidden',
+  'credential_unavailable',
+
+  // HITL / interrupt callbacks
+  'interrupt_not_found',
+  'approval_token_invalid',
+  'approval_token_expired',
+  'approval_token_consumed',
+
+  // Generic server failure
+  'internal_error',
+] as const;
+
+export type HttpErrorCode = (typeof HTTP_ERROR_CODES)[number];
+
+/**
+ * Type guard that narrows a string to a known canonical HTTP error code.
+ * Returns false for host extensions and future spec additions; callers
+ * should still render a fallback from the envelope's `message`.
+ */
+export function isHttpErrorCode(value: unknown): value is HttpErrorCode {
+  return typeof value === 'string' && (HTTP_ERROR_CODES as readonly string[]).includes(value);
+}
+
+// ─── Run error codes ─────────────────────────────────────────────────────
+
+/**
+ * Run-document error codes — stable identifiers used in
+ * `RunSnapshot.error.code` when a run reaches `failed`. These are distinct
+ * from the HTTP-level `ErrorEnvelope.error` codes above: a request can fail
+ * with `unauthenticated` before a run exists, while a run can fail later
+ * with `node_execution_failed` or `recursion_limit_exceeded`.
+ *
+ * Add a new code here when adding a new run failure mode that crosses the
+ * network boundary. Do NOT add codes for purely internal engine errors.
+ *
+ * **Drift risk note.** This list is canonical for SDK consumers but is
+ * NOT yet pinned by `conformance/src/scenarios/errors.test.ts` against
+ * host emission. A future conformance addition (tracked separately)
+ * SHOULD compare host-emitted error codes against this set and fail on
+ * unrecognized values. Until that lands, drift between this list + the
+ * engine's actual emission set is detectable only by manual review.
+ */
+export const RUN_ERROR_CODES = [
+  // Authorization / access
+  'auth_required',
+  'forbidden',
+  'workspace_not_found',
+
+  // Run-state conflicts
+  'run_already_active',
+  'run_not_found',
+  'run_terminal',
+  'engine_version_mismatch',
+
+  // Validation
+  'invalid_workflow_definition',
+  'invalid_trigger_input',
+  'node_type_not_found',
+  'config_validation_failed',
+
+  // Quota / budget
+  'token_budget_exceeded',
+  'concurrent_run_limit_reached',
+  'rate_limited',
+
+  // Execution
+  'node_timeout',
+  'global_timeout',
+  'node_execution_failed',
+  'external_call_failed',
+  'recursion_limit_exceeded',
+  'capability_not_provided',
+
+  // Approval
+  'approval_timeout',
+  'approval_token_invalid',
+  'approval_token_expired',
+  'approval_token_consumed',
+
+  // Persistence
+  'persistence_failed',
+  'doc_budget_exceeded',
+] as const;
+
+export type RunErrorCode = (typeof RUN_ERROR_CODES)[number];
+
+/**
+ * Type guard that narrows a string to a known {@link RunErrorCode}.
+ * Returns false for unknown / malformed values rather than throwing —
+ * SDK consumers usually want to display a fallback for unknown codes
+ * rather than crash the render pipeline.
+ */
+export function isRunErrorCode(value: unknown): value is RunErrorCode {
+  return typeof value === 'string' && (RUN_ERROR_CODES as readonly string[]).includes(value);
+}
+
+/**
+ * Run-level error shape — the structured `error` field on a `failed` run
+ * document. Distinct from the HTTP-level {@link import('./types.js').ErrorEnvelope}:
+ *
+ *   - `RunError` lives on the run document; describes WHY the run failed.
+ *     `code` is from the typed {@link RunErrorCode} vocabulary.
+ *   - `ErrorEnvelope` lives on HTTP error responses; describes WHY the
+ *     request failed. `error` is a free string code (often from
+ *     {@link HTTP_ERROR_CODES}, but not type-pinned, to permit host
+ *     extensions and future protocol additions).
+ *
+ * The shapes share `message` and `details` but diverge on the code field
+ * name (`code` vs `error`) by design — they represent different layers.
+ */
+export interface RunError {
+  code: RunErrorCode;
+  message: string;
+  /** Optional node-id where the error originated. */
+  nodeId?: string;
+  /** Optional structured context — implementations MAY extend. */
+  details?: Record<string, unknown>;
+}

package/src/sse.ts

@@ -0,0 +1,167 @@
+/**
+ * SSE consumer for `GET /v1/runs/{runId}/events`. Async-iterable shape so
+ * consumers can write `for await (const event of client.runs.events(...))`.
+ *
+ * Implementation parses event:/data:/id: lines per RFC 8895. Native fetch +
+ * ReadableStream — zero third-party deps.
+ *
+ * Designed to be cancellable: pass an AbortSignal via options, or break out
+ * of the for-await loop and the underlying connection is torn down on the
+ * next tick.
+ */
+
+import type { RunEventDoc, StreamMode } from './types.js';
+
+export interface EventsStreamOptions {
+  /**
+   * Single mode (e.g., 'updates') OR array of modes (S4 mixed-mode,
+   * e.g., ['updates', 'messages']). Arrays serialize to a comma-
+   * separated `?streamMode=updates,messages` query.
+   */
+  readonly streamMode?: StreamMode | readonly StreamMode[];
+  readonly lastEventId?: string;
+  readonly signal?: AbortSignal;
+  /**
+   * S3 batching hint. When set, server batches events for up to N ms;
+   * the SDK transparently flattens batched arrays back into individual
+   * RunEventDoc yields, so consumers see the same per-event surface as
+   * unbuffered streams. Range 0..5000.
+   */
+  readonly bufferMs?: number;
+}
+
+export interface EventsStreamContext {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+}
+
+export async function* streamEvents(
+  ctx: EventsStreamContext,
+  runId: string,
+  opts: EventsStreamOptions = {},
+): AsyncGenerator<RunEventDoc, void, void> {
+  const params = new URLSearchParams();
+  if (opts.streamMode) {
+    const modeParam: string =
+      typeof opts.streamMode === 'string' ? opts.streamMode : opts.streamMode.join(',');
+    params.set('streamMode', modeParam);
+  }
+  if (opts.bufferMs !== undefined) {
+    params.set('bufferMs', String(opts.bufferMs));
+  }
+  const qs = params.toString();
+  const url = `${ctx.baseUrl}/v1/runs/${encodeURIComponent(runId)}/events${qs ? `?${qs}` : ''}`;
+
+  const headers: Record<string, string> = {
+    Accept: 'text/event-stream',
+    Authorization: `Bearer ${ctx.apiKey}`,
+    'Cache-Control': 'no-cache',
+  };
+  if (opts.lastEventId) {
+    headers['Last-Event-ID'] = opts.lastEventId;
+  }
+
+  const internalAbort = new AbortController();
+  const externalSignal = opts.signal;
+  if (externalSignal) {
+    if (externalSignal.aborted) internalAbort.abort();
+    else externalSignal.addEventListener('abort', () => internalAbort.abort(), { once: true });
+  }
+
+  const res = await fetch(url, { method: 'GET', headers, signal: internalAbort.signal });
+  if (!res.ok || res.body === null) {
+    throw new Error(`SSE subscribe failed: HTTP ${res.status}`);
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+  let pendingEvent = 'message';
+  let pendingData: string[] = [];
+  let pendingId: string | null = null;
+
+  /**
+   * Flush the buffered event. Returns an array of RunEventDoc:
+   *   - 0 elements when the buffer is empty or non-JSON (skip).
+   *   - 1 element for a normal `event: <type>` event.
+   *   - N elements when the server batched per S3 — `event: batch` with
+   *     `data:` as a JSON array of RunEventDoc.
+   */
+  const flushAndYield = (): RunEventDoc[] => {
+    if (pendingData.length === 0) {
+      pendingEvent = 'message';
+      pendingId = null;
+      return [];
+    }
+    const dataStr = pendingData.join('\n');
+    const eventType = pendingEvent;
+    pendingEvent = 'message';
+    pendingData = [];
+    pendingId = null;
+    try {
+      const parsed = JSON.parse(dataStr) as unknown;
+      // S3 batched envelope — `event: batch` carries an array of events.
+      if (eventType === 'batch' && Array.isArray(parsed)) {
+        return parsed as RunEventDoc[];
+      }
+      // Normal single-event payload.
+      return [parsed as RunEventDoc];
+    } catch {
+      // Skip non-JSON events (keep-alive payloads, vendor extensions).
+      return [];
+    }
+  };
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let nlIdx: number;
+      while ((nlIdx = buffer.indexOf('\n')) !== -1) {
+        const rawLine = buffer.slice(0, nlIdx).replace(/\r$/, '');
+        buffer = buffer.slice(nlIdx + 1);
+
+        if (rawLine === '') {
+          for (const event of flushAndYield()) yield event;
+          continue;
+        }
+        if (rawLine.startsWith(':')) continue; // keep-alive comment
+
+        const colon = rawLine.indexOf(':');
+        const field = colon === -1 ? rawLine : rawLine.slice(0, colon);
+        const valueRaw = colon === -1 ? '' : rawLine.slice(colon + 1);
+        const fieldValue = valueRaw.startsWith(' ') ? valueRaw.slice(1) : valueRaw;
+
+        switch (field) {
+          case 'event':
+            pendingEvent = fieldValue;
+            break;
+          case 'data':
+            pendingData.push(fieldValue);
+            break;
+          case 'id':
+            pendingId = fieldValue;
+            break;
+          default:
+            break;
+        }
+      }
+    }
+    // Flush any final unterminated event.
+    for (const final of flushAndYield()) yield final;
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // best-effort
+    }
+    if (!internalAbort.signal.aborted) internalAbort.abort();
+  }
+
+  // Reference pendingEvent/pendingId so the linter doesn't flag them as
+  // unused; they're consumed via flushAndYield's closure but TS can't see
+  // that across a generator boundary.
+  void pendingEvent;
+  void pendingId;
+}

package/src/types.ts

@@ -0,0 +1,224 @@
+/**
+ * Request/response types for the openwop REST surface.
+ *
+ * Mirrors `api/openapi.yaml` and the JSON Schemas in
+ * `schemas/`. Hand-authored rather than codegen'd — see
+ * SDK README §rationale.
+ *
+ * Forward-compat: types use `string` (not narrow unions) for fields whose
+ * spec'd values may grow over time (status enums, event types, error codes).
+ * Consumers wanting exhaustive narrowing should `as const` their checks
+ * rather than relying on the SDK to refuse unknown values.
+ */
+
+/** Run statuses per `RunSnapshot.status` in OpenAPI. */
+export type RunStatus =
+  | 'pending'
+  | 'running'
+  | 'paused'
+  | 'waiting-approval'
+  | 'waiting-input'
+  | 'completed'
+  | 'failed'
+  | 'cancelled';
+
+export interface Capabilities {
+  protocolVersion: string;
+  supportedEnvelopes: readonly string[];
+  schemaVersions: Record<string, number>;
+  limits: {
+    clarificationRounds: number;
+    schemaRounds: number;
+    envelopesPerTurn: number;
+    maxNodeExecutions?: number;
+  };
+  extensions?: Record<string, unknown>;
+  // Network-handshake superset (all `(future)` fields per capabilities.md)
+  implementation?: { name?: string; version?: string; vendor?: string };
+  engineVersion?: number;
+  eventLogSchemaVersion?: number;
+  supportedTransports?: readonly ('rest' | 'mcp' | 'a2a' | 'grpc')[];
+  configurable?: Record<string, unknown>;
+  observability?: Record<string, unknown>;
+  minClientVersion?: string;
+}
+
+export interface RunSnapshot {
+  runId: string;
+  workflowId: string;
+  status: RunStatus;
+  currentNodeId?: string;
+  startedAt?: string;
+  completedAt?: string;
+  nodeStates?: Record<string, unknown>;
+  variables?: Record<string, unknown>;
+  channels?: Record<string, unknown>;
+  error?: { code?: string; message?: string };
+}
+
+/**
+ * Per-run parameter overlay carried in `RunOptions.configurable`. Reserved
+ * keys are typed; unknown keys are passed through verbatim. See
+ * `run-options.md`.
+ */
+export interface RunConfigurable {
+  /** Override the per-run node-execution ceiling. Clamped server-side. */
+  recursionLimit?: number;
+  /** Override AI model for nodes that consume `ctx.config.configurable.model`. */
+  model?: string;
+  /** Override AI temperature (server SHOULD enforce 0..2). */
+  temperature?: number;
+  /** Override AI max-tokens cap. */
+  maxTokens?: number;
+  /** Per-prompt-ID variant override map. */
+  promptOverrides?: Record<string, string>;
+  /** Implementation-specific extensions; passed through verbatim. */
+  [key: string]: unknown;
+}
+
+export interface CreateRunRequest {
+  workflowId: string;
+  inputs?: Record<string, unknown>;
+  tenantId?: string;
+  scopeId?: string;
+  callbackUrl?: string;
+  configurable?: RunConfigurable;
+  tags?: readonly string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface CreateRunResponse {
+  runId: string;
+  status: RunStatus;
+  eventsUrl: string;
+  statusUrl?: string;
+}
+
+export interface CancelRunRequest {
+  reason?: string;
+}
+
+export interface CancelRunResponse {
+  runId: string;
+  status: 'cancelled' | 'cancelling';
+}
+
+export interface ForkRunRequest {
+  fromSeq: number;
+  mode: 'replay' | 'branch';
+  runOptionsOverlay?: Record<string, unknown>;
+}
+
+export interface ForkRunResponse {
+  runId: string;
+  sourceRunId: string;
+  fromSeq?: number;
+  mode: 'replay' | 'branch';
+  status: RunStatus;
+  eventsUrl: string;
+}
+
+export interface ResolveInterruptRequest {
+  resumeValue: unknown;
+}
+
+export interface ResolveInterruptResponse {
+  runId: string;
+  nodeId: string;
+  status: RunStatus;
+}
+
+/**
+ * Token-scoped interrupt inspection response — mirrors `suspend-request.schema.json`
+ * (the `InterruptPayload` shape).
+ */
+export interface InterruptByTokenInspection {
+  kind: 'approval' | 'clarification' | 'external-event' | 'custom';
+  key: string;
+  resumeSchema?: Record<string, unknown>;
+  timeoutMs?: number;
+  data: unknown;
+}
+
+export interface ResolveInterruptByTokenResponse {
+  // Server-defined shape (openapi declares `type: object`); kept as
+  // unknown-typed object so SDK consumers narrow per implementation.
+  [key: string]: unknown;
+}
+
+export interface PollEventsResponse {
+  events: readonly RunEventDoc[];
+  isComplete: boolean;
+}
+
+/** Mirror of `run-event.schema.json` — top-level shape only. */
+export interface RunEventDoc {
+  eventId: string;
+  runId: string;
+  nodeId?: string;
+  type: string; // RunEventType — string-typed for forward compat
+  payload: unknown;
+  timestamp: string;
+  sequence: number;
+  schemaVersion?: number;
+  engineVersion?: string;
+  causationId?: string;
+}
+
+export interface ErrorEnvelope {
+  error: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+export type StreamMode = 'values' | 'updates' | 'messages' | 'debug';
+
+/**
+ * Thrown when the server returns a non-2xx response. Carries the original
+ * status, parsed error envelope (if available), the raw response text,
+ * and any `traceparent` the server returned (per
+ * `observability.md` §Trace context propagation —
+ * "Clients SHOULD display the trace ID in error messages so operators
+ * can search backend traces").
+ */
+export class WopError extends Error {
+  readonly status: number;
+  readonly envelope: ErrorEnvelope | undefined;
+  readonly rawText: string;
+  /** W3C `traceparent` from the response headers, when present. */
+  readonly traceparent: string | undefined;
+  /** 32-hex-char trace ID extracted from `traceparent`, when parseable. */
+  readonly traceId: string | undefined;
+
+  constructor(
+    status: number,
+    rawText: string,
+    envelope: ErrorEnvelope | undefined,
+    traceparent: string | undefined,
+  ) {
+    const traceId = traceparent ? extractTraceId(traceparent) : undefined;
+    const baseMessage = envelope?.message ?? `openwop request failed: HTTP ${status}`;
+    const messageWithTrace = traceId ? `${baseMessage} (trace=${traceId})` : baseMessage;
+    super(messageWithTrace);
+    this.name = 'WopError';
+    this.status = status;
+    this.rawText = rawText;
+    this.envelope = envelope;
+    this.traceparent = traceparent;
+    this.traceId = traceId;
+  }
+}
+
+/**
+ * Extract the 32-hex trace ID from a W3C traceparent header. Format:
+ * `00-<32-hex>-<16-hex>-<2-hex>`. Returns undefined for malformed
+ * input — never throws (errors during error construction would be
+ * truly miserable).
+ */
+function extractTraceId(traceparent: string): string | undefined {
+  const parts = traceparent.split('-');
+  if (parts.length < 3) return undefined;
+  const traceId = parts[1];
+  if (!traceId || !/^[0-9a-f]{32}$/i.test(traceId)) return undefined;
+  return traceId;
+}