@kolisachint/hoocode-agent 0.5.42 → 0.5.44

package/dist/modes/interactive/websearch-warning.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The "websearch has no API key" startup notice.
+ *
+ * `websearch` works with no configuration at all, but the keyless default is
+ * scraped DuckDuckGo HTML: it is rate-limited hard and can fail outright, and
+ * the failure surfaces as a bad search rather than as a setup problem. So when
+ * the tool is active and no keyed backend is configured, the session says so
+ * once — the same shape as the Anthropic extra-usage notice, including the
+ * `/settings` switch that turns it off.
+ */
+import type { WarningSettings } from "../../core/settings-types.js";
+import { type WebtoolsSearchSettings } from "../../core/tools/webtools-shared.js";
+export declare const WEBSEARCH_API_KEY_TITLE = "Web search has no API key";
+export interface WebSearchApiKeyNoticeInput {
+    /** Tools the session actually exposes; the notice is pointless without `websearch`. */
+    activeToolNames: readonly string[];
+    /** Warning switches from settings (`warnings.websearchApiKey`). */
+    warnings: WarningSettings;
+    /** The `webtools.search` block, as the binary would read it. */
+    search?: WebtoolsSearchSettings;
+}
+export interface WebSearchApiKeyNotice {
+    title: string;
+    body: string[];
+}
+/**
+ * The notice to show, or undefined when there is nothing to say: the tool is
+ * off, a keyed backend is configured, the user pinned the keyless backend on
+ * purpose, or the warning is switched off.
+ *
+ * Pure, so the decision is testable without a TUI; the caller owns the
+ * once-per-session latch.
+ */
+export declare function websearchApiKeyNotice(input: WebSearchApiKeyNoticeInput): WebSearchApiKeyNotice | undefined;
+//# sourceMappingURL=websearch-warning.d.ts.map

package/dist/modes/interactive/websearch-warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websearch-warning.d.ts","sourceRoot":"","sources":["../../../src/modes/interactive/websearch-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAA+B,KAAK,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAE/G,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,MAAM,WAAW,0BAA0B;IAC1C,uFAAuF;IACvF,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,mEAAmE;IACnE,QAAQ,EAAE,eAAe,CAAC;IAC1B,gEAAgE;IAChE,MAAM,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,qBAAqB,GAAG,SAAS,CAiB1G","sourcesContent":["/**\n * The \"websearch has no API key\" startup notice.\n *\n * `websearch` works with no configuration at all, but the keyless default is\n * scraped DuckDuckGo HTML: it is rate-limited hard and can fail outright, and\n * the failure surfaces as a bad search rather than as a setup problem. So when\n * the tool is active and no keyed backend is configured, the session says so\n * once — the same shape as the Anthropic extra-usage notice, including the\n * `/settings` switch that turns it off.\n */\n\nimport type { WarningSettings } from \"../../core/settings-types.js\";\nimport { resolveWebSearchCredentials, type WebtoolsSearchSettings } from \"../../core/tools/webtools-shared.js\";\n\nexport const WEBSEARCH_API_KEY_TITLE = \"Web search has no API key\";\n\nexport interface WebSearchApiKeyNoticeInput {\n\t/** Tools the session actually exposes; the notice is pointless without `websearch`. */\n\tactiveToolNames: readonly string[];\n\t/** Warning switches from settings (`warnings.websearchApiKey`). */\n\twarnings: WarningSettings;\n\t/** The `webtools.search` block, as the binary would read it. */\n\tsearch?: WebtoolsSearchSettings;\n}\n\nexport interface WebSearchApiKeyNotice {\n\ttitle: string;\n\tbody: string[];\n}\n\n/**\n * The notice to show, or undefined when there is nothing to say: the tool is\n * off, a keyed backend is configured, the user pinned the keyless backend on\n * purpose, or the warning is switched off.\n *\n * Pure, so the decision is testable without a TUI; the caller owns the\n * once-per-session latch.\n */\nexport function websearchApiKeyNotice(input: WebSearchApiKeyNoticeInput): WebSearchApiKeyNotice | undefined {\n\tif (input.warnings.websearchApiKey === false) return undefined;\n\tif (!input.activeToolNames.includes(\"websearch\")) return undefined;\n\n\tconst credentials = resolveWebSearchCredentials(input.search);\n\tif (credentials.configured || credentials.explicitKeyless) return undefined;\n\n\treturn {\n\t\ttitle: WEBSEARCH_API_KEY_TITLE,\n\t\t// Two lines, like the Anthropic notice: what is wrong and the one setting\n\t\t// that fixes it. The other backends and the settings.json block are in\n\t\t// the docs — a startup notice is not the place to list them.\n\t\tbody: [\n\t\t\t\"Searching keyless DuckDuckGo, which is rate-limited. Set BRAVE_API_KEY or TAVILY_API_KEY.\",\n\t\t\t\"Turn off in /settings → Web search API key.\",\n\t\t],\n\t};\n}\n"]}

