@openwop/openwop 1.1.1 → 1.1.3

package/src/types.ts

@@ -18,6 +18,7 @@ export type RunStatus =
   | 'paused'
   | 'waiting-approval'
   | 'waiting-input'
+  | 'waiting-external'
   | 'completed'
   | 'failed'
   | 'cancelled';
@@ -54,6 +55,24 @@ export interface RunSnapshot {
   variables?: Record<string, unknown>;
   channels?: Record<string, unknown>;
   error?: { code?: string; message?: string };
+  /** Linkage back to the parent run when this run was spawned via
+   *  `core.subWorkflow`. Per `interrupt-profiles.md §openwop-interrupt-
+   *  cascade-cancel`: child runs preserve `parentRunId` + `parentNodeId`
+   *  so cancellation can cascade. Absent for top-level runs. */
+  parentRunId?: string;
+  parentNodeId?: string;
+  /** Surfaced for `waiting-*` runs per `interrupt.md §"Signed-token
+   *  callback"`. Carries the open interrupt's metadata so clients can
+   *  resolve via `POST /v1/interrupts/{token}` without consulting a
+   *  separate endpoint. Hosts MAY omit `data` to keep payloads small;
+   *  the token + callbackUrl are the load-bearing fields. */
+  interrupt?: {
+    kind: string;
+    nodeId: string;
+    interruptToken?: string;
+    callbackUrl?: string;
+    data?: unknown;
+  };
 }
 
 /**
@@ -103,6 +122,80 @@ export interface CancelRunResponse {
   status: 'cancelled' | 'cancelling';
 }
 
+/**
+ * Portable JSON diagnostic export for a single run per
+ * `spec/v1/debug-bundle.md` + `schemas/debug-bundle.schema.json`.
+ *
+ * Hosts MAY omit non-required fields. Consumers MUST treat masked /
+ * omitted / hashed values as the spec-canonical content per the host's
+ * advertised `redactionMode` — they are NOT placeholders for missing
+ * data.
+ */
+export interface DebugBundle {
+  bundleVersion: string;
+  generatedAt: string;
+  host: { name?: string; version?: string; vendor?: string };
+  run: Record<string, unknown>;
+  events: ReadonlyArray<Record<string, unknown>>;
+  redactionApplied: boolean;
+  /** Reflects the host's `capabilities.compliance.defaultMode`. */
+  redactionMode: 'mask' | 'omit' | 'hash' | 'passthrough';
+  /** True when the bundle hit the host's size cap; pair with `truncatedReason`. */
+  truncated?: boolean;
+  truncatedReason?: string;
+  [key: string]: unknown;
+}
+
+export interface DebugBundleOptions {
+  /** Optional host-extension query parameter to lower the size cap for testing. Spec-canonical hosts SHOULD prefer `host.<vendor>.<query>` namespacing; this is the SQLite-reference convention. */
+  maxEvents?: number;
+}
+
+export interface RegisterWebhookRequest {
+  /** Receiver URL the host will POST signed deliveries to. */
+  url: string;
+  /** Event types to subscribe to (subset of the `RunEventType` enum). */
+  events: readonly string[];
+  /** Optional pre-shared secret; if omitted the host generates one and returns it in the response. */
+  secret?: string;
+  /** Optional tag filter — only events from runs carrying these tags are delivered. */
+  tags?: readonly string[];
+}
+
+export interface RegisterWebhookResponse {
+  /** Server-issued opaque subscription id; pass to `webhooks.unregister`. */
+  subscriptionId: string;
+  url: string;
+  /**
+   * The signing secret. **Returned ONCE on registration** — the host
+   * cannot recover it later. Store it server-side for HMAC verification.
+   */
+  secret: string;
+  eventTypes: readonly string[];
+  createdAt: string;
+}
+
+export interface PauseRunRequest {
+  reason?: string;
+  drainPolicy?: 'immediate' | 'drain-current-node';
+}
+
+export interface PauseRunResponse {
+  runId: string;
+  status: 'paused';
+  pausedAt?: string;
+}
+
+export interface ResumeRunRequest {
+  reason?: string;
+}
+
+export interface ResumeRunResponse {
+  runId: string;
+  status: 'running';
+  resumedAt?: string;
+}
+
 // rest-endpoints.md §"POST /v1/runs:bulk-cancel" (closes R1).
 export interface BulkCancelRunsRequest {
   runIds: readonly string[];
@@ -388,9 +481,100 @@ export interface AgentsCapability {
   reasoning?: {
     verbosity: ReasoningVerbosity;
     tokenLimit?: number;
+    /** RFC 0024. When `true`, host MAY emit `agent.reasoning.delta`
+     *  events incrementally while a reasoning block is still open,
+     *  in addition to the final `agent.reasoned`. Consumers that
+     *  only read `agent.reasoned` remain correct (the closing event
+     *  is authoritative). */
+    streaming?: boolean;
   };
 }
 
+// ─── agent.* event payloads (RFC 0002 §B + RFC 0024) ────────────────────
+//
+// Mirror of `schemas/run-event-payloads.schema.json#$defs.agent*`. Field
+// names + types match the canonical wire contract verbatim; the `[key:
+// string]: unknown` index signature reflects the deliberate
+// `additionalProperties: true` carve-out on the agent.* payloads (Phase
+// 1 of the multi-agent shift). When the canonical schema changes, these
+// interfaces MUST be updated in lock-step — see the assertion in
+// `__tests__/event-helpers.test.ts` that exercises every required field.
+
+/** `agent.reasoned` payload (RFC 0002 §B). Fired once per closed
+ *  reasoning block. The `reasoning` field is authoritative — when a
+ *  streaming host also emitted `agent.reasoning.delta` events, this
+ *  event still carries the complete trace (possibly after host-side
+ *  truncation under `verbosity: 'summary'`). */
+export interface AgentReasonedPayload {
+  agentId: string;
+  reasoning: string;
+  verbosity?: ReasoningVerbosity;
+  [key: string]: unknown;
+}
+
+/** `agent.reasoning.delta` payload (RFC 0024). Incremental reasoning
+ *  chunk emitted while a reasoning block is still open. Consumers
+ *  concatenate `delta` strings in `sequence` order to reconstruct
+ *  the in-progress trace; the closing `agent.reasoned` event carries
+ *  the authoritative final content. */
+export interface AgentReasoningDeltaPayload {
+  agentId: string;
+  delta: string;
+  sequence: number;
+  verbosity?: ReasoningVerbosity;
+  [key: string]: unknown;
+}
+
+/** `agent.toolCalled` payload (RFC 0002 §B). Pairs with `agent.toolReturned`
+ *  via shared `callId`; the toolReturned event's `causationId` equals
+ *  the toolCalled event's `eventId`. */
+export interface AgentToolCalledPayload {
+  agentId: string;
+  toolName: string;
+  callId: string;
+  inputs?: unknown;
+  [key: string]: unknown;
+}
+
+/** `agent.toolReturned` payload (RFC 0002 §B). `outcome` and `error`
+ *  are mutually exclusive: success returns set `outcome`; failures set
+ *  `error`. Hosts that need stricter validation layer it host-side. */
+export interface AgentToolReturnedPayload {
+  agentId: string;
+  toolName: string;
+  callId: string;
+  outcome?: unknown;
+  error?: ErrorEnvelope;
+  [key: string]: unknown;
+}
+
+/** `agent.handoff` payload (RFC 0002 §B). Note the distinct field
+ *  names — `fromAgentId` / `toAgentId`, NOT a single `agentId` like
+ *  the other agent.* events. */
+export interface AgentHandoffPayload {
+  fromAgentId: string;
+  toAgentId: string;
+  reason?: string;
+  [key: string]: unknown;
+}
+
+/** `agent.decided` payload (RFC 0002 §B). `confidence` in `[0, 1]`
+ *  drives the low-confidence escalation contract (`node.suspended
+ *  { reason: 'low-confidence' }`) when below the resolved threshold. */
+export interface AgentDecidedPayload {
+  agentId: string;
+  decision: unknown;
+  confidence?: number;
+  [key: string]: unknown;
+}
+
+/** A `RunEventDoc` narrowed to a specific event-type discriminator +
+ *  payload shape. Returned by the `isAgent*` type guards in
+ *  `event-helpers.ts`. */
+export interface TypedRunEvent<T> extends RunEventDoc {
+  payload: T;
+}
+
 // ─── Auth profile claims (Phase I.5 + I.6) ──────────────────────────────
 
 /** Profile identifiers per auth-profiles.md. */
@@ -419,6 +603,246 @@ export interface DiscoveryAuthScopedCapability {
   mode: 'same-endpoint';
 }
 
+// ---------------------------------------------------------------------------
+// AI Envelope (DRAFT v1.x — `spec/v1/ai-envelope.md`)
+//
+// Inbound LLM-emission envelope. Distinct from `RunEventDoc` (outbound event
+// log) and `ErrorEnvelope` (host HTTP error response). Top-level shape is
+// closed; payload shape is selected by `type` and validated against a
+// per-kind JSON Schema advertised via `Capabilities.supportedEnvelopes` +
+// `Capabilities.schemaVersions`. See spec doc for full normative prose.
+// ---------------------------------------------------------------------------
+
+/** Wire metadata on every AI Envelope. */
+export interface EnvelopeMeta {
+  /** Provenance of this emission. */
+  source: 'ai-generation' | 'user' | 'system';
+  /** Mirrors `RunEventDoc.contentTrust`. Hosts MUST set 'untrusted' for MCP / A2A origin. */
+  contentTrust?: 'trusted' | 'untrusted';
+  /** ISO 8601 UTC timestamp. */
+  ts: string;
+  /** Optional W3C trace-context for distributed tracing. */
+  traceparent?: string;
+  /** Optional human-readable label for ops dashboards. */
+  label?: string;
+}
+
+/** Chunking info for streamed emissions. (in-flight) */
+export interface PartialInfo {
+  isPartial: boolean;
+  index: number;
+  /** -1 when total is unknown (streaming without precount). */
+  total: number;
+}
+
+/** Canonical inbound LLM-emission wire shape per `spec/v1/ai-envelope.md`. */
+export interface AIEnvelope<TPayload = unknown> {
+  /** Discriminator for payload shape, kind routing, and Envelope Contract gate. */
+  type: string;
+  /** Per-kind schema version. Absent → treat as 0. */
+  schemaVersion?: number;
+  /** Globally unique envelope id. Engine-assigned if absent on receipt. */
+  envelopeId: string;
+  /** Caller-stable id for dedup, replay short-circuit, and causal chaining. */
+  correlationId: string;
+  /** Set when the emitting node is identifiable. */
+  nodeId?: string;
+  /** Discriminated payload. Shape selected by `type`. */
+  payload: TPayload;
+  /** Wire metadata. */
+  meta: EnvelopeMeta;
+  /** Present when this is one fragment of a streamed emission. */
+  partial?: PartialInfo;
+}
+
+/** Per-typeId envelope-kind permission set per `ai-envelope.md` §"Envelope Contract". */
+export interface EnvelopeContract {
+  /** Kinds the engine will accept from this node. */
+  accepts: string[];
+  /** Refusal behavior for non-`accepts`, non-universal kinds. */
+  refusalMode: 'fail-node' | 'discard-and-warn';
+}
+
+/** Returned by the engine's `acceptEnvelope` path. */
+export type EnvelopeOutcome =
+  | { status: 'accepted'; recordedEventIds: string[] }
+  | { status: 'gated'; reason: string; gate: EnvelopeContractRefusal }
+  | { status: 'invalid'; reason: string; details: ValidationDetail[] }
+  | { status: 'breached'; reason: string; capKind: 'envelopes' | 'schema' | 'clarification' };
+
+export interface EnvelopeContractRefusal {
+  refusedType: string;
+  acceptedTypes: string[];
+  refusalMode: 'fail-node' | 'discard-and-warn';
+}
+
+export interface ValidationDetail {
+  path: string;
+  message: string;
+}
+
+/** Optional capability advertisement. Default when absent: 'warn'. */
+export type EnvelopeStrictness = 'warn' | 'strict';
+
+/** Optional capability advertisement per `ai-envelope.md` §"Capability handshake integration". */
+export interface EnvelopeContractsCapability {
+  advertised: boolean;
+}
+
+// Universal-kind payloads. Per-kind schemas at `schemas/envelopes/<kind>.schema.json`.
+
+/** Payload of the universal `clarification.request` envelope kind. */
+export interface ClarificationRequestPayload {
+  questions: Array<{
+    id: string;
+    question: string;
+    schema?: Record<string, unknown>;
+  }>;
+  contextType?: string;
+}
+
+/** Payload of the universal `schema.request` envelope kind. */
+export interface SchemaRequestPayload {
+  envelopeType: string;
+  reason?: string;
+}
+
+/** Payload of the universal `schema.response` envelope kind (LLM ack). */
+export interface SchemaResponsePayload {
+  envelopeType: string;
+  ack: true;
+}
+
+/**
+ * Payload of the universal `error` envelope kind (the LLM's deliberate error
+ * report). Distinct from `ErrorEnvelope` (the host's HTTP error response).
+ */
+export interface AIEnvelopeErrorPayload {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+// ── RFC 0027 + RFC 0028 — Prompt library (spec/v1/prompts.md) ──
+
+/**
+ * Role a PromptTemplate plays when composed into an LLM call. Shared enum
+ * `$ref`-ed by every schema that names a prompt kind. Per
+ * `schemas/prompt-kind.schema.json`.
+ */
+export type PromptKind = 'system' | 'user' | 'few-shot' | 'schema-hint';
+
+/**
+ * Typed interpolation slot in a PromptTemplate. Bindings are validated
+ * against this declaration before composition. Per
+ * `schemas/prompt-template.schema.json#/$defs/PromptVariable`.
+ */
+export interface PromptVariable {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+  required: boolean;
+  source?: 'input' | 'variable' | 'secret' | 'context';
+  extractPath?: string;
+  defaultValue?: unknown;
+  description?: string;
+}
+
+/**
+ * Named, versioned, variable-bound prompt body. Per
+ * `schemas/prompt-template.schema.json` + spec/v1/prompts.md §PromptTemplate.
+ *
+ * `meta.packName` + `meta.packVersion` are required when `meta.source: "pack"`
+ * (RFC 0028 §C); a JSON-Schema `if/then` conditional enforces this at the
+ * wire layer.
+ */
+export interface PromptTemplate {
+  templateId: string;
+  version: string;
+  kind: PromptKind;
+  text: string;
+  name?: string;
+  description?: string;
+  variables?: PromptVariable[];
+  modelHints?: {
+    modelClass?: string;
+    temperature?: number;
+    maxTokens?: number;
+    envelopeType?: string;
+  };
+  tags?: string[];
+  meta?: {
+    author?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    source?: 'host' | 'pack' | 'user';
+    packName?: string;
+    packVersion?: string;
+  };
+}
+
+/**
+ * Reference to a PromptTemplate. Two equivalent forms — the stringy URI
+ * `prompt:<templateId>[@<version>]` and the structured object — per
+ * `schemas/prompt-ref.schema.json`. The stringy form is canonical for
+ * inline use; the object form is canonical when `libraryId` disambiguation
+ * or per-reference `variableOverrides` are needed.
+ */
+export type PromptRef =
+  | string
+  | {
+      libraryId?: string;
+      templateId: string;
+      version?: string;
+      variableOverrides?: Record<string, unknown>;
+    };
+
+/** Filter set for `client.prompts.list(...)` per RFC 0028 §A. */
+export interface ListPromptsRequest {
+  kind?: PromptKind;
+  tag?: string;
+  modelClass?: string;
+  source?: 'host' | 'pack' | 'user';
+  cursor?: string;
+  limit?: number;
+}
+
+export interface ListPromptsResponse {
+  items: PromptTemplate[];
+  nextCursor?: string;
+}
+
+/** Identifier set for `client.prompts.get(...)` per RFC 0028 §A. */
+export interface GetPromptRequest {
+  templateId: string;
+  /** Pin to a SemVer version. When omitted, returns the latest. */
+  version?: string;
+  /** Disambiguate when multiple installed packs ship the same templateId. */
+  libraryId?: string;
+}
+
+/** Request shape for `client.prompts.render(...)` per RFC 0028 §A. */
+export interface RenderPromptRequest {
+  ref: PromptRef;
+  variables: Record<string, unknown>;
+  /**
+   * Aggregate trust marker for the supplied bindings; propagated through
+   * composition per RFC 0027 §E. Defaults to `trusted` when omitted.
+   */
+  contentTrust?: 'trusted' | 'untrusted';
+}
+
+/** Response shape for `client.prompts.render(...)`. The `hash` and
+ *  `variableHashes` are always present; `composed` populates only under
+ *  `capabilities.prompts.observability: "full"`. Same deterministic-hash
+ *  invariant as `prompt.composed` events (RFC 0027 §F). */
+export interface RenderPromptResponse {
+  hash: string;
+  refs: string[];
+  variableHashes: Record<string, string>;
+  composed?: string;
+  contentTrust?: 'trusted' | 'untrusted';
+}
+
 /**
  * Thrown when the server returns a non-2xx response. Carries the original
  * status, parsed error envelope (if available), the raw response text,

package/src/webhook-helpers.ts

@@ -0,0 +1,131 @@
+/**
+ * Webhook delivery-verification helpers per `spec/v1/webhooks.md`
+ * §"Signature recipe". Receivers MUST verify both the HMAC AND the
+ * timestamp freshness before accepting a delivery — verifying HMAC
+ * alone leaves the receiver open to replay attacks.
+ *
+ * The canonical signing recipe:
+ *
+ *     hmac = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
+ *     header `openwop-Webhook-Signature: v1=<hmac-hex>`
+ *     header `openwop-Webhook-Timestamp: <unix-seconds>`
+ *
+ * Verification:
+ *
+ *   1. Parse the `v1=<hex>` value from the signature header.
+ *   2. Recompute `expected = HMAC-SHA256(secret, `${timestamp}.${rawBody}`)`.
+ *   3. Compare using **constant-time** equality (timing-safe).
+ *   4. Reject when `|now - timestamp|` exceeds the freshness window
+ *      (default 5 minutes per `webhooks.md`'s recommendation).
+ *
+ * Implementation note: this helper uses `node:crypto`'s `timingSafeEqual`
+ * for the comparison. The browser-side equivalent (Web Crypto's
+ * `subtle.verify`) is not wrapped here — the SDK's runtime is Node.
+ *
+ * @module @openwop/openwop/webhook-helpers
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/** Default freshness window per `spec/v1/webhooks.md` §"Replay attack resistance". */
+export const DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS = 300;
+
+export interface VerifyWebhookSignatureOptions {
+  /**
+   * Maximum age in seconds for the delivery timestamp before it's
+   * treated as a replay. Default 300 (5 minutes) per the spec.
+   * Set to 0 to disable timestamp checks (NOT recommended).
+   */
+  freshnessWindowSeconds?: number;
+  /**
+   * Override the "now" timestamp in unix seconds. Useful for testing.
+   * Default `Math.floor(Date.now() / 1000)`.
+   */
+  nowSeconds?: number;
+}
+
+export type VerifyWebhookOutcome =
+  | { valid: true }
+  | { valid: false; reason: 'signature_mismatch' | 'timestamp_expired' | 'timestamp_too_far_in_future' | 'malformed_signature_header' | 'malformed_timestamp_header' };
+
+/**
+ * Verify a webhook delivery per `spec/v1/webhooks.md` §"Signature
+ * recipe". Returns `{ valid: true }` on success; otherwise
+ * `{ valid: false, reason }` so callers can log + alert appropriately.
+ *
+ * Callers MUST pass the **raw** body bytes — JSON-parsed-then-
+ * re-serialized bodies will fail verification because the host
+ * signs the exact bytes it delivered.
+ *
+ * @param secret The pre-shared secret returned from `webhooks.register`.
+ * @param signatureHeader The value of the `openwop-Webhook-Signature` header (e.g., `"v1=abc123…"`).
+ * @param timestampHeader The value of the `openwop-Webhook-Timestamp` header (unix seconds as string).
+ * @param rawBody The exact request body bytes the host POSTed.
+ */
+export function verifyWebhookSignature(
+  secret: string,
+  signatureHeader: string,
+  timestampHeader: string,
+  rawBody: string | Buffer,
+  options: VerifyWebhookSignatureOptions = {},
+): VerifyWebhookOutcome {
+  // 1. Parse the signature header.
+  if (!signatureHeader.startsWith('v1=')) {
+    return { valid: false, reason: 'malformed_signature_header' };
+  }
+  const providedHex = signatureHeader.slice(3);
+  if (!/^[0-9a-f]+$/i.test(providedHex)) {
+    return { valid: false, reason: 'malformed_signature_header' };
+  }
+
+  // 2. Parse the timestamp.
+  const timestamp = Number(timestampHeader);
+  if (!Number.isInteger(timestamp) || timestamp <= 0) {
+    return { valid: false, reason: 'malformed_timestamp_header' };
+  }
+
+  // 3. Freshness check.
+  const window = options.freshnessWindowSeconds ?? DEFAULT_WEBHOOK_FRESHNESS_WINDOW_SECONDS;
+  if (window > 0) {
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    const delta = now - timestamp;
+    if (delta > window) return { valid: false, reason: 'timestamp_expired' };
+    // Allow small future skew (within the window) but reject far-future timestamps.
+    if (delta < -window) return { valid: false, reason: 'timestamp_too_far_in_future' };
+  }
+
+  // 4. Recompute + constant-time compare.
+  const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+  const signedBytes = `${timestamp}.${bodyStr}`;
+  const expectedHex = createHmac('sha256', secret).update(signedBytes, 'utf8').digest('hex');
+
+  const providedBuf = Buffer.from(providedHex, 'hex');
+  const expectedBuf = Buffer.from(expectedHex, 'hex');
+  if (providedBuf.length !== expectedBuf.length) {
+    return { valid: false, reason: 'signature_mismatch' };
+  }
+  if (!timingSafeEqual(providedBuf, expectedBuf)) {
+    return { valid: false, reason: 'signature_mismatch' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Compute the canonical webhook signature for a payload — useful when
+ * implementing a host (forward direction) OR when generating test
+ * fixtures. Receivers verify via `verifyWebhookSignature`; this is the
+ * inverse.
+ */
+export function signWebhookDelivery(
+  secret: string,
+  timestamp: number,
+  rawBody: string | Buffer,
+): { signatureHeader: string; timestampHeader: string } {
+  const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+  const hex = createHmac('sha256', secret).update(`${timestamp}.${bodyStr}`, 'utf8').digest('hex');
+  return {
+    signatureHeader: `v1=${hex}`,
+    timestampHeader: String(timestamp),
+  };
+}