Hermes integration survives restarts, fix error hadling, increase turn length limit

This commit is contained in:
James Babcock committed 2026-10-17 13:52:43 -07:00
1 parent 825559aa82
commit de653f0fbb
6 files changed
+100 -9

No files matched your search

+10 -2
View File
@@ -25,6 +25,13 @@ const MAX_ITERATIONS = 8;
/** The on-phone model is slower per step and unreliable on long tool chains. */ /** The on-phone model is slower per step and unreliable on long tool chains. */
const MAX_ITERATIONS_LOCAL = 4; const MAX_ITERATIONS_LOCAL = 4;
const MAX_TURN_MS = 2 * 60 * 1000; const MAX_TURN_MS = 2 * 60 * 1000;
/**
* Hermes runs whole multi-tool agent tasks in one request, and dropping the
* stream interrupts the run on the server, so its cap is only a backstop. A
* dead server is caught sooner: Hermes sends keepalives every 10s, and both
* transports fail a stream that goes quiet for 180s.
*/
const MAX_TURN_MS_HERMES = 20 * 60 * 1000;
export type DirectTurnOptions = { export type DirectTurnOptions = {
provider: AssistantProvider; provider: AssistantProvider;
@@ -66,13 +73,14 @@ export class DirectAssistantBackend {
}; };
const maxIterations = options.provider === "local" ? MAX_ITERATIONS_LOCAL : MAX_ITERATIONS; const maxIterations = options.provider === "local" ? MAX_ITERATIONS_LOCAL : MAX_ITERATIONS;
const maxTurnMs = options.provider === "hermes" ? MAX_TURN_MS_HERMES : MAX_TURN_MS;
const runIteration = (iteration: number): void => { const runIteration = (iteration: number): void => {
if (cancelled) return; if (cancelled) return;
if (iteration >= maxIterations) { if (iteration >= maxIterations) {
finishError("Assistant stopped: too many tool steps"); finishError("Assistant stopped: too many tool steps");
return; return;
} }
if (Date.now() - startMs > MAX_TURN_MS) { if (Date.now() - startMs > maxTurnMs) {
finishError("Assistant stopped: turn took too long"); finishError("Assistant stopped: turn took too long");
return; return;
} }
@@ -142,7 +150,7 @@ export class DirectAssistantBackend {
: streamAnthropicMessage(streamOptions); : streamAnthropicMessage(streamOptions);
}; };
deadline = setTimeout(() => finishError("Assistant stopped: turn took too long"), MAX_TURN_MS); deadline = setTimeout(() => finishError("Assistant stopped: turn took too long"), maxTurnMs);
runIteration(0); runIteration(0);
return { return {
+9 -3
View File
@@ -22,6 +22,8 @@ export type AssistantSessionHistory = {
transcript: AssistantTranscriptEntry[]; transcript: AssistantTranscriptEntry[];
/** Model identity for safe replay after Auto resolves differently on restart. */ /** Model identity for safe replay after Auto resolves differently on restart. */
engine?: string; engine?: string;
/** The Hermes server-side session for this conversation (Hermes keeps the history). */
hermesSessionId?: string;
}; };
/** Which engine answers utterances, plus what it needs to do so. */ /** Which engine answers utterances, plus what it needs to do so. */
@@ -48,14 +50,18 @@ export class AssistantSession {
// API-safe tool name -> canonical registry name. Provider APIs restrict tool // API-safe tool name -> canonical registry name. Provider APIs restrict tool
// names, so dotted registry names are sanitized and mapped back on calls. // names, so dotted registry names are sanitized and mapped back on calls.
private readonly toolNameMap = new Map<string, string>(); private readonly toolNameMap = new Map<string, string>();
// The Hermes server-side session for this conversation (Hermes keeps the history). // Saved with the history: Faceclaw only sends Hermes the latest message, so a
private readonly hermesSessionId = `faceclaw-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`; // restored conversation must keep addressing the same server-side session.
private readonly hermesSessionId: string;
constructor( constructor(
private config: AssistantBackendConfig, private config: AssistantBackendConfig,
private readonly registry: ToolRegistry = toolRegistry, private readonly registry: ToolRegistry = toolRegistry,
history?: AssistantSessionHistory, history?: AssistantSessionHistory,
) { ) {
this.hermesSessionId = typeof history?.hermesSessionId === "string" && history.hermesSessionId
? history.hermesSessionId
: `faceclaw-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
if (history) { if (history) {
this.messages.push(...history.messages); this.messages.push(...history.messages);
this.transcript.push(...history.transcript); this.transcript.push(...history.transcript);
@@ -75,7 +81,7 @@ export class AssistantSession {
} }
history(): AssistantSessionHistory { history(): AssistantSessionHistory {
return { messages: this.messages, transcript: this.transcript, engine: this.engine() }; return { messages: this.messages, transcript: this.transcript, engine: this.engine(), hermesSessionId: this.hermesSessionId };
} }
configure(config: AssistantBackendConfig): void { configure(config: AssistantBackendConfig): void {
+18 -3
View File
@@ -36,9 +36,23 @@ export function streamHermesChat(options: HermesStreamOptions): LlmStreamHandle
}; };
const done = () => { const done = () => {
if (settled) return; if (settled) return;
// A failed or interrupted run still ends with a finish chunk and [DONE]; the
// chunk carries an error object only when Hermes has a message to show.
if (finishReason === "error") {
fail("Hermes: the agent run failed");
return;
}
if (finishReason === "cancelled") {
fail("Hermes: the agent run was interrupted");
return;
}
if (!text) {
fail("Hermes ended the turn without a reply");
return;
}
settled = true; settled = true;
request?.cancel(); request?.cancel();
options.onDone({ text, content: text ? [{ type: "text", text }] : [], stopReason: finishReason === "length" ? "max_tokens" : "end_turn" }); options.onDone({ text, content: [{ type: "text", text }], stopReason: finishReason === "length" ? "max_tokens" : "end_turn" });
}; };
const baseUrl = normalizeHermesUrl(options.baseUrl); const baseUrl = normalizeHermesUrl(options.baseUrl);
@@ -86,8 +100,9 @@ export function streamHermesChat(options: HermesStreamOptions): LlmStreamHandle
if (choice?.finish_reason) finishReason = String(choice.finish_reason); if (choice?.finish_reason) finishReason = String(choice.finish_reason);
}, },
onHttpError: (code: number, errorBody: string) => fail(describeHttpError(Number(code), String(errorBody))), onHttpError: (code: number, errorBody: string) => fail(describeHttpError(Number(code), String(errorBody))),
// Some servers close without [DONE] after the final chunk. // Some servers close without [DONE] after the final chunk. Hermes always sends
onComplete: () => (finishReason || text ? done() : fail("Hermes stream ended without a reply")), // a finish_reason, so a stream closed without one was cut off.
onComplete: () => (finishReason ? done() : fail(text ? "Hermes: the reply was cut off" : "Hermes stream ended without a reply")),
onFailure: (message: string) => fail(`Hermes connection failed: ${String(message)}`), onFailure: (message: string) => fail(`Hermes connection failed: ${String(message)}`),
}; };
@@ -57,8 +57,9 @@ internal object IosStreamingHttp : StreamingHttp {
} }
val request = buildRequest(target, "POST", body, listOf("Content-Type" to "application/json; charset=utf-8", "Accept" to "text/event-stream") + headers) val request = buildRequest(target, "POST", body, listOf("Content-Type" to "application/json; charset=utf-8", "Accept" to "text/event-stream") + headers)
val configuration = NSURLSessionConfiguration.ephemeralSessionConfiguration val configuration = NSURLSessionConfiguration.ephemeralSessionConfiguration
// An idle limit only, like Android's OkHttp read timeout: callers cap a stream's
// total time, and a Hermes agent turn can stream for many minutes.
configuration.timeoutIntervalForRequest = 180.0 configuration.timeoutIntervalForRequest = 180.0
configuration.timeoutIntervalForResource = 180.0
val delegate = StreamingDelegate(sink) val delegate = StreamingDelegate(sink)
val session = NSURLSession.sessionWithConfiguration(configuration, delegate, delegateQueue = null) val session = NSURLSession.sessionWithConfiguration(configuration, delegate, delegateQueue = null)
val task = session.dataTaskWithRequest(request) val task = session.dataTaskWithRequest(request)
+7
View File
@@ -6,6 +6,13 @@ OpenAI-compatible API server and streams the answer back to the glasses. Hermes
runs its own tools and keeps the conversation: each Faceclaw assistant runs its own tools and keeps the conversation: each Faceclaw assistant
conversation maps to one Hermes session (`X-Hermes-Session-Id`), and only the conversation maps to one Hermes session (`X-Hermes-Session-Id`), and only the
latest message is sent. Faceclaw's own glasses tools are not offered to Hermes. latest message is sent. Faceclaw's own glasses tools are not offered to Hermes.
The session ID is saved with the conversation, so a conversation restored after
an app restart continues the same Hermes session.
A Hermes turn may run for up to 20 minutes (other models get 2), because Hermes
runs whole multi-tool tasks in one request and closing the stream interrupts the
run on the server. A run that fails or is interrupted on the server shows as an
error on the glasses, with any partial answer kept.
## Enable the API server in Hermes ## Enable the API server in Hermes
+54
View File
@@ -60,6 +60,60 @@ test('a rejected key and an empty stream are errors', () => {
assert.deepEqual(empty.errors, ['Hermes stream ended without a reply']); assert.deepEqual(empty.errors, ['Hermes stream ended without a reply']);
}); });
test('failed, interrupted, empty and cut-off runs are errors, not blank answers', () => {
const api = hermes();
const ending = (lines, close = 'done') => {
const s = stream(api);
for (const line of lines) s.request.listener.onLine(line);
if (close === 'done') s.request.listener.onLine('data: [DONE]');
else s.request.listener.onComplete();
assert.deepEqual(s.results, []);
return s.errors;
};
// Hermes's finish chunk: an error object rides along only when there is a message to show.
const finish = (reason, extra = {}) => `data: ${JSON.stringify({ choices: [{ index: 0, delta: {}, finish_reason: reason }], ...extra })}`;
assert.deepEqual(ending([chunk({ content: 'Half' }), finish('error')]), ['Hermes: the agent run failed']);
assert.deepEqual(ending([finish('error', { error: { message: 'admission_conflict', type: 'agent_error' } })]), ['Hermes: admission_conflict']);
assert.deepEqual(ending([chunk({ content: 'Half' }), finish('cancelled')]), ['Hermes: the agent run was interrupted']);
assert.deepEqual(ending([finish('stop')]), ['Hermes ended the turn without a reply']);
assert.deepEqual(ending([chunk({ content: 'Half' })], 'close'), ['Hermes: the reply was cut off']);
const closed = stream(api);
closed.request.listener.onLine(chunk({ content: 'Kiwi' }, 'stop'));
closed.request.listener.onComplete();
assert.deepEqual(closed.results.map((r) => r.text), ['Kiwi'], 'a finished stream may close without [DONE]');
});
test('a restored conversation keeps its Hermes session, and Hermes turns get a long deadline', () => {
const requests = [], delays = [];
const load = loader({ global: { isIOS: false, isAndroid: true }, setTimeout: (_fn, ms) => { delays.push(ms); return 0; }, clearTimeout: () => {} }, {
'./sse': { openSseRequest: (_url, _body, headers, listener) => {
const request = { headers, listener, cancel() {} };
requests.push(request);
return request;
} },
'../native/llama': { streamLocalQwen: () => assert.fail('no local model') },
'./bridge-client': { assistantBridge: {} }, './tool-registry': { toolRegistry: {} },
'../prompts': { ASSISTANT_SYSTEM_PROMPT_BASE: '', buildAssistantSystemPrompt: () => '', describeAssistantContext: () => '' },
});
const { AssistantSession } = load('app/assistant/session.ts');
const config = { kind: 'direct', llm: { selection: 'hermes', provider: 'hermes', model: 'hermes-agent', apiKey: 'k', baseUrl: 'http://hermes-host:8642' } };
const callbacks = { onTextDelta() {}, onToolActivity() {}, onError: (e) => assert.fail(e), onTurnDone() {} };
const turn = (session, text) => {
session.sendUtterance(text, {}, callbacks);
const request = requests.at(-1);
request.listener.onLine(chunk({ content: 'OK' }, 'stop'));
request.listener.onLine('data: [DONE]');
return request.headers['X-Hermes-Session-Id'];
};
const first = new AssistantSession(config, undefined);
const id = turn(first, 'Remember kiwi.');
assert.match(id, /^faceclaw-/);
assert.ok(delays.includes(20 * 60 * 1000), 'Hermes turns are not held to the 2-minute LLM cap');
const restored = new AssistantSession(config, undefined, JSON.parse(JSON.stringify(first.history())));
assert.equal(turn(restored, 'Which word?'), id);
assert.notEqual(turn(new AssistantSession(config, undefined), 'Hello'), id, 'a new conversation gets its own session');
});
test('URL normalization adds /v1 to a bare host and drops the endpoint path', () => { test('URL normalization adds /v1 to a bare host and drops the endpoint path', () => {
const { normalizeHermesUrl } = hermes(); const { normalizeHermesUrl } = hermes();
assert.equal(normalizeHermesUrl('http://192.0.2.10:8642'), 'http://192.0.2.10:8642/v1'); assert.equal(normalizeHermesUrl('http://192.0.2.10:8642'), 'http://192.0.2.10:8642/v1');