synthesisui 0.16.243 → 0.16.244

package/dist/agent-provenance.js

@@ -0,0 +1,92 @@
+/**
+ * DE ONDE VEIO A RESPOSTA - e é um DADO, não uma frase (dono, 18/08).
+ *
+ * O pedido veio com a razão embutida: *"eu trataria a linha Source como algo
+ * estrutural mesmo, não só visual. Isso pode virar uma métrica de maturidade
+ * depois - porcentagem de respostas por receita, por composição, por
+ * improviso."*
+ *
+ * Então a procedência nasce como estrutura e o texto é DERIVADO dela. O
+ * contrário - escrever a frase à mão em cada resposta - produz duas verdades no
+ * dia em que uma delas for editada, e a que vai para a métrica é sempre a que
+ * ninguém leu.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * O QUE CADA KIND SIGNIFICA, e a fronteira é a GARANTIA
+ *
+ *   contract   veio do que este sistema declara - receita, token, regra,
+ *              vocabulário. A plataforma responde por isso.
+ *   composed   montado a partir de camadas porque não havia receita para o
+ *              pedido. Vale, e vale menos que um contrato. (Nasce com o
+ *              compose_context; hoje nada devolve isto, e é de propósito -
+ *              um kind que ninguém emite é um número que mente por otimismo.)
+ *   pointer    um ponteiro para conhecimento de terceiro. Não é nosso, não é
+ *              garantido, e a resposta diz o pacote. Mesma gramática que a
+ *              plataforma já usa: "3rd-party · <pacote>".
+ *   none       este sistema não tinha nada para o pedido. É o kind mais
+ *              valioso dos quatro: é ele que mede o improviso, e é o evento
+ *              que a plataforma não contava.
+ *
+ * A TAXA DE IMPROVISO é `none` sobre o total, e ela é a pergunta que decide se
+ * a composição vale ser construída - respondida com dado em vez de sensação.
+ */
+/**
+ * A LINHA QUE O AGENTE E A PESSOA LEEM - derivada, nunca escrita à mão.
+ *
+ * Ela serve dois leitores de uma vez: o dev sabe o quanto confiar no que
+ * acabou de receber, e o agente sabe se está pisando em contrato ou em
+ * composição. Um agente que não sabe a diferença trata as duas com a mesma
+ * confiança, e é assim que uma suposição nossa entra no repositório dele com
+ * cara de regra.
+ */
+export function sourceLine(source) {
+    const label = source.kind === "pointer"
+        ? "3rd-party pointer"
+        : source.kind === "none"
+            ? "none"
+            : source.kind;
+    return source.detail
+        ? `Source: ${label} · ${source.detail}`
+        : `Source: ${label}`;
+}
+/**
+ * O texto com a procedência colada no fim - uma linha em branco antes, para
+ * ela não se misturar com a última frase da resposta.
+ */
+export function withSource(answer) {
+    return `${answer.body}\n\n${sourceLine(answer.source)}`;
+}
+/**
+ * O VALOR GRAVADO, e o prefixo existe para o eixo ser legível numa tabela que
+ * já carrega outra coisa.
+ *
+ * `agent_reads.action` é `text` sem CHECK no banco (medido em produção), então
+ * um valor novo não custa migração - e uma coluna nova custaria a tabela
+ * inteira até a migração rodar. `src-` marca de qual eixo a linha fala:
+ * `describe`/`add` são gesto, `tool` é chamada, `src-*` é procedência.
+ *
+ * E UMA LACUNA LEVA O MOTIVO NO PRÓPRIO VALOR: `src-none-recipe`. Assim a
+ * pergunta agregada continua sendo um `like 'src-none%'` e a pergunta por
+ * motivo é a mesma consulta com o valor inteiro - sem coluna nova, e sem
+ * perder o total.
+ *
+ * Recebe a procedência INTEIRA e não o `kind`: com o kind sozinho, o motivo
+ * seria um segundo argumento que alguém esquece, e a linha gravada voltaria a
+ * ser um `none` cego.
+ */
+export function provenanceAction(source) {
+    return source.kind === "none"
+        ? `src-none-${source.reason}`
+        : `src-${source.kind}`;
+}
+/**
+ * O NOME DA FERRAMENTA COMO A TABELA O GUARDA.
+ *
+ * A coluna `component` aceita `^[a-z][a-z0-9-]*$` na rota - a mesma forma de um
+ * slug de receita. As ferramentas são snake_case, então elas viajam em
+ * kebab-case; sem isto o ping seria recusado com 400 e a instrumentação
+ * silenciaria justamente na ferramenta nova.
+ */
+export function toolSlug(tool) {
+    return tool.replace(/_/g, "-").toLowerCase();
+}

