@mewbleh/purrx 1.0.8

package/src/core/approval.js

@@ -0,0 +1,101 @@
+import readline from "node:readline";
+import { READ_ONLY_TOOLS } from "../tools/builtin.js";
+
+// Tools that only read state are always safe to run without approval.
+const SAFE_TOOLS = READ_ONLY_TOOLS;
+
+// Tools considered "edits" (auto-approved under the auto-edit policy).
+const EDIT_TOOLS = new Set(["write_file", "edit_file", "remember"]);
+
+// Approval policies:
+//   "suggest"   -> ask before every mutating action (default, safest)
+//   "auto-edit" -> auto-approve file writes/edits, still ask before commands
+//   "full-auto" -> never ask (use with care)
+export const POLICIES = ["suggest", "auto-edit", "full-auto"];
+
+/**
+ * @typedef {(toolName: string, description: string) => Promise<"approve"|"always"|"reject">} Prompter
+ */
+
+/**
+ * @param {import("../types.js").ApprovalPolicy} [policy]
+ */
+export function createApprovalManager(policy = "suggest") {
+  // Remembers "always allow" decisions for the current session.
+  const alwaysAllowed = new Set();
+
+  /** @type {Prompter} */
+  let prompter = defaultPrompter;
+
+  /** @param {string} toolName */
+  function needsApproval(toolName) {
+    if (SAFE_TOOLS.has(toolName)) return false;
+    if (policy === "full-auto") return false;
+    if (policy === "auto-edit" && EDIT_TOOLS.has(toolName)) return false;
+    if (alwaysAllowed.has(toolName)) return false;
+    return true;
+  }
+
+  /**
+   * Ask the user to approve a tool call.
+   * @param {string} toolName
+   * @param {string} description
+   * @returns {Promise<"approve"|"reject">}
+   */
+  async function requestApproval(toolName, description) {
+    if (!needsApproval(toolName)) return "approve";
+    const decision = await prompter(toolName, description);
+    if (decision === "always") {
+      alwaysAllowed.add(toolName);
+      return "approve";
+    }
+    return decision === "approve" ? "approve" : "reject";
+  }
+
+  /** @param {Prompter} fn */
+  function setPrompter(fn) {
+    prompter = fn;
+  }
+
+  function getPrompter() {
+    return prompter;
+  }
+
+  return {
+    needsApproval,
+    requestApproval,
+    setPrompter,
+    getPrompter,
+    get policy() {
+      return policy;
+    },
+  };
+}
+
+/**
+ * Fallback readline-based prompter used when no richer UI is attached.
+ * @type {Prompter}
+ */
+async function defaultPrompter(toolName, description) {
+  const answer = await ask(
+    `\nApprove ${description}\n  [y]es / [n]o / [a]lways allow ${toolName}: `
+  );
+  const choice = answer.trim().toLowerCase();
+  if (choice === "a" || choice === "always") return "always";
+  if (choice === "y" || choice === "yes" || choice === "") return "approve";
+  return "reject";
+}
+
+/** @param {string} question */
+function ask(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}

package/src/core/compact.js

