@oh-my-pi/pi-coding-agent 12.8.2 → 12.10.0

package/src/export/ttsr.ts

@@ -1,7 +1,7 @@
 /**
  * Time Traveling Stream Rules (TTSR) Manager
  *
- * Manages rules that get injected mid-stream when their trigger pattern matches
+ * Manages rules that get injected mid-stream when their condition 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.
  */
@@ -9,36 +9,72 @@ import { logger } from "@oh-my-pi/pi-utils";
 import type { Rule } from "../capability/rule";
 import type { TtsrSettings } from "../config/settings";
 
+export type TtsrMatchSource = "text" | "thinking" | "tool";
+
+/** Context about the stream content currently being checked against TTSR rules. */
+export interface TtsrMatchContext {
+	source: TtsrMatchSource;
+	/** Tool name for tool argument deltas, e.g. "edit" or "write". */
+	toolName?: string;
+	/** Candidate file paths associated with the current stream chunk. */
+	filePaths?: string[];
+	/** Stable key to isolate buffering (for example a tool call ID). */
+	streamKey?: string;
+}
+
+interface ToolScope {
+	toolName?: string;
+	pathGlob?: Bun.Glob;
+	pathPattern?: string;
+}
+
+interface TtsrScope {
+	allowText: boolean;
+	allowThinking: boolean;
+	allowAnyTool: boolean;
+	toolScopes: ToolScope[];
+}
+
 interface TtsrEntry {
 	rule: Rule;
-	regex: RegExp;
+	conditions: RegExp[];
+	scope: TtsrScope;
+	globalPathGlobs?: Bun.Glob[];
 }
 
-/** Tracks when a rule was last injected (for repeat-after-gap mode) */
+/** Tracks when a rule was last injected (for repeat gating). */
 interface InjectionRecord {
-	/** Message count when the rule was last injected */
+	/** Message count (turn index) when the rule was last injected. */
 	lastInjectedAt: number;
 }
 
 const DEFAULT_SETTINGS: Required<TtsrSettings> = {
 	enabled: true,
 	contextMode: "discard",
+	interruptMode: "always",
 	repeatMode: "once",
 	repeatGap: 10,
 };
 
