gemcatch 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-24
+
+### Added
+
+- **Research over your own data.** A Deep Research agent could only read the
+  public web through gemcatch, while the API has always let it read much more.
+  Five new flags on `research` and `batch` open that up, listed under their own
+  heading in `--help`. All of them need `--agent`; without it gemcatch exits
+  with one line naming the flag and writes nothing.
+
+  - `--attach <path|url>` (repeatable) gives the agent a PDF, CSV or image.
+    Local files go inline, in order, while the request stays under the API's
+    inline limit (100 MB, or 50 MB once a PDF is in it). The file that would
+    cross it, and every one after, is uploaded through the Files API and sent by
+    URI. Uploads expire after 48 hours, and a `--plan` run prints when. An https
+    URL is sent by reference, its query string masked everywhere but the wire,
+    and one without a supported extension is typed from a HEAD request (a
+    one-byte GET if HEAD is refused). Unknown types, missing and empty files are refused in one
+    line before the spend confirmation, with a hint to export Word files as PDF
+    and spreadsheets as CSV. A file that changes size between that check and
+    the send is refused too. A `batch` of more than one prompt uploads every
+    local file once instead of sending it inline with each prompt.
+  - `--mcp <url>` (repeatable) adds a remote MCP server, named after its host
+    unless `--mcp-name` says otherwise. `--mcp-header 'Name: value'` and
+    `--mcp-allow tool,tool` apply to the `--mcp` before them. Header values
+    and URL credentials are masked in the confirmation, `--dry-run`,
+    `list --json`, `get --raw` and API errors. A header value can read
+    `${VAR}` from the environment at send time, so the token never reaches
+    `tasks.db`; a value written out in full is kept there, since a later turn
+    has to resend it. On POSIX systems the data directory and the images
+    folder are now 0700, and `tasks.db` and each image 0600. A local or
+    private address, or credentials over plain http, get a warning.
+  - `--file-search <store>` (repeatable) lets the agent search File Search
+    stores, all in one `file_search` tool.
+  - `--no-web` drops Google Search and URL Context so the agent reads only what
+    you gave it. Code Execution stays, because it's how the agent works through a
+    CSV and draws a chart. It's refused when nothing else was given to read.
+  - `--visualize` sets `agent_config.visualization: "auto"`, alongside
+    `collaborative_planning` when `--plan` is also given. Charts in the final
+    report are written to the data directory's `images/` folder as
+    `<task-id>-<n>.<ext>`, recorded in the store, and listed under the report by
+    `get`, `watch` and `digest` and as `images` in `--json`. `export -o` copies
+    them next to the export and links them; `rm` and `prune` delete them.
+
+  Once a tool flag is given, the request lists Google Search, URL Context and
+  Code Execution alongside the new sources, because an explicit `tools` list
+  replaces the agent's defaults. `--attach` on its own sends no `tools` field.
+  `refine` and `approve` resend the plan's tools and visualization setting;
+  attachments go with the first turn only. `--dry-run` and the spend
+  confirmation list the sources above the cost, and `list` gains a SOURCES
+  column when a listed task used any of this.
+- An unknown `--flag=value` option is reported without its value, which could
+  be a token.
+- Additive schema migration: `tools_json`, `attachments_json`, `visualization`
+  and `images_json`, all nullable. A 0.5.0 `tasks.db` upgrades in place and
+  behaves exactly as it did.
+
+### Notes
+
+- A run with none of the new flags sends the same request body, byte for byte,
+  as 0.5.0 did, and a result without charts prints the same text.
+
 ## [0.5.0] - 2026-09-04
 
 ### Added
