@fideliosai/adapter-hermes-local 0.0.41 → 0.0.43

package/src/server/headless.test.js

@@ -0,0 +1,253 @@
+/**
+ * Tests for FID-52: headless I/O contract.
+ */
+import { describe, it, expect, vi } from "vitest";
+
+import {
+    isHeadlessEnv,
+    filterHeadlessUnsafe,
+    filterHeadlessCsv,
+    parseClarifyMarker,
+    escalateClarify,
+} from "./headless.js";
+
+describe("isHeadlessEnv", () => {
+    it("returns true when FIDELIOS_RUN_ID is present", () => {
+        expect(isHeadlessEnv({ FIDELIOS_RUN_ID: "abc" })).toBe(true);
+    });
+
+    it("returns true when FIDELIOS_HEADLESS=1", () => {
+        expect(isHeadlessEnv({ FIDELIOS_HEADLESS: "1" })).toBe(true);
+        expect(isHeadlessEnv({ FIDELIOS_HEADLESS: "true" })).toBe(true);
+    });
+
+    it("explicit FIDELIOS_HEADLESS=0 wins over RUN_ID (used for tests)", () => {
+        expect(isHeadlessEnv({ FIDELIOS_HEADLESS: "0", FIDELIOS_RUN_ID: "x" })).toBe(false);
+    });
+
+    it("returns false on empty env when stdin is a TTY", () => {
+        expect(isHeadlessEnv({}, { stdinIsTTY: true })).toBe(false);
+    });
+
+    it("returns true when stdin is not a TTY (and no FideliOS markers)", () => {
+        expect(isHeadlessEnv({}, { stdinIsTTY: false })).toBe(true);
+    });
+
+    it("returns false when neither marker nor TTY hint is present (assume interactive)", () => {
+        expect(isHeadlessEnv({})).toBe(false);
+    });
+});
+
+describe("filterHeadlessUnsafe", () => {
+    it("strips clarify (registry-flagged headlessSafe:false)", () => {
+        const r = filterHeadlessUnsafe(["file", "clarify", "web"]);
+        expect(r.kept).toEqual(["file", "web"]);
+        expect(r.stripped).toEqual(["clarify"]);
+    });
+
+    it("preserves order of kept names", () => {
+        const r = filterHeadlessUnsafe(["clarify", "terminal", "clarify", "file"]);
+        expect(r.kept).toEqual(["terminal", "file"]);
+        expect(r.stripped).toEqual(["clarify", "clarify"]);
+    });
+
+    it("leaves unknown names alone (Hermes / triage handle those)", () => {
+        const r = filterHeadlessUnsafe(["mystery", "file"]);
+        expect(r.kept).toEqual(["mystery", "file"]);
+        expect(r.stripped).toEqual([]);
+    });
+
+    it("accepts a custom registry override", () => {
+        const reg = [
+            { name: "alpha", headlessSafe: false },
+            { name: "beta" },
+        ];
+        const r = filterHeadlessUnsafe(["alpha", "beta", "clarify"], reg);
+        // Note: with custom registry, `clarify` is unknown → kept.
+        expect(r.kept).toEqual(["beta", "clarify"]);
+        expect(r.stripped).toEqual(["alpha"]);
+    });
+});
+
+describe("filterHeadlessCsv", () => {
+    it("filters comma-separated input and returns new csv", () => {
+        const r = filterHeadlessCsv("file,clarify,web");
+        expect(r.csv).toBe("file,web");
+        expect(r.stripped).toEqual(["clarify"]);
+    });
+
+    it("returns empty string when nothing is left after stripping", () => {
+        const r = filterHeadlessCsv("clarify");
+        expect(r.csv).toBe("");
+        expect(r.stripped).toEqual(["clarify"]);
+    });
+
+    it("passes through undefined input", () => {
+        const r = filterHeadlessCsv(undefined);
+        expect(r.csv).toBeUndefined();
+        expect(r.stripped).toEqual([]);
+    });
+
+    it("passes through empty string input", () => {
+        const r = filterHeadlessCsv("");
+        expect(r.csv).toBe("");
+        expect(r.stripped).toEqual([]);
+    });
+
+    it("trims whitespace and skips empty entries", () => {
+        const r = filterHeadlessCsv(" file , clarify ,, web ");
+        expect(r.csv).toBe("file,web");
+        expect(r.stripped).toEqual(["clarify"]);
+    });
+});
+
+describe("parseClarifyMarker", () => {
+    it("extracts question from a verbose tool-call line", () => {
+        const line = `[tool] clarify {"question":"What now?","choices":["a","b"]}`;
+        expect(parseClarifyMarker(line)).toBe("What now?");
+    });
+
+    it("returns null for unrelated lines", () => {
+        expect(parseClarifyMarker("[tool] file {\"path\":\"x\"}")).toBeNull();
+        expect(parseClarifyMarker("session_id: abc")).toBeNull();
+        expect(parseClarifyMarker("")).toBeNull();
+        expect(parseClarifyMarker(null)).toBeNull();
+    });
+
+    it("returns null when JSON cannot be parsed", () => {
+        expect(parseClarifyMarker("[tool] clarify { not-json")).toBeNull();
+    });
+});
+
+describe("escalateClarify", () => {
+    function jsonRes(status, body) {
+        return {
+            ok: status >= 200 && status < 300,
+            status,
+            json: async () => body,
+        };
+    }
+
+    it("posts comment + PATCHes blocked and returns commentId", async () => {
+        const calls = [];
+        const fetchImpl = vi.fn(async (url, init) => {
+            calls.push({ url, method: init.method, body: init.body });
+            if (init.method === "POST") return jsonRes(201, { id: "c-1" });
+            return jsonRes(200, {});
+        });
+        const r = await escalateClarify({
+            question: "Pick A or B?",
+            taskId: "task-1",
+            apiUrl: "http://api/api",
+            fetchImpl,
+        });
+        expect(r.ok).toBe(true);
+        expect(r.commentId).toBe("c-1");
+        expect(calls).toHaveLength(2);
+        expect(calls[0].url).toBe("http://api/api/issues/task-1/comments");
+        expect(calls[0].method).toBe("POST");
+        expect(JSON.parse(calls[0].body).body).toMatch(/Agent question.*Pick A or B/);
+        expect(calls[1].url).toBe("http://api/api/issues/task-1");
+        expect(calls[1].method).toBe("PATCH");
+        expect(JSON.parse(calls[1].body)).toEqual({ status: "blocked" });
+    });
+
+    it("attaches Authorization header when apiKey is provided", async () => {
+        const fetchImpl = vi.fn(async () => jsonRes(201, { id: "c-2" }));
+        await escalateClarify({
+            question: "q",
+            taskId: "t",
+            apiUrl: "http://api/api",
+            apiKey: "secret",
+            fetchImpl,
+        });
+        expect(fetchImpl.mock.calls[0][1].headers["Authorization"]).toBe("Bearer secret");
+    });
+
+    it("trims trailing slash from apiUrl", async () => {
+        const fetchImpl = vi.fn(async () => jsonRes(201, { id: "c-3" }));
+        await escalateClarify({
+            question: "q",
+            taskId: "t",
+            apiUrl: "http://api/api/",
+            fetchImpl,
+        });
+        expect(fetchImpl.mock.calls[0][0]).toBe("http://api/api/issues/t/comments");
+    });
+
+    it("returns error when comment POST fails", async () => {
+        const fetchImpl = vi.fn(async () => jsonRes(500, { error: "boom" }));
+        const r = await escalateClarify({
+            question: "q",
+            taskId: "t",
+            apiUrl: "http://api/api",
+            fetchImpl,
+        });
+        expect(r.ok).toBe(false);
+        expect(r.error).toMatch(/comment POST 500/);
+    });
+
+    it("returns error when status PATCH fails (but reports commentId)", async () => {
+        let i = 0;
+        const fetchImpl = vi.fn(async () => {
+            i += 1;
+            if (i === 1) return jsonRes(201, { id: "c-4" });
+            return jsonRes(403, { error: "no" });
+        });
+        const r = await escalateClarify({
+            question: "q",
+            taskId: "t",
+            apiUrl: "http://api/api",
+            fetchImpl,
+        });
+        expect(r.ok).toBe(false);
+        expect(r.commentId).toBe("c-4");
+        expect(r.error).toMatch(/status PATCH 403/);
+    });
+
+    it("returns error when fetch throws", async () => {
+        const fetchImpl = vi.fn(async () => {
+            throw new Error("network down");
+        });
+        const r = await escalateClarify({
+            question: "q",
+            taskId: "t",
+            apiUrl: "http://api/api",
+            fetchImpl,
+        });
+        expect(r.ok).toBe(false);
+        expect(r.error).toMatch(/network down/);
+    });
+
+    it("rejects with structured error when taskId / apiUrl missing", async () => {
+        const fetchImpl = vi.fn();
+        let r = await escalateClarify({ question: "q", apiUrl: "http://api", fetchImpl });
+        expect(r.ok).toBe(false);
+        expect(r.error).toBe("taskId required");
+        r = await escalateClarify({ question: "q", taskId: "t", fetchImpl });
+        expect(r.ok).toBe(false);
+        expect(r.error).toBe("apiUrl required");
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+
+    it("rejects when fetch is not available", async () => {
+        const r = await escalateClarify({
+            question: "q",
+            taskId: "t",
+            apiUrl: "http://api",
+            fetchImpl: undefined,
+            // simulate by overriding globalThis.fetch via temp deletion
+        });
+        // Real-world cwd: globalThis.fetch exists in node 18+, so this test
+        // path is only exercised in environments without fetch. The helper
+        // returns ok:false in that case.
+        if (typeof globalThis.fetch !== "function") {
+            expect(r.ok).toBe(false);
+            expect(r.error).toBe("fetch not available");
+        } else {
+            // When fetch is present it goes through and fails on the network
+            // call to a fake host — still ok:false.
+            expect(r.ok).toBe(false);
+        }
+    });
+});

package/src/server/toolset-registry.js

@@ -0,0 +1,95 @@
+/**
+ * Canonical registry of Hermes Agent built-in toolsets.
+ *
+ * Snapshot from `hermes tools list` (Hermes Agent v0.12.0, 2026.4.30).
+ * Used by the triage engine (FID-48) to:
+ *   1. expose names + descriptions to the triage LLM,
+ *   2. filter LLM-returned toolsets to known names,
+ *   3. supply a safe-default fallback when triage fails.
+ *
+ * Source-of-truth refresh policy: rerun `hermes tools list` and update this
+ * file when a new Hermes release adds/removes toolsets.
+ *
+ * `headlessSafe` flag:
+ *   - false  → tool is known to block on stdin or otherwise hang in headless mode.
+ *   - true (or omitted) → safe for unattended runs.
+ * Currently only `clarify` is marked unsafe (FID-47). The headless I/O contract
+ * is being addressed separately under FID-52.
+ */
+
+/**
+ * @typedef {Object} ToolsetEntry
+ * @property {string} name           Canonical Hermes toolset name (matches `-t` flag).
+ * @property {string} description    Human + LLM-facing description for triage prompt.
+ * @property {boolean} [headlessSafe] Default true; false for stdin-blocking toolsets.
+ */
+
+/** @type {ToolsetEntry[]} */
+export const HERMES_TOOLSET_REGISTRY = [
+  { name: "web", description: "Web Search & Scraping — fetch and parse pages, run web queries." },
+  { name: "browser", description: "Browser Automation — drive a real browser (clicks, forms, screenshots)." },
+  { name: "terminal", description: "Terminal & Processes — run shell commands, manage long-running processes." },
+  { name: "file", description: "File Operations — read, write, edit files on disk." },
+  { name: "code_execution", description: "Code Execution — run Python / JavaScript snippets in a sandbox." },
+  { name: "vision", description: "Vision / Image Analysis — describe and reason about images." },
+  { name: "video", description: "Video Analysis — extract frames, transcribe, summarize video." },
+  { name: "image_gen", description: "Image Generation — generate images from text prompts." },
+  { name: "moa", description: "Mixture of Agents — multi-model ensemble reasoning." },
+  { name: "tts", description: "Text-to-Speech — synthesize spoken audio from text." },
+  { name: "skills", description: "Skills — invoke installed Hermes skill packages." },
+  { name: "todo", description: "Task Planning — track multi-step todo lists during execution." },
+  { name: "memory", description: "Memory — persist facts and preferences across sessions." },
+  { name: "session_search", description: "Session Search — search prior chat sessions for context." },
+  { name: "clarify", description: "Clarifying Questions — ask the user follow-up questions interactively.", headlessSafe: false },
+  { name: "delegation", description: "Task Delegation — spawn sub-agents to handle parts of a task." },
+  { name: "cronjob", description: "Cron Jobs — schedule recurring background tasks." },
+  { name: "messaging", description: "Cross-Platform Messaging — send messages on Telegram/Discord/Slack/etc." },
+  { name: "rl", description: "RL Training — record trajectories for reinforcement-learning fine-tunes." },
+  { name: "homeassistant", description: "Home Assistant — control smart-home devices via HA." },
+  { name: "spotify", description: "Spotify — control playback and query the Spotify catalog." },
+  { name: "yuanbao", description: "Yuanbao — Tencent Yuanbao integration." },
+];
+
+/**
+ * Safe-default subset used when triage fails or produces no usable result.
+ *
+ * Chosen to cover the vast majority of FideliOS agent tasks (read code, run
+ * commands, fetch the web, persist memory) while excluding stdin-blocking and
+ * heavyweight toolsets (`clarify`, `browser`, `image_gen`, etc.).
+ */
+export const SAFE_DEFAULT_TOOLSETS = [
+  "terminal",
+  "file",
+  "code_execution",
+  "web",
+  "skills",
+  "todo",
+  "memory",
+  "session_search",
+];
+
+/**
+ * Map of toolset name → registry entry, for O(1) filter/validation.
+ * @type {Map<string, ToolsetEntry>}
+ */
+export const TOOLSET_BY_NAME = new Map(
+  HERMES_TOOLSET_REGISTRY.map((entry) => [entry.name, entry])
+);
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isKnownToolset(name) {
+  return TOOLSET_BY_NAME.has(name);
+}
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isHeadlessSafeToolset(name) {
+  const entry = TOOLSET_BY_NAME.get(name);
+  if (!entry) return false;
+  return entry.headlessSafe !== false;
+}

package/src/server/toolset-registry.test.js

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import {
+  HERMES_TOOLSET_REGISTRY,
+  SAFE_DEFAULT_TOOLSETS,
+  TOOLSET_BY_NAME,
+  isHeadlessSafeToolset,
+  isKnownToolset,
+} from "./toolset-registry.js";
+
+describe("toolset-registry", () => {
+  it("exposes a non-empty canonical list with unique names", () => {
+    expect(HERMES_TOOLSET_REGISTRY.length).toBeGreaterThan(0);
+    const names = HERMES_TOOLSET_REGISTRY.map((t) => t.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+
+  it("populates name → entry map for every entry", () => {
+    expect(TOOLSET_BY_NAME.size).toBe(HERMES_TOOLSET_REGISTRY.length);
+    for (const entry of HERMES_TOOLSET_REGISTRY) {
+      expect(TOOLSET_BY_NAME.get(entry.name)).toBe(entry);
+    }
+  });
+
+  it("requires every entry to have a non-empty description", () => {
+    for (const entry of HERMES_TOOLSET_REGISTRY) {
+      expect(typeof entry.description).toBe("string");
+      expect(entry.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("marks `clarify` as not headless-safe (FID-47)", () => {
+    expect(isHeadlessSafeToolset("clarify")).toBe(false);
+  });
+
+  it("treats unknown toolsets as not headless-safe", () => {
+    expect(isHeadlessSafeToolset("does_not_exist")).toBe(false);
+  });
+
+  it("treats omitted-flag toolsets as headless-safe by default", () => {
+    expect(isHeadlessSafeToolset("file")).toBe(true);
+    expect(isHeadlessSafeToolset("terminal")).toBe(true);
+  });
+
+  it("isKnownToolset identifies registry vs unknown names", () => {
+    expect(isKnownToolset("file")).toBe(true);
+    expect(isKnownToolset("not_a_real_toolset")).toBe(false);
+  });
+
+  it("safe-default subset is fully contained in the registry", () => {
+    for (const name of SAFE_DEFAULT_TOOLSETS) {
+      expect(TOOLSET_BY_NAME.has(name)).toBe(true);
+    }
+  });
+
+  it("safe-default subset excludes the known stdin-blocker `clarify`", () => {
+    expect(SAFE_DEFAULT_TOOLSETS).not.toContain("clarify");
+  });
+});

package/src/server/triage.js

@@ -0,0 +1,234 @@
+/**
+ * Hermes toolset triage engine (FID-48).
+ *
+ * Before each Hermes spawn, ask the configured local LLM to pick which subset
+ * of available toolsets is relevant for the user's prompt. The selected names
+ * are then passed to Hermes via `-t a,b,c`, replacing the static whitelist
+ * approach rejected in FID-47.
+ *
+ * Design decisions:
+ *   - The router LLM defaults to `adapterConfig.model` (the same Ollama model
+ *     already configured for the agent). Optional `triageModel` override.
+ *   - We call Ollama with `format: 'json'` for robust parsing.
+ *   - Hard 30s timeout. On any failure (timeout, parse error, empty result,
+ *     bad JSON shape) we fall back to SAFE_DEFAULT_TOOLSETS and surface a
+ *     warning + `triageError` field.
+ *   - LLM-returned names are intersected with the registry, so unknown / made-up
+ *     toolsets are silently dropped.
+ */
+import { Ollama } from "ollama";
+import {
+  HERMES_TOOLSET_REGISTRY,
+  SAFE_DEFAULT_TOOLSETS,
+  TOOLSET_BY_NAME,
+} from "./toolset-registry.js";
+
+/**
+ * @typedef {import("./toolset-registry.js").ToolsetEntry} ToolsetEntry
+ */
+
+/**
+ * @typedef {Object} TriageResult
+ * @property {string[]} toolsets         Filtered, deduped list of canonical toolset names.
+ * @property {boolean}  usedFallback     True when SAFE_DEFAULT_TOOLSETS was returned.
+ * @property {string=}  error            Human-readable error string when fallback was used.
+ * @property {number}   durationMs       Wall-clock time spent on the triage call.
+ * @property {string=}  rawContent       Raw LLM response (for debug / log truncation).
+ */
+
+const DEFAULT_TRIAGE_TIMEOUT_MS = 30_000;
+
+/**
+ * Build the system prompt presented to the triage LLM.
+ *
+ * Kept short and structured to maximize JSON-mode reliability with small
+ * local models. We err on the side of "include the toolset if unsure" so
+ * the downstream agent is never starved of capability.
+ *
+ * @param {ToolsetEntry[]} registry
+ * @returns {string}
+ */
+export function buildTriageSystemPrompt(registry) {
+  const lines = registry.map((t) => `- ${t.name}: ${t.description}`);
+  return [
+    "You are a tool-selection router for an autonomous AI agent.",
+    "Given the user's task, choose which toolsets the agent will actually need.",
+    "",
+    "Rules:",
+    '- Reply with valid JSON only, shape: {"toolsets": ["name1", "name2", ...]}.',
+    "- Use only canonical names from the list below — do not invent new ones.",
+    "- Prefer fewer toolsets, but include any that the agent may plausibly need.",
+    "- If the task is ambiguous or general, include the core defaults: terminal, file, code_execution, web, skills, todo, memory.",
+    "",
+    "Available toolsets:",
+    ...lines,
+  ].join("\n");
+}
+
+/**
+ * Parse a raw LLM JSON response into a clean array of toolset names.
+ * Tolerates whitespace, trailing prose, and bare JSON without code fences.
+ *
+ * @param {string} raw
+ * @returns {string[] | null} null when content is unparseable.
+ */
+export function parseTriageJson(raw) {
+  if (typeof raw !== "string" || !raw.trim()) return null;
+  // Try direct parse first (Ollama format:'json' should already give us a JSON doc).
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // Fall back to extracting the first {...} block.
+    const match = raw.match(/\{[\s\S]*\}/);
+    if (!match) return null;
+    try {
+      parsed = JSON.parse(match[0]);
+    } catch {
+      return null;
+    }
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const list = parsed.toolsets ?? parsed.tools ?? parsed.selected;
+  if (!Array.isArray(list)) return null;
+  return list.filter((v) => typeof v === "string" && v.length > 0);
+}
+
+/**
+ * Dedupe + filter a list of LLM-returned names against the canonical registry
+ * (or a caller-supplied registry, for tests).
+ *
+ * @param {string[]} names
+ * @param {ToolsetEntry[]} [registry] Defaults to the canonical Hermes registry.
+ * @returns {string[]}
+ */
+export function filterToolsetNames(names, registry) {
+  const lookup = registry
+    ? new Set(registry.map((t) => t.name))
+    : TOOLSET_BY_NAME;
+  const seen = new Set();
+  const out = [];
+  for (const name of names) {
+    if (typeof name !== "string") continue;
+    const trimmed = name.trim();
+    if (!trimmed) continue;
+    const known = lookup instanceof Set ? lookup.has(trimmed) : lookup.has(trimmed);
+    if (!known) continue;
+    if (seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
+/**
+ * Wrap a promise with a timeout. Resolves with the original promise's value
+ * or rejects with a timeout Error.
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {string} label
+ * @returns {Promise<T>}
+ */
+function withTimeout(promise, ms, label) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+  });
+  return Promise.race([
+    promise.finally(() => clearTimeout(timer)),
+    timeout,
+  ]);
+}
+
+/**
+ * Run the triage LLM call. Always resolves — never rejects.
+ * On any error, returns SAFE_DEFAULT_TOOLSETS with `usedFallback: true` and
+ * an `error` field describing what went wrong.
+ *
+ * @param {Object} opts
+ * @param {string} opts.prompt                User-facing prompt that the agent will execute.
+ * @param {string} opts.model                 Ollama model name (e.g. "qwen3:4b").
+ * @param {ToolsetEntry[]} [opts.registry]    Override registry (defaults to the canonical one).
+ * @param {string[]} [opts.fallback]          Override fallback list.
+ * @param {number} [opts.timeoutMs]           Hard timeout in ms.
+ * @param {string} [opts.host]                Optional Ollama host override.
+ * @param {{ chat: Function } | null} [opts.client]  Optional pre-built Ollama client (tests).
+ * @param {{ Ollama: any } | null} [opts.ollamaCtor] Optional Ollama ctor (tests).
+ * @returns {Promise<TriageResult>}
+ */
+export async function triageToolsets(opts) {
+  const start = Date.now();
+  const registry = opts.registry ?? HERMES_TOOLSET_REGISTRY;
+  const fallback = opts.fallback ?? SAFE_DEFAULT_TOOLSETS;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TRIAGE_TIMEOUT_MS;
+
+  const fallbackResult = (error, rawContent) => ({
+    toolsets: filterToolsetNames(fallback, registry),
+    usedFallback: true,
+    error,
+    durationMs: Date.now() - start,
+    rawContent,
+  });
+
+  if (!opts.model || typeof opts.model !== "string") {
+    return fallbackResult("triage skipped: no model configured");
+  }
+  if (!opts.prompt || typeof opts.prompt !== "string") {
+    return fallbackResult("triage skipped: empty prompt");
+  }
+
+  let client = opts.client;
+  if (!client) {
+    try {
+      const Ctor = opts.ollamaCtor?.Ollama ?? Ollama;
+      client = new Ctor(opts.host ? { host: opts.host } : {});
+    } catch (err) {
+      return fallbackResult(`failed to construct Ollama client: ${err?.message ?? err}`);
+    }
+  }
+
+  const system = buildTriageSystemPrompt(registry);
+  const messages = [
+    { role: "system", content: system },
+    { role: "user", content: `Task:\n${opts.prompt.slice(0, 4000)}` },
+  ];
+
+  let response;
+  try {
+    response = await withTimeout(
+      client.chat({
+        model: opts.model,
+        messages,
+        format: "json",
+        stream: false,
+        options: { temperature: 0 },
+      }),
+      timeoutMs,
+      "hermes-triage"
+    );
+  } catch (err) {
+    return fallbackResult(`triage call failed: ${err?.message ?? err}`);
+  }
+
+  const raw = response?.message?.content ?? "";
+  const parsed = parseTriageJson(raw);
+  if (!parsed) {
+    return fallbackResult("triage response not valid JSON", raw);
+  }
+
+  const filtered = filterToolsetNames(parsed, registry);
+  if (filtered.length === 0) {
+    return fallbackResult("triage returned no known toolsets", raw);
+  }
+
+  return {
+    toolsets: filtered,
+    usedFallback: false,
+    durationMs: Date.now() - start,
+    rawContent: raw,
+  };
+}