mono-pilot 0.2.9 → 0.2.12

package/README.md

@@ -27,9 +27,25 @@ mono-pilot
 # Interactive
 mono-pilot
 
+# Interactive game profile (murder mystery, role-play)
+mono-pilot --mono-mode game
+
 # One-shot prompt
 mono-pilot -p "Refactor this module"
 
+# One-shot game prompt
+mono-pilot --mono-mode game -p "你现在是侦探，先做自我介绍"
+
+# Game mode with explicit channel override
+mono-pilot --mono-mode game --game-channel game:office-004
+
+# Game mode with identity auto-load from workspace
+# expects .mono-game/profile.json and optional .mono-game/identity.md
+mono-pilot --mono-mode game
+
+# Optional: limit tools per role
+# profile.json example: { "displayName": "侦探", "tools": ["BusSend", "MailBox", "ReadFile"] }
+
 # Continue previous session
 mono-pilot --continue
 ```
@@ -46,9 +62,14 @@ If you pass `--tools`, MonoPilot removes built-in `edit`, `write`, `read`, `grep
 
 - `src/cli.ts` – launcher that wraps `pi`
 - `src/extensions/mono-pilot.ts` – extension entrypoint (tool wiring)
+- `src/extensions/mono-game.ts` – game-oriented extension entrypoint (story + bus tools)
 - `src/extensions/system-prompt.ts` – provider-agnostic prompt stack
 - `src/extensions/user-message.ts` – user message envelope assembly
