@humain/terminal 0.0.3-beta.0 → 0.0.3-beta.2

package/dist/humain/web-access/vendor/index.js

@@ -10,6 +10,7 @@ import { Box, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { StringEnum, complete } from "@earendil-works/pi-ai/compat";
 import { normalizeFetchContentParams } from "./fetch-params.js";
+import { resolveAuthFetchProfile } from "./auth-fetch.js";
 import { findContent } from "./content-find.js";
 import { answerFromPage } from "./page-query.js";
 import { clearCloneCache } from "./github-extract.js";
@@ -38,6 +39,7 @@ import { isSearch1APIAvailable } from "./search1api.js";
 import { isSearchinfinityAvailable } from "./searchinfinity.js";
 import { isQueritAvailable } from "./querit.js";
 import { isTavilyAvailable } from "./tavily.js";
+import { isFirecrawlAvailable } from "./firecrawl.js";
 import { isJinaSearchAvailable } from "./jina-search.js";
 import { isSerpdiveAvailable } from "./serpdive.js";
 import { isKagiAvailable } from "./kagi.js";
@@ -276,6 +278,7 @@ async function getProviderAvailability(ctx) {
         searchinfinity: isSearchinfinityAvailable(),
         querit: isQueritAvailable(),
         tavily: isTavilyAvailable(),
+        firecrawl: isFirecrawlAvailable(),
         jina: isJinaSearchAvailable(),
         serpdive: isSerpdiveAvailable(),
         kagi: isKagiAvailable(),
@@ -339,6 +342,8 @@ function firstAvailableProvider(available, preferOpenAI, fallback) {
         return "querit";
     if (available.tavily)
         return "tavily";
+    if (available.firecrawl)
+        return "firecrawl";
     if (available.jina)
         return "jina";
     if (available.serpdive)
@@ -397,6 +402,9 @@ function resolveProvider(provider, available, options) {
     if (provider === "tavily" && !available.tavily) {
         return firstAvailableProvider(available, preferOpenAI, "tavily");
     }
+    if (provider === "firecrawl" && !available.firecrawl) {
+        return firstAvailableProvider(available, preferOpenAI, "firecrawl");
+    }
     if (provider === "jina" && !available.jina) {
         return firstAvailableProvider(available, preferOpenAI, "jina");
     }
@@ -435,8 +443,8 @@ const activeCurators = new Map();
 const glimpseWins = new Map();
 const DEFAULT_MAX_INLINE_CONTENT_CHARS = 30_000;
 const MAX_INLINE_CONTENT_CHARS = 200_000;
-function getMaxInlineContentChars() {
-    const value = loadConfig().maxInlineContentChars;
+function getMaxInlineContentChars(config = loadConfig()) {
+    const value = config.maxInlineContentChars;
     if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
         return DEFAULT_MAX_INLINE_CONTENT_CHARS;
     }
@@ -445,6 +453,12 @@ function getMaxInlineContentChars() {
 function stripThumbnails(results) {
     return results.map(({ thumbnail, frames, ...rest }) => rest);
 }
+function storeFetchResult(pi, responseId, data, authProfile) {
+    if (authProfile?.cache === "off")
+        return false;
+    pi.appendEntry("web-search-results", storeFetchedContentResult(responseId, data));
+    return true;
+}
 function initialContentSlice(content, maxChars) {
     let endOffset = Math.min(content.length, maxChars);
     if (endOffset < content.length) {
@@ -468,6 +482,19 @@ function normalizeFindQueries(value) {
         throw new Error("findText must contain at least one non-empty string");
     return queries;
 }
+function formatInputValue(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number")
+        return Number.isNaN(value) ? "NaN" : String(value);
+    try {
+        const serialized = JSON.stringify(value);
+        return serialized === undefined ? String(value) : serialized;
+    }
+    catch {
+        return String(value);
+    }
+}
 function formatSearchSummary(results, answer) {
     if (results.length === 0) {
         return answer ? `${answer}\n\n---\n\n**Sources:**\nNo sources returned.` : "No results found.";
@@ -1420,12 +1447,12 @@ export default function (pi) {
         pi.registerTool({
             name: toolNames.webSearch,
             label: "Web Search",
-            description: `Search the web using OpenAI, Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Jina, SERPdive, Kagi, Bocha, Ollama, SearXNG, DuckDuckGo, Exa, Perplexity, Gemini, AnySearch, xAI, Bright Data, or SerpBase. Pass a provider array to search only those providers simultaneously, or use provider "all" to search every eligible provider except DuckDuckGo, AnySearch, xAI, Bright Data, and SerpBase. Returns an AI-synthesized answer with source citations. OpenAI search uses a Codex subscription or OpenAI API key; xAI search uses a SuperGrok/X Premium subscription or xAI API key. DuckDuckGo, AnySearch, xAI, Bright Data, and SerpBase are available only when explicitly selected. For comprehensive research, prefer queries (plural) with 2-4 varied angles over a single query — each query gets its own synthesized answer, so varying phrasing and scope gives much broader coverage. When includeContent is true, full page content is fetched in the background. Searches auto-open the interactive browser curator and stream results live; set workflow to "none" to skip curation or "auto-summary" for a model-generated summary without the browser curator. The configured provider is used when provider is omitted or set to auto; omit provider unless explicitly overriding it. Without a configured provider, auto-selects OpenAI when suitable and available, then Exa, Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Jina, SERPdive, Kagi, Bocha, Ollama, Perplexity, Gemini API, or Gemini Web. When SearXNG is configured, it is preferred first for local/private search.`,
+            description: `Search the web using OpenAI, Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Bocha, Ollama, SearXNG, DuckDuckGo, Exa, Perplexity, Gemini, AnySearch, xAI, Bright Data, or SerpBase. Pass a provider array to search only those providers simultaneously, or use provider "all" to search every eligible provider except DuckDuckGo, AnySearch, xAI, Bright Data, and SerpBase. Returns an AI-synthesized answer with source citations. OpenAI search uses a Codex subscription or OpenAI API key; xAI search uses a SuperGrok/X Premium subscription or xAI API key. DuckDuckGo, AnySearch, xAI, Bright Data, and SerpBase are available only when explicitly selected. For comprehensive research, prefer queries (plural) with 2-4 varied angles over a single query — each query gets its own synthesized answer, so varying phrasing and scope gives much broader coverage. When includeContent is true, full page content is fetched in the background. Searches auto-open the interactive browser curator and stream results live; set workflow to "none" to skip curation or "auto-summary" for a model-generated summary without the browser curator. The configured provider is used when provider is omitted or set to auto; omit provider unless explicitly overriding it. Without a configured provider, auto-selects OpenAI when suitable and available, then Exa, Brave, Parallel, TinyFish, Search1API, Searchinfinity, Querit, Tavily, Firecrawl, Jina, SERPdive, Kagi, Bocha, Ollama, Perplexity, Gemini API, or Gemini Web. When SearXNG is configured, it is preferred first for local/private search.`,
             promptSnippet: "Use for web research questions. Prefer {queries:[...]} with 2-4 varied angles over a single query for broader coverage. Omit provider unless explicitly overriding the configured default.",
             parameters: Type.Object({
                 query: Type.Optional(Type.String({ description: "Single search query. For research tasks, prefer 'queries' with multiple varied angles instead." })),
                 queries: Type.Optional(Type.Array(Type.String(), { description: "Multiple queries searched in sequence, each returning its own synthesized answer. Prefer this for research — vary phrasing, scope, and angle across 2-4 queries to maximize coverage. Good: ['React vs Vue performance benchmarks 2026', 'React vs Vue developer experience comparison', 'React ecosystem size vs Vue ecosystem']. Bad: ['React vs Vue', 'React vs Vue comparison', 'React vs Vue review'] (too similar, redundant results)." })),
-                numResults: Type.Optional(Type.Number({ description: "Results per query (default: 5, max: 20)" })),
+                numResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "Results per query (default: 5, max: 20)" })),
                 includeContent: Type.Optional(Type.Boolean({ description: "Fetch full page content (async)" })),
                 recencyFilter: Type.Optional(StringEnum(["day", "week", "month", "year"], { description: "Filter by recency" })),
                 domainFilter: Type.Optional(Type.Array(Type.String(), { description: "Limit to domains (prefix with - to exclude)" })),
@@ -1928,7 +1955,7 @@ export default function (pi) {
             parameters: Type.Object({
                 claim: Type.String({ description: "The assertion to check against web sources." }),
                 queries: Type.Optional(Type.Array(Type.String(), { description: "Search queries (default: the claim)." })),
-                numResults: Type.Optional(Type.Number({ description: "Results per query (default: 5, max: 20)." })),
+                numResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "Results per query (default: 5, max: 20)." })),
                 fetchContent: Type.Optional(Type.Boolean({ description: "Fetch up to 5 result pages for exact passage extraction." })),
                 recencyFilter: Type.Optional(StringEnum(["day", "week", "month", "year"], { description: "Filter by recency." })),
                 domainFilter: Type.Optional(Type.Array(Type.String(), { description: "Limit to domains; prefix with - to exclude." })),
@@ -2051,6 +2078,9 @@ export default function (pi) {
                 model: Type.Optional(Type.String({
                     description: "Override the Gemini model for video/YouTube analysis (e.g. 'gemini-3.6-flash'). Defaults to config or gemini-3.6-flash.",
                 })),
+                auth: Type.Optional(Type.Union([Type.String(), Type.Boolean()], {
+                    description: "Opt into an authFetch profile for local browser-cookie fetching. Use a profile name, or true only when exactly one profile exists.",
+                })),
             }),
             async execute(_toolCallId, params, signal, onUpdate, ctx) {
                 let normalized;
@@ -2075,6 +2105,19 @@ export default function (pi) {
                 if (mode === "answer" && options.model) {
                     return { content: [{ type: "text", text: "Error: use answerModel, not model, with mode answer." }], details: { error: "model is incompatible with mode answer" } };
                 }
+                if (mode === "answer" && options.auth !== undefined) {
+                    return { content: [{ type: "text", text: "Error: auth cannot be combined with mode answer." }], details: { error: "auth cannot be combined with mode answer" } };
+                }
+                let authFetchProfile;
+                if (options.auth !== undefined) {
+                    try {
+                        authFetchProfile = resolveAuthFetchProfile(options.auth);
+                    }
+                    catch (err) {
+                        const error = err instanceof Error ? err.message : String(err);
+                        return { content: [{ type: "text", text: `Error: ${error}` }], details: { error } };
+                    }
+                }
                 if (urlList.length === 0) {
                     return {
                         content: [{ type: "text", text: "Error: No URL provided." }],
@@ -2085,13 +2128,13 @@ export default function (pi) {
                     content: [{ type: "text", text: `Fetching ${urlList.length} URL(s)...` }],
                     details: { phase: "fetch", progress: 0 },
                 });
-                const { answerModel: _answerModel, ...extractionOptions } = options;
+                const { answerModel: _answerModel, auth: _auth, ...extractionOptions } = options;
                 const fetchOptions = mode === "answer"
                     ? (() => {
                         const { prompt: _prompt, ...rest } = extractionOptions;
-                        return rest;
+                        return { ...rest, ...(authFetchProfile ? { authFetchProfile } : {}) };
                     })()
-                    : extractionOptions;
+                    : { ...extractionOptions, ...(authFetchProfile ? { authFetchProfile } : {}) };
                 const fetchResults = await fetchAllContent(urlList, signal, fetchOptions);
                 const presentedResults = mode === "answer"
                     ? await Promise.all(fetchResults.map(async result => {
@@ -2116,7 +2159,6 @@ export default function (pi) {
                     : fetchResults;
                 const successful = presentedResults.filter((r) => !r.error).length;
                 const totalChars = presentedResults.reduce((sum, r) => sum + r.content.length, 0);
-                // ALWAYS store results (even for single URL)
                 const responseId = generateId();
                 const data = {
                     id: responseId,
@@ -2124,14 +2166,14 @@ export default function (pi) {
                     timestamp: Date.now(),
                     urls: stripThumbnails(fetchResults),
                 };
-                pi.appendEntry("web-search-results", storeFetchedContentResult(responseId, data));
+                const storedContent = storeFetchResult(pi, responseId, data, authFetchProfile);
                 // Single URL: return content directly (possibly truncated) with responseId
                 if (urlList.length === 1) {
                     const result = presentedResults[0];
                     if (result.error) {
                         return {
                             content: [{ type: "text", text: `Error: ${result.error}` }],
-                            details: { urls: urlList, urlCount: 1, successful: 0, error: result.error, responseId, prompt: params.prompt, timestamp: params.timestamp, frames: params.frames },
+                            details: { urls: urlList, urlCount: 1, successful: 0, error: result.error, ...(storedContent ? { responseId } : {}), prompt: params.prompt, timestamp: params.timestamp, frames: params.frames },
                         };
                     }
                     const fullLength = result.content.length;
@@ -2140,9 +2182,11 @@ export default function (pi) {
                     let output = slice.text;
                     if (truncated) {
                         output += `\n\n---\nShowing ${slice.endOffset} of ${fullLength} chars, ${slice.shownBytes} of ${slice.totalBytes} bytes, and ${slice.shownLines} of ${slice.totalLines} lines. `;
-                        output += getSearchContentEnabled
-                            ? `Use ${toolNames.getSearchContent}({ responseId: "${responseId}", urlIndex: 0, offset: ${slice.endOffset} }) for the next slice.`
-                            : "Content retrieval is not registered.";
+                        output += storedContent
+                            ? getSearchContentEnabled
+                                ? `Use ${toolNames.getSearchContent}({ responseId: "${responseId}", urlIndex: 0, offset: ${slice.endOffset} }) for the next slice.`
+                                : "Content retrieval is not registered."
+                            : "Authenticated fetch cache is off; repeat the fetch to read more.";
                     }
                     const content = [];
                     if (result.frames?.length) {
@@ -2164,7 +2208,7 @@ export default function (pi) {
                             successful: 1,
                             totalChars: fullLength,
                             title: result.title,
-                            responseId,
+                            ...(storedContent ? { responseId } : {}),
                             truncated,
                             hasImage: imageCount > 0,
                             imageCount,
@@ -2192,17 +2236,19 @@ export default function (pi) {
                         output += `- ${title || url} (${content.length} chars)\n`;
                     }
                 }
-                output += getSearchContentEnabled
-                    ? `\n---\nUse ${toolNames.getSearchContent}({ responseId: "${responseId}", urlIndex: 0 }) to retrieve bounded content slices.`
-                    : "\n---\nContent retrieval is not registered.";
+                output += storedContent
+                    ? getSearchContentEnabled
+                        ? `\n---\nUse ${toolNames.getSearchContent}({ responseId: "${responseId}", urlIndex: 0 }) to retrieve bounded content slices.`
+                        : "\n---\nContent retrieval is not registered."
+                    : "\n---\nAuthenticated fetch cache is off; repeat the fetch to read content.";
                 return {
                     content: [{ type: "text", text: output }],
-                    details: { urls: urlList, urlCount: urlList.length, successful, totalChars, responseId },
+                    details: { urls: urlList, urlCount: urlList.length, successful, totalChars, ...(storedContent ? { responseId } : {}) },
                 };
             },
             renderCall(args, theme) {
                 const { urlList, options } = normalizeFetchContentParams(args);
-                const { prompt, timestamp, frames, model, mode, answerModel } = options;
+                const { prompt, timestamp, frames, model, mode, answerModel, auth } = options;
                 if (urlList.length === 0) {
                     return new Text(theme.fg("toolTitle", theme.bold("fetch ")) + theme.fg("error", "(no URL)"), 0, 0);
                 }
@@ -2240,6 +2286,9 @@ export default function (pi) {
                 if (answerModel) {
                     lines.push(theme.fg("dim", "  answer model: ") + theme.fg("warning", answerModel));
                 }
+                if (auth !== undefined) {
+                    lines.push(theme.fg("dim", "  auth: ") + theme.fg("warning", auth === true ? "true" : auth));
+                }
                 return new Text(lines.join("\n"), 0, 0);
             },
             renderResult(result, { expanded, isPartial }, theme) {
@@ -2313,7 +2362,8 @@ export default function (pi) {
                 return new Text(statusLine + "\n" + theme.fg("dim", preview), 0, 0);
             },
         });
-    if (getSearchContentEnabled)
+    if (getSearchContentEnabled) {
+        const maxInlineContentChars = getMaxInlineContentChars(initConfig);
         pi.registerTool({
             name: toolNames.getSearchContent,
             label: "Get Search Content",
@@ -2322,11 +2372,11 @@ export default function (pi) {
             parameters: Type.Object({
                 responseId: Type.String({ description: `The responseId from ${storedContentSources}` }),
                 query: Type.Optional(Type.String({ description: searchQueryDescription })),
-                queryIndex: Type.Optional(Type.Number({ description: "Get content for query at index" })),
+                queryIndex: Type.Optional(Type.Integer({ minimum: 0, description: "Get content for query at index" })),
                 url: Type.Optional(Type.String({ description: "Get content for this URL" })),
-                urlIndex: Type.Optional(Type.Number({ description: "Get content for URL at index" })),
-                offset: Type.Optional(Type.Number({ description: "Character offset for fetched URL content slices (default 0). Cannot be combined with findText." })),
-                limit: Type.Optional(Type.Number({ description: "Maximum characters to return for fetched URL content slices (default and max are set by maxInlineContentChars). Cannot be combined with findText." })),
+                urlIndex: Type.Optional(Type.Integer({ minimum: 0, description: "Get content for URL at index" })),
+                offset: Type.Optional(Type.Integer({ minimum: 0, description: "Character offset for fetched URL content slices (default 0). Cannot be combined with findText." })),
+                limit: Type.Optional(Type.Integer({ minimum: 1, maximum: maxInlineContentChars, description: "Maximum characters to return for fetched URL content slices (default and max are set by maxInlineContentChars). Cannot be combined with findText." })),
                 findText: Type.Optional(Type.Union([
                     Type.String({ minLength: 1, maxLength: 500 }),
                     Type.Array(Type.String({ minLength: 1, maxLength: 500 }), { minItems: 1, maxItems: 10 }),
@@ -2335,15 +2385,23 @@ export default function (pi) {
             }),
             async execute(_toolCallId, params) {
                 if (params.findText !== undefined && (params.offset !== undefined || params.limit !== undefined)) {
-                    return { content: [{ type: "text", text: "findText cannot be combined with offset or limit" }], details: { error: "Incompatible find options" } };
+                    const offset = formatInputValue(params.offset);
+                    const limit = formatInputValue(params.limit);
+                    return {
+                        content: [{ type: "text", text: `findText cannot be combined with offset or limit. Received offset=${offset}, limit=${limit}; omit offset and limit when using findText.` }],
+                        details: { error: "Incompatible find options" },
+                    };
                 }
                 if (params.findMode !== undefined && params.findText === undefined) {
-                    return { content: [{ type: "text", text: "findMode requires findText" }], details: { error: "findMode requires findText" } };
+                    return {
+                        content: [{ type: "text", text: `findMode ${formatInputValue(params.findMode)} requires findText; provide findText or omit findMode.` }],
+                        details: { error: "findMode requires findText" },
+                    };
                 }
                 const data = getResult(params.responseId);
                 if (!data) {
                     return {
-                        content: [{ type: "text", text: `Error: No stored results for "${params.responseId}"` }],
+                        content: [{ type: "text", text: `Error: No stored results for responseId ${formatInputValue(params.responseId)}. Use a responseId returned by ${storedContentSources}.` }],
                         details: { error: "Not found", responseId: params.responseId },
                     };
                 }
@@ -2351,22 +2409,30 @@ export default function (pi) {
                     const artifact = getResearchArtifact(params.responseId);
                     if (!artifact) {
                         return {
-                            content: [{ type: "text", text: `Error: artifact ${params.responseId} not found` }],
+                            content: [{ type: "text", text: `Error: stored research artifact for responseId ${formatInputValue(params.responseId)} was not found. Use a responseId returned by ${storedContentSources}.` }],
                             details: { error: "Artifact not found", responseId: params.responseId },
                         };
                     }
                     const serialized = JSON.stringify(artifact, null, 2);
-                    const maxInlineContentChars = getMaxInlineContentChars();
                     const offset = params.offset ?? 0;
                     const limit = params.limit ?? maxInlineContentChars;
                     if (!Number.isInteger(offset) || offset < 0) {
-                        return { content: [{ type: "text", text: "offset must be a non-negative integer" }], details: { error: "Invalid offset", offset } };
+                        return {
+                            content: [{ type: "text", text: `Invalid offset: received ${formatInputValue(offset)} for responseId ${formatInputValue(params.responseId)}; offset must be a non-negative integer. Use 0 or a larger integer.` }],
+                            details: { error: "Invalid offset", offset },
+                        };
                     }
                     if (!Number.isInteger(limit) || limit <= 0 || limit > maxInlineContentChars) {
-                        return { content: [{ type: "text", text: `limit must be an integer from 1 to ${maxInlineContentChars}` }], details: { error: "Invalid limit", limit, maxLimit: maxInlineContentChars } };
+                        return {
+                            content: [{ type: "text", text: `Invalid limit: received ${formatInputValue(limit)} for responseId ${formatInputValue(params.responseId)}; limit must be an integer from 1 to ${maxInlineContentChars}. Use a value in that range.` }],
+                            details: { error: "Invalid limit", limit, maxLimit: maxInlineContentChars },
+                        };
                     }
                     if (offset > serialized.length) {
-                        return { content: [{ type: "text", text: `offset ${offset} is out of range (0-${serialized.length})` }], details: { error: "Offset out of range", offset, contentLength: serialized.length } };
+                        return {
+                            content: [{ type: "text", text: `Offset ${offset} is out of range for responseId ${formatInputValue(params.responseId)}. Received offset ${offset}; valid range is 0-${serialized.length}. Use an offset within that range.` }],
+                            details: { error: "Offset out of range", offset, contentLength: serialized.length },
+                        };
                     }
                     const endOffset = Math.min(offset + limit, serialized.length);
                     const artifactSlice = serialized.slice(offset, endOffset);
@@ -2383,7 +2449,7 @@ export default function (pi) {
                         if (!queryData) {
                             const available = data.queries.map((q) => `"${q.query}"`).join(", ");
                             return {
-                                content: [{ type: "text", text: `Query "${params.query}" not found. Available: ${available}` }],
+                                content: [{ type: "text", text: `Query ${formatInputValue(params.query)} was not found for responseId ${formatInputValue(params.responseId)}. Received query=${formatInputValue(params.query)}. Available queries: ${available || "none"}. Use one of the available queries or queryIndex.` }],
                                 details: { error: "Query not found" },
                             };
                         }
@@ -2391,8 +2457,9 @@ export default function (pi) {
                     else if (params.queryIndex !== undefined) {
                         queryData = data.queries[params.queryIndex];
                         if (!queryData) {
+                            const available = data.queries.map((q, i) => `${i}: "${q.query}"`).join(", ");
                             return {
-                                content: [{ type: "text", text: `Index ${params.queryIndex} out of range (0-${data.queries.length - 1})` }],
+                                content: [{ type: "text", text: `Query index ${formatInputValue(params.queryIndex)} is out of range for responseId ${formatInputValue(params.responseId)}. Received queryIndex=${formatInputValue(params.queryIndex)}; valid indexes are 0-${data.queries.length - 1}. Available queries: ${available || "none"}. Use one of the available indexes.` }],
                                 details: { error: "Index out of range" },
                             };
                         }
@@ -2400,13 +2467,13 @@ export default function (pi) {
                     else {
                         const available = data.queries.map((q, i) => `${i}: "${q.query}"`).join(", ");
                         return {
-                            content: [{ type: "text", text: `Specify query or queryIndex. Available: ${available}` }],
+                            content: [{ type: "text", text: `Specify query or queryIndex for responseId ${formatInputValue(params.responseId)}. Available queries: ${available || "none"}.` }],
                             details: { error: "No query specified" },
                         };
                     }
                     if (queryData.error) {
                         return {
-                            content: [{ type: "text", text: `Error for "${queryData.query}": ${queryData.error}` }],
+                            content: [{ type: "text", text: `Error retrieving query ${formatInputValue(queryData.query)} from responseId ${formatInputValue(params.responseId)}: ${queryData.error}. Check the stored search result and retry with another query or queryIndex if needed.` }],
                             details: { error: queryData.error, query: queryData.query },
                         };
                     }
@@ -2422,7 +2489,10 @@ export default function (pi) {
                         }
                         catch (err) {
                             const error = err instanceof Error ? err.message : String(err);
-                            return { content: [{ type: "text", text: error }], details: { error, query: queryData.query } };
+                            return {
+                                content: [{ type: "text", text: `Unable to find ${formatInputValue(params.findText)} in query ${formatInputValue(queryData.query)} for responseId ${formatInputValue(params.responseId)}: ${error}. Check findText and use a supported findMode.` }],
+                                details: { error, query: queryData.query },
+                            };
                         }
                     }
                     return {
@@ -2439,7 +2509,7 @@ export default function (pi) {
                         if (!urlData) {
                             const available = data.urls.map((u) => u.url).join("\n  ");
                             return {
-                                content: [{ type: "text", text: `URL not found. Available:\n  ${available}` }],
+                                content: [{ type: "text", text: `URL ${formatInputValue(params.url)} was not found for responseId ${formatInputValue(params.responseId)}. Received url=${formatInputValue(params.url)}. Available URLs:\n  ${available || "  none"}\nUse one of the available URLs or urlIndex.` }],
                                 details: { error: "URL not found" },
                             };
                         }
@@ -2448,8 +2518,9 @@ export default function (pi) {
                         selectedUrlIndex = params.urlIndex;
                         urlData = data.urls[selectedUrlIndex];
                         if (!urlData) {
+                            const available = data.urls.map((u, i) => `${i}: ${u.url}`).join("\n  ");
                             return {
-                                content: [{ type: "text", text: `Index ${params.urlIndex} out of range (0-${data.urls.length - 1})` }],
+                                content: [{ type: "text", text: `URL index ${formatInputValue(params.urlIndex)} is out of range for responseId ${formatInputValue(params.responseId)}. Received urlIndex=${formatInputValue(params.urlIndex)}; valid indexes are 0-${data.urls.length - 1}. Available URLs:\n  ${available || "  none"}\nUse one of the available indexes.` }],
                                 details: { error: "Index out of range" },
                             };
                         }
@@ -2457,13 +2528,13 @@ export default function (pi) {
                     else {
                         const available = data.urls.map((u, i) => `${i}: ${u.url}`).join("\n  ");
                         return {
-                            content: [{ type: "text", text: `Specify url or urlIndex. Available:\n  ${available}` }],
+                            content: [{ type: "text", text: `Specify url or urlIndex for responseId ${formatInputValue(params.responseId)}. Available URLs:\n  ${available || "  none"}` }],
                             details: { error: "No URL specified" },
                         };
                     }
                     if (urlData.error) {
                         return {
-                            content: [{ type: "text", text: `Error for ${urlData.url}: ${urlData.error}` }],
+                            content: [{ type: "text", text: `Error retrieving URL ${formatInputValue(urlData.url)} from responseId ${formatInputValue(params.responseId)}: ${urlData.error}. Check the stored fetch result and retry with another URL or urlIndex if needed.` }],
                             details: { error: urlData.error, url: urlData.url },
                         };
                     }
@@ -2478,27 +2549,29 @@ export default function (pi) {
                         }
                         catch (err) {
                             const error = err instanceof Error ? err.message : String(err);
-                            return { content: [{ type: "text", text: error }], details: { error, url: urlData.url } };
+                            return {
+                                content: [{ type: "text", text: `Unable to find ${formatInputValue(params.findText)} in URL ${formatInputValue(urlData.url)} for responseId ${formatInputValue(params.responseId)}: ${error}. Check findText and use a supported findMode.` }],
+                                details: { error, url: urlData.url },
+                            };
                         }
                     }
-                    const maxInlineContentChars = getMaxInlineContentChars();
                     const offset = params.offset ?? 0;
                     const limit = params.limit ?? maxInlineContentChars;
                     if (!Number.isInteger(offset) || offset < 0) {
                         return {
-                            content: [{ type: "text", text: "offset must be a non-negative integer" }],
+                            content: [{ type: "text", text: `Invalid offset: received ${formatInputValue(offset)} for URL ${formatInputValue(urlData.url)}; offset must be a non-negative integer. Use 0 or a larger integer.` }],
                             details: { error: "Invalid offset", offset },
                         };
                     }
                     if (!Number.isInteger(limit) || limit <= 0 || limit > maxInlineContentChars) {
                         return {
-                            content: [{ type: "text", text: `limit must be an integer from 1 to ${maxInlineContentChars}` }],
+                            content: [{ type: "text", text: `Invalid limit: received ${formatInputValue(limit)} for URL ${formatInputValue(urlData.url)}; limit must be an integer from 1 to ${maxInlineContentChars}. Use a value in that range.` }],
                             details: { error: "Invalid limit", limit, maxLimit: maxInlineContentChars },
                         };
                     }
                     if (offset > urlData.content.length) {
                         return {
-                            content: [{ type: "text", text: `offset ${offset} is out of range (0-${urlData.content.length})` }],
+                            content: [{ type: "text", text: `Offset ${offset} is out of range for URL ${formatInputValue(urlData.url)} in responseId ${formatInputValue(params.responseId)}. Received offset ${offset}; valid range is 0-${urlData.content.length}. Use an offset within that range.` }],
                             details: { error: "Offset out of range", offset, contentLength: urlData.content.length },
                         };
                     }
@@ -2527,7 +2600,7 @@ export default function (pi) {
                     };
                 }
                 return {
-                    content: [{ type: "text", text: "Invalid stored data format" }],
+                    content: [{ type: "text", text: `Invalid stored data for responseId ${formatInputValue(params.responseId)}: received type ${formatInputValue(data.type)}. Use a responseId returned by ${storedContentSources}.` }],
                     details: { error: "Invalid data" },
                 };
             },
@@ -2589,6 +2662,7 @@ export default function (pi) {
                 return new Text(statusLine + "\n" + theme.fg("dim", preview), 0, 0);
             },
         });
+    }
     if (isCommandEnabled(initConfig, "websearch"))
         pi.registerCommand("websearch", {
             description: "Open web search curator",