totemlayer 0.1.4 → 0.1.6

package/README.md

@@ -26,7 +26,7 @@ another program; machine-readable output remains undecorated JSON.
    ╭───╯╰────╮   ╺┳╸┏━┓╺┳╸┏━╸┏┳┓
   ╰────╮╭────╯    ┃ ┃ ┃ ┃ ┣╸ ┃┃┃
        ╰╯          ╹ ┗━┛ ╹ ┗━╸╹ ╹
-TotemLayer CLI 0.1.4 · cross-company agent authorization
+TotemLayer CLI 0.1.5 · cross-company agent authorization
 ```
 
 For a one-off run without a global install:
@@ -43,6 +43,23 @@ The package is distributed under the included TotemLayer CLI Use License, which
 permits anyone to install and use unmodified copies with TotemLayer-compatible
 services without exposing or licensing the private server application.
 
+## Guided agent setup (local preview)
+
+This checkout adds one-time connection profiles and automatic pickup of approved Mission work. These commands require the matching local package; they are not yet available in the published npm release.
+
+```sh
+totem setup --profile my-agent --agent-id YOUR_AGENT_UUID --base-url https://your-totem-service.example
+totem status --profile my-agent
+totem start --profile my-agent --background
+totem stop --profile my-agent
+```
+
+Create an agent and connection key in the Totem app first. Setup asks for the key privately, verifies the identity, and saves a private connection. It can approve explicitly chosen local repository paths. Noninteractive setup accepts a private `--key-file`; key values are never command arguments. Existing settings require explicit `--replace` before changing.
+
+The automatic Mission worker uses an already running local Qwen model. It receives consented assignments without a Mission ID, retains recovery journals, and continues within the current permissions and limits. `--background` keeps the worker independent of the terminal, but the computer and model must remain running. After a computer restart, start the saved profile again. Setup and status never start a model or worker themselves.
+
+Choosing Codex or Claude connects MCP tools and can install a profile-specific connection with explicit `--install-mcp`. Setup checks existing settings before updating them and gives named recovery instructions when they cannot be verified. Restart the AI app and call `totem_get_identity` to verify its connection. Those connections do not run the automatic Mission worker in this preview. Ordinary Chat has its own `totem network run` command. Status reports connection, repository, model, and worker readiness separately; coding readiness requires an approved checkout, while other Mission work can run without one.
+
 ## Before the first production request
 
 Each participating company completes its one-time setup at
@@ -273,10 +290,10 @@ uses stdio and writes protocol messages only to stdout; operational errors go to
 export TOTEM_BASE_URL=http://localhost:3413
 export TOTEM_NETWORK_API_KEY_FILE="$HOME/.totem-agent-key" # chmod 600 this file
 totem network me --json
-totem network run --provider ollama --model qwen3.5:9b
+totem network run --provider qwen-local --qwen-url http://127.0.0.1:8087/v1 --model qwen3.5-9b
 ```
 
-Register an agent and create its key in **Agents** (`/communications?view=setup`). Open **Chat** in Totem to talk to the running agent. Ollama and the named model must already be installed; the CLI does not download them. Personal agents do not require a company domain.
+Register an agent and create its key in **Agents** (`/communications?view=setup`). Open **Chat** in Totem to talk to the running agent. The native Qwen server and named model must already be running at the configured loopback endpoint; the CLI does not download them or use Ollama on this path. Personal agents do not require a company domain.
 
 Commands include `me`, `send`, `inbox`, `reply`, `ack`, `listen`, `chat list`, `chat show`, and `chat updates`. Output is JSON; `--json` also emits errors as JSON on stdout. `listen` is an at-least-once unread stream with explicit acknowledgment. `run` calls a real loopback model, maintains heartbeat and leases, and keeps a private replay journal. Use `--allow-agent <exact-address>` to allow its bounded `ask_agent` tool. No arbitrary shell or external action tools are installed.
 
@@ -285,3 +302,7 @@ Packing this package inside the source repository builds and embeds the current
 the package has no installation scripts. This local addition has not been published to npm. See
 `docs/network/agent-runtime.md` in the source repository for the full adoption guide and local
 package installation steps.
