@ccmsg/cli 0.1.0

package/src/transcript/index.ts

@@ -0,0 +1,16 @@
+export {
+  type AgentNames,
+  type TranscriptFile,
+  TranscriptFiles,
+  type TranscriptFilesDeps,
+} from "./files.ts";
+export {
+  NO_FACTS,
+  readRecord,
+  type TranscriptFacts,
+  TranscriptFold,
+  type TranscriptRecord,
+} from "./fold.ts";
+export { READ_LIMIT, readSlice } from "./read.ts";
+export { type Appended, FOLD_TAIL_BYTES, TranscriptTail } from "./tail.ts";
+export { Transcripts, type TranscriptsDeps } from "./transcripts.ts";

package/src/transcript/read.ts

@@ -0,0 +1,82 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import type { TranscriptReadResult, Sid } from "@ccmsg/protocol";
+import { OpError } from "../dispatch/index.ts";
+
+/** How much of a transcript one read may carry.
+ *
+ * The contract lets a caller ask for less and says the instance narrows the
+ * ask to its own limit, so this is both the ceiling and the default: a caller
+ * that states nothing gets a slice of the size the paging was designed around,
+ * and one that asks for a file's worth gets the same. It is the file-read
+ * limit, for the same reason — one connection, one bounded payload. */
+export const READ_LIMIT = 512 * 1024;
+
+/** A slice of a transcript, read backwards from an offset.
+ *
+ * Paging is by byte offset aligned to line boundaries (§3.3): the end of the
+ * file is read first, and each further page asks for what began before the
+ * slice just read. Nothing is scanned whole and no index is built, which is
+ * what lets a transcript of any size be read from its end.
+ *
+ * The offsets are the ones the `transcript` topic's frames carry, so what a
+ * client reads and what arrives live stitch together without overlap. */
+export function readSlice(
+  sid: Sid,
+  file: string,
+  before?: number,
+  maxBytes?: number,
+): TranscriptReadResult {
+  let size: number;
+  try {
+    size = statSync(file).size;
+  } catch {
+    throw new OpError("not_found", `the transcript of ${sid} could not be read`);
+  }
+  const until = before === undefined ? size : Math.min(before, size);
+  const want = Math.min(maxBytes ?? READ_LIMIT, READ_LIMIT);
+  const from = Math.max(0, until - want);
+  // One byte before what was asked for, so the read can see whether it began
+  // on a line boundary. Without it a slice starting exactly at a record's
+  // first byte is indistinguishable from one starting inside the record
+  // before it, and the whole first record would be dropped as a fragment.
+  const probe = from === 0 ? 0 : from - 1;
+  // The offsets are found in the bytes and never in decoded text. The probe
+  // byte, and a slice that begins part-way into a file, both land wherever the
+  // arithmetic puts them — inside a character as readily as before one — and
+  // decoding first would turn those bytes into replacement characters of a
+  // different length, moving every offset derived from them.
+  const bytes = slice(file, probe, until);
+  // What of the read is whole records: everything up to the last newline. A
+  // record the writer has not finished ends the file without one.
+  const lastNewline = bytes.lastIndexOf(NEWLINE);
+  if (lastNewline < 0) return { sid, lines: [], start: until, end: until, size };
+  const complete = bytes.subarray(0, lastNewline + 1);
+  const end = probe + complete.byteLength;
+  // Whatever of a record preceded `from` is dropped: empty when `from` already
+  // sat on a boundary, and the tail of a record the caller has already read
+  // otherwise. Either way the slice starts after the newline that ended it.
+  const first = probe < from ? complete.indexOf(NEWLINE) + 1 : 0;
+  const lines: string[] = [];
+  for (let at = first; at < complete.byteLength;) {
+    const newline = complete.indexOf(NEWLINE, at);
+    lines.push(complete.toString("utf8", at, newline));
+    at = newline + 1;
+  }
+  return { sid, lines, start: probe + first, end, size };
+}
+
+const NEWLINE = 0x0a;
+
+/** The bytes in a range. A range that reads short — the file was truncated
+ * between the stat and the read — yields what was actually there. */
+function slice(file: string, from: number, to: number): Buffer {
+  if (to <= from) return Buffer.alloc(0);
+  const handle = openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(to - from);
+    const read = readSync(handle, buffer, 0, buffer.length, from);
+    return buffer.subarray(0, read);
+  } finally {
+    closeSync(handle);
+  }
+}

package/src/transcript/tail.ts

@@ -0,0 +1,195 @@
+import { type FSWatcher, statSync, watch } from "node:fs";
+import { open, stat } from "node:fs/promises";
+import { CONFIRM_POLL_MS } from "../sessions/harness.ts";
+
+/** How much of an existing transcript is read when a tail starts.
+ *
+ * The fold's two values both describe the present — the error the latest turn
+ * ended on, and the last time a person spoke — so what a tail needs on opening
+ * is the recent end of the file, not its history. A megabyte is a few hundred
+ * records at the sizes the harness writes, which reaches back past the current
+ * turn by a wide margin while costing one read of fixed size however large the
+ * file has grown (§3.3: a transcript of any size is read from its end).
+ *
+ * A person who has not spoken within it is reported as having no known input
+ * rather than as having spoken long ago, which is what the contract's absent
+ * `last_user_input_at` already means. */
+export const FOLD_TAIL_BYTES = 1024 * 1024;
+
+/** What the tail found appended, with the offsets that place it.
+ *
+ * The offsets are the ones a transcript read pages by, so what arrives live
+ * and what was read stitch together without reading anything twice. `end` is
+ * past the last complete line, which is not `size` when a record is still
+ * being written. */
+export interface Appended {
+  readonly lines: readonly string[];
+  readonly start: number;
+  readonly end: number;
+  readonly size: number;
+}
+
+export interface TailDeps {
+  /** Complete lines only; a record still being written waits for its end. */
+  readonly onAppended: (appended: Appended) => void;
+  /** The end of the file as it stood when the tail opened, oldest first. The
+   * seed of the fold, not something a subscriber is sent. */
+  readonly onSeed: (lines: readonly string[]) => void;
+  /** The file is not the one the tail was reading: it shrank, so what was
+   * folded out of the old contents no longer describes it. */
+  readonly onTruncated: () => void;
+  readonly pollMs?: number;
+}
+
+/** One transcript file, followed while somebody wants it (§6.3).
+ *
+ * Watch plus a low-rate confirmation poll, for the reason and at the interval
+ * the sessions directory uses (§5.1): the watch is the route and the poll is
+ * the backstop for what a delayed FSEvents queue is still sitting on. The
+ * interval is shared rather than chosen again, so the two watches cannot
+ * drift into two different answers to the same question. */
+export class TranscriptTail {
+  #watcher: FSWatcher | undefined;
+  #timer: ReturnType<typeof setInterval> | undefined;
+  #reading: Promise<void> = Promise.resolve();
+  /** Just past the last complete line consumed. A record still being written
+   * leaves the offset before it, so the next read takes it whole rather than
+   * having to hold half of it — which also keeps a character split across two
+   * writes from being decoded in halves. */
+  #offset = 0;
+  #size = 0;
+
+  constructor(
+    private readonly path: string,
+    private readonly deps: TailDeps,
+  ) {
+    // Where the file ends, read before anything can ask. A subscription's
+    // snapshot states this and is answered in the same turn the tail is
+    // created, so a size that only the awaited seed had filled in would be
+    // reported as zero and every byte already written would look appended.
+    // Reading it here also fixes what the seed reads: the seed takes this size
+    // rather than stating a newer one, so nothing lands between the size the
+    // subscriber was given and the first frame it is sent.
+    this.#size = sizeNow(path);
+    this.#offset = this.#size;
+  }
+
+  /** The transcript's size as last observed, which is what a subscription's
+   * snapshot states and where the frames after it begin. */
+  get size(): number {
+    return this.#size;
+  }
+
+  get running(): boolean {
+    return this.#watcher !== undefined || this.#timer !== undefined;
+  }
+
+  /** Begin following, seeding the fold from the end of what is already there.
+   * Resolves once the seed has been read, so a snapshot taken after it states
+   * a size the fold has caught up with. */
+  async start(): Promise<void> {
+    if (this.running) return;
+    await this.#seed();
+    try {
+      this.#watcher = watch(this.path, () => void this.refresh());
+    } catch {
+      // The file does not exist yet — a session that has not been written to.
+      // The poll covers the wait and picks it up when it appears.
+      this.#watcher = undefined;
+    }
+    this.#timer = setInterval(() => void this.refresh(), this.deps.pollMs ?? CONFIRM_POLL_MS);
+  }
+
+  stop(): void {
+    this.#watcher?.close();
+    this.#watcher = undefined;
+    if (this.#timer !== undefined) clearInterval(this.#timer);
+    this.#timer = undefined;
+  }
+
+  /** Read what has been appended since the last read. Reads are chained rather
+   * than overlapped, so a watch event and a poll arriving together cannot
+   * interleave their reads of the same file. */
+  refresh(): Promise<void> {
+    this.#reading = this.#reading.then(() => this.#read());
+    return this.#reading;
+  }
+
+  async #seed(): Promise<void> {
+    const size = this.#size;
+    if (size === 0) return;
+    const from = Math.max(0, size - FOLD_TAIL_BYTES);
+    const text = await this.#slice(from, size);
+    const complete = whole(text);
+    this.#offset = from + byteLength(complete);
+    const lines = split(complete);
+    // The first line is half a record whenever the read began mid-file, so it
+    // is dropped: what the fold reads are whole records or nothing.
+    if (from > 0) lines.shift();
+    this.deps.onSeed(lines);
+  }
+
+  async #read(): Promise<void> {
+    const size = await this.#stat();
+    if (size < this.#offset) {
+      // Shorter than what was already consumed: the file was replaced, so what
+      // was folded out of it describes nothing, and reading resumes from its
+      // beginning.
+      this.#offset = 0;
+      this.deps.onTruncated();
+    }
+    this.#size = size;
+    if (size === this.#offset) return;
+    const complete = whole(await this.#slice(this.#offset, size));
+    if (complete.length === 0) return;
+    const start = this.#offset;
+    const end = start + byteLength(complete);
+    this.#offset = end;
+    this.deps.onAppended({ lines: split(complete), start, end, size });
+  }
+
+  async #stat(): Promise<number> {
+    try {
+      return (await stat(this.path)).size;
+    } catch {
+      // Not there. Nothing was appended, and the poll keeps looking.
+      return this.#offset;
+    }
+  }
+
+  /** The bytes in a range, as text. A range that reads short — the file was
+   * truncated between the stat and the read — yields what was actually there. */
+  async #slice(from: number, to: number): Promise<string> {
+    const handle = await open(this.path, "r").catch(() => undefined);
+    if (handle === undefined) return "";
+    try {
+      const buffer = Buffer.alloc(to - from);
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, from);
+      return buffer.subarray(0, bytesRead).toString("utf8");
+    } finally {
+      await handle.close();
+    }
+  }
+}
+
+/** What of a read is whole records: everything up to and including the last
+ * newline. A transcript ends every record with one, so what follows the last
+ * is a record the writer has not finished. */
+function whole(text: string): string {
+  const last = text.lastIndexOf("\n");
+  return last < 0 ? "" : text.slice(0, last + 1);
+}
+
+function split(complete: string): string[] {
+  return complete.split("\n").slice(0, -1);
+}
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, "utf8");
+}
+
+/** How large the file is right now, or zero for one that is not there yet.
+ * Synchronous because the value is wanted before the first await. */
+function sizeNow(path: string): number {
+  return statSync(path, { throwIfNoEntry: false })?.size ?? 0;
+}

package/src/transcript/transcripts.ts

@@ -0,0 +1,162 @@
+import type { InstanceId, Sid } from "@ccmsg/protocol";
+import { topicParam, type TopicValue, type UpstreamResource } from "../topics/index.ts";
+import { NO_FACTS, type TranscriptFacts, TranscriptFold } from "./fold.ts";
+import { type Appended, TranscriptTail } from "./tail.ts";
+
+export interface TranscriptsDeps {
+  readonly self: InstanceId;
+  /** Where a session's transcript is, as the session announced it (§5.1). A
+   * sid with no path is one that never said, and nothing is guessed for it. */
+  readonly pathOf: (sid: Sid) => string | undefined;
+  /** The one way a value reaches subscribers (§6.1). */
+  readonly publish: (topic: string, data: unknown) => void;
+  /** The fold now says something different about this session. What the fold
+   * settles is an input to the sessions domain (§5.1), so the domain that
+   * states those values is told to state them again. */
+  readonly onFacts: (sid: Sid) => void;
+  /** Overrides the confirmation poll, for a test that cannot wait. */
+  readonly pollMs?: number;
+}
+
+/** One tail and one fold per session, and the `transcript:<sid>` topic they
+ * feed (§3.3).
+ *
+ * The fold is one per session, not one per consumer: a line is read once and
+ * every value it settles is settled from that read, so the api error, the last
+ * human input and the appended bytes are three uses of one pass rather than
+ * three passes (M5).
+ *
+ * A tail runs while something wants it and stops when nothing does (§6.3).
+ * Subscription is one such want; a `hold` is the other, for the values the
+ * sessions domain states about a session nobody is watching the transcript of.
+ * They are counted together, so the last one to go is what stops the tail. */
+export class Transcripts implements UpstreamResource {
+  readonly #followed = new Map<Sid, Followed>();
+
+  constructor(private readonly deps: TranscriptsDeps) {}
+
+  // --- UpstreamResource (§6.3)
+
+  start(topic: string): void {
+    const sid = topicParam(topic);
+    if (sid !== undefined) this.hold(sid);
+  }
+
+  stop(topic: string): void {
+    const sid = topicParam(topic);
+    if (sid !== undefined) this.release(sid);
+  }
+
+  /** Where the transcript ends as the subscription begins. What follows starts
+   * there, which is the whole of the snapshot for a topic whose frames are an
+   * append rather than a value (§6.2). A session whose transcript this
+   * instance cannot find has nothing to state, and the subscriber begins at
+   * the first thing appended after one appears. */
+  snapshot(topic: string): readonly TopicValue[] {
+    const sid = topicParam(topic);
+    const followed = sid === undefined ? undefined : this.#followed.get(sid);
+    if (sid === undefined || followed === undefined) return [];
+    return [{ instance: this.deps.self, data: { sid, size: followed.tail.size } }];
+  }
+
+  /** What the fold currently says about a session. Empty for one not being
+   * followed, which is the same as a transcript that has said nothing. */
+  facts(sid: Sid): TranscriptFacts {
+    return this.#followed.get(sid)?.fold.facts ?? NO_FACTS;
+  }
+
+  /** Whether a session's transcript is being followed, which is how "the
+   * subscription drives the resource" is observable from outside. */
+  following(sid: Sid): boolean {
+    return this.#followed.get(sid)?.tail.running === true;
+  }
+
+  /** Ask for a session's transcript to be followed. Each hold is released
+   * once; the tail runs until the last is. */
+  hold(sid: Sid): void {
+    const held = this.#followed.get(sid);
+    if (held !== undefined) {
+      held.holds += 1;
+      return;
+    }
+    const path = this.deps.pathOf(sid);
+    if (path === undefined) return;
+    const followed = this.#follow(sid, path);
+    this.#followed.set(sid, followed);
+    void followed.tail.start();
+  }
+
+  release(sid: Sid): void {
+    const held = this.#followed.get(sid);
+    if (held === undefined) return;
+    held.holds -= 1;
+    if (held.holds > 0) return;
+    this.#followed.delete(sid);
+    held.tail.stop();
+    // What the fold held goes with it: the values it derived describe a file
+    // this instance is no longer reading, and stating them from memory would
+    // outlive the reading that justified them.
+    this.deps.onFacts(sid);
+  }
+
+  /** Stop following everything. What shutdown reaches through the topics it
+   * drops; a hold taken outside a subscription needs the same door. */
+  stopAll(): void {
+    const followed = new Map(this.#followed);
+    this.#followed.clear();
+    for (const [sid, entry] of followed) {
+      entry.tail.stop();
+      this.deps.onFacts(sid);
+    }
+  }
+
+  #follow(sid: Sid, path: string): Followed {
+    const fold = new TranscriptFold();
+    const followed: Followed = {
+      holds: 1,
+      fold,
+      tail: new TranscriptTail(path, {
+        onSeed: (lines) => {
+          // The end of the file as it already stood: it settles what the fold
+          // says, and it is not an append, so nothing is published for it.
+          if (foldAll(fold, lines)) this.deps.onFacts(sid);
+        },
+        onAppended: (appended) => this.#appended(sid, fold, appended),
+        onTruncated: () => {
+          fold.reset();
+          this.deps.onFacts(sid);
+        },
+        ...(this.deps.pollMs === undefined ? {} : { pollMs: this.deps.pollMs }),
+      }),
+    };
+    return followed;
+  }
+
+  /** The one pass over what was appended: the lines go to the fold and to the
+   * topic, in that order, and are not read a second time for either (M5). */
+  #appended(sid: Sid, fold: TranscriptFold, appended: Appended): void {
+    const changed = foldAll(fold, appended.lines);
+    this.deps.publish(`transcript:${sid}`, {
+      sid,
+      lines: [...appended.lines],
+      start: appended.start,
+      end: appended.end,
+      size: appended.size,
+    });
+    if (changed) this.deps.onFacts(sid);
+  }
+}
+
+interface Followed {
+  holds: number;
+  readonly fold: TranscriptFold;
+  readonly tail: TranscriptTail;
+}
+
+function foldAll(fold: TranscriptFold, lines: readonly string[]): boolean {
+  let changed = false;
+  for (const line of lines) {
+    if (fold.line(line)) changed = true;
+  }
+  return changed;
+}

package/src/translate/helper.ts

@@ -0,0 +1,87 @@
+import { accessSync, constants } from "node:fs";
+import { isAbsolute } from "node:path";
+import type { Capability } from "@ccmsg/protocol";
+import { ConfigError, type UpstreamConfig } from "../instance/config.ts";
+
+/** One exchange with the helper: a line in, a line out.
+ *
+ * The helper is a process that reads one JSON line and answers with one, and
+ * this is that process as everything above it needs to see it. Named rather
+ * than reached through directly so the wire can be exercised without a program
+ * on the host answering it. */
+export interface HelperChannel {
+  write(line: string): Promise<void>;
+  /** The next line the helper wrote, or `undefined` once it has written its
+   * last — which is how a helper that died is told from one that is thinking. */
+  read(): Promise<string | undefined>;
+  kill(): void;
+}
+
+/** Read the helper the config names (§8.2).
+ *
+ * A helper that is named and cannot be run ends the start rather than leaving
+ * translation silently off (DV-Q9): an instance without the capability looks
+ * exactly like one nobody configured, and the operator who named a program
+ * meant to have it. */
+export function translateSetup(config: UpstreamConfig, file: string): string | undefined {
+  const helper = config.translate_helper;
+  if (helper === undefined) return undefined;
+  if (!isAbsolute(helper)) {
+    throw new ConfigError(file, "upstream.translate_helper must be an absolute path");
+  }
+  try {
+    accessSync(helper, constants.X_OK);
+  } catch (cause) {
+    throw new ConfigError(
+      file,
+      `upstream.translate_helper ${helper} cannot be run (${String(cause)})`,
+    );
+  }
+  return helper;
+}
+
+/** Present exactly where a helper is configured: translation happens on this
+ * host or not at all, and a client is told which before it asks. */
+export function translateCapabilities(helper?: string): Capability[] {
+  return helper === undefined ? [] : ["translate"];
+}
+
+/** Start the configured helper, speaking one JSON line at a time. */
+export function spawnHelper(path: string): HelperChannel {
+  const child = Bun.spawn([path], { stdin: "pipe", stdout: "pipe", stderr: "inherit" });
+  const stdin = child.stdin;
+  const lines = readLines(child.stdout);
+  return {
+    write: async (line) => {
+      // The write is awaited because a full pipe answers with a promise rather
+      // than a count, and a line half-taken is a batch the helper never sees.
+      await stdin.write(line);
+      await stdin.flush();
+    },
+    read: () => lines(),
+    kill: () => {
+      child.kill();
+    },
+  };
+}
+
+/** The helper's output, one line at a time. */
+function readLines(stream: ReadableStream<Uint8Array>): () => Promise<string | undefined> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  return async () => {
+    for (;;) {
+      const at = buffer.indexOf("\n");
+      if (at >= 0) {
+        const line = buffer.slice(0, at);
+        buffer = buffer.slice(at + 1);
+        if (line.trim() !== "") return line;
+        continue;
+      }
+      const { done, value } = await reader.read();
+      if (done) return undefined;
+      buffer += decoder.decode(value, { stream: true });
+    }
+  };
+}

