@ours.network/fleet 1.1.4 → 1.1.5

package/dist/harness/hermes-config.js

@@ -0,0 +1,367 @@
+import { chmodSync, lstatSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join, parse, resolve } from 'node:path';
+import YAML from 'yaml';
+import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
+import { harnessRuntimeDir } from '../isolation/policy.js';
+import { acpMcpServersFor, validateMcpServers } from './acp-mcp.js';
+import { translateHermesPermissions } from './hermes-permissions.js';
+const mapping = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const credentialPathName = (key) => /(?:^|_)CREDENTIALS(?:_PATH|_FILE)?$/i.test(key);
+const reserved = (key) => /^(?:_?HERMES_|OURS_|COPILOT_|CODEX_HOME$|TERMINAL_|OPENAI_|ANTHROPIC_|AZURE_|AWS_|GOOGLE_|GEMINI_|GROQ_|OPENROUTER_|NOUS_|TOGETHER_|FIREWORKS_|DEEPSEEK_|XAI_|MISTRAL_|COHERE_|OLLAMA_|LM_STUDIO_|VLLM_)/i.test(key)
+    || /(?:_API_KEY|_TOKEN|_SECRET|_PASSWORD|_BASE_URL|_KEY)$/i.test(key) || credentialPathName(key);
+// Native providers may choose arbitrary credential variable names (key_env).
+// An execution allowlist is therefore the inherited baseline, not a credential denylist.
+const executionKey = (key) => /^(?:PATH|HOME|USER|LOGNAME|SHELL|LANG|LANGUAGE|LC_[A-Z_]+|TERM|COLORTERM|TMPDIR|TMP|TEMP|TZ|SystemRoot|SYSTEMROOT|WINDIR|COMSPEC|ComSpec|PATHEXT|USERPROFILE|HOMEDRIVE|HOMEPATH|APPDATA|LOCALAPPDATA|PROGRAMDATA|PROGRAMFILES|ProgramFiles|NUMBER_OF_PROCESSORS|OS|PROCESSOR_ARCHITECTURE)$/i.test(key);
+export function validateHermesOptions(options) {
+    if (options == null)
+        return [];
+    if (!mapping(options))
+        return [{ path: 'harness_options', message: 'must be a map' }];
+    const errors = Object.keys(options).filter(key => key !== 'mcp_servers').map(key => ({ path: `harness_options.${key}`, message: 'unsupported Hermes option; allowed: mcp_servers (provider and credentials must be provisioned in the stopped native home)' }));
+    errors.push(...validateMcpServers(options.mcp_servers));
+    if (!errors.length && options.mcp_servers != null) {
+        const servers = options.mcp_servers;
+        for (const [name, server] of Object.entries(servers)) {
+            const remote = server.type === 'http' || server.type === 'sse';
+            const allowed = remote ? ['type', 'url', 'headers'] : ['type', 'command', 'args', 'env'];
+            for (const key of Object.keys(server))
+                if (!allowed.includes(key))
+                    errors.push({ path: `harness_options.mcp_servers.${name}.${key}`, message: 'unsupported field for this MCP transport' });
+            for (const key of Object.keys(server.env ?? {}))
+                if (/^(?:OURS_|_?HERMES_)/i.test(key))
+                    errors.push({ path: `harness_options.mcp_servers.${name}.env.${key}`, message: 'reserved Fleet/Hermes environment variable' });
+            if (remote) {
+                try {
+                    if (!['http:', 'https:'].includes(new URL(server.url).protocol))
+                        throw new Error();
+                }
+                catch {
+                    errors.push({ path: `harness_options.mcp_servers.${name}.url`, message: 'must be an absolute HTTP(S) URL' });
+                }
+            }
+        }
+        if (servers.ours && !identicalOurs(servers.ours))
+            errors.push({ path: 'harness_options.mcp_servers.ours', message: 'reserved ours connector must be { command: ours-mcp, args: [proxy] } with no overrides' });
+    }
+    return errors;
+}
+function identicalOurs(server) {
+    return Object.keys(server).every(key => ['type', 'command', 'args', 'env'].includes(key))
+        && (server.type == null || server.type === 'stdio') && server.command === 'ours-mcp'
+        && JSON.stringify(server.args) === '["proxy"]' && Object.keys(server.env ?? {}).length === 0;
+}
+export function validateHermesRole(role) {
+    const errors = validateHermesOptions(role.harness_options);
+    if (typeof role.model !== 'string' || !role.model.trim())
+        errors.push({ path: 'model', message: 'Hermes requires an explicit non-empty Brain model' });
+    for (const key of ['effort', 'model_chain'])
+        if (role[key] != null)
+            errors.push({ path: key, message: `Hermes does not support ${key}` });
+    if (role.session !== 'acp')
+        errors.push({ path: 'session', message: 'Hermes requires session: acp' });
+    if (role.monitor?.mode === 'native')
+        errors.push({ path: 'monitor.mode', message: 'Hermes requires Fleet-owned monitoring' });
+    if (role.monitor?.interrupt === 'after_tool')
+        errors.push({ path: 'monitor.interrupt', message: 'Hermes does not support after_tool' });
+    const permissions = translateHermesPermissions(role.permissions);
+    if (!permissions.supported)
+        errors.push({ path: 'permissions', message: permissions.reason });
+    for (const key of Object.keys(role.env ?? {}))
+        if (reserved(key))
+            errors.push({ path: `env.${key}`, message: 'reserved Hermes/Fleet or provider variable; provision provider credentials in the stopped native home' });
+    return errors;
+}
+function throwErrors(errors) {
+    if (errors.length)
+        throw new Error(errors.map(e => `${e.path}: ${e.message}`).join('; '));
+}
+// Match the supported native config expander's ${VAR} and ${env:VAR} shapes.
+const hasNativeInterpolation = (value) => typeof value === 'string' && /\$\{[^}]+\}/.test(value);
+// Native config.py's credential vocabulary, plus its model.api alias below.
+const credentialFields = new Set(['api_key', 'apikey', 'key', 'token', 'access_token', 'refresh_token', 'id_token', 'secret', 'client_secret', 'password', 'passwd', 'auth', 'authorization', 'private_key', 'bearer', 'jwt']);
+const credentialEnvName = (key) => credentialFields.has(key.toLowerCase()) || /(?:_API_KEY|_TOKEN|_SECRET|_PASSWORD|_PASSWD|_KEY)$/i.test(key) || credentialPathName(key);
+function configReferences(value) {
+    return [...value.matchAll(/\$\{([^}]+)\}/g)].flatMap(match => {
+        const inner = match[1].trim();
+        const name = inner.startsWith('env:') ? inner.slice(4).trim()
+            : /^[a-z][a-z0-9_-]*:/.test(inner) ? '' : inner;
+        return name ? [name] : [];
+    });
+}
+function nativeCredentialKeys(config) {
+    const keys = new Set();
+    // YAML aliases can reach the same object through ordinary and credential fields.
+    const seen = [new Set(), new Set()];
+    const visit = (value, credential = false) => {
+        if (typeof value === 'string') {
+            if (credential)
+                for (const name of configReferences(value))
+                    keys.add(name);
+            return;
+        }
+        if (value === null || typeof value !== 'object' || seen[Number(credential)].has(value))
+            return;
+        seen[Number(credential)].add(value);
+        for (const [key, child] of Object.entries(value)) {
+            if ((key === 'key_env' || key === 'api_key_env') && typeof child === 'string' && child.trim()) {
+                if (hasNativeInterpolation(child))
+                    throw new Error('Hermes credential variable names do not support interpolation in a Fleet-managed home; provision literal key_env/api_key_env names with the role stopped');
+                keys.add(child.trim());
+            }
+            else
+                visit(child, credential || credentialFields.has(key.toLowerCase()) || key === 'extra_headers' || (value === config.model && key === 'api'));
+        }
+    };
+    visit(config);
+    return keys;
+}
+function dotenvSources(content, sources) {
+    const lines = content.split(/\r\n?|\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const assignment = /^\s*(?:export\s+)?(?:'([^']+)'|([^\s=#]+))\s*=/.exec(lines[i]);
+        if (!assignment)
+            continue;
+        const key = assignment[1] ?? assignment[2];
+        let value = lines[i].slice(assignment[0].length).trimStart();
+        let ambiguous = false;
+        if (value.startsWith('"') || value.startsWith("'")) {
+            // Only discover references: do not expand values or resolve assignment precedence.
+            const quoted = value.startsWith('"') ? /^"((?:\\"|[^"])*)"/ : /^'((?:\\'|[^'])*)'/;
+            let match = quoted.exec(value);
+            let last = i;
+            let combined = value;
+            while (!match && last + 1 < lines.length) {
+                combined += '\n' + lines[++last];
+                match = quoted.exec(combined);
+            }
+            if (match) {
+                value = match[1];
+                ambiguous = last !== i;
+                i = last;
+            }
+            else
+                ambiguous = true;
+        }
+        else
+            value = value.replace(/\s+#.*$/, '').trimEnd();
+        // python-dotenv uses ${NAME} / ${NAME:-default}, not Hermes config's env: prefix.
+        const references = [...value.matchAll(/\$\{([^}:]*)(?::-[^}]*)?\}/g)].map(match => match[1]);
+        const source = sources.get(key) ?? { references: new Set(), ambiguous: false };
+        for (const name of references)
+            source.references.add(name);
+        source.ambiguous ||= references.length > 0 && (ambiguous || value.includes('\\'));
+        sources.set(key, source);
+    }
+}
+function validateNativeCredentialOverrides(role, config, home) {
+    const keys = nativeCredentialKeys(config);
+    const sources = new Map();
+    for (const name of ['.env', '.op.env']) {
+        const content = validateHomeDotenv(join(home, name));
+        if (content !== undefined)
+            dotenvSources(content, sources);
+    }
+    for (const key of sources.keys())
+        if (credentialEnvName(key))
+            keys.add(key);
+    // Set iteration visits newly added dependencies; cycles terminate without evaluating secrets.
+    for (const key of keys) {
+        const source = sources.get(key);
+        if (source?.ambiguous)
+            throw new Error('Hermes credential dotenv interpolation must use single-line assignments without escape encoding; provision it with the role stopped');
+        for (const dependency of source?.references ?? [])
+            keys.add(dependency);
+    }
+    for (const key of keys)
+        if (Object.hasOwn(role.env ?? {}, key))
+            throw new Error('role.env overrides a native credential variable; provision credentials in the stopped Hermes home');
+    return keys;
+}
+/** Complete environment: transport MUST use inheritEnvironment:false after this final merge. */
+export function hermesChildEnvironment(role, home, trustedFleetEnv, inherited = process.env) {
+    for (const key of Object.keys(role.env ?? {}))
+        if (reserved(key))
+            throw new Error(`env.${key} is reserved; provision native credentials in the stopped Hermes home`);
+    const credentialKeys = validateNativeCredentialOverrides(role, readConfig(join(home, 'config.yaml')), home);
+    const env = {};
+    for (const [key, value] of Object.entries(inherited))
+        if (value !== undefined && executionKey(key) && !credentialKeys.has(key))
+            env[key] = value;
+    Object.assign(env, role.env);
+    for (const [key, value] of Object.entries(trustedFleetEnv))
+        if (key.startsWith('OURS_'))
+            env[key] = value;
+    env.HERMES_HOME = home;
+    env.HERMES_ACP_SKIP_CONFIGURED_MCP = '1';
+    return env;
+}
+export function hermesMcpServers(role, trustedFleetEnv = {}) {
+    throwErrors(validateHermesOptions(role.harness_options));
+    const options = (role.harness_options ?? {});
+    const oursEnv = Object.fromEntries(Object.entries(trustedFleetEnv).filter(([key]) => key.startsWith('OURS_')));
+    return acpMcpServersFor({ ours: { command: 'ours-mcp', args: ['proxy'], env: oursEnv }, ...Object.fromEntries(Object.entries(options.mcp_servers ?? {}).filter(([name]) => name !== 'ours')) });
+}
+function stat(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return undefined;
+        throw e;
+    }
+}
+function regular(path) {
+    const info = stat(path);
+    if (!info)
+        return false;
+    if (info.isSymbolicLink() || !info.isFile() || info.nlink !== 1)
+        throw new Error(`Hermes requires a regular, non-symlink, unshared file: ${path}`);
+    return true;
+}
+function privateDirectory(path) {
+    const absolute = resolve(path);
+    let current = parse(absolute).root;
+    for (const component of absolute.slice(current.length).split('/').filter(Boolean)) {
+        current = join(current, component);
+        const info = stat(current);
+        if (info?.isSymbolicLink() || (info && !info.isDirectory()))
+            throw new Error(`Hermes home path must contain directories without symlinks: ${current}`);
+        if (!info)
+            mkdirSync(current, { mode: 0o700 });
+    }
+    chmodSync(absolute, 0o700);
+}
+function parseNativeFile(path) {
+    try {
+        return path.endsWith('.json') ? JSON.parse(readFileSync(path, 'utf8')) : YAML.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        throw new Error(`Invalid Hermes configuration file; repair it with the role stopped: ${path}`);
+    }
+}
+function validateHomeDotenv(path) {
+    if (!regular(path))
+        return;
+    // Native dotenv accepts export and single-quoted keys. Read keys only; never
+    // return credential values or native parser diagnostics that may contain them.
+    // Native startup rewrites UTF-16 and strips NULs before parsing. Refuse those
+    // inputs rather than normalize credentials or validate a different assignment.
+    const bytes = readFileSync(path);
+    let content;
+    try {
+        if (bytes.includes(0))
+            throw new Error();
+        content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        // Python treats these controls as whitespace; JavaScript's key scanner does not.
+        if (/[\u001c-\u001f\u0085]/.test(content))
+            throw new Error();
+    }
+    catch {
+        throw new Error(`Unsupported Hermes dotenv encoding; use UTF-8 without NUL or unsupported control characters with the role stopped: ${path}`);
+    }
+    for (const line of content.split(/\r\n?|\n/)) {
+        const match = /^\s*(?:export\s+)?(?:'([^']+)'|([^\s=#]+))\s*=/.exec(line);
+        if (!match)
+            continue;
+        const key = match[1] ?? match[2];
+        if (/^OURS_/i.test(key) || /^(?:_?HERMES_(?:HOME|PROFILE|CONFIG(?:_PATH)?|ENV(?:_PATH)?|SHARED_AUTH_DIR|MANAGED_DIR|YOLO_MODE|INTERACTIVE|EXEC_ASK|GATEWAY_SESSION|CRON_SESSION|SINGLE_QUERY_SESSION|SESSION_.*|ACP_AUTO_APPROVE|ACP_SKIP_CONFIGURED_MCP|MODEL|ENABLE_PROJECT_PLUGINS|OPTIONAL_MCPS|SAFE_MODE|IGNORE_USER_CONFIG))$/i.test(key)) {
+            throw new Error(`Hermes home dotenv contains a reserved Fleet/Hermes setting; remove it with the role stopped: ${path}`);
+        }
+    }
+    return content;
+}
+function readConfig(path) {
+    if (!regular(path))
+        return {};
+    const doc = parseNativeFile(path);
+    if (!mapping(doc))
+        throw new Error(`Hermes configuration must be a YAML mapping: ${path}`);
+    return doc;
+}
+function managedMapping(config, key) {
+    if (config[key] === undefined)
+        return {};
+    if (!mapping(config[key]))
+        throw new Error(`Hermes configuration ${key} must be a mapping`);
+    return config[key];
+}
+function validateHomeMcp(config, home) {
+    if (config.mcp_servers != null) {
+        if (!mapping(config.mcp_servers))
+            throw new Error('Hermes home mcp_servers must be a map');
+        for (const server of Object.values(config.mcp_servers)) {
+            if (!mapping(server) || server.enabled !== false)
+                throw new Error(`Disable home-configured MCP servers in ${join(home, 'config.yaml')}; declare extras through Fleet harness_options.mcp_servers`);
+        }
+    }
+    const plugins = config.plugins;
+    if (plugins != null && !mapping(plugins))
+        throw new Error('Hermes home plugins must be a map');
+    if (mapping(plugins)) {
+        for (const gate of ['enabled', 'disabled']) {
+            const names = plugins[gate];
+            if (Array.isArray(names) && names.some(hasNativeInterpolation))
+                throw new Error('Hermes plugins.enabled/disabled do not support interpolation in a Fleet-managed home; provision literal plugin names with the role stopped');
+        }
+    }
+    const enabled = mapping(plugins) && Array.isArray(plugins.enabled) && plugins.enabled.every(x => typeof x === 'string') ? plugins.enabled : undefined;
+    const disabled = mapping(plugins) && Array.isArray(plugins.disabled) ? plugins.disabled : [];
+    if (enabled?.length === 0)
+        return;
+    const scan = (directory, prefix = '', depth = 0) => {
+        const info = stat(directory);
+        if (!info)
+            return;
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw new Error(`Hermes plugins directory must be a non-symlink directory: ${directory}`);
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (entry.isSymbolicLink())
+                throw new Error(`Hermes plugin paths must not be symlinks: ${join(directory, entry.name)}`);
+            if (!entry.isDirectory())
+                continue;
+            const root = join(directory, entry.name);
+            const key = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const manifests = ['plugin.yaml', 'plugin.yml', 'plugin.json'];
+            const manifest = manifests.find(name => stat(join(root, name)));
+            if (!manifest) {
+                if (depth === 0)
+                    scan(root, key, 1);
+                continue;
+            }
+            regular(join(root, manifest));
+            const value = parseNativeFile(join(root, manifest));
+            const name = mapping(value) && typeof value.name === 'string' ? value.name : entry.name;
+            if (disabled.includes(key) || disabled.includes(name) || (enabled && !enabled.includes(key) && !enabled.includes(name)))
+                continue;
+            const mcpPath = join(root, 'mcp.json');
+            if (manifest === 'plugin.json' && regular(mcpPath)) {
+                const mcp = parseNativeFile(mcpPath);
+                if (!mapping(mcp) || !mapping(mcp.mcpServers) || Object.keys(mcp.mcpServers).length)
+                    throw new Error(`Disable MCP-providing agent plugin ${key} in ${join(home, 'config.yaml')}; declare MCP extras through Fleet`);
+            }
+        }
+    };
+    scan(join(home, 'plugins'));
+}
+export async function prepareHermesConfig(role, dirs) {
+    throwErrors(validateHermesRole(role));
+    const home = harnessRuntimeDir(dirs.stateDir, 'hermes');
+    privateDirectory(home);
+    const file = join(home, 'config.yaml');
+    const lock = `${file}.lock`;
+    const lockStat = stat(lock);
+    if (lockStat?.isSymbolicLink() || (lockStat && !lockStat.isDirectory()))
+        throw new Error(`Hermes configuration lock must be a non-symlink directory: ${lock}`);
+    await withFileLock(lock, () => {
+        const config = readConfig(file);
+        const model = managedMapping(config, 'model');
+        const approvals = managedMapping(config, 'approvals');
+        validateNativeCredentialOverrides(role, config, home);
+        validateHomeMcp(config, home);
+        config.model = { ...model, default: role.model };
+        config.approvals = { ...approvals, mode: 'manual' };
+        replaceFileAtomically(file, YAML.stringify(config), 0o600);
+    });
+    return { env: hermesChildEnvironment(role, home, { OURS_BIND_IDENTITY: role.identity }) };
+}

package/dist/harness/hermes-permissions.d.ts

@@ -0,0 +1,4 @@
+import type { CommonPermissions } from '../config.js';
+import type { PermissionTranslation } from './types.js';
+export declare function hermesPermissionMode(permissions: CommonPermissions): 'default' | 'accept_edits' | 'dont_ask';
+export declare function translateHermesPermissions(permissions: CommonPermissions): PermissionTranslation;

package/dist/harness/hermes-permissions.js

@@ -0,0 +1,36 @@
+export function hermesPermissionMode(permissions) {
+    if (permissions.approval === 'deny')
+        throw new Error('Hermes does not support legacy approval: deny');
+    const modes = { ask: 'default', auto: 'accept_edits', allow: 'dont_ask' };
+    const mode = modes[permissions.approval];
+    if (!mode)
+        throw new Error('Hermes approval must be ask, auto or allow');
+    return mode;
+}
+export function translateHermesPermissions(permissions) {
+    if (permissions.filesystem === 'read-only')
+        return { supported: false, reason: 'Hermes does not support read-only filesystem mode, including with Fleet isolation' };
+    if (!['workspace', 'unrestricted'].includes(permissions.filesystem))
+        return { supported: false, reason: 'Hermes filesystem must be workspace or unrestricted' };
+    let mode;
+    try {
+        mode = hermesPermissionMode(permissions);
+    }
+    catch (e) {
+        return { supported: false, reason: e.message };
+    }
+    const capabilities = ['read-state', 'messaging', 'monitor', 'status-commands'];
+    if (permissions.approval !== 'ask')
+        capabilities.push('write-state', 'workspace-edit');
+    return {
+        supported: true,
+        native: { permission_mode: mode, approvals_mode: 'manual' },
+        exact: false,
+        capabilities,
+        warnings: [
+            'Hermes modes mediate dangerous terminal commands and write_file/patch; browser, memory, skills, delegation and MCP side effects are not universally approval-mediated.',
+            'Unattended wait is bounded by Fleet’s 50-second permission timeout and the tested Hermes native 60-second dangerous-command timeout; protected-action floors remain active.',
+            ...(permissions.filesystem === 'workspace' ? ['Workspace confinement is an approximation unless enforcing Fleet isolation is verified on this platform.'] : []),
+        ],
+    };
+}

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

