diff --git a/app/assistant/direct-backend.ts b/app/assistant/direct-backend.ts index a28b095a..20c6b2e6 100644 --- a/app/assistant/direct-backend.ts +++ b/app/assistant/direct-backend.ts @@ -25,6 +25,13 @@ const MAX_ITERATIONS = 8; /** The on-phone model is slower per step and unreliable on long tool chains. */ const MAX_ITERATIONS_LOCAL = 4; 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 = { provider: AssistantProvider; @@ -66,13 +73,14 @@ export class DirectAssistantBackend { }; 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 => { if (cancelled) return; if (iteration >= maxIterations) { finishError("Assistant stopped: too many tool steps"); return; } - if (Date.now() - startMs > MAX_TURN_MS) { + if (Date.now() - startMs > maxTurnMs) { finishError("Assistant stopped: turn took too long"); return; } @@ -142,7 +150,7 @@ export class DirectAssistantBackend { : 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); return { diff --git a/app/assistant/session.ts b/app/assistant/session.ts index 3065f4f5..a8803d6c 100644 --- a/app/assistant/session.ts +++ b/app/assistant/session.ts @@ -22,6 +22,8 @@ export type AssistantSessionHistory = { transcript: AssistantTranscriptEntry[]; /** Model identity for safe replay after Auto resolves differently on restart. */ 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. */ @@ -48,14 +50,18 @@ 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(); - // 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)}`; + // Saved with the history: Faceclaw only sends Hermes the latest message, so a + // restored conversation must keep addressing the same server-side session. + private readonly hermesSessionId: string; constructor( private config: AssistantBackendConfig, private readonly registry: ToolRegistry = toolRegistry, 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) { this.messages.push(...history.messages); this.transcript.push(...history.transcript); @@ -75,7 +81,7 @@ export class AssistantSession { } 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 { diff --git a/app/native/hermes.ts b/app/native/hermes.ts index dc45f834..2e6eed76 100644 --- a/app/native/hermes.ts +++ b/app/native/hermes.ts @@ -36,9 +36,23 @@ export function streamHermesChat(options: HermesStreamOptions): LlmStreamHandle }; const done = () => { 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; 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); @@ -86,8 +100,9 @@ export function streamHermesChat(options: HermesStreamOptions): LlmStreamHandle if (choice?.finish_reason) finishReason = String(choice.finish_reason); }, onHttpError: (code: number, errorBody: string) => fail(describeHttpError(Number(code), String(errorBody))), - // Some servers close without [DONE] after the final chunk. - onComplete: () => (finishReason || text ? done() : fail("Hermes stream ended without a reply")), + // Some servers close without [DONE] after the final chunk. Hermes always sends + // 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)}`), }; diff --git a/native/kotlin/shared/src/iosMain/kotlin/com/faceclaw/app/net/IosStreamingHttp.kt b/native/kotlin/shared/src/iosMain/kotlin/com/faceclaw/app/net/IosStreamingHttp.kt index 209bbc36..fcada2d9 100644 --- a/native/kotlin/shared/src/iosMain/kotlin/com/faceclaw/app/net/IosStreamingHttp.kt +++ b/native/kotlin/shared/src/iosMain/kotlin/com/faceclaw/app/net/IosStreamingHttp.kt @@ -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 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.timeoutIntervalForResource = 180.0 val delegate = StreamingDelegate(sink) val session = NSURLSession.sessionWithConfiguration(configuration, delegate, delegateQueue = null) val task = session.dataTaskWithRequest(request) diff --git a/notes/hermes-assistant.md b/notes/hermes-assistant.md index 91eff4cd..5aab3885 100644 --- a/notes/hermes-assistant.md +++ b/notes/hermes-assistant.md @@ -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 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. +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 diff --git a/tests/hermes-assistant.test.cjs b/tests/hermes-assistant.test.cjs index 114e000a..476c3780 100644 --- a/tests/hermes-assistant.test.cjs +++ b/tests/hermes-assistant.test.cjs @@ -60,6 +60,60 @@ test('a rejected key and an empty stream are errors', () => { 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', () => { const { normalizeHermesUrl } = hermes(); assert.equal(normalizeHermesUrl('http://192.0.2.10:8642'), 'http://192.0.2.10:8642/v1');