@ultimat3/ai 27.8.1 → 27.10.0

package/src/billed.ts

@@ -0,0 +1,87 @@
+// Single responsibility: what a model call, or a whole run, was BILLED before it failed — the
+// shape it travels in on a thrown error's `meta.billed`, the reader a job uses to store it, and
+// the arithmetic that adds one call to a run.
+//
+// It exists because a failure after the provider answered is not free: a truncated answer, tool
+// arguments that would not parse, a schema no repair turn satisfied — each was generated and
+// charged for. A job that only sees the error would otherwise have to guess what the attempt cost.
+
+import { isUltimateError } from '@ultimat3/core';
+import type { Money } from '@ultimat3/money';
+import type { TokenUsage } from './provider';
+
+/** The `meta` key every failure after a provider answered carries its bill under. */
+export const BILLED_META = 'billed';
+
+export interface Billed {
+  /** Summed over every provider call that ANSWERED — the provider's own counts. */
+  readonly usage: TokenUsage;
+  /** The price of `usage`, rounded up once. */
+  readonly cost: Money;
+  /** Provider calls that answered and are counted above. */
+  readonly calls: number;
+  /**
+   * Provider calls that were started and never reported usage: aborted by the caller or a
+   * deadline, cut mid-stream, or failed in transport. What they cost CANNOT be known from here —
+   * a provider may bill the tokens it generated before the socket closed, and usage is the last
+   * thing a response carries. Zero means the figures above are the whole bill.
+   */
+  readonly unsettled: number;
+}
+
+const COUNTERS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens'] as const;
+
+const isCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+const isScale = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= 15;
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * What `error` says was billed, or `undefined` when it carries no bill — it was thrown before any
+ * provider answered, or it is not one of this package's failures. Total: the value came out of a
+ * `catch`, and `meta` is data an app stores and reads back, so every field is checked.
+ */
+export function billedOf(error: unknown): Billed | undefined {
+  if (!isUltimateError(error)) return undefined;
+  let raw: unknown;
+  try {
+    raw = error.meta?.[BILLED_META];
+  } catch {
+    return undefined;
+  }
+  const record = asRecord(raw);
+  const usage = asRecord(record?.['usage']);
+  const cost = asRecord(record?.['cost']);
+  if (record === undefined || usage === undefined || cost === undefined) return undefined;
+  if (!COUNTERS.every((key) => isCount(usage[key]))) return undefined;
+  if (!isCount(cost['minor']) || typeof cost['currency'] !== 'string') return undefined;
+  if (!isCount(record['calls']) || !isCount(record['unsettled'])) return undefined;
+  return {
+    usage: {
+      inputTokens: usage['inputTokens'] as number,
+      outputTokens: usage['outputTokens'] as number,
+      cacheReadTokens: usage['cacheReadTokens'] as number,
+      cacheWriteTokens: usage['cacheWriteTokens'] as number,
+    },
+    // The scale travels with the amount: an exact cost read without it is a million times over.
+    cost: {
+      minor: cost['minor'],
+      currency: cost['currency'],
+      ...(isScale(cost['scale']) ? { scale: cost['scale'] } : {}),
+    },
+    calls: record['calls'],
+    unsettled: record['unsettled'],
+  };
+}
+
+/** One answered call, as a bill. */
+export function billedCall(usage: TokenUsage, cost: Money): Billed {
+  return { usage, cost, calls: 1, unsettled: 0 };
+}

package/src/budget.ts

@@ -13,7 +13,8 @@
 import type { Actor } from '@ultimat3/core';
 import { assert, asyncContext, finiteCount } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
-import { assertSameCurrency } from '@ultimat3/money';
+import { assertSameCurrency, commonScale, exponentOf, minorAt } from '@ultimat3/money';
+import { compareMoney, costScale, ledgerUnits, roundUpCost } from './cost';
 import { AiBudgetExceededError } from './errors';
 import type { GenerateRequest, TokenUsage } from './provider';
 import { estimateCost, estimateInputTokens, estimateTokens, totalTokens } from './provider';
@@ -57,11 +58,12 @@ export interface SpendEstimate {
 }
 
 /** Price a request pre-flight. The pessimistic read on purpose — see `estimateCost`. */
