omnirush 0.5.3 → 0.5.4

package/assets/extensions/omnirush/collector.ts

@@ -41,11 +41,17 @@ export default function (pi: any) {
   const origin = resolveOrigin(process.env);
   const accessToken =
     (process.env.OMNIRUSH_ACCESS_TOKEN || process.env.OMNIRUSH_TOKEN || "").trim();
+  // Linked/child mode (spawn_agents): the env var names the parent
+  // session. This collector then ships only trace events + this
+  // session's own transcript artifact (parent_session_id stamped) —
+  // never a second workspace baseline for the same tree.
+  const linkedParentSession = (process.env.OMNIRUSH_PARENT_SESSION || "").trim() || undefined;
   const collector = new WorkspaceCollector({
     gatewayUrl: process.env.OMNIRUSH_GATEWAY_URL || gatewayUrlForOrigin(origin),
     accessToken,
     stateDir: omniDir(),
     agentDir: piAgentDir(),
+    linkedParentSession,
     clientId: (os.hostname() || "unknown").split(/[.\\s]/)[0].slice(0, 64) || null,
     identityProvider:
       accessToken
@@ -123,6 +129,13 @@ export default function (pi: any) {
 
   pi.on("turn_end", (event: any) => {
     collector.recordTrace(sessionId, "turn.end", { turn_index: event?.turnIndex });
+    // Per-turn trace flush: a complete valid trace artifact (lifecycle
+    // events + transcript messages-so-far) ships after EVERY completed
+    // turn on the priority lane, instead of waiting for the 2,000-event
+    // relief threshold or shutdown. An interrupted process therefore
+    // still leaves every turn it finished behind, and the artifacts
+    // never queue behind a multi-part workspace baseline.
+    collector.flushTrace(sessionId);
   });
 
   pi.on("tool_execution_start", (event: any) => {
@@ -167,14 +180,18 @@ export default function (pi: any) {
       }),
     ]);
     // Flush buffered stdout (the reply) before the hard exit — bun
-    // buffers pipe writes and process.exit would drop them.
+    // buffers pipe writes and process.exit would drop them. Bun needs
+    // the explicit flush() (the empty-write callback from the previous
+    // attempt fired immediately and the exit still ate the reply); a
+    // short grace covers runtimes without flush().
+    try {
+      (process.stdout as any).flush?.();
+    } catch {
+      /* non-bun runtime */
+    }
     await new Promise((resolve) => {
-      const fallback = setTimeout(resolve, 2_000);
-      fallback.unref?.();
-      process.stdout.write("", () => {
-        clearTimeout(fallback);
-        resolve();
-      });
+      const grace = setTimeout(resolve, 250);
+      grace.unref?.();
     });
     process.exit(0);
   });

package/assets/extensions/omnirush/index.ts

@@ -12,6 +12,9 @@ import commands from "./commands";
 import mcp from "./mcp";
 import recorder from "./recorder";
 import sota from "./sota";
+import agents from "./agents";
+import plan from "./plan";
+import webfetch from "./webfetch";
 
 export default function (pi: ExtensionAPI) {
   commands(pi as any);
@@ -19,4 +22,7 @@ export default function (pi: ExtensionAPI) {
   sota(pi as any);
   collector(pi as any);
   mcp(pi as any);
+  webfetch(pi as any);
+  plan(pi as any);
+  agents(pi as any);
 }

package/assets/extensions/omnirush/plan-lib.ts

@@ -0,0 +1,113 @@
+// plan-lib — pure plan/todo logic for the `plan` tool (codex
+// update_plan parity): an ordered task list with pending / in-progress
+// / done statuses. Pure + injectable so node:test covers it directly.
+
+export const PLAN_STATUSES = ["pending", "in-progress", "done"] as const;
+export type PlanStatus = (typeof PLAN_STATUSES)[number];
+
+export interface PlanItem {
+  title: string;
+  status: PlanStatus;
+}
+
+/** Shape persisted to `__agent__/plan.json` (ships in the workspace
+ *  trace, so buyers see how the agent structured the work). */
+export interface PlanFile {
+  schema_version: 1;
+  items: PlanItem[];
+  updated_at: string;
+}
+
+export const PLAN_MAX_ITEMS = 50;
+export const PLAN_TITLE_MAX = 500;
+
+/**
+ * Validate/normalize a raw items array (unknown in, e.g. model JSON):
+ * trims titles, drops empties, enforces status vocabulary and caps.
+ * Returns null when the input is not a usable plan (caller turns that
+ * into a tool error).
+ */
+export function normalizePlanItems(input: unknown): PlanItem[] | null {
+  if (!Array.isArray(input)) return null;
+  const items: PlanItem[] = [];
+  for (const raw of input) {
+    if (items.length >= PLAN_MAX_ITEMS) break;
+    if (!raw || typeof raw !== "object") return null;
+    const record = raw as Record<string, unknown>;
+    if (typeof record.title !== "string") return null;
+    const title = record.title.trim().slice(0, PLAN_TITLE_MAX);
+    if (!title) return null;
+    const status = record.status ?? "pending";
+    if (typeof status !== "string" || !PLAN_STATUSES.includes(status as PlanStatus)) {
+      return null;
+    }
+    items.push({ title, status: status as PlanStatus });
+  }
+  if (items.length === 0) return null;
+  return items;
+}
+
+/** Progress counts: done/total plus the first in-progress title. */
+export function planProgress(items: PlanItem[]): {
+  done: number;
+  total: number;
+  current: string | null;
+} {
+  let done = 0;
+  let current: string | null = null;
+  for (const item of items) {
+    if (item.status === "done") done += 1;
+    else if (item.status === "in-progress" && current === null) current = item.title;
+  }
+  return { done, total: items.length, current };
+}
+
+function clip(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/**
+ * One-line footer for ctx.ui.setStatus, e.g.
+ *   "plan 2/5 · ▸ wire tests"
+ * or "plan 4/5 done". Null when there is nothing to show.
+ */
+export function renderPlanFooter(items: PlanItem[]): string | null {
+  if (!Array.isArray(items) || items.length === 0) return null;
+  const { done, total, current } = planProgress(items);
+  // The ▸ task is the in-progress one, falling back to the first
+  // not-done item (what is next up).
+  const pointed = current ?? items.find((item) => item.status !== "done")?.title ?? null;
+  if (pointed) return `plan ${done}/${total} · ▸ ${clip(pointed, 60)}`;
+  return `plan ${done}/${total} done`;
+}
+
+/**
+ * A multi-line text rendering for the tool RESULT (what the model
+ * reads): statuses as [ ] / [~] / [x], the current task flagged.
+ */
+export function renderPlanItems(items: PlanItem[]): string {
+  const lines = items.map((item) => {
+    const box = item.status === "done" ? "[x]" : item.status === "in-progress" ? "[~]" : "[ ]";
+    return `${box} ${item.title}`;
+  });
+  const { done, total } = planProgress(items);
+  return `${lines.join("\n")}\n\n${done}/${total} done`;
+}
+
+export function buildPlanFile(items: PlanItem[], updatedAt: string): PlanFile {
+  return { schema_version: 1, items, updated_at: updatedAt };
+}
+
+/** Parse a persisted plan.json, returning null on anything unusable. */
+export function parsePlanFile(text: string): PlanFile | null {
+  try {
+    const parsed = JSON.parse(text) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== "object" || parsed.schema_version !== 1) return null;
+    const items = normalizePlanItems(parsed.items);
+    if (!items) return null;
+    const updatedAt = typeof parsed.updated_at === "string" ? parsed.updated_at : "";
+    return { schema_version: 1, items, updated_at: updatedAt };
+  } catch {
+    return null;
+  }
+}

package/assets/extensions/omnirush/plan.ts

@@ -0,0 +1,136 @@
+// plan — a plan/todo custom tool (codex update_plan parity).
+//
+// The model maintains an ordered task list (items with pending /
+// in-progress / done statuses) while it works. Every update:
+//   - persists to <cwd>/__agent__/plan.json (the workspace collector
+//     ships it, so buyers see how the agent structured the work),
+//   - appends an `omnirush.plan` custom entry to the session JSONL —
+//     trace-format.ts carries those as additive `plan_records` on the
+//     trace artifact,
+//   - renders one line in the footer via ctx.ui.setStatus,
+//   - returns the full list as the tool result.
+//
+// Full-replace semantics (like codex update_plan): every call sends
+// the WHOLE list with current statuses.
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  buildPlanFile,
+  normalizePlanItems,
+  parsePlanFile,
+  planProgress,
+  renderPlanFooter,
+  renderPlanItems,
+  type PlanItem,
+} from "./plan-lib";
+
+const PLAN_TOOL_NAME = "plan";
+const PLAN_ENTRY_TYPE = "omnirush.plan";
+const PLAN_STATUS_KEY = "omnirush-plan";
+// Same directory the collector journals under — it ships with the
+// workspace trace. (Mirrors collector-lib's AGENT_DIR; kept local so
+// this module stays independent of the collector's implementation.)
+const AGENT_DIR = "__agent__";
+
+const PlanParams = Type.Object({
+  items: Type.Array(
+    Type.Object({
+      title: Type.String({ description: "Short task title (imperative, e.g. 'add failing test first')" }),
+      status: Type.Optional(StringEnum(["pending", "in-progress", "done"] as const, {
+        description: "Task status; defaults to pending. Exactly one item should be in-progress while working.",
+      })),
+    }),
+    { description: "The FULL ordered task list with current statuses (replaces the previous plan)" },
+  ),
+});
+
+export default function (pi: ExtensionAPI) {
+  /** Show the footer for a plan (or clear it when the plan is gone). */
+  const showFooter = (items: PlanItem[] | null, ctx: any) => {
+    try {
+      const line = items ? renderPlanFooter(items) : null;
+      ctx?.ui?.setStatus?.(PLAN_STATUS_KEY, line ?? undefined);
+    } catch {
+      /* non-TUI host */
+    }
+  };
+
+  pi.registerTool({
+    name: PLAN_TOOL_NAME,
+    label: "Plan",
+    description: [
+      "Maintain the ordered task list for the current work (todo list).",
+      "Send the FULL list with current statuses every time; keep exactly one item in-progress while working and mark items done as you complete them.",
+      "The list persists for the session and is visible to the user in the footer.",
+    ].join(" "),
+    promptSnippet: "plan: maintain an ordered task list (todo) with statuses",
+    promptGuidelines: [
+      "Use plan for multi-step work (3+ steps or user-requested tracking): send the full task list before starting, mark items done as you finish them, and keep exactly one item in-progress.",
+      "Do not use plan for single trivial actions.",
+    ],
+    parameters: PlanParams,
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const items = normalizePlanItems(params.items);
+      if (!items) {
+        throw new Error(
+          "invalid plan items: provide a non-empty array of {title, status} objects (status pending | in-progress | done)",
+        );
+      }
+      const updatedAt = new Date().toISOString();
+      const cwd = ctx?.cwd ? resolve(ctx.cwd) : process.cwd();
+      try {
+        const planPath = join(cwd, AGENT_DIR, "plan.json");
+        await mkdir(dirname(planPath), { recursive: true });
+        await writeFile(planPath, JSON.stringify(buildPlanFile(items, updatedAt), null, 2) + "\n", "utf8");
+      } catch {
+        // Persistence is best effort: the session entry + footer still
+        // carry the plan (and the tool result returns it).
+      }
+      try {
+        pi.appendEntry(PLAN_ENTRY_TYPE, { items, updated_at: updatedAt });
+      } catch {
+        /* sessions may be unavailable in some hosts */
+      }
+      showFooter(items, ctx);
+      const { done, total } = planProgress(items);
+      return {
+        content: [{ type: "text", text: renderPlanItems(items) }],
+        details: { done, total, items },
+      };
+    },
+  });
+
+  // Restore the footer after reload/resume: the session's latest plan
+  // entry wins, falling back to the persisted plan.json.
+  pi.on("session_start", async (_event: any, ctx: any) => {
+    try {
+      let items: PlanItem[] | null = null;
+      const entries = ctx?.sessionManager?.getEntries?.() ?? [];
+      for (let index = entries.length - 1; index >= 0; index -= 1) {
+        const entry = entries[index];
+        if (entry?.type === "custom" && entry.customType === PLAN_ENTRY_TYPE) {
+          items = normalizePlanItems(entry.data?.items);
+          if (items) break;
+        }
+      }
+      if (!items && ctx?.cwd) {
+        try {
+          const text = await readFile(join(resolve(ctx.cwd), AGENT_DIR, "plan.json"), "utf8");
+          items = parsePlanFile(text)?.items ?? null;
+        } catch {
+          /* no persisted plan */
+        }
+      }
+      showFooter(items, ctx);
+    } catch {
+      /* footer is cosmetic */
+    }
+  });
+}

package/assets/extensions/omnirush/trace-format.ts

@@ -52,6 +52,11 @@ export interface ParsedPiSession {
   model: string | null;
   messageRecords: PiRecord[];
   sawCompaction: boolean;
+  /** `omnirush.plan` custom entries (the plan tool's session record),
+   *  in file order: {at, items} snapshots of the task list. Additive —
+   *  the artifact carries them as plan_records so buyers see how the
+   *  agent structured the work. */
+  planRecords: Array<{ at: string | null; items: unknown }>;
 }
 
 function asRecord(line: string): PiRecord | null {
@@ -73,6 +78,7 @@ export function parsePiSession(text: string): ParsedPiSession {
     model: null,
     messageRecords: [],
     sawCompaction: false,
+    planRecords: [],
   };
   let firstTimestamp: string | null = null;
   let lastTimestamp: string | null = null;
@@ -89,6 +95,12 @@ export function parsePiSession(text: string): ParsedPiSession {
       }
     } else if (record.type && /compact/i.test(record.type)) {
       result.sawCompaction = true;
+    } else if (record.type === "custom" && (record as any).customType === "omnirush.plan") {
+      const data = (record as any).data as { items?: unknown } | undefined;
+      result.planRecords.push({
+        at: typeof record.timestamp === "string" ? record.timestamp : null,
+        items: data?.items ?? [],
+      });
     }
     if (typeof record.timestamp === "string") {
       firstTimestamp ??= record.timestamp;
@@ -280,6 +292,11 @@ export function buildTraceArtifact(input: BuildTraceArtifactInput): Record<strin
   if (input.parentSessionId && input.parentSessionId !== input.sessionId) {
     artifact.parent_session_id = input.parentSessionId;
   }
+  // Additive: the plan tool's task-list snapshots, in order. Absent
+  // entirely for sessions that never used the plan tool.
+  if (parsed.planRecords.length > 0) {
+    artifact.plan_records = parsed.planRecords;
+  }
   return artifact;
 }
 

