getbotons 0.0.0-stage → 0.1.0

package/payload/server/src/limits.ts

@@ -0,0 +1,44 @@
+const WINDOW_MS = 3_600_000;
+
+/**
+ * Sliding one-hour windows on runs (or asks) started: per key and in total.
+ * In memory, so a restart starts them afresh.
+ */
+export class RunLimiter {
+  #perKey: number;
+  #total: number;
+  #byKey = new Map<string, number[]>();
+  #all: number[] = [];
+
+  constructor(perKey: number, total: number) {
+    this.#perKey = perKey;
+    this.#total = total;
+  }
+
+  /** Null if `key` may start another now; otherwise which limit it hit and when a slot frees up. */
+  check(key: string): { limit: 'routine' | 'total'; max: number; retryAfterMs: number } | null {
+    const now = Date.now();
+    const mine = this.#prune(this.#byKey.get(key) ?? [], now);
+    if (mine.length) this.#byKey.set(key, mine);
+    else this.#byKey.delete(key);
+    this.#all = this.#prune(this.#all, now);
+    if (mine.length >= this.#perKey) return { limit: 'routine', max: this.#perKey, retryAfterMs: mine[mine.length - this.#perKey] + WINDOW_MS - now };
+    if (this.#all.length >= this.#total) return { limit: 'total', max: this.#total, retryAfterMs: this.#all[this.#all.length - this.#total] + WINDOW_MS - now };
+    return null;
+  }
+
+  record(key: string): void {
+    const now = Date.now();
+    const mine = this.#byKey.get(key) ?? [];
+    mine.push(now);
+    this.#byKey.set(key, mine);
+    this.#all.push(now);
+  }
+
+  #prune(times: number[], now: number): number[] {
+    const from = now - WINDOW_MS;
+    let i = 0;
+    while (i < times.length && times[i] <= from) i++;
+    return i ? times.slice(i) : times;
+  }
+}

package/payload/server/src/lock.ts

@@ -0,0 +1,75 @@
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+export class DataDirInUseError extends Error {
+  name = 'DataDirInUseError';
+  constructor(home: string, pid: number | null) {
+    super(
+      `Botons data dir in use: another Botons server${pid ? ` (pid ${pid})` : ''} is using ${home}. ` +
+        'Stop it first, or set BOTONS_HOME to another folder. Nothing was changed.',
+    );
+  }
+}
+
+export interface DataDirLock {
+  release(): void;
+}
+
+function livePid(pidFile: string): number | null {
+  let pid: number;
+  try {
+    pid = Number(readFileSync(pidFile, 'utf8').trim());
+  } catch {
+    return null;
+  }
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+    return pid;
+  } catch (err) {
+    // EPERM: it exists but belongs to another user.
+    return (err as NodeJS.ErrnoException).code === 'EPERM' ? pid : null;
+  }
+}
+
+/** Each held lock's connection, so dropping a lock's handle can't let GC close it and free the data dir. */
+const heldLocks = new Set<DatabaseSync>();
+
+/**
+ * Only one server may open the database. The lock is an open EXCLUSIVE
+ * transaction on `<home>/server.lock`: the kernel drops its fcntl lock when the
+ * process dies however it dies, so it never goes stale. server.pid only names
+ * the holder in the error.
+ */
+export function lockDataDir(home: string): DataDirLock {
+  const lockFile = join(home, 'server.lock');
+  const pidFile = join(home, 'server.pid');
+  const db = new DatabaseSync(lockFile, { timeout: 0 });
+  try {
+    // Journal in memory, so no server.lock-journal appears.
+    db.exec('pragma journal_mode = memory; begin exclusive');
+  } catch (err) {
+    db.close();
+    // SQLITE_BUSY (5), possibly as an extended code.
+    if ((((err as { errcode?: number }).errcode ?? 0) & 0xff) === 5) throw new DataDirInUseError(home, livePid(pidFile));
+    throw err;
+  }
+  heldLocks.add(db);
+  try {
+    writeFileSync(pidFile, `${process.pid}\n`);
+  } catch {}
+  let held = true;
+  return {
+    release() {
+      if (!held) return;
+      held = false;
+      // While still holding the lock, so it never removes the next holder's pid file.
+      try {
+        if (readFileSync(pidFile, 'utf8').trim() === String(process.pid)) rmSync(pidFile, { force: true });
+      } catch {}
+      heldLocks.delete(db);
+      db.close();
+    },
+  };
+}

