@axiom-lattice/gateway 4.8.4 → 4.9.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import * as http from 'http';
-import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, ProjectStore, TaskWorkItemStore, TenantStore, OutboxStore, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+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, ProjectRoom, Thread, ProjectStore, TaskWorkItemStore, TenantStore, OutboxStore, A2AApiKeyStore, AssistantStore, A2AApiKeyEntry, A2AAuthContext, Assistant, OpenGrant, A2AApiKeyRecord, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
 import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, TaskLifecycleService, IMessageQueueStore, Agent, TaskRunRegistry } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
+import { RouteGenericInterface, FastifyRequest, FastifyReply } from 'fastify';
 
 /** Public publisher surface for committed Project Room business facts. */
 interface ProjectRoomRealtimePublisher {
@@ -166,6 +167,252 @@ declare class MessageRouter {
     private projectRoomInterrupt;
 }
 
+/**
+ * Tenant model provider service.
+ *
+ * Owns provider configuration CRUD, upstream discovery, and the tenant-scoped
+ * model catalog. All tenant scoping decisions live here; the controller is a
+ * thin HTTP shell.
+ */
+
+/** Narrow persistence and registry dependencies of the service. */
+interface ModelProviderServiceDeps {
+    providerStore: ModelProviderStore;
+    userTenantLinkStore: Pick<UserTenantLinkStore, "getLink">;
+    registry: {
+        register(tenantId: string, modelKey: string, config: LLMConfig): void;
+        has(tenantId: string, modelKey: string): boolean;
+        remove(tenantId: string, modelKey: string): boolean;
+        listRegistered(tenantId: string): string[];
+    };
+    idFactory?: () => string;
+    /**
+     * Best-effort local change notification for cross-replica invalidation.
+     * Called synchronously after a successful mutating operation.
+     */
+    onChanged?: (tenantId: string, providerId: string) => void;
+}
+/**
+ * Service for tenant-scoped model provider configuration and discovery.
+ */
+declare class ModelProviderService {
+    private readonly deps;
+    private readonly idFactory;
+    constructor(deps: ModelProviderServiceDeps);
+    /**
+     * List the tenant's provider configurations.
+     */
+    list(userId: string | undefined, tenantId: string): Promise<ModelProviderPublicEntry[]>;
+    /**
+     * Read one provider configuration.
+     */
+    get(userId: string | undefined, tenantId: string, id: string): Promise<ModelProviderPublicEntry>;
+    /**
+     * The full model catalog visible to a tenant.
+     */
+    catalog(userId: string | undefined, tenantId: string): Promise<TenantModelCatalog>;
+    /**
+     * Hydrates the runtime model registry from the persisted provider catalog.
+     *
+     * @returns The model keys registered in this process.
+     * @remarks Registers the Phase-1 (default tenant) enabled provider models so a
+     * replica that did not perform discovery — or that restarted — can execute
+     * them. Best-effort; the caller logs failures.
+     */
+    hydrateRegistry(): Promise<string[]>;
+    /**
+     * Bring this replica's registry in line with one provider's current state.
+     *
+     * @param tenantId Tenant scope (only the default tenant registers).
+     * @param providerId Provider to reconcile; omit to re-hydrate the tenant.
+     * @remarks A missing provider removes every registry key under its
+     * `${providerId}/` prefix; legacy keys registered through `/api/models` are
+     * left untouched.
+     */
+    reconcileProvider(tenantId: string, providerId?: string): Promise<void>;
+    /**
+     * Create a provider configuration. Does not run discovery.
+     */
+    create(userId: string | undefined, tenantId: string, input: CreateModelProviderRequest): Promise<ModelProviderPublicEntry>;
+    /**
+     * Update a provider configuration.
+     * An omitted or empty `apiKey` keeps the stored key.
+     */
+    update(userId: string | undefined, tenantId: string, id: string, updates: Partial<UpdateModelProviderRequest>): Promise<ModelProviderPublicEntry>;
+    /**
+     * Delete a provider configuration, its snapshot, and any registry entries
+     * that no other provider in the tenant still supplies.
+     */
+    remove(userId: string | undefined, tenantId: string, id: string): Promise<void>;
+    /**
+     * Discover the provider's models and replace its snapshot.
+     */
+    discover(userId: string | undefined, tenantId: string, id: string): Promise<ModelDiscoveryResult>;
+    /**
+     * Bring the execution registry in line with a provider's current state.
+     *
+     * Registration copies `apiKey` and `baseURL` by value, so a rotated
+     * credential or a changed endpoint only takes effect once the model is
+     * re-registered. Disabled models — and every model of a disabled provider —
+     * are removed instead.
+     *
+     * @returns The model keys left registered
+     */
+    /**
+     * Probe an upstream without touching the store.
+     *
+     * Powers the provider form's "test latency" and "list models" actions, which
+     * validate a base URL and API key the user has typed but not yet saved. The
+     * URL is validated exactly as on create/update and is never persisted, so the
+     * "discover resolves its URL from the store" rule is not weakened — nothing
+     * a probe learns can reach the snapshot.
+     */
+    probe(userId: string | undefined, tenantId: string, input: ModelProviderProbeRequest): Promise<ModelProviderProbeResult>;
+    /**
+     * Set exactly which models this provider contributes.
+     *
+     * This is the "add model" action: the caller passes the ids it picked from
+     * the live list, and the provider's model set becomes precisely those. Ids
+     * are expected to have come from a probe — model names cannot be guessed,
+     * since a wrong id surfaces later as "model not found" or an authorisation
+     * error rather than at configuration time.
+     */
+    setModels(userId: string | undefined, tenantId: string, id: string, selection: ModelSelection[]): Promise<ModelProviderPublicEntry>;
+    private syncRegistry;
+    /** Best-effort local mutation notification; never affects the operation. */
+    private notifyChanged;
+    /**
+     * Enable or disable a single discovered model.
+     */
+    setModelEnabled(userId: string | undefined, tenantId: string, id: string, modelId: string, enabled: boolean): Promise<ModelProviderPublicEntry>;
+    /**
+     * Whether discovered models should be registered for execution.
+     */
+    private shouldRegister;
+    /**
+     * Build the runtime LLM config for a discovered model.
+     *
+     * `apiKeyEnvName`, `extra` and `modelKwargs` are deliberately omitted — they
+     * would let a tenant name an arbitrary process environment variable to read
+     * credentials from, or inject arbitrary constructor options.
+     */
+    private toLlmConfig;
+    /**
+     * The sole projection from an internal provider entry to an API-safe shape.
+     */
+    private toPublicEntry;
+    /**
+     * Reject a provider that would end up without a credential.
+     *
+     * @param apiKey - The key the provider would hold, if any
+     * @throws {ModelProviderServiceError} When no key is present
+     */
+    private assertHasApiKey;
+    /**
+     * Load a provider or fail with 404.
+     *
+     * Callers always pass the session's tenant, so a provider belonging to
+     * another tenant is indistinguishable from a missing one.
+     */
+    private requireProvider;
+    /**
+     * Require that the caller belongs to the tenant.
+     * An absent userId means the unauthenticated development fallback.
+     */
+    private assertMember;
+    /**
+     * Require that the caller is a tenant owner or admin.
+     * Roles are read from the tenant link, never from the session token.
+     */
+    private assertAdmin;
+    /**
+     * Validate the shape of an upstream URL and translate failures into service
+     * errors.
+     *
+     * Addresses are deliberately not restricted: other tenant-configured URLs in
+     * this platform (metrics servers, MCP servers) reach wherever they point, and
+     * self-hosted model servers normally sit on the gateway's own network.
+     *
+     * The mapping is explicit so the public error codes stay decoupled from the
+     * reasons the URL utility happens to use internally.
+     */
+    private assertSafeUrl;
+    /**
+     * Translate a store-level unique violation into a stable service error.
+     */
+    private mapStoreError;
+}
+
+/**
+ * HTTP controller for tenant model providers.
+ *
+ * Thin shell: resolves the tenant scope from the authenticated session, parses
+ * the request, delegates to ModelProviderService, and renders service errors.
+ */
+
+type Request<T extends RouteGenericInterface = RouteGenericInterface> = FastifyRequest<T> & {
+    user?: {
+        id?: string;
+        tenantId?: string;
+    };
+};
+/** Controller for tenant-scoped model provider management. */
+declare class ModelProviderController {
+    private readonly service;
+    private readonly authRequired;
+    constructor(deps: ModelProviderServiceDeps, options?: {
+        authRequired?: boolean;
+    });
+    /** GET /api/tenant-models */
+    getCatalog(request: Request, reply: FastifyReply): Promise<unknown>;
+    /** Hydrates the runtime model registry from persisted providers (startup). */
+    hydrateRegistry(): Promise<string[]>;
+    /** Reconciles one provider (or the tenant) after a foreign change. */
+    reconcileProvider(tenantId: string, providerId?: string): Promise<void>;
+    /** GET /api/model-providers */
+    listProviders(request: Request, reply: FastifyReply): Promise<unknown>;
+    /** GET /api/model-providers/:providerId */
+    getProvider(request: Request<{
+        Params: {
+            providerId: string;
+        };
+    }>, reply: FastifyReply): Promise<unknown>;
+    /** POST /api/model-providers */
+    createProvider(request: Request, reply: FastifyReply): Promise<unknown>;
+    /** PUT /api/model-providers/:providerId */
+    updateProvider(request: Request<{
+        Params: {
+            providerId: string;
+        };
+    }>, reply: FastifyReply): Promise<unknown>;
+    /** DELETE /api/model-providers/:providerId */
+    deleteProvider(request: Request<{
+        Params: {
+            providerId: string;
+        };
+    }>, reply: FastifyReply): Promise<unknown>;
+    /** POST /api/model-providers/probe */
+    probeProvider(request: Request, reply: FastifyReply): Promise<unknown>;
+    /** PUT /api/model-providers/:providerId/models */
+    setProviderModels(request: Request<{
+        Params: {
+            providerId: string;
+        };
+    }>, reply: FastifyReply): Promise<unknown>;
+    /** POST /api/model-providers/:providerId/discover */
+    discoverProvider(request: Request<{
+        Params: {
+            providerId: string;
+        };
+    }>, reply: FastifyReply): Promise<unknown>;
+    /** POST /api/model-providers/:providerId/models/enabled */
+    setModelEnabled(request: Request<{
+        Params: {
+            providerId: string;
+        };
+    }>, reply: FastifyReply): Promise<unknown>;
+}
+
 type Listener = (event: ProjectRoomBusinessEvent) => void | Promise<void>;
 /** Construction options for the bounded process-local Project Room event broker. */
 interface ProjectRoomEventBrokerOptions {
@@ -473,6 +720,12 @@ interface ProjectTaskExecutionDependencies {
     dispatcher: TrustedAgentMessageDispatcher;
     queue: IMessageQueueStore;
     agentFor: (task: TaskItem, thread: Thread) => Agent;
+    /** JIT-materializes a public-project task owner so it has a room anchor to post/reply. */
+    ensurePublicOwner?: (input: {
+        tenantId: string;
+        projectId: string;
+        assistantId: string;
+    }) => Promise<unknown>;
 }
 /** Input for recovering exactly one persisted Project Task queue execution. */
 interface RecoverProjectTaskExecutionInput {
@@ -704,6 +957,8 @@ interface LatticeRouteResult {
     projectTaskUnavailableReason?: string;
     /** Present only in exact single-Gateway realtime mode. */
     projectRoomRealtimeRuntime?: ProjectRoomRealtimeRuntime;
+    /** Always-present controller used by the outbox poller to reconcile foreign changes. */
+    modelProviderController: ModelProviderController;
 }
 
 declare const defaultSwaggerConfig: {
@@ -1116,6 +1371,122 @@ declare function publishRoomEvent(outbox: OutboxStore, owner: string, scope: Pro
  */
 declare function ingestRoomEvent(payload: unknown, broker: ProjectRoomEventBroker): boolean;
 
+/** Outbox topic carrying cross-replica A2A API-key invalidation. */
+declare const A2A_KEY_CHANGED_TOPIC = "a2a-key-changed";
+/**
+ * Best-effort publish of an A2A key change to the durable outbox.
+ *
+ * @param outbox Shared outbox store.
+ * @param owner This replica id (recorded as the event origin).
+ * @param tenantId Tenant whose keys changed.
+ * @remarks Never throws; peers fall back to startup load / the next change.
+ */
+declare function publishA2AKeyChanged(outbox: OutboxStore, owner: string, tenantId: string): Promise<void>;
+/**
+ * Reloads this replica's key map after a foreign key change.
+ *
+ * @param payload Outbox payload, expected to carry a non-empty `tenantId`.
+ * @param reload Store-backed reload callback (refreshes the global key map).
+ */
+declare function handleA2AKeyChanged(payload: unknown, reload: () => Promise<void>): Promise<void>;
+
+/** Outbox topic carrying cross-replica model-provider invalidation. */
+declare const MODEL_PROVIDER_CHANGED_TOPIC = "model-provider-changed";
+/**
+ * Best-effort publish of a model provider change to the durable outbox.
+ *
+ * @param outbox Shared outbox store.
+ * @param owner This replica id (recorded as the event origin).
+ * @param tenantId Tenant that owns the changed provider.
+ * @param providerId Provider that changed; omitted to reconcile the tenant.
+ * @remarks Never throws; startup hydration / the next change corrects a miss.
+ */
+declare function publishModelProviderChanged(outbox: OutboxStore, owner: string, tenantId: string, providerId?: string): Promise<void>;
+/**
+ * Reconciles one provider (or the whole tenant) after a foreign change.
+ *
+ * @param payload Outbox payload, expected to carry a non-empty `tenantId`.
+ * @param reconcile Store-backed reconcile callback.
+ */
+declare function handleModelProviderChanged(payload: unknown, reconcile: (tenantId: string, providerId?: string) => Promise<void>): Promise<void>;
+
+/**
+ * Dependencies injected into {@link A2AAuthService} so stores can be mocked in tests.
+ */
+interface A2AAuthServiceDeps {
+    keyStore: A2AApiKeyStore;
+    assistantStore: AssistantStore;
+    projectStore: ProjectStore;
+    envKeyMap?: Map<string, A2AApiKeyEntry>;
+    /**
+     * When true, requests with no key are allowed through when no keys are
+     * configured (dev mode). Defaults to false — JSON-RPC stays locked until a
+     * key is configured or this opt-in is explicitly enabled.
+     */
+    allowUnauthenticated?: boolean;
+}
+interface UpdateKeyScopedInput {
+    label?: string;
+    projectId?: string;
+    assistantIds?: string[];
+    grants?: OpenGrant[];
+}
+/** Input for creating an API key scoped to a tenant + project. */
+interface CreateKeyScopedInput {
+    tenantId: string;
+    projectId?: string;
+    assistantIds?: string[];
+    /** Open-door grants (validated minimally; unknown domains simply never match). */
+    grants?: OpenGrant[];
+    label?: string;
+}
+/**
+ * Parse an `A2A_API_KEYS="key:tenant:project,..."` env string into a lookup map.
+ * Entries missing a key, tenant, or project segment are skipped.
+ */
+declare function parseEnvKeys(env: string): Map<string, A2AApiKeyEntry>;
+/**
+ * Authenticates A2A requests against the key store + env key map,
+ * enforces assistant whitelist / exposure, and validates key scope on creation.
+ */
+declare class A2AAuthService {
+    private readonly keyStore;
+    private readonly assistantStore;
+    private readonly projectStore;
+    private readonly envKeyMap;
+    /** Lazily-populated store key map; reloaded via {@link refresh} after keys CRUD. */
+    private storeKeyMapCache;
+    private readonly allowUnauthenticated;
+    constructor(deps: A2AAuthServiceDeps);
+    /**
+     * Reload the cached store key map. Call once at startup and after any keys
+     * CRUD mutation so {@link authenticate} does not hit the store on every request.
+     */
+    refresh(): Promise<void>;
+    /** Return the cached store key map, loading it on first use. */
+    private getStoreKeyMap;
+    /**
+     * Authenticate an incoming request header (authorization or x-api-key value).
+     * Returns an auth context; `authenticated: false` means the caller must reject.
+     */
+    authenticate(header: string | undefined): Promise<A2AAuthContext>;
+    /**
+     * Assert that the given assistant is reachable under the provided auth
+     * context: authenticated, same tenant, and within the key's whitelist.
+     *
+     * Authorization is unified on the API key — the agent no longer carries an
+     * exposure flag; the key's assistant whitelist / grants is the single source.
+     */
+    assertAgentAccess(auth: A2AAuthContext, assistantId: string): Promise<Assistant>;
+    /**
+     * Create an API key scoped to a tenant + project, validating the project exists
+     * in the tenant and every assistant belongs to the same tenant.
+     */
+    createKeyScoped(input: CreateKeyScopedInput): Promise<A2AApiKeyRecord>;
+    updateKeyScoped(id: string, tenantId: string, input: UpdateKeyScopedInput): Promise<A2AApiKeyRecord>;
+    private extractToken;
+}
+
 /**
  * Logger configuration for gateway
  */
@@ -1135,6 +1506,16 @@ interface LatticeGatewayConfig {
         defaultStartPollingQueue: boolean;
     };
     loggerConfig?: Partial<GatewayLoggerConfig>;
+    /**
+     * Install SIGTERM/SIGINT graceful-shutdown handlers (default `true`). On a
+     * signal the gateway aborts in-flight thread runs (releasing their
+     * cross-replica `thread-run` leases so a peer can take over immediately),
+     * stops background jobs, and closes the HTTP server before exiting.
+     * Set `false` when the host manages its own shutdown.
+     */
+    gracefulShutdown?: boolean;
+    /** Force-exit deadline for graceful shutdown in ms (default 10_000). */
+    gracefulShutdownTimeoutMs?: number;
 }
 declare const LatticeGateway: {
     startAsHttpEndpoint: (config?: LatticeGatewayConfig) => Promise<void>;
@@ -1146,4 +1527,4 @@ declare const LatticeGateway: {
     AgentTaskConsumer: typeof AgentTaskConsumer;
 };
 
-export { type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, ProjectRoomEventBroker, ROOM_EVENT_TOPIC, type RecoverTaskDeps, type RecoverTaskResult, type TaskLivenessProbe, createOrphanRecoveryRuntime, createRecoveryCallerDeps, createTaskRunLiveness, ingestRoomEvent, publishRoomEvent, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery };
+export { A2AAuthService, A2A_KEY_CHANGED_TOPIC, type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, MODEL_PROVIDER_CHANGED_TOPIC, ModelProviderService, type ModelProviderServiceDeps, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, ProjectRoomEventBroker, ROOM_EVENT_TOPIC, type RecoverTaskDeps, type RecoverTaskResult, type TaskLivenessProbe, createOrphanRecoveryRuntime, createRecoveryCallerDeps, createTaskRunLiveness, handleA2AKeyChanged, handleModelProviderChanged, ingestRoomEvent, parseEnvKeys, publishA2AKeyChanged, publishModelProviderChanged, publishRoomEvent, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery };