totemlayer 0.1.30 → 0.1.38

package/bin/mcp-install.mjs

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 
 import { installedClientInvocation, localClientEnvironment } from "./platform-client.mjs";
 import { runtimeRoot } from "./runtime-installation.mjs";
+import { loadMcpIdentityBinding } from "./mcp-identity-binding.mjs";
 
 const DEFAULT_ORIGIN = "https://totemlayer.com";
 const DEFAULT_NAME = "totem-local";
@@ -14,6 +15,7 @@ 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 generic --key-file /absolute/path/to/agent.key
   totem mcp install codex --key-file /absolute/path/to/agent.key
   totem mcp install claude --key-file /absolute/path/to/agent.key
 
@@ -21,13 +23,25 @@ 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)
+  --agent-id <UUID>    Require this credential-derived agent identity
+  --environment <env> Require PRODUCTION or SANDBOX
+  --codex-thread <ID>   Bind a new Codex listener to this owner-selected chat
+  --no-start           Configure tools only; do not start a local listener
   --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.
+Use --agent-id and --environment to reject an unintended agent or environment.
+Codex/Claude installation also prepares this exact identity's supervised listener
+for login and crash recovery. Existing stops and owner permissions remain in force.
 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.
+
+Use generic for any stdio MCP client: it prints JSON configuration without
+changing client settings or starting a background listener. Adapt the outer
+configuration wrapper to your client's schema. For hosted Streamable HTTP,
+connect directly to https://totemlayer.com/mcp using OAuth or a Bearer agent key.
 `;
 
 function fail(message) {
@@ -37,14 +51,29 @@ function fail(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.");
+  if (!["generic", "codex", "claude"].includes(client))
+    fail(
+      "Choose generic for any stdio MCP client, or codex or claude for automatic configuration. Run `totem mcp install --help` for examples.",
+    );
   const values = {};
   for (let index = 0; index < rest.length; index += 2) {
     const option = rest[index];
+    if (option === "--no-start") {
+      if (values[option]) fail("--no-start was provided more than once.");
+      values[option] = true;
+      index -= 1;
+      continue;
+    }
     const value = rest[index + 1];
     if (
-      !["--key-file", "--base-url", "--name"].includes(option) ||
+      ![
+        "--key-file",
+        "--base-url",
+        "--name",
+        "--agent-id",
+        "--environment",
+        "--codex-thread",
+      ].includes(option) ||
       !value ||
       value.startsWith("--")
     )
@@ -78,7 +107,41 @@ function parseInstallArgs(args, environment) {
     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 };
+  if (
+    values["--codex-thread"] &&
+    (client !== "codex" ||
+      !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(values["--codex-thread"]))
+  )
+    fail("--codex-thread requires codex and an owner-selected chat UUID.");
+  return {
+    client,
+    codexThreadId: values["--codex-thread"],
+    configDirectory: environment.TOTEM_CONFIG_DIR ? runtimeRoot(environment) : undefined,
+    noStart: values["--no-start"] === true || environment.TOTEM_AUTO_START === "0",
+    keyFile: resolve(keyFile),
+    name,
+    baseUrl: url.origin,
+    ...loadMcpIdentityBinding({
+      TOTEM_EXPECTED_AGENT_ID: values["--agent-id"] ?? environment.TOTEM_EXPECTED_AGENT_ID,
+      TOTEM_EXPECTED_ENVIRONMENT: values["--environment"] ?? environment.TOTEM_EXPECTED_ENVIRONMENT,
+    }),
+  };
+}
+
+function identityEnvironment(binding) {
+  return {
+    ...(binding.expectedAgentId ? { TOTEM_EXPECTED_AGENT_ID: binding.expectedAgentId } : {}),
+    ...(binding.expectedEnvironment
+      ? { TOTEM_EXPECTED_ENVIRONMENT: binding.expectedEnvironment }
+      : {}),
+  };
+}
+
+function managedIdentityBinding(profile) {
+  return loadMcpIdentityBinding({
+    TOTEM_EXPECTED_AGENT_ID: profile.agentId,
+    TOTEM_EXPECTED_ENVIRONMENT: profile.environment,
+  });
 }
 
 async function validateKeyFile(path, platform) {
@@ -114,22 +177,68 @@ export async function installTotemMcp(args, environment = process.env, runtime =
   runtime = { platform: process.platform, spawnProcess: spawnSync, ...runtime };
   await validateKeyFile(options.keyFile, runtime.platform);
 
+  if (options.client === "generic")
+    return (
+      JSON.stringify(
+        {
+          mcpServers: {
+            [options.name]: {
+              command: process.execPath,
+              args: [runtime.serverEntry ?? SERVER_ENTRY, "mcp"],
+              env: {
+                TOTEM_BASE_URL: options.baseUrl,
+                TOTEM_NETWORK_API_KEY_FILE: options.keyFile,
+                ...identityEnvironment(options),
+                ...(options.noStart ? { TOTEM_AUTO_START: "0" } : {}),
+                ...(options.configDirectory ? { TOTEM_CONFIG_DIR: options.configDirectory } : {}),
+              },
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n"
+    );
+
   const command = options.client;
-  const existing = runClient(command, ["mcp", "get", options.name], environment, runtime);
-  if (existing.status === 0)
+  const getArgs = ["mcp", "get", options.name, ...(command === "codex" ? ["--json"] : [])];
+  const existing = runClient(command, getArgs, environment, runtime);
+  let sameEntry = false;
+  if (existing.status === 0 && command === "codex") {
+    try {
+      sameEntry = matchesManagedEntry(
+        JSON.parse(existing.stdout),
+        {
+          baseUrl: options.baseUrl,
+          credentialFile: options.keyFile,
+          agentId: options.expectedAgentId,
+          environment: options.expectedEnvironment,
+          noStart: options.noStart,
+          configDirectory: options.configDirectory,
+        },
+        options.name,
+        runtime.serverEntry ?? SERVER_ENTRY,
+      );
+    } catch {}
+  }
+  if (existing.status === 0 && !sameEntry)
     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}`))
