@mate-academy/llm-gateway 8.0.0 → 8.2.0

package/dist/client/LLMClientEngine.js

@@ -0,0 +1,350 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMClientEngine = void 0;
+const LLMService_typedefs_1 = require("../LLMService.typedefs");
+const LLMAgent_1 = require("../client/LLMAgent");
+const agentRunner_1 = require("../client/agentRunner");
+const plainMessages_1 = require("../client/plainMessages");
+const coerceToolResult_1 = require("../client/coerceToolResult");
+const promptVariables_1 = require("../client/promptVariables");
+const errors_1 = require("../client/errors");
+/**
+ * The client's single implementation. `createLLMClient` owns its construction
+ * and exposes only the `LLMClient` surface, so every call path — `generate`,
+ * `countTokens`, `runAgent`, `describePrompt` — shares one prompt resolution,
+ * one credentials lookup, one reporter/trace context, and one error taxonomy.
+ */
+class LLMClientEngine {
+    gateway;
+    registry;
+    runtime;
+    credentials;
+    reporter;
+    logger;
+    staticContext;
+    mode;
+    toolResultNormalizer;
+    agentRunner;
+    constructor(config) {
+        this.gateway = config.gateway;
+        this.registry = config.registry;
+        this.runtime = config.runtime;
+        this.credentials = config.credentials;
+        this.reporter = config.reporter;
+        this.logger = config.logger;
+        this.staticContext = config.staticContext;
+        this.mode = config.mode;
+        this.toolResultNormalizer = config.normalizeToolResult;
+        this.agentRunner = new agentRunner_1.LLMAgentRunner(this, config.logger);
+    }
+    async generate(prompt, options) {
+        const promptName = String(prompt);
+        const binding = this.registry[prompt];
+        const schema = options.schema ?? binding.schema;
+        this.assertOverridesAllowed(promptName, options.overrides);
+        const resolved = await this.resolvePrompt(promptName, binding, options.variables, {
+            purpose: LLMService_typedefs_1.LLMPurposes.Completion,
+            overrides: options.overrides,
+        });
+        return this.runCompletion(resolved, schema, options);
+    }
+    defineAgent(definition) {
+        return new LLMAgent_1.LLMAgent(definition);
+    }
+    async runAgent(promptOrAgent, options) {
+        const agent = promptOrAgent instanceof LLMAgent_1.LLMAgent ? promptOrAgent : undefined;
+        const promptKey = (agent ? agent.prompt : promptOrAgent);
+        const promptName = String(promptKey);
+        const binding = this.registry[promptKey];
+        this.assertOverridesAllowed(promptName, options.overrides);
+        const runResult = await this.agentRunner.run({
+            agentName: agent?.name ?? promptName,
+            promptName,
+            binding,
+            variables: { ...agent?.variables, ...options.variables },
+            input: options.input,
+            history: options.history,
+            tools: agent ? agent.tools : options.tools,
+            subagents: (agent ? agent.subagents : options.subagents),
+            maxToolIterations: agent
+                ? agent.maxToolIterations
+                : options.maxToolIterations,
+            context: options.context,
+            abortSignal: options.abortSignal,
+            overrides: options.overrides,
+            onEvent: options.onEvent,
+        });
+        return runResult;
+    }
+    async countTokens(prompt, options) {
+        const promptName = String(prompt);
+        const binding = this.registry[prompt];
+        const resolved = await this.resolvePrompt(promptName, binding, options.variables, { purpose: LLMService_typedefs_1.LLMPurposes.Completion });
+        const service = await this.buildCompletionService(resolved, promptName);
+        const envelope = this.buildMessageEnvelope(resolved, options.history);
+        return service.countTokens([...envelope.history, envelope.message], resolved.model);
+    }
+    async describePrompt(prompt) {
+        const promptName = String(prompt);
+        const binding = this.registry[prompt];
+        const metadata = await this.runtime.describe({
+            name: promptName,
+            kind: binding.kind === 'chat' ? 'chat' : 'text',
+            requires: binding.requires ?? [],
+            purpose: LLMService_typedefs_1.LLMPurposes.Completion,
+        });
+        if (!metadata) {
+            throw new errors_1.LLMConfigError(`unable to resolve routing metadata for "${promptName}" (live and `
+                + 'fallback both unusable)', { promptName });
+        }
+        return {
+            provider: metadata.provider,
+            model: metadata.model,
+            promptVersion: metadata.promptVersion,
+            isFallback: metadata.isFallback,
+        };
+    }
+    async resolvePrompt(promptName, binding, variables, call) {
+        const resolved = await this.runtime.resolve({
+            name: promptName,
+            kind: binding.kind === 'chat' ? 'chat' : 'text',
+            variables: (0, promptVariables_1.stringifyPromptVariables)(variables),
+            requires: [
+                ...(binding.requires ?? []),
+                ...(call.additionalRequires ?? []),
+            ],
+            purpose: call.purpose,
+            versionOverride: call.overrides?.promptVersion,
+            labelOverride: call.overrides?.promptLabel,
+        });
+        if (!resolved) {
+            throw new errors_1.LLMConfigError(`unable to resolve a valid prompt for "${promptName}" (live and fallback unusable)`, { promptName });
+        }
+        return resolved;
+    }
+    /**
+     * The single place a tool's return value becomes what the model reads. The
+     * package's own coercion always runs first, so a client-supplied normalizer
+     * never sees a malformed value and cannot reintroduce one.
+     */
+    normalizeToolResult(context) {
+        const coerced = (0, coerceToolResult_1.coerceToolResult)(context.result);
+        if (!this.toolResultNormalizer) {
+            return coerced;
+        }
+        return (0, coerceToolResult_1.coerceToolResult)(this.toolResultNormalizer({ ...context, result: coerced }));
+    }
+    async runCompletion(resolved, schema, options) {
+        const service = await this.buildCompletionService(resolved, resolved.name);
+        const envelope = this.buildMessageEnvelope(resolved, options.history);
+        const reporterContext = this.buildReporterContext(resolved, options.context);
+        const traceContext = this.buildTraceContext(resolved, options.context);
+        const sendResult = await this.callProvider(() => (schema
+            ? service.sendMessage({
+                message: envelope.message,
+                model: resolved.model,
+                history: envelope.history,
+                instructions: envelope.instructions,
+                schema,
+                abortSignal: options.abortSignal,
+                reporterContext,
+                traceContext,
+            })
+            : service.sendMessage({
+                message: envelope.message,
+                model: resolved.model,
+                history: envelope.history,
+                instructions: envelope.instructions,
+                abortSignal: options.abortSignal,
+                reporterContext,
+                traceContext,
+            })), resolved, options.abortSignal);
+        return this.unwrapResult(resolved, schema, sendResult);
+    }
+    /**
+     * Builds the provider message envelope from the resolved prompt. A `text`
+     * prompt is one user message. A `chat` prompt preserves the structure the
+     * prompt declares: a leading `system` message maps to `instructions`, the final
+     * `user` message is the request, and any messages between them join the
+     * call-supplied history in order.
+     */
+    buildMessageEnvelope(resolved, callHistory) {
+        if (resolved.kind !== 'chat') {
+            return {
+                message: this.buildUserMessage(resolved.text),
+                history: this.buildHistory(callHistory),
+                instructions: undefined,
+            };
+        }
+        const systemMessage = resolved.messages.find((message) => message.role === 'system');
+        const conversation = resolved.messages.filter((message) => message.role !== 'system');
+        const lastUserIndex = this.findLastUserIndex(conversation);
+        const promptHistory = conversation
+            .filter((_, index) => index !== lastUserIndex)
+            .map((message) => this.toCompletionMessage(message.role, message.content));
+        const requestText = lastUserIndex >= 0
+            ? conversation[lastUserIndex].content
+            : resolved.text;
+        return {
+            message: this.buildUserMessage(requestText),
+            history: [...promptHistory, ...this.buildHistory(callHistory)],
+            instructions: systemMessage?.content,
+        };
+    }
+    findLastUserIndex(messages) {
+        for (let index = messages.length - 1; index >= 0; index -= 1) {
+            if (messages[index].role === 'user') {
+                return index;
+            }
+        }
+        return -1;
+    }
+    async callProvider(send, resolved, abortSignal) {
+        try {
+            const result = await send();
+            if (result && typeof result === 'object' && 'error' in result) {
+                throw result.error;
+            }
+            return result;
+        }
+        catch (error) {
+            throw this.toTaxonomyError(error, resolved, abortSignal);
+        }
+    }
+    unwrapResult(resolved, schema, sendResult) {
+        if (!schema) {
+            return sendResult.text ?? '';
+        }
+        if (sendResult.parseError || sendResult.data === undefined) {
+            throw new errors_1.LLMSchemaValidationError(`structured output for "${resolved.name}" failed schema validation`, {
+                promptName: resolved.name,
+                provider: resolved.config.provider,
+                model: resolved.config.model,
+                rawText: sendResult.text ?? '',
+                parseDetails: sendResult.parseError ?? 'no data returned',
+            });
+        }
+        return sendResult.data;
+    }
+    toTaxonomyError(error, resolved, abortSignal) {
+        const context = {
+            promptName: resolved.name,
+            provider: resolved.config.provider,
+            model: resolved.config.model,
+            cause: error,
+        };
+        if (abortSignal?.aborted) {
+            return new errors_1.LLMAbortedError('LLM call aborted', context);
+        }
+        const status = this.extractStatus(error);
+        return new errors_1.LLMProviderError(error instanceof Error ? error.message : String(error), { ...context, retryable: this.isRetryableStatus(status), status });
+    }
+    async buildAssistanceService(resolved, promptName) {
+        const providerOptions = await this.resolveProviderOptions(resolved, promptName);
+        return this.gateway.getAssistanceService({
+            provider: resolved.config.provider,
+            options: providerOptions,
+            logger: this.logger,
+            reporter: this.reporter,
+        });
+    }
+    getBinding(promptName) {
+        return this.registry[promptName];
+    }
+    async buildCompletionService(resolved, promptName) {
+        const providerOptions = await this.resolveProviderOptions(resolved, promptName);
+        return this.gateway.getCompletionService({
+            provider: resolved.config.provider,
+            options: providerOptions,
+            logger: this.logger,
+            reporter: this.reporter,
+        });
+    }
+    async resolveProviderOptions(resolved, promptName) {
+        return this.credentials({
+            provider: resolved.config.provider,
+            promptName,
+            product: this.staticContext.product,
+        });
+    }
+    buildUserMessage(text) {
+        return this.toCompletionMessage('user', text);
+    }
+    buildHistory(history) {
+        return (0, plainMessages_1.plainMessagesToContentMessages)(history);
+    }
+    toCompletionMessage(role, text) {
+        return {
+            role: role === 'assistant' ? LLMService_typedefs_1.LLMRoles.Assistant : LLMService_typedefs_1.LLMRoles.User,
+            content: [{ type: LLMService_typedefs_1.LLMMessageContentType.TEXT, text }],
+        };
+    }
+    buildReporterContext(resolved, callContext) {
+        if (!this.reporter) {
+            return undefined;
+        }
+        return {
+            ...this.staticContext,
+            ...this.serializeCallContext(callContext),
+            promptName: resolved.name,
+            promptVersion: resolved.version,
+        };
+    }
+    /**
+     * Builds the per-call trace context every client path threads into the gateway
+     * service. The structural `prompt` names the observation and carries the
+     * managed prompt version, so the generation the service records on success and
+     * on error is the single one Langfuse links to that prompt — the client never
+     * records a second observation of its own.
+     */
+    buildTraceContext(resolved, callContext) {
+        const metadata = {
+            promptVersion: resolved.version,
+            isFallback: resolved.isFallback,
+        };
+        const userId = callContext?.userId;
+        if (userId !== undefined && userId !== null) {
+            metadata.userId = userId;
+        }
+        return {
+            prompt: {
+                name: resolved.name,
+                version: resolved.version,
+                isFallback: resolved.isFallback,
+            },
+            metadata,
+        };
+    }
+    assertOverridesAllowed(promptName, overrides) {
+        if (this.mode === 'experiment' || !overrides) {
+            return;
+        }
+        const hasOverride = Object.values(overrides).some((value) => value !== undefined);
+        if (hasOverride) {
+            throw new errors_1.LLMConfigError(`per-call overrides are rejected by a production-mode client for "${promptName}"`, { promptName });
+        }
+    }
+    serializeCallContext(callContext) {
+        if (!callContext) {
+            return {};
+        }
+        return Object.fromEntries(Object.entries(callContext).filter((entry) => (entry[1] !== undefined && entry[1] !== null)));
+    }
+    extractStatus(error) {
+        if (error
+            && typeof error === 'object'
+            && 'status' in error
+            && typeof error.status === 'number') {
+            return error.status;
+        }
+        return null;
+    }
+    isRetryableStatus(status) {
+        if (status === null) {
+            return true;
+        }
+        return status === 429 || status >= 500;
+    }
+}
+exports.LLMClientEngine = LLMClientEngine;
+//# sourceMappingURL=LLMClientEngine.js.map

