mono-pilot 0.2.9 → 0.2.12

package/dist/src/memory/session/transcript/entry.js

@@ -0,0 +1,28 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+function formatMessages(messages) {
+    return messages.map((message) => `${message.role}: ${message.text}`).join("\n");
+}
+export function buildSessionTranscriptEntry(input) {
+    const iso = input.timestamp.toISOString();
+    const [datePart, timePart] = iso.split("T");
+    const time = (timePart ?? "").split(".")[0] ?? "";
+    const lines = [
+        `# Session Transcript Delta: ${datePart ?? ""} ${time} UTC`,
+        "",
+        `- **Reason**: ${input.reason}`,
+        `- **Session ID**: ${input.sessionId ?? "unknown"}`,
+        `- **Session File**: ${input.sessionFile}`,
+        `- **Range**: lines ${input.fromLineExclusive + 1}-${input.toLineInclusive}`,
+        "",
+        "## Conversation Excerpt",
+        "",
+        formatMessages(input.messages),
+        "",
+    ];
+    return lines.join("\n");
+}
+export async function writeSessionTranscriptFile(filePath, content) {
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, "utf-8");
+}

package/dist/src/memory/session/transcript/flush.js

@@ -0,0 +1,56 @@
+import { join } from "node:path";
+import { buildTranscriptContentHashSlug } from "./content-hash.js";
+import { formatSessionTimestampParts } from "../paths.js";
+import { buildSessionTranscriptEntry, writeSessionTranscriptFile } from "./entry.js";
+import { readSessionTranscriptDelta } from "./reader.js";
+import { buildSessionTranscriptFilename, getSessionTranscriptDir, getSessionTranscriptStatePath, normalizeSessionId, } from "./paths.js";
+import { loadSessionTranscriptState, saveSessionTranscriptState } from "./state.js";
+function toIsoMinuteSlug(time) {
+    return time.replace(/:/g, "").slice(0, 4);
+}
+export async function flushSessionTranscript(params) {
+    const initialSessionId = normalizeSessionId(undefined, params.sessionFile);
+    const initialStatePath = getSessionTranscriptStatePath(params.agentId, initialSessionId);
+    const initialState = await loadSessionTranscriptState(initialStatePath);
+    const delta = await readSessionTranscriptDelta(params.sessionFile, initialState.lastLine);
+    const finalSessionId = normalizeSessionId(delta.sessionId, params.sessionFile);
+    const statePath = getSessionTranscriptStatePath(params.agentId, finalSessionId);
+    const state = finalSessionId === initialSessionId ? initialState : await loadSessionTranscriptState(statePath);
+    const finalDelta = finalSessionId === initialSessionId
+        ? delta
+        : await readSessionTranscriptDelta(params.sessionFile, state.lastLine);
+    if (finalDelta.messages.length === 0) {
+        await saveSessionTranscriptState(statePath, {
+            lastLine: finalDelta.lastLine,
+            updatedAt: new Date().toISOString(),
+        });
+        return { written: false, lastLine: finalDelta.lastLine };
+    }
+    const now = new Date();
+    const { date, time } = formatSessionTimestampParts(now);
+    const timeSlug = toIsoMinuteSlug(time);
+    const textForHash = finalDelta.messages.map((msg) => `${msg.role}:${msg.text}`).join("\n");
+    const hashSlug = buildTranscriptContentHashSlug(`${finalDelta.sessionId ?? finalSessionId}\n${textForHash}`);
+    const filename = buildSessionTranscriptFilename(date, timeSlug, hashSlug);
+    const transcriptDir = getSessionTranscriptDir(params.agentId, finalSessionId);
+    const transcriptPath = join(transcriptDir, filename);
+    const content = buildSessionTranscriptEntry({
+        timestamp: now,
+        reason: params.reason,
+        sessionId: finalDelta.sessionId,
+        sessionFile: params.sessionFile,
+        fromLineExclusive: state.lastLine,
+        toLineInclusive: finalDelta.lastLine,
+        messages: finalDelta.messages,
+    });
+    await writeSessionTranscriptFile(transcriptPath, content);
+    await saveSessionTranscriptState(statePath, {
+        lastLine: finalDelta.lastLine,
+        updatedAt: now.toISOString(),
+    });
+    return {
+        written: true,
+        filePath: transcriptPath,
+        lastLine: finalDelta.lastLine,
+    };
+}

