@fazer-ai/agents 1.0.0

package/dist/oauth.js

@@ -0,0 +1,578 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pkce = pkce;
+exports.randomState = randomState;
+exports.browserCommand = browserCommand;
+exports.openBrowser = openBrowser;
+exports.callbackHtml = callbackHtml;
+exports.startLoopback = startLoopback;
+exports.parseMcpEnvelope = parseMcpEnvelope;
+exports.readMcpResult = readMcpResult;
+exports.oauthCachePath = oauthCachePath;
+exports.loadOAuthCache = loadOAuthCache;
+exports.saveOAuthCache = saveOAuthCache;
+exports.classifyRefreshStatus = classifyRefreshStatus;
+exports.resolveBrowserClientMode = resolveBrowserClientMode;
+exports.listHubLicenses = listHubLicenses;
+exports.hubCall = hubCall;
+// Fluxo OAuth de CLI (authorization code + PKCE + loopback) contra o hub, e a
+// auto-provisão da credencial de registro via MCP. Zero-dep (node:crypto/http).
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const exec_1 = require("./exec");
+function base64url(buf) {
+    return buf
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+// PKCE S256: verifier aleatório + challenge = base64url(sha256(verifier)).
+function pkce() {
+    const verifier = base64url((0, node_crypto_1.randomBytes)(32));
+    const challenge = base64url((0, node_crypto_1.createHash)("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+function randomState() {
+    return base64url((0, node_crypto_1.randomBytes)(16));
+}
+// Monta o comando que abre uma URL no browser, por plataforma. Função pura
+// (testável). No Windows usa `Start-Process` do PowerShell, NÃO `cmd /c start`: o
+// `start` do cmd trata `&` como separador de comando e trunca a URL no primeiro
+// query param (quebrando redirect_uri/state/PKCE do OAuth). `Start-Process` com a
+// URL entre aspas simples preserva a URL inteira. macOS/Linux passam a URL como
+// argv puro (sem shell), então o `&` já não é problema.
+function browserCommand(url, platform = process.platform) {
+    if (platform === "win32") {
+        return {
+            cmd: (0, exec_1.windowsPowershell)(),
+            args: [
+                "-NoProfile",
+                "-Command",
+                `Start-Process '${url.replace(/'/g, "''")}'`,
+            ],
+        };
+    }
+    if (platform === "darwin")
+        return { cmd: "open", args: [url] };
+    return { cmd: "xdg-open", args: [url] };
+}
+// Abre a URL no browser do usuário (best-effort; não lança).
+function openBrowser(url) {
+    const { cmd, args } = browserCommand(url);
+    try {
+        // No Windows NÃO usar `detached`: o PowerShell destacado roda sem a window
+        // station interativa e o `Start-Process` não abre o browser na sessão do
+        // usuário (o `cmd start` antigo tolerava por sair instantâneo). Sem detached
+        // ele herda a sessão e abre; `windowsHide` evita o flash de janela. No Unix,
+        // `detached` mantém o open/xdg-open vivo após o CLI sair.
+        const child = process.platform === "win32"
+            ? (0, node_child_process_1.spawn)(cmd, args, { stdio: "ignore", windowsHide: true })
+            : (0, node_child_process_1.spawn)(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // sem browser: o chamador imprime a URL como fallback.
+    }
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+// Página self-contained mostrada no callback do loopback (modelada na
+// buildOAuthCallbackHtml do projeto): card, dark/light por prefers-color-scheme,
+// ícone SVG inline. Sem deps, sem fontes externas, sem script.
+function callbackHtml(ok, detail) {
+    const icon = ok
+        ? '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>'
+        : '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M18 6 6 18M6 6l12 12"/></svg>';
+    const heading = ok ? "Conexão concluída" : "Não foi possível conectar";
+    const body = ok
+        ? "Você já pode fechar esta aba e voltar ao terminal."
+        : (detail ?? "Tente de novo pelo terminal.");
+    return `<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>fazer.ai</title>
+<style>
+*{box-sizing:border-box}
+html,body{height:100%;margin:0}
+body{display:flex;align-items:center;justify-content:center;padding:24px;
+font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+background:#f4f5f7;color:#1c1e21}
+.card{width:100%;max-width:360px;background:#fff;border:1px solid #e4e6eb;border-radius:16px;
+padding:32px 28px;text-align:center;box-shadow:0 10px 34px rgba(0,0,0,.08);animation:rise .25s ease-out}
+@keyframes rise{from{opacity:0;transform:translateY(6px)}to{opacity:1;transform:none}}
+.icon{width:56px;height:56px;border-radius:50%;margin:0 auto 18px;display:flex;align-items:center;justify-content:center}
+.icon svg{width:30px;height:30px}
+.ok .icon{background:#e7f7ee;color:#1a7f47}
+.err .icon{background:#fdeaea;color:#c0392b}
+h1{font-size:18px;font-weight:600;margin:0 0 8px}
+.detail{font-size:14px;color:#4b4f56;margin:0;word-break:break-word}
+.hint{font-size:12px;color:#8a8d91;margin:16px 0 0}
+@media (prefers-color-scheme:dark){
+body{background:#0f1013;color:#e9eaec}
+.card{background:#1b1d21;border-color:#2a2d33;box-shadow:0 10px 34px rgba(0,0,0,.45)}
+.detail{color:#b7bbc2}.hint{color:#7d8189}
+.ok .icon{background:#13301f;color:#4ade80}
+.err .icon{background:#3a1b1b;color:#f87171}
+}
+</style>
+</head>
+<body>
+<main class="card ${ok ? "ok" : "err"}">
+<div class="icon">${icon}</div>
+<h1>${heading}</h1>
+<p class="detail">${escapeHtml(body)}</p>
+<p class="hint">fazer.ai · onboarding do fazer.ai agents</p>
+</main>
+</body>
+</html>`;
+}
+// Sobe um servidor HTTP no loopback para capturar o redirect do OAuth.
+function startLoopback(opts) {
+    const path = opts?.path ?? "/callback";
+    return new Promise((resolveServer, rejectServer) => {
+        let resolveCode;
+        let rejectCode;
+        const codePromise = new Promise((res, rej) => {
+            resolveCode = res;
+            rejectCode = rej;
+        });
+        const server = (0, node_http_1.createServer)((req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== path) {
+                res.statusCode = 404;
+                res.end("not found");
+                return;
+            }
+            const error = url.searchParams.get("error");
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state") ?? "";
+            const ok = Boolean(code) && !error;
+            res.statusCode = ok ? 200 : 400;
+            res.setHeader("content-type", "text/html; charset=utf-8");
+            res.end(ok
+                ? callbackHtml(true)
+                : callbackHtml(false, error
+                    ? `Autorização negada: ${error}`
+                    : "Resposta sem código de autorização."));
+            if (error)
+                rejectCode(new Error(`autorização negada: ${error}`));
+            else if (code)
+                resolveCode({ code, state });
+            else
+                rejectCode(new Error("callback sem code"));
+        });
+        server.on("error", rejectServer);
+        server.listen(opts?.port ?? 0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : (opts?.port ?? 0);
+            resolveServer({
+                redirectUri: `http://127.0.0.1:${port}${path}`,
+                waitForCode(timeoutMs = 300_000) {
+                    const timer = setTimeout(() => rejectCode(new Error("tempo esgotado esperando o login")), timeoutMs);
+                    return codePromise.finally(() => clearTimeout(timer));
+                },
+                close() {
+                    server.close();
+                },
+            });
+        });
+    });
+}
+function httpJson(method, urlStr, opts) {
+    const url = new URL(urlStr);
+    const isHttps = url.protocol === "https:";
+    const request = isHttps ? node_https_1.request : node_http_1.request;
+    const payload = opts?.body !== undefined ? JSON.stringify(opts.body) : undefined;
+    return new Promise((resolve, reject) => {
+        const req = request({
+            method,
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 80),
+            path: url.pathname + url.search,
+            headers: {
+                accept: "application/json",
+                "user-agent": "@fazer-ai/agents",
+                ...(payload
+                    ? {
+                        "content-type": "application/json",
+                        "content-length": Buffer.byteLength(payload),
+                    }
+                    : {}),
+                ...opts?.headers,
+            },
+        }, (res) => {
+            let body = "";
+            res.setEncoding("utf8");
+            res.on("data", (chunk) => {
+                body += chunk;
+            });
+            res.on("end", () => resolve({
+                status: res.statusCode ?? 0,
+                body,
+                contentType: String(res.headers["content-type"] ?? ""),
+            }));
+        });
+        req.setTimeout(opts?.timeoutMs ?? 15_000, () => {
+            req.destroy(new Error("o hub não respondeu a tempo"));
+        });
+        req.on("error", reject);
+        if (payload)
+            req.write(payload);
+        req.end();
+    });
+}
+function parseJson(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+}
+// O transporte Streamable HTTP do MCP responde JSON puro (enableJsonResponse) OU
+// SSE (text/event-stream, o padrão do SDK): linhas `data: {json}`. Extrai o
+// envelope JSON-RPC dos dois casos (no SSE, o último `data:` com result/error/id).
+function parseMcpEnvelope(body, contentType) {
+    const isSse = contentType.includes("text/event-stream") ||
+        /^\s*(event|data):/m.test(body);
+    if (!isSse)
+        return parseJson(body);
+    const payloads = body
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice("data:".length).trim())
+        .filter(Boolean);
+    for (let i = payloads.length - 1; i >= 0; i--) {
+        const obj = parseJson(payloads[i]);
+        if ("result" in obj || "error" in obj || "id" in obj)
+            return obj;
+    }
+    const last = payloads[payloads.length - 1];
+    return last ? parseJson(last) : {};
+}
+async function discover(hubBaseUrl) {
+    const r = await httpJson("GET", `${hubBaseUrl}/.well-known/oauth-authorization-server`);
+    if (r.status !== 200) {
+        throw new Error(`metadata OAuth indisponível no hub (HTTP ${r.status})`);
+    }
+    const m = parseJson(r.body);
+    const authorization = m.authorization_endpoint;
+    const token = m.token_endpoint;
+    if (!authorization || !token) {
+        throw new Error("metadata OAuth do hub sem authorization/token endpoint");
+    }
+    return {
+        authorization,
+        token,
+        registration: m.registration_endpoint,
+    };
+}
+async function dcrRegister(registrationUrl, redirectUri) {
+    const r = await httpJson("POST", registrationUrl, {
+        body: {
+            client_name: "@fazer-ai/agents CLI",
+            redirect_uris: [redirectUri],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+            scope: "mcp:read mcp:write",
+        },
+    });
+    if (r.status !== 201 && r.status !== 200) {
+        throw new Error(`registro do client OAuth falhou (HTTP ${r.status})`);
+    }
+    const clientId = parseJson(r.body).client_id;
+    if (!clientId)
+        throw new Error("o hub não devolveu client_id no registro");
+    return clientId;
+}
+// Interpreta o envelope JSON-RPC já parseado de um tools/call. Surfa tanto um
+// erro de protocolo (`error`) quanto um resultado de tool com `isError:true`
+// (cujo texto é a mensagem crua, não JSON), senão um erro de tool viraria
+// silenciosamente um objeto vazio.
+function readMcpResult(envelope) {
+    const rpcError = envelope.error;
+    if (rpcError)
+        return { ok: false, error: rpcError.message ?? "erro" };
+    const result = envelope.result;
+    const text = result?.content?.find((c) => c.type === "text")?.text;
+    if (result?.isError)
+        return { ok: false, error: text || "erro" };
+    return {
+        ok: true,
+        data: text ? parseJson(text) : (result ?? {}),
+    };
+}
+let rpcId = 0;
+async function mcpCall(hubBaseUrl, accessToken, name, args) {
+    rpcId += 1;
+    const r = await httpJson("POST", `${hubBaseUrl}/api/mcp`, {
+        // O Streamable HTTP exige Accept com os DOIS tipos, senão devolve 406.
+        headers: {
+            authorization: `Bearer ${accessToken}`,
+            accept: "application/json, text/event-stream",
+        },
+        body: {
+            jsonrpc: "2.0",
+            id: rpcId,
+            method: "tools/call",
+            params: { name, arguments: args },
+        },
+    });
+    if (r.status !== 200) {
+        const snippet = r.body.trim().slice(0, 200);
+        throw new Error(`chamada MCP ${name} falhou (HTTP ${r.status})${snippet ? `: ${snippet}` : ""}`);
+    }
+    const parsed = readMcpResult(parseMcpEnvelope(r.body, r.contentType));
+    if (!parsed.ok)
+        throw new Error(`MCP ${name}: ${parsed.error}`);
+    return parsed.data;
+}
+function oauthCachePath(home = (0, node_os_1.homedir)()) {
+    return (0, node_path_1.join)(home, ".fazer-ai", "oauth.json");
+}
+// Lê o cache só se for do MESMO hub (cache de outro hub não serve).
+function loadOAuthCache(hubBaseUrl, path = oauthCachePath()) {
+    try {
+        const obj = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+        if (obj.hubBaseUrl !== hubBaseUrl)
+            return {};
+        return { clientId: obj.clientId, refreshToken: obj.refreshToken };
+    }
+    catch {
+        return {};
+    }
+}
+function saveOAuthCache(hubBaseUrl, data, path = oauthCachePath()) {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)(path, `${JSON.stringify({ hubBaseUrl, ...data }, null, 2)}\n`, {
+            mode: 0o600,
+        });
+        (0, node_fs_1.chmodSync)(path, 0o600);
+    }
+    catch {
+        // cache é best-effort; falhar aqui não quebra o login.
+    }
+}
+// Classifica o status do endpoint de token num veredito de refresh. Pura (testável). Um 4xx (≠429) é
+// TERMINAL: invalid_grant/invalid_client/reuso detectado, a sessão morreu de fato. 5xx/429 (e erro de
+// rede, mapeado fora daqui) são TRANSITÓRIOS: o hub está instável e o refresh token NÃO foi consumido,
+// então re-tentar é seguro e quase sempre salva a sessão.
+function classifyRefreshStatus(status) {
+    if (status === 200)
+        return "ok";
+    if (status >= 400 && status < 500 && status !== 429)
+        return "terminal";
+    return "transient";
+}
+// Re-tenta o refresh algumas vezes antes de desistir; só uma falha transitória (rede/5xx/429) é re-tentada.
+const REFRESH_ATTEMPTS = 3;
+const REFRESH_BACKOFF_MS = [300, 800];
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// Troca o refresh_token por um access_token novo, sem browser. Re-tenta em falha transitória (hub
+// instável/rede): essas não consomem o refresh token, então re-tentar quase sempre salva a sessão. Só
+// desiste como terminal num 4xx de auth (expirado/revogado/reuso), aí o chamador cai pro browser/re-login.
+async function refreshAccessToken(tokenEndpoint, clientId, refreshToken, resource) {
+    let lastDetail = "o hub não respondeu ao refresh";
+    for (let attempt = 0; attempt < REFRESH_ATTEMPTS; attempt++) {
+        if (attempt > 0)
+            await sleep(REFRESH_BACKOFF_MS[attempt - 1] ?? 800);
+        let res;
+        try {
+            res = await httpJson("POST", tokenEndpoint, {
+                body: {
+                    grant_type: "refresh_token",
+                    refresh_token: refreshToken,
+                    client_id: clientId,
+                    resource,
+                },
+            });
+        }
+        catch (e) {
+            // Erro de transporte (DNS/conexão/timeout): sem veredito, o refresh token não foi consumido → re-tenta.
+            lastDetail = e instanceof Error ? e.message : "falha de rede no refresh";
+            continue;
+        }
+        const verdict = classifyRefreshStatus(res.status);
+        if (verdict === "ok") {
+            const tok = parseJson(res.body);
+            const accessToken = tok.access_token;
+            if (accessToken) {
+                return {
+                    ok: true,
+                    accessToken,
+                    refreshToken: tok.refresh_token,
+                };
+            }
+            return { ok: false, transient: false, detail: "refresh sem access_token" };
+        }
+        if (verdict === "terminal") {
+            return {
+                ok: false,
+                transient: false,
+                detail: `refresh recusado (HTTP ${res.status})`,
+            };
+        }
+        lastDetail = `o hub respondeu HTTP ${res.status} ao refresh`;
+    }
+    return { ok: false, transient: true, detail: lastDetail };
+}
+// Decide como obter o client_id para o login NO BROWSER. O clientId em cache
+// serve só pro refresh (sem browser) e pode ter expirado/sido removido no hub
+// (→ `invalid_client` no /authorize), então no browser preferimos um client
+// FRESCO via DCR. Precedência: client_id fixo (env) > registrar via DCR > cache
+// (último recurso, hub sem DCR) > erro. Pura (testável).
+function resolveBrowserClientMode(opts) {
+    if (opts.fixedClientId)
+        return "fixed";
+    if (opts.hasRegistration)
+        return "register";
+    if (opts.cachedClientId)
+        return "cached";
+    return "error";
+}
+// Obtém um access_token do hub: refresh do cache (sem browser) ou login no
+// browser (loopback + PKCE). Salva clientId + refresh rotacionado pra próxima
+// run dispensar o browser. Chamadas repetidas no mesmo run só refrescam (1 login).
+async function acquireAccessToken(config, opts, 
+// Loga "sessão reaproveitada" ao usar o refresh em cache. Off no caminho que
+// re-chama em loop (lista de licenças), pra não repetir a cada refresh.
+logReuse = true) {
+    const endpoints = await discover(config.hubBaseUrl);
+    const resource = `${config.hubBaseUrl}/api/mcp`;
+    const cache = loadOAuthCache(config.hubBaseUrl);
+    let clientId = process.env.AGENTS_OAUTH_CLIENT_ID?.trim() || cache.clientId;
+    let accessToken;
+    let refreshToken;
+    // 1) Sessão salva: troca o refresh por um access novo, sem browser.
+    let refreshFailure;
+    if (!opts.forceLogin && clientId && cache.refreshToken) {
+        const refreshed = await refreshAccessToken(endpoints.token, clientId, cache.refreshToken, resource);
+        if (refreshed.ok) {
+            accessToken = refreshed.accessToken;
+            refreshToken = refreshed.refreshToken ?? cache.refreshToken;
+            if (logReuse) {
+                opts.log(`[${new URL(config.hubBaseUrl).host}] Sessão reaproveitada.`);
+            }
+        }
+        else {
+            refreshFailure = refreshed;
+        }
+    }
+    // Proxy do hub (headless): sem sessão válida, falha rápido em vez de abrir o browser e travar. Distingue
+    // um hub instável/inacessível (transitório → re-rodar o MESMO comando salva a sessão, que segue válida)
+    // de uma sessão de fato expirada/revogada (terminal → re-login no browser). Tratar um blip de rede como
+    // "sessão expirada" mandava o agente re-logar e tentar caminhos não documentados à toa.
+    if (!accessToken && opts.refreshOnly) {
+        if (refreshFailure?.transient) {
+            throw new Error(`o hub fazer.ai não respondeu ao refresh da sessão (${refreshFailure.detail}); a sessão provavelmente segue válida; rode o mesmo comando de novo em instantes.`);
+        }
+        throw new Error("sessão do hub expirada/ausente; re-rode o CLI de onboarding para logar (browser).");
+    }
+    // 2) Sem sessão válida: login no browser (loopback + PKCE).
+    if (!accessToken) {
+        const loop = await startLoopback();
+        try {
+            const fixedClientId = process.env.AGENTS_OAUTH_CLIENT_ID?.trim();
+            const mode = resolveBrowserClientMode({
+                fixedClientId,
+                hasRegistration: Boolean(endpoints.registration),
+                cachedClientId: cache.clientId,
+            });
+            if (mode === "fixed") {
+                clientId = fixedClientId;
+            }
+            else if (mode === "register") {
+                // Client fresco: o cache.clientId pode ter expirado no hub (invalid_client).
+                clientId = await dcrRegister(endpoints.registration, loop.redirectUri);
+            }
+            else if (mode === "cached") {
+                clientId = cache.clientId;
+            }
+            else {
+                throw new Error("o hub não tem DCR habilitado nem client pré-registrado. Habilite MCP_DCR_ENABLED ou defina AGENTS_OAUTH_CLIENT_ID.");
+            }
+            if (!clientId)
+                throw new Error("client_id do OAuth não resolvido.");
+            const { verifier, challenge } = pkce();
+            const state = randomState();
+            const authUrl = `${endpoints.authorization}?${new URLSearchParams({
+                client_id: clientId,
+                redirect_uri: loop.redirectUri,
+                response_type: "code",
+                code_challenge: challenge,
+                code_challenge_method: "S256",
+                scope: "mcp:read mcp:write",
+                state,
+                resource,
+            }).toString()}`;
+            opts.log("Abrindo o navegador para você entrar com a fazer.ai...");
+            opts.log(`Se não abrir, acesse: ${authUrl}`);
+            openBrowser(authUrl);
+            const cb = await loop.waitForCode();
+            if (cb.state !== state) {
+                throw new Error("resposta de login inconsistente (state não confere)");
+            }
+            const tokenRes = await httpJson("POST", endpoints.token, {
+                body: {
+                    grant_type: "authorization_code",
+                    client_id: clientId,
+                    code: cb.code,
+                    redirect_uri: loop.redirectUri,
+                    code_verifier: verifier,
+                    resource,
+                },
+            });
+            if (tokenRes.status !== 200) {
+                throw new Error(`troca de token falhou (HTTP ${tokenRes.status})`);
+            }
+            const tok = parseJson(tokenRes.body);
+            accessToken = tok.access_token;
+            refreshToken = tok.refresh_token;
+        }
+        finally {
+            loop.close();
+        }
+    }
+    if (!accessToken)
+        throw new Error("o hub não devolveu access_token");
+    // Guarda clientId + refresh (rotacionado) pra próxima run dispensar o browser.
+    saveOAuthCache(config.hubBaseUrl, { clientId, refreshToken });
+    return accessToken;
+}
+// Lista as licenças do usuário no hub (read-only, mcp:read). Reusa a aquisição de
+// token; o `list_licenses` devolve `{ licenses: [...] }`. O filtro Kanban/Chatwoot
+// fica no chamador (licenses.ts).
+async function listHubLicenses(config, opts) {
+    // Silencia a tag de reuso: este caminho re-chama em loop (refresh da lista).
+    const accessToken = await acquireAccessToken(config, opts, false);
+    const data = await mcpCall(config.hubBaseUrl, accessToken, "list_licenses", {});
+    const licenses = data.licenses;
+    return Array.isArray(licenses) ? licenses : [];
+}
+// Operação genérica do hub, exposta pelo subcomando `agents hub …` (proxy) em vez de injetar o hub
+// MCP no agente: o agente ganha só as ops que o onboarding precisa, e o refresh token nunca entra na
+// sessão dele. Reusa o MESMO `acquireAccessToken` (refresh + rotação do oauth.json) e `mcpCall` que o
+// `listHubLicenses`: zero duplicação de OAuth. `args.dry_run` controla preview vs apply.
+async function hubCall(config, opts, name, args) {
+    const accessToken = await acquireAccessToken(config, opts, false);
+    return mcpCall(config.hubBaseUrl, accessToken, name, args);
+}

