@fazer-ai/agents 1.0.0

package/dist/skills/agents-operation/references/04-validate-and-apply.md

@@ -0,0 +1,31 @@
+# 04: Validar e aplicar
+
+Ordem: re-validar no playground → (quando fizer sentido) conversa de teste controlada → aplicar em produção com aprovação.
+
+## 1. Re-validar no playground
+
+Com o ajuste **proposto** (ou já aplicado num agente de teste/clone), repita no playground o mesmo turno do `02-reproduce.md` e confirme que o comportamento corrigiu. Use `trace` + `sources` para checar a tool/grounding certos. Itere aqui (barato, isolado) antes de tocar tráfego real.
+
+## 2. Conversa de teste controlada (Inbox API)
+
+Quando o problema depende da ponta real (webhook → debounce → turn → reply) e não só do agente, prove headless com um inbox `Channel::Api`, sem aparelho:
+
+- Crie/use um inbox `Channel::Api` no Chatwoot bound ao agente (auto-provisiona Agent Bot + webhook).
+- Injete uma mensagem **incoming** pela API do Chatwoot (criar conversa + `POST .../messages` com `message_type: incoming`).
+- Cadeia esperada: incoming → `/api/v1/chatwoot/webhook/:routeToken` → debounce → turn → modelo real → resposta **outgoing**. Confirme a resposta + o novo `ExecutionLog`/trace.
+
+Isso exercita o caminho de produção sem expor um cliente real. Faça nesse inbox de teste, não numa conversa de cliente.
+
+## 3. Aplicar
+
+- Só com **aprovação explícita** do usuário para aquela mudança específica.
+- Console (editor do agente) ou MCP com `dry_run:false` (mostre o diff do dry-run **antes**).
+- O write é registrado: editor → via API normal; MCP → grava `AuditLog` (`actorType: "mcp"`, com before/after projetado e limitado, nunca segredo). Para auditar depois: página de audit ou `audit_list` (MCP read).
+
+## 4. Confirmar em produção
+
+Após aplicar, acompanhe os próximos turnos reais no `/logs` + Langfuse e confirme que o estágio que divergia agora passa. Se uma conversa real ficou com erro pendente, há um badge de erro + botão de **re-engage** na conversa (re-responde o tail não respondido), use só com OK, é envio real ao cliente.
+
+## Tocar a conversa real diretamente (último recurso, efeito externo)
+
+As tools `conversation_*` de escrita (`reply`/`handoff`/`return`/`status`/`reengage`, MCP `mcp:write`) ou a tela de Conversations postam/mudam estado numa conversa **viva** do cliente. O dry-run do `conversation_reply` mostra o **texto exato** que seria enviado; aplicar **não é reversível**. Só com OK explícito, e confirme que o alvo é a conversa certa.

package/dist/ui-select.js

