@oh-my-pi/pi-coding-agent 0.1.0

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/core/utils.ts

@@ -0,0 +1,187 @@
+// Utility constant for representing aborted operations
+const kAbortError = new Error("Operation aborted");
+
+/**
+ * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
+ * execution, the promise is rejected with a standard error.
+ *
+ * @param signal - Optional AbortSignal to cancel the operation
+ * @param pr - Function returning a promise to run
+ * @returns Promise resolving as `pr` would, or rejecting on abort
+ */
+export function untilAborted<T>(signal: AbortSignal | undefined | null, pr: () => Promise<T>): Promise<T> {
+	if (!signal) {
+		return pr();
+	}
+
+	if (signal.aborted) {
+		return Promise.reject(kAbortError);
+	}
+
+	return new Promise((resolve, reject) => {
+		const listener = () => reject(kAbortError);
+		signal.addEventListener("abort", listener, { once: true });
+
+		signal.throwIfAborted();
+
+		pr()
+			.then(resolve, reject)
+			.finally(() => {
+				signal.removeEventListener("abort", listener);
+			});
+	});
+}
+
+/**
+ * Memoizes a function with no arguments, calling it once and caching the result.
+ *
+ * @param fn - Function to be called once
+ * @returns A function that returns the cached result of `fn`
+ */
+export function once<T>(fn: () => T): () => T {
+	let store = undefined as { value: T } | undefined;
+	return () => {
+		if (store) {
+			return store.value;
+		}
+		const value = fn();
+		store = { value };
+		return value;
+	};
+}
+
+// ScopeSignal is a cancellation/helper utility similar to AbortController but
+// allows composition of an existing AbortSignal and/or a timeout. It exposes a
+// simple API for cancellation observation (finally, catch).
+interface ScopeSignalOptions {
+	signal?: AbortSignal;
+	timeout?: number;
+}
+
+const kTimeoutReason = new Error("Timeout");
+const kDisposedReason = new Error("Disposed");
+
+/**
+ * Type of signal exit (None = disposed, TimedOut = timed out, Aborted = underlying signal aborted)
+ */
+enum ExitReason {
+	None = 0,
+	TimedOut = 1,
+	Aborted = 2,
+}
+
+/**
+ * ScopeSignal: composable cancellation for async work–observes an external AbortSignal and/or a timeout.
+ *
+ * Use .finally(fn) to register a one-time callback invoked on *any* exit (abort, timeout, or manual dispose).
+ * Use .catch(fn) to register a one-time callback invoked only on abort/timeout.
+ *
+ * Disposing ScopeSignal disables further callbacks.
+ */
+export class ScopeSignal implements Disposable {
+	#signal: AbortSignal | undefined;
+	#timer: NodeJS.Timeout | undefined;
+	#exit = undefined as ExitReason | undefined;
+	#onAbort: (() => void) | undefined;
+	#callbacks?: (() => void)[];
+	#reason: unknown | undefined;
+
+	/**
+	 * Provides abort/timeout reason (Error or user-defined).
+	 */
+	get reason(): unknown | undefined {
+		return this.#reason;
+	}
+
+	/**
+	 * True if exited due to external AbortSignal or timeout.
+	 */
+	get aborted(): boolean {
+		return this.#exit !== undefined && this.#exit > ExitReason.None;
+	}
+
+	/**
+	 * True if this ScopeSignal timed out (not external abort).
+	 */
+	timedOut(): boolean {
+		return this.#exit === ExitReason.TimedOut;
+	}
+
+	/**
+	 * Create a new ScopeSignal, optionally observing an AbortSignal and/or auto-aborting after a timeout (ms).
+	 */
+	constructor(options?: ScopeSignalOptions) {
+		const { signal, timeout } = options ?? {};
+
+		if (signal?.aborted) {
+			this.#abort(ExitReason.Aborted, signal.reason); // Immediately abort if already-aborted
+			return;
+		}
+		if (timeout && timeout <= 0) {
+			this.#abort(ExitReason.TimedOut, kTimeoutReason);
+			return;
+		}
+
+		// Observe external signal if provided
+		if (signal) {
+			const onAbort = () => {
+				this.#abort(ExitReason.Aborted, signal.reason);
+			};
+			this.#signal = signal;
+			this.#onAbort = onAbort;
+			this.#signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		// Set up timeout if provided
+		if (timeout) {
+			this.#timer = setTimeout(() => {
+				this.#abort(ExitReason.TimedOut, kTimeoutReason);
+			}, timeout);
+		}
+	}
+
+	/**
+	 * Register a one-time callback invoked on any exit (abort, timeout, or manual dispose).
+	 * Runs immediately if already exited.
+	 */
+	finally(onfinally: () => void): void {
+		if (this.#exit !== undefined) {
+			onfinally();
+			return;
+		}
+		this.#callbacks ??= [];
+		this.#callbacks.push(onfinally);
+	}
+
+	/**
+	 * Register a one-time callback invoked only if exited due to abort/timeout (not normal disposal).
+	 */
+	catch(oncatch: (reason: unknown) => void): void {
+		this.finally(() => {
+			if (this.aborted) {
+				oncatch(this.reason);
+			}
+		});
+	}
+
+	/** Internal: cause exit; only first call takes effect. */
+	#abort(exit: ExitReason, reason?: unknown): void {
+		if (this.#exit !== undefined) return;
+		this.#reason = reason;
+		clearTimeout(this.#timer);
+		this.#signal?.removeEventListener("abort", this.#onAbort!);
+
+		this.#exit = exit;
+
+		const callbacks = this.#callbacks;
+		this.#callbacks = undefined;
+		callbacks?.forEach((fn) => void fn());
+	}
+
+	/**
+	 * Dispose: marks as normally exited (not abort/timeout); disables further callback registration.
+	 */
+	[Symbol.dispose](): void {
+		this.#abort(ExitReason.None, kDisposedReason);
+	}
+}

