gemcatch 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,113 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-04
+
+### Added
+
+- **Collaborative planning.** Until now the only agent flow was a blind one-shot
+  bet: gemcatch showed a cost band, asked y/N, and fired. The cost band was
+  everything you knew before spending, and there was no way to check the agent
+  had read the prompt the way you meant it. A 20-line `batch` against
+  `deep-research-max` is a $60–$140 command placed sight unseen. The Deep
+  Research docs have always documented a second mode for exactly this, and
+  gemcatch could not reach it. Now it can:
+
+  - `--plan` on `research` and `batch` submits with
+    `agent_config.collaborative_planning: true`, so **the agent returns a
+    research plan instead of a report**. Still `background: true`, still stored,
+    still collected by the daemon. The row is stored with `kind='plan'`.
+  - `gemcatch get <id>` on a plan prints the plan and then the literal next
+    command, `Approve with: gemcatch approve 8f3a1c04 · Refine with: gemcatch
+    refine 8f3a1c04 "..."`, on stderr, so `get <plan> > plan.md` still captures
+    just the plan.
+  - `gemcatch refine <id> "<instruction>"` sends the instruction back with
+    `previous_interaction_id` and planning still on, and stores the revised plan
+    linked to the one it came from, inheriting its agent and tag.
+  - `gemcatch approve <id>` is the turn that commits: `previous_interaction_id`
+    with `collaborative_planning: false`, stored as `kind='report'` linked to the
+    plan. It shows the cost band and asks, honours `--yes` when stdin is not a
+    TTY, and honours `--dry-run`.
+
+  **Planning is not cheaper.** The docs give one band per task and do not price a
+  planning turn separately, so a planning turn is quoted at the same band and the
+  line says so: *"the docs price per task and do not price a planning turn
+  separately"*. What you get for it is a look at the plan before you commit to
+  the research run, not a discount.
+- `gemcatch list` renders a chain indented under its root, in submission order,
+  and grows a `KIND` column when a listing contains plans or reports (a store
+  with neither keeps the layout it had). `gemcatch export` follows a chain to its
+  report and leaves the intermediate plans out unless `--include-plans` is
+  passed; the Markdown sections and the JSON rows now name the turn.
+- `gemcatch stats` now tallies plan and report turns, and totals the estimated
+  spend across the agent turns that were actually billed, from the same
+  published bands the guard quotes before each one. A chain bills per turn, so a
+  release that turns one submission into three owes the user a running total. It
+  is the documented bands applied to what was submitted, not a reading of your
+  bill, and it errs toward telling you rather than flattering you: only runs
+  that reached the server are priced (a submit that failed before it left the
+  machine is counted as an attempt but costs nothing), and an agent with no
+  published band totals to `unknown`, never to `$0.00`. A store with no agent
+  runs prints neither line.
+- Additive schema migration: `collaborative_planning`, `previous_interaction_id`,
+  `kind` (defaulting to `'task'`) and `parent_id`. A 0.4.0 `tasks.db` upgrades in
+  place, keeps every row, and behaves exactly as it did.
+
+### Fixed
+
+- `approve` and `refine` fail before sending anything when the target is not a
+  plan, or is a plan that has not completed. A plan whose interaction the free
+  tier has already dropped names the retention window (1 day free, 55 days paid)
+  instead of sending a `previous_interaction_id` the server would reject. A plan
+  that expires *after* it completed locally gets the same explanation rather
+  than a bare 404 for an id the user never typed.
+- `--plan` without `--agent` (or with `--model`) is a clean error rather than a
+  flag that quietly does nothing: collaborative planning is an agent feature.
+- Approving the same plan twice submits a second run rather than silently
+  reusing the first, and `list` shows both under their plan.
+
+## [0.4.0] - 2026-08-08
+
+### Added
+
+- **Research agents.** `-a, --agent <id>` on `research` and `batch` submits to a
+  Gemini Deep Research agent instead of a model — `interactions.create` is sent
+  `agent` *instead of* `model` (they are mutually exclusive, and passing both is
+  a clean error). Aliases resolve through one table: `deep-research` →
+  `deep-research-preview-04-2026`, `deep-research-max` →
+  `deep-research-max-preview-04-2026`; any other value passes through unchanged,
+  so a future agent id works without a gemcatch release. Agents *require*
+  background execution, which gemcatch has always set — and on the free tier the
+  finished report is dropped after 1 day, which is exactly the race the daemon
+  exists to win. The agent is recorded per task, shown in `list` (the AGENT
+  column appears when a listing contains agent runs) and tallied in `stats`.
+- **Spend guard.** Deep Research is documented at $1.00–$3.00 per task and Deep
+  Research Max at $3.00–$7.00 (estimates based on preview rates, per the docs,
+  and subject to change). Every agent submission prints its band first —
+  `batch` prints N × the band as a total — and asks for an interactive `y/N`
+  confirmation. When stdin is not a TTY, `--yes` is required and anything else
+  is refused before a row is written; declining writes nothing and exits
+  non-zero. `--dry-run` (now on `research` too) prints the full projected spend
+  and submits nothing.
+- **Citations.** Agent runs return citations alongside the report; the docs say
+  to review them to verify the sources, so they are persisted (new `citations`
+  column, JSON) rather than discarded, printed under the result as a `Sources:`
+  list, and carried in `--json` output.
+- Result extraction now takes the **final answer-bearing step** — where the
+  docs place an agent's completed report (`steps[-1].content[0].text`) and
+  where a model run's `model_output` already sits — with a fall-back to the old
+  collect-everything behaviour if that step carries no text, so an unexpected
+  shape can never silently blank a result. No special-casing on the agent id.
+- Additive schema migration: `agent` and `citations` columns. A pre-0.4.0
+  `tasks.db` upgrades in place, keeps every row, and reports `agent` as NULL
+  for them.
+
+### Changed
+
+- The default model is now **`gemini-3.5-flash-lite`** (GA on 2026-07-21),
+  replacing the older `gemini-3.1-flash-lite`. Override with `GEMCATCH_MODEL`
+  or `--model` as before.
+
 ## [0.3.0] - 2026-07-19
 
 ### Added
