acp-devtools 0.4.0 → 0.6.0

package/dist/index.js

@@ -3755,21 +3755,21 @@ var require_fast_uri = __commonJS({
         normalizeString(uri, options);
       } else if (typeof uri === "object") {
         uri = /** @type {T} */
-        parse(serialize(uri, options), options);
+        parse2(serialize(uri, options), options);
       }
       return uri;
     }
     function resolve2(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
-      const resolved = resolveComponent(parse(baseURI, schemelessOptions), parse(relativeURI, schemelessOptions), schemelessOptions, true);
+      const resolved = resolveComponent(parse2(baseURI, schemelessOptions), parse2(relativeURI, schemelessOptions), schemelessOptions, true);
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
     function resolveComponent(base, relative, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
-        base = parse(serialize(base, options), options);
-        relative = parse(serialize(relative, options), options);
+        base = parse2(serialize(base, options), options);
+        relative = parse2(serialize(relative, options), options);
       }
       options = options || {};
       if (!options.tolerant && relative.scheme) {
@@ -3992,7 +3992,7 @@ var require_fast_uri = __commonJS({
       }
       return { parsed, malformedAuthorityOrPort };
     }
-    function parse(uri, opts) {
+    function parse2(uri, opts) {
       return parseWithStatus(uri, opts).parsed;
     }
     function normalizeString(uri, opts) {
@@ -4021,7 +4021,7 @@ var require_fast_uri = __commonJS({
       resolveComponent,
       equal,
       serialize,
-      parse
+      parse: parse2
     };
     module.exports = fastUri;
     module.exports.default = fastUri;
@@ -7278,8 +7278,12 @@ function createAcpValidator(schema3) {
   const ajv = new Ajv2020({ strict: false, allErrors: true, validateFormats: false });
   ajv.addSchema(schema3, SCHEMA_ID);
   const methodIndex = /* @__PURE__ */ new Map();
+  const softRequired = /* @__PURE__ */ new Map();
   const defs = schema3.$defs ?? {};
   for (const [name, def] of Object.entries(defs)) {
+    const soon = Object.entries(def.properties ?? {}).filter(([, prop]) => SOON_REQUIRED_RE.test(prop.description ?? "")).map(([field]) => field);
+    if (soon.length > 0)
+      softRequired.set(name, soon);
     const method = def["x-method"];
     if (typeof method !== "string")
       continue;
@@ -7332,22 +7336,41 @@ function createAcpValidator(schema3) {
     }
     if (!defName)
       return { valid: true, errors: [], skipped: "no-schema-for-kind" };
+    const advisories = collectAdvisories(defName, target);
     const validator2 = getValidator(defName);
     const ok = validator2(target);
-    if (ok)
-      return { valid: true, errors: [], schemaName: defName };
-    return {
+    const base = ok ? { valid: true, errors: [], schemaName: defName } : {
       valid: false,
       errors: (validator2.errors ?? []).map(toError),
       schemaName: defName
     };
+    if (advisories.length > 0)
+      base.advisories = advisories;
+    return base;
+  }
+  function collectAdvisories(defName, target) {
+    const fields = softRequired.get(defName);
+    if (!fields || typeof target !== "object" || target === null)
+      return [];
+    const obj = target;
+    const out = [];
+    for (const field of fields) {
+      if (obj[field] === void 0 || obj[field] === null) {
+        out.push({
+          path: field,
+          message: `missing ${field} \u2014 will be required in a future ACP version`,
+          kind: "soon-required"
+        });
+      }
+    }
+    return out;
   }
   function knownAcpMethods2() {
     return [...methodIndex.keys()].sort();
   }
   return { validateAcpMessage: validateAcpMessage2, knownAcpMethods: knownAcpMethods2 };
 }
-var import__, ajvModule, Ajv2020, SCHEMA_ID;
+var import__, ajvModule, Ajv2020, SCHEMA_ID, SOON_REQUIRED_RE;
 var init_validate_factory = __esm({
   "../core/dist/acp/validate-factory.js"() {
     "use strict";
@@ -7355,6 +7378,7 @@ var init_validate_factory = __esm({
     ajvModule = import__.default;
     Ajv2020 = ajvModule.default ?? ajvModule;
     SCHEMA_ID = "acp";
+    SOON_REQUIRED_RE = /will be required/i;
   }
 });
 
@@ -8430,6 +8454,7 @@ function detectAgentShortcut(agentCommand) {
   const trimmed = agentCommand.trim();
   if (trimmed.length === 0)
     return null;
+  const candidates = [trimmed, basenameFirstToken(trimmed)];
   for (const def of Object.values(AGENT_REGISTRY)) {
     const variants = [
       [def.command, ...def.args],
@@ -8437,14 +8462,23 @@ function detectAgentShortcut(agentCommand) {
     ];
     for (const variant of variants) {
       const exact = variant.join(" ");
-      if (trimmed === exact)
-        return def;
-      if (trimmed.startsWith(exact + " "))
-        return def;
+      for (const candidate of candidates) {
+        if (candidate === exact)
+          return def;
+        if (candidate.startsWith(exact + " "))
+          return def;
+      }
     }
   }
   return null;
 }
+function basenameFirstToken(command) {
+  const spaceAt = command.indexOf(" ");
+  const head = spaceAt === -1 ? command : command.slice(0, spaceAt);
+  const rest = spaceAt === -1 ? "" : command.slice(spaceAt);
+  const base = head.split(/[/\\]/).pop() ?? head;
+  return base + rest;
+}
 var AGENT_REGISTRY, DEFAULT_AGENT;
 var init_registry = __esm({
   "../core/dist/agents/registry.js"() {
@@ -8484,6 +8518,14 @@ var init_registry = __esm({
         command: "opencode",
         args: ["acp"],
         requiresExternalInstall: true
+      },
+      junie: {
+        shortName: "junie",
+        displayName: "Junie",
+        description: "JetBrains Junie CLI \u2014 install separately, then this runs `junie --acp=true`",
+        command: "junie",
+        args: ["--acp=true"],
+        requiresExternalInstall: true
       }
     };
     DEFAULT_AGENT = "claude-code";
@@ -10039,6 +10081,142 @@ var init_dist = __esm({
   }
 });
 
+// src/lib/style.ts
+function colorEnabled(stream = process.stdout, env = process.env) {
+  if (env.FORCE_COLOR === "0" || env.FORCE_COLOR === "false") return false;
+  if (env.FORCE_COLOR !== void 0) return true;
+  if (env.NO_COLOR !== void 0) return false;
+  return Boolean(stream.isTTY);
+}
+function paint(enabled, code, s) {
+  if (!enabled) return s;
+  return `${ESC}[${CODES[code]}m${s}${ESC}[${CODES.reset}m`;
+}
+function createStyler(enabled = colorEnabled()) {
+  const wrap = (code) => (s) => paint(enabled, code, s);
+  return {
+    enabled,
+    bold: wrap("bold"),
+    dim: wrap("dim"),
+    italic: wrap("italic"),
+    underline: wrap("underline"),
+    red: wrap("red"),
+    green: wrap("green"),
+    yellow: wrap("yellow"),
+    blue: wrap("blue"),
+    magenta: wrap("magenta"),
+    cyan: wrap("cyan"),
+    gray: wrap("gray")
+  };
+}
+function stripAnsi(s) {
+  return s.replace(ANSI_PATTERN, "");
+}
+function visibleWidth(s) {
+  return stripAnsi(s).length;
+}
+var ESC, CODES, ANSI_PATTERN;
+var init_style = __esm({
+  "src/lib/style.ts"() {
+    "use strict";
+    ESC = String.fromCharCode(27);
+    CODES = {
+      reset: 0,
+      bold: 1,
+      dim: 2,
+      italic: 3,
+      underline: 4,
+      red: 31,
+      green: 32,
+      yellow: 33,
+      blue: 34,
+      magenta: 35,
+      cyan: 36,
+      gray: 90
+    };
+    ANSI_PATTERN = new RegExp(`${ESC}\\[[0-9;]*m`, "g");
+  }
+});
+
+// src/lib/table.ts
+function renderTable(s, columns, rows, opts = {}) {
+  const indent = opts.indent ?? "";
+  const gap = opts.gap ?? "  ";
+  const widths = columns.map(
+    (col, c) => Math.max(visibleWidth(col.title), ...rows.map((r) => visibleWidth(r[c] ?? "")))
+  );
+  const pad2 = (text, width, align) => {
+    const fill = " ".repeat(Math.max(0, width - visibleWidth(text)));
+    return align === "right" ? fill + text : text + fill;
+  };
+  const lineFor = (cells, color) => {
+    const rendered = columns.map((col, c) => {
+      const align = col.align ?? "left";
+      const text = cells[c] ?? "";
+      const isLast = c === columns.length - 1;
+      const cell = isLast && align === "left" ? text : pad2(text, widths[c], align);
+      return color(cell);
+    });
+    return indent + rendered.join(gap);
+  };
+  const out = [];
+  out.push(
+    lineFor(
+      columns.map((col) => col.title),
+      (t) => s.dim(t)
+    )
+  );
+  for (const row2 of rows) {
+    out.push(lineFor(row2, (t) => t));
+  }
+  return out.map((l) => l + "\n").join("");
+}
+var init_table = __esm({
+  "src/lib/table.ts"() {
+    "use strict";
+    init_style();
+  }
+});
+
+// src/commands/agents.ts
+function registerAgentsCommand(program) {
+  program.command("agents").description("List the built-in agent shortcuts (use with proxy / setup / --agent)").option("--json", "emit machine-readable JSON instead of a table").action((opts) => {
+    const agents = listAgents();
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(agents, null, 2) + "\n");
+      return;
+    }
+    const s = createStyler(colorEnabled(process.stdout));
+    const rows = agents.map((a) => [
+      s.green(a.shortName),
+      a.displayName,
+      [a.command, ...a.args].join(" "),
+      a.requiresExternalInstall ? "install separately" : "auto via npx"
+    ]);
+    process.stdout.write(renderTable(s, COLUMNS, rows));
+    process.stdout.write(
+      s.dim(
+        "\nUse a shortcut: acp-devtools <name> \xB7 proxy --agent <name> \xB7 setup <name> --editor <zed|jetbrains>\nAny other ACP agent: acp-devtools setup --editor <ed> -- <command\u2026>\n"
+      )
+    );
+  });
+}
+var COLUMNS;
+var init_agents2 = __esm({
+  "src/commands/agents.ts"() {
+    "use strict";
+    init_dist();
+    init_style();
+    init_table();
+    COLUMNS = [
+      { title: "SHORTCUT" },
+      { title: "NAME" },
+      { title: "RUNS" },
+      { title: "INSTALL" }
+    ];
+  }
+});
+
 // src/commands/backfill-metadata.ts
 function backfillSession(db, id) {
   let session;
@@ -10187,63 +10365,6 @@ var init_delete = __esm({
   }
 });
 
-// src/lib/style.ts
-function colorEnabled(stream = process.stdout, env = process.env) {
-  if (env.FORCE_COLOR === "0" || env.FORCE_COLOR === "false") return false;
-  if (env.FORCE_COLOR !== void 0) return true;
-  if (env.NO_COLOR !== void 0) return false;
-  return Boolean(stream.isTTY);
-}
-function paint(enabled, code, s) {
-  if (!enabled) return s;
-  return `${ESC}[${CODES[code]}m${s}${ESC}[${CODES.reset}m`;
-}
-function createStyler(enabled = colorEnabled()) {
-  const wrap = (code) => (s) => paint(enabled, code, s);
-  return {
-    enabled,
-    bold: wrap("bold"),
-    dim: wrap("dim"),
-    italic: wrap("italic"),
-    underline: wrap("underline"),
-    red: wrap("red"),
-    green: wrap("green"),
-    yellow: wrap("yellow"),
-    blue: wrap("blue"),
-    magenta: wrap("magenta"),
-    cyan: wrap("cyan"),
-    gray: wrap("gray")
-  };
-}
-function stripAnsi(s) {
-  return s.replace(ANSI_PATTERN, "");
-}
-function visibleWidth(s) {
-  return stripAnsi(s).length;
-}
-var ESC, CODES, ANSI_PATTERN;
-var init_style = __esm({
-  "src/lib/style.ts"() {
-    "use strict";
-    ESC = String.fromCharCode(27);
-    CODES = {
-      reset: 0,
-      bold: 1,
-      dim: 2,
-      italic: 3,
-      underline: 4,
-      red: 31,
-      green: 32,
-      yellow: 33,
-      blue: 34,
-      magenta: 35,
-      cyan: 36,
-      gray: 90
-    };
-    ANSI_PATTERN = new RegExp(`${ESC}\\[[0-9;]*m`, "g");
-  }
-});
-
 // src/lib/palette.ts
 function colorKind(s, kind, text) {
   switch (kind) {
@@ -10277,46 +10398,6 @@ var init_palette = __esm({
   }
 });
 
-// src/lib/table.ts
-function renderTable(s, columns, rows, opts = {}) {
-  const indent = opts.indent ?? "";
-  const gap = opts.gap ?? "  ";
-  const widths = columns.map(
-    (col, c) => Math.max(visibleWidth(col.title), ...rows.map((r) => visibleWidth(r[c] ?? "")))
-  );
-  const pad2 = (text, width, align) => {
-    const fill = " ".repeat(Math.max(0, width - visibleWidth(text)));
-    return align === "right" ? fill + text : text + fill;
-  };
-  const lineFor = (cells, color) => {
-    const rendered = columns.map((col, c) => {
-      const align = col.align ?? "left";
-      const text = cells[c] ?? "";
-      const isLast = c === columns.length - 1;
-      const cell = isLast && align === "left" ? text : pad2(text, widths[c], align);
-      return color(cell);
-    });
-    return indent + rendered.join(gap);
-  };
-  const out = [];
-  out.push(
-    lineFor(
-      columns.map((col) => col.title),
-      (t) => s.dim(t)
-    )
-  );
-  for (const row2 of rows) {
-    out.push(lineFor(row2, (t) => t));
-  }
-  return out.map((l) => l + "\n").join("");
-}
-var init_table = __esm({
-  "src/lib/table.ts"() {
-    "use strict";
-    init_style();
-  }
-});
-
 // src/commands/diff.ts
 function registerDiffCommand(program) {
   program.command("diff").description(
@@ -10600,10 +10681,130 @@ var init_diff = __esm({
   }
 });
 
+// src/lib/setup-config.ts
+import { homedir as homedir3, platform } from "os";
+import { join as join3 } from "path";
+import { applyEdits, modify, parse } from "jsonc-parser";
+function isEditor(value) {
+  return EDITORS.includes(value);
+}
+function zedSettingsPath() {
+  if (platform() === "win32") {
+    return join3(process.env.APPDATA ?? "", "Zed", "settings.json");
+  }
+  if (platform() === "darwin") {
+    return join3(homedir3(), ".config", "zed", "settings.json");
+  }
+  return join3(process.env.XDG_CONFIG_HOME ?? join3(homedir3(), ".config"), "zed", "settings.json");
+}
+function jetbrainsConfigPath() {
+  return join3(homedir3(), ".jetbrains", "acp.json");
+}
+function editorInfo(editor) {
+  if (editor === "zed") {
+    return {
+      id: "zed",
+      label: "Zed",
+      configPath: zedSettingsPath(),
+      placement: "add the agent_servers block to Zed\u2019s settings.json (create the file or the key if missing)",
+      restart: "reopen the agent panel so Zed re-reads the config",
+      dedicatedFile: false
+    };
+  }
+  return {
+    id: "jetbrains",
+    label: "JetBrains",
+    configPath: jetbrainsConfigPath(),
+    placement: "write this to the global JetBrains ACP config (create it if missing \u2014 every JetBrains IDE shares this one file)",
+    restart: "restart the AI chat tool window (close and reopen it)",
+    dedicatedFile: true
+  };
+}
+function deriveCustomName(target) {
+  const first = target[0] ?? "agent";
+  if (first === "npx") {
+    for (let i = 1; i < target.length; i++) {
+      const token = target[i];
+      if (!token.startsWith("-")) return token;
+    }
+  }
+  return first.split(/[/\\]/).pop() || first;
+}
+function buildSetupPlan(input) {
+  const target = input.target.length > 0 ? [...input.target] : [DEFAULT_AGENT];
+  const single = target.length === 1 ? target[0] : null;
+  let args;
+  let displayName;
+  let isCustom;
+  let agentDescription;
+  let requiresExternalInstall = false;
+  if (single !== null && isAgentShortcut(single)) {
+    const def = resolveAgent(single);
+    args = [def.shortName];
+    displayName = input.name ?? `${def.displayName} (via ACP Devtools)`;
+    isCustom = false;
+    agentDescription = def.description;
+    requiresExternalInstall = def.requiresExternalInstall ?? false;
+  } else {
+    args = ["proxy", ...target];
+    displayName = input.name ?? `${deriveCustomName(target)} (via ACP Devtools)`;
+    isCustom = true;
+  }
+  return {
+    editor: editorInfo(input.editor),
+    displayName,
+    entry: { type: "custom", command: input.selfPath, args },
+    isCustom,
+    agentDescription,
+    requiresExternalInstall
+  };
+}
+function renderConfigBlock(plan) {
+  const entries = { [plan.displayName]: plan.entry };
+  if (plan.editor.dedicatedFile) {
+    return JSON.stringify({ agent_servers: entries }, null, 4);
+  }
+  return `"agent_servers": ${JSON.stringify(entries, null, 4)}`;
+}
+function detectFormatting(text) {
+  const match = text.match(/\n([ \t]+)\S/);
+  if (!match) return { insertSpaces: true, tabSize: 4 };
+  const ws = match[1];
+  if (ws.startsWith("	")) return { insertSpaces: false, tabSize: 1 };
+  return { insertSpaces: true, tabSize: ws.length };
+}
+function mergeIntoConfig(existing, name, entry) {
+  const base = existing !== null && existing.trim().length > 0 ? existing : "{}";
+  const errors = [];
+  const root = parse(base, errors, { allowTrailingComma: true });
+  if (errors.length > 0) {
+    throw new Error("config is not valid JSON");
+  }
+  if (typeof root !== "object" || root === null || Array.isArray(root)) {
+    throw new Error("config root is not a JSON object");
+  }
+  const servers = root.agent_servers;
+  const replaced = typeof servers === "object" && servers !== null && !Array.isArray(servers) ? Object.prototype.hasOwnProperty.call(servers, name) : false;
+  const edits = modify(base, ["agent_servers", name], entry, {
+    formattingOptions: detectFormatting(base)
+  });
+  let text = applyEdits(base, edits);
+  if (!text.endsWith("\n")) text += "\n";
+  return { text, replaced };
+}
+var EDITORS;
+var init_setup_config = __esm({
+  "src/lib/setup-config.ts"() {
+    "use strict";
+    init_dist();
+    EDITORS = ["zed", "jetbrains"];
+  }
+});
+
 // src/commands/doctor.ts
 import { existsSync as existsSync6, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
-import { homedir as homedir3, platform, release } from "os";
-import { join as join3 } from "path";
+import { homedir as homedir4, platform as platform2, release } from "os";
+import { join as join4 } from "path";
 function colorStatus(s, status, text) {
   switch (status) {
     case "ok":
@@ -10626,7 +10827,7 @@ function checkEnvironment() {
   });
   results.push({
     status: "info",
-    label: `Platform: ${platform()} ${process.arch} (${release()})`
+    label: `Platform: ${platform2()} ${process.arch} (${release()})`
   });
   const binary = process.argv[1] ?? "(unknown)";
   results.push({
@@ -10710,21 +10911,17 @@ function checkState() {
   return results;
 }
 function probeZed() {
-  const path = platform() === "win32" ? join3(process.env.APPDATA ?? "", "Zed", "settings.json") : platform() === "darwin" ? join3(homedir3(), ".config", "zed", "settings.json") : join3(
-    process.env.XDG_CONFIG_HOME ?? join3(homedir3(), ".config"),
-    "zed",
-    "settings.json"
-  );
+  const path = zedSettingsPath();
   return { name: "Zed", path, exists: existsSync6(path) };
 }
 function probeJetBrains() {
   const baseDirs = [];
-  if (platform() === "darwin") {
-    baseDirs.push(join3(homedir3(), "Library", "Application Support", "JetBrains"));
-  } else if (platform() === "win32") {
-    baseDirs.push(join3(process.env.APPDATA ?? "", "JetBrains"));
+  if (platform2() === "darwin") {
+    baseDirs.push(join4(homedir4(), "Library", "Application Support", "JetBrains"));
+  } else if (platform2() === "win32") {
+    baseDirs.push(join4(process.env.APPDATA ?? "", "JetBrains"));
   } else {
-    baseDirs.push(join3(homedir3(), ".config", "JetBrains"));
+    baseDirs.push(join4(homedir4(), ".config", "JetBrains"));
   }
   const probes = [];
   for (const base of baseDirs) {
@@ -10738,7 +10935,7 @@ function probeJetBrains() {
     for (const entry of entries) {
       if (entry.startsWith(".")) continue;
       if (!JETBRAINS_VERSIONED.test(entry) && !JETBRAINS_UNVERSIONED.has(entry)) continue;
-      const full = join3(base, entry);
+      const full = join4(base, entry);
       try {
         if (!statSync2(full).isDirectory()) continue;
       } catch {
@@ -10837,6 +11034,7 @@ var init_doctor = __esm({
     "use strict";
     init_dist();
     init_style();
+    init_setup_config();
     STATUS_MARK = {
       ok: "\u2713",
       warn: "!",
@@ -10853,7 +11051,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = "0.4.0";
+    CLI_VERSION = "0.6.0";
   }
 });
 
@@ -11322,9 +11520,9 @@ function formatTable(rows) {
       labelOf(r)
     ];
   });
-  return renderTable(s, COLUMNS, body);
+  return renderTable(s, COLUMNS2, body);
 }
-var COLUMNS;
+var COLUMNS2;
 var init_list = __esm({
   "src/commands/list.ts"() {
     "use strict";
@@ -11332,7 +11530,7 @@ var init_list = __esm({
     init_style();
     init_palette();
     init_table();
-    COLUMNS = [
+    COLUMNS2 = [
       { title: "ID", align: "left" },
       { title: "AGE", align: "right" },
       { title: "KIND", align: "left" },
@@ -11589,7 +11787,9 @@ function buildMcpServer(opts) {
       description: "Fetch a single captured frame by (session_id, seq). Returns the full record: raw JSON bytes, parsed payload, parseError (if any), direction, kind, method, rpcId, timestamp. Use this after find_spec_violations / get_session_messages narrows you down to a specific seq.",
       inputSchema: {
         session_id: z.number().int().positive().describe("session id from list_sessions"),
-        seq: z.number().int().positive().describe("per-session sequence number from list_session_messages or find_spec_violations")
+        seq: z.number().int().positive().describe(
+          "per-session sequence number from list_session_messages or find_spec_violations"
+        )
       },
       outputSchema: {
         session_id: z.number(),
@@ -11668,7 +11868,7 @@ function buildMcpServer(opts) {
   server.registerTool(
     "find_spec_violations",
     {
-      description: "Validate every captured frame in a session against the ACP JSON schema (Draft 2020-12, ajv-compiled). Returns every offender with its seq, method, and per-error path + keyword + message. Schema-skipped frames (unknown methods, parse errors, generic envelopes) are not counted. Use the returned seq with get_message to inspect the offending raw payload. Start here when an agent is misbehaving but you don't yet know how.",
+      description: "Validate every captured frame in a session against the ACP JSON schema (Draft 2020-12, ajv-compiled). Returns every offender with its seq, method, and per-error path + keyword + message. Schema-skipped frames (unknown methods, parse errors, generic envelopes) are not counted. Also returns `advisories`: frames valid under today's schema that omit a field the spec says will become mandatory (e.g. `agentInfo` on an initialize response, `clientInfo` on the request) \u2014 these never count as violations. Use the returned seq with get_message to inspect the offending raw payload. Start here when an agent is misbehaving but you don't yet know how.",
       inputSchema: {
         session_id: z.number().int().positive().describe("session id from list_sessions")
       },
@@ -11683,13 +11883,23 @@ function buildMcpServer(opts) {
           z.object({
             seq: z.number(),
             method: z.string().nullable(),
-            errors: z.array(z.looseObject({
-              keyword: z.string(),
-              instancePath: z.string().optional(),
-              schemaPath: z.string().optional(),
-              message: z.string().optional()
-            }))
+            errors: z.array(
+              z.looseObject({
+                keyword: z.string(),
+                instancePath: z.string().optional(),
+                schemaPath: z.string().optional(),
+                message: z.string().optional()
+              })
+            )
           }).loose()
+        ),
+        advisories: z.array(
+          z.object({
+            seq: z.number(),
+            method: z.string().nullable(),
+            path: z.string(),
+            message: z.string()
+          })
         )
       },
       annotations: annotations({ title: "Validate session against ACP schema" })
@@ -11700,6 +11910,7 @@ function buildMcpServer(opts) {
       const seqToMethod = /* @__PURE__ */ new Map();
       for (const m of messages) if (m.method) seqToMethod.set(m.seq, m.method);
       const violations = [];
+      const advisories = [];
       let checked = 0;
       for (const m of messages) {
         const pair = pairs.get(m.seq);
@@ -11709,15 +11920,15 @@ function buildMcpServer(opts) {
         const result = validateAcpMessage(m, validationOpts);
         if (result.skipped) continue;
         checked += 1;
+        const method = m.method ?? pairedMethod ?? null;
         if (!result.valid) {
-          violations.push({
-            seq: m.seq,
-            method: m.method ?? pairedMethod ?? null,
-            errors: result.errors
-          });
+          violations.push({ seq: m.seq, method, errors: result.errors });
+        }
+        for (const a of result.advisories ?? []) {
+          advisories.push({ seq: m.seq, method, path: a.path, message: a.message });
         }
       }
-      return structuredResult({ session_id, checked, violations });
+      return structuredResult({ session_id, checked, violations, advisories });
     }
   );
   server.registerTool(
@@ -11808,6 +12019,88 @@ function buildMcpServer(opts) {
       });
     }
   );
+  server.registerTool(
+    "list_agent_shortcuts",
+    {
+      description: "List the built-in agent shortcuts you can pass to generate_editor_config as `agent` (or that the CLI accepts as `acp-devtools <name>` / `proxy --agent <name>`). Each is a known ACP agent wired into the registry; anything else is still supported via generate_editor_config's `command` argument. Same data as the CLI `acp-devtools agents`.",
+      inputSchema: {},
+      outputSchema: {
+        agents: z.array(
+          z.object({
+            shortName: z.string(),
+            displayName: z.string(),
+            command: z.string(),
+            args: z.array(z.string()),
+            requiresExternalInstall: z.boolean()
+          })
+        )
+      },
+      annotations: annotations({ title: "List agent shortcuts" })
+    },
+    async () => {
+      const agents = listAgents().map((a) => ({
+        shortName: a.shortName,
+        displayName: a.displayName,
+        command: a.command,
+        args: [...a.args],
+        requiresExternalInstall: a.requiresExternalInstall ?? false
+      }));
+      return structuredResult({ agents });
+    }
+  );
+  server.registerTool(
+    "generate_editor_config",
+    {
+      description: 'Generate the editor config (Zed or JetBrains) that runs an ACP agent through ACP Devtools, with the absolute acp-devtools binary path already filled in. Use this when the user asks to wire up / add an agent \u2014 e.g. "add junie for zed". Returns `block` (the JSON to add to the editor config), `configPath` (where it goes), and `writeCommand` (the equivalent `acp-devtools setup --write` to run instead). This tool only COMPUTES the config \u2014 it does not write any file; add `block` to `configPath` with your own file tools, or tell the user to run `writeCommand`. Pass `agent` for a registry shortcut (see list_agent_shortcuts) or `command` for any other agent (wrapped via `proxy`). Mirrors the CLI `acp-devtools setup`.',
+      inputSchema: {
+        editor: z.enum(["zed", "jetbrains"]).describe("target editor: zed or jetbrains"),
+        agent: z.string().optional().describe(
+          "registry shortcut: junie, goose, codex, opencode, or claude-code (the default when neither agent nor command is given)"
+        ),
+        command: z.array(z.string()).optional().describe(
+          'custom agent command tokens (e.g. ["npx","-y","@scope/acp"]), wrapped via proxy; ignored when `agent` is set'
+        ),
+        name: z.string().optional().describe("display name override for the agent entry")
+      },
+      outputSchema: {
+        displayName: z.string(),
+        editor: z.enum(["zed", "jetbrains"]),
+        configPath: z.string(),
+        dedicatedFile: z.boolean(),
+        entry: z.object({
+          type: z.literal("custom"),
+          command: z.string(),
+          args: z.array(z.string())
+        }),
+        block: z.string(),
+        writeCommand: z.string(),
+        requiresExternalInstall: z.boolean(),
+        installHint: z.string().optional()
+      },
+      annotations: annotations({ title: "Generate editor config" })
+    },
+    async ({ editor, agent, command, name }) => {
+      const target = command && command.length > 0 ? command : agent ? [agent] : [];
+      const selfPath = process.argv[1] ?? "acp-devtools";
+      const plan = buildSetupPlan({ target, editor, selfPath, name });
+      const writeParts = ["acp-devtools setup", `--editor ${editor}`, "--write"];
+      if (name) writeParts.push(`--name ${JSON.stringify(name)}`);
+      if (target.length === 1) writeParts.push(target[0]);
+      else if (target.length > 1) writeParts.push("--", ...target);
+      const installHint = plan.isCustom ? void 0 : plan.requiresExternalInstall ? plan.agentDescription : "Installs automatically via npx on first run.";
+      return structuredResult({
+        displayName: plan.displayName,
+        editor,
+        configPath: plan.editor.configPath,
+        dedicatedFile: plan.editor.dedicatedFile,
+        entry: plan.entry,
+        block: renderConfigBlock(plan),
+        writeCommand: writeParts.join(" "),
+        requiresExternalInstall: plan.requiresExternalInstall,
+        ...installHint !== void 0 ? { installHint } : {}
+      });
+    }
+  );
   registerPrompts(server);
   return server;
 }
@@ -11931,12 +12224,14 @@ var init_mcp = __esm({
     "use strict";
     init_dist();
     init_version();
+    init_setup_config();
     SERVER_INSTRUCTIONS = `acp-devtools exposes a local SQLite store of captured
 Agent Client Protocol (ACP) sessions. ACP is the editor\u2194agent JSON-RPC
 protocol used by Claude Code, Goose, Codex, and other IDE agents.
 
 Every tool here is **read-only** \u2014 nothing in this server writes to the
-database. Use it to investigate:
+database or to any file (\`generate_editor_config\` only returns the config
+text to write; you apply it). Use it to investigate:
 
 - a slow session (\`get_latency_stats\` returns per-method p50/p99/max
   plus auto-detected insights: hotspot, long-tail, outlier, busiest,
@@ -11953,6 +12248,12 @@ database. Use it to investigate:
   (\`diff_sessions\` aligns two captures and reports added / removed
   frames and field-level payload changes)
 
+It also helps wire agents up: \`list_agent_shortcuts\` enumerates the known
+agents, and \`generate_editor_config({editor, agent})\` returns the
+Zed/JetBrains config block to run one through the proxy (e.g. "add junie for
+zed") \u2014 apply \`block\` to \`configPath\` with your own file tools, or run the
+returned \`writeCommand\`.
+
 A typical investigation:
 1. \`list_sessions\` to see what is captured
 2. \`get_session_summary({session_id})\` for the headline numbers and
@@ -12888,7 +13189,7 @@ function renderHits(s, hits, needle) {
     truncate2(h.method ?? "\u2014", METHOD_MAX2),
     highlight(s, h.snippet, needle)
   ]);
-  return renderTable(s, COLUMNS2, body);
+  return renderTable(s, COLUMNS3, body);
 }
 function highlight(s, snippet, needle) {
   if (!s.enabled || needle.length === 0) return snippet;
@@ -12910,7 +13211,7 @@ function truncate2(s, max) {
   if (s.length <= max) return s;
   return s.slice(0, Math.max(1, max - 1)) + "\u2026";
 }
-var SNIPPET_LEN, METHOD_MAX2, COLUMNS2;
+var SNIPPET_LEN, METHOD_MAX2, COLUMNS3;
 var init_search = __esm({
   "src/commands/search.ts"() {
     "use strict";
@@ -12919,7 +13220,7 @@ var init_search = __esm({
     init_table();
     SNIPPET_LEN = 80;
     METHOD_MAX2 = 32;
-    COLUMNS2 = [
+    COLUMNS3 = [
       { title: "LOC", align: "left" },
       { title: "METHOD", align: "left" },
       { title: "MATCH", align: "left" }
@@ -13107,6 +13408,139 @@ var init_session_info = __esm({
   }
 });
 
+// src/commands/setup.ts
+import { mkdirSync as mkdirSync6, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname5 } from "path";
+function fail(message, code) {
+  process.stderr.write(`acp-devtools: ${message}
+`);
+  process.exit(code);
+}
+function rerunCommand(editor, target, opts) {
+  const parts = ["acp-devtools setup", `--editor ${editor}`, "--write"];
+  if (opts.name) parts.push(`--name ${JSON.stringify(opts.name)}`);
+  if (opts.configPath) parts.push(`--config-path ${opts.configPath}`);
+  if (target.length === 1) {
+    parts.push(target[0]);
+  } else if (target.length > 1) {
+    parts.push("--", ...target);
+  }
+  return parts.join(" ");
+}
+function printInstallHint(plan, s) {
+  if (plan.isCustom) return;
+  if (plan.requiresExternalInstall) {
+    process.stdout.write(`
+  ${s.yellow("!")} ${plan.agentDescription}
+`);
+  } else {
+    process.stdout.write(`
+  ${s.dim("Installs automatically via npx on first run.")}
+`);
+  }
+}
+function printGuidance(plan, target, opts, configPath, s) {
+  const block = renderConfigBlock(plan);
+  process.stdout.write(
+    `
+${s.bold(plan.displayName)} ${s.dim("\u2192")} ${s.bold(plan.editor.label)}
+
+`
+  );
+  process.stdout.write(`  ${plan.editor.placement}:
+`);
+  process.stdout.write(`  ${s.cyan(configPath)}
+
+`);
+  process.stdout.write(`${block}
+`);
+  printInstallHint(plan, s);
+  process.stdout.write(`
+  Then ${plan.editor.restart}.
+`);
+  process.stdout.write(
+    `
+  ${s.dim("Or let ACP Devtools edit the file for you:")}
+    ${rerunCommand(opts.editor, target, opts)}
+
+`
+  );
+}
+function doWrite(plan, target, opts, configPath, s) {
+  let existing = null;
+  try {
+    existing = readFileSync5(configPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      fail(`cannot read ${configPath}: ${err.message}`, 1);
+    }
+  }
+  let merged;
+  try {
+    merged = mergeIntoConfig(existing, plan.displayName, plan.entry);
+  } catch {
+    process.stderr.write(
+      `${s.red("\u2717")} ${configPath} isn't valid JSON \u2014 leaving it untouched.
+  Paste this block in by hand:
+`
+    );
+    process.stdout.write(`
+${renderConfigBlock(plan)}
+
+`);
+    process.exit(1);
+  }
+  try {
+    mkdirSync6(dirname5(configPath), { recursive: true });
+    writeFileSync3(configPath, merged.text);
+  } catch (err) {
+    fail(`cannot write ${configPath}: ${err.message}`, 1);
+  }
+  const verb = merged.replaced ? "updated" : "wrote";
+  process.stdout.write(
+    `
+${s.green("\u2713")} ${verb} ${s.bold(JSON.stringify(plan.displayName))} in ${s.cyan(configPath)}
+`
+  );
+  printInstallHint(plan, s);
+  process.stdout.write(`
+  Then ${plan.editor.restart}.
+
+`);
+  process.exit(0);
+}
+function registerSetupCommand(program) {
+  program.command("setup [target...]").description("Generate an editor config that runs an agent through ACP Devtools").option("--editor <name>", `target editor (${EDITORS.join(" | ")})`).option("--name <label>", "display name for the agent entry").option("--config-path <path>", "override the editor config file location").option("--write", "merge the entry into the editor config instead of printing it", false).option("--no-color", "disable ANSI colour output").action((target, opts) => {
+    if (!opts.editor) {
+      fail(`--editor is required (${EDITORS.join(" | ")})`, 2);
+    }
+    if (!isEditor(opts.editor)) {
+      fail(`unknown editor "${opts.editor}" (expected ${EDITORS.join(" | ")})`, 2);
+    }
+    const selfPath = process.argv[1] ?? "acp-devtools";
+    const plan = buildSetupPlan({
+      target,
+      editor: opts.editor,
+      selfPath,
+      name: opts.name
+    });
+    const configPath = opts.configPath ?? editorInfo(opts.editor).configPath;
+    const s = createStyler(opts.color && colorEnabled(process.stdout));
+    if (opts.write) {
+      doWrite(plan, target, opts, configPath, s);
+    }
+    printGuidance(plan, target, opts, configPath, s);
+    process.exit(0);
+  });
+}
+var init_setup = __esm({
+  "src/commands/setup.ts"() {
+    "use strict";
+    init_style();
+    init_setup_config();
+  }
+});
+
 // src/commands/stats.ts
 function registerStatsCommand(program) {
   program.command("stats").description(
@@ -13401,11 +13835,11 @@ var init_stats = __esm({
 // src/commands/ui.ts
 import { createReadStream, existsSync as existsSync7, statSync as statSync3 } from "fs";
 import { createServer } from "http";
-import { dirname as dirname5, extname, join as join4, normalize, resolve, sep } from "path";
+import { dirname as dirname6, extname, join as join5, normalize, resolve, sep } from "path";
 import { fileURLToPath } from "url";
 import { spawn as spawn2 } from "child_process";
 function uiDistDir() {
-  const here = dirname5(fileURLToPath(import.meta.url));
+  const here = dirname6(fileURLToPath(import.meta.url));
   return resolve(here, "ui");
 }
 function contentTypeFor(path) {
@@ -13419,7 +13853,7 @@ function serveStatic(req, res, rootDir) {
   }
   const urlPath = decodeURIComponent((req.url ?? "/").split("?")[0] ?? "/");
   const relative = urlPath === "/" || urlPath === "" ? "/index.html" : urlPath;
-  const candidate = normalize(join4(rootDir, relative));
+  const candidate = normalize(join5(rootDir, relative));
   if (!candidate.startsWith(rootDir + sep) && candidate !== rootDir) {
     res.statusCode = 403;
     res.end();
@@ -13427,7 +13861,7 @@ function serveStatic(req, res, rootDir) {
   }
   let filePath = candidate;
   if (!existsSync7(filePath) || !statSync3(filePath).isFile()) {
-    filePath = join4(rootDir, "index.html");
+    filePath = join5(rootDir, "index.html");
     if (!existsSync7(filePath)) {
       res.statusCode = 404;
       res.setHeader("content-type", "text/plain; charset=utf-8");
@@ -13470,7 +13904,7 @@ function registerUiCommand(program) {
       process.exit(2);
     }
     const rootDir = uiDistDir();
-    if (!existsSync7(join4(rootDir, "index.html"))) {
+    if (!existsSync7(join5(rootDir, "index.html"))) {
       process.stderr.write(
         `acp-devtools: UI bundle missing at ${rootDir}
   Run \`npm run build:full\` in the monorepo, or reinstall the published package.
@@ -13597,6 +14031,7 @@ function registerValidateCommand(program) {
     }
     const methodNeedle = opts.method ? opts.method.toLowerCase() : null;
     const violations = [];
+    const advisories = [];
     let checked = 0;
     let skipped = 0;
     for (const m of messages) {
@@ -13610,11 +14045,20 @@ function registerValidateCommand(program) {
         continue;
       }
       checked += 1;
-      if (result.valid) continue;
       const method = m.method ?? pairedMethod ?? null;
-      if (methodNeedle && (!method || !method.toLowerCase().includes(methodNeedle))) {
-        continue;
+      const methodMatch = !methodNeedle || !!method && method.toLowerCase().includes(methodNeedle);
+      if (methodMatch && result.advisories) {
+        for (const a of result.advisories) {
+          advisories.push({
+            seq: m.seq,
+            method,
+            schemaName: result.schemaName ?? "?",
+            path: a.path,
+            message: a.message
+          });
+        }
       }
+      if (result.valid || !methodMatch) continue;
       for (const e of result.errors) {
         if (violations.length >= limit) break;
         const v = {
@@ -13633,7 +14077,7 @@ function registerValidateCommand(program) {
     if (opts.json) {
       process.stdout.write(
         JSON.stringify(
-          { sessionId: id, checked, skipped, violations },
+          { sessionId: id, checked, skipped, violations, advisories },
           null,
           2
         ) + "\n"
@@ -13644,18 +14088,25 @@ function registerValidateCommand(program) {
     const errStyler = createStyler(colorEnabled(process.stderr));
     const affected = new Set(violations.map((v) => v.method ?? "?"));
     const vCount = violations.length === 0 ? errStyler.green("0 violations") : errStyler.red(`${violations.length} violations`);
+    const aCount = advisories.length === 0 ? "" : ` \xB7 ${errStyler.yellow(`${advisories.length} advisor${advisories.length === 1 ? "y" : "ies"}`)}`;
     process.stderr.write(
-      `${errStyler.bold(errStyler.cyan(`session #${id}`))} \xB7 ${checked} checked \xB7 ${skipped} skipped (no schema) \xB7 ${vCount} in ${affected.size} method${affected.size === 1 ? "" : "s"}
+      `${errStyler.bold(errStyler.cyan(`session #${id}`))} \xB7 ${checked} checked \xB7 ${skipped} skipped (no schema) \xB7 ${vCount} in ${affected.size} method${affected.size === 1 ? "" : "s"}${aCount}
 
 `
     );
-    if (violations.length === 0) {
+    const s = createStyler(colorEnabled(process.stdout));
+    if (violations.length > 0) {
+      process.stdout.write(renderViolations(s, violations));
+    }
+    if (advisories.length > 0) {
+      if (violations.length > 0) process.stdout.write("\n");
+      process.stdout.write(renderAdvisories(s, advisories));
+    }
+    if (violations.length === 0 && advisories.length === 0) {
       process.stdout.write(errStyler.green("no violations") + "\n");
       return;
     }
-    const s = createStyler(colorEnabled(process.stdout));
-    process.stdout.write(renderViolations(s, violations));
-    process.exit(1);
+    if (violations.length > 0) process.exit(1);
   });
 }
 function renderViolations(s, violations) {
@@ -13666,13 +14117,24 @@ function renderViolations(s, violations) {
     s.cyan(truncate3(v.path, PATH_MAX)),
     s.red(v.message)
   ]);
-  return renderTable(s, COLUMNS3, body);
+  return renderTable(s, COLUMNS4, body);
+}
+function renderAdvisories(s, advisories) {
+  const heading5 = s.yellow(`${advisories.length} advisor${advisories.length === 1 ? "y" : "ies"}`) + s.dim(" \u2014 valid today, but a future ACP version will require these fields") + "\n";
+  const body = advisories.map((a) => [
+    s.dim(`#${a.seq}`),
+    truncate3(a.method ?? "\u2014", METHOD_MAX4),
+    s.dim(truncate3(a.schemaName, SCHEMA_MAX)),
+    s.yellow(truncate3(a.path, PATH_MAX)),
+    s.yellow(a.message)
+  ]);
+  return heading5 + renderTable(s, ADVISORY_COLUMNS, body);
 }
 function truncate3(s, max) {
   if (s.length <= max) return s;
   return s.slice(0, Math.max(1, max - 1)) + "\u2026";
 }
-var METHOD_MAX4, SCHEMA_MAX, PATH_MAX, COLUMNS3;
+var METHOD_MAX4, SCHEMA_MAX, PATH_MAX, COLUMNS4, ADVISORY_COLUMNS;
 var init_validate2 = __esm({
   "src/commands/validate.ts"() {
     "use strict";
@@ -13683,19 +14145,26 @@ var init_validate2 = __esm({
     METHOD_MAX4 = 28;
     SCHEMA_MAX = 28;
     PATH_MAX = 38;
-    COLUMNS3 = [
+    COLUMNS4 = [
       { title: "SEQ", align: "right" },
       { title: "METHOD", align: "left" },
       { title: "SCHEMA", align: "left" },
       { title: "PATH", align: "left" },
       { title: "ERROR", align: "left" }
     ];
+    ADVISORY_COLUMNS = [
+      { title: "SEQ", align: "right" },
+      { title: "METHOD", align: "left" },
+      { title: "SCHEMA", align: "left" },
+      { title: "FIELD", align: "left" },
+      { title: "ADVISORY", align: "left" }
+    ];
   }
 });
 
 // src/lib/help.ts
-import { homedir as homedir4 } from "os";
-function tidyHome(text, home = homedir4()) {
+import { homedir as homedir5 } from "os";
+function tidyHome(text, home = homedir5()) {
   if (!home) return text;
   const escapedHome = home.replace(/\\/g, "\\\\");
   const collapsed = text.split(escapedHome).join("~").split(home).join("~");
@@ -13857,7 +14326,7 @@ var init_help = __esm({
       },
       { title: "View", commands: ["ui", "replay"] },
       { title: "Manage", commands: ["export", "import", "delete", "backfill-metadata"] },
-      { title: "Setup", commands: ["doctor", "mcp"] }
+      { title: "Setup", commands: ["setup", "agents", "doctor", "mcp"] }
     ];
     SUMMARIES = {
       proxy: "Capture an agent's traffic through a proxy",
@@ -13876,6 +14345,8 @@ var init_help = __esm({
       import: "Import a JSON export into the store",
       delete: "Delete saved sessions permanently",
       "backfill-metadata": "Recompute session metadata columns",
+      setup: "Generate an editor config for an agent",
+      agents: "List the built-in agent shortcuts",
       doctor: "Diagnose setup and report issues",
       mcp: "Expose captures to Claude over MCP"
     };
@@ -13934,6 +14405,17 @@ var init_help = __esm({
       replay: ["acp-devtools replay 12", "acp-devtools replay --file session-12.json"],
       validate: ["acp-devtools validate 12"],
       "session-info": ["acp-devtools session-info 12"],
+      setup: [
+        "# See which agent shortcuts exist",
+        "acp-devtools agents",
+        "",
+        "# Print a Zed config block for a registry agent",
+        "acp-devtools setup junie --editor zed",
+        "",
+        "# Wrap a custom agent and write it straight into the JetBrains config",
+        "acp-devtools setup --editor jetbrains --write -- npx -y @your-scope/your-acp"
+      ],
+      agents: ["acp-devtools agents", "", "# Machine-readable", "acp-devtools agents --json"],
       doctor: ["acp-devtools doctor"],
       mcp: ["# Read-only MCP server over stdio (wire into .claude/mcp_servers.json)", "acp-devtools mcp"],
       "backfill-metadata": [
@@ -13970,6 +14452,8 @@ function buildProgram() {
   registerInspectCommand(program);
   registerSearchCommand(program);
   registerSessionInfoCommand(program);
+  registerSetupCommand(program);
+  registerAgentsCommand(program);
   registerStatsCommand(program);
   registerBackfillMetadataCommand(program);
   registerMcpCommand(program);
@@ -13981,6 +14465,7 @@ function buildProgram() {
 var init_program = __esm({
   "src/program.ts"() {
     "use strict";
+    init_agents2();
     init_backfill_metadata();
     init_delete();
     init_diff();
@@ -13996,6 +14481,7 @@ var init_program = __esm({
     init_replay2();
     init_search();
     init_session_info();
+    init_setup();
     init_stats();
     init_ui();
     init_validate2();
@@ -14100,6 +14586,8 @@ var KNOWN_SUBCOMMANDS = /* @__PURE__ */ new Set([
   "inspect",
   "search",
   "session-info",
+  "setup",
+  "agents",
   "stats",
   "validate",
   "backfill-metadata",