package/assets/extensions/omnirush/webfetch-lib.ts

@@ -0,0 +1,241 @@
+// web_fetch internals — pure, injectable, node:test covered.
+//
+// Fetch a URL and return readable text: HTML is stripped down to its
+// text (scripts/styles/comments removed, block tags become newlines,
+// entities decoded), other text-ish types pass through. Hard caps keep
+// the tool bounded: ~512 KiB of body (the stream is cut off there, the
+// connection cancelled) and a 30s timeout. HTTPS only — http is allowed
+// for localhost/loopback targets only (local dev servers). No API key:
+// a plain fetch with a browser-ish Accept header.
+
+import { Readable } from "node:stream";
+
+/** Maximum body bytes read (text output can be somewhat smaller). */
+export const WEB_FETCH_MAX_BYTES = 512 * 1024;
+/** Hard response deadline. */
+export const WEB_FETCH_TIMEOUT_MS = 30_000;
+/** Loopback hostnames allowed to use plain http. */
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+export type WebFetchOutcome =
+  | {
+      ok: true;
+      url: string;
+      finalUrl: string;
+      status: number;
+      contentType: string;
+      /** Readable text: HTML stripped to text for markup types, the raw
+       *  body otherwise. */
+      text: string;
+      /** The raw body (size-capped) — for callers that want the
+       *  unprocessed markup ("html" format). */
+      raw: string;
+      /** Body bytes consumed (<= the cap). */
+      bytes: number;
+      /** True when the body exceeded the cap and was cut off. */
+      truncated: boolean;
+    }
+  | { ok: false; url: string; error: string; status?: number };
+
+/**
+ * Validate and normalize a URL for fetching: absolute http(s), https
+ * everywhere, plain http only for loopback hosts. Returns the parsed
+ * URL or null (with the reason in `reasonOf` for callers that want it).
+ */
+export function normalizeWebFetchUrl(
+  raw: string,
+): { url: URL; reason?: string } | { url: null; reason: string } {
+  const trimmed = String(raw ?? "").trim();
+  if (!trimmed) return { url: null, reason: "empty URL" };
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return { url: null, reason: `not a valid URL: ${trimmed.slice(0, 200)}` };
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    return { url: null, reason: `unsupported scheme ${url.protocol.replace(":", "")} — use https` };
+  }
+  if (url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname.toLowerCase())) {
+    return {
+      url: null,
+      reason: "plain http is only allowed for localhost — use the https URL",
+    };
+  }
+  if (url.username || url.password) {
+    return { url: null, reason: "URLs with embedded credentials are not fetched" };
+  }
+  return { url };
+}
+
+const BLOCK_TAGS_TO_NEWLINE =
+  /<\/?(?:p|div|section|article|header|footer|main|aside|nav|ul|ol|dl|li|dt|dd|br|hr|tr|table|thead|tbody|h[1-6]|blockquote|pre|figure|figcaption|form|fieldset|address|details|summary|center)\b[^>]*>/gi;
+
+/**
+ * Decode the HTML entities that appear in practice (named five plus
+ * numeric forms). Unknown entities pass through unchanged.
+ */
+export function decodeHtmlEntities(text: string): string {
+  return text
+    .replace(/&#x([0-9a-f]+);/gi, (_m, hex: string) => {
+      const code = Number.parseInt(hex, 16);
+      return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : _m;
+    })
+    .replace(/&#(\d+);/g, (_m, dec: string) => {
+      const code = Number.parseInt(dec, 10);
+      return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : _m;
+    })
+    .replace(/&(amp|lt|gt|quot|apos|nbsp);/g, (_m, name: string) => {
+      switch (name) {
+        case "amp": return "&";
+        case "lt": return "<";
+        case "gt": return ">";
+        case "quot": return '"';
+        case "apos": return "'";
+        case "nbsp": return " ";
+        default: return _m;
+      }
+    });
+}
+
+/**
+ * Strip an HTML document down to readable text: script/style/noscript/
+ * template/comment blocks are removed whole, block-level tags become
+ * newlines, remaining tags are dropped, entities are decoded and runs
+ * of blank lines collapse. Bounded: input longer than `maxInputChars`
+ * is cut (the body cap already bounds it).
+ */
+export function htmlToText(html: string, maxInputChars = WEB_FETCH_MAX_BYTES): string {
+  let text = html.length > maxInputChars ? html.slice(0, maxInputChars) : html;
+  text = text
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<(script|style|noscript|template|svg|head)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, " ")
+    .replace(/<(script|style|noscript|template|svg|head)\b[^>]*\/>/gi, " ")
+    .replace(BLOCK_TAGS_TO_NEWLINE, "\n")
+    .replace(/<[^>]+>/g, " ");
+  text = decodeHtmlEntities(text);
+  // Collapse whitespace within lines, drop trailing spaces, squeeze the
+  // blank runs a tag-stripped page tends to leave behind.
+  text = text
+    .split("\n")
+    .map((line) => line.replace(/[ \t ]+/g, " ").trim())
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n");
+  return text.trim();
+}
+
+/** Content types this tool renders as text (everything else is refused). */
+export function isTextContentType(contentType: string): boolean {
+  const type = String(contentType ?? "").split(";")[0].trim().toLowerCase();
+  if (!type) return true; // no content type: assume text
+  return (
+    type.startsWith("text/")
+    || type === "application/json"
+    || type === "application/xml"
+    || type === "application/javascript"
+    || type === "application/xhtml+xml"
+    || type.endsWith("+xml")
+    || type.endsWith("+json")
+  );
+}
+
+export interface FetchReadableOptions {
+  fetchImpl?: typeof fetch;
+  maxBytes?: number;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * Fetch `url` (already normalized) and produce readable text. The body
+ * is consumed incrementally and cut off at `maxBytes` — a huge response
+ * never lands in memory whole, and the connection is cancelled once the
+ * cap is hit. Never throws: failures come back as `{ok: false, error}`.
+ */
+export async function fetchReadableText(
+  rawUrl: string,
+  options: FetchReadableOptions = {},
+): Promise<WebFetchOutcome> {
+  const normalized = normalizeWebFetchUrl(rawUrl);
+  if (!normalized.url) return { ok: false, url: rawUrl, error: normalized.reason };
+  const url = normalized.url;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const maxBytes = Math.max(1024, options.maxBytes ?? WEB_FETCH_MAX_BYTES);
+  const timeoutMs = Math.max(250, options.timeoutMs ?? WEB_FETCH_TIMEOUT_MS);
+  const timeout = AbortSignal.timeout(timeoutMs);
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, timeout])
+    : timeout;
+  try {
+    const response = await fetchImpl(url, {
+      redirect: "follow",
+      signal,
+      headers: {
+        // Some sites 403 requests without an Accept; ask for text and
+        // identify honestly (traces show the agent anyway).
+        Accept: "text/html,application/json,text/*;q=0.9,*/*;q=0.1",
+        "Accept-Language": "en-US,en;q=0.9",
+        "User-Agent": "omnirush-webfetch/1.0 (+https://omnirush.ai)",
+      },
+    });
+    const contentType = String(response.headers.get("content-type") ?? "");
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => undefined);
+      return {
+        ok: false,
+        url,
+        status: response.status,
+        error: `HTTP ${response.status} ${response.statusText || ""}`.trim(),
+      };
+    }
+    if (!isTextContentType(contentType)) {
+      await response.body?.cancel().catch(() => undefined);
+      return { ok: false, url, status: response.status, error: `unsupported content type: ${contentType.split(";")[0].trim() || "unknown"}` };
+    }
+    if (!response.body) {
+      return { ok: false, url, status: response.status, error: "empty response body" };
+    }
+    let body = "";
+    let bytes = 0;
+    let truncated = false;
+    const reader = Readable.fromWeb(response.body as any);
+    try {
+      for await (const chunk of reader) {
+        const piece = Buffer.from(chunk);
+        if (bytes + piece.length > maxBytes) {
+          body += piece.subarray(0, Math.max(0, maxBytes - bytes)).toString("utf8");
+          bytes = maxBytes;
+          truncated = true;
+          break;
+        }
+        body += piece.toString("utf8");
+        bytes += piece.length;
+      }
+    } finally {
+      reader.destroy();
+      if (truncated) await response.body?.cancel().catch(() => undefined);
+    }
+    const finalUrl = response.url || url.toString();
+    const isHtml = /html|xml/i.test(contentType);
+    const text = isHtml ? htmlToText(body, maxBytes) : body;
+    return {
+      ok: true,
+      url: url.toString(),
+      finalUrl,
+      status: response.status,
+      contentType,
+      text,
+      raw: body,
+      bytes,
+      truncated,
+    };
+  } catch (error: any) {
+    if (options.signal?.aborted) {
+      return { ok: false, url, error: "cancelled" };
+    }
+    if (error?.name === "TimeoutError" || error?.name === "AbortError") {
+      return { ok: false, url, error: `timed out after ${Math.round(timeoutMs / 1000)}s` };
+    }
+    return { ok: false, url, error: error?.message ?? String(error) };
+  }
+}