@@ -0,0 +1,24 @@
+import type * as acp from '@agentclientprotocol/sdk';
+import type { ResolvedRole } from '../config.js';
+import type { SessionPrep } from './types.js';
+import type { AgentSessionAdapter, AgentSessionStartOptions, BrainSelection } from './agent-session.js';
+import type { AcpSessionTransport } from './acp-session-transport.js';
+/** Native provider resolution and executable compatibility remain harness-owned. */
+export interface HermesStartupChecks {
+    /** Independently resolved native provider identity, never copied from the ACP report. */
+    expectedProvider(role: ResolvedRole, prep: SessionPrep): string | Promise<string>;
+    validateArtifact(initialized: acp.InitializeResponse): void | Promise<void>;
+    /** Inspect the executable using the completed child environment before spawning it. */
+    preflight?(options: AgentSessionStartOptions, env: Record<string, string>): void | Promise<void>;
+}
+/** Fresh-only Hermes implementation of Fleet's existing live-session factory. */
+export declare class HermesAgentSessionAdapter implements AgentSessionAdapter {
+    private readonly transport;
+    private readonly checks?;
+    constructor(transport?: AcpSessionTransport, checks?: HermesStartupChecks | undefined);
+    resolveBrain(brain: BrainSelection): ReturnType<AgentSessionAdapter['resolveBrain']>;
+    modelEnvironmentVariable(): string | undefined;
+    prepareLaunch(role: ResolvedRole, prep: SessionPrep): ReturnType<AgentSessionAdapter['prepareLaunch']>;
+    sessionConfigSelections(role: ResolvedRole): ReturnType<AgentSessionAdapter['sessionConfigSelections']>;
+    start(options: AgentSessionStartOptions): ReturnType<AgentSessionAdapter['start']>;
+}

