@phren/agent 0.0.1

package/dist/index.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+import { parseArgs, printHelp } from "./config.js";
+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, saveSessionMessages, loadLastSessionMessages } from "./memory/session.js";
+import { loadProjectContext, evolveProjectContext } from "./memory/project-context.js";
+import { buildSystemPrompt } from "./system-prompt.js";
+import { runAgent, createSession, runTurn } from "./agent-loop.js";
+import { createCostTracker } from "./cost.js";
+import { codexLogin, codexLogout } from "./providers/codex-auth.js";
+import { createCheckpoint } from "./checkpoint.js";
+import { detectLintCommand, detectTestCommand } from "./tools/lint-test.js";
+import { connectMcpServers, loadMcpConfig, parseMcpInline } from "./mcp-client.js";
+const VERSION = "0.0.1";
+/**
+ * Run the agent CLI with the given argv tokens.
+ * Called from `phren agent ...` or directly via `phren-agent ...`.
+ */
+export async function runAgentCli(raw) {
+    // Handle auth subcommands before normal arg parsing
+    if (raw[0] === "auth") {
+        if (raw[1] === "login") {
+            await codexLogin();
+            process.exit(0);
+        }
+        if (raw[1] === "logout") {
+            codexLogout();
+            process.exit(0);
+        }
+        console.error("Usage: phren-agent auth login|logout");
+        process.exit(1);
+    }
+    const args = parseArgs(raw);
+    if (args.help) {
+        printHelp();
+        process.exit(0);
+    }
+    if (args.version) {
+        console.log(`phren-agent v${VERSION}`);
+        process.exit(0);
+    }
+    if (!args.task && !args.interactive && !args.multi && !args.team) {
+        console.error("Usage: phren-agent <task>\nRun phren-agent --help for more info.");
+        process.exit(1);
+    }
+    // Resolve LLM provider
+    let provider;
+    try {
+        provider = resolveProvider(args.provider, args.model);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    }
+    if (args.verbose) {
+        process.stderr.write(`Provider: ${provider.name}\n`);
+    }
+    // Build phren context
+    const phrenCtx = await buildPhrenContext(args.project);
+    let contextSnippet = "";
+    let priorSummary = null;
+    let sessionId = null;
+    if (phrenCtx) {
+        if (args.verbose) {
+            process.stderr.write(`Phren: ${phrenCtx.phrenPath} (project: ${phrenCtx.project ?? "none"})\n`);
+        }
+        contextSnippet = await buildContextSnippet(phrenCtx, args.task);
+        priorSummary = getPriorSummary(phrenCtx);
+        sessionId = startSession(phrenCtx);
+        // Load evolved project context for warm start
+        const projectCtx = loadProjectContext(phrenCtx);
+        if (projectCtx) {
+            contextSnippet += `\n\n## Agent context (${phrenCtx.project})\n\n${projectCtx}`;
+        }
+    }
+    const systemPrompt = buildSystemPrompt(contextSnippet, priorSummary);
+    // Dry run: print system prompt and exit
+    if (args.dryRun) {
+        console.log("=== System Prompt ===");
+        console.log(systemPrompt);
+        console.log("\n=== Task ===");
+        console.log(args.task);
+        process.exit(0);
+    }
+    // Register tools
+    const registry = new ToolRegistry();
+    registry.setPermissions({
+        mode: args.permissions,
+        allowedPaths: [],
+        projectRoot: process.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));
+    }
+    // Git tools
+    registry.register(gitStatusTool);
+    registry.register(gitDiffTool);
+    registry.register(gitCommitTool);
+    // MCP server connections
+    let mcpCleanup;
+    const mcpServers = {};
+    if (args.mcpConfig) {
+        Object.assign(mcpServers, loadMcpConfig(args.mcpConfig));
+    }
+    for (let idx = 0; idx < args.mcp.length; idx++) {
+        const entry = parseMcpInline(args.mcp[idx]);
+        mcpServers[`mcp-${idx}`] = entry;
+    }
+    if (Object.keys(mcpServers).length > 0) {
+        const { tools: mcpTools, cleanup } = await connectMcpServers(mcpServers, args.verbose);
+        mcpCleanup = cleanup;
+        for (const tool of mcpTools)
+            registry.register(tool);
+    }
+    // Build cost tracker from model info
+    const modelName = args.model ?? provider.name;
+    const costTracker = createCostTracker(modelName, args.budget);
+    // Build lint/test config from CLI flags or auto-detect
+    const cwd = process.cwd();
+    const lintCmd = args.lintCmd ?? detectLintCommand(cwd);
+    const testCmd = args.testCmd ?? detectTestCommand(cwd);
+    const lintTestConfig = (lintCmd || testCmd) ? { lintCmd: lintCmd ?? undefined, testCmd: testCmd ?? undefined } : undefined;
+    if (args.verbose && lintTestConfig) {
+        if (lintTestConfig.lintCmd)
+            process.stderr.write(`Lint: ${lintTestConfig.lintCmd}\n`);
+        if (lintTestConfig.testCmd)
+            process.stderr.write(`Test: ${lintTestConfig.testCmd}\n`);
+    }
+    const agentConfig = {
+        provider,
+        registry,
+        systemPrompt,
+        maxTurns: args.maxTurns,
+        verbose: args.verbose,
+        phrenCtx,
+        costTracker,
+        plan: args.plan,
+        lintTestConfig,
+    };
+    // Multi-agent TUI mode
+    if (args.multi || args.team) {
+        const { AgentSpawner } = await import("./multi/spawner.js");
+        const { startMultiTui } = await import("./multi/tui-multi.js");
+        const spawner = new AgentSpawner();
+        process.on("SIGINT", async () => {
+            await spawner.shutdown();
+            process.exit(130);
+        });
+        await startMultiTui(spawner, agentConfig);
+        await spawner.shutdown();
+        if (phrenCtx && sessionId) {
+            endSession(phrenCtx, sessionId, "Multi-agent session ended");
+        }
+        mcpCleanup?.();
+        return;
+    }
+    // Interactive mode — TUI if terminal, fallback to REPL if not
+    if (args.interactive) {
+        const isTTY = process.stdout.isTTY && process.stdin.isTTY;
+        const session = isTTY
+            ? await (await import("./tui.js")).startTui(agentConfig)
+            : await (await import("./repl.js")).startRepl(agentConfig);
+        // Flush anti-patterns at session end
+        if (phrenCtx) {
+            try {
+                await session.antiPatterns.flushAntiPatterns(phrenCtx);
+            }
+            catch { /* best effort */ }
+            try {
+                await evolveProjectContext(phrenCtx, provider, session.messages);
+            }
+            catch { /* best effort */ }
+        }
+        if (phrenCtx && sessionId) {
+            const lastText = session.messages.length > 0 ? "Interactive session ended" : "Empty session";
+            endSession(phrenCtx, sessionId, lastText);
+        }
+        mcpCleanup?.();
+        return;
+    }
+    // Create initial checkpoint before agent starts
+    const initCheckpoint = createCheckpoint(cwd, "pre-agent");
+    if (args.verbose && initCheckpoint) {
+        process.stderr.write(`Checkpoint: ${initCheckpoint.slice(0, 8)}\n`);
+    }
+    // SIGINT handler: offer rollback
+    process.on("SIGINT", () => {
+        process.stderr.write("\nInterrupted. Use --resume to continue later.\n");
+        if (process.stdin.isTTY) {
+            try {
+                process.stdin.setRawMode(false);
+            }
+            catch { }
+        }
+        mcpCleanup?.();
+        if (phrenCtx && sessionId) {
+            endSession(phrenCtx, sessionId, "Interrupted by user");
+        }
+        process.exit(130);
+    });
+    // One-shot mode
+    try {
+        let result;
+        if (args.resume && phrenCtx) {
+            // Resume: load previous messages and continue
+            const prevMessages = loadLastSessionMessages(phrenCtx.phrenPath);
+            if (prevMessages && prevMessages.length > 0) {
+                if (args.verbose)
+                    process.stderr.write(`Resuming session with ${prevMessages.length} messages\n`);
+                const contextLimit = provider.contextWindow ?? 200_000;
+                const session = createSession(contextLimit);
+                session.messages = prevMessages;
+                const turnResult = await runTurn("Continuing where we left off. Please review the conversation and continue with the task.", session, agentConfig);
+                // Save messages for future resume
+                saveSessionMessages(phrenCtx.phrenPath, sessionId, session.messages);
+                result = {
+                    finalText: turnResult.text,
+                    turns: turnResult.turns,
+                    toolCalls: turnResult.toolCalls,
+                    totalCost: agentConfig.costTracker?.formatCost(),
+                    messages: session.messages,
+                };
+            }
+            else {
+                process.stderr.write("No previous session to resume.\n");
+                result = await runAgent(args.task, agentConfig);
+            }
+        }
+        else {
+            result = await runAgent(args.task, agentConfig);
+        }
+        if (args.verbose) {
+            const costStr = result.totalCost ? `, ${result.totalCost}` : "";
+            process.stderr.write(`\nDone: ${result.turns} turns, ${result.toolCalls} tool calls${costStr}\n`);
+        }
+        // End session with summary + memory intelligence
+        if (phrenCtx && sessionId) {
+            const summary = result.finalText.slice(0, 500);
+            endSession(phrenCtx, sessionId, summary);
+            // Save messages for resume
+            saveSessionMessages(phrenCtx.phrenPath, sessionId, result.messages);
+            // Evolve project context via lightweight LLM reflection
+            try {
+                await evolveProjectContext(phrenCtx, provider, result.messages);
+            }
+            catch { /* best effort */ }
+        }
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        if (phrenCtx && sessionId) {
+            endSession(phrenCtx, sessionId, `Error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        mcpCleanup?.();
+        process.exit(1);
+    }
+    mcpCleanup?.();
+}
+// When run directly (phren-agent binary), parse from process.argv
+const isDirectRun = process.argv[1]?.endsWith("/agent/index.js") ||
+    process.argv[1]?.endsWith("/agent/index.ts");
+if (isDirectRun) {
+    runAgentCli(process.argv.slice(2));
+}

package/dist/mcp-client.js

@@ -0,0 +1,168 @@
+/**
+ * MCP client — connects to MCP servers, discovers tools, wraps them as AgentTools.
+ * Uses stdio transport (spawns server as child process).
+ */
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as readline from "readline";
+/** Active MCP server connection. */
+class McpConnection {
+    proc;
+    nextId = 1;
+    pending = new Map();
+    rl;
+    name;
+    constructor(name, config) {
+        this.name = name;
+        const env = { ...process.env, ...config.env };
+        this.proc = spawn(config.command, config.args ?? [], {
+            stdio: ["pipe", "pipe", "pipe"],
+            env,
+        });
+        this.rl = readline.createInterface({ input: this.proc.stdout });
+        this.rl.on("line", (line) => {
+            try {
+                const msg = JSON.parse(line);
+                if (msg.id !== undefined && this.pending.has(msg.id)) {
+                    const { resolve, reject } = this.pending.get(msg.id);
+                    this.pending.delete(msg.id);
+                    if (msg.error)
+                        reject(new Error(`MCP error: ${msg.error.message}`));
+                    else
+                        resolve(msg.result);
+                }
+            }
+            catch { /* ignore non-JSON lines */ }
+        });
+        this.proc.on("error", (err) => {
+            for (const { reject } of this.pending.values())
+                reject(err);
+            this.pending.clear();
+        });
+    }
+    send(method, params) {
+        return new Promise((resolve, reject) => {
+            const id = this.nextId++;
+            const msg = { jsonrpc: "2.0", id, method, params };
+            this.pending.set(id, { resolve, reject });
+            this.proc.stdin.write(JSON.stringify(msg) + "\n");
+            // Timeout after 30s
+            setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`MCP call ${method} timed out (30s)`));
+                }
+            }, 30_000);
+        });
+    }
+    async initialize() {
+        await this.send("initialize", {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "phren-agent", version: "0.0.1" },
+        });
+        // Send initialized notification (no id)
+        this.proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
+    }
+    async listTools() {
+        const result = await this.send("tools/list");
+        return result?.tools ?? [];
+    }
+    async callTool(name, args) {
+        return await this.send("tools/call", { name, arguments: args });
+    }
+    close() {
+        try {
+            this.proc.stdin.end();
+        }
+        catch { /* ignore */ }
+        try {
+            this.proc.kill();
+        }
+        catch { /* ignore */ }
+        this.rl.close();
+        for (const { reject } of this.pending.values())
+            reject(new Error("Connection closed"));
+        this.pending.clear();
+    }
+}
+/** Wrap an MCP tool as an AgentTool. */
+function wrapMcpTool(conn, def) {
+    return {
+        name: `mcp_${conn.name}_${def.name}`,
+        description: `[${conn.name}] ${def.description ?? def.name}`,
+        input_schema: def.inputSchema ?? { type: "object", properties: {} },
+        async execute(input) {
+            try {
+                const result = await conn.callTool(def.name, input);
+                const text = result.content
+                    ?.map((c) => c.text ?? JSON.stringify(c))
+                    .join("\n") ?? "OK";
+                return { output: text };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { output: `MCP error: ${msg}`, is_error: true };
+            }
+        },
+    };
+}
+/** Connect to MCP servers and return their tools as AgentTools. */
+export async function connectMcpServers(servers, verbose = false) {
+    const connections = [];
+    const tools = [];
+    for (const [name, config] of Object.entries(servers)) {
+        try {
+            if (verbose)
+                process.stderr.write(`Connecting to MCP server: ${name}...\n`);
+            const conn = new McpConnection(name, config);
+            await conn.initialize();
+            const mcpTools = await conn.listTools();
+            for (const def of mcpTools) {
+                tools.push(wrapMcpTool(conn, def));
+            }
+            connections.push(conn);
+            if (verbose)
+                process.stderr.write(`  ${name}: ${mcpTools.length} tools\n`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`Failed to connect to MCP server "${name}": ${msg}\n`);
+        }
+    }
+    return {
+        tools,
+        cleanup: () => { for (const conn of connections)
+            conn.close(); },
+    };
+}
+/** Load MCP server config from a JSON file (same format as Claude Code's mcpServers). */
+export function loadMcpConfig(configPath) {
+    if (!fs.existsSync(configPath))
+        return {};
+    try {
+        const raw = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        // Support both { mcpServers: {...} } and direct { serverName: {...} } formats
+        const servers = raw.mcpServers ?? raw;
+        const result = {};
+        for (const [name, entry] of Object.entries(servers)) {
+            const e = entry;
+            if (e.command && typeof e.command === "string") {
+                result[name] = {
+                    command: e.command,
+                    args: Array.isArray(e.args) ? e.args : undefined,
+                    env: typeof e.env === "object" && e.env !== null ? e.env : undefined,
+                };
+            }
+        }
+        return result;
+    }
+    catch {
+        return {};
+    }
+}
+/** Parse --mcp "command args..." into an McpConfigEntry. */
+export function parseMcpInline(spec) {
+    const parts = spec.split(/\s+/);
+    return { command: parts[0], args: parts.slice(1) };
+}

package/dist/memory/anti-patterns.js

@@ -0,0 +1,69 @@
+import { addFinding } from "@phren/cli/core/finding";
+export class AntiPatternTracker {
+    attempts = [];
+    /** Record a tool execution result. */
+    recordAttempt(name, input, succeeded, output) {
+        this.attempts.push({
+            name,
+            input: JSON.stringify(input).slice(0, 300),
+            succeeded,
+            output: output.slice(0, 300),
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Extract anti-patterns: find cases where a tool failed then later
+     * succeeded with different input (same tool name).
+     */
+    extractAntiPatterns() {
+        const patterns = [];
+        const seen = new Set();
+        for (let i = 0; i < this.attempts.length; i++) {
+            const fail = this.attempts[i];
+            if (fail.succeeded)
+                continue;
+            // Look for a later success with same tool name
+            for (let j = i + 1; j < this.attempts.length; j++) {
+                const success = this.attempts[j];
+                if (success.name !== fail.name || !success.succeeded)
+                    continue;
+                if (success.input === fail.input)
+                    continue; // Same input, not an anti-pattern
+                const key = `${fail.name}:${fail.input}`;
+                if (seen.has(key))
+                    break;
+                seen.add(key);
+                patterns.push({
+                    tool: fail.name,
+                    failedInput: fail.input,
+                    failedOutput: fail.output,
+                    succeededInput: success.input,
+                });
+                break;
+            }
+        }
+        return patterns;
+    }
+    /**
+     * Save top 3 anti-patterns as findings at session end.
+     */
+    async flushAntiPatterns(ctx) {
+        if (!ctx.project)
+            return 0;
+        const patterns = this.extractAntiPatterns().slice(0, 3);
+        if (patterns.length === 0)
+            return 0;
+        let saved = 0;
+        try {
+            for (const p of patterns) {
+                const finding = `[anti-pattern] ${p.tool}: failed with ${p.failedInput.slice(0, 100)} (${p.failedOutput.slice(0, 80)}), succeeded with ${p.succeededInput.slice(0, 100)}`;
+                await addFinding(ctx.phrenPath, ctx.project, finding);
+                saved++;
+            }
+        }
+        catch {
+            // best effort
+        }
+        return saved;
+    }
+}

package/dist/memory/auto-capture.js

@@ -0,0 +1,72 @@
+/**
+ * Auto-capture: extract findings from error tool results.
+ * Runs after each turn on error results only.
+ */
+import * as crypto from "crypto";
+import { addFinding } from "@phren/cli/core/finding";
+const SESSION_CAP = 10;
+const COOLDOWN_MS = 30_000;
+/** Patterns that indicate capturable knowledge in error output. */
+const CAPTURE_PATTERNS = [
+    { pattern: /ENOENT.*no such file/i, label: "missing-file" },
+    { pattern: /EACCES|permission denied/i, label: "permission-error" },
+    { pattern: /Cannot find module/i, label: "missing-module" },
+    { pattern: /ERR_MODULE_NOT_FOUND/i, label: "missing-module" },
+    { pattern: /ECONNREFUSED|ETIMEDOUT/i, label: "connection-error" },
+    { pattern: /port\s+\d+\s+(already|in use)/i, label: "port-conflict" },
+    { pattern: /deprecated/i, label: "deprecation" },
+    { pattern: /version\s+mismatch|incompatible/i, label: "version-mismatch" },
+    { pattern: /out of memory|heap|OOM/i, label: "memory-issue" },
+    { pattern: /syntax\s*error/i, label: "syntax-error" },
+    { pattern: /type\s*error.*is not a function/i, label: "type-error" },
+    { pattern: /config(uration)?\s+(not found|missing|invalid)/i, label: "config-issue" },
+    { pattern: /https?:\/\/\S+:\d+/i, label: "service-endpoint" },
+    { pattern: /env\s+var(iable)?.*not set|missing.*env/i, label: "env-var" },
+];
+export function createCaptureState() {
+    return { captured: 0, hashes: new Set(), lastCaptureTime: 0 };
+}
+function hashText(text) {
+    return crypto.createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+/**
+ * Analyze error output and auto-capture relevant findings.
+ * Returns the number of findings captured this call.
+ */
+export async function analyzeAndCapture(ctx, errorOutput, state) {
+    if (!ctx.project)
+        return 0;
+    if (state.captured >= SESSION_CAP)
+        return 0;
+    const now = Date.now();
+    if (now - state.lastCaptureTime < COOLDOWN_MS)
+        return 0;
+    let captured = 0;
+    for (const { pattern, label } of CAPTURE_PATTERNS) {
+        if (state.captured + captured >= SESSION_CAP)
+            break;
+        const match = errorOutput.match(pattern);
+        if (!match)
+            continue;
+        // Build a concise finding from the matched line
+        const lines = errorOutput.split("\n");
+        const matchedLine = lines.find((l) => pattern.test(l))?.trim() ?? match[0];
+        const finding = `[auto-capture:${label}] ${matchedLine.slice(0, 200)}`;
+        const hash = hashText(finding);
+        if (state.hashes.has(hash))
+            continue;
+        try {
+            await addFinding(ctx.phrenPath, ctx.project, finding);
+            state.hashes.add(hash);
+            captured++;
+        }
+        catch {
+            // best effort
+        }
+    }
+    if (captured > 0) {
+        state.captured += captured;
+        state.lastCaptureTime = now;
+    }
+    return captured;
+}

package/dist/memory/context-flush.js

@@ -0,0 +1,24 @@
+import { estimateTokens, estimateMessageTokens } from "../context/token-counter.js";
+export function createFlushConfig(contextLimit) {
+    return { contextLimit, triggered: false };
+}
+const FLUSH_PROMPT = "Before continuing, briefly summarize the key decisions, patterns, and discoveries from this conversation so far. " +
+    "Focus on non-obvious findings that would be valuable to remember in future sessions. " +
+    "Be concise — 3-5 bullet points maximum.";
+/**
+ * Check if a context flush should be injected.
+ * Returns the flush message to inject, or null if not needed.
+ * Only triggers once per session.
+ */
+export function checkFlushNeeded(systemPrompt, messages, config) {
+    if (config.triggered)
+        return null;
+    const systemTokens = estimateTokens(systemPrompt);
+    const msgTokens = estimateMessageTokens(messages);
+    const usage = (systemTokens + msgTokens) / config.contextLimit;
+    if (usage >= 0.75) {
+        config.triggered = true;
+        return FLUSH_PROMPT;
+    }
+    return null;
+}