@ultimat3/ai 27.11.0 → 27.13.0

package/CLAUDE.md

@@ -64,6 +64,7 @@ one adds, the other adds.
 | `agent-guards.ts` / `agent-errors.ts` | the repeated-turn detector and the run deadline; their two classes |
 | `prompt-cache.ts` | PROVIDER prompt caching: `SystemParts`, `PromptCacheHint`, `PROMPT_CACHE_RULES` (sources in its header) |
 | `prompt-cache-blocks.ts` | the Anthropic wire's marks (chat-completions': `openai-messages.ts`) |
+| `agent-per-run.ts` / `agent-run-limits.ts` | one run's `offerTools()`/`model()`/`limits()`, narrow only; `costPerRun` |
 | `agent-continue.ts` / `agent-turn.ts` | `.run()` / `.continue()`, the transcript handle and its screen; one turn's report and refusals |
 | `agent-transcript.ts` | what one turn leaves in the transcript: the assistant replay, the tool results, the correction |
 | `agent-facts.ts` | `describeAgents()` — the agent registry, and the row a manifest WOULD publish (its consumer has to be `cli`, tier 5) |
@@ -236,6 +237,9 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
     rule a hive member's `reason` follows too. Never a second copy. One widening, for an
     `inProcess` tool only (`discloseOwnFailure`): a branded error under a code with NO declared
     status is shown as `{ error: { code, cause, fix } }`; `discloseErrors: false` opts out.
+- **A run only NARROWS its declaration**: `offerTools()` ⊆ declared names (`X_AGENT_TOOL_UNDECLARED`),
+  `model()` via `modelSpec`, `limits()` screened and ≤ declared (`X_AI_REQUEST_INVALID`); all
+  before `vars()`. The handle binds the run's model and OFFERED subset; `costPerRun` is checked per turn.
 - **`.run()`/`.continue()` are the SAME action**, marked by an ambient session only the declaring
   agent may claim, once (a nested agent starts fresh). The handle is SIGNED (`sealTranscript`: the
   cursor secret, own label) and bound to agent, model, tool names and `orgId`; screened before
