pi-ketch 0.1.1 → 0.1.3

package/README.md

@@ -73,9 +73,9 @@ You only need one working search backend to get started:
 - **Brave**: direct API search with a Brave API key.
 - **SearXNG**: self-hosted metasearch through a configured SearXNG URL.
 
-You can use either one as the default backend. Routine `ketch_search` calls use that single configured default, which is the recommended behavior for normal searches. Brave is the simplest direct default; SearXNG adds self-hosted metasearch.
+You can use either one as the default backend. Every routine `ketch_search` call must omit `backend`, `multi`, and `allBackends`, using only that single configured default. It should not automatically combine Brave and DuckDuckGo or any other providers. Brave is the simplest direct default; SearXNG adds self-hosted metasearch.
 
-For contested, multi-part, or deep research, `pi-ketch` can set `allBackends: true`. Ketch then uses `--multi=all` to discover and query every search backend it currently considers usable; users and agents do not need to hardcode provider names. An explicit `multi` list remains available for targeted provider comparisons.
+Federated search is reserved for deeper work. For contested, multi-part, or deep research, `pi-ketch` can set `allBackends: true`. Ketch then uses `--multi=all` to discover and query every search backend it currently considers usable; users and agents do not need to hardcode provider names. An explicit `multi` list remains available only for deeper corroboration or user-requested provider comparisons.
 
 Additional search backends—DuckDuckGo, Exa, Firecrawl, and Keenable—are optional. Firecrawl is used here only as an explicit or federated web-search backend; it does not power `ketch_scrape` or `ketch_crawl`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ketch",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Agent-native web research tools for Pi: multi-backend search, public code search, library docs, scraping, crawling, and browser rendering, powered by Ketch.",
   "type": "module",
   "license": "MIT",

package/skills/ketch/SKILL.md

@@ -33,9 +33,9 @@ Do not route routine web search or URL extraction through another extension's ov
 ## Default workflow
 
 1. Choose one surface using the table above.
-2. For routine web search, call `ketch_search` without `backend`, `multi`, or `allBackends`; Ketch will use the user's configured default backend.
-3. For contested, time-sensitive, multi-part, or deep research, use `allBackends: true`; Ketch dynamically queries every backend it currently considers usable, so do not hardcode provider names.
-4. Use an explicit `backend` or `multi` list only when the user requests particular providers or a targeted backend retry is needed.
+2. For every routine web search, call `ketch_search` without `backend`, `multi`, or `allBackends`; Ketch must use the user's single configured default backend. Never automatically send `multi: ["brave", "ddg"]` or any other provider list.
+3. Reserve federated search for deeper work: use `allBackends: true` for contested, time-sensitive, multi-part, or deep research. Ketch dynamically queries every backend it currently considers usable, so do not hardcode provider names.
+4. Use an explicit `multi` list only for deeper corroboration or when the user requests particular providers. Use an explicit single `backend` only for a user request or targeted retry.
 5. Make bounded calls, cite the URL supporting every externally sourced claim, and state material retrieval failures instead of treating missing sources as evidence.
 
 For deep research, read `references/research.md`. For detailed parameters and gotchas, read `references/surfaces.md`. For missing keys, browser setup, or backend failures, read `references/setup.md`.

package/skills/ketch/references/surfaces.md

@@ -2,7 +2,7 @@
 
 ## `ketch_search`
 
-Use for the open web. A routine search should omit `backend`, `multi`, and `allBackends` so Ketch uses the user's configured default. For contested, multi-part, or deep research, set `allBackends: true`; Ketch translates this to `--multi=all` and dynamically queries every backend it currently considers usable. `backend` selects one provider and `multi` selects an explicit provider list; all three modes are mutually exclusive. Set `scrape: true` only when fetched content from every result is needed. Pair it with a low `limit` and explicit `maxChars`.
+Use for the open web. Every routine search must omit `backend`, `multi`, and `allBackends` so Ketch uses the user's single configured default; never automatically submit `multi: ["brave", "ddg"]` or another provider list. Reserve federation for deeper work: set `allBackends: true` for contested, multi-part, or deep research, or use `multi` only for deeper corroboration or a user-requested provider comparison. Ketch translates `allBackends` to `--multi=all` and dynamically queries every backend it currently considers usable. `backend` selects one provider and `multi` selects an explicit provider list; all three modes are mutually exclusive. Set `scrape: true` only when fetched content from every result is needed. Pair it with a low `limit` and explicit `maxChars`.
 
 ## `ketch_code`
 

