threadwire 0.1.26 → 0.1.28

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+- Add an optional loopback-only TensorBuzz-to-Telegram queue bridge. It verifies
+  bounded raw-body HMAC-SHA-256 requests before JSON parsing, admits a closed
+  `build_group.completed` schema, builds a bounded canonical `/queue` prompt,
+  and routes through a reviewed read-only event-class mapping. A dedicated
+  MTProto user sender uses durable `node:sqlite` receipts, stable send random
+  IDs, per-topic FIFO, classified transient retry, audit state, and persisted
+  Telegram message IDs. The profile-gated container receives only its dedicated
+  secret files and includes liveness/readiness endpoints plus activation,
+  rotation, revocation, pause, and rollback documentation.
+
+- Require `THREADWIRE_KIMI_E2E_OUTER_BROKER_HOST` for
+  `npm run test:kimi-isolated-runtime-e2e`, publish the outer broker on a
+  Docker-assigned host port, and verify that exact endpoint from a task-DinD
+  container before launching the isolated runtime.
+
 - Enforce per-run worker mutation boundaries in isolated runtime. `threadwire run
   --relay-write` accepts a closed `--mutation-policy <json>` with
   `{worktreeEdit, commit, push, githubWrite}` booleans; omitted capabilities

package/bin/tensorbuzz-queue-bridge.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// @ts-check
+
+import {loadBridgeConfig} from "../src/tensorbuzz-queue-bridge/config.js"
+import {TeleprotoUserSender} from "../src/tensorbuzz-queue-bridge/mtproto-sender.js"
+import {TensorBuzzQueueBridgeService} from "../src/tensorbuzz-queue-bridge/service.js"
+
+const config = await loadBridgeConfig(process.env)
+const sender = await TeleprotoUserSender.connect(config)
+const service = new TensorBuzzQueueBridgeService({...config, sender})
+await service.listen(config.host, config.port)
+
+let stopping = false
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.once(signal, () => {
+    if (stopping) return
+    stopping = true
+    void service.close().then(() => sender.close()).then(() => process.exit(0), (error) => {
+      process.stderr.write(`TensorBuzz queue bridge shutdown failed: ${error instanceof Error ? error.message : "unknown error"}\n`)
+      process.exit(1)
+    })
+  })
+}

package/docker/tensorbuzz-queue-bridge-healthcheck.mjs

@@ -0,0 +1,3 @@
+const port = process.env.THREADWIRE_TENSORBUZZ_PORT ?? "8790"
+const response = await fetch(`http://127.0.0.1:${port}/readyz`, {signal: AbortSignal.timeout(2_000)})
+if (!response.ok) process.exitCode = 1

package/docs/isolated-provider-runtime.md

@@ -315,7 +315,19 @@ state makes health and preflight fail closed with redacted errors.
 ### Kimi validation and rollback
 
 Run `npm run test:kimi-isolated-runtime-e2e` from an approved Docker supervisor
-boundary after supplying the documented immutable image variables. A real
+boundary after supplying the documented immutable image variables and an
+explicit outer broker address:
+
+```sh
+THREADWIRE_KIMI_E2E_OUTER_BROKER_HOST='<outer-host-ipv4>' \
+  npm run test:kimi-isolated-runtime-e2e
+```
+
+Replace `<outer-host-ipv4>` with an IPv4 address on the outer Docker host that
+the outer daemon can bind and containers created by the task DinD can reach.
+The E2E asks Docker to allocate the published broker host port, inspects that
+exact binding, and probes it from a throwaway task-DinD container; do not infer
+the address from a default gateway or reserve a fixed host port. A real
 account smoke must then cover fresh execution, capture of exactly one native
 session ID, exact resume with that ID, an approved non-default alias if used,
 Telegram DM/topic routing, cancellation, and confirmation that service logs and

package/docs/tensorbuzz-queue-bridge.md

@@ -0,0 +1,133 @@
+# TensorBuzz queue bridge
+
+The optional `threadwire-tensorbuzz-queue-bridge` service admits one closed
+TensorBuzz event class, durably records it, and sends a real MTProto **user**
+message to a statically reviewed Telegram destination. Its only outbound text is
+`/queue <canonical prompt>`. Event payloads cannot select a route, sender,
+method, command, or arbitrary prompt fields.
+
+The bridge is deliberately separate from Telegram bot ingress and from worker
+execution. It does not synthesize Telegram updates, call a Hermes API or
+adapter, impersonate another Telegram user, or execute queued work itself.
+
+## Security and delivery model
+
+- HTTP binds only to IPv4 loopback (`127.0.0.1`, default port `8790`). Compose
+  uses host networking so a host-local TensorBuzz webhook producer can reach
+  that loopback socket without publishing it externally.
+- `POST /webhook` accepts at most 65,536 raw bytes. The lowercase-hex
+  HMAC-SHA-256 over `<unix-seconds>.<exact raw body>` is checked before JSON
+  parsing. Required headers are `X-Webhook-Timestamp`,
+  `X-TensorBuzz-Delivery`, and `X-Webhook-Signature-V2`. Timestamps have a
+  five-minute freshness window. Delivery IDs use a bounded 128-character
+  identifier for durable idempotency only and are not part of the signature.
+- Only `build_group.completed` is accepted. Its exact fields are `event`,
+  `project`, `buildGroupId`, `status`, `commitSha`, `branch`, and `summary`;
+  values are bounded and controls/newlines are rejected. Unknown or missing
+  fields fail closed.
+- The reviewed route file must contain exactly one mapping:
+
+  ```json
+  {
+    "build_group.completed": {
+      "chatId": "-100REVIEWED_SUPERGROUP_ID",
+      "messageThreadId": 123
+    }
+  }
+  ```
+
+  Replace both example values. Review this file like code and mount it
+  read-only; never derive it from a webhook payload.
+- Built-in `node:sqlite` stores receipts, a bounded audit ledger, a stable
+  MTProto `randomId`, retry state, and the returned Telegram message ID. Startup
+  resumes an interrupted send with the same `randomId`, allowing Telegram's
+  MTProto idempotency to prevent a second message if the process stopped after
+  Telegram accepted the first send but before SQLite recorded it. Topic order
+  is FIFO. Only structured flood-wait and transport failures retry; other
+  failures become terminal and surface.
+- `GET /healthz` is liveness. `GET /readyz` becomes ready only after the
+  authorized MTProto client, SQLite store, and loopback listener are active.
+
+## Install and provision
+
+Create four root/operator-readable files outside the repository and one
+reviewed non-secret route file. Do not put their contents in shell exports,
+Compose values, source, images, logs, prompts, or command output:
+
+- webhook HMAC secret (at least 32 random bytes);
+- Telegram API ID;
+- Telegram API hash;
+- serialized Teleproto user session;
+- reviewed route JSON shown above.
+
+Provision the serialized session interactively outside this service, using a
+dedicated automation Telegram user. Phone number and 2FA password are
+provisioning inputs only and must not be stored in this repository, Compose, or
+the runtime container. Give that user access only to the reviewed destination.
+
+Set only file paths in the operator environment:
+
+```sh
+THREADWIRE_TENSORBUZZ_WEBHOOK_SECRET_FILE=/secure/threadwire/tensorbuzz-hmac
+THREADWIRE_MTPROTO_API_ID_FILE=/secure/threadwire/mtproto-api-id
+THREADWIRE_MTPROTO_API_HASH_FILE=/secure/threadwire/mtproto-api-hash
+THREADWIRE_MTPROTO_SESSION_FILE=/secure/threadwire/mtproto-session
+THREADWIRE_TENSORBUZZ_ROUTES_FILE=/secure/threadwire/tensorbuzz-routes.json
+export THREADWIRE_TENSORBUZZ_WEBHOOK_SECRET_FILE THREADWIRE_MTPROTO_API_ID_FILE
+export THREADWIRE_MTPROTO_API_HASH_FILE THREADWIRE_MTPROTO_SESSION_FILE
+export THREADWIRE_TENSORBUZZ_ROUTES_FILE
+```
+
+These variables contain paths, not credentials. Build without activating:
+
+```sh
+docker compose --profile tensorbuzz-queue-bridge build tensorbuzz-queue-bridge
+```
+
+## Activate and verify
+
+Start only after the route and dedicated user access have been reviewed:
+
+```sh
+docker compose --profile tensorbuzz-queue-bridge up --detach tensorbuzz-queue-bridge
+docker compose --profile tensorbuzz-queue-bridge exec -T tensorbuzz-queue-bridge \
+  node docker/tensorbuzz-queue-bridge-healthcheck.mjs
+```
+
+Configure TensorBuzz to POST to `http://127.0.0.1:8790/webhook` with the signing
+contract above. Never place the shared HMAC secret in the URL.
+
+## Rotate, revoke, pause, and roll back
+
+HMAC rotation is a coordinated cutover: pause TensorBuzz delivery, atomically
+replace the secret file, recreate the bridge, update TensorBuzz's signer, then
+resume and verify readiness. There is intentionally no old-secret fallback.
+
+MTProto rotation uses a newly provisioned session for the same dedicated user:
+pause delivery, atomically replace the session file, recreate, verify readiness,
+then revoke the old Telegram session in Telegram's active-sessions control.
+Rotate API hash files with the same pause/recreate/readiness sequence.
+
+To revoke immediately, pause TensorBuzz delivery and stop the profile service,
+then revoke the dedicated Telegram session and remove its destination access.
+Keep the SQLite volume for audit and idempotent recovery unless its retention
+policy explicitly authorizes deletion.
+
+To pause without revocation:
+
+```sh
+docker compose --profile tensorbuzz-queue-bridge stop tensorbuzz-queue-bridge
+```
+
+For rollback, keep TensorBuzz paused, select the prior immutable Threadwire
+image, recreate the bridge against the existing SQLite volume, verify
+`/readyz`, then resume. Do not roll back the database by deleting or replacing
+the volume; retained receipts are what prevent duplicate sends.
+
+## Live-proof blocker
+
+Automated tests use only an injected fake MTProto sender. Live end-to-end proof
+is blocked until a dedicated automation Telegram user is provisioned with its
+own MTProto session and access to the reviewed destination chat/topic. No
+production Telegram session, phone number, 2FA secret, API hash, or message was
+used while implementing this service.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadwire",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "Stream Codex, Claude, Kimi Code, and OpenCode worker progress to an explicit Telegram destination",
   "keywords": [
     "ai-agent",
@@ -17,6 +17,7 @@
   "files": [
     "CHANGELOG.md",
     "bin/",
+    "docker/tensorbuzz-queue-bridge-healthcheck.mjs",
     "docs/",
     "scripts/",
     "src/",
@@ -26,6 +27,7 @@
     "threadwire-isolated-runtime": "bin/isolated-runtime.js",
     "threadwire-kimi-model-broker": "bin/kimi-model-broker.js",
     "threadwire-model-broker": "bin/model-broker.js",
+    "threadwire-tensorbuzz-queue-bridge": "bin/tensorbuzz-queue-bridge.js",
     "threadwire": "bin/threadwire.js",
     "threadwire-telegram-webhook": "bin/telegram-webhook.js"
   },
@@ -69,5 +71,10 @@
     "release-patch": "1.0.3",
     "typescript": "6.0.2"
   },
-  "license": "AGPL-3.0-only"
+  "license": "AGPL-3.0-only",
+  "dependencies": {
+    "big-integer": "1.6.52",
+    "teleproto": "1.228.5",
+    "typanic": "1.0.9"
+  }
 }

package/scripts/seed-production-package-cache.js

@@ -0,0 +1,32 @@
+// @ts-check
+
+import {execFile} from "node:child_process"
+import {promisify} from "node:util"
+
+const execFileAsync = promisify(execFile)
+
+export const PRODUCTION_PACKAGE_SPECS = Object.freeze([
+  "big-integer@1.6.52",
+  "graceful-fs@4.2.11",
+  "imurmurhash@0.1.4",
+  "ip-address@10.5.0",
+  "mime@3.0.0",
+  "node-localstorage@2.2.1",
+  "slide@1.1.6",
+  "smart-buffer@4.2.0",
+  "socks@2.8.9",
+  "store2@2.14.4",
+  "teleproto@1.228.5",
+  "typanic@1.0.9",
+  "write-file-atomic@1.3.4"
+])
+
+/** @param {string} cacheDirectory @param {NodeJS.ProcessEnv} environment */
+export async function seedProductionPackageCache(cacheDirectory, environment) {
+  for (const packageSpec of PRODUCTION_PACKAGE_SPECS) {
+    await execFileAsync("npm", ["cache", "add", "--cache", cacheDirectory, packageSpec], {
+      env: environment,
+      maxBuffer: 10 * 1024 * 1024
+    })
+  }
+}

package/scripts/verify-package.js

@@ -6,6 +6,7 @@ import {mkdtemp, rm} from "node:fs/promises"
 import {tmpdir} from "node:os"
 import {join} from "node:path"
 import {promisify} from "node:util"
+import {seedProductionPackageCache} from "./seed-production-package-cache.js"
 
 const execFileAsync = promisify(execFile)
 const npmEnvironment = {
@@ -24,6 +25,7 @@ const EXPECTED_FILES = [
   "bin/isolated-runtime.js",
   "bin/kimi-model-broker.js",
   "bin/model-broker.js",
+  "bin/tensorbuzz-queue-bridge.js",
   "docs/capacity-admission.md",
   "docs/card-10520-plan.md",
   "docs/container-runtime.md",
@@ -31,6 +33,8 @@ const EXPECTED_FILES = [
   "docs/development-container.md",
   "docs/evidence-artifacts.md",
   "docs/isolated-provider-runtime.md",
+  "docs/tensorbuzz-queue-bridge.md",
+  "docker/tensorbuzz-queue-bridge-healthcheck.mjs",
   "package.json",
   "scripts/atomic-install.js",
   "scripts/install-local-launcher.js",
@@ -39,6 +43,7 @@ const EXPECTED_FILES = [
   "scripts/provider-shims/codex.adapter.sh",
   "scripts/provider-shims/front-door.sh.template",
   "scripts/provider-shims/opencode-local-fleet.adapter.sh",
+  "scripts/seed-production-package-cache.js",
   "scripts/verify-package.js",
   "src/absolute-deadline.js",
   "src/activity-log.js",
@@ -89,6 +94,11 @@ const EXPECTED_FILES = [
   "src/telegram-ingress/http.js",
   "src/telegram-ingress/update-guard.js",
   "src/telegram-webhook.js",
+  "src/tensorbuzz-queue-bridge/bridge.js",
+  "src/tensorbuzz-queue-bridge/config.js",
+  "src/tensorbuzz-queue-bridge/http.js",
+  "src/tensorbuzz-queue-bridge/mtproto-sender.js",
+  "src/tensorbuzz-queue-bridge/service.js",
   "src/threadwire-binding.js",
   "src/types.js",
   "src/worker-control.js"
@@ -121,6 +131,7 @@ async function main() {
     )
 
     const tarballPath = join(temporaryDirectory, packResult.filename)
+    await seedProductionPackageCache(cacheDirectory, npmEnvironment)
     const {stdout: helpOutput} = await execFileAsync("npm", [
       "exec",
       "--dry-run=false",

package/src/tensorbuzz-queue-bridge/bridge.js

@@ -0,0 +1,249 @@
+// @ts-check
+
+import {randomBytes} from "node:crypto"
+import {DatabaseSync} from "node:sqlite"
+import {forcedInteger, forcedString} from "typanic"
+
+const EVENT_FIELDS = Object.freeze(["branch", "buildGroupId", "commitSha", "event", "project", "status", "summary"])
+const STATUSES = new Set(["passed", "failed", "cancelled"])
+
+/**
+ * @typedef {{chatId: string, messageThreadId: number}} Route
+ * @typedef {{chatId: string, messageThreadId: number, text: string, randomId: string}} OutboundMessage
+ * @typedef {{sendMessage: (message: OutboundMessage) => Promise<{messageId: number}>}} MtProtoSender
+ */
+
+export class TensorBuzzQueueBridge {
+  /** @type {DatabaseSync} */
+  #database
+  /** @type {Readonly<Record<string, Route>>} */
+  #routes
+  /** @type {MtProtoSender} */
+  #sender
+  /** @type {() => number} */
+  #now
+
+  /** @param {{databasePath: string, routes: Readonly<Record<string, Route>>, sender: MtProtoSender, now?: () => number}} options */
+  constructor(options) {
+    this.#routes = options.routes
+    this.#sender = options.sender
+    this.#now = options.now ?? Date.now
+    this.#database = new DatabaseSync(options.databasePath)
+    this.#database.exec("PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL; PRAGMA busy_timeout = 5000")
+    this.#database.exec(`
+      CREATE TABLE IF NOT EXISTS receipts (
+        delivery_id TEXT PRIMARY KEY,
+        event_class TEXT NOT NULL,
+        topic_key TEXT NOT NULL,
+        chat_id TEXT NOT NULL,
+        message_thread_id INTEGER NOT NULL,
+        prompt TEXT NOT NULL,
+        random_id TEXT NOT NULL UNIQUE,
+        state TEXT NOT NULL CHECK (state IN ('pending', 'sending', 'sent', 'failed')),
+        attempts INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at INTEGER NOT NULL,
+        telegram_message_id INTEGER,
+        last_error_class TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS audit (
+        id INTEGER PRIMARY KEY,
+        delivery_id TEXT NOT NULL,
+        action TEXT NOT NULL,
+        at INTEGER NOT NULL,
+        detail TEXT,
+        FOREIGN KEY (delivery_id) REFERENCES receipts(delivery_id)
+      );
+    `)
+    const now = this.#now()
+    this.#database.prepare("UPDATE receipts SET state = 'pending', next_attempt_at = ?, updated_at = ? WHERE state = 'sending'").run(now, now)
+  }
+
+  /** @param {unknown} candidate @param {string} deliveryId */
+  acceptEvent(candidate, deliveryId) {
+    const event = validateEvent(candidate)
+    if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(deliveryId)) throw new Error("Invalid delivery ID")
+    const route = this.#routes[event.event]
+    if (!route) throw new Error(`Unreviewed event class: ${event.event}`)
+    const prompt = canonicalPrompt(event)
+    const now = this.#now()
+    const randomId = randomBytes(8).readBigInt64BE().toString()
+    this.#database.exec("BEGIN IMMEDIATE")
+    try {
+      const result = this.#database.prepare(`
+        INSERT OR IGNORE INTO receipts
+          (delivery_id, event_class, topic_key, chat_id, message_thread_id, prompt, random_id, state, next_attempt_at, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?)
+      `).run(deliveryId, event.event, `${route.chatId}:${route.messageThreadId}`, route.chatId, route.messageThreadId, prompt, randomId, now, now, now)
+      if (result.changes === 1) {
+        this.#database.prepare("INSERT INTO audit (delivery_id, action, at) VALUES (?, 'accepted', ?)").run(deliveryId, now)
+      } else {
+        const existing = this.#database.prepare("SELECT event_class, chat_id, message_thread_id, prompt FROM receipts WHERE delivery_id = ?").get(deliveryId)
+        if (!existing ||
+            forcedString(existing.event_class, "stored event_class") !== event.event ||
+            forcedString(existing.chat_id, "stored chat_id") !== route.chatId ||
+            forcedInteger(existing.message_thread_id, "stored message_thread_id") !== route.messageThreadId ||
+            forcedString(existing.prompt, "stored prompt") !== prompt) {
+          throw new Error("Authenticated delivery ID conflict")
+        }
+      }
+      this.#database.exec("COMMIT")
+      return result.changes === 1
+    } catch (error) {
+      this.#database.exec("ROLLBACK")
+      throw error
+    }
+  }
+
+  async drainOnce() {
+    const now = this.#now()
+    const candidate = this.#database.prepare(`
+      SELECT r.* FROM receipts r
+      WHERE r.state = 'pending' AND r.next_attempt_at <= ?
+        AND NOT EXISTS (
+          SELECT 1 FROM receipts earlier
+          WHERE earlier.topic_key = r.topic_key AND earlier.state IN ('pending', 'sending')
+            AND earlier.rowid < r.rowid
+        )
+      ORDER BY r.created_at, r.rowid LIMIT 1
+    `).get(now)
+    if (!candidate) return false
+    const row = readQueuedReceipt(candidate)
+    this.#database.exec("BEGIN IMMEDIATE")
+    try {
+      const claimed = this.#database.prepare("UPDATE receipts SET state = 'sending', attempts = attempts + 1, updated_at = ? WHERE delivery_id = ? AND state = 'pending'").run(now, row.deliveryId)
+      if (claimed.changes !== 1) {
+        this.#database.exec("ROLLBACK")
+        return false
+      }
+      this.#database.prepare("INSERT INTO audit (delivery_id, action, at) VALUES (?, 'sending', ?)").run(row.deliveryId, now)
+      this.#database.exec("COMMIT")
+    } catch (error) {
+      this.#database.exec("ROLLBACK")
+      throw error
+    }
+
+    try {
+      const result = await this.#sender.sendMessage({
+        chatId: row.chatId,
+        messageThreadId: row.messageThreadId,
+        text: `/queue ${row.prompt}`,
+        randomId: row.randomId
+      })
+      this.#finish(row.deliveryId, "sent", result.messageId, null, now)
+      return true
+    } catch (error) {
+      const retry = classifyTransient(error)
+      if (retry) {
+        const retryAt = now + retry.delayMs
+        this.#database.exec("BEGIN IMMEDIATE")
+        try {
+          this.#database.prepare("UPDATE receipts SET state = 'pending', next_attempt_at = ?, last_error_class = ?, updated_at = ? WHERE delivery_id = ?").run(retryAt, retry.errorClass, now, row.deliveryId)
+          this.#database.prepare("INSERT INTO audit (delivery_id, action, at, detail) VALUES (?, 'retry', ?, ?)").run(row.deliveryId, now, retry.errorClass)
+          this.#database.exec("COMMIT")
+        } catch (databaseError) {
+          this.#database.exec("ROLLBACK")
+          throw databaseError
+        }
+        return false
+      }
+      this.#finish(row.deliveryId, "failed", null, "permanent", now)
+      throw error
+    }
+  }
+
+  /** @param {string} deliveryId */
+  receipt(deliveryId) {
+    const row = this.#database.prepare("SELECT state, telegram_message_id FROM receipts WHERE delivery_id = ?").get(deliveryId)
+    if (!row) return null
+    const state = forcedString(row.state, "receipt state")
+    if (state !== "pending" && state !== "sending" && state !== "sent" && state !== "failed") throw new Error("Receipt has invalid state")
+    const telegramMessageId = row.telegram_message_id === null ? null : forcedInteger(row.telegram_message_id, "receipt telegram_message_id")
+    return {state, telegramMessageId}
+  }
+
+  close() {
+    this.#database.close()
+  }
+
+  /** @param {string} deliveryId @param {"sent" | "failed"} state @param {number | null} messageId @param {string | null} detail @param {number} now */
+  #finish(deliveryId, state, messageId, detail, now) {
+    this.#database.exec("BEGIN IMMEDIATE")
+    try {
+      this.#database.prepare("UPDATE receipts SET state = ?, telegram_message_id = ?, last_error_class = ?, updated_at = ? WHERE delivery_id = ?").run(state, messageId, detail, now, deliveryId)
+      this.#database.prepare("INSERT INTO audit (delivery_id, action, at, detail) VALUES (?, ?, ?, ?)").run(deliveryId, state, now, detail)
+      this.#database.exec("COMMIT")
+    } catch (error) {
+      this.#database.exec("ROLLBACK")
+      throw error
+    }
+  }
+}
+
+/** @param {Record<string, import("node:sqlite").SQLOutputValue>} row */
+function readQueuedReceipt(row) {
+  const deliveryId = forcedString(row.delivery_id, "receipt delivery_id")
+  const chatId = forcedString(row.chat_id, "receipt chat_id")
+  const messageThreadId = forcedInteger(row.message_thread_id, "receipt message_thread_id")
+  const prompt = forcedString(row.prompt, "receipt prompt")
+  const randomId = forcedString(row.random_id, "receipt random_id")
+  return {deliveryId, chatId, messageThreadId, prompt, randomId}
+}
+
+/** @param {unknown} candidate */
+function validateEvent(candidate) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate) || Object.getPrototypeOf(candidate) !== Object.prototype) {
+    throw new Error("Event must be a plain object")
+  }
+  const keys = Object.keys(candidate).sort()
+  if (keys.length !== EVENT_FIELDS.length || keys.some((key, index) => key !== EVENT_FIELDS[index])) throw new Error("Event has an unknown or missing field")
+  const record = /** @type {Record<string, unknown>} */ (candidate)
+  const event = forcedString(record.event, "event")
+  if (event !== "build_group.completed") throw new Error("Unsupported event class")
+  const project = bounded(record.project, "project", 1, 200)
+  const buildGroupId = bounded(record.buildGroupId, "buildGroupId", 1, 128)
+  const status = forcedString(record.status, "status")
+  if (!STATUSES.has(status)) throw new Error("Unsupported build status")
+  const commitSha = forcedString(record.commitSha, "commitSha")
+  if (!/^[a-f0-9]{40}$/u.test(commitSha)) throw new Error("commitSha must be a full lowercase Git SHA")
+  const branch = bounded(record.branch, "branch", 1, 200)
+  const summary = bounded(record.summary, "summary", 1, 500)
+  return {event, project, buildGroupId, status, commitSha, branch, summary}
+}
+
+/** @param {unknown} value @param {string} label @param {number} minimum @param {number} maximum */
+function bounded(value, label, minimum, maximum) {
+  const string = forcedString(value, label)
+  let hasControl = false
+  for (const character of string) {
+    const codePoint = character.codePointAt(0)
+    if (codePoint !== undefined && (codePoint < 32 || codePoint === 127)) hasControl = true
+  }
+  if (string.length < minimum || string.length > maximum || hasControl) throw new Error(`${label} has invalid length or characters`)
+  return string
+}
+
+/** @param {ReturnType<typeof validateEvent>} event */
+function canonicalPrompt(event) {
+  return [
+    "TensorBuzz build group completed",
+    `Project: ${event.project}`,
+    `Build group: ${event.buildGroupId}`,
+    `Status: ${event.status}`,
+    `Commit: ${event.commitSha}`,
+    `Branch: ${event.branch}`,
+    `Summary: ${event.summary}`
+  ].join("\n")
+}
+
+/** @param {unknown} error */
+function classifyTransient(error) {
+  if (!error || typeof error !== "object") return null
+  const record = /** @type {{errorMessage?: unknown, seconds?: unknown, code?: unknown}} */ (error)
+  if (typeof record.errorMessage === "string" && /^FLOOD_WAIT_\d+$/u.test(record.errorMessage) && Number.isSafeInteger(record.seconds) && Number(record.seconds) > 0) {
+    return {errorClass: "flood-wait", delayMs: Math.min(Number(record.seconds) * 1_000, 3_600_000)}
+  }
+  if (record.code === "ECONNRESET" || record.code === "ETIMEDOUT" || record.code === 500) return {errorClass: "transport", delayMs: 5_000}
+  return null
+}

package/src/tensorbuzz-queue-bridge/config.js

@@ -0,0 +1,61 @@
+// @ts-check
+
+import {readFile} from "node:fs/promises"
+import {isAbsolute} from "node:path"
+import {forcedInteger, forcedString} from "typanic"
+
+const LOOPBACK_HOST = "127.0.0.1"
+
+/** @param {NodeJS.ProcessEnv} environment */
+export async function loadBridgeConfig(environment) {
+  const secret = await readSecretFile(environment.THREADWIRE_TENSORBUZZ_WEBHOOK_SECRET_FILE, "THREADWIRE_TENSORBUZZ_WEBHOOK_SECRET_FILE")
+  if (Buffer.byteLength(secret) < 32) throw new Error("TensorBuzz webhook secret must contain at least 32 bytes")
+  const apiIdText = await readSecretFile(environment.THREADWIRE_MTPROTO_API_ID_FILE, "THREADWIRE_MTPROTO_API_ID_FILE")
+  if (!/^\d+$/u.test(apiIdText)) throw new Error("MTProto API ID file must contain a positive integer")
+  const apiId = Number(apiIdText)
+  if (!Number.isSafeInteger(apiId) || apiId <= 0) throw new Error("MTProto API ID must be a positive safe integer")
+  const apiHash = await readSecretFile(environment.THREADWIRE_MTPROTO_API_HASH_FILE, "THREADWIRE_MTPROTO_API_HASH_FILE")
+  const session = await readSecretFile(environment.THREADWIRE_MTPROTO_SESSION_FILE, "THREADWIRE_MTPROTO_SESSION_FILE")
+  const routesPath = requiredAbsolutePath(environment.THREADWIRE_TENSORBUZZ_ROUTES_FILE, "THREADWIRE_TENSORBUZZ_ROUTES_FILE")
+  let routes
+  try {
+    routes = parseRoutes(JSON.parse(await readFile(routesPath, "utf8")))
+  } catch (error) {
+    throw new Error("TensorBuzz routes configuration could not be loaded", {cause: error})
+  }
+  const databasePath = requiredAbsolutePath(environment.THREADWIRE_TENSORBUZZ_DATABASE_PATH, "THREADWIRE_TENSORBUZZ_DATABASE_PATH")
+  const port = environment.THREADWIRE_TENSORBUZZ_PORT === undefined ? 8790 : Number(environment.THREADWIRE_TENSORBUZZ_PORT)
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) throw new Error("THREADWIRE_TENSORBUZZ_PORT must be a valid TCP port")
+  return {host: LOOPBACK_HOST, port, secret, apiId, apiHash, session, routes, databasePath}
+}
+
+/** @param {string | undefined} path @param {string} label */
+async function readSecretFile(path, label) {
+  const value = (await readFile(requiredAbsolutePath(path, label), "utf8")).trim()
+  if (!value) throw new Error(`${label} must reference a nonempty file`)
+  return value
+}
+
+/** @param {string | undefined} value @param {string} label */
+function requiredAbsolutePath(value, label) {
+  const path = forcedString(value, label)
+  if (!isAbsolute(path)) throw new Error(`${label} must be absolute`)
+  return path
+}
+
+/** @param {unknown} candidate */
+function parseRoutes(candidate) {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate) || Object.getPrototypeOf(candidate) !== Object.prototype) throw new Error("Routes must be a plain object")
+  const keys = Object.keys(candidate)
+  if (keys.length !== 1 || keys[0] !== "build_group.completed") throw new Error("Routes must contain only build_group.completed")
+  const route = /** @type {Record<string, unknown>} */ (candidate)["build_group.completed"]
+  if (!route || typeof route !== "object" || Array.isArray(route) || Object.getPrototypeOf(route) !== Object.prototype) throw new Error("Route must be a plain object")
+  const record = /** @type {Record<string, unknown>} */ (route)
+  const routeKeys = Object.keys(record).sort()
+  if (routeKeys.join(",") !== "chatId,messageThreadId") throw new Error("Route has an unknown or missing field")
+  const chatId = forcedString(record.chatId, "route chatId")
+  if (!/^-100[1-9]\d+$/u.test(chatId)) throw new Error("Route chatId must be a Telegram supergroup ID")
+  const messageThreadId = forcedInteger(record.messageThreadId, "route messageThreadId")
+  if (messageThreadId <= 0) throw new Error("Route messageThreadId must be positive")
+  return Object.freeze({"build_group.completed": Object.freeze({chatId, messageThreadId})})
+}

package/src/tensorbuzz-queue-bridge/http.js

@@ -0,0 +1,134 @@
+// @ts-check
+
+import {createHmac, timingSafeEqual} from "node:crypto"
+
+export const MAX_BODY_BYTES = 65_536
+export const MAX_CLOCK_SKEW_SECONDS = 300
+
+/**
+ * @typedef {{sendMessage: (message: {chatId: string, messageThreadId: number, text: string, randomId: string}) => Promise<{messageId: number}>}} MtProtoSender
+ * @typedef {{secret: string, now?: () => number, sender?: MtProtoSender, acceptEvent?: (event: unknown, deliveryId: string) => Promise<void> | void, isReady?: () => boolean}} HandlerOptions
+ */
+
+/**
+ * Create the loopback bridge HTTP handler.
+ * @param {HandlerOptions} options
+ */
+export function createTensorBuzzQueueBridgeHandler(options) {
+  const now = options.now ?? Date.now
+  return (/** @type {import("node:http").IncomingMessage} */ request, /** @type {import("node:http").ServerResponse} */ response) => {
+    void handleRequest(request, response, options, now).catch(() => {
+      if (!response.headersSent) send(response, 500)
+    })
+  }
+}
+
+/**
+ * @param {import("node:http").IncomingMessage} request
+ * @param {import("node:http").ServerResponse} response
+ * @param {HandlerOptions} options
+ * @param {() => number} now
+ */
+async function handleRequest(request, response, options, now) {
+  if (request.method === "GET" && request.url === "/healthz") return send(response, 200, "ok\n")
+  if (request.method === "GET" && request.url === "/readyz") {
+    return options.isReady?.() === false ? send(response, 503, "not ready\n") : send(response, 200, "ready\n")
+  }
+  if (request.method !== "POST" || request.url !== "/webhook") return reject(request, response, 404)
+  if (request.headers["content-type"]?.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+    return reject(request, response, 415)
+  }
+
+  let rawBody
+  try {
+    rawBody = await readBoundedBody(request)
+  } catch (error) {
+    return send(response, error instanceof BodyTooLargeError ? 413 : 400)
+  }
+
+  const deliveryId = singleHeader(request.headers["x-tensorbuzz-delivery"])
+  const timestamp = singleHeader(request.headers["x-webhook-timestamp"])
+  const signature = singleHeader(request.headers["x-webhook-signature-v2"])
+  if (!deliveryId || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(deliveryId) ||
+      !timestamp || !/^\d{10}$/u.test(timestamp) ||
+      Math.abs(Math.floor(now() / 1000) - Number(timestamp)) > MAX_CLOCK_SKEW_SECONDS ||
+      !signatureMatches(options.secret, timestamp, rawBody, signature)) {
+    return send(response, 401)
+  }
+
+  let event
+  try {
+    event = JSON.parse(rawBody.toString("utf8"))
+  } catch {
+    return send(response, 400)
+  }
+  if (options.acceptEvent) await options.acceptEvent(event, deliveryId)
+  return send(response, 202)
+}
+
+/** @param {import("node:http").IncomingMessage} request */
+function readBoundedBody(request) {
+  return new Promise((resolve, reject) => {
+    /** @type {Buffer[]} */
+    const chunks = []
+    let bytes = 0
+    let settled = false
+    /** @param {Buffer | string} chunk */
+    const onData = (chunk) => {
+      if (settled) return
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      bytes += buffer.length
+      if (bytes > MAX_BODY_BYTES) {
+        settled = true
+        request.removeListener("data", onData)
+        request.removeListener("end", onEnd)
+        request.removeListener("error", onError)
+        reject(new BodyTooLargeError())
+        request.resume()
+      } else {
+        chunks.push(buffer)
+      }
+    }
+    const onEnd = () => {
+      if (settled) return
+      settled = true
+      resolve(Buffer.concat(chunks, bytes))
+    }
+    /** @param {Error} error */
+    const onError = (error) => {
+      if (settled) return
+      settled = true
+      reject(error)
+    }
+    request.on("data", onData)
+    request.once("end", onEnd)
+    request.once("error", onError)
+  })
+}
+
+class BodyTooLargeError extends Error {}
+
+/** @param {string} secret @param {string} timestamp @param {Buffer} body @param {string | null} provided */
+function signatureMatches(secret, timestamp, body, provided) {
+  if (!provided || !/^[a-f0-9]{64}$/u.test(provided)) return false
+  const expected = createHmac("sha256", secret).update(`${timestamp}.`).update(body).digest()
+  const actual = Buffer.from(provided, "hex")
+  return timingSafeEqual(expected, actual)
+}
+
+/** @param {string | string[] | undefined} value */
+function singleHeader(value) {
+  return typeof value === "string" ? value : null
+}
+
+/** @param {import("node:http").IncomingMessage} request @param {import("node:http").ServerResponse} response @param {number} status */
+function reject(request, response, status) {
+  request.resume()
+  send(response, status)
+}
+
+/** @param {import("node:http").ServerResponse} response @param {number} status @param {string} [body] */
+function send(response, status, body = "") {
+  response.writeHead(status, {"cache-control": "no-store", "content-type": "text/plain; charset=utf-8"})
+  response.end(body)
+}

package/src/tensorbuzz-queue-bridge/mtproto-sender.js

@@ -0,0 +1,61 @@
+// @ts-check
+
+import bigInteger from "big-integer"
+import {Api, TelegramClient, sessions} from "teleproto"
+
+export class TeleprotoUserSender {
+  /** @type {TelegramClient} */
+  #client
+
+  /** @param {TelegramClient} client */
+  constructor(client) {
+    this.#client = client
+  }
+
+  /** @param {{apiId: number, apiHash: string, session: string}} config */
+  static async connect(config) {
+    const client = new TelegramClient(new sessions.StringSession(config.session), config.apiId, config.apiHash, {connectionRetries: 3})
+    await client.connect()
+    if (!await client.checkAuthorization()) {
+      await client.disconnect()
+      throw new Error("The dedicated MTProto automation user session is not authorized")
+    }
+    return new TeleprotoUserSender(client)
+  }
+
+  /** @param {{chatId: string, messageThreadId: number, text: string, randomId: string}} outbound */
+  async sendMessage(outbound) {
+    const peer = await this.#client.getInputEntity(outbound.chatId)
+    const updates = await this.#client.invoke(new Api.messages.SendMessage({
+      peer,
+      message: outbound.text,
+      randomId: bigInteger(outbound.randomId),
+      replyTo: new Api.InputReplyToMessage({
+        replyToMsgId: outbound.messageThreadId,
+        topMsgId: outbound.messageThreadId
+      })
+    }))
+    const messageId = extractMessageId(updates)
+    if (messageId === null) throw new Error("MTProto send response did not contain a Telegram message ID")
+    return {messageId}
+  }
+
+  async close() {
+    await this.#client.disconnect()
+  }
+}
+
+/** @param {unknown} response */
+function extractMessageId(response) {
+  if (!response || typeof response !== "object") return null
+  const updates = /** @type {{updates?: unknown}} */ (response).updates
+  if (!Array.isArray(updates)) return null
+  for (const update of updates) {
+    if (!update || typeof update !== "object") continue
+    const message = /** @type {{message?: unknown}} */ (update).message
+    if (!message || typeof message !== "object") continue
+    const id = /** @type {{id?: unknown}} */ (message).id
+    if (Number.isSafeInteger(id) && Number(id) > 0) return Number(id)
+  }
+  return null
+}

package/src/tensorbuzz-queue-bridge/service.js

@@ -0,0 +1,72 @@
+// @ts-check
+
+import {createServer} from "node:http"
+import {TensorBuzzQueueBridge} from "./bridge.js"
+import {createTensorBuzzQueueBridgeHandler} from "./http.js"
+
+export class TensorBuzzQueueBridgeService {
+  #bridge
+  #server
+  #draining = false
+  #ready = false
+  /** @type {NodeJS.Timeout | null} */
+  #retryTimer = null
+
+  /** @param {{host: string, port: number, secret: string, databasePath: string, routes: Readonly<Record<string, {chatId: string, messageThreadId: number}>>, sender: import("./bridge.js").MtProtoSender}} options */
+  constructor(options) {
+    this.#bridge = new TensorBuzzQueueBridge(options)
+    this.#server = createServer(createTensorBuzzQueueBridgeHandler({
+      secret: options.secret,
+      sender: options.sender,
+      isReady: () => this.#ready,
+      acceptEvent: (event, deliveryId) => {
+        this.#bridge.acceptEvent(event, deliveryId)
+        this.#scheduleDrain(0)
+      }
+    }))
+  }
+
+  /** @param {string} host @param {number} port */
+  async listen(host, port) {
+    if (host !== "127.0.0.1") throw new Error("TensorBuzz queue bridge must bind IPv4 loopback")
+    await new Promise((resolve, reject) => {
+      this.#server.once("error", reject)
+      this.#server.listen(port, host, () => {
+        this.#server.removeListener("error", reject)
+        resolve(undefined)
+      })
+    })
+    this.#ready = true
+    this.#scheduleDrain(0)
+  }
+
+  async close() {
+    this.#ready = false
+    if (this.#retryTimer) clearTimeout(this.#retryTimer)
+    await new Promise((resolve, reject) => this.#server.close((error) => error ? reject(error) : resolve(undefined)))
+    this.#bridge.close()
+  }
+
+  /** @param {number} delayMs */
+  #scheduleDrain(delayMs) {
+    if (this.#draining || this.#retryTimer) return
+    this.#retryTimer = setTimeout(() => {
+      this.#retryTimer = null
+      void this.#drain()
+    }, delayMs)
+  }
+
+  async #drain() {
+    if (this.#draining) return
+    this.#draining = true
+    try {
+      let drained
+      do {
+        drained = await this.#bridge.drainOnce()
+      } while (drained)
+    } finally {
+      this.#draining = false
+      if (this.#ready) this.#scheduleDrain(1_000)
+    }
+  }
+}