@mate-academy/llm-gateway 8.8.2 → 8.8.3

package/dist/client/agentRunner.d.ts

@@ -0,0 +1,161 @@
+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';
+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 LLMDelegationGate, type LLMPlainMessage, type LLMProviderServiceScope, type LLMToolResultContext, type LLMTraceContextScope } 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>;
+type AgentSendResult = {
+    text: string;
+    data?: unknown;
+    parseError?: string;
+    stopReason?: LLMToolLoopStopReasons;
+    terminalTool?: LLMTerminalToolOutcome;
+};
+/**
+ * How one prompt resolution should run: the model-map purpose, extra
+ * capability requirements beyond the binding's own, and per-call overrides.
+ */
+export interface LLMPromptResolutionCall {
+    purpose: LLMPurposes;
+    additionalRequires?: LLMCapabilityRequirement[];
+    overrides?: LLMCallOverrides;
+}
+/**
+ * The prompt-resolution and call-plumbing surface the agent runner borrows from
+ * the client engine, so both `generate` and `runAgent` share one gate, one
+ * credentials path, one context shape, and one error taxonomy.
+ */
+export interface LLMAgentCallServices {
+    resolvePrompt(promptName: string, binding: LLMPromptBinding, variables: Record<string, LLMVariableValue>, call: LLMPromptResolutionCall): Promise<ResolvedPrompt>;
+    buildAssistanceService(scope: LLMProviderServiceScope): Promise<AgentAssistanceService>;
+    buildReporterContext(resolved: ResolvedPrompt, callContext: LLMClientCallContext | undefined): unknown;
+    buildTraceContext(scope: LLMTraceContextScope): LLMCallTraceContext;
+    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;
+    withAgentObservation<Result>(name: string, input: unknown, fn: () => Promise<Result>): Promise<Result>;
+}
+/**
+ * A plain-object subagent with the registry generics erased: the engine
+ * narrows the typed definition at the `runAgent` boundary, the runner only
+ * needs the runtime shape.
+ */
+export interface LLMAgentSubagentSpec {
+    prompt: string;
+    name: string;
+    description: string;
+    variables?: Record<string, LLMVariableValue>;
+    tools?: LLMToolDefinition[];
+    inputSchema?: LLMSchemaInterface;
+    canExecute?: LLMDelegationGate;
+    maxToolIterations?: number;
+}
+type SubagentEntry = LLMAgentSubagentSpec | LLMAgent;
+export interface LLMAgentRunInput {
+    agentName: string;
+    promptName: string;
+    binding: LLMPromptBinding;
+    variables: Record<string, LLMVariableValue>;
+    input: string;
+    history?: LLMPlainMessage[];
+    tools?: LLMToolDefinition[];
+    subagents?: SubagentEntry[];
+    maxToolIterations?: number;
+    context?: LLMClientCallContext;
+    /**
+     * The Langfuse session every generation of this run belongs to. Copied onto
+     * delegated subagent runs, so one anchor covers the whole run tree.
+     */
+    sessionId?: string;
+    traceTags?: string[];
+    abortSignal?: AbortSignal;
+    overrides?: LLMCallOverrides;
+    onEvent?: LLMAgentEventListener;
+}
+/**
+ * Runs one agent: instructions resolved from the prompt registry (Langfuse is
+ * the source of the instructions text and the model routing), the provider
+ * assistance tool loop does the model⇄tool rounds, subagents join as tools,
+ * and every step emits an `LLMAgentEvent` for live progress and persistence.
+ * Langfuse observability needs no extra wiring here — the provider services
+ * already record generation and tool observations under the active trace.
+ */
+export declare class LLMAgentRunner {
+    private readonly services;
+    private readonly logger;
+    constructor(services: LLMAgentCallServices, logger: LLMLoggerInterface | undefined);
+    run(run: LLMAgentRunInput): Promise<LLMAgentRunResult<unknown>>;
+    private runAgentTree;
+    /**
+     * A terminal tool ends the turn without a model answer, so the bound schema
+     * is deliberately not applied — there is nothing to validate, and unwrapping
+     * would fail a legitimate outcome. Any other stop carries the model's answer
+     * and unwraps exactly like `generate`.
+     */
+    private buildRunResult;
+    private executeRun;
+    private runInChat;
+    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
+     * subagent that stopped on its own terminal tool hands that tool's output
+     * back as the delegation result and the parent's loop continues.
+     */
+    private stringifySubagentOutcome;
+    private normalizeSubagent;
+    private withLifecycleEvents;
+    /**
+     * Emit an `agent_message` for visible assistant text the model produced
+     * between tool rounds. Attributed to the emitting run via `agent`/`runId`,
+     * so a subagent's narration carries the subagent's identity. Empty or
+     * whitespace-only text is skipped — an `agent_message` always carries real
+     * narration.
+     */
+    private emitAgentMessage;
+    private emit;
+    private warnListenerFailure;
+}
+export {};

