@openwop/openwop 1.8.0 → 2.0.0

package/src/run-helpers.ts

@@ -4,7 +4,7 @@
  * declared in `types.ts`.
  *
  * **Why these live here.** `types.ts` declares the canonical wire shapes
- * (mirroring `api/openapi.yaml` + `schemas/run-snapshot.schema.json`).
+ * (mirroring `api/v2/openapi.yaml` + `schemas/v2/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,
@@ -28,7 +28,8 @@
  * @module @openwop/openwop/run-helpers
  */
 
-import type { RunStatus } from './types.js';
+import type { RunStatus, VendorErrorCode } from './types.js';
+import { ERROR_CODES, RETRIABLE_ERROR_CODES, VENDOR_ERROR_CODE_PATTERN, type ErrorCode } from './generated.js';
 
 // ─── Run statuses ────────────────────────────────────────────────────────
 
@@ -85,92 +86,31 @@ export function isTerminalRunStatus(status: RunStatus | string): boolean {
 // ─── 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`.
+ * The v2 error registry (`spec/v2/errors.json`, errors.md): every code a v2
+ * host may return in `ErrorEnvelope.error`, generated into `generated.ts`.
+ * Kept under the 1.x name for call-site parity; `ERROR_CODES` is the same
+ * array.
  */
-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',
+export const HTTP_ERROR_CODES = ERROR_CODES;
 
-  // Streaming / protocol negotiation
-  'unsupported_stream_mode',
-  'force_engine_version_forbidden',
-  'mock_provider_forbidden',
+export type HttpErrorCode = ErrorCode;
 
-  // Capability / credential negotiation
-  'capability_not_provided',
-  'capability_required',
-  'credential_required',
-  'credential_forbidden',
-  'credential_unavailable',
-
-  // Node-pack lifecycle (registry + lockfile) per node-packs.md §"Dependency resolution + lockfile"
-  'pack_integrity_mismatch',
-  'pack_signature_invalid',
-  'pack_peer_dependency_missing',
-  'pack_lockfile_incomplete',
-  'pack_version_not_found',
-
-  // HITL / interrupt callbacks
-  'interrupt_not_found',
-  'approval_token_invalid',
-  'approval_token_expired',
-  'approval_token_consumed',
-
-  // Phase H.1″ — AI provider policy enforcement per
-  // capabilities.md §"aiProviders.policies".
-  'provider_policy_denied',
-
-  // Phase H.2 — MCP client error codes.
-  'mcp_server_not_configured',
-  'mcp_timeout',
-  'mcp_network_error',
-  'mcp_server_error',
-  'mcp_protocol_error',
-  'mcp_tool_error',
-
-  // Phase H.3 — HTTP client error codes.
-  'http_url_rejected',
-  'http_timeout',
-  'http_network_error',
-  'http_unexpected_status',
-
-  // Phase H webhook codes (restored to spec-de-facto per Python host
-  // close-out and conformance webhook-negative.test.ts).
-  'webhook_url_rejected',
-  'subscription_not_found',
+/** Type guard that narrows a string to a registered protocol {@link ErrorCode}. */
+export function isErrorCode(value: unknown): value is ErrorCode {
+  return typeof value === 'string' && (ERROR_CODES as readonly string[]).includes(value);
+}
 
-  // Generic server failure
-  'internal_error',
-] as const;
+/** 1.x name for {@link isErrorCode}. */
+export const isHttpErrorCode = isErrorCode;
 
-export type HttpErrorCode = (typeof HTTP_ERROR_CODES)[number];
+/** True for the registry rows marked `retriable: true`; retry timing lives in `Retry-After` only (RFC 0171 §B.2). */
+export function isRetriableErrorCode(value: unknown): value is (typeof RETRIABLE_ERROR_CODES)[number] {
+  return typeof value === 'string' && (RETRIABLE_ERROR_CODES as readonly string[]).includes(value);
+}
 
-/**
- * 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);
+/** True for a well-formed vendor code (`<org>.<name>`, `openwop.` reserved); does not check org registration. */
+export function isVendorErrorCode(value: unknown): value is VendorErrorCode {
+  return typeof value === 'string' && VENDOR_ERROR_CODE_PATTERN.test(value);
 }
 
 // ─── Run error codes ─────────────────────────────────────────────────────