package/dist/modes/interactive/websearch-warning.js

@@ -0,0 +1,40 @@
+/**
+ * The "websearch has no API key" startup notice.
+ *
+ * `websearch` works with no configuration at all, but the keyless default is
+ * scraped DuckDuckGo HTML: it is rate-limited hard and can fail outright, and
+ * the failure surfaces as a bad search rather than as a setup problem. So when
+ * the tool is active and no keyed backend is configured, the session says so
+ * once — the same shape as the Anthropic extra-usage notice, including the
+ * `/settings` switch that turns it off.
+ */
+import { resolveWebSearchCredentials } from "../../core/tools/webtools-shared.js";
+export const WEBSEARCH_API_KEY_TITLE = "Web search has no API key";
+/**
+ * The notice to show, or undefined when there is nothing to say: the tool is
+ * off, a keyed backend is configured, the user pinned the keyless backend on
+ * purpose, or the warning is switched off.
+ *
+ * Pure, so the decision is testable without a TUI; the caller owns the
+ * once-per-session latch.
+ */
+export function websearchApiKeyNotice(input) {
+    if (input.warnings.websearchApiKey === false)
+        return undefined;
+    if (!input.activeToolNames.includes("websearch"))
+        return undefined;
+    const credentials = resolveWebSearchCredentials(input.search);
+    if (credentials.configured || credentials.explicitKeyless)
+        return undefined;
+    return {
+        title: WEBSEARCH_API_KEY_TITLE,
+        // Two lines, like the Anthropic notice: what is wrong and the one setting
+        // that fixes it. The other backends and the settings.json block are in
+        // the docs — a startup notice is not the place to list them.
+        body: [
+            "Searching keyless DuckDuckGo, which is rate-limited. Set BRAVE_API_KEY or TAVILY_API_KEY.",
+            "Turn off in /settings → Web search API key.",
+        ],
+    };
+}
+//# sourceMappingURL=websearch-warning.js.map

