@openwop/openwop 1.1.1 → 1.1.3

package/src/client.ts

@@ -22,11 +22,25 @@ import {
   type ErrorEnvelope,
   type ForkRunRequest,
   type ForkRunResponse,
+  type GetPromptRequest,
   type InterruptByTokenInspection,
+  type DebugBundle,
+  type DebugBundleOptions,
+  type ListPromptsRequest,
+  type ListPromptsResponse,
+  type PromptTemplate,
+  type RegisterWebhookRequest,
+  type RegisterWebhookResponse,
+  type PauseRunRequest,
+  type PauseRunResponse,
   type PollEventsResponse,
+  type RenderPromptRequest,
+  type RenderPromptResponse,
   type ResolveInterruptByTokenResponse,
   type ResolveInterruptRequest,
   type ResolveInterruptResponse,
+  type ResumeRunRequest,
+  type ResumeRunResponse,
   type RunEventDoc,
   type RunSnapshot,
 } from './types.js';
@@ -106,6 +120,33 @@ export class OpenwopClient {
         path: `/v1/runs/${encodeURIComponent(runId)}`,
       }),
 
+    /**
+     * Fetch the portable JSON diagnostic export for a single run per
+     * `spec/v1/debug-bundle.md`. The bundle's `redactionMode` reflects
+     * the host's advertised `capabilities.compliance.defaultMode`; the
+     * caller MUST treat masked/omitted/hashed fields as the
+     * spec-canonical value. The `truncated` + `truncatedReason` fields
+     * indicate the host hit its size cap.
+     *
+     * Returns `null` when the host doesn't advertise
+     * `capabilities.debugBundle.supported: true` (the endpoint returns
+     * 404 in that case per `debug-bundle.md` §"Authorization").
+     */
+    debugBundle: async (runId: string, opts: DebugBundleOptions = {}): Promise<DebugBundle | null> => {
+      const params = new URLSearchParams();
+      if (opts.maxEvents !== undefined) params.set('maxEvents', String(opts.maxEvents));
+      const query = params.toString();
+      const path = `/v1/runs/${encodeURIComponent(runId)}/debug-bundle${query ? `?${query}` : ''}`;
+      try {
+        return await this.#request<DebugBundle>({ method: 'GET', path });
+      } catch (err) {
+        // Host doesn't advertise the capability → 404. Surface as null so callers
+        // can branch on capability discovery without try/catch.
+        if (err instanceof Error && /\b404\b/.test(err.message)) return null;
+        throw err;
+      }
+    },
+
     cancel: (
       runId: string,
       body: CancelRunRequest = {},
@@ -118,6 +159,30 @@ export class OpenwopClient {
         headers: this.#mutationHeaders(opts),
       }),
 
