Files
faceclaw/app/assistant/session.ts
T
James BabcockandClaude Fable 5 48bac85cbe External assistant backend: agent bridge client + MCP server
Phase 3 of the voice-assistant design: assistant.backend=external routes
utterances over a dial-out websocket to faceclaw-agent-bridge (an OpenClaw
plugin on the user's machine). The phone serves its ToolRegistry as MCP on
the same socket, with proactive gating and rate limiting enforced locally.
New Assistant settings section with backend/bridge settings.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XCdkQyB3RUVPTuEmhxVEdp
2026-08-01 18:28:47 -07:00

175 lines
6.1 KiB
TypeScript

import { buildAssistantSystemPrompt } from "../prompts";
import { assistantBridge } from "./bridge-client";
import { DirectAssistantBackend } from "./direct-backend";
import type { LlmMessage, LlmToolDefinition } from "./llm-protocol";
import type { ResolvedAssistantModel } from "./models";
import { toolRegistry, type ToolRegistry } from "./tool-registry";
import type {
AssistantBridgeConfig,
AssistantContext,
AssistantTurnCallbacks,
AssistantTurnHandle,
} from "./types";
/**
* One assistant conversation. Owns the message history and turn state and
* drives either the on-phone provider loop (direct) or the external agent
* bridge. The UI talks only to this surface, so AssistantLayer is
* backend-agnostic.
*
* Sessions are cheap and idle-expire (see isExpired): the shell starts a fresh
* one for a new wakeword and reuses the current one for a follow-up. In
* external mode the conversation history lives on the agent's machine (one
* long-lived session there), so expiry here only affects the overlay UI.
*/
/** Which engine answers utterances, plus what it needs to do so. */
export type AssistantBackendConfig =
| { kind: "direct"; llm: ResolvedAssistantModel }
| { kind: "external"; bridge: AssistantBridgeConfig };
/** A new PTT after this much idle starts a fresh conversation. */
const SESSION_IDLE_MS = 10 * 60 * 1000;
/** Trim history from the head once it grows past this many messages. */
const MAX_HISTORY_MESSAGES = 40;
export class AssistantSession {
private readonly directBackend = new DirectAssistantBackend();
private readonly messages: LlmMessage[] = [];
private turnHandle: AssistantTurnHandle | null = null;
private lastActivityMs = Date.now();
// API-safe tool name -> canonical registry name. Provider APIs restrict tool
// names, so dotted registry names are sanitized and mapped back on calls.
private readonly toolNameMap = new Map<string, string>();
constructor(
private readonly config: AssistantBackendConfig,
private readonly registry: ToolRegistry = toolRegistry,
) {}
matchesConfiguration(config: AssistantBackendConfig): boolean {
if (this.config.kind !== config.kind) return false;
if (this.config.kind === "direct" && config.kind === "direct") {
return (
this.config.llm.provider === config.llm.provider &&
this.config.llm.model === config.llm.model &&
this.config.llm.apiKey === config.llm.apiKey
);
}
if (this.config.kind === "external" && config.kind === "external") {
return (
this.config.bridge.host === config.bridge.host &&
this.config.bridge.port === config.bridge.port &&
this.config.bridge.token === config.bridge.token
);
}
return false;
}
/** Whether this session has been idle long enough to retire. */
isExpired(nowMs = Date.now()): boolean {
return nowMs - this.lastActivityMs > SESSION_IDLE_MS;
}
isTurnActive(): boolean {
return this.turnHandle !== null;
}
/** Begin a turn from a spoken utterance. Only one turn runs at a time. */
sendUtterance(text: string, ctx: AssistantContext, callbacks: AssistantTurnCallbacks): void {
if (this.turnHandle) {
callbacks.onError("The assistant is still working on the previous request");
return;
}
this.lastActivityMs = Date.now();
const finish = () => {
this.turnHandle = null;
this.lastActivityMs = Date.now();
};
const wrappedCallbacks: AssistantTurnCallbacks = {
onTextDelta: callbacks.onTextDelta,
onToolActivity: callbacks.onToolActivity,
onTurnDone: (result) => {
finish();
callbacks.onTurnDone(result);
},
onError: (message) => {
finish();
callbacks.onError(message);
},
};
if (this.config.kind === "external") {
// History and the agent loop live on the agent's machine; the phone just
// streams this turn. The overlay keeps its own display state.
this.turnHandle = assistantBridge.sendUtterance(text, ctx, wrappedCallbacks);
return;
}
this.messages.push({ role: "user", content: text });
this.trimHistory();
const llm = this.config.llm;
this.turnHandle = this.directBackend.runTurn({
provider: llm.provider,
apiKey: llm.apiKey,
model: llm.model,
effort: llm.effort,
system: buildAssistantSystemPrompt(ctx),
messages: this.messages,
buildTools: () => this.buildToolDefinitions(),
registry: this.registry,
resolveToolName: (apiName) => this.toolNameMap.get(apiName) ?? apiName,
callbacks: wrappedCallbacks,
});
}
cancel(): void {
this.turnHandle?.cancel();
this.turnHandle = null;
this.lastActivityMs = Date.now();
}
private buildToolDefinitions(): LlmToolDefinition[] {
this.toolNameMap.clear();
return this.registry.listTools().map((spec) => {
const apiName = this.toApiToolName(spec.name);
this.toolNameMap.set(apiName, spec.name);
return { name: apiName, description: spec.description, input_schema: spec.inputSchema };
});
}
/** Convert a canonical registry name to a provider-legal tool name. */
private toApiToolName(name: string): string {
let base = name.replace(/[^a-zA-Z0-9_-]/g, "_");
// Disambiguate the rare case where two canonical names sanitize alike.
if (this.toolNameMap.has(base)) {
let i = 2;
while (this.toolNameMap.has(`${base}_${i}`)) i++;
base = `${base}_${i}`;
}
return base;
}
private trimHistory(): void {
if (this.messages.length <= MAX_HISTORY_MESSAGES) return;
// Drop whole messages from the head. A leading orphan tool_result (whose
// tool_use we trimmed) would be rejected by the API, so skip past any
// tool_result-only user message left at the front.
const overflow = this.messages.length - MAX_HISTORY_MESSAGES;
this.messages.splice(0, overflow);
while (this.messages.length && startsWithToolResult(this.messages[0]!)) {
this.messages.shift();
}
}
}
function startsWithToolResult(message: LlmMessage): boolean {
return (
Array.isArray(message.content) &&
message.content.length > 0 &&
message.content[0]!.type === "tool_result"
);
}