@cotal-ai/connector-hermes 0.1.0

package/dist/hermes-hooks.js

@@ -0,0 +1,51 @@
+/** Last tool the turn started — so `waiting` (approval) and `working` can name what it's doing. */
+let pendingTool;
+/** A short, human-readable preview of a tool call: "name: most-salient-input". */
+function toolDetail(name, input) {
+    if (typeof name !== "string" || !name)
+        return undefined;
+    const i = (input ?? {});
+    const salient = i.command ?? i.file_path ?? i.path ?? i.url ?? i.query ?? i.description;
+    let detail = typeof salient === "string" && salient ? `${name}: ${salient}` : name;
+    if (detail.length > 200)
+        detail = `${detail.slice(0, 199)}…`;
+    return detail;
+}
+export const hermesHookHandle = async (agent, ev) => {
+    const event = String(ev.hook_event_name ?? "");
+    try {
+        switch (event) {
+            case "gateway_startup": // gateway up / adapter connected — present and free
+            case "on_session_start":
+                await agent.setStatus("idle");
+                return {};
+            case "pre_llm_call": // a turn is running the model
+                await agent.setStatus("working", pendingTool);
+                return {};
+            case "pre_tool_call": // record what it's about to run
+                pendingTool = toolDetail(ev.tool_name, ev.tool_input);
+                await agent.setStatus("working", pendingTool);
+                return {};
+            case "approval_wait": // Hermes asked for command approval — blocked on a human/peer
+                await agent.setStatus("waiting", typeof ev.detail === "string" ? ev.detail : pendingTool);
+                return {};
+            case "post_llm_call": // turn done
+            case "on_session_end":
+                pendingTool = undefined;
+                await agent.setStatus("idle");
+                // Now idle: if ambient messages were held while busy, ask the bridge to flush them.
+                if (agent.inboxCount() > 0)
+                    agent.requestWake();
+                return {};
+            case "gateway_shutdown":
+                await agent.setStatus("offline");
+                return {};
+            default:
+                return {};
+        }
+    }
+    catch {
+        return {}; // never block the gateway
+    }
+};
+//# sourceMappingURL=hermes-hooks.js.map

package/dist/hermes-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hermes-hooks.js","sourceRoot":"","sources":["../src/hermes-hooks.ts"],"names":[],"mappings":"AAcA,mGAAmG;AACnG,IAAI,WAA+B,CAAC;AAEpC,kFAAkF;AAClF,SAAS,UAAU,CAAC,IAAa,EAAE,KAAc;IAC/C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAC;IACnD,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,WAAW,CAAC;IACxF,IAAI,MAAM,GAAG,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACnF,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG;QAAE,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;IAC7D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAe,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;IAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;IAC/C,IAAI,CAAC;QACH,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,iBAAiB,CAAC,CAAC,oDAAoD;YAC5E,KAAK,kBAAkB;gBACrB,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;gBAC9B,OAAO,EAAE,CAAC;YACZ,KAAK,cAAc,EAAE,8BAA8B;gBACjD,MAAM,KAAK,CAAC,SAAS,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;gBAC9C,OAAO,EAAE,CAAC;YACZ,KAAK,eAAe,EAAE,gCAAgC;gBACpD,WAAW,GAAG,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC;gBACtD,MAAM,KAAK,CAAC,SAAS,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;gBAC9C,OAAO,EAAE,CAAC;YACZ,KAAK,eAAe,EAAE,8DAA8D;gBAClF,MAAM,KAAK,CAAC,SAAS,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;gBAC1F,OAAO,EAAE,CAAC;YACZ,KAAK,eAAe,CAAC,CAAC,YAAY;YAClC,KAAK,gBAAgB;gBACnB,WAAW,GAAG,SAAS,CAAC;gBACxB,MAAM,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;gBAC9B,oFAAoF;gBACpF,IAAI,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC;oBAAE,KAAK,CAAC,WAAW,EAAE,CAAC;gBAChD,OAAO,EAAE,CAAC;YACZ,KAAK,kBAAkB;gBACrB,MAAM,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;gBACjC,OAAO,EAAE,CAAC;YACZ;gBACE,OAAO,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC,CAAC,0BAA0B;IACvC,CAAC;AACH,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./extension.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./extension.js"; // self-registers the `hermes` connector on import
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC,CAAC,kDAAkD"}

