bloby-bot 0.70.12 → 0.71.0

package/supervisor/harnesses/pi/test-completion.ts

@@ -11,6 +11,8 @@
  *   - google-gemini       → POST {baseUrl}/models/{modelId}:generateContent
  */
 import { getPiSubProvider, type PiApiFlavor } from './sub-providers.js';
+import { streamProvider } from './providers/stream.js';
+import { toolDefsForProvider } from './tools/registry.js';
 
 export interface PiTestCompletionInput {
   subProvider: string;
@@ -88,6 +90,60 @@ export async function runPiTestCompletion(input: PiTestCompletionInput): Promise
   }
 }
 
+/**
+ * Streaming + tools probe (audit C-4). The non-streaming, tool-less test above
+ * validates a contract no real turn uses — free-form model ids (Ollama, LM
+ * Studio, custom, OpenRouter) could pass it and then fail the first actual
+ * message, which streams SSE with the full tool schema attached. This probe
+ * exercises the REAL wire shape in one cheap request: success = any
+ * text/tool-call event arrives before an error does.
+ */
+export async function runPiStreamProbe(input: PiTestCompletionInput): Promise<PiTestCompletionResult> {
+  const provider = getPiSubProvider(input.subProvider);
+  if (!provider) return { ok: false, error: `Unknown sub-provider: ${input.subProvider}` };
+  const baseUrl = pickBaseUrl(input);
+  if (!baseUrl) return { ok: false, error: 'Missing base URL' };
+  const modelId = pickModelId(input);
+  if (!modelId) return { ok: false, error: 'Missing model ID' };
+
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const stream = streamProvider(provider.flavor, {
+      modelId,
+      baseUrl,
+      apiKey: input.apiKey?.trim() || '',
+      systemPrompt: 'You are a connectivity probe. Reply with the single word OK.',
+      messages: [{ role: 'user', content: [{ type: 'text', text: input.prompt || 'Reply with the single word OK.' }] }],
+      // withTask: the live conversation's schema is the superset every real
+      // turn sends — probe with the same shape (review PI-D-4).
+      tools: toolDefsForProvider({ withTask: true }),
+      // Generous: reasoning models burn output budget on hidden thinking first.
+      maxOutputTokens: 2048,
+      maxTokensField: provider.maxTokensField,
+      includeStreamUsage: provider.noStreamUsage ? false : undefined,
+      signal: ctl.signal,
+    });
+    for await (const evt of stream) {
+      if (evt.type === 'text_delta' || evt.type === 'tool_use') {
+        return { ok: true, text: 'stream OK', modelId, subProvider: provider.id };
+      }
+      if (evt.type === 'error') {
+        return { ok: false, error: evt.error, modelId, subProvider: provider.id };
+      }
+    }
+    if (ctl.signal.aborted) {
+      return { ok: false, error: `Stream probe timed out after ${REQUEST_TIMEOUT_MS / 1000}s.`, modelId, subProvider: provider.id };
+    }
+    return { ok: false, error: 'The stream ended without producing any output.', modelId, subProvider: provider.id };
+  } catch (err: any) {
+    const msg = err?.name === 'AbortError' ? `Stream probe timed out after ${REQUEST_TIMEOUT_MS / 1000}s.` : err?.message || String(err);
+    return { ok: false, error: msg, modelId, subProvider: provider.id };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 interface DispatchArgs {
   baseUrl: string;
   modelId: string;

package/supervisor/harnesses/pi/tools/bash.ts

@@ -1,26 +1,100 @@
 /**
- * Bash tool — runs a shell command in the workspace.
+ * Bash tool — runs a shell command in the workspace (+ background jobs).
  *
- * Stays small on purpose: combined stdout+stderr, hard timeout, kills the
- * process on session abort. No interactive subshells, no background jobs.
+ * Claude-SDK-parity surface (audit C-9): 120s default / 10min max timeout,
+ * SIGTERM-with-grace then SIGKILL on the whole process group (detached spawn —
+ * a SIGKILLed direct child can leave orphans holding the stdio pipes, and
+ * 'close' then never fires), settle-on-exit drain guard so the tool promise
+ * can never hang a turn, and `run_in_background` with the companion
+ * BashOutput / KillShell tools for long builds and dev servers.
  */
-import { spawn } from 'child_process';
+import { spawn, type ChildProcess } from 'child_process';
 import type { PiTool } from './types.js';
 
-const DEFAULT_TIMEOUT_MS = 60_000;
-const HARD_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const HARD_TIMEOUT_MS = 10 * 60_000;
 const OUTPUT_CAP_BYTES = 200 * 1024;  // 200 KB; matches Claude SDK's behavior
+const TERM_GRACE_MS = 3_000;
+/** Safety ceiling for background jobs (claude shells die with the subprocess;
+ *  pi jobs die with the session abort signal — this is the belt-and-braces). */
+const BACKGROUND_MAX_MS = 30 * 60_000;
+
+function killTreeWithGrace(child: ChildProcess): void {
+  const signalGroup = (sig: NodeJS.Signals) => {
+    try {
+      if (child.pid) process.kill(-child.pid, sig);
+      else child.kill(sig);
+    } catch {
+      try { child.kill(sig); } catch {}
+    }
+  };
+  signalGroup('SIGTERM');
+  const escalate = setTimeout(() => signalGroup('SIGKILL'), TERM_GRACE_MS);
+  escalate.unref?.();
+  child.once('exit', () => clearTimeout(escalate));
+}
+
+/* ── Background job table ── */
+
+interface BashJob {
+  id: string;
+  command: string;
+  child: ChildProcess;
+  out: string;
+  truncated: boolean;
+  /** How much of `out` the model has already seen via BashOutput. */
+  readOffset: number;
+  exited: boolean;
+  /** stdio fully drained ('close' fired) — late pipe data can arrive after 'exit'. */
+  closed: boolean;
+  exitCode: number | null;
+  exitSignal: NodeJS.Signals | null;
+  killed: boolean;
+  startedAt: number;
+}
+
+/** Finished jobs linger as readable tombstones for a few minutes (repeat polls
+ *  keep working), then a reap timer frees them — bounds the table without the
+ *  delete-on-first-read trap that lost late pipe output (review PI-D-3). */
+const JOB_TOMBSTONE_TTL_MS = 5 * 60_000;
+
+const jobs = new Map<string, BashJob>();
+let jobCounter = 0;
+
+function appendCapped(job: BashJob, chunk: Buffer): void {
+  if (job.truncated) return;
+  const remaining = OUTPUT_CAP_BYTES - Buffer.byteLength(job.out, 'utf-8');
+  if (remaining <= 0) { job.truncated = true; return; }
+  const text = chunk.toString('utf-8');
+  if (Buffer.byteLength(text, 'utf-8') > remaining) {
+    job.out += text.slice(0, remaining);
+    job.truncated = true;
+  } else {
+    job.out += text;
+  }
+}
+
+function jobStatusLine(job: BashJob): string {
+  if (!job.exited) return `[running for ${Math.round((Date.now() - job.startedAt) / 1000)}s]`;
+  if (job.killed) return '[killed]';
+  return `[exited with code ${job.exitCode}${job.exitSignal ? ` (signal ${job.exitSignal})` : ''}]`;
+}
+
+/* ── Tools ── */
 
 export const bashTool: PiTool = {
   name: 'Bash',
   description:
-    'Run a shell command in the workspace and return its combined stdout+stderr. Use this for non-interactive commands only — no editors, no long-running servers.',
+    'Run a shell command in the workspace and return its combined stdout+stderr. ' +
+    'For long-running commands (builds, installs, dev servers) set run_in_background: true ' +
+    'and poll with BashOutput; stop them with KillShell.',
   inputSchema: {
     type: 'object',
     properties: {
       command: { type: 'string', description: 'The shell command to execute.' },
       description: { type: 'string', description: 'A short description (5–10 words) of what the command does.' },
-      timeout: { type: 'integer', description: 'Timeout in milliseconds (default 60 000, max 300 000).' },
+      timeout: { type: 'integer', description: 'Timeout in milliseconds (default 120 000, max 600 000). Ignored for background jobs.' },
+      run_in_background: { type: 'boolean', description: 'Start the command as a background job and return immediately with a job id.' },
     },
     required: ['command'],
   },
@@ -29,6 +103,61 @@ export const bashTool: PiTool = {
     const command = typeof input?.command === 'string' ? input.command : '';
     if (!command.trim()) return { output: 'command is required.', isError: true };
 
+    if (input?.run_in_background) {
+      const id = `bash_${++jobCounter}`;
+      let child: ChildProcess;
+      try {
+        child = spawn('bash', ['-lc', command], {
+          cwd: ctx.cwd,
+          env: process.env,
+          stdio: ['ignore', 'pipe', 'pipe'],
+          detached: true,
+        });
+      } catch (err: any) {
+        return { output: `Failed to spawn command: ${err?.message || err}`, isError: true };
+      }
+      const job: BashJob = {
+        id, command, child,
+        out: '', truncated: false, readOffset: 0,
+        exited: false, closed: false, exitCode: null, exitSignal: null, killed: false,
+        startedAt: Date.now(),
+      };
+      jobs.set(id, job);
+      child.stdout?.on('data', (c: Buffer) => appendCapped(job, c));
+      child.stderr?.on('data', (c: Buffer) => appendCapped(job, c));
+      const onAbort = () => { if (!job.exited) { job.killed = true; killTreeWithGrace(child); } };
+      const reap = () => {
+        const t = setTimeout(() => jobs.delete(id), JOB_TOMBSTONE_TTL_MS);
+        t.unref?.();
+      };
+      child.on('error', () => {
+        job.exited = true;
+        job.closed = true;
+        job.exitCode = -1;
+        ctx.signal?.removeEventListener('abort', onAbort);
+        reap();
+      });
+      child.on('exit', (code, signal) => {
+        job.exited = true;
+        job.exitCode = code;
+        job.exitSignal = signal;
+        // Listener cleanup on natural exit — without it every finished job
+        // pins its ChildProcess + output buffer on the session's AbortSignal
+        // for the conversation's whole life (review D-TOOLS-5).
+        ctx.signal?.removeEventListener('abort', onAbort);
+        reap();
+      });
+      child.on('close', () => { job.closed = true; });
+      // Jobs die with the session (claude parity: background shells die with
+      // the SDK subprocess) and have a hard safety ceiling.
+      const ceiling = setTimeout(() => { if (!job.exited) { job.killed = true; killTreeWithGrace(child); } }, BACKGROUND_MAX_MS);
+      ceiling.unref?.();
+      ctx.signal?.addEventListener('abort', onAbort, { once: true });
+      return {
+        output: `Started background job ${id}. Poll it with BashOutput {"bash_id": "${id}"}; stop it with KillShell {"shell_id": "${id}"}.`,
+      };
+    }
+
     const requestedTimeout = Number(input?.timeout) || DEFAULT_TIMEOUT_MS;
     const timeout = Math.min(HARD_TIMEOUT_MS, Math.max(1000, requestedTimeout));
 
@@ -39,9 +168,8 @@ export const bashTool: PiTool = {
       let settled = false;
 
       // detached:true gives the child its own process group so kills reach
-      // grandchildren too — a SIGKILLed direct child can leave orphans holding
-      // the stdio pipes, and 'close' (which waits for the pipes) then never
-      // fires, hanging the tool promise and wedging the whole turn.
+      // grandchildren too — orphans holding the stdio pipes would otherwise
+      // keep 'close' from ever firing and hang the tool promise.
       const child = spawn('bash', ['-lc', command], {
         cwd: ctx.cwd,
         env: process.env,
@@ -49,15 +177,6 @@ export const bashTool: PiTool = {
         detached: true,
       });
 
-      const killTree = () => {
-        try {
-          if (child.pid) process.kill(-child.pid, 'SIGKILL');
-          else child.kill('SIGKILL');
-        } catch {
-          try { child.kill('SIGKILL'); } catch {}
-        }
-      };
-
       const append = (chunk: Buffer) => {
         if (truncated) return;
         const remaining = OUTPUT_CAP_BYTES - Buffer.byteLength(out, 'utf-8');
@@ -79,11 +198,11 @@ export const bashTool: PiTool = {
 
       const timer = setTimeout(() => {
         timedOut = true;
-        killTree();
+        killTreeWithGrace(child);
       }, timeout);
 
       const onAbort = () => {
-        killTree();
+        killTreeWithGrace(child);
       };
       ctx.signal?.addEventListener('abort', onAbort);
 
@@ -130,3 +249,60 @@ export const bashTool: PiTool = {
     });
   },
 };
+
+export const bashOutputTool: PiTool = {
+  name: 'BashOutput',
+  description: 'Read NEW output from a background Bash job since the last read, plus its status.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      bash_id: { type: 'string', description: 'The job id returned by Bash with run_in_background.' },
+    },
+    required: ['bash_id'],
+  },
+  async run(input) {
+    const id = typeof input?.bash_id === 'string' ? input.bash_id : (typeof input?.shell_id === 'string' ? input.shell_id : '');
+    const job = jobs.get(id);
+    if (!job) {
+      const known = Array.from(jobs.keys()).join(', ') || 'none';
+      return { output: `No background job "${id}". Known jobs: ${known}.`, isError: true };
+    }
+    const fresh = job.out.slice(job.readOffset);
+    job.readOffset = job.out.length;
+    const tail = job.truncated ? '\n[output capped at 200 KB]' : '';
+    // Deliberately NO delete here: 'exit' can fire before the stdio pipes
+    // drain, so an eager delete lost the output tail and made a follow-up
+    // poll error out (review PI-D-3). The reap timer frees finished jobs.
+    return {
+      output: `${jobStatusLine(job)}\n${fresh || '(no new output)'}${tail}`,
+      isError: job.exited && !job.killed && job.exitCode !== 0,
+    };
+  },
+};
+
+export const killShellTool: PiTool = {
+  name: 'KillShell',
+  description: 'Stop a background Bash job started with run_in_background.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      shell_id: { type: 'string', description: 'The job id to stop.' },
+    },
+    required: ['shell_id'],
+  },
+  async run(input) {
+    const id = typeof input?.shell_id === 'string' ? input.shell_id : (typeof input?.bash_id === 'string' ? input.bash_id : '');
+    const job = jobs.get(id);
+    if (!job) {
+      const known = Array.from(jobs.keys()).join(', ') || 'none';
+      return { output: `No background job "${id}". Known jobs: ${known}.`, isError: true };
+    }
+    if (job.exited) {
+      jobs.delete(id);
+      return { output: `Job ${id} had already finished ${jobStatusLine(job)}.` };
+    }
+    job.killed = true;
+    killTreeWithGrace(job.child);
+    return { output: `Killing job ${id} (SIGTERM, then SIGKILL after ${TERM_GRACE_MS / 1000}s).` };
+  },
+};

package/supervisor/harnesses/pi/tools/glob.ts

@@ -0,0 +1,79 @@
+/**
+ * Glob tool — find files by name pattern, newest first (audit D5-4).
+ * Mirrors the Claude SDK Glob's contract; shares the walk + pattern
+ * translation with Grep.
+ */
+import fs from 'fs';
+import path from 'path';
+import type { PiTool } from './types.js';
+import { safeResolve, displayPath } from './path-safety.js';
+import { globToRegExp } from './grep.js';
+
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'dist', 'dist-bloby', 'build', '.cache', '.next', 'coverage', '.venv', '__pycache__']);
+const MAX_RESULTS = 100;
+const MAX_FILES_SCANNED = 20_000;
+
+export const globTool: PiTool = {
+  name: 'Glob',
+  description:
+    'Find files by name pattern (e.g. "**/*.ts", "src/**/config.*"). Returns matching paths sorted newest-first.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'Glob pattern to match file paths against.' },
+      path: { type: 'string', description: 'Directory to search in (default: workspace root).' },
+    },
+    required: ['pattern'],
+  },
+
+  async run(input, ctx) {
+    const pattern = typeof input?.pattern === 'string' ? input.pattern.trim() : '';
+    if (!pattern) return { output: 'pattern is required.', isError: true };
+
+    let root: string;
+    try {
+      root = safeResolve(ctx.cwd, typeof input?.path === 'string' && input.path.trim() ? input.path : '.');
+    } catch (err: any) {
+      return { output: err.message, isError: true };
+    }
+
+    const re = globToRegExp(pattern);
+    const found: { p: string; mtime: number }[] = [];
+    const stack = [root];
+    let scanned = 0;
+    let truncatedScan = false;
+
+    while (stack.length > 0) {
+      if (ctx.signal?.aborted) break;
+      const dir = stack.pop()!;
+      let entries: fs.Dirent[];
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+      for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+          if (!SKIP_DIRS.has(e.name)) stack.push(full);
+          continue;
+        }
+        if (!e.isFile()) continue;
+        if (++scanned > MAX_FILES_SCANNED) { truncatedScan = true; break; }
+        const rel = path.relative(root, full).split(path.sep).join('/');
+        if (re.test(rel) || re.test(e.name)) {
+          let mtime = 0;
+          try { mtime = fs.statSync(full).mtimeMs; } catch {}
+          found.push({ p: displayPath(ctx.cwd, full), mtime });
+        }
+      }
+      if (truncatedScan) break;
+    }
+
+    if (found.length === 0) {
+      return { output: 'No files matched.' + (truncatedScan ? ` [Scan stopped at ${MAX_FILES_SCANNED} files — narrow the path]` : '') };
+    }
+    found.sort((a, b) => b.mtime - a.mtime);
+    const shown = found.slice(0, MAX_RESULTS);
+    const tail = found.length > MAX_RESULTS || truncatedScan
+      ? `\n\n[${found.length} matches — showing the ${shown.length} most recent]`
+      : '';
+    return { output: shown.map((f) => f.p).join('\n') + tail };
+  },
+};