package/dist/src/memory/session/transcript/paths.js

@@ -0,0 +1,28 @@
+import { basename, extname, join } from "node:path";
+import { getAgentDir } from "../../../agents-paths.js";
+const MAX_SESSION_SLUG_CHARS = 80;
+function sanitizeSessionId(raw) {
+    const normalized = raw
+        .trim()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return normalized.slice(0, MAX_SESSION_SLUG_CHARS);
+}
+export function normalizeSessionId(sessionId, sessionFile) {
+    const fallback = basename(sessionFile, extname(sessionFile));
+    const candidate = sessionId && sessionId.trim().length > 0 ? sessionId : fallback;
+    const sanitized = sanitizeSessionId(candidate);
+    return sanitized || "unknown-session";
+}
+export function getSessionTranscriptsRootDir(agentId) {
+    return join(getAgentDir(agentId), "session-transcripts");
+}
+export function getSessionTranscriptDir(agentId, sessionSlug) {
+    return join(getSessionTranscriptsRootDir(agentId), sessionSlug);
+}
+export function getSessionTranscriptStatePath(agentId, sessionSlug) {
+    return join(getSessionTranscriptsRootDir(agentId), ".state", `${sessionSlug}.json`);
+}
+export function buildSessionTranscriptFilename(datePart, timePart, hashSlug) {
+    return `${datePart}-${timePart}-${hashSlug}.md`;
+}

package/dist/src/memory/session/transcript/reader.js

@@ -0,0 +1,112 @@
+import { readFile } from "node:fs/promises";
+const USER_QUERY_OPEN = "<user_query>";
+const USER_QUERY_CLOSE = "</user_query>";
+function parseJsonLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractTextContent(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return undefined;
+    }
+    const texts = content
+        .map((item) => {
+        if (!item || typeof item !== "object")
+            return undefined;
+        const entry = item;
+        return entry.type === "text" && typeof entry.text === "string" ? entry.text : undefined;
+    })
+        .filter((text) => typeof text === "string" && text.trim().length > 0);
+    if (texts.length === 0)
+        return undefined;
+    return texts.join("\n");
+}
+function shouldSkipUserText(text) {
+    return text.trim().startsWith("/");
+}
+function extractUserQuery(text) {
+    const start = text.indexOf(USER_QUERY_OPEN);
+    const end = text.lastIndexOf(USER_QUERY_CLOSE);
+    if (start === -1 || end === -1 || end <= start)
+        return undefined;
+    const extracted = text.slice(start + USER_QUERY_OPEN.length, end).trim();
+    return extracted.length > 0 ? extracted : undefined;
+}
+export async function readSessionTranscriptDelta(sessionFile, fromLineExclusive) {
+    const result = {
+        messages: [],
+        lastLine: fromLineExclusive,
+        deltaBytes: 0,
+    };
+    let raw;
+    try {
+        raw = await readFile(sessionFile, "utf-8");
+    }
+    catch {
+        return result;
+    }
+    const lines = raw.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const lineNo = index + 1;
+        const line = lines[index] ?? "";
+        if (!line.trim())
+            continue;
+        if (lineNo <= fromLineExclusive) {
+            result.lastLine = lineNo;
+            continue;
+        }
+        result.deltaBytes += Buffer.byteLength(line, "utf-8") + 1;
+        const entry = parseJsonLine(line);
+        if (!entry) {
+            result.lastLine = lineNo;
+            continue;
+        }
+        if (entry.type === "session" && typeof entry.id === "string" && !result.sessionId) {
+            result.sessionId = entry.id;
+            result.lastLine = lineNo;
+            continue;
+        }
+        if (entry.type !== "message" || !entry.message) {
+            result.lastLine = lineNo;
+            continue;
+        }
+        const role = entry.message.role;
+        if (role !== "user" && role !== "assistant") {
+            result.lastLine = lineNo;
+            continue;
+        }
+        const text = extractTextContent(entry.message.content ?? "");
+        if (!text) {
+            result.lastLine = lineNo;
+            continue;
+        }
+        let normalized = text.trim();
+        if (!normalized) {
+            result.lastLine = lineNo;
+            continue;
+        }
+        if (role === "user") {
+            const extracted = extractUserQuery(normalized);
+            if (!extracted) {
+                result.lastLine = lineNo;
+                continue;
+            }
+            if (shouldSkipUserText(extracted)) {
+                result.lastLine = lineNo;
+                continue;
+            }
+            normalized = extracted;
+        }
+        result.messages.push({ role, text: normalized, line: lineNo });
+        result.lastLine = lineNo;
+    }
+    return result;
+}

