liberty-code-cli 1.0.0 → 2.0.0

package/src/constants.js

@@ -0,0 +1,77 @@
+'use strict';
+/**
+ * Constantes centrais do Liberty Code.
+ *
+ * NOVO (v2): antes essas constantes viviam soltas dentro de bin/liberty.js.
+ * Extraídas pra cá porque agora vários módulos (memory, session, hooks,
+ * skills, mcp) precisam dos mesmos caminhos — ter uma fonte única evita
+ * inconsistência (ex: session.js e memory.js apontando pra pastas diferentes
+ * por causa de um typo em um dos dois lugares).
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+// ── Diretórios globais (nível usuário — válidos em qualquer projeto) ───────
+const GLOBAL_DIR    = path.join(os.homedir(), '.libertycode');
+const CONFIG_FILE   = path.join(GLOBAL_DIR, 'config.json');
+const GLOBAL_MEMORY_FILE = path.join(GLOBAL_DIR, 'LIBERTY.md');
+const GLOBAL_SKILLS_DIR  = path.join(GLOBAL_DIR, 'skills');
+const SESSIONS_ROOT  = path.join(GLOBAL_DIR, 'sessions');
+
+// ── Diretórios de projeto (nível repositório — pensados pra ir pro git,
+//    igual .claude/ do Claude Code) ─────────────────────────────────────────
+const PROJECT_DIR_NAME   = '.liberty';
+function projectDir(cwd)     { return path.join(cwd, PROJECT_DIR_NAME); }
+function projectSettingsFile(cwd) { return path.join(projectDir(cwd), 'settings.json'); }
+function projectMcpFile(cwd)      { return path.join(projectDir(cwd), 'mcp.json'); }
+function projectSkillsDir(cwd)    { return path.join(projectDir(cwd), 'skills'); }
+function projectLogsDir(cwd)      { return path.join(projectDir(cwd), 'logs'); }
+function projectMemoryFile(cwd)   { return path.join(cwd, 'LIBERTY.md'); }
+
+// ── Servidor ─────────────────────────────────────────────────────────────
+const SERVER_URL = process.env.LIBERTY_SERVER_URL || 'https://libertychat.onrender.com';
+
+// ── Limites ──────────────────────────────────────────────────────────────
+const MAX_FILE_READ_BYTES   = 256 * 1024;   // por leitura de trecho; arquivos maiores exigem offset/limit
+const MAX_TOOL_ITERATIONS   = 30;           // era 12 — baixo demais pra tarefas reais de várias etapas
+const MAX_SUBAGENT_ITERATIONS = 12;         // subagente é pra tarefa focada, não precisa do mesmo teto
+const MAX_SUBAGENT_DEPTH    = 1;            // subagente não pode disparar outro subagente (evita recursão/custo descontrolado)
+const TOOL_RESULT_CHAR_CAP  = 12000;        // por resultado de ferramenta enviado de volta ao modelo
+const RUN_COMMAND_TIMEOUT_MS = 120_000;
+const RUN_COMMAND_MAX_BUFFER = 8 * 1024 * 1024;
+const HOOK_TIMEOUT_MS = 15_000;
+const HISTORY_MESSAGES_SENT = 60; // espelha o slice(-60) que o server.js já aplica
+
+const PERMISSION_MODES = Object.freeze({
+  DEFAULT: 'default',           // pergunta antes de write_file / edit_file / run_command
+  ACCEPT_EDITS: 'acceptEdits',  // aprova edições de arquivo automaticamente, ainda pergunta pra comandos
+  BYPASS: 'bypassPermissions',  // aprova tudo automaticamente — requer flag explícita pra ligar
+  PLAN: 'plan',                 // somente leitura — nem oferece as ferramentas de escrita ao modelo
+});
+
+function slugifyProjectPath(cwd) {
+  // Usado pra isolar sessões/memória por projeto sem depender do nome da
+  // pasta (que pode repetir entre máquinas) — hash curto do caminho absoluto
+  // + nome legível da pasta, só pra facilitar achar visualmente em ~/.libertycode/sessions.
+  const abs = path.resolve(cwd);
+  const hash = crypto.createHash('sha1').update(abs).digest('hex').slice(0, 10);
+  const base = path.basename(abs).replace(/[^a-zA-Z0-9_-]/g, '_') || 'root';
+  return `${base}-${hash}`;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+module.exports = {
+  GLOBAL_DIR, CONFIG_FILE, GLOBAL_MEMORY_FILE, GLOBAL_SKILLS_DIR, SESSIONS_ROOT,
+  PROJECT_DIR_NAME, projectDir, projectSettingsFile, projectMcpFile, projectSkillsDir, projectLogsDir, projectMemoryFile,
+  SERVER_URL,
+  MAX_FILE_READ_BYTES, MAX_TOOL_ITERATIONS, MAX_SUBAGENT_ITERATIONS, MAX_SUBAGENT_DEPTH,
+  TOOL_RESULT_CHAR_CAP, RUN_COMMAND_TIMEOUT_MS, RUN_COMMAND_MAX_BUFFER, HOOK_TIMEOUT_MS,
+  HISTORY_MESSAGES_SENT, PERMISSION_MODES,
+  slugifyProjectPath, ensureDir,
+};

package/src/engine.js

@@ -0,0 +1,64 @@
+'use strict';
+/**
+ * Loop do agente — extraído de dentro do promptUser() do bin/liberty.js
+ * original pra virar uma função reutilizável.
+ *
+ * Por que isso importa mais do que parece: sem essa extração, subagentes
+ * (task) precisariam duplicar o while(iterations...) inteiro, ou o REPL
+ * principal teria que virar recursivo de um jeito estranho. Com o loop
+ * isolado aqui, tanto repl.js (sessão principal, MAX_TOOL_ITERATIONS,
+ * ferramentas completas) quanto subagents.js (MAX_SUBAGENT_ITERATIONS,
+ * ferramentas restritas, histórico isolado) chamam a MESMA função — é
+ * literalmente o mesmo motor com parâmetros diferentes, igual o Claude Code
+ * reaproveita seu loop principal pra rodar subagentes.
+ */
+const { apiChat } = require('./api');
+const { executeLocalTool } = require('./tools');
+const { paint, truncateForDisplay } = require('./ui');
+
+/**
+ * @param {object} opts
+ * @param {Array} opts.messages - histórico mutável (a função dá push nele)
+ * @param {string} opts.token
+ * @param {Array} opts.tools - schemas enviados ao modelo nesta chamada
+ * @param {string} [opts.systemPromptSuffix]
+ * @param {object} opts.ctx - contexto de execução de ferramentas (cwd, rl, permissions, hooks, ignoreEngine, todos, runSubagent, allowSubagents, mcpManager)
+ * @param {number} opts.maxIterations
+ * @param {boolean} [opts.verbose] - imprime "→ resultado" de cada ferramenta (true no loop principal, false em subagentes pra não poluir)
+ * @param {AbortSignal} [opts.signal]
+ */
+async function runAgentLoop({ messages, token, tools, systemPromptSuffix, ctx, maxIterations, verbose = true, signal }) {
+  let iterations = 0;
+  while (iterations++ < maxIterations) {
+    let response;
+    try {
+      response = await apiChat(messages, token, { tools, systemPromptSuffix, signal });
+    } catch (e) {
+      if (e.name === 'AbortError') return { finalText: null, cancelled: true };
+      throw e;
+    }
+
+    if (response.type === 'tool_calls') {
+      messages.push({
+        role: 'assistant', content: response.content || null,
+        tool_calls: response.toolCalls.map(tc => ({ id: tc.id, type: 'function', function: { name: tc.name, arguments: JSON.stringify(tc.arguments) } })),
+      });
+      for (const call of response.toolCalls) {
+        if (verbose) console.log(paint('yellow', `\n🔧 ${call.name}`) + paint('gray', ` ${truncateForDisplay(JSON.stringify(call.arguments || {}), 120)}`));
+        const result = await executeLocalTool(call, ctx);
+        if (verbose) console.log(paint('gray', `   → ${truncateForDisplay(result, 200)}`));
+        messages.push({ role: 'tool', tool_call_id: call.id, content: result });
+      }
+      continue; // devolve o resultado da(s) ferramenta(s) e deixa o modelo decidir o próximo passo
+    }
+
+    messages.push({ role: 'assistant', content: response.content });
+    return { finalText: response.content, cancelled: false, stoppedByLimit: false };
+  }
+  return {
+    finalText: null, cancelled: false, stoppedByLimit: true,
+    limitMessage: `[Atingido o limite de ${maxIterations} chamadas de ferramenta nesta resposta. Se a tarefa não terminou, peça pra continuar.]`,
+  };
+}
+
+module.exports = { runAgentLoop };

