totemlayer 0.1.2 → 0.1.3

package/bin/network.mjs

@@ -0,0 +1,323 @@
+import { parseArgs, stripVTControlCharacters } from "node:util";
+import { readFile, stat } from "node:fs/promises";
+import { Totem } from "./sdk/index.js";
+import { runCollaborationListener } from "./collaboration-listener.mjs";
+import { runRuntime } from "./network-runtime.mjs";
+
+export const NETWORK_HELP = `Totem agent messaging
+
+One-time setup in the Totem app:
+  Open Agents in the Totem app, register an agent, and create an API key.
+  Store its key in a private file (0600), then set TOTEM_NETWORK_API_KEY_FILE.
+  Alternatively set TOTEM_NETWORK_API_KEY. Never pass keys as command arguments.
+  Set TOTEM_BASE_URL to your Totem origin; HTTP is allowed only on loopback.
+
+Local adoption:
+  export TOTEM_BASE_URL=http://localhost:3413
+  totem network me --json
+  totem network work --allow-agent peer@workspace.totem --provider codex
+  # Or use --provider claude after configuring Claude's Totem MCP server.
+  totem network run --provider ollama --model qwen3.5:9b
+  Open Chat in Totem and send your agent a message.
+
+Commands:
+  totem network me
+  totem network send --to <address> --text <text> [--conversation-hops <2-8>]
+    [--idempotency-key <key>]
+  totem network inbox [--all] [--cursor <cursor>] [--limit <1-100>]
+  totem network reply <message-id> --text <text> [--idempotency-key <key>]
+  totem network ack <message-id>
+  totem network listen [--once] [--poll-ms <milliseconds>]
+  totem network work --allow-agent <exact-peer-address> --provider codex|claude
+    [--repo-root <checkout>] [--check] [--once] [--poll-ms 5000]
+  totem network chat list [--cursor <cursor>] [--limit <1-100>]
+  totem network chat show <chat-id>
+  totem network chat updates <chat-id> --text <text> [--idempotency-key <key>]
+  totem network run --provider ollama --model <installed-model>
+    [--allow-agent <exact-address>]... [--auto-reply-hops <0-8>]
+    [--system-file <path>] [--once]
+    [--poll-ms 1000] [--model-timeout-ms 120000] [--reply-timeout-ms 90000]
+    [--ollama-url http://127.0.0.1:11434] [--state-dir <private-directory>]
+
+All commands accept --json for machine-readable output and --base-url <origin>.
+--text-file <path> can replace --text (UTF-8, at most 32 KiB).
+listen prints incoming messages without replying or acknowledging; acknowledge
+only after your own agent has handled them. Stream output is newline-delimited JSON.
+work is an opt-in local listener for one peer and one Git checkout. It runs the
+owner's installed Codex or Claude CLI on matching task messages, resumes that
+client's task for later peer messages, and journals each message before launch.
+It never silently retries an uncertain or failed model run. Configure Totem MCP
+in that AI app first; neither a Totem key nor a peer message grants Git access.
+--check validates the agent, peer, and checkout without processing messages.
+run executes a real local model for human commands and new A2A messages. It renews
+leases and heartbeats, and acknowledges only handled messages. By default it
+ignores reply loops. A send with --conversation-hops and two runtimes with
+--auto-reply-hops can continue a bounded exchange with exact allowed peers.
+In human Chat, /ask <allowed-address> <message> routes directly and returns the
+actual peer reply without relying on model tool selection. Both /ask and the
+optional ask_agent model tool are restricted to --allow-agent addresses.
+There are no shell, payment, or arbitrary tool actions. Model/DNS/email services
+are not provided by this command. Ctrl+C stops requests; unfinished leases expire.
+`;
+
+function numberOption(value, fallback, min, max, label) {
+  const result = value === undefined ? fallback : Number(value);
+  if (!Number.isInteger(result) || result < min || result > max)
+    throw Object.assign(new Error(`${label} must be an integer from ${min} to ${max}.`), {
+      code: "INVALID_ARGUMENT",
+    });
+  return result;
+}
+
+export function parseNetworkArgs(args) {
+  const parsed = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      help: { type: "boolean", short: "h" },
+      json: { type: "boolean" },
+      "base-url": { type: "string" },
+      to: { type: "string" },
+      text: { type: "string" },
+      "text-file": { type: "string" },
+      "idempotency-key": { type: "string" },
+      cursor: { type: "string" },
+      limit: { type: "string" },
+      all: { type: "boolean" },
+      once: { type: "boolean" },
+      check: { type: "boolean" },
+      "poll-ms": { type: "string" },
+      provider: { type: "string" },
+      model: { type: "string" },
+      "ollama-url": { type: "string" },
+      "allow-agent": { type: "string", multiple: true },
+      "conversation-hops": { type: "string" },
+      "auto-reply-hops": { type: "string" },
+      "system-file": { type: "string" },
+      "model-timeout-ms": { type: "string" },
+      "reply-timeout-ms": { type: "string" },
+      "state-dir": { type: "string" },
+      "repo-root": { type: "string" },
+    },
+  });
+  return { ...parsed.values, positionals: parsed.positionals };
+}
+
+async function textInput(options) {
+  if (options.text !== undefined && options["text-file"] !== undefined)
+    throw new Error("Choose --text or --text-file, not both.");
+  let text = options.text;
+  if (options["text-file"]) {
+    if ((await stat(options["text-file"])).size > 32 * 1024)
+      throw new Error("Text files must not exceed 32 KiB.");
+    const content = await readFile(options["text-file"]);
+    if (content.byteLength > 32 * 1024) throw new Error("Text files must not exceed 32 KiB.");
+    text = new TextDecoder("utf-8", { fatal: true }).decode(content);
+  }
+  if (typeof text !== "string" || !text.trim() || Buffer.byteLength(text) > 32 * 1024)
+    throw new Error("Provide --text or --text-file containing 1–32768 bytes.");
+  return text;
+}
+
+function required(value, description) {
+  if (!value) throw new Error(`Provide ${description}.`);
+  return value;
+}
+
+export function safeOutput(value, secrets = []) {
+  let output = JSON.stringify(value);
+  for (const secret of secrets) if (secret) output = output.split(secret).join("[REDACTED]");
+  return output;
+}
+
+export async function networkMain(args) {
+  const json = args.includes("--json");
+  let secret = process.env.TOTEM_NETWORK_API_KEY;
+  const emit = (value) => process.stdout.write(`${safeOutput(value, [secret])}\n`);
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  try {
+    const options = parseNetworkArgs(args);
+    const [command, action, id] = options.positionals;
+    if (options.help || !command || command === "help") {
+      process.stdout.write(NETWORK_HELP);
+      return;
+    }
+    if (process.env.TOTEM_NETWORK_API_KEY_FILE) {
+      if (secret)
+        throw new Error("Set only one of TOTEM_NETWORK_API_KEY and TOTEM_NETWORK_API_KEY_FILE.");
+      const path = process.env.TOTEM_NETWORK_API_KEY_FILE;
+      const info = await stat(path);
+      if (
+        !info.isFile() ||
+        info.size > 8192 ||
+        (process.platform !== "win32" && (info.mode & 0o077) !== 0)
+      )
+        throw new Error("The key file must be a regular private file (chmod 600), at most 8 KiB.");
+      secret = (await readFile(path, "utf8")).trim();
+    }
+    if (!secret?.trim())
+      throw new Error(
+        "Set TOTEM_NETWORK_API_KEY or TOTEM_NETWORK_API_KEY_FILE to an agent API key from Agents.",
+      );
+    const baseUrl = options["base-url"] ?? process.env.TOTEM_BASE_URL;
+    const client = new Totem({ apiKey: secret, baseUrl });
+    const signal = controller.signal;
+    const query = {
+      limit: numberOption(options.limit, 50, 1, 100, "--limit"),
+      ...(options.cursor ? { cursor: options.cursor } : {}),
+    };
+    const write = { idempotencyKey: options["idempotency-key"], signal };
+    let result;
+    if (command === "me") result = await client.agent({ signal });
+    else if (command === "send")
+      result = await client.send(
+        {
+          to: required(options.to, "--to <address>"),
+          text: await textInput(options),
+          ...(options["conversation-hops"] === undefined
+            ? {}
+            : {
+                metadata: {
+                  totemAutonomy: {
+                    version: 1,
+                    maxHops: numberOption(
+                      options["conversation-hops"],
+                      0,
+                      2,
+                      8,
+                      "--conversation-hops",
+                    ),
+                  },
+                },
+              }),
+        },
+        write,
+      );
+    else if (command === "inbox") {
+      emit(
+        await client.messages.list(
+          { ...query, direction: "inbound", ...(options.all ? {} : { unread: true }) },
+          { signal },
+        ),
+      );
+      return;
+    } else if (command === "reply")
+      result = await client.messages.reply(
+        required(action, "a message ID"),
+        await textInput(options),
+        write,
+      );
+    else if (command === "ack")
+      result = await client.messages.ack(required(action, "a message ID"), { signal });
+    else if (command === "chat" && action === "list") {
+      emit(await client.chats.list(query, { signal }));
+      return;
+    } else if (command === "chat" && action === "show")
+      result = await client.chats.get(required(id, "a chat ID"), { ...query, signal });
+    else if (command === "chat" && action === "updates")
+      result = await client.chats.updates(
+        required(id, "a chat ID"),
+        await textInput(options),
+        write,
+      );
+    else if (command === "listen" || command === "run" || command === "work") {
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+      const interval = numberOption(options["poll-ms"], 1000, 100, 60000, "--poll-ms");
+      if (command === "work") {
+        if (!process.env.TOTEM_NETWORK_API_KEY_FILE)
+          throw new Error(
+            "work requires TOTEM_NETWORK_API_KEY_FILE so the local agent process never inherits a raw Totem key.",
+          );
+        if ((options["allow-agent"] ?? []).length !== 1)
+          throw new Error("work requires exactly one --allow-agent <exact-peer-address>.");
+        await runCollaborationListener({
+          client,
+          signal,
+          emit,
+          once: options.once,
+          checkOnly: options.check,
+          pollMs: numberOption(options["poll-ms"], 5000, 1000, 60000, "--poll-ms"),
+          peerAddress: options["allow-agent"][0],
+          provider: options.provider ?? "codex",
+          repositoryRoot: options["repo-root"] ?? process.cwd(),
+          stateDirectory: options["state-dir"],
+        });
+      } else if (command === "listen") {
+        do {
+          for await (const message of client.messages.iterate(
+            { direction: "inbound", unread: true, limit: 100 },
+            { signal },
+          ))
+            emit({ type: "message", data: message });
+          if (!options.once) await pause(interval, signal);
+        } while (!signal.aborted && !options.once);
+      } else {
+        await runRuntime({
+          client,
+          signal,
+          emit,
+          once: options.once,
+          pollMs: interval,
+          baseUrl,
+          provider: options.provider,
+          model: options.model,
+          ollamaUrl: options["ollama-url"],
+          allowAgents: options["allow-agent"] ?? [],
+          autoReplyHops: numberOption(options["auto-reply-hops"], 0, 0, 8, "--auto-reply-hops"),
+          systemFile: options["system-file"],
+          stateDir: options["state-dir"],
+          modelTimeoutMs: numberOption(
+            options["model-timeout-ms"],
+            120000,
+            1000,
+            600000,
+            "--model-timeout-ms",
+          ),
+          replyTimeoutMs: numberOption(
+            options["reply-timeout-ms"],
+            90000,
+            1000,
+            600000,
+            "--reply-timeout-ms",
+          ),
+        });
+      }
+      return;
+    } else throw new Error("Unknown network command. Run totem network --help.");
+    emit({ data: result });
+  } catch (error) {
+    if (controller.signal.aborted) return;
+    const payload = {
+      error: {
+        code: error.code ?? "COMMAND_FAILED",
+        message: error.message ?? "The network command failed.",
+        ...(error.requestId ? { requestId: error.requestId } : {}),
+      },
+    };
+    if (json) emit(payload);
+    else process.stderr.write(`${stripVTControlCharacters(safeOutput(payload, [secret]))}\n`);
+    process.exitCode = 1;
+  } finally {
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+  }
+}
+
+export function pause(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      reject(new Error("Runtime stopped."));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+  });
+}

