modelrig 0.9.0 → 0.10.0

package/dist/prompts/prompt-fetch.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * PSR-2b — SDK fetch-by-label + the content-addressed prompt cache (spec §3
+ * "SDK read", §4). The remote half of serving a prompt by its movable `prod`
+ * label.
+ *
+ * The gateway already serves the promoted version's template+manifest through
+ * `routes.bundle` (PSR-2a's write-through). This module adds the OPTIONAL
+ * explicit read the SDK uses when it wants a prompt by label directly:
+ *   GET /v1/prompts/:route?label=prod   (key-auth, org-scoped)
+ *     → { version, template, manifest, template_sha }
+ *   ETag: <template_sha>                (304 Not Modified when it matches)
+ *
+ * The fetcher mirrors `call-config.ts`'s leak discipline: header-only auth, no
+ * body/URL in an error (C2), and it NEVER throws — a network/HTTP failure
+ * resolves `null`, a 304 resolves `"not-modified"`, a malformed 200 resolves
+ * `null`. So the fail-open resolver ({@link ./prompt-resolve}) always stays
+ * fail-open around it.
+ *
+ * The cache is CONTENT-ADDRESSED, keyed `label+template_sha` (spec §3): the
+ * same served content is one entry regardless of how many times it is fetched,
+ * and a per-(route,label) pointer records the last-known-good sha — the tier the
+ * resolver falls back to when the control plane is unreachable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseServedPrompt = parseServedPrompt;
+exports.createPromptCache = createPromptCache;
+exports.createApiPromptFetcher = createApiPromptFetcher;
+const manifest_1 = require("./manifest");
+/**
+ * Narrow an untrusted endpoint body into a {@link ServedPrompt}, or null when the
+ * shape is not what the endpoint promises (a malformed 200 is a miss, never
+ * trusted — we never fabricate a served prompt from junk). The manifest is
+ * validated with the shared {@link validateManifest} so a structurally-broken
+ * manifest can never reach the client-fill engine.
+ */
+function parseServedPrompt(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return null;
+    const b = body;
+    if (typeof b.version !== "number" || !Number.isInteger(b.version))
+        return null;
+    if (typeof b.template !== "string")
+        return null;
+    if (typeof b.template_sha !== "string" || b.template_sha === "")
+        return null;
+    const validation = (0, manifest_1.validateManifest)(b.manifest);
+    if (!validation.ok)
+        return null;
+    return {
+        version: b.version,
+        template: b.template,
+        manifest: validation.manifest,
+        template_sha: b.template_sha,
+    };
+}
+const KEY_SEP = "\0"; // NUL — cannot appear in a route/label/sha identifier.
+function contentKey(route, label, sha) {
+    return `${route}${KEY_SEP}${label}${KEY_SEP}${sha}`;
+}
+function pointerKey(route, label) {
+    return `${route}${KEY_SEP}${label}`;
+}
+/** Build an empty {@link PromptCache}. One per rig. In-memory only — a prompt
+ * cache is a per-process convenience, never durable state. */
+function createPromptCache() {
+    const content = new Map();
+    const pointer = new Map(); // (route,label) → last-known-good sha
+    return {
+        get(route, label, sha) {
+            return content.get(contentKey(route, label, sha));
+        },
+        lastKnown(route, label) {
+            const sha = pointer.get(pointerKey(route, label));
+            return sha === undefined ? undefined : content.get(contentKey(route, label, sha));
+        },
+        lastKnownSha(route, label) {
+            return pointer.get(pointerKey(route, label));
+        },
+        put(route, label, prompt) {
+            content.set(contentKey(route, label, prompt.template_sha), prompt);
+            pointer.set(pointerKey(route, label), prompt.template_sha);
+        },
+    };
+}
+/**
+ * The api-mode prompt fetcher: one authenticated, ETag-aware GET per (route,
+ * label). Mirrors the api sink's leak discipline (status only, never the
+ * body/URL in an error — C2). NEVER throws: a network/HTTP failure resolves
+ * null, a 304 resolves "not-modified", a malformed 200 resolves null — so the
+ * resolver stays fail-open.
+ */
+function createApiPromptFetcher(config) {
+    const base = config.ingestUrl.replace(/\/$/, "");
+    const fetchFn = config.fetchFn ?? fetch;
+    return {
+        async fetch(route, label, etag) {
+            const url = `${base}/v1/prompts/${encodeURIComponent(route)}?label=${encodeURIComponent(label)}`;
+            let response;
+            try {
+                response = await fetchFn(url, {
+                    method: "GET",
+                    headers: {
+                        authorization: `Bearer ${config.apiKey}`,
+                        ...(etag !== undefined ? { "if-none-match": etag } : {}),
+                    },
+                });
+            }
+            catch {
+                return null; // network throw — fail-open, keep last-known.
+            }
+            if (response.status === 304)
+                return "not-modified";
+            if (!response.ok)
+                return null;
+            const body = (await response.json().catch(() => null));
+            return parseServedPrompt(body);
+        },
+    };
+}

package/dist/prompts/prompt-resolve.d.ts

@@ -0,0 +1,76 @@
+/**
+ * PSR-2b — the fail-open prompt resolver (spec §4 "Fail-open", HARD requirement).
+ *
+ * The template fetch is the ONLY remote part of serving a prompt; the SDK stays
+ * in-process. A control-plane blip must NEVER block a call, so this resolver
+ * degrades exactly like the artifact namespace already does — through named
+ * tiers, in order:
+ *
+ *   1. cache-fresh    — within `ttlMs` of the last fetch, serve the cached
+ *                       last-known-good with no network at all.
+ *   2. fetch          — revalidate by ETag (`template_sha`); a new version is
+ *                       cached and served, a 304 keeps the cache.
+ *   3. last-known-good — the fetch failed/miss, but a version was fetched before:
+ *                       serve the cached last-known-good.
+ *   4. embedded        — never fetched successfully, and the fetch is failing:
+ *                       serve the embedded/pinned template (the last export or a
+ *                       bundled default) supplied by the app.
+ *
+ * If every tier is empty (never fetched, no embedded) the resolver returns
+ * `null` — "no PSR prompt; use your existing bundle serve path" (which itself
+ * fail-opens). So a call is never BLOCKED by the control plane: it is served the
+ * best template available, or falls through to the pre-PSR path.
+ *
+ * `resolve` NEVER throws. It is the fail-open envelope around the fetcher (which
+ * already never throws) and the cache (in-memory).
+ */
+import type { PromptCache, PromptFetcher, ServedPrompt } from "./prompt-fetch";
+/** Where a resolution came from — the served tier (spec §4). Surfaced so status
+ * / a test can prove which fail-open tier answered a call. */
+export type PromptServeSource = "cache" | "fetch" | "last-known-good" | "embedded";
+/** A resolved served prompt plus the tier that answered. */
+export interface ServedPromptResolution {
+    readonly prompt: ServedPrompt;
+    readonly source: PromptServeSource;
+}
+/**
+ * The embedded/pinned templates the app ships as the last-resort floor (spec
+ * §4: "the last export or a bundled default"). Keyed by (route,label); a `get`
+ * miss just means no floor for that label — the resolver returns null and the
+ * caller uses its existing bundle path.
+ */
+export interface EmbeddedPrompts {
+    get(route: string, label: string): ServedPrompt | undefined;
+}
+/** Build an {@link EmbeddedPrompts} from a plain in-memory table (the common
+ * case: a small set of bundled defaults or the last export the app pins). */
+export declare function createEmbeddedPrompts(table?: Readonly<Record<string, Readonly<Record<string, ServedPrompt>>>>): EmbeddedPrompts;
+export interface PromptResolverConfig {
+    readonly fetcher: PromptFetcher;
+    readonly cache: PromptCache;
+    /** The last-resort floor. Absent ⇒ tier 4 is empty (a cold fetch failure
+     * returns null ⇒ the caller's existing bundle path). */
+    readonly embedded?: EmbeddedPrompts;
+    /** Cache freshness window (spec §4, parity with call-config ~30–60s). Within
+     * it, no fetch — serve the cached last-known-good. */
+    readonly ttlMs: number;
+    /** Injectable clock for tests; defaults to Date.now. */
+    readonly now?: () => number;
+}
+export interface PromptResolver {
+    /**
+     * Resolve `route`'s prompt for `label`, fail-open through the tiers above.
+     * NEVER throws. Returns null only when every tier is empty (⇒ the caller
+     * serves its existing bundle, which itself fail-opens).
+     */
+    resolve(route: string, label: string): Promise<ServedPromptResolution | null>;
+}
+/**
+ * Build the fail-open prompt resolver (spec §4). Holds a per-(route,label) fetch
+ * timestamp so a read within `ttlMs` skips the network; a stale read revalidates
+ * by ETag and folds the result into the cache. Every failure path falls to the
+ * next tier — last-known-good, then embedded, then null — so a control-plane
+ * outage never blocks a call.
+ */
+export declare function createPromptResolver(config: PromptResolverConfig): PromptResolver;
+//# sourceMappingURL=prompt-resolve.d.ts.map

package/dist/prompts/prompt-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-resolve.d.ts","sourceRoot":"","sources":["../../src/prompts/prompt-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE/E;8DAC8D;AAC9D,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,iBAAiB,GAAG,UAAU,CAAC;AAEnF,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;CAC7D;AAED;6EAC6E;AAC7E,wBAAgB,qBAAqB,CACnC,KAAK,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAM,GAC3E,eAAe,CAMjB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B;4DACwD;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC;0DACsD;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;CAC/E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CA+CjF"}

package/dist/prompts/prompt-resolve.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * PSR-2b — the fail-open prompt resolver (spec §4 "Fail-open", HARD requirement).
+ *
+ * The template fetch is the ONLY remote part of serving a prompt; the SDK stays
+ * in-process. A control-plane blip must NEVER block a call, so this resolver
+ * degrades exactly like the artifact namespace already does — through named
+ * tiers, in order:
+ *
+ *   1. cache-fresh    — within `ttlMs` of the last fetch, serve the cached
+ *                       last-known-good with no network at all.
+ *   2. fetch          — revalidate by ETag (`template_sha`); a new version is
+ *                       cached and served, a 304 keeps the cache.
+ *   3. last-known-good — the fetch failed/miss, but a version was fetched before:
+ *                       serve the cached last-known-good.
+ *   4. embedded        — never fetched successfully, and the fetch is failing:
+ *                       serve the embedded/pinned template (the last export or a
+ *                       bundled default) supplied by the app.
+ *
+ * If every tier is empty (never fetched, no embedded) the resolver returns
+ * `null` — "no PSR prompt; use your existing bundle serve path" (which itself
+ * fail-opens). So a call is never BLOCKED by the control plane: it is served the
+ * best template available, or falls through to the pre-PSR path.
+ *
+ * `resolve` NEVER throws. It is the fail-open envelope around the fetcher (which
+ * already never throws) and the cache (in-memory).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmbeddedPrompts = createEmbeddedPrompts;
+exports.createPromptResolver = createPromptResolver;
+/** Build an {@link EmbeddedPrompts} from a plain in-memory table (the common
+ * case: a small set of bundled defaults or the last export the app pins). */
+function createEmbeddedPrompts(table = {}) {
+    return {
+        get(route, label) {
+            return table[route]?.[label];
+        },
+    };
+}
+/**
+ * Build the fail-open prompt resolver (spec §4). Holds a per-(route,label) fetch
+ * timestamp so a read within `ttlMs` skips the network; a stale read revalidates
+ * by ETag and folds the result into the cache. Every failure path falls to the
+ * next tier — last-known-good, then embedded, then null — so a control-plane
+ * outage never blocks a call.
+ */
+function createPromptResolver(config) {
+    const now = config.now ?? (() => Date.now());
+    const { fetcher, cache, embedded } = config;
+    const fetchedAt = new Map(); // (route,label) → last fetch ts
+    const stamp = (route, label) => `${route}\0${label}`;
+    /** The last-known-good or embedded floor, in that order, or null. */
+    function floor(route, label) {
+        const known = cache.lastKnown(route, label);
+        if (known !== undefined)
+            return { prompt: known, source: "last-known-good" };
+        const pinned = embedded?.get(route, label);
+        if (pinned !== undefined)
+            return { prompt: pinned, source: "embedded" };
+        return null;
+    }
+    return {
+        async resolve(route, label) {
+            const key = stamp(route, label);
+            const last = fetchedAt.get(key);
+            const cached = cache.lastKnown(route, label);
+            // Tier 1 — cache-fresh: within the TTL of a prior fetch, no network.
+            if (cached !== undefined && last !== undefined && now() - last < config.ttlMs) {
+                return { prompt: cached, source: "cache" };
+            }
+            try {
+                // Tier 2 — fetch, ETag-revalidated against the last-known-good sha.
+                const result = await fetcher.fetch(route, label, cache.lastKnownSha(route, label));
+                if (result === "not-modified") {
+                    fetchedAt.set(key, now());
+                    // 304 ⇒ the cached last-known-good is current.
+                    return floor(route, label);
+                }
+                if (result === null) {
+                    // Miss/error ⇒ tiers 3–4 (last-known-good, then embedded).
+                    return floor(route, label);
+                }
+                cache.put(route, label, result);
+                fetchedAt.set(key, now());
+                return { prompt: result, source: "fetch" };
+            }
+            catch {
+                // The hot path never throws — fall to the fail-open floor.
+                return floor(route, label);
+            }
+        },
+    };
+}

package/dist/prompts/slot-resolver.d.ts

@@ -0,0 +1,91 @@
+/**
+ * PSR-2b — the client-fill engine (spec §4 "two-layer resolution", ADJ-2;
+ * authoring-guide §5–§6). Resolves a served {@link Manifest} into an assembled
+ * prompt string, ENTIRELY in the customer's process.
+ *
+ * Per call the SDK walks the manifest's slots IN ORDER (order = send order, D6)
+ * and fills each one:
+ *   • `static`            → authored text (inline `text`, or `from: system|template`)
+ *   • `dynamic·tool`      → the registered {@link ToolFn}, run in-process with the
+ *                           customer's keys (spec §4)
+ *   • `dynamic·cache`     → the declared cache handle, read by the caller's reader
+ *   • `dynamic·upstream`  → the prior step's APPROVED output (from the caller)
+ *   • `dynamic·variable`  → the call's variable whitelist
+ * then assembles the resolved parts in order. The assembled text is a plain
+ * string the caller dispatches through the existing `rig.run`/`runRaw` seam.
+ *
+ * FAIL CLOSED, NEVER SILENT (spec §4, HARD requirement). A `dynamic·tool` slot
+ * whose tool is not registered throws a teaching {@link SlotResolutionError} that
+ * NAMES the missing tool and what IS bound — never an empty slot, never a silent
+ * skip. The same discipline covers every dynamic kind: a slot that cannot be
+ * filled from what the caller provided fails closed, so a half-assembled prompt
+ * is never dispatched.
+ *
+ * PRIVACY: this module has ZERO network/telemetry imports. Its inputs (tool fns,
+ * cache reader, upstream outputs, variables) and its output (the assembled text)
+ * are all in-process values. Nothing tool-derived is sent anywhere — assembly is
+ * a local computation. That is the "tool keys + dynamic data never leave the
+ * process" guarantee, structural rather than promised.
+ */
+import type { Manifest } from "./manifest";
+import type { ToolRegistry } from "./tools-register";
+/** Reads a `dynamic·cache` slot's declared handle into text, in-process. Async
+ * (a cache is usually an out-of-band read). The handle is the slot's
+ * `source.ref`; the reader is the customer's — ModelRig never reads it. */
+export type CacheReader = (handle: string) => string | Promise<string>;
+/**
+ * Everything the resolver needs to fill slots — supplied by the caller, all
+ * in-process. Only the kinds a given manifest uses need be present; a slot of a
+ * kind the caller did not provide for FAILS CLOSED (never a silent empty slot).
+ */
+export interface SlotResolveContext {
+    /** The authored template text a `from: template` static slot pulls (the served
+     * `ServedPrompt.template`). */
+    readonly template: string;
+    /** The authored system text a `from: system` static slot pulls, when the
+     * manifest declares one. */
+    readonly system?: string;
+    /** The tool bindings (`rig.tools`) a `dynamic·tool` slot resolves against. */
+    readonly tools: ToolRegistry;
+    /** The variable whitelist — the customer's own call inputs. A
+     * `dynamic·variable` slot reads `variables[ref]`; also passed to each tool as
+     * its {@link ToolResolveContext.input}. */
+    readonly variables?: Readonly<Record<string, unknown>>;
+    /** Reader for `dynamic·cache` slots. Absent ⇒ a cache slot fails closed. */
+    readonly cache?: CacheReader;
+    /** Prior steps' APPROVED outputs, keyed by step key — a `dynamic·upstream`
+     * slot reads `upstream[ref]`. Absent/missing ref ⇒ fails closed. */
+    readonly upstream?: Readonly<Record<string, string>>;
+}
+/** One resolved slot: its id and the text it contributed, in send order. */
+export interface ResolvedSlot {
+    readonly id: string;
+    readonly text: string;
+}
+/** The assembled prompt plus the per-slot parts (send order preserved). `text`
+ * is `parts` joined with a blank line — the string the caller dispatches. */
+export interface AssembledPrompt {
+    readonly text: string;
+    readonly parts: readonly ResolvedSlot[];
+}
+/**
+ * A slot that could not be filled — the fail-closed signal (spec §4). Carries
+ * the slot id and a teaching message; the tool-unbound case names the missing
+ * tool and the bound names, so the fix is obvious at the call site.
+ */
+export declare class SlotResolutionError extends Error {
+    readonly slotId: string;
+    constructor(slotId: string, message: string);
+}
+/**
+ * Resolve every slot of a served manifest IN ORDER and assemble the prompt
+ * (spec §4). Slots resolve sequentially so `upstream` ordering and any
+ * side-effecting tool run in declared send order. Throws
+ * {@link SlotResolutionError} on the FIRST slot that cannot be filled — the
+ * prompt is never dispatched half-assembled (fail closed).
+ *
+ * Pure over its inputs apart from the tool/cache functions the caller supplies,
+ * which run in-process. The returned {@link AssembledPrompt} is a local value.
+ */
+export declare function assemblePrompt(manifest: Manifest, ctx: SlotResolveContext): Promise<AssembledPrompt>;
+//# sourceMappingURL=slot-resolver.d.ts.map

package/dist/prompts/slot-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot-resolver.d.ts","sourceRoot":"","sources":["../../src/prompts/slot-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAQ,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;2EAE2E;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;mCAC+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;gCAC4B;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;+CAE2C;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B;wEACoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;6EAC6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACzC;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAiGD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,eAAe,CAAC,CAO1B"}

package/dist/prompts/slot-resolver.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * PSR-2b — the client-fill engine (spec §4 "two-layer resolution", ADJ-2;
+ * authoring-guide §5–§6). Resolves a served {@link Manifest} into an assembled
+ * prompt string, ENTIRELY in the customer's process.
+ *
+ * Per call the SDK walks the manifest's slots IN ORDER (order = send order, D6)
+ * and fills each one:
+ *   • `static`            → authored text (inline `text`, or `from: system|template`)
+ *   • `dynamic·tool`      → the registered {@link ToolFn}, run in-process with the
+ *                           customer's keys (spec §4)
+ *   • `dynamic·cache`     → the declared cache handle, read by the caller's reader
+ *   • `dynamic·upstream`  → the prior step's APPROVED output (from the caller)
+ *   • `dynamic·variable`  → the call's variable whitelist
+ * then assembles the resolved parts in order. The assembled text is a plain
+ * string the caller dispatches through the existing `rig.run`/`runRaw` seam.
+ *
+ * FAIL CLOSED, NEVER SILENT (spec §4, HARD requirement). A `dynamic·tool` slot
+ * whose tool is not registered throws a teaching {@link SlotResolutionError} that
+ * NAMES the missing tool and what IS bound — never an empty slot, never a silent
+ * skip. The same discipline covers every dynamic kind: a slot that cannot be
+ * filled from what the caller provided fails closed, so a half-assembled prompt
+ * is never dispatched.
+ *
+ * PRIVACY: this module has ZERO network/telemetry imports. Its inputs (tool fns,
+ * cache reader, upstream outputs, variables) and its output (the assembled text)
+ * are all in-process values. Nothing tool-derived is sent anywhere — assembly is
+ * a local computation. That is the "tool keys + dynamic data never leave the
+ * process" guarantee, structural rather than promised.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SlotResolutionError = void 0;
+exports.assemblePrompt = assemblePrompt;
+/**
+ * A slot that could not be filled — the fail-closed signal (spec §4). Carries
+ * the slot id and a teaching message; the tool-unbound case names the missing
+ * tool and the bound names, so the fix is obvious at the call site.
+ */
+class SlotResolutionError extends Error {
+    constructor(slotId, message) {
+        super(message);
+        this.name = "SlotResolutionError";
+        this.slotId = slotId;
+    }
+}
+exports.SlotResolutionError = SlotResolutionError;
+/** The separator between assembled slot parts — a blank line, so adjacent blocks
+ * stay legible and a cache `prefix` slot keeps a stable boundary. */
+const PART_SEPARATOR = "\n\n";
+/** Resolve ONE slot to its text, or throw {@link SlotResolutionError} (fail
+ * closed). Every branch either returns a concrete string or throws — a slot
+ * never resolves to `undefined`/empty by omission. */
+async function resolveSlot(slot, ctx) {
+    if (slot.kind === "static") {
+        if (slot.text !== undefined)
+            return slot.text;
+        if (slot.from === "template")
+            return ctx.template;
+        if (slot.from === "system") {
+            if (ctx.system === undefined) {
+                throw new SlotResolutionError(slot.id, `static slot "${slot.id}" references \`from: system\`, but no authored ` +
+                    "`system` text was provided to the resolver");
+            }
+            return ctx.system;
+        }
+        // A validated manifest guarantees text XOR from; this is unreachable for a
+        // validated slot, but fail closed rather than emit an empty slot.
+        throw new SlotResolutionError(slot.id, `static slot "${slot.id}" has neither inline \`text\` nor a \`from\` reference`);
+    }
+    // dynamic — a validated manifest guarantees a well-formed `source`.
+    const source = slot.source;
+    if (source === undefined) {
+        throw new SlotResolutionError(slot.id, `dynamic slot "${slot.id}" is missing its \`source\``);
+    }
+    const ref = source.ref;
+    switch (source.kind) {
+        case "tool": {
+            const fn = ctx.tools.get(ref);
+            if (fn === undefined) {
+                const bound = ctx.tools.names();
+                const boundList = bound.length > 0 ? `bound tools: ${bound.join(", ")}` : "no tools are bound";
+                throw new SlotResolutionError(slot.id, `slot "${slot.id}" needs tool "${ref}", but it is not bound — call ` +
+                    `rig.tools.register("${ref}", fn) before this route runs (${boundList}). ` +
+                    "The prompt was NOT sent with an empty slot (spec §4, fail closed).");
+            }
+            return fn({ ref, input: ctx.variables ?? {} });
+        }
+        case "cache": {
+            if (ctx.cache === undefined) {
+                throw new SlotResolutionError(slot.id, `slot "${slot.id}" needs cache handle "${ref}", but no cache reader was ` +
+                    "provided to the resolver");
+            }
+            return ctx.cache(ref);
+        }
+        case "upstream": {
+            const value = ctx.upstream?.[ref];
+            if (value === undefined) {
+                throw new SlotResolutionError(slot.id, `slot "${slot.id}" needs the approved output of upstream step "${ref}", ` +
+                    "but it was not provided to the resolver");
+            }
+            return value;
+        }
+        case "variable": {
+            const value = ctx.variables?.[ref];
+            if (value === undefined) {
+                throw new SlotResolutionError(slot.id, `slot "${slot.id}" needs variable "${ref}", but it is not in the call's ` +
+                    "variable whitelist");
+            }
+            return typeof value === "string" ? value : JSON.stringify(value);
+        }
+        default: {
+            // Exhaustive over DynamicSourceKind; a future kind fails closed here.
+            const exhaustive = source.kind;
+            throw new SlotResolutionError(slot.id, `slot "${slot.id}" has an unknown dynamic source kind ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}
+/**
+ * Resolve every slot of a served manifest IN ORDER and assemble the prompt
+ * (spec §4). Slots resolve sequentially so `upstream` ordering and any
+ * side-effecting tool run in declared send order. Throws
+ * {@link SlotResolutionError} on the FIRST slot that cannot be filled — the
+ * prompt is never dispatched half-assembled (fail closed).
+ *
+ * Pure over its inputs apart from the tool/cache functions the caller supplies,
+ * which run in-process. The returned {@link AssembledPrompt} is a local value.
+ */
+async function assemblePrompt(manifest, ctx) {
+    const parts = [];
+    for (const slot of manifest.slots) {
+        const text = await resolveSlot(slot, ctx);
+        parts.push({ id: slot.id, text });
+    }
+    return { text: parts.map((p) => p.text).join(PART_SEPARATOR), parts };
+}

package/dist/prompts/tools-register.d.ts

@@ -0,0 +1,60 @@
+/**
+ * PSR-2b — the client-side tool-binding registry (spec §4 ADJ-2, authoring-guide
+ * §5). The client-fill half of the prompt system-of-record.
+ *
+ * A `dynamic·tool` manifest slot NAMES a tool (`source.ref`, e.g.
+ * `"search_tickets"`); it carries no code and no data (structure-only, D6). To
+ * fill that slot at call time the SDK needs a **client-side binding** from that
+ * name to a function that runs IN THE CUSTOMER'S PROCESS, with the customer's
+ * keys. `rig.tools.register(name, fn)` is that binding.
+ *
+ * The privacy guarantee lives here: a bound tool `fn` closes over the customer's
+ * credentials and does its work locally; ModelRig only ever knows the tool's
+ * NAME (already in the manifest). Nothing this registry holds — not a fn, not a
+ * key it closes over, not a value it returns — is ever serialized or sent
+ * anywhere. This module has ZERO network/telemetry imports, by design, so
+ * "tool keys never leave the process" is a structural property, not a promise.
+ *
+ * Pure + dependency-free.
+ */
+/**
+ * The context a bound tool receives when the SDK resolves its slot. Carries the
+ * tool NAME being filled and the call's variable whitelist (the same values a
+ * `dynamic·variable` slot draws from) so a tool can shape its work from the
+ * call's inputs — never anything ModelRig-side. Read-only: a tool observes, it
+ * does not mutate the call.
+ */
+export interface ToolResolveContext {
+    /** The tool name being resolved (the slot's `source.ref`). */
+    readonly ref: string;
+    /** The call's variable whitelist — the customer's own inputs, in-process. */
+    readonly input: Readonly<Record<string, unknown>>;
+}
+/**
+ * A bound tool: runs in-process with the customer's keys and returns the text
+ * to place in its slot. May be async (a tool usually calls out to the customer's
+ * own upstream). Whatever it returns stays local — it becomes the slot's filled
+ * text and is assembled into the prompt on the customer's machine.
+ */
+export type ToolFn = (ctx: ToolResolveContext) => string | Promise<string>;
+/**
+ * The registry backing `rig.tools`. `register` binds a name → fn (last write
+ * wins, so a re-register is a rebind, never a silent duplicate); `get`/`has`
+ * look a binding up by name; `names` lists the bound names (for a teaching
+ * error). Never throws on read — the caller decides what a missing binding
+ * means (the slot resolver FAILS CLOSED with a teaching error, spec §4).
+ */
+export interface ToolRegistry {
+    /** Bind `name` to `fn`. Rejects an empty name or a non-function with a
+     * teaching error — a misbinding is a bug at the developer's machine, surfaced
+     * at register time, never a mystery at call time. */
+    register(name: string, fn: ToolFn): void;
+    get(name: string): ToolFn | undefined;
+    has(name: string): boolean;
+    /** The bound names, sorted — used to name what IS available when a slot
+     * references a tool that is not. */
+    names(): readonly string[];
+}
+/** Build an empty {@link ToolRegistry}. One per rig; `rig.tools` exposes it. */
+export declare function createToolRegistry(): ToolRegistry;
+//# sourceMappingURL=tools-register.d.ts.map

package/dist/prompts/tools-register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-register.d.ts","sourceRoot":"","sources":["../../src/prompts/tools-register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,kBAAkB,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;yDAEqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B;wCACoC;IACpC,KAAK,IAAI,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,IAAI,YAAY,CA4BjD"}

package/dist/prompts/tools-register.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * PSR-2b — the client-side tool-binding registry (spec §4 ADJ-2, authoring-guide
+ * §5). The client-fill half of the prompt system-of-record.
+ *
+ * A `dynamic·tool` manifest slot NAMES a tool (`source.ref`, e.g.
+ * `"search_tickets"`); it carries no code and no data (structure-only, D6). To
+ * fill that slot at call time the SDK needs a **client-side binding** from that
+ * name to a function that runs IN THE CUSTOMER'S PROCESS, with the customer's
+ * keys. `rig.tools.register(name, fn)` is that binding.
+ *
+ * The privacy guarantee lives here: a bound tool `fn` closes over the customer's
+ * credentials and does its work locally; ModelRig only ever knows the tool's
+ * NAME (already in the manifest). Nothing this registry holds — not a fn, not a
+ * key it closes over, not a value it returns — is ever serialized or sent
+ * anywhere. This module has ZERO network/telemetry imports, by design, so
+ * "tool keys never leave the process" is a structural property, not a promise.
+ *
+ * Pure + dependency-free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolRegistry = createToolRegistry;
+/** Build an empty {@link ToolRegistry}. One per rig; `rig.tools` exposes it. */
+function createToolRegistry() {
+    const bindings = new Map();
+    return {
+        register(name, fn) {
+            if (typeof name !== "string" || name.length === 0) {
+                throw new Error("rig.tools.register: the tool name must be a non-empty string (it is the " +
+                    "name a `dynamic·tool` manifest slot references)");
+            }
+            if (typeof fn !== "function") {
+                throw new Error(`rig.tools.register: the binding for tool "${name}" must be a function ` +
+                    "(it runs in-process with your keys to fill the slot)");
+            }
+            bindings.set(name, fn);
+        },
+        get(name) {
+            return bindings.get(name);
+        },
+        has(name) {
+            return bindings.has(name);
+        },
+        names() {
+            return [...bindings.keys()].sort();
+        },
+    };
+}