@loomwork/ui-hydration 0.0.0-stage → 0.1.0

package/dist/esm/invokers.js

@@ -0,0 +1,310 @@
+import { canonicalJson } from "@loomwork/core";
+import { MCP_INVOKE_TOOL_ID } from "@loomwork/plugin-mcp";
+// ── Invoker wrappers: a call cap, an owner's lifetime signal, an in-pass step memo ─
+// All are TransientInvokers wrapping a TransientInvoker, so they compose with each other and
+// with loom's EffectRuntime without either knowing the other exists. The in-process controller
+// builds ONE `limitInvoker` (the cap is controller-wide: it bounds every call it makes), ONE
+// `signalInvoker` over it bound to its own lifetime (so `dispose` cancels every upstream call at
+// once), and one `memoInvoker` PER PASS in front of both (a memo hit takes no slot). The split
+// server (`serveHandles`, split.ts) composes a memo over a cap the same way, once per batch.
+// None ever returns a promise it did not get from the inner invoker except to wait for a slot,
+// so they add no settle latency on a free slot.
+/**
+ * The rejection for a call abandoned because its signal aborted. Named `AbortError` (the
+ * platform's own name for a cancelled operation) so a consumer classifies it by `name` — a
+ * planner's decider must propagate a cancellation, never retry it or record it as a failed
+ * plan. A plain `Error("aborted")` is indistinguishable from a provider failure. Message kept.
+ */
+function abortError() {
+    const e = new Error("aborted");
+    e.name = "AbortError";
+    return e;
+}
+/**
+ * At most `max` calls in flight through this invoker, across every caller. A queued call whose
+ * signal aborts leaves the queue and rejects `"aborted"` without ever reaching `inner`. FIFO: a
+ * finished call hands its slot straight to the oldest waiter.
+ */
+export function limitInvoker(inner, max) {
+    if (!Number.isInteger(max) || max < 1)
+        throw new RangeError(`limitInvoker: the cap must be a positive integer, got ${String(max)}`);
+    let active = 0;
+    // Insertion-ordered: the first entry is the oldest waiter; add/delete are O(1).
+    const waiting = new Set();
+    const release = () => {
+        const next = waiting.values().next();
+        if (next.done === true) {
+            active -= 1;
+            return;
+        }
+        waiting.delete(next.value);
+        next.value(); // the slot passes to the waiter: `active` is unchanged
+    };
+    const acquire = (signal) => {
+        // Checked before capacity: an already-aborted caller must never take a slot (or reach
+        // `inner`) just because one happened to be free — that slot belongs to the next live caller.
+        if (signal?.aborted === true)
+            return Promise.reject(abortError());
+        if (active < max) {
+            active += 1;
+            return undefined;
+        }
+        return new Promise((resolve, reject) => {
+            const onAbort = () => {
+                waiting.delete(grant);
+                reject(abortError());
+            };
+            const grant = () => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            };
+            waiting.add(grant);
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    };
+    const run = (call) => {
+        let p;
+        try {
+            p = call();
+        }
+        catch (e) {
+            release();
+            return Promise.reject(e);
+        }
+        p.then(release, release);
+        return p;
+    };
+    return {
+        invokeTransient(toolId, input, opts) {
+            const call = () => inner.invokeTransient(toolId, input, opts);
+            const slot = acquire(opts?.signal);
+            return slot === undefined ? run(call) : slot.then(() => run(call));
+        },
+    };
+}
+/** `call()`, with a synchronous throw turned into the rejected promise the contract promises. */
+function callSafely(call) {
+    try {
+        return call();
+    }
+    catch (e) {
+        return Promise.reject(e);
+    }
+}
+/**
+ * Every call through this invoker is ALSO cancelled, synchronously, when `signal` aborts — the
+ * owner's lifetime (a controller's `dispose`), independent of any caller's own signal, which still
+ * reaches `inner` too. Once `signal` has aborted, new calls reject `"aborted"` without reaching
+ * `inner`. Leak-free on a long-lived `signal`: a call holds its listener only until it settles.
+ */
+export function signalInvoker(inner, signal) {
+    return {
+        invokeTransient(toolId, input, opts) {
+            const own = opts?.signal;
+            if (signal.aborted || own?.aborted === true)
+                return Promise.reject(abortError());
+            const ac = new AbortController();
+            const abort = () => ac.abort();
+            signal.addEventListener("abort", abort, { once: true });
+            own?.addEventListener("abort", abort, { once: true });
+            const release = () => {
+                signal.removeEventListener("abort", abort);
+                own?.removeEventListener("abort", abort);
+            };
+            const p = callSafely(() => inner.invokeTransient(toolId, input, { ...opts, signal: ac.signal }));
+            p.then(release, release);
+            return p;
+        },
+    };
+}
+/**
+ * The shape `canonicalJson` actually understands — null/string/finite-number/boolean, and arrays
+ * or plain objects (`Object.prototype` or `null` as the prototype) built from those, recursively.
+ * `canonicalJson` does not THROW on a `Date`, `Map`, `Set` or a class instance — it silently reads
+ * `Object.keys()` on it, which for most of those is `[]`, so two calls with DIFFERENT such
+ * arguments would canonicalize to the same `"{}"` and collide on one memo key. Reject those before
+ * a key is ever computed, not after: `memoInvoker` must never be the reason a value collapses.
+ *
+ * `seen` makes this cycle-safe: a hostile or accidental circular reference is walked at most once
+ * per object (the second visit reports "not plain" rather than recursing forever), so a cyclic
+ * argument bypasses the memo instead of throwing `RangeError: Maximum call stack size exceeded`
+ * out of `invokeTransient`. Sharing one `seen` set across a whole call's plainness check is
+ * deliberately conservative: a repeated (non-cyclic) reference is also flagged "not plain" and
+ * bypasses sharing rather than being memoized — safe, since bypass just means no caching, never a
+ * wrong answer.
+ */
+function isPlainJsonValue(value, seen = new WeakSet()) {
+    if (value === null || value === undefined)
+        return true;
+    const t = typeof value;
+    if (t === "string" || t === "boolean")
+        return true;
+    if (t === "number")
+        return Number.isFinite(value);
+    if (t !== "object")
+        return false; // function, bigint, symbol
+    const obj = value;
+    if (seen.has(obj))
+        return false;
+    seen.add(obj);
+    if (Array.isArray(value))
+        return value.every((v) => isPlainJsonValue(v, seen));
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== Object.prototype && proto !== null)
+        return false;
+    return Object.values(value).every((v) => isPlainJsonValue(v, seen));
+}
+/**
+ * One call per identical MCP step for this invoker's lifetime (a PASS): same tool, same resolved
+ * arguments, same schema pin, same call options — the canonical JSON of `[principal, every other
+ * option except signal, mcp.invoke's input]`, so key order does not matter. A joiner is
+ * served straight from the shared promise — it never calls `inner` itself, so it never passes
+ * through whatever per-call authorizer `inner` enforces. That is safe ONLY because every
+ * authorization input is part of the key: the principal, and also the stamped execution identity
+ * (`as` — an authorizer may grant by workflow), the `label` (which names the transient
+ * execution when `as` is absent) and anything else in the options. Every joiner
+ * sharing one entry was, by construction, asking with the exact inputs the leader's own (sole)
+ * call to `inner` was authorized for; an option that is not plain JSON passes through, uncached. Settled results stay (a step in a later wave is still
+ * served) and failures are shared. Other effects (a sandbox reshape) always run, uncached.
+ *
+ * Cancellation is ref-counted, not leader-owned: `inner` is called once, through an internal
+ * `AbortController` this function owns — never a caller's own signal directly — so any ONE
+ * caller's abort only ever settles that caller's OWN returned promise (a race against the shared
+ * promise). The upstream call itself is cancelled, and the entry forgotten, only once every live
+ * caller has aborted AND the call had not already settled; a caller that arrives after a real
+ * cancellation finds no entry and starts a fresh call.
+ */
+export function memoInvoker(inner) {
+    const memo = new Map();
+    const onCallerAbort = (key, hit) => {
+        hit.live -= 1;
+        if (hit.live > 0)
+            return;
+        // Deferred one microtask: `hit.settled` is set by a handler attached at entry-creation time,
+        // which — because it was attached first — runs before this check for any settlement the memo
+        // can observe, even when the abort lands in the very same synchronous turn as `hit.promise`
+        // settling. Checking `hit.settled` synchronously right here would miss exactly that race.
+        // "The memo can observe" is `hit.promise` — `inner`'s promise — not the raw upstream: behind
+        // a queued `limitInvoker` (or any wrapper that settles a few hops after its own inner call),
+        // an all-abort landing after the RAW upstream settled but before `hit.promise` does still
+        // cancels and evicts, so a later caller re-fetches. A wasted call, never a wrong answer.
+        //
+        // Both conditions below are RE-READ at that later point, not captured now, because either can
+        // change in the gap between "live just dropped to 0" and "the microtask actually runs": a
+        // fresh caller with no signal of its own can join in the very same synchronous turn (bumping
+        // `live` back above 0 before this ever executes), and the upstream can settle in that same
+        // window (flipping `settled` true). A snapshot taken at decrement time would race both ways —
+        // this is why the check happens here, once, right before the one place that acts on it.
+        //
+        // Invariant: the controller is aborted, and the entry deleted, AT MOST ONCE per entry — and
+        // only when, at the moment this specific check runs, `settled` is still false AND `live` is
+        // still <= 0 (no one re-joined). Either condition failing means someone still needs this call
+        // to keep going (or already has its answer), so it is left alone.
+        queueMicrotask(() => {
+            if (hit.settled || hit.live > 0)
+                return;
+            // Forget the entry BEFORE aborting: `abort()` runs `inner`'s listeners synchronously, and a
+            // caller re-entering with the same key from one of them must start a fresh call, not join
+            // this dying one.
+            if (memo.get(key) === hit)
+                memo.delete(key);
+            hit.controller.abort();
+        });
+    };
+    const join = (key, hit, signal) => {
+        if (signal?.aborted === true) {
+            onCallerAbort(key, hit);
+            return Promise.reject(abortError());
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const onAbort = () => {
+                if (settled)
+                    return;
+                settled = true;
+                onCallerAbort(key, hit);
+                reject(abortError());
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            hit.promise.then((v) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                resolve(v);
+            }, (e) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal?.removeEventListener("abort", onAbort);
+                reject(e);
+            });
+        });
+    };
+    return {
+        invokeTransient(toolId, input, opts) {
+            // Every pass-through is guarded like the leader's call: a synchronous throw from `inner`
+            // must come back as a rejected promise, never escape `invokeTransient`.
+            const passThrough = () => callSafely(() => inner.invokeTransient(toolId, input, opts));
+            if (toolId !== MCP_INVOKE_TOOL_ID)
+                return passThrough();
+            // Everything in `opts` except the one field that cannot change the answer (`signal`) is
+            // part of the key: the principal, the stamped identity (`as`, which an authorizer may key
+            // grants on), the `label` (without `as`, the transient executionId is `transient:<label>`,
+            // and an authorizer may grant per execution), the budget snapshot, and any option added
+            // later. Keying on the remainder rather than a list of known fields is what keeps a joiner
+            // from being served a result authorized for a different input this function has never
+            // heard of.
+            const { signal: _signal, principal = null, ...rest } = opts ?? {};
+            let key;
+            try {
+                const seen = new WeakSet();
+                if (!isPlainJsonValue(principal, seen) ||
+                    !isPlainJsonValue(rest, seen) ||
+                    !isPlainJsonValue(input, seen))
+                    return passThrough();
+                key = canonicalJson([principal, rest, input]);
+            }
+            catch {
+                return passThrough();
+            }
+            const hit = memo.get(key);
+            if (hit !== undefined) {
+                hit.live += 1;
+                return join(key, hit, opts?.signal);
+            }
+            // Mirrors limitInvoker's fast path: an already-aborted caller must never become the leader
+            // — that would call `inner`, create an entry nobody asked to keep, and (since nothing here
+            // would yet be subscribed to the resulting promise) risk an unhandled rejection.
+            if (opts?.signal?.aborted === true)
+                return Promise.reject(abortError());
+            const controller = new AbortController();
+            let promise;
+            try {
+                // `inner.invokeTransient` is typed to return a Promise, but a misbehaving implementation
+                // can still throw synchronously; the interface contract (and every caller of THIS
+                // function) requires a rejected promise instead, never a thrown exception. No entry is
+                // created for a call that never actually started.
+                promise = inner.invokeTransient(toolId, input, {
+                    ...opts,
+                    signal: controller.signal,
+                });
+            }
+            catch (e) {
+                return Promise.reject(e);
+            }
+            const entry = { promise, controller, live: 1, settled: false };
+            const onSettle = () => {
+                entry.settled = true;
+            };
+            // Attached at entry-creation time — before any joiner's own `.then` — so `entry.settled`
+            // is set before `onCallerAbort`'s deferred check can run (see there). Also the
+            // backstop: attaching a rejection handler here means NO path can ever leave `promise`
+            // unhandled, even if a future caller subscribes late or never at all.
+            promise.then(onSettle, onSettle);
+            memo.set(key, entry);
+            return join(key, entry, opts?.signal);
+        },
+    };
+}
+//# sourceMappingURL=invokers.js.map

package/dist/esm/invokers.js.map

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

package/dist/esm/loomEffectProvider.js

@@ -0,0 +1,96 @@
+import { toolInputJsonSchema } from "@loomwork/agent";
+import { TypedFailure, jsonSchemaHash } from "@loomwork/core";
+import { MCP_INVOKE_TOOL_ID } from "@loomwork/plugin-mcp";
+import { SANDBOX_TOOL_ID } from "@loomwork/plugin-sandbox";
+/** The kind id of a step whose target is a registered loom effect. */
+export const LOOM_EFFECT_KIND = "loom-effect";
+/**
+ * The failure channel for a target the host did not declare. Served to a client as the fixed
+ * `tool-targetUnregistered` code — never the target id or any text of the effect's own.
+ */
+export const TARGET_UNREGISTERED = "targetUnregistered";
+/**
+ * The failure channel for an effect that itself raised `schemaDrift` (e.g. a target wrapping
+ * `mcp.invoke`). Only the provider's OWN pin check may emit `schemaDrift`: a target's drift
+ * would otherwise be read as this kind's pin drift, and a repair would re-pin to the inner
+ * hash and flip forever. Served as the `tool-targetFailed` code (`tool-failed` to a client).
+ */
+export const TARGET_FAILED = "targetFailed";
+/**
+ * The pin of an effect's input contract: `jsonSchemaHash` (the one canonical hash MCP pins use)
+ * of the schema's JSON-Schema form. Use it BOTH when the host builds a planner `CapabilityRef`
+ * (`toolSchemaHash`) and when it lists the effect for {@link loomEffectProvider} (via
+ * `{ inputSchema }`) so the two come from one source: editing the effect's zod schema moves
+ * the pin, and every stored step drifts.
+ */
+export function effectPin(schema) {
+    return jsonSchemaHash(toolInputJsonSchema(schema));
+}
+/** The effect kinds a data read can never reach: a person's answer, a model call. */
+const REFUSED_KINDS = new Set(["human", "llm"]);
+/**
+ * Effects hydration already reaches through a dedicated plane (the MCP kind, the sandbox
+ * reshaper). Exposing them as a data TARGET would let a stored step bypass the pin and the
+ * reshaping boundary, so a host cannot list them.
+ */
+const RESERVED_TARGETS = new Set([MCP_INVOKE_TOOL_ID, SANDBOX_TOOL_ID]);
+/**
+ * The `loom-effect` kind: a step whose `toolName` is the id of an effect registered with the
+ * loom effect runtime (a `tool$`, a read-model query effect, an A2A call…), invoked through the
+ * SAME transient invoker and therefore the same authoriser, budget and principal as the MCP
+ * kind. Construction refuses an effect that is unregistered, not explicitly `ambient`, or a
+ * `human` / `llm` kind.
+ *
+ * An effect's call is not memoised across a pass (the in-pass memo coalesces `mcp.invoke` only:
+ * an arbitrary effect is not known to be a pure read), so two steps naming one effect with equal
+ * arguments call it twice. (Memoising `ambient` effects is a possible follow-up.)
+ *
+ * A persisted experience crosses a version boundary only through the log: an older in-memory
+ * `executeProvider` / `seal` that predates kinds would run a kinded step as an MCP call.
+ */
+export function loomEffectProvider(options) {
+    const { runtime } = options;
+    const pins = new Map();
+    for (const [id, entry] of Object.entries(options.effects)) {
+        if (id === "")
+            throw new TypeError("loomEffectProvider: an effect id is empty");
+        if (RESERVED_TARGETS.has(id))
+            throw new TypeError(`loomEffectProvider: "${id}" is reached through its own plane (the MCP kind / the sandbox) and cannot be a data target`);
+        if (!runtime.has(id))
+            throw new TypeError(`loomEffectProvider: effect "${id}" is not registered with the runtime`);
+        if (runtime.modeOf(id) !== "ambient")
+            throw new TypeError(`loomEffectProvider: effect "${id}" is not declared mode "ambient" (ADR 0073); a data read may not run an undeclared or journaled effect`);
+        const kind = runtime.kindOf(id);
+        if (kind !== undefined && REFUSED_KINDS.has(kind))
+            throw new TypeError(`loomEffectProvider: effect "${id}" is a ${kind} effect, not a data read`);
+        const pin = entry !== null && typeof entry === "object" && "inputSchema" in entry
+            ? effectPin(entry.inputSchema)
+            : entry?.pin;
+        if (typeof pin !== "string" || pin === "")
+            throw new TypeError(`loomEffectProvider: effect "${id}" needs a non-empty pin`);
+        pins.set(id, pin);
+    }
+    return Object.freeze({
+        kind: LOOM_EFFECT_KIND,
+        async invoke(call, invoker, opts) {
+            const current = pins.get(call.target);
+            if (current === undefined)
+                throw new TypedFailure(TARGET_UNREGISTERED, { target: call.target });
+            if (current !== call.expectedPin)
+                throw new TypedFailure("schemaDrift", {
+                    toolName: call.target,
+                    expectedSchemaHash: call.expectedPin,
+                    observedHash: current,
+                });
+            try {
+                return await invoker.invokeTransient(call.target, call.args, opts);
+            }
+            catch (e) {
+                if (e instanceof TypedFailure && e.channel === "schemaDrift")
+                    throw new TypedFailure(TARGET_FAILED, { target: call.target });
+                throw e;
+            }
+        },
+    });
+}
+//# sourceMappingURL=loomEffectProvider.js.map

