@bevel-software/platform-mcp-core 0.23.0 → 0.25.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/google-service-account/google-auth-http.protocol.d.ts

@@ -0,0 +1,24 @@
+import { type CallTemplate, type IUtcpClient } from '@utcp/sdk';
+import { HttpCommunicationProtocol } from '@utcp/http';
+import type { IServiceAccountTokenSource } from './service-account-token.contract.js';
+/**
+ * The stock UTCP `http` protocol, taught one more auth type. A call whose
+ * template names `google_service_account` is handed to the stock protocol with
+ * that auth swapped for the bearer token it resolves to (as `oauth2_user`,
+ * which the stock protocol sends as `Authorization: Bearer <token>` and strips
+ * on a cross-origin redirect). Every other call passes through untouched.
+ */
+export declare class GoogleAuthHttpProtocol extends HttpCommunicationProtocol {
+    private readonly tokens;
+    constructor(tokens: IServiceAccountTokenSource);
+    callTool(caller: IUtcpClient, toolName: string, toolArgs: Record<string, unknown>, toolCallTemplate: CallTemplate): Promise<unknown>;
+    callToolStreaming(caller: IUtcpClient, toolName: string, toolArgs: Record<string, unknown>, toolCallTemplate: CallTemplate): AsyncGenerator<unknown, void, unknown>;
+    private withBearerToken;
+}
+/**
+ * Put the service-account-aware protocol in place of the stock `http` one,
+ * minting tokens from `tokens`. Exported so a suite can answer for Google;
+ * a process never needs to call it, since loading this module already has.
+ */
+export declare function installGoogleServiceAccountAuth(tokens?: IServiceAccountTokenSource): void;
+//# sourceMappingURL=google-auth-http.protocol.d.ts.map

package/dist/google-service-account/google-auth-http.protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-auth-http.protocol.d.ts","sourceRoot":"","sources":["../../src/google-service-account/google-auth-http.protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,yBAAyB,EAAyB,MAAM,YAAY,CAAC;AAG9E,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AAEtF;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,yBAAyB;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,0BAA0B;IAIhD,QAAQ,CACrB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,gBAAgB,EAAE,YAAY,GAC7B,OAAO,CAAC,OAAO,CAAC;IAIH,iBAAiB,CAC/B,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,gBAAgB,EAAE,YAAY,GAC7B,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC;YAI3B,eAAe;CAM9B;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,GAAE,0BAAkE,GACzE,IAAI,CAEN"}

package/dist/google-service-account/google-auth-http.protocol.js

@@ -0,0 +1,47 @@
+import { CommunicationProtocol } from '@utcp/sdk';
+import { HttpCommunicationProtocol } from '@utcp/http';
+import { isGoogleServiceAccountAuth } from './google-service-account.auth.js';
+import { GoogleServiceAccountTokenSource } from './google-service-account.token-source.js';
+/**
+ * The stock UTCP `http` protocol, taught one more auth type. A call whose
+ * template names `google_service_account` is handed to the stock protocol with
+ * that auth swapped for the bearer token it resolves to (as `oauth2_user`,
+ * which the stock protocol sends as `Authorization: Bearer <token>` and strips
+ * on a cross-origin redirect). Every other call passes through untouched.
+ */
+export class GoogleAuthHttpProtocol extends HttpCommunicationProtocol {
+    tokens;
+    constructor(tokens) {
+        super();
+        this.tokens = tokens;
+    }
+    async callTool(caller, toolName, toolArgs, toolCallTemplate) {
+        return super.callTool(caller, toolName, toolArgs, await this.withBearerToken(toolCallTemplate));
+    }
+    async *callToolStreaming(caller, toolName, toolArgs, toolCallTemplate) {
+        yield* super.callToolStreaming(caller, toolName, toolArgs, await this.withBearerToken(toolCallTemplate));
+    }
+    async withBearerToken(template) {
+        const auth = template.auth;
+        if (!isGoogleServiceAccountAuth(auth))
+            return template;
+        const accessToken = await this.tokens.accessToken(auth);
+        return { ...template, auth: { auth_type: 'oauth2_user', access_token: accessToken } };
+    }
+}
+/**
+ * Put the service-account-aware protocol in place of the stock `http` one,
+ * minting tokens from `tokens`. Exported so a suite can answer for Google;
+ * a process never needs to call it, since loading this module already has.
+ */
+export function installGoogleServiceAccountAuth(tokens = new GoogleServiceAccountTokenSource()) {
+    CommunicationProtocol.communicationProtocols['http'] = new GoogleAuthHttpProtocol(tokens);
+}
+// Installed on module load, the way `@utcp/http` installs the protocol this
+// one replaces: once per process, before any client exists (a client copies
+// the registry when it is built). The import of `@utcp/http` above has already
+// run its own registration by the time this line does, whatever order the
+// importing module lists the two in. One token cache then serves the process;
+// its entries are keyed by the key itself, so knowledge bases never share one.
+installGoogleServiceAccountAuth();
+//# sourceMappingURL=google-auth-http.protocol.js.map

