@dyyz1993/pi-coding-agent 0.74.24 → 0.74.25

package/dist/extensions/preview/index.ts

@@ -0,0 +1,278 @@
+import { existsSync, statSync } from "node:fs";
+import { extname, isAbsolute, resolve } from "node:path";
+import { createConnection } from "node:net";
+import type { AgentToolResult } from "@dyyz1993/pi-agent-core";
+import { Text } from "@dyyz1993/pi-tui";
+import { Type } from "typebox";
+import type { ExtensionAPI, ExtensionContext } from "@dyyz1993/pi-coding-agent";
+
+export type ResourceType = "image" | "url" | "html" | "pdf" | "video" | "audio" | "markdown" | "text";
+
+export interface PreviewDetails {
+	source: string;
+	absolutePath?: string;
+	resourceType: ResourceType;
+	mimeType?: string;
+	status: "ok" | "not_found" | "error";
+	size?: number;
+	title?: string;
+	error?: string;
+}
+
+const EXT_TO_RESOURCE: Record<string, { resourceType: ResourceType; mimeType: string }> = {
+	".png": { resourceType: "image", mimeType: "image/png" },
+	".jpg": { resourceType: "image", mimeType: "image/jpeg" },
+	".jpeg": { resourceType: "image", mimeType: "image/jpeg" },
+	".gif": { resourceType: "image", mimeType: "image/gif" },
+	".webp": { resourceType: "image", mimeType: "image/webp" },
+	".svg": { resourceType: "image", mimeType: "image/svg+xml" },
+	".bmp": { resourceType: "image", mimeType: "image/bmp" },
+	".ico": { resourceType: "image", mimeType: "image/x-icon" },
+	".html": { resourceType: "html", mimeType: "text/html" },
+	".htm": { resourceType: "html", mimeType: "text/html" },
+	".pdf": { resourceType: "pdf", mimeType: "application/pdf" },
+	".mp4": { resourceType: "video", mimeType: "video/mp4" },
+	".webm": { resourceType: "video", mimeType: "video/webm" },
+	".ogg": { resourceType: "video", mimeType: "video/ogg" },
+	".mp3": { resourceType: "audio", mimeType: "audio/mpeg" },
+	".wav": { resourceType: "audio", mimeType: "audio/wav" },
+	".flac": { resourceType: "audio", mimeType: "audio/flac" },
+	".md": { resourceType: "markdown", mimeType: "text/markdown" },
+	".mdx": { resourceType: "markdown", mimeType: "text/mdx" },
+};
+
+const URL_PATTERN = /^https?:\/\//i;
+
+function isLocalAddress(host: string): boolean {
+	if (!host) return false;
+	const lower = host.toLowerCase();
+	if (lower === "localhost" || lower === "127.0.0.1" || lower === "::1") return true;
+	if (/^192\.168\.\d{1,3}\.\d{1,3}$/.test(host)) return true;
+	if (/^10\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) return true;
+	if (/^172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}$/.test(host)) return true;
+	return false;
+}
+
+function checkReachable(host: string, port: number, timeoutMs = 2000): Promise<boolean> {
+	return new Promise((resolve) => {
+		const socket = createConnection({ host, port }, () => {
+			socket.destroy();
+			resolve(true);
+		});
+		socket.setTimeout(timeoutMs);
+		socket.on("timeout", () => {
+			socket.destroy();
+			resolve(false);
+		});
+		socket.on("error", () => {
+			socket.destroy();
+			resolve(false);
+		});
+	});
+}
+
+function isUrl(source: string): boolean {
+	return URL_PATTERN.test(source);
+}
+
+function detectResource(
+	source: string,
+	cwd: string,
+): {
+	resourceType: ResourceType;
+	mimeType?: string;
+	absolutePath?: string;
+} {
+	if (isUrl(source)) {
+		return { resourceType: "url", absolutePath: source };
+	}
+
+	const absolutePath = isAbsolute(source) ? source : resolve(cwd, source);
+	const ext = extname(source).toLowerCase();
+	const mapped = EXT_TO_RESOURCE[ext];
+	if (mapped) {
+		return { resourceType: mapped.resourceType, mimeType: mapped.mimeType, absolutePath };
+	}
+	return { resourceType: "text", mimeType: "text/plain", absolutePath };
+}
+
+const PreviewParams = Type.Object({
+	source: Type.String({ description: "File path or URL to preview" }),
+	title: Type.Optional(Type.String({ description: "Optional display title for the card" })),
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "preview",
+		label: "Preview",
+		description:
+			"Preview a resource (image, URL, PDF, video, audio, markdown, etc.) as a card in the UI. Does not send file content to the LLM.",
+		promptSnippet: "Preview a file or URL as a card",
+		parameters: PreviewParams,
+
+		async execute(
+			_toolCallId: string,
+			params: { source: string; title?: string },
+			_signal?: AbortSignal,
+			_onUpdate?: unknown,
+			ctx?: ExtensionContext,
+		): Promise<AgentToolResult<PreviewDetails>> {
+			const cwd = ctx?.cwd ?? process.cwd();
+
+			if (!params.source?.trim()) {
+				return {
+					content: [{ type: "text", text: "Error: source is required" }],
+					details: { source: "", resourceType: "text", status: "error", error: "source required" },
+				};
+			}
+
+			const { resourceType, mimeType, absolutePath } = detectResource(params.source, cwd);
+
+			if (resourceType === "url") {
+				// 对本地/LAN 地址做 TCP 可达性检测
+				if (params.source.startsWith("http://")) {
+					try {
+						const parsed = new URL(params.source);
+						if (isLocalAddress(parsed.hostname)) {
+							const port = parseInt(parsed.port || "80", 10);
+							const reachable = await checkReachable(parsed.hostname, port);
+							if (!reachable) {
+								const msg = `Preview 失败：${parsed.host} 未在局域网开放，服务可能只监听 127.0.0.1。请将服务绑定到 0.0.0.0 后重试。`;
+								return {
+									content: [{ type: "text", text: msg }],
+									details: {
+										source: params.source,
+										absolutePath: params.source,
+										resourceType: "url",
+										status: "error",
+										title: params.title,
+										error: `${parsed.host} 未在局域网开放，可能只监听 127.0.0.1`,
+									},
+								};
+							}
+						}
+					} catch {
+						// URL parse 失败，继续正常流程
+					}
+				}
+
+				return {
+					content: [{ type: "text", text: `Preview: ${params.source} (url)` }],
+					details: {
+						source: params.source,
+						absolutePath: params.source,
+						resourceType: "url",
+						status: "ok",
+						title: params.title,
+					},
+				};
+			}
+
+			if (!absolutePath || !existsSync(absolutePath)) {
+				return {
+					content: [{ type: "text", text: `Preview: ${params.source} not found` }],
+					details: {
+						source: params.source,
+						absolutePath,
+						resourceType,
+						status: "not_found",
+						title: params.title,
+						error: "file not found",
+					},
+				};
+			}
+
+			const stat = statSync(absolutePath);
+			if (stat.isDirectory()) {
+				return {
+					content: [{ type: "text", text: `Preview: ${params.source} is a directory` }],
+					details: {
+						source: params.source,
+						absolutePath,
+						resourceType,
+						status: "error",
+						title: params.title,
+						error: "is a directory",
+					},
+				};
+			}
+
+			const sizeStr =
+				stat.size > 1024 * 1024
+					? `${(stat.size / (1024 * 1024)).toFixed(1)}MB`
+					: stat.size > 1024
+						? `${(stat.size / 1024).toFixed(1)}KB`
+						: `${stat.size}B`;
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Preview: ${params.source} (${resourceType}${mimeType ? `, ${mimeType}` : ""}, ${sizeStr})`,
+					},
+				],
+				details: {
+					source: params.source,
+					absolutePath,
+					resourceType,
+					mimeType,
+					status: "ok",
+					size: stat.size,
+					title: params.title,
+				},
+			};
+		},
+
+		renderCall(args, theme) {
+			let text = theme.fg("toolTitle", theme.bold("preview "));
+			if (args.title) text += theme.fg("dim", `"${args.title}" `);
+			text += theme.fg("muted", args.source ?? "");
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded: _expanded }, theme) {
+			const details = result.details as PreviewDetails | undefined;
+			if (!details) {
+				const text = result.content[0];
+				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+			}
+
+			if (details.error || details.status === "not_found") {
+				return new Text(theme.fg("error", `Preview: ${details.error ?? "error"}`), 0, 0);
+			}
+
+			const icon = resourceIcon(details.resourceType);
+			const label = details.title ?? details.source;
+			const sizeStr = details.size ? ` (${formatSize(details.size)})` : "";
+
+			return new Text(`${theme.fg("success", icon)} ${theme.fg("muted", `${label}${sizeStr}`)}`, 0, 0);
+		},
+	});
+}
+
+function resourceIcon(type: ResourceType): string {
+	switch (type) {
+		case "image":
+			return "🖼";
+		case "url":
+			return "🔗";
+		case "video":
+			return "🎬";
+		case "audio":
+			return "🎵";
+		case "pdf":
+			return "📄";
+		case "html":
+			return "🌐";
+		case "markdown":
+			return "📝";
+		default:
+			return "📋";
+	}
+}
+
+function formatSize(bytes: number): string {
+	if (bytes > 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	if (bytes > 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${bytes}B`;
+}

package/dist/extensions/rules-engine/MATCH_HISTORY_RECONCILIATION.md

@@ -0,0 +1,111 @@
+# Rules Engine: MatchHistory Staleness Scenarios & Reconciliation
+
+## Problem
+
+Conditional rule matches are tracked in `matchHistory` (an array of `MatchRecord`).
+The history can become **stale** when messages that triggered matches are removed or modified
+without an explicit notification to the rules-engine plugin.
+
+## Scenarios
+
+### 1. Context Compaction
+
+**What happens**: pi compacts old messages into a summary. ToolResult messages
+that contained `details.rulesMatched` are replaced by a compact summary entry.
+
+**Signal**: `session_compact` event fires. Plugin resets `cachedMatchHash` and clears `lastMessages`.
+
+**Reconciliation**:
+- `context` event fires on the next agent turn with the **post-compaction** message list
+- `rebuildMatchHistory()` scans remaining messages — compacted-away matches disappear
+- `turn_end` also checks for drift and sends corrected snapshot if needed
+
+**Result**: Matched rules from compacted-away messages are automatically cleared.
+
+### 2. Rollback / Abort Retry
+
+**What happens**: User triggers abort_retry, which removes the last assistant turn
+including its tool results. Previously matched rules are no longer in context.
+
+**Signal**: No explicit event. The rolled-back messages are removed from the message list.
+
+**Reconciliation**:
+- `context` event fires on the next agent turn — rolled-back messages are absent
+- `rebuildMatchHistory()` only finds matches in remaining messages
+- `turn_end` catches this too
+
+**Result**: Stale. Panel may show old matches until next agent turn or manual `requestSnapshot`.
+
+### 3. Manual Message Deletion
+
+**What happens**: User manually deletes a message (e.g., via UI). If the deleted message
+was a toolResult with `details.rulesMatched`, the match is no longer valid.
+
+**Signal**: No event at all.
+
+**Reconciliation**:
+- Same as rollback: `context` and `turn_end` eventually reconcile
+- Frontend `requestSnapshot` (on panel open/refresh) triggers `rebuildMatchHistory(lastMessages)`
+- But `lastMessages` may be stale if no `context` event fired since deletion
+
+**Result**: Stale until next agent turn or `requestSnapshot` with fresh context.
+
+### 4. Other Plugin Modifies/Hides Tool Results
+
+**What happens**: Another plugin (e.g., todo-cleanup) hides or modifies a toolResult entry,
+removing its `details.rulesMatched` field or replacing the message entirely.
+
+**Signal**: No cross-plugin notification.
+
+**Reconciliation**:
+- `context` event sees the modified messages and rebuilds accordingly
+- If the other plugin modifies messages between `context` events, stale data persists
+
+**Result**: Same as deletion — eventually consistent after next `context`.
+
+### 5. Session Fork / Switch
+
+**What happens**: Session is forked or user switches to a different session. The forked
+session has a copy of messages, but the rules-engine state is per-process.
+
+**Signal**: `session_start` fires for the new session. Plugin sends fresh snapshot.
+
+**Reconciliation**:
+- New pi process → fresh state → `session_start` sends snapshot with empty history
+- `context` event rebuilds from the forked messages
+- Any matches present in the forked messages will be picked up
+
+**Result**: Correct — matches from the fork are preserved, new matches start fresh.
+
+## Reconciliation Mechanism Summary
+
+| Mechanism | Trigger | Uses Fresh Data? | Cost |
+|-----------|---------|------------------|------|
+| `context` event | Every agent turn (before LLM call) | Yes (current messages) | Medium — scans all messages |
+| `turn_end` event | End of every turn | Yes (cached `lastMessages`) | Low — hash comparison + conditional snapshot |
+| `requestSnapshot` RPC | Frontend panel open/refresh | Yes (cached `lastMessages`) | Low — only when user requests |
+| `session_compact` | After compaction | Clears cache → forces rebuild | Negligible |
+
+## Latency Analysis
+
+The `context` event fires via `transformContext` in the agent loop (`packages/agent/agent-loop.ts:145-146`),
+called **before every LLM call**. This is the primary reconciliation point.
+
+**Latency gap**: Between a message mutation (rollback, deletion, compaction) and the next LLM call,
+the panel may show stale data. This is acceptable because:
+
+1. Users rarely watch the rules panel during message mutations
+2. Next agent turn reconciles immediately (sub-second)
+3. `requestSnapshot` (panel open/refresh) uses `lastMessages` which is at most one turn stale
+4. No event exists for message deletion in the pi extension API — polling would be the only alternative
+
+**Why not poll?** Periodic `requestSnapshot` would require fresh messages (not cached), which means
+calling into the agent state on a timer. The `context` event already provides this for free on every turn.
+
+## Implementation Notes
+
+- `rebuildMatchHistory()` is the single source of truth — shared by `context`, `turn_end`, and `requestSnapshot`
+- `lastMessages` is cached from the most recent `context` event
+- `cachedMatchHash` is used to avoid sending duplicate snapshots when nothing changed
+- Frontend merges `matchHistory` on snapshot (doesn't wipe on empty) to survive between reconciliations
+- All 5 scenarios are **eventually consistent** with at most one-turn latency — no additional mechanism needed