@fonoster/autopilot 0.26.0 → 0.30.0

package/dist/session/hosted.js

@@ -0,0 +1,506 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileWorkspaceSecrets = exports.CellSecretCredentials = exports.DatabaseWorkspaceSecrets = exports.PrismaAssistantSource = exports.FileAssistantSource = exports.AUTOPILOT_CONFIG_DIRS = exports.hostedConfigSchema = void 0;
+exports.findHostedConfig = findHostedConfig;
+exports.loadHostedConfig = loadHostedConfig;
+exports.s3Knowledge = s3Knowledge;
+exports.hostedOptions = hostedOptions;
+exports.eagerKnowledge = eagerKnowledge;
+exports.signedWorkspaceOnly = signedWorkspaceOnly;
+exports.startHostedAutopilot = startHostedAutopilot;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const common_1 = require("@fonoster/common");
+const logger_1 = require("@fonoster/logger");
+const voice_1 = require("@fonoster/voice");
+const yaml = __importStar(require("js-yaml"));
+const zod_1 = require("zod");
+const createAutopilot_1 = require("./createAutopilot");
+const knowledge_1 = require("./knowledge");
+const llm_1 = require("./llm");
+// The hosted Autopilot (rework-autopilot A2, task 4.3): an ordinary VoiceServer that the gateway
+// dials like any app. Everything it needs comes from one operator config file; no vendor key is
+// read from Autopilot's environment by name (A8, A11), only through credential refs.
+const logger = (0, logger_1.getLogger)({ service: "autopilot", filePath: __filename });
+const secretRef = zod_1.z.union([
+    zod_1.z.object({ env: zod_1.z.string() }).strict(),
+    zod_1.z.object({ value: zod_1.z.string() }).strict()
+]);
+const wsUrl = zod_1.z.string().regex(/^wss?:\/\//, "must be a ws:// or wss:// URL");
+exports.hostedConfigSchema = zod_1.z
+    .object({
+    host: zod_1.z.string().default("0.0.0.0"),
+    port: zod_1.z.number().int().nonnegative().default(50061),
+    /**
+     * Private destinations HTTP tools may call (host names, IPs, CIDRs; RV-B2); defaults to
+     * FONOSTER_ALLOWED_DESTINATIONS.
+     */
+    allowedDestinations: zod_1.z.array(zod_1.z.string()).optional(),
+    /** The secret the gateway signs Autopilot sessions with (one for every Autopilot app). */
+    signingSecret: secretRef,
+    /**
+     * 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: zod_1.z.union([wsUrl, zod_1.z.array(wsUrl).min(1)], {
+        errorMap: (issue, ctx) => ({
+            message: issue.code !== "invalid_union"
+                ? ctx.defaultError
+                : ctx.data === undefined
+                    ? "is required: the URL Autopilot apps point to (the apiserver's apps.autopilotUrl)"
+                    : "must be a ws:// or wss:// URL, or a list of them"
+        })
+    }),
+    /**
+     * 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: zod_1.z.union([
+        zod_1.z.object({ file: zod_1.z.string() }).strict(),
+        zod_1.z
+            .object({
+            source: zod_1.z.literal("database"),
+            cacheMs: zod_1.z.number().int().nonnegative().default(5000)
+        })
+            .strict()
+    ]),
+    /** The provider registry's catalog: the JSON file fonoster-registry writes, or the tables. */
+    registry: zod_1.z.union([
+        zod_1.z.object({ file: zod_1.z.string() }).strict(),
+        zod_1.z
+            .object({
+            source: zod_1.z.literal("database"),
+            refreshMs: zod_1.z.number().int().positive().default(30000)
+        })
+            .strict()
+    ]),
+    /** Platform keys by credentialRef. */
+    credentials: zod_1.z.record(secretRef).default({}),
+    /**
+     * Workspace Secrets (bring your own key): a JSON file by workspace and credentialRef, or
+     * `database`: the workspace's vendor keys (workspace_provider_keys).
+     */
+    workspaceSecrets: zod_1.z
+        .union([
+        zod_1.z.object({ file: zod_1.z.string() }).strict(),
+        zod_1.z.object({ source: zod_1.z.literal("database") }).strict(),
+        // A private region's cell secrets (add-private-regions PR-4, PR-9): by credentialRef or
+        // provider id, set on the cell with `fonoster-region secrets set <name>`.
+        zod_1.z
+            .object({
+            cellSecrets: zod_1.z
+                .object({
+                file: zod_1.z.string().optional(),
+                dir: zod_1.z.string().optional(),
+                keyEnv: zod_1.z.string().optional()
+            })
+                .strict()
+        })
+            .strict()
+    ])
+        .optional(),
+    /**
+     * 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: zod_1.z
+        .object({
+        url: zod_1.z.string().min(1),
+        /** A client generated from the apiserver schema (default `@prisma/client`). */
+        clientModule: zod_1.z.string().optional()
+    })
+        .strict()
+        .optional(),
+    /** Endpoint overrides by adapter or provider id (e.g. a local ollama, the fake LLM). */
+    endpoints: zod_1.z.record(zod_1.z.string()).default({}),
+    /** The S3 + Unstructured knowledge bases; keys by credentialRef (task 4.1). */
+    knowledge: zod_1.z
+        .object({
+        s3: zod_1.z.object({
+            endpoint: zod_1.z.string(),
+            region: zod_1.z.string().default("us-east-1"),
+            accessKeyIdRef: zod_1.z.string(),
+            secretAccessKeyRef: zod_1.z.string()
+        }),
+        unstructured: zod_1.z.object({ url: zod_1.z.string(), apiKeyRef: zod_1.z.string() }),
+        embeddings: zod_1.z.object({ apiKeyRef: zod_1.z.string() })
+    })
+        .optional(),
+    /**
+     * The apiserver's encryption key (fonoster.yaml `encryption.key`; vendor keys are encrypted
+     * Secrets). Usually "${ENCRYPTION_KEY}".
+     */
+    encryption: zod_1.z
+        .object({ key: zod_1.z.string().min(1) })
+        .strict()
+        .optional(),
+    /** OTLP export (empty = off): `otlpEndpoint: "${OTEL_EXPORTER_OTLP_ENDPOINT:-}"`. */
+    telemetry: common_1.telemetrySchema,
+    testMode: zod_1.z.boolean().default(false)
+})
+    .strict();
+function readStructured(file) {
+    const text = fs.readFileSync(file, "utf8");
+    return /\.ya?ml$/.test(file) ? yaml.load(text) : JSON.parse(text);
+}
+/** Where Autopilot looks for its file when none is named (autopilot.yaml, then the older name). */
+exports.AUTOPILOT_CONFIG_DIRS = ["/config", "/etc/fonoster", "./config"];
+/** The file `loadHostedConfig` reads without `--config`: the first one found, or undefined. */
+function findHostedConfig() {
+    for (const base of ["autopilot", "autopilot-session"]) {
+        const found = (0, common_1.resolveConfigFile)(base, [], exports.AUTOPILOT_CONFIG_DIRS);
+        if (found.path)
+            return found.path;
+    }
+    return undefined;
+}
+/**
+ * Loads the hosted Autopilot's file the apiserver's way (unify-config-placeholders): `${VAR}`
+ * placeholders from the container environment, `secret://` references, strict validation.
+ */
+function loadHostedConfig(file, env = process.env) {
+    const config = (0, common_1.loadServiceConfig)({
+        service: "autopilot",
+        schema: exports.hostedConfigSchema,
+        argv: ["--config", file],
+        env,
+        interpolatePaths: ["*"],
+        // The URL no longer falls back to APISERVER_DATABASE_URL (fix-config-and-placement-gaps).
+        movedKeys: {
+            "database.urlEnv": 'database.url ("${APISERVER_DATABASE_URL}")'
+        }
+    });
+    const dir = path.dirname(file);
+    const rel = (p) => (path.isAbsolute(p) ? p : path.join(dir, p));
+    const withFile = (c) => "file" in c ? { ...c, file: rel(c.file) } : c;
+    const needsDb = !("file" in config.assistants) ||
+        !("file" in config.registry) ||
+        (config.workspaceSecrets &&
+            "source" in config.workspaceSecrets &&
+            config.workspaceSecrets.source === "database");
+    if (needsDb && !config.database)
+        throw new Error("source: database needs a database section");
+    return {
+        ...config,
+        assistants: withFile(config.assistants),
+        registry: withFile(config.registry),
+        ...(config.workspaceSecrets
+            ? { workspaceSecrets: withFile(config.workspaceSecrets) }
+            : {})
+    };
+}
+const resolveSecret = (s) => "value" in s && s.value !== undefined ? s.value : process.env[s.env ?? ""];
+/** Apps and assistants from a file (a stand-in until assistants come from the control plane). */
+class FileAssistantSource {
+    constructor(file) {
+        this.file = file;
+    }
+    async get(appRef) {
+        const data = readStructured(this.file);
+        const app = data.apps?.[appRef];
+        return app
+            ? { assistant: app.assistant, workspaceRef: app.workspaceRef }
+            : undefined;
+    }
+}
+exports.FileAssistantSource = FileAssistantSource;
+/**
+ * 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.
+ */
+class PrismaAssistantSource {
+    constructor(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    prisma, options = {}) {
+        this.prisma = prisma;
+        this.options = options;
+        this.cache = new Map();
+    }
+    async get(appRef) {
+        const now = this.options.now?.() ?? Date.now();
+        const hit = this.cache.get(appRef);
+        if (hit && now - hit.at < (this.options.cacheMs ?? 5000))
+            return hit.value;
+        const row = await this.prisma.application.findUnique({
+            where: { ref: appRef },
+            include: { intelligence: true }
+        });
+        const value = row && row.type === "AUTOPILOT" && row.intelligence?.config
+            ? { assistant: row.intelligence.config, workspaceRef: row.accessKeyId }
+            : undefined;
+        this.cache.set(appRef, { at: now, value });
+        return value;
+    }
+}
+exports.PrismaAssistantSource = PrismaAssistantSource;
+/** Workspace vendor keys from the database, looked up by the credentialRef's providers. */
+class DatabaseWorkspaceSecrets {
+    constructor(keys, providers) {
+        this.keys = keys;
+        this.providers = providers;
+    }
+    get(ref, scope) {
+        if (!scope.workspaceRef)
+            return undefined;
+        return this.keys.forCredentialRef(scope.workspaceRef, ref, this.providers());
+    }
+}
+exports.DatabaseWorkspaceSecrets = DatabaseWorkspaceSecrets;
+/** A private region's cell secrets (PR-4): keys never leave the cell. */
+class CellSecretCredentials {
+    constructor(keys, providers) {
+        this.keys = keys;
+        this.providers = providers;
+    }
+    get(ref) {
+        return this.keys.forCredentialRef(ref, this.providers());
+    }
+}
+exports.CellSecretCredentials = CellSecretCredentials;
+/** Workspace Secrets from a JSON file: `{<workspaceRef>: {<credentialRef>: value}}`. */
+class FileWorkspaceSecrets {
+    constructor(file) {
+        this.file = file;
+    }
+    get(ref, scope) {
+        if (!scope.workspaceRef)
+            return undefined;
+        const data = readStructured(this.file);
+        return data[scope.workspaceRef]?.[ref];
+    }
+}
+exports.FileWorkspaceSecrets = FileWorkspaceSecrets;
+/**
+ * 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).
+ */
+function s3Knowledge(config, credentials, make) {
+    return async (assistant, scope) => {
+        const documents = assistant.languageModel.knowledgeBase.map((d) => d.document);
+        if (!documents.length || !scope.workspaceRef)
+            return undefined;
+        const key = (ref) => credentials.get(ref, scope);
+        const [accessKeyId, secretAccessKey, unstructuredKey, embeddingsKey] = await Promise.all([
+            key(config.s3.accessKeyIdRef),
+            key(config.s3.secretAccessKeyRef),
+            key(config.unstructured.apiKeyRef),
+            key(config.embeddings.apiKeyRef)
+        ]);
+        const params = {
+            bucket: scope.workspaceRef.toLowerCase(),
+            documents,
+            s3Config: {
+                endpoint: config.s3.endpoint,
+                region: config.s3.region,
+                credentials: {
+                    accessKeyId: accessKeyId ?? "",
+                    secretAccessKey: secretAccessKey ?? ""
+                },
+                forcePathStyle: true
+            },
+            unstructuredAPIURL: config.unstructured.url,
+            unstructuredAPIKey: unstructuredKey ?? "",
+            embeddingsApiKey: embeddingsKey ?? ""
+        };
+        const kb = (make ?? defaultKnowledgeBase)(params);
+        kb.load().catch((e) => logger.warn(`knowledge base did not load: ${e.message}`));
+        return (0, knowledge_1.fromKnowledgeBase)(kb);
+    };
+}
+function defaultKnowledgeBase(params) {
+    // Loaded lazily: the S3 loader and embeddings pull in LangChain, which only the knowledge
+    // port still uses.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { S3KnowledgeBase } = require("../knowledge/S3KnowledgeBase");
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { OpenAIEmbeddings } = require("@langchain/openai");
+    return new S3KnowledgeBase({
+        ...params,
+        embeddings: new OpenAIEmbeddings({ apiKey: params.embeddingsApiKey })
+    });
+}
+/** Opens the control-plane database named in the config (once). */
+function databaseOf(config) {
+    const d = config.database;
+    return common_1.Registry.openPrismaClient({
+        url: d.url,
+        encryptionKey: config.encryption?.key,
+        clientModule: d.clientModule
+    });
+}
+/** The registry store: the file, or the tables refreshed every `refreshMs`. */
+function registryStore(config, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+db) {
+    if ("file" in config.registry)
+        return new common_1.Registry.FileRegistryStore(config.registry.file);
+    const store = new common_1.Registry.MemoryRegistryStore();
+    const every = config.registry.refreshMs ?? 30000;
+    const load = () => common_1.Registry.PrismaRegistryStore.open(db())
+        .then((loaded) => {
+        for (const e of loaded.all())
+            store.put(e);
+    })
+        .catch((e) => logger.warn(`registry refresh failed, keeping the last: ${e.message}`));
+    void load();
+    setInterval(load, every).unref();
+    return store;
+}
+/** The handler options the hosted Autopilot runs with, built from its config. */
+function hostedOptions(config, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+deps = {}) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let prisma = deps.prisma;
+    const db = () => (prisma ?? (prisma = databaseOf(config)));
+    const store = registryStore(config, db);
+    const registry = new common_1.Registry.Registry({
+        store,
+        testMode: config.testMode
+    });
+    const providers = () => store
+        .all()
+        .filter((e) => e.kind === "provider")
+        .map((e) => ({
+        id: e.id,
+        credentialRef: e.credentialRef
+    }));
+    const workspace = config.workspaceSecrets;
+    const credentials = new llm_1.LayeredCredentials([
+        ...(workspace
+            ? [
+                "file" in workspace
+                    ? new FileWorkspaceSecrets(workspace.file)
+                    : "cellSecrets" in workspace
+                        ? new CellSecretCredentials(new common_1.CellSecrets.CellSecretKeys(common_1.CellSecrets.openCellSecrets(workspace.cellSecrets)), providers)
+                        : new DatabaseWorkspaceSecrets(new common_1.Registry.PrismaWorkspaceKeys(db()), providers)
+            ]
+            : []),
+        new llm_1.ConfigCredentials(config.credentials)
+    ]);
+    const assistants = "file" in config.assistants
+        ? new FileAssistantSource(config.assistants.file)
+        : new PrismaAssistantSource(db(), {
+            cacheMs: config.assistants.cacheMs
+        });
+    const knowledge = config.knowledge
+        ? s3Knowledge(config.knowledge, credentials)
+        : undefined;
+    return {
+        load: async (session) => signedWorkspaceOnly(session, await assistants.get(session.appRef)),
+        allowedDestinations: config.allowedDestinations,
+        llm: new llm_1.RegistryLlmResolver({
+            registry,
+            credentials,
+            endpoints: config.endpoints
+        }),
+        knowledgeFor: knowledge ? eagerKnowledge(knowledge) : undefined
+    };
+}
+/**
+ * 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).
+ */
+function eagerKnowledge(build) {
+    return (assistant, scope) => {
+        const port = Promise.resolve()
+            .then(() => build(assistant, scope))
+            .catch((e) => {
+            logger.warn(`knowledge port unavailable: ${e?.message ?? e}`);
+            return undefined;
+        });
+        return {
+            find: async (question, signal) => {
+                const p = await port;
+                return p ? p.find(question, signal) : "";
+            }
+        };
+    };
+}
+/**
+ * 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").
+ */
+function signedWorkspaceOnly(session, loaded) {
+    const signed = session.signedFor;
+    if (!loaded || !signed || loaded.workspaceRef === undefined)
+        return loaded;
+    if (signed.workspaceRef === loaded.workspaceRef)
+        return loaded;
+    logger.warn("refused a session: the app is not in the signed workspace", {
+        appRef: session.appRef
+    });
+    return undefined;
+}
+/** Starts the hosted Autopilot. */
+async function startHostedAutopilot(config) {
+    const secret = resolveSecret(config.signingSecret);
+    if (!secret)
+        throw new Error("signingSecret resolves to nothing");
+    const server = await new voice_1.VoiceServer({
+        host: config.host,
+        port: config.port,
+        signingSecret: secret,
+        // Every Autopilot app shares this secret: check the configured URL only (never Host) and
+        // require the signature bound to the app and workspace.
+        publicUrl: config.publicUrl,
+        requireAppBinding: true
+    }).listen((0, createAutopilot_1.createAutopilotHandler)(hostedOptions(config)));
+    logger.info(`hosted autopilot listening on ${config.host}:${server.port}`);
+    return server;
+}

