@axiom-lattice/gateway 7.0.0 → 8.0.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as http from 'http';
-import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ModelProviderStore, UserTenantLinkStore, LLMConfig, ModelProviderPublicEntry, TenantModelCatalog, CreateModelProviderRequest, UpdateModelProviderRequest, ModelDiscoveryResult, ModelProviderProbeRequest, ModelProviderProbeResult, ModelSelection, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, Thread, ProjectRoom, ProjectStore, Project, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LeaseStore, CheckpointMaintenance, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
-import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, AgentRunJsonObject, TrustedRunContext, AgentRunRecord, TaskLifecycleService, IAgentRunLedger, AppendLog, TaskLivenessProbe, TaskRunRegistry, AgentLifecycleTapEvent, AgentLifecycleEventName, AgentThreadInterface, AgentCheckpointTip, ExecuteRunInput, ExecuteRunResult, AgentRunSource, AgentRunStatus, ThreadRunLeaseHandle } from '@axiom-lattice/core';
+import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ModelProviderStore, UserTenantLinkStore, LLMConfig, ModelProviderPublicEntry, TenantModelCatalog, CreateModelProviderRequest, UpdateModelProviderRequest, ModelDiscoveryResult, ModelProviderProbeRequest, ModelProviderProbeResult, ModelSelection, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, Thread, ProjectRoom, ProjectStore, Project, ObservabilityDashboardInput, ObservabilityDashboardResult, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LeaseStore, CheckpointMaintenance, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, AgentRunJsonObject, TrustedRunContext, AgentRunRecord, TaskLifecycleService, IAgentRunLedger, ObservabilityProvider, ObservabilityTraceContext, AppendLog, TaskLivenessProbe, TaskRunRegistry, AgentLifecycleTapEvent, AgentLifecycleEventName, AgentThreadInterface, AgentCheckpointTip, ExecuteRunInput, ExecuteRunResult, AgentRunSource, AgentRunStatus, ThreadRunLeaseHandle } from '@axiom-lattice/core';
 export { TaskLivenessProbe } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
 import { RouteGenericInterface, FastifyRequest, FastifyReply, FastifyInstance } from 'fastify';
