@minionry/minion 0.7.36

package/dist/server/engines/hermes/HermesEngine.js

@@ -0,0 +1,628 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { spawn as nodeSpawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { hlog } from '../../cli/headless/headless-logger.js';
+import { BROWSER_SYSTEM_PROMPT } from '../../cli/headless/mcp-config.js';
+import { killProcessGroup } from '../../cli/headless/runner.js';
+import { isDirectory } from '../../services/pathUtils.js';
+import { findAvailablePort } from '../../utils/port-manager.js';
+import { EngineEventStream } from '../engine-event-stream.js';
+import { HERMES_READ_ONLY_REFUSAL, READ_ONLY_UNSUPPORTED, sessionIsReadOnly } from '../read-only.js';
+import { AppRunUnsupportedError, EngineStartError, } from '../types.js';
+import { HERMES_CONNECT_MESSAGE, } from './hermes-auth.js';
+import { hermesAppRunBaseEnv } from './hermes-gateway-home.js';
+import { HermesEventMapper } from './hermes-invoker.js';
+import { hermesAvailability, resolveHermesCommand } from './hermes-provision.js';
+function asRecord(value) {
+    return typeof value === 'object' && value !== null
+        ? value
+        : undefined;
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+const HERMES_THINKING_MODEL_PATTERN = /(^|\/)(hermes-4|deephermes)/i;
+export function resolveHermesReasoningEffort(model, effortLevel) {
+    if (!model || !HERMES_THINKING_MODEL_PATTERN.test(model))
+        return undefined;
+    if (!effortLevel || effortLevel === 'auto' || effortLevel === 'default')
+        return undefined;
+    return effortLevel === 'ultracode' ? 'ultra' : effortLevel;
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms).unref?.();
+    });
+}
+const GATEWAY_BASE_PORT = 8642;
+const claimedGatewayPorts = new Set();
+async function claimGatewayPort() {
+    let from = GATEWAY_BASE_PORT;
+    for (;;) {
+        const port = await findAvailablePort(from);
+        if (!claimedGatewayPorts.has(port)) {
+            claimedGatewayPorts.add(port);
+            return port;
+        }
+        from = port + 1;
+    }
+}
+const STARTUP_OUTPUT_LINES = 5;
+const STARTUP_OUTPUT_LINE_CHARS = 300;
+export class HermesEngine extends EngineEventStream {
+    engineId = 'hermes';
+    resolveCommand;
+    spawn;
+    fetchImpl;
+    resolvePort;
+    generateApiKey;
+    generateConversationId;
+    healthTimeoutMs;
+    healthPollIntervalMs;
+    auth;
+    provisionGatewayHome;
+    checkAppRunAvailability;
+    gatewayHome = null;
+    nativeResume = true;
+    browserMcpActive = false;
+    providerEnv = {};
+    connection = null;
+    sessionOptions = null;
+    conversationId = 'pending';
+    previousResponseId;
+    apiKey = '';
+    baseUrl = '';
+    gateway = null;
+    gatewayStartError = null;
+    claimedPort = null;
+    startupOutput = [];
+    currentAbort = null;
+    currentRunSettled = null;
+    cancelling = false;
+    runBudgetExpired = false;
+    turnIdleEmitted = false;
+    turnStreamFailed = false;
+    sseBuffer = '';
+    healthy = false;
+    disposed = false;
+    mapper = new HermesEventMapper({ sessionId: 'pending' });
+    constructor(options = {}) {
+        super();
+        this.resolveCommand = options.resolveCommand ?? (() => resolveHermesCommand());
+        this.spawn = options.spawn ?? nodeSpawn;
+        this.fetchImpl =
+            options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+        this.resolvePort = options.resolvePort ?? (() => this.claimPort());
+        this.generateApiKey = options.generateApiKey ?? (() => randomUUID());
+        this.generateConversationId = options.generateConversationId ?? (() => randomUUID());
+        this.healthTimeoutMs = options.healthTimeoutMs ?? 30_000;
+        this.healthPollIntervalMs = options.healthPollIntervalMs ?? 250;
+        this.auth = options.auth;
+        this.provisionGatewayHome = options.provisionGatewayHome;
+        this.checkAppRunAvailability = options.checkAppRunAvailability ?? (() => hermesAvailability());
+    }
+    async startSession(options) {
+        if (this.sessionOptions) {
+            throw new Error('HermesEngine: startSession called more than once');
+        }
+        if (this.disposed) {
+            throw new Error('HermesEngine: cannot start a disposed engine');
+        }
+        this.assertAppRunConfinable(options);
+        this.assertReadOnlyEnforceable(options);
+        const appRun = options.appRun;
+        this.sessionOptions = options;
+        this.conversationId = options.resumeSessionId ?? this.generateConversationId();
+        this.previousResponseId = undefined;
+        this.apiKey = this.generateApiKey();
+        this.mapper = new HermesEventMapper({ sessionId: this.conversationId });
+        let command;
+        try {
+            command = await this.resolveCommand();
+        }
+        catch (err) {
+            throw new EngineStartError('HERMES_NOT_INSTALLED', err instanceof Error ? err.message : String(err));
+        }
+        await this.assertAppRunAvailable(options);
+        if (this.disposed)
+            return;
+        if (this.auth && !appRun) {
+            this.providerEnv = this.auth.providerEnv();
+            this.connection = await this.auth.connectionStatus(command);
+            if (this.disposed)
+                return;
+        }
+        this.provisionSessionHome(options);
+        this.nativeResume = !options.resumeSessionId || !this.gatewayHome || this.gatewayHome.persistent;
+        this.resolveBrowserMcpActive(options);
+        const port = await this.resolvePort();
+        this.baseUrl = `http://127.0.0.1:${port}`;
+        const cwd = appRun?.cwd ?? options.workingDir;
+        const child = this.spawnGateway(command, cwd, port, options);
+        this.gateway = child;
+        this.wireGateway(child);
+        await this.waitForHealthy(cwd);
+    }
+    spawnGateway(command, cwd, port, options) {
+        try {
+            return this.spawn(command, ['gateway', 'run'], {
+                cwd,
+                env: {
+                    ...this.inheritedSpawnEnv(options),
+                    ...this.providerEnv,
+                    ...(this.gatewayHome?.env ?? {}),
+                    API_SERVER_ENABLED: 'true',
+                    API_SERVER_KEY: this.apiKey,
+                    API_SERVER_PORT: String(port),
+                    API_SERVER_HOST: '127.0.0.1',
+                },
+                detached: true,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            throw this.gatewayStartFailure(err instanceof Error ? err : new Error(String(err)), cwd);
+        }
+    }
+    async sendPrompt(prompt, _attachments) {
+        if (!this.sessionOptions) {
+            throw new Error('HermesEngine: sendPrompt called before startSession');
+        }
+        if (this.disposed) {
+            throw new Error('HermesEngine: sendPrompt called after dispose');
+        }
+        if (this.currentAbort) {
+            throw new Error('HermesEngine: another prompt is already in flight');
+        }
+        if (this.connection && this.connection.path === 'none' && !this.gatewayHome) {
+            this.turnIdleEmitted = false;
+            this.emitTurnError('HERMES_NO_CREDENTIALS', HERMES_CONNECT_MESSAGE);
+            this.emitTurnIdle('error');
+            return;
+        }
+        this.cancelling = false;
+        this.turnIdleEmitted = false;
+        this.turnStreamFailed = false;
+        this.sseBuffer = '';
+        const controller = new AbortController();
+        this.currentAbort = controller;
+        const runBudget = this.startRunBudget(controller);
+        this.currentRunSettled = this.runTurn(prompt, controller.signal).finally(() => {
+            if (runBudget)
+                clearTimeout(runBudget);
+            this.currentAbort = null;
+        });
+    }
+    async cancel() {
+        if (!this.currentAbort)
+            return;
+        this.cancelling = true;
+        this.currentAbort.abort();
+        if (this.currentRunSettled) {
+            await this.currentRunSettled;
+        }
+    }
+    getUsage() {
+        return this.mapper.getUsage();
+    }
+    get hermesConversationId() {
+        return this.conversationId;
+    }
+    get hermesLastResponseId() {
+        return this.mapper.lastResponseId;
+    }
+    get hermesConnectionStatus() {
+        return this.connection;
+    }
+    get resumedNatively() {
+        return this.nativeResume;
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.currentAbort?.abort();
+        this.killGateway();
+        this.releasePort();
+        if (this.currentRunSettled) {
+            await this.currentRunSettled;
+        }
+        this.closeIterator();
+        this.gatewayHome?.cleanup();
+        this.gatewayHome = null;
+    }
+    sessionIdForEvent() {
+        return this.conversationId;
+    }
+    assertAppRunConfinable(options) {
+        if (options.appRun && (!options.model || !this.provisionGatewayHome)) {
+            throw new AppRunUnsupportedError('hermes', 'an app run needs a model with a managed gateway home');
+        }
+    }
+    assertReadOnlyEnforceable(options) {
+        if (options.appRun || !sessionIsReadOnly(options))
+            return;
+        throw new EngineStartError(READ_ONLY_UNSUPPORTED, HERMES_READ_ONLY_REFUSAL);
+    }
+    async assertAppRunAvailable(options) {
+        if (!options.appRun)
+            return;
+        const availability = await this.checkAppRunAvailability();
+        if (!availability.available) {
+            throw new AppRunUnsupportedError('hermes', availability.reason ?? 'this Hermes cannot confine an app run');
+        }
+    }
+    provisionSessionHome(options) {
+        if (!options.model || !this.provisionGatewayHome)
+            return;
+        const appRun = options.appRun;
+        if (appRun) {
+            mkdirSync(appRun.cwd, { recursive: true, mode: 0o700 });
+            this.gatewayHome = this.provisionGatewayHome(options.model, undefined, appRun);
+            if (this.gatewayHome === null) {
+                throw new AppRunUnsupportedError('hermes', 'the model has no key for its endpoint');
+            }
+            return;
+        }
+        this.gatewayHome = this.provisionGatewayHome(options.model, options.browserMcp);
+        if (this.gatewayHome === null) {
+            hlog(`[hermes] no gateway credential can pin model ${options.model}; using the user's Hermes home (model selection may not apply)`);
+        }
+    }
+    inheritedSpawnEnv(options) {
+        return options.appRun ? hermesAppRunBaseEnv() : { ...process.env, ...options.extraEnv };
+    }
+    resolveBrowserMcpActive(options) {
+        this.browserMcpActive = !!options.browserMcp && !options.appRun && this.gatewayHome !== null;
+        if (options.browserMcp && options.appRun) {
+            hlog('[hermes] browser MCP requested for an app run; app runs have no tools, so it is not attached');
+        }
+        else if (options.browserMcp && !this.browserMcpActive) {
+            hlog('[hermes] browser MCP requested but no managed gateway home was provisioned (needs a selected model + a universal-gateway credential); this session has NO browser_* tools');
+        }
+    }
+    buildInstructions() {
+        return [
+            this.browserMcpActive ? BROWSER_SYSTEM_PROMPT : '',
+            this.sessionOptions?.systemPrompt ?? '',
+        ]
+            .filter(Boolean)
+            .join('\n\n');
+    }
+    wireGateway(child) {
+        this.drainGatewayOutput(child.stdout, 'stdout');
+        this.drainGatewayOutput(child.stderr, 'stderr');
+        child.on('error', (err) => {
+            this.gatewayStartError = err;
+            if (this.gateway === child && this.sessionOptions && !this.disposed) {
+                this.gateway = null;
+            }
+            if (this.healthy && !this.disposed) {
+                this.emit({
+                    kind: 'engine.error',
+                    sessionId: this.sessionIdForEvent(),
+                    timestamp: Date.now(),
+                    code: 'HERMES_GATEWAY_ERROR',
+                    message: err.message,
+                    fatal: true,
+                });
+            }
+        });
+        child.on('exit', (code, signal) => {
+            if (this.gateway === child)
+                this.gateway = null;
+            if (this.disposed)
+                return;
+            this.gatewayStartError ??= new Error(`hermes gateway exited (${signal ? `signal ${signal}` : `code ${code}`})`);
+            if (this.healthy) {
+                this.emit({
+                    kind: 'engine.error',
+                    sessionId: this.sessionIdForEvent(),
+                    timestamp: Date.now(),
+                    code: 'HERMES_GATEWAY_EXIT',
+                    message: this.gatewayStartError.message,
+                    fatal: true,
+                });
+            }
+        });
+    }
+    drainGatewayOutput(stream, label) {
+        if (!stream)
+            return;
+        stream.on('data', (chunk) => {
+            if (this.disposed)
+                return;
+            if (this.sessionOptions?.appRun && this.healthy)
+                return;
+            const text = chunk.toString('utf8').trim();
+            if (!text)
+                return;
+            hlog(`[hermes gateway ${label}] ${text.slice(0, 2000)}`);
+            if (!this.healthy)
+                this.keepStartupOutput(text);
+        });
+        stream.on('error', () => { });
+    }
+    keepStartupOutput(text) {
+        for (const line of text.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed)
+                this.startupOutput.push(trimmed.slice(0, STARTUP_OUTPUT_LINE_CHARS));
+        }
+        this.startupOutput.splice(0, Math.max(0, this.startupOutput.length - STARTUP_OUTPUT_LINES));
+    }
+    gatewayStartFailure(err, cwd) {
+        const errno = err.code;
+        if ((errno === 'ENOENT' || errno === 'ENOTDIR') && !isDirectory(cwd)) {
+            return new EngineStartError('WORKING_DIRECTORY_NOT_FOUND', `Could not start Hermes: its working directory ${cwd} is not a directory — it may have been moved, renamed, or deleted.`);
+        }
+        return new Error(`HermesEngine: gateway failed to start — ${err.message}${this.startupOutputSuffix()}`);
+    }
+    async waitForHealthy(cwd) {
+        const deadline = Date.now() + this.healthTimeoutMs;
+        while (Date.now() < deadline) {
+            if (this.disposed) {
+                throw new Error('HermesEngine: engine disposed during startup');
+            }
+            if (this.gatewayStartError) {
+                const err = this.gatewayStartError;
+                this.killGateway();
+                throw this.gatewayStartFailure(err, cwd);
+            }
+            try {
+                const res = await this.fetchImpl(`${this.baseUrl}/health`, {
+                    method: 'GET',
+                    headers: { Authorization: `Bearer ${this.apiKey}` },
+                });
+                if (res.ok) {
+                    const body = asRecord(await res.json());
+                    if (asString(body?.status) === 'ok') {
+                        this.healthy = true;
+                        return;
+                    }
+                }
+            }
+            catch {
+            }
+            await delay(this.healthPollIntervalMs);
+        }
+        this.killGateway();
+        throw new Error(`HermesEngine: gateway did not become healthy within ${this.healthTimeoutMs}ms${this.startupOutputSuffix()}`);
+    }
+    async runTurn(prompt, signal) {
+        const resumeId = this.previousResponseId;
+        const degrade = await this.attemptTurn(prompt, signal, resumeId, resumeId !== undefined);
+        if (degrade && !this.cancelling && !signal.aborted) {
+            hlog(`[hermes] resume with previous_response_id=${resumeId} was rejected before streaming; retrying as a cold start`);
+            this.previousResponseId = undefined;
+            await this.attemptTurn(prompt, signal, undefined, false);
+        }
+    }
+    async attemptTurn(prompt, signal, previousResponseId, canDegrade) {
+        const outcome = await this.postTurn(prompt, signal, previousResponseId);
+        if (outcome.kind === 'aborted') {
+            this.emitAbortedIdle();
+            return false;
+        }
+        if (outcome.kind === 'error') {
+            if (canDegrade)
+                return true;
+            this.emitTurnError(outcome.code, outcome.detail);
+            this.emitTurnIdle('error');
+            return false;
+        }
+        try {
+            await this.consumeSse(outcome.response, signal);
+        }
+        catch (err) {
+            if (this.cancelling || signal.aborted) {
+                this.emitAbortedIdle();
+            }
+            else {
+                this.emitTurnError('HERMES_STREAM_ERROR', errMessage(err));
+                this.emitTurnIdle('error');
+            }
+        }
+        finally {
+            if (this.mapper.lastResponseId) {
+                this.previousResponseId = this.mapper.lastResponseId;
+            }
+        }
+        return false;
+    }
+    async postTurn(prompt, signal, previousResponseId) {
+        const body = {
+            input: prompt,
+            stream: true,
+            store: true,
+        };
+        if (previousResponseId !== undefined) {
+            body.previous_response_id = previousResponseId;
+        }
+        else {
+            body.conversation = this.conversationId;
+        }
+        const model = this.sessionOptions?.model;
+        if (model)
+            body.model = model;
+        const instructions = this.buildInstructions();
+        if (instructions)
+            body.instructions = instructions;
+        const reasoningEffort = resolveHermesReasoningEffort(model, this.sessionOptions?.effortLevel);
+        if (reasoningEffort)
+            body.model_options = { reasoning: { effort: reasoningEffort } };
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}/v1/responses`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'X-Hermes-Session-Key': this.conversationId,
+                },
+                body: JSON.stringify(body),
+                signal,
+            });
+        }
+        catch (err) {
+            if (this.cancelling || signal.aborted)
+                return { kind: 'aborted' };
+            return { kind: 'error', code: 'HERMES_REQUEST_ERROR', detail: errMessage(err) };
+        }
+        if (!response.ok) {
+            let detail = `${response.status} ${response.statusText}`;
+            try {
+                const text = (await response.text()).trim();
+                if (text)
+                    detail = text;
+            }
+            catch {
+            }
+            return { kind: 'error', code: 'HERMES_HTTP_ERROR', detail };
+        }
+        return { kind: 'ok', response };
+    }
+    async consumeSse(response, signal) {
+        const body = response.body;
+        if (body) {
+            const reader = body.getReader();
+            const decoder = new TextDecoder();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value) {
+                        this.sseBuffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, '\n');
+                        this.drainSseFrames();
+                    }
+                }
+                const trailing = this.sseBuffer.trim();
+                this.sseBuffer = '';
+                if (trailing)
+                    this.handleSseFrame(trailing);
+            }
+            finally {
+                reader.releaseLock?.();
+            }
+        }
+        this.emitStreamEndIdle(signal);
+    }
+    emitStreamEndIdle(signal) {
+        if (this.cancelling || signal.aborted) {
+            this.emitAbortedIdle();
+        }
+        else {
+            this.emitTurnIdle(this.turnStreamFailed ? 'error' : 'end_turn');
+        }
+    }
+    drainSseFrames() {
+        let sepIdx = this.sseBuffer.indexOf('\n\n');
+        while (sepIdx >= 0) {
+            const frame = this.sseBuffer.slice(0, sepIdx);
+            this.sseBuffer = this.sseBuffer.slice(sepIdx + 2);
+            if (frame.trim())
+                this.handleSseFrame(frame);
+            sepIdx = this.sseBuffer.indexOf('\n\n');
+        }
+    }
+    handleSseFrame(frame) {
+        for (const event of this.mapper.ingestFrame(frame)) {
+            if (event.kind === 'session.idle')
+                this.turnIdleEmitted = true;
+            if (event.kind === 'engine.error')
+                this.turnStreamFailed = true;
+            this.emit(event);
+        }
+    }
+    emitTurnIdle(stopReason, raw, notice) {
+        if (this.turnIdleEmitted || this.disposed)
+            return;
+        this.turnIdleEmitted = true;
+        this.emit({
+            kind: 'session.idle',
+            sessionId: this.sessionIdForEvent(),
+            timestamp: Date.now(),
+            stopReason,
+            ...(notice ? { notice } : {}),
+            raw,
+        });
+    }
+    startRunBudget(controller) {
+        const appRun = this.sessionOptions?.appRun;
+        this.runBudgetExpired = false;
+        if (!appRun)
+            return undefined;
+        const timer = setTimeout(() => {
+            this.runBudgetExpired = true;
+            controller.abort();
+        }, appRun.runBudgetSeconds * 1000);
+        timer.unref?.();
+        return timer;
+    }
+    emitAbortedIdle() {
+        const appRun = this.sessionOptions?.appRun;
+        if (appRun && this.runBudgetExpired) {
+            this.emitTurnIdle('run_budget_exhausted', undefined, `The run reached its ${appRun.runBudgetSeconds}-second time limit and was stopped.`);
+            return;
+        }
+        this.emitTurnIdle('cancelled');
+    }
+    emitTurnError(code, message, raw) {
+        if (this.disposed)
+            return;
+        this.emit({
+            kind: 'engine.error',
+            sessionId: this.sessionIdForEvent(),
+            timestamp: Date.now(),
+            code,
+            message,
+            fatal: false,
+            raw,
+        });
+    }
+    async claimPort() {
+        const port = await claimGatewayPort();
+        if (this.disposed) {
+            claimedGatewayPorts.delete(port);
+        }
+        else {
+            this.claimedPort = port;
+        }
+        return port;
+    }
+    releasePort() {
+        if (this.claimedPort === null)
+            return;
+        claimedGatewayPorts.delete(this.claimedPort);
+        this.claimedPort = null;
+    }
+    startupOutputSuffix() {
+        if (this.startupOutput.length === 0)
+            return '';
+        const secrets = [
+            this.apiKey,
+            ...Object.values(this.providerEnv),
+            ...Object.values(this.gatewayHome?.env ?? {}),
+        ].filter((value) => value.length >= 8);
+        const lines = this.startupOutput.map((line) => secrets.reduce((masked, secret) => masked.split(secret).join('[redacted]'), line));
+        return `\nLast gateway output:\n${lines.join('\n')}`;
+    }
+    killGateway() {
+        const child = this.gateway;
+        if (!child || child.pid === undefined)
+            return;
+        const pid = child.pid;
+        killProcessGroup(pid, 'SIGTERM');
+        setTimeout(() => {
+            if (!child.killed) {
+                killProcessGroup(pid, 'SIGKILL');
+            }
+        }, 5000).unref?.();
+    }
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}