@mrclrchtr/supi-web 11.0.0 → 11.1.0

package/README.md

@@ -46,6 +46,39 @@ The package adds four tools that Pi selects as needed:
 
 Pi searches Context7 first when the library ID is unknown, then fetches docs with the selected ID. Narrow questions produce more useful documentation context than broad requests. Documentation returns as Markdown by default; the agent can request structured JSON snippets when needed.
 
+### Structured results in codemode
+
+All four tools declare PI-native `outputSchema` contracts. Direct calls still return readable, bounded text; `await tools.<name>(args)` in codemode resolves to structured data, not that text or UI `details`.
+
+| Tool | Structured value |
+|---|---|
+| `web_fetch_md` | `mode: "inline"` with complete `markdown`, or `mode: "file"` with `filePath`; both include resolved `url`, `chars`, and `lines` |
+| `web_search` | Complete `sources` (`title`, `url`, `excerpts`, optional `sourceDate`), `sourceCount`, and `excerptCount` |
+| `web_docs_search` | All `results` with IDs, names, complete descriptions/versions, scores, and snippet counts; `count` is the number returned by Context7 |
+| `web_docs_fetch` | `libraryId`, `chars`, `lines`, and either `format: "markdown"` with complete `markdown`, or `format: "snippets"` with SDK-normalized `snippets` (`title`, `content`, `source`) for `raw: true` |
+
+Inline/data results include `modelOutput.truncated` and, when text is truncated, `modelOutput.fullOutputPath`. These describe the **direct-call text**, not missing structured data. Library search also reports `modelOutput.omittedResults`: matches excluded by the table's top-10 row limit before line/byte truncation. Structured descriptions and version lists are not shortened. File-mode page fetches retain the existing disk delivery instead of duplicating the body in structured data.
+
+Results describe the evidence returned by the provider, not exhaustive coverage of the web or a library. Empty search arrays and empty snippet arrays are successful outcomes. Authentication, network, malformed web-search data, and cancellation failures still throw; codemode calls reject rather than returning a successful empty result. No tool currently returns a schema-defined failure or paginated result.
+
+```javascript
+const libraries = await tools.web_docs_search({
+  library_name: "react",
+  query: "effect cleanup",
+});
+if (libraries.results.length > 0) {
+  const docs = await tools.web_docs_fetch({
+    library_id: libraries.results[0].id,
+    query: "effect cleanup",
+    raw: true,
+  });
+  return docs.snippets.map(({ title, source }) => ({ title, source }));
+}
+return [];
+```
+
+Structured values can be larger than their text previews. Select the fields you need before printing them. The package's `./api` export provides `WebFetchMdOutput`, `WebSearchOutput`, `WebDocsSearchOutput`, and `WebDocsFetchOutput` types. Active Pi sessions need `/reload` or a restart to load extension changes.
+
 ## Web Search
 
 `web_search` uses the installed `bx` executable. The tool is enabled by default, but it is available only when `bx` is on `PATH`. Search freshness accepts `pd`, `pw`, `pm`, `py`, or an ordered `YYYY-MM-DDtoYYYY-MM-DD` range.
@@ -91,14 +124,18 @@ pi -e npm:@mrclrchtr/supi-web
 
 ## Context7 API key
 
-The documentation tools call the [Context7 API](https://context7.com/). Create a free key at <https://context7.com/dashboard>, export it before starting Pi, and keep it out of repository files:
+The documentation tools use the official [Context7 TypeScript SDK](https://github.com/upstash/context7/tree/master/packages/sdk). Create a free key at <https://context7.com/dashboard>, export it before starting Pi, and keep it out of repository files:
 
 ```bash
 export CONTEXT7_API_KEY="ctx7sk-..."
 pi
 ```
 
-`web_fetch_md` does not use Context7 and needs no API key.
+`web_fetch_md` does not use Context7 and needs no API key. Credentials are resolved when a documentation tool is called, not while the extension loads.
+
+`raw: true` requests JSON and normalizes both provider code snippets and information snippets into `{ title, content, source }` objects. It does not expose the untouched REST envelope or provider ranking metadata. Default mode retains Context7's formatted text.
+
+Requests make one attempt, forward cancellation, and add no SDK timeout. The explicit `no_libraries_found` HTTP 404 response is a successful empty library search; other API errors remain failures. Use a library ID returned by search: stale IDs can produce redirect errors instead of documentation.
 
 ## Boundaries
 

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "11.0.0",
+  "version": "11.1.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -14,6 +14,8 @@ export interface DebugRegistryConfig {
   enabled: boolean;
   /** What the agent-callable debug tool may return. */
   agentAccess: DebugAgentAccess;
+  /** Whether Agent Run retrospective capture is explicitly enabled. */
+  agentRunRetrospectivesEnabled: boolean;
   /** Maximum number of session-local events to keep in memory. */
   maxEvents: number;
 }
@@ -21,6 +23,7 @@ export interface DebugRegistryConfig {
 export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
   enabled: false,
   agentAccess: "sanitized",
+  agentRunRetrospectivesEnabled: false,
   maxEvents: 100,
 };
 
@@ -75,6 +78,9 @@ export interface DebugEventQueryResult {
 /** Receives a sanitized event whenever the registry records one. */
 export type DebugEventListener = (event: DebugEventView) => void;
 
+/** Receives sanitized events for persistence; separate from ordinary event subscriptions. */
+export type DebugPersistenceSink = (event: DebugEventView) => void;
+
 export interface DebugSummary {
   total: number;
   byLevel: Partial<Record<DebugLevel, number>>;
@@ -85,6 +91,7 @@ interface DebugRegistryState {
   config: DebugRegistryConfig;
   events: DebugEvent[];
   listeners: Set<DebugEventListener>;
+  persistenceSinks: Set<DebugPersistenceSink>;
   nextId: number;
 }
 
@@ -111,13 +118,15 @@ function getState(): DebugRegistryState {
       config: cloneConfig(DEBUG_REGISTRY_DEFAULTS),
       events: [],
       listeners: new Set(),
+      persistenceSinks: new Set(),
       nextId: 1,
     };
     (globalThis as Record<symbol, unknown>)[REGISTRY_KEY] = state;
   }
   // Keep the shared registry compatible with extension reloads that reuse an
-  // instance created before listeners existed.
+  // instance created before listener sets existed.
   if (!state.listeners) state.listeners = new Set();
+  if (!state.persistenceSinks) state.persistenceSinks = new Set();
   return state;
 }
 
@@ -200,6 +209,19 @@ export function isDebugRegistryEnabled(): boolean {
   return getState().config.enabled;
 }
 
+/**
+ * Return whether a retrospective can be captured: Debug and its explicit opt-in
+ * must be enabled, and at least one persistence sink must be registered.
+ */
+export function canRecordAgentRunRetrospective(): boolean {
+  const state = getState();
+  return (
+    state.config.enabled &&
+    state.config.agentRunRetrospectivesEnabled &&
+    state.persistenceSinks.size > 0
+  );
+}
+
 /** Best-effort redaction helper for data exposed through sanitized debug views. */
 export function redactDebugData<T>(value: T): T {
   return redactValue(value, 8) as T;
@@ -226,6 +248,16 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
   return () => state.listeners.delete(listener);
 }
 
+/**
+ * Register a sanitized event persistence sink. Sinks are tracked separately from
+ * ordinary listeners so eligibility checks only succeed when logging is active.
+ */
+export function subscribeDebugPersistence(sink: DebugPersistenceSink): () => void {
+  const state = getState();
+  state.persistenceSinks.add(sink);
+  return () => state.persistenceSinks.delete(sink);
+}
+
 /** Record a session-local debug event if debugging is enabled. */
 export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   const state = getState();
@@ -251,6 +283,13 @@ export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
       // Debug-event consumers must not alter producer behavior.
     }
   }