package/bin/presenter-mcp.mjs

@@ -0,0 +1,238 @@
+import { execFile } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { promisify } from "node:util";
+
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod/v4";
+
+const execFileAsync = promisify(execFile);
+const VERSION = "0.1.0";
+const MAX_KEY_BYTES = 8 * 1024;
+const DEFAULT_BASE_URL = "https://totemlayer.com";
+
+function clean(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function result(value) {
+  const data = clean(value);
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    structuredContent: { data },
+  };
+}
+
+function toolError(error) {
+  const payload = {
+    error: {
+      code:
+        error && typeof error === "object" && typeof error.code === "string"
+          ? error.code
+          : "TOTEM_PRESENTER_ERROR",
+      message: error instanceof Error ? error.message : "The Totem request failed.",
+      ...(error && typeof error === "object" && typeof error.requestId === "string"
+        ? { requestId: error.requestId }
+        : {}),
+    },
+  };
+  return {
+    isError: true,
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    structuredContent: payload,
+  };
+}
+
+function validatePresenterKey(value) {
+  const key = value.trim();
+  if (!/^at_(?:live|test)_[A-Za-z0-9_-]+$/.test(key)) {
+    throw new Error(
+      "The configured credential is not a Totem presenter API key. Use the at_live_ or at_test_ key bound to this agent with credential.present access.",
+    );
+  }
+  return key;
+}
+
+async function readPrivateFile(path) {
+  const info = await stat(path);
+  if (!info.isFile() || info.size > MAX_KEY_BYTES) {
+    throw new Error("The presenter key file must be a regular file no larger than 8 KiB.");
+  }
+  if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
+    throw new Error(
+      "The presenter key file must be private. Run chmod 600 on it before connecting.",
+    );
+  }
+  return readFile(path, "utf8");
+}
+
+async function readMacOSKeychain(service, account) {
+  if (process.platform !== "darwin") {
+    throw new Error("macOS Keychain credentials are available only on macOS.");
+  }
+  try {
+    const { stdout } = await execFileAsync(
+      "/usr/bin/security",
+      ["find-generic-password", "-s", service, "-a", account, "-w"],
+      { encoding: "utf8", maxBuffer: MAX_KEY_BYTES },
+    );
+    return stdout;
+  } catch {
+    throw new Error(
+      `No Totem presenter key was found in macOS Keychain for service ${service} and account ${account}.`,
+    );
+  }
+}
+
+export async function readTotemPresenterKey(environment = process.env) {
+  const direct = environment.TOTEM_AGENT_API_KEY?.trim();
+  const keyFile = environment.TOTEM_AGENT_API_KEY_FILE?.trim();
+  const keychainService = environment.TOTEM_AGENT_KEYCHAIN_SERVICE?.trim();
+  const keychainAccount = environment.TOTEM_AGENT_KEYCHAIN_ACCOUNT?.trim();
+  const sources = [Boolean(direct), Boolean(keyFile), Boolean(keychainService)].filter(Boolean);
+
+  if (sources.length !== 1) {
+    throw new Error(
+      "Configure exactly one Totem presenter key source: TOTEM_AGENT_API_KEY, TOTEM_AGENT_API_KEY_FILE, or TOTEM_AGENT_KEYCHAIN_SERVICE.",
+    );
+  }
+
+  if (direct) return validatePresenterKey(direct);
+  if (keyFile) return validatePresenterKey(await readPrivateFile(keyFile));
+  if (!keychainService) throw new Error("A Totem presenter key source is required.");
+  if (!keychainAccount) {
+    throw new Error("TOTEM_AGENT_KEYCHAIN_ACCOUNT is required with the Keychain service.");
+  }
+  return validatePresenterKey(await readMacOSKeychain(keychainService, keychainAccount));
+}
+
+function baseUrl(environment) {
+  const value =
+    environment.TOTEM_URL?.trim() || environment.TOTEM_BASE_URL?.trim() || DEFAULT_BASE_URL;
+  const url = new URL(value);
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:")) {
+    throw new Error("TOTEM_URL must use HTTPS, except for an explicit localhost development URL.");
+  }
+  return url.origin;
+}
+
+export async function loadTotemPresenterMcpConfig(environment = process.env) {
+  const apiKey = await readTotemPresenterKey(environment);
+  return {
+    apiKey,
+    baseUrl: baseUrl(environment),
+    label: environment.TOTEM_AGENT_LABEL?.trim() || "Configured Totem agent",
+    environment: apiKey.startsWith("at_live_") ? "PRODUCTION" : "SANDBOX",
+  };
+}
+
+async function parseResponse(response) {
+  const text = await response.text();
+  let payload;
+  try {
+    payload = text ? JSON.parse(text) : {};
+  } catch {
+    payload = {};
+  }
+  if (response.ok) return payload;
+
+  const apiError = payload && typeof payload === "object" ? payload.error : undefined;
+  const error = new Error(
+    apiError && typeof apiError.message === "string"
+      ? apiError.message
+      : `Totem returned HTTP ${response.status}.`,
+  );
+  if (apiError && typeof apiError.code === "string") error.code = apiError.code;
+  if (apiError && typeof apiError.requestId === "string") error.requestId = apiError.requestId;
+  throw error;
+}
+
+export function createTotemPresenterMcpServer(config, options = {}) {
+  const fetchImpl = options.fetch ?? fetch;
+  const server = new McpServer(
+    { name: "totem-presenter", version: VERSION },
+    {
+      instructions:
+        "This connector presents Totem credentials as the agent bound to its configured credential. The credential determines identity and cannot be overridden by tool input. Call totem_get_presenter_config to inspect the local configuration. Call totem_present_credential only for a receiver-provided challenge and an intended credential; it creates a short-lived signed proof but does not itself authorize or execute an external action.",
+    },
+  );
+
+  server.registerTool(
+    "totem_get_presenter_config",
+    {
+      title: "Get Totem presenter configuration",
+      description:
+        "Show the local label, Totem host, and environment for this presenter connector without revealing its key.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    },
+    async () =>
+      result({
+        label: config.label,
+        baseUrl: config.baseUrl,
+        environment: config.environment,
+        capability: "credential.present",
+        identityBinding:
+          "Totem derives the actual presenter agent from the configured key when a proof is created.",
+      }),
+  );
+
+  server.registerTool(
+    "totem_present_credential",
+    {
+      title: "Present a Totem credential",
+      description:
+        "Create a short-lived, challenge-bound proof using the agent identity bound to this connector's credential.",
+      inputSchema: z.object({
+        credentialId: z.string().trim().min(1).max(100),
+        challengeId: z.string().trim().min(1).max(100),
+        nonce: z
+          .string()
+          .trim()
+          .min(32)
+          .max(256)
+          .regex(/^[A-Za-z0-9_-]+$/),
+      }),
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    async (input) => {
+      try {
+        const response = await fetchImpl(`${config.baseUrl}/api/v1/presentations`, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${config.apiKey}`,
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(input),
+          redirect: "error",
+          signal: AbortSignal.timeout(15_000),
+        });
+        return result(await parseResponse(response));
+      } catch (error) {
+        return toolError(error);
+      }
+    },
+  );
+
+  return server;
+}
+
+export async function presenterMcpMain(environment = process.env) {
+  try {
+    const config = await loadTotemPresenterMcpConfig(environment);
+    serveStdio(() => createTotemPresenterMcpServer(config), {
+      onerror: (error) => console.error(`Totem presenter MCP: ${error.message}`),
+    });
+    console.error(`Totem presenter MCP is ready for ${config.label}.`);
+  } catch (error) {
+    console.error(
+      error instanceof Error ? error.message : "Could not start the Totem presenter MCP server.",
+    );
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  await presenterMcpMain();
+}

package/bin/repository.d.mts

@@ -0,0 +1,27 @@
+export interface LocalRepository {
+  repository: string;
+  headCommit: string;
+  currentBranch: string | null;
+  clean: boolean;
+}
+
+export interface RepoVerification extends LocalRepository {
+  repositoryMatches: boolean;
+  baseMatches: boolean;
+  branchMatches: boolean;
+  baseAncestor: boolean;
+  changedPaths: string[];
+  outOfScopePaths: string[];
+  locallyVerified: boolean;
+  remotelyVerified: false;
+}
+
+export function repositoryIdFromRemote(remote: string): string;
+export function inspectLocalRepository(
+  environment?: Record<string, string | undefined>,
+): Promise<LocalRepository>;
+export function verifyLocalRepoClaim(
+  task: { repository: string; baseCommit: string },
+  claim: { repository: string; baseCommit: string; branch: string; paths: string[] },
+  environment?: Record<string, string | undefined>,
+): Promise<RepoVerification>;