+  if (
+    !sameEntry &&
+    !/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 envArgs = Object.entries({
+    TOTEM_BASE_URL: options.baseUrl,
+    TOTEM_NETWORK_API_KEY_FILE: options.keyFile,
+    ...identityEnvironment(options),
+    ...(options.noStart ? { TOTEM_AUTO_START: "0" } : {}),
+    ...(options.configDirectory ? { TOTEM_CONFIG_DIR: options.configDirectory } : {}),
+  }).flatMap(([key, value]) => ["--env", `${key}=${value}`]);
   const addArgs =
     options.client === "codex"
       ? [
@@ -156,17 +265,48 @@ export async function installTotemMcp(args, environment = process.env, runtime =
           runtime.serverEntry ?? SERVER_ENTRY,
           "mcp",
         ];
-  const added = runClient(command, addArgs, environment, runtime);
+  const added = sameEntry ? { status: 0 } : 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);
+  const verified = sameEntry ? existing : runClient(command, getArgs, 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`;
+  let listener = "";
+  if (!runtime.skipListenerSetup) {
+    try {
+      const config = await (runtime.loadConfig ?? (await import("./mcp.mjs")).loadTotemMcpConfig)({
+        TOTEM_BASE_URL: options.baseUrl,
+        TOTEM_NETWORK_API_KEY_FILE: options.keyFile,
+        ...identityEnvironment(options),
+      });
+      const status = await (
+        runtime.prepareListener ?? (await import("./mcp-runtime.mjs")).ensureMcpListener
+      )(
+        config,
+        { ...environment, ...(options.noStart ? { TOTEM_AUTO_START: "0" } : {}) },
+        {
+          allowCreate: true,
+          provider: options.client,
+          keyFile: options.keyFile,
+          codexThreadId: options.codexThreadId,
+        },
+      );
+      listener = ` Listener: ${status.state}${status.persistent === false ? " (login recovery is unavailable on this host)" : ""}.`;
+      if (["needs_attention", "setup_required"].includes(status.state))
+        fail(
+          "MCP settings were saved, but the listener needs attention. Run totem status or totem setup with this same agent's private key; no existing identity or permission was replaced.",
+        );
+    } catch {
+      fail(
+        "MCP settings were saved, but the listener could not confirm setup. Run totem status or totem setup with this same agent's private key; no existing identity or permission was replaced.",
+      );
+    }
+  }
+  return `Connected ${options.name} to ${command} at ${options.baseUrl}.${listener} Restart ${command}, then ask it to call totem_get_identity. The Totem CLI package must remain installed.\n`;
 }
 
 /** Guided setup owns a distinct entry per profile; the manual installer retains its default. */
@@ -179,7 +319,7 @@ export function managedMcpName(profileName) {
     : `totem_${profileName.slice(0, 24)}_${createHash("sha256").update(profileName).digest("hex").slice(0, 32)}`;
 }
 
-async function installedServerEntry(profile, environment) {
+async function installedServerEntry(profile) {
   if (!profile.stateDirectory) return SERVER_ENTRY;
   const path = join(resolve(profile.stateDirectory, "../../../.."), "runtime", "totem.mjs");
   try {
@@ -199,12 +339,11 @@ async function installedServerEntry(profile, environment) {
 }
 
 function managedArgs(profile, name, entry = SERVER_ENTRY) {
-  const variables = [
-    "--env",
-    `TOTEM_BASE_URL=${profile.baseUrl}`,
-    "--env",
-    `TOTEM_NETWORK_API_KEY_FILE=${profile.credentialFile}`,
-  ];
+  const variables = Object.entries({
+    TOTEM_BASE_URL: profile.baseUrl,
+    TOTEM_NETWORK_API_KEY_FILE: profile.credentialFile,
+    ...identityEnvironment(managedIdentityBinding(profile)),
+  }).flatMap(([key, value]) => ["--env", `${key}=${value}`]);
   return profile.client === "codex"
     ? ["mcp", "add", name, ...variables, "--", process.execPath, entry, "mcp"]
     : [
@@ -228,6 +367,9 @@ function matchesManagedEntry(entry, profile, name, serverEntry = SERVER_ENTRY) {
   const expectedEnvironment = {
     TOTEM_BASE_URL: profile.baseUrl,
     TOTEM_NETWORK_API_KEY_FILE: profile.credentialFile,
+    ...identityEnvironment(managedIdentityBinding(profile)),
+    ...(profile.noStart ? { TOTEM_AUTO_START: "0" } : {}),
+    ...(profile.configDirectory ? { TOTEM_CONFIG_DIR: profile.configDirectory } : {}),
   };
   return (
     entry?.name === name &&
@@ -243,7 +385,7 @@ function matchesManagedEntry(entry, profile, name, serverEntry = SERVER_ENTRY) {
     (transport.env_vars == null ||
       (Array.isArray(transport.env_vars) && transport.env_vars.length === 0)) &&
     transport.env &&
-    Object.keys(transport.env).length === 2 &&
+    Object.keys(transport.env).length === Object.keys(expectedEnvironment).length &&
     Object.entries(expectedEnvironment).every(([key, value]) => transport.env[key] === value) &&
     Object.keys(transport).every((key) =>
       ["type", "command", "args", "env", "env_vars", "cwd"].includes(key),
@@ -307,8 +449,23 @@ function reconnectAdvice(profile, name) {
   return `Inspect ${name} with \`${profile.client} mcp get ${name}\`. To replace that exact entry after reviewing it, run \`${profile.client} mcp remove ${name}\`, then \`totem setup --profile ${profile.profileName} --install-mcp\`. Other entries are preserved.`;
 }
 
+function missingBindingAdvice(entry, profile, name, serverEntry) {
+  const binding = managedIdentityBinding(profile);
+  if (
+    (binding.expectedAgentId || binding.expectedEnvironment) &&
+    matchesManagedEntry(
+      entry,
+      { ...profile, agentId: undefined, environment: undefined },
+      name,
+      serverEntry,
+    )
+  )
+    return `The existing entry matches this profile's key reference and origin, but lacks its expected identity binding${binding.expectedAgentId ? ` for agent ${binding.expectedAgentId}` : ""}${binding.expectedEnvironment ? ` in ${binding.expectedEnvironment}` : ""}. It was preserved; review and repair that exact entry. `;
+  return "";
+}
+
 export async function inspectManagedTotemMcp(profile, environment = process.env, runtime = {}) {
-  const serverEntry = await installedServerEntry(profile, environment);
+  const serverEntry = await installedServerEntry(profile);
   const inspected = await inspectEntry(profile, localClientEnvironment(environment), runtime);
   if (
     inspected.state === "present" &&
@@ -328,7 +485,7 @@ export async function inspectManagedTotemMcp(profile, environment = process.env,
   return {
     name: inspected.name,
     state: "needs_attention",
-    message: `${inspected.state === "unavailable" ? "The client configuration could not be read." : "The existing entry could not be verified against this saved profile."} ${reconnectAdvice(profile, inspected.name)}`,
+    message: `${missingBindingAdvice(inspected.entry, profile, inspected.name, serverEntry) || (inspected.state === "unavailable" ? "The client configuration could not be read. " : "The existing entry could not be verified against this saved profile. ")}${reconnectAdvice(profile, inspected.name)}`,
   };
 }
 
@@ -338,7 +495,7 @@ export async function installManagedTotemMcp(
   environment = process.env,
   runtime = {},
 ) {
-  const serverEntry = await installedServerEntry(profile, environment);
+  const serverEntry = await installedServerEntry(profile);
   if (!["codex", "claude"].includes(profile.client))
     fail("Choose an existing AI app for MCP setup.");
   try {
@@ -366,9 +523,11 @@ export async function installManagedTotemMcp(
           profile.baseUrl,
           "--name",
           name,
+          ...(profile.agentId ? ["--agent-id", profile.agentId] : []),
+          ...(profile.environment ? ["--environment", profile.environment] : []),
         ],
         safeEnvironment,
-        { ...runtime, serverEntry },
+        { ...runtime, serverEntry, skipListenerSetup: true },
       );
       if (profile.client === "codex") {
         const after = await inspectEntry(profile, safeEnvironment, runtime);
@@ -404,9 +563,18 @@ export async function installManagedTotemMcp(
       state: "configured_unverified",
       message: `${name} already matches this profile; nothing changed. Verify its identity in your AI app with totem_get_identity.`,
     };
+  const missingBinding = missingBindingAdvice(inspected.entry, profile, name, serverEntry);
+  if (missingBinding)
+    return {
+      name,
+      state: "needs_attention",
+      message: `${missingBinding}${guidance}`,
+    };
   const ownsPrevious =
     previousProfile?.profileName === profile.profileName &&
     previousProfile.client === profile.client &&
+    JSON.stringify(managedIdentityBinding(previousProfile)) ===
+      JSON.stringify(managedIdentityBinding(profile)) &&
     inspected.state === "present" &&
     matchesManagedEntry(
       inspected.entry,

package/bin/mcp-runtime.mjs

@@ -0,0 +1,169 @@
+import { opendir } from "node:fs/promises";
+import { join } from "node:path";
+import { Totem } from "./sdk/index.js";
+import { readAgentCredential, readAgentProfile } from "./agent-profile.mjs";
+import { runtimeRoot } from "./runtime-installation.mjs";
+import { automaticEnabled } from "./automatic-runtime.mjs";
+
+function listenerBinding(profile) {
+  return {
+    profile: profile.profileName,
+    agentId: profile.agentId,
+    environment: profile.environment,
+    codexThreadId: profile.codexThreadId ?? null,
+  };
+}
+
+/** Recover only the exact credential-bound profile. MCP transport grants no new host authority. */
+export async function ensureMcpListener(config, environment = process.env, options = {}) {
+  if (environment.TOTEM_AUTO_START === "0" || environment.CI)
+    return { state: "disabled_by_request", ready: false, persistent: false };
+  if (!options.keyFile)
+    return {
+      state: "setup_required",
+      ready: false,
+      message:
+        "Tools are connected. Use explicit local setup with this agent's private key file to configure a listener; hosted or secret-only MCP transport does not install host software.",
+    };
+  const client = options.client ?? new Totem({ ...config, timeoutMs: 5000, maxRetries: 0 });
+  const identity = await client.agent();
+  if (
+    !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(identity?.id ?? "") ||
+    !["PRODUCTION", "SANDBOX"].includes(identity?.environment) ||
+    (config.expectedAgentId && identity.id !== config.expectedAgentId) ||
+    (config.expectedEnvironment && identity.environment !== config.expectedEnvironment)
+  )
+    throw new Error("The MCP credential does not match the selected Totem identity.");
+  const profiles = [];
+  try {
+    const entries = await opendir(join(runtimeRoot(environment), "connections"));
+    for await (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const profile = await readAgentProfile(entry.name, { environment });
+      if (
+        profile.agentId === identity.id &&
+        profile.baseUrl === config.baseUrl &&
+        profile.environment === identity.environment
+      )
+        profiles.push(profile);
+    }
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (profiles.length > 1)
+    return {
+      state: "needs_attention",
+      ready: false,
+      message:
+        "Multiple saved listeners match this identity. Select the intended profile with totem setup; no profile was changed.",
+    };
+  let profile = profiles[0];
+  if (profile && options.codexThreadId && profile.codexThreadId !== options.codexThreadId)
+    return {
+      state: "needs_attention",
+      ready: false,
+      message:
+        "The saved profile has a different executor/chat binding. Stop and explicitly repair that exact profile; it was not rebound.",
+    };
+  if (profile && (await readAgentCredential(profile)) !== config.apiKey)
+    return {
+      state: "needs_attention",
+      ready: false,
+      message:
+        "The saved listener uses another credential generation. Repair that exact profile with totem setup; its credential was preserved.",
+    };
+  if (!profile) {
+    if (!options.allowCreate || !["codex", "claude"].includes(options.provider) || !options.keyFile)
+      return {
+        state: "setup_required",
+        ready: false,
+        message:
+          "MCP tools are connected, but this identity has no saved listener on this computer. The owner must run totem setup with this agent's private key and selected executor once. Hosted MCP cannot install a local listener.",
+      };
+    const setup = options.setup ?? (await import("./agent-setup.mjs")).agentSetupMain;
+    let output = "";
+    const result = await setup(
+      [
+        "--profile",
+        identity.id,
+        "--provider",
+        options.provider,
+        "--key-file",
+        options.keyFile,
+        "--base-url",
+        config.baseUrl,
+        "--agent-id",
+        identity.id,
+        "--no-mcp",
+        "--json",
+        ...(options.codexThreadId ? ["--codex-thread", options.codexThreadId] : []),
+      ],
+      {
+        env: environment,
+        stdout: {
+          write(chunk) {
+            output = (output + chunk).slice(-65536);
+          },
+        },
+        stderr: { write() {} },
+      },
+    );
+    if (result)
+      return {
+        state: "needs_attention",
+        ready: false,
+        message:
+          "MCP tools are connected. The listener setup did not confirm readiness; inspect totem status. No repository or peer permission was added.",
+      };
+    profile = await readAgentProfile(identity.id, { environment });
+    const created = JSON.parse(output);
+    if (!created.automatic) throw new Error("Listener setup did not return its startup status.");
+    return { ...created.automatic, ...listenerBinding(profile) };
+  }
+  if (!(await automaticEnabled(profile)))
+    return {
+      state: "paused",
+      ready: false,
+      ...listenerBinding(profile),
+      message:
+        "This listener was explicitly stopped. Its opt-out remains in effect; totem start can resume it.",
+    };
+  const activate = options.activate ?? (await import("./installation.mjs")).activateConnection;
+  const status = await activate(profile, environment);
+  return { ...status, ...listenerBinding(profile) };
+}
+
+/** Status reads never start workers, rotate credentials or change an owner's pause. */
+export async function readMcpListenerStatus(config, environment, initial, options = {}) {
+  if (!initial.profile) return initial;
+  try {
+    const profile = await readAgentProfile(initial.profile, { environment });
+    if (
+      profile.agentId !== initial.agentId ||
+      profile.baseUrl !== config.baseUrl ||
+      profile.environment !== initial.environment ||
+      (profile.codexThreadId ?? null) !== initial.codexThreadId ||
+      (config.expectedEnvironment && profile.environment !== config.expectedEnvironment) ||
+      (await readAgentCredential(profile)) !== config.apiKey
+    )
+      throw new Error("Listener binding changed");
+    const status = { ...initial, ready: false, checkedAt: new Date().toISOString() };
+    if (!(await automaticEnabled(profile))) return { ...status, state: "paused" };
+    const readStatus =
+      options.readStatus ?? (await import("./agent-runner.mjs")).readAgentRuntimeStatus;
+    const current = await readStatus(profile);
+    return {
+      ...status,
+      ...current,
+      state: !current.running ? "offline" : current.ready ? "ready" : "needs_attention",
+      ready: Boolean(current.running && current.ready),
+    };
+  } catch {
+    return {
+      state: "needs_attention",
+      ready: false,
+      message:
+        "The saved listener binding or current status could not be verified. No startup was attempted.",
+    };
+  }
+}