@bevel-software/platform-mcp-core 0.22.0 → 0.24.0

package/dist/chain-runtime.js

@@ -0,0 +1,352 @@
+import { utcpNameToTsInterfaceName } from './code-mode-names.js';
+import { describeToolFailure } from './results.js';
+/**
+ * What runs a `call_tool_chain` chain, for every surface that offers one: the
+ * hosted MCP proxy, the local `hexis-mcp` server and the in-process agent's
+ * Mastra tool.
+ *
+ * Three things live here because all three surfaces need them to be the same:
+ *
+ *  - the BROWSER GLOBALS a chain is promised (`atob`, `btoa`, `TextEncoder`,
+ *    `TextDecoder`). `@utcp/code-mode` runs the chain in a bare `isolated-vm`
+ *    isolate — plain V8, so no Node globals (`Buffer`) and no web platform
+ *    (`atob`), and a chain could not decode base64 or bytes at all. They are
+ *    added as a PRELUDE to the chain's own source rather than injected into
+ *    the isolate's context, because the isolate is created inside
+ *    `callToolChain` and is reachable from nowhere else (see
+ *    {@link CHAIN_RUNTIME_PRELUDE});
+ *  - the ANSWER for a chain that failed. `callToolChain` does not throw when
+ *    the chain dies: it resolves `{ result: null, logs: ['[ERROR] Code
+ *    execution failed: …'] }`, so a surface that read only `result` reported
+ *    `success: true` with a null result and the agent was told nothing. Every
+ *    failure — a timeout, an undefined namespace, a tool that threw — becomes
+ *    an error that says what happened;
+ *  - the promise that a chain ALWAYS answers. A request that never settles is
+ *    what reaches an agent as a dropped connection rather than as something it
+ *    can act on, so the runner is raced against a watchdog (see
+ *    {@link WATCHDOG_GRACE_MS}).
+ */
+/**
+ * The largest `timeout` a chain may ask for, in milliseconds. One constant: it
+ * is the schema's bound on every surface AND the figure the timeout error tells
+ * the agent it may raise `timeout` to, and those two drifting apart would send
+ * an agent to retry with a value the schema then clamps straight back down.
+ */
+export const CHAIN_TIMEOUT_MAX_MS = 120_000;
+/** The smallest `timeout` a chain may ask for, in milliseconds. */
+export const CHAIN_TIMEOUT_MIN_MS = 1_000;
+/** The `timeout` a chain that does not ask for one gets, in milliseconds. */
+export const CHAIN_TIMEOUT_DEFAULT_MS = 30_000;
+/**
+ * How long past its own `timeout` the runner is given to answer before the
+ * watchdog answers for it. `callToolChain` enforces the timeout itself and so
+ * normally settles well inside this; the watchdog covers the case where it does
+ * not, where the alternative is a request that hangs until the client gives up
+ * — the dropped connection an agent cannot tell from a crash.
+ */
+const WATCHDOG_GRACE_MS = 5_000;
+/** The log line `@utcp/code-mode` records when a chain's code fails. */
+const CHAIN_FAILURE_LOG = '[ERROR] Code execution failed: ';
+/** The runner's own wording for a chain it stopped at the timeout. */
+const RUNNER_TIMEOUT = /Script execution timeout after (\d+)\s*ms/;
+/** `isolated-vm`'s wording when V8 itself terminated the script at the deadline. */
+const ISOLATE_TERMINATED = /Script execution timed out|execution was terminated|script execution interrupted/i;
+/** `isolated-vm`'s wording when the chain exhausted the isolate's heap. */
+const ISOLATE_OUT_OF_MEMORY = /memory limit|out of memory|allocation failed/i;
+/** The identifier a chain named that the isolate has no binding for. */
+const UNDEFINED_IDENTIFIER = /ReferenceError: ([A-Za-z_$][\w$]*) is not defined/;
+/**
+ * The browser globals, as ONE physical line of plain ES5 JavaScript.
+ *
+ * One line on purpose. The prelude is prepended to the agent's own chain
+ * source, and a failed chain is reported with its stack in it; a multi-line
+ * prelude would shift every line number in that stack and point the agent at
+ * the wrong line of its own code. Prepended WITHOUT a trailing newline for the
+ * same reason, so the chain's first line stays line one. (The one casualty is
+ * a `'use strict'` directive written as a chain's first statement, which is no
+ * longer in first position and so no longer applies. A chain is a handful of
+ * statements against a tool catalog, and strict mode is not something the
+ * chain protocol ever offered.)
+ *
+ * `atob`/`btoa` follow WHATWG forgiving-base64: ASCII whitespace is stripped,
+ * the padding is optional, and anything else throws rather than decoding to
+ * silent garbage. `TextEncoder`/`TextDecoder` are UTF-8 only — that is the
+ * encoding the Specification asks for, and a decoder that took a `label` it
+ * then ignored would quietly answer mojibake. `TextDecoder` drops a leading
+ * byte-order mark the way a browser's default does, and keeps it under
+ * `{ ignoreBOM: true }`: a chain decoding a UTF-8 file written on Windows would
+ * otherwise find a stray `\uFEFF` at the front of it, which breaks a
+ * `JSON.parse` and every exact-match comparison. It honours `{ stream: true }`:
+ * a chain that decodes bytes in pieces gets a character whose bytes straddle
+ * two pieces whole, where a decoder that started afresh on every call returned
+ * two replacement characters for it — and a call without the option ends the
+ * stream, answering a sequence left unfinished as one. Each is defined only when the
+ * runtime does not already have it, so a future `@utcp/code-mode` that ships
+ * them natively wins.
+ */
+export const CHAIN_RUNTIME_PRELUDE = [
+    '(function(g){',
+    "var A='ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';",
+    'if(typeof g.btoa!=="function"){g.btoa=function(input){',
+    'var s=String(input),i,o="";',
+    'for(i=0;i<s.length;i++){if(s.charCodeAt(i)>255)throw new Error("InvalidCharacterError: btoa() takes a string whose every character is in the Latin-1 range (0-255). To base64 text, encode it to UTF-8 bytes with TextEncoder first.");}',
+    'for(i=0;i<s.length;i+=3){',
+    'var b0=s.charCodeAt(i),b1=s.charCodeAt(i+1),b2=s.charCodeAt(i+2),h1=!isNaN(b1),h2=!isNaN(b2);',
+    'o+=A.charAt(b0>>2)+A.charAt(((b0&3)<<4)|(h1?b1>>4:0));',
+    'o+=(h1?A.charAt(((b1&15)<<2)|(h2?b2>>6:0)):"=")+(h2?A.charAt(b2&63):"=");',
+    '}return o;};}',
+    'if(typeof g.atob!=="function"){g.atob=function(input){',
+    'var s=String(input).replace(/[\\t\\n\\f\\r ]/g,"");',
+    'if(s.length%4===0)s=s.replace(/==?$/,"");',
+    'if(s.length%4===1||/[^+\\/0-9A-Za-z]/.test(s))throw new Error("InvalidCharacterError: atob() was given a string that is not valid base64.");',
+    'var o="",buf=0,bits=0,i;',
+    'for(i=0;i<s.length;i++){buf=(buf<<6)|A.indexOf(s.charAt(i));bits+=6;',
+    'if(bits>=8){bits-=8;o+=String.fromCharCode((buf>>bits)&255);}}',
+    'return o;};}',
+    'if(typeof g.TextEncoder!=="function"){',
+    'var TE=function TextEncoder(){};',
+    'TE.prototype.encoding="utf-8";',
+    'TE.prototype.encode=function(input){',
+    'var s=String(input===undefined?"":input),out=[],i=0;',
+    'while(i<s.length){var c=s.codePointAt(i);i+=c>65535?2:1;',
+    'if(c<128)out.push(c);',
+    'else if(c<2048)out.push(192|(c>>6),128|(c&63));',
+    'else if(c>=55296&&c<=57343)out.push(239,191,189);',
+    'else if(c<65536)out.push(224|(c>>12),128|((c>>6)&63),128|(c&63));',
+    'else out.push(240|(c>>18),128|((c>>12)&63),128|((c>>6)&63),128|(c&63));}',
+    'return new Uint8Array(out);};',
+    'g.TextEncoder=TE;}',
+    'if(typeof g.TextDecoder!=="function"){',
+    'var TD=function TextDecoder(label,options){',
+    'var e=String(label===undefined?"utf-8":label).toLowerCase();',
+    'if(e!=="utf-8"&&e!=="utf8"&&e!=="unicode-1-1-utf-8")throw new RangeError("TextDecoder(): the tool-chain runtime decodes UTF-8 only, not \\""+label+"\\".");',
+    'this.ignoreBOM=!!(options&&options.ignoreBOM);};',
+    'TD.prototype.encoding="utf-8";',
+    'TD.prototype.ignoreBOM=false;',
+    // `p` is what one call leaves for the next under `{ stream: true }`: the
+    // sequence in progress (need, seen, c and the bounds on its next byte) and
+    // whether the stream has produced its first character yet, which is the
+    // only place a byte-order mark is one.
+    'TD.prototype.decode=function(input,options){',
+    'var st=!!(options&&options.stream),ig=this.ignoreBOM,p=this._p||[0,0,0,128,191,0];',
+    'var b=(input===undefined||input===null)?new Uint8Array(0):(input instanceof Uint8Array?input:(input instanceof ArrayBuffer?new Uint8Array(input):(input&&input.buffer instanceof ArrayBuffer?new Uint8Array(input.buffer,input.byteOffset,input.byteLength):new Uint8Array(input))));',
+    'var o="",n=b.length,need=p[0],seen=p[1],c=p[2],lo=p[3],hi=p[4],bom=p[5],i=0,x,t;',
+    'while(i<n){x=b[i];',
+    'if(need===0){i++;',
+    'if(x<128){bom=1;o+=String.fromCharCode(x);}',
+    'else if(x>=194&&x<=223){need=1;c=x&31;}',
+    'else if(x>=224&&x<=239){if(x===224)lo=160;if(x===237)hi=159;need=2;c=x&15;}',
+    'else if(x>=240&&x<=244){if(x===240)lo=144;if(x===244)hi=143;need=3;c=x&7;}',
+    'else{bom=1;o+="\\uFFFD";}',
+    'continue;}',
+    'if(x<lo||x>hi){need=0;seen=0;c=0;lo=128;hi=191;bom=1;o+="\\uFFFD";continue;}',
+    'lo=128;hi=191;i++;c=(c<<6)|(x&63);seen++;',
+    'if(seen===need){',
+    'if(c===65279&&!bom&&!ig){}',
+    'else if(c<=65535)o+=String.fromCharCode(c);',
+    'else{t=c-65536;o+=String.fromCharCode(55296+(t>>10),56320+(t&1023));}',
+    'bom=1;need=0;seen=0;c=0;}}',
+    'if(st){this._p=[need,seen,c,lo,hi,bom];return o;}',
+    'if(need!==0)o+="\\uFFFD";',
+    'this._p=null;',
+    'return o;};',
+    'g.TextDecoder=TD;}',
+    '})(globalThis);',
+].join('');
+/**
+ * The agent's chain source with the runtime prelude in front of it, on the same
+ * physical line, so a stack from the chain still names the chain's own line
+ * numbers (see {@link CHAIN_RUNTIME_PRELUDE}).
+ */
+export function withChainRuntime(code) {
+    return `${CHAIN_RUNTIME_PRELUDE}${code}`;
+}
+/**
+ * What a chain can actually call. `@utcp/code-mode` gives every tool whose UTCP
+ * name is `MANUAL.tool` a `global.MANUAL` object, so the namespaces are the
+ * sanitized manual names — and a tool registered under a bare name becomes a
+ * global function rather than a namespace, which is why those are listed apart.
+ */
+export async function chainNamespaces(client) {
+    const namespaces = new Set();
+    const bare = new Set();
+    for (const tool of await client.config.tool_repository.getTools()) {
+        const tsName = utcpNameToTsInterfaceName(tool.name);
+        const dot = tsName.indexOf('.');
+        if (dot > 0)
+            namespaces.add(tsName.slice(0, dot));
+        else
+            bare.add(tsName);
+    }
+    return { namespaces: [...namespaces].sort(), bare: [...bare].sort() };
+}
+/** What a chain is told when it timed out: the limit it hit, and how to raise it. */
+export function chainTimeoutMessage(timeoutMs) {
+    return (`The tool chain timed out after ${timeoutMs} ms and was stopped, so it has no result. ` +
+        `Raise \`timeout\` (milliseconds, up to a maximum of ${CHAIN_TIMEOUT_MAX_MS}) and run it again, ` +
+        'or split the work across several shorter chains. The connection is unaffected — your next tool call works as usual.');
+}
+/** What a chain is told when it exhausted the isolate's heap. */
+export function chainOutOfMemoryMessage(reason) {
+    return (`The tool chain ran out of memory and was stopped, so it has no result (${reason}). ` +
+        'Return less from the chain — filter, map or count inside it instead of accumulating every record — ' +
+        'or split the work across several chains. The connection is unaffected — your next tool call works as usual.');
+}
+/** What a chain is told when it named something the runtime has no binding for. */
+export function unknownNamespaceMessage(identifier, found) {
+    const { namespaces, bare } = found;
+    const existing = namespaces.length
+        ? `The tool namespaces this connection exposes are: ${namespaces.join(', ')}.`
+        : 'This connection exposes no tool namespaces at all.';
+    const example = namespaces[0] ? ` Call a tool as \`${namespaces[0]}.<tool>({ body: { … } })\`.` : '';
+    const bareNote = bare.length ? ` Callable without a namespace: ${bare.join(', ')}.` : '';
+    return (`ReferenceError: ${identifier} is not defined — "${identifier}" is not one of them. ` +
+        `${existing}${example}${bareNote} Use \`list_tools\` for the exact callable names.`);
+}
+/**
+ * Why a RESOLVED `callToolChain` is a failure, or undefined when it is not one.
+ *
+ * `callToolChain` resolves rather than throws on a dead chain, reporting it as
+ * a `[ERROR] Code execution failed: …` log line with a null result. Both halves
+ * are required: a chain that returned a value succeeded however it logged.
+ *
+ * The LAST such line, not the last line: the runner appends its own entry in a
+ * `catch` and then, in the `finally`, a `[WARN] Tool call "…" abandoned` line
+ * per tool call still in flight — so a chain that timed out mid-call has the
+ * reason second-from-last or further back. A chain that prints that exact
+ * prefix itself through `console.error` AND returns null is read as a failure;
+ * that trade is deliberate, since the alternative — a dead chain reported as a
+ * success with a null result — is the bug this replaces.
+ */
+function failureReason(outcome) {
+    if (outcome.result !== null && outcome.result !== undefined)
+        return undefined;
+    for (let i = outcome.logs.length - 1; i >= 0; i -= 1) {
+        const line = outcome.logs[i];
+        if (typeof line === 'string' && line.startsWith(CHAIN_FAILURE_LOG)) {
+            return line.slice(CHAIN_FAILURE_LOG.length);
+        }
+    }
+    return undefined;
+}
+/**
+ * Turn the runner's reason into the sentence the agent reads. A timeout, an
+ * exhausted heap and an undefined namespace each get their own; anything else
+ * passes through exactly as the runner reported it, so a real cause is never
+ * replaced by a guess.
+ */
+export async function describeChainFailure(client, reason, timeoutMs) {
+    // Memory before termination: an isolate killed for its heap reports being
+    // disposed too, and calling that a timeout would send the agent to raise a
+    // limit that was never the problem.
+    if (ISOLATE_OUT_OF_MEMORY.test(reason))
+        return chainOutOfMemoryMessage(reason);
+    const runnerTimeout = RUNNER_TIMEOUT.exec(reason);
+    if (runnerTimeout)
+        return chainTimeoutMessage(Number(runnerTimeout[1]));
+    if (ISOLATE_TERMINATED.test(reason))
+        return chainTimeoutMessage(timeoutMs);
+    const undefinedIdentifier = UNDEFINED_IDENTIFIER.exec(reason);
+    if (undefinedIdentifier) {
+        // The namespace list costs one catalog read, so it is fetched only on the
+        // failure that needs it. A catalog that cannot be read must not replace the
+        // chain's own reason with an unrelated one: the agent keeps the
+        // ReferenceError, just without the list.
+        try {
+            return unknownNamespaceMessage(undefinedIdentifier[1], await chainNamespaces(client));
+        }
+        catch {
+            return reason;
+        }
+    }
+    return reason;
+}
+/**
+ * Run a chain and ALWAYS answer: with its value, or with the reason it has
+ * none. Never throws, and never leaves a caller waiting past the chain's own
+ * timeout plus {@link WATCHDOG_GRACE_MS}.
+ *
+ * What the caller does with an error is still the caller's (the hosted proxy
+ * maps a retired tool's name onto its own message first, for instance); this
+ * decides only whether there IS one and what it says about the runtime.
+ */
+export async function runToolChain(client, code, timeoutMs) {
+    let watchdog;
+    try {
+        const watchdogFired = new Promise((resolve) => {
+            watchdog = setTimeout(() => resolve('watchdog'), timeoutMs + WATCHDOG_GRACE_MS);
+            // A watchdog nobody is waiting on must not hold a CLI's exit open.
+            watchdog.unref?.();
+        });
+        const settled = await Promise.race([
+            client.callToolChain(withChainRuntime(code), timeoutMs).then((outcome) => ({ outcome })),
+            watchdogFired,
+        ]);
+        if (settled === 'watchdog')
+            return { ok: false, error: chainTimeoutMessage(timeoutMs), logs: [] };
+        const logs = Array.isArray(settled.outcome.logs) ? settled.outcome.logs : [];
+        const reason = failureReason({ result: settled.outcome.result, logs });
+        if (reason !== undefined) {
+            return { ok: false, error: await describeChainFailure(client, reason, timeoutMs), logs };
+        }
+        return { ok: true, result: settled.outcome.result, logs };
+    }
+    catch (err) {
+        // Everything the runner throws BEFORE the chain starts (a catalog read, a
+        // registry outage) and anything a tool bridge rethrows. The http transport
+        // carries a status and a body on a tool failure, and both are worth more to
+        // the agent than the message on its own.
+        //
+        // `describeToolFailure` is what reads the PROVIDER's own reason out of such
+        // a failure — `response.data.error`, with the machine-readable `kind` kept
+        // beside it on a typed refusal. The MCP dispatcher used to call it on the
+        // thrown error itself; now that the catch lives here, taking `err.message`
+        // instead would hand the agent a generic transport line and drop the half
+        // it can act on.
+        //
+        // Under a guard even so. `describeToolFailure` is total — it reads `err`
+        // through try/catch — but THIS function's contract is that it never throws,
+        // and that contract is what the "no chain failure reaches the agent as a
+        // dropped connection" criterion rests on. A guard here keeps it local
+        // rather than resting on another module staying total.
+        let error;
+        try {
+            error = describeToolFailure(err);
+        }
+        catch {
+            // Describing it is the first thing that can fail, so the fallback is
+            // itself layered: the thrown value's own message if it can be read, and
+            // a fixed sentence if even that throws. An opaque answer is still an
+            // ANSWER — what must never happen is a rejection out of this catch.
+            try {
+                error = err instanceof Error ? err.message : String(err);
+            }
+            catch {
+                error = '(indescribable tool failure)';
+            }
+        }
+        let status;
+        let data;
+        try {
+            const e = err;
+            status = e?.status ?? e?.response?.status;
+            data = e?.data ?? e?.response?.data;
+        }
+        catch {
+            // A throwing getter or Proxy says nothing about the failure; the message
+            // above already stands on its own.
+        }
+        return {
+            ok: false,
+            error,
+            logs: [],
+            ...(typeof status === 'number' ? { status } : {}),
+            ...(data !== undefined ? { data } : {}),
+        };
+    }
+    finally {
+        if (watchdog)
+            clearTimeout(watchdog);
+    }
+}
+//# sourceMappingURL=chain-runtime.js.map