package/dist/harness/hermes-session.js

@@ -0,0 +1,85 @@
+import { AcpSession } from '../session/acp.js';
+import { hermesChildEnvironment, hermesMcpServers, validateHermesOptions, validateHermesRole } from './hermes-config.js';
+import { hermesPermissionMode } from './hermes-permissions.js';
+function requireValid(errors) {
+    if (errors.length)
+        throw new Error(errors.map(error => `${error.path}: ${error.message}`).join('; '));
+}
+function requireModel(model) {
+    if (typeof model !== 'string' || !model.trim())
+        throw new Error('Hermes requires an explicit non-empty Brain model');
+    return model.trim();
+}
+function preparedHome(prep) {
+    if (!prep.env.HERMES_HOME?.trim())
+        throw new Error('Hermes requires a prepared runtime home');
+    return prep.env.HERMES_HOME;
+}
+/** Fresh-only Hermes implementation of Fleet's existing live-session factory. */
+export class HermesAgentSessionAdapter {
+    transport;
+    checks;
+    constructor(transport = AcpSession.start, checks) {
+        this.transport = transport;
+        this.checks = checks;
+    }
+    resolveBrain(brain) {
+        const model = requireModel(brain.model);
+        if (brain.effort != null)
+            throw new Error('Hermes does not support effort');
+        requireValid(validateHermesOptions(brain.harnessOptions));
+        return { model, ...(brain.harnessOptions ? { harnessOptions: brain.harnessOptions } : {}) };
+    }
+    modelEnvironmentVariable() { return undefined; }
+    prepareLaunch(role, prep) {
+        requireValid(validateHermesRole(role));
+        preparedHome(prep);
+        const command = role.session_options?.acp?.command;
+        const argv = Array.isArray(command) ? [...command]
+            : typeof command === 'string' ? ['sh', '-c', command] : ['hermes-acp'];
+        return { argv, env: { ...prep.env } };
+    }
+    sessionConfigSelections(role) {
+        requireValid(validateHermesRole(role));
+        return [];
+    }
+    async start(options) {
+        const { role, prep, launch } = options;
+        requireValid(validateHermesRole({ ...role, permissions: options.permissions }));
+        const model = requireModel(role.model);
+        if (!this.checks)
+            throw new Error('Hermes startup checks are required before launching a managed session');
+        // Reapply the complete environment boundary after runner routing/isolation
+        // composition; no second ambient merge may reintroduce provider secrets.
+        const env = hermesChildEnvironment(role, preparedHome(prep), launch.env, launch.env);
+        delete env.OURS_AUTOSTART;
+        await this.checks.preflight?.(options, env);
+        const nativeProvider = await this.checks.expectedProvider(role, prep);
+        if (typeof nativeProvider !== 'string' || !nativeProvider.trim())
+            throw new Error('Hermes requires an independently resolved native provider');
+        const provider = nativeProvider.trim().toLowerCase();
+        // model_catalog.encode_model_choice preserves model colons; its catalog
+        // constructor promotes Ollama to the named custom provider identity.
+        const expectedModelId = `${provider === 'ollama' ? 'custom:ollama' : provider}:${model}`;
+        const modeId = hermesPermissionMode(options.permissions);
+        return this.transport({
+            name: role.name, harness: 'hermes', argv: launch.argv, cwd: options.cwd, env,
+            inheritEnvironment: false, stateDir: options.stateDir, mode: 'fresh',
+            permissions: options.permissions, modeId, requireMode: true,
+            permissionMode: { fleetMode: options.permissionMode.fleetMode, nativeMode: modeId },
+            permissionTimeoutMs: 50_000,
+            mcpServers: hermesMcpServers(role, env),
+            scrubObsoleteOursAutostart: true,
+            validateStartupResponse: async (initialized, created) => {
+                await this.checks.validateArtifact(initialized);
+                if (typeof created.models?.currentModelId !== 'string'
+                    || created.models.currentModelId !== expectedModelId)
+                    throw new Error('Hermes fresh-session model/provider report does not match the Brain model and provisioned provider');
+            },
+            ...(role.monitor?.mode === 'fleet' && role.monitor.stall_recovery ? {
+                stallRecovery: { timeoutMs: role.monitor.stall_timeout_ms },
+            } : {}),
+            log: options.log,
+        });
+    }
+}

package/dist/harness/hermes-startup.d.ts

@@ -0,0 +1,3 @@
+export { validateHermesInitialize as validateHermesHandshake } from './hermes-compatibility.js';
+/** Compare a native provisioned identity, never infer it from the child's report. */
+export declare function hermesConfiguredProvider(home: string): string;

package/dist/harness/hermes-startup.js

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import YAML from 'yaml';
+export { validateHermesInitialize as validateHermesHandshake } from './hermes-compatibility.js';
+/** Compare a native provisioned identity, never infer it from the child's report. */
+export function hermesConfiguredProvider(home) {
+    let provider;
+    try {
+        provider = YAML.parse(readFileSync(join(home, 'config.yaml'), 'utf8'))?.model?.provider;
+    }
+    catch {
+        throw new Error('Cannot read Hermes native provider; repair config.yaml in the stopped role home');
+    }
+    if (typeof provider !== 'string' || !provider.trim() || provider.trim().toLowerCase() === 'auto' || provider.includes('${'))
+        throw new Error('Hermes requires a literal native model.provider in the stopped role home so startup can detect provider fallback');
+    const canonical = provider.trim().toLowerCase();
+    // The tested runtime collapses named custom endpoints to custom, while its
+    // ACP model catalog reports Ollama under custom:ollama.
+    return canonical === 'ollama' || canonical === 'custom:ollama' ? 'custom:ollama'
+        : canonical.startsWith('custom:') ? 'custom' : canonical;
+}

package/dist/harness/hermes.d.ts

@@ -0,0 +1,5 @@
+import { type Exec } from '../exec.js';
+import type { AcpSessionTransport } from './acp-session-transport.js';
+import type { HarnessAdapter } from './types.js';
+export declare function makeHermesAdapter(exec?: Exec, transport?: AcpSessionTransport): HarnessAdapter;
+export declare const hermesAdapter: HarnessAdapter;

package/dist/harness/hermes.js

@@ -0,0 +1,62 @@
+import { realExec } from '../exec.js';
+import { HermesAgentSessionAdapter } from './hermes-session.js';
+import { inspectHermesCompatibility } from './hermes-compatibility.js';
+import { hermesConfiguredProvider, validateHermesHandshake } from './hermes-startup.js';
+import { prepareHermesConfig, validateHermesOptions, validateHermesRole } from './hermes-config.js';
+import { hermesPermissionMode, translateHermesPermissions } from './hermes-permissions.js';
+import { registerAdapter } from './registry.js';
+const wakeNote = 'Your mail wake-ups are delivered by the fleet supervisor as `[fleet-monitor]` lines. '
+    + 'Call **get_messages**, handle the mail, and reply with send_message. '
+    + 'Do NOT arm arm_monitor, foreground_monitor or a native Hermes monitor.';
+export function makeHermesAdapter(exec = realExec, transport) {
+    return {
+        id: 'hermes',
+        agentSession: new HermesAgentSessionAdapter(transport, {
+            expectedProvider: (_role, prep) => hermesConfiguredProvider(prep.env.HERMES_HOME),
+            validateArtifact: validateHermesHandshake,
+            async preflight(options, env) {
+                const original = new HermesAgentSessionAdapter().prepareLaunch(options.role, options.prep);
+                const report = await inspectHermesCompatibility({ argv: original.argv, env, home: options.prep.env.HERMES_HOME }, exec);
+                options.log(`Hermes ${report.artifact.hermesVersion}, ACP ${report.artifact.acpVersion}; fresh conversation, MCP availability unverified until actual use`);
+            },
+        }),
+        supportsResume: false,
+        async checkPrereqs() {
+            const result = await exec('hermes-acp', ['--help'], { timeout: 10_000 });
+            const ok = result.code === 0;
+            return { ok, checks: [{ name: 'hermes-acp', ok, detail: ok
+                            ? 'Hermes ACP executable found; launch still requires a tested compatible artifact, an explicit Brain model and provider/credentials provisioned in the exact stopped role home. Home/plugin MCP providers must be disabled.'
+                            : 'hermes-acp unavailable; install the tested Hermes artifact and provision provider/credentials in the exact stopped role home.' }] };
+        },
+        validateOptions(options, role) {
+            return role ? validateHermesRole({ ...role, harness_options: options })
+                : validateHermesOptions(options);
+        },
+        prepareSession: prepareHermesConfig,
+        // The selected home is already beneath the role state directory, which
+        // Fleet mounts writable. No operator home or credential path is shared.
+        isolationPaths: () => ({ shared: [] }),
+        nativePermissionOverrides: () => ({}),
+        translatePermissions: translateHermesPermissions,
+        effectivePermissions: role => translateHermesPermissions(role.permissions),
+        effectivePermissionMode(role) {
+            const nativeMode = hermesPermissionMode(role.permissions);
+            return { fleetMode: role.permissions.approval, nativeMode };
+        },
+        vocabulary: {
+            bindTool: 'choose_identity', createTool: 'create_identity',
+            temporaryCreateTool: 'create_temporary_identity', setBioTool: 'set_bio',
+            setPersonaTool: 'set_persona', currentIdentityTool: 'current_identity',
+            sendTool: 'send_message', getMessagesTool: 'get_messages',
+            listHistoryTool: 'list_history', getHistoryItemTool: 'get_history_item',
+            monitorInstruction: () => wakeNote,
+            supervisedWakeNote: () => wakeNote,
+            launchNote: name => `You were launched as Fleet role ${name} in a fresh Hermes ACP conversation. Confirm you are running.`,
+            restartPrompt: (identity, worklog) => `This is a fresh Hermes conversation. Follow the full role briefing, bind identity "${identity}" without force, `
+                + `and continue from ${worklog}. Native memory and skills persist; the previous conversation is not restored. ${wakeNote}`,
+        },
+        exitPolicy: { cleanExitIsFresh: true, fastFailSecs: 20 },
+    };
+}
+export const hermesAdapter = makeHermesAdapter();
+registerAdapter(hermesAdapter);

package/dist/harness/registry.js

@@ -29,7 +29,7 @@ export function knownAdapters() {
  * registry" is not the same question — this is the set doctor falls back to
  * when a broken configuration names no harness at all.
  */
-const PRODUCTION_ADAPTERS = ['claude-code', 'codex'];
+const PRODUCTION_ADAPTERS = ['claude-code', 'codex', 'hermes'];
 /** Production adapters actually registered in this process. */
 export function productionAdapters() {
     return PRODUCTION_ADAPTERS.filter(id => adapters.has(id));

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { OwnerChannel } from './owner-channel/channel.js';
 export { registerAdapter, getAdapter, knownAdapters } from './harness/registry.js';
 export { claudeCodeAdapter, makeClaudeCodeAdapter } from './harness/claude-code.js';
 export { codexAdapter, makeCodexAdapter } from './harness/codex.js';
+export { hermesAdapter, makeHermesAdapter } from './harness/hermes.js';
 export { generateBriefing } from './briefing.js';
 export { effectivePermissionMode } from './permissions.js';
 export { pickBackend } from './supervisor/index.js';

package/dist/index.js

@@ -6,6 +6,7 @@ export { OwnerChannel } from './owner-channel/channel.js';
 export { registerAdapter, getAdapter, knownAdapters } from './harness/registry.js';
 export { claudeCodeAdapter, makeClaudeCodeAdapter } from './harness/claude-code.js';
 export { codexAdapter, makeCodexAdapter } from './harness/codex.js';
+export { hermesAdapter, makeHermesAdapter } from './harness/hermes.js';
 export { generateBriefing } from './briefing.js';
 export { effectivePermissionMode } from './permissions.js';
 export { pickBackend } from './supervisor/index.js';