@anyslate/cli 0.3.0 → 0.4.0

package/src/guard.mjs

@@ -0,0 +1,381 @@
+// Client-side circuit breaker and local call ceiling — `~/.anyslate/cli-guard.json`.
+//
+// WHY THIS HAS TO BE ON DISK. Every hook invocation is its own process. An
+// in-memory breaker would be reconstructed, empty, fifty times a minute, which
+// is exactly the shape of the 2026-08-02 overload: one machine with a stale
+// refresh token issued `POST /oauth/token` + `POST /mcp` continuously for hours
+// because each new process started with no memory that the last fifty had all
+// been rejected. The breaker is only useful if it OUTLIVES the process.
+//
+// WHAT IT ENFORCES
+//   * after repeated 401s (or one definitively dead credential) capture is
+//     paused for an escalating period, the user is told ONCE how to fix it
+//     (`anyslate login`), and until then the client makes no request at all,
+//   * a `Retry-After` from a 429/503 becomes a persisted pause, so the wait is
+//     honoured by whichever process runs next rather than by a sleeping hook,
+//   * repeated transport failures (the server saying "overloaded") pause too,
+//     so a struggling service is not kept under load by its own clients,
+//   * a generous per-minute ceiling on calls from this machine, as a backstop
+//     against a runaway agent that is succeeding at fifty calls a minute.
+//
+// FINGERPRINTING, SO A FIX IS NOT PUNISHED. The breaker is bound to the
+// (apiUrl, credential) pair that tripped it. Point the CLI at a different
+// service root, swap the token, or run `anyslate login`, and it no longer
+// applies — otherwise "I fixed my config" would still mean fifteen minutes of
+// dead capture. An OAuth session is fingerprinted by its `client_id`, which
+// survives refresh-token rotation; if it did not, every refresh would silently
+// reset the breaker and we would be back to the storm.
+//
+// FAILS OPEN, ALWAYS. Every function here swallows its own I/O errors. A
+// guard file we cannot read or write must never be the reason a user's capture
+// or login stops working — a local cache blip converting into a lockout is a
+// worse failure than the one this module prevents.
+
+import { createHash } from 'node:crypto';
+import { unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { anyslateDir } from './config.mjs';
+import { readJsonFile, writeJsonFile } from './credentials.mjs';
+
+export const GUARD_FILE = 'cli-guard.json';
+
+/** Consecutive 401s before capture is paused. One is a blip; three is a state. */
+export const AUTH_FAILURES_BEFORE_OPEN = 3;
+
+/** Consecutive transport failures before we stop leaning on a struggling host. */
+export const TRANSIENT_FAILURES_BEFORE_OPEN = 5;
+
+/**
+ * Escalating pauses. A credential that is still dead after 15 minutes is not
+ * going to be alive at 16, and the user has already been told what to do — so
+ * the client backs further off rather than re-asking every quarter hour.
+ */
+export const AUTH_PAUSE_LADDER_MS = [15 * 60_000, 60 * 60_000, 6 * 60 * 60_000, 24 * 60 * 60_000];
+export const TRANSIENT_PAUSE_LADDER_MS = [30_000, 2 * 60_000, 10 * 60_000, 30 * 60_000];
+
+/** Clamp on a server-named wait: long enough to respect, short enough to recover from. */
+export const MIN_THROTTLE_MS = 1_000;
+export const MAX_THROTTLE_MS = 60 * 60_000;
+
+/**
+ * Machine-wide ceiling on capture calls per rolling minute. Set well above any
+ * human session (a busy Claude Code hour is single-digit calls per minute) —
+ * it exists to cap a runaway loop, not to shape normal traffic.
+ * `ANYSLATE_MAX_CALLS_PER_MINUTE=0` disables it.
+ */
+export const DEFAULT_CALLS_PER_MINUTE = 60;
+
+/** Auth failures that no amount of retrying can resolve — pause on the first one. */
+const TERMINAL_AUTH_CODES = new Set([
+  'invalid_grant',
+  'no_refresh_token',
+  'no_oauth_credentials',
+  'no_credentials',
+  'unauthorized_client',
+  'invalid_client',
+]);
+
+export function guardPath(env = process.env) {
+  return join(anyslateDir(env), GUARD_FILE);
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Record<string, any>}
+ */
+export function readGuard(env = process.env) {
+  return readJsonFile(GUARD_FILE, env);
+}
+
+/**
+ * @param {Record<string, any>} next
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean} whether it landed — callers proceed either way
+ */
+export function writeGuard(next, env = process.env) {
+  try {
+    writeJsonFile(GUARD_FILE, next, env);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Identify the (endpoint, credential) pair a breaker state belongs to, without
+ * storing anything a leaked guard file could be used with. Hashed for the same
+ * reason the run log is redacted: this file is written to a shared home
+ * directory and read by `doctor`.
+ *
+ * @param {{apiUrl?: string, authMode?: string, oauth?: object|null, mcpToken?: string|null,
+ *          staticToken?: string|null, sources?: {mcpToken?: string}}} cfg
+ * @returns {string}
+ */
+export function authFingerprint(cfg) {
+  const apiUrl = String(cfg?.apiUrl ?? '');
+  let identity = 'none';
+  if (cfg?.sources?.mcpToken === 'env' && cfg?.mcpToken) {
+    identity = `env:${cfg.mcpToken}`;
+  } else if (cfg?.oauth && (cfg.oauth.access_token || cfg.oauth.refresh_token)) {
+    // client_id, NOT the tokens: rotation replaces those on every refresh, and a
+    // fingerprint that changes hourly is a breaker that never holds.
+    identity = `oauth:${cfg.oauth.client_id ?? ''}:${cfg.oauth.root ?? ''}`;
+  } else if (cfg?.staticToken || cfg?.mcpToken) {
+    identity = `static:${cfg.staticToken ?? cfg.mcpToken}`;
+  }
+  return createHash('sha256').update(`${apiUrl}|${identity}`).digest('hex').slice(0, 16);
+}
+
+/**
+ * Is capture paused right now for this config?
+ *
+ * Pure read — the caller decides whether to speak, then calls `markNotified`.
+ * Splitting it that way keeps "tell the user once" honest across processes: the
+ * flag is only set once something was actually printed.
+ *
+ * @param {{cfg: object, env?: NodeJS.ProcessEnv, now?: number}} opts
+ * @returns {{open: boolean, reason: string|null, detail: string|null, until: string|null,
+ *   pausedForMs: number, noticeDue: boolean}}
+ */
+export function breakerGate({ cfg, env = process.env, now = Date.now() }) {
+  const closed = { open: false, reason: null, detail: null, until: null, pausedForMs: 0, noticeDue: false };
+  const state = readGuard(env);
+  if (!state.open_until) return closed;
+
+  // A different endpoint or credential is a different problem; do not serve a
+  // stale verdict about a setup the user has since changed.
+  if (state.fingerprint && state.fingerprint !== authFingerprint(cfg)) return closed;
+
+  const until = Date.parse(String(state.open_until));
+  if (!Number.isFinite(until) || until <= now) return closed;
+
+  return {
+    open: true,
+    reason: state.reason ?? 'auth',
+    detail: state.detail ?? null,
+    until: new Date(until).toISOString(),
+    pausedForMs: until - now,
+    noticeDue: !state.notified_at,
+  };
+}
+
+/**
+ * The one line a paused client is allowed to say. Names the fix, names when it
+ * will try again, and never repeats itself on the hook path.
+ *
+ * @param {{reason: string|null, detail: string|null, until: string|null}} gate
+ * @returns {string}
+ */
+export function breakerNotice(gate) {
+  const until = gate.until ? ` until ${gate.until}` : '';
+  const detail = gate.detail ? ` (${gate.detail})` : '';
+  if (gate.reason === 'auth') {
+    return (
+      `anyslate: capture paused${until} — repeated authentication failures${detail}. ` +
+      'Run `anyslate login` to sign in again; no requests are sent until then.'
+    );
+  }
+  if (gate.reason === 'throttled') {
+    return `anyslate: capture paused${until} — the server asked this client to back off${detail}.`;
+  }
+  return (
+    `anyslate: capture paused${until} — repeated failures reaching the service${detail}. ` +
+    'Run `anyslate doctor` to check it.'
+  );
+}
+
+/**
+ * Record that a call was rejected, and open the breaker if this is a pattern.
+ *
+ * @param {object} opts
+ * @param {object} opts.cfg
+ * @param {'auth'|'throttled'|'transient'|'fatal'|null} opts.kind
+ * @param {string} [opts.code]        OAuth/refresh error code, when there is one
+ * @param {string} [opts.detail]      short human reason, stored for `doctor`
+ * @param {number|null} [opts.retryAfterMs]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {number} [opts.now]
+ * @returns {{opened: boolean, open: boolean, reason: string|null, until: string|null, detail: string|null}}
+ */
+export function recordCallFailure({ cfg, kind, code, detail, retryAfterMs = null, env = process.env, now = Date.now() }) {
+  const quiet = { opened: false, open: false, reason: null, until: null, detail: null };
+  // A 4xx we caused is not a reason to stop capturing: the request was cheap to
+  // reject and the next one may be well-formed.
+  if (kind !== 'auth' && kind !== 'throttled' && kind !== 'transient') return quiet;
+
+  const fingerprint = authFingerprint(cfg);
+  const previous = readGuard(env);
+  // Counters belong to one (endpoint, credential) pair; a switch resets them.
+  const carried = previous.fingerprint === fingerprint ? previous : {};
+
+  const next = {
+    fingerprint,
+    auth_failures: Number(carried.auth_failures) || 0,
+    transient_failures: Number(carried.transient_failures) || 0,
+    trips: Number(carried.trips) || 0,
+    open_until: carried.open_until ?? null,
+    reason: carried.reason ?? null,
+    detail: carried.detail ?? null,
+    notified_at: carried.notified_at ?? null,
+    window_started_at: carried.window_started_at ?? null,
+    window_calls: Number(carried.window_calls) || 0,
+    updated_at: new Date(now).toISOString(),
+  };
+
+  let pauseMs = 0;
+  if (kind === 'throttled') {
+    // One is enough. `Retry-After` is an instruction, not a hint, and the
+    // machine that ignored it is the one that took the database down.
+    pauseMs = clamp(retryAfterMs ?? TRANSIENT_PAUSE_LADDER_MS[0], MIN_THROTTLE_MS, MAX_THROTTLE_MS);
+    next.reason = 'throttled';
+  } else if (kind === 'auth') {
+    next.auth_failures += 1;
+    const terminal = code ? TERMINAL_AUTH_CODES.has(code) : false;
+    if (terminal || next.auth_failures >= AUTH_FAILURES_BEFORE_OPEN) {
+      pauseMs = ladder(AUTH_PAUSE_LADDER_MS, next.trips);
+      next.reason = 'auth';
+    }
+  } else {
+    next.transient_failures += 1;
+    if (next.transient_failures >= TRANSIENT_FAILURES_BEFORE_OPEN) {
+      pauseMs = ladder(TRANSIENT_PAUSE_LADDER_MS, next.trips);
+      next.reason = 'server';
+    }
+  }
+
+  if (!pauseMs) {
+    writeGuard(next, env);
+    return quiet;
+  }
+
+  next.open_until = new Date(now + pauseMs).toISOString();
+  next.detail = detail ? String(detail).slice(0, 200) : (code ?? null);
+  next.trips += 1;
+  next.auth_failures = 0;
+  next.transient_failures = 0;
+  // Re-arm the "say it once" flag: a NEW pause deserves a fresh notice.
+  next.notified_at = null;
+  writeGuard(next, env);
+
+  return { opened: true, open: true, reason: next.reason, until: next.open_until, detail: next.detail };
+}
+
+/**
+ * A call landed. Everything the breaker knew is stale.
+ *
+ * The rolling-minute window is deliberately preserved — a successful call still
+ * counts against the machine ceiling.
+ *
+ * @param {{cfg: object, env?: NodeJS.ProcessEnv}} opts
+ */
+export function recordCallSuccess({ cfg, env = process.env }) {
+  const previous = readGuard(env);
+  if (!previous.open_until && !previous.auth_failures && !previous.transient_failures && !previous.trips) return;
+  writeGuard(
+    {
+      fingerprint: authFingerprint(cfg),
+      auth_failures: 0,
+      transient_failures: 0,
+      trips: 0,
+      open_until: null,
+      reason: null,
+      detail: null,
+      notified_at: null,
+      window_started_at: previous.window_started_at ?? null,
+      window_calls: Number(previous.window_calls) || 0,
+      updated_at: new Date().toISOString(),
+    },
+    env,
+  );
+}
+
+/**
+ * Mark the pause as explained, so the next hook stays quiet.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {number} [now]
+ */
+export function markNotified(env = process.env, now = Date.now()) {
+  const state = readGuard(env);
+  if (!state.open_until) return;
+  writeGuard({ ...state, notified_at: new Date(now).toISOString() }, env);
+}
+
+/**
+ * Drop the breaker entirely. `login` calls this: the user has just proved they
+ * can authenticate, so making them wait out a pause earned by the credential
+ * they just replaced would be absurd.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function clearBreaker(env = process.env) {
+  try {
+    unlinkSync(guardPath(env));
+  } catch {
+    // Never existed, or the home directory is not ours to write. Either way the
+    // breaker reads as closed, which is the fail-open answer.
+  }
+}
+
+/**
+ * The machine-wide ceiling. Read-modify-write, so two hooks racing in the same
+ * second can undercount — that is the intended direction to be wrong in: this
+ * is a runaway backstop, not an accounting system, and a lost increment lets a
+ * legitimate call through rather than dropping it.
+ *
+ * @param {{env?: NodeJS.ProcessEnv, now?: number, limit?: number}} [opts]
+ * @returns {{allowed: boolean, count: number, limit: number, resetInMs: number}}
+ */
+export function reserveCallSlot({ env = process.env, now = Date.now(), limit } = {}) {
+  const ceiling = limit ?? callsPerMinuteLimit(env);
+  if (!ceiling) return { allowed: true, count: 0, limit: 0, resetInMs: 0 };
+
+  const state = readGuard(env);
+  const startedAt = Date.parse(String(state.window_started_at ?? ''));
+  const fresh = !Number.isFinite(startedAt) || now - startedAt >= 60_000;
+  const windowStart = fresh ? now : startedAt;
+  const count = (fresh ? 0 : Number(state.window_calls) || 0) + 1;
+
+  writeGuard(
+    { ...state, window_started_at: new Date(windowStart).toISOString(), window_calls: count },
+    env,
+  );
+
+  return {
+    allowed: count <= ceiling,
+    count,
+    limit: ceiling,
+    resetInMs: Math.max(0, windowStart + 60_000 - now),
+  };
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number} 0 disables the ceiling
+ */
+export function callsPerMinuteLimit(env = process.env) {
+  const raw = env.ANYSLATE_MAX_CALLS_PER_MINUTE;
+  if (raw === undefined || raw === null || String(raw).trim() === '') return DEFAULT_CALLS_PER_MINUTE;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_CALLS_PER_MINUTE;
+  return Math.floor(n);
+}
+
+/**
+ * @param {{count: number, limit: number, resetInMs: number}} slot
+ * @returns {string}
+ */
+export function ceilingNotice(slot) {
+  return (
+    `anyslate: local rate ceiling reached (${slot.count} calls in the last minute, limit ${slot.limit}) — ` +
+    `skipping this one for ${Math.ceil(slot.resetInMs / 1000)}s. ` +
+    'Raise or disable it with ANYSLATE_MAX_CALLS_PER_MINUTE.'
+  );
+}
+
+function ladder(steps, index) {
+  return steps[Math.min(index, steps.length - 1)];
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}

package/src/index.mjs

@@ -78,6 +78,18 @@ env:
   ANYSLATE_DISABLE=1  kill switch: hook / checkpoint / upload-artifact make no
                       network call and exit 0. \`doctor\` and \`login\` still run
                       so you can diagnose and set up while capture is off.
+  ANYSLATE_HOOK_TIMEOUT_MS
+                      total request budget for one \`hook\` submission
+                      (default 5000). Hooks never retry.
+  ANYSLATE_MAX_CALLS_PER_MINUTE
+                      machine-wide ceiling on capture calls (default 60;
+                      0 disables). A backstop against a runaway loop.
+
+capture pauses:
+  After repeated authentication failures — or when the server answers 429/503
+  with a Retry-After — the CLI stops calling entirely and records the pause in
+  ~/.anyslate/cli-guard.json. It says so once, then stays silent. \`anyslate
+  login\` clears an auth pause immediately; \`anyslate doctor\` always reports one.
 `;
 
 /**

package/src/mcp-client.mjs

@@ -99,9 +99,20 @@ export function formatErrorPayload(raw) {
 }
 
 /**
- * Extract 429 metadata. `Retry-After` was never read and
+ * Statuses that carry a server-named wait.
+ *
+ * 503 joined 429 after 2026-08-02: when the database was overloaded the
+ * handlers returned bare 500s, every client read that as "try again now", and
+ * the retries deepened the outage. The service now answers 503 + `Retry-After`
+ * on that path, so the client has to read it there too — an unread Retry-After
+ * is the same as no Retry-After.
+ */
+const THROTTLE_STATUSES = new Set([429, 503]);
+
+/**
+ * Extract throttle metadata. `Retry-After` was never read and
  * `retry_after_seconds`/`reset_at`/`reason` survived only in `raw`
- * (defect #31). Surfacing only — no retry/backoff logic.
+ * (defect #31). Surfacing only — backoff.mjs/guard.mjs decide what to do with it.
  *
  * @param {Response} res
  * @param {unknown} raw
@@ -294,7 +305,7 @@ export async function callTool({
         const formatted = formatErrorPayload(init.raw);
         const errLike = formatted ?? { message: `initialize failed (HTTP ${init.status})` };
         const out = { ok: false, status: init.status, data: errLike, raw: init.raw };
-        if (init.status === 429) {
+        if (THROTTLE_STATUSES.has(init.status)) {
           const rl = extractRateLimit(init.res, init.raw);
           out.rateLimit = rl;
           out.retryAfterSeconds = rl.retry_after_seconds;
@@ -322,7 +333,7 @@ export async function callTool({
 
     const status = res.status;
     const raw = await readBody(res);
-    const rateLimit = status === 429 ? extractRateLimit(res, raw) : null;
+    const rateLimit = THROTTLE_STATUSES.has(status) ? extractRateLimit(res, raw) : null;
 
     const finish = (out) => {
       if (rateLimit) {
@@ -356,7 +367,7 @@ export async function callTool({
         const embeddedStatus = Number.isFinite(parsed.status) ? Number(parsed.status) : status;
         const data = formatErrorPayload(parsed) ?? parsed.error ?? text ?? 'tool returned isError';
         const out = { ok: false, status: embeddedStatus, data, raw, isError: true };
-        if (embeddedStatus === 429) {
+        if (THROTTLE_STATUSES.has(embeddedStatus)) {
           const rl = extractRateLimit(res, parsed);
           out.rateLimit = rl;
           out.retryAfterSeconds = rl.retry_after_seconds;