@mate-academy/llm-gateway 7.7.0 → 8.0.0-canary.1

package/README.md

@@ -141,6 +141,216 @@ To assert emitted observations in tests, register a test double implementing
 `LLMGatewayTracer` via `initLLMGateway({ tracer })` and assert what it captured
 (see `@mate-academy/llm-tracer`'s README for asserting real Langfuse spans).
 
+### v2 Client (`createLLMClient`)
+
+The v2 client is the prompt-name-first call surface. A call site names the
+operation (the Langfuse prompt name); everything else — prompt text, model,
+provider, params, credentials, reporter wiring, tracing, structured output —
+resolves from it inside the package. Build it once at the composition root and
+inject it via DI; feature code never sees configuration or credentials.
+
+Live prompt fetching is behind the `LLMGatewayPromptClient` port, not a
+Langfuse SDK client: the gateway carries no `@langfuse/*` dependency of its
+own. `@mate-academy/prompt-client`'s `LLMPromptClient` satisfies this port
+structurally — pass its `promptClient` straight through. Omitting
+`promptClient` runs the client on the build-time snapshot alone (the same
+no-op-by-omission story as the tracer port).
+
+```typescript
+import {
+  createLLMClient,
+  defineLLMPrompts,
+  LLMSchema,
+} from '@mate-academy/llm-gateway';
+import { LLMPrompt, langfusePromptSnapshot } from './langfusePrompts.generated';
+
+const llmPromptRegistry = defineLLMPrompts({
+  [LLMPrompt.CityPredictionPredictCityName]: {
+    schema: LLMSchema.object({ cityName: LLMSchema.string().nullable() }),
+  },
+});
+
+const llm = createLLMClient({
+  registry: llmPromptRegistry,
+  snapshot: langfusePromptSnapshot,
+  credentials: async ({ provider, promptName, product }) => providerOptions,
+  reporting: { reporter },
+  logger,
+  context: { product, appEnvironment },
+  mode: 'production',
+  promptClient, // an `@mate-academy/prompt-client` bundle's `promptClient`, or omit for snapshot-only
+});
+
+const { cityName } = await llm.generate(
+  LLMPrompt.CityPredictionPredictCityName,
+  { variables: { locationName, countryName }, context: { userId } },
+);
+```
+
+- **Typed end to end.** The client is generic over `typeof registry`. Variables
+  are typed from the generated snapshot (strict on required names, tolerant of
+  extras so a Langfuse edit can never break a build); the return type is the
+  bound schema's inferred type, or `string` when no schema is bound.
+- **Single validation gate on every fetch.** Vars subset, `config` zod-parse,
+  provider/model in the gateway map, param ceilings, and the resolved model's
+  capabilities vs the registry `requires`. Any failure serves the last-known-good
+  snapshot and emits the `LangfuseFallbackServed` metric; `LLMConfigError` throws
+  only when the live config and the fallback are both unusable.
+- **Errors throw with a taxonomy** (`LLMGatewayError` base + `LLMProviderError`,
+  `LLMSchemaValidationError`, `LLMAbortedError`, `LLMConfigError`); validated
+  `data` is the return value, never an `'error' in response` union.
+- **Override gating.** `mode: 'production'` rejects per-call `overrides` with
+  `LLMConfigError`; only `mode: 'experiment'` (harness/playground/tests) honors
+  them.
+
+#### Agent runs (`runAgent`)
+
+`llm.runAgent` runs a tool-calling agent whose instructions are a registry
+prompt: the Langfuse prompt text is the agent's system instructions and its
+`config` routes the model, so an agent is versioned and re-routed exactly like
+any other operation. The provider assistance loop executes the model⇄tool
+rounds; subagents are exposed to the model as tools (one level deep — a
+subagent cannot declare its own subagents).
+
+```typescript
+const turn = await llm.runAgent(LLMPrompt.ContentEditorRootAgent, {
+  variables: { courseName },
+  input: userMessage,
+  history: persistedMessages, // resume from stored session state
+  tools: [createTopicTool, updateTheoryTool, askUserTool],
+  subagents: [{
+    prompt: LLMPrompt.ContentEditorResearchSubagent,
+    name: 'researcher',
+    description: 'Researches sources for course content',
+    variables: { courseName },
+    tools: [searchTool],
+  }],
+  context: { userId },
+  onEvent: (event) => publishAndPersist(event), // WS updates + run history
+});
+
+if (turn.stopReason === LLMToolLoopStopReasons.TerminalTool) {
+  await askTheUser(turn.terminalTool.output); // agent handed control back
+} else {
+  await applyStructure(turn.output); // the model's answer
+}
+```
+
+- **Structured progress events.** Every step emits an `LLMAgentEvent`
+  (`agent_started/message/completed/failed`, `tool_call_started/completed/failed`,
+  `subagent_started/completed/failed`) through `onEvent`, for live subscription
+  updates and durable run persistence. Events carry correlation ids from one
+  sequence per root run — `runId` on every event, `invocationId` on tool and
+  subagent events, `subagentRunId` linking a delegation to the nested run's
+  events — so parallel tool calls and repeated delegations reconstruct into an
+  unambiguous run tree. Listeners may be async; a throw or rejection is logged
+  and never affects the run.
+- **Intermediate narration.** When the model returns visible assistant text
+  alongside tool calls in a round that will continue, that text is emitted as
+  `agent_message` (attributed to the emitting run, so a subagent's narration
+  carries the subagent's identity) before the round's tools run. Reasoning /
+  thinking content and the final answer are never sent this way — the final
+  answer is `agent_completed.output`.
+- **Terminal tools end the turn.** A tool declaring `terminal: true` (an
+  `ask_user` tool, say) hands control back to the application. The round it
+  appears in still runs in full — every call of that round, including parallel
+  ones, executes and emits its `tool_call_*` events — but the results are not
+  fed back and no further model round starts. The run then returns
+  `stopReason: 'terminal_tool'` with `terminalTool` carrying the tool's name
+  and output; if several terminal calls land in one round, the first in the
+  round's order is the outcome (all still execute). This is ordinary control
+  flow — no exception, no abort — and `maxToolIterations` is untouched. A
+  terminal tool that throws still ends the turn, carrying its failure message
+  as the outcome. Delegation tools are never terminal, so a subagent that stops
+  on its own terminal tool returns that output as its delegation result and the
+  parent's loop continues.
+- **Subagent names are tool names.** A subagent's `name` must match
+  `[a-zA-Z0-9_-]+` (it is exposed to the model as a tool); an invalid name
+  fails the run upfront with `LLMConfigError` instead of being silently
+  rewritten.
+
+The plain-object form above is complete on its own. `llm.defineAgent` is
+optional sugar for reusable, composable definitions: it returns an immutable
+`LLMAgent` instance (typed against the registry) that `runAgent` accepts in
+place of a prompt key, and that other agents accept as a subagent. Unlike
+plain-object subagents, `LLMAgent` subagents may declare their own
+`subagents` — instances are immutable, so a delegation cycle cannot be
+constructed. Agent-level `variables` are a base merged under the per-run
+`variables`; a subagent used as a delegation tool must carry `name` and
+`description`.
+
+```typescript
+const researcher = llm.defineAgent({
+  prompt: LLMPrompt.ContentEditorResearchSubagent,
+  name: 'researcher',
+  description: 'Researches sources for course content',
+  variables: { courseName },
+  tools: [searchTool],
+});
+
+const rootAgent = llm.defineAgent({
+  prompt: LLMPrompt.ContentEditorRootAgent,
+  tools: [createTopicTool, updateTheoryTool],
+  subagents: [researcher],
+});
+
+const turn = await llm.runAgent(rootAgent, {
+  variables: { courseName },
+  input: userMessage,
+  context: { userId },
+  onEvent: (event) => publishAndPersist(event),
+});
+```
+- **Typed final output.** A run returns a result discriminated by `stopReason`.
+  For an answered turn (`completed`, or `max_iterations`) the prompt's binding
+  drives `output` exactly like `generate`: the bound schema's inferred type, or
+  the final assistant text when no schema is bound. A `terminal_tool` turn has
+  no model answer, so the bound schema is deliberately not applied — `output`
+  is absent and `terminalTool` is the outcome instead. Both carry `text`, the
+  visible assistant text of the final round.
+- **Tool-capability gate.** When a run has tools or subagents, the validation
+  gate additionally requires the resolved model to declare the `tools`
+  capability, so a Langfuse re-route to a tool-less model serves the fallback
+  instead of failing mid-run.
+- **Langfuse for free.** Provider services already record generation and tool
+  observations under the active trace; wrap the run with the tracer's
+  `withTrace` at the call site to group the whole agent session.
+- Overrides, credentials, reporter context, and the error taxonomy behave
+  exactly as in `generate`.
+
+#### Prompt snapshot codegen
+
+`langfusePrompts.generated.ts` is produced by `npm run langfuse:generate` (root),
+which fetches every labeled prompt and emits the `LLMPrompt` enum, per-prompt
+variable unions, typed `compile()` helpers, and the snapshot used as the outage
+fallback. It is gitignored exactly like GraphQL generated files: regenerated
+locally on demand, in CI before image builds (with a cached-artifact fallback so a
+Langfuse outage never fails a build), and refreshed non-blocking at API pod boot.
+
+`generateSnapshot` (exported from `@mate-academy/llm-gateway/codegen`) takes an
+injected `LLMPromptCatalog` instead of constructing a Langfuse SDK client
+itself — the caller owns the catalog's credentials and its Langfuse project.
+`@mate-academy/prompt-client`'s `LLMPromptClient` satisfies this port too, so
+the same instance a runtime composition root builds can be reused for codegen:
+
+```typescript
+import { generateSnapshot } from '@mate-academy/llm-gateway/codegen';
+
+await generateSnapshot({
+  catalog: promptClient, // an `@mate-academy/prompt-client` bundle's `promptClient`
+  label: 'production',
+  outputPath: './src/langfusePrompts.generated.ts',
+  onLog: (message) => console.log(message),
+});
+```
+
+#### Escape hatch
+
+`@mate-academy/llm-gateway/advanced` re-exports `LLMServiceFactory`, the provider
+services, and the model maps for the rare call site needing raw control. It
+bypasses prompt management, the validation gate, and config-in-prompt routing —
+prefer the v2 client.
+
 ### Logger Interface
 
 The package accepts an optional logger that implements the `LLMLoggerInterface` interface. Most logging libraries are compatible (`@mate-academy/logger`, winston, pino, etc.). If no logger is provided, no logging will occur.

package/dist/LLMService.typedefs.d.ts

@@ -312,6 +312,8 @@ export type LLMStructuredResult<T = any> = LLMRequestResult<{
     parseError?: string;
     toolIterationsUsed?: number;
     toolIterationsExhausted?: true;
+    stopReason?: LLMToolLoopStopReasons;
+    terminalTool?: LLMTerminalToolOutcome;
     usage?: LLMModelUsage;
     cost?: LLMCostsResult;
 }>;
@@ -422,6 +424,16 @@ export type LLMAssistanceOptions<Provider extends LLMProviders, Reporter extends
     storageId?: string;
     tools?: LLMToolDefinition[];
     maxToolIterations?: number;
+    /**
+     * Invoked with the model's visible assistant text from a tool-calling round
+     * that will continue the loop (narration emitted alongside tool calls),
+     * before that round's tools execute. Never carries the final round's answer
+     * or reasoning/thinking content; the text may be empty when the round
+     * produced only tool calls, so the consumer skips empty/whitespace-only text.
+     * Observability-only: the callback must not throw — the tool loop does not
+     * guard the call.
+     */
+    onAssistantNarration?: (text: string) => void;
 };
 /**
  * Result type for assistance requests.
@@ -430,6 +442,8 @@ export type LLMAssistanceResult = LLMRequestResult<{
     text: string;
     toolIterationsUsed?: number;
     toolIterationsExhausted?: true;
+    stopReason?: LLMToolLoopStopReasons;
+    terminalTool?: LLMTerminalToolOutcome;
 }>;
 /**
  * Options for a one-shot prompt in a newly created chat.
@@ -479,6 +493,36 @@ export interface LLMToolDefinition<Schema extends LLMSchemaInterface = LLMSchema
     description: string;
     parameters: Schema;
     execute: (args: InferSchema<Schema>) => Promise<LLMToolResult> | LLMToolResult;
+    /**
+     * Ends the turn once this tool runs. The round executes in full (every call
+     * of that round, including parallel ones), but its results are not fed back
+     * and no further model round starts — the loop stops with
+     * `LLMToolLoopStopReasons.TerminalTool` and this tool's output as the turn
+     * outcome. Use for tools that hand control back to the application, such as
+     * an `ask_user` tool that needs a human reply before the agent can continue.
+     */
+    terminal?: boolean;
+}
+/**
+ * Why a provider's model⇄tool loop stopped. `Completed` is the ordinary end
+ * (a model round returned no tool calls), `MaxIterations` means the loop hit
+ * `maxToolIterations` with tool calls still pending, and `TerminalTool` means
+ * a tool declaring `terminal` ran and ended the turn.
+ */
+export declare enum LLMToolLoopStopReasons {
+    Completed = "completed",
+    MaxIterations = "max_iterations",
+    TerminalTool = "terminal_tool"
+}
+/**
+ * The terminal tool call that ended a turn: the tool's name and the output it
+ * returned, which the application handles instead of a model answer. When more
+ * than one terminal call lands in the same round, the first in the round's
+ * order is reported (all of them still execute).
+ */
+export interface LLMTerminalToolOutcome {
+    name: string;
+    output: LLMToolResult;
 }
 /**
  * Function type for counting tokens in messages for a specific provider's model.

package/dist/LLMService.typedefs.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LLMUploadFileMimeTypes = exports.LLMMessageContentType = exports.LLMRoles = exports.LLMPurposes = exports.LLMProviders = void 0;
+exports.LLMToolLoopStopReasons = exports.LLMUploadFileMimeTypes = exports.LLMMessageContentType = exports.LLMRoles = exports.LLMPurposes = exports.LLMProviders = void 0;
 /**
  * Enum of supported LLM providers.
  */
@@ -57,4 +57,16 @@ var LLMUploadFileMimeTypes;
     LLMUploadFileMimeTypes["AUDIO_WEBM"] = "audio/webm";
     LLMUploadFileMimeTypes["AUDIO_OGG"] = "audio/ogg";
 })(LLMUploadFileMimeTypes || (exports.LLMUploadFileMimeTypes = LLMUploadFileMimeTypes = {}));
+/**
+ * Why a provider's model⇄tool loop stopped. `Completed` is the ordinary end
+ * (a model round returned no tool calls), `MaxIterations` means the loop hit
+ * `maxToolIterations` with tool calls still pending, and `TerminalTool` means
+ * a tool declaring `terminal` ran and ended the turn.
+ */
+var LLMToolLoopStopReasons;
+(function (LLMToolLoopStopReasons) {
+    LLMToolLoopStopReasons["Completed"] = "completed";
+    LLMToolLoopStopReasons["MaxIterations"] = "max_iterations";
+    LLMToolLoopStopReasons["TerminalTool"] = "terminal_tool";
+})(LLMToolLoopStopReasons || (exports.LLMToolLoopStopReasons = LLMToolLoopStopReasons = {}));
 //# sourceMappingURL=LLMService.typedefs.js.map

package/dist/LLMService.typedefs.js.map

@@ -1 +1 @@
-{"version":3,"file":"LLMService.typedefs.js","sourceRoot":"","sources":["../src/LLMService.typedefs.ts"],"names":[],"mappings":";;;AAkCA;;GAEG;AACH,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,iCAAiB,CAAA;IACjB,yDAAyC,CAAA;IACzC,iCAAiB,CAAA;AACnB,CAAC,EAJW,YAAY,4BAAZ,YAAY,QAIvB;AAoBD;;GAEG;AACH,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,wCAAyB,CAAA;IACzB,wCAAyB,CAAA;IACzB,8CAA+B,CAAA;IAC/B,8CAA+B,CAAA;AACjC,CAAC,EALW,WAAW,2BAAX,WAAW,QAKtB;AAiLD;;GAEG;AACH,IAAY,QAGX;AAHD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,mCAAuB,CAAA;AACzB,CAAC,EAHW,QAAQ,wBAAR,QAAQ,QAGnB;AAED;;GAEG;AACH,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,sCAAa,CAAA;IACb,gDAAuB,CAAA;IACvB,kDAAyB,CAAA;AAC3B,CAAC,EAJW,qBAAqB,qCAArB,qBAAqB,QAIhC;AA8KD;;GAEG;AACH,IAAY,sBAeX;AAfD,WAAY,sBAAsB;IAChC,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,yDAA+B,CAAA;IAC/B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,oDAA0B,CAAA;IAC1B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;AACzB,CAAC,EAfW,sBAAsB,sCAAtB,sBAAsB,QAejC"}
+{"version":3,"file":"LLMService.typedefs.js","sourceRoot":"","sources":["../src/LLMService.typedefs.ts"],"names":[],"mappings":";;;AAkCA;;GAEG;AACH,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,iCAAiB,CAAA;IACjB,yDAAyC,CAAA;IACzC,iCAAiB,CAAA;AACnB,CAAC,EAJW,YAAY,4BAAZ,YAAY,QAIvB;AAoBD;;GAEG;AACH,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,wCAAyB,CAAA;IACzB,wCAAyB,CAAA;IACzB,8CAA+B,CAAA;IAC/B,8CAA+B,CAAA;AACjC,CAAC,EALW,WAAW,2BAAX,WAAW,QAKtB;AAiLD;;GAEG;AACH,IAAY,QAGX;AAHD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,mCAAuB,CAAA;AACzB,CAAC,EAHW,QAAQ,wBAAR,QAAQ,QAGnB;AAED;;GAEG;AACH,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,sCAAa,CAAA;IACb,gDAAuB,CAAA;IACvB,kDAAyB,CAAA;AAC3B,CAAC,EAJW,qBAAqB,qCAArB,qBAAqB,QAIhC;AAgLD;;GAEG;AACH,IAAY,sBAeX;AAfD,WAAY,sBAAsB;IAChC,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,yDAA+B,CAAA;IAC/B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,oDAA0B,CAAA;IAC1B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;AACzB,CAAC,EAfW,sBAAsB,sCAAtB,sBAAsB,QAejC;AAwND;;;;;GAKG;AACH,IAAY,sBAIX;AAJD,WAAY,sBAAsB;IAChC,iDAAuB,CAAA;IACvB,0DAAgC,CAAA;IAChC,wDAA8B,CAAA;AAChC,CAAC,EAJW,sBAAsB,sCAAtB,sBAAsB,QAIjC"}