package/dist/launch.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=launch.d.ts.map

package/dist/launch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.d.ts","sourceRoot":"","sources":["../src/launch.ts"],"names":[],"mappings":""}

package/dist/launch.js

@@ -0,0 +1,149 @@
+/**
+ * Hermes launcher / supervisor — the `hermes` connector's command (run from source via tsx).
+ *
+ * Hermes is a long-lived gateway daemon that creates a fresh `AIAgent` per inbound message, so the
+ * mesh endpoint must outlive every turn — it can't ride inside a per-turn MCP server the way it
+ * does for Claude Code / Codex. This process OWNS the single {@link MeshAgent} (via the shared
+ * {@link startSidecar}) and supervises `hermes gateway run` as its child:
+ *
+ *   - connector-core **control socket** ← Python presence hooks (relay.ts pattern) → presence
+ *   - **bridge socket** ⇄ Python gateway adapter + cotal_* tools (inbound wake/drive, outbound)
+ *   - **tools file** → the cotal_* descriptors the plugin registers at load
+ *   - an isolated **HERMES_HOME** profile so the operator's own ~/.hermes is never touched
+ *
+ * The manager runs this in a PTY; stdio is inherited so the gateway's output is what you attach to.
+ */
+import { spawn, execFileSync } from "node:child_process";
+import { mkdirSync, writeFileSync, cpSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadAgentFile } from "@cotal-ai/core";
+import { hasIdentity, configFromEnv, controlSocketPath } from "@cotal-ai/connector-core";
+import { startSidecar } from "./sidecar.js";
+/** Hermes API line this connector is written + pinned against (see pyproject.toml). A different
+ *  major.minor may move the plugin/platform/hook signatures, so we assert and fail loudly. */
+const HERMES_PIN = "0.16";
+const ILLEGAL = /[^A-Za-z0-9_-]/g;
+const tok = (s) => s.trim().replace(ILLEGAL, "_").slice(0, 40) || "_";
+/** This package's root (where pyproject.toml + plugin/ live), resolved from this source file. */
+const PKG_DIR = fileURLToPath(new URL("..", import.meta.url));
+const PLUGIN_SRC = join(PKG_DIR, "plugin", "cotal");
+function bridgeSocketPath(space, name) {
+    return join(tmpdir(), `cotal-hermes-bridge-${tok(space)}-${tok(name)}.sock`);
+}
+function log(msg) {
+    process.stderr.write(`[cotal-hermes] ${msg}\n`);
+}
+/** A double-quoted YAML basic-string literal (escaped). */
+const yamlStr = (s) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+/**
+ * Build the isolated Hermes profile (HERMES_HOME) so the operator's ~/.hermes is never touched.
+ * Drops the cotal plugin into the profile's plugins dir, enables it + the cotal platform, and
+ * turns approvals off (an autonomous spawned gateway has no human at the TUI to approve commands).
+ */
+function setupProfile(home, opts) {
+    mkdirSync(home, { recursive: true });
+    const pluginDst = join(home, "plugins", "cotal");
+    rmSync(pluginDst, { recursive: true, force: true });
+    mkdirSync(join(home, "plugins"), { recursive: true });
+    cpSync(PLUGIN_SRC, pluginDst, { recursive: true });
+    const lines = [
+        "# Cotal-managed Hermes profile — regenerated each launch; do not edit.",
+        "plugins:",
+        "  enabled: [cotal]",
+        "gateway:",
+        "  platforms:",
+        "    cotal:",
+        "      enabled: true",
+        "approvals:",
+        "  mode: off",
+    ];
+    if (opts.model)
+        lines.push(`model: ${yamlStr(opts.model)}`);
+    writeFileSync(join(home, "config.yaml"), lines.join("\n") + "\n");
+    // Persona → SOUL.md (Hermes' identity file) — the one place a system prompt can be set.
+    if (opts.persona)
+        writeFileSync(join(home, "SOUL.md"), opts.persona.trim() + "\n");
+}
+/** Assert the installed hermes-agent is on the pinned API line, or throw. No silent degrade: a
+ *  different major.minor can shift the plugin/platform/hook contract this connector depends on. */
+function assertHermesVersion() {
+    let raw;
+    try {
+        raw = execFileSync("uv", ["run", "--project", PKG_DIR, "--quiet", "python", "-c", "from importlib.metadata import version; print(version('hermes-agent'))"], { encoding: "utf8" }).trim();
+    }
+    catch (e) {
+        throw new Error(`could not resolve the hermes-agent version via uv — is uv installed and hermes-agent available? (${e.message})`);
+    }
+    const line = raw.split(".").slice(0, 2).join(".");
+    if (line !== HERMES_PIN)
+        throw new Error(`hermes-agent ${raw} is not on the pinned ${HERMES_PIN} line this connector targets — pin ${HERMES_PIN}.x or update src/launch.ts + pyproject.toml together`);
+    log(`hermes-agent ${raw} (pinned line ${HERMES_PIN}) ✓`);
+}
+async function main() {
+    // No identity → a plain run, not a launcher-spawned agent. Stay off the mesh.
+    if (!hasIdentity()) {
+        log("no COTAL_NAME — not a managed session; staying off the mesh");
+        process.exit(0);
+    }
+    const config = configFromEnv();
+    const home = join(tmpdir(), `cotal-hermes-${tok(config.space)}-${tok(config.name)}`);
+    const persona = process.env.COTAL_AGENT_FILE
+        ? loadAgentFile(process.env.COTAL_AGENT_FILE).persona
+        : undefined;
+    setupProfile(home, { model: process.env.HERMES_MODEL, persona });
+    // Paths shared by the sidecar and the gateway child — set in our env so startSidecar reads
+    // them, and forwarded verbatim to the child so the plugin connects to the same sockets/file.
+    const controlSock = controlSocketPath(config.space, config.name);
+    const bridgeSock = bridgeSocketPath(config.space, config.name);
+    const toolsFile = join(home, "cotal-tools.json");
+    process.env.COTAL_CONTROL_SOCKET = controlSock;
+    process.env.COTAL_BRIDGE_SOCKET = bridgeSock;
+    process.env.COTAL_TOOLS_FILE = toolsFile;
+    const sidecar = startSidecar();
+    // Fail loudly before we hand control to the gateway if the Hermes API line is wrong.
+    assertHermesVersion();
+    const childEnv = {
+        ...process.env,
+        HERMES_HOME: home,
+        COTAL_CONTROL_SOCKET: controlSock,
+        COTAL_BRIDGE_SOCKET: bridgeSock,
+        COTAL_TOOLS_FILE: toolsFile,
+    };
+    log(`launching hermes gateway as ${config.name}${config.role ? `/${config.role}` : ""} (HERMES_HOME=${home})`);
+    const child = spawn("uv", ["run", "--project", PKG_DIR, "hermes", "gateway", "run"], {
+        env: childEnv,
+        stdio: "inherit",
+    });
+    let shuttingDown = false;
+    const shutdown = async (code) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            await sidecar.stop();
+        }
+        finally {
+            process.exit(code);
+        }
+    };
+    child.on("exit", (code) => void shutdown(code ?? 0));
+    child.on("error", (e) => {
+        log(`failed to launch hermes gateway: ${e.message} — is uv (and hermes-agent) available?`);
+        void shutdown(1);
+    });
+    process.on("SIGINT", () => void shutdown(0));
+    process.on("SIGTERM", () => void shutdown(0));
+}
+main().catch((e) => {
+    log(`fatal: ${e.stack ?? String(e)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=launch.js.map

package/dist/launch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../src/launch.ts"],"names":[],"mappings":"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"}

package/dist/sidecar.d.ts

@@ -0,0 +1,10 @@
+import { MeshAgent, type AgentConfig } from "@cotal-ai/connector-core";
+export interface Sidecar {
+    agent: MeshAgent;
+    config: AgentConfig;
+    stop(): Promise<void>;
+}
+/** Start the mesh agent, the control + bridge servers, and emit the tool descriptors file.
+ *  Reads `COTAL_CONTROL_SOCKET`, `COTAL_BRIDGE_SOCKET`, and `COTAL_TOOLS_FILE` from the env. */
+export declare function startSidecar(): Sidecar;
+//# sourceMappingURL=sidecar.d.ts.map

package/dist/sidecar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.d.ts","sourceRoot":"","sources":["../src/sidecar.ts"],"names":[],"mappings":"AAgBA,OAAO,EAEL,SAAS,EAET,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAKlC,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAQD;gGACgG;AAChG,wBAAgB,YAAY,IAAI,OAAO,CAgCtC"}

package/dist/sidecar.js

@@ -0,0 +1,60 @@
+/**
+ * The Cotal mesh sidecar — the long-lived TypeScript half of the Hermes connector.
+ *
+ * It owns the single {@link MeshAgent} for the gateway's whole life (NATS, presence, the
+ * stream-backed inbox, attention modes, manager control) and exposes two local sockets the
+ * in-gateway Python plugin connects to:
+ *   - the connector-core **control socket** ← presence hooks (relay.ts pattern),
+ *   - the **bridge socket** ⇄ inbound push / outbound replies / cotal_* tool calls (bridge.ts).
+ * It also writes the generated tool descriptors to **`COTAL_TOOLS_FILE`** so the plugin can
+ * register the `cotal_*` tools synchronously at load, without blocking on the bridge.
+ *
+ * Both entrypoints reuse this: `launch.ts` (managed — also spawns `hermes gateway run` as a child)
+ * and `standalone.ts` (a user's own gateway spawns the bundled sidecar itself). Whoever spawns the
+ * sidecar sets the three socket/file env vars; we throw if any is missing (no silent fallback).
+ */
+import { writeFileSync } from "node:fs";
+import { configFromEnv, MeshAgent, startControlServer, } from "@cotal-ai/connector-core";
+import { hermesHookHandle } from "./hermes-hooks.js";
+import { startBridgeServer } from "./bridge.js";
+import { hermesToolDescriptors } from "./tool-schema.js";
+function need(name) {
+    const v = process.env[name];
+    if (!v)
+        throw new Error(`${name} not set — the sidecar must be spawned with bridge/control/tools paths`);
+    return v;
+}
+/** Start the mesh agent, the control + bridge servers, and emit the tool descriptors file.
+ *  Reads `COTAL_CONTROL_SOCKET`, `COTAL_BRIDGE_SOCKET`, and `COTAL_TOOLS_FILE` from the env. */
+export function startSidecar() {
+    const config = configFromEnv();
+    const agent = new MeshAgent(config);
+    agent.start(); // background connect with retry
+    const controlSock = need("COTAL_CONTROL_SOCKET");
+    const bridgeSock = need("COTAL_BRIDGE_SOCKET");
+    const toolsFile = need("COTAL_TOOLS_FILE");
+    const controlServer = startControlServer(agent, controlSock, hermesHookHandle);
+    const bridge = startBridgeServer(agent, config, bridgeSock);
+    // The plugin reads this at register(ctx) time to declare the cotal_* tools (full shared parity).
+    writeFileSync(toolsFile, JSON.stringify(hermesToolDescriptors(config)));
+    return {
+        agent,
+        config,
+        async stop() {
+            try {
+                bridge.close();
+            }
+            catch {
+                /* ignore */
+            }
+            try {
+                controlServer.close();
+            }
+            catch {
+                /* ignore */
+            }
+            await agent.stop();
+        },
+    };
+}
+//# sourceMappingURL=sidecar.js.map

package/dist/sidecar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar.js","sourceRoot":"","sources":["../src/sidecar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EACL,aAAa,EACb,SAAS,EACT,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAQzD,SAAS,IAAI,CAAC,IAAY;IACxB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,wEAAwE,CAAC,CAAC;IACzG,OAAO,CAAC,CAAC;AACX,CAAC;AAED;gGACgG;AAChG,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IACpC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,gCAAgC;IAE/C,MAAM,WAAW,GAAG,IAAI,CAAC,sBAAsB,CAAC,CAAC;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAE3C,MAAM,aAAa,GAAG,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,gBAAgB,CAAC,CAAC;IAC/E,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;IAE5D,iGAAiG;IACjG,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAExE,OAAO;QACL,KAAK;QACL,MAAM;QACN,KAAK,CAAC,IAAI;YACR,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YACD,IAAI,CAAC;gBACH,aAAa,CAAC,KAAK,EAAE,CAAC;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YACD,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/standalone.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=standalone.d.ts.map

package/dist/standalone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone.d.ts","sourceRoot":"","sources":["../src/standalone.ts"],"names":[],"mappings":""}

package/dist/standalone.js

@@ -0,0 +1,31 @@
+/**
+ * Standalone sidecar entry — bundled (esbuild → dist/standalone.cjs) and spawned by the Python
+ * plugin when a user runs their OWN Hermes (`hermes plugins install cotal-ai/<repo> --enable`).
+ *
+ * In that mode there is no Cotal launcher: the enabled plugin sees COTAL_SPACE / COTAL_NAME /
+ * COTAL_SERVERS but no bridge socket, so it derives the socket/file paths, sets them in the
+ * sidecar's env, and spawns this. We just bring up the mesh + bridge + control + tools file and
+ * stay alive for the gateway's lifetime — the gateway itself is already running around us, so
+ * (unlike launch.ts) we never spawn a `hermes` child.
+ */
+import { startSidecar } from "./sidecar.js";
+function log(msg) {
+    process.stderr.write(`[cotal-hermes/standalone] ${msg}\n`);
+}
+const sidecar = startSidecar();
+log(`mesh sidecar up for ${sidecar.config.name} in space ${sidecar.config.space}`);
+let stopping = false;
+const stop = async (code) => {
+    if (stopping)
+        return;
+    stopping = true;
+    try {
+        await sidecar.stop();
+    }
+    finally {
+        process.exit(code);
+    }
+};
+process.on("SIGINT", () => void stop(0));
+process.on("SIGTERM", () => void stop(0));
+//# sourceMappingURL=standalone.js.map

package/dist/standalone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone.js","sourceRoot":"","sources":["../src/standalone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,SAAS,GAAG,CAAC,GAAW;IACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,GAAG,IAAI,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,OAAO,GAAG,YAAY,EAAE,CAAC;AAC/B,GAAG,CAAC,uBAAuB,OAAO,CAAC,MAAM,CAAC,IAAI,aAAa,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;AAEnF,IAAI,QAAQ,GAAG,KAAK,CAAC;AACrB,MAAM,IAAI,GAAG,KAAK,EAAE,IAAY,EAAiB,EAAE;IACjD,IAAI,QAAQ;QAAE,OAAO;IACrB,QAAQ,GAAG,IAAI,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;AACH,CAAC,CAAC;AAEF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AACzC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/tool-schema.d.ts

@@ -0,0 +1,10 @@
+import { type AgentConfig } from "@cotal-ai/connector-core";
+/** A Hermes plugin tool: name + description + a JSON-Schema object for its parameters. */
+export interface HermesToolDescriptor {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** Build the Hermes tool descriptors for a given agent config (rendered from the shared specs). */
+export declare function hermesToolDescriptors(config: AgentConfig): HermesToolDescriptor[];
+//# sourceMappingURL=tool-schema.d.ts.map

package/dist/tool-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.d.ts","sourceRoot":"","sources":["../src/tool-schema.ts"],"names":[],"mappings":"AAaA,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5E,0FAA0F;AAC1F,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAYD,mGAAmG;AACnG,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,WAAW,GAAG,oBAAoB,EAAE,CAUjF"}

package/dist/tool-schema.js

@@ -0,0 +1,34 @@
+/**
+ * Render the shared Cotal tool surface as Hermes plugin-tool descriptors.
+ *
+ * One source of truth: {@link cotalToolSpecs} (connector-core). We do NOT hand-write the Hermes
+ * tool list — we generate `{name, description, parameters}` from each spec (Zod raw shape →
+ * JSON Schema via Zod 4's `toJSONSchema`) so a Hermes peer gets exactly the same `cotal_*`
+ * surface as Claude Code / OpenCode, and `parity.smoke.ts` fails if the two ever drift.
+ *
+ * The descriptors are written to a file the launcher hands the gateway (`COTAL_TOOLS_FILE`); the
+ * Python plugin reads it at `register(ctx)` time so tool registration stays synchronous and never
+ * has to block on the bridge. Tool *calls* still ride the bridge at runtime.
+ */
+import { z } from "zod";
+import { cotalToolSpecs } from "@cotal-ai/connector-core";
+const EMPTY_PARAMS = { type: "object", properties: {}, required: [] };
+/** cotal_inbox is read-only under a driven connector: this connector surfaces each batch into a
+ *  turn and acks on completion, so the agent's inbox tool must PEEK, never drain (a drain would
+ *  race the connector's ack). Mirror the OpenCode connector's read-only framing. */
+const READONLY_INBOX_DESCRIPTION = "Show the peer messages currently waiting for you (incl. focus-mode recall). You don't normally " +
+    "need this — peer messages are delivered into your turns automatically; use it to re-check " +
+    "what's pending mid-task. Read-only: it never consumes them.";
+/** Build the Hermes tool descriptors for a given agent config (rendered from the shared specs). */
+export function hermesToolDescriptors(config) {
+    return cotalToolSpecs(config, "hermes").map((spec) => {
+        if (spec.name === "cotal_inbox") {
+            return { name: spec.name, description: READONLY_INBOX_DESCRIPTION, parameters: EMPTY_PARAMS };
+        }
+        const parameters = spec.schema
+            ? z.toJSONSchema(z.object(spec.schema))
+            : EMPTY_PARAMS;
+        return { name: spec.name, description: spec.description, parameters };
+    });
+}
+//# sourceMappingURL=tool-schema.js.map

package/dist/tool-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.js","sourceRoot":"","sources":["../src/tool-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAoB,MAAM,0BAA0B,CAAC;AAS5E,MAAM,YAAY,GAA4B,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAE/F;;oFAEoF;AACpF,MAAM,0BAA0B,GAC9B,iGAAiG;IACjG,4FAA4F;IAC5F,6DAA6D,CAAC;AAEhE,mGAAmG;AACnG,MAAM,UAAU,qBAAqB,CAAC,MAAmB;IACvD,OAAO,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACnD,IAAI,IAAI,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YAChC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,0BAA0B,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;QAChG,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM;YAC5B,CAAC,CAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAA6B;YACpE,CAAC,CAAC,YAAY,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@cotal-ai/connector-hermes",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Cotal-AI/Cotal.git",
+    "directory": "extensions/connector-hermes"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "connector-hermes": "./bin/install.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "tsx": "^4.22.4",
+    "zod": "^4.4.3",
+    "@cotal-ai/connector-core": "0.2.0"
+  },
+  "peerDependencies": {
+    "@cotal-ai/core": "0.1.3"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "@cotal-ai/core": "0.1.3"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "plugin/cotal/*.py",
+    "plugin/cotal/plugin.yaml",
+    "plugin/cotal/_sidecar",
+    "pyproject.toml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx tool-parity.smoke.ts",
+    "build": "tsc -p tsconfig.json && pnpm run bundle",
+    "bundle": "esbuild src/standalone.ts --bundle --platform=node --format=cjs --target=node20 --outfile=plugin/cotal/_sidecar/standalone.cjs"
+  }
+}

package/plugin/cotal/__init__.py

@@ -0,0 +1,148 @@
+"""Cotal plugin for Hermes — joins the gateway to the Cotal mesh.
+
+Registers three things on the Hermes plugin context:
+  - a **gateway platform adapter** (``cotal``) — inbound wake/drive + outbound reply routing,
+  - **lifecycle hooks** → Cotal presence (over connector-core's control socket),
+  - the **cotal_* tools** — proactive mesh actions for the agent (full shared parity).
+
+All three talk to the TS sidecar (which owns the mesh endpoint) over the sockets the launcher set
+in the environment. Two run modes:
+  - **Managed** — the Cotal launcher spawns this gateway with COTAL_BRIDGE_SOCKET (and the control
+    socket + tools file) already set; we just register against them.
+  - **Standalone** — a user's own ``hermes`` with the plugin installed: COTAL_SPACE / COTAL_NAME /
+    COTAL_SERVERS are set but no bridge socket, so we spawn the bundled sidecar ourselves, derive
+    the socket/file paths, and register against those.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+from . import hooks
+from .tools import register_tools
+
+
+def _is_managed() -> bool:
+    """Managed launches preset the bridge socket; its presence means the sidecar already exists."""
+    return bool(os.environ.get("COTAL_BRIDGE_SOCKET"))
+
+
+def _have_identity() -> bool:
+    """Mirror core's hasIdentity: a name, a join link, or an agent file is the explicit opt-in.
+    A COTAL_LINK (cotal://token@host/space) carries space + server + auth on its own, so a peer
+    can join with just the link (+ an optional COTAL_NAME)."""
+    return bool(
+        os.environ.get("COTAL_NAME")
+        or os.environ.get("COTAL_LINK")
+        or os.environ.get("COTAL_AGENT_FILE")
+    )
+
+
+def _check_requirements() -> bool:
+    """Enable the cotal platform when we can reach (or bootstrap) a sidecar: a preset bridge socket
+    (managed) or enough identity to spawn one (standalone)."""
+    return _is_managed() or _have_identity()
+
+
+def _resolve_sidecar_js() -> Path:
+    """Locate the bundled standalone sidecar (esbuild → cotal/_sidecar/standalone.cjs). Honors an
+    explicit COTAL_SIDECAR_JS override; otherwise resolves it relative to THIS plugin dir. The
+    bundle ships inside the plugin dir on purpose, so it travels with the plugin in every layout
+    (monorepo, managed copy into HERMES_HOME, `hermes plugins install`, npm). Throws if absent —
+    no silent fallback."""
+    override = os.environ.get("COTAL_SIDECAR_JS")
+    if override:
+        p = Path(override)
+        if not p.is_file():
+            raise RuntimeError(f"COTAL_SIDECAR_JS={override} does not exist")
+        return p
+    candidate = Path(__file__).resolve().parent / "_sidecar" / "standalone.cjs"
+    if not candidate.is_file():
+        raise RuntimeError(
+            f"bundled sidecar not found at {candidate} — build the connector (pnpm build) or set "
+            "COTAL_SIDECAR_JS"
+        )
+    return candidate
+
+
+def _bootstrap_standalone_sidecar() -> None:
+    """Standalone mode: spawn the bundled Node sidecar and wait until it has published the bridge
+    socket + tools file. Sets the three path env vars first so the sidecar and the rest of this
+    registration agree on them."""
+    run_dir = Path(tempfile.mkdtemp(prefix="cotal-hermes-"))
+    # Identity may come entirely from COTAL_LINK (which carries the space), so neither of these is
+    # guaranteed — they're only used for the readiness error below.
+    name = os.environ.get("COTAL_NAME") or "hermes"
+    space = os.environ.get("COTAL_SPACE") or "(from COTAL_LINK)"
+    os.environ.setdefault("COTAL_BRIDGE_SOCKET", str(run_dir / "bridge.sock"))
+    os.environ.setdefault("COTAL_CONTROL_SOCKET", str(run_dir / "control.sock"))
+    os.environ.setdefault("COTAL_TOOLS_FILE", str(run_dir / "cotal-tools.json"))
+
+    sidecar = _resolve_sidecar_js()
+    subprocess.Popen(  # noqa: S603 — trusted bundled asset
+        ["node", str(sidecar)],
+        env=os.environ.copy(),
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+    # Wait for the sidecar to be ready (tools file written + bridge socket bound). Fail loudly.
+    tools_file = Path(os.environ["COTAL_TOOLS_FILE"])
+    bridge_sock = Path(os.environ["COTAL_BRIDGE_SOCKET"])
+    deadline = time.monotonic() + 20.0
+    while time.monotonic() < deadline:
+        if tools_file.is_file() and bridge_sock.exists():
+            return
+        time.sleep(0.1)
+    raise RuntimeError(
+        f"cotal sidecar did not come up within 20s for {name}@{space} "
+        f"(tools={tools_file.is_file()}, bridge={bridge_sock.exists()})"
+    )
+
+
+def register(ctx: Any) -> None:
+    if not _is_managed():
+        if not _have_identity():
+            return  # not a cotal gateway — nothing to wire up
+        _bootstrap_standalone_sidecar()
+
+    # Gateway platform adapter (imported lazily so a non-gateway context still loads tools/hooks).
+    from .adapter import CotalAdapter
+
+    # Cotal mesh peers are already authorized by the NATS JWT, and an autonomous gateway has no
+    # operator to approve a pairing code or pick a home channel — both are first-contact gateway
+    # prompts that would otherwise intercept a peer's first message. Suppress them for the cotal
+    # platform ONLY (per-platform allow-all + a sentinel home channel), so a standalone user's
+    # other platforms (Telegram, …) keep their own access control.
+    os.environ.setdefault("COTAL_ALLOW_ALL_USERS", "true")
+    os.environ.setdefault("COTAL_HOME_CHANNEL", "mesh")
+
+    ctx.register_platform(
+        name="cotal",
+        label="Cotal",
+        adapter_factory=lambda cfg: CotalAdapter(cfg),
+        check_fn=_check_requirements,
+        allowed_users_env="COTAL_ALLOWED_USERS",
+        allow_all_env="COTAL_ALLOW_ALL_USERS",
+        platform_hint=(
+            "You are coordinating with peer agents on the Cotal mesh. Your reply is delivered "
+            "automatically back to whoever messaged you; use cotal_* tools only to reach OTHER "
+            "peers/channels or report status."
+        ),
+        emoji="🔗",
+        max_message_length=8000,
+    )
+
+    # Lifecycle hooks → presence.
+    ctx.register_hook("on_session_start", hooks.on_session_start)
+    ctx.register_hook("pre_llm_call", hooks.pre_llm_call)
+    ctx.register_hook("pre_tool_call", hooks.pre_tool_call)
+    ctx.register_hook("post_llm_call", hooks.post_llm_call)
+    ctx.register_hook("on_session_end", hooks.on_session_end)
+
+    # Proactive mesh tools (declared from the descriptors the sidecar wrote to COTAL_TOOLS_FILE).
+    register_tools(ctx)