package/src/translate/index.ts

@@ -0,0 +1,2 @@
+export * from "./helper.ts";
+export * from "./translate.ts";

package/src/translate/translate.ts

@@ -0,0 +1,127 @@
+import type { TranslateResult, TranslateRunArgs, TranslateRunResult } from "@ccmsg/protocol";
+import { type HandlerInput, OpError } from "../dispatch/index.ts";
+import { type HelperChannel, spawnHelper } from "./helper.ts";
+
+/** How long one batch may take before the helper is assumed wedged.
+ *
+ * The deadline grows with the input because the work does: a sentence comes
+ * back in seconds and a page takes minutes. The helper reports no progress, so
+ * a batch that outlives its deadline can only be ended by ending the helper —
+ * the next call starts a fresh one. */
+const BASE_MS = 10_000;
+const PER_100_CHARS_MS = 1_000;
+const MAX_MS = 120_000;
+
+export function deadlineMs(chars: number): number {
+  return Math.min(MAX_MS, BASE_MS + Math.ceil(chars / 100) * PER_100_CHARS_MS);
+}
+
+export interface TranslateDeps {
+  /** Starts the helper. Replaced in tests, which answer the same line protocol
+   * without a program on the host. */
+  readonly start?: () => HelperChannel;
+  readonly deadlineMs?: (chars: number) => number;
+}
+
+/** The host's translator, kept running between calls.
+ *
+ * Resident because starting it is the expensive part (DR-0023 §3.1): the
+ * process loads a translation session once and answers from it, so a batch per
+ * process would pay that cost on every keystroke's worth of text. One batch is
+ * in flight at a time — the helper answers one line per line it is given, and
+ * two batches sharing that channel could not tell the answers apart. */
+export class Translate {
+  #helper: HelperChannel | undefined;
+  #queue: Promise<unknown> = Promise.resolve();
+  #next = 0;
+
+  constructor(
+    private readonly helperPath: string,
+    private readonly deps: TranslateDeps = {},
+  ) {}
+
+  async run(args: TranslateRunArgs): Promise<TranslateRunResult> {
+    // Nothing to translate needs no helper, and starting one to answer with an
+    // empty list would make the empty batch the probe it is not.
+    if (args.texts.length === 0) return { results: [] };
+    const done = this.#queue.then(
+      () => this.#exchange(args.texts),
+      () => this.#exchange(args.texts),
+    );
+    this.#queue = done.catch(() => undefined);
+    return { results: await done };
+  }
+
+  /** Stop the helper. What shutdown calls, and what a wedged batch does before
+   * it gives up. */
+  stop(): void {
+    this.#helper?.kill();
+    this.#helper = undefined;
+  }
+
+  async #exchange(texts: readonly string[]): Promise<TranslateResult[]> {
+    const helper = (this.#helper ??= (this.deps.start ?? (() => spawnHelper(this.helperPath)))());
+    const id = `${(this.#next += 1)}`;
+    const chars = texts.reduce((total, text) => total + text.length, 0);
+    const budget = (this.deps.deadlineMs ?? deadlineMs)(chars);
+    let expired: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await helper.write(`${JSON.stringify({ id, texts })}\n`);
+      const line = await Promise.race([
+        helper.read(),
+        new Promise<never>((_resolve, reject) => {
+          expired = setTimeout(() => {
+            reject(new Error(`the helper did not answer within ${budget}ms`));
+          }, budget);
+        }),
+      ]);
+      if (line === undefined) throw new Error("the helper stopped before it answered");
+      return read(line, id, texts.length);
+    } catch (cause) {
+      // Whatever went wrong, this helper is no longer known to be in step with
+      // the line protocol, so it is ended and the next call starts a fresh one.
+      this.stop();
+      throw new OpError(
+        "translate_helper_failed",
+        `the translation helper failed: ${String(cause)}`,
+      );
+    } finally {
+      if (expired !== undefined) clearTimeout(expired);
+    }
+  }
+}
+
+/** One answer line, read as the batch it was meant to answer.
+ *
+ * The id and the count are both checked: an answer to another batch, or one
+ * holding a different number of results, would hand the caller texts that are
+ * not the ones it sent. */
+function read(line: string, id: string, expected: number): TranslateResult[] {
+  const parsed: unknown = JSON.parse(line);
+  if (typeof parsed !== "object" || parsed === null) throw new Error("the answer is not an object");
+  const fields = parsed as Record<string, unknown>;
+  if (fields["id"] !== id) throw new Error(`the answer names batch ${String(fields["id"])}`);
+  const results = fields["results"];
+  if (!Array.isArray(results) || results.length !== expected) {
+    throw new Error(
+      `the answer holds ${Array.isArray(results) ? results.length : 0} of ${expected}`,
+    );
+  }
+  return results.map((entry): TranslateResult => {
+    const item = (typeof entry === "object" && entry !== null ? entry : {}) as Record<
+      string,
+      unknown
+    >;
+    const text = item["text"];
+    if (item["ok"] === true && typeof text === "string") return { ok: true, text };
+    const error = item["error"];
+    return { ok: false, error: typeof error === "string" ? error : "the helper stated no reason" };
+  });
+}
+
+export function translateHandlers(translate: Translate) {
+  return {
+    translate_run: (input: HandlerInput): Promise<TranslateRunResult> =>
+      translate.run(input.args as unknown as TranslateRunArgs),
+  };
+}