@fonoster/autopilot 0.26.0 → 0.30.0

package/dist/session/hosted.d.ts

@@ -0,0 +1,456 @@
+import { CellSecrets, Registry } from "@fonoster/common";
+import { Session, VoiceServer } from "@fonoster/voice";
+import { z } from "zod";
+import { SessionAssistant } from "./config";
+import { AutopilotOptions, LoadedAssistant } from "./createAutopilot";
+import { KnowledgePort } from "./knowledge";
+import { CredentialSource } from "./llm";
+export declare const hostedConfigSchema: z.ZodObject<{
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Private destinations HTTP tools may call (host names, IPs, CIDRs; RV-B2); defaults to
+     * FONOSTER_ALLOWED_DESTINATIONS.
+     */
+    allowedDestinations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** The secret the gateway signs Autopilot sessions with (one for every Autopilot app). */
+    signingSecret: z.ZodUnion<[z.ZodObject<{
+        env: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        env?: string;
+    }, {
+        env?: string;
+    }>, z.ZodObject<{
+        value: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        value?: string;
+    }, {
+        value?: string;
+    }>]>;
+    /**
+     * The URL Autopilot apps point to, exactly as the apps have it (the apiserver's
+     * `apps.autopilotUrl`, e.g. ws://autopilot:3000), or several. Signatures are checked against
+     * it, never against the request's Host header.
+     */
+    publicUrl: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+    /**
+     * Apps and their assistants: a file `{apps: {<appRef>: {workspaceRef?, assistant}}}` (JSON or
+     * YAML), or `database`: the apps' Intelligence rows, cached for `cacheMs` (CP-B11).
+     */
+    assistants: z.ZodUnion<[z.ZodObject<{
+        file: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        file?: string;
+    }, {
+        file?: string;
+    }>, z.ZodObject<{
+        source: z.ZodLiteral<"database">;
+        cacheMs: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        source?: "database";
+        cacheMs?: number;
+    }, {
+        source?: "database";
+        cacheMs?: number;
+    }>]>;
+    /** The provider registry's catalog: the JSON file fonoster-registry writes, or the tables. */
+    registry: z.ZodUnion<[z.ZodObject<{
+        file: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        file?: string;
+    }, {
+        file?: string;
+    }>, z.ZodObject<{
+        source: z.ZodLiteral<"database">;
+        refreshMs: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        source?: "database";
+        refreshMs?: number;
+    }, {
+        source?: "database";
+        refreshMs?: number;
+    }>]>;
+    /** Platform keys by credentialRef. */
+    credentials: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+        env: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        env?: string;
+    }, {
+        env?: string;
+    }>, z.ZodObject<{
+        value: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        value?: string;
+    }, {
+        value?: string;
+    }>]>>>;
+    /**
+     * Workspace Secrets (bring your own key): a JSON file by workspace and credentialRef, or
+     * `database`: the workspace's vendor keys (workspace_provider_keys).
+     */
+    workspaceSecrets: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        file: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        file?: string;
+    }, {
+        file?: string;
+    }>, z.ZodObject<{
+        source: z.ZodLiteral<"database">;
+    }, "strict", z.ZodTypeAny, {
+        source?: "database";
+    }, {
+        source?: "database";
+    }>, z.ZodObject<{
+        cellSecrets: z.ZodObject<{
+            file: z.ZodOptional<z.ZodString>;
+            dir: z.ZodOptional<z.ZodString>;
+            keyEnv: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            file?: string;
+            dir?: string;
+            keyEnv?: string;
+        }, {
+            file?: string;
+            dir?: string;
+            keyEnv?: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        cellSecrets?: {
+            file?: string;
+            dir?: string;
+            keyEnv?: string;
+        };
+    }, {
+        cellSecrets?: {
+            file?: string;
+            dir?: string;
+            keyEnv?: string;
+        };
+    }>]>>;
+    /**
+     * The control-plane database (the apiserver's), for any `source: database`. The URL comes
+     * from this file only, usually as a placeholder: `url: "${APISERVER_DATABASE_URL}"`.
+     */
+    database: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        /** A client generated from the apiserver schema (default `@prisma/client`). */
+        clientModule: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        url?: string;
+        clientModule?: string;
+    }, {
+        url?: string;
+        clientModule?: string;
+    }>>;
+    /** Endpoint overrides by adapter or provider id (e.g. a local ollama, the fake LLM). */
+    endpoints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** The S3 + Unstructured knowledge bases; keys by credentialRef (task 4.1). */
+    knowledge: z.ZodOptional<z.ZodObject<{
+        s3: z.ZodObject<{
+            endpoint: z.ZodString;
+            region: z.ZodDefault<z.ZodString>;
+            accessKeyIdRef: z.ZodString;
+            secretAccessKeyRef: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            endpoint?: string;
+            region?: string;
+            accessKeyIdRef?: string;
+            secretAccessKeyRef?: string;
+        }, {
+            endpoint?: string;
+            region?: string;
+            accessKeyIdRef?: string;
+            secretAccessKeyRef?: string;
+        }>;
+        unstructured: z.ZodObject<{
+            url: z.ZodString;
+            apiKeyRef: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            url?: string;
+            apiKeyRef?: string;
+        }, {
+            url?: string;
+            apiKeyRef?: string;
+        }>;
+        embeddings: z.ZodObject<{
+            apiKeyRef: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            apiKeyRef?: string;
+        }, {
+            apiKeyRef?: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        s3?: {
+            endpoint?: string;
+            region?: string;
+            accessKeyIdRef?: string;
+            secretAccessKeyRef?: string;
+        };
+        unstructured?: {
+            url?: string;
+            apiKeyRef?: string;
+        };
+        embeddings?: {
+            apiKeyRef?: string;
+        };
+    }, {
+        s3?: {
+            endpoint?: string;
+            region?: string;
+            accessKeyIdRef?: string;
+            secretAccessKeyRef?: string;
+        };
+        unstructured?: {
+            url?: string;
+            apiKeyRef?: string;
+        };
+        embeddings?: {
+            apiKeyRef?: string;
+        };
+    }>>;
+    /**
+     * The apiserver's encryption key (fonoster.yaml `encryption.key`; vendor keys are encrypted
+     * Secrets). Usually "${ENCRYPTION_KEY}".
+     */
+    encryption: z.ZodOptional<z.ZodObject<{
+        key: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        key?: string;
+    }, {
+        key?: string;
+    }>>;
+    /** OTLP export (empty = off): `otlpEndpoint: "${OTEL_EXPORTER_OTLP_ENDPOINT:-}"`. */
+    telemetry: z.ZodOptional<z.ZodObject<{
+        otlpEndpoint: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        otlpEndpoint?: string;
+    }, {
+        otlpEndpoint?: string;
+    }>>;
+    testMode: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    registry?: {
+        file?: string;
+    } | {
+        source?: "database";
+        refreshMs?: number;
+    };
+    host?: string;
+    port?: number;
+    allowedDestinations?: string[];
+    signingSecret?: {
+        env?: string;
+    } | {
+        value?: string;
+    };
+    publicUrl?: string | string[];
+    assistants?: {
+        file?: string;
+    } | {
+        source?: "database";
+        cacheMs?: number;
+    };
+    database?: {
+        url?: string;
+        clientModule?: string;
+    };
+    credentials?: Record<string, {
+        env?: string;
+    } | {
+        value?: string;
+    }>;
+    workspaceSecrets?: {
+        file?: string;
+    } | {
+        source?: "database";
+    } | {
+        cellSecrets?: {
+            file?: string;
+            dir?: string;
+            keyEnv?: string;
+        };
+    };
+    endpoints?: Record<string, string>;
+    knowledge?: {
+        s3?: {
+            endpoint?: string;
+            region?: string;
+            accessKeyIdRef?: string;
+            secretAccessKeyRef?: string;
+        };
+        unstructured?: {
+            url?: string;
+            apiKeyRef?: string;
+        };
+        embeddings?: {
+            apiKeyRef?: string;
+        };
+    };
+    encryption?: {
+        key?: string;
+    };
+    telemetry?: {
+        otlpEndpoint?: string;
+    };
+    testMode?: boolean;
+}, {
+    registry?: {
+        file?: string;
+    } | {
+        source?: "database";
+        refreshMs?: number;
+    };
+    host?: string;
+    port?: number;
+    allowedDestinations?: string[];
+    signingSecret?: {
+        env?: string;
+    } | {
+        value?: string;
+    };
+    publicUrl?: string | string[];
+    assistants?: {
+        file?: string;
+    } | {
+        source?: "database";
+        cacheMs?: number;
+    };
+    database?: {
+        url?: string;
+        clientModule?: string;
+    };
+    credentials?: Record<string, {
+        env?: string;
+    } | {
+        value?: string;
+    }>;
+    workspaceSecrets?: {
+        file?: string;
+    } | {
+        source?: "database";
+    } | {
+        cellSecrets?: {
+            file?: string;
+            dir?: string;
+            keyEnv?: string;
+        };
+    };
+    endpoints?: Record<string, string>;
+    knowledge?: {
+        s3?: {
+            endpoint?: string;
+            region?: string;
+            accessKeyIdRef?: string;
+            secretAccessKeyRef?: string;
+        };
+        unstructured?: {
+            url?: string;
+            apiKeyRef?: string;
+        };
+        embeddings?: {
+            apiKeyRef?: string;
+        };
+    };
+    encryption?: {
+        key?: string;
+    };
+    telemetry?: {
+        otlpEndpoint?: string;
+    };
+    testMode?: boolean;
+}>;
+export type HostedConfig = z.infer<typeof hostedConfigSchema>;
+/** Where Autopilot looks for its file when none is named (autopilot.yaml, then the older name). */
+export declare const AUTOPILOT_CONFIG_DIRS: string[];
+/** The file `loadHostedConfig` reads without `--config`: the first one found, or undefined. */
+export declare function findHostedConfig(): string | undefined;
+/**
+ * Loads the hosted Autopilot's file the apiserver's way (unify-config-placeholders): `${VAR}`
+ * placeholders from the container environment, `secret://` references, strict validation.
+ */
+export declare function loadHostedConfig(file: string, env?: Record<string, string | undefined>): HostedConfig;
+/** Apps and assistants from a file (a stand-in until assistants come from the control plane). */
+export declare class FileAssistantSource {
+    private readonly file;
+    constructor(file: string);
+    get(appRef: string): Promise<LoadedAssistant | undefined>;
+}
+/**
+ * Assistants from the control plane: an Autopilot app's Intelligence row holds its assistant
+ * (CP-B3). Each app is cached for `cacheMs` (misses too), so edits show up within seconds.
+ */
+export declare class PrismaAssistantSource {
+    private readonly prisma;
+    private readonly options;
+    private cache;
+    constructor(prisma: any, options?: {
+        cacheMs?: number;
+        now?: () => number;
+    });
+    get(appRef: string): Promise<LoadedAssistant | undefined>;
+}
+/** Workspace vendor keys from the database, looked up by the credentialRef's providers. */
+export declare class DatabaseWorkspaceSecrets implements CredentialSource {
+    private readonly keys;
+    private readonly providers;
+    constructor(keys: Registry.PrismaWorkspaceKeys, providers: () => {
+        id: string;
+        credentialRef: string;
+    }[]);
+    get(ref: string, scope: {
+        workspaceRef?: string;
+    }): Promise<string>;
+}
+/** A private region's cell secrets (PR-4): keys never leave the cell. */
+export declare class CellSecretCredentials implements CredentialSource {
+    private readonly keys;
+    private readonly providers;
+    constructor(keys: CellSecrets.CellSecretKeys, providers: () => {
+        id: string;
+        credentialRef: string;
+    }[]);
+    get(ref: string): string;
+}
+/** Workspace Secrets from a JSON file: `{<workspaceRef>: {<credentialRef>: value}}`. */
+export declare class FileWorkspaceSecrets implements CredentialSource {
+    private readonly file;
+    constructor(file: string);
+    get(ref: string, scope: {
+        workspaceRef?: string;
+    }): string;
+}
+type KnowledgeBaseLike = {
+    load(): Promise<void>;
+    queryKnowledgeBase(query: string, k?: number): Promise<string>;
+};
+/**
+ * Builds the knowledge port for an assistant from the operator's S3 + Unstructured settings,
+ * with keys from the credential source (never Autopilot's environment). The bucket is the
+ * workspace's, as today. `make` is the knowledge base constructor (the S3 one by default).
+ */
+export declare function s3Knowledge(config: NonNullable<HostedConfig["knowledge"]>, credentials: CredentialSource, make?: (params: Record<string, unknown>) => KnowledgeBaseLike): (assistant: SessionAssistant, scope: {
+    workspaceRef?: string;
+}) => Promise<KnowledgePort | undefined>;
+/** The handler options the hosted Autopilot runs with, built from its config. */
+export declare function hostedOptions(config: HostedConfig, deps?: {
+    prisma?: any;
+}): AutopilotOptions;
+/**
+ * One knowledge port per call, built eagerly; a lookup waits for it (and gives up after 800 ms
+ * like any). A port that fails to build is logged and answers nothing: the eager promise always
+ * has a handler, so a failure never becomes an unhandled rejection (RV-B5).
+ */
+export declare function eagerKnowledge(build: (assistant: SessionAssistant, scope: {
+    workspaceRef?: string;
+}) => Promise<KnowledgePort | undefined>): (assistant: SessionAssistant, scope: {
+    workspaceRef?: string;
+}) => KnowledgePort;
+/**
+ * The app's assistant only when the app belongs to the workspace the gateway signed for: one
+ * secret serves every Autopilot app, so a session is bound to its app and workspace
+ * (voice-session, "Connection requests are bound to the app").
+ */
+export declare function signedWorkspaceOnly(session: Pick<Session, "appRef" | "signedFor">, loaded: LoadedAssistant | undefined): LoadedAssistant | undefined;
+/** Starts the hosted Autopilot. */
+export declare function startHostedAutopilot(config: HostedConfig): Promise<VoiceServer>;
+export {};