package/dist/advanced.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Escape hatch entry point. Re-exports the internal engine — `LLMServiceFactory`,
+ * the provider services, and the model maps — for the rare call site that needs
+ * raw control the v2 client does not expose. Discouraged: prefer `createLLMClient`
+ * + the typed registry. This surface bypasses prompt management, the validation
+ * gate, and config-in-prompt routing.
+ */
+export { LLMServiceFactory } from './LLMService.factory';
+export { LLM_SERVICE_FACTORIES, LLM_SERVICE_MODELS, } from './LLMService.constants';
+export * from './providers';
+export * from './services';

package/dist/advanced.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM_SERVICE_MODELS = exports.LLM_SERVICE_FACTORIES = exports.LLMServiceFactory = void 0;
+/**
+ * Escape hatch entry point. Re-exports the internal engine — `LLMServiceFactory`,
+ * the provider services, and the model maps — for the rare call site that needs
+ * raw control the v2 client does not expose. Discouraged: prefer `createLLMClient`
+ * + the typed registry. This surface bypasses prompt management, the validation
+ * gate, and config-in-prompt routing.
+ */
+var LLMService_factory_1 = require("./LLMService.factory");
+Object.defineProperty(exports, "LLMServiceFactory", { enumerable: true, get: function () { return LLMService_factory_1.LLMServiceFactory; } });
+var LLMService_constants_1 = require("./LLMService.constants");
+Object.defineProperty(exports, "LLM_SERVICE_FACTORIES", { enumerable: true, get: function () { return LLMService_constants_1.LLM_SERVICE_FACTORIES; } });
+Object.defineProperty(exports, "LLM_SERVICE_MODELS", { enumerable: true, get: function () { return LLMService_constants_1.LLM_SERVICE_MODELS; } });
+__exportStar(require("./providers"), exports);
+__exportStar(require("./services"), exports);
+//# sourceMappingURL=advanced.js.map

