borgmcp 5.6.0 → 5.7.0

package/hermes-plugin/borg-representative-push/plugin.yaml

@@ -0,0 +1,39 @@
+name: borg-representative-push
+version: 1.0.0
+manifest_version: 2
+api_version: 1
+description: >-
+  Wakes one Hermes gateway conversation when the bound Borg Coordinator replies
+  to the human representative. Supervises `borg representative listen` inside
+  the messaging gateway and injects a fixed, body-free prompt; reply content is
+  only ever fetched by the conversation through borg_representative-read.
+license: Apache-2.0
+homepage: https://github.com/Byte-Ventures/borg-mcp-client
+tags: [borg, gateway, representative]
+# Hooks are registered only when the settings below are valid (a post_tool_call
+# observer for the deliver tool), so none is declared unconditionally here.
+config_schema:
+  session_key:
+    type: str
+    required: true
+    description: Gateway session key of the conversation to wake, e.g. agent:main:telegram:dm:<chat id>.
+  worktree:
+    type: str
+    required: true
+    description: Absolute path of the prepared representative worktree.
+  borg_command:
+    type: str
+    default: borg
+    description: The borg executable (borgmcp >= 5.6.0).
+  mcp_server:
+    type: str
+    default: borg-representative
+    description: Name of the mcp_servers entry that runs `borg representative mcp`.
+  reinject_after_s:
+    type: int
+    default: 600
+    description: Seconds before an undelivered reply wakes the conversation again.
+  max_reinjects:
+    type: int
+    default: 3
+    description: Maximum repeat wakes for one undelivered reply.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "5.6.0",
+  "version": "5.7.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,6 +45,8 @@
     "dist",
     "src",
     "docs/*.md",
+    "hermes-plugin/borg-representative-push/plugin.yaml",
+    "hermes-plugin/borg-representative-push/__init__.py",
     "README.md",
     "LICENSE",
     "NOTICE",

package/src/claude.ts

@@ -404,6 +404,10 @@ async function main() {
       process.stderr.write(`Run \`borg representative --help\` for usage.\n`);
       process.exit(1);
     }
