@mate-academy/llm-gateway 8.8.2 → 8.8.3

package/dist/client/createLLMClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createLLMClient.js","sourceRoot":"","sources":["../../src/client/createLLMClient.ts"],"names":[],"mappings":";;AAkBA,0CA2CC;AA5DD,8DAA2D;AAC3D,4EAAwE;AACxE,oEAMqC;AAErC;;;;;;GAMG;AACH,SAAgB,eAAe,CAK7B,MAAwD;IAExD,MAAM,IAAI,GAAkB,MAAM,CAAC,IAAI,IAAI,YAAY,CAAC;IACxD,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,KAAK,sCAAiB;QACtD,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;IAErB,MAAM,OAAO,GAAG,IAAI,8CAAqB,CAAC;QACxC,qBAAqB,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,CACrC,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAC9C;QACD,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,YAAY;QACjD,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,iCAAe,CAAC;QACjC,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,OAAO;QACP,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,QAAQ,EAAE,SAAS,EAAE,QAAQ;QAC7B,oBAAoB,EAAE,SAAS,EAAE,YAAY;QAC7C,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,aAAa,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;QACnC,IAAI;QACJ,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;KAChD,CAAC,CAAC;IAEH,OAAO;QACL,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAC/D,WAAW,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC;QACrE,WAAW,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC;QAC3D,QAAQ,EAAE,CAAC,aAAa,EAAE,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;QAC7E,cAAc,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC;KACtB,CAAC;AACxC,CAAC"}

package/dist/client/defineLLMPrompts.d.ts

@@ -0,0 +1,34 @@
+import { type LLMSchemaInterface } from '../utilities/schema';
+import { type LLMModelCapabilities } from '../LLMService.typedefs';
+import { type LLMPromptKind } from '../client/promptSnapshot.typedefs';
+/**
+ * A capability the resolved model must support for a prompt. Mirrors the boolean
+ * flags on `LLMModelCapabilities`, so the gate can check each requirement
+ * against the model map without a separate mapping.
+ */
+export type LLMCapabilityRequirement = keyof Pick<LLMModelCapabilities, 'vision' | 'tools' | 'reasoning' | 'webSearch' | 'jsonOutput' | 'structuredOutputs' | 'tts' | 'stt' | 'multimodalToolResults'>;
+/**
+ * The code-owned contract for one prompt. `schema` drives structured output and
+ * the `generate` return type; `toolSchemas` carry tool name+parameter shapes for
+ * typing/capability validation (executable tools are always passed per call);
+ * `requires` lists capabilities the resolved model must satisfy; `kind`
+ * distinguishes config-only audio prompts; `variables` is the code-owned list
+ * of required input names for this prompt. The client derives each call site's
+ * `variables` type from this list, independently of the prompt body stored in
+ * Langfuse.
+ */
+export interface LLMPromptBinding<Schema extends LLMSchemaInterface = LLMSchemaInterface> {
+    schema?: Schema;
+    toolSchemas?: Record<string, LLMSchemaInterface>;
+    requires?: LLMCapabilityRequirement[];
+    kind?: LLMPromptKind | 'transcription' | 'speech';
+    variables?: readonly string[];
+}
+export type LLMPromptRegistry = Record<string, LLMPromptBinding>;
+/**
+ * Binds each `LLMPrompt` member (the generated enum) to its code contract. The
+ * identity return preserves the literal binding types so `createLLMClient` can
+ * infer per-prompt variables and return types from `typeof registry` — bind the
+ * registry once at the composition root, never via module augmentation.
+ */
+export declare function defineLLMPrompts<const Registry extends LLMPromptRegistry>(registry: Registry): Registry;

package/dist/client/defineLLMPrompts.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineLLMPrompts = defineLLMPrompts;
+/**
+ * Binds each `LLMPrompt` member (the generated enum) to its code contract. The
+ * identity return preserves the literal binding types so `createLLMClient` can
+ * infer per-prompt variables and return types from `typeof registry` — bind the
+ * registry once at the composition root, never via module augmentation.
+ */
+function defineLLMPrompts(registry) {
+    return registry;
+}
+//# sourceMappingURL=defineLLMPrompts.js.map

package/dist/client/defineLLMPrompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineLLMPrompts.js","sourceRoot":"","sources":["../../src/client/defineLLMPrompts.ts"],"names":[],"mappings":";;AAkDA,4CAIC;AAVD;;;;;GAKG;AACH,SAAgB,gBAAgB,CAC9B,QAAkB;IAElB,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/client/errors.d.ts

@@ -0,0 +1,57 @@
+import { type LLMProviders } from '../LLMService.typedefs';
+export interface LLMGatewayErrorContext {
+    promptName: string;
+    provider?: LLMProviders;
+    model?: string;
+    cause?: unknown;
+}
+/**
+ * Base class for every error the v2 client throws. Carries the prompt name plus
+ * the resolved provider/model so callers can attribute a failure to one
+ * operation without inspecting the cause chain.
+ */
+export declare class LLMGatewayError extends Error {
+    readonly promptName: string;
+    readonly provider: LLMProviders | undefined;
+    readonly model: string | undefined;
+    constructor(message: string, context: LLMGatewayErrorContext);
+}
+/**
+ * Upstream provider failure. `retryable` is true when the v2 retry policy may
+ * re-attempt the request (timeouts, 5xx, rate limits); false for deterministic
+ * provider rejections (malformed request, auth).
+ */
+export declare class LLMProviderError extends LLMGatewayError {
+    readonly retryable: boolean;
+    readonly status: number | null;
+    constructor(message: string, context: LLMGatewayErrorContext & {
+        retryable: boolean;
+        status?: number | null;
+    });
+}
+/**
+ * The model returned text that failed schema validation after the internal
+ * JSON-fixer retry. `rawText` is the unparsed completion and `parseDetails`
+ * the validator message, so a caller can attempt its own recovery.
+ */
+export declare class LLMSchemaValidationError extends LLMGatewayError {
+    readonly rawText: string;
+    readonly parseDetails: string;
+    constructor(message: string, context: LLMGatewayErrorContext & {
+        rawText: string;
+        parseDetails: string;
+    });
+}
+/**
+ * The call was aborted via its `AbortSignal` before completion.
+ */
+export declare class LLMAbortedError extends LLMGatewayError {
+}
+/**
+ * Configuration could not be resolved into a usable call: live config and the
+ * fallback snapshot are both unusable, or per-call overrides were passed to a
+ * production-mode client.
+ */
+export declare class LLMConfigError extends LLMGatewayError {
+}
+export declare function isLLMGatewayError(error: unknown): error is LLMGatewayError;

package/dist/client/errors.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMConfigError = exports.LLMAbortedError = exports.LLMSchemaValidationError = exports.LLMProviderError = exports.LLMGatewayError = void 0;
+exports.isLLMGatewayError = isLLMGatewayError;
+/**
+ * Base class for every error the v2 client throws. Carries the prompt name plus
+ * the resolved provider/model so callers can attribute a failure to one
+ * operation without inspecting the cause chain.
+ */
+class LLMGatewayError extends Error {
+    promptName;
+    provider;
+    model;
+    constructor(message, context) {
+        super(message, { cause: context.cause });
+        this.name = new.target.name;
+        this.promptName = context.promptName;
+        this.provider = context.provider;
+        this.model = context.model;
+    }
+}
+exports.LLMGatewayError = LLMGatewayError;
+/**
+ * Upstream provider failure. `retryable` is true when the v2 retry policy may
+ * re-attempt the request (timeouts, 5xx, rate limits); false for deterministic
+ * provider rejections (malformed request, auth).
+ */
+class LLMProviderError extends LLMGatewayError {
+    retryable;
+    status;
+    constructor(message, context) {
+        super(message, context);
+        this.retryable = context.retryable;
+        this.status = context.status ?? null;
+    }
+}
+exports.LLMProviderError = LLMProviderError;
+/**
+ * The model returned text that failed schema validation after the internal
+ * JSON-fixer retry. `rawText` is the unparsed completion and `parseDetails`
+ * the validator message, so a caller can attempt its own recovery.
+ */
+class LLMSchemaValidationError extends LLMGatewayError {
+    rawText;
+    parseDetails;
+    constructor(message, context) {
+        super(message, context);
+        this.rawText = context.rawText;
+        this.parseDetails = context.parseDetails;
+    }
+}
+exports.LLMSchemaValidationError = LLMSchemaValidationError;
+/**
+ * The call was aborted via its `AbortSignal` before completion.
+ */
+class LLMAbortedError extends LLMGatewayError {
+}
+exports.LLMAbortedError = LLMAbortedError;
+/**
+ * Configuration could not be resolved into a usable call: live config and the
+ * fallback snapshot are both unusable, or per-call overrides were passed to a
+ * production-mode client.
+ */
+class LLMConfigError extends LLMGatewayError {
+}
+exports.LLMConfigError = LLMConfigError;
+function isLLMGatewayError(error) {
+    return error instanceof LLMGatewayError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/client/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":";;;AAqFA,8CAEC;AA9ED;;;;GAIG;AACH,MAAa,eAAgB,SAAQ,KAAK;IAC/B,UAAU,CAAS;IAEnB,QAAQ,CAA2B;IAEnC,KAAK,CAAqB;IAEnC,YAAY,OAAe,EAAE,OAA+B;QAC1D,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QAEzC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;CACF;AAfD,0CAeC;AAED;;;;GAIG;AACH,MAAa,gBAAiB,SAAQ,eAAe;IAC1C,SAAS,CAAU;IAEnB,MAAM,CAAgB;IAE/B,YACE,OAAe,EACf,OAAgF;QAEhF,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAExB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACvC,CAAC;CACF;AAdD,4CAcC;AAED;;;;GAIG;AACH,MAAa,wBAAyB,SAAQ,eAAe;IAClD,OAAO,CAAS;IAEhB,YAAY,CAAS;IAE9B,YACE,OAAe,EACf,OAA2E;QAE3E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAExB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC3C,CAAC;CACF;AAdD,4DAcC;AAED;;GAEG;AACH,MAAa,eAAgB,SAAQ,eAAe;CAAG;AAAvD,0CAAuD;AAEvD;;;;GAIG;AACH,MAAa,cAAe,SAAQ,eAAe;CAAG;AAAtD,wCAAsD;AAEtD,SAAgB,iBAAiB,CAAC,KAAc;IAC9C,OAAO,KAAK,YAAY,eAAe,CAAC;AAC1C,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,13 @@
+export * from './errors';
+export * from './llmConfig.schema';
+export * from './promptSnapshot.typedefs';
+export * from './snapshotRuntime.typedefs';
+export * from './snapshotRuntime';
+export * from './promptClientPort.typedefs';
+export * from './defineLLMPrompts';
+export * from './validationGate';
+export * from './promptRegistry.runtime';
+export * from './llmClient.typedefs';
+export * from './createLLMClient';
+export * from './agentRun.typedefs';
+export * from './LLMAgent';

package/dist/client/index.js

@@ -0,0 +1,30 @@
+"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 });
+__exportStar(require("./errors"), exports);
+__exportStar(require("./llmConfig.schema"), exports);
+__exportStar(require("./promptSnapshot.typedefs"), exports);
+__exportStar(require("./snapshotRuntime.typedefs"), exports);
+__exportStar(require("./snapshotRuntime"), exports);
+__exportStar(require("./promptClientPort.typedefs"), exports);
+__exportStar(require("./defineLLMPrompts"), exports);
+__exportStar(require("./validationGate"), exports);
+__exportStar(require("./promptRegistry.runtime"), exports);
+__exportStar(require("./llmClient.typedefs"), exports);
+__exportStar(require("./createLLMClient"), exports);
+__exportStar(require("./agentRun.typedefs"), exports);
+__exportStar(require("./LLMAgent"), exports);
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,qDAAmC;AACnC,4DAA0C;AAC1C,6DAA2C;AAC3C,oDAAkC;AAClC,8DAA4C;AAC5C,qDAAmC;AACnC,mDAAiC;AACjC,2DAAyC;AACzC,uDAAqC;AACrC,oDAAkC;AAClC,sDAAoC;AACpC,6CAA2B"}

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

@@ -0,0 +1,265 @@
+import { type LLMInstanceOptions, type LLMProviders, type LLMToolGateResult, type LLMToolResult } from '../LLMService.typedefs';
+import { type LLMGateway } from '../LLMGateway';
+import { type LLMLoggerInterface } from '../utilities/logger';
+import { type LLMReporterInterface } from '../utilities/reporter';
+import { type InferSchema, type LLMSchemaInterface } from '../utilities/schema';
+import { type LLMTraceContext } from '../utilities/llmTracing/llmTracing.typedefs';
+import { type LLMGatewayPromptClient } from '../client/promptClientPort.typedefs';
+import { type LLMPromptBinding, type LLMPromptRegistry } from '../client/defineLLMPrompts';
+import { type LLMPromptSnapshot, type LLMVariableValue } from '../client/promptSnapshot.typedefs';
+import { type PromptRegistryRuntime, type ResolvedPrompt } from '../client/promptRegistry.runtime';
+import { type LLMAgent, type LLMAgentDefinition } from '../client/LLMAgent';
+import { type LLMAgentInlineRunOptions, type LLMAgentRunOptions, type LLMAgentRunResult } from '../client/agentRun.typedefs';
+export type LLMClientMode = 'production' | 'experiment';
+/**
+ * The explicit opt-out for the reporter pipeline; unlike tracing/prompts,
+ * reporting has no safe silent default, so tests must opt out loudly. Passed
+ * where `reporting` is expected to disable the Reporter/DWHSync wiring (tests,
+ * scripts).
+ */
+export declare const ReportingDisabled: unique symbol;
+export type ReportingDisabledToken = typeof ReportingDisabled;
+/**
+ * Resolves provider credentials for one call, scoped by provider + prompt +
+ * product, preserving the existing per-feature Secrets Manager layout.
+ */
+export type LLMCredentialsResolver = <Provider extends LLMProviders>(scope: {
+    provider: Provider;
+    promptName: string;
+    product?: string;
+}) => Promise<LLMInstanceOptions[Provider]>;
+export interface LLMClientStaticContext {
+    product?: string;
+    appEnvironment?: string;
+    [key: string]: string | undefined;
+}
+export interface LLMClientCallContext {
+    userId?: string | number | null;
+    /**
+     * The product this one call belongs to, when the caller knows it better than
+     * the client does. A client is built once per process, so its static context
+     * can only carry the product of whatever built it — the request host, or
+     * nothing at all on a message-bus or WebSocket entry point. A call site that
+     * resolves the product from its own subject (the user's domain, say) passes
+     * it here, and it wins over the static one for both credentials resolution
+     * and the reporter's payload.
+     */
+    product?: string;
+    [key: string]: string | number | boolean | null | undefined;
+}
+/**
+ * What the client knows about one call when it asks the composition root to
+ * build the reporter's context: the resolved prompt, the per-call context the
+ * feature passed, the static context the client was built with, and the context
+ * of the trace scope the call runs inside.
+ */
+export interface LLMReporterContextScope {
+    promptName: string;
+    promptVersion: number;
+    callContext: LLMClientCallContext | undefined;
+    staticContext: LLMClientStaticContext;
+    /**
+     * What the surrounding operation declared when it opened its trace scope, or
+     * `undefined` outside a scope. It is the reporter's level-1 context: a call
+     * that names nothing of its own still belongs to a user and a session, and
+     * this is where the composition root reads them from.
+     */
+    scopeContext: LLMTraceContext | undefined;
+}
+/**
+ * What building the per-call trace context needs: the resolved prompt, the
+ * per-call context, and the typed Langfuse trace fields the call site supplied.
+ */
+export interface LLMTraceContextScope {
+    resolved: ResolvedPrompt;
+    callContext: LLMClientCallContext | undefined;
+    sessionId: string | undefined;
+    traceTags: string[] | undefined;
+}
+export interface LLMReportingConfig<Context extends Record<string, any> = Record<string, any>> {
+    reporter: LLMReporterInterface<Context>;
+    /**
+     * Builds the reporter's own context for one call. Required, and owned by the
+     * composition root on purpose: the reporter's payload is a downstream
+     * contract (DWH columns, dashboards built on their exact values), and the
+     * gateway must never guess its shape or invent its strings. The client
+     * supplies only what it knows — the resolved prompt and the contexts it was
+     * given — and the application maps that onto its own typed context.
+     */
+    buildContext: (scope: LLMReporterContextScope) => Context;
+}
+/**
+ * What building a provider service for one call needs: the resolved prompt and
+ * the context that decides whose credentials the provider is built with.
+ */
+export interface LLMProviderServiceScope {
+    resolved: ResolvedPrompt;
+    callContext: LLMClientCallContext | undefined;
+}
+/**
+ * One tool call's outcome, as it stands before the client hands it to the
+ * model. `tool` is the tool (or subagent delegation) name, `agent` the run that
+ * called it, `input` the arguments the model supplied, and `result` the value
+ * the tool returned after the package's own coercion.
+ */
+export interface LLMToolResultContext {
+    tool: string;
+    agent: string;
+    input: unknown;
+    result: LLMToolResult;
+}
+/**
+ * A client-wide hook that rewrites every tool result before it reaches the
+ * model. It runs after the package coerces the raw return value, so it always
+ * receives a well-formed result; its own return is coerced again. Use it to
+ * apply one truncation, redaction, or envelope policy across every tool
+ * instead of repeating it in each `execute`.
+ */
+export type LLMToolResultNormalizer = (context: LLMToolResultContext) => LLMToolResult;
+/**
+ * The precondition a delegation tool may declare, checked before the subagent
+ * starts. The `subagents` list erases the input schema's generic, so the
+ * arguments arrive untyped here: they are the subagent's `inputSchema` shape
+ * when it declares one, and `{ prompt }` otherwise.
+ */
+export type LLMDelegationGate = (args: Record<string, unknown>) => Promise<LLMToolGateResult> | LLMToolGateResult;
+/**
+ * `ReporterContext` ties the reporter to the mapper that feeds it: declare it
+ * and a `LLMReporterInterface<T>` forces `buildContext` to return exactly `T`,
+ * so a mapper that drops or mistypes a DWH column fails the build instead of
+ * corrupting a dashboard. It is inferred from `reporting` when the call site
+ * passes no explicit type arguments; TypeScript has no partial inference, so a
+ * call site that spells out `Registry`/`VariableMap` must spell this out too.
+ * The factory defaults it to `never`, so a partially explicit call cannot
+ * silently fall back to an unchecked reporter context.
+ */
+export interface CreateLLMClientConfig<Registry extends LLMPromptRegistry, ReporterContext extends Record<string, any> = Record<string, any>> {
+    gateway: LLMGateway;
+    registry: Registry;
+    snapshot: LLMPromptSnapshot;
+    credentials: LLMCredentialsResolver;
+    reporting: LLMReportingConfig<ReporterContext> | ReportingDisabledToken;
+    logger?: LLMLoggerInterface;
+    context?: LLMClientStaticContext;
+    mode?: LLMClientMode;
+    promptClient?: LLMGatewayPromptClient;
+    defaultLabel?: string;
+    cacheTtlSeconds?: number;
+    normalizeToolResult?: LLMToolResultNormalizer;
+}
+export interface LLMClientEngineConfig<Registry extends LLMPromptRegistry> {
+    gateway: LLMGateway;
+    registry: Registry;
+    runtime: PromptRegistryRuntime;
+    credentials: LLMCredentialsResolver;
+    reporter: LLMReporterInterface<any> | undefined;
+    buildReporterContext: ((scope: LLMReporterContextScope) => unknown) | undefined;
+    logger: LLMLoggerInterface | undefined;
+    staticContext: LLMClientStaticContext;
+    mode: LLMClientMode;
+    normalizeToolResult: LLMToolResultNormalizer | undefined;
+}
+/**
+ * The variables a prompt requires. Required keys come exclusively from the
+ * code-owned prompt registry. Extras remain tolerated so callers can migrate a
+ * variable in more than one deployment.
+ */
+export type LLMPromptVariables<RequiredKeys extends string> = Record<RequiredKeys, LLMVariableValue> & Record<string, LLMVariableValue>;
+/**
+ * Where a subagent's prompt variables come from. Without an `inputSchema` the
+ * parent model supplies only a task string, so the definition must carry every
+ * variable the prompt requires. With one, the model fills the rest at call
+ * time — the definition's own variables become a partial base and the runtime
+ * validation gate is what proves the set complete.
+ */
+export type LLMSubagentVariableSource<RequiredKeys extends string> = {
+    inputSchema?: undefined;
+    variables: LLMPromptVariables<RequiredKeys>;
+} | {
+    inputSchema: LLMSchemaInterface;
+    variables?: Partial<LLMPromptVariables<RequiredKeys>>;
+};
+/**
+ * The return type of `generate` for one prompt: the bound schema's inferred type
+ * when a schema is present, else the raw completion string.
+ */
+export type LLMGenerateResult<Binding extends LLMPromptBinding> = Binding extends {
+    schema: infer Schema;
+} ? Schema extends LLMSchemaInterface ? InferSchema<Schema> : string : string;
+export interface LLMGenerateOptions<Variables extends Record<string, LLMVariableValue>, Schema extends LLMSchemaInterface = never> {
+    variables: Variables;
+    context?: LLMClientCallContext;
+    history?: LLMPlainMessage[];
+    abortSignal?: AbortSignal;
+    overrides?: LLMCallOverrides;
+    /**
+     * Groups the traces of one conversation, review, or agent run into a single
+     * Langfuse session. It is a typed Langfuse trace field, not metadata, so it
+     * never reaches the reporter's payload. Top level rather than nested under a
+     * trace object because a session is understandable without knowing what a
+     * trace is. Keep the anchor stable — changing it splits a session's history
+     * in two.
+     */
+    sessionId?: string;
+    /**
+     * Langfuse trace tags. Typed Langfuse trace fields, not metadata. The `trace`
+     * prefix is deliberate: a bare `tags` says nothing about which system reads
+     * them.
+     */
+    traceTags?: string[];
+    /**
+     * Per-call structured-output schema. Overrides the registry binding's `schema`
+     * for this call and drives the return type (`InferSchema<Schema>`). Use it when
+     * the output contract is dynamic per call (e.g. a schema whose shape depends on
+     * runtime input). The schema is the code-owned output contract, not a routing
+     * control, so it is honored in every mode.
+     */
+    schema?: Schema;
+}
+export interface LLMCallOverrides {
+    model?: string;
+    provider?: LLMProviders;
+    promptVersion?: number;
+    promptLabel?: string;
+}
+export type LLMPlainMessageRole = 'user' | 'assistant';
+export interface LLMPlainMessage {
+    role: LLMPlainMessageRole;
+    text: string;
+}
+/**
+ * Maps each registry key to the union of variable names declared by code. The
+ * Langfuse prompt body and generated fallback snapshot do not participate in
+ * call-site typing.
+ */
+export type LLMPromptVariableMap<Registry extends LLMPromptRegistry> = {
+    [Key in keyof Registry]: Registry[Key] extends {
+        variables: readonly (infer VariableName extends string)[];
+    } ? VariableName : never;
+};
+export interface LLMClient<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string> = LLMPromptVariableMap<Registry>> {
+    generate<Key extends keyof Registry, Schema extends LLMSchemaInterface = never>(prompt: Key, options: LLMGenerateOptions<Record<VariableMap[Key], LLMVariableValue> & Record<string, LLMVariableValue>, Schema>): Promise<[
+        Schema
+    ] extends [never] ? LLMGenerateResult<Registry[Key]> : InferSchema<Schema>>;
+    countTokens<Key extends keyof Registry>(prompt: Key, options: {
+        variables: Record<string, LLMVariableValue>;
+        history?: LLMPlainMessage[];
+    }): Promise<number>;
+    defineAgent<Key extends keyof Registry>(definition: LLMAgentDefinition<Registry, VariableMap, Key>): LLMAgent<Registry, VariableMap, Key>;
+    runAgent<Key extends keyof Registry>(prompt: Key, options: LLMAgentInlineRunOptions<Record<VariableMap[Key], LLMVariableValue> & Record<string, LLMVariableValue>, Registry, VariableMap>): Promise<LLMAgentRunResult<LLMGenerateResult<Registry[Key]>>>;
+    runAgent<Key extends keyof Registry>(agent: LLMAgent<Registry, VariableMap, Key>, options: LLMAgentRunOptions<Record<VariableMap[Key], LLMVariableValue> & Record<string, LLMVariableValue>>): Promise<LLMAgentRunResult<LLMGenerateResult<Registry[Key]>>>;
+    describePrompt<Key extends keyof Registry>(prompt: Key): Promise<LLMPromptDescription>;
+}
+/**
+ * Read-only routing metadata for a prompt — the `{ provider, model,
+ * promptVersion }` the runtime would serve right now (same resolve/cache/fallback
+ * path `generate` uses). Lets analytics events record the resolved model without
+ * coupling to `generate`'s data-only return. `isFallback` flags the snapshot
+ * config was used because the live fetch was unreachable or failed the gate.
+ */
+export interface LLMPromptDescription {
+    provider: LLMProviders;
+    model: string;
+    promptVersion: number;
+    isFallback: boolean;
+}

package/dist/client/llmClient.typedefs.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReportingDisabled = void 0;
+/**
+ * The explicit opt-out for the reporter pipeline; unlike tracing/prompts,
+ * reporting has no safe silent default, so tests must opt out loudly. Passed
+ * where `reporting` is expected to disable the Reporter/DWHSync wiring (tests,
+ * scripts).
+ */
+exports.ReportingDisabled = Symbol('ReportingDisabled');
+//# sourceMappingURL=llmClient.typedefs.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llmClient.typedefs.js","sourceRoot":"","sources":["../../src/client/llmClient.typedefs.ts"],"names":[],"mappings":";;;AAiCA;;;;;GAKG;AACU,QAAA,iBAAiB,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC"}

package/dist/client/llmConfig.schema.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { LLMProviders } from '../LLMService.typedefs';
+/**
+ * Hard ceilings the runtime gate enforces on every prompt `config`, independent
+ * of provider. A live edit that exceeds one of these never reaches production
+ * traffic; the gate serves the fallback snapshot instead.
+ */
+export declare const LLM_CONFIG_PARAM_CEILINGS: {
+    readonly maxOutputTokens: 32768;
+    readonly temperature: {
+        readonly min: 0;
+        readonly max: 2;
+    };
+    readonly topP: {
+        readonly min: 0;
+        readonly max: 1;
+    };
+};
+export declare const REASONING_EFFORT_VALUES: readonly ["minimal", "low", "medium", "high"];
+export declare const llmConfigParamsSchema: z.ZodObject<{
+    temperature: z.ZodOptional<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningEffort: z.ZodOptional<z.ZodEnum<{
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>>;
+}, z.core.$loose>;
+/**
+ * The gateway-owned shape of a prompt's `config`. The provider routes the call;
+ * `model` is checked against `LLM_SERVICE_MODELS` by the runtime gate (a string
+ * here because the snapshot is provider-agnostic); `params` are the generation
+ * knobs, capped by `LLM_CONFIG_PARAM_CEILINGS`.
+ */
+export declare const llmPromptConfigSchema: z.ZodObject<{
+    provider: z.ZodEnum<typeof LLMProviders>;
+    model: z.ZodString;
+    params: z.ZodOptional<z.ZodObject<{
+        temperature: z.ZodOptional<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+        reasoningEffort: z.ZodOptional<z.ZodEnum<{
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export type LLMPromptConfig = z.infer<typeof llmPromptConfigSchema>;
+export type LLMPromptConfigParams = z.infer<typeof llmConfigParamsSchema>;

package/dist/client/llmConfig.schema.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.llmPromptConfigSchema = exports.llmConfigParamsSchema = exports.REASONING_EFFORT_VALUES = exports.LLM_CONFIG_PARAM_CEILINGS = void 0;
+const zod_1 = require("zod");
+const LLMService_typedefs_1 = require("../LLMService.typedefs");
+/**
+ * Hard ceilings the runtime gate enforces on every prompt `config`, independent
+ * of provider. A live edit that exceeds one of these never reaches production
+ * traffic; the gate serves the fallback snapshot instead.
+ */
+exports.LLM_CONFIG_PARAM_CEILINGS = {
+    maxOutputTokens: 32_768,
+    temperature: { min: 0, max: 2 },
+    topP: { min: 0, max: 1 },
+};
+exports.REASONING_EFFORT_VALUES = ['minimal', 'low', 'medium', 'high'];
+exports.llmConfigParamsSchema = zod_1.z
+    .object({
+    temperature: zod_1.z
+        .number()
+        .min(exports.LLM_CONFIG_PARAM_CEILINGS.temperature.min)
+        .max(exports.LLM_CONFIG_PARAM_CEILINGS.temperature.max)
+        .optional(),
+    topP: zod_1.z
+        .number()
+        .min(exports.LLM_CONFIG_PARAM_CEILINGS.topP.min)
+        .max(exports.LLM_CONFIG_PARAM_CEILINGS.topP.max)
+        .optional(),
+    maxOutputTokens: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .max(exports.LLM_CONFIG_PARAM_CEILINGS.maxOutputTokens)
+        .optional(),
+    reasoningEffort: zod_1.z.enum(exports.REASONING_EFFORT_VALUES).optional(),
+})
+    .passthrough();
+/**
+ * The gateway-owned shape of a prompt's `config`. The provider routes the call;
+ * `model` is checked against `LLM_SERVICE_MODELS` by the runtime gate (a string
+ * here because the snapshot is provider-agnostic); `params` are the generation
+ * knobs, capped by `LLM_CONFIG_PARAM_CEILINGS`.
+ */
+exports.llmPromptConfigSchema = zod_1.z.object({
+    provider: zod_1.z.nativeEnum(LLMService_typedefs_1.LLMProviders),
+    model: zod_1.z.string().min(1),
+    params: exports.llmConfigParamsSchema.optional(),
+});
+//# sourceMappingURL=llmConfig.schema.js.map

package/dist/client/llmConfig.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmConfig.schema.js","sourceRoot":"","sources":["../../src/client/llmConfig.schema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,+DAAqD;AAErD;;;;GAIG;AACU,QAAA,yBAAyB,GAAG;IACvC,eAAe,EAAE,MAAM;IACvB,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;IAC/B,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;CAChB,CAAC;AAEE,QAAA,uBAAuB,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAExE,QAAA,qBAAqB,GAAG,OAAC;KACnC,MAAM,CAAC;IACN,WAAW,EAAE,OAAC;SACX,MAAM,EAAE;SACR,GAAG,CAAC,iCAAyB,CAAC,WAAW,CAAC,GAAG,CAAC;SAC9C,GAAG,CAAC,iCAAyB,CAAC,WAAW,CAAC,GAAG,CAAC;SAC9C,QAAQ,EAAE;IACb,IAAI,EAAE,OAAC;SACJ,MAAM,EAAE;SACR,GAAG,CAAC,iCAAyB,CAAC,IAAI,CAAC,GAAG,CAAC;SACvC,GAAG,CAAC,iCAAyB,CAAC,IAAI,CAAC,GAAG,CAAC;SACvC,QAAQ,EAAE;IACb,eAAe,EAAE,OAAC;SACf,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,GAAG,CAAC,iCAAyB,CAAC,eAAe,CAAC;SAC9C,QAAQ,EAAE;IACb,eAAe,EAAE,OAAC,CAAC,IAAI,CAAC,+BAAuB,CAAC,CAAC,QAAQ,EAAE;CAC5D,CAAC;KACD,WAAW,EAAE,CAAC;AAEjB;;;;;GAKG;AACU,QAAA,qBAAqB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,OAAC,CAAC,UAAU,CAAC,kCAAY,CAAC;IACpC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,MAAM,EAAE,6BAAqB,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAC"}

package/dist/client/plainMessages.d.ts

@@ -0,0 +1,12 @@
+import { LLMRoles, type LLMMessageTextContent } from '../LLMService.typedefs';
+import { type LLMPlainMessage } from '../client/llmClient.typedefs';
+export interface LLMPlainTextContentMessage {
+    role: LLMRoles;
+    content: LLMMessageTextContent[];
+}
+/**
+ * Maps the client's persisted plain-message history into the gateway's
+ * content-message shape. The single mapper both `generate` and `runAgent` use,
+ * so a persisted session replays identically through either surface.
+ */
+export declare function plainMessagesToContentMessages(history: LLMPlainMessage[] | undefined): LLMPlainTextContentMessage[];