@openwop/openwop 1.1.1 → 1.1.2

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());
+  }
+}

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,