@voybio/ace-swarm 2.4.1 → 2.4.2

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_LLM_PROVIDERS, DEFAULTS_ROOT, PACKAGE_ROOT, WORKSPACE_ROOT, fileExists, getAllMcpServerConfigSnippets, getMcpClientInstallHint, getMcpServerConfigSnippet, wsPath, } from "./helpers.js";
 import { refreshAstgrepIndex } from "./astgrep-index.js";
 import { scanWorkspaceDelta } from "./index-store.js";
-import { startStdioServer } from "./server.js";
+import { startHermesShadowStdioServer, startStdioServer } from "./server.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe, waitForPendingStatusEventMirrors } from "./status-events.js";
 import { bootstrapStoreWorkspace } from "./store/bootstrap-store.js";
@@ -12,16 +12,20 @@ import { DiscoveryRepository } from "./store/repositories/discovery-repository.j
 import { withStoreWriteCoordinator } from "./store/write-coordinator.js";
 import { getWorkspaceStorePath, readStoreBlobSync, readStoreJsonSync, } from "./store/store-snapshot.js";
 import { ensureCanonicalWorkspaceStore } from "./store/workspace-store-paths.js";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { spawn } from "node:child_process";
 import { runTui } from "./tui/index.js";
 import { buildOpenAiCompatibleBaseUrl, buildProviderDoctorCommands, defaultModelForProvider, discoverProviderContext, isLocalLlmProvider, normalizeLocalBaseUrl, normalizeLlamaCppHfModelName, normalizeProvider, scanLocalModelRuntimes, } from "./tui/provider-discovery.js";
 import { diagnoseChatRuntimeConfig, OpenAICompatibleClient, } from "./tui/openai-compatible.js";
 import { runShellCommand } from "./runtime-command.js";