package/payload/server/src/log.ts

@@ -0,0 +1,137 @@
+import { fstatSync } from 'node:fs';
+
+// Node builtins only: scripts/backup.ts imports config.ts, which imports this, without node_modules.
+
+/*
+ * One JSON object per line on stdout. Never log secrets (tokens, webhook keys,
+ * Authorization headers, ?key= values), chat text or webhook payloads; known
+ * token shapes are masked anyway, as a last line of defense.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export const LOG_LEVELS: readonly LogLevel[] = ['debug', 'info', 'warn', 'error'];
+
+/** `err` (any thrown value) is written as `error` and `stack`. */
+export type LogFields = Record<string, unknown>;
+
+export interface LogLine {
+  ts: string;
+  level: LogLevel;
+  msg: string;
+  [field: string]: unknown;
+}
+
+/** syslog priorities, for the `<N>` prefix journald reads (and strips) when stdout is the journal. */
+const PRIORITY: Record<LogLevel, number> = { debug: 7, info: 6, warn: 4, error: 3 };
+
+const envLevel = process.env.BOTONS_LOG_LEVEL?.trim().toLowerCase();
+/** BOTONS_LOG_LEVEL until the server applies its config. */
+let threshold: LogLevel = LOG_LEVELS.find((l) => l === envLevel) ?? 'info';
+/** Set while a test captures lines. */
+let sink: ((line: string) => void) | null = null;
+/** Called with every line written (never debug), before it is serialized: Settings → Server events. */
+const taps = new Set<(level: LogLevel, msg: string, fields: LogFields, at: Date) => void>();
+
+/** Sees each info, warn and error line the threshold lets through; returns the function that stops it. A tap that throws costs nothing. */
+export function tapLogs(fn: (level: LogLevel, msg: string, fields: LogFields, at: Date) => void): () => void {
+  taps.add(fn);
+  return () => void taps.delete(fn);
+}
+
+export function setLogLevel(level: LogLevel): void {
+  threshold = level;
+}
+
+/** Whether JOURNAL_STREAM (`<device>:<inode>`) names stdout, so `journalctl -p` works and `-o cat` still shows plain JSON. */
+export function isJournalStream(journalStream: string | undefined, stat: () => { dev: bigint; ino: bigint }): boolean {
+  const m = /^(\d+):(\d+)$/.exec(journalStream?.trim() ?? '');
+  if (!m) return false;
+  try {
+    const st = stat();
+    return st.dev === BigInt(m[1]) && st.ino === BigInt(m[2]);
+  } catch {
+    return false;
+  }
+}
+
+let toJournal: boolean | undefined;
+
+function errorFields(err: unknown): { error: string; stack?: string } {
+  if (err instanceof Error) return err.stack ? { error: err.message, stack: err.stack } : { error: err.message };
+  return { error: typeof err === 'string' ? err : safeString(err) };
+}
+
+function safeString(v: unknown): string {
+  try {
+    return typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v);
+  } catch {
+    return Object.prototype.toString.call(v);
+  }
+}
+
+/** Runs on the JSON text, and never introduces a quote or backslash. */
+export function redact(text: string): string {
+  return text
+    .replace(/\b(md|mm)t_[A-Za-z0-9_-]{8,}/g, '$1t_[redacted]')
+    .replace(/(\bBearer\s+)[A-Za-z0-9._~+/=-]+/gi, '$1[redacted]')
+    .replace(/([?&]key=)[^&\s"\\#]+/gi, '$1[redacted]');
+}
+
+const replacer = (_key: string, value: unknown) => {
+  if (typeof value === 'bigint') return value.toString();
+  if (value instanceof Error) return errorFields(value);
+  return value;
+};
+
+export function formatLine(level: LogLevel, msg: string, fields: LogFields = {}, now = new Date()): string {
+  const out: Record<string, unknown> = { ts: now.toISOString(), level, msg };
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === undefined || k === 'ts' || k === 'level' || k === 'msg') continue;
+    if (k === 'err') Object.assign(out, errorFields(v));
+    else out[k] = v;
+  }
+  try {
+    return redact(JSON.stringify(out, replacer));
+  } catch (err) {
+    // A field that can't be serialized (a cycle, say) must not cost the line.
+    return redact(JSON.stringify({ ts: out.ts, level, msg, logError: `fields not logged: ${(err as Error).message}` }));
+  }
+}
+
+function emit(level: LogLevel, msg: string, fields?: LogFields): void {
+  if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf(threshold)) return;
+  const now = new Date();
+  if (level !== 'debug') {
+    for (const tap of taps) {
+      try {
+        tap(level, msg, fields ?? {}, now);
+      } catch {}
+    }
+  }
+  const line = formatLine(level, msg, fields, now);
+  if (sink) return sink(line);
+  toJournal ??= isJournalStream(process.env.JOURNAL_STREAM, () => fstatSync(1, { bigint: true }));
+  process.stdout.write(`${toJournal ? `<${PRIORITY[level]}>` : ''}${line}\n`);
+}
+
+export const log = {
+  debug: (msg: string, fields?: LogFields) => emit('debug', msg, fields),
+  info: (msg: string, fields?: LogFields) => emit('info', msg, fields),
+  warn: (msg: string, fields?: LogFields) => emit('warn', msg, fields),
+  error: (msg: string, fields?: LogFields) => emit('error', msg, fields),
+};
+
+/** For tests: collect every line (all levels) instead of writing it, until restore(). */
+export function captureLogs(): { lines: LogLine[]; restore(): void } {
+  const lines: LogLine[] = [];
+  const prev = { sink, threshold };
+  sink = (line) => lines.push(JSON.parse(line) as LogLine);
+  threshold = 'debug';
+  return {
+    lines,
+    restore() {
+      sink = prev.sink;
+      threshold = prev.threshold;
+    },
+  };
+}