package/dist/src/memory/session/transcript/state.js

@@ -0,0 +1,31 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+const INITIAL_STATE = {
+    lastLine: 0,
+    updatedAt: new Date(0).toISOString(),
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export async function loadSessionTranscriptState(statePath) {
+    try {
+        const raw = await readFile(statePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed))
+            return INITIAL_STATE;
+        const lastLineRaw = parsed.lastLine;
+        const updatedAtRaw = parsed.updatedAt;
+        const lastLine = typeof lastLineRaw === "number" && Number.isFinite(lastLineRaw) && lastLineRaw > 0
+            ? Math.trunc(lastLineRaw)
+            : 0;
+        const updatedAt = typeof updatedAtRaw === "string" && updatedAtRaw.trim() ? updatedAtRaw : INITIAL_STATE.updatedAt;
+        return { lastLine, updatedAt };
+    }
+    catch {
+        return INITIAL_STATE;
+    }
+}
+export async function saveSessionTranscriptState(statePath, state) {
+    await mkdir(dirname(statePath), { recursive: true });
+    await writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+}

package/dist/src/memory/store/schema.js

@@ -0,0 +1,89 @@
+export const FILES_TABLE = "files";
+export const CHUNKS_TABLE = "chunks";
+export const FTS_TABLE = "chunks_fts";
+export const EMBEDDING_CACHE_TABLE = "embedding_cache";
+export const VECTOR_TABLE = "chunks_vec";
+export function ensureMemoryIndexSchema(params) {
+    params.db.exec(`
+		CREATE TABLE IF NOT EXISTS meta (
+			key TEXT PRIMARY KEY,
+			value TEXT NOT NULL
+		);
+	`);
+    params.db.exec(`
+		CREATE TABLE IF NOT EXISTS ${FILES_TABLE} (
+			path TEXT NOT NULL,
+			agent_id TEXT NOT NULL,
+			source TEXT NOT NULL DEFAULT 'memory',
+			hash TEXT NOT NULL,
+			mtime INTEGER NOT NULL,
+			size INTEGER NOT NULL,
+			PRIMARY KEY (path, agent_id)
+		);
+	`);
+    params.db.exec(`
+		CREATE TABLE IF NOT EXISTS ${CHUNKS_TABLE} (
+			id TEXT PRIMARY KEY,
+			path TEXT NOT NULL,
+			agent_id TEXT NOT NULL,
+			source TEXT NOT NULL DEFAULT 'memory',
+			start_line INTEGER NOT NULL,
+			end_line INTEGER NOT NULL,
+			hash TEXT NOT NULL,
+			model TEXT NOT NULL,
+			text TEXT NOT NULL,
+			embedding TEXT NOT NULL,
+			updated_at INTEGER NOT NULL
+		);
+	`);
+    params.db.exec(`
+		CREATE TABLE IF NOT EXISTS ${EMBEDDING_CACHE_TABLE} (
+			provider TEXT NOT NULL,
+			model TEXT NOT NULL,
+			provider_key TEXT NOT NULL,
+			hash TEXT NOT NULL,
+			embedding TEXT NOT NULL,
+			dims INTEGER,
+			updated_at INTEGER NOT NULL,
+			PRIMARY KEY (provider, model, provider_key, hash)
+		);
+	`);
+    params.db.exec(`CREATE INDEX IF NOT EXISTS idx_embedding_cache_updated_at ON ${EMBEDDING_CACHE_TABLE}(updated_at);`);
+    let ftsAvailable = false;
+    let ftsError;
+    if (params.ftsEnabled) {
+        try {
+            params.db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS ${FTS_TABLE} USING fts5(
+					text,
+					id UNINDEXED,
+					path UNINDEXED,
+					source UNINDEXED,
+					model UNINDEXED,
+					start_line UNINDEXED,
+					end_line UNINDEXED
+				);`);
+            ftsAvailable = true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            ftsAvailable = false;
+            ftsError = message;
+        }
+    }
+    ensureColumn(params.db, FILES_TABLE, "source", "TEXT NOT NULL DEFAULT 'memory'");
+    ensureColumn(params.db, FILES_TABLE, "agent_id", "TEXT NOT NULL DEFAULT ''");
+    ensureColumn(params.db, CHUNKS_TABLE, "source", "TEXT NOT NULL DEFAULT 'memory'");
+    ensureColumn(params.db, CHUNKS_TABLE, "agent_id", "TEXT NOT NULL DEFAULT ''");
+    params.db.exec(`CREATE INDEX IF NOT EXISTS idx_chunks_path ON ${CHUNKS_TABLE}(path);`);
+    params.db.exec(`CREATE INDEX IF NOT EXISTS idx_chunks_source ON ${CHUNKS_TABLE}(source);`);
+    params.db.exec(`CREATE INDEX IF NOT EXISTS idx_chunks_agent_id ON ${CHUNKS_TABLE}(agent_id);`);
+    params.db.exec(`CREATE INDEX IF NOT EXISTS idx_files_agent_id ON ${FILES_TABLE}(agent_id);`);
+    return { ftsAvailable, ...(ftsError ? { ftsError } : {}) };
+}
+function ensureColumn(db, table, column, definition) {
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    if (rows.some((row) => row.name === column)) {
+        return;
+    }
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+}

package/dist/src/memory/store/sqlite.js

@@ -0,0 +1,89 @@
+import { mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+const require = createRequire(import.meta.url);
+let sqliteWarningPatched = false;
+export function requireNodeSqlite() {
+    try {
+        suppressSqliteExperimentalWarning();
+        return require("node:sqlite");
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`SQLite support is unavailable in this Node runtime (missing node:sqlite). ${message}`, { cause: err });
+    }
+}
+export function openSqliteDatabase(path, allowExtension = false) {
+    ensureDir(dirname(path));
+    const { DatabaseSync } = requireNodeSqlite();
+    const db = new DatabaseSync(path, { allowExtension });
+    configureSqliteConnection(db);
+    return db;
+}
+export async function loadSqliteVecExtension(params) {
+    try {
+        const sqliteVec = await import("sqlite-vec");
+        const resolvedPath = params.extensionPath?.trim() ? params.extensionPath.trim() : undefined;
+        const extensionPath = resolvedPath ?? sqliteVec.getLoadablePath();
+        params.db.enableLoadExtension(true);
+        if (resolvedPath) {
+            params.db.loadExtension(extensionPath);
+        }
+        else {
+            sqliteVec.load(params.db);
+        }
+        return { ok: true, extensionPath };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: message };
+    }
+}
+function ensureDir(path) {
+    try {
+        mkdirSync(path, { recursive: true });
+    }
+    catch {
+        // Ignore directory creation errors; caller handles downstream failures.
+    }
+}
+function configureSqliteConnection(db) {
+    try {
+        db.exec("PRAGMA journal_mode=WAL;");
+    }
+    catch { }
+    try {
+        db.exec("PRAGMA busy_timeout=5000;");
+    }
+    catch { }
+}
+function suppressSqliteExperimentalWarning() {
+    if (sqliteWarningPatched)
+        return;
+    sqliteWarningPatched = true;
+    const originalEmitWarning = process.emitWarning.bind(process);
+    process.emitWarning = ((warning, ...args) => {
+        if (isSqliteExperimentalWarning(warning, args))
+            return;
+        return originalEmitWarning(warning, ...args);
+    });
+}
+function isSqliteExperimentalWarning(warning, args) {
+    const message = typeof warning === "string"
+        ? warning
+        : warning instanceof Error
+            ? warning.message
+            : warning?.message;
+    const name = warning instanceof Error
+        ? warning.name
+        : warning?.name;
+    const type = typeof args[0] === "string"
+        ? args[0]
+        : args[0]?.type;
+    const warningType = name ?? type;
+    if (warningType !== "ExperimentalWarning")
+        return false;
+    if (!message)
+        return false;
+    return message.includes("SQLite is an experimental feature");
+}

package/dist/src/memory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/memory/warm.js

@@ -0,0 +1,25 @@
+import { loadResolvedMemorySearchConfig } from "./config/loader.js";
+import { getMemorySearchManager } from "./runtime/index.js";
+import { memoryLog } from "./log.js";
+export async function warmMemorySearch(params) {
+    try {
+        const settings = await loadResolvedMemorySearchConfig();
+        if (!settings.enabled || !settings.sync.onSessionStart) {
+            return { attempted: false, succeeded: true };
+        }
+        memoryLog.info("warm start", { agentId: params.agentId });
+        const manager = await getMemorySearchManager(params);
+        if (!manager?.sync) {
+            return { attempted: false, succeeded: true };
+        }
+        await manager.sync({ reason: "session-start", onWorkDetected: params.onWorkDetected });
+        memoryLog.info("warm complete", { agentId: params.agentId });
+        return { attempted: true, succeeded: true };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`[memory] warm failed: ${message}`);
+        memoryLog.error("warm failed", { agentId: params.agentId, error: message });
+        return { attempted: true, succeeded: false, error: message };
+    }
+}

package/dist/src/rules/discovery.js

@@ -0,0 +1,41 @@
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+export const RULES_RELATIVE_DIR = join(".pi", "rules");
+/** List *.rule.txt full paths from a directory, sorted. Returns empty array if directory is missing. */
+export async function listRuleFiles(dirPath) {
+    if (!existsSync(dirPath))
+        return [];
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true, encoding: "utf8" });
+        return entries
+            .filter((e) => e.isFile() && e.name.endsWith(".rule.txt"))
+            .map((e) => resolve(dirPath, e.name))
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Discover rule files from project (.pi/rules/) and user (~/.pi/rules/) directories.
+ * Project rules take priority: a user rule with the same basename is excluded.
+ */
+export async function discoverRules(cwd) {
+    const projectDir = resolve(cwd, RULES_RELATIVE_DIR);
+    const userDir = resolve(homedir(), RULES_RELATIVE_DIR);
+    const [projectFiles, userFiles] = await Promise.all([listRuleFiles(projectDir), listRuleFiles(userDir)]);
+    // Project rules are processed first so they claim seenNames → user duplicates are dropped
+    const seenNames = new Set();
+    const dedupeByName = (files) => files.filter((filePath) => {
+        const name = basename(filePath, ".rule.txt");
+        if (seenNames.has(name))
+            return false;
+        seenNames.add(name);
+        return true;
+    });
+    const projectRules = dedupeByName(projectFiles);
+    const userRules = dedupeByName(userFiles);
+    return { userRules, projectRules };
+}

package/dist/{tools → src/tools}/README.md

@@ -21,22 +21,35 @@ Tool descriptions are now loaded by the tool implementation and exposed via the
   - Find paths by glob pattern.
 - `rg.ts` (`rg`)
   - Search file content with ripgrep.
+- `ast-grep.ts` (`AstGrep`)
+  - Search code by AST structure using ast-grep (`run` and `scan`, read-only).
 - `read-file.ts` (`ReadFile`)
   - Read file content with truncation and pagination behavior.
 - `delete.ts` (`Delete`)
   - Delete files or directories.
 - `semantic-search.ts` / `semantic-search-description.md` (`SemanticSearch`)
   - Search code semantically by intent and meaning.
+- `memory-search.ts` (`memory_search`)
+  - Search indexed memory files for relevant snippets.
+- `memory-get.ts` (`memory_get`)
+  - Read a snippet from a memory file.
 - `web-search.ts` (`WebSearch`)
   - Search the web for current information with result snippets.
 - `web-fetch.ts` (`WebFetch`)
   - Fetch web page content and return readable markdown.
+  - Detects common anti-bot/captcha interstitial pages (for example WeChat risk-control pages) and returns an explicit block reason instead of noisy converted HTML.
+- `generate-image.ts` (`GenerateImage`)
+  - Generate images with Gemini API or OpenRouter.
 - `ask-question.ts` (`AskQuestion`)
   - Collect structured multiple-choice answers from the user.
 - `subagent.ts` / `subagent-description.md` (`Subagent`)
   - Launch delegated subagent subprocesses with foreground/background and parallel orchestration.
+- `bus-send.ts` (`BusSend`)
+  - Send messages to a displayName/agentId or broadcast to a channel over the cluster bus.
+- `mailbox.ts` (`MailBox`)
+  - Read queued bus messages that are not injected into the conversation.
 - `list-mcp-resources.ts` (`ListMcpResources`)
-  - Read `.pi/mcp.json` config and list MCP resources with server metadata.
+  - Read `.pi/mcp.json` (project) and `~/.pi/mcp.json` (user) configs to list MCP resources with server metadata.
 - `fetch-mcp-resource.ts` (`FetchMcpResource`)
   - Fetch a specific MCP resource by server + URI, optionally writing to workspace.
 - `list-mcp-tools.ts` (`ListMcpTools`)
@@ -45,6 +58,19 @@ Tool descriptions are now loaded by the tool implementation and exposed via the
 - `call-mcp-tool.ts` (`CallMcpTool`)
   - Call a remote MCP tool by server + tool name + JSON arguments.
 - `switch-mode.ts` (`SwitchMode`)
-  - Switch runtime interaction mode (tool supports `plan`; `/plan` toggles Plan/Agent).
+  - Switch runtime interaction mode (tool supports `plan`; optional `plan_file` binds a plan document path used by Plan-mode reminders).
+- `exit-plan-mode.ts` / `exit-plan-mode-description.md` (`ExitPlanMode`)
+  - Exit Plan mode and switch runtime mode back to Agent.
 - `apply-patch.ts` / `apply-patch-description.md` (`ApplyPatch`)
-  - Apply single-file patches in `*** Begin Patch` format.
+  - Apply single-file patches in `*** Begin Patch` format (SFTP auto-upload is attached by the SFTP extension hook).
+- `codex-apply-patch.ts` / `codex-apply-patch-description.md` (`CodexApplyPatch`)
+  - Apply codex-style multi-file patches (`Add/Delete/Update/Move`) with relative paths.
+
+### Brief tools
+
+- `brief-write.ts` (`brief_write`)
+  - Write content to a brief file with frontmatter preservation and line-limit validation.
+
+Brief files are stored in `~/.mono-pilot/agents/<agent-id>/brief/`.
+Core briefs are auto-injected into the system prompt via `src/brief/blocks.ts`.
+Reflection reminders are injected every 25 turns via `src/brief/reflection.ts`.

package/dist/{tools → src/tools}/apply-patch-description.md

@@ -1,4 +1,4 @@
-Use this tool to edit files.
+Use this tool to edit files. Patch path must be absolute.
 Your patch language is a stripped-down, file-oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high-level envelope:
 
 *** Begin Patch
@@ -33,6 +33,12 @@ For instructions on [context_before] and [context_after]:
 + [new_code]
 [3 lines of post-context]
 
+You can optionally anchor a hunk to a line number (1-based) to reduce ambiguity. Supported forms:
+@@ -42,5 +42,6 @@
+@@ line 42
+@@ line: 42-60
+The line hint is a search hint; context headers still apply if provided.
+
 The full grammar definition is below:
 Patch := Begin { FileOp } End
 Begin := "*** Begin Patch" NEWLINE
@@ -89,4 +95,4 @@ eof_line: "*** End of File" LF
 
 %import common.LF
 . You must reason carefully about the input and make sure it obeys the grammar.
-IMPORTANT: Do NOT call this tool in parallel with other tools.
+IMPORTANT: Do NOT call this tool in parallel with other tools.