getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/callback.ts

@@ -0,0 +1,218 @@
+import { createHmac } from 'node:crypto';
+import { earlierName } from '../../shared/legacy-names.mjs';
+import { request as httpRequest, type IncomingMessage } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import type { CallbackDelivery, RoutineRun, RunCallback } from '../../shared/types.ts';
+import type { CallbacksConfig } from './config.ts';
+import type { EventHub } from './events.ts';
+import { log } from './log.ts';
+import { allowance, guardedLookup, refusedUrl } from './ssrf.ts';
+import { HttpError, PENDING_CALLBACK_LIMIT, type Store } from './store.ts';
+import { nowIso } from './util.ts';
+
+type Attempt = { ok: boolean; status: number | null; error: string | null; retry: boolean };
+
+/**
+ * POSTs each finished run's result to its routine's callbackUrl, signed with the webhook key.
+ *
+ * The store records a run's callback as pending in the same transaction that finishes the run, so what a stop or a
+ * crash cuts off is still pending at the next start, and resumePending sends it again. This only sends: a run.upserted
+ * carrying a pending callback starts a send, and the outcome replaces pending after the last attempt. Delivery is
+ * at-least-once, so a receiver may get a result twice: X-Boton-Run tells them apart.
+ */
+export class Callbacks {
+  #cfg: CallbacksConfig;
+  #store: Store;
+  /** Runs whose callback is being sent, so a run.upserted meanwhile doesn't send it again. */
+  #sending = new Set<string>();
+  #stopped = false;
+  #inflight = new Set<AbortController>();
+  #waits = new Map<NodeJS.Timeout, () => void>();
+  #unsubscribe: () => void;
+
+  constructor(cfg: CallbacksConfig, store: Store, hub: EventHub) {
+    this.#cfg = cfg;
+    this.#store = store;
+    this.#unsubscribe = hub.subscribe((ev) => {
+      if (ev.type === 'run.upserted' && ev.run.meta?.callback?.pending) this.#take(ev.run);
+    });
+  }
+
+  /** On shutdown, before the database closes. */
+  stop(): void {
+    this.#stopped = true;
+    this.#unsubscribe();
+    for (const [t, wake] of this.#waits) {
+      clearTimeout(t);
+      wake();
+    }
+    this.#waits.clear();
+    for (const c of this.#inflight) c.abort();
+  }
+
+  /** At start: send the callbacks the last stop or crash cut off, to the routine's callback URL now. */
+  resumePending(): number {
+    const runs = this.#store.pendingCallbackRuns();
+    for (const run of runs) {
+      if (this.#sending.has(run.id)) continue;
+      log.info('callback resumed after a restart', { runId: run.id, routineId: run.routineId });
+      this.#take(run);
+    }
+    return runs.length;
+  }
+
+  /** A run whose callback the store has recorded as pending. */
+  #take(run: RoutineRun) {
+    // A test run is a dry run: its result is not for the receiver, which may act on it.
+    if (this.#stopped || run.trigger === 'test' || this.#sending.has(run.id)) return;
+    // Read now: a run failed because its routine is being deleted still has its routine at this point.
+    const target = this.#store.callbackTarget(run.routineId);
+    if (!target) {
+      this.#record(run, { url: run.meta!.callback!.url, ok: false, status: null, error: 'Not sent: the routine no longer has a callback URL', attempts: 0, at: nowIso() });
+      return;
+    }
+    this.#send(run, target);
+  }
+
+  /** The owner sends a run's result again after its callback failed. */
+  resend(runId: string): RoutineRun {
+    if (this.#stopped) throw new HttpError(503, 'The server is stopping');
+    const run = this.#store.getRun(runId);
+    const last = run.meta?.callback;
+    if (run.trigger === 'test') throw new HttpError(409, 'A test run sends no callback');
+    if (!last) throw new HttpError(409, 'This run sent no callback');
+    if (last.pending || this.#sending.has(run.id)) throw new HttpError(409, 'This run\'s result is being sent now');
+    if (last.ok) throw new HttpError(409, 'This run\'s result was already sent');
+    const target = this.#store.callbackTarget(run.routineId);
+    if (!target) throw new HttpError(409, 'The routine no longer has a callback URL');
+    if (this.#store.pendingCallbackCount(run.routineId) >= PENDING_CALLBACK_LIMIT) {
+      throw new HttpError(409, `${PENDING_CALLBACK_LIMIT} results are already waiting for this callback URL; send it again once they are done`);
+    }
+    // Claimed in memory first, so the run.upserted this write publishes doesn't start a second send.
+    this.#sending.add(run.id);
+    let marked: RoutineRun | null;
+    try {
+      // Recorded before the first POST: what is still pending at the next start was cut off.
+      marked = this.#store.setRunCallback(run.id, { url: target.url, ok: false, status: null, error: null, attempts: 0, at: nowIso(), pending: true });
+    } catch (err) {
+      this.#sending.delete(run.id);
+      throw err;
+    }
+    if (!marked) {
+      this.#sending.delete(run.id);
+      throw new HttpError(404, `No run with id ${run.id}`);
+    }
+    void this.#deliver(marked, target).finally(() => this.#sending.delete(run.id));
+    return marked;
+  }
+
+  #send(run: RoutineRun, target: { url: string; key: string }) {
+    this.#sending.add(run.id);
+    void this.#deliver(run, target).finally(() => this.#sending.delete(run.id));
+  }
+
+  #record(run: RoutineRun, delivery: CallbackDelivery): RoutineRun | null {
+    try {
+      return this.#store.setRunCallback(run.id, delivery);
+    } catch (err) {
+      log.warn('could not record a callback for a run', { runId: run.id, err });
+      return null;
+    }
+  }
+
+  async #deliver(run: RoutineRun, target: { url: string; key: string }) {
+    const body = JSON.stringify({
+      runId: run.id,
+      routineId: run.routineId,
+      botId: run.botId,
+      trigger: run.trigger,
+      status: run.status,
+      quiet: run.quiet,
+      reply: run.reply,
+      error: run.error,
+      startedAt: run.startedAt,
+      finishedAt: run.finishedAt,
+      attempts: run.attempts,
+      cancelled: !!run.meta?.cancelled,
+      timedOut: !!run.meta?.timedOut,
+    } satisfies RunCallback);
+    const headers = {
+      'content-type': 'application/json',
+      'user-agent': 'Botons-Callback/1',
+      'x-boton-signature': `sha256=${createHmac('sha256', target.key).update(body).digest('hex')}`,
+      'x-boton-run': run.id,
+    };
+    // And under their deprecated names, for one release, so receivers set up for them keep working (shared/legacy-names.mjs).
+    for (const k of ['x-boton-signature', 'x-boton-run'] as const) (headers as Record<string, string>)[earlierName(k)!] = headers[k];
+    let attempts = 0;
+    let last: Attempt;
+    for (;;) {
+      attempts++;
+      last = await this.#attempt(target.url, headers, body);
+      // Stopping, a callback not yet sent stays pending, for the next start.
+      if (this.#stopped && !last.ok) return;
+      if (last.ok || !last.retry || attempts > this.#cfg.retryDelaysMs.length) break;
+      await this.#sleep(this.#cfg.retryDelaysMs[attempts - 1]);
+      if (this.#stopped) return;
+    }
+    const fields = { runId: run.id, routineId: run.routineId, attempts, status: last.status ?? undefined };
+    if (last.ok) log.info('callback sent', fields);
+    else log.warn('callback failed', { ...fields, error: last.error });
+    this.#record(run, { url: target.url, ok: last.ok, status: last.status, error: last.error, attempts, at: nowIso() });
+  }
+
+  #sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      const t = setTimeout(() => {
+        this.#waits.delete(t);
+        resolve();
+      }, ms);
+      t.unref();
+      this.#waits.set(t, resolve);
+    });
+  }
+
+  /** One POST. Never throws. */
+  #attempt(url: string, headers: Record<string, string>, body: string): Promise<Attempt> {
+    const allow = allowance(this.#cfg.allow);
+    const refused = refusedUrl(url, allow);
+    if (refused) return Promise.resolve({ ok: false, status: null, error: refused, retry: false });
+    const u = new URL(url);
+    const controller = new AbortController();
+    this.#inflight.add(controller);
+    const timer = setTimeout(() => controller.abort(new Error(`no answer within ${this.#cfg.timeoutMs} ms`)), this.#cfg.timeoutMs);
+    return new Promise<Attempt>((resolve) => {
+      const request = u.protocol === 'https:' ? httpsRequest : httpRequest;
+      // guardedLookup checks the addresses the name resolves to as it connects.
+      const req = request(u, { method: 'POST', headers: { ...headers, 'content-length': String(Buffer.byteLength(body)) }, lookup: guardedLookup(allow), signal: controller.signal }, (res: IncomingMessage) => {
+        res.resume();
+        res.on('end', () => {
+          const status = res.statusCode ?? 0;
+          const ok = status >= 200 && status < 300;
+          const redirect = status >= 300 && status < 400;
+          resolve({
+            ok,
+            status,
+            error: ok ? null : redirect ? `HTTP ${status}: redirects are not followed` : `HTTP ${status}`,
+            retry: status === 408 || status === 429 || status >= 500,
+          });
+        });
+        res.on('error', (err) => resolve({ ok: false, status: res.statusCode ?? null, error: describe(err), retry: true }));
+        res.on('close', () => resolve({ ok: false, status: res.statusCode ?? null, error: 'The connection closed before the answer ended', retry: true }));
+      });
+      req.on('error', (err: NodeJS.ErrnoException) => {
+        const reason = controller.signal.aborted ? controller.signal.reason : err;
+        resolve({ ok: false, status: null, error: describe(reason), retry: err.code !== 'EREFUSEDADDRESS' });
+      });
+      req.end(body);
+    }).finally(() => {
+      clearTimeout(timer);
+      this.#inflight.delete(controller);
+    });
+  }
+}
+
+function describe(err: unknown): string {
+  const e = err as { code?: string; message?: string };
+  return e?.message ?? e?.code ?? String(err);
+}

