@ultimat3/ai 27.10.0 → 27.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "27.10.0",
+  "version": "27.10.2",
   "description": "LLM gateway, versioned prompts, evals as tests, embeddings, hybrid vector search, RAG",
   "license": "MIT",
   "type": "module",
@@ -32,15 +32,15 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "27.10.0",
-    "@ultimat3/cache": "27.10.0",
-    "@ultimat3/core": "27.10.0",
-    "@ultimat3/db": "27.10.0",
-    "@ultimat3/http": "27.10.0",
-    "@ultimat3/jobs": "27.10.0",
-    "@ultimat3/money": "27.10.0",
-    "@ultimat3/policy": "27.10.0",
-    "@ultimat3/schema": "27.10.0",
-    "@ultimat3/time": "27.10.0"
+    "@ultimat3/action": "27.10.2",
+    "@ultimat3/cache": "27.10.2",
+    "@ultimat3/core": "27.10.2",
+    "@ultimat3/db": "27.10.2",
+    "@ultimat3/http": "27.10.2",
+    "@ultimat3/jobs": "27.10.2",
+    "@ultimat3/money": "27.10.2",
+    "@ultimat3/policy": "27.10.2",
+    "@ultimat3/schema": "27.10.2",
+    "@ultimat3/time": "27.10.2"
   }
 }

package/src/agent.ts

@@ -60,7 +60,7 @@ import { RESPOND, respondFor } from './respond';
 import { runMeter } from './run-meter';
 import { aiGateway, aiRedactor, installedGateway } from './runtime';
 import type { Sampling } from './sampling';
-import { ignoredSampling, screenSampling } from './sampling';
+import { ignoredSamplingAttribute, screenSampling } from './sampling';
 import type { AgentTool, LlmTool, LlmToolResult, ProjectableAction } from './tools';
 import { asProjectableAction, isOfferedTool, runLlmToolCall, toLlmTools, toolLabel } from './tools';
 
@@ -196,12 +196,15 @@ async function run<
       'agent.max_turns': maxTurns,
       'llm.redacted': rendered !== rawPrompt || !sameSystem(system, rawSystem),
       'llm.prompt_cache': promptCache !== undefined,
-      'llm.sampling.ignored': ignoredSampling(
-        model,
-        bounds.sampling,
-        installedGateway()?.samplingWires?.(model),
-      ).join(','),
     });
+    // Read when the run ends, not here: the gateway may be what registers the model's row.
+    const reportSampling = (): void => {
+      span.setAttributes(
+        ignoredSamplingAttribute(model, bounds.sampling, () =>
+          installedGateway()?.samplingWires?.(model),
+        ),
+      );
+    };
 
     // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
     const gateway = aiGateway(name);
@@ -371,18 +374,21 @@ async function run<
       throw new AgentMaxTurnsError({ agent: name, turns: maxTurns, calls });
     };
     return withBudget(ledger, () =>
-      meter.within(loop).catch((error: unknown) => {
-        const failed = meter.fail(error);
-        // A failed `.run()` / `.continue()` leaves a handle too: the transcript up to the request
-        // the failed turn was answering, with `turns` and `usage` counting what this call was
-        // billed. Without it a retry resumes from the OLD handle, which never heard of that spend
-        // — six truncated continuations billed six times against a ceiling that saw none of them.
-        if (session !== undefined && at.messages.length > 0) {
-          const { usage } = runTotal(model, prior?.usage, meter.billed());
-          withTranscript(failed, sealTranscript(binding, { ...at, usage }));
-        }
-        throw failed;
-      }),
+      meter
+        .within(loop)
+        .catch((error: unknown) => {
+          const failed = meter.fail(error);
+          // A failed `.run()` / `.continue()` leaves a handle too: the transcript up to the request
+          // the failed turn was answering, with `turns` and `usage` counting what this call was
+          // billed. Without it a retry resumes from the OLD handle, which never heard of that spend
+          // — six truncated continuations billed six times against a ceiling that saw none of them.
+          if (session !== undefined && at.messages.length > 0) {
+            const { usage } = runTotal(model, prior?.usage, meter.billed());
+            withTranscript(failed, sealTranscript(binding, { ...at, usage }));
+          }
+          throw failed;
+        })
+        .finally(reportSampling),
     );
   });
 }

package/src/failure-disclosure.ts

@@ -3,7 +3,7 @@
 // it withholds goes to the log as content-free facts (code, name, frames) — never its text.
 
 import type { Logger } from '@ultimat3/core';
-import { hasPublicCause, isUltimateError, stringField } from '@ultimat3/core';
+import { failureStack, hasPublicCause, isUltimateError, stringField } from '@ultimat3/core';
 import { declaredStatusFor, statusFor } from '@ultimat3/http';
 
 /**
@@ -91,7 +91,8 @@ export function discloseOwnFailure(
 const FRAME = /^\s+at\s/;
 
 function framesOf(error: unknown): string | null {
-  const stack = stringField(error, 'stack');
+  // The header restored first: a lost one (`Error`, #773) made `skip` below eat real frames.
+  const stack = failureStack(error);
   if (stack === undefined) return null;
   const lines = stack.split('\n');
   // Skip to the first frame line that FOLLOWS the message: a message may itself contain text

package/src/llm.ts

@@ -50,7 +50,7 @@ import type { RunMeter } from './run-meter';
 import { runMeter } from './run-meter';
 import { aiGateway, aiRedactor, installedGateway } from './runtime';
 import type { Sampling } from './sampling';
-import { ignoredSampling, screenSampling } from './sampling';
+import { ignoredSamplingAttribute, screenSampling } from './sampling';
 
 /** Two attempts total: the answer, then one repair turn. See `LlmOutputInvalidError`. */
 const ATTEMPTS = 2;
@@ -182,12 +182,13 @@ async function generate<
       // an audit asks evidence for, and a redactor that silently stopped matching looks identical
       // to one that had nothing to remove until this attribute separates them.
       'llm.redacted': redacted,
-      'llm.sampling.ignored': ignoredSampling(
-        model,
-        sampling,
-        installedGateway()?.samplingWires?.(model),
-      ).join(','),
     });
+    // Read when the call ends, not here: the gateway may be what registers the model's row.
+    const reportSampling = (): void => {
+      span.setAttributes(
+        ignoredSamplingAttribute(model, sampling, () => installedGateway()?.samplingWires?.(model)),
+      );
+    };
 
     // A cached answer is still data of unknown provenance, so it goes through the schema like
     // any other. One that no longer fits — the schema moved under it — is a miss, not a
@@ -201,7 +202,10 @@ async function generate<
     });
     const hit = await accept(def.output, await cache?.lookup());
     span.setAttribute('llm.cache.hit', hit !== undefined);
-    if (hit !== undefined) return hit.value;
+    if (hit !== undefined) {
+      reportSampling();
+      return hit.value;
+    }
 
     // No `tools` yet: the `respond` projection belongs to the non-streaming path alone. A tool
     // call is emitted whole, so forcing the answer through one leaves a stream with nothing to
@@ -292,9 +296,11 @@ async function generate<
       });
     };
     return withBudget(ledger, () =>
-      answer().catch((error: unknown) => {
-        throw meter.fail(error);
-      }),
+      answer()
+        .catch((error: unknown) => {
+          throw meter.fail(error);
+        })
+        .finally(reportSampling),
     );
   });
 }

package/src/sampling.ts

@@ -11,7 +11,7 @@
 
 import { AiRequestInvalidError } from './errors';
 import type { ModelId } from './models';
-import { modelSpec } from './models';
+import { isModelRegistered, modelSpec } from './models';
 
 export interface Sampling {
   /** 0 to 2. `0` is the most repeatable a model offers; it is not a guarantee of determinism. */
@@ -74,6 +74,8 @@ export function ignoredSampling(
   /** The wire formats of the providers serving `model`, when the gateway can say. */
   wires?: readonly SamplingWire[],
 ): readonly string[] {
+  // Nothing asked, nothing ignored — and no row read: a model none asked of needs none here.
+  if (request.temperature === undefined && request.seed === undefined) return [];
   const accepts = modelSpec(model).sampling;
   // A knob no serving wire has a word for is dropped too — `seed` on the Messages API.
   const sendable = (knob: 'temperature' | 'seed'): boolean =>
@@ -84,3 +86,28 @@ export function ignoredSampling(
     (knob) => request[knob] !== undefined && (accepts?.[knob] !== true || !sendable(knob)),
   );
 }
+
+/**
+ * The `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`.
+ * A model still unregistered by then has no row to report against; the call's own failure says so.
+ */
+export function ignoredSamplingAttribute(
+  model: ModelId,
+  request: Sampling,
+  wires: () => readonly SamplingWire[] | undefined,
+): Record<'llm.sampling.ignored', string> | Record<string, never> {
+  if (request.temperature === undefined && request.seed === undefined) {
+    return { '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(',') };
+  } catch {
+    return {};
+  }
+}