@ibeex/pi-fetch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ibeex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# @ibeex/pi-fetch
+
+Installable pi package that adds a `/fetch` slash command.
+
+Published package name: `@ibeex/pi-fetch`
+
+Repository: https://github.com/ibeex/pi-fetch
+
+`/fetch` retrieves web content and injects it into pi's session context so the next prompt can use it.
+
+## Features
+
+- `/fetch <url>` only
+- uses `jina` for normal public URLs and `raw` for localhost, private-network, and other likely local URLs
+- retries Jina once with auth on 401/429/auth-required style responses
+- loads Jina API key from `JINA_API_KEY`, `JINA_API_TOKEN`, or `pass api/jina`
+- supports site-specific cleanup before truncation
+- currently cleans Hacker News item pages so the model sees story metadata + comment text instead of repetitive UI noise
+- shows a live footer status while fetching
+- shows a visible fetch result row in chat; expand it with `Ctrl+O` to inspect what was captured
+- truncates fetched content before injecting it into context
+- when truncation happens, only the first `PI_FETCH_MAX_CONTEXT_CHARS` chars are added to context and the full fetched response is saved to a temp file
+- default fetch context limit is `28000` chars, roughly `~7k` tokens for normal English text
+- stores fetched content as a hidden custom session message, so it is available to the model without cluttering chat
+
+## Install
+
+Because this repo now has a `package.json` with a `pi` manifest, you can install it as a pi package.
+
+### Install from npm
+
+```bash
+pi install npm:@ibeex/pi-fetch
+```
+
+### Clone the repository
+
+```bash
+git clone git@github.com:ibeex/pi-fetch.git
+cd pi-fetch
+```
+
+### Install globally
+
+```bash
+pi install /absolute/path/to/pi-fetch
+```
+
+### Install into another project
+
+From the target project directory:
+
+```bash
+pi install /absolute/path/to/pi-fetch -l
+```
+
+Then start pi in that project, or run:
+
+```text
+/reload
+```
+
+## Quick test without installing
+
+From outside this repo:
+
+```bash
+pi -e /absolute/path/to/pi-fetch
+```
+
+If you test from inside this repo and already have another copy of `@ibeex/pi-fetch` auto-loaded, disable extension auto-discovery to avoid duplicate `/fetch` commands:
+
+```bash
+pi --no-extensions -e .
+```
+
+Or load the raw extension file directly:
+
+```bash
+pi --no-extensions -e ./index.ts
+```
+
+## Usage
+
+```text
+/fetch https://example.com/docs
+/fetch http://localhost:3000/health
+```
+
+After `/fetch`, ask a normal question in the next prompt, for example:
+
+```text
+/fetch https://example.com/docs
+What are the main points from that page?
+```
+
+In interactive mode, `/fetch` also shows:
+
+- a temporary footer spinner while the request is running
+- a visible result row after completion
+- a short collapsed preview of the captured content
+- expandable details with `Ctrl+O`, including the exact content that was injected into context
+
+## Jina auth
+
+Lookup order:
+
+1. `JINA_API_KEY`
+2. `JINA_API_TOKEN`
+3. `pass api/jina`
+
+Example:
+
+```bash
+pass insert api/jina
+```
+
+## Optional env vars
+
+- `PI_FETCH_TIMEOUT_MS` default `30000`
+- `PI_FETCH_MAX_CONTEXT_CHARS` default `28000` (roughly `~7k` tokens)
+- `PI_FETCH_JINA_PASS_PATH` default `api/jina`
+
+## Notes
+
+- This is intentionally slash-command based, not an LLM tool.
+- `/fetch` adds context for the next prompt; it does not automatically ask the model a follow-up question.
+- `PI_FETCH_MAX_CONTEXT_CHARS` only affects fetched-page context from this extension.
+- `truncated` means the fetched response was larger than `PI_FETCH_MAX_CONTEXT_CHARS`, so only the first chunk was injected into model context.
+- If truncated, the visible result row shows how many chars were kept vs omitted, and expanded details show the temp file path for the full response.
+- The visible fetch result row is filtered out of model context; only the hidden fetched-content message is sent to the model.
+- Jina reader is used only for public web URLs. Localhost, private-network, and other likely local URLs use raw fetch automatically.

package/cleaners/hacker-news.ts