package/dist/onboarding-marker.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onboardingMarkerPath = onboardingMarkerPath;
+exports.loadOnboardingMarker = loadOnboardingMarker;
+exports.saveOnboardingMarker = saveOnboardingMarker;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+function onboardingMarkerPath(home = (0, node_os_1.homedir)()) {
+    return (0, node_path_1.join)(home, ".fazer-ai", "onboarding.json");
+}
+function loadOnboardingMarker(path = onboardingMarkerPath()) {
+    try {
+        const obj = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+        // Default conservador: markers antigos (sem o campo) e valores inválidos → "new".
+        const chatwootSource = obj.chatwootSource === "existing" ? "existing" : "new";
+        const edition = obj.edition === "pro" ? "pro" : "free";
+        // Chatwoot existente (BYO): sem tier/licença: o fazer.ai agents conecta ao que já está no ar.
+        if (chatwootSource === "existing") {
+            return { chatwootSource, edition };
+        }
+        // source = "new": exige um tier válido (pro/community), como o marker legado.
+        if (obj.chatwootTier !== "pro" && obj.chatwootTier !== "community") {
+            return undefined;
+        }
+        const out = {
+            chatwootSource,
+            chatwootTier: obj.chatwootTier,
+            edition,
+        };
+        if (typeof obj.chatwootLicenseId === "string" && obj.chatwootLicenseId) {
+            out.chatwootLicenseId = obj.chatwootLicenseId;
+        }
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
+function saveOnboardingMarker(marker, path = onboardingMarkerPath()) {
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(marker, null, 2)}\n`);
+    }
+    catch {
+        // best-effort; falhar aqui não quebra o fluxo.
+    }
+}

package/dist/preferences.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preferencesPath = preferencesPath;
+exports.loadPreferences = loadPreferences;
+exports.savePreferences = savePreferences;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+function preferencesPath(home = (0, node_os_1.homedir)()) {
+    return (0, node_path_1.join)(home, ".fazer-ai", "preferences.json");
+}
+function loadPreferences(path = preferencesPath()) {
+    try {
+        const obj = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+        const out = {};
+        if (typeof obj.agent === "string" && obj.agent)
+            out.agent = obj.agent;
+        if (typeof obj.provider === "string" && obj.provider)
+            out.provider = obj.provider;
+        if (typeof obj.chatwootLicenseId === "string" && obj.chatwootLicenseId)
+            out.chatwootLicenseId = obj.chatwootLicenseId;
+        if (typeof obj.chatwootSource === "string" && obj.chatwootSource)
+            out.chatwootSource = obj.chatwootSource;
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+// Mescla com o que já está salvo, então gravar `agent` não apaga `provider`.
+function savePreferences(partial, path = preferencesPath()) {
+    try {
+        const next = { ...loadPreferences(path), ...partial };
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(next, null, 2)}\n`);
+    }
+    catch {
+        // best-effort; falhar aqui não quebra o fluxo.
+    }
+}