@ultimat3/ai 1.2.0 → 2.0.0

package/src/redaction.ts

@@ -0,0 +1,22 @@
+// The one gate between `vars()` and the provider: a `Secret` never reaches a prompt.
+//
+// Not a leak check — `Secret` redacts by value, so the string would have arrived as `[redacted]`.
+// It is a CORRECTNESS check, and the same one `render()` already makes for an unfilled `{{slot}}`:
+// a prompt that reads fine and means something else is the failure nobody sees, and here it is
+// also a token bill for an answer about a placeholder.
+
+import { isSecret } from '@ultimat3/core';
+import { AiPromptSecretError } from './errors';
+
+/**
+ * Refuse a `Secret` among a prompt's variables, naming every key that carries one. Runs whether
+ * or not an app installed a redactor: the redactor is the app's policy, this is the framework's
+ * invariant, and an invariant that only holds when something optional is configured is not one.
+ *
+ * Structural (`isSecret` reads the shared brand), so two copies of `@ultimat3/core` in one tree
+ * still recognise each other's secrets.
+ */
+export function assertNoSecrets(ref: string, vars: Readonly<Record<string, unknown>>): void {
+  const keys = Object.keys(vars).filter((key) => isSecret(vars[key]));
+  if (keys.length > 0) throw new AiPromptSecretError({ ref, keys: keys.sort() });
+}

package/src/remote-embedder.ts

@@ -6,6 +6,7 @@
 // vendor: `baseUrl` selects the provider and nothing else changes. A second class per vendor
 // would be a second thing to learn for a difference that does not exist on the wire.
 
+import { readWithinLimit } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { normalize } from './embeddings';
 import { AiKeyMissingError, AiTransportError, EmbedderDimMismatchError } from './errors';
@@ -15,6 +16,14 @@ const DEFAULT_BASE_URL = 'https://api.voyageai.com/v1';
 /** Providers cap a batch around 128 inputs; 96 leaves headroom for long texts. */
 const DEFAULT_BATCH_SIZE = 96;
 const DETAIL_LIMIT = 300;
+/**
+ * A hosted endpoint is a third party and `baseUrl` is app config, so neither its latency nor its
+ * response size is ours to assume. 30s is longer than any healthy embedding batch and shorter than
+ * a job lease; 32 MiB is an order of magnitude past the worst legitimate batch (96 inputs x 3072
+ * dimensions of JSON floats is under 4 MiB), so nothing real hits it and nothing unreal is held.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
 
 export interface RemoteEmbedderInput {
   /** The provider's model id. Doubles as the embedder name, so a store records what wrote it. */
@@ -30,6 +39,10 @@ export interface RemoteEmbedderInput {
   readonly baseUrl?: string;
   /** Inputs per request. Larger calls are split; the provider's own cap is not the caller's. */
   readonly batchSize?: number;
+  /** Deadline for ONE batch request. Defaults to 30s; `AbortSignal.timeout` enforces it. */
+  readonly timeoutMs?: number;
+  /** Bytes this process will hold of one response. Defaults to 32 MiB. */
+  readonly maxResponseBytes?: number;
   /** Injectable so a test can assert the request body without a network. Defaults to `fetch`. */
   readonly fetch?: typeof fetch;
 }
@@ -65,19 +78,53 @@ export class RemoteEmbedder implements Embedder {
       throw new AiKeyMissingError({ provider: this.name, envVar: API_KEY_ENV });
     }
     const doFetch = this.config.fetch ?? fetch;
