letagents 0.12.29 → 0.12.31

package/shared/agent-codenames.mjs

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+
+import { normalizeRoutingHandle, normalizeRoutingSender } from "./routing-aliases.mjs";
+
+/**
+ * The one pool of generated agent names. Every runtime that names an agent
+ * (the API, MCP, the desktop app and its daemon) draws from this list, so a
+ * name means the same thing wherever it was assigned.
+ *
+ * The order is part of the contract: a legacy MCP identity with no saved name
+ * re-derives its name, and therefore its key, from an index into this list.
+ * Append new words; never reorder or remove.
+ */
+export const AGENT_CODENAMES = Object.freeze([
+  "amber", "anchor", "autumn", "badger", "bay", "bear", "brook", "calm",
+  "canyon", "cedar", "clear", "cloud", "comet", "copper", "creek", "crisp",
+  "crest", "dawn", "delta", "dune", "ember", "falcon", "fern", "field",
+  "firefly", "fjord", "forest", "fox", "garden", "glade", "golden", "granite",
+  "grove", "harbor", "hawk", "hollow", "indigo", "ivory", "jade", "juniper",
+  "lagoon", "lake", "lantern", "leaf", "lively", "lunar", "lynx", "maple",
+  "marsh", "meadow", "mesa", "misty", "moon", "morrow", "moss", "noble",
+  "oak", "olive", "opal", "otter", "owl", "peak", "pearl", "pine",
+  "quiet", "raven", "reef", "ridge", "river", "rook", "sage", "scarlet",
+  "shore", "silver", "sky", "solar", "sparrow", "spring", "star", "stone",
+  "storm", "summit", "sun", "sunlit", "swift", "thicket", "tidal", "timber",
+  "trail", "valley", "verdant", "vista", "warm", "wave", "west", "wild",
+  "willow", "wind", "winter", "wolf", "wood", "wren",
+]);
+
+export const AGENT_CODENAME_SPACE = AGENT_CODENAMES.length * AGENT_CODENAMES.length;
+
+function titleCase(word) {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+/** Fused two-word codename at `index`, e.g. "RiverValley". Any integer wraps into the pool. */
+export function agentCodenameAt(index) {
+  const normalized = ((index % AGENT_CODENAME_SPACE) + AGENT_CODENAME_SPACE) % AGENT_CODENAME_SPACE;
+  const first = AGENT_CODENAMES[Math.floor(normalized / AGENT_CODENAMES.length)];
+  const second = AGENT_CODENAMES[normalized % AGENT_CODENAMES.length];
+  return `${titleCase(first)}${titleCase(second)}`;
+}
+
+export function agentCodenameSeedIndex(seed) {
+  return createHash("sha256").update(String(seed)).digest().readUInt32BE(0) % AGENT_CODENAME_SPACE;
+}
+
+/**
+ * The form in which two display names are the same name to a room. A display
+ * name is what people and agents type after "@", so names are compared the way
+ * mention routing compares them: "FieldMeadow", "fieldmeadow" and
+ * "Field Meadow" all answer to "@FieldMeadow" and cannot coexist.
+ */
+export function agentDisplayNameKey(displayName) {
+  return normalizeRoutingHandle(displayName) || normalizeRoutingSender(displayName);
+}
+
+/**
+ * A codename no listed name already answers to. The seed fixes where the scan
+ * starts, so one agent is offered the same name whenever the same names are
+ * held. Returns null only when the whole pool is held.
+ */
+export function suggestFreeAgentCodename(heldDisplayNames, seed) {
+  const held = new Set();
+  for (const name of heldDisplayNames ?? []) {
+    const key = agentDisplayNameKey(typeof name === "string" ? name : "");
+    if (key) held.add(key);
+  }
+  const start = agentCodenameSeedIndex(seed);
+  for (let offset = 0; offset < AGENT_CODENAME_SPACE; offset += 1) {
+    const candidate = agentCodenameAt(start + offset);
+    if (!held.has(agentDisplayNameKey(candidate))) return candidate;
+  }
+  return null;
+}
+
+const PLACEHOLDER_SUFFIX = " supervised agent";
+const PLACEHOLDER_PROVIDERS = new Set([
+  "codex", "claude", "claude-code", "claude code", "antigravity", "cursor",
+  "open-model", "open_model", "open model",
+]);
+
+/**
+ * Whether a name is what was written when no name was chosen: nothing,
+ * "Supervised agent", or a provider followed by "supervised agent". Only
+ * known providers count, so a name a person chose that happens to end the
+ * same way is left alone.
+ */
+export function isPlaceholderAgentDisplayName(displayName, provider) {
+  const name = String(displayName ?? "").trim().toLowerCase().replace(/\s+/g, " ");
+  if (!name || name === PLACEHOLDER_SUFFIX.trim()) return true;
+  if (!name.endsWith(PLACEHOLDER_SUFFIX)) return false;
+  const label = name.slice(0, -PLACEHOLDER_SUFFIX.length);
+  return PLACEHOLDER_PROVIDERS.has(label)
+    || label === String(provider ?? "").trim().toLowerCase();
+}

package/shared/daemon-maintenance.d.mts

@@ -0,0 +1,13 @@
+export interface DaemonMaintenanceHold { version: 1; id: string; createdAt: string }
+export function daemonMaintenancePath(root?: string): string;
+export const DAEMON_MAINTENANCE_MESSAGE: string;
+export function readDaemonMaintenance(path?: string): Promise<DaemonMaintenanceHold | null>;
+export function createDaemonMaintenance(path?: string): Promise<DaemonMaintenanceHold>;
+export function clearDaemonMaintenance(id: string, path?: string): Promise<void>;
+
+export interface DaemonMaintenanceOperation {
+  read(): Promise<DaemonMaintenanceHold | null>;
+  create(): Promise<DaemonMaintenanceHold>;
+  clear(id: string): Promise<void>;
+}
+export function withDaemonMaintenanceOperation<T>(operation: (owner: DaemonMaintenanceOperation) => Promise<T>, path?: string): Promise<T>;

package/shared/daemon-maintenance.mjs

@@ -0,0 +1,99 @@
+import { constants } from "node:fs";
+import { link, lstat, mkdir, open, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+
+export const daemonMaintenancePath = (root = join(homedir(), ".letagents")) => join(root, "daemon-maintenance.json");
+export const DAEMON_MAINTENANCE_MESSAGE = "Agent supervision is paused for service maintenance. Resume it in Settings → Updates.";
+
+async function syncDirectory(path) {
+  const directory = await open(dirname(path), "r");
+  try { await directory.sync(); } finally { await directory.close(); }
+}
+
+/** Only ENOENT means normal operation. Corruption or an unsafe path must fail closed. */
+export async function readDaemonMaintenance(path = daemonMaintenancePath()) {
+  let file;
+  try { file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > 4096 || (stat.mode & 0o077) !== 0
+      || (process.getuid && stat.uid !== process.getuid())) throw new Error("Unsafe service maintenance record.");
+    const value = JSON.parse(await file.readFile("utf8"));
+    if (value?.version !== 1 || typeof value.id !== "string" || !/^[a-f0-9-]{36}$/.test(value.id)
+      || typeof value.createdAt !== "string" || !Number.isFinite(Date.parse(value.createdAt))
+      || Object.keys(value).sort().join(",") !== "createdAt,id,version") throw new Error("Invalid service maintenance record.");
+    return value;
+  } finally { await file.close(); }
+}
+
+/** Publish a complete, fsynced hold before any daemon signal; never replace an existing hold. */
+async function publishHold(path) {
+  const existing = await readDaemonMaintenance(path);
+  if (existing) { await syncDirectory(path); return existing; }
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const value = { version: 1, id: randomUUID(), createdAt: new Date().toISOString() };
+  const temporary = `${path}.${value.id}.tmp`;
+  const file = await open(temporary, "wx", 0o600);
+  try {
+    await file.writeFile(`${JSON.stringify(value)}\n`, "utf8");
+    await file.sync();
+    try { await link(temporary, path); }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+    await syncDirectory(path);
+    const published = await readDaemonMaintenance(path);
+    if (!published) throw new Error("Service maintenance record disappeared before commit.");
+    return published;
+  } finally { await file.close(); await unlink(temporary); }
+}
+
+/** Explicit resume owns removal, after the held daemon has exited. */
+async function removeHold(id, path) {
+  const before = await lstat(path);
+  const value = await readDaemonMaintenance(path);
+  const after = await lstat(path);
+  if (!value || value.id !== id || before.ino !== after.ino || before.dev !== after.dev) {
+    throw new Error("Service maintenance changed. Refresh before resuming.");
+  }
+  await unlink(path);
+  await syncDirectory(path);
+}
+
+// Keep this inode forever. Unlinking a flock file can create two owners. Darwin
+// uses the kernel lock; non-Darwin tests model ownership in-process, like the
+// daemon singleton. Product maintenance is currently macOS-only.
+const simulatedClaims = new Set();
+export async function withDaemonMaintenanceOperation(operation, path = daemonMaintenancePath()) {
+  const lockPath = `${resolve(path)}.lock`;
+  await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+  const native = process.platform === "darwin";
+  if (!native && simulatedClaims.has(lockPath)) throw new Error("Another service maintenance action is in progress.");
+  if (!native) simulatedClaims.add(lockPath);
+  let lock;
+  let active = true;
+  const assertActive = () => { if (!active) throw new Error("Service maintenance action has ended."); };
+  try {
+    lock = await open(lockPath, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW
+      | constants.O_NONBLOCK | (native ? 0x20 /* Darwin O_EXLOCK */ : 0), 0o600);
+    const stat = await lock.stat();
+    if (!stat.isFile() || (stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid())) {
+      throw new Error("Unsafe service maintenance lock.");
+    }
+    return await operation({
+      read: () => { assertActive(); return readDaemonMaintenance(path); },
+      create: () => { assertActive(); return publishHold(path); },
+      clear: id => { assertActive(); return removeHold(id, path); },
+    });
+  } catch (error) {
+    if (["EAGAIN", "EWOULDBLOCK"].includes(error.code)) throw new Error("Another service maintenance action is in progress.");
+    throw error;
+  } finally {
+    active = false;
+    await lock?.close();
+    if (!native) simulatedClaims.delete(lockPath);
+  }
+}
+export const createDaemonMaintenance = (path = daemonMaintenancePath()) => withDaemonMaintenanceOperation(owner => owner.create(), path);
+export const clearDaemonMaintenance = (id, path = daemonMaintenancePath()) => withDaemonMaintenanceOperation(owner => owner.clear(id), path);

package/shared/permission-review.d.mts

@@ -0,0 +1,30 @@
+export const PERMISSION_REVIEW_APPROVE_AT: number;
+export const PERMISSION_REVIEW_RISKY_AT_MOST: number;
+export const PERMISSION_REVIEW_MAX_COMMANDS: number;
+export const PERMISSION_REVIEW_MAX_COMMAND_CHARS: number;
+export const PERMISSION_REVIEW_MAX_PROJECT_CHARS: number;
+
+export type PermissionReviewKind = "read" | "check" | "edit" | "risky";
+export type PermissionReviewAnswers = {
+  /** Null when the model did not give one consistent answer. */
+  kinds: Record<PermissionReviewKind, number> | null;
+};
+export type PermissionReviewDecision = "allow" | "ask";
+
+export type PermissionReviewRequest = {
+  state: { commands: string[]; project: string };
+  questions: Record<string, { type: "choice"; instructions: string; criteria: Record<string, string> }>;
+};
+
+/** True when a person must decide: no fixed rule can read the command in full. */
+export function commandNeedsPerson(command: unknown, project: unknown): boolean;
+
+/** Null when the fixed rules already require a person. */
+export function buildPermissionReviewRequest(input: {
+  commands: readonly string[];
+  project: string;
+}): PermissionReviewRequest | null;
+
+export function parsePermissionReviewAnswers(body: unknown): PermissionReviewAnswers;
+
+export function decidePermissionReview(answers: PermissionReviewAnswers | null | undefined): PermissionReviewDecision;