getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/providers/failures.ts

@@ -0,0 +1,143 @@
+// Patterns from the CLIs' own messages (claude 2.1.316, codex-cli 0.166.0). Transient ones are narrow on
+// purpose: a permanent error taken for a network blip runs the work again.
+import { isValidTimezone } from '../../../shared/util.ts';
+import { zonedToUtc } from '../schedule.ts';
+
+export type FailureKind = 'usage_limit' | 'auth' | 'transient' | 'other';
+
+/** When a usage limit gives no reset time. */
+export const DEFAULT_COOLDOWN_MS = 30 * 60_000;
+/** A reset in the past (a skewed clock) would otherwise re-run the turn at once, over and over. */
+export const MIN_COOLDOWN_MS = 60_000;
+
+const USAGE_LIMIT = [
+  /usage limit reached/i,
+  /\bhit your (?:[\w'’-]+ ){0,3}limit\b/i,
+  /\breached your (?:[\w'’-]+ ){0,2}limit\b/i,
+  /\bspend limit reached\b/i,
+  /\bout of usage credits\b/i,
+];
+
+const AUTH = [
+  /\bnot logged in\b/i,
+  /please run \/login/i,
+  /\binvalid api key\b/i,
+  /\boauth token (?:has )?(?:expired|revoked)\b/i,
+  /\bauthentication_error\b/i,
+  /\bauthentication failed\b/i,
+  /\b401\b[^\n]*unauthori[sz]ed/i,
+  /\bcodex login\b/i,
+  /\bno codex credentials\b/i,
+  /\bsign in again\b/i,
+  /\baccess token could not be refreshed\b/i,
+  /\brefresh token was rejected\b/i,
+];
+
+/** Not overloaded or 429 errors: both CLIs retry those themselves. */
+const TRANSIENT = [
+  /\bconnection error\b/i,
+  /\brequest timed out\b/i,
+  /\bfetch failed\b/i,
+  /\b(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH|EPIPE)\b/,
+  /\bsocket hang up\b/i,
+  /\bstream disconnected before completion\b/i,
+  /\berror sending request\b/i,
+  /\bconnection (?:failed|reset|refused)\b/i,
+  // Codex's reconnects used up on a network failure, not an HTTP status.
+  /^Reconnecting\.\.\. \d+\/\d+ \((?!unexpected status)/m,
+];
+
+/** `transientText` is only the failure itself: stderr often carries harmless network noise. */
+export function classifyFailure(said: string, transientText: string, opts: { now?: Date; localTz?: string } = {}): { kind: FailureKind; retryAt: Date | null } {
+  const now = opts.now ?? new Date();
+  if (USAGE_LIMIT.some((re) => re.test(said))) {
+    const localTz = opts.localTz ?? (Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC');
+    const reset = parseReset(said, now, localTz)?.getTime() ?? now.getTime() + DEFAULT_COOLDOWN_MS;
+    return { kind: 'usage_limit', retryAt: new Date(Math.max(reset, now.getTime() + MIN_COOLDOWN_MS)) };
+  }
+  if (AUTH.some((re) => re.test(said))) return { kind: 'auth', retryAt: null };
+  if (TRANSIENT.some((re) => re.test(transientText))) return { kind: 'transient', retryAt: null };
+  return { kind: 'other', retryAt: null };
+}
+
+/** Weekly limits reset within 7 days: anything later is a misread. */
+const MAX_AHEAD_MS = 8 * 86_400_000;
+const CLOCK_SLACK_MS = 60_000;
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+
+/** Times without a zone are in `localTz` (the CLIs print local time). */
+export function parseReset(text: string, now: Date, localTz: string): Date | null {
+  const ok = (d: Date | null) => (d && d.getTime() > now.getTime() - 5 * 60_000 && d.getTime() - now.getTime() <= MAX_AHEAD_MS ? d : null);
+  // "Claude AI usage limit reached|1762400000" (seconds since the epoch).
+  const epoch = /limit reached\|(\d{10,13})\b/i.exec(text);
+  if (epoch) {
+    const n = Number(epoch[1]);
+    const d = ok(new Date(n < 1e12 ? n * 1000 : n));
+    if (d) return d;
+  }
+  // "resets in 2h 30m", "try again in 4 days 3 hours".
+  const inDur = /\b(?:resets|try again) in ([^.\n·]+)/i.exec(text);
+  if (inDur) {
+    const ms = parseDurationWords(inDur[1]);
+    if (ms !== null) return ok(new Date(now.getTime() + ms));
+  }
+  // "resets 3pm (Europe/Berlin)", "resets Nov 7, 9am (…)", "resets 2026-08-08 00:00 UTC", "try again at Nov 5th, 2026 3:05 PM."
+  const at = /\b(?:resets|try again)(?: at| on)? ([^\n·]+)/i.exec(text);
+  if (at) {
+    const when = at[1].split(/\. |\.$| — | - /)[0];
+    const d = parseWhen(when, now, localTz);
+    if (d) return ok(d.getTime() <= now.getTime() ? new Date(now.getTime() + CLOCK_SLACK_MS) : d);
+  }
+  return null;
+}
+
+function parseDurationWords(s: string): number | null {
+  const units: Record<string, number> = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1000 };
+  let total = 0;
+  let found = false;
+  for (const m of s.matchAll(/(\d+(?:\.\d+)?)\s*(days?|d|hours?|hrs?|h|minutes?|mins?|m|seconds?|secs?|s)\b/gi)) {
+    found = true;
+    total += Number(m[1]) * units[m[2][0].toLowerCase()];
+  }
+  return found ? Math.round(total) : null;
+}
+
+function parseWhen(s: string, now: Date, localTz: string): Date | null {
+  const zone = /\(([A-Za-z]+(?:\/[A-Za-z0-9_+-]+)+)\)/.exec(s)?.[1] ?? (/\b(?:UTC|GMT)\b/.test(s) ? 'UTC' : localTz);
+  const tz = isValidTimezone(zone) ? zone : localTz;
+  const iso = /(\d{4})-(\d{2})-(\d{2})[ T](\d{1,2}):(\d{2})/.exec(s);
+  if (iso) return zonedToUtc(+iso[1], +iso[2], +iso[3], +iso[4], +iso[5], tz);
+
+  const time = /(?:^|[\s,])(\d{1,2})(?::(\d{2}))?\s*([ap])\.?m\.?(?![a-z])|(?:^|[\s,])(\d{1,2}):(\d{2})(?![\d:])/i.exec(s);
+  if (!time) return null;
+  let h = Number(time[1] ?? time[4]);
+  const min = Number(time[2] ?? time[5] ?? 0);
+  const ap = time[3]?.toLowerCase();
+  if (ap === 'p' && h < 12) h += 12;
+  if (ap === 'a' && h === 12) h = 0;
+  if (h > 23 || min > 59) return null;
+
+  const today = ymdIn(now, tz);
+  const md = /\b([A-Za-z]{3})[a-z]*\.? (\d{1,2})(?:st|nd|rd|th)?\b(?:,? (\d{4}))?/.exec(s);
+  const month = md ? MONTHS.indexOf(md[1].toLowerCase()) : -1;
+  if (md && month >= 0) {
+    let year = md[3] ? Number(md[3]) : today.y;
+    let d = zonedToUtc(year, month + 1, Number(md[2]), h, min, tz);
+    // "Jan 2" seen on Dec 30 means next year.
+    if (!md[3] && d.getTime() < now.getTime() - 86_400_000) d = zonedToUtc(++year, month + 1, Number(md[2]), h, min, tz);
+    return new Date(d.getTime() + CLOCK_SLACK_MS);
+  }
+  // A time of day only: today, or tomorrow if that has passed (a minute ago still counts as now).
+  let d = zonedToUtc(today.y, today.m, today.d, h, min, tz);
+  if (d.getTime() < now.getTime() - 5 * 60_000) {
+    const t = ymdIn(new Date(now.getTime() + 86_400_000), tz);
+    d = zonedToUtc(t.y, t.m, t.d, h, min, tz);
+  }
+  return new Date(d.getTime() + CLOCK_SLACK_MS);
+}
+
+function ymdIn(at: Date, tz: string): { y: number; m: number; d: number } {
+  const parts = new Intl.DateTimeFormat('en-US', { timeZone: tz, year: 'numeric', month: 'numeric', day: 'numeric' }).formatToParts(at);
+  const get = (t: string) => Number(parts.find((p) => p.type === t)?.value);
+  return { y: get('year'), m: get('month'), d: get('day') };
+}

package/payload/server/src/providers/index.ts

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { type ModelEfforts, providerEffort } from '../../../shared/effort.ts';
+import type { ProviderEffortInfo, ProviderInfo } from '../../../shared/types.ts';
+import { nowIso, truncate } from '../util.ts';
+import { ClaudeCliProvider } from './claude-cli.ts';
+import { CodexCliProvider } from './codex-cli.ts';
+import { MockProvider } from './mock.ts';
+import { brainReadiness } from './readiness.ts';
+import type { Provider } from './types.ts';
+
+/** Rechecks the owner can ask for, per provider, in OWNER_RECHECK_WINDOW_MS; past that they get the last check. */
+export const OWNER_RECHECKS = 6;
+export const OWNER_RECHECK_WINDOW_MS = 60_000;
+
+export class ProviderRegistry {
+  #providers = new Map<string, Provider>();
+  /** Replacing a CLI replaces its checker, so its counters need a fresh identity. */
+  #incarnations = new Map<string, string>();
+  /** How each provider's real turns went, since the server started. */
+  #turns = new Map<string, Pick<ProviderInfo, 'lastSuccessAt' | 'lastError'>>();
+  /** When the owner's rechecks of each provider started, within the window. */
+  #rechecks = new Map<string, number[]>();
+  /** Until when each provider's turns are held by a usage limit (the engine's). */
+  #usageLimitUntil: (id: string) => string | null = () => null;
+  /** This run of the server, for its answers' readiness: checks are counted per run, and runs aren't ordered by clock. */
+  readonly boot = randomUUID();
+
+  /** `managed`: which CLIs are Botons' own copies (managed-clis.ts). */
+  constructor(opts: { enableMock: boolean; claudeBin?: string; codexBin?: string; managed?: { claude?: boolean; codex?: boolean } }) {
+    this.register(new ClaudeCliProvider(opts.claudeBin ?? process.env.BOTONS_CLAUDE_BIN ?? 'claude', opts.managed?.claude));
+    this.register(new CodexCliProvider(opts.codexBin ?? process.env.BOTONS_CODEX_BIN ?? 'codex', undefined, opts.managed?.codex));
+    if (opts.enableMock) this.register(new MockProvider());
+  }
+
+  register(p: Provider) {
+    if (this.#providers.has(p.id)) { this.#incarnations.set(p.id, randomUUID()); this.#rechecks.delete(p.id); }
+    this.#providers.set(p.id, p);
+  }
+
+  get(id: string): Provider | undefined {
+    return this.#providers.get(id);
+  }
+
+  ids(): Set<string> {
+    return new Set(this.#providers.keys());
+  }
+
+  /** What `provider`'s own model list says `model` takes, or null when nothing is known about it. */
+  modelEfforts(provider: string, model: string): ModelEfforts | null {
+    return this.#providers.get(provider)?.modelEfforts?.(model.trim()) ?? null;
+  }
+
+  /** Where the usage limits come from, so each provider's readiness shows its own. */
+  setUsageLimits(until: (id: string) => string | null): void {
+    this.#usageLimitUntil = until;
+  }
+
+  async infos(opts: { recheck?: boolean } = {}): Promise<ProviderInfo[]> {
+    const providers = [...this.#providers.values()];
+    if (opts.recheck) for (const p of providers) p.recheck?.();
+    return Promise.all(
+      providers.map(async (p) => {
+        const boot = this.#incarnations.get(p.id) ?? this.boot;
+        const turns = this.#turns.get(p.id);
+        const { check, ...info } = await p.info();
+        const readiness = brainReadiness({ ...info, check }, this.#usageLimitUntil(p.id), Date.now(), boot);
+        return { ...info, effort: info.effort ?? effortInfo(p.id, p.label), lastSuccessAt: turns?.lastSuccessAt ?? null, lastError: turns?.lastError ?? null, readiness };
+      }),
+    );
+  }
+
+  /**
+   * The providers as infos() would show them, from the checks already done: runs no check, whatever their age. A
+   * provider never checked is 'unknown' ('not-checked'), one checked too long ago 'unknown' ('outdated').
+   */
+  snapshots(now = Date.now()): ProviderInfo[] {
+    return [...this.#providers.values()].map((p) => {
+      const turns = this.#turns.get(p.id);
+      const status = p.snapshot ? p.snapshot() : { id: p.id, label: p.label, kind: 'cli' as const, available: false, reason: 'Not checked yet since the server started.', installed: false, version: null, loggedIn: null, checkedAt: null, models: [], defaultModel: '' };
+      const { check, ...info } = status;
+      const readiness = brainReadiness({ ...info, check }, this.#usageLimitUntil(p.id), now, this.#incarnations.get(p.id) ?? this.boot);
+      return { ...info, effort: info.effort ?? effortInfo(p.id, p.label), lastSuccessAt: turns?.lastSuccessAt ?? null, lastError: turns?.lastError ?? null, readiness };
+    });
+  }
+
+  /**
+   * The owner's "check again": each provider's checks run anew, unless it was asked OWNER_RECHECKS times in the last
+   * OWNER_RECHECK_WINDOW_MS, so a held-down button can't keep the CLIs busy. A check already running is waited for and
+   * a new one runs after it (CliChecker): never two at once. Returns the providers whose checks run anew.
+   */
+  ownerRecheck(now = Date.now()): string[] {
+    const rechecked: string[] = [];
+    for (const p of this.#providers.values()) {
+      if (!p.recheck) continue;
+      const recent = (this.#rechecks.get(p.id) ?? []).filter((t) => now - t < OWNER_RECHECK_WINDOW_MS);
+      if (recent.length < OWNER_RECHECKS) {
+        recent.push(now);
+        p.recheck();
+        rechecked.push(p.id);
+      }
+      this.#rechecks.set(p.id, recent);
+    }
+    return rechecked;
+  }
+
+  /** After a failure the checks run again at once (in the background), so a signed-out CLI gets logged. */
+  recordTurn(id: string, outcome: { ok: true } | { ok: false; error: string }): void {
+    const rec = this.#turns.get(id) ?? { lastSuccessAt: null, lastError: null };
+    const at = nowIso();
+    if (outcome.ok) rec.lastSuccessAt = at;
+    else rec.lastError = { at, message: truncate(outcome.error, 500) };
+    this.#turns.set(id, rec);
+    const p = this.#providers.get(id);
+    if (!outcome.ok && p?.recheck) {
+      p.recheck();
+      p.info().catch(() => {});
+    }
+  }
+
+  async defaultProvider(): Promise<string> {
+    const infos = await this.infos();
+    return (infos.find((i) => i.available && i.id !== 'mock') ?? infos[0]).id;
+  }
+}
+
+/** What the owner's effort control offers for a provider: its levels, or why it has none. */
+export function effortInfo(id: string, label: string): ProviderEffortInfo {
+  const p = providerEffort(id);
+  if (!p) return { levels: [], reason: `${label} has no effort setting Botons can pass on, so it runs at its own default.`, via: null, defaultText: 'the provider’s default' };
+  return { levels: p.levels.map((l) => ({ id: l.id, label: l.label })), reason: null, via: p.via, defaultText: p.defaultText };
+}

package/payload/server/src/providers/mcp-stdio.ts

@@ -0,0 +1,147 @@
+import { VERSION } from '../../../shared/app-version.mjs';
+import { type ChildProcess, spawn } from 'node:child_process';
+import { cleanResult, cleanTools, type McpTool, type ToolResult } from '../mcp-client.ts';
+import { redact } from '../secrets.ts';
+
+/*
+ * Just enough of an MCP client over stdio (newline-delimited JSON-RPC) for an API brain's library and browser
+ * connectors: initialize, list tools, call one. The server runs as the CLIs run their MCP servers: as the server's user,
+ * in its own process group, with only the environment it is given; it is killed when the turn ends. A library
+ * connector comes here already wrapped in the Workspace sandbox (connector-launch.ts).
+ */
+
+const PROTOCOL = '2025-06-18';
+const MAX_LINE = 4 * 1024 * 1024;
+const MAX_TOOL_PAGES = 20;
+
+export class StdioMcp {
+  #child: ChildProcess;
+  #id = 0;
+  #pending = new Map<number, { resolve: (v: Record<string, unknown>) => void; reject: (e: Error) => void; timer: NodeJS.Timeout }>();
+  #buf = '';
+  #closed: Error | null = null;
+  #stderr = '';
+  #secrets: string[];
+
+  constructor(server: { command: string; args: string[]; env: Record<string, string>; cwd: string; secrets?: string[] }, baseEnv: NodeJS.ProcessEnv) {
+    // The connector's own secrets: the values of the environment it was saved with.
+    this.#secrets = [...(server.secrets ?? []), ...Object.values(server.env)].filter((v) => v.length >= 8);
+    this.#child = spawn(server.command, server.args, { cwd: server.cwd, env: { ...baseEnv, ...server.env }, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+    this.#child.stdout!.setEncoding('utf8');
+    this.#child.stdout!.on('data', (chunk: string) => this.#read(chunk));
+    this.#child.stderr!.setEncoding('utf8');
+    // Redacted as it comes, and only then cut from the front: a secret split across chunks is whole again before
+    // the cut, and the cut only ever drops text that was already redacted.
+    const keep = Math.max(2000, 2 * Math.max(0, ...this.#secrets.map((v) => v.length)));
+    this.#child.stderr!.on('data', (chunk: string) => {
+      this.#stderr = redact(this.#stderr + chunk, this.#secrets).slice(-keep);
+    });
+    this.#child.stdin!.on('error', () => {});
+    this.#child.on('error', (err) => this.#fail(new Error(`could not start: ${(err as NodeJS.ErrnoException).code ?? err.message}`)));
+    this.#child.on('close', (code) => this.#fail(new Error(`it exited (${code ?? 'killed'})${this.#tail()}`)));
+  }
+
+  /** The connector's own secrets (see the constructor). */
+  get secrets(): string[] {
+    return [...this.#secrets];
+  }
+
+  #tail(): string {
+    const t = redact(this.#stderr, this.#secrets).trim().split('\n').pop()?.slice(0, 200) ?? '';
+    return t ? `: ${t}` : '';
+  }
+
+  #fail(err: Error) {
+    this.#closed ??= err;
+    for (const [, p] of this.#pending) {
+      clearTimeout(p.timer);
+      p.reject(this.#closed);
+    }
+    this.#pending.clear();
+  }
+
+  #read(chunk: string) {
+    this.#buf += chunk;
+    if (this.#buf.length > MAX_LINE && !this.#buf.includes('\n')) {
+      this.#fail(new Error('it sent a message larger than Botons reads'));
+      this.close();
+      return;
+    }
+    let nl: number;
+    while ((nl = this.#buf.indexOf('\n')) >= 0) {
+      const line = this.#buf.slice(0, nl).trim();
+      this.#buf = this.#buf.slice(nl + 1);
+      if (!line) continue;
+      let msg: Record<string, unknown>;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const id = typeof msg.id === 'number' ? msg.id : null;
+      const p = id === null ? undefined : this.#pending.get(id);
+      if (!p) continue;
+      this.#pending.delete(id!);
+      clearTimeout(p.timer);
+      if (msg.error) {
+        const e = msg.error as { message?: unknown };
+        p.reject(new Error(typeof e?.message === 'string' ? redact(e.message, this.#secrets).slice(0, 200) : 'error'));
+      } else p.resolve(msg.result && typeof msg.result === 'object' && !Array.isArray(msg.result) ? (msg.result as Record<string, unknown>) : {});
+    }
+  }
+
+  #send(msg: Record<string, unknown>) {
+    this.#child.stdin!.write(`${JSON.stringify(msg)}\n`);
+  }
+
+  request(method: string, params: Record<string, unknown>, timeoutMs: number): Promise<Record<string, unknown>> {
+    if (this.#closed) return Promise.reject(this.#closed);
+    const id = ++this.#id;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new Error(`no answer to ${method} within ${Math.round(timeoutMs / 1000)} s`));
+      }, timeoutMs);
+      this.#pending.set(id, { resolve, reject, timer });
+      this.#send({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  async initialize(timeoutMs: number): Promise<void> {
+    await this.request('initialize', { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: 'Botons', version: VERSION } }, timeoutMs);
+    this.#send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+  }
+
+  async listTools(timeoutMs: number): Promise<McpTool[]> {
+    const tools: McpTool[] = [];
+    let cursor: unknown;
+    for (let page = 0; page < MAX_TOOL_PAGES; page++) {
+      const r = await this.request('tools/list', cursor === undefined ? {} : { cursor }, timeoutMs);
+      for (const t of Array.isArray(r.tools) ? r.tools : []) {
+        if (t && typeof t.name === 'string')
+          tools.push({ name: t.name, inputSchema: t.inputSchema && typeof t.inputSchema === 'object' ? t.inputSchema : null, description: typeof t.description === 'string' ? t.description : null });
+      }
+      if (typeof r.nextCursor !== 'string' || !r.nextCursor) break;
+      cursor = r.nextCursor;
+    }
+    return cleanTools(tools, this.#secrets);
+  }
+
+  /** `also`: more to take out of the result before it is cut (see cleanResult). */
+  async callTool(name: string, args: Record<string, unknown>, timeoutMs: number, also?: (text: string) => string): Promise<ToolResult> {
+    return cleanResult(await this.request('tools/call', { name, arguments: args }, timeoutMs), this.#secrets, also);
+  }
+
+  close(): void {
+    this.#fail(new Error('closed'));
+    try {
+      if (this.#child.pid) process.kill(-this.#child.pid, 'SIGTERM');
+    } catch {}
+    const pid = this.#child.pid;
+    setTimeout(() => {
+      try {
+        if (pid) process.kill(-pid, 'SIGKILL');
+      } catch {}
+    }, 2000).unref();
+  }
+}

package/payload/server/src/providers/mock.ts

@@ -0,0 +1,94 @@
+import { setTimeout as wait } from 'node:timers/promises';
+import { type Provider, ProviderError, type ProviderStatus, step, type TurnRequest, type TurnResult } from './types.ts';
+
+/**
+ * For tests (BOTONS_ENABLE_MOCK=1): replies "Echo: <input>". Triggers in the input: FAIL_PLEASE, SLOW_PLEASE[:ms],
+ * QUIET_PLEASE[:note], STEP_PLEASE:[<n>x]<command>, STREAM_PLEASE[:ms].
+ */
+export class MockProvider implements Provider {
+  id = 'mock';
+  label = 'Mock (tests)';
+  askFirst = true;
+  turns: TurnRequest[] = [];
+  /** A string is the turn's reply; null leaves the turn to the triggers. */
+  script: ((req: TurnRequest) => Promise<string | null> | string | null) | null = null;
+  #failures = new Map<string, Error[]>();
+
+  /** The Boton's next turns throw these errors, one per turn. */
+  failNext(botId: string, ...errors: Error[]): void {
+    this.#failures.set(botId, [...(this.#failures.get(botId) ?? []), ...errors]);
+  }
+
+  async info(): Promise<ProviderStatus> {
+    return this.snapshot();
+  }
+
+  snapshot(): ProviderStatus {
+    return {
+      id: this.id,
+      label: this.label,
+      kind: 'api',
+      available: true,
+      reason: null,
+      installed: true,
+      version: null,
+      loggedIn: true,
+      checkedAt: new Date().toISOString(),
+      models: [{ id: '', label: 'Echo' }],
+      defaultModel: '',
+      askFirst: true,
+    };
+  }
+
+  async runTurn(req: TurnRequest): Promise<TurnResult> {
+    this.turns.push(req);
+    const fail = this.#failures.get(req.env.BOTON_BOT_ID ?? '')?.shift();
+    if (fail) throw fail;
+    req.onActivity('Thinking');
+    const started = Date.now();
+    const scripted = this.script ? await this.script(req) : null;
+    if (scripted !== null) return { sessionId: req.sessionId ?? `mock-${this.turns.length}`, text: scripted };
+    // Only this turn's input, not the context block or a replayed transcript.
+    const body = req.prompt.split('</boton_context>').pop()!.trim();
+    for (const m of body.matchAll(/STEP_PLEASE:(?:(\d+)x)?([^\n]+)/g)) {
+      const command = m[2].trim();
+      for (let i = 0; i < Number(m[1] ?? 1); i++) {
+        req.onActivity(`Running \`${command}\``);
+        req.onStep?.(step('command', `Running \`${command.slice(0, 70)}\``, command));
+      }
+    }
+    const slow = /SLOW_PLEASE(?::(\d+))?/.exec(body);
+    await work(slow ? Number(slow[1] ?? 30_000) : 50, req, started);
+    if (req.prompt.includes('FAIL_PLEASE')) throw new Error('Mock failure requested');
+    const quiet = /QUIET_PLEASE(?::([^\n]*))?/.exec(body);
+    const text = quiet ? `[quiet]${quiet[1] ? ` ${quiet[1].trim()}` : ''}` : `Echo: ${body.slice(0, 500)}`;
+    const stream = /STREAM_PLEASE(?::(\d+))?/.exec(body);
+    if (stream) {
+      const words = text.split(/(?<=\s)/);
+      for (let i = 1; i <= words.length; i++) {
+        req.onText?.(words.slice(0, i).join(''));
+        await work(Number(stream[1] ?? 40), req, started);
+      }
+    }
+    const usage = { inputTokens: Math.ceil(req.prompt.length / 4), outputTokens: Math.ceil(text.length / 4), cacheReadTokens: 0, cacheWriteTokens: 0, model: req.model || 'mock-echo' };
+    return { sessionId: req.sessionId ?? `mock-${this.turns.length}`, text, usage };
+  }
+}
+
+/**
+ * Waits `ms` as a CLI turn would run, ending it as runJsonl does: stopped by `req.signal`, or timed out at
+ * `req.timeoutMs` from `started`, whichever comes first.
+ */
+async function work(ms: number, req: TurnRequest, started: number): Promise<void> {
+  const left = started + req.timeoutMs - Date.now();
+  await sleep(Math.min(ms, Math.max(0, left)), req.signal);
+  if (req.signal.aborted) throw new Error('Stopped.');
+  if (ms >= left) {
+    const err = new ProviderError('Mock timed out.', false);
+    err.exit = { exitCode: null, signal: 'SIGTERM', timedOut: true, stderrTail: '' };
+    throw err;
+  }
+}
+
+/** Wait `ms`, or less if `signal` aborts first. */
+const sleep = (ms: number, signal: AbortSignal) => wait(ms, undefined, { signal }).catch(() => {});