@oh-my-pi/pi-coding-agent 3.3.1337 → 3.5.1337

package/src/core/tools/index.ts

@@ -24,6 +24,12 @@ export { createNotebookTool, type NotebookToolDetails, notebookTool } from "./no
 export { createOutputTool, type OutputToolDetails, outputTool } from "./output";
 export { createReadTool, type ReadToolDetails, readTool } from "./read";
 export { createReportFindingTool, createSubmitReviewTool, reportFindingTool, submitReviewTool } from "./review";
+export {
+	createRulebookTool,
+	filterRulebookRules,
+	formatRulesForPrompt,
+	type RulebookToolDetails,
+} from "./rulebook";
 export { BUNDLED_AGENTS, createTaskTool, taskTool } from "./task/index";
 export type { TruncationResult } from "./truncate";
 export { createWebFetchTool, type WebFetchToolDetails, webFetchCustomTool, webFetchTool } from "./web-fetch";

package/src/core/tools/rulebook.ts

@@ -0,0 +1,124 @@
+/**
+ * Rulebook Tool
+ *
+ * Allows the agent to fetch full content of rules that have descriptions.
+ * Rules are listed in the system prompt with name + description; this tool
+ * retrieves the complete rule content on demand.
+ */
+
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { Type } from "@sinclair/typebox";
+import type { Rule } from "../../capability/rule";
+
+export interface RulebookToolDetails {
+	type: "rulebook";
+	ruleName: string;
+	found: boolean;
+	content?: string;
+}
+
+const rulebookSchema = Type.Object({
+	name: Type.String({ description: "The name of the rule to fetch" }),
+});
+
+/**
+ * Create a rulebook tool with access to discovered rules.
+ * @param rules - Array of discovered rules (non-TTSR rules with descriptions)
+ */
+export function createRulebookTool(rules: Rule[]): AgentTool<typeof rulebookSchema> {
+	// Build lookup map for O(1) access
+	const ruleMap = new Map<string, Rule>();
+	for (const rule of rules) {
+		ruleMap.set(rule.name, rule);
+	}
+
+	const ruleNames = rules.map((r) => r.name);
+
+	return {
+		name: "rulebook",
+		label: "Rulebook",
+		description: `Fetch the full content of a project rule by name. Use this when a rule listed in <available_rules> is relevant to your current task. Available: ${ruleNames.join(", ") || "(none)"}`,
+		parameters: rulebookSchema,
+		execute: async (_toolCallId: string, { name }: { name: string }) => {
+			const rule = ruleMap.get(name);
+
+			if (!rule) {
+				const available = ruleNames.join(", ");
+				return {
+					content: [{ type: "text", text: `Rule "${name}" not found. Available rules: ${available || "(none)"}` }],
+					details: {
+						type: "rulebook",
+						ruleName: name,
+						found: false,
+					} satisfies RulebookToolDetails,
+				};
+			}
+
+			return {
+				content: [{ type: "text", text: `# Rule: ${rule.name}\n\n${rule.content}` }],
+				details: {
+					type: "rulebook",
+					ruleName: name,
+					found: true,
+					content: rule.content,
+				} satisfies RulebookToolDetails,
+			};
+		},
+	};
+}
+
+/**
+ * Filter rules to only those suitable for the rulebook (have descriptions, no TTSR trigger).
+ */
+export function filterRulebookRules(rules: Rule[]): Rule[] {
+	return rules.filter((rule) => {
+		// Exclude TTSR rules (handled separately by streaming)
+		if (rule.ttsrTrigger) return false;
+		// Exclude always-apply rules (already in context)
+		if (rule.alwaysApply) return false;
+		// Must have a description for agent to know when to fetch
+		if (!rule.description) return false;
+		return true;
+	});
+}
+
+/**
+ * Format rules for inclusion in the system prompt.
+ * Lists rule names and descriptions so the agent knows what's available.
+ */
+export function formatRulesForPrompt(rules: Rule[]): string {
+	if (rules.length === 0) {
+		return "";
+	}
+
+	const lines = [
+		"\n\n## Available Rules",
+		"",
+		"The following project rules are available. Use the `rulebook` tool to fetch a rule's full content when it's relevant to your task.",
+		"",
+		"<available_rules>",
+	];
+
+	for (const rule of rules) {
+		lines.push("  <rule>");
+		lines.push(`    <name>${escapeXml(rule.name)}</name>`);
+		lines.push(`    <description>${escapeXml(rule.description || "")}</description>`);
+		if (rule.globs && rule.globs.length > 0) {
+			lines.push(`    <globs>${escapeXml(rule.globs.join(", "))}</globs>`);
+		}
+		lines.push("  </rule>");
+	}
+
+	lines.push("</available_rules>");
+
+	return lines.join("\n");
+}
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}

package/src/core/ttsr.ts