package/src/hooks.js

@@ -0,0 +1,105 @@
+'use strict';
+/**
+ * Hooks — equivalente aos hooks do Claude Code (PreToolUse, PostToolUse etc).
+ *
+ * NOVO (v2): não existia nenhuma forma de interceptar o agente de fora. Isso
+ * significa que coisas como "rodar eslint --fix depois de toda edição" ou
+ * "bloquear qualquer `rm -rf`" tinham que ser pedidas em português no prompt
+ * e torcer pro modelo obedecer sempre — nada garantido.
+ *
+ * Configurado em .liberty/settings.json:
+ * {
+ *   "hooks": {
+ *     "PreToolUse":  [{ "matcher": "run_command", "command": "node .liberty/hooks/block-rm-rf.js" }],
+ *     "PostToolUse": [{ "matcher": "write_file|edit_file", "command": "npx eslint --fix \"$LIBERTY_FILE\"" }],
+ *     "SessionStart":[{ "command": "git status --short" }],
+ *     "Stop":        [{ "command": "echo sessão encerrada >> .liberty/logs/audit.log" }]
+ *   }
+ * }
+ *
+ * Convenção de saída do hook (igual Claude Code):
+ *   exit 0            → ok. stdout (se houver) é só informativo, mostrado ao usuário.
+ *   exit 2             → BLOQUEIA a ação (só faz sentido em PreToolUse). stderr vira o
+ *                        motivo da recusa, devolvido ao modelo como resultado da ferramenta.
+ *   qualquer outro código → aviso (mostrado ao usuário), mas não bloqueia nada.
+ *
+ * O payload do evento é enviado por stdin como JSON E também como variáveis
+ * de ambiente (LIBERTY_EVENT, LIBERTY_TOOL, LIBERTY_FILE) pra hooks simples
+ * poderem ser um one-liner de shell sem precisar parsear JSON.
+ */
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const { projectSettingsFile, HOOK_TIMEOUT_MS } = require('./constants');
+const { paint } = require('./ui');
+
+function loadHooksConfig(cwd) {
+  try {
+    const raw = fs.readFileSync(projectSettingsFile(cwd), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.hooks || {};
+  } catch { return {}; }
+}
+
+function matches(matcher, toolName) {
+  if (!matcher) return true; // sem matcher = roda pra qualquer evento/ferramenta
+  try { return new RegExp(`^(${matcher})$`).test(toolName || ''); }
+  catch { return matcher === toolName; }
+}
+
+/**
+ * @param {'PreToolUse'|'PostToolUse'|'SessionStart'|'Stop'|'UserPromptSubmit'} event
+ * @param {{toolName?: string, args?: object, filePath?: string, cwd: string}} payload
+ * @returns {{blocked: boolean, reason?: string, infoLines: string[]}}
+ */
+function runHooks(event, payload, cwd) {
+  const config = loadHooksConfig(cwd);
+  const list = config[event];
+  const result = { blocked: false, reason: null, infoLines: [], rawOutputs: [] };
+  if (!Array.isArray(list) || !list.length) return result;
+
+  for (const hook of list) {
+    if (!hook || !hook.command) continue;
+    if (!matches(hook.matcher, payload.toolName)) continue;
+
+    const env = {
+      ...process.env,
+      LIBERTY_EVENT: event,
+      LIBERTY_TOOL: payload.toolName || '',
+      LIBERTY_FILE: payload.filePath || '',
+    };
+    let proc;
+    try {
+      proc = spawnSync(hook.command, {
+        shell: true,
+        cwd,
+        env,
+        input: JSON.stringify(payload),
+        timeout: HOOK_TIMEOUT_MS,
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024,
+      });
+    } catch (e) {
+      result.infoLines.push(paint('yellow', `⚠ hook "${hook.command}" falhou ao iniciar: ${e.message}`));
+      continue;
+    }
+    if (proc.error) {
+      result.infoLines.push(paint('yellow', `⚠ hook "${hook.command}" falhou: ${proc.error.message}`));
+      continue;
+    }
+    if (proc.status === 2) {
+      result.blocked = true;
+      result.reason = (proc.stderr || proc.stdout || 'hook bloqueou a ação sem motivo informado').trim();
+      break; // primeiro bloqueio já é suficiente pra interromper
+    }
+    if (proc.status && proc.status !== 0) {
+      result.infoLines.push(paint('yellow', `⚠ hook "${hook.command}" saiu com código ${proc.status}`));
+    }
+    if (proc.stdout && proc.stdout.trim()) {
+      result.infoLines.push(paint('gray', `  [hook:${event}] ${proc.stdout.trim().slice(0, 300)}`));
+      result.rawOutputs.push(proc.stdout.trim());
+    }
+  }
+  return result;
+}
+
+module.exports = { loadHooksConfig, runHooks };

package/src/ignoreEngine.js

@@ -0,0 +1,46 @@
+'use strict';
+/**
+ * Filtro de arquivos ignorados, compartilhado por list_directory / glob_files
+ * / grep_search.
+ *
+ * ANTES: list_directory tinha uma lista fixa de 5 nomes (node_modules, .git,
+ * .next, dist, build) direto no código — não lia .gitignore de verdade, então
+ * qualquer projeto com convenções diferentes (coverage/, .venv/, target/ no
+ * Rust, __pycache__/ no Python...) poluía a listagem e desperdiçava contexto.
+ *
+ * AGORA: usa a lib `ignore` (mesma base usada por ESLint/Prettier pra
+ * interpretar regras de .gitignore) combinando: (1) defaults sensatos, (2)
+ * .gitignore do projeto se existir, (3) .liberty/.libertyignore opcional pra
+ * regras específicas do agente (ex: ignorar uma pasta de dados grande que nem
+ * está no .gitignore mas não faz sentido o agente varrer).
+ */
+const fs = require('fs');
+const path = require('path');
+const ignore = require('ignore');
+
+const DEFAULT_IGNORES = [
+  'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out', 'coverage',
+  '.venv', 'venv', '__pycache__', '*.pyc', 'target', '.cache', '.parcel-cache',
+  '.turbo', '.vercel', '.DS_Store', '*.log', '.env', '.env.*', '!.env.example',
+  '.liberty/logs',
+];
+
+function buildIgnoreEngine(cwd) {
+  const ig = ignore().add(DEFAULT_IGNORES);
+  for (const file of ['.gitignore', path.join('.liberty', '.libertyignore')]) {
+    try {
+      const content = fs.readFileSync(path.join(cwd, file), 'utf8');
+      ig.add(content);
+    } catch { /* arquivo não existe — tudo bem, é opcional */ }
+  }
+  return {
+    isIgnored(relPath) {
+      // a lib `ignore` exige caminhos relativos com separador "/" (mesmo no Windows)
+      const normalized = relPath.split(path.sep).join('/');
+      if (!normalized || normalized === '.') return false;
+      try { return ig.ignores(normalized); } catch { return false; }
+    },
+  };
+}
+
+module.exports = { buildIgnoreEngine };

package/src/mcp.js

@@ -0,0 +1,139 @@
+'use strict';
+/**
+ * Integração MCP — igual ao Claude Code, servidores MCP são processos locais
+ * conversados via stdio (JSON-RPC), configurados em .liberty/mcp.json:
+ *
+ * {
+ *   "mcpServers": {
+ *     "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "..." } }
+ *   }
+ * }
+ *
+ * (Mesmo formato do mcpServers do Claude Desktop/Claude Code — quem já tem
+ * servidores MCP configurados lá pode só copiar o bloco.)
+ *
+ * NOVO (v2): não existia NENHUMA forma de estender as ferramentas do agente
+ * sem editar o código do CLI. Isso é o item mais "custoso" da lista pedida —
+ * é um protocolo de verdade (JSON-RPC sobre stdio, handshake de
+ * initialize/initialized), então usamos o SDK oficial (@modelcontextprotocol/sdk)
+ * em vez de reimplementar o protocolo na mão.
+ *
+ * Ferramentas de cada servidor entram no array enviado ao modelo com o nome
+ * "mcp__<servidor>__<ferramenta>" (mesma convenção do Claude Code) — e como
+ * tools/index.js já reconhece esse prefixo no dispatch, nenhuma outra parte
+ * do agente precisa saber a diferença entre uma ferramenta nativa e uma MCP.
+ *
+ * Falha em UM servidor (comando não existe, crashou, timeout no handshake)
+ * não derruba os outros nem o CLI — só avisa e segue sem aquele servidor.
+ */
+const fs = require('fs');
+const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
+const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
+const { projectMcpFile } = require('./constants');
+const { paint } = require('./ui');
+const pkg = require('../package.json');
+
+const CONNECT_TIMEOUT_MS = 10_000;
+
+function loadMcpConfig(cwd) {
+  try {
+    const raw = fs.readFileSync(projectMcpFile(cwd), 'utf8');
+    return JSON.parse(raw).mcpServers || {};
+  } catch { return {}; }
+}
+
+function sanitizeName(name) {
+  return String(name).replace(/[^a-zA-Z0-9_-]/g, '_');
+}
+
+function withTimeout(promise, ms, label) {
+  let timer;
+  const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`timeout (${ms}ms) em ${label}`)), ms); });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+class McpManager {
+  constructor() {
+    this.servers = new Map(); // nome -> { client, transport }
+    this.toolIndex = new Map(); // "mcp__nome__tool" -> { serverName, toolName }
+    this._descriptions = new Map();
+    this._schemas = new Map();
+  }
+
+  async connectAll(cwd) {
+    const config = loadMcpConfig(cwd);
+    const names = Object.keys(config);
+    if (!names.length) return { connected: [], failed: [] };
+
+    const connected = [], failed = [];
+    for (const rawName of names) {
+      const name = sanitizeName(rawName);
+      const def = config[rawName];
+      if (!def || !def.command) { failed.push({ name: rawName, error: 'sem "command" definido' }); continue; }
+      try {
+        const transport = new StdioClientTransport({
+          command: def.command, args: def.args || [], env: { ...process.env, ...(def.env || {}) },
+        });
+        const client = new Client({ name: 'liberty-code-cli', version: pkg.version }, { capabilities: {} });
+        await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `conectar em ${rawName}`);
+        const { tools } = await withTimeout(client.listTools(), CONNECT_TIMEOUT_MS, `listar ferramentas de ${rawName}`);
+
+        this.servers.set(name, { client, transport });
+        for (const tool of tools) {
+          const namespaced = `mcp__${name}__${sanitizeName(tool.name)}`;
+          this.toolIndex.set(namespaced, { serverName: name, toolName: tool.name });
+          this._descriptions.set(namespaced, tool.description || '');
+          this._schemas.set(namespaced, tool.inputSchema || { type: 'object', properties: {} });
+        }
+        connected.push({ name: rawName, toolCount: tools.length });
+      } catch (e) {
+        failed.push({ name: rawName, error: e.message });
+      }
+    }
+    return { connected, failed };
+  }
+
+  getToolSchemas() {
+    const schemas = [];
+    for (const [namespaced, { serverName }] of this.toolIndex.entries()) {
+      schemas.push({
+        type: 'function',
+        function: {
+          name: namespaced,
+          description: `[MCP:${serverName}] ${this._descriptions.get(namespaced) || namespaced}`,
+          parameters: this._schemas.get(namespaced) || { type: 'object', properties: {} },
+        },
+      });
+    }
+    return schemas;
+  }
+
+  async callTool(namespacedName, args) {
+    const entry = this.toolIndex.get(namespacedName);
+    if (!entry) return `[Ferramenta MCP desconhecida: ${namespacedName}]`;
+    const { client } = this.servers.get(entry.serverName);
+    try {
+      const result = await client.callTool({ name: entry.toolName, arguments: args || {} });
+      const text = (result.content || [])
+        .map(block => block.type === 'text' ? block.text : `[bloco ${block.type} omitido]`)
+        .join('\n');
+      return result.isError ? `[Erro reportado pelo servidor MCP] ${text}` : (text || '(sem retorno)');
+    } catch (e) {
+      return `[Erro ao chamar ferramenta MCP ${namespacedName}: ${e.message}]`;
+    }
+  }
+
+  async disconnectAll() {
+    for (const { client, transport } of this.servers.values()) {
+      try { await client.close(); } catch { /* ignora erro no encerramento */ }
+      try { await transport.close(); } catch { /* idem */ }
+    }
+  }
+
+  printSummary(connected, failed) {
+    connected.forEach(s => console.log(paint('green', `   ✓ MCP "${s.name}" conectado (${s.toolCount} ferramenta${s.toolCount === 1 ? '' : 's'})`)));
+    failed.forEach(s => console.log(paint('red', `   ✗ MCP "${s.name}" falhou: ${s.error}`)));
+  }
+}
+
+module.exports = { McpManager, loadMcpConfig };

