@pi-archimedes/web 2.10.3 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/web",
-  "version": "2.10.3",
+  "version": "2.11.0",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -14,7 +14,7 @@
   ],
   "dependencies": {
     "@mozilla/readability": "^0.6.0",
-    "@pi-archimedes/core": "2.10.3",
+    "@pi-archimedes/core": "2.11.0",
     "linkedom": "^0.18.9",
     "p-limit": "^6.2.0",
     "turndown": "^7.2.0",
@@ -22,16 +22,16 @@
     "undici": "^7.4.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
-    "@types/node": "^22.0.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
+    "@types/node": "22.19.19",
     "@types/turndown": "^5.0.5",
     "typebox": "^1.1.38",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.1.0",
-    "@earendil-works/pi-tui": ">=0.1.0",
+    "@earendil-works/pi-coding-agent": ">=0.99.0",
+    "@earendil-works/pi-tui": ">=0.99.0",
     "typebox": ">=1.1.0"
   },
   "pi": {

package/src/command.ts

@@ -16,7 +16,9 @@ export function registerCommand(pi: ExtensionAPI) {
           break;
         }
         case "status": {
-          const config = loadConfig();
+          // `pi` from the enclosing registerCommand — `/web status` reports the
+          // provider the *effective* settings pick, project scope included.
+          const config = loadConfig(pi);
           const provider = resolveProvider(undefined, config);
           const stats = getCacheStats();
           ctx.ui.notify(`Active provider: ${provider.name}\nCache: ${stats.count} items, ${stats.estimatedBytes} bytes`);
@@ -28,7 +30,7 @@ export function registerCommand(pi: ExtensionAPI) {
             ctx.ui.notify("Usage: /web search <query>");
             return;
           }
-          const config = loadConfig();
+          const config = loadConfig(pi);
           const results = await executeSearch([query], {}, config);
           const summary = `Found ${results.results.length} results using ${results.provider}:\n${results.results.map(r => `- ${r.title}: ${r.url}`).join("\n")}`;
           ctx.ui.notify(summary, "info");

package/src/config.test.ts

@@ -0,0 +1,152 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// ── Where web's config comes from ───────────────────────────────────────────
+//
+// `loadConfig()` used to read `~/.pi/agent/settings.json` by hand, which cannot
+// see project-scoped settings (`<cwd>/.pi/settings.json`) or in-process
+// overrides — so a key configured only in the project file was invisible to the
+// search tools while `pi.getSettings()` could see it. The handle is threaded in
+// from the tool/command call sites, which have it; `getSettings()` lives on
+// ExtensionAPI, not on ExtensionContext, so it has to be `pi` and not `ctx`.
+
+const { tempDir, fs, join, randomUUID } = vi.hoisted(() => {
+  const fs = require("node:fs");
+  const { join } = require("node:path");
+  const { tmpdir } = require("node:os");
+  const { randomUUID } = require("node:crypto");
+  const dir = join(tmpdir(), `web-config-test-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return { tempDir: dir, fs, join, tmpdir, randomUUID };
+});
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => tempDir,
+}));
+
+const { loadConfig } = await import("./config.js");
+
+const settingsPath = () => join(tempDir, "settings.json");
+
+/** The env vars loadConfig consults first — cleared so tests are deterministic. */
+const ENV_KEYS = [
+  "BRAVE_API_KEY",
+  "TAVILY_API_KEY",
+  "OPENAI_API_KEY",
+  "PERPLEXITY_API_KEY",
+  "SEARXNG_URL",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+] as const;
+
+let savedEnv: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+  savedEnv = {};
+  for (const key of ENV_KEYS) {
+    savedEnv[key] = process.env[key];
+    delete process.env[key];
+  }
+  try {
+    fs.unlinkSync(settingsPath());
+  } catch {
+    /* ignore */
+  }
+});
+
+afterEach(() => {
+  for (const key of ENV_KEYS) {
+    if (savedEnv[key] === undefined) delete process.env[key];
+    else process.env[key] = savedEnv[key];
+  }
+  try {
+    fs.unlinkSync(settingsPath());
+  } catch {
+    /* ignore */
+  }
+});
+
+describe("loadConfig with an ExtensionAPI handle", () => {
+  it("sees a key that exists only in the effective settings (project scope)", () => {
+    // The global file says nothing about web at all; the value lives in the
+    // project's `.pi/settings.json`, which only pi's merged view contains.
+    fs.writeFileSync(settingsPath(), JSON.stringify({ theme: "dark" }), "utf-8");
+    const pi = {
+      getSettings: () => ({ "archimedes.web": { braveApiKey: "project-only-key" } }),
+    };
+    expect(loadConfig(pi as never).braveApiKey).toBe("project-only-key");
+  });
+
+  it("prefers the effective settings over the file when both carry a value", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ "archimedes.web": { braveApiKey: "global-key", defaultProvider: "brave" } }),
+      "utf-8",
+    );
+    const pi = {
+      getSettings: () => ({ "archimedes.web": { braveApiKey: "effective-key" } }),
+    };
+    const config = loadConfig(pi as never);
+    expect(config.braveApiKey).toBe("effective-key");
+    // Whatever the effective object does not carry is simply absent: it is the
+    // effective view, not a merge with our private file read.
+    expect(config.defaultProvider).toBeUndefined();
+  });
+
+  it("carries the rest of the namespace through (provider selection sees project config)", () => {
+    const pi = {
+      getSettings: () => ({
+        "archimedes.web": { defaultProvider: "tavily", tavilyApiKey: "tvly-project" },
+      }),
+    };
+    const config = loadConfig(pi as never);
+    expect(config.defaultProvider).toBe("tavily");
+    expect(config.tavilyApiKey).toBe("tvly-project");
+  });
+
+  it("an env var still outranks both sources (unchanged precedence)", () => {
+    const pi = {
+      getSettings: () => ({ "archimedes.web": { braveApiKey: "effective-key" } }),
+    };
+    process.env.BRAVE_API_KEY = "env-key";
+    expect(loadConfig(pi as never).braveApiKey).toBe("env-key");
+  });
+});
+
+describe("loadConfig without a usable handle (the fallback that keeps core's floor)", () => {
+  it("reads settings.json when no handle is passed", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ "archimedes.web": { braveApiKey: "file-key" } }),
+      "utf-8",
+    );
+    expect(loadConfig().braveApiKey).toBe("file-key");
+  });
+
+  it("reads settings.json when the host predates getSettings()", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ "archimedes.web": { searxngUrl: "http://localhost:8888" } }),
+      "utf-8",
+    );
+    expect(loadConfig({} as never).searxngUrl).toBe("http://localhost:8888");
+  });
+
+  it("reads settings.json when getSettings() throws", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ "archimedes.web": { braveApiKey: "file-key" } }),
+      "utf-8",
+    );
+    const pi = {
+      getSettings: () => {
+        throw new Error("Extension is not active");
+      },
+    };
+    expect(loadConfig(pi as never).braveApiKey).toBe("file-key");
+  });
+
+  it("yields an empty config when there is nothing anywhere, and never writes", () => {
+    expect(loadConfig()).toEqual({});
+    expect(fs.existsSync(settingsPath())).toBe(false);
+  });
+});

package/src/config.ts

@@ -1,4 +1,5 @@
-import { loadConfig as loadSettings } from "@pi-archimedes/core/settings-io";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readEffectiveSettings } from "@pi-archimedes/core/settings-io";
 
 export interface WebConfig {
   braveApiKey?: string;
@@ -10,16 +11,31 @@ export interface WebConfig {
   defaultProvider?: string;
 }
 
-export function loadConfig(): WebConfig {
-  const fileConfig = loadSettings("archimedes.web", {}) as Record<string, any>;
-  
+/**
+ * The web package's view of settings, from the effective settings the running pi
+ * applies.
+ *
+ * `pi` is the `ExtensionAPI` handle, threaded in by the tool `execute` and the
+ * `/web` command handler — the two places that have it. It is optional because
+ * it is not always available (and older pi has no `getSettings`), and
+ * `readEffectiveSettings` falls back to reading `~/.pi/agent/settings.json` by
+ * hand in that case. Passing the handle is what makes a key configured only in
+ * the project's `.pi/settings.json`, or set by an in-process override, visible
+ * here: the hand-rolled file read sees the global file and nothing else.
+ *
+ * Note the handle is used and then dropped — it is never stored.
+ */
+export function loadConfig(pi?: ExtensionAPI): WebConfig {
+  const effective = readEffectiveSettings(pi);
+  const config = (effective["archimedes.web"] ?? {}) as Record<string, any>;
+
   return {
-    braveApiKey: process.env.BRAVE_API_KEY || fileConfig.braveApiKey,
-    tavilyApiKey: process.env.TAVILY_API_KEY || fileConfig.tavilyApiKey,
-    openaiApiKey: process.env.OPENAI_API_KEY || fileConfig.openaiApiKey,
-    perplexityApiKey: process.env.PERPLEXITY_API_KEY || fileConfig.perplexityApiKey,
-    searxngUrl: process.env.SEARXNG_URL || fileConfig.searxngUrl,
-    proxy: process.env.HTTP_PROXY || process.env.HTTPS_PROXY || fileConfig.proxy,
-    defaultProvider: fileConfig.defaultProvider,
+    braveApiKey: process.env.BRAVE_API_KEY || config.braveApiKey,
+    tavilyApiKey: process.env.TAVILY_API_KEY || config.tavilyApiKey,
+    openaiApiKey: process.env.OPENAI_API_KEY || config.openaiApiKey,
+    perplexityApiKey: process.env.PERPLEXITY_API_KEY || config.perplexityApiKey,
+    searxngUrl: process.env.SEARXNG_URL || config.searxngUrl,
+    proxy: process.env.HTTP_PROXY || process.env.HTTPS_PROXY || config.proxy,
+    defaultProvider: config.defaultProvider,
   };
-}
+}

package/src/renderer.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import { Text } from '@earendil-works/pi-tui';
-import { reuseText, sanitizeStatus, renderWebSearchCall } from './renderer.js';
+import { reuseText, sanitizeStatus, renderWebSearchCall, renderGetSearchContentResult } from './renderer.js';
 
 describe('renderer', () => {
   it('reuseText recycles existing Text component', () => {
@@ -29,3 +29,49 @@ describe('renderer', () => {
     }).not.toThrow();
   });
 });
+
+describe('renderGetSearchContentResult', () => {
+  // Records the theme token each fragment is coloured with, so a test can tell
+  // an error row ("error" token, ✗) from a success row ("success", ✓).
+  const theme = { fg: (token: string, s: string) => `${token}:${s}`, bold: (s: string) => s } as any;
+  // One context per call: reuseText() recycles `lastComponent`, and the
+  // collapsed and expanded rows under test must not share a component.
+  const fresh = () => ({ lastComponent: new Text('', 0, 0) });
+  const row = (result: unknown, expanded: boolean) =>
+    renderGetSearchContentResult(result, { expanded, isPartial: false }, theme, fresh()).render(200).join('\n');
+
+  // The cache-miss result exactly as `get_search_content` returns it: reported
+  // with isError, so the row must not read as a successful retrieval.
+  const miss = {
+    content: [{ type: 'text', text: 'Response not found' }],
+    details: { responseId: 'web_missing', error: 'Response not found' },
+    isError: true,
+  };
+
+  it('collapses to an error row naming the failure, not "Content retrieved"', () => {
+    const rendered = row(miss, false);
+    expect(rendered).toContain('✗');
+    expect(rendered).toContain('error:');
+    expect(rendered).toContain('Response not found');
+    expect(rendered).not.toContain('Content retrieved');
+    expect(rendered).not.toContain('✓');
+  });
+
+  it('expands to the failure text, not the "No content found" placeholder', () => {
+    const rendered = row(miss, true);
+    expect(rendered).toContain('Response not found');
+    expect(rendered).not.toContain('No content found');
+  });
+
+  it('a successful retrieval still renders its success row (the fix is not a blanket error)', () => {
+    const ok = { content: [{ type: 'text', text: 'cached body' }], details: { content: 'cached body' } };
+    const rendered = row(ok, false);
+    expect(rendered).toContain('✓');
+    expect(rendered).toContain('11 characters');
+  });
+
+  it('a passages row still renders its passage count', () => {
+    const ok = { content: [{ type: 'text', text: '[]' }], details: { matches: [{ passage: 'p', offset: 0, match: 'm' }] } };
+    expect(row(ok, false)).toContain('Found 1 passages');
+  });
+});

package/src/renderer.ts

@@ -135,6 +135,17 @@ export function renderGetSearchContentResult(result: unknown, options: { expande
       text.setText(renderStatusLabel("error", sanitizeStatus("No details"), theme));
       return text;
     }
+
+    // A failed lookup (`Response not found`) is reported with `isError`, and pi
+    // hands a renderer only `{ content, details }` — the flag itself is not in
+    // what this function is given (`modes/interactive/components/
+    // tool-execution.js:243`) — so `details.error` is what a row can read. Without
+    // this branch the row said “✓ Content retrieved” for a call that retrieved
+    // nothing, and expanding said “No content found”.
+    if (details.error) {
+      text.setText(renderStatusLabel("error", sanitizeStatus(details.error), theme));
+      return text;
+    }
     
     if (options?.expanded) {
       text.setText(sanitizeExpanded(details.matches ? details.matches.map((m: any) => m.passage).join("\n\n") : (details.content ?? "No content found")));

package/src/tool-declarations.test.ts

@@ -0,0 +1,52 @@
+/**
+ * Task 11 item 3 — how the web tools are declared to the model and to scripts.
+ *
+ * `openWorldHint` is the MCP hint for "this reaches outside the closed domain",
+ * which is exactly what a search provider and an HTTP fetch do. pi documents
+ * `annotations` as author-declared and unverified — a permission gate's input,
+ * not a guarantee (`pi: dist/core/extensions/types.d.ts`, `ToolAnnotations`).
+ *
+ * The exposure assertion is the negative half of the plan: these tools stay
+ * `direct`. `codemode`/`deferred` would take their declarations away from the
+ * model, and the suite does not register virtual models or MCP servers
+ * (ADR 0029), so nothing would put them back.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { registerTools } from "./tools.js";
+
+vi.mock("./config.js", () => ({ loadConfig: () => ({}) }));
+
+type RegisteredTool = {
+  name: string;
+  annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean };
+  exposure?: string;
+};
+
+const tools: Record<string, RegisteredTool> = {};
+registerTools({ registerTool: (t: unknown) => { const tool = t as RegisteredTool; tools[tool.name] = tool; } } as never);
+
+const names = ["web_search", "fetch_content", "get_search_content"];
+
+describe("web tool annotations", () => {
+  it.each(names)("%s declares openWorldHint", (name) => {
+    expect(tools[name]!.annotations?.openWorldHint).toBe(true);
+  });
+
+  it.each(names)("%s declares nothing it has not earned", (name) => {
+    const annotations = tools[name]!.annotations ?? {};
+    // Only `openWorldHint` is declared. The others are claims this suite has
+    // not verified and a permission gate would have to take on trust: a fetch
+    // writes to the in-process response cache, so "read-only" is not plainly
+    // true of these handlers either.
+    expect(annotations.readOnlyHint).toBeUndefined();
+    expect(annotations.destructiveHint).toBeUndefined();
+    expect(annotations.idempotentHint).toBeUndefined();
+  });
+});
+
+describe("web tool exposure", () => {
+  it.each(names)("%s stays direct: declared to the model and callable from scripts", (name) => {
+    expect(tools[name]!.exposure ?? "direct").toBe("direct");
+  });
+});

package/src/tools.output-schema.test.ts

@@ -0,0 +1,305 @@
+/**
+ * Task 11 item 2 — `web_search`, `fetch_content` and `get_search_content` as
+ * programmatic tools.
+ *
+ * Same referee as `todo`'s: the payloads come from the real handlers, and are
+ * validated against the `outputSchema` the registered tool declares
+ * (`pi` hands a codemode script `structuredContent` only when one is declared,
+ * and validates nothing). The providers and the cache are mocked so the shapes
+ * under test are the ones the real modules produce — `SearchResultItem`,
+ * the extractor's document fields, and `PassageResult` — not invented ones.
+ *
+ * The third group is the throw-to-`isError` change. All three handlers used to
+ * let a provider failure (or a cache miss) escape; `pi` turned that into an
+ * error result whose text was the message (`pi-agent-core: agent-loop.js`,
+ * `createErrorToolResult()`, which also attaches `details: {}`). Returning
+ * `isError: true` keeps that text byte-identical and moves the failure report
+ * out of the harness and into the handler, where the tool can say what it
+ * knows. See `AgentToolResult.isError`.
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Value } from "typebox/value";
+import { registerTools } from "./tools.js";
+
+const { executeSearch, extractContent, getResponse, findPassages } = vi.hoisted(() => ({
+  executeSearch: vi.fn(),
+  extractContent: vi.fn(),
+  getResponse: vi.fn(),
+  findPassages: vi.fn(),
+}));
+
+vi.mock("./config.js", () => ({ loadConfig: () => ({}) }));
+vi.mock("./providers/registry.js", () => ({ executeSearch }));
+vi.mock("./extractors/pipeline.js", () => ({ extractContent }));
+vi.mock("./storage/cache.js", () => ({
+  storeResponse: () => "web_test_1",
+  getResponse,
+}));
+vi.mock("./storage/find.js", () => ({ findPassages }));
+
+type RegisteredTool = {
+  name: string;
+  outputSchema?: unknown;
+  execute: (
+    id: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<{
+    content: Array<{ type: "text"; text: string }>;
+    details: unknown;
+    structuredContent?: unknown;
+    isError?: boolean;
+  }>;
+};
+
+function register(): Record<string, RegisteredTool> {
+  const tools: Record<string, RegisteredTool> = {};
+  registerTools({
+    registerTool: (t: unknown) => {
+      const tool = t as RegisteredTool;
+      tools[tool.name] = tool;
+    },
+  } as never);
+  return tools;
+}
+
+const tools = register();
+
+function check(tool: RegisteredTool, value: unknown): boolean {
+  expect(tool.outputSchema, `${tool.name} declares no outputSchema`).toBeDefined();
+  return Value.Check(tool.outputSchema as never, value);
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  executeSearch.mockResolvedValue({
+    provider: "test-provider",
+    results: [
+      { title: "First", url: "https://example.com/1", snippet: "snap one" },
+      {
+        title: "Second",
+        url: "https://example.com/2",
+        snippet: "snap two",
+        publishedDate: "2026-01-02",
+      },
+    ],
+  });
+  extractContent.mockResolvedValue({
+    url: "https://example.com/page",
+    title: "A page",
+    markdown: "# A page\nbody text",
+    wordCount: 42,
+    status: 200,
+    extractor: "readability",
+  });
+  getResponse.mockReturnValue({
+    id: "web_test_1",
+    type: "search",
+    content: "cached body",
+    timestamp: 1,
+  });
+  findPassages.mockReturnValue([{ passage: "…cached body…", offset: 2, match: "body" }]);
+});
+
+describe("outputSchema declarations", () => {
+  it("all three web tools declare one", () => {
+    for (const name of ["web_search", "fetch_content", "get_search_content"]) {
+      expect(tools[name]!.outputSchema, `${name} declares no outputSchema`).toBeDefined();
+    }
+  });
+
+});
+
+describe("web_search", () => {
+  it("success → structuredContent mirrors the details the renderer already uses", async () => {
+    const tool = tools.web_search!;
+    const result = await tool.execute("c1", { query: "pi" }, undefined, undefined, {});
+    expect(result.content[0]!.text).toBe(
+      "[First](https://example.com/1)\n[Second](https://example.com/2)",
+    );
+    expect(result.structuredContent).toEqual({
+      responseId: "web_test_1",
+      provider: "test-provider",
+      resultCount: 2,
+      results: [
+        { title: "First", url: "https://example.com/1", snippet: "snap one" },
+        {
+          title: "Second",
+          url: "https://example.com/2",
+          snippet: "snap two",
+          publishedDate: "2026-01-02",
+        },
+      ],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("a provider that rejects comes back as isError, not a thrown error", async () => {
+    executeSearch.mockRejectedValueOnce(new Error("provider exploded"));
+    const tool = tools.web_search!;
+    const result = await tool.execute("c1", { query: "pi" }, undefined, undefined, {});
+    expect(result.isError).toBe(true);
+    // Same text pi's own catch produced from the throw.
+    expect(result.content[0]!.text).toBe("provider exploded");
+    expect("structuredContent" in result).toBe(false);
+  });
+
+  it("a hit with no publishedDate omits the optional, and still validates", async () => {
+    executeSearch.mockResolvedValueOnce({
+      provider: "p",
+      results: [{ title: "No date", url: "https://example.com/nd", snippet: "s" }],
+    });
+    const tool = tools.web_search!;
+    const result = await tool.execute("c1", { query: "pi" }, undefined, undefined, {});
+    expect((result.structuredContent as { results: Array<Record<string, unknown>> }).results[0]).toEqual({
+      title: "No date",
+      url: "https://example.com/nd",
+      snippet: "s",
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("zero hits → results: [], still valid", async () => {
+    executeSearch.mockResolvedValueOnce({ provider: "p", results: [] });
+    const tool = tools.web_search!;
+    const result = await tool.execute("c1", { query: "nothing matches this" }, undefined, undefined, {});
+    expect(result.structuredContent).toEqual({ responseId: "web_test_1", provider: "p", resultCount: 0, results: [] });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+});
+
+describe("fetch_content", () => {
+  it("success → structuredContent mirrors the details", async () => {
+    const tool = tools.fetch_content!;
+    const result = await tool.execute("c2", { url: "https://example.com/page" }, undefined, undefined, {});
+    expect(result.content[0]!.text).toBe("# A page\nbody text");
+    expect(result.structuredContent).toEqual({
+      responseId: "web_test_1",
+      url: "https://example.com/page",
+      title: "A page",
+      wordCount: 42,
+      status: 200,
+      extractor: "readability",
+      content: "# A page\nbody text",
+      snippet: "# A page\nbody text",
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("an extractor that rejects comes back as isError, not a thrown error", async () => {
+    extractContent.mockRejectedValueOnce(new Error("HTTP 404"));
+    const tool = tools.fetch_content!;
+    const result = await tool.execute("c2", { url: "https://example.com/x" }, undefined, undefined, {});
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toBe("HTTP 404");
+    expect("structuredContent" in result).toBe(false);
+  });
+
+  it("a document longer than the snippet keeps its FULL text in structuredContent", async () => {
+    // Declaring `outputSchema` moves a script from the text (the whole document)
+    // to the structured content (pi: `toScriptValue()`), so the structured
+    // payload has to carry what the text used to — a 500-character window is not
+    // the document. pi's own `bash` does the same: `structuredContent.output`
+    // holds the output, not a preview (`core/tools/bash.js`).
+    const long = "# Heading\n" + "word ".repeat(400);
+    extractContent.mockResolvedValueOnce({
+      url: "https://example.com/long",
+      title: "Long page",
+      markdown: long,
+      wordCount: 401,
+      status: 200,
+      extractor: "readability",
+    });
+    const tool = tools.fetch_content!;
+    const result = await tool.execute("c2", { url: "https://example.com/long" }, undefined, undefined, {});
+    const structured = result.structuredContent as Record<string, unknown>;
+    // The model still reads the whole document from `content`…
+    expect(result.content[0]!.text).toBe(long);
+    // …and so does a script, which never sees `content`.
+    expect(structured["content"]).toBe(long);
+    // The glanceable window stays, unchanged.
+    expect(structured["snippet"]).toBe(long.slice(0, 500));
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+});
+
+describe("get_search_content", () => {
+  it("content branch → { responseId, content }", async () => {
+    const tool = tools.get_search_content!;
+    const result = await tool.execute("c3", { responseId: "web_test_1" }, undefined, undefined, {});
+    expect(result.content[0]!.text).toBe("cached body");
+    expect(result.structuredContent).toEqual({ responseId: "web_test_1", content: "cached body" });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("offset/limit branch → the slice actually handed back", async () => {
+    const tool = tools.get_search_content!;
+    const result = await tool.execute(
+      "c3",
+      { responseId: "web_test_1", offset: 1, limit: 3 },
+      undefined,
+      undefined,
+      {},
+    );
+    expect(result.structuredContent).toEqual({ responseId: "web_test_1", content: "ach" });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("limit 0 → empty content, still valid against the schema", async () => {
+    const tool = tools.get_search_content!;
+    const result = await tool.execute("c3", { responseId: "web_test_1", limit: 0 }, undefined, undefined, {});
+    expect(result.structuredContent).toEqual({ responseId: "web_test_1", content: "" });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("findText branch → { responseId, matches }, passages with offset and match", async () => {
+    const tool = tools.get_search_content!;
+    const result = await tool.execute(
+      "c3",
+      { responseId: "web_test_1", findText: "body" },
+      undefined,
+      undefined,
+      {},
+    );
+    expect(result.content[0]!.text).toBe(JSON.stringify([{ passage: "…cached body…", offset: 2, match: "body" }]));
+    expect(result.structuredContent).toEqual({
+      responseId: "web_test_1",
+      matches: [{ passage: "…cached body…", offset: 2, match: "body" }],
+    });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("an unknown responseId is an isError result, not a thrown Error", async () => {
+    getResponse.mockReturnValue(undefined);
+    const tool = tools.get_search_content!;
+    const result = await tool.execute("c3", { responseId: "web_missing" }, undefined, undefined, {});
+    expect(result.isError).toBe(true);
+    // Byte-identical to the text pi built from `throw new Error("Response not found")`.
+    expect(result.content[0]!.text).toBe("Response not found");
+    expect("structuredContent" in result).toBe(false);
+  });
+
+  it("findText with no matches → matches: [] — the union's second branch, empty", async () => {
+    findPassages.mockReturnValueOnce([]);
+    const tool = tools.get_search_content!;
+    const result = await tool.execute(
+      "c3",
+      { responseId: "web_test_1", findText: "not in the cache" },
+      undefined,
+      undefined,
+      {},
+    );
+    expect(result.structuredContent).toEqual({ responseId: "web_test_1", matches: [] });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+
+  it("an offset past the end → empty content, first branch still valid", async () => {
+    const tool = tools.get_search_content!;
+    const result = await tool.execute("c3", { responseId: "web_test_1", offset: 999 }, undefined, undefined, {});
+    expect(result.structuredContent).toEqual({ responseId: "web_test_1", content: "" });
+    expect(check(tool, result.structuredContent)).toBe(true);
+  });
+});

package/src/tools.ts

@@ -2,7 +2,9 @@ import { Type } from "typebox";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadConfig } from "./config.js";
 import { executeSearch } from "./providers/registry.js";
+import type { SearchResultItem } from "./providers/types.js";
 import { extractContent } from "./extractors/pipeline.js";
+import type { ExtractedDoc } from "./extractors/types.js";
 import { storeResponse, getResponse } from "./storage/cache.js";
 import { findPassages } from "./storage/find.js";
 import {
@@ -11,6 +13,81 @@ import {
   renderGetSearchContentCall, renderGetSearchContentResult
 } from "./renderer.js";
 
+// ── Output schemas ───────────────────────────────────────────────────────────
+//
+// Each schema describes the `structuredContent` the handler really returns, so
+// a codemode script resolves to structure where it used to resolve to the
+// text (`pi: dist/extensions/codemode/execute.js`, `toScriptValue()`). pi does
+// not validate one against the other, so `tools.output-schema.test.ts` runs the
+// handlers and validates the payloads against these declarations.
+//
+// Failure results carry no structured content: a provider that failed, a page
+// that could not be fetched and a cache miss are all calls that produced no
+// observation, so a script keeps rejecting with the same text it rejected with
+// before these schemas existed. (pi's own `bash` does the opposite for a
+// non-zero exit, where the failing command *is* the observation.)
+//
+// Exposure is left at `direct` for all three on purpose: `codemode`/`deferred`
+// would take the declarations away from the model, and with no virtual model and
+// no MCP server registered (ADR 0029) nothing would hand them back.
+
+/** One hit, as the providers produce them (`SearchResultItem`). */
+const SearchResultItemSchema = Type.Object({
+  title: Type.String(),
+  url: Type.String(),
+  snippet: Type.String(),
+  publishedDate: Type.Optional(Type.String()),
+});
+
+const WebSearchOutputSchema = Type.Object({
+  /** Id to hand `get_search_content` to page through this response. */
+  responseId: Type.String(),
+  provider: Type.String(),
+  resultCount: Type.Number(),
+  results: Type.Array(SearchResultItemSchema),
+});
+
+const FetchContentOutputSchema = Type.Object({
+  responseId: Type.String(),
+  url: Type.String({ description: "The URL the document was read from, after redirects" }),
+  title: Type.String(),
+  wordCount: Type.Number(),
+  status: Type.Number({ description: "HTTP status of the fetch" }),
+  extractor: Type.String(),
+  /**
+   * The whole document, the same text the `content` block carries. A script
+   * cannot read that block — declaring `outputSchema` makes pi hand it this
+   * object instead (`toScriptValue()`) — so the document itself belongs here,
+   * as it does in pi's own `bash`, whose `structuredContent.output` is the
+   * output rather than a preview (`core/tools/bash.js`).
+   */
+  content: Type.String({ description: "The full extracted document, exactly as the content block reports it" }),
+  /** First 500 characters of `content`, for a glanceable confirmation. */
+  snippet: Type.String(),
+});
+
+const PassageOutputSchema = Type.Object({
+  passage: Type.String(),
+  offset: Type.Number(),
+  match: Type.String(),
+});
+
+// The two shapes this tool can answer with: passages for `findText`, text for
+// everything else.
+const GetSearchContentOutputSchema = Type.Union([
+  Type.Object({ responseId: Type.String(), content: Type.String() }),
+  Type.Object({ responseId: Type.String(), matches: Type.Array(PassageOutputSchema) }),
+]);
+
+/**
+ * The text pi builds from a thrown error (`pi-agent-core: agent-loop.js`,
+ * `createErrorToolResult()`), so reporting a failure as `isError` instead of
+ * throwing leaves the model-facing text byte-identical.
+ */
+function failureText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 export function registerTools(pi: ExtensionAPI) {
   pi.registerTool({
     name: "web_search",
@@ -25,20 +102,38 @@ export function registerTools(pi: ExtensionAPI) {
       domainFilter: Type.Optional(Type.Array(Type.String())),
       proxy: Type.Optional(Type.String()),
     }),
+    outputSchema: WebSearchOutputSchema,
+    // Results come from outside this session's domain, which is what the MCP
+    // hint means. Author-declared and unverified: pi documents `annotations` as
+    // the input for a permission gate, not as a guarantee.
+    annotations: { openWorldHint: true },
     renderCall: renderWebSearchCall,
     renderResult: renderWebSearchResult,
     execute: async (_toolCallId, params, signal, _onUpdate, _ctx) => {
-      const config = loadConfig();
+      // `pi` comes from the enclosing registerTools: `getSettings()` is an
+      // ExtensionAPI method, so a tool's own ctx cannot answer it.
+      const config = loadConfig(pi);
       const queries = params.queries ?? (params.query ? [params.query] : []);
       const proxy = params.proxy ?? config.proxy;
-      const { provider, results } = await executeSearch(queries, {
-        ...(params.numResults !== undefined && { numResults: params.numResults }),
-        ...(params.recencyFilter !== undefined && { recencyFilter: params.recencyFilter }),
-        ...(params.domainFilter !== undefined && { domainFilter: params.domainFilter }),
-        ...(proxy !== undefined && { proxy }),
-        signal
-      }, config);
-      
+      let search: { provider: string; results: SearchResultItem[] };
+      try {
+        search = await executeSearch(queries, {
+          ...(params.numResults !== undefined && { numResults: params.numResults }),
+          ...(params.recencyFilter !== undefined && { recencyFilter: params.recencyFilter }),
+          ...(params.domainFilter !== undefined && { domainFilter: params.domainFilter }),
+          ...(proxy !== undefined && { proxy }),
+          signal
+        }, config);
+      } catch (error) {
+        // Reported, not thrown: same text pi would have built from the throw.
+        return {
+          content: [{ type: "text", text: failureText(error) }],
+          details: { error: failureText(error) },
+          isError: true,
+        };
+      }
+      const { provider, results } = search;
+
       const summary = results.map(r => `[${r.title}](${r.url})`).join('\n');
       const responseId = storeResponse({
         type: "search",
@@ -48,7 +143,18 @@ export function registerTools(pi: ExtensionAPI) {
       
       return { 
         content: [{ type: "text", text: summary }], 
-        details: { responseId, provider, resultCount: results.length, results } 
+        details: { responseId, provider, resultCount: results.length, results },
+        structuredContent: {
+          responseId,
+          provider,
+          resultCount: results.length,
+          results: results.map((r) => ({
+            title: r.title,
+            url: r.url,
+            snippet: r.snippet,
+            ...(r.publishedDate !== undefined && { publishedDate: r.publishedDate }),
+          })),
+        },
       };
     },
   });
@@ -63,25 +169,47 @@ export function registerTools(pi: ExtensionAPI) {
       prompt: Type.Optional(Type.String()),
       proxy: Type.Optional(Type.String()),
     }),
+    outputSchema: FetchContentOutputSchema,
+    annotations: { openWorldHint: true },
     renderCall: renderFetchContentCall,
     renderResult: renderFetchContentResult,
     execute: async (_toolCallId, params, signal, _onUpdate, _ctx) => {
-      const config = loadConfig();
+      const config = loadConfig(pi);
       const proxy = params.proxy ?? config.proxy;
-      const doc = await extractContent(params.url, params.mode ?? "readable", { 
-        ...(params.prompt !== undefined && { prompt: params.prompt }),
-        ...(proxy !== undefined && { proxy }),
-        signal: signal ?? undefined
-      });
+      let doc: ExtractedDoc;
+      try {
+        doc = await extractContent(params.url, params.mode ?? "readable", { 
+          ...(params.prompt !== undefined && { prompt: params.prompt }),
+          ...(proxy !== undefined && { proxy }),
+          signal: signal ?? undefined
+        });
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: failureText(error) }],
+          details: { error: failureText(error) },
+          isError: true,
+        };
+      }
       const responseId = storeResponse({
         type: "fetch",
         content: doc.markdown,
         metadata: { url: doc.url, title: doc.title, wordCount: doc.wordCount, status: doc.status, extractor: doc.extractor },
       });
+      const snippet = doc.markdown.slice(0, 500);
       
       return { 
         content: [{ type: "text", text: doc.markdown }], 
-        details: { responseId, url: doc.url, title: doc.title, wordCount: doc.wordCount, status: doc.status, extractor: doc.extractor, snippet: doc.markdown.slice(0, 500) } 
+        details: { responseId, url: doc.url, title: doc.title, wordCount: doc.wordCount, status: doc.status, extractor: doc.extractor, snippet } ,
+        structuredContent: {
+          responseId,
+          url: doc.url,
+          title: doc.title,
+          wordCount: doc.wordCount,
+          status: doc.status,
+          extractor: doc.extractor,
+          content: doc.markdown,
+          snippet,
+        },
       };
     },
   });
@@ -96,21 +224,48 @@ export function registerTools(pi: ExtensionAPI) {
       offset: Type.Optional(Type.Number()),
       limit: Type.Optional(Type.Number()),
     }),
+    outputSchema: GetSearchContentOutputSchema,
+    annotations: { openWorldHint: true },
     renderCall: renderGetSearchContentCall,
     renderResult: renderGetSearchContentResult,
     execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
       const item = getResponse(params.responseId);
-      if (!item) throw new Error("Response not found");
+      if (!item) {
+        // Reported, not thrown: pi turned this throw into an error result whose
+        // text was the message, and that text is what the model has been reading.
+        return {
+          content: [{ type: "text", text: "Response not found" }],
+          details: { responseId: params.responseId, error: "Response not found" },
+          isError: true,
+        };
+      }
       
       if (params.findText) {
         const matches = findPassages(item.content, [params.findText]);
-        return { content: [{ type: "text", text: JSON.stringify(matches) }], details: { matches } };
+        return {
+          content: [{ type: "text", text: JSON.stringify(matches) }],
+          details: { matches },
+          structuredContent: {
+            responseId: params.responseId,
+            matches: matches.map((m) => ({ passage: m.passage, offset: m.offset, match: m.match })),
+          },
+        };
       }
       
-      if (params.limit === 0) return { content: [{ type: "text", text: "" }], details: { content: "" } };
+      if (params.limit === 0) {
+        return {
+          content: [{ type: "text", text: "" }],
+          details: { content: "" },
+          structuredContent: { responseId: params.responseId, content: "" },
+        };
+      }
       
       const content = item.content.slice(params.offset ?? 0, params.limit ? (params.offset ?? 0) + params.limit : undefined);
-      return { content: [{ type: "text", text: content }], details: { content } };
+      return {
+        content: [{ type: "text", text: content }],
+        details: { content },
+        structuredContent: { responseId: params.responseId, content },
+      };
     },
   });
 }