@phren/agent 0.0.1

package/dist/memory/context.js

@@ -0,0 +1,170 @@
+import * as fs from "fs";
+import * as path from "path";
+import { findPhrenPath, getProjectDirs } from "@phren/cli/paths";
+import { resolveRuntimeProfile } from "@phren/cli/runtime-profile";
+import { buildIndex } from "@phren/cli/shared";
+import { searchKnowledgeRows, rankResults } from "@phren/cli/shared/retrieval";
+import { readTasks } from "@phren/cli/data/tasks";
+import { readFindings } from "@phren/cli/data/access";
+/** Try to find phren path and detect the active project from cwd. */
+export async function buildPhrenContext(projectOverride) {
+    try {
+        const phrenPath = findPhrenPath();
+        if (!phrenPath || !fs.existsSync(phrenPath))
+            return null;
+        let profile = "";
+        try {
+            profile = resolveRuntimeProfile(phrenPath) ?? "";
+        }
+        catch { /* no profile */ }
+        let project = projectOverride ?? null;
+        if (!project) {
+            try {
+                const projectDirs = getProjectDirs(phrenPath, profile || undefined);
+                const cwd = process.cwd();
+                for (const dir of projectDirs) {
+                    const name = path.basename(dir);
+                    try {
+                        const configPath = path.join(dir, "project.yaml");
+                        if (fs.existsSync(configPath)) {
+                            const content = fs.readFileSync(configPath, "utf-8");
+                            const sourceMatch = content.match(/source:\s*(.+)/);
+                            if (sourceMatch?.[1]) {
+                                const sourcePath = sourceMatch[1].trim().replace(/^['"]|['"]$/g, "");
+                                if (cwd.startsWith(sourcePath) || cwd === sourcePath) {
+                                    project = name;
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    catch { /* skip */ }
+                    if (path.basename(cwd) === name) {
+                        project = name;
+                        break;
+                    }
+                }
+            }
+            catch { /* no project detection */ }
+        }
+        return { phrenPath, profile, project };
+    }
+    catch {
+        return null;
+    }
+}
+/** Read truths.md pinned entries for a project. */
+function readTruths(phrenPath, project) {
+    try {
+        const truthsPath = path.join(phrenPath, project, "truths.md");
+        if (!fs.existsSync(truthsPath))
+            return [];
+        const content = fs.readFileSync(truthsPath, "utf-8");
+        return content.split("\n").filter((line) => line.startsWith("- "));
+    }
+    catch {
+        return [];
+    }
+}
+/** Read source path from project.yaml. */
+function readProjectSourcePath(phrenPath, project) {
+    try {
+        const configPath = path.join(phrenPath, project, "project.yaml");
+        if (!fs.existsSync(configPath))
+            return null;
+        const content = fs.readFileSync(configPath, "utf-8");
+        const match = content.match(/source:\s*(.+)/);
+        if (!match?.[1])
+            return null;
+        return match[1].trim().replace(/^['"]|['"]$/g, "");
+    }
+    catch {
+        return null;
+    }
+}
+/** Build a context string from phren knowledge to inject into the system prompt. */
+export async function buildContextSnippet(ctx, taskKeywords) {
+    const sections = [];
+    const label = ctx.project ?? "global";
+    // Section 1: Pinned truths
+    if (ctx.project) {
+        try {
+            const truths = readTruths(ctx.phrenPath, ctx.project);
+            if (truths.length > 0) {
+                sections.push(`## Pinned truths (${label})\n\n${truths.join("\n")}`);
+            }
+        }
+        catch { /* silent */ }
+    }
+    // Section 2: Active tasks
+    if (ctx.project) {
+        try {
+            const result = readTasks(ctx.phrenPath, ctx.project);
+            if (result.ok && result.data) {
+                const items = result.data.items;
+                const lines = [];
+                const active = items.Active?.slice(0, 5) ?? [];
+                const queue = items.Queue?.slice(0, 3) ?? [];
+                for (const t of active)
+                    lines.push(`- [Active] ${t.line}`);
+                for (const t of queue)
+                    lines.push(`- [Queue] ${t.line}`);
+                if (lines.length > 0) {
+                    sections.push(`## Tasks (${label})\n\n${lines.join("\n")}`);
+                }
+            }
+        }
+        catch { /* silent */ }
+    }
+    // Section 3: Recent findings
+    if (ctx.project) {
+        try {
+            const result = readFindings(ctx.phrenPath, ctx.project);
+            if (result.ok && result.data) {
+                const active = result.data
+                    .filter((f) => f.status === "active" && f.tier !== "archived")
+                    .slice(-5);
+                if (active.length > 0) {
+                    const lines = active.map((f) => `- ${f.text}`);
+                    sections.push(`## Recent findings (${label})\n\n${lines.join("\n")}`);
+                }
+            }
+        }
+        catch { /* silent */ }
+    }
+    // Section 4: Project CLAUDE.md
+    if (ctx.project) {
+        try {
+            const sourcePath = readProjectSourcePath(ctx.phrenPath, ctx.project);
+            if (sourcePath) {
+                const claudePath = path.join(sourcePath, "CLAUDE.md");
+                if (fs.existsSync(claudePath)) {
+                    const content = fs.readFileSync(claudePath, "utf-8").slice(0, 800);
+                    sections.push(`## Project CLAUDE.md (${label})\n\n${content}`);
+                }
+            }
+        }
+        catch { /* silent */ }
+    }
+    // Section 5: FTS5 search
+    try {
+        const db = await buildIndex(ctx.phrenPath, ctx.profile || undefined);
+        const result = await searchKnowledgeRows(db, {
+            query: taskKeywords,
+            maxResults: 10,
+            filterProject: ctx.project || null,
+            filterType: null,
+            phrenPath: ctx.phrenPath,
+        });
+        const ranked = rankResults(result.rows ?? [], taskKeywords, null, ctx.project || null, ctx.phrenPath, db);
+        if (ranked.length > 0) {
+            const snippets = ranked.slice(0, 5).map((r) => {
+                const content = r.content?.slice(0, 400) ?? "";
+                return `[${r.project}/${r.filename}] ${content}`;
+            });
+            sections.push(`## Related knowledge (${label})\n\n${snippets.join("\n\n")}`);
+        }
+    }
+    catch { /* silent */ }
+    return sections.join("\n\n");
+}

package/dist/memory/error-recovery.js

@@ -0,0 +1,58 @@
+import { buildIndex } from "@phren/cli/shared";
+import { searchKnowledgeRows, rankResults } from "@phren/cli/shared/retrieval";
+const NOISE_WORDS = new Set([
+    "at", "in", "of", "the", "is", "was", "error", "err", "warning",
+    "from", "to", "and", "or", "not", "with", "for", "on", "by",
+    "null", "undefined", "true", "false", "function", "object",
+]);
+const HEX_PATTERN = /\b0x[0-9a-f]+\b/gi;
+const STACK_LINE = /^\s+at\s+/;
+const PATH_NOISE = /\(?\/?[\w./\\-]+:\d+:\d+\)?/g;
+/** Extract meaningful keywords from an error string. */
+function extractErrorKeywords(errorOutput) {
+    const lines = errorOutput.split("\n");
+    // Keep only non-stack-trace lines
+    const meaningful = lines
+        .filter((l) => !STACK_LINE.test(l))
+        .slice(0, 5)
+        .join(" ");
+    const cleaned = meaningful
+        .replace(HEX_PATTERN, "")
+        .replace(PATH_NOISE, "")
+        .replace(/[^a-zA-Z0-9_\s.-]/g, " ");
+    const words = cleaned
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !NOISE_WORDS.has(w.toLowerCase()))
+        .slice(0, 12);
+    return words.join(" ");
+}
+/**
+ * Search phren for past knowledge related to a tool error.
+ * Returns a formatted context string, or empty string on no results / error.
+ */
+export async function searchErrorRecovery(ctx, errorOutput) {
+    try {
+        const keywords = extractErrorKeywords(errorOutput);
+        if (!keywords.trim())
+            return "";
+        const db = await buildIndex(ctx.phrenPath, ctx.profile || undefined);
+        const result = await searchKnowledgeRows(db, {
+            query: keywords,
+            maxResults: 6,
+            filterProject: ctx.project || null,
+            filterType: null,
+            phrenPath: ctx.phrenPath,
+        });
+        const ranked = rankResults(result.rows ?? [], keywords, null, ctx.project || null, ctx.phrenPath, db);
+        if (ranked.length === 0)
+            return "";
+        const snippets = ranked.slice(0, 3).map((r) => {
+            const content = r.content?.slice(0, 300) ?? "";
+            return `[${r.project}/${r.filename}] ${content}`;
+        });
+        return `\n\n--- phren recovery context ---\n${snippets.join("\n\n")}`;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/memory/project-context.js

@@ -0,0 +1,77 @@
+/**
+ * Project context evolution: lightweight LLM reflection at session end
+ * and warm-start context loading.
+ */
+import * as fs from "fs";
+import * as path from "path";
+const CONTEXT_FILE = "agent-context.md";
+const MAX_DATE_SECTIONS = 3;
+function contextPath(ctx) {
+    if (!ctx.project)
+        return null;
+    return path.join(ctx.phrenPath, ctx.project, CONTEXT_FILE);
+}
+/**
+ * Load the last N date sections from agent-context.md for warm start.
+ */
+export function loadProjectContext(ctx) {
+    const file = contextPath(ctx);
+    if (!file || !fs.existsSync(file))
+        return "";
+    try {
+        const content = fs.readFileSync(file, "utf-8");
+        const sections = content.split(/(?=^## \d{4}-\d{2}-\d{2})/m).filter(Boolean);
+        const recent = sections.slice(-MAX_DATE_SECTIONS);
+        return recent.join("\n").trim();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Run a lightweight LLM reflection at session end and append to agent-context.md.
+ * Summarizes key learnings from the conversation.
+ */
+export async function evolveProjectContext(ctx, provider, sessionMessages) {
+    const file = contextPath(ctx);
+    if (!file)
+        return;
+    // Build a condensed conversation summary for the reflection prompt
+    const condensed = sessionMessages
+        .slice(-20) // last 20 messages max
+        .map((m) => {
+        if (typeof m.content === "string")
+            return `${m.role}: ${m.content.slice(0, 200)}`;
+        const text = m.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text.slice(0, 150))
+            .join(" ");
+        const tools = m.content
+            .filter((b) => b.type === "tool_use")
+            .map((b) => b.name);
+        const parts = [text, tools.length > 0 ? `[tools: ${tools.join(", ")}]` : ""].filter(Boolean);
+        return `${m.role}: ${parts.join(" ")}`;
+    })
+        .join("\n");
+    const reflectionPrompt = "Based on this conversation excerpt, extract 2-4 key learnings about this project " +
+        "(patterns, pitfalls, architecture decisions, important paths/configs). " +
+        "Be extremely concise — one line per point. Output only the bullet points, nothing else.\n\n" +
+        condensed;
+    try {
+        const response = await provider.chat("You are a concise technical note-taker.", [{ role: "user", content: reflectionPrompt }], []);
+        const reflection = response.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text)
+            .join("\n")
+            .trim();
+        if (!reflection || reflection.length < 10)
+            return;
+        const date = new Date().toISOString().slice(0, 10);
+        const entry = `\n## ${date}\n\n${reflection}\n`;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, entry);
+    }
+    catch {
+        // best effort — don't fail the session over this
+    }
+}

package/dist/memory/session.js

@@ -0,0 +1,100 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+function sessionsDir(phrenPath) {
+    const dir = path.join(phrenPath, ".runtime", "sessions");
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function sessionFile(phrenPath, sessionId) {
+    return path.join(sessionsDir(phrenPath), `session-${sessionId}.json`);
+}
+export function startSession(ctx) {
+    const sessionId = crypto.randomUUID();
+    const state = {
+        sessionId,
+        project: ctx.project || undefined,
+        startedAt: new Date().toISOString(),
+        findingsAdded: 0,
+        tasksCompleted: 0,
+        agentCreated: true,
+    };
+    const file = sessionFile(ctx.phrenPath, sessionId);
+    fs.writeFileSync(file, JSON.stringify(state, null, 2) + "\n");
+    return sessionId;
+}
+export function endSession(ctx, sessionId, summary) {
+    const file = sessionFile(ctx.phrenPath, sessionId);
+    if (!fs.existsSync(file))
+        return;
+    try {
+        const state = JSON.parse(fs.readFileSync(file, "utf-8"));
+        state.endedAt = new Date().toISOString();
+        if (summary) {
+            // Also write to last-summary.json for fast pickup by next session_start
+            const summaryFile = path.join(sessionsDir(ctx.phrenPath), "last-summary.json");
+            fs.writeFileSync(summaryFile, JSON.stringify({
+                summary,
+                sessionId,
+                project: state.project,
+                endedAt: state.endedAt,
+            }, null, 2) + "\n");
+        }
+        fs.writeFileSync(file, JSON.stringify(state, null, 2) + "\n");
+    }
+    catch { /* best effort */ }
+}
+export function incrementSessionCounter(phrenPath, sessionId, counter) {
+    const file = sessionFile(phrenPath, sessionId);
+    if (!fs.existsSync(file))
+        return;
+    try {
+        const state = JSON.parse(fs.readFileSync(file, "utf-8"));
+        state[counter] = (state[counter] ?? 0) + 1;
+        fs.writeFileSync(file, JSON.stringify(state, null, 2) + "\n");
+    }
+    catch { /* best effort */ }
+}
+/** Read the most recent session summary for prior context. */
+export function getPriorSummary(ctx) {
+    try {
+        const summaryFile = path.join(sessionsDir(ctx.phrenPath), "last-summary.json");
+        if (!fs.existsSync(summaryFile))
+            return null;
+        const data = JSON.parse(fs.readFileSync(summaryFile, "utf-8"));
+        return data.summary || null;
+    }
+    catch {
+        return null;
+    }
+}
+function messagesDir(phrenPath) {
+    const dir = path.join(phrenPath, ".runtime", "sessions");
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** Save session messages for later resume. */
+export function saveSessionMessages(phrenPath, sessionId, messages) {
+    const file = path.join(messagesDir(phrenPath), `session-${sessionId}-messages.json`);
+    fs.writeFileSync(file, JSON.stringify(messages, null, 2) + "\n");
+}
+/** Load the last session's messages for resume. Returns null if none found. */
+export function loadLastSessionMessages(phrenPath) {
+    try {
+        const dir = messagesDir(phrenPath);
+        const files = fs.readdirSync(dir)
+            .filter(f => f.endsWith("-messages.json"))
+            .map(f => ({
+            name: f,
+            mtime: fs.statSync(path.join(dir, f)).mtimeMs,
+        }))
+            .sort((a, b) => b.mtime - a.mtime);
+        if (files.length === 0)
+            return null;
+        const data = fs.readFileSync(path.join(dir, files[0].name), "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/multi/agent-colors.js

@@ -0,0 +1,41 @@
+/**
+ * Unique colors and icons for spawned agents.
+ *
+ * Each agent gets a deterministic style based on its index (mod array length),
+ * so the same slot always looks the same even across re-renders.
+ */
+const ESC = "\x1b[";
+const RESET = `${ESC}0m`;
+// ── Color palette (8 distinct ANSI colors) ──────────────────────────────────
+const AGENT_COLORS = [
+    { name: "cyan", code: "36" },
+    { name: "magenta", code: "35" },
+    { name: "yellow", code: "33" },
+    { name: "green", code: "32" },
+    { name: "blue", code: "34" },
+    { name: "red", code: "31" },
+    { name: "white", code: "37" },
+    { name: "bright-cyan", code: "96" },
+];
+// ── Icon palette (8 unicode icons) ──────────────────────────────────────────
+const AGENT_ICONS = ["◆", "◇", "●", "○", "■", "□", "▲", "★"];
+/** Get a deterministic style for agent at the given index. */
+export function getAgentStyle(index) {
+    const c = AGENT_COLORS[index % AGENT_COLORS.length];
+    const icon = AGENT_ICONS[index % AGENT_ICONS.length];
+    return {
+        color: (text) => `${ESC}${c.code}m${text}${RESET}`,
+        icon,
+        colorName: c.name,
+    };
+}
+/** Format an agent name with its icon and color: "◆ agent-name" */
+export function formatAgentName(name, index) {
+    const { color, icon } = getAgentStyle(index);
+    return color(`${icon} ${name}`);
+}
+/** Prefix a line with the agent's icon in its color. */
+export function prefixLine(line, index) {
+    const { color, icon } = getAgentStyle(index);
+    return `${color(icon)} ${line}`;
+}

package/dist/multi/child-entry.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Child agent entry point — standalone process that:
+ * 1. Receives SpawnPayload via IPC from parent
+ * 2. Resolves the LLM provider
+ * 3. Registers the standard tool set
+ * 4. Runs the agent loop with TurnHooks that serialize events back via process.send()
+ * 5. Sends a final "done" message with the result
+ */
+import { resolveProvider } from "../providers/resolve.js";
+import { ToolRegistry } from "../tools/registry.js";
+import { readFileTool } from "../tools/read-file.js";
+import { writeFileTool } from "../tools/write-file.js";
+import { editFileTool } from "../tools/edit-file.js";
+import { shellTool } from "../tools/shell.js";
+import { globTool } from "../tools/glob.js";
+import { grepTool } from "../tools/grep.js";
+import { createPhrenSearchTool } from "../tools/phren-search.js";
+import { createPhrenFindingTool } from "../tools/phren-finding.js";
+import { createPhrenGetTasksTool, createPhrenCompleteTaskTool } from "../tools/phren-tasks.js";
+import { gitStatusTool, gitDiffTool, gitCommitTool } from "../tools/git.js";
+import { buildPhrenContext, buildContextSnippet } from "../memory/context.js";
+import { startSession, endSession, getPriorSummary } from "../memory/session.js";
+import { loadProjectContext } from "../memory/project-context.js";
+import { buildSystemPrompt } from "../system-prompt.js";
+import { runAgent } from "../agent-loop.js";
+import { createCostTracker } from "../cost.js";
+let cancelled = false;
+/** Send a typed message to the parent process. */
+function send(msg) {
+    if (process.send) {
+        process.send(msg);
+    }
+}
+/** Build TurnHooks that relay all events to the parent via IPC. */
+function createIpcHooks(agentId) {
+    return {
+        onTextDelta(text) {
+            send({ type: "text_delta", agentId, text });
+        },
+        onTextDone() {
+            // No-op — parent reconstructs from deltas
+        },
+        onTextBlock(text) {
+            send({ type: "text_block", agentId, text });
+        },
+        onToolStart(name, input, count) {
+            send({ type: "tool_start", agentId, toolName: name, input, count });
+        },
+        onToolEnd(name, input, output, isError, durationMs) {
+            send({ type: "tool_end", agentId, toolName: name, input, output, isError, durationMs });
+        },
+        onStatus(msg) {
+            send({ type: "status", agentId, message: msg });
+        },
+    };
+}
+/** Run the agent with the given spawn payload. */
+async function runChildAgent(payload) {
+    const { agentId, task, cwd, provider: providerName, model, project, permissions, maxTurns, budget, plan, verbose } = payload;
+    // Set cwd
+    process.chdir(cwd);
+    // Resolve LLM provider
+    let provider;
+    try {
+        provider = resolveProvider(providerName, model);
+    }
+    catch (err) {
+        send({ type: "error", agentId, error: err instanceof Error ? err.message : String(err) });
+        process.exit(1);
+    }
+    // Build phren context
+    const phrenCtx = await buildPhrenContext(project);
+    let contextSnippet = "";
+    let priorSummary = null;
+    let sessionId = null;
+    if (phrenCtx) {
+        contextSnippet = await buildContextSnippet(phrenCtx, task);
+        priorSummary = getPriorSummary(phrenCtx);
+        sessionId = startSession(phrenCtx);
+        const projectCtx = loadProjectContext(phrenCtx);
+        if (projectCtx) {
+            contextSnippet += `\n\n## Agent context (${phrenCtx.project})\n\n${projectCtx}`;
+        }
+    }
+    const systemPrompt = buildSystemPrompt(contextSnippet, priorSummary);
+    // Register tools
+    const registry = new ToolRegistry();
+    registry.setPermissions({
+        mode: permissions,
+        allowedPaths: [],
+        projectRoot: cwd,
+    });
+    registry.register(readFileTool);
+    registry.register(writeFileTool);
+    registry.register(editFileTool);
+    registry.register(shellTool);
+    registry.register(globTool);
+    registry.register(grepTool);
+    if (phrenCtx) {
+        registry.register(createPhrenSearchTool(phrenCtx));
+        registry.register(createPhrenFindingTool(phrenCtx, sessionId));
+        registry.register(createPhrenGetTasksTool(phrenCtx));
+        registry.register(createPhrenCompleteTaskTool(phrenCtx, sessionId));
+    }
+    registry.register(gitStatusTool);
+    registry.register(gitDiffTool);
+    registry.register(gitCommitTool);
+    // Cost tracker
+    const modelName = model ?? provider.name;
+    const costTracker = createCostTracker(modelName, budget);
+    const config = {
+        provider,
+        registry,
+        systemPrompt,
+        maxTurns,
+        verbose,
+        phrenCtx,
+        costTracker,
+        plan,
+    };
+    // Run the agent
+    try {
+        const result = await runAgent(task, config);
+        // End phren session
+        if (phrenCtx && sessionId) {
+            const summary = result.finalText.slice(0, 500);
+            endSession(phrenCtx, sessionId, summary);
+        }
+        send({
+            type: "done",
+            agentId,
+            result: {
+                finalText: result.finalText,
+                turns: result.turns,
+                toolCalls: result.toolCalls,
+                totalCost: result.totalCost,
+            },
+        });
+    }
+    catch (err) {
+        if (phrenCtx && sessionId) {
+            endSession(phrenCtx, sessionId, `Error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        send({
+            type: "error",
+            agentId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        process.exit(1);
+    }
+}
+// ── Main: wait for spawn payload from parent ────────────────────────────────
+process.on("message", (msg) => {
+    if (msg.type === "spawn") {
+        runChildAgent(msg).then(() => {
+            process.exit(0);
+        }).catch((err) => {
+            const agentId = msg.agentId;
+            send({ type: "error", agentId, error: err instanceof Error ? err.message : String(err) });
+            process.exit(1);
+        });
+    }
+    else if (msg.type === "cancel") {
+        cancelled = true;
+        process.exit(130);
+    }
+});
+// If no IPC channel (run directly), exit with error
+if (!process.send) {
+    process.stderr.write("child-entry.ts must be spawned via AgentSpawner (requires IPC channel)\n");
+    process.exit(1);
+}