smart-web-mcp 0.11.6 → 0.12.0

package/CHANGELOG.md

@@ -68,6 +68,20 @@ The format is based on Keep a Changelog[^1] and this project uses SemVer.
 - `smart-web-dev` issue reporting now points at `jojo-labs/smart-web`, and the dev hot-reload runtime writes explicit ESM snapshot metadata before loading rebuilt `dist/*.js` modules
 - `initSettings` now writes `settings.json` through a temp file + rename so crashes during first-run or `--force` initialization cannot leave the runtime config truncated
 
+## [0.12.0](https://github.com/jojo-labs/smart-web/compare/v0.11.7...v0.12.0) (2026-04-27)
+
+
+### Features
+
+* add CAPTCHA type hints to handoff metadata ([#142](https://github.com/jojo-labs/smart-web/issues/142)) ([f7eeec1](https://github.com/jojo-labs/smart-web/commit/f7eeec107d8c9950662e29fafdb8cea6bb016485))
+
+## [0.11.7](https://github.com/jojo-labs/smart-web/compare/v0.11.6...v0.11.7) (2026-04-26)
+
+
+### Bug Fixes
+
+* allow external links on root index pages, reject timestamp/points noise in thread ([#138](https://github.com/jojo-labs/smart-web/issues/138)) ([3e1c00e](https://github.com/jojo-labs/smart-web/commit/3e1c00e5db2d912cf61eb9f914efeac905d581ca))
+
 ## [0.11.6](https://github.com/jojo-labs/smart-web/compare/v0.11.5...v0.11.6) (2026-04-26)
 
 

package/LICENSE

@@ -1,21 +1,68 @@
-MIT License
-
-Copyright (c) 2026 rich-jojo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+smart-web MCP Server — Proprietary License
+
+Copyright (c) 2026 jojo-labs. All rights reserved.
+
+1. Grant of License
+
+   Subject to the terms and conditions of this License, jojo-labs hereby
+   grants you a non-exclusive, non-transferable, limited license to:
+
+   a) Install and run the smart-web-mcp npm package as a local MCP server;
+   b) Use the smartfetch, smartsearch, and smartcrawl tools provided by the
+      server through an MCP host.
+
+   This license does not grant any right to modify, reverse-engineer,
+   decompile, disassemble, sublicense, redistribute, or create derivative
+   works from the software.
+
+2. Restrictions
+
+   You may not:
+
+   a) Distribute, sublicense, or make available the software or any portion
+      thereof to any third party, except as an integral part of a runtime
+      MCP host configuration that invokes the unmodified software via npx;
+   b) Use the software in a competing product or service that provides web
+      retrieval, search, or crawl capabilities as a primary feature;
+   c) Remove, alter, or obscure any proprietary notices on the software;
+   d) Use the software in any way that violates applicable law or regulation.
+
+3. Intellectual Property
+
+   The software and all associated content, including but not limited to
+   source code, binaries, documentation, and configuration templates, are
+   the proprietary property of jojo-labs and are protected by copyright and
+   other intellectual property laws. No title to or ownership of the
+   software is transferred to you under this License.
+
+4. Disclaimer of Warranties
+
+   THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT SHALL
+   JOJO-LABS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
+   IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR
+   IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.
+
+5. Limitation of Liability
+
+   IN NO EVENT SHALL JOJO-LABS BE LIABLE FOR ANY DIRECT, INDIRECT,
+   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING BUT
+   NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+   THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+6. Termination
+
+   This License and the rights granted hereunder will terminate automatically
+   upon any breach by you of the terms of this License. Upon termination, you
+   shall destroy all copies of the software in your possession.
+
+7. Governing Law
+
+   This License shall be governed by and construed in accordance with the
+   laws of the Republic of Korea, without regard to its conflict of law
+   provisions.

package/README.md

@@ -14,31 +14,29 @@ It is designed for **agents and MCP hosts**, not for manual browser automation.
 
 If a page is login-gated, keep the login UI, session persistence, and capture flow in a companion runtime instead of moving that stateful behavior into the `smart-web` core.
 
-- npm: `https://www.npmjs.com/package/smart-web-mcp`
+- npm: <https://www.npmjs.com/package/smart-web-mcp>
 - MCP Registry: `io.github.jojo-labs/smart-web`
-- GitHub: `https://github.com/jojo-labs/smart-web`
+- Issues: <https://github.com/jojo-labs/smart-web/issues>
 
 If `smart-web` returns reproducible incorrect or misleading output, open a GitHub issue with the exact input, tool arguments, observed output, expected behavior, and version. Skip obvious transient network, auth, or rate-limit failures unless the smart-web classification itself looks wrong.
 
 ## Highlights
 
 - one local MCP instead of separate search, fetch, and crawl servers
-- explicit routing: URL -> `smartfetch`, query -> `smartsearch`, known site -> `smartcrawl`
-- up-front smartfetch acquisition lanes instead of broad direct -> browser retry chains
-- optional Jina Reader relay for weak generic/article fetches when you explicitly enable it, now with JSON mode and alternate-link preservation
-- weak generic pages can now recover through JSON-LD or Next.js payload extraction and same-origin RSS/Atom feed discovery before falling back to a handoff
-- paywalled article pages now prefer lawful archive recovery and search-indexed reference previews before telling the host to escalate elsewhere
-- LinkedIn authwall handling now prefers compliant public fallbacks such as archives and search-indexed reference metadata before giving up
+- explicit routing: URL → `smartfetch`, query → `smartsearch`, known site → `smartcrawl`
+- up-front smartfetch acquisition lanes instead of broad direct → browser retry chains
+- optional Jina Reader relay for weak generic/article fetches when you explicitly enable it, with JSON mode and alternate-link preservation
+- weak generic pages can recover through JSON-LD or Next.js payload extraction and same-origin RSS/Atom feed discovery before falling back to a handoff
+- paywalled article pages prefer lawful archive recovery and search-indexed reference previews before telling the host to escalate elsewhere
+- LinkedIn authwall handling prefers compliant public fallbacks such as archives and search-indexed reference metadata before giving up
 - legal paper fallback for academic URLs: DOI-aware OpenAlex, Unpaywall, Semantic Scholar, CORE discovery, and Europe PMC enrichment plus bioRxiv/medRxiv API fallback when a direct paper page is thin or blocked
-- site-native public search fallbacks now cover Reddit, GitHub repository discovery, npm, Hacker News, Stack Exchange, and Velog when a matching `site:` query is available
+- site-native public search fallbacks cover Reddit, GitHub repository discovery, npm, Hacker News, Stack Exchange, and Velog when a matching `site:` query is available
 - structured output with `assessment` and `pipeline` fields for host-side decision making
 - local-first defaults with privacy-aware search/fetch behavior
 - useful normalization for common public surfaces instead of raw HTML dumps
 
 ## Tool routing
 
-Use the tools like this:
-
 - `smartfetch` first when the user already gave a URL or shortlink
 - `smartsearch` when the user gave a topic, keywords, or a `site:` query
 - `smartcrawl` when you already know the site and need multiple relevant pages
@@ -53,9 +51,7 @@ Use the tools like this:
 
 ## What the tools return
 
-All three tools are shaped for agent consumption.
-
-Common high-signal fields include:
+All three tools are shaped for agent consumption. Common high-signal fields include:
 
 - `assessment`: confidence, block/auth hints, recommended handoff
 - `pipeline`: resolve/acquire/normalize/assess stages
@@ -85,9 +81,7 @@ When a source stays blocked or under-specified, `smart-web` prefers partial but
 npx -y smart-web-mcp
 ```
 
-`npm` is the canonical package-manager path for this repo and package.
-
-When `smartfetch` or `smartcrawl` needs Playwright-backed page loading, `smart-web` now checks whether the bundled Chromium revision is available. If the local Playwright browser cache is missing or outdated, `smart-web` warns at startup and will try `npx playwright install chromium` automatically on first browser use before surfacing a structured error.
+When `smartfetch` or `smartcrawl` needs Playwright-backed page loading, `smart-web` checks whether the bundled Chromium revision is available. If the local Playwright browser cache is missing or outdated, `smart-web` warns at startup and will try `npx playwright install chromium` automatically on first browser use before surfacing a structured error.
 
 ## Host setup
 
@@ -97,8 +91,6 @@ When `smartfetch` or `smartcrawl` needs Playwright-backed page loading, `smart-w
 claude mcp add smart-web -- npx -y smart-web-mcp
 ```
 
-For a checked-out local repo, use [examples/claude.mcp.json](examples/claude.mcp.json).
-
 ### Codex
 
 ```bash
@@ -128,14 +120,40 @@ args = ["-y", "smart-web-mcp"]
 }
 ```
 
-## Configuration
+### Custom settings file
+
+To use a non-default settings path, append `--settings-file` to the command:
+
+```bash
+npx -y smart-web-mcp --settings-file /absolute/path/to/smart-web.settings.json
+```
+
+For Claude Code:
+
+```bash
+claude mcp add smart-web -- npx -y smart-web-mcp --settings-file /absolute/path/to/smart-web.settings.json
+```
 
-Default settings path:
+For OpenCode, add `"args"` after `"command"`:
 
-```text
-~/.config/smart-web/settings.json
+```json
+{
+  "mcp": {
+    "smart-web": {
+      "type": "local",
+      "command": ["npx", "-y", "smart-web-mcp", "--settings-file", "/absolute/path/to/smart-web.settings.json"],
+      "enabled": true
+    }
+  }
+}
 ```
 
+## Configuration
+
+### Settings path
+
+Default: `~/.config/smart-web/settings.json`
+
 Print a template:
 
 ```bash
@@ -148,90 +166,269 @@ Initialize the default file:
 npx -y smart-web-mcp --init-settings
 ```
 
-Use a non-default settings file:
+`smart-web` treats the settings file as the single runtime config surface.
 
-```bash
-npx -y smart-web-mcp --settings-file /absolute/path/to/smart-web.settings.json
+### Full settings reference
+
+```jsonc
+{
+  // "balanced" (default) or "private"
+  // "private" disables relay-style providers and public search helpers
+  "profile": "balanced",
+
+  "runtime": {
+    // Optional override for staging/export temp files
+    // Default: platform cache root (e.g. ~/.cache/smart-web/tmp)
+    "tempDir": ""
+  },
+
+  "search": {
+    // API keys — leave empty to skip that provider
+    "exaApiKey": "",
+    "braveSearchApiKey": "",
+    // Self-hosted SearXNG instance URL
+    "searxngBaseUrl": "",
+    "enableSearxng": true
+  },
+
+  "fetch": {
+    // Browser overrides — most users leave these empty
+    "chromeChannel": "",
+    "chromePath": "",
+    // Auto-install Playwright Chromium when missing (default: true)
+    "autoInstallPlaywright": true,
+    // Jina Reader relay — opt-in third-party path for weak article pages
+    "enableJinaReader": false,
+    "jinaReaderBaseUrl": "https://r.jina.ai/",
+    // Academic fallback — legal OA enrichment for paper URLs
+    "enableAcademicFallback": true,
+    "enableOpenAlex": true,
+    "enableEuropePmc": true,
+    "enableBiorxivApi": true,
+    // Unpaywall — requires a contact email
+    "enableUnpaywall": true,
+    "unpaywallEmail": "",
+    // Semantic Scholar — optional API key for higher-rate access
+    "enableSemanticScholar": true,
+    "semanticScholarApiKey": "",
+    // CORE — optional API key for richer search-backed enrichment
+    "enableCoreDiscovery": true,
+    "coreApiKey": "",
+    // FxTwitter — transparent x.com → fxtwitter redirect
+    "enableFxTwitter": true,
+    // Undetected-chromedriver — optional Python Selenium fallback for tough anti-bot pages
+    "enableUndetectedChromedriver": true,
+    "undetectedChromedriverPython": "python3",
+    // Site-specific fetches
+    "enableRedditJson": true,
+    "enableYoutubeTranscript": true,
+    // Archive fallback — Wayback and archive.md recovery
+    "enableArchiveFallback": true,
+    "enableWayback": true,
+    "enableArchiveMd": true
+  },
+
+  "network": {
+    // Allow localhost/private/reserved fetch targets (default: false)
+    "allowPrivateHosts": false
+  }
+}
 ```
 
-`smart-web` now treats the settings file as the single runtime config surface. Use the default path or pass `--settings-file` when you need a different file.
+### Common setups
 
-Most installations only need:
+#### Default — no config file needed
 
-- `profile: "balanced"`
-- `profile: "private"`
-- `search.searxngBaseUrl`
-- `search.exaApiKey`
-- `search.braveSearchApiKey`
-- `fetch.enableJinaReader`
-- `fetch.unpaywallEmail`
+Out of the box `smart-web` works with sensible defaults. Create a settings file only when you need to change something.
 
-If you do not want `smart-web` to auto-install Playwright browsers, set `fetch.autoInstallPlaywright` to `false` and the server will return an actionable `playwright_browsers_missing` or `playwright_browsers_outdated` error instead.
+#### Minimal: profile only
 
-If you want a narrow URL-to-Markdown relay for weak generic/article pages, set `fetch.enableJinaReader` to `true`. This stays opt-in because it is a third-party relay path rather than the default deterministic fetch lane.
+```json
+{
+  "profile": "balanced"
+}
+```
 
-## Quick verification
+#### Private / local-first
 
-Sanity-check the server with a few real calls:
+```json
+{
+  "profile": "private",
+  "search": {
+    "searxngBaseUrl": "http://localhost:8080"
+  }
+}
+```
 
-- `smartfetch` on a normal article URL
-- `smartfetch` on a Medium or other member-only article URL and confirm it returns either archive-backed content or an honest `reference_only` preview
-- `smartfetch` on a Naver Map, Kakao Map, or `naver.me` place-share URL
-- `smartfetch` on an arXiv abstract URL
-- `smartfetch` on a PubMed, PMC, or bioRxiv/medRxiv paper URL
-- `smartfetch` on a known product URL
-- `smartsearch` on a `site:` query
-- `smartcrawl` on a docs site or board you actually use
+In `private` mode, relay-style provider requests are blocked, Exa and Brave default off unless you explicitly re-enable them, public no-key search fallbacks are disabled, and SearXNG bases must resolve to localhost or private addresses.
 
-## Examples
+#### Private with Exa allowed back in
 
-- [Claude Code](examples/claude.mcp.json)
-- [OpenCode](examples/opencode.json)
-- [OpenCode dev hot-reload](examples/opencode.dev.json)
-- [Settings template](examples/smart-web.settings.json)
+```json
+{
+  "profile": "private",
+  "search": {
+    "exaApiKey": "...",
+    "enableExa": true
+  }
+}
+```
 
-These examples use `/absolute/path/to/...` placeholders for local checkouts.
+#### With Exa and Brave API keys
 
-## Docs
+```json
+{
+  "profile": "balanced",
+  "search": {
+    "exaApiKey": "exa-...",
+    "braveSearchApiKey": "BSA-..."
+  }
+}
+```
 
-- [Getting started](docs/getting-started.md)
-- [Configuration](docs/configuration.md)
-- [Crawling](docs/crawling.md)
-- [Docs export](docs/docscrawl.md)
-- [Retrieval lanes](docs/retrieval-lanes.md)
-- [Providers](docs/providers.md)
-- [Architecture](docs/architecture.md)
-- [Long-term design](docs/long-term-design.md)
-- [Contributing](CONTRIBUTING.md)
-- [CHANGELOG](CHANGELOG.md)
+#### Disable Playwright auto-install
 
-## Development
+```json
+{
+  "fetch": {
+    "autoInstallPlaywright": false
+  }
+}
+```
 
-```bash
-npm install
-npm run test:file -- src/mcp.test.ts
-npm run check
+The server will return an actionable `playwright_browsers_missing` or `playwright_browsers_outdated` error instead.
+
+#### Opt in to Jina Reader for weak generic article pages
+
+```json
+{
+  "fetch": {
+    "enableJinaReader": true
+  }
+}
 ```
 
