@fonoster/autopilot 0.30.0 → 0.31.0

package/dist/session/createAutopilot.js

@@ -23,7 +23,10 @@ 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 });
@@ -32,8 +35,26 @@ const logger = (0, logger_1.getLogger)({ service: "autopilot", filePath: __filen
  * runs the state machine on the session's public messages only.
  */
 function createAutopilotHandler(options) {
+    const run = createSessionRunner(options);
     return async (session) => {
-        // Listen before any await: turn events that arrive while the assistant and model load are
+        // 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);
@@ -47,37 +68,48 @@ function createAutopilotHandler(options) {
                 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)
             : {
-                assistant: typeof options.assistant === "function"
-                    ? await options.assistant(session)
-                    : options.assistant
+                agent: typeof options.agent === "function"
+                    ? await options.agent(session)
+                    : options.agent
             };
         if (!loaded) {
-            logger.warn("no assistant for this app; ending the call", {
+            logger.warn("no agent 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 agentConfig = config_1.sessionAgentSchema.parse(loaded.agent);
         const scope = { workspaceRef: loaded.workspaceRef };
         const recorder = options.recorder ?? (0, Agent_1.sessionRecorder)(session);
         const settings = {
-            temperature: assistant.languageModel.temperature,
-            maxTokens: assistant.languageModel.maxTokens
+            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(assistant.languageModel.model, settings, scope);
-                think = resolved.think;
+                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);
             }
@@ -86,10 +118,10 @@ function createAutopilotHandler(options) {
                 logger.error(`autopilot cannot reach its language model: ${e.message}`);
                 recorder.note({
                     type: "llm.unavailable",
-                    reason: e.message
+                    reason: e instanceof llm_1.KeyUnavailableError ? e.reason : e.message
                 });
                 await session
-                    .say(assistant.conversationSettings.systemErrorMessage, {
+                    .say(agentConfig.conversationSettings.systemErrorMessage, {
                     interruptible: false
                 })
                     .catch(() => undefined);
@@ -97,11 +129,11 @@ function createAutopilotHandler(options) {
                 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, {
+        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?.(assistant, scope));
+            }), 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);

package/dist/session/hosted.d.ts

@@ -1,10 +1,11 @@
 import { CellSecrets, Registry } from "@fonoster/common";
 import { Session, VoiceServer } from "@fonoster/voice";
 import { z } from "zod";
-import { SessionAssistant } from "./config";
-import { AutopilotOptions, LoadedAssistant } from "./createAutopilot";
+import { 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>;
@@ -13,7 +14,7 @@ export declare const hostedConfigSchema: z.ZodObject<{
      * FONOSTER_ALLOWED_DESTINATIONS.
      */
     allowedDestinations: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    /** The secret the gateway signs Autopilot sessions with (one for every Autopilot app). */
+    /** The secret AppBridge signs Autopilot sessions with (one for every Autopilot app). */
     signingSecret: z.ZodUnion<[z.ZodObject<{
         env: z.ZodString;
     }, "strict", z.ZodTypeAny, {
@@ -34,10 +35,10 @@ export declare const hostedConfigSchema: z.ZodObject<{
      */
     publicUrl: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
     /**
-     * Apps and their assistants: a file `{apps: {<appRef>: {workspaceRef?, assistant}}}` (JSON or
+     * Apps and their agents: a file `{apps: {<appRef>: {workspaceRef?, agent}}}` (JSON or
      * YAML), or `database`: the apps' Intelligence rows, cached for `cacheMs` (CP-B11).
      */
-    assistants: z.ZodUnion<[z.ZodObject<{
+    agents: z.ZodUnion<[z.ZodObject<{
         file: z.ZodString;
     }, "strict", z.ZodTypeAny, {
         file?: string;
@@ -142,7 +143,7 @@ export declare const hostedConfigSchema: z.ZodObject<{
         url?: string;
         clientModule?: string;
     }>>;
-    /** Endpoint overrides by adapter or provider id (e.g. a local ollama, the fake LLM). */
+    /** 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<{
@@ -227,7 +228,6 @@ export declare const hostedConfigSchema: z.ZodObject<{
     }, {
         otlpEndpoint?: string;
     }>>;
-    testMode: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     registry?: {
         file?: string;
@@ -244,7 +244,7 @@ export declare const hostedConfigSchema: z.ZodObject<{
         value?: string;
     };
     publicUrl?: string | string[];
-    assistants?: {
+    agents?: {
         file?: string;
     } | {
         source?: "database";
@@ -292,7 +292,6 @@ export declare const hostedConfigSchema: z.ZodObject<{
     telemetry?: {
         otlpEndpoint?: string;
     };
-    testMode?: boolean;
 }, {
     registry?: {
         file?: string;
@@ -309,7 +308,7 @@ export declare const hostedConfigSchema: z.ZodObject<{
         value?: string;
     };
     publicUrl?: string | string[];
-    assistants?: {
+    agents?: {
         file?: string;
     } | {
         source?: "database";
@@ -357,7 +356,6 @@ export declare const hostedConfigSchema: z.ZodObject<{
     telemetry?: {
         otlpEndpoint?: string;
     };
-    testMode?: boolean;
 }>;
 export type HostedConfig = z.infer<typeof hostedConfigSchema>;
 /** Where Autopilot looks for its file when none is named (autopilot.yaml, then the older name). */
@@ -369,17 +367,17 @@ export declare function findHostedConfig(): string | undefined;
  * placeholders from the container environment, `secret://` references, strict validation.
  */
 export declare function loadHostedConfig(file: string, env?: Record<string, string | undefined>): HostedConfig;
-/** Apps and assistants from a file (a stand-in until assistants come from the control plane). */
-export declare class FileAssistantSource {
+/** 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<LoadedAssistant | undefined>;
+    get(appRef: string): Promise<LoadedAgent | undefined>;
 }
 /**
- * Assistants from the control plane: an Autopilot app's Intelligence row holds its assistant
+ * 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 PrismaAssistantSource {
+export declare class PrismaAgentSource {
     private readonly prisma;
     private readonly options;
     private cache;
@@ -387,7 +385,7 @@ export declare class PrismaAssistantSource {
         cacheMs?: number;
         now?: () => number;
     });
-    get(appRef: string): Promise<LoadedAssistant | undefined>;
+    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 {
@@ -424,13 +422,13 @@ type KnowledgeBaseLike = {
     queryKnowledgeBase(query: string, k?: number): Promise<string>;
 };
 /**
- * Builds the knowledge port for an assistant from the operator's S3 + Unstructured settings,
+ * 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): (assistant: SessionAssistant, scope: {
+export declare function s3Knowledge(config: NonNullable<HostedConfig["knowledge"]>, credentials: CredentialSource, make?: (params: Record<string, unknown>) => KnowledgeBaseLike): (agent: SessionAgent, scope: {
     workspaceRef?: string;
-}) => Promise<KnowledgePort | undefined>;
+}, 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;
@@ -440,17 +438,17 @@ export declare function hostedOptions(config: HostedConfig, deps?: {
  * like any). A port that fails to build is logged and answers nothing: the eager promise always
  * has a handler, so a failure never becomes an unhandled rejection (RV-B5).
  */
-export declare function eagerKnowledge(build: (assistant: SessionAssistant, scope: {
+export declare function eagerKnowledge(build: (agent: SessionAgent, scope: {
     workspaceRef?: string;
-}) => Promise<KnowledgePort | undefined>): (assistant: SessionAssistant, scope: {
+}, usage?: UsageSink) => Promise<KnowledgePort | undefined>): (agent: SessionAgent, scope: {
     workspaceRef?: string;
-}) => KnowledgePort;
+}, usage?: UsageSink) => KnowledgePort;
 /**
- * The app's assistant only when the app belongs to the workspace the gateway signed for: one
+ * 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: LoadedAssistant | undefined): LoadedAssistant | undefined;
+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 {};

package/dist/session/hosted.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 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.FileWorkspaceSecrets = exports.CellSecretCredentials = exports.DatabaseWorkspaceSecrets = exports.PrismaAgentSource = exports.FileAgentSource = exports.AUTOPILOT_CONFIG_DIRS = exports.hostedConfigSchema = void 0;
 exports.findHostedConfig = findHostedConfig;
 exports.loadHostedConfig = loadHostedConfig;
 exports.s3Knowledge = s3Knowledge;
@@ -66,10 +66,11 @@ const logger_1 = require("@fonoster/logger");
 const voice_1 = require("@fonoster/voice");
 const yaml = __importStar(require("js-yaml"));
 const zod_1 = require("zod");
+const MeteredEmbeddings_1 = require("../knowledge/MeteredEmbeddings");
 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
+// The hosted Autopilot (rework-autopilot A2, task 4.3): an ordinary VoiceServer that AppBridge
 // 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 });
@@ -87,7 +88,7 @@ exports.hostedConfigSchema = zod_1.z
      * 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). */
+    /** The secret AppBridge 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
@@ -104,10 +105,10 @@ exports.hostedConfigSchema = zod_1.z
         })
     }),
     /**
-     * Apps and their assistants: a file `{apps: {<appRef>: {workspaceRef?, assistant}}}` (JSON or
+     * Apps and their agents: a file `{apps: {<appRef>: {workspaceRef?, agent}}}` (JSON or
      * YAML), or `database`: the apps' Intelligence rows, cached for `cacheMs` (CP-B11).
      */
-    assistants: zod_1.z.union([
+    agents: zod_1.z.union([
         zod_1.z.object({ file: zod_1.z.string() }).strict(),
         zod_1.z
             .object({
@@ -163,7 +164,7 @@ exports.hostedConfigSchema = zod_1.z
     })
         .strict()
         .optional(),
-    /** Endpoint overrides by adapter or provider id (e.g. a local ollama, the fake LLM). */
+    /** Endpoint overrides by provider or adapter id (e.g. a local ollama); the catalog's otherwise. */
     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
@@ -187,8 +188,7 @@ exports.hostedConfigSchema = zod_1.z
         .strict()
         .optional(),
     /** OTLP export (empty = off): `otlpEndpoint: "${OTEL_EXPORTER_OTLP_ENDPOINT:-}"`. */
-    telemetry: common_1.telemetrySchema,
-    testMode: zod_1.z.boolean().default(false)
+    telemetry: common_1.telemetrySchema
 })
     .strict();
 function readStructured(file) {
@@ -216,16 +216,12 @@ function loadHostedConfig(file, env = process.env) {
         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}")'
-        }
+        interpolatePaths: ["*"]
     });
     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) ||
+    const needsDb = !("file" in config.agents) ||
         !("file" in config.registry) ||
         (config.workspaceSecrets &&
             "source" in config.workspaceSecrets &&
@@ -234,7 +230,7 @@ function loadHostedConfig(file, env = process.env) {
         throw new Error("source: database needs a database section");
     return {
         ...config,
-        assistants: withFile(config.assistants),
+        agents: withFile(config.agents),
         registry: withFile(config.registry),
         ...(config.workspaceSecrets
             ? { workspaceSecrets: withFile(config.workspaceSecrets) }
@@ -242,8 +238,8 @@ function loadHostedConfig(file, env = process.env) {
     };
 }
 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 {
+/** Apps and agents from a file (a stand-in until agents come from the control plane). */
+class FileAgentSource {
     constructor(file) {
         this.file = file;
     }
@@ -251,16 +247,16 @@ class FileAssistantSource {
         const data = readStructured(this.file);
         const app = data.apps?.[appRef];
         return app
-            ? { assistant: app.assistant, workspaceRef: app.workspaceRef }
+            ? { agent: app.agent, workspaceRef: app.workspaceRef }
             : undefined;
     }
 }
-exports.FileAssistantSource = FileAssistantSource;
+exports.FileAgentSource = FileAgentSource;
 /**
- * Assistants from the control plane: an Autopilot app's Intelligence row holds its assistant
+ * 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.
  */
-class PrismaAssistantSource {
+class PrismaAgentSource {
     constructor(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     prisma, options = {}) {
@@ -278,13 +274,13 @@ class PrismaAssistantSource {
             include: { intelligence: true }
         });
         const value = row && row.type === "AUTOPILOT" && row.intelligence?.config
-            ? { assistant: row.intelligence.config, workspaceRef: row.accessKeyId }
+            ? { agent: row.intelligence.config, workspaceRef: row.accessKeyId }
             : undefined;
         this.cache.set(appRef, { at: now, value });
         return value;
     }
 }
-exports.PrismaAssistantSource = PrismaAssistantSource;
+exports.PrismaAgentSource = PrismaAgentSource;
 /** Workspace vendor keys from the database, looked up by the credentialRef's providers. */
 class DatabaseWorkspaceSecrets {
     constructor(keys, providers) {
@@ -323,13 +319,13 @@ class FileWorkspaceSecrets {
 }
 exports.FileWorkspaceSecrets = FileWorkspaceSecrets;
 /**
- * Builds the knowledge port for an assistant from the operator's S3 + Unstructured settings,
+ * 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).
  */
 function s3Knowledge(config, credentials, make) {
-    return async (assistant, scope) => {
-        const documents = assistant.languageModel.knowledgeBase.map((d) => d.document);
+    return async (agent, scope, usage) => {
+        const documents = agent.languageModel.knowledgeBase.map((d) => d.document);
         if (!documents.length || !scope.workspaceRef)
             return undefined;
         const key = (ref) => credentials.get(ref, scope);
@@ -337,7 +333,7 @@ function s3Knowledge(config, credentials, make) {
             key(config.s3.accessKeyIdRef),
             key(config.s3.secretAccessKeyRef),
             key(config.unstructured.apiKeyRef),
-            key(config.embeddings.apiKeyRef)
+            (0, llm_1.resolveCredential)(credentials, config.embeddings.apiKeyRef, scope)
         ]);
         const params = {
             bucket: scope.workspaceRef.toLowerCase(),
@@ -353,7 +349,9 @@ function s3Knowledge(config, credentials, make) {
             },
             unstructuredAPIURL: config.unstructured.url,
             unstructuredAPIKey: unstructuredKey ?? "",
-            embeddingsApiKey: embeddingsKey ?? ""
+            embeddingsApiKey: embeddingsKey?.key ?? "",
+            embeddingsKeySource: embeddingsKey?.source ?? "platform",
+            usage
         };
         const kb = (make ?? defaultKnowledgeBase)(params);
         kb.load().catch((e) => logger.warn(`knowledge base did not load: ${e.message}`));
@@ -365,11 +363,14 @@ function defaultKnowledgeBase(params) {
     // 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 })
+        // Metered: the vendor's token usage reaches the call (add-usage-metering).
+        embeddings: new MeteredEmbeddings_1.MeteredEmbeddings({
+            apiKey: String(params.embeddingsApiKey ?? ""),
+            keySource: params.embeddingsKeySource,
+            sink: params.usage
+        })
     });
 }
 /** Opens the control-plane database named in the config (once). */
@@ -407,17 +408,11 @@ deps = {}) {
     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 registry = new common_1.Registry.Registry({ store });
     const providers = () => store
         .all()
-        .filter((e) => e.kind === "provider")
-        .map((e) => ({
-        id: e.id,
-        credentialRef: e.credentialRef
-    }));
+        .filter((e) => e.kind === "provider" && Boolean(e.credentialRef))
+        .map((e) => ({ id: e.id, credentialRef: e.credentialRef }));
     const workspace = config.workspaceSecrets;
     const credentials = new llm_1.LayeredCredentials([
         ...(workspace
@@ -431,16 +426,16 @@ deps = {}) {
             : []),
         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 agents = "file" in config.agents
+        ? new FileAgentSource(config.agents.file)
+        : new PrismaAgentSource(db(), {
+            cacheMs: config.agents.cacheMs
         });
     const knowledge = config.knowledge
         ? s3Knowledge(config.knowledge, credentials)
         : undefined;
     return {
-        load: async (session) => signedWorkspaceOnly(session, await assistants.get(session.appRef)),
+        load: async (session) => signedWorkspaceOnly(session, await agents.get(session.appRef)),
         allowedDestinations: config.allowedDestinations,
         llm: new llm_1.RegistryLlmResolver({
             registry,
@@ -456,9 +451,9 @@ deps = {}) {
  * has a handler, so a failure never becomes an unhandled rejection (RV-B5).
  */
 function eagerKnowledge(build) {
-    return (assistant, scope) => {
+    return (agent, scope, usage) => {
         const port = Promise.resolve()
-            .then(() => build(assistant, scope))
+            .then(() => build(agent, scope, usage))
             .catch((e) => {
             logger.warn(`knowledge port unavailable: ${e?.message ?? e}`);
             return undefined;
@@ -472,7 +467,7 @@ function eagerKnowledge(build) {
     };
 }
 /**
- * The app's assistant only when the app belongs to the workspace the gateway signed for: one
+ * 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").
  */

package/dist/session/index.d.ts

@@ -18,12 +18,12 @@
  */
 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 "./telemetry";
 export * from "./think";
 export * from "./tools";

package/dist/session/index.js

@@ -34,12 +34,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 __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("./telemetry"), exports);
 __exportStar(require("./think"), exports);
 __exportStar(require("./tools"), exports);

package/dist/session/knowledge.d.ts

@@ -19,7 +19,7 @@
 /**
  * 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.
+ * the agent config.
  */
 export interface KnowledgePort {
     find(question: string, signal: AbortSignal): Promise<string>;

package/dist/session/llm.d.ts

@@ -37,6 +37,20 @@ export declare class ConfigCredentials implements CredentialSource {
     }>);
     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;
@@ -44,7 +58,18 @@ export declare class LayeredCredentials implements 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 {
@@ -53,6 +78,8 @@ 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;
@@ -71,7 +98,7 @@ export interface LlmResolver {
 export type RegistryLlmResolverOptions = {
     registry: Registry.Registry;
     credentials: CredentialSource;
-    /** Endpoint overrides by adapter or provider id (required for fake; e.g. a local ollama). */
+    /** 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 {