gemcatch 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +204,8 @@ 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.4.0...HEAD
+[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:
@@ -99,6 +99,8 @@ 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`. |
+| `--yes` | `research`, `batch` | 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 +112,7 @@ 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. |
+| `--dry-run` | `research`, `batch`, `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 +155,46 @@ $ 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.
+
+The agent recipe, end to end:
+
+```bash
+$ gemcatch batch questions.txt --agent deep-research --yes   # bands shown, N × total quoted
+$ gemcatch daemon --exit-when-idle                           # catch reports before the 1-day expiry
+$ gemcatch export --tag batch-1a2b3c -o reports.md           # every report, with its sources
+```
+
 ## How it works
 
 Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
@@ -160,7 +202,7 @@ 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
 ```
 
 `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 +250,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,11 @@ 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'],
 ];
 
 let _db = null;
@@ -59,8 +64,8 @@ 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) ' +
+        'VALUES (@id, @prompt, @status, @now, @now, @model, @system_instruction, @tag, @agent)'
     )
     .run({
       id,
@@ -70,6 +75,7 @@ function createTask(fields) {
       model: t.model || null,
       system_instruction: t.systemInstruction || null,
       tag: t.tag || null,
+      agent: t.agent || null,
     });
   return id;
 }
@@ -101,7 +107,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 +173,14 @@ 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();
+}
+
 function close() {
   if (_db) _db.close();
   _db = null;
@@ -185,5 +199,6 @@ module.exports = {
   removeMany,
   prunableTasks,
   counts,
+  agentCounts,
   close,
 };

package/gemini.js

@@ -3,7 +3,41 @@
 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',
+});
+
+// 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 +197,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 +211,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 +282,7 @@ function shape(r) {
     interactionId: r.id,
     status: r.status,
     text: textOf(r),
+    citations: citationsOf(r),
     usage: r.usage || null,
     raw: r,
   };
