@ultimat3/ai 27.9.0 → 27.10.1

package/src/provider.ts

@@ -1,11 +1,12 @@
-// The `Provider` interface, `AnthropicProvider` (the real Messages API, streaming and not) and
-// the money arithmetic over a call's reported usage — `EchoProvider`, the double, is
-// ./echo-provider's. The REQUEST half only: ./models owns the catalogue and the per-model rules,
+// The `Provider` interface and `AnthropicProvider` (the real Messages API, streaming and not) —
+// `EchoProvider`, the double, is ./echo-provider's, and the money arithmetic is ./cost's
+// (`costOf` is re-exported here, where every caller has always imported it from). The REQUEST half only: ./models owns the catalogue and the per-model rules,
 // ./wire owns the response half.
 
 import type { Money } from '@ultimat3/money';
 import type { AiMediaBlock } from './content-blocks';
 import { assertMediaContent, blockText, mediaTokenEstimate } from './content-blocks';
+import { costOf, exactCostOf } from './cost';
 import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiRequestInvalidError, AiTransportError } from './errors';
 import type { AiFetch } from './fetch-seam';
@@ -15,7 +16,10 @@ import { modelSpec, reasoningBody } from './models';
 import type { PromptCacheHint, SystemPrompt } from './prompt-cache';
 import { promptCacheRule, systemText } from './prompt-cache';
 import { anthropicPrompt } from './prompt-cache-blocks';
+import type { SamplingWire } from './sampling';
+import { samplingBody } from './sampling';
 import { readSse } from './sse';