-Repo-owned hook entrypoints now live under `.git-hooks/` and are chained from the machine-level git hooks. `npm install` no longer rewrites repo-local git config.
+This stays opt-in because it is a third-party relay path. When enabled, it only applies to weak generic/article direct fetches and prefers Jina JSON mode when that improves the page. `profile: "private"` hard-disables relay-style providers.
 
-### Dev MCP without restarting the host
+#### Force archive fallback off
 
-```bash
-npm run dev:watch
-smart-web-dev
+```json
+{
+  "fetch": {
+    "enableArchiveFallback": false
+  }
+}
+```
+
+#### Legal OA DOI recovery for paywalled paper pages
+
+```json
+{
+  "fetch": {
+    "enableUnpaywall": true,
+    "unpaywallEmail": "research@example.com",
+    "enableSemanticScholar": true,
+    "enableCoreDiscovery": true
+  }
+}
+```
+
+#### Enable undetected-chromedriver from a dedicated virtualenv
+
+```json
+{
+  "fetch": {
+    "enableUndetectedChromedriver": true,
+    "undetectedChromedriverPython": "/absolute/path/to/venv/bin/python"
+  }
+}
 ```
 
-`smart-web-dev` hot-swaps rebuilt `dist/*.js` modules on each tool call. New implementations update after rebuilds, but brand-new MCP tools or schema changes still require a client reconnect because MCP registration happens at process start.
+This helper is optional. `smart-web` still works without it, but when installed and reachable it can act as a second browser engine for stubborn pages where Playwright alone is not enough.
 
-By default, staging snapshots live under the platform cache root (for example `~/.cache/smart-web/tmp` on Linux). Set `runtime.tempDir` in `settings.json` if you need an explicit override.
+#### Custom temp directory
+
+```json
+{
+  "runtime": {
+    "tempDir": "/absolute/path/to/smart-web-tmp"
+  }
+}
+```
+
+### Advanced overrides
+
+These keys live inside `settings.json` when you need to force one provider on or off:
+
+**Search**
+
+- `search.enableExa`
+- `search.enableBrave`
+- `search.enableSearxng`
+- `search.enableDuckDuckGo`
+- `search.enableBraveHtml`
+
+**Fetch**
+
+- `fetch.enableFxTwitter`
+- `fetch.enableXOembed`
+- `fetch.autoInstallPlaywright`
+- `fetch.enableJinaReader`
+- `fetch.jinaReaderBaseUrl`
+- `fetch.enableAcademicFallback`
+- `fetch.enableOpenAlex`
+- `fetch.enableEuropePmc`
+- `fetch.enableBiorxivApi`
+- `fetch.enableUnpaywall`
+- `fetch.unpaywallEmail`
+- `fetch.enableSemanticScholar`
+- `fetch.semanticScholarApiKey`
+- `fetch.enableCoreDiscovery`
+- `fetch.coreApiKey`
+- `fetch.enableUndetectedChromedriver`
+- `fetch.undetectedChromedriverPython`
+- `fetch.enableRedditJson`
+- `fetch.enableYoutubeTranscript`
+- `fetch.enableArchiveFallback`
+- `fetch.enableWayback`
+- `fetch.enableArchiveMd`
+
+**Compatibility**
+
+- `network.localOnly`: advanced override that forces local-only behavior regardless of profile
+
+## Quick verification
+
+Sanity-check the server with a few real calls:
+
+- `smartfetch` on a normal article URL
+- `smartfetch` on a Medium or other member-only article URL — confirm it returns either archive-backed content or an honest `reference_only` preview
+- `smartfetch` on a Naver Map, Kakao Map, or `naver.me` place-share URL
+- `smartfetch` on an arXiv abstract URL
+- `smartfetch` on a PubMed, PMC, or bioRxiv/medRxiv paper URL
+- `smartfetch` on a known product URL
+- `smartsearch` on a `site:` query
+- `smartcrawl` on a docs site or board you actually use
+
+## Reporting issues
+
+If `smart-web` returns reproducible incorrect or misleading output, open a GitHub issue with:
+
+- exact input and tool arguments
+- observed output
+- expected behavior
+- `smart-web-mcp` version
+
+Skip obvious transient network, auth, or rate-limit failures unless the classification itself looks wrong.
 
 ## License
 
-MIT
+All rights reserved. See [LICENSE](LICENSE) for terms.
+
+This software is licensed under a proprietary license that permits installation and use as a local MCP server but prohibits modification, redistribution, reverse engineering, or use in competing products.
 
 ## References
 
 [^1]: Model Context Protocol, "Tools" specification — MCP tools are a retrieval and integration surface, not a requirement to emulate full browser-automation flows inside one tool.
 
-[^2]: Model Context Protocol Blog, "Tool Annotations as Risk Vocabulary: What Hints Can and Can't Do" (2026-03-16) — structured tool output and accurate hints improve host-side routing and escalation decisions.
+[^2]: Model Context Protocol Blog, "Tool Annotations as Risk Vocabulary: What Hints Can and Can't Do" (2026-03-16) — structured tool output and accurate hints improve host-side routing and escalation decisions.

package/dist/assessment.d.ts

@@ -1,10 +1,11 @@
-import type { RetrievalAssessment, RetrievalConfidence, RetrievalHandoffSuggestion, ToolError } from "./shared.js";
+import type { CaptchaType, RetrievalAssessment, RetrievalConfidence, RetrievalHandoffSuggestion, ToolError } from "./shared.js";
 export declare function createHandoffSuggestion(input: {
     tool: RetrievalHandoffSuggestion["tool"];
     reason: string;
     mode?: RetrievalHandoffSuggestion["mode"];
     url: string;
     goal: string;
+    captcha_type?: CaptchaType;
 }): RetrievalHandoffSuggestion;
 export declare function createAssessment(input?: {
     confidence?: RetrievalConfidence;
@@ -17,3 +18,10 @@ export declare function createAssessment(input?: {
 export declare function firstMeaningfulBlockedReason(items: Array<ToolError | string | null | undefined>): string;
 export declare function detectAuthLikeText(value: string): boolean;
 export declare function detectInteractiveLikeText(value: string): boolean;
+/**
+ * Detect CAPTCHA widget type from page text/HTML content.
+ * smart-web is read-only so it cannot inspect the live DOM — instead it
+ * infers the likely CAPTCHA type from known signatures in the fetched HTML
+ * (iframe src patterns, class names, data-sitekey attributes).
+ */
+export declare function detectCaptchaTypeFromContent(html: string): CaptchaType | null;

