auggy 0.3.0

package/src/cli/agent-index.ts

@@ -0,0 +1,289 @@
+/**
+ * Agent index — `~/.auggy/agents.json`.
+ *
+ * Maps agent name → { localDir, createdAt, cloud }. Load-bearing facility
+ * metadata: every CLI command that finds an agent on disk goes through here.
+ *
+ * Pattern mirrors `pid-registry.ts`: atomic write via temp+rename, defensive
+ * recovery on corruption, no in-memory caching across invocations.
+ */
+
+import {
+  closeSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { IndexFile, IndexEntry } from "./types";
+
+const SCHEMA_VERSION = 1 as const;
+
+// Lock acquisition tuning. Spin with short busy-waits up to LOCK_TIMEOUT_MS,
+// matching the cadence in pid-registry's other file-coordination paths.
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_POLL_MS = 50;
+
+interface IndexOptions {
+  /** Override `~/.auggy/` for tests. Production callers omit. */
+  auggyDir?: string;
+}
+
+function getAuggyDir(opts: IndexOptions = {}): string {
+  return opts.auggyDir ?? join(homedir(), ".auggy");
+}
+
+function indexPath(opts: IndexOptions): string {
+  return join(getAuggyDir(opts), "agents.json");
+}
+
+function ensureDir(opts: IndexOptions): void {
+  mkdirSync(getAuggyDir(opts), { recursive: true });
+}
+
+function emptyIndex(): IndexFile {
+  return { version: SCHEMA_VERSION, agents: {} };
+}
+
+function lockPath(opts: IndexOptions): string {
+  return join(getAuggyDir(opts), "agents.json.lock");
+}
+
+interface LockHandle {
+  release: () => void;
+}
+
+interface LockFileContents {
+  pid: number;
+  acquired: string;
+}
+
+/**
+ * Try to atomically create the lock file. Returns a release handle on
+ * success, or null if the lock is already held (EEXIST). Any other I/O
+ * error propagates.
+ *
+ * Extracted from `acquireLock` so the happy path and the force-recovery
+ * retry path share a single implementation.
+ */
+function tryAcquire(path: string, body: string): LockHandle | null {
+  try {
+    const fd = openSync(path, "wx");
+    try {
+      writeSync(fd, body);
+    } finally {
+      closeSync(fd);
+    }
+    return {
+      release: () => {
+        try {
+          unlinkSync(path);
+        } catch {
+          // Already gone — nothing to do.
+        }
+      },
+    };
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+    return null;
+  }
+}
+
+/**
+ * Acquire a cross-process advisory lock on `agents.json.lock`.
+ *
+ * Uses `openSync(path, "wx")` for atomic exclusive create — same primitive
+ * used by `pid-registry` for atomic per-agent manifests. On EEXIST: busy-wait
+ * `LOCK_POLL_MS` and retry until `LOCK_TIMEOUT_MS` elapses. Once the deadline
+ * passes we assume the previous holder crashed, force-unlink the lock, and
+ * retry once. If that retry still fails (e.g. permissions/IO error), throw.
+ *
+ * Why time-based recovery instead of PID liveness checks: reading the lock
+ * file's content to extract a holder PID requires a second `openSync(path, "r")`,
+ * which CodeQL flags as TOCTOU against the EEXIST signal even though we only
+ * extract a number. Time-based recovery uses a single primitive (`openSync(wx)`),
+ * so there is no path-based race surface to flag.
+ *
+ * Synchronous on purpose — the rest of this module is sync, and CLI mutators
+ * are short-running. Blocking the event loop for at most 5s is acceptable.
+ */
+function acquireLock(opts: IndexOptions = {}): LockHandle {
+  ensureDir(opts);
+  const path = lockPath(opts);
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+  const body = JSON.stringify({
+    pid: process.pid,
+    acquired: new Date().toISOString(),
+  } satisfies LockFileContents);
+
+  for (;;) {
+    const handle = tryAcquire(path, body);
+    if (handle) return handle;
+
+    if (Date.now() >= deadline) {
+      // Force-recover: assume the previous holder crashed.
+      try {
+        unlinkSync(path);
+      } catch {
+        // Race: someone else cleaned it up. Recovery retry below will succeed.
+      }
+      const recovered = tryAcquire(path, body);
+      if (recovered) return recovered;
+      throw new Error(
+        `Could not acquire agents.json lock at ${path} after ${LOCK_TIMEOUT_MS}ms ` +
+          `(another process holding it).`,
+      );
+    }
+
+    Bun.sleepSync(LOCK_POLL_MS);
+  }
+}
+
+/**
+ * Read the index. Returns an empty index when the file doesn't exist.
+ *
+ * On JSON parse failure, backs up the corrupt file to
+ * `agents.json.corrupt-<ISO>` and returns an empty index — operator can
+ * recover from the backup if needed.
+ *
+ * Throws on unknown schema versions (forward-compat guard).
+ */
+export function readIndex(opts: IndexOptions = {}): IndexFile {
+  const path = indexPath(opts);
+
+  // Open via fd to avoid existsSync+readFileSync TOCTOU.
+  let fd: number;
+  try {
+    fd = openSync(path, "r");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return emptyIndex();
+    }
+    throw err;
+  }
+
+  let raw: string;
+  try {
+    const stats = fstatSync(fd);
+    const buf = Buffer.alloc(stats.size);
+    if (stats.size > 0) {
+      readSync(fd, buf, 0, stats.size, 0);
+    }
+    raw = buf.toString("utf-8");
+  } finally {
+    try {
+      closeSync(fd);
+    } catch {
+      // best-effort
+    }
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (_err) {
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const backupPath = join(getAuggyDir(opts), `agents.json.corrupt-${ts}`);
+    renameSync(path, backupPath);
+    console.warn(
+      `[agent-index] corrupt agents.json detected; backed up to ${backupPath}. Recreating empty index.`,
+    );
+    return emptyIndex();
+  }
+
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    (parsed as { version?: number }).version !== SCHEMA_VERSION
+  ) {
+    const got = (parsed as { version?: number } | null)?.version;
+    throw new Error(
+      `agents.json has unknown schema version ${got} (expected ${SCHEMA_VERSION}). ` +
+        `This file may be from a newer version of auggy.`,
+    );
+  }
+
+  return parsed as IndexFile;
+}
+
+/**
+ * Write the index atomically: write to `agents.json.tmp`, then rename
+ * over the target. Same hygiene as `pid-registry.ts`.
+ */
+export function writeIndex(idx: IndexFile, opts: IndexOptions = {}): void {
+  ensureDir(opts);
+  const target = indexPath(opts);
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, JSON.stringify(idx, null, 2));
+  renameSync(tmp, target);
+}
+
+/**
+ * Add an agent to the index. Throws if `name` is already registered.
+ *
+ * Holds an advisory lock for the read-modify-write window so two concurrent
+ * CLI invocations don't lose each other's updates.
+ */
+export function addAgent(name: string, localDir: string, opts: IndexOptions = {}): void {
+  const lock = acquireLock(opts);
+  try {
+    const idx = readIndex(opts);
+    if (idx.agents[name]) {
+      throw new Error(
+        `Agent "${name}" already registered at ${idx.agents[name].localDir}. ` +
+          `Choose a different name or remove the existing one with \`auggy remove ${name}\`.`,
+      );
+    }
+    idx.agents[name] = {
+      localDir,
+      createdAt: new Date().toISOString(),
+      cloud: null,
+    };
+    writeIndex(idx, opts);
+  } finally {
+    lock.release();
+  }
+}
+
+/**
+ * Remove an agent from the index. Idempotent — no-op when not present.
+ *
+ * Holds an advisory lock for the read-modify-write window. The lock is
+ * released even when no entry exists.
+ */
+export function removeAgent(name: string, opts: IndexOptions = {}): void {
+  const lock = acquireLock(opts);
+  try {
+    const idx = readIndex(opts);
+    if (!idx.agents[name]) return;
+    delete idx.agents[name];
+    writeIndex(idx, opts);
+  } finally {
+    lock.release();
+  }
+}
+
+/**
+ * Look up an agent by name. Returns null if not registered.
+ */
+export function getAgent(name: string, opts: IndexOptions = {}): IndexEntry | null {
+  const idx = readIndex(opts);
+  return idx.agents[name] ?? null;
+}
+
+/**
+ * List all registered agents with their names.
+ */
+export function listAgents(opts: IndexOptions = {}): Array<IndexEntry & { name: string }> {
+  const idx = readIndex(opts);
+  return Object.entries(idx.agents).map(([name, entry]) => ({
+    name,
+    ...entry,
+  }));
+}

package/src/cli/augment-catalog.ts

@@ -0,0 +1,320 @@
+/**
+ * Augment catalog — metadata for all built-in augments.
+ *
+ * Used by `auggy create` (interactive selection) and `auggy add`
+ * (add to existing agent). Each entry describes what the augment
+ * does, its default config, and whether it ships with a bundled skill
+ * folder under `src/augments/<type>/skill/`.
+ *
+ * Skills are no longer carried as inline string templates here. Per
+ * ADR-025 + PR α task 4, scaffold copies `src/augments/<name>/skill/`
+ * into the agent dir directly; the catalog only records *whether* a
+ * bundled skill exists so the create UI can label entries accurately.
+ * The `scaffold-skills` module is the single source of truth for the
+ * type → folder mapping.
+ */
+
+export interface CatalogEntry {
+  /** Display name for selection UI. */
+  label: string;
+  /** Short description shown in the selector. */
+  description: string;
+  /** The augment type identifier in agent.yaml. */
+  type: string;
+  /** Default instance name in agent.yaml. */
+  defaultName: string;
+  /** Default options for agent.yaml. */
+  defaultOptions: Record<string, unknown>;
+  /** Whether this augment is always included (not deselectable). */
+  required: boolean;
+  /** Env vars this augment needs (shown in .env.example). */
+  envVars?: string[];
+  /**
+   * Whether this augment ships a bundled `src/augments/<type>/skill/` folder
+   * the scaffold copies into the agent dir. Authoritative state lives on
+   * disk; this flag is informational for the create UI.
+   */
+  hasSkill: boolean;
+}
+
+export const AUGMENT_CATALOG: CatalogEntry[] = [
+  // NOTE on identity: the agent's identity preamble is mounted via the
+  // top-level `identity: ./identity.md` shorthand (see config-parser §α-5),
+  // not via a catalog entry. Keeping an explicit fileMemory@system entry
+  // here AND emitting the shorthand would trigger α-5's conflict check on
+  // the very first scaffold. The scaffold and the create command emit the
+  // shorthand directly; the catalog never carries an identity row.
+  {
+    label: "fileMemory (learned)",
+    description: "Mutable memory — agent writes learned behaviors here",
+    type: "fileMemory",
+    defaultName: "learned",
+    defaultOptions: {
+      label: "learned",
+      source: "./learned.md",
+      mutable: true,
+      origin: "system",
+      priority: "high",
+      placement: "preamble",
+      eviction: "drop",
+    },
+    required: true,
+    hasSkill: false,
+  },
+  {
+    label: "layeredMemory",
+    description: "Peer-scoped episodic memory with provenance (SQLite or Supabase)",
+    type: "layeredMemory",
+    defaultName: "memory",
+    defaultOptions: {
+      backend: "sqlite",
+      dbPath: "./memory.sqlite",
+      namespace: "ep",
+      retentionDays: 90,
+    },
+    required: true,
+    hasSkill: true,
+  },
+  {
+    label: "filesystem",
+    description: "Read/write files — skills directory + workspace",
+    type: "filesystem",
+    defaultName: "files",
+    defaultOptions: {
+      mounts: [
+        { name: "skills", path: "./skills", writable: false },
+        { name: "workspace", path: "./workspace", writable: true, deletable: true },
+      ],
+    },
+    required: true,
+    hasSkill: true,
+  },
+  {
+    label: "webTransport",
+    description: "AG-UI chat endpoint (HTTP + SSE)",
+    type: "webTransport",
+    defaultName: "web",
+    defaultOptions: {
+      port: 8080,
+      auth: { type: "bearer", token: "${AUGGY_WEB_TOKEN}" },
+      visitorTokens: {
+        // signingKey is NOT set here — visitorAuth is the single source of truth
+        // and the resolver injects it. Setting it here would trigger the
+        // duplicate-key warning on every boot.
+        agentBinding: "${AUGGY_AGENT_ID}",
+      },
+    },
+    required: false,
+    envVars: ["AUGGY_WEB_TOKEN", "AUGGY_AGENT_ID"],
+    hasSkill: false,
+  },
+  {
+    label: "webFetch",
+    description: "Fetch URLs, read web pages, call HTTP APIs",
+    type: "webFetch",
+    defaultName: "fetch",
+    defaultOptions: {
+      timeoutMs: 15000,
+    },
+    required: false,
+    hasSkill: true,
+  },
+  {
+    label: "supabaseMemory",
+    description: "Episodic memory backed by Supabase (visitor profiles, events)",
+    type: "supabaseMemory",
+    defaultName: "episodic",
+    defaultOptions: {
+      namespace: "episode",
+      table: "agent_memories",
+      mutable: true,
+      origin: "peer-derived",
+      priority: "normal",
+      placement: "preamble",
+      eviction: "drop",
+      supabaseUrl: "${SUPABASE_URL}",
+      supabaseKey: "${SUPABASE_SERVICE_KEY}",
+    },
+    required: false,
+    envVars: ["SUPABASE_URL", "SUPABASE_SERVICE_KEY"],
+    hasSkill: false,
+  },
+  {
+    label: "orgContext",
+    description: "Connect to org knowledge API (manifest + org_fetch)",
+    type: "orgContext",
+    defaultName: "org",
+    defaultOptions: {
+      // Default to file:// scheme pointing at the scaffolded example dir
+      // (per α-6 + spec §Decision 9). Operators wanting an HTTP-served
+      // manifest replace this with `${ORG_CONTEXT_URL}` and provide the env.
+      baseUrl: "file://./org-context",
+    },
+    required: false,
+    hasSkill: true,
+  },
+  {
+    // ADR-030: model-facing skill surface. Emits a single system-placement
+    // context block listing each mounted skill's name + description (read
+    // from each SKILL.md's YAML frontmatter, agentskills.io standard).
+    // Activation is fs_read via the filesystem augment. Required because
+    // without it no skills are surfaced to the model; operators wanting an
+    // agent with literally zero skill discovery can edit agent.yaml after
+    // scaffolding.
+    label: "skills",
+    description: "Lists mounted skills for the model (ADR-030 skill surface)",
+    type: "skills",
+    defaultName: "skills",
+    defaultOptions: {
+      dir: "./skills",
+    },
+    required: true,
+    // The augment itself carries no skill — it IS the skill surface.
+    hasSkill: false,
+  },
+  {
+    label: "bash",
+    description: "Execute shell commands with configurable risk levels",
+    type: "bash",
+    defaultName: "bash",
+    defaultOptions: {
+      risk: "restricted",
+      allowedCommands: ["echo", "ls", "cat", "pwd", "date"],
+    },
+    required: false,
+    hasSkill: true,
+  },
+  {
+    label: "budgets",
+    description: "Per-trust-level turn budgets + dailyBudgetUsd ceiling (SQLite)",
+    type: "budgets",
+    defaultName: "budgets",
+    defaultOptions: {
+      dbPath: "./budgets.db",
+      caps: {
+        public: {
+          recognized: { maxTurnsPerThread: 20, maxTurnsPerDay: 50, maxUsdPerDay: 1 },
+          anonymous: { maxTurnsPerThread: 5 },
+        },
+      },
+      anonymousGlobalLimit: 30,
+      dailyBudgetUsd: 5,
+    },
+    required: false,
+    hasSkill: false,
+  },
+  {
+    label: "notify",
+    description:
+      "Outbound messaging to operator-defined destinations (webhook + telegram + agentmail adapters)",
+    type: "notify",
+    defaultName: "notify",
+    defaultOptions: {
+      destinations: [{ name: "creator", transport: "webhook", url: "${ORG_NOTIFY_URL}" }],
+      rateLimit: {
+        cooldownMs: 120_000,
+        globalMaxPerHour: 5,
+        dedupWindowMs: 300_000,
+        dedupThreshold: 0.6,
+        perPeerCooldownMs: 30_000,
+      },
+    },
+    required: false,
+    envVars: ["ORG_NOTIFY_URL"],
+    hasSkill: true,
+  },
+  {
+    label: "telegramTransport",
+    description: "Bidirectional Telegram I/O — long-poll OR webhook inbound, four-path identity",
+    type: "telegramTransport",
+    defaultName: "telegram",
+    defaultOptions: {
+      botToken: "${TELEGRAM_BOT_TOKEN}",
+      inbound: {
+        mode: "polling",
+        polling: { timeoutSec: 30 },
+        // To switch to webhook mode, replace the polling block with:
+        // mode: "webhook"
+        // webhook: { publicUrl: "${TELEGRAM_WEBHOOK_URL}", port: 8081, secretToken: "${TELEGRAM_WEBHOOK_SECRET}" }
+      },
+      auth: {
+        creatorUserIds: [],
+        anonymousIdentityMode: "ephemeral",
+      },
+    },
+    required: false,
+    envVars: ["TELEGRAM_BOT_TOKEN"],
+    hasSkill: false,
+  },
+  {
+    label: "Turn Control",
+    description:
+      "Lets the agent pause and request input from the user. Recommended for chat-shaped agents (web/telegram).",
+    type: "turnControl",
+    defaultName: "turn-control",
+    defaultOptions: {},
+    required: false,
+    hasSkill: true,
+  },
+  {
+    label: "link",
+    description:
+      "Peer-to-peer A2A v0.2 transport (auggy ↔ auggy / A2A-speaking peers) via @auggy/link",
+    type: "link",
+    defaultName: "link",
+    defaultOptions: {
+      port: 8081,
+      dbPath: "./link.db",
+      agentCard: {
+        id: "${AUGGY_AGENT_ID}",
+        name: "${AUGGY_AGENT_NAME}",
+        description: "augment-1 link endpoint",
+        endpointUrl: "${AUGGY_LINK_PUBLIC_URL}",
+      },
+      peers: {},
+    },
+    required: false,
+    envVars: ["AUGGY_AGENT_ID", "AUGGY_AGENT_NAME", "AUGGY_LINK_PUBLIC_URL"],
+    hasSkill: false,
+  },
+  {
+    label: "Visitor Auth",
+    description:
+      "Email magic-link verification — promotes anonymous visitors to recognized identity",
+    type: "visitorAuth",
+    defaultName: "visitor-auth",
+    defaultOptions: {
+      publicUrl: "${AUGGY_PUBLIC_URL}",
+      dbPath: "./visitor-auth.db",
+      agentMail: {
+        apiKey: "${AGENTMAIL_API_KEY}",
+        inboxId: "${AGENTMAIL_INBOX_ID}",
+        subjectPrefix: "[Verify] ",
+      },
+      signingKey: "${VISITOR_SIGNING_KEY}",
+      agentBinding: "${AUGGY_AGENT_ID}",
+      rateLimit: { perHour: 1, perDay: 3 },
+      reverifyAfterDays: 90,
+      tokenTtlMinutes: 15,
+      layeredMemoryDbPath: "./memory.db",
+    },
+    required: false,
+    envVars: [
+      "AGENTMAIL_API_KEY",
+      "AGENTMAIL_INBOX_ID",
+      "AUGGY_PUBLIC_URL",
+      "VISITOR_SIGNING_KEY",
+      "AUGGY_AGENT_ID",
+    ],
+    hasSkill: true,
+  },
+];
+
+/** Get catalog entries that are not yet installed (by type + defaultName). */
+export function getAvailableAugments(
+  installed: Array<{ type: string; name: string }>,
+): CatalogEntry[] {
+  return AUGMENT_CATALOG.filter(
+    (entry) => !installed.some((i) => i.type === entry.type && i.name === entry.defaultName),
+  );
+}