gemcatch 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-19
+
+### Added
+
+- `gemcatch batch <file>` — submit many background tasks from a file in one
+  command. One prompt per non-empty line by default (`#` comments and blanks are
+  skipped); `--separator <str>` splits the file on a delimiter line so prompts
+  can span multiple lines; `-` reads the list from stdin. The whole batch is
+  tagged as a unit — `-t/--tag` sets it, otherwise an auto tag `batch-<hex>` is
+  generated and printed — so it is collectable with `gemcatch list --tag`.
+  Submissions are bounded but concurrent (four at a time, paced by `GEMCATCH_RPM`),
+  and a single failed submit is marked `failed` and reported without sinking the
+  rest of the batch. Supports `-m/--model`, `-s/--system`, `--dry-run` (parse and
+  list, submit nothing), `--json`, and `-w/--watch` (poll the batch to completion,
+  then print a combined tally).
+
+## [0.1.1] - 2026-07-19
+
+### Fixed
+
+- REST fallback (`GEMCATCH_FORCE_REST=1`, or when the SDK lacks Interactions)
+  no longer prepends the echoed prompt and the model's reasoning to the result.
+  A real Interactions response tags each step by type; only `model_output` is
+  the answer. The default SDK path was unaffected. Verified live against the API.
+
+### Changed
+
+- Require Node.js 22+. The advertised "20+" was never accurate — `commander@15`
+  requires Node `>=22.12`, and Node 20 reached end-of-life. CI now covers 22 and 24.
+- Clarified the free-tier wording in the README: `gemini-3.1-flash-lite` is free
+  within the free tier's daily quota, then billed at standard rates.
+
 ## [0.1.0] - 2026-07-17
 
 First release. Wraps the background execution capability added to the Gemini