package/dist/client/LLMClientEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMClientEngine.js","sourceRoot":"","sources":["../../src/client/LLMClientEngine.ts"],"names":[],"mappings":";;;AAAA,+DAO+B;AAa/B,gDAAsE;AACtE,sDAK8B;AAC9B,0DAAwE;AACxE,gEAA6D;AAC7D,8DAAoE;AAmBpE,4CAKyB;AAEzB;;;;;GAKG;AACH,MAAa,eAAe;IAET,OAAO,CAAa;IAEpB,QAAQ,CAAW;IAEnB,OAAO,CAAwB;IAE/B,WAAW,CAAyB;IAEpC,QAAQ,CAAwC;IAEhD,MAAM,CAAiC;IAEvC,aAAa,CAAqC;IAElD,IAAI,CAAgB;IAEpB,oBAAoB,CAAsC;IAE1D,WAAW,CAAiB;IAE7C,YAAY,MAAuC;QACjD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACxB,IAAI,CAAC,oBAAoB,GAAG,MAAM,CAAC,mBAAmB,CAAC;QACvD,IAAI,CAAC,WAAW,GAAG,IAAI,4BAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,MAAW,EACX,OAAqE;QAErE,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;QAEhD,IAAI,CAAC,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAE3D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CACvC,UAAU,EACV,OAAO,EACP,OAAO,CAAC,SAAS,EACjB;YACE,OAAO,EAAE,iCAAW,CAAC,UAAU;YAC/B,SAAS,EAAE,OAAO,CAAC,SAAS;SAC7B,CACF,CAAC;QAEF,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAED,WAAW,CACT,UAA6E;QAE7E,OAAO,IAAI,mBAAQ,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,QAAQ,CACZ,aAAuE,EACvE,OAIC;QAED,MAAM,KAAK,GAAG,aAAa,YAAY,mBAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5E,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAQ,CAAC;QAChE,MAAM,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAEzC,IAAI,CAAC,sBAAsB,CAAC,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAE3D,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;YAC3C,SAAS,EAAE,KAAK,EAAE,IAAI,IAAI,UAAU;YACpC,UAAU;YACV,OAAO;YACP,SAAS,EAAE,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE;YACxD,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK;YAC1C,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CACxB;YAC/B,iBAAiB,EAAE,KAAK;gBACtB,CAAC,CAAC,KAAK,CAAC,iBAAiB;gBACzB,CAAC,CAAC,OAAO,CAAC,iBAAiB;YAC7B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;QAEH,OAAO,SAAgE,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,WAAW,CACf,MAAW,EACX,OAAqF;QAErF,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,CACvC,UAAU,EACV,OAAO,EACP,OAAO,CAAC,SAAS,EACjB,EAAE,OAAO,EAAE,iCAAW,CAAC,UAAU,EAAE,CACpC,CAAC;QAEF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAEtE,OAAO,OAAO,CAAC,WAAW,CACxB,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,EACvC,QAAQ,CAAC,KAAK,CACf,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,cAAc,CAClB,MAAW;QAEX,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEtC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;YAC3C,IAAI,EAAE,UAAU;YAChB,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;YAC/C,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;YAChC,OAAO,EAAE,iCAAW,CAAC,UAAU;SAChC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,uBAAc,CACtB,2CAA2C,UAAU,cAAc;kBACjE,yBAAyB,EAC3B,EAAE,UAAU,EAAE,CACf,CAAC;QACJ,CAAC;QAED,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,aAAa,EAAE,QAAQ,CAAC,aAAa;YACrC,UAAU,EAAE,QAAQ,CAAC,UAAU;SAChC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,UAAkB,EAClB,OAAyB,EACzB,SAA2C,EAC3C,IAA6B;QAE7B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAC1C,IAAI,EAAE,UAAU;YAChB,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;YAC/C,SAAS,EAAE,IAAA,0CAAwB,EAAC,SAAS,CAAC;YAC9C,QAAQ,EAAE;gBACR,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;gBAC3B,GAAG,CAAC,IAAI,CAAC,kBAAkB,IAAI,EAAE,CAAC;aACnC;YACD,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,eAAe,EAAE,IAAI,CAAC,SAAS,EAAE,aAAa;YAC9C,aAAa,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW;SAC3C,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,uBAAc,CACtB,yCAAyC,UAAU,gCAAgC,EACnF,EAAE,UAAU,EAAE,CACf,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,OAA6B;QAC/C,MAAM,OAAO,GAAG,IAAA,mCAAgB,EAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAEjD,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC;YAC/B,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,OAAO,IAAA,mCAAgB,EACrB,IAAI,CAAC,oBAAoB,CAAC,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAC3D,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,aAAa,CACzB,QAAwB,EACxB,MAAsC,EACtC,OAAiF;QAEjF,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACtE,MAAM,eAAe,GAAG,IAAI,CAAC,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAC7E,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAEvE,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,YAAY,CACxC,GAAG,EAAE,CAAC,CAAC,MAAM;YACX,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;gBACpB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,YAAY,EAAE,QAAQ,CAAC,YAAY;gBACnC,MAAM;gBACN,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,eAAe;gBACf,YAAY;aACb,CAAC;YACF,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;gBACpB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,YAAY,EAAE,QAAQ,CAAC,YAAY;gBACnC,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,eAAe;gBACf,YAAY;aACb,CAAC,CAAC,EACL,QAAQ,EACR,OAAO,CAAC,WAAW,CACpB,CAAC;QAEF,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IACzD,CAAC;IAED;;;;;;OAMG;IACK,oBAAoB,CAC1B,QAAwB,EACxB,WAA0C;QAM1C,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC7B,OAAO;gBACL,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAC7C,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC;gBACvC,YAAY,EAAE,SAAS;aACxB,CAAC;QACJ,CAAC;QAED,MAAM,aAAa,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAC1C,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,CACvC,CAAC;QACF,MAAM,YAAY,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAC3C,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,CACvC,CAAC;QACF,MAAM,aAAa,GAAG,IAAI,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;QAC3D,MAAM,aAAa,GAAG,YAAY;aAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,aAAa,CAAC;aAC7C,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7E,MAAM,WAAW,GAAG,aAAa,IAAI,CAAC;YACpC,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,OAAO;YACrC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAElB,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC;YAC3C,OAAO,EAAE,CAAC,GAAG,aAAa,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YAC9D,YAAY,EAAE,aAAa,EAAE,OAAO;SACrC,CAAC;IACJ,CAAC;IAEO,iBAAiB,CAAC,QAA4B;QACpD,KAAK,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YAC7D,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBACpC,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;IAEO,KAAK,CAAC,YAAY,CACxB,IAA4B,EAC5B,QAAwB,EACxB,WAAyB;QAEzB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;YAE5B,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;gBAC9D,MAAO,MAA6B,CAAC,KAAK,CAAC;YAC7C,CAAC;YAED,OAAO,MAAgE,CAAC;QAC1E,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,YAAY,CACV,QAAwB,EACxB,MAAsC,EACtC,UAAkE;QAElE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC;QAC/B,CAAC;QAED,IAAI,UAAU,CAAC,UAAU,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC3D,MAAM,IAAI,iCAAwB,CAChC,0BAA0B,QAAQ,CAAC,IAAI,4BAA4B,EACnE;gBACE,UAAU,EAAE,QAAQ,CAAC,IAAI;gBACzB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ;gBAClC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK;gBAC5B,OAAO,EAAE,UAAU,CAAC,IAAI,IAAI,EAAE;gBAC9B,YAAY,EAAE,UAAU,CAAC,UAAU,IAAI,kBAAkB;aAC1D,CACF,CAAC;QACJ,CAAC;QAED,OAAO,UAAU,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,eAAe,CACb,KAAc,EACd,QAAwB,EACxB,WAAyB;QAEzB,MAAM,OAAO,GAAG;YACd,UAAU,EAAE,QAAQ,CAAC,IAAI;YACzB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ;YAClC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK;YAC5B,KAAK,EAAE,KAAK;SACb,CAAC;QAEF,IAAI,WAAW,EAAE,OAAO,EAAE,CAAC;YACzB,OAAO,IAAI,wBAAe,CAAC,kBAAkB,EAAE,OAAO,CAAC,CAAC;QAC1D,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAEzC,OAAO,IAAI,yBAAgB,CACzB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EACtD,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAClE,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,sBAAsB,CAC1B,QAAwB,EACxB,UAAkB;QAElB,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,sBAAsB,CACvD,QAAQ,EACR,UAAU,CACX,CAAC;QAEF,OAAO,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC;YACvC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ;YAClC,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC,CAAC;IACL,CAAC;IAED,UAAU,CAAC,UAAkB;QAC3B,OAAQ,IAAI,CAAC,QAA8B,CAAC,UAAU,CAAC,CAAC;IAC1D,CAAC;IAEO,KAAK,CAAC,sBAAsB,CAClC,QAAwB,EACxB,UAAkB;QAElB,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC,sBAAsB,CACvD,QAAQ,EACR,UAAU,CACX,CAAC;QAEF,OAAO,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC;YACvC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ;YAClC,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,sBAAsB,CAClC,QAAwB,EACxB,UAAkB;QAElB,OAAO,IAAI,CAAC,WAAW,CAAC;YACtB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ;YAClC,UAAU;YACV,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,OAAO;SACpC,CAAC,CAAC;IACL,CAAC;IAEO,gBAAgB,CAAC,IAAY;QACnC,OAAO,IAAI,CAAC,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC;IAEO,YAAY,CAClB,OAAsC;QAEtC,OAAO,IAAA,8CAA8B,EAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IAEO,mBAAmB,CACzB,IAAY,EACZ,IAAY;QAEZ,OAAO;YACL,IAAI,EAAE,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,8BAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,8BAAQ,CAAC,IAAI;YAC/D,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,2CAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;SACtD,CAAC;IACJ,CAAC;IAED,oBAAoB,CAClB,QAAwB,EACxB,WAA6C;QAE7C,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO;YACL,GAAG,IAAI,CAAC,aAAa;YACrB,GAAG,IAAI,CAAC,oBAAoB,CAAC,WAAW,CAAC;YACzC,UAAU,EAAE,QAAQ,CAAC,IAAI;YACzB,aAAa,EAAE,QAAQ,CAAC,OAAO;SAChC,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,iBAAiB,CACf,QAAwB,EACxB,WAA6C;QAE7C,MAAM,QAAQ,GAA8C;YAC1D,aAAa,EAAE,QAAQ,CAAC,OAAO;YAC/B,UAAU,EAAE,QAAQ,CAAC,UAAU;SAChC,CAAC;QAEF,MAAM,MAAM,GAAG,WAAW,EAAE,MAAM,CAAC;QAEnC,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAC5C,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC;QAC3B,CAAC;QAED,OAAO;YACL,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,OAAO,EAAE,QAAQ,CAAC,OAAO;gBACzB,UAAU,EAAE,QAAQ,CAAC,UAAU;aAChC;YACD,QAAQ;SACT,CAAC;IACJ,CAAC;IAEO,sBAAsB,CAC5B,UAAkB,EAClB,SAAuC;QAEvC,IAAI,IAAI,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7C,OAAO;QACT,CAAC;QAED,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAC/C,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAC/B,CAAC;QAEF,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,IAAI,uBAAc,CACtB,oEAAoE,UAAU,GAAG,EACjF,EAAE,UAAU,EAAE,CACf,CAAC;QACJ,CAAC;IACH,CAAC;IAEO,oBAAoB,CAC1B,WAA6C;QAE7C,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,MAAM,CAChC,CAAC,KAAK,EAAgD,EAAE,CAAC,CACvD,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,CAC5C,CACF,CACF,CAAC;IACJ,CAAC;IAEO,aAAa,CAAC,KAAc;QAClC,IACE,KAAK;eACF,OAAO,KAAK,KAAK,QAAQ;eACzB,QAAQ,IAAI,KAAK;eACjB,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EACnC,CAAC;YACD,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,iBAAiB,CAAC,MAAqB;QAC7C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,MAAM,KAAK,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC;IACzC,CAAC;CACF;AAlhBD,0CAkhBC"}