package/dist/advanced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,2DAAyD;AAAhD,uHAAA,iBAAiB,OAAA;AAC1B,+DAGgC;AAF9B,6HAAA,qBAAqB,OAAA;AACrB,0HAAA,kBAAkB,OAAA;AAEpB,8CAA4B;AAC5B,6CAA2B"}

package/dist/client/LLMAgent.d.ts

@@ -0,0 +1,63 @@
+import { type LLMToolDefinition } from '../LLMService.typedefs';
+import { type LLMPromptRegistry } from '../client/defineLLMPrompts';
+import { type LLMVariableValue } from '../client/promptSnapshot.typedefs';
+import { type LLMPromptVariables } from '../client/createLLMClient.typedefs';
+/**
+ * A bounded specialist the root agent may delegate to, as a plain object.
+ * `prompt` names the registry entry whose Langfuse prompt is the subagent's
+ * instructions (and whose config routes its model); `name`/`description` are
+ * what the root model sees when deciding to delegate. A plain-object subagent
+ * cannot declare its own subagents — use `LLMAgent` instances (via
+ * `llm.defineAgent`) when deeper composition is needed.
+ */
+export type LLMAgentSubagentDefinition<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>> = {
+    [Key in keyof Registry]: {
+        prompt: Key;
+        name: string;
+        description: string;
+        variables: LLMPromptVariables<VariableMap[Key]>;
+        tools?: LLMToolDefinition[];
+        maxToolIterations?: number;
+    };
+}[keyof Registry];
+/**
+ * Anything accepted in a `subagents` list: a plain definition object or an
+ * `LLMAgent` instance — both describe the same delegation tool.
+ */
+export type LLMAgentSubagent<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>> = LLMAgentSubagentDefinition<Registry, VariableMap> | LLMAgent<Registry, VariableMap>;
+/**
+ * The declarative description of one agent. `prompt` names the registry entry
+ * whose Langfuse prompt is the agent's instructions (and whose config routes
+ * its model). `name`/`description` are required when the agent is used as a
+ * subagent — the name becomes the delegation tool the parent model calls.
+ * `variables` given here are a base merged under the per-run variables (for a
+ * subagent they are the only source).
+ */
+export interface LLMAgentDefinition<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>, Key extends keyof Registry> {
+    prompt: Key;
+    name?: string;
+    description?: string;
+    variables?: LLMPromptVariables<VariableMap[Key]>;
+    tools?: LLMToolDefinition[];
+    subagents?: LLMAgentSubagent<Registry, VariableMap>[];
+    maxToolIterations?: number;
+}
+/**
+ * An immutable agent definition bound to the prompt registry. Optional sugar
+ * over the plain-object `runAgent` options: build instances with
+ * `llm.defineAgent(...)` — the client factory carries the registry generics,
+ * so `prompt`, `variables`, and the `runAgent` return type stay fully typed.
+ * Agents compose: a subagent may itself be an `LLMAgent` with its own
+ * subagents; because instances are immutable, a delegation cycle cannot be
+ * constructed and nesting depth is always finite.
+ */
+export declare class LLMAgent<Registry extends LLMPromptRegistry = LLMPromptRegistry, VariableMap extends Record<keyof Registry, string> = Record<keyof Registry, string>, Key extends keyof Registry = keyof Registry> {
+    readonly prompt: Key;
+    readonly name: string | undefined;
+    readonly description: string | undefined;
+    readonly variables: Record<string, LLMVariableValue> | undefined;
+    readonly tools: LLMToolDefinition[] | undefined;
+    readonly subagents: LLMAgentSubagent<Registry, VariableMap>[] | undefined;
+    readonly maxToolIterations: number | undefined;
+    constructor(definition: LLMAgentDefinition<Registry, VariableMap, Key>);
+}

