@kairyou/agent-tools 0.1.0 → 0.2.0

package/scripts/install.mjs

@@ -5,11 +5,19 @@
 // Capabilities (all global for now — they target the user-level config):
 //   statusline  Claude Code statusLine script (claude only).
 //   usage       Active API provider quota/balance (codex + opencode).
+//   vision      inspect_image MCP server + at-vision skill (all agents).
+//
+// Standalone commands (dispatched before capability parsing):
+//   inspect-image <path|url> --question "..."   Human diagnostic for vision.
+//   mcp-vision                                  Run the vision MCP stdio server.
 //
 // Targets:
 //   claude   -> ~/.claude/settings.json (statusLine key)
+//               ~/.claude.json (vision MCP) + ~/.claude/skills (at-vision)
 //   codex    -> ~/.codex/hooks.json (standalone hooks file)
-//   opencode -> ~/.config/opencode/ (server + TUI plugins)
+//               ~/.codex/config.toml (vision MCP) + ~/.agents/skills (at-vision)
+//   opencode -> ~/.config/opencode/ (server + TUI plugins,
+//               vision MCP in opencode.json + skills/at-vision)
 // Runtime scripts are copied into ~/.agent-tools so this installer can be
 // run via npx from GitHub without requiring a persistent local clone.
 //
@@ -25,10 +33,15 @@
 //   --settings <path>         Override the Claude settings.json (for testing).
 //   --codex-hooks <path>      Override the Codex hooks.json (for testing).
 //   --opencode-config-dir <p> Override the opencode config dir (for testing).
+//   --claude-json <path>      Override ~/.claude.json for vision MCP (for testing).
+//   --claude-skills-dir <p>   Override ~/.claude/skills (for testing).
+//   --codex-config <path>     Override ~/.codex/config.toml (for testing).
+//   --codex-skills-dir <p>    Override ~/.agents/skills (for testing).
 //   --uninstall               Remove what this installer added, restoring backups.
 //   --dry-run                 Print planned changes without writing anything.
 //   -h, --help                Show this help.
 
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -56,13 +69,21 @@ const RUNTIME = {
   opencodeUsagePlugin: path.join(INSTALL_ROOT, "plugins", "opencode", "usage-plugin.mjs"),
   opencodeUsageTui: path.join(INSTALL_ROOT, "plugins", "opencode", "usage-tui.mjs"),
 };
-const ALL_CAPS = ["statusline", "usage"];
+const ALL_CAPS = ["statusline", "usage", "vision"];
 const ALL_AGENTS = ["claude", "codex", "opencode"];
 const AGENT_CAPS = {
-  claude: ["statusline"],
-  codex: ["usage"],
-  opencode: ["usage"],
+  claude: ["statusline", "vision"],
+  codex: ["usage", "vision"],
+  opencode: ["usage", "vision"],
 };
+const VISION_MCP_NAME = "agent-tools-vision";
+const VISION_SKILL_NAME = "at-vision";
+// The at-vision skill ships inside the vision feature dir (plugins/vision),
+// not skills/: it is unusable without the MCP server, so it must not surface
+// as an independently installable skill.
+const VISION_SKILL_SRC = path.join(REPO_ROOT, "plugins", "vision", "skills", VISION_SKILL_NAME);
+const VISION_BUNDLED_MCP_SERVER = path.join(REPO_ROOT, "dist", "vision", "mcp-server.mjs");
+const VISION_BUNDLED_CLI = path.join(REPO_ROOT, "dist", "vision", "cli.mjs");
 
 function fwd(p) {
   return p.replace(/\\/g, "/");
@@ -247,6 +268,10 @@ function parseArgs(argv) {
     settings: null,
     codexHooks: null,
     opencodeConfigDir: null,
+    claudeJson: null,
+    claudeSkillsDir: null,
+    codexConfig: null,
+    codexSkillsDir: null,
     uninstall: false,
     dryRun: false,
     help: false,
@@ -277,6 +302,10 @@ function parseArgs(argv) {
       case "--settings": opts.settings = argv[++i]; break;
       case "--codex-hooks": opts.codexHooks = argv[++i]; break;
       case "--opencode-config-dir": opts.opencodeConfigDir = argv[++i]; break;
+      case "--claude-json": opts.claudeJson = argv[++i]; break;
+      case "--claude-skills-dir": opts.claudeSkillsDir = argv[++i]; break;
+      case "--codex-config": opts.codexConfig = argv[++i]; break;
+      case "--codex-skills-dir": opts.codexSkillsDir = argv[++i]; break;
       case "--uninstall": opts.uninstall = true; break;
       case "--dry-run": opts.dryRun = true; break;
       case "-h":
@@ -403,9 +432,285 @@ function applyProviderUsage(cfg, { remove }) {
   if (Object.keys(cfg.hooks).length === 0) delete cfg.hooks;
 }
 
+// ---- Vision capability helpers. ----
+
+const VISION_RUNTIME_DIR = path.join(INSTALL_ROOT, "vision-runtime");
+const VISION_RATE_LIMIT_STATE = path.join(INSTALL_ROOT, "cache", "vision-rate-limit.json");
+const VISION_DIST_DIR = path.join(REPO_ROOT, "dist", "vision");
+const VISION_RUNTIME_SERVER = path.join(VISION_RUNTIME_DIR, "mcp-server.mjs");
+const VISION_RUNTIME_CLI = path.join(VISION_RUNTIME_DIR, "cli.mjs");
+const VISION_LEGACY_RUNTIME_SERVER = path.join(
+  VISION_RUNTIME_DIR,
+  "plugins",
+  "vision",
+  "mcp-server.mjs"
+);
+const VISION_SKILL_MARKER = ".agent-tools-managed.json";
+const VISION_SKILL_MARKER_DATA = Object.freeze({
+  owner: "@kairyou/agent-tools",
+  capability: "vision",
+  artifact: "skill",
+});
+// Vision is bundled at release time. Install atomically swaps two self-contained
+// entry files into ~/.agent-tools/vision-runtime, so hosts never run npm and a
+// failed update cannot destroy the previously working runtime.
+function visionMcpCommand() {
+  return { command: "node", args: [fwd(VISION_RUNTIME_SERVER)] };
+}
+
+function sameFilePath(left, right) {
+  function canonical(value) {
+    const resolved = path.resolve(String(value));
+    try {
+      return fs.realpathSync.native(resolved);
+    } catch {
+      return resolved;
+    }
+  }
+  const a = canonical(left);
+  const b = canonical(right);
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+
+function isClaudeVisionMcp(value, mcp = visionMcpCommand()) {
+  return Boolean(
+    value &&
+      value.command === mcp.command &&
+      Array.isArray(value.args) &&
+      value.args.length === 1 &&
+      (sameFilePath(value.args[0], mcp.args[0]) ||
+        sameFilePath(value.args[0], VISION_LEGACY_RUNTIME_SERVER))
+  );
+}
+
+function isOpenCodeVisionMcp(value, mcp = visionMcpCommand()) {
+  return Boolean(
+    value &&
+      value.type === "local" &&
+      Array.isArray(value.command) &&
+      value.command.length === 2 &&
+      value.command[0] === mcp.command &&
+      (sameFilePath(value.command[1], mcp.args[0]) ||
+        sameFilePath(value.command[1], VISION_LEGACY_RUNTIME_SERVER))
+  );
+}
+
+function installVisionRuntime(opts) {
+  if (opts.uninstall) return;
+  console.log(`vision runtime: ${VISION_RUNTIME_DIR}`);
+  if (opts.dryRun) {
+    console.log(`  [dry-run] would atomically install ${VISION_DIST_DIR} -> ${VISION_RUNTIME_DIR}`);
+    return;
+  }
+  for (const name of ["mcp-server.mjs", "cli.mjs"]) {
+    if (!fs.existsSync(path.join(VISION_DIST_DIR, name))) {
+      throw new Error(`Missing bundled vision runtime ${path.join(VISION_DIST_DIR, name)}. Run npm run build:vision.`);
+    }
+  }
+
+  fs.mkdirSync(path.dirname(VISION_RUNTIME_DIR), { recursive: true });
+  const suffix = `${process.pid}-${Date.now()}`;
+  const stage = `${VISION_RUNTIME_DIR}.stage-${suffix}`;
+  const backup = `${VISION_RUNTIME_DIR}.backup-${suffix}`;
+  let movedCurrent = false;
+  try {
+    fs.cpSync(VISION_DIST_DIR, stage, { recursive: true });
+    writeText(
+      path.join(stage, "runtime.json"),
+      JSON.stringify({ owner: "@kairyou/agent-tools", capability: "vision", version: 1 }, null, 2) + "\n",
+      false
+    );
+    for (const name of ["mcp-server.mjs", "cli.mjs"]) {
+      const check = spawnSync(process.execPath, ["--check", path.join(stage, name)], {
+        encoding: "utf8",
+      });
+      if (check.status !== 0) {
+        throw new Error(`Bundled vision runtime failed syntax validation (${name}): ${check.stderr || check.stdout}`);
+      }
+    }
+
+    if (fs.existsSync(VISION_RUNTIME_DIR)) {
+      fs.renameSync(VISION_RUNTIME_DIR, backup);
+      movedCurrent = true;
+    }
+    if (process.env.AGENT_TOOLS_VISION_TEST_FAIL_SWAP === "1") {
+      throw new Error("Simulated vision runtime swap failure");
+    }
+    fs.renameSync(stage, VISION_RUNTIME_DIR);
+    fs.rmSync(backup, { recursive: true, force: true });
+    console.log("  installed bundled vision runtime");
+  } catch (error) {
+    fs.rmSync(stage, { recursive: true, force: true });
+    if (movedCurrent && !fs.existsSync(VISION_RUNTIME_DIR) && fs.existsSync(backup)) {
+      fs.renameSync(backup, VISION_RUNTIME_DIR);
+    }
+    throw error;
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+    if (fs.existsSync(VISION_RUNTIME_DIR)) fs.rmSync(backup, { recursive: true, force: true });
+  }
+}
+
+function isManagedVisionSkillDir(dest) {
+  const marker = path.join(dest, VISION_SKILL_MARKER);
+  if (!fs.existsSync(marker)) return false;
+  try {
+    const value = JSON.parse(fs.readFileSync(marker, "utf8"));
+    return Object.entries(VISION_SKILL_MARKER_DATA).every(([key, expected]) => value?.[key] === expected);
+  } catch {
+    return false;
+  }
+}
+
+function isLegacyManagedVisionSkillDir(dest) {
+  try {
+    const entries = fs.readdirSync(dest);
+    if (entries.length !== 1 || entries[0] !== "SKILL.md") return false;
+    const skill = fs.readFileSync(path.join(dest, "SKILL.md"), "utf8");
+    return (
+      /^---\s*[\s\S]*?^name:\s*at-vision\s*$/m.test(skill) &&
+      skill.includes("# Visual Reasoning Policy") &&
+      skill.includes("`inspect_image` MCP tool (server `agent-tools-vision`)")
+    );
+  } catch {
+    return false;
+  }
+}
+
+function installSkillDir(skillsRoot, { remove, dryRun }) {
+  const dest = path.join(skillsRoot, VISION_SKILL_NAME);
+  if (remove) {
+    if (!fs.existsSync(dest)) return;
+    if (!isManagedVisionSkillDir(dest)) {
+      console.log(`  kept unmanaged ${dest}`);
+      return;
+    }
+    if (dryRun) {
+      console.log(`  [dry-run] would remove ${dest}`);
+      return;
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+    console.log(`  removed ${dest}`);
+    return;
+  }
+  if (fs.existsSync(dest) && !isManagedVisionSkillDir(dest)) {
+    if (isLegacyManagedVisionSkillDir(dest)) {
+      console.log(`  adopting legacy managed skill ${dest}`);
+    } else {
+      console.error(
+        `  Refusing to overwrite existing unowned skill directory ${dest}. ` +
+          `Move or remove it, then re-run the install.`
+      );
+      process.exit(1);
+    }
+  }
+  if (dryRun) {
+    console.log(`  [dry-run] would copy ${VISION_SKILL_SRC} -> ${dest}`);
+    return;
+  }
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.cpSync(VISION_SKILL_SRC, dest, { recursive: true });
+  const skillFile = path.join(dest, "SKILL.md");
+  const skill = fs.readFileSync(skillFile, "utf8");
+  const token = "{{VISION_CLI_PATH}}";
+  if (!skill.includes(token)) {
+    fs.rmSync(dest, { recursive: true, force: true });
+    throw new Error(`Vision skill template is missing ${token}`);
+  }
+  fs.writeFileSync(skillFile, skill.replaceAll(token, fwd(VISION_RUNTIME_CLI)));
+  fs.writeFileSync(
+    path.join(dest, VISION_SKILL_MARKER),
+    JSON.stringify(VISION_SKILL_MARKER_DATA, null, 2) + "\n"
+  );
+  console.log(`  wrote ${dest}`);
+}
+
+const CODEX_VISION_BEGIN = "# >>> agent-tools vision >>>";
+const CODEX_VISION_END = "# <<< agent-tools vision <<<";
+
+// Codex config.toml is user-owned free-form TOML; we manage exactly one
+// marker-delimited block so install/update/uninstall never touch other keys.
+function updateCodexVisionBlock(file, { remove, dryRun, mcp }) {
+  const current = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const blockRe = new RegExp(
+    `\\r?\\n?${escape(CODEX_VISION_BEGIN)}[\\s\\S]*?${escape(CODEX_VISION_END)}\\r?\\n?`
+  );
+  let next = current.replace(blockRe, "\n").replace(/^\n+/, "");
+  if (!remove) {
+    // A same-named table outside our marker block would make the appended
+    // TOML a duplicate declaration and break the ENTIRE config.toml parse.
+    const manualRe = new RegExp(`^\\s*\\[mcp_servers\\.["']?${escape(VISION_MCP_NAME)}["']?\\]`, "m");
+    if (manualRe.test(next)) {
+      console.error(
+        `  Found an existing [mcp_servers.${VISION_MCP_NAME}] entry in ${file} that was not ` +
+          "written by this installer. Remove or rename that entry, then re-run the install."
+      );
+      process.exit(1);
+    }
+    const args = mcp.args.map((a) => JSON.stringify(a)).join(", ");
+    const block = [
+      CODEX_VISION_BEGIN,
+      `[mcp_servers.${VISION_MCP_NAME}]`,
+      `command = ${JSON.stringify(mcp.command)}`,
+      `args = [${args}]`,
+      CODEX_VISION_END,
+      "",
+    ].join("\n");
+    next = next.trim() === "" ? block : next.replace(/\s*$/, "\n\n") + block;
+  }
+  if (next === current) {
+    console.log(`  kept existing ${file}`);
+    return;
+  }
+  if (remove && next.trim() === "" && fs.existsSync(file) && current.trim() !== "") {
+    // The file only ever contained our block; leave an empty file rather than
+    // deleting config.toml, which Codex may expect to exist.
+    writeText(file, "", dryRun);
+    return;
+  }
+  writeText(file, next, dryRun);
+}
+
 // ---- Claude: statusLine backed up in _agentTools. ----
 
+function runClaudeVision(opts) {
+  const claudeJson = opts.claudeJson || path.join(os.homedir(), ".claude.json");
+  const skillsDir = opts.claudeSkillsDir || path.join(os.homedir(), ".claude", "skills");
+  console.log(`claude vision: ${claudeJson}`);
+  const cfg = readJson(claudeJson);
+  const mcp = visionMcpCommand();
+  const existing = cfg.mcpServers?.[VISION_MCP_NAME];
+  if (opts.uninstall) {
+    if (isClaudeVisionMcp(existing, mcp)) {
+      delete cfg.mcpServers[VISION_MCP_NAME];
+      if (Object.keys(cfg.mcpServers).length === 0) delete cfg.mcpServers;
+      writeJson(claudeJson, cfg, opts.dryRun);
+    } else if (existing) {
+      console.log(`  kept unmanaged ${VISION_MCP_NAME} entry in ${claudeJson}`);
+    } else {
+      console.log(`  no ${VISION_MCP_NAME} MCP entry found; nothing to remove.`);
+    }
+    installSkillDir(skillsDir, { remove: true, dryRun: opts.dryRun });
+    console.log("  - vision");
+    return;
+  }
+  if (existing && !isClaudeVisionMcp(existing, mcp)) {
+    throw new Error(
+      `Found an existing unmanaged ${VISION_MCP_NAME} entry in ${claudeJson}. ` +
+        "Remove or rename it, then re-run the install."
+    );
+  }
+  cfg.mcpServers = cfg.mcpServers || {};
+  cfg.mcpServers[VISION_MCP_NAME] = { type: "stdio", command: mcp.command, args: mcp.args };
+  writeJson(claudeJson, cfg, opts.dryRun);
+  installSkillDir(skillsDir, { remove: false, dryRun: opts.dryRun });
+  console.log("  + vision (inspect_image MCP + at-vision skill)");
+}
+
 function runClaude(opts) {
+  if (wants(opts, "vision")) runClaudeVision(opts);
+  if (!wants(opts, "statusline")) return;
   const settings = opts.settings || path.join(os.homedir(), ".claude", "settings.json");
   console.log(`claude (global): ${settings}`);
   const cfg = readJson(settings);
@@ -444,9 +749,22 @@ function runClaude(opts) {
 // written (Codex validates hooks.json against a schema); our hook is found by
 // command signature instead. ----
 
+function runCodexVision(opts) {
+  const file = opts.codexConfig || path.join(os.homedir(), ".codex", "config.toml");
+  const skillsDir = opts.codexSkillsDir || path.join(os.homedir(), ".agents", "skills");
+  console.log(`codex vision: ${file}`);
+  updateCodexVisionBlock(file, {
+    remove: opts.uninstall,
+    dryRun: opts.dryRun,
+    mcp: visionMcpCommand(),
+  });
+  installSkillDir(skillsDir, { remove: opts.uninstall, dryRun: opts.dryRun });
+  console.log(opts.uninstall ? "  - vision" : "  + vision (inspect_image MCP + at-vision skill)");
+}
+
 function runCodex(opts) {
+  if (wants(opts, "vision")) runCodexVision(opts);
   if (!wants(opts, "usage")) {
-    console.log("codex: nothing to do (supports: usage).");
     return;
   }
   const file = opts.codexHooks || path.join(os.homedir(), ".codex", "hooks.json");
@@ -491,9 +809,58 @@ function opencodeConfigDir(opts) {
   );
 }
 
+// opencode.json may be JSONC with user comments — edit only our key in place.
+function updateOpencodeVisionMcp(file, { remove, dryRun, mcp }) {
+  const exists = fs.existsSync(file);
+  const currentText = exists ? fs.readFileSync(file, "utf8") : "{}\n";
+  const errors = [];
+  const current = parseJsonc(currentText, errors, { allowTrailingComma: true }) || {};
+  if (errors.length > 0 || typeof current !== "object" || Array.isArray(current)) {
+    throw new Error(`Cannot parse ${file} as JSONC`);
+  }
+  const existing = current.mcp && current.mcp[VISION_MCP_NAME];
+  if (existing && !isOpenCodeVisionMcp(existing, mcp)) {
+    if (remove) {
+      console.log(`  kept unmanaged ${VISION_MCP_NAME} entry in ${file}`);
+      return;
+    }
+    throw new Error(
+      `Found an existing unmanaged ${VISION_MCP_NAME} entry in ${file}. ` +
+        "Remove or rename it, then re-run the install."
+    );
+  }
+  const desired = remove
+    ? undefined
+    : { type: "local", command: [mcp.command, ...mcp.args], enabled: true };
+  if (JSON.stringify(existing) === JSON.stringify(desired)) {
+    console.log(`  kept existing ${file}`);
+    return;
+  }
+  const eol = currentText.includes("\r\n") ? "\r\n" : "\n";
+  const edits = modify(currentText, ["mcp", VISION_MCP_NAME], desired, {
+    formattingOptions: { insertSpaces: true, tabSize: 2, eol },
+  });
+  const updated = applyEdits(currentText, edits).replace(/\s*$/, "") + eol;
+  writeText(file, updated, dryRun);
+}
+
+function runOpencodeVision(opts) {
+  const configDir = opencodeConfigDir(opts);
+  const file = path.join(configDir, "opencode.json");
+  const skillsDir = path.join(configDir, "skills");
+  console.log(`opencode vision: ${file}`);
+  updateOpencodeVisionMcp(file, {
+    remove: opts.uninstall,
+    dryRun: opts.dryRun,
+    mcp: visionMcpCommand(),
+  });
+  installSkillDir(skillsDir, { remove: opts.uninstall, dryRun: opts.dryRun });
+  console.log(opts.uninstall ? "  - vision" : "  + vision (inspect_image MCP + at-vision skill)");
+}
+
 function runOpencode(opts) {
+  if (wants(opts, "vision")) runOpencodeVision(opts);
   if (!wants(opts, "usage")) {
-    console.log("opencode: nothing to do (supports: usage).");
     return;
   }
 
@@ -520,6 +887,73 @@ function runOpencode(opts) {
   if (!opts.dryRun) console.log("  NOTE: restart opencode to load the agent-tools usage plugin.");
 }
 
+function visionRuntimeHasRemainingReference(opts) {
+  const removed = new Set(opts.agents);
+  if (!removed.has("claude")) {
+    const file = opts.claudeJson || path.join(os.homedir(), ".claude.json");
+    try {
+      if (isClaudeVisionMcp(readJson(file).mcpServers?.[VISION_MCP_NAME])) return true;
+    } catch {
+      return true;
+    }
+  }
+  if (!removed.has("codex")) {
+    const file = opts.codexConfig || path.join(os.homedir(), ".codex", "config.toml");
+    try {
+      const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+      const start = text.indexOf(CODEX_VISION_BEGIN);
+      const end = text.indexOf(CODEX_VISION_END, start + CODEX_VISION_BEGIN.length);
+      if (start !== -1 && end !== -1) {
+        const block = text.slice(start, end);
+        if (
+          block.includes(fwd(VISION_RUNTIME_SERVER)) ||
+          block.includes(fwd(VISION_LEGACY_RUNTIME_SERVER))
+        ) {
+          return true;
+        }
+      }
+    } catch {
+      return true;
+    }
+  }
+  if (!removed.has("opencode")) {
+    const file = path.join(opencodeConfigDir(opts), "opencode.json");
+    try {
+      if (fs.existsSync(file)) {
+        const errors = [];
+        const config = parseJsonc(fs.readFileSync(file, "utf8"), errors, { allowTrailingComma: true });
+        if (errors.length > 0) return true;
+        if (isOpenCodeVisionMcp(config?.mcp?.[VISION_MCP_NAME])) return true;
+      }
+    } catch {
+      return true;
+    }
+  }
+  return false;
+}
+
+function cleanupVisionRuntimeIfUnused(opts) {
+  if (!opts.uninstall || !wants(opts, "vision") || !fs.existsSync(VISION_RUNTIME_DIR)) return;
+  if (visionRuntimeHasRemainingReference(opts)) {
+    console.log(`  kept shared vision runtime ${VISION_RUNTIME_DIR} (another agent still references it)`);
+    return;
+  }
+  if (opts.dryRun) {
+    console.log(`  [dry-run] would remove unused vision runtime ${VISION_RUNTIME_DIR}`);
+    return;
+  }
+  fs.rmSync(VISION_RUNTIME_DIR, { recursive: true, force: true });
+  if (!fs.existsSync(`${VISION_RATE_LIMIT_STATE}.lock`)) {
+    fs.rmSync(VISION_RATE_LIMIT_STATE, { force: true });
+    try {
+      fs.rmdirSync(path.dirname(VISION_RATE_LIMIT_STATE));
+    } catch {
+      // The shared cache directory may contain state for other capabilities.
+    }
+  }
+  console.log(`  removed unused vision runtime ${VISION_RUNTIME_DIR}`);
+}
+
 const AGENTS = { claude: runClaude, codex: runCodex, opencode: runOpencode };
 
 function main() {
@@ -538,6 +972,7 @@ function main() {
   }
   validateAgentCapabilities(opts);
   installRuntimeAssets(opts);
+  if (wants(opts, "vision")) installVisionRuntime(opts);
   for (const name of opts.agents) {
     const run = AGENTS[name];
     if (!run) {
@@ -546,6 +981,19 @@ function main() {
     }
     run(opts);
   }
+  cleanupVisionRuntimeIfUnused(opts);
 }
 
-main();
+// Standalone vision commands dispatch before capability parsing so image
+// paths and questions are never mistaken for capabilities.
+const subcommand = process.argv[2];
+if (subcommand === "inspect-image") {
+  const { runInspectImageCli } = await import(
+    pathToFileURL(VISION_BUNDLED_CLI).href
+  );
+  process.exitCode = await runInspectImageCli(process.argv.slice(3));
+} else if (subcommand === "mcp-vision") {
+  await import(pathToFileURL(VISION_BUNDLED_MCP_SERVER).href);
+} else {
+  main();
+}

package/scripts/release.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// Release helper for @kairyou/agent-tools.
+//
+// Usage:
+//   npm run release [-- minor|major]   # default: patch
+//   npm run release -- --dry-run       # npm test + preview tarball, no bump/publish
+//
+// Steps: clean-tree check -> npm test -> npm version -> npm publish -> git push --follow-tags
+//
+// Release when scripts/ lib/ plugins/ hooks/ statusline/ config.default.jsonc or
+// package.json deps change — npx users only get these from the published package.
+// (skills/ ships from GitHub via `npx skills add`; no release needed.)
+
+import { spawnSync } from "node:child_process";
+
+const BUMPS = ["patch", "minor", "major"];
+let bump = "patch";
+let dryRun = false;
+for (const arg of process.argv.slice(2)) {
+  if (arg === "--dry-run") dryRun = true;
+  else if (BUMPS.includes(arg)) bump = arg;
+  else {
+    console.error(`Unknown argument: ${arg} (expected ${BUMPS.join("|")} or --dry-run)`);
+    process.exit(2);
+  }
+}
+
+function run(command, opts = {}) {
+  console.log(`\n> ${command}`);
+  const result = spawnSync(command, { stdio: "inherit", shell: true, ...opts });
+  if (result.status !== 0) {
+    console.error(`\nAborted: \`${command}\` exited with ${result.status}.`);
+    process.exit(result.status ?? 1);
+  }
+}
+
+const status = spawnSync("git status --porcelain", { shell: true, encoding: "utf8" });
+if (!dryRun && status.stdout.trim() !== "") {
+  console.error("Working tree is not clean — commit or stash first:\n" + status.stdout);
+  process.exit(1);
+}
+
+run("npm test");
+
+if (dryRun) {
+  // Shows exactly which files would ship; verify nothing is missing/extra.
+  run("npm pack --dry-run");
+  console.log("\nDry run complete. No version bump, nothing published.");
+  process.exit(0);
+}
+
+run(`npm version ${bump}`);
+run("npm publish");
+run("git push --follow-tags");
+
+console.log("\nRelease complete.");