@phren/agent 0.0.1

package/dist/multi/coordinator.js

@@ -0,0 +1,263 @@
+/**
+ * Task-based coordination for multi-agent teams.
+ *
+ * Manages a shared JSON task list at ~/.phren-agent/teams/<team>/tasks.json.
+ * Multiple child processes may claim tasks concurrently — all mutations go
+ * through file locking + atomic rename to prevent corruption.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import * as crypto from "node:crypto";
+// ── File Locking ────────────────────────────────────────────────────────
+const LOCK_MAX_WAIT_MS = 5_000;
+const LOCK_POLL_MS = 50;
+const LOCK_STALE_MS = 30_000;
+function sleepSync(ms) {
+    const buf = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(buf, 0, 0, ms);
+}
+function acquireLock(lockPath) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    let waited = 0;
+    while (waited < LOCK_MAX_WAIT_MS) {
+        try {
+            fs.writeFileSync(lockPath, `${process.pid}\n${Date.now()}`, { flag: "wx" });
+            return; // acquired
+        }
+        catch {
+            // Lock exists — check if stale
+            try {
+                const stat = fs.statSync(lockPath);
+                if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+                    // Check if owner process is alive
+                    let alive = false;
+                    try {
+                        const content = fs.readFileSync(lockPath, "utf-8");
+                        const pid = parseInt(content.split("\n")[0], 10);
+                        if (pid > 0) {
+                            try {
+                                process.kill(pid, 0);
+                                alive = true;
+                            }
+                            catch { /* dead */ }
+                        }
+                    }
+                    catch { /* file vanished */ }
+                    if (!alive) {
+                        try {
+                            fs.unlinkSync(lockPath);
+                        }
+                        catch { /* gone */ }
+                        continue;
+                    }
+                }
+            }
+            catch { /* stat failed, retry */ }
+            sleepSync(LOCK_POLL_MS);
+            waited += LOCK_POLL_MS;
+        }
+    }
+    throw new Error(`TeamCoordinator: could not acquire lock within ${LOCK_MAX_WAIT_MS}ms`);
+}
+function releaseLock(lockPath) {
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch { /* already gone */ }
+}
+function withLock(filePath, fn) {
+    const lockPath = filePath + ".lock";
+    acquireLock(lockPath);
+    try {
+        return fn();
+    }
+    finally {
+        releaseLock(lockPath);
+    }
+}
+// ── Atomic File Write ───────────────────────────────────────────────────
+function atomicWriteJsonSync(filePath, data) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, `.tmp-${crypto.randomBytes(6).toString("hex")}`);
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+    fs.renameSync(tmp, filePath);
+}
+// ── Coordinator ─────────────────────────────────────────────────────────
+export class TeamCoordinator {
+    teamName;
+    filePath;
+    constructor(teamName) {
+        this.teamName = teamName;
+        this.filePath = path.join(os.homedir(), ".phren-agent", "teams", teamName, "tasks.json");
+    }
+    // ── Read / Write helpers (always called inside a lock) ──────────────
+    readFile() {
+        try {
+            const raw = fs.readFileSync(this.filePath, "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            const now = new Date().toISOString();
+            return { teamName: this.teamName, tasks: [], createdAt: now, updatedAt: now };
+        }
+    }
+    writeFile(data) {
+        data.updatedAt = new Date().toISOString();
+        atomicWriteJsonSync(this.filePath, data);
+    }
+    nextId(data) {
+        if (data.tasks.length === 0)
+            return "1";
+        const max = Math.max(...data.tasks.map((t) => parseInt(t.id, 10) || 0));
+        return String(max + 1);
+    }
+    // ── Public API ──────────────────────────────────────────────────────
+    /** Add a new task to the list. Returns the created task. */
+    createTask(subject, description, blockedBy) {
+        return withLock(this.filePath, () => {
+            const data = this.readFile();
+            const task = {
+                id: this.nextId(data),
+                subject,
+                description,
+                status: "pending",
+                owner: null,
+                createdAt: new Date().toISOString(),
+                claimedAt: null,
+                completedAt: null,
+                result: null,
+                error: null,
+                blockedBy: blockedBy ?? [],
+            };
+            data.tasks.push(task);
+            this.writeFile(data);
+            return task;
+        });
+    }
+    /**
+     * Atomically claim the next available task for an agent.
+     * Skips tasks that are blocked by incomplete dependencies.
+     * Returns null if nothing is available.
+     */
+    claimTask(agentName) {
+        return withLock(this.filePath, () => {
+            const data = this.readFile();
+            const completedIds = new Set(data.tasks.filter((t) => t.status === "completed").map((t) => t.id));
+            for (const task of data.tasks) {
+                if (task.status !== "pending")
+                    continue;
+                // Check blockedBy — all listed tasks must be completed
+                const blocked = task.blockedBy.some((depId) => !completedIds.has(depId));
+                if (blocked)
+                    continue;
+                task.status = "claimed";
+                task.owner = agentName;
+                task.claimedAt = new Date().toISOString();
+                this.writeFile(data);
+                return task;
+            }
+            return null;
+        });
+    }
+    /** Transition a claimed task to in_progress. */
+    startTask(taskId, agentName) {
+        withLock(this.filePath, () => {
+            const data = this.readFile();
+            const task = data.tasks.find((t) => t.id === taskId);
+            if (!task)
+                throw new Error(`Task ${taskId} not found`);
+            if (task.owner !== agentName) {
+                throw new Error(`Task ${taskId} is owned by "${task.owner}", not "${agentName}"`);
+            }
+            if (task.status !== "claimed") {
+                throw new Error(`Task ${taskId} is "${task.status}", expected "claimed"`);
+            }
+            task.status = "in_progress";
+            this.writeFile(data);
+        });
+    }
+    /** Mark a task as completed. */
+    completeTask(taskId, agentName, result) {
+        withLock(this.filePath, () => {
+            const data = this.readFile();
+            const task = data.tasks.find((t) => t.id === taskId);
+            if (!task)
+                throw new Error(`Task ${taskId} not found`);
+            if (task.owner !== agentName) {
+                throw new Error(`Task ${taskId} is owned by "${task.owner}", not "${agentName}"`);
+            }
+            task.status = "completed";
+            task.completedAt = new Date().toISOString();
+            task.result = result ?? null;
+            this.writeFile(data);
+        });
+    }
+    /** Mark a task as failed. */
+    failTask(taskId, agentName, error) {
+        withLock(this.filePath, () => {
+            const data = this.readFile();
+            const task = data.tasks.find((t) => t.id === taskId);
+            if (!task)
+                throw new Error(`Task ${taskId} not found`);
+            if (task.owner !== agentName) {
+                throw new Error(`Task ${taskId} is owned by "${task.owner}", not "${agentName}"`);
+            }
+            task.status = "failed";
+            task.completedAt = new Date().toISOString();
+            task.error = error;
+            this.writeFile(data);
+        });
+    }
+    /** Get the full task list (read-only snapshot). */
+    getTaskList() {
+        return withLock(this.filePath, () => {
+            return structuredClone(this.readFile().tasks);
+        });
+    }
+    /** Get the task currently assigned to an agent, or null. */
+    getAgentTask(agentName) {
+        return withLock(this.filePath, () => {
+            const data = this.readFile();
+            return (data.tasks.find((t) => t.owner === agentName &&
+                (t.status === "claimed" || t.status === "in_progress")) ?? null);
+        });
+    }
+    /** Get a single task by ID. */
+    getTask(taskId) {
+        return withLock(this.filePath, () => {
+            const data = this.readFile();
+            return data.tasks.find((t) => t.id === taskId) ?? null;
+        });
+    }
+    /** Return all tasks that are now unblocked (pending with all deps completed). */
+    getUnblockedTasks() {
+        return withLock(this.filePath, () => {
+            const data = this.readFile();
+            const completedIds = new Set(data.tasks.filter((t) => t.status === "completed").map((t) => t.id));
+            return data.tasks.filter((t) => t.status === "pending" &&
+                t.blockedBy.every((depId) => completedIds.has(depId)));
+        });
+    }
+    /** Summary string for display. */
+    formatStatus() {
+        const tasks = this.getTaskList();
+        if (tasks.length === 0)
+            return `Team "${this.teamName}": no tasks`;
+        const counts = {};
+        for (const t of tasks)
+            counts[t.status] = (counts[t.status] ?? 0) + 1;
+        const lines = [`Team "${this.teamName}" — ${tasks.length} tasks:`];
+        for (const t of tasks) {
+            const owner = t.owner ? ` [${t.owner}]` : "";
+            const blocked = t.blockedBy.length > 0 ? ` (blocked by: ${t.blockedBy.join(", ")})` : "";
+            lines.push(`  #${t.id} [${t.status}]${owner} ${t.subject}${blocked}`);
+        }
+        const summary = Object.entries(counts)
+            .map(([s, c]) => `${s}: ${c}`)
+            .join(", ");
+        lines.push(`  (${summary})`);
+        return lines.join("\n");
+    }
+}

package/dist/multi/diff-renderer.js

@@ -0,0 +1,175 @@
+/**
+ * Inline diff renderer — produces colored ANSI output for file edits.
+ *
+ * Uses a simple line-based diff (longest common subsequence) with no
+ * external dependencies. Output is capped at 30 lines.
+ */
+// ── ANSI helpers ─────────────────────────────────────────────────────────────
+const ESC = "\x1b[";
+const red = (t) => `${ESC}31m${t}${ESC}0m`;
+const green = (t) => `${ESC}32m${t}${ESC}0m`;
+const dim = (t) => `${ESC}2m${t}${ESC}0m`;
+const cyan = (t) => `${ESC}36m${t}${ESC}0m`;
+/**
+ * Compute a line-level diff between two arrays of strings.
+ * Uses the LCS (Longest Common Subsequence) approach for correctness.
+ */
+function computeLineDiff(oldLines, newLines) {
+    const m = oldLines.length;
+    const n = newLines.length;
+    // Build LCS table
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (oldLines[i - 1] === newLines[j - 1]) {
+                dp[i][j] = dp[i - 1][j - 1] + 1;
+            }
+            else {
+                dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+            }
+        }
+    }
+    // Backtrack to produce diff entries
+    const result = [];
+    let i = m;
+    let j = n;
+    while (i > 0 || j > 0) {
+        if (i > 0 && j > 0 && oldLines[i - 1] === newLines[j - 1]) {
+            result.push({ op: "equal", line: oldLines[i - 1], oldLineNo: i, newLineNo: j });
+            i--;
+            j--;
+        }
+        else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+            result.push({ op: "insert", line: newLines[j - 1], newLineNo: j });
+            j--;
+        }
+        else {
+            result.push({ op: "delete", line: oldLines[i - 1], oldLineNo: i });
+            i--;
+        }
+    }
+    result.reverse();
+    return result;
+}
+// ── Renderer ─────────────────────────────────────────────────────────────────
+const MAX_OUTPUT_LINES = 30;
+const MAX_FIRST_CHUNK = 20;
+const CONTEXT_LINES = 3;
+/**
+ * Render a colored inline diff between old and new file content.
+ *
+ * Output format:
+ *   ─── path/to/file ───
+ *   (context lines in gray, removed in red, added in green)
+ *   Collapsed unchanged sections shown as "... (N unchanged lines) ..."
+ *
+ * Capped at 30 output lines. If the diff is larger, shows the first 20
+ * lines plus a "... (N more changes)" trailer.
+ */
+export function renderInlineDiff(oldContent, newContent, filePath) {
+    const oldLines = oldContent.split("\n");
+    const newLines = newContent.split("\n");
+    const diff = computeLineDiff(oldLines, newLines);
+    // Identify which diff entries have changes nearby (within CONTEXT_LINES)
+    const hasChange = diff.map((d) => d.op !== "equal");
+    const visible = new Array(diff.length).fill(false);
+    for (let i = 0; i < diff.length; i++) {
+        if (hasChange[i]) {
+            for (let c = Math.max(0, i - CONTEXT_LINES); c <= Math.min(diff.length - 1, i + CONTEXT_LINES); c++) {
+                visible[c] = true;
+            }
+        }
+    }
+    // Build output lines
+    const outputLines = [];
+    let inCollapsed = false;
+    let collapsedCount = 0;
+    for (let i = 0; i < diff.length; i++) {
+        if (!visible[i]) {
+            if (!inCollapsed) {
+                inCollapsed = true;
+                collapsedCount = 0;
+            }
+            collapsedCount++;
+            continue;
+        }
+        // Emit collapsed marker if we just exited a collapsed section
+        if (inCollapsed) {
+            outputLines.push(dim(`  ... (${collapsedCount} unchanged lines) ...`));
+            inCollapsed = false;
+            collapsedCount = 0;
+        }
+        const d = diff[i];
+        const lineNo = d.oldLineNo ?? d.newLineNo ?? 0;
+        const lineNoStr = dim(String(lineNo).padStart(4) + " ");
+        switch (d.op) {
+            case "equal":
+                outputLines.push(lineNoStr + dim(d.line));
+                break;
+            case "delete":
+                outputLines.push(lineNoStr + red(`- ${d.line}`));
+                break;
+            case "insert":
+                outputLines.push(lineNoStr + green(`+ ${d.line}`));
+                break;
+        }
+    }
+    // Trailing collapsed section
+    if (inCollapsed) {
+        outputLines.push(dim(`  ... (${collapsedCount} unchanged lines) ...`));
+    }
+    // If no changes found
+    if (outputLines.length === 0) {
+        return "";
+    }
+    // Cap output
+    let body;
+    if (outputLines.length > MAX_OUTPUT_LINES) {
+        const truncated = outputLines.slice(0, MAX_FIRST_CHUNK);
+        const remaining = outputLines.length - MAX_FIRST_CHUNK;
+        truncated.push(dim(`  ... (${remaining} more lines) ...`));
+        body = truncated.join("\n");
+    }
+    else {
+        body = outputLines.join("\n");
+    }
+    const header = cyan(`─── ${filePath} ───`);
+    return `${header}\n${body}`;
+}
+/** Diff marker used in tool output to separate normal output from diff data. */
+export const DIFF_MARKER = "\n---DIFF---\n";
+/**
+ * Encode old + new content after the diff marker for downstream rendering.
+ * Format: `---DIFF---\nFILE:path\nOLD_LEN:N\n<old content>\nNEW_LEN:N\n<new content>`
+ */
+export function encodeDiffPayload(filePath, oldContent, newContent) {
+    return `${DIFF_MARKER}FILE:${filePath}\nOLD_LEN:${oldContent.length}\n${oldContent}\nNEW_LEN:${newContent.length}\n${newContent}`;
+}
+/**
+ * Detect and decode a diff payload from tool output.
+ * Returns null if no diff marker is found.
+ */
+export function decodeDiffPayload(output) {
+    const idx = output.indexOf(DIFF_MARKER);
+    if (idx === -1)
+        return null;
+    const payload = output.slice(idx + DIFF_MARKER.length);
+    const fileMatch = payload.match(/^FILE:(.+)\n/);
+    if (!fileMatch)
+        return null;
+    const filePath = fileMatch[1];
+    const rest = payload.slice(fileMatch[0].length);
+    const oldLenMatch = rest.match(/^OLD_LEN:(\d+)\n/);
+    if (!oldLenMatch)
+        return null;
+    const oldLen = parseInt(oldLenMatch[1], 10);
+    const afterOldHeader = rest.slice(oldLenMatch[0].length);
+    const oldContent = afterOldHeader.slice(0, oldLen);
+    const afterOld = afterOldHeader.slice(oldLen);
+    const newLenMatch = afterOld.match(/^\nNEW_LEN:(\d+)\n/);
+    if (!newLenMatch)
+        return null;
+    const newLen = parseInt(newLenMatch[1], 10);
+    const newContent = afterOld.slice(newLenMatch[0].length, newLenMatch[0].length + newLen);
+    return { filePath, oldContent, newContent };
+}

