@openwop/openwop 1.1.0 → 1.1.2

package/README.md

@@ -84,10 +84,14 @@ npx tsc --noEmit   # typecheck the SDK source
 | `GET /v1/runs/{id}/events` (SSE) | `client.runs.events(id, opts?)` (async iterable) |
 | `GET /v1/runs/{id}/events/poll` | `client.runs.pollEvents(id, opts?)` |
 | `POST /v1/runs/{id}/cancel` | `client.runs.cancel(id, body?)` |
+| `POST /v1/runs:bulk-cancel` | `client.runs.bulkCancel(body, opts?)` |
+| `POST /v1/runs/{id}:pause` | `client.runs.pause(id, body?, opts?)` |
+| `POST /v1/runs/{id}:resume` | `client.runs.resume(id, body?, opts?)` |
 | `POST /v1/runs/{id}:fork` | `client.runs.fork(id, body)` |
 | `POST /v1/runs/{id}/interrupts/{nodeId}` | `client.interrupts.resolveByRun(id, nodeId, body)` |
 | `GET /v1/interrupts/{token}` | `client.interrupts.inspectByToken(token)` |
 | `POST /v1/interrupts/{token}` | `client.interrupts.resolveByToken(token, body)` |
+| `GET /v1/audit/verify` | `client.audit.verify(fromSeq, toSeq)` |
 
 **Idempotency-Key** is supported via the `idempotencyKey` option on every mutation method.
 

package/dist/client.d.ts

@@ -8,7 +8,7 @@
  * ../../auth.md for credential format.
  */
 import { type EventsStreamOptions } from './sse.js';