package/dist/esm/loomEffectProvider.js.map

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

package/dist/esm/params.js

@@ -0,0 +1,207 @@
+import { canonicalJson, fnv1a64 } from "@loomwork/core";
+import { resolveArguments } from "./plan";
+/** A time-range default a host may pass as `ControllerOptions.defaultParams`: the last 24 hours, relative to each pass. */
+export const DEFAULT_TIME_RANGE = Object.freeze({ from: "$now-24h", to: "$now" });
+/** Token-shaped: `$now` not followed by a word character. `$nowcast` is an ordinary string. */
+const TOKEN_LIKE = /^\$now(?![A-Za-z0-9_])/;
+const TIME_TOKEN = /^\$now(?:([+-])(\d{1,9})([smhdw]))?$/;
+const UNIT_MS = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+};
+const bad = (code, message) => ({ code, severity: "error", message });
+const note = (code, message) => ({ code, severity: "warn", message });
+/** An async argument hook returns one of these: `prepareArguments` never awaits it. */
+function isThenable(v) {
+    return (v !== null && typeof v === "object" && typeof v.then === "function");
+}
+/** `$now`, `$now-7d`, `$now+1h` (units s m h d w) as an ISO-8601 instant; `undefined` otherwise. */
+export function resolveTimeToken(token, now) {
+    const m = TIME_TOKEN.exec(token);
+    if (!m)
+        return undefined;
+    const offset = m[1] === undefined
+        ? 0
+        : (m[1] === "-" ? -1 : 1) * Number(m[2]) * UNIT_MS[m[3]];
+    const at = new Date(now + offset);
+    // Past ±8.64e15 ms a Date is invalid and `toISOString` would throw: refuse instead.
+    return Number.isNaN(at.getTime()) ? undefined : at.toISOString();
+}
+/** Every token-shaped string leaf is resolved, or the whole value is refused. Other leaves pass. */
+export function resolveTimeTokens(value, now, where) {
+    let failure;
+    const visit = (v) => {
+        if (failure)
+            return v;
+        if (typeof v === "string") {
+            if (!TOKEN_LIKE.test(v))
+                return v;
+            const iso = resolveTimeToken(v, now);
+            if (iso !== undefined)
+                return iso;
+            failure = bad("invalid-time-token", `${where}: "${v.slice(0, 64)}" is not a relative-time token ($now, $now-7d, $now+1h; units s m h d w)`);
+            return v;
+        }
+        if (Array.isArray(v))
+            return v.map(visit);
+        if (v !== null && typeof v === "object")
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, visit(x)]));
+        return v;
+    };
+    const out = visit(value);
+    return failure ? { ok: false, finding: failure } : { ok: true, value: out };
+}
+const STEP_REF = /\{\{\s*steps\./;
+function containsStepTemplate(v) {
+    if (typeof v === "string")
+        return STEP_REF.test(v);
+    if (Array.isArray(v))
+        return v.some(containsStepTemplate);
+    if (v !== null && typeof v === "object")
+        return Object.values(v).some(containsStepTemplate);
+    return false;
+}
+/** A plain object `canonicalJson` can represent (no NaN/±Infinity, bigint, function, over-deep nest). */
+export function checkParams(params) {
+    if (params === null || typeof params !== "object" || Array.isArray(params))
+        return bad("invalid-params", "params must be a plain object");
+    try {
+        canonicalJson(params);
+        return undefined;
+    }
+    catch (e) {
+        return bad("invalid-params", `params cannot be represented as JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** Canonical identity of a param set (key order irrelevant); `""` for none. Throws only on what `checkParams` refuses. */
+export function paramsKey(params) {
+    return Object.keys(params).length === 0 ? "" : fnv1a64(canonicalJson(params));
+}
+/** Every argument name any step of the provider declares overridable, sorted. */
+export function providerParams(spec) {
+    const names = new Set();
+    for (const step of spec.executionGraph)
+        for (const n of step.overridable ?? [])
+            names.add(n);
+    return [...names].sort();
+}
+/**
+ * The named params the set actually holds (own keys only), as a fresh, FROZEN object — this is
+ * the object every step's `prepareArguments` call (and its argument hook) receives as `ctx.params`
+ * for the whole load, so a hook mutating it would leak into every other step's view of the load.
+ * Reads `params[n]` once per name: on params that crossed a trust boundary, snapshot them first
+ * (`snapshotParams`) — a live accessor that answered safely for an earlier, separate check (e.g.
+ * `checkParams` alone) is free to answer differently by the time THIS read runs.
+ */
+export function pickParams(params, names) {
+    return Object.freeze(Object.fromEntries(names.filter((n) => Object.hasOwn(params, n)).map((n) => [n, params[n]])));
+}
+/**
+ * ONE plain, detached copy of untrusted params — a JSON round-trip through `canonicalJson`, so a
+ * value it refuses (a function, bigint, non-finite number, a cycle, past the depth cap) is caught
+ * HERE, and `JSON.parse` builds the result from that already-captured string alone: nothing
+ * downstream (`checkParams`, `pickParams`, `relevantParams`) ever reads a property of the SOURCE
+ * object again. Required wherever params cross a trust boundary (`serveHandle(s)`) — validating a
+ * live accessor and then separately picking named keys off it re-reads it, and a hostile getter is
+ * free to answer only the validating read safely and answer a later, picking read with something
+ * else entirely (observed: a plain value for the first two reads, a function for the third).
+ */
+export function snapshotParams(params) {
+    if (params === null || typeof params !== "object" || Array.isArray(params))
+        return { ok: false, finding: bad("invalid-params", "params must be a plain object") };
+    try {
+        return { ok: true, params: JSON.parse(canonicalJson(params)) };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            finding: bad("invalid-params", `params cannot be represented as JSON: ${e instanceof Error ? e.message : String(e)}`),
+        };
+    }
+}
+/** The params this provider can use: everything else cannot change its answer. */
+export function relevantParams(spec, params) {
+    return pickParams(params, providerParams(spec));
+}
+export function applyParams(node, params) {
+    const { args, findings } = applyParamsDetailed(node, params);
+    return { args, findings };
+}
+/** {@link applyParams}, plus which top-level arguments a param actually replaced (U9b needs them). */
+export function applyParamsDetailed(node, params) {
+    const names = node.overridable ?? [];
+    const findings = [];
+    const replaced = [];
+    if (names.length === 0)
+        return { args: node.arguments, findings, replaced };
+    // A Map, then `Object.fromEntries`: every write is CreateDataProperty, so an argument named
+    // `__proto__` lands as an own key instead of setting a prototype.
+    const args = new Map(Object.entries(node.arguments));
+    for (const name of names) {
+        if (!Object.hasOwn(params, name))
+            continue;
+        if (containsStepTemplate(args.get(name))) {
+            findings.push(note("param-templated", `step "${node.stepId}": argument "${name}" is a {{steps.…}} template — another step's output — so no param replaces it`));
+            continue;
+        }
+        const value = params[name];
+        if (containsStepTemplate(value)) {
+            findings.push(note("param-template-refused", `step "${node.stepId}": the param for "${name}" contains a {{steps.…}} template; a param is a literal, so it is not applied`));
+            continue;
+        }
+        args.set(name, value);
+        replaced.push(name);
+    }
+    return { args: Object.fromEntries(args), findings, replaced };
+}
+export function prepareArguments(node, outputs, ctx) {
+    const applied = applyParamsDetailed(node, ctx.params);
+    const refused = ctx.guard?.(node, applied);
+    if (refused !== undefined)
+        return { ok: false, finding: refused };
+    const timed = resolveTimeTokens(applied.args, ctx.now, `step "${node.stepId}"`);
+    if (!timed.ok)
+        return timed;
+    const templated = resolveArguments({ ...node, arguments: timed.value }, outputs);
+    if (!templated.ok)
+        return templated;
+    const finished = ctx.finish ? ctx.finish(templated.args) : templated.args;
+    if (ctx.hook === undefined)
+        return { ok: true, args: finished, findings: applied.findings };
+    let hooked;
+    try {
+        hooked = ctx.hook(finished, {
+            handle: ctx.handle,
+            stepId: node.stepId,
+            toolName: node.toolName,
+            ...(node.kind !== undefined && { kind: node.kind }),
+            params: ctx.params,
+            now: ctx.now,
+        });
+    }
+    catch (e) {
+        return {
+            ok: false,
+            finding: bad("argument-hook-failed", `step "${node.stepId}": the argument hook threw: ${e instanceof Error ? e.message : String(e)}`),
+        };
+    }
+    if (isThenable(hooked)) {
+        // The step callback never awaits a hook (it is documented as synchronous): swallow whatever
+        // this thenable eventually does, so an async hook never surfaces as an unhandled rejection.
+        hooked.then(() => { }, () => { });
+        return {
+            ok: false,
+            finding: bad("argument-hook-failed", `step "${node.stepId}": the argument hook returned a thenable — hooks must return the arguments object synchronously, not a Promise`),
+        };
+    }
+    if (hooked === null || typeof hooked !== "object" || Array.isArray(hooked))
+        return {
+            ok: false,
+            finding: bad("argument-hook-failed", `step "${node.stepId}": the argument hook returned ${hooked === null ? "null" : Array.isArray(hooked) ? "an array" : typeof hooked}, not an arguments object`),
+        };
+    return { ok: true, args: hooked, findings: applied.findings };
+}
+//# sourceMappingURL=params.js.map

package/dist/esm/params.js.map

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