package/dist/client/agentRun.typedefs.d.ts

@@ -1,7 +1,7 @@
 import { type LLMToolDefinition, type LLMToolResult, type LLMTerminalToolOutcome, type LLMToolLoopStopReasons } from '../LLMService.typedefs';
 import { type LLMPromptRegistry } from '../client/defineLLMPrompts';
 import { type LLMVariableValue } from '../client/promptSnapshot.typedefs';
-import { type LLMCallOverrides, type LLMClientCallContext, type LLMPlainMessage } from '../client/createLLMClient.typedefs';
+import { type LLMCallOverrides, type LLMClientCallContext, type LLMPlainMessage } from '../client/llmClient.typedefs';
 import { type LLMAgentSubagent } from '../client/LLMAgent';
 /**
  * Structured progress events an agent run emits while it works. They exist for
@@ -18,6 +18,7 @@ export declare enum LLMAgentEventTypes {
     ToolCallStarted = "tool_call_started",
     ToolCallCompleted = "tool_call_completed",
     ToolCallFailed = "tool_call_failed",
+    ToolCallDenied = "tool_call_denied",
     SubagentStarted = "subagent_started",
     SubagentCompleted = "subagent_completed",
     SubagentFailed = "subagent_failed"
@@ -88,13 +89,27 @@ export interface LLMAgentToolCallFailedEvent extends LLMAgentInvocationEventBase
     error: string;
     durationMs: number;
 }
+/**
+ * A call the model made that never ran: the tool's `canExecute` precondition
+ * refused it. It replaces the `tool_call_completed` of that invocation (the
+ * `tool_call_started` before it shares the `invocationId`), and the run
+ * continues — the `reason` goes back to the model as the call's result. A
+ * refused delegation reports here too, with `tool` naming the subagent; the
+ * `subagent_started` that precedes it has no nested run because the subagent
+ * never started.
+ */
+export interface LLMAgentToolCallDeniedEvent extends LLMAgentInvocationEventBase {
+    type: LLMAgentEventTypes.ToolCallDenied;
+    tool: string;
+    reason: string;
+}
 export interface LLMAgentSubagentStartedEvent extends LLMAgentSubagentEventBase {
     type: LLMAgentEventTypes.SubagentStarted;
     input: string;
 }
 export interface LLMAgentSubagentCompletedEvent extends LLMAgentSubagentEventBase {
     type: LLMAgentEventTypes.SubagentCompleted;
-    output: string;
+    output: LLMToolResult;
     durationMs: number;
 }
 export interface LLMAgentSubagentFailedEvent extends LLMAgentSubagentEventBase {
@@ -102,7 +117,7 @@ export interface LLMAgentSubagentFailedEvent extends LLMAgentSubagentEventBase {
     error: string;
     durationMs: number;
 }
-export type LLMAgentEvent = LLMAgentStartedEvent | LLMAgentMessageEvent | LLMAgentCompletedEvent | LLMAgentFailedEvent | LLMAgentToolCallStartedEvent | LLMAgentToolCallCompletedEvent | LLMAgentToolCallFailedEvent | LLMAgentSubagentStartedEvent | LLMAgentSubagentCompletedEvent | LLMAgentSubagentFailedEvent;
+export type LLMAgentEvent = LLMAgentStartedEvent | LLMAgentMessageEvent | LLMAgentCompletedEvent | LLMAgentFailedEvent | LLMAgentToolCallStartedEvent | LLMAgentToolCallCompletedEvent | LLMAgentToolCallFailedEvent | LLMAgentToolCallDeniedEvent | LLMAgentSubagentStartedEvent | LLMAgentSubagentCompletedEvent | LLMAgentSubagentFailedEvent;
 /**
  * May be async: a returned promise's rejection is caught and logged, so a
  * failing listener (WS publish, DB persist) never affects the agent run.

package/dist/client/agentRun.typedefs.js

@@ -17,6 +17,7 @@ var LLMAgentEventTypes;
     LLMAgentEventTypes["ToolCallStarted"] = "tool_call_started";
     LLMAgentEventTypes["ToolCallCompleted"] = "tool_call_completed";
     LLMAgentEventTypes["ToolCallFailed"] = "tool_call_failed";
+    LLMAgentEventTypes["ToolCallDenied"] = "tool_call_denied";
     LLMAgentEventTypes["SubagentStarted"] = "subagent_started";
     LLMAgentEventTypes["SubagentCompleted"] = "subagent_completed";
     LLMAgentEventTypes["SubagentFailed"] = "subagent_failed";

package/dist/client/agentRun.typedefs.js.map

@@ -1 +1 @@
-{"version":3,"file":"agentRun.typedefs.js","sourceRoot":"","sources":["../../src/client/agentRun.typedefs.ts"],"names":[],"mappings":";;;AAeA;;;;;;GAMG;AACH,IAAY,kBAWX;AAXD,WAAY,kBAAkB;IAC5B,oDAA8B,CAAA;IAC9B,oDAA8B,CAAA;IAC9B,wDAAkC,CAAA;IAClC,kDAA4B,CAAA;IAC5B,2DAAqC,CAAA;IACrC,+DAAyC,CAAA;IACzC,yDAAmC,CAAA;IACnC,0DAAoC,CAAA;IACpC,8DAAwC,CAAA;IACxC,wDAAkC,CAAA;AACpC,CAAC,EAXW,kBAAkB,kCAAlB,kBAAkB,QAW7B"}
+{"version":3,"file":"agentRun.typedefs.js","sourceRoot":"","sources":["../../src/client/agentRun.typedefs.ts"],"names":[],"mappings":";;;AAeA;;;;;;GAMG;AACH,IAAY,kBAYX;AAZD,WAAY,kBAAkB;IAC5B,oDAA8B,CAAA;IAC9B,oDAA8B,CAAA;IAC9B,wDAAkC,CAAA;IAClC,kDAA4B,CAAA;IAC5B,2DAAqC,CAAA;IACrC,+DAAyC,CAAA;IACzC,yDAAmC,CAAA;IACnC,yDAAmC,CAAA;IACnC,0DAAoC,CAAA;IACpC,8DAAwC,CAAA;IACxC,wDAAkC,CAAA;AACpC,CAAC,EAZW,kBAAkB,kCAAlB,kBAAkB,QAY7B"}

package/dist/client/agentRunner.d.ts

@@ -1,4 +1,4 @@
-import { LLMPurposes, LLMToolLoopStopReasons, type LLMCallTraceContext, type LLMProviders, type LLMTerminalToolOutcome, type LLMToolDefinition } from '../LLMService.typedefs';
+import { LLMPurposes, LLMToolLoopStopReasons, type LLMCallTraceContext, type LLMProviders, type LLMTerminalToolOutcome, type LLMToolDefinition, type LLMToolResult } from '../LLMService.typedefs';
 import { type LLMAssistanceService } from '../services';
 import { type LLMLoggerInterface } from '../utilities/logger';
 import { type LLMReporterInterface } from '../utilities/reporter';
@@ -6,7 +6,7 @@ import { type LLMSchemaInterface } from '../utilities/schema';
 import { type LLMCapabilityRequirement, type LLMPromptBinding } from '../client/defineLLMPrompts';
 import { type LLMVariableValue } from '../client/promptSnapshot.typedefs';
 import { type ResolvedPrompt } from '../client/promptRegistry.runtime';
-import { type LLMCallOverrides, type LLMClientCallContext, type LLMPlainMessage } from '../client/createLLMClient.typedefs';
+import { type LLMCallOverrides, type LLMClientCallContext, type LLMDelegationGate, type LLMPlainMessage, type LLMToolResultContext } from '../client/llmClient.typedefs';
 import { LLMAgent } from '../client/LLMAgent';
 import { type LLMAgentEventListener, type LLMAgentRunResult } from '../client/agentRun.typedefs';
 type AgentAssistanceService = LLMAssistanceService<LLMProviders, LLMReporterInterface<any> | undefined>;
@@ -39,6 +39,7 @@ export interface LLMAgentCallServices {
     toTaxonomyError(error: unknown, resolved: ResolvedPrompt, abortSignal?: AbortSignal): Error;
     unwrapResult(resolved: ResolvedPrompt, schema: LLMSchemaInterface | undefined, sendResult: AgentSendResult): unknown;
     getBinding(promptName: string): LLMPromptBinding | undefined;
+    normalizeToolResult(context: LLMToolResultContext): LLMToolResult;
 }
 /**
  * A plain-object subagent with the registry generics erased: the engine
@@ -49,8 +50,10 @@ export interface LLMAgentSubagentSpec {
     prompt: string;
     name: string;
     description: string;
-    variables: Record<string, LLMVariableValue>;
+    variables?: Record<string, LLMVariableValue>;
     tools?: LLMToolDefinition[];
+    inputSchema?: LLMSchemaInterface;
+    canExecute?: LLMDelegationGate;
     maxToolIterations?: number;
 }
 type SubagentEntry = LLMAgentSubagentSpec | LLMAgent;
@@ -95,7 +98,39 @@ export declare class LLMAgentRunner {
     private assistInChat;
     private buildTools;
     private wrapToolWithEvents;
+    /**
+     * The lifecycle of one tool invocation. The completion event depends on what
+     * the invocation produced: a refused call reports `tool_call_denied` in place
+     * of `tool_call_completed`, so a listener never records a side effect that
+     * did not happen.
+     */
+    private buildToolCallLifecycle;
+    private executeGatedTool;
+    private resolveToolGate;
+    /**
+     * What a refused call hands back to the model. It names the tool and the
+     * reason so the model can adapt instead of retrying the same call, and it
+     * never passes through the client's normalizer — a denial is the package's
+     * own control flow, not a tool's output.
+     */
+    private buildDenial;
     private buildSubagentTool;
+    private buildDelegationLifecycle;
+    private delegateToSubagent;
+    /**
+     * A typed delegation hands the whole argument object to the subagent as its
+     * request, since the parent model filled a schema rather than writing a
+     * task sentence. Without a schema the single `prompt` argument is the
+     * request, exactly as before.
+     */
+    private buildDelegationInput;
+    /**
+     * Typed delegation arguments join the subagent's own variables (and win over
+     * them), so the delegated Langfuse prompt can reference what the parent model
+     * supplied as `{{argument}}` and the validation gate covers it like any other
+     * variable.
+     */
+    private buildDelegationVariables;
     /**
      * Flattens a nested run back into the string its delegation tool returns to
      * the parent model. A delegation tool is never itself terminal, so a