package/dist/google-service-account/google-auth-http.protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-auth-http.protocol.js","sourceRoot":"","sources":["../../src/google-service-account/google-auth-http.protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAuC,MAAM,WAAW,CAAC;AACvF,OAAO,EAAE,yBAAyB,EAAyB,MAAM,YAAY,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,+BAA+B,EAAE,MAAM,0CAA0C,CAAC;AAG3F;;;;;;GAMG;AACH,MAAM,OAAO,sBAAuB,SAAQ,yBAAyB;IACtC;IAA7B,YAA6B,MAAkC;QAC7D,KAAK,EAAE,CAAC;QADmB,WAAM,GAAN,MAAM,CAA4B;IAE/D,CAAC;IAEQ,KAAK,CAAC,QAAQ,CACrB,MAAmB,EACnB,QAAgB,EAChB,QAAiC,EACjC,gBAA8B;QAE9B,OAAO,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAClG,CAAC;IAEQ,KAAK,CAAC,CAAC,iBAAiB,CAC/B,MAAmB,EACnB,QAAgB,EAChB,QAAiC,EACjC,gBAA8B;QAE9B,KAAK,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,IAAI,CAAC,eAAe,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC3G,CAAC;IAEO,KAAK,CAAC,eAAe,CAAC,QAAsB;QAClD,MAAM,IAAI,GAAI,QAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC;YAAE,OAAO,QAAQ,CAAC;QACvD,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACxD,OAAO,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,EAAkB,CAAC;IACxG,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAC7C,SAAqC,IAAI,+BAA+B,EAAE;IAE1E,qBAAqB,CAAC,sBAAsB,CAAC,MAAM,CAAC,GAAG,IAAI,sBAAsB,CAAC,MAAM,CAAC,CAAC;AAC5F,CAAC;AAED,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,0EAA0E;AAC1E,8EAA8E;AAC9E,+EAA+E;AAC/E,+BAA+B,EAAE,CAAC"}

package/dist/google-service-account/google-service-account.auth.d.ts

@@ -0,0 +1,45 @@
+import { type GoogleServiceAccountAuth } from './service-account-token.contract.js';
+/** Whether a call template's `auth` asks for a Google service-account token. */
+export declare function isGoogleServiceAccountAuth(auth: unknown): auth is GoogleServiceAccountAuth;
+/**
+ * Where in `doc` a `google_service_account` auth block sits that nothing will
+ * act on, as a phrase for a refusal, or null when every block is the `auth` of
+ * one of `toolCallTemplates` and that template is an `http` one.
+ *
+ * `toolCallTemplates` are the templates tools are really called through, which
+ * only the caller knows: the document's shape is its business. A block
+ * anywhere else is read by nothing, whatever the object around it looks like:
+ * a template the document never registers, an `auth_tools`, a block at the
+ * root of a file that discovers its tools from a url.
+ *
+ * UTCP validates an auth type on any call template that takes an `auth`, but
+ * only the `http` protocol mints the token. Every other protocol sends an auth
+ * type it does not know as no credentials at all, so such a tool would save
+ * cleanly and then call Google unauthenticated.
+ *
+ * Every block in the document is found, at any depth (see
+ * `googleServiceAccountBlocks`), and the first one in document order that
+ * nothing will act on is the one named.
+ */
+export declare function findUnservedGoogleServiceAccountAuth(doc: unknown, toolCallTemplates: readonly unknown[]): string | null;
+/**
+ * Whether any `google_service_account` block in `doc` has its key WRITTEN IN
+ * THE DOCUMENT: a `credentials` that is anything but one variable reference.
+ *
+ * The document is a `.tool`, which is knowledge-base content: it is committed
+ * to the repository, and read by everyone and every agent that can read the
+ * knowledge base. A key written into it is a key all of them hold, for as
+ * long as the history keeps it. So the place for the key is the vault, and
+ * `credentials` only ever names the variable.
+ *
+ * Asked of the document as its author wrote it, wherever the block sits: a
+ * key in a block nothing will act on is just as readable. It cannot be asked
+ * where the auth type itself is validated, because that also runs on the
+ * template AFTER its variables were substituted, where `credentials` is the
+ * key and has to be.
+ *
+ * Says only that one was found. It never returns, quotes or measures the
+ * value: what it would be describing is the secret.
+ */
+export declare function holdsLiteralGoogleServiceAccountKey(doc: unknown): boolean;
+//# sourceMappingURL=google-service-account.auth.d.ts.map

