totemlayer 0.1.5 → 0.1.11

package/bin/automatic-runtime.mjs

@@ -0,0 +1,131 @@
+import { opendir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { readAgentProfile } from "./agent-profile.mjs";
+import { agentStartMain, readAgentRuntimeStatus } from "./agent-runner.mjs";
+import {
+  privateDirectory,
+  privateRead,
+  privateWrite,
+  runtimeRoot,
+} from "./runtime-installation.mjs";
+import { resumeDeviceLogin } from "./device-login.mjs";
+
+export async function setAutomaticEnabled(profile, enabled) {
+  await privateWrite(join(profile.stateDirectory, "automatic.json"), { enabled });
+}
+export async function automaticEnabled(profile) {
+  try {
+    return (await privateRead(join(profile.stateDirectory, "automatic.json"))).enabled === true;
+  } catch (error) {
+    if (error.code === "ENOENT") return true;
+    throw error;
+  }
+}
+export async function superviseOnce(env = process.env, options = {}) {
+  const directory = join(runtimeRoot(env), "runtime");
+  await Promise.resolve((options.resumeLogin ?? resumeDeviceLogin)({ directory }, env)).catch(
+    () => {},
+  );
+  let profiles;
+  try {
+    profiles = await opendir(join(runtimeRoot(env), "connections"));
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const results = [];
+  for await (const entry of profiles) {
+    if (!entry.isDirectory()) continue;
+    try {
+      const profile = await readAgentProfile(entry.name, { environment: env });
+      if (!(await automaticEnabled(profile))) continue;
+      const state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+      if (state.running) continue;
+      // The run-local journal decides whether any interrupted work can safely resume.
+      await (options.start ?? agentStartMain)(["--profile", entry.name, "--background", "--json"], {
+        env,
+        automatic: true,
+        stdout: { write() {} },
+      });
+      results.push(entry.name);
+    } catch {
+      /* One offline/revoked connection cannot stop other profiles. */
+    }
+  }
+  return results;
+}
+export async function automaticRuntimeMain(env = process.env, options = {}) {
+  const directory = join(runtimeRoot(env), "runtime");
+  await privateDirectory(directory);
+  const lock = join(directory, "supervisor.lock");
+  await import("node:fs/promises").then(async ({ mkdir }) => {
+    try {
+      await mkdir(lock, { mode: 0o700 });
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const current = await privateRead(join(lock, "owner.json")).catch(() => null);
+      if (!current || !Number.isInteger(current.pid))
+        throw new Error("Another supervisor is starting. Wait before retrying.");
+      try {
+        process.kill(current.pid, 0);
+        throw new Error("The Totem supervisor is already running.");
+      } catch (failure) {
+        if (failure.code !== "ESRCH") throw failure;
+      }
+      await rm(lock, { recursive: true });
+      await mkdir(lock, { mode: 0o700 });
+    }
+  });
+  await privateWrite(join(lock, "owner.json"), { pid: process.pid });
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once("SIGTERM", stop);
+  process.once("SIGINT", stop);
+  try {
+    while (!controller.signal.aborted && !options.signal?.aborted) {
+      let environment = { ...env };
+      try {
+        environment = {
+          ...environment,
+          ...(await privateRead(join(directory, "environment.json"))),
+        };
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      try {
+        environment = {
+          ...environment,
+          ...(await privateRead(join(directory, "provider-environment.json"))),
+        };
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+
+      await privateWrite(join(directory, "supervisor.json"), {
+        pid: process.pid,
+        updatedAt: new Date().toISOString(),
+      });
+      await superviseOnce(environment, options);
+      await sleep(options.intervalMs ?? 5000, undefined, {
+        signal: options.signal
+          ? AbortSignal.any([controller.signal, options.signal])
+          : controller.signal,
+      }).catch(() => {});
+    }
+  } finally {
+    process.removeListener("SIGTERM", stop);
+    process.removeListener("SIGINT", stop);
+    await rm(lock, { recursive: true, force: true });
+  }
+}
+if (
+  process.argv[1] === fileURLToPath(import.meta.url) ||
+  process.argv[1]?.endsWith("/runtime/supervisor.mjs") ||
+  process.argv[1]?.endsWith("\\runtime\\supervisor.mjs")
+) {
+  await automaticRuntimeMain().catch(() => {
+    process.exitCode = 1;
+  });
+}

package/bin/cloud-bootstrap.mjs

@@ -0,0 +1,64 @@
+import { agentSetupMain, agentStatusMain } from "./agent-setup.mjs";
+import { agentStartMain } from "./agent-runner.mjs";
+import { installationMain } from "./installation.mjs";
+
+/** Run from the cloud environment's startup command; secrets stay in its store. */
+export async function cloudBootstrapMain(args = [], options = {}) {
+  const env = options.env ?? process.env;
+  const output = options.stdout ?? process.stdout;
+  if (args.includes("--help")) {
+    output.write(
+      "totem cloud setup [--provider codex|claude|qwen-local|command|http] [--repo-root <checkout>] [--install-mcp]\nProvision TOTEM_NETWORK_API_KEY or TOTEM_NETWORK_API_KEY_FILE and TOTEM_AGENT_ID in the environment secret/settings store. The setup command verifies the exact identity, saves a private profile, and starts its message and Mission worker.\n",
+    );
+    return 0;
+  }
+  if (!env.TOTEM_NETWORK_API_KEY && !env.TOTEM_NETWORK_API_KEY_FILE) {
+    const loginArgs = ["--no-browser"];
+    const selected = args.indexOf("--provider");
+    if (selected >= 0 && args[selected + 1]) loginArgs.push("--provider", args[selected + 1]);
+    if (args.includes("--json")) loginArgs.push("--json");
+    return installationMain(loginArgs, options);
+  }
+  const profile = env.TOTEM_AGENT_ID ?? "default";
+  const setup = [
+    "--profile",
+    profile,
+    ...(env.TOTEM_AGENT_ID ? ["--agent-id", env.TOTEM_AGENT_ID] : []),
+    "--base-url",
+    env.TOTEM_BASE_URL ?? "https://totemlayer.com",
+    "--json",
+    ...args,
+  ];
+
+  if (await agentSetupMain(setup, options)) return 1;
+  let readiness;
+  const probe = {
+    ...options,
+    stdout: {
+      write(value) {
+        output.write(value);
+        try {
+          readiness = JSON.parse(value);
+        } catch {
+          /* Only status JSON is inspected. */
+        }
+      },
+    },
+  };
+  if (await agentStatusMain(["--profile", profile, "--json"], probe)) return 1;
+  if (readiness?.checks?.model?.state !== "available") {
+    output.write(
+      JSON.stringify({
+        ok: false,
+        error: {
+          code: "CLOUD_EXECUTOR_UNAVAILABLE",
+          message:
+            "The cloud connection is saved, but its selected executor is unavailable. Install and authenticate that executor before startup.",
+        },
+      }) + "\n",
+    );
+    return 1;
+  }
+  if (await agentStartMain(["--profile", profile, "--background", "--json"], options)) return 1;
+  return agentStatusMain(["--profile", profile, "--json"], options);
+}

package/bin/collaboration-listener.mjs

@@ -7,9 +7,9 @@ import { setTimeout as sleep } from "node:timers/promises";
 
 import { inspectLocalRepository } from "./repository.mjs";
 import { localClientEnvironment, streamingClientInvocation } from "./platform-client.mjs";
+import { runFile } from "./mission-worker.mjs";
 
 const MAX_RUNS_PER_TASK = 16;
-const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
 const MAX_PROMPT_BYTES = 32 * 1024;
 const DEFAULT_RUN_TIMEOUT_MS = 15 * 60 * 1000;
 
@@ -84,7 +84,10 @@ function runnerCommand(provider, sessionId, platform = process.platform) {
   if (provider === "codex")
     invocation = sessionId
       ? { command: "codex", args: ["exec", "resume", "--json", sessionId, "-"] }
-      : { command: "codex", args: ["exec", "--sandbox", "workspace-write", "--json", "-"] };
+      : {
+          command: "codex",
+          args: ["exec", "--sandbox", "workspace-write", "--json", "-"],
+        };
   else if (provider === "claude")
     invocation = {
       command: "claude",
@@ -106,7 +109,9 @@ function runnerCommand(provider, sessionId, platform = process.platform) {
 }
 
 function runnerEnvironment(repositoryRoot, environment = process.env) {
-  return localClientEnvironment(environment, { TOTEM_REPOSITORY_ROOT: repositoryRoot });
+  return localClientEnvironment(environment, {
+    TOTEM_REPOSITORY_ROOT: repositoryRoot,
+  });
 }
 
 export async function runLocalCollaborationAgent({
@@ -120,79 +125,42 @@ export async function runLocalCollaborationAgent({
   spawnProcess = spawn,
 }) {
   const { command, args } = runnerCommand(provider, sessionId, platform);
-  return new Promise((resolveRun, rejectRun) => {
-    const child = spawnProcess(command, args, {
-      cwd: repositoryRoot,
-      env: runnerEnvironment(repositoryRoot),
-      stdio: ["pipe", "pipe", "pipe"],
-      shell: false,
-    });
-    let output = "";
-    let totalOutputBytes = 0;
-    let observedSession = sessionId ?? null;
-    let finalResponse = "";
-    let finished = false;
-    const fail = (error) => {
-      if (finished) return;
-      finished = true;
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", abort);
-      rejectRun(error);
-    };
-    const abort = () => child.kill("SIGTERM");
-    const timer = setTimeout(() => child.kill("SIGTERM"), timeoutMs);
-    signal?.addEventListener("abort", abort, { once: true });
-    if (signal?.aborted) abort();
-    child.stdout.on("data", (chunk) => {
-      totalOutputBytes += chunk.byteLength;
-      output += chunk.toString("utf8");
-      if (totalOutputBytes > MAX_OUTPUT_BYTES) child.kill("SIGTERM");
-      if (provider !== "codex") return;
-      let newline;
-      while ((newline = output.indexOf("\n")) >= 0) {
-        const line = output.slice(0, newline);
-        output = output.slice(newline + 1);
-        try {
-          const event = JSON.parse(line);
-          if (event.type === "thread.started" && typeof event.thread_id === "string")
-            observedSession = event.thread_id;
-          if (event.type === "item.completed" && event.item?.type === "agent_message")
-            finalResponse = String(event.item.text ?? "");
-        } catch {
-          // Ignore non-JSON progress lines; never echo model output to CLI logs.
-        }
-      }
-    });
-    child.stderr.on("data", () => {});
-    child.once("error", (error) => fail(error));
-    child.once("close", (code) => {
-      if (finished) return;
-      if (signal?.aborted) return fail(new Error("The collaboration listener was stopped."));
-      if (code !== 0)
-        return fail(
-          new Error(
-            `The ${provider} run exited with status ${code ?? "unknown"}. Check that client's local logs and permissions.`,
-          ),
-        );
-      if (provider === "claude") {
-        try {
-          const result = JSON.parse(output);
-          observedSession = result.session_id ?? observedSession;
-          finalResponse = typeof result.result === "string" ? result.result : "";
-          if (result.is_error) return fail(new Error("Claude reported a failed run."));
-        } catch {
-          return fail(new Error("Claude returned an invalid JSON result."));
-        }
-      }
-      if (!observedSession)
-        return fail(new Error(`${provider} did not return a resumable session ID.`));
-      finished = true;
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", abort);
-      resolveRun({ sessionId: observedSession, finalResponse });
-    });
-    child.stdin.end(prompt);
+  const { stdout } = await runFile(command, args, {
+    cwd: repositoryRoot,
+    env: runnerEnvironment(repositoryRoot),
+    input: prompt,
+    signal,
+    timeoutMs,
+    platform,
+    spawnProcess,
   });
+  let observedSession = sessionId ?? null;
+  let finalResponse = "";
+  if (provider === "claude") {
+    let result;
+    try {
+      result = JSON.parse(stdout);
+    } catch {
+      throw new Error("Claude returned an invalid JSON result.");
+    }
+    observedSession = result.session_id ?? observedSession;
+    finalResponse = typeof result.result === "string" ? result.result : "";
+    if (result.is_error) throw new Error("Claude reported a failed run.");
+  } else {
+    for (const line of stdout.split("\n")) {
+      try {
+        const event = JSON.parse(line);
+        if (event.type === "thread.started" && typeof event.thread_id === "string")
+          observedSession = event.thread_id;
+        if (event.type === "item.completed" && event.item?.type === "agent_message")
+          finalResponse = String(event.item.text ?? "");
+      } catch {
+        // Ignore non-JSON progress lines; never echo model output to CLI logs.
+      }
+    }
+  }
+  if (!observedSession) throw new Error(`${provider} did not return a resumable session ID.`);
+  return { sessionId: observedSession, finalResponse };
 }
 
 async function readJournal(file) {
@@ -216,7 +184,12 @@ async function latestOutboundTaskCursor(client, taskId, cursor, signal) {
   let latest = cursor;
   for (let page = 0; page < 20; page++) {
     const result = await client.messages.list(
-      { direction: "outbound", taskId, limit: 100, ...(latest ? { cursor: latest } : {}) },
+      {
+        direction: "outbound",
+        taskId,
+        limit: 100,
+        ...(latest ? { cursor: latest } : {}),
+      },
       { signal },
     );
     const messages = result.data ?? [];
@@ -247,7 +220,9 @@ export async function runCollaborationListener({
   if (!Number.isInteger(pollMs) || pollMs < 1000 || pollMs > 60000)
     throw new Error("--poll-ms must be between 1000 and 60000.");
   const root = resolve(repositoryRoot);
-  const repository = await inspectLocalRepository({ TOTEM_REPOSITORY_ROOT: root });
+  const repository = await inspectLocalRepository({
+    TOTEM_REPOSITORY_ROOT: root,
+  });
   const identity = await client.agent({ signal });
   const peer = await client.resolve(peerAddress, { signal });
   if (!peer?.id || peer.address !== peerAddress) throw new Error("The allowed peer was not found.");
@@ -267,7 +242,12 @@ export async function runCollaborationListener({
   }
   try {
     const journal = await readJournal(journalFile);
-    const binding = { agentId: identity.id, peerAddress, repository: repository.repository, root };
+    const binding = {
+      agentId: identity.id,
+      peerAddress,
+      repository: repository.repository,
+      root,
+    };
     if (journal.binding && JSON.stringify(journal.binding) !== JSON.stringify(binding))
       throw new Error("This journal belongs to a different agent, peer, or checkout.");
     if (!journal.binding) {
@@ -301,7 +281,11 @@ export async function runCollaborationListener({
             continue;
           }
           if (prior?.status === "started" || prior?.status === "failed") {
-            emit({ type: "needs_attention", messageId: message.id, taskId: message.taskId });
+            emit({
+              type: "needs_attention",
+              messageId: message.id,
+              taskId: message.taskId,
+            });
             continue;
           }
           const task = await client.tasks.get(message.taskId, { signal });
@@ -352,7 +336,12 @@ export async function runCollaborationListener({
           const outboundBefore = await latestOutboundTaskCursor(client, task.id, undefined, signal);
           journal.messages[message.id] = { status: "started", taskId: task.id };
           await saveJournal(journalFile, journal);
-          emit({ type: "started", messageId: message.id, taskId: task.id, provider });
+          emit({
+            type: "started",
+            messageId: message.id,
+            taskId: task.id,
+            provider,
+          });
           try {
             const result = await runAgent({
               provider,
@@ -377,12 +366,23 @@ export async function runCollaborationListener({
               sessionId: result.sessionId,
               runCount: (savedTask?.runCount ?? 0) + 1,
             };
-            journal.messages[message.id] = { status: "completed", taskId: task.id };
+            journal.messages[message.id] = {
+              status: "completed",
+              taskId: task.id,
+            };
             await saveJournal(journalFile, journal);
             await client.messages.ack(message.id, { signal });
-            emit({ type: "completed", messageId: message.id, taskId: task.id, provider });
+            emit({
+              type: "completed",
+              messageId: message.id,
+              taskId: task.id,
+              provider,
+            });
           } catch (error) {
-            journal.messages[message.id] = { status: "failed", taskId: task.id };
+            journal.messages[message.id] = {
+              status: "failed",
+              taskId: task.id,
+            };
             await saveJournal(journalFile, journal);
             await client.tasks
               .postUpdate(task.id, listenerStatusText(provider, "failed"), {

package/bin/connected-agent-service.mjs

@@ -0,0 +1,84 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { runMissionAgentService } from "./mission-agent-service.mjs";
+import { runRuntime } from "./network-runtime.mjs";
+
+// Both queues use the same verified identity and private profile. A stopped or
+// revoked connection cancels both consumers; Missions retains its own leases.
+export async function runConnectedAgentService(settings, dependencies = {}) {
+  const controller = new AbortController();
+  const signal = settings.signal
+    ? AbortSignal.any([settings.signal, controller.signal])
+    : controller.signal;
+  const emit = settings.emit ?? (() => {});
+  const phases = { messages: "starting", missions: "starting" };
+  const report = (queue, event) => {
+    phases[queue] = event.type === "completed" ? "waiting" : event.type;
+    const values = Object.values(phases);
+    const type =
+      ["reconnecting", "starting", "blocked", "working"].find((phase) => values.includes(phase)) ??
+      "waiting";
+    emit({ ...event, type });
+  };
+  const messages = async () => {
+    let attempts = 0;
+    while (!signal.aborted) {
+      try {
+        await (dependencies.runRuntime ?? runRuntime)({
+          ...settings,
+          signal,
+          stateDir: settings.stateDirectory,
+          allowAgents: [],
+          modelTimeoutMs: 900000,
+          replyTimeoutMs: 90000,
+          pollMs: settings.pollMs ?? 5000,
+          emit(event) {
+            if (event.type === "runtime_started") {
+              attempts = 0;
+              report("messages", { type: "waiting" });
+            } else if (event.type === "runtime_error")
+              report("messages", { type: "blocked", code: event.error?.code });
+            else if (["message_handled", "chat_completed"].includes(event.type))
+              report("messages", { type: "waiting" });
+          },
+        });
+        if (!signal.aborted) throw new Error("The message runtime stopped unexpectedly.");
+      } catch (error) {
+        if (signal.aborted) return;
+        if (
+          error.status === 401 ||
+          error.status === 403 ||
+          error.code === "AGENT_IDENTITY_MISMATCH"
+        )
+          throw error;
+        report("messages", { type: "reconnecting" });
+        await sleep(
+          error.status === 429 ? 30000 : Math.min(30000, 1000 * 2 ** Math.min(attempts++, 5)),
+          undefined,
+          { signal },
+        );
+      }
+    }
+  };
+  const guarded = async (run) => {
+    try {
+      await run();
+    } catch (error) {
+      if (!signal.aborted) {
+        controller.abort();
+        throw error;
+      }
+    }
+  };
+  const results = await Promise.allSettled([
+    guarded(messages),
+    guarded(() =>
+      (dependencies.runMissions ?? runMissionAgentService)({
+        ...settings,
+        signal,
+        emit: (event) => report("missions", event),
+      }),
+    ),
+  ]);
+  const failure = results.find((result) => result.status === "rejected");
+  if (failure) throw failure.reason;
+}

package/bin/device-login.mjs

@@ -0,0 +1,168 @@
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { privateRead, privateWrite } from "./runtime-installation.mjs";
+import { detectInstalledProvider, providerArguments } from "./provider-detection.mjs";
+
+function origin(value) {
+  const url = new URL(value ?? "https://totemlayer.com");
+  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)))
+  )
+    throw new Error("Choose an HTTPS Totem origin or local development origin.");
+  return url.origin;
+}
+async function request(baseUrl, path, options = {}, fetcher = fetch) {
+  const response = await fetcher(baseUrl + path, {
+    ...options,
+    redirect: "error",
+    signal: AbortSignal.timeout(15000),
+  });
+  const result = await response.json();
+  if (!response.ok && response.status !== 410)
+    throw new Error("Totem could not complete this installation request.");
+  return result;
+}
+export async function beginDeviceLogin(runtime, env = process.env, options = {}) {
+  const baseUrl = origin(env.TOTEM_BASE_URL);
+  let pending;
+  try {
+    pending = await privateRead(join(runtime.directory, "connection-request.json"));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (
+    !pending ||
+    pending.baseUrl !== baseUrl ||
+    pending.requestedAgentId !== env.TOTEM_AGENT_ID ||
+    pending.provider !== (env.TOTEM_PROVIDER ?? "auto") ||
+    new Date(pending.expiresAt) <= new Date()
+  ) {
+    const result = await request(
+      baseUrl,
+      "/api/installations",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          deviceName: hostname().slice(0, 100),
+          provider: env.TOTEM_PROVIDER ?? "auto",
+          ...(env.TOTEM_AGENT_ID ? { agentId: env.TOTEM_AGENT_ID } : {}),
+        }),
+      },
+      options.fetch,
+    );
+    if (
+      !/^[a-f0-9-]{36}$/.test(result.id) ||
+      !/^[A-Za-z0-9_-]{43}$/.test(result.token) ||
+      !/^[A-Z2-9]{12}$/.test(result.code) ||
+      !Number.isFinite(Date.parse(result.expiresAt))
+    )
+      throw new Error("Totem returned an invalid installation request.");
+    pending = {
+      ...result,
+      baseUrl,
+      requestedAgentId: env.TOTEM_AGENT_ID,
+      provider: env.TOTEM_PROVIDER ?? "auto",
+    };
+    await privateWrite(join(runtime.directory, "connection-request.json"), pending);
+  }
+  const url = `${baseUrl}/connect?code=${pending.code}`;
+  if (options.openBrowser !== false) {
+    const command =
+      process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+          ? ["rundll32.exe", ["url.dll,FileProtocolHandler", url]]
+          : ["xdg-open", [url]];
+    await (options.execute ?? promisify(execFile))(command[0], command[1], { timeout: 5000 }).catch(
+      () => {},
+    );
+  }
+  return { url, code: pending.code, expiresAt: pending.expiresAt };
+}
+
+export async function resumeDeviceLogin(runtime, env = process.env, options = {}) {
+  let staged;
+  try {
+    staged = await privateRead(join(runtime.directory, "connection-ready.json"));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  if (!staged) {
+    let pending;
+    try {
+      pending = await privateRead(join(runtime.directory, "connection-request.json"));
+    } catch (error) {
+      if (error.code === "ENOENT") return;
+      throw error;
+    }
+
+    const result = await request(
+      origin(pending.baseUrl),
+      `/api/installations/${pending.id}`,
+      { headers: { "x-totem-installation-token": pending.token } },
+      options.fetch,
+    );
+    if (result.status !== "approved") return;
+    if (
+      !/^[a-f0-9-]{36}$/.test(result.agentId) ||
+      !/^tn_(?:test|live)_[A-Za-z0-9_-]{43}$/.test(result.key)
+    )
+      throw new Error("Totem returned an invalid connection.");
+    staged = {
+      agentId: result.agentId,
+      key: result.key,
+      baseUrl: pending.baseUrl,
+      requestId: pending.id,
+      token: pending.token,
+    };
+    // Persist privately before acknowledging, so an interrupted setup never loses the key.
+    await privateWrite(join(runtime.directory, "connection-ready.json"), staged);
+  }
+  if (staged.requestId) {
+    const receipt = await request(
+      staged.baseUrl,
+      `/api/installations/${staged.requestId}`,
+      { method: "POST", headers: { "x-totem-installation-token": staged.token } },
+      options.fetch,
+    );
+    if (receipt.status !== "completed")
+      throw new Error("This connection expired before it was saved. Run totem login again.");
+    delete staged.requestId;
+    delete staged.token;
+    await privateWrite(join(runtime.directory, "connection-ready.json"), staged);
+  }
+  const provider = await (options.detectProvider ?? detectInstalledProvider)(env);
+  if (!provider) return { state: "executor_needed" };
+  const { agentSetupMain } = await import("./agent-setup.mjs");
+  const status = await (options.setup ?? agentSetupMain)(
+    [
+      "--profile",
+      staged.agentId ?? "default",
+      ...(staged.agentId ? ["--agent-id", staged.agentId] : []),
+      "--base-url",
+      origin(staged.baseUrl),
+      ...(await providerArguments(provider, env)),
+      "--no-start",
+      "--json",
+    ],
+    {
+      env: { ...env, TOTEM_NETWORK_API_KEY: staged.key },
+      stdout: { write() {} },
+      stderr: { write() {} },
+    },
+  );
+  if (status) throw new Error("The approved connection could not be saved.");
+  const { rm } = await import("node:fs/promises");
+  await rm(join(runtime.directory, "connection-ready.json"));
+  await rm(join(runtime.directory, "connection-request.json"), { force: true });
+  return { state: "connected", profile: staged.agentId };
+}