+import { assertToolArguments } from './tool-arguments';
 import type { LlmTool, LlmToolCall } from './tools';
 import {
   asToolInput,
@@ -83,6 +87,10 @@ export interface GenerateRequest {
   readonly thinking?: ThinkingMode;
   readonly tools?: readonly LlmTool[];
   readonly stopSequences?: readonly string[];
+  /** Sent only to a model whose row takes it (`ModelSpec.sampling`, `./sampling`). 0 to 2. */
+  readonly temperature?: number;
+  /** As `temperature`; chat-completions only — the Messages API has no seed. */
+  readonly seed?: number;
   /**
    * The caller's abort signal, forwarded to the socket by every provider in this package.
    *
@@ -147,8 +155,14 @@ export interface GenerateResult {
   /** Required, not optional: a provider that forgets it turns a refusal into a silent empty answer. */
   readonly stopDetails: StopDetails | undefined;
   readonly usage: TokenUsage;
-  /** Cost of this call, computed from `usage` and the model's prices. */
+  /** Cost of this call in the currency's minor units, rounded up once (`costOf`). */
   readonly cost: Money;
+  /**
+   * The same cost EXACTLY, as `Money` at a finer `scale` (`exactCostOf`) — what a ledger sums, so
+   * a run of cheap calls is rounded once at the end and not once per call. Optional: a `Provider`
+   * an app wrote may not state it, and its `cost` is summed in its place.
+   */
+  readonly costExact?: Money;
 }
 
 /** One streamed increment. `done` carries the assembled result. */
@@ -158,6 +172,8 @@ export type StreamChunk =
   | { readonly type: 'tool-call'; readonly call: LlmToolCall }
   | { readonly type: 'done'; readonly result: GenerateResult };
 
+export { costOf } from './cost';
+
 export interface Provider {
   readonly name: string;
   /** Models this provider can serve. The gateway routes by membership. */
@@ -170,33 +186,8 @@ export interface Provider {
    * can happen.
    */
   marksPromptCache?(model: ModelId): boolean;
-}
-
-/**
- * Cost of one call, in integer minor units. Rounded UP: a fraction of a cent that we round
- * away is money the framework silently absorbs, and under-reporting spend defeats a budget.
- */
-export function costOf(model: ModelId, usage: TokenUsage): Money {
-  // 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.
-  const spec = modelSpec(model);
-  const input = spec.inputPerMillion.minor;
-  // In TWENTIETHS of a minor unit, so the standard multipliers stay integral on any whole price:
-  // a cache read is 0.1x input (2/20) and a 5-minute write 1.25x (25/20) unless the row states
-  // its own — Opus 5.5 reads at 0.05x and Fable 5.1 at 0.025x, which a fixed 0.1x overstated.
-  const read =
-    spec.cacheReadPerMillion === undefined ? input * 2 : spec.cacheReadPerMillion.minor * 20;
-  const write =
-    spec.cacheWritePerMillion === undefined ? input * 25 : spec.cacheWritePerMillion.minor * 20;
-  const inputUnits =
-    usage.inputTokens * input * 20 + usage.cacheReadTokens * read + usage.cacheWriteTokens * write;
-  const inputMinor = divideCeil(inputUnits, 20_000_000);
-  const outputMinor = divideCeil(usage.outputTokens * spec.outputPerMillion.minor, 1_000_000);
-  return { minor: inputMinor + outputMinor, currency: spec.inputPerMillion.currency };
-}
-
-function divideCeil(numerator: number, denominator: number): number {
-  return Math.ceil(numerator / denominator);
+  /** Which wire format this provider speaks, when it is one of the two built in (`./sampling`). */
+  readonly wire?: SamplingWire;
 }
 
 /** Total tokens a usage record accounts for — what a budget is debited by. */
@@ -244,12 +235,14 @@ export function anthropicProvider(input: AnthropicProviderInput): AnthropicProvi
 /**
  * The real Messages API shape. The request-surface rules are encoded rather than documented,
  * because getting them wrong is a 400:
- *   - `temperature`/`top_p`/`top_k` are REJECTED on every current model. Steer with the prompt.
+ *   - `top_p`/`top_k` are never sent, and `temperature` only to a model whose row takes it
+ *     (`ModelSpec.sampling`): a reasoning model rejects all three.
  *   - `thinking.budget_tokens` is REJECTED. Use `output_config.effort`.
  *   - `effort` and adaptive thinking are per-model, and ./models owns which model takes which.
  */
 export class AnthropicProvider implements Provider {
   readonly name = 'anthropic';
+  readonly wire = 'anthropic' as const;
   /** The app's list, never the registry's: a model served elsewhere must not be routed here. */
   readonly models: readonly ModelId[];
   private readonly config: AnthropicProviderInput;
@@ -332,10 +325,13 @@ export class AnthropicProvider implements Provider {
           'the stream ended before message_stop, or with a tool call still open — the answer is truncated',
       });
     }
-    const state = message.state();
+    const { malformed, ...state } = message.state();
+    const cost = costOf(model, state.usage);
+    // After usage is known, so a finished turn with unreadable arguments fails WITH its bill.
+    assertToolArguments({ provider: this.name, model, ...state, malformed, cost });
     yield {
       type: 'done',
-      result: { model, ...state, cost: costOf(model, state.usage) },
+      result: { model, ...state, cost, costExact: exactCostOf(model, state.usage) },
     };
   }
 
@@ -357,6 +353,7 @@ export class AnthropicProvider implements Provider {
       max_tokens: Math.min(request.maxTokens, modelSpec(model).maxOutput),
       messages: prompt.messages,
       ...reasoningBody(model, request.effort, request.thinking),
+      ...samplingBody('anthropic', model, request),
     };
     if (prompt.system !== undefined) body['system'] = prompt.system;
     if (request.tools !== undefined && request.tools.length > 0) body['tools'] = request.tools;
@@ -445,6 +442,7 @@ export function parseMessage(model: ModelId, raw: Record<string, unknown>): Gene
     stopDetails,
     usage,
     cost: costOf(model, usage),
+    costExact: exactCostOf(model, usage),
   };
 }
 

package/src/run-meter.ts

@@ -0,0 +1,147 @@
+// Single responsibility: one run's meter — every provider call an `llm()` or an `agent()` makes
+// goes through it, so the run always knows what it was billed, and a failure can say so.
+//
+// The ledger is not the place to read this from: a ledger is shared (a job's scope, an org's
+// window), and the question a failed job asks is about THIS run.
+
+import { asyncContext, isUltimateError } from '@ultimat3/core';
+import type { AgentRunUsage } from './agent-usage';
+import { addUsage } from './agent-usage';
+import type { Billed } from './billed';
+import { BILLED_META, billedCall, billedOf } from './billed';
+import { addMoney } from './cost';
+import type { GenerateResult } from './provider';
+import { ZERO_USAGE } from './wire';
+
+export interface RunMeter {
+  /**
+   * Await one provider call. Until it reports usage it is UNSETTLED: an abort, a deadline or a
+   * transport failure leaves it that way, and its bill cannot be known from here.
+   */
+  call(work: Promise<GenerateResult>): Promise<GenerateResult>;
+  /** The run so far, re-priced from the summed usage — `undefined` before the first answer. */
+  total(): AgentRunUsage | undefined;
+  /** The run's bill, or `undefined` when no provider call was ever started. */
+  billed(): Billed | undefined;
+  /**
+   * What runs UNDERNEATH this one were billed — a tool that itself calls `llm()` or an `agent()`.
+   * Their failures are read by the model as tool results and never thrown here, so this is the
+   * only way that spend reaches the run that caused it.
+   */
+  below(): Billed | undefined;
+  /** Run `fn` with this meter as the one nested runs report to. */
+  within<T>(fn: () => T): T;
+  /**
+   * `error`, carrying the run's bill on `meta.billed`. Returned for a `throw`, never thrown here.
+   * Only an `UltimateError` has a `meta` to carry it; anything else is returned untouched (the
+   * ledger still holds the bill).
+   */
+  fail(error: unknown): unknown;
+}
+
+// The meter of the run in flight, so a run started underneath it can report upward.
+const meters = asyncContext<{ report(bill: Billed): void }>('an AI run meter');
+
+/** Errors a nested meter already reported upward: their `meta.billed` must not be added again. */
+const reported = new WeakSet<object>();
+
+export function runMeter(): RunMeter {
+  const parent = meters.get();
+  let nested: Billed | undefined;
+  const report = (bill: Billed): void => {
+    nested = nested === undefined ? bill : sum(nested, bill);
+    parent?.report(bill);
+  };
+  let own: AgentRunUsage | undefined;
+  let calls = 0;
+  let unsettled = 0;
+  // Bills that arrived ON an error and were not priced by this meter: a provider's
+  // `X_LLM_TOOL_ARGUMENTS_INVALID`, or a nested run's failure passing through.
+  let carried: Billed | undefined;
+  const counted = new WeakSet<object>();
+
+  const absorb = (error: unknown): void => {
+    const billed = billedOf(error);
+    if (billed === undefined || typeof error !== 'object' || error === null) return;
+    if (counted.has(error) || reported.has(error)) return;
+    counted.add(error);
+    carried = carried === undefined ? billed : sum(carried, billed);
+  };
+
+  const billed = (): Billed | undefined => {
+    const direct = directBill();
+    if (direct === undefined) return nested;
+    return nested === undefined ? direct : sum(direct, nested);
+  };
+  const directBill = (): Billed | undefined => {
+    if (calls === 0 && unsettled === 0 && carried === undefined) return undefined;
+    const mine: Billed = {
+      usage: own?.usage ?? ZERO_USAGE,
+      cost: own?.cost ?? carried?.cost ?? { minor: 0, currency: 'USD' },
+      calls,
+      unsettled,
+    };
+    if (carried === undefined) return mine;
+    return own === undefined
+      ? { ...carried, unsettled: carried.unsettled + unsettled }
+      : sum(mine, carried);
+  };
+
+  return {
+    async call(work) {
+      unsettled += 1;
+      try {
+        const result = await work;
+        unsettled -= 1;
+        calls += 1;
+        own = addUsage(own, result);
+        parent?.report(billedCall(result.usage, result.costExact ?? result.cost));
+        return result;
+      } catch (error) {
+        // The provider answered and billed, then the answer could not be used: settled after all.
+        const bill = billedOf(error);
+        if (bill !== undefined) {
+          unsettled -= 1;
+          absorb(error);
+          parent?.report(bill);
+        }
+        throw error;
+      }
+    },
+    total: () => own,
+    billed,
+    below: () => nested,
+    within: (fn) => meters.run({ report }, fn),
+    fail(error) {
+      absorb(error);
+      // Everything this run was billed already reached the parent call by call.
+      if (parent !== undefined && typeof error === 'object' && error !== null) reported.add(error);
+      const bill = billed();
+      if (bill === undefined || !isUltimateError(error)) return error;
+      // An error is thrown once, by the run it failed, and `meta` is a plain own property the
+      // constructor assigned. Written in place rather than wrapped: a wrapper would be a second
+      // error with a different stack, and every reader upstream matches on the ORIGINAL's code.
+      try {
+        Reflect.set(error, 'meta', { ...error.meta, [BILLED_META]: bill });
+      } catch {
+        // A frozen error keeps the meta it was thrown with.
+      }
+      return error;
+    },
+  };
+}
+
+/** Two bills as one. A cost in another currency cannot be added and is left out of the sum. */
+function sum(a: Billed, b: Billed): Billed {
+  return {
+    usage: {
+      inputTokens: a.usage.inputTokens + b.usage.inputTokens,
+      outputTokens: a.usage.outputTokens + b.usage.outputTokens,
+      cacheReadTokens: a.usage.cacheReadTokens + b.usage.cacheReadTokens,
+      cacheWriteTokens: a.usage.cacheWriteTokens + b.usage.cacheWriteTokens,
+    },
+    cost: a.cost.currency === b.cost.currency ? addMoney(a.cost, b.cost) : a.cost,
+    calls: a.calls + b.calls,
+    unsettled: a.unsettled + b.unsettled,
+  };
+}

