@loomwork/ui-hydration 0.0.0-stage → 0.1.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,2CASsB;AARpB,qHAAA,uBAAuB,OAAA;AACvB,0HAAA,4BAA4B,OAAA;AAC5B,iHAAA,mBAAmB,OAAA;AACnB,4HAAA,8BAA8B,OAAA;AAC9B,iHAAA,mBAAmB,OAAA;AACnB,4GAAA,cAAc,OAAA;AACd,iHAAA,mBAAmB,OAAA;AACnB,8GAAA,gBAAgB,OAAA;AAUlB,uCAAsE;AAA7D,wGAAA,YAAY,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AACjD,qCAA+E;AAAtE,0GAAA,eAAe,OAAA;AAAE,yGAAA,cAAc,OAAA;AAAE,4GAAA,iBAAiB,OAAA;AAE3D,mCAA2D;AAAlD,4GAAA,kBAAkB,OAAA;AAAE,qGAAA,WAAW,OAAA;AACxC,6CAAsD;AAA7C,oHAAA,qBAAqB,OAAA;AAO9B,+CAKwB;AAJtB,sHAAA,sBAAsB,OAAA;AACtB,4HAAA,4BAA4B,OAAA;AAC5B,mHAAA,mBAAmB,OAAA;AACnB,2GAAA,WAAW,OAAA;AAGb,2DAM8B;AAL5B,sHAAA,gBAAgB,OAAA;AAChB,mHAAA,aAAa,OAAA;AACb,yHAAA,mBAAmB,OAAA;AACnB,+GAAA,SAAS,OAAA;AACT,wHAAA,kBAAkB,OAAA;AAOpB,uCAA6C;AAApC,2GAAA,eAAe,OAAA;AACxB,+BAAkE;AAAzD,sGAAA,cAAc,OAAA;AAAE,qGAAA,aAAa,OAAA;AAAE,iGAAA,SAAS,OAAA;AAEjD,iCAAoE;AAA3D,kHAAA,yBAAyB,OAAA;AAAE,uGAAA,cAAc,OAAA;AAGlD,2CAAmD;AAA1C,iHAAA,mBAAmB,OAAA;AAE5B,uCASuB;AARrB,0GAAA,iBAAiB,OAAA;AACjB,qHAAA,4BAA4B,OAAA;AAC5B,iHAAA,wBAAwB,OAAA;AACxB,2GAAA,kBAAkB,OAAA;AAClB,wGAAA,eAAe,OAAA;AACf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,qGAAA,YAAY,OAAA;AAad,mCAA2D;AAAlD,yGAAA,eAAe,OAAA;AAAE,wGAAA,cAAc,OAAA;AAExC,2CAAgE;AAAvD,iHAAA,mBAAmB,OAAA;AAAE,yGAAA,WAAW,OAAA"}

package/dist/invoker.d.ts

@@ -0,0 +1,10 @@
+import type { TransientInvokeOptions } from "@loomwork/effect-runtime";
+/**
+ * The one thing hydration needs from loom's runtime: a one-shot, non-durable effect call.
+ * `EffectRuntime` satisfies this structurally (ADR 0066 `invokeTransient`); tests use a fake.
+ * Keeping it an interface is what makes the read path provably log-free — there is no `ctx`.
+ */
+export interface TransientInvoker {
+    invokeTransient<TIn = unknown, TOut = unknown>(toolId: string, input: TIn, opts?: TransientInvokeOptions): Promise<TOut>;
+}
+//# sourceMappingURL=invoker.d.ts.map

package/dist/invoker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../src/invoker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,eAAe,CAAC,GAAG,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO,EAC3C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,GAAG,EACV,IAAI,CAAC,EAAE,sBAAsB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB"}

package/dist/invoker.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=invoker.js.map

package/dist/invoker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoker.js","sourceRoot":"","sources":["../src/invoker.ts"],"names":[],"mappings":""}

package/dist/invokers.d.ts