+
+## Repository test isolation
+
+Version 0.1.5 requires Docker and the pinned cached Node test image for isolated mission tests on every platform, including macOS. Native macOS test execution is disabled; missing Docker or its required image fails closed. Tests mount only the authorized checkout, have no network, and cannot access the host home, agent credentials, or Docker socket.

package/bin/agent-profile.mjs

@@ -0,0 +1,466 @@
+import { constants } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
+
+import { localModelEndpoint } from "./local-model-provider.mjs";
+import { repositoryIdFromRemote } from "./repository.mjs";
+
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const KEY = /^tn_(test|live)_[A-Za-z0-9_-]{43}$/;
+const MAX_PROFILE_BYTES = 32768;
+const profileBindings = new WeakMap();
+
+function fail(code = "AGENT_PROFILE_INVALID") {
+  const messages = {
+    AGENT_PROFILE_INVALID: "The private agent profile is invalid or unsafe.",
+    AGENT_PROFILE_NOT_FOUND: "The named agent connection has not been configured.",
+    AGENT_PROFILE_EXISTS:
+      "This connection already has different settings or credentials. Explicit replacement is required.",
+    AGENT_PROFILE_BUSY:
+      "Another setup or worker start may be updating this profile. Wait for it to finish. If this persists after those processes have stopped, inspect this profile's private profile.lock file before recovery. The lock is never cleared automatically.",
+    AGENT_PROFILE_RUNNING:
+      "This agent connection is running. Stop it before replacing its settings or credentials.",
+    AGENT_PROFILE_IO: "The private agent connection could not be safely read or saved.",
+  };
+  throw Object.assign(new Error(messages[code] ?? messages.AGENT_PROFILE_INVALID), { code });
+}
+
+function validName(name) {
+  if (
+    typeof name !== "string" ||
+    name.length > 64 ||
+    !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) ||
+    /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/.test(name)
+  )
+    fail();
+  return name;
+}
+
+function absolutePath(value) {
+  if (
+    typeof value !== "string" ||
+    value.length > 4096 ||
+    /[\x00-\x1f\x7f]/.test(value) ||
+    !isAbsolute(value) ||
+    resolve(value) !== value
+  )
+    fail();
+  return value;
+}
+
+export function connectionDirectory(profile = "default", environment = process.env) {
+  const root = absolutePath(environment.TOTEM_CONFIG_DIR ?? join(homedir(), ".totem"));
+  if (root === parse(root).root) fail();
+  return join(root, "connections", validName(profile));
+}
+
+function owned(info) {
+  return typeof process.getuid !== "function" || info.uid === process.getuid();
+}
+
+function privateDirectory(info) {
+  if (
+    !info.isDirectory() ||
+    info.isSymbolicLink() ||
+    !owned(info) ||
+    (process.platform !== "win32" && (info.mode & 0o777) !== 0o700)
+  )
+    fail();
+}
+
+async function directories(path, privateRoot, create = false) {
+  absolutePath(path);
+  let current = parse(path).root;
+  for (const part of path.slice(current.length).split(sep).filter(Boolean)) {
+    current = join(current, part);
+    let info;
+    try {
+      info = await lstat(current);
+    } catch (error) {
+      if (error.code !== "ENOENT" || !create) throw error;
+      try {
+        await mkdir(current, { mode: 0o700 });
+      } catch (createError) {
+        if (createError.code !== "EEXIST") throw createError;
+      }
+      info = await lstat(current);
+    }
+    if (info.isSymbolicLink() || !info.isDirectory()) fail();
+    if (current === privateRoot || current.startsWith(`${privateRoot}${sep}`))
+      privateDirectory(info);
+  }
+}
+
+function privateFile(info, maximum) {
+  if (
+    !info.isFile() ||
+    info.isSymbolicLink() ||
+    info.nlink !== 1 ||
+    !owned(info) ||
+    (process.platform !== "win32" && (info.mode & 0o777) !== 0o600) ||
+    info.size > maximum
+  )
+    fail();
+}
+
+async function boundedPrivateRead(path, maximum) {
+  const info = await lstat(path);
+  privateFile(info, maximum);
+  const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const actual = await file.stat();
+    privateFile(actual, maximum);
+    if (actual.ino !== info.ino || actual.dev !== info.dev || actual.size > maximum) fail();
+    const buffer = Buffer.alloc(maximum + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await file.read(buffer, length, buffer.length - length, length);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    if (length > maximum) fail();
+    return buffer.subarray(0, length).toString("utf8");
+  } finally {
+    await file.close();
+  }
+}
+
+async function writePrivate(path, contents) {
+  const file = await open(
+    path,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+    0o600,
+  );
+  try {
+    await file.writeFile(contents);
+    await file.sync();
+  } finally {
+    await file.close();
+  }
+}
+
+function origin(value) {
+  if (typeof value !== "string" || value.length > 2048 || /[\s\\]/.test(value)) fail();
+  const url = new URL(value);
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (
+    (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    url.pathname !== "/"
+  )
+    fail();
+  return url.origin;
+}
+
+function credentialValue(value, environment) {
+  if (
+    typeof value !== "string" ||
+    !KEY.test(value) ||
+    !value.startsWith(environment === "SANDBOX" ? "tn_test_" : "tn_live_")
+  )
+    fail();
+  return value;
+}
+
+async function normalizedSettings(input, directory) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) fail();
+  const allowed = new Set([
+    "baseUrl",
+    "agentId",
+    "address",
+    "environment",
+    "provider",
+    "model",
+    "qwenUrl",
+    "repositoryRoots",
+    "stateDirectory",
+    "client",
+  ]);
+  if (Object.keys(input).some((key) => !allowed.has(key))) fail();
+  const baseUrl = origin(input.baseUrl);
+  if (typeof input.agentId !== "string" || !UUID.test(input.agentId)) fail();
+  if (
+    typeof input.address !== "string" ||
+    input.address.length > 320 ||
+    !/^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9.-]*$/.test(input.address) ||
+    !["SANDBOX", "PRODUCTION"].includes(input.environment)
+  )
+    fail();
+  const provider = input.provider ?? "qwen-local";
+  const model = input.model ?? "qwen3.5-9b";
+  if (
+    provider !== "qwen-local" ||
+    typeof model !== "string" ||
+    !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(model)
+  )
+    fail();
+  if (
+    input.qwenUrl !== undefined &&
+    (typeof input.qwenUrl !== "string" ||
+      input.qwenUrl.length > 2048 ||
+      /[\s\\]/.test(input.qwenUrl))
+  )
+    fail();
+  const endpoint = new URL(localModelEndpoint(provider, { qwenUrl: input.qwenUrl }));
+  const qwenUrl = `${endpoint.origin}/v1`;
+  if (input.client !== undefined && !["codex", "claude"].includes(input.client)) fail();
+  const roots = input.repositoryRoots ?? [];
+  if (!Array.isArray(roots) || roots.length > 32) fail();
+  const ids = new Set();
+  const repositoryRoots = [];
+  for (const entry of roots) {
+    if (
+      !entry ||
+      typeof entry !== "object" ||
+      Array.isArray(entry) ||
+      Object.keys(entry).some((key) => !["repositoryId", "root"].includes(key))
+    )
+      fail();
+    if (
+      typeof entry.repositoryId !== "string" ||
+      entry.repositoryId.length > 500 ||
+      repositoryIdFromRemote(`https://${entry.repositoryId}`) !== entry.repositoryId ||
+      ids.has(entry.repositoryId.toLowerCase())
+    )
+      fail();
+    const root = absolutePath(entry.root);
+    await directories(root, directory);
+    if ((await realpath(root)) !== root) fail();
+    ids.add(entry.repositoryId.toLowerCase());
+    repositoryRoots.push({ repositoryId: entry.repositoryId, root });
+  }
+  repositoryRoots.sort((a, b) => a.repositoryId.localeCompare(b.repositoryId));
+  const scope = createHash("sha256")
+    .update(JSON.stringify([baseUrl, input.agentId]))
+    .digest("hex");
+  const stateDirectory = join(directory, "state", scope);
+  if (input.stateDirectory !== undefined && input.stateDirectory !== stateDirectory) fail();
+  return {
+    baseUrl,
+    agentId: input.agentId,
+    address: input.address,
+    environment: input.environment,
+    provider,
+    model,
+    qwenUrl,
+    repositoryRoots,
+    stateDirectory,
+    ...(input.client === undefined ? {} : { client: input.client }),
+  };
+}
+
+function publicProfile(name, directory, settings, generation, serialized) {
+  const profile = Object.freeze({
+    version: 1,
+    profileName: name,
+    ...settings,
+    repositoryRoots: Object.freeze(settings.repositoryRoots.map((entry) => Object.freeze(entry))),
+    credentialFile: join(directory, "credentials", generation, "agent.key"),
+  });
+  profileBindings.set(profile, { directory, serialized });
+  return profile;
+}
+
+async function readStored(name, directory, privateRoot) {
+  await directories(directory, privateRoot);
+  const text = await boundedPrivateRead(join(directory, "profile.json"), MAX_PROFILE_BYTES);
+  const record = JSON.parse(text);
+  if (
+    !record ||
+    record.version !== 1 ||
+    record.profileName !== name ||
+    !UUID.test(record.credentialGeneration ?? "")
+  )
+    fail();
+  const credentialGeneration = record.credentialGeneration;
+  const input = Object.fromEntries(
+    Object.entries(record).filter(
+      ([key]) => !["version", "profileName", "credentialGeneration"].includes(key),
+    ),
+  );
+  const settings = await normalizedSettings(input, directory);
+  const expected = JSON.stringify({
+    version: 1,
+    profileName: name,
+    ...settings,
+    credentialGeneration,
+  });
+  if (JSON.stringify(record) !== expected) fail();
+  await directories(join(directory, "credentials", credentialGeneration), privateRoot);
+  await directories(settings.stateDirectory, privateRoot);
+  const profile = publicProfile(name, directory, settings, credentialGeneration, expected);
+  await readAgentCredential(profile);
+  return { profile, settings, serialized: expected };
+}
+
+function safeFailure(error) {
+  if (typeof error?.code === "string" && error.code.startsWith("AGENT_PROFILE_")) throw error;
+  fail("AGENT_PROFILE_IO");
+}
+
+export async function readAgentProfile(profileName = "default", options = {}) {
+  try {
+    const directory = connectionDirectory(profileName, options.environment);
+    try {
+      return (await readStored(profileName, directory, dirname(dirname(directory)))).profile;
+    } catch (error) {
+      if (error.code === "ENOENT") fail("AGENT_PROFILE_NOT_FOUND");
+      throw error;
+    }
+  } catch (error) {
+    safeFailure(error);
+  }
+}
+
+export async function readAgentCredential(profile) {
+  try {
+    const binding = profileBindings.get(profile);
+    if (!binding) fail();
+    const privateRoot = dirname(dirname(binding.directory));
+    await directories(dirname(profile.credentialFile), privateRoot);
+    await directories(profile.stateDirectory, privateRoot);
+    const current = await boundedPrivateRead(
+      join(binding.directory, "profile.json"),
+      MAX_PROFILE_BYTES,
+    );
+    if (current !== binding.serialized) fail();
+    return credentialValue(
+      await boundedPrivateRead(profile.credentialFile, 128),
+      profile.environment,
+    );
+  } catch (error) {
+    safeFailure(error);
+  }
+}
+
+/** Register a runner under the same short-lived lock used to replace its connection. */
+export async function withAgentProfileLock(profile, operation) {
+  let lock;
+  let lockPath;
+  try {
+    const binding = profileBindings.get(profile);
+    if (!binding || typeof operation !== "function") fail();
+    await directories(binding.directory, dirname(dirname(binding.directory)));
+    lockPath = join(binding.directory, "profile.lock");
+    try {
+      lock = await open(
+        lockPath,
+        constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+        0o600,
+      );
+    } catch (error) {
+      if (error.code === "EEXIST") fail("AGENT_PROFILE_BUSY");
+      throw error;
+    }
+    // A replacement may have completed after live authentication but before registration.
+    await readAgentCredential(profile);
+  } catch (error) {
+    if (lock) {
+      await lock.close().catch(() => {});
+      await unlink(lockPath).catch(() => {});
+    }
+    safeFailure(error);
+  }
+  try {
+    return await operation();
+  } finally {
+    await lock.close().catch(() => {});
+    await unlink(lockPath).catch(() => {});
+  }
+}
+
+export async function saveAgentProfile(profileName = "default", input, credential, options = {}) {
+  let lock;
+  let lockPath;
+  let temporary;
+  try {
+    const directory = connectionDirectory(profileName, options.environment);
+    const privateRoot = dirname(dirname(directory));
+    const settings = await normalizedSettings(input, directory);
+    credentialValue(credential, settings.environment);
+    if (options.replace !== undefined && typeof options.replace !== "boolean") fail();
+    await directories(directory, privateRoot, true);
+    lockPath = join(directory, "profile.lock");
+    try {
+      lock = await open(
+        lockPath,
+        constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+        0o600,
+      );
+    } catch (error) {
+      if (error.code === "EEXIST") fail("AGENT_PROFILE_BUSY");
+      throw error;
+    }
+    let existing;
+    try {
+      existing = await readStored(profileName, directory, privateRoot);
+    } catch (error) {
+      // Only absence of the manifest permits first creation; missing key data is corruption.
+      if (error.code !== "ENOENT") throw error;
+      try {
+        await lstat(join(directory, "profile.json"));
+        fail();
+      } catch (manifestError) {
+        if (manifestError.code !== "ENOENT") throw manifestError;
+      }
+    }
+    if (existing) {
+      const unchanged =
+        JSON.stringify(existing.settings) === JSON.stringify(settings) &&
+        (await readAgentCredential(existing.profile)) === credential;
+      if (unchanged) return existing.profile;
+      if (!options.replace) fail("AGENT_PROFILE_EXISTS");
+      // Shared with initial runner registration. Never orphan a live old identity or
+      // silently change local repository permissions underneath an active session.
+      const { readAgentRuntimeStatus } = await import("./agent-runner.mjs");
+      const runtime = await readAgentRuntimeStatus(existing.profile);
+      if (runtime.running) fail("AGENT_PROFILE_RUNNING");
+    }
+    const generation = randomUUID();
+    const keyDirectory = join(directory, "credentials", generation);
+    const serialized = JSON.stringify({
+      version: 1,
+      profileName,
+      ...settings,
+      credentialGeneration: generation,
+    });
+    if (Buffer.byteLength(serialized) > MAX_PROFILE_BYTES) fail();
+    await directories(keyDirectory, privateRoot, true);
+    await writePrivate(join(keyDirectory, "agent.key"), credential);
+    await directories(settings.stateDirectory, privateRoot, true);
+    temporary = join(directory, `.profile-${randomUUID()}.tmp`);
+    await writePrivate(temporary, serialized);
+    await directories(directory, privateRoot);
+    if (existing) {
+      if (
+        (await boundedPrivateRead(join(directory, "profile.json"), MAX_PROFILE_BYTES)) !==
+        existing.serialized
+      )
+        fail();
+    } else {
+      try {
+        await lstat(join(directory, "profile.json"));
+        fail();
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    // The manifest is the only commit point. Previous private key generations are retained.
+    await rename(temporary, join(directory, "profile.json"));
+    temporary = undefined;
+    return publicProfile(profileName, directory, settings, generation, serialized);
+  } catch (error) {
+    safeFailure(error);
+  } finally {
+    if (temporary) await unlink(temporary).catch(() => {});
+    if (lock) {
+      await lock.close().catch(() => {});
+      await unlink(lockPath).catch(() => {});
+    }
+  }
+}