package/src/sampling.ts

@@ -0,0 +1,113 @@
+// Single responsibility: the two determinism knobs a request may carry — `temperature` and `seed`
+// — screened once where they are declared, and written onto a wire body only for a model whose
+// row says it takes them.
+//
+// A row decides, never an `if` in a body builder (the rule `reasoningBody` follows): a reasoning
+// model in either family answers a sampling parameter with a 400, and which models those are is
+// the app's catalogue. So `ModelSpec.sampling` is the switch, absent means NOT SENT — every row
+// that predates it keeps sending exactly what it sent — and an asked-for knob the row does not
+// take is left out, not refused: a verifier that asks for `temperature: 0` still runs on a model
+// that has no such control, and `ignoredSampling` is what a span says about it.
+
+import { AiRequestInvalidError } from './errors';
+import type { ModelId } from './models';
+import { isModelRegistered, modelSpec } from './models';
+
+export interface Sampling {
+  /** 0 to 2. `0` is the most repeatable a model offers; it is not a guarantee of determinism. */
+  readonly temperature?: number;
+  /** A whole number. Honoured by chat-completions endpoints that support it; best effort there. */
+  readonly seed?: number;
+}
+
+/** Which knobs each wire HAS. The Messages API has no `seed` at all. */
+const WIRE_KNOBS = {
+  openai: ['temperature', 'seed'],
+  anthropic: ['temperature'],
+} as const;
+
+export type SamplingWire = keyof typeof WIRE_KNOBS;
+
+/** A declaration's knobs, screened: a `NaN` temperature or a fractional seed is a 400 mid-run. */
+export function screenSampling(subject: string, sampling: Sampling): Sampling {
+  const { temperature, seed } = sampling;
+  if (
+    temperature !== undefined &&
+    !(Number.isFinite(temperature) && temperature >= 0 && temperature <= 2)
+  ) {
+    throw new AiRequestInvalidError({
+      detail: `${subject} temperature is ${String(temperature)}; it must be a number from 0 to 2`,
+      fix: `temperature: 0   # on the ${subject}() declaration — 0 to 2, or drop the key`,
+    });
+  }
+  if (seed !== undefined && !Number.isSafeInteger(seed)) {
+    throw new AiRequestInvalidError({
+      detail: `${subject} seed is ${String(seed)}; it must be a whole number`,
+      fix: `seed: 7   # on the ${subject}() declaration — a whole number, or drop the key`,
+    });
+  }
+  return {
+    ...(temperature === undefined ? {} : { temperature }),
+    ...(seed === undefined ? {} : { seed }),
+  };
+}
+
+/** The body fields for the knobs this request asks for AND this model, on this wire, takes. */
+export function samplingBody(
+  wire: SamplingWire,
+  model: ModelId,
+  request: Sampling,
+): Record<string, number> {
+  const accepts = modelSpec(model).sampling;
+  const body: Record<string, number> = {};
+  for (const knob of WIRE_KNOBS[wire]) {
+    const value = request[knob];
+    if (value !== undefined && accepts?.[knob] === true) body[knob] = value;
+  }
+  return body;
+}
+
+/** The knobs a request asked for that no wire will send to `model` — what a span reports. */
+export function ignoredSampling(
+  model: ModelId,
+  request: Sampling,
+  /** The wire formats of the providers serving `model`, when the gateway can say. */
+  wires?: readonly SamplingWire[],
+): readonly string[] {
+  // Nothing asked, nothing ignored — and no row read: a model none asked of needs none here.
+  if (request.temperature === undefined && request.seed === undefined) return [];
+  const accepts = modelSpec(model).sampling;
+  // A knob no serving wire has a word for is dropped too — `seed` on the Messages API.
+  const sendable = (knob: 'temperature' | 'seed'): boolean =>
+    wires === undefined ||
+    wires.length === 0 ||
+    wires.some((wire) => (WIRE_KNOBS[wire] as readonly string[]).includes(knob));
+  return (['temperature', 'seed'] as const).filter(
+    (knob) => request[knob] !== undefined && (accepts?.[knob] !== true || !sendable(knob)),
+  );
+}
+
+/**
+ * The `llm.sampling.ignored` span attribute, set when a run ENDS — answered or failed — never at
+ * its start. The catalogue is the app's, and an app may register it when its gateway is first used
+ * (a gateway built lazily from the env): read at the top of `agent()` / `llm()`, before the gateway
+ * was asked anything, the row was not there yet and a REPORT refused the call `X_AI_MODEL_UNKNOWN`.
+ * A model still unregistered by then has no row to report against; the call's own failure says so.
+ */
+export function ignoredSamplingAttribute(
+  model: ModelId,
+  request: Sampling,
+  wires: () => readonly SamplingWire[] | undefined,
+): Record<'llm.sampling.ignored', string> | Record<string, never> {
+  if (request.temperature === undefined && request.seed === undefined) {
+    return { 'llm.sampling.ignored': '' };
+  }
+  if (!isModelRegistered(model)) return {};
+  // A report never fails the call it describes: an installed gateway may throw from
+  // `samplingWires`, and the attribute is then left out rather than replacing the call's result.
+  try {
+    return { 'llm.sampling.ignored': ignoredSampling(model, request, wires()).join(',') };
+  } catch {
+    return {};
+  }
+}

package/src/tool-arguments.ts

@@ -0,0 +1,88 @@
+// Single responsibility: reading a tool call's argument STRING, and deciding what an unreadable
+// one means once the turn's stop reason is known. One copy for both wire formats, streamed or not.
+//
+// "The arguments are not JSON" is two different events, and neither is the provider being
+// unavailable — which is what both wires used to report it as, under the one code this package
+// classifies retryable, with the answer already billed:
+//   - the turn was CUT OFF mid-arguments. The stop reason says so, and the fragment is dropped: a
+//     fragment is never a call, and `llm()` / `agent()` refuse a truncated turn before reading it.
+//   - the turn FINISHED and the model wrote broken JSON. That is `X_LLM_TOOL_ARGUMENTS_INVALID`,
+//     thrown with the usage the provider reported, so the gateway records the bill instead of
+//     releasing the reservation and nothing retries a request that was answered.
+
+import type { Money } from '@ultimat3/money';
+import { AiProviderUnexpectedError, LlmToolArgumentsError } from './answer-errors';
+import { billedCall } from './billed';
+import type { ModelId } from './models';
+import type { StopReason, TokenUsage } from './provider';
+import { isTruncated } from './provider';
+
+/** A tool call whose arguments could not be read. Never the text: it is the model's, unscreened. */
+export interface MalformedToolCall {
+  readonly name: string;
+  /** Characters of argument text that arrived. */
+  readonly chars: number;
+  /**
+   * The fragments carried neither an `index` nor an `id`, and more than one named a tool: two
+   * calls that cannot be told apart. Refused whole — never run as one call with merged arguments.
+   */
+  readonly unkeyed?: boolean;
+}
+
+/**
+ * The arguments as an object, or `undefined` when the string is not JSON. A blank string is `{}`:
+ * a tool that takes no arguments sends `''` or `'{}'`, and neither is a fault. JSON that is not an
+ * object is `{}` too — `input` is untrusted, and a string under `Record<string, unknown>` is a
+ * type lie every later reader indexes into.
+ */
+export function parseToolArguments(raw: string): Record<string, unknown> | undefined {
+  if (raw.trim() === '') return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : {};
+}
+
+/**
+ * Refuse a FINISHED turn that carried unreadable arguments. Called by a provider once usage is
+ * known — on a stream that is the last frame, long after the call closed — so the error can say
+ * what the answer cost. A truncated turn passes: its fragments were already dropped.
+ */
+export function assertToolArguments(turn: {
+  readonly provider: string;
+  readonly model: ModelId;
+  readonly stopReason: StopReason;
+  readonly malformed: readonly MalformedToolCall[];
+  readonly usage: TokenUsage;
+  readonly cost: Money;
+  /** The raw finish reason, when the wire did not know it (`openai-wire.ts`). */
+  readonly unknownFinish?: string | undefined;
+}): void {
+  // A reason nobody knows is not truncation. A turn that is whole was read as a stop; one that is
+  // not — arguments that do not parse — or one the endpoint itself called an `error`, is refused
+  // by name, with its bill, instead of being guessed at.
+  const unknown = turn.unknownFinish;
+  if (unknown !== undefined && (turn.malformed.length > 0 || unknown.toLowerCase() === 'error')) {
+    throw new AiProviderUnexpectedError({
+      provider: turn.provider,
+      model: turn.model,
+      reason: unknown,
+      billed: billedCall(turn.usage, turn.cost),
+    });
+  }
+  const first = turn.malformed[0];
+  if (first === undefined || isTruncated(turn.stopReason)) return;
+  throw new LlmToolArgumentsError({
+    provider: turn.provider,
+    model: turn.model,
+    tool: first.name,
+    chars: first.chars,
+    unkeyed: first.unkeyed === true,
+    billed: billedCall(turn.usage, turn.cost),
+  });
+}

