@fonoster/autopilot 0.27.0 → 0.30.0

package/dist/{machine/guards/index.d.ts → session/config.d.ts}

@@ -16,5 +16,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export { idleTimeoutCountExceedsMax } from "./idleTimeoutCountExceedsMax";
-export { hasSpeechResult } from "./hasSpeechResult";
+export { sessionAssistantSchema, sessionConversationSettingsSchema, sessionLanguageModelSchema } from "@fonoster/common";
+export type { SessionAssistant, SessionConversationSettings, SessionLanguageModel, ToolDefinition } from "@fonoster/common";

package/dist/session/config.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionLanguageModelSchema = exports.sessionConversationSettingsSchema = exports.sessionAssistantSchema = void 0;
+/**
+ * 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.
+ */
+// The session assistant schema lives in @fonoster/common (rework-autopilot 5.1), so the control
+// plane validates assistants with the same rules Autopilot runs with.
+var common_1 = require("@fonoster/common");
+Object.defineProperty(exports, "sessionAssistantSchema", { enumerable: true, get: function () { return common_1.sessionAssistantSchema; } });
+Object.defineProperty(exports, "sessionConversationSettingsSchema", { enumerable: true, get: function () { return common_1.sessionConversationSettingsSchema; } });
+Object.defineProperty(exports, "sessionLanguageModelSchema", { enumerable: true, get: function () { return common_1.sessionLanguageModelSchema; } });

package/dist/session/convertLegacyAssistant.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { SessionAssistant } from "./config";
+type Legacy = {
+    conversationSettings?: Record<string, unknown> & {
+        maxSpeechWaitTimeout?: number;
+        vad?: unknown;
+        transferOptions?: {
+            phoneNumber: string;
+            message: string;
+            timeout?: number;
+        };
+    };
+    languageModel?: Record<string, unknown> & {
+        provider?: string;
+        model?: string;
+        apiKey?: string;
+        baseUrl?: string;
+    };
+    eventsHook?: {
+        url: string;
+        events?: string[];
+        headers?: Record<string, string>;
+    };
+    audioFilters?: unknown;
+    testCases?: unknown;
+};
+/**
+ * VAD-era settings → the patience knob (add-turn-taking 3.2, AP-B3). maxSpeechWaitTimeout was
+ * extra waiting after the caller's speech before answering; 0 (the old default) is today's
+ * behaviour, normal. Any extra wait becomes high (about 1.6 × the gateway's silence timeout, and
+ * more as the gateway adapts to a caller who pauses). Nothing maps to low: the old settings had
+ * no way to answer faster than the default. allowUserBargeIn keeps its meaning: it sets
+ * `interruptible` on every speak and whether Autopilot sends clear on turn.user_started.
+ */
+export declare function patienceFor(maxSpeechWaitTimeout?: number): "low" | "normal" | "high";
+export type AssistantConversion = {
+    assistant: SessionAssistant;
+    /**
+     * An inline key to store as the workspace's key for `providerId` (the config no longer holds
+     * it). The migration job binds it like the dashboard's Vendor keys page does (a Secret named
+     * `provider-key/<provider>` in workspace_provider_keys), which is where the registry's
+     * credentialRef lookup finds workspace keys (AP-B4, LG-B1).
+     */
+    secret?: {
+        providerId: string;
+        name: string;
+        value: string;
+    };
+    /** The retired eventsHook URL, for creating a workspace webhook endpoint. */
+    webhook?: {
+        url: string;
+    };
+    /** Audio filters that now belong in the app's configuration. */
+    appFilters?: unknown;
+    notices: string[];
+};
+export declare function convertLegacyAssistant(old: Legacy, options: {
+    assistantRef: string;
+}): AssistantConversion;
+export {};

