@ultimat3/ai 23.0.0 → 24.0.0

package/src/remote-embedder.ts

@@ -9,6 +9,7 @@
 import { finiteCount, readWithinLimit, renderThrowable } from '@ultimat3/core';
 import type { Embedder } from './embeddings';
 import { normalize } from './embeddings';
+import { detailOf, withoutKey } from './error-body';
 import { AiKeyMissingError, AiTransportError, EmbedderDimMismatchError } from './errors';
 import type { AiFetch } from './fetch-seam';
 
@@ -16,7 +17,6 @@ const API_KEY_ENV = 'EMBEDDINGS_API_KEY';
 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
@@ -124,7 +124,7 @@ export class RemoteEmbedder implements Embedder {
         // and the endpoint is app config, so the rejection is a value this package did not build —
         // and `instanceof` RUNS a `Proxy`'s `getPrototypeOf` trap, whose throw escapes this very
         // `catch` and replaces a coded refusal with an uncoded crash.
-        detail: `${renderThrowable(error)} — no answer within ${timeoutMs}ms (deadline, egress, DNS or TLS)`,
+        detail: `${withoutKey(renderThrowable(error), apiKey)} — no answer within ${timeoutMs}ms (deadline, egress, DNS or TLS)`,
         envVar: API_KEY_ENV,
       });
     }
@@ -132,7 +132,9 @@ export class RemoteEmbedder implements Embedder {
       throw new AiTransportError({
         provider: this.name,
         status: response.status,
-        detail: await detailOf(response.body),
+        // The shared reader and the shared scrub: a proxy echoing the bearer header into its 4xx
+        // body put the key into an error that reaches a log, a span and a problem document.
+        detail: withoutKey(await detailOf(response), apiKey),
         envVar: API_KEY_ENV,
       });
     }
@@ -218,36 +220,3 @@ function asRecord(value: unknown): Record<string, unknown> | undefined {
 function countOf(data: unknown): string {
   return Array.isArray(data) ? String(data.length) : 'no data array';
 }
-
-/**
- * The start of an error body, and never more. `response.text()` read it WHOLE — outside
- * `maxResponseBytes`, which bounds a success only — so a provider streaming an endless 5xx body
- * held the call and its memory forever. Capped through the same counting reader, and decoded from
- * the bytes it kept: `over` still has a detail worth showing.
- */
-async function detailOf(body: ReadableStream<Uint8Array> | null): Promise<string> {
-  if (body === null) return '';
-  const reader = body.getReader();
-  const kept: Uint8Array[] = [];
-  let total = 0;
-  try {
-    while (total < DETAIL_LIMIT) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      kept.push(value);
-      total += value.byteLength;
-    }
-  } catch {
-    // A body that fails mid-read still has whatever arrived; the status is the error's substance.
-  } finally {
-    await reader.cancel().catch(() => undefined);
-    reader.releaseLock();
-  }
-  const bytes = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of kept) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return new TextDecoder().decode(bytes).slice(0, DETAIL_LIMIT);
-}

package/src/respond.ts

