acp-devtools 0.4.0 → 0.5.0

package/dist/index.js

@@ -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"() {
@@ -10853,7 +10887,7 @@ var CLI_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    CLI_VERSION = "0.4.0";
+    CLI_VERSION = "0.5.0";
   }
 });
 
@@ -11668,7 +11702,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")
       },
@@ -11690,6 +11724,14 @@ function buildMcpServer(opts) {
               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 +11742,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 +11752,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(
@@ -13597,6 +13640,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 +13654,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 +13686,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 +13697,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) {
@@ -13668,11 +13728,22 @@ function renderViolations(s, violations) {
   ]);
   return renderTable(s, COLUMNS3, 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, COLUMNS3, ADVISORY_COLUMNS;
 var init_validate2 = __esm({
   "src/commands/validate.ts"() {
     "use strict";
@@ -13690,6 +13761,13 @@ var init_validate2 = __esm({
       { 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" }
+    ];
   }
 });