@@ -276,17 +280,13 @@ Why each is shaped this way: [`docs/history/ai.md`](../../docs/history/ai.md#llm
 Full text of each rule: [`docs/history/ai.md`](../../docs/history/ai.md#evals-retrieval-fix-lines).
 
 - **No fix line may name `x ai`** (planned); an eval is selected with `x test eval --filter <name>`.
-- Every eval result carries the prompt hash; an eval gates on the DROP from its recorded baseline,
-  mean AND per case (`X_EVAL_BASELINE_MISSING` / `_INVALID`); every prompt is named by an eval
-  (`X_EVAL_MISSING`); `ULTIMATE_EVAL_RECORD=1` records, and `x verify` with it is `X_EVAL_RECORDING`.
-- Retrieval is hybrid by default, no vector-only path. `chunk()` hard-wraps (no chunk over `size`);
-  `metadata.source` is written AFTER the caller's spread; `VectorStore.prune` is required.
+- An eval gates on the DROP from its baseline, mean AND per case; every prompt is named by an eval
+  (`X_EVAL_MISSING`); `ULTIMATE_EVAL_RECORD=1` records (`x verify` with it: `X_EVAL_RECORDING`).
+- Retrieval is hybrid, no vector-only path; `chunk()` hard-wraps; `VectorStore.prune` is required.
 - **An unbound store read inside a request whose actor has an `orgId` is `X_VECTOR_UNSCOPED`**
   (both stores, every read); `scope: UNSCOPED` is the named opt-in, an omitted scope is `UNBOUND`.
-- `postgresVectorStore()` is the only production vector path; `pg-vector.live.test.ts` refuses to
-  skip without the extension. Distance ordering is an ascending raw subquery (the shape hnsw
-  answers), pinned by a plan assertion. Tenant and policy filters are in SQL on every statement and
-  BOTH fusion halves; `(tenant, id)` is the key; `scoped()` only TIGHTENS (`X_VECTOR_SCOPE_WIDENED`).
+- `postgresVectorStore()` is the only production vector path (the live suite never skips); tenant
+  and policy filters in SQL on every statement and BOTH fusion halves; `scoped()` only TIGHTENS.
 
 ## Commands
 

package/README.md

@@ -442,6 +442,8 @@ sub-agent in its own `tools` and the sub-agent runs under the same actor, throug
 | both stops are registered `terminal` | an `agentJob()` dead-letters on attempt one instead of buying the same run per attempt |
 | every turn asks the provider to cache its prefix (`promptCache`, default `'auto'`) | the transcript IS the request, so an uncached run pays for its stable prefix once per turn — [below](#provider-prompt-caching) |
 | `budget.tokensPerRun` caps the **whole run** | a single call is bounded by `maxTokens`; a loop is bounded by nothing until this is set |
+| `budget.costPerRun` caps the run's **money**: before each turn, what the run cost so far (continuations and nested calls included) plus that turn's worst-case estimate | `costPerCall` bounds one call and nothing bounded their sum; refused pre-flight as `X_AI_BUDGET_EXCEEDED` (scope `costPerRun`), never truncated |
+| one run may **narrow** its declaration, never widen it: `offerTools()` a subset of `tools` (another name is `X_AGENT_TOOL_UNDECLARED`), `model` as a function (resolved through the registry, `X_AI_MODEL_UNKNOWN`), `limits()` lower ceilings (a higher one is `X_AI_REQUEST_INVALID`) | a stored permission rule or model tier needed one declared agent per combination; the declaration stays the blast radius, and the handle binds the run's model and offered subset — [Agents → Per-run picks](https://github.com/developerz-ai/ultimate/wiki/Agents#per-run-picks-offertools-model-limits) |
 | a tool result is truncated, and says so | the transcript IS the request, so an untruncated result is re-billed once per remaining turn |
 | **no semantic cache** | similar prompts do not have similar answers once the answer depends on what `lookupOrder` returned this second |
 
@@ -701,7 +703,7 @@ import { describeAgents } from '@ultimat3/ai';
 describeAgents();
 // [{ name: 'supportAgent', prompt: 'support@1.0.0', promptHash: '…', model: 'house-large', modelFrom: 'gateway',
 //    maxTurns: 6, maxToolResultChars: 4000, tools: ['issueRefund', 'lookupOrder'],
-//    budget: { tokensIn: null, tokensPerRun: 200000, costPerCall: { minor: 50, currency: 'USD' } },
+//    budget: { tokensIn: null, tokensPerRun: 200000, costPerCall: { minor: 50, currency: 'USD' }, costPerRun: null },
 //    mcp: true }]
 ```
 
@@ -966,6 +968,7 @@ fail-closed `terminal` default.
 | `X_LLM_STREAM_INVALID` | a streamed answer failed its schema, and a stream cannot take a repair turn |
 | `X_AGENT_MAX_TURNS` | an `agent()` used every turn without answering |
 | `X_AGENT_TOOL_UNEXPOSED` | an `agent()` lists a tool that is neither in-process nor an MCP-exposed action |
+| `X_AGENT_TOOL_UNDECLARED` | an `agent()` run's `offerTools()` named a tool its declaration does not list |
 | `X_AGENT_TOOL_LOOP` | an `agent()` made the same tool calls and read the same results `maxRepeatedToolCalls` turns in a row |
 | `X_AGENT_DEADLINE` | an `agent()` outlived its declared `deadlineMs` |
 | `X_EVAL_THRESHOLD` | an eval scored below its bar |
@@ -986,6 +989,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `AgentDeadlineError` | `X_AGENT_DEADLINE` | `src/agent-errors.ts` |
 | `AgentMaxTurnsError` | `X_AGENT_MAX_TURNS` | `src/errors.ts` |
 | `AgentToolLoopError` | `X_AGENT_TOOL_LOOP` | `src/agent-errors.ts` |
+| `AgentToolUndeclaredError` | `X_AGENT_TOOL_UNDECLARED` | `src/agent-errors.ts` |
 | `AgentTranscriptInvalidError` | `X_AGENT_TRANSCRIPT_INVALID` | `src/agent-errors.ts` |
 | `AgentToolUnexposedError` | `X_AGENT_TOOL_UNEXPOSED` | `src/errors.ts` |
 | `AiBudgetExceededError` | `X_AI_BUDGET_EXCEEDED` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ai",
-  "version": "27.11.0",
+  "version": "27.13.0",
   "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.11.0",
-    "@ultimat3/cache": "27.11.0",
-    "@ultimat3/core": "27.11.0",
-    "@ultimat3/db": "27.11.0",
-    "@ultimat3/http": "27.11.0",
-    "@ultimat3/jobs": "27.11.0",
-    "@ultimat3/money": "27.11.0",
-    "@ultimat3/policy": "27.11.0",
-    "@ultimat3/schema": "27.11.0",
-    "@ultimat3/time": "27.11.0"
+    "@ultimat3/action": "27.13.0",
+    "@ultimat3/cache": "27.13.0",
+    "@ultimat3/core": "27.13.0",
+    "@ultimat3/db": "27.13.0",
+    "@ultimat3/http": "27.13.0",
+    "@ultimat3/jobs": "27.13.0",
+    "@ultimat3/money": "27.13.0",
+    "@ultimat3/policy": "27.13.0",
+    "@ultimat3/schema": "27.13.0",
+    "@ultimat3/time": "27.13.0"
   }
 }

package/src/agent-declared.ts

@@ -4,7 +4,7 @@
 
 import { finiteCount, isMcpExposed } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
-import type { AgentDef } from './agent-def';
+import type { AgentBudget, AgentDef } from './agent-def';
 import type { AgentFact } from './agent-facts';
 import { DEFAULT_MAX_REPEATED_TOOL_CALLS } from './agent-guards';
 import type { BudgetLimits } from './budget';
@@ -107,7 +107,10 @@ export function factsOf<
     // The run's own precedence, so the row names the model a call would use NOW: read when the
     // facts are, at describe time, like every name in the row. `modelFrom` says which place
     // answered — `gateway` (or `null`, none yet) depends on the gateway installed at that moment.
-    ...modelFact(describedModel(def.model, def.prompt.model, installedGateway()?.defaultModel)),
+    // A model picked per run (`model` as a function) has no answer until a run asks it.
+    ...(typeof def.model === 'function'
+      ? { model: null, modelFrom: 'run' as const }
+      : modelFact(describedModel(def.model, def.prompt.model, installedGateway()?.defaultModel))),
     maxTurns: def.maxTurns ?? DEFAULT_MAX_TURNS,
     maxToolResultChars: def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS,
     tools: [...def.tools.map(toolLabel)].sort(),
@@ -115,17 +118,18 @@ export function factsOf<
       tokensIn: budget?.tokensIn ?? null,
       tokensPerRun: budget?.tokensPerRun ?? null,
       costPerCall: budget?.costPerCall ?? null,
+      costPerRun: budget?.costPerRun ?? null,
     },
     mcp: isMcpExposed(def.mcp),
   };
 }
 
-export function limitsOf<
-  TInput extends StandardSchemaV1,
-  TOutput extends StandardSchemaV1,
-  V extends PromptVars,
->(def: AgentDef<TInput, TOutput, V>, used?: TokenUsage): BudgetLimits {
-  const budget = def.budget;
+export function limitsOf(budget: AgentBudget | undefined, used?: TokenUsage): BudgetLimits {
+  // `costPerRun` is not a ledger scope — the run checks it before each turn (`assertRunCost`) —
+  // but it is screened here with the rest, so a bad one is refused before anything is loaded.
+  if (budget?.costPerRun !== undefined) {
+    screenedMoney(SUBJECT, 'budget.costPerRun', budget.costPerRun);
+  }
   return {
     // Screened under the names the DECLARATION uses, not the ledger's: `tokensPerRun` arrives at
     // `BudgetLimits` as `request`, and a fix line naming a key the app never wrote is not a fix.

package/src/agent-def.ts

@@ -20,8 +20,38 @@ export interface AgentBudget extends LlmBudget {
    * a single call is bounded by `maxTokens`, a loop is bounded by nothing until this is set.
    */
   readonly tokensPerRun?: number;
+  /**
+   * Money ceiling for the WHOLE run, every turn and every continuation counted, integer minor
+   * units. Checked before each turn against what the run has cost so far plus that turn's
+   * worst-case estimate — the run-level twin of `costPerCall`. A refusal is `X_AI_BUDGET_EXCEEDED`
+   * (scope `costPerRun`) before the provider is called.
+   */
+  readonly costPerRun?: Money;
 }
 
+/**
+ * The ceilings ONE run may lower (`limits()`), under the keys the declaration uses. Each may only
+ * be at or under the declared value (after its default); a higher one is `X_AI_REQUEST_INVALID`.
+ * One the declaration leaves unset (`deadlineMs`, a `budget` key) may be set by a run: any value
+ * is tighter than none.
+ */
+export interface AgentRunLimits {
+  readonly maxTurns?: number;
+  readonly maxTokens?: number;
+  readonly maxToolResultChars?: number;
+  readonly maxRepeatedToolCalls?: number;
+  readonly deadlineMs?: number;
+  readonly budget?: AgentBudget;
+}
+
+/**
+ * The model a run is on: an id, or a function of the run's input and context answering one —
+ * `undefined` from it falls through to the prompt's `model`, then the gateway's `defaultModel`.
+ */
+export type AgentModel<TInput extends StandardSchemaV1> =
+  | ModelId
+  | ((args: AgentVarsArgs<TInput>) => ModelId | undefined | Promise<ModelId | undefined>);
+
 export interface AgentVarsArgs<TInput extends StandardSchemaV1> {
   readonly input: InferOutput<TInput>;
   readonly ctx: Ctx;
@@ -32,7 +62,13 @@ export interface AgentDef<
   TOutput extends StandardSchemaV1,
   V extends PromptVars,
 > {
-  readonly model?: ModelId;
+  /**
+   * An id, or a function picking one per run (a stored override, a tier for this tenant). Either
+   * way it is resolved through the model registry — an unregistered id is `X_AI_MODEL_UNKNOWN`
+   * before anything is loaded — and bound into the transcript handle, so `.continue()` runs on the
+   * model the run started on or is refused.
+   */
+  readonly model?: AgentModel<TInput>;
   readonly input: TInput;
   readonly output: TOutput;
   readonly prompt: Prompt<V>;
@@ -59,6 +95,14 @@ export interface AgentDef<
    * of both.
    */
   readonly tools: readonly AgentTool[];
+  /**
+   * The tool NAMES this run is offered — a subset of `tools`, picked per run (a stored permission
+   * rule, the actor's plan). Unset offers every declared tool. A name the declaration does not
+   * list is `X_AGENT_TOOL_UNDECLARED` before anything is loaded: a run narrows the catalogue and
+   * never adds to it. The model sees only the subset, a call to any other tool answers
+   * `unknown tool`, and the transcript handle is bound to the subset offered.
+   */
+  offerTools?(args: AgentVarsArgs<TInput>): readonly string[] | Promise<readonly string[]>;
   /**
    * `false` withholds the refusals of EVERY in-process tool this agent runs, as a projected tool's
    * are — for an agent whose transcript leaves the tenant it ran for. Default `true`; one tool
@@ -79,6 +123,12 @@ export interface AgentDef<
    */
   readonly deadlineMs?: number;
   readonly budget?: AgentBudget;
+  /**
+   * Ceilings for ONE run, read from its input and context (a stored override, a cheaper tier):
+   * each may only LOWER the declared one — see `AgentRunLimits`. Called once per `.run()`,
+   * `.continue()` or plain call, before the deadline is armed and before `vars()`.
+   */
+  limits?(args: AgentVarsArgs<TInput>): AgentRunLimits | Promise<AgentRunLimits>;
   readonly policy: ActionPolicy;
   readonly mcp?: ActionMcp;
   /** Enforced completion ceiling PER TURN. The model never sees it. */

package/src/agent-errors.ts

@@ -67,3 +67,20 @@ export class AgentTranscriptInvalidError extends UltimateError {
     });
   }
 }
+
+/**
+ * One run's `offerTools()` named a tool the declaration does not list. Refused rather than
+ * dropped, for the reason `X_AGENT_TOOL_UNEXPOSED` is: a name that reads as offered and silently is
+ * not is the worst of both — and a per-run choice can only NARROW the declared catalogue, never
+ * add to it, so the declaration stays the agent's whole blast radius.
+ */
+export class AgentToolUndeclaredError extends UltimateError {
+  constructor(input: { agent: string; tools: readonly string[]; declared: readonly string[] }) {
+    super({
+      code: 'X_AGENT_TOOL_UNDECLARED',
+      cause: `agent "${input.agent}" was offered tools its declaration does not list: ${input.tools.join(', ')} (declared: ${input.declared.join(', ') || 'none'})`,
+      fix: "offerTools: () => ['<a name from the cause's declared list>']   # on the agent — or add the tool to its tools: first if this run really needs it",
+      meta: { agent: input.agent, tools: input.tools },
+    });
+  }
+}

package/src/agent-facts.ts

@@ -16,6 +16,7 @@ export interface AgentBudgetFact {
   readonly tokensIn: number | null;
   readonly tokensPerRun: number | null;
   readonly costPerCall: Money | null;
+  readonly costPerRun: Money | null;
 }
 
 export interface AgentFact {
@@ -33,11 +34,17 @@ export interface AgentFact {
    * `null` when none names one yet — a call in that state is refused (`X_AI_MODEL_UNRESOLVED`).
    */
   readonly model: string | null;
-  /** Which of those answered; `gateway` and `null` are as of the gateway installed at read time. */
-  readonly modelFrom: ModelSource | null;
+  /**
+   * Which of those answered; `gateway` and `null` are as of the gateway installed at read time.
+   * `run` (with `model: null`): the declaration's `model` is a function, so each run picks its own.
+   */
+  readonly modelFrom: ModelSource | 'run' | null;
   readonly maxTurns: number;
   readonly maxToolResultChars: number;
-  /** Tool names, sorted — the catalogue this agent may call, which is its blast radius. */
+  /**
+   * Tool names, sorted — the catalogue this agent may call, which is its blast radius. A run's
+   * `offerTools()` only ever narrows it.
+   */
   readonly tools: readonly string[];
   readonly budget: AgentBudgetFact;
   /** Whether the agent itself is offered as a tool, so a supervisor could call it. */

package/src/agent-per-run.ts

@@ -0,0 +1,117 @@
+// Single responsibility: what ONE run of an `agent()` picks from its declaration — the tools it is
+// offered (`offerTools()`), the model it runs on (`model` as a function) and the ceilings it runs
+// under (`limits()`) — each read from the run's own input and context, and each only ever a
+// NARROWING of what the declaration states. Split from ./agent at its line ceiling.
+
+import type { Ctx } from '@ultimat3/core';
+import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { limitsOf } from './agent-declared';
+import type { AgentDef } from './agent-def';
+import { AgentToolUndeclaredError } from './agent-errors';
+import type { RunCeilings } from './agent-run-limits';
+import { narrowCeilings } from './agent-run-limits';
+import { AiRequestInvalidError } from './errors';
+import { modelForCall } from './model-resolve';
+import type { ModelId } from './models';
+import { modelSpec } from './models';
+import type { PromptVars } from './prompt';
+import type { AgentTool, LlmTool, ProjectableAction } from './tools';
+import { asProjectableAction, toLlmTools } from './tools';
+
+/** The tools as `runLlmToolCall` consumes them, and as the request offers them. One projection. */
+export interface Adapted {
+  readonly tools: readonly ProjectableAction[];
+  readonly offered: readonly LlmTool[];
+}
+
+export function project(tools: readonly AgentTool[]): Adapted {
+  const projected = tools.map(asProjectableAction);
+  return { tools: projected, offered: toLlmTools(projected) };
+}
+
+/** One run's picks, resolved before anything is loaded, reserved or sent. */
+export interface PerRun extends RunCeilings {
+  readonly model: ModelId;
+  readonly adapted: Adapted;
+}
+
+type RunArgs<TInput extends StandardSchemaV1> = {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+};
+
+export async function resolvePerRun<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(
+  def: AgentDef<TInput, TOutput, V>,
+  declared: RunCeilings & { readonly adapted: Adapted },
+  args: RunArgs<TInput>,
+): Promise<PerRun> {
+  const name = def.prompt.ref;
+  // The declared budget first, so a bad declaration is refused whether or not a gateway exists —
+  // then the run's own ceilings, screened the same way after narrowing.
+  limitsOf(declared.budget);
+  const ceilings = narrowCeilings(
+    name,
+    declared,
+    def.limits === undefined ? undefined : await def.limits(args),
+  );
+  limitsOf(ceilings.budget);
+  const adapted =
+    def.offerTools === undefined
+      ? declared.adapted
+      : offered(name, declared.adapted, await def.offerTools(args));
+  const model = await modelOf(def, args);
+  return { ...ceilings, model, adapted };
+}
+
+/**
+ * The declaration, its prompt, then the gateway's `defaultModel` — the app's three places, with
+ * the first one asked per run when it is a function. A per-run id is refused here when it is not
+ * registered (`X_AI_MODEL_UNKNOWN`), before `vars()` loads anything: it is data the app read from
+ * somewhere, and the gateway's own check would come only after the load.
+ */
+async function modelOf<
+  TInput extends StandardSchemaV1,
+  TOutput extends StandardSchemaV1,
+  V extends PromptVars,
+>(def: AgentDef<TInput, TOutput, V>, args: RunArgs<TInput>): Promise<ModelId> {
+  const name = def.prompt.ref;
+  if (typeof def.model !== 'function') {
+    return modelForCall('agent', name, def.model, def.prompt.model);
+  }
+  const picked: unknown = await def.model(args);
+  if (picked !== undefined && (typeof picked !== 'string' || picked === '')) {
+    throw new AiRequestInvalidError({
+      detail: `agent "${name}" model() answered ${picked === '' ? 'an empty string' : typeof picked}, not a model id`,
+      fix: 'model: ({ input, ctx }) => modelId   # an id your app registerModel-ed, or undefined for the prompt model, then the gateway defaultModel',
+    });
+  }
+  const model = modelForCall('agent', name, picked, def.prompt.model);
+  modelSpec(model);
+  return model;
+}
+
+/**
+ * The declared tools narrowed to `names`, in the catalogue's own order (so the request is the same
+ * bytes whatever order a rule lists them in, and a provider's prompt cache still reads it back). A
+ * repeated name is one tool; a name the declaration does not list is refused, never dropped.
+ */
+function offered(agent: string, adapted: Adapted, names: unknown): Adapted {
+  if (!Array.isArray(names) || names.some((entry) => typeof entry !== 'string')) {
+    throw new AiRequestInvalidError({
+      detail: `agent "${agent}" offerTools() answered something other than an array of tool names`,
+      fix: "offerTools: ({ input, ctx }) => ['toolName']   # names from the agent's tools",
+    });
+  }
+  const wanted = new Set<string>(names);
+  const declared = adapted.tools.map((tool) => tool.name);
+  const unknown = [...wanted].filter((entry) => !declared.includes(entry));
+  if (unknown.length > 0) {
+    throw new AgentToolUndeclaredError({ agent, tools: unknown, declared });
+  }
+  const tools = adapted.tools.filter((tool) => wanted.has(tool.name));
+  return { tools, offered: adapted.offered.filter((tool) => wanted.has(tool.name)) };
+}

package/src/agent-run-limits.ts

@@ -0,0 +1,148 @@
+// Single responsibility: the ceilings ONE agent run runs under — the declared bounds narrowed by
+// that run's own `limits()`, never widened — and the run-level money ceiling (`costPerRun`),
+// checked before each turn. Split from ./agent-declared, which owns the declaration's half.
+
+import { finiteCount } from '@ultimat3/core';
+import type { Money } from '@ultimat3/money';
+import { assertSameCurrency, commonScale, exponentOf, minorAt } from '@ultimat3/money';
+import type { AgentBounds } from './agent-declared';
+import { SUBJECT } from './agent-declared';
+import type { AgentBudget, AgentRunLimits } from './agent-def';
+import { screenedMoney } from './budget';
+import { compareMoney } from './cost';
+import { AiBudgetExceededError, AiRequestInvalidError } from './errors';
+
+/** What one run is bounded by: the loop bounds, the deadline and the budget, after `limits()`. */
+export interface RunCeilings {
+  readonly bounds: AgentBounds;
+  readonly deadlineMs: number | undefined;
+  readonly budget: AgentBudget | undefined;
+}
+
+/** The key a refusal names: `limits().budget.tokensPerRun`, as the app's function wrote it. */
+const KEY = 'limits()';
+
+/**
+ * The run's ceilings: `asked` screened like a declared bound (`finiteCount` — a `NaN` here would
+ * switch a ceiling off), then held at or under `declared`. A higher value is refused, not clamped:
+ * a function that asks for more than the declaration allows is a wrong rule, and clamping it
+ * silently would hide that until a run needed the turns it was promised.
+ */
+export function narrowCeilings(
+  agent: string,
+  declared: RunCeilings,
+  asked: AgentRunLimits | undefined,
+): RunCeilings {
+  if (asked === undefined) return declared;
+  const lower = (
+    key: string,
+    value: number | undefined,
+    ceiling: number | undefined,
+    min: 0 | 1 = 0,
+  ): number | undefined => {
+    if (value === undefined) return ceiling;
+    const screened = finiteCount(SUBJECT, `${KEY}.${key}`, value, min);
+    if (ceiling !== undefined && screened > ceiling) refuseWider(agent, key, value, ceiling);
+    return screened;
+  };
+  const { bounds } = declared;
+  const repeats = lower(
+    'maxRepeatedToolCalls',
+    asked.maxRepeatedToolCalls,
+    bounds.maxRepeatedToolCalls,
+    1,
+  );
+  if (repeats !== undefined && repeats < 2) {
+    throw new AiRequestInvalidError({
+      detail: `agent "${agent}" limits() set maxRepeatedToolCalls to ${repeats}, which would stop the run at its first tool turn`,
+      fix: 'maxRepeatedToolCalls: 2   # in what limits() returns — at least 2; it counts consecutive identical turns, the first included',
+    });
+  }
+  const narrowed: AgentBounds = {
+    maxTurns: lower('maxTurns', asked.maxTurns, bounds.maxTurns, 1) ?? bounds.maxTurns,
+    maxTokens: lower('maxTokens', asked.maxTokens, bounds.maxTokens, 1) ?? bounds.maxTokens,
+    maxToolResultChars:
+      lower('maxToolResultChars', asked.maxToolResultChars, bounds.maxToolResultChars, 1) ??
+      bounds.maxToolResultChars,
+    maxRepeatedToolCalls: repeats ?? bounds.maxRepeatedToolCalls,
+  };
+  const deadlineMs = lower('deadlineMs', asked.deadlineMs, declared.deadlineMs, 1);
+  return {
+    bounds: narrowed,
+    deadlineMs,
+    budget: narrowBudget(agent, declared.budget, asked.budget),
+  };
+}
+
+function narrowBudget(
+  agent: string,
+  declared: AgentBudget | undefined,
+  asked: AgentBudget | undefined,
+): AgentBudget | undefined {
+  if (asked === undefined) return declared;
+  const count = (key: 'tokensIn' | 'tokensPerRun'): number | undefined => {
+    const value = asked[key];
+    const ceiling = declared?.[key];
+    if (value === undefined) return ceiling;
+    const screened = finiteCount(SUBJECT, `${KEY}.budget.${key}`, value);
+    if (ceiling !== undefined && screened > ceiling) {
+      refuseWider(agent, `budget.${key}`, value, ceiling);
+    }
+    return screened;
+  };
+  const money = (key: 'costPerCall' | 'costPerRun'): Money | undefined => {
+    const value = asked[key];
+    const ceiling = declared?.[key];
+    if (value === undefined) return ceiling;
+    screenedMoney(SUBJECT, `${KEY}.budget.${key}`, value);
+    if (ceiling !== undefined) {
+      assertSameCurrency(ceiling, value);
+      if (compareMoney(value, ceiling) > 0) {
+        refuseWider(agent, `budget.${key}`, `${value.minor} ${value.currency}`, ceiling.minor);
+      }
+    }
+    return value;
+  };
+  const tokensIn = count('tokensIn');
+  const tokensPerRun = count('tokensPerRun');
+  const costPerCall = money('costPerCall');
+  const costPerRun = money('costPerRun');
+  return {
+    ...(tokensIn === undefined ? {} : { tokensIn }),
+    ...(tokensPerRun === undefined ? {} : { tokensPerRun }),
+    ...(costPerCall === undefined ? {} : { costPerCall }),
+    ...(costPerRun === undefined ? {} : { costPerRun }),
+  };
+}
+
+function refuseWider(agent: string, key: string, value: number | string, ceiling: number): never {
+  throw new AiRequestInvalidError({
+    detail: `agent "${agent}" limits() asked for ${key} ${value}, over the declared ${ceiling} — a run may only lower a declared ceiling`,
+    fix: `${key}: ${ceiling}   # at most this in what limits() returns — or raise ${key} on the agent declaration first`,
+  });
+}
+
+/**
+ * `costPerRun`, before one turn: what the run has cost so far (every turn, every continuation,
+ * every nested call reported up) plus this turn's worst-case estimate, against the ceiling. The
+ * figures are compared at one scale and refused, never truncated, exactly as `costPerCall` is.
+ */
+export function assertRunCost(limit: Money, spent: Money, estimate: Money): void {
+  assertSameCurrency(limit, spent);
+  assertSameCurrency(limit, estimate);
+  const scale = Math.max(commonScale(limit, spent), commonScale(limit, estimate));
+  const ceiling = minorAt(limit, scale);
+  const used = minorAt(spent, scale);
+  const want = minorAt(estimate, scale);
+  if (used + want <= ceiling) return;
+  throw new AiBudgetExceededError({
+    scope: 'costPerRun',
+    requested: Number(want),
+    remaining: Number(ceiling - used),
+    limit: Number(ceiling),
+    unit:
+      scale === exponentOf(limit.currency)
+        ? `${limit.currency} minor units`
+        : `${limit.currency} at scale ${scale}`,
+  });
+}

