totemlayer 0.1.42 → 0.1.59

package/bin/mcp-install.mjs

@@ -1,3 +1,5 @@
+import { parseArgs } from "node:util";
+import { buildMcpConfig } from "./mcp-config.mjs";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { stat, lstat } from "node:fs/promises";
@@ -15,21 +17,33 @@ 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 claude             Add hosted MCP and open one OAuth approval
+  totem mcp install codex              Add hosted MCP and open one OAuth approval
+  totem mcp install generic            HTTP settings for other hosts
+  totem mcp config                     HTTP settings for any MCP client
+  totem mcp config --transport stdio --key-file /absolute/path/to/agent.key
+  totem mcp config --format muse       Muse Code settings
   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
 
 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)
+  --name <name>        MCP name (default: totem, or totem-local with --key-file)
+  --key-file <path>    Use an existing private agent key for local stdio instead
   --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
+Without --key-file, this uses the client's native hosted MCP and OAuth support.
+The client saves credentials privately. No Totem website guide, copied key,
+local worker, or model change is required. Existing connections are preserved.
+The host may require reloading tools after adding a server. Call
+totem_get_identity in that host to verify the selected identity and access.
+
+With --key-file, 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.
@@ -82,8 +96,7 @@ function parseInstallArgs(args, environment) {
     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;
+  const name = values["--name"] ?? (keyFile ? DEFAULT_NAME : "totem");
   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.",
@@ -118,7 +131,7 @@ function parseInstallArgs(args, environment) {
     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),
+    keyFile: keyFile ? resolve(keyFile) : undefined,
     name,
     baseUrl: url.origin,
     ...loadMcpIdentityBinding({
@@ -152,16 +165,46 @@ async function validateKeyFile(path, platform) {
     fail("The Totem agent key file must be private (mode 0600). Fix its permissions and retry.");
 }
 
+export async function configureTotemMcp(args, environment = process.env, runtime = {}) {
+  const flags = parseArgs({
+    args,
+    strict: true,
+    options: {
+      transport: { type: "string", default: "http" },
+      format: { type: "string", default: "generic" },
+      name: { type: "string", default: "totem" },
+      "base-url": { type: "string" },
+      "key-file": { type: "string" },
+      "agent-id": { type: "string" },
+      environment: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+  }).values;
+  if (flags.help) return MCP_INSTALL_HELP;
+  const keyFile = flags["key-file"] ?? environment.TOTEM_NETWORK_API_KEY_FILE;
+  const config = buildMcpConfig({
+    baseUrl: flags["base-url"] ?? environment.TOTEM_BASE_URL ?? DEFAULT_ORIGIN,
+    transport: flags.transport,
+    format: flags.format,
+    name: flags.name,
+    keyFile: keyFile ? resolve(keyFile) : undefined,
+    expectedAgentId: flags["agent-id"] ?? environment.TOTEM_EXPECTED_AGENT_ID,
+    expectedEnvironment: flags.environment ?? environment.TOTEM_EXPECTED_ENVIRONMENT,
+    command: process.execPath,
+    args: [runtime.serverEntry ?? SERVER_ENTRY, "mcp"],
+  });
+  if (flags.transport === "stdio")
+    await validateKeyFile(resolve(keyFile), runtime.platform ?? process.platform);
+  return JSON.stringify(config, null, 2) + "\n";
+}
+
 function runClient(command, args, environment, runtime) {
-  const invocation =
-    runtime.platform === "win32"
-      ? installedClientInvocation(command, args, environment)
-      : { command, args };
+  const invocation = installedClientInvocation(command, args, environment, runtime);
   const result = runtime.spawnProcess(invocation.command, invocation.args, {
     encoding: "utf8",
     env: environment,
-    stdio: ["ignore", "pipe", "pipe"],
-    timeout: 20_000,
+    stdio: runtime.stdio ?? ["ignore", "pipe", "pipe"],
+    timeout: runtime.timeoutMs ?? 20_000,
   });
   if (result.error?.code === "ENOENT")
     fail(
@@ -171,10 +214,98 @@ function runClient(command, args, environment, runtime) {
   return result;
 }
 
+function hostedEntryMatches(result, client, endpoint) {
+  if (result.status !== 0) return false;
+  if (client === "codex") {
+    try {
+      const entry = JSON.parse(result.stdout);
+      const transport = entry.transport;
+      return (
+        entry.enabled !== false &&
+        !entry.disabled_reason &&
+        transport?.type === "streamable_http" &&
+        transport.url === endpoint &&
+        !transport.bearer_token_env_var &&
+        Object.keys(transport.http_headers ?? {}).length === 0 &&
+        Object.keys(transport.env_http_headers ?? {}).length === 0
+      );
+    } catch {
+      return false;
+    }
+  }
+  // Claude currently exposes human-readable get output rather than a JSON export.
+  const output = String(result.stdout ?? "").replace(/\u001b\[[0-9;]*m/g, "");
+  const field = (name) => output.match(new RegExp(`^\\s*${name}:\\s*(.*)$`, "mi"))?.[1]?.trim();
+  return (
+    field("Type") === "http" &&
+    field("URL") === endpoint &&
+    !/^.*(?:disabled|rejected|pending approval)/im.test(field("Status") ?? "") &&
+    !/^\s*(?:Headers?|Authorization|Environment|headersHelper):/im.test(output)
+  );
+}
+
+async function installHostedTotemMcp(options, environment, runtime) {
+  const config = buildMcpConfig({
+    baseUrl: options.baseUrl,
+    name: options.name,
+    expectedAgentId: options.expectedAgentId,
+    expectedEnvironment: options.expectedEnvironment,
+  });
+  if (options.client === "generic") return JSON.stringify(config, null, 2) + "\n";
+  if (options.codexThreadId)
+    fail(
+      "--codex-thread requires local stdio setup with --key-file. Hosted MCP does not bind a desktop chat.",
+    );
+  const endpoint = config.mcpServers[options.name].url;
+  const env = localClientEnvironment(environment);
+  const getArgs = ["mcp", "get", options.name, ...(options.client === "codex" ? ["--json"] : [])];
+  const inspect = () => runClient(options.client, getArgs, env, runtime);
+  let entry = inspect();
+  if (entry.status === 0 && !hostedEntryMatches(entry, options.client, endpoint))
+    fail(
+      `${options.name} already exists with different or disabled settings. It was preserved; inspect that exact connection before continuing.`,
+    );
+  if (entry.status !== 0) {
+    if (!/no mcp server|not found|does not exist/i.test(`${entry.stderr}\n${entry.stdout}`))
+      fail("The client could not check its existing MCP settings. No configuration was changed.");
+    const args =
+      options.client === "claude"
+        ? ["mcp", "add", "--transport", "http", "--scope", "user", options.name, endpoint]
+        : ["mcp", "add", options.name, "--url", endpoint];
+    if (runClient(options.client, args, env, runtime).status !== 0)
+      fail(
+        "The host could not save Totem's MCP connection. Check its MCP configuration permissions.",
+      );
+    entry = inspect();
+    if (!hostedEntryMatches(entry, options.client, endpoint))
+      fail(
+        "Totem's saved MCP settings could not be verified. No sign-in was started; inspect the exact entry before retrying.",
+      );
+  }
+  const connected =
+    options.client === "claude" &&
+    /^\s*Status:\s*(?:✔\s*)?Connected\s*$/im.test(
+      String(entry.stdout ?? "").replace(/\u001b\[[0-9;]*m/g, ""),
+    );
+  if (!connected) {
+    const login = runClient(options.client, ["mcp", "login", options.name], env, {
+      ...runtime,
+      timeoutMs: 600_000,
+      stdio: "inherit",
+    });
+    if (login.status !== 0)
+      fail(
+        `Totem's settings are saved, but approval is incomplete. Finish this server's native MCP sign-in in ${options.client}; do not create another connection or switch identities. Older hosts may require their MCP sign-in panel.`,
+      );
+  }
+  return `Totem's hosted MCP settings are saved in ${options.client}. ${connected ? "The existing authenticated connection was reused." : "The client's OAuth approval completed; credentials stay in its private store."} Reload this host's tools if needed, then call totem_get_identity to verify the agent, organization and environment. Check incoming chat delivery separately.\n`;
+}
+
 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 };
+  if (!options.keyFile) return installHostedTotemMcp(options, environment, runtime);
   await validateKeyFile(options.keyFile, runtime.platform);
 
   if (options.client === "generic")

package/bin/mcp-listener.d.mts

@@ -0,0 +1,22 @@
+import type { Totem } from "./sdk/index.js";
+export function createAutomaticMcpListener(options: {
+  client: Totem;
+  authorize?: (signal: AbortSignal) => Promise<unknown>;
+  enabled?: () => Promise<boolean>;
+  notify: (logger: string, data: unknown, cursor?: string) => Promise<void>;
+  hostKind?: "local" | "hosted";
+  pollMs?: number;
+  cursors?: { cursor?: string; messageCursor?: string };
+  signal?: AbortSignal;
+}): {
+  start(): void;
+  stop(): Promise<void>;
+  done(): Promise<void>;
+  status(): {
+    state: string;
+    listenerReady: boolean;
+    executionAuthorized: boolean;
+    runId?: string;
+    code?: string;
+  };
+};

package/bin/mcp-listener.mjs

@@ -0,0 +1,4 @@
+export {
+  createAutomaticNetworkListener as createAutomaticMcpListener,
+  readTotemActivity,
+} from "./sdk/listener.js";

package/bin/mcp-runtime.mjs

@@ -17,7 +17,7 @@ function listenerBinding(profile) {
 
 /** 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)
+  if (environment.TOTEM_AUTO_START === "0" || (environment.CI && !options.connectionOnly))
     return { state: "disabled_by_request", ready: false, persistent: false };
   if (!options.keyFile)
     return {
@@ -122,6 +122,8 @@ export async function ensureMcpListener(config, environment = process.env, optio
       message:
         "This listener was explicitly stopped. Its opt-out remains in effect; totem start can resume it.",
     };
+  if (options.connectionOnly)
+    return { state: "managed", ready: false, ...listenerBinding(profile) };
   const activate = options.activate ?? (await import("./installation.mjs")).activateConnection;
   if (["codex", "claude"].includes(profile.client ?? profile.provider)) {
     try {