@fonoster/autopilot 0.27.0 → 0.31.0

package/dist/session/llm.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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;
+}
+/**
+ * A workspace's own key could not be read (its store failed). It never falls back to the platform
+ * key (remove-platform-key-fallback): the session ends with reason key_unavailable.
+ */
+export declare class KeyUnavailableError extends Error {
+    readonly ref: string;
+    readonly reason = "key_unavailable";
+    constructor(ref: string, cause?: unknown);
+}
+/** A key and whose it is: the workspace's own (or its private region's), or the platform's. */
+export type ResolvedCredential = {
+    key: string;
+    source: "workspace" | "platform";
+};
+/** 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>;
+    /**
+     * The first key found and whose it is (add-usage-metering): the operator's config holds the
+     * platform keys; every other source holds the workspace's own.
+     */
+    resolve(ref: string, scope: {
+        workspaceRef?: string;
+    }): Promise<ResolvedCredential | undefined>;
+}
+/** A credential and its source; a source that cannot tell is the platform's. */
+export declare function resolveCredential(credentials: CredentialSource, ref: string, scope: {
+    workspaceRef?: string;
+}): Promise<ResolvedCredential | undefined>;
+/** 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;
+    /** Whose key the model is called with; keyless providers count as the platform's. */
+    keySource: "workspace" | "platform";
+    /** 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 provider or adapter id (e.g. a local ollama); win over the catalog's. */
+    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>;
+}

