totemlayer 0.1.68 → 0.1.74

package/bin/strict-installation.mjs

@@ -0,0 +1,206 @@
+import { parseArgs } from "node:util";
+import { GUIDE_UNAVAILABLE, runStrictSetup } from "./strict-setup.mjs";
+import { readReleaseSetupGuide } from "./setup-guide.mjs";
+
+export const STRICT_INSTALL_HELP = `Install Totem with every required verification
+
+  totem install [--provider codex] [--agent-id UUID] [--environment PRODUCTION|SANDBOX]
+    [--session CURRENT_NATIVE_SESSION] [--model CURRENT_MODEL] [--wait-seconds 1200] [--json]
+    [--device-login --no-browser]
+  totem install --read-guide
+  totem install --status
+
+Run inside the intended agent's command-capable host. The current native session and
+model must be verified; an installed client is never selected as a substitute.
+Sign in and approve the connection when requested. Credentials are never arguments.
+The installer retains one receiver, explicit pauses and permissions. Success requires
+identity, five-second receiving, durable startup, recovery, native wake and separately
+verified peer and website-owner replies. Missing capabilities/tests return incomplete.
+Repeat the same command to resume the same binding; never reauthorize to repair a pause.
+
+Phone apps and hosted-only assistants use their native custom MCP flow at
+https://totemlayer.com/mcp. A phone browser approves an agent on its actual host;
+it does not run a local service. API fallback requires the observed missing custom-MCP
+capability first. Read setup.md for the full mobile, MCP and API requirements.
+`;
+
+export async function strictInstallationMain(args = [], options = {}) {
+  const stdout = options.stdout ?? process.stdout;
+  let flags;
+  try {
+    const values = parseArgs({
+      args,
+      strict: true,
+      options: {
+        provider: { type: "string" },
+        "agent-id": { type: "string" },
+        environment: { type: "string" },
+        "base-url": { type: "string" },
+        session: { type: "string" },
+        model: { type: "string" },
+        "wait-seconds": { type: "string", default: "1200" },
+        "read-guide": { type: "boolean" },
+        json: { type: "boolean" },
+        "device-login": { type: "boolean" },
+        "no-browser": { type: "boolean" },
+        status: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+      },
+    }).values;
+    if (values.help) {
+      stdout.write(STRICT_INSTALL_HELP);
+      return 0;
+    }
+    if (values["read-guide"]) {
+      const guide = await readReleaseSetupGuide();
+      stdout.write(guide.text);
+      return 0;
+    }
+    const baseUrl = new URL(values["base-url"] ?? "https://totemlayer.com");
+    if (
+      baseUrl.username ||
+      baseUrl.password ||
+      baseUrl.search ||
+      baseUrl.hash ||
+      baseUrl.pathname !== "/" ||
+      (baseUrl.protocol !== "https:" &&
+        !(
+          baseUrl.protocol === "http:" &&
+          ["localhost", "127.0.0.1", "[::1]"].includes(baseUrl.hostname)
+        ))
+    )
+      throw new Error();
+    const waitSeconds = Number(values["wait-seconds"]);
+    if (
+      !/^\d+$/.test(values["wait-seconds"]) ||
+      !Number.isSafeInteger(waitSeconds) ||
+      waitSeconds < 0 ||
+      waitSeconds > 3600
+    )
+      throw new Error();
+    if (
+      values["agent-id"] &&
+      !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(values["agent-id"])
+    )
+      throw new Error();
+    if (
+      values.environment &&
+      (!values["agent-id"] || !["PRODUCTION", "SANDBOX"].includes(values.environment))
+    )
+      throw new Error();
+    if (
+      values.model &&
+      (!/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(values.model) ||
+        /tn_(?:live|test)_/.test(values.model))
+    )
+      throw new Error();
+    if (values.session && !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(values.session))
+      throw new Error();
+    const env = options.env ?? process.env;
+    flags = {
+      provider: values.provider ?? (env.CODEX_THREAD_ID ? "codex" : undefined),
+      agentId: values["agent-id"]?.toLowerCase(),
+      environment: values.environment,
+      baseUrl: baseUrl.origin,
+      sessionId: values.session,
+      model: values.model,
+      waitSeconds,
+      json: values.json === true,
+    };
+    if (values["device-login"]) flags.deviceLogin = true;
+    if (values["no-browser"]) flags.noBrowser = true;
+    if (values.status) {
+      flags.sessionId ??= env.CODEX_THREAD_ID;
+      const { readStrictSetupJob } = await import("./strict-setup-jobs.mjs");
+      const publicStatus = { ...(await readStrictSetupJob(flags, env)) };
+      delete publicStatus.pid;
+      delete publicStatus.processIdentity;
+      stdout.write(JSON.stringify(publicStatus) + "\n");
+      return publicStatus.complete ? 0 : 2;
+    }
+  } catch {
+    stdout.write(
+      JSON.stringify({
+        complete: false,
+        state: "incomplete",
+        code: "INSTALL_OPTIONS_INVALID",
+        message: "Use totem install --help. Never pass credentials in command arguments.",
+      }) + "\n",
+    );
+    return 2;
+  }
+  const write = async (value) => stdout.write(JSON.stringify(value) + "\n");
+  if (!options.adapter && !options.foreground && flags.provider === "codex") {
+    // Return before readiness needs a model turn in this same native chat.
+    const adapter = (await import("./strict-codex-adapter.mjs")).createStrictCodexAdapter(flags, {
+      ...options,
+      write,
+    });
+    try {
+      let guide;
+      for (const reader of ["primary", "alternate"]) {
+        try {
+          guide = await readReleaseSetupGuide(reader);
+          break;
+        } catch {}
+      }
+      if (!guide) {
+        await write({
+          complete: false,
+          state: "incomplete",
+          code: "GUIDE_UNAVAILABLE",
+          message: GUIDE_UNAVAILABLE,
+        });
+        return 3;
+      }
+      const inspected = await adapter.inspect(true);
+      if (inspected.paused) {
+        await write(
+          await runStrictSetup(adapter, {
+            expectedAgentId: flags.agentId,
+            expectedEnvironment: flags.environment,
+          }),
+        );
+        return 2;
+      }
+      const host = inspected.host;
+      const { scheduleStrictSetup } = await import("./strict-setup-jobs.mjs");
+      await write(await scheduleStrictSetup(flags, host, options.env ?? process.env));
+      return 2;
+    } catch (error) {
+      await write({
+        complete: false,
+        state: "incomplete",
+        code: /^[A-Z][A-Z0-9_]{0,79}$/.test(error.code ?? "") ? error.code : "SETUP_ADAPTER_FAILED",
+      });
+      return 2;
+    } finally {
+      await adapter.close();
+    }
+  }
+  // The command has no arbitrary adapter/script URL, proof, skip-check or force-success option.
+  const adapter =
+    options.adapter ??
+    (flags.provider === "codex"
+      ? (await import("./strict-codex-adapter.mjs")).createStrictCodexAdapter(flags, {
+          ...options,
+          write,
+        })
+      : {
+          readGuide: readReleaseSetupGuide,
+          async inspect() {
+            throw Object.assign(new Error(), {
+              code: flags.provider ? "HOST_ADAPTER_UNSUPPORTED" : "EXACT_NATIVE_HOST_REQUIRED",
+            });
+          },
+        });
+  const result = await runStrictSetup(adapter, {
+    expectedAgentId: flags.agentId,
+    expectedEnvironment: flags.environment,
+    progress: async (value) => {
+      if (!flags.json || value.stage === "guide_verified") await write(value);
+    },
+  });
+  await write(result);
+  return result.complete ? 0 : result.message === GUIDE_UNAVAILABLE ? 3 : 2;
+}