package/supervisor/harnesses/pi/tools/registry.ts

@@ -11,10 +11,19 @@ import type { PiToolDef } from '../providers/types.js';
 import { readTool } from './read.js';
 import { writeTool } from './write.js';
 import { editTool } from './edit.js';
-import { bashTool } from './bash.js';
+import { bashTool, bashOutputTool, killShellTool } from './bash.js';
+import { grepTool } from './grep.js';
+import { globTool } from './glob.js';
+import { todoWriteTool } from './todo-write.js';
+import { webFetchTool } from './web-fetch.js';
 import { taskTool, taskToolDef } from './task.js';
 
-export const PI_TOOLS: PiTool[] = [readTool, writeTool, editTool, bashTool, taskTool];
+export const PI_TOOLS: PiTool[] = [
+  readTool, writeTool, editTool,
+  bashTool, bashOutputTool, killShellTool,
+  grepTool, globTool, todoWriteTool, webFetchTool,
+  taskTool,
+];
 
 const TOOL_BY_NAME = new Map<string, PiTool>();
 for (const t of PI_TOOLS) {
@@ -33,13 +42,16 @@ export function findTool(name: string): PiTool | undefined {
   return TOOL_BY_NAME.get(name) || TOOL_BY_NAME.get(name.toLowerCase());
 }
 
-export function toolDefsForProvider(opts?: { forSubagent?: boolean }): PiToolDef[] {
+export function toolDefsForProvider(opts?: { withTask?: boolean }): PiToolDef[] {
   const defs: PiToolDef[] = [];
   for (const t of PI_TOOLS) {
     if (t.name === 'Task') {
-      // Children cannot spawn grandchildren (Claude SDK parity) — a child that
-      // hallucinates a Task call still fails gracefully (ctx.tasks is unset).
-      if (opts?.forSubagent) continue;
+      // Task is opt-in: only live PARENT conversations have a task host.
+      // Sub-agent children can't spawn grandchildren (Claude SDK parity) and
+      // one-shots (pulse/cron/customer/agent-API) have no host either — a
+      // session that hallucinates a Task call still fails gracefully
+      // (ctx.tasks is unset).
+      if (!opts?.withTask) continue;
       // Rebuilt fresh so agent-roster/prompt edits apply per session start.
       defs.push(taskToolDef());
       continue;

package/supervisor/harnesses/pi/tools/todo-write.ts

@@ -0,0 +1,45 @@
+/**
+ * TodoWrite tool — visible task planning (audit D5-5).
+ *
+ * The tool itself is a no-op acknowledgement: its value is the bot:tool event
+ * the session already emits for every tool_use — on the dashboard that commits
+ * the streamed text as its own bubble (the plan "rhythm" claude users see),
+ * and on WhatsApp/Telegram it flushes the pending chunk as an intermediate
+ * progress message. Claude's TodoWrite works the same way from the harness's
+ * point of view. Deliberately NOT in FILE_TOOL_NAMES — updating a plan must
+ * never trigger a backend restart.
+ */
+import type { PiTool } from './types.js';
+
+export const todoWriteTool: PiTool = {
+  name: 'TodoWrite',
+  description:
+    'Maintain a visible todo list for multi-step tasks. Call it when you start a task (all items pending, ' +
+    'first in_progress) and again after each step completes. Exactly one item should be in_progress at a time.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      todos: {
+        type: 'array',
+        description: 'The complete, updated todo list (replaces the previous one).',
+        items: {
+          type: 'object',
+          properties: {
+            content: { type: 'string', description: 'Imperative description, e.g. "Add the API route".' },
+            status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+            activeForm: { type: 'string', description: 'Present-continuous label shown while in_progress.' },
+          },
+          required: ['content', 'status'],
+        },
+      },
+    },
+    required: ['todos'],
+  },
+
+  async run(input) {
+    const todos = Array.isArray(input?.todos) ? input.todos : [];
+    if (todos.length === 0) return { output: 'Todo list cleared.' };
+    const done = todos.filter((t: any) => t?.status === 'completed').length;
+    return { output: `Todo list updated (${done}/${todos.length} completed).` };
+  },
+};

package/supervisor/harnesses/pi/tools/web-fetch.ts

@@ -0,0 +1,129 @@
+/**
+ * WebFetch tool — fetch a URL and return readable text (audit D5-9).
+ *
+ * Hand-rolled, no deps: global fetch with a hard timeout, http(s)-only,
+ * naive HTML→text strip, capped output. There is deliberately NO WebSearch
+ * counterpart — claude's runs on Anthropic's server-side search; a hand-rolled
+ * one would need a scrape target or API key, so the pi prompt tells the model
+ * to ask for URLs instead.
+ */
+import type { PiTool } from './types.js';
+
+const FETCH_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_CHARS = 50_000;
+/** Raw-byte read budget — HTML needs headroom over the text cap (markup is
+ *  stripped), but the body must never be fully buffered: a multi-GB URL would
+ *  otherwise spike the single supervisor process (review D-TOOLS-6). */
+const MAX_BODY_BYTES = 2 * 1024 * 1024;
+const MAX_REDIRECTS_NOTE = 'follow'; // fetch follows redirects by default
+
+/** Stream-read up to MAX_BODY_BYTES, then cancel the rest of the body. */
+async function readBodyCapped(res: Response): Promise<{ text: string; bodyTruncated: boolean }> {
+  if (!res.body) return { text: '', bodyTruncated: false };
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let text = '';
+  let bytes = 0;
+  let bodyTruncated = false;
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value) {
+        bytes += value.byteLength;
+        text += decoder.decode(value, { stream: true });
+        if (bytes >= MAX_BODY_BYTES) {
+          bodyTruncated = true;
+          try { await reader.cancel(); } catch {}
+          break;
+        }
+      }
+    }
+  } finally {
+    try { reader.releaseLock(); } catch {}
+  }
+  text += decoder.decode();
+  return { text, bodyTruncated };
+}
+
+function htmlToText(html: string): string {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/(p|div|h[1-6]|li|tr|section|article|header|footer)>/gi, '\n')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n\s*\n\s*\n+/g, '\n\n')
+    .trim();
+}
+
+export const webFetchTool: PiTool = {
+  name: 'WebFetch',
+  description:
+    'Fetch a web page or API endpoint over HTTP(S) and return its readable text content. ' +
+    'HTML is stripped to text; JSON and plain text are returned as-is (capped).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: 'Absolute http:// or https:// URL to fetch.' },
+    },
+    required: ['url'],
+  },
+
+  async run(input, ctx) {
+    const raw = typeof input?.url === 'string' ? input.url.trim() : '';
+    let url: URL;
+    try {
+      url = new URL(raw);
+    } catch {
+      return { output: `Invalid URL: ${raw || '(empty)'}`, isError: true };
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return { output: `Only http(s) URLs are supported (got ${url.protocol}).`, isError: true };
+    }
+
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), FETCH_TIMEOUT_MS);
+    const onOuterAbort = () => ctl.abort();
+    ctx.signal?.addEventListener('abort', onOuterAbort, { once: true });
+    try {
+      const res = await fetch(url, {
+        signal: ctl.signal,
+        redirect: MAX_REDIRECTS_NOTE,
+        headers: { 'user-agent': 'Bloby/1.0 (+https://bloby.bot)', accept: 'text/html,application/json,text/plain,*/*' },
+      });
+      const declared = Number(res.headers.get('content-length') || 0);
+      if (declared > 50 * 1024 * 1024) {
+        try { await res.body?.cancel(); } catch {}
+        return { output: `Response too large to fetch (${Math.round(declared / 1024 / 1024)} MB). Use Bash (curl) to download it to disk instead.`, isError: true };
+      }
+      const { text: body, bodyTruncated } = await readBodyCapped(res);
+      const contentType = res.headers.get('content-type') || '';
+      const text = /text\/html|application\/xhtml/i.test(contentType) ? htmlToText(body) : body.trim();
+      const capped = text.length > MAX_OUTPUT_CHARS || bodyTruncated
+        ? `${text.slice(0, MAX_OUTPUT_CHARS)}\n\n[Truncated${bodyTruncated ? ` — read stopped at ${MAX_BODY_BYTES / 1024 / 1024} MB` : ` at ${MAX_OUTPUT_CHARS} characters`}]`
+        : text;
+      if (!res.ok) {
+        return { output: `HTTP ${res.status} ${res.statusText} from ${url.host}\n\n${capped.slice(0, 2000)}`, isError: true };
+      }
+      return { output: capped || '(empty response body)' };
+    } catch (err: any) {
+      const msg = err?.name === 'AbortError'
+        ? (ctx.signal?.aborted ? 'Fetch aborted (session ended).' : `Fetch timed out after ${FETCH_TIMEOUT_MS / 1000}s.`)
+        : `Fetch failed: ${err?.message || err}`;
+      return { output: msg, isError: true };
+    } finally {
+      clearTimeout(timer);
+      ctx.signal?.removeEventListener('abort', onOuterAbort);
+    }
+  },
+};