hermes-action-bridge 0.2.0

package/dist/mcp-server.js

@@ -0,0 +1,69 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "./config.js";
+import { buildEffectiveRun } from "./run.js";
+import { runHermesCli } from "./adapters/hermes-cli.js";
+import { checkHermesStatus } from "./status.js";
+import { version } from "./version.js";
+const modeSchema = z.enum(["plan", "draft", "execute", "request-approval"]);
+async function delegate(config, options) {
+    const dryRun = options.dryRun ?? false;
+    const run = buildEffectiveRun(config, {
+        prompt: options.prompt,
+        mode: options.mode,
+        preset: options.preset,
+        contextFiles: options.contextFiles ?? [],
+        yolo: options.yolo ?? false,
+        dryRun,
+        json: false,
+    });
+    const result = await runHermesCli(config, run, dryRun);
+    const sections = [result.stdout, result.stderr].filter((section) => section.trim().length > 0);
+    const text = sections.length > 0 ? sections.join("\n") : `Hermes exited with code ${result.exitCode}`;
+    const content = [{ type: "text", text }];
+    return result.ok ? { content } : { content, isError: true };
+}
+export async function startMcpServer(configPath) {
+    const config = loadConfig(process.cwd(), configPath);
+    const server = new McpServer({ name: "hermes-action-bridge", version });
+    server.registerTool("hermes_run", {
+        title: "Delegate a request to Hermes",
+        description: "Run Hermes through the configured hermes-action-bridge policy and presets.",
+        inputSchema: {
+            prompt: z.string().min(1),
+            mode: modeSchema.optional(),
+            preset: z.string().optional(),
+            contextFiles: z.array(z.string()).optional(),
+            yolo: z.boolean().optional(),
+            dryRun: z.boolean().optional(),
+        },
+    }, (args) => delegate(config, {
+        prompt: args.prompt,
+        mode: args.mode,
+        preset: args.preset,
+        contextFiles: args.contextFiles,
+        yolo: args.yolo,
+        dryRun: args.dryRun,
+    }));
+    server.registerTool("hermes_plan", {
+        title: "Ask Hermes for a plan",
+        description: "Shortcut for hermes_run with mode=plan.",
+        inputSchema: { prompt: z.string().min(1), preset: z.string().optional(), contextFiles: z.array(z.string()).optional() },
+    }, (args) => delegate(config, {
+        prompt: args.prompt,
+        mode: "plan",
+        preset: args.preset,
+        contextFiles: args.contextFiles,
+    }));
+    server.registerTool("hermes_presets", {
+        title: "List presets",
+        description: "List configured hermes-action-bridge presets.",
+    }, () => ({ content: [{ type: "text", text: JSON.stringify(config.presets, null, 2) }] }));
+    server.registerTool("hermes_status", {
+        title: "Check Hermes runtime status",
+        description: "Check whether the configured Hermes command is available.",
+    }, () => ({ content: [{ type: "text", text: JSON.stringify(checkHermesStatus(config), null, 2) }] }));
+    await server.connect(new StdioServerTransport());
+}
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.js","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAW5E,KAAK,UAAU,QAAQ,CAAC,MAAoB,EAAE,OAAwB;IACpE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IACvC,MAAM,GAAG,GAAG,iBAAiB,CAAC,MAAM,EAAE;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,EAAE;QACxC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,KAAK;QAC3B,MAAM;QACN,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/F,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,2BAA2B,MAAM,CAAC,QAAQ,EAAE,CAAC;IACtG,MAAM,OAAO,GAAG,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,UAAmB;IACtD,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC,CAAC;IAExE,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,KAAK,EAAE,8BAA8B;QACrC,WAAW,EAAE,4EAA4E;QACzF,WAAW,EAAE;YACX,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACzB,IAAI,EAAE,UAAU,CAAC,QAAQ,EAAE;YAC3B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC7B,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;YAC5C,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;YAC5B,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SAC/B;KACF,EACD,CAAC,IAAI,EAAE,EAAE,CACP,QAAQ,CAAC,MAAM,EAAE;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAA8B;QACzC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC,CACL,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,aAAa,EACb;QACE,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,yCAAyC;QACtD,WAAW,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE;KACxH,EACD,CAAC,IAAI,EAAE,EAAE,CACP,QAAQ,CAAC,MAAM,EAAE;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,YAAY,EAAE,IAAI,CAAC,YAAY;KAChC,CAAC,CACL,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE,+CAA+C;KAC7D,EACD,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACvF,CAAC;IAEF,MAAM,CAAC,YAAY,CACjB,eAAe,EACf;QACE,KAAK,EAAE,6BAA6B;QACpC,WAAW,EAAE,2DAA2D;KACzE,EACD,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAClG,CAAC;IAEF,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC"}

package/dist/policy.d.ts

@@ -0,0 +1,9 @@
+import type { BridgeMode, PolicyConfig, RiskCategory } from "./types.js";
+export interface PolicyDecision {
+    mode: BridgeMode;
+    requestedMode: BridgeMode;
+    detectedRisks: RiskCategory[];
+    approvalRequired: boolean;
+}
+export declare function detectRisks(text: string): RiskCategory[];
+export declare function applyPolicy(requestedMode: BridgeMode, policy: PolicyConfig, prompt: string, yoloFlag: boolean): PolicyDecision;

package/dist/policy.js

@@ -0,0 +1,25 @@
+const riskMatchers = [
+    { risk: "publish_external", pattern: /\b(publish|post|tweet|linkedin|reddit|x\.com|twitter|social)\b/i },
+    { risk: "send_message", pattern: /\b(send|message|dm|discord|telegram|slack|whatsapp|sms)\b/i },
+    { risk: "send_email", pattern: /\b(email|e-mail|gmail|send mail|reply to)\b/i },
+    { risk: "delete", pattern: /\b(delete|remove|destroy|drop|wipe|rm\s+-rf)\b/i },
+    { risk: "payment", pattern: /\b(pay|payment|purchase|buy|subscribe|credit card|checkout)\b/i },
+    { risk: "git_push", pattern: /\b(git push|push to|publish branch|create repo|gh repo create)\b/i },
+    { risk: "credential_change", pattern: /\b(token|secret|api key|credential|password|oauth|keychain)\b/i },
+];
+export function detectRisks(text) {
+    const risks = new Set();
+    for (const matcher of riskMatchers) {
+        if (matcher.pattern.test(text))
+            risks.add(matcher.risk);
+    }
+    return [...risks];
+}
+export function applyPolicy(requestedMode, policy, prompt, yoloFlag) {
+    const detectedRisks = detectRisks(prompt);
+    const yolo = yoloFlag || policy.yolo;
+    const approvalRequired = !yolo && detectedRisks.some((risk) => policy.requireApprovalFor.includes(risk));
+    const mode = approvalRequired && requestedMode === "execute" ? "request-approval" : requestedMode;
+    return { mode, requestedMode, detectedRisks, approvalRequired };
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAmD;IACnE,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,iEAAiE,EAAE;IACxG,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,4DAA4D,EAAE;IAC/F,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,8CAA8C,EAAE;IAC/E,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,iDAAiD,EAAE;IAC9E,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,gEAAgE,EAAE;IAC9F,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,mEAAmE,EAAE;IAClG,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,gEAAgE,EAAE;CACzG,CAAC;AASF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IACtC,KAAK,MAAM,OAAO,IAAI,YAAY,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,aAAyB,EAAE,MAAoB,EAAE,MAAc,EAAE,QAAiB;IAC5G,MAAM,aAAa,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC;IACrC,MAAM,gBAAgB,GAAG,CAAC,IAAI,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACzG,MAAM,IAAI,GAAG,gBAAgB,IAAI,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,aAAa,CAAC;IAClG,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC;AAClE,CAAC"}

package/dist/prompt.d.ts

@@ -0,0 +1,2 @@
+import type { EffectiveRun } from "./types.js";
+export declare function buildHermesPrompt(run: EffectiveRun): string;

package/dist/prompt.js

@@ -0,0 +1,34 @@
+export function buildHermesPrompt(run) {
+    const contextBlock = run.contextDocuments.length
+        ? run.contextDocuments
+            .map((doc) => `<context path="${escapeAttribute(doc.path)}">\n${doc.content}\n</context>`)
+            .join("\n\n")
+        : "<context>None provided.</context>";
+    return [
+        "You are Hermes Agent being called by an external agent through hermes-action-bridge.",
+        "",
+        `Mode: ${run.mode}`,
+        `Requested mode: ${run.requestedMode}`,
+        `Preset: ${run.presetName}`,
+        `YOLO: ${run.yolo ? "enabled" : "disabled"}`,
+        `Detected risks: ${run.detectedRisks.length ? run.detectedRisks.join(", ") : "none"}`,
+        "",
+        "Policy:",
+        "- Follow the user's request using the tools and skills available in this Hermes session.",
+        "- If Mode is plan, return a plan only. Do not perform side effects.",
+        "- If Mode is draft, produce the requested artifact only. Do not perform external side effects.",
+        "- If Mode is request-approval, prepare the action and explicitly ask the human for approval before irreversible external effects.",
+        "- If Mode is execute, perform allowed actions, but still obey Hermes' own safety rules and any platform approval prompts.",
+        "- Never reveal secrets. Do not print API keys, OAuth tokens, passwords, private keys, or session cookies.",
+        "",
+        "External agent request:",
+        run.prompt,
+        "",
+        "Context files:",
+        contextBlock,
+    ].join("\n");
+}
+function escapeAttribute(value) {
+    return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+}
+//# sourceMappingURL=prompt.js.map

package/dist/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../src/prompt.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,MAAM,YAAY,GAAG,GAAG,CAAC,gBAAgB,CAAC,MAAM;QAC9C,CAAC,CAAC,GAAG,CAAC,gBAAgB;aACjB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,cAAc,CAAC;aACzF,IAAI,CAAC,MAAM,CAAC;QACjB,CAAC,CAAC,mCAAmC,CAAC;IAExC,OAAO;QACL,sFAAsF;QACtF,EAAE;QACF,SAAS,GAAG,CAAC,IAAI,EAAE;QACnB,mBAAmB,GAAG,CAAC,aAAa,EAAE;QACtC,WAAW,GAAG,CAAC,UAAU,EAAE;QAC3B,SAAS,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE;QAC5C,mBAAmB,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE;QACrF,EAAE;QACF,SAAS;QACT,0FAA0F;QAC1F,qEAAqE;QACrE,gGAAgG;QAChG,mIAAmI;QACnI,2HAA2H;QAC3H,2GAA2G;QAC3G,EAAE;QACF,yBAAyB;QACzB,GAAG,CAAC,MAAM;QACV,EAAE;QACF,gBAAgB;QAChB,YAAY;KACb,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC1F,CAAC"}

package/dist/run.d.ts

@@ -0,0 +1,2 @@
+import type { BridgeConfig, EffectiveRun, RunOptions } from "./types.js";
+export declare function buildEffectiveRun(config: BridgeConfig, options: RunOptions): EffectiveRun;

package/dist/run.js

@@ -0,0 +1,27 @@
+import { applyPolicy } from "./policy.js";
+import { readContextFiles } from "./context.js";
+export function buildEffectiveRun(config, options) {
+    const presetName = options.preset || config.defaults.preset;
+    const preset = config.presets[presetName];
+    if (!preset)
+        throw new Error(`Unknown preset: ${presetName}`);
+    const requestedMode = options.mode || config.defaults.mode;
+    const yolo = options.yolo || config.policy.yolo;
+    const decision = applyPolicy(requestedMode, config.policy, options.prompt, yolo);
+    return {
+        mode: decision.mode,
+        requestedMode: decision.requestedMode,
+        presetName,
+        preset,
+        prompt: options.prompt,
+        source: options.source || preset.source || config.defaults.source,
+        profile: options.profile || preset.profile || config.defaults.profile,
+        provider: options.provider || preset.provider,
+        model: options.model || preset.model,
+        maxTurns: options.maxTurns || preset.maxTurns || config.defaults.maxTurns,
+        yolo,
+        detectedRisks: decision.detectedRisks,
+        contextDocuments: readContextFiles(options.contextFiles),
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,UAAU,iBAAiB,CAAC,MAAoB,EAAE,OAAmB;IACzE,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,UAAU,EAAE,CAAC,CAAC;IAC9D,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC3D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;IAChD,MAAM,QAAQ,GAAG,WAAW,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAEjF,OAAO;QACL,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,aAAa,EAAE,QAAQ,CAAC,aAAa;QACrC,UAAU;QACV,MAAM;QACN,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM;QACjE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO;QACrE,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;QAC7C,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK;QACpC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ;QACzE,IAAI;QACJ,aAAa,EAAE,QAAQ,CAAC,aAAa;QACrC,gBAAgB,EAAE,gBAAgB,CAAC,OAAO,CAAC,YAAY,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/status.d.ts

@@ -0,0 +1,8 @@
+import type { BridgeConfig } from "./types.js";
+export interface StatusResult {
+    command: string;
+    available: boolean;
+    version?: string;
+    error?: string;
+}
+export declare function checkHermesStatus(config: BridgeConfig): StatusResult;

package/dist/status.js

@@ -0,0 +1,10 @@
+import { spawnSync } from "node:child_process";
+export function checkHermesStatus(config) {
+    const result = spawnSync(config.runtime.command, ["--version"], { encoding: "utf8" });
+    if (result.error)
+        return { command: config.runtime.command, available: false, error: result.error.message };
+    if (result.status !== 0)
+        return { command: config.runtime.command, available: false, error: result.stderr.trim() || `exit ${result.status}` };
+    return { command: config.runtime.command, available: true, version: result.stdout.trim() };
+}
+//# sourceMappingURL=status.js.map

package/dist/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAU/C,MAAM,UAAU,iBAAiB,CAAC,MAAoB;IACpD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACtF,IAAI,MAAM,CAAC,KAAK;QAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;IAC5G,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;IAC9I,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;AAC7F,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export declare const modes: readonly ["plan", "draft", "execute", "request-approval"];
+export type BridgeMode = (typeof modes)[number];
+export type RuntimeAdapter = "hermes-cli";
+export interface RuntimeConfig {
+    adapter: RuntimeAdapter;
+    command: string;
+}
+export interface PresetConfig {
+    description?: string | undefined;
+    skills: string[];
+    toolsets: string[];
+    provider?: string | undefined;
+    model?: string | undefined;
+    profile?: string | undefined;
+    maxTurns?: number | undefined;
+    source?: string | undefined;
+}
+export interface DefaultsConfig {
+    mode: BridgeMode;
+    profile?: string | undefined;
+    source: string;
+    maxTurns: number;
+    preset: string;
+}
+export type RiskCategory = "publish_external" | "send_message" | "send_email" | "delete" | "payment" | "git_push" | "credential_change";
+export interface PolicyConfig {
+    yolo: boolean;
+    requireApprovalFor: RiskCategory[];
+}
+export interface BridgeConfig {
+    runtime: RuntimeConfig;
+    defaults: DefaultsConfig;
+    presets: Record<string, PresetConfig>;
+    policy: PolicyConfig;
+}
+export interface RunOptions {
+    prompt: string;
+    mode?: BridgeMode | undefined;
+    preset?: string | undefined;
+    contextFiles: string[];
+    yolo: boolean;
+    dryRun: boolean;
+    json: boolean;
+    profile?: string | undefined;
+    provider?: string | undefined;
+    model?: string | undefined;
+    maxTurns?: number | undefined;
+    source?: string | undefined;
+}
+export interface ContextDocument {
+    path: string;
+    content: string;
+}
+export interface EffectiveRun {
+    mode: BridgeMode;
+    requestedMode: BridgeMode;
+    presetName: string;
+    preset: PresetConfig;
+    prompt: string;
+    source: string;
+    profile?: string | undefined;
+    provider?: string | undefined;
+    model?: string | undefined;
+    maxTurns: number;
+    yolo: boolean;
+    detectedRisks: RiskCategory[];
+    contextDocuments: ContextDocument[];
+}
+export interface AdapterResult {
+    ok: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    command: string[];
+    prompt: string;
+    dryRun: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export const modes = ["plan", "draft", "execute", "request-approval"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,kBAAkB,CAAU,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const version: string;

package/dist/version.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+function readVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export const version = readVersion();
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAMvC,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAgB,CAAC;QACzG,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,105 @@
+# Architecture
+
+Hermes Action Bridge is deliberately small. It does not try to become another automation platform.
+
+Its job is to let an external agent ask Hermes Agent to handle a task, while applying a local, configurable policy layer.
+
+```text
+Claude Code / Codex / Cursor / CI / shell
+        |
+        v
+hermes-action CLI or MCP server
+        |
+        v
+Hermes Agent CLI session
+        |
+        v
+Hermes skills, tools, browser automation, MCPs, cron jobs, messaging, APIs
+```
+
+## Core modules
+
+- `src/cli.ts`: command-line interface.
+- `src/config.ts`: YAML config loading and normalization.
+- `src/policy.ts`: risk detection and mode switching.
+- `src/prompt.ts`: prompt envelope sent to Hermes.
+- `src/context.ts`: context file loading with size guardrails.
+- `src/adapters/hermes-cli.ts`: Hermes CLI adapter.
+- `src/mcp-server.ts`: minimal MCP server.
+- `src/status.ts`: runtime availability check.
+- `src/version.ts`: single source of truth for the package version.
+- `src/doctor.ts`: environment checks for `hermes-action doctor`.
+
+## Native skills installer (`src/install/`)
+
+The `install` / `uninstall` commands install an open-standard `SKILL.md` for Claude Code (`~/.claude/skills/`) and Codex (`~/.codex/skills/`). The CLI remains the deterministic execution layer; the skill only tells the agent when to delegate.
+
+- `src/install/paths.ts`: cross-platform skill and instruction-file paths (injectable home/cwd).
+- `src/install/templates.ts`: single source for the `SKILL.md` body, project hint, and MCP snippets.
+- `src/install/managed-file.ts`: lock-based provenance for skill bundles (classify, atomic write, refuse-unmanaged).
+- `src/install/marker-block.ts`: fail-safe marker block for the optional `CLAUDE.md` / `AGENTS.md` hint.
+- `src/install/file-edit.ts`: shared read-edit-write helper used by the hint and the `.mcp.json` writer.
+- `src/install/mcp-config.ts`: MCP snippets and the Claude Code `.mcp.json` merge/unmerge writer.
+- `src/install/install-service.ts`: per-agent install/uninstall with failure isolation.
+
+Defaults are conservative: never modify `CLAUDE.md` / `AGENTS.md` without `--project-hint`, never overwrite a file the installer did not generate, and stay idempotent.
+
+## Config precedence
+
+The bridge merges config in this order:
+
+```text
+built-in defaults -> user config -> project config -> CLI flags
+```
+
+User config:
+
+```text
+~/.config/hermes-action/config.yaml
+```
+
+Project config:
+
+```text
+.hermes-action.yaml
+```
+
+## Modes
+
+The bridge does not decide how Hermes completes the task. It only labels the requested behavior:
+
+- `plan`: no side effects.
+- `draft`: produce an artifact, no external side effects.
+- `execute`: execute allowed actions.
+- `request-approval`: prepare the action and ask for approval.
+
+## Policy
+
+Policy is intentionally conservative and transparent.
+
+When a prompt contains risky intent and `mode=execute`, the bridge changes the effective mode to `request-approval` unless YOLO is enabled.
+
+The detected risks are included in the prompt envelope so Hermes knows why the mode changed.
+
+## YOLO
+
+YOLO is explicit and local:
+
+```bash
+hermes-action run --yolo --mode execute "..."
+```
+
+It bypasses the bridge policy only. Hermes Agent still enforces its own rules and any tool/provider/platform approval flow.
+
+## MCP design
+
+The MCP server exposes a small delegation surface instead of mirroring every Hermes tool.
+
+Tools:
+
+- `hermes_run`
+- `hermes_plan`
+- `hermes_presets`
+- `hermes_status`
+
+This keeps schema drift low and lets Hermes remain the action runtime.

package/docs/FUNCTIONAL-TESTS.md

@@ -0,0 +1,97 @@
+# Functional Testing
+
+This project has two validation layers.
+
+## Automated tests
+
+Run:
+
+```bash
+npm run check
+```
+
+This executes:
+
+- TypeScript build with `tsc`.
+- Vitest unit tests.
+- Functional CLI tests using a fake Hermes executable.
+
+The fake Hermes tests verify:
+
+- `hermes-action run` calls the configured Hermes command.
+- Skills and toolsets are passed as CLI flags.
+- Risky `execute` requests become `request-approval`.
+- `--yolo` passes through and keeps `execute` mode.
+- The prompt envelope contains mode, preset, YOLO state, detected risks, user request, and context.
+- A failed Hermes run is surfaced through the MCP server as an error result (`isError`).
+
+The installer tests verify (with injected home/cwd and temp `HOME`, no real agents required):
+
+- `install` / `uninstall` are idempotent and never touch `CLAUDE.md` / `AGENTS.md` by default.
+- `--dry-run` and `--print` write nothing; `--force` replaces a managed skill; a non-managed file is refused.
+- `--project-hint` adds and removes a marker block without losing existing content.
+- `--project` installs a project-local skill without creating the global one.
+- `install mcp --write` merges and `uninstall mcp --write` unmerges the project `.mcp.json`, preserving other servers.
+- `doctor` assembles its checks and JSON report, and `--probe` accepts the sentinel on stdout or stderr.
+- The shipped `examples/*/SKILL.md` match the installer template exactly (no drift).
+
+## Live Hermes smoke test
+
+Use a safe dry-run first:
+
+```bash
+npm run build
+node dist/cli.js run --dry-run --json "Return the word BRIDGE_OK only."
+```
+
+Then run a minimal real Hermes call if you intentionally want to spend provider tokens:
+
+```bash
+node dist/cli.js run \
+  --mode plan \
+  --max-turns 2 \
+  "Return the word BRIDGE_OK only. Do not use tools."
+```
+
+## Claude Code smoke test
+
+After `npm link`, ask Claude Code to run:
+
+```bash
+hermes-action run --dry-run --json "Return BRIDGE_OK only."
+```
+
+Expected result:
+
+- The command exits `0`.
+- The JSON output contains a `command` array starting with `hermes chat -Q`.
+- The prompt contains `Mode: plan`.
+
+## Codex smoke test
+
+After `npm link`, ask Codex to run:
+
+```bash
+hermes-action run --dry-run --json "Return BRIDGE_OK only."
+```
+
+Expected result is the same as Claude Code.
+
+## MCP smoke test
+
+Configure an MCP client with:
+
+```json
+{
+  "mcpServers": {
+    "hermes-action": {
+      "command": "hermes-action",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Call `hermes_status` first. It should report whether the configured Hermes command is available.
+
+Then call `hermes_run` with `dryRun: true` before making real Hermes calls.

package/examples/claude-code/CLAUDE.md

@@ -0,0 +1,21 @@
+# Claude Code: Hermes Action Bridge
+
+Install the native skill so Claude Code knows when to delegate real-world actions to Hermes:
+
+```bash
+hermes-action install claude-code
+```
+
+This writes `~/.claude/skills/hermes-action-bridge/SKILL.md`. Preview the exact content first with:
+
+```bash
+hermes-action install claude-code --print
+```
+
+To add a small marker-managed hint to this project's `CLAUDE.md` (instead of, or in addition to, the global skill):
+
+```bash
+hermes-action install claude-code --project-hint
+```
+
+The generated skill is shown in [SKILL.md](SKILL.md). Check your setup with `hermes-action doctor`. Remove everything with `hermes-action uninstall claude-code --project-hint`.

package/examples/claude-code/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: hermes-action-bridge
+description: Delegate external actions, Hermes skills, browser automation, messaging, cron jobs, and integrations to Hermes Agent through hermes-action. Use when a task needs capabilities outside the local coding session.
+---
+
+# Hermes Action Bridge
+
+Use this skill when a task needs capabilities outside the local coding session:
+Hermes skills or memory, messaging platforms, browser automation, scheduled or
+cron automation, external research, or any platform integration already
+configured in Hermes Agent.
+
+Do not reimplement those integrations here. Delegate them to Hermes through the
+`hermes-action` CLI.
+
+## When to use
+
+- The task requires a Hermes skill, tool, profile, or connected service.
+- The task needs a real-world action that is not local code editing.
+- The task needs research, messaging, browser, or scheduled automation Hermes owns.
+
+## Safe default
+
+Ask Hermes for a plan first; it has no side effects:
+
+```bash
+hermes-action run --mode plan "<describe what Hermes should do>"
+```
+
+## With context
+
+Write a concise handoff to a file and pass it explicitly:
+
+```bash
+hermes-action run --preset coding --context ./handoff.md "<request>"
+```
+
+## External side effects
+
+For public posts, outbound email or messages, deletes, payments, credential
+changes, or git pushes, require human approval:
+
+```bash
+hermes-action run --mode request-approval "<request requiring side effects>"
+```
+
+Never use `--yolo` unless the human explicitly asked for trusted local
+execution. It bypasses only the bridge policy, not Hermes' own safety rules.
+
+## Verify setup
+
+```bash
+hermes-action status
+hermes-action run --dry-run --json "Return BRIDGE_OK only."
+```

package/examples/codex/AGENTS.md

@@ -0,0 +1,21 @@
+# Codex: Hermes Action Bridge
+
+Install the native skill so Codex knows when to delegate real-world actions to Hermes:
+
+```bash
+hermes-action install codex
+```
+
+This writes `~/.codex/skills/hermes-action-bridge/SKILL.md`. Preview the exact content first with:
+
+```bash
+hermes-action install codex --print
+```
+
+To add a small marker-managed hint to this project's `AGENTS.md` (instead of, or in addition to, the global skill):
+
+```bash
+hermes-action install codex --project-hint
+```
+
+The generated skill is shown in [SKILL.md](SKILL.md). Check your setup with `hermes-action doctor`. Remove everything with `hermes-action uninstall codex --project-hint`.