totemlayer 0.1.96 → 0.1.115

package/bin/native-mcp-source.mjs

@@ -0,0 +1,244 @@
+import { randomUUID, createHash } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { privateDirectory, privateRead, privateWrite } from "./runtime-installation.mjs";
+import { acquireSupervisorLock } from "./runtime-lock.mjs";
+
+const fail = code => Object.assign(new Error(code), { code });
+const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const stopped = new Set(["LISTENER_STOPPED", "LISTENER_PAUSED", "AGENT_IDENTITY_MISMATCH", "LISTENER_ALREADY_ACTIVE", "LISTENER_KIND_MISMATCH", "AGENT_AUTH_REQUIRED", "MCP_AUTOMATIC_START_UNAVAILABLE", "MCP_NATIVE_INCOMING_UNAVAILABLE", "MCP_TOOL_UNAVAILABLE", "NATIVE_PI_MCP_CONFIG_CHANGED", "NATIVE_PI_MCP_CONFIG_INVALID", "NATIVE_PI_VERSION_CHANGED"]);
+const expired = new Set(["LISTENER_EXPIRED", "RUNTIME_SUPERSEDED", "LISTENER_NOT_READY", "READINESS_EXPIRED"]);
+export function validNativePeerScope(scope) {
+  if (scope === undefined) return true;
+  if (!scope || typeof scope !== "object" || Array.isArray(scope) || Object.keys(scope).length !== 2 ||
+    typeof scope.conversationId !== "string" || !uuid.test(scope.conversationId) || typeof scope.after !== "string")
+    return false;
+  const after = Date.parse(scope.after);
+  return Number.isFinite(after) && new Date(after).toISOString() === scope.after;
+}
+
+export function unwrapNativeMcp(result) {
+  let value = result?.structuredContent;
+  if (!value) {
+    try { value = JSON.parse(result?.content?.find(item => item.type === "text")?.text); }
+    catch { throw fail("MCP_RESPONSE_INVALID"); }
+  }
+  if (value?.error || result?.isError) {
+    const backend = value?.error;
+    const error = fail(/^[A-Z0-9_]{1,100}$/.test(backend?.code ?? "") ? backend.code : "MCP_CALL_FAILED");
+    if (Number.isInteger(backend?.status)) error.status = backend.status;
+    if (Number.isSafeInteger(backend?.retryAfterSeconds) && backend.retryAfterSeconds > 0 && backend.retryAfterSeconds <= 86400) error.retryAfterSeconds = backend.retryAfterSeconds;
+    throw error;
+  }
+  if (!value || typeof value !== "object") throw fail("MCP_RESPONSE_INVALID");
+  return value.data ?? value;
+}
+const readMissing = async path => privateRead(path).catch(error => { if (error.code !== "ENOENT") throw error; return undefined; });
+
+/** One durable, model-free checker. onSnapshot enqueues work synchronously;
+ * it must not wait for model execution. Server unread queues remain authoritative.
+ */
+export async function runNativeMcpSource(config, options) {
+  if (!uuid.test(config?.agentId ?? "") || !["PRODUCTION", "SANDBOX"].includes(config.environment) ||
+    typeof config.directory !== "string" || !isAbsolute(config.directory) || /[\0\r\n]/.test(config.directory) ||
+    (config.hostKind !== undefined && !["local", "hosted"].includes(config.hostKind)) ||
+    (config.receivingMode !== undefined && !["fallback", "native"].includes(config.receivingMode)) ||
+    !validNativePeerScope(config.peerScope) ||
+    !/^[a-f0-9]{64}$/.test(config.bindingFingerprint ?? "") || typeof config.ownerChats !== "boolean" ||
+    typeof options?.connect !== "function" || typeof options.onSnapshot !== "function") throw fail("NATIVE_SOURCE_CONFIG_INVALID");
+  const intervalMs = options.intervalMs ?? 5000;
+  if (!Number.isSafeInteger(intervalMs) || intervalMs < 10 || intervalMs > 10000) throw fail("NATIVE_SOURCE_CONFIG_INVALID");
+  const now = options.now ?? Date.now, signal = options.signal;
+  await privateDirectory(config.directory);
+  const release = await acquireSupervisorLock(join(config.directory, "source-owner"));
+  const path = join(config.directory, "receive.json"), statusPath = join(config.directory, "status.json"), pausePath = join(config.directory, "paused.json");
+  const nativeMode = config.receivingMode === "native";
+  const bindingParts = [config.agentId, config.environment, config.bindingFingerprint, config.ownerChats];
+  if (nativeMode) bindingParts.push("native"); // Retain existing fallback bindings unchanged.
+  const peerScope = config.peerScope;
+  const peerAfter = peerScope ? Date.parse(peerScope.after) : undefined;
+  if (peerScope) bindingParts.push([peerScope.conversationId, peerScope.after]);
+  const binding = createHash("sha256").update(JSON.stringify(bindingParts)).digest("hex");
+  let surface, state, failures = 0, unexpected = 0, identityAt = 0, identityRequired = true, recovery = true;
+  const sleep = async ms => { try { await (options.wait ?? delay)(ms, undefined, { signal }); } catch (error) { if (!signal?.aborted) throw error; } };
+  const status = extra => privateWrite(statusPath, { version: 1, pid: process.pid, agentId: config.agentId, intervalMs, updatedAt: new Date(now()).toISOString(), ...extra });
+  try {
+    state = await readMissing(path) ?? { version: 1, binding, cursor: "0", messageCursor: "0", notified: {} };
+    if (state.version !== 1 || state.binding !== binding || !state.notified || typeof state.notified !== "object" || Array.isArray(state.notified) ||
+      ![state.cursor, state.messageCursor].every(cursor => typeof cursor === "string" && cursor.length <= 4096) ||
+      (state.runId !== undefined && !uuid.test(state.runId)) ||
+      (state.retryAt !== undefined && (!Number.isSafeInteger(state.retryAt) || state.retryAt < 0)) ||
+      Object.entries(state.notified).some(([id, at]) => !/^[mc]:/.test(id) || !uuid.test(id.slice(2)) || !Number.isSafeInteger(at)) ||
+      (state.ownerCommands !== undefined && (!config.ownerChats || !state.ownerCommands || typeof state.ownerCommands !== "object" || Array.isArray(state.ownerCommands) || Object.keys(state.ownerCommands).length > 128 || Object.entries(state.ownerCommands).some(([id, chatId]) => !uuid.test(id) || !uuid.test(chatId))))) throw fail("NATIVE_SOURCE_STATE_CHANGED");
+    async function call(name, args = {}) {
+      return unwrapNativeMcp(await surface.call(name, args, { signal: AbortSignal.any([
+        ...(signal ? [signal] : []), AbortSignal.timeout(10000),
+      ]) }));
+    }
+    async function collect(name, args) {
+      const rows = [], seen = new Set(); let cursor;
+      do {
+        const page = await call(name, { ...args, ...(cursor ? { cursor } : {}) });
+        if (!Array.isArray(page.data) || rows.length + page.data.length > 2000) throw fail("MCP_RESPONSE_INVALID");
+        rows.push(...page.data);
+        cursor = page.nextCursor;
+        if (cursor && (typeof cursor !== "string" || cursor.length > 4096 || seen.has(cursor))) throw fail("MCP_CURSOR_STALLED");
+        if (cursor) seen.add(cursor);
+      } while (cursor && !signal?.aborted);
+      return rows;
+    }
+    async function identity() {
+      const own = await call("totem_get_identity");
+      if (own.id !== config.agentId || own.environment !== config.environment) throw fail("AGENT_IDENTITY_MISMATCH");
+      const current = own.runtime?.currentConnection;
+      if (["LISTENER_STOPPED", "LISTENER_PAUSED"].includes(current?.errorCode)) throw fail("LISTENER_PAUSED");
+      if (nativeMode) {
+        const seen = Date.parse(current?.lastSeenAt ?? "");
+        if (current?.listenerKind !== "mcp" || current.connectionState !== "connected" || current.state !== "online" ||
+          current.listenerReady !== true || !Number.isFinite(seen) || seen > now() + 5000 || now() - seen > 45000) throw fail("MCP_NATIVE_RECEIVE_NOT_READY");
+      }
+      identityAt = now();
+      identityRequired = false;
+    }
+    while (!signal?.aborted) {
+      if (await readMissing(pausePath)) { await status({ state: "paused" }); return { state: "paused" }; }
+      if (state.retryAt > now()) {
+        await status({ state: "reconnecting", retryAt: state.retryAt });
+        await sleep(Math.min(1000, state.retryAt - now())); continue;
+      }
+      const started = now(); let backoff = 0;
+      try {
+        surface ??= await options.connect({ signal });
+        if (nativeMode && surface.nativeIncoming !== true) throw fail("MCP_NATIVE_INCOMING_UNAVAILABLE");
+        let identityChecked = false;
+        if (identityRequired || (!nativeMode && (!state.runId || now() - identityAt >= 30000))) {
+          await identity(); identityChecked = true;
+        }
+        const continuingFallback = !nativeMode && state.runId && !state.readinessReply;
+        if (!nativeMode && !state.runId) {
+          const start = surface.listTools().find(tool => tool.name === "totem_start_listener");
+          // An older schema cannot atomically preserve owner pause. Never retry
+          // without the flag or convert a policy denial to an explicit resume.
+          if (start?.inputSchema?.properties?.automatic?.type !== "boolean") throw fail("MCP_AUTOMATIC_START_UNAVAILABLE");
+          const lease = await call("totem_start_listener", { runId: randomUUID(), hostKind: config.hostKind ?? "local", automatic: true });
+          if (!uuid.test(lease.runId ?? "")) throw fail("MCP_RESPONSE_INVALID");
+          state.runId = lease.runId; state.readinessReply = lease.readinessReply;
+          await privateWrite(path, state);
+        }
+        async function readFeed() {
+          let feed; const pages = new Set();
+        do {
+          feed = nativeMode
+            ? await call("totem_get_activity", { cursor: state.cursor, messageCursor: state.messageCursor, limit: 100 })
+            : await call("totem_listen", { runId: state.runId, cursor: state.cursor, messageCursor: state.messageCursor,
+              ...(state.readinessReply ? { readinessReply: state.readinessReply } : {}), timeoutSeconds: 0, limit: 100 });
+          if (typeof feed.activity?.cursor !== "string" || typeof feed.messages?.cursor !== "string") throw fail("MCP_RESPONSE_INVALID");
+          state.cursor = feed.activity.cursor; state.messageCursor = feed.messages.cursor;
+          delete state.readinessReply; await privateWrite(path, state);
+          if (feed.activity.nextCursor || feed.messages.nextCursor) {
+            const pair = JSON.stringify([state.cursor, state.messageCursor]);
+            if (pages.has(pair) || pages.size > 100) throw fail("MCP_CURSOR_STALLED");
+            pages.add(pair);
+          }
+        } while ((feed.activity.nextCursor || feed.messages.nextCursor) && !signal?.aborted);
+        if (!nativeMode && feed.listenerReady !== true) throw fail("LISTENER_NOT_READY");
+          return feed;
+        }
+        const unreadPeers = { direction: "inbound", unread: true, limit: 100 };
+        if (peerScope) unreadPeers.conversationId = peerScope.conversationId;
+        // Finish the initial fallback readiness exchange before reading queues.
+        // Established listeners can overlap independent reads, but a failed
+        // feed or queue read must suppress the entire wake snapshot.
+        if (!nativeMode && !continuingFallback) await readFeed();
+        const results = await Promise.allSettled([
+          nativeMode && !identityChecked ? identity() : undefined,
+          nativeMode || continuingFallback ? readFeed() : undefined,
+          collect("totem_list_messages", unreadPeers),
+          config.ownerChats ? collect("totem_list_chat_commands", { limit: 100 }) : [],
+        ]);
+        const failed = results.find(result => result.status === "rejected");
+        if (failed) throw failed.reason;
+        let [, , messages, commands] = results.map(result => result.value);
+        if (peerScope)
+          messages = messages.filter(row => row?.conversationId === peerScope.conversationId &&
+            typeof row.createdAt === "string" && Date.parse(row.createdAt) > peerAfter);
+        const availableCommands = new Set(commands.map(row => row.id));
+        if (config.ownerChats) {
+          state.ownerCommands ??= {};
+          for (const row of commands) {
+            if (!uuid.test(row.id) || !uuid.test(row.chatId) || (state.ownerCommands[row.id] && state.ownerCommands[row.id] !== row.chatId)) throw fail("MCP_RESPONSE_INVALID");
+            if (!state.ownerCommands[row.id] && Object.keys(state.ownerCommands).length >= 128) continue;
+            state.ownerCommands[row.id] = row.chatId;
+          }
+          // Claiming a website command removes it from list_chat_commands.
+          // Queue absence is never completion: retain its journal until the
+          // original chat confirms a terminal run, including after a crash.
+          const chats = new Map();
+          for (const [id, chatId] of Object.entries(state.ownerCommands)) {
+            if (availableCommands.has(id)) continue;
+            if (!chats.has(chatId)) chats.set(chatId, await call("totem_get_chat", { chatId, limit: 1 }));
+            const detail = chats.get(chatId), run = detail.runs?.find(row => row.id === id);
+            if (detail.chat?.id !== chatId || detail.chat.agentId !== config.agentId || !run || !["queued", "running", "completed", "failed", "canceled"].includes(run.state)) throw fail("MCP_OWNER_COMMAND_UNVERIFIED");
+            if (["completed", "failed", "canceled"].includes(run.state)) delete state.ownerCommands[id];
+            else if (run.state === "queued") availableCommands.add(id);
+          }
+          commands = Object.keys(state.ownerCommands).map(id => ({ id }));
+        }
+        const ids = [...new Set([...messages.map(row => "m:" + row.id), ...commands.map(row => "c:" + row.id)])];
+        const readyIds = ids.filter(id => id.startsWith("m:") || availableCommands.has(id.slice(2)));
+        if (ids.some(id => !uuid.test(id.slice(2)))) throw fail("MCP_RESPONSE_INVALID");
+        const fresh = readyIds.filter(id => recovery || !state.notified[id] || now() - state.notified[id] >= 120000);
+        if (fresh.length) await identity(); // Recheck owner pause before waking work.
+        const at = now();
+        // Delivery to this callback is a wake hint, never a processed/ack proof.
+        // Persist owner/chat bindings before dispatch can claim the command.
+        if (config.ownerChats) await privateWrite(path, state);
+        const queued = options.onSnapshot({ ids, readyIds, fresh, checkedAt: new Date(at).toISOString() });
+        if (queued?.then) throw fail("NATIVE_SOURCE_ASYNC_SNAPSHOT");
+        for (const id of fresh) state.notified[id] = at;
+        state.notified = Object.fromEntries(Object.entries(state.notified).filter(([id]) => ids.includes(id)).slice(-512));
+        recovery = false; failures = 0; unexpected = 0; delete state.retryAt;
+        state.lastCheckAt = new Date(at).toISOString(); await privateWrite(path, state);
+        await status({ state: "listening", listenerReady: true, lastCheckAt: state.lastCheckAt, pendingPeers: messages.length, pendingOwnerChats: commands.length });
+      } catch (error) {
+        if (signal?.aborted) break;
+        const code = /^[A-Z0-9_]{1,100}$/.test(error.code ?? "") ? error.code : "NATIVE_SOURCE_CHECK_FAILED";
+        if (expired.has(code)) { delete state.runId; delete state.readinessReply; }
+        failures++;
+        const transient = expired.has(code) || [408, 429, 500, 502, 503, 504].includes(error.status) || ["NETWORK_ERROR", "TIMEOUT", "RUN_CANCELLED", "ENOTFOUND", "EAI_AGAIN", "ECONNRESET", "ETIMEDOUT", "NATIVE_PI_MCP_CLOSED", "NATIVE_HERMES_MCP_CLOSED", "NATIVE_PI_MCP_CALL_FAILED", "NATIVE_HERMES_MCP_CALL_FAILED", "NATIVE_OPENCODE_MCP_CLOSED", "NATIVE_KILO_MCP_CLOSED", "NATIVE_OPENCODE_MCP_CALL_FAILED", "NATIVE_KILO_MCP_CALL_FAILED", "NATIVE_OPENCODE_MCP_AUTH_REFRESH_REQUIRED", "NATIVE_KILO_MCP_AUTH_REFRESH_REQUIRED", "MCP_NATIVE_RECEIVE_NOT_READY"].includes(code);
+        unexpected = transient ? 0 : unexpected + 1;
+        const fatal = stopped.has(code) || /^NATIVE_(?:HERMES|OPENCODE|KILO|CLAUDE)_(?:MCP_CONFIG_CHANGED|MCP_CONFIG_INVALID|MCP_PROFILE_CHANGED|VERSION_CHANGED|MCP_AUTH_UNSUPPORTED)$/.test(code) || [401, 403].includes(error.status) || unexpected >= 5;
+        backoff = Math.max(intervalMs, Math.min(30000, intervalMs * 2 ** Math.min(failures - 1, 10)), (error.retryAfterSeconds ?? 0) * 1000);
+        state.retryAt = now() + backoff; await privateWrite(path, state);
+        await status({ state: fatal ? "paused" : "reconnecting", errorCode: code, retryAt: state.retryAt });
+        if (fatal) {
+          await privateWrite(pausePath, { code, at: new Date(now()).toISOString() });
+          return { state: "paused", code };
+        }
+        // A timed-out native call may retire its entire MCP client. Reusing
+        // that handle turns a short service restart into repeated cancellation
+        // failures and an automatic failure pause. Reconnect only after the
+        // saved cooldown, and fence the new connection with a fresh identity.
+        // Readiness and explicit server cooldown responses keep a healthy
+        // channel open; a native incoming channel may need time to become ready.
+        const keepChannel = expired.has(code) || code === "MCP_NATIVE_RECEIVE_NOT_READY" ||
+          [429, 500, 502, 503, 504].includes(error.status);
+        if (!keepChannel) {
+          const retired = surface;
+          surface = undefined;
+          identityRequired = true;
+          try { await retired?.close(); } catch { /* Retain the original failure and cooldown. */ }
+        }
+      }
+      await sleep(backoff ? Math.min(1000, backoff) : Math.max(0, intervalMs - (now() - started)));
+    }
+    await status({ state: "stopped" });
+    return { state: "stopped" };
+  } catch (error) {
+    const code = /^[A-Z0-9_]{1,100}$/.test(error.code ?? "") ? error.code : "NATIVE_SOURCE_STATE_INVALID";
+    await status({ state: "error", errorCode: code }).catch(() => {});
+    throw fail(code);
+  } finally {
+    try { await surface?.close(); } finally { await release(); }
+  }
+}

