totemlayer 0.1.96 → 0.1.115

package/bin/native-claude-receiver.mjs

@@ -0,0 +1,272 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { localClientEnvironment } from "./platform-client.mjs";
+import { installNativeInboxReceiver } from "./native-inbox-installation.mjs";
+import { runNativeInboxReceiver } from "./native-inbox-receiver.mjs";
+import { unwrapNativeMcp } from "./native-mcp-source.mjs";
+import { privateRead } from "./runtime-installation.mjs";
+import { acquireSupervisorLock } from "./runtime-lock.mjs";
+
+const fail = suffix => Object.assign(new Error(suffix), { code: "NATIVE_CLAUDE_" + suffix });
+const digest = value => createHash("sha256").update(value).digest("hex");
+const absolute = value => typeof value === "string" && isAbsolute(value) && !/[\0\r\n]/.test(value);
+const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const hash = /^[a-f0-9]{64}$/;
+const watchdog = fileURLToPath(new URL("./native-cli-process.py", import.meta.url));
+const checkers = ["totem_get_identity", "totem_start_listener", "totem_listen",
+  "totem_list_messages", "totem_list_chat_commands", "totem_get_chat", "totem_get_conversation", "totem_get_activity"];
+const peerTools = ["totem_get_identity", "totem_list_messages", "totem_get_conversation",
+  "totem_get_message", "totem_reply_to_message", "totem_acknowledge_message"];
+const ownerTools = ["totem_get_identity", "totem_get_chat", "totem_claim_chat_command",
+  "totem_renew_chat_command", "totem_complete_chat_command"];
+
+function nativeEnvironment(environment) {
+  const env = localClientEnvironment(environment, {
+    TERM: "dumb", DO_NOT_TRACK: "1", DISABLE_AUTOUPDATER: "1",
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1", CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1",
+    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1", CLAUDE_CODE_DISABLE_ORG_MEMORY: "1",
+    CLAUDE_CODE_DISABLE_CLAUDE_CODE_SKILL: "1", CLAUDE_CODE_DISABLE_CLAUDE_API_SKILL: "1",
+  });
+  for (const key of Object.keys(env))
+    if (/^(TOTEM|AGENTTRUST)_|^(OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN|CLAUDE_CONFIG_DIR)$/i.test(key)) delete env[key];
+  return env;
+}
+
+export async function inspectClaudeMcp(binding) {
+  if (!absolute(binding?.configPath) || !absolute(binding.cwd) || !uuid.test(binding.agentId ?? "") ||
+    !["PRODUCTION", "SANDBOX"].includes(binding.environment) ||
+    !/^[a-zA-Z0-9_-]{1,64}$/.test(binding.serverName ?? "") || !hash.test(binding.serverFingerprint ?? ""))
+    throw fail("MCP_BINDING_INVALID");
+  const config = await privateRead(binding.configPath);
+  const entries = Object.entries(config.mcpServers ?? {});
+  const [name, server] = entries[0] ?? [];
+  if (entries.length !== 1 || name !== binding.serverName ||
+    !absolute(server?.command) || !Array.isArray(server.args) ||
+    server.args.some(arg => typeof arg !== "string" || /[\0\r\n]|tn_(live|test)_|Bearer\s/i.test(arg)) ||
+    (server.type && server.type !== "stdio") ||
+    Object.entries(server.env ?? {}).some(([key, value]) =>
+      !/^(TOTEM_CONFIG_DIR|TOTEM_BASE_URL|TOTEM_NETWORK_API_KEY_FILE|TOTEM_EXPECTED_AGENT_ID|TOTEM_EXPECTED_ENVIRONMENT|TOTEM_AUTO_START|TOTEM_AUTO_UPDATE|HOME|PATH)$/.test(key) ||
+      typeof value !== "string" || /[\0\r\n]|tn_(live|test)_|Bearer\s/i.test(value)) ||
+    server.env?.TOTEM_AUTO_START !== "0" || server.env?.TOTEM_AUTO_UPDATE !== "0" ||
+    (server.env.TOTEM_EXPECTED_AGENT_ID && server.env.TOTEM_EXPECTED_AGENT_ID !== binding.agentId) ||
+    (server.env.TOTEM_EXPECTED_ENVIRONMENT && server.env.TOTEM_EXPECTED_ENVIRONMENT !== binding.environment) ||
+    digest(JSON.stringify(config)) !== binding.serverFingerprint)
+    throw fail("MCP_CONFIG_CHANGED");
+  return server;
+}
+
+export function createClaudeNativeBridge(binding, options = {}) {
+  if (binding?.kind !== "claude" || binding.dedicated !== true || binding.provider !== "firstParty" ||
+    !uuid.test(binding.sessionId ?? "") || !hash.test(binding.accountFingerprint ?? "") ||
+    !/^claude-[a-z0-9.-]{1,95}$/.test(binding.model ?? "") || !/^2\.\d+\.\d+$/.test(binding.nativeVersion ?? "") ||
+    ![binding.binary, binding.python, binding.cwd].every(absolute) || binding.permissionMode !== "dontAsk" ||
+    binding.mcp?.cwd !== binding.cwd) throw fail("BINDING_INVALID");
+  const saved = structuredClone(binding);
+  const env = nativeEnvironment(options.env ?? process.env);
+  let release, active, controller, closed = false;
+
+  async function invoke(prompt, purpose, workIds, signal, timeoutMs) {
+    await inspectClaudeMcp(saved.mcp);
+    const tools = purpose === "ownerChat" ? ownerTools : peerTools;
+    const args = ["--print", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose",
+      "--resume", saved.sessionId, "--model", saved.model, "--strict-mcp-config",
+      "--permission-mode", saved.permissionMode, "--permission-prompts", "none", "--setting-sources", "user",
+      "--settings", '{"disableAllHooks":true}', "--tools", "ToolSearch", "--allowedTools",
+      ["ToolSearch", ...tools.map(tool => "mcp__" + saved.mcp.serverName + "__" + tool)].join(",")];
+    if (prompt) args.push("--mcp-config", JSON.stringify({ mcpServers: { [saved.mcp.serverName]: {
+      command: process.execPath, args: [fileURLToPath(import.meta.url), "--mcp-filter",
+        JSON.stringify(saved.mcp), purpose, JSON.stringify(workIds)],
+    } } }));
+    const requestId = randomUUID();
+    const send = value => child.stdin.write(JSON.stringify(value) + "\n");
+    const endInput = () => child.stdin.write("\0close\n");
+    const deadline = AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]);
+    if (deadline.aborted) throw fail("TURN_CANCELLED");
+    const child = (options.spawn ?? spawn)(saved.python, ["-I", watchdog, saved.binary, ...args], {
+      cwd: saved.cwd, env, shell: false, stdio: ["pipe", "pipe", "ignore"], windowsHide: true,
+    });
+    const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    let initialized = false, confirmed = false, completed = false, error;
+    function stop(failure) {
+      error ??= failure;
+      child.stdin.end();
+    }
+    const cancel = () => stop(fail("TURN_CANCELLED"));
+    deadline.addEventListener("abort", cancel, { once: true });
+    try {
+      await new Promise((resolve, reject) => {
+        child.once("error", () => stop(fail("UNAVAILABLE")));
+        child.stdin.on("error", () => stop(fail("PROTOCOL_FAILED")));
+        child.once("close", code => {
+          if (error || code !== 0 || !initialized || (prompt && !completed))
+            reject(error ?? fail(!initialized ? "SESSION_CHANGED" : "TURN_FAILED"));
+          else resolve();
+        });
+        lines.on("line", line => {
+          if (error) return;
+          try {
+            if (Buffer.byteLength(line) > 2 * 1024 * 1024) throw fail("PROTOCOL_FAILED");
+            const event = JSON.parse(line);
+            if (event.session_id !== undefined && event.session_id !== saved.sessionId) throw fail("SESSION_CHANGED");
+            if (event.type === "control_response") {
+              const response = event.response;
+              if (initialized || response?.request_id !== requestId || response.subtype !== "success") throw fail("PROTOCOL_FAILED");
+              const data = response.response;
+              if (data?.claude_code_version !== saved.nativeVersion) throw fail("VERSION_CHANGED");
+              const email = data?.account?.email;
+              if (data.account?.apiProvider !== saved.provider || typeof email !== "string" ||
+                digest("claude:" + email.trim().toLowerCase()) !== saved.accountFingerprint) throw fail("ACCOUNT_CHANGED");
+              if (data.current_permission_mode !== saved.permissionMode) throw fail("POLICY_CHANGED");
+              initialized = true;
+              if (!prompt) endInput();
+              else send({ type: "user", session_id: saved.sessionId, parent_tool_use_id: null, message: { role: "user", content: prompt } });
+            } else if (event.type === "system" && event.subtype === "init") {
+              if (!initialized || event.session_id !== saved.sessionId) throw fail("SESSION_CHANGED");
+              if (event.model !== saved.model) throw fail("MODEL_CHANGED");
+              if (event.permissionMode !== saved.permissionMode) throw fail("POLICY_CHANGED");
+              confirmed = true;
+            } else if (event.type === "control_request") throw fail("INTERACTION_REQUIRED");
+            else if (event.type === "result") {
+              if (!initialized && !prompt) throw fail("SESSION_CHANGED");
+              if (!confirmed || event.session_id !== saved.sessionId || event.is_error !== false) throw fail("TURN_FAILED");
+              completed = true;
+              endInput();
+            }
+          } catch (cause) { stop(cause.code?.startsWith("NATIVE_CLAUDE_") ? cause : fail("PROTOCOL_FAILED")); }
+        });
+        if (deadline.aborted) cancel();
+        else send({ type: "control_request", request_id: requestId, request: { subtype: "initialize" } });
+      });
+    } finally {
+      deadline.removeEventListener("abort", cancel);
+      lines.close();
+    }
+  }
+
+  function execute(prompt, { purpose, workIds, signal, timeoutMs = 10000 } = {}) {
+    if (closed || active) throw fail("BUSY");
+    controller = new AbortController();
+    active = invoke(prompt, purpose, workIds, signal ? AbortSignal.any([controller.signal, signal]) : controller.signal, timeoutMs)
+      .finally(() => { active = undefined; });
+    return active;
+  }
+
+  return {
+    async open() {
+      if (closed || release || await realpath(saved.cwd) !== saved.cwd) throw fail("BINDING_INVALID");
+      release = await acquireSupervisorLock(join(saved.cwd, ".totem-claude-" + saved.sessionId));
+      try { await execute(); }
+      catch (error) { await release(); release = undefined; throw error; }
+    },
+    run(prompt, turn) {
+      if (!release || typeof prompt !== "string" || !prompt.trim() || Buffer.byteLength(prompt) > 128 * 1024 ||
+        !validWork(turn?.purpose, turn?.workIds))
+        throw fail("TURN_INVALID");
+      return execute(prompt, turn);
+    },
+    async close() {
+      closed = true;
+      controller?.abort();
+      await active?.catch(() => {});
+      await release?.();
+      release = undefined;
+    },
+  };
+}
+
+async function connectMcp(binding, options, allowed) {
+  const server = await inspectClaudeMcp(binding);
+  const [{ Client }, { StdioClientTransport }] = await Promise.all([
+    import("@modelcontextprotocol/client"), import("@modelcontextprotocol/client/stdio"),
+  ]);
+  const client = new Client({ name: "totem-native-claude-checker", version: "1" });
+  const transport = new StdioClientTransport({
+    command: server.command, args: server.args, env: { ...nativeEnvironment(options.env ?? process.env), ...server.env },
+    cwd: binding.cwd, stderr: "ignore",
+  });
+  try {
+    await client.connect(transport, { signal: options.signal, timeout: 10000 });
+    const { tools } = await client.listTools({}, { signal: options.signal, timeout: 10000 });
+    return {
+      nativeIncoming: false,
+      listTools: () => tools.filter(tool => allowed.includes(tool.name)),
+      async call(name, args, { signal } = {}) {
+        if (!allowed.includes(name)) throw Object.assign(new Error("MCP_TOOL_UNAVAILABLE"), { code: "MCP_TOOL_UNAVAILABLE" });
+        await inspectClaudeMcp(binding);
+        return client.callTool({ name, arguments: args }, undefined, { signal, timeout: 10000 });
+      },
+      close: () => client.close(),
+    };
+  } catch (error) {
+    await client.close().catch(() => {});
+    throw error;
+  }
+}
+
+export const createClaudeMcpSurface = (binding, options = {}) => connectMcp(binding, options, checkers);
+
+function validWork(purpose, ids) {
+  return ["peer", "ownerChat"].includes(purpose) && Array.isArray(ids) && ids.length > 0 &&
+    ids.length <= 16 && ids.every(id => typeof id === "string" && uuid.test(id));
+}
+
+async function serveModelMcp(binding, purpose, workIds) {
+  if (!validWork(purpose, workIds)) throw fail("MCP_PURPOSE_INVALID");
+  const [{ Server }, { StdioServerTransport }] = await Promise.all([
+    import("@modelcontextprotocol/server"), import("@modelcontextprotocol/server/stdio"),
+  ]);
+  const upstream = await connectMcp(binding, {}, purpose === "ownerChat" ? ownerTools : peerTools);
+  try {
+    const identity = unwrapNativeMcp(await upstream.call("totem_get_identity", {}));
+    if (identity.id !== binding.agentId || identity.environment !== binding.environment) throw fail("MCP_IDENTITY_CHANGED");
+    const tools = upstream.listTools();
+    const replied = new Set();
+    const server = new Server({ name: "totem-claude-scoped-mcp", version: "1" }, { capabilities: { tools: {} } });
+    server.setRequestHandler("tools/list", async () => ({ tools }));
+    server.setRequestHandler("tools/call", async (request, context) => {
+      const { name, arguments: args } = request.params;
+      const tool = tools.find(tool => tool.name === name);
+      const peerMessage = ["totem_get_message", "totem_reply_to_message", "totem_acknowledge_message"].includes(name);
+      const ownerCommand = ["totem_claim_chat_command", "totem_renew_chat_command", "totem_complete_chat_command"].includes(name);
+      const target = peerMessage ? args?.messageId : args?.commandId;
+      if (!tool || ((peerMessage || ownerCommand) && !workIds.includes(target)))
+        return { isError: true, content: [{ type: "text", text: "This operation is outside the current receiver work." }] };
+      if (name === "totem_acknowledge_message" && !replied.has(target))
+        return { isError: true, content: [{ type: "text", text: "Confirm the reply with the same stable key before acknowledging." }] };
+      const stable = ["totem_reply_to_message", "totem_complete_chat_command"].includes(name);
+      const idempotencyKey = stable ? "native-claude-" + digest(binding.agentId + ":" + (peerMessage ? "m:" : "c:") + target) : undefined;
+      const result = await upstream.call(name, stable ? { ...args, idempotencyKey } : args ?? {}, { signal: context.signal });
+      if (name === "totem_reply_to_message" && !result.isError) {
+        const receipt = unwrapNativeMcp(result);
+        if (receipt.inReplyToId === target && typeof receipt.id === "string" && receipt.id) replied.add(target);
+      }
+      return server.projectCallToolResult(result, tool.outputSchema);
+    });
+    process.stdin.once("end", () => { void upstream.close().catch(() => {}); });
+    await server.connect(new StdioServerTransport());
+  } catch (error) {
+    await upstream.close().catch(() => {});
+    throw error;
+  }
+}
+
+const adapter = { kind: "claude", createBridge: createClaudeNativeBridge, createSurface: createClaudeMcpSurface,
+  files: ["native-claude-receiver.mjs", "native-cli-process.py", "native-mcp-source.mjs", "native-inbox-receiver.mjs"] };
+function bind(config) {
+  if (JSON.stringify(config?.native?.mcp) !== JSON.stringify(config?.mcp) ||
+    config?.mcp?.agentId !== config?.source?.agentId || config?.mcp?.environment !== config?.source?.environment)
+    throw fail("MCP_BINDING_CHANGED");
+  return config;
+}
+export const installClaudeNativeReceiver = (root, config, options) => installNativeInboxReceiver(root, bind(config), adapter, options);
+export const runClaudeNativeReceiver = (config, options) => runNativeInboxReceiver(bind(config), adapter, options);
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href &&
+  process.argv[2] === "--mcp-filter") {
+  try { await serveModelMcp(JSON.parse(process.argv[3]), process.argv[4], JSON.parse(process.argv[5])); }
+  catch { process.stderr.write("NATIVE_CLAUDE_MCP_FILTER_FAILED\n"); process.exitCode = 1; }
+}

package/bin/native-cli-process.py

@@ -0,0 +1,105 @@
+"""Stop the owned native CLI tree when its receiver's liveness pipe closes."""
+import contextlib
+import os
+from queue import SimpleQueue
+import signal
+import subprocess
+import sys
+import threading
+
+if len(sys.argv) < 4 or not os.path.isabs(sys.argv[1]):
+    raise SystemExit(2)
+client = os.path.basename(sys.argv[1]).lower()
+claude = client in ("claude", "claude.exe") and sys.argv[2:9] == [
+    "--print", "--input-format", "stream-json", "--output-format", "stream-json", "--verbose", "--resume",
+]
+local_cli = client in ("opencode", "opencode.exe", "kilo", "kilo.exe") and sys.argv[2:4] == ["--pure", "run"]
+if not (claude or local_cli):
+    raise SystemExit(2)
+child = subprocess.Popen(sys.argv[1:], stdin=subprocess.PIPE if claude else subprocess.DEVNULL,
+                         start_new_session=os.name != "nt",
+                         creationflags=subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0)
+lock = threading.RLock()
+
+
+def stop(*_):
+    with lock:
+        if child.poll() is not None:
+            return
+        if os.name == "nt":
+            with contextlib.suppress(OSError, subprocess.TimeoutExpired):
+                subprocess.run(["taskkill.exe", "/PID", str(child.pid), "/T", "/F"],
+                               stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=3)
+        else:
+            with contextlib.suppress(ProcessLookupError):
+                os.killpg(child.pid, signal.SIGTERM)
+        try:
+            child.wait(timeout=0.75)
+        except subprocess.TimeoutExpired:
+            with contextlib.suppress(ProcessLookupError):
+                if os.name == "nt":
+                    child.kill()
+                else:
+                    os.killpg(child.pid, signal.SIGKILL)
+            child.wait()
+
+
+requested = threading.Event()
+protocol = SimpleQueue()
+
+
+def request_stop(*_):
+    requested.set()
+
+
+def stop_requested():
+    requested.wait()
+    stop()
+
+
+def forward_protocol():
+    try:
+        while True:
+            line = protocol.get()
+            if line == b"\0close":
+                child.stdin.close()
+            elif not child.stdin.closed:
+                child.stdin.write(line + b"\n")
+                child.stdin.flush()
+    except OSError:
+        request_stop()
+
+
+def parent_pipe():
+    try:
+        if claude:
+            # Closing Claude's stdin completes its protocol. Only an actual
+            # EOF from the receiver ends the watchdog's liveness channel.
+            pending = b""
+            while chunk := os.read(0, 65536):
+                pending += chunk
+                while b"\n" in pending:
+                    line, pending = pending.split(b"\n", 1)
+                    protocol.put(line)
+        else:
+            while os.read(0, 1):
+                pass
+    except OSError:
+        pass
+    finally:
+        request_stop()
+
+
+for sig in (signal.SIGTERM, signal.SIGINT):
+    signal.signal(sig, request_stop)
+if claude:
+    threading.Thread(target=forward_protocol, daemon=True).start()
+threading.Thread(target=parent_pipe, daemon=True).start()
+stopper = threading.Thread(target=stop_requested, daemon=True)
+stopper.start()
+try:
+    result = child.wait()
+finally:
+    request_stop()
+    stopper.join(timeout=3)
+raise SystemExit(result if result >= 0 else 1)

package/bin/native-harness-environment.mjs

@@ -0,0 +1,20 @@
+// Host-owned profile and CA bundle locations, not credentials or peer-supplied configuration.
+export const NATIVE_HARNESS_ENVIRONMENT = Object.freeze([
+  "CODEX_HOME",
+  "CODEX_CA_CERTIFICATE",
+  "SSL_CERT_FILE",
+  "CLAUDE_CONFIG_DIR",
+  "PI_CODING_AGENT_DIR",
+  "HERMES_HOME",
+  "HERMES_MANAGED_DIR",
+  "OPENCLAW_STATE_DIR",
+  "OPENCLAW_AGENT_DIR",
+  "OPENCLAW_CONFIG_PATH",
+  "OPENCODE_CONFIG",
+  "OPENCODE_CONFIG_DIR",
+  "KILO_CONFIG",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_CACHE_HOME",
+  "XDG_RUNTIME_DIR",
+]);

package/bin/native-hermes-bridge.mjs

@@ -0,0 +1,99 @@
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { StringDecoder } from "node:string_decoder";
+import { localClientEnvironment } from "./platform-client.mjs";
+
+const execute = promisify(execFile), fail = code => Object.assign(new Error(code), { code });
+const sessionPattern = /^\d{8}_\d{6}_[a-f0-9]{6}$/;
+
+/** Runs the native CLI with its owned saved profile/session and tool policy.
+ * Native process/transcript completion remains separate from a Totem receipt.
+ */
+export function createHermesNativeBridge(binding, options = {}) {
+  if (binding?.dedicated !== true || !sessionPattern.test(binding.sessionId ?? "") ||
+    ![binding.python, binding.nativeRoot, binding.home, binding.cwd].every(value => typeof value === "string" && isAbsolute(value) && !/[\0\r\n]/.test(value)) ||
+    ![binding.provider, binding.model].every(value => typeof value === "string" && /^[a-zA-Z0-9._:/-]{1,128}$/.test(value)) ||
+    binding.toolsets !== "totem" || typeof binding.ignoreRules !== "boolean" ||
+    !/^[a-f0-9]{64}$/.test(binding.policyFingerprint ?? "")) throw fail("NATIVE_HERMES_BINDING_INVALID");
+  const saved = structuredClone(binding), env = localClientEnvironment(options.env ?? process.env);
+  for (const key of Object.keys(env)) if (/^(TOTEM|AGENTTRUST)_|^(OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)$/i.test(key)) delete env[key];
+  Object.assign(env, { HERMES_HOME: saved.home, HERMES_SKIP_NODE_BOOTSTRAP: "1", PYTHONPATH: saved.nativeRoot, PYTHONDONTWRITEBYTECODE: "1" });
+  let busy = false, closed = false, active, controller;
+  async function inspect() {
+    if (closed) throw fail("NATIVE_HERMES_CLOSED");
+    let metadata;
+    try {
+      if (options.readMetadata) metadata = await options.readMetadata(saved, env);
+      else {
+        const result = await execute(saved.python, [fileURLToPath(new URL("./native-hermes-metadata.py", import.meta.url)), saved.nativeRoot, saved.home, saved.sessionId],
+          { env, cwd: saved.nativeRoot, timeout: 10000, maxBuffer: 65536, windowsHide: true });
+        metadata = JSON.parse(result.stdout);
+      }
+    } catch { throw fail("NATIVE_HERMES_METADATA_UNAVAILABLE"); }
+    if (metadata.sessionId !== saved.sessionId) throw fail("NATIVE_HERMES_SESSION_CHANGED");
+    if (metadata.model !== saved.model || metadata.provider !== saved.provider ||
+      metadata.observedRouteModel !== saved.model || metadata.observedRouteProvider !== saved.provider) throw fail("NATIVE_HERMES_MODEL_CHANGED");
+    if (metadata.policyFingerprint !== saved.policyFingerprint) throw fail("NATIVE_HERMES_POLICY_CHANGED");
+    if (![metadata.apiCalls, metadata.messages].every(value => Number.isSafeInteger(value) && value >= 0)) throw fail("NATIVE_HERMES_METADATA_UNAVAILABLE");
+    return metadata;
+  }
+  function runProcess(prompt, signal, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      let child, failure, output = "", diagnostics = "", bytes = 0, force;
+      const decoder = new StringDecoder("utf8");
+      const kill = type => {
+        if (!child?.pid) return;
+        try {
+          if (process.platform !== "win32") process.kill(-child.pid, type);
+          else execFile("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], { windowsHide: true, timeout: 3000 }, () => {});
+        } catch { /* This launcher signals only its own process group. */ }
+      };
+      const stop = code => { if (failure) return; failure = code; kill("SIGTERM"); force = setTimeout(() => kill("SIGKILL"), 1000); };
+      const abort = () => stop("NATIVE_HERMES_CANCELLED");
+      const args = ["-m", "hermes_cli.main", "chat", "--cli", "--provider", saved.provider, "--model", saved.model,
+        "--toolsets", saved.toolsets, ...(saved.ignoreRules ? ["--ignore-rules"] : []), "--quiet", "--max-turns", "12", "--source", "tool",
+        "--resume", saved.sessionId, "--no-restore-cwd", "--query", prompt];
+      try { child = (options.spawn ?? spawn)(saved.python, [fileURLToPath(new URL("./native-hermes-process.py", import.meta.url)), ...args], { env, cwd: saved.cwd, detached: process.platform !== "win32", windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }); }
+      catch { return reject(fail("NATIVE_HERMES_START_FAILED")); }
+      child.stdin.on("error", () => {}); // The native child's exit closes its liveness pipe.
+      const timer = setTimeout(() => stop("NATIVE_HERMES_TURN_TIMEOUT"), timeoutMs);
+      signal.addEventListener("abort", abort, { once: true }); if (signal.aborted) abort();
+      child.stdout.on("data", chunk => { bytes += chunk.length; if (bytes > 1024 * 1024) stop("NATIVE_HERMES_OUTPUT_LIMIT"); else output += decoder.write(chunk); });
+      child.stderr.on("data", chunk => { bytes += chunk.length; if (bytes > 1024 * 1024) stop("NATIVE_HERMES_OUTPUT_LIMIT"); else diagnostics += chunk.toString("utf8"); });
+      child.once("error", () => { failure ??= "NATIVE_HERMES_START_FAILED"; });
+      child.once("close", code => {
+        clearTimeout(timer); clearTimeout(force); signal.removeEventListener("abort", abort); kill("SIGKILL");
+        if (failure) return reject(fail(failure));
+        if (/not logged in|authentication required|unauthorized|refresh token.*(?:expired|reused)/i.test(diagnostics)) return reject(fail("AGENT_AUTH_REQUIRED"));
+        if (/quota.*(?:exceeded|insufficient)|credit balance|usage limit/i.test(diagnostics)) return reject(fail("AGENT_QUOTA_EXCEEDED"));
+        if (code !== 0) return reject(fail("NATIVE_HERMES_EXIT_FAILED"));
+        const ids = [...(output + "\n" + diagnostics).matchAll(/(?:^|\n)session_id: ([A-Za-z0-9_-]+)\s*(?=\n|$)/g)].map(match => match[1]);
+        if (ids.length !== 1 || ids[0] !== saved.sessionId) return reject(fail("NATIVE_HERMES_SESSION_UNVERIFIED"));
+        resolve();
+      });
+    });
+  }
+  return {
+    open: inspect, inspect,
+    async run(prompt, { signal, timeoutMs = 120000 } = {}) {
+      if (busy) throw fail("NATIVE_HERMES_BUSY");
+      if (typeof prompt !== "string" || !prompt.trim() || Buffer.byteLength(prompt) > 65536 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 900000) throw fail("NATIVE_HERMES_PROMPT_INVALID");
+      if (closed || signal?.aborted) throw fail("NATIVE_HERMES_CANCELLED");
+      busy = true; controller = new AbortController();
+      const combined = AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]);
+      active = (async () => {
+        const before = await inspect();
+        if (combined.aborted) throw fail("NATIVE_HERMES_CANCELLED");
+        await runProcess(prompt, combined, timeoutMs);
+        const after = await inspect();
+        if (combined.aborted) throw fail("NATIVE_HERMES_CANCELLED");
+        if (after.messages <= before.messages || after.apiCalls <= before.apiCalls) throw fail("NATIVE_HERMES_TRANSCRIPT_UNVERIFIED");
+        return { nativeProcessExited: true, nativeTranscriptAdvanced: true, sessionId: after.sessionId, model: after.model, provider: after.provider, totemReplyVerified: false };
+      })();
+      try { return await active; } finally { busy = false; active = undefined; controller = undefined; }
+    },
+    async close() { closed = true; controller?.abort(); await active?.catch(() => {}); },
+  };
+}