package/src/tools.ts

@@ -24,7 +24,7 @@ import type { Actor } from '@ultimat3/core';
 import { isMcpExposed, tryUseContext } from '@ultimat3/core';
 import type { WireJsonSchema } from '@ultimat3/schema';
 import { toWireSchema } from '@ultimat3/schema';
-import { discloseFailure } from './failure-disclosure';
+import { discloseFailure, discloseOwnFailure } from './failure-disclosure';
 import { takeToolIdempotencyKey, withToolIdempotencyKey } from './tool-idempotency';
 
 /**
@@ -69,6 +69,14 @@ export interface ProjectableAction {
   readonly description?: string;
   readonly mcp?: { readonly expose?: boolean; readonly description?: string };
   readonly inputJsonSchema?: JsonSchema;
+  /**
+   * The tool runs IN PROCESS — the app's own code, called by its own agent — and is not the
+   * projection of an exposed action. Its typed refusal is then shown to the model whole, as a
+   * structured error (`discloseOwnFailure`); a projected tool keeps the rule MCP follows.
+   */
+  readonly inProcess?: boolean;
+  /** In-process only: `false` withholds its refusals as a projected tool's are. Default `true`. */
+  readonly discloseErrors?: boolean;
   run(args: { input: unknown; actor: Actor }): Promise<unknown>;
 }
 