package/dist/assessment.js

@@ -8,6 +8,7 @@ export function createHandoffSuggestion(input) {
         mode: input.mode || "read",
         url: String(input.url || "").trim(),
         goal: String(input.goal || "").trim(),
+        ...(input.captcha_type ? { captcha_type: input.captcha_type } : {}),
     };
 }
 export function createAssessment(input = {}) {
@@ -49,4 +50,41 @@ export function detectInteractiveLikeText(value) {
         return false;
     return /(enable javascript|checking your browser|just a moment|please wait|open the app|continue in browser|use the search box|select a filter|load more|show more)/i.test(text);
 }
+/**
+ * Detect CAPTCHA widget type from page text/HTML content.
+ * smart-web is read-only so it cannot inspect the live DOM — instead it
+ * infers the likely CAPTCHA type from known signatures in the fetched HTML
+ * (iframe src patterns, class names, data-sitekey attributes).
+ */
+export function detectCaptchaTypeFromContent(html) {
+    if (!html)
+        return null;
+    // Turnstile: Cloudflare challenge platform iframe or widget class
+    if (/challenges\.cloudflare\.com\/cdn-cgi\/challenge-platform/i.test(html))
+        return "turnstile";
+    if (/class="[^"]*cf-turnstile[^"]*"/i.test(html))
+        return "turnstile";
+    if (/data-sitekey[^>]*class="[^"]*cf-turnstile/i.test(html))
+        return "turnstile";
+    // reCAPTCHA: Google iframe or widget class
+    if (/recaptcha\/(?:api2|enterprise)\/anchor/i.test(html))
+        return "recaptcha";
+    if (/class="[^"]*g-recaptcha[^"]*"/i.test(html))
+        return "recaptcha";
+    if (/class="[^"]*g_recaptcha[^"]*"/i.test(html))
+        return "recaptcha";
+    if (/data-sitekey[^>]*class="[^"]*g-recaptcha/i.test(html))
+        return "recaptcha";
+    // hCaptcha: hCaptcha iframe or widget class
+    if (/hcaptcha\.com\/captcha/i.test(html))
+        return "hcaptcha";
+    if (/class="[^"]*h-captcha[^"]*"/i.test(html))
+        return "hcaptcha";
+    if (/data-sitekey[^>]*class="[^"]*h-captcha/i.test(html))
+        return "hcaptcha";
+    // Fallback: "captcha" keyword without a specific type
+    if (/\bcaptcha\b/i.test(html))
+        return "recaptcha";
+    return null;
+}
 //# sourceMappingURL=assessment.js.map

