@mate-academy/llm-gateway 8.8.2 → 8.8.3

package/dist/client/LLMClientEngine.js

@@ -0,0 +1,406 @@
+"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;
+    buildReporterContextFor;
+    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.buildReporterContextFor = config.buildReporterContext;
+        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,
+            sessionId: options.sessionId,
+            traceTags: options.traceTags,
+            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,
+            callContext: undefined,
+        });
+        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 }));
+    }
+    withAgentObservation(name, input, fn) {
+        return this.gateway.getTracer().withAgentObservation(name, input, fn);
+    }
+    async runCompletion(resolved, schema, options) {
+        const service = await this.buildCompletionService({
+            resolved,
+            callContext: options.context,
+        });
+        const envelope = this.buildMessageEnvelope(resolved, options.history);
+        const reporterContext = this.buildReporterContext(resolved, options.context);
+        const traceContext = this.buildTraceContext({
+            resolved,
+            callContext: options.context,
+            sessionId: options.sessionId,
+            traceTags: options.traceTags,
+        });
+        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(options) {
+        const providerOptions = await this.resolveProviderOptions(options);
+        const { resolved } = options;
+        return this.gateway.getAssistanceService({
+            provider: resolved.config.provider,
+            options: providerOptions,
+            logger: this.logger,
+            reporter: this.reporter,
+        });
+    }
+    getBinding(promptName) {
+        return this.registry[promptName];
+    }
+    async buildCompletionService(options) {
+        const providerOptions = await this.resolveProviderOptions(options);
+        const { resolved } = options;
+        return this.gateway.getCompletionService({
+            provider: resolved.config.provider,
+            options: providerOptions,
+            logger: this.logger,
+            reporter: this.reporter,
+        });
+    }
+    /**
+     * Resolves credentials for the product this call belongs to. The per-call
+     * context wins over the static one: the client is built once per process, so
+     * its static product is only ever the one its builder knew, while a call site
+     * that resolves the product from its own subject knows better.
+     */
+    async resolveProviderOptions(options) {
+        const { resolved, callContext } = options;
+        return this.credentials({
+            provider: resolved.config.provider,
+            promptName: resolved.name,
+            product: typeof callContext?.product === 'string'
+                ? callContext.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 }],
+        };
+    }
+    /**
+     * Delegates the reporter's payload to the composition root. The gateway never
+     * shapes it: those fields are a downstream contract (DWH columns and the
+     * dashboards built on their exact values), so inventing a key or a string
+     * here would silently break analytics rather than fail a build.
+     *
+     * The active trace scope's context travels along as `scopeContext`, so the
+     * composition root can fall back to what the surrounding operation declared
+     * when the call itself names nothing.
+     */
+    buildReporterContext(resolved, callContext) {
+        if (!this.reporter || !this.buildReporterContextFor) {
+            return undefined;
+        }
+        return this.buildReporterContextFor({
+            promptName: resolved.name,
+            promptVersion: resolved.version,
+            callContext,
+            staticContext: this.staticContext,
+            scopeContext: this.gateway.getTracer().getActiveTraceContext(),
+        });
+    }
+    /**
+     * 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.
+     *
+     * `userId`, `sessionId` and `tags` travel as typed trace fields and never
+     * through `serializeCallContext`, which is the metadata path. The user
+     * therefore appears twice — typed here and, as it always has, inside the
+     * metadata bag the existing dashboards read.
+     */
+    buildTraceContext(scope) {
+        const { resolved, callContext, sessionId, traceTags, } = scope;
+        return {
+            prompt: {
+                name: resolved.name,
+                version: resolved.version,
+                isFallback: resolved.isFallback,
+            },
+            userId: this.toTraceUserId(callContext?.userId),
+            sessionId,
+            tags: traceTags,
+            metadata: {
+                ...this.serializeCallContext(callContext),
+                promptVersion: resolved.version,
+                isFallback: resolved.isFallback,
+            },
+        };
+    }
+    /**
+     * The call context holds the user as whatever the application uses for its
+     * own ids, while Langfuse holds it as a string. Absent stays absent, so a
+     * call that names no user leaves the trace's user field for the scope to fill.
+     */
+    toTraceUserId(userId) {
+        if (userId === null || userId === undefined) {
+            return undefined;
+        }
+        return String(userId);
+    }
+    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":"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"}

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