package/bin/native-opencode-bridge.mjs

@@ -0,0 +1,108 @@
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { open, unlink, readFile, lstat } from "node:fs/promises";
+import { randomUUID, createHash } from "node:crypto";
+import { join, 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 });
+
+/** Uses an existing dedicated native session and native model OAuth. Configuration
+ * is inspected before and after each turn; a process exit alone is not a receipt.
+ */
+export function createOpenCodeNativeBridge(binding, options = {}) {
+  if (!["opencode", "kilo"].includes(binding?.kind) || binding.dedicated !== true ||
+    !/^ses_[A-Za-z0-9]{12,80}$/.test(binding.sessionId ?? "") ||
+    ![binding.binary, binding.python, binding.profile, binding.configPath, binding.cwd].every(p => typeof p === "string" && isAbsolute(p) && !/[\0\r\n]/.test(p)) ||
+    ![binding.model, binding.provider].every(s => typeof s === "string" && /^[a-zA-Z0-9._:-]{1,128}$/.test(s)) ||
+    !/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(binding.nativeVersion ?? "") ||
+    !/^[a-f0-9]{64}$/.test(binding.policyFingerprint ?? "")) throw fail("NATIVE_OPENCODE_BINDING_INVALID");
+  const saved = structuredClone(binding), prefix = "NATIVE_" + saved.kind.toUpperCase();
+  const 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|OPENCODE_CONFIG_DIR|KILO_CONFIG)$/i.test(key)) delete env[key];
+  Object.assign(env, { XDG_CONFIG_HOME: join(saved.profile, "config"), XDG_DATA_HOME: join(saved.profile, "data"), XDG_CACHE_HOME: join(saved.profile, "cache"),
+    [saved.kind === "opencode" ? "OPENCODE_CONFIG" : "KILO_CONFIG"]: saved.configPath, DO_NOT_TRACK: "1", OPENCODE_DISABLE_CODEBASE_INDEXING: "true" });
+  let closed = false, busy = false, controller, active;
+  async function exportMetadata() {
+    const path = join(saved.profile, ".totem-session-inspect-" + randomUUID());
+    const file = await open(path, "wx+", 0o600);
+    await unlink(path); // Native stdout stays a private regular file, avoiding its 128KiB pipe truncation.
+    try {
+      await new Promise((resolve, reject) => {
+        const child = spawn(saved.binary, ["--pure", "export", saved.sessionId, "--sanitize"], { env, cwd: saved.cwd, windowsHide: true, stdio: ["ignore", file.fd, "pipe"] });
+        let bytes = 0, failed;
+        const timer = setTimeout(() => { failed = prefix + "_METADATA_TIMEOUT"; child.kill(); }, 10000);
+        child.stderr.on("data", chunk => { bytes += chunk.length; if (bytes > 65536) { failed = prefix + "_METADATA_OUTPUT_LIMIT"; child.kill(); } });
+        child.once("error", () => { failed = prefix + "_METADATA_UNAVAILABLE"; });
+        child.once("close", code => { clearTimeout(timer); if (failed || code !== 0) reject(fail(failed ?? prefix + "_METADATA_UNAVAILABLE")); else resolve(); });
+      });
+      const { size } = await file.stat();
+      if (size < 2 || size > 16 * 1024 * 1024) throw fail(prefix + "_METADATA_OUTPUT_LIMIT");
+      const buffer = Buffer.alloc(size), result = await file.read(buffer, 0, size, 0);
+      if (result.bytesRead !== size) throw fail(prefix + "_METADATA_UNAVAILABLE");
+      const value = JSON.parse(buffer.toString("utf8"));
+      return { sessionId: value.info?.id, model: value.info?.model?.id, provider: value.info?.model?.providerID,
+        variant: value.info?.model?.variant ?? "default", messages: value.messages?.length, routes: [...new Set((value.messages ?? []).filter(m => m.info?.role === "assistant").map(m => m.info.providerID + "/" + m.info.modelID))] };
+    } finally { await file.close(); }
+  }
+  async function inspect() {
+    if (closed) throw fail(prefix + "_CLOSED");
+    const info = await lstat(saved.configPath);
+    if (!info.isFile() || info.isSymbolicLink() || (typeof process.getuid === "function" && info.uid !== process.getuid()) ||
+      (process.platform !== "win32" && (info.mode & 0o777) !== 0o600) ||
+      createHash("sha256").update(await readFile(saved.configPath)).digest("hex") !== saved.policyFingerprint) throw fail(prefix + "_POLICY_CHANGED");
+    const version = await (options.execute ?? execute)(saved.binary, ["--pure", "--version"], { env, cwd: saved.cwd, timeout: 10000, maxBuffer: 65536, windowsHide: true });
+    if (version.stdout.trim() !== saved.nativeVersion) throw fail(prefix + "_VERSION_CHANGED");
+    const metadata = await (options.readMetadata ?? exportMetadata)();
+    if (metadata.sessionId !== saved.sessionId) throw fail(prefix + "_SESSION_CHANGED");
+    if ((metadata.variant ?? "default") !== "default" || metadata.model !== saved.model || metadata.provider !== saved.provider ||
+      !Array.isArray(metadata.routes) || metadata.routes.length !== 1 || metadata.routes[0] !== saved.provider + "/" + saved.model) throw fail(prefix + "_MODEL_CHANGED");
+    if (!Number.isSafeInteger(metadata.messages) || metadata.messages < 1) throw fail(prefix + "_METADATA_UNAVAILABLE");
+    return metadata;
+  }
+  async function runProcess(prompt, signal, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      const args = [fileURLToPath(new URL("./native-cli-process.py", import.meta.url)), saved.binary, "--pure", "run", "--model", saved.provider + "/" + saved.model, "--format", "json", "--session", saved.sessionId, prompt];
+      let child;
+      try { child = (options.spawn ?? spawn)(saved.python, args, { env, cwd: saved.cwd, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] }); }
+      catch { return reject(fail(prefix + "_START_FAILED")); }
+      let output = "", bytes = 0, failure, force;
+      const decoder = new StringDecoder("utf8");
+      const stop = code => { if (failure) return; failure = code; child.stdin.end(); child.kill("SIGTERM"); force = setTimeout(() => child.kill("SIGKILL"), 2000); };
+      child.stdin.on("error", () => {});
+      const abort = () => stop(prefix + "_CANCELLED"), timer = setTimeout(() => stop(prefix + "_TURN_TIMEOUT"), timeoutMs);
+      signal.addEventListener("abort", abort, { once: true }); if (signal.aborted) abort();
+      child.stdout.on("data", chunk => { bytes += chunk.length; if (bytes > 2 * 1024 * 1024) stop(prefix + "_OUTPUT_LIMIT"); else output += decoder.write(chunk); });
+      child.stderr.on("data", chunk => { bytes += chunk.length; if (bytes > 2 * 1024 * 1024) stop(prefix + "_OUTPUT_LIMIT"); });
+      child.once("error", () => { failure ??= prefix + "_START_FAILED"; });
+      child.once("close", code => {
+        clearTimeout(timer); clearTimeout(force); signal.removeEventListener("abort", abort);
+        if (failure || code !== 0) return reject(fail(failure ?? prefix + "_EXIT_FAILED"));
+        output += decoder.end();
+        let records;
+        try { records = output.trim().split("\n").map(line => JSON.parse(line)); } catch { return reject(fail(prefix + "_PROTOCOL_INVALID")); }
+        const sessions = [...new Set(records.map(row => row.sessionID).filter(Boolean))];
+        if (records.some(row => row.type === "error") || sessions.length !== 1 || sessions[0] !== saved.sessionId) return reject(fail(prefix + "_TRANSCRIPT_UNVERIFIED"));
+        resolve();
+      });
+    });
+  }
+  return { open: inspect, inspect,
+    async run(prompt, { signal, timeoutMs = 120000 } = {}) {
+      if (busy) throw fail(prefix + "_BUSY");
+      if (closed || signal?.aborted) throw fail(prefix + "_CANCELLED");
+      if (typeof prompt !== "string" || !prompt.trim() || Buffer.byteLength(prompt) > 65536 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 900000) throw fail(prefix + "_PROMPT_INVALID");
+      busy = true; controller = new AbortController();
+      const combined = AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]);
+      active = (async () => { const before = await inspect(); if (combined.aborted) throw fail(prefix + "_CANCELLED");
+        await runProcess(prompt, combined, timeoutMs); const after = await inspect();
+        if (combined.aborted) throw fail(prefix + "_CANCELLED");
+        if (after.messages <= before.messages) throw fail(prefix + "_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; controller = undefined; active = undefined; }
+    }, async close() { closed = true; controller?.abort(); await active?.catch(() => {}); },
+  };
+}