@@ -221,6 +161,9 @@ export const RUN_ERROR_CODES = [
   'node_execution_failed',
   'external_call_failed',
   'recursion_limit_exceeded',
+  'run_timeout',
+  'loop_limit_exceeded',
+  'envelope_refusal',
   'capability_not_provided',
 
   // Approval
@@ -253,9 +196,8 @@ export function isRunErrorCode(value: unknown): value is RunErrorCode {
  *   - `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).
+ *     request failed. `error` is a registered {@link ErrorCode} or a vendor
+ *     code (`<org>.<name>`).
  *
  * The shapes share `message` and `details` but diverge on the code field
  * name (`code` vs `error`) by design — they represent different layers.

package/src/sse.ts

@@ -1,41 +1,58 @@
 /**
- * SSE consumer for `GET /v1/runs/{runId}/events`. Async-iterable shape so
- * consumers can write `for await (const event of client.runs.events(...))`.
+ * SSE consumers for `GET /runs/{runId}/events` (the `runEvents` channel) and
+ * `GET /host/events` (the `hostEvents` channel) — events.md §SSE frames.
+ * 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.
+ * Parses `event:` / `data:` / `id:` lines per the WHATWG EventSource
+ * grammar. 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.
+ * Cancellable: pass an AbortSignal via options, or break out of the
+ * for-await loop and the underlying connection is torn down.
  */
 
-import type { RunEventDoc, StreamMode } from './types.js';
+import type { HostEventDoc, 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.
+   * Single mode (e.g., 'updates') OR array of modes (mixed mode, e.g.,
+   * ['updates', 'messages']). Arrays serialize to a comma-separated
+   * `?streamMode=updates,messages` query (events.md §The events channel).
    */
   readonly streamMode?: StreamMode | readonly StreamMode[];
+  /** `Last-Event-ID` — the host resumes at the next sequence and never re-emits the resumption point. */
   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.
+   * Batching hint (0..5000). The host accumulates events into one
+   * `event: batch` frame whose `data:` is an array of `RunEventDoc`; the SDK
+   * flattens the batch back into individual yields.
    */
   readonly bufferMs?: number;
 }
 
+export interface HostEventsStreamOptions {
+  /** `Last-Event-ID` for resumption. */
+  readonly lastEventId?: string;
+  readonly signal?: AbortSignal;
+  /**
+   * The channel address. Default `/host/events`; a host MAY declare another
+   * under `heartbeat.deliveryChannel` (capabilities.md).
+   */
+  readonly path?: string;
+}
+
 export interface EventsStreamContext {
   readonly baseUrl: string;
   readonly apiKey: string;
+  /** The `OpenWOP-Version` value sent on the subscribe request (RFC 0172 §A.3). */
+  readonly protocolVersion: string;
+  /** Optional fetch implementation override. Defaults to global `fetch`. */
+  readonly fetch?: typeof fetch;
 }
 
-export async function* streamEvents(
+/** Subscribe to a run's event stream. Yields each `RunEventDoc` until the host closes after the terminal event. */
+export function streamEvents(
   ctx: EventsStreamContext,
   runId: string,
   opts: EventsStreamOptions = {},
@@ -50,12 +67,30 @@ export async function* streamEvents(
     params.set('bufferMs', String(opts.bufferMs));
   }
   const qs = params.toString();
-  const url = `${ctx.baseUrl}/v1/runs/${encodeURIComponent(runId)}/events${qs ? `?${qs}` : ''}`;
+  const path = `/runs/${encodeURIComponent(runId)}/events${qs ? `?${qs}` : ''}`;
+  return streamSse<RunEventDoc>(ctx, path, opts);
+}
+
+/** Subscribe to the host events channel (heartbeat messages; content-free of run data). */
+export function streamHostEvents(
+  ctx: EventsStreamContext,
+  opts: HostEventsStreamOptions = {},
+): AsyncGenerator<HostEventDoc, void, void> {
+  return streamSse<HostEventDoc>(ctx, opts.path ?? '/host/events', opts);
+}
+
+async function* streamSse<T>(
+  ctx: EventsStreamContext,
+  path: string,
+  opts: { readonly lastEventId?: string; readonly signal?: AbortSignal },
+): AsyncGenerator<T, void, void> {
+  const url = `${ctx.baseUrl}${path}`;
 
   const headers: Record<string, string> = {
     Accept: 'text/event-stream',
     Authorization: `Bearer ${ctx.apiKey}`,
     'Cache-Control': 'no-cache',
+    'OpenWOP-Version': ctx.protocolVersion,
   };
   if (opts.lastEventId) {
     headers['Last-Event-ID'] = opts.lastEventId;
@@ -68,7 +103,8 @@ export async function* streamEvents(
     else externalSignal.addEventListener('abort', () => internalAbort.abort(), { once: true });
   }
 
-  const res = await fetch(url, { method: 'GET', headers, signal: internalAbort.signal });
+  const doFetch = ctx.fetch ?? fetch;
+  const res = await doFetch(url, { method: 'GET', headers, signal: internalAbort.signal });
   if (!res.ok || res.body === null) {
     throw new Error(`SSE subscribe failed: HTTP ${res.status}`);
   }
@@ -78,36 +114,29 @@ export async function* streamEvents(
   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.
+   * Flush the buffered frame. Returns 0 elements when the buffer is empty or
+   * non-JSON (skip), 1 element for a normal `event: <type>` frame, N for an
+   * `event: batch` frame whose `data:` is a JSON array.
    */
-  const flushAndYield = (): RunEventDoc[] => {
+  const flushAndYield = (): T[] => {
     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[];
+        return parsed as T[];
       }
-      // Normal single-event payload.
-      return [parsed as RunEventDoc];
+      return [parsed as T];
     } catch {
-      // Skip non-JSON events (keep-alive payloads, vendor extensions).
+      // Skip non-JSON frames (keep-alive payloads, vendor extensions).
       return [];
     }
   };
@@ -140,15 +169,13 @@ export async function* streamEvents(
           case 'data':
             pendingData.push(fieldValue);
             break;
-          case 'id':
-            pendingId = fieldValue;
-            break;
           default:
+            // `id:` is the sequence; the consumer reads it from the document itself.
             break;
         }
       }
     }
-    // Flush any final unterminated event.
+    // Flush any final unterminated frame.
     for (const final of flushAndYield()) yield final;
   } finally {
     try {
@@ -158,10 +185,4 @@ export async function* streamEvents(
     }
     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;
 }