@phren/agent 0.0.1

package/dist/agent-loop.js

@@ -0,0 +1,328 @@
+import { createSpinner, formatTurnHeader, formatToolCall } from "./spinner.js";
+import { searchErrorRecovery } from "./memory/error-recovery.js";
+import { shouldPrune, pruneMessages } from "./context/pruner.js";
+import { withRetry } from "./providers/retry.js";
+import { createCaptureState, analyzeAndCapture } from "./memory/auto-capture.js";
+import { AntiPatternTracker } from "./memory/anti-patterns.js";
+import { createFlushConfig, checkFlushNeeded } from "./memory/context-flush.js";
+import { injectPlanPrompt, requestPlanApproval } from "./plan.js";
+import { detectLintCommand, detectTestCommand, runPostEditCheck } from "./tools/lint-test.js";
+import { createCheckpoint } from "./checkpoint.js";
+const MAX_TOOL_CONCURRENCY = 5;
+const MAX_LINT_TEST_RETRIES = 3;
+export function createSession(contextLimit) {
+    return {
+        messages: [],
+        turns: 0,
+        toolCalls: 0,
+        captureState: createCaptureState(),
+        antiPatterns: new AntiPatternTracker(),
+        flushConfig: createFlushConfig(contextLimit ?? 200_000),
+    };
+}
+/** Run tool blocks with concurrency limit. */
+async function runToolsConcurrently(blocks, registry) {
+    const results = [];
+    for (let i = 0; i < blocks.length; i += MAX_TOOL_CONCURRENCY) {
+        const batch = blocks.slice(i, i + MAX_TOOL_CONCURRENCY);
+        const batchResults = await Promise.all(batch.map(async (block) => {
+            const TOOL_TIMEOUT_MS = 120_000;
+            try {
+                const result = await Promise.race([
+                    registry.execute(block.name, block.input),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error(`Tool '${block.name}' timed out after ${TOOL_TIMEOUT_MS / 1000}s`)), TOOL_TIMEOUT_MS)),
+                ]);
+                return { block, output: result.output, is_error: !!result.is_error };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return { block, output: msg, is_error: true };
+            }
+        }));
+        results.push(...batchResults);
+    }
+    return results;
+}
+/** Consume a chatStream into ContentBlock[] + stop_reason, streaming text via callback. */
+async function consumeStream(stream, costTracker, onTextDelta) {
+    const content = [];
+    let stop_reason = "end_turn";
+    let currentText = "";
+    // Map block index -> tool state for Anthropic-style index-based IDs
+    const toolsByIndex = new Map();
+    for await (const delta of stream) {
+        if (delta.type === "text_delta") {
+            (onTextDelta ?? process.stdout.write.bind(process.stdout))(delta.text);
+            currentText += delta.text;
+        }
+        else if (delta.type === "tool_use_start") {
+            // Flush accumulated text
+            if (currentText) {
+                content.push({ type: "text", text: currentText });
+                currentText = "";
+            }
+            toolsByIndex.set(delta.id, { id: delta.id, name: delta.name, jsonParts: [] });
+        }
+        else if (delta.type === "tool_use_delta") {
+            const tool = toolsByIndex.get(delta.id);
+            if (tool)
+                tool.jsonParts.push(delta.json);
+        }
+        else if (delta.type === "tool_use_end") {
+            const tool = toolsByIndex.get(delta.id);
+            if (tool) {
+                const jsonStr = tool.jsonParts.join("");
+                let input = {};
+                try {
+                    input = JSON.parse(jsonStr);
+                }
+                catch (e) {
+                    process.stderr.write(`\x1b[33m[warning] Malformed tool_use JSON for ${tool.name} (${tool.id}), skipping block\x1b[0m\n`);
+                    continue;
+                }
+                content.push({ type: "tool_use", id: tool.id, name: tool.name, input });
+            }
+        }
+        else if (delta.type === "done") {
+            stop_reason = delta.stop_reason;
+            if (costTracker && delta.usage) {
+                costTracker.recordUsage(delta.usage.input_tokens, delta.usage.output_tokens);
+            }
+        }
+    }
+    // Flush remaining text
+    if (currentText) {
+        if (!currentText.endsWith("\n")) {
+            (onTextDelta ?? process.stdout.write.bind(process.stdout))("\n");
+        }
+        content.push({ type: "text", text: currentText });
+    }
+    return { content, stop_reason };
+}
+export async function runTurn(userInput, session, config, hooks) {
+    const { provider, registry, maxTurns, verbose, costTracker } = config;
+    let systemPrompt = config.systemPrompt;
+    const toolDefs = registry.getDefinitions();
+    const spinner = createSpinner();
+    const useStream = typeof provider.chatStream === "function";
+    const write = hooks?.onTextDelta ?? process.stdout.write.bind(process.stdout);
+    const status = hooks?.onStatus ?? ((msg) => process.stderr.write(msg));
+    // Plan mode: modify system prompt for first turn
+    let planPending = config.plan && session.turns === 0;
+    if (planPending) {
+        systemPrompt = injectPlanPrompt(systemPrompt);
+    }
+    // Append user message
+    session.messages.push({ role: "user", content: userInput });
+    let turnToolCalls = 0;
+    const turnStart = session.turns;
+    while (session.turns - turnStart < maxTurns) {
+        // Budget check
+        if (costTracker?.isOverBudget()) {
+            status(`\x1b[33m[budget exceeded: ${costTracker.formatCost()}]\x1b[0m\n`);
+            break;
+        }
+        if (verbose && session.turns > turnStart) {
+            status(`\n${formatTurnHeader(session.turns + 1, turnToolCalls)}\n`);
+        }
+        // Check if context flush is needed (one-time per session) — must run before pruning
+        const contextLimit = provider.contextWindow ?? 200_000;
+        const flushPrompt = checkFlushNeeded(systemPrompt, session.messages, session.flushConfig);
+        if (flushPrompt) {
+            session.messages.push({ role: "user", content: flushPrompt });
+            if (verbose)
+                status("[context flush injected]\n");
+        }
+        // Prune context if approaching limit
+        if (shouldPrune(systemPrompt, session.messages, { contextLimit })) {
+            session.messages = pruneMessages(session.messages, { contextLimit, keepRecentTurns: 6 });
+            if (verbose)
+                status("[context pruned]\n");
+        }
+        // For plan mode first turn, pass empty tools so LLM can't call any
+        const turnTools = planPending ? [] : toolDefs;
+        let assistantContent;
+        let stopReason;
+        if (useStream) {
+            // Streaming path — retry the initial connection (before consuming deltas)
+            const stream = await withRetry(async () => provider.chatStream(systemPrompt, session.messages, turnTools), undefined, verbose);
+            const result = await consumeStream(stream, costTracker, hooks?.onTextDelta);
+            assistantContent = result.content;
+            stopReason = result.stop_reason;
+        }
+        else {
+            // Batch path
+            spinner.start("Thinking...");
+            const response = await withRetry(() => provider.chat(systemPrompt, session.messages, turnTools), undefined, verbose);
+            spinner.stop();
+            assistantContent = response.content;
+            stopReason = response.stop_reason;
+            // Track cost from batch response
+            if (costTracker && response.usage) {
+                costTracker.recordUsage(response.usage.input_tokens, response.usage.output_tokens);
+            }
+            // Print text blocks (streaming already prints inline)
+            for (const block of assistantContent) {
+                if (block.type === "text" && block.text) {
+                    if (hooks?.onTextBlock) {
+                        hooks.onTextBlock(block.text);
+                    }
+                    else {
+                        process.stdout.write(block.text);
+                        if (!block.text.endsWith("\n"))
+                            process.stdout.write("\n");
+                    }
+                }
+            }
+        }
+        session.messages.push({ role: "assistant", content: assistantContent });
+        session.turns++;
+        // Show turn cost
+        if (verbose && costTracker) {
+            status(`\x1b[2m  cost: ${costTracker.formatCost()}\x1b[0m\n`);
+        }
+        // Plan mode gate: after first response, ask for approval
+        if (planPending) {
+            planPending = false;
+            const { approved, feedback } = await requestPlanApproval();
+            if (!approved) {
+                // Always restore original system prompt on rejection to prevent plan prompt leaking
+                systemPrompt = config.systemPrompt;
+                const msg = feedback
+                    ? `The user rejected the plan with feedback: ${feedback}\nPlease revise your plan.`
+                    : "The user rejected the plan. Task aborted.";
+                if (feedback) {
+                    // Let the LLM revise — add feedback as user message and continue
+                    session.messages.push({ role: "user", content: msg });
+                    continue;
+                }
+                break;
+            }
+            // Approved — restore original system prompt and continue with tools enabled
+            systemPrompt = config.systemPrompt;
+            session.messages.push({ role: "user", content: "Plan approved. Proceed with execution." });
+            continue;
+        }
+        // If max_tokens, warn user and inject continuation prompt
+        if (stopReason === "max_tokens") {
+            status("\x1b[33m[response truncated: max_tokens reached, requesting continuation]\x1b[0m\n");
+            session.messages.push({ role: "user", content: "Your response was truncated due to length. Please continue where you left off." });
+            continue;
+        }
+        // If no tool use, we're done
+        if (stopReason !== "tool_use")
+            break;
+        // Execute tool calls with concurrency
+        const toolUseBlocks = assistantContent.filter((b) => b.type === "tool_use");
+        // Log all tool calls upfront
+        if (hooks?.onToolStart) {
+            for (const block of toolUseBlocks)
+                hooks.onToolStart(block.name, block.input, toolUseBlocks.length);
+        }
+        else {
+            for (const block of toolUseBlocks)
+                status(formatToolCall(block.name, block.input) + "\n");
+        }
+        if (!hooks?.onToolStart)
+            spinner.start(`Running ${toolUseBlocks.length} tool${toolUseBlocks.length > 1 ? "s" : ""}...`);
+        const execResults = await runToolsConcurrently(toolUseBlocks, registry);
+        if (!hooks?.onToolStart)
+            spinner.stop();
+        const toolResults = [];
+        for (const { block, output, is_error } of execResults) {
+            session.toolCalls++;
+            turnToolCalls++;
+            let finalOutput = output;
+            // Record for anti-pattern tracking
+            session.antiPatterns.recordAttempt(block.name, block.input, !is_error, output);
+            // Append phren recovery context on tool errors
+            if (is_error && config.phrenCtx) {
+                try {
+                    const recovery = await searchErrorRecovery(config.phrenCtx, output);
+                    if (recovery)
+                        finalOutput += recovery;
+                }
+                catch { /* best effort */ }
+                // Auto-capture error patterns
+                try {
+                    await analyzeAndCapture(config.phrenCtx, output, session.captureState);
+                }
+                catch { /* best effort */ }
+            }
+            if (hooks?.onToolEnd) {
+                hooks.onToolEnd(block.name, block.input, finalOutput, is_error, 0);
+            }
+            else if (verbose) {
+                const preview = finalOutput.slice(0, 200);
+                status(`\x1b[2m  ← ${is_error ? "ERROR: " : ""}${preview}${finalOutput.length > 200 ? "..." : ""}\x1b[0m\n`);
+            }
+            toolResults.push({
+                type: "tool_result",
+                tool_use_id: block.id,
+                content: finalOutput,
+                is_error,
+            });
+        }
+        // Post-edit lint/test check
+        const mutatingTools = new Set(["edit_file", "write_file"]);
+        const hasMutation = toolUseBlocks.some(b => mutatingTools.has(b.name));
+        if (hasMutation && config.lintTestConfig) {
+            const cwd = process.cwd();
+            const lintCmd = config.lintTestConfig.lintCmd ?? detectLintCommand(cwd);
+            const testCmd = config.lintTestConfig.testCmd ?? detectTestCommand(cwd);
+            const lintFailures = [];
+            for (const cmd of [lintCmd, testCmd].filter(Boolean)) {
+                const check = runPostEditCheck(cmd, cwd);
+                if (!check.passed) {
+                    if (verbose)
+                        status(`\x1b[33m[post-edit check failed: ${cmd}]\x1b[0m\n`);
+                    lintFailures.push(`Post-edit check failed (${cmd}):\n${check.output.slice(0, 2000)}`);
+                }
+            }
+            if (lintFailures.length > 0) {
+                // Inject as plain text in the tool results user message (not as a fabricated tool_result)
+                toolResults.push({
+                    type: "text",
+                    text: lintFailures.join("\n\n"),
+                });
+            }
+        }
+        // Create checkpoint before mutating tool results are committed to conversation
+        if (hasMutation) {
+            createCheckpoint(process.cwd(), `turn-${session.turns}`);
+        }
+        // Add tool results as a user message
+        session.messages.push({ role: "user", content: toolResults });
+        // Steering input injection (TUI mid-turn input)
+        const steer = hooks?.getSteeringInput?.();
+        if (steer) {
+            session.messages.push({ role: "user", content: steer });
+        }
+    }
+    // Extract text from the last assistant message in this turn
+    const lastAssistant = [...session.messages].reverse().find((m) => m.role === "assistant");
+    let text = "";
+    if (lastAssistant && Array.isArray(lastAssistant.content)) {
+        text = lastAssistant.content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text)
+            .join("\n");
+    }
+    else if (lastAssistant && typeof lastAssistant.content === "string") {
+        text = lastAssistant.content;
+    }
+    return { text, turns: session.turns - turnStart, toolCalls: turnToolCalls };
+}
+/** One-shot agent run — thin wrapper around createSession + runTurn. */
+export async function runAgent(task, config) {
+    const contextLimit = config.provider.contextWindow ?? 200_000;
+    const session = createSession(contextLimit);
+    const result = await runTurn(task, session, config);
+    return {
+        finalText: result.text,
+        turns: result.turns,
+        toolCalls: result.toolCalls,
+        totalCost: config.costTracker?.formatCost(),
+        messages: session.messages,
+    };
+}

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runAgentCli } from "./index.js";
+runAgentCli(process.argv.slice(2));

