@openwop/openwop 1.1.1 → 1.1.3

package/dist/envelope-directive.js

@@ -0,0 +1,89 @@
+/**
+ * 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)"
+ */
+/**
+ * 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, strength) {
+    if (strength === 'off')
+        return null;
+    if (!responseSchema || typeof responseSchema !== 'object')
+        return null;
+    const schema = responseSchema;
+    const properties = schema.properties;
+    if (!properties || typeof properties !== 'object')
+        return null;
+    const reasoningProp = properties.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(' ');
+}
+//# sourceMappingURL=envelope-directive.js.map

package/dist/envelope-directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope-directive.js","sourceRoot":"","sources":["../src/envelope-directive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAoBH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,uBAAuB,CACrC,cAAuB,EACvB,QAAoC;IAEpC,IAAI,QAAQ,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,CAAC,cAAc,IAAI,OAAO,cAAc,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAEvE,MAAM,MAAM,GAAG,cAA0C,CAAC;IAC1D,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACrC,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAE/D,MAAM,aAAa,GAAI,UAAsC,CAAC,SAAS,CAAC;IACxE,IAAI,CAAC,aAAa,IAAI,OAAO,aAAa,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAErE,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,OAAO;YACL,+FAA+F;YAC/F,8FAA8F;YAC9F,gGAAgG;YAChG,2FAA2F;YAC3F,oEAAoE;SACrE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACd,CAAC;IAED,0BAA0B;IAC1B,OAAO;QACL,8FAA8F;QAC9F,gGAAgG;QAChG,8FAA8F;QAC9F,+FAA+F;QAC/F,4FAA4F;KAC7F,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,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"}

package/dist/event-helpers.js

@@ -0,0 +1,160 @@
+/**
+ * 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 } from './sse.js';
+// ─── Type guards ────────────────────────────────────────────────────────
+function hasStringField(payload, field) {
+    return (payload !== null &&
+        typeof payload === 'object' &&
+        typeof payload[field] === 'string');
+}
+/** `agent.reasoned` (RFC 0002 §B). Narrows when `type` matches AND
+ *  payload carries the required `agentId` + `reasoning` strings. */
+export function isAgentReasoned(ev) {
+    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) {
+    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.sequence;
+    return typeof seq === 'number' && Number.isInteger(seq) && seq >= 0;
+}
+/** `agent.toolCalled` (RFC 0002 §B). */
+export function isAgentToolCalled(ev) {
+    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) {
+    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) {
+    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) {
+    return (ev.type === 'agent.decided' &&
+        hasStringField(ev.payload, 'agentId') &&
+        ev.payload !== null &&
+        typeof ev.payload === 'object' &&
+        'decision' in ev.payload);
+}
+/**
+ * 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, runId, callbacks, options = {}) {
+    const abort = new AbortController();
+    let stopped = false;
+    const stop = () => {
+        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;
+}
+//# sourceMappingURL=event-helpers.js.map

package/dist/event-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-helpers.js","sourceRoot":"","sources":["../src/event-helpers.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -12,9 +12,22 @@
 export { OpenwopClient } from './client.js';
 export type { OpenwopClientOptions, MutationOptions } from './client.js';
 export { WopError } from './types.js';
-export type { AuditVerifyAnomaly, AuditVerifyCheckpoint, AuditVerifyResult, BulkCancelRunResult, BulkCancelRunsRequest, BulkCancelRunsResponse, Capabilities, CancelRunRequest, CancelRunResponse, CreateRunRequest, CreateRunResponse, ErrorEnvelope, ForkRunRequest, ForkRunResponse, InterruptByTokenInspection, PollEventsResponse, ResolveInterruptByTokenResponse, ResolveInterruptRequest, ResolveInterruptResponse, RunConfigurable, RunEventDoc, RunSnapshot, RunStatus, StreamMode, } from './types.js';
+export type { AuditVerifyAnomaly, AuditVerifyCheckpoint, AuditVerifyResult, BulkCancelRunResult, BulkCancelRunsRequest, BulkCancelRunsResponse, Capabilities, CancelRunRequest, CancelRunResponse, CreateRunRequest, CreateRunResponse, ErrorEnvelope, ForkRunRequest, ForkRunResponse, DebugBundle, DebugBundleOptions, RegisterWebhookRequest, RegisterWebhookResponse, InterruptByTokenInspection, PauseRunRequest, PauseRunResponse, PollEventsResponse, ResolveInterruptByTokenResponse, ResolveInterruptRequest, ResolveInterruptResponse, ResumeRunRequest, ResumeRunResponse, RunConfigurable, RunEventDoc, RunSnapshot, RunStatus, StreamMode, TypedRunEvent, AgentReasonedPayload, AgentReasoningDeltaPayload, AgentToolCalledPayload, AgentToolReturnedPayload, AgentHandoffPayload, AgentDecidedPayload, GetPromptRequest, ListPromptsRequest, ListPromptsResponse, PromptKind, PromptRef, PromptTemplate, PromptVariable, RenderPromptRequest, RenderPromptResponse, } from './types.js';
 export { streamEvents } from './sse.js';
 export type { EventsStreamContext, EventsStreamOptions } from './sse.js';
+export { isAgentReasoned, isAgentReasoningDelta, isAgentToolCalled, isAgentToolReturned, isAgentHandoff, isAgentDecided, subscribeToAgentReasoning, } from './event-helpers.js';
+export type { AgentReasoningCallbacks, Unsubscribe, } from './event-helpers.js';
 export { ACTIVE_RUN_STATUSES, TERMINAL_RUN_STATUSES, isTerminalRunStatus, HTTP_ERROR_CODES, isHttpErrorCode, RUN_ERROR_CODES, isRunErrorCode, } from './run-helpers.js';
 export type { ActiveRunStatus, TerminalRunStatus, HttpErrorCode, RunErrorCode, RunError, } from './run-helpers.js';
+export { OPENWOP_COST_ATTRIBUTE_NAMES, sanitizeCostAttributes, } from './cost-attribution.js';
+export type { OpenwopCostAttributeName } from './cost-attribution.js';
+export { DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS, verifyWebhookSignature, signWebhookDelivery, } from './webhook-helpers.js';
+export type { VerifyWebhookSignatureOptions, VerifyWebhookOutcome, } from './webhook-helpers.js';
+export { RegistryClient } from './registry-helpers.js';
+export type { RegistryClientOptions, RegistryDiscovery, RegistryIndex, RegistryIndexEntry, RegistryPackMetadata, RegistryVersionManifest, } from './registry-helpers.js';
+export type { AIEnvelope, AIEnvelopeErrorPayload, ClarificationRequestPayload, EnvelopeContract, EnvelopeContractRefusal, EnvelopeContractsCapability, EnvelopeMeta, EnvelopeOutcome, EnvelopeStrictness, PartialInfo, SchemaRequestPayload, SchemaResponsePayload, ValidationDetail, } from './types.js';
+export { buildReasoningDirective } from './envelope-directive.js';
+export type { ReasoningDirectiveStrength } from './envelope-directive.js';
+export { parseRefusal } from './parse-refusal.js';
+export type { RefusalProvider, RefusalSignal } from './parse-refusal.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,eAAe,EACf,0BAA0B,EAC1B,kBAAkB,EAClB,+BAA+B,EAC/B,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAKzE,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,QAAQ,GACT,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACd,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,+BAA+B,EAC/B,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EAEnB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAIzE,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,uBAAuB,EACvB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAMtE,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAI/B,YAAY,EACV,UAAU,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,uBAAuB,EACvB,2BAA2B,EAC3B,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,WAAW,EACX,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAQpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAW1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -12,8 +12,42 @@
 export { OpenwopClient } from './client.js';
 export { WopError } from './types.js';
 export { streamEvents } from './sse.js';
+// RFC 0002 + RFC 0024 typed event helpers — type guards over `RunEventDoc`
+// plus a high-level streaming-reasoning subscription helper.
+export { isAgentReasoned, isAgentReasoningDelta, isAgentToolCalled, isAgentToolReturned, isAgentHandoff, isAgentDecided, subscribeToAgentReasoning, } from './event-helpers.js';
 // Run-status + run-error helpers (added in 1). Forward-compat predicates
 // over the wire-format unions declared above; full design + rationale in
 // `run-helpers.ts`.
 export { ACTIVE_RUN_STATUSES, TERMINAL_RUN_STATUSES, isTerminalRunStatus, HTTP_ERROR_CODES, isHttpErrorCode, RUN_ERROR_CODES, isRunErrorCode, } from './run-helpers.js';
+// Cost-attribution allowlist + sanitizer helpers
+// (`spec/v1/observability.md §"Cost attribution attributes"`). Single
+// source of truth for the canonical attribute names so independent
+// hosts share one list instead of each re-deriving it.
+export { OPENWOP_COST_ATTRIBUTE_NAMES, sanitizeCostAttributes, } from './cost-attribution.js';
+// Webhook-delivery verification helpers (SDK-3 close-out 2026-05-15).
+// HMAC-SHA256 + timestamp freshness window verification per
+// spec/v1/webhooks.md §"Signature recipe". Receivers MUST verify both
+// the HMAC AND the timestamp to defeat replay attacks.
+export { DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS, verifyWebhookSignature, signWebhookDelivery, } from './webhook-helpers.js';
+// Public-registry read helpers (SDK-5 close-out 2026-05-15). Read-only
+// typed client for the public node-pack registry at packs.openwop.dev
+// per spec/v1/registry-operations.md.
+export { RegistryClient } from './registry-helpers.js';
+// RFC 0030 §A `reasoning` field prompt-directive helper. Hosts that
+// advertise `capabilities.envelopes.reasoning.supported: true` use this
+// to synthesize the system-prompt fragment that instructs the model to
+// populate the OPTIONAL `reasoning` field. See `envelope-directive.ts`
+// for the operational note on `"mandatory"` strength (provider-side
+// refusal risk per the 2026-05-21 RFC 0030 amendment).
+export { buildReasoningDirective } from './envelope-directive.js';
+// RFC 0032 §B.3 + RFC 0033 §D refusal detection helper. Normalizes
+// per-provider safety-stop signals (Anthropic `stop_reason: "refusal"`,
+// OpenAI `message.refusal` + `finish_reason: "content_filter"`, Gemini
+// `finishReason: "SAFETY"` + `promptFeedback.blockReason: "SAFETY"`)
+// to a canonical `{ refusalText, safetyCategory?, provider }` shape.
+// Hosts route the non-null return through `envelope.refusal` emission
+// + the `envelope_refusal` terminal error code (RFC 0033 §F).
+// **SECURITY:** Pass `refusalText` through the BYOK redaction harness
+// BEFORE persistence — this helper does NOT redact.
+export { parseRefusal } from './parse-refusal.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AA2BtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAoDtC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,2EAA2E;AAC3E,6DAA6D;AAC7D,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,cAAc,EACd,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAM5B,yEAAyE;AACzE,yEAAyE;AACzE,oBAAoB;AACpB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,kBAAkB,CAAC;AAS1B,iDAAiD;AACjD,sEAAsE;AACtE,mEAAmE;AACnE,uDAAuD;AACvD,OAAO,EACL,4BAA4B,EAC5B,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAG/B,sEAAsE;AACtE,4DAA4D;AAC5D,sEAAsE;AACtE,uDAAuD;AACvD,OAAO,EACL,wCAAwC,EACxC,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAM9B,uEAAuE;AACvE,sEAAsE;AACtE,sCAAsC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA4BvD,oEAAoE;AACpE,wEAAwE;AACxE,uEAAuE;AACvE,uEAAuE;AACvE,oEAAoE;AACpE,uDAAuD;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,mEAAmE;AACnE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,sEAAsE;AACtE,8DAA8D;AAC9D,sEAAsE;AACtE,oDAAoD;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/parse-refusal.d.ts

@@ -0,0 +1,114 @@
+/**
+ * parseRefusal — normalize per-provider LLM safety-stop signals to the
+ * canonical RFC 0032 §B.3 refusal shape.
+ *
+ * The three Tier-1 vendors (Anthropic / OpenAI / Google Gemini) surface
+ * refusals through different fields:
+ *
+ *   - **Anthropic Messages API**: `stop_reason: "refusal"` (their 2025
+ *     release) OR `stop_reason: "end_turn"` accompanied by safety-stop
+ *     markers in the content. Refusal text MAY be inline in the
+ *     `content[]` array's text blocks.
+ *   - **OpenAI Chat Completions**: `choices[0].finish_reason:
+ *     "content_filter"` OR `choices[0].message.refusal: <string>` (the
+ *     refusal-text field added in their structured-output release).
+ *   - **Google Gemini**: `candidates[0].finishReason: "SAFETY"` OR
+ *     `promptFeedback.blockReason: "SAFETY"` (input-side block).
+ *
+ * Without normalization, every host re-implements this detection. This
+ * helper consolidates the per-vendor shape-detection and returns a
+ * canonical `RefusalSignal | null` — null when the response is a
+ * normal completion (no refusal detected).
+ *
+ * Per RFC 0032 §B.3 + RFC 0033 §D, hosts MUST NOT retry on refusal
+ * (circumvention concern). Callers route the non-null return through
+ * `envelope.refusal` emission + the `envelope_refusal` terminal error
+ * code (per RFC 0033 §F).
+ *
+ * Per SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak,
+ * `refusalText` MUST be passed through the host's BYOK redaction
+ * harness BEFORE persistence — this helper does NOT redact; the
+ * caller is responsible for SR-1 carry-forward.
+ *
+ * @see RFCS/0032-envelope-reliability-events.md §B.3
+ * @see RFCS/0033-envelope-completion-contract.md §D + §F
+ * @see SECURITY/invariants.yaml §envelope-refusal-no-prompt-leak
+ */
+/**
+ * Provider identifier for the matched shape. `"unknown"` is reserved
+ * for refusals matched on heuristic signals without a definitive
+ * vendor-shape match.
+ */
+export type RefusalProvider = 'anthropic' | 'openai' | 'google' | 'unknown';
+/**
+ * Canonical refusal signal. All three Tier-1 vendor shapes normalize
+ * to this form. `null` from `parseRefusal()` means "no refusal detected"
+ * (a normal completion); a non-null `RefusalSignal` means the caller
+ * SHOULD route through the RFC 0032 §B.3 refusal-emission path.
+ */
+export interface RefusalSignal {
+    /**
+     * The provider's refusal text, when surfaced. MAY be `null` even for
+     * detected refusals — Anthropic + Gemini frequently refuse without
+     * inline text (the safety filter is opaque to the model). OpenAI's
+     * `message.refusal` field is the most consistent source of human-
+     * readable refusal text.
+     *
+     * **SECURITY:** When non-null, `refusalText` MAY contain prompt
+     * content that triggered the safety filter. Callers MUST pass it
+     * through their BYOK + prompt-content redaction harness BEFORE
+     * persistence (per `envelope-refusal-no-prompt-leak` SECURITY
+     * invariant).
+     */
+    refusalText: string | null;
+    /**
+     * Provider-specific safety-category identifier, when surfaced.
+     * Examples: Gemini's safety-rating categories
+     * (`HARM_CATEGORY_HARASSMENT`, etc.), OpenAI's content-filter category,
+     * Anthropic's policy-violation tag. Hosts MAY echo this on the
+     * `envelope.refusal.safetyCategory` event field for downstream
+     * observability.
+     */
+    safetyCategory?: string;
+    /**
+     * Which provider's shape was matched. Useful for debugging
+     * cross-host integration + for hosts that want to route refusals
+     * differently per vendor (e.g., different operator notifications).
+     */
+    provider: RefusalProvider;
+}
+/**
+ * Parse a provider response into a canonical refusal signal.
+ *
+ * Returns `null` when no refusal is detected (normal completion).
+ * Returns a `RefusalSignal` when the response matches one of the
+ * three Tier-1 vendors' safety-stop shapes.
+ *
+ * Detection order: OpenAI → Anthropic → Gemini. Each detector inspects
+ * a distinctive top-level field, so cross-vendor false-positives are
+ * unlikely. A response that doesn't match any vendor shape returns
+ * `null` (hosts that route through novel providers add their own
+ * detector + fall back to this for the three known ones).
+ *
+ * @example
+ * ```ts
+ * import { parseRefusal } from '@openwop/openwop';
+ *
+ * const response = await callOpenAI({...});
+ * const refusal = parseRefusal(response);
+ * if (refusal) {
+ *   // Route through envelope.refusal emission + envelope_refusal error code.
+ *   // REMEMBER to redact refusalText through the BYOK harness before
+ *   // persistence (SECURITY invariant envelope-refusal-no-prompt-leak).
+ *   await emitEnvelopeRefusal({
+ *     refusalText: redactBYOK(refusal.refusalText),
+ *     safetyCategory: refusal.safetyCategory,
+ *     provider: refusal.provider,
+ *   });
+ *   throw new EnvelopeRefusalError(...);
+ * }
+ * // ...normal-completion handling...
+ * ```
+ */
+export declare function parseRefusal(providerResponse: unknown): RefusalSignal | null;
+//# sourceMappingURL=parse-refusal.d.ts.map

package/dist/parse-refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-refusal.d.ts","sourceRoot":"","sources":["../src/parse-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAE3B;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,QAAQ,EAAE,eAAe,CAAC;CAC3B;AA6LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAAC,gBAAgB,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAM5E"}