package/dist/session/llm.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistryLlmResolver = exports.LlmResolutionError = exports.OPENAI_COMPATIBLE = exports.LayeredCredentials = exports.KeyUnavailableError = exports.ConfigCredentials = void 0;
+exports.resolveCredential = resolveCredential;
+const community_1 = require("@fonoster/community");
+const openai_1 = require("@fonoster/community/openai");
+Object.defineProperty(exports, "OPENAI_COMPATIBLE", { enumerable: true, get: function () { return openai_1.OPENAI_COMPATIBLE; } });
+/**
+ * Platform credentials from operator config: `{ "<credentialRef>": { env } | { value } }`. The
+ * variable names are operator choices; Autopilot never reads a vendor variable by itself.
+ */
+class ConfigCredentials {
+    constructor(refs) {
+        this.refs = refs;
+    }
+    get(ref) {
+        const c = this.refs[ref];
+        return c?.value ?? (c?.env ? process.env[c.env] : undefined);
+    }
+}
+exports.ConfigCredentials = ConfigCredentials;
+/**
+ * A workspace's own key could not be read (its store failed). It never falls back to the platform
+ * key (remove-platform-key-fallback): the session ends with reason key_unavailable.
+ */
+class KeyUnavailableError extends Error {
+    constructor(ref, cause) {
+        super(`the workspace's key ${ref} could not be read: ${cause?.message ?? cause}`);
+        this.ref = ref;
+        this.reason = "key_unavailable";
+    }
+}
+exports.KeyUnavailableError = KeyUnavailableError;
+/** Workspace Secrets (BYOK) in front of platform credentials. */
+class LayeredCredentials {
+    constructor(sources) {
+        this.sources = sources;
+    }
+    async get(ref, scope) {
+        return (await this.resolve(ref, scope))?.key;
+    }
+    /**
+     * The first key found and whose it is (add-usage-metering): the operator's config holds the
+     * platform keys; every other source holds the workspace's own.
+     */
+    async resolve(ref, scope) {
+        for (const s of this.sources) {
+            let key;
+            try {
+                key = await s.get(ref, scope);
+            }
+            catch (e) {
+                if (s instanceof ConfigCredentials)
+                    throw e;
+                throw new KeyUnavailableError(ref, e);
+            }
+            if (key)
+                return {
+                    key,
+                    source: s instanceof ConfigCredentials ? "platform" : "workspace"
+                };
+        }
+        return undefined;
+    }
+}
+exports.LayeredCredentials = LayeredCredentials;
+/** A credential and its source; a source that cannot tell is the platform's. */
+async function resolveCredential(credentials, ref, scope) {
+    if (credentials instanceof LayeredCredentials)
+        return credentials.resolve(ref, scope);
+    const key = await credentials.get(ref, scope);
+    return key ? { key, source: "platform" } : undefined;
+}
+class LlmResolutionError extends Error {
+}
+exports.LlmResolutionError = LlmResolutionError;
+class RegistryLlmResolver {
+    constructor(options) {
+        this.options = options;
+    }
+    async resolve(catalogId, settings, scope = {}) {
+        const { registry } = this.options;
+        const resolution = registry.resolve(catalogId);
+        const id = resolution.id;
+        const entries = registry.list();
+        const model = entries.find((e) => e.id === id);
+        if (!model || model.kind !== "model" || model.type !== "llm")
+            throw new LlmResolutionError(`${catalogId} is not a language model in the catalog`);
+        const providerId = id.slice(0, id.indexOf("/"));
+        const provider = entries.find((e) => e.id === providerId);
+        if (!provider || provider.kind !== "provider")
+            throw new LlmResolutionError(`no provider ${providerId} for ${id}`);
+        if (provider.state === "retired")
+            throw new LlmResolutionError(`provider ${providerId} is retired`);
+        const llm = (0, community_1.adapterFor)(provider.adapter)?.llm;
+        if (!llm)
+            throw new LlmResolutionError(`adapter ${provider.adapter} has no language model implementation in Autopilot yet`);
+        const baseUrl = this.options.endpoints?.[provider.id] ??
+            this.options.endpoints?.[provider.adapter] ??
+            provider.endpoints?.llm ??
+            llm.defaultEndpoint;
+        if (!baseUrl)
+            throw new LlmResolutionError(`no endpoint for provider ${provider.id} (adapter ${provider.adapter})`);
+        // A provider without a credentialRef is keyless (local models, the fakes).
+        const credential = provider.credentialRef
+            ? await resolveCredential(this.options.credentials, provider.credentialRef, scope)
+            : undefined;
+        const apiKey = credential?.key;
+        if (provider.credentialRef && !apiKey)
+            throw new LlmResolutionError(`no credential ${provider.credentialRef} for provider ${provider.id}`);
+        return {
+            id,
+            keySource: credential?.source ?? "platform",
+            think: llm.create({ baseUrl, apiKey }, id.slice(providerId.length + 1), settings),
+            ...(resolution.event
+                ? {
+                    event: {
+                        type: resolution.event,
+                        id: catalogId,
+                        replacement: resolution.replacement
+                    }
+                }
+                : {})
+        };
+    }
+}
+exports.RegistryLlmResolver = RegistryLlmResolver;

package/dist/session/machine.d.ts

