@ultimat3/ai 2.0.0 → 4.0.0

package/src/tools.ts

@@ -8,13 +8,20 @@
 // `run` below is `ProjectableAction`'s — the projection SEAM, which is what carries `invoke`.
 // It is not a member of the action facade: an `action()` is `as`/`tool`/`openapi`/`job`/
 // `contract` and the callable itself, and this header claimed `action.run` until 2026-08.
+// `asProjectableAction` is what BUILDS that seam out of a real `action()`, so an app writes
+// `agent({ tools: [publishPost] })` and never a hand-shaped stand-in — the same union
+// @ultimat3/mcp's `ListedPrimitive` accepts, adapted at this package's own edge because the two
+// wire formats want different schemas (issue #124).
 //
 // The JSON Schema type and the projectable-primitive shape are declared here rather than
 // imported from @ultimat3/mcp: that package is the same tier, so importing it would be a
 // boundary error. Both packages describe the same structural contract.
 
+import type { AnyAction } from '@ultimat3/action';
+import { actionName, invoke, isAction } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
-import { isMcpExposed } from '@ultimat3/core';
+import { isMcpExposed, stringField } from '@ultimat3/core';
+import { toMcpInputSchema } from '@ultimat3/schema';
 
 /** The JSON Schema subset the framework emits for tool arguments. */
 export interface JsonSchema {
@@ -68,6 +75,57 @@ export interface ProjectableAction {
   run(args: { input: unknown; actor: Actor }): Promise<unknown>;
 }
 
+/**
+ * What `agent({ tools })` accepts: the real primitive an app writes, or a pre-projected one.
+ *
+ * The real `action()` comes first because it is what an app has. Until 2026-08 this list took
+ * `ProjectableAction` alone, which no `action()` structurally satisfies — an action carries
+ * `as`/`tool`/`openapi`/`job`/`contract` and never `run` — so the documented shape
+ * `agent({ tools: [publishPost] })` was a `TS2741` and every test in this package hand-built a
+ * stand-in, which is why the suite stayed green over an API that did not compile (issue #124).
+ * `ProjectableAction` stays in the union for a surface that builds its catalog programmatically
+ * and for a test that projects a fake.
+ */
+export type AgentTool = AnyAction | ProjectableAction;
+
+/**
+ * Adapt whatever the author listed. The same shape @ultimat3/mcp's `asProjectable` produces, from
+ * the same `invoke` — an in-app agent and an external MCP client end at one execution path, so one
+ * policy decides both. It is not shared code and cannot be: `mcp` is this package's own tier, and
+ * the two projections narrow the schema differently on purpose (`toWireSchema` publishes only what
+ * that server's arg validator will hold a call to; this one publishes the tool schema the Messages
+ * API reads).
+ *
+ * `isAction` is structural against @ultimat3/action's PRIVATE declaration store, so a look-alike
+ * carrying `kind: 'action'` cannot take the first branch — it falls through as the already
+ * projectable object it claims to be.
+ */
+export function asProjectableAction(listed: AgentTool): ProjectableAction {
+  if (!isAction(listed)) return listed;
+  const mcp = listed.mcp;
+  return {
+    // Throws `X_ACTION_UNREGISTERED` on an unnamed action rather than offering a tool called `''`:
+    // a nameless tool is unaddressable by the model, by `runLlmToolCall` and by the author.
+    name: actionName(listed),
+    ...(mcp === undefined ? {} : { mcp }),
+    ...(mcp?.description === undefined ? {} : { description: mcp.description }),
+    inputJsonSchema: toMcpInputSchema(listed.input),
+    // The actor rides in on the options and `invoke` swaps it inside the one execution path —
+    // the action's own `policy` still decides, and its `input:` still parses what the model sent,
+    // which is what drops a `{ actor: 'admin' }` the model invented before any handler sees it.
+    run: ({ input, actor }) => invoke(listed, input, { surface: 'mcp', actor }),
+  };
+}
+
+/**
+ * The tool's name for an error message, before anything is registered. Never `actionName()`:
+ * `X_AGENT_TOOL_UNEXPOSED` is raised at declaration, where an action beside it in the same module
+ * has no name yet, and a naming failure there would hide the exposure failure being reported.
+ */
+export function toolLabel(listed: AgentTool): string {
+  return listed.name === '' ? '(an unregistered action)' : listed.name;
+}
+
 const EMPTY_SCHEMA: JsonSchema = { type: 'object', properties: {}, additionalProperties: false };
 
 /** One action → one LLM tool definition. Opt-in via `mcp.expose`, same flag as MCP. */
@@ -108,18 +166,47 @@ export async function runLlmToolCall(
   }
   try {
     const output = await action.run({ input: call.input, actor });
-    return { toolUseId: call.id, content: JSON.stringify(output) };
+    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), isError: true };
   }
 }
 