package/src/agent.ts

@@ -35,12 +35,14 @@ import {
   sessionCalls,
   withTranscript,
 } from './agent-continue';
-import type { AgentBounds } from './agent-declared';
 import { factsOf, limitsOf, SUBJECT, screenBounds } from './agent-declared';
 import type { AgentDef } from './agent-def';
 import { AgentTranscriptInvalidError } from './agent-errors';
 import { registerAgentFact } from './agent-facts';
 import { runDeadline, toolLoopGuard } from './agent-guards';
+import type { Adapted, PerRun } from './agent-per-run';
+import { project, resolvePerRun } from './agent-per-run';
+import { assertRunCost } from './agent-run-limits';
 import { sameSystem, systemOf } from './agent-system';
 import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
 import { assertAnswerable, observeTurn } from './agent-turn';
@@ -49,11 +51,10 @@ import { LlmTruncatedError } from './answer-errors';
 import { budgetKeysFor, currentBudget, withBudget } from './budget';
 import { AgentMaxTurnsError, AgentToolUnexposedError, LlmOutputInvalidError } from './errors';
 import { answerAttributes } from './llm';
-import { modelForCall } from './model-resolve';
 import type { PromptVars } from './prompt';
 import { promptCacheHint } from './prompt-cache';
 import type { AiMessage, GenerateRequest } from './provider';