@@ -269,7 +331,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.5.0...HEAD
+[Unreleased]: https://github.com/Booyaka101/gemcatch/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/Booyaka101/gemcatch/compare/v0.5.0...v0.6.0
 [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

package/README.md

@@ -103,6 +103,11 @@ Useful flags:
 | `-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`. |
+| `--attach <path\|url>` | `research`, `batch` | Give the agent a PDF, CSV or image ([your own data](#research-over-your-own-data)). Repeatable. Needs `--agent`. |
+| `--mcp <url>` | `research`, `batch` | Let the agent call a remote MCP server. Repeatable; `--mcp-header`, `--mcp-allow` and `--mcp-name` apply to the one before them. Needs `--agent`. |
+| `--file-search <store>` | `research`, `batch` | Let the agent search a File Search store. Repeatable. Needs `--agent`. |
+| `--no-web` | `research`, `batch` | Drop Google Search and URL Context, so the agent reads only what you gave it. Needs `--agent`. |
+| `--visualize` | `research`, `batch` | Let the agent draw charts; they're saved as image files. 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. |
@@ -282,6 +287,81 @@ $ gemcatch export --tag batch-1a2b3c -o reports.md                  # every repo
 
 Drop `--plan` and the first two lines become the 0.4.0 one-shot flow, which still works exactly as it did.
 
+## Research over your own data
+
+Out of the box a Deep Research agent reads the public web. These flags hand it your files, your MCP servers and your File Search stores as well, and `--visualize` lets it draw charts. They are agent features, so every one of them needs `--agent`. Without it gemcatch stops with one line naming the flag and sends nothing.
+
+### Files: `--attach`
+
+```console
+$ gemcatch research "Which region is growing fastest, and does the board pack agree?" --agent deep-research \
+    --attach sales-2026.csv --attach q3-board-pack.pdf --attach whiteboard.png \
+    --attach customer-contracts-2026.pdf --yes
+Attachments: sales-2026.csv (inline, 1 KB); q3-board-pack.pdf (inline, 1 KB); whiteboard.png (inline, 1 KB); customer-contracts-2026.pdf (upload, 40.0 MB)
+Agent deep-research-preview-04-2026 — estimated $1.00–$3.00 for this task (preview rates, subject to change).
+Uploading customer-contracts-2026.pdf (40.0 MB) to the Files API...
+Task 7cf00c5b submitted. Run: gemcatch get 7cf00c5b when ready.
+```
+
+PDF and CSV go in as documents; PNG, JPEG, WebP, HEIC, HEIF, GIF and BMP as images. The type comes from the extension, and anything else is refused before you're asked to pay, with a nudge to export a Word file as PDF or a spreadsheet as CSV. `--attach` also takes an https URL, which is passed to the agent by reference. A URL with no supported extension (arxiv's `https://arxiv.org/pdf/1706.03762`, say) gets one HEAD request to read its Content-Type, or a one-byte GET if the server refuses HEAD. The query string of a signed URL is sent as given and shown as `***` everywhere else, the store included.
+
+Local files are sent inline, in the order given, as long as the request stays under the API's inline limit: 100 MB of base64, or 50 MB once a PDF is in it. The first file that doesn't fit, and every file after it, goes up through the Files API instead and is referenced by URI. Google keeps uploads for 48 hours. On a `--plan` run gemcatch prints when they expire, and a `refine` or `approve` after that gets a warning. A file given twice is sent once.
+
+In a `batch` with more than one prompt, every local file is uploaded, once, and each prompt points at the upload. Inline bytes would otherwise go over the wire again with every prompt.
+
+Files go with the first turn only. A `refine` or `approve` continues the same conversation, and the files are already in it.
+
+### MCP servers: `--mcp`
+
+```console
+$ gemcatch research "Which accounts are at risk of churn this quarter?" --agent deep-research --plan --yes \
+    --mcp https://mcp.example-crm.com/mcp \
+    --mcp-header 'Authorization: Bearer ${CRM_TOKEN}' \
+    --mcp-allow search_accounts,get_account
+Tools: google_search; url_context; code_execution; MCP mcp.example-crm.com https://mcp.example-crm.com/mcp (Authorization: ***) [search_accounts, get_account]
+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).
+Plan task 5451f8b9 submitted. Run: gemcatch get 5451f8b9 when ready.
+```
+
+`--mcp` is repeatable, and `--mcp-header`, `--mcp-allow` and `--mcp-name` apply to the `--mcp` just before them. The server is named after its host unless you pass `--mcp-name`, and two servers on one host become `host` and `host-2`. Giving two servers the same `--mcp-name`, or one server the same header twice, is refused. Google's servers make the call, not your machine, so the URL has to be reachable from the internet; a localhost or private address gets a warning, and so does a plain `http://` URL that carries credentials.
+
+Header values, and any user, password, query string or fragment in an MCP URL, never appear in anything gemcatch prints: the confirmation, `--dry-run`, `list --json`, `get --raw` and API errors all show `***`.
+
+Note the single quotes in the example. gemcatch reads `${CRM_TOKEN}` from the environment itself, each time a turn is sent, so `tasks.db` only ever holds the reference. A `refine` or `approve` needs the variable set too, and stops in one line naming it if it isn't. A value written out in full, or expanded by your shell, is stored as given, because a later turn has to send it again. On Linux and macOS gemcatch keeps `~/.gemcatch` readable by you alone.
+
+### File Search stores: `--file-search`
+
+```console
+$ gemcatch research "What does our playbook say about discounting?" --agent deep-research \
+    --file-search sales-playbooks --no-web --dry-run
+Tools: code_execution; File Search fileSearchStores/sales-playbooks
+Agent deep-research-preview-04-2026 — estimated $1.00–$3.00 for this task. Nothing submitted (--dry-run).
+```
+
+Repeat it for more stores; they all go in one `file_search` tool. A bare name gets `fileSearchStores/` put in front of it. gemcatch doesn't create or fill stores, [the File Search docs](https://ai.google.dev/gemini-api/docs/file-search) cover that.
+
+### Charts: `--visualize`
+
+```console
+$ gemcatch research "Which region is growing fastest, and does the board pack agree?" --agent deep-research \
+    --attach sales-2026.csv --visualize --yes -w
+...
+(report text)
+
+Images:
+  /home/you/.gemcatch/images/7cf00c5b-1.png
+```
+
+This sets `agent_config.visualization` to `auto`, next to `collaborative_planning` when you also pass `--plan`. The charts in the final report are written to the data directory's `images/` folder as `<task-id>-<n>.<ext>`, and listed under the report by `get`, `watch` and `digest`, and as `images` in `--json`. `export -o report.md` copies them next to the export and links them in the Markdown. `rm` and `prune` delete them with the task.
+
+### What the agent can reach: `--no-web`
+
+With no source flags gemcatch sends no `tools` field and the agent gets its defaults: Google Search, URL Context and Code Execution. The API reads an explicit list as the whole set, so once you add `--mcp` or `--file-search`, gemcatch lists those three back in alongside your sources. `--attach` alone sends no list at all, since a file isn't a tool.
+
+`--no-web` drops Google Search and URL Context, so the agent works only from what you gave it. Code Execution stays: it can't reach the web, and it's what the agent uses to crunch a CSV and draw a chart. On its own `--no-web` is refused, because it would leave the agent nothing to read.
+
+`refine` and `approve` send the plan's tools and visualization setting again, so every turn of a chain reaches the same sources. Once a task in the listing used any of this, `list` grows a SOURCES column (`mcp`, `store`, `no-web`, `2 files`, `charts`).
+
 ## How it works
 
 Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
@@ -290,7 +370,8 @@ Tasks live in SQLite at `~/.gemcatch/tasks.db` (override with `GEMCATCH_HOME`):
 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, agent, citations,
---      collaborative_planning, previous_interaction_id, kind, parent_id
+--      collaborative_planning, previous_interaction_id, kind, parent_id,
+--      tools_json, attachments_json, visualization, images_json
 ```
 
 `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.
@@ -340,6 +421,7 @@ Transient failures are retried with exponential backoff and full jitter, honouri
 | `GEMCATCH_HOME` | Where `tasks.db` lives. Default `~/.gemcatch`. |
 | `GEMCATCH_MODEL` | Default model. Default `gemini-3.5-flash-lite`. |
 | `GEMCATCH_POLL_MS` | `watch` poll interval in ms. Default `10000`. |
+| `GEMCATCH_UPLOAD_POLL_MS` | How often an upload still being processed by the Files API is checked, in ms. Default `2000`. |
 | `GEMCATCH_DAEMON_S` | `daemon` interval in seconds. Default `300`. |
 | `GEMCATCH_RPM` | Requests/minute ceiling. Default `15` (the free tier). `0` disables pacing. |
 | `GEMCATCH_MAX_RETRIES` | Extra attempts on a transient failure. Default `4`. `0` disables retries. |

package/db.js

@@ -42,6 +42,15 @@ const MIGRATIONS = [
   ['previous_interaction_id', 'TEXT'],
   ['kind', "TEXT DEFAULT 'task'"],
   ['parent_id', 'TEXT'],
+  // 0.6.0: sources. `tools_json` is the tools array the row was submitted with
+  // (header values included, so it is masked wherever it is printed);
+  // `attachments_json` records what was attached on this turn, never the bytes;
+  // `visualization` is the agent_config value; `images_json` lists the image
+  // files saved from the result. All NULL for a run that used none of them.
+  ['tools_json', 'TEXT'],
+  ['attachments_json', 'TEXT'],
+  ['visualization', 'TEXT'],
+  ['images_json', 'TEXT'],
 ];
 
 let _db = null;
@@ -57,8 +66,18 @@ function migrate(d) {
 
 function db() {
   if (_db) return _db;
-  fs.mkdirSync(HOME, { recursive: true });
+  const created = fs.mkdirSync(HOME, { recursive: true, mode: 0o700 });
   _db = new Database(DB_PATH);
+  // Rows can hold MCP header values. mkdir's mode only applies to a new
+  // directory, so an existing ~/.gemcatch is tightened too; a GEMCATCH_HOME the
+  // user already had is left alone. SQLite gives the -wal and -shm files the
+  // database file's mode. Best effort: some mounts refuse chmod.
+  if (process.platform !== 'win32') {
+    try {
+      if (!created && !process.env.GEMCATCH_HOME) fs.chmodSync(HOME, 0o700);
+      fs.chmodSync(DB_PATH, 0o600);
+    } catch (_) {}
+  }
   _db.pragma('journal_mode = WAL');
   _db.exec(BASE_SCHEMA);
   migrate(_db);
@@ -76,9 +95,11 @@ function createTask(fields) {
   db()
     .prepare(
       'INSERT INTO tasks (id, prompt, status, created_at, updated_at, model, system_instruction, tag, agent, ' +
-        'kind, parent_id, collaborative_planning, previous_interaction_id) ' +
+        'kind, parent_id, collaborative_planning, previous_interaction_id, ' +
+        'tools_json, attachments_json, visualization, images_json) ' +
         'VALUES (@id, @prompt, @status, @now, @now, @model, @system_instruction, @tag, @agent, ' +
-        '@kind, @parent_id, @collaborative_planning, @previous_interaction_id)'
+        '@kind, @parent_id, @collaborative_planning, @previous_interaction_id, ' +
+        '@tools_json, @attachments_json, @visualization, @images_json)'
     )
     .run({
       id,
@@ -95,6 +116,10 @@ function createTask(fields) {
       // 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,
+      tools_json: t.toolsJson || null,
+      attachments_json: t.attachmentsJson || null,
+      visualization: t.visualization || null,
+      images_json: t.imagesJson || null,
     });
   return id;
 }
@@ -126,7 +151,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', 'citations']) {
+  for (const key of ['result', 'error', 'usage', 'citations', 'images_json']) {
     if (e[key] !== undefined) {
       sets.push(`${key} = @${key}`);
       params[key] = e[key];

package/gemini.js

@@ -1,6 +1,9 @@
 'use strict';
 
+const fs = require('fs');
+const path = require('path');
 const { isDone, isSuccess } = require('./status');
+const { redactText } = require('./sources');
 
 // Free of charge on the Gemini free tier; override per-call with --model.
 // gemini-3.5-flash-lite went GA on 2026-07-21 (it replaced 3.1 as the
@@ -48,6 +51,9 @@ function resolveAgent(id) {
 // Overridable for tests and for routing via a proxy/gateway.
 const REST_BASE =
   process.env.GEMCATCH_BASE_URL || 'https://generativelanguage.googleapis.com/v1beta/interactions';
+// The Files API shares the Interactions API's version root, with uploads under
+// /upload/<version>/files. Derived from REST_BASE so a gateway moves both.
+const API_ROOT = REST_BASE.replace(/\/interactions\/?$/, '');
 
 function envNum(name, dflt) {
   const raw = process.env[name];
@@ -195,21 +201,25 @@ async function call(fn) {
 
 // --- response shaping -----------------------------------------------------
 
-// output_text is added by the SDK, so REST responses need text pulled from steps.
-function collectText(node, acc) {
-  if (!node || typeof node !== 'object') return acc;
+// Depth-first over every object in a response. `citations` subtrees are
+// sources *about* the answer, not answer content: an agent step carries them
+// alongside its content, and a citation's own title/snippet must not be read as
+// answer text, so the walk never enters them. They are collected separately.
+function walk(node, visit, skip = (k) => k === 'citations') {
+  if (!node || typeof node !== 'object') return;
   if (Array.isArray(node)) {
-    for (const n of node) collectText(n, acc);
-    return acc;
-  }
-  if (typeof node.text === 'string' && node.text.trim()) acc.push(node.text);
-  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);
+    for (const n of node) walk(n, visit, skip);
+    return;
   }
+  visit(node);
+  for (const [k, v] of Object.entries(node)) if (!skip(k, v)) walk(v, visit, skip);
+}
+
+// output_text is added by the SDK, so REST responses need text pulled from steps.
+function collectText(node, acc) {
+  walk(node, (n) => {
+    if (typeof n.text === 'string' && n.text.trim()) acc.push(n.text);
+  });
   return acc;
 }
 
@@ -230,9 +240,12 @@ function collectText(node, acc) {
 // silently blank result.
 const NON_ANSWER_STEP = new Set(['user_input', 'thought']);
 
+function answerSteps(steps) {
+  return Array.isArray(steps) ? steps.filter((s) => !(s && NON_ANSWER_STEP.has(s.type))) : [];
+}
+
 function textFromSteps(steps) {
-  if (!Array.isArray(steps)) return '';
-  const candidates = steps.filter((s) => !(s && NON_ANSWER_STEP.has(s.type)));
+  const candidates = answerSteps(steps);
   if (!candidates.length) return '';
   const last = collectText(candidates[candidates.length - 1], []).join('\n').trim();
   if (last) return last;
@@ -246,18 +259,10 @@ function textFromSteps(steps) {
 // 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);
-  }
+  walk(node, (n) => {
+    if (!Array.isArray(n.citations)) return;
+    for (const c of n.citations) if (c && typeof c === 'object') acc.push(c);
+  }, (k, v) => k === 'citations' && Array.isArray(v));
   return acc;
 }
 
@@ -283,11 +288,26 @@ function textOf(interaction) {
   return textFromSteps(interaction && interaction.steps);
 }
 
+// With agent_config.visualization the agent's charts come back as image content
+// ({type:'image', data:<base64>, mime_type}) in the same final step as the
+// report. Interim drafts can carry images too, so only that step is read.
+function imagesOf(interaction) {
+  const candidates = answerSteps(interaction && interaction.steps);
+  const images = [];
+  walk(candidates[candidates.length - 1], (n) => {
+    if (n.type === 'image' && typeof n.data === 'string' && n.data) {
+      images.push({ data: n.data, mime_type: n.mime_type || 'image/png' });
+    }
+  });
+  return images;
+}
+
 function shape(r) {
   return {
     interactionId: r.id,
     status: r.status,
     text: textOf(r),
+    images: imagesOf(r),
     citations: citationsOf(r),
     usage: r.usage || null,
     raw: r,
@@ -296,30 +316,40 @@ function shape(r) {
 
 // --- transports -----------------------------------------------------------
 
-let _api;
+let _client;
 
-function sdkInteractions() {
+function sdkClient() {
   // GEMCATCH_FORCE_REST exercises the raw-fetch fallback without uninstalling the
   // SDK. Checked every call so it always wins over the memo below.
   if (process.env.GEMCATCH_FORCE_REST === '1') return null;
-  if (_api !== undefined) return _api;
+  if (_client !== undefined) return _client;
   let GoogleGenAI;
   try {
     ({ GoogleGenAI } = require('@google/genai'));
   } catch (_) {
-    _api = null;
-    return _api;
+    _client = null;
+    return _client;
   }
   // apiKey() throws before the memo is written, so a missing key keeps
   // reporting itself instead of being cached as "no SDK".
-  const client = new GoogleGenAI({ apiKey: apiKey() });
-  const i = client.interactions;
+  _client = new GoogleGenAI({ apiKey: apiKey() });
+  return _client;
+}
+
+function sdkInteractions() {
+  const c = sdkClient();
+  const i = c && c.interactions;
   // Only use the SDK if background is genuinely first-class here.
-  _api = i && typeof i.create === 'function' && typeof i.get === 'function' ? i : null;
-  return _api;
+  return i && typeof i.create === 'function' && typeof i.get === 'function' ? i : null;
 }
 
-async function restJson(url, init) {
+function sdkFiles() {
+  const c = sdkClient();
+  const f = c && c.files;
+  return f && typeof f.upload === 'function' && typeof f.get === 'function' ? f : null;
+}
+
+async function restRequest(url, init) {
   let res;
   try {
     res = await fetch(url, init);
@@ -345,7 +375,11 @@ async function restJson(url, init) {
     }
   }
   if (!res.ok) throw apiError(res.status, body, res.headers);
-  return Array.isArray(body) ? body[0] : body;
+  return { body: Array.isArray(body) ? body[0] : body, headers: res.headers };
+}
+
+async function restJson(url, init) {
+  return (await restRequest(url, init)).body;
 }
 
 // NOTE: the API key goes in x-goog-api-key. `Authorization: Bearer <key>` is
@@ -360,36 +394,110 @@ async function submit(prompt, opts) {
   const o = opts || {};
   // `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.
+  // stays a plain string unless files are attached, and `background` stays true
+  // either way -- agents *require* background execution, which gemcatch has
+  // always set.
+  const input = o.attachments && o.attachments.length ? [{ type: 'text', text: prompt }, ...o.attachments] : prompt;
   const body = o.agent
-    ? { agent: o.agent, input: prompt, background: true }
-    : { model: o.model || DEFAULT_MODEL, input: prompt, background: true };
+    ? { agent: o.agent, input, background: true }
+    : { model: o.model || DEFAULT_MODEL, input, background: true };
   if (o.systemInstruction) body.system_instruction = o.systemInstruction;
+  // An explicit tools list replaces the agent's defaults, so it is sent only
+  // when the user named a source; a plain run leaves the field out entirely.
+  if (o.tools) body.tools = o.tools;
   // 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,
-    };
+  // when a plan turn or visualization 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 || o.visualization) {
+    body.agent_config = { type: AGENT_CONFIG_TYPE };
+    if (o.collaborativePlanning !== undefined) {
+      body.agent_config.thinking_summaries = 'auto';
+      body.agent_config.collaborative_planning = !!o.collaborativePlanning;
+    }
+    if (o.visualization) body.agent_config.visualization = o.visualization;
   }
   // 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
-      ? api.create(body)
-      : restJson(REST_BASE, { method: 'POST', headers: restHeaders(), body: JSON.stringify(body) });
-  });
+  let r;
+  try {
+    r = await call(() => {
+      const api = sdkInteractions();
+      return api
+        ? api.create(body)
+        : restJson(REST_BASE, { method: 'POST', headers: restHeaders(), body: JSON.stringify(body) });
+    });
+  } catch (err) {
+    // A 400 can quote the request back; MCP header values are credentials.
+    const urls = (o.attachments || []).map((a) => a.uri).filter(Boolean);
+    err.message = redactText(err.message, o.tools, urls);
+    throw err;
+  }
   return shape(r);
 }
 
+// Google's resumable upload, in its single-request form: start a session, then
+// send every byte and finalize in one go. Returns the File resource.
+async function restUpload(filePath, mime) {
+  const blob = await fs.openAsBlob(filePath, { type: mime });
+  const root = new URL(API_ROOT);
+  const start = await restRequest(`${root.origin}/upload${root.pathname.replace(/\/$/, '')}/files`, {
+    method: 'POST',
+    headers: {
+      ...restHeaders(),
+      'X-Goog-Upload-Protocol': 'resumable',
+      'X-Goog-Upload-Command': 'start',
+      'X-Goog-Upload-Header-Content-Length': String(blob.size),
+      'X-Goog-Upload-Header-Content-Type': mime,
+    },
+    body: JSON.stringify({ file: { display_name: path.basename(filePath) } }),
+  });
+  const session = start.headers.get('x-goog-upload-url');
+  if (!session) {
+    const e = new Error('the Files API did not return an upload URL');
+    e.code = 'NETWORK';
+    throw e;
+  }
+  const done = await restJson(session, {
+    method: 'POST',
+    headers: { 'X-Goog-Upload-Offset': '0', 'X-Goog-Upload-Command': 'upload, finalize' },
+    body: blob,
+  });
+  return (done && done.file) || done;
+}
+
+const UPLOAD_POLL_MS = envNum('GEMCATCH_UPLOAD_POLL_MS', 2000);
+const UPLOAD_WAIT_MS = 10 * 60 * 1000;
+
+// Uploads a local file through the Files API and waits until it can be used.
+// Resolves to {uri, expiresAt} (ms since epoch; Google keeps files 48 hours).
+async function upload(filePath, mime) {
+  let file = await call(() => {
+    const files = sdkFiles();
+    return files
+      ? files.upload({ file: filePath, config: { mimeType: mime, displayName: path.basename(filePath) } })
+      : restUpload(filePath, mime);
+  });
+  const failed = (why) => Object.assign(new Error(`upload of ${path.basename(filePath)} failed: ${why}`), { code: 'UPLOAD_FAILED' });
+  const deadline = Date.now() + UPLOAD_WAIT_MS;
+  while (file && file.state === 'PROCESSING') {
+    if (Date.now() > deadline) throw failed(`still processing after ${UPLOAD_WAIT_MS / 60000} minutes`);
+    await sleep(UPLOAD_POLL_MS);
+    const name = file.name;
+    file = await call(() => {
+      const files = sdkFiles();
+      return files ? files.get({ name }) : restJson(`${API_ROOT}/${name}`, { method: 'GET', headers: restHeaders() });
+    });
+  }
+  if (!file || !file.uri || file.state === 'FAILED') {
+    throw failed((file && file.error && file.error.message) || 'no usable file came back');
+  }
+  return { uri: file.uri, expiresAt: Date.parse(file.expirationTime) || null };
+}
+
 async function poll(interactionId) {
   const r = await call(() => {
     const api = sdkInteractions();
@@ -438,6 +546,7 @@ module.exports = {
   AGENT_CONFIG_TYPE,
   resolveAgent,
   submit,
+  upload,
   poll,
   cancel,
   remove,