@hncode/hncode 0.5.2 → 0.5.4

package/src/tools/tasks.js

@@ -1,141 +1,214 @@
-// TaskList / TaskOutput / TaskStop / TaskWait — manage background tasks spawned
-// by Bash (run_in_background) and Agent (run_in_background). The task records
-// live in the shared registry (src/agent-task.js), so the CLI tools and the
-// /tasks panel read exactly the same data.
-
-import cp from 'node:child_process';
-import { isTerminal, settleTask, STATUS_LABEL } from '../agent-task.js';
-
-function taskLine(t) {
-  const extra = t.stopReason ? ` (${t.stopReason})` : '';
-  const label = STATUS_LABEL[t.status] || t.status;
-  const what = t.kind === 'process' ? (t.description || t.command) : t.description;
-  return `#${t.taskId} [${label}${extra}] pid=${t.pid || '-'} ${what}`;
-}
-
-export const TaskListSpec = {
-  name: 'TaskList',
-  description: 'List background tasks (from Bash or Agent run_in_background). Reports task id, status, description.',
-  parameters: { type: 'object', properties: {}, required: [] },
-  async execute(_args, ctx) {
-    const tasks = Object.values(ctx.tasks || {}).sort((a, b) => b.startedAt - a.startedAt);
-    if (tasks.length === 0) return 'No background tasks.';
-    return tasks.map(taskLine).join('\n');
-  },
-};
-
-export const TaskOutputSpec = {
-  name: 'TaskOutput',
-  description: 'Get the output of a background task by task_id. head_limit caps the lines returned.',
-  parameters: {
-    type: 'object',
-    properties: {
-      task_id: { type: 'string', description: 'Task id returned when the task was started.' },
-      head_limit: { type: 'integer', minimum: 0, description: 'Max output lines returned.' },
-    },
-    required: ['task_id'],
-  },
-  async execute(args, ctx) {
-    const t = (ctx.tasks || {})[args.task_id];
-    if (!t) return `No such task: ${args.task_id}`;
-    const text = t.output || '';
-    const lines = text ? text.split('\n').filter((l) => l.length > 0) : [];
-    const capped = args.head_limit ? lines.slice(0, args.head_limit) : lines;
-    const tail = lines.length > capped.length;
-    const label = STATUS_LABEL[t.status] || t.status;
-    const head = `#${t.taskId} [${label}] (pid ${t.pid || '-'})`;
-    let out = capped.length ? `${head}\n${capped.join('\n')}` : `${head}\n(no output yet)`;
-    if (tail) out += `\n... [${lines.length - capped.length} more lines; use head_limit]`;
-    return out;
-  },
-};
-
-export const TaskStopSpec = {
-  name: 'TaskStop',
-  description: 'Stop a running background task by task_id. Use only when the task must be cancelled.',
-  parameters: {
-    type: 'object',
-    properties: {
-      task_id: { type: 'string', description: 'Background task id to stop.' },
-      reason: { type: 'string', description: 'Short reason recorded on stop.' },
-    },
-    required: ['task_id'],
-  },
-  async execute(args, ctx) {
-    const t = (ctx.tasks || {})[args.task_id];
-    if (!t) return `No such task: ${args.task_id}`;
-    if (isTerminal(t.status)) return `Task ${t.taskId} already ${STATUS_LABEL[t.status] || t.status}.`;
-    const reason = args.reason || 'Stopped by TaskStop';
-    try {
-      // An agent task aborts through its controller; a process is killed.
-      if (t.kind === 'agent' && typeof t._abort === 'function') {
-        t._abort();
-      } else if (t.pid) {
-        if (process.platform === 'win32') {
-          try { cp.spawnSync('taskkill', ['/pid', String(t.pid), '/t', '/f'], { stdio: 'ignore' }); } catch {}
-        } else {
-          try { process.kill(t.pid, 'SIGTERM'); } catch {}
-        }
-      }
-    } catch (e) {
-      return `Failed to stop ${t.taskId}: ${e.message}`;
-    }
-    // 'killed' — a deliberate stop, distinct from a failure (kimi's vocabulary).
-    settleTask(t, 'killed', { stopReason: reason });
-    return `Stopped task ${t.taskId}. reason: ${reason}`;
-  },
-};
-
-// Wait for background tasks to finish. A timeout is not an error; the result
-// lists the tasks still running so the caller can wait again.
-export const TaskWaitSpec = {
-  name: 'TaskWait',
-  description: 'Wait for background tasks to finish, timeout in seconds (1-600). With task_id, waits for that task; without it, returns when any running task finishes. A timeout is not an error; still-running tasks are listed, so you may call it again.',
-  parameters: {
-    type: 'object',
-    properties: {
-      timeout: { type: 'integer', minimum: 1, maximum: 600, description: 'Max seconds to wait (1-600).' },
-      task_id: { type: 'string', description: 'Task id to wait for; omit to wait for any running task.' },
-    },
-    required: ['timeout'],
-  },
-  async execute(args, ctx) {
-    const tasks = ctx.tasks || {};
-    const target = args.task_id ? tasks[args.task_id] : null;
-    if (args.task_id && !target) return `No such task: ${args.task_id}`;
-    const secs = Math.max(1, Math.min(600, Number(args.timeout) || 1));
-    const deadline = Date.now() + secs * 1000;
-    const signal = ctx && ctx.signal;
-
-    const isDone = (t) => t && isTerminal(t.status);
-    const anyRunning = () => Object.values(tasks).some((t) => t.status === 'running');
-
-    if (args.task_id) {
-      if (isDone(target)) return `Task ${target.taskId} already ${STATUS_LABEL[target.status] || target.status}${target.exitCode != null ? ` (exit ${target.exitCode})` : ''}.`;
-    } else if (!anyRunning()) {
-      return 'No background tasks are running.';
-    }
-
-    await new Promise((resolve) => {
-      const tick = setInterval(() => {
-        const done = args.task_id ? isDone(target) : !anyRunning();
-        if (done || Date.now() >= deadline || (signal && signal.aborted)) {
-          clearInterval(tick);
-          resolve();
-        }
-      }, 100);
-    });
-
-    if (signal && signal.aborted) return 'Interrupted by user';
-    const still = Object.values(tasks).filter((t) => t.status === 'running');
-    if (args.task_id) {
-      if (isDone(target)) {
-        return `Task ${target.taskId} finished: ${STATUS_LABEL[target.status] || target.status}${target.exitCode != null ? ` (exit ${target.exitCode})` : ''}${target.stopReason ? ` — ${target.stopReason}` : ''}.`;
-      }
-      return `Task ${target.taskId} still running after ${secs}s.`;
-    }
-    if (!still.length) return 'All background tasks have finished.';
-    const list = still.map((t) => `#${t.taskId} ${t.description || t.command || ''}`).join('; ');
-    return `Timeout after ${secs}s; still running: ${list}`;
-  },
-};
+// TaskList / TaskOutput / TaskStop / TaskWait — manage background tasks spawned
+// by Bash (run_in_background) and Agent (run_in_background). The task records
+// live in the shared registry (src/agent-task.js), so the CLI tools and the
+// /tasks panel read exactly the same data.
+
+import cp from 'node:child_process';
+import { isTerminal, settleTask, STATUS_LABEL } from '../agent-task.js';
+
+function taskLine(t) {
+  const extra = t.stopReason ? ` (${t.stopReason})` : '';
+  const label = STATUS_LABEL[t.status] || t.status;
+  const what = t.kind === 'process' ? (t.description || t.command) : t.description;
+  return `#${t.taskId} [${label}${extra}] pid=${t.pid || '-'} ${what}`;
+}
+
+export const TaskListSpec = {
+  name: 'TaskList',
+  description: 'List background tasks (from Bash or Agent run_in_background). Reports task id, status, description.',
+  parameters: { type: 'object', properties: {}, required: [] },
+  async execute(_args, ctx) {
+    const tasks = Object.values(ctx.tasks || {}).sort((a, b) => b.startedAt - a.startedAt);
+    if (tasks.length === 0) return 'No background tasks.';
+    return tasks.map(taskLine).join('\n');
+  },
+};
+
+export const TaskOutputSpec = {
+  name: 'TaskOutput',
+  description: 'Get the output of a background task by task_id. head_limit caps the lines returned.',
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'Task id returned when the task was started.' },
+      head_limit: { type: 'integer', minimum: 0, description: 'Max output lines returned.' },
+    },
+    required: ['task_id'],
+  },
+  async execute(args, ctx) {
+    const t = (ctx.tasks || {})[args.task_id];
+    if (!t) return `No such task: ${args.task_id}`;
+    const text = t.output || '';
+    const lines = text ? text.split('\n').filter((l) => l.length > 0) : [];
+    const capped = args.head_limit ? lines.slice(0, args.head_limit) : lines;
+    const tail = lines.length > capped.length;
+    const label = STATUS_LABEL[t.status] || t.status;
+    const head = `#${t.taskId} [${label}] (pid ${t.pid || '-'})`;
+    let out = capped.length ? `${head}\n${capped.join('\n')}` : `${head}\n(no output yet)`;
+    if (tail) out += `\n... [${lines.length - capped.length} more lines; use head_limit]`;
+    return out;
+  },
+};
+
+export const TaskStopSpec = {
+  name: 'TaskStop',
+  description: 'Stop a running background task by task_id. Use only when the task must be cancelled.',
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'Background task id to stop.' },
+      reason: { type: 'string', description: 'Short reason recorded on stop.' },
+    },
+    required: ['task_id'],
+  },
+  async execute(args, ctx) {
+    const t = (ctx.tasks || {})[args.task_id];
+    if (!t) return `No such task: ${args.task_id}`;
+    if (isTerminal(t.status)) return `Task ${t.taskId} already ${STATUS_LABEL[t.status] || t.status}.`;
+    const reason = args.reason || 'Stopped by TaskStop';
+    try {
+      // An agent OR teammate task aborts through its controller; a process is killed.
+      // Keyed on the handle, not the kind — a teammate task carries `_abort` too
+      // (see spawnTeammate), and gating on kind==='agent' left teammates unstoppable.
+      if (typeof t._abort === 'function') {
+        t._abort();
+      } else if (t.pid) {
+        if (process.platform === 'win32') {
+          try { cp.spawnSync('taskkill', ['/pid', String(t.pid), '/t', '/f'], { stdio: 'ignore' }); } catch {}
+        } else {
+          try { process.kill(t.pid, 'SIGTERM'); } catch {}
+        }
+      }
+    } catch (e) {
+      return `Failed to stop ${t.taskId}: ${e.message}`;
+    }
+    // 'killed' — a deliberate stop, distinct from a failure (kimi's vocabulary).
+    settleTask(t, 'killed', { stopReason: reason });
+    return `Stopped task ${t.taskId}. reason: ${reason}`;
+  },
+};
+
+/**
+ * Write to a background task started with `Bash {interactive: true}`.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A background command's stdin is /dev/null by default — deliberately, because leaving it as an open pipe
+ * made `cat` and `npm init` block until the timeout. That also meant a command that WANTS input could never
+ * be given any: a REPL, a prompt-driven generator, or a server reading commands had no way in.
+ *
+ * `interactive` opts ONE run into a real pipe and this tool is the other end of it. Both are needed: the
+ * flag without the tool leaves a pipe nobody can write to, and the tool without the flag has no pipe to
+ * find.
+ *
+ * ENTER is a parameter rather than something baked into `text`, because a prompt-driven program
+ * distinguishes "line entered" from "line still being typed", and a caller sending three lines then a bare
+ * Enter should not have to remember to write a trailing newline.
+ */
+export const TaskInputSpec = {
+  name: 'TaskInput',
+  description: [
+    'Send text to the stdin of a background task started with `Bash {interactive: true}`.',
+    '',
+    '`text` is written verbatim. `enter` (default true) appends a newline, which is what a prompt-driven',
+    'program needs to accept the line; pass `enter: false` to type without submitting.',
+    '',
+    'The task must still be running: a finished one has no stdin, and this says so rather than pretending',
+    'the write landed. Read the reply with TaskOutput.',
+  ].join('\n'),
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'Background task id (from Bash with interactive: true).' },
+      text: { type: 'string', description: 'Text to write, verbatim.' },
+      enter: { type: 'boolean', default: true, description: 'Append a newline so the program accepts the line. False types without submitting.' },
+    },
+    required: ['task_id'],
+  },
+  async execute(args, ctx) {
+    const t = (ctx.tasks || {})[args.task_id];
+    if (!t) return `No such task: ${args.task_id}`;
+    if (isTerminal(t.status)) {
+      return `Task ${t.taskId} is ${STATUS_LABEL[t.status] || t.status} — it has no stdin to write to.`;
+    }
+    if (!t.stdin) {
+      // The two ways to have no pipe, told apart: the task was never interactive, or its process closed
+      // stdin by itself. Naming which one saves a round of guessing.
+      return t.interactive
+        ? `Task ${t.taskId} closed its stdin — the process is no longer reading input.`
+        : `Task ${t.taskId} was not started with \`interactive: true\`, so it has no stdin. Restart it with that flag.`;
+    }
+
+    const text = args.text == null ? '' : String(args.text);
+    const payload = args.enter === false ? text : `${text}\n`;
+    if (!payload) return 'Nothing to write.';
+
+    try {
+      // Resolve on the WRITE CALLBACK, not on the return value: `write` returns false when the buffer is
+      // full, and the callback fires once the bytes are actually out. Awaiting it is the difference
+      // between "we called write" and "the write landed".
+      await new Promise((resolve, reject) => {
+        t.stdin.write(payload, (err) => (err ? reject(err) : resolve()));
+      });
+    } catch (e) {
+      // EPIPE: the process exited between the status check and the write. Not a failure of the tool.
+      t.stdin = null;
+      return `Task ${t.taskId} stopped reading input: ${e.message}`;
+    }
+
+    return `Wrote ${payload.length} character(s) to ${t.taskId}. Read the reply with TaskOutput.`;
+  },
+};
+// Wait for background tasks to finish. A timeout is not an error; the result
+// lists the tasks still running so the caller can wait again.
+export const TaskWaitSpec = {
+  name: 'TaskWait',
+  description: 'Wait for background tasks to finish, timeout in seconds (1-600). With task_id, waits for that task; without it, returns when any running task finishes. A timeout is not an error; still-running tasks are listed, so you may call it again.',
+  parameters: {
+    type: 'object',
+    properties: {
+      timeout: { type: 'integer', minimum: 1, maximum: 600, description: 'Max seconds to wait (1-600).' },
+      task_id: { type: 'string', description: 'Task id to wait for; omit to wait for any running task.' },
+    },
+    required: ['timeout'],
+  },
+  async execute(args, ctx) {
+    const tasks = ctx.tasks || {};
+    const target = args.task_id ? tasks[args.task_id] : null;
+    if (args.task_id && !target) return `No such task: ${args.task_id}`;
+    const secs = Math.max(1, Math.min(600, Number(args.timeout) || 1));
+    const deadline = Date.now() + secs * 1000;
+    const signal = ctx && ctx.signal;
+
+    const isDone = (t) => t && isTerminal(t.status);
+    const anyRunning = () => Object.values(tasks).some((t) => t.status === 'running');
+
+    if (args.task_id) {
+      if (isDone(target)) return `Task ${target.taskId} already ${STATUS_LABEL[target.status] || target.status}${target.exitCode != null ? ` (exit ${target.exitCode})` : ''}.`;
+    } else if (!anyRunning()) {
+      return 'No background tasks are running.';
+    }
+
+    await new Promise((resolve) => {
+      const tick = setInterval(() => {
+        const done = args.task_id ? isDone(target) : !anyRunning();
+        if (done || Date.now() >= deadline || (signal && signal.aborted)) {
+          clearInterval(tick);
+          resolve();
+        }
+      }, 100);
+    });
+
+    if (signal && signal.aborted) return 'Interrupted by user';
+    const still = Object.values(tasks).filter((t) => t.status === 'running');
+    if (args.task_id) {
+      if (isDone(target)) {
+        return `Task ${target.taskId} finished: ${STATUS_LABEL[target.status] || target.status}${target.exitCode != null ? ` (exit ${target.exitCode})` : ''}${target.stopReason ? ` — ${target.stopReason}` : ''}.`;
+      }
+      return `Task ${target.taskId} still running after ${secs}s.`;
+    }
+    if (!still.length) return 'All background tasks have finished.';
+    const list = still.map((t) => `#${t.taskId} ${t.description || t.command || ''}`).join('; ');
+    return `Timeout after ${secs}s; still running: ${list}`;
+  },
+};

package/src/tools/team.js

@@ -226,6 +226,19 @@ export const SendMessageSpec = {
     // reaches the person, and it is why the box exists.
     if (args.to === TEAM_LEAD_NAME) {
       writeToMailbox(teamName, TEAM_LEAD_NAME, { from: me.name, text, summary: args.summary, color });
+      // Tell the running TUI at once, so the message appears in the user's transcript as it is sent
+      // rather than waiting for their next turn.
+      //
+      // Without this the reply was only ever written to a file: `formatLeadInbox` runs at the START of
+      // a turn, so a member's answer sat unread until the person happened to type something else. From
+      // the user's side that is indistinguishable from the team being dead — they send an instruction,
+      // nothing appears, and the answer is already on disk.
+      //
+      // The callback reaches here through `ctx`, which the Agent builds by spreading the teammate's
+      // config, so the spawner only has to put it there.
+      if (typeof ctx?.onLeadMail === 'function') {
+        try { ctx.onLeadMail({ from: me.name, text, summary: args.summary, color }); } catch { /* never fail a send over a display hook */ }
+      }
       return { content: 'Sent to the lead (the user).' };
     }
 

package/src/tools/utils.js

@@ -31,8 +31,13 @@ export function truncateBuf(buf) {
 export function normalizeInput(p) {
   let s = String(p);
   if (s.startsWith('~')) s = path.join(os.homedir(), s.slice(1));
-  const m = s.match(/^\/([a-zA-Z])\/(.*)$/);
-  if (m) return path.join(`${m[1].toUpperCase()}:\\`, ...m[2].split('/'));
+  // Windows only: under Git Bash an agent writes `/d/hncode/src` for `D:\hncode\src`.
+  // Gated on the platform because on Linux `/c/x` is a perfectly ordinary absolute
+  // path, and rewriting it to `C:\x` turned it into a relative garbage filename.
+  if (process.platform === 'win32') {
+    const m = s.match(/^\/([a-zA-Z])\/(.*)$/);
+    if (m) return path.join(`${m[1].toUpperCase()}:\\`, ...m[2].split('/'));
+  }
   return s;
 }
 
@@ -44,7 +49,11 @@ export function resolvePath(input, ctx) {
   if (!ctx.allowExternal) {
     let rel = path.relative(ws, p);
     if (rel === '') return p;
-    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    // ESCAPE check, not a prefix check: the first path segment must not be `..`.
+    // A plain startsWith('..') also rejected files INSIDE the workspace whose
+    // names merely begin with dots — `..notes.md` — while `...` / `..a` are
+    // legitimate relative names that stay below the root.
+    if (rel.split(path.sep)[0] === '..' || path.isAbsolute(rel)) {
       throw new Error(`Path outside workspace: ${input}. Run hncode from that directory or set HNCODE_ALLOW_EXTERNAL=1.`);
     }
   }

package/src/tools/web-search.js

@@ -1,88 +1,88 @@
-// WebSearch tool — search the web through puri.li's JSON API.
-//
-// WHY NOT A SCRAPED SEARCH PAGE
-// -----------------------------
-// This used to fetch Bing's HTML and parse `<li class="b_algo">` blocks. That worked until it
-// silently stopped: the request still returned 200 with the query echoed in `<title>`, but the
-// page contained no results — the two or three `b_algo` blocks it did have were
-// `translate.google.cn` and similar chrome, unrelated to the query. Measured over five identical
-// requests for one query: five different first results (Yandex, GitHub, 知乎, PixelOS, Nature),
-// none of them related. Adding a market parameter, warming up cookies, and sending a full set of
-// browser headers all changed nothing.
-//
-// The failure mode is what made this urgent. A scraper that returns junk does not look broken to
-// the model — the results arrive in the normal shape, so they get used and cited. A JSON API that
-// answers with `results: []` can at least be reported honestly.
-
-const ENDPOINT = 'https://puri.li/api/search';
-const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36';
-
-/**
- * The API's payload, as a list of results.
- *
- * Tolerant on purpose: this is a third-party service with no published schema, so a missing or
- * renamed field must degrade to "fewer results" rather than throw. `description` is the snippet;
- * an entry without a URL is dropped, because a result the model cannot open is not usable.
- */
-export function parseSearchResults(json, limit = 8) {
-  const list = json && Array.isArray(json.results) ? json.results : [];
-  const out = [];
-  for (const r of list) {
-    if (!r || typeof r.url !== 'string' || !r.url) continue;
-    out.push({
-      title: String(r.title || r.url).trim(),
-      url: r.url,
-      snippet: String(r.description || r.snippet || '').replace(/\s+/g, ' ').trim(),
-    });
-    if (out.length >= limit) break;
-  }
-  return out;
-}
-
-export const spec = {
-  name: 'WebSearch',
-  description: 'Search the web. Results are title/URL/snippet; snippets are summaries, so fetch a promising URL with FetchURL. Cite sources.',
-  parameters: {
-    type: 'object',
-    properties: {
-      query: { type: 'string', description: 'Search query.' },
-      page: { type: 'integer', description: 'Page number, 1-based. Defaults to 1.' },
-    },
-    required: ['query'],
-  },
-  async execute(args, ctx) {
-    const query = String(args.query || '').trim();
-    if (!query) return 'Error: query must not be empty.';
-    const page = Math.max(1, Math.trunc(Number(args.page)) || 1);
-    const signal = (ctx && ctx.signal) || undefined;
-    const url = `${ENDPOINT}?q=${encodeURIComponent(query)}&page=${page}`;
-    try {
-      const res = await fetch(url, {
-        headers: { 'User-Agent': UA, Accept: 'application/json' },
-        signal,
-      });
-      if (!res.ok) return `Error: search failed (${res.status} ${res.statusText}).`;
-      // The endpoint answers with JSON. If it ever does not, say so rather than parsing a page.
-      const text = await res.text();
-      let json;
-      try { json = JSON.parse(text); }
-      catch { return `Error: search returned a non-JSON response (${text.length} bytes) for "${query}".`; }
-
-      const results = parseSearchResults(json, 8);
-      if (!results.length) {
-        // A genuine empty result set, NOT an error. The old scraper could not tell the two apart,
-        // which is why a broken page looked like a successful search with odd results.
-        return page > 1
-          ? `No search results found for: ${query} (page ${page}).`
-          : `No search results found for: ${query}`;
-      }
-      const more = json && json.hasNext ? `\n\nMore results available: call WebSearch again with page=${page + 1}.` : '';
-      return results
-        .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`)
-        .join('\n\n') + more;
-    } catch (e) {
-      const msg = e && e.name === 'AbortError' ? 'interrupted' : (e.message || String(e));
-      return `Error searching "${query}": ${msg}`;
-    }
-  },
-};
+// WebSearch tool — search the web through puri.li's JSON API.
+//
+// WHY NOT A SCRAPED SEARCH PAGE
+// -----------------------------
+// This used to fetch Bing's HTML and parse `<li class="b_algo">` blocks. That worked until it
+// silently stopped: the request still returned 200 with the query echoed in `<title>`, but the
+// page contained no results — the two or three `b_algo` blocks it did have were
+// `translate.google.cn` and similar chrome, unrelated to the query. Measured over five identical
+// requests for one query: five different first results (Yandex, GitHub, a Q&A site, PixelOS, Nature),
+// none of them related. Adding a market parameter, warming up cookies, and sending a full set of
+// browser headers all changed nothing.
+//
+// The failure mode is what made this urgent. A scraper that returns junk does not look broken to
+// the model — the results arrive in the normal shape, so they get used and cited. A JSON API that
+// answers with `results: []` can at least be reported honestly.
+
+const ENDPOINT = 'https://puri.li/api/search';
+const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36';
+
+/**
+ * The API's payload, as a list of results.
+ *
+ * Tolerant on purpose: this is a third-party service with no published schema, so a missing or
+ * renamed field must degrade to "fewer results" rather than throw. `description` is the snippet;
+ * an entry without a URL is dropped, because a result the model cannot open is not usable.
+ */
+export function parseSearchResults(json, limit = 8) {
+  const list = json && Array.isArray(json.results) ? json.results : [];
+  const out = [];
+  for (const r of list) {
+    if (!r || typeof r.url !== 'string' || !r.url) continue;
+    out.push({
+      title: String(r.title || r.url).trim(),
+      url: r.url,
+      snippet: String(r.description || r.snippet || '').replace(/\s+/g, ' ').trim(),
+    });
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
+export const spec = {
+  name: 'WebSearch',
+  description: 'Search the web. Results are title/URL/snippet; snippets are summaries, so fetch a promising URL with FetchURL. Cite sources.',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query.' },
+      page: { type: 'integer', description: 'Page number, 1-based. Defaults to 1.' },
+    },
+    required: ['query'],
+  },
+  async execute(args, ctx) {
+    const query = String(args.query || '').trim();
+    if (!query) return 'Error: query must not be empty.';
+    const page = Math.max(1, Math.trunc(Number(args.page)) || 1);
+    const signal = (ctx && ctx.signal) || undefined;
+    const url = `${ENDPOINT}?q=${encodeURIComponent(query)}&page=${page}`;
+    try {
+      const res = await fetch(url, {
+        headers: { 'User-Agent': UA, Accept: 'application/json' },
+        signal,
+      });
+      if (!res.ok) return `Error: search failed (${res.status} ${res.statusText}).`;
+      // The endpoint answers with JSON. If it ever does not, say so rather than parsing a page.
+      const text = await res.text();
+      let json;
+      try { json = JSON.parse(text); }
+      catch { return `Error: search returned a non-JSON response (${text.length} bytes) for "${query}".`; }
+
+      const results = parseSearchResults(json, 8);
+      if (!results.length) {
+        // A genuine empty result set, NOT an error. The old scraper could not tell the two apart,
+        // which is why a broken page looked like a successful search with odd results.
+        return page > 1
+          ? `No search results found for: ${query} (page ${page}).`
+          : `No search results found for: ${query}`;
+      }
+      const more = json && json.hasNext ? `\n\nMore results available: call WebSearch again with page=${page + 1}.` : '';
+      return results
+        .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`)
+        .join('\n\n') + more;
+    } catch (e) {
+      const msg = e && e.name === 'AbortError' ? 'interrupted' : (e.message || String(e));
+      return `Error searching "${query}": ${msg}`;
+    }
+  },
+};