@ultimat3/ai 27.8.1 → 27.10.0

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