-- `tools/` – tool implementations and descriptions (see `tools/README.md`)
+- `src/brief/` – persistent agent memory ("brief" system), inspired by [letta-ai/letta-code](https://github.com/letta-ai/letta-code.git)'s memory architecture, renamed from "memory" to "brief" to distinguish condensed knowledge from conversation history
+- `src/memory/` – memory search indexing + retrieval (builtin, SQLite + FTS)
+- `src/mcp/` – config loading, JSON-RPC transport, server resolution
+- `src/rules/` – rule file discovery (shared by envelope and session hints)
+- `src/tools/` – tool implementations and descriptions (see `src/tools/README.md`)
 
 ## Cursor-styled tools
 
@@ -69,11 +90,15 @@ The full Cursor-styled tool list exposed by the extension:
 - `Shell` – execute shell commands in the workspace
 - `Glob` – find paths by glob pattern
 - `rg` – search file content with ripgrep
+- `AstGrep` – search code structure with ast-grep (`run`/`scan`, read-only)
 - `ReadFile` – read file content with pagination
 - `Delete` – delete files or directories
 - `SemanticSearch` – semantic search by intent
+- `memory_search` – search indexed memory snippets
+- `memory_get` – read a snippet from memory files
 - `WebSearch` – search the web with snippets
 - `WebFetch` – fetch and render web content
+- `GenerateImage` – generate images via Gemini API or OpenRouter
 - `AskQuestion` – collect structured multiple-choice answers
 - `Subagent` – launch delegated subprocesses
 - `ListMcpResources` – list MCP resources from config
@@ -81,21 +106,257 @@ The full Cursor-styled tool list exposed by the extension:
 - `ListMcpTools` – discover MCP tools and schemas
 - `CallMcpTool` – invoke MCP tools by name
 - `SwitchMode` – switch interaction mode (`option + m`, cycles Plan → Ask → Agent)
-- `ApplyPatch` – apply single-file patches
+- `ExitPlanMode` – exit Plan mode and switch back to Agent mode
+- `ApplyPatch` – apply single-file patches (supports diff-style @@ line hints)
+- `CodexApplyPatch` – apply codex-style multi-file patches with `Add/Delete/Update/Move` operations
+- `MailBox` – read queued bus messages (game mailbox)
 
 ## User rules
 
-MonoPilot can inject workspace user rules into the runtime envelope on each input (handled by `src/extensions/user-message.ts`).
+MonoPilot injects user rules into the runtime envelope on each turn (handled by `src/extensions/user-message.ts`).
+
+Rules are loaded from two locations:
 
-- Rules live in `.pi/rules/*.rule.txt` under the workspace root
-- Each file becomes one `<user_rule>` block wrapped by a `<rules>` envelope
-- Files are read in filename order; empty files are ignored
-- If no rules are present, the `<rules>` section is omitted
+- `~/.pi/rules/*.rule.txt` – user-level rules (applies to all projects)
+- `.pi/rules/*.rule.txt` – project-level rules (workspace root)
+
+When the same filename exists in both, the project rule wins. Each file becomes one `<user_rule>` block inside a `<rules>` envelope, sorted by filename. Empty files are ignored; the envelope is omitted if no rules are found.
 
 ## MCP
 
 - The user message envelope issues a lightweight MCP server `initialize` request to collect server instructions.
 - MCP tools then progressively load and surface resources, schemas, and execution only when needed.
+- MCP configs are loaded from `.pi/mcp.json` (project) and `~/.pi/mcp.json` (user); project entries take precedence on name conflicts.
+
+## Memory search
+
+- Builtin memory search reads `~/.mono-pilot/config.json` (`memorySearch` field). If missing, defaults are used.
+- Local embeddings use `node-llama-cpp`; configure `memorySearch.local.modelPath` (and optional `modelCacheDir`).
+- Session flush triggers are configured via `memorySearch.flush` (`onSessionSwitch`, `onSessionCompact`, `deltaBytes`, `deltaMessages`).
+- Use `/build-memory --mode full|dirty` to rebuild or incrementally sync the current agent's memory index partition.
+
+## Cluster v2 logging
+
+- Enable cluster_v2 with `MONO_PILOT_CLUSTER_V2=1` or `MONO_PILOT_CLUSTER_VERSION=2`.
+- cluster_v2 logs are persisted to `~/.mono-pilot/logs/cluster_v2.YYYY-MM-DD.log`.
+- Default behavior is file-only logging (keeps TUI clean). Set `MONO_PILOT_CLUSTER_V2_LOG_STDIO=1` to also mirror logs to stdout/stderr.
+- `/cluster` operational subcommands include `status`, `services`, `reelect`, `stepdown`, and `close`.
+
+## System events (TUI)
+
+- MonoPilot keeps an in-session system event queue for low-disruption operational signals (for example SFTP, memory warmup/build/session flush, cluster failover, Discord collector progress, and Twitter pull status/failures).
+- In interactive mode, info/warning/error system events show a bottom-right overlay toast (non-capturing), with latest-only replacement.
+- Overlay can be dismissed with `Esc` or clicking header `[×]`; a 2-minute timeout remains as a fallback.
+- Use `/events` to inspect recent events, `/events <N>` for more lines, and `/events clear` to reset.
+
+## Discord intelligence collector (leader-local)
+
+When `cluster_v2` is enabled, leader can run a local Discord IPC collector that subscribes to
+message events and persists them as JSONL for intelligence gathering.
+
+- No follower push
+- No Discord channel interaction
+- Local persistence only
+
+Config in `~/.mono-pilot/config.json`:
+
+```json
+{
+  "discord": {
+    "enabled": true,
+    "clientId": "YOUR_DISCORD_APP_ID",
+    "channels": [
+      {
+        "id": "123456789012345678",
+        "alias": "My Server / general"
+      }
+    ],
+    "events": ["MESSAGE_CREATE", "MESSAGE_UPDATE", "MESSAGE_DELETE"],
+    "scopes": ["rpc", "messages.read", "identify"],
+    "outputPath": "~/.mono-pilot/discord/messages.jsonl",
+    "includeRawPayload": false,
+    "systemEventBatchSize": 20
+  }
+}
+```
+
+Notes:
+
+- Requires a locally running Discord desktop client.
+- If `accessToken` is omitted, collector first tries cached auth from `~/.mono-pilot/auth.json`.
+- If cache is missing/invalid, collector runs RPC `AUTHORIZE` + OAuth token exchange, then stores tokens back to `~/.mono-pilot/auth.json`.
+- For first-time OAuth token exchange, many Discord apps require `clientSecret` (and sometimes `redirectUri`) in config.
+- `accessToken` and cached tokens are never printed in logs.
+- `channels[].alias` is persisted as `channelAlias` in each JSONL event record.
+- Collector enriches records by resolving `channelId -> channelName` and `guildId -> guildName` via RPC (`GET_CHANNEL` / `GET_GUILD`) when available.
+- Collector writes with daily rotation: `outputPath` is treated as base name and actual files are `<base>.YYYY-MM-DD.jsonl`.
+- Collector emits system-events when a channel accumulates `systemEventBatchSize` MESSAGE_CREATE events, then resets the channel counter and continues.
+- Collector service is registered as `discord_intel` in `/cluster services` when active.
+
+## Twitter intelligence collector (leader-local)
+
+When `cluster_v2` is enabled, leader can run a local Twitter/X collector via `bird` CLI.
+The collector verifies browser profile/cookie access at startup, then periodically pulls the
+"For You" timeline and persists JSONL records locally.
+
+Config in `~/.mono-pilot/config.json`:
+
+```json
+{
+  "twitter": {
+    "enabled": true,
+    "outputPath": "~/.mono-pilot/twitter/home.jsonl",
+    "pullIntervalMinutes": 10,
+    "pullCount": 10,
+    "commandTimeoutMs": 30000,
+    "requestTimeoutMs": 15000,
+    "chromeProfile": "Profile 4",
+    "chromeProfileDir": "~/Library/Application Support/Google/Chrome",
+    "cookieSource": ["chrome"],
+    "cookieTimeoutMs": 5000,
+    "includeRawPayload": false
+  }
+}
+```
+
+Notes:
+
+- Startup runs `bird check`; if browser profile/cookies are not readable, collector startup fails and is skipped (no in-process retry loop).
+- On successful startup, collector runs one timeline pull immediately and then every `pullIntervalMinutes`; it treats `bird home` and `bird home --following` as two channels and switches between them when the current channel returns 0 tweets.
+- Persisted `tweets[]` keeps bird top-level tweet objects as-is, including nested quote structure (not flattened).
+- Collector uses depth-1 enrichment (`tweet` + `quotedTweet`) and short-link resolution: it records `shortLinkMappings[]` (`shortUrl -> resolvedUrl -> tweetId?`) for all detected t.co links, and when a mapping resolves to a tweet id it attaches `shortLinkMappings[].tweetFull` (deduped by tweet id within a pull cycle, excluding self-reference where `tweetId` equals the host tweet id).
+- Before each pull, collector loads archived `tweetId` snapshots from the recent two-day window (`today` + `yesterday`) and skips re-archiving duplicates that already have `tweetFull`; duplicate ids with missing historical `tweetFull` are kept for backfill attempts.
+- Each persisted batch includes a unique `snapshotId` to avoid downstream overwrite collisions.
+- Persisted `feed` reflects the actual source timeline for the batch (`for_you` or `following`).
+- Per-cycle pull errors are reported as system-events/log warnings and skipped until next scheduled cycle (no immediate retry).
+- Collector writes with daily rotation: `outputPath` is treated as base name and actual files are `<base>.YYYY-MM-DD.jsonl`.
+- Collector service is registered as `twitter_intel` in `/cluster services` when active.
+
+## Digest draft command
+
+Use `/digest draft` to generate the digest draft in TUI.
+Use `/digest backfill` to serially backfill missing archive fields in-place (`tweetFull`, `quotedTweetFull`, `shortLinkMappings`).
+
+`/digest draft` reads the daily JSONL file (`<outputBase>.YYYY-MM-DD.jsonl`) and classifies tweets with TUI progress events.
+`/digest backfill` scans archive files and writes updates back to the same JSONL lines (serial mode to keep upstream pressure low).
+
+Config in `~/.mono-pilot/config.json`:
+
+```json
+{
+  "twitter": {
+    "digest": {
+      "classifier": {
+        "provider": "openai",
+        "model": "gpt-4o-mini",
+        "temperature": 0,
+        "maxTokens": 300,
+        "concurrency": 4
+      }
+    }
+  }
+}
+```
+
+Command examples:
+
+```text
+/digest draft
+/digest draft --date 2026-03-09
+/digest draft --file ~/.mono-pilot/twitter/home.2026-03-09.jsonl --concurrency 8 --sample 6
+/digest backfill
+/digest backfill --date 2026-03-09
+/digest backfill --file ~/.mono-pilot/twitter/home.2026-03-09.jsonl
+```
+
+Notes:
+
+- Classification categories are fixed to 7 classes: 技术 / 产品 / 融资并购 / 开源生态 / 组织动态 / 政策监管 / 学术研究.
+- Depth-1 enriched fields (`tweetFull`, `quotedTweetFull`) are used when present.
+- Draft rendering rewrites `t.co` short links to `shortLinkMappings[].resolvedUrl`; if the resolved link points to the host tweet itself, that short link is removed from draft text.
+- Draft mode now starts in background and rejects duplicate runs while active; check progress via `/events`.
+- Draft artifacts are written to `~/.mono-pilot/twitter/draft.md` (primary draft) and `~/.mono-pilot/twitter/draft-debug.md` (classification debug details).
+- Backfill mode is serial (non-concurrent), starts in background, and reuses per-run tweetId cache to avoid repeated `bird read` calls.
+- `/events` includes backfill start/file progress/end summary plus low-frequency item-level progress updates.
+
+## Image generation config
+
+`GenerateImage` can read defaults from `~/.mono-pilot/config.json`:
+
+```json
+{
+  "imageGen": {
+    "provider": "openrouter",
+    "model": "google/gemini-3.1-flash-image-preview"
+  },
+  "imageGenProviders": {
+    "openrouter": {
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "apiKey": "",
+      "authHeader": true,
+      "models": [
+        { "id": "google/gemini-3.1-flash-image-preview", "name": "Nano Banana 2" }
+      ]
+    }
+  }
+}
+```
+
+Use `/image-model` to switch the active provider/model stored in config:
+
+```text
+/image-model
+/image-model list
+/image-model use openrouter google/gemini-3.1-flash-image-preview
+```
+
+## SFTP sync on ApplyPatch
+
+If `.vscode/sftp.json` exists and a profile has `uploadOnSave: true`, patch tools can trigger uploads after successful writes:
+
+- `ApplyPatch`: uploads the affected file.
+- `CodexApplyPatch`: uploads files in `added[]` and `modified[]` (`deleted[]` is intentionally not auto-deleted remotely).
+
+Set `interactiveAuth: true` to enable OTP prompts for `/sftp` commands and patch-triggered sync when needed.
+
+Manual commands:
+
+```text
+/sftp
+/sftp upload path/to/file-or-dir
+/sftp download path/to/file-or-dir
+/sftp target <targetName>
+```
+
+`/sftp` (without args) opens an interactive target selector (up/down to choose, enter to confirm).
+
+```json
+[
+  {
+    "name": "prod",
+    "protocol": "sftp",
+    "host": "10.0.0.130",
+    "port": 22,
+    "username": "wanqian",
+    "privateKeyPath": "~/.ssh/id_rsa",
+    "passphrase": "...",
+    "remotePath": "/home/wanqian/project",
+    "uploadOnSave": true,
+    "interactiveAuth": true,
+    "hop": {
+      "host": "36.151.163.132",
+      "port": 22,
+      "username": "wanqian",
+      "privateKeyPath": "/Users/wanqian/.ssh/id_rsa",
+      "passphrase": "...",
+      "interactiveAuth": true
+    }
+  }
+]
+```
+
+`hop` enables single-jump SFTP tunneling (`local -> hop -> target`).
+Both target and hop authentication are performed by the local client, so `privateKeyPath` values must point to local files.
 
 ## Local development
 
@@ -122,6 +383,8 @@ npm run dev:continue
 npm run dev:watch:continue
 ```
 
+When running in interactive mode, `option+o` opens the current workspace directory in `nvim` (falls back to `vim` when `nvim` is unavailable).
+
 ## Prompt inspection
 
 ```bash

package/dist/src/agents-paths.js

@@ -0,0 +1,36 @@
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/**
+ * Derive a stable, traceable agent ID from a project path.
+ * Uses the same convention as pi-coding-agent session directories:
+ * `/Users/wanqian/foo` → `--Users-wanqian-foo--`
+ */
+export function deriveAgentId(cwd) {
+    return `-${resolve(cwd).replaceAll("/", "-")}--`;
+}
+export function getAllAgentsDir() {
+    return join(homedir(), ".mono-pilot", "agents");
+}
+export function getAgentDir(agentId) {
+    return join(getAllAgentsDir(), agentId);
+}
+export function getAgentMemoryDir(agentId) {
+    return join(getAgentDir(agentId), "memory");
+}
+export function getAgentTerminalsDir(agentId, sessionId) {
+    return join(getAgentDir(agentId), "terminals", sessionId);
+}
+export async function listAgentIds() {
+    const baseDir = getAllAgentsDir();
+    try {
+        const entries = await readdir(baseDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/src/brief/blocks.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { deriveAgentId, getAgentBriefDir } from "./paths.js";
+import { parseFrontmatter } from "./frontmatter.js";
+import { ensureDefaults } from "./defaults.js";
+/** Recursively collect .md files under a directory, returning parsed body content. */
+function collectMarkdownFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    function walk(currentDir) {
+        let entries;
+        try {
+            entries = readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                walk(fullPath);
+            }
+            else if (entry.name.endsWith(".md")) {
+                try {
+                    const raw = readFileSync(fullPath, "utf-8");
+                    const { body } = parseFrontmatter(raw);
+                    const trimmed = body.trim();
+                    if (trimmed.length > 0) {
+                        results.push({ relativePath: relative(dir, fullPath), body: trimmed });
+                    }
+                }
+                catch {
+                    // skip unreadable files
+                }
+            }
+        }
+    }
+    walk(dir);
+    return results.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+function buildSection(heading, pathHint, files) {
+    if (files.length === 0)
+        return "";
+    const lines = [`## ${heading}  [${pathHint}]`];
+    for (const f of files) {
+        lines.push(`### ${f.relativePath}`);
+        lines.push(f.body);
+    }
+    return lines.join("\n");
+}
+const BRIEF_GUIDELINE = "When applying this brief in responses, integrate it naturally — like a colleague who recalls shared context. " +
+    'Never draw attention to the brief system itself or use phrases like "I remember that..." — just use what you know seamlessly.';
+const BRIEF_CHECK = "Review this conversation for information worth storing in your brief. " +
+    "Update silently (no confirmation needed) via brief_write if you learned:\n" +
+    "- **User info**: Name, role, preferences, working style, current goals\n" +
+    "- **Project details**: Architecture, patterns, gotchas, dependencies, conventions\n" +
+    "- **Corrections**: User corrected you or clarified something important\n" +
+    "- **Preferences**: How they want you to behave, communicate, or approach tasks\n\n" +
+    'Ask yourself: "If I started a new session tomorrow, what from this conversation would I want to remember?" ' +
+    "If the answer is meaningful, update the appropriate brief file(s) now.";
+/**
+ * Read all core brief files and build the <brief> block for system prompt injection.
+ * Creates default template files if they don't exist yet.
+ */
+export function buildBriefBlock(cwd) {
+    const agentId = deriveAgentId(cwd);
+    ensureDefaults(agentId);
+    const briefDir = getAgentBriefDir(agentId);
+    const sections = [];
+    const humanSection = buildSection("User Context", `~/.mono-pilot/agents/${agentId}/brief/human/`, collectMarkdownFiles(join(briefDir, "human")));
+    if (humanSection)
+        sections.push(humanSection);
+    const projectSection = buildSection("Project Context", `~/.mono-pilot/agents/${agentId}/brief/project/`, collectMarkdownFiles(join(briefDir, "project")));
+    if (projectSection)
+        sections.push(projectSection);
+    const tasksSection = buildSection("Current Tasks", `~/.mono-pilot/agents/${agentId}/brief/tasks/`, collectMarkdownFiles(join(briefDir, "tasks")));
+    if (tasksSection)
+        sections.push(tasksSection);
+    if (sections.length === 0)
+        return "";
+    return `<brief>\n${sections.join("\n\n")}\n\n${BRIEF_GUIDELINE}\n\n${BRIEF_CHECK}\n</brief>`;
+}

package/dist/src/brief/defaults.js

@@ -0,0 +1,60 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentBriefDir } from "./paths.js";
+const DEFAULTS = {
+    "human/identity.md": {
+        description: "What I know about the person I'm working with. Update when learning about their background, role, or identity.",
+        limit: 40,
+        content: "I haven't gotten to know this person yet.",
+    },
+    "human/prefs/communication.md": {
+        description: "How this person prefers to communicate. Update when they express language, verbosity, or style preferences.",
+        limit: 30,
+        content: "No communication preferences learned yet.",
+    },
+    "human/prefs/coding-style.md": {
+        description: "Coding conventions and style preferences. Update when they show patterns in naming, formatting, or tooling choices.",
+        limit: 30,
+        content: "No coding style preferences learned yet.",
+    },
+    "project/overview.md": {
+        description: "High-level understanding of this project. Update after exploring the codebase structure, tech stack, and architecture.",
+        limit: 50,
+        content: "I'm still getting to know this codebase.\nIf there's an AGENTS.md, CLAUDE.md, or README, I should read it early.",
+    },
+    "project/commands.md": {
+        description: "Build, test, lint, and run commands. Update when discovering or confirming project commands.",
+        limit: 30,
+        content: "No commands discovered yet.",
+    },
+    "project/conventions.md": {
+        description: "Code conventions, commit style, and recurring patterns. Update when observing how this project does things.",
+        limit: 40,
+        content: "No conventions learned yet.",
+    },
+    "project/gotchas.md": {
+        description: "Known pitfalls, warnings, and surprising behavior. Update when hitting unexpected issues.",
+        limit: 40,
+        content: "No gotchas discovered yet.",
+    },
+    "tasks/current.md": {
+        description: "Current task progress and status. Update when starting, progressing, or completing tasks.",
+        limit: 50,
+        content: "No active tasks.",
+    },
+};
+function writeDefaultFile(baseDir, relativePath, template) {
+    const filePath = join(baseDir, relativePath);
+    if (existsSync(filePath))
+        return;
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    const content = `---\ndescription: ${template.description}\nlimit: ${template.limit}\n---\n${template.content}\n`;
+    writeFileSync(filePath, content, "utf-8");
+}
+export function ensureDefaults(agentId) {
+    const dir = getAgentBriefDir(agentId);
+    for (const [path, template] of Object.entries(DEFAULTS)) {
+        writeDefaultFile(dir, path, template);
+    }
+}

package/dist/src/brief/frontmatter.js

@@ -0,0 +1,53 @@
+/**
+ * Parse YAML frontmatter from a brief file.
+ * Supports only `description` (string) and `limit` (positive integer).
+ */
+export function parseFrontmatter(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith("---")) {
+        return { frontmatter: {}, body: content };
+    }
+    const endIndex = trimmed.indexOf("\n---", 3);
+    if (endIndex === -1) {
+        return { frontmatter: {}, body: content };
+    }
+    const yamlBlock = trimmed.slice(4, endIndex).trim();
+    const body = trimmed.slice(endIndex + 4).trimStart();
+    const frontmatter = {};
+    for (const line of yamlBlock.split("\n")) {
+        const colonIndex = line.indexOf(":");
+        if (colonIndex === -1)
+            continue;
+        const key = line.slice(0, colonIndex).trim();
+        const value = line.slice(colonIndex + 1).trim();
+        if (key === "limit") {
+            const num = parseInt(value, 10);
+            if (!isNaN(num) && num > 0)
+                frontmatter.limit = num;
+        }
+        else if (key === "description") {
+            frontmatter.description = value;
+        }
+    }
+    return { frontmatter, body };
+}
+export function serializeWithFrontmatter(frontmatter, body) {
+    const lines = ["---"];
+    if (frontmatter.description) {
+        lines.push(`description: ${frontmatter.description}`);
+    }
+    if (frontmatter.limit !== undefined) {
+        lines.push(`limit: ${frontmatter.limit}`);
+    }
+    lines.push("---");
+    if (body.length > 0) {
+        lines.push(body);
+    }
+    return lines.join("\n") + "\n";
+}
+export function countBodyLines(body) {
+    const trimmed = body.trim();
+    if (trimmed.length === 0)
+        return 0;
+    return trimmed.split("\n").length;
+}

package/dist/src/brief/paths.js

@@ -0,0 +1,10 @@
+import { join } from "node:path";
+import { getAgentDir } from "../agents-paths.js";
+// Re-export agent-level paths for backward compatibility during migration
+export { deriveAgentId, getAgentDir, getAllAgentsDir } from "../agents-paths.js";
+export function getAgentBriefDir(agentId) {
+    return join(getAgentDir(agentId), "brief");
+}
+export function resolveBriefPath(relativePath, agentId) {
+    return join(getAgentBriefDir(agentId), relativePath);
+}

package/dist/src/brief/reflection.js

@@ -0,0 +1,27 @@
+const REFLECTION_INTERVAL = 25;
+let turnCount = 0;
+let pendingCompactionReflection = false;
+/** Flag that a compaction just occurred — next turn will get a reflection reminder. */
+export function onCompaction() {
+    pendingCompactionReflection = true;
+}
+/**
+ * Return a reflection reminder if triggered by compaction event
+ * or periodic turn interval. Compaction trigger takes priority.
+ */
+export function getBriefReflectionReminder() {
+    turnCount++;
+    const triggered = pendingCompactionReflection || turnCount % REFLECTION_INTERVAL === 0;
+    if (!triggered)
+        return undefined;
+    const source = pendingCompactionReflection ? "post-compaction" : `turn ${turnCount}`;
+    pendingCompactionReflection = false;
+    return `<brief_reminder>
+[${source}] Review this conversation for information worth remembering across sessions. If you learned anything important, use brief_write to update the relevant file:
+- User info / preferences -> human/identity.md or human/prefs/
+- Project context / architecture -> project/overview.md, project/conventions.md, etc.
+- Task progress -> tasks/current.md
+Ask yourself: "If I started a new session tomorrow, what from this conversation would I want to remember?"
+Keep notes factual and concise. Append new info rather than overwriting existing knowledge.
+</brief_reminder>`;
+}