@@ -64,5 +96,7 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/Booyaka101/gemcatch/compare/v0.2.0...HEAD
+[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
 [0.1.0]: https://github.com/Booyaka101/gemcatch/releases/tag/v0.1.0

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 20+ 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.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.
 
 1. Get a key at **<https://aistudio.google.com/apikey>**
 2. Put it in your environment:
@@ -79,6 +79,7 @@ This week in AI: ...
 | Command | What it does |
 | --- | --- |
 | `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. |
@@ -95,15 +96,16 @@ Useful flags:
 | Flag | On | Does |
 | --- | --- | --- |
 | `--json` | most commands | Machine-readable output. |
-| `-m, --model <id>` | `research` | Override the model. |
-| `-s, --system <text>` | `research` | Set a system instruction. |
+| `-m, --model <id>` | `research`, `batch` | Override the model. |
+| `-s, --system <text>` | `research`, `batch` | Set a system instruction. |
 | `-f, --file <path>` | `research` | Read the prompt from a file. |
-| `-t, --tag <tag>` | `research`, `list` | Label tasks and filter them. |
-| `-w, --watch` | `research` | Submit and wait, in one command. |
+| `-t, --tag <tag>` | `research`, `batch`, `list` | Label tasks and filter them. |
+| `-w, --watch` | `research`, `batch` | Submit and wait, in one command. |
+| `--separator <str>` | `batch` | Split the file on this delimiter line for multi-line prompts. |
 | `-i, --interval <s>` | `watch`, `daemon` | Poll rate. Default 10s for `watch`, 300s for `daemon`. |
 | `--exit-when-idle` | `daemon` | Stop once nothing is left in flight. |
 | `-n, --limit <n>` | `list` | Cap the rows. |
-| `--dry-run` | `prune` | Show what would go; delete nothing. |
+| `--dry-run` | `batch`, `prune` | Show what would go; 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.
@@ -113,7 +115,17 @@ Statuses come straight from the API: `in_progress`, `requires_action`, `complete
 ## Recipes
 
 ```bash
-# Fire off a batch, then collect later
+# Fire off a whole file of prompts in one command, then collect later.
+# Every task shares one auto-generated tag (batch-xxxxxx), printed on submit.
+$ gemcatch batch questions.txt        # one prompt per line; # and blanks skipped
+$ gemcatch daemon --exit-when-idle    # keep polling until they're all in
+$ gemcatch list --tag batch-1a2b3c --status completed
+
+# Multi-line prompts: split the file on a delimiter line instead of per-line
+$ gemcatch batch briefs.md --separator ---
+$ gemcatch batch - < questions.txt    # or pipe the list in on stdin
+
+# The same thing by hand, if you prefer a loop
 $ for q in "topic A" "topic B" "topic C"; do gemcatch research "$q" -t batch1; done
 $ gemcatch sync                       # one pass now...
 $ gemcatch daemon --exit-when-idle    # ...or keep polling until they're all in

package/index.js

@@ -2,6 +2,7 @@
 'use strict';
 
 const fs = require('fs');
+const crypto = require('crypto');
 const { Command, Option } = require('commander');
 const store = require('./db');
 const gemini = require('./gemini');
@@ -42,6 +43,12 @@ function emit(json, value, human) {
   else human();
 }
 
+// One-line preview of a prompt for the list/batch columns.
+function snippet(prompt, n = 60) {
+  const s = (prompt || '').replace(/\s+/g, ' ');
+  return s.length > n ? `${s.slice(0, n - 3)}...` : s;
+}
+
 function die(err) {
   console.error(`Error: ${err.message}`);
   process.exit(1);
@@ -168,6 +175,121 @@ program
     }
   });
 
+// --- batch ----------------------------------------------------------------
+
+// Turn a prompts file into a list of prompts. Default: one per line, skipping
+// blank lines and `#` comments. With --separator, split the whole file on that
+// delimiter line instead, so a single prompt can span multiple lines.
+function parsePrompts(text, separator) {
+  if (separator) {
+    const blocks = [];
+    let cur = [];
+    for (const line of text.split(/\r?\n/)) {
+      if (line.trim() === separator) {
+        blocks.push(cur.join('\n').trim());
+        cur = [];
+      } else {
+        cur.push(line);
+      }
+    }
+    blocks.push(cur.join('\n').trim());
+    return blocks.filter(Boolean);
+  }
+  return text
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+}
+
+// Poll just this batch until nothing tagged with it is still in flight, then
+// tally the outcome. Modelled on syncPass (a bounded refresh pass) and
+// watchTask (poll-until-terminal), but scoped to one tag.
+async function watchBatch(tag, intervalMs, json) {
+  const inFlight = () => store.listTasks({ tag }).filter((t) => t.interaction_id && !isDone(t.status));
+  let pending = inFlight();
+  while (pending.length) {
+    // A poll that throws keeps the task's old status; the next pass retries it.
+    await mapLimit(pending, 4, (t) => refresh(t).catch(() => {}));
+    pending = inFlight();
+    if (pending.length) await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  const tasks = store.listTasks({ tag });
+  const completed = tasks.filter((t) => isSuccess(t.status)).length;
+  const failed = tasks.filter((t) => isDone(t.status) && !isSuccess(t.status)).length;
+  emit(json, { tag, completed, failed, total: tasks.length }, () =>
+    console.log(dim(`Batch ${tag}: ${completed}/${tasks.length} completed, ${failed} failed.`))
+  );
+}
+
+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('-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('--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) => {
+    try {
+      const text = file === '-' ? await readStdin() : fs.readFileSync(file, 'utf8');
+      const prompts = parsePrompts(text, opts.separator);
+      if (!prompts.length) throw new Error(`no prompts found in ${file === '-' ? 'stdin' : file}`);
+      // Auto-tag so the batch is collectable as a unit; a user tag wins.
+      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)}`);
+        });
+        return;
+      }
+
+      // 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 });
+        try {
+          const r = await gemini.submit(prompt, { model: opts.model, systemInstruction: opts.system });
+          store.setInteraction(id, r.interactionId, r.status);
+          return { id, interaction_id: r.interactionId, status: r.status, prompt };
+        } catch (err) {
+          store.setStatus(id, 'failed', { error: err.message });
+          return { id, interaction_id: null, status: 'failed', prompt, error: err.message };
+        }
+      });
+      const submitted = results.filter((r) => !r.error);
+      const failed = results.filter((r) => r.error);
+
+      if (opts.watch) {
+        // The submit lines are progress, not the answer, so they go to stderr.
+        if (!opts.json) {
+          console.error(`Batch ${tag}: submitted ${submitted.length} task(s)` + (failed.length ? `, ${failed.length} failed` : '') + '. Watching...');
+        }
+        await watchBatch(tag, DEFAULT_POLL_MS, opts.json);
+        return;
+      }
+
+      emit(opts.json, { tag, submitted, failed }, () => {
+        console.log(`Batch ${tag}: submitted ${submitted.length} task(s)` + (failed.length ? `, ${failed.length} failed` : '') + '.');
+        for (const r of results) {
+          const status = r.status || PENDING;
+          // Pad before colouring: ANSI codes would break the column width.
+          const pad = ' '.repeat(Math.max(0, 16 - status.length));
+          console.log(`${r.id}  ${colorStatus(status)}${pad} ${snippet(r.prompt)}`);
+        }
+        console.log(dim('\nCollect them:'));
+        console.log(dim('  gemcatch daemon --exit-when-idle'));
+        console.log(dim(`  gemcatch list --tag ${tag} --status completed`));
+      });
+    } catch (err) {
+      die(err);
+    }
+  });
+
 // --- status ---------------------------------------------------------------
 
 program
@@ -246,8 +368,7 @@ program
     }
     console.log(dim('ID        AGE   STATUS           PROMPT'));
     for (const t of tasks) {
-      const prompt = (t.prompt || '').replace(/\s+/g, ' ');
-      const snip = prompt.length > 60 ? `${prompt.slice(0, 57)}...` : prompt;
+      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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemcatch",
-  "version": "0.1.0",
+  "version": "0.2.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": {
@@ -16,7 +16,7 @@
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "test": "node test-offline.js",