@@ -0,0 +1,206 @@
+import { Agent, AgentEvent } from "./Agent";
+/**
+ * Autopilot's states (rework-autopilot A4). The machine decides; the Agent acts on the session.
+ * The idle clock runs only in listening.
+ */
+export declare const autopilotMachine: import("xstate").StateMachine<{
+    agent: Agent;
+}, AgentEvent, {}, never, import("xstate").Values<{
+    transfer: {
+        type: "transfer";
+        params: unknown;
+    };
+    stop: {
+        type: "stop";
+        params: unknown;
+    };
+    prepare: {
+        type: "prepare";
+        params: unknown;
+    };
+    greet: {
+        type: "greet";
+        params: unknown;
+    };
+    armIdle: {
+        type: "armIdle";
+        params: unknown;
+    };
+    disarmIdle: {
+        type: "disarmIdle";
+        params: unknown;
+    };
+    sayIdle: {
+        type: "sayIdle";
+        params: unknown;
+    };
+    resumed: {
+        type: "resumed";
+        params: unknown;
+    };
+    answer: {
+        type: "answer";
+        params: unknown;
+    };
+    abortReply: {
+        type: "abortReply";
+        params: unknown;
+    };
+    clear: {
+        type: "clear";
+        params: unknown;
+    };
+    goodbye: {
+        type: "goodbye";
+        params: unknown;
+    };
+}>, import("xstate").Values<{
+    spokenFrom: {
+        type: "spokenFrom";
+        params: string[];
+    };
+    bargeIn: {
+        type: "bargeIn";
+        params: unknown;
+    };
+    idleExhausted: {
+        type: "idleExhausted";
+        params: unknown;
+    };
+}>, never, "greeting" | "listening" | "thinking" | "ending" | "speaking" | "transferring" | "ended", string, {
+    agent: Agent;
+}, {}, import("xstate").EventObject, import("xstate").MetaObject, {
+    readonly id: "autopilot";
+    readonly initial: "greeting";
+    readonly context: ({ input }: {
+        spawn: {
+            <TSrc extends never>(logic: TSrc, ...[options]: never): import("xstate").ActorRefFromLogic<never>;
+            <TLogic extends import("xstate").AnyActorLogic>(src: TLogic, options?: {
+                id?: never;
+                systemId?: string;
+                input?: import("xstate").InputFrom<TLogic>;
+                syncSnapshot?: boolean;
+            }): import("xstate").ActorRefFromLogic<TLogic>;
+        };
+        input: {
+            agent: Agent;
+        };
+        self: import("xstate").ActorRef<import("xstate").MachineSnapshot<{
+            agent: Agent;
+        }, AgentEvent, Record<string, import("xstate").AnyActorRef>, import("xstate").StateValue, string, unknown, any, any>, AgentEvent, import("xstate").AnyEventObject>;
+    }) => {
+        agent: Agent;
+    };
+    readonly on: {
+        readonly SESSION_END: ".ended";
+        readonly MAX_DURATION: ".ending";
+        readonly HANGUP_REQUESTED: ".ending";
+        readonly TRANSFER_REQUESTED: ".transferring";
+        readonly TURN_BACKCHANNEL: {};
+    };
+    readonly states: {
+        readonly greeting: {
+            readonly entry: "greet";
+            readonly on: {
+                readonly SPOKEN: {
+                    readonly guard: {
+                        readonly type: "spokenFrom";
+                        readonly params: ["greeting"];
+                    };
+                    readonly target: "listening";
+                };
+                readonly TURN_USER_STARTED: {
+                    readonly guard: "bargeIn";
+                    readonly actions: "clear";
+                };
+                readonly TURN_LIKELY_ENDED: {
+                    readonly actions: "prepare";
+                };
+                readonly TURN_RESUMED: {
+                    readonly actions: "resumed";
+                };
+                readonly TURN_ENDED: "thinking";
+            };
+        };
+        readonly listening: {
+            readonly entry: "armIdle";
+            readonly exit: "disarmIdle";
+            readonly on: {
+                readonly TURN_LIKELY_ENDED: {
+                    readonly actions: "prepare";
+                };
+                readonly TURN_RESUMED: {
+                    readonly actions: "resumed";
+                };
+                readonly TURN_ENDED: "thinking";
+                readonly IDLE: readonly [{
+                    readonly guard: "idleExhausted";
+                    readonly target: "ending";
+                }, {
+                    readonly target: "speaking";
+                    readonly actions: "sayIdle";
+                }];
+            };
+        };
+        readonly thinking: {
+            readonly entry: "answer";
+            readonly on: {
+                readonly REPLY_SPEAKING: "speaking";
+                readonly SPOKEN: {
+                    readonly guard: {
+                        readonly type: "spokenFrom";
+                        readonly params: ["reply", "error"];
+                    };
+                    readonly target: "listening";
+                };
+                readonly TURN_USER_STARTED: {
+                    readonly guard: "bargeIn";
+                    readonly actions: "clear";
+                };
+                readonly TURN_ENDED: {
+                    readonly target: "thinking";
+                    readonly reenter: true;
+                    readonly actions: "abortReply";
+                };
+            };
+        };
+        readonly speaking: {
+            readonly on: {
+                readonly SPOKEN: {
+                    readonly guard: {
+                        readonly type: "spokenFrom";
+                        readonly params: ["reply", "idle", "error"];
+                    };
+                    readonly target: "listening";
+                };
+                readonly TURN_USER_STARTED: {
+                    readonly guard: "bargeIn";
+                    readonly actions: "clear";
+                };
+                readonly TURN_ENDED: {
+                    readonly target: "thinking";
+                    readonly actions: "abortReply";
+                };
+            };
+        };
+        readonly transferring: {
+            readonly entry: "transfer";
+            readonly on: {
+                readonly SPOKEN: {
+                    readonly guard: {
+                        readonly type: "spokenFrom";
+                        readonly params: ["error"];
+                    };
+                    readonly target: "listening";
+                };
+            };
+        };
+        readonly ending: {
+            readonly entry: "goodbye";
+        };
+        readonly ended: {
+            readonly type: "final";
+            readonly entry: "stop";
+        };
+    };
+}>;