+/**
+ * One tool's return value as the `tool_result` text. `content` is typed `string` and the agent
+ * loop TRUNCATES it, so anything else ends the run in a `TypeError` two frames away — and the
+ * value is an app's, so neither of `JSON.stringify`'s two other answers can be assumed away:
+ * `undefined` for a handler that returns nothing, and a throw on a bigint, a cycle or a `toJSON`
+ * of its own. A throw is reported as what it is — the call SUCCEEDED and its value cannot be
+ * read — never as a failure, because a model told the tool failed calls it again and buys its
+ * side effects twice.
+ */
+function resultOf(toolUseId: string, output: unknown): LlmToolResult {
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(output);
+  } catch {
+    return {
+      toolUseId,
+      content:
+        'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — do not call it again',
+      isError: true,
+    };
+  }
+  return { toolUseId, content: text ?? 'null' };
+}
+
+/**
+ * The thrown value, read STRUCTURALLY and totally. `stringField` from `@ultimat3/core`, never
+ * `typeof e.code === 'string'`: the value is whatever an app's handler, its driver or its SDK
+ * threw, so each read is a getter call or a `Proxy` trap — and it runs inside the catch block
+ * that has nothing left to answer the model with if the probe itself raises.
+ */
 function describeFailure(error: unknown): string {
-  if (typeof error !== 'object' || error === null) return 'tool failed';
-  const e = error as { code?: unknown; cause?: unknown; fix?: unknown };
-  if (typeof e.code !== 'string') return 'tool failed';
-  const cause = typeof e.cause === 'string' ? e.cause : 'unknown';
-  const fix = typeof e.fix === 'string' ? e.fix : '';
-  return fix === '' ? `${e.code}: ${cause}` : `${e.code}: ${cause} (fix: ${fix})`;
+  const code = stringField(error, 'code');
+  if (code === undefined) return 'tool failed';
+  const cause = stringField(error, 'cause') ?? 'unknown';
+  const fix = stringField(error, 'fix') ?? '';
+  return fix === '' ? `${code}: ${cause}` : `${code}: ${cause} (fix: ${fix})`;
 }

package/src/wire.ts

@@ -42,7 +42,11 @@ export function parsePartialUsage(raw: unknown): Partial<TokenUsage> {
   const usage: Partial<Record<keyof TokenUsage, number>> = {};
   for (const [field, wire] of Object.entries(USAGE_FIELDS) as [keyof TokenUsage, string][]) {
     const value = record[wire];
-    if (typeof value === 'number') usage[field] = value;
+    // Floored at zero, and finite: usage is the provider's number, a negative one becomes a
+    // negative `cost`, and `MemoryBudgetStore.add` reads a negative debit as a CREDIT — releasing
+    // an unspent reservation is one — so an unclamped `-1` tops the ledger up instead of
+    // under-reporting it. `NaN` propagates the same way through every later sum.
+    if (typeof value === 'number' && Number.isFinite(value)) usage[field] = Math.max(0, value);
   }
   return usage;
 }
@@ -81,17 +85,23 @@ export function parseStopDetails(raw: unknown): StopDetails | undefined {
  * retry rule in the gateway: an overloaded provider is retryable whether it says so with a
  * 529 on the handshake or with an `overloaded_error` frame ten tokens in.
  */
-const ERROR_STATUS: Readonly<Record<string, number>> = {
-  invalid_request_error: 400,
-  authentication_error: 401,
-  permission_error: 403,
-  not_found_error: 404,
-  request_too_large: 413,
-  rate_limit_error: 429,
-  api_error: 500,
-  timeout_error: 504,
-  overloaded_error: 529,
-};
+// A `Map`, not an object literal: `type` is the PROVIDER's string on the one read below, and
+// `ERROR_STATUS['constructor']` on an object answers the `Object` FUNCTION where
+// `AiTransportError.status` is declared `number | undefined`. Same fix, same reason, as
+// `openai-wire.ts`'s twin and `core`'s `error-retry.ts`.
+const ERROR_STATUS: ReadonlyMap<string, number> = new Map(
+  Object.entries({
+    invalid_request_error: 400,
+    authentication_error: 401,
+    permission_error: 403,
+    not_found_error: 404,
+    request_too_large: 413,
+    rate_limit_error: 429,
+    api_error: 500,
+    timeout_error: 504,
+    overloaded_error: 529,
+  }),
+);
 
 /**
  * A 200 whose body carries an `error` object instead of an answer, refused — how a gateway in
@@ -298,7 +308,7 @@ function inBandFailure(error: Record<string, unknown>): AiTransportError {
   const message = typeof error['message'] === 'string' ? error['message'] : type;
   return new AiTransportError({
     provider: 'anthropic',
-    status: ERROR_STATUS[type],
+    status: ERROR_STATUS.get(type),
     detail: message,
   });
 }