@@ -0,0 +1,36 @@
+import type { TransientInvoker } from "./invoker";
+/**
+ * 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 declare function limitInvoker(inner: TransientInvoker, max: number): TransientInvoker;
+/**
+ * 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 declare function signalInvoker(inner: TransientInvoker, signal: AbortSignal): TransientInvoker;
+/**
+ * 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 declare function memoInvoker(inner: TransientInvoker): TransientInvoker;
+//# sourceMappingURL=invokers.d.ts.map

package/dist/invokers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invokers.d.ts","sourceRoot":"","sources":["../src/invokers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAwBlD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,gBAAgB,CA0DnF;AAWD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,GAAG,gBAAgB,CAwB5F;AAyDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,gBAAgB,CA2IrE"}

package/dist/invokers.js

@@ -0,0 +1,315 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.limitInvoker = limitInvoker;
+exports.signalInvoker = signalInvoker;
+exports.memoInvoker = memoInvoker;
+const core_1 = require("@loomwork/core");
+const plugin_mcp_1 = require("@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.
+ */
+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.
+ */
+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.
+ */
+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 !== plugin_mcp_1.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 = (0, core_1.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/invokers.js.map

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

package/dist/loomEffectProvider.d.ts

@@ -0,0 +1,67 @@
+import { toolInputJsonSchema } from "@loomwork/agent";
+import type { EffectRuntime } from "@loomwork/effect-runtime";
+import type { DataProvider } from "./dataProvider";
+/** The kind id of a step whose target is a registered loom effect. */
+export declare 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 declare 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 declare const TARGET_FAILED = "targetFailed";
+/** The schema of an effect's input, as `tool$({ inputSchema })` takes it. */
+export type EffectInputSchema = Parameters<typeof toolInputJsonSchema>[0];
+/**
+ * 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 declare function effectPin(schema: EffectInputSchema): string;
+/** How a listed effect's pin is obtained: computed from its schema, or asserted by the host. */
+export type EffectEntry = {
+    readonly inputSchema: NonNullable<EffectInputSchema>;
+} | {
+    readonly pin: string;
+};
+export interface LoomEffectProviderOptions {
+    /**
+     * The runtime the effects are registered with. Read at CONSTRUCTION only (`has` / `modeOf` /
+     * `kindOf`): hydration is a read path that runs per viewer load, unmemoised and retried, so
+     * every listed effect must be registered, explicitly `mode: "ambient"` (ADR 0073 — loom
+     * refuses only an explicit `journaled` one on the transient path, so an UNDECLARED mode is
+     * not a read declaration and is refused here), and not a `human` / `llm` kind.
+     */
+    readonly runtime: Pick<EffectRuntime, "has" | "modeOf" | "kindOf">;
+    /**
+     * The effects a stored step may name. `{ inputSchema }` computes the pin with
+     * {@link effectPin} (a schema change drifts every stored step); `{ pin }` is HOST-ASSERTED —
+     * nothing checks it against the effect, so the host owns changing it when callers must
+     * re-author. A step naming an effect not listed is refused (`tool-targetUnregistered`) and
+     * nothing runs. Pins must be non-empty.
+     */
+    readonly effects: Readonly<Record<string, EffectEntry>>;
+}
+/**
+ * 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 declare function loomEffectProvider(options: LoomEffectProviderOptions): DataProvider;
+//# sourceMappingURL=loomEffectProvider.d.ts.map

package/dist/loomEffectProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loomEffectProvider.d.ts","sourceRoot":"","sources":["../src/loomEffectProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAG9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,gBAAgB,CAAC;AAE9C;;;GAGG;AACH,eAAO,MAAM,mBAAmB,uBAAuB,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,iBAAiB,CAAC;AAE5C,6EAA6E;AAC7E,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAE3D;AAYD,gGAAgG;AAChG,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7B,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC,CAAC;IACnE;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,YAAY,CAiDnF"}

package/dist/loomEffectProvider.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TARGET_FAILED = exports.TARGET_UNREGISTERED = exports.LOOM_EFFECT_KIND = void 0;
+exports.effectPin = effectPin;
+exports.loomEffectProvider = loomEffectProvider;
+const agent_1 = require("@loomwork/agent");
+const core_1 = require("@loomwork/core");
+const plugin_mcp_1 = require("@loomwork/plugin-mcp");
+const plugin_sandbox_1 = require("@loomwork/plugin-sandbox");
+/** The kind id of a step whose target is a registered loom effect. */
+exports.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.
+ */
+exports.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).
+ */
+exports.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.
+ */
+function effectPin(schema) {
+    return (0, core_1.jsonSchemaHash)((0, agent_1.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([plugin_mcp_1.MCP_INVOKE_TOOL_ID, plugin_sandbox_1.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.
+ */
+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: exports.LOOM_EFFECT_KIND,
+        async invoke(call, invoker, opts) {
+            const current = pins.get(call.target);
+            if (current === undefined)
+                throw new core_1.TypedFailure(exports.TARGET_UNREGISTERED, { target: call.target });
+            if (current !== call.expectedPin)
+                throw new core_1.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 core_1.TypedFailure && e.channel === "schemaDrift")
+                    throw new core_1.TypedFailure(exports.TARGET_FAILED, { target: call.target });
+                throw e;
+            }
+        },
+    });
+}
+//# sourceMappingURL=loomEffectProvider.js.map

package/dist/loomEffectProvider.js.map

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