package/dist/session/machine.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autopilotMachine = 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.
+ */
+const xstate_1 = require("xstate");
+/**
+ * Autopilot's states (rework-autopilot A4). The machine decides; the Agent acts on the session.
+ * The idle clock runs only in listening.
+ */
+exports.autopilotMachine = (0, xstate_1.setup)({
+    types: {
+        context: {},
+        input: {},
+        events: {}
+    },
+    guards: {
+        spokenFrom: ({ event }, sources) => event.type === "SPOKEN" && sources.includes(event.source),
+        bargeIn: ({ context }) => context.agent.settings.allowUserBargeIn,
+        idleExhausted: ({ context }) => context.agent.idleExhausted()
+    },
+    actions: {
+        greet: ({ context }) => void context.agent.greet(),
+        armIdle: ({ context }) => context.agent.armIdle(),
+        disarmIdle: ({ context }) => context.agent.disarmIdle(),
+        sayIdle: ({ context }) => void context.agent.sayIdle(),
+        prepare: ({ context, event }) => context.agent.prepare(event.text),
+        resumed: ({ context }) => context.agent.resumed(),
+        answer: ({ context, event }) => void context.agent.answer(event.text),
+        abortReply: ({ context }) => context.agent.abortReply(),
+        clear: ({ context }) => void context.agent.clear(),
+        goodbye: ({ context }) => void context.agent.goodbye(),
+        transfer: ({ context }) => void context.agent.transfer(),
+        stop: ({ context }) => context.agent.stop()
+    }
+}).createMachine({
+    id: "autopilot",
+    initial: "greeting",
+    context: ({ input }) => ({ agent: input.agent }),
+    on: {
+        SESSION_END: ".ended",
+        MAX_DURATION: ".ending",
+        HANGUP_REQUESTED: ".ending",
+        TRANSFER_REQUESTED: ".transferring",
+        // Backchannels are not interruptions: nothing happens in any state.
+        TURN_BACKCHANNEL: {}
+    },
+    states: {
+        greeting: {
+            entry: "greet",
+            on: {
+                SPOKEN: {
+                    guard: { type: "spokenFrom", params: ["greeting"] },
+                    target: "listening"
+                },
+                TURN_USER_STARTED: { guard: "bargeIn", actions: "clear" },
+                TURN_LIKELY_ENDED: { actions: "prepare" },
+                TURN_RESUMED: { actions: "resumed" },
+                TURN_ENDED: "thinking"
+            }
+        },
+        listening: {
+            entry: "armIdle",
+            exit: "disarmIdle",
+            on: {
+                TURN_LIKELY_ENDED: { actions: "prepare" },
+                TURN_RESUMED: { actions: "resumed" },
+                TURN_ENDED: "thinking",
+                IDLE: [
+                    { guard: "idleExhausted", target: "ending" },
+                    { target: "speaking", actions: "sayIdle" }
+                ]
+            }
+        },
+        thinking: {
+            entry: "answer",
+            on: {
+                REPLY_SPEAKING: "speaking",
+                SPOKEN: {
+                    guard: { type: "spokenFrom", params: ["reply", "error"] },
+                    target: "listening"
+                },
+                TURN_USER_STARTED: { guard: "bargeIn", actions: "clear" },
+                // A new turn cancels the reply in flight; its user text stays in the history.
+                TURN_ENDED: { target: "thinking", reenter: true, actions: "abortReply" }
+            }
+        },
+        speaking: {
+            on: {
+                SPOKEN: {
+                    guard: { type: "spokenFrom", params: ["reply", "idle", "error"] },
+                    target: "listening"
+                },
+                TURN_USER_STARTED: { guard: "bargeIn", actions: "clear" },
+                TURN_ENDED: { target: "thinking", actions: "abortReply" }
+            }
+        },
+        transferring: {
+            entry: "transfer",
+            on: {
+                SPOKEN: {
+                    guard: { type: "spokenFrom", params: ["error"] },
+                    target: "listening"
+                }
+            }
+        },
+        ending: { entry: "goodbye" },
+        ended: { type: "final", entry: "stop" }
+    }
+});