@@ -147,6 +155,16 @@ export function toLlmTool(action: ProjectableAction): LlmTool {
   };
 }
 
+/**
+ * Whether an agent may be OFFERED this tool: an action an MCP surface exposes (`isMcpExposed`,
+ * core's one predicate — an in-app agent and an external one see the same catalogue of ACTIONS), or
+ * a tool that is this process's alone (`inProcessTool()`), which no surface but the agent sees.
+ */
+export const isOfferedTool = (tool: {
+  readonly mcp?: ProjectableAction['mcp'];
+  readonly inProcess?: boolean;
+}): boolean => tool.inProcess === true || isMcpExposed(tool.mcp);
+
 /**
  * Every exposed action as a tool definition, in stable name order. The gateway and MCP ask
  * `isMcpExposed` — @ultimat3/core's one predicate — so an in-app agent and an external one are
@@ -154,7 +172,7 @@ export function toLlmTool(action: ProjectableAction): LlmTool {
  */
 export function toLlmTools(actions: readonly ProjectableAction[]): readonly LlmTool[] {
   return actions
-    .filter((a) => isMcpExposed(a.mcp))
+    .filter(isOfferedTool)
     .map(toLlmTool)
     .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
@@ -167,8 +185,10 @@ export async function runLlmToolCall(
   actions: readonly ProjectableAction[],
   call: LlmToolCall,
   actor: Actor,
+  /** `discloseErrors: false` withholds every in-process tool's refusal (`agent({ discloseToolErrors })`). */
+  options: { readonly discloseErrors?: boolean } = {},
 ): Promise<LlmToolResult> {
-  const action = actions.find((a) => a.name === call.name && isMcpExposed(a.mcp));
+  const action = actions.find((a) => a.name === call.name && isOfferedTool(a));
   if (action === undefined) {
     return { toolUseId: call.id, content: `unknown tool: ${call.name}`, isError: true };
   }
@@ -177,7 +197,8 @@ export async function runLlmToolCall(
     return resultOf(call.id, output);
   } catch (error) {
     // A policy denial is an outcome the model should read and react to, not a crash.
-    return { toolUseId: call.id, content: describeFailure(error, call.name), isError: true };
+    const content = describeFailure(error, action, options.discloseErrors !== false);
+    return { toolUseId: call.id, content, isError: true };
   }
 }
 
@@ -212,14 +233,38 @@ function resultOf(toolUseId: string, output: unknown): LlmToolResult {
 export const HIDDEN_TOOL_CAUSE =
   'the tool failed inside the server; the details are withheld from this conversation; the server log records its code and where it failed';
 
+/** The most of an in-process refusal's `cause` / `fix` a model is sent. */
+export const OWN_CAUSE_CHARS = 1_000;
+export const OWN_FIX_CHARS = 500;
+
+const clip = (text: string, chars: number): string =>
+  text.length <= chars ? text : `${text.slice(0, chars - 1)}…`;
+
 /**
  * `discloseFailure`'s verdict, rendered as the `tool_result` line — the same rule a hive member's
  * reason follows, so what an agent may read of a throw is decided once. An uncoded throw says only
  * that it failed; a withheld cause becomes `HIDDEN_TOOL_CAUSE`, and the log has the rest.
+ *
+ * An in-process tool's OWN refusal is rendered as JSON — `{ error: { code, cause, fix } }` — the
+ * structured form of the three authored fields, and nothing but them.
  */
-function describeFailure(error: unknown, toolName: string): string {
-  const shown = discloseFailure(error, tryUseContext()?.logger, `tool ${toolName}`);
+function describeFailure(error: unknown, tool: ProjectableAction, disclose: boolean): string {
+  const logger = tryUseContext()?.logger;
+  const where = `tool ${tool.name}`;
+  const own = disclose && tool.inProcess === true && tool.discloseErrors !== false;
+  const shown = own
+    ? discloseOwnFailure(error, logger, where)
+    : discloseFailure(error, logger, where);
   if (shown.code === undefined) return 'tool failed';
+  if (own && shown.cause !== undefined) {
+    // Bounded BEFORE it is serialised: the loop truncates a tool result at `maxToolResultChars`,
+    // and a cut through the middle of this JSON is a string the model cannot read.
+    const cause = clip(shown.cause, OWN_CAUSE_CHARS);
+    const fix = shown.fix === undefined ? undefined : clip(shown.fix, OWN_FIX_CHARS);
+    return JSON.stringify({
+      error: { code: clip(shown.code, 128), cause, ...(fix === undefined ? {} : { fix }) },
+    });
+  }
   const line = `${shown.code}: ${shown.cause ?? HIDDEN_TOOL_CAUSE}`;
   return shown.fix === undefined ? line : `${line} (fix: ${shown.fix})`;
 }

package/src/wire.ts

@@ -11,6 +11,8 @@ import { renderThrowable } from '@ultimat3/core';
 import { AiTransportError } from './errors';
 import type { StopDetails, StopReason, StreamChunk, TokenUsage } from './provider';
 import type { SseFrame } from './sse';
+import type { MalformedToolCall } from './tool-arguments';
+import { parseToolArguments } from './tool-arguments';
 import type { LlmToolCall } from './tools';
 
 export const ZERO_USAGE: TokenUsage = {
@@ -141,6 +143,8 @@ interface PendingTool {
 export interface StreamState {
   readonly text: string;
   readonly toolCalls: readonly LlmToolCall[];
+  /** Calls whose arguments were not JSON — never among `toolCalls`; `openai-wire.ts`'s twin. */
+  readonly malformed: readonly MalformedToolCall[];
   readonly stopReason: StopReason;
   readonly stopDetails: StopDetails | undefined;
   readonly usage: TokenUsage;
@@ -154,6 +158,7 @@ export interface StreamState {
 export class MessageStream {
   private text = '';
   private readonly toolCalls: LlmToolCall[] = [];
+  private readonly malformed: MalformedToolCall[] = [];
   private stopReason: StopReason = 'end_turn';
   private stopDetails: StopDetails | undefined;
   private usage: TokenUsage = ZERO_USAGE;
@@ -199,6 +204,7 @@ export class MessageStream {
     return {
       text: this.text,
       toolCalls: [...this.toolCalls],
+      malformed: [...this.malformed],
       // A refusal detail is a refusal whatever the stop reason says. `parseStopReason` answers
       // `end_turn` for a spelling this build has never seen, and every consumer branches on the
       // REASON, so the pair would read as a complete answer that happens to be empty.
@@ -272,24 +278,19 @@ export class MessageStream {
     const tool = this.pending.get(index);
     if (tool === undefined) return [];
     this.pending.delete(index);
-    const call: LlmToolCall = { id: tool.id, name: tool.name, input: this.inputOf(tool) };
+    // A tool with no arguments streams no `input_json_delta` at all, which is `{}`, not a fault.
+    const input = parseToolArguments(tool.json);
+    if (input === undefined) {
+      // Not thrown here: the block closes BEFORE `message_delta` says why the turn stopped, and
+      // that reason is what tells a cut-off call from broken JSON. The provider decides, at the end.
+      this.malformed.push({ name: tool.name, chars: tool.json.length });
+      return [];
+    }
+    const call: LlmToolCall = { id: tool.id, name: tool.name, input };
     this.toolCalls.push(call);
     return [{ type: 'tool-call', call }];
   }
 
-  /** A tool with no arguments streams no `input_json_delta` at all, which is `{}`, not a fault. */
-  private inputOf(tool: PendingTool): Record<string, unknown> {
-    if (tool.json === '') return {};
-    try {
-      return asToolInput(JSON.parse(tool.json));
-    } catch (error) {
-      throw new AiTransportError({
-        provider: 'anthropic',
-        detail: `tool "${tool.name}" streamed arguments that are not JSON: ${renderThrowable(error)}`,
-      });
-    }
-  }
-
   private onMessageDelta(payload: Record<string, unknown>): readonly StreamChunk[] {
     const delta = asRecord(payload['delta']);
     // ABSENT is not a report, and neither is `null`. `!== null` alone admitted the absent key, so