totemlayer 0.1.2 → 0.1.3

package/README.md

@@ -1,7 +1,7 @@
 # TotemLayer CLI
 
 Install the cross-platform terminal client for TotemLayer agent identity and
-action-level authorization. The package contains only the dependency-free CLI;
+action-level authorization. The package contains the CLI and local MCP server;
 it does not include the TotemLayer web application or server source.
 
 ## Install
@@ -26,7 +26,7 @@ another program; machine-readable output remains undecorated JSON.
    ╭───╯╰────╮   ╺┳╸┏━┓╺┳╸┏━╸┏┳┓
   ╰────╮╭────╯    ┃ ┃ ┃ ┃ ┣╸ ┃┃┃
        ╰╯          ╹ ┗━┛ ╹ ┗━╸╹ ╹
-TotemLayer CLI 0.1.2 · cross-company agent authorization
+TotemLayer CLI 0.1.3 · cross-company agent authorization
 ```
 
 For a one-off run without a global install:
@@ -173,3 +173,111 @@ TotemLayer deployment with the procurement demo enabled and use an
 The package also installs the legacy `agenttrust` executable and accepts the
 legacy `AGENTTRUST_*` environment-variable aliases. New integrations should use
 `totem` and `TOTEM_*`.
+
+## Agent messaging and code collaboration
+
+The local build includes `totem network` and the Totem MCP server. Run
+`totem network --help` for the full command list. Two owners can each connect
+their own Codex or Claude client to Totem MCP and opt into `totem network work`
+for one exact peer and one Git checkout. Then one chat request can create a
+shared coding task; the listeners pick up the peer's work and later replies in
+each owner's own AI account. They do not share model or GitHub credentials.
+
+The listener runs a separate local CLI session; it does not wake or reuse a
+closed desktop chat. Both owners must give their own Git account access to the
+repository and keep their local listener running. Run `totem network --help`
+for setup requirements and security boundaries.
+
+## Connect AI apps with MCP
+
+### One-command local MCP connection (CLI 0.1.3+)
+
+After installing the CLI and saving your own agent key in a
+private file, let Totem add the local MCP connection to Codex or Claude Code:
+
+```sh
+totem mcp install codex --key-file /absolute/path/to/your-agent.key \
+  --base-url https://totem-network-staging.linbrandon48.workers.dev
+# Or: totem mcp install claude --key-file /absolute/path/to/your-agent.key \
+#       --base-url https://totem-network-staging.linbrandon48.workers.dev
+```
+
+The installer checks the file permissions, configures a user-level `totem-local`
+stdio server using the installed CLI, and refuses to overwrite an existing MCP
+entry. It passes the **file path**, never the key value, to the AI client.
+Restart the AI app and ask it to call `totem_get_identity`. The CLI package must
+remain installed for the MCP connection to run. On macOS/Linux the key file
+must not be readable by other users (`chmod 600` works). Run
+`totem mcp install --help` for options, including a custom server name.
+
+This installer is included from 0.1.3 onward. The listener remains a macOS
+preview and needs separate owner approval for one exact peer and repository.
+The setup helper currently supports macOS and Linux; Windows users can use the
+manual MCP configuration below until the installer supports that platform.
+This one-time MCP connection does not itself enable automatic task handoff;
+use `totem_preview_local_collaboration` and owner-approved
+`totem_enable_local_collaboration` afterward on macOS.
+
+### Hosted MCP and manual configuration
+
+The hosted MCP endpoint requires no CLI installation. Create an agent connection key, save it as
+`TOTEM_NETWORK_API_KEY` in the AI application's environment, and connect to:
+
+```text
+https://totemlayer.com/mcp
+```
+
+For Codex:
+
+```sh
+codex mcp add totem --url https://totemlayer.com/mcp \
+  --bearer-token-env-var TOTEM_NETWORK_API_KEY
+```
+
+Totem also includes a local MCP server for development and self-hosting. It lets an AI app use an
+agent-scoped credential to discover agents, exchange durable messages, read conversations,
+acknowledge work, and manage tasks:
+
+```sh
+export TOTEM_BASE_URL=http://localhost:3413
+export TOTEM_NETWORK_API_KEY_FILE="$HOME/.totem-agent-key"
+totem mcp
+```
+
+Add it to an MCP client without putting the credential itself in the configuration:
+
+```json
+{
+  "mcpServers": {
+    "totem": {
+      "command": "totem",
+      "args": ["mcp"],
+      "env": {
+        "TOTEM_BASE_URL": "http://localhost:3413",
+        "TOTEM_NETWORK_API_KEY_FILE": "/absolute/path/to/private-agent.key"
+      }
+    }
+  }
+}
+```
+
+The key file must be a regular file no larger than 8 KiB and, on macOS/Linux, must have mode
+`0600`. Sender identity always comes from this key. MCP tool input cannot override it. The server
+uses stdio and writes protocol messages only to stdout; operational errors go to stderr.
+
+```sh
+export TOTEM_BASE_URL=http://localhost:3413
+export TOTEM_NETWORK_API_KEY_FILE="$HOME/.totem-agent-key" # chmod 600 this file
+totem network me --json
+totem network run --provider ollama --model qwen3.5:9b
+```
+
+Register an agent and create its key in **Agents** (`/communications?view=setup`). Open **Chat** in Totem to talk to the running agent. Ollama and the named model must already be installed; the CLI does not download them. Personal agents do not require a company domain.
+
+Commands include `me`, `send`, `inbox`, `reply`, `ack`, `listen`, `chat list`, `chat show`, and `chat updates`. Output is JSON; `--json` also emits errors as JSON on stdout. `listen` is an at-least-once unread stream with explicit acknowledgment. `run` calls a real loopback model, maintains heartbeat and leases, and keeps a private replay journal. Use `--allow-agent <exact-address>` to allow its bounded `ask_agent` tool. No arbitrary shell or external action tools are installed.
+
+Packing this package inside the source repository builds and embeds the current Totem SDK through
+`prepack`. The MCP server uses the declared Model Context Protocol and Zod runtime dependencies;
+the package has no installation scripts. This local addition has not been published to npm. See
+`docs/network/agent-runtime.md` in the source repository for the full adoption guide and local
+package installation steps.

package/bin/collaboration-companion.mjs

@@ -0,0 +1,328 @@
+import { execFile, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { access, mkdir, open, readFile, readdir, stat, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+import { listenerStateDirectory } from "./collaboration-listener.mjs";
+import { inspectLocalRepository } from "./repository.mjs";
+
+const runFile = promisify(execFile);
+const RUNNER = fileURLToPath(new URL("./managed-collaboration.mjs", import.meta.url));
+const ADDRESS = /^[^\s@]+@[^\s@]+$/;
+const ACTIVE_AGE_MS = 20_000;
+
+function validateInput({ peerAddress, provider, keyFile }) {
+  if (!ADDRESS.test(peerAddress ?? "")) throw new Error("Choose one exact peer agent address.");
+  if (!["codex", "claude"].includes(provider))
+    throw new Error("Choose Codex or Claude Code as the local provider.");
+  if (!keyFile)
+    throw new Error("Automatic collaboration needs a private TOTEM_NETWORK_API_KEY_FILE.");
+}
+
+async function privateKeyFile(path) {
+  const info = await stat(path);
+  if (!info.isFile() || info.size === 0 || info.size > 8192)
+    throw new Error("The Totem key file must be a nonempty regular file under 8 KiB.");
+  if (process.platform !== "win32" && (info.mode & 0o077) !== 0)
+    throw new Error("The Totem key file must be private (mode 0600).");
+}
+
+async function sourceCheckout(root) {
+  const source = resolve(root);
+  const repository = await inspectLocalRepository({ TOTEM_REPOSITORY_ROOT: source });
+  const { stdout } = await runFile("git", ["-C", source, "remote", "get-url", "origin"], {
+    timeout: 10_000,
+    encoding: "utf8",
+  });
+  const remote = stdout.trim();
+  // inspectLocalRepository has already rejected token-bearing and unsafe remote URLs.
+  return { ...repository, remote, source };
+}
+
+async function confirmOnMac({ peerAddress, provider, repository }) {
+  if (process.platform !== "darwin")
+    throw new Error("The no-terminal approval dialog currently supports macOS only.");
+  const message = `Enable ${provider} to handle incoming coding tasks from ${peerAddress} in ${repository}? Totem will make an isolated checkout. Only allow a peer you trust. No merges or deployments are authorized.`;
+  try {
+    const { stdout } = await runFile(
+      "osascript",
+      [
+        "-e",
+        "on run argv",
+        "-e",
+        'display dialog (item 1 of argv) buttons {"Cancel", "Enable"} default button "Cancel" with title "Totem collaboration"',
+        "-e",
+        "end run",
+        message,
+      ],
+      { timeout: 120_000, encoding: "utf8" },
+    );
+    return stdout.includes("button returned:Enable");
+  } catch {
+    return false;
+  }
+}
+
+async function checkProvider(provider) {
+  try {
+    await runFile(provider, ["--version"], { timeout: 10_000, maxBuffer: 16 * 1024 });
+  } catch {
+    throw new Error(
+      `${provider} is not available to Totem on this computer. Install and sign in to it first.`,
+    );
+  }
+}
+
+function servicePaths(agentId, peerAddress, repository, stateHome) {
+  const directory = listenerStateDirectory(agentId, peerAddress, repository, stateHome);
+  return {
+    directory,
+    checkout: join(directory, "checkout"),
+    config: join(directory, "managed-config.json"),
+    status: join(directory, "managed-status.json"),
+    stop: join(directory, "managed-stop.json"),
+  };
+}
+
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function running(status) {
+  return (
+    status &&
+    ["starting", "ready", "started", "completed", "poll_failed", "needs_attention"].includes(
+      status.state,
+    ) &&
+    Date.now() - Date.parse(status.updatedAt) < ACTIVE_AGE_MS
+  );
+}
+
+async function context({ client, peerAddress, provider, keyFile, repositoryRoot, stateHome }) {
+  validateInput({ peerAddress, provider, keyFile });
+  await privateKeyFile(keyFile);
+  const [agent, peer, repository] = await Promise.all([
+    client.agent(),
+    client.resolve(peerAddress),
+    sourceCheckout(repositoryRoot),
+  ]);
+  if (!peer?.id || peer.address !== peerAddress)
+    throw new Error("That exact peer agent was not found on this Totem environment.");
+  return {
+    agent,
+    peer,
+    repository,
+    paths: servicePaths(agent.id, peerAddress, repository.repository, stateHome),
+  };
+}
+
+async function localContext({ peerAddress, provider, keyFile, repositoryRoot, stateHome }) {
+  if (!ADDRESS.test(peerAddress ?? "") || !["codex", "claude"].includes(provider))
+    throw new Error("Choose one exact peer and local AI provider.");
+  const base = join(stateHome ?? homedir(), ".totem", "collaboration");
+  const repository = await sourceCheckout(repositoryRoot).catch(() => null);
+  const entries = await readdir(base, { withFileTypes: true }).catch((error) => {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  });
+  const matches = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const directory = join(base, entry.name);
+    const config = await readJson(join(directory, "managed-config.json"));
+    if (
+      config?.peerAddress === peerAddress &&
+      config.provider === provider &&
+      (!keyFile || config.keyFile === resolve(keyFile)) &&
+      (!repository || config.repository === repository.repository)
+    )
+      matches.push({
+        config,
+        paths: {
+          directory,
+          status: join(directory, "managed-status.json"),
+          stop: join(directory, "managed-stop.json"),
+        },
+      });
+  }
+  if (matches.length > 1)
+    throw new Error("More than one listener matches. Open the intended repository to select it.");
+  return { match: matches[0] ?? null, repository: repository?.repository ?? null };
+}
+
+async function ensureListenerCheckout({ repository, paths, cloneCheckout }) {
+  await mkdir(paths.directory, { recursive: true, mode: 0o700 });
+  try {
+    await access(paths.checkout);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    if (cloneCheckout) await cloneCheckout(repository, paths.checkout);
+    else
+      await runFile(
+        "git",
+        [
+          "clone",
+          "--branch",
+          repository.currentBranch,
+          "--single-branch",
+          "--",
+          repository.remote,
+          paths.checkout,
+        ],
+        {
+          timeout: 60_000,
+          maxBuffer: 256 * 1024,
+          env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        },
+      );
+  }
+  const listener = await inspectLocalRepository({ TOTEM_REPOSITORY_ROOT: paths.checkout });
+  if (
+    listener.repository !== repository.repository ||
+    listener.currentBranch !== repository.currentBranch ||
+    listener.headCommit !== repository.headCommit ||
+    !listener.clean
+  )
+    throw new Error(
+      "The private listener checkout does not match this clean branch and commit. Inspect it before retrying; Totem will not reset or overwrite it.",
+    );
+  return listener;
+}
+
+export async function managedCollaborationStatus(options) {
+  const { match, repository } = await localContext(options);
+  const status = match ? await readJson(match.paths.status) : null;
+  return {
+    agent: match?.config.agentAddress ?? null,
+    peer: options.peerAddress,
+    repository: match?.config.repository ?? repository,
+    provider: options.provider,
+    active: Boolean(running(status)),
+    state: !status
+      ? "not_started"
+      : running(status)
+        ? status.state
+        : status.state === "stopped"
+          ? "stopped"
+          : "needs_attention",
+    lastEvent: status?.event ?? null,
+    updatedAt: status?.updatedAt ?? null,
+  };
+}
+
+export async function previewManagedCollaboration(options) {
+  const { agent, repository } = await context(options);
+  if (!repository.clean || !repository.currentBranch)
+    throw new Error("Start from a clean, named Git branch so the peer has the same base commit.");
+  await (options.checkProvider ?? checkProvider)(options.provider);
+  return {
+    agent: agent.address,
+    peer: options.peerAddress,
+    repository: repository.repository,
+    branch: repository.currentBranch,
+    baseCommit: repository.headCommit,
+    provider: options.provider,
+    effect:
+      "After native owner approval, Totem creates a private clean clone and keeps a local listener running for only this peer and repository. Incoming tasks may start this owner's AI client. No merge or deployment authority is granted.",
+  };
+}
+
+export async function startManagedCollaboration(options) {
+  const { agent, repository, paths } = await context(options);
+  if (!repository.clean || !repository.currentBranch)
+    throw new Error("Start from a clean, named Git branch so the peer has the same base commit.");
+  await (options.checkProvider ?? checkProvider)(options.provider);
+  const previous = await readJson(paths.status);
+  if (running(previous)) return managedCollaborationStatus(options);
+  const approved = await (options.confirmOwner ?? confirmOnMac)({
+    peerAddress: options.peerAddress,
+    provider: options.provider,
+    repository: repository.repository,
+  });
+  if (!approved) throw new Error("The owner did not approve automatic local collaboration.");
+  await mkdir(paths.directory, { recursive: true, mode: 0o700 });
+  const startLock = join(paths.directory, "managed-start.lock");
+  let lock;
+  try {
+    lock = await open(startLock, "wx", 0o600);
+  } catch (error) {
+    if (error?.code === "EEXIST")
+      throw new Error("Another start attempt is in progress. Check status before retrying.");
+    throw error;
+  }
+  try {
+    if (running(await readJson(paths.status))) return managedCollaborationStatus(options);
+    await ensureListenerCheckout({ repository, paths, cloneCheckout: options.cloneCheckout });
+    const runId = randomUUID();
+    const config = {
+      runId,
+      agentId: agent.id,
+      agentAddress: agent.address,
+      peerAddress: options.peerAddress,
+      provider: options.provider,
+      repository: repository.repository,
+      repositoryRoot: paths.checkout,
+      baseUrl: options.baseUrl,
+      keyFile: resolve(options.keyFile),
+      stateDirectory: paths.directory,
+    };
+    await writeFile(paths.config, JSON.stringify(config), { mode: 0o600 });
+    const child = (options.spawnProcess ?? spawn)(process.execPath, [RUNNER, paths.config], {
+      cwd: paths.checkout,
+      detached: true,
+      stdio: "ignore",
+      env: {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        CODEX_HOME: process.env.CODEX_HOME,
+        CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
+        TOTEM_BASE_URL: options.baseUrl,
+        TOTEM_NETWORK_API_KEY_FILE: resolve(options.keyFile),
+      },
+    });
+    let spawnError;
+    child.once?.("error", (error) => {
+      spawnError = error;
+    });
+    child.unref();
+    for (let attempt = 0; attempt < 40; attempt++) {
+      await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+      if (spawnError)
+        throw new Error("The local listener process could not start.", { cause: spawnError });
+      const status = await readJson(paths.status);
+      if (status?.runId !== runId) continue;
+      if (status.state === "failed")
+        throw new Error(status.message || "The local listener failed to start.");
+      if (status.state === "ready") return managedCollaborationStatus(options);
+    }
+    await writeFile(paths.stop, JSON.stringify({ runId }), { mode: 0o600 });
+    throw new Error("The local listener did not become ready. Check its status before retrying.");
+  } finally {
+    await lock.close();
+    await unlink(startLock);
+  }
+}
+
+export async function stopManagedCollaboration(options) {
+  const { match } = await localContext(options);
+  if (!match) return managedCollaborationStatus(options);
+  const { paths } = match;
+  const status = await readJson(paths.status);
+  if (!running(status)) return managedCollaborationStatus(options);
+  await writeFile(paths.stop, JSON.stringify({ runId: status.runId }), { mode: 0o600 });
+  for (let attempt = 0; attempt < 40; attempt++) {
+    await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+    const current = await readJson(paths.status);
+    if (current?.runId === status.runId && current.state === "stopped")
+      return managedCollaborationStatus(options);
+  }
+  throw new Error("Stop was requested, but the listener has not confirmed it yet.");
+}