Assistant: add a Hermes agent backend

A "Hermes agent" assistant model talks to a Hermes Agent gateway's
OpenAI-compatible API server (streamed /v1/chat/completions), with Hermes URL
and key settings under Assistant. Hermes keeps the conversation: each
assistant session maps to one X-Hermes-Session-Id and only the latest user
message is sent. Faceclaw's own tools are not offered to it, and its reasoning
stream is not shown on the glasses. See notes/hermes-assistant.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
FilipAlexanderandClaude Opus 5.5 committed 2026-10-17 16:44:23 +02:00
1 parent 2bb7b3ea1a
commit d9924eedcd
9 files changed
+297 -4

No files matched your search

+9 -2
View File
@@ -1,4 +1,5 @@
import { streamAnthropicMessage } from "../native/anthropic";
import { streamHermesChat } from "../native/hermes";
import { streamLocalQwen } from "../native/llama";
import { streamOpenAiResponse } from "../native/openai";
import type {
@@ -30,6 +31,9 @@ export type DirectTurnOptions = {
apiKey: string;
model: string;
effort?: "low" | "medium" | "high";
/** Hermes: the API root, and the server-side session this conversation maps to. */
baseUrl?: string;
sessionId?: string;
system: string;
/** Owned by the session; this loop appends assistant + tool_result messages. */
messages: LlmMessage[];
@@ -79,7 +83,8 @@ export class DirectAssistantBackend {
system: options.system,
effort: options.effort,
messages: options.messages,
tools: options.buildTools(),
// Hermes runs its own tools; Faceclaw's are not offered to it.
tools: options.provider === "hermes" ? [] : options.buildTools(),
onTextDelta: (delta, textSoFar) => {
if (cancelled) return;
options.callbacks.onTextDelta(delta, priorText + textSoFar);
@@ -128,7 +133,9 @@ export class DirectAssistantBackend {
},
};
streamHandle =
options.provider === "openai"
options.provider === "hermes"
? streamHermesChat({ ...streamOptions, baseUrl: options.baseUrl ?? "", sessionId: options.sessionId ?? "" })
: options.provider === "openai"
? streamOpenAiResponse(streamOptions)
: options.provider === "local"
? streamLocalQwen(streamOptions)
+14 -1
View File
@@ -10,6 +10,7 @@ export const ASSISTANT_MODEL_VALUES = [
"terra",
"sol",
"qwen",
"hermes",
] as const;
export type AssistantModel = (typeof ASSISTANT_MODEL_VALUES)[number];
@@ -20,11 +21,14 @@ export function supportedAssistantModel(value: AssistantModel): AssistantModel {
return global.isIOS && value === "qwen" ? "auto" : value;
}
export type AssistantProvider = "anthropic" | "openai" | "local";
export type AssistantProvider = "anthropic" | "openai" | "local" | "hermes";
export type AssistantApiKeys = {
anthropic: string;
openai: string;
/** A Hermes Agent API server; only the voice assistant passes these. */
hermesUrl?: string;
hermesKey?: string;
};
export type ResolvedAssistantModel = {
@@ -33,6 +37,8 @@ export type ResolvedAssistantModel = {
model: string;
apiKey: string;
effort?: "low" | "medium" | "high";
/** API root for providers that are not fixed services (Hermes). */
baseUrl?: string;
};
type ModelDefinition = {
@@ -55,6 +61,8 @@ const MODEL_DEFINITIONS: Record<Exclude<AssistantModel, "auto">, ModelDefinition
// Runs on the phone itself (llama.cpp); needs the downloaded model file,
// not an API key. The default for users who haven't set any key.
qwen: { label: `${LOCAL_MODEL.label} (on-phone)`, provider: "local", model: LOCAL_MODEL.id },
// Your own Hermes Agent (its API server), with its own tools and memory.
hermes: { label: "Hermes agent", provider: "hermes", model: "hermes-agent" },
};
export function assistantModelLabel(value: AssistantModel): string {
@@ -93,6 +101,11 @@ export function resolveAssistantModel(
}
const definition = MODEL_DEFINITIONS[resolvedSelection as Exclude<AssistantModel, "auto">];
if (definition.provider === "hermes") {
const baseUrl = keys.hermesUrl?.trim() ?? "";
if (!baseUrl) return null;
return { selection, provider: "hermes", model: definition.model, apiKey: keys.hermesKey?.trim() ?? "", baseUrl };
}
if (definition.provider === "local") {
if (!isLocalModelReady()) return null;
return {
+11 -1
View File
@@ -32,6 +32,11 @@ export type AssistantBackendConfig =
/** Trim history from the head once it grows past this many messages. */
const MAX_HISTORY_MESSAGES = 40;
/** Hermes brings its own persona and tools; it only needs to know where the reply is shown. */
const HERMES_SYSTEM_PROMPT =
"The user is talking to you through smart glasses with a small text display. Reply briefly in plain text, without Markdown.";
export class AssistantSession {
private readonly directBackend = new DirectAssistantBackend();
private readonly messages: LlmMessage[] = [];
@@ -43,6 +48,8 @@ export class AssistantSession {
// 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>();
// The Hermes server-side session for this conversation (Hermes keeps the history).
private readonly hermesSessionId = `faceclaw-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
constructor(
private config: AssistantBackendConfig,
@@ -173,7 +180,10 @@ export class AssistantSession {
apiKey: llm.apiKey,
model: llm.model,
effort: llm.effort,
system: isLocal ? ASSISTANT_SYSTEM_PROMPT_BASE : buildAssistantSystemPrompt(ctx),
baseUrl: llm.baseUrl,
sessionId: this.hermesSessionId,
system: llm.provider === "hermes" ? HERMES_SYSTEM_PROMPT
: isLocal ? ASSISTANT_SYSTEM_PROMPT_BASE : buildAssistantSystemPrompt(ctx),
messages: turnMessages,
buildTools: () => this.buildToolDefinitions(),
registry: this.registry,