package/src/index.ts

@@ -6,6 +6,8 @@ import { registerDocsTool } from "./tools/docs.js";
 import { registerScrapeTool } from "./tools/scrape.js";
 import { registerSearchTool } from "./tools/search.js";
 
+const STATUS_ID = "pi-ketch";
+
 export default function ketchExtension(pi: ExtensionAPI): void {
   registerSearchTool(pi);
   registerScrapeTool(pi);
@@ -13,4 +15,12 @@ export default function ketchExtension(pi: ExtensionAPI): void {
   registerDocsTool(pi);
   registerCrawlTool(pi);
   registerDiagnostics(pi);
+
+  pi.on("session_start", (_event, ctx) => {
+    ctx.ui.setStatus(STATUS_ID, "🌐 ketch: active");
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    ctx.ui.setStatus(STATUS_ID, undefined);
+  });
 }

package/src/schemas.ts

@@ -8,8 +8,8 @@ const DocsBackend = StringEnum(["context7"] as const);
 export const SearchParams = Type.Object({
   query: Type.String({ description: "Web search query." }),
   backend: Type.Optional(SearchBackend),
-  multi: Type.Optional(Type.Array(SearchBackend, { description: "Explicit search backends to query together. Cannot be combined with backend or allBackends.", maxItems: 6 })),
-  allBackends: Type.Optional(Type.Boolean({ description: "Query every search backend Ketch currently considers usable. Intended for deep research, not routine searches." })),
+  multi: Type.Optional(Type.Array(SearchBackend, { description: "Query an explicit backend set only for deep research, corroboration, or a user-requested provider comparison. Never use for routine searches; omit it to use the configured default backend. Cannot be combined with backend or allBackends.", maxItems: 6 })),
+  allBackends: Type.Optional(Type.Boolean({ description: "Query every search backend Ketch currently considers usable. Use only for contested or deep research; never for routine searches." })),
   limit: Type.Optional(Type.Integer({ description: "Maximum results. Defaults to Ketch config; capped at 20.", minimum: 1, maximum: 20 })),
   scrape: Type.Optional(Type.Boolean({ description: "Fetch result pages and include extracted content." })),
   trim: Type.Optional(Type.Boolean({ description: "Strip Markdown formatting from scraped content." })),

package/src/tools/search.ts

@@ -27,12 +27,12 @@ export function registerSearchTool(pi: ExtensionAPI): void {
     defineTool({
       name: "ketch_search",
       label: "Ketch Web Search",
-      description: "Search the live web through Ketch using configured Brave, DuckDuckGo, SearXNG, Exa, Firecrawl, or Keenable backends. Can optionally scrape bounded content from each result.",
+      description: "Search the live web through Ketch. Routine searches must omit backend, multi, and allBackends so Ketch uses one configured default backend. Federated modes are reserved for deeper research. Can optionally scrape bounded content from each result.",
       parameters: SearchParams,
-      promptSnippet: "ketch_search: Search the current external web through Ketch; cite returned URLs.",
+      promptSnippet: "ketch_search: For routine web search, omit backend options and use only Ketch's configured default; cite returned URLs.",
       promptGuidelines: [
-        "Use ketch_search without backend options for routine searches so Ketch uses the user's configured default backend.",
-        "Use ketch_search with allBackends for contested, multi-part, or deep research that needs results from every currently usable backend; cite returned URLs.",
+        "For every routine search, omit backend, multi, and allBackends. Do not automatically send multi: ['brave', 'ddg'] or any other provider list; Ketch must use the user's single configured default backend.",
+        "Use multi only for deeper corroboration or an explicit request to compare particular providers. Prefer allBackends for contested, multi-part, or deep research that needs every currently usable backend.",
         "When ketch_search uses scrape, bound each fetched result with maxChars.",
       ],
       ...ketchRenderers("ketch_search"),