@agentskit/cli 0.11.3 → 0.13.1

package/dist/index.cjs

@@ -14,6 +14,7 @@ var fs = require('fs');
 var tools = require('@agentskit/tools');
 var skills = require('@agentskit/skills');
 var memory = require('@agentskit/memory');
+var integrations = require('@agentskit/integrations');
 var child_process = require('child_process');
 var jsxRuntime = require('react/jsx-runtime');
 var url = require('url');
@@ -24,6 +25,8 @@ var chokidar = require('chokidar');
 var rag = require('@agentskit/rag');
 var agentSchema = require('@agentskit/core/agent-schema');
 var yaml = require('yaml');
+var security = require('@agentskit/core/security');
+var core = require('@agentskit/core');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -152,7 +155,7 @@ function createDemoAdapter(provider, model) {
           ].join(" ");
           for (const chunk of reply.match(/.{1,18}/g) ?? []) {
             if (cancelled) return;
-            await new Promise((resolve4) => setTimeout(resolve4, 35));
+            await new Promise((resolve6) => setTimeout(resolve6, 35));
             yield { type: "text", content: chunk };
           }
           yield { type: "done" };
@@ -607,7 +610,7 @@ function instantiate(kind) {
     case "filesystem":
       return tools.filesystem({ basePath: process.cwd() });
     case "shell":
-      return [tools.shell({ timeout: 3e4 })];
+      return [tools.shell({ timeout: 3e4, allowAny: true })];
   }
 }
 function gateTool(tool) {
@@ -627,9 +630,19 @@ function resolveTools(toolNames) {
       case "shell":
         tools.push(...instantiate(name));
         break;
-      default:
-        process.stderr.write(`Unknown tool: ${name}
+      default: {
+        if (integrations.getIntegration(name)) {
+          const { tools: projected, credentialFound, envVar } = integrations.integrationToolsFromEnv(name, process.env);
+          if (!credentialFound) {
+            process.stderr.write(`Integration "${name}" needs ${envVar} set in the environment.
 `);
+          }
+          tools.push(...projected);
+        } else {
+          process.stderr.write(`Unknown tool: ${name}
+`);
+        }
+      }
     }
   }
   return tools;
@@ -864,20 +877,39 @@ function configHooksToHandlers(config) {
 function runShellHook(entry, payload) {
   return new Promise((resolvePromise) => {
     const timeoutMs = entry.timeout ?? 5e3;
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise(result);
+    };
     const child = child_process.spawn("sh", ["-c", entry.run], {
-      stdio: ["pipe", "pipe", "inherit"]
+      stdio: ["pipe", "pipe", "inherit"],
+      detached: true
     });
     let stdout = "";
     child.stdout.on("data", (chunk) => {
       stdout += chunk.toString();
     });
     const timer = setTimeout(() => {
-      child.kill("SIGTERM");
+      if (child.pid !== void 0) {
+        try {
+          process.kill(-child.pid, "SIGKILL");
+        } catch {
+        }
+      }
+      try {
+        child.kill("SIGKILL");
+      } catch {
+      }
+      settle({ decision: "block", reason: `shell hook timed out after ${timeoutMs}ms` });
     }, timeoutMs);
+    child.stdin.on("error", () => {
+    });
     child.on("close", (code) => {
-      clearTimeout(timer);
       if (code !== 0) {
-        resolvePromise({
+        settle({
           decision: "block",
           reason: `shell hook exited with code ${code}`
         });
@@ -885,19 +917,18 @@ function runShellHook(entry, payload) {
       }
       const trimmed = stdout.trim();
       if (!trimmed) {
-        resolvePromise({ decision: "continue" });
+        settle({ decision: "continue" });
         return;
       }
       try {
         const parsed = JSON.parse(trimmed);
-        resolvePromise(parsed);
+        settle(parsed);
       } catch {
-        resolvePromise({ decision: "continue" });
+        settle({ decision: "continue" });
       }
     });
     child.on("error", (err) => {
-      clearTimeout(timer);
-      resolvePromise({ decision: "block", reason: err.message });
+      settle({ decision: "block", reason: err.message });
     });
     try {
       child.stdin.write(JSON.stringify(payload));
@@ -3687,13 +3718,6 @@ function registerConfigCommand(program) {
 `);
       process.exit(2);
     }
-    if (fs.existsSync(targetPath) && !options.force) {
-      process.stderr.write(
-        `Config already exists at ${targetPath}. Re-run with --force to overwrite.
-`
-      );
-      process.exit(1);
-    }
     const template = {
       defaults: {
         provider: "openai",
@@ -3704,7 +3728,20 @@ function registerConfigCommand(program) {
       }
     };
     fs.mkdirSync(path__default.default.dirname(targetPath), { recursive: true });
-    fs.writeFileSync(targetPath, JSON.stringify(template, null, 2) + "\n");
+    try {
+      fs.writeFileSync(targetPath, JSON.stringify(template, null, 2) + "\n", {
+        flag: options.force ? "w" : "wx"
+      });
+    } catch (err) {
+      if (err.code === "EEXIST") {
+        process.stderr.write(
+          `Config already exists at ${targetPath}. Re-run with --force to overwrite.
+`
+        );
+        process.exit(1);
+      }
+      throw err;
+    }
     process.stdout.write(
       `Wrote ${targetPath}
 Edit it to taste, then run:
@@ -4002,12 +4039,12 @@ function scaffoldAgent(schema) {
   return files;
 }
 async function writeScaffold(files, outDir, opts = {}) {
-  const { writeFile: writeFile2, mkdir: mkdir2, access } = await import('fs/promises');
-  const { dirname, join: join5 } = await import('path');
+  const { writeFile: writeFile5, mkdir: mkdir5, access } = await import('fs/promises');
+  const { dirname: dirname4, join: join8 } = await import('path');
   const written = [];
   for (const f of files) {
-    const full = join5(outDir, f.path);
-    await mkdir2(dirname(full), { recursive: true });
+    const full = join8(outDir, f.path);
+    await mkdir5(dirname4(full), { recursive: true });
     if (!opts.overwrite) {
       try {
         await access(full);
@@ -4015,7 +4052,7 @@ async function writeScaffold(files, outDir, opts = {}) {
       } catch {
       }
     }
-    await writeFile2(full, f.content, "utf8");
+    await writeFile5(full, f.content, "utf8");
     written.push(f.path);
   }
   return written;
@@ -4168,6 +4205,724 @@ function registerFlowCommand(program) {
     }
   });
 }
+function lintTaxonomyFile(filePath) {
+  const absolute = path.resolve(filePath);
+  let raw;
+  try {
+    raw = fs.readFileSync(absolute, "utf8");
+  } catch (err) {
+    return {
+      file: absolute,
+      ruleCount: 0,
+      result: {
+        ok: false,
+        issues: [{ index: -1, path: "", message: `cannot read file: ${err.message}` }]
+      }
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      file: absolute,
+      ruleCount: 0,
+      result: {
+        ok: false,
+        issues: [{ index: -1, path: "", message: `invalid JSON: ${err.message}` }]
+      }
+    };
+  }
+  const result = security.validatePIITaxonomy(parsed);
+  const ruleCount = parsed && typeof parsed === "object" && Array.isArray(parsed.rules) ? parsed.rules.length : 0;
+  return { file: absolute, result, ruleCount };
+}
+function renderLintReport(report, opts = {}) {
+  const { color = false } = opts;
+  const red = (s) => color ? `\x1B[31m${s}\x1B[0m` : s;
+  const green = (s) => color ? `\x1B[32m${s}\x1B[0m` : s;
+  const dim = (s) => color ? `\x1B[2m${s}\x1B[0m` : s;
+  const lines = [];
+  lines.push(dim(report.file));
+  if (report.result.ok) {
+    lines.push(green(`\u2713 valid \xB7 ${report.ruleCount} rule${report.ruleCount === 1 ? "" : "s"}`));
+  } else {
+    lines.push(red(`\u2717 ${report.result.issues.length} issue${report.result.issues.length === 1 ? "" : "s"}`));
+    for (const issue of report.result.issues) {
+      lines.push(`  ${red("\u2022")} ${issue.path || "<root>"}: ${issue.message}`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+
+// src/commands/pii.ts
+function registerPiiCommand(program) {
+  const pii = program.command("pii").description("Inspect and validate PII taxonomies.");
+  pii.command("lint <file...>").description("Validate one or more PII taxonomy JSON files.").option("--json", "Emit JSON instead of formatted output").action((files, options) => {
+    const reports = files.map(lintTaxonomyFile);
+    const failed = reports.filter((r) => !r.result.ok).length;
+    if (options.json) {
+      process.stdout.write(JSON.stringify(reports, null, 2) + "\n");
+    } else {
+      for (const report of reports) {
+        process.stdout.write(renderLintReport(report, { color: process.stdout.isTTY }));
+      }
+      if (failed > 0) {
+        process.stderr.write(`
+${failed} of ${reports.length} taxonomy file${reports.length === 1 ? "" : "s"} failed validation
+`);
+      }
+    }
+    if (failed > 0) process.exit(1);
+  });
+}
+
+// src/rules/cursor.ts
+var CURSOR_RULE = `---
+description: AgentsKit conventions \u2014 apply to every file in this workspace
+globs: ["**/*.ts", "**/*.tsx"]
+alwaysApply: true
+---
+
+# AgentsKit project rules
+
+When writing or editing TypeScript in this workspace, follow these rules. They
+are non-negotiable and enforced by CI.
+
+## Imports
+
+- Use **named exports only**. No \`export default\`.
+- Import from package roots: \`@agentskit/core\`, \`@agentskit/runtime\`, \`@agentskit/react\`,
+  \`@agentskit/ink\`, \`@agentskit/adapters\`, \`@agentskit/tools\`, \`@agentskit/skills\`,
+  \`@agentskit/memory\`, \`@agentskit/rag\`, \`@agentskit/observability\`, \`@agentskit/eval\`,
+  \`@agentskit/sandbox\`, \`@agentskit/cli\`, \`@agentskit/templates\`.
+- For tools subpaths, use \`@agentskit/tools/integrations\`, \`@agentskit/tools/mcp\`,
+  \`@agentskit/tools/mcp-devtools\`.
+
+## Types
+
+- TypeScript strict mode is on. **Do not use \`any\`** \u2014 use \`unknown\` and narrow.
+- Headless React components: no hardcoded styles, use \`data-ak-*\` attributes.
+
+## Errors
+
+- Never \`throw new Error(...)\` inside package source. Use the typed errors from
+  \`@agentskit/core\`: \`AdapterError\`, \`ToolError\`, \`MemoryError\`, \`RuntimeError\`,
+  \`SandboxError\`, \`SkillError\`, \`ConfigError\`. Pair with \`ErrorCodes.<...>\`.
+
+## Tests
+
+- vitest. Place tests under \`packages/<pkg>/tests/\` mirroring \`src/\`.
+- E2E lives in \`apps/example-*\` with Playwright.
+
+## Versioning
+
+- Every PR with a behavior change requires a Changeset (\`pnpm changeset\`).
+
+## Where to look first
+
+- Architecture, contracts, ADRs: \`docs/architecture/adrs/\`
+- Per-package conventions: \`packages/<pkg>/CONVENTIONS.md\`
+- Agent-facing index: \`AGENTS.md\` and \`apps/docs-next/content/docs/for-agents/\`
+`;
+
+// src/rules/windsurf.ts
+var WINDSURF_RULE = `# AgentsKit project rules (read first)
+
+This workspace builds AgentsKit \u2014 a JavaScript agent toolkit with a 10 KB core,
+six formal contracts, and ~19 plug-and-play packages. When generating or
+editing code, follow these rules \u2014 they are enforced by CI.
+
+## Imports
+- **Named exports only.** No \`export default\`.
+- Import from package roots (\`@agentskit/core\`, \`@agentskit/runtime\`, \`@agentskit/react\`, etc.).
+- Tools subpaths: \`@agentskit/tools/integrations\`, \`@agentskit/tools/mcp\`, \`@agentskit/tools/mcp-devtools\`.
+
+## Types
+- Strict mode TypeScript. **No \`any\`** \u2014 use \`unknown\` and narrow.
+
+## Errors
+- **Do not** \`throw new Error(...)\` in package source. Use \`AdapterError\` /
+  \`ToolError\` / \`MemoryError\` / \`RuntimeError\` / \`SandboxError\` / \`SkillError\` /
+  \`ConfigError\` from \`@agentskit/core\`, paired with \`ErrorCodes\`.
+
+## Tests
+- vitest. Tests live in \`packages/<pkg>/tests/\` mirroring \`src/\`.
+- E2E lives in \`apps/example-*\` with Playwright.
+
+## Versioning
+- Every behavior change needs a Changeset (\`pnpm changeset\`).
+
+## Read first
+- \`AGENTS.md\` \u2014 universal agent guidance
+- \`apps/docs-next/content/docs/for-agents/\` \u2014 per-package agent docs
+- \`docs/architecture/adrs/\` \u2014 six core contracts (Adapter, Tool, Memory, Retriever, Skill, Runtime)
+- \`packages/<pkg>/CONVENTIONS.md\` \u2014 per-package contribution rules
+`;
+
+// src/rules/codex.ts
+var CODEX_PROFILE = `<!-- agentskit-codex-profile:start -->
+## Codex / Aider profile
+
+Structured hints for CLI coding agents (OpenAI Codex, Aider, Claude Code,
+Cursor) running against this workspace. Update via \`agentskit rules codex\`.
+
+\`\`\`yaml
+# AgentsKit Codex profile v1
+profile: agentskit
+runtime: node-25
+package_manager: pnpm
+test_runner: vitest
+build_runner: turborepo
+
+allowed_commands:
+  - pnpm install
+  - pnpm build
+  - pnpm test
+  - pnpm lint
+  - pnpm changeset
+  - pnpm --filter @agentskit/* test
+  - pnpm --filter @agentskit/* lint
+  - pnpm --filter @agentskit/* build
+
+restricted_paths:
+  - packages/core/src/errors.ts        # Touch carefully \u2014 every package depends on the typed errors here.
+  - packages/core/src/security/        # Security-sensitive \u2014 small surface, requires review.
+  - docs/architecture/adrs/            # Contract changes need a new ADR + major bump.
+
+models_recommended:
+  - claude-sonnet-4-6                  # Default \u2014 long context, fast.
+  - gpt-5                              # Strong reasoning for refactors / cross-package work.
+  - claude-opus-4-7                    # Heavy refactors, contract redesigns.
+
+invariants:
+  core_max_kb_gzip: 10
+  no_default_exports: true
+  strict_typescript: true
+  no_bare_throw_new_error: true
+  named_exports_only: true
+  changeset_required_for_behavior_changes: true
+
+read_first:
+  - AGENTS.md
+  - apps/docs-next/content/docs/for-agents/
+  - docs/architecture/adrs/
+\`\`\`
+<!-- agentskit-codex-profile:end -->
+`;
+
+// src/rules/claude-code.ts
+var CLAUDE_CODE_SKILL = [
+  {
+    path: "SKILL.md",
+    contents: `---
+name: agentskit
+description: Scaffold AgentsKit projects, add tools/skills, run doctor, and inspect the runtime \u2014 wraps the agentskit CLI.
+---
+
+# AgentsKit
+
+Skill bundle for working with the AgentsKit toolkit from inside Claude Code.
+
+Pair this skill with the project-scoped slash commands at \`.claude/commands/agentskit-*.md\`:
+
+- \`/agentskit-new-agent\` \u2014 interactive scaffold (\`agentskit init\`)
+- \`/agentskit-doctor\` \u2014 diagnose the local environment (\`agentskit doctor\`)
+- \`/agentskit-add-tool\` \u2014 add a tool integration template
+- \`/agentskit-add-skill\` \u2014 add a skill template
+- \`/agentskit-lint-pii\` \u2014 validate a PII taxonomy file
+- \`/agentskit-rules\` \u2014 write \`.cursor/rules\` / \`.windsurfrules\` / Codex profile
+
+When the user is inside an AgentsKit workspace, prefer the slash commands over
+hand-rolling shell invocations \u2014 they share the canonical defaults.
+
+For convention reminders (named exports only, no bare throw, etc.), read
+\`AGENTS.md\` at the workspace root.
+`
+  }
+];
+var CLAUDE_CODE_SLASH_COMMANDS = [
+  {
+    path: "agentskit-new-agent.md",
+    contents: `---
+description: Scaffold a new AgentsKit project (interactive)
+allowed-tools: Bash(npx agentskit init:*)
+---
+
+Run \`npx @agentskit/cli init\` interactively in the user's chosen directory.
+After scaffold completes, summarise the layout (templates created, next
+commands the user should run).
+`
+  },
+  {
+    path: "agentskit-doctor.md",
+    contents: `---
+description: Run the AgentsKit environment doctor and summarise findings
+allowed-tools: Bash(npx agentskit doctor:*)
+---
+
+Run \`npx @agentskit/cli doctor\` in the workspace root. Format the output
+into pass / warn / fail buckets and propose a fix for each fail / warn.
+`
+  },
+  {
+    path: "agentskit-add-tool.md",
+    contents: `---
+description: Add a tool template to the current package
+---
+
+Ask the user which tool to add. Use \`packages/templates/src/blueprints/tool.ts\`
+to scaffold the file under \`packages/<pkg>/src/tools/\`. Update the package's
+\`src/index.ts\` to re-export the new tool. Add a vitest mock test under
+\`packages/<pkg>/tests/\`.
+`
+  },
+  {
+    path: "agentskit-add-skill.md",
+    contents: `---
+description: Add a skill template to @agentskit/skills
+---
+
+Use \`packages/templates/src/blueprints/skill.ts\` to scaffold a new skill
+under \`packages/skills/src/\`. Re-export from the package index. Add a
+golden-dataset test fixture under \`packages/skills/tests/\` (10\u201350 input/
+expected examples, per the conventions).
+`
+  },
+  {
+    path: "agentskit-lint-pii.md",
+    contents: `---
+description: Validate a PII taxonomy JSON file
+allowed-tools: Bash(npx agentskit pii lint:*)
+---
+
+Ask the user for a path. Run \`npx @agentskit/cli pii lint <path>\` and
+display the report. If issues exist, suggest concrete fixes per the
+issue messages.
+`
+  },
+  {
+    path: "agentskit-rules.md",
+    contents: `---
+description: Write editor rule files (Cursor / Windsurf / Codex / Claude Code)
+allowed-tools: Bash(npx agentskit rules:*)
+---
+
+Ask which editor (or "all"). Run the matching:
+- \`npx @agentskit/cli rules cursor\`
+- \`npx @agentskit/cli rules windsurf\`
+- \`npx @agentskit/cli rules codex\`
+- \`npx @agentskit/cli rules claude-code\`
+
+After writing, summarise which files landed and what each one does.
+`
+  }
+];
+
+// src/rules.ts
+var CODEX_BLOCK_START = "<!-- agentskit-codex-profile:start -->";
+var CODEX_BLOCK_END = "<!-- agentskit-codex-profile:end -->";
+async function ensureDir2(path5) {
+  await promises.mkdir(path.dirname(path5), { recursive: true });
+}
+async function writeIfChanged(absPath, contents, force) {
+  let existing;
+  try {
+    existing = await promises.readFile(absPath, "utf8");
+  } catch {
+  }
+  if (existing === contents) return "skipped";
+  if (existing !== void 0 && !force) {
+    return "skipped";
+  }
+  await ensureDir2(absPath);
+  await promises.writeFile(absPath, contents, "utf8");
+  return existing === void 0 ? "wrote" : "updated";
+}
+async function writeCursor(rootDir, force) {
+  const path5 = path.join(rootDir, ".cursor", "rules", "agentskit.mdc");
+  const action = await writeIfChanged(path5, CURSOR_RULE, force);
+  return [{ path: path5, action }];
+}
+async function writeWindsurf(rootDir, force) {
+  const path5 = path.join(rootDir, ".windsurfrules");
+  const action = await writeIfChanged(path5, WINDSURF_RULE, force);
+  return [{ path: path5, action }];
+}
+async function writeCodex(rootDir, force) {
+  const path5 = path.join(rootDir, "AGENTS.md");
+  let existing = "";
+  try {
+    existing = await promises.readFile(path5, "utf8");
+  } catch {
+  }
+  const startIdx = existing.indexOf(CODEX_BLOCK_START);
+  const endIdx = startIdx >= 0 ? existing.lastIndexOf(CODEX_BLOCK_END, existing.length) : -1;
+  if (startIdx >= 0 && endIdx <= startIdx) {
+    throw new core.ConfigError({
+      code: core.ErrorCodes.AK_CONFIG_INVALID,
+      message: `${path5}: found agentskit-codex-profile:start sentinel but no matching :end after it \u2014 refusing to modify a half-edited block.`,
+      hint: "Restore the closing sentinel or remove the partial block, then re-run."
+    });
+  }
+  let next;
+  if (startIdx >= 0 && endIdx > startIdx) {
+    next = existing.slice(0, startIdx) + CODEX_PROFILE.trimEnd() + existing.slice(endIdx + CODEX_BLOCK_END.length);
+  } else if (existing) {
+    next = `${existing.replace(/\s+$/, "")}
+
+${CODEX_PROFILE}`;
+  } else {
+    next = CODEX_PROFILE;
+  }
+  if (next === existing) return [{ path: path5, action: "skipped" }];
+  if (existing && !force) {
+    return [{ path: path5, action: "skipped" }];
+  }
+  await ensureDir2(path5);
+  await promises.writeFile(path5, next, "utf8");
+  return [{ path: path5, action: existing ? "updated" : "wrote" }];
+}
+async function writeClaudeCode(rootDir, force) {
+  const out = [];
+  const skillRoot = path.join(rootDir, ".claude", "skills", "agentskit");
+  for (const file of CLAUDE_CODE_SKILL) {
+    const abs = path.join(skillRoot, file.path);
+    const action = await writeIfChanged(abs, file.contents, force);
+    out.push({ path: abs, action });
+  }
+  const commandsRoot = path.join(rootDir, ".claude", "commands");
+  for (const cmd of CLAUDE_CODE_SLASH_COMMANDS) {
+    const abs = path.join(commandsRoot, cmd.path);
+    const action = await writeIfChanged(abs, cmd.contents, force);
+    out.push({ path: abs, action });
+  }
+  return out;
+}
+async function writeRules(editor, options = {}) {
+  const root = path.resolve(options.rootDir ?? process.cwd());
+  const force = options.force === true;
+  if (editor === "all") {
+    return [
+      { editor: "cursor", files: await writeCursor(root, force) },
+      { editor: "windsurf", files: await writeWindsurf(root, force) },
+      { editor: "codex", files: await writeCodex(root, force) },
+      { editor: "claude-code", files: await writeClaudeCode(root, force) }
+    ];
+  }
+  switch (editor) {
+    case "cursor":
+      return [{ editor, files: await writeCursor(root, force) }];
+    case "windsurf":
+      return [{ editor, files: await writeWindsurf(root, force) }];
+    case "codex":
+      return [{ editor, files: await writeCodex(root, force) }];
+    case "claude-code":
+      return [{ editor, files: await writeClaudeCode(root, force) }];
+  }
+}
+
+// src/commands/rules.ts
+var VALID = ["cursor", "windsurf", "codex", "claude-code", "all"];
+function registerRulesCommand(program) {
+  program.command("rules <editor>").description(
+    "Write editor rule files (cursor | windsurf | codex | claude-code | all). Teaches the editor AgentsKit conventions so generated code respects named-export-only, package boundaries, and the for-agents/* manifest."
+  ).option("--out <dir>", "Workspace root to write files into (default: cwd)").option("-f, --force", "Overwrite existing rule files (codex / claude-code skill always update in place)").action(async (editor, options) => {
+    if (!VALID.includes(editor)) {
+      process.stderr.write(`unknown editor "${editor}". Valid: ${VALID.join(", ")}
+`);
+      process.exit(1);
+    }
+    try {
+      const results = await writeRules(editor, {
+        rootDir: options.out,
+        force: options.force === true
+      });
+      const counts = { wrote: 0, updated: 0, skipped: 0 };
+      for (const { editor: ed, files } of results) {
+        process.stdout.write(`
+[${ed}]
+`);
+        for (const f of files) {
+          counts[f.action]++;
+          process.stdout.write(`  ${f.action.padEnd(7)} ${f.path}
+`);
+        }
+      }
+      process.stdout.write(
+        `
+Done \u2014 ${counts.wrote} wrote, ${counts.updated} updated, ${counts.skipped} skipped.
+`
+      );
+      if (counts.skipped > 0 && options.force !== true) {
+        process.stdout.write(`(re-run with --force to overwrite skipped files)
+`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`
+rules failed: ${message}
+`);
+      process.exit(1);
+    }
+  });
+}
+var RAW_BASE = "https://raw.githubusercontent.com/AgentsKit-io/agentskit-registry/main";
+var HOSTED_BASE = `${RAW_BASE}/public/r`;
+async function getJson(url, fetchImpl) {
+  const res = await fetchImpl(url);
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+  return res.json();
+}
+async function getText(url, fetchImpl) {
+  const res = await fetchImpl(url);
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+  return res.text();
+}
+async function fetchAgent(id, options = {}) {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  try {
+    const hosted = await getJson(`${HOSTED_BASE}/${id}.json`, fetchImpl);
+    if (hosted?.sources?.length) return hosted;
+    throw new Error("hosted entry missing sources");
+  } catch {
+    const meta = await getJson(`${RAW_BASE}/registry/${id}/meta.json`, fetchImpl);
+    const sources = await Promise.all(
+      meta.files.map(async (rel) => ({
+        path: rel,
+        content: await getText(`${RAW_BASE}/registry/${id}/${rel}`, fetchImpl)
+      }))
+    );
+    return { ...meta, sources };
+  }
+}
+function resolveSystemPrompt(agent) {
+  if (agent.skill?.systemPrompt) return agent.skill.systemPrompt;
+  const src = agent.sources.find((f) => f.path === "agent.ts")?.content;
+  if (!src) return null;
+  const m = src.match(/systemPrompt:\s*`((?:\\.|[^`\\])*)`/);
+  return m ? m[1].replace(/\\`/g, "`").replace(/\\\$\{/g, "${") : null;
+}
+async function defaultExists(path5) {
+  const { access } = await import('fs/promises');
+  try {
+    await access(path5);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function addAgent(id, options = {}) {
+  const agent = await fetchAgent(id, options);
+  const baseDir = options.outDir ?? "agents";
+  const targetDir = path.join(baseDir, id);
+  const exists = options.existsImpl ?? defaultExists;
+  const write = options.writeFileImpl ?? (async (path5, content) => {
+    await promises.mkdir(path.dirname(path5), { recursive: true });
+    await promises.writeFile(path5, content, "utf8");
+  });
+  const written = [];
+  for (const file of agent.sources) {
+    const dest = path.join(targetDir, file.path);
+    if (!options.force && await exists(dest)) {
+      throw new Error(`${dest} already exists (re-run with --force to overwrite)`);
+    }
+    await write(dest, file.content);
+    written.push(dest);
+  }
+  return { agent, written, targetDir };
+}
+function lineDiff(a, b) {
+  const x = a.split("\n");
+  const y = b.split("\n");
+  const m = x.length;
+  const n = y.length;
+  const lcs = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i2 = m - 1; i2 >= 0; i2--) {
+    for (let j2 = n - 1; j2 >= 0; j2--) {
+      lcs[i2][j2] = x[i2] === y[j2] ? lcs[i2 + 1][j2 + 1] + 1 : Math.max(lcs[i2 + 1][j2], lcs[i2][j2 + 1]);
+    }
+  }
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < m && j < n) {
+    if (x[i] === y[j]) {
+      out.push({ type: " ", text: x[i] });
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      out.push({ type: "-", text: x[i++] });
+    } else {
+      out.push({ type: "+", text: y[j++] });
+    }
+  }
+  while (i < m) out.push({ type: "-", text: x[i++] });
+  while (j < n) out.push({ type: "+", text: y[j++] });
+  return out;
+}
+async function diffAgent(id, options = {}) {
+  const agent = await fetchAgent(id, options);
+  const targetDir = path.join(options.outDir ?? "agents", id);
+  const readLocal = options.readFileImpl ?? (async (p) => {
+    const { readFile: readFile6 } = await import('fs/promises');
+    try {
+      return await readFile6(p, "utf8");
+    } catch {
+      return null;
+    }
+  });
+  const files = [];
+  for (const f of agent.sources) {
+    const local = await readLocal(path.join(targetDir, f.path));
+    if (local == null) {
+      files.push({ path: f.path, status: "missing-local", upstream: f.content });
+    } else if (local === f.content) {
+      files.push({ path: f.path, status: "unchanged", upstream: f.content });
+    } else {
+      files.push({ path: f.path, status: "modified", diff: lineDiff(local, f.content), upstream: f.content });
+    }
+  }
+  return { agent, targetDir, files };
+}
+
+// src/commands/add.ts
+function registerAddCommand(program) {
+  program.command("add <agent>").description(
+    'Add a ready-made agent from the AgentsKit registry (registry.agentskit.io). Copies the agent source into your project \u2014 you own the code. With --run, also executes it. e.g. `agentskit add research` or `agentskit add legal-contract-reviewer --run "review this NDA\u2026" --provider ollama`.'
+  ).option("--out <dir>", "Directory to write the agent into (default: ./agents)").option("-f, --force", "Overwrite existing files").option("--run <task>", "Run the agent on this task right after adding it").option("--provider <provider>", "Provider for --run (openai, anthropic, gemini, ollama, demo)", "demo").option("--model <model>", "Model for --run").option("--api-key <key>", "API key for --run (else read from the provider env var)").action(
+    async (agent, options) => {
+      try {
+        const result = await addAgent(agent, { outDir: options.out, force: options.force === true });
+        process.stdout.write(`
+Added "${result.agent.title}" \u2192 ${result.targetDir}/
+`);
+        for (const f of result.written) process.stdout.write(`  wrote  ${f}
+`);
+        if (result.agent.packages.length > 0) {
+          process.stdout.write(`
+Install the packages it uses:
+`);
+          process.stdout.write(`  npm install ${result.agent.packages.join(" ")} @agentskit/adapters
+`);
+        }
+        const required = (result.agent.env ?? []).filter((e) => e.required);
+        if (required.length > 0) {
+          process.stdout.write(`
+Required environment:
+`);
+          for (const e of required) process.stdout.write(`  ${e.name} \u2014 ${e.description}
+`);
+        }
+        const readme2 = result.written.find((f) => f.toLowerCase().endsWith("readme.md"));
+        process.stdout.write(readme2 ? `
+See ${readme2} for usage.
+` : "\n");
+        if (options.run) {
+          const systemPrompt = resolveSystemPrompt(result.agent);
+          if (!systemPrompt) {
+            process.stderr.write(
+              `
+--run is not supported for "${agent}" (it composes tools/keys). Use it as a library \u2014 see the README.
+`
+            );
+            process.exit(1);
+          }
+          process.stdout.write(`
+Running "${result.agent.title}" via ${options.provider}\u2026
+
+`);
+          await runAgent(options.run, {
+            provider: options.provider,
+            model: options.model,
+            apiKey: options.apiKey,
+            systemPrompt,
+            maxSteps: "8"
+          });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`
+add failed: ${message}
+`);
+        process.stderr.write(`(browse agents at https://registry.agentskit.io)
+`);
+        process.exit(1);
+      }
+    }
+  );
+}
+function registerDiffCommand(program) {
+  program.command("diff <agent>").description("Show how your local copy of a registry agent differs from the current registry source.").option("--out <dir>", "Directory the agent was added into (default: ./agents)").action(async (agent, options) => {
+    try {
+      const { targetDir, files } = await diffAgent(agent, { outDir: options.out });
+      let changed = 0;
+      for (const f of files) {
+        if (f.status === "unchanged") continue;
+        changed++;
+        process.stdout.write(`
+${f.status === "missing-local" ? "missing" : "modified"}: ${path.join(targetDir, f.path)}
+`);
+        if (f.diff) {
+          for (const line of f.diff) {
+            if (line.type === " ") continue;
+            process.stdout.write(`  ${line.type} ${line.text}
+`);
+          }
+        }
+      }
+      process.stdout.write(
+        changed === 0 ? `
+${agent}: up to date with the registry.
+` : `
+${changed} file(s) differ. Run \`agentskit update ${agent}\` to apply the registry version.
+`
+      );
+    } catch (err) {
+      process.stderr.write(`
+diff failed: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
+function registerUpdateCommand(program) {
+  program.command("update <agent>").description("Update your local copy of a registry agent to the current registry source.").option("--out <dir>", "Directory the agent was added into (default: ./agents)").option("-f, --force", "Apply without listing the changes first").action(async (agent, options) => {
+    try {
+      const { targetDir, files } = await diffAgent(agent, { outDir: options.out });
+      const changed = files.filter((f) => f.status !== "unchanged");
+      if (changed.length === 0) {
+        process.stdout.write(`
+${agent}: already up to date.
+`);
+        return;
+      }
+      if (!options.force) {
+        process.stdout.write(`
+Will overwrite ${changed.length} file(s) with the registry version:
+`);
+        for (const f of changed) process.stdout.write(`  ${f.path} (${f.status})
+`);
+      }
+      for (const f of changed) {
+        const dest = path.join(targetDir, f.path);
+        await promises.mkdir(path.dirname(dest), { recursive: true });
+        await promises.writeFile(dest, f.upstream, "utf8");
+        process.stdout.write(`  updated ${dest}
+`);
+      }
+      process.stdout.write(`
+Updated ${agent}. Review the changes with your VCS before committing.
+`);
+    } catch (err) {
+      process.stderr.write(`
+update failed: ${err instanceof Error ? err.message : String(err)}
+`);
+      process.exit(1);
+    }
+  });
+}
 
 // src/commands/index.ts
 function createCli() {
@@ -4183,6 +4938,11 @@ function createCli() {
   registerRagCommand(program);
   registerAiCommand(program);
   registerFlowCommand(program);
+  registerPiiCommand(program);
+  registerRulesCommand(program);
+  registerAddCommand(program);
+  registerDiffCommand(program);
+  registerUpdateCommand(program);
   return program;
 }