pi-web-access 0.5.0 → 0.7.0

package/index.ts

@@ -4,7 +4,9 @@ import { Type } from "@sinclair/typebox";
 import { StringEnum } from "@mariozechner/pi-ai";
 import { fetchAllContent, type ExtractedContent } from "./extract.js";
 import { clearCloneCache } from "./github-extract.js";
-import { searchWithPerplexity, type SearchResult } from "./perplexity.js";
+import { search, type SearchProvider } from "./gemini-search.js";
+import type { SearchResult } from "./perplexity.js";
+import { formatSeconds } from "./utils.js";
 import {
 	clearResults,
 	deleteResult,
@@ -25,6 +27,10 @@ let widgetUnsubscribe: (() => void) | null = null;
 
 const MAX_INLINE_CONTENT = 30000; // Content returned directly to agent
 
+function stripThumbnails(results: ExtractedContent[]): ExtractedContent[] {
+	return results.map(({ thumbnail, frames, ...rest }) => rest);
+}
+
 function formatSearchSummary(results: SearchResult[], answer: string): string {
 	let output = answer ? `${answer}\n\n---\n\n**Sources:**\n` : "";
 	output += results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}`).join("\n\n");
@@ -144,7 +150,7 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => handleSessionChange(ctx));
 	pi.on("session_switch", async (_event, ctx) => handleSessionChange(ctx));
-	pi.on("session_branch", async (_event, ctx) => handleSessionChange(ctx));
+	pi.on("session_fork", async (_event, ctx) => handleSessionChange(ctx));
 	pi.on("session_tree", async (_event, ctx) => handleSessionChange(ctx));
 
 	pi.on("session_shutdown", () => {
@@ -163,16 +169,19 @@ export default function (pi: ExtensionAPI) {
 		name: "web_search",
 		label: "Web Search",
 		description:
-			"Search the web using Perplexity AI. Returns an AI-synthesized answer with source citations. Supports batch searching with multiple queries. When includeContent is true, full page content is fetched in the background.",
+			"Search the web using Perplexity AI or Gemini. Returns an AI-synthesized answer with source citations. Supports batch searching with multiple queries. When includeContent is true, full page content is fetched in the background. Provider auto-selects: Perplexity if configured, else Gemini API (needs key), else Gemini Web (needs Chrome login).",
 		parameters: Type.Object({
 			query: Type.Optional(Type.String({ description: "Single search query" })),
-			queries: Type.Optional(Type.Array(Type.String(), { description: "Multiple queries (parallel)" })),
+			queries: Type.Optional(Type.Array(Type.String(), { description: "Multiple queries (batch)" })),
 			numResults: Type.Optional(Type.Number({ description: "Results per query (default: 5, max: 20)" })),
 			includeContent: Type.Optional(Type.Boolean({ description: "Fetch full page content (async)" })),
 			recencyFilter: Type.Optional(
 				StringEnum(["day", "week", "month", "year"], { description: "Filter by recency" }),
 			),
 			domainFilter: Type.Optional(Type.Array(Type.String(), { description: "Limit to domains (prefix with - to exclude)" })),
+			provider: Type.Optional(
+				StringEnum(["auto", "perplexity", "gemini"], { description: "Search provider (default: auto)" }),
+			),
 		}),
 
 		async execute(_toolCallId, params, signal, onUpdate, _ctx) {
@@ -196,7 +205,8 @@ export default function (pi: ExtensionAPI) {
 				});
 
 				try {
-					const { answer, results } = await searchWithPerplexity(query, {
+					const { answer, results } = await search(query, {
+						provider: params.provider as SearchProvider | undefined,
 						numResults: params.numResults,
 						recencyFilter: params.recencyFilter,
 						domainFilter: params.domainFilter,
@@ -249,7 +259,7 @@ export default function (pi: ExtensionAPI) {
 							id: capturedFetchId,
 							type: "fetch",
 							timestamp: Date.now(),
-							urls: fetched,
+							urls: stripThumbnails(fetched),
 						};
 						storeResult(capturedFetchId, data);
 						pi.appendEntry("web-search-results", data);
@@ -392,13 +402,24 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "fetch_content",
 		label: "Fetch Content",
-		description: "Fetch URL(s) and extract readable content as markdown. Content is always stored and can be retrieved with get_search_content.",
+		description: "Fetch URL(s) and extract readable content as markdown. Supports YouTube video transcripts (with thumbnail), GitHub repository contents, and local video files (with frame thumbnail). Video frames can be extracted via timestamp/range or sampled across the entire video with frames alone. Falls back to Gemini for pages that block bots or fail Readability extraction. For YouTube and video files: ALWAYS pass the user's specific question via the prompt parameter — this directs the AI to focus on that aspect of the video, producing much better results than a generic extraction. Content is always stored and can be retrieved with get_search_content.",
 		parameters: Type.Object({
 			url: Type.Optional(Type.String({ description: "Single URL to fetch" })),
 			urls: Type.Optional(Type.Array(Type.String(), { description: "Multiple URLs (parallel)" })),
 			forceClone: Type.Optional(Type.Boolean({
 				description: "Force cloning large GitHub repositories that exceed the size threshold",
 			})),
+			prompt: Type.Optional(Type.String({
+				description: "Question or instruction for video analysis (YouTube and video files). Pass the user's specific question here — e.g. 'describe the book shown at the advice for beginners section'. Without this, a generic transcript extraction is used which may miss what the user is asking about.",
+			})),
+			timestamp: Type.Optional(Type.String({
+				description: "Extract video frame(s) at a timestamp or time range. Single: '1:23:45', '23:45', or '85' (seconds). Range: '23:41-25:00' extracts evenly-spaced frames across that span (default 6). Use frames with ranges to control density; single+frames uses a fixed 5s interval. YouTube requires yt-dlp + ffmpeg; local videos require ffmpeg. Use a range when you know the approximate area but not the exact moment — you'll get a contact sheet to visually identify the right frame.",
+			})),
+			frames: Type.Optional(Type.Integer({
+				minimum: 1,
+				maximum: 12,
+				description: "Number of frames to extract. Use with timestamp range for custom density, with single timestamp to get N frames at 5s intervals, or alone to sample across the entire video. Requires yt-dlp + ffmpeg for YouTube, ffmpeg for local video.",
+			})),
 		}),
 
 		async execute(_toolCallId, params, signal, onUpdate, _ctx) {
@@ -417,6 +438,9 @@ export default function (pi: ExtensionAPI) {
 
 			const fetchResults = await fetchAllContent(urlList, signal, {
 				forceClone: params.forceClone,
+				prompt: params.prompt,
+				timestamp: params.timestamp,
+				frames: params.frames,
 			});
 			const successful = fetchResults.filter((r) => !r.error).length;
 			const totalChars = fetchResults.reduce((sum, r) => sum + r.content.length, 0);
@@ -427,7 +451,7 @@ export default function (pi: ExtensionAPI) {
 				id: responseId,
 				type: "fetch",
 				timestamp: Date.now(),
-				urls: fetchResults,
+				urls: stripThumbnails(fetchResults),
 			};
 			storeResult(responseId, data);
 			pi.appendEntry("web-search-results", data);
@@ -438,7 +462,7 @@ export default function (pi: ExtensionAPI) {
 				if (result.error) {
 					return {
 						content: [{ type: "text", text: `Error: ${result.error}` }],
-						details: { urls: urlList, urlCount: 1, successful: 0, error: result.error, responseId },
+						details: { urls: urlList, urlCount: 1, successful: 0, error: result.error, responseId, prompt: params.prompt, timestamp: params.timestamp, frames: params.frames },
 					};
 				}
 
@@ -453,8 +477,20 @@ export default function (pi: ExtensionAPI) {
 						`Use get_search_content({ responseId: "${responseId}", urlIndex: 0 }) for full content.`;
 				}
 
+				const content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> = [];
+				if (result.frames?.length) {
+					for (const frame of result.frames) {
+						content.push({ type: "image", data: frame.data, mimeType: frame.mimeType });
+						content.push({ type: "text", text: `Frame at ${frame.timestamp}` });
+					}
+				} else if (result.thumbnail) {
+					content.push({ type: "image", data: result.thumbnail.data, mimeType: result.thumbnail.mimeType });
+				}
+				content.push({ type: "text", text: output });
+
+				const imageCount = (result.frames?.length ?? 0) + (result.thumbnail ? 1 : 0);
 				return {
-					content: [{ type: "text", text: output }],
+					content,
 					details: {
 						urls: urlList,
 						urlCount: 1,
@@ -463,6 +499,12 @@ export default function (pi: ExtensionAPI) {
 						title: result.title,
 						responseId,
 						truncated,
+						hasImage: imageCount > 0,
+						imageCount,
+						prompt: params.prompt,
+						timestamp: params.timestamp,
+						frames: params.frames,
+						duration: result.duration,
 					},
 				};
 			}
@@ -485,27 +527,39 @@ export default function (pi: ExtensionAPI) {
 		},
 
 		renderCall(args, theme) {
-			const { url, urls } = args as { url?: string; urls?: string[] };
+			const { url, urls, prompt, timestamp, frames } = args as { url?: string; urls?: string[]; prompt?: string; timestamp?: string; frames?: number };
 			const urlList = urls ?? (url ? [url] : []);
 			if (urlList.length === 0) {
 				return new Text(theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("error", "(no URL)"), 0, 0);
 			}
+			const lines: string[] = [];
 			if (urlList.length === 1) {
-				const display = urlList[0].length > 50 ? urlList[0].slice(0, 47) + "..." : urlList[0];
-				return new Text(theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("accent", display), 0, 0);
+				const display = urlList[0].length > 60 ? urlList[0].slice(0, 57) + "..." : urlList[0];
+				lines.push(theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("accent", display));
+			} else {
+				lines.push(theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("accent", `${urlList.length} URLs`));
+				for (const u of urlList.slice(0, 5)) {
+					const display = u.length > 60 ? u.slice(0, 57) + "..." : u;
+					lines.push(theme.fg("muted", "  " + display));
+				}
+				if (urlList.length > 5) {
+					lines.push(theme.fg("muted", `  ... and ${urlList.length - 5} more`));
+				}
+			}
+			if (timestamp) {
+				lines.push(theme.fg("dim", "  timestamp: ") + theme.fg("warning", timestamp));
 			}
-			const lines = [theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("accent", `${urlList.length} URLs`)];
-			for (const u of urlList.slice(0, 5)) {
-				const display = u.length > 60 ? u.slice(0, 57) + "..." : u;
-				lines.push(theme.fg("muted", "  " + display));
+			if (typeof frames === "number") {
+				lines.push(theme.fg("dim", "  frames: ") + theme.fg("warning", String(frames)));
 			}
-			if (urlList.length > 5) {
-				lines.push(theme.fg("muted", `  ... and ${urlList.length - 5} more`));
+			if (prompt) {
+				const display = prompt.length > 250 ? prompt.slice(0, 247) + "..." : prompt;
+				lines.push(theme.fg("dim", "  prompt: ") + theme.fg("muted", `"${display}"`));
 			}
 			return new Text(lines.join("\n"), 0, 0);
 		},
 
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded, isPartial }, theme) {
 			const details = result.details as {
 				urlCount?: number;
 				successful?: number;
@@ -514,27 +568,63 @@ export default function (pi: ExtensionAPI) {
 				title?: string;
 				truncated?: boolean;
 				responseId?: string;
+				phase?: string;
+				progress?: number;
+				hasImage?: boolean;
+				imageCount?: number;
+				prompt?: string;
+				timestamp?: string;
+				frames?: number;
+				duration?: number;
 			};
 
+			if (isPartial) {
+				const progress = details?.progress ?? 0;
+				const bar = "\u2588".repeat(Math.floor(progress * 10)) + "\u2591".repeat(10 - Math.floor(progress * 10));
+				return new Text(theme.fg("accent", `[${bar}] ${details?.phase || "fetching"}`), 0, 0);
+			}
+
 			if (details?.error) {
 				return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
 			}
 
 			if (details?.urlCount === 1) {
 				const title = details?.title || "Untitled";
-				let statusLine = theme.fg("success", title) + theme.fg("muted", ` (${details?.totalChars ?? 0} chars)`);
+				const imgCount = details?.imageCount ?? (details?.hasImage ? 1 : 0);
+				const imageBadge = imgCount > 1
+					? theme.fg("accent", ` [${imgCount} images]`)
+					: imgCount === 1
+						? theme.fg("accent", " [image]")
+						: "";
+				let statusLine = theme.fg("success", title) + theme.fg("muted", ` (${details?.totalChars ?? 0} chars)`) + imageBadge;
 				if (details?.truncated) {
 					statusLine += theme.fg("warning", " [truncated]");
 				}
+				if (typeof details?.duration === "number") {
+					statusLine += theme.fg("muted", ` | ${formatSeconds(Math.floor(details.duration))} total`);
+				}
 				if (!expanded) {
 					return new Text(statusLine, 0, 0);
 				}
+				const lines = [statusLine];
+				if (details?.prompt) {
+					const display = details.prompt.length > 250 ? details.prompt.slice(0, 247) + "..." : details.prompt;
+					lines.push(theme.fg("dim", `  prompt: "${display}"`));
+				}
+				if (details?.timestamp) {
+					lines.push(theme.fg("dim", `  timestamp: ${details.timestamp}`));
+				}
+				if (typeof details?.frames === "number") {
+					lines.push(theme.fg("dim", `  frames: ${details.frames}`));
+				}
 				const textContent = result.content.find((c) => c.type === "text")?.text || "";
 				const preview = textContent.length > 500 ? textContent.slice(0, 500) + "..." : textContent;
-				return new Text(statusLine + "\n" + theme.fg("dim", preview), 0, 0);
+				lines.push(theme.fg("dim", preview));
+				return new Text(lines.join("\n"), 0, 0);
 			}
 
-			const statusLine = theme.fg("success", `${details?.successful}/${details?.urlCount} URLs`) + theme.fg("muted", " (content stored)");
+			const countColor = (details?.successful ?? 0) > 0 ? "success" : "error";
+			const statusLine = theme.fg(countColor, `${details?.successful}/${details?.urlCount} URLs`) + theme.fg("muted", " (content stored)");
 			if (!expanded) {
 				return new Text(statusLine, 0, 0);
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-access",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "keywords": ["pi-package", "pi", "pi-coding-agent", "extension", "web-search", "perplexity", "fetch", "scraping"],
   "dependencies": {
@@ -11,6 +11,8 @@
     "unpdf": "^1.4.0"
   },
   "pi": {
-    "extensions": ["./index.ts"]
+    "extensions": ["./index.ts"],
+    "skills": ["./skills"],
+    "video": "https://github.com/nicobailon/pi-web-access/raw/refs/heads/main/pi-web-fetch-demo.mp4"
   }
 }

package/perplexity.ts

@@ -19,7 +19,7 @@ export interface SearchResult {
 	snippet: string;
 }
 
-export interface PerplexityResponse {
+export interface SearchResponse {
 	answer: string;
 	results: SearchResult[];
 }
@@ -91,7 +91,12 @@ function validateDomainFilter(domains: string[]): string[] {
 	});
 }
 
-export async function searchWithPerplexity(query: string, options: SearchOptions = {}): Promise<PerplexityResponse> {
+export function isPerplexityAvailable(): boolean {
+	const config = loadConfig();
+	return Boolean(config.perplexityApiKey || process.env.PERPLEXITY_API_KEY);
+}
+
+export async function searchWithPerplexity(query: string, options: SearchOptions = {}): Promise<SearchResponse> {
 	checkRateLimit();
 
 	const activityId = activityMonitor.logStart({ type: "api", query });

package/rsc-extract.ts

@@ -150,7 +150,7 @@ export function extractRSCContent(html: string): RSCExtractResult | null {
         case "p": return ctx.inTable ? content : `${content.trim()}\n\n`;
         case "code": {
           const codeContent = children ? extractNode(children as Node, { ...ctx, inCode: true }) : "";
-          return `\`${codeContent}\``;
+          return ctx.inCode ? codeContent : `\`${codeContent}\``;
         }
         case "pre": {
           const preContent = children ? extractNode(children as Node, { ...ctx, inCode: true }) : "";

package/skills/librarian/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: librarian
+description: Research open-source libraries with evidence-backed answers and GitHub permalinks. Use when the user asks about library internals, needs implementation details with source code references, wants to understand why something was changed, or needs authoritative answers backed by actual code. Excels at navigating large open-source repos and providing citations to exact lines of code.
+---
+
+# Librarian
+
+Answer questions about open-source libraries by finding evidence with GitHub permalinks. Every claim backed by actual code.
+
+## Execution Model
+
+Pi executes tool calls sequentially, even when you emit multiple calls in one turn. But batching independent calls in a single turn still saves LLM round-trips (~5-10s each). Use these patterns:
+
+| Pattern | When | Actually parallel? |
+|---------|------|-------------------|
+| Batch tool calls in one turn | Independent ops (web_search + fetch_content + read) | No, but saves round-trips |
+| `fetch_content({ urls: [...] })` | Multiple URLs to fetch | Yes (3 concurrent) |
+| Bash with `&` + `wait` | Multiple git/gh commands | Yes (OS-level) |
+
+## Step 1: Classify the Request
+
+Before doing anything, classify the request to pick the right research strategy.
+
+| Type | Trigger | Primary Approach |
+|------|---------|-----------------|
+| **Conceptual** | "How do I use X?", "Best practice for Y?" | web_search + fetch_content (README/docs) |
+| **Implementation** | "How does X implement Y?", "Show me the source" | fetch_content (clone) + code search |
+| **Context/History** | "Why was this changed?", "History of X?" | git log + git blame + issue/PR search |
+| **Comprehensive** | Complex or ambiguous requests, "deep dive" | All of the above |
+
+## Step 2: Research by Type
+
+### Conceptual Questions
+
+Batch these in one turn:
+
+1. **web_search**: `"library-name topic"` via Perplexity for recent articles and discussions
+2. **fetch_content**: the library's GitHub repo URL to clone and check README, docs, or examples
+
+Synthesize web results + repo docs. Cite official documentation and link to relevant source files.
+
+### Implementation Questions
+
+The core workflow -- clone, find, permalink:
+
+1. **fetch_content** the GitHub repo URL -- this clones it locally and returns the file tree
+2. Use **bash** to search the cloned repo: `grep -rn "function_name"`, `find . -name "*.ts"`
+3. Use **read** to examine specific files once you've located them
+4. Get the commit SHA: `cd /tmp/pi-github-repos/owner/repo && git rev-parse HEAD`
+5. Construct permalink: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`
+
+Batch the initial calls: fetch_content (clone) + web_search (recent discussions) in one turn. Then dig into the clone with grep/read once it's available.
+
+### Context/History Questions
+
+Use git operations on the cloned repo:
+
+```bash
+cd /tmp/pi-github-repos/owner/repo
+
+# Recent changes to a specific file
+git log --oneline -n 20 -- path/to/file.ts
+
+# Who changed what and when
+git blame -L 10,30 path/to/file.ts
+
+# Full diff for a specific commit
+git show <sha> -- path/to/file.ts
+
+# Search commit messages
+git log --oneline --grep="keyword" -n 10
+```
+
+For issues and PRs, use bash:
+
+```bash
+# Search issues
+gh search issues "keyword" --repo owner/repo --state all --limit 10
+
+# Search merged PRs
+gh search prs "keyword" --repo owner/repo --state merged --limit 10
+
+# View specific issue/PR with comments
+gh issue view <number> --repo owner/repo --comments
+gh pr view <number> --repo owner/repo --comments
+
+# Release notes
+gh api repos/owner/repo/releases --jq '.[0:5] | .[].tag_name'
+```
+
+### Comprehensive Research
+
+Combine everything. Batch these in one turn:
+
+1. **web_search**: recent articles and discussions
+2. **fetch_content**: clone the repo (or multiple repos if comparing)
+3. **bash**: `gh search issues "keyword" --repo owner/repo --limit 10 & gh search prs "keyword" --repo owner/repo --state merged --limit 10 & wait`
+
+Then dig into the clone with grep, read, git blame, git log as needed.
+
+## Step 3: Construct Permalinks
+
+Permalinks are the whole point. They make your answers citable and verifiable.
+
+```
+https://github.com/<owner>/<repo>/blob/<commit-sha>/<filepath>#L<start>-L<end>
+```
+
+Getting the SHA from a cloned repo:
+
+```bash
+cd /tmp/pi-github-repos/owner/repo && git rev-parse HEAD
+```
+
+Getting the SHA from a tag:
+
+```bash
+gh api repos/owner/repo/git/refs/tags/v1.0.0 --jq '.object.sha'
+```
+
+Always use full commit SHAs, not branch names. Branch links break when code changes. Permalinks don't.
+
+## Step 4: Cite Everything
+
+Every code-related claim needs a permalink. Format:
+
+```markdown
+The stale time check happens in [`notifyManager.ts`](https://github.com/TanStack/query/blob/abc123/packages/query-core/src/notifyManager.ts#L42-L50):
+
+\`\`\`typescript
+function isStale(query: Query, staleTime: number): boolean {
+  return query.state.dataUpdatedAt + staleTime < Date.now()
+}
+\`\`\`
+```
+
+For conceptual answers, link to official docs and relevant source files. For implementation answers, every function/class reference should have a permalink.
+
+## Video Analysis
+
+For questions about video tutorials, conference talks, or screen recordings:
+
+```typescript
+// Full extraction (transcript + visual descriptions)
+fetch_content({ url: "https://youtube.com/watch?v=abc" })
+
+// Ask a specific question about a video
+fetch_content({ url: "https://youtube.com/watch?v=abc", prompt: "What libraries are imported in this tutorial?" })
+
+// Single frame at a known moment
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41" })
+
+// Range scan for visual discovery
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00" })
+
+// Custom density across a range
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00", frames: 3 })
+
+// Whole-video sampling
+fetch_content({ url: "https://youtube.com/watch?v=abc", frames: 6 })
+
+// Analyze a local recording
+fetch_content({ url: "/path/to/demo.mp4", prompt: "What error message appears on screen?" })
+
+// Batch multiple videos with the same question
+fetch_content({
+  urls: ["https://youtube.com/watch?v=abc", "https://youtube.com/watch?v=def"],
+  prompt: "What packages are installed?"
+})
+```
+
+Use single timestamps for known moments, ranges for visual scanning, and frames-alone for a quick overview of the whole video.
+
+The `prompt` parameter only applies to video content (YouTube URLs and local video files). For non-video URLs, it's ignored.
+
+## Failure Recovery
+
+| Failure | Recovery |
+|---------|----------|
+| grep finds nothing | Broaden the query, try concept names instead of exact function names |
+| gh CLI rate limited | Use the already-cloned repo in /tmp/pi-github-repos/ for git operations |
+| Repo too large to clone | fetch_content returns an API-only view automatically; use that or add `forceClone: true` |
+| File not found in clone | Branch name with slashes may have misresolved; list the repo tree and navigate manually |
+| Uncertain about implementation | State your uncertainty explicitly, propose a hypothesis, show what evidence you did find |
+| Video extraction fails | Ensure Chrome is signed into gemini.google.com (free) or set GEMINI_API_KEY |
+| Page returns 403/bot block | Gemini fallback triggers automatically; no action needed if Gemini is configured |
+| web_search fails | Check provider config; try explicit `provider: "gemini"` if Perplexity key is missing |
+
+## Guidelines
+
+- Vary search queries when running multiple searches -- different angles, not the same pattern repeated
+- Prefer recent sources; filter out outdated results when they conflict with newer information
+- For version-specific questions, clone the tagged version: `fetch_content("https://github.com/owner/repo/tree/v1.0.0")`
+- When the repo is already cloned from a previous fetch_content call, reuse it -- check the path before cloning again
+- Answer directly. Skip preamble like "I'll help you with..." -- go straight to findings

package/utils.ts

@@ -0,0 +1,44 @@
+export function formatSeconds(s: number): string {
+	const h = Math.floor(s / 3600);
+	const m = Math.floor((s % 3600) / 60);
+	const sec = s % 60;
+	if (h > 0) return `${h}:${String(m).padStart(2, "0")}:${String(sec).padStart(2, "0")}`;
+	return `${m}:${String(sec).padStart(2, "0")}`;
+}
+
+export function readExecError(err: unknown): { code?: string; stderr: string; message: string } {
+	if (!err || typeof err !== "object") {
+		return { stderr: "", message: String(err) };
+	}
+	const code = (err as { code?: string }).code;
+	const message = (err as { message?: string }).message ?? "";
+	const stderrRaw = (err as { stderr?: Buffer | string }).stderr;
+	const stderr = Buffer.isBuffer(stderrRaw)
+		? stderrRaw.toString("utf-8")
+		: typeof stderrRaw === "string"
+			? stderrRaw
+			: "";
+	return { code, stderr, message };
+}
+
+export function isTimeoutError(err: unknown): boolean {
+	if (!err || typeof err !== "object") return false;
+	if ((err as { killed?: boolean }).killed) return true;
+	const name = (err as { name?: string }).name;
+	const code = (err as { code?: string }).code;
+	const message = (err as { message?: string }).message ?? "";
+	return name === "AbortError" || code === "ETIMEDOUT" || message.toLowerCase().includes("timed out");
+}
+
+export function trimErrorText(text: string): string {
+	return text.replace(/\s+/g, " ").trim().slice(0, 200);
+}
+
+export function mapFfmpegError(err: unknown): string {
+	const { code, stderr, message } = readExecError(err);
+	if (code === "ENOENT") return "ffmpeg is not installed. Install with: brew install ffmpeg";
+	if (isTimeoutError(err)) return "ffmpeg timed out extracting frame";
+	if (stderr.includes("403")) return "Stream URL returned 403 — may have expired, try again";
+	const snippet = trimErrorText(stderr || message);
+	return snippet ? `ffmpeg failed: ${snippet}` : "ffmpeg failed";
+}