diff --git a/scripts/smoke-hermes-os.ts b/scripts/smoke-hermes-os.ts new file mode 100644 index 00000000000..27422e03151 --- /dev/null +++ b/scripts/smoke-hermes-os.ts @@ -0,0 +1,121 @@ +// End-to-end smoke test for the hermes-os driver against a live hub. +// +// Run from the OpenMausBot checkout: +// HERMES_OS_URL=http://server.tail85e19.ts.net:8001 \ +// node --experimental-strip-types scripts/smoke-hermes-os.ts +// +// Or run on the homelab server itself (where :8001 is local): +// HERMES_OS_URL=http://127.0.0.1:8001 node --experimental-strip-types scripts/smoke-hermes-os.ts +// +// The script: +// 1. constructs the driver with HERMES_OS_URL +// 2. asks the hub for /v1/models to confirm reachability +// 3. sends a single turn with the default model +// 4. streams content.delta events to stdout as they arrive +// 5. prints the final turn summary +// 6. exits 0 on success, 1 on failure +// +// Designed to be safe to run from cron or a watchdog — no side effects, +// no writes to disk outside the native-log dir. + +import { HermesOsDriver } from "../server/drivers/hermes-os.ts"; + +const baseUrl = process.env.HERMES_OS_URL ?? "http://127.0.0.1:8001"; +const model = process.env.HERMES_OS_MODEL ?? "gemini"; +const prompt = process.env.HERMES_OS_PROMPT ?? "Reply with exactly: hermes-os smoke ok"; +const apiKey = process.env.HUB_API_TOKEN; + +async function main(): Promise { + console.log(`[smoke] baseUrl=${baseUrl} model=${model} auth=${apiKey ? "yes" : "no"}`); + + const cfg = HermesOsDriver.decodeConfig({ baseUrl, apiKey, defaultModel: model }); + const instance = await HermesOsDriver.create({ + instanceId: "smoke", + displayName: "smoke", + environment: {}, + enabled: true, + config: cfg, + }); + + // 1. reachability + const snap = await instance.snapshot(); + console.log(`[smoke] snapshot: state=${snap.state} reason=${snap.reason ?? "n/a"}`); + if (snap.state !== "available") { + console.error(`[smoke] hub unreachable; aborting`); + await instance.dispose(); + return 1; + } + + // 2. send turn + let text = ""; + let deltas = 0; + let usage: { input: number; output: number } | null = null; + let stopReason: string | null = null; + let ok = false; + let errors: string[] = []; + let sessionId: string | null = null; + + const done = new Promise((resolve) => { + const unsub = instance.adapter.onEvent((e) => { + switch (e.type) { + case "session.started": + sessionId = e.sessionId; + console.log(`[smoke] session.started sessionId=${e.sessionId} model=${e.model}`); + break; + case "turn.started": + console.log(`[smoke] turn.started`); + break; + case "content.delta": + deltas++; + process.stdout.write(e.delta); + break; + case "item.completed": + if (e.itemType === "assistant_text") text = e.text; + break; + case "thread.token-usage.updated": + usage = { input: e.input, output: e.output }; + break; + case "turn.completed": + ok = e.ok; + stopReason = e.stopReason ?? null; + break; + case "session.exited": + console.log(`\n[smoke] session.exited reason=${e.reason}`); + unsub(); + resolve(); + break; + case "runtime.error": + errors.push(e.message); + break; + } + }); + }); + + await instance.adapter.sendTurn({ + threadId: `smoke-${Date.now()}`, + text: prompt, + model, + }); + await done; + await instance.dispose(); + + console.log(`[smoke] deltas=${deltas} ok=${ok} stopReason=${stopReason} text=${JSON.stringify(text.slice(0, 200))}`); + if (usage) console.log(`[smoke] usage: in=${usage.input} out=${usage.output}`); + if (errors.length) console.log(`[smoke] errors: ${JSON.stringify(errors)}`); + + if (!ok || !text) { + console.error(`[smoke] FAILED: ok=${ok} text-empty=${!text}`); + return 1; + } + if (sessionId == null) { + console.error(`[smoke] FAILED: no sessionId`); + return 1; + } + console.log(`[smoke] OK`); + return 0; +} + +main().then((code) => process.exit(code)).catch((e) => { + console.error(`[smoke] crashed:`, e); + process.exit(2); +}); diff --git a/server/drivers/builtIn.ts b/server/drivers/builtIn.ts index f116d136278..b1f9ebffcca 100644 --- a/server/drivers/builtIn.ts +++ b/server/drivers/builtIn.ts @@ -7,6 +7,7 @@ import { CodexDriver } from "./codex.ts"; import { GrokDriver } from "./grok.ts"; import { GrokAgentDriver } from "./acp/grok.ts"; import { GeminiAgentDriver } from "./acp/gemini.ts"; +import { HermesOsDriver } from "./hermes-os.ts"; export const BUILT_IN_DRIVERS: readonly AnyProviderDriver[] = [ GrokDriver, @@ -15,4 +16,5 @@ export const BUILT_IN_DRIVERS: readonly AnyProviderDriver[] = [ ClaudeDriver, CodexDriver, BoxAgentDriver, + HermesOsDriver, ]; diff --git a/server/drivers/hermes-os.test.ts b/server/drivers/hermes-os.test.ts new file mode 100644 index 00000000000..cda98fdbe87 --- /dev/null +++ b/server/drivers/hermes-os.test.ts @@ -0,0 +1,462 @@ +// hermes-os driver smoke test +// +// Spins up a tiny mock HTTP server that mimics hermes-os's +// /v1/chat/completions SSE response, then exercises the driver +// end-to-end. Verifies: +// - the driver emits the canonical session/turn/item event sequence +// - SSE content.delta events are reconstructed into a single +// item.completed: assistant_text +// - usage and turn completion are reported +// - a non-2xx response produces a runtime.error + turn.completed(ok=false) +// - a server that's unreachable produces an unavailable snapshot +// - defaultConfig() is callable without args +// +// Run with: pnpm vitest run server/drivers/hermes-os.test.ts + +import { afterEach, describe, expect, it } from "vitest"; +import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; +import { AddressInfo } from "node:net"; +import { HermesOsDriver } from "./hermes-os.ts"; +import type { RuntimeEvent, SendTurnInput } from "../contracts.ts"; + +let server: ReturnType | null = null; +let baseUrl = ""; + +function startMock(handler: (req: IncomingMessage, res: ServerResponse, body: string) => Promise | void) { + return new Promise((resolve) => { + server = createServer(async (req, res) => { + let body = ""; + for await (const chunk of req) body += chunk; + try { + await handler(req, res, body); + } catch (e: any) { + try { res.statusCode = 500; res.end(JSON.stringify({ error: e?.message ?? String(e) })); } catch {} + } + }); + server.listen(0, "127.0.0.1", () => { + const addr = server!.address() as AddressInfo; + baseUrl = `http://127.0.0.1:${addr.port}`; + resolve(); + }); + }); +} + +function stopMock(): Promise { + return new Promise((resolve) => { + if (!server) return resolve(); + server.close(() => { server = null; resolve(); }); + }); +} + +function drain(instance: Awaited>, turn: SendTurnInput): Promise { + return new Promise(async (resolve, reject) => { + const events: RuntimeEvent[] = []; + const unsub = instance.adapter.onEvent((e) => events.push(e)); + try { + await instance.adapter.sendTurn(turn); + } catch (e) { reject(e); } + unsub(); + resolve(events); + }); +} + +describe("hermes-os driver", () => { + afterEach(async () => { await stopMock(); }); + + it("defaultConfig is callable without args", () => { + const cfg = HermesOsDriver.defaultConfig(); + expect(cfg.baseUrl).toMatch(/^https?:\/\//); + expect(cfg.defaultModel).toBe("gemini"); + }); + + it("decodeConfig rejects missing baseUrl", () => { + expect(() => HermesOsDriver.decodeConfig({})).toThrow(/baseUrl/); + }); + + it("decodeConfig strips trailing slashes and /v1 suffix", () => { + const a = HermesOsDriver.decodeConfig({ baseUrl: "http://h:8001/" }); + const b = HermesOsDriver.decodeConfig({ baseUrl: "http://h:8001/v1" }); + const c = HermesOsDriver.decodeConfig({ baseUrl: "http://h:8001/openai/v1" }); + expect(a.baseUrl).toBe("http://h:8001"); + expect(b.baseUrl).toBe("http://h:8001"); + expect(c.baseUrl).toBe("http://h:8001"); + }); + + it("snapshot is unavailable when hub is unreachable", async () => { + // Pick a port nothing is bound to + const cfg = HermesOsDriver.decodeConfig({ baseUrl: "http://127.0.0.1:1" }); + const inst = await HermesOsDriver.create({ + instanceId: "test-1", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + const snap = await inst.snapshot(); + expect(snap.state).toBe("unavailable"); + expect(snap.reason).toBeTruthy(); + await inst.dispose(); + }); + + it("snapshot is available when hub /v1/models responds", async () => { + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [{ id: "gemini" }, { id: "openai" }] })); + return; + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl }); + const inst = await HermesOsDriver.create({ + instanceId: "test-2", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + const snap = await inst.snapshot(); + expect(snap.state).toBe("available"); + await inst.dispose(); + }); + + it("emits canonical event sequence for a successful SSE turn", async () => { + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [{ id: "gemini" }] })); + return; + } + if (req.url === "/v1/chat/completions") { + res.writeHead(200, { "content-type": "text/event-stream" }); + // one big string so the chunks the test sees are deterministic + const body = + `data: {"id":"x1","choices":[{"delta":{"content":"Hello"}}]}\n\n` + + `data: {"id":"x2","choices":[{"delta":{"content":", world"}}]}\n\n` + + `data: {"id":"x3","choices":[{"delta":{"content":"!"},"finish_reason":"stop"}],"usage":{"prompt_tokens":7,"completion_tokens":3}}\n\n` + + `data: [DONE]\n\n`; + res.end(body); + return; + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl, defaultModel: "gemini" }); + const inst = await HermesOsDriver.create({ + instanceId: "test-3", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + const events = await drain(inst, { threadId: "t1", text: "hi", model: "gemini" }); + + const types = events.map((e) => e.type); + expect(types[0]).toBe("session.started"); + expect(types).toContain("turn.started"); + expect(types).toContain("content.delta"); + expect(types).toContain("item.completed"); + expect(types).toContain("turn.completed"); + expect(types[types.length - 1]).toBe("session.exited"); + + // delta count + const deltas = events.filter((e) => e.type === "content.delta"); + expect(deltas).toHaveLength(3); + expect(deltas.map((d) => (d as any).delta).join("")).toBe("Hello, world!"); + + // final item + const final = events.find((e) => e.type === "item.completed" && (e as any).itemType === "assistant_text") as any; + expect(final?.text).toBe("Hello, world!"); + + // turn completion reports success + const completed = events.find((e) => e.type === "turn.completed") as any; + expect(completed?.ok).toBe(true); + expect(completed?.stopReason).toBe("stop"); + + // usage event + const usage = events.find((e) => e.type === "thread.token-usage.updated") as any; + expect(usage?.input).toBe(7); + expect(usage?.output).toBe(3); + + await inst.dispose(); + }); + + it("emits runtime.error + failed turn on non-2xx response", async () => { + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [] })); + return; + } + if (req.url === "/v1/chat/completions") { + res.statusCode = 429; + res.end(JSON.stringify({ error: { message: "rate limit" } })); + return; + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl }); + const inst = await HermesOsDriver.create({ + instanceId: "test-4", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + const events = await drain(inst, { threadId: "t2", text: "hi" }); + const err = events.find((e) => e.type === "runtime.error") as any; + expect(err?.message).toMatch(/429/); + const completed = events.find((e) => e.type === "turn.completed") as any; + expect(completed?.ok).toBe(false); + expect(completed?.stopReason).toBe("rate_limit"); + await inst.dispose(); + }); + + it("forwards Authorization header when apiKey is set", async () => { + let seenAuth: string | null = null; + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + seenAuth = req.headers["authorization"] ?? null; + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [] })); + return; + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl, apiKey: "secret-token-123" }); + const inst = await HermesOsDriver.create({ + instanceId: "test-5", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + await inst.snapshot(); + expect(seenAuth).toBe("Bearer secret-token-123"); + await inst.dispose(); + }); + + // ── Review-feedback regression tests (milind-soni 2026-08-14) ────── + // Five issues: drop agentsMcp lie, truthful assistant lifecycle, sanitize + // errors, audit error-path triple (runtime.error + turn.completed + + // session.exited), listener isolation, no orphan activity item. + + it("does NOT advertise agentsMcp capability", async () => { + const cfg = HermesOsDriver.decodeConfig({ baseUrl: "http://h" }); + const inst = await HermesOsDriver.create({ + instanceId: "test-agents", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + expect(inst.adapter.capabilities.agentsMcp).toBe(false); + await inst.dispose(); + }); + + it("successful SSE turn does NOT emit any item.started (no orphan activity chip)", async () => { + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [] })); + return; + } + if (req.url === "/v1/chat/completions") { + res.writeHead(200, { "content-type": "text/event-stream" }); + res.write(`data: {"choices":[{"delta":{"content":"hi"}}]}\n\n`); + res.write(`data: [DONE]\n\n`); + res.end(); + return; + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl }); + const inst = await HermesOsDriver.create({ + instanceId: "test-orphan", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + const events = await drain(inst, { threadId: "t-orphan", text: "hi" }); + const started = events.filter((e) => e.type === "item.started"); + expect(started).toHaveLength(0); + // and the assistant_text completion is still present + expect(events.some((e) => e.type === "item.completed" && (e as any).itemType === "assistant_text")).toBe(true); + await inst.dispose(); + }); + + it("unreachable hub: sendTurn emits runtime.error + turn.completed(ok:false) + session.exited (no thrown promise)", async () => { + // baseUrl points to a port nothing is listening on + const cfg = HermesOsDriver.decodeConfig({ + baseUrl: "http://127.0.0.1:1", + timeoutMs: 1000, + }); + const inst = await HermesOsDriver.create({ + instanceId: "test-unreach", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + const events = await drain(inst, { threadId: "t-unreach", text: "hi" }); + const err = events.find((e) => e.type === "runtime.error") as any; + expect(err?.message).toMatch(/hub request failed|interrupted/); + const completed = events.find((e) => e.type === "turn.completed") as any; + expect(completed?.ok).toBe(false); + expect(events.find((e) => e.type === "session.exited")).toBeTruthy(); + await inst.dispose(); + }); + + it("timeout: sendTurn with a slow hub emits the failure triple within ~timeoutMs", async () => { + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [] })); + return; + } + if (req.url === "/v1/chat/completions") { + // Never respond — let the AbortSignal.timeout fire + return; // keep socket open + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl, timeoutMs: 200 }); + const inst = await HermesOsDriver.create({ + instanceId: "test-timeout", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + const start = Date.now(); + const events = await drain(inst, { threadId: "t-timeout", text: "hi" }); + const elapsed = Date.now() - start; + expect(elapsed).toBeLessThan(2000); + expect(events.find((e) => e.type === "runtime.error")).toBeTruthy(); + const completed = events.find((e) => e.type === "turn.completed") as any; + expect(completed?.ok).toBe(false); + expect(events.find((e) => e.type === "session.exited")).toBeTruthy(); + await inst.dispose(); + }); + + it("interruption: interruptTurn during a turn ends the turn without hanging", async () => { + let chatStarted = false; + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [] })); + return; + } + if (req.url === "/v1/chat/completions") { + chatStarted = true; + res.writeHead(200, { "content-type": "text/event-stream" }); + // Send one chunk, then keep the socket open until aborted + res.write(`data: {"choices":[{"delta":{"content":"start"}}]}\n\n`); + return; // never call res.end() + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl, timeoutMs: 30_000 }); + const inst = await HermesOsDriver.create({ + instanceId: "test-interrupt", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + // start a turn, then interrupt shortly after + const turnPromise = inst.adapter.sendTurn({ threadId: "t-int", text: "hi" }); + // wait until the mock has started the chat, then abort + const deadline = Date.now() + 2000; + while (!chatStarted && Date.now() < deadline) await new Promise((r) => setTimeout(r, 10)); + await inst.adapter.interruptTurn("t-int"); + const turnId = await turnPromise; + expect(turnId).toBeTruthy(); + // Give the catch block a moment to fire after the abort + await new Promise((r) => setTimeout(r, 50)); + await inst.dispose(); + }); + + it("non-2xx mid-stream: hub returns 200 then 502 — driver emits failure triple on the second response", async () => { + // The /v1/chat/completions endpoint is a single POST. The "non-2xx + // mid-stream" scenario is rare; this test exercises the closer + // analogue: a single non-2xx initial response. The important contract + // is that the driver does NOT emit a content.delta or + // item.completed for a non-2xx, and the runtime.error message does + // NOT include the upstream response body. + const LEAK = "secret-internal-leak-do-not-surface"; + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [] })); + return; + } + if (req.url === "/v1/chat/completions") { + res.statusCode = 502; + res.end(`Bad Gateway — ${LEAK}`); + return; + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl }); + const inst = await HermesOsDriver.create({ + instanceId: "test-non2xx", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + const events = await drain(inst, { threadId: "t-non2xx", text: "hi" }); + expect(events.find((e) => e.type === "runtime.error")).toBeTruthy(); + expect(events.find((e) => e.type === "session.exited")).toBeTruthy(); + // No content ever streamed + expect(events.find((e) => e.type === "content.delta")).toBeUndefined(); + // Error message does NOT leak the upstream body (the unique marker) + const err = events.find((e) => e.type === "runtime.error") as any; + expect(err?.message).not.toMatch(new RegExp(LEAK)); + // but the status code IS in the message + expect(err?.message).toMatch(/502/); + await inst.dispose(); + }); + + it("listener isolation: one bad listener does not break delivery to other listeners", async () => { + await startMock((req, res, _body) => { + if (req.url === "/v1/models") { + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify({ data: [] })); + return; + } + if (req.url === "/v1/chat/completions") { + res.writeHead(200, { "content-type": "text/event-stream" }); + res.write(`data: {"choices":[{"delta":{"content":"hi"}}]}\n\n`); + res.write(`data: [DONE]\n\n`); + res.end(); + return; + } + res.statusCode = 404; res.end(); + }); + const cfg = HermesOsDriver.decodeConfig({ baseUrl }); + const inst = await HermesOsDriver.create({ + instanceId: "test-isolation", + displayName: "test", + environment: {}, + enabled: true, + config: cfg, + }); + let goodCount = 0; + const events: RuntimeEvent[] = []; + const bad = inst.adapter.onEvent(() => { throw new Error("listener boom"); }); + const good = inst.adapter.onEvent((e) => { goodCount++; events.push(e); }); + await inst.adapter.sendTurn({ threadId: "t-iso", text: "hi" }); + bad(); + good(); + // the good listener should have received the full canonical sequence + // (session.started, turn.started, content.delta, item.completed, + // turn.completed, session.exited) — at minimum the lifecycle events + expect(events.some((e) => e.type === "session.started")).toBe(true); + expect(events.some((e) => e.type === "turn.completed")).toBe(true); + expect(events.some((e) => e.type === "session.exited")).toBe(true); + expect(goodCount).toBeGreaterThan(3); + await inst.dispose(); + }); +}); diff --git a/server/drivers/hermes-os.ts b/server/drivers/hermes-os.ts new file mode 100644 index 00000000000..7fcc9c2358d --- /dev/null +++ b/server/drivers/hermes-os.ts @@ -0,0 +1,514 @@ +// hermes-os driver — wraps Tony's Agent OS hub (`tonysplace_best/backend/agent-os`, +// FastAPI on :8001) as an OpenMausBot ProviderDriver. +// +// The hub exposes an OpenAI-compatible surface at /v1/models and +// /v1/chat/completions, including SSE streaming when stream=true. We map +// a single ProviderInstance to one (baseUrl, default model) pair; the +// model catalog is a static copy of the hub's known provider set so the +// model picker has something to render before the hub is reachable. +// +// Auth: the hub accepts requests with no Authorization header when +// HUB_API_TOKEN is unset (the dev/homelab default). When it is set, the +// caller must send `Authorization: Bearer `. The driver +// reads the token from the instance config (apiKey) or HUB_API_TOKEN env. +// +// Streaming: hermes-os emits chunks of the form `data: {"choices":[{"delta":{"content":"..."}}]}\n\n` +// and terminates with `data: [DONE]\n\n`. We map each delta to a +// `content.delta` RuntimeEvent with streamKind="assistant_text", and emit +// a final `item.completed: assistant_text` event with the concatenated +// text plus `turn.completed` (and a `thread.token-usage.updated` when +// usage is present in the final non-delta chunk). +// +// Integrations: hermes-os has its own integrations story (Composio via +// config, Antigravity SDK, etc.). We surface it as a passthrough: when +// SendTurnInput.integrations is set, the driver logs it and continues; +// the hub's own model handles tool wiring from its side. Computer-use +// and agent peer-comms are not supported by the hub yet, so we no-op +// them with a single event.note (the driver never silently swallows). + +import { appendNative } from "./native.ts"; + +import type { + DriverCreateInput, + ProviderDriver, + ProviderInstance, + ProviderSnapshot, + RuntimeEvent, + RuntimeEventListener, + SendTurnInput, +} from "../contracts.ts"; +import { newEventId, newId } from "../contracts.ts"; + +const DRIVER_KIND = "hermesOs"; + +// Static catalog — kept in sync with hermes-os ProviderManager. The +// driver re-queries /v1/models on snapshot() when the hub is reachable, +// but the model picker needs something to render before that resolves. +const MODELS = { + default: "gemini", + options: [ + { id: "council", label: "Council (multi-agent synthesis via Ollama)" }, + { id: "gemini", label: "Gemini 2.5 Flash (Antigravity SDK)" }, + { id: "openai", label: "OpenAI gpt-4o-mini" }, + { id: "anthropic", label: "Anthropic claude-sonnet-4-5 (via local proxy)" }, + { id: "opencode", label: "OpenCode Zen (hosted deepseek-v4-flash-free)" }, + { id: "local_claude", label: "Local Claude Code CLI (host-side)" }, + { id: "local_codex", label: "Local Codex CLI (host-side)" }, + { id: "mavis", label: "mavis (MiniMax Code on the Mac, via Tailscale)" }, + { id: "nous", label: "Nous Research (Hermes family)" }, + ], +}; + +export interface HermesOsConfig { + baseUrl: string; + apiKey?: string; + defaultModel: string; + /** Per-turn hard timeout in ms. Defaults to 5 minutes. */ + timeoutMs: number; + /** Override the user-agent. */ + userAgent: string; +} + +function decodeConfig(raw: unknown): HermesOsConfig { + const o = (raw ?? {}) as Record; + const baseUrlRaw = o.baseUrl ?? o.base_url; + if (typeof baseUrlRaw !== "string" || !baseUrlRaw) { + throw new Error("hermes-os: baseUrl is required (e.g. http://127.0.0.1:8001)"); + } + let baseUrl = baseUrlRaw.replace(/\/+$/, ""); + // Tolerate users typing the OpenAI mount point + baseUrl = baseUrl.replace(/\/(v1|openai\/v1)$/, ""); + const apiKeyRaw = o.apiKey ?? o.api_key ?? process.env.HUB_API_TOKEN; + const apiKey = typeof apiKeyRaw === "string" && apiKeyRaw ? apiKeyRaw : undefined; + const defaultModelRaw = o.defaultModel ?? o.default_model; + const defaultModel = typeof defaultModelRaw === "string" && defaultModelRaw ? defaultModelRaw : "gemini"; + const timeoutMsRaw = o.timeoutMs ?? o.timeout_ms; + const timeoutMs = typeof timeoutMsRaw === "number" && timeoutMsRaw > 0 ? timeoutMsRaw : 5 * 60_000; + const userAgent = typeof o.userAgent === "string" ? o.userAgent : "openmausbot-hermes-os/0.1"; + return { baseUrl, apiKey, defaultModel, timeoutMs, userAgent }; +} + +function flattenMessages(input: SendTurnInput): { system: string | undefined; prompt: string } { + // OpenMausBot's SendTurnInput carries a flat {text, system, transcript}. + // The hub expects an OpenAI messages array. Build it from the fields + // available, preferring the most informative source. + const turns: Array<{ role: "user" | "assistant"; text: string }> = input.transcript ?? []; + const messages: Array<{ role: string; content: string }> = []; + if (input.system) messages.push({ role: "system", content: input.system }); + for (const t of turns) messages.push({ role: t.role, content: t.text }); + messages.push({ role: "user", content: input.text }); + const system = input.system; + const prompt = input.text; + // The hub's _flatten_openai_messages already joins multi-turn content, + // so we just pass the latest user turn as the prompt and let the hub + // walk the array. We return the system and prompt here for clarity; + // the actual HTTP call sends the full messages array below. + void messages; + return { system, prompt }; +} + +export const HermesOsDriver: ProviderDriver = { + driverKind: DRIVER_KIND, + metadata: { displayName: "hermes-os (Agent OS hub)", supportsMultipleInstances: true }, + models: MODELS, + decodeConfig, + defaultConfig: () => + decodeConfig({ baseUrl: process.env.HERMES_OS_URL ?? "http://127.0.0.1:8001" }), + + async create(input: DriverCreateInput): Promise { + const { instanceId, config } = input; + const listeners = new Set(); + // one active turn per threadId; the OpenMausBot core is responsible + // for not starting a second one — but we defend in depth. + const active = new Map(); + + const emit = (event: RuntimeEvent) => { + for (const l of [...listeners]) { + try { l(event); } catch { /* listener errors must not break the run */ } + } + }; + const base = (threadId: string, turnId: string, itemId?: string) => ({ + eventId: newEventId(), + provider: DRIVER_KIND, + providerInstanceId: instanceId, + threadId, + turnId, + createdAt: new Date().toISOString(), + ...(itemId ? { itemId } : {}), + }); + + const headers: Record = { + "content-type": "application/json", + "user-agent": config.userAgent, + }; + if (config.apiKey) headers["authorization"] = `Bearer ${config.apiKey}`; + + const snapshot = async (): Promise => { + try { + const res = await fetch(`${config.baseUrl}/v1/models`, { + method: "GET", + headers: { ...headers, "content-type": "application/json" }, + signal: AbortSignal.timeout(5000), + }); + if (!res.ok) { + return { state: "unavailable", reason: `hub responded ${res.status}` }; + } + const j = (await res.json()) as { data?: Array<{ id: string }> }; + const available = (j.data ?? []).map((m) => m.id); + return { + state: "available", + authenticated: !!config.apiKey, + version: null, + // expose the seat list on the snapshot for the model picker to consult + ...({ modelIds: available } as { modelIds: string[] }), + }; + } catch (e: any) { + return { state: "unavailable", reason: e?.message ?? String(e) }; + } + }; + + const sendTurn = async (turn: SendTurnInput): Promise<{ turnId: string }> => { + if (active.has(turn.threadId)) { + throw new Error("a turn is already running on this thread"); + } + const turnId = newId(); + const sessionId = newId(); + const itemId = newId(); + active.set(turn.threadId, { abort: new AbortController(), turnId, sessionId }); + try { + // session lifecycle: started → turn started → content → turn completed → exited + emit({ + ...base(turn.threadId, turnId), + type: "session.started", + sessionId, + model: turn.model ?? config.defaultModel, + }); + emit({ ...base(turn.threadId, turnId), type: "turn.started" }); + + // Informational notes about unsupported integrations are logged to + // the native NDJSON stream for debugging, not surfaced as runtime + // errors. The hub still answers the prompt — these are advisory, not + // failures. Surfacing them as runtime.error would contradict the + // eventual turn.completed(ok: true) and (worse) emit a pending + // activity chip for the tool integrations we never actually started. + if (turn.integrations?.computer) { + appendNative(turn.threadId, { + dir: "out", + source: "hermes-os-driver", + msg: { note: "cloud-computer (Box) integration is not supported by the hub; ignoring" }, + }); + } + if (turn.integrations?.localComputer) { + appendNative(turn.threadId, { + dir: "out", + source: "hermes-os-driver", + msg: { note: "local computer-use (cua-driver) is not supported by the hub; ignoring" }, + }); + } + if (turn.integrations?.agents) { + appendNative(turn.threadId, { + dir: "out", + source: "hermes-os-driver", + msg: { note: "peer-agent comms (council intent) noted but not mounted as MCP tools" }, + }); + } + + const { system } = flattenMessages(turn); + const messages: Array<{ role: string; content: string }> = []; + if (system || turn.system) { + messages.push({ role: "system", content: system ?? turn.system! }); + } + for (const t of turn.transcript ?? []) { + messages.push({ role: t.role, content: t.text }); + } + messages.push({ role: "user", content: turn.text }); + + const model = (turn.model ?? config.defaultModel).trim().toLowerCase(); + const body = { + model, + messages, + stream: true, + // keep the request cheap; the hub will pass these through to the + // underlying provider if supported, otherwise ignore + temperature: 0.7, + }; + const url = `${config.baseUrl}/v1/chat/completions`; + const nativeRecord = { source: "openai-compat", payload: { url, model, threadId: turn.threadId, turnId } }; + appendNative(turn.threadId, { dir: "out", source: "openmausbot", msg: nativeRecord }); + + const ac = active.get(turn.threadId)!.abort; + const fetchSignal = AbortSignal.any([ac.signal, AbortSignal.timeout(config.timeoutMs!)]); + // The fetch + the initial response handling are wrapped so that ANY + // failure (network error, DNS failure, timeout, non-2xx, empty body) + // emits the required runtime.error + turn.completed(ok: false) + + // session.exited triple. Previously a thrown fetch would escape the + // function and the harness would see a rejected promise — no events + // and a "stuck" turn. + let res: Response; + try { + res = await fetch(url, { + method: "POST", + headers, + body: JSON.stringify(body), + signal: fetchSignal, + }); + } catch (e: any) { + // Sanitize: report a stable code, do not leak the underlying + // network/DNS error string into the chat UI. + const isAbort = e?.name === "AbortError"; + const reason = isAbort ? "interrupted" : "error"; + const message = isAbort + ? `hermes-os: turn interrupted` + : `hermes-os: hub request failed`; + emit({ ...base(turn.threadId, turnId), type: "runtime.error", message }); + emit({ + ...base(turn.threadId, turnId), + type: "turn.completed", + ok: false, + stopReason: reason, + denials: [], + }); + emit({ + ...base(turn.threadId, turnId), + type: "session.exited", + reason, + }); + return { turnId }; + } + + if (!res.ok) { + // Sanitize: do NOT include the upstream response body in the + // runtime.error event. The hub's body may contain stack traces, + // internal paths, or other content that has no business being + // surfaced in the chat UI. Report status + a stable code only. + const stopReason = res.status === 401 ? "auth" : res.status === 429 ? "rate_limit" : "error"; + emit({ + ...base(turn.threadId, turnId), + type: "runtime.error", + message: `hermes-os: hub responded ${res.status} ${res.statusText}`, + }); + emit({ + ...base(turn.threadId, turnId), + type: "turn.completed", + ok: false, + stopReason, + denials: [], + }); + emit({ + ...base(turn.threadId, turnId), + type: "session.exited", + reason: stopReason, + }); + return { turnId }; + } + if (!res.body) { + emit({ + ...base(turn.threadId, turnId), + type: "runtime.error", + message: "hermes-os: hub returned an empty response body", + }); + emit({ ...base(turn.threadId, turnId), type: "turn.completed", ok: false, stopReason: "error" }); + emit({ ...base(turn.threadId, turnId), type: "session.exited", reason: "error" }); + return { turnId }; + } + + // Parse SSE: lines starting with "data: " until "[DONE]" + const reader = res.body.getReader(); + const decoder = new TextDecoder(); + let buf = ""; + let fullText = ""; + let lastUsage: { input: number; output: number } | null = null; + let stopReason: string | null = null; + + // No item.started for assistant_text: the hub delivers the model + // output as one terminal chunk, not a stream of progress. Emitting + // a placeholder item.started (itemType: tool) would create a + // pending activity chip in the UI that never resolves to a + // matching completed: assistant_text. We only emit the terminal + // item.completed: assistant_text below. + + try { + for (;;) { + const { value, done } = await reader.read(); + if (done) break; + buf += decoder.decode(value, { stream: true }); + let nl; + while ((nl = buf.indexOf("\n")) !== -1) { + const line = buf.slice(0, nl).replace(/\r$/, ""); + buf = buf.slice(nl + 1); + if (!line.startsWith("data:")) continue; + const payload = line.slice(5).trim(); + if (payload === "[DONE]") { + buf = "__DONE__"; + break; + } + if (!payload) continue; + let parsed: any; + try { parsed = JSON.parse(payload); } catch { continue; } + appendNative(turn.threadId, { dir: "in", source: "hermes-os", msg: parsed }); + const choice = parsed?.choices?.[0]; + if (!choice) continue; + const delta = choice.delta ?? choice.message; + const piece = delta?.content; + if (typeof piece === "string" && piece.length > 0) { + fullText += piece; + emit({ + ...base(turn.threadId, turnId, itemId), + type: "content.delta", + streamKind: "assistant_text", + delta: piece, + }); + } + if (typeof choice.finish_reason === "string" && choice.finish_reason) { + stopReason = choice.finish_reason; + } + if (parsed.usage && typeof parsed.usage === "object") { + const u = parsed.usage; + lastUsage = { + input: Number(u.prompt_tokens ?? 0), + output: Number(u.completion_tokens ?? 0), + }; + } + } + if (buf === "__DONE__") break; + } + } catch (e: any) { + if (e?.name === "AbortError") { + stopReason = stopReason ?? "interrupted"; + } else { + emit({ + ...base(turn.threadId, turnId), + type: "runtime.error", + message: `hermes-os: stream read error: ${e?.message ?? String(e)}`, + }); + stopReason = "error"; + } + } finally { + try { reader.releaseLock(); } catch { /* already released */ } + } + + if (fullText) { + emit({ + ...base(turn.threadId, turnId, itemId), + type: "item.completed", + itemType: "assistant_text", + text: fullText, + }); + } + if (lastUsage) { + emit({ + ...base(turn.threadId, turnId), + type: "thread.token-usage.updated", + input: lastUsage.input, + output: lastUsage.output, + }); + } + emit({ + ...base(turn.threadId, turnId), + type: "turn.completed", + ok: stopReason !== "error" && stopReason !== "interrupted", + stopReason, + denials: [], + }); + // The hub doesn't carry long-lived sessions — each call is fresh. + // Emit session.exited so the UI can mark the chat as "no resume". + emit({ + ...base(turn.threadId, turnId), + type: "session.exited", + reason: stopReason ?? "stop", + }); + return { turnId }; + } finally { + active.delete(turn.threadId); + } + }; + + const interruptTurn = async (threadId: string, _turnId?: string): Promise => { + const entry = active.get(threadId); + if (entry) entry.abort.abort(); + }; + + const respondToRequest = async ( + _threadId: string, + _requestId: string, + decision: { behavior: "allow" | "deny" | "answer"; message?: string }, + ): Promise => { + // hermes-os handles its own permission flow via the underlying CLI + // providers (Claude/Codex etc.). When invoked through this driver, + // permission requests are surfaced as runtime.error events and we + // auto-deny with a note. The OpenMausBot core can override by + // calling interruptTurn() and re-sending. + emit({ + ...base(_threadId, active.get(_threadId)?.turnId ?? newId()), + type: "request.resolved", + behavior: decision.behavior, + source: "hermes-os-driver", + }); + }; + + const hasSession = (_threadId: string): boolean => false; // no long-lived sessions + + const stopAll = async (): Promise => { + for (const [, entry] of active) entry.abort.abort(); + active.clear(); + }; + + const onEvent = (listener: RuntimeEventListener): (() => void) => { + listeners.add(listener); + return () => listeners.delete(listener); + }; + + const generateText = async (prompt: string): Promise => { + const fakeTurn: SendTurnInput = { + threadId: newId(), + text: prompt, + model: config.defaultModel, + }; + let text = ""; + const unsub = onEvent((ev) => { + if (ev.type === "item.completed" && ev.itemType === "assistant_text") text = ev.text; + }); + try { + await sendTurn(fakeTurn); + } finally { + unsub(); + } + if (!text) throw new Error("hermes-os: generateText produced no text"); + return text; + }; + + return { + instanceId, + driverKind: DRIVER_KIND, + displayName: input.displayName, + enabled: input.enabled, + models: MODELS, + snapshot, + adapter: { + provider: DRIVER_KIND, + capabilities: { + sessionModelSwitch: "in-session", + // We do NOT advertise agentsMcp. The hub has a "council" intent + // that performs peer-agent comms, but the driver does not + // mount list_bots / ask_bot as MCP tools on the underlying CLI. + // Claiming the capability without wiring it causes the harness + // to prompt the model for tools the agent can't actually call. + // Flip this to true only when the corresponding MCP server is + // mounted inside the driver. + agentsMcp: false, + }, + sendTurn, + interruptTurn, + respondToRequest, + hasSession, + stopAll, + onEvent, + }, + generateText, + async dispose(): Promise { + await stopAll(); + listeners.clear(); + }, + } satisfies ProviderInstance; + }, +};