package/dist/client/agentRunner.js

@@ -0,0 +1,517 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMAgentRunner = void 0;
+const LLMService_typedefs_1 = require("../LLMService.typedefs");
+const serializeError_1 = require("../utilities/serializeError");
+const schema_1 = require("../utilities/schema");
+const tools_1 = require("../utilities/tools");
+const plainMessages_1 = require("../client/plainMessages");
+const promptVariables_1 = require("../client/promptVariables");
+const LLMAgent_1 = require("../client/LLMAgent");
+const agentRun_typedefs_1 = require("../client/agentRun.typedefs");
+const errors_1 = require("../client/errors");
+const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+/**
+ * The delegation-tool parameters a subagent gets when it declares no
+ * `inputSchema`: one free-form task string, which also becomes the nested
+ * run's input.
+ */
+const DELEGATION_PROMPT_SCHEMA = schema_1.LLMSchema.object({
+    prompt: schema_1.LLMSchema.string().describe('The task or question to delegate to this agent'),
+});
+/**
+ * Allocates the `runId`/`invocationId` values that correlate events within one
+ * root run. One sequence spans the whole run tree so every id is unique across
+ * the root agent, its subagents, and all tool invocations.
+ */
+class AgentRunIdSequence {
+    currentId = 0;
+    next() {
+        this.currentId += 1;
+        return this.currentId;
+    }
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Runs one agent: instructions resolved from the prompt registry (Langfuse is
+ * the source of the instructions text and the model routing), the provider
+ * assistance tool loop does the model⇄tool rounds, subagents join as tools,
+ * and every step emits an `LLMAgentEvent` for live progress and persistence.
+ * Langfuse observability needs no extra wiring here — the provider services
+ * already record generation and tool observations under the active trace.
+ */
+class LLMAgentRunner {
+    services;
+    logger;
+    constructor(services, logger) {
+        this.services = services;
+        this.logger = logger?.child('LLMAgentRunner');
+    }
+    async run(run) {
+        const sequence = new AgentRunIdSequence();
+        return this.runAgentTree(run, sequence, sequence.next());
+    }
+    async runAgentTree(run, sequence, runId) {
+        return this.services.withAgentObservation(run.agentName, run.input, async () => {
+            const completedRun = await this.withLifecycleEvents(run.onEvent, {
+                started: {
+                    type: agentRun_typedefs_1.LLMAgentEventTypes.AgentStarted,
+                    agent: run.agentName,
+                    runId,
+                    input: run.input,
+                },
+                completed: (workResult, durationMs) => ({
+                    type: agentRun_typedefs_1.LLMAgentEventTypes.AgentCompleted,
+                    agent: run.agentName,
+                    runId,
+                    output: workResult.text,
+                    durationMs,
+                }),
+                failed: (errorMessage, durationMs) => ({
+                    type: agentRun_typedefs_1.LLMAgentEventTypes.AgentFailed,
+                    agent: run.agentName,
+                    runId,
+                    error: errorMessage,
+                    durationMs,
+                }),
+            }, async () => {
+                const { resolved, sendResult } = await this.executeRun(run, sequence, runId);
+                return {
+                    text: sendResult.text,
+                    result: this.buildRunResult(run, resolved, sendResult),
+                };
+            });
+            return completedRun.result;
+        });
+    }
+    /**
+     * A terminal tool ends the turn without a model answer, so the bound schema
+     * is deliberately not applied — there is nothing to validate, and unwrapping
+     * would fail a legitimate outcome. Any other stop carries the model's answer
+     * and unwraps exactly like `generate`.
+     */
+    buildRunResult(run, resolved, sendResult) {
+        if (sendResult.terminalTool) {
+            return {
+                stopReason: LLMService_typedefs_1.LLMToolLoopStopReasons.TerminalTool,
+                terminalTool: sendResult.terminalTool,
+                text: sendResult.text,
+            };
+        }
+        return {
+            stopReason: sendResult.stopReason === LLMService_typedefs_1.LLMToolLoopStopReasons.MaxIterations
+                ? LLMService_typedefs_1.LLMToolLoopStopReasons.MaxIterations
+                : LLMService_typedefs_1.LLMToolLoopStopReasons.Completed,
+            output: this.services.unwrapResult(resolved, run.binding.schema, sendResult),
+            text: sendResult.text,
+        };
+    }
+    async executeRun(run, sequence, runId) {
+        const tools = this.buildTools(run, sequence, runId);
+        const resolved = await this.services.resolvePrompt(run.promptName, run.binding, run.variables, {
+            purpose: LLMService_typedefs_1.LLMPurposes.Assistance,
+            additionalRequires: tools.length > 0 ? ['tools'] : [],
+            overrides: run.overrides,
+        });
+        const service = await this.services.buildAssistanceService({
+            resolved,
+            callContext: run.context,
+        });
+        const sendResult = await this.runInChat(service, resolved, run, tools, runId);
+        return { resolved, sendResult };
+    }
+    async runInChat(service, resolved, run, tools, runId) {
+        const reporterContext = this.services.buildReporterContext(resolved, run.context);
+        const traceContext = this.services.buildTraceContext({
+            resolved,
+            callContext: run.context,
+            sessionId: run.sessionId,
+            traceTags: run.traceTags,
+        });
+        const chatOptions = {
+            model: resolved.model,
+            instructions: resolved.text,
+            history: run.history?.length
+                ? (0, plainMessages_1.plainMessagesToContentMessages)(run.history)
+                : undefined,
+            abortSignal: run.abortSignal,
+            reporterContext,
+            traceContext,
+        };
+        const chatResult = await service.createChat(chatOptions);
+        if ('error' in chatResult) {
+            throw this.services.toTaxonomyError(chatResult.error, resolved, run.abortSignal);
+        }
+        try {
+            return await this.assistInChat(service, resolved, run, {
+                chatId: chatResult.chatId,
+                tools,
+                reporterContext,
+                traceContext,
+                runId,
+            });
+        }
+        finally {
+            await service.deleteChat(chatResult.chatId).catch((deleteError) => {
+                this.logger?.warn('Failed to delete agent chat', {
+                    agent: run.agentName,
+                    chatId: chatResult.chatId,
+                    error: (0, serializeError_1.serializeError)(deleteError),
+                });
+            });
+        }
+    }
+    async assistInChat(service, resolved, run, session) {
+        const assistOptions = {
+            chatId: session.chatId,
+            model: resolved.model,
+            message: {
+                role: LLMService_typedefs_1.LLMRoles.User,
+                content: [{
+                        type: LLMService_typedefs_1.LLMMessageContentType.TEXT,
+                        text: run.input,
+                    }],
+            },
+            ...(session.tools.length > 0 && { tools: session.tools }),
+            ...(run.maxToolIterations !== undefined && {
+                maxToolIterations: run.maxToolIterations,
+            }),
+            ...(run.binding.schema && { schema: run.binding.schema }),
+            abortSignal: run.abortSignal,
+            reporterContext: session.reporterContext,
+            traceContext: session.traceContext,
+            onAssistantNarration: run.onEvent
+                ? (text) => {
+                    this.emitAgentMessage(run, session.runId, text);
+                }
+                : undefined,
+        };
+        try {
+            const sendResult = await service.assistInChat(assistOptions);
+            if ('error' in sendResult) {
+                throw sendResult.error;
+            }
+            return sendResult;
+        }
+        catch (error) {
+            throw this.services.toTaxonomyError(error, resolved, run.abortSignal);
+        }
+    }
+    buildTools(run, sequence, runId) {
+        const explicitTools = (run.tools ?? []).map((tool) => this.wrapToolWithEvents(tool, run, sequence, runId));
+        const subagentTools = (run.subagents ?? []).map((subagent) => this.buildSubagentTool(subagent, run, sequence, runId));
+        return [...explicitTools, ...subagentTools];
+    }
+    wrapToolWithEvents(tool, run, sequence, runId) {
+        return {
+            ...tool,
+            execute: async (toolInput) => {
+                const invocationId = sequence.next();
+                const outcome = await this.withLifecycleEvents(run.onEvent, this.buildToolCallLifecycle({
+                    toolName: tool.name,
+                    input: toolInput,
+                    run,
+                    runId,
+                    invocationId,
+                }), async () => this.executeGatedTool({
+                    tool,
+                    args: toolInput,
+                    agentName: run.agentName,
+                }));
+                return outcome.result;
+            },
+        };
+    }
+    /**
+     * 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.
+     */
+    buildToolCallLifecycle(invocation) {
+        const correlation = {
+            agent: invocation.run.agentName,
+            runId: invocation.runId,
+            tool: invocation.toolName,
+            invocationId: invocation.invocationId,
+        };
+        return {
+            started: {
+                type: agentRun_typedefs_1.LLMAgentEventTypes.ToolCallStarted,
+                ...correlation,
+                input: invocation.input,
+            },
+            completed: (outcome, durationMs) => (outcome.denialReason === undefined
+                ? {
+                    type: agentRun_typedefs_1.LLMAgentEventTypes.ToolCallCompleted,
+                    ...correlation,
+                    output: outcome.result,
+                    durationMs,
+                }
+                : {
+                    type: agentRun_typedefs_1.LLMAgentEventTypes.ToolCallDenied,
+                    ...correlation,
+                    reason: outcome.denialReason,
+                }),
+            failed: (errorMessage, durationMs) => ({
+                type: agentRun_typedefs_1.LLMAgentEventTypes.ToolCallFailed,
+                ...correlation,
+                error: errorMessage,
+                durationMs,
+            }),
+        };
+    }
+    async executeGatedTool(execution) {
+        const gate = await this.resolveToolGate(execution.tool.canExecute, execution.args);
+        if (!gate.allowed) {
+            return this.buildDenial(execution.tool.name, gate.reason);
+        }
+        const rawResult = await execution.tool.execute(execution.args);
+        return {
+            result: this.services.normalizeToolResult({
+                tool: execution.tool.name,
+                agent: execution.agentName,
+                input: execution.args,
+                result: rawResult,
+            }),
+        };
+    }
+    async resolveToolGate(gate, args) {
+        if (!gate) {
+            return { allowed: true };
+        }
+        return gate(args);
+    }
+    /**
+     * 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.
+     */
+    buildDenial(toolName, reason) {
+        return {
+            result: `The "${toolName}" call was not executed. Reason: ${reason}`,
+            denialReason: reason,
+        };
+    }
+    buildSubagentTool(subagentEntry, run, sequence, runId) {
+        const subagent = this.normalizeSubagent(subagentEntry);
+        const binding = this.services.getBinding(subagent.prompt);
+        if (!binding) {
+            throw new errors_1.LLMConfigError(`subagent "${subagent.name}" references prompt "${subagent.prompt}"`
+                + ' that is not in the registry', { promptName: subagent.prompt });
+        }
+        if (!TOOL_NAME_PATTERN.test(subagent.name)) {
+            throw new errors_1.LLMConfigError(`subagent name "${subagent.name}" cannot be used as a tool name:`
+                + ' it must match [a-zA-Z0-9_-]+', { promptName: subagent.prompt });
+        }
+        return tools_1.LLMTool.create({
+            name: subagent.name,
+            description: subagent.description,
+            parameters: subagent.inputSchema ?? DELEGATION_PROMPT_SCHEMA,
+            execute: async (args) => {
+                const invocationId = sequence.next();
+                const subagentRunId = sequence.next();
+                const input = this.buildDelegationInput(subagent, args);
+                const outcome = await this.withLifecycleEvents(run.onEvent, this.buildDelegationLifecycle({
+                    subagentName: subagent.name,
+                    input,
+                    run,
+                    runId,
+                    invocationId,
+                    subagentRunId,
+                }), async () => this.delegateToSubagent({
+                    subagent,
+                    binding,
+                    args,
+                    input,
+                    run,
+                    sequence,
+                    subagentRunId,
+                }));
+                return outcome.result;
+            },
+        });
+    }
+    buildDelegationLifecycle(delegation) {
+        const correlation = {
+            agent: delegation.run.agentName,
+            runId: delegation.runId,
+            subagent: delegation.subagentName,
+            invocationId: delegation.invocationId,
+            subagentRunId: delegation.subagentRunId,
+        };
+        return {
+            started: {
+                type: agentRun_typedefs_1.LLMAgentEventTypes.SubagentStarted,
+                ...correlation,
+                input: delegation.input,
+            },
+            completed: (outcome, durationMs) => (outcome.denialReason === undefined
+                ? {
+                    type: agentRun_typedefs_1.LLMAgentEventTypes.SubagentCompleted,
+                    ...correlation,
+                    output: outcome.result,
+                    durationMs,
+                }
+                : {
+                    type: agentRun_typedefs_1.LLMAgentEventTypes.ToolCallDenied,
+                    agent: delegation.run.agentName,
+                    runId: delegation.runId,
+                    tool: delegation.subagentName,
+                    invocationId: delegation.invocationId,
+                    reason: outcome.denialReason,
+                }),
+            failed: (errorMessage, durationMs) => ({
+                type: agentRun_typedefs_1.LLMAgentEventTypes.SubagentFailed,
+                ...correlation,
+                error: errorMessage,
+                durationMs,
+            }),
+        };
+    }
+    async delegateToSubagent(delegation) {
+        const { subagent, args, run } = delegation;
+        const gate = await this.resolveToolGate(subagent.canExecute, args);
+        if (!gate.allowed) {
+            return this.buildDenial(subagent.name, gate.reason);
+        }
+        const subagentResult = await this.runAgentTree({
+            agentName: subagent.name,
+            promptName: subagent.prompt,
+            binding: delegation.binding,
+            variables: this.buildDelegationVariables(subagent, args),
+            input: delegation.input,
+            tools: subagent.tools,
+            subagents: subagent.subagents,
+            maxToolIterations: subagent.maxToolIterations,
+            context: run.context,
+            sessionId: run.sessionId,
+            traceTags: run.traceTags,
+            abortSignal: run.abortSignal,
+            overrides: run.overrides,
+            onEvent: run.onEvent,
+        }, delegation.sequence, delegation.subagentRunId);
+        return {
+            result: this.services.normalizeToolResult({
+                tool: subagent.name,
+                agent: run.agentName,
+                input: args,
+                result: this.stringifySubagentOutcome(subagentResult),
+            }),
+        };
+    }
+    /**
+     * 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.
+     */
+    buildDelegationInput(subagent, args) {
+        if (!subagent.inputSchema) {
+            return String(args.prompt ?? '');
+        }
+        return JSON.stringify(args);
+    }
+    /**
+     * 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.
+     */
+    buildDelegationVariables(subagent, args) {
+        if (!subagent.inputSchema) {
+            return subagent.variables;
+        }
+        return { ...subagent.variables, ...(0, promptVariables_1.stringifyPromptVariables)(args) };
+    }
+    /**
+     * 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
+     * subagent that stopped on its own terminal tool hands that tool's output
+     * back as the delegation result and the parent's loop continues.
+     */
+    stringifySubagentOutcome(subagentResult) {
+        const outcome = subagentResult.terminalTool
+            ? subagentResult.terminalTool.output
+            : subagentResult.output;
+        return typeof outcome === 'string'
+            ? outcome
+            : JSON.stringify(outcome);
+    }
+    normalizeSubagent(subagentEntry) {
+        if (!(subagentEntry instanceof LLMAgent_1.LLMAgent)) {
+            return { ...subagentEntry, variables: subagentEntry.variables ?? {} };
+        }
+        const promptName = String(subagentEntry.prompt);
+        if (!subagentEntry.name || !subagentEntry.description) {
+            throw new errors_1.LLMConfigError(`agent for prompt "${promptName}" needs both "name" and "description"`
+                + ' to be used as a subagent', { promptName });
+        }
+        return {
+            prompt: promptName,
+            name: subagentEntry.name,
+            description: subagentEntry.description,
+            variables: subagentEntry.variables ?? {},
+            tools: subagentEntry.tools,
+            subagents: subagentEntry.subagents,
+            inputSchema: subagentEntry.inputSchema,
+            canExecute: subagentEntry.canExecute,
+            maxToolIterations: subagentEntry.maxToolIterations,
+        };
+    }
+    async withLifecycleEvents(listener, lifecycle, work) {
+        const startedAt = Date.now();
+        this.emit(listener, lifecycle.started);
+        try {
+            const workResult = await work();
+            this.emit(listener, lifecycle.completed(workResult, Date.now() - startedAt));
+            return workResult;
+        }
+        catch (error) {
+            this.emit(listener, lifecycle.failed(toErrorMessage(error), Date.now() - startedAt));
+            throw error;
+        }
+    }
+    /**
+     * Emit an `agent_message` for visible assistant text the model produced
+     * between tool rounds. Attributed to the emitting run via `agent`/`runId`,
+     * so a subagent's narration carries the subagent's identity. Empty or
+     * whitespace-only text is skipped — an `agent_message` always carries real
+     * narration.
+     */
+    emitAgentMessage(run, runId, text) {
+        if (text.trim().length === 0) {
+            return;
+        }
+        this.emit(run.onEvent, {
+            type: agentRun_typedefs_1.LLMAgentEventTypes.AgentMessage,
+            agent: run.agentName,
+            runId,
+            text,
+        });
+    }
+    emit(listener, event) {
+        if (!listener) {
+            return;
+        }
+        try {
+            void Promise.resolve(listener(event)).catch((listenerError) => {
+                this.warnListenerFailure(event, listenerError);
+            });
+        }
+        catch (listenerError) {
+            this.warnListenerFailure(event, listenerError);
+        }
+    }
+    warnListenerFailure(event, error) {
+        this.logger?.warn('Agent event listener failed', {
+            eventType: event.type,
+            error: toErrorMessage(error),
+        });
+    }
+}
+exports.LLMAgentRunner = LLMAgentRunner;
+//# sourceMappingURL=agentRunner.js.map