package/dist/chain-runtime.js.map

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

package/dist/index.d.ts

@@ -26,10 +26,12 @@
  * thing as session recovery, and stays each surface's own.
  */
 export { type ProxiedTool, toListedTool, sanitizeInputSchema, flattenManualTool, flattenDiscoveredTool, } from './proxied-tool.js';
-export { describeToolFailure, toCallToolResult, renderProgress, toolError, needsAuthorizationResult, MCP_IMAGE_RESULT_KIND, type McpImageResult, mcpImageResult, isMcpImageResult, omitImagePayloads, } from './results.js';
-export { CODE_MODE_META_TOOLS, META_TOOL_NAMES, CALL_TOOL_CHAIN_MAX_OUTPUT, type SpillPort, dispatchMetaTool, } from './meta-tools.js';
+export { describeToolFailure, withTransportDetail, toCallToolResult, renderProgress, toolError, needsAuthorizationResult, MCP_IMAGE_RESULT_KIND, type McpImageResult, mcpImageResult, isMcpImageResult, omitImagePayloads, } from './results.js';
+export { codeModeMetaTools, chainNamespaceExample, META_TOOL_NAMES, CALL_TOOL_CHAIN_MAX_OUTPUT, CALL_TOOL_CHAIN_NAME, CHAIN_FAILURES_RULE, CHAIN_LARGE_RESULTS_RULE, type CodeModeMetaToolsOptions, type SpillPort, dispatchMetaTool, } from './meta-tools.js';
+export { CHAIN_RUNTIME_PRELUDE, CHAIN_TIMEOUT_DEFAULT_MS, CHAIN_TIMEOUT_MAX_MS, CHAIN_TIMEOUT_MIN_MS, type ChainNamespaces, type ToolChainOutcome, chainNamespaces, chainOutOfMemoryMessage, chainTimeoutMessage, describeChainFailure, runToolChain, unknownNamespaceMessage, withChainRuntime, } from './chain-runtime.js';
+export { type ChainExample, type ChainExampleTool, chainExample, } from './chain-example.js';
 export { registerManual, dispatchToolCall } from './dispatch.js';
-export { RETIRED_TOOL_MESSAGES, RETIRED_TOOL_NAMES, retiredToolMessage, retiredToolInFailure, retiredToolChainFailure, } from './retired-tools.js';
+export { RETIRED_TOOL_MESSAGES, RETIRED_TOOL_NAMES, retiredToolMessage, retiredToolInFailure, } from './retired-tools.js';
 export { isSessionLoss, installSessionRecovery, noteManualReregistered, type SessionRecoveryOptions, } from './session-recovery.js';
 export { type SkillSummary, type LoadedSkill, skillPromptText, } from './skills.js';
 export { utcpNamespacePrefix, utcpNamespacedKey, seedBevelHostedManualVars, } from './utcp-namespace.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,cAAc,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,0BAA0B,EAC1B,KAAK,SAAS,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EACL,KAAK,WAAW,EAChB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EACrB,KAAK,cAAc,EACnB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,SAAS,EACd,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -26,10 +26,12 @@
  * thing as session recovery, and stays each surface's own.
  */
 export { toListedTool, sanitizeInputSchema, flattenManualTool, flattenDiscoveredTool, } from './proxied-tool.js';
-export { describeToolFailure, toCallToolResult, renderProgress, toolError, needsAuthorizationResult, MCP_IMAGE_RESULT_KIND, mcpImageResult, isMcpImageResult, omitImagePayloads, } from './results.js';
-export { CODE_MODE_META_TOOLS, META_TOOL_NAMES, CALL_TOOL_CHAIN_MAX_OUTPUT, dispatchMetaTool, } from './meta-tools.js';
+export { describeToolFailure, withTransportDetail, toCallToolResult, renderProgress, toolError, needsAuthorizationResult, MCP_IMAGE_RESULT_KIND, mcpImageResult, isMcpImageResult, omitImagePayloads, } from './results.js';
+export { codeModeMetaTools, chainNamespaceExample, META_TOOL_NAMES, CALL_TOOL_CHAIN_MAX_OUTPUT, CALL_TOOL_CHAIN_NAME, CHAIN_FAILURES_RULE, CHAIN_LARGE_RESULTS_RULE, dispatchMetaTool, } from './meta-tools.js';
+export { CHAIN_RUNTIME_PRELUDE, CHAIN_TIMEOUT_DEFAULT_MS, CHAIN_TIMEOUT_MAX_MS, CHAIN_TIMEOUT_MIN_MS, chainNamespaces, chainOutOfMemoryMessage, chainTimeoutMessage, describeChainFailure, runToolChain, unknownNamespaceMessage, withChainRuntime, } from './chain-runtime.js';
+export { chainExample, } from './chain-example.js';
 export { registerManual, dispatchToolCall } from './dispatch.js';