package/dist/google-service-account/google-service-account.auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-service-account.auth.d.ts","sourceRoot":"","sources":["../../src/google-service-account/google-service-account.auth.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoC,KAAK,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AA0BtH,gFAAgF;AAChF,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,wBAAwB,CAM1F;AAYD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oCAAoC,CAAC,GAAG,EAAE,OAAO,EAAE,iBAAiB,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,GAAG,IAAI,CASvH;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOzE"}

package/dist/google-service-account/google-service-account.auth.js

@@ -0,0 +1,153 @@
+import { AuthSerializer, Serializer } from '@utcp/sdk';
+import { z } from 'zod';
+import { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE } from './service-account-token.contract.js';
+const GoogleServiceAccountAuthSchema = z.object({
+    auth_type: z.literal(GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE),
+    credentials: z
+        .string()
+        .min(1)
+        .describe('The service-account key JSON. Recommended to use a vault variable like "${GOOGLE_SA_KEY}".'),
+    // Trimmed before the length check, so a blank scope is refused here rather
+    // than reaching Google as an empty one.
+    scopes: z
+        .union([z.string().trim().min(1), z.array(z.string().trim().min(1)).min(1)])
+        .describe('OAuth scopes for the token, e.g. "https://www.googleapis.com/auth/adwords".'),
+    subject: z.string().trim().min(1).optional().describe('User to impersonate under domain-wide delegation.'),
+});
+class GoogleServiceAccountAuthSerializer extends Serializer {
+    toDict(obj) {
+        return { ...obj };
+    }
+    validateDict(obj) {
+        return GoogleServiceAccountAuthSchema.parse(obj);
+    }
+}
+/** Whether a call template's `auth` asks for a Google service-account token. */
+export function isGoogleServiceAccountAuth(auth) {
+    return (typeof auth === 'object' &&
+        auth !== null &&
+        auth.auth_type === GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE);
+}
+/** The one call template type whose protocol turns the key into a token. */
+const SERVED_CALL_TEMPLATE_TYPE = 'http';
+/**
+ * The other call template types an author is likely to have reached for, which
+ * the answer below may name. A type outside this list is the file's own text,
+ * and is described rather than quoted back.
+ */
+const NAMEABLE_CALL_TEMPLATE_TYPES = ['sse', 'streamable_http', 'mcp', 'cli'];
+/**
+ * Where in `doc` a `google_service_account` auth block sits that nothing will
+ * act on, as a phrase for a refusal, or null when every block is the `auth` of
+ * one of `toolCallTemplates` and that template is an `http` one.
+ *
+ * `toolCallTemplates` are the templates tools are really called through, which
+ * only the caller knows: the document's shape is its business. A block
+ * anywhere else is read by nothing, whatever the object around it looks like:
+ * a template the document never registers, an `auth_tools`, a block at the
+ * root of a file that discovers its tools from a url.
+ *
+ * UTCP validates an auth type on any call template that takes an `auth`, but
+ * only the `http` protocol mints the token. Every other protocol sends an auth
+ * type it does not know as no credentials at all, so such a tool would save
+ * cleanly and then call Google unauthenticated.
+ *
+ * Every block in the document is found, at any depth (see
+ * `googleServiceAccountBlocks`), and the first one in document order that
+ * nothing will act on is the one named.
+ */
+export function findUnservedGoogleServiceAccountAuth(doc, toolCallTemplates) {
+    const served = new Set(toolCallTemplates);
+    for (const { parent, key } of googleServiceAccountBlocks(doc)) {
+        // Judged by where it sits, so once per place it appears: an aliased
+        // block can be served in one place and ignored in another.
+        const where = unservedPlacement(parent, key, served);
+        if (where)
+            return where;
+    }
+    return null;
+}
+/** `${NAME}` or `$NAME`, as UTCP spells a variable, and nothing else around it. */
+const ONE_VARIABLE_REFERENCE = /^\s*(?:\$\{[a-zA-Z0-9_]+\}|\$[a-zA-Z0-9_]+)\s*$/;
+/**
+ * Whether any `google_service_account` block in `doc` has its key WRITTEN IN
+ * THE DOCUMENT: a `credentials` that is anything but one variable reference.
+ *
+ * The document is a `.tool`, which is knowledge-base content: it is committed
+ * to the repository, and read by everyone and every agent that can read the
+ * knowledge base. A key written into it is a key all of them hold, for as
+ * long as the history keeps it. So the place for the key is the vault, and
+ * `credentials` only ever names the variable.
+ *
+ * Asked of the document as its author wrote it, wherever the block sits: a
+ * key in a block nothing will act on is just as readable. It cannot be asked
+ * where the auth type itself is validated, because that also runs on the
+ * template AFTER its variables were substituted, where `credentials` is the
+ * key and has to be.
+ *
+ * Says only that one was found. It never returns, quotes or measures the
+ * value: what it would be describing is the secret.
+ */
+export function holdsLiteralGoogleServiceAccountKey(doc) {
+    for (const { block } of googleServiceAccountBlocks(doc)) {
+        const { credentials } = block;
+        // Not a string is not a key either; the auth type's own schema refuses it.
+        if (typeof credentials === 'string' && !ONE_VARIABLE_REFERENCE.test(credentials))
+            return true;
+    }
+    return false;
+}
+/**
+ * Every `google_service_account` auth block in `doc`, at any depth, with the
+ * object it sits in and the key it sits under, in document order.
+ *
+ * The walk keeps its own stack, so a deeply nested document cannot overflow
+ * the call stack, and it does not re-enter an object it has seen: a YAML
+ * anchor aliased inside itself parses to a cyclic object. A block is yielded
+ * once per place it appears, since an aliased one sits in several.
+ */
+function* googleServiceAccountBlocks(doc) {
+    const seen = new WeakSet();
+    const pending = [{ node: doc }];
+    for (let next = pending.pop(); next; next = pending.pop()) {
+        const { node, parent, key } = next;
+        if (!node || typeof node !== 'object')
+            continue;
+        if (isGoogleServiceAccountAuth(node)) {
+            yield { block: node, parent, key };
+            continue;
+        }
+        if (seen.has(node))
+            continue;
+        seen.add(node);
+        // Pushed in reverse, so blocks come out in document order.
+        if (Array.isArray(node)) {
+            for (let i = node.length - 1; i >= 0; i--)
+                pending.push({ node: node[i] });
+        }
+        else {
+            const obj = node;
+            const keys = Object.keys(obj);
+            for (let i = keys.length - 1; i >= 0; i--)
+                pending.push({ node: obj[keys[i]], parent: obj, key: keys[i] });
+        }
+    }
+}
+/** Why a block under `parent[key]` is acted on by nothing, or null when it is. */
+function unservedPlacement(parent, key, served) {
+    if (!parent || key !== 'auth' || typeof parent.call_template_type !== 'string') {
+        return "somewhere that is not a call template's `auth`";
+    }
+    const type = parent.call_template_type.toLowerCase().trim();
+    if (type !== SERVED_CALL_TEMPLATE_TYPE) {
+        return NAMEABLE_CALL_TEMPLATE_TYPES.includes(type) ? `a \`${type}\` call template` : 'a call template that is not an `http` one';
+    }
+    return served.has(parent) ? null : 'an `http` call template that no tool is called through';
+}
+// Register the auth type on module load, so a `.tool` naming it validates
+// wherever UTCP parses a call template: the inline manual route, the preview,
+// and the client re-validating a template after substituting its variables.
+// UTCP's registry is process-wide and the type carries no state, so one
+// registration serves every knowledge base. Idempotent (safe under hot-reload).
+AuthSerializer.registerAuth(GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, new GoogleServiceAccountAuthSerializer(), true);
+//# sourceMappingURL=google-service-account.auth.js.map