@fonoster/autopilot 0.30.0 → 0.31.0

package/dist/models/evaluations/session/runSessionEval.d.ts

@@ -1,17 +1,20 @@
-import { SessionAssistant } from "../../../session/config";
+import { SessionAgent } from "../../../session/config";
 import { Think } from "../../../session/think";
+import { createTestTextSimilarity } from "../createTestTextSimilarity";
 import { RunEvalCallbacks } from "../types";
 import { SessionEvalOptions, SessionScenarioReport } from "./evaluateSessionScenario";
 export type RunSessionEvalOptions = Omit<SessionEvalOptions, "testTextSimilarity"> & {
-    /** Defaults to the OpenAI similarity judge from the assistant's testCases. */
+    /** Defaults to the OpenAI similarity judge from the agent's testCases. */
     testTextSimilarity?: SessionEvalOptions["testTextSimilarity"];
     /** The judge's key (the testCases model is always OpenAI). */
     evaluationApiKey?: string;
+    /** Meters the judge's tokens (add-usage-metering). */
+    judgeUsage?: Parameters<typeof createTestTextSimilarity>[2];
 };
 /**
- * The session-engine Think for an assistant whose catalog provider speaks OpenAI-compatible Chat
+ * The session-engine Think for an agent whose catalog provider speaks OpenAI-compatible Chat
  * Completions with a known endpoint (openai, groq, ollama); undefined otherwise.
  */
-export declare function sessionThinkFor(assistant: SessionAssistant, apiKey: string | undefined): Think | undefined;
+export declare function sessionThinkFor(agent: SessionAgent, apiKey: string | undefined): Think | undefined;
 /** Runs every test-case scenario through the session engine, streaming results. */
 export declare function runSessionEval(options: RunSessionEvalOptions, callbacks?: Partial<RunEvalCallbacks>): Promise<SessionScenarioReport[]>;

package/dist/models/evaluations/session/runSessionEval.js

@@ -26,29 +26,29 @@ const createTestTextSimilarity_1 = require("../createTestTextSimilarity");
 const textSimilaryPrompt_1 = require("../textSimilaryPrompt");
 const evaluateSessionScenario_1 = require("./evaluateSessionScenario");
 /**
- * The session-engine Think for an assistant whose catalog provider speaks OpenAI-compatible Chat
+ * The session-engine Think for an agent whose catalog provider speaks OpenAI-compatible Chat
  * Completions with a known endpoint (openai, groq, ollama); undefined otherwise.
  */