@@ -0,0 +1,211 @@
+/**
+ * Time Traveling Stream Rules (TTSR) Manager
+ *
+ * Manages rules that get injected mid-stream when their trigger pattern matches
+ * the agent's output. When a match occurs, the stream is aborted, the rule is
+ * injected as a system reminder, and the request is retried.
+ */
+
+import type { Rule } from "../capability/rule";
+import { logger } from "./logger";
+import type { TtsrSettings } from "./settings-manager";
+
+interface TtsrEntry {
+	rule: Rule;
+	regex: RegExp;
+}
+
+/** Tracks when a rule was last injected (for repeat-after-gap mode) */
+interface InjectionRecord {
+	/** Message count when the rule was last injected */
+	lastInjectedAt: number;
+}
+
+export interface TtsrManager {
+	/** Add a TTSR rule to be monitored */
+	addRule(rule: Rule): void;
+
+	/** Check if any uninjected TTSR matches the stream buffer. Returns matching rules. */
+	check(streamBuffer: string): Rule[];
+
+	/** Mark rules as injected (won't trigger again until conditions allow) */
+	markInjected(rules: Rule[]): void;
+
+	/** Get names of all injected rules (for persistence) */
+	getInjectedRuleNames(): string[];
+
+	/** Restore injected state from a list of rule names */
+	restoreInjected(ruleNames: string[]): void;
+
+	/** Reset stream buffer (called on new turn) */
+	resetBuffer(): void;
+
+	/** Get current stream buffer */
+	getBuffer(): string;
+
+	/** Append to stream buffer */
+	appendToBuffer(text: string): void;
+
+	/** Check if any TTSRs are registered */
+	hasRules(): boolean;
+
+	/** Increment message counter (call after each turn) */
+	incrementMessageCount(): void;
+
+	/** Get current message count */
+	getMessageCount(): number;
+
+	/** Get settings */
+	getSettings(): Required<TtsrSettings>;
+}
+
+const DEFAULT_SETTINGS: Required<TtsrSettings> = {
+	enabled: true,
+	contextMode: "discard",
+	repeatMode: "once",
+	repeatGap: 10,
+};
+
+export function createTtsrManager(settings?: TtsrSettings): TtsrManager {
+	/** Resolved settings with defaults */
+	const resolvedSettings: Required<TtsrSettings> = {
+		...DEFAULT_SETTINGS,
+		...settings,
+	};
+
+	/** Map of rule name -> { rule, compiled regex } */
+	const rules = new Map<string, TtsrEntry>();
+
+	/** Map of rule name -> injection record */
+	const injectionRecords = new Map<string, InjectionRecord>();
+
+	/** Current stream buffer for pattern matching */
+	let buffer = "";
+
+	/** Message counter for tracking gap between injections */
+	let messageCount = 0;
+
+	/** Check if a rule can be triggered based on repeat settings */
+	function canTrigger(ruleName: string): boolean {
+		const record = injectionRecords.get(ruleName);
+		if (!record) {
+			// Never injected, can trigger
+			return true;
+		}
+
+		if (resolvedSettings.repeatMode === "once") {
+			// Once mode: never trigger again after first injection
+			return false;
+		}
+
+		// After-gap mode: check if enough messages have passed
+		const gap = messageCount - record.lastInjectedAt;
+		return gap >= resolvedSettings.repeatGap;
+	}
+
+	return {
+		addRule(rule: Rule): void {
+			// Only add rules that have a TTSR trigger pattern
+			if (!rule.ttsrTrigger) {
+				return;
+			}
+
+			// Skip if already registered
+			if (rules.has(rule.name)) {
+				return;
+			}
+
+			// Compile the regex pattern
+			try {
+				const regex = new RegExp(rule.ttsrTrigger);
+				rules.set(rule.name, { rule, regex });
+				logger.debug("TTSR rule registered", {
+					ruleName: rule.name,
+					pattern: rule.ttsrTrigger,
+				});
+			} catch (err) {
+				logger.warn("TTSR rule has invalid regex pattern, skipping", {
+					ruleName: rule.name,
+					pattern: rule.ttsrTrigger,
+					error: err instanceof Error ? err.message : String(err),
+				});
+			}
+		},
+
+		check(streamBuffer: string): Rule[] {
+			const matches: Rule[] = [];
+
+			for (const [name, entry] of rules) {
+				// Skip rules that can't trigger yet
+				if (!canTrigger(name)) {
+					continue;
+				}
+
+				// Test the buffer against the rule's pattern
+				if (entry.regex.test(streamBuffer)) {
+					matches.push(entry.rule);
+					logger.debug("TTSR pattern matched", {
+						ruleName: name,
+						pattern: entry.rule.ttsrTrigger,
+					});
+				}
+			}
+
+			return matches;
+		},
+
+		markInjected(rulesToMark: Rule[]): void {
+			for (const rule of rulesToMark) {
+				injectionRecords.set(rule.name, { lastInjectedAt: messageCount });
+				logger.debug("TTSR rule marked as injected", {
+					ruleName: rule.name,
+					messageCount,
+					repeatMode: resolvedSettings.repeatMode,
+				});
+			}
+		},
+
+		getInjectedRuleNames(): string[] {
+			return Array.from(injectionRecords.keys());
+		},
+
+		restoreInjected(ruleNames: string[]): void {
+			// When restoring, we don't know the original message count, so use 0
+			// This means in "after-gap" mode, rules can trigger again after the gap
+			for (const name of ruleNames) {
+				injectionRecords.set(name, { lastInjectedAt: 0 });
+			}
+			if (ruleNames.length > 0) {
+				logger.debug("TTSR injected state restored", { ruleNames });
+			}
+		},
+
+		resetBuffer(): void {
+			buffer = "";
+		},
+
+		getBuffer(): string {
+			return buffer;
+		},
+
+		appendToBuffer(text: string): void {
+			buffer += text;
+		},
+
+		hasRules(): boolean {
+			return rules.size > 0;
+		},
+
+		incrementMessageCount(): void {
+			messageCount++;
+		},
+
+		getMessageCount(): number {
+			return messageCount;
+		},
+
+		getSettings(): Required<TtsrSettings> {
+			return resolvedSettings;
+		},
+	};
+}