package/bin/native-hermes-installation.mjs

@@ -0,0 +1,9 @@
+import { createHermesNativeBridge } from "./native-hermes-bridge.mjs";
+import { createHermesMcpSurface } from "./native-hermes-mcp.mjs";
+import { installNativeInboxReceiver } from "./native-inbox-installation.mjs";
+
+export function installHermesNativeReceiver(root, config, options = {}) {
+  return installNativeInboxReceiver(root, config, { kind: "hermes", createBridge: createHermesNativeBridge, createSurface: createHermesMcpSurface,
+    files: ["native-hermes-bridge.mjs", "native-hermes-metadata.py", "native-hermes-process.py", "native-hermes-mcp.mjs", "native-hermes-mcp.py", "native-mcp-source.mjs", "native-hermes-receiver.mjs", "native-inbox-receiver.mjs"],
+  }, options);
+}

package/bin/native-hermes-mcp.mjs

@@ -0,0 +1,107 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { StringDecoder } from "node:string_decoder";
+import { localClientEnvironment } from "./platform-client.mjs";
+
+const fail = code => Object.assign(new Error(code), { code });
+const limit = 8 * 1024 * 1024;
+const tools = new Set(["totem_get_identity", "totem_get_activity", "totem_list_messages", "totem_list_chat_commands", "totem_get_chat", "totem_get_conversation", "totem_listen", "totem_start_listener"]);
+const codeOf = value => /^[A-Z0-9_]{1,100}$/.test(value) ? value : "NATIVE_HERMES_MCP_CALL_FAILED";
+
+/** Uses the native Hermes MCP task and its own OAuth manager; never reads or
+ * copies authentication files and never launches an LLM for empty checks.
+ */
+export async function createHermesMcpSurface(binding, options = {}) {
+  if (!binding || ![binding.python, binding.nativeRoot, binding.home, binding.cwd].every(value =>
+    typeof value === "string" && isAbsolute(value) && !/[\0\r\n]/.test(value)) ||
+    !/^[a-zA-Z0-9_-]{1,80}$/.test(binding.serverName ?? "") ||
+    !/^[a-f0-9]{64}$/.test(binding.policyFingerprint ?? "") ||
+    !/^[a-f0-9]{64}$/.test(binding.serverFingerprint ?? "") ||
+    !/^\d+\.\d+\.\d+(?:[-+][a-zA-Z0-9.-]+)?$/.test(binding.nativeVersion ?? "")) throw fail("NATIVE_HERMES_MCP_BINDING_INVALID");
+  const saved = structuredClone(binding), env = localClientEnvironment(options.env ?? process.env);
+  for (const key of Object.keys(env)) if (/^(TOTEM|AGENTTRUST)_|^(OPENAI_API_KEY|ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)$/i.test(key)) delete env[key];
+  Object.assign(env, { HERMES_HOME: saved.home, HERMES_SKIP_NODE_BOOTSTRAP: "1", PYTHONPATH: saved.nativeRoot, PYTHONDONTWRITEBYTECODE: "1", PYTHONUNBUFFERED: "1" });
+  let child, ready, closed = false, closing, buffer = "", nativeTools = [], incoming = false;
+  const pending = new Map(), decoder = new StringDecoder("utf8");
+  const timeoutMs = options.timeoutMs ?? 25000;
+  let resolveReady, rejectReady;
+  const opened = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+  function terminal(code) {
+    const error = fail(code);
+    rejectReady(error);
+    for (const request of pending.values()) request.finish(error);
+    pending.clear();
+    void close();
+  }
+  function accept(record) {
+    if (record?.type === "fatal") return terminal(codeOf(record.error?.code));
+    if (record?.type === "ready" && !ready && Array.isArray(record.tools) && record.tools.length <= tools.size &&
+      record.tools.every(tool => tools.has(tool.name) && tool.inputSchema && typeof tool.inputSchema === "object")) {
+      ready = true; nativeTools = record.tools; incoming = record.nativeIncoming === true; resolveReady(); return;
+    }
+    if (record?.type !== "response" || !pending.has(record.id)) return terminal("NATIVE_HERMES_MCP_PROTOCOL_INVALID");
+    const request = pending.get(record.id); pending.delete(record.id);
+    if (record.error) {
+      const error = fail(codeOf(record.error.code));
+      if (Number.isInteger(record.error.status) && record.error.status >= 400 && record.error.status <= 599) error.status = record.error.status;
+      if (Number.isSafeInteger(record.error.retryAfterSeconds) && record.error.retryAfterSeconds > 0 && record.error.retryAfterSeconds <= 86400) error.retryAfterSeconds = record.error.retryAfterSeconds;
+      request.finish(error);
+    } else request.finish(undefined, record.result);
+  }
+  async function close() {
+    closed = true;
+    closing ??= (async () => {
+      if (!child) return;
+      child.stdin.end();
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      await new Promise(resolve => {
+        const term = setTimeout(() => child.kill("SIGTERM"), 1000);
+        const kill = setTimeout(() => child.kill("SIGKILL"), 3000);
+        child.once("close", () => { clearTimeout(term); clearTimeout(kill); resolve(); });
+      });
+    })();
+    await closing;
+  }
+  try {
+    child = (options.spawn ?? spawn)(saved.python, [fileURLToPath(new URL("./native-hermes-mcp.py", import.meta.url))],
+      { env, cwd: saved.cwd, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
+    child.stdout.on("data", chunk => {
+      buffer += decoder.write(chunk);
+      if (Buffer.byteLength(buffer) > limit) return terminal("NATIVE_HERMES_MCP_OUTPUT_LIMIT");
+      for (;;) {
+        const end = buffer.indexOf("\n"); if (end < 0) break;
+        const line = buffer.slice(0, end); buffer = buffer.slice(end + 1);
+        try { accept(JSON.parse(line)); } catch { return terminal("NATIVE_HERMES_MCP_PROTOCOL_INVALID"); }
+      }
+    });
+    child.stderr.on("data", () => {}); // Native diagnostics can contain private URLs.
+    child.on("error", () => terminal("NATIVE_HERMES_MCP_UNAVAILABLE"));
+    child.once("close", () => terminal("NATIVE_HERMES_MCP_CLOSED"));
+    child.stdin.on("error", () => terminal("NATIVE_HERMES_MCP_CLOSED"));
+    child.stdin.write(JSON.stringify(saved) + "\n");
+    const abort = () => terminal("RUN_CANCELLED"), timer = setTimeout(() => terminal("TIMEOUT"), timeoutMs);
+    options.signal?.addEventListener("abort", abort, { once: true });
+    try { if (options.signal?.aborted) abort(); await opened; }
+    finally { clearTimeout(timer); options.signal?.removeEventListener("abort", abort); }
+  } catch (error) { await close(); throw fail(codeOf(error.code)); }
+  return {
+    get nativeIncoming() { return incoming; },
+    listTools() { if (closed) throw fail("NATIVE_HERMES_MCP_CLOSED"); return structuredClone(nativeTools); },
+    async call(name, args = {}, { signal } = {}) {
+      if (closed || signal?.aborted) throw fail("RUN_CANCELLED");
+      if (!tools.has(name) || !nativeTools.some(tool => tool.name === name)) throw fail("MCP_TOOL_UNAVAILABLE");
+      if (name === "totem_start_listener" && args.automatic !== true) throw fail("MCP_AUTOMATIC_START_UNAVAILABLE");
+      const id = randomUUID(), message = JSON.stringify({ id, name, arguments: args }) + "\n";
+      if (Buffer.byteLength(message) > limit) throw fail("NATIVE_HERMES_MCP_INPUT_LIMIT");
+      return new Promise((resolve, reject) => {
+        const abort = () => terminal("RUN_CANCELLED"), timer = setTimeout(() => terminal("TIMEOUT"), timeoutMs);
+        pending.set(id, { finish(error, result) { clearTimeout(timer); signal?.removeEventListener("abort", abort); if (error) reject(error); else resolve(result); } });
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted) abort();
+        else child.stdin.write(message, error => { if (error) terminal("NATIVE_HERMES_MCP_CLOSED"); });
+      });
+    }, close,
+  };
+}