kafox-cli 0.6.0 → 0.8.0

package/src/sessions.js

@@ -0,0 +1,172 @@
+/**
+ * Historico de conversas do CLI.
+ *
+ * Cada sessao vira um arquivo em ~/.kafox/chats/<codigo>.json e o codigo curto
+ * e o que aparece no `kafox resume <codigo>` (e no `kafox history`).
+ */
+const crypto = require("crypto");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const storage = require("./storage");
+
+// Poda: com muitos arquivos a pasta vira lixo e o `history` precisa listar rapido.
+const MAX_SESSIONS = 60;
+const TITLE_MAX = 60;
+
+const FALLBACK_DIR = process.env.KAFOX_HOME
+  ? path.resolve(process.env.KAFOX_HOME)
+  : path.join(os.homedir(), ".kafox");
+
+// storage.DIR vem do modulo real; em teste ele pode ser stub, entao nunca
+// confiar cegamente (path.join(undefined) estoura).
+function baseDir() {
+  return storage.DIR || FALLBACK_DIR;
+}
+
+function chatsDir() {
+  return path.join(baseDir(), "chats");
+}
+
+function ensureDir() {
+  fs.mkdirSync(chatsDir(), { recursive: true, mode: 0o700 });
+}
+
+function newId() {
+  return crypto.randomBytes(4).toString("hex");
+}
+
+function fileFor(id) {
+  return path.join(chatsDir(), `${id}.json`);
+}
+
+/** Codigo digitado pelo usuario: so letras/numeros (sem caminho, sem "."). */
+function normalizeId(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, "");
+}
+
+/** Data curta do chat: "2026-10-28T..." -> "28/10". */
+function dayMonth(value) {
+  const parsed = new Date(value || "");
+  if (Number.isNaN(parsed.getTime())) return "";
+  const day = String(parsed.getDate()).padStart(2, "0");
+  const month = String(parsed.getMonth() + 1).padStart(2, "0");
+  return `${day}/${month}`;
+}
+
+/** Titulo curto: primeira mensagem do usuario, em uma linha. */
+function titleFrom(messages, fallback = "") {
+  const first = (messages || []).find(
+    (message) => message?.role === "user" && String(message.text || "").trim()
+  );
+  const text = String(first?.text || fallback || "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!text) return "conversa sem titulo";
+  return text.length > TITLE_MAX ? `${text.slice(0, TITLE_MAX - 1).trimEnd()}…` : text;
+}
+
+function save({ id, cwd, model, theme, messages, context, startedAt, title }) {
+  if (!id) return null;
+  ensureDir();
+  const now = new Date().toISOString();
+  const list = Array.isArray(messages) ? messages : [];
+  const data = {
+    id,
+    title: title || titleFrom(list),
+    cwd: cwd || process.cwd(),
+    model: model || null,
+    theme: theme || null,
+    startedAt: startedAt || now,
+    updatedAt: now,
+    messages: list,
+    context: Array.isArray(context) ? context : [],
+  };
+  const tmp = `${fileFor(id)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+  fs.renameSync(tmp, fileFor(id));
+  prune();
+  return data;
+}
+
+function load(id) {
+  if (!id) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(fileFor(id), "utf8"));
+    if (!data || typeof data !== "object") return null;
+    // Arquivo antigo pode nao ter titulo: deriva das mensagens.
+    if (!data.title) data.title = titleFrom(data.messages);
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+function list() {
+  let names = [];
+  try {
+    names = fs.readdirSync(chatsDir()).filter((name) => name.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const chats = [];
+  for (const name of names) {
+    const id = name.replace(/\.json$/, "");
+    const data = load(id);
+    if (!data) continue;
+    chats.push({
+      id,
+      title: data.title || titleFrom(data.messages),
+      cwd: data.cwd,
+      model: data.model,
+      updatedAt: data.updatedAt,
+      messages: (data.messages || []).length,
+    });
+  }
+  return chats.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+}
+
+function latest() {
+  return list()[0] || null;
+}
+
+/**
+ * Acha a conversa por id exato ou por prefixo unico: `kafox resume 3f1c`
+ * tambem funciona quando o codigo foi copiado pela metade.
+ */
+function find(value) {
+  const needle = normalizeId(value);
+  if (!needle) return null;
+  const exact = load(needle);
+  if (exact) return exact;
+  const matches = list().filter((chat) => chat.id.startsWith(needle));
+  if (matches.length !== 1) return null;
+  return load(matches[0].id);
+}
+
+function prune() {
+  for (const chat of list().slice(MAX_SESSIONS)) {
+    try {
+      fs.unlinkSync(fileFor(chat.id));
+    } catch {}
+  }
+}
+
+module.exports = {
+  MAX_SESSIONS,
+  TITLE_MAX,
+  chatsDir,
+  newId,
+  titleFrom,
+  normalizeId,
+  dayMonth,
+  save,
+  load,
+  list,
+  latest,
+  find,
+  prune,
+};

package/src/storage.js

@@ -4,7 +4,8 @@ const path = require("path");
 const os = require("os");
 
 const HOME = os.homedir();
-const DIR = path.join(HOME, ".kafox");
+// KAFOX_HOME aponta a pasta de configuracao direto (testes e uso portatil).
+const DIR = process.env.KAFOX_HOME ? path.resolve(process.env.KAFOX_HOME) : path.join(HOME, ".kafox");
 const TOKEN_FILE = path.join(DIR, "token.json");
 const CONFIG_FILE = path.join(DIR, "config.json");
 

package/src/subagents.js

@@ -0,0 +1,156 @@
+/**
+ * Subagentes: um agente dentro do agente.
+ *
+ * O modelo chama `spawn_subagent` com um objetivo; cada tarefa roda em contexto
+ * proprio (nao polui a conversa principal) e devolve apenas o resultado final.
+ * Várias tarefas rodam em paralelo, o que serve para investigar pontos
+ * diferentes do projeto ao mesmo tempo (auditoria, testes, levantamento).
+ */
+const SUBAGENT_TOOL_NAME = "spawn_subagent";
+const MAX_TASKS = 3;
+const MAX_DEPTH = 1;
+// Subagente tambem nao tem teto por padrao: roda ate entregar o objetivo.
+const DEFAULT_MAX_STEPS = Infinity;
+const READ_ONLY_TOOLS = ["read_file", "list_dir"];
+const ALL_LOCAL_TOOLS = ["read_file", "list_dir", "write_file", "edit_file", "run_command"];
+
+const SUBAGENT_TOOL = {
+  type: "function",
+  function: {
+    name: SUBAGENT_TOOL_NAME,
+    description:
+      "Lanca um ou mais subagentes com objetivo proprio. Cada subagente roda em contexto separado, usa as ferramentas liberadas (padrao: read_file e list_dir) e devolve so o resultado final. Use para dividir trabalho, investigar varios pontos em paralelo (auditoria, testes, busca de arquivos) ou tarefas longas que nao precisam sujar esta conversa.",
+    parameters: {
+      type: "object",
+      properties: {
+        tasks: {
+          type: "array",
+          description: `Lista de tarefas (1 a ${MAX_TASKS}). Independentes rodam em paralelo.`,
+          items: {
+            type: "object",
+            properties: {
+              objective: {
+                type: "string",
+                description: "O que o subagente deve entregar, com o criterio de pronto",
+              },
+              context: {
+                type: "string",
+                description: "Contexto extra: arquivos, caminhos, comandos, restricoes",
+              },
+              tools: {
+                type: "array",
+                items: { type: "string" },
+                description:
+                  "Ferramentas liberadas para esta tarefa (read_file, list_dir, write_file, edit_file, run_command). Padrao: read_file e list_dir.",
+              },
+              max_steps: {
+                type: "integer",
+                description: "Limite de passos (opcional; sem ele o subagente roda ate terminar)",
+              },
+            },
+            required: ["objective"],
+          },
+        },
+        objective: {
+          type: "string",
+          description: "Atalho para uma unica tarefa (equivalente a tasks: [{objective}])",
+        },
+        context: { type: "string", description: "Contexto extra para a tarefa unica" },
+        model: { type: "string", description: "Modelo dos subagentes (padrao: o da sessao)" },
+      },
+    },
+  },
+};
+
+function normalizeTasks(args = {}) {
+  const list = [];
+  if (Array.isArray(args.tasks)) {
+    for (const item of args.tasks) {
+      if (!item) continue;
+      if (typeof item === "string") list.push({ objective: item });
+      else if (item.objective) list.push(item);
+    }
+  } else if (args.objective) {
+    list.push({ objective: args.objective, context: args.context, tools: args.tools });
+  }
+  return list.slice(0, MAX_TASKS).map((task) => ({
+    objective: String(task.objective).trim(),
+    context: task.context ? String(task.context) : "",
+    tools: allowedTools(task.tools),
+    maxSteps: Number(task.max_steps || task.maxSteps) > 0 ? Number(task.max_steps || task.maxSteps) : Infinity,
+  }));
+}
+
+function allowedTools(requested) {
+  if (!Array.isArray(requested) || !requested.length) return [...READ_ONLY_TOOLS];
+  const chosen = requested
+    .map((name) => String(name).trim())
+    .filter((name) => ALL_LOCAL_TOOLS.includes(name));
+  return chosen.length ? [...new Set(chosen)] : [...READ_ONLY_TOOLS];
+}
+
+function subagentPrompt({ objective, context, cwd, depth }) {
+  return [
+    "Voce e um subagente do kafox CLI, rodando em contexto separado do agente principal.",
+    `Diretorio de trabalho: ${cwd}`,
+    `Objetivo: ${objective}`,
+    context ? `Contexto: ${context}` : "",
+    depth >= MAX_DEPTH ? "Nao lance outros subagentes." : "",
+    "Trabalhe so no objetivo recebido, use as ferramentas disponiveis e pare quando tiver a resposta.",
+    "Devolva um relatorio curto e direto em Markdown: o que encontrou, evidencias (arquivo:linha, saida de comando) e o que ficou em duvida.",
+    "Nao invente nada: se nao conseguiu verificar, diga isso explicitamente.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function describeSubagentCall(args = {}) {
+  const tasks = normalizeTasks(args);
+  if (!tasks.length) return "(sem objetivo)";
+  if (tasks.length === 1) return tasks[0].objective.slice(0, 120);
+  return `${tasks.length} tarefas: ${tasks.map((task) => task.objective.slice(0, 40)).join(" | ")}`;
+}
+
+/* ------------------------- historico da sessao ------------------------- */
+// O que os subagentes desta sessao fizeram: alimenta o `/agents`.
+const SESSION_RUNS = [];
+const MAX_RUNS = 50;
+
+function recordRun({ objective, tools = [], ok, ms = 0, steps = 0, report = "" }) {
+  SESSION_RUNS.push({
+    objective: String(objective || "(sem objetivo)"),
+    tools: [...tools],
+    ok: Boolean(ok),
+    ms: Number(ms) || 0,
+    steps: Number(steps) || 0,
+    report: String(report || ""),
+    at: new Date().toISOString(),
+  });
+  if (SESSION_RUNS.length > MAX_RUNS) SESSION_RUNS.splice(0, SESSION_RUNS.length - MAX_RUNS);
+  return SESSION_RUNS[SESSION_RUNS.length - 1];
+}
+
+function listRuns() {
+  return SESSION_RUNS.map((run) => ({ ...run }));
+}
+
+function clearRuns() {
+  SESSION_RUNS.length = 0;
+}
+
+module.exports = {
+  SUBAGENT_TOOL,
+  SUBAGENT_TOOL_NAME,
+  MAX_TASKS,
+  MAX_DEPTH,
+  DEFAULT_MAX_STEPS,
+  READ_ONLY_TOOLS,
+  ALL_LOCAL_TOOLS,
+  normalizeTasks,
+  allowedTools,
+  subagentPrompt,
+  describeSubagentCall,
+  recordRun,
+  listRuns,
+  clearRuns,
+};

package/src/tools.js

@@ -102,6 +102,10 @@ const TOOL_NAMES = LOCAL_TOOL_NAMES;
 const APPROVAL_REQUIRED = new Set(["write_file", "edit_file", "run_command"]);
 
 const TOOL_META = {
+  // A ferramenta de subagente e montada no agent.js (nao vai para TOOL_SPECS
+  // porque só aparece enquanto a profundidade permite), mas o card da TUI
+  // precisa do mesmo rótulo das outras.
+  spawn_subagent: { kind: "agent", label: "Subagente" },
   read_file: { kind: "read", label: "Read" },
   list_dir: { kind: "list", label: "List" },
   write_file: { kind: "write", label: "Write" },
@@ -292,6 +296,14 @@ function previewToolChange(name, args = {}, context = {}) {
 
 /** Resumo curto da chamada para mostrar na conversa. */
 function describeToolCall(name, args = {}) {
+  if (name === "spawn_subagent") {
+    const tasks = Array.isArray(args.tasks) ? args.tasks : args.objective ? [args] : [];
+    if (!tasks.length) return "(sem objetivo)";
+    if (tasks.length === 1) return String(tasks[0].objective || "(objetivo)").slice(0, 120);
+    return `${tasks.length} subagentes: ${tasks
+      .map((task) => String(task.objective || "").slice(0, 40))
+      .join(" | ")}`;
+  }
   if (name === "read_file") return args.path || "(arquivo)";
   if (name === "write_file") return `${args.path || "(arquivo)"} (${String(args.content || "").length} chars)`;
   if (name === "edit_file") return `${args.path || "(arquivo)"}`;