@openwop/openwop 1.1.0 → 1.1.2

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,18 @@
 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';
 //# 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"}

package/dist/index.js

@@ -12,8 +12,25 @@
 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';
 //# 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"}

package/dist/registry-helpers.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 declare class RegistryClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(options?: RegistryClientOptions);
+    /** `GET /.well-known/openwop-registry` — discovery + endpoint catalog. */
+    discovery(): Promise<RegistryDiscovery>;
+    /** `GET /v1/index.json` — registry-wide pack index. */
+    index(): Promise<RegistryIndex>;
+    /** `GET /v1/packs/{name}/index.json` — per-pack metadata. */
+    pack(name: string): Promise<RegistryPackMetadata>;
+    /** `GET /v1/packs/{name}/-/{version}.json` — version manifest. */
+    version(name: string, version: string): Promise<RegistryVersionManifest>;
+    /** Fetch raw tarball bytes. Caller MUST verify SRI + signature before trust. */
+    tarball(name: string, version: string): Promise<Buffer>;
+    /** Fetch raw 64-byte Ed25519 signature bytes. */
+    signature(name: string, version: string): Promise<Buffer>;
+    /** Fetch a publisher's public key as PEM text. */
+    publicKey(keyId: string): Promise<string>;
+}
+//# sourceMappingURL=registry-helpers.d.ts.map

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

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

package/dist/registry-helpers.js

@@ -0,0 +1,82 @@
+/**
+ * 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
+ */
+/**
+ * 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 {
+    baseUrl;
+    #fetch;
+    constructor(options = {}) {
+        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() {
+        return this.#getJson('/.well-known/openwop-registry');
+    }
+    /** `GET /v1/index.json` — registry-wide pack index. */
+    async index() {
+        return this.#getJson('/v1/index.json');
+    }
+    /** `GET /v1/packs/{name}/index.json` — per-pack metadata. */
+    async pack(name) {
+        return this.#getJson(`/v1/packs/${encodeURIComponent(name)}/index.json`);
+    }
+    /** `GET /v1/packs/{name}/-/{version}.json` — version manifest. */
+    async version(name, version) {
+        return this.#getJson(`/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.json`);
+    }
+    /** Fetch raw tarball bytes. Caller MUST verify SRI + signature before trust. */
+    async tarball(name, version) {
+        return this.#getBinary(`/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.tgz`);
+    }
+    /** Fetch raw 64-byte Ed25519 signature bytes. */
+    async signature(name, version) {
+        return this.#getBinary(`/v1/packs/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.sig`);
+    }
+    /** Fetch a publisher's public key as PEM text. */
+    async publicKey(keyId) {
+        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(path) {
+        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());
+    }
+    async #getBinary(path) {
+        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());
+    }
+}
+//# sourceMappingURL=registry-helpers.js.map

package/dist/registry-helpers.js.map

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