package/src/discovery/agents-md.ts

@@ -0,0 +1,75 @@
+/**
+ * AGENTS.md Provider
+ *
+ * Discovers standalone AGENTS.md files by walking up from cwd.
+ * This handles AGENTS.md files that live in project root (not in config directories
+ * like .codex/ or .gemini/, which are handled by their respective providers).
+ */
+
+import { dirname, join, sep } from "node:path";
+import { type ContextFile, contextFileCapability } from "../capability/context-file";
+import { registerProvider } from "../capability/index";
+import type { LoadContext, LoadResult } from "../capability/types";
+import { calculateDepth, createSourceMeta } from "./helpers";
+
+const PROVIDER_ID = "agents-md";
+const DISPLAY_NAME = "AGENTS.md";
+const MAX_DEPTH = 20; // Prevent walking up excessively far from cwd
+
+/**
+ * Load standalone AGENTS.md files.
+ */
+function loadAgentsMd(ctx: LoadContext): LoadResult<ContextFile> {
+	const items: ContextFile[] = [];
+	const warnings: string[] = [];
+
+	// Walk up from cwd looking for AGENTS.md files
+	let current = ctx.cwd;
+	let depth = 0;
+
+	while (depth < MAX_DEPTH) {
+		const candidate = join(current, "AGENTS.md");
+
+		if (ctx.fs.isFile(candidate)) {
+			// Skip if it's inside a config directory (handled by other providers)
+			const parent = dirname(candidate);
+			const baseName = parent.split(sep).pop() ?? "";
+
+			// Skip if inside .codex, .gemini, or other config dirs
+			if (!baseName.startsWith(".")) {
+				const content = ctx.fs.readFile(candidate);
+
+				if (content === null) {
+					warnings.push(`Failed to read: ${candidate}`);
+				} else {
+					const fileDir = dirname(candidate);
+					const calculatedDepth = calculateDepth(ctx.cwd, fileDir, sep);
+
+					items.push({
+						path: candidate,
+						content,
+						level: "project",
+						depth: calculatedDepth,
+						_source: createSourceMeta(PROVIDER_ID, candidate, "project"),
+					});
+				}
+			}
+		}
+
+		// Move to parent directory
+		const parent = dirname(current);
+		if (parent === current) break; // Reached filesystem root
+		current = parent;
+		depth++;
+	}
+
+	return { items, warnings };
+}
+
+registerProvider(contextFileCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Standalone AGENTS.md files (Codex/Gemini style)",
+	priority: 10,
+	load: loadAgentsMd,
+});