@lazco/pi-rules 0.8.0 → 0.9.0

package/README.md

@@ -87,6 +87,9 @@ pi-rules reads the injected rules from the messages that the model sees, so it s
 - resume a session, run `/reload`, or fork a session,
 - compact the session. The rules that the summary replaced load again when they are needed.
 
+When you change a rule file that already loaded, also only its frontmatter, the new version loads before the next model call, marked `(updated)`.
+When you delete it, the model gets a short notice that the rule no longer applies.
+
 ## Rule files
 
 A rule is a Markdown file.
@@ -203,7 +206,6 @@ pi-rules reads `rules.json` when a session starts and after a compaction.
 
 - **Project rules of other projects.** A file in another project loads only user rules, not the rules in the directories of that project.
 - **Shell commands.** A file that a `bash` command changes does not load a rule.
-- **Changed rules.** A rule that already loaded does not load again after you change its file, until the next compaction.
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazco/pi-rules",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Pi extension: load Markdown rules into the agent context for the whole project or for matching files",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/src/discovery.ts

@@ -141,7 +141,7 @@ export async function parseRuleFile(sourcePath: string, sourceLabel: string, sco
       return { diagnostic: { sourceLabel, reason: "unclosed frontmatter" } };
     }
     const body = content.replace(/^\uFEFF/, "");
-    return { rule: { id: sourcePath, sourcePath, sourceLabel, scope, body, hash: hashBody(body) } };
+    return { rule: { id: sourcePath, sourcePath, sourceLabel, scope, body, hash: hashContent(content) } };
   }
 
   let raw: unknown;
@@ -183,7 +183,7 @@ export async function parseRuleFile(sourcePath: string, sourceLabel: string, sco
   }
 
   const body = content.slice(frontmatter[0].length);
-  const rule: Rule = { id: sourcePath, sourcePath, sourceLabel, scope, body, hash: hashBody(body) };
+  const rule: Rule = { id: sourcePath, sourcePath, sourceLabel, scope, body, hash: hashContent(content) };
   if (paths) rule.paths = paths;
   if (events) rule.events = events;
   if (skills) rule.skills = skills;
@@ -329,8 +329,8 @@ function labelDirectory(directory: string, home: string): string {
   return directory.split(path.sep).join("/");
 }
 