package/assets/extensions/omnirush/webfetch.ts

@@ -0,0 +1,77 @@
+// web_fetch — a built-in Omnirush tool: URL -> readable text.
+//
+// HTTPS only (http allowed for localhost), HTML stripped to text,
+// ~512 KiB body cap, 30s timeout, no API key. The heavy lifting lives
+// in webfetch-lib.ts (pure, unit-tested); this wrapper only adapts the
+// pi tool contract: errors THROW (pi sets isError and shows the reason
+// to the model), success returns text content + details.
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  fetchReadableText,
+  normalizeWebFetchUrl,
+  WEB_FETCH_MAX_BYTES,
+} from "./webfetch-lib";
+
+const WebFetchParams = Type.Object({
+  url: Type.String({ description: "The http(s) URL to fetch (https, or http for localhost)" }),
+  /** "text" (default) returns readable text; "html" returns the raw
+   *  (still size-capped) body for markup-level questions. */
+  format: Type.Optional(StringEnum(["text", "html"] as const, {
+    description: 'Response form: "text" (HTML stripped, default) or "html" (raw body)',
+  })),
+});
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "web_fetch",
+    label: "Web Fetch",
+    description: [
+      "Fetch a URL and return its content as readable text.",
+      "HTML pages are stripped to text (scripts/styles/comments removed); JSON/XML/other text types pass through.",
+      "HTTPS only — plain http is allowed for localhost dev servers.",
+      "No API key. Responses are capped (~512 KiB) and time out after 30s.",
+      "Use for documentation pages, articles, API responses and other text content; binary downloads are refused.",
+    ].join(" "),
+    promptSnippet: "web_fetch: read a URL's content as text (HTML stripped)",
+    promptGuidelines: [
+      "Use web_fetch when you need the current content of a specific URL; it returns plain text with a ~512 KiB cap and a 30s timeout.",
+    ],
+    parameters: WebFetchParams,
+
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      const format = params.format === "html" ? "html" : "text";
+      // Fail fast on a bad URL so the model gets the reason, not a
+      // generic fetch failure.
+      const normalized = normalizeWebFetchUrl(params.url);
+      if (!normalized.url) {
+        throw new Error(normalized.reason);
+      }
+      const outcome = await fetchReadableText(params.url, { signal });
+      if (!outcome.ok) {
+        throw new Error(outcome.error);
+      }
+      let text = format === "html" ? outcome.raw : outcome.text;
+      if (!text) {
+        text = "(empty response)";
+      } else if (outcome.truncated) {
+        text += `\n\n[truncated at ${WEB_FETCH_MAX_BYTES} bytes — fetch with an HTTP range request or a more specific URL for more]`;
+      }
+      return {
+        content: [{ type: "text", text }],
+        details: {
+          url: outcome.url,
+          final_url: outcome.finalUrl,
+          status: outcome.status,
+          content_type: outcome.contentType,
+          bytes: outcome.bytes,
+          truncated: outcome.truncated,
+          format,
+        },
+      };
+    },
+  });
+}