+    pause: (
+      runId: string,
+      body: PauseRunRequest = {},
+      opts: MutationOptions = {},
+    ): Promise<PauseRunResponse> =>
+      this.#request<PauseRunResponse>({
+        method: 'POST',
+        path: `/v1/runs/${encodeURIComponent(runId)}:pause`,
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    resume: (
+      runId: string,
+      body: ResumeRunRequest = {},
+      opts: MutationOptions = {},
+    ): Promise<ResumeRunResponse> =>
+      this.#request<ResumeRunResponse>({
+        method: 'POST',
+        path: `/v1/runs/${encodeURIComponent(runId)}:resume`,
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
     /**
      * Bulk-cancel a set of in-flight runs in a single request per
      * `rest-endpoints.md` §"POST /v1/runs:bulk-cancel" (closes R1).
@@ -229,6 +294,159 @@ export class OpenwopClient {
       ),
   };
 
+  // ── Webhook subscriptions (per spec/v1/webhooks.md) ─────────────────────
+  readonly webhooks = {
+    /**
+     * Register a webhook subscription. Server signs deliveries with
+     * HMAC-SHA256 over `${timestamp}.${rawBody}` using the
+     * registration-time secret per `spec/v1/webhooks.md` §"Signature
+     * recipe". The secret is returned ONCE in the response — store it
+     * server-side for verification; the host cannot recover it.
+     */
+    register: (
+      body: RegisterWebhookRequest,
+      opts: MutationOptions = {},
+    ): Promise<RegisterWebhookResponse> =>
+      this.#request<RegisterWebhookResponse>({
+        method: 'POST',
+        path: '/v1/webhooks',
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    /**
+     * Unregister a webhook subscription. Returns void on success;
+     * throws `WopError` with `subscription_not_found` on unknown
+     * subscriptionId.
+     */
+    unregister: async (subscriptionId: string): Promise<void> => {
+      await this.#request<unknown>({
+        method: 'DELETE',
+        path: `/v1/webhooks/${encodeURIComponent(subscriptionId)}`,
+      });
+    },
+  };
+
+  // ── Prompt library (RFC 0028; gated on capabilities.prompts.*) ──
+  //
+  // Read endpoints (list, get, render) gate on
+  // `capabilities.prompts.endpointsSupported: true`. Mutating endpoints
+  // (create, update, delete) additionally require
+  // `capabilities.prompts.mutableLibrary: true`. Hosts that don't advertise
+  // the relevant capability return `501 capability_not_provided`; the SDK
+  // surfaces that as a `WopError`. Clients SHOULD pre-flight via
+  // `getCapabilities()` before calling.
+  //
+  // NOTE: `capabilities.prompts.supported: true` (without
+  // `endpointsSupported: true`) ONLY gates node-execution PromptRef
+  // resolution per RFC 0027 Phase A; it does NOT imply these endpoints are
+  // available. See spec/v1/prompts.md §"Capability advertisement" for the
+  // two-axis gating split.
+  readonly prompts = {
+    /**
+     * List prompt templates available to the caller per RFC 0028 §A
+     * (operationId `listPromptTemplates`). Supports kind / tag / modelClass
+     * / source filters + opaque cursor pagination.
+     */
+    list: (req: ListPromptsRequest = {}): Promise<ListPromptsResponse> => {
+      const search = new URLSearchParams();
+      if (req.kind) search.set('kind', req.kind);
+      if (req.tag) search.set('tag', req.tag);
+      if (req.modelClass) search.set('modelClass', req.modelClass);
+      if (req.source) search.set('source', req.source);
+      if (req.cursor) search.set('cursor', req.cursor);
+      if (req.limit !== undefined) search.set('limit', String(req.limit));
+      const query = search.toString();
+      return this.#request<ListPromptsResponse>({
+        method: 'GET',
+        path: `/v1/prompts${query ? `?${query}` : ''}`,
+      });
+    },
+
+    /**
+     * Fetch a single PromptTemplate by id per RFC 0028 §A
+     * (operationId `getPromptTemplate`). Optionally pin a SemVer
+     * `version`; supply `libraryId` to disambiguate when multiple installed
+     * packs ship the same templateId.
+     */
+    get: (req: GetPromptRequest): Promise<PromptTemplate> => {
+      const search = new URLSearchParams();
+      if (req.version) search.set('version', req.version);
+      if (req.libraryId) search.set('libraryId', req.libraryId);
+      const query = search.toString();
+      return this.#request<PromptTemplate>({
+        method: 'GET',
+        path: `/v1/prompts/${encodeURIComponent(req.templateId)}${query ? `?${query}` : ''}`,
+      });
+    },
+
+    /**
+     * Render a PromptTemplate with supplied variable bindings per RFC 0028
+     * §A (operationId `renderPromptTemplate`). Returns composed body +
+     * sha256 hash + per-variable hashes. The deterministic-hash invariant
+     * (RFC 0028 §A) requires the `hash` to match what a matching
+     * `prompt.composed` event would carry at dispatch time. Does NOT
+     * dispatch an LLM call. Secret-source variable values MUST be supplied
+     * as `[REDACTED:<credentialRef>]` markers per
+     * SECURITY/threat-model-secret-leakage.md §SR-1.
+     */
+    render: (req: RenderPromptRequest): Promise<RenderPromptResponse> => {
+      return this.#request<RenderPromptResponse>({
+        method: 'POST',
+        path: '/v1/prompts:render',
+        body: req,
+      });
+    },
+
+    /**
+     * Create a new user-source PromptTemplate per RFC 0028 §A
+     * (operationId `createPromptTemplate`). Mutating endpoint —
+     * requires `capabilities.prompts.mutableLibrary: true`. Supports
+     * `Idempotency-Key` per the standard `MutationOptions` pattern.
+     */
+    create: (template: PromptTemplate, opts: MutationOptions = {}): Promise<void> => {
+      return this.#request<void>({
+        method: 'POST',
+        path: '/v1/prompts',
+        body: template,
+        headers: this.#mutationHeaders(opts),
+      });
+    },
+
+    /**
+     * Replace an existing user-source PromptTemplate per RFC 0028 §A
+     * (operationId `updatePromptTemplate`). Submitted SemVer MUST be
+     * strictly greater than stored. Mutating endpoint — requires
+     * `capabilities.prompts.mutableLibrary: true`. Pack-sourced and
+     * host-built-in templates are read-only (host returns 403).
+     */
+    update: (
+      templateId: string,
+      template: PromptTemplate,
+      opts: MutationOptions = {},
+    ): Promise<PromptTemplate> => {
+      return this.#request<PromptTemplate>({
+        method: 'PUT',
+        path: `/v1/prompts/${encodeURIComponent(templateId)}`,
+        body: template,
+        headers: this.#mutationHeaders(opts),
+      });
+    },
+
+    /**
+     * Delete a user-source PromptTemplate per RFC 0028 §A
+     * (operationId `deletePromptTemplate`). Mutating endpoint —
+     * requires `capabilities.prompts.mutableLibrary: true`. Pack-sourced
+     * and host-built-in templates are read-only (host returns 403).
+     */
+    delete: (templateId: string): Promise<void> => {
+      return this.#request<void>({
+        method: 'DELETE',
+        path: `/v1/prompts/${encodeURIComponent(templateId)}`,
+      });
+    },
+  };
+
   // ── Audit-log integrity (gated on openwop-audit-log-integrity profile) ──
   readonly audit = {
     /**

package/src/cost-attribution.ts

@@ -0,0 +1,72 @@
+/**
+ * Cost-attribution allowlist + sanitizer helpers
+ * (`spec/v1/observability.md §"Cost attribution attributes"`).
+ *
+ * The spec MUSTs that hosts emitting `openwop.cost.*` OTel span attrs
+ * route them through an allowlist sanitizer that drops any attribute
+ * name outside the canonical set AND any non-primitive value. The
+ * `cost-attribution-allowlist-redaction` SECURITY invariant + the
+ * `cost-attribution.test.ts` conformance scenario are the public test
+ * surface; this module is the SDK-side helper that independent hosts
+ * (TypeScript / Python / Go) can share so the allowlist has a single
+ * source of truth instead of being re-derived in each runtime.
+ *
+ * Why this lives in the SDK and not just the conformance suite:
+ * implementations need the allowlist at HOST EMIT TIME (before spans
+ * are written). Importing from `@openwop/openwop` keeps the runtime
+ * + the conformance assertion in lockstep — if a future RFC adds an
+ * eighth attribute, one PR updates the constant and both surfaces
+ * pick it up.
+ *
+ * @see spec/v1/observability.md §"Cost attribution attributes"
+ * @see SECURITY/invariants.yaml row `cost-attribution-allowlist-redaction`
+ * @see conformance/src/scenarios/cost-attribution.test.ts
+ */
+
+/** Canonical allowlist of cost-attribute names. Mutating this list is
+ *  a wire-shape change — needs an RFC. */
+export const OPENWOP_COST_ATTRIBUTE_NAMES = [
+  'openwop.cost.tokens.input',
+  'openwop.cost.tokens.output',
+  'openwop.cost.tokens.total',
+  'openwop.cost.usd',
+  'openwop.cost.currency',
+  'openwop.cost.estimated',
+  'openwop.cost.provider',
+] as const;
+
+/** Union of the canonical attribute names. Useful for typed
+ *  sanitizer outputs in callers that pin the shape. */
+export type OpenwopCostAttributeName = (typeof OPENWOP_COST_ATTRIBUTE_NAMES)[number];
+
+const ALLOWLIST: ReadonlySet<string> = new Set<string>(OPENWOP_COST_ATTRIBUTE_NAMES);
+
+/** Pure-function sanitizer. Returns a NEW object containing only
+ *  allowlisted keys with primitive-typed values (number / string /
+ *  boolean). Drops anything else — non-allowlisted keys, nested
+ *  objects, arrays, functions, symbols, null, undefined.
+ *
+ *  Callers SHOULD invoke this immediately before writing cost attrs
+ *  to an OTel span:
+ *
+ *  ```ts
+ *  import { sanitizeCostAttributes } from '@openwop/openwop';
+ *  for (const [k, v] of Object.entries(sanitizeCostAttributes(rawAttrs))) {
+ *    span.setAttribute(k, v);
+ *  }
+ *  ```
+ *
+ *  The reference workflow-engine host wires this via
+ *  `apps/workflow-engine/backend/typescript/src/observability/costEmitter.ts`. */
+export function sanitizeCostAttributes(
+  input: Record<string, unknown>,
+): Record<string, number | string | boolean> {
+  const out: Record<string, number | string | boolean> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (!ALLOWLIST.has(key)) continue;
+    if (typeof value === 'number' || typeof value === 'string' || typeof value === 'boolean') {
+      out[key] = value;
+    }
+  }
+  return out;
+}

package/src/envelope-directive.ts

@@ -0,0 +1,110 @@
+/**
+ * envelopeDirective — RFC 0030 §A `reasoning`-field prompt directive synthesis.
+ *
+ * Hosts that advertise `capabilities.envelopes.reasoning.supported: true`
+ * with `promptDirective: "advisory"` or `"mandatory"` inject a system-prompt
+ * directive instructing the model to populate the OPTIONAL `reasoning` field
+ * on envelope payload schemas that carry it. The directive is informational
+ * — hosts MUST NOT reject envelopes where `reasoning` is absent regardless
+ * of `promptDirective` strength (RFC 0030 §A).
+ *
+ * The directive fires only when the envelope's `responseSchema` declares a
+ * top-level `reasoning` property. Schemas without `reasoning` (e.g.,
+ * `schema.response` per RFC 0030 §A) do NOT receive the directive.
+ *
+ * Honest separation of concerns:
+ *   - This module decides WHEN to inject (schema has `reasoning`).
+ *   - The caller decides WHETHER to inject (read `promptDirective` from
+ *     the host's discovery advertisement).
+ *   - The model decides whether to ACTUALLY populate the field (the spec
+ *     forbids rejecting envelopes where `reasoning` is absent).
+ *
+ * **Operational note on `"mandatory"`** (per RFC 0030 §A 2026-05-21
+ * amendment). Strict-output models may honor the mandatory wording
+ * literally and refuse mid-emission when reasoning would be vacuous.
+ * Hosts SHOULD prefer `"advisory"` unless empirical testing against the
+ * active model class confirms `"mandatory"` doesn't trigger refusals.
+ *
+ * @see RFCS/0030-envelope-reasoning-and-tier-one-subset.md §A
+ * @see spec/v1/ai-envelope.md §"Reasoning field (normative)"
+ */
+
+/**
+ * The strength of the host's `reasoning`-directive prompt injection.
+ *
+ * `"off"`      — no directive injected. Caller skips this module entirely.
+ * `"advisory"` — directive is suggestive ("populate `reasoning` with your
+ *                analytical process if the schema permits it"). The
+ *                spec-recommended default per RFC 0030 §C.
+ * `"mandatory"` — directive is firm ("you MUST populate `reasoning` before
+ *                 emitting the structured fields"). Hosts SHOULD prefer
+ *                 `"advisory"` unless model-class-specific testing shows
+ *                 `"mandatory"` is safe.
+ *
+ * Both `"advisory"` and `"mandatory"` are prompt-injection postures, NOT
+ * wire-level refusal contracts — the host accepts envelopes regardless of
+ * whether `reasoning` is populated (RFC 0030 §A normative MUST NOT).
+ */
+export type ReasoningDirectiveStrength = 'off' | 'advisory' | 'mandatory';
+
+/**
+ * Build the directive string to append to the system prompt, OR `null` if
+ * the schema does not declare a top-level `reasoning` property.
+ *
+ * Callers append the returned string to the existing system prompt with a
+ * separating newline. When `strength === 'off'`, callers SHOULD short-circuit
+ * before invoking this helper (returning `null` here is treated as "no
+ * applicable schema," not "directive disabled").
+ *
+ * The helper inspects only the top-level `properties.reasoning` slot.
+ * Nested `reasoning` fields (e.g., inside an `anyOf` branch's payload) are
+ * not auto-detected — vendor-kind authors who want per-branch directives
+ * synthesize their own.
+ *
+ * @example
+ * ```ts
+ * import { buildReasoningDirective } from '@openwop/openwop';
+ *
+ * const directive = buildReasoningDirective(
+ *   { type: 'object', properties: { reasoning: { type: 'string' }, ... } },
+ *   'advisory',
+ * );
+ * // directive is a string ~80 words; null when schema lacks `reasoning`
+ * const systemPrompt = [originalSystemPrompt, schemaHint, directive]
+ *   .filter((s): s is string => Boolean(s))
+ *   .join('\n\n');
+ * ```
+ */
+export function buildReasoningDirective(
+  responseSchema: unknown,
+  strength: ReasoningDirectiveStrength,
+): string | null {
+  if (strength === 'off') return null;
+  if (!responseSchema || typeof responseSchema !== 'object') return null;
+
+  const schema = responseSchema as { properties?: unknown };
+  const properties = schema.properties;
+  if (!properties || typeof properties !== 'object') return null;
+
+  const reasoningProp = (properties as { reasoning?: unknown }).reasoning;
+  if (!reasoningProp || typeof reasoningProp !== 'object') return null;
+
+  if (strength === 'mandatory') {
+    return [
+      'BEFORE emitting the structured fields, populate the `reasoning` property with your analytical',
+      'process — explain how you derived each structured field, what assumptions you made, and what',
+      'risks or alternative interpretations you considered. The `reasoning` field is REQUIRED in your',
+      'output; do not skip it. (Note: the host accepts envelopes where `reasoning` is absent per',
+      'RFC 0030 §A, but for this dispatch the host expects it populated.)',
+    ].join(' ');
+  }
+
+  // strength === 'advisory'
+  return [
+    'If your response schema declares a `reasoning` property, populate it as the first field with',
+    'your analytical process — explain how you derived each structured field. Per Tam et al. (arXiv',
+    "2408.02442), models constrained to strict JSON output suffer reasoning-quality collapse when",
+    'no reasoning slot exists; use this field to think before emitting the structured payload. The',
+    'host accepts envelopes where `reasoning` is absent — populate it when it improves clarity.',
+  ].join(' ');
+}

package/src/event-helpers.ts

@@ -0,0 +1,238 @@
+/**
+ * Typed helpers for the `agent.*` event family (RFC 0002 §B + RFC 0024).
+ *
+ * Two layers:
+ *
+ *   1. **Type guards** (`isAgentReasoned`, `isAgentReasoningDelta`, etc.)
+ *      — discriminator-based predicates that narrow `RunEventDoc` to a
+ *      `TypedRunEvent<TPayload>` inside the guarded branch. Use these
+ *      when you're iterating events yourself (e.g., inside a
+ *      `for await (const ev of streamEvents(...))` loop) and want
+ *      compile-time-narrowed access to the payload.
+ *
+ *   2. **High-level subscription helper** (`subscribeToAgentReasoning`)
+ *      — fan-outs the `streamEvents()` generator into typed callbacks
+ *      (`onDelta`, `onClosed`). Composes with the existing
+ *      `streamEvents` SSE consumer; cleanup via the returned
+ *      `Unsubscribe` function aborts the underlying fetch.
+ *
+ * Forward-compat: `RunEventDoc.type` is intentionally `string`-typed
+ * (not a closed union) per `COMPATIBILITY.md §2.1` — consumers MUST
+ * tolerate unknown event types. The type guards here only narrow when
+ * the discriminator AND the required payload fields are present; they
+ * return `false` for malformed or unknown events.
+ *
+ * @see schemas/run-event-payloads.schema.json
+ * @see RFCS/0002-agent-identity-and-reasoning-events.md
+ * @see RFCS/0024-agent-reasoning-streaming.md
+ */
+
+import { streamEvents, type EventsStreamContext, type EventsStreamOptions } from './sse.js';
+import type {
+  AgentDecidedPayload,
+  AgentHandoffPayload,
+  AgentReasonedPayload,
+  AgentReasoningDeltaPayload,
+  AgentToolCalledPayload,
+  AgentToolReturnedPayload,
+  RunEventDoc,
+  TypedRunEvent,
+} from './types.js';
+
+// ─── Type guards ────────────────────────────────────────────────────────
+
+function hasStringField(
+  payload: unknown,
+  field: string,
+): payload is Record<string, unknown> {
+  return (
+    payload !== null &&
+    typeof payload === 'object' &&
+    typeof (payload as Record<string, unknown>)[field] === 'string'
+  );
+}
+
+/** `agent.reasoned` (RFC 0002 §B). Narrows when `type` matches AND
+ *  payload carries the required `agentId` + `reasoning` strings. */
+export function isAgentReasoned(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<AgentReasonedPayload> {
+  return (
+    ev.type === 'agent.reasoned' &&
+    hasStringField(ev.payload, 'agentId') &&
+    hasStringField(ev.payload, 'reasoning')
+  );
+}
+
+/** `agent.reasoning.delta` (RFC 0024). Narrows when `type` matches AND
+ *  payload carries the required `agentId` + `delta` strings + numeric
+ *  `sequence`. */
+export function isAgentReasoningDelta(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<AgentReasoningDeltaPayload> {
+  if (ev.type !== 'agent.reasoning.delta') return false;
+  if (!hasStringField(ev.payload, 'agentId')) return false;
+  if (!hasStringField(ev.payload, 'delta')) return false;
+  const seq = (ev.payload as Record<string, unknown>).sequence;
+  return typeof seq === 'number' && Number.isInteger(seq) && seq >= 0;
+}
+
+/** `agent.toolCalled` (RFC 0002 §B). */
+export function isAgentToolCalled(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<AgentToolCalledPayload> {
+  return (
+    ev.type === 'agent.toolCalled' &&
+    hasStringField(ev.payload, 'agentId') &&
+    hasStringField(ev.payload, 'toolName') &&
+    hasStringField(ev.payload, 'callId')
+  );
+}
+
+/** `agent.toolReturned` (RFC 0002 §B). Pairs with `agent.toolCalled`
+ *  via `callId`; `outcome` and `error` are mutually exclusive but the
+ *  guard doesn't enforce that (callers inspect after narrowing). */
+export function isAgentToolReturned(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<AgentToolReturnedPayload> {
+  return (
+    ev.type === 'agent.toolReturned' &&
+    hasStringField(ev.payload, 'agentId') &&
+    hasStringField(ev.payload, 'toolName') &&
+    hasStringField(ev.payload, 'callId')
+  );
+}
+
+/** `agent.handoff` (RFC 0002 §B). Note the distinct field names —
+ *  `fromAgentId` / `toAgentId`, NOT a single `agentId`. */
+export function isAgentHandoff(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<AgentHandoffPayload> {
+  return (
+    ev.type === 'agent.handoff' &&
+    hasStringField(ev.payload, 'fromAgentId') &&
+    hasStringField(ev.payload, 'toAgentId')
+  );
+}
+
+/** `agent.decided` (RFC 0002 §B). `decision` is `unknown` per the
+ *  schema (host-specific shape); guard only validates `agentId` +
+ *  the presence of a `decision` key. */
+export function isAgentDecided(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<AgentDecidedPayload> {
+  return (
+    ev.type === 'agent.decided' &&
+    hasStringField(ev.payload, 'agentId') &&
+    ev.payload !== null &&
+    typeof ev.payload === 'object' &&
+    'decision' in (ev.payload as Record<string, unknown>)
+  );
+}
+
+// ─── High-level subscription helper ─────────────────────────────────────
+
+/** Returned by {@link subscribeToAgentReasoning}. Call to cancel the
+ *  underlying SSE subscription. Idempotent — repeated calls are no-ops. */
+export type Unsubscribe = () => void;
+
+/** Per-callback signatures for {@link subscribeToAgentReasoning}. All
+ *  callbacks are optional; the helper only invokes those provided.
+ *  Callback exceptions are caught + reported via `onError` (when
+ *  provided) so one bad handler doesn't tear down the stream. */
+export interface AgentReasoningCallbacks {
+  /** Fired for each `agent.reasoning.delta` event in arrival order
+   *  (RFC 0024). `sequence` starts at 0 and increments by 1 per delta
+   *  within a single reasoning block. */
+  onDelta?: (payload: AgentReasoningDeltaPayload, ev: TypedRunEvent<AgentReasoningDeltaPayload>) => void | Promise<void>;
+  /** Fired once per closed reasoning block with the full
+   *  authoritative content. Consumers that only care about the final
+   *  trace can subscribe just to this. */
+  onClosed?: (payload: AgentReasonedPayload, ev: TypedRunEvent<AgentReasonedPayload>) => void | Promise<void>;
+  /** Fired when the SSE stream ends cleanly (server closed or run
+   *  reached terminal status). */
+  onEnd?: () => void;
+  /** Fired when the stream fails OR a callback throws. The helper
+   *  catches handler exceptions so a thrown error in `onDelta` doesn't
+   *  tear down the whole subscription; the original error is surfaced
+   *  here. */
+  onError?: (err: Error) => void;
+}
+
+/**
+ * Subscribe to the reasoning event sub-stream for a single run.
+ * Convenience wrapper over `streamEvents()` that dispatches the two
+ * RFC 0024 event types into typed callbacks.
+ *
+ * Returns immediately; the SSE consumption runs as a detached async
+ * task in the background. Call the returned `Unsubscribe` to cancel.
+ *
+ * @example
+ * ```ts
+ * const stop = subscribeToAgentReasoning(ctx, runId, {
+ *   onDelta: ({ delta, sequence }) => process.stdout.write(delta),
+ *   onClosed: ({ reasoning }) => console.log('\nfinal:', reasoning),
+ * });
+ * // ...later
+ * stop();
+ * ```
+ */
+export function subscribeToAgentReasoning(
+  ctx: EventsStreamContext,
+  runId: string,
+  callbacks: AgentReasoningCallbacks,
+  options: Omit<EventsStreamOptions, 'signal'> = {},
+): Unsubscribe {
+  const abort = new AbortController();
+  let stopped = false;
+
+  const stop: Unsubscribe = () => {
+    if (stopped) return;
+    stopped = true;
+    abort.abort();
+  };
+
+  void (async () => {
+    try {
+      // streamModes default to 'updates' — agent.* events flow there
+      // per `spec/v1/stream-modes.md`.
+      const events = streamEvents(ctx, runId, {
+        ...options,
+        streamMode: options.streamMode ?? 'updates',
+        signal: abort.signal,
+      });
+
+      for await (const ev of events) {
+        if (stopped) break;
+        try {
+          if (isAgentReasoningDelta(ev)) {
+            await callbacks.onDelta?.(ev.payload, ev);
+          } else if (isAgentReasoned(ev)) {
+            await callbacks.onClosed?.(ev.payload, ev);
+          }
+          // Other event types ignored — forward-compat per
+          // COMPATIBILITY.md §2.1. Consumers that want them iterate
+          // streamEvents() directly.
+        } catch (handlerErr) {
+          // Handler exceptions: surface via onError but DO NOT tear
+          // down the stream. One bad handler shouldn't kill the rest.
+          callbacks.onError?.(
+            handlerErr instanceof Error
+              ? handlerErr
+              : new Error(String(handlerErr)),
+          );
+        }
+      }
+      if (!stopped) callbacks.onEnd?.();
+    } catch (streamErr) {
+      if (stopped) return; // intentional cancellation
+      callbacks.onError?.(
+        streamErr instanceof Error
+          ? streamErr
+          : new Error(String(streamErr)),
+      );
+    }
+  })();
+
+  return stop;
+}