package/payload/server/src/managed-clis.ts

@@ -0,0 +1,65 @@
+import { readFileSync, existsSync, lstatSync, readdirSync, rmSync, realpathSync, statSync } from 'node:fs';
+import { join, relative, isAbsolute, delimiter } from 'node:path';
+import { homedir } from 'node:os';
+export type ManagedProvider = 'codex-cli' | 'claude-cli';
+export const managedRoot = (userHome = homedir()) => join(userHome, '.local/share/botons');
+const cliName = (provider: ManagedProvider) => (provider === 'codex-cli' ? 'codex' : 'claude');
+
+/** The first executable `name` on `path`, as a shell would find it; null when there is none. */
+export function onPath(name: string, path = process.env.PATH ?? ''): string | null {
+  for (const dir of path.split(delimiter)) {
+    if (!dir || !isAbsolute(dir)) continue;
+    try { const file = join(dir, name); if (statSync(file).isFile() && (statSync(file).mode & 0o111)) return file; } catch {}
+  }
+  return null;
+}
+
+/** Whether two CLI settings ("codex", "/usr/bin/codex", a symlink to it) run the same file. */
+export function sameCli(a: string, b: string, path = process.env.PATH ?? ''): boolean {
+  if (a === b) return true;
+  const real = (bin: string) => { try { const file = bin.includes('/') ? bin : onPath(bin, path); return file ? realpathSync(file) : null; } catch { return null; } };
+  const x = real(a);
+  return x !== null && x === real(b);
+}
+
+/** Botons' own copy: one Settings → Brains installed, or the installer's, both under the managed root. */
+export function isManagedBin(bin: string, provider: ManagedProvider, root = managedRoot()): boolean {
+  const path = relative(join(root, 'clis'), bin), name = cliName(provider);
+  return isAbsolute(bin) && (path === `${name}/bin/${name}` || new RegExp(`^${provider}/releases/[a-zA-Z0-9-]+/bin/${name}$`).test(path));
+}
+
+/** The copy a terminal on this machine runs as `codex` or `claude`, when it is another file than Botons' `bin`. */
+export function terminalCli(provider: ManagedProvider, bin: string, path = process.env.PATH ?? ''): string | null {
+  const found = onPath(cliName(provider), path);
+  return found && !sameCli(found, bin, path) ? found : null;
+}
+
+export function managedBin(home: string, provider: ManagedProvider, fallback: string, root = managedRoot(), searchPath = process.env.PATH ?? ''): string {
+  try {
+    const record = JSON.parse(readFileSync(join(home, 'managed-clis.json'), 'utf8'))[provider];
+    if (!record || typeof record.bin !== 'string') return fallback;
+    // The same system copy, named another way ("codex" or its full path), keeps Botons' own; another copy wins.
+    if (fallback !== record.bin && !(typeof record.previous === 'string' && sameCli(fallback, record.previous, searchPath))) return fallback;
+    const path = relative(join(root, 'clis', provider, 'releases'), record.bin);
+    if (isAbsolute(path) || path.startsWith('..') || !/^[a-zA-Z0-9-]+\/bin\/(codex|claude)$/.test(path)) return fallback;
+    return record.bin;
+  } catch { return fallback; }
+}
+
+/** Call only after turns drain, or at startup before turns begin. Never clean system paths or links. */
+export function pruneManagedReleases(root: string, provider: ManagedProvider, current: string): void {
+  const releases = join(root, 'clis', provider, 'releases');
+  const selected = relative(releases, current);
+  if (!/^[0-9a-f-]{36}\/bin\/(codex|claude)$/.test(selected) || !existsSync(current)) return;
+  try {
+    for (const path of [root, join(root, 'clis'), join(root, 'clis', provider), releases]) if (lstatSync(path).isSymbolicLink()) return;
+    const selectedRelease = join(releases, selected.split('/')[0]);
+    if (lstatSync(selectedRelease).isSymbolicLink() || lstatSync(join(selectedRelease, 'bin')).isSymbolicLink()) return;
+    const backing = relative(selectedRelease, realpathSync(current));
+    if (isAbsolute(backing) || backing === '..' || backing.startsWith('../')) return;
+    for (const entry of readdirSync(releases, {withFileTypes:true})) {
+      if (!entry.isDirectory() || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(entry.name) || selected.startsWith(entry.name + '/')) continue;
+      rmSync(join(releases, entry.name), {recursive:true, force:true});
+    }
+  } catch { /* Retaining an old release must not prevent startup or undo activation. */ }
+}