-export function estimateSpend(request: GenerateRequest): SpendEstimate {
+export function estimateSpend(request: GenerateRequest, marked = false): SpendEstimate {
   return {
     inputTokens: estimateInputTokens(request),
     tokens: estimateTokens(request),
-    cost: estimateCost(request),
+    // `marked`: a provider would send this request with a cache mark, so it can bill as a write.
+    cost: estimateCost(request, marked),
   };
 }
 
@@ -186,7 +188,10 @@ export interface BudgetLedgerInput {
 
 export interface BudgetReport {
   readonly requestTokens: number;
+  /** Everything recorded, rounded up ONCE to the currency's minor unit. */
   readonly cost: Money;
+  /** The same sum exactly, at `costScale(currency)` — micro-units of the minor unit. */
+  readonly costExact: Money;
   readonly limits: BudgetLimits;
   readonly actorSpent: number;
   readonly orgSpent: number;
@@ -198,7 +203,8 @@ export class BudgetLedger {
   private readonly orgKey: string | undefined;
   private readonly store: BudgetStore;
   private requestTokens = 0;
-  private costMinor = 0;
+  /** Summed EXACTLY, in micro-units of the minor unit, and rounded up once — when it is read. */
+  private costMicro = 0n;
   private readonly currency: string;
   /**
    * The ledger this one was `derive`d from, or `undefined` for a scope's root. Set by `derive`
@@ -334,8 +340,11 @@ export class BudgetLedger {
   async record(usage: TokenUsage, cost: Money, reservation?: BudgetReservation): Promise<void> {
     // Up the chain, because `derive` copies the currency: a scope's reported cost is its own
     // calls plus every call made under a ledger derived from it.
+    // `cost` may be exact (`GenerateResult.costExact`, a finer `scale`) or already rounded; either
+    // way it is widened to one scale and summed there, so fourteen cheap calls are rounded once.
+    const micro = ledgerUnits(cost);
     for (let l: BudgetLedger | undefined = this; l !== undefined; l = l.parent) {
-      l.costMinor += cost.minor;
+      l.costMicro += micro;
     }
     await this.debit(totalTokens(usage) - (reservation?.tokens ?? 0));
   }
@@ -373,13 +382,23 @@ export class BudgetLedger {
   async report(): Promise<BudgetReport> {
     return {
       requestTokens: this.requestTokens,
-      cost: { minor: this.costMinor, currency: this.currency },
+      cost: roundUpCost(this.exactCost()),
+      costExact: this.exactCost(),
       limits: this.limits,
       actorSpent: this.actorKey === undefined ? 0 : await this.store.spent(this.actorKey),
       orgSpent: this.orgKey === undefined ? 0 : await this.store.spent(this.orgKey),
     };
   }
 
+  private exactCost(): Money {
+    const minor = Number(this.costMicro);
+    return {
+      minor: Number.isSafeInteger(minor) ? minor : Number.MAX_SAFE_INTEGER,
+      currency: this.currency,
+      scale: costScale(this.currency),
+    };
+  }
+
   private assertScope(scope: string, limit: number | undefined, spent: number, want: number): void {
     if (limit === undefined) return;
     const remaining = limit - spent;
@@ -393,13 +412,21 @@ export class BudgetLedger {
     const limit = this.limits.costPerCall;
     if (limit === undefined) return;
     assertSameCurrency(limit, cost);
-    if (cost.minor > limit.minor) {
+    if (compareMoney(cost, limit) > 0) {
+      // ONE scale for all three figures: the estimate is in the currency's minor units and the
+      // ceiling may be finer, and printing each in its own under one label compares nothing.
+      const scale = commonScale(cost, limit);
+      const ceiling = Number(minorAt(limit, scale));
       throw new AiBudgetExceededError({
         scope: 'costPerCall',
-        requested: cost.minor,
-        remaining: limit.minor,
-        limit: limit.minor,
-        unit: `${limit.currency} minor units`,
+        requested: Number(minorAt(cost, scale)),
+        remaining: ceiling,
+        limit: ceiling,
+        // The currency's own minor units say so as they always did; a finer ceiling names its scale.
+        unit:
+          scale === exponentOf(limit.currency)
+            ? `${limit.currency} minor units`
+            : `${limit.currency} at scale ${scale}`,
       });
     }
   }
@@ -455,7 +482,8 @@ function tighterMoney(a: Money | undefined, b: Money | undefined): Money | undef
   if (a === undefined) return b;
   if (b === undefined) return a;
   assertSameCurrency(a, b);
-  return a.minor <= b.minor ? a : b;
+  // As money: a ceiling at a finer `scale` is not larger for having a larger `minor`.
+  return compareMoney(a, b) <= 0 ? a : b;
 }
 
 const storage = asyncContext<BudgetLedger>('an AI budget');

package/src/cost.ts

@@ -0,0 +1,146 @@
+// Single responsibility: the money arithmetic over a call's reported usage — what it cost exactly,
+// and that figure rounded up to the currency's own minor unit, once.
+//
+// Exact, in integers: a price is `Money` per million tokens at whatever `scale` the row states
+// (`{ minor: 75, currency: 'USD', scale: 3 }` is $0.075), and a cost is `Money` at
+// `COST_SCALE_DIGITS` more digits than the currency's minor unit — millionths of a cent for USD.
+// The multiplication is done in bigint, so no call, however large, loses a digit on the way.
+
+import type { Money } from '@ultimat3/money';
+import { commonScale, exponentOf, minorAt, moneyScale } from '@ultimat3/money';
+import type { ModelId, ModelSpec } from './models';
+import { modelSpec, PRICE_SCALE_DIGITS } from './models';
+import type { TokenUsage } from './provider';
+
+/** Digits an exact cost carries beyond the currency's minor unit: micro-units of it. */
+export const COST_SCALE_DIGITS = PRICE_SCALE_DIGITS;
+
+const MICRO = 10n ** BigInt(COST_SCALE_DIGITS);
+const MILLION = 1_000_000n;
+/** Prices are summed in TWENTIETHS so the default cache multipliers (0.1x, 1.25x) stay whole. */
+const TWENTIETHS = 20n;
+
+/** The scale an exact cost in `currency` is stated at. */
+export const costScale = (currency: string): number => exponentOf(currency) + COST_SCALE_DIGITS;
+
+/**
+ * What one call cost, EXACTLY to a micro-unit of the currency's minor unit (rounded up at that
+ * digit, which no real price reaches). `Money` with an explicit `scale` — never a float, never a
+ * second type: `{ minor: 105_000, currency: 'USD', scale: 8 }` is 0.105 cents.
+ *
+ * The one price lookup: a model the app never `registerModel`-ed is `X_AI_MODEL_UNKNOWN` here, so
+ * no call is priced — and no budget reserved — against a number nobody chose.
+ */
+export function exactCostOf(model: ModelId, usage: TokenUsage): Money {
+  const spec = modelSpec(model);
+  const { currency } = spec.inputPerMillion;
+  const scale = costScale(currency);
+  return {
+    minor: toSafe(ceilDiv(units(spec, usage, scale), TWENTIETHS * MILLION)),
+    currency,
+    scale,
+  };
+}
+
+/**
+ * Cost of one call in the currency's own minor units — the figure every existing reader of
+ * `cost.minor` means. Rounded UP: a fraction we round away is money the framework silently
+ * absorbs, and under-reporting spend defeats a budget. Rounded ONCE, over the whole call: the
+ * input and output halves were each rounded up before, so a call worth a tenth of a cent read two.
+ */
+export function costOf(model: ModelId, usage: TokenUsage): Money {
+  const spec = modelSpec(model);
+  const { currency } = spec.inputPerMillion;
+  const total = units(spec, usage, costScale(currency));
+  return { minor: toSafe(ceilDiv(total, TWENTIETHS * MILLION * MICRO)), currency };
+}
+
+/** An exact cost (or any finer `Money`) rounded up to its currency's minor unit. */
+export function roundUpCost(exact: Money): Money {
+  const from = exact.scale ?? exponentOf(exact.currency);
+  const drop = 10n ** BigInt(Math.max(0, from - exponentOf(exact.currency)));
+  return { minor: toSafe(ceilDiv(BigInt(exact.minor), drop)), currency: exact.currency };
+}
+
+/** `usage` priced, in twentieths of (a unit at `scale`) per million tokens — before any division. */
+function units(spec: ModelSpec, usage: TokenUsage, scale: number): bigint {
+  const input = minorAt(spec.inputPerMillion, scale);
+  // A cache read is 0.1x input (2/20) and a 5-minute write 1.25x (25/20) unless the row states
+  // its own — a vendor's 0.05x or 0.025x read is a row, which a fixed 0.1x overstated.
+  const read =
+    spec.cacheReadPerMillion === undefined
+      ? input * 2n
+      : minorAt(spec.cacheReadPerMillion, scale) * TWENTIETHS;
+  const write =
+    spec.cacheWritePerMillion === undefined
+      ? input * 25n
+      : minorAt(spec.cacheWritePerMillion, scale) * TWENTIETHS;
+  return (
+    count(usage.inputTokens) * input * TWENTIETHS +
+    count(usage.cacheReadTokens) * read +
+    count(usage.cacheWriteTokens) * write +
+    count(usage.outputTokens) * minorAt(spec.outputPerMillion, scale) * TWENTIETHS
+  );
+}
+
+/** A token count as a bigint. Usage is the provider's number: floored, and never negative. */
+const count = (tokens: number): bigint =>
+  Number.isFinite(tokens) && tokens > 0 ? BigInt(Math.floor(tokens)) : 0n;
+
+const ceilDiv = (numerator: bigint, denominator: bigint): bigint =>
+  (numerator + denominator - 1n) / denominator;
+
+/** Back to the `number` `Money` carries. Past 2^53 minor units there is no honest answer. */
+const toSafe = (value: bigint): number =>
+  value > BigInt(Number.MAX_SAFE_INTEGER) ? Number.MAX_SAFE_INTEGER : Number(value);
+
+/**
+ * `a` against `b` as MONEY — negative, zero or positive — at the finer of their two scales. Never
+ * `a.minor - b.minor`: `{ minor: 500, scale: 3 }` is fifty cents, and read by `minor` alone it
+ * outranked four dollars.
+ */
+export function compareMoney(a: Money, b: Money): number {
+  const scale = commonScale(a, b);
+  const left = minorAt(a, scale);
+  const right = minorAt(b, scale);
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+/** Two amounts of one currency as one, at the finer scale — stated only when either stated one. */
+export function addMoney(a: Money, b: Money): Money {
+  const scale = commonScale(a, b);
+  const minor = toSafe(minorAt(a, scale) + minorAt(b, scale));
+  return a.scale === undefined && b.scale === undefined
+    ? { minor, currency: a.currency }
+    : { minor, currency: a.currency, scale };
+}
+
+/**
+ * A cost as a `Provider` reported it, made bookable. The built-in providers price in integers, but
+ * `Provider` is an interface an app implements, and its `cost.minor` was summed as a plain number
+ * until the ledger went exact: a fraction was accepted. So a fraction is ROUNDED UP (never down:
+ * under-reporting spend defeats a budget), and a value that is no amount at all — `NaN`, an
+ * infinity, a negative, which a ledger would read as a credit — is booked as zero. Never a throw:
+ * this runs after the provider was paid, and a bookkeeping error must not cost the answer.
+ */
+export function bookableCost(cost: Money): Money {
+  const minor = Number.isFinite(cost.minor) && cost.minor > 0 ? Math.ceil(cost.minor) : 0;
+  const scale = Number.isInteger(cost.scale) ? cost.scale : undefined;
+  return scale === undefined
+    ? { minor, currency: cost.currency }
+    : { minor, currency: cost.currency, scale };
+}
+
+/**
+ * `cost` in units of the ledger's scale (`costScale`), as a bigint. A coarser cost is widened
+ * exactly; a FINER one — a provider pricing to twelve places — is rounded UP to the ledger's
+ * digit, here, in bigint: `minorAt` only widens and throws on the rest, and `rescale` answers a
+ * `Money` whose `minor` can leave the safe range.
+ */
+export function ledgerUnits(cost: Money): bigint {
+  const booked = bookableCost(cost);
+  const target = costScale(booked.currency);
+  const from = moneyScale(booked);
+  if (from <= target) return minorAt(booked, target);
+  return ceilDiv(BigInt(booked.minor), 10n ** BigInt(from - target));
+}

package/src/echo-provider.ts

@@ -2,6 +2,7 @@
 // from ./provider, which owns the real Messages API, because a double and the socket it stands in
 // for are two jobs — and the request half had reached its line ceiling holding both.
 
+import { costOf, exactCostOf } from './cost';
 import { resolveModel } from './model-resolve';
 import type { ModelId } from './models';
 import { modelIds } from './models';
@@ -13,7 +14,7 @@ import type {
   StreamChunk,
   TokenUsage,
 } from './provider';
-import { costOf, estimateTextTokens, estimateTokens, messageText } from './provider';
+import { estimateTextTokens, estimateTokens, messageText } from './provider';
 
 export interface EchoProviderInput {
   /** Fixed replies keyed by the last user message, for eval fixtures. */
@@ -69,6 +70,7 @@ export class EchoProvider implements Provider {
       stopDetails: undefined,
       usage,
       cost: costOf(model, usage),
+      costExact: exactCostOf(model, usage),
     };
   }
 

package/src/errors-retry.ts

@@ -38,6 +38,20 @@ export const AI_ERROR_RETRY = {
   // be both, and registering the code here is what makes the override honoured: core reads an
   // instance `terminal` on an UNREGISTERED code as unclassified.
   X_AI_PROVIDER_UNAVAILABLE: 'retryable',
+  // The two stops an unattended `agent()` run makes, REGISTERED terminal — the deliberate decision
+  // the paragraph above leaves to whoever makes it. A run stopped for repeating itself repeats
+  // itself again, and a run that outlived its declared deadline is the same run against the same
+  // deadline: unclassified, an `agentJob` with `attempts: 3` paid for it three times.
+  X_AGENT_TOOL_LOOP: 'terminal',
+  X_AGENT_DEADLINE: 'terminal',
+  // The four a job otherwise pays for once per attempt, for the same answer: the ceiling does not
+  // move between attempts, a schema two answers failed is a prompt to edit, arguments a model
+  // broke on this request are a schema to simplify, and a refused handle is refused again. The
+  // caller changes the declaration or starts a new run; retrying only re-bills.
+  X_LLM_TRUNCATED: 'terminal',
+  X_LLM_OUTPUT_INVALID: 'terminal',
+  X_LLM_TOOL_ARGUMENTS_INVALID: 'terminal',
+  X_AGENT_TRANSCRIPT_INVALID: 'terminal',
 } as const satisfies Readonly<Partial<Record<AiErrorCode, ErrorRetry>>>;
 
 // `Partial`, so the table may be a subset — but every key is still checked against the declared set,

package/src/errors.ts

@@ -30,6 +30,11 @@ export const AI_ERROR_CODES = [
   'X_VECTOR_UNSCOPED',
   'X_AI_CONTENT_UNSUPPORTED',
   'X_AI_MODEL_UNRESOLVED',
+  'X_AGENT_TOOL_LOOP',
+  'X_AGENT_DEADLINE',
+  'X_LLM_TOOL_ARGUMENTS_INVALID',
+  'X_AGENT_TRANSCRIPT_INVALID',
+  'X_AI_PROVIDER_UNEXPECTED',
 ] as const;
 
 export type AiErrorCode = (typeof AI_ERROR_CODES)[number];
@@ -48,7 +53,8 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_LLM_TRUNCATED: 'the answer hit its maxTokens ceiling before it was complete',
   X_LLM_STREAM_INVALID: 'a streamed answer failed its output schema, and a stream cannot repair',
   X_AGENT_MAX_TURNS: 'an agent hit its turn ceiling without answering',
-  X_AGENT_TOOL_UNEXPOSED: 'an agent lists a tool that is not an MCP-exposed action',
+  X_AGENT_TOOL_UNEXPOSED:
+    'an agent lists a tool that is neither in-process nor an MCP-exposed action',
   X_HIVE_EMPTY: 'a hive split produced no members, so the run did nothing',
   X_EVAL_THRESHOLD: 'an eval scored below its tolerance',
   X_EVAL_BASELINE_MISSING: 'an eval has no recorded baseline to gate against',
@@ -61,6 +67,12 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_VECTOR_UNSCOPED: 'a vector store was read with no tenant bound inside an org request',
   X_AI_CONTENT_UNSUPPORTED: 'an image or document block the role, model or wire format cannot take',
   X_AI_MODEL_UNRESOLVED: 'a model call named no model',
+  X_AGENT_TOOL_LOOP: 'an agent repeated one tool call with one result and was stopped',
+  X_AGENT_DEADLINE: 'an agent ran past its declared deadline and was stopped',
+  X_LLM_TOOL_ARGUMENTS_INVALID: 'a finished turn called a tool with arguments that are not JSON',
+  X_AGENT_TRANSCRIPT_INVALID: 'an agent was asked to continue from a transcript it cannot read',
+  X_AI_PROVIDER_UNEXPECTED:
+    'a provider ended a turn with an unknown reason and an incomplete answer',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Unconditional and
@@ -202,9 +214,20 @@ export class LlmStreamInvalidError extends UltimateError {
  * bad roll — a third attempt only spends money, so this throws instead of looping.
  */
 export class LlmOutputInvalidError extends UltimateError {
-  constructor(input: { prompt: string; attempts: number; issues: string }) {
+  constructor(input: {
+    prompt: string;
+    attempts: number;
+    issues: string;
+    /** The last answer's issues, one per entry — what a job stores; `issues` is the cause's text. */
+    list?: readonly string[];
+  }) {
     super({
       code: 'X_LLM_OUTPUT_INVALID',
+      meta: {
+        prompt: input.prompt,
+        attempts: input.attempts,
+        issues: input.list ?? [input.issues],
+      },
       cause:
         `prompt "${input.prompt}" returned output failing its schema on all ` +
         `${input.attempts} attempts: ${input.issues}`,
@@ -250,7 +273,7 @@ export class AgentToolUnexposedError extends UltimateError {
     super({
       code: 'X_AGENT_TOOL_UNEXPOSED',
       cause: `agent "${input.agent}" lists tools no MCP surface exposes: ${input.tools.join(', ')}`,
-      fix: 'add mcp: { expose: true } to the action named in cause, or drop it from the agent tools list',
+      fix: "inProcessTool({ name, description, input, execute })   # for a tool only this agent may call — or add mcp: { expose: true } to the action named in cause to offer it to MCP clients too, or drop it from the agent's tools",
     });
   }
 }
@@ -291,22 +314,6 @@ export class LlmRefusedError extends UltimateError {
   }
 }
 
-/**
- * The answer was cut off at the enforced ceiling and what arrived does not satisfy the schema.
- * Thrown instead of the repair turn on purpose: the ceiling does not move between attempts, so
- * a second answer truncates at exactly the same place and only spends money.
- */
-export class LlmTruncatedError extends UltimateError {
-  constructor(input: { prompt: string; maxTokens: number }) {
-    super({
-      code: 'X_LLM_TRUNCATED',
-      cause: `prompt "${input.prompt}" was cut off at its ${input.maxTokens}-token ceiling`,
-      fix: `set maxTokens: ${input.maxTokens * 2} on the llm() declaration, or drop fields from its output schema`,
-    });
-  }
-}
-
-/** A prompt was requested at a version whose content hash does not match the registry. */
 export class AiPromptVersionError extends UltimateError {
   constructor(input: { id: string; requested: string; available: readonly string[] }) {
     super({

package/src/failure-disclosure.ts

@@ -4,7 +4,7 @@
 
 import type { Logger } from '@ultimat3/core';
 import { hasPublicCause, isUltimateError, stringField } from '@ultimat3/core';
-import { statusFor } from '@ultimat3/http';
+import { declaredStatusFor, statusFor } from '@ultimat3/http';
 
 /**
  * What may be shown. `code` is absent for an uncoded throw — a foreign `.message` is the server's
@@ -46,6 +46,42 @@ export function discloseFailure(
   };
 }
 
+/**
+ * The verdict for a tool that runs IN PROCESS: the app's own code, called by the agent it was
+ * written for. Its typed refusal — an `UltimateError` built in this process, under a code NOBODY
+ * gave an HTTP status — is shown whole: code, cause, and the fix (the caller's when it has one).
+ * That is the one case the general rule gets wrong for this reader: an unmapped app code defaults
+ * to 500, a 500's cause is hidden, and a model that cannot read why its call was refused makes
+ * the same call again.
+ *
+ * Everything else keeps the general verdict, so nothing internal rides along: an uncoded throw
+ * (a `TypeError`, a driver's own error) shows nothing; a code the framework or the app DECLARED a
+ * status for follows that status — a driver's `X_DB_STATEMENT_FAILED` stays hidden; and a
+ * look-alike object carrying a `code` is not a typed refusal. Never a stack: only authored fields.
+ */
+export function discloseOwnFailure(
+  error: unknown,
+  logger: Logger | undefined,
+  where: string,
+): DisclosedFailure {
+  const code = isUltimateError(error) ? stringField(error, 'code') : undefined;
+  // The model is a REMOTE reader, so the fix it gets is the caller's wherever one was written —
+  // `x actions show …` is no use to it.
+  const callerFix = code === undefined ? undefined : stringField(error, 'callerFix');
+  if (code === undefined || declaredStatusFor(code) !== undefined) {
+    const shown = discloseFailure(error, logger, where);
+    return shown.cause === undefined || callerFix === undefined
+      ? shown
+      : { ...shown, fix: callerFix };
+  }
+  const fix = callerFix ?? stringField(error, 'fix');
+  return {
+    code,
+    cause: stringField(error, 'cause') ?? 'unknown',
+    fix: fix === undefined || fix === '' ? undefined : fix,
+  };
+}
+
 /**
  * A stack's FRAMES and nothing else: every line that is a frame (`    at …`), none that is not.
  * The message is the first line — and, when it spans several, the lines after it until the first