@fire-spark/cli 0.15.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fire-spark/cli",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Fire Spark command line: doctor and future commands",
   "type": "module",
   "bin": {

package/src/commands/doctor/client/agent.flow.ts

@@ -0,0 +1,439 @@
+import { access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import type { Copy } from "../../../core/i18n";
+import { say, textOf } from "./flow";
+import type { CheckBinding, Outcome, RunCtx } from "./runner";
+
+const text = (es: string, en: string, pt: string): Copy => {
+  return { "es-EC": es, "en-US": en, "pt-BR": pt };
+};
+
+const vars = "AGENT_SIGNING_JWKS y FIRESPARK_AGENT_LINK_SECRET.";
+const varsEn = "AGENT_SIGNING_JWKS and FIRESPARK_AGENT_LINK_SECRET.";
+const varsPt = "AGENT_SIGNING_JWKS e FIRESPARK_AGENT_LINK_SECRET.";
+const skipEs = "AGT-09 se salta: falta {field}.";
+const skipEn = "AGT-09 is skipped: {field} is missing.";
+const skipPt = "AGT-09 é pulado: falta {field}.";
+const builderEs = "AGT-09 se salta: este checkout no trae el Channel Builder.";
+const builderEn = "AGT-09 is skipped: this checkout has no Channel Builder.";
+const builderPt = "AGT-09 é pulado: este checkout não traz o Channel Builder.";
+const failEs = "AGT-09 falló en {problem}.";
+const failEn = "AGT-09 failed at {problem}.";
+const failPt = "AGT-09 falhou em {problem}.";
+const createdEs = `Se creó el canal Agent {id}. Documenta ${vars}`;
+const createdEn = `Created Agent channel {id}. Documents ${varsEn}`;
+const createdPt = `O canal Agent {id} foi criado. Documenta ${varsPt}`;
+const linkedEs = `Se enlazó el canal Agent {id}. Documenta ${vars}`;
+const linkedEn = `Linked Agent channel {id}. Documents ${varsEn}`;
+const linkedPt = `O canal Agent {id} foi vinculado. Documenta ${varsPt}`;
+
+const COPY = {
+  skip: text(skipEs, skipEn, skipPt),
+  noBuilder: text(builderEs, builderEn, builderPt),
+  fail: text(failEs, failEn, failPt),
+  created: text(createdEs, createdEn, createdPt),
+  linked: text(linkedEs, linkedEn, linkedPt)
+};
+
+interface DoctorResult {
+  ok: boolean;
+  action: "created" | "linked" | null;
+  channelId: string;
+  problem: string;
+}
+
+interface DoctorModule {
+  runAgentDoctor: (input: {
+    root: string;
+    apiUrl: string;
+    clientId: string;
+    clientSecret: string;
+    merchantId: string;
+  }) => Promise<DoctorResult>;
+}
+
+const exists = async (path: string) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const monorepoRoot = async () => {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let depth = 0; depth < 8; depth += 1) {
+    const marker = "packages/channel-builder/src/agent.doctor.ts";
+    if (await exists(join(dir, marker))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+};
+
+interface MissingCredential {
+  kind: "missing";
+  field: string;
+}
+
+interface ReadyCredential {
+  kind: "ready";
+  clientId: string;
+  clientSecret: string;
+  apiUrl: string;
+  merchantId: string;
+}
+
+const gapOf = (ctx: RunCtx): MissingCredential | ReadyCredential => {
+  const clientId = textOf(ctx.env.FIRESPARK_CLIENT_ID);
+  const clientSecret = textOf(ctx.env.FIRESPARK_CLIENT_SECRET);
+  const fromEnv = textOf(ctx.env.FIRESPARK_API_URL);
+  const fromDoctor = textOf(ctx.env.FIRESPARK_DOCTOR_API_URL);
+  const merchantEnv = textOf(ctx.env.FIRESPARK_DOCTOR_MERCHANT_ID);
+  const channel = ctx.channels.find(item => {
+    return textOf(item.api_url) && textOf(item.merchant_id);
+  });
+  const apiUrl = fromEnv || fromDoctor || textOf(channel?.api_url);
+  const merchantId = merchantEnv || textOf(channel?.merchant_id);
+  if (!clientId) return { kind: "missing", field: "FIRESPARK_CLIENT_ID" };
+  if (!clientSecret) {
+    return { kind: "missing", field: "FIRESPARK_CLIENT_SECRET" };
+  }
+  if (!apiUrl) return { kind: "missing", field: "FIRESPARK_API_URL" };
+  const merchantField = "FIRESPARK_DOCTOR_MERCHANT_ID";
+  if (!merchantId) return { kind: "missing", field: merchantField };
+  const ready = { kind: "ready" as const, clientId, clientSecret, apiUrl };
+  return { ...ready, merchantId };
+};
+
+const loadDoctor = async (root: string) => {
+  const file = join(root, "packages/channel-builder/src/agent.doctor.ts");
+  try {
+    return (await import(pathToFileURL(file).href)) as DoctorModule;
+  } catch {
+    return null;
+  }
+};
+
+const runAgent = async (ctx: RunCtx): Promise<Outcome> => {
+  const gap = gapOf(ctx);
+  if (gap.kind === "missing") {
+    return say(ctx.locale, "skip", COPY.skip, { field: gap.field });
+  }
+  const root = await monorepoRoot();
+  if (!root) return say(ctx.locale, "skip", COPY.noBuilder);
+  const doctor = await loadDoctor(root);
+  if (!doctor) return say(ctx.locale, "skip", COPY.noBuilder);
+  const b1 = { root, apiUrl: gap.apiUrl, clientId: gap.clientId };
+  const b2 = { clientSecret: gap.clientSecret, merchantId: gap.merchantId };
+  const result = await doctor.runAgentDoctor({ ...b1, ...b2 });
+  if (!result.ok) {
+    return say(ctx.locale, "fail", COPY.fail, { problem: result.problem });
+  }
+  const copy = result.action === "linked" ? COPY.linked : COPY.created;
+  return say(ctx.locale, "pass", copy, { id: result.channelId });
+};
+
+const WIDGETS = [
+  ["ui://firespark/menu", "get_menu"],
+  ["ui://firespark/product", "get_product"],
+  ["ui://firespark/cart", "build_cart"]
+] as const;
+
+const META = {
+  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+  "io.modelcontextprotocol/clientCapabilities": {}
+};
+
+const uiSkipEs = "{id} se salta: falta {field}.";
+const uiSkipEn = "{id} is skipped: {field} is missing.";
+const uiSkipPt = "{id} é pulado: falta {field}.";
+const uiChannelEs = "{id} se salta: el canal no es Agent.";
+const uiChannelEn = "{id} is skipped: the channel is not Agent.";
+const uiChannelPt = "{id} é pulado: o canal não é Agent.";
+const uiFailEs = "{id} falló: {problem}.";
+const uiFailEn = "{id} failed: {problem}.";
+const uiFailPt = "{id} falhou: {problem}.";
+const uiPassEs = "{id} leyó las vistas del comercio.";
+const uiPassEn = "{id} read the merchant views.";
+const uiPassPt = "{id} leu as vistas do comércio.";
+
+const UI_COPY = {
+  skip: text(uiSkipEs, uiSkipEn, uiSkipPt),
+  channel: text(uiChannelEs, uiChannelEn, uiChannelPt),
+  fail: text(uiFailEs, uiFailEn, uiFailPt),
+  pass: text(uiPassEs, uiPassEn, uiPassPt)
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> => {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+};
+
+const rpcText = async (response: Response) => {
+  const text = await response.text();
+  const trimmed = text.trim();
+  if (trimmed.startsWith("{")) return trimmed;
+  const line = trimmed.split("\n").find(item => item.startsWith("data:"));
+  return line ? line.slice(5).trim() : trimmed;
+};
+
+const rpc = async (
+  url: string,
+  token: string,
+  method: string,
+  params: Record<string, unknown>,
+  name?: string
+) => {
+  const headers = new Headers();
+  headers.set("authorization", `Bearer ${token}`);
+  headers.set("content-type", "application/json");
+  headers.set("accept", "application/json, text/event-stream");
+  headers.set("mcp-protocol-version", "2026-07-28");
+  headers.set("mcp-method", method);
+  if (name) headers.set("mcp-name", name);
+  const b1 = { jsonrpc: "2.0", id: 1, method };
+  const b2 = { params: { ...params, _meta: META } };
+  const body = JSON.stringify({ ...b1, ...b2 });
+  const response = await fetch(url, { method: "POST", headers, body });
+  const text = await rpcText(response);
+  const json = JSON.parse(text) as Record<string, unknown>;
+  return { status: response.status, json };
+};
+
+const endpointOf = (ctx: RunCtx) => {
+  const chosen = ctx.channels.find(item => item.template === "agent");
+  const channel = chosen ?? ctx.channels[0];
+  if (!channel || channel.template !== "agent") {
+    return { kind: "channel" as const };
+  }
+  const token = textOf(ctx.env.FIRESPARK_DOCTOR_AGENT_TOKEN);
+  if (!token)
+    return { kind: "missing" as const, field: "FIRESPARK_DOCTOR_AGENT_TOKEN" };
+  const fromEnv = textOf(ctx.env.FIRESPARK_DOCTOR_AGENT_MCP_URL);
+  const url = textOf(channel.url).replace(/\/+$/, "");
+  const merchant = textOf(channel.merchant_id);
+  let endpoint = fromEnv;
+  if (!endpoint && url.endsWith("/mcp")) endpoint = url;
+  if (!endpoint && url && merchant) {
+    endpoint = `${url}/m/${encodeURIComponent(merchant)}/mcp`;
+  }
+  if (!endpoint) return { kind: "missing" as const, field: "url" };
+  return { kind: "ready" as const, endpoint, token, channel };
+};
+
+const toolMeta = (tool: Record<string, unknown>) => {
+  const meta = isRecord(tool._meta) ? tool._meta : {};
+  const ui = isRecord(meta.ui) ? meta.ui : {};
+  return ui;
+};
+
+const runWidgets = async (ctx: RunCtx): Promise<Outcome> => {
+  const ready = endpointOf(ctx);
+  if (ready.kind === "channel") {
+    return say(ctx.locale, "skip", UI_COPY.channel, { id: "AGT-10" });
+  }
+  if (ready.kind === "missing") {
+    const skipped = { id: "AGT-10", field: ready.field };
+    return say(ctx.locale, "skip", UI_COPY.skip, skipped);
+  }
+  try {
+    const listed = await rpc(ready.endpoint, ready.token, "tools/list", {});
+    const result = isRecord(listed.json.result) ? listed.json.result : {};
+    const tools = Array.isArray(result.tools) ? result.tools : [];
+    const byName = new Map<string, Record<string, unknown>>();
+    for (const tool of tools) {
+      if (isRecord(tool) && typeof tool.name === "string") {
+        byName.set(tool.name, tool);
+      }
+    }
+    for (const [uri, name] of WIDGETS) {
+      const tool = byName.get(name);
+      const ui = tool ? toolMeta(tool) : {};
+      if (ui.resourceUri !== uri) {
+        const failed = { id: "AGT-10", problem: name };
+        return say(ctx.locale, "fail", UI_COPY.fail, failed);
+      }
+    }
+    const hidden = byName.get("get_menu_category");
+    const visibility = hidden ? toolMeta(hidden).visibility : [];
+    const appOnly = Array.isArray(visibility) && visibility.join() === "app";
+    if (!appOnly) {
+      const failed = { id: "AGT-10", problem: "get_menu_category" };
+      return say(ctx.locale, "fail", UI_COPY.fail, failed);
+    }
+    for (const [uri] of WIDGETS) {
+      const p1 = [ready.endpoint, ready.token, "resources/read"] as const;
+      const read = await rpc(...p1, { uri }, uri);
+      const body = isRecord(read.json.result) ? read.json.result : {};
+      const contents = Array.isArray(body.contents) ? body.contents : [];
+      const first = isRecord(contents[0]) ? contents[0] : {};
+      const mime = typeof first.mimeType === "string" ? first.mimeType : "";
+      const html = typeof first.text === "string" ? first.text : "";
+      if (!mime.includes("profile=mcp-app") || !html.includes('id="root"')) {
+        const failed = { id: "AGT-10", problem: uri };
+        return say(ctx.locale, "fail", UI_COPY.fail, failed);
+      }
+    }
+    return say(ctx.locale, "pass", UI_COPY.pass, { id: "AGT-10" });
+  } catch (error) {
+    const problem = error instanceof Error ? error.message : "mcp";
+    return say(ctx.locale, "fail", UI_COPY.fail, { id: "AGT-10", problem });
+  }
+};
+
+const pageOf = (json: Record<string, unknown>) => {
+  const result = isRecord(json.result) ? json.result : {};
+  const raw = result.structuredContent;
+  const structured = isRecord(raw) ? raw : {};
+  const view = isRecord(structured.view) ? structured.view : structured;
+  const products = Array.isArray(view.products) ? view.products : [];
+  const page = isRecord(view.page) ? view.page : {};
+  const total = typeof page.total === "number" ? page.total : products.length;
+  const cursor = typeof view.next_cursor === "string" ? view.next_cursor : "";
+  const handle = typeof view.handle === "string" ? view.handle : "";
+  const category = typeof view.category_id === "string" ? view.category_id : "";
+  return { products, total, cursor, handle, category };
+};
+
+const runPages = async (ctx: RunCtx): Promise<Outcome> => {
+  const ready = endpointOf(ctx);
+  if (ready.kind === "channel") {
+    return say(ctx.locale, "skip", UI_COPY.channel, { id: "AGT-11" });
+  }
+  if (ready.kind === "missing") {
+    const skipped = { id: "AGT-11", field: ready.field };
+    return say(ctx.locale, "skip", UI_COPY.skip, skipped);
+  }
+  try {
+    const storeId = textOf(ready.channel.store_id);
+    const args: Record<string, unknown> = {};
+    if (storeId) args.store_id = storeId;
+    const call = { name: "get_menu", arguments: args };
+    const p1 = [ready.endpoint, ready.token, "tools/call"] as const;
+    const menu = await rpc(...p1, call, "get_menu");
+    const first = pageOf(menu.json);
+    if (first.products.length > 24 || first.products.length === 0) {
+      const failed = { id: "AGT-11", problem: "get_menu" };
+      return say(ctx.locale, "fail", UI_COPY.fail, failed);
+    }
+    if (first.total > first.products.length && !first.cursor) {
+      const failed = { id: "AGT-11", problem: "cursor" };
+      return say(ctx.locale, "fail", UI_COPY.fail, failed);
+    }
+    if (first.cursor && first.handle && first.category) {
+      const a1 = { handle: first.handle, category_id: first.category };
+      const a2 = { cursor: first.cursor, limit: 24 };
+      const call2 = { name: "get_menu_category", arguments: { ...a1, ...a2 } };
+      const p2 = [ready.endpoint, ready.token, "tools/call"] as const;
+      const more = await rpc(...p2, call2, "get_menu_category");
+      const next = pageOf(more.json);
+      if (next.products.length === 0) {
+        const failed = { id: "AGT-11", problem: "get_menu_category" };
+        return say(ctx.locale, "fail", UI_COPY.fail, failed);
+      }
+    }
+    const sample = first.products.find(isRecord);
+    const query = sample && typeof sample.name === "string" ? sample.name : "";
+    const call3 = { name: "search_menu", arguments: { ...args, query } };
+    const p3 = [ready.endpoint, ready.token, "tools/call"] as const;
+    const search = await rpc(...p3, call3, "search_menu");
+    const found = pageOf(search.json);
+    const hit = found.products.some(item => {
+      return isRecord(item) && item.id === sample?.id;
+    });
+    if (!query || !hit) {
+      const failed = { id: "AGT-11", problem: "search_menu" };
+      return say(ctx.locale, "fail", UI_COPY.fail, failed);
+    }
+    return say(ctx.locale, "pass", UI_COPY.pass, { id: "AGT-11" });
+  } catch (error) {
+    const problem = error instanceof Error ? error.message : "mcp";
+    return say(ctx.locale, "fail", UI_COPY.fail, { id: "AGT-11", problem });
+  }
+};
+
+interface AuthCheck {
+  id: string;
+  status: "pass" | "fail" | "skip";
+  detail: string;
+}
+
+interface AuthModule {
+  runAgentAuthChecks: () => Promise<AuthCheck[]>;
+}
+
+let authChecks: Promise<AuthCheck[]> | null = null;
+
+const loadAuth = async (): Promise<AuthModule | null> => {
+  const root = await monorepoRoot();
+  if (!root) return null;
+  const file = join(root, "sdk/ai/src/auth/doctor.ts");
+  try {
+    return (await import(pathToFileURL(file).href)) as AuthModule;
+  } catch {
+    return null;
+  }
+};
+
+const authSkipEs = "{id} se salta: falta {field}.";
+const authSkipEn = "{id} is skipped: {field} is missing.";
+const authSkipPt = "{id} é pulado: falta {field}.";
+const missEsA = "{id} se salta: este checkout no trae";
+const missEsB = " el servidor de autorización.";
+const authMissEs = `${missEsA}${missEsB}`;
+const missEn = "{id} is skipped: this checkout has no authorization server.";
+const missPtA = "{id} é pulado: este checkout não traz";
+const missPtB = " o servidor de autorização.";
+const authMissPt = `${missPtA}${missPtB}`;
+const authFailEs = "{id} falló en {detail}.";
+const authFailEn = "{id} failed at {detail}.";
+const authFailPt = "{id} falhou em {detail}.";
+const authPassEs = "{id} pasó.";
+const authPassEn = "{id} passed.";
+const authPassPt = "{id} passou.";
+
+const authCopy = {
+  skip: text(authSkipEs, authSkipEn, authSkipPt),
+  missing: text(authMissEs, missEn, authMissPt),
+  fail: text(authFailEs, authFailEn, authFailPt),
+  pass: text(authPassEs, authPassEn, authPassPt)
+};
+
+const runAuth = (id: string) => {
+  return async (ctx: RunCtx): Promise<Outcome> => {
+    const auth = await loadAuth();
+    if (!auth) return say(ctx.locale, "skip", authCopy.missing, { id });
+    authChecks ??= auth.runAgentAuthChecks();
+    const found = (await authChecks).find(item => item.id === id);
+    if (!found) {
+      const miss = { id, detail: id };
+      return say(ctx.locale, "fail", authCopy.fail, miss);
+    }
+    if (found.status === "skip") {
+      const skipped = { id, field: found.detail };
+      return say(ctx.locale, "skip", authCopy.skip, skipped);
+    }
+    if (found.status === "fail") {
+      const failed = { id, detail: found.detail };
+      return say(ctx.locale, "fail", authCopy.fail, failed);
+    }
+    return say(ctx.locale, "pass", authCopy.pass, { id });
+  };
+};
+
+export const AGENT_BINDINGS: Record<string, CheckBinding> = {
+  "AGT-09": { kind: "script", run: runAgent },
+  "AGT-10": { kind: "script", run: runWidgets },
+  "AGT-11": { kind: "script", run: runPages },
+  "AGT-12": { kind: "script", run: runAuth("AGT-12") },
+  "AGT-13": { kind: "script", run: runAuth("AGT-13") },
+  "AGT-14": { kind: "script", run: runAuth("AGT-14") },
+  "AGT-15": { kind: "script", run: runAuth("AGT-15") },
+  "AGT-16": { kind: "script", run: runAuth("AGT-16") },
+  "AGT-17": { kind: "script", run: runAuth("AGT-17") },
+  "AGT-18": { kind: "script", run: runAuth("AGT-18") }
+};

package/src/commands/doctor/client/catalog.json

@@ -1582,5 +1582,135 @@
     "notes": "Los datos operativos viven en el YAML de config (por ejemplo .bembos.doctor.yml) o en las flags equivalentes, no en el channel-manifest. El manifest cubre la identidad del canal. Un canal se trata como desplegado solo si está marcado así en esa config; tener manifest no implica que ya se desplegó. Si el YAML no existe al arrancar, la CLI auto-invoca init y no dispara este error. Fixable es No para que --fix no invente URLs ni IDs.",
     "verification": "deterministic",
     "howTo": "Script local: invocar la CLI con un canal marcado como desplegado y sin URL pública (y por separado sin store-id, fulfillment-id o credenciales) y afirmar que el código de salida no es 0, que no se corrió ningún check y que el error nombra el campo y el canal. Repetir con un canal nunca desplegado, solo con identidad, y afirmar que no aparece este error por falta de URLs u otros datos operativos."
+  },
+  {
+    "id": "AGT-09",
+    "description": "Channel Builder genera el template AGENT.",
+    "acceptance": "Al invocar firespark doctor run AGT-09, el check genera el template AGENT con el Channel Builder en un directorio temporal. El resultado incluye la ruta MCP, la página de pago, el checkout, las pantallas de órdenes y de detalle de orden, el servidor de autorización montado en /authorize, y documenta AGENT_SIGNING_JWKS (JWK set privado) y FIRESPARK_AGENT_LINK_SECRET (firma los links de pago). El merchantId, el issuer y el jwksUrl salen del canal, no de un arreglo en env. Si el comercio ya tiene un canal AGENT, lo enlaza; si no, lo crea por la API de integrations. El check se salta solo cuando falta una credencial real: FIRESPARK_CLIENT_ID, FIRESPARK_CLIENT_SECRET, la URL de la API o el id del comercio. No se salta por precaución.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": true,
+    "area": "sdk",
+    "notes": "El template es un extracto del web template (auth, checkout, órdenes y detalle) más las rutas MCP y de pago del server template, y el paquete @fire-spark/ai. No copia el resto del sitio.",
+    "verification": "deterministic",
+    "howTo": "Script local: con FIRESPARK_CLIENT_ID, FIRESPARK_CLIENT_SECRET, la URL de la API y el id del comercio, correr firespark doctor run AGT-09. Afirmar que el canal AGENT se crea o se enlaza y que el directorio temporal trae la ruta MCP, la página de pago, checkout, órdenes, detalle, los widgets, /authorize y AGENT_SIGNING_JWKS más FIRESPARK_AGENT_LINK_SECRET en .env.example, README y docs. Sin una de esas credenciales, el check se salta y nombra el dato que falta."
+  },
+  {
+    "id": "AGT-10",
+    "description": "Las vistas MCP del canal Agent se sirven como HTML mcp-app y las tools declaran _meta.ui.",
+    "acceptance": "resources/read de ui://firespark/menu, ui://firespark/product y ui://firespark/cart responde mimeType text/html;profile=mcp-app con el HTML de la vista. get_menu, get_product, build_cart, validate_cart y search_menu traen _meta.ui.resourceUri. get_menu_category queda visible solo para la app.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": false,
+    "area": "menu",
+    "notes": "Necesita FIRESPARK_DOCTOR_AGENT_TOKEN y la URL del MCP (url del canal o FIRESPARK_DOCTOR_AGENT_MCP_URL). Se salta si el canal no es agent o falta el token.",
+    "verification": "deterministic",
+    "howTo": "Registra el preview como servidor MCP y corre firespark doctor run AGT-10 con el token del cliente. Afirmar el mime mcp-app y _meta.ui."
+  },
+  {
+    "id": "AGT-11",
+    "description": "get_menu pagina el menú real del comercio y search_menu encuentra un producto de esa página.",
+    "acceptance": "get_menu devuelve como máximo 24 productos. Si hay más, next_cursor y get_menu_category traen la página siguiente. search_menu con el nombre de un producto de la primera página lo devuelve.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": false,
+    "area": "menu",
+    "notes": "Usa el mismo token y la misma URL que AGT-10, contra el menú del comercio. No manda el menú completo.",
+    "verification": "deterministic",
+    "howTo": "Con el MCP del preview y FIRESPARK_DOCTOR_AGENT_TOKEN, correr firespark doctor run AGT-11. Afirmar la página de 24, el cursor y la búsqueda."
+  },
+  {
+    "id": "AGT-12",
+    "description": "El servidor de autorización publica metadata OAuth.",
+    "acceptance": "Al invocar firespark doctor run AGT-12, el check levanta el servidor de autorización real y pide /.well-known/oauth-authorization-server. La metadata trae issuer, JWKS, /authorize, /token, /register, /revoke, PKCE solo S256, iss en la respuesta y CIMD. Si FIRESPARK_DOCTOR_AGENT_ISSUER está definido, también pide esa metadata en vivo y falla si el issuer no coincide. Se salta solo si este checkout no trae el servidor.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": true,
+    "area": "sdk",
+    "notes": "El mismo oidc-provider que monta el template. No hay un token fijo.",
+    "verification": "deterministic",
+    "howTo": "Correr firespark doctor run AGT-12. Afirmar pass. Con FIRESPARK_DOCTOR_AGENT_ISSUER, afirmar que un issuer distinto falla."
+  },
+  {
+    "id": "AGT-13",
+    "description": "El authorization code exige PKCE S256.",
+    "acceptance": "Al invocar firespark doctor run AGT-13, el check registra un cliente, rechaza /authorize sin code_challenge y completa el canje con S256. Se salta solo si este checkout no trae el servidor.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": true,
+    "area": "sdk",
+    "notes": "plain no está en code_challenge_methods_supported.",
+    "verification": "deterministic",
+    "howTo": "Correr firespark doctor run AGT-13 y afirmar pass."
+  },
+  {
+    "id": "AGT-14",
+    "description": "DCR respeta la política de dominios y CIMD bloquea direcciones privadas.",
+    "acceptance": "Al invocar firespark doctor run AGT-14, el check rechaza el registro de un redirect en un dominio bloqueado y rechaza un client_id CIMD en 127.0.0.1. Si FIRESPARK_DOCTOR_CIMD_URL apunta a un documento público, también acepta ese cliente. Se salta solo si este checkout no trae el servidor.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": true,
+    "area": "sdk",
+    "notes": "El fetch de CIMD es https, sin redirects a redes privadas, con límite de tamaño y tiempo.",
+    "verification": "deterministic",
+    "howTo": "Correr firespark doctor run AGT-14. Sin FIRESPARK_DOCTOR_CIMD_URL igual corre el rechazo. Con esa URL, el documento público tiene que pasar."
+  },
+  {
+    "id": "AGT-15",
+    "description": "El access token trae aud del MCP, iss del comercio y customer_id igual a sub.",
+    "acceptance": "Al invocar firespark doctor run AGT-15, el check completa login, consentimiento y canje. El JWT tiene aud igual a la URL MCP, iss igual al issuer, y sub y customer_id iguales. Se salta solo si este checkout no trae el servidor.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": true,
+    "area": "sdk",
+    "notes": "El exchange de Spark usa sub como customer id. Por eso los dos claims coinciden.",
+    "verification": "deterministic",
+    "howTo": "Correr firespark doctor run AGT-15 y afirmar pass."
+  },
+  {
+    "id": "AGT-16",
+    "description": "Reusar un refresh token revoca la familia.",
+    "acceptance": "Al invocar firespark doctor run AGT-16, el check rota el refresh token y luego rechaza el token viejo y el rotado. Se salta solo si este checkout no trae el servidor.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": true,
+    "area": "sdk",
+    "notes": "La revocación también está en /revoke.",
+    "verification": "deterministic",
+    "howTo": "Correr firespark doctor run AGT-16 y afirmar pass."
+  },
+  {
+    "id": "AGT-17",
+    "description": "La pantalla de consentimiento está en español de Ecuador.",
+    "acceptance": "Al invocar firespark doctor run AGT-17, el check abre el consentimiento real y afirma que nombra los scopes en palabras llanas (ver el menú, crear pedidos) y que usa aquí. Se salta solo si este checkout no trae el servidor.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": true,
+    "area": "sdk",
+    "notes": "Crear un pedido sigue pidiendo confirmar el total en la conversación.",
+    "verification": "deterministic",
+    "howTo": "Correr firespark doctor run AGT-17 y afirmar pass."
+  },
+  {
+    "id": "AGT-18",
+    "description": "El adaptador de Firebase verifica el ID token y toma customer_id.",
+    "acceptance": "Al invocar firespark doctor run AGT-18, el check verifica un ID token real de Firebase contra el JWKS de securetoken y exige customer_id o, si no viene, el sub. Se salta solo cuando falta FIRESPARK_DOCTOR_FIREBASE_PROJECT_ID o FIRESPARK_DOCTOR_FIREBASE_ID_TOKEN. No se salta por precaución si los dos están.",
+    "channels": ["agent"],
+    "platforms": ["web"],
+    "fixable": false,
+    "required": true,
+    "area": "sdk",
+    "notes": "El dominio del servidor de autorización tiene que estar en los dominios autorizados de Firebase.",
+    "verification": "deterministic",
+    "howTo": "Sin las dos variables, el check se salta y nombra la que falta. Con un ID token real y el project id, afirmar pass."
   }
 ]

package/src/commands/doctor/client/catalog.ts

@@ -89,7 +89,7 @@ for (const [slug, copy] of Object.entries(AREA_LABELS)) {
 }
 
 const channelA = ["kiosk", "pos", "web", "app", "chat"] as const;
-const channelB = ["call-center", "server", "dashboard"] as const;
+const channelB = ["call-center", "server", "dashboard", "agent"] as const;
 const CHANNELS = new Set([...channelA, ...channelB]);
 
 const PLATFORMS = new Set(["web", "android", "ios", "dashboard"]);

package/src/commands/doctor/client/options.ts

@@ -22,9 +22,9 @@ export const CLIENT_OPTIONS: OptionSpec[] = [
     name: "channel",
     kind: "string",
     description: text(
-      "Filtra por canal: kiosk, pos, web, app, chat, call-center, server, dashboard.",
-      "Filter by channel: kiosk, pos, web, app, chat, call-center, server, dashboard.",
-      "Filtra por canal: kiosk, pos, web, app, chat, call-center, server, dashboard."
+      "Filtra por canal: kiosk, pos, web, app, agent, chat, call-center, server, dashboard.",
+      "Filter by channel: kiosk, pos, web, app, agent, chat, call-center, server, dashboard.",
+      "Filtra por canal: kiosk, pos, web, app, agent, chat, call-center, server, dashboard."
     )
   }),
   option({

package/src/commands/doctor/client/runner.ts

@@ -3,6 +3,7 @@ import { translate } from "../../../core/i18n";
 import type { Output } from "../../../core/output";
 import type { Redactor } from "../../../core/redact";
 import { ADMIN_BINDINGS } from "./admin.flow";
+import { AGENT_BINDINGS } from "./agent.flow";
 import type { CatalogCheck } from "./catalog";
 import { CHECKOUT_BINDINGS } from "./checkout.flow";
 import { CONTENT_BINDINGS } from "./content.flow";
@@ -113,7 +114,8 @@ export const BINDINGS: Record<string, CheckBinding> = {
   ...CONTENT_BINDINGS,
   ...STORE_BINDINGS,
   ...OPS_BINDINGS,
-  ...ADMIN_BINDINGS
+  ...ADMIN_BINDINGS,
+  ...AGENT_BINDINGS
 };
 
 export const runOne = async (