-function hashBody(body: string): string {
-  return createHash("sha256").update(body).digest("hex").slice(0, 16);
+function hashContent(content: string): string {
+  return createHash("sha256").update(content).digest("hex").slice(0, 16);
 }
 
 function getErrorCode(error: unknown): string {

package/src/index.ts

@@ -10,7 +10,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { DEFAULT_RULE_SOURCES, discoverRules, loadRuleConfig, type RuleSource } from "./discovery.ts";
 import { extractTarget, ruleAppliesToTarget, ruleMatchesToolCallEvent, targetLabel } from "./matching.ts";
 import { addInjection, collectInjectedState, CUSTOM_MESSAGE_TYPE, type InjectedState } from "./state.ts";
-import type { PendingRule, Rule, RuleInjectionDetails } from "./types.ts";
+import type { DueRule, PendingRule, RemovedRule, Rule, RuleInjectionDetails } from "./types.ts";
 
 export { CUSTOM_MESSAGE_TYPE };
 
@@ -38,9 +38,19 @@ export function makeExtension() {
 
     pi.registerMessageRenderer<RuleInjectionDetails>(CUSTOM_MESSAGE_TYPE, (message, { expanded }, theme) => {
       const details = message.details;
-      const sourceLines = (details?.sources ?? ["(unknown)"]).map((source) => `↳ ${source}`).join("\n");
+      const updated = new Set(details?.updated ?? []);
+      const sourceLines = (details?.sources ?? ["(unknown)"])
+        .map((source) => `↳ ${source}${updated.has(source) ? " (updated)" : ""}`)
+        .join("\n");
       const skillLines = (details?.skills ?? []).map((skill) => `↳ ${skill}`).join("\n");
-      const summary = `Loaded rules:\n${sourceLines}${skillLines ? `\nLoaded skills:\n${skillLines}` : ""}`;
+      const removedLines = (details?.removed ?? []).map((rule) => `↳ ${rule.label}`).join("\n");
+      const summary = [
+        sourceLines ? `Loaded rules:\n${sourceLines}` : "",
+        skillLines ? `Loaded skills:\n${skillLines}` : "",
+        removedLines ? `Removed rules:\n${removedLines}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n");
       if (!expanded) {
         return new Text(theme.fg("muted", summary), 0, 0);
       }
@@ -48,15 +58,12 @@ export function makeExtension() {
       const targetLines = details?.sources
         .map((source) => {
           const targets = details.targets[source] ?? [];
-          return targets.length > 0 ? `${source} → ${targets.join(", ")}` : `${source} → unconditional`;
+          if (targets.length > 0) return `${source} → ${targets.join(", ")}`;
+          return `${source} → ${updated.has(source) ? "updated" : "unconditional"}`;
         })
         .join("\n");
       const content = typeof message.content === "string" ? message.content : JSON.stringify(message.content, null, 2);
-      return new Text(
-        `${theme.fg("accent", "Loaded rules:")}\n${theme.fg("muted", sourceLines)}\n\n${theme.fg("dim", targetLines ?? "")}\n\n${content}`,
-        0,
-        0,
-      );
+      return new Text(`${theme.fg("accent", summary)}\n\n${theme.fg("dim", targetLines ?? "")}\n\n${content}`, 0, 0);
     });
 
     const reloadConfig = async (cwd: string): Promise<void> => {
@@ -95,20 +102,42 @@ export function makeExtension() {
       return withInFlight(cachedBranch.state);
     };
 
-    // Takes the matches of this turn and adds every unconditional rule that the model does not have.
-    const takeDueRules = (state: InjectedState): PendingRule[] => {
-      const due = [...pendingRules.values()].filter((entry) => !state.rules.has(entry.rule.id));
+    /**
+     * Takes the matches of this turn, and adds every unconditional rule that the model does not have,
+     * every rule whose file changed after the model got it, and every rule whose file is gone.
+     */
+    const takeDueRules = (state: InjectedState): { due: DueRule[]; removed: RemovedRule[] } => {
+      // A rule file can change between the tool call and the end of the turn, so take the newest version.
+      const current = new Map(rules.map((rule) => [rule.id, rule]));
+      const due: DueRule[] = [];
+      for (const entry of pendingRules.values()) {
+        const rule = current.get(entry.rule.id);
+        if (rule && !state.rules.has(rule.id)) due.push({ rule, targets: entry.targets, updated: false });
+      }
       pendingRules.clear();
       for (const rule of rules) {
-        if (isScoped(rule) || state.rules.has(rule.id)) continue;
-        if (!due.some((entry) => entry.rule.id === rule.id)) due.push({ rule, targets: new Set<string>() });
+        if (due.some((entry) => entry.rule.id === rule.id)) continue;
+        const known = state.rules.get(rule.id);
+        if (known) {
+          if (known.hash !== rule.hash) due.push({ rule, targets: new Set<string>(), updated: true });
+        } else if (!isScoped(rule)) {
+          due.push({ rule, targets: new Set<string>(), updated: false });
+        }
       }
-      return due;
+      const discovered = new Set(rules.map((rule) => rule.id));
+      const removed = [...state.rules]
+        .filter(([id]) => !discovered.has(id))
+        .map(([id, known]) => ({ id, label: known.label }));
+      return { due, removed };
     };
 
-    const buildInjection = async (entries: PendingRule[], state: InjectedState): Promise<RuleInjection> => {
-      const skillBlocks = await loadSkillBlocks(entries, availableSkills, state.skills, reportWarning);
-      return createInjection(entries, skillBlocks);
+    const buildInjection = async (
+      { due, removed }: { due: DueRule[]; removed: RemovedRule[] },
+      state: InjectedState,
+    ): Promise<RuleInjection | undefined> => {
+      if (due.length === 0 && removed.length === 0) return undefined;
+      const skillBlocks = await loadSkillBlocks(due, availableSkills, state.skills, reportWarning);
+      return createInjection(due, skillBlocks, removed);
     };
 
     pi.on("session_start", async (_event, ctx) => {
@@ -133,9 +162,9 @@ export function makeExtension() {
       if (!config.enabled) return;
       rules = await reloadRules(ctx.cwd);
       const state = branchState(ctx);
-      const due = takeDueRules(state);
-      if (due.length === 0) return;
-      return { message: await buildInjection(due, state) };
+      const injection = await buildInjection(takeDueRules(state), state);
+      if (!injection) return;
+      return { message: injection };
     });
 
     pi.on("tool_call", async (event, ctx) => {
@@ -173,9 +202,8 @@ export function makeExtension() {
       rules = await reloadRules(ctx.cwd);
       // The preview already holds the entries that earlier handlers proposed for this boundary.
       const state = withInFlight(collectInjectedState(event.context.contextEntries, event.context.pendingMessages));
-      const due = takeDueRules(state);
-      if (due.length === 0) return;
-      const injection = await buildInjection(due, state);
+      const injection = await buildInjection(takeDueRules(state), state);
+      if (!injection) return;
       return { entries: [...event.entries, { type: "custom_message", ...injection }] };
     });
 
@@ -189,9 +217,8 @@ export function makeExtension() {
       rules = await reloadRules(ctx.cwd);
       // A compaction that retries the turn makes a model call before any turn boundary, so restore the rules now.
       const state = branchState(ctx);
-      const due = takeDueRules(state);
-      if (due.length === 0) return;
-      const injection = await buildInjection(due, state);
+      const injection = await buildInjection(takeDueRules(state), state);
+      if (!injection) return;
       inFlight.set(injection.details.injectionId, injection.details);
       pi.sendMessage(injection);
     });
@@ -208,23 +235,34 @@ interface SkillBlock {
   content: string;
 }
 
-export function createInjection(entries: PendingRule[], skillBlocks: SkillBlock[] = []): RuleInjection {
+export function createInjection(
+  entries: Array<PendingRule & { updated?: boolean }>,
+  skillBlocks: SkillBlock[] = [],
+  removed: RemovedRule[] = [],
+): RuleInjection {
   const sorted = [...entries].sort(comparePendingRules);
   const sources = sorted.map((entry) => entry.rule.sourceLabel);
   const targets = Object.fromEntries(sorted.map((entry) => [entry.rule.sourceLabel, [...entry.targets].sort()]));
-  const ruleBody = sorted
-    .map((entry) => `## Rule: ${entry.rule.sourceLabel}\n\n${entry.rule.body}`)
-    .join("\n\n---\n\n");
-  const skillBody = skillBlocks.map((skill) => skill.content).join("\n\n");
+  const blocks = [
+    ...sorted.map((entry) =>
+      entry.updated
+        ? `## Rule: ${entry.rule.sourceLabel} (updated)\n\nThis version replaces the earlier version of this rule.\n\n${entry.rule.body}`
+        : `## Rule: ${entry.rule.sourceLabel}\n\n${entry.rule.body}`,
+    ),
+    ...removed.map((rule) => `## Rule removed: ${rule.label}\n\nThis rule no longer applies. Stop following its earlier version.`),
+    ...skillBlocks.map((skill) => skill.content),
+  ];
 
   return {
     customType: CUSTOM_MESSAGE_TYPE,
-    content: skillBody ? `${ruleBody}\n\n---\n\n${skillBody}` : ruleBody,
+    content: blocks.join("\n\n---\n\n"),
     display: true,
     details: {
       injectionId: randomUUID(),
-      rules: sorted.map((entry) => ({ id: entry.rule.id, hash: entry.rule.hash })),
+      rules: sorted.map((entry) => ({ id: entry.rule.id, hash: entry.rule.hash, label: entry.rule.sourceLabel })),
+      removed,
       sources,
+      updated: sorted.filter((entry) => entry.updated).map((entry) => entry.rule.sourceLabel),
       targets,
       skills: skillBlocks.map((skill) => skill.name),
     },

package/src/state.ts

@@ -1,12 +1,11 @@
 import type { ProjectedSessionEntry } from "@earendil-works/pi-coding-agent";
-import type { RuleInjectionDetails } from "./types.ts";
 
 export const CUSTOM_MESSAGE_TYPE = "pi-rules-injection";
 
 /** The rules and skills that the model can see now, read from the injection messages in its context. */
 export interface InjectedState {
-  /** Rule id to the hash of the body that the model has. */
-  rules: Map<string, string>;
+  /** Rule id to the version of the rule that the model has. */
+  rules: Map<string, { hash: string; label: string }>;
   skills: Set<string>;
   injectionIds: Set<string>;
 }
@@ -42,7 +41,11 @@ export function collectInjectedState(
 export function addInjection(state: InjectedState, details: unknown): void {
   if (!isInjectionDetails(details)) return;
   state.injectionIds.add(details.injectionId);
-  for (const rule of details.rules) state.rules.set(rule.id, rule.hash);
+  details.rules.forEach((rule, index) => {
+    // 0.7 and 0.8 stored the label only in `sources`, in the same order as `rules`.
+    state.rules.set(rule.id, { hash: rule.hash, label: rule.label ?? details.sources[index] ?? rule.id });
+  });
+  for (const rule of details.removed ?? []) state.rules.delete(rule.id);
   for (const skill of details.skills) state.skills.add(skill);
 }
 
@@ -57,13 +60,24 @@ function isInjectionMessage(message: unknown): message is { details: unknown } {
 }
 
 // Injections written by older versions have no rule list. They are ignored, so those rules load once more.
-function isInjectionDetails(details: unknown): details is RuleInjectionDetails {
+interface StoredInjectionDetails {
+  injectionId: string;
+  rules: Array<{ id: string; hash: string; label?: string }>;
+  removed?: Array<{ id: string }>;
+  sources: string[];
+  skills: string[];
+}
+
+function isInjectionDetails(details: unknown): details is StoredInjectionDetails {
   if (typeof details !== "object" || details === null) return false;
-  const candidate = details as Partial<RuleInjectionDetails>;
+  const candidate = details as Partial<StoredInjectionDetails>;
   return (
     typeof candidate.injectionId === "string" &&
     Array.isArray(candidate.rules) &&
     candidate.rules.every((rule) => typeof rule?.id === "string" && typeof rule.hash === "string") &&
+    (candidate.removed === undefined ||
+      (Array.isArray(candidate.removed) && candidate.removed.every((rule) => typeof rule?.id === "string"))) &&
+    Array.isArray(candidate.sources) &&
     Array.isArray(candidate.skills)
   );
 }

package/src/types.ts

@@ -13,7 +13,7 @@ export interface Rule {
   sourceLabel: string;
   scope: RuleScope;
   body: string;
-  /** Hash of the body, so a changed rule file can be told apart from the copy the model already has. */
+  /** Hash of the whole file, so a changed rule can be told apart from the version that the model has. */
   hash: string;
   paths?: string[];
   events?: RuleEvents;
@@ -33,16 +33,31 @@ export interface DiscoveryResult {
 export interface InjectedRule {
   id: string;
   hash: string;
+  label: string;
+}
+
+export interface RemovedRule {
+  id: string;
+  label: string;
 }
 
 export interface RuleInjectionDetails {
   injectionId: string;
+  /** Rules that this message loads, also new versions of rules that the model has. */
   rules: InjectedRule[];
+  /** Rules whose file is gone. The message tells the model to stop following them. */
+  removed: RemovedRule[];
   sources: string[];
+  /** The labels in `sources` that replace an earlier version. */
+  updated: string[];
   targets: Record<string, string[]>;
   skills: string[];
 }
 
+export interface DueRule extends PendingRule {
+  updated: boolean;
+}
+
 export interface PendingRule {
   rule: Rule;
   targets: Set<string>;