@ultimat3/ai 30.9.0 → 31.1.0

package/src/runtime.ts

@@ -1,5 +1,6 @@
 // The ambient AI runtime an `llm()` action calls into: the gateway that serves every model
-// call, the embedder the semantic cache keys on, and one semantic cache per declared scope.
+// call, the embedder the semantic cache keys on, and one semantic cache per declared scope. All
+// three are adapter ports, filled from `apps/<app>/runtime.ts` through `@ultimat3/ai/adapter`.
 //
 // Ambient rather than injected, for the same reason the budget ledger is: an `llm()`
 // declaration is evaluated at module scope, long before a provider, an API key or a request
@@ -10,21 +11,19 @@
 import type { SemanticCache } from '@ultimat3/cache';
 import { memorySemanticCache } from '@ultimat3/cache';
 import { asyncContext, cachedFormatter } from '@ultimat3/core';
+import { type AdapterSlot, adapterSlot } from '@ultimat3/core/adapter';
 import type { Embedder } from './embeddings';
 import { hashEmbedder } from './embeddings';
 import { AiGatewayMissingError } from './errors';
 import type { Gateway } from './gateway';
 
+/**
+ * The AI runtime's configuration — the redactor, and nothing that selects a backend. The gateway,
+ * the embedder and the semantic-cache factory are ports with one way in each: `aiGateway`,
+ * `embedder` and `semanticCache` in `apps/<app>/runtime.ts`, installed by the boot through
+ * `@ultimat3/ai/adapter`. `gateway`, `embedder` and `semanticCache` left this input in 31.0.0.
+ */
 export interface AiRuntimeInput {
-  readonly gateway: Gateway;
-  /**
-   * Keys the semantic cache. Defaults to `HashEmbedder`: deterministic, offline, and lexical
-   * rather than semantic — at the thresholds an LLM cache runs at that is a near-exact-match
-   * cache, which is the safe way to be wrong. Install a real embedder to get paraphrase hits.
-   */
-  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
@@ -33,7 +32,7 @@ export interface AiRuntimeInput {
    *
    * 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()`
+   * (`ultimate.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;
@@ -46,28 +45,73 @@ export interface AiRuntimeInput {
  */
 export type Redactor = (text: string) => string;
 
-/** No app redactor installed. Named rather than inline so `llm.redacted` has one thing to mean. */
+/** No app redactor installed. Named rather than inline so `ultimate.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;
-}
+/**
+ * The `semanticCache` port: one cache per scope key. A FACTORY, because scopes are separate cache
+ * instances (`semanticCacheFor`). Default: a `memorySemanticCache()` per scope, per process.
+ */
+export type SemanticCacheFactory = (scope: string) => SemanticCache;
 
-let runtime: AiRuntime | undefined;
+let redactor: Redactor = noRedaction;
+/** The `aiGateway` port's ONE slot, written only by `installAiGateway`. */
+const gatewaySlot = /* @__PURE__ */ adapterSlot<Gateway | undefined>(() => undefined);
+/**
+ * The `embedder` port. Default `hashEmbedder()`: deterministic, offline and lexical rather than
+ * semantic — at the thresholds an LLM cache runs at that is a near-exact-match cache, which is the
+ * safe way to be wrong. Install a real embedder (`remoteEmbedder`) to get paraphrase hits.
+ */
+const embedderSlot = /* @__PURE__ */ adapterSlot<Embedder>(() => fallbackEmbedder());
+/** The `semanticCache` port. Default the in-memory driver; pgvector in production. */
+const semanticCacheSlot = /* @__PURE__ */ adapterSlot<SemanticCacheFactory>(() => memoryPerScope);
+const memoryPerScope: SemanticCacheFactory = () => memorySemanticCache();
+let hashed: Embedder | undefined;
+/** One default embedder per process, built on first use rather than at import. */
+const fallbackEmbedder = (): Embedder => {
+  hashed ??= hashEmbedder();
+  return hashed;
+};
 const caches = new Map<string, SemanticCache>();
 
-export function configureAi(input: AiRuntimeInput): void {
-  runtime = {
-    gateway: input.gateway,
-    embedder: input.embedder ?? hashEmbedder(),
-    semanticCache: input.semanticCache ?? (() => memorySemanticCache()),
-    redact: input.redact ?? noRedaction,
+/**
+ * Install into a slot whose value every cached `SemanticCache` was built against, and clear the
+ * caches on the install and on the release alike: vectors from two embedders are not comparable,
+ * and a test's double must never be served what the real backend answered (and back).
+ */
+function installClearing<T>(slot: AdapterSlot<T>, value: T): () => void {
+  const release = slot.install(value);
+  caches.clear();
+  return () => {
+    release();
+    caches.clear();
   };
-  // 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.
+}
+
+/**
+ * The boot's install of the `aiGateway` port, from `@ultimat3/ai/adapter` only. Answers the release
+ * that removes THIS install and no other (core's `adapterSlot`), in any order, once.
+ */
+export function installAiGateway(gateway: Gateway): () => void {
+  // A cached answer is one gateway's: kept across a swap, a test's double would be served what
+  // the real gateway answered (and back).
+  return installClearing(gatewaySlot, gateway);
+}
+
+/** The boot's install of the `embedder` port, from `@ultimat3/ai/adapter` only. Answers its release. */
+export function installAiEmbedder(embedder: Embedder): () => void {
+  return installClearing(embedderSlot, embedder);
+}
+
+/** The boot's install of the `semanticCache` port, from `@ultimat3/ai/adapter` only. */
+export function installSemanticCache(factory: SemanticCacheFactory): () => void {
+  return installClearing(semanticCacheSlot, factory);
+}
+
+/** Replace the runtime's configuration; an omitted field takes its default. Clears the caches. */
+export function configureAi(input: AiRuntimeInput = {}): void {
+  redactor = input.redact ?? noRedaction;
+  // What a test calls between cases to start from empty caches; harmless anywhere else.
   caches.clear();
 }
 
@@ -108,22 +152,24 @@ export function currentEvalScope(): EvalScope | undefined {
 export function aiGateway(prompt: string): Gateway {
   const scoped = evalScopes.get()?.gateway;
   if (scoped !== undefined) return scoped;
-  if (runtime === undefined) throw new AiGatewayMissingError({ prompt });
-  return runtime.gateway;
+  const installed = gatewaySlot.current();
+  if (installed === undefined) throw new AiGatewayMissingError({ prompt });
+  return installed;
 }
 
 /** The installed gateway, or `undefined` — for a caller that may run without one (`hive()`). */
 export function installedGateway(): Gateway | undefined {
-  return evalScopes.get()?.gateway ?? runtime?.gateway;
+  return evalScopes.get()?.gateway ?? gatewaySlot.current();
 }
 
+/** The installed embedder (`embedder` port), or the process's hash embedder. */
 export function aiEmbedder(): Embedder {
-  return runtime?.embedder ?? hashEmbedder();
+  return embedderSlot.current();
 }
 
 /** The installed redactor, or the identity. Never absent, so the call site has no branch. */
 export function aiRedactor(): Redactor {
-  return runtime?.redact ?? noRedaction;
+  return redactor;
 }
 
 /**
@@ -139,15 +185,14 @@ export function aiRedactor(): Redactor {
  * no entries at all and the memory one loses a cache.
  */
 export function semanticCacheFor(scope: string): SemanticCache {
-  return cachedFormatter(
-    caches,
-    scope,
-    () => runtime?.semanticCache(scope) ?? memorySemanticCache(),
-  );
+  return cachedFormatter(caches, scope, () => semanticCacheSlot.current()(scope));
 }
 
 /** Test-only reset. Module-level state otherwise leaks between test files. */
 export function resetAiRuntime(): void {
-  runtime = undefined;
+  redactor = noRedaction;
+  gatewaySlot.reset();
+  embedderSlot.reset();
+  semanticCacheSlot.reset();
   caches.clear();
 }

package/src/sampling.ts

@@ -88,7 +88,7 @@ export function ignoredSampling(
 }
 
 /**
- * The `llm.sampling.ignored` span attribute, set when a run ENDS — answered or failed — never at
+ * The `ultimate.llm.sampling.ignored` span attribute, set when a run ENDS — answered or failed — never at
  * its start. The catalogue is the app's, and an app may register it when its gateway is first used
  * (a gateway built lazily from the env): read at the top of `agent()` / `llm()`, before the gateway
  * was asked anything, the row was not there yet and a REPORT refused the call `X_AI_MODEL_UNKNOWN`.
@@ -98,15 +98,15 @@ export function ignoredSamplingAttribute(
   model: ModelId,
   request: Sampling,
   wires: () => readonly SamplingWire[] | undefined,
-): Record<'llm.sampling.ignored', string> | Record<string, never> {
+): Record<'ultimate.llm.sampling.ignored', string> | Record<string, never> {
   if (request.temperature === undefined && request.seed === undefined) {
-    return { 'llm.sampling.ignored': '' };
+    return { 'ultimate.llm.sampling.ignored': '' };
   }
   if (!isModelRegistered(model)) return {};
   // A report never fails the call it describes: an installed gateway may throw from
   // `samplingWires`, and the attribute is then left out rather than replacing the call's result.
   try {
-    return { 'llm.sampling.ignored': ignoredSampling(model, request, wires()).join(',') };
+    return { 'ultimate.llm.sampling.ignored': ignoredSampling(model, request, wires()).join(',') };
   } catch {
     return {};
   }

package/src/scorers.ts

@@ -52,7 +52,7 @@ export interface Scorer {
  * `"score": null` for a `NaN`, which `parseBaseline` then refuses as `X_EVAL_BASELINE_INVALID`.
  */
 export const clampScore = (n: number): number =>
-  Number.isFinite(n) ? (n < 0 ? 0 : n > 1 ? 1 : n) : n > 0 ? 1 : 0;
+  Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : n > 0 ? 1 : 0;
 
 /** Exact match after trimming. The strictest and cheapest scorer; prefer it when it fits. */
 export const exact: Scorer = {

package/src/tools.ts

@@ -28,7 +28,7 @@ import {
 } from '@ultimat3/action';
 import type { Actor } from '@ultimat3/core';
 import {
-  isMcpExposed,
+  isAgentOffered,
   isUltimateError,
   stringField,
   toolDescription,
@@ -82,7 +82,11 @@ export interface LlmToolResult {
 export interface ProjectableAction {
   readonly name: string;
   readonly description?: string;
-  readonly mcp?: { readonly expose?: boolean; readonly description?: string };
+  readonly mcp?: {
+    readonly expose?: boolean;
+    readonly agents?: 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
@@ -194,19 +198,19 @@ 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
+ * Whether an agent may be OFFERED this tool: an action an MCP surface exposes or one declared
+ * `agents: true` (`isAgentOffered`, core's one predicate — an in-app agent sees every exposed
+ * action, plus the ones offered here and published nowhere, such as `mcpTools()`'s), 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);
+}): boolean => tool.inProcess === true || isAgentOffered(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
- * offered exactly the same tools.
+ * Every offered action as a tool definition, in stable name order — `isOfferedTool`, so an in-app
+ * agent sees every action an external MCP client sees, plus those declared for agents only.
  */
 export function toLlmTools(actions: readonly ProjectableAction[]): readonly LlmTool[] {
   return actions

package/src/vector.ts

@@ -141,8 +141,10 @@ export class MemoryVectorStore implements VectorStore {
 
   async upsert(records: readonly VectorRecord[]): Promise<void> {
     const tenant = this.scope.tenant ?? NO_VECTOR_TENANT;
+    // Every width checked before any row is written, as `PostgresVectorStore.upsert` does: checked
+    // per record, a refused batch had already written the rows ahead of the bad one.
+    for (const record of records) this.assertDimension(record.vector.length);
     for (const record of records) {
-      this.assertDimension(record.vector.length);
       this.records.set(storageKey(tenant, record.id), { ...record, tenant });
     }
   }