-export { RETIRED_TOOL_MESSAGES, RETIRED_TOOL_NAMES, retiredToolMessage, retiredToolInFailure, retiredToolChainFailure, } from './retired-tools.js';
+export { RETIRED_TOOL_MESSAGES, RETIRED_TOOL_NAMES, retiredToolMessage, retiredToolInFailure, } from './retired-tools.js';
 export { isSessionLoss, installSessionRecovery, noteManualReregistered, } from './session-recovery.js';
 export { skillPromptText, } from './skills.js';
 export { utcpNamespacePrefix, utcpNamespacedKey, seedBevelHostedManualVars, } from './utcp-namespace.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,0BAA0B,EAE1B,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EAGxB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EAGpB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/meta-tools.d.ts

@@ -1,6 +1,105 @@
 import type { Tool as McpTool, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import type { CodeModeUtcpClient } from '@utcp/code-mode';
-export declare const CODE_MODE_META_TOOLS: McpTool[];
+import { type ChainExampleTool } from './chain-example.js';
+/**
+ * Code-mode meta-tools exposed ALONGSIDE the direct tools. They let an external
+ * agent batch many Bevel calls into one isolated-vm run (`call_tool_chain`)
+ * instead of one MCP round-trip per call — the same efficiency our own agent
+ * gets. `call_tool_chain`'s description carries the code-mode protocol, so the
+ * client learns the convention from the tool itself; `list_tools`/`tools_info`
+ * are how it discovers what to call. There IS a system prompt over MCP now: the
+ * platform header and the admin's preamble arrive as `instructions` on the
+ * initialize handshake (see core-backend's modules/agent-instructions/compose.ts).
+ * The PROTOCOL stays in the description regardless, because several clients
+ * (claude.ai on the web, the Agent SDK, Cline) drop that field.
+ *
+ * What a chain DOES, though — to a failure, to a large result, to an image —
+ * is true of every call, and those rules are stated once, in the handshake
+ * instructions and in the platform-managed agent guide, rather than on each
+ * tool they cover. So on a surface that has those rules the chain description
+ * ends with the same pointer sentence every file tool ends with, composed
+ * where the tool is served and the guide's configured name is known
+ * (core-backend's mcp.service.ts; nothing here may spell `AGENTS.md`, since
+ * the name is a deployment setting). A client that drops `instructions` is
+ * then still told WHERE the rules are, which is what the guide is for.
+ * The standalone bridge in `hexis-mcp` passes no pointer and so serves the
+ * description WHOLE, rules included: it proxies a remote knowledge base and
+ * does not know that deployment's layout.
+ *
+ * Security is identical to the direct surface: the chain runs in an isolated-vm
+ * but calls tools with the CALLER's credentials against the external catalog —
+ * internal-only tools aren't in that catalog, so a chain can't reach them either.
+ *
+ * These three belong to whichever client holds the registry. A surface that
+ * registers ANOTHER Bevel MCP endpoint as one of its manuals therefore has to
+ * drop that endpoint's copies from the passthrough (see {@link META_TOOL_NAMES}):
+ * the remote trio describes the remote registry, and locally they must describe
+ * the merged one.
+ */
+/** The chain tool's name, for the callers that single it out by name. */
+export declare const CALL_TOOL_CHAIN_NAME = "call_tool_chain";
+/**
+ * The namespace every example in the three descriptions is written against.
+ *
+ * It is NOT fixed text, because it is not the same name on every connection:
+ * the hosted endpoint registers the knowledge-base tools as `KNOWLEDGE_BASE`,
+ * while the local server registers the whole deployment as one `hexis` manual.
+ * A description that named the other one taught the agent a namespace the
+ * runtime had no binding for, and the example call it copied died of
+ * `ReferenceError` — which is how this was reported. So each surface passes
+ * the name it actually registers, and the examples are built from it.
+ *
+ * Sanitized the way the runtime sanitizes it, so the example is callable even
+ * when the registered manual's name is not a bare identifier: `@utcp/code-mode`
+ * exposes `global.<sanitized manual name>`, and an example spelled any other
+ * way would not run.
+ */
+export declare function chainNamespaceExample(namespace: string): string;
+/**
+ * What a chain does when it FAILS — one of the rules about a chain that are
+ * true of every call, not of how to write one.
+ *
+ * Exported as text because it is stated in ONE of two places, never both: in
+ * the rules every tool shares (the handshake instructions and the managed
+ * agent guide, see core-backend's `agent-instructions/shared-file-rules.ts`)
+ * on a surface that has them, and in the chain's own description on one that
+ * does not. The same sentences either way, so the rule cannot read differently
+ * depending on where an agent found it.
+ */
+export declare const CHAIN_FAILURES_RULE = "Failures are answered, never dropped: a chain that throws comes back as an error carrying the reason, and one that outlives `timeout` (default 30000 ms, maximum 120000 ms) comes back saying so \u2014 raise `timeout` or split the work and run it again. Either way the connection stays open and your next call works as usual.";
+/** What a chain does with a result too large to return. Placed as {@link CHAIN_FAILURES_RULE} is. */
+export declare const CHAIN_LARGE_RESULTS_RULE = "Large results: if the combined result+logs exceed `max_output_size` (default 200000 chars) the full JSON is spilled to a shared store and you get back a `__tool_chain_spill__/\u2026` ref instead. Read it with `read_file` (pass that ref as `path` \u2014 `branch` is ignored \u2014 plus `offset`/`limit` to slice it), or better, re-run a narrower chain that returns only what you need.";
+/** What a surface says about itself when it asks for the meta-tools. */
+export interface CodeModeMetaToolsOptions {
+    /**
+     * The sentence that ends the chain's description on a surface whose
+     * knowledge base states the shared rules (see {@link callToolChainDescription}).
+     * Opaque text: the caller composes it, because it names the agent guide and
+     * that name is a deployment setting — nothing here may spell `AGENTS.md`.
+     * Absent, the description carries the chain's rules itself.
+     */
+    sharedRulesPointer?: string;
+}
+/**
+ * The three meta-tools, with every example written against the namespace this
+ * connection really exposes and a tool name its catalog really has.
+ *
+ * Built per listing rather than held as a module constant: both belong to the
+ * surface, and a description computed once and shared across surfaces is the
+ * fixed text this replaces. `tools` is the surface's catalog — pass every tool
+ * it serves, names AND input schemas, since the arguments in the example come
+ * from the schema (see `chainExample`).
+ *
+ * `list_tools` and `tools_info` describe the registry, not what a call does,
+ * so neither ever carried a shared rule and neither gains the pointer.
+ */
+export declare function codeModeMetaTools(namespace: string, tools?: readonly ChainExampleTool[], options?: CodeModeMetaToolsOptions): McpTool[];
+/**
+ * The meta-tool NAMES, which no namespace can change. Kept separate from
+ * {@link codeModeMetaTools} because every surface needs them to route a call
+ * and to keep a discovered copy out of its listing, and neither of those knows
+ * — or should need — the namespace.
+ */
 export declare const META_TOOL_NAMES: ReadonlySet<string>;
 /** Default cap on a `call_tool_chain` result's stringified size before it spills. */
 export declare const CALL_TOOL_CHAIN_MAX_OUTPUT = 200000;

package/dist/meta-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta-tools.d.ts","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAkC1D,eAAO,MAAM,oBAAoB,EAAE,OAAO,EAkCzC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAAoD,CAAC;AAErG,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAgBlD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAAC,cAAc,CAAC,CA+FzB"}
+{"version":3,"file":"meta-tools.d.ts","sourceRoot":"","sources":["../src/meta-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,IAAI,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,EAAmC,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAU5F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,wUAA8W,CAAC;AAE/Y,qGAAqG;AACrG,eAAO,MAAM,wBAAwB,oYAC+U,CAAC;AAyCrX,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,SAAS,gBAAgB,EAAO,EACvC,OAAO,GAAE,wBAA6B,GACrC,OAAO,EAAE,CA0CX;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAA+D,CAAC;AAChH,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAgBlD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,kBAAkB,EAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAAC,cAAc,CAAC,CAkHzB"}