@@ -363,24 +363,32 @@ declare class ModelProviderService {
      */
     setModels(userId: string | undefined, tenantId: string, id: string, selection: ModelSelection[]): Promise<ModelProviderPublicEntry>;
     /**
-     * Give a tenant's sole **chat** model the default flag.
+     * Give each kind's sole model its default flag.
      *
-     * A tenant with exactly one runnable chat model has an obvious default, and
-     * saying so is what keeps the invariant the rest of the feature leans on: a
-     * tenant either has no chat model at all — and falls back to the deployment's
-     * default — or has a default, which cannot be deleted. Without this a tenant
-     * could sit with one model and no default, and deleting that model would
-     * leave nothing behind.
+     * A tenant with exactly one runnable model **of a kind** has an obvious
+     * default for that kind, and saying so keeps the invariant the rest of the
+     * feature leans on: a kind either has no model at all — and falls back to the
+     * deployment's default — or has a default, which cannot be deleted.
      *
-     * Chat only: a bare `"default"` key resolves to a chat client, so an
-     * embedding or ASR row must never be marked as one.
+     * Per kind because each kind publishes its own alias key (`default`,
+     * `default:embedding`, `default:asr`).
      *
-     * Deliberately narrow: more than one model is the tenant's choice to make,
-     * and a disabled model is not a candidate for "the model this tenant runs".
+     * Deliberately narrow: more than one model of a kind is the tenant's choice to
+     * make, and a disabled model is not a candidate.
      *
      * @param tenantId - The tenant whose model set just changed
      */
     private ensureDefaultModel;
+    /**
+     * Persist the embedding shape a probe detected.
+     *
+     * A probe is read-only except for this: when the initial shape fails with
+     * 400/404 and another shape works, writing it down is what makes the
+     * runtime use it. The whole provider set is written because
+     * `replaceProviderModels` replaces it — passing one row would delete its
+     * siblings.
+     */
+    private persistEmbeddingShape;
     private syncRegistry;
     /** Best-effort local mutation notification; never affects the operation. */
     private notifyChanged;
@@ -1488,6 +1496,121 @@ interface LifespanLogger {
  */
 declare function installLifespanHooks(app: FastifyInstance, lifespans?: GatewayLifespan | GatewayLifespan[], log?: LifespanLogger): void;
 
+/** Environment-driven configuration for the built-in Langfuse provider. */
+interface LangfuseConfig {
+    publicKey: string;
+    secretKey: string;
+    baseUrl: string;
+    uiUrl: string;
+    release?: string;
+    environment?: string;
+    sampleRate: number;
+}
+/** Best-effort logger for provider lifecycle failures. */
+interface LangfuseProviderLogger {
+    /**
+     * @param message - Stable diagnostic message.
+     * @param error - The contained failure.
+     */
+    warn(message: string, error?: unknown): void;
+}
+/**
+ * Parse the built-in Langfuse provider configuration.
+ *
+ * @param env - Environment source, defaults to `process.env`.
+ * @returns The parsed config, or `undefined` when the provider is disabled or
+ * required keys/URL are missing.
+ */
+declare function readLangfuseConfig(env?: NodeJS.ProcessEnv): LangfuseConfig | undefined;
+/**
+ * Recursively redact secret-like keys and bearer tokens before export.
+ *
+ * @param value - Arbitrary span data. JSON-serialized strings are parsed and
+ * redacted recursively before being serialized again.
+ * @returns A redacted copy. Objects and arrays are rebuilt recursively, so
+ * non-JSON object instances such as `Date` or `Buffer` do not retain their
+ * original type.
+ */
+declare function redactLangfuseValue(value: unknown): unknown;
+/**
+ * Build a provider from environment variables.
+ *
+ * @param env - Environment source, defaults to `process.env`.
+ * @param logger - Optional best-effort lifecycle logger.
+ * @returns A configured provider, or `undefined` when disabled/incomplete.
+ */
+declare function createLangfuseProviderFromEnv(env?: NodeJS.ProcessEnv, logger?: LangfuseProviderLogger): LangfuseObservabilityProvider | undefined;
+/**
+ * Built-in Langfuse observability provider.
+ *
+ * Registers Langfuse's OpenTelemetry span processor for the Langfuse
+ * destination and returns LangChain callback handlers correlated to each
+ * Agent invocation.
+ *
+ * @remarks
+ * This class does not register itself with the observability lattice. The host
+ * decides when to call {@link start} / {@link stop} and how to register it.
+ */
+declare class LangfuseObservabilityProvider implements ObservabilityProvider {
+    private readonly config;
+    private readonly logger?;
+    readonly type = "langfuse";
+    readonly capabilities: {
+        autoCallbacks: boolean;
+        customObservations: boolean;
+        scores: boolean;
+        sessions: boolean;
+        promptManagement: boolean;
+    };
+    private tracerProvider?;
+    /**
+     * @param config - Parsed Langfuse configuration.
+     * @param logger - Optional best-effort lifecycle logger.
+     */
+    constructor(config: LangfuseConfig, logger?: LangfuseProviderLogger | undefined);
+    private warn;
+    /**
+     * Start the OpenTelemetry tracer provider exporting to Langfuse.
+     *
+     * @remarks
+     * Never throws. If construction or registration fails, the provider is
+     * marked not started and any constructed tracer provider is shut down
+     * best-effort.
+     */
+    start(): Promise<void>;
+    /**
+     * Flush pending spans and shut down the tracer provider.
+     *
+     * @remarks
+     * Never throws and is idempotent. OpenTelemetry has no process-wide
+     * unregister API, so the host must install exactly one provider instance per
+     * process; stopping flushes spans but does not remove the global registration.
+     */
+    stop(): Promise<void>;
+    /**
+     * Fetches the Langfuse metrics dashboard for one tenant.
+     *
+     * @param input - Time range and server-resolved tenant scope.
+     * @returns The normalized Langfuse payload.
+     * @throws ObservabilityDashboardUnsupportedError for Langfuse < v4.
+     * @throws ObservabilityDashboardUnavailableError when every query fails.
+     */
+    getDashboard(input: ObservabilityDashboardInput): Promise<ObservabilityDashboardResult>;
+    private fetchMetrics;
+    /**
+     * Create a Langfuse callback handler for one invocation.
+     *
+     * @param context - Correlation fields for the running Agent invocation.
+     * @returns One callback handler, or an empty list before start or when
+     * sampled out.
+     */
+    createCallbacks(context: ObservabilityTraceContext): readonly unknown[];
+    /**
+     * @returns The configured Langfuse UI trace-list URL.
+     */
+    getTraceListUrl(): string;
+}
+
 /**
  * Redis Streams implementation of the core {@link AppendLog} port.
  *
@@ -2879,4 +3002,4 @@ declare const LatticeGateway: {
     };
 };
 
-export { A2AAuthService, A2A_KEY_CHANGED_TOPIC, AGENT_LIFECYCLE_TOPIC, type AgentLifecycleHandlerDeps, type AgentLifecycleTarget, type AgentLifecycleTargetScope, ChunkLogCorruptionError, type CreateRedisRunTaskWakeOptions, DEFAULT_RUN_TASK_JOBS, DEFAULT_RUN_TASK_LEASE_TTL_MS, DEFAULT_RUN_TASK_MAX_ATTEMPTS, DEFAULT_RUN_TASK_SCAN_MS, DEFAULT_THREAD_RUN_LEASE_TTL_MS, type GatewayLifespan, type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, type LifespanLogger, MIRRORED_AGENT_EVENTS, MODEL_PROVIDER_CHANGED_TOPIC, ModelProviderService, type ModelProviderServiceDeps, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, ProjectRoomEventBroker, ROOM_EVENT_TOPIC, RUN_TASK_WAKE_CHANNEL, type RecoverTaskDeps, type RecoverTaskResult, type RedisAppendLogHandle, type RedisAppendLogLogger, type RedisAppendLogOptions, RedisRunTaskWake, type RedisRunTaskWakeDependencies, type RunTaskAgent, RunTaskConcurrencyLimiter, type RunTaskLogger, RunTaskRecovery, type RunTaskRecoveryDependencies, type RunTaskRecoveryStats, RunTaskRuntime, type RunTaskRuntimeDependencies, type RunTaskRuntimeStats, type RunTaskWake, type RunTaskWakeFrame, type RunTaskWakeLogger, type RunTaskWakePublisher, type RunTaskWakeRedisClient, type RunTaskWakeRedisMessageHandler, type RunTaskWakeStats, type RunTaskWakeStatsSource, RunTaskWorker, type RunTaskWorkerDependencies, type RunTaskWorkerStats, createConfiguredRedisRunTaskWake, createOrphanRecoveryRuntime, createRecoveryCallerDeps, createRedisAppendLog, createRedisRunTaskWake, createTaskRunLiveness, getRunTaskRuntime, getRunTaskWakeStatsSource, handleA2AKeyChanged, handleAgentLifecycle, handleModelProviderChanged, ingestRoomEvent, installAgentLifecycleSync, installLifespanHooks, parseEnvKeys, publishA2AKeyChanged, publishAgentLifecycle, publishModelProviderChanged, publishRoomEvent, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery, setRunTaskRuntime, setRunTaskWakePublisher, setRunTaskWakeStatsSource, wakeRunTaskQueue };
+export { A2AAuthService, A2A_KEY_CHANGED_TOPIC, AGENT_LIFECYCLE_TOPIC, type AgentLifecycleHandlerDeps, type AgentLifecycleTarget, type AgentLifecycleTargetScope, ChunkLogCorruptionError, type CreateRedisRunTaskWakeOptions, DEFAULT_RUN_TASK_JOBS, DEFAULT_RUN_TASK_LEASE_TTL_MS, DEFAULT_RUN_TASK_MAX_ATTEMPTS, DEFAULT_RUN_TASK_SCAN_MS, DEFAULT_THREAD_RUN_LEASE_TTL_MS, type GatewayLifespan, type GatewayLoggerConfig, LangfuseObservabilityProvider, LatticeGateway, type LatticeGatewayConfig, type LifespanLogger, MIRRORED_AGENT_EVENTS, MODEL_PROVIDER_CHANGED_TOPIC, ModelProviderService, type ModelProviderServiceDeps, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, ProjectRoomEventBroker, ROOM_EVENT_TOPIC, RUN_TASK_WAKE_CHANNEL, type RecoverTaskDeps, type RecoverTaskResult, type RedisAppendLogHandle, type RedisAppendLogLogger, type RedisAppendLogOptions, RedisRunTaskWake, type RedisRunTaskWakeDependencies, type RunTaskAgent, RunTaskConcurrencyLimiter, type RunTaskLogger, RunTaskRecovery, type RunTaskRecoveryDependencies, type RunTaskRecoveryStats, RunTaskRuntime, type RunTaskRuntimeDependencies, type RunTaskRuntimeStats, type RunTaskWake, type RunTaskWakeFrame, type RunTaskWakeLogger, type RunTaskWakePublisher, type RunTaskWakeRedisClient, type RunTaskWakeRedisMessageHandler, type RunTaskWakeStats, type RunTaskWakeStatsSource, RunTaskWorker, type RunTaskWorkerDependencies, type RunTaskWorkerStats, createConfiguredRedisRunTaskWake, createLangfuseProviderFromEnv, createOrphanRecoveryRuntime, createRecoveryCallerDeps, createRedisAppendLog, createRedisRunTaskWake, createTaskRunLiveness, getRunTaskRuntime, getRunTaskWakeStatsSource, handleA2AKeyChanged, handleAgentLifecycle, handleModelProviderChanged, ingestRoomEvent, installAgentLifecycleSync, installLifespanHooks, parseEnvKeys, publishA2AKeyChanged, publishAgentLifecycle, publishModelProviderChanged, publishRoomEvent, readLangfuseConfig, recoverTask, recoverTopCaller, redactLangfuseValue, resolveTopCaller, runOrphanRecovery, setRunTaskRuntime, setRunTaskWakePublisher, setRunTaskWakeStatsSource, wakeRunTaskQueue };