+import { resolveHermesLaunchProfile } from "./hermes/launch-profile.js";
 function printHelp() {
     console.log(`ACE Swarm CLI
 
 Usage:
   ace mcp                      Start MCP server over stdio
+  ace mcp-shadow --tools <csv> Start filtered Hermes-local MCP shadow server over stdio
   ace serve                    Alias for mcp
   ace tui [options]            Launch interactive TUI dashboard
   ace init [options]           Bootstrap the ACE store into current workspace
@@ -39,6 +43,16 @@ Options for tui:
   --model <name>               Model name override (defaults from profile/settings discovery)
   --base-url <url>             Local runtime base URL override
   --ollama-url <url>           Legacy alias for --base-url
+  --engine <name>              direct|hermes_local execution engine
+  --hermes                     Alias for --engine hermes_local
+  --hermes-root <path>         User-supplied Hermes checkout/import root
+  --hermes-python <path>       User-supplied Python executable with Hermes deps
+  --hermes-uv-project <path>   Optional uv project root for operator-managed Hermes
+  --hermes-command-json <json> Advanced command array override for Hermes Python
+  
+  Hermes is optional and user-supplied. \`ace tui\` and \`ace doctor\` only resolve
+  Hermes when you pass \`--hermes\` / \`--engine hermes_local\` or set the matching
+  Hermes environment variables.
 
 Options for init:
   --project <name>             Project name stored in agent-state/ace-state.ace metadata
@@ -63,6 +77,11 @@ Options for doctor:
   --base-url <url>             Runtime base URL override
   --ollama-url <url>           Legacy alias for --base-url
   --scan                       Probe common local Ollama + llama.cpp endpoints when URL is unset
+  --hermes                     Also run optional Hermes-local readiness checks
+  --hermes-root <path>         User-supplied Hermes checkout/import root (or ACE_HERMES_ROOT)
+  --hermes-python <path>       User-supplied Python executable (or HERMES_PYTHON)
+  --hermes-uv-project <path>   Optional uv project root for operator-managed Hermes
+  --hermes-command-json <json> Advanced command array override for Hermes Python
   --repair-ollama              Opt-in: run ollama pull <model> when doctor finds a missing Ollama model
 
 Options for cache:
@@ -73,6 +92,11 @@ Options for mcp-config:
   --client <name>              codex|vscode|copilot|claude|cursor|antigravity
   --all                        Print all client snippets for optional global install
 
+Hermes environment:
+  ACE_HERMES_ROOT              User-supplied Hermes checkout/import root
+  HERMES_PYTHON                User-supplied Python with Hermes dependencies
+  ACE_HERMES_UV_PROJECT        Optional operator-managed uv project root
+
 preconfig writes .mcp-config/ at the workspace root with ready-to-use config files for every
 supported MCP client plus a root .mcp.json for GitHub Copilot CLI. Run once after ace init.
 Each file includes the install hint for its client.
@@ -87,6 +111,180 @@ function readFlagValue(args, flag) {
         return undefined;
     return args[index + 1];
 }
+async function runCommandArray(command, args, options) {
+    const [bin, ...prefixArgs] = command;
+    if (!bin)
+        return { ok: false, stdout: "", stderr: "", detail: "empty command array" };
+    return await new Promise((resolveCommand) => {
+        const child = spawn(bin, [...prefixArgs, ...args], {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+        }, options.timeoutMs ?? 5000);
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            resolveCommand({ ok: false, stdout, stderr, detail: error.message });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timeout);
+            resolveCommand({
+                ok: code === 0,
+                stdout,
+                stderr,
+                detail: code === 0 ? "exit 0" : `exit ${code}; ${stderr.slice(0, 300)}`,
+            });
+        });
+    });
+}
+function mcpFrame(payload) {
+    const body = JSON.stringify(payload);
+    return `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`;
+}
+async function probeHermesShadowMcp(cliPath, toolAllowlist) {
+    return await new Promise((resolveProbe, rejectProbe) => {
+        const child = spawn(process.execPath, [cliPath, "mcp-shadow", "--tools", toolAllowlist.join(",")], {
+            cwd: PACKAGE_ROOT,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+            rejectProbe(new Error(`shadow MCP probe timed out${stderr ? `: ${stderr.slice(0, 200)}` : ""}`));
+        }, 2500);
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+            if (stdout.includes('"tools"') && stdout.includes(toolAllowlist[0] ?? "")) {
+                clearTimeout(timeout);
+                child.kill("SIGTERM");
+                resolveProbe(`shadow MCP initialize/tools-list probe succeeded; tools=${toolAllowlist.join(",")}`);
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (error) => {
+            clearTimeout(timeout);
+            rejectProbe(error);
+        });
+        child.on("close", () => {
+            clearTimeout(timeout);
+            if (stdout.includes('"tools"') && stdout.includes(toolAllowlist[0] ?? "")) {
+                resolveProbe(`shadow MCP initialize/tools-list probe succeeded; tools=${toolAllowlist.join(",")}`);
+            }
+            else {
+                rejectProbe(new Error(`shadow MCP probe did not return tools/list${stderr ? `: ${stderr.slice(0, 200)}` : ""}`));
+            }
+        });
+        child.stdin.write(mcpFrame({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "ace-doctor", version: "0.0.0" },
+            },
+        }));
+        child.stdin.write(mcpFrame({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }));
+        child.stdin.write(mcpFrame({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }));
+    });
+}
+async function appendHermesLocalReadinessChecks(checks, profile) {
+    const hermesRoot = profile.hermes_root;
+    const workerPath = profile.worker_path;
+    const cliPath = resolve(PACKAGE_ROOT, "dist", "cli.js");
+    const toolAllowlist = ["get_all_agents_summary"];
+    checks.push({
+        name: "Hermes launch profile",
+        ok: true,
+        detail: `source=${profile.source}; mode=${profile.mode}; command=${JSON.stringify(profile.command)}; hermes_root=${profile.hermes_root ?? "not configured"}`,
+    });
+    checks.push({
+        name: "Hermes worker packaged",
+        ok: existsSync(workerPath),
+        detail: existsSync(workerPath)
+            ? workerPath
+            : `Missing ${workerPath}; run npm run build.`,
+    });
+    checks.push({
+        name: "Hermes checkout import root",
+        ok: Boolean(hermesRoot &&
+            existsSync(resolve(hermesRoot, "run_agent.py")) &&
+            existsSync(resolve(hermesRoot, "tools", "mcp_tool.py"))),
+        detail: hermesRoot && existsSync(resolve(hermesRoot, "run_agent.py"))
+            ? hermesRoot
+            : "ACE does not install Hermes. Set ACE_HERMES_ROOT or pass --hermes-root to a Hermes checkout.",
+    });
+    const pythonResolves = await runCommandArray(profile.command, ["-c", "import sys; print(sys.executable)"], {
+        cwd: PACKAGE_ROOT,
+        timeoutMs: 5000,
+    });
+    checks.push({
+        name: "Hermes Python command",
+        ok: pythonResolves.ok,
+        detail: pythonResolves.ok ? `${JSON.stringify(profile.command)} -> ${pythonResolves.stdout.trim()}` : pythonResolves.detail,
+    });
+    const importEnv = {
+        ...process.env,
+        PYTHONPATH: [hermesRoot, process.env.PYTHONPATH].filter(Boolean).join(":"),
+    };
+    const importResult = hermesRoot
+        ? await runCommandArray(profile.command, ["-c", "from run_agent import AIAgent; print(AIAgent.__name__)"], {
+            cwd: hermesRoot,
+            env: importEnv,
+            timeoutMs: 5000,
+        })
+        : { ok: false, detail: "Hermes root not configured", stdout: "", stderr: "" };
+    checks.push({
+        name: "Hermes Python imports",
+        ok: importResult.ok,
+        detail: importResult.ok ? "run_agent.AIAgent import ok" : importResult.detail,
+    });
+    checks.push({
+        name: "ACE shadow MCP command",
+        ok: existsSync(cliPath),
+        detail: existsSync(cliPath)
+            ? JSON.stringify([process.execPath, cliPath, "mcp-shadow", "--tools", toolAllowlist.join(",")])
+            : `Missing ${cliPath}; run npm run build.`,
+    });
+    if (existsSync(cliPath)) {
+        try {
+            checks.push({
+                name: "ACE shadow MCP handshake",
+                ok: true,
+                detail: await probeHermesShadowMcp(cliPath, toolAllowlist),
+            });
+        }
+        catch (error) {
+            checks.push({
+                name: "ACE shadow MCP handshake",
+                ok: false,
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    else {
+        checks.push({
+            name: "ACE shadow MCP handshake",
+            ok: false,
+            detail: `Cannot probe shadow MCP until ${cliPath} exists; run npm run build.`,
+        });
+    }
+}
 function readLlmProfile() {
     const storeProfile = readStoreJsonSync(WORKSPACE_ROOT, "state/runtime/llm_profile") ??
         readStoreJsonSync(WORKSPACE_ROOT, "state/runtime/llm-profile");
@@ -654,6 +852,25 @@ async function runDoctor(args) {
             }
         }
     }
+    if (isLocalLlmProvider(provider) && args.includes("--hermes")) {
+        try {
+            const hermesProfile = resolveHermesLaunchProfile({
+                workspaceRoot: WORKSPACE_ROOT,
+                cliHermesRoot: readFlagValue(args, "--hermes-root"),
+                cliHermesPython: readFlagValue(args, "--hermes-python"),
+                cliHermesUvProject: readFlagValue(args, "--hermes-uv-project"),
+                cliHermesCommandJson: readFlagValue(args, "--hermes-command-json"),
+            });
+            await appendHermesLocalReadinessChecks(checks, hermesProfile);
+        }
+        catch (error) {
+            checks.push({
+                name: "Hermes launch profile",
+                ok: false,
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     const failed = checks.filter((check) => !check.ok);
     console.log("ACE Doctor Report");
     console.log(`Workspace: ${WORKSPACE_ROOT}`);
@@ -740,11 +957,32 @@ async function main() {
         await startStdioServer();
         return;
     }
+    if (command === "mcp-shadow") {
+        const shadowArgs = args.slice(1);
+        const tools = (readFlagValue(shadowArgs, "--tools") ?? "")
+            .split(",")
+            .map((tool) => tool.trim())
+            .filter(Boolean);
+        await startHermesShadowStdioServer(tools);
+        return;
+    }
     if (command === "tui") {
         const tuiArgs = args.slice(1);
         const cliProvider = readFlagValue(tuiArgs, "--provider")?.trim() ||
             readFlagValue(tuiArgs, "--llm")?.trim();
         const cliModel = readFlagValue(tuiArgs, "--model")?.trim();
+        const cliEngine = readFlagValue(tuiArgs, "--engine")?.trim() ||
+            (tuiArgs.includes("--hermes") ? "hermes_local" : undefined);
+        const normalizedCliEngine = cliEngine?.toLowerCase().replace(/-/g, "_");
+        const hermesLaunchProfile = normalizedCliEngine === "hermes_local"
+            ? resolveHermesLaunchProfile({
+                workspaceRoot: WORKSPACE_ROOT,
+                cliHermesRoot: readFlagValue(tuiArgs, "--hermes-root"),
+                cliHermesPython: readFlagValue(tuiArgs, "--hermes-python"),
+                cliHermesUvProject: readFlagValue(tuiArgs, "--hermes-uv-project"),
+                cliHermesCommandJson: readFlagValue(tuiArgs, "--hermes-command-json"),
+            })
+            : undefined;
         const cliBaseUrl = readBaseUrlFlag(tuiArgs);
         const discovered = discoverProviderContext({
             workspaceRoot: WORKSPACE_ROOT,
@@ -774,8 +1012,50 @@ async function main() {
                 },
             }
             : discovered;
+        // Merge any persisted discovery records from the workspace store so recent `ace doctor`
+        // results are reflected immediately in the TUI startup options.
+        try {
+            const store = await openStore(getWorkspaceStorePath(WORKSPACE_ROOT), { readOnly: true });
+            try {
+                const discoveryRepo = new DiscoveryRepository(store);
+                const stored = await discoveryRepo.listAll();
+                const mergedProviders = new Set(resolvedTui.providers ?? []);
+                const mergedModelsByProvider = { ...(resolvedTui.modelsByProvider ?? {}) };
+                const mergedProviderBaseUrls = { ...(resolvedTui.providerBaseUrls ?? {}) };
+                for (const p of stored) {
+                    if (!p || !p.provider)
+                        continue;
+                    const prov = String(p.provider).trim();
+                    if (!prov)
+                        continue;
+                    mergedProviders.add(prov);
+                    if (Array.isArray(p.models) && p.models.length > 0) {
+                        const existing = new Set(mergedModelsByProvider[prov] ?? []);
+                        for (const m of p.models)
+                            if (typeof m === "string" && m.trim())
+                                existing.add(m.trim());
+                        mergedModelsByProvider[prov] = [...existing].sort((a, b) => a.localeCompare(b));
+                    }
+                    if (p.endpoint && typeof p.endpoint === "string") {
+                        mergedProviderBaseUrls[prov] = p.endpoint;
+                    }
+                }
+                resolvedTui.providers = [...mergedProviders].sort((a, b) => a.localeCompare(b));
+                resolvedTui.modelsByProvider = { ...(resolvedTui.modelsByProvider ?? {}), ...mergedModelsByProvider };
+                resolvedTui.providerBaseUrls = { ...(resolvedTui.providerBaseUrls ?? {}), ...mergedProviderBaseUrls };
+            }
+            finally {
+                await store.close();
+            }
+        }
+        catch (err) {
+            // Non-fatal — continue with discovered defaults if store read fails.
+            console.warn(`Could not merge discovery records into TUI startup: ${err instanceof Error ? err.message : String(err)}`);
+        }
         await runTui({
             provider: resolvedTui.provider,
+            engine: cliEngine,
+            hermesLaunchProfile,
             model: resolvedTui.model,
             providers: resolvedTui.providers,
             modelsByProvider: resolvedTui.modelsByProvider,

package/dist/helpers/constants.d.ts

@@ -26,6 +26,8 @@ export declare const ALL_MCP_CLIENTS: readonly ["codex", "vscode", "copilot", "c
 export type McpClient = (typeof ALL_MCP_CLIENTS)[number];
 export declare const ALL_LLM_PROVIDERS: readonly ["ollama", "llama.cpp", "codex", "claude", "gemini", "copilot"];
 export type LlmProvider = (typeof ALL_LLM_PROVIDERS)[number];
+export declare const ALL_EXECUTION_ENGINES: readonly ["direct", "hermes_local"];
+export type ExecutionEngine = (typeof ALL_EXECUTION_ENGINES)[number];
 export declare const ALL_AGENTS: readonly ["orchestrator", "vos", "ui", "coders", "astgrep", "skeptic", "ops", "research", "spec", "builder", "qa", "docs", "memory", "security", "observability", "eval", "release", "planner"];
 export type AgentRole = (typeof ALL_AGENTS)[number];
 export declare const SWARM_AGENTS: readonly ["orchestrator", "vos", "ui", "coders"];

package/dist/helpers/constants.js

@@ -53,6 +53,7 @@ export const ALL_LLM_PROVIDERS = [
     "gemini",
     "copilot",
 ];
+export const ALL_EXECUTION_ENGINES = ["direct", "hermes_local"];
 export const ALL_AGENTS = [
     "orchestrator",
     "vos",

package/dist/hermes/bridge-protocol.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export declare const HERMES_BRIDGE_PROTOCOL_VERSION = "1.0.0";
+declare const bridgeEventSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        error: "error";
+        status: "status";
+        tool_start: "tool_start";
+        session_open: "session_open";
+        turn_run: "turn_run";
+        interrupt: "interrupt";
+        session_close: "session_close";
+        delta: "delta";
+        reasoning: "reasoning";
+        assistant_interim: "assistant_interim";
+        tool_progress: "tool_progress";
+        tool_complete: "tool_complete";
+        final: "final";
+    }>;
+    session_id: z.ZodOptional<z.ZodString>;
+    turn_id: z.ZodOptional<z.ZodString>;
+    sequence: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+export type HermesBridgeEvent = z.infer<typeof bridgeEventSchema>;
+export interface DecodedHermesBridgeFrame {
+    ok: true;
+    event: HermesBridgeEvent;
+}
+export interface RejectedHermesBridgeFrame {
+    ok: false;
+    reason: string;
+    raw: string;
+}
+export type HermesBridgeFrame = DecodedHermesBridgeFrame | RejectedHermesBridgeFrame;
+export declare class HermesBridgeFrameDecoder {
+    private decoder;
+    private buffer;
+    push(chunk: Uint8Array, end?: boolean): HermesBridgeFrame[];
+}
+export declare function decodeHermesBridgeLine(line: string): HermesBridgeFrame;
+export {};
+//# sourceMappingURL=bridge-protocol.d.ts.map

package/dist/hermes/bridge-protocol.js

@@ -0,0 +1,70 @@
+import { TextDecoder } from "node:util";
+import { z } from "zod";
+export const HERMES_BRIDGE_PROTOCOL_VERSION = "1.0.0";
+const bridgeEventBaseSchema = z.object({
+    type: z.enum([
+        "session_open",
+        "turn_run",
+        "interrupt",
+        "session_close",
+        "status",
+        "delta",
+        "reasoning",
+        "assistant_interim",
+        "tool_start",
+        "tool_progress",
+        "tool_complete",
+        "final",
+        "error",
+    ]),
+    session_id: z.string().optional(),
+    turn_id: z.string().optional(),
+    sequence: z.number().int().nonnegative().optional(),
+});
+const bridgeEventSchema = bridgeEventBaseSchema.passthrough();
+function sanitizeBridgeLine(line) {
+    if (line.includes("\u0000"))
+        return undefined;
+    const stripped = line.replace(/[\u0001-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
+    const trimmed = stripped.trim();
+    return trimmed ? trimmed : undefined;
+}
+export class HermesBridgeFrameDecoder {
+    decoder = new TextDecoder("utf-8", { fatal: false });
+    buffer = "";
+    push(chunk, end = false) {
+        this.buffer += this.decoder.decode(chunk, { stream: !end });
+        const lines = this.buffer.split(/\r?\n/);
+        this.buffer = end ? "" : (lines.pop() ?? "");
+        const frames = [];
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            frames.push(decodeHermesBridgeLine(line));
+        }
+        if (end && this.buffer.trim()) {
+            frames.push(decodeHermesBridgeLine(this.buffer));
+            this.buffer = "";
+        }
+        return frames;
+    }
+}
+export function decodeHermesBridgeLine(line) {
+    const sanitized = sanitizeBridgeLine(line);
+    if (!sanitized) {
+        return { ok: false, reason: "bridge_frame_control_bytes", raw: line };
+    }
+    try {
+        const parsed = JSON.parse(sanitized);
+        const event = bridgeEventSchema.parse(parsed);
+        return { ok: true, event };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : "bridge_frame_invalid_json",
+            raw: sanitized,
+        };
+    }
+}
+//# sourceMappingURL=bridge-protocol.js.map

package/dist/hermes/launch-profile.d.ts

@@ -0,0 +1,19 @@
+export interface HermesLaunchProfile {
+    enabled: boolean;
+    mode: "ephemeral_subprocess" | "external_command";
+    hermes_root?: string;
+    command: readonly string[];
+    worker_path: string;
+    source: "cli" | "env" | "store" | "default";
+    diagnostics: string[];
+}
+export interface ResolveHermesLaunchProfileInput {
+    workspaceRoot: string;
+    cliHermesRoot?: string;
+    cliHermesPython?: string;
+    cliHermesUvProject?: string;
+    cliHermesCommandJson?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function resolveHermesLaunchProfile(input: ResolveHermesLaunchProfileInput): HermesLaunchProfile;
+//# sourceMappingURL=launch-profile.d.ts.map

package/dist/hermes/launch-profile.js

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readStoreJsonSync } from "../store/store-snapshot.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DIST_ROOT = resolve(__dirname, "..");
+const PACKAGE_ROOT = resolve(DIST_ROOT, "..");
+function parseCommandJson(raw, source) {
+    if (!raw?.trim())
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${source} must be a JSON array of command tokens.`);
+    }
+    if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some((item) => typeof item !== "string" || !item.trim())) {
+        throw new Error(`${source} must be a non-empty JSON array of non-empty strings.`);
+    }
+    return parsed.map((item) => item.trim());
+}
+function defaultHermesRoot() {
+    const candidate = resolve(PACKAGE_ROOT, "..", ".tmp", "hermes-agent");
+    return existsSync(candidate) ? candidate : undefined;
+}
+export function resolveHermesLaunchProfile(input) {
+    const env = input.env ?? process.env;
+    const diagnostics = [];
+    const workerPath = resolve(PACKAGE_ROOT, "scripts", "hermes_bridge_worker.py");
+    const stored = readStoreJsonSync(input.workspaceRoot, "state/runtime/hermes_launch_profile") ??
+        undefined;
+    const hermesRoot = input.cliHermesRoot ?? env.ACE_HERMES_ROOT ?? stored?.hermes_root ?? defaultHermesRoot();
+    const commandJson = input.cliHermesCommandJson ?? env.ACE_HERMES_COMMAND_JSON ?? stored?.hermes_command_json;
+    const uvProject = input.cliHermesUvProject ?? env.ACE_HERMES_UV_PROJECT ?? stored?.hermes_uv_project;
+    const python = input.cliHermesPython ?? env.HERMES_PYTHON ?? stored?.hermes_python;
+    let command;
+    let source = "default";
+    if (commandJson) {
+        command = parseCommandJson(commandJson, input.cliHermesCommandJson ? "--hermes-command-json" : "ACE_HERMES_COMMAND_JSON");
+        source = input.cliHermesCommandJson ? "cli" : "env";
+        if (!input.cliHermesCommandJson && !env.ACE_HERMES_COMMAND_JSON) {
+            source = "store";
+        }
+    }
+    else if (uvProject) {
+        command = ["uv", "run", "--project", uvProject, "python"];
+        source = input.cliHermesUvProject ? "cli" : "env";
+        if (!input.cliHermesUvProject && !env.ACE_HERMES_UV_PROJECT) {
+            source = "store";
+        }
+    }
+    else if (python) {
+        command = [python];
+        source = input.cliHermesPython ? "cli" : "env";
+        if (!input.cliHermesPython && !env.HERMES_PYTHON) {
+            source = "store";
+        }
+    }
+    else {
+        command = ["python3"];
+        diagnostics.push("HERMES_PYTHON not set; using python3 fallback.");
+    }
+    if (!hermesRoot) {
+        diagnostics.push("ACE_HERMES_ROOT not set and no default Hermes checkout was found.");
+    }
+    if (!existsSync(workerPath)) {
+        diagnostics.push(`Hermes bridge worker is missing at ${workerPath}.`);
+    }
+    return {
+        enabled: true,
+        mode: commandJson ? "external_command" : "ephemeral_subprocess",
+        hermes_root: hermesRoot,
+        command,
+        worker_path: workerPath,
+        source,
+        diagnostics,
+    };
+}
+//# sourceMappingURL=launch-profile.js.map

package/dist/hermes/session-manager.d.ts

@@ -0,0 +1,42 @@
+import type { BridgeResult } from "../model-bridge.js";
+import type { LocalModelRuntimeConfig } from "../local-model-runtime.js";
+import type { LocalModelExecutionPolicy } from "../local-model-policy.js";
+import { type HermesBridgeEvent } from "./bridge-protocol.js";
+import { type HermesLaunchProfile } from "./launch-profile.js";
+export interface HermesLocalTurnOptions {
+    task: string;
+    role: string;
+    runtime: LocalModelRuntimeConfig;
+    policy: LocalModelExecutionPolicy;
+    toolScope?: string[];
+    maxTurns: number;
+}
+export interface HermesLocalTurnResult {
+    result: BridgeResult;
+    metadata: {
+        bridge_protocol_version: string;
+        hermes_session_id: string;
+        shadow_mcp_session_id: string;
+        execution_engine: "hermes_local";
+        provider: string;
+        model: string;
+        events: HermesBridgeEvent[];
+    };
+}
+export interface HermesLocalExecutor {
+    runTurn(options: HermesLocalTurnOptions): Promise<HermesLocalTurnResult>;
+}
+export interface HermesSubprocessExecutorOptions {
+    hermesRoot?: string;
+    workerPath?: string;
+    pythonCommand?: string;
+    command?: readonly string[];
+    launchProfile?: HermesLaunchProfile;
+    keepTemp?: boolean;
+}
+export declare class HermesSubprocessExecutor implements HermesLocalExecutor {
+    private options;
+    constructor(options?: HermesSubprocessExecutorOptions);
+    runTurn(options: HermesLocalTurnOptions): Promise<HermesLocalTurnResult>;
+}
+//# sourceMappingURL=session-manager.d.ts.map