package/dist/commands/mcp.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { provenanceAction, toolSlug, withSource, } from "../agent-provenance.js";
 import { pinnedHookVersion } from "../agent-wiring.js";
 import { readToken, resolveRegistry } from "../config.js";
 import { readEvents } from "../doctor/ledger.js";
@@ -14,6 +15,16 @@ import { installedSlug, remeasure } from "./sync.js";
 const send = (msg) => {
     process.stdout.write(`${JSON.stringify(msg)}\n`);
 };
+/**
+ * A RESPOSTA QUE VEIO DO CONTRATO - o atalho, porque é o caso comum.
+ *
+ * `detail` fica de fora quando a própria resposta já nomeia a fonte (o token,
+ * o componente, a versão): repetir aquilo na linha de procedência é ruído.
+ */
+const fromContract = (body, detail) => ({
+    body,
+    source: { kind: "contract", ...(detail ? { detail } : null) },
+});
 /** A tool result is always text: readable by the model, and by a person
  *  watching the transcript when something goes wrong. */
 const text = (body, isError = false) => ({
@@ -254,7 +265,10 @@ export const MCP_TOOL_COUNT = TOOLS.length;
 async function checkFile(root, path) {
     const { table } = await loadSystem(root);
     if (table.byName.size === 0)
-        return "No design system installed here, so there is nothing to check against. Run `synthesisui init` or `synthesisui adopt`.";
+        return {
+            body: "No design system installed here, so there is nothing to check against. Run `synthesisui init` or `synthesisui adopt`.",
+            source: { kind: "none", reason: "system", detail: "no system installed" },
+        };
     const scope = resolve(root, path);
     const reports = [];
     for await (const file of walkAll([scope])) {
@@ -263,7 +277,7 @@ async function checkFile(root, path) {
             reports.push(scanSource(relative(root, file), src, table));
     }
     if (reports.length === 0)
-        return `Nothing readable at ${path}.`;
+        return fromContract(`Nothing readable at ${path}.`);
     const d = diagnose(reports);
     const out = [
         `${table.name ?? table.slug}: ${d.coverage}% of design values come from the system.`,
@@ -284,12 +298,16 @@ async function checkFile(root, path) {
     }
     if (d.findings.length === 0 && phantoms.length === 0)
         out.push("", "Nothing to fix here.");
-    return out.join("\n");
+    return fromContract(out.join("\n"));
 }
 async function findToken(root, value) {
     const { table } = await loadSystem(root);
-    if (table.byName.size === 0)
-        return "No design system installed here.";
+    if (table.byName.size === 0) {
+        return {
+            body: "No design system installed here.",
+            source: { kind: "none", reason: "system", detail: "no system installed" },
+        };
+    }
     /**
      * O NOME DELE PRIMEIRO, como no doctor (`nameToWrite`): `loadSystem` já devolve a tabela COM os
      * aliases dele (`withTheirNames`) e este era o único leitor que nunca os consultava. Sem o `kind`
@@ -306,16 +324,27 @@ async function findToken(root, value) {
     const exact = tokenFor(table, value);
     if (exact) {
         const shown = theirNameFor(value) ?? exact;
-        return `${value} is ${shown} in this project. Use var(${shown}).`;
+        return fromContract(`${value} is ${shown} in this project. Use var(${shown}).`);
     }
     const near = nearestToken(table, value);
     if (near) {
         const shown = theirNameFor(near.value) ?? near.name;
-        return `No token holds ${value}. The closest is ${shown} at ${near.value}. If that is what you meant, use it - if it genuinely is not, say so rather than inventing a token.`;
+        /** Perto não é o valor: o sistema NÃO tem este, e a métrica precisa saber. */
+        return {
+            body: `No token holds ${value}. The closest is ${shown} at ${near.value}. If that is what you meant, use it - if it genuinely is not, say so rather than inventing a token.`,
+            source: {
+                kind: "none",
+                reason: "token",
+                detail: `no token for ${value}`,
+            },
+        };
     }
     // Same words the managed block uses. A refusal is only useful if it is the
     // same refusal every time.
-    return `No token in this system holds ${value}, and nothing is close. Do NOT invent one. Say which value you need and what you would call it, and let a person decide.`;
+    return {
+        body: `No token in this system holds ${value}, and nothing is close. Do NOT invent one. Say which value you need and what you would call it, and let a person decide.`,
+        source: { kind: "none", reason: "token", detail: `no token for ${value}` },
+    };
 }
 /**
  * A DOUTRINA DO SISTEMA - as regras e a filosofia, servidas em vez de materializadas.
@@ -801,18 +830,28 @@ async function validateRecipes(root, entries) {
  * had 26 names against a catalogue of 41.
  */
 /**
- * O CONTADOR DO AGENTE, fire-and-forget: a tela do UI Kit mostra "vezes que esta receita
- * foi consultada pelo Agente", e este é o único ponto onde a consulta acontece de
- * verdade. Nunca bloqueia a resposta: sem sessão ou sem rede, não conta e não quebra -
- * telemetria que atrasa a ferramenta é telemetria que alguém desliga.
+ * O CONTADOR DO AGENTE, fire-and-forget e agora CENTRAL.
+ *
+ * Ele nasceu para uma tela: o UI Kit mostra "vezes que esta receita foi consultada pelo
+ * Agente". E era chamado à mão em duas ferramentas de treze, o que quer dizer que onze
+ * ferramentas nunca contaram nada - inclusive a única que sabe dizer que o sistema NÃO
+ * tinha o que foi pedido.
+ *
+ * Agora o `callTool` o chama uma vez, para toda ferramenta, com a procedência da
+ * resposta. O dono foi explícito sobre por que centralizar (18/08): *"isso vira
+ * comportamento padrão e não depende de disciplina futura."* Um contador chamado dentro
+ * de um `case` é um contador que a próxima ferramenta esquece.
+ *
+ * Nunca bloqueia a resposta: sem sessão ou sem rede, não conta e não quebra - telemetria
+ * que atrasa a ferramenta é telemetria que alguém desliga.
  */
-function countAgentRead(root, component, action, 
+function recordAgentCall(root, call, 
 /** A versão que está reportando - ver `repoStateOf`. Ausente = não reporta estado. */
 cli) {
     void (async () => {
         try {
             const token = await readToken();
-            if (!token || !component)
+            if (!token)
                 return;
             // O slug vem do .lock do sistema instalado - a mesma resolução do sync.
             const dsDir = join(root, "_synthesisui", "ds");
@@ -853,8 +892,10 @@ cli) {
                  */
                 body: JSON.stringify({
                     slug,
-                    component,
-                    action,
+                    tool: toolSlug(call.tool),
+                    source: provenanceAction(call.source),
+                    ...(call.component ? { component: call.component } : {}),
+                    ...(call.action ? { action: call.action } : {}),
                     ...(repo ? { repo } : {}),
                 }),
             });
@@ -912,7 +953,22 @@ async function describeComponent(root, name) {
             break;
     }
     if (!recipe) {
-        return `This system has no component called "${name}". Run list_components to see what it does have - and if nothing covers what you need, file request_component rather than writing one from scratch.`;
+        /**
+         * O EVENTO MAIS VALIOSO DA PLATAFORMA, e até 18/08 ele não era contado.
+         *
+         * Aqui é onde o agente descobre que vai ter que improvisar. A frase já
+         * existia; o que não existia era o REGISTRO - então ninguém sabia quantas
+         * vezes, nem para quê. É este número que decide se compor conhecimento
+         * vale ser construído, e para quais famílias primeiro.
+         */
+        return {
+            body: `This system has no component called "${name}". Run list_components to see what it does have - and if nothing covers what you need, file request_component rather than writing one from scratch.`,
+            source: {
+                kind: "none",
+                reason: "recipe",
+                detail: `no recipe for "${name}"`,
+            },
+        };
     }
     const out = [
         `${name}${recipe.description ? ` - ${recipe.description}` : ""}`,
@@ -1036,51 +1092,98 @@ async function describeComponent(root, name) {
     if (laws.length === 0 && needed.length === 0) {
         out.push("", "No rules govern this component yet. Build with it, and if you find yourself working around it, file request_component with the reasoning.");
     }
-    return out.join("\n");
+    return fromContract(out.join("\n"));
 }
 async function addComponent(root, name) {
     const { table } = await loadSystem(root);
-    if (!table.slug)
-        return "No design system installed here.";
+    if (!table.slug) {
+        return {
+            body: "No design system installed here.",
+            source: { kind: "none", reason: "system", detail: "no system installed" },
+        };
+    }
     const { out } = await capturing(() => component(table.slug, name, { dir: root }));
-    return `${out}\n\nIt is real code in this project now - import it and extend it rather than writing your own.`;
+    return fromContract(`${out}\n\nIt is real code in this project now - import it and extend it rather than writing your own.`);
 }
 // ── The protocol ─────────────────────────────────────────────────────────────
+/**
+ * AS FERRAMENTAS QUE FALAM DE UM COMPONENTE PELO NOME - as únicas cujo alvo é
+ * um slug de receita, e por isso as únicas que gravam o alvo.
+ *
+ * Um valor como `#2563eb` (o alvo de `find_token`) não é nome de componente e
+ * seria recusado pela rota, que valida a coluna como slug. Então o alvo só
+ * viaja quando é um: para o resto, o eixo da procedência é a própria
+ * ferramenta.
+ */
+const BY_COMPONENT = {
+    describe_component: "describe",
+    add_component: "add",
+};
+/**
+ * O ÚNICO PONTO DE INSTRUMENTAÇÃO - e é isto que o dono pediu (18/08): *"vira
+ * comportamento padrão e não depende de disciplina futura."*
+ *
+ * A ferramenta responde, a chamada é registrada com a procedência daquela
+ * resposta, e a linha `Source:` é colada ao texto a partir do MESMO dado que
+ * foi gravado. Não há como o número e a frase discordarem, porque não há duas
+ * fontes.
+ *
+ * Uma ferramenta nova entra no switch e passa a contar sem tocar nesta função.
+ */
 async function callTool(root, name, args, 
-/** A versão que reporta o estado do repo no ping - ver `countAgentRead`. */
+/** A versão que reporta o estado do repo no ping - ver `repoStateOf`. */
 cli) {
+    const answer = await runTool(root, name, args);
+    const gesture = BY_COMPONENT[name];
+    const target = gesture
+        ? String(args.name ?? "")
+            .trim()
+            .toLowerCase()
+        : "";
+    recordAgentCall(root, {
+        tool: name,
+        source: answer.source,
+        ...(gesture ? { action: gesture } : {}),
+        ...(target ? { component: target } : {}),
+    }, cli);
+    return text(withSource(answer), answer.isError);
+}
+/**
+ * O SWITCH PURO - ele resolve a ferramenta e devolve a resposta COM a
+ * procedência. Nenhuma linha dele conta nada: quem instrumenta é `callTool`,
+ * uma vez, para todas.
+ */
+async function runTool(root, name, args) {
     switch (name) {
         case "check_file":
-            return text(await checkFile(root, String(args.path ?? ".")));
+            return checkFile(root, String(args.path ?? "."));
         case "find_token":
-            return text(await findToken(root, String(args.value ?? "")));
+            return findToken(root, String(args.value ?? ""));
         case "system_doctrine":
-            return text(await systemDoctrine(root));
+            return fromContract(await systemDoctrine(root));
         case "list_components":
-            return text(await listComponents(root));
+            return fromContract(await listComponents(root));
         case "describe_component":
-            countAgentRead(root, String(args.name ?? ""), "describe", cli);
-            return text(await describeComponent(root, String(args.name ?? "")));
+            return describeComponent(root, String(args.name ?? ""));
         case "add_component":
-            countAgentRead(root, String(args.name ?? ""), "add", cli);
-            return text(await addComponent(root, String(args.name ?? "")));
+            return addComponent(root, String(args.name ?? ""));
         case "playbook": {
             const skill = String(args?.skill ?? "");
             const section = args?.section ? String(args.section) : undefined;
-            return text(await playbook(skill, section));
+            return fromContract(await playbook(skill, section));
         }
         case "recipe_vocabulary":
-            return text(await recipeVocabulary());
+            return fromContract(await recipeVocabulary());
         case "validate_recipe": {
             // Same resolution as the batch: an `at` the validator cannot see reads as
             // an empty node and earns a false floor verdict (dono, 01/08).
             const [only] = await resolveAtNodes(root, [
                 { name: String(args.name ?? "this component"), recipe: args.recipe },
             ]);
-            return text(await validateRecipe(String(args.name ?? "this component"), only?.recipe ?? args.recipe));
+            return fromContract(await validateRecipe(String(args.name ?? "this component"), only?.recipe ?? args.recipe));
         }
         case "validate_recipes":
-            return text(await validateRecipes(root, Array.isArray(args.recipes)
+            return fromContract(await validateRecipes(root, Array.isArray(args.recipes)
                 ? args.recipes
                 : []));
         case "request_component": {
@@ -1091,7 +1194,7 @@ cli) {
                 considered: args.considered ? String(args.considered) : undefined,
                 file: args.file ? String(args.file) : undefined,
             });
-            return text(`Filed as ${r.id}. It shows up in \`synthesisui doctor\` until a person authors it or closes it - keep building with your workaround, and say in your summary that the request exists.`);
+            return fromContract(`Filed as ${r.id}. It shows up in \`synthesisui doctor\` until a person authors it or closes it - keep building with your workaround, and say in your summary that the request exists.`);
         }
         case "refresh_system": {
             /**
@@ -1111,10 +1214,10 @@ cli) {
              */
             const slug = await installedSlug(root);
             if (!slug)
-                return text("No system installed here that belongs to a dashboard row, so there is nothing to refresh. `synthesisui add <slug>` installs one; an adopted system is described here and owned elsewhere.");
+                return fromContract("No system installed here that belongs to a dashboard row, so there is nothing to refresh. `synthesisui add <slug>` installs one; an adopted system is described here and owned elsewhere.");
             const token = await readToken();
             if (!token)
-                return text("Not signed in, so nothing could be sent. A person has to run `synthesisui login` once in the terminal - it opens a browser, and I cannot complete it for them.");
+                return fromContract("Not signed in, so nothing could be sent. A person has to run `synthesisui login` once in the terminal - it opens a browser, and I cannot complete it for them.");
             const { out } = await capturing(() => remeasure({
                 root,
                 base: resolveRegistry(),
@@ -1137,7 +1240,7 @@ cli) {
             const behind = pinned && pinned !== VERSION ? pinned : null;
             const said = out.trim() ||
                 "Nothing was reported by the refresh - which means it found nothing to measure.";
-            return text(behind
+            return fromContract(behind
                 ? `${said}\n\nUPDATE THE DESIGN SYSTEM BEFORE CONTINUING.\nThe check that runs after your writes is pinned to ${behind} and these tools are ${VERSION}.\n\n  npx synthesisui@latest connect\n\nAsk the person, run it for them, and then say this: close and reopen the editor. The hook and the tools only rewire on a new session, so nothing you write before that is checked by the reader you are holding.`
                 : said);
         }
@@ -1159,7 +1262,7 @@ cli) {
                 file: args.file ? String(args.file) : undefined,
                 ...(area ? { area } : null),
             });
-            return text(area
+            return fromContract(area
                 ? `Filed as ${r.id} and routed to the synthesisui platform team - the system's contract already promises this and the shipped css does not deliver it. No one needs to act: it closes itself when an update lands. Keep the quiet base meanwhile.`
                 : `Filed as ${r.id}. Do not add the token yourself - the request shows up in \`synthesisui doctor\` for a person to decide.`);
         }
@@ -1179,10 +1282,14 @@ cli) {
                 considered: args.considered ? String(args.considered) : undefined,
                 file: args.file ? String(args.file) : undefined,
             });
-            return text(`Filed as ${r.id}. Do not adopt the convention as if it were a rule - it shows up in \`synthesisui doctor\` and travels to the system's queue, for the owner to make it a rule or decline it.`);
+            return fromContract(`Filed as ${r.id}. Do not adopt the convention as if it were a rule - it shows up in \`synthesisui doctor\` and travels to the system's queue, for the owner to make it a rule or decline it.`);
         }
         default:
-            return text(`No tool named ${name}.`, true);
+            return {
+                body: `No tool named ${name}.`,
+                source: { kind: "none", reason: "tool", detail: "unknown tool" },
+                isError: true,
+            };
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.243",
+  "version": "0.16.244",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {