@amenophis1er/foreman 0.1.0

package/src/models.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Endpoint model discovery.
+ *
+ * The behaviour worth pinning down is which probe wins and what "no answer"
+ * means: an endpoint that cannot be reached is not the same as one with no
+ * models, and conflating them would show an empty picker for a typo'd host.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import { costRank, describeModel, discoverModels } from './models.js';
+
+/** A stub endpoint; `routes` maps a path to [status, body]. */
+function stub(routes: Record<string, [number, unknown]>): Promise<{
+  url: string; hits: string[]; auth: (string | undefined)[]; close: () => Promise<void>;
+}> {
+  const hits: string[] = [];
+  const auth: (string | undefined)[] = [];
+  const server = http.createServer((req, res) => {
+    hits.push(req.url ?? '');
+    auth.push(req.headers.authorization as string | undefined);
+    const hit = routes[req.url ?? ''];
+    if (!hit) { res.writeHead(404); res.end('{}'); return; }
+    res.writeHead(hit[0], { 'content-type': 'application/json' });
+    res.end(JSON.stringify(hit[1]));
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => {
+      const a = server.address();
+      const port = typeof a === 'object' && a ? a.port : 0;
+      resolve({
+        url: `http://127.0.0.1:${port}`, hits, auth,
+        close: () => new Promise((r) => server.close(() => r())),
+      });
+    });
+  });
+}
+
+const TAGS = {
+  models: [
+    { name: 'kimi-k3:cloud', remote_model: 'kimi-k3', remote_host: 'https://ollama.com', details: { parameter_size: '2.81T' } },
+    { name: 'smollm:135m', details: { parameter_size: '134.52M' } },
+    { name: 'ornith:9b', details: { parameter_size: '9.0B' } },
+    { name: '', details: {} },
+  ],
+};
+
+test('Ollama’s richer listing is preferred where it answers', async (t) => {
+  const s = await stub({ '/api/tags': [200, TAGS] });
+  t.after(() => s.close());
+  const models = await discoverModels(s.url, { timeoutMs: 800 });
+  assert.ok(models);
+  // Alphabetical: a cloud model is not a lesser option to be listed last.
+  assert.deepEqual(models.map((m) => m.id), ['kimi-k3:cloud', 'ornith:9b', 'smollm:135m']);
+  assert.equal(models[0].remote, true);
+  assert.equal(models[0].host, 'https://ollama.com');
+  assert.equal(models[2].size, '134.52M');
+  assert.deepEqual(s.hits, ['/api/tags'], '/v1/models must not be probed once tags answered');
+});
+
+test('anything OpenAI-compatible falls back to /v1/models', async (t) => {
+  const s = await stub({ '/v1/models': [200, { data: [{ id: 'gpt-5' }, { id: 'glm-5.3-flash' }] }] });
+  t.after(() => s.close());
+  const models = await discoverModels(s.url, { timeoutMs: 800 });
+  assert.deepEqual(models?.map((m) => m.id), ['glm-5.3-flash', 'gpt-5']);
+  assert.equal(models?.[0].remote, false, 'the OpenAI shape cannot express this, so do not claim it');
+  assert.deepEqual(s.hits, ['/api/tags', '/v1/models']);
+});
+
+test('unreachable is null, and is not the same as empty', async (t) => {
+  // Nothing listening: a typo'd host must be distinguishable from a daemon
+  // with nothing pulled, or the picker lies about which it is.
+  assert.equal(await discoverModels('http://127.0.0.1:1', { timeoutMs: 300 }), null);
+
+  const s = await stub({ '/api/tags': [200, { models: [] }] });
+  t.after(() => s.close());
+  assert.deepEqual(await discoverModels(s.url, { timeoutMs: 800 }), []);
+});
+
+test('a pasted /v1 suffix or trailing slash is tolerated', async (t) => {
+  const s = await stub({ '/api/tags': [200, TAGS] });
+  t.after(() => s.close());
+  for (const suffix of ['', '/', '/v1']) {
+    const models = await discoverModels(s.url + suffix, { timeoutMs: 800 });
+    assert.equal(models?.length, 3, `failed for ${JSON.stringify(suffix)}`);
+  }
+});
+
+test('a key is sent when the endpoint needs one to list', async (t) => {
+  const s = await stub({ '/v1/models': [200, { data: [{ id: 'x' }] }] });
+  t.after(() => s.close());
+  await discoverModels(s.url, { apiKey: 'sk-test', timeoutMs: 800 });
+  assert.ok(s.auth.every((a) => a === 'Bearer sk-test'));
+});
+
+test('the note names the trade rather than ranking the options', () => {
+  assert.match(describeModel({ id: 'a', remote: true, host: 'https://ollama.com' }), /ollama\.com.*Fast/s);
+  assert.match(describeModel({ id: 'b', remote: false, size: '9.0B' }), /Local · 9\.0B.*Free and private/s);
+});
+
+// ---------------------------------------------------------------------------
+// What a picker is told about price
+// ---------------------------------------------------------------------------
+
+test('a published rate leads the description, in per-million terms', () => {
+  // Per-token is how the source publishes and how prices.ts stores it; per
+  // million is how a person reads a pricing page. The conversion happens here
+  // and nowhere else.
+  assert.equal(
+    describeModel({ id: 'x', remote: false, price: { input: 0.000002, output: 0.00001 } }),
+    '$2.00 in / $10.00 out per million tokens.',
+  );
+});
+
+test('a sub-cent rate is not rounded away to nothing', () => {
+  // "$0.00 in / $0.00 out" would say free about a model that is not.
+  assert.equal(
+    describeModel({ id: 'x', remote: false, price: { input: 0.00000005, output: 0.0000004 } }),
+    '$0.050 in / $0.400 out per million tokens.',
+  );
+});
+
+test('a model published at zero is described as free at that endpoint', () => {
+  assert.equal(
+    describeModel({ id: 'x', remote: false, price: { input: 0, output: 0 } }),
+    'Free at this endpoint.',
+  );
+});
+
+test('an unpriced remote model says the rate is not visible, rather than implying none', () => {
+  const note = describeModel({ id: 'x', remote: true, host: 'https://ollama.com' });
+  assert.match(note, /billed to that account/);
+  assert.match(note, /Foreman cannot see/);
+});
+
+test('cost bars come from the real rate where there is one', () => {
+  const rank = (output: number) => costRank({ id: 'x', remote: true, price: { input: 0, output } });
+  assert.equal(rank(0), 0);
+  assert.equal(rank(0.0000005), 1);   // $0.50/Mtok
+  assert.equal(rank(0.000002), 2);    // $2
+  assert.equal(rank(0.00001), 3);     // $10
+  assert.equal(rank(0.00006), 4);     // $60
+  // With no rate published, the old constant stands: local is free, remote is
+  // a guess, and the note beside it says the rate is unknown.
+  assert.equal(costRank({ id: 'x', remote: false }), 0);
+  assert.equal(costRank({ id: 'x', remote: true }), 2);
+});

package/src/models.ts

@@ -0,0 +1,158 @@
+/**
+ * What models does an endpoint actually have?
+ *
+ * Every `openai-compatible` provider can answer this, and the answer belongs
+ * to the *endpoint*, not to the server: a project pointed at an Ollama on
+ * another machine must be offered that machine's models, not this one's.
+ *
+ * Two probes, richest first:
+ *
+ *  - `GET /api/tags` — Ollama's own. Worth preferring where it answers,
+ *    because it distinguishes a local model from a `:cloud` one and reports
+ *    parameter counts, and those are the facts a person actually chooses on.
+ *  - `GET /v1/models` — the OpenAI-compatible standard. Works for ollama.com
+ *    direct, OpenRouter, vLLM, LM Studio, and anything else in that family,
+ *    but returns bare ids.
+ *
+ * Neither throws. A picker that cannot reach its endpoint shows an empty list
+ * and says so; it does not fail a page.
+ */
+import { parsePricing, type ModelPrice } from './prices.js';
+
+export interface EndpointModel {
+  /** Exactly what the API expects as a model id. */
+  id: string;
+  /** Parameter count where the endpoint reports one. */
+  size?: string;
+  /** Runs somewhere other than the endpoint's own machine (Ollama `:cloud`). */
+  remote: boolean;
+  /** Where a remote model actually runs, e.g. `https://ollama.com`. */
+  host?: string;
+  /**
+   * Per-token rates, where the endpoint publishes them (OpenRouter does).
+   *
+   * This is the only price Foreman will ever put a dollar sign on for a
+   * gateway run: it comes from the party that sends the bill. Absent means
+   * unpriced, and unpriced is left saying so — see prices.ts.
+   */
+  price?: ModelPrice;
+}
+
+export interface DiscoverOptions {
+  /** Bearer credential, for endpoints that need one to list models. */
+  apiKey?: string;
+  /** Discovery runs on page loads and preflight; it must not hang either. */
+  timeoutMs?: number;
+}
+
+async function getJson(url: string, apiKey?: string, timeoutMs = 1500): Promise<unknown | null> {
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(timeoutMs),
+    headers: apiKey ? { authorization: `Bearer ${apiKey}` } : undefined,
+  }).catch(() => null);
+  if (!res?.ok) return null;
+  return res.json().catch(() => null);
+}
+
+/** Ollama's `/api/tags`, which knows more than the OpenAI shape can express. */
+function fromOllamaTags(body: unknown): EndpointModel[] | null {
+  const models = (body as { models?: unknown })?.models;
+  if (!Array.isArray(models)) return null;
+  const out: EndpointModel[] = [];
+  for (const m of models as Array<Record<string, any>>) {
+    if (typeof m?.name !== 'string' || !m.name) continue;
+    out.push({
+      id: m.name,
+      size: m.details?.parameter_size || undefined,
+      remote: Boolean(m.remote_model),
+      host: m.remote_host || undefined,
+    });
+  }
+  return out;
+}
+
+/**
+ * The OpenAI-compatible `/v1/models` listing: ids, and rates where the
+ * endpoint volunteers them. OpenAI's own listing carries none; OpenRouter's
+ * carries a full `pricing` object per model.
+ */
+function fromOpenAiList(body: unknown): EndpointModel[] | null {
+  const data = (body as { data?: unknown })?.data;
+  if (!Array.isArray(data)) return null;
+  const out: EndpointModel[] = [];
+  for (const m of data as Array<Record<string, any>>) {
+    if (typeof m?.id !== 'string' || !m.id) continue;
+    const price = parsePricing(m.pricing);
+    out.push({ id: m.id, remote: false, ...(price ? { price } : {}) });
+  }
+  return out;
+}
+
+/**
+ * Models an OpenAI-compatible endpoint offers, or null if it cannot be
+ * reached. `baseUrl` is the host root — the same value a provider stores.
+ */
+export async function discoverModels(
+  baseUrl: string,
+  { apiKey, timeoutMs = 1500 }: DiscoverOptions = {},
+): Promise<EndpointModel[] | null> {
+  const root = baseUrl.replace(/\/+$/, '').replace(/\/v1$/, '');
+
+  const tags = fromOllamaTags(await getJson(`${root}/api/tags`, apiKey, timeoutMs));
+  // An Ollama with nothing pulled answers with an empty list, which is a real
+  // answer — fall through to /v1/models only when the probe did not apply.
+  const models = tags ?? fromOpenAiList(await getJson(`${root}/v1/models`, apiKey, timeoutMs));
+  if (!models) return null;
+
+  // Plain alphabetical. A cloud model is not a lesser option to be listed after
+  // the real ones — it is the one fast enough to direct a mission with.
+  return models.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Per-million-token rates, which is how a pricing page reads.
+ *
+ * The conversion lives here, in the one place that renders a rate for a
+ * person — prices.ts deliberately keeps the source's own per-token unit so
+ * there is exactly one factor of a million to get wrong.
+ */
+function rateLine(price: ModelPrice): string {
+  const perM = (n: number) => {
+    const v = n * 1_000_000;
+    // Sub-cent rates are real and common; rounding them to "$0.00" would say
+    // free about something that is not.
+    return v >= 1 ? `$${v.toFixed(2)}` : `$${v.toFixed(3)}`;
+  };
+  if (price.input === 0 && price.output === 0) return 'Free at this endpoint.';
+  return `${perM(price.input)} in / ${perM(price.output)} out per million tokens.`;
+}
+
+/**
+ * The picker's 0–4 cost bars, from a real rate where there is one.
+ *
+ * A rank, not a figure — the line under it carries the actual number. Banded
+ * on the output rate because output dominates what an agent run spends, and a
+ * constant guess (every remote model was "2") ranked a cheap flash model
+ * level with a flagship.
+ */
+export function costRank(m: EndpointModel): 0 | 1 | 2 | 3 | 4 {
+  if (!m.price) return m.remote ? 2 : 0;
+  const perM = m.price.output * 1_000_000;
+  if (perM === 0) return 0;
+  if (perM < 1) return 1;
+  if (perM < 5) return 2;
+  if (perM < 20) return 3;
+  return 4;
+}
+
+/** One line for a picker, naming the trade rather than ranking the options. */
+export function describeModel(m: EndpointModel): string {
+  // A published rate is the most useful thing anyone can be told about a
+  // model they are about to spend on, so it leads.
+  if (m.price) return rateLine(m.price);
+  if (m.remote) {
+    return `Runs on ${m.host ?? 'the provider’s servers'}, not this machine. ` +
+      'Fast; billed to that account, at a rate Foreman cannot see.';
+  }
+  return `Local${m.size ? ` · ${m.size}` : ''}. Free and private, but slow on long prompts.`;
+}

package/src/notify/commands.test.ts

@@ -0,0 +1,28 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { expandHome, parseCommand, projectsRoot, slug } from './commands.js';
+
+test('parseCommand: one shape per command, bot suffix tolerated, junk is null', () => {
+  assert.deepEqual(parseCommand('/help'), { cmd: 'help' });
+  assert.deepEqual(parseCommand('/start'), { cmd: 'help' });
+  assert.deepEqual(parseCommand('/projects'), { cmd: 'projects' });
+  assert.deepEqual(parseCommand('/new My Shop'), { cmd: 'new', name: 'My Shop' });
+  assert.deepEqual(parseCommand('/plan@ForemanBot test-4 add a footer\nwith links'), { cmd: 'plan', project: 'test-4', text: 'add a footer\nwith links' });
+  assert.deepEqual(parseCommand('/run lp1 ship it'), { cmd: 'run', project: 'lp1', text: 'ship it' });
+  assert.deepEqual(parseCommand('/stop'), { cmd: 'stop' });
+  assert.deepEqual(parseCommand('/stop lp1'), { cmd: 'stop', project: 'lp1' });
+  assert.equal(parseCommand('/plan test-4'), null);
+  assert.equal(parseCommand('/new'), null);
+  assert.equal(parseCommand('/dance'), null);
+  assert.equal(parseCommand('just words'), null);
+});
+
+test('slug and roots', () => {
+  assert.equal(slug('My New App!'), 'my-new-app');
+  assert.equal(slug('  ../evil  '), 'evil');
+  assert.equal(expandHome('~/Projects', '/home/a'), '/home/a/Projects');
+  assert.equal(projectsRoot(undefined, '/home/a'), '/home/a/Projects');
+  assert.equal(projectsRoot('~/Code', '/home/a'), '/home/a/Code');
+  assert.equal(projectsRoot('/srv/work', '/home/a'), '/srv/work');
+  assert.equal(projectsRoot('rel', '/home/a'), '/home/a/rel');
+});

package/src/notify/commands.ts

@@ -0,0 +1,73 @@
+/**
+ * What the linked Telegram chat can say to Foreman besides answering asks.
+ *
+ * The parser is pure and small on purpose: the phone is the least forgiving
+ * place to discover a command's shape, so every command has one shape, a
+ * `/help` lists them, and anything that is not a command is treated as talk
+ * for the planner of the project last spoken to.
+ */
+import os from 'node:os';
+import path from 'node:path';
+
+export type Command =
+  | { cmd: 'help' }
+  | { cmd: 'projects' }
+  | { cmd: 'status' }
+  | { cmd: 'new'; name: string }
+  | { cmd: 'plan'; project: string; text: string }
+  | { cmd: 'run'; project: string; text: string }
+  | { cmd: 'stop'; project?: string };
+
+/** `/plan@ForemanBot test-4 add a footer` → { cmd: 'plan', project: 'test-4', text: 'add a footer' }. */
+export function parseCommand(text: string): Command | null {
+  const m = /^\/(\w+)(?:@\w+)?(?:\s+([\s\S]*))?$/.exec(text.trim());
+  if (!m) return null;
+  const cmd = m[1].toLowerCase();
+  const rest = (m[2] ?? '').trim();
+  const split = () => {
+    const i = rest.search(/\s/);
+    return i < 0 ? [rest, ''] : [rest.slice(0, i), rest.slice(i).trim()];
+  };
+  switch (cmd) {
+    case 'help': case 'start': return { cmd: 'help' };
+    case 'projects': case 'ls': return { cmd: 'projects' };
+    case 'status': return { cmd: 'status' };
+    case 'new': return rest ? { cmd: 'new', name: rest } : null;
+    case 'plan': { const [project, t] = split(); return project && t ? { cmd: 'plan', project, text: t } : null; }
+    case 'run': { const [project, t] = split(); return project && t ? { cmd: 'run', project, text: t } : null; }
+    case 'stop': return { cmd: 'stop', ...(rest ? { project: rest } : {}) };
+    default: return null;
+  }
+}
+
+/** A folder name from whatever was typed: `My New App!` → `my-new-app`. */
+export function slug(name: string): string {
+  return name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').slice(0, 64);
+}
+
+/** `~/Projects` → `/Users/me/Projects`; absolute paths pass through. */
+export function expandHome(p: string, home = os.homedir()): string {
+  if (p === '~') return home;
+  if (p.startsWith('~/')) return path.join(home, p.slice(2));
+  return p;
+}
+
+/** The projects root: Settings → Projects → "Projects root", else `~/Projects`. */
+export function projectsRoot(settingsRoot: unknown, home = os.homedir()): string {
+  const v = typeof settingsRoot === 'string' && settingsRoot.trim() ? settingsRoot.trim() : '~/Projects';
+  const abs = expandHome(v, home);
+  return path.isAbsolute(abs) ? abs : path.join(home, abs);
+}
+
+export const HELP_TEXT = [
+  '<b>Foreman</b> — what you can say here',
+  '',
+  '/projects — the fleet, with what is running',
+  '/status — the runs in flight and what they need',
+  '/new &lt;name&gt; — create a project under your projects root and link it',
+  '/plan &lt;project&gt; &lt;what you want&gt; — talk to that project\'s planner',
+  '/run &lt;project&gt; &lt;brief&gt; — skip the talk: start a mission at the project\'s default cap',
+  '/stop [project] — stop the planner reply in flight',
+  '',
+  'Anything else you type answers the open question, or continues the last planning conversation.',
+].join('\n');

package/src/notify/telegram.ts

@@ -0,0 +1,259 @@
+/**
+ * Telegram — the first channel, chosen because it needs no credential minted.
+ *
+ * The human creates a bot with @BotFather and pastes its token; Foreman keeps
+ * that in the secret store at 0600, like a provider key, and never returns
+ * it. Linking is a one-time code: Foreman shows `/start <code>` (and a QR of
+ * the t.me deep link that pre-fills it), the human sends it to their bot, and
+ * the chat that sent it is the one Foreman talks to. No OAuth, no public URL
+ * — updates are read by long-polling `getUpdates`, which works from a laptop
+ * behind NAT, where a webhook would not.
+ *
+ * ONE POLLER. Telegram allows a single `getUpdates` consumer per bot; two
+ * concurrent pollers get 409s and lose messages between them. So a bot has
+ * exactly one {@link TelegramBot}, which reads everything — link codes,
+ * button taps, text replies — and dispatches. Linking, answering and the
+ * transport all hang off it.
+ *
+ * Everything here swallows transport errors. A dead channel is a lost tap on
+ * the shoulder; it must never become a failed run.
+ */
+import type { Button, Transport } from '../notify.js';
+
+export const TELEGRAM_API = 'https://api.telegram.org';
+
+interface TgResponse<T> { ok: boolean; result?: T; description?: string }
+
+async function call<T>(
+  apiBase: string, token: string, method: string, body: Record<string, unknown>, timeoutMs = 15_000,
+): Promise<T | null> {
+  try {
+    const r = await fetch(`${apiBase}/bot${token}/${method}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const j = await r.json().catch(() => null) as TgResponse<T> | null;
+    return j?.ok ? (j.result as T) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The bot's own identity, used to validate a pasted token and to show whose bot this is. */
+export async function getMe(token: string, apiBase = TELEGRAM_API): Promise<{ username: string } | null> {
+  const me = await call<{ username?: string }>(apiBase, token, 'getMe', {}, 8_000);
+  return me?.username ? { username: me.username } : null;
+}
+
+const keyboard = (buttons?: Button[][]) => buttons?.length
+  ? { reply_markup: { inline_keyboard: buttons.map((row) => row.map((b) => ({ text: b.label, callback_data: b.data.slice(0, 64) }))) } }
+  : {};
+
+/** A Telegram chat as a Transport. HTML parse mode; previews off so links stay one line. */
+export function telegramTransport(token: string, chatId: string, apiBase = TELEGRAM_API): Transport {
+  return {
+    name: 'telegram',
+    async send(text, opts) {
+      const m = await call<{ message_id: number }>(apiBase, token, 'sendMessage', {
+        chat_id: chatId, text, parse_mode: 'HTML', disable_web_page_preview: true, ...keyboard(opts?.buttons),
+      });
+      return m ? String(m.message_id) : null;
+    },
+    async edit(id, text, opts) {
+      // No reply_markup in the body means Telegram removes the keyboard — an
+      // answered question offers nothing to tap.
+      await call(apiBase, token, 'editMessageText', {
+        chat_id: chatId, message_id: Number(id), text, parse_mode: 'HTML', disable_web_page_preview: true,
+        ...(opts?.buttons ? keyboard(opts.buttons) : { reply_markup: { inline_keyboard: [] } }),
+      });
+    },
+  };
+}
+
+/**
+ * The deep link that opens the bot with `/start <code>` pre-filled.
+ *
+ * Telegram delivers the `start` payload as exactly the message the poller
+ * waits for, so a QR of this URL turns linking into one scan and one tap —
+ * no typing a code on a phone. Only the bot's username is public here; the
+ * code is single-use and expires, which is why it is safe on a screen.
+ */
+/** The "/" menu on the phone. Registered on every start, so the list is never behind the code. */
+export const BOT_COMMANDS: Array<{ command: string; description: string }> = [
+  { command: 'projects', description: 'The fleet, with what is running' },
+  { command: 'status', description: 'Runs in flight, spend, what needs you' },
+  { command: 'new', description: 'Create a project: /new <name>' },
+  { command: 'plan', description: 'Talk to a planner: /plan <project> <what you want>' },
+  { command: 'run', description: 'Skip the talk: /run <project> <brief>' },
+  { command: 'stop', description: 'Stop the planner reply in flight' },
+  { command: 'help', description: 'What you can say here' },
+];
+
+export async function setBotCommands(token: string, apiBase = TELEGRAM_API): Promise<boolean> {
+  try { await call(apiBase, token, 'setMyCommands', { commands: BOT_COMMANDS }, 10_000); return true; }
+  catch { return false; }
+}
+
+export function telegramStartLink(bot: string, code: string): string {
+  return `https://t.me/${bot.replace(/^@/, '')}?start=${encodeURIComponent(code)}`;
+}
+
+/** Six characters from an alphabet with no look-alikes: typed on a phone, read off a screen. */
+export function linkCode(): string {
+  const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+  let out = '';
+  for (let i = 0; i < 6; i++) out += alphabet[Math.floor(Math.random() * alphabet.length)];
+  return out;
+}
+
+export interface LinkedChat {
+  chatId: string;
+  /** Who linked: a username or first name, for the Settings panel to show. */
+  label: string;
+}
+
+interface TgUpdate {
+  update_id: number;
+  message?: {
+    message_id: number; text?: string;
+    chat: { id: number; username?: string; first_name?: string; title?: string };
+    reply_to_message?: { message_id: number };
+  };
+  callback_query?: {
+    id: string; data?: string;
+    from: { id: number };
+    message?: { message_id: number; chat: { id: number } };
+  };
+}
+
+export interface BotHandlers {
+  /** A tap on an inline button, from the linked chat only. */
+  onCallback?: (data: string, messageId: string) => void;
+  /** A text message, from the linked chat only. */
+  onText?: (text: string, replyToMessageId?: string) => void;
+}
+
+/**
+ * The one reader of a bot's updates.
+ *
+ * `linkedChatId` is the only chat whose taps and texts are dispatched; a
+ * message from anyone else is dropped unless it is a `/start <code>` for a
+ * code currently being waited on — the only way in, and it needs the code
+ * shown on the human's own screen.
+ */
+export class TelegramBot {
+  private stopped = false;
+  private offset: number | undefined;
+  private links = new Map<string, { resolve: (c: LinkedChat) => void; deadline: number }>();
+  private running: Promise<void> | null = null;
+
+  constructor(
+    private readonly token: string,
+    private readonly apiBase = TELEGRAM_API,
+    public linkedChatId: string | null = null,
+    private handlers: BotHandlers = {},
+  ) {}
+
+  setHandlers(h: BotHandlers): void { this.handlers = h; }
+
+  /** Begin polling; idempotent. */
+  start(): void {
+    if (this.running) return;
+    this.stopped = false;
+    this.running = this.loop().finally(() => { this.running = null; });
+  }
+
+  /**
+   * Stop reading, and tell Telegram what was consumed. Without the final
+   * zero-timeout `getUpdates` carrying the advanced offset, the next reader
+   * on this token would be handed the same updates again — a link code that
+   * already linked, a tap that already resolved.
+   */
+  async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.offset !== undefined) {
+      await call(this.apiBase, this.token, 'getUpdates', { offset: this.offset, timeout: 0 }, 5_000);
+    }
+  }
+
+  /**
+   * Wait for `/start <code>`; resolves with the chat that sent it, or null at
+   * the deadline. Several codes may wait at once; the newest one from the
+   * Settings panel is the one the human sees, and an old code someone else
+   * happened to have still only links if it has not expired.
+   */
+  link(code: string, maxMs = 10 * 60_000): { done: Promise<LinkedChat | null>; abort(): void } {
+    let settle: (c: LinkedChat | null) => void = () => {};
+    const done = new Promise<LinkedChat | null>((r) => { settle = r; });
+    const key = code.toLowerCase();
+    this.links.set(key, { resolve: (c) => { this.links.delete(key); settle(c); }, deadline: Date.now() + maxMs });
+    const timer = setTimeout(() => { if (this.links.delete(key)) settle(null); }, maxMs);
+    (timer as { unref?: () => void }).unref?.();
+    this.start();
+    return { done, abort: () => { if (this.links.delete(key)) settle(null); clearTimeout(timer); } };
+  }
+
+  private async loop(): Promise<void> {
+    while (!this.stopped) {
+      const updates = await call<TgUpdate[]>(this.apiBase, this.token, 'getUpdates', {
+        timeout: 25, offset: this.offset, allowed_updates: ['message', 'callback_query'],
+      }, 35_000);
+      if (this.stopped) return;
+      if (!updates) { await new Promise((r) => setTimeout(r, 2_000)); continue; }
+      for (const u of updates) {
+        this.offset = u.update_id + 1;
+        try { await this.dispatch(u); } catch { /* one bad update must not stop the reader */ }
+      }
+    }
+  }
+
+  private async dispatch(u: TgUpdate): Promise<void> {
+    if (u.callback_query) {
+      const cq = u.callback_query;
+      const chat = String(cq.message?.chat.id ?? cq.from.id);
+      // Always acknowledge, so the phone's spinner stops — even for a tap we
+      // then ignore because it came from a chat that is not the linked one.
+      await call(this.apiBase, this.token, 'answerCallbackQuery', { callback_query_id: cq.id }, 5_000);
+      if (this.linkedChatId && chat === this.linkedChatId && cq.data) {
+        this.handlers.onCallback?.(cq.data, String(cq.message?.message_id ?? ''));
+      }
+      return;
+    }
+    const m = u.message;
+    if (!m) return;
+    const chat = String(m.chat.id);
+    const text = (m.text ?? '').trim();
+
+    const start = /^\/start(?:@\w+)?\s+(\S+)/i.exec(text);
+    if (start) {
+      const want = this.links.get(start[1].toLowerCase());
+      if (want && want.deadline > Date.now()) {
+        this.linkedChatId = chat;
+        want.resolve({ chatId: chat, label: m.chat.username ? `@${m.chat.username}` : (m.chat.first_name ?? m.chat.title ?? chat) });
+      }
+      return;
+    }
+    if (this.linkedChatId && chat === this.linkedChatId && text) {
+      this.handlers.onText?.(text, m.reply_to_message ? String(m.reply_to_message.message_id) : undefined);
+    }
+  }
+}
+
+/**
+ * Compatibility: wait for a link code with a poller of its own. Only for a
+ * bot that has no running {@link TelegramBot} — two pollers on one token
+ * conflict. The server uses `bot.link(code)` instead.
+ */
+export function linkByCode(
+  token: string, code: string,
+  opts: { apiBase?: string; maxMs?: number } = {},
+): { done: Promise<LinkedChat | null>; abort(): void } {
+  const bot = new TelegramBot(token, opts.apiBase ?? TELEGRAM_API);
+  const l = bot.link(code, opts.maxMs);
+  // The ack is awaited before `done` resolves, so a caller that starts a new
+  // reader right after is not handed the code message again.
+  const done = l.done.then(async (c) => { await bot.stop(); return c; });
+  return { done, abort: () => { l.abort(); void bot.stop(); } };
+}