package/dist/multi/markdown.js

@@ -0,0 +1,96 @@
+/**
+ * Simple markdown-to-ANSI renderer for terminal output.
+ * Regex-based, no AST parser. Handles the common subset of markdown
+ * that LLMs produce: headers, bold, inline code, code blocks, bullet lists.
+ */
+const ESC = "\x1b[";
+const RESET = `${ESC}0m`;
+const BOLD = `${ESC}1m`;
+const DIM = `${ESC}2m`;
+const ITALIC = `${ESC}3m`;
+const CYAN = `${ESC}36m`;
+const YELLOW = `${ESC}33m`;
+const GREEN = `${ESC}32m`;
+const MAGENTA = `${ESC}35m`;
+const INVERSE = `${ESC}7m`;
+const MAX_WIDTH = 80;
+/** Render basic markdown to ANSI-colored terminal text. */
+export function renderMarkdown(text) {
+    const lines = text.split("\n");
+    const out = [];
+    let inCodeBlock = false;
+    let codeLang = "";
+    for (const line of lines) {
+        // Code block fences
+        if (line.trimStart().startsWith("```")) {
+            if (!inCodeBlock) {
+                inCodeBlock = true;
+                codeLang = line.trimStart().slice(3).trim();
+                const label = codeLang ? ` ${codeLang}` : "";
+                out.push(`${DIM}  ┌──${label}${"─".repeat(Math.max(0, MAX_WIDTH - 6 - label.length))}${RESET}`);
+            }
+            else {
+                inCodeBlock = false;
+                codeLang = "";
+                out.push(`${DIM}  └${"─".repeat(MAX_WIDTH - 3)}${RESET}`);
+            }
+            continue;
+        }
+        if (inCodeBlock) {
+            out.push(`${DIM}  │ ${line.slice(0, MAX_WIDTH - 4)}${RESET}`);
+            continue;
+        }
+        // Headers
+        const h3 = line.match(/^###\s+(.+)/);
+        if (h3) {
+            out.push(`${MAGENTA}${BOLD}   ${h3[1]}${RESET}`);
+            continue;
+        }
+        const h2 = line.match(/^##\s+(.+)/);
+        if (h2) {
+            out.push(`${GREEN}${BOLD}  ${h2[1]}${RESET}`);
+            continue;
+        }
+        const h1 = line.match(/^#\s+(.+)/);
+        if (h1) {
+            out.push(`${YELLOW}${BOLD}${h1[1]}${RESET}`);
+            continue;
+        }
+        // Bullet lists (-, *, +)
+        const bullet = line.match(/^(\s*)[*+-]\s+(.+)/);
+        if (bullet) {
+            const indent = bullet[1];
+            const content = renderInline(bullet[2]);
+            out.push(`${indent}  ${DIM}${BOLD}·${RESET} ${content}`);
+            continue;
+        }
+        // Numbered lists
+        const numbered = line.match(/^(\s*)\d+[.)]\s+(.+)/);
+        if (numbered) {
+            const indent = numbered[1];
+            const num = line.match(/^(\s*)(\d+[.)])/);
+            const content = renderInline(numbered[2]);
+            out.push(`${indent}  ${DIM}${num[2]}${RESET} ${content}`);
+            continue;
+        }
+        // Regular line — apply inline formatting
+        out.push(renderInline(line));
+    }
+    return out.join("\n");
+}
+/** Apply inline formatting: bold, italic, inline code. */
+function renderInline(text) {
+    let result = text;
+    // Inline code (must go first to avoid bold/italic inside code)
+    result = result.replace(/`([^`]+)`/g, `${CYAN}${INVERSE} $1 ${RESET}`);
+    // Bold+italic (***text*** or ___text___)
+    result = result.replace(/\*\*\*(.+?)\*\*\*/g, `${BOLD}${ITALIC}$1${RESET}`);
+    result = result.replace(/___(.+?)___/g, `${BOLD}${ITALIC}$1${RESET}`);
+    // Bold (**text** or __text__)
+    result = result.replace(/\*\*(.+?)\*\*/g, `${BOLD}$1${RESET}`);
+    result = result.replace(/__(.+?)__/g, `${BOLD}$1${RESET}`);
+    // Italic (*text* or _text_ — careful not to match mid-word underscores)
+    result = result.replace(/(?<!\w)\*([^*]+)\*(?!\w)/g, `${ITALIC}$1${RESET}`);
+    result = result.replace(/(?<!\w)_([^_]+)_(?!\w)/g, `${ITALIC}$1${RESET}`);
+    return result;
+}

package/dist/multi/presets.js

@@ -0,0 +1,107 @@
+/**
+ * Agent config presets — save/load provider+model+permissions combos.
+ *
+ * User presets stored at ~/.phren-agent/presets.json.
+ * Built-in presets are always available and cannot be overwritten.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+// ── Built-in presets ────────────────────────────────────────────────────
+const BUILTIN_PRESETS = {
+    fast: {
+        provider: "ollama",
+        permissions: "auto-confirm",
+        maxTurns: 20,
+    },
+    careful: {
+        provider: "anthropic",
+        permissions: "suggest",
+        plan: true,
+    },
+    yolo: {
+        provider: "openrouter",
+        permissions: "full-auto",
+        maxTurns: 100,
+        budget: null,
+    },
+};
+const BUILTIN_NAMES = new Set(Object.keys(BUILTIN_PRESETS));
+// ── File path ───────────────────────────────────────────────────────────
+const PRESETS_PATH = path.join(os.homedir(), ".phren-agent", "presets.json");
+// ── File I/O ────────────────────────────────────────────────────────────
+function readFile() {
+    try {
+        const raw = fs.readFileSync(PRESETS_PATH, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { presets: {} };
+    }
+}
+function writeFile(data) {
+    const dir = path.dirname(PRESETS_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(PRESETS_PATH, JSON.stringify(data, null, 2) + "\n");
+}
+// ── Public API ──────────────────────────────────────────────────────────
+/** Save a user preset. Cannot overwrite built-in names. */
+export function savePreset(name, config) {
+    if (BUILTIN_NAMES.has(name)) {
+        throw new Error(`Cannot overwrite built-in preset "${name}".`);
+    }
+    const data = readFile();
+    data.presets[name] = config;
+    writeFile(data);
+}
+/** Load a preset by name. Checks built-ins first, then user presets. */
+export function loadPreset(name) {
+    if (BUILTIN_PRESETS[name]) {
+        return { ...BUILTIN_PRESETS[name] };
+    }
+    const data = readFile();
+    const preset = data.presets[name];
+    return preset ? { ...preset } : null;
+}
+/** Delete a user preset. Cannot delete built-in presets. */
+export function deletePreset(name) {
+    if (BUILTIN_NAMES.has(name)) {
+        throw new Error(`Cannot delete built-in preset "${name}".`);
+    }
+    const data = readFile();
+    if (!(name in data.presets))
+        return false;
+    delete data.presets[name];
+    writeFile(data);
+    return true;
+}
+/** List all presets: built-in + user. */
+export function listPresets() {
+    const results = [];
+    for (const [name, preset] of Object.entries(BUILTIN_PRESETS)) {
+        results.push({ name, preset, builtin: true });
+    }
+    const data = readFile();
+    for (const [name, preset] of Object.entries(data.presets)) {
+        results.push({ name, preset, builtin: false });
+    }
+    return results;
+}
+/** Format a preset for display. */
+export function formatPreset(name, preset, builtin) {
+    const parts = [];
+    if (preset.provider)
+        parts.push(`provider=${preset.provider}`);
+    if (preset.model)
+        parts.push(`model=${preset.model}`);
+    if (preset.permissions)
+        parts.push(`perms=${preset.permissions}`);
+    if (preset.maxTurns !== undefined)
+        parts.push(`turns=${preset.maxTurns}`);
+    if (preset.budget !== undefined)
+        parts.push(preset.budget === null ? "no-budget" : `budget=$${preset.budget}`);
+    if (preset.plan)
+        parts.push("plan");
+    const tag = builtin ? " (built-in)" : "";
+    return `${name}${tag}: ${parts.join(", ")}`;
+}

package/dist/multi/progress.js

@@ -0,0 +1,32 @@
+/**
+ * Progress indicators for terminal output.
+ */
+const FILLED = "█";
+const EMPTY = "░";
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Render a progress bar: `[████░░░░] 50%` */
+export function renderProgressBar(current, total, width = 20) {
+    if (total <= 0)
+        return `[${"░".repeat(width)}] 0%`;
+    const pct = Math.min(1, Math.max(0, current / total));
+    const filled = Math.round(pct * width);
+    const empty = width - filled;
+    const percent = Math.round(pct * 100);
+    return `[${FILLED.repeat(filled)}${EMPTY.repeat(empty)}] ${percent}%`;
+}
+/** Get a braille spinner frame by index (wraps automatically). */
+export function renderSpinnerFrame(frame) {
+    return SPINNER_FRAMES[frame % SPINNER_FRAMES.length];
+}
+/** Format elapsed time from a start timestamp: `2.1s` or `1m 30s`. */
+export function renderElapsed(startMs) {
+    const elapsed = Date.now() - startMs;
+    if (elapsed < 1000)
+        return `${elapsed}ms`;
+    const secs = elapsed / 1000;
+    if (secs < 60)
+        return `${secs.toFixed(1)}s`;
+    const mins = Math.floor(secs / 60);
+    const remSecs = Math.round(secs % 60);
+    return `${mins}m ${remSecs}s`;
+}