package/dist/{assistants → session}/index.d.ts

@@ -16,5 +16,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export * from "./loadAndValidateAssistant";
-export * from "./types";
+export * from "./Agent";
+export * from "./config";
+export * from "./convertLegacyAssistant";
+export * from "./createAutopilot";
+export * from "./hosted";
+export * from "./knowledge";
+export * from "./llm";
+export * from "./machine";
+export * from "./sentences";
+export * from "./think";
+export * from "./tools";

package/dist/{machine/actors → session}/index.js

@@ -32,6 +32,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-__exportStar(require("./doProcessUserRequest"), exports);
-__exportStar(require("./doGreetUser"), exports);
-__exportStar(require("./doAnnounceIdleTimeout"), exports);
+__exportStar(require("./Agent"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./convertLegacyAssistant"), exports);
+__exportStar(require("./createAutopilot"), exports);
+__exportStar(require("./hosted"), exports);
+__exportStar(require("./knowledge"), exports);
+__exportStar(require("./llm"), exports);
+__exportStar(require("./machine"), exports);
+__exportStar(require("./sentences"), exports);
+__exportStar(require("./think"), exports);
+__exportStar(require("./tools"), exports);

package/dist/{machine/actions/appendSpeech.js → session/knowledge.d.ts}

@@ -1,6 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.appendSpeech = void 0;
 /**
  * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
  * http://github.com/fonoster/fonoster
@@ -19,17 +16,17 @@ exports.appendSpeech = void 0;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-const logger_1 = require("@fonoster/logger");
-const xstate_1 = require("xstate");
-const logger = (0, logger_1.getLogger)({ service: "autopilot", filePath: __filename });
-exports.appendSpeech = (0, xstate_1.assign)(({ context, event }) => {
-    const speech = event.speech;
-    logger.verbose("called the appendSpeech action", { speech });
-    if (!speech) {
-        return context;
-    }
-    context.speechBuffer = ((context.speechBuffer ?? "") +
-        " " +
-        speech).trimStart();
-    return context;
-});
+/**
+ * The knowledge port (rework-autopilot A8): one operation, find what is relevant to a question.
+ * Implementations (S3 + Unstructured today) are wired by the operator; their keys never live in
+ * the assistant config.
+ */
+export interface KnowledgePort {
+    find(question: string, signal: AbortSignal): Promise<string>;
+}
+/** Knowledge lookups never hold a reply back longer than this. */
+export declare const KNOWLEDGE_TIMEOUT_MS = 800;
+/** Adapts the current knowledge bases (mods/autopilot/src/knowledge) to the port. */
+export declare function fromKnowledgeBase(kb: {
+    queryKnowledgeBase(query: string, k?: number): Promise<string>;
+}): KnowledgePort;

package/dist/session/knowledge.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWLEDGE_TIMEOUT_MS = void 0;
+exports.fromKnowledgeBase = fromKnowledgeBase;
+/** Knowledge lookups never hold a reply back longer than this. */
+exports.KNOWLEDGE_TIMEOUT_MS = 800;
+/** Adapts the current knowledge bases (mods/autopilot/src/knowledge) to the port. */
+function fromKnowledgeBase(kb) {
+    return { find: (question) => kb.queryKnowledgeBase(question) };
+}

package/dist/session/llm.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Registry } from "@fonoster/common";
+import { Think } from "@fonoster/community";
+import { OPENAI_COMPATIBLE } from "@fonoster/community/openai";
+/** Where keys come from: workspace Secrets first (bring your own key), then platform keys. */
+export interface CredentialSource {
+    get(ref: string, scope: {
+        workspaceRef?: string;
+    }): Promise<string | undefined> | string | undefined;
+}
+/**
+ * Platform credentials from operator config: `{ "<credentialRef>": { env } | { value } }`. The
+ * variable names are operator choices; Autopilot never reads a vendor variable by itself.
+ */
+export declare class ConfigCredentials implements CredentialSource {
+    private readonly refs;
+    constructor(refs: Record<string, {
+        env?: string;
+        value?: string;
+    }>);
+    get(ref: string): string;
+}
+/** Workspace Secrets (BYOK) in front of platform credentials. */
+export declare class LayeredCredentials implements CredentialSource {
+    private readonly sources;
+    constructor(sources: CredentialSource[]);
+    get(ref: string, scope: {
+        workspaceRef?: string;
+    }): Promise<string>;
+}
+/** Adapters whose LLMs speak OpenAI-compatible Chat Completions (moved to @fonoster/community/openai). */
+export { OPENAI_COMPATIBLE };
+export declare class LlmResolutionError extends Error {
+}
+export type ResolvedLlm = {
+    think: Think;
+    /** The id actually used (a retired id resolves to its replacement). */
+    id: string;
+    /** For the call record: provider.deprecated_used / provider.retired_used (registry PR4). */
+    event?: {
+        type: string;
+        id: string;
+        replacement?: string;
+    };
+};
+export interface LlmResolver {
+    resolve(catalogId: string, options: {
+        temperature: number;
+        maxTokens: number;
+    }, scope: {
+        workspaceRef?: string;
+    }): Promise<ResolvedLlm>;
+}
+export type RegistryLlmResolverOptions = {
+    registry: Registry.Registry;
+    credentials: CredentialSource;
+    /** Endpoint overrides by adapter or provider id (required for fake; e.g. a local ollama). */
+    endpoints?: Record<string, string>;
+};
+export declare class RegistryLlmResolver implements LlmResolver {
+    private readonly options;
+    constructor(options: RegistryLlmResolverOptions);
+    resolve(catalogId: string, settings: {
+        temperature: number;
+        maxTokens: number;
+    }, scope?: {
+        workspaceRef?: string;
+    }): Promise<ResolvedLlm>;
+}