package/dist/modes/interactive/websearch-warning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websearch-warning.js","sourceRoot":"","sources":["../../../src/modes/interactive/websearch-warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,2BAA2B,EAA+B,MAAM,qCAAqC,CAAC;AAE/G,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;AAgBnE;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAiC,EAAqC;IAC3G,IAAI,KAAK,CAAC,QAAQ,CAAC,eAAe,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAC/D,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,SAAS,CAAC;IAEnE,MAAM,WAAW,GAAG,2BAA2B,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,WAAW,CAAC,UAAU,IAAI,WAAW,CAAC,eAAe;QAAE,OAAO,SAAS,CAAC;IAE5E,OAAO;QACN,KAAK,EAAE,uBAAuB;QAC9B,0EAA0E;QAC1E,uEAAuE;QACvE,+DAA6D;QAC7D,IAAI,EAAE;YACL,2FAA2F;YAC3F,+CAA6C;SAC7C;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * The \"websearch has no API key\" startup notice.\n *\n * `websearch` works with no configuration at all, but the keyless default is\n * scraped DuckDuckGo HTML: it is rate-limited hard and can fail outright, and\n * the failure surfaces as a bad search rather than as a setup problem. So when\n * the tool is active and no keyed backend is configured, the session says so\n * once — the same shape as the Anthropic extra-usage notice, including the\n * `/settings` switch that turns it off.\n */\n\nimport type { WarningSettings } from \"../../core/settings-types.js\";\nimport { resolveWebSearchCredentials, type WebtoolsSearchSettings } from \"../../core/tools/webtools-shared.js\";\n\nexport const WEBSEARCH_API_KEY_TITLE = \"Web search has no API key\";\n\nexport interface WebSearchApiKeyNoticeInput {\n\t/** Tools the session actually exposes; the notice is pointless without `websearch`. */\n\tactiveToolNames: readonly string[];\n\t/** Warning switches from settings (`warnings.websearchApiKey`). */\n\twarnings: WarningSettings;\n\t/** The `webtools.search` block, as the binary would read it. */\n\tsearch?: WebtoolsSearchSettings;\n}\n\nexport interface WebSearchApiKeyNotice {\n\ttitle: string;\n\tbody: string[];\n}\n\n/**\n * The notice to show, or undefined when there is nothing to say: the tool is\n * off, a keyed backend is configured, the user pinned the keyless backend on\n * purpose, or the warning is switched off.\n *\n * Pure, so the decision is testable without a TUI; the caller owns the\n * once-per-session latch.\n */\nexport function websearchApiKeyNotice(input: WebSearchApiKeyNoticeInput): WebSearchApiKeyNotice | undefined {\n\tif (input.warnings.websearchApiKey === false) return undefined;\n\tif (!input.activeToolNames.includes(\"websearch\")) return undefined;\n\n\tconst credentials = resolveWebSearchCredentials(input.search);\n\tif (credentials.configured || credentials.explicitKeyless) return undefined;\n\n\treturn {\n\t\ttitle: WEBSEARCH_API_KEY_TITLE,\n\t\t// Two lines, like the Anthropic notice: what is wrong and the one setting\n\t\t// that fixes it. The other backends and the settings.json block are in\n\t\t// the docs — a startup notice is not the place to list them.\n\t\tbody: [\n\t\t\t\"Searching keyless DuckDuckGo, which is rate-limited. Set BRAVE_API_KEY or TAVILY_API_KEY.\",\n\t\t\t\"Turn off in /settings → Web search API key.\",\n\t\t],\n\t};\n}\n"]}

package/docs/settings.md

@@ -74,15 +74,20 @@ Set `HOOCODE_SKIP_VERSION_CHECK=1` to disable the HooCode version update check.
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `warnings.anthropicExtraUsage` | boolean | `true` | Show a warning when Anthropic subscription auth may use paid extra usage |
+| `warnings.websearchApiKey` | boolean | `true` | Show a warning when `websearch` is enabled with no search API key, so it falls back to keyless DuckDuckGo |
 
 ```json
 {
   "warnings": {
-    "anthropicExtraUsage": false
+    "anthropicExtraUsage": false,
+    "websearchApiKey": false
   }
 }
 ```
 
+Both warnings are shown once per session in the TUI and can also be toggled from
+`/settings` → Warnings.
+
 ### Compaction
 
 | Setting | Type | Default | Description |
@@ -329,6 +334,7 @@ there.
 |---------|------|---------|-------------|
 | `enableWebTools` | boolean | `false` | Enable `webfetch` + `websearch` (network access). Needs the `webtools` binary. |
 | `webtools.timeoutSecs` | number | `15` | Per-request timeout in seconds, clamped 1–120. Wins over `HOOCODE_WEBTOOLS_TIMEOUT`. |
