@ultimat3/ai 24.0.0 → 25.1.0

package/src/agent-job.ts

@@ -13,8 +13,10 @@
  */
 
 import type { Action, ActionJobHandle } from '@ultimat3/action';
+import type { Actor, Ctx } from '@ultimat3/core';
+import { impersonate, useContext } from '@ultimat3/core';
 import type { JobHandle, JobTenant, RetryPolicy } from '@ultimat3/jobs';
-import { job } from '@ultimat3/jobs';
+import { JobTenantMismatchError, job } from '@ultimat3/jobs';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 
 export interface AgentJobOptions<I> {
@@ -51,6 +53,19 @@ export interface AgentJobOptions<I> {
    * indistinguishable here, and a rule refusing both would be a wrong refusal. See the README.
    */
   idempotencyKey?(input: I): string;
+  /**
+   * Who the run acts FOR, resolved from its own input on EVERY attempt — the jobs rule "a job
+   * acting for a user takes the user's id in its input and re-authorises it in the body", for a
+   * body that is the agent's. Without it the agent, its policy and every tool run as the WORKER,
+   * which in a served app is the anonymous actor: a member rule refuses it `X_UNAUTHENTICATED`.
+   *
+   * Load the member under the job's tenant (the ambient context already carries it) and build the
+   * same actor a request would: a member who left, or lost the role, is refused on the next
+   * attempt rather than trusted from the enqueue. The swap is core's `impersonate`, so the worker
+   * stays on the record as `onBehalfOf`. An actor in another org than `tenant` declared is refused
+   * before the agent starts — `tenant` is the org this run acts under, and nothing moves it.
+   */
+  actor?(args: { readonly input: I; readonly ctx: Ctx }): Promise<Actor> | Actor;
 }
 
 /**
@@ -82,7 +97,31 @@ export function agentJob<TInput extends StandardSchemaV1, TOutput extends Standa
     // input, { surface: 'job', ctx })`, so the agent's policy, its input parse, its budget scope
     // and its span all apply — and `ctx` is the WORKER's, so `ctx.signal` aborting at the attempt
     // timeout reaches the agent's turn loop.
-    run: ({ input, ctx }) => bridge().invoke(asInput<TInput>(input), ctx),
+    run: async ({ input, ctx }) => {
+      if (options.actor === undefined) return bridge().invoke(asInput<TInput>(input), ctx);
+      const actor = await options.actor({ input, ctx });
+      assertSameTenant(options.name, actor, ctx.actor.orgId);
+      return impersonate(actor, `agentJob ${options.name} acts for the actor its input names`, () =>
+        // The CHILD context: the resolved actor, the worker's signal, deadline and services.
+        bridge().invoke(asInput<TInput>(input), useContext()),
+      );
+    },
+  });
+}
+
+/**
+ * The resolver's actor stays inside the org the job declared. Coded and TERMINAL — jobs' own
+ * `X_JOB_TENANT_MISMATCH`, the refusal a webhook delivery naming the wrong org gets — because the
+ * same payload resolves the same foreign actor on every attempt: an unclassified `assert` spent the
+ * whole retry policy re-proving it.
+ */
+function assertSameTenant(name: string, actor: Actor, tenant: string | undefined): void {
+  const orgId = actor.orgId ?? undefined;
+  if (orgId === tenant) return;
+  throw new JobTenantMismatchError({
+    job: name,
+    reason: `resolved an actor in org ${orgId ?? '(none)'} through actor(), but the run is under ${tenant === undefined ? "tenant 'none'" : `org ${tenant}`}, so it would act outside the org it declared`,
+    fix: `actor: ({ input, ctx }) => memberActorIn(ctx.actor.orgId, input) — in agentJob("${name}"), load the member under the job's own tenant, so a member of another org is not found rather than returned`,
   });
 }
 

package/src/agent.ts

@@ -6,8 +6,8 @@
  * ninth kind, and the list is what a reader counts instead of a sentence in one of them that
  * cannot see the rest. A tool-using run is
  * still one server-authoritative operation with an input schema, an output schema and a policy —
- * so this returns an `action`, and inherits `.tool()`, `.openapi()`, `.client()`, `.job()`,
- * `.contract()` and its manifest row without a line here.
+ * so this returns an `action`, and inherits `.openapi()`, `.client()`, `.job()`, `.contract()`,
+ * its MCP tool (`@ultimat3/mcp`'s `toolFrom`) and its manifest row without a line here.
  *
  * It exists because the alternative is a hand-rolled loop outside the framework, and a hand-rolled
  * loop is where the dangerous mistake lives: taking the ACTOR from the model's output. Here the
@@ -31,7 +31,7 @@ import type { AgentFact } from './agent-facts';
 import { registerAgentFact } from './agent-facts';
 import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
 import type { BudgetLimits } from './budget';
-import { budgetKeysFor, currentBudget, withBudget } from './budget';
+import { budgetKeysFor, currentBudget, screenedMoney, withBudget } from './budget';
 import {
   AgentMaxTurnsError,
   AgentToolUnexposedError,
@@ -41,8 +41,9 @@ import {
 } from './errors';
 import type { LlmBudget } from './llm';
 import { answerAttributes } from './llm';
+import { describedModel, type ModelSource, modelForCall } from './model-resolve';
 import type { ModelId } from './models';
-import { DEFAULT_MODEL, moreCapableThan } from './models';
+import { moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
 import type {
   AiMessage,
@@ -55,7 +56,7 @@ import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
 import type { Respond } from './respond';
 import { RESPOND, respondFor } from './respond';
-import { aiGateway, aiRedactor } from './runtime';
+import { aiGateway, aiRedactor, installedGateway } from './runtime';
 import type { AgentTool, LlmTool, LlmToolResult, ProjectableAction } from './tools';
 import { asProjectableAction, runLlmToolCall, toLlmTools, toolLabel } from './tools';
 
@@ -203,6 +204,16 @@ export function agent<
   return built;
 }
 
+// `null`, not `undefined`, for a row naming no model yet: the row is a published fact, and an
+// absent key reads as a reader that forgot to ask.
+const modelFact = (described: {
+  readonly model: string | undefined;
+  readonly from: ModelSource | undefined;
+}): Pick<AgentFact, 'model' | 'modelFrom'> => ({
+  model: described.model ?? null,
+  modelFrom: described.from ?? null,
+});
+
 function factsOf<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,
@@ -213,7 +224,10 @@ function factsOf<
     prompt: def.prompt.ref,
     promptId: def.prompt.id,
     promptHash: def.prompt.hash,
-    model: def.model ?? def.prompt.model ?? DEFAULT_MODEL,
+    // The run's own precedence, so the row names the model a call would use NOW: read when the
+    // facts are, at describe time, like every name in the row. `modelFrom` says which place
+    // answered — `gateway` (or `null`, none yet) depends on the gateway installed at that moment.
+    ...modelFact(describedModel(def.model, def.prompt.model, installedGateway()?.defaultModel)),
     maxTurns: def.maxTurns ?? DEFAULT_MAX_TURNS,
     maxToolResultChars: def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS,
     tools: [...def.tools.map(toolLabel)].sort(),
@@ -249,7 +263,10 @@ async function run<
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
   const name = prompt.ref;
-  const model = def.model ?? prompt.model ?? DEFAULT_MODEL;
+  // Screened first: a bad declaration is refused whether or not a gateway exists.
+  const limits = limitsOf(def);
+  // The declaration, its prompt, then the gateway's `defaultModel` — the app's three places.
+  const model = modelForCall('agent', name, def.model, prompt.model);
   const vars = await def.vars({ input: args.input, ctx: args.ctx });
   assertNoSecrets(name, vars);
   const redact = aiRedactor();
@@ -269,8 +286,6 @@ async function run<
       'llm.redacted': rendered !== rawPrompt || system !== prompt.system,
     });
 
-    // Screened first, as before: a bad declaration is refused whether or not a gateway exists.
-    const limits = limitsOf(def);
     // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
     const gateway = aiGateway(name);
     // Keyed on the CALLER, so the gateway's `actor` / `org` ceilings count this call against them.
@@ -323,7 +338,7 @@ async function run<
           usage: result.usage,
           cost: result.cost,
         });
-        assertAnswerable(result, name);
+        assertAnswerable(result, name, base);
 
         if (requested.length > 0) {
           // Concurrent, and deliberately unbounded WITHIN one turn: the batch is what a single
@@ -398,12 +413,12 @@ async function observeTurn<
 }
 
 /** Refuse before the answer is read, for the reason `llm()` does: a refusal is a 200 with no answer. */
-function assertAnswerable(result: GenerateResult, name: string): void {
+function assertAnswerable(result: GenerateResult, name: string, request: GenerateRequest): void {
   if (result.stopReason !== 'refusal') return;
   throw new LlmRefusedError({
     prompt: name,
     model: result.model,
-    alternative: moreCapableThan(result.model),
+    alternative: moreCapableThan(result.model, request),
     category: result.stopDetails?.category,
     explanation: result.stopDetails?.explanation,
   });
@@ -421,7 +436,9 @@ function limitsOf<
     ...(budget?.tokensIn === undefined
       ? {}
       : { tokensIn: finiteCount(SUBJECT, 'budget.tokensIn', budget.tokensIn) }),
-    ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
+    ...(budget?.costPerCall === undefined
+      ? {}
+      : { costPerCall: screenedMoney(SUBJECT, 'budget.costPerCall', budget.costPerCall) }),
     // The ledger's `request` scope accumulates across every call made under one ledger, which for
     // a run under `withBudget` is exactly "the whole run".
     ...(budget?.tokensPerRun === undefined

package/src/budget.ts

@@ -101,12 +101,23 @@ export interface BudgetKeys {
 }
 
 export function budgetKeysFor(actor: Actor): BudgetKeys {
+  const orgId: string | null | undefined = actor.orgId;
   return {
     actorKey: `actor:${actor.kind}:${actor.id}`,
-    ...(actor.orgId === undefined ? {} : { orgKey: `org:${actor.orgId}` }),
+    ...(orgless(orgId) ? {} : { orgKey: `org:${orgId}` }),
   };
 }
 
+/**
+ * "Inside no org", in all three spellings `orgId` arrives in: it is a value off the wire (a decoded
+ * session row, an app's adapter), so `null` and `''` reach here despite core's
+ * `string | undefined`. Testing `undefined` alone turned the other two into the real keys `org:null`
+ * and `org:` — ONE org window shared by every org-less caller in the deployment. The same predicate
+ * as `@ultimat3/query`'s `cache.ts`, restated because that one is module-private.
+ */
+const orgless = (orgId: string | null | undefined): boolean =>
+  orgId === undefined || orgId === null || orgId === '';
+
 /**
  * What `reserve` debited, so `record` can reconcile it against the provider's real counts and
  * `release` can give it back. Held by the caller rather than the ledger because one ledger serves
@@ -159,6 +170,11 @@ export class MemoryBudgetStore implements BudgetStore {
   }
 }
 
+/** The one way to build the per-process store; the class is a type in the barrel only. */
+export function memoryBudgetStore(): MemoryBudgetStore {
+  return new MemoryBudgetStore();
+}
+
 export interface BudgetLedgerInput {
   readonly limits: BudgetLimits;
   /** Stable identity keys. Omit a key to skip that scope even when a limit is set. */
@@ -200,7 +216,7 @@ export class BudgetLedger {
     // limit makes `limit - spent` a `NaN`, `want > NaN` false, and the scope silently unlimited —
     // the ceiling does not become wrong, it stops existing. `llm()`, `agent()` and `hive()` screen
     // the same numbers first under the key names their declarations use (`tokensPerRun` is this
-    // `request`), so this is the backstop for a `createGateway({ budget })` or a hand-built ledger,
+    // `request`), so this is the backstop for a `providerGateway({ budget })` or a hand-built ledger,
     // where these ARE the names the caller wrote.
     this.limits = assertFiniteLimits(input.limits);
     this.actorKey = input.actorKey;
@@ -289,6 +305,9 @@ export class BudgetLedger {
    * an `llm()` action must not be able to widen the actor or org ceiling it runs inside.
    */
   derive(limits: BudgetLimits): BudgetLedger {
+    // Screened BEFORE tightening, not only by the child's constructor: a `NaN` that won
+    // `tighterMoney` would otherwise reach the child as the parent's ceiling, widened.
+    assertFiniteLimits(limits);
     const child = new BudgetLedger({
       limits: {
         ...pick('request', tighterNumber(this.limits.request, limits.request)),
@@ -387,18 +406,34 @@ export class BudgetLedger {
 }
 
 /**
- * Every declared token ceiling, proven to be a number. A limit is optional and an absent one is
+ * Every declared ceiling, proven to be a whole count. A limit is optional and an absent one is
  * "unlimited" by design — which is exactly why a `NaN` one is the dangerous value: it reads as a
- * declared ceiling everywhere (`report()`, a manifest row, a log line) and enforces nothing.
+ * declared ceiling everywhere (`report()`, a manifest row, a log line) and enforces nothing. The
+ * money one most of all: `tighterMoney` asks `a.minor <= b.minor`, false against a `NaN`, so an
+ * unscreened `costPerCall` won every `derive` and WIDENED the stricter ceiling it ran inside.
+ * `subject` and `prefix` let a caller name the key its own declaration wrote (`gateway`'s
+ * `budget.org`), because a fix line naming a key the app never typed is not a fix.
  */
-function assertFiniteLimits(limits: BudgetLimits): BudgetLimits {
+export function assertFiniteLimits(
+  limits: BudgetLimits,
+  subject = 'the AI budget',
+  prefix = '',
+): BudgetLimits {
   for (const scope of ['request', 'tokensIn', 'actor', 'org'] as const) {
     const limit = limits[scope];
-    if (limit !== undefined) finiteCount('the AI budget', scope, limit);
+    if (limit !== undefined) finiteCount(subject, `${prefix}${scope}`, limit);
   }
+  const money = limits.costPerCall;
+  if (money !== undefined) finiteCount(subject, `${prefix}costPerCall.minor`, money.minor);
   return limits;
 }
 
+/** One money ceiling screened under `key`, for a declaration whose field names differ from ours. */
+export function screenedMoney(subject: string, key: string, money: Money): Money {
+  finiteCount(subject, `${key}.minor`, money.minor);
+  return money;
+}
+
 function isBudgetTake(value: unknown): value is BudgetTake {
   if (typeof value !== 'object' || value === null) return false;
   const record = value as Record<string, unknown>;

package/src/content-blocks.ts

@@ -0,0 +1,227 @@
+// The image and document blocks a user turn may carry: their shapes (the Messages API's own field
+// names, so the Anthropic body passes them through untouched), the screen every request runs them
+// through before it leaves, and what they add to the pre-flight token estimate.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { AiContentUnsupportedError } from './content-errors';
+import { AiRequestInvalidError } from './errors';
+import type { ContentKind, ModelId } from './models';
+import { modelSpec } from './models';
+import type { AiContentBlock } from './provider';
+
+/** "JPEG, PNG, GIF, and WebP" — the one list both wire formats publish. */
+export const IMAGE_MEDIA_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'] as const;
+export type ImageMediaType = (typeof IMAGE_MEDIA_TYPES)[number];
+
+/**
+ * Ceilings on a base64 `data` string, in CHARACTERS — the encoded size, which is what the limits
+ * are stated in. Image: the Claude API's 10 MB per image (MiB, as its own refusal counts them).
+ * Document: 32 MiB, the Messages API's whole-request ceiling, so no single PDF can be legal on
+ * its own and still be a request the endpoint refuses. The OpenAI format allows more for a file
+ * (50 MB); one table for both, the stricter, so which provider answers never changes the verdict.
+ */
+export const MAX_IMAGE_BASE64_CHARS = 10 * 1024 * 1024;
+export const MAX_DOCUMENT_BASE64_CHARS = 32 * 1024 * 1024;
+
+/**
+ * An image's pre-flight token estimate: the most visual tokens Claude 4.7+ spends on one image
+ * after resizing (4,784 — vision guide, high-resolution tier). Pessimistic on purpose, like the
+ * rest of the estimate: the budget reserves it and `record` gives back what the call did not use.
+ */
+export const IMAGE_TOKEN_ESTIMATE = 4_784;
+
+export type AiImageSource =
+  | { readonly type: 'base64'; readonly media_type: ImageMediaType; readonly data: string }
+  | { readonly type: 'url'; readonly url: string };
+
+export type AiDocumentSource =
+  | { readonly type: 'base64'; readonly media_type: 'application/pdf'; readonly data: string }
+  | { readonly type: 'url'; readonly url: string }
+  | { readonly type: 'text'; readonly media_type: 'text/plain'; readonly data: string };
+
+export interface AiImageBlock {
+  readonly type: 'image';
+  readonly source: AiImageSource;
+}
+
+/** `title` is the Messages API's; on the OpenAI format it becomes the file's `filename`. */
+export interface AiDocumentBlock {
+  readonly type: 'document';
+  readonly source: AiDocumentSource;
+  readonly title?: string;
+}
+
+export type AiMediaBlock = AiImageBlock | AiDocumentBlock;
+
+/** The two kinds this module screens; a narrowing every consumer of `AiContentBlock` can reuse. */
+export function isMediaBlock(block: { readonly type: string }): block is AiMediaBlock {
+  return block.type === 'image' || block.type === 'document';
+}
+
+/** The fields of a message this screen reads — structural, so `provider.ts` stays the owner. */
+interface ScreenedMessage {
+  readonly role: string;
+  readonly content: string | readonly { readonly type: string }[];
+}
+
+/**
+ * Refuse every media block the target cannot take, and every one that is malformed, BEFORE the
+ * request is built. Blocks reach here from typed code and from replayed JSON alike, so the screen
+ * is at runtime: a media type outside the list, a URL that is not `https:`, a base64 string over
+ * its ceiling or outside the alphabet. A malformed block is `X_AI_REQUEST_INVALID`; a well-formed
+ * one the role or model cannot take is `X_AI_CONTENT_UNSUPPORTED`.
+ */
+export function assertMediaContent(
+  messages: readonly ScreenedMessage[],
+  target: { readonly provider: string; readonly model: ModelId },
+): void {
+  messages.forEach((message, m) => {
+    if (typeof message.content === 'string') return;
+    message.content.forEach((block, b) => {
+      if (!isMediaBlock(block)) return;
+      const at = `messages[${m}].content[${b}]`;
+      const kind: ContentKind = block.type;
+      if (message.role !== 'user') {
+        const refusal = { by: 'role', ...target, role: message.role } as const;
+        throw new AiContentUnsupportedError({ kind, at, refusal });
+      }
+      if (!(modelSpec(target.model).input ?? []).includes(kind)) {
+        throw new AiContentUnsupportedError({ kind, at, refusal: { by: 'model', ...target } });
+      }
+      assertSource(block, at);
+    });
+  });
+}
+
+function assertSource(block: AiMediaBlock, at: string): void {
+  const fields = fieldsOf(block.source);
+  const type = fields['type'];
+  // Read as untrusted: a replayed block's title is whatever the JSON held, on either kind.
+  const title: unknown = (block as { readonly title?: unknown }).title;
+  if (title !== undefined && typeof title !== 'string') {
+    throw invalid(
+      at,
+      `has a title of ${renderCauseValue(title)}`,
+      "title: 'q3.pdf'   # a string, or omit the field",
+    );
+  }
+  if (type === 'url') {
+    assertUrl(fields['url'], at);
+    return;
+  }
+  if (type === 'base64') {
+    assertBase64(block.type, fields, at);
+    return;
+  }
+  if (type === 'text' && block.type === 'document') {
+    assertText(fields, at);
+    return;
+  }
+  const legal = block.type === 'image' ? "'base64' or 'url'" : "'base64', 'url' or 'text'";
+  throw invalid(
+    at,
+    `has source.type ${renderCauseValue(type)}`,
+    `source: { type: 'base64', media_type, data }   # source.type is ${legal}`,
+  );
+}
+
+function assertUrl(url: unknown, at: string): void {
+  // `https:` only: a `data:` URL is the base64 source spelled a second way, and plain `http:` is a
+  // fetch the vendor makes over a channel anyone on the path can rewrite.
+  if (typeof url === 'string' && URL.canParse(url) && new URL(url).protocol === 'https:') return;
+  throw invalid(
+    at,
+    `has source.url ${renderCauseValue(url)}, which is not an https: URL`,
+    "source: { type: 'url', url: 'https://…' }   # or send the bytes as { type: 'base64', media_type, data }",
+  );
+}
+
+/** The standard alphabet with its padding, whole: no whitespace, no `data:` prefix, no URL-safe. */
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+
+function assertBase64(kind: ContentKind, fields: Record<string, unknown>, at: string): void {
+  const mediaType = fields['media_type'];
+  const legal: readonly unknown[] = kind === 'image' ? IMAGE_MEDIA_TYPES : ['application/pdf'];
+  if (!legal.includes(mediaType)) {
+    throw invalid(
+      at,
+      `has media_type ${renderCauseValue(mediaType)}, which a ${kind} block does not take`,
+      `media_type: '${String(legal[0])}'   # one of ${legal.join(', ')}${kind === 'document' ? "; text goes as { type: 'text', media_type: 'text/plain', data }" : ''}`,
+    );
+  }
+  const data = fields['data'];
+  const cap = kind === 'image' ? MAX_IMAGE_BASE64_CHARS : MAX_DOCUMENT_BASE64_CHARS;
+  if (
+    typeof data !== 'string' ||
+    data.length > cap ||
+    data.length % 4 !== 0 ||
+    !BASE64.test(data)
+  ) {
+    const size = typeof data === 'string' ? `${data.length} characters` : renderCauseValue(data);
+    throw invalid(
+      at,
+      `has source.data of ${size}: not one non-empty, padded, standard-alphabet base64 string of at most ${cap} characters`,
+      `data: Buffer.from(bytes).toString('base64')   # no data: prefix, at most ${cap} characters; a larger ${kind} goes as an https:// url source`,
+    );
+  }
+}
+
+function assertText(fields: Record<string, unknown>, at: string): void {
+  const data = fields['data'];
+  if (fields['media_type'] === 'text/plain' && typeof data === 'string' && data !== '') return;
+  throw invalid(
+    at,
+    'has a text source that is not { media_type: "text/plain", data: <non-empty string> }',
+    "source: { type: 'text', media_type: 'text/plain', data: text }   # the document's text, non-empty",
+  );
+}
+
+const invalid = (at: string, what: string, fix: string): AiRequestInvalidError =>
+  new AiRequestInvalidError({ detail: `${at} ${what}`, fix });
+
+/**
+ * The readable text of one block, for `messageText`. An image and a PDF have none — their cost is
+ * `mediaTokenEstimate`'s, never their base64 read as prose — and a text document's is its data.
+ */
+export function blockText(block: AiContentBlock): string {
+  if (block.type === 'text') return block.text;
+  if (block.type === 'tool_result') return block.content;
+  if (block.type === 'tool_use') return JSON.stringify(block.input);
+  if (block.type !== 'document') return '';
+  const source = fieldsOf(block.source);
+  return source['type'] === 'text' ? stringOr(source['data']) : '';
+}
+
+/**
+ * What the media blocks add to the pre-flight estimate. An image is `IMAGE_TOKEN_ESTIMATE`, its
+ * worst case. A base64 PDF is its encoded length over four — the same 4-characters-per-token rule
+ * as text, and in the published per-page range (text plus one page image) for an ordinary PDF. A
+ * text document's `data` is already counted by `messageText`. A PDF by URL is UNKNOWABLE before
+ * the vendor fetches it and adds nothing: `record` reconciles to the real usage afterwards.
+ *
+ * Runs BEFORE the screen (the gateway reserves, then the provider builds), so every field is read
+ * as untrusted — a malformed block is estimated as nothing and refused a moment later.
+ */
+export function mediaTokenEstimate(messages: readonly ScreenedMessage[]): number {
+  let tokens = 0;
+  for (const message of messages) {
+    if (typeof message.content === 'string') continue;
+    for (const block of message.content) {
+      if (!isMediaBlock(block)) continue;
+      if (block.type === 'image') {
+        tokens += IMAGE_TOKEN_ESTIMATE;
+        continue;
+      }
+      const source = fieldsOf(block.source);
+      if (source['type'] === 'base64') tokens += Math.ceil(stringOr(source['data']).length / 4);
+    }
+  }
+  return tokens;
+}
+
+const stringOr = (value: unknown): string => (typeof value === 'string' ? value : '');
+
+/** A block's `source` as untrusted fields: a replayed block may carry none, or `null`. */
+function fieldsOf(source: unknown): Readonly<Record<string, unknown>> {
+  return typeof source === 'object' && source !== null ? (source as Record<string, unknown>) : {};
+}

package/src/content-errors.ts

@@ -0,0 +1,67 @@
+// The X_AI_CONTENT_UNSUPPORTED class, apart from ./errors because that catalogue is at its ceiling —
+// the split `hive-errors.ts` and `eval-errors.ts` made. Its code and title are registered in
+// ./errors with the rest: one owner, one registration, one place a duplicate can surface.
+
+import { UltimateError } from '@ultimat3/core';
+
+/** Where a block was refused: a capability of the WIRE format, or of the model's own row. */
+export type ContentRefusal =
+  | { readonly by: 'model'; readonly model: string; readonly provider: string }
+  | {
+      readonly by: 'provider';
+      readonly model: string;
+      readonly provider: string;
+      /** What the wire format lacks — and, in `fix`, the block this provider DOES take instead. */
+      readonly why: string;
+      readonly fix: string;
+    }
+  | {
+      readonly by: 'role';
+      readonly model: string;
+      readonly provider: string;
+      readonly role: string;
+    };
+
+/**
+ * A message carries an image or document block the target cannot take. Refused before the request
+ * leaves, because the alternative is a 400 whose message names a JSON path, not the fix — or, on
+ * the endpoints that skip what they cannot parse, an answer about a document the model never saw.
+ *
+ * Never collected into `X_AI_PROVIDER_UNAVAILABLE`: the same blocks get the same refusal from
+ * every provider serving that model, so retrying burns attempts and discards this fix line.
+ */
+export class AiContentUnsupportedError extends UltimateError {
+  constructor(input: {
+    readonly kind: string;
+    readonly at: string;
+    readonly refusal: ContentRefusal;
+  }) {
+    const { kind, at, refusal } = input;
+    super({
+      code: 'X_AI_CONTENT_UNSUPPORTED',
+      cause: `${at} is a ${kind} block, and ${causeOf(kind, refusal)}`,
+      fix: fixOf(kind, refusal),
+      meta: { kind, at, by: refusal.by, model: refusal.model, provider: refusal.provider },
+    });
+  }
+}
+
+function causeOf(kind: string, refusal: ContentRefusal): string {
+  if (refusal.by === 'model') {
+    return `model "${refusal.model}" is registered without '${kind}' in its input list`;
+  }
+  if (refusal.by === 'role') {
+    return `a ${kind} block may only travel in a user turn, not a ${refusal.role} turn (provider "${refusal.provider}", model "${refusal.model}")`;
+  }
+  return `provider "${refusal.provider}" cannot send it to model "${refusal.model}": ${refusal.why}`;
+}
+
+function fixOf(kind: string, refusal: ContentRefusal): string {
+  if (refusal.by === 'model') {
+    return `registerModel({ ...modelSpec('${refusal.model}'), input: ['image', 'document'] })   # if its endpoint accepts ${kind}s; or route the request to a model that does`;
+  }
+  if (refusal.by === 'role') {
+    return `{ role: 'user', content: [/* the ${kind} block */] }   # move the block out of the ${refusal.role} turn`;
+  }
+  return refusal.fix;
+}