package/payload/server/src/capabilities.ts

@@ -0,0 +1,90 @@
+import type { Bot, BotonCapabilities, BotonConnector, Routine } from '../../shared/types.ts';
+import { splitRules } from './ask-rules.ts';
+
+/** The Boton's brain, as far as Ask first goes: the engine only hands rules to a provider that enforces them. */
+export interface BrainSupport {
+  label: string;
+  askFirst: boolean;
+  /** Botons runs its tools itself (an API key brain): its own sandbox, not a CLI's. */
+  serverTools?: boolean;
+}
+
+/**
+ * What a Boton may do, worded for its owner. It reads the same fields the
+ * engine enforces (access, connectors, skills, Ask first and Always allow
+ * rules, routines), so it never grants anything itself. Ask first rules are
+ * split the way the engine splits them: only a brain that pauses on them gets
+ * any, and the ones "Always allow" covers don't pause (except in webhook runs).
+ */
+export function botonCapabilities(bot: Bot, connectors: BotonConnector[], routines: Routine[], ownerName: string, brain: BrainSupport, browser: { enabled: boolean; sites: string[] } | null = null): BotonCapabilities {
+  const owner = ownerName || 'you';
+  const mine = connectors.filter((c) => c.state === 'yours');
+  const requestable = connectors.filter((c) => c.state === 'available');
+  const hooks = routines.filter((r) => r.webhook);
+  const fullHooks = hooks.filter((r) => !r.webhookWorkspace);
+  const callbacks = hooks.filter((r) => r.webhook?.callbackUrl);
+  const summary: string[] = [];
+  if (bot.access === 'host') {
+    summary.push(`Full computer access: it runs as the server's user and can read and change everything that user can, including the database, every workspace, the CLI logins and the server's environment.`);
+  } else {
+    summary.push(`Workspace access: it works in its own folder (and the shared one) inside ${brain.serverTools ? 'its sandbox' : "the CLI's sandbox"}, and can't read other workspaces, the data folder, the CLI logins or common credential folders.`);
+  }
+  if (brain.serverTools) {
+    summary.push(
+      `Its brain is an API key (${brain.label}): Botons runs its tools itself.${bot.access === 'host' ? ' With Full computer access they run as the server’s user, outside any sandbox.' : ' Its commands and file edits run in the OS sandbox (bubblewrap, with a filter that refuses Unix sockets) with no network; where that sandbox can’t be made, its turns don’t run.'} Its \`botons\` commands reach the Botons server as the CLIs' do. Botons’ tool loop has no step that pauses for ${owner}, so Ask first rules don’t apply to it. Each request’s tokens and estimated cost are counted, and its spending caps apply.`,
+    );
+  }
+  if (fullHooks.length) {
+    summary.push(`Webhooks can start ${fullHooks.length === 1 ? `"${fullHooks[0].name}"` : `${fullHooks.length} routines`} with Full computer access, on a payload from outside.`);
+  } else if (hooks.length) {
+    summary.push(`Webhooks can start ${hooks.length === 1 ? `"${hooks[0].name}"` : `${hooks.length} routines`}; those runs are held to Workspace access.`);
+  }
+  if (callbacks.length) summary.push(`${callbacks.length === 1 ? 'One routine sends' : `${callbacks.length} routines send`} run results to a callback URL you set.`);
+  if (browser?.enabled && browser.sites.length) {
+    summary.push(
+      `Browser: its own managed browser, reaching ${browser.sites.join(', ')}. It reads on its own (it opens and reads pages and takes screenshots) and clicks and types, but sends nothing a page would send (a form, a POST) unless you allow that exact request on a card, once; it never types passwords, codes or card numbers, signs in itself (you can sign its browser in yourself, by taking it over), downloads or uploads. No access to this computer's screen or your own browser profile. Not in webhook runs.`,
+    );
+  } else if (browser?.enabled) summary.push('Browser: on, but no site is listed yet, so it reaches nothing.');
+  const on = mine.filter((c) => !c.off);
+  const off = mine.filter((c) => c.off);
+  if (on.length) summary.push(`Connectors: ${on.map((c) => c.name).join(', ')}.`);
+  if (off.length) summary.push(`Turned off by ${owner}, so its turns go without ${off.length === 1 ? 'it' : 'them'} until ${off.length === 1 ? "it is" : 'they are'} on again (still granted): ${off.map((c) => c.name).join(', ')}.`);
+  if (!mine.length) summary.push('No connectors.');
+  if (requestable.length) {
+    const now = requestable.filter((c) => c.grant === 'immediate');
+    summary.push(
+      `It may ask for ${requestable.map((c) => c.name).join(', ')}${now.length ? `; ${now.map((c) => c.name).join(', ')} ${now.length === 1 ? 'is' : 'are'} granted without a card (except to webhook runs)` : `; ${owner} approves each request on a card`}.`,
+    );
+  }
+  const split = splitRules(bot.askFirst, bot.alwaysAllow, false);
+  const askFirst = brain.askFirst ? { enforced: split.ask, alwaysAllowed: split.allow, inactive: [] as string[] } : { enforced: [], alwaysAllowed: [], inactive: bot.askFirst };
+  if (askFirst.enforced.length) summary.push(`Asks ${owner} first before: ${askFirst.enforced.join(', ')}.`);
+  if (askFirst.alwaysAllowed.length) summary.push(`Ask first rules ${owner} always allows, so they pause only webhook runs: ${askFirst.alwaysAllowed.join(', ')}.`);
+  if (askFirst.inactive.length) {
+    summary.push(`Not enforced: its brain (${brain.label}) doesn't pause on Ask first rules, so these saved rules do nothing until it runs on Claude Code (the local CLI): ${askFirst.inactive.join(', ')}.`);
+  }
+  if (bot.alwaysAllow.length) summary.push(`Always allowed without asking: ${bot.alwaysAllow.join(', ')}.`);
+  summary.push(bot.skills === null ? 'Can use every skill in the library.' : bot.skills.length ? `Skills: ${bot.skills.join(', ')}.` : 'No skills.');
+  summary.push(`It can message other Botons (rate limited), notify ${owner}, and ask ${owner} for approval; it can never approve its own requests or pair a device.`);
+  if (bot.paused) summary.unshift('Paused: it runs nothing until resumed.');
+  return {
+    botId: bot.id,
+    access: bot.access,
+    paused: bot.paused,
+    summary,
+    connectors: mine.map((c) => ({ id: c.id, name: c.name, usable: c.usable, off: c.off })),
+    requestable: requestable.map((c) => ({ id: c.id, name: c.name, grant: c.grant ?? 'approval' })),
+    skills: bot.skills,
+    askFirst,
+    alwaysAllow: bot.alwaysAllow,
+    routines: routines.map((r) => ({
+      id: r.id,
+      name: r.name,
+      enabled: r.enabled,
+      schedule: r.schedule !== null,
+      webhook: r.webhook !== null,
+      webhookFullAccess: r.webhook !== null && !r.webhookWorkspace,
+      callback: !!r.webhook?.callbackUrl,
+    })),
+  };
+}

package/payload/server/src/cards.ts

@@ -0,0 +1,243 @@
+import {
+  answerText,
+  type CardAnswer,
+  type CardBlock,
+  type CardDescriptor,
+  CardError,
+  interactiveBlock,
+  parseAnswer,
+  parseCard,
+  type TranscriptCard,
+} from '../../shared/cards.ts';
+import type { ApprovalOrigin, Message } from '../../shared/types.ts';
+import type { Audit } from './audit.ts';
+import type { Principal } from './auth.ts';
+import { formatDuration, parseDuration } from './config.ts';
+import type { Connectors } from './connectors.ts';
+import { fileRef, resolveInWorkspace } from './files.ts';
+import { RunLimiter } from './limits.ts';
+import { log } from './log.ts';
+import { HttpError, type Store } from './store.ts';
+import { nowIso } from './util.ts';
+
+/*
+ * Transcript cards (shared/cards.ts): a Boton posts one with `botons card post`, the owner answers it in the chat.
+ * A card is a chat event whose meta holds the checked card and its state (Message.meta.card); the message is its
+ * one record, so there is no other table to keep in step. Every answer is checked here against the card as saved:
+ * the client sends only which option, which values or which button, never what it means. A connector card's button
+ * is the same grant as the connector's own request (on request, at the policy generation the card was posted
+ * under, checked again at the click) and is audited as the same permission change Settings records.
+ */
+
+const TTL_MS = 24 * 3_600_000;
+const TTL_MIN_MS = 60_000;
+const TTL_MAX_MS = 7 * 24 * 3_600_000;
+const PENDING_MAX = 10;
+const POSTS_PER_HOUR = 30;
+
+const NO_TURN: ApprovalOrigin = { trigger: 'chat', turnId: null, routineId: null, routineName: null, runId: null, sandboxed: false, askedBy: [] };
+
+const pastTense: Record<TranscriptCard['status'], string> = {
+  shown: 'shown (it has nothing to answer)',
+  pending: 'waiting',
+  answered: 'answered',
+  declined: 'declined',
+  expired: 'expired',
+  refused: 'closed',
+};
+
+const bad = (err: unknown): never => {
+  if (err instanceof CardError) throw new HttpError(400, err.message);
+  throw err;
+};
+
+export class Cards {
+  #store: Store;
+  #connectors: Connectors;
+  #audit: Audit;
+  #wake: (botId: string) => void;
+  #origin: (botId: string) => ApprovalOrigin | null;
+  /** In memory: a restart resets it. */
+  #limiter = new RunLimiter(POSTS_PER_HOUR, Number.MAX_SAFE_INTEGER);
+
+  constructor(opts: { store: Store; connectors: Connectors; audit: Audit; wake: (botId: string) => void; origin: (botId: string) => ApprovalOrigin | null }) {
+    this.#store = opts.store;
+    this.#connectors = opts.connectors;
+    this.#audit = opts.audit;
+    this.#wake = opts.wake;
+    this.#origin = opts.origin;
+  }
+
+  /** The Boton a card belongs to, or null (for route access: a Boton reads only its own). */
+  owner(id: string): string | null {
+    const m = this.#store.findMessage(id);
+    return m?.meta?.kind === 'card.posted' ? m.botId : null;
+  }
+
+  /** The card's message as it stands now; one past its expiry is closed as expired first. */
+  get(id: string, botId?: string): Message {
+    const m = this.#store.findMessage(id);
+    if (!m || m.role !== 'event' || m.meta?.kind !== 'card.posted' || !m.meta.card || (botId && m.botId !== botId)) throw new HttpError(404, `No card ${id}`);
+    const card = m.meta.card;
+    if (card.status === 'pending' && card.expiresAt <= nowIso()) return this.#store.closeCard(m.id, { ...card, status: 'expired' }) ?? this.get(id, botId);
+    return m;
+  }
+
+  /** `botons card post`, from Boton `botId`'s turn token. Body: `{ card, expiresIn? }`. */
+  async post(botId: string, body: unknown, opts: { sandboxed: boolean }): Promise<{ message: Message; duplicate: boolean }> {
+    const bot = this.#store.getBot(botId);
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) throw new HttpError(400, 'The body must be {"card": {...}, "expiresIn": "1d"}');
+    const extra = Object.keys(body).find((k) => k !== 'card' && k !== 'expiresIn');
+    if (extra) throw new HttpError(400, `Unknown field "${extra}" (the body has card and expiresIn)`);
+    const { card: raw, expiresIn } = body as { card?: unknown; expiresIn?: unknown };
+    let descriptor: CardDescriptor;
+    try {
+      descriptor = parseCard(raw);
+    } catch (err) {
+      return bad(err);
+    }
+    const ttl = expiresIn === undefined || expiresIn === null || expiresIn === '' ? TTL_MS : typeof expiresIn === 'string' ? parseDuration(expiresIn) : Number.NaN;
+    if (Number.isNaN(ttl)) throw new HttpError(400, 'expiresIn must be a duration such as "30m", "2h" or "3d"');
+    if (ttl < TTL_MIN_MS || ttl > TTL_MAX_MS) throw new HttpError(400, `expiresIn must be between ${formatDuration(TTL_MIN_MS)} and ${formatDuration(TTL_MAX_MS)}`);
+
+    const turn = this.#origin(botId) ?? NO_TURN;
+    const from = { trigger: turn.trigger, routineId: turn.routineId, routineName: turn.routineName, runId: turn.runId, sandboxed: opts.sandboxed || turn.sandboxed };
+
+    // Files: only regular files in the Boton's workspace, by the path the server resolved.
+    const blocks: CardBlock[] = [];
+    for (const b of descriptor.blocks) {
+      if (b.type !== 'file') {
+        blocks.push(b);
+        continue;
+      }
+      const found = await resolveInWorkspace(bot.workspace, b.path);
+      if (!found.stat.isFile()) throw new HttpError(400, `${b.path} is not a file in your workspace`);
+      blocks.push({ ...b, path: fileRef(found).path });
+    }
+    descriptor = { ...descriptor, blocks };
+
+    const ask = interactiveBlock(descriptor);
+    let connector: TranscriptCard['connector'];
+    if (ask?.type === 'connector') {
+      // A payload from outside must not ask to widen what later turns can reach.
+      if (from.sandboxed) throw new HttpError(403, "A webhook run can't post a connector card: it would widen what your later turns can reach");
+      if (bot.connections.includes(ask.connectorId)) throw new HttpError(400, `${ask.connectorId} is already one of your connectors`);
+      const problem = this.#connectors.grantProblem(bot, ask.connectorId, 'now', { usable: true });
+      if (problem) throw new HttpError(problem.startsWith('There is no') ? 404 : 403, `${problem}. See \`botons connector list\`: a card asks only for one you may ask for.`);
+      const c = this.#connectors.catalog().connectors.find((x) => x.id === ask.connectorId)!;
+      connector = { id: c.id, name: c.name, generation: this.#connectors.policyOf(c.id).generation };
+    }
+
+    const now = nowIso();
+    if (ask) {
+      const same = this.#store.samePendingCard(botId, JSON.stringify(descriptor), now);
+      if (same) return { message: same, duplicate: true };
+      if (this.#store.pendingCards(botId, now) >= PENDING_MAX) {
+        throw new HttpError(409, `You already have ${PENDING_MAX} cards waiting for ${this.#store.getSettings().ownerName}'s answer. Wait for their answers, or let them expire.`);
+      }
+    }
+    const hit = this.#limiter.check(botId);
+    if (hit) throw new HttpError(429, `At most ${POSTS_PER_HOUR} cards an hour: try again in ${formatDuration(hit.retryAfterMs)}`);
+    this.#limiter.record(botId);
+
+    const card: TranscriptCard = {
+      descriptor,
+      status: ask ? 'pending' : 'shown',
+      expiresAt: new Date(Date.now() + ttl).toISOString(),
+      from,
+      ...(connector ? { connector } : {}),
+    };
+    const run = from.routineId ? { routineId: from.routineId, ...(from.routineName ? { routineName: from.routineName } : {}), ...(from.runId ? { runId: from.runId } : {}) } : {};
+    const message = this.#store.addMessage(botId, 'event', `Posted a card: ${descriptor.title}`, { kind: 'card.posted', card, ...run });
+    log.info('card posted', { botId, cardId: message.id, ask: ask?.type ?? 'none', sandboxed: from.sandboxed || undefined, trigger: from.trigger });
+    return { message, duplicate: false };
+  }
+
+  /** The owner's answer (the route takes only paired devices). Returns the card's message as it is now. */
+  answer(botId: string, id: string, input: unknown, principal: Principal | null): Message {
+    const m = this.get(id, botId);
+    const card = m.meta!.card!;
+    if (card.status !== 'pending') throw new HttpError(409, `This card was already ${pastTense[card.status]}`);
+    let answer: ReturnType<typeof parseAnswer>;
+    try {
+      answer = parseAnswer(card.descriptor, input);
+    } catch (err) {
+      return bad(err);
+    }
+    const deviceId = principal?.kind === 'device' ? principal.deviceId : null;
+    const at = nowIso();
+    const record: CardAnswer = { action: answer.action, at, by: deviceId };
+    const ask = interactiveBlock(card.descriptor)!;
+    if (answer.action === 'choose' && ask.type === 'choice') record.option = ask.options.find((o) => o.id === answer.option)!;
+    if (answer.action === 'submit') record.values = answer.values;
+
+    // One transaction: the check of the connector (its policy generation, its sign-in, the Boton's brain and room),
+    // the card's one change, the grant with its turn, and both audit rows (required: either one failing undoes all of
+    // it, and the card still waits). Chat events go out and the Boton is woken only once it has committed.
+    const status = answer.action === 'decline' ? 'declined' : 'answered';
+    const done = this.#store.atomically((): { problem: string } | { closed: Message } => {
+      let granted = false;
+      if (answer.action === 'grant') {
+        const c = card.connector!;
+        const bot = this.#store.getBot(botId);
+        if (bot.connections.includes(c.id)) record.result = 'already';
+        else {
+          const problem = card.from.sandboxed ? 'A webhook run posted this card' : this.#connectors.grantProblem(bot, c.id, c.generation, { usable: true });
+          if (problem) return { problem };
+          record.result = 'granted';
+          granted = true;
+        }
+      }
+      const closed = this.#store.closeCard(id, { ...card, status, answer: record });
+      if (!closed) throw new HttpError(409, 'This card was already answered');
+      if (granted) {
+        const bot = this.#store.getBot(botId);
+        this.#store.setConnections(botId, [...bot.connections, card.connector!.id]);
+        // The connector's own follow-up turn (engine.ts grantedPrompt), as a request granted on a card gets.
+        this.#store.addMessage(botId, 'user', `Connector ${card.connector!.name} added`, { kind: 'connector.granted', connectorId: card.connector!.id, cardId: id }, true);
+        // The same record a change in Settings makes, so the connector's and the Boton's history show it.
+        this.#audit.require(principal, {
+          action: 'boton.permissions_changed',
+          target: { kind: 'boton', id: botId, label: bot.name },
+          details: { connectionsAdded: [card.connector!.id], via: 'card', card: id },
+        });
+      } else {
+        // A pending user message: it starts the Boton's turn with the answer, and waits out a pause or a usage limit.
+        this.#store.addMessage(botId, 'user', answerText(card.descriptor, record), { kind: 'card.answered', cardId: id }, true);
+      }
+      this.#audited(principal, m, card, answer.action, record.result ?? status, record);
+      return { closed };
+    });
+    if ('problem' in done) {
+      // Closed for good, with the reason, and nothing given: no grant, no turn. Its audit row is required too: if it
+      // can't be written the card still waits (and the answer fails), so a refusal is never unrecorded.
+      this.#store.atomically(() => {
+        if (!this.#store.closeCard(id, { ...card, status: 'refused', reason: done.problem })) throw new HttpError(409, 'This card was already answered');
+        this.#audited(principal, m, card, 'grant', 'refused');
+      });
+      throw new HttpError(409, `${done.problem}, so nothing was given and the card is closed.`);
+    }
+    log.info('card answered', { botId, cardId: id, action: answer.action, result: record.result, deviceId: deviceId ?? undefined });
+    this.#wake(botId);
+    return done.closed;
+  }
+
+  /**
+   * Which card, what was pressed and how it ended: never the values typed (they are in the chat, not the log).
+   * Required, inside the answer's transaction: should it fail, the card is not answered, refused or granted.
+   */
+  #audited(principal: Principal | null, m: Message, card: TranscriptCard, action: string, result: string, answer?: CardAnswer) {
+    this.#audit.require(principal, {
+      action: 'card.answered',
+      target: { kind: 'card', id: m.id, label: card.descriptor.title },
+      details: {
+        boton: m.botId,
+        answer: action,
+        result,
+        ...(answer?.option ? { option: answer.option.id } : {}),
+        ...(answer?.values ? { fields: Object.keys(answer.values) } : {}),
+        ...(card.connector ? { connector: card.connector.id, connectorName: card.connector.name } : {}),
+      },
+    });
+  }
+}

