@mate-academy/llm-gateway 8.0.0 → 8.2.0

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
@@ -135,6 +135,14 @@ Langfuse; a fallback prompt intentionally produces no link. The v2 client builds
 this context for every call it makes, so `generate` and `runAgent` need nothing
 at the call site.
 
+The observation also carries its real time span. Each provider service captures
+`startedAt` (epoch ms) before the provider call and the base service stamps
+`endedAt` when it hands the record to the tracer, so the exported generation has
+the actual call latency instead of a zero-width span. Both fields are required
+on `LLMGenerationTraceRecord`, and `startedAt` is required on the
+`LLMGenerationTrace` a provider builds — a new provider call site cannot compile
+without threading a start timestamp.
+
 To group several calls under one trace, wrap the work so nested gateway calls
 attach to it automatically:
 
@@ -307,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
@@ -366,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/LLMGateway.d.ts

@@ -1,7 +1,7 @@
 import { type LLMProviders, type LLMPurposes, type LLMServiceByPurpose, type LLMServiceOptions } from './LLMService.typedefs';
 import { type LLMGatewayOptions } from './LLMGateway.typedefs';
 import { type LLMReporterInterface } from './utilities/reporter';
-import { type LangfuseFallbackMetricDimensions, type LLMGatewayTracer, type LLMTraceContext } from './utilities/llmTracing';
+import { type LLMFallbackMetricDimensions, type LLMGatewayTracer, type LLMTraceContext } from './utilities/llmTracing';
 /**
  * An explicitly constructed gateway: every service it hands out is wired to the
  * tracer this instance was built with. `LLMServiceFactory` stays available for
@@ -25,6 +25,6 @@ export declare class LLMGateway {
      * long-running API calls it from its shutdown hook only.
      */
     flush(): Promise<void>;
-    emitFallbackServed(dimensions: LangfuseFallbackMetricDimensions): void;
+    emitFallbackServed(dimensions: LLMFallbackMetricDimensions): void;
     private traced;
 }

package/dist/LLMGateway.js.map

@@ -1 +1 @@
-{"version":3,"file":"LLMGateway.js","sourceRoot":"","sources":["../src/LLMGateway.ts"],"names":[],"mappings":";;;AAMA,6DAAyD;AAGzD,uDAOgC;AAMhC;;;;GAIG;AACH,MAAa,UAAU;IACJ,MAAM,CAAmB;IAEzB,qBAAqB,CAAgC;IAEtE,YAAY,UAA6B,EAAE;QACzC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,iCAAoB,CAAC;QACrD,IAAI,CAAC,qBAAqB;cACtB,OAAO,CAAC,qBAAqB,IAAI,sCAAyB,CAAC;IACjE,CAAC;IAED,oBAAoB,CAIlB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,oBAAoB,CAIlB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,sBAAsB,CAIpB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,sBAAsB,CAIpB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,SAAS,CACP,IAAY,EACZ,OAAwB,EACxB,EAAyB;QAEzB,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED,kBAAkB,CAAC,UAA4C;QAC7D,IAAI,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAEO,MAAM,CAAmC,OAAgB;QAC/D,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEhC,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AA/ED,gCA+EC"}
+{"version":3,"file":"LLMGateway.js","sourceRoot":"","sources":["../src/LLMGateway.ts"],"names":[],"mappings":";;;AAMA,6DAAyD;AAGzD,uDAOgC;AAMhC;;;;GAIG;AACH,MAAa,UAAU;IACJ,MAAM,CAAmB;IAEzB,qBAAqB,CAA2B;IAEjE,YAAY,UAA6B,EAAE;QACzC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,iCAAoB,CAAC;QACrD,IAAI,CAAC,qBAAqB;cACtB,OAAO,CAAC,qBAAqB,IAAI,sCAAyB,CAAC;IACjE,CAAC;IAED,oBAAoB,CAIlB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,oBAAoB,CAIlB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,sBAAsB,CAIpB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,sBAAsB,CAIpB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,SAAS,CACP,IAAY,EACZ,OAAwB,EACxB,EAAyB;QAEzB,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED,kBAAkB,CAAC,UAAuC;QACxD,IAAI,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAEO,MAAM,CAAmC,OAAgB;QAC/D,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEhC,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AA/ED,gCA+EC"}

package/dist/LLMGateway.typedefs.d.ts

@@ -1,5 +1,5 @@
-import { type LangfuseFallbackMetricEmitter, type LLMGatewayTracer } from './utilities/llmTracing';
+import { type LLMFallbackMetricEmitter, type LLMGatewayTracer } from './utilities/llmTracing';
 export interface LLMGatewayOptions {
     tracer?: LLMGatewayTracer;
-    fallbackMetricEmitter?: LangfuseFallbackMetricEmitter;
+    fallbackMetricEmitter?: LLMFallbackMetricEmitter;
 }

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;
+}