-function sessionThinkFor(assistant, apiKey) {
-    const id = assistant.languageModel.model;
+function sessionThinkFor(agent, apiKey) {
+    const id = agent.languageModel.model;
     const slash = id.indexOf("/");
     const baseUrl = openai_1.OPENAI_COMPATIBLE[id.slice(0, slash)];
     if (!baseUrl)
         return undefined;
     return new openai_1.OpenAiCompatibleThink({ baseUrl, apiKey }, id.slice(slash + 1), {
-        temperature: assistant.languageModel.temperature,
-        maxTokens: assistant.languageModel.maxTokens
+        temperature: agent.languageModel.temperature,
+        maxTokens: agent.languageModel.maxTokens
     });
 }
 /** Runs every test-case scenario through the session engine, streaming results. */
 async function runSessionEval(options, callbacks) {
-    const testCases = common_1.testCasesSchema.parse(options.assistant.testCases);
+    const testCases = common_1.testCasesSchema.parse(options.agent.testCases);
     const testTextSimilarity = options.testTextSimilarity ??
         (0, createTestTextSimilarity_1.createTestTextSimilarity)({
             provider: testCases.evalsLanguageModel.provider,
             model: testCases.evalsLanguageModel.model,
             apiKey: options.evaluationApiKey ?? testCases.evalsLanguageModel.apiKey
-        }, testCases.evalsSystemPrompt || textSimilaryPrompt_1.textSimilaryPrompt);
+        }, testCases.evalsSystemPrompt || textSimilaryPrompt_1.textSimilaryPrompt, options.judgeUsage);
     const reports = [];
     for (const scenario of testCases.scenarios) {
         const report = await (0, evaluateSessionScenario_1.evaluateSessionScenario)({ ...options, testTextSimilarity }, scenario, callbacks?.onStepResult);

package/dist/models/evaluations/textSimilaryPrompt.d.ts

@@ -16,4 +16,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const textSimilaryPrompt = "\nYou are a text similarity evaluator for a Voice Assistant application. \n\nGive Text1 and Text2, you use the following process to evaluate the similarity between the two texts:\n\n- Take the first text and determmine the intent of the text.\n- Take the second text and determine the intent of the text.\n- Compare the intents of the two texts ignoring the actual text content, the entities, and length of the text.\n\n## Example 1\n\nText1: \"You're welcome. Have a great day!\"\nText2: \"You're welcome [name]. Your appointment is confirmed. Goodbye!\"\n\nAnswer: true\n\n=== \n\nAre the intents of the two texts the same? Respond with true.\n";
+export declare const textSimilaryPrompt = "\nYou are a text similarity evaluator for a Voice Agent application. \n\nGive Text1 and Text2, you use the following process to evaluate the similarity between the two texts:\n\n- Take the first text and determmine the intent of the text.\n- Take the second text and determine the intent of the text.\n- Compare the intents of the two texts ignoring the actual text content, the entities, and length of the text.\n\n## Example 1\n\nText1: \"You're welcome. Have a great day!\"\nText2: \"You're welcome [name]. Your appointment is confirmed. Goodbye!\"\n\nAnswer: true\n\n=== \n\nAre the intents of the two texts the same? Respond with true.\n";

package/dist/models/evaluations/textSimilaryPrompt.js

@@ -20,7 +20,7 @@ exports.textSimilaryPrompt = void 0;
  * limitations under the License.
  */
 exports.textSimilaryPrompt = `
-You are a text similarity evaluator for a Voice Assistant application. 
+You are a text similarity evaluator for a Voice Agent application. 
 
 Give Text1 and Text2, you use the following process to evaluate the similarity between the two texts:
 

package/dist/models/evaluations/types.d.ts

@@ -17,7 +17,7 @@
  * limitations under the License.
  */
 import { StepEvaluationReport } from "@fonoster/types";
-import { EvalAssistant, LanguageModel } from "../types";
+import { EvalAgent, LanguageModel } from "../types";
 type EvalExpectedTool = {
     tool: string;
     parameters?: Record<string, unknown>;
@@ -45,9 +45,9 @@ type EvalScenario = {
 };
 type EvaluateIntelligenceRequest = {
     intelligence: {
-        /** Ignored: the assistant's catalog id names the provider. */
+        /** Ignored: the agent's catalog id names the provider. */
         productRef?: string;
-        /** A session assistant (with testCases), as a protobuf Struct. */
+        /** A session agent (with testCases), as a protobuf Struct. */
         config: unknown;
     };
 };
@@ -55,10 +55,10 @@ type EvaluateStepParams = {
     step: EvalConversationStep;
     languageModel: LanguageModel;
     testTextSimilarity: (text1: string, text2: string) => Promise<boolean>;
-    assistantConfig: EvalAssistant;
+    agentConfig: EvalAgent;
 };
 type ScenarioEvaluationRequest = {
-    assistantConfig: EvalAssistant;
+    agentConfig: EvalAgent;
     scenario: EvalScenario;
     languageModel: LanguageModel;
     testTextSimilarity: (text1: string, text2: string) => Promise<boolean>;

package/dist/models/types.d.ts

@@ -26,10 +26,10 @@ import { Tool } from "../tools/types";
 /** The language model vendors the LangChain models (used by the evaluations only) implement. */
 type LlmProvider = "openai" | "groq" | "ollama" | "google" | "anthropic";
 /**
- * A session assistant as the evaluations run it (rework-autopilot 8.2): the catalog id split into
+ * A session agent as the evaluations run it (rework-autopilot 8.2): the catalog id split into
  * provider and model, and the keys the control plane resolved for this run. Never stored.
  */
-type EvalAssistant = {
+type EvalAgent = {
     conversationSettings: SessionConversationSettings;
     languageModel: Omit<SessionLanguageModel, "model" | "provider" | "apiKey" | "baseUrl"> & {
         provider: LlmProvider;
@@ -67,4 +67,4 @@ type TelephonyContext = {
     callerNumber: string;
     metadata?: Record<string, string>;
 };
-export { BaseModelParams, EvalAssistant, LlmProvider, InvocationResult, LanguageModel, LanguageModelParams, TelephonyContext };
+export { BaseModelParams, EvalAgent, LlmProvider, InvocationResult, LanguageModel, LanguageModelParams, TelephonyContext };

package/dist/session/Agent.d.ts

@@ -1,8 +1,29 @@
-import { SessionAssistant } from "./config";
+/**
+ * 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 { SessionAgent } from "./config";
 import { KnowledgePort } from "./knowledge";
 import { ChatMessage, Think } from "./think";
 import { ToolPort } from "./tools";
 import type { Session } from "@fonoster/voice";
+/** What Autopilot says when a transfer fails and the agent sets no `failedMessage`. */
+export declare const DEFAULT_TRANSFER_FAILED_MESSAGE = "Sorry, I couldn't connect you. How else can I help?";
 export type SpokenSource = "greeting" | "reply" | "idle" | "error";
 export type AgentEvent = {
     type: "TURN_USER_STARTED";
@@ -51,6 +72,8 @@ export type TurnTrace = {
 export interface Recorder {
     turn(trace: TurnTrace): void;
     note(event: Record<string, unknown>): void;
+    /** Model token usage for the call (usage.report); absent where there is no call. */
+    usage?(lines: Usage.UsageLine[]): void;
 }
 /** Writes turn traces and notes to the call record through the session (record.note). */
 export declare function sessionRecorder(session: Session): Recorder;
@@ -58,7 +81,7 @@ export declare const logRecorder: Recorder;
 /** The side effects of Autopilot: everything the state machine asks it to do on the session. */
 export declare class Agent {
     private readonly session;
-    private readonly assistant;
+    private readonly agent;
     private readonly think;
     private readonly tools;
     private readonly recorder;
@@ -68,6 +91,8 @@ export declare class Agent {
     private inflight?;
     private prepared?;
     private idleTimer?;
+    /** The model's `transfer` tool call, answered in the history if the transfer fails. */
+    private transferCallId?;
     private maxTimer?;
     private idleCount;
     private resumes;
@@ -75,7 +100,7 @@ export declare class Agent {
     private prepareEarly;
     private stopped;
     send: (event: AgentEvent) => void;
-    constructor(session: Session, assistant: SessionAssistant, think: Think, tools: ToolPort, recorder?: Recorder, knowledge?: KnowledgePort);
+    constructor(session: Session, agent: SessionAgent, think: Think, tools: ToolPort, recorder?: Recorder, knowledge?: KnowledgePort);
     get settings(): {
         firstMessage?: string;
         systemPrompt?: string;
@@ -86,6 +111,7 @@ export declare class Agent {
         transferOptions?: {
             message?: string;
             phoneNumber?: string;
+            failedMessage?: string;
         };
         idleOptions?: {
             message?: string;
@@ -119,16 +145,25 @@ export declare class Agent {
     abortReply(): void;
     /** turn.ended: answer the caller, streaming sentences into one speak id. */
     answer(text: string): Promise<void>;
+    /** One turn (STT final, LLM, TTS) as an autopilot.turn span. */
     private respond;
+    private respondTurn;
     private speakRound;
     private runTools;
     goodbye(): Promise<void>;
     transfer(): Promise<void>;
+    /**
+     * The transfer failed: say so and keep helping (autopilot "Transfer fails"). The model learns
+     * the outcome as its transfer call's result, and the machine returns to listening.
+     */
+    private transferFailed;
     private messages;
     /** Knowledge for this turn, as a system message for the request only (never in history). */
     private contextFor;
     private toolSpecs;
     private startStream;
+    /** think.stream inside an autopilot.llm.request span, with request and latency metrics. */
+    private traced;
     private takePrepared;
     private discardPrepared;
     private pump;

package/dist/session/Agent.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Agent = exports.logRecorder = void 0;
+exports.Agent = exports.logRecorder = exports.DEFAULT_TRANSFER_FAILED_MESSAGE = void 0;
 exports.sessionRecorder = sessionRecorder;
 /**
  * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
@@ -20,11 +20,15 @@ exports.sessionRecorder = sessionRecorder;
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+const common_1 = require("@fonoster/common");
 const logger_1 = require("@fonoster/logger");
 const voice_1 = require("@fonoster/voice");
 const AsyncQueue_1 = require("./AsyncQueue");
 const knowledge_1 = require("./knowledge");
 const sentences_1 = require("./sentences");
+const telemetry_1 = require("./telemetry");
+/** What Autopilot says when a transfer fails and the agent sets no `failedMessage`. */
+exports.DEFAULT_TRANSFER_FAILED_MESSAGE = "Sorry, I couldn't connect you. How else can I help?";
 const logger = (0, logger_1.getLogger)({ service: "autopilot", filePath: __filename });
 const MAX_TOOL_ROUNDS = 4;
 const BUILT_IN_TOOLS = [
@@ -44,7 +48,8 @@ function sessionRecorder(session) {
     const write = (data) => void session.note(data).catch(() => undefined);
     return {
         turn: (trace) => write({ kind: "autopilot.turn", ...trace }),
-        note: (event) => write({ kind: "autopilot.note", ...event })
+        note: (event) => write({ kind: "autopilot.note", ...event }),
+        usage: (lines) => void session.reportUsage(lines).catch(() => undefined)
     };
 }
 exports.logRecorder = {
@@ -53,9 +58,9 @@ exports.logRecorder = {
 };
 /** The side effects of Autopilot: everything the state machine asks it to do on the session. */
 class Agent {
-    constructor(session, assistant, think, tools, recorder = exports.logRecorder, knowledge) {
+    constructor(session, agent, think, tools, recorder = exports.logRecorder, knowledge) {
         this.session = session;
-        this.assistant = assistant;
+        this.agent = agent;
         this.think = think;
         this.tools = tools;
         this.recorder = recorder;
@@ -65,10 +70,10 @@ class Agent {
         this.resumes = 0;
         this.stopped = false;
         this.send = () => undefined;
-        this.prepareEarly = assistant.conversationSettings.patience !== "high";
+        this.prepareEarly = agent.conversationSettings.patience !== "high";
     }
     get settings() {
-        return this.assistant.conversationSettings;
+        return this.agent.conversationSettings;
     }
     // ---- lifecycle ----------------------------------------------------------------------
     /** Greeting: subscribe to the estimate, send initial DTMF, speak the first message. */
@@ -76,8 +81,8 @@ class Agent {
         this.maxTimer = setTimeout(() => this.send({ type: "MAX_DURATION" }), this.settings.maxSessionDuration);
         await this.safely(async () => {
             await this.session.subscribe(["turn.estimate"]);
-            // The gateway's Pacing policy owns turn timing; Autopilot only tells it how patient to be.
-            // Recognition hints (names, brands) add to the app's defaults at the gateway (VO-B3).
+            // AppBridge's Pacing policy owns turn timing; Autopilot only tells it how patient to be.
+            // Recognition hints (names, brands) add to the app's defaults at AppBridge (VO-B3).
             const hints = this.settings.hints?.length
                 ? this.settings.hints
                 : undefined;
@@ -144,7 +149,7 @@ class Agent {
                 ...this.messages(prepared.context),
                 { role: "user", content: text }
             ];
-            await this.pump(this.think.stream(messages, this.toolSpecs(), abort.signal), chunks);
+            await this.pump(this.traced(messages, abort.signal), chunks);
         })();
     }
     /** turn.resumed: the caller kept talking; the prepared reply is dropped. */
@@ -152,7 +157,7 @@ class Agent {
         this.discardPrepared();
         this.resumes++;
         if (this.resumes >= 3 && this.prepareEarly) {
-            // A caller who pauses often: stop preparing early for the rest of this call. The gateway
+            // A caller who pauses often: stop preparing early for the rest of this call. AppBridge
             // adapts its own turn timing within the call (TT-B6), so Autopilot does not also change
             // the patience it asked for (AP-B2).
             this.prepareEarly = false;
@@ -181,7 +186,23 @@ class Agent {
         this.inflight = run;
         return run;
     }
+    /** One turn (STT final, LLM, TTS) as an autopilot.turn span. */
     async respond(text, abort, previous) {
+        const callRef = this.session.callRef;
+        const span = telemetry_1.telemetry.startSpan("autopilot.turn", { [common_1.CALL_REF_ATTR]: callRef }, telemetry_1.telemetry.traceparent(callRef));
+        try {
+            await this.respondTurn(text, abort, previous);
+            span.end({ "turn.cancelled": abort.signal.aborted });
+        }
+        catch (e) {
+            span.end({}, e.message);
+            throw e;
+        }
+        finally {
+            telemetry_1.telemetry.count("fonoster.autopilot.turns", 1);
+        }
+    }
+    async respondTurn(text, abort, previous) {
         // Let a cancelled reply settle first, so what the caller heard of it is recorded before
         // this turn (honest history, A6).
         await previous?.catch(() => undefined);
@@ -232,6 +253,8 @@ class Agent {
                     break;
                 const builtIn = outcome.toolCalls.find((c) => c.name === "hangup" || c.name === "transfer");
                 if (builtIn) {
+                    if (builtIn.name === "transfer")
+                        this.transferCallId = builtIn.id;
                     this.recorder.turn({
                         ...trace,
                         toolCalls: [...trace.toolCalls, { name: builtIn.name, ok: true }]
@@ -279,7 +302,7 @@ class Agent {
                         full += chunk.text;
                         text.push(chunk.text);
                     }
-                    else
+                    else if (chunk.type === "tool_calls")
                         toolCalls = chunk.calls;
                 }
                 text.end();
@@ -323,8 +346,8 @@ class Agent {
     }
     async runTools(calls, abort, trace) {
         for (const call of calls) {
-            const tool = this.assistant.languageModel.tools.find((t) => t.name === call.name);
-            // The start message is spoken while the tool runs; the gateway queues the reply after it.
+            const tool = this.agent.languageModel.tools.find((t) => t.name === call.name);
+            // The start message is spoken while the tool runs; AppBridge queues the reply after it.
             if (tool?.requestStartMessage) {
                 void this.session
                     .say(tool.requestStartMessage, this.speechOptions())
@@ -373,9 +396,33 @@ class Agent {
                 ...this.speechOptions(),
                 interruptible: false
             });
-            await this.session.transfer(options.phoneNumber);
+            try {
+                await this.session.transfer(options.phoneNumber);
+            }
+            catch (e) {
+                if (!(e instanceof voice_1.SessionError) || e.code !== "transfer_failed")
+                    throw e;
+                await this.transferFailed(options.failedMessage);
+            }
         });
     }
+    /**
+     * The transfer failed: say so and keep helping (autopilot "Transfer fails"). The model learns
+     * the outcome as its transfer call's result, and the machine returns to listening.
+     */
+    async transferFailed(message) {
+        const callId = this.transferCallId;
+        this.transferCallId = undefined;
+        if (callId)
+            this.history.push({
+                role: "tool",
+                tool_call_id: callId,
+                content: JSON.stringify({ error: "the transfer failed" })
+            });
+        const r = await this.session.say(message || exports.DEFAULT_TRANSFER_FAILED_MESSAGE, this.speechOptions());
+        this.history.push({ role: "assistant", content: r.heardText });
+        this.send({ type: "SPOKEN", source: "error" });
+    }
     // ---- internals --------------------------------------------------------------------
     messages(context = []) {
         return [
@@ -408,7 +455,7 @@ class Agent {
         }
     }
     toolSpecs() {
-        const own = this.assistant.languageModel.tools.map((t) => ({
+        const own = this.agent.languageModel.tools.map((t) => ({
             name: t.name,
             description: t.description,
             parameters: t.parameters
@@ -418,9 +465,36 @@ class Agent {
     }
     startStream(signal, context = []) {
         const chunks = new AsyncQueue_1.AsyncQueue();
-        void this.pump(this.think.stream(this.messages(context), this.toolSpecs(), signal), chunks);
+        void this.pump(this.traced(this.messages(context), signal), chunks);
         return chunks;
     }
+    /** think.stream inside an autopilot.llm.request span, with request and latency metrics. */
+    async *traced(messages, signal) {
+        const callRef = this.session.callRef;
+        const span = telemetry_1.telemetry.startSpan("autopilot.llm.request", { [common_1.CALL_REF_ATTR]: callRef, "llm.messages": messages.length }, telemetry_1.telemetry.traceparent(callRef));
+        const started = Date.now();
+        let first;
+        let failure;
+        try {
+            for await (const chunk of this.think.stream(messages, this.toolSpecs(), signal)) {
+                first ?? (first = Date.now() - started);
+                yield chunk;
+            }
+        }
+        catch (e) {
+            failure = e.message;
+            throw e;
+        }
+        finally {
+            telemetry_1.telemetry.count("fonoster.autopilot.llm.requests", 1);
+            if (first !== undefined)
+                telemetry_1.telemetry.count("fonoster.autopilot.llm.latency_ms", first);
+            span.end({
+                "llm.first_chunk_ms": first ?? -1,
+                "llm.cancelled": signal.aborted
+            }, failure);
+        }
+    }
     takePrepared(text) {
         const p = this.prepared;
         this.prepared = undefined;

package/dist/session/config.d.ts

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

package/dist/session/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sessionLanguageModelSchema = exports.sessionConversationSettingsSchema = exports.sessionAssistantSchema = void 0;
+exports.sessionLanguageModelSchema = exports.sessionConversationSettingsSchema = exports.sessionAgentSchema = void 0;
 /**
  * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
  * http://github.com/fonoster/fonoster
@@ -19,9 +19,9 @@ exports.sessionLanguageModelSchema = exports.sessionConversationSettingsSchema =
  * 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.
+// The session agent schema lives in @fonoster/common (rework-autopilot 5.1), so the control
+// plane validates agents 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, "sessionAgentSchema", { enumerable: true, get: function () { return common_1.sessionAgentSchema; } });
 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/createAutopilot.d.ts

@@ -1,24 +1,25 @@
 import { Agent, Recorder } from "./Agent";
-import { SessionAssistant } from "./config";
+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 LoadedAssistant = {
-    assistant: unknown;
+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 assistant for a session (validated with the session assistant schema). */
-    assistant?: unknown | ((session: Session) => Promise<unknown> | unknown);
+    /** 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 assistant and workspace for a session; undefined means the
-     * app has no assistant (the call is ended).
+     * 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<LoadedAssistant | undefined>;
+    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). */
@@ -32,10 +33,10 @@ export type AutopilotOptions = {
     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: {
+    /** Builds the knowledge port for an agent (operator wiring, task 4.1). */
+    knowledgeFor?: (agent: SessionAgent, scope: {
         workspaceRef?: string;
-    }) => KnowledgePort | undefined;
+    }, usage?: UsageSink) => KnowledgePort | undefined;
     recorder?: Recorder;
     /** Called with each session's Agent, for tests and observability. */
     onAgent?: (agent: Agent) => void;