@@ -0,0 +1,207 @@
+import { streamResponse } from "../api/client.js";
+import { CONTEXT_LIMIT, COMPACT_THRESHOLD } from "../config.js";
+
+// Automatic context-window compaction.
+//
+// As a conversation grows, the history array (Responses API input items) can
+// approach the model's context limit. When it does, we summarize the older
+// portion of the conversation into a single compact "summary" message and keep
+// the most recent turns verbatim. This preserves continuity while freeing
+// space, similar to how Codex/Claude handle long sessions.
+
+// Rough token estimate: ~4 chars per token. Good enough for a trigger
+// heuristic; the real count from the API (when available) takes precedence.
+/**
+ * @param {import("../types.js").HistoryItem[]} history
+ * @returns {number}
+ */
+export function estimateTokens(history) {
+  let chars = 0;
+  for (const item of history) {
+    chars += approxItemChars(item);
+  }
+  return Math.ceil(chars / 4);
+}
+
+/**
+ * @param {import("../types.js").HistoryItem} item
+ * @returns {number}
+ */
+function approxItemChars(item) {
+  let n = 0;
+  if (typeof item.output === "string") n += item.output.length;
+  if (typeof item.arguments === "string") n += item.arguments.length;
+  if (Array.isArray(item.content)) {
+    for (const part of item.content) {
+      if (part && typeof part.text === "string") n += part.text.length;
+    }
+  }
+  return n;
+}
+
+/**
+ * Decide whether the history should be compacted.
+ * @param {import("../types.js").HistoryItem[]} history
+ * @param {number} [usedTokens] real token count from the last API response
+ * @returns {boolean}
+ */
+export function shouldCompact(history, usedTokens) {
+  const tokens = usedTokens && usedTokens > 0 ? usedTokens : estimateTokens(history);
+  return tokens >= CONTEXT_LIMIT * COMPACT_THRESHOLD;
+}
+
+// How many of the most recent history items to always keep verbatim.
+const KEEP_RECENT = 6;
+
+// A boundary must not split a function_call from its function_call_output, so
+// we find a safe cut index at or before the desired keep point.
+/**
+ * @param {import("../types.js").HistoryItem[]} history
+ * @param {number} desiredKeep
+ * @returns {number} index where the "recent" tail begins
+ */
+function safeCutIndex(history, desiredKeep) {
+  let cut = Math.max(0, history.length - desiredKeep);
+  // If the item just before the cut is a function_call whose output is at/after
+  // the cut, move the cut earlier so the pair stays together on one side.
+  // Simpler: ensure the first kept item is not a dangling function_call_output.
+  while (cut < history.length && history[cut]?.type === "function_call_output") {
+    cut += 1;
+  }
+  return cut;
+}
+
+/**
+ * Produce a plain-text transcript of history items for summarization.
+ * @param {import("../types.js").HistoryItem[]} items
+ * @returns {string}
+ */
+function transcript(items) {
+  const lines = [];
+  for (const item of items) {
+    if (item.type === "message") {
+      const text = (item.content || [])
+        .map((p) => p.text || "")
+        .join("")
+        .trim();
+      if (text) lines.push(`${item.role || "assistant"}: ${text}`);
+    } else if (item.type === "function_call") {
+      lines.push(`tool_call ${item.name}(${item.arguments || ""})`);
+    } else if (item.type === "function_call_output") {
+      const out = String(item.output || "").slice(0, 500);
+      lines.push(`tool_result: ${out}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Compact the history in place if it is over threshold. Summarizes the older
+ * portion via the model and replaces it with one summary message, keeping the
+ * recent tail verbatim.
+ *
+ * @param {Object} opts
+ * @param {import("../types.js").AuthInfo} opts.authInfo
+ * @param {import("../types.js").HistoryItem[]} opts.history mutated in place
+ * @param {string} opts.model
+ * @param {number} [opts.usedTokens]
+ * @param {(msg: string) => void} [opts.onInfo]
+ * @returns {Promise<boolean>} true if compaction happened
+ */
+export async function maybeCompact({ authInfo, history, model, usedTokens, onInfo }) {
+  if (!shouldCompact(history, usedTokens)) return false;
+  // Need enough material to be worth compacting.
+  if (history.length <= KEEP_RECENT + 2) return false;
+
+  const cut = safeCutIndex(history, KEEP_RECENT);
+  if (cut <= 1) return false;
+
+  const older = history.slice(0, cut);
+  const recent = history.slice(cut);
+
+  if (onInfo) onInfo("context is getting long; compacting older history...");
+
+  const summaryText = await summarize(authInfo, model, older).catch(() => null);
+  if (!summaryText) {
+    if (onInfo) onInfo("compaction skipped (summary failed).");
+    return false;
+  }
+
+  /** @type {import("../types.js").HistoryItem} */
+  const summaryItem = {
+    type: "message",
+    role: "user",
+    content: [
+      {
+        type: "input_text",
+        text:
+          "[Conversation summary of earlier turns, auto-generated to save context]\n" +
+          summaryText,
+      },
+    ],
+  };
+
+  // Replace history contents in place.
+  history.length = 0;
+  history.push(summaryItem, ...recent);
+
+  if (onInfo) onInfo(`compacted ${older.length} items into a summary.`);
+  return true;
+}
+
+/**
+ * Ask the model to summarize a transcript.
+ * @param {import("../types.js").AuthInfo} authInfo
+ * @param {string} model
+ * @param {import("../types.js").HistoryItem[]} older
+ * @returns {Promise<string|null>}
+ */
+async function summarize(authInfo, model, older) {
+  const text = transcript(older);
+  if (!text.trim()) return null;
+
+  const input = [
+    {
+      type: "message",
+      role: "user",
+      content: [
+        {
+          type: "input_text",
+          text:
+            "Summarize the following coding-assistant conversation so it can " +
+            "replace the original turns without losing important context. " +
+            "Preserve: the user's goals and decisions, files created or edited " +
+            "and how, key facts learned, unresolved tasks, and any preferences. " +
+            "Use terse bullet points. Do not invent details.\n\n" +
+            text,
+        },
+      ],
+    },
+  ];
+
+  let out = "";
+  const final = await streamResponse(
+    {
+      authInfo,
+      model,
+      input,
+      instructions:
+        "You are a precise summarizer that compresses conversation history for " +
+        "a coding agent. Output only the summary as bullet points.",
+    },
+    {
+      onText: (delta) => {
+        out += delta;
+      },
+    }
+  );
+
+  if (out.trim()) return out.trim();
+  // Fall back to assembling from the final response output if no text deltas.
+  const fromOutput = (final?.output || [])
+    .flatMap((i) => i.content || [])
+    .map((p) => p.text || "")
+    .join("")
+    .trim();
+  return fromOutput || null;
+}

package/src/core/context.js

@@ -0,0 +1,245 @@
+import fs from "node:fs";
+import path from "node:path";
+import { memoriesDir, skillsDir } from "../config.js";
+
+// ---------------------------------------------------------------------------
+// AGENTS.md  -  project + user instructions
+// ---------------------------------------------------------------------------
+//
+// We collect AGENTS.md files from (in order):
+//   1. the user's global config dir
+//   2. each directory from the filesystem root down to cwd (so nested project
+//      instructions override broader ones)
+// The concatenation is injected into the system prompt.
+
+/**
+ * Walk from `cwd` up to the root, returning AGENTS.md contents ordered from
+ * outermost (root) to innermost (cwd).
+ * @param {string} cwd
+ * @returns {{ path: string, content: string }[]}
+ */
+export function findAgentsFiles(cwd) {
+  /** @type {{ path: string, content: string }[]} */
+  const found = [];
+  let dir = path.resolve(cwd);
+  const chain = [];
+  while (true) {
+    chain.push(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // Root-first so closer files come later and take precedence.
+  for (const d of chain.reverse()) {
+    for (const name of ["AGENTS.md", "agents.md"]) {
+      const p = path.join(d, name);
+      try {
+        const content = fs.readFileSync(p, "utf8").trim();
+        if (content) found.push({ path: p, content });
+        break;
+      } catch {
+        // not here
+      }
+    }
+  }
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// memories.d  -  persistent cross-session memory
+// ---------------------------------------------------------------------------
+//
+// Every *.md file in <home>/memories.d is loaded and injected. The agent can
+// write new memories via the `remember` tool (see tools/builtin.js).
+
+/**
+ * @returns {{ name: string, content: string }[]}
+ */
+export function loadMemories() {
+  const dir = memoriesDir();
+  /** @type {{ name: string, content: string }[]} */
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+  } catch {
+    return out;
+  }
+  for (const f of entries.sort()) {
+    try {
+      const content = fs.readFileSync(path.join(dir, f), "utf8").trim();
+      if (content) out.push({ name: f.replace(/\.md$/, ""), content });
+    } catch {
+      // skip
+    }
+  }
+  return out;
+}
+
+/**
+ * Append a memory entry to a memory file (defaults to "notes").
+ * @param {string} text
+ * @param {string} [topic]
+ * @returns {string} the file written to
+ */
+export function saveMemory(text, topic = "notes") {
+  const dir = memoriesDir();
+  fs.mkdirSync(dir, { recursive: true });
+  const safe = topic.replace(/[^a-z0-9_-]/gi, "-").toLowerCase() || "notes";
+  const file = path.join(dir, `${safe}.md`);
+  const stamp = new Date().toISOString().slice(0, 10);
+  const entry = `- (${stamp}) ${text.trim()}\n`;
+  fs.appendFileSync(file, entry, "utf8");
+  return file;
+}
+
+// ---------------------------------------------------------------------------
+// Skills  -  reusable playbooks the model can opt into
+// ---------------------------------------------------------------------------
+//
+// A skill lives at <skillsDir>/<name>/SKILL.md or <skillsDir>/<name>.md, and
+// may also be defined per-project in ./.purrx/skills. Each SKILL.md starts with
+// an optional frontmatter-like header:
+//
+//   # Title
+//   description: one line shown in the skill list
+//
+// We surface the name + description to the model always, and load the full body
+// only when the model invokes the `use_skill` tool. This keeps the prompt lean.
+
+/**
+ * @param {string} cwd
+ * @returns {string[]} candidate skill directories (global + project)
+ */
+function skillSearchDirs(cwd) {
+  return [skillsDir(), path.join(cwd, ".purrx", "skills")];
+}
+
+/**
+ * @typedef {Object} SkillMeta
+ * @property {string} name
+ * @property {string} description
+ * @property {string} file
+ */
+
+/**
+ * List available skills (metadata only).
+ * @param {string} cwd
+ * @returns {SkillMeta[]}
+ */
+export function listSkills(cwd) {
+  /** @type {SkillMeta[]} */
+  const skills = [];
+  const seen = new Set();
+  for (const base of skillSearchDirs(cwd)) {
+    let entries;
+    try {
+      entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      let name = null;
+      let file = null;
+      if (e.isDirectory()) {
+        const candidate = path.join(base, e.name, "SKILL.md");
+        if (fs.existsSync(candidate)) {
+          name = e.name;
+          file = candidate;
+        }
+      } else if (e.isFile() && e.name.endsWith(".md") && e.name !== "SKILL.md") {
+        name = e.name.replace(/\.md$/, "");
+        file = path.join(base, e.name);
+      }
+      if (!name || !file || seen.has(name)) continue;
+      seen.add(name);
+      skills.push({ name, description: readSkillDescription(file), file });
+    }
+  }
+  return skills;
+}
+
+/**
+ * Read the full body of a named skill.
+ * @param {string} cwd
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function readSkill(cwd, name) {
+  const skill = listSkills(cwd).find((s) => s.name === name);
+  if (!skill) return null;
+  try {
+    return fs.readFileSync(skill.file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pull a one-line description from a SKILL.md: a `description:` line if present,
+ * else the first non-heading line.
+ * @param {string} file
+ * @returns {string}
+ */
+function readSkillDescription(file) {
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+  const lines = text.split("\n").map((l) => l.replace(/\r$/, ""));
+  for (const line of lines) {
+    const m = line.match(/^\s*description:\s*(.+)$/i);
+    if (m) return m[1].trim();
+  }
+  for (const line of lines) {
+    const t = line.trim();
+    if (t && !t.startsWith("#")) return t.slice(0, 100);
+  }
+  return "";
+}
+
+// ---------------------------------------------------------------------------
+// Compose everything into a system-prompt addendum.
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the extra context block (AGENTS.md + memories + skill index) appended
+ * to the base system instructions.
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function buildContextBlock(cwd) {
+  const parts = [];
+
+  const agents = findAgentsFiles(cwd);
+  if (agents.length) {
+    const joined = agents
+      .map((a) => `<!-- ${a.path} -->\n${a.content}`)
+      .join("\n\n");
+    parts.push(`# Project instructions (AGENTS.md)\n${joined}`);
+  }
+
+  const memories = loadMemories();
+  if (memories.length) {
+    const joined = memories
+      .map((m) => `## ${m.name}\n${m.content}`)
+      .join("\n\n");
+    parts.push(
+      `# Memories (persistent notes from past sessions)\n${joined}`
+    );
+  }
+
+  const skills = listSkills(cwd);
+  if (skills.length) {
+    const list = skills
+      .map((s) => `- ${s.name}: ${s.description || "(no description)"}`)
+      .join("\n");
+    parts.push(
+      `# Available skills\nCall the use_skill tool with a skill name to load its full playbook before doing the task.\n${list}`
+    );
+  }
+
+  return parts.join("\n\n");
+}

package/src/core/session.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { sessionsDir } from "../config.js";
+
+// A session captures the conversation history (Responses API input items) plus
+// some metadata so it can be resumed later.
+
+export function newSessionId() {
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const rand = crypto.randomBytes(3).toString("hex");
+  return `${ts}_${rand}`;
+}
+
+function sessionPath(id) {
+  return path.join(sessionsDir(), `${id}.json`);
+}
+
+export function saveSession(session) {
+  const dir = sessionsDir();
+  fs.mkdirSync(dir, { recursive: true });
+  session.updated_at = new Date().toISOString();
+  fs.writeFileSync(sessionPath(session.id), JSON.stringify(session, null, 2));
+  return sessionPath(session.id);
+}
+
+export function loadSession(id) {
+  try {
+    const raw = fs.readFileSync(sessionPath(id), "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function createSession(meta = {}) {
+  const id = newSessionId();
+  return {
+    id,
+    created_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    cwd: meta.cwd || process.cwd(),
+    model: meta.model || null,
+    history: [],
+  };
+}
+
+// Returns the most recently updated session, or null.
+export function latestSession() {
+  const sessions = listSessions();
+  return sessions.length ? loadSession(sessions[0].id) : null;
+}
+
+// Lists sessions sorted newest-first with a short summary.
+export function listSessions() {
+  const dir = sessionsDir();
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const f of files) {
+    try {
+      const data = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+      out.push({
+        id: data.id,
+        updated_at: data.updated_at || data.created_at,
+        cwd: data.cwd,
+        turns: (data.history || []).filter(
+          (i) => i.type === "message" && i.role === "user"
+        ).length,
+        preview: firstUserText(data.history),
+      });
+    } catch {
+      // skip corrupt files
+    }
+  }
+  out.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+  return out;
+}
+
+export function deleteSession(id) {
+  try {
+    fs.rmSync(sessionPath(id));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function firstUserText(history = []) {
+  const first = history.find(
+    (i) => i.type === "message" && i.role === "user"
+  );
+  if (!first) return "";
+  const part = (first.content || []).find((c) => c.type === "input_text");
+  const text = part?.text || "";
+  return text.length > 60 ? text.slice(0, 60) + "..." : text;
+}

package/src/index.js

@@ -0,0 +1,24 @@
+// Public programmatic API for purrx. The CLI lives in bin/purrx.js.
+export { runTurn } from "./core/agent.js";
+export { ToolRegistry } from "./tools/registry.js";
+export { createApprovalManager } from "./core/approval.js";
+export { streamResponse } from "./api/client.js";
+export {
+  ensureFreshAuth,
+  resolveAuthMode,
+  readAuth,
+  writeAuth,
+} from "./auth/tokens.js";
+export { loginWithChatGPT, loginWithApiKey } from "./auth/login.js";
+export { listModels, resolveModel } from "./api/models.js";
+export { detectPlatform } from "./platform.js";
+export { startTui } from "./ui/tui.js";
+export {
+  buildContextBlock,
+  listSkills,
+  readSkill,
+  loadMemories,
+  saveMemory,
+  findAgentsFiles,
+} from "./core/context.js";
+export { maybeCompact, shouldCompact, estimateTokens } from "./core/compact.js";