totemlayer 0.1.2 → 0.1.4

package/bin/managed-collaboration.mjs

@@ -0,0 +1,94 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { runCollaborationListener } from "./collaboration-listener.mjs";
+import { loadTotemMcpConfig } from "./mcp.mjs";
+import { Totem } from "./sdk/index.js";
+
+const configPath = process.argv[2];
+if (!configPath) throw new Error("The managed listener needs its private configuration file.");
+const config = JSON.parse(await readFile(configPath, "utf8"));
+const statusPath = join(config.stateDirectory, "managed-status.json");
+const stopPath = join(config.stateDirectory, "managed-stop.json");
+const controller = new AbortController();
+let current = { state: "starting", event: null, message: null };
+let writes = Promise.resolve();
+
+function saveStatus(next = {}) {
+  current = { ...current, ...next };
+  const body = JSON.stringify({
+    runId: config.runId,
+    pid: process.pid,
+    ...current,
+    updatedAt: new Date().toISOString(),
+  });
+  writes = writes.then(async () => {
+    const temporary = `${statusPath}.${process.pid}.tmp`;
+    await writeFile(temporary, body, { mode: 0o600 });
+    await rename(temporary, statusPath);
+  });
+  return writes;
+}
+
+async function checkStop() {
+  try {
+    const request = JSON.parse(await readFile(stopPath, "utf8"));
+    if (request.runId === config.runId) controller.abort();
+  } catch (error) {
+    if (error?.code !== "ENOENT")
+      await saveStatus({ event: "stop_check_failed", message: "Could not read stop request." });
+  }
+}
+
+const stop = () => controller.abort();
+process.once("SIGTERM", stop);
+process.once("SIGINT", stop);
+const stopTimer = setInterval(() => void checkStop(), 1000);
+const heartbeat = setInterval(() => void saveStatus(), 5000);
+
+try {
+  await saveStatus();
+  const credentials = await loadTotemMcpConfig({
+    TOTEM_BASE_URL: config.baseUrl,
+    TOTEM_NETWORK_API_KEY_FILE: config.keyFile,
+  });
+  const client = new Totem(credentials);
+  const identity = await client.agent({ signal: controller.signal });
+  if (identity.id !== config.agentId)
+    throw new Error("This key no longer belongs to the agent that enabled the listener.");
+  await runCollaborationListener({
+    client,
+    peerAddress: config.peerAddress,
+    provider: config.provider,
+    repositoryRoot: config.repositoryRoot,
+    stateDirectory: config.stateDirectory,
+    signal: controller.signal,
+    emit: (event) => {
+      const attention = [
+        "poll_failed",
+        "run_failed",
+        "checkout_mismatch",
+        "needs_attention",
+        "provider_mismatch",
+        "run_limit",
+      ].includes(event.type);
+      void saveStatus({
+        state: attention ? "needs_attention" : event.type === "ready" ? "ready" : current.state,
+        event: event.type,
+        message: event.type === "poll_failed" || event.type === "run_failed" ? event.message : null,
+      });
+    },
+  });
+  await saveStatus({ state: "stopped", event: "stopped", message: null });
+} catch (error) {
+  await saveStatus({
+    state: controller.signal.aborted ? "stopped" : "failed",
+    event: controller.signal.aborted ? "stopped" : "failed",
+    message: error instanceof Error ? error.message : "The local listener failed.",
+  });
+  if (!controller.signal.aborted) process.exitCode = 1;
+} finally {
+  clearInterval(stopTimer);
+  clearInterval(heartbeat);
+  await writes;
+}

package/bin/mcp-install.mjs