@@ -269,7 +352,13 @@ 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;
   const r = await call(() => {
     const api = sdkInteractions();
@@ -323,6 +412,9 @@ module.exports = {
   REST_BASE,
   RPM,
   MAX_RETRIES,
+  AGENT_ALIASES,
+  AGENT_PRICE_BANDS,
+  resolveAgent,
   submit,
   poll,
   cancel,
@@ -330,6 +422,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.

package/index.js

@@ -89,6 +89,104 @@ function needTask(id) {
   return task;
 }
 
+// Citations ride along with an agent's report -- the docs tell users to review
+// them to verify the sources, so they are printed under the result rather than
+// left in the database. A run without citations prints exactly as before.
+function withSources(text, citations) {
+  const body = text || '(empty response)';
+  if (!Array.isArray(citations) || !citations.length) return body;
+  const lines = citations.map((c, i) => {
+    const title = (c && (c.title || c.text)) || '';
+    const url = (c && (c.url || c.uri)) || '';
+    return `  [${i + 1}] ${[title, url].filter(Boolean).join(' — ') || JSON.stringify(c)}`;
+  });
+  return `${body}\n\nSources:\n${lines.join('\n')}`;
+}
+
+// The citations column holds JSON (or NULL). Parsed defensively: a corrupt row
+// degrades to "no sources", never a crash in the middle of printing a result.
+function parseCitations(raw) {
+  if (!raw) return null;
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) && v.length ? v : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// --- spend guard ----------------------------------------------------------
+
+// Deep Research agents are billed PER TASK, not per token -- the docs put
+// Deep Research at $1.00-$3.00 and Deep Research Max at $3.00-$7.00 -- and
+// gemcatch's whole ergonomic is firing a file of prompts at once, which turns
+// one careless `batch --agent` into a three-figure command. So no agent
+// submission happens without the cost being shown and confirmed: interactively
+// on a TTY, via --yes otherwise, and --dry-run previews without submitting.
+// The bands are quoted with the docs' own hedge ("estimates based on preview
+// rates and subject to change"), never as authoritative.
+
+function bandText(agentId, count) {
+  const band = gemini.AGENT_PRICE_BANDS[agentId];
+  if (!band) return 'no published price band for this agent';
+  const money = (n) => `$${(n * count).toFixed(2)}`;
+  return count > 1
+    ? `estimated ${money(band[0])}–${money(band[1])} total`
+    : `estimated ${money(band[0])}–${money(band[1])} for this task`;
+}
+
+function spendLine(agentId, count) {
+  const head = count > 1 ? `${count} prompts × ${agentId}` : `Agent ${agentId}`;
+  return `${head} — ${bandText(agentId, count)}`;
+}
+
+function askYesNo(question) {
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test((answer || '').trim()));
+    });
+  });
+}
+
+// Returns only when the submission is confirmed; otherwise it exits (declined)
+// or throws (no way to ask). Runs BEFORE any row is written, so a declined or
+// refused submission leaves the tasks table untouched.
+async function confirmSpend(agentId, count, opts) {
+  console.error(`${spendLine(agentId, count)} (preview rates, subject to change).`);
+  if (opts.yes) return;
+  // GEMCATCH_ASSUME_TTY lets the offline suite drive the interactive branch
+  // through a pipe; real non-TTY callers (cron, CI, scripts) must say --yes.
+  const interactive = process.stdin.isTTY || process.env.GEMCATCH_ASSUME_TTY === '1';
+  if (!interactive) {
+    throw new Error(
+      'stdin is not a TTY, so this agent submission cannot be confirmed interactively.\n' +
+        '  Pass --yes to confirm the cost above, or --dry-run to preview without submitting.'
+    );
+  }
+  if (!(await askYesNo('Submit? [y/N] '))) {
+    console.error('Nothing submitted.');
+    process.exit(1);
+  }
+}
+
+// Shared by research and batch: resolve the agent alias and reject the
+// ambiguous combination before anything is stored or sent. `--model` counts
+// only when the user actually typed it -- commander fills in the default
+// otherwise, and the default must not poison every agent run.
+function resolveAgentOpts(opts, cmd) {
+  if (!opts.agent) return null;
+  if (cmd.getOptionValueSource('model') === 'cli') {
+    throw new Error(
+      '--model and --agent are mutually exclusive: an agent run is submitted with `agent` ' +
+        'instead of `model`, and the agent picks its own models. Drop one of the two.'
+    );
+  }
+  return gemini.resolveAgent(opts.agent);
+}
+
 // --- input ----------------------------------------------------------------
 
 function readStdin() {
@@ -139,8 +237,12 @@ async function refresh(task) {
   }
   const extra = {};
   if (isDone(r.status)) {
-    if (isSuccess(r.status)) extra.result = r.text;
-    else if (r.text) extra.error = r.text;
+    if (isSuccess(r.status)) {
+      extra.result = r.text;
+      // Agent runs return citations with the report; the docs tell users to
+      // review them to verify the sources, so they are persisted, not dropped.
+      if (r.citations && r.citations.length) extra.citations = JSON.stringify(r.citations);
+    } else if (r.text) extra.error = r.text;
   }
   if (r.usage) extra.usage = JSON.stringify(r.usage);
   store.setStatus(task.id, r.status, extra);
@@ -177,22 +279,35 @@ program
   .argument('[prompt]', 'what you want researched; "-" reads stdin')
   .option('-f, --file <path>', 'read the prompt from a file')
   .option('-m, --model <id>', 'model to use', gemini.DEFAULT_MODEL)
+  .option('-a, --agent <id>', 'submit to a research agent instead of a model (e.g. deep-research)')
   .option('-s, --system <text>', 'system instruction')
   .option('-t, --tag <tag>', 'label for filtering with `gemcatch list --tag`')
   .option('-w, --watch', 'wait for the result instead of exiting')
+  .option('--yes', 'confirm the agent cost without asking (required when stdin is not a TTY)')
+  .option('--dry-run', 'show what would be submitted (and what it would cost); submit nothing')
   .option('--json', 'machine-readable output')
   .description('submit a background task and exit immediately')
-  .action(async (promptArg, opts) => {
+  .action(async (promptArg, opts, cmd) => {
     let id;
     try {
+      const agent = resolveAgentOpts(opts, cmd);
       const prompt = await resolvePrompt(promptArg, opts);
+      if (opts.dryRun) {
+        emit(opts.json, { dry_run: true, agent: agent || null, model: agent ? null : opts.model, prompt }, () => {
+          if (agent) console.log(`${spendLine(agent, 1)}. Nothing submitted (--dry-run).`);
+          else console.log(`Would submit to ${opts.model}: ${snippet(prompt)}. Nothing submitted (--dry-run).`);
+        });
+        return;
+      }
+      if (agent) await confirmSpend(agent, 1, opts);
       id = store.createTask({
         prompt,
-        model: opts.model,
+        model: agent ? null : opts.model,
+        agent,
         systemInstruction: opts.system,
         tag: opts.tag,
       });
-      const r = await gemini.submit(prompt, { model: opts.model, systemInstruction: opts.system });
+      const r = await gemini.submit(prompt, { model: opts.model, agent, systemInstruction: opts.system });
       store.setInteraction(id, r.interactionId, r.status);
       if (opts.watch) {
         // Under --watch the submit line is progress, not the answer, so it
@@ -296,15 +411,18 @@ program
   .command('batch')
   .argument('<file>', 'prompts file — one per line, or "-" to read stdin')
   .option('-m, --model <id>', 'model to use', gemini.DEFAULT_MODEL)
+  .option('-a, --agent <id>', 'submit every prompt to a research agent instead of a model')
   .option('-s, --system <text>', 'system instruction')
   .option('-t, --tag <tag>', 'tag the whole batch (default: batch-<hex>)')
   .option('--separator <str>', 'split the file on this delimiter line for multi-line prompts')
   .option('-w, --watch', 'submit all, then poll until the whole batch finishes')
+  .option('--yes', 'confirm the agent cost without asking (required when stdin is not a TTY)')
   .option('--dry-run', 'parse and list what would be submitted; submit nothing')
   .option('--json', 'machine-readable output')
   .description('submit many background tasks from a file, tagged as one batch')
-  .action(async (file, opts) => {
+  .action(async (file, opts, cmd) => {
     try {
+      const agent = resolveAgentOpts(opts, cmd);
       const text = file === '-' ? await readStdin() : fs.readFileSync(file, 'utf8');
       const { prompts, skipped } = parsePrompts(text, opts.separator);
       if (!prompts.length) throw new Error(`no prompts found in ${file === '-' ? 'stdin' : file}`);
@@ -317,19 +435,28 @@ program
       const tag = opts.tag || `batch-${crypto.randomUUID().slice(0, 6)}`;
 
       if (opts.dryRun) {
-        emit(opts.json, { tag, dry_run: true, prompts }, () => {
-          console.log(`Batch ${tag}: ${prompts.length} prompt(s) would be submitted:`);
-          for (const p of prompts) console.log(`  ${snippet(p)}`);
+        emit(opts.json, { tag, dry_run: true, agent: agent || null, prompts }, () => {
+          if (agent) {
+            // The whole point of the guard: N × the per-task band, up front.
+            console.log(`${spendLine(agent, prompts.length)}. Nothing submitted (--dry-run).`);
+          } else {
+            console.log(`Batch ${tag}: ${prompts.length} prompt(s) would be submitted:`);
+            for (const p of prompts) console.log(`  ${snippet(p)}`);
+          }
         });
         return;
       }
 
+      // An agent batch multiplies a per-task dollar band by the whole file, so
+      // it is confirmed as one total before a single row is written.
+      if (agent) await confirmSpend(agent, prompts.length, opts);
+
       // One failed submit must not sink the batch: mark that task failed and
       // keep going. mapLimit preserves input order, so the report is stable.
       const results = await mapLimit(prompts, 4, async (prompt) => {
-        const id = store.createTask({ prompt, model: opts.model, systemInstruction: opts.system, tag });
+        const id = store.createTask({ prompt, model: agent ? null : opts.model, agent, systemInstruction: opts.system, tag });
         try {
-          const r = await gemini.submit(prompt, { model: opts.model, systemInstruction: opts.system });
+          const r = await gemini.submit(prompt, { model: opts.model, agent, systemInstruction: opts.system });
           store.setInteraction(id, r.interactionId, r.status);
           return { id, interaction_id: r.interactionId, status: r.status, prompt };
         } catch (err) {
@@ -402,16 +529,17 @@ program
       // text stores `''`, which is exactly the case the cache must still serve
       // -- re-polling it would 404 after 24h, the very thing we cache to avoid.
       if (isSuccess(task.status) && task.result != null && !opts.raw) {
-        emit(opts.json, { id: task.id, status: task.status, result: task.result }, () =>
-          console.log(task.result || '(empty response)')
+        const cits = parseCitations(task.citations);
+        emit(opts.json, { id: task.id, status: task.status, result: task.result, citations: cits }, () =>
+          console.log(withSources(task.result, cits))
         );
         return;
       }
       const r = await refresh(task);
       if (opts.raw) return console.log(JSON.stringify(r.raw, null, 2));
       if (isSuccess(r.status)) {
-        emit(opts.json, { id: task.id, status: r.status, result: r.text }, () =>
-          console.log(r.text || '(empty response)')
+        emit(opts.json, { id: task.id, status: r.status, result: r.text, citations: r.citations || null }, () =>
+          console.log(withSources(r.text, r.citations))
         );
       } else if (isDone(r.status)) {
         emit(opts.json, { id: task.id, status: r.status, error: r.text || null }, () =>
@@ -450,14 +578,21 @@ program
       console.log('No tasks yet. Submit one:  gemcatch research "your question"');
       return;
     }
-    console.log(dim('ID        AGE   STATUS           PROMPT'));
+    // The AGENT column only appears when something in the listing used one, so
+    // a pure-model store keeps the compact four-column layout it always had.
+    // Agent ids are shown compact -- the "-preview-MM-YYYY" suffix is version
+    // noise in a table (the full id is in --json and in stats).
+    const showAgent = tasks.some((t) => t.agent);
+    const shortAgent = (a) => (a ? a.replace(/-preview-\d{2}-\d{4}$/, '') : '-');
+    console.log(dim(`ID        AGE   STATUS           ${showAgent ? 'AGENT              ' : ''}PROMPT`));
     for (const t of tasks) {
       const snip = snippet(t.prompt);
       const status = t.status || PENDING;
       // Pad before colouring: ANSI codes would break the column width.
       const pad = ' '.repeat(Math.max(0, 16 - status.length));
+      const agentCol = showAgent ? `${shortAgent(t.agent).padEnd(18)} ` : '';
       console.log(
-        `${t.id}  ${age(t.created_at).padEnd(4)}  ${colorStatus(status)}${pad} ${snip}`
+        `${t.id}  ${age(t.created_at).padEnd(4)}  ${colorStatus(status)}${pad} ${agentCol}${snip}`
       );
     }
   });
@@ -726,8 +861,8 @@ async function watchTask(task, intervalMs, json) {
       last = r.status;
     }
     if (isSuccess(r.status)) {
-      emit(json, { id: task.id, status: r.status, result: r.text }, () =>
-        console.log(r.text || '(empty response)')
+      emit(json, { id: task.id, status: r.status, result: r.text, citations: r.citations || null }, () =>
+        console.log(withSources(r.text, r.citations))
       );
       return;
     }
@@ -755,8 +890,9 @@ program
       // Serve a completed result from cache -- present, not merely truthy, so an
       // empty-text completion is served instead of re-polled (and lost at 24h).
       if (isSuccess(task.status) && task.result != null) {
-        emit(opts.json, { id: task.id, status: task.status, result: task.result }, () =>
-          console.log(task.result || '(empty response)')
+        const cits = parseCitations(task.citations);
+        emit(opts.json, { id: task.id, status: task.status, result: task.result, citations: cits }, () =>
+          console.log(withSources(task.result, cits))
         );
         return;
       }
@@ -850,11 +986,16 @@ program
   .description('where the store lives and what is in it')
   .action((opts) => {
     const rows = store.counts();
+    const agents = store.agentCounts();
     const total = rows.reduce((n, r) => n + r.n, 0);
-    emit(opts.json, { db: store.DB_PATH, total, by_status: rows }, () => {
+    emit(opts.json, { db: store.DB_PATH, total, by_status: rows, by_agent: agents }, () => {
       console.log(`Store: ${store.DB_PATH}`);
       console.log(`Tasks: ${total}`);
       for (const r of rows) console.log(`  ${colorStatus(r.status).padEnd(useColor ? 26 : 17)} ${r.n}`);
+      if (agents.length) {
+        console.log('Agent runs:');
+        for (const a of agents) console.log(`  ${a.agent.padEnd(34)} ${a.n}`);
+      }
     });
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemcatch",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Fire-and-forget CLI for Gemini's Interactions API background execution. Submit long-running research prompts, close your laptop, collect results later.",
   "main": "index.js",
   "bin": {
@@ -29,6 +29,7 @@
     "background",
     "async",
     "agents",
+    "deep-research",
     "cli",
     "research",
     "daemon",
@@ -46,7 +47,11 @@
   "homepage": "https://github.com/Booyaka101/gemcatch#readme",
   "dependencies": {
     "@google/genai": "^2.12.0",
-    "better-sqlite3": "^12.11.1",
+    "better-sqlite3": "^13.0.3",
     "commander": "^15.0.0"
+  },
+  "allowScripts": {
+    "@google/genai@2.15.0": true,
+    "protobufjs@7.6.5": true
   }
 }