package/payload/server/src/cli/approve-mcp.ts

@@ -0,0 +1,119 @@
+import { VERSION } from '../../../shared/app-version.mjs';
+// `botons mcp`: an MCP server (JSON-RPC over stdio, one message per line) whose one tool, approve, is
+// Claude Code's --permission-prompt-tool for a turn with Ask first rules. It asks the Botons server with
+// the turn's token, then polls until the owner decides or the call's wait ends.
+import { createInterface } from 'node:readline';
+import type { ToolCallVerdict } from '../../../shared/types.ts';
+
+/** The MCP version this speaks when the client names none. */
+const PROTOCOL = '2025-06-18';
+/** Polls that may fail in a row (a server restarting, say) before the call is denied. */
+const POLL_FAILURES_MAX = 5;
+
+const APPROVE_TOOL = {
+  name: 'approve',
+  description: "Asks the Boton's owner whether a tool call one of their Ask first rules covers may run. Called by Claude Code for permission prompts only.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      tool_name: { type: 'string' },
+      input: { type: 'object' },
+      tool_use_id: { type: 'string' },
+    },
+    required: ['tool_name', 'input'],
+  },
+};
+
+type Answer = { behavior: 'allow'; updatedInput: unknown } | { behavior: 'deny'; message: string };
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** Serve until stdin closes. */
+export function serveApprovals(opts: { api: string; bot: string; token: string; pollMs?: number }): Promise<void> {
+  const pollMs = opts.pollMs ?? 1000;
+  const send = (m: unknown): void => {
+    process.stdout.write(`${JSON.stringify(m)}\n`);
+  };
+
+  async function call(method: string, path: string, body?: unknown): Promise<ToolCallVerdict> {
+    const res = await fetch(`${opts.api}${path}`, {
+      method,
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${opts.token}` },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: AbortSignal.timeout(30_000),
+    });
+    const text = await res.text();
+    let data: any = null;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {}
+    if (!res.ok) throw new Error(data?.error ?? `HTTP ${res.status}`);
+    return data as ToolCallVerdict;
+  }
+
+  async function approve(args: any): Promise<Answer> {
+    const input = args?.input ?? {};
+    if (!opts.bot || !opts.token) return { behavior: 'deny', message: 'This call needs your owner\'s approval, but this turn has no Botons token to ask with, so it is denied.' };
+    try {
+      let v = await call('POST', `/api/bots/${encodeURIComponent(opts.bot)}/approvals/tool-call`, { toolName: args?.tool_name, input, toolUseId: args?.tool_use_id });
+      let failures = 0;
+      // This call's own place on the card: an allow goes to one call only.
+      const waiter = v.waiter ?? '';
+      while (v.behavior === 'wait' && v.approval) {
+        await sleep(pollMs);
+        try {
+          v = await call('GET', `/api/approvals/${encodeURIComponent(v.approval.id)}/tool-call?waiter=${encodeURIComponent(waiter)}`);
+          failures = 0;
+        } catch (err) {
+          if (++failures >= POLL_FAILURES_MAX) throw err;
+        }
+      }
+      if (v.behavior === 'allow') return { behavior: 'allow', updatedInput: input };
+      return { behavior: 'deny', message: v.message ?? 'Denied.' };
+    } catch (err) {
+      return { behavior: 'deny', message: `This call needs your owner's approval, but the Botons server could not be asked (${(err as Error).message}), so it is denied.` };
+    }
+  }
+
+  async function handle(msg: any): Promise<void> {
+    const id = msg?.id;
+    const reply = (result: unknown) => send({ jsonrpc: '2.0', id, result });
+    switch (msg?.method) {
+      case 'initialize':
+        return reply({
+          protocolVersion: typeof msg.params?.protocolVersion === 'string' ? msg.params.protocolVersion : PROTOCOL,
+          capabilities: { tools: {} },
+          serverInfo: { name: 'botons', version: VERSION },
+        });
+      case 'ping':
+        return reply({});
+      case 'tools/list':
+        return reply({ tools: [APPROVE_TOOL] });
+      case 'tools/call': {
+        if (msg.params?.name !== APPROVE_TOOL.name) {
+          return send({ jsonrpc: '2.0', id, error: { code: -32602, message: `Unknown tool ${msg.params?.name}` } });
+        }
+        const answer = await approve(msg.params?.arguments);
+        return reply({ content: [{ type: 'text', text: JSON.stringify(answer) }] });
+      }
+      default:
+        // Notifications (no id) need no answer.
+        if (id !== undefined && id !== null) send({ jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${msg?.method}` } });
+    }
+  }
+
+  const lines = createInterface({ input: process.stdin, crlfDelay: Number.POSITIVE_INFINITY });
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let msg: unknown;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+      return;
+    }
+    // Answered as they finish: a call waiting for the owner holds up nothing else.
+    void handle(msg);
+  });
+  return new Promise((done) => lines.on('close', () => done()));
+}