package/dist/session/main.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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.
+ */
+// Autopilot's entry point (rework-autopilot task 4.3; the only engine since cleanbreak CB-B5):
+//
+//   node dist/session/main.js --config /config/autopilot.yaml
+const common_1 = require("@fonoster/common");
+const logger_1 = require("@fonoster/logger");
+const hosted_1 = require("./hosted");
+const telemetry_1 = require("./telemetry");
+const logger = (0, logger_1.getLogger)({ service: "autopilot", filePath: __filename });
+(0, common_1.logUnhandledRejections)(logger);
+// --config, AUTOPILOT_SESSION_CONFIG, else /config/autopilot.yaml (or an older location).
+const at = process.argv.indexOf("--config");
+const file = at >= 0
+    ? process.argv[at + 1]
+    : (process.env.AUTOPILOT_SESSION_CONFIG ?? (0, hosted_1.findHostedConfig)());
+if (!file) {
+    logger.error("no Autopilot config file: mount /config/autopilot.yaml or pass --config <file>");
+    process.exit(1);
+}
+const config = (0, hosted_1.loadHostedConfig)(file);
+// Off unless an OTLP endpoint is configured (telemetry.otlpEndpoint or OTEL_EXPORTER_OTLP_*).
+(0, telemetry_1.startTelemetry)(config.telemetry);
+(0, hosted_1.startHostedAutopilot)(config).catch((e) => {
+    logger.error(`hosted autopilot failed to start: ${e.message}`);
+    process.exit(1);
+});

package/dist/session/meteredThink.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { Usage } from "@fonoster/common";
+import { Think, TokenUsage } from "@fonoster/community";
+/** Where a model's usage goes: Autopilot sends it to the call (usage.report). */
+export type UsageSink = {
+    usage(lines: Usage.UsageLine[]): void;
+    /** A completed request whose vendor reported no usage (add-usage-metering). */
+    missing(catalogId: string): void;
+};
+export type MeteredModel = {
+    /** The catalog id (`<provider>/<model>`). */
+    catalogId: string;
+    keySource: Usage.KeySource;
+};
+/** How long an interrupted reply is read in the background for its usage report (design D6). */
+export declare const DRAIN_DEADLINE_MS = 30000;
+export declare function usageLines(model: MeteredModel, usage: TokenUsage): Usage.UsageLine[];
+/**
+ * A Think that meters its model (add-usage-metering D6). Chunks pass through; the vendor's usage
+ * chunk is reported, never forwarded. When the caller stops reading (barge-in, a newer turn), the
+ * stream ends for the caller at once but keeps being read in the background, so the vendor's usage
+ * for the whole request still arrives; after the deadline, or when `closed` aborts (the session
+ * ended), the request is reported as missing usage. A request the vendor failed reports nothing.
+ */
+export declare function meteredThink(inner: Think, model: MeteredModel, sink: UsageSink, options?: {
+    drainMs?: number;
+    closed?: AbortSignal;
+}): Think;