@mate-academy/llm-gateway 8.1.0 → 8.2.1

package/README.md

@@ -124,10 +124,10 @@ content, model, params, usage, cost) at the same success/error points the metric
 reporter already wraps — one on success, one (level `ERROR`) on failure;
 assistance tool loops emit a child `tool` observation per tool call. Calls that
 carry no per-call trace context (text-to-speech, file and chat management) emit
-none, on either branch. Observation input/output are capped by `truncateTraceIO`
-before they are stamped, so a large prompt or completion cannot inflate the trace
-payload. All of this is fire-and-forget — a tracing failure never blocks or fails
-an LLM call.
+none, on either branch. Observation input/output are recorded in full — the
+prompt and the completion are what a trace exists to show, so they are never
+truncated. All of this is fire-and-forget — a tracing failure never blocks or
+fails an LLM call.
 
 Pass `traceContext.prompt` (`{ name, version, isFallback }`) to name the
 observation after the managed prompt and link it to that prompt version in
@@ -315,6 +315,62 @@ if (turn.stopReason === LLMToolLoopStopReasons.TerminalTool) {
   `[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.
+- **Typed delegation inputs.** A subagent declaring an `inputSchema` is exposed
+  to the model with that schema instead of the default single `prompt` string,
+  and the arguments the parent model fills join the subagent's own `variables`
+  (winning over them), so its prompt can reference them as `{{topicRef}}` and
+  the validation gate checks them like any other variable. Use it whenever the
+  delegated work needs identifiers the parent must not paraphrase — an entity
+  ref, a changeset id, an enum choice. Without `inputSchema` nothing changes:
+  one free-form `prompt` argument, which is also the nested run's input.
+
+  ```typescript
+  const theoryWriter = llm.defineAgent({
+    prompt: LLMPrompt.ContentEditorWriteTheory,
+    name: 'write_theory',
+    description: 'Authors one theory document into the current changeset',
+    inputSchema: LLMSchema.object({
+      topicRef: LLMSchema.string().describe('Changeset entity ref of the topic'),
+      audienceLevel: LLMSchema.enum(['beginner', 'intermediate', 'advanced']),
+      outline: LLMSchema.array(LLMSchema.string()),
+    }),
+    variables: { changesetId },
+    tools: [getEntityTool, saveTheoryTool],
+  });
+  ```
+- **One place normalizes tool output.** Every tool result and every delegation
+  result passes through the package's coercion before the model sees it, so a
+  tool that returns an object, a number or nothing cannot put `[object Object]`
+  into the conversation. A client may add its own `normalizeToolResult` on top —
+  the natural place to wrap untrusted material (a fetched web page) so no tool
+  author can forget to:
+
+  ```typescript
+  const llm = createLLMClient({
+    // ...
+    normalizeToolResult: ({ tool, result }) => (
+      UNTRUSTED_TOOLS.has(tool)
+        ? { content: `<untrusted source="${tool}">\n${toText(result)}\n</untrusted>` }
+        : result
+    ),
+  });
+  ```
+
+  The normalized value is what reaches both the model and the
+  `tool_call_completed` event, so a persisted run history records exactly what
+  the model read.
+- **Preconditions gate a call before it runs.** A tool may declare
+  `canExecute(args)` returning `{ allowed: true }` or
+  `{ allowed: false, reason }`. It is checked before `execute`, so a refused
+  call never has its side effect. A refusal is ordinary control flow, not an
+  error: the model is told the reason as that call's result, the run continues,
+  and the iteration budget is untouched — so the model can ask the user or take
+  another path. The invocation reports `tool_call_denied` instead of
+  `tool_call_completed`, and a refused delegation reports the same event with
+  `tool` naming the subagent. Use it for permission, quota and state checks that
+  depend on the arguments (an authorization check before a write, a stale-hash
+  guard, a per-run write budget) — enforcement then lives in the tool's
+  definition rather than in prompt instructions the model may ignore.
 
 The plain-object form above is complete on its own. `llm.defineAgent` is
 optional sugar for reusable, composable definitions: it returns an immutable
@@ -374,6 +430,14 @@ 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.
 
+The emitted file contains declarations only. Its compile helpers delegate to
+`compileTextFromSnapshot` / `compileMessagesFromSnapshot`, imported from this
+package rather than copied into the output as source text, so the substitution
+logic has one implementation with its own tests. The declarations themselves are
+built with ts-morph through its structural API, not by string concatenation —
+ts-morph is a dependency of the `codegen` entry point only, so importing the
+package's main entry never pulls it in.
+
 `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.

package/dist/LLMService.typedefs.d.ts

@@ -491,11 +491,31 @@ export interface LLMStructuredToolResult {
  * images.
  */
 export type LLMToolResult = string | LLMStructuredToolResult;
+/**
+ * The verdict of a tool's `canExecute` precondition. A refusal carries the
+ * `reason` the model is told, which is why it is required: a denial the model
+ * cannot explain to itself is a denial it will retry blindly.
+ */
+export type LLMToolGateResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
 export interface LLMToolDefinition<Schema extends LLMSchemaInterface = LLMSchemaInterface> {
     name: string;
     description: string;
     parameters: Schema;
     execute: (args: InferSchema<Schema>) => Promise<LLMToolResult> | LLMToolResult;
+    /**
+     * Decides whether this call may run, on the arguments the model supplied.
+     * Checked before `execute`, so a refused call never has its side effect. A
+     * refusal is ordinary control flow, not an error: the model is told the
+     * `reason` as the call's result and the run continues with its iteration
+     * budget untouched. Use it for permission, quota, and state preconditions
+     * that depend on the arguments rather than on the tool being present at all.
+     */
+    canExecute?: (args: InferSchema<Schema>) => Promise<LLMToolGateResult> | LLMToolGateResult;
     /**
      * 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

package/dist/LLMService.typedefs.js.map

@@ -1 +1 @@
-{"version":3,"file":"LLMService.typedefs.js","sourceRoot":"","sources":["../src/LLMService.typedefs.ts"],"names":[],"mappings":";;;AAmCA;;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;AAkLD;;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"}
+{"version":3,"file":"LLMService.typedefs.js","sourceRoot":"","sources":["../src/LLMService.typedefs.ts"],"names":[],"mappings":";;;AAmCA;;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;AAkLD;;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;AA4OD;;;;;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/client/LLMAgent.d.ts

@@ -1,7 +1,8 @@
 import { type LLMToolDefinition } from '../LLMService.typedefs';
+import { type LLMSchemaInterface } from '../utilities/schema';
 import { type LLMPromptRegistry } from '../client/defineLLMPrompts';
 import { type LLMVariableValue } from '../client/promptSnapshot.typedefs';
-import { type LLMPromptVariables } from '../client/createLLMClient.typedefs';
+import { type LLMDelegationGate, type LLMPromptVariables, type LLMSubagentVariableSource } from '../client/llmClient.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
@@ -15,10 +16,10 @@ export type LLMAgentSubagentDefinition<Registry extends LLMPromptRegistry, Varia
         prompt: Key;
         name: string;
         description: string;
-        variables: LLMPromptVariables<VariableMap[Key]>;
         tools?: LLMToolDefinition[];
+        canExecute?: LLMDelegationGate;
         maxToolIterations?: number;
-    };
+    } & LLMSubagentVariableSource<VariableMap[Key]>;
 }[keyof Registry];
 /**
  * Anything accepted in a `subagents` list: a plain definition object or an
@@ -31,7 +32,8 @@ export type LLMAgentSubagent<Registry extends LLMPromptRegistry, VariableMap ext
  * 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).
+ * subagent they are the only source, unless `inputSchema` lets the parent
+ * model supply more).
  */
 export interface LLMAgentDefinition<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>, Key extends keyof Registry> {
     prompt: Key;
@@ -40,6 +42,15 @@ export interface LLMAgentDefinition<Registry extends LLMPromptRegistry, Variable
     variables?: LLMPromptVariables<VariableMap[Key]>;
     tools?: LLMToolDefinition[];
     subagents?: LLMAgentSubagent<Registry, VariableMap>[];
+    /**
+     * The arguments the parent model must supply when delegating to this agent,
+     * replacing the default single `prompt` string. Each argument joins the
+     * subagent's prompt variables (over the definition's own), so the delegated
+     * prompt can reference them as `{{name}}`. Only meaningful as a subagent.
+     */
+    inputSchema?: LLMSchemaInterface;
+    /** Refuses a delegation call before it runs; see `LLMDelegationGate`. */
+    canExecute?: LLMDelegationGate;
     maxToolIterations?: number;
 }
 /**
@@ -58,6 +69,8 @@ export declare class LLMAgent<Registry extends LLMPromptRegistry = LLMPromptRegi
     readonly variables: Record<string, LLMVariableValue> | undefined;
     readonly tools: LLMToolDefinition[] | undefined;
     readonly subagents: LLMAgentSubagent<Registry, VariableMap>[] | undefined;
+    readonly inputSchema: LLMSchemaInterface | undefined;
+    readonly canExecute: LLMDelegationGate | undefined;
     readonly maxToolIterations: number | undefined;
     constructor(definition: LLMAgentDefinition<Registry, VariableMap, Key>);
 }

package/dist/client/LLMAgent.js

@@ -17,6 +17,8 @@ class LLMAgent {
     variables;
     tools;
     subagents;
+    inputSchema;
+    canExecute;
     maxToolIterations;
     constructor(definition) {
         this.prompt = definition.prompt;
@@ -25,6 +27,8 @@ class LLMAgent {
         this.variables = definition.variables;
         this.tools = definition.tools;
         this.subagents = definition.subagents;
+        this.inputSchema = definition.inputSchema;
+        this.canExecute = definition.canExecute;
         this.maxToolIterations = definition.maxToolIterations;
     }
 }

package/dist/client/LLMAgent.js.map

@@ -1 +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"}
+{"version":3,"file":"LLMAgent.js","sourceRoot":"","sources":["../../src/client/LLMAgent.ts"],"names":[],"mappings":";;;AA2EA;;;;;;;;GAQG;AACH,MAAa,QAAQ;IAMV,MAAM,CAAM;IAEZ,IAAI,CAAqB;IAEzB,WAAW,CAAqB;IAEhC,SAAS,CAA+C;IAExD,KAAK,CAAkC;IAEvC,SAAS,CAAwD;IAEjE,WAAW,CAAiC;IAE5C,UAAU,CAAgC;IAE1C,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,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;QACxC,IAAI,CAAC,iBAAiB,GAAG,UAAU,CAAC,iBAAiB,CAAC;IACxD,CAAC;CACF;AAnCD,4BAmCC"}

package/dist/client/LLMClientEngine.d.ts

@@ -0,0 +1,81 @@
+import { type LLMCallTraceContext, type LLMToolResult } from '../LLMService.typedefs';
+import { type LLMReporterInterface } from '../utilities/reporter';
+import { type LLMSchemaInterface } from '../utilities/schema';
+import { type LLMPromptBinding, type LLMPromptRegistry } from '../client/defineLLMPrompts';
+import { type LLMAgentInlineRunOptions, type LLMAgentRunResult } from '../client/agentRun.typedefs';
+import { LLMAgent, type LLMAgentDefinition } from '../client/LLMAgent';
+import { type LLMAgentCallServices, type LLMPromptResolutionCall } from '../client/agentRunner';
+import { type LLMClientCallContext, type LLMClientEngineConfig, type LLMGenerateOptions, type LLMGenerateResult, type LLMPlainMessage, type LLMPromptDescription, type LLMToolResultContext } from '../client/llmClient.typedefs';
+import { type LLMVariableValue } from '../client/promptSnapshot.typedefs';
+import { type ResolvedPrompt } from '../client/promptRegistry.runtime';
+/**
+ * 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.
+ */
+export declare class LLMClientEngine<Registry extends LLMPromptRegistry> implements LLMAgentCallServices {
+    private readonly gateway;
+    private readonly registry;
+    private readonly runtime;
+    private readonly credentials;
+    private readonly reporter;
+    private readonly logger;
+    private readonly staticContext;
+    private readonly mode;
+    private readonly toolResultNormalizer;
+    private readonly agentRunner;
+    constructor(config: LLMClientEngineConfig<Registry>);
+    generate<Key extends keyof Registry, Schema extends LLMSchemaInterface = never>(prompt: Key, options: LLMGenerateOptions<Record<string, LLMVariableValue>, Schema>): Promise<unknown>;
+    defineAgent<Key extends keyof Registry>(definition: LLMAgentDefinition<Registry, Record<keyof Registry, string>, Key>): LLMAgent<Registry, Record<keyof Registry, string>, Key>;
+    runAgent<Key extends keyof Registry>(promptOrAgent: Key | LLMAgent<Registry, Record<keyof Registry, string>>, options: LLMAgentInlineRunOptions<Record<string, LLMVariableValue>, Registry, Record<keyof Registry, string>>): Promise<LLMAgentRunResult<LLMGenerateResult<Registry[Key]>>>;
+    countTokens<Key extends keyof Registry>(prompt: Key, options: {
+        variables: Record<string, LLMVariableValue>;
+        history?: LLMPlainMessage[];
+    }): Promise<number>;
+    describePrompt<Key extends keyof Registry>(prompt: Key): Promise<LLMPromptDescription>;
+    resolvePrompt(promptName: string, binding: LLMPromptBinding, variables: Record<string, LLMVariableValue>, call: LLMPromptResolutionCall): Promise<ResolvedPrompt>;
+    /**
+     * 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: LLMToolResultContext): LLMToolResult;
+    private runCompletion;
+    /**
+     * 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.
+     */
+    private buildMessageEnvelope;
+    private findLastUserIndex;
+    private callProvider;
+    unwrapResult(resolved: ResolvedPrompt, schema: LLMSchemaInterface | undefined, sendResult: {
+        text?: string;
+        data?: unknown;
+        parseError?: string;
+    }): unknown;
+    toTaxonomyError(error: unknown, resolved: ResolvedPrompt, abortSignal?: AbortSignal): Error;
+    buildAssistanceService(resolved: ResolvedPrompt, promptName: string): Promise<import("..").LLMAssistanceService<import("../LLMService.typedefs").LLMProviders, LLMReporterInterface<any>>>;
+    getBinding(promptName: string): LLMPromptBinding | undefined;
+    private buildCompletionService;
+    private resolveProviderOptions;
+    private buildUserMessage;
+    private buildHistory;
+    private toCompletionMessage;
+    buildReporterContext(resolved: ResolvedPrompt, callContext: LLMClientCallContext | undefined): Record<string, unknown> | undefined;
+    /**
+     * Builds the per-call trace context every client path threads into the gateway
+     * service. The structural `prompt` names the observation and carries the
+     * managed prompt version, so the generation the service records on success and
+     * on error is the single one Langfuse links to that prompt — the client never
+     * records a second observation of its own.
+     */
+    buildTraceContext(resolved: ResolvedPrompt, callContext: LLMClientCallContext | undefined): LLMCallTraceContext;
+    private assertOverridesAllowed;
+    private serializeCallContext;
+    private extractStatus;
+    private isRetryableStatus;
+}

package/dist/client/LLMClientEngine.js

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