package/dist/client/LLMAgent.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMAgent = void 0;
+/**
+ * An immutable agent definition bound to the prompt registry. Optional sugar
+ * over the plain-object `runAgent` options: build instances with
+ * `llm.defineAgent(...)` — the client factory carries the registry generics,
+ * so `prompt`, `variables`, and the `runAgent` return type stay fully typed.
+ * Agents compose: a subagent may itself be an `LLMAgent` with its own
+ * subagents; because instances are immutable, a delegation cycle cannot be
+ * constructed and nesting depth is always finite.
+ */
+class LLMAgent {
+    prompt;
+    name;
+    description;
+    variables;
+    tools;
+    subagents;
+    maxToolIterations;
+    constructor(definition) {
+        this.prompt = definition.prompt;
+        this.name = definition.name;
+        this.description = definition.description;
+        this.variables = definition.variables;
+        this.tools = definition.tools;
+        this.subagents = definition.subagents;
+        this.maxToolIterations = definition.maxToolIterations;
+    }
+}
+exports.LLMAgent = LLMAgent;
+//# sourceMappingURL=LLMAgent.js.map

package/dist/client/LLMAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMAgent.js","sourceRoot":"","sources":["../../src/client/LLMAgent.ts"],"names":[],"mappings":";;;AA8DA;;;;;;;;GAQG;AACH,MAAa,QAAQ;IAMV,MAAM,CAAM;IAEZ,IAAI,CAAqB;IAEzB,WAAW,CAAqB;IAEhC,SAAS,CAA+C;IAExD,KAAK,CAAkC;IAEvC,SAAS,CAAwD;IAEjE,iBAAiB,CAAqB;IAE/C,YAAY,UAA0D;QACpE,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC;QACtC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC;QACtC,IAAI,CAAC,iBAAiB,GAAG,UAAU,CAAC,iBAAiB,CAAC;IACxD,CAAC;CACF;AA7BD,4BA6BC"}

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