@@ -0,0 +1,86 @@
+// The `respond` tool an `llm()` / `agent()` answers through, and the reader that gets the answer
+// back out of a turn: the tool call's arguments, or the prose parsed as JSON. One file so the
+// envelope a non-object `output` is wrapped in and its unwrapping cannot drift apart.
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { toWireSchema } from '@ultimat3/schema';
+import type { GenerateResult } from './provider';
+import type { LlmTool } from './tools';
+
+/**
+ * The tool the model answers through. One name, so the reader never has to guess — and shared
+ * with `agent()`, which offers the app's tools alongside it and needs the same name to tell an
+ * answer from a tool call.
+ */
+export const RESPOND = 'respond';
+
+/** The one property a non-object `output` travels under. */
+const ENVELOPE = 'value';
+
+/** The tool for one `output`, and the reader that undoes whatever the tool did to it. */
+export interface Respond {
+  readonly tool: LlmTool;
+  /** The answer in `result`, unwrapped — or `undefined` when there is none to validate. */
+  read(result: GenerateResult): unknown;
+}
+
+/**
+ * The output schema as the only tool the model may answer through — the spec's "structured
+ * output drives tool use". `toWireSchema` is the projection an MCP client is served, so a model
+ * and an agent are shown one shape, and a schema it cannot express throws HERE, at declaration
+ * time.
+ *
+ * A tool's `input_schema` must be an OBJECT, so any other `output` (`t.string`, `t.number`, an
+ * array) is wrapped in `{ value }` and unwrapped on the way back — never refused: `.stream()` is
+ * documented for `output: t.string`, and the same declaration must work called plainly.
+ */
+export function respondFor(output: StandardSchemaV1): Respond {
+  const schema = toWireSchema(output);
+  const wrapped = schema.type !== 'object';
+  return {
+    tool: {
+      name: RESPOND,
+      description: 'Return the result. Call this exactly once; do not answer in prose.',
+      input_schema: wrapped
+        ? {
+            type: 'object',
+            properties: { [ENVELOPE]: schema },
+            required: [ENVELOPE],
+            additionalProperties: false,
+          }
+        : schema,
+      strict: true,
+    },
+    read(result) {
+      const call = result.toolCalls.find((c) => c.name === RESPOND);
+      if (call !== undefined) return wrapped ? call.input[ENVELOPE] : call.input;
+      // A model that answers in prose is a schema failure, not a crash, so it flows into the
+      // repair turn. For a wrapped output the prose itself may BE the answer (`t.string`), the
+      // rule `.stream()` already applies.
+      const parsed = parseJsonish(result.text);
+      return parsed === undefined && wrapped && result.text !== '' ? result.text : parsed;
+    },
+  };
+}
+
+const FENCE = '```';
+
+/**
+ * The JSON in a prose answer: the first fenced block when there is a closed one, else the whole
+ * text. Two `indexOf` scans, never a backtracking pattern: the regex this replaced re-scanned the
+ * tail from every whitespace position after an unterminated fence — quadratic on model output.
+ */
+export function parseJsonish(text: string): unknown {
+  const open = text.indexOf(FENCE);
+  const close = open === -1 ? -1 : text.indexOf(FENCE, open + FENCE.length);
+  let body = text;
+  if (close !== -1) {
+    body = text.slice(open + FENCE.length, close);
+    if (body.startsWith('json')) body = body.slice('json'.length);
+  }
+  try {
+    return JSON.parse(body.trim());
+  } catch {
+    return undefined;
+  }
+}

package/src/runtime.ts

@@ -77,6 +77,11 @@ export function aiGateway(prompt: string): Gateway {
   return runtime.gateway;
 }
 
+/** The installed gateway, or `undefined` — for a caller that may run without one (`hive()`). */
+export function installedGateway(): Gateway | undefined {
+  return runtime?.gateway;
+}
+
 export function aiEmbedder(): Embedder {
   return runtime?.embedder ?? new HashEmbedder();
 }

package/src/scorers.ts

@@ -4,7 +4,7 @@
 // is a model call, which means it is itself a measuring instrument that can drift — so its
 // prompt is a versioned artifact and its hash is part of the scorer's name.
 
-import { finiteCount } from '@ultimat3/core';
+import { assert, finiteCount, finiteOption } from '@ultimat3/core';
 import type { Gateway } from './gateway';
 import type { Prompt } from './prompt';
 
@@ -81,8 +81,17 @@ export function jsonSchemaValid(required: readonly string[]): Scorer {
   };
 }
 
-/** Graded numeric closeness — 1 at exact, 0 at or beyond `tolerance`. */
+/**
+ * Graded numeric closeness — 1 at exact, 0 at or beyond `tolerance`. `tolerance: 0` is exact match.
+ * Screened at declaration: a `NaN` scored every answer `NaN`, a negative one every answer 0.
+ */
 export function numericTolerance(tolerance: number): Scorer {
+  finiteOption('numericTolerance', 'tolerance', tolerance);
+  assert(
+    tolerance >= 0,
+    `numericTolerance tolerance is ${String(tolerance)}: a distance cannot be negative, so every answer would score 0`,
+    'numericTolerance(0)   # 0 is exact match; a positive tolerance grades closeness',
+  );
   return {
     name: 'numeric-tolerance',
     score: ({ output, expected }) => {
@@ -90,6 +99,8 @@ export function numericTolerance(tolerance: number): Scorer {
       const want = Number.parseFloat((expected ?? '').trim());
       if (Number.isNaN(got) || Number.isNaN(want)) return 0;
       const delta = Math.abs(got - want);
+      // Exact first: at `tolerance: 0`, `0 >= 0` read an exact match as out of range.
+      if (delta === 0) return 1;
       return delta >= tolerance ? 0 : 1 - delta / tolerance;
     },
   };

package/src/tools.ts

@@ -20,21 +20,16 @@
 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';
+import { hasPublicCause, isMcpExposed, isUltimateError, stringField } from '@ultimat3/core';
+import { statusFor } from '@ultimat3/http';
+import type { WireJsonSchema } from '@ultimat3/schema';
+import { toWireSchema } from '@ultimat3/schema';
 
-/** The JSON Schema subset the framework emits for tool arguments. */
-export interface JsonSchema {
-  readonly type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
-  readonly description?: string;
-  readonly properties?: Readonly<Record<string, JsonSchema>>;
-  readonly required?: readonly string[];
-  /** A schema, not just a flag: `@ultimat3/schema` emits one for open records. */
-  readonly additionalProperties?: boolean | JsonSchema;
-  readonly items?: JsonSchema;
-  readonly enum?: readonly (string | number | boolean | null)[];
-  readonly default?: unknown;
-}
+/**
+ * The JSON Schema subset the framework emits for tool arguments — `@ultimat3/schema`'s
+ * `WireJsonSchema`, the one document `.tool()`, `tools/list` and the model are all handed.
+ */
+export type JsonSchema = WireJsonSchema;
 
 /** Anthropic Messages API tool definition shape (`tools[]` on a request). */
 export interface LlmTool {
@@ -91,10 +86,8 @@ 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).
+ * policy decides both. The execution adapter is not shared code and cannot be — `mcp` is this
+ * package's own tier — but the schema is: both publish `@ultimat3/schema`'s `toWireSchema`.
  *
  * `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
@@ -109,7 +102,7 @@ export function asProjectableAction(listed: AgentTool): ProjectableAction {
     name: actionName(listed),
     ...(mcp === undefined ? {} : { mcp }),
     ...(mcp?.description === undefined ? {} : { description: mcp.description }),
-    inputJsonSchema: toMcpInputSchema(listed.input),
+    inputJsonSchema: toWireSchema(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.
@@ -197,15 +190,33 @@ function resultOf(toolUseId: string, output: unknown): LlmToolResult {
   return { toolUseId, content: text ?? 'null' };
 }
 
+/**
+ * What the model reads in place of a cause it may not see. Fixed, so nothing of the throw rides on
+ * it: the provider keeps every request it is sent, and a cause that reached it cannot be recalled.
+ */
+export const HIDDEN_TOOL_CAUSE =
+  'the tool failed inside the server; the details are withheld from this conversation and are in the server logs';
+
 /**
  * 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.
+ *
+ * A 5xx code's cause is shown only when core's `hasPublicCause` allows it — the rule a production
+ * problem document follows (`@ultimat3/http`'s `toProblem`). Hidden, the developer's `fix` goes with
+ * it (a driver writes it from the statement it failed on); a `callerFix` an `UltimateError` built in
+ * this process is authored for a remote reader and stays.
  */
 function describeFailure(error: unknown): string {
   const code = stringField(error, 'code');
   if (code === undefined) return 'tool failed';
+  if (statusFor(code) >= 500 && !hasPublicCause(code)) {
+    const callerFix = isUltimateError(error) ? stringField(error, 'callerFix') : undefined;
+    return callerFix === undefined
+      ? `${code}: ${HIDDEN_TOOL_CAUSE}`
+      : `${code}: ${HIDDEN_TOOL_CAUSE} (fix: ${callerFix})`;
+  }
   const cause = stringField(error, 'cause') ?? 'unknown';
   const fix = stringField(error, 'fix') ?? '';
   return fix === '' ? `${code}: ${cause}` : `${code}: ${cause} (fix: ${fix})`;

package/src/vector-scope.ts

@@ -4,6 +4,7 @@
 // production is a leak nobody finds. Deriving a scope may only ever TIGHTEN it: a scope that
 // could be widened from a call site is not a scope, it is a hint.
 
+import { tryUseContext, UltimateError } from '@ultimat3/core';
 import { VectorScopeWidenedError } from './errors';
 
 export interface VectorScope {
@@ -14,10 +15,22 @@ export interface VectorScope {
    * deny — a row missing the key is invisible, and an empty list matches nothing at all.
    */
   readonly allow?: Readonly<Record<string, readonly string[]>> | undefined;
+  /**
+   * Every tenant, ON PURPOSE — `UNSCOPED`'s mark, and the only way a read with no tenant bound
+   * runs inside a request acting for an org. Meaningless once a tenant is bound, so dropped then.
+   */
+  readonly crossTenant?: true | undefined;
 }
 
-/** The store as constructed: every tenant, every row. The backfill and migration path. */
-export const UNSCOPED: VectorScope = Object.freeze({});
+/**
+ * Every tenant, every row, named on purpose: the backfill and migration path. Pass it as a
+ * store's `scope` (or `.scoped(UNSCOPED)`) where a cross-tenant read is the point. A store opened
+ * with no scope binds no tenant either, but reading it inside an org's request is refused.
+ */
+export const UNSCOPED: VectorScope = Object.freeze({ crossTenant: true });
+
+/** A store's scope when none was given: no tenant, and no cross-tenant opt-in. */
+export const UNBOUND: VectorScope = Object.freeze({});
 
 /** The tenant column value a row carries when its store had no tenant bound. */
 export const NO_TENANT = '';
@@ -33,12 +46,41 @@ export function tenantOf(scope: VectorScope): string {
 export function narrowScope(store: string, base: VectorScope, next: VectorScope): VectorScope {
   const tenant = narrowTenant(store, base.tenant, next.tenant);
   const allow = narrowAllow(base.allow, next.allow);
+  const crossTenant =
+    tenant === undefined && (base.crossTenant === true || next.crossTenant === true);
   return {
     ...(tenant === undefined ? {} : { tenant }),
     ...(allow === undefined ? {} : { allow }),
+    ...(crossTenant ? { crossTenant: true as const } : {}),
   };
 }
 
+/**
+ * Refuse a read that would search every tenant inside a request acting for one. Entities derive
+ * the tenant from the ambient actor; a vector store is bound by `.scoped({ tenant })`, and a
+ * forgotten call answered with every org's rows. Outside a request, or for an actor with no org,
+ * there is no tenant to leak across — a single-tenant app and a job's system actor read as before.
+ */
+export function assertTenantRead(store: string, scope: VectorScope): void {
+  if (scope.tenant !== undefined || scope.crossTenant === true) return;
+  if (tryUseContext()?.actor.orgId === undefined) return;
+  throw new VectorUnscopedError({ store });
+}
+
+/** `X_VECTOR_UNSCOPED`. Its code and title stay in `errors.ts`, beside every other `X_VECTOR_*`. */
+export class VectorUnscopedError extends UltimateError {
+  constructor(input: { store: string }) {
+    super({
+      code: 'X_VECTOR_UNSCOPED',
+      cause:
+        `vector store "${input.store}" was read with no tenant bound, inside a request acting ` +
+        'for an org — the read would answer with every tenant’s rows. A deliberate cross-tenant ' +
+        'read (a backfill, a migration) opens the store with scope: UNSCOPED',
+      fix: 'vectorStore.scoped({ tenant: ctx.actor.orgId })',
+    });
+  }
+}
+
 function narrowTenant(
   store: string,
   base: string | undefined,

package/src/vector.ts

@@ -11,7 +11,14 @@
 import { finiteCount, finiteOption } from '@ultimat3/core';
 import { cosine, tokenize } from './embeddings';
 import { VectorDimMismatchError } from './errors';
-import { NO_TENANT, narrowScope, scopeAdmits, UNSCOPED, type VectorScope } from './vector-scope';
+import {
+  assertTenantRead,
+  NO_TENANT,
+  narrowScope,
+  scopeAdmits,
+  UNBOUND,
+  type VectorScope,
+} from './vector-scope';
 
 export interface VectorRecord {
   readonly id: string;
@@ -44,7 +51,7 @@ export interface HybridSearchInput {
 export interface VectorStore {
   readonly name: string;
   readonly dimension: number;
-  /** The tenant + policy envelope every statement carries. `UNSCOPED` on a fresh store. */
+  /** The tenant + policy envelope every statement carries. `UNBOUND` on a fresh store. */
   readonly scope: VectorScope;
   /** A view of the same rows through a NARROWER envelope. It can only ever tighten. */
   scoped(scope: VectorScope): VectorStore;
@@ -56,10 +63,10 @@ export interface VectorStore {
   /**
    * Delete every row `filter` matches EXCEPT the ids in `keep`, inside this store's scope. What a
    * re-index needs: `indexDocument` upserts a document's new chunks, then prunes the ones the
-   * shorter text no longer produced. Optional so a hand-written store still satisfies the type;
-   * without it a re-index cannot clean up, and says so in `indexDocument`'s doc.
+   * shorter text no longer produced. Required: an optional `prune` was a re-index that silently
+   * left the old tail retrievable on any store that skipped it.
    */
-  prune?(filter: MetadataFilter, keep: readonly string[]): Promise<void>;
+  prune(filter: MetadataFilter, keep: readonly string[]): Promise<void>;
 }
 
 export interface MemoryVectorStoreInput {
@@ -101,7 +108,7 @@ export class MemoryVectorStore implements VectorStore {
     this.input = input;
     this.name = input.name ?? 'memory';
     this.dimension = input.dimension;
-    this.scope = input.scope ?? UNSCOPED;
+    this.scope = input.scope ?? UNBOUND;
     this.records = input.records ?? new Map<string, StoredRecord>();
     // Screened, not clamped: a `NaN` here makes every BM25 score `NaN`, `hit.score > 0` reads
     // false for every document, and `searchText` answers an empty list — zero work reported as a
@@ -136,6 +143,7 @@ export class MemoryVectorStore implements VectorStore {
     k: number,
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
+    assertTenantRead(this.name, this.scope);
     this.assertDimension(vector.length);
     // `k` carries no default, so `??` never sees it and nothing else does either: `slice(0, NaN)`
     // is `[]`, which is a search that answers "no matches" for every query and reports success.
@@ -151,6 +159,7 @@ export class MemoryVectorStore implements VectorStore {
     k: number,
     filter?: MetadataFilter,
   ): Promise<readonly SearchHit[]> {
+    assertTenantRead(this.name, this.scope);
     const width = finiteCount(SUBJECT, 'k', k);
     const candidates = this.candidates(filter);
     if (candidates.length === 0) return [];
@@ -182,6 +191,7 @@ export class MemoryVectorStore implements VectorStore {
    * by exact term match beats one that merely leads a flat vector ranking.
    */
   async hybrid(input: HybridSearchInput): Promise<readonly SearchHit[]> {
+    assertTenantRead(this.name, this.scope);
     // Three bounds, none of which `Math.max` screens — it PROPAGATES a `NaN`. A `NaN` `k` collapses
     // both candidate widths and the final slice to `[]`; a `NaN` `rrfK` makes every fused score
     // `NaN`, and the ranking this method exists to produce becomes whatever order the sort left.