@@ -0,0 +1,200 @@
+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/llmClient.typedefs';
+import { type LLMAgentSubagent } from '../client/LLMAgent';
+/**
+ * Structured progress events an agent run emits while it works. They exist for
+ * two consumers with different needs: live UI updates (publish each event over
+ * a subscription/WS channel) and durable run history (persist each event as it
+ * arrives). Events are observability output, not control flow — a listener
+ * failure never affects the run.
+ */
+export declare enum LLMAgentEventTypes {
+    AgentStarted = "agent_started",
+    AgentMessage = "agent_message",
+    AgentCompleted = "agent_completed",
+    AgentFailed = "agent_failed",
+    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"
+}
+/**
+ * `agent` names the run that emitted the event: the prompt name for the root
+ * run, the subagent's `name` for a delegated run. `runId` identifies that run
+ * uniquely within the root run's event stream (ids come from one sequence
+ * spanning the whole tree), so a flat listener can rebuild the run tree even
+ * when the same subagent runs twice or tools execute in parallel.
+ */
+interface LLMAgentEventBase {
+    agent: string;
+    runId: number;
+}
+/** Correlates the started/completed/failed events of one tool invocation. */
+interface LLMAgentInvocationEventBase extends LLMAgentEventBase {
+    invocationId: number;
+}
+/**
+ * `subagentRunId` is the `runId` carried by the delegated run's own events,
+ * linking a Subagent* event to the nested Agent* events it produced.
+ */
+interface LLMAgentSubagentEventBase extends LLMAgentInvocationEventBase {
+    subagent: string;
+    subagentRunId: number;
+}
+export interface LLMAgentStartedEvent extends LLMAgentEventBase {
+    type: LLMAgentEventTypes.AgentStarted;
+    input: string;
+}
+/**
+ * Visible assistant text the model produced in a tool-calling round that will
+ * continue the loop — narration emitted alongside tool calls, before those
+ * tools run. The final round's answer is never sent here (it is
+ * `LLMAgentCompletedEvent.output`); reasoning/thinking content and
+ * empty/whitespace-only text are never sent either. `agent`/`runId` identify
+ * the emitting run, so a subagent's narration is attributed to the subagent.
+ */
+export interface LLMAgentMessageEvent extends LLMAgentEventBase {
+    type: LLMAgentEventTypes.AgentMessage;
+    text: string;
+}
+export interface LLMAgentCompletedEvent extends LLMAgentEventBase {
+    type: LLMAgentEventTypes.AgentCompleted;
+    output: string;
+    durationMs: number;
+}
+export interface LLMAgentFailedEvent extends LLMAgentEventBase {
+    type: LLMAgentEventTypes.AgentFailed;
+    error: string;
+    durationMs: number;
+}
+export interface LLMAgentToolCallStartedEvent extends LLMAgentInvocationEventBase {
+    type: LLMAgentEventTypes.ToolCallStarted;
+    tool: string;
+    input: unknown;
+}
+export interface LLMAgentToolCallCompletedEvent extends LLMAgentInvocationEventBase {
+    type: LLMAgentEventTypes.ToolCallCompleted;
+    tool: string;
+    output: LLMToolResult;
+    durationMs: number;
+}
+export interface LLMAgentToolCallFailedEvent extends LLMAgentInvocationEventBase {
+    type: LLMAgentEventTypes.ToolCallFailed;
+    tool: string;
+    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: LLMToolResult;
+    durationMs: number;
+}
+export interface LLMAgentSubagentFailedEvent extends LLMAgentSubagentEventBase {
+    type: LLMAgentEventTypes.SubagentFailed;
+    error: string;
+    durationMs: number;
+}
+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.
+ */
+export type LLMAgentEventListener = (event: LLMAgentEvent) => void | Promise<void>;
+/**
+ * A turn that produced a model answer: either the model finished on its own
+ * (`Completed`) or the loop hit `maxToolIterations` (`MaxIterations`). `output`
+ * is the bound schema's type, or the final assistant text when no schema is
+ * bound — exactly what `generate` returns.
+ */
+export interface LLMAgentAnsweredRunResult<Output> {
+    stopReason: Exclude<LLMToolLoopStopReasons, LLMToolLoopStopReasons.TerminalTool>;
+    output: Output;
+    /** Visible assistant text of the final round. */
+    text: string;
+    terminalTool?: undefined;
+}
+/**
+ * A turn ended by a tool declaring `terminal` (for example an `ask_user` tool).
+ * The model produced no final answer — the round ran in full, its results were
+ * not fed back, and no further model round started — so the turn's outcome is
+ * `terminalTool`, which the application handles before resuming the agent.
+ */
+export interface LLMAgentTerminalToolRunResult {
+    stopReason: LLMToolLoopStopReasons.TerminalTool;
+    terminalTool: LLMTerminalToolOutcome;
+    /** Visible assistant text of the terminating round; often empty. */
+    text: string;
+    output?: undefined;
+}
+/**
+ * What one agent run produced. Discriminate on `stopReason` (or on the presence
+ * of `terminalTool`) to tell an answered turn from one handed back to the
+ * application by a terminal tool.
+ */
+export type LLMAgentRunResult<Output> = LLMAgentAnsweredRunResult<Output> | LLMAgentTerminalToolRunResult;
+/**
+ * Per-run inputs shared by both `runAgent` forms. When running an `LLMAgent`
+ * instance these are the only options — the agent already carries its tools,
+ * subagents, and iteration bound.
+ */
+export interface LLMAgentRunOptions<Variables extends Record<string, LLMVariableValue>> {
+    /** Variables compiled into the agent's instructions prompt. */
+    variables: Variables;
+    /** The user request the agent works on this run. */
+    input: string;
+    /** Prior conversation restored from persisted session state. */
+    history?: LLMPlainMessage[];
+    context?: LLMClientCallContext;
+    /**
+     * Groups the traces of one conversation, review, or agent run into a single
+     * Langfuse session, subagent runs included. It is a typed Langfuse trace
+     * field, not metadata, so it never reaches the reporter's payload. Top level
+     * rather than nested under a trace object because a session is understandable
+     * without knowing what a trace is. Keep the anchor stable — changing it
+     * splits a session's history in two.
+     */
+    sessionId?: string;
+    /**
+     * Langfuse trace tags. Typed Langfuse trace fields, not metadata. The `trace`
+     * prefix is deliberate: a bare `tags` says nothing about which system reads
+     * them.
+     */
+    traceTags?: string[];
+    abortSignal?: AbortSignal;
+    overrides?: LLMCallOverrides;
+    onEvent?: LLMAgentEventListener;
+}
+/**
+ * Options for the prompt-key form of `runAgent`, where the agent shape is
+ * declared inline instead of via an `LLMAgent` instance.
+ */
+export interface LLMAgentInlineRunOptions<Variables extends Record<string, LLMVariableValue>, Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>> extends LLMAgentRunOptions<Variables> {
+    /** Executable tools available to the agent. */
+    tools?: LLMToolDefinition[];
+    subagents?: LLMAgentSubagent<Registry, VariableMap>[];
+    maxToolIterations?: number;
+}
+export {};

package/dist/client/agentRun.typedefs.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMAgentEventTypes = void 0;
+/**
+ * Structured progress events an agent run emits while it works. They exist for
+ * two consumers with different needs: live UI updates (publish each event over
+ * a subscription/WS channel) and durable run history (persist each event as it
+ * arrives). Events are observability output, not control flow — a listener
+ * failure never affects the run.
+ */
+var LLMAgentEventTypes;
+(function (LLMAgentEventTypes) {
+    LLMAgentEventTypes["AgentStarted"] = "agent_started";
+    LLMAgentEventTypes["AgentMessage"] = "agent_message";
+    LLMAgentEventTypes["AgentCompleted"] = "agent_completed";
+    LLMAgentEventTypes["AgentFailed"] = "agent_failed";
+    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";
+})(LLMAgentEventTypes || (exports.LLMAgentEventTypes = LLMAgentEventTypes = {}));
+//# sourceMappingURL=agentRun.typedefs.js.map

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

@@ -0,0 +1 @@
+{"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"}