pi-rebrief 0.0.0 → 0.1.0

package/README.md

@@ -1,14 +1,17 @@
 # pi-rebrief
 
-[![Known Vulnerabilities](https://snyk.io/test/github/asakin/pi-rebrief/badge.svg)](https://snyk.io/test/github/asakin/pi-rebrief)
+![npm](https://img.shields.io/npm/v/pi-rebrief) ![CI](https://github.com/asakin/pi-rebrief/actions/workflows/ci.yml/badge.svg) ![license](https://img.shields.io/npm/l/pi-rebrief) ![Known Vulnerabilities](https://snyk.io/test/github/asakin/pi-rebrief/badge.svg)
 
-A [Pi](https://pi.dev) extension that adds a `/rebrief` command. It reloads only the
-project context files, including `AGENTS.md` and `CLAUDE.md`, into a running session, and
-tells you which files changed. It loads them with the same function Pi uses, so it picks up
-whatever files your Pi version discovers.
+A [Pi](https://pi.dev) extension that adds a `/rebrief` command. It reloads the project
+context files, including `AGENTS.md` and `CLAUDE.md`, into the running session and tells you
+which files have changed.
 
-Pi's own `/reload` also re-reads context files, but along with everything else: settings,
-extensions, MCP servers, skills and themes. `/rebrief` leaves all of that running.
+It also flags in the status bar when those files change on disk, for example after a `git pull`
+or a branch switch.
+
+`/reload` refreshes the whole session: settings, extensions, MCP servers, skills, themes, and
+context files. `/rebrief` is for when only the context files changed, including while a turn
+is in progress.
 
 ## Install
 
@@ -16,30 +19,42 @@ extensions, MCP servers, skills and themes. `/rebrief` leaves all of that runnin
 pi install npm:pi-rebrief
 ```
 
-Then run `/reload` in an active session, or try it for a single session without installing:
-
-```bash
-pi -e npm:pi-rebrief
-```
+Restart or `/reload` your session to use.
 
 ## Usage
 
-Edit a context file, then run:
+When a context file changes on disk, the status bar says so:
 
+```text
+● pi-rebrief: AGENTS.md changed on disk since it was loaded. Run /rebrief to load the new version.
 ```
+
+Nothing is reloaded until you run:
+
+```text
 /rebrief
 ```
 
-The next turn sees the new instructions, and so does every turn after it. `/rebrief` reports
+Your next message runs with the new instructions, and so does everything after it. `/rebrief` reports
 what it found, for example:
 
-- `Reloaded context files: changed AGENTS.md, added sub/AGENTS.md.`
-- `Context files unchanged (2 context files).`
+```text
+pi-rebrief: reloaded context files.
+  changed: AGENTS.md
+  added:   sub/AGENTS.md
+They apply from your next message.
+```
+
+If you run it while a turn is in progress, the rest of that turn will use the new
+instructions.
 
-If Pi was started with `--no-context-files`, `/rebrief` does nothing.
+## Examples
 
-Pair it with `/tree` to rewind a couple of turns, tighten an instruction in `AGENTS.md`,
-run `/rebrief`, and continue from before the derail.
+- Pair it with `/tree` to retry an earlier prompt under new instructions.
+- The agent derails. Rewind with `/tree` to the turn before it did, tighten the instruction
+it missed in `AGENTS.md`, run `/rebrief`, and continue from there.
+- You `git pull` mid-task and a teammate's commit changed `AGENTS.md`. The status bar flags
+it; run `/rebrief` and keep going in the same session.
 
 ## License
 

package/format.ts

@@ -0,0 +1,117 @@
+import { homedir } from "node:os";
+import { isAbsolute, relative, sep } from "node:path";
+
+type ContextFile = { path: string; content: string };
+
+// Every message starts with this so a user who forgot the extension knows where it comes from
+const PREFIX = "pi-rebrief:";
+
+// How many file names to show before falling back to "and N more"
+const MAX_LISTED = 3;
+
+// Show a path relative to cwd when inside it or in a parent folder, else home-relative, else absolute
+function displayPath(path: string, cwd: string, home: string): string {
+  const rel = relative(cwd, path);
+  if (rel && !isAbsolute(rel) && (!rel.startsWith("..") || /^(\.\.[/\\])+[^/\\]+$/.test(rel))) {
+    return rel;
+  }
+  if (home && path.startsWith(home + sep)) {
+    return `~${path.slice(home.length)}`;
+  }
+  return path;
+}
+
+interface Changes {
+  changed: string[];
+  added: string[];
+  removed: string[];
+}
+
+function diffFiles(previous: readonly ContextFile[], fresh: readonly ContextFile[], cwd: string, home: string): Changes {
+  const before = new Map(previous.map((file) => [file.path, file.content]));
+  const after = new Set(fresh.map((file) => file.path));
+  const changes: Changes = { changed: [], added: [], removed: [] };
+  for (const file of fresh) {
+    const old = before.get(file.path);
+    if (old === undefined) {
+      changes.added.push(displayPath(file.path, cwd, home));
+    } else if (old !== file.content) {
+      changes.changed.push(displayPath(file.path, cwd, home));
+    }
+  }
+  for (const file of previous) {
+    if (!after.has(file.path)) {
+      changes.removed.push(displayPath(file.path, cwd, home));
+    }
+  }
+  return changes;
+}
+
+function fileCount(count: number): string {
+  return `${count} file${count === 1 ? "" : "s"}`;
+}
+
+// The /rebrief summary: one line per kind of change, capped at MAX_LISTED names
+export function describeChanges(
+  previous: readonly ContextFile[],
+  fresh: readonly ContextFile[],
+  cwd: string,
+  home: string = homedir(),
+): string[] {
+  const changes = diffFiles(previous, fresh, cwd, home);
+  const lines: string[] = [];
+  let remaining = MAX_LISTED;
+  for (const kind of ["changed", "added", "removed"] as const) {
+    const shown = changes[kind].slice(0, remaining);
+    if (shown.length > 0) {
+      lines.push(`  ${`${kind}:`.padEnd(8)} ${shown.join(", ")}`);
+      remaining -= shown.length;
+    }
+  }
+  const total = changes.changed.length + changes.added.length + changes.removed.length;
+  if (total === 0) {
+    lines.push("  order changed");
+  } else if (total > MAX_LISTED) {
+    lines.push(`  and ${total - MAX_LISTED} more`);
+  }
+  return lines;
+}
+
+export function formatReloadedNotice(
+  previous: readonly ContextFile[],
+  files: readonly ContextFile[],
+  cwd: string,
+  running: boolean,
+): string {
+  const when = running
+    ? "They apply to the current turn, starting with the agent's next step."
+    : "They apply from your next message.";
+  return [`${PREFIX} reloaded context files.`, ...describeChanges(previous, files, cwd), when].join("\n");
+}
+
+export function formatUnchangedNotice(count: number): string {
+  return `${PREFIX} context files are unchanged (${fileCount(count)}). Nothing to reload.`;
+}
+
+export function formatDisabledNotice(): string {
+  return `${PREFIX} Pi was started with --no-context-files, so there are no context files to reload.`;
+}
+
+// Status bar text when the files on disk differ from what the session loaded
+export function formatStaleStatus(
+  loaded: readonly ContextFile[],
+  onDisk: readonly ContextFile[],
+  cwd: string,
+  home: string = homedir(),
+): string {
+  const changes = diffFiles(loaded, onDisk, cwd, home);
+  const names = [...changes.changed, ...changes.added, ...changes.removed];
+  if (names.length === 1) {
+    return `● ${PREFIX} ${names[0]} changed on disk since it was loaded. Run /rebrief to load the new version.`;
+  }
+  const listed = names.slice(0, MAX_LISTED).join(", ");
+  const more = names.length > MAX_LISTED ? `, and ${names.length - MAX_LISTED} more` : "";
+  const which = names.length > 0 ? ` (${listed}${more})` : "";
+  const count = names.length > 0 ? `${names.length} context files` : "context files";
+  return `● ${PREFIX} ${count} changed on disk since they were loaded${which}. Run /rebrief to load them.`;
+}

package/index.ts

@@ -1,10 +1,13 @@
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
+  ExtensionUIContext,
 } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
-import { homedir } from "node:os";
-import { isAbsolute, relative, sep } from "node:path";
+import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
+import { formatDisabledNotice, formatReloadedNotice, formatStaleStatus, formatUnchangedNotice } from "./format.ts";
+
+export { describeChanges, formatStaleStatus } from "./format.ts";
 
 export interface ContextFile {
   path: string;
@@ -12,142 +15,154 @@ export interface ContextFile {
 }
 
 export interface RebriefDeps {
-  getAgentDir?: () => string;
   loadProjectContextFiles?: (options: { cwd: string; agentDir: string }) => ContextFile[];
   contextFilesDisabled?: () => boolean;
+  startTimer?: (tick: () => void, ms: number) => () => void;
 }
 
+const STATUS_KEY = "pi-rebrief";
+const POLL_MS = 3000; // How often to check for context file changes
+
 // Check if Pi was started with --no-context-files (-nc); extensions can't read built-in flags
 export function contextFilesDisabledByArgv(argv: readonly string[]): boolean {
   return argv.includes("--no-context-files") || argv.includes("-nc");
 }
 
-// Check if two sets of context files are the same
 export function sameContextFiles(a: readonly ContextFile[], b: readonly ContextFile[]): boolean {
-  if (a.length !== b.length) return false;
+  if (a.length !== b.length) {
+    return false;
+  }
   for (let i = 0; i < a.length; i++) {
-    const left = a[i]!;
-    const right = b[i]!;
-    if (left.path !== right.path || left.content !== right.content) return false;
+    if (a[i]!.path !== b[i]!.path || a[i]!.content !== b[i]!.content) {
+      return false;
+    }
   }
   return true;
 }
 
-// Show a path relative to cwd when inside it, else home-relative, else absolute
-function displayPath(path: string, cwd: string, home: string): string {
-  const rel = relative(cwd, path);
-  if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return rel;
-  if (home && path.startsWith(home + sep)) return `~${path.slice(home.length)}`;
-  return path;
-}
-
-const MAX_LISTED = 3;
-
-// Summarize which context files changed, were added, or were removed
-export function describeChanges(
-  previous: readonly ContextFile[],
-  fresh: readonly ContextFile[],
-  cwd: string,
-  home: string = homedir(),
-): string {
-  const before = new Map(previous.map((file) => [file.path, file.content]));
-  const after = new Set(fresh.map((file) => file.path));
-  const entries: string[] = [];
-  for (const file of fresh) {
-    const old = before.get(file.path);
-    if (old === undefined) entries.push(`added ${displayPath(file.path, cwd, home)}`);
-    else if (old !== file.content) entries.push(`changed ${displayPath(file.path, cwd, home)}`);
+// Render the project_context prompt section the way Pi does (Pi does not export its renderer)
+export function renderProjectContext(files: readonly ContextFile[]): string | null {
+  if (files.length === 0) {
+    return null;
   }
-  for (const file of previous) {
-    if (!after.has(file.path)) entries.push(`removed ${displayPath(file.path, cwd, home)}`);
-  }
-  if (entries.length === 0) return "order changed";
-
-  // "changed a, b" instead of "changed a, changed b"
-  const merged: string[] = [];
-  let lastVerb = "";
-  for (const entry of entries.slice(0, MAX_LISTED)) {
-    const [verb] = entry.split(" ", 1);
-    merged.push(verb === lastVerb ? entry.slice(verb!.length + 1) : entry);
-    lastVerb = verb!;
-  }
-  const more = entries.length - MAX_LISTED;
-  return more > 0 ? `${merged.join(", ")}, and ${more} more` : merged.join(", ");
+  const body = [
+    "Project-specific instructions and guidelines:",
+    ...files.map(({ path, content }) => `<project_instructions path="${path}">\n${content}\n</project_instructions>`),
+  ].join("\n\n");
+  return `<project_context>\n${body}\n</project_context>`;
 }
 
-// Format the number of context files into a human-readable string
-function fileCountLabel(count: number): string {
-  return `${count} context file${count === 1 ? "" : "s"}`;
+function startInterval(tick: () => void, ms: number): () => void {
+  const timer = setInterval(tick, ms);
+  timer.unref?.();
+  return () => clearInterval(timer);
 }
 
-// Clone the context files
-function cloneContextFiles(files: readonly ContextFile[]): ContextFile[] {
-  return files.map((file) => ({ path: file.path, content: file.content }));
-}
-
-// Create the rebrief extension
 export function createRebriefExtension(deps: RebriefDeps = {}) {
-  const resolveAgentDir = deps.getAgentDir ?? getAgentDir;
   const loadContextFiles = deps.loadProjectContextFiles ?? loadProjectContextFiles;
   const contextFilesDisabled = deps.contextFilesDisabled ?? (() => contextFilesDisabledByArgv(process.argv));
+  const startTimer = deps.startTimer ?? startInterval;
 
   return function piRebrief(pi: ExtensionAPI) {
-    let rebriefed: { cwd: string; files: ContextFile[] } | undefined;
+    // The context files the session has
+    let files: ContextFile[] = [];
+    // The user ran /rebrief: stamp `files` onto every run
+    let pinned = false;
+    // A /rebrief issued while a run was in progress; anchored after the newest message of the next request
+    let pending: { anchor?: number; at: number } | undefined;
+    let stopTimer: (() => void) | undefined;
+    let status: string | undefined;
+
+    const load = (cwd: string) => loadContextFiles({ cwd, agentDir: getAgentDir() });
+
+    const showStatus = (ui: ExtensionUIContext | undefined, text: string | undefined) => {
+      const next = text === undefined ? undefined : ui?.theme.fg("warning", text);
+      if (!ui || next === status) {
+        return;
+      }
+      status = next;
+      ui.setStatus(STATUS_KEY, next);
+    };
+
+    pi.on("session_start", (_event, ctx) => {
+      pinned = false;
+      pending = undefined;
+      status = undefined;
+      stopTimer?.();
+      stopTimer = undefined;
+      if (contextFilesDisabled()) {
+        return;
+      }
+      const ui = ctx.hasUI ? ctx.ui : undefined;
+      files = load(ctx.cwd);
+      stopTimer = startTimer(() => {
+        const onDisk = load(ctx.cwd);
+        showStatus(ui, sameContextFiles(files, onDisk) ? undefined : formatStaleStatus(files, onDisk, ctx.cwd));
+      }, POLL_MS);
+    });
 
-    pi.on("session_start", () => {
-      rebriefed = undefined;
+    pi.on("session_shutdown", () => {
+      stopTimer?.();
+      stopTimer = undefined;
     });
 
     pi.registerCommand("rebrief", {
       description: "Reload only context files (lighter than /reload)",
       handler: async (_args: string, ctx: ExtensionCommandContext) => {
-        if (contextFilesDisabled()) {
+        const notify = (msg: string, level: "info" | "warning") => {
           if (ctx.hasUI) {
-            ctx.ui.notify("Context files are disabled (--no-context-files) — nothing to rebrief.", "warning");
+            ctx.ui.notify(msg, level);
           }
-          return;
-        }
+        };
 
-        let freshFiles: ContextFile[];
-        try {
-          freshFiles = loadContextFiles({
-            cwd: ctx.cwd,
-            agentDir: resolveAgentDir(),
-          });
-        } catch (err) {
-          if (ctx.hasUI) {
-            const detail = err instanceof Error ? err.message : String(err);
-            ctx.ui.notify(`Failed to reload context files: ${detail}`, "error");
-          }
+        if (contextFilesDisabled()) {
+          notify(formatDisabledNotice(), "warning");
           return;
         }
 
-        const baseOptions = ctx.getSystemPromptOptions?.();
-        const previousFiles =
-          rebriefed?.cwd === ctx.cwd
-            ? rebriefed.files
-            : (baseOptions?.contextFiles ?? []);
-        const changed = !sameContextFiles(previousFiles, freshFiles);
-
-        rebriefed = { cwd: ctx.cwd, files: cloneContextFiles(freshFiles) };
-        if (baseOptions) {
-          baseOptions.contextFiles = cloneContextFiles(freshFiles);
+        const previous = files;
+        files = load(ctx.cwd);
+        pinned = true;
+        const changed = !sameContextFiles(previous, files);
+        const running = !ctx.isIdle();
+        if (changed && running) {
+          pending = { at: Date.now() };
         }
 
-        if (!ctx.hasUI) return;
+        showStatus(ctx.hasUI ? ctx.ui : undefined, undefined);
 
         if (!changed) {
-          ctx.ui.notify(`Context files unchanged (${fileCountLabel(freshFiles.length)}).`, "info");
+          notify(formatUnchangedNotice(files.length), "info");
           return;
         }
-
-        ctx.ui.notify(`Reloaded context files: ${describeChanges(previousFiles, freshFiles, ctx.cwd)}.`, "info");
+        notify(formatReloadedNotice(previous, files, ctx.cwd, running), "info");
       },
     });
 
-    pi.on("before_agent_start", async (event) => {
-      if (!rebriefed || rebriefed.cwd !== event.systemPromptOptions.cwd) return;
-      event.systemPromptOptions.contextFiles = cloneContextFiles(rebriefed.files);
+    pi.on("before_agent_start", (event) => {
+      pending = undefined;
+      if (pinned) {
+        event.systemPromptOptions.contextFiles = files.map((file) => ({ ...file }));
+      } else {
+        files = event.systemPromptOptions.contextFiles ?? [];
+      }
+    });
+
+    // Mid-run /rebrief: add a request-local section update until the next run starts
+    pi.on("context_with_system", (event) => {
+      if (!pending) {
+        return;
+      }
+      const messages = event.messages;
+      const desired = renderProjectContext(files);
+      if ((getCurrentSystemMessage(messages)?.sections?.project_context ?? null) === desired) {
+        return;
+      }
+      pending.anchor ??= messages.at(-1)?.timestamp;
+      const update = { role: "system" as const, content: "", sections: { project_context: desired }, timestamp: pending.at };
+      const anchor = messages.findIndex((m) => m.timestamp === pending!.anchor);
+      const at = anchor === -1 ? messages.length : anchor + 1;
+      return { messages: [...messages.slice(0, at), update, ...messages.slice(at)] };
     });
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-rebrief",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "type": "module",
   "description": "Reload only the project context files, including AGENTS.md and CLAUDE.md, into a running Pi session: no extension restart or MCP reconnect like /reload, plus a report of what changed.",
   "keywords": [
@@ -26,6 +26,7 @@
   },
   "files": [
     "index.ts",
+    "format.ts",
     "README.md",
     "LICENSE"
   ],
@@ -39,6 +40,7 @@
     "test": "node --test"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {