akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/service/predefinedAdaptor/documentTransfer.ts

@@ -0,0 +1,89 @@
+import { mkdir, readdir } from "node:fs/promises";
+import path from "node:path";
+import { Logger } from "akanjs/common";
+import type { DatabaseAdaptor, TransferRow } from "./sql/types";
+
+export interface TransferReport {
+  table: string;
+  rows: number;
+}
+
+/**
+ * Model tables to one NDJSON file each and back, rows as stored. `_akan_meta`, the search mirror, the cache and the
+ * queue stay behind: the target writes its own meta and rebuilds the mirror; sessions and pending jobs do not move.
+ */
+export class DocumentTransfer {
+  static readonly #chunk = 1000;
+  readonly #database: DatabaseAdaptor;
+  readonly #logger = new Logger("DocumentTransfer");
+
+  constructor(database: DatabaseAdaptor) {
+    this.#database = database;
+  }
+
+  async exportTo(dir: string): Promise<TransferReport[]> {
+    await mkdir(dir, { recursive: true });
+    const reports: TransferReport[] = [];
+    for (const store of this.#stores()) {
+      const writer = Bun.file(path.join(dir, `${store.table}.ndjson`)).writer();
+      let rows = 0;
+      let after = "";
+      for (;;) {
+        const chunk = await store.exportRows(after, DocumentTransfer.#chunk);
+        for (const row of chunk) writer.write(`${JSON.stringify(row)}\n`);
+        rows += chunk.length;
+        const last = chunk.at(-1);
+        if (!last || chunk.length < DocumentTransfer.#chunk) break;
+        after = last.id;
+      }
+      await writer.end();
+      reports.push({ table: store.table, rows });
+    }
+    return reports;
+  }
+
+  async importFrom(dir: string): Promise<TransferReport[]> {
+    const files = new Set((await readdir(dir)).filter((file) => file.endsWith(".ndjson")));
+    const search = this.#database.getSearchIndex();
+    const reports: TransferReport[] = [];
+    for (const store of this.#stores()) {
+      const file = `${store.table}.ndjson`;
+      if (!files.delete(file)) continue;
+      
+      await search?.suspend(store.database);
+      let rows = 0;
+      let chunk: TransferRow[] = [];
+      for await (const line of DocumentTransfer.#lines(path.join(dir, file))) {
+        chunk.push(JSON.parse(line) as TransferRow);
+        if (chunk.length < DocumentTransfer.#chunk) continue;
+        await store.importRows(chunk);
+        rows += chunk.length;
+        chunk = [];
+      }
+      if (chunk.length) await store.importRows(chunk);
+      rows += chunk.length;
+      if (search && !(await search.resume(store.constant, store.database)))
+        this.#logger.warn(`Another process holds the search rebuild of ${store.table}; it catches up once that ends`);
+      reports.push({ table: store.table, rows });
+    }
+    for (const file of files) this.#logger.warn(`${file} matches no model of this app; skipped`);
+    return reports;
+  }
+
+  #stores() {
+    const stores = this.#database.stores?.();
+    if (!stores) throw new Error("This database adaptor keeps no model stores to transfer.");
+    return stores;
+  }
+
+  static async *#lines(file: string) {
+    let buffered = "";
+    for await (const chunk of Bun.file(file).stream().pipeThrough(new TextDecoderStream())) {
+      buffered += chunk;
+      const lines = buffered.split("\n");
+      buffered = lines.pop() ?? "";
+      for (const line of lines) if (line.trim()) yield line;
+    }
+    if (buffered.trim()) yield buffered;
+  }
+}

package/service/predefinedAdaptor/index.ts

@@ -2,9 +2,10 @@ export * from "./anthropicLlm";
 export * from "./cache.adaptor";
 export * from "./compress.adaptor";
 export * from "./database.adaptor";
-export * from "./deepseekLlm";
+export * from "./documentTransfer";
 export * from "./insightQuery";
 export * from "./llm.adaptor";
+export * from "./llmOverflow";
 export * from "./logging.adaptor";
 export * from "./openaiDialect";
 export * from "./openaiLlm";

package/service/predefinedAdaptor/insightQuery.ts

@@ -1,75 +1,54 @@
-import type { AkanSqlClient } from "./database.adaptor";
+import type { DatabaseAdaptor } from "./database.adaptor";
+import { PostgresAkanClient } from "./sql/driver/postgres";
 
 export interface InsightQueryOptions {
-  /** Rows to return at most. Clamped to `InsightQuery.maxRows`, which no caller can raise. */
+  /** Clamped to `InsightQuery.maxRows`, which no caller can raise. */
   limit?: number;
-  /** How long to wait for the driver, in ms. See the note on `#raced` for which dialects this can actually stop. */
+  /** In ms. Only Postgres stops the query (`statement_timeout`); a synchronous `bun:sqlite` read runs to the end. */
   timeoutMs?: number;
 }
 
 export interface InsightQueryResult {
   columns: string[];
   rows: Record<string, unknown>[];
-  /** The ceiling cut the answer short, so the caller knows not to read it as complete. */
   truncated: boolean;
 }
 
 /**
- * One read-only SQL statement, for an agent or an operator asking a question the domain endpoints cannot express.
- *
- * This is the layer-bypassing read, and every safeguard the framework has is bypassed with it — guards, soft delete,
- * cascade, `_postRemove`, and the `hidden`/`secret` masking every other response path performs. So it is read-only
- * by construction rather than by convention, and it is deliberately *not* wired to an endpoint here: the framework
- * owns no guard strong enough to sit in front of it. An app that wants it writes the endpoint with its own
- * `SuperAdmin`, the same way guards ship with the library that owns the model.
- *
- * Three things enforce read-only, and only the third is ours:
- *
- * 1. The statement is wrapped as a derived table — `SELECT * FROM (<sql>) AS "akanInsight" LIMIT ?`. Nothing but a
- *    query is legal in that position, in either dialect, so a write is a syntax error from the engine rather than a
- *    pattern this code had to recognise. A second statement smuggled behind `;` is a syntax error for the same
- *    reason, and the row ceiling rides along on the same wrapper.
- * 2. A rejection before execution, so the caller reads why rather than a syntax error. It runs on the statement with
- *    comments and string literals removed, because that is what makes `-- ` and `'…'` unable to hide anything.
- * 3. **`_doc` never crosses the boundary.** Every non-base field lives in that one JSON column, which is where the
- *    plan's "re-apply schema-based masking" runs into the fact that an arbitrary SELECT has no model to mask by. So
- *    the enforceable rule is the column itself: unnameable in the statement, dropped from the rows, and any cell
- *    that still arrives holding a JSON object or array is refused. An insight is made of scalars; a value that is
- *    not one is either a document or indistinguishable from it.
- *
- * What that costs is real and worth saying: this answers "how many, since when, grouped how" over base columns and
- * the search mirror, and it cannot read a domain field. Field-level reads go through the domain tools, which mask.
+ * One read-only statement that bypasses guards, soft delete and `hidden`/`secret` masking, so no endpoint is wired
+ * here: an app fronts it with its own `SuperAdmin`. `_doc` is withheld by the engine — `openInsight()` opens a
+ * read-only connection lacking the column, since no text check catches `*`, whole-row values or quoted names.
  */
 export class InsightQuery {
-  /** Not an option. A caller asking for more gets this, because the point is that no caller sets the ceiling. */
   static readonly maxRows = 1000;
   static readonly #allowedFirstKeywords = new Set(["select", "with"]);
-  /**
-   * Words that cannot appear anywhere in a read, checked so read-only does not rest on a dialect's own rule.
-   *
-   * `WITH` has to be allowed as a first keyword — a CTE is how a real question gets asked — and Postgres lets a CTE
-   * modify data. That it is illegal *inside* the derived table this wraps the statement in is true and is what would
-   * stop it, but it is one sentence of another project's documentation away from not being true. This does not
-   * depend on it. Word-boundary matched on the comment- and literal-stripped statement, so `deleted_at` is fine and
-   * a column that is genuinely named `update` is refused — the wrong answer in the safe direction.
-   */
+  
   static readonly #forbidden =
     /\b(insert|update|delete|drop|alter|create|truncate|replace|grant|revoke|attach|detach|vacuum|reindex|pragma)\b/i;
-  /** The column every document's non-base fields live in. See the class note. */
   static readonly #documentColumn = "_doc";
+  static readonly #identifierChar = /[\p{L}\p{N}_$]/u;
+  static readonly #dollarQuote = /^\$(?:[\p{L}_][\p{L}\p{N}_]*)?\$/u;
 
-  readonly #client: AkanSqlClient;
+  readonly #database: DatabaseAdaptor;
 
-  constructor(client: AkanSqlClient) {
-    this.#client = client;
+  constructor(database: DatabaseAdaptor) {
+    this.#database = database;
   }
 
   async run(sql: string, { limit = InsightQuery.maxRows, timeoutMs = 10_000 }: InsightQueryOptions = {}) {
-    const statement = InsightQuery.#assertReadable(sql);
+    const statement = InsightQuery.#assertReadable(sql, this.#database.getConnection() instanceof PostgresAkanClient);
     const rows = Math.max(1, Math.min(limit, InsightQuery.maxRows));
     
-    const wrapped = `SELECT * FROM (${statement}) AS "akanInsight" LIMIT ${rows + 1}`;
-    const found = await InsightQuery.#raced(this.#client.prepare(wrapped).all(), timeoutMs);
+    const wrapped = `SELECT * FROM (${statement}\n) AS "akanInsight" LIMIT ${rows + 1}`;
+    if (!this.#database.openInsight)
+      throw new Error("This database adaptor opens no insight connection, so it cannot run an insight query.");
+    const session = await this.#database.openInsight();
+    let found: Record<string, unknown>[];
+    try {
+      found = await InsightQuery.#raced(session.read(wrapped, timeoutMs), timeoutMs);
+    } finally {
+      await session.close();
+    }
     const truncated = found.length > rows;
     const kept = truncated ? found.slice(0, rows) : found;
     return {
@@ -79,14 +58,6 @@ export class InsightQuery {
     } satisfies InsightQueryResult;
   }
 
-  /**
-   * Stops waiting; does not stop the query.
-   *
-   * With libsql or Postgres the driver call is genuinely asynchronous, so the caller is freed and the connection
-   * finishes on its own. With `bun:sqlite` it is synchronous and holds the event loop, so this timer cannot fire
-   * until the query is already done — the ceiling is what limits that case, not the clock. Do not read the timeout
-   * as protection against an expensive statement.
-   */
   static async #raced<T>(work: Promise<T[]>, timeoutMs: number): Promise<T[]> {
     let timer: ReturnType<typeof setTimeout> | undefined;
     const expiry = new Promise<never>((_, reject) => {
@@ -99,11 +70,10 @@ export class InsightQuery {
     }
   }
 
-  /** Returns the statement with a trailing `;` removed, or throws naming what is wrong with it. */
-  static #assertReadable(sql: string) {
+  static #assertReadable(sql: string, postgres: boolean) {
     const statement = sql.trim().replace(/;\s*$/, "");
     if (!statement) throw new Error("An insight query needs a statement.");
-    const bare = InsightQuery.#stripLiterals(statement);
+    const bare = InsightQuery.#stripLiterals(statement, postgres);
     if (bare.includes(";")) throw new Error("An insight query is one statement. Remove the `;`.");
     const first = /[a-z]+/.exec(bare.toLowerCase())?.[0];
     if (!first || !InsightQuery.#allowedFirstKeywords.has(first))
@@ -120,23 +90,70 @@ export class InsightQuery {
   }
 
   /**
-   * Blanks out comments and string literals so the checks above read only what the engine would treat as syntax.
-   *
-   * Replaced with spaces rather than deleted, so nothing that was two tokens becomes one — `a/**\/b` must not read
-   * as the identifier `ab`. Dollar-quoting is not handled: it is Postgres function-body syntax, and a statement
-   * that begins with SELECT or WITH has nowhere legal to put one.
-   *
-   * A double-quoted span is **unquoted, not blanked**. It is an identifier in both dialects, not a literal, so
-   * blanking it was what let `SELECT "_doc"` through the column check while `SELECT _doc` was refused. Keeping the
-   * contents means SQLite's fallback — a double-quoted string, where no such column exists — is read as an
-   * identifier too, which errs toward refusing a statement rather than toward reading the column.
+   * One left-to-right pass, since a literal can hold a comment opener and a comment a quote; blanked with spaces so no
+   * two tokens merge. A quoted identifier is unquoted, not blanked, or `"_doc"` would pass the column check. Postgres
+   * `$tag$`, `E'…'` and backslash strings are refused — their end would be a guess — and a block comment ends at the
+   * first `*\/` (Postgres nests), which at worst refuses a statement.
    */
-  static #stripLiterals(sql: string) {
-    return sql
-      .replace(/\/\*[\s\S]*?(\*\/|$)/g, (match) => " ".repeat(match.length))
-      .replace(/--[^\n]*/g, (match) => " ".repeat(match.length))
-      .replace(/'(?:''|[^'])*'/g, (match) => " ".repeat(match.length))
-      .replace(/"(?:""|[^"])*"/g, (match) => ` ${match.slice(1, -1)} `);
+  static #stripLiterals(sql: string, postgres: boolean) {
+    const bare: string[] = [];
+    let at = 0;
+    const blankTo = (end: number) => {
+      bare.push(" ".repeat(end - at));
+      at = end;
+    };
+    const unquoteTo = (end: number) => {
+      bare.push(` ${sql.slice(at + 1, end - 1)} `);
+      at = end;
+    };
+    while (at < sql.length) {
+      const char = sql[at];
+      const next = sql[at + 1];
+      const joined = at > 0 && InsightQuery.#identifierChar.test(sql[at - 1]);
+      if (char === "-" && next === "-") {
+        const end = sql.indexOf("\n", at);
+        blankTo(end === -1 ? sql.length : end);
+      } else if (char === "/" && next === "*") {
+        const end = sql.indexOf("*/", at + 2);
+        blankTo(end === -1 ? sql.length : end + 2);
+      } else if (char === "'") {
+        const end = InsightQuery.#closing(sql, at, "'");
+        if (postgres && InsightQuery.#escapeStringPrefix(sql, at))
+          throw new Error("An insight query takes plain '…' strings: E'…' is refused.");
+        if (postgres && sql.slice(at, end).includes("\\"))
+          throw new Error("An insight query takes no backslash inside a string literal.");
+        blankTo(end);
+      } else if (char === '"') {
+        unquoteTo(InsightQuery.#closing(sql, at, '"'));
+      } else if (!postgres && char === "`") {
+        unquoteTo(InsightQuery.#closing(sql, at, "`"));
+      } else if (!postgres && char === "[") {
+        const end = sql.indexOf("]", at + 1);
+        unquoteTo(end === -1 ? sql.length : end + 1);
+      } else if (postgres && char === "$" && !joined && InsightQuery.#dollarQuote.test(sql.slice(at))) {
+        throw new Error("An insight query takes plain '…' strings: a $$-quoted string is refused.");
+      } else {
+        bare.push(char);
+        at += 1;
+      }
+    }
+    return bare.join("");
+  }
+
+  /** A doubled quote escapes itself in both dialects; returns the index past the closing quote. */
+  static #closing(sql: string, open: number, quote: string) {
+    for (let at = open + 1; at < sql.length; at += 1) {
+      if (sql[at] !== quote) continue;
+      if (sql[at + 1] !== quote) return at + 1;
+      at += 1;
+    }
+    return sql.length;
+  }
+
+  static #escapeStringPrefix(sql: string, quote: number) {
+    const prefix = sql[quote - 1];
+    if (prefix !== "E" && prefix !== "e") return false;
+    return quote < 2 || !InsightQuery.#identifierChar.test(sql[quote - 2]);
   }
 
   static #columnsOf(rows: Record<string, unknown>[]) {
@@ -146,13 +163,6 @@ export class InsightQuery {
     return [...columns];
   }
 
-  /**
-   * Drops the document column and refuses anything else shaped like one.
-   *
-   * The column has to be dropped here as well as rejected in the statement, because `SELECT * FROM "user"` returns
-   * it without ever naming it. The JSON check is for the ways a dialect can hand back a whole row under another
-   * name — `row_to_json(u)` — which no list of forbidden function names would keep up with.
-   */
   static #readable(row: Record<string, unknown>) {
     const readable: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(row)) {

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -12,11 +12,7 @@ export interface AgentWireToolResult {
   error?: string;
 }
 
-/**
- * A file the caller attached to one message. Exactly one carrier reaches the model — `data` as inlined bytes, `url`
- * as something the provider fetches, `text` as content already extracted — and which of them a given provider can
- * read is what `LlmAccepts` answers.
- */
+/** Exactly one carrier reaches the model: `data` (inlined bytes), `url` (fetched by the provider) or `text`. */
 export interface AgentWireAttachment {
   name: string;
   mimeType: string;
@@ -24,25 +20,34 @@ export interface AgentWireAttachment {
   data?: string;
   url?: string;
   text?: string;
-  /** The host's own handle on this file, carried so a relay can act on it. A provider mapping ignores it. */
+  /** The host's own handle on this file, for a relay; a provider mapping ignores it. */
   ref?: string;
 }
 
 /**
- * One transcript message of the in-page agent wire (`use-agentic`'s WIRE.md), typed at both ends independently —
- * the wire is the contract, so the server never imports the client package.
+ * `value` is a send-time snapshot the host already masked — the server has no model class to mask it with — and
+ * `refName`/`refId`/`path` lead back to the current value.
  */
+export interface AgentWireReference {
+  refName: string;
+  refId: string;
+  label: string;
+  path?: string;
+  value?: unknown;
+  /** Read by the model in place of a value there is none of — clipped, unreadable, or gone from a restored chat. */
+  note?: string;
+}
+
+/** `use-agentic`'s WIRE.md, typed at both ends independently so the server never imports the client package. */
 export interface AgentWireMessage {
   role: "user" | "assistant" | "tool";
   text?: string;
   attachments?: AgentWireAttachment[];
+  references?: AgentWireReference[];
   toolCalls?: AgentWireToolCall[];
   toolResults?: AgentWireToolResult[];
   error?: string;
-  /**
-   * Stands in for the messages the client's own compaction replaced. It arrives with the user's role because the
-   * wire has no other, but it is history rather than an ask, so a provider mapping frames it as one.
-   */
+  /** A compaction summary: it arrives with the user's role but is history, not an ask, and a provider frames it so. */
   summary?: boolean;
 }
 
@@ -68,74 +73,79 @@ export interface LlmTurnRequest {
 export interface LlmTurnAnswer {
   text?: string;
   toolCalls?: AgentWireToolCall[];
-  /**
-   * Why the turn ended. `"length"` is the provider's ceiling — `finish_reason: "length"`, `stop_reason:
-   * "max_tokens"` — and it is distinguished from `"end"` because the two are indistinguishable downstream
-   * otherwise: a truncated answer reads as a complete one, and a turn cut off mid tool call carries no complete
-   * call at all, so it would end the loop looking exactly like a model that chose to stop.
-   */
+  /** `"length"` is the provider's ceiling; a turn cut off mid tool call must not read as a model that chose to stop. */
   stop: "end" | "toolUse" | "length";
+  /** Absent when the provider reported nothing. */
+  usage?: LlmUsage;
+  /** The model that answered, as the adaptor named it to the provider. */
+  model?: string;
+}
+
+/** `inputTokens` is the whole prompt, cached part included; `cachedTokens` is the share billed at the cache rate. */
+export interface LlmUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cachedTokens: number;
 }
 
 /**
- * The provider seam for one stateless agent turn: the whole transcript in, one assistant answer out. The server
- * relays — it never executes a client tool — so this is the only surface a provider integration fills. An
- * implementation is an `adapt()` class in a lib's `srvkit/`.
- *
- * `null` means this provider is not configured, and the caller turns it into the one sentence that says so. A
- * failure the provider explained is logged and **thrown** instead, as an `Err` whose text the chat prints: a
- * refused turn and an unconfigured app are different things to be told, and collapsing both into `null` left a
- * user reading "no model is configured" about a conversation that had merely outgrown the context window.
+ * The provider seam for one stateless agent turn; the server relays and never executes a client tool. `chat`
+ * resolves `null` only when unconfigured — a refusal the provider explained is thrown as an `Err` the chat prints.
  */
 export interface LlmAdaptor {
-  /**
-   * `onDelta` opts into streaming: the adapter reports assistant text as it arrives and still resolves the full
-   * answer. An adapter may ignore it — the caller treats zero reported deltas as "answered whole".
-   */
+  /** `onDelta` opts into streaming and the full answer still resolves; an adaptor may ignore it. */
   chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null>;
-  /** Which attachment carriers this provider's model can read. Omitted means text only. */
+  /** Omitted means text only. */
   readonly accepts?: LlmAccepts;
+  /** Omitted means nothing is known. */
+  readonly limits?: LlmLimits;
+}
+
+/** Relayed to the browser on every turn, so the chat compacts its transcript before the provider refuses it. */
+export interface LlmLimits {
+  /** The model's context window, prompt and answer together. */
+  window?: number;
+  /** The answer ceiling the adaptor actually requests; left out when it sends none. */
+  output?: number;
 }
 
 /**
- * What an adaptor's model reads beyond text. Declared rather than defaulted to true, because the failure of
- * guessing wrong is the worst one available: a provider handed bytes it cannot decode either rejects the whole
- * turn or accepts it having seen nothing, and the model then answers confidently about a file it never read.
- * `AgentService` degrades what is not accepted into a note the model can repeat back, so a text-only provider
- * needs no attachment code at all — which is every provider until somebody swaps one in for vision.
+ * Declared, never defaulted to true: a provider handed bytes it cannot decode refuses the turn or answers about a
+ * file it never read. `AgentService` degrades what is not accepted into a note.
  */
 export interface LlmAccepts {
-  /** Inlined or linked image bytes. */
   image?: boolean;
   /** Non-image bytes handed over whole — a PDF the model parses itself. */
   document?: boolean;
 }
 
 /**
- * Settings for whichever adaptor fills `LlmAdaptorRole`, registered with `option.setLlm(...)` and injected as the
- * `llmOption` use. It belongs to the role rather than to one provider: swapping the default for another `adapt()`
- * class re-reads the same three fields under that provider's own defaults.
+ * Registered with `option.setLlm(...)` for whichever adaptor fills `LlmAdaptorRole`. `setLlm` keeps extra fields, so
+ * a custom adaptor extends this interface and reads it with `use<MyLlmOption>()`.
  */
 export interface LlmOption {
   apiKey?: string;
   model?: string;
   host?: string;
-  /**
-   * What the *configured* model reads beyond text, overriding what the adaptor claims for its provider. It rides
-   * beside `model` because that is what capability belongs to: an adaptor answers for an API, and one API serves
-   * models that differ. Declared here rather than as a table the framework keeps, because a table is a claim about
-   * models that ship after it and goes quietly wrong — and getting this wrong is the worst failure available, a
-   * provider handed bytes it cannot decode either refusing the turn or accepting it having seen nothing.
-   */
+  /** Overrides what the adaptor claims for its provider: one API serves models that read different things. */
   accepts?: LlmAccepts;
   /**
-   * The answer ceiling, for an API that requires one. A fixed default is a hazard on a model that thinks before
-   * it writes: the budget goes on reasoning and the turn comes back empty with a length stop, which reads as the
-   * model refusing rather than as a number being too small.
-   *
-   * Sampling knobs are deliberately absent from this option. They are the one place a per-model difference is a
-   * hard failure rather than a nuance — `temperature` is a 400 on some models rather than an ignored field — so
-   * the role carries nothing it would have to guess the legality of per model.
+   * The answer ceiling, for an API that requires one. Sampling knobs are absent on purpose: `temperature` is a 400
+   * on some models.
    */
   maxTokens?: number;
+  /** In tokens. Left out, the chat learns it from the first refusal that names it. */
+  contextWindow?: number;
 }
+
+/**
+ * The refusing party printed on `agent.error.llmRequestFailed`: the host, not the adaptor's name, since one dialect
+ * class serves many hosts. A host that is not a URL is printed as written.
+ */
+export const llmProviderOf = (host: string): string => {
+  try {
+    return new URL(host).hostname;
+  } catch {
+    return host;
+  }
+};

package/service/predefinedAdaptor/llmOverflow.ts

@@ -0,0 +1,63 @@
+import { Err } from "akanjs/dictionary";
+import { llmProviderOf } from "./llm.adaptor";
+
+/** Each field is present only when the refusal named it. */
+export interface LlmOverflowFacts {
+  limit?: number;
+  requested?: number;
+}
+
+/** Matches each provider's own too-long-prompt sentence; a status code cannot tell it from any other bad request. */
+export class LlmOverflow {
+  static readonly patterns = [
+    /prompt (?:is )?too long/i, // Anthropic: "prompt is too long: 213462 tokens > 200000 maximum"
+    /request_too_large/i, // Anthropic, past the request byte ceiling
+    /context[_ ]length[_ ]exceeded/i, // OpenAI's error code
+    /exceeds the context window/i, // OpenAI
+    /maximum context length/i, // the OpenAI dialect: DeepSeek, OpenRouter, vLLM, LiteLLM
+    /input token count.*exceeds the maximum/i, // Gemini
+    /maximum prompt length is \d+/i, // xAI
+    /reduce the length of the messages/i, // Groq
+    /is longer than the model'?s context length/i, // Together
+    /too large for model with \d+ maximum context length/i, // Mistral
+  ];
+
+  /** A quota borrows the same words, and compacting a conversation that fit loses detail for nothing. */
+  static readonly quotas = [/rate limit/i, /too many requests/i, /per minute/i];
+
+  static readonly measured = [
+    /(?<requested>[\d,]+) tokens > (?<limit>[\d,]+) maximum/i,
+    /maximum context length is (?<limit>[\d,]+) tokens(?:.*?requested (?:about )?(?<requested>[\d,]+))?/i,
+    /input length \((?<requested>[\d,]+)\) exceeds model'?s maximum context length \((?<limit>[\d,]+)\)/i,
+    /maximum context length of (?<limit>[\d,]+)/i,
+    /input token count \((?<requested>[\d,]+)\) exceeds the maximum number of tokens allowed \((?<limit>[\d,]+)\)/i,
+    /maximum prompt length is (?<limit>[\d,]+) but the request contains (?<requested>[\d,]+)/i,
+    /input \((?<requested>[\d,]+) tokens\) is longer than the model'?s context length \((?<limit>[\d,]+) tokens\)/i,
+  ];
+
+  static match(reason: string): LlmOverflowFacts | null {
+    if (LlmOverflow.quotas.some((pattern) => pattern.test(reason))) return null;
+    if (!LlmOverflow.patterns.some((pattern) => pattern.test(reason))) return null;
+    for (const pattern of LlmOverflow.measured) {
+      const groups = pattern.exec(reason)?.groups;
+      if (!groups) continue;
+      const limit = LlmOverflow.#count(groups.limit);
+      const requested = LlmOverflow.#count(groups.requested);
+      return { ...(limit ? { limit } : {}), ...(requested ? { requested } : {}) };
+    }
+    return {};
+  }
+
+  /** `contextOverflow` when the prompt did not fit (the chat compacts and asks again), else `llmRequestFailed`. */
+  static refusal(host: string, status: number, reason: string): Error {
+    const provider = llmProviderOf(host);
+    const overflow = LlmOverflow.match(reason);
+    if (overflow) return new Err("agent.error.contextOverflow", { provider, ...overflow });
+    return new Err("agent.error.llmRequestFailed", { provider, status: String(status), reason });
+  }
+
+  static #count(text: string | undefined): number | undefined {
+    const count = text ? Number(text.replace(/,/g, "")) : Number.NaN;
+    return Number.isFinite(count) && count > 0 ? count : undefined;
+  }
+}