@ultimat3/ai 30.9.0 → 31.0.0

package/src/agent-tools.ts

@@ -0,0 +1,123 @@
+/**
+ * One model turn's tool calls, run as a BOUNDED fan-out: at most `concurrency` in flight, results in
+ * the order the model emitted the calls. The bound is what stands between an injected or confused
+ * model asking for N calls and N concurrent invocations — and N pool checkouts — in one process.
+ */
+
+import type { Actor, Ctx } from '@ultimat3/core';
+import { throwIfAborted } from '@ultimat3/core';
+import type { RunDeadline } from './agent-guards';
+import type { EmitChunk } from './agent-stream';
+import { assistantTurn, toolResultTurn } from './agent-transcript';
+import type { AiMessage, GenerateResult } from './provider';
+import type { LlmToolCall, LlmToolResult, ProjectableAction } from './tools';
+import { runLlmToolCall } from './tools';
+
+/**
+ * Calls of one turn in flight at once, unless the agent declares `maxToolConcurrency`. Eight keeps
+ * the speed-up of a turn that asked for a handful (serial cost 5x wall clock for five) while a turn
+ * that asked for fifty cannot drain a database pool sized for the whole process.
+ */
+export const DEFAULT_TOOL_CONCURRENCY = 8;
+
+export interface ToolBatchOptions {
+  readonly concurrency: number;
+  readonly discloseErrors?: boolean;
+  /** Asked before EACH call starts — the run's abort and deadline checks: a throw starts nothing more. */
+  readonly beforeCall?: () => void;
+}
+
+/**
+ * Runs `calls` with at most `concurrency` in flight. Order is by INDEX, not by completion: each
+ * worker writes its result into the call's own slot, so a fast tool answering first cannot be paired
+ * with a slow tool's call. A worker takes its next call only after `beforeCall` passed, so a run that
+ * was aborted or ran out of time mid-batch starts nothing new.
+ */
+export async function runToolBatch(
+  tools: readonly ProjectableAction[],
+  calls: readonly LlmToolCall[],
+  actor: Actor,
+  options: ToolBatchOptions,
+): Promise<readonly LlmToolResult[]> {
+  const results: LlmToolResult[] = new Array<LlmToolResult>(calls.length);
+  const disclosure =
+    options.discloseErrors === undefined ? {} : { discloseErrors: options.discloseErrors };
+  let next = 0;
+  const worker = async (): Promise<void> => {
+    while (next < calls.length) {
+      const index = next;
+      next += 1;
+      const call = calls[index];
+      if (call === undefined) continue;
+      options.beforeCall?.();
+      results[index] = await runLlmToolCall(tools, call, actor, disclosure);
+    }
+  };
+  const width = Math.max(1, Math.min(options.concurrency, calls.length));
+  await Promise.all(Array.from({ length: width }, worker));
+  return results;
+}
+
+/** What one run's tool turns share — fixed before the first turn. */
+export interface ToolRun {
+  readonly tools: readonly ProjectableAction[];
+  readonly ctx: Ctx;
+  /** Read ONCE from `ctx`, never from the model: the only identity any tool runs as. */
+  readonly actor: Actor;
+  readonly deadline: RunDeadline;
+  readonly emit: EmitChunk;
+  readonly concurrency: number;
+  readonly discloseErrors: boolean;
+  readonly maxTurns: number;
+  readonly chars: number;
+  readonly redact: (text: string) => string;
+  readonly repeated: (calls: readonly LlmToolCall[], results: readonly LlmToolResult[]) => void;
+}
+
+/**
+ * One turn that asked for tools: run them, stream what happened, refuse a repeating loop, and
+ * answer with the transcript the next turn sends. `answers` are the same turn's `respond` calls.
+ */
+export async function toolTurn(
+  run: ToolRun,
+  turn: number,
+  result: GenerateResult,
+  requested: readonly LlmToolCall[],
+  answers: readonly LlmToolCall[],
+  messages: readonly AiMessage[],
+): Promise<readonly AiMessage[]> {
+  const { deadline, emit } = run;
+  const stop = (): void => {
+    throwIfAborted(run.ctx);
+    deadline.check();
+  };
+  stop();
+  for (const call of requested) emit({ type: 'tool_call', turn, id: call.id, name: call.name });
+  const results = await deadline.guard(
+    // Inside the deadline's scope, so each tool's own `ctx.signal` carries it.
+    deadline.scope(() =>
+      runToolBatch(run.tools, requested, run.actor, {
+        concurrency: run.concurrency,
+        discloseErrors: run.discloseErrors,
+        beforeCall: stop,
+      }),
+    ),
+  );
+  results.forEach((done, index) => {
+    const name = requested[index]?.name ?? '';
+    emit({ type: 'tool_result', turn, id: done.toolUseId, name, isError: done.isError === true });
+  });
+  emit({ type: 'turn', turn, maxTurns: run.maxTurns });
+  // Before the next turn is bought: the same calls with the same results cannot lead anywhere a
+  // further turn would not also lead.
+  run.repeated(requested, results);
+  return [
+    ...messages,
+    assistantTurn(result),
+    // Parallel tool use — one turn asking for a tool AND answering — is normal, and the answer is
+    // speculative: it was written before the result it asked for existed. So the loop continues,
+    // and the answer is REJECTED on the wire rather than dropped, because a replayed `respond`
+    // block with no `tool_result` is a 400 and the whole run becomes `X_AI_PROVIDER_UNAVAILABLE`.
+    toolResultTurn(results, run.chars, answers, run.redact),
+  ];
+}

package/src/agent-turn.ts

@@ -4,11 +4,14 @@
 
 import type { Span } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { SUBJECT } from './agent-declared';
 import type { AgentDef, AgentTurn } from './agent-def';
+import { LlmTruncatedError } from './answer-errors';
 import { LlmRefusedError } from './errors';
 import { moreCapableThan } from './models';
 import type { PromptVars } from './prompt';
 import type { GenerateRequest, GenerateResult } from './provider';
+import { isTruncated } from './provider';
 
 /**
  * One turn, reported twice: onto the span every run already opens, and to the declaration's own
@@ -26,13 +29,13 @@ export async function observeTurn<
   span.addEvent('agent.turn', {
     'agent.turn': event.turn,
     'agent.turn.tool_calls': event.toolCalls.length,
-    'llm.stop': event.stopReason,
-    'llm.cost.minor': event.cost.minor,
+    'ultimate.llm.stop': event.stopReason,
+    'ultimate.llm.cost.minor': event.cost.minor,
     'agent.turn.repair': event.repairOf !== undefined,
     // What the provider's prompt cache did for this turn — the two numbers that say whether the
     // stable prefix is really stable.
-    'llm.cache.read_tokens': event.usage.cacheReadTokens,
-    'llm.cache.write_tokens': event.usage.cacheWriteTokens,
+    'ultimate.llm.cache.read_tokens': event.usage.cacheReadTokens,
+    'ultimate.llm.cache.write_tokens': event.usage.cacheWriteTokens,
   });
   await def.onTurn?.(event);
 }
@@ -43,6 +46,13 @@ export function assertAnswerable(
   name: string,
   request: GenerateRequest,
 ): void {
+  // A turn cut off at the ceiling carries arguments that stop wherever the ceiling fell — `{}` on
+  // both wires for a call that never reached its first byte — so running a tool on them is a side
+  // effect the model did not ask for, and validating them accepts an empty answer for any `output`
+  // of optional keys. Refused before a tool runs and before the answer is read.
+  if (isTruncated(result.stopReason)) {
+    throw new LlmTruncatedError({ prompt: name, maxTokens: request.maxTokens, subject: SUBJECT });
+  }
   if (result.stopReason !== 'refusal') return;
   throw new LlmRefusedError({
     prompt: name,

package/src/agent.ts

@@ -1,13 +1,10 @@
 /**
  * `agent()` — a multi-turn tool-using model call, declared as an `action`.
  *
- * One more instance of the framework's rule — the whole list is `PRIMITIVE_FACTORIES` in
- * `@ultimat3/core`: a new capability arrives as a FACTORY over an existing primitive, never as a
- * ninth kind, and the list is what a reader counts instead of a sentence in one of them that
- * cannot see the rest. A tool-using run is
- * still one server-authoritative operation with an input schema, an output schema and a policy —
- * so this returns an `action`, and inherits `.openapi()`, `.client()`, `.job()`, `.contract()`,
- * its MCP tool (`@ultimat3/mcp`'s `toolFrom`) and its manifest row without a line here.
+ * A FACTORY over an existing primitive (`PRIMITIVE_FACTORIES` in `@ultimat3/core`), never a ninth
+ * kind: a tool-using run is still one server-authoritative operation with an input schema, an
+ * output schema and a policy — so this returns an `action`, and inherits `.openapi()`, `.client()`,
+ * `.job()`, `.contract()`, its MCP tool (`toolFrom`) and its manifest row without a line here.
  *
  * It exists because the alternative is a hand-rolled loop outside the framework, and a hand-rolled
  * loop is where the dangerous mistake lives: taking the ACTOR from the model's output. Here the
@@ -23,7 +20,7 @@
 import type { Action } from '@ultimat3/action';
 import { action, noteToolNames } from '@ultimat3/action';
 import type { Ctx } from '@ultimat3/core';
-import { throwIfAborted, withSpan } from '@ultimat3/core';
+import { finiteCount, throwIfAborted, withSpan } from '@ultimat3/core';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
 import { checkpointer } from './agent-checkpoint';
@@ -32,14 +29,7 @@ import { compactor } from './agent-compact';
 import type { CompactPlan } from './agent-compact-def';
 import { screenCompact } from './agent-compact-def';
 import type { AgentAction, TranscriptBinding } from './agent-continue';
-import {
-  claimAgentSession,
-  continued,
-  screenTranscript,
-  sealTranscript,
-  sessionCalls,
-  withTranscript,
-} from './agent-continue';
+import { continued, screenTranscript, sealTranscript, withTranscript } from './agent-continue';
 import { factsOf, limitsOf, SUBJECT, screenBounds } from './agent-declared';
 import type { AgentDef } from './agent-def';
 import { AgentTranscriptInvalidError } from './agent-errors';
@@ -50,20 +40,23 @@ import { project, resolvePerRun } from './agent-per-run';
 import { assertRunCost } from './agent-run-limits';
 import type { TurnSend } from './agent-send';
 import { sendTurn } from './agent-send';
+import { claimAgentSession, sessionCalls } from './agent-session';
 import type { EmitChunk } from './agent-stream';
 import { AgentChunk, streamOf } from './agent-stream';
 import { sameSystem, systemOf } from './agent-system';
-import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
+import type { ToolRun } from './agent-tools';
+import { DEFAULT_TOOL_CONCURRENCY, toolTurn } from './agent-tools';
+import { assistantTurn, repairTurn } from './agent-transcript';
 import { assertAnswerable, observeTurn } from './agent-turn';
 import { runTotal } from './agent-usage';
-import { LlmTruncatedError } from './answer-errors';
 import { budgetKeysFor, currentBudget, withBudget } from './budget';
 import { AgentMaxTurnsError, AgentToolUnexposedError, LlmOutputInvalidError } from './errors';
-import { answerAttributes } from './llm';
+import { answerAttributes } from './llm-answer';
+import { reportedCall } from './llm-instrument';
 import type { PromptVars } from './prompt';
 import { promptCacheHint } from './prompt-cache';
 import type { AiMessage, GenerateRequest } from './provider';
-import { estimateCost, isTruncated } from './provider';
+import { estimateCost } from './provider';
 import { assertNoSecrets } from './redaction';
 import type { Respond } from './respond';
 import { RESPOND, respondFor } from './respond';
@@ -71,8 +64,7 @@ import { runMeter } from './run-meter';
 import { aiGateway, aiRedactor, installedGateway } from './runtime';
 import type { Sampling } from './sampling';
 import { ignoredSamplingAttribute, screenSampling } from './sampling';
-import type { LlmToolResult } from './tools';
-import { isOfferedTool, runLlmToolCall, toolLabel } from './tools';
+import { isOfferedTool, toolLabel } from './tools';
 
 export type { AgentCompaction, AgentCompactOption, AgentCompactRule } from './agent-compact-def';
 export type {
@@ -111,6 +103,12 @@ export function agent<
   const owner = {};
   const sampling = screenSampling(SUBJECT, def);
   const compact = screenCompact(def.compact, bounds.maxTokens);
+  const toolConcurrency = finiteCount(
+    SUBJECT,
+    'maxToolConcurrency',
+    def.maxToolConcurrency ?? DEFAULT_TOOL_CONCURRENCY,
+    1,
+  );
   // Projected on FIRST RUN, memoised, for the reason above: `agent()` is evaluated at module
   // scope and a tool's name is stamped by `registerAction` at boot, so naming it here would make
   // the ordinary `export const publishPost = action(...)` beside it `X_ACTION_UNREGISTERED`.
@@ -132,7 +130,7 @@ export function agent<
           def,
           respond,
           await resolvePerRun(def, { ...declared, adapted: adapt() }, args),
-          { sampling, owner, compact, emit },
+          { sampling, owner, compact, emit, toolConcurrency },
           args,
         ),
       ),
@@ -143,10 +141,7 @@ export function agent<
   return continuable(built, owner);
 }
 
-/**
- * Attach `.run()` and `.continue()` IN PLACE, for the reason `llm()`'s `streamable` gives: the
- * object an app exported is the one the registry names, and `named()`'s twin gets them too.
- */
+/** `.run()` / `.continue()` IN PLACE (as `llm()`'s `streamable`): the export IS the registry's. */
 function continuable<TInput extends StandardSchemaV1, TOutput extends StandardSchemaV1>(
   target: Action<TInput, TOutput>,
   owner: object,
@@ -172,6 +167,7 @@ async function run<
     readonly owner: object;
     readonly compact: CompactPlan | undefined;
     readonly emit: EmitChunk;
+    readonly toolConcurrency: number;
   },
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
@@ -224,8 +220,8 @@ async function run<
       'agent.prompt.hash': prompt.hash,
       'agent.tools': adapted.offered.length,
       'agent.max_turns': maxTurns,
