@phren/agent 0.0.1

package/dist/providers/openai-compat.js

@@ -0,0 +1,163 @@
+/** Convert Anthropic tool defs to OpenAI function format. */
+export function toOpenAiTools(tools) {
+    return tools.map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.input_schema },
+    }));
+}
+/** Convert Anthropic messages to OpenAI messages. */
+export function toOpenAiMessages(system, messages) {
+    const out = [{ role: "system", content: system }];
+    for (const msg of messages) {
+        if (msg.role === "assistant") {
+            if (typeof msg.content === "string") {
+                out.push({ role: "assistant", content: msg.content });
+            }
+            else {
+                const textParts = msg.content.filter((b) => b.type === "text").map((b) => b.type === "text" ? b.text : "");
+                const toolCalls = msg.content.filter((b) => b.type === "tool_use").map((b) => {
+                    if (b.type !== "tool_use")
+                        throw new Error("unreachable");
+                    return { id: b.id, type: "function", function: { name: b.name, arguments: JSON.stringify(b.input) } };
+                });
+                const entry = { role: "assistant" };
+                if (textParts.length > 0)
+                    entry.content = textParts.join("\n");
+                if (toolCalls.length > 0)
+                    entry.tool_calls = toolCalls;
+                out.push(entry);
+            }
+        }
+        else if (msg.role === "user") {
+            if (typeof msg.content === "string") {
+                out.push({ role: "user", content: msg.content });
+            }
+            else {
+                for (const block of msg.content) {
+                    if (block.type === "tool_result") {
+                        out.push({ role: "tool", tool_call_id: block.tool_use_id, content: block.content });
+                    }
+                    else if (block.type === "text") {
+                        out.push({ role: "user", content: block.text });
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}
+/** Parse OpenAI response into Anthropic content blocks. */
+export function parseOpenAiResponse(data) {
+    const choice = data.choices?.[0] ?? {};
+    const message = choice.message;
+    const content = [];
+    if (message?.content && typeof message.content === "string") {
+        content.push({ type: "text", text: message.content });
+    }
+    const toolCalls = message?.tool_calls;
+    if (toolCalls) {
+        for (const tc of toolCalls) {
+            const fn = tc.function;
+            content.push({
+                type: "tool_use",
+                id: tc.id,
+                name: fn.name,
+                input: JSON.parse(fn.arguments),
+            });
+        }
+    }
+    const finishReason = choice.finish_reason;
+    const stop_reason = finishReason === "tool_calls" ? "tool_use"
+        : finishReason === "length" ? "max_tokens"
+            : "end_turn";
+    const usage = data.usage;
+    return {
+        content,
+        stop_reason,
+        usage: usage ? { input_tokens: usage.prompt_tokens ?? 0, output_tokens: usage.completion_tokens ?? 0 } : undefined,
+    };
+}
+/** Parse OpenAI-compatible SSE stream into StreamDelta events. */
+export async function* parseOpenAiStream(res) {
+    if (!res.body)
+        throw new Error("Provider returned empty response body");
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    // Track active tool calls by index
+    const activeTools = new Map(); // index -> tool_call id
+    let stopReason = "end_turn";
+    let usage;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        const lines = buf.split("\n");
+        buf = lines.pop();
+        for (const line of lines) {
+            if (!line.startsWith("data: "))
+                continue;
+            const raw = line.slice(6).trim();
+            if (raw === "[DONE]") {
+                // Close out any active tool calls before signaling done
+                for (const [, toolId] of activeTools) {
+                    yield { type: "tool_use_end", id: toolId };
+                }
+                activeTools.clear();
+                yield { type: "done", stop_reason: stopReason, usage };
+                return;
+            }
+            let chunk;
+            try {
+                chunk = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            // Usage from final chunk (OpenAI includes it when stream_options.include_usage is set)
+            const u = chunk.usage;
+            if (u) {
+                usage = { input_tokens: u.prompt_tokens ?? 0, output_tokens: u.completion_tokens ?? 0 };
+            }
+            const choice = chunk.choices?.[0];
+            if (!choice)
+                continue;
+            const finishReason = choice.finish_reason;
+            if (finishReason === "tool_calls")
+                stopReason = "tool_use";
+            else if (finishReason === "length")
+                stopReason = "max_tokens";
+            const delta = choice.delta;
+            if (!delta)
+                continue;
+            // Text content
+            if (delta.content && typeof delta.content === "string") {
+                yield { type: "text_delta", text: delta.content };
+            }
+            // Tool calls
+            const toolCalls = delta.tool_calls;
+            if (toolCalls) {
+                for (const tc of toolCalls) {
+                    const idx = tc.index;
+                    const fn = tc.function;
+                    // New tool call starts when id is present
+                    if (tc.id && typeof tc.id === "string") {
+                        activeTools.set(idx, tc.id);
+                        yield { type: "tool_use_start", id: tc.id, name: fn?.name ?? "" };
+                    }
+                    // Argument deltas
+                    if (fn?.arguments && typeof fn.arguments === "string") {
+                        const toolId = activeTools.get(idx) ?? String(idx);
+                        yield { type: "tool_use_delta", id: toolId, json: fn.arguments };
+                    }
+                }
+            }
+        }
+    }
+    // Emit tool_use_end for all active tools, then done
+    for (const [, toolId] of activeTools) {
+        yield { type: "tool_use_end", id: toolId };
+    }
+    yield { type: "done", stop_reason: stopReason, usage };
+}

package/dist/providers/openrouter.js

@@ -0,0 +1,116 @@
+import { toOpenAiTools, toOpenAiMessages, parseOpenAiResponse, parseOpenAiStream } from "./openai-compat.js";
+export class OpenRouterProvider {
+    name = "openrouter";
+    contextWindow = 200_000;
+    apiKey;
+    model;
+    baseUrl;
+    constructor(apiKey, model, baseUrl) {
+        this.apiKey = apiKey;
+        this.model = model ?? "anthropic/claude-sonnet-4-20250514";
+        this.baseUrl = baseUrl ?? "https://openrouter.ai/api/v1";
+    }
+    async chat(system, messages, tools) {
+        const body = {
+            model: this.model,
+            messages: toOpenAiMessages(system, messages),
+            max_tokens: 8192,
+        };
+        if (tools.length > 0)
+            body.tools = toOpenAiTools(tools);
+        const res = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+                "HTTP-Referer": "https://github.com/alaarab/phren",
+                "X-Title": "phren-agent",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`OpenRouter API error ${res.status}: ${text}`);
+        }
+        return parseOpenAiResponse(await res.json());
+    }
+    async *chatStream(system, messages, tools) {
+        const body = {
+            model: this.model,
+            messages: toOpenAiMessages(system, messages),
+            max_tokens: 8192,
+            stream: true,
+            stream_options: { include_usage: true },
+        };
+        if (tools.length > 0)
+            body.tools = toOpenAiTools(tools);
+        const res = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+                "HTTP-Referer": "https://github.com/alaarab/phren",
+                "X-Title": "phren-agent",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`OpenRouter API error ${res.status}: ${text}`);
+        }
+        yield* parseOpenAiStream(res);
+    }
+}
+/** OpenAI-native provider (same protocol, different base URL). */
+export class OpenAiProvider {
+    name = "openai";
+    contextWindow = 128_000;
+    apiKey;
+    model;
+    baseUrl;
+    constructor(apiKey, model, baseUrl) {
+        this.apiKey = apiKey;
+        this.model = model ?? "gpt-4o";
+        this.baseUrl = baseUrl ?? "https://api.openai.com/v1";
+    }
+    async chat(system, messages, tools) {
+        const body = {
+            model: this.model,
+            messages: toOpenAiMessages(system, messages),
+            max_tokens: 8192,
+        };
+        if (tools.length > 0)
+            body.tools = toOpenAiTools(tools);
+        const res = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.apiKey}` },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`OpenAI API error ${res.status}: ${text}`);
+        }
+        return parseOpenAiResponse(await res.json());
+    }
+    async *chatStream(system, messages, tools) {
+        const body = {
+            model: this.model,
+            messages: toOpenAiMessages(system, messages),
+            max_tokens: 8192,
+            stream: true,
+            stream_options: { include_usage: true },
+        };
+        if (tools.length > 0)
+            body.tools = toOpenAiTools(tools);
+        const res = await fetch(`${this.baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.apiKey}` },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`OpenAI API error ${res.status}: ${text}`);
+        }
+        yield* parseOpenAiStream(res);
+    }
+}

package/dist/providers/resolve.js

@@ -0,0 +1,39 @@
+import { OpenRouterProvider, OpenAiProvider } from "./openrouter.js";
+import { AnthropicProvider } from "./anthropic.js";
+import { OllamaProvider } from "./ollama.js";
+import { CodexProvider } from "./codex.js";
+import { hasCodexToken } from "./codex-auth.js";
+export function resolveProvider(overrideProvider, overrideModel) {
+    const explicit = overrideProvider ?? process.env.PHREN_AGENT_PROVIDER;
+    if (explicit === "openrouter" || (!explicit && process.env.OPENROUTER_API_KEY)) {
+        const key = process.env.OPENROUTER_API_KEY;
+        if (!key)
+            throw new Error("OPENROUTER_API_KEY is required for OpenRouter provider.");
+        return new OpenRouterProvider(key, overrideModel);
+    }
+    if (explicit === "anthropic" || (!explicit && process.env.ANTHROPIC_API_KEY)) {
+        const key = process.env.ANTHROPIC_API_KEY;
+        if (!key)
+            throw new Error("ANTHROPIC_API_KEY is required for Anthropic provider.");
+        return new AnthropicProvider(key, overrideModel);
+    }
+    if (explicit === "openai" || (!explicit && process.env.OPENAI_API_KEY)) {
+        const key = process.env.OPENAI_API_KEY;
+        if (!key)
+            throw new Error("OPENAI_API_KEY is required for OpenAI provider.");
+        return new OpenAiProvider(key, overrideModel);
+    }
+    // Codex: uses your ChatGPT subscription directly — no API key, no middleman
+    if (explicit === "codex" || (!explicit && hasCodexToken())) {
+        return new CodexProvider(overrideModel);
+    }
+    if (explicit === "ollama" || (!explicit && process.env.PHREN_OLLAMA_URL && process.env.PHREN_OLLAMA_URL !== "off")) {
+        return new OllamaProvider(overrideModel, process.env.PHREN_OLLAMA_URL);
+    }
+    // Last resort: try Ollama at default URL
+    if (!explicit) {
+        return new OllamaProvider(overrideModel);
+    }
+    throw new Error(`Unknown provider "${explicit}". Supported: openrouter, anthropic, openai, codex, ollama.\n` +
+        "Set one of: OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, or run 'phren-agent auth login' for Codex.");
+}

package/dist/providers/retry.js

@@ -0,0 +1,55 @@
+const DEFAULT_CONFIG = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 60_000,
+    retryableStatuses: new Set([429, 500, 502, 503, 529]),
+};
+const RETRYABLE_NETWORK_CODES = new Set(["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "EPIPE"]);
+/** Extract HTTP status from error message like "API error 429: ..." */
+function extractStatus(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    const match = msg.match(/\berror\s+(\d{3})\b/i);
+    return match ? parseInt(match[1], 10) : null;
+}
+/** Check if the error is a retryable network error by code or message. */
+function isNetworkError(error) {
+    if (error instanceof Error && "code" in error) {
+        const code = error.code;
+        if (code && RETRYABLE_NETWORK_CODES.has(code))
+            return true;
+    }
+    const msg = error instanceof Error ? error.message : String(error);
+    return RETRYABLE_NETWORK_CODES.has(msg) || Array.from(RETRYABLE_NETWORK_CODES).some((c) => msg.includes(c));
+}
+/** Extract Retry-After hint from error message. */
+function extractRetryAfter(error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    const match = msg.match(/retry[- ]?after[:\s]+(\d+)/i);
+    return match ? parseInt(match[1], 10) * 1000 : null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Wrap an async function with exponential backoff retry. */
+export async function withRetry(fn, config, verbose) {
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const status = extractStatus(error);
+            const isRetryable = (status !== null && cfg.retryableStatuses.has(status)) || isNetworkError(error);
+            if (!isRetryable || attempt >= cfg.maxRetries) {
+                throw error;
+            }
+            const retryAfterMs = extractRetryAfter(error);
+            const backoff = Math.min(cfg.baseDelayMs * Math.pow(2, attempt) + Math.random() * 1000, cfg.maxDelayMs);
+            const delayMs = retryAfterMs ?? backoff;
+            if (verbose) {
+                process.stderr.write(`Retry ${attempt + 1}/${cfg.maxRetries} after ${Math.round(delayMs)}ms (status ${status})\n`);
+            }
+            await sleep(delayMs);
+        }
+    }
+}

package/dist/providers/types.js

@@ -0,0 +1,2 @@
+/** LLM provider types — Anthropic content-block format internally. */
+export {};

package/dist/repl.js

@@ -0,0 +1,180 @@
+/** Interactive REPL for the phren agent with steering/queue input modes. */
+import * as readline from "node:readline/promises";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { createSession, runTurn } from "./agent-loop.js";
+import { handleCommand } from "./commands.js";
+const HISTORY_DIR = path.join(os.homedir(), ".phren-agent");
+const HISTORY_FILE = path.join(HISTORY_DIR, "repl-history.txt");
+const SETTINGS_FILE = path.join(HISTORY_DIR, "settings.json");
+const MAX_HISTORY = 500;
+const CYAN = "\x1b[36m";
+const RED = "\x1b[31m";
+const DIM = "\x1b[2m";
+const YELLOW = "\x1b[33m";
+const RESET = "\x1b[0m";
+function loadHistory() {
+    try {
+        const data = fs.readFileSync(HISTORY_FILE, "utf-8");
+        return data.split("\n").filter(Boolean).slice(-MAX_HISTORY);
+    }
+    catch {
+        return [];
+    }
+}
+function saveHistory(lines) {
+    try {
+        fs.mkdirSync(HISTORY_DIR, { recursive: true });
+        fs.writeFileSync(HISTORY_FILE, lines.slice(-MAX_HISTORY).join("\n") + "\n");
+    }
+    catch { /* ignore */ }
+}
+function loadInputMode() {
+    try {
+        const data = JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf-8"));
+        if (data.inputMode === "queue")
+            return "queue";
+    }
+    catch { /* ignore */ }
+    return "steering";
+}
+function saveInputMode(mode) {
+    try {
+        fs.mkdirSync(HISTORY_DIR, { recursive: true });
+        let data = {};
+        try {
+            data = JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf-8"));
+        }
+        catch { /* fresh */ }
+        data.inputMode = mode;
+        fs.writeFileSync(SETTINGS_FILE, JSON.stringify(data, null, 2) + "\n");
+    }
+    catch { /* ignore */ }
+}
+function savePermissionMode(mode) {
+    try {
+        fs.mkdirSync(HISTORY_DIR, { recursive: true });
+        let data = {};
+        try {
+            data = JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf-8"));
+        }
+        catch { /* fresh */ }
+        data.permissionMode = mode;
+        fs.writeFileSync(SETTINGS_FILE, JSON.stringify(data, null, 2) + "\n");
+    }
+    catch { /* ignore */ }
+}
+export async function startRepl(config) {
+    const contextLimit = config.provider.contextWindow ?? 200_000;
+    const session = createSession(contextLimit);
+    const history = loadHistory();
+    let inputMode = loadInputMode();
+    // Queued/steering input buffer — collects input typed while agent is running
+    let pendingInput = null;
+    let agentRunning = false;
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+        prompt: `${CYAN}phren>${RESET} `,
+        terminal: process.stdin.isTTY ?? false,
+        history,
+        historySize: MAX_HISTORY,
+    });
+    const modeLabel = inputMode === "steering" ? "steering" : "queue";
+    process.stderr.write(`${DIM}phren-agent interactive mode (${modeLabel}). Type /help for commands, Ctrl+D to exit.${RESET}\n`);
+    rl.prompt();
+    const allHistory = [...history];
+    for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            rl.prompt();
+            continue;
+        }
+        allHistory.push(trimmed);
+        // Handle slash commands
+        if (trimmed === "/mode") {
+            const newMode = inputMode === "steering" ? "queue" : "steering";
+            inputMode = newMode;
+            saveInputMode(newMode);
+            process.stderr.write(`${YELLOW}Input mode: ${newMode}${RESET}\n`);
+            rl.prompt();
+            continue;
+        }
+        if (trimmed.startsWith("/permissions")) {
+            const VALID_MODES = ["suggest", "auto-confirm", "full-auto"];
+            const arg = trimmed.split(/\s+/)[1];
+            if (!arg || !VALID_MODES.includes(arg)) {
+                const current = config.registry.permissionConfig.mode;
+                process.stderr.write(`${DIM}Permission mode: ${current}${RESET}\n`);
+                process.stderr.write(`${DIM}Usage: /permissions <suggest|auto-confirm|full-auto>${RESET}\n`);
+            }
+            else {
+                config.registry.setPermissions({ ...config.registry.permissionConfig, mode: arg });
+                savePermissionMode(arg);
+                process.stderr.write(`${YELLOW}Permission mode: ${arg}${RESET}\n`);
+            }
+            rl.prompt();
+            continue;
+        }
+        if (handleCommand(trimmed, { session, contextLimit, undoStack: [] })) {
+            rl.prompt();
+            continue;
+        }
+        // If agent is already running, buffer the input
+        if (agentRunning) {
+            pendingInput = trimmed;
+            if (inputMode === "steering") {
+                process.stderr.write(`${DIM}↳ steering: "${trimmed.slice(0, 60)}${trimmed.length > 60 ? "..." : ""}" will be injected${RESET}\n`);
+            }
+            else {
+                process.stderr.write(`${DIM}↳ queued: "${trimmed.slice(0, 60)}${trimmed.length > 60 ? "..." : ""}"${RESET}\n`);
+            }
+            continue;
+        }
+        agentRunning = true;
+        try {
+            await runTurn(trimmed, session, config);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`${RED}Error: ${msg}${RESET}\n`);
+        }
+        agentRunning = false;
+        // Process any input that came in while the agent was working
+        while (pendingInput !== null) {
+            const queued = pendingInput;
+            pendingInput = null;
+            allHistory.push(queued);
+            if (queued.startsWith("/")) {
+                if (queued === "/mode") {
+                    inputMode = inputMode === "steering" ? "queue" : "steering";
+                    saveInputMode(inputMode);
+                    process.stderr.write(`${YELLOW}Input mode: ${inputMode}${RESET}\n`);
+                }
+                else {
+                    handleCommand(queued, { session, contextLimit, undoStack: [] });
+                }
+                break;
+            }
+            agentRunning = true;
+            try {
+                if (inputMode === "steering") {
+                    // Steering: inject as a correction/redirect
+                    process.stderr.write(`${YELLOW}↳ steering with: ${queued.slice(0, 80)}${RESET}\n`);
+                }
+                await runTurn(queued, session, config);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`${RED}Error: ${msg}${RESET}\n`);
+            }
+            agentRunning = false;
+        }
+        rl.prompt();
+    }
+    // EOF (Ctrl+D) — clean exit
+    saveHistory(allHistory);
+    process.stderr.write(`\n${DIM}Session ended. ${session.turns} turns, ${session.toolCalls} tool calls.${RESET}\n`);
+    return session;
+}

package/dist/spinner.js

@@ -0,0 +1,46 @@
+/** TTY spinner + formatting helpers for the agent REPL. */
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const INTERVAL = 80;
+export function createSpinner() {
+    const isTTY = process.stderr.isTTY;
+    let timer = null;
+    let frame = 0;
+    let text = "";
+    function render() {
+        process.stderr.write(`\r\x1b[2K\x1b[90m${FRAMES[frame]} ${text}\x1b[0m`);
+        frame = (frame + 1) % FRAMES.length;
+    }
+    return {
+        start(t) {
+            if (!isTTY)
+                return;
+            text = t;
+            frame = 0;
+            if (timer)
+                clearInterval(timer);
+            render();
+            timer = setInterval(render, INTERVAL);
+        },
+        update(t) {
+            text = t;
+        },
+        stop() {
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+            if (isTTY)
+                process.stderr.write("\r\x1b[2K");
+        },
+    };
+}
+/** Format a turn header for REPL output. */
+export function formatTurnHeader(turn, toolCalls) {
+    return `\x1b[90m--- turn ${turn} (${toolCalls} tool call${toolCalls !== 1 ? "s" : ""}) ---\x1b[0m`;
+}
+/** Format a tool call for display: name + truncated input preview. */
+export function formatToolCall(name, input) {
+    const raw = JSON.stringify(input);
+    const preview = raw.length > 100 ? raw.slice(0, 100) + "..." : raw;
+    return `\x1b[2m  ${name}(${preview})\x1b[0m`;
+}

package/dist/system-prompt.js

@@ -0,0 +1,31 @@
+export function buildSystemPrompt(phrenContext, priorSummary) {
+    const parts = [
+        `You are phren-agent, a coding assistant with persistent memory powered by phren. You retain knowledge across sessions — past decisions, discovered patterns, and project context are all searchable. Use this memory to avoid repeating mistakes and to build on prior work.`,
+        "",
+        "## Workflow",
+        "1. **Orient** — Before starting, search phren for relevant findings (`phren_search`) and check active tasks (`phren_get_tasks`). Past sessions may have context that saves time.",
+        "2. **Read** — Read the relevant code before modifying it. Use `glob` to find files, `grep` to locate symbols, `read_file` to understand context.",
+        "3. **Change** — Make targeted edits. Use `edit_file` for surgical changes; reserve `write_file` for new files. Don't refactor code you weren't asked to touch.",
+        "4. **Verify** — Run tests and linters via `shell` after edits. Check `git_diff` to review your changes.",
+        "5. **Remember** — Save non-obvious discoveries with `phren_add_finding`: tricky bugs, architecture decisions, gotchas, workarounds. Skip obvious things — only save what would help a future session.",
+        "6. **Report** — Explain what you did concisely. Mention files changed and why.",
+        "",
+        "## Memory",
+        "- `phren_search` finds past findings, reference docs, and project context. Search before asking the user for context they may have already provided.",
+        "- `phren_add_finding` saves insights for future sessions. Good findings: non-obvious patterns, decisions with rationale, error resolutions, architecture constraints. Bad findings: narration of what you did, obvious facts, secrets.",
+        "- `phren_get_tasks` shows tracked work items. Complete tasks with `phren_complete_task` when done.",
+        "",
+        "## Rules",
+        "- Never write secrets, API keys, or PII to files or findings.",
+        "- Prefer `edit_file` over `write_file` for existing files.",
+        "- Keep shell commands safe. No `rm -rf`, no `sudo`, no destructive operations.",
+        "- If unsure, say so. Don't guess at behavior you can verify by reading code or running tests.",
+    ];
+    if (priorSummary) {
+        parts.push("", `## Last session\n${priorSummary}`);
+    }
+    if (phrenContext) {
+        parts.push("", phrenContext);
+    }
+    return parts.join("\n");
+}

package/dist/tools/edit-file.js

@@ -0,0 +1,31 @@
+import * as fs from "fs";
+import { encodeDiffPayload } from "../multi/diff-renderer.js";
+export const editFileTool = {
+    name: "edit_file",
+    description: "Edit a file by replacing an exact string match. Preferred over write_file for modifying existing files — only changes what's needed. The old_string must appear exactly once; include surrounding lines for uniqueness if needed.",
+    input_schema: {
+        type: "object",
+        properties: {
+            path: { type: "string", description: "File path to edit." },
+            old_string: { type: "string", description: "Exact string to find and replace." },
+            new_string: { type: "string", description: "Replacement string." },
+        },
+        required: ["path", "old_string", "new_string"],
+    },
+    async execute(input) {
+        const filePath = input.path;
+        const oldStr = input.old_string;
+        const newStr = input.new_string;
+        if (!fs.existsSync(filePath))
+            return { output: `File not found: ${filePath}`, is_error: true };
+        const oldContent = fs.readFileSync(filePath, "utf-8");
+        const count = oldContent.split(oldStr).length - 1;
+        if (count === 0)
+            return { output: "old_string not found in file.", is_error: true };
+        if (count > 1)
+            return { output: `old_string found ${count} times — must be unique. Provide more context.`, is_error: true };
+        const newContent = oldContent.replace(oldStr, newStr);
+        fs.writeFileSync(filePath, newContent);
+        return { output: `Edited ${filePath}${encodeDiffPayload(filePath, oldContent, newContent)}` };
+    },
+};