@ultimat3/ai 27.8.0 → 27.9.0

package/src/agent-system.ts

@@ -0,0 +1,37 @@
+// Single responsibility: the system prompt ONE agent run sends — the prompt's static text and what
+// the declaration's `system()` loaded, composed into the stable and per-run parts a cache keys on.
+
+import type { SystemPrompt } from './prompt-cache';
+
+/**
+ * What `system()` adds to the prompt's own `system`. `stable` joins it in the block every run
+ * shares — it must be BYTE-identical run to run (sorted, undated), or each run pays a full cache
+ * write for it. `run` is a second block after it, for whatever differs.
+ */
+export interface AgentSystem {
+  readonly stable?: string;
+  readonly run?: string;
+}
+
+/**
+ * The system prompt one run sends: the prompt's static text and `system()`'s stable part as ONE
+ * block (the half every run shares), the per-run part after it. A plain string when there is no
+ * per-run part — the shape every request had before the parts existed.
+ */
+export function systemOf(
+  fixed: string | undefined,
+  extra: AgentSystem,
+  redact: (text: string) => string,
+): SystemPrompt | undefined {
+  const stable = [fixed ?? '', extra.stable ?? '']
+    .filter((part) => part !== '')
+    .map(redact)
+    .join('\n\n');
+  const run = extra.run === undefined || extra.run === '' ? '' : redact(extra.run);
+  if (run !== '') return { stable, run };
+  return fixed === undefined && stable === '' ? undefined : stable;
+}
+
+/** Whether two composed prompts are the same text — what `llm.redacted` compares. */
+export const sameSystem = (a: SystemPrompt | undefined, b: SystemPrompt | undefined): boolean =>
+  JSON.stringify(a) === JSON.stringify(b);

package/src/agent-usage.ts

@@ -0,0 +1,27 @@
+// Single responsibility: a run's running token and money total, across its turns.
+
+import type { Money } from '@ultimat3/money';
+import type { GenerateResult, TokenUsage } from './provider';
+import { costOf } from './provider';
+
+/** The run so far, this turn included. */
+export interface AgentRunUsage {
+  readonly usage: TokenUsage;
+  readonly cost: Money;
+}
+
+/**
+ * The run's total after one more turn. The cost is re-priced from the summed usage rather than
+ * summed per turn: each turn's cost is rounded UP to a minor unit, and ten round-ups is not the
+ * price of the run.
+ */
+export function addUsage(total: AgentRunUsage | undefined, result: GenerateResult): AgentRunUsage {
+  const before = total?.usage;
+  const usage: TokenUsage = {
+    inputTokens: (before?.inputTokens ?? 0) + result.usage.inputTokens,
+    outputTokens: (before?.outputTokens ?? 0) + result.usage.outputTokens,
+    cacheReadTokens: (before?.cacheReadTokens ?? 0) + result.usage.cacheReadTokens,
+    cacheWriteTokens: (before?.cacheWriteTokens ?? 0) + result.usage.cacheWriteTokens,
+  };
+  return { usage, cost: costOf(result.model, usage) };
+}

package/src/agent.ts

@@ -20,38 +20,36 @@
  * one run's world state to another. Version bump plus the tools' own caching is the story.
  */
 
-import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
+import type { Action } from '@ultimat3/action';
 import { action } from '@ultimat3/action';
 import type { Ctx, Span } from '@ultimat3/core';
 import { finiteCount, isMcpExposed, throwIfAborted, withSpan } from '@ultimat3/core';
-import type { Money } from '@ultimat3/money';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, validateAsync } from '@ultimat3/schema';
+import type { AgentDef, AgentTurn } from './agent-def';
 import type { AgentFact } from './agent-facts';
 import { registerAgentFact } from './agent-facts';
+import { DEFAULT_MAX_REPEATED_TOOL_CALLS, runDeadline, toolLoopGuard } from './agent-guards';
+import { sameSystem, systemOf } from './agent-system';
 import { assistantTurn, repairTurn, toolResultTurn } from './agent-transcript';
+import type { AgentRunUsage } from './agent-usage';
+import { addUsage } from './agent-usage';
 import type { BudgetLimits } from './budget';
 import { budgetKeysFor, currentBudget, screenedMoney, withBudget } from './budget';
 import {
   AgentMaxTurnsError,
   AgentToolUnexposedError,
+  AiRequestInvalidError,
   LlmOutputInvalidError,
   LlmRefusedError,
   LlmTruncatedError,
 } from './errors';
-import type { LlmBudget } from './llm';
 import { answerAttributes } from './llm';
 import { describedModel, type ModelSource, modelForCall } from './model-resolve';
-import type { ModelId } from './models';
 import { moreCapableThan } from './models';
-import type { Prompt, PromptVars } from './prompt';
-import type {
-  AiMessage,
-  GenerateRequest,
-  GenerateResult,
-  StopReason,
-  TokenUsage,
-} from './provider';
+import type { PromptVars } from './prompt';
+import { promptCacheHint } from './prompt-cache';
+import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
 import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
 import type { Respond } from './respond';
@@ -80,76 +78,7 @@ const DEFAULT_TOOL_RESULT_CHARS = 4_000;
 /** Named in every bound refusal, so the fix names the key the declaration carries. */
 const SUBJECT = 'agent';
 
-export interface AgentBudget extends LlmBudget {
-  /**
-   * Token ceiling for the WHOLE run, every turn counted. The one ceiling `llm()` does not need:
-   * a single call is bounded by `maxTokens`, a loop is bounded by nothing until this is set.
-   */
-  readonly tokensPerRun?: number;
-}
-
-export interface AgentVarsArgs<TInput extends StandardSchemaV1> {
-  readonly input: InferOutput<TInput>;
-  readonly ctx: Ctx;
-}
-
-export interface AgentDef<
-  TInput extends StandardSchemaV1,
-  TOutput extends StandardSchemaV1,
-  V extends PromptVars,
-> {
-  readonly model?: ModelId;
-  readonly input: TInput;
-  readonly output: TOutput;
-  readonly prompt: Prompt<V>;
-  /** Same contract as `llm()`: the one declared place a run loads data. */
-  vars(args: AgentVarsArgs<TInput>): V | Promise<V>;
-  /**
-   * The actions the model may call. Each must be `mcp: { expose: true }` — the same predicate an
-   * external MCP client is filtered by, so an in-app agent and an external one are offered
-   * exactly the same tools. Listing one that is not exposed is refused at declaration rather than
-   * dropped, because a tool that reads as offered and silently is not is the worst of both.
-   */
-  readonly tools: readonly AgentTool[];
-  /** Hard ceiling on model turns. Reaching it is `X_AGENT_MAX_TURNS`, never a partial answer. */
-  readonly maxTurns?: number;
-  readonly maxToolResultChars?: number;
-  readonly budget?: AgentBudget;
-  readonly policy: ActionPolicy;
-  readonly mcp?: ActionMcp;
-  /** Enforced completion ceiling PER TURN. The model never sees it. */
-  readonly maxTokens?: number;
-  /**
-   * Called once per completed model turn, before the answer or the tool calls are acted on. The
-   * one thing a multi-turn run could not do until 2026-08: a 90-second loop emitted nothing until
-   * it returned, so a progress indicator, a per-turn spend line and a transcript log all had to be
-   * hand-rolled outside the framework — which is exactly the loop `agent()` exists to replace.
-   *
-   * Observation only: it cannot steer the loop, cannot see the transcript and cannot reach the
-   * actor. A throw from it FAILS the run rather than being swallowed — it is the app's code on the
-   * run's own path, and an observer that silently stopped working would be indistinguishable from
-   * one that is fine. The same facts land on the span as an `agent.turn` event, so a run that
-   * declares no hook is still readable in a trace.
-   *
-   * NOT `.stream()`. Tokens on a screen is a different contract, and `llm()`'s streamed half is
-   * one turn deep by construction; this is per TURN.
-   */
-  onTurn?(event: AgentTurn): void | Promise<void>;
-}
-
-/** One completed model turn, as an observer sees it. Facts only — no transcript, no actor. */
-export interface AgentTurn {
-  /** 1-based, so `turn === maxTurns` is the last one this run will take. */
-  readonly turn: number;
-  readonly maxTurns: number;
-  readonly model: ModelId;
-  /** Tools this turn asked for, in the order the model emitted them. `respond` is not one. */
-  readonly toolCalls: readonly string[];
-  readonly stopReason: StopReason;
-  readonly usage: TokenUsage;
-  /** This turn's cost alone, integer minor units — never the run's running total. */
-  readonly cost: Money;
-}
+export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent-def';
 
 export function agent<
   TInput extends StandardSchemaV1,
@@ -183,6 +112,21 @@ export function agent<
     1,
   );
   finiteCount(SUBJECT, 'maxTokens', def.maxTokens ?? DEFAULT_MAX_TOKENS, 1);
+  const repeats = finiteCount(
+    SUBJECT,
+    'maxRepeatedToolCalls',
+    def.maxRepeatedToolCalls ?? DEFAULT_MAX_REPEATED_TOOL_CALLS,
+    1,
+  );
+  if (repeats < 2) {
+    // One "repeat" is the first tool turn of every run: the agent could never use a tool.
+    throw new AiRequestInvalidError({
+      detail: `agent maxRepeatedToolCalls is ${repeats}, which would stop every run at its first tool turn`,
+      fix: 'maxRepeatedToolCalls: 3   # on the agent — at least 2; it counts consecutive identical turns, the first included',
+    });
+  }
+  // `AbortSignal.timeout(NaN)` throws a RangeError mid-run; `0` aborts before turn one.
+  if (def.deadlineMs !== undefined) finiteCount(SUBJECT, 'deadlineMs', def.deadlineMs, 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`.
@@ -267,12 +211,19 @@ async function run<
   const limits = 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);
-  const vars = await def.vars({ input: args.input, ctx: args.ctx });
+  // Armed before anything is loaded: `vars()` is part of the run a deadline bounds.
+  const deadline = runDeadline(name, def.deadlineMs, args.ctx.signal);
+  const vars = await deadline.guard(Promise.resolve(def.vars(args)));
   assertNoSecrets(name, vars);
   const redact = aiRedactor();
   const rawPrompt = prompt.render(vars);
   const rendered = redact(rawPrompt);
-  const system = prompt.system === undefined ? undefined : redact(prompt.system);
+  const extra =
+    def.system === undefined ? {} : await deadline.guard(Promise.resolve(def.system(args)));
+  const rawSystem = systemOf(prompt.system, extra, (text) => text);
+  const system = systemOf(prompt.system, extra, redact);
+  const promptCache = promptCacheHint(def.promptCache, 'auto', args);
+  const repeated = toolLoopGuard(name, def.maxRepeatedToolCalls ?? DEFAULT_MAX_REPEATED_TOOL_CALLS);
   const maxTurns = def.maxTurns ?? DEFAULT_MAX_TURNS;
   const chars = def.maxToolResultChars ?? DEFAULT_TOOL_RESULT_CHARS;
 
@@ -283,7 +234,8 @@ async function run<
       'agent.prompt.hash': prompt.hash,
       'agent.tools': adapted.offered.length,
       'agent.max_turns': maxTurns,
-      'llm.redacted': rendered !== rawPrompt || system !== prompt.system,
+      'llm.redacted': rendered !== rawPrompt || !sameSystem(system, rawSystem),
+      'llm.prompt_cache': promptCache !== undefined,
     });
 
     // Rooted in the GATEWAY's own ceilings when no scope is open — an empty root ignored them.
@@ -295,6 +247,7 @@ async function run<
     const base: GenerateRequest = {
       model,
       ...(system === undefined ? {} : { system }),
+      ...(promptCache === undefined ? {} : { promptCache }),
       messages: [],
       maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
@@ -302,7 +255,8 @@ async function run<
       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.
-      signal: args.ctx.signal,
+      // The run's deadline is folded into the same signal, so it reaches the socket too.
+      signal: deadline.signal,
     };
 
     return withBudget(ledger, async () => {
@@ -313,13 +267,23 @@ async function run<
       let messages: readonly AiMessage[] = [{ role: 'user', content: rendered }];
       let calls = 0;
       let issues: string | undefined;
+      let total: AgentRunUsage | undefined;
 
       for (let turn = 1; turn <= maxTurns; turn += 1) {
         // The caller is gone, so unwind instead of finishing. Every turn re-sends the WHOLE
         // transcript, so a loop that keeps going after a disconnect spends the rest of the run's
         // budget, runs every remaining tool's side effects, and discards the answer.
         throwIfAborted(args.ctx);
-        const result = await gateway.generate({ ...base, messages });
+        deadline.check();
+        const result = await deadline
+          .guard(gateway.generate({ ...base, messages }))
+          .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);
+            throw error;
+          });
+        total = addUsage(total, result);
         const requested = result.toolCalls.filter((call) => call.name !== RESPOND);
         // The same turn's `respond` calls, kept rather than forgotten: they are never RUN, but
         // `assistantTurn` replays them, and every replayed `tool_use` has to be answered.
@@ -337,6 +301,7 @@ async function run<
           stopReason: result.stopReason,
           usage: result.usage,
           cost: result.cost,
+          run: total,
         });
         assertAnswerable(result, name, base);
 
@@ -352,10 +317,17 @@ async function run<
           // 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);
-          const results: readonly LlmToolResult[] = await Promise.all(
-            requested.map((call) => runLlmToolCall(adapted.tools, call, actor)),
+          deadline.check();
+          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))),
+            ),
           );
           calls += requested.length;
+          // 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),
@@ -408,6 +380,10 @@ async function observeTurn<
     'agent.turn.tool_calls': event.toolCalls.length,
     'llm.stop': event.stopReason,
     'llm.cost.minor': event.cost.minor,
+    // 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,
   });
   await def.onTurn?.(event);
 }

package/src/budget.ts

@@ -57,11 +57,12 @@ export interface SpendEstimate {
 }
 
 /** Price a request pre-flight. The pessimistic read on purpose — see `estimateCost`. */
-export function estimateSpend(request: GenerateRequest): SpendEstimate {
+export function estimateSpend(request: GenerateRequest, marked = false): SpendEstimate {
   return {
     inputTokens: estimateInputTokens(request),
     tokens: estimateTokens(request),
-    cost: estimateCost(request),
+    // `marked`: a provider would send this request with a cache mark, so it can bill as a write.
+    cost: estimateCost(request, marked),
   };
 }
 

package/src/errors-retry.ts

@@ -38,6 +38,12 @@ export const AI_ERROR_RETRY = {
   // be both, and registering the code here is what makes the override honoured: core reads an
   // instance `terminal` on an UNREGISTERED code as unclassified.
   X_AI_PROVIDER_UNAVAILABLE: 'retryable',
+  // The two stops an unattended `agent()` run makes, REGISTERED terminal — the deliberate decision
+  // the paragraph above leaves to whoever makes it. A run stopped for repeating itself repeats
+  // itself again, and a run that outlived its declared deadline is the same run against the same
+  // deadline: unclassified, an `agentJob` with `attempts: 3` paid for it three times.
+  X_AGENT_TOOL_LOOP: 'terminal',
+  X_AGENT_DEADLINE: '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

@@ -30,6 +30,8 @@ export const AI_ERROR_CODES = [
   'X_VECTOR_UNSCOPED',
   'X_AI_CONTENT_UNSUPPORTED',
   'X_AI_MODEL_UNRESOLVED',
+  'X_AGENT_TOOL_LOOP',
+  'X_AGENT_DEADLINE',
 ] as const;
 
 export type AiErrorCode = (typeof AI_ERROR_CODES)[number];
@@ -61,6 +63,8 @@ export const AI_ERROR_TITLES: Readonly<Record<AiErrorCode, string>> = {
   X_VECTOR_UNSCOPED: 'a vector store was read with no tenant bound inside an org request',
   X_AI_CONTENT_UNSUPPORTED: 'an image or document block the role, model or wire format cannot take',
   X_AI_MODEL_UNRESOLVED: 'a model call named no model',
+  X_AGENT_TOOL_LOOP: 'an agent repeated one tool call with one result and was stopped',
+  X_AGENT_DEADLINE: 'an agent ran past its declared deadline and was stopped',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Unconditional and

package/src/gateway.ts

@@ -180,7 +180,7 @@ 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));
+    const reservation = await ledger?.reserve(estimateSpend(resolved, this.marks(model)));
 
     let result: GenerateResult;
     try {
@@ -230,7 +230,7 @@ class GatewayImpl implements Gateway {
     const provider = this.providerFor(model);
 
     const ledger = currentBudget() ?? this.callLedger({});
-    const reservation = await ledger?.reserve(estimateSpend(resolved));
+    const reservation = await ledger?.reserve(estimateSpend(resolved, this.marks(model)));
     let settled = false;
     try {
       for await (const chunk of provider.stream(resolved)) {
@@ -251,6 +251,13 @@ class GatewayImpl implements Gateway {
     }
   }
 
+  /** Whether any provider serving `model` would send a hinted request with a cache mark. */
+  private marks(model: ModelId): boolean {
+    return this.config.providers.some(
+      (p) => p.models.includes(model) && p.marksPromptCache?.(model) === true,
+    );
+  }
+
   private providerFor(model: ModelId): Provider {
     const provider = this.config.providers.find((p) => p.models.includes(model));
     if (provider === undefined) {

package/src/index.ts

@@ -4,12 +4,15 @@
 /** Re-exported so an `llm` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
-export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent';
 export { agent } from './agent';
+export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent-def';
+export { AgentDeadlineError, AgentToolLoopError } from './agent-errors';
 export type { AgentBudgetFact, AgentFact } from './agent-facts';
 export { describeAgents, resetAgents } from './agent-facts';
 export type { AgentJobOptions } from './agent-job';
 export { agentJob } from './agent-job';
+export type { AgentSystem } from './agent-system';
+export type { AgentRunUsage } from './agent-usage';
 export type {
   BudgetKeys,
   BudgetLedger,
@@ -177,6 +180,21 @@ export {
   promptVersions,
   resetPrompts,
 } from './prompt';
+export type {
+  CacheWire,
+  PromptCacheHint,
+  PromptCacheOption,
+  PromptCacheRule,
+  SystemParts,
+  SystemPrompt,
+} from './prompt-cache';
+export {
+  OPENAI_CACHE_KEY_MAX,
+  PROMPT_CACHE_RULES,
+  promptCacheRule,
+  SESSION_KEY_MAX,
+  systemText,
+} from './prompt-cache';
 export { promptFences } from './prompt-fence';
 export type {
   AiContentBlock,

package/src/llm.ts

@@ -45,6 +45,8 @@ import { modelForCall } from './model-resolve';
 import type { ModelId } from './models';
 import { moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
+import type { PromptCacheOption } from './prompt-cache';
+import { promptCacheHint } from './prompt-cache';
 import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
 import { isTruncated } from './provider';
 import { assertNoSecrets } from './redaction';
@@ -94,6 +96,13 @@ export interface LlmDef<
    */
   vars(args: LlmVarsArgs<TInput>): V | Promise<V>;
   readonly cache?: LlmCache<InferOutput<TInput>>;
+  /**
+   * PROVIDER prompt caching (`./prompt-cache`) — not `cache`, which is this package's own semantic
+   * cache. Default `'off'`: a one-shot call marked for caching pays the write premium (1.25x on
+   * Anthropic) for a prefix nothing may ever read back. `'auto'` is for a call made many times
+   * inside the cache's lifetime with one long `system`; the repair turn reads it back either way.
+   */
+  readonly promptCache?: PromptCacheOption<LlmVarsArgs<TInput>>;
   readonly budget?: LlmBudget;
   readonly policy: ActionPolicy;
   readonly mcp?: ActionMcp;
@@ -207,6 +216,7 @@ async function generate<
   const rendered = redact(rawPrompt);
   const system = prompt.system === undefined ? undefined : redact(prompt.system);
   const redacted = rendered !== rawPrompt || system !== prompt.system;
+  const promptCache = promptCacheHint(def.promptCache, 'off', args);
 
   return withSpan('ai.llm', async (span) => {
     span.setAttributes({
@@ -239,6 +249,7 @@ async function generate<
     const base: GenerateRequest = {
       model,
       ...(system === undefined ? {} : { system }),
+      ...(promptCache === undefined ? {} : { promptCache }),
       messages: [{ role: 'user', content: rendered }],
       maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),

package/src/openai-body.ts

@@ -9,6 +9,7 @@ import { AiRequestInvalidError } from './errors';
 import type { Effort, ModelId, ThinkingMode } from './models';
 import { modelSpec } from './models';
 import { toOpenAiMessages, toOpenAiTools, toolChoiceFor } from './openai-messages';
+import { OPENAI_CACHE_KEY_MAX, promptCacheRule, SESSION_KEY_MAX } from './prompt-cache';
 import type { GenerateRequest } from './provider';
 
 export interface ChatCompletionBodyInput {
@@ -18,6 +19,8 @@ export interface ChatCompletionBodyInput {
   /** The provider's `name`, so a content refusal names the endpoint that cannot take the block. */
   readonly provider: string;
   readonly stream: boolean;
+  /** The endpoint, for `PROMPT_CACHE_RULES` — which host this is decides what a cache hint sends. */
+  readonly baseUrl?: string | undefined;
 }
 
 /**
@@ -33,9 +36,12 @@ export function chatCompletionBody(input: ChatCompletionBodyInput): Record<strin
   const { request, model, stream, provider } = input;
   const spec = modelSpec(model);
   assertMediaContent(request.messages, { provider, model });
+  const hint = request.promptCache;
+  const rule = promptCacheRule('openai', input.baseUrl, model);
+  const marked = hint !== undefined && rule.marks === 'parts';
   const body: Record<string, unknown> = {
     model,
-    messages: toOpenAiMessages(request.system, request.messages, { provider, model }),
+    messages: toOpenAiMessages(request.system, request.messages, { provider, model }, marked),
     max_completion_tokens: Math.min(request.maxTokens, spec.maxOutput),
     ...reasoningFields(model, request.effort, request.thinking),
   };
@@ -47,6 +53,11 @@ export function chatCompletionBody(input: ChatCompletionBodyInput): Record<strin
   if (request.stopSequences !== undefined && request.stopSequences.length > 0) {
     body['stop'] = request.stopSequences;
   }
+  // OpenAI's own grouping key. OpenRouter's session rides a header instead (`sessionHeaders`), so
+  // the body never carries two spellings of one key.
+  if (hint?.session !== undefined && rule.session === 'prompt_cache_key') {
+    body['prompt_cache_key'] = cacheKey(hint.session);
+  }
   if (stream) {
     body['stream'] = true;
     // Without this the final chunk carries no `usage` and the budget reconciles against nothing —
@@ -57,6 +68,44 @@ export function chatCompletionBody(input: ChatCompletionBodyInput): Record<strin
   return body;
 }
 
+/** The headers a cache hint adds for this endpoint and model: OpenRouter's stickiness key, or none. */
+export function sessionHeaders(
+  request: GenerateRequest,
+  model: ModelId,
+  baseUrl: string | undefined,
+): Readonly<Record<string, string>> {
+  const session = request.promptCache?.session;
+  if (session === undefined) return {};
+  if (promptCacheRule('openai', baseUrl, model).session !== 'x-session-id') return {};
+  return { 'x-session-id': sessionKey(session) };
+}
+
+/**
+ * OpenAI's grouping key. Never cut — a truncated key is a different key two tenants can share —
+ * and never refused for length: over `OPENAI_CACHE_KEY_MAX` it is sent as a hash of itself, which
+ * groups the same requests. `h:` plus 62 hex characters of its SHA-256.
+ */
+function cacheKey(session: string): string {
+  if (session === '') return sessionKey(session);
+  if (session.length <= OPENAI_CACHE_KEY_MAX) return session;
+  const digest = new Bun.CryptoHasher('sha256').update(session).digest('hex');
+  return `h:${digest.slice(0, OPENAI_CACHE_KEY_MAX - 2)}`;
+}
+
+/**
+ * OpenRouter's header. Refused, never cut: a truncated key is a DIFFERENT key that two tenants can
+ * share, and a control character in a header value is a request the runtime refuses with no code.
+ */
+function sessionKey(session: string): string {
+  if (session !== '' && session.length <= SESSION_KEY_MAX && !/[^\x20-\x7e]/.test(session)) {
+    return session;
+  }
+  throw new AiRequestInvalidError({
+    detail: `the prompt-cache session key is ${session.length} characters; it must be 1 to ${SESSION_KEY_MAX} printable ASCII characters to travel as a header`,
+    fix: `promptCache: { session: 'kb-agent' }   # at most ${SESSION_KEY_MAX} printable ASCII characters (the x-session-id header's limit): a short, stable, non-secret name`,
+  });
+}
+
 /**
  * The reasoning half, shaped for one model. Refused LOCALLY when the model's spec says the endpoint
  * has no such control, for the reason models.ts states: a round trip to learn a rule the registry