@@ -0,0 +1,264 @@
+import type { ContentCleaner } from "./index.ts";
+
+const HN_URL_PATTERN = String.raw`https?:\/\/news\.ycombinator\.com`;
+const HN_VOTE_LINK_RE = new RegExp(String.raw`${HN_URL_PATTERN}\/vote\?id=`);
+const HN_ITEM_LINK_RE = new RegExp(String.raw`\[(?<count>\d+\s+comments?)\]\(${HN_URL_PATTERN}\/item\?id=\d+[^)]*\)`);
+const HN_COMMENT_HEADER_RE = new RegExp(
+	String.raw`^\[(?<user>[^\]]+)\]\(${HN_URL_PATTERN}\/user\?id=[^)]+\)\[(?<age>[^\]]+)\]\(${HN_URL_PATTERN}\/item\?id=\d+[^)]*\)(?<tail>[\s\S]*)$`,
+);
+const HN_SEGMENT_SPLIT_RE = new RegExp(
+	String.raw`(?:!?\[Image \d+\]\(${HN_URL_PATTERN}\/s\.gif\))?\[\]\(${HN_URL_PATTERN}\/vote\?id=`,
+);
+const HN_PLAIN_STATS_RE =
+	/^(?<points>\d+\s+points?)\s+by\s+(?<submitter>\S+)\s+(?<age>.+?)\s+\|\s+.*?(?<comments>\d+\s+comments?)\s*$/;
+const HN_PLAIN_COMMENT_HEADER_RE = /^(?<user>\S+)\s+(?<age>.+?\bago)\s+\|\s+.+\[[^\]]+\]$/;
+
+function simplifyMarkdownText(value: string): string {
+	let cleaned = value;
+	cleaned = cleaned.replace(/!?\[Image \d+\]\([^)]*\)/g, "");
+	cleaned = cleaned.replace(/\[\[[^\]]*\]\]\(javascript:void\(0\)\)/g, "");
+	cleaned = cleaned.replace(/\[\]\([^)]*\)/g, "");
+
+	for (const label of ["reply", "parent", "next", "prev", "root", "hide", "favorite", "past", "help", "login"]) {
+		cleaned = cleaned.replace(new RegExp(`\\[${label}\\]\\([^)]+\\)`, "gi"), "");
+	}
+
+	cleaned = cleaned.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_match, label: string) => {
+		const text = label.trim();
+		if (!text) {
+			return "";
+		}
+		if (/^https?:\/\//i.test(text)) {
+			return text;
+		}
+		return text;
+	});
+
+	cleaned = cleaned.replace(/\s+\|\s+/g, " • ");
+	cleaned = cleaned.replace(/(?:\s*•\s*){2,}/g, " • ");
+	cleaned = cleaned.replace(/[ \t]{2,}/g, " ");
+	cleaned = cleaned.replace(/\n{3,}/g, "\n\n");
+	return cleaned.trim();
+}
+
+function formatStoryHeader(segment: string): string[] {
+	let rest = segment;
+	const lines = ["Hacker News discussion"];
+
+	const titleMatch = rest.match(/^\[(?<title>[^\]]+)\]\((?<link>[^)]+)\)(?<tail>[\s\S]*)$/);
+	if (titleMatch?.groups) {
+		lines.push("", `Title: ${titleMatch.groups.title}`, `Article: ${titleMatch.groups.link}`);
+		rest = titleMatch.groups.tail;
+	}
+
+	const siteMatch = rest.match(/^\s*\(\[(?<site>[^\]]+)\]\([^)]+\)\)(?<tail>[\s\S]*)$/);
+	if (siteMatch?.groups) {
+		lines.push(`Site: ${siteMatch.groups.site}`);
+		rest = siteMatch.groups.tail;
+	}
+
+	const statsMatch = rest.match(
+		/(?<points>\d+\s+points?)\s+by\s+\[(?<submitter>[^\]]+)\]\([^)]+\)\[(?<age>[^\]]+)\]\([^)]+\)/,
+	);
+	if (statsMatch?.groups) {
+		lines.push(`Points: ${statsMatch.groups.points}`);
+		lines.push(`Submitter: ${statsMatch.groups.submitter}`);
+		lines.push(`Posted: ${statsMatch.groups.age}`);
+	}
+
+	const commentsMatch = rest.match(HN_ITEM_LINK_RE);
+	if (commentsMatch?.groups) {
+		lines.push(`Comments: ${commentsMatch.groups.count}`);
+	}
+
+	let extraLinks = simplifyMarkdownText(rest);
+	extraLinks = extraLinks.replace(/^.*?\d+\s+points?\s+by\s+.+?comments/i, "").trim();
+	extraLinks = extraLinks.replace(/^•\s*/, "").trim();
+	if (extraLinks) {
+		lines.push("", `Links: ${extraLinks}`);
+	}
+
+	return lines;
+}
+
+function extractPageTitle(lines: string[]): string | undefined {
+	const titleLine = lines.find((line) => line.startsWith("Title: "));
+	if (!titleLine) {
+		return undefined;
+	}
+	const title = titleLine.slice("Title: ".length).replace(/\s+\|\s+Hacker News$/i, "").trim();
+	return title || undefined;
+}
+
+function looksLikeStoryHeader(segment: string): boolean {
+	return /^\[[^\]]+\]\([^)]+\)/.test(segment) || /\d+\s+points?\s+by\s+\[/.test(segment) || HN_ITEM_LINK_RE.test(segment);
+}
+
+function formatComment(segment: string, index: number): string | undefined {
+	const commentMatch = segment.match(HN_COMMENT_HEADER_RE);
+	if (!commentMatch?.groups) {
+		const fallback = simplifyMarkdownText(segment);
+		return fallback ? `${index}. ${fallback}` : undefined;
+	}
+
+	let body = commentMatch.groups.tail;
+	body = body.replace(/^(?:\s*\|\s*\[(?:parent|next|prev|root)\]\([^)]+\))+/gi, "");
+	body = body.replace(/^\s*\[\[[^\]]*\]\]\(javascript:void\(0\)\)\s*/i, "");
+	body = simplifyMarkdownText(body).replace(/^•\s*/, "").trim();
+	if (!body) {
+		return undefined;
+	}
+
+	return `${index}. ${commentMatch.groups.user} — ${commentMatch.groups.age}\n${body}`;
+}
+
+function normalizePlainLine(line: string): string {
+	return line.replace(/\u00a0/g, " ").trim();
+}
+
+function collapsePlainTextParagraphs(lines: string[]): string {
+	const paragraphs: string[] = [];
+	let current: string[] = [];
+
+	for (const rawLine of lines) {
+		const line = normalizePlainLine(rawLine);
+		if (!line) {
+			if (current.length > 0) {
+				paragraphs.push(current.join(" "));
+				current = [];
+			}
+			continue;
+		}
+		current.push(line);
+	}
+
+	if (current.length > 0) {
+		paragraphs.push(current.join(" "));
+	}
+
+	return paragraphs.join("\n\n").trim();
+}
+
+function cleanPlainTextHackerNewsItemContent(lines: string[]): string | undefined {
+	const normalizedLines = lines.map(normalizePlainLine);
+	const statsIndex = normalizedLines.findIndex((line) => HN_PLAIN_STATS_RE.test(line));
+	if (statsIndex < 0) {
+		return undefined;
+	}
+
+	const statsMatch = normalizedLines[statsIndex].match(HN_PLAIN_STATS_RE);
+	if (!statsMatch?.groups) {
+		return undefined;
+	}
+
+	let titleLine = "";
+	for (let index = statsIndex - 1; index >= 0; index -= 1) {
+		const candidate = normalizedLines[index];
+		if (!candidate || /^#/.test(candidate) || /^Hacker News/i.test(candidate) || candidate === "help") {
+			continue;
+		}
+		titleLine = candidate;
+		break;
+	}
+
+	const output = ["Hacker News discussion"];
+	if (titleLine) {
+		const titleMatch = titleLine.match(/^(?<title>.+?)\s+\((?<site>[^()]+\.[^()]+)\)$/);
+		if (titleMatch?.groups) {
+			output.push("", `Title: ${titleMatch.groups.title}`, `Site: ${titleMatch.groups.site}`);
+		} else {
+			output.push("", `Title: ${titleLine}`);
+		}
+	}
+
+	output.push(`Points: ${statsMatch.groups.points}`);
+	output.push(`Submitter: ${statsMatch.groups.submitter}`);
+	output.push(`Posted: ${statsMatch.groups.age}`);
+	output.push(`Comments: ${statsMatch.groups.comments}`);
+
+	const comments: string[] = [];
+	for (let index = statsIndex + 1; index < normalizedLines.length; index += 1) {
+		const line = normalizedLines[index];
+		const commentMatch = line.match(HN_PLAIN_COMMENT_HEADER_RE);
+		if (!commentMatch?.groups) {
+			continue;
+		}
+
+		const bodyLines: string[] = [];
+		for (index += 1; index < normalizedLines.length; index += 1) {
+			const currentLine = normalizedLines[index];
+			if (!currentLine) {
+				bodyLines.push("");
+				continue;
+			}
+			if (currentLine === "reply") {
+				break;
+			}
+			if (/^Guidelines\b/i.test(currentLine)) {
+				index = normalizedLines.length;
+				break;
+			}
+			if (HN_PLAIN_COMMENT_HEADER_RE.test(currentLine)) {
+				index -= 1;
+				break;
+			}
+			bodyLines.push(currentLine);
+		}
+
+		const body = collapsePlainTextParagraphs(bodyLines);
+		if (!body) {
+			continue;
+		}
+
+		comments.push(`${comments.length + 1}. ${commentMatch.groups.user} — ${commentMatch.groups.age}\n${body}`);
+	}
+
+	if (comments.length > 0) {
+		output.push("", "Comments:", "", comments.join("\n\n"));
+	}
+
+	return output.join("\n").trim() || undefined;
+}
+
+function cleanHackerNewsItemContent(body: string): string {
+	const lines = body.split(/\r?\n/).map((line) => line.trimEnd());
+	const pageTitle = extractPageTitle(lines);
+	const markdownIndex = lines.findIndex((line) => line.trim() === "Markdown Content:");
+	const markdownLines = markdownIndex >= 0 ? lines.slice(markdownIndex + 1) : lines;
+	const discussionLine = markdownLines.find((line) => HN_VOTE_LINK_RE.test(line));
+	if (discussionLine) {
+		const segments = discussionLine
+			.split(HN_SEGMENT_SPLIT_RE)
+			.map((segment) => segment.replace(/^\d+&how=up&goto=[^)]*\)/, "").trim())
+			.filter(Boolean);
+		if (segments.length > 0) {
+			const hasStoryHeader = looksLikeStoryHeader(segments[0]);
+			const output = hasStoryHeader ? formatStoryHeader(segments[0]) : ["Hacker News discussion"];
+			if (!hasStoryHeader && pageTitle) {
+				output.push("", `Title: ${pageTitle}`);
+			}
+			const commentSegments = hasStoryHeader ? segments.slice(1) : segments;
+			const comments = commentSegments
+				.map((segment, index) => formatComment(segment, index + 1))
+				.filter((comment): comment is string => Boolean(comment));
+
+			if (comments.length > 0) {
+				output.push("", "Comments:", "", comments.join("\n\n"));
+			}
+
+			return output.join("\n").trim() || body;
+		}
+	}
+
+	return cleanPlainTextHackerNewsItemContent(markdownLines) || body;
+}
+
+export const hackerNewsCleaner: ContentCleaner = {
+	id: "hacker-news-item",
+	matches(url) {
+		return url.hostname === "news.ycombinator.com" && url.pathname === "/item";
+	},
+	clean(body) {
+		return cleanHackerNewsItemContent(body);
+	},
+};

package/cleaners/index.ts

@@ -0,0 +1,19 @@
+import { hackerNewsCleaner } from "./hacker-news.ts";
+
+export type ContentCleaner = {
+	id: string;
+	matches(url: URL): boolean;
+	clean(body: string): string;
+};
+
+const CLEANERS: ContentCleaner[] = [hackerNewsCleaner];
+
+export function cleanFetchedBody(url: string, body: string): string {
+	try {
+		const parsedUrl = new URL(url);
+		const cleaner = CLEANERS.find((candidate) => candidate.matches(parsedUrl));
+		return cleaner ? cleaner.clean(body) : body;
+	} catch {
+		return body;
+	}
+}

package/index.ts

@@ -0,0 +1,656 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { keyHint } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { execFile } from "node:child_process";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { isIP } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { cleanFetchedBody } from "./cleaners/index.ts";
+
+const execFileAsync = promisify(execFile);
+
+const JINA_READER_URL = "https://r.jina.ai/";
+const DEFAULT_USER_AGENT = "pi-fetch/0.1";
+const DEFAULT_TIMEOUT_MS = parsePositiveInt(process.env.PI_FETCH_TIMEOUT_MS, 30_000);
+const DEFAULT_MAX_CONTEXT_CHARS = parsePositiveInt(process.env.PI_FETCH_MAX_CONTEXT_CHARS, 28_000);
+const DEFAULT_PASS_PATH = process.env.PI_FETCH_JINA_PASS_PATH?.trim() || "api/jina";
+const CONTENT_TRUNCATED_MARKER = "[Content truncated for context]";
+const FETCH_CONTEXT_CUSTOM_TYPE = "pi-fetch-context";
+const FETCH_RESULT_CUSTOM_TYPE = "pi-fetch-result";
+const FETCH_STATUS_KEY = "pi-fetch";
+const FETCH_STATUS_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const FETCH_STATUS_TICK_MS = 80;
+type FetchMode = "auto" | "raw" | "jina";
+type FetchDelivery = "nextPrompt" | "afterCurrentRun";
+
+type FetchResult = {
+	url: string;
+	mode: Exclude<FetchMode, "auto">;
+	status: number;
+	contentType: string;
+	content: string;
+	truncated: boolean;
+	rawLength: number;
+	contextLength: number;
+	omittedLength: number;
+	fullOutputPath?: string;
+};
+
+type FetchDisplayDetails =
+	| {
+			ok: true;
+			delivery: FetchDelivery;
+			url: string;
+			mode: Exclude<FetchMode, "auto">;
+			status: number;
+			contentType: string;
+			truncated: boolean;
+			rawLength: number;
+			contextLength: number;
+			omittedLength: number;
+			contextContent: string;
+			fullOutputPath?: string;
+	  }
+	| {
+			ok: false;
+			error: string;
+			url?: string;
+			mode?: Exclude<FetchMode, "auto">;
+	  };
+
+class HttpStatusError extends Error {
+	status: number;
+	detail: string;
+
+	constructor(status: number, statusText: string, detail: string) {
+		super(detail ? `HTTP ${status} ${statusText}: ${detail}` : `HTTP ${status} ${statusText}`);
+		this.name = "HttpStatusError";
+		this.status = status;
+		this.detail = detail;
+	}
+}
+
+function parsePositiveInt(raw: string | undefined, fallback: number): number {
+	const value = Number.parseInt(raw ?? "", 10);
+	if (!Number.isFinite(value) || value <= 0) {
+		return fallback;
+	}
+	return value;
+}
+
+function formatCount(value: number): string {
+	return new Intl.NumberFormat("en-US").format(value);
+}
+
+function shortenUrl(value: string, maxLength = 96): string {
+	if (value.length <= maxLength) {
+		return value;
+	}
+	const separator = "...";
+	const available = maxLength - separator.length;
+	const head = Math.ceil(available / 2);
+	const tail = Math.floor(available / 2);
+	return `${value.slice(0, head)}${separator}${value.slice(-tail)}`;
+}
+
+function truncateForContext(
+	text: string,
+	limit: number,
+): { content: string; truncated: boolean; contextLength: number; omittedLength: number } {
+	const normalized = text.trim() || "(empty response body)";
+	if (normalized.length <= limit) {
+		return { content: normalized, truncated: false, contextLength: normalized.length, omittedLength: 0 };
+	}
+	const content = normalized.slice(0, limit).trimEnd();
+	return {
+		content: `${content}\n${CONTENT_TRUNCATED_MARKER}`,
+		truncated: true,
+		contextLength: content.length,
+		omittedLength: normalized.length - content.length,
+	};
+}
+
+function preprocessFetchedBody(url: string, body: string): string {
+	return cleanFetchedBody(url, body);
+}
+
+function stripWrappingQuotes(value: string): string {
+	const trimmed = value.trim();
+	if (trimmed.length >= 2) {
+		const first = trimmed[0];
+		const last = trimmed[trimmed.length - 1];
+		if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+			return trimmed.slice(1, -1).trim();
+		}
+	}
+	return trimmed;
+}
+
+function validateUrl(value: string): string {
+	const candidate = stripWrappingQuotes(value);
+	if (!candidate) {
+		throw new Error("URL must not be empty.");
+	}
+	const parsed = new URL(candidate);
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+		throw new Error("URL must start with http:// or https://.");
+	}
+	if (!parsed.hostname) {
+		throw new Error("URL must include a hostname.");
+	}
+	return parsed.toString();
+}
+
+function normalizeHostname(hostname: string): string {
+	const trimmed = hostname.trim().toLowerCase();
+	const withoutBrackets =
+		trimmed.startsWith("[") && trimmed.endsWith("]") ? trimmed.slice(1, -1) : trimmed;
+	return withoutBrackets.endsWith(".") ? withoutBrackets.slice(0, -1) : withoutBrackets;
+}
+
+function isPrivateIpv4(hostname: string): boolean {
+	const parts = hostname.split(".").map((part) => Number.parseInt(part, 10));
+	if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
+		return false;
+	}
+
+	const [a, b] = parts;
+	return (
+		a === 0 ||
+		a === 10 ||
+		a === 127 ||
+		(a === 169 && b === 254) ||
+		(a === 172 && b >= 16 && b <= 31) ||
+		(a === 192 && b === 168)
+	);
+}
+
+function isPrivateIpv6(hostname: string): boolean {
+	return (
+		hostname === "::" ||
+		hostname === "::1" ||
+		hostname.startsWith("fc") ||
+		hostname.startsWith("fd") ||
+		hostname.startsWith("fe80:")
+	);
+}
+
+function isLikelyPrivateHostname(hostname: string): boolean {
+	if (!hostname) {
+		return false;
+	}
+
+	if (hostname === "localhost" || hostname.endsWith(".localhost") || hostname.endsWith(".local")) {
+		return true;
+	}
+
+	const ipVersion = isIP(hostname);
+	if (ipVersion === 4) {
+		return isPrivateIpv4(hostname);
+	}
+	if (ipVersion === 6) {
+		return isPrivateIpv6(hostname);
+	}
+
+	return !hostname.includes(".");
+}
+
+function isLocalUrl(value: string): boolean {
+	const hostname = normalizeHostname(new URL(value).hostname);
+	return isLikelyPrivateHostname(hostname);
+}
+
+function resolveMode(url: string, mode: FetchMode): Exclude<FetchMode, "auto"> {
+	if (mode === "raw" || mode === "jina") {
+		return mode;
+	}
+	return isLocalUrl(url) ? "raw" : "jina";
+}
+
+function shouldRetryWithJinaApiKey(status: number, detail: string): boolean {
+	const normalized = detail.toLowerCase();
+	return (
+		status === 401 ||
+		status === 403 ||
+		status === 429 ||
+		normalized.includes("rate limit") ||
+		normalized.includes("too many requests") ||
+		normalized.includes("authentication is required") ||
+		normalized.includes("authenticationrequirederror") ||
+		normalized.includes("provide a valid api key") ||
+		normalized.includes("authorization header")
+	);
+}
+
+function describeDelivery(delivery: FetchDelivery): string {
+	return delivery === "nextPrompt"
+		? "Available to the model in your next prompt."
+		: "Will be added after the current run finishes.";
+}
+
+function formatAddedNotice(result: FetchResult): string {
+	if (!result.truncated) {
+		return `Fetched ${result.url} via ${result.mode} and added ${formatCount(result.contextLength)} chars to context.`;
+	}
+	return `Fetched ${result.url} via ${result.mode}. Retrieved ${formatCount(result.rawLength)} chars; kept ${formatCount(result.contextLength)} chars in context and omitted ${formatCount(result.omittedLength)}.`;
+}
+
+function parseCommandArgs(args: string): string {
+	const trimmed = args.trim();
+	if (!trimmed) {
+		throw new Error("Usage: /fetch <url>");
+	}
+	return validateUrl(trimmed);
+}
+
+function buildContextMessage(result: FetchResult): string {
+	const lines = [
+		"Fetched web content explicitly requested by the user:",
+		`URL: ${result.url}`,
+		`Mode: ${result.mode}`,
+		`Status: ${result.status}`,
+		`Content-Type: ${result.contentType}`,
+		`Raw-Length: ${result.rawLength}`,
+		`Context-Length: ${result.contextLength}`,
+		`Omitted-Length: ${result.omittedLength}`,
+	];
+	if (result.fullOutputPath) {
+		lines.push(`Full-Response-Path: ${result.fullOutputPath}`);
+	}
+	lines.push("", result.content);
+	return lines.join("\n");
+}
+
+function queueFetchedContext(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	result: FetchResult,
+): FetchDelivery {
+	const delivery: FetchDelivery = ctx.isIdle() ? "nextPrompt" : "afterCurrentRun";
+	const message = {
+		customType: FETCH_CONTEXT_CUSTOM_TYPE,
+		content: buildContextMessage(result),
+		display: false,
+		details: {
+			url: result.url,
+			mode: result.mode,
+			status: result.status,
+			contentType: result.contentType,
+			truncated: result.truncated,
+			rawLength: result.rawLength,
+			contextLength: result.contextLength,
+			omittedLength: result.omittedLength,
+			fullOutputPath: result.fullOutputPath,
+		},
+	};
+
+	if (ctx.isIdle()) {
+		pi.sendMessage(message);
+		return delivery;
+	}
+
+	pi.sendMessage(message, { deliverAs: "followUp" });
+	return delivery;
+}
+
+function sendFetchResultMessage(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	result: FetchResult,
+	delivery: FetchDelivery,
+): void {
+	const details: FetchDisplayDetails = {
+		ok: true,
+		delivery,
+		url: result.url,
+		mode: result.mode,
+		status: result.status,
+		contentType: result.contentType,
+		truncated: result.truncated,
+		rawLength: result.rawLength,
+		contextLength: result.contextLength,
+		omittedLength: result.omittedLength,
+		contextContent: result.content,
+		fullOutputPath: result.fullOutputPath,
+	};
+	const message = {
+		customType: FETCH_RESULT_CUSTOM_TYPE,
+		content: formatAddedNotice(result),
+		display: true,
+		details,
+	};
+
+	if (ctx.isIdle()) {
+		pi.sendMessage(message);
+		return;
+	}
+
+	pi.sendMessage(message, { deliverAs: "steer" });
+}
+
+function sendFetchFailureMessage(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	error: string,
+	url?: string,
+	mode?: Exclude<FetchMode, "auto">,
+): void {
+	const prefix = url ? `Fetch failed for ${url}` : "Fetch failed";
+	const details: FetchDisplayDetails = {
+		ok: false,
+		error,
+		url,
+		mode,
+	};
+	const message = {
+		customType: FETCH_RESULT_CUSTOM_TYPE,
+		content: `${prefix}: ${error}`,
+		display: true,
+		details,
+	};
+
+	if (ctx.isIdle()) {
+		pi.sendMessage(message);
+		return;
+	}
+
+	pi.sendMessage(message, { deliverAs: "steer" });
+}
+
+function startFetchStatus(
+	ctx: ExtensionCommandContext,
+	url: string,
+	mode: Exclude<FetchMode, "auto">,
+): () => void {
+	if (!ctx.hasUI) {
+		return () => {};
+	}
+
+	let frame = 0;
+	const render = () => {
+		const spinner = ctx.ui.theme.fg("accent", FETCH_STATUS_FRAMES[frame % FETCH_STATUS_FRAMES.length]!);
+		const label = ctx.ui.theme.fg("dim", ` Fetching ${shortenUrl(url, 72)} via ${mode}...`);
+		ctx.ui.setStatus(FETCH_STATUS_KEY, spinner + label);
+		frame++;
+	};
+
+	render();
+	const timer = setInterval(render, FETCH_STATUS_TICK_MS);
+
+	return () => {
+		clearInterval(timer);
+		ctx.ui.setStatus(FETCH_STATUS_KEY, undefined);
+	};
+}
+
+function buildPreview(content: string, maxLines = 3, maxCharsPerLine = 100): { text: string; clipped: boolean } {
+	const normalized = content.replace(`\n${CONTENT_TRUNCATED_MARKER}`, "").trim();
+	if (!normalized) {
+		return { text: "(empty response body)", clipped: false };
+	}
+
+	const sourceLines = normalized
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter(Boolean);
+	const previewLines = sourceLines.slice(0, maxLines).map((line) => {
+		if (line.length <= maxCharsPerLine) {
+			return line;
+		}
+		return `${line.slice(0, maxCharsPerLine).trimEnd()}…`;
+	});
+	const clipped =
+		sourceLines.length > previewLines.length || previewLines.some((line, index) => line !== sourceLines[index]);
+	return { text: previewLines.join("\n"), clipped };
+}
+
+function renderFetchResult(message: { content: string; details?: unknown }, expanded: boolean, theme: any): Text {
+	const details = message.details as FetchDisplayDetails | undefined;
+	if (!details) {
+		return new Text(message.content, 0, 0);
+	}
+
+	if (!details.ok) {
+		let text = theme.fg("error", "✗ fetch failed");
+		if (details.url) {
+			text += "\n" + theme.fg("muted", shortenUrl(details.url));
+		}
+		if (details.mode) {
+			text += "\n" + theme.fg("dim", `Mode: ${details.mode}`);
+		}
+		text += "\n" + theme.fg("error", details.error);
+		return new Text(text, 0, 0);
+	}
+
+	let text = theme.fg("success", "✓ ") + theme.fg("accent", "fetch ") + theme.fg("muted", shortenUrl(details.url));
+	text += "\n" + theme.fg("dim", `via ${details.mode} • HTTP ${details.status} • ${details.contentType}`);
+
+	if (details.truncated) {
+		text +=
+			"\n" +
+			theme.fg(
+				"warning",
+				`${formatCount(details.contextLength)} of ${formatCount(details.rawLength)} chars were added to context (${formatCount(details.omittedLength)} omitted)`,
+			);
+	} else {
+		text += "\n" + theme.fg("success", `${formatCount(details.contextLength)} chars added to context`);
+	}
+
+	text += "\n" + theme.fg("muted", describeDelivery(details.delivery));
+
+	if (!expanded) {
+		const preview = buildPreview(details.contextContent);
+		text += "\n\n" + theme.fg("dim", preview.text);
+		if (preview.clipped || details.truncated) {
+			text += "\n" + theme.fg("dim", "…");
+		}
+		text += "\n" + theme.fg("muted", `(${keyHint("app.tools.expand", "to inspect captured content")})`);
+		return new Text(text, 0, 0);
+	}
+
+	if (details.truncated) {
+		text +=
+			"\n\n" +
+			theme.fg(
+				"warning",
+				`Only the first ${formatCount(details.contextLength)} chars below were injected into model context.`,
+			);
+	}
+
+	if (details.fullOutputPath) {
+		text += "\n" + theme.fg("muted", `Full response saved to: ${details.fullOutputPath}`);
+	}
+
+	text += "\n\n" + theme.fg("accent", theme.bold("Captured context content"));
+	text += `\n${details.contextContent}`;
+	return new Text(text, 0, 0);
+}
+
+async function getJinaApiKey(): Promise<string> {
+	const envKey = process.env.JINA_API_KEY?.trim() || process.env.JINA_API_TOKEN?.trim();
+	if (envKey) {
+		return envKey;
+	}
+
+	try {
+		const result = await execFileAsync("pass", [DEFAULT_PASS_PATH]);
+		const lines = result.stdout
+			.split(/\r?\n/)
+			.map((line) => line.trim())
+			.filter(Boolean);
+		if (lines.length === 0) {
+			throw new Error(`pass ${DEFAULT_PASS_PATH} returned no secret.`);
+		}
+		return lines[0];
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(
+			`Jina API key not available. Set JINA_API_KEY or store it in pass at ${DEFAULT_PASS_PATH}. (${message})`,
+		);
+	}
+}
+
+async function persistFullOutput(text: string): Promise<string> {
+	const directory = await mkdtemp(join(tmpdir(), "pi-fetch-"));
+	const filePath = join(directory, "response.txt");
+	await writeFile(filePath, text, "utf8");
+	return filePath;
+}
+
+async function fetchText(url: string, init: RequestInit, timeoutMs: number): Promise<{ response: Response; body: string }> {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetch(url, {
+			...init,
+			signal: controller.signal,
+		});
+		const body = (await response.text()).trim() || "(empty response body)";
+		return { response, body };
+	} catch (error) {
+		if (error instanceof Error && error.name === "AbortError") {
+			throw new Error(`Request timed out after ${timeoutMs}ms.`);
+		}
+		throw error;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+async function runRawRequest(url: string, timeoutMs: number, maxContextChars: number): Promise<FetchResult> {
+	const { response, body } = await fetchText(
+		url,
+		{
+			headers: {
+				"user-agent": DEFAULT_USER_AGENT,
+				accept: "text/plain,text/html,application/json,application/xml;q=0.9,*/*;q=0.8",
+				"accept-language": "en-US,en;q=0.9",
+			},
+		},
+		timeoutMs,
+	);
+	if (!response.ok) {
+		throw new HttpStatusError(response.status, response.statusText, body);
+	}
+	const processedBody = preprocessFetchedBody(url, body);
+	const truncated = truncateForContext(processedBody, maxContextChars);
+	const fullOutputPath = truncated.truncated ? await persistFullOutput(processedBody) : undefined;
+	return {
+		url,
+		mode: "raw",
+		status: response.status,
+		contentType: response.headers.get("content-type") || "unknown",
+		content: truncated.content,
+		truncated: truncated.truncated,
+		rawLength: processedBody.length,
+		contextLength: truncated.contextLength,
+		omittedLength: truncated.omittedLength,
+		fullOutputPath,
+	};
+}
+
+async function runJinaRequest(
+	url: string,
+	timeoutMs: number,
+	maxContextChars: number,
+	apiKey?: string,
+): Promise<FetchResult> {
+	const headers: Record<string, string> = {
+		"user-agent": DEFAULT_USER_AGENT,
+		accept: "text/plain",
+		"accept-language": "en-US,en;q=0.9",
+	};
+	if (apiKey) {
+		headers.authorization = `Bearer ${apiKey}`;
+	}
+
+	const { response, body } = await fetchText(`${JINA_READER_URL}${url}`, { headers }, timeoutMs);
+	if (!response.ok) {
+		throw new HttpStatusError(response.status, response.statusText, body);
+	}
+
+	const processedBody = preprocessFetchedBody(url, body);
+	const truncated = truncateForContext(processedBody, maxContextChars);
+	const fullOutputPath = truncated.truncated ? await persistFullOutput(processedBody) : undefined;
+	return {
+		url,
+		mode: "jina",
+		status: response.status,
+		contentType: response.headers.get("content-type") || "text/plain",
+		content: truncated.content,
+		truncated: truncated.truncated,
+		rawLength: processedBody.length,
+		contextLength: truncated.contextLength,
+		omittedLength: truncated.omittedLength,
+		fullOutputPath,
+	};
+}
+
+async function fetchUrl(
+	url: string,
+	mode: FetchMode,
+	timeoutMs: number,
+	maxContextChars: number,
+): Promise<FetchResult> {
+	const resolvedMode = resolveMode(url, mode);
+	if (resolvedMode === "raw") {
+		return runRawRequest(url, timeoutMs, maxContextChars);
+	}
+
+	try {
+		return await runJinaRequest(url, timeoutMs, maxContextChars);
+	} catch (error) {
+		if (!(error instanceof HttpStatusError) || !shouldRetryWithJinaApiKey(error.status, error.detail)) {
+			throw error;
+		}
+		const apiKey = await getJinaApiKey();
+		return runJinaRequest(url, timeoutMs, maxContextChars, apiKey);
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("context", async (event) => {
+		return {
+			messages: event.messages.filter(
+				(message) => (message as { customType?: string }).customType !== FETCH_RESULT_CUSTOM_TYPE,
+			),
+		};
+	});
+
+	pi.registerMessageRenderer(FETCH_RESULT_CUSTOM_TYPE, (message, options, theme) => {
+		return renderFetchResult(message as { content: string; details?: unknown }, options.expanded, theme);
+	});
+
+	pi.registerCommand("fetch", {
+		description: "Fetch a URL and add the content to session context for the next prompt",
+		handler: async (args, ctx) => {
+			let url: string | undefined;
+			let mode: Exclude<FetchMode, "auto"> | undefined;
+			let stopStatus = () => {};
+
+			try {
+				url = parseCommandArgs(args);
+				mode = resolveMode(url, "auto");
+				stopStatus = startFetchStatus(ctx, url, mode);
+
+				const result = await fetchUrl(url, "auto", DEFAULT_TIMEOUT_MS, DEFAULT_MAX_CONTEXT_CHARS);
+				const delivery = queueFetchedContext(pi, ctx, result);
+				sendFetchResultMessage(pi, ctx, result, delivery);
+
+				if (ctx.hasUI && delivery === "afterCurrentRun") {
+					ctx.ui.notify(`${formatAddedNotice(result)} It will be appended after the current run finishes.`, "info");
+				}
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				sendFetchFailureMessage(pi, ctx, message, url, mode);
+				if (ctx.hasUI && !ctx.isIdle()) {
+					ctx.ui.notify(`Fetch failed: ${message}`, "warning");
+				}
+			} finally {
+				stopStatus();
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ibeex/pi-fetch",
+  "version": "0.1.0",
+  "description": "pi extension that fetches web content into session context with Jina/raw fallback and cleaned previews",
+  "type": "module",
+  "keywords": ["pi-package"],
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:ibeex/pi-fetch.git"
+  },
+  "homepage": "https://github.com/ibeex/pi-fetch",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build'",
+    "check": "echo 'nothing to check'"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  }
+}