@tiny-fish/cli 0.51.1-next.409 → 0.51.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.51.1-next.409",
+  "version": "0.51.1",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
     "test:e2e:real": "vitest --run --config vitest.e2e.config.ts e2e/real-harnesses.e2e.test.ts"
   },
   "dependencies": {
-    "@tiny-fish/sdk": "^0.9.0",
+    "@tiny-fish/sdk": "^0.10.0",
     "commander": "^12.0.0",
     "cross-spawn": "^7.0.6",
     "tldts": "^6.1.86",
@@ -53,11 +53,11 @@
     "oxfmt": "^0.48.0",
     "oxlint": "^1.63.0",
     "typescript": "^5.0.0",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.12"
   },
   "overrides": {
     "esbuild": "0.28.2",
-    "vite": "7.3.6",
+    "vite": "7.3.7",
     "brace-expansion": "^5.0.9",
     "ip-address": ">=10.3.1",
     "postcss": ">=8.5.23",

package/skill/.source-commit

@@ -1 +1 @@
-6aca200440f85ca0e25c92b78e36f43f3179a18a
+7c2e319dcf5545c7b287c0a1849c079b554fa91f

package/skill/tinyfish-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tinyfish-research
-description: "Web research powered by TinyFish search and fetch. Use for any question needing current web information, and for deep research — competitive analysis, literature reviews, lead generation, deep dives — including phrases like 'research this', 'find everything about', 'find me all', or 'deep dive on'."
+description: "Web research powered by TinyFish search and fetch, plus TinyFish deep research runs when the user explicitly asks for deep research. Use for any question needing current web information, and for deep research — competitive analysis, literature reviews, lead generation, deep dives — including phrases like 'research this', 'find everything about', 'find me all', or 'deep dive on'."
 ---
 
 # TinyFish Research
@@ -9,7 +9,8 @@ You are the orchestrator. Understand the question, decide how much work it deser
 passes, then compile and deliver. If you have a subagent tool, see "Fanning out" for when to delegate
 instead.
 
-Two tools do all the work, and **both are free**, so depth costs latency and context — never money:
+Two tools do most of the work, and **both are free**, so search-and-fetch depth costs latency and
+context — never money. Deep research runs, below, are the exception: each is billed.
 
 - **`search`** — ranked web results with titles, snippets, URLs. Filters for recency, date range,
   domain include/exclude, news, and research papers.
@@ -19,6 +20,30 @@ Do not use `run_web_automation` for research. It costs $0.016 per step and is fo
 sites, not reading them. The only exception is a page that requires a login to read — that's
 `tinyfish-authenticated`.
 
+## Deep research runs
+
+**Search and fetch stay the default.** Start a TinyFish deep research run only when the user
+explicitly asks for one: "deep research", "deep dive", "comprehensive report", "cited report",
+"literature review", "survey", or "landscape". A run searches, reads, and synthesizes many sources
+into a cited report. It takes several minutes and is **billed per run**. Without such an ask, never
+use it for single facts, definitions, current news, docs lookups, "what is" or "compare X vs Y"
+questions, or reading known URLs. An explicit ask wins even when the topic is news or a comparison.
+
+1. `start_deep_research` with `query` (the question plus every scope and constraint the user gave,
+   dates computed as in "Dates first") and `mode`. `deep` is the default; use `max` only when the
+   user asks for maximum depth or an exhaustive report — it is slower and costs more. It returns a
+   `research_run_id`.
+2. `get_deep_research` with that `research_run_id` until the run finishes and the cited report is
+   in the result. **Start one run per request**: if you already have a `research_run_id` for this
+   question, keep polling it instead of starting another. **Never cancel because it is slow**;
+   `cancel_deep_research` is only for when the user asks to stop.
+3. Deliver the report in Step 3's answer shape, with its citations as inline links, opening with "I
+   used a TinyFish deep research run." Don't redo the research with search passes; one
+   `fetch_content` to check a load-bearing claim is fine.
+
+If the deep research tools aren't available, or the run fails, say so and offer the search-and-fetch
+passes below instead. Never swap one for the other silently.
+
 ## Auth
 
 Both tools run through the `tinyfish` CLI: `search` is `tinyfish search query "<q>"` and
@@ -60,7 +85,8 @@ With a subagent tool, each pass above becomes a delegated child instead — same
 **Ask before starting when the level is genuinely ambiguous** — when a question could reasonably be
 Moderate *or* Exhaustive. Present your reading of the question, the two plausible depths, what each
 would look like in practice, and let the user pick. Do not ask when the question is obviously trivial
-or obviously exhaustive, or when the user already stated the depth ("quick answer", "deep dive").
+or obviously exhaustive, or when the user already stated the depth ("quick answer", or an explicit
+deep research ask, which goes to "Deep research runs").
 
 If the user names a target — "find 50 of them" — keep working until you hit it or can explain why the
 web doesn't contain it.
@@ -152,7 +178,10 @@ the one-screen summary.
 
 ## Gotchas
 
-- **Over-execution.** "What year was X founded" gets one search, not four subagents.
+- **Over-execution.** "What year was X founded" gets one search, not four subagents — and never a
+  deep research run.
+- **Duplicate runs.** A slow `get_deep_research` is normal. Poll the run you have; never start
+  another or cancel it.
 - **Under-execution.** Four-plus constraints, temporal joins, or semantic filtering will not survive
   a single search. Fan out.
 - **Synonym queries.** "Overrated AI tools" and "overhyped AI tools" hit the same semantic region and

package/skill/tinyfish-web/SKILL.md

@@ -5,7 +5,8 @@ description: "Pick the right TinyFish tool for a web task. Use when a request in
 
 # Choosing a TinyFish Tool
 
-TinyFish covers reading the web and acting on it. Reading is free; acting is metered. Picking correctly
+TinyFish covers reading the web and acting on it. Reading with search and fetch is free; acting is
+metered, and so are deep research runs. Picking correctly
 is mostly about not paying for the second when the first would do.
 
 ## Decision table
@@ -15,6 +16,7 @@ is mostly about not paying for the second when the first would do.
 | Find pages, or get current information | `search` | **free** | `tinyfish-research` |
 | Read pages you have URLs for (up to 10 per call) | `fetch_content` | **free** | `tinyfish-research` |
 | Research a topic across many sources | `search` + `fetch_content`, fanned out across subagents | **free** | `tinyfish-research` |
+| Write a cited report, only when the user explicitly asks: "deep research", "deep dive", "comprehensive report", "cited report", "literature review", "survey", or "landscape" | `start_deep_research`, then `get_deep_research` | billed per run | `tinyfish-research` |
 | Click, type, submit, navigate a flow, or extract data that only appears after interaction | `run_web_automation` | $0.016/step | `tinyfish-automation` |
 | Do the above on a site the user is logged into | `run_web_automation` + `use_profile` / `use_vault` | $0.016/step | `tinyfish-authenticated` |
 | Drive a browser from Playwright, Puppeteer, or Selenium code | `create_browser_session` | $0.002/min | `tinyfish-browser` |
@@ -62,7 +64,7 @@ shell. **The CLI grammar is two-level and does not match the tool names**, so ru
 --help` before your first use of a group and follow the syntax it prints. Where this table and the
 skill text disagree, the table is right for the CLI.
 
-| These skills say | CLI command (CLI 0.49) |
+| These skills say | CLI command (CLI 0.49; `tinyfish research` 0.51) |
 |---|---|
 | `search` | `tinyfish search query "<query>"` |
 | `fetch_content` | `tinyfish fetch content get <url>...` (up to 10 URLs) |
@@ -81,6 +83,12 @@ skill text disagree, the table is right for the CLI.
 | `list_monitors`, `get_monitor`, `run_monitor`, `pause_monitor`, `resume_monitor`, `cancel_monitor` | `tinyfish monitor list`, `monitor <get\|run\|pause\|resume\|cancel> <monitor_id>` |
 | `create_browser_session`, `list_browser_sessions`, `close_browser_session` | `tinyfish browser session create`, `list`, `close <session_id>` |
 | `get_wallet`, `get_search_usage`, `list_fetch_usage` | `tinyfish wallet status`, `search usage`, `fetch usage` |
+| `start_deep_research` | `tinyfish research run "<query>" --async --pretty` (add `--mode max` only when asked) — prints the `research_run_id`. Always `--async`: a foreground run streams for minutes, and interrupting it cancels the run |
+| `get_deep_research` | `tinyfish research run get <research_run_id> --pretty` — returns at once with `<id> <status> <query>`, then the report and numbered citations once `COMPLETED`. Wait about 30 seconds between checks; don't use `research run watch`, which blocks for up to 45 minutes. `FAILED`, `CANCELLED` and `TIMED_OUT` are final. Lost the ID? `tinyfish research run list --pretty` before starting another |
+| `cancel_deep_research` | `tinyfish research run cancel <research_run_id>` |
+
+`tinyfish research` needs CLI 0.51 or later; on an older CLI, tell the user to run
+`npm i -g @tiny-fish/cli@latest`.
 
 `search query` takes `--include-domains`, `--exclude-domains`, `--location`, `--language` and `--page`
 only. The recency, date-range and `domain_type` filters in `tinyfish-research` are MCP-only; put the