@hncode/hncode 0.5.0 → 0.5.2

package/src/tools/git.js

@@ -71,11 +71,17 @@ Use this instead of writing \`git\` shell pipelines. Destructive resets are not
         a.push('--stat');
         // paths after --
         const paths = Array.isArray(args.paths) ? args.paths.filter(Boolean) : [];
-        const statR = git.runGit(a.concat(paths.length ? ['--', ...paths] : []), cwd);
+        // ASYNC, with the turn's signal: a `git diff` on a large repository is slow enough that a
+        // synchronous call would freeze the TUI — and with the event loop held, Esc could not even
+        // be read, let alone interrupt it.
+        const statR = await git.runGitAsync(a.concat(paths.length ? ['--', ...paths] : []), cwd, { signal: ctx && ctx.signal });
         if (!statR.ok) return `Error: ${statR.stderr.trim() || statR.error}`;
         if (!statR.stdout.trim()) return args.staged ? 'No staged changes.' : 'No changes.';
         // Also include the full diff, bounded so a huge change cannot flood context.
-        const full = git.runGit(['diff'].concat(args.staged ? ['--cached'] : []).concat(paths.length ? ['--', ...paths] : []), cwd);
+        const full = await git.runGitAsync(
+          ['diff'].concat(args.staged ? ['--cached'] : []).concat(paths.length ? ['--', ...paths] : []),
+          cwd, { signal: ctx && ctx.signal },
+        );
         const MAX = 60 * 1024;
         let body = full.stdout || '';
         let note = '';
@@ -115,7 +121,13 @@ Use this instead of writing \`git\` shell pipelines. Destructive resets are not
 
       case 'log': {
         const n = Math.max(1, Math.min(200, Number(args.count) || 10));
-        const r = git.runGit(['log', `-${n}`, '--pretty=format:%h %ad %s', '--date=short'], cwd);
+        // Async with the signal: `git log` is the slowest call here on a large history, and it is
+        // exactly the one a user presses Esc on.
+        const r = await git.runGitAsync(
+          ['log', `-${n}`, '--pretty=format:%h %ad %s', '--date=short'],
+          cwd, { signal: ctx && ctx.signal },
+        );
+        if (r.error === 'interrupted') return 'Interrupted by user.';
         return r.ok ? (r.stdout.trim() || 'No commits yet.') : `Error: ${r.stderr.trim() || r.error}`;
       }
 

package/src/tools/index.js

@@ -18,6 +18,7 @@ import { spec as agentSpec } from './agent.js';
 import { spec as agentSwarmSpec } from './agent-swarm.js';
 import { TaskListSpec, TaskOutputSpec, TaskStopSpec, TaskWaitSpec } from './tasks.js';
 import { AgentListSpec, AgentMessageSpec, AgentInterruptSpec, AgentCloseSpec } from './agent-control.js';
+import { TEAM_TOOL_SPECS } from './team.js';
 import { spec as notebookSpec } from './notebook.js';
 import { spec as diagnosticsSpec } from './diagnostics.js';
 import * as memoryMod from './memory.js';
@@ -53,6 +54,7 @@ const builtinTools = [
   notebookSpec,
   diagnosticsSpec,
   memoryMod.spec,
+  ...TEAM_TOOL_SPECS,
 ];
 
 

package/src/tools/team.js

@@ -0,0 +1,398 @@
+// The tools a model uses to work with a team.
+//
+//   TeamCreate    start a team (the caller becomes its lead)
+//   TeamDelete    dissolve it
+//   SendMessage   talk to a member, or to everyone
+//   TaskCreate    put work on the shared list
+//   TaskUpdate    change a task's state, and claim or release it
+//   TaskList      read the list
+//
+// Each one is a THIN wrapper: the rules live in team.js / tasks.js / mailbox.js, so a command,
+// a tool and a test all take the same path. A tool that reimplemented "can I claim this" would
+// be a second place for that rule to be wrong.
+import { createTeam, disbandTeam, addMember, removeTeammate, formatRoster, findMember, leadOf } from '../team/team.js';
+import { readTeamFile, formatAgentId } from '../team/store.js';
+import { writeToMailbox, readMailbox, formatInbox } from '../team/mailbox.js';
+import { createTask, updateTask, readTasks, claimTask, releaseTask, formatTasks, TASK_STATES } from '../team/tasks.js';
+import { currentAgent } from '../team/context.js';
+import { leadTeam as sharedLeadTeam, setLeadTeam, clearLeadTeam as sharedClearLeadTeam } from '../session-core.js';
+import { TEAM_LEAD_NAME, BROADCAST } from '../team/constants.js';
+
+// The lead's team lives in session-core.js, because the `/team` command needs it too and a
+// second copy would let the keyboard and the model disagree about which team is active.
+
+/** The team the lead is on, or null. Read by the roster view and by the team command. */
+export function leadTeam() { return sharedLeadTeam(); }
+
+/** Forget the lead's team. Called when it is dissolved. */
+export function clearLeadTeam() { return sharedClearLeadTeam(); }
+
+/**
+ * Who is calling, and which team they are on.
+ *
+ * A teammate's team comes from its AsyncLocalStorage identity; the lead passes the team name
+ * explicitly because it has no identity of its own — `currentAgent()` is undefined for the
+ * person at the keyboard.
+ */
+function caller(args) {
+  const me = currentAgent();
+  if (me) return { name: me.name, teamName: me.teamName, isTeammate: true };
+  return { name: TEAM_LEAD_NAME, teamName: args.team_name || sharedLeadTeam(), isTeammate: false };
+}
+
+function requireTeam(teamName) {
+  if (!teamName) return 'Error: no team. Pass `team_name`, or create one with TeamCreate.';
+  const team = readTeamFile(teamName);
+  if (!team) return `Error: no team "${teamName}". Use TeamCreate first.`;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// TeamCreate
+// ---------------------------------------------------------------------------
+
+export const TeamCreateSpec = {
+  name: 'TeamCreate',
+  get description() {
+    return [
+      'Create a team and become its lead.',
+      '',
+      'A team is a named roster of agents that can message each other and share one task list.',
+      'Use it when the work divides into parts that need to talk — an agent that only needs to',
+      'report back does not need a team; the Agent tool is cheaper.',
+      '',
+      'After creating one, add members with TeamCreate\'s `members` list, then put work on the',
+      'shared list with TaskCreate.',
+    ].join('\n');
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      team_name: { type: 'string', description: 'A short name for the team, e.g. "auth-refactor".' },
+      description: { type: 'string', description: 'What the team is for. Shown to every member.' },
+      members: {
+        type: 'array',
+        description: 'Members to start with. Each gets its own agent, running in the background.',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', description: 'A short name, used to address this member.' },
+            agent_type: { type: 'string', description: 'Its role, e.g. "coder", "tester".' },
+            prompt: { type: 'string', description: 'What it should start doing. Omit to have it ask.' },
+            model: { type: 'string', description: 'Optional model override.' },
+          },
+          required: ['name'],
+        },
+      },
+    },
+    required: ['team_name'],
+  },
+  async execute(args, ctx) {
+    const me = caller(args);
+    if (me.isTeammate) {
+      return { error: 'Error: a teammate cannot create a team. Only the session\'s own agent can.' };
+    }
+    const r = createTeam({
+      teamName: args.team_name,
+      description: args.description,
+      leadSessionId: (ctx && ctx.session && ctx.session.id) || '',
+      cwd: (ctx && ctx.cwd) || process.cwd(),
+    });
+    if (!r.ok) return { error: `Error: ${r.error}` };
+    // Remember it, so every later tool call from the lead knows where it belongs.
+    setLeadTeam(r.team.name);
+
+    const added = [];
+    const refused = [];
+    for (const m of (Array.isArray(args.members) ? args.members : [])) {
+      const a = addMember(args.team_name, {
+        name: m.name,
+        agentType: m.agent_type || 'general',
+        model: m.model || '',
+        prompt: m.prompt || '',
+        cwd: (ctx && ctx.cwd) || process.cwd(),
+      });
+      if (a.ok) added.push({ ...a.member, prompt: m.prompt || '' });
+      else refused.push(`${m.name}: ${a.error}`);
+    }
+
+    // Spawning is the caller's job: this module has no business starting agents, and the TUI
+    // owns the event loop they need. It hands back what to spawn.
+    if (ctx && typeof ctx.spawnTeammates === 'function' && added.length) {
+      try { await ctx.spawnTeammates(args.team_name, added); } catch { /* reported below */ }
+    }
+
+    const lines = [
+      `Team "${r.team.name}" created. You are "${TEAM_LEAD_NAME}".`,
+      r.team.description ? `Purpose: ${r.team.description}` : '',
+      '',
+      formatRoster(readTeamFile(r.team.name)),
+    ].filter(Boolean);
+    if (refused.length) lines.push('', 'Not added:', ...refused.map((x) => `  ${x}`));
+    if (added.length && !(ctx && ctx.spawnTeammates)) {
+      lines.push('', 'Note: these members are on the roster but no agent is running for them yet.');
+    }
+    return { content: lines.join('\n') };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// TeamDelete
+// ---------------------------------------------------------------------------
+
+export const TeamDeleteSpec = {
+  name: 'TeamDelete',
+  description: 'Dissolve a team: tell its members, then remove the roster, the inboxes and the shared task list.',
+  parameters: {
+    type: 'object',
+    properties: {
+      team_name: { type: 'string', description: 'The team to dissolve. Defaults to the caller\'s own team.' },
+      reason: { type: 'string', description: 'Sent to each member before the team goes.' },
+    },
+  },
+  async execute(args) {
+    const me = caller(args);
+    const teamName = me.teamName || args.team_name;
+    const err = requireTeam(teamName);
+    if (err) return { error: err };
+    const r = disbandTeam(teamName, { reason: args.reason || 'the lead ended the team' });
+    if (!r.ok) return { error: `Error: ${r.error}` };
+    if (sharedLeadTeam() === teamName) sharedClearLeadTeam();
+    return { content: `Team "${teamName}" dissolved.${r.told ? ` ${r.told} member(s) were told.` : ''}` };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// SendMessage
+// ---------------------------------------------------------------------------
+
+export const SendMessageSpec = {
+  name: 'SendMessage',
+  get description() {
+    return [
+      'Send a message to a teammate, or to everyone on the team.',
+      '',
+      '`to` is a member name, or "*" to reach every member except yourself.',
+      '',
+      'Messages are delivered to the recipient\'s inbox and read on its next step — so this is',
+      'asynchronous: it does not wait for a reply. Say what you need and move on; the answer',
+      'arrives as a message of its own.',
+      '',
+      'Use it to hand over work, report a result, or ask a question only that member can answer.',
+      'Do not use it to narrate progress — a message that says nothing costs the recipient a turn.',
+    ].join('\n');
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      to: { type: 'string', description: 'A member name, or "*" to message the whole team.' },
+      message: { type: 'string', description: 'The text to send.' },
+      summary: { type: 'string', description: 'Five to ten words for the recipient\'s list view.' },
+    },
+    required: ['to', 'message'],
+  },
+  async execute(args, ctx) {
+    const me = caller(args);
+    const teamName = me.teamName || args.team_name;
+    const err = requireTeam(teamName);
+    if (err) return { error: err };
+
+    const team = readTeamFile(teamName);
+    const text = String(args.message == null ? '' : args.message).trim();
+    if (!text) return { error: 'Error: `message` is empty.' };
+
+    const color = (findMember(teamName, me.name) || {}).color;
+
+    if (args.to === BROADCAST) {
+      // Everyone but the sender. The lead is included when a MEMBER broadcasts — "everyone else"
+      // means the lead too, and leaving it out was why a member's broadcast reached no one.
+      const others = team.members.filter((m) => m.name !== me.name);
+      if (!others.length) return { error: 'Error: there is nobody else on the team to broadcast to.' };
+      for (const m of others) {
+        writeToMailbox(teamName, m.name, { from: me.name, text, summary: args.summary, color });
+      }
+      return { content: `Broadcast to ${others.length} member(s): ${others.map((m) => m.name).join(', ')}` };
+    }
+
+    // `team-lead` is the USER, and it is a real inbox — not a roster entry.
+    //
+    // The user is not a member: their session sits outside the roster, and it reads the boxes
+    // named `leadOf(team)` AND `TEAM_LEAD_NAME` (see `readLeadInbox`). Their own sends carry the
+    // `team-lead` alias, so a teammate answering one addresses `to: 'team-lead'`.
+    //
+    // Resolving that to `leadOf(team)` was wrong: for a team whose only agent IS the lead, the
+    // alias resolved back to the sender, and `SendMessage` refused with "that is you" — so the
+    // report it had just written was never delivered. Writing to the alias directly is what
+    // 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 });
+      return { content: 'Sent to the lead (the user).' };
+    }
+
+    const target = team.members.find((m) => m.name === args.to);
+    if (!target) {
+      // Naming the candidates turns a dead end into a fix.
+      return { error: `Error: no member "${args.to}" on team "${teamName}". Members: ${team.members.map((m) => m.name).join(', ')}` };
+    }
+    if (target.name === me.name) return { error: 'Error: that is you. Pick another member, or "*".' };
+
+    writeToMailbox(teamName, target.name, { from: me.name, text, summary: args.summary, color });
+    return { content: `Sent to ${target.name}.` };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// TaskCreate / TaskUpdate / TaskList
+// ---------------------------------------------------------------------------
+
+export const TeamTaskCreateSpec = {
+  name: 'TeamTaskCreate',
+  description: 'Add a task to the team\'s shared list. Every member sees the same list, so this is how work is divided.',
+  parameters: {
+    type: 'object',
+    properties: {
+      subject: { type: 'string', description: 'One line: what needs doing.' },
+      description: { type: 'string', description: 'Detail a member needs to do it without asking.' },
+      owner: { type: 'string', description: 'A member name to assign it to. Omit to leave it for whoever is free.' },
+      blocked_by: {
+        type: 'array',
+        description: 'Task ids that must finish first, e.g. ["#1"].',
+        items: { type: 'string' },
+      },
+    },
+    required: ['subject'],
+  },
+  async execute(args, ctx) {
+    const me = caller(args);
+    const teamName = me.teamName || args.team_name;
+    const err = requireTeam(teamName);
+    if (err) return { error: err };
+
+    if (args.owner) {
+      const team = readTeamFile(teamName);
+      // The LEAD is addressable by the alias the user's own messages carry, so an owner named
+      // `team-lead` resolves to the agent that actually holds the role.
+      const owner = args.owner === TEAM_LEAD_NAME ? leadOf(teamName) : args.owner;
+      if (!team.members.some((m) => m.name === owner)) {
+        return { error: `Error: no member "${args.owner}". Members: ${team.members.map((m) => m.name).join(', ')}` };
+      }
+    }
+    const t = createTask(teamName, {
+      subject: args.subject,
+      description: args.description,
+      owner: args.owner || null,
+      blockedBy: args.blocked_by,
+      createdBy: me.name,
+    });
+    if (args.owner) updateTask(teamName, t.id, { status: 'in_progress' });
+    return { content: `Created ${t.id}: ${t.subject}${args.owner ? ` (assigned to ${args.owner})` : ''}` };
+  },
+};
+
+export const TeamTaskUpdateSpec = {
+  name: 'TeamTaskUpdate',
+  get description() {
+    return [
+      'Change a task: claim it, release it, or set its state.',
+      '',
+      `status is one of: ${TASK_STATES.join(', ')}.`,
+      '',
+      'Claiming checks the task is not taken and not blocked, and says which when it refuses —',
+      'so a refusal tells you what to do next rather than just failing.',
+    ].join('\n');
+  },
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'The id, e.g. "#3".' },
+      status: { type: 'string', enum: TASK_STATES, description: 'The new state.' },
+      claim: { type: 'boolean', description: 'Take ownership. Refused if someone else has it, or it is blocked.' },
+      release: { type: 'boolean', description: 'Give it back, so another member can take it.' },
+      owner: { type: 'string', description: 'Assign it to a member by name.' },
+      result: { type: 'string', description: 'What came of it. Worth setting when completing.' },
+    },
+    required: ['task_id'],
+  },
+  async execute(args, ctx) {
+    const me = caller(args);
+    const teamName = me.teamName || args.team_name;
+    const err = requireTeam(teamName);
+    if (err) return { error: err };
+    const id = String(args.task_id);
+
+    if (args.claim) {
+      const r = claimTask(teamName, id, me.name);
+      if (!r.ok) return { error: `Error: cannot claim ${id} — ${r.reason}.` };
+      return { content: `Claimed ${id}: ${r.task.subject}` };
+    }
+    if (args.release) {
+      const r = releaseTask(teamName, id, me.name);
+      if (!r.ok) return { error: `Error: ${r.reason}.` };
+      return { content: `Released ${id}.` };
+    }
+
+    const patch = {};
+    if (args.status) patch.status = args.status;
+    if (args.owner) patch.owner = args.owner;
+    if (args.result !== undefined) patch.result = String(args.result);
+    if (!Object.keys(patch).length) return { error: 'Error: nothing to change. Pass status, claim, release, owner or result.' };
+
+    // Completing without saying who did it leaves the list unable to answer "who finished this".
+    if (patch.status === 'completed' && !patch.result && !me.isTeammate) {
+      patch.result = '';
+    }
+    const t = updateTask(teamName, id, patch);
+    if (!t) return { error: `Error: no task ${id} on team "${teamName}".` };
+    return { content: `Updated ${id}: ${t.status}${t.owner ? ` @${t.owner}` : ''} — ${t.subject}` };
+  },
+};
+
+export const TeamTaskListSpec = {
+  name: 'TeamTaskList',
+  description: 'Read the team\'s shared task list: what is unclaimed, what is in flight, what is blocked.',
+  parameters: {
+    type: 'object',
+    properties: {
+      owner: { type: 'string', description: 'Only tasks owned by this member.' },
+      status: { type: 'string', enum: TASK_STATES, description: 'Only tasks in this state.' },
+    },
+  },
+  async execute(args) {
+    const me = caller(args);
+    const teamName = me.teamName || args.team_name;
+    const err = requireTeam(teamName);
+    if (err) return { error: err };
+    let list = readTasks(teamName);
+    if (args.owner) list = list.filter((t) => t.owner === args.owner);
+    if (args.status) list = list.filter((t) => t.status === args.status);
+    return { content: formatTasks(list) };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// ListTeammates — so a member can find out who exists without being told
+// ---------------------------------------------------------------------------
+
+export const ListTeammatesSpec = {
+  name: 'ListTeammates',
+  description: 'The team roster: who is on it, what they are doing, and how much unread mail each has.',
+  parameters: { type: 'object', properties: {} },
+  async execute(args) {
+    const me = caller(args);
+    const teamName = me.teamName || args.team_name;
+    const err = requireTeam(teamName);
+    if (err) return { error: err };
+    return { content: formatRoster(readTeamFile(teamName)) };
+  },
+};
+
+/** Every team tool, for the catalog. */
+export const TEAM_TOOL_SPECS = [
+  TeamCreateSpec,
+  TeamDeleteSpec,
+  SendMessageSpec,
+  TeamTaskCreateSpec,
+  TeamTaskUpdateSpec,
+  TeamTaskListSpec,
+  ListTeammatesSpec,
+];

package/src/tools/web-search.js

@@ -1,75 +1,88 @@
-// WebSearch tool — search the web via Bing's HTML endpoint (no API key needed).
-
-import { htmlToText } from './fetch-url.js';
-
-const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36';
-
-function decodeEntities(s) {
-  return String(s || '')
-    .replace(/ /gi, ' ')
-    .replace(/&/gi, '&')
-    .replace(/&lt;/gi, '<')
-    .replace(/&gt;/gi, '>')
-    .replace(/&quot;/gi, '"')
-    .replace(/&#39;|&apos;/gi, "'")
-    .replace(/&ensp;/gi, ' ')
-    .replace(/&emsp;/gi, ' ')
-    .replace(/&middot;/gi, '·')
-    .replace(/&hellip;/gi, '…')
-    .replace(/&#(\d+);/g, (_, d) => String.fromCharCode(Number(d)));
-}
-
-// Parse Bing's HTML into { title, url, snippet } results.
-export function parseBingResults(html, limit = 8) {
-  const out = [];
-  const blocks = String(html).match(/<li class="b_algo"[\s\S]*?<\/li>/g) || [];
-  for (const block of blocks) {
-    const href = (block.match(/<a[^>]+href="(https?:\/\/[^"]+)"/) || [])[1];
-    if (!href) continue;
-    const titleHtml = (block.match(/<h2[^>]*>[\s\S]*?<a[^>]*>([\s\S]*?)<\/a>/) || [])[1] || '';
-    const title = decodeEntities(titleHtml.replace(/<[^>]+>/g, '')).trim();
-    // Snippet lives in <p> or a caption div; fall back to stripped block text.
-    let snippet = (block.match(/<p[^>]*>([\s\S]*?)<\/p>/) || [])[1]
-      || (block.match(/class="b_caption"[^>]*>[\s\S]*?<p[^>]*>([\s\S]*?)<\/p>/) || [])[1]
-      || '';
-    snippet = decodeEntities(snippet.replace(/<[^>]+>/g, '')).replace(/\s+/g, ' ').trim();
-    if (!snippet) snippet = htmlToText(block).replace(/\s+/g, ' ').slice(0, 240);
-    out.push({ title: title || href, url: href, snippet });
-    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.' },
-    },
-    required: ['query'],
-  },
-  async execute(args, ctx) {
-    const query = String(args.query || '').trim();
-    if (!query) return 'Error: query must not be empty.';
-    const signal = (ctx && ctx.signal) || undefined;
-    const url = 'https://www.bing.com/search?q=' + encodeURIComponent(query) + '&setlang=en';
-    try {
-      const res = await fetch(url, {
-        headers: { 'User-Agent': UA, 'Accept-Language': 'en-US,en;q=0.9' },
-        signal,
-      });
-      if (!res.ok) return `Error: search failed (${res.status} ${res.statusText}).`;
-      const html = await res.text();
-      const results = parseBingResults(html, 8);
-      if (!results.length) return `No search results found for: ${query}`;
-      return results
-        .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}\n   ${r.snippet}`)
-        .join('\n\n');
-    } 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, 知乎, 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}`;
+    }
+  },
+};