package/dist/session/convertLegacyAssistant.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patienceFor = patienceFor;
+exports.convertLegacyAssistant = convertLegacyAssistant;
+/**
+ * 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 config_1 = require("./config");
+// The one-time conversion of stored assistants at cutover (owner decision, rework-autopilot 5.3).
+// It never writes anything itself: it returns the new config plus what the migration job must do
+// around it (create a workspace Secret, a webhook endpoint, app audio filters) and notices for the
+// workspace.
+const PROVIDERS = ["openai", "groq", "ollama", "google", "anthropic"];
+const PLACEHOLDER_KEYS = new Set(["", "your-api-key", "changeme", "xxx"]);
+/**
+ * VAD-era settings → the patience knob (add-turn-taking 3.2, AP-B3). maxSpeechWaitTimeout was
+ * extra waiting after the caller's speech before answering; 0 (the old default) is today's
+ * behaviour, normal. Any extra wait becomes high (about 1.6 × the gateway's silence timeout, and
+ * more as the gateway adapts to a caller who pauses). Nothing maps to low: the old settings had
+ * no way to answer faster than the default. allowUserBargeIn keeps its meaning: it sets
+ * `interruptible` on every speak and whether Autopilot sends clear on turn.user_started.
+ */
+function patienceFor(maxSpeechWaitTimeout) {
+    return (maxSpeechWaitTimeout ?? 0) > 0 ? "high" : "normal";
+}
+const DEFAULT_VAD = {
+    activationThreshold: 0.4,
+    deactivationThreshold: 0.25,
+    debounceFrames: 4
+};
+function isDefaultVad(vad) {
+    if (!vad || typeof vad !== "object")
+        return true;
+    const v = vad;
+    return Object.keys(DEFAULT_VAD).every((k) => v[k] === undefined || v[k] === DEFAULT_VAD[k]);
+}
+function convertLegacyAssistant(old, options) {
+    const notices = [];
+    const lm = { ...(old.languageModel ?? {}) };
+    const cs = { ...(old.conversationSettings ?? {}) };
+    const result = { notices };
+    const provider = String(lm.provider ?? "");
+    if (!PROVIDERS.includes(provider))
+        throw new Error(`unknown language model provider "${provider}"`);
+    const model = `${provider}/${lm.model}`;
+    if (typeof lm.apiKey === "string" &&
+        !PLACEHOLDER_KEYS.has(lm.apiKey.trim())) {
+        void options.assistantRef;
+        result.secret = {
+            providerId: provider,
+            name: `provider-key/${provider}`,
+            value: lm.apiKey
+        };
+        notices.push(`The ${provider} key moved out of the assistant into the workspace's ${provider} vendor key (Secret "${result.secret.name}").`);
+    }
+    if (lm.baseUrl) {
+        notices.push(`The custom model endpoint ${lm.baseUrl} was removed; endpoints now come from the provider registry.`);
+    }
+    const patience = patienceFor(cs.maxSpeechWaitTimeout);
+    if (patience !== "normal") {
+        notices.push(`maxSpeechWaitTimeout (${cs.maxSpeechWaitTimeout} ms) became patience "${patience}"; turn timing now comes from the gateway.`);
+    }
+    if (cs.vad !== undefined && !isDefaultVad(cs.vad))
+        notices.push("Custom VAD settings were removed; turn detection now runs in the gateway. For noisy lines use the app's audio filters or a more patient setting.");
+    if (cs.transferOptions?.timeout !== undefined &&
+        cs.transferOptions.timeout !== 30000) {
+        notices.push(`The transfer timeout (${cs.transferOptions.timeout} ms) is no longer configurable per assistant.`);
+    }
+    if (old.eventsHook?.url) {
+        result.webhook = { url: old.eventsHook.url };
+        notices.push(`Assistant webhooks are retired; create a workspace webhook for ${old.eventsHook.url} (call.started, call.ended, call_record.sealed).`);
+    }
+    if (old.audioFilters !== undefined) {
+        result.appFilters = old.audioFilters;
+        notices.push("Audio filters moved to the app's configuration.");
+    }
+    const { maxSpeechWaitTimeout, vad, transferOptions, ...settings } = cs;
+    void vad;
+    void maxSpeechWaitTimeout;
+    const assistant = config_1.sessionAssistantSchema.parse({
+        conversationSettings: {
+            ...settings,
+            ...(transferOptions
+                ? {
+                    transferOptions: {
+                        phoneNumber: transferOptions.phoneNumber,
+                        message: transferOptions.message
+                    }
+                }
+                : {}),
+            ...(patience !== "normal" ? { patience } : {})
+        },
+        languageModel: {
+            model,
+            temperature: lm.temperature,
+            maxTokens: lm.maxTokens,
+            tools: lm.tools,
+            knowledgeBase: lm.knowledgeBase
+        },
+        ...(old.testCases !== undefined ? { testCases: old.testCases } : {})
+    });
+    return { ...result, assistant };
+}

