pi-rebrief 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariel Sakin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# pi-rebrief
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![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 the project
+context files, including `AGENTS.md` and `CLAUDE.md`, into the running session and tells you
+which files have changed.
+
+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
+
+```bash
+pi install npm:pi-rebrief
+```
+
+Restart or `/reload` your session to use.
+
+## Usage
+
+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
+```
+
+Your next message runs with the new instructions, and so does everything after it. `/rebrief` reports
+what it found, for example:
+
+```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.
+
+## Examples
+
+- 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
+
+MIT

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

@@ -0,0 +1,170 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionUIContext,
+} from "@earendil-works/pi-coding-agent";
+import { getAgentDir, loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+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;
+  content: string;
+}
+
+export interface RebriefDeps {
+  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");
+}
+
+export function sameContextFiles(a: readonly ContextFile[], b: readonly ContextFile[]): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i]!.path !== b[i]!.path || a[i]!.content !== b[i]!.content) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// 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;
+  }
+  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>`;
+}
+
+function startInterval(tick: () => void, ms: number): () => void {
+  const timer = setInterval(tick, ms);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}
+
+export function createRebriefExtension(deps: RebriefDeps = {}) {
+  const loadContextFiles = deps.loadProjectContextFiles ?? loadProjectContextFiles;
+  const contextFilesDisabled = deps.contextFilesDisabled ?? (() => contextFilesDisabledByArgv(process.argv));
+  const startTimer = deps.startTimer ?? startInterval;
+
+  return function piRebrief(pi: ExtensionAPI) {
+    // 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_shutdown", () => {
+      stopTimer?.();
+      stopTimer = undefined;
+    });
+
+    pi.registerCommand("rebrief", {
+      description: "Reload only context files (lighter than /reload)",
+      handler: async (_args: string, ctx: ExtensionCommandContext) => {
+        const notify = (msg: string, level: "info" | "warning") => {
+          if (ctx.hasUI) {
+            ctx.ui.notify(msg, level);
+          }
+        };
+
+        if (contextFilesDisabled()) {
+          notify(formatDisabledNotice(), "warning");
+          return;
+        }
+
+        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() };
+        }
+
+        showStatus(ctx.hasUI ? ctx.ui : undefined, undefined);
+
+        if (!changed) {
+          notify(formatUnchangedNotice(files.length), "info");
+          return;
+        }
+        notify(formatReloadedNotice(previous, files, ctx.cwd, running), "info");
+      },
+    });
+
+    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)] };
+    });
+  };
+}
+
+export default createRebriefExtension();

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "pi-rebrief",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "pi",
+    "agents-md",
+    "claude-md",
+    "context-files",
+    "reload",
+    "system-prompt"
+  ],
+  "license": "MIT",
+  "author": "Ariel Sakin <asakin@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asakin/pi-rebrief.git"
+  },
+  "homepage": "https://github.com/asakin/pi-rebrief#readme",
+  "bugs": {
+    "url": "https://github.com/asakin/pi-rebrief/issues"
+  },
+  "files": [
+    "index.ts",
+    "format.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.0.0",
+    "@types/node": ">=22.0.0",
+    "typescript": ">=5.0.0"
+  }
+}