-import { isTruncated } from './provider';
+import { estimateCost, isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
 import type { Respond } from './respond';
 import { RESPOND, respondFor } from './respond';
@@ -61,10 +62,17 @@ import { runMeter } from './run-meter';
 import { aiGateway, aiRedactor, installedGateway } from './runtime';
 import type { Sampling } from './sampling';
 import { ignoredSamplingAttribute, screenSampling } from './sampling';
-import type { AgentTool, LlmTool, LlmToolResult, ProjectableAction } from './tools';
-import { asProjectableAction, isOfferedTool, runLlmToolCall, toLlmTools, toolLabel } from './tools';
+import type { LlmToolResult } from './tools';
+import { isOfferedTool, runLlmToolCall, toolLabel } from './tools';
 
-export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent-def';
+export type {
+  AgentBudget,
+  AgentDef,
+  AgentModel,
+  AgentRunLimits,
+  AgentTurn,
+  AgentVarsArgs,
+} from './agent-def';
 
 export function agent<
   TInput extends StandardSchemaV1,
@@ -84,6 +92,8 @@ export function agent<
     });
   }
   const bounds = screenBounds(def);
+  // What every run is held under; a run's `limits()` may only lower it (`narrowCeilings`).
+  const declared = { bounds, deadlineMs: def.deadlineMs, budget: def.budget };
   // This declaration's identity for `.run()` / `.continue()` sessions (`claimAgentSession`).
   const owner = {};
   const sampling = screenSampling(SUBJECT, def);
