@mmerterden/multi-agent-pipeline 20.29.0 → 20.30.0

package/pipeline/schemas/tool-call-request.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/tool-call-request.schema.json",
+  "title": "Tool call request",
+  "description": "The body of POST /v1/tools/{name}/call: the tool's arguments, which must satisfy its inputSchema. At most 64 KiB.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "arguments": {
+      "type": "object"
+    }
+  }
+}

package/pipeline/schemas/tool-call.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/tool-call.schema.json",
+  "title": "Tool call result",
+  "description": "What POST /v1/tools/{name}/call returns (`toolkit-tools.mjs call`): the tool's result as text, JSON (as text) and images (base64, image types only). Every text is redacted.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "tool", "risk", "isError", "content"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "tool": {
+      "type": "string"
+    },
+    "risk": {
+      "enum": ["read", "low", "high"]
+    },
+    "isError": {
+      "type": "boolean"
+    },
+    "content": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind"],
+        "properties": {
+          "kind": {
+            "enum": ["text", "json", "image"]
+          },
+          "text": {
+            "type": "string"
+          },
+          "mime": {
+            "type": "string"
+          },
+          "data": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/tools.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/tools.schema.json",
+  "title": "Toolkit tools",
+  "description": "What GET /v1/tools returns (`toolkit-tools.mjs list`): every tool the registered multi-agent-toolkit MCP server serves, with its category (the name's prefix), risk from its own annotations (readOnlyHint read, destructiveHint high, else low) and its inputSchema, from which a client builds the form. Calls are denied by default; allowed says which tools can be called and reason why the others cannot.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "tools"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "title",
+          "category",
+          "description",
+          "risk",
+          "inputSchema",
+          "allowed",
+          "reason"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "title": {
+            "type": ["string", "null"]
+          },
+          "category": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "risk": {
+            "enum": ["read", "low", "high"]
+          },
+          "inputSchema": {
+            "type": "object"
+          },
+          "allowed": {
+            "type": "boolean",
+            "description": "Whether POST /v1/tools/{name}/call accepts this tool: only a readOnlyHint tool whose inputSchema takes no location (path, URL, file, directory, output, project, root) and that is not in the web or context family."
+          },
+          "reason": {
+            "type": ["string", "null"]
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/scripts/_cost.mjs

@@ -1,6 +1,7 @@
 /**
  * @file _cost.mjs  -  shared token-cost pricing math for the .mjs cost scripts
- * (cost-budget-check.mjs, run-aggregator.mjs).
+ * (cost-budget-check.mjs, run-aggregator.mjs, cost-analyze.mjs,
+ * office-ledger.mjs).
  *
  * The single source of the pricing formula for Node callers. Rate DATA still
  * lives in cost-table.json; this module owns only the arithmetic so the formula
@@ -73,3 +74,67 @@ export function attemptSpend(rows) {
   }
   return { usd, unknown };
 }
+
+/**
+ * Wire ID -> rate. Transcripts carry the wire value ("claude-opus-5-5"); the
+ * price table is keyed by rung, so each rung's `modelId` and `copilotModelId`
+ * map to its rate, `legacy` adds previous-generation IDs at their own rates,
+ * and `models` overrides the rung rate for a dispatched ID whose model is not
+ * the rung's (Copilot CLI's older models bill at their own rate). Matching on
+ * the ID rather than the rung name keeps a generation move a data edit, which
+ * is the contract cost-table.json states for itself. A rung name ("opus")
+ * prices as its rung, which is what a tracker records.
+ *
+ * @param {object} table  cost-table.json
+ * @returns {(modelId: string|null|undefined) => object|null}
+ */
+export function modelRateLookup(table) {
+  const byId = new Map([
+    ...Object.entries(table.legacy || {}),
+    ...Object.values(table.prices || {}).flatMap((p) =>
+      [p.modelId, p.copilotModelId].filter(Boolean).map((id) => [id, p]),
+    ),
+    ...Object.entries(table.models || {}),
+  ]);
+  const longestFirst = [...byId.keys()].sort((a, b) => b.length - a.length);
+  return (modelId) => {
+    if (!modelId) return null;
+    const exact = byId.get(modelId) ?? table.prices?.[modelId];
+    if (exact) return exact;
+    // A dated snapshot id (a known id, a hyphen, a release date) prices as that
+    // id; the longest known id wins, so a current id is never read as a shorter
+    // legacy one. Written as a shape rather than as a literal, because
+    // smoke-model-fallback.sh reads every model id in this tree and requires it
+    // to exist in cost-table.json. An id nobody knows prices as nothing and is
+    // COUNTED as unpriced rather than folded in at zero.
+    const id = longestFirst.find(
+      (known) => modelId.startsWith(`${known}-`) || modelId.startsWith(`${known}[`),
+    );
+    return id ? byId.get(id) : null;
+  };
+}
+
+/**
+ * Cache WRITES are not a discount, they are a surcharge: Anthropic prices a
+ * 1h cache write above fresh input. cost-table.json carries cacheReadPerMtok
+ * only, so the write rate is derived at the published 1.25x of input - an
+ * unpriced component silently dropped would make every long-context session
+ * look cheap, which is the direction that hurts.
+ */
+export const CACHE_WRITE_MULTIPLIER = 1.25;
+
+/**
+ * USD for one transcript usage record, or null without a rate.
+ *
+ * @param {object|null} rate
+ * @param {{input_tokens?:number, output_tokens?:number, cache_read_input_tokens?:number, cache_creation_input_tokens?:number}} u
+ */
+export function priceUsage(rate, u) {
+  const fresh = Number(u.input_tokens || 0);
+  const out = Number(u.output_tokens || 0);
+  const cacheRead = Number(u.cache_read_input_tokens || 0);
+  const cacheWrite = Number(u.cache_creation_input_tokens || 0);
+  const base = costUsd(rate, fresh, out, cacheRead);
+  if (base === null) return null;
+  return base + (cacheWrite / 1_000_000) * (rate.inPerMtok || 0) * CACHE_WRITE_MULTIPLIER;
+}

package/pipeline/scripts/_office-smoke-lib.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# _office-smoke-lib.sh  -  shared by the office route smokes: a synthetic
+# office seeded into a temporary directory, one contract-server started on it,
+# and a request helper that can send any Host, Origin or Authorization.
+#
+# Repo layout only: the seed lives under test/fixtures, which an install does
+# not carry, so a smoke sourcing this skips itself when that file is absent.
+#
+# Usage (from a smoke in pipeline/scripts/):
+#   . "$(dirname "${BASH_SOURCE[0]}")/_office-smoke-lib.sh"
+#   office_start            # sets OFFICE_PORT, OFFICE_TOKEN, OFFICE_SECRET, ...
+#   office_req GET /v1/activity [header...]   # body in $OFFICE_BODY, status echoed
+#   office_stop             # also run by the EXIT trap
+
+OFFICE_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OFFICE_ROOT="$(cd "$OFFICE_LIB_DIR/../.." && pwd)"
+OFFICE_SEED="$OFFICE_ROOT/test/fixtures/office-seed.mjs"
+OFFICE_SERVER="$OFFICE_LIB_DIR/contract-server.mjs"
+OFFICE_TMP=""
+OFFICE_PID=""
+
+office_available() { [ -f "$OFFICE_SEED" ] && command -v curl >/dev/null 2>&1; }
+
+office_stop() {
+  if [ -n "$OFFICE_PID" ]; then
+    kill -TERM "$OFFICE_PID" 2>/dev/null
+    wait "$OFFICE_PID" 2>/dev/null
+    OFFICE_PID=""
+  fi
+  if [ -n "$OFFICE_TMP" ] && [ -d "$OFFICE_TMP" ]; then
+    find "$OFFICE_TMP" -depth -mindepth 1 -delete 2>/dev/null
+    rmdir "$OFFICE_TMP" 2>/dev/null
+  fi
+}
+
+# office_json <file> <expression on o>  -  one value out of a JSON file.
+office_json() {
+  node -e 'const o=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));const v=(new Function("o","return "+process.argv[2]))(o);process.stdout.write(typeof v==="string"?v:JSON.stringify(v))' "$1" "$2"
+}
+
+office_start() {
+  OFFICE_TMP="$(mktemp -d "${TMPDIR:-/tmp}/office-smoke.XXXXXX")"
+  trap office_stop EXIT
+  node "$OFFICE_SEED" "$OFFICE_TMP/office" > "$OFFICE_TMP/seed.json" || return 1
+  OFFICE_SECRET="$(office_json "$OFFICE_TMP/seed.json" o.secret)"
+  OFFICE_BLOB="$(office_json "$OFFICE_TMP/seed.json" o.blob)"
+  OFFICE_THINKING="$(office_json "$OFFICE_TMP/seed.json" o.thinking)"
+  OFFICE_SESSION="$(office_json "$OFFICE_TMP/seed.json" o.session)"
+  node -e '
+    const s = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"));
+    for (const [k, v] of Object.entries(s.env)) console.log(`export ${k}=${JSON.stringify(v)}`);
+  ' "$OFFICE_TMP/seed.json" > "$OFFICE_TMP/env.sh"
+  # shellcheck disable=SC1091
+  . "$OFFICE_TMP/env.sh"
+  node "$OFFICE_SERVER" --port 0 --print-token --allow-origin "http://127.0.0.1:5173" \
+    > "$OFFICE_TMP/ready" 2> "$OFFICE_TMP/server.err" &
+  OFFICE_PID=$!
+  local i=0
+  while [ ! -s "$OFFICE_TMP/ready" ] && [ "$i" -lt 100 ]; do
+    sleep 0.1
+    i=$((i + 1))
+  done
+  [ -s "$OFFICE_TMP/ready" ] || return 1
+  OFFICE_PORT="$(office_json "$OFFICE_TMP/ready" o.port)"
+  OFFICE_TOKEN="$(office_json "$OFFICE_TMP/ready" o.token)"
+  return 0
+}
+
+# office_req METHOD PATH [header...]
+# Sends Host 127.0.0.1:<port> and the bearer token unless a header overrides
+# them (pass "Host: x" or "Authorization: none" to change them). Prints the
+# status; the body is left in $OFFICE_TMP/body. The URL and every header go
+# to curl through a 0600 config file, never through argv, so the token (and
+# the token-shaped values the attack checks send) stay off the process list.
+office_req() {
+  local method="$1" path="$2"
+  shift 2
+  local host="Host: 127.0.0.1:$OFFICE_PORT" auth="Authorization: Bearer $OFFICE_TOKEN"
+  local cfg="$OFFICE_TMP/curl.cfg"
+  local h
+  : > "$cfg"
+  chmod 600 "$cfg"
+  for h in "$@"; do
+    case "$h" in
+      Host:*) host="$h" ;;
+      "Authorization: none") auth="" ;;
+      Authorization:*) auth="$h" ;;
+      *) office_cfg_line header "$h" >> "$cfg" ;;
+    esac
+  done
+  office_cfg_line header "$host" >> "$cfg"
+  [ -n "$auth" ] && office_cfg_line header "$auth" >> "$cfg"
+  if [ -n "${OFFICE_DATA:-}" ]; then
+    office_cfg_line header "Content-Type: application/json" >> "$cfg"
+    printf '%s' "$OFFICE_DATA" > "$OFFICE_TMP/data.json"
+    office_cfg_line data-binary "@$OFFICE_TMP/data.json" >> "$cfg"
+  fi
+  office_cfg_line url "http://127.0.0.1:$OFFICE_PORT$path" >> "$cfg"
+  curl -s -m "${OFFICE_MAX_TIME:-10}" -o "$OFFICE_TMP/body" -w '%{http_code}' -X "$method" -K "$cfg"
+}
+
+# office_cfg_line KEY VALUE  -  one curl config line, the value quoted.
+office_cfg_line() {
+  local v="${2//\\/\\\\}"
+  v="${v//\"/\\\"}"
+  printf '%s = "%s"\n' "$1" "$v"
+}
+
+# office_call METHOD PATH [headers...]  -  office_req without a subshell:
+# sets OFFICE_STATUS and OFFICE_BODY in the caller.
+office_call() {
+  OFFICE_STATUS="$(office_req "$@")"
+  OFFICE_BODY="$(cat "$OFFICE_TMP/body" 2>/dev/null)"
+}

package/pipeline/scripts/_spawn-async.mjs

@@ -0,0 +1,73 @@
+/**
+ * @file _spawn-async.mjs  -  run a child process without blocking the event
+ * loop, for the scripts contract-server.mjs calls per request: a slow service
+ * client must not stall every other route while it waits.
+ *
+ * Output is collected up to a cap; past it the child is killed and the result
+ * says `truncated`. A timeout kills the child too and resolves with
+ * `timedOut`. Never rejects: the caller reads `status`.
+ *
+ * @module pipeline/scripts/_spawn-async
+ */
+
+import { spawn } from "node:child_process";
+import { clearTimeout, setTimeout } from "node:timers";
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {{env?: object, timeoutMs?: number, maxBytes?: number}} [opts]
+ * @returns {Promise<{status: number|null, stdout: string, timedOut: boolean, truncated: boolean, error: string|null}>}
+ */
+export function spawnAsync(
+  cmd,
+  args,
+  { env = process.env, timeoutMs = 60_000, maxBytes = 32 * 1024 * 1024 } = {},
+) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(cmd, args, { env, stdio: ["ignore", "pipe", "ignore"] });
+    } catch (e) {
+      resolve({
+        status: null,
+        stdout: "",
+        timedOut: false,
+        truncated: false,
+        error: e.code ?? e.message,
+      });
+      return;
+    }
+    const chunks = [];
+    let size = 0;
+    let timedOut = false;
+    let truncated = false;
+    let error = null;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    child.stdout.on("data", (d) => {
+      size += d.length;
+      if (size > maxBytes) {
+        truncated = true;
+        child.kill("SIGKILL");
+        return;
+      }
+      chunks.push(d);
+    });
+    child.on("error", (e) => {
+      error = e.code ?? e.message;
+    });
+    child.on("close", (status) => {
+      clearTimeout(timer);
+      resolve({
+        status: timedOut || truncated ? null : status,
+        stdout: Buffer.concat(chunks).toString("utf8"),
+        timedOut,
+        truncated,
+        error,
+      });
+    });
+  });
+}

package/pipeline/scripts/_transcript-tail.mjs

@@ -0,0 +1,274 @@
+/**
+ * @file _transcript-tail.mjs  -  read the end of a session transcript, and
+ * whatever was appended to it since the last read, without reading the file
+ * whole.
+ *
+ * The office view (activity-snapshot.mjs) asks two questions of a transcript
+ * that may run to hundreds of megabytes: "what was appended since I last
+ * looked" (createFollower, one byte offset per file, a half-written last line
+ * left for the next read) and "show me the last N messages, then the N before
+ * those" (readTailPage, reading backwards in chunks from an offset the caller
+ * sends back).
+ *
+ * Privacy is decided here, before anything is parsed:
+ *
+ *   - api-request, api-request-blob and api-request-shape records are never
+ *     parsed. They carry whole request bodies (every file the session read),
+ *     and their top-level `"type":"api-request..."` is recognised on the raw
+ *     line, which can only appear unescaped as a real key;
+ *   - a line over MAX_LINE_BYTES is skipped unparsed;
+ *   - a record whose type is not in the caller's allow-list is dropped;
+ *   - thinking and redacted_thinking blocks are removed from every record
+ *     returned, so no caller can emit one.
+ *
+ * Redaction of what remains is the caller's job (transcript-index.mjs
+ * createRedactor), because only the caller knows which fields it shows.
+ *
+ * Synchronous reads with bounded buffers: a poll touches a handful of files
+ * and each read is capped, so there is no stream to manage or leak.
+ *
+ * @module pipeline/scripts/_transcript-tail
+ */
+
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+
+export const NEVER_READ_TYPES = ["api-request", "api-request-blob", "api-request-shape"];
+const NEVER_READ = /"type"\s*:\s*"api-request(?:-blob|-shape)?"/;
+const THINKING = new Set(["thinking", "redacted_thinking"]);
+
+/** A single line longer than this is skipped without being parsed. */
+export const MAX_LINE_BYTES = 2 * 1024 * 1024;
+/** How far back from the end a follower starts on a file it has not seen. */
+export const DEFAULT_INITIAL_BYTES = 256 * 1024;
+/** The most one follower read takes in; a larger jump starts over near the end. */
+const MAX_FOLLOW_BYTES = 8 * 1024 * 1024;
+const CHUNK = 64 * 1024;
+/** How far one page may scan backwards before it returns what it found. */
+const MAX_SCAN_BYTES = 32 * 1024 * 1024;
+
+/** The record types the chat drawer shows. */
+export const CHAT_TYPES = new Set(["user", "assistant"]);
+/** The record types the office view reduces to a desk's state. */
+export const ACTIVITY_TYPES = new Set(["user", "assistant", "system", "ai-title"]);
+
+/**
+ * One line, parsed, or null when it is not to be read: an api-request record,
+ * an oversized line, not JSON, not an object, or a type outside `allow`
+ * (null allows every type except the never-read ones).
+ *
+ * @param {string} text
+ * @param {Set<string>|null} [allow]
+ */
+export function parseLine(text, allow = null) {
+  if (!text || Buffer.byteLength(text) > MAX_LINE_BYTES) return null;
+  if (NEVER_READ.test(text)) return null;
+  let rec;
+  try {
+    rec = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!rec || typeof rec !== "object" || Array.isArray(rec)) return null;
+  if (NEVER_READ_TYPES.includes(rec.type)) return null;
+  if (allow && !allow.has(rec.type)) return null;
+  const content = rec.message?.content;
+  if (Array.isArray(content)) {
+    rec.message.content = content.filter((b) => !(b && THINKING.has(b.type)));
+  }
+  return rec;
+}
+
+function readRange(fd, start, end) {
+  const len = Math.max(0, end - start);
+  const buf = Buffer.alloc(len);
+  let got = 0;
+  while (got < len) {
+    const n = readSync(fd, buf, got, len - got, start + got);
+    if (n <= 0) break;
+    got += n;
+  }
+  return got === len ? buf : buf.subarray(0, got);
+}
+
+/**
+ * Remembers one byte offset per file and returns what was appended since.
+ *
+ * The first read of a file starts `maxInitialBytes` before its end (at the
+ * next line boundary), so a long session costs one bounded read. A file that
+ * shrank or was replaced (a different inode) starts over the same way, and the
+ * result says `reset`. A last line without its newline is left unread and
+ * returned once it is complete.
+ *
+ * @param {{maxInitialBytes?: number, allow?: Set<string>|null}} [opts]
+ */
+export function createFollower({ maxInitialBytes = DEFAULT_INITIAL_BYTES, allow = null } = {}) {
+  const files = new Map();
+  return {
+    /**
+     * @param {string} path
+     * @returns {{records: {offset:number, record:object}[], reset: boolean, size: number}}
+     */
+    read(path) {
+      let fd;
+      try {
+        fd = openSync(path, "r");
+      } catch {
+        files.delete(path);
+        return { records: [], reset: false, size: 0 };
+      }
+      try {
+        const st = fstatSync(fd);
+        if (!st.isFile()) return { records: [], reset: false, size: 0 };
+        const prev = files.get(path);
+        let start;
+        let skipFirst = false;
+        let reset = false;
+        if (prev && prev.ino === st.ino && prev.offset <= st.size) {
+          start = prev.offset;
+          if (st.size - start > MAX_FOLLOW_BYTES) {
+            start = st.size - maxInitialBytes;
+            skipFirst = true;
+            reset = true;
+          }
+        } else {
+          reset = Boolean(prev);
+          start = Math.max(0, st.size - maxInitialBytes);
+          skipFirst = start > 0;
+        }
+        const buf = readRange(fd, start, st.size);
+        const records = [];
+        let from = 0;
+        if (skipFirst) {
+          const nl = buf.indexOf(0x0a);
+          from = nl === -1 ? buf.length : nl + 1;
+        }
+        let consumed = from;
+        for (let at = buf.indexOf(0x0a, from); at !== -1; at = buf.indexOf(0x0a, from)) {
+          const rec =
+            at - from > MAX_LINE_BYTES ? null : parseLine(buf.toString("utf8", from, at), allow);
+          if (rec) records.push({ offset: start + from, record: rec });
+          from = at + 1;
+          consumed = from;
+        }
+        files.set(path, { ino: st.ino, offset: start + consumed });
+        return { records, reset, size: st.size };
+      } finally {
+        closeSync(fd);
+      }
+    },
+    forget(path) {
+      files.delete(path);
+    },
+    get size() {
+      return files.size;
+    },
+  };
+}
+
+/**
+ * The last `limit` allowed records before byte offset `before` (the end of the
+ * file when null), in file order. `before` in the result is the offset of the
+ * first record returned, to send back for the page before it, or null when the
+ * page reached the start of the file. A last line still being written (no
+ * newline yet) is not returned.
+ *
+ * @param {string} path
+ * @param {{before?: number|null, limit?: number, allow?: Set<string>|null}} [opts]
+ * @returns {{records: {offset:number, record:object}[], before: number|null}}
+ */
+export function readTailPage(path, { before = null, limit = 200, allow = null } = {}) {
+  let size;
+  try {
+    const st = statSync(path);
+    if (!st.isFile()) return { records: [], before: null };
+    size = st.size;
+  } catch {
+    return { records: [], before: null };
+  }
+  let end = before === null || before === undefined ? size : Math.min(Number(before), size);
+  const fd = openSync(path, "r");
+  const found = [];
+  let pos = end;
+  let scanned = 0;
+  let reachedStart = false;
+  try {
+    // A file whose last line has no newline is mid-write: that line starts
+    // after the last newline and is left out.
+    if (before === null || before === undefined) {
+      const tail = readRange(fd, Math.max(0, end - CHUNK), end);
+      if (tail.length && tail[tail.length - 1] !== 0x0a) {
+        const nl = tail.lastIndexOf(0x0a);
+        end = nl === -1 ? Math.max(0, end - tail.length) : end - tail.length + nl + 1;
+        if (nl === -1 && end > 0) end = trimToLineStart(fd, end);
+        pos = end;
+      }
+    }
+    // `carry` holds the bytes of a line whose start is not read yet; past the
+    // size cap it is dropped and the line is skipped once its start is found.
+    let carry = Buffer.alloc(0);
+    let carryOversized = false;
+    while (found.length < limit) {
+      if (pos <= 0) {
+        if (carry.length && !carryOversized) take(carry, 0);
+        reachedStart = true;
+        break;
+      }
+      if (scanned >= MAX_SCAN_BYTES) break;
+      const from = Math.max(0, pos - CHUNK);
+      const chunk = readRange(fd, from, pos);
+      scanned += chunk.length;
+      const buf = carryOversized ? chunk : Buffer.concat([chunk, carry]);
+      let lineEnd = buf.length;
+      let nl = buf.lastIndexOf(0x0a, lineEnd - 1);
+      // The bytes after the chunk's last newline belong to the carried line.
+      if (carryOversized && nl !== -1) {
+        lineEnd = nl;
+        carryOversized = false;
+        nl = buf.lastIndexOf(0x0a, lineEnd - 1);
+      } else if (carryOversized) {
+        pos = from;
+        continue;
+      }
+      while (nl !== -1 && found.length < limit) {
+        const lineStart = nl + 1;
+        if (lineEnd > lineStart) take(buf.subarray(lineStart, lineEnd), from + lineStart);
+        lineEnd = nl;
+        nl = lineEnd > 0 ? buf.lastIndexOf(0x0a, lineEnd - 1) : -1;
+      }
+      if (found.length >= limit) break;
+      carry = buf.subarray(0, lineEnd);
+      if (carry.length > MAX_LINE_BYTES) {
+        carry = Buffer.alloc(0);
+        carryOversized = true;
+      }
+      pos = from;
+    }
+  } finally {
+    closeSync(fd);
+  }
+  found.reverse();
+  const first = found.length ? found[0].offset : null;
+  return {
+    records: found,
+    before: reachedStart || first === 0 ? null : (first ?? pos),
+  };
+
+  function take(bytes, offset) {
+    if (bytes.length > MAX_LINE_BYTES) return;
+    const rec = parseLine(bytes.toString("utf8"), allow);
+    if (rec) found.push({ offset, record: rec });
+  }
+}
+
+/** The start of the line `end` falls in, scanning back at most MAX_SCAN_BYTES. */
+function trimToLineStart(fd, end) {
+  let pos = end;
+  while (pos > 0 && end - pos < MAX_SCAN_BYTES) {
+    const from = Math.max(0, pos - CHUNK);
+    const chunk = readRange(fd, from, pos);
+    const nl = chunk.lastIndexOf(0x0a);
+    if (nl !== -1) return from + nl + 1;
+    pos = from;
+  }
+  return 0;
+}