+const DEFAULT_SCOPE: TtsrScope = {
+	allowText: true,
+	allowThinking: false,
+	allowAnyTool: true,
+	toolScopes: [],
+};
+
 export class TtsrManager {
 	readonly #settings: Required<TtsrSettings>;
 	readonly #rules = new Map<string, TtsrEntry>();
 	readonly #injectionRecords = new Map<string, InjectionRecord>();
-	#buffer = "";
+	readonly #buffers = new Map<string, string>();
 	#messageCount = 0;
 
 	constructor(settings?: TtsrSettings) {
 		this.#settings = { ...DEFAULT_SETTINGS, ...settings };
 	}
 
-	/** Check if a rule can be triggered based on repeat settings */
+	/** Check if a rule can be triggered based on repeat settings. */
 	#canTrigger(ruleName: string): boolean {
 		const record = this.#injectionRecords.get(ruleName);
 		if (!record) {
@@ -53,71 +89,315 @@ export class TtsrManager {
 		return gap >= this.#settings.repeatGap;
 	}
 
-	/** Add a TTSR rule to be monitored */
-	addRule(rule: Rule): void {
-		if (!rule.ttsrTrigger) {
-			return;
+	#compileConditions(rule: Rule): RegExp[] {
+		const compiled: RegExp[] = [];
+		for (const pattern of rule.condition ?? []) {
+			try {
+				compiled.push(new RegExp(pattern));
+			} catch (error) {
+				logger.warn("TTSR condition has invalid regex pattern, skipping condition", {
+					ruleName: rule.name,
+					pattern,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		}
+
+		return compiled;
+	}
+
+	#compileGlobalPathGlobs(globs: Rule["globs"]): Bun.Glob[] | undefined {
+		if (!globs || globs.length === 0) {
+			return undefined;
+		}
+
+		const compiled = globs
+			.map(glob => glob.trim())
+			.filter(glob => glob.length > 0)
+			.map(glob => new Bun.Glob(glob));
+		return compiled.length > 0 ? compiled : undefined;
+	}
+
+	#parseToolScopeToken(token: string): ToolScope | undefined {
+		const match = /^(?:(?<prefix>tool)(?::(?<tool>[a-z0-9_-]+))?|(?<bare>[a-z0-9_-]+))(?:\((?<path>[^)]+)\))?$/i.exec(
+			token,
+		);
+		if (!match) {
+			return undefined;
+		}
+
+		const groups = match.groups;
+		const hasToolPrefix = groups?.prefix !== undefined;
+		const toolName = (groups?.tool ?? (hasToolPrefix ? undefined : groups?.bare))?.trim().toLowerCase();
+		const pathPattern = groups?.path?.trim();
+
+		if (!pathPattern) {
+			return { toolName };
+		}
+
+		return {
+			toolName,
+			pathPattern,
+			pathGlob: new Bun.Glob(pathPattern),
+		};
+	}
+
+	#buildScope(rule: Rule): TtsrScope {
+		if (!rule.scope || rule.scope.length === 0) {
+			return {
+				allowText: DEFAULT_SCOPE.allowText,
+				allowThinking: DEFAULT_SCOPE.allowThinking,
+				allowAnyTool: DEFAULT_SCOPE.allowAnyTool,
+				toolScopes: [...DEFAULT_SCOPE.toolScopes],
+			};
+		}
+
+		const scope: TtsrScope = {
+			allowText: false,
+			allowThinking: false,
+			allowAnyTool: false,
+			toolScopes: [],
+		};
+
+		for (const rawToken of rule.scope) {
+			const token = rawToken.trim();
+			const normalizedToken = token.toLowerCase();
+			if (token.length === 0) {
+				continue;
+			}
+
+			if (normalizedToken === "text") {
+				scope.allowText = true;
+				continue;
+			}
+
+			if (normalizedToken === "thinking") {
+				scope.allowThinking = true;
+				continue;
+			}
+
+			if (normalizedToken === "tool" || normalizedToken === "toolcall") {
+				scope.allowAnyTool = true;
+				continue;
+			}
+
+			const toolScope = this.#parseToolScopeToken(token);
+			if (!toolScope) {
+				logger.warn("TTSR scope token is invalid, skipping token", {
+					ruleName: rule.name,
+					token: rawToken,
+				});
+				continue;
+			}
+
+			if (!toolScope.toolName && !toolScope.pathGlob) {
+				scope.allowAnyTool = true;
+				continue;
+			}
+
+			scope.toolScopes.push(toolScope);
+		}
+
+		return scope;
+	}
+
+	#hasReachableScope(scope: TtsrScope): boolean {
+		return scope.allowText || scope.allowThinking || scope.allowAnyTool || scope.toolScopes.length > 0;
+	}
+
+	#bufferKey(context: TtsrMatchContext): string {
+		if (context.streamKey && context.streamKey.trim().length > 0) {
+			return context.streamKey;
+		}
+		if (context.source !== "tool") {
+			return context.source;
+		}
+		const toolName = context.toolName?.trim().toLowerCase();
+		return toolName ? `tool:${toolName}` : "tool";
+	}
+
+	#normalizePath(pathValue: string): string {
+		return pathValue.replaceAll("\\", "/");
+	}
+
+	#matchesGlob(glob: Bun.Glob, filePaths: string[] | undefined): boolean {
+		if (!filePaths || filePaths.length === 0) {
+			return false;
+		}
+		for (const filePath of filePaths) {
+			const normalized = this.#normalizePath(filePath);
+			if (glob.match(normalized)) {
+				return true;
+			}
+			const slashIndex = normalized.lastIndexOf("/");
+			const basename = slashIndex === -1 ? normalized : normalized.slice(slashIndex + 1);
+			if (basename !== normalized && glob.match(basename)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	#matchesGlobalPaths(entry: TtsrEntry, context: TtsrMatchContext): boolean {
+		if (!entry.globalPathGlobs || entry.globalPathGlobs.length === 0) {
+			return true;
+		}
+
+		for (const glob of entry.globalPathGlobs) {
+			if (this.#matchesGlob(glob, context.filePaths)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	#matchesScope(entry: TtsrEntry, context: TtsrMatchContext): boolean {
+		if (context.source === "text") {
+			return entry.scope.allowText;
+		}
+
+		if (context.source === "thinking") {
+			return entry.scope.allowThinking;
+		}
+
+		if (entry.scope.allowAnyTool) {
+			return true;
+		}
+
+		const toolName = context.toolName?.trim().toLowerCase();
+		for (const toolScope of entry.scope.toolScopes) {
+			if (toolScope.toolName && toolScope.toolName !== toolName) {
+				continue;
+			}
+			if (toolScope.pathGlob && !this.#matchesGlob(toolScope.pathGlob, context.filePaths)) {
+				continue;
+			}
+			return true;
+		}
+
+		return false;
+	}
+
+	#matchesCondition(entry: TtsrEntry, streamBuffer: string): boolean {
+		for (const condition of entry.conditions) {
+			condition.lastIndex = 0;
+			if (condition.test(streamBuffer)) {
+				return true;
+			}
 		}
+		return false;
+	}
 
+	/** Add a TTSR rule to be monitored. */
+	addRule(rule: Rule): boolean {
 		if (this.#rules.has(rule.name)) {
-			return;
+			return false;
 		}
 
-		try {
-			const regex = new RegExp(rule.ttsrTrigger);
-			this.#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", {
+		const conditions = this.#compileConditions(rule);
+		if (conditions.length === 0) {
+			return false;
+		}
+
+		const scope = this.#buildScope(rule);
+		if (!this.#hasReachableScope(scope)) {
+			logger.warn("TTSR scope excludes all streams, skipping rule", {
 				ruleName: rule.name,
-				pattern: rule.ttsrTrigger,
-				error: err instanceof Error ? err.message : String(err),
+				scope: rule.scope,
 			});
+			return false;
 		}
+		const globalPathGlobs = this.#compileGlobalPathGlobs(rule.globs);
+		this.#rules.set(rule.name, {
+			rule,
+			conditions,
+			scope,
+			globalPathGlobs,
+		});
+
+		logger.debug("TTSR rule registered", {
+			ruleName: rule.name,
+			conditions: rule.condition,
+			scope: rule.scope,
+			globs: rule.globs,
+		});
+
+		return true;
 	}
 
-	/** Check if any uninjected TTSR matches the stream buffer. Returns matching rules. */
-	check(streamBuffer: string): Rule[] {
-		const matches: Rule[] = [];
+	/**
+	 * Add a stream chunk to its scoped buffer and return matching rules.
+	 *
+	 * Buffers are isolated by source/tool key so matches don't bleed across
+	 * assistant prose, thinking text, and unrelated tool argument streams.
+	 */
+	checkDelta(delta: string, context: TtsrMatchContext): Rule[] {
+		const bufferKey = this.#bufferKey(context);
+		const nextBuffer = `${this.#buffers.get(bufferKey) ?? ""}${delta}`;
+		this.#buffers.set(bufferKey, nextBuffer);
 
+		const matches: Rule[] = [];
 		for (const [name, entry] of this.#rules) {
 			if (!this.#canTrigger(name)) {
 				continue;
 			}
-
-			if (entry.regex.test(streamBuffer)) {
-				matches.push(entry.rule);
-				logger.debug("TTSR pattern matched", {
-					ruleName: name,
-					pattern: entry.rule.ttsrTrigger,
-				});
+			if (!this.#matchesScope(entry, context)) {
+				continue;
 			}
+			if (!this.#matchesGlobalPaths(entry, context)) {
+				continue;
+			}
+			if (!this.#matchesCondition(entry, nextBuffer)) {
+				continue;
+			}
+
+			matches.push(entry.rule);
+			logger.debug("TTSR condition matched", {
+				ruleName: name,
+				conditions: entry.rule.condition,
+				source: context.source,
+				toolName: context.toolName,
+				filePaths: context.filePaths,
+			});
 		}
 
 		return matches;
 	}
 
-	/** Mark rules as injected (won't trigger again until conditions allow) */
+	/** Mark rules as injected (won't trigger again until conditions allow). */
 	markInjected(rulesToMark: Rule[]): void {
-		for (const rule of rulesToMark) {
-			this.#injectionRecords.set(rule.name, { lastInjectedAt: this.#messageCount });
+		this.markInjectedByNames(rulesToMark.map(rule => rule.name));
+	}
+
+	/** Mark rule names as injected (won't trigger again until conditions allow). */
+	markInjectedByNames(ruleNames: string[]): void {
+		for (const rawName of ruleNames) {
+			const ruleName = rawName.trim();
+			if (ruleName.length === 0) {
+				continue;
+			}
+			const record = this.#injectionRecords.get(ruleName);
+			if (!record) {
+				this.#injectionRecords.set(ruleName, { lastInjectedAt: this.#messageCount });
+			} else {
+				record.lastInjectedAt = this.#messageCount;
+			}
 			logger.debug("TTSR rule marked as injected", {
-				ruleName: rule.name,
+				ruleName,
 				messageCount: this.#messageCount,
 				repeatMode: this.#settings.repeatMode,
 			});
 		}
 	}
 
-	/** Get names of all injected rules (for persistence) */
+	/** Get names of all injected rules (for persistence). */
 	getInjectedRuleNames(): string[] {
 		return Array.from(this.#injectionRecords.keys());
 	}
 
-	/** Restore injected state from a list of rule names */
+	/** Restore injected state from a list of rule names. */
 	restoreInjected(ruleNames: string[]): void {
 		for (const name of ruleNames) {
 			this.#injectionRecords.set(name, { lastInjectedAt: 0 });
@@ -127,37 +407,27 @@ export class TtsrManager {
 		}
 	}
 
-	/** Reset stream buffer (called on new turn) */
+	/** Reset stream buffers (called on new turn). */
 	resetBuffer(): void {
-		this.#buffer = "";
-	}
-
-	/** Get current stream buffer */
-	getBuffer(): string {
-		return this.#buffer;
-	}
-
-	/** Append to stream buffer */
-	appendToBuffer(text: string): void {
-		this.#buffer += text;
+		this.#buffers.clear();
 	}
 
-	/** Check if any TTSRs are registered */
+	/** Check if any TTSR rules are registered. */
 	hasRules(): boolean {
 		return this.#rules.size > 0;
 	}
 
-	/** Increment message counter (call after each turn) */
+	/** Increment message counter (call after each turn). */
 	incrementMessageCount(): void {
 		this.#messageCount++;
 	}
 
-	/** Get current message count */
+	/** Get current message count. */
 	getMessageCount(): number {
 		return this.#messageCount;
 	}
 
-	/** Get settings */
+	/** Get settings. */
 	getSettings(): Required<TtsrSettings> {
 		return this.#settings;
 	}

package/src/extensibility/custom-tools/wrapper.ts

@@ -5,7 +5,7 @@ import type { AgentTool, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core
 import type { Static, TSchema } from "@sinclair/typebox";
 import type { Theme } from "../../modes/theme/theme";
 import { applyToolProxy } from "../tool-proxy";
-import type { CustomTool, CustomToolContext, LoadedCustomTool } from "./types";
+import type { CustomTool, CustomToolContext } from "./types";
 
 export class CustomToolAdapter<TParams extends TSchema = TSchema, TDetails = any, TTheme extends Theme = Theme>
 	implements AgentTool<TParams, TDetails, TTheme>
@@ -42,14 +42,4 @@ export class CustomToolAdapter<TParams extends TSchema = TSchema, TDetails = any
 	): AgentTool<TParams, TDetails, TTheme> {
 		return new CustomToolAdapter(tool, getContext);
 	}
-
-	/**
-	 * Wrap all loaded custom tools into AgentTools.
-	 */
-	static wrapTools<TParams extends TSchema = TSchema, TDetails = any, TTheme extends Theme = Theme>(
-		loadedTools: LoadedCustomTool<TParams, TDetails>[],
-		getContext: () => CustomToolContext,
-	): AgentTool<TParams, TDetails, TTheme>[] {
-		return loadedTools.map(lt => CustomToolAdapter.wrap(lt.tool, getContext));
-	}
 }

package/src/internal-urls/index.ts

@@ -1,15 +1,16 @@
 /**
- * Internal URL routing system for agent:// and skill:// URLs.
+ * Internal URL routing system for internal protocols like agent://, memory://, and skill://.
  *
  * This module provides a unified way to resolve internal URLs without
  * exposing filesystem paths to the agent.
  *
  * @example
  * ```ts
- * import { InternalUrlRouter, AgentProtocolHandler, SkillProtocolHandler } from './internal-urls';
+ * import { InternalUrlRouter, AgentProtocolHandler, MemoryProtocolHandler, SkillProtocolHandler } from './internal-urls';
  *
  * const router = new InternalUrlRouter();
  * router.register(new AgentProtocolHandler({ getArtifactsDir: () => sessionDir }));
+ * router.register(new MemoryProtocolHandler({ getMemoryRoot: () => memoryRoot }));
  * router.register(new SkillProtocolHandler({ getSkills: () => skills }));
  *
  * if (router.canHandle('agent://reviewer_0')) {
@@ -22,6 +23,7 @@
 export { AgentProtocolHandler, type AgentProtocolOptions } from "./agent-protocol";
 export { ArtifactProtocolHandler, type ArtifactProtocolOptions } from "./artifact-protocol";
 export { applyQuery, parseQuery, pathToQuery } from "./json-query";
+export { MemoryProtocolHandler, type MemoryProtocolOptions, resolveMemoryUrlToPath } from "./memory-protocol";
 export { PlanProtocolHandler, type PlanProtocolOptions, resolvePlanUrlToPath } from "./plan-protocol";
 export { InternalUrlRouter } from "./router";
 export { RuleProtocolHandler, type RuleProtocolOptions } from "./rule-protocol";

package/src/internal-urls/memory-protocol.ts

@@ -0,0 +1,133 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { validateRelativePath } from "./skill-protocol";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+const DEFAULT_MEMORY_FILE = "memory_summary.md";
+const MEMORY_NAMESPACE = "root";
+
+/**
+ * Options for the memory:// URL protocol.
+ */
+export interface MemoryProtocolOptions {
+	/**
+	 * Returns the absolute path to the current project's memory root.
+	 */
+	getMemoryRoot: () => string;
+}
+
+function ensureWithinRoot(targetPath: string, rootPath: string): void {
+	if (targetPath !== rootPath && !targetPath.startsWith(`${rootPath}${path.sep}`)) {
+		throw new Error("memory:// URL escapes memory root");
+	}
+}
+
+function toMemoryValidationError(error: unknown): Error {
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(message.replace("skill://", "memory://"));
+}
+
+/**
+ * Resolve a memory:// URL to an absolute filesystem path under memory root.
+ */
+export function resolveMemoryUrlToPath(url: InternalUrl, memoryRoot: string): string {
+	const namespace = url.rawHost || url.hostname;
+	if (!namespace) {
+		throw new Error("memory:// URL requires a namespace: memory://root");
+	}
+	if (namespace !== MEMORY_NAMESPACE) {
+		throw new Error(`Unknown memory namespace: ${namespace}. Supported: ${MEMORY_NAMESPACE}`);
+	}
+
+	const rawPathname = url.rawPathname ?? url.pathname;
+	const hasPath = rawPathname && rawPathname !== "/" && rawPathname !== "";
+	if (!hasPath) {
+		return path.resolve(memoryRoot, DEFAULT_MEMORY_FILE);
+	}
+	let relativePath: string;
+	try {
+		relativePath = decodeURIComponent(rawPathname.slice(1));
+	} catch {
+		throw new Error(`Invalid URL encoding in memory:// path: ${url.href}`);
+	}
+
+	try {
+		validateRelativePath(relativePath);
+	} catch (error) {
+		throw toMemoryValidationError(error);
+	}
+
+	return path.resolve(memoryRoot, relativePath);
+}
+
+/**
+ * Protocol handler for memory:// URLs.
+ *
+ * URL forms:
+ * - memory://root - Reads memory_summary.md
+ * - memory://root/<path> - Reads a relative file under memory root
+ */
+export class MemoryProtocolHandler implements ProtocolHandler {
+	readonly scheme = "memory";
+
+	constructor(private readonly options: MemoryProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const memoryRoot = path.resolve(this.options.getMemoryRoot());
+		let resolvedRoot: string;
+		try {
+			resolvedRoot = await fs.realpath(memoryRoot);
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error(
+					"Memory artifacts are not available for this project yet. Run a session with memories enabled first.",
+				);
+			}
+			throw error;
+		}
+
+		const targetPath = resolveMemoryUrlToPath(url, resolvedRoot);
+		ensureWithinRoot(targetPath, resolvedRoot);
+
+		const parentDir = path.dirname(targetPath);
+		try {
+			const realParent = await fs.realpath(parentDir);
+			ensureWithinRoot(realParent, resolvedRoot);
+		} catch (error) {
+			if (!isEnoent(error)) {
+				throw error;
+			}
+		}
+
+		let realTargetPath: string;
+		try {
+			realTargetPath = await fs.realpath(targetPath);
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error(`Memory file not found: ${url.href}`);
+			}
+			throw error;
+		}
+
+		ensureWithinRoot(realTargetPath, resolvedRoot);
+
+		const stat = await fs.stat(realTargetPath);
+		if (!stat.isFile()) {
+			throw new Error(`memory:// URL must resolve to a file: ${url.href}`);
+		}
+
+		const content = await Bun.file(realTargetPath).text();
+		const ext = path.extname(realTargetPath).toLowerCase();
+		const contentType: InternalResource["contentType"] = ext === ".md" ? "text/markdown" : "text/plain";
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: realTargetPath,
+			notes: [],
+		};
+	}
+}

package/src/internal-urls/router.ts

@@ -1,12 +1,12 @@
 /**
- * Internal URL router for resolving agent:// and skill:// URLs.
+ * Internal URL router for internal protocols (agent://, artifact://, plan://, memory://, skill://, rule://).
  */
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
 
 /**
  * Router for internal URL schemes.
  *
- * Dispatches URLs like `agent://output_id` or `skill://skill-name` to
+ * Dispatches URLs like `agent://output_id` or `memory://root/memory_summary.md` to
  * registered protocol handlers.
  */
 export class InternalUrlRouter {
@@ -52,6 +52,8 @@ export class InternalUrlRouter {
 			// Leave rawHost as-is if decoding fails.
 		}
 		(parsed as InternalUrl).rawHost = rawHost;
+		const pathMatch = input.match(/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*(\/[^?#]*)?/i);
+		(parsed as InternalUrl).rawPathname = pathMatch?.[1] ?? parsed.pathname;
 
 		const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
 		const handler = this.#handlers.get(scheme);

package/src/internal-urls/skill-protocol.ts

@@ -30,7 +30,7 @@ function getContentType(filePath: string): InternalResource["contentType"] {
 /**
  * Validate that a path is safe (no traversal, no absolute paths).
  */
-function validateRelativePath(relativePath: string): void {
+export function validateRelativePath(relativePath: string): void {
 	if (path.isAbsolute(relativePath)) {
 		throw new Error("Absolute paths are not allowed in skill:// URLs");
 	}