package/dist/assessment.js.map

@@ -1 +1 @@
-{"version":3,"file":"assessment.js","sourceRoot":"","sources":["../src/assessment.ts"],"names":[],"mappings":"AAEA,SAAS,gBAAgB,CAAC,OAAiB;IACzC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;AAC9F,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAMvC;IACC,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QACzC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,MAAM;QAC1B,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QACnC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;KACtC,CAAA;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAO7B,EAAE;IACJ,OAAO;QACL,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,QAAQ;QACxC,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QACzD,oBAAoB,EAAE,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC;QACzD,uBAAuB,EAAE,OAAO,CAAC,KAAK,CAAC,uBAAuB,CAAC;QAC/D,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;QAC9C,mBAAmB,EAAE,KAAK,CAAC,mBAAmB,IAAI,IAAI;KACvD,CAAA;AACH,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAmD;IAC9F,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI;YAAE,SAAQ;QACnB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;YACxB,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,yBAAyB,CAAC,IAAI,CAAC,IAAI,6EAA6E,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAA;YACxK,SAAQ;QACV,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAA;QAC/D,IAAI,yDAAyD,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,IAAI,CAAA;IACtI,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IAC9C,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAA;IACvB,OAAO,gLAAgL,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACpM,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAa;IACrD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAA;IAC9C,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAA;IACvB,OAAO,8JAA8J,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAClL,CAAC"}
+{"version":3,"file":"assessment.js","sourceRoot":"","sources":["../src/assessment.ts"],"names":[],"mappings":"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"}

package/dist/composition.d.ts

@@ -4,6 +4,9 @@ export type WebTaskRequestPlan = {
     goal: string;
     startUrl: string;
     mode: "read" | "act";
+    /** When the smart-web handoff identified a known CAPTCHA type on the page,
+     *  this field lets web-task-api prepare the right solving strategy upfront. */
+    captchaType?: "turnstile" | "recaptcha" | "hcaptcha";
 };
 export type SmartcrawlRequestPlan = {
     url: string;
@@ -11,11 +14,13 @@ export type SmartcrawlRequestPlan = {
     mode: "auto" | "board" | "docs";
 };
 export declare function planWebTaskFromSmartfetch(output: SmartfetchOutput): {
+    captchaType?: import("./shared.js").CaptchaType;
     goal: string;
     startUrl: string;
     mode: "read" | "act";
 } | null;
 export declare function planWebTaskFromSmartcrawl(response: SmartcrawlResponse): {
+    captchaType?: import("./shared.js").CaptchaType;
     goal: string;
     startUrl: string;
     mode: "read" | "act";