@fonoster/autopilot 0.27.0 → 0.31.0

package/dist/session/createAutopilot.d.ts

@@ -0,0 +1,48 @@
+import { Agent, Recorder } from "./Agent";
+import { SessionAgent } from "./config";
+import { KnowledgePort } from "./knowledge";
+import { LlmResolver } from "./llm";
+import { UsageSink } from "./meteredThink";
+import { Think, ThinkProvider } from "./think";
+import { ToolPort } from "./tools";
+import type { Session } from "@fonoster/voice";
+/** What the hosted Autopilot knows about the app a session belongs to. */
+export type LoadedAgent = {
+    agent: unknown;
+    /** The workspace that owns the app: scope for its own keys (BYOK) and knowledge. */
+    workspaceRef?: string;
+};
+export type AutopilotOptions = {
+    /** The agent for a session (validated with the session agent schema). */
+    agent?: unknown | ((session: Session) => Promise<unknown> | unknown);
+    /**
+     * The hosted path: loads the app's agent and workspace for a session; undefined means the
+     * app has no agent (the call is ended).
+     */
+    load?: (session: Session) => Promise<LoadedAgent | undefined>;
+    /** Language models through the provider registry (task 3.1). */
+    llm?: LlmResolver;
+    /** Language model endpoints by provider name (the stand-in used before the registry). */
+    providers?: Record<string, ThinkProvider>;
+    think?: Think;
+    tools?: ToolPort;
+    /**
+     * Private destinations HTTP tools may call (host names, IPs, CIDRs); defaults to
+     * FONOSTER_ALLOWED_DESTINATIONS. Everything else must be public (RV-B2).
+     */
+    allowedDestinations?: string[];
+    /** Finds what is relevant to the caller's question (the knowledge port). */
+    knowledge?: KnowledgePort;
+    /** Builds the knowledge port for an agent (operator wiring, task 4.1). */
+    knowledgeFor?: (agent: SessionAgent, scope: {
+        workspaceRef?: string;
+    }, usage?: UsageSink) => KnowledgePort | undefined;
+    recorder?: Recorder;
+    /** Called with each session's Agent, for tests and observability. */
+    onAgent?: (agent: Agent) => void;
+};
+/**
+ * Autopilot as an ordinary application (rework-autopilot A2): returns a VoiceServer handler that
+ * runs the state machine on the session's public messages only.
+ */
+export declare function createAutopilotHandler(options: AutopilotOptions): (session: Session) => Promise<void>;

package/dist/session/createAutopilot.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAutopilotHandler = createAutopilotHandler;
+/**
+ * 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 logger_1 = require("@fonoster/logger");
+const xstate_1 = require("xstate");
+const Agent_1 = require("./Agent");
+const config_1 = require("./config");
+const llm_1 = require("./llm");
+const machine_1 = require("./machine");
+const meteredThink_1 = require("./meteredThink");
+const telemetry_1 = require("./telemetry");
+const think_1 = require("./think");
+const tools_1 = require("./tools");
+const logger = (0, logger_1.getLogger)({ service: "autopilot", filePath: __filename });
+/**
+ * Autopilot as an ordinary application (rework-autopilot A2): returns a VoiceServer handler that
+ * runs the state machine on the session's public messages only.
+ */
+function createAutopilotHandler(options) {
+    const run = createSessionRunner(options);
+    return async (session) => {
+        // The session span joins the call's trace when AppBridge sent a traceparent.
+        const span = telemetry_1.telemetry.startCall(session.callRef, "autopilot.session", {
+            "fonoster.app_ref": session.appRef,
+            "fonoster.session_ref": session.sessionRef
+        }, session.traceparent);
+        try {
+            await run(session);
+            span.end();
+        }
+        catch (e) {
+            span.end({}, e.message);
+            throw e;
+        }
+    };
+}
+function createSessionRunner(options) {
+    return async (session) => {
+        // Listen before any await: turn events that arrive while the agent and model load are
+        // held and delivered once the machine runs.
+        const early = [];
+        let deliver = (event) => early.push(event);
+        session.on("turn.user_started", () => deliver({ type: "TURN_USER_STARTED" }));
+        session.on("turn.likely_ended", (e) => deliver({ type: "TURN_LIKELY_ENDED", text: e.text }));
+        session.on("turn.resumed", () => deliver({ type: "TURN_RESUMED" }));
+        // A turn with no words (line noise, an abandoned start) is not an answer: no reply, and the
+        // idle count is kept, so a silent call still ends.
+        session.on("turn.ended", (e) => {
+            if (e.text.trim())
+                deliver({ type: "TURN_ENDED", text: e.text });
+        });
+        session.on("turn.backchannel", () => deliver({ type: "TURN_BACKCHANNEL" }));
+        // Open drains of interrupted replies stop with the session: their usage can no longer
+        // reach the call (add-usage-metering D6).
+        const closed = new AbortController();
+        const ended = new Promise((resolve) => session.on("end", () => {
+            closed.abort();
+            deliver({ type: "SESSION_END" });
+            resolve();
+        }));
+        const loaded = options.load
+            ? await options.load(session)
+            : {
+                agent: typeof options.agent === "function"
+                    ? await options.agent(session)
+                    : options.agent
+            };
+        if (!loaded) {
+            logger.warn("no agent for this app; ending the call", {
+                appRef: session.appRef,
+                callRef: session.callRef
+            });
+            await session.hangup().catch(() => undefined);
+            return;
+        }
+        const agentConfig = config_1.sessionAgentSchema.parse(loaded.agent);
+        const scope = { workspaceRef: loaded.workspaceRef };
+        const recorder = options.recorder ?? (0, Agent_1.sessionRecorder)(session);
+        const settings = {
+            temperature: agentConfig.languageModel.temperature,
+            maxTokens: agentConfig.languageModel.maxTokens
+        };
+        const sink = {
+            usage: (lines) => recorder.usage?.(lines),
+            missing: (catalogId) => {
+                telemetry_1.telemetry.count("fonoster.usage.missing", 1, { catalog_id: catalogId });
+                recorder.note({ type: "usage_missing", catalogId });
+            }
+        };
+        let think = options.think;
+        if (!think && options.llm) {
+            try {
+                const resolved = await options.llm.resolve(agentConfig.languageModel.model, settings, scope);
+                think = (0, meteredThink_1.meteredThink)(resolved.think, { catalogId: resolved.id, keySource: resolved.keySource }, sink, { closed: closed.signal });
+                if (resolved.event)
+                    recorder.note(resolved.event);
+            }
+            catch (e) {
+                // A model the registry cannot serve: apologise and end the call, never a silent line.
+                logger.error(`autopilot cannot reach its language model: ${e.message}`);
+                recorder.note({
+                    type: "llm.unavailable",
+                    reason: e instanceof llm_1.KeyUnavailableError ? e.reason : e.message
+                });
+                await session
+                    .say(agentConfig.conversationSettings.systemErrorMessage, {
+                    interruptible: false
+                })
+                    .catch(() => undefined);
+                await session.hangup().catch(() => undefined);
+                return;
+            }
+        }
+        think ?? (think = (0, meteredThink_1.meteredThink)((0, think_1.resolveThink)(agentConfig.languageModel.model, options.providers ?? {}, settings), { catalogId: agentConfig.languageModel.model, keySource: "platform" }, sink, { closed: closed.signal }));
+        const agent = new Agent_1.Agent(session, agentConfig, think, options.tools ??
+            new tools_1.HttpToolPort(agentConfig.languageModel.tools, {
+                allow: options.allowedDestinations
+            }), recorder, options.knowledge ?? options.knowledgeFor?.(agentConfig, scope, sink));
+        options.onAgent?.(agent);
+        const actor = (0, xstate_1.createActor)(machine_1.autopilotMachine, { input: { agent } });
+        agent.send = (event) => actor.send(event);
+        actor.subscribe((state) => logger.verbose("autopilot state", {
+            callRef: session.callRef,
+            state: state.value
+        }));
+        actor.start();
+        deliver = (event) => actor.send(event);
+        for (const event of early.splice(0))
+            actor.send(event);
+        await ended;
+        actor.stop();
+    };
+}