@@ -0,0 +1,279 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyAction = keyAction;
+exports.nextSelectable = nextSelectable;
+exports.clampStart = clampStart;
+exports.summaryTitle = summaryTitle;
+exports.renderFrame = renderFrame;
+exports.select = select;
+exports.acknowledge = acknowledge;
+exports.confirmKey = confirmKey;
+exports.confirm = confirm;
+// Seletor interativo de UMA opção: navegação por ↑/↓ (+ k/j) e Enter, zero-dep
+// (raw mode no mesmo padrão do askSecret). Dígitos 1-9 saltam o destaque. Sem
+// TTY, resolve o default sem prompt. A UI vai pro stderr (como o resto); ao
+// confirmar, colapsa o menu numa linha "✔ título: escolha".
+const ui_1 = require("./ui");
+const ESC = "\x1b[";
+// Mapeia os bytes do raw mode numa ação. Setas = CSI (\x1b[A/B); aceita k/j
+// (vim), Enter (\r/\n), Ctrl-C/Ctrl-D (cancela) e dígitos 1-9 (salto).
+function keyAction(data) {
+    if (data === "\x1b[A" || data === "k")
+        return "up";
+    if (data === "\x1b[B" || data === "j")
+        return "down";
+    if (data === "\r" || data === "\n")
+        return "enter";
+    if (data === "\x03" || data === "\x04")
+        return "cancel";
+    if (/^[1-9]$/.test(data))
+        return { digit: Number.parseInt(data, 10) };
+    return null;
+}
+// Próximo índice selecionável a partir de `from`, andando `step` (±1), pulando
+// desabilitados, com wrap. Devolve `from` se nada for selecionável.
+function nextSelectable(from, total, step, isDisabled) {
+    if (total === 0)
+        return from;
+    let i = from;
+    for (let n = 0; n < total; n++) {
+        i = (i + step + total) % total;
+        if (!isDisabled(i))
+            return i;
+    }
+    return from;
+}
+// Primeiro índice selecionável em/depois de `wanted` (senão o primeiro de todos).
+function clampStart(wanted, options, isDisabled) {
+    const within = Math.min(Math.max(wanted, 0), options.length - 1);
+    if (!isDisabled(within))
+        return within;
+    return nextSelectable(within, options.length, 1, isDisabled);
+}
+// Condensa o título (que pode ser uma pergunta longa com recomendação) num ASSUNTO
+// curto pro resumo pós-escolha: corta na 1ª quebra forte (?, :, .) e tira o "Qual/Onde"
+// inicial pra virar substantivo. Ex.: "Qual agente você prefere usar? Recomendamos…" →
+// "Agente". Fallback: o título inteiro. Puro (testável).
+function summaryTitle(title) {
+    const head = title.split(/[?:.]/)[0]?.trim() ?? title;
+    const stripped = head
+        .replace(/^qual\s+(o\s+|a\s+)?/i, "")
+        .replace(/^onde\s+(está\s+)?(o\s+|a\s+)?(sua\s+|seu\s+)?/i, "")
+        .replace(/\s+você\s+(quer|prefere)\s+usar$/i, "")
+        .trim();
+    const subject = stripped || head || title;
+    return subject.charAt(0).toUpperCase() + subject.slice(1);
+}
+function lineFor(opt, index, selected) {
+    const pointer = selected ? ui_1.c.cyan("❯ ") : "  ";
+    const num = ui_1.c.cyan(`${index + 1})`);
+    const label = opt.disabled
+        ? ui_1.c.gray(opt.label)
+        : selected
+            ? ui_1.c.bold(opt.label)
+            : opt.label;
+    const hint = opt.hint ? ` ${opt.hint}` : "";
+    return `${pointer}${num} ${label}${hint}`;
+}
+// O quadro completo (título + opções), como string. Puro: usado nos testes e
+// reimpresso a cada tecla na versão interativa.
+function renderFrame(title, options, selected) {
+    const lines = options.map((o, i) => lineFor(o, i, i === selected));
+    return `${(0, ui_1.headline)(title)}\n${lines.join("\n")}\n`;
+}
+function select(config) {
+    const { title, options } = config;
+    if (options.length === 0)
+        throw new Error("select: sem opções");
+    const out = config.out ?? process.stderr;
+    const isDisabled = (i) => Boolean(options[i]?.disabled);
+    const start = clampStart(config.defaultIndex ?? 0, options, isDisabled);
+    const startOpt = options[start];
+    // Sem TTY (CI/pipe): não há como navegar; resolve o default e segue.
+    if (!process.stdin.isTTY) {
+        out.write(`${ui_1.sym.ok} ${title}: ${ui_1.c.bold(startOpt.label)} ${ui_1.c.gray("(padrão, sem terminal interativo)")}\n`);
+        return Promise.resolve(startOpt.value);
+    }
+    const frameLines = options.length + 1; // título + opções
+    let selected = start;
+    const stdin = process.stdin;
+    out.write("\n");
+    out.write(`${ESC}?25l`); // esconde o cursor
+    out.write(renderFrame(title, options, selected));
+    return new Promise((resolve) => {
+        // Repinta o quadro NO LUGAR: sobe até o título e reescreve cada linha com `\r` +
+        // conteúdo + apagar-até-o-fim-da-linha (`\x1b[K`), em vez de limpar tudo (`\x1b[0J`)
+        // e repintar. Limpar-tudo deixa o quadro em branco por um instante entre o erase e o
+        // paint, o que pisca em terminal lento/SSH. Repintar linha a linha nunca some. Só
+        // redesenha quando o destaque MUDA (no-op de tecla repetida não repinta). (item 13)
+        const redrawInPlace = () => {
+            out.write(`${ESC}${frameLines}A`); // sobe até o título
+            // renderFrame termina com \n (split deixa um "" no fim); repinta só as frameLines
+            // linhas de conteúdo pra não empurrar o quadro pra baixo a cada tecla.
+            const lines = renderFrame(title, options, selected)
+                .split("\n")
+                .slice(0, frameLines);
+            for (const line of lines) {
+                // \r → coluna 0; linha; \x1b[K → apaga o resto (caso a nova seja mais curta).
+                out.write(`\r${line}${ESC}K\n`);
+            }
+        };
+        // Reposiciona o destaque e repinta só se mudou de fato.
+        const moveTo = (next) => {
+            if (next === selected)
+                return;
+            selected = next;
+            redrawInPlace();
+        };
+        const teardown = () => {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.removeListener("data", onData);
+            out.write(`${ESC}?25h`); // mostra o cursor
+        };
+        const onData = (chunk) => {
+            const action = keyAction(chunk);
+            if (action === "up") {
+                moveTo(nextSelectable(selected, options.length, -1, isDisabled));
+            }
+            else if (action === "down") {
+                moveTo(nextSelectable(selected, options.length, 1, isDisabled));
+            }
+            else if (action && typeof action === "object") {
+                const idx = action.digit - 1;
+                if (idx < options.length && !isDisabled(idx))
+                    moveTo(idx);
+            }
+            else if (action === "enter") {
+                if (isDisabled(selected))
+                    return;
+                const chosen = options[selected];
+                // Colapsa o quadro (aqui o 0J é legítimo: some com as N linhas de opção) numa
+                // linha de resumo clara: ✔ <assunto> · escolhido: <label>. (item 7)
+                out.write(`${ESC}${frameLines}A`);
+                out.write(`${ESC}0J`);
+                out.write(`\r${ui_1.sym.ok} ${summaryTitle(title)} ${ui_1.c.gray("· escolhido:")} ${ui_1.c.bold(chosen.label)}${ESC}K\n`);
+                teardown();
+                resolve(chosen.value);
+            }
+            else if (action === "cancel") {
+                teardown();
+                out.write("\n");
+                process.exit(130);
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        stdin.on("data", onData);
+    });
+}
+// "OK" de ação única: mostra a mensagem e espera UMA tecla (Enter/qualquer) pra
+// seguir. Sem segunda opção, quem chama sempre prossegue (ex.: recarregar a
+// lista). Ctrl-C cancela. Sem TTY, resolve na hora.
+function acknowledge(message, out = process.stderr) {
+    if (!process.stdin.isTTY)
+        return Promise.resolve();
+    const stdin = process.stdin;
+    out.write(`\n${ui_1.sym.info} ${message} ${ui_1.c.gray("[Enter]")}`);
+    return new Promise((resolve) => {
+        const teardown = () => {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.removeListener("data", onData);
+        };
+        const onData = (chunk) => {
+            if (chunk === "\x03") {
+                teardown();
+                out.write("\n");
+                process.exit(130);
+            }
+            teardown();
+            out.write("\n");
+            resolve();
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        stdin.on("data", onData);
+    });
+}
+// Mapeia a tecla num confirm S/N. Atalho de tecla única (s/y → sim, n → não)
+// confirma na hora; setas/hjkl movem o destaque (Sim à esquerda, Não à direita);
+// Enter confirma o atual; Ctrl-C/Ctrl-D cancela.
+function confirmKey(data) {
+    if (data === "s" || data === "S" || data === "y" || data === "Y")
+        return "yes";
+    if (data === "n" || data === "N")
+        return "no";
+    if (data === "\x1b[D" || data === "\x1b[A" || data === "h" || data === "k") {
+        return "left";
+    }
+    if (data === "\x1b[C" || data === "\x1b[B" || data === "l" || data === "j") {
+        return "right";
+    }
+    if (data === "\r" || data === "\n")
+        return "confirm";
+    if (data === "\x03" || data === "\x04")
+        return "cancel";
+    return null;
+}
+// Confirmação S/N interativa, no mesmo estilo do select(): uma linha que se
+// redesenha, tecla única ou setas+Enter, colapsa em "✔ pergunta Sim/Não". Sem
+// TTY devolve `false` (caminho seguro; automações usam --yes).
+function confirm(question, defaultYes = false, out = process.stderr) {
+    if (!process.stdin.isTTY)
+        return Promise.resolve(false);
+    const q = question.replace(/\s+/g, " ").trim();
+    let yes = defaultYes;
+    const stdin = process.stdin;
+    const render = () => {
+        const pill = (isYes) => {
+            const label = isYes ? "Sim" : "Não";
+            return isYes === yes ? ui_1.c.cyan(`❯ ${label}`) : ui_1.c.gray(`  ${label}`);
+        };
+        out.write(`\r${ESC}K${ui_1.sym.info} ${q}  ${pill(true)}  ${pill(false)}  ${ui_1.c.gray("(s/n)")}`);
+    };
+    out.write("\n");
+    out.write(`${ESC}?25l`);
+    render();
+    return new Promise((resolve) => {
+        const teardown = () => {
+            stdin.setRawMode(false);
+            stdin.pause();
+            stdin.removeListener("data", onData);
+            out.write(`${ESC}?25h`);
+        };
+        const finish = (val) => {
+            out.write(`\r${ESC}K${ui_1.sym.ok} ${q} ${ui_1.c.bold(val ? "Sim" : "Não")}\n`);
+            teardown();
+            resolve(val);
+        };
+        const onData = (chunk) => {
+            const action = confirmKey(chunk);
+            if (action === "yes")
+                finish(true);
+            else if (action === "no")
+                finish(false);
+            else if (action === "left") {
+                yes = true;
+                render();
+            }
+            else if (action === "right") {
+                yes = false;
+                render();
+            }
+            else if (action === "confirm")
+                finish(yes);
+            else if (action === "cancel") {
+                teardown();
+                out.write("\n");
+                process.exit(130);
+            }
+        };
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        stdin.on("data", onData);
+    });
+}

package/dist/ui.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cmd = exports.detail = exports.step = exports.sym = exports.c = exports.THEME = void 0;
+exports.headline = headline;
+exports.clearScreen = clearScreen;
+exports.banner = banner;
+exports.targetLine = targetLine;
+exports.phaseHeader = phaseHeader;
+exports.renderProgress = renderProgress;
+// Estilo de terminal zero-dep, no padrão da casa fazer.ai (ANSI puro; espelha o
+// install-script.sh do hub). Cor desliga sem TTY ou com NO_COLOR; FORCE_COLOR força.
+const COLOR = !process.env.NO_COLOR &&
+    (process.env.FORCE_COLOR ? true : Boolean(process.stderr.isTTY));
+// Tema claro opcional (FAZER_AI_CLI_THEME=light), para terminais de fundo branco em
+// que o cinza-escuro/ciano-claro do tema padrão some. O default segue o tema escuro.
+// NOTE: ANSI cru não conhece a cor real do terminal; o toggle é explícito por env.
+exports.THEME = process.env.FAZER_AI_CLI_THEME?.trim().toLowerCase() === "light"
+    ? "light"
+    : "dark";
+const ESC = "\x1b[";
+function wrap(code, s) {
+    return COLOR ? `${ESC}${code}m${s}${ESC}0m` : s;
+}
+const PALETTES = {
+    dark: {
+        red: "0;31",
+        green: "0;32",
+        yellow: "1;33",
+        blue: "0;34",
+        cyan: "0;36",
+        magenta: "0;35",
+        gray: "0;90",
+    },
+    light: {
+        red: "0;31",
+        green: "0;32",
+        yellow: "0;33",
+        blue: "0;34",
+        cyan: "0;36",
+        magenta: "0;35",
+        gray: "2",
+    },
+};
+const P = PALETTES[exports.THEME];
+exports.c = {
+    red: (s) => wrap(P.red, s),
+    green: (s) => wrap(P.green, s),
+    yellow: (s) => wrap(P.yellow, s),
+    blue: (s) => wrap(P.blue, s),
+    cyan: (s) => wrap(P.cyan, s),
+    magenta: (s) => wrap(P.magenta, s),
+    gray: (s) => wrap(P.gray, s),
+    bold: (s) => wrap("1", s),
+    dim: (s) => wrap("2", s),
+};
+exports.sym = {
+    ok: exports.c.green("✔"),
+    err: exports.c.red("✗"),
+    info: exports.c.cyan("→"),
+    warn: exports.c.yellow("!"),
+    bar: exports.c.yellow("│"),
+};
+// Bold + a cor da paleta num código SGR só (c.bold(c.cyan()) não serve porque o "0;"
+// do fg reseta o bold). Troca o atributo de brilho por "1" (bold), preservando o
+// número da cor (ex.: "0;36" → "1;36", "0;37" → "1;37").
+function boldColor(code) {
+    return `1;${code.split(";").pop()}`;
+}
+// Cabeçalho de seção: bold + ciano (o acento da casa).
+function headline(text) {
+    return COLOR ? `${ESC}${boldColor(P.cyan)}m${text}${ESC}0m` : text;
+}
+// Logo "fazer.ai" em ANSI Shadow (a mesma fonte do Hermes), na cor da casa (ciano + sombra cinza).
+const LOGO = [
+    "███████╗ █████╗ ███████╗███████╗██████╗     █████╗ ██╗",
+    "██╔════╝██╔══██╗╚══███╔╝██╔════╝██╔══██╗   ██╔══██╗██║",
+    "█████╗  ███████║  ███╔╝ █████╗  ██████╔╝   ███████║██║",
+    "██╔══╝  ██╔══██║ ███╔╝  ██╔══╝  ██╔══██╗   ██╔══██║██║",
+    "██║     ██║  ██║███████╗███████╗██║  ██║██╗██║  ██║██║",
+    "╚═╝     ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝╚═╝",
+];
+// Pinta os blocos (█) no acento ciano (bold) e a sombra (box-drawing ╗║╔═╝╚) em cinza, no padrão
+// da casa. Sem cor (NO_COLOR/sem TTY), devolve cru.
+const SHADOW_CHARS = new Set(["╗", "║", "╔", "═", "╝", "╚"]);
+function paintLogo(line) {
+    if (!COLOR)
+        return line;
+    const block = boldColor(P.cyan);
+    let out = "";
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === "█") {
+            let j = i;
+            while (line[j] === "█")
+                j++;
+            out += `${ESC}${block}m${line.slice(i, j)}${ESC}0m`;
+            i = j;
+        }
+        else if (ch !== undefined && SHADOW_CHARS.has(ch)) {
+            let j = i;
+            while (j < line.length && SHADOW_CHARS.has(line[j]))
+                j++;
+            out += `${ESC}${P.gray}m${line.slice(i, j)}${ESC}0m`;
+            i = j;
+        }
+        else {
+            out += ch ?? "";
+            i++;
+        }
+    }
+    return out;
+}
+// Limpa a tela antes do banner, só num terminal de verdade (stderr é TTY) e com cor
+// habilitada (respeita NO_COLOR: quem desliga cor tende a estar em pipe/CI/log, onde um
+// clear ANSI vira lixo). No-op fora disso. ANSI: 2J limpa a tela, H manda o cursor pro topo.
+function clearScreen(out = process.stderr) {
+    if (process.env.NO_COLOR || !process.stderr.isTTY)
+        return;
+    out.write(`${ESC}2J${ESC}H`);
+}
+function banner() {
+    const logo = LOGO.map(paintLogo).join("\n");
+    return `\n${logo}\n${exports.c.bold("  Bem-vindo ao instalador do fazer.ai agents")}\n${exports.c.gray("  do zero ao seu agente de atendimento")}\n`;
+}
+// Linha de status do agente alvo.
+function targetLine(displayName, state) {
+    const name = exports.c.bold(displayName);
+    if (!state.hasDetect)
+        return `${exports.sym.info} Agente alvo: ${name}`;
+    if (state.installed) {
+        const v = state.version ? exports.c.gray(` ${state.version}`) : "";
+        return `${exports.sym.ok} Agente alvo: ${name}${exports.c.gray(" detectado")}${v}`;
+    }
+    if (state.willInstall) {
+        return `${exports.sym.info} Agente alvo: ${name} ${exports.c.gray("(será instalado)")}`;
+    }
+    return `${exports.sym.err} Agente alvo: ${name}${exports.c.gray(" não instalado")}`;
+}
+// Cabeçalho de uma macro-fase da jornada ("Fase 2/4 · provedor"). Enquadra o onboarding
+// nas 4 fases (agente → provedor → chatwoot → configurar agente) sem reordenar nada.
+function phaseHeader(n, total, title) {
+    return `\n${headline(`Fase ${n}/${total}`)} ${exports.c.gray("·")} ${exports.c.bold(title)}`;
+}
+const step = (n, title) => `\n  ${exports.c.cyan(`${n}.`)} ${exports.c.bold(title)}`;
+exports.step = step;
+const detail = (text) => `     ${exports.sym.bar} ${exports.c.gray(text)}`;
+exports.detail = detail;
+const cmd = (text) => `     ${exports.c.dim("$")} ${exports.c.cyan(text)}`;
+exports.cmd = cmd;
+// Barra de progresso de uma linha (substitui os contadores "[n/total]"). Puro e
+// testável: monta a string; quem chama decide onde escrever (stderr). Clampa step em
+// [0, total], usa uma largura fixa de blocos e anexa "n/total" + o rótulo do passo.
+// Sem cor (NO_COLOR/sem TTY), sai cru, legível em log/pipe.
+const PROGRESS_WIDTH = 14;
+function renderProgress(step, total, label) {
+    const safeTotal = Math.max(1, Math.floor(total));
+    const done = Math.min(Math.max(0, Math.floor(step)), safeTotal);
+    const filled = Math.round((done / safeTotal) * PROGRESS_WIDTH);
+    const bar = "█".repeat(filled) + "░".repeat(PROGRESS_WIDTH - filled);
+    const painted = COLOR
+        ? `${exports.c.cyan("█".repeat(filled))}${exports.c.gray("░".repeat(PROGRESS_WIDTH - filled))}`
+        : bar;
+    const count = exports.c.gray(`${done}/${safeTotal}`);
+    const text = label.trim();
+    return `  ${painted} ${count}${text ? ` ${exports.c.bold(text)}` : ""}`;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@fazer-ai/agents",
+  "version": "1.0.0",
+  "description": "Bootstrap do onboarding do fazer.ai agents: prepara o seu agente de IA (Claude Code, Codex, Hermes) e entrega a jornada de onboarding.",
+  "license": "MIT",
+  "author": {
+    "name": "fazer.ai",
+    "url": "https://fazer.ai"
+  },
+  "homepage": "https://app.fazer.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fazer-ai/agents.git",
+    "directory": "tooling/cli"
+  },
+  "bin": {
+    "agents": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/bundle-skills.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "fazer-ai",
+    "agents",
+    "onboarding",
+    "cli",
+    "agent"
+  ],
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "cross-spawn": "^7.0.6"
+  }
+}