@@ -0,0 +1,159 @@
+import { spawnSync } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { installedClientInvocation } from "./platform-client.mjs";
+
+const DEFAULT_ORIGIN = "https://totemlayer.com";
+const DEFAULT_NAME = "totem-local";
+const SERVER_ENTRY = fileURLToPath(new URL("./totem.mjs", import.meta.url));
+
+export const MCP_INSTALL_HELP = `Connect Totem to an AI app
+
+Usage:
+  totem mcp install codex --key-file /absolute/path/to/agent.key
+  totem mcp install claude --key-file /absolute/path/to/agent.key
+
+Options:
+  --base-url <origin>  Totem origin (default: https://totemlayer.com)
+  --name <name>        MCP server name (default: totem-local)
+  --key-file <path>    Existing private agent key file (required)
+  --help               Show this guide
+
+This installs a user-level local stdio MCP connection. It never puts the key
+value in a command, client config, or repository. It will not overwrite an
+existing MCP server. Restart the AI app afterward and ask for totem_get_identity.
+On macOS/Linux the key file must be mode 0600. On Windows, protect it with
+your user's filesystem ACL. The package must remain installed.
+`;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function parseInstallArgs(args, environment) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) return { help: true };
+  const [client, ...rest] = args;
+  if (client !== "codex" && client !== "claude")
+    fail("Choose codex or claude. Run `totem mcp install --help` for examples.");
+  const values = {};
+  for (let index = 0; index < rest.length; index += 2) {
+    const option = rest[index];
+    const value = rest[index + 1];
+    if (
+      !["--key-file", "--base-url", "--name"].includes(option) ||
+      !value ||
+      value.startsWith("--")
+    )
+      fail(`Invalid option ${option ?? ""}. Run \`totem mcp install --help\`.`);
+    if (values[option] !== undefined) fail(`${option} was provided more than once.`);
+    values[option] = value;
+  }
+  const keyFile = values["--key-file"] ?? environment.TOTEM_NETWORK_API_KEY_FILE;
+  if (!keyFile) fail("Pass --key-file with the path to your own Totem agent key file.");
+  const name = values["--name"] ?? DEFAULT_NAME;
+  if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name))
+    fail(
+      "The MCP name must be 1-64 letters, numbers, hyphens or underscores and start with a letter.",
+    );
+  const rawOrigin = values["--base-url"] ?? environment.TOTEM_BASE_URL ?? DEFAULT_ORIGIN;
+  let url;
+  try {
+    url = new URL(rawOrigin);
+  } catch {
+    fail("--base-url must be a valid HTTPS origin (or HTTP loopback for local development).");
+  }
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/" ||
+    (url.protocol !== "https:" &&
+      !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+  )
+    fail(
+      "--base-url must be a credential-free HTTPS origin (or HTTP loopback for local development).",
+    );
+  return { client, keyFile: resolve(keyFile), name, baseUrl: url.origin };
+}
+
+async function validateKeyFile(path, platform) {
+  const info = await stat(path);
+  if (!info.isFile() || info.size === 0 || info.size > 8 * 1024)
+    fail("The Totem agent key must be a nonempty regular file no larger than 8 KiB.");
+  if (platform !== "win32" && (info.mode & 0o077) !== 0)
+    fail("The Totem agent key file must be private (mode 0600). Fix its permissions and retry.");
+}
+
+function runClient(command, args, environment, runtime) {
+  const invocation =
+    runtime.platform === "win32"
+      ? installedClientInvocation(command, args, environment)
+      : { command, args };
+  const result = runtime.spawnProcess(invocation.command, invocation.args, {
+    encoding: "utf8",
+    env: environment,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 20_000,
+  });
+  if (result.error?.code === "ENOENT")
+    fail(
+      `${command} is not installed or is not on PATH. Install and sign in to that AI client first.`,
+    );
+  if (result.error) fail(`${command} could not complete MCP setup: ${result.error.message}`);
+  return result;
+}
+
+export async function installTotemMcp(args, environment = process.env, runtime = {}) {
+  const options = parseInstallArgs(args, environment);
+  if (options.help) return MCP_INSTALL_HELP;
+  runtime = { platform: process.platform, spawnProcess: spawnSync, ...runtime };
+  await validateKeyFile(options.keyFile, runtime.platform);
+
+  const command = options.client;
+  const existing = runClient(command, ["mcp", "get", options.name], environment, runtime);
+  if (existing.status === 0)
+    fail(
+      `${options.name} already exists in ${command}. No configuration was changed. Choose another --name or inspect the existing connection first.`,
+    );
+  if (!/no mcp server|not found|does not exist/i.test(`${existing.stderr}\n${existing.stdout}`))
+    fail(
+      `${command} could not check whether ${options.name} already exists. No configuration was changed.`,
+    );
+  const envArgs = [
+    "--env",
+    `TOTEM_BASE_URL=${options.baseUrl}`,
+    "--env",
+    `TOTEM_NETWORK_API_KEY_FILE=${options.keyFile}`,
+  ];
+  const addArgs =
+    options.client === "codex"
+      ? ["mcp", "add", options.name, ...envArgs, "--", process.execPath, SERVER_ENTRY, "mcp"]
+      : [
+          "mcp",
+          "add",
+          ...envArgs,
+          "--scope",
+          "user",
+          "--transport",
+          "stdio",
+          options.name,
+          "--",
+          process.execPath,
+          SERVER_ENTRY,
+          "mcp",
+        ];
+  const added = runClient(command, addArgs, environment, runtime);
+  if (added.status !== 0)
+    fail(
+      `${command} could not add ${options.name}. No Totem key value was sent. Check the client's MCP setup and retry.`,
+    );
+  const verified = runClient(command, ["mcp", "get", options.name], environment, runtime);
+  if (verified.status !== 0)
+    fail(
+      `${command} reported an install, but ${options.name} could not be verified. Inspect its MCP settings before using it.`,
+    );
+  return `Connected ${options.name} to ${command} at ${options.baseUrl}. Restart ${command}, then ask it to call totem_get_identity. The Totem CLI package must remain installed.\n`;
+}