package/bin/strict-setup-jobs.mjs

@@ -0,0 +1,253 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { opendir } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  privateRead,
+  privateWrite,
+  ensureInstalledRuntime,
+  installRuntimeService,
+  runtimeRoot,
+} from "./runtime-installation.mjs";
+import { acquireSupervisorLock, processIdentity } from "./automatic-runtime.mjs";
+
+const valid = (id) => typeof id === "string" && /^[a-f0-9]{64}$/.test(id);
+const missing = async (promise) =>
+  promise.catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+const directory = (env, id) => join(runtimeRoot(env), "runtime", "strict-setup-jobs", id);
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const active = async (record) =>
+  Number.isSafeInteger(record?.pid) &&
+  record.pid > 1 &&
+  record.processIdentity &&
+  (await processIdentity(record.pid, record.processIdentity).catch(() => null)) ===
+    record.processIdentity;
+
+export function strictSetupJobId(flags) {
+  return hash([
+    flags.baseUrl,
+    flags.provider,
+    flags.sessionId,
+    flags.agentId ?? null,
+    flags.environment ?? null,
+  ]);
+}
+
+function validJob(job) {
+  const keys = [
+    "provider",
+    "agentId",
+    "environment",
+    "baseUrl",
+    "sessionId",
+    "model",
+    "waitSeconds",
+    "json",
+    "deviceLogin",
+    "noBrowser",
+  ];
+  return (
+    job?.version === 1 &&
+    valid(job.id) &&
+    job.flags?.provider === "codex" &&
+    /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(job.flags.sessionId ?? "") &&
+    /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(job.flags.model ?? "") &&
+    !/tn_(?:test|live)_/.test(job.flags.model) &&
+    job.flags.model !== "default" &&
+    Number.isInteger(job.flags.waitSeconds) &&
+    job.flags.waitSeconds >= 0 &&
+    job.flags.waitSeconds <= 3600 &&
+    Object.keys(job.flags).every((key) => keys.includes(key)) &&
+    strictSetupJobId(job.flags) === job.id
+  );
+}
+
+async function launch(job, runtime, env) {
+  const path = directory(env, job.id);
+  const state = await missing(privateRead(join(path, "status.json")));
+  if (await active(state)) return state;
+  if (["complete", "blocked", "paused"].includes(state?.state)) return state;
+  const child = spawn(process.execPath, [runtime.cli, "install-worker", job.id], {
+    env: { ...env, TOTEM_AUTO_START: "1" },
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  await new Promise((resolve, reject) => {
+    child.once("spawn", resolve);
+    child.once("error", reject);
+  });
+  child.unref();
+  return { state: "installing", complete: false, jobId: job.id };
+}
+
+/** Foreground returns promptly so the bound native chat can handle its queued readiness callbacks. */
+export async function scheduleStrictSetup(flags, host, env = process.env, options = {}) {
+  const selected = { ...flags, sessionId: host.sessionId, model: host.model };
+  const id = strictSetupJobId(selected),
+    path = directory(env, id);
+  const previous = await missing(privateRead(join(path, "job.json")));
+  if (previous && (!validJob(previous) || previous.flags.model !== selected.model))
+    throw Object.assign(new Error(), { code: "SETUP_BINDING_CHANGED" });
+  const job = previous ?? { version: 1, id, flags: selected };
+  if (!validJob(job)) throw Object.assign(new Error(), { code: "SETUP_BINDING_UNVERIFIED" });
+  const runtime = await (options.ensureRuntime ?? ensureInstalledRuntime)(env);
+  if (!previous) await privateWrite(join(path, "job.json"), job);
+  const status = await missing(privateRead(join(path, "status.json")));
+  if (status?.state === "complete")
+    await privateWrite(join(path, "status.json"), {
+      state: "checking",
+      complete: false,
+      previousVerifiedAt: status.updatedAt,
+    });
+  const service = await (options.installService ?? installRuntimeService)(runtime, env);
+  if (service.persistent !== true)
+    return {
+      state: "incomplete",
+      complete: false,
+      code: "SETUP_SUPERVISION_UNAVAILABLE",
+      jobId: id,
+    };
+  return {
+    ...(await (options.launch ?? launch)(job, runtime, env)),
+    jobId: id,
+    message:
+      "Setup continues under the host supervisor. Finish sign-in/approval when requested; this native chat must be available for queued checks. Inspect totem install --status without restarting setup.",
+  };
+}
+
+export async function readStrictSetupJob(flags, env = process.env) {
+  const id = strictSetupJobId(flags);
+  return (
+    (await missing(privateRead(join(directory(env, id), "status.json")))) ?? {
+      state: "not_started",
+      complete: false,
+      jobId: id,
+    }
+  );
+}
+
+export async function resumeStrictSetupJobs(env = process.env, options = {}) {
+  const root = join(runtimeRoot(env), "runtime", "strict-setup-jobs");
+  const entries = await missing(opendir(root));
+  if (!entries) return;
+  const runtime = { cli: join(runtimeRoot(env), "runtime", "totem.mjs") };
+  let count = 0;
+  for await (const entry of entries) {
+    if (++count > 100) throw new Error("Too many pending setup jobs.");
+    if (!entry.isDirectory() || !valid(entry.name)) continue;
+    const job = await privateRead(join(root, entry.name, "job.json"));
+    if (!validJob(job) || job.id !== entry.name) throw new Error("Unsafe pending setup job.");
+    await (options.launch ?? launch)(job, runtime, env);
+  }
+}
+
+export async function strictSetupWorkerMain(id, options = {}) {
+  const env = options.env ?? process.env;
+  if (!valid(id)) return 2;
+  const path = directory(env, id);
+  const job = await privateRead(join(path, "job.json"));
+  if (!validJob(job) || job.id !== id) return 2;
+  let release;
+  try {
+    release = await acquireSupervisorLock(join(path, "worker"));
+  } catch {
+    return 2;
+  }
+  const fingerprint = await processIdentity(process.pid);
+  let writes = Promise.resolve();
+  const save = async (value) =>
+    privateWrite(join(path, "status.json"), {
+      ...value,
+      jobId: id,
+      pid: process.pid,
+      processIdentity: fingerprint,
+      updatedAt: Date.now(),
+    });
+  try {
+    await save({ state: "installing", complete: false });
+    const { strictInstallationMain } = await import("./strict-installation.mjs");
+    let partial = "",
+      final;
+    await strictInstallationMain(
+      [
+        "--provider",
+        job.flags.provider,
+        "--session",
+        job.flags.sessionId,
+        "--model",
+        job.flags.model,
+        "--base-url",
+        job.flags.baseUrl,
+        "--wait-seconds",
+        String(job.flags.waitSeconds),
+        ...(job.flags.agentId ? ["--agent-id", job.flags.agentId] : []),
+        ...(job.flags.environment ? ["--environment", job.flags.environment] : []),
+        ...(job.flags.deviceLogin ? ["--device-login"] : []),
+        ...(job.flags.noBrowser ? ["--no-browser"] : []),
+      ],
+      {
+        ...options,
+        foreground: true,
+        env,
+        stdout: {
+          write(chunk) {
+            partial += chunk;
+            let newline;
+            while ((newline = partial.indexOf("\n")) !== -1) {
+              const line = partial.slice(0, newline);
+              partial = partial.slice(newline + 1);
+              try {
+                const value = JSON.parse(line);
+                if (value.version === 1 && typeof value.complete === "boolean") final = value;
+                // Serialize writes below; callbacks never export credentials or message contents.
+                writes = writes.then(() =>
+                  save({
+                    state: "installing",
+                    complete: false,
+                    stage: value.stage,
+                    ...(value.stage === "sign_in_required" ? { url: value.url } : {}),
+                    ...(value.stage === "sign_in_required" && value.approvalCode
+                      ? { approvalCode: value.approvalCode }
+                      : {}),
+                    ...(value.stage === "tests_requested" ? { marker: value.marker } : {}),
+                    ...(value.message ? { message: value.message } : {}),
+                  }),
+                );
+              } catch {
+                /* Non-JSON text is never forwarded into a receipt. */
+              }
+            }
+          },
+        },
+      },
+    );
+    final ??= { complete: false, state: "incomplete", code: "SETUP_WORKER_FAILED" };
+    await writes;
+    const state = final.complete
+      ? "complete"
+      : final.state === "paused"
+        ? "paused"
+        : ["AUTHORIZED_TESTS_PENDING", "RECOVERY_WAITING_FOR_IDLE"].includes(final.code)
+          ? "waiting"
+          : "blocked";
+    await save({ ...final, state });
+    if (!options.adapter && ["complete", "blocked", "paused"].includes(state)) {
+      const { defaultCodexQueue } = await import("./codex-chat-bridge.mjs");
+      await defaultCodexQueue({
+        threadId: job.flags.sessionId,
+        environment: env,
+        prompt: `Totem's strict installer finished this attempt. Report this verified receipt to the owner, preserving every incomplete check and limitation. Do not rerun a denied operation or claim completion when complete is false. Receipt: ${JSON.stringify(final)}`,
+      }).catch(() => {});
+    }
+    return final.complete ? 0 : 2;
+  } catch {
+    await writes.catch(() => {});
+    await save({ complete: false, state: "blocked", code: "SETUP_WORKER_FAILED" });
+    return 2;
+  } finally {
+    await release();
+  }
+}