package/payload/server/src/mcp-client.ts

@@ -0,0 +1,229 @@
+import { VERSION } from '../../shared/app-version.mjs';
+import { hostOf, OutboundError, outbound } from './outbound.ts';
+import { redact, redactJson, sanitize } from './secrets.ts';
+import { refusedText } from '../../shared/services.ts';
+
+/*
+ * Just enough of an MCP client (Streamable HTTP) for the server's own calls with a connector's token: initialize,
+ * list tools, call one. Each answer may be JSON or a short event stream; both are bounded by outbound().
+ */
+
+const PROTOCOL = '2025-06-18';
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_TOOL_PAGES = 20;
+
+export class McpError extends Error {
+  /** auth: the token was refused (401/403); rpc: the server answered with an error; transport: anything else. */
+  readonly kind: 'auth' | 'rpc' | 'transport';
+  constructor(kind: McpError['kind'], message: string) {
+    super(message);
+    this.kind = kind;
+  }
+}
+
+/**
+ * The secrets in a set of request headers: each value, and the credential after an auth scheme ("Bearer x" → x), so
+ * a server that echoes them back in an error or a tool name can't get them into a result, a log line or the audit.
+ */
+export function secretsOf(headers: Record<string, string>): string[] {
+  const out = new Set<string>();
+  for (const v of Object.values(headers)) {
+    out.add(v);
+    const m = /^\S+\s+(\S.*)$/.exec(v);
+    if (m) out.add(m[1]);
+  }
+  return [...out].filter((v) => v.length > 0).sort((a, b) => b.length - a.length);
+}
+
+export { redact };
+
+/** Every secret of the session taken out of a result's text, whatever its length. */
+function sanitizeText(text: string, secrets: string[]): string {
+  let out = text;
+  for (const v of secrets) if (v.length >= 4) out = out.split(v).join('[redacted]');
+  return out;
+}
+
+/**
+ * What a server said about its tools or a call, with the session's secrets out of all of it (structured content, a
+ * tool's description and input schema, not only text) before anything else reads it. Names stay as they are, for the
+ * caller to judge (an API brain leaves out a tool whose name holds one: it can't be redacted and still be called).
+ */
+export function cleanTools(tools: McpTool[], secrets: string[]): McpTool[] {
+  const scrub = (t: string) => sanitizeText(t, secrets);
+  return tools.map((t) => ({ name: t.name, inputSchema: t.inputSchema ? (redactJson(t.inputSchema, scrub) as Record<string, unknown>) : null, description: typeof t.description === 'string' ? scrub(t.description) : null }));
+}
+
+/** Whether `text` holds one of `secrets` (as cleanTools and cleanResult take them out). */
+export function holdsSecret(text: string, secrets: string[]): boolean {
+  return secrets.some((v) => v.length >= 4 && text.includes(v));
+}
+
+/**
+ * A tools/call result with the session's secrets out of it, and `also` (the caller's own, such as an API brain's
+ * keys) applied too: both to the whole text, before it is cut, so no part of a secret is left at the cut.
+ */
+export function cleanResult(r: Record<string, unknown>, secrets: string[], also: (text: string) => string = (t) => t): ToolResult {
+  const scrub = (t: string) => also(sanitizeText(t, secrets));
+  const sc = r.structuredContent;
+  return {
+    isError: r.isError === true,
+    structured: sc && typeof sc === 'object' && !Array.isArray(sc) ? (redactJson(sc, scrub) as Record<string, unknown>) : null,
+    text: resultText(r.content, scrub),
+  };
+}
+
+export interface McpTool {
+  name: string;
+  inputSchema: Record<string, unknown> | null;
+  /** The server's own words for it, when a string (for a model to read; never trusted). */
+  description?: string | null;
+}
+
+export interface ToolResult {
+  isError: boolean;
+  structured: Record<string, unknown> | null;
+  /** Its text content blocks, joined, bounded (other kinds of content are named, not passed on). */
+  text?: string;
+}
+
+const MAX_RESULT_TEXT = 64 * 1024;
+
+/**
+ * A tools/call result's content as text: text blocks as they are, anything else by its kind, joined; `scrub` goes
+ * over the whole of it (across the blocks' joins too) before it is cut at MAX_RESULT_TEXT.
+ */
+export function resultText(content: unknown, scrub: (text: string) => string = (t) => t): string {
+  const parts: string[] = [];
+  for (const b of Array.isArray(content) ? content : []) {
+    const block = b as { type?: unknown; text?: unknown };
+    if (block?.type === 'text' && typeof block.text === 'string') parts.push(block.text);
+    else if (typeof block?.type === 'string') parts.push(`[${block.type.slice(0, 40)} content not shown]`);
+  }
+  const text = scrub(parts.join('\n'));
+  return text.length > MAX_RESULT_TEXT ? `${text.slice(0, MAX_RESULT_TEXT)}\n[… cut at ${MAX_RESULT_TEXT} characters]` : text;
+}
+
+/** The JSON-RPC answer with `id`, from a JSON body or an SSE stream. */
+function answerOf(body: string, contentType: string, id: number): Record<string, unknown> | null {
+  const pick = (v: unknown) => {
+    const list = Array.isArray(v) ? v : [v];
+    return (list.find((m) => m && typeof m === 'object' && (m as Record<string, unknown>).id === id) as Record<string, unknown> | undefined) ?? null;
+  };
+  if (contentType.includes('text/event-stream')) {
+    for (const block of body.split(/\r?\n\r?\n/)) {
+      const data = block
+        .split(/\r?\n/)
+        .filter((l) => l.startsWith('data:'))
+        .map((l) => l.slice(5).trimStart())
+        .join('\n');
+      if (!data) continue;
+      try {
+        const found = pick(JSON.parse(data));
+        if (found) return found;
+      } catch {}
+    }
+    return null;
+  }
+  try {
+    return pick(JSON.parse(body));
+  } catch {
+    return null;
+  }
+}
+
+export class McpSession {
+  #url: string;
+  #headers: Record<string, string>;
+  #allow: string[];
+  #signal?: AbortSignal;
+  #session: string | null = null;
+  #version = PROTOCOL;
+  #id = 0;
+  #authority?: () => void;
+  /** How long one request may take; tools/call of an API brain's connector may take longer than a test's. */
+  timeoutMs = 20_000;
+
+  /** `auth`: a bearer token, or the headers a library server was saved with (the protocol's own headers win). */
+  constructor(url: string, auth: string | Record<string, string>, allow: string[], signal?: AbortSignal, authority?: () => void) {
+    this.#url = url;
+    this.#headers = {};
+    if (typeof auth === 'string') this.#headers.authorization = `Bearer ${auth}`;
+    else for (const [k, v] of Object.entries(auth)) this.#headers[k.toLowerCase()] = v;
+    this.#allow = allow;
+    this.#signal = signal;
+    this.#authority = authority;
+  }
+
+  /** What this session sends that must not come back out in text: see secretsOf(). */
+  get secrets(): string[] {
+    return secretsOf(this.#headers);
+  }
+
+  async #post(body: Record<string, unknown>, expectAnswer: boolean): Promise<Record<string, unknown> | null> {
+    // Includes initialization notifications and each discovery page, not only top-level tool calls.
+    this.#authority?.();
+    const headers: Record<string, string> = {
+      ...this.#headers,
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      'mcp-protocol-version': this.#version,
+    };
+    delete headers['mcp-session-id'];
+    if (this.#session) headers['mcp-session-id'] = this.#session;
+    let res;
+    try {
+      res = await outbound(this.#url, { method: 'POST', allow: this.#allow, headers, body: JSON.stringify(body), maxBytes: MAX_BYTES, timeoutMs: this.timeoutMs, signal: this.#signal });
+    } catch (err) {
+      throw new McpError('transport', sanitize(err instanceof OutboundError ? err.message : String(err), this.secrets, 300));
+    }
+    this.#authority?.();
+    if (res.status === 401 || res.status === 403) throw new McpError('auth', refusedText(this.#url, res.status, 'authorization' in this.#headers));
+    const sid = res.headers['mcp-session-id'];
+    if (typeof sid === 'string' && /^[\x21-\x7e]{1,200}$/.test(sid)) this.#session = sid;
+    if (!expectAnswer) {
+      if (res.status >= 300) throw new McpError('transport', `${hostOf(this.#url)} answered ${res.status}`);
+      return null;
+    }
+    if (res.status !== 200) throw new McpError('transport', `${hostOf(this.#url)} answered ${res.status}`);
+    const answer = answerOf(res.body, String(res.headers['content-type'] ?? ''), body.id as number);
+    if (!answer) throw new McpError('transport', `${hostOf(this.#url)} sent no answer to ${String(body.method)}`);
+    if (answer.error) {
+      const e = answer.error as { message?: unknown };
+      throw new McpError('rpc', `${hostOf(this.#url)}: ${typeof e?.message === 'string' ? sanitize(e.message, this.secrets, 200) : 'error'}`);
+    }
+    const result = answer.result;
+    return result && typeof result === 'object' && !Array.isArray(result) ? (result as Record<string, unknown>) : {};
+  }
+
+  #request(method: string, params: Record<string, unknown>) {
+    return this.#post({ jsonrpc: '2.0', id: ++this.#id, method, params }, true) as Promise<Record<string, unknown>>;
+  }
+
+  async initialize(): Promise<void> {
+    const r = await this.#request('initialize', { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: 'Botons', version: VERSION } });
+    if (typeof r.protocolVersion === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(r.protocolVersion)) this.#version = r.protocolVersion;
+    await this.#post({ jsonrpc: '2.0', method: 'notifications/initialized' }, false);
+  }
+
+  /** Every tool, following nextCursor (bounded). */
+  async listTools(): 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 });
+      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>, also?: (text: string) => string): Promise<ToolResult> {
+    return cleanResult(await this.#request('tools/call', { name, arguments: args }), this.secrets, also);
+  }
+}