package/src/memory.js

@@ -0,0 +1,89 @@
+'use strict';
+/**
+ * Memória persistente de projeto — equivalente ao CLAUDE.md.
+ *
+ * ANTES: loadProjectMemory() lia só um LIBERTY.md na raiz do cwd, uma vez,
+ * sem hierarquia nenhuma.
+ *
+ * AGORA:
+ *   1. Global  — ~/.libertycode/LIBERTY.md: preferências do USUÁRIO,
+ *      valem em qualquer projeto (ex: "sempre responda em português",
+ *      "prefiro pnpm a npm").
+ *   2. Projeto — <cwd>/LIBERTY.md: convenções do REPOSITÓRIO (como
+ *      já existia), pensado pra ir pro git e ser compartilhado pelo time.
+ *   3. Imports — dentro de qualquer LIBERTY.md, uma linha
+ *      "@caminho/relativo.md" importa o conteúdo daquele arquivo (só 1
+ *      nível de profundidade, sem recursão — evita loop de import A→B→A).
+ *
+ * Os três são concatenados com um cabeçalho indicando a origem, pra o modelo
+ * saber diferenciar "preferência pessoal" de "regra do repositório" se um dia
+ * entrarem em conflito.
+ */
+const fs = require('fs');
+const path = require('path');
+const { GLOBAL_MEMORY_FILE, projectMemoryFile, ensureDir, GLOBAL_DIR } = require('./constants');
+
+function resolveImports(content, baseDir, depth = 0) {
+  if (depth > 0) return content; // só 1 nível — @import dentro de um @import não é seguido
+  return content.replace(/^@([^\s]+\.md)\s*$/gm, (match, relPath) => {
+    try {
+      const full = path.resolve(baseDir, relPath);
+      const imported = fs.readFileSync(full, 'utf8').trim();
+      return `\n--- (importado de ${relPath}) ---\n${imported}\n--- (fim de ${relPath}) ---\n`;
+    } catch {
+      return `[LIBERTY.md: import "@${relPath}" não encontrado, ignorado]`;
+    }
+  });
+}
+
+function readMemoryFile(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8').trim();
+    if (!raw) return null;
+    return resolveImports(raw, path.dirname(filePath));
+  } catch { return null; }
+}
+
+/** @returns {string|null} bloco de contexto pronto pra virar a 1ª mensagem da sessão, ou null se não houver nenhuma memória. */
+function loadHierarchicalMemory(cwd) {
+  const blocks = [];
+  const global = readMemoryFile(GLOBAL_MEMORY_FILE);
+  if (global) blocks.push(`### Preferências globais do usuário (~/.libertycode/LIBERTY.md)\n${global}`);
+
+  const project = readMemoryFile(projectMemoryFile(cwd));
+  if (project) blocks.push(`### Convenções deste projeto (./LIBERTY.md)\n${project}`);
+
+  if (!blocks.length) return null;
+  return blocks.join('\n\n');
+}
+
+function hasProjectMemory(cwd) {
+  return fs.existsSync(projectMemoryFile(cwd));
+}
+
+function hasGlobalMemory() {
+  return fs.existsSync(GLOBAL_MEMORY_FILE);
+}
+
+/** Usado pelo atalho "#" do REPL: anexa uma nota rápida ao LIBERTY.md do projeto sem chamar o modelo. */
+function appendQuickNote(cwd, note) {
+  const file = projectMemoryFile(cwd);
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8').replace(/\s+$/, '') : '# LIBERTY.md\n\nContexto e convenções deste projeto para o Liberty Code.';
+  const hasNotesSection = /^##\s+Notas rápidas/m.test(existing);
+  const stamp = new Date().toISOString().slice(0, 10);
+  const line = `- (${stamp}) ${note}`;
+  const updated = hasNotesSection
+    ? existing.replace(/^##\s+Notas rápidas.*$/m, match => `${match}\n${line}`)
+    : `${existing}\n\n## Notas rápidas\n${line}\n`;
+  fs.writeFileSync(file, updated.trimEnd() + '\n', 'utf8');
+  return file;
+}
+
+function ensureGlobalDir() {
+  ensureDir(GLOBAL_DIR);
+}
+
+module.exports = {
+  loadHierarchicalMemory, hasProjectMemory, hasGlobalMemory, appendQuickNote, ensureGlobalDir,
+  projectMemoryFile, GLOBAL_MEMORY_FILE,
+};

package/src/permissions.js

@@ -0,0 +1,77 @@
+'use strict';
+/**
+ * Modos de permissão — equivalente ao permission mode do Claude Code.
+ *
+ * ANTES: toolWriteFile e toolRunCommand tinham um "Permitir? [y/N]" idêntico
+ * e hardcoded, sem opção de modo. Isso significa reconfirmar a MESMA operação
+ * repetidas vezes numa sessão longa (ex: rodar `npm test` 15 vezes seguidas
+ * enquanto corrige um bug) — cansativo o suficiente pra incentivar o usuário
+ * a copiar/colar o código manualmente em vez de deixar o agente iterar.
+ *
+ * AGORA: 4 modos, trocáveis em runtime via `/mode <nome>`:
+ *   - default          pergunta pra write_file / edit_file / run_command
+ *   - acceptEdits       aprova edição de arquivo sozinho, ainda pergunta comando
+ *   - bypassPermissions aprova tudo (requer confirmação explícita ao ligar)
+ *   - plan              somente leitura — nem chega a esta camada, porque as
+ *                        ferramentas de escrita simplesmente não são
+ *                        oferecidas ao modelo nesse modo (ver tools/index.js)
+ *
+ * E dentro do modo `default`, a resposta 'a' ("always"/sempre) grava uma
+ * regra na allow-list da SESSÃO ATUAL (perdida ao fechar o CLI, de propósito
+ * — não é uma allow-list persistente tipo .liberty/settings.json, que o
+ * usuário precisaria editar à mão pra ser realmente segura).
+ */
+const readline = require('readline');
+const { PERMISSION_MODES } = require('./constants');
+const { paint } = require('./ui');
+
+class PermissionEngine {
+  constructor(initialMode = PERMISSION_MODES.DEFAULT) {
+    this.mode = initialMode;
+    this.sessionAllow = new Set(); // chaves tipo "write:src/index.js" ou "cmd:npm test"
+  }
+
+  setMode(mode) {
+    if (!Object.values(PERMISSION_MODES).includes(mode)) {
+      throw new Error(`Modo desconhecido: ${mode}. Use: ${Object.values(PERMISSION_MODES).join(', ')}`);
+    }
+    this.mode = mode;
+  }
+
+  /**
+   * @param {'write'|'edit'|'run'} kind
+   * @param {string} key       - identificador estável pra allow-list (path ou comando)
+   * @param {string} promptLabel - texto mostrado antes do "Permitir?"
+   * @param {readline.Interface} rl
+   * @returns {Promise<boolean>}
+   */
+  async check(kind, key, promptLabel, rl) {
+    const allowKey = `${kind}:${key}`;
+    if (this.mode === PERMISSION_MODES.BYPASS) return true;
+    if (this.mode === PERMISSION_MODES.ACCEPT_EDITS && (kind === 'write' || kind === 'edit')) return true;
+    if (this.sessionAllow.has(allowKey)) return true;
+
+    const answer = await new Promise(resolve => {
+      rl.question(
+        `${promptLabel} ${paint('gray', '[y]es / [n]o / [a]lways nesta sessão  ')}`,
+        a => resolve(a.trim().toLowerCase())
+      );
+    });
+    if (['a', 'always', 'sempre'].includes(answer)) {
+      this.sessionAllow.add(allowKey);
+      return true;
+    }
+    return ['y', 'yes', 's', 'sim'].includes(answer);
+  }
+
+  describeMode() {
+    return {
+      [PERMISSION_MODES.DEFAULT]: 'default — pergunta antes de editar arquivos ou rodar comandos',
+      [PERMISSION_MODES.ACCEPT_EDITS]: 'acceptEdits — edita arquivos sem perguntar, mas ainda confirma comandos',
+      [PERMISSION_MODES.BYPASS]: 'bypassPermissions — roda tudo sem perguntar (cuidado)',
+      [PERMISSION_MODES.PLAN]: 'plan — somente leitura, o modelo só pode explorar e propor um plano',
+    }[this.mode];
+  }
+}
+
+module.exports = { PermissionEngine };