-    const response = await doFetch(`${this.config.baseUrl ?? DEFAULT_BASE_URL}/embeddings`, {
-      method: 'POST',
-      headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
-      body: JSON.stringify({ model: this.name, input: texts }),
-    });
+    const timeoutMs = this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const url = `${this.config.baseUrl ?? DEFAULT_BASE_URL}/embeddings`;
+    let response: Response;
+    try {
+      response = await doFetch(url, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' },
+        body: JSON.stringify({ model: this.name, input: texts }),
+        // Without this the call has no deadline at all: the per-request budget produces a
+        // `ctx.signal` that never reaches here, so a provider that accepts the connection and
+        // never answers holds a worker for as long as the socket stays open.
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+    } catch (error) {
+      throw new AiTransportError({
+        provider: this.name,
+        detail: `${error instanceof Error ? error.message : 'the request failed before a response'} — no answer within ${timeoutMs}ms (deadline, egress, DNS or TLS)`,
+        envVar: API_KEY_ENV,
+      });
+    }
     if (!response.ok) {
       throw new AiTransportError({
         provider: this.name,
         status: response.status,
         detail: (await response.text().catch(() => '')).slice(0, DETAIL_LIMIT),
+        envVar: API_KEY_ENV,
       });
     }
-    return this.decode((await response.json()) as unknown, texts.length);
+    // Read through core's counting reader rather than `response.json()`: a body is buffered whole
+    // before anything measures it otherwise, and a `content-length` a remote wrote is not a bound.
+    const maxBytes = this.config.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const read = await readWithinLimit(response.body, maxBytes);
+    if ('over' in read) {
+      throw new AiTransportError({
+        provider: this.name,
+        status: response.status,
+        detail: `response body is at least ${read.over} bytes, limit is ${maxBytes}`,
+        envVar: API_KEY_ENV,
+      });
+    }
+    let payload: unknown;
+    try {
+      payload = JSON.parse(new TextDecoder().decode(read.bytes));
+    } catch {
+      throw this.malformed('the response body is not valid JSON');
+    }
+    return this.decode(payload, texts.length);
   }
 
   private decode(payload: unknown, expected: number): readonly Float32Array[] {

package/src/runtime.ts

@@ -24,12 +24,35 @@ export interface AiRuntimeInput {
   readonly embedder?: Embedder;
   /** One cache per scope key. Defaults to the in-memory driver; pgvector in production. */
   readonly semanticCache?: (scope: string) => SemanticCache;
+  /**
+   * The last thing that runs over a prompt before it leaves the process. Declared here, in the
+   * one place the framework already owns, because `vars()` is the one declared place a model call
+   * loads data — the framework knows exactly where the row enters the prompt, and until now
+   * nothing sat between that and a third-party endpoint.
+   *
+   * WHAT to remove is the app's decision, not the framework's: a PII classifier is a model choice
+   * and ships in no framework (axiom 8). Ultimate ships the seam, the span attribute
+   * (`llm.redacted`) and the one rule it can enforce structurally — a `Secret` reaching `vars()`
+   * is `X_AI_PROMPT_SECRET`, whether or not a redactor is installed.
+   */
+  readonly redact?: Redactor;
 }
 
+/**
+ * Rewrites a prompt on its way to the provider. Sees the whole RENDERED text, system prompt
+ * included — template as well as values, because a redactor shown only the values cannot tell
+ * a name in a data slot from the same name in an instruction.
+ */
+export type Redactor = (text: string) => string;
+
+/** No app redactor installed. Named rather than inline so `llm.redacted` has one thing to mean. */
+const noRedaction: Redactor = (text) => text;
+
 interface AiRuntime {
   readonly gateway: Gateway;
   readonly embedder: Embedder;
   readonly semanticCache: (scope: string) => SemanticCache;
+  readonly redact: Redactor;
 }
 
 let runtime: AiRuntime | undefined;
@@ -40,6 +63,7 @@ export function configureAi(input: AiRuntimeInput): void {
     gateway: input.gateway,
     embedder: input.embedder ?? new HashEmbedder(),
     semanticCache: input.semanticCache ?? (() => createMemorySemanticCache()),
+    redact: input.redact ?? noRedaction,
   };
   // A new runtime means a new embedder and a new gateway; vectors from the old one are not
   // comparable to vectors from the new one, and a stale hit would answer the wrong question.
@@ -56,6 +80,11 @@ export function aiEmbedder(): Embedder {
   return runtime?.embedder ?? new HashEmbedder();
 }
 
+/** The installed redactor, or the identity. Never absent, so the call site has no branch. */
+export function aiRedactor(): Redactor {
+  return runtime?.redact ?? noRedaction;
+}
+
 /**
  * The cache for one scope. Scopes are separate CACHE INSTANCES, never a filter over a shared
  * one: cosine similarity has no notion of a tenant, so two tenants asking near-identical

package/src/tools.ts

@@ -2,14 +2,19 @@
 //
 // 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.
+//
 // 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 { Actor } from '@ultimat3/core';
+import { isMcpExposed } from '@ultimat3/core';
 
 /** The JSON Schema subset the framework emits for tool arguments. */
 export interface JsonSchema {
@@ -76,10 +81,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,7 +102,7 @@ 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 };
   }

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>;