package/src/discovery/builtin.ts

@@ -310,6 +310,7 @@ function loadRules(ctx: LoadContext): LoadResult<Rule> {
 					globs: frontmatter.globs as string[] | undefined,
 					alwaysApply: frontmatter.alwaysApply as boolean | undefined,
 					description: frontmatter.description as string | undefined,
+					ttsrTrigger: typeof frontmatter.ttsr_trigger === "string" ? frontmatter.ttsr_trigger : undefined,
 					_source: source,
 				};
 			},

package/src/discovery/cline.ts

@@ -52,6 +52,7 @@ function loadRules(ctx: LoadContext): LoadResult<Rule> {
 					globs,
 					alwaysApply: typeof frontmatter.alwaysApply === "boolean" ? frontmatter.alwaysApply : undefined,
 					description: typeof frontmatter.description === "string" ? frontmatter.description : undefined,
+					ttsrTrigger: typeof frontmatter.ttsr_trigger === "string" ? frontmatter.ttsr_trigger : undefined,
 					_source: source,
 				};
 			},
@@ -85,6 +86,7 @@ function loadRules(ctx: LoadContext): LoadResult<Rule> {
 			globs,
 			alwaysApply: typeof frontmatter.alwaysApply === "boolean" ? frontmatter.alwaysApply : undefined,
 			description: typeof frontmatter.description === "string" ? frontmatter.description : undefined,
+			ttsrTrigger: typeof frontmatter.ttsr_trigger === "string" ? frontmatter.ttsr_trigger : undefined,
 			_source: source,
 		});
 	}

package/src/discovery/cursor.ts

@@ -163,6 +163,7 @@ function transformMDCRule(
 	// Extract frontmatter fields
 	const description = typeof frontmatter.description === "string" ? frontmatter.description : undefined;
 	const alwaysApply = frontmatter.alwaysApply === true;
+	const ttsrTrigger = typeof frontmatter.ttsr_trigger === "string" ? frontmatter.ttsr_trigger : undefined;
 
 	// Parse globs (can be array or single string)
 	let globs: string[] | undefined;
@@ -182,6 +183,7 @@ function transformMDCRule(
 		description,
 		alwaysApply,
 		globs,
+		ttsrTrigger,
 		_source: source,
 	};
 }

package/src/discovery/windsurf.ts

@@ -128,6 +128,7 @@ function loadRules(ctx: LoadContext): LoadResult<Rule> {
 				globs,
 				alwaysApply: frontmatter.alwaysApply as boolean | undefined,
 				description: frontmatter.description as string | undefined,
+				ttsrTrigger: typeof frontmatter.ttsr_trigger === "string" ? frontmatter.ttsr_trigger : undefined,
 				_source: createSourceMeta(PROVIDER_ID, userPath, "user"),
 			});
 		}
@@ -157,6 +158,7 @@ function loadRules(ctx: LoadContext): LoadResult<Rule> {
 					globs,
 					alwaysApply: frontmatter.alwaysApply as boolean | undefined,
 					description: frontmatter.description as string | undefined,
+					ttsrTrigger: typeof frontmatter.ttsr_trigger === "string" ? frontmatter.ttsr_trigger : undefined,
 					_source: source,
 				};
 			},
@@ -187,6 +189,7 @@ function loadRules(ctx: LoadContext): LoadResult<Rule> {
 				globs,
 				alwaysApply: frontmatter.alwaysApply as boolean | undefined,
 				description: frontmatter.description as string | undefined,
+				ttsrTrigger: typeof frontmatter.ttsr_trigger === "string" ? frontmatter.ttsr_trigger : undefined,
 				_source: createSourceMeta(PROVIDER_ID, legacyPath, "project"),
 			});
 		}