@@ -100,7 +110,14 @@ export function agent<
     output: def.output,
     policy: def.policy,
     ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
-    handle: (args) => run(def, respond, adapt(), { ...bounds, sampling, owner }, args),
+    handle: async (args) =>
+      run(
+        def,
+        respond,
+        await resolvePerRun(def, { ...declared, adapted: adapt() }, args),
+        { sampling, owner },
+        args,
+      ),
   });
   // A thunk, resolved when the manifest asks: every name in the row is stamped at boot, and this
   // line runs at module scope.
@@ -123,17 +140,6 @@ function continuable<TInput extends StandardSchemaV1, TOutput extends StandardSc
   });
 }
 
-/** The tools as `runLlmToolCall` consumes them, and as the request offers them. One projection. */
-interface Adapted {
-  readonly tools: readonly ProjectableAction[];
-  readonly offered: readonly LlmTool[];
-}
-
-function project(tools: readonly AgentTool[]): Adapted {
-  const projected = tools.map(asProjectableAction);
-  return { tools: projected, offered: toLlmTools(projected) };
-}
-
 async function run<
   TInput extends StandardSchemaV1,
   TOutput extends StandardSchemaV1,
@@ -141,24 +147,23 @@ async function run<
 >(
   def: AgentDef<TInput, TOutput, V>,
   respond: Respond,
-  adapted: Adapted,
-  bounds: AgentBounds & { readonly sampling: Sampling; readonly owner: object },
+  /** This run's picks — model, offered tools, ceilings — resolved from the declaration. */
+  picked: PerRun,
+  fixed: { readonly sampling: Sampling; readonly owner: object },
   args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
 ): Promise<InferOutput<TOutput>> {
   const { prompt } = def;
   const name = prompt.ref;
   // A `.continue()` in flight: its handle is the app's stored data, so it is screened before
   // anything is loaded, reserved or sent.
-  const session = claimAgentSession(bounds.owner);
+  const session = claimAgentSession(fixed.owner);
+  const { adapted, model, bounds } = picked;
   const resume = session?.resume;
   if (resume !== undefined && resume.user.trim() === '') {
     throw new AgentTranscriptInvalidError({ agent: name, reason: 'the user turn is empty' });
   }
-  // Screened first: a bad declaration is refused whether or not a gateway exists.
-  limitsOf(def);
-  // The declaration, its prompt, then the gateway's `defaultModel` — the app's three places.
-  const model = modelForCall('agent', name, def.model, prompt.model);
-  // What a handle is bound to, read off the declaration and the request — never off the handle.
+  // What a handle is bound to, read off the declaration and the request — never off the handle:
+  // the run's own model and the tools THIS run is offered.
   const binding: TranscriptBinding = {
     agent: name,
     model,
@@ -166,9 +171,10 @@ async function run<
     org: args.ctx.actor.orgId ?? null,
   };
   const prior = resume === undefined ? undefined : screenTranscript(binding, resume.transcript);
-  const limits = limitsOf(def, prior?.usage);
+  const limits = limitsOf(picked.budget, prior?.usage);
+  const costPerRun = picked.budget?.costPerRun;
   // Armed before anything is loaded: `vars()` is part of the run a deadline bounds.
-  const deadline = runDeadline(name, def.deadlineMs, args.ctx.signal);
+  const deadline = runDeadline(name, picked.deadlineMs, args.ctx.signal);
   const redact = aiRedactor();
   // A continuation does not render the prompt again: the transcript holds what was sent, and
   // `vars()` — the load — is not run a second time. Its own turn is the caller's text.
@@ -185,6 +191,7 @@ async function run<
   const system = systemOf(prompt.system, extra, redact);
   const promptCache = promptCacheHint(def.promptCache, 'auto', args);
   const repeated = toolLoopGuard(name, bounds.maxRepeatedToolCalls);
+  const sampling = fixed.sampling;
   const { maxTurns, maxToolResultChars: chars } = bounds;
 
   return withSpan('ai.agent', async (span) => {
@@ -200,9 +207,7 @@ async function run<
     // 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),
-        ),
+        ignoredSamplingAttribute(model, sampling, () => installedGateway()?.samplingWires?.(model)),
       );
     };
 
@@ -220,7 +225,7 @@ async function run<
       maxTokens: bounds.maxTokens,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
       ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
-      ...bounds.sampling,
+      ...sampling,
       tools: [...adapted.offered, respond.tool],
       // The caller's own signal, forwarded to the transport. A disconnect has to reach the socket,
       // not just the top of the next turn: a provider call already in flight is the expensive one.
@@ -254,8 +259,17 @@ async function run<
         // budget, runs every remaining tool's side effects, and discards the answer.
         throwIfAborted(args.ctx);
         deadline.check();
+        const request: GenerateRequest = { ...base, messages };
+        if (costPerRun !== undefined) {
+          // Worst case: the run so far (continuations and nested calls included) plus this turn,
+          // estimated as the gateway's own reservation will be — at the write rate only where a
+          // provider serving the model would mark the request.
+          const spent = runTotal(model, prior?.usage, meter.total(), meter.below()).costExact;
+          const marked = gateway.marksPromptCache?.(model) === true;
+          assertRunCost(costPerRun, spent, estimateCost(request, marked));
+        }
         const result = await deadline
-          .guard(meter.call(gateway.generate({ ...base, messages })))
+          .guard(meter.call(gateway.generate(request)))
           .catch((error: unknown) => {
             // The caller left mid-call: the aborted socket reads as a provider failure, which is
             // RETRYABLE. Say what happened instead.

package/src/errors-retry.ts

@@ -52,6 +52,9 @@ export const AI_ERROR_RETRY = {
   X_LLM_OUTPUT_INVALID: 'terminal',
   X_LLM_TOOL_ARGUMENTS_INVALID: 'terminal',
   X_AGENT_TRANSCRIPT_INVALID: 'terminal',
+  // A run whose `offerTools()` named an undeclared tool names it again on the next attempt: the
+  // fix is the declaration or the app's own rule, never a retry.
+  X_AGENT_TOOL_UNDECLARED: 'terminal',
 } as const satisfies Readonly<Partial<Record<AiErrorCode, ErrorRetry>>>;
 
 // `Partial`, so the table may be a subset — but every key is still checked against the declared set,

package/src/errors.ts

@@ -35,6 +35,7 @@ export const AI_ERROR_CODES = [
   'X_LLM_TOOL_ARGUMENTS_INVALID',
   'X_AGENT_TRANSCRIPT_INVALID',
   'X_AI_PROVIDER_UNEXPECTED',
+  'X_AGENT_TOOL_UNDECLARED',
 ] as const;
 
 export type AiErrorCode = (typeof AI_ERROR_CODES)[number];
@@ -73,6 +74,7 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_AGENT_TRANSCRIPT_INVALID: 'an agent was asked to continue from a transcript it cannot read',
   X_AI_PROVIDER_UNEXPECTED:
     'a provider ended a turn with an unknown reason and an incomplete answer',
+  X_AGENT_TOOL_UNDECLARED: 'an agent run offered a tool its declaration does not list',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Unconditional and

package/src/gateway.ts

@@ -86,6 +86,12 @@ export interface ProviderGatewayInput {
 export interface Gateway {
   /** The wire formats of the providers serving `model` — what `llm.sampling.ignored` is read from. */
   samplingWires?(model: ModelId): readonly SamplingWire[];
+  /**
+   * Whether a provider serving `model` would send a hinted request with a cache mark — so its
+   * worst-case estimate prices the prompt at the write rate. Read by `agent()`'s `costPerRun`
+   * check to estimate a turn exactly as the gateway's own reservation does; absent reads as no.
+   */
+  marksPromptCache?(model: ModelId): boolean;
   /**
    * The model a call with none declared runs on — `providerGateway({ defaultModel })`. Read by
    * `llm()` and `agent()` after the declaration and its prompt, so the app's choice is the one
@@ -184,7 +190,9 @@ class GatewayImpl implements Gateway {
     // The estimate is DEBITED here, not merely checked: three concurrent calls under one ledger
     // all read the same `spent()` otherwise, all pass, and all three record against a ceiling
     // only one of them fitted.
-    const reservation = await ledger?.reserve(estimateSpend(resolved, this.marks(model)));
+    const reservation = await ledger?.reserve(
+      estimateSpend(resolved, this.marksPromptCache(model)),
+    );
 
     let result: GenerateResult;
     try {
@@ -246,7 +254,9 @@ class GatewayImpl implements Gateway {
     const provider = this.providerFor(model);
 
     const ledger = currentBudget() ?? this.callLedger({});
-    const reservation = await ledger?.reserve(estimateSpend(resolved, this.marks(model)));
+    const reservation = await ledger?.reserve(
+      estimateSpend(resolved, this.marksPromptCache(model)),
+    );
     let settled = false;
     try {
       for await (const chunk of provider.stream(resolved)) {
@@ -284,7 +294,7 @@ class GatewayImpl implements Gateway {
   }
 
   /** Whether any provider serving `model` would send a hinted request with a cache mark. */
-  private marks(model: ModelId): boolean {
+  marksPromptCache(model: ModelId): boolean {
     return this.config.providers.some(
       (p) => p.models.includes(model) && p.marksPromptCache?.(model) === true,
     );

package/src/index.ts

@@ -17,10 +17,18 @@ export {
   TRANSCRIPT_VERSION,
   transcriptOf,
 } from './agent-continue';
-export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent-def';
+export type {
+  AgentBudget,
+  AgentDef,
+  AgentModel,
+  AgentRunLimits,
+  AgentTurn,
+  AgentVarsArgs,
+} from './agent-def';
 export {
   AgentDeadlineError,
   AgentToolLoopError,
+  AgentToolUndeclaredError,
   AgentTranscriptInvalidError,
 } from './agent-errors';
 export type { AgentBudgetFact, AgentFact } from './agent-facts';