package/dist/session/createAutopilot.d.ts

@@ -0,0 +1,47 @@
+import { Agent, Recorder } from "./Agent";
+import { SessionAssistant } from "./config";
+import { KnowledgePort } from "./knowledge";
+import { LlmResolver } from "./llm";
+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 LoadedAssistant = {
+    assistant: unknown;
+    /** The workspace that owns the app: scope for its own keys (BYOK) and knowledge. */
+    workspaceRef?: string;
+};
+export type AutopilotOptions = {
+    /** The assistant for a session (validated with the session assistant schema). */
+    assistant?: unknown | ((session: Session) => Promise<unknown> | unknown);
+    /**
+     * The hosted path: loads the app's assistant and workspace for a session; undefined means the
+     * app has no assistant (the call is ended).
+     */
+    load?: (session: Session) => Promise<LoadedAssistant | 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 assistant (operator wiring, task 4.1). */
+    knowledgeFor?: (assistant: SessionAssistant, scope: {
+        workspaceRef?: string;
+    }) => 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,119 @@
+"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 machine_1 = require("./machine");
+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) {
+    return async (session) => {
+        // Listen before any await: turn events that arrive while the assistant 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" }));
+        const ended = new Promise((resolve) => session.on("end", () => {
+            deliver({ type: "SESSION_END" });
+            resolve();
+        }));
+        const loaded = options.load
+            ? await options.load(session)
+            : {
+                assistant: typeof options.assistant === "function"
+                    ? await options.assistant(session)
+                    : options.assistant
+            };
+        if (!loaded) {
+            logger.warn("no assistant for this app; ending the call", {
+                appRef: session.appRef,
+                callRef: session.callRef
+            });
+            await session.hangup().catch(() => undefined);
+            return;
+        }
+        const assistant = config_1.sessionAssistantSchema.parse(loaded.assistant);
+        const scope = { workspaceRef: loaded.workspaceRef };
+        const recorder = options.recorder ?? (0, Agent_1.sessionRecorder)(session);
+        const settings = {
+            temperature: assistant.languageModel.temperature,
+            maxTokens: assistant.languageModel.maxTokens
+        };
+        let think = options.think;
+        if (!think && options.llm) {
+            try {
+                const resolved = await options.llm.resolve(assistant.languageModel.model, settings, scope);
+                think = resolved.think;
+                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.message
+                });
+                await session
+                    .say(assistant.conversationSettings.systemErrorMessage, {
+                    interruptible: false
+                })
+                    .catch(() => undefined);
+                await session.hangup().catch(() => undefined);
+                return;
+            }
+        }
+        think ?? (think = (0, think_1.resolveThink)(assistant.languageModel.model, options.providers ?? {}, settings));
+        const agent = new Agent_1.Agent(session, assistant, think, options.tools ??
+            new tools_1.HttpToolPort(assistant.languageModel.tools, {
+                allow: options.allowedDestinations
+            }), recorder, options.knowledge ?? options.knowledgeFor?.(assistant, scope));
+        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();
+    };
+}