package/bin/native-opencode-installation.mjs

@@ -0,0 +1,15 @@
+import { createOpenCodeNativeBridge } from "./native-opencode-bridge.mjs";
+import { createOpenCodeMcpSurface } from "./native-opencode-mcp.mjs";
+import { installNativeInboxReceiver } from "./native-inbox-installation.mjs";
+
+export async function installOpenCodeNativeReceiver(root, config, options = {}) {
+  return installNativeCliReceiver("opencode", root, config, options);
+}
+export async function installNativeCliReceiver(kind, root, config, options = {}) {
+  if (!["opencode", "kilo"].includes(kind) || config?.native?.kind !== kind || config.mcp?.kind !== kind ||
+    config.native.profile !== config.mcp.profile || config.native.configPath !== config.mcp.configPath)
+    throw Object.assign(new Error("Native profile binding changed"), { code: "NATIVE_" + (kind === "kilo" ? "KILO" : "OPENCODE") + "_INSTALL_CONFIG_INVALID" });
+  return installNativeInboxReceiver(root, config, { kind, createBridge: createOpenCodeNativeBridge, createSurface: createOpenCodeMcpSurface,
+    files: ["native-opencode-bridge.mjs", "native-opencode-mcp.mjs", "native-cli-process.py", "native-mcp-source.mjs", "native-opencode-receiver.mjs", "native-inbox-receiver.mjs", ...(kind === "kilo" ? ["native-kilo-receiver.mjs"] : [])],
+  }, options);
+}

package/bin/native-opencode-mcp.mjs

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { isAbsolute, join, resolve } from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+import { privateRead } from "./runtime-installation.mjs";
+import { localClientEnvironment } from "./platform-client.mjs";
+import { configureEnvironmentProxy } from "./runtime-proxy.mjs";
+
+const execute = promisify(execFile), fail = code => Object.assign(new Error(code), { code });
+const checkers = new Set(["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 canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+export const openCodeMcpBindingFingerprint = server => createHash("sha256").update(JSON.stringify(canonical(server))).digest("hex");
+
+/** Read the native client's own cache in place. Only the official native CLI
+ * refreshes it; no credential is exported, copied, or written by this checker.
+ */
+export async function createOpenCodeMcpSurface(binding, options = {}) {
+  if (!["opencode", "kilo"].includes(binding?.kind) ||
+    ![binding.binary, binding.profile, binding.configPath, binding.cwd].every(p => typeof p === "string" && isAbsolute(p) && !/[\0\r\n]/.test(p)) ||
+    !/^[\w-]{1,80}$/.test(binding.serverName ?? "") || !/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(binding.nativeVersion ?? "") ||
+    !/^[a-f0-9]{64}$/.test(binding.serverFingerprint ?? "")) throw fail("NATIVE_OPENCODE_MCP_BINDING_INVALID");
+  const saved = structuredClone(binding), prefix = "NATIVE_" + saved.kind.toUpperCase();
+  const 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|OPENCODE_CONFIG_DIR|KILO_CONFIG)$/i.test(key)) delete env[key];
+  Object.assign(env, { XDG_CONFIG_HOME: join(saved.profile, "config"), XDG_DATA_HOME: join(saved.profile, "data"), XDG_CACHE_HOME: join(saved.profile, "cache"),
+    [saved.kind === "opencode" ? "OPENCODE_CONFIG" : "KILO_CONFIG"]: saved.configPath, DO_NOT_TRACK: "1" });
+  const cache = join(saved.profile, "data", saved.kind, "mcp-auth.json");
+  const now = options.now ?? Date.now;
+  let client, connectedToken, connectedUntil, closed = false, closing;
+  const refreshRequired = () => fail(prefix + "_MCP_AUTH_REFRESH_REQUIRED");
+  async function inspect() {
+    if (closed) throw fail(prefix + "_MCP_CLOSED");
+    const profile = await lstat(saved.profile);
+    if (!profile.isDirectory() || profile.isSymbolicLink() || (typeof process.getuid === "function" && profile.uid !== process.getuid()) ||
+      (process.platform !== "win32" && (profile.mode & 0o777) !== 0o700)) throw fail(prefix + "_MCP_PROFILE_CHANGED");
+    for (const path of [saved.configPath, cache]) if (await realpath(path) !== resolve(path)) throw fail(prefix + "_MCP_PROFILE_CHANGED");
+    const config = await privateRead(saved.configPath), server = config.mcp?.[saved.serverName];
+    if (server?.enabled === false) throw fail("LISTENER_PAUSED");
+    let url;
+    try { url = new URL(server?.url); } catch { /* Reject below. */ }
+    if (server?.type !== "remote" || server.oauth === false || Object.keys(server.headers ?? {}).length ||
+      !url || url.origin !== "https://totemlayer.com" || url.pathname !== "/mcp" || url.username || url.password || url.hash || url.search ||
+      openCodeMcpBindingFingerprint(server) !== saved.serverFingerprint) throw fail(prefix + "_MCP_CONFIG_CHANGED");
+    const entry = (await privateRead(cache))[saved.serverName];
+    if (entry?.serverUrl !== server.url || typeof entry.tokens?.accessToken !== "string" || !entry.tokens.accessToken ||
+      !Number.isFinite(entry.tokens.expiresAt) || entry.tokens.expiresAt <= 0 || entry.tokens.expiresAt > Number.MAX_SAFE_INTEGER / 1000) throw fail("AGENT_AUTH_REQUIRED");
+    return { server, entry };
+  }
+  async function native(args, signal) {
+    return (options.execute ?? execute)(saved.binary, ["--pure", ...args], { env, cwd: saved.cwd, signal, timeout: 20000, maxBuffer: 65536, windowsHide: true });
+  }
+  async function close() { closed = true; closing ??= Promise.resolve().then(() => client?.close()); await closing; }
+  try {
+    const version = await native(["--version"], options.signal);
+    if (version.stdout.trim() !== saved.nativeVersion) throw fail(prefix + "_VERSION_CHANGED");
+    let current = await inspect();
+    if (current.entry.tokens.expiresAt * 1000 <= now() + 15000) {
+      await native(["mcp", "list"], options.signal);
+      current = await inspect();
+      // A saved refresh token can still recover after a missed renewal.
+      const { expiresAt, refreshToken } = current.entry.tokens;
+      if (expiresAt * 1000 <= now() + 15000) {
+        if (expiresAt * 1000 < now() - 60000 && !(typeof refreshToken === "string" && refreshToken))
+          throw fail("AGENT_AUTH_REQUIRED");
+        throw refreshRequired();
+      }
+    }
+    if (options.signal?.aborted) throw fail("RUN_CANCELLED");
+    await (options.configureProxy ?? configureEnvironmentProxy)();
+    const sdk = options.createClient && options.createTransport ? undefined : await import("@modelcontextprotocol/client");
+    client = options.createClient ? options.createClient() : new sdk.Client({ name: "totem-native-" + saved.kind + "-checker", version: "1" });
+    connectedToken = current.entry.tokens.accessToken;
+    connectedUntil = current.entry.tokens.expiresAt * 1000;
+    const transport = options.createTransport ? options.createTransport() : new sdk.StreamableHTTPClientTransport(new URL(current.server.url), {
+      requestInit: { headers: { authorization: "Bearer " + current.entry.tokens.accessToken } },
+    });
+    await client.connect(transport, { signal: options.signal, timeout: 20000 });
+    const advertised = (await client.listTools({}, { signal: options.signal, timeout: 20000 })).tools;
+    return {
+      nativeIncoming: false,
+      listTools: () => advertised.filter(tool => checkers.has(tool.name)),
+      async call(name, args, { signal } = {}) {
+        if (!checkers.has(name)) throw fail("MCP_TOOL_UNAVAILABLE");
+        const current = await inspect();
+        if (signal?.aborted) throw fail("RUN_CANCELLED");
+        // requestInit binds this client to one native token. A rotated cache or
+        // expiry must retire that channel before its next request; reconnect
+        // uses the native client's refresh flow and preserves the receiver lease.
+        if (current.entry.tokens.accessToken !== connectedToken || connectedUntil <= now() + 15000) throw refreshRequired();
+        try { return await client.callTool({ name, arguments: args }, undefined, { signal, timeout: 20000 }); }
+        catch (error) {
+          if (signal?.aborted) throw fail("RUN_CANCELLED");
+          if (error.status === 401) {
+            const latest = await inspect();
+            if (latest.entry.tokens.accessToken !== connectedToken || connectedUntil <= now() + 15000) throw refreshRequired();
+          }
+          if (error.name === "TimeoutError" || error.code === -32001) throw fail("TIMEOUT");
+          const failure = fail(prefix + "_MCP_CALL_FAILED");
+          if (Number.isInteger(error.status) && error.status >= 400 && error.status <= 599) failure.status = error.status;
+          throw failure;
+        }
+      }, close,
+    };
+  } catch (error) {
+    await close().catch(() => {});
+    if (error.status === 401 && connectedUntil <= now() + 15000) throw refreshRequired();
+    const failure = fail(/^[A-Z0-9_]{1,100}$/.test(error.code ?? "") ? error.code : options.signal?.aborted ? "RUN_CANCELLED" : prefix + "_MCP_UNAVAILABLE");
+    if (Number.isInteger(error.status) && error.status >= 400 && error.status <= 599) failure.status = error.status;
+    throw failure;
+  }
+}

package/bin/native-opencode-receiver.mjs

@@ -0,0 +1,22 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { privateRead } from "./runtime-installation.mjs";
+import { createOpenCodeNativeBridge } from "./native-opencode-bridge.mjs";
+import { createOpenCodeMcpSurface } from "./native-opencode-mcp.mjs";
+import { runNativeInboxReceiver } from "./native-inbox-receiver.mjs";
+
+export function runOpenCodeNativeReceiver(config, options = {}) {
+  const kind = config?.native?.kind;
+  if (!["opencode", "kilo"].includes(kind) || config.mcp?.kind !== kind || config.mcp.profile !== config.native.profile || config.mcp.configPath !== config.native.configPath)
+    throw Object.assign(new Error("Native profile binding changed"), { code: "NATIVE_OPENCODE_RECEIVER_CONFIG_INVALID" });
+  return runNativeInboxReceiver(config, { kind, createBridge: createOpenCodeNativeBridge, createSurface: createOpenCodeMcpSurface }, options);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  const controller = new AbortController(), stop = () => controller.abort();
+  process.once("SIGTERM", stop); process.once("SIGINT", stop);
+  try {
+    const result = await runOpenCodeNativeReceiver(await privateRead(resolve(process.argv[2])), { signal: controller.signal });
+    if (result.state === "paused") await new Promise(resolve => { if (controller.signal.aborted) resolve(); else controller.signal.addEventListener("abort", resolve, { once: true }); });
+  } catch (error) { process.stderr.write(/^[A-Z0-9_]{1,100}$/.test(error.code ?? "") ? error.code + "\n" : "NATIVE_OPENCODE_RECEIVER_FAILED\n"); process.exitCode = 1; }
+  finally { process.off("SIGTERM", stop); process.off("SIGINT", stop); }
+}