@openwop/openwop 1.1.1 → 1.1.3

package/src/index.ts

@@ -28,20 +28,61 @@ export type {
   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,
+  // RFC 0027 + RFC 0028 — Prompt library (spec/v1/prompts.md)
+  GetPromptRequest,
+  ListPromptsRequest,
+  ListPromptsResponse,
+  PromptKind,
+  PromptRef,
+  PromptTemplate,
+  PromptVariable,
+  RenderPromptRequest,
+  RenderPromptResponse,
 } from './types.js';
 export { streamEvents } from './sse.js';
 export type { EventsStreamContext, EventsStreamOptions } 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';
+export type {
+  AgentReasoningCallbacks,
+  Unsubscribe,
+} 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`.
@@ -61,3 +102,79 @@ export type {
   RunErrorCode,
   RunError,
 } 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';
+export type { OpenwopCostAttributeName } 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';
+export type {
+  VerifyWebhookSignatureOptions,
+  VerifyWebhookOutcome,
+} 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';
+export type {
+  RegistryClientOptions,
+  RegistryDiscovery,
+  RegistryIndex,
+  RegistryIndexEntry,
+  RegistryPackMetadata,
+  RegistryVersionManifest,
+} from './registry-helpers.js';
+
+// AI Envelope types (DRAFT v1.x — spec/v1/ai-envelope.md). Inbound LLM-emission
+// envelope, distinct from RunEventDoc (outbound) and ErrorEnvelope (host HTTP).
+export type {
+  AIEnvelope,
+  AIEnvelopeErrorPayload,
+  ClarificationRequestPayload,
+  EnvelopeContract,
+  EnvelopeContractRefusal,
+  EnvelopeContractsCapability,
+  EnvelopeMeta,
+  EnvelopeOutcome,
+  EnvelopeStrictness,
+  PartialInfo,
+  SchemaRequestPayload,
+  SchemaResponsePayload,
+  ValidationDetail,
+} from './types.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';
+export type { ReasoningDirectiveStrength } 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';
+export type { RefusalProvider, RefusalSignal } from './parse-refusal.js';

package/src/parse-refusal.ts

@@ -0,0 +1,311 @@
+/**
+ * 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;
+}
+
+interface OpenAIChoiceMessage {
+  refusal?: unknown;
+  content?: unknown;
+}
+
+interface OpenAIChoice {
+  finish_reason?: unknown;
+  message?: unknown;
+}
+
+interface OpenAIResponse {
+  choices?: unknown;
+}
+
+interface AnthropicTextBlock {
+  type?: unknown;
+  text?: unknown;
+}
+
+interface AnthropicResponse {
+  stop_reason?: unknown;
+  content?: unknown;
+}
+
+interface GeminiSafetyRating {
+  category?: unknown;
+  probability?: unknown;
+}
+
+interface GeminiCandidate {
+  finishReason?: unknown;
+  safetyRatings?: unknown;
+  content?: unknown;
+}
+
+interface GeminiPromptFeedback {
+  blockReason?: unknown;
+  safetyRatings?: unknown;
+}
+
+interface GeminiResponse {
+  candidates?: unknown;
+  promptFeedback?: unknown;
+}
+
+/**
+ * Try to parse the response as OpenAI Chat Completions output.
+ *
+ * Detection: top-level `choices` array. Refusal signals:
+ *   - `choices[0].finish_reason === "content_filter"`
+ *   - `choices[0].message.refusal` is a non-empty string
+ */
+function tryParseOpenAI(response: unknown): RefusalSignal | null {
+  if (!response || typeof response !== 'object') return null;
+  const r = response as OpenAIResponse;
+  if (!Array.isArray(r.choices) || r.choices.length === 0) return null;
+  const choice = r.choices[0] as OpenAIChoice;
+  if (!choice || typeof choice !== 'object') return null;
+
+  const finishReason = choice.finish_reason;
+  const message = choice.message as OpenAIChoiceMessage | undefined;
+  const refusalField = message && typeof message === 'object' ? message.refusal : undefined;
+
+  // Primary signal: explicit refusal-text field. OpenAI's structured-output
+  // release populates this when the safety filter intervenes.
+  if (typeof refusalField === 'string' && refusalField.length > 0) {
+    return { refusalText: refusalField, provider: 'openai' };
+  }
+
+  // Secondary signal: finish_reason. content_filter is the canonical
+  // safety-stop value.
+  if (finishReason === 'content_filter') {
+    const text =
+      message && typeof message === 'object' && typeof message.content === 'string'
+        ? message.content
+        : null;
+    return { refusalText: text, safetyCategory: 'content_filter', provider: 'openai' };
+  }
+
+  return null;
+}
+
+/**
+ * Try to parse the response as Anthropic Messages API output.
+ *
+ * Detection: top-level `stop_reason` field (Anthropic's distinctive
+ * marker). Refusal signals:
+ *   - `stop_reason === "refusal"` (their 2025 release)
+ *
+ * Anthropic does not surface a distinct safety-category field on
+ * refusals; the `refusal` stop_reason is the binary signal.
+ */
+function tryParseAnthropic(response: unknown): RefusalSignal | null {
+  if (!response || typeof response !== 'object') return null;
+  const r = response as AnthropicResponse;
+  if (typeof r.stop_reason !== 'string') return null;
+
+  if (r.stop_reason === 'refusal') {
+    // Extract refusal text from the content array (Anthropic returns an
+    // array of typed blocks; refusal text appears in `text`-type blocks).
+    let refusalText: string | null = null;
+    if (Array.isArray(r.content)) {
+      const textBlocks: string[] = [];
+      for (const block of r.content) {
+        if (block && typeof block === 'object') {
+          const b = block as AnthropicTextBlock;
+          if (b.type === 'text' && typeof b.text === 'string') {
+            textBlocks.push(b.text);
+          }
+        }
+      }
+      if (textBlocks.length > 0) refusalText = textBlocks.join('\n');
+    }
+    return { refusalText, provider: 'anthropic' };
+  }
+
+  return null;
+}
+
+/**
+ * Try to parse the response as Google Gemini `generateContent` output.
+ *
+ * Detection: top-level `candidates` array OR top-level `promptFeedback`
+ * object. Refusal signals:
+ *   - `candidates[0].finishReason === "SAFETY"` (output-side block)
+ *   - `promptFeedback.blockReason === "SAFETY"` (input-side block)
+ *
+ * Gemini surfaces safety categories on `safetyRatings[]`; this helper
+ * picks the highest-probability HIGH/MEDIUM-tier category as
+ * `safetyCategory` when available.
+ */
+function tryParseGemini(response: unknown): RefusalSignal | null {
+  if (!response || typeof response !== 'object') return null;
+  const r = response as GeminiResponse;
+
+  // Output-side safety block.
+  if (Array.isArray(r.candidates) && r.candidates.length > 0) {
+    const candidate = r.candidates[0] as GeminiCandidate;
+    if (candidate && typeof candidate === 'object' && candidate.finishReason === 'SAFETY') {
+      const safetyCategory = extractGeminiHighestRiskCategory(candidate.safetyRatings);
+      const result: RefusalSignal = { refusalText: null, provider: 'google' };
+      if (safetyCategory !== undefined) result.safetyCategory = safetyCategory;
+      return result;
+    }
+  }
+
+  // Input-side safety block (Gemini rejected the prompt itself).
+  if (r.promptFeedback && typeof r.promptFeedback === 'object') {
+    const pf = r.promptFeedback as GeminiPromptFeedback;
+    if (typeof pf.blockReason === 'string' && pf.blockReason.toUpperCase().includes('SAFETY')) {
+      const safetyCategory = extractGeminiHighestRiskCategory(pf.safetyRatings);
+      const result: RefusalSignal = { refusalText: null, provider: 'google' };
+      if (safetyCategory !== undefined) result.safetyCategory = safetyCategory;
+      return result;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * From a Gemini `safetyRatings[]` array, return the highest-probability
+ * non-NEGLIGIBLE category identifier. Returns `undefined` when the
+ * array is absent or all ratings are NEGLIGIBLE.
+ */
+function extractGeminiHighestRiskCategory(safetyRatings: unknown): string | undefined {
+  if (!Array.isArray(safetyRatings)) return undefined;
+  const PROBABILITY_RANK: Record<string, number> = {
+    HIGH: 3,
+    MEDIUM: 2,
+    LOW: 1,
+    NEGLIGIBLE: 0,
+  };
+  let best: { category: string; rank: number } | null = null;
+  for (const rating of safetyRatings) {
+    if (!rating || typeof rating !== 'object') continue;
+    const r = rating as GeminiSafetyRating;
+    if (typeof r.category !== 'string' || typeof r.probability !== 'string') continue;
+    const rank = PROBABILITY_RANK[r.probability.toUpperCase()] ?? 0;
+    if (rank === 0) continue;
+    if (best === null || rank > best.rank) {
+      best = { category: r.category, rank };
+    }
+  }
+  return best?.category;
+}
+
+/**
+ * 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 function parseRefusal(providerResponse: unknown): RefusalSignal | null {
+  return (
+    tryParseOpenAI(providerResponse) ??
+    tryParseAnthropic(providerResponse) ??
+    tryParseGemini(providerResponse)
+  );
+}

package/src/registry-helpers.ts

@@ -0,0 +1,173 @@
+/**
+ * Public-registry read helpers per
+ * `spec/v1/registry-operations.md`.
+ *
+ * The OpenWOP host SDK targets the host wire surface
+ * (`/.well-known/openwop` + `/v1/runs/*` + `/v1/interrupts/*` etc).
+ * The **public node-pack registry** at `packs.openwop.dev` is a
+ * separate wire surface with its own discovery payload and pack-
+ * versioned read endpoints. This module exposes a thin typed client
+ * for that surface so adopters fetching pack manifests, indices, or
+ * signature material don't roll their own HTTP plumbing.
+ *
+ * Read-only by design — the public registry uses pull-request-driven
+ * publishing per `spec/v1/registry-operations.md` §"Submission flow"
+ * + the `registry-publish.yml` GitHub workflow. There is no write API.
+ *
+ * No auth required for public reads.
+ *
+ * @module @openwop/openwop/registry-helpers
+ */
+
+/** Public registry discovery payload per `registry-operations.md` §"Discovery". */
+export interface RegistryDiscovery {
+  registryVersion: string;
+  protocolVersion: string;
+  name?: string;
+  operator?: string;
+  url?: string;
+  supportedNamespaces: readonly string[];
+  supportedSigningMethods: readonly string[];
+  supportedTrustModes?: readonly string[];
+  endpoints: {
+    registryIndex: string;
+    packMetadata: string;
+    versionManifest: string;
+    versionTarball: string;
+    versionSignature: string;
+    publicKey: string;
+  };
+  signingKeys?: ReadonlyArray<{
+    keyId: string;
+    algorithm: string;
+    publicKeyUrl?: string;
+    permittedNamespaces?: readonly string[];
+    operator?: string;
+    status?: string;
+  }>;
+  [key: string]: unknown;
+}
+
+/** Registry-wide index entry per `/v1/index.json` rows. */
+export interface RegistryIndexEntry {
+  name: string;
+  latestVersion: string;
+  description?: string;
+  scope?: string;
+  [key: string]: unknown;
+}
+
+export interface RegistryIndex {
+  packs: ReadonlyArray<RegistryIndexEntry>;
+  generated?: string;
+  packCount?: number;
+  [key: string]: unknown;
+}
+
+/** Per-pack metadata document at `/v1/packs/{name}/index.json`. */
+export interface RegistryPackMetadata {
+  name: string;
+  description?: string;
+  versions: ReadonlyArray<string>;
+  latestVersion?: string;
+  [key: string]: unknown;
+}
+
+/** Version manifest at `/v1/packs/{name}/-/{version}.json`. */
+export interface RegistryVersionManifest {
+  name: string;
+  version: string;
+  description?: string;
+  /** SRI hash: `sha256-<43-char-b64>=`. */
+  integrity?: string;
+  signing?: {
+    method: 'ed25519' | 'manual' | string;
+    keyId: string;
+    publicKeyUrl?: string;
+  };
+  [key: string]: unknown;
+}
+
+export interface RegistryClientOptions {
+  /** Base URL for the registry. Defaults to `https://packs.openwop.dev`. */
+  baseUrl?: string;
+  /** Custom fetch implementation; defaults to `globalThis.fetch`. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Typed client for the public OpenWOP node-pack registry. Read-only;
+ * no auth required for the canonical public read surface.
+ *
+ * For host-side install-time verification (SRI + Ed25519 + lockfile),
+ * see `examples/hosts/postgres/src/pack-consumer.ts` — the registry
+ * client is the fetch surface; the consumer is the security surface.
+ */
+export class RegistryClient {
+  readonly baseUrl: string;
+  readonly #fetch: typeof fetch;
+
+  constructor(options: RegistryClientOptions = {}) {
+    this.baseUrl = (options.baseUrl ?? 'https://packs.openwop.dev').replace(/\/$/, '');
+    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  /** `GET /.well-known/openwop-registry` — discovery + endpoint catalog. */
+  async discovery(): Promise<RegistryDiscovery> {
+    return this.#getJson<RegistryDiscovery>('/.well-known/openwop-registry');
+  }
+
+  /** `GET /v1/index.json` — registry-wide pack index. */
+  async index(): Promise<RegistryIndex> {
+    return this.#getJson<RegistryIndex>('/v1/index.json');
+  }
+
+  /** `GET /v1/packs/{name}/index.json` — per-pack metadata. */
+  async pack(name: string): Promise<RegistryPackMetadata> {
+    return this.#getJson<RegistryPackMetadata>(
+      `/v1/packs/${encodeURIComponent(name)}/index.json`,
+    );
+  }
+
+  /** `GET /v1/packs/{name}/-/{version}.json` — version manifest. */
+  async version(name: string, version: string): Promise<RegistryVersionManifest> {
+    return this.#getJson<RegistryVersionManifest>(
+      `/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.json`,
+    );
+  }
+
+  /** Fetch raw tarball bytes. Caller MUST verify SRI + signature before trust. */
+  async tarball(name: string, version: string): Promise<Buffer> {
+    return this.#getBinary(
+      `/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.tgz`,
+    );
+  }
+
+  /** Fetch raw 64-byte Ed25519 signature bytes. */
+  async signature(name: string, version: string): Promise<Buffer> {
+    return this.#getBinary(
+      `/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.sig`,
+    );
+  }
+
+  /** Fetch a publisher's public key as PEM text. */
+  async publicKey(keyId: string): Promise<string> {
+    const res = await this.#fetch(`${this.baseUrl}/keys/${encodeURIComponent(keyId)}.pub`);
+    if (!res.ok) throw new Error(`registry: GET /keys/${keyId}.pub returned ${res.status}`);
+    return res.text();
+  }
+
+  async #getJson<T>(path: string): Promise<T> {
+    const res = await this.#fetch(`${this.baseUrl}${path}`, {
+      headers: { Accept: 'application/json' },
+    });
+    if (!res.ok) throw new Error(`registry: GET ${path} returned ${res.status}`);
+    return (await res.json()) as T;
+  }
+
+  async #getBinary(path: string): Promise<Buffer> {
+    const res = await this.#fetch(`${this.baseUrl}${path}`);
+    if (!res.ok) throw new Error(`registry: GET ${path} returned ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+  }
+}