package/dist/checkpoint.js

@@ -0,0 +1,103 @@
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+function isGitRepo(cwd) {
+    try {
+        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function storeFile(_cwd) {
+    const dir = path.join(os.homedir(), ".phren-agent");
+    fs.mkdirSync(dir, { recursive: true });
+    return path.join(dir, "checkpoints.json");
+}
+function loadStore(cwd) {
+    const file = storeFile(cwd);
+    if (fs.existsSync(file)) {
+        try {
+            return JSON.parse(fs.readFileSync(file, "utf-8"));
+        }
+        catch { /* ignore corrupt */ }
+    }
+    return { checkpoints: [] };
+}
+function saveStore(cwd, store) {
+    fs.writeFileSync(storeFile(cwd), JSON.stringify(store, null, 2) + "\n");
+}
+/**
+ * Create a checkpoint via `git stash create`. Returns the ref or null if
+ * the working tree is clean (stash create produces no output when clean).
+ */
+export function createCheckpoint(cwd, label) {
+    if (!isGitRepo(cwd))
+        return null;
+    try {
+        const ref = execFileSync("git", ["stash", "create"], {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        if (!ref)
+            return null; // clean working tree
+        // Store the ref so `git gc` won't collect it
+        execFileSync("git", ["stash", "store", "-m", label || "phren-checkpoint", ref], {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const store = loadStore(cwd);
+        store.checkpoints.push({
+            ref,
+            label: label || `checkpoint-${store.checkpoints.length + 1}`,
+            createdAt: new Date().toISOString(),
+        });
+        saveStore(cwd, store);
+        return ref;
+    }
+    catch {
+        return null;
+    }
+}
+/** Rollback to a checkpoint by discarding current changes and applying the stash. */
+export function rollbackToCheckpoint(cwd, ref) {
+    if (!isGitRepo(cwd))
+        return false;
+    try {
+        // Discard current working tree changes
+        execFileSync("git", ["checkout", "."], {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        // Apply the stash ref
+        execFileSync("git", ["stash", "apply", ref], {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** List stored checkpoints. */
+export function listCheckpoints(cwd) {
+    return loadStore(cwd).checkpoints;
+}
+/** Get the latest checkpoint ref. */
+export function getLatestCheckpoint(cwd) {
+    const store = loadStore(cwd);
+    return store.checkpoints.length > 0
+        ? store.checkpoints[store.checkpoints.length - 1].ref
+        : null;
+}