-import { type AuditVerifyResult, type BulkCancelRunsRequest, type BulkCancelRunsResponse, type Capabilities, type CancelRunRequest, type CancelRunResponse, type CreateRunRequest, type CreateRunResponse, type ForkRunRequest, type ForkRunResponse, type InterruptByTokenInspection, type PollEventsResponse, type ResolveInterruptByTokenResponse, type ResolveInterruptRequest, type ResolveInterruptResponse, type RunEventDoc, type RunSnapshot } from './types.js';
+import { type AuditVerifyResult, type BulkCancelRunsRequest, type BulkCancelRunsResponse, type Capabilities, type CancelRunRequest, type CancelRunResponse, type CreateRunRequest, type CreateRunResponse, 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';
 export interface OpenwopClientOptions {
     /** Base URL of the openwop server, e.g., `https://api.example.com`. Trailing slash optional. */
     readonly baseUrl: string;
@@ -38,7 +38,22 @@ export declare class OpenwopClient {
     readonly runs: {
         create: (body: CreateRunRequest, opts?: MutationOptions) => Promise<CreateRunResponse>;
         get: (runId: string) => Promise<RunSnapshot>;
+        /**
+         * 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: (runId: string, opts?: DebugBundleOptions) => Promise<DebugBundle | null>;
         cancel: (runId: string, body?: CancelRunRequest, opts?: MutationOptions) => Promise<CancelRunResponse>;
+        pause: (runId: string, body?: PauseRunRequest, opts?: MutationOptions) => Promise<PauseRunResponse>;
+        resume: (runId: string, body?: ResumeRunRequest, opts?: MutationOptions) => Promise<ResumeRunResponse>;
         /**
          * Bulk-cancel a set of in-flight runs in a single request per
          * `rest-endpoints.md` §"POST /v1/runs:bulk-cancel" (closes R1).
@@ -78,6 +93,70 @@ export declare class OpenwopClient {
          */
         resolveByToken: (token: string, body: ResolveInterruptRequest, opts?: MutationOptions) => Promise<ResolveInterruptByTokenResponse>;
     };
+    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>;
+        /**
+         * Unregister a webhook subscription. Returns void on success;
+         * throws `WopError` with `subscription_not_found` on unknown
+         * subscriptionId.
+         */
+        unregister: (subscriptionId: string) => Promise<void>;
+    };
+    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>;
+        /**
+         * 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>;
+        /**
+         * 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>;
+        /**
+         * 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>;
+        /**
+         * 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>;
+        /**
+         * 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>;
+    };
     readonly audit: {
         /**
          * Verify the audit-log hash chain over `[fromSeq, toSeq]` per

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EAEtB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACvB,KAAK,+BAA+B,EACpC,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EAChB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,gGAAgG;IAChG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAUD,qBAAa,aAAa;;gBAMZ,IAAI,EAAE,oBAAoB;IAUtC,QAAQ,CAAC,SAAS;4BACE,OAAO,CAAC,YAAY,CAAC;uBAG1B,OAAO,CAAC,OAAO,CAAC;MAE7B;IAGF,QAAQ,CAAC,SAAS;0BACE,MAAM,KAAG,OAAO,CAAC,OAAO,CAAC;MAK3C;IAGF,QAAQ,CAAC,IAAI;uBACI,gBAAgB,SAAQ,eAAe,KAAQ,OAAO,CAAC,iBAAiB,CAAC;qBAQ3E,MAAM,KAAG,OAAO,CAAC,WAAW,CAAC;wBAOjC,MAAM,SACP,gBAAgB,SAChB,eAAe,KACpB,OAAO,CAAC,iBAAiB,CAAC;QAQ7B;;;;;;;;WAQG;2BAEK,qBAAqB,SACrB,eAAe,KACpB,OAAO,CAAC,sBAAsB,CAAC;sBASzB,MAAM,QACP,cAAc,SACd,eAAe,KACpB,OAAO,CAAC,eAAe,CAAC;4BASlB,MAAM,WACL;YAAE,YAAY,CAAC,EAAE,MAAM,CAAC;YAAC,cAAc,CAAC,EAAE,MAAM,CAAA;SAAE,KACzD,OAAO,CAAC,kBAAkB,CAAC;QAe9B;;;;WAIG;wBACa,MAAM,SAAQ,mBAAmB,KAAQ,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC;MAEhG;IAGF,QAAQ,CAAC,UAAU;8BAER,MAAM,UACL,MAAM,QACR,uBAAuB,SACvB,eAAe,KACpB,OAAO,CAAC,wBAAwB,CAAC;QAQpC;;;;;;WAMG;gCACqB,MAAM,KAAG,OAAO,CAAC,0BAA0B,CAAC;QASpE;;;;WAIG;gCAEM,MAAM,QACP,uBAAuB,SACvB,eAAe,KACpB,OAAO,CAAC,+BAA+B,CAAC;MAU3C;IAGF,QAAQ,CAAC,KAAK;QACZ;;;;;;;;;;WAUG;0BACe,MAAM,SAAS,MAAM,KAAG,OAAO,CAAC,iBAAiB,CAAC;MASpE;CAsEH"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -48,12 +48,53 @@ export class OpenwopClient {
             method: 'GET',
             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, opts = {}) => {
+            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({ 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, body = {}, opts = {}) => this.#request({
             method: 'POST',
             path: `/v1/runs/${encodeURIComponent(runId)}/cancel`,
             body,
             headers: this.#mutationHeaders(opts),
         }),
+        pause: (runId, body = {}, opts = {}) => this.#request({
+            method: 'POST',
+            path: `/v1/runs/${encodeURIComponent(runId)}:pause`,
+            body,
+            headers: this.#mutationHeaders(opts),
+        }),
+        resume: (runId, body = {}, opts = {}) => this.#request({
+            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).
@@ -127,6 +168,151 @@ export class OpenwopClient {
             headers: this.#mutationHeaders(opts),
         }, false),
     };
+    // ── Webhook subscriptions (per spec/v1/webhooks.md) ─────────────────────
+    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, opts = {}) => this.#request({
+            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) => {
+            await this.#request({
+                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.
+    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 = {}) => {
+            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({
+                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) => {
+            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({
+                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) => {
+            return this.#request({
+                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, opts = {}) => {
+            return this.#request({
+                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, template, opts = {}) => {
+            return this.#request({
+                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) => {
+            return this.#request({
+                method: 'DELETE',
+                path: `/v1/prompts/${encodeURIComponent(templateId)}`,
+            });
+        },
+    };
     // ── Audit-log integrity (gated on openwop-audit-log-integrity profile) ──
     audit = {
         /**

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAA4B,MAAM,UAAU,CAAC;AAClE,OAAO,EACL,QAAQ,GAmBT,MAAM,YAAY,CAAC;AA4BpB,MAAM,OAAO,aAAa;IACf,QAAQ,CAAS;IACjB,OAAO,CAAS;IAChB,MAAM,CAAe;IACrB,eAAe,CAAqB;IAE7C,YAAY,IAA0B;QACpC,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;QAC7E,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAC;QAC3E,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAChD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC;QAClC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,cAAc,CAAC;IAC7C,CAAC;IAED,wEAAwE;IAC/D,SAAS,GAAG;QACnB,YAAY,EAAE,GAA0B,EAAE,CACxC,IAAI,CAAC,QAAQ,CAAe,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,EAAE,EAAE,KAAK,CAAC;QAErF,OAAO,EAAE,GAAqB,EAAE,CAC9B,IAAI,CAAC,QAAQ,CAAU,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,KAAK,CAAC;KAC7E,CAAC;IAEF,wEAAwE;IAC/D,SAAS,GAAG;QACnB,GAAG,EAAE,CAAC,UAAkB,EAAoB,EAAE,CAC5C,IAAI,CAAC,QAAQ,CAAU;YACrB,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,iBAAiB,kBAAkB,CAAC,UAAU,CAAC,EAAE;SACxD,CAAC;KACL,CAAC;IAEF,wEAAwE;IAC/D,IAAI,GAAG;QACd,MAAM,EAAE,CAAC,IAAsB,EAAE,OAAwB,EAAE,EAA8B,EAAE,CACzF,IAAI,CAAC,QAAQ,CAAoB;YAC/B,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,UAAU;YAChB,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;SACrC,CAAC;QAEJ,GAAG,EAAE,CAAC,KAAa,EAAwB,EAAE,CAC3C,IAAI,CAAC,QAAQ,CAAc;YACzB,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,YAAY,kBAAkB,CAAC,KAAK,CAAC,EAAE;SAC9C,CAAC;QAEJ,MAAM,EAAE,CACN,KAAa,EACb,OAAyB,EAAE,EAC3B,OAAwB,EAAE,EACE,EAAE,CAC9B,IAAI,CAAC,QAAQ,CAAoB;YAC/B,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,YAAY,kBAAkB,CAAC,KAAK,CAAC,SAAS;YACpD,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;SACrC,CAAC;QAEJ;;;;;;;;WAQG;QACH,UAAU,EAAE,CACV,IAA2B,EAC3B,OAAwB,EAAE,EACO,EAAE,CACnC,IAAI,CAAC,QAAQ,CAAyB;YACpC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,sBAAsB;YAC5B,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;SACrC,CAAC;QAEJ,IAAI,EAAE,CACJ,KAAa,EACb,IAAoB,EACpB,OAAwB,EAAE,EACA,EAAE,CAC5B,IAAI,CAAC,QAAQ,CAAkB;YAC7B,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,YAAY,kBAAkB,CAAC,KAAK,CAAC,OAAO;YAClD,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;SACrC,CAAC;QAEJ,UAAU,EAAE,CACV,KAAa,EACb,SAA6D,EAAE,EAClC,EAAE;YAC/B,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;YACrC,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;gBACtC,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;YAC1D,CAAC;YACD,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;gBACxC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC;YACvD,CAAC;YACD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,QAAQ,CAAqB;gBACvC,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,YAAY,kBAAkB,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;aAC/E,CAAC,CAAC;QACL,CAAC;QAED;;;;WAIG;QACH,MAAM,EAAE,CAAC,KAAa,EAAE,OAA4B,EAAE,EAA2C,EAAE,CACjG,YAAY,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC;KAC9E,CAAC;IAEF,wEAAwE;IAC/D,UAAU,GAAG;QACpB,YAAY,EAAE,CACZ,KAAa,EACb,MAAc,EACd,IAA6B,EAC7B,OAAwB,EAAE,EACS,EAAE,CACrC,IAAI,CAAC,QAAQ,CAA2B;YACtC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,YAAY,kBAAkB,CAAC,KAAK,CAAC,eAAe,kBAAkB,CAAC,MAAM,CAAC,EAAE;YACtF,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;SACrC,CAAC;QAEJ;;;;;;WAMG;QACH,cAAc,EAAE,CAAC,KAAa,EAAuC,EAAE,CACrE,IAAI,CAAC,QAAQ,CACX;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,EAAE;SACpD,EACD,KAAK,CACN;QAEH;;;;WAIG;QACH,cAAc,EAAE,CACd,KAAa,EACb,IAA6B,EAC7B,OAAwB,EAAE,EACgB,EAAE,CAC5C,IAAI,CAAC,QAAQ,CACX;YACE,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,EAAE;YACnD,IAAI;YACJ,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;SACrC,EACD,KAAK,CACN;KACJ,CAAC;IAEF,2EAA2E;IAClE,KAAK,GAAG;QACf;;;;;;;;;;WAUG;QACH,MAAM,EAAE,CAAC,OAAe,EAAE,KAAa,EAA8B,EAAE;YACrE,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;YACrC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;YACvC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC,QAAQ,CAAoB;gBACtC,MAAM,EAAE,KAAK;gBACb,IAAI,EAAE,oBAAoB,MAAM,CAAC,QAAQ,EAAE,EAAE;aAC9C,CAAC,CAAC;QACL,CAAC;KACF,CAAC;IAEF,wEAAwE;IACxE,gBAAgB,CAAC,IAAqB;QACpC,MAAM,CAAC,GAA2B,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,cAAc;YAAE,CAAC,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC;QACpE,IAAI,IAAI,CAAC,KAAK;YAAE,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;QAC1C,OAAO,CAAC,CAAC;IACX,CAAC;IAED,KAAK,CAAC,QAAQ,CAAI,IAAuB,EAAE,aAAa,GAAG,IAAI;QAC7D,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,OAAO,GAA2B;YACtC,MAAM,EAAE,kBAAkB;YAC1B,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;SACxB,CAAC;QACF,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC,KAAK,SAAS,EAAE,CAAC;YACrE,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QAC/C,CAAC;QACD,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,CAAC,aAAa,GAAG,UAAU,IAAI,CAAC,OAAO,EAAE,CAAC;QACnD,CAAC;QACD,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC;QACpD,CAAC;QAED,MAAM,IAAI,GAAgB,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QAC3D,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5B,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,+DAA+D;QAC/D,kEAAkE;QAClE,4DAA4D;QAC5D,MAAM,WAAW,GACf,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS,CAAC;QAEhF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,GAA8B,CAAC;YACnC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC9D,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,IAAI,MAAM,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;oBACrF,GAAG,GAAG,MAAuB,CAAC;gBAChC,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,qCAAqC;YACvC,CAAC;YACD,MAAM,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAc,CAAC;QAC7C,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,MAAM,EACV,IAAI,EACJ;gBACE,KAAK,EAAE,cAAc;gBACrB,OAAO,EAAE,kDAAkD;aAC5D,EACD,WAAW,CACZ,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cost-attribution.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare const OPENWOP_COST_ATTRIBUTE_NAMES: readonly ["openwop.cost.tokens.input", "openwop.cost.tokens.output", "openwop.cost.tokens.total", "openwop.cost.usd", "openwop.cost.currency", "openwop.cost.estimated", "openwop.cost.provider"];
+/** 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];
+/** 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 declare function sanitizeCostAttributes(input: Record<string, unknown>): Record<string, number | string | boolean>;
+//# sourceMappingURL=cost-attribution.d.ts.map

package/dist/cost-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-attribution.d.ts","sourceRoot":"","sources":["../src/cost-attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;0CAC0C;AAC1C,eAAO,MAAM,4BAA4B,mMAQ/B,CAAC;AAEX;uDACuD;AACvD,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIrF;;;;;;;;;;;;;;;;kFAgBkF;AAClF,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAS3C"}

package/dist/cost-attribution.js

@@ -0,0 +1,65 @@
+/**
+ * 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',
+];
+const ALLOWLIST = new Set(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) {
+    const out = {};
+    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;
+}
+//# sourceMappingURL=cost-attribution.js.map

package/dist/cost-attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-attribution.js","sourceRoot":"","sources":["../src/cost-attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;0CAC0C;AAC1C,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,2BAA2B;IAC3B,4BAA4B;IAC5B,2BAA2B;IAC3B,kBAAkB;IAClB,uBAAuB;IACvB,wBAAwB;IACxB,uBAAuB;CACf,CAAC;AAMX,MAAM,SAAS,GAAwB,IAAI,GAAG,CAAS,4BAA4B,CAAC,CAAC;AAErF;;;;;;;;;;;;;;;;kFAgBkF;AAClF,MAAM,UAAU,sBAAsB,CACpC,KAA8B;IAE9B,MAAM,GAAG,GAA8C,EAAE,CAAC;IAC1D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YACzF,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/event-helpers.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 { type EventsStreamContext, type EventsStreamOptions } from './sse.js';
+import type { AgentDecidedPayload, AgentHandoffPayload, AgentReasonedPayload, AgentReasoningDeltaPayload, AgentToolCalledPayload, AgentToolReturnedPayload, RunEventDoc, TypedRunEvent } from './types.js';
+/** `agent.reasoned` (RFC 0002 §B). Narrows when `type` matches AND
+ *  payload carries the required `agentId` + `reasoning` strings. */
+export declare function isAgentReasoned(ev: RunEventDoc): ev is TypedRunEvent<AgentReasonedPayload>;
+/** `agent.reasoning.delta` (RFC 0024). Narrows when `type` matches AND
+ *  payload carries the required `agentId` + `delta` strings + numeric
+ *  `sequence`. */
+export declare function isAgentReasoningDelta(ev: RunEventDoc): ev is TypedRunEvent<AgentReasoningDeltaPayload>;
+/** `agent.toolCalled` (RFC 0002 §B). */
+export declare function isAgentToolCalled(ev: RunEventDoc): ev is TypedRunEvent<AgentToolCalledPayload>;
+/** `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 declare function isAgentToolReturned(ev: RunEventDoc): ev is TypedRunEvent<AgentToolReturnedPayload>;
+/** `agent.handoff` (RFC 0002 §B). Note the distinct field names —
+ *  `fromAgentId` / `toAgentId`, NOT a single `agentId`. */
+export declare function isAgentHandoff(ev: RunEventDoc): ev is TypedRunEvent<AgentHandoffPayload>;
+/** `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 declare function isAgentDecided(ev: RunEventDoc): ev is TypedRunEvent<AgentDecidedPayload>;
+/** 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 declare function subscribeToAgentReasoning(ctx: EventsStreamContext, runId: string, callbacks: AgentReasoningCallbacks, options?: Omit<EventsStreamOptions, 'signal'>): Unsubscribe;
+//# sourceMappingURL=event-helpers.d.ts.map

package/dist/event-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-helpers.d.ts","sourceRoot":"","sources":["../src/event-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAgB,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC5F,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,WAAW,EACX,aAAa,EACd,MAAM,YAAY,CAAC;AAepB;oEACoE;AACpE,wBAAgB,eAAe,CAC7B,EAAE,EAAE,WAAW,GACd,EAAE,IAAI,aAAa,CAAC,oBAAoB,CAAC,CAM3C;AAED;;kBAEkB;AAClB,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,WAAW,GACd,EAAE,IAAI,aAAa,CAAC,0BAA0B,CAAC,CAMjD;AAED,wCAAwC;AACxC,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,WAAW,GACd,EAAE,IAAI,aAAa,CAAC,sBAAsB,CAAC,CAO7C;AAED;;oEAEoE;AACpE,wBAAgB,mBAAmB,CACjC,EAAE,EAAE,WAAW,GACd,EAAE,IAAI,aAAa,CAAC,wBAAwB,CAAC,CAO/C;AAED;2DAC2D;AAC3D,wBAAgB,cAAc,CAC5B,EAAE,EAAE,WAAW,GACd,EAAE,IAAI,aAAa,CAAC,mBAAmB,CAAC,CAM1C;AAED;;wCAEwC;AACxC,wBAAgB,cAAc,CAC5B,EAAE,EAAE,WAAW,GACd,EAAE,IAAI,aAAa,CAAC,mBAAmB,CAAC,CAQ1C;AAID;2EAC2E;AAC3E,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;iEAGiE;AACjE,MAAM,WAAW,uBAAuB;IACtC;;2CAEuC;IACvC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,0BAA0B,EAAE,EAAE,EAAE,aAAa,CAAC,0BAA0B,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvH;;4CAEwC;IACxC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,EAAE,EAAE,EAAE,aAAa,CAAC,oBAAoB,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5G;oCACgC;IAChC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB;;;gBAGY;IACZ,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,mBAAmB,EACxB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,uBAAuB,EAClC,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAM,GAChD,WAAW,CAqDb"}