+| `webtools.search` | object | — | Search backend and credentials, read by the `webtools` binary itself. See [Web search providers](#web-search-providers). |
 | `enableEmbsearchTools` | boolean | `true` | Build and fuse the semantic index into `search`. Set false to run `search` lexical-only. `grep`/`find` are unaffected. |
 | `embsearchBinaryPath` | string | — | Explicit path to the `embsearch` binary. Default: resolve from `PATH`. |
 | `embsearchThresholdBytes` | number | `0` | Minimum indexable source bytes before a repo is embedded. `0` indexes every repo. |
@@ -346,6 +352,66 @@ Environment variables:
 On Android/Termux the published Linux builds do not run; install with
 `pkg install <name>` instead.
 
+#### Reading a long page
+
+`webfetch` budgets its output in tokens (`maxTokens`, default 4000, hard cap
+25000). When a page runs past that, the result says so — the budget it stopped
+at, and the ways past it — so a long document reads as a first page rather than
+a dead end. The TUI marks the same fetch `~4000 tokens (truncated at 4000)`.
+
+When the `webtools` binary reports paging offsets, the note names the offset to
+continue at; pass it back as `offset` to read the next window. Windows tile the
+document exactly, so a long page costs one budget per window rather than one
+copy of the page per attempt. Against an older binary the note falls back to
+advising a larger `maxTokens`.
+
+Prefer a more specific URL or `#anchor` over paging a whole document: extraction
+has already dropped nav and boilerplate, so the first few thousand tokens are
+usually the article itself.
+
+#### Web search providers
+
+`websearch` needs no configuration: it defaults to keyless DuckDuckGo Lite.
+That backend is scraped HTML, though — rate-limited hard, and it can fail
+outright — so when search reliability matters, point it at a backend with an
+actual API contract. With none configured, the TUI says so once per session
+(see [`warnings.websearchApiKey`](#warnings)).
+
+The `webtools` binary reads its own `webtools` key out of the user-level
+`~/.hoocode/settings.json`, using its own (snake_case) key names. HooCode never
+writes this block; it only reads it to tell whether a keyed backend exists. Put
+it in the user-level file — a project `.hoocode/settings.json` is not read by the
+binary, and a file holding credentials is worth keeping out of a working tree.
+
+```json
+{
+  "webtools": {
+    "search": {
+      "provider": "brave",
+      "fallback": "duckduckgo",
+      "providers": {
+        "brave": { "api_key": "..." },
+        "tavily": { "api_key": "..." },
+        "searxng": { "base_url": "https://searx.internal" }
+      }
+    }
+  }
+}
+```
+
+Environment variables win over the file, so a key can stay out of it entirely:
+
+| Variable | Effect |
+|---|---|
+| `WEBTOOLS_SEARCH_PROVIDER` | Backend to use: `duckduckgo` (default), `brave`, `tavily`, `searxng`. Pin `duckduckgo` to accept the keyless backend and silence the warning. |
+| `WEBTOOLS_SEARCH_FALLBACK` | Backend tried when the primary fails; `none` disables the fallback. |
+| `WEBTOOLS_BRAVE_API_KEY`, `BRAVE_API_KEY` | Brave Search key. |
+| `WEBTOOLS_TAVILY_API_KEY`, `TAVILY_API_KEY` | Tavily key. Returns cleaned page content, so a search often answers without a follow-up `webfetch`. |
+| `WEBTOOLS_SEARXNG_URL`, `WEBTOOLS_SEARXNG_API_KEY` | Self-hosted SearXNG endpoint (and optional key), for networks where the public APIs are unreachable. |
+
+Every result records the backend that answered it, so a fallback to the scraped
+backend is never silent.
+
 ### Resources
 
 These settings define where to load extensions, skills, prompts, and themes from.
@@ -408,7 +474,8 @@ See [packages.md](packages.md) for package management details.
   },
   "enabledModels": ["claude-*", "gpt-4o"],
   "warnings": {
-    "anthropicExtraUsage": true
+    "anthropicExtraUsage": true,
+    "websearchApiKey": true
   },
   "packages": ["hoocode-skills"]
 }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kolisachint/hoocode-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.3.42",
+	"version": "0.3.44",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.0.0"

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kolisachint/hoocode-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.3.42",
+	"version": "0.3.44",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.0.0"

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kolisachint/hoocode-extension-sandbox",
 	"private": true,
-	"version": "0.3.42",
+	"version": "0.3.44",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.0.0"

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kolisachint/hoocode-extension-with-deps",
 	"private": true,
-	"version": "0.3.42",
+	"version": "0.3.44",
 	"type": "module",
 	"engines": {
 		"bun": ">=1.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kolisachint/hoocode-agent",
-	"version": "0.5.42",
+	"version": "0.5.44",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"hoocodeConfig": {
@@ -50,9 +50,9 @@
 		"prepublishOnly": "npm run clean && npm run build"
 	},
 	"dependencies": {
-		"@kolisachint/hoocode-agent-core": "^0.5.42",
-		"@kolisachint/hoocode-ai": "^0.5.42",
-		"@kolisachint/hoocode-tui": "^0.5.42",
+		"@kolisachint/hoocode-agent-core": "^0.5.44",
+		"@kolisachint/hoocode-ai": "^0.5.44",
+		"@kolisachint/hoocode-tui": "^0.5.44",
 		"@silvia-odwyer/photon-node": "^0.3.4",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",