package/dist/session/hosted.d.ts

@@ -0,0 +1,454 @@
+import { CellSecrets, Registry } from "@fonoster/common";
+import { Session, VoiceServer } from "@fonoster/voice";
+import { z } from "zod";
+import { SessionAgent } from "./config";
+import { AutopilotOptions, LoadedAgent } from "./createAutopilot";
+import { KnowledgePort } from "./knowledge";
+import { CredentialSource } from "./llm";
+import { UsageSink } from "./meteredThink";
+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 AppBridge 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 agents: a file `{apps: {<appRef>: {workspaceRef?, agent}}}` (JSON or
+     * YAML), or `database`: the apps' Intelligence rows, cached for `cacheMs` (CP-B11).
+     */
+    agents: 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 provider or adapter id (e.g. a local ollama); the catalog's otherwise. */
+    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;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    registry?: {
+        file?: string;
+    } | {
+        source?: "database";
+        refreshMs?: number;
+    };
+    host?: string;
+    port?: number;
+    allowedDestinations?: string[];
+    signingSecret?: {
+        env?: string;
+    } | {
+        value?: string;
+    };
+    publicUrl?: string | string[];
+    agents?: {
+        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;
+    };
+}, {
+    registry?: {
+        file?: string;
+    } | {
+        source?: "database";
+        refreshMs?: number;
+    };
+    host?: string;
+    port?: number;
+    allowedDestinations?: string[];
+    signingSecret?: {
+        env?: string;
+    } | {
+        value?: string;
+    };
+    publicUrl?: string | string[];
+    agents?: {
+        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;
+    };
+}>;
+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 agents from a file (a stand-in until agents come from the control plane). */
+export declare class FileAgentSource {
+    private readonly file;
+    constructor(file: string);
+    get(appRef: string): Promise<LoadedAgent | undefined>;
+}
+/**
+ * Agents from the control plane: an Autopilot app's Intelligence row holds its agent
+ * (CP-B3). Each app is cached for `cacheMs` (misses too), so edits show up within seconds.
+ */
+export declare class PrismaAgentSource {
+    private readonly prisma;
+    private readonly options;
+    private cache;
+    constructor(prisma: any, options?: {
+        cacheMs?: number;
+        now?: () => number;
+    });
+    get(appRef: string): Promise<LoadedAgent | 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 agent 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): (agent: SessionAgent, scope: {
+    workspaceRef?: string;
+}, usage?: UsageSink) => 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: (agent: SessionAgent, scope: {
+    workspaceRef?: string;
+}, usage?: UsageSink) => Promise<KnowledgePort | undefined>): (agent: SessionAgent, scope: {
+    workspaceRef?: string;
+}, usage?: UsageSink) => KnowledgePort;
+/**
+ * The app's agent only when the app belongs to the workspace AppBridge 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: LoadedAgent | undefined): LoadedAgent | undefined;
+/** Starts the hosted Autopilot. */
+export declare function startHostedAutopilot(config: HostedConfig): Promise<VoiceServer>;
+export {};