+    if (parsed.command.action === 'hermes-plugin-install') {
+      const install = await import('./hermes-plugin-install.js');
+      process.exit(await install.runHermesPluginInstall(parsed.command, install.defaultHermesPluginInstallDeps()));
+    }
     const deps = await representative.buildDefaultRepresentativeDeps();
     if (parsed.command.action === 'prepare') {
       process.exit(await representative.runRepresentativePrepare(parsed.command, deps));

package/src/cli-help.ts

@@ -130,6 +130,7 @@ export function representativeHelpText(version: string): string {
     `  borg representative status [--worktree <path>]\n` +
     `  borg representative mcp [--worktree <path>]\n` +
     `  borg representative listen --worktree <path> [--replay-after <entry_id>]\n` +
+    `  borg representative hermes-plugin install [--hermes-home <path>] [--force]\n` +
     `  borg representative --help\n\n` +
     `Commands:\n` +
     `  prepare   Create or resume the representative's own drone in this repository's cube and bind it to\n` +
@@ -138,7 +139,11 @@ export function representativeHelpText(version: string): string {
     `            another drone is never chosen instead.\n` +
     `  status    Show the saved binding, re-check it against the live cube, and list unresolved sends.\n` +
     `  mcp       Serve the restricted stdio MCP tools (status, send, read, deliver, ack) for a generic MCP host.\n` +
-    `  listen    Emit body-free JSON wake hints from the server stream; supervise this separate process.\n\n` +
+    `  listen    Emit body-free JSON wake hints from the server stream; supervise this separate process.\n` +
+    `  hermes-plugin install\n` +
+    `            Copy the Borg-owned Hermes push plugin into <Hermes home>/plugins and print the config to add.\n` +
+    `            It wakes one Hermes messaging-gateway conversation (not a Desktop chat). Never edits Hermes\n` +
+    `            config and never starts or restarts Hermes.\n\n` +
     `Options:\n` +
     `  --replay-after <entry_id>    listen: replay later retained hints after the last durably enqueued entry\n` +
     `  --coordinator <drone-label>  Exact label of the Coordinator drone (see \`borg drones\`). Required for prepare.\n` +
@@ -147,6 +152,8 @@ export function representativeHelpText(version: string): string {
     `  --worktree <path>            status/mcp/listen: absolute path of the prepared representative worktree\n` +
     `  --host <host>                prepare: explicit Borg server, as in \`borg assimilate --host\`\n` +
     `  --rebind                     prepare: explicitly replace the saved cube/Coordinator selection\n` +
+    `  --hermes-home <path>         hermes-plugin install: absolute Hermes home (default: $HERMES_HOME or ~/.hermes)\n` +
+    `  --force                      hermes-plugin install: replace the files of an existing install\n` +
     `  --help, -h                   Show this help\n\n` +
     `Limits: the MCP process has no background wake; a separate listen process emits wake hints, not content.\n` +
     `Reading changes nothing: persist replies durably, then deliver through the last one. On a listener gap, call read.\n` +
@@ -233,7 +240,7 @@ export function topLevelHelpText(version: string): string {
     `  borg drones              List this machine's registered drones and worktrees\n` +
     `  borg launch <drone-label-or-id-prefix>  Reopen one registered drone from its worktree\n` +
     `  borg launch-all [cube]   Launch all drone worktrees of a cube (default: active cube)\n` +
-    `  borg representative prepare|status|mcp|listen  Let an MCP host (e.g. Hermes) speak for you to one Coordinator drone\n` +
+    `  borg representative prepare|status|mcp|listen|hermes-plugin  Let an MCP host (e.g. Hermes) speak for you to one Coordinator drone\n` +
     `  borg server <command> [arguments]\n` +
     `  borg --cli claude|codex|opencode  Launch that agent CLI directly\n` +
     `  borg --version           Show installed version\n\n` +

package/src/hermes-plugin-install.ts

@@ -0,0 +1,147 @@
+/**
+ * `borg representative hermes-plugin install`: copy the Borg-owned Hermes push
+ * plugin (hermes-plugin/borg-representative-push) into <Hermes home>/plugins.
+ *
+ * It only places the plugin's own files. It never edits Hermes config, never
+ * enables the plugin and never starts or restarts Hermes: the operator does
+ * those steps from the printed snippet.
+ */
+import { lstat, mkdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const HERMES_PLUGIN_NAME = 'borg-representative-push';
+/** Exactly the shipped files; nothing else in the source directory is copied. */
+export const HERMES_PLUGIN_FILES = ['plugin.yaml', '__init__.py'] as const;
+
+export interface HermesPluginInstallDeps {
+  env: NodeJS.ProcessEnv;
+  homedir(): string;
+  /** Directory holding the packaged plugin files. */
+  sourceDir: string;
+  stdout(text: string): void;
+  stderr(text: string): void;
+}
+
+export function packagedHermesPluginDir(): string {
+  return fileURLToPath(new URL(`../hermes-plugin/${HERMES_PLUGIN_NAME}/`, import.meta.url));
+}
+
+export function defaultHermesPluginInstallDeps(): HermesPluginInstallDeps {
+  return {
+    env: process.env,
+    homedir,
+    sourceDir: packagedHermesPluginDir(),
+    stdout: (text) => { process.stdout.write(text); },
+    stderr: (text) => { process.stderr.write(text); },
+  };
+}
+
+class InstallRefused extends Error {}
+
+function errnoCode(error: unknown): string | undefined {
+  return (error as NodeJS.ErrnoException | undefined)?.code;
+}
+
+async function lstatOrNull(path: string) {
+  try {
+    return await lstat(path);
+  } catch (error) {
+    if (errnoCode(error) === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export function hermesPluginConfigSnippet(): string {
+  return (
+    `plugins:\n` +
+    `  enabled:\n` +
+    `    - ${HERMES_PLUGIN_NAME}\n` +
+    `  entries:\n` +
+    `    ${HERMES_PLUGIN_NAME}:\n` +
+    `      allow_gateway_injection: true\n` +
+    `      settings:\n` +
+    `        session_key: "agent:main:<platform>:<chat type>:<chat id>"  # the gateway conversation to wake\n` +
+    `        worktree: "<absolute path of the prepared representative worktree>"\n` +
+    `mcp_servers:\n` +
+    `  borg-representative:\n` +
+    `    command: borg\n` +
+    `    args: ["representative", "mcp", "--worktree", "<same absolute worktree path>"]\n` +
+    `    lazy: true\n`
+  );
+}
+
+export async function runHermesPluginInstall(
+  command: { hermesHome?: string; force: boolean },
+  deps: HermesPluginInstallDeps,
+): Promise<number> {
+  try {
+    const home = command.hermesHome ?? (deps.env.HERMES_HOME || join(deps.homedir(), '.hermes'));
+    if (!isAbsolute(home)) throw new InstallRefused(`The Hermes home must be an absolute path: ${home}`);
+    const homeStat = await stat(home).catch(() => null);
+    if (!homeStat?.isDirectory()) {
+      throw new InstallRefused(`No Hermes home at ${home}. Install Hermes first, or pass --hermes-home <path>.`);
+    }
+
+    const sources = await Promise.all(HERMES_PLUGIN_FILES.map(async (name) => {
+      try {
+        return { name, content: await readFile(join(deps.sourceDir, name)) };
+      } catch {
+        throw new InstallRefused(`The packaged plugin file ${name} is missing from ${deps.sourceDir}; reinstall borgmcp.`);
+      }
+    }));
+
+    const pluginsDir = join(home, 'plugins');
+    const pluginsStat = await stat(pluginsDir).catch((error: unknown) => {
+      if (errnoCode(error) === 'ENOENT') return null;
+      throw error;
+    });
+    if (pluginsStat && !pluginsStat.isDirectory()) throw new InstallRefused(`${pluginsDir} is not a directory.`);
+    if (!pluginsStat) await mkdir(pluginsDir, { mode: 0o755 });
+
+    const target = join(pluginsDir, HERMES_PLUGIN_NAME);
+    const existing = await lstatOrNull(target);
+    if (existing?.isSymbolicLink()) {
+      throw new InstallRefused(`${target} is a symbolic link; remove it yourself before installing.`);
+    }
+    if (existing && !existing.isDirectory()) throw new InstallRefused(`${target} exists and is not a directory.`);
+    if (existing && !command.force) {
+      throw new InstallRefused(`${target} already exists. Pass --force to replace the plugin's files.`);
+    }
+    if (!existing) await mkdir(target, { mode: 0o755 });
+
+    for (const { name, content } of sources) {
+      const destination = join(target, name);
+      const temporary = join(target, `.${name}.${process.pid}.tmp`);
+      // 'wx' refuses to follow or reuse anything already at the temporary path.
+      await writeFile(temporary, content, { mode: 0o644, flag: 'wx' });
+      try {
+        await rename(temporary, destination);
+      } catch (error) {
+        await unlink(temporary).catch(() => {});
+        throw error;
+      }
+    }
+
+    deps.stdout(
+      `${existing ? 'Replaced' : 'Installed'} the Hermes plugin ${HERMES_PLUGIN_NAME} in ${target}.\n\n` +
+      `Hermes config was not changed. Add the following to ${join(home, 'config.yaml')}\n` +
+      `(\`hermes plugins enable ${HERMES_PLUGIN_NAME}\` covers the enabled list only):\n\n` +
+      hermesPluginConfigSnippet() +
+      `\nThen:\n` +
+      `- session_key must name a messaging-gateway conversation (for example your Telegram DM). A Hermes\n` +
+      `  Desktop chat cannot be woken: Hermes injects plugin messages only into gateway conversations.\n` +
+      `- Only one process may use the representative tools. With lazy: true, run \`hermes tools\` and disable\n` +
+      `  the mcp-borg-representative toolset on every platform except the one in session_key (Desktop and CLI\n` +
+      `  included). If Desktop already holds the tools lease, restart the Desktop backend once.\n` +
+      `- Restart the gateway (\`hermes gateway restart\`) so it loads the plugin.\n` +
+      `Details: docs/HUMAN_REPRESENTATIVE.md, section "Hermes push plugin".\n`,
+    );
+    return 0;
+  } catch (error) {
+    const message = error instanceof InstallRefused ? error.message : `Install failed: ${error instanceof Error ? error.message : String(error)}`;
+    deps.stderr(`${message}\n`);
+    return 1;
+  }
+}

package/src/representative-cmd.ts

@@ -43,7 +43,8 @@ export type RepresentativeCommand =
   | { action: 'prepare'; coordinator: string; role: string; rebind: boolean; worktreeName?: string; host?: string }
   | { action: 'status'; worktree?: string }
   | { action: 'mcp'; worktree?: string }
-  | { action: 'listen'; worktree?: string; replayAfter?: string };
+  | { action: 'listen'; worktree?: string; replayAfter?: string }
+  | { action: 'hermes-plugin-install'; hermesHome?: string; force: boolean };
 
 export type ParsedRepresentativeArgs =
   | { ok: true; command: RepresentativeCommand }
@@ -64,8 +65,9 @@ export interface RepresentativeCmdDeps {
 
 export function parseRepresentativeArgs(args: readonly string[]): ParsedRepresentativeArgs {
   const [action, ...rest] = args;
+  if (action === 'hermes-plugin') return parseHermesPluginArgs(rest);
   if (action !== 'prepare' && action !== 'status' && action !== 'mcp' && action !== 'listen') {
-    return { ok: false, error: 'expected one of: prepare, status, mcp, listen' };
+    return { ok: false, error: 'expected one of: prepare, status, mcp, listen, hermes-plugin' };
   }
   const values: Record<string, string> = {};
   let rebind = false;
@@ -124,6 +126,30 @@ export function parseRepresentativeArgs(args: readonly string[]): ParsedRepresen
   };
 }
 
+function parseHermesPluginArgs(args: readonly string[]): ParsedRepresentativeArgs {
+  const [subcommand, ...rest] = args;
+  if (subcommand !== 'install') return { ok: false, error: 'expected: hermes-plugin install [--hermes-home <path>] [--force]' };
+  let hermesHome: string | undefined;
+  let force = false;
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i];
+    if (arg === '--force') {
+      force = true;
+    } else if (arg === '--hermes-home') {
+      const next = rest[i + 1];
+      if (typeof next !== 'string' || next.length === 0 || next.startsWith('-')) {
+        return { ok: false, error: '--hermes-home requires a value' };
+      }
+      if (!isAbsolute(next)) return { ok: false, error: '--hermes-home must be an absolute path' };
+      hermesHome = next;
+      i += 1;
+    } else {
+      return { ok: false, error: `unknown argument: ${arg}. Supported: --hermes-home, --force` };
+    }
+  }
+  return { ok: true, command: { action: 'hermes-plugin-install', force, ...(hermesHome ? { hermesHome } : {}) } };
+}
+
 function canonicalWorktree(path: string, deps: Pick<RepresentativeCmdDeps, 'findProjectRoot'>): string {
   let real = resolve(path);
   try {