@@ -162,7 +269,9 @@ seen a task complete, the text is cached locally and survives that expiry — bu
 something has to poll inside that window for it to be seen at all, which is what
 `gemcatch daemon` exists to do.
 
-[Unreleased]: https://github.com/Booyaka101/gemcatch/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Booyaka101/gemcatch/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/Booyaka101/gemcatch/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/Booyaka101/gemcatch/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Booyaka101/gemcatch/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Booyaka101/gemcatch/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Booyaka101/gemcatch/compare/v0.1.0...v0.1.1

package/README.md

@@ -24,7 +24,7 @@ The EU AI Act's high-risk obligations phase in from August 2026, whereas...
 
 ## Setup
 
-Needs Node.js 22+ and a Gemini API key. **Getting a key needs no billing account and no card.** `gemini-3.1-flash-lite` runs free within the [free tier's](https://ai.google.dev/gemini-api/docs/pricing) daily quota; past that, paid rates apply.
+Needs Node.js 22+ and a Gemini API key. **Getting a key needs no billing account and no card.** `gemini-3.5-flash-lite` (the default model, GA since July 2026) runs free within the [free tier's](https://ai.google.dev/gemini-api/docs/pricing) daily quota; past that, paid rates apply.
 
 1. Get a key at **<https://aistudio.google.com/apikey>**
 2. Put it in your environment:
@@ -81,8 +81,10 @@ This week in AI: ...
 | `gemcatch research "<prompt>"` | Submits with `background: true`, stores the interaction ID, exits immediately. |
 | `gemcatch batch <file>` | Submits many prompts from a file at once, tagged as one collectable batch. |
 | `gemcatch status <id>` | Polls the API and prints the current state. |
-| `gemcatch get <id>` | Prints the full response if complete, otherwise the current status. |
-| `gemcatch list` | All tasks, newest first: id, age, status, prompt. |
+| `gemcatch get <id>` | Prints the full response if complete, otherwise the current status. On a [plan](#see-the-plan-before-you-pay-for-the-run), the plan plus the approve/refine commands. |
+| `gemcatch refine <id> "<instruction>"` | Sends an instruction back to a plan and returns a revised plan. |
+| `gemcatch approve <id>` | Approves a plan and submits the research run it describes. |
+| `gemcatch list` | All tasks, newest first: id, age, status, prompt. Plan chains are indented under their root. |
 | `gemcatch export` | Concatenates finished results, each under its prompt, to stdout or a file (Markdown or JSON). |
 | `gemcatch digest` | Feeds a tag's completed results through one Gemini call into a single summary. |
 | `gemcatch watch <id>` | Polls until the task finishes, then prints the result. |
@@ -91,7 +93,7 @@ This week in AI: ...
 | `gemcatch cancel <id>` | Asks the API to stop an in-flight task. |
 | `gemcatch rm <ids...>` | Forgets tasks locally. `--remote` deletes them server-side too. |
 | `gemcatch prune` | Drops finished tasks older than `--days` (default 30). |
-| `gemcatch stats` | Where the store lives and what's in it. |
+| `gemcatch stats` | Where the store lives, what's in it, and what the agent runs have plausibly cost. |
 
 Useful flags:
 
@@ -99,6 +101,9 @@ Useful flags:
 | --- | --- | --- |
 | `--json` | most commands | Machine-readable output. |
 | `-m, --model <id>` | `research`, `batch` | Override the model. |
+| `-a, --agent <id>` | `research`, `batch` | Submit to a [research agent](#research-agents) instead of a model. Mutually exclusive with `--model`. |
+| `--plan` | `research`, `batch` | Ask the agent for a [research plan](#see-the-plan-before-you-pay-for-the-run) first, to refine and approve. Needs `--agent`. |
+| `--yes` | `research`, `batch`, `refine`, `approve` | Confirm the agent cost without asking. Required for `--agent` when stdin is not a TTY. |
 | `-s, --system <text>` | `research`, `batch` | Set a system instruction. |
 | `-f, --file <path>` | `research` | Read the prompt from a file. |
 | `-t, --tag <tag>` | `research`, `batch`, `list` | Label tasks and filter them. |
@@ -110,7 +115,8 @@ Useful flags:
 | `-n, --limit <n>` | `list` | Cap the rows (non-negative; `0` shows none). |
 | `--format <md\|json>` | `export` | Output format. Default `md`. |
 | `-o, --out <file>` | `export` | Write to a file instead of stdout. |
-| `--dry-run` | `batch`, `prune` | Show what would go; submit/delete nothing. |
+| `--include-plans` | `export` | Also emit a chain's plan turns, not just its report. |
+| `--dry-run` | `research`, `batch`, `refine`, `approve`, `prune` | Show what would go — including the projected agent spend; submit/delete nothing. |
 | `--raw` | `get` | Dump the raw interaction JSON. |
 
 IDs are the first 8 characters of a UUID. Any unique prefix works, so `gemcatch get 8f3a` is fine.
@@ -153,6 +159,129 @@ $ id=$(gemcatch research "..." --json | jq -r .id)
 $ gemcatch watch "$id" --json | jq -r .result
 ```
 
+## Research agents
+
+The [Gemini Deep Research agents](https://ai.google.dev/gemini-api/docs/deep-research) are reachable only through the Interactions API, and the docs are explicit: *"You must use background execution (set `background=true`) to run the agent asynchronously and poll for results or stream updates."* That is precisely the half of the job `gemcatch` already does — it always sets `background: true`, owns the polling, and its daemon collects results before the free tier drops interactions after **1 day** (paid tier: 55 days). A Deep Research run takes minutes and you were never going to sit there holding the connection; submit it, and let the daemon catch it.
+
+```console
+$ gemcatch research "map the EU AI Act high-risk obligations against the UK approach" --agent deep-research
+Agent deep-research-preview-04-2026 — estimated $1.00–$3.00 for this task (preview rates, subject to change).
+Submit? [y/N] y
+Task 8f3a1c04 submitted. Run: gemcatch get 8f3a1c04 when ready.
+```
+
+`--agent` takes an alias or a raw agent id:
+
+| You type | Sent to the API |
+| --- | --- |
+| `deep-research` | `deep-research-preview-04-2026` |
+| `deep-research-max` | `deep-research-max-preview-04-2026` |
+| anything else | passed through unchanged (future agent ids work without a gemcatch release; a bad id fails fast with the API's own 4xx) |
+
+An agent is sent **instead of** a model — the agent picks its own models — so `--model` and `--agent` together is an error, and nothing is submitted.
+
+**These agents cost real money, per task.** The docs put Deep Research at **$1.00–$3.00 per task** and Deep Research Max at **$3.00–$7.00 per task** — with their own hedge attached: *"These figures are estimates based on preview rates and are subject to change."* Because `gemcatch batch` fires a whole file at once, a 20-line file against `deep-research-max` is a **$60–$140 command**, so every agent submission shows its band and asks first. In a script (stdin not a TTY) you must pass `--yes`; `--dry-run` prints the full projected spend and submits nothing:
+
+```console
+$ gemcatch batch questions.txt --agent deep-research-max --dry-run
+20 prompts × deep-research-max-preview-04-2026 — estimated $60.00–$140.00 total. Nothing submitted (--dry-run).
+```
+
+The report lands like any other result — final answer only, none of the agent's interim plan — and its **citations** come with it. The docs tell you to review them to verify the sources, so `gemcatch get` prints them under the report as a `Sources:` list, `--json` carries them as an array, and they live in the store alongside the result.
+
+An agent run can also come back `incomplete` — that is what a `max_total_tokens` budget cap produces when the run "safely pauses" — which `gemcatch` treats as terminal, exactly like the API does: the daemon retires it and moves on.
+
+### See the plan before you pay for the run
+
+A cost band tells you what a run will cost. It tells you nothing about whether the agent understood the question. Add `--plan` and it doesn't start researching: with `agent_config.collaborative_planning: true`, *"the agent returns a research plan instead of a full report"*. You read it, push back on it, and approve it when it's right.
+
+```console
+$ gemcatch research "map the EU AI Act high-risk obligations against the UK approach" --agent deep-research --plan -t euuk
+Agent deep-research-preview-04-2026 (planning turn) — estimated $1.00–$3.00 for this task (preview rates, subject to change; the docs price per task and do not price a planning turn separately).
+Submit? [y/N] y
+Plan task d014e21b submitted. Run: gemcatch get d014e21b when ready.
+
+$ gemcatch get d014e21b
+Research plan
+
+1. Scope the EU AI Act high-risk regime: Annex III use cases, Article 6 classification,
+   and the Chapter III obligations (risk management, data governance, logging, human
+   oversight, conformity assessment) with their August 2026 / August 2027 dates.
+2. Scope the UK approach: the five cross-sector principles, the regulator-led model
+   (ICO, FCA, MHRA, Ofcom), and what is guidance rather than statute.
+3. Build an obligation-by-obligation comparison table: EU requirement, nearest UK
+   equivalent, whether it is binding, and who enforces it.
+4. Flag the gaps in both directions and the compliance implications for a firm
+   operating in both.
+Approve with: gemcatch approve d014e21b   ·   Refine with: gemcatch refine d014e21b "..."
+
+$ gemcatch refine d014e21b "cut the history, and add enforcement penalties on both sides"
+Plan task 2140e699 submitted (refines d014e21b). Run: gemcatch get 2140e699 when ready.
+
+$ gemcatch approve 2140e699
+Agent deep-research-preview-04-2026 — estimated $1.00–$3.00 for this task (preview rates, subject to change).
+Submit? [y/N] y
+Task 96e8209b submitted (approves plan 2140e699).
+```
+
+Every turn is an ordinary background task: stored, polled, and collected by the daemon before the 1-day expiry, same as everything else. `refine` chains as many times as you like; each revision inherits the agent and tag of the plan it came from.
+
+**A planning turn is a task, and it is billed as one.** The docs publish one band per task and price no planning turn separately, so `gemcatch` quotes the same band for it and says exactly that on the line. What `--plan` buys you is a look at the plan before you commit to the research run, not a discount. Budget for the plan, each refinement, and the run.
+
+Since a chain bills per turn, `gemcatch stats` keeps a running total across all of them:
+
+```console
+$ gemcatch stats
+Store: ~/.gemcatch/tasks.db
+Tasks: 3
+  completed         3
+Agent runs:
+  deep-research-preview-04-2026      3
+Plan chains: 2 plan, 1 report
+Estimated spend: $3.00–$9.00 across 3 billed task(s) (preview rates, subject to change).
+```
+
+That's the chain above: one plan, one refinement, one run, three tasks at the same band. It's the published bands applied to what you actually submitted, not a reading of your bill, and it errs toward telling you rather than flattering you:
+
+- Only runs that **reached the server** are priced. A submit that failed before it left the machine (bad key, rejected agent id) is still counted under "Agent runs" as an attempt, but it costs nothing and isn't billed.
+- An agent with **no published band** totals to `unknown`, never to `$0.00`. Quoting zero for a run that costs real money is the one thing a spend guard must not do.
+
+`list` shows the chain as one thing, and `export` follows it to the report:
+
+```console
+$ gemcatch list
+ID        AGE   STATUS           KIND    AGENT              PROMPT
+d014e21b  22s   completed        plan    deep-research      map the EU AI Act high-risk obligations against the UK ap...
+2140e699  12s   completed        plan    deep-research      └─ cut the history, and add enforcement penalties on both sides
+96e8209b  7s    completed        report  deep-research        └─ map the EU AI Act high-risk obligations against the UK ap...
+
+$ gemcatch export --tag euuk -o report.md
+Wrote 1 result(s) to report.md.
+```
+
+The plans are working notes on the way to the report, so `export` leaves them out; pass `--include-plans` if you want the whole chain in the document. The report is filed under the question that started the chain rather than the one-line approval actually sent to the API, so an exported document reads as research.
+
+A few things that will bite otherwise:
+
+- `--plan` needs `--agent`. Collaborative planning is an agent feature, so `--plan --model ...` (or `--plan` on its own) is an error, not a no-op.
+- `approve` only works on a plan that has completed. Anything else fails before a request goes out.
+- On the free tier the plan's interaction is dropped after a day. Once that happens the chain cannot be continued. `approve` says so and names the window instead of sending a `previous_interaction_id` the server will reject. Run the daemon, or approve the same day.
+- Approving twice submits twice. There is no dedupe, and both runs show up under the plan in `list`.
+- `--plan` and `--watch` work together: `gemcatch research "..." --agent deep-research --plan -w` waits for the plan and then prints it.
+
+The agent recipe, end to end:
+
+```bash
+$ gemcatch batch questions.txt --agent deep-research --plan --yes   # a plan per prompt, N × band quoted
+$ gemcatch daemon --exit-when-idle                                  # catch the plans
+$ gemcatch list --tag batch-1a2b3c                                  # read them, approve the good ones
+$ gemcatch approve 8f3a1c04 --yes
+$ gemcatch daemon --exit-when-idle                                  # catch the reports before the 1-day expiry
+$ gemcatch export --tag batch-1a2b3c -o reports.md                  # every report, with its sources
+```
+
+Drop `--plan` and the first two lines become the 0.4.0 one-shot flow, which still works exactly as it did.
+
 ## How it works
 
 Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
@@ -160,7 +289,8 @@ Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
 ```sql
 CREATE TABLE tasks (id TEXT PRIMARY KEY, prompt TEXT, interaction_id TEXT,
                     status TEXT DEFAULT 'pending', result TEXT, created_at INTEGER);
--- plus model, system_instruction, tag, error, usage, updated_at
+-- plus model, system_instruction, tag, error, usage, updated_at, agent, citations,
+--      collaborative_planning, previous_interaction_id, kind, parent_id
 ```
 
 `research` calls `interactions.create({model, input, background: true})` via [`@google/genai`](https://www.npmjs.com/package/@google/genai) and keeps the returned `id`. The polling commands call `interactions.get(id)` and write the status back. Once a task completes, the text is cached in the `result` column — `gemcatch get` then answers from disk without touching the network.
@@ -208,7 +338,7 @@ Transient failures are retried with exponential backoff and full jitter, honouri
 | --- | --- |
 | `GEMINI_API_KEY` | Your API key. `GOOGLE_API_KEY` also works. |
 | `GEMCATCH_HOME` | Where `tasks.db` lives. Default `~/.gemcatch`. |
-| `GEMCATCH_MODEL` | Default model. Default `gemini-3.1-flash-lite`. |
+| `GEMCATCH_MODEL` | Default model. Default `gemini-3.5-flash-lite`. |
 | `GEMCATCH_POLL_MS` | `watch` poll interval in ms. Default `10000`. |
 | `GEMCATCH_DAEMON_S` | `daemon` interval in seconds. Default `300`. |
 | `GEMCATCH_RPM` | Requests/minute ceiling. Default `15` (the free tier). `0` disables pacing. |

package/db.js

@@ -26,6 +26,22 @@ const MIGRATIONS = [
   ['error', 'TEXT'],
   ['usage', 'TEXT'],
   ['updated_at', 'INTEGER'],
+  // 0.4.0: agent runs. `agent` is the resolved agent id the task was submitted
+  // with (NULL for model runs, including every pre-0.4.0 row); `citations` is
+  // the JSON array of sources an agent run returned alongside its report.
+  ['agent', 'TEXT'],
+  ['citations', 'TEXT'],
+  // 0.5.0: collaborative planning. `collaborative_planning` is the agent_config
+  // flag the row was submitted with (1 plan turn, 0 report turn, NULL for every
+  // run that sent no agent_config at all, including every pre-0.5.0 row);
+  // `previous_interaction_id` is the interaction this turn continues;
+  // `kind` is 'task' | 'plan' | 'report'; `parent_id` is the local task this
+  // turn continues. The DEFAULT backfills 'task' for older rows, so a 0.4.0
+  // store keeps behaving exactly as it did.
+  ['collaborative_planning', 'INTEGER'],
+  ['previous_interaction_id', 'TEXT'],
+  ['kind', "TEXT DEFAULT 'task'"],
+  ['parent_id', 'TEXT'],
 ];
 
 let _db = null;
@@ -59,8 +75,10 @@ function createTask(fields) {
   const now = Date.now();
   db()
     .prepare(
-      'INSERT INTO tasks (id, prompt, status, created_at, updated_at, model, system_instruction, tag) ' +
-        'VALUES (@id, @prompt, @status, @now, @now, @model, @system_instruction, @tag)'
+      'INSERT INTO tasks (id, prompt, status, created_at, updated_at, model, system_instruction, tag, agent, ' +
+        'kind, parent_id, collaborative_planning, previous_interaction_id) ' +
+        'VALUES (@id, @prompt, @status, @now, @now, @model, @system_instruction, @tag, @agent, ' +
+        '@kind, @parent_id, @collaborative_planning, @previous_interaction_id)'
     )
     .run({
       id,
@@ -70,6 +88,13 @@ function createTask(fields) {
       model: t.model || null,
       system_instruction: t.systemInstruction || null,
       tag: t.tag || null,
+      agent: t.agent || null,
+      kind: t.kind || 'task',
+      parent_id: t.parentId || null,
+      // Presence, not truthiness: `false` is the report turn's real flag and
+      // must be stored as 0, while a run that sends no agent_config stores NULL.
+      collaborative_planning: t.collaborativePlanning === undefined ? null : Number(!!t.collaborativePlanning),
+      previous_interaction_id: t.previousInteractionId || null,
     });
   return id;
 }
@@ -101,7 +126,7 @@ function setStatus(id, status, extra) {
   const e = extra || {};
   const sets = ['status = @status', 'updated_at = @now'];
   const params = { id, status, now: Date.now() };
-  for (const key of ['result', 'error', 'usage']) {
+  for (const key of ['result', 'error', 'usage', 'citations']) {
     if (e[key] !== undefined) {
       sets.push(`${key} = @${key}`);
       params[key] = e[key];
@@ -167,6 +192,35 @@ function counts() {
   return db().prepare('SELECT status, COUNT(*) AS n FROM tasks GROUP BY status').all();
 }
 
+// Per-agent totals for `stats`. Model runs (agent IS NULL) are not a row here;
+// they are already accounted for in counts().
+function agentCounts() {
+  return db()
+    .prepare('SELECT agent, COUNT(*) AS n FROM tasks WHERE agent IS NOT NULL GROUP BY agent')
+    .all();
+}
+
+// Agent runs that actually reached the server, keyed by agent. A submit that
+// never got an interaction_id (a bad key, a rejected agent id, a network
+// failure) was never billed, so it must not appear in a spend total -- unlike
+// agentCounts(), which tallies every attempt.
+function billedAgentCounts() {
+  return db()
+    .prepare(
+      'SELECT agent, COUNT(*) AS n FROM tasks WHERE agent IS NOT NULL AND interaction_id IS NOT NULL GROUP BY agent'
+    )
+    .all();
+}
+
+// Plan/report totals for `stats`. Ordinary tasks are not a row here; they are
+// already accounted for in counts(), and a store that has never planned reports
+// nothing at all.
+function kindCounts() {
+  return db()
+    .prepare("SELECT kind, COUNT(*) AS n FROM tasks WHERE kind IS NOT NULL AND kind != 'task' GROUP BY kind")
+    .all();
+}
+
 function close() {
   if (_db) _db.close();
   _db = null;
@@ -185,5 +239,8 @@ module.exports = {
   removeMany,
   prunableTasks,
   counts,
+  agentCounts,
+  billedAgentCounts,
+  kindCounts,
   close,
 };

package/gemini.js

@@ -3,7 +3,47 @@
 const { isDone, isSuccess } = require('./status');
 
 // Free of charge on the Gemini free tier; override per-call with --model.
-const DEFAULT_MODEL = process.env.GEMCATCH_MODEL || 'gemini-3.1-flash-lite';
+// gemini-3.5-flash-lite went GA on 2026-07-21 (it replaced 3.1 as the
+// low-latency free-tier workhorse in the same release that deprecated the
+// sampling parameters).
+const DEFAULT_MODEL = process.env.GEMCATCH_MODEL || 'gemini-3.5-flash-lite';
+
+// --- agents ---------------------------------------------------------------
+
+// The Deep Research agents are reachable ONLY through the Interactions API,
+// and only with background execution -- which gemcatch always sets. An agent
+// is sent as `agent` on create, INSTEAD of `model`: the two are mutually
+// exclusive, and the CLI rejects the combination before anything is written.
+//
+// This table is the ONE place the full preview ids live. They are preview ids
+// and will be superseded; call sites must resolve through here (or pass an
+// unknown id straight through, so a future agent works without a release).
+const AGENT_ALIASES = Object.freeze({
+  'deep-research': 'deep-research-preview-04-2026',
+  'deep-research-max': 'deep-research-max-preview-04-2026',
+});
+
+// `agent_config.type` for the config block a collaborative-planning turn sends.
+// Both documented Deep Research agents use the same value, and an unknown
+// pass-through id is assumed to be one too -- collaborative planning is a Deep
+// Research feature, so there is nothing else it could be.
+const AGENT_CONFIG_TYPE = 'deep-research';
+
+// Documented per-task price bands, in dollars, keyed by the RESOLVED id.
+// The docs' own hedge applies -- "These figures are estimates based on
+// preview rates and are subject to change" -- so the spend guard quotes
+// them as estimates, never as authoritative.
+const AGENT_PRICE_BANDS = Object.freeze({
+  'deep-research-preview-04-2026': Object.freeze([1, 3]),
+  'deep-research-max-preview-04-2026': Object.freeze([3, 7]),
+});
+
+// A known alias resolves to its full preview id; anything else passes through
+// unchanged so a new or newer agent id works without a gemcatch release (a
+// genuinely bad id fails fast: the API 4xxes, and a 4xx never retries).
+function resolveAgent(id) {
+  return AGENT_ALIASES[id] || id;
+}
 
 // Overridable for tests and for routing via a proxy/gateway.
 const REST_BASE =
@@ -163,7 +203,11 @@ function collectText(node, acc) {
     return acc;
   }
   if (typeof node.text === 'string' && node.text.trim()) acc.push(node.text);
-  for (const v of Object.values(node)) {
+  for (const [k, v] of Object.entries(node)) {
+    // Citations are sources *about* the answer, not answer text: an agent step
+    // carries them alongside its content, and a citation's own title/snippet
+    // must not be concatenated into the result. They are collected separately.
+    if (k === 'citations') continue;
     if (v && typeof v === 'object') collectText(v, acc);
   }
   return acc;
@@ -173,21 +217,65 @@ function collectText(node, acc) {
 // internal reasoning with the actual answer, each tagged by `type`:
 //   [ {type:'user_input', ...}, {type:'thought', ...}, {type:'model_output', ...} ]
 // Collecting text indiscriminately prepends the prompt (and any reasoning) to
-// the result, so those step types are skipped. Anything else -- model_output,
-// an untyped step, a future answer-bearing type -- still contributes, so a
-// renamed step never silently blanks the result.
+// the result, so those step types are skipped.
+//
+// Both kinds of run put the deliverable in the FINAL answer-bearing step. A
+// model run ends [user_input, thought, model_output]; an agent run's steps
+// additionally interleave its plan, searches and interim drafts, and the docs
+// place the finished report at `interaction.steps[-1].content[0].text`. So one
+// rule serves both, with no special-casing on the agent id: take the last step
+// that is not user_input/thought. If that step somehow carries no text -- an
+// unexpected shape, a renamed type -- fall back to collecting across every
+// answer-bearing step, so the failure mode is "too much text", never a
+// silently blank result.
 const NON_ANSWER_STEP = new Set(['user_input', 'thought']);
 
 function textFromSteps(steps) {
   if (!Array.isArray(steps)) return '';
+  const candidates = steps.filter((s) => !(s && NON_ANSWER_STEP.has(s.type)));
+  if (!candidates.length) return '';
+  const last = collectText(candidates[candidates.length - 1], []).join('\n').trim();
+  if (last) return last;
   const acc = [];
-  for (const step of steps) {
-    if (step && NON_ANSWER_STEP.has(step.type)) continue;
-    collectText(step, acc);
-  }
+  for (const step of candidates) collectText(step, acc);
   return acc.join('\n').trim();
 }
 
+// Agent runs carry citations -- the docs explicitly tell users to review them
+// to verify the sources -- so they are gathered rather than discarded. The
+// walk is shape-agnostic (any `citations` array anywhere in the interaction),
+// because the docs do not pin down where they attach; duplicates are dropped.
+function collectCitations(node, acc) {
+  if (!node || typeof node !== 'object') return acc;
+  if (Array.isArray(node)) {
+    for (const n of node) collectCitations(n, acc);
+    return acc;
+  }
+  for (const [k, v] of Object.entries(node)) {
+    if (k === 'citations' && Array.isArray(v)) {
+      for (const c of v) if (c && typeof c === 'object') acc.push(c);
+      continue;
+    }
+    if (v && typeof v === 'object') collectCitations(v, acc);
+  }
+  return acc;
+}
+
+function citationsOf(interaction) {
+  const all = collectCitations(interaction, []);
+  if (!all.length) return null;
+  const seen = new Set();
+  const out = [];
+  for (const c of all) {
+    const key = JSON.stringify(c);
+    if (!seen.has(key)) {
+      seen.add(key);
+      out.push(c);
+    }
+  }
+  return out;
+}
+
 function textOf(interaction) {
   if (interaction && typeof interaction.output_text === 'string' && interaction.output_text) {
     return interaction.output_text;
@@ -200,6 +288,7 @@ function shape(r) {
     interactionId: r.id,
     status: r.status,
     text: textOf(r),
+    citations: citationsOf(r),
     usage: r.usage || null,
     raw: r,
   };
@@ -269,8 +358,29 @@ function restHeaders() {
 
 async function submit(prompt, opts) {
   const o = opts || {};
-  const body = { model: o.model || DEFAULT_MODEL, input: prompt, background: true };
+  // `agent` and `model` are mutually exclusive on create: an agent run is sent
+  // with `agent` INSTEAD of `model` (the agent picks its own models). `input`
+  // stays a plain string and `background` stays true either way -- agents
+  // *require* background execution, which gemcatch has always set.
+  const body = o.agent
+    ? { agent: o.agent, input: prompt, background: true }
+    : { model: o.model || DEFAULT_MODEL, input: prompt, background: true };
   if (o.systemInstruction) body.system_instruction = o.systemInstruction;
+  // collaborative_planning is an `agent_config` field, NOT a top-level one, and
+  // the docs send the whole block (type + thinking_summaries) with it. Sent only
+  // when a plan turn is involved -- agent_config is optional otherwise, so an
+  // ordinary run keeps making exactly the request it always made. Presence, not
+  // truthiness: `false` is the approval turn's real value and must reach the API.
+  if (o.collaborativePlanning !== undefined) {
+    body.agent_config = {
+      type: AGENT_CONFIG_TYPE,
+      thinking_summaries: 'auto',
+      collaborative_planning: !!o.collaborativePlanning,
+    };
+  }
+  // Continues an earlier interaction server-side: the plan is already in that
+  // conversation, so this turn sends only what changed.
+  if (o.previousInteractionId) body.previous_interaction_id = o.previousInteractionId;
   const r = await call(() => {
     const api = sdkInteractions();
     return api
@@ -323,6 +433,10 @@ module.exports = {
   REST_BASE,
   RPM,
   MAX_RETRIES,
+  AGENT_ALIASES,
+  AGENT_PRICE_BANDS,
+  AGENT_CONFIG_TYPE,
+  resolveAgent,
   submit,
   poll,
   cancel,
@@ -330,6 +444,7 @@ module.exports = {
   apiKey,
   textOf,
   collectText,
+  citationsOf,
   // Exported for the suite: the retry policy is behaviour worth pinning.
   shouldRetry,
   // Re-exported so callers need only one require.