@ultimat3/ai 1.2.0 → 3.0.0

package/src/tools.ts

@@ -2,14 +2,26 @@
 //
 // This is the SAME projection @ultimat3/mcp performs, in a different wire format: an
 // in-app agent calling a tool through the gateway and an external agent calling it over
-// MCP both end at `action.run`, so they authorize identically. There is no "LLM
+// MCP both end at the same `invoke`, so they authorize identically. There is no "LLM
 // permissions" concept in Ultimate, because there is no second authz system.
 //
+// `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, stringField } from '@ultimat3/core';
+import { toMcpInputSchema } from '@ultimat3/schema';
 
 /** The JSON Schema subset the framework emits for tool arguments. */
 export interface JsonSchema {
@@ -63,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. */
@@ -76,10 +139,14 @@ export function toLlmTool(action: ProjectableAction): LlmTool {
   };
 }
 
-/** Every exposed action as a tool definition, in stable name order. */
+/**
+ * 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
+ * offered exactly the same tools.
+ */
 export function toLlmTools(actions: readonly ProjectableAction[]): readonly LlmTool[] {
   return actions
-    .filter((a) => a.mcp?.expose === true)
+    .filter((a) => isMcpExposed(a.mcp))
     .map(toLlmTool)
     .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
@@ -93,24 +160,53 @@ export async function runLlmToolCall(
   call: LlmToolCall,
   actor: Actor,
 ): Promise<LlmToolResult> {
-  const action = actions.find((a) => a.name === call.name && a.mcp?.expose === true);
+  const action = actions.find((a) => a.name === call.name && isMcpExposed(a.mcp));
   if (action === undefined) {
     return { toolUseId: call.id, content: `unknown tool: ${call.name}`, isError: true };
   }
   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

@@ -93,6 +93,27 @@ const ERROR_STATUS: Readonly<Record<string, number>> = {
   overloaded_error: 529,
 };
 
+/**
+ * A 200 whose body carries an `error` object instead of an answer, refused — how a gateway in
+ * front of a model reports a fault it noticed after the headers were sent. Exported because the
+ * non-streaming read needs the identical rule and the identical status table: the envelope arrives
+ * on either transport, and one copy of the mapping is what keeps the gateway's retry decision the
+ * same on both. The twin of `openai-wire.ts`'s.
+ */
+export function throwInBandError(payload: Record<string, unknown>): void {
+  const error = asRecord(payload['error']);
+  if (error === undefined) return;
+  throw inBandFailure(error);
+}
+
+/**
+ * A tool call's arguments, or `{}`. Never a cast: `input` is untrusted, so a string or an array
+ * arriving under `Record<string, unknown>` is a type lie every later reader indexes into.
+ */
+export function asToolInput(value: unknown): Record<string, unknown> {
+  return asRecord(value) ?? {};
+}
+
 interface PendingTool {
   readonly id: string;
   readonly name: string;
@@ -156,7 +177,10 @@ export class MessageStream {
     return {
       text: this.text,
       toolCalls: [...this.toolCalls],
-      stopReason: this.stopReason,
+      // 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.
+      stopReason: this.stopDetails === undefined ? this.stopReason : 'refusal',
       stopDetails: this.stopDetails,
       usage: this.usage,
     };
@@ -237,8 +261,7 @@ export class MessageStream {
   private inputOf(tool: PendingTool): Record<string, unknown> {
     if (tool.json === '') return {};
     try {
-      const parsed: unknown = JSON.parse(tool.json);
-      return asRecord(parsed) ?? {};
+      return asToolInput(JSON.parse(tool.json));
     } catch (error) {
       throw new AiTransportError({
         provider: 'anthropic',
@@ -261,18 +284,25 @@ export class MessageStream {
     return [];
   }
 
+  /**
+   * An `error` EVENT is a failure whether or not it carried a detail — the event type is itself
+   * the report. A body has no such signal, which is why `throwInBandError` reads the object first.
+   */
   private onError(payload: Record<string, unknown>): never {
-    const error = asRecord(payload['error']);
-    const type = typeof error?.['type'] === 'string' ? error['type'] : 'api_error';
-    const message = typeof error?.['message'] === 'string' ? error['message'] : type;
-    throw new AiTransportError({
-      provider: 'anthropic',
-      status: ERROR_STATUS[type],
-      detail: message,
-    });
+    throw inBandFailure(asRecord(payload['error']) ?? {});
   }
 }
 
+function inBandFailure(error: Record<string, unknown>): AiTransportError {
+  const type = typeof error['type'] === 'string' ? error['type'] : 'api_error';
+  const message = typeof error['message'] === 'string' ? error['message'] : type;
+  return new AiTransportError({
+    provider: 'anthropic',
+    status: ERROR_STATUS[type],
+    detail: message,
+  });
+}
+
 function asRecord(value: unknown): Record<string, unknown> | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
   return value as Record<string, unknown>;