@@ -0,0 +1,170 @@
+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 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",
+    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;
+}
+export interface LLMAgentSubagentStartedEvent extends LLMAgentSubagentEventBase {
+    type: LLMAgentEventTypes.SubagentStarted;
+    input: string;
+}
+export interface LLMAgentSubagentCompletedEvent extends LLMAgentSubagentEventBase {
+    type: LLMAgentEventTypes.SubagentCompleted;
+    output: string;
+    durationMs: number;
+}
+export interface LLMAgentSubagentFailedEvent extends LLMAgentSubagentEventBase {
+    type: LLMAgentEventTypes.SubagentFailed;
+    error: string;
+    durationMs: number;
+}
+export type LLMAgentEvent = LLMAgentStartedEvent | LLMAgentMessageEvent | LLMAgentCompletedEvent | LLMAgentFailedEvent | LLMAgentToolCallStartedEvent | LLMAgentToolCallCompletedEvent | LLMAgentToolCallFailedEvent | 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;
+    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,24 @@
+"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["SubagentStarted"] = "subagent_started";
+    LLMAgentEventTypes["SubagentCompleted"] = "subagent_completed";
+    LLMAgentEventTypes["SubagentFailed"] = "subagent_failed";
+})(LLMAgentEventTypes || (exports.LLMAgentEventTypes = LLMAgentEventTypes = {}));
+//# sourceMappingURL=agentRun.typedefs.js.map