@mrclrchtr/supi-web 11.4.0 → 12.0.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [12.0.0]
+
+- **Breaking:** Web tool parameters are camelCase, like every other SuPi tool. `web_fetch_md`: `output_mode` → `outputMode`, `fetch_mode` → `fetchMode`, `abs_links` → `absLinks`, `timeout_ms` → `timeoutMs`. `web_docs_search`: `library_name` → `libraryName`. `web_docs_fetch`: `library_id` → `libraryId`. Values such as `firecrawl_fallback` are unchanged. Update codemode scripts and saved prompts that pass the old names; they are now rejected as unknown fields.
+- Codemode now lists the Web tools under a `web` namespace heading, so scripts can find them with `describeNamespace("web")` or `searchTools(query, { namespace: "web" })`. Every Web tool now declares audited `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` annotations, which permission extensions can read from `pi.getAllTools()`. They are read-only and open-world ([#582](https://github.com/mrclrchtr/supi/issues/582)).
+
 ## [11.4.0]
 
 - Guides agents toward the library documentation tools for library and framework usage questions, while keeping web search available for issues, release notes, and news.

package/README.md

@@ -63,12 +63,12 @@ Results describe the evidence returned by the provider, not exhaustive coverage
 
 ```javascript
 const libraries = await tools.web_docs_search({
-  library_name: "react",
+  libraryName: "react",
   query: "effect cleanup",
 });
 if (libraries.results.length > 0) {
   const docs = await tools.web_docs_fetch({
-    library_id: libraries.results[0].id,
+    libraryId: libraries.results[0].id,
     query: "effect cleanup",
     raw: true,
   });
@@ -84,7 +84,7 @@ HTTP fetch failures include the requested URL and response status in the error m
 ```javascript
 for (const url of urls) {
   try {
-    const page = await tools.web_fetch_md({ url, output_mode: "file" });
+    const page = await tools.web_fetch_md({ url, outputMode: "file" });
     text({ url, filePath: page.filePath });
   } catch (error) {
     text({ url, error: String(error) });
@@ -117,7 +117,7 @@ Search results are provider-reported source material. A source date can be a pub
 
 It follows redirects and, for HTML, removes scripts and styles while preserving headings, links, lists, code blocks, and tables.
 
-Native Markdown is returned unchanged, including relative links and code examples. For HTML conversion, `abs_links` defaults to `true`; set it to `false` to preserve original link and image destinations. Unsafe URL schemes are removed in either HTML mode.
+Native Markdown is returned unchanged, including relative links and code examples. For HTML conversion, `absLinks` defaults to `true`; set it to `false` to preserve original link and image destinations. Unsafe URL schemes are removed in either HTML mode.
 
 ### Optional Firecrawl retrieval
 
@@ -125,7 +125,7 @@ Direct fetching remains the default and needs no API key. To allow Firecrawl, op
 
 Export `FIRECRAWL_API_KEY` before starting Pi. The key stays in the environment, not settings. Enabling without a key saves the preference and shows a warning; direct fetching remains available.
 
-The agent can select one `fetch_mode`:
+The agent can select one `fetchMode`:
 
 | Mode | Behavior |
 |---|---|
@@ -140,19 +140,19 @@ For a public page blocked with HTTP 403:
 ```javascript
 const page = await tools.web_fetch_md({
   url: "https://example.com/article",
-  fetch_mode: "firecrawl_fallback",
-  output_mode: "file",
+  fetchMode: "firecrawl_fallback",
+  outputMode: "file",
 });
 return page;
 ```
 
-For JS-rendered content, select `fetch_mode: "firecrawl"` instead. The key is read only when Firecrawl is actually needed and is not returned in results. Firecrawl receives the requested URL and may consume credits, including for cached results. The tool requests Markdown only, with no structured-extraction add-ons or client-side retries. Firecrawl manages its own retrieval pipeline.
+For JS-rendered content, select `fetchMode: "firecrawl"` instead. The key is read only when Firecrawl is actually needed and is not returned in results. Firecrawl receives the requested URL and may consume credits, including for cached results. The tool requests Markdown only, with no structured-extraction add-ons or client-side retries. Firecrawl manages its own retrieval pipeline.
 
 `firecrawl_fallback` runs only after the direct pipeline ends with HTTP 403—not for authentication errors (401), missing pages, rate limits, network failures, or cancellation. Neither mode retries Firecrawl failures through another provider. Both modes reject credential-bearing URLs, local/reserved hosts, and hosts resolving to non-public addresses before sharing them. Do not select Firecrawl for signed URLs or login-protected, private, or paywalled pages. These checks are not a sandbox or proof that a page is publicly accessible.
 
 Firecrawl results retain the requested source URL and include `retrieval.provider: "firecrawl"`, plus `cacheState` and `cachedAt` when supplied. Both inline/file responses disclose retrieval provenance. [Firecrawl caching](https://docs.firecrawl.dev/features/scrape#caching-and-freshness) allows cached content up to two days old by default; missing cache metadata does not establish freshness. Empty, unsuccessful, warning-bearing, and recognizable access-block responses are failures, not usable article content. A null or absent warning is accepted. Firecrawl can still return incomplete or noisy content, so inspect it before relying on it.
 
-`timeout_ms` applies to each direct HTTP request and to the complete Firecrawl attempt, including DNS validation and response reading; it is not a whole-tool deadline. The provider timeout is clamped to its supported 1–300 second range, while the local deadline still enforces shorter budgets. Cancellation is forwarded to Firecrawl. Native/Firecrawl Markdown remains unchanged, so `abs_links` applies only to local HTML conversion.
+`timeoutMs` applies to each direct HTTP request and to the complete Firecrawl attempt, including DNS validation and response reading; it is not a whole-tool deadline. The provider timeout is clamped to its supported 1–300 second range, while the local deadline still enforces shorter budgets. Cancellation is forwarded to Firecrawl. Native/Firecrawl Markdown remains unchanged, so `absLinks` applies only to local HTML conversion.
 
 ### Large pages
 

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-web",
-  "version": "11.4.0",
+  "version": "12.0.0",
   "description": "Public web pages, web search sources, and focused Context7 docs",
   "license": "MIT",
   "repository": {
@@ -39,7 +39,7 @@
     "@mozilla/readability": "^0.6.0",
     "turndown": "^7.2.0",
     "turndown-plugin-gfm": "^1.0.2",
-    "@mrclrchtr/supi-core": "11.4.0"
+    "@mrclrchtr/supi-core": "12.0.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/tool/namespace.ts

@@ -0,0 +1,12 @@
+import type { ToolNamespace } from "@earendil-works/pi-coding-agent";
+
+/** Codemode namespace shared by every `web_*` tool. */
+export const WEB_TOOL_NAMESPACE: ToolNamespace = {
+  name: "web",
+  description: "Public web search, page fetching, and library documentation lookup.",
+  instructions: [
+    "For library or framework usage, call web_docs_search for a libraryId, then web_docs_fetch.",
+    "Use web_search for current or external sources such as issues, release notes, or news.",
+    "Use web_fetch_md to read a known public URL.",
+  ].join("\n"),
+};

package/src/tool/web_docs_fetch/execute.ts

@@ -13,11 +13,11 @@ export async function runFetch(
   _ctx: ExtensionContext,
 ): Promise<FetchResult> {
   const input = (params ?? {}) as WebDocsFetchInput;
-  const libraryId = input.library_id?.trim();
+  const libraryId = input.libraryId?.trim();
   const query = input.query?.trim();
   const raw = Boolean(input.raw);
 
-  if (!libraryId) throw new Error("'library_id' parameter is required");
+  if (!libraryId) throw new Error("'libraryId' parameter is required");
   if (!query) throw new Error("'query' parameter is required");
 
   onUpdate?.({

package/src/tool/web_docs_fetch/guidance.ts

@@ -1,5 +1,5 @@
 export const toolDescription =
-  "Fetch focused Context7 docs for a known library_id. Search first if the ID is unknown. Markdown is the default; raw=true returns JSON snippets.";
+  "Fetch focused Context7 docs for a known libraryId. Search first if the ID is unknown. Markdown is the default; raw=true returns JSON snippets.";
 
 export const promptSnippet = "fetch focused Context7 documentation";
 

package/src/tool/web_docs_fetch/register.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WEB_TOOL_NAMESPACE } from "../namespace.ts";
 import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
 import { renderFetchCall, renderFetchResult } from "./render.ts";
 import { webDocsFetchSpec } from "./spec.ts";
@@ -7,6 +8,7 @@ import { webDocsFetchSpec } from "./spec.ts";
 export function registerWebDocsFetchTool(pi: ExtensionAPI): void {
   pi.registerTool({
     ...webDocsFetchSpec,
+    namespace: WEB_TOOL_NAMESPACE,
     description: toolDescription,
     promptSnippet,
     promptGuidelines: [...promptGuidelines],

package/src/tool/web_docs_fetch/render.ts

@@ -6,7 +6,7 @@ import { WEB_DOCS_FETCH_TOOL_NAME, type WebDocsFetchInput } from "./spec.ts";
 /** Transcript renderer for web_docs_fetch tool calls. */
 export function renderFetchCall(args: unknown, theme: Theme) {
   const input = (args ?? {}) as WebDocsFetchInput;
-  const libraryId = typeof input.library_id === "string" ? input.library_id : "";
+  const libraryId = typeof input.libraryId === "string" ? input.libraryId : "";
   const query = typeof input.query === "string" ? truncatePreview(input.query) : undefined;
   return renderToolCall(WEB_DOCS_FETCH_TOOL_NAME, libraryId, theme, query);
 }

package/src/tool/web_docs_fetch/spec.ts

@@ -8,7 +8,7 @@ export const WEB_DOCS_FETCH_TOOL_LABEL = "Web Docs Fetch";
 
 export const webDocsFetchParameters = Type.Object(
   {
-    library_id: Type.String({
+    libraryId: Type.String({
       description: "Context7 ID, for example /react/react.",
     }),
     query: Type.String({ description: "Specific docs question" }),
@@ -28,6 +28,12 @@ export type WebDocsFetchInput = Static<typeof webDocsFetchParameters>;
 export const webDocsFetchSpec = {
   name: WEB_DOCS_FETCH_TOOL_NAME,
   label: WEB_DOCS_FETCH_TOOL_LABEL,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
   parameters: webDocsFetchParameters,
   outputSchema: webDocsFetchOutputSchema,
   execute: runFetch,

package/src/tool/web_docs_search/execute.ts

@@ -18,10 +18,10 @@ export async function runSearch(
   _ctx: ExtensionContext,
 ): Promise<SearchResult> {
   const input = (params ?? {}) as WebDocsSearchInput;
-  const libraryName = input.library_name?.trim();
+  const libraryName = input.libraryName?.trim();
   const query = input.query?.trim();
 
-  if (!libraryName) throw new Error("'library_name' parameter is required");
+  if (!libraryName) throw new Error("'libraryName' parameter is required");
   if (!query) throw new Error("'query' parameter is required");
 
   onUpdate?.({

package/src/tool/web_docs_search/register.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WEB_TOOL_NAMESPACE } from "../namespace.ts";
 import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
 import { renderSearchCall, renderSearchResult } from "./render.ts";
 import { webDocsSearchSpec } from "./spec.ts";
@@ -7,6 +8,7 @@ import { webDocsSearchSpec } from "./spec.ts";
 export function registerWebDocsSearchTool(pi: ExtensionAPI): void {
   pi.registerTool({
     ...webDocsSearchSpec,
+    namespace: WEB_TOOL_NAMESPACE,
     description: toolDescription,
     promptSnippet,
     promptGuidelines: [...promptGuidelines],

package/src/tool/web_docs_search/render.ts

@@ -6,7 +6,7 @@ import { WEB_DOCS_SEARCH_TOOL_NAME, type WebDocsSearchInput } from "./spec.ts";
 /** Transcript renderer for web_docs_search tool calls. */
 export function renderSearchCall(args: unknown, theme: Theme) {
   const input = (args ?? {}) as WebDocsSearchInput;
-  const libraryName = typeof input.library_name === "string" ? input.library_name : "";
+  const libraryName = typeof input.libraryName === "string" ? input.libraryName : "";
   const query = typeof input.query === "string" ? truncatePreview(input.query) : undefined;
   return renderToolCall(WEB_DOCS_SEARCH_TOOL_NAME, libraryName, theme, query);
 }

package/src/tool/web_docs_search/result.ts

@@ -83,7 +83,7 @@ export function formatSearchResults(
   const noun = results.length === 1 ? "library" : "libraries";
   const hiddenNote =
     hiddenCount > 0
-      ? [`_${hiddenCount} more omitted; refine \`library_name\` or \`query\` if needed._`, ""]
+      ? [`_${hiddenCount} more omitted; refine \`libraryName\` or \`query\` if needed._`, ""]
       : [];
 
   return [

package/src/tool/web_docs_search/spec.ts

@@ -8,7 +8,7 @@ export const WEB_DOCS_SEARCH_TOOL_LABEL = "Web Docs Search";
 
 export const webDocsSearchParameters = Type.Object(
   {
-    library_name: Type.String({
+    libraryName: Type.String({
       description: "Library name (e.g. react, next.js, fastapi)",
     }),
     query: Type.String({
@@ -24,6 +24,12 @@ export type WebDocsSearchInput = Static<typeof webDocsSearchParameters>;
 export const webDocsSearchSpec = {
   name: WEB_DOCS_SEARCH_TOOL_NAME,
   label: WEB_DOCS_SEARCH_TOOL_LABEL,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
   parameters: webDocsSearchParameters,
   outputSchema: webDocsSearchOutputSchema,
   execute: runSearch,

package/src/tool/web_fetch_md/execute.ts

@@ -41,9 +41,9 @@ async function fetchAsMarkdown(
     throw new Error(`URL must be http(s): ${url}`);
   }
 
-  const outputMode = input.output_mode ?? "auto";
-  const absLinks = input.abs_links ?? true;
-  const timeoutMs = typeof input.timeout_ms === "number" ? input.timeout_ms : 30_000;
+  const outputMode = input.outputMode ?? "auto";
+  const absLinks = input.absLinks ?? true;
+  const timeoutMs = typeof input.timeoutMs === "number" ? input.timeoutMs : 30_000;
 
   onUpdate?.({
     content: [{ type: "text", text: `Fetching ${url}...` }],
@@ -53,7 +53,7 @@ async function fetchAsMarkdown(
   const result = await fetchPage(url, {
     timeoutMs,
     signal,
-    fetchMode: input.fetch_mode,
+    fetchMode: input.fetchMode,
     firecrawlEnabled: loadWebConfig(configCwd).firecrawlEnabled,
   });
   const markdown = await resolveMarkdown(result, absLinks);

package/src/tool/web_fetch_md/fetch.ts

@@ -71,7 +71,7 @@ export async function fetchPage(
   const mode = options.fetchMode ?? "direct";
   if (!WEB_FETCH_MODES.includes(mode)) {
     throw new FetchError(
-      'Unsupported fetch_mode; select "direct", "firecrawl_fallback", or "firecrawl"',
+      'Unsupported fetchMode; select "direct", "firecrawl_fallback", or "firecrawl"',
     );
   }
   if (mode !== "direct" && !options.firecrawlEnabled) {
@@ -89,7 +89,7 @@ export async function fetchPage(
         ? ""
         : "requires Firecrawl enabled in /supi-settings and FIRECRAWL_API_KEY; ";
       throw new FetchError(
-        `${error.message}. For a public page, retry with fetch_mode: "firecrawl_fallback" (${setupHint}shares the URL and may consume credits).`,
+        `${error.message}. For a public page, retry with fetchMode: "firecrawl_fallback" (${setupHint}shares the URL and may consume credits).`,
         { status: 403, cause: error },
       );
     }

package/src/tool/web_fetch_md/input.ts

@@ -26,8 +26,8 @@ const OutputModeEnum = Type.Enum(WEB_FETCH_OUTPUT_MODES, {
 export const webFetchMdParameters = Type.Object(
   {
     url: Type.String({ description: "Public http(s) URL" }),
-    output_mode: Type.Optional(OutputModeEnum),
-    fetch_mode: Type.Optional(
+    outputMode: Type.Optional(OutputModeEnum),
+    fetchMode: Type.Optional(
       Type.Enum(WEB_FETCH_MODES, {
         type: "string",
         default: "direct",
@@ -35,13 +35,13 @@ export const webFetchMdParameters = Type.Object(
           "direct fetches locally; firecrawl_fallback uses Firecrawl only after HTTP 403; firecrawl skips direct fetching for JS-heavy or poorly extracted pages. Firecrawl requires opt-in via /supi-settings and FIRECRAWL_API_KEY, shares the URL and may consume credits. Never use it for signed, login-protected, private, or paywalled URLs.",
       }),
     ),
-    abs_links: Type.Optional(
+    absLinks: Type.Optional(
       Type.Boolean({
         description: "Absolutize HTML links/images; false preserves original destinations.",
         default: true,
       }),
     ),
-    timeout_ms: Type.Optional(
+    timeoutMs: Type.Optional(
       Type.Integer({
         description: "Timeout per direct request and for the complete Firecrawl attempt (ms)",
         default: 30_000,

package/src/tool/web_fetch_md/register.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WEB_TOOL_NAMESPACE } from "../namespace.ts";
 import { createWebFetchExecute } from "./execute.ts";
 import { getWebFetchPromptSurface } from "./guidance.ts";
 import { renderWebFetchCall, renderWebFetchResult } from "./render.ts";
@@ -12,6 +13,7 @@ export function registerWebFetchMdTool(pi: ExtensionAPI, configCwd?: string): vo
   const surface = getWebFetchPromptSurface();
   pi.registerTool({
     ...webFetchMdSpec,
+    namespace: WEB_TOOL_NAMESPACE,
     ...(configCwd ? { execute: createWebFetchExecute(configCwd) } : {}),
     description: surface.description,
     promptSnippet: surface.promptSnippet,

package/src/tool/web_fetch_md/render.ts

@@ -7,8 +7,8 @@ import { WEB_FETCH_MD_TOOL_NAME, type WebFetchMdInput } from "./spec.ts";
 export function renderWebFetchCall(args: unknown, theme: Theme) {
   const input = (args ?? {}) as WebFetchMdInput;
   const url = typeof input.url === "string" ? input.url : "";
-  const outputMode = typeof input.output_mode === "string" ? input.output_mode : undefined;
-  const annotation = [outputMode, input.fetch_mode].filter(Boolean).join(", ");
+  const outputMode = typeof input.outputMode === "string" ? input.outputMode : undefined;
+  const annotation = [outputMode, input.fetchMode].filter(Boolean).join(", ");
   return renderToolCall(WEB_FETCH_MD_TOOL_NAME, url, theme, annotation || undefined);
 }
 

package/src/tool/web_fetch_md/spec.ts

@@ -17,6 +17,12 @@ export const WEB_FETCH_MD_TOOL_LABEL = "Web Fetch";
 export const webFetchMdSpec = {
   name: WEB_FETCH_MD_TOOL_NAME,
   label: WEB_FETCH_MD_TOOL_LABEL,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
   parameters: webFetchMdParameters,
   outputSchema: webFetchMdOutputSchema,
   execute: runWebFetch,

package/src/tool/web_search/register.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { WEB_TOOL_NAMESPACE } from "../namespace.ts";
 import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
 import { renderWebSearchCall, renderWebSearchResult } from "./render.ts";
 import { webSearchSpec } from "./spec.ts";
@@ -7,6 +8,7 @@ import { webSearchSpec } from "./spec.ts";
 export function registerWebSearchTool(pi: ExtensionAPI): void {
   pi.registerTool({
     ...webSearchSpec,
+    namespace: WEB_TOOL_NAMESPACE,
     description: toolDescription,
     promptSnippet,
     promptGuidelines: [...promptGuidelines],

package/src/tool/web_search/spec.ts

@@ -14,6 +14,12 @@ export const WEB_SEARCH_TOOL_LABEL = "Web Search";
 export const webSearchSpec = {
   name: WEB_SEARCH_TOOL_NAME,
   label: WEB_SEARCH_TOOL_LABEL,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+  },
   parameters: webSearchParameters,
   outputSchema: webSearchOutputSchema,
   execute: runWebSearch,