+  for (const sink of state.persistenceSinks) {
+    try {
+      sink(toSanitizedView(event));
+    } catch {
+      // Persistence failures must not alter producer behavior.
+    }
+  }
   return {
     ...event,
     data: event.data === undefined ? undefined : redactDebugData(event.data),
@@ -309,5 +348,6 @@ export function resetDebugRegistry(): void {
   state.config = cloneConfig(DEBUG_REGISTRY_DEFAULTS);
   state.events = [];
   state.listeners.clear();
+  state.persistenceSinks.clear();
   state.nextId = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-web",
-  "version": "11.0.0",
+  "version": "11.1.0",
   "description": "Public web pages, web search sources, and focused Context7 docs",
   "license": "MIT",
   "repository": {
@@ -33,11 +33,12 @@
     "README.md"
   ],
   "dependencies": {
+    "@upstash/context7-sdk": "0.6.0",
     "jsdom": "^30.0.0",
     "@mozilla/readability": "^0.6.0",
     "turndown": "^7.2.0",
     "turndown-plugin-gfm": "^1.0.2",
-    "@mrclrchtr/supi-core": "11.0.0"
+    "@mrclrchtr/supi-core": "11.1.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/api.ts

@@ -21,3 +21,7 @@ export {
   type WebSearchInput,
   type WebToolName,
 } from "./tool/tool-specs.ts";
+export type { WebDocsFetchOutput } from "./tool/web_docs_fetch/result-schema.ts";
+export type { WebDocsSearchOutput } from "./tool/web_docs_search/result-schema.ts";
+export type { WebFetchMdOutput } from "./tool/web_fetch_md/result-schema.ts";
+export type { WebSearchOutput } from "./tool/web_search/result-schema.ts";

package/src/context7-client.ts

@@ -1,135 +1,50 @@
-/**
- * Context7 API client — calls the Context7 REST API directly via fetch(),
- * matching the official Context7 pi extension pattern.
- *
- * API key is read from CONTEXT7_API_KEY env var. Without a key, requests are
- * sent without an Authorization header; the API will return 401.
- */
+/** Context7 SDK adapter: request policy and SuPi's successful empty-search outcome. */
 
-const BASE_URL = "https://context7.com/api";
+import { Context7, Context7Error, type Documentation, type Library } from "@upstash/context7-sdk";
 
-export class Context7Error extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "Context7Error";
-  }
-}
-
-export interface SearchResult {
-  id: string;
-  name: string;
-  description: string;
-  totalSnippets: number;
-  trustScore: number;
-  benchmarkScore: number;
-  versions?: string[];
-}
+export type { Documentation as DocSnippet, Library as SearchResult } from "@upstash/context7-sdk";
+export { Context7Error } from "@upstash/context7-sdk";
 
-export interface DocSnippet {
-  title: string;
-  content: string;
-  source: string;
-}
-
-/** Request options shared by Context7 REST calls. */
+/** Request options shared by Context7 calls. */
 export interface Context7RequestOptions {
   signal?: AbortSignal;
 }
 
-function authHeaders(): Record<string, string> {
-  const apiKey = process.env.CONTEXT7_API_KEY;
-  return apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
-}
-
-async function parseErrorResponse(response: Response): Promise<string> {
-  try {
-    const json = (await response.json()) as { message?: string };
-    if (json.message) return json.message;
-  } catch {
-    // JSON parsing failed, fall through to status-based message
-  }
-
-  const hasKey = Boolean(process.env.CONTEXT7_API_KEY);
-  if (response.status === 429) {
-    return hasKey
-      ? "Rate limited or quota exceeded. Upgrade your plan at https://context7.com/plans for higher limits."
-      : "Rate limited or quota exceeded. Create a free API key at https://context7.com/dashboard for higher limits.";
-  }
-  if (response.status === 404) {
-    return "The library you are trying to access does not exist. Please try with a different library ID.";
-  }
-  if (response.status === 401) {
-    return "Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix.";
-  }
-  return `Request failed with status ${response.status}. Please try again later.`;
-}
-
-interface ApiSearchResult {
-  id: string;
-  title: string;
-  description: string;
-  totalSnippets: number;
-  trustScore: number;
-  benchmarkScore: number;
-  versions?: string[];
-}
-
-interface ApiSearchResponse {
-  error?: string;
-  results: ApiSearchResult[];
-}
-
-function mapSearchResult(r: ApiSearchResult): SearchResult {
-  return {
-    id: r.id,
-    name: r.title,
-    description: r.description,
-    totalSnippets: r.totalSnippets,
-    trustScore: r.trustScore,
-    benchmarkScore: r.benchmarkScore,
-    versions: r.versions,
-  };
+function createClient(): Context7 {
+  // Resolve credentials per call, never during extension loading. Preserve single-attempt,
+  // signal-driven requests rather than inheriting the SDK's retries and timeout.
+  return new Context7({ retry: false, timeout: false });
 }
 
+/** Search libraries; only the provider's explicit no-match response is a successful empty result. */
 export async function searchLibrary(
   query: string,
   libraryName: string,
   options: Context7RequestOptions = {},
-): Promise<SearchResult[]> {
-  const url = new URL(`${BASE_URL}/v2/libs/search`);
-  url.searchParams.set("query", query);
-  url.searchParams.set("libraryName", libraryName);
-
-  const response = await fetch(url, { headers: authHeaders(), signal: options.signal });
-
-  if (!response.ok) {
-    throw new Context7Error(await parseErrorResponse(response));
+): Promise<Library[]> {
+  try {
+    return await createClient().searchLibrary(query, libraryName, options);
+  } catch (error) {
+    if (
+      error instanceof Context7Error &&
+      error.status === 404 &&
+      error.code === "no_libraries_found"
+    ) {
+      return [];
+    }
+    throw error;
   }
-
-  const data = (await response.json()) as ApiSearchResponse;
-  return (data.results ?? []).map(mapSearchResult);
 }
 
+/** Fetch text or SDK-normalized JSON snippets, preserving code and information snippets. */
 export async function getContext(
   query: string,
   libraryId: string,
   raw?: boolean,
   options: Context7RequestOptions = {},
-): Promise<string | DocSnippet[]> {
-  const url = new URL(`${BASE_URL}/v2/context`);
-  url.searchParams.set("query", query);
-  url.searchParams.set("libraryId", libraryId);
-
-  const response = await fetch(url, { headers: authHeaders(), signal: options.signal });
-
-  if (!response.ok) {
-    throw new Context7Error(await parseErrorResponse(response));
-  }
-
-  if (raw) {
-    const json = (await response.json()) as DocSnippet[];
-    return json;
-  }
-
-  return response.text();
+): Promise<string | Documentation[]> {
+  return createClient().getContext(query, libraryId, {
+    ...options,
+    type: raw ? "json" : "txt",
+  });
 }

package/src/tool/result-schema.ts

@@ -0,0 +1,7 @@
+import { Type } from "typebox";
+
+/** Limits apply to the model-facing text, not the structured payload. */
+export const modelOutputSchema = Type.Object({
+  truncated: Type.Boolean(),
+  fullOutputPath: Type.Optional(Type.String()),
+});

package/src/tool/result.ts

@@ -5,7 +5,9 @@ import {
   type TruncationResult,
   truncateHead,
 } from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
 import { writeTempFile } from "../temp-file.ts";
+import type { modelOutputSchema } from "./result-schema.ts";
 
 /** Result of preparing content for a tool response visible to the model. */
 export interface ModelVisibleOutput {
@@ -17,6 +19,14 @@ export interface ModelVisibleOutput {
   fullOutputPath?: string;
 }
 
+/** Project only public truncation metadata, without copying preview text or internal state. */
+export function modelOutputMetadata(output: ModelVisibleOutput): Static<typeof modelOutputSchema> {
+  return {
+    truncated: output.truncation?.truncated === true,
+    ...(output.fullOutputPath ? { fullOutputPath: output.fullOutputPath } : {}),
+  };
+}
+
 /** Prepare content for model-visible output, preserving full output in a temp file if truncated. */
 export async function limitModelVisibleOutput(
   content: string,

package/src/tool/tool-specs.ts

@@ -10,6 +10,7 @@ import {
   WEB_DOCS_FETCH_TOOL_LABEL,
   WEB_DOCS_FETCH_TOOL_NAME,
   webDocsFetchParameters,
+  webDocsFetchSpec,
 } from "./web_docs_fetch/spec.ts";
 import {
   toolDescription as searchDescription,
@@ -20,6 +21,7 @@ import {
   WEB_DOCS_SEARCH_TOOL_LABEL,
   WEB_DOCS_SEARCH_TOOL_NAME,
   webDocsSearchParameters,
+  webDocsSearchSpec,
 } from "./web_docs_search/spec.ts";
 import {
   toolDescription as fetchDescription,
@@ -31,6 +33,7 @@ import {
   WEB_FETCH_MD_TOOL_LABEL,
   WEB_FETCH_MD_TOOL_NAME,
   webFetchMdParameters,
+  webFetchMdSpec,
 } from "./web_fetch_md/spec.ts";
 import {
   toolDescription as webSearchDescription,
@@ -41,6 +44,7 @@ import {
   WEB_SEARCH_TOOL_LABEL,
   WEB_SEARCH_TOOL_NAME,
   webSearchParameters,
+  webSearchSpec,
 } from "./web_search/spec.ts";
 
 export type { WebDocsFetchInput } from "./web_docs_fetch/spec.ts";
@@ -74,6 +78,7 @@ export interface WebToolSpec {
   promptSnippet: string;
   promptGuidelines: readonly string[];
   parameters: TSchema;
+  outputSchema: TSchema;
 }
 
 export const WEB_TOOL_SPECS = [
@@ -84,6 +89,7 @@ export const WEB_TOOL_SPECS = [
     promptSnippet: fetchSnippet,
     promptGuidelines: fetchGuidelines,
     parameters: webFetchMdParameters,
+    outputSchema: webFetchMdSpec.outputSchema,
   },
   {
     name: WEB_DOCS_SEARCH_TOOL_NAME,
@@ -92,6 +98,7 @@ export const WEB_TOOL_SPECS = [
     promptSnippet: searchSnippet,
     promptGuidelines: searchGuidelines,
     parameters: webDocsSearchParameters,
+    outputSchema: webDocsSearchSpec.outputSchema,
   },
   {
     name: WEB_DOCS_FETCH_TOOL_NAME,
@@ -100,6 +107,7 @@ export const WEB_TOOL_SPECS = [
     promptSnippet: docsFetchSnippet,
     promptGuidelines: docsFetchGuidelines,
     parameters: webDocsFetchParameters,
+    outputSchema: webDocsFetchSpec.outputSchema,
   },
   {
     name: WEB_SEARCH_TOOL_NAME,
@@ -108,6 +116,7 @@ export const WEB_TOOL_SPECS = [
     promptSnippet: webSearchSnippet,
     promptGuidelines: webSearchGuidelines,
     parameters: webSearchParameters,
+    outputSchema: webSearchSpec.outputSchema,
   },
 ] as const satisfies readonly WebToolSpec[];
 

package/src/tool/web_docs_fetch/execute.ts

@@ -1,11 +1,7 @@
-import type {
-  AgentToolResult,
-  AgentToolUpdateCallback,
-  ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import type { AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getContext } from "../../context7-client.ts";
 import { limitModelVisibleOutput } from "../result.ts";
-import { buildFetchResult, type FetchDetails } from "./result.ts";
+import { buildFetchResult, type FetchResult } from "./result.ts";
 import type { WebDocsFetchInput } from "./spec.ts";
 
 // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
@@ -15,7 +11,7 @@ export async function runFetch(
   signal: AbortSignal | undefined,
   onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
   _ctx: ExtensionContext,
-): Promise<AgentToolResult<FetchDetails>> {
+): Promise<FetchResult> {
   const input = (params ?? {}) as WebDocsFetchInput;
   const libraryId = input.library_id?.trim();
   const query = input.query?.trim();
@@ -37,5 +33,5 @@ export async function runFetch(
     suffix: raw ? ".json" : ".md",
   });
 
-  return buildFetchResult(libraryId, raw, textContent, output);
+  return buildFetchResult(libraryId, { raw, content, textContent }, output);
 }

package/src/tool/web_docs_fetch/result-schema.ts

@@ -0,0 +1,32 @@
+import { type Static, Type } from "typebox";
+import { modelOutputSchema } from "../result-schema.ts";
+
+const context = {
+  libraryId: Type.String(),
+  chars: Type.Integer({ minimum: 0 }),
+  lines: Type.Integer({ minimum: 0 }),
+  modelOutput: modelOutputSchema,
+};
+
+/** Context7's text payload or parsed snippet data, selected by the existing raw input. */
+export const webDocsFetchOutputSchema = Type.Union([
+  Type.Object({
+    ...context,
+    format: Type.Literal("markdown"),
+    markdown: Type.String(),
+  }),
+  Type.Object({
+    ...context,
+    format: Type.Literal("snippets"),
+    snippets: Type.Array(
+      Type.Object({
+        title: Type.String(),
+        content: Type.String(),
+        source: Type.String(),
+      }),
+    ),
+  }),
+]);
+
+/** Complete documentation payload, unaffected by model-text truncation. */
+export type WebDocsFetchOutput = Static<typeof webDocsFetchOutputSchema>;

package/src/tool/web_docs_fetch/result.ts

@@ -1,5 +1,12 @@
 import type { AgentToolResult, TruncationResult } from "@earendil-works/pi-coding-agent";
-import type { ModelVisibleOutput } from "../result.ts";
+import type { DocSnippet } from "../../context7-client.ts";
+import { type ModelVisibleOutput, modelOutputMetadata } from "../result.ts";
+import type { WebDocsFetchOutput } from "./result-schema.ts";
+
+/** Final documentation result preserves the API payload for programmatic callers. */
+export type FetchResult = AgentToolResult<FetchDetails> & {
+  structuredContent: WebDocsFetchOutput;
+};
 
 export interface FetchDetails extends Record<string, unknown> {
   libraryId: string;
@@ -13,17 +20,32 @@ export interface FetchDetails extends Record<string, unknown> {
 /** Assemble the model-facing result for one docs fetch. */
 export function buildFetchResult(
   libraryId: string,
-  raw: boolean,
-  textContent: string,
+  payload: { raw: boolean; content: string | DocSnippet[]; textContent: string },
   output: ModelVisibleOutput,
-): AgentToolResult<FetchDetails> {
+): FetchResult {
+  const { raw, content, textContent } = payload;
+  const chars = textContent.length;
+  const lines = textContent.split("\n").length;
+  const context = { libraryId, chars, lines, modelOutput: modelOutputMetadata(output) };
   return {
     content: [{ type: "text", text: output.text }],
+    structuredContent:
+      typeof content === "string"
+        ? { ...context, format: "markdown", markdown: content }
+        : {
+            ...context,
+            format: "snippets",
+            snippets: content.map(({ title, content: body, source }) => ({
+              title,
+              content: body,
+              source,
+            })),
+          },
     details: {
       libraryId,
       raw,
-      chars: textContent.length,
-      lines: textContent.split("\n").length,
+      chars,
+      lines,
       truncation: output.truncation,
       fullOutputPath: output.fullOutputPath,
     },

package/src/tool/web_docs_fetch/spec.ts

@@ -1,6 +1,7 @@
 import type { Static } from "typebox";
 import { Type } from "typebox";
 import { runFetch } from "./execute.ts";
+import { webDocsFetchOutputSchema } from "./result-schema.ts";
 
 export const WEB_DOCS_FETCH_TOOL_NAME = "web_docs_fetch";
 export const WEB_DOCS_FETCH_TOOL_LABEL = "Web Docs Fetch";
@@ -8,7 +9,7 @@ export const WEB_DOCS_FETCH_TOOL_LABEL = "Web Docs Fetch";
 export const webDocsFetchParameters = Type.Object(
   {
     library_id: Type.String({
-      description: "Context7 ID, for example /facebook/react.",
+      description: "Context7 ID, for example /react/react.",
     }),
     query: Type.String({ description: "Specific docs question" }),
     raw: Type.Optional(
@@ -28,5 +29,6 @@ export const webDocsFetchSpec = {
   name: WEB_DOCS_FETCH_TOOL_NAME,
   label: WEB_DOCS_FETCH_TOOL_LABEL,
   parameters: webDocsFetchParameters,
+  outputSchema: webDocsFetchOutputSchema,
   execute: runFetch,
 } as const;

package/src/tool/web_docs_search/execute.ts

@@ -1,15 +1,11 @@
-import type {
-  AgentToolResult,
-  AgentToolUpdateCallback,
-  ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import type { AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { searchLibrary } from "../../context7-client.ts";
 import { limitModelVisibleOutput } from "../result.ts";
 import {
   buildNoResultsResult,
   buildSearchResult,
   formatSearchResults,
-  type SearchDetails,
+  type SearchResult,
 } from "./result.ts";
 import type { WebDocsSearchInput } from "./spec.ts";
 
@@ -20,7 +16,7 @@ export async function runSearch(
   signal: AbortSignal | undefined,
   onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
   _ctx: ExtensionContext,
-): Promise<AgentToolResult<SearchDetails>> {
+): Promise<SearchResult> {
   const input = (params ?? {}) as WebDocsSearchInput;
   const libraryName = input.library_name?.trim();
   const query = input.query?.trim();

package/src/tool/web_docs_search/result-schema.ts

@@ -0,0 +1,28 @@
+import { type Static, Type } from "typebox";
+import { modelOutputSchema } from "../result-schema.ts";
+
+/** Complete Context7 library matches, independent of the compact table's limits. */
+export const webDocsSearchOutputSchema = Type.Object({
+  results: Type.Array(
+    Type.Object({
+      id: Type.String(),
+      name: Type.String(),
+      description: Type.String(),
+      totalSnippets: Type.Number(),
+      trustScore: Type.Number(),
+      benchmarkScore: Type.Number(),
+      versions: Type.Optional(Type.Array(Type.String())),
+    }),
+  ),
+  count: Type.Integer({ minimum: 0 }),
+  modelOutput: Type.Object({
+    ...modelOutputSchema.properties,
+    omittedResults: Type.Integer({
+      minimum: 0,
+      description: "Matches excluded by the compact table's row limit, before text truncation.",
+    }),
+  }),
+});
+
+/** All API matches, with unshortened descriptions and versions. */
+export type WebDocsSearchOutput = Static<typeof webDocsSearchOutputSchema>;

package/src/tool/web_docs_search/result.ts

@@ -1,6 +1,12 @@
 import type { AgentToolResult, TruncationResult } from "@earendil-works/pi-coding-agent";
 import type { searchLibrary } from "../../context7-client.ts";
-import type { ModelVisibleOutput } from "../result.ts";
+import { type ModelVisibleOutput, modelOutputMetadata } from "../result.ts";
+import type { WebDocsSearchOutput } from "./result-schema.ts";
+
+/** Final library search includes complete matches, not a Markdown table as data. */
+export type SearchResult = AgentToolResult<SearchDetails> & {
+  structuredContent: WebDocsSearchOutput;
+};
 
 export interface SearchDetails extends Record<string, unknown> {
   count: number;
@@ -16,7 +22,7 @@ const MAX_DESCRIPTION_CHARS = 120;
 const MAX_VERSION_COUNT = 5;
 
 /** Assemble the empty-search result. */
-export function buildNoResultsResult(libraryName: string): AgentToolResult<SearchDetails> {
+export function buildNoResultsResult(libraryName: string): SearchResult {
   return {
     content: [
       {
@@ -24,6 +30,11 @@ export function buildNoResultsResult(libraryName: string): AgentToolResult<Searc
         text: `No libraries found for "${libraryName}". Try a different search term.`,
       },
     ],
+    structuredContent: {
+      results: [],
+      count: 0,
+      modelOutput: { truncated: false, omittedResults: 0 },
+    },
     details: { count: 0, libraryName },
   };
 }
@@ -33,9 +44,25 @@ export function buildSearchResult(
   libraryName: string,
   results: Awaited<ReturnType<typeof searchLibrary>>,
   output: ModelVisibleOutput,
-): AgentToolResult<SearchDetails> {
+): SearchResult {
   return {
     content: [{ type: "text", text: output.text }],
+    structuredContent: {
+      results: results.map((result) => ({
+        id: result.id,
+        name: result.name,
+        description: result.description,
+        totalSnippets: result.totalSnippets,
+        trustScore: result.trustScore,
+        benchmarkScore: result.benchmarkScore,
+        ...(result.versions ? { versions: [...result.versions] } : {}),
+      })),
+      count: results.length,
+      modelOutput: {
+        ...modelOutputMetadata(output),
+        omittedResults: Math.max(0, results.length - MAX_SEARCH_RESULTS),
+      },
+    },
     details: {
       count: results.length,
       libraryName,

package/src/tool/web_docs_search/spec.ts

@@ -1,6 +1,7 @@
 import type { Static } from "typebox";
 import { Type } from "typebox";
 import { runSearch } from "./execute.ts";
+import { webDocsSearchOutputSchema } from "./result-schema.ts";
 
 export const WEB_DOCS_SEARCH_TOOL_NAME = "web_docs_search";
 export const WEB_DOCS_SEARCH_TOOL_LABEL = "Web Docs Search";
@@ -24,5 +25,6 @@ export const webDocsSearchSpec = {
   name: WEB_DOCS_SEARCH_TOOL_NAME,
   label: WEB_DOCS_SEARCH_TOOL_LABEL,
   parameters: webDocsSearchParameters,
+  outputSchema: webDocsSearchOutputSchema,
   execute: runSearch,
 } as const;

package/src/tool/web_fetch_md/execute.ts

@@ -1,8 +1,4 @@
-import type {
-  AgentToolResult,
-  AgentToolUpdateCallback,
-  ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import type { AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { htmlToMarkdown, wrapAsCodeBlock } from "../../convert.ts";
 import { fetchWithNegotiation, isValidHttpUrl } from "../../fetch.ts";
 import { writeTempFile } from "../../temp-file.ts";
@@ -12,7 +8,7 @@ import {
   type WebFetchMdInput,
   type WebFetchOutputMode,
 } from "./input.ts";
-import { buildFileResult, buildInlineResult, type WebFetchDetails } from "./result.ts";
+import { buildFileResult, buildInlineResult, type WebFetchResult } from "./result.ts";
 
 // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
 export async function runWebFetch(
@@ -21,7 +17,7 @@ export async function runWebFetch(
   signal: AbortSignal | undefined,
   onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
   _ctx: ExtensionContext,
-): Promise<AgentToolResult<WebFetchDetails>> {
+): Promise<WebFetchResult> {
   const input = (params ?? {}) as WebFetchMdInput;
   const url = String(input.url || "").trim();
   if (!isValidHttpUrl(url)) {
@@ -52,7 +48,7 @@ export async function runWebFetch(
     tempPrefix: "web-fetch-md",
     suffix: ".md",
   });
-  return buildInlineResult(base, output);
+  return buildInlineResult(base, markdown, output);
 }
 
 function shouldReturnFile(outputMode: WebFetchOutputMode, chars: number): boolean {

package/src/tool/web_fetch_md/result-schema.ts

@@ -0,0 +1,26 @@
+import { type Static, Type } from "typebox";
+import { modelOutputSchema } from "../result-schema.ts";
+
+const metrics = {
+  url: Type.String({ description: "Resolved source URL." }),
+  chars: Type.Integer({ minimum: 0 }),
+  lines: Type.Integer({ minimum: 0 }),
+};
+
+/** Page payload, or a file reference when auto/file delivery selects a file. */
+export const webFetchMdOutputSchema = Type.Union([
+  Type.Object({
+    ...metrics,
+    mode: Type.Literal("inline"),
+    markdown: Type.String(),
+    modelOutput: modelOutputSchema,
+  }),
+  Type.Object({
+    ...metrics,
+    mode: Type.Literal("file"),
+    filePath: Type.String(),
+  }),
+]);
+
+/** Complete Markdown in inline mode; file mode retains the existing disk delivery. */
+export type WebFetchMdOutput = Static<typeof webFetchMdOutputSchema>;

package/src/tool/web_fetch_md/result.ts

@@ -1,6 +1,12 @@
 import type { AgentToolResult, TruncationResult } from "@earendil-works/pi-coding-agent";
-import type { ModelVisibleOutput } from "../result.ts";
-import type { WebFetchOutputMode } from "./spec.ts";
+import { type ModelVisibleOutput, modelOutputMetadata } from "../result.ts";
+import type { WebFetchOutputMode } from "./input.ts";
+import type { WebFetchMdOutput } from "./result-schema.ts";
+
+/** Final fetch result requires both native representations. */
+export type WebFetchResult = AgentToolResult<WebFetchDetails> & {
+  structuredContent: WebFetchMdOutput;
+};
 
 export interface WebFetchDetails extends Record<string, unknown> {
   chars: number;
@@ -21,10 +27,7 @@ export interface WebFetchResultBase {
 }
 
 /** Assemble the file-mode result for one fetch. */
-export function buildFileResult(
-  base: WebFetchResultBase,
-  filePath: string,
-): AgentToolResult<WebFetchDetails> {
+export function buildFileResult(base: WebFetchResultBase, filePath: string): WebFetchResult {
   return {
     content: [
       {
@@ -32,6 +35,13 @@ export function buildFileResult(
         text: `Content written to ${filePath} (${base.chars.toLocaleString()} chars, ${base.lines.toLocaleString()} lines). Use the read tool to access it.`,
       },
     ],
+    structuredContent: {
+      mode: "file",
+      url: base.url,
+      chars: base.chars,
+      lines: base.lines,
+      filePath,
+    },
     details: { ...base, filePath },
   };
 }
@@ -39,10 +49,19 @@ export function buildFileResult(
 /** Assemble the inline-mode result for one fetch. */
 export function buildInlineResult(
   base: WebFetchResultBase,
+  markdown: string,
   output: ModelVisibleOutput,
-): AgentToolResult<WebFetchDetails> {
+): WebFetchResult {
   return {
     content: [{ type: "text", text: output.text }],
+    structuredContent: {
+      mode: "inline",
+      url: base.url,
+      chars: base.chars,
+      lines: base.lines,
+      markdown,
+      modelOutput: modelOutputMetadata(output),
+    },
     details: {
       ...base,
       truncation: output.truncation,

package/src/tool/web_fetch_md/spec.ts

@@ -1,5 +1,6 @@
 import { runWebFetch } from "./execute.ts";
 import { webFetchMdParameters } from "./input.ts";
+import { webFetchMdOutputSchema } from "./result-schema.ts";
 
 export {
   WEB_FETCH_INLINE_MAX_CHARS,
@@ -17,5 +18,6 @@ export const webFetchMdSpec = {
   name: WEB_FETCH_MD_TOOL_NAME,
   label: WEB_FETCH_MD_TOOL_LABEL,
   parameters: webFetchMdParameters,
+  outputSchema: webFetchMdOutputSchema,
   execute: runWebFetch,
 } as const;

package/src/tool/web_search/execute.ts

@@ -1,13 +1,9 @@
-import type {
-  AgentToolResult,
-  AgentToolUpdateCallback,
-  ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import type { AgentToolUpdateCallback, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { limitModelVisibleOutput } from "../result.ts";
 import { runBxContext } from "./bx.ts";
 import { validateWebSearchInput } from "./input.ts";
 import { parseBxResponse } from "./parse.ts";
-import { buildSearchResult, formatSearchResults, type WebSearchDetails } from "./result.ts";
+import { buildSearchResult, formatSearchResults, type WebSearchResult } from "./result.ts";
 
 /** Execute one direct bx context search. */
 // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
@@ -17,7 +13,7 @@ export async function runWebSearch(
   signal: AbortSignal | undefined,
   onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
   ctx: ExtensionContext,
-): Promise<AgentToolResult<WebSearchDetails>> {
+): Promise<WebSearchResult> {
   const input = validateWebSearchInput(params);
   onUpdate?.({
     content: [{ type: "text", text: "Searching the web..." }],

package/src/tool/web_search/result-schema.ts

@@ -0,0 +1,22 @@
+import { type Static, Type } from "typebox";
+import { modelOutputSchema } from "../result-schema.ts";
+
+/** All validated provider sources; no generated answer or private bx envelope. */
+export const webSearchOutputSchema = Type.Object({
+  sources: Type.Array(
+    Type.Object({
+      title: Type.String(),
+      url: Type.String(),
+      excerpts: Type.Array(Type.String()),
+      sourceDate: Type.Optional(
+        Type.String({ description: "Provider-reported publication or modification date." }),
+      ),
+    }),
+  ),
+  sourceCount: Type.Integer({ minimum: 0 }),
+  excerptCount: Type.Integer({ minimum: 0 }),
+  modelOutput: modelOutputSchema,
+});
+
+/** Source evidence remains complete even when model-facing Markdown is truncated. */
+export type WebSearchOutput = Static<typeof webSearchOutputSchema>;

package/src/tool/web_search/result.ts

@@ -1,6 +1,12 @@
 import type { AgentToolResult, TruncationResult } from "@earendil-works/pi-coding-agent";
-import type { ModelVisibleOutput } from "../result.ts";
+import { type ModelVisibleOutput, modelOutputMetadata } from "../result.ts";
 import type { WebSearchSource } from "./parse.ts";
+import type { WebSearchOutput } from "./result-schema.ts";
+
+/** Final search result requires source data as well as direct-call text. */
+export type WebSearchResult = AgentToolResult<WebSearchDetails> & {
+  structuredContent: WebSearchOutput;
+};
 
 /** Human-facing and model-facing facts for one Web Search result. */
 export interface WebSearchDetails extends Record<string, unknown> {
@@ -14,12 +20,25 @@ export interface WebSearchDetails extends Record<string, unknown> {
 export function buildSearchResult(
   sources: WebSearchSource[],
   output: ModelVisibleOutput,
-): AgentToolResult<WebSearchDetails> {
+): WebSearchResult {
+  const sourceCount = sources.length;
+  const excerptCount = sources.reduce((count, source) => count + source.excerpts.length, 0);
   return {
     content: [{ type: "text", text: output.text }],
+    structuredContent: {
+      sources: sources.map(({ title, url, excerpts, sourceDate }) => ({
+        title,
+        url,
+        excerpts: [...excerpts],
+        ...(sourceDate ? { sourceDate } : {}),
+      })),
+      sourceCount,
+      excerptCount,
+      modelOutput: modelOutputMetadata(output),
+    },
     details: {
-      sourceCount: sources.length,
-      excerptCount: sources.reduce((count, source) => count + source.excerpts.length, 0),
+      sourceCount,
+      excerptCount,
       truncation: output.truncation,
       fullOutputPath: output.fullOutputPath,
     },

package/src/tool/web_search/spec.ts

@@ -1,5 +1,6 @@
 import { runWebSearch } from "./execute.ts";
 import { webSearchParameters } from "./input.ts";
+import { webSearchOutputSchema } from "./result-schema.ts";
 
 export {
   type WebSearchInput,
@@ -14,5 +15,6 @@ export const webSearchSpec = {
   name: WEB_SEARCH_TOOL_NAME,
   label: WEB_SEARCH_TOOL_LABEL,
   parameters: webSearchParameters,
+  outputSchema: webSearchOutputSchema,
   execute: runWebSearch,
 } as const;