auggy 0.3.0

package/src/cli/engine-resolver.ts

@@ -0,0 +1,68 @@
+/**
+ * Engine resolver — EngineConfig → ModelClient.
+ *
+ * Maps the `engine.provider` string from agent.yaml to the corresponding
+ * engine factory. Supports "anthropic", "openai", and "openrouter".
+ *
+ * API keys are NEVER in the YAML config — each engine reads its own
+ * environment variable:
+ *   - anthropic   → ANTHROPIC_API_KEY (read by the Anthropic SDK)
+ *   - openai      → OPENAI_API_KEY    (read by the openai SDK)
+ *   - openrouter  → OPENROUTER_API_KEY (read by createOpenRouterEngine,
+ *     which throws explicitly if absent rather than letting the SDK fall
+ *     through to OPENAI_API_KEY)
+ */
+
+import { createAnthropicEngine } from "../engines/anthropic";
+import { createOpenAIEngine } from "../engines/openai";
+import { createOpenRouterEngine } from "../engines/openrouter";
+import type { ModelClient } from "../types";
+import type { EngineConfig } from "./types";
+
+export function resolveEngine(config: EngineConfig): ModelClient {
+  // Defensive: programmatic callers may bypass the YAML parser. Catch
+  // missing/empty provider with a clearer message than the catch-all throw.
+  if (typeof config.provider !== "string" || config.provider.length === 0) {
+    throw new Error(`engine.provider is required (got: ${JSON.stringify(config.provider)})`);
+  }
+
+  if (config.provider === "anthropic") {
+    return createAnthropicEngine({
+      model: config.model,
+      maxContextTokens: config.maxContextTokens,
+      maxTokens: config.maxTokens,
+      baseURL: config.baseURL,
+      costOverride: config.costOverride,
+      // apiKey intentionally omitted — SDK reads ANTHROPIC_API_KEY from env.
+    });
+  }
+
+  if (config.provider === "openai") {
+    return createOpenAIEngine({
+      model: config.model,
+      maxContextTokens: config.maxContextTokens,
+      maxTokens: config.maxTokens,
+      baseURL: config.baseURL,
+      reasoningEffort: config.reasoningEffort,
+      costOverride: config.costOverride,
+      // apiKey intentionally omitted — SDK reads OPENAI_API_KEY from env.
+    });
+  }
+
+  if (config.provider === "openrouter") {
+    return createOpenRouterEngine({
+      model: config.model,
+      maxContextTokens: config.maxContextTokens,
+      maxTokens: config.maxTokens,
+      reasoningEffort: config.reasoningEffort,
+      providerRouting: config.providerRouting,
+      costOverride: config.costOverride,
+      // baseURL intentionally NOT passed — hardcoded to OpenRouter.
+      // apiKey intentionally omitted — engine reads OPENROUTER_API_KEY from env.
+    });
+  }
+
+  throw new Error(
+    `Unknown engine provider: "${config.provider}" (supported: anthropic, openai, openrouter)`,
+  );
+}

package/src/cli/index.ts

@@ -0,0 +1,178 @@
+#!/usr/bin/env bun
+/**
+ * auggy — CLI for the Auggy agent runtime.
+ *
+ * Commands:
+ *   auggy create <name>              Scaffold a new agent (interactive)
+ *   auggy add <name>                 Add augments to an existing agent
+ *   auggy add-skill <augment>        Install a bundled skill into an agent
+ *   auggy dev <name> [--config]      Run agent in foreground
+ *   auggy start <name> [--config]    Install as launchd service (always-on)
+ *   auggy stop <name>                Stop a running agent
+ *   auggy restart <name>             Stop + start
+ *   auggy status [name]              Show running agents
+ *   auggy ls                         List registered agents
+ *   auggy remove <name> [--yes]      Delete an agent (dir + index entry)
+ *   auggy chat                       Launch local GUI
+ *   auggy eval [name]                Run portable security eval suite
+ */
+
+import { Command } from "commander";
+import { runCreate } from "./commands/create";
+import { runAdd } from "./commands/add";
+import { addSkillCommand } from "./commands/add-skill";
+import { runDev } from "./commands/dev";
+import { runStart } from "./commands/start";
+import { runStop } from "./commands/stop";
+import { runRestart } from "./commands/restart";
+import { runStatus } from "./commands/status";
+import { chatCommand } from "./commands/chat";
+import { evalCommand } from "./commands/eval";
+import { runRemove } from "./commands/remove";
+import { runLs } from "./commands/ls";
+
+const program = new Command();
+
+program.name("auggy").description("Auggy agent runtime CLI").version("0.1.0");
+
+program
+  .command("create <name>")
+  .description("Scaffold a new agent directory (interactive)")
+  .option("--dir <path>", "target directory (defaults to ./<name>)")
+  .action(async (name: string, opts: { dir?: string }) => {
+    try {
+      await runCreate(name, opts);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("add <name>")
+  .description("Add augments to an existing agent")
+  .option("--config <path>", "path to agent.yaml")
+  .action(async (name: string, opts: { config?: string }) => {
+    try {
+      await runAdd(name, opts);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program.addCommand(addSkillCommand());
+
+program
+  .command("dev <name>")
+  .description("Run an agent in the foreground (Ctrl-C to stop)")
+  .option("--config <path>", "path to agent.yaml")
+  .option("--internal-mode <mode>", "(internal) process mode for PID manifest")
+  .action(async (name: string, opts: { config?: string; internalMode?: string }) => {
+    try {
+      await runDev(name, opts);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("start <name>")
+  .description("Install agent as a launchd service (always-on)")
+  .option("--config <path>", "path to agent.yaml")
+  .action(async (name: string, opts: { config?: string }) => {
+    try {
+      await runStart(name, opts);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("stop <name>")
+  .description("Stop a running agent")
+  .action(async (name: string) => {
+    try {
+      await runStop(name);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("restart <name>")
+  .description("Stop and restart a running agent")
+  .option("--config <path>", "path to agent.yaml")
+  .action(async (name: string, opts: { config?: string }) => {
+    try {
+      await runRestart(name, opts);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("status [name]")
+  .description("Show running agents or detail a specific one")
+  .action(async (name?: string) => {
+    try {
+      await runStatus(name);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("remove <name>")
+  .description("Remove an agent (delete dir + clear index entry)")
+  .option("--yes", "skip the confirmation prompt")
+  .action(async (name: string, opts: { yes?: boolean }) => {
+    try {
+      await runRemove(name, { yes: opts.yes });
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("ls")
+  .description("List registered agents with their status")
+  .action(async () => {
+    try {
+      await runLs();
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command("visitors <agent>")
+  .description("list verified visitors for an agent")
+  .option("--revoke <email>", "revoke a verified visitor by email")
+  .option("--yes", "skip the confirmation prompt for --revoke")
+  .action(async (agentName: string, options: { revoke?: string; yes?: boolean }) => {
+    try {
+      if (options.revoke) {
+        const { runVisitorsRevoke } = await import("./commands/visitors-revoke");
+        await runVisitorsRevoke(agentName, options.revoke, { confirm: options.yes !== true });
+        return;
+      }
+      const { runVisitorsList } = await import("./commands/visitors");
+      await runVisitorsList(agentName);
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program.addCommand(chatCommand());
+program.addCommand(evalCommand());
+
+program.parse();

package/src/cli/model-picker.ts

@@ -0,0 +1,89 @@
+/**
+ * Model picker — derives `auggy create` model choices from per-provider
+ * pricing tables. Single source of truth for "models we can cost-track."
+ *
+ * The Custom escape hatch is handled in `commands/create.ts`, not here —
+ * this module only enumerates priced choices.
+ */
+
+import * as anthropicPricing from "../engines/anthropic/pricing";
+import * as openaiPricing from "../engines/openai/pricing";
+
+export type Provider = "anthropic" | "openai" | "openrouter";
+
+export interface ModelChoice {
+  /** Model ID as it appears in agent.yaml `engine.model`. */
+  id: string;
+  inputUsdPerMtok: number;
+  outputUsdPerMtok: number;
+}
+
+interface PricingTableEntry {
+  inputUsdPerMtok: number;
+  outputUsdPerMtok: number;
+}
+
+/**
+ * Read raw pricing tables. We import each provider's pricing module and
+ * call `listModels()` + `lookup()` to enumerate priced choices without
+ * coupling to the internal table shape.
+ */
+function readEntry(provider: Provider, id: string): PricingTableEntry | null {
+  if (provider === "anthropic") return anthropicPricing.lookup(id);
+  if (provider === "openai") return openaiPricing.lookup(id);
+  return null;
+}
+
+/**
+ * Get the priced model choices for a provider, ordered cheapest-first.
+ */
+export function getModelChoices(provider: Provider): ModelChoice[] {
+  let pairs: Array<{ id: string; entry: PricingTableEntry }> = [];
+
+  if (provider === "anthropic") {
+    const ids = anthropicPricing.listModels();
+    pairs = ids
+      .map((id) => ({ id, entry: readEntry(provider, id) }))
+      .filter((p): p is { id: string; entry: PricingTableEntry } => p.entry !== null);
+  } else if (provider === "openai") {
+    const ids = openaiPricing.listModels();
+    pairs = ids
+      .map((id) => ({ id, entry: readEntry(provider, id) }))
+      .filter((p): p is { id: string; entry: PricingTableEntry } => p.entry !== null);
+  } else if (provider === "openrouter") {
+    const anthropicSlugs = anthropicPricing.listModels().map((id) => ({
+      id: `anthropic/${id}`,
+      entry: readEntry("anthropic", id),
+    }));
+    const openaiSlugs = openaiPricing.listModels().map((id) => ({
+      id: `openai/${id}`,
+      entry: readEntry("openai", id),
+    }));
+    pairs = [...anthropicSlugs, ...openaiSlugs].filter(
+      (p): p is { id: string; entry: PricingTableEntry } => p.entry !== null,
+    );
+  }
+
+  return pairs
+    .map((p) => ({
+      id: p.id,
+      inputUsdPerMtok: p.entry.inputUsdPerMtok,
+      outputUsdPerMtok: p.entry.outputUsdPerMtok,
+    }))
+    .sort((a, b) => a.inputUsdPerMtok - b.inputUsdPerMtok);
+}
+
+/**
+ * Format a choice as: `<id> — $<input>/$<output> per Mtok`.
+ *
+ * Sub-dollar rates render with two decimals ($0.80, not $0.8); whole-dollar
+ * rates render without decimals ($3, not $3.00).
+ */
+export function formatChoiceLabel(choice: ModelChoice): string {
+  const fmt = (n: number): string => {
+    if (Number.isInteger(n)) return `$${n}`;
+    if (n < 1) return `$${n.toFixed(2)}`;
+    return `$${n}`;
+  };
+  return `${choice.id} — ${fmt(choice.inputUsdPerMtok)}/${fmt(choice.outputUsdPerMtok)} per Mtok`;
+}

package/src/cli/pid-registry.ts

@@ -0,0 +1,146 @@
+/**
+ * PID registry — tracks running Auggy agents via JSON manifests.
+ *
+ * Each running agent gets a manifest at ~/.auggy/<name>.json containing
+ * pid, port, config path, start time, and mode. Atomic writes via the
+ * "wx" flag prevent concurrent starts of the same agent name.
+ *
+ * Replicates the PID guard pattern from telemetry-exporter/bin/daemon.ts.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { PidManifest } from "./types";
+
+const AUGGY_DIR = join(homedir(), ".auggy");
+// No time-based staleness heuristic — always-on agents can run for weeks.
+// Liveness is determined solely by whether the PID is alive.
+
+function ensureDir(): void {
+  mkdirSync(AUGGY_DIR, { recursive: true });
+}
+
+function manifestPath(name: string): string {
+  return join(AUGGY_DIR, `${name}.json`);
+}
+
+// ---------------------------------------------------------------------------
+// Process liveness check
+// ---------------------------------------------------------------------------
+
+/** Check if a process with the given PID is alive. */
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CRUD operations
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a PID manifest atomically. Throws EEXIST if the manifest
+ * already exists (another instance is running or stale).
+ *
+ * Call `cleanupStaleManifest` first if you want to recover from a
+ * stale PID file before writing.
+ */
+export function writePidManifest(manifest: PidManifest): void {
+  ensureDir();
+  const path = manifestPath(manifest.name);
+  writeFileSync(path, JSON.stringify(manifest, null, 2), { flag: "wx" });
+}
+
+/** Read a PID manifest. Returns null if not found. */
+export function readPidManifest(name: string): PidManifest | null {
+  const path = manifestPath(name);
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as PidManifest;
+  } catch {
+    return null;
+  }
+}
+
+/** Remove a PID manifest (called on clean shutdown). */
+export function removePidManifest(name: string): void {
+  const path = manifestPath(name);
+  try {
+    unlinkSync(path);
+  } catch {
+    // Already gone — fine.
+  }
+}
+
+/**
+ * List all PID manifests. Dead processes are cleaned up automatically.
+ * Returns only manifests whose processes are still alive.
+ */
+export function listPidManifests(): PidManifest[] {
+  ensureDir();
+  const manifests: PidManifest[] = [];
+
+  for (const file of readdirSync(AUGGY_DIR)) {
+    if (!file.endsWith(".json")) continue;
+    const path = join(AUGGY_DIR, file);
+    try {
+      const manifest = JSON.parse(readFileSync(path, "utf-8")) as PidManifest;
+      if (isProcessAlive(manifest.pid)) {
+        manifests.push(manifest);
+      } else {
+        // Dead process — clean up the stale manifest.
+        try {
+          unlinkSync(path);
+        } catch {}
+      }
+    } catch {
+      // Corrupt manifest — remove it.
+      try {
+        unlinkSync(path);
+      } catch {}
+    }
+  }
+
+  return manifests;
+}
+
+/**
+ * Try to claim a name for a new agent. If a manifest exists:
+ *  - If the process is dead, remove the stale manifest and return true.
+ *  - If the process is alive but older than 24h, treat it as stuck —
+ *    remove the manifest and return true.
+ *  - If the process is alive and recent, return false (name is taken).
+ */
+export function tryClaimName(name: string): boolean {
+  const manifest = readPidManifest(name);
+  if (!manifest) return true;
+
+  if (!isProcessAlive(manifest.pid)) {
+    removePidManifest(name);
+    return true;
+  }
+
+  // Process is alive — name is taken.
+  return false;
+}
+
+/**
+ * Return the path to the auggy directory (~/.auggy/).
+ * Used by the plist generator for log paths.
+ */
+export function getAuggyDir(): string {
+  ensureDir();
+  return AUGGY_DIR;
+}

package/src/cli/plist-generator.ts

@@ -0,0 +1,117 @@
+/**
+ * launchd plist generator — creates a macOS plist that keeps an
+ * Auggy agent alive via launchd.
+ *
+ * The plist invokes `auggy dev <name>` (the foreground runner) and
+ * lets launchd handle daemonization, restart, and log routing.
+ *
+ * Pattern replicated from telemetry-exporter/com.lo.telemetry-exporter.plist.
+ */
+
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface PlistOptions {
+  /** Agent name (used in label and log file names). */
+  name: string;
+  /** Absolute path to the agent directory. */
+  agentDir: string;
+  /** Absolute path to agent.yaml. */
+  configPath: string;
+  /** Absolute path to the bun binary. */
+  bunPath: string;
+  /** Absolute path to the auggy CLI entrypoint (src/cli/index.ts). */
+  cliEntryPoint: string;
+}
+
+/** The launchd label for an agent. */
+export function plistLabel(name: string): string {
+  return `com.auggy.agent.${name}`;
+}
+
+/** Where generated plists are stored. */
+export function plistStorePath(name: string): string {
+  return join(homedir(), ".auggy", "plists", `${plistLabel(name)}.plist`);
+}
+
+/** Where the symlink goes in ~/Library/LaunchAgents/. */
+export function plistInstallPath(name: string): string {
+  return join(homedir(), "Library", "LaunchAgents", `${plistLabel(name)}.plist`);
+}
+
+/** Log directory for agent stdout/stderr. */
+export function logDir(): string {
+  return join(homedir(), ".auggy", "logs");
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+/**
+ * Generate a launchd plist XML string for an Auggy agent.
+ *
+ * The plist runs `bun run <cliEntryPoint> dev <name> --config <configPath>`
+ * with KeepAlive=true so launchd restarts on crash.
+ */
+export function generatePlist(opts: PlistOptions): string {
+  const label = plistLabel(opts.name);
+  const bunDir = dirname(opts.bunPath);
+  const home = homedir();
+  const logs = logDir();
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(label)}</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${escapeXml(opts.bunPath)}</string>
+    <string>run</string>
+    <string>${escapeXml(opts.cliEntryPoint)}</string>
+    <string>dev</string>
+    <string>${escapeXml(opts.name)}</string>
+    <string>--config</string>
+    <string>${escapeXml(opts.configPath)}</string>
+    <string>--internal-mode</string>
+    <string>launchd</string>
+  </array>
+
+  <key>WorkingDirectory</key>
+  <string>${escapeXml(opts.agentDir)}</string>
+
+  <key>KeepAlive</key>
+  <true/>
+
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+
+  <key>RunAtLoad</key>
+  <true/>
+
+  <key>StandardOutPath</key>
+  <string>${escapeXml(join(logs, `${opts.name}.log`))}</string>
+
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(join(logs, `${opts.name}.err`))}</string>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${escapeXml(bunDir)}:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    <key>HOME</key>
+    <string>${escapeXml(home)}</string>
+  </dict>
+</dict>
+</plist>
+`;
+}

package/src/cli/resolve-config.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared config path resolution for CLI commands.
+ *
+ * Resolution order:
+ *   1. Explicit --config <path> flag
+ *   2. Look up <name> in `~/.auggy/agents.json` (the index)
+ *
+ * The legacy CWD-relative fallback (`./<name>/agent.yaml`, `./agent.yaml`)
+ * was removed in ADR-021. Pre-ADR-021 agents are not auto-discovered;
+ * adoption is deferred until concrete demand.
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getAgent } from "./agent-index";
+
+interface ResolveOptions {
+  /** Override `~/.auggy/` for tests. */
+  auggyDir?: string;
+}
+
+/**
+ * Resolve the config file path from explicit flag or the agent index.
+ */
+export function resolveConfigPath(
+  name: string,
+  configFlag?: string,
+  opts: ResolveOptions = {},
+): string {
+  if (configFlag) {
+    const absPath = resolve(configFlag);
+    if (!existsSync(absPath)) {
+      throw new Error(`Config file not found: ${absPath}`);
+    }
+    return absPath;
+  }
+
+  const entry = getAgent(name, opts);
+  if (!entry) {
+    throw new Error(
+      `Agent "${name}" is not registered.\n\n` +
+        `  Run \`auggy create ${name}\` to scaffold a new agent,\n` +
+        `  or \`auggy ls\` to see registered agents.`,
+    );
+  }
+
+  const cfg = join(entry.localDir, "agent.yaml");
+  if (!existsSync(cfg)) {
+    throw new Error(
+      `agent.yaml missing at indexed path: ${cfg}\n\n` +
+        `  The agent directory may have been deleted or moved manually.\n` +
+        `  Run \`auggy remove ${name}\` to clean up the index entry.`,
+    );
+  }
+  return cfg;
+}