-      'llm.redacted': rendered !== rawPrompt || !sameSystem(system, rawSystem),
-      'llm.prompt_cache': promptCache !== undefined,
+      'ultimate.llm.redacted': rendered !== rawPrompt || !sameSystem(system, rawSystem),
+      'ultimate.llm.prompt_cache': promptCache !== undefined,
     });
     // Read when the run ends, not here: the gateway may be what registers the model's row.
     const reportSampling = (): void => {
@@ -259,7 +255,6 @@ async function run<
     // Every provider call below goes through the meter, so whatever ends the run — a ceiling, a
     // deadline, a truncated turn, the caller leaving — is thrown carrying what the run was billed.
     const meter = runMeter();
-    const disclosure = { discloseErrors: def.discloseToolErrors !== false };
     // Worst case: the run so far (continuations and nested calls included) plus this request,
     // estimated as the gateway's own reservation will be — at the write rate only where a provider
     // serving the model would mark it. Before every turn, and before a compaction's summary call.
@@ -297,7 +292,9 @@ async function run<
       compacting,
       send: (request) => {
         assertCost(request);
-        return deadline.guard(meter.call(gateway.generate(request))).catch((error: unknown) => {
+        // `reportedCall`: each turn is one model call, so each is one `ai.llm` (`llm-instrument.ts`).
+        const answered = reportedCall(request.model ?? model, gateway.generate(request));
+        return deadline.guard(meter.call(answered)).catch((error: unknown) => {
           // The caller left mid-call: the aborted socket reads as a provider failure, which is
           // RETRYABLE. Say what happened instead.
           throwIfAborted(args.ctx);
@@ -321,6 +318,19 @@ async function run<
       // identity any tool runs as. Nothing below reads an actor out of `result` — a model cannot
       // name the identity it acts as, and a loop that let it would be an escalation primitive.
       const { actor } = args.ctx;
+      const tools: ToolRun = {
+        tools: adapted.tools,
+        ctx: args.ctx,
+        actor,
+        deadline,
+        emit,
+        concurrency: fixed.toolConcurrency,
+        discloseErrors: def.discloseToolErrors !== false,
+        maxTurns,
+        chars,
+        redact,
+        repeated,
+      };
       let messages: readonly AiMessage[] =
         prior === undefined ? [{ role: 'user', content: rendered }] : continued(prior, rendered);
       let calls = 0;
@@ -369,68 +379,13 @@ async function run<
           run: runTotal(result.model, prior?.usage, meter.total(), meter.below()),
         });
         if (result.text !== '') emit({ type: 'text', turn, text: result.text });
+        // Before a tool runs and before the answer is read (`X_LLM_REFUSED`, `X_LLM_TRUNCATED`).
         assertAnswerable(result, name, base);
-        // Before a tool runs and before the answer is read: a turn cut off at the ceiling carries
-        // arguments that stop wherever the ceiling fell — `{}` on both wires for a call that never
-        // reached its first byte — so running a tool on them is a side effect the model did not
-        // ask for, and validating them accepts an empty answer for any `output` of optional keys.
-        if (isTruncated(result.stopReason)) {
-          throw new LlmTruncatedError({
-            prompt: name,
-            maxTokens: base.maxTokens,
-            subject: SUBJECT,
-          });
-        }
 
         if (requested.length > 0) {
-          // Concurrent, and deliberately unbounded WITHIN one turn: the batch is what a single
-          // model turn asked for, each entry is an ordinary `action` carrying its own policy and
-          // its own `rateLimit`, and a second ceiling here would be a throttle competing with
-          // those. A tool that calls a model still reserves on the same ledger chain, which
-          // debits before it checks, so the budget holds. Serial cost 5x wall clock for a turn that asked for 5 tools, and nothing
-          // in the types or the docs ever said so.
-          //
-          // Order is by INDEX, not by completion: `Promise.all` resolves positionally and each
-          // result carries the `tool_use` id `runLlmToolCall` was handed, so a fast tool answering
-          // first cannot be paired with a slow tool's call.
-          throwIfAborted(args.ctx);
-          deadline.check();
-          for (const call of requested)
-            emit({ type: 'tool_call', turn, id: call.id, name: call.name });
-          const results: readonly LlmToolResult[] = await deadline.guard(
-            // Inside the deadline's scope, so each tool's own `ctx.signal` carries it.
-            deadline.scope(() =>
-              Promise.all(
-                requested.map((call) => runLlmToolCall(adapted.tools, call, actor, disclosure)),
-              ),
-            ),
-          );
+          messages = await toolTurn(tools, turn, result, requested, answers, messages);
           calls += requested.length;
-          results.forEach((done, index) => {
-            const name = requested[index]?.name ?? '';
-            emit({
-              type: 'tool_result',
-              turn,
-              id: done.toolUseId,
-              name,
-              isError: done.isError === true,
-            });
-          });
-          emit({ type: 'turn', turn, maxTurns });
           rejected = undefined;
-          // Before the next turn is bought: the same calls with the same results cannot lead
-          // anywhere a further turn would not also lead.
-          repeated(requested, results);
-          messages = [
-            ...messages,
-            assistantTurn(result),
-            // Parallel tool use — one turn asking for a tool AND answering — is normal, and the
-            // answer is speculative: it was written before the result it asked for existed. So
-            // the loop continues, and the answer is REJECTED on the wire rather than dropped,
-            // because a replayed `respond` block with no `tool_result` is a 400 and the whole run
-            // becomes an `X_AI_PROVIDER_UNAVAILABLE`.
-            toolResultTurn(results, chars, answers, redact),
-          ];
           await landed(turn, messages, result.model);
           continue;
         }

package/src/budget-store.ts

@@ -0,0 +1,82 @@
+// Single responsibility: where cross-request budget counters live — the `BudgetStore` contract
+// (an atomic `take`), the per-process `memoryBudgetStore()`, and the guard a store's answer passes.
+// Split from ./budget (the ledger) at its line ceiling.
+
+/**
+ * What one `take` found. `spent` is the counter as the store read it, BEFORE this take — so a
+ * refusal can say how much was left.
+ */
+export interface BudgetTake {
+  readonly taken: boolean;
+  readonly spent: number;
+}
+
+/** Where cross-request counters live. Swap for Redis in a multi-process deployment. */
+export interface BudgetStore {
+  spent(key: string): Promise<number> | number;
+  /** `tokens` may be NEGATIVE: releasing a reservation the call never spent is a credit. */
+  add(key: string, tokens: number): Promise<void> | void;
+  /**
+   * Add `tokens` to `key` only if the total stays at or under `limit`, in ONE atomic step — a
+   * Redis `EVAL`, a SQL `update … set spent = spent + $2 where key = $1 and spent + $2 <= $3`.
+   * Required, with no default built on `spent` + `add`: that pair is the read-then-write two
+   * concurrent requests both pass, which is the overspend this member exists to close.
+   */
+  take(key: string, tokens: number, limit: number): Promise<BudgetTake> | BudgetTake;
+  reset(key?: string): Promise<void> | void;
+}
+
+/**
+ * The per-process default. There is NO window: a counter lives until `reset()` or a restart, so an
+ * `actor` / `org` ceiling here is "per process lifetime". It holds one entry per caller that has
+ * spent under a DECLARED ceiling (none at all without one), and deliberately no eviction: dropping
+ * a counter hands that caller its whole ceiling back, which is the bypass the ceiling exists to
+ * stop. A window — per day, per month — is a shared store whose keys expire.
+ */
+export class MemoryBudgetStore implements BudgetStore {
+  private readonly counters = new Map<string, number>();
+
+  spent(key: string): number {
+    return this.counters.get(key) ?? 0;
+  }
+
+  /** A counter back at zero is deleted: absent and zero are the same answer, and an entry costs. */
+  add(key: string, tokens: number): void {
+    this.write(key, this.spent(key) + tokens);
+  }
+
+  /** Atomic because it is synchronous: nothing else runs between the read and the write. */
+  take(key: string, tokens: number, limit: number): BudgetTake {
+    const spent = this.spent(key);
+    if (spent + tokens > limit) return { taken: false, spent };
+    this.write(key, spent + tokens);
+    return { taken: true, spent };
+  }
+
+  /** How many counters are held — one per caller that has spent under a declared ceiling. */
+  size(): number {
+    return this.counters.size;
+  }
+
+  private write(key: string, total: number): void {
+    if (total === 0) this.counters.delete(key);
+    else this.counters.set(key, total);
+  }
+
+  reset(key?: string): void {
+    if (key === undefined) this.counters.clear();
+    else this.counters.delete(key);
+  }
+}
+
+/** The one way to build the per-process store; the class is a type in the barrel only. */
+export function memoryBudgetStore(): MemoryBudgetStore {
+  return new MemoryBudgetStore();
+}
+
+/** A store's `take` answer is app code's: read, never trusted. */
+export function isBudgetTake(value: unknown): value is BudgetTake {
+  if (typeof value !== 'object' || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return typeof record['taken'] === 'boolean' && Number.isFinite(record['spent']);
+}

package/src/budget.ts

@@ -14,11 +14,18 @@ import type { Actor } from '@ultimat3/core';
 import { assert, asyncContext, finiteCount } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import { assertSameCurrency, commonScale, exponentOf, minorAt } from '@ultimat3/money';
+import type { BudgetStore } from './budget-store';
+import { isBudgetTake, MemoryBudgetStore } from './budget-store';
 import { compareMoney, costScale, ledgerUnits, roundUpCost } from './cost';
 import { AiBudgetExceededError } from './errors';
 import type { GenerateRequest, TokenUsage } from './provider';
 import { estimateCost, estimateInputTokens, estimateTokens, totalTokens } from './provider';
 
+// The store half lives in ./budget-store; named here too, so `./budget` stays the one import a
+// ledger reader needs.
+export type { BudgetStore, BudgetTake } from './budget-store';
+export { MemoryBudgetStore, memoryBudgetStore } from './budget-store';
+
 /** Ceilings. An omitted scope is unlimited — declare the ones that matter. */
 export interface BudgetLimits {
   /**
@@ -67,30 +74,6 @@ export function estimateSpend(request: GenerateRequest, marked = false): SpendEs
   };
 }
 
-/**
- * What one `take` found. `spent` is the counter as the store read it, BEFORE this take — so a
- * refusal can say how much was left.
- */
-export interface BudgetTake {
-  readonly taken: boolean;
-  readonly spent: number;
-}
-
-/** Where cross-request counters live. Swap for Redis in a multi-process deployment. */
-export interface BudgetStore {
-  spent(key: string): Promise<number> | number;
-  /** `tokens` may be NEGATIVE: releasing a reservation the call never spent is a credit. */
-  add(key: string, tokens: number): Promise<void> | void;
-  /**
-   * Add `tokens` to `key` only if the total stays at or under `limit`, in ONE atomic step — a
-   * Redis `EVAL`, a SQL `update … set spent = spent + $2 where key = $1 and spent + $2 <= $3`.
-   * Required, with no default built on `spent` + `add`: that pair is the read-then-write two
-   * concurrent requests both pass, which is the overspend this member exists to close.
-   */
-  take(key: string, tokens: number, limit: number): Promise<BudgetTake> | BudgetTake;
-  reset(key?: string): Promise<void> | void;
-}
-
 /**
  * The store keys a call's identity is counted under: the acting identity (kind and id — one window
  * per actor, whichever org it acts in) and its org, when it has one. Derived, never taken from a
@@ -129,54 +112,6 @@ export interface BudgetReservation {
   readonly tokens: number;
 }
 
-/**
- * The per-process default. There is NO window: a counter lives until `reset()` or a restart, so an
- * `actor` / `org` ceiling here is "per process lifetime". It holds one entry per caller that has
- * spent under a DECLARED ceiling (none at all without one), and deliberately no eviction: dropping
- * a counter hands that caller its whole ceiling back, which is the bypass the ceiling exists to
- * stop. A window — per day, per month — is a shared store whose keys expire.
- */
-export class MemoryBudgetStore implements BudgetStore {
-  private readonly counters = new Map<string, number>();
-
-  spent(key: string): number {
-    return this.counters.get(key) ?? 0;
-  }
-
-  /** A counter back at zero is deleted: absent and zero are the same answer, and an entry costs. */
-  add(key: string, tokens: number): void {
-    this.write(key, this.spent(key) + tokens);
-  }
-
-  /** Atomic because it is synchronous: nothing else runs between the read and the write. */
-  take(key: string, tokens: number, limit: number): BudgetTake {
-    const spent = this.spent(key);
-    if (spent + tokens > limit) return { taken: false, spent };
-    this.write(key, spent + tokens);
-    return { taken: true, spent };
-  }
-
-  /** How many counters are held — one per caller that has spent under a declared ceiling. */
-  size(): number {
-    return this.counters.size;
-  }
-
-  private write(key: string, total: number): void {
-    if (total === 0) this.counters.delete(key);
-    else this.counters.set(key, total);
-  }
-
-  reset(key?: string): void {
-    if (key === undefined) this.counters.clear();
-    else this.counters.delete(key);
-  }
-}
-
-/** The one way to build the per-process store; the class is a type in the barrel only. */
-export function memoryBudgetStore(): MemoryBudgetStore {
-  return new MemoryBudgetStore();
-}
-
 export interface BudgetLedgerInput {
   readonly limits: BudgetLimits;
   /** Stable identity keys. Omit a key to skip that scope even when a limit is set. */
@@ -461,12 +396,6 @@ export function screenedMoney(subject: string, key: string, money: Money): Money
   return money;
 }
 
-function isBudgetTake(value: unknown): value is BudgetTake {
-  if (typeof value !== 'object' || value === null) return false;
-  const record = value as Record<string, unknown>;
-  return typeof record['taken'] === 'boolean' && Number.isFinite(record['spent']);
-}
-
 /** Spreadable single-key record, so an absent limit stays absent under exactOptionalPropertyTypes. */
 function pick<K extends string, V>(key: K, value: V | undefined): Partial<Record<K, V>> {
   return value === undefined ? {} : ({ [key]: value } as Record<K, V>);

package/src/embeddings.ts

@@ -147,5 +147,5 @@ export function cosine(a: Float32Array, b: Float32Array): number {
     normB += y * y;
   }
   const similarity = dot / Math.sqrt(normA * normB);
-  return similarity > 1 ? 1 : similarity < -1 ? -1 : similarity;
+  return Math.min(1, Math.max(-1, similarity));
 }

package/src/errors.ts

@@ -72,7 +72,7 @@ export class AiGatewayMissingError extends UltimateError {
       // The provider is the app's choice, so no vendor is the default (M12): the fix is the shape
       // and the cause names what `provider` is — one of the peers, or the app's own.
       cause: `an llm action on prompt "${input.prompt}" ran before any gateway was configured (provider: anthropicProvider({ models }) for the Anthropic Messages format, openAiProvider({ baseUrl, models }) for the OpenAI chat-completions format on any compatible server, or your own Provider)`,
-      fix: 'configureAi({ gateway: providerGateway({ providers: [provider] }) }) at boot',
+      fix: 'export const runtime = { aiGateway: providerGateway({ providers: [provider] }) }   # apps/<app>/runtime.ts — in a test, installAiGateway(gateway) from @ultimat3/ai/adapter',
     });
   }
 }
@@ -187,16 +187,16 @@ export class AgentMaxTurnsError extends UltimateError {
  * than filtered at the call, because a silently dropped tool is the worst of both: the
  * declaration reads as if the model can call it, and the model is never offered it.
  *
- * `isMcpExposed` is the one predicate — an in-app agent and an external MCP client see exactly
- * the same catalogue, which is what keeps "there is no second authz system" true of the catalogue
- * too.
+ * `isAgentOffered` is the one predicate — an in-app agent sees every action an external MCP client
+ * sees, plus the ones declared `agents: true` — so the catalogue is still declared at the action,
+ * never filtered here.
  */
 export class AgentToolUnexposedError extends UltimateError {
   constructor(input: { agent: string; tools: readonly string[] }) {
     super({
       code: 'X_AGENT_TOOL_UNEXPOSED',
       cause: `agent "${input.agent}" lists tools no MCP surface exposes: ${input.tools.join(', ')}`,
-      fix: "inProcessTool({ name, description, input, execute })   # for a tool only this agent may call — or add mcp: { expose: true } to the action named in cause to offer it to MCP clients too, or drop it from the agent's tools",
+      fix: "inProcessTool({ name, description, input, execute })   # for a tool only this agent may call — or add mcp: { expose: false, agents: true } to the action named in cause for this app's agents alone, mcp: { expose: true } to offer it to MCP clients too, or drop it from the agent's tools",
     });
   }
 }

package/src/eval-agent.ts

@@ -66,7 +66,7 @@ export function agentPrompt(agent: AnyAction, evalName: string): Prompt {
   assert(
     prompt !== undefined,
     `defineEval "${evalName}" names an agent whose prompt is not registered: an action agent() did not build, a named() twin, or a prompt reset since`,
-    `registerAction('<name>', agent({ … })) and pass that action to defineEval({ agent })`,
+    `export the agent({ … }) from a module defineApi({ actions }) registers, and pass that action to defineEval({ agent })`,
   );
   return prompt;
 }