ctxr-cli 0.38.0 → 0.40.0

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** Kept in sync with package.json's "version" field. */
-export declare const CLI_VERSION = "0.38.0";
+export declare const CLI_VERSION = "0.40.0";
 /**
  * The npm package this executable is published as. Bound here, beside the
  * version, because the release check resolves the latest published release by

package/dist/version.js

@@ -1,5 +1,5 @@
 /** Kept in sync with package.json's "version" field. */
-export const CLI_VERSION = '0.38.0';
+export const CLI_VERSION = '0.40.0';
 /**
  * The npm package this executable is published as. Bound here, beside the
  * version, because the release check resolves the latest published release by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctxr-cli",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Context store for AI coding agents — markdown and git, catalog and graph retrieval, no vector database.",
   "type": "module",
   "license": "MIT",

package/templates/skills/ctxr-capture-circleback/sweep.mjs

@@ -12,9 +12,16 @@
 // Two facts about `cb` shape this file: search results carry no tags (every `tags` field is empty), so
 // tags come from `cb meetings read`; and a meeting older than the plan's history window reads back with
 // a notice in place of its notes, which is how a locked meeting is recognised.
+//
+// Circleback's API documentation limits each account to 3 requests a second and 20 a minute on the Free plan
+// (20 and 300 on paid plans), counting every API key and CLI token of the account together; `cb` reports a
+// refusal as `rate_limited` but passes on no Retry-After. So every `cb` call is spaced to stay under the Free
+// plan's 20 a minute, which also keeps it under 3 a second; a refused call is retried after waiting out a
+// one-minute window; and if the limit still holds, the meetings not yet read are reported as deferred, keeping
+// what was already written: the next run picks them up.
 
 import { execFileSync } from 'node:child_process';
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -27,6 +34,32 @@ const PAGE_SIZE = 20;
 const READ_BATCH = 50;
 const BRANCH = 'circleback-capture';
 const LOCKED_NOTICE = 'outside the history available';
+// The Free plan's limits. The runner cannot tell which plan the account is on, so it keeps to the lowest.
+const REQUESTS_PER_MINUTE = 20;
+// A little under the limit, leaving room for whatever else uses the account and for a `cb` call that makes
+// more than one request: about 17 calls a minute.
+const CALL_SPACING_MS = Math.ceil(60_000 / REQUESTS_PER_MINUTE) + 500;
+// The minute window refills within 60 seconds, so the first retry waits half of it and the rest a whole one.
+const RETRY_DELAYS_MS = [30_000, 60_000, 60_000];
+const RATE_LIMITED = /"reason"\s*:\s*"rate_limited"/;
+// Every wait is multiplied by this. Only the tests set it, to 0; a store never does.
+const WAIT_SCALE = Number.isFinite(Number(process.env.CTXR_CIRCLEBACK_WAIT_SCALE)) ? Number(process.env.CTXR_CIRCLEBACK_WAIT_SCALE) : 1;
+
+/** Thrown when `cb` is still rate-limited after every retry. */
+class RateLimited extends Error {}
+
+function pause(ms) {
+  const wait = ms * WAIT_SCALE;
+  if (wait > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, wait);
+}
+
+let lastCbCall = -Infinity;
+
+/** Waits until CALL_SPACING_MS has passed since the previous `cb` call, retries included. */
+function spaceCbCall() {
+  pause(Math.max(0, lastCbCall + CALL_SPACING_MS - Date.now()));
+  lastCbCall = Date.now();
+}
 
 function run(command, args, { cwd, check = true } = {}) {
   try {
@@ -34,12 +67,32 @@ function run(command, args, { cwd, check = true } = {}) {
   } catch (error) {
     if (!check) return error.stdout ?? '';
     const detail = String(error.stderr || error.message).trim().slice(0, 300);
-    throw new Error(`${command} ${args.slice(0, 2).join(' ')} failed: ${detail}`);
+    throw Object.assign(new Error(`${command} ${args.slice(0, 2).join(' ')} failed: ${detail}`), {
+      output: `${error.stdout ?? ''}\n${error.stderr ?? ''}`,
+    });
   }
 }
 
+/** One `cb` call, retried with backoff while Circleback reports a rate limit. */
 function cb(args) {
-  return JSON.parse(run('cb', [...args, '--json']));
+  for (let attempt = 0; ; attempt += 1) {
+    let output;
+    spaceCbCall();
+    try {
+      output = run('cb', [...args, '--json']);
+    } catch (error) {
+      if (!RATE_LIMITED.test(error.output ?? '')) throw error;
+      if (attempt >= RETRY_DELAYS_MS.length) throw new RateLimited(error.message);
+      pause(RETRY_DELAYS_MS[attempt]);
+      continue;
+    }
+    const result = JSON.parse(output);
+    if (result?.status !== 'error') return result;
+    // An error printed as the result, with a zero exit: treat it the same as a failed call.
+    if (!RATE_LIMITED.test(output)) throw new Error(`cb ${args.slice(0, 2).join(' ')} failed: ${output.trim().slice(0, 300)}`);
+    if (attempt >= RETRY_DELAYS_MS.length) throw new RateLimited(`cb ${args.slice(0, 2).join(' ')} failed: ${output.trim().slice(0, 300)}`);
+    pause(RETRY_DELAYS_MS[attempt]);
+  }
 }
 
 function storeRoot() {
@@ -134,9 +187,17 @@ function prepareWorktree(root, settings) {
   return { worktree, continuing: open[0]?.number };
 }
 
-function captureFileName(meeting) {
-  const slug = meeting.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || meeting.id;
-  return `circleback-${meeting.createdAt.slice(0, 10)}-${slug}.md`;
+/**
+ * Where a meeting's record goes in the inbox: named for its date and title, with the meeting id added when that
+ * name is already taken. The slug keeps only ASCII letters and digits, so two titles mostly in another script can
+ * reduce to the same name, and one record must never overwrite another, from this run or already in the inbox.
+ */
+function captureFilePath(inbox, meeting) {
+  const date = meeting.createdAt.slice(0, 10);
+  const slug = meeting.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const named = path.join(inbox, `circleback-${date}-${slug || meeting.id}.md`);
+  if (!existsSync(named)) return named;
+  return path.join(inbox, `circleback-${date}-${slug ? `${slug}-` : ''}${meeting.id}.md`);
 }
 
 /** The mechanical part of a capture. The speaker judgment is the agent's, added afterwards. */
@@ -232,12 +293,26 @@ function main() {
     mkdirSync(inbox, { recursive: true });
     report.push(`\nWORKTREE: ${worktree} (branch \`${BRANCH}\`, ${continuing ? `continuing pull request #${continuing}` : `fresh from origin/${settings.default_branch}`})`);
     report.push('RETRIEVED (verbatim records in the inbox; continue with ctxr-capture from step 2):');
+    const deferred = [];
     for (const meeting of owed) {
-      const transcript = cb(['transcripts', 'read', meeting.id]);
-      const file = path.join(inbox, captureFileName(meeting));
+      // Once the limit has outlasted every retry, read nothing more this run.
+      if (deferred.length > 0) {
+        deferred.push(line(meeting));
+        continue;
+      }
+      let transcript;
+      try {
+        transcript = cb(['transcripts', 'read', meeting.id]);
+      } catch (error) {
+        if (!(error instanceof RateLimited)) throw error;
+        deferred.push(line(meeting));
+        continue;
+      }
+      const file = captureFilePath(inbox, meeting);
       writeFileSync(file, renderCapture(meeting, transcript, settings));
       report.push(file);
     }
+    report.push(...section('DEFERRED — owed, but Circleback is rate-limiting transcript reads; the next run retrieves them', deferred));
   }
   report.push(
     ...section('UNPUSHED — captured in a local worktree but not on the default branch or in an open pull request; land that work', unpushed),

package/templates/skills/ctxr-capture-circleback.md

@@ -25,6 +25,12 @@ writes the record into `__INBOX_PATH__` there: the meeting's metadata and attend
 summary (marked as the service's derivation), and the transcript verbatim, with `source_type` and `source_id`
 stamped. It never writes the recording URL, which is a signed, expiring link and so a credential.
 
+Circleback's free plan allows an account 20 requests a minute, counting every other use of the same account. The
+runner spaces its calls to stay under that, so a large backlog takes a few minutes, and waits and retries when it is
+refused anyway. If the limit still holds, it keeps the records it already wrote and lists the meetings it could not
+read under DEFERRED; the next run retrieves them. That is a partial result, not a failure: carry on with what was
+retrieved.
+
 The report is authoritative. Do not work the list out again yourself, and do not rebuild the files it wrote. If it
 prints `COLLECTION FAILED`, report that line and stop.
 
@@ -53,6 +59,7 @@ Give the counts (retrieved, already present), the pull request link, and the run
 they are:
 
 - **LOCKED**: tagged for this store but no longer readable in full, so it cannot be captured.
+- **DEFERRED**: owed, but not read this run because of the rate limit. The next run retrieves them.
 - **UNPUSHED**: captured in a local worktree but not yet on the default branch or in a pull request. That work
   needs landing; nothing here captures it again.
 - **UNTAGGED**, **TAGGED FOR MORE THAN ONE STORE** and **DECLINED IN THE LAST 8 DAYS**, when the runner prints them.