@ultimat3/ai 2.0.0 → 4.0.0

package/src/hive-pool.ts

@@ -0,0 +1,90 @@
+// The bounded, order-preserving, cancellation-linked worker pool a hive fans out through.
+//
+// Apart from `hive.ts` because it is a different job with a different failure mode: that file owns
+// the declaration and the budget scope, this one owns "how many at once, in what order, and what
+// happens to the siblings when one throws". Nothing here knows what a model is.
+
+import type { Ctx } from '@ultimat3/core';
+import { isThrownError, isUltimateError, stringField, withChildContext } from '@ultimat3/core';
+import type { HiveMember, HiveMemberError } from './hive-result';
+import { SKIPPED_ABORTED, SKIPPED_NO_INPUT } from './hive-result';
+
+export interface PoolInput<I, O> {
+  readonly inputs: readonly I[];
+  readonly width: number;
+  readonly ctx: Ctx;
+  readonly onMemberError: HiveMemberError;
+  /** One member run. The caller supplies it already bound, so this file never sees an action. */
+  member(payload: I): Promise<O>;
+}
+
+/**
+ * A bounded pool of `width` workers over one shared cursor. Results land BY INDEX, so the answer is
+ * in split order however the members interleave — `Promise.all` over a mapped array would give the
+ * same ordering but no ceiling, and a settle-ordered push would give neither.
+ *
+ * The controller is linked to `ctx.signal` in both directions that matter: the caller going away
+ * aborts every member, and `onMemberError: 'abort'` aborts the siblings without touching the
+ * caller's own signal. Each member runs under `withChildContext({ signal })`, which carries the
+ * actor forward untouched — the hive never names an identity.
+ */
+export async function runPool<I, O>(input: PoolInput<I, O>): Promise<readonly HiveMember<O>[]> {
+  const { inputs, width, ctx } = input;
+  const members = new Array<HiveMember<O>>(inputs.length);
+  const controller = new AbortController();
+  const relay = (): void => controller.abort();
+  if (ctx.signal.aborted) controller.abort();
+  ctx.signal.addEventListener('abort', relay, { once: true });
+
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    for (;;) {
+      const index = cursor;
+      cursor += 1;
+      if (index >= inputs.length) return;
+      const payload = inputs[index];
+      // Every index is claimed by exactly one worker and assigned exactly once, so the array has
+      // no holes for a caller to trip over — `skipped` is a recorded outcome, never an absence.
+      // Two reasons, because they are two facts: the run stopped, or the split had nothing here.
+      if (controller.signal.aborted || payload === undefined) {
+        const reason = controller.signal.aborted ? SKIPPED_ABORTED : SKIPPED_NO_INPUT;
+        members[index] = { status: 'skipped', index, reason };
+        continue;
+      }
+      try {
+        const value = await withChildContext({ signal: controller.signal }, () =>
+          input.member(payload),
+        );
+        members[index] = { status: 'ok', index, value };
+      } catch (error) {
+        members[index] = { status: 'failed', index, ...failureOf(error) };
+        if (input.onMemberError === 'abort') controller.abort();
+      }
+    }
+  };
+
+  try {
+    await Promise.all(Array.from({ length: width }, worker));
+  } finally {
+    ctx.signal.removeEventListener('abort', relay);
+  }
+  return members;
+}
+
+/**
+ * What a member threw, as two data fields — never as an error's `cause:`, which is why the thrown
+ * value is read structurally and never interpolated. A foreign throw gets `'unknown'` rather than
+ * an invented `X_` code: a code nothing declares is a code no `x errors explain` can answer.
+ */
+function failureOf(error: unknown): { readonly code: string; readonly reason: string } {
+  if (isUltimateError(error)) return { code: error.code, reason: error.cause };
+  // `isThrownError` and `stringField`, never `error instanceof Error` and `.message`: a member
+  // is an app's action, so the value is one the framework did not build — `instanceof` runs a
+  // `Proxy`'s `getPrototypeOf` trap and `.message` is a getter call. A throw HERE would take the
+  // whole hive down with it, which is the one outcome the three arms exist to prevent.
+  const message = stringField(error, 'message');
+  if (isThrownError(error) && message !== undefined && message !== '') {
+    return { code: 'unknown', reason: message };
+  }
+  return { code: 'unknown', reason: 'the member threw a value that is not an Error' };
+}

package/src/hive-result.ts

@@ -0,0 +1,96 @@
+// What a hive run answers, as a TYPE and as a SCHEMA built from the member's own `output`.
+//
+// It is a schema and not a plain interface because `hive()` returns an `action`, and an action's
+// `output:` is what drives `validateOutput`, the OpenAPI response body, the typed client, the MCP
+// tool and the manifest row. A hand-written interface would give the type and none of the six
+// projections — the whole reason a hive is a factory over `action()` rather than a helper.
+
+import type { Money } from '@ultimat3/money';
+import type { AnySchema, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { t } from '@ultimat3/schema';
+
+/**
+ * One member's outcome. THREE arms, not two: a member that ran and threw and a member that never
+ * ran at all are different facts, and the second one is what an aborted sibling is. Collapsing
+ * them would make "the hive stopped early" indistinguishable from "every remaining item is bad
+ * data", which is the difference between retrying the tail and fixing the source.
+ *
+ * `index` is the position in `split`'s output on every arm, so a caller can join a result back to
+ * the row it came from without depending on array position surviving a filter.
+ */
+export type HiveMember<O> =
+  | { readonly status: 'ok'; readonly index: number; readonly value: O }
+  | {
+      readonly status: 'failed';
+      readonly index: number;
+      /** The `UltimateError` code the member threw, or `'unknown'` for a foreign throw. */
+      readonly code: string;
+      readonly reason: string;
+    }
+  | { readonly status: 'skipped'; readonly index: number; readonly reason: string };
+
+export interface HiveResult<O> {
+  /** In SPLIT order, always — never completion order, and never with the failures filtered out. */
+  readonly members: readonly HiveMember<O>[];
+  readonly ok: number;
+  readonly failed: number;
+  /**
+   * Published beside `ok` and `failed` rather than left to be derived: three arms and two counters
+   * means `members.length - ok - failed`, and a caller who writes that once writes it wrong once.
+   */
+  readonly skipped: number;
+  /** Tokens the whole run debited, every member counted, from the hive's own derived ledger. */
+  readonly tokens: number;
+  readonly cost: Money;
+}
+
+/** The declared shape of `hive()`'s output, given the member action's own `output`. */
+export type HiveOutput<MOut extends AnySchema> = StandardSchemaV1<
+  unknown,
+  HiveResult<InferOutput<MOut>>
+>;
+
+/** What a member failure means for its siblings. No default: both answers are somebody's bug. */
+export type HiveMemberError =
+  /** Stop. Siblings that have not started are `skipped`; ones in flight see the aborted signal. */
+  | 'abort'
+  /** Record it as `failed` and keep going — a partial harvest is the point of a hive. */
+  | 'collect';
+
+export const SKIPPED_ABORTED = 'a sibling failed and onMemberError is abort';
+
+/**
+ * The OTHER way a member never runs, and a different fact: `split` produced nothing at this
+ * index. Its own string because `SKIPPED_ABORTED` named a cause that did not happen — a caller
+ * reading it retries the tail against a hive that stopped early, when the split is what to fix.
+ */
+export const SKIPPED_NO_INPUT = 'split produced no input at this index';
+
+/**
+ * The member's `output` embedded verbatim in the `ok` arm, so a hive over `summarisePost` publishes
+ * a summary in its OpenAPI response and its MCP `outputSchema` — not an opaque object.
+ *
+ * A DISCRIMINATED union, not a plain one: `status` routes the parse, so a malformed `ok` reports
+ * that arm's issues instead of all three arms' at once.
+ */
+export function hiveResultSchema(output: AnySchema): AnySchema {
+  const member = t.discriminatedUnion(
+    'status',
+    t.object({ status: t.literal('ok'), index: t.number.int(), value: output }),
+    t.object({
+      status: t.literal('failed'),
+      index: t.number.int(),
+      code: t.string,
+      reason: t.string,
+    }),
+    t.object({ status: t.literal('skipped'), index: t.number.int(), reason: t.string }),
+  );
+  return t.object({
+    members: t.array(member),
+    ok: t.number.int(),
+    failed: t.number.int(),
+    skipped: t.number.int(),
+    tokens: t.number.int(),
+    cost: t.money,
+  });
+}

package/src/hive.ts

@@ -0,0 +1,177 @@
+/**
+ * `hive()` — one action fanned out over many inputs, declared as an `action`.
+ *
+ * The fourth instance of the framework's factory rule, after `llm()`, `backfill()` and `agent()`:
+ * a fan-out is still one server-authoritative operation with an input schema, an output schema and
+ * a policy, so this returns an `action` and inherits `.tool()`, `.openapi()`, `.client()`,
+ * `.job()`, `.contract()` and its manifest row without a line here.
+ *
+ * It exists because the alternative is a hand-rolled `Promise.all` over `agent()` calls, and that
+ * loop gets four things wrong every time: it takes the actor from somewhere other than the request,
+ * it reports results in completion order, it cannot tell "ran and failed" from "never ran", and it
+ * has no ceiling — so the first bad split spends the whole budget in parallel.
+ */
+
+import type { Action, ActionMcp, ActionPolicy } from '@ultimat3/action';
+import { action, actionName } from '@ultimat3/action';
+import type { Ctx } from '@ultimat3/core';
+import { throwIfAborted, withSpan } from '@ultimat3/core';
+import type { AnySchema, InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import type { BudgetLimits } from './budget';
+import { BudgetLedger, currentBudget, withBudget } from './budget';
+import { HiveEmptyError } from './hive-errors';
+import { runPool } from './hive-pool';
+import type { HiveMember, HiveMemberError, HiveOutput, HiveResult } from './hive-result';
+import { hiveResultSchema } from './hive-result';
+import type { LlmBudget } from './llm';
+
+/**
+ * Members in flight at once when the declaration omits one. Small and deliberately arbitrary — it
+ * is a floor to start from, not a number measured off any run: the framework cannot know a
+ * provider's concurrency allowance, and a default read off one benchmark would be wrong for
+ * everybody else's account. Raise it in the declaration once the run demonstrably fits.
+ */
+const DEFAULT_CONCURRENCY = 4;
+
+/**
+ * Below this many members the split is not fanned out at all. A member carries a fixed cost — a
+ * child context, a derived ledger, a whole model call's handshake — and paying it in parallel for
+ * one or two items buys nothing but a second way for the run to fail.
+ */
+const DEFAULT_MIN_MEMBERS = 2;
+
+export interface HiveSplitArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  readonly ctx: Ctx;
+}
+
+export interface HiveDef<
+  TInput extends StandardSchemaV1,
+  MIn extends StandardSchemaV1,
+  MOut extends AnySchema,
+> {
+  readonly input: TInput;
+  /**
+   * The action every member runs — an `agent()`, an `llm()`, or any action at all. Its own
+   * `policy` decides every member call and its own `input:` parses every member payload, which is
+   * what keeps a hive from being a second authz system.
+   */
+  readonly member: Action<MIn, MOut>;
+  /**
+   * The one declared place a run decides what the members are. Derived from `input` and `ctx` and
+   * from NOTHING a model emitted — that boundary is the same one `agent()` holds, and the reason
+   * both belong in the framework rather than in a loop somebody writes per feature.
+   */
+  split(
+    args: HiveSplitArgs<TInput>,
+  ): readonly InferInput<MIn>[] | Promise<readonly InferInput<MIn>[]>;
+  /** Members in flight at once. */
+  readonly concurrency?: number;
+  /** Below this many members the split runs serially instead of fanning out. */
+  readonly minMembers?: number;
+  readonly onMemberError: HiveMemberError;
+  /** Ceilings for the WHOLE fan-out. `tokensPerRun` is the run's, every member counted. */
+  readonly budget?: LlmBudget & { readonly tokensPerRun?: number };
+  readonly policy: ActionPolicy;
+  readonly mcp?: ActionMcp;
+}
+
+export function hive<
+  TInput extends StandardSchemaV1,
+  MIn extends StandardSchemaV1,
+  MOut extends AnySchema,
+>(def: HiveDef<TInput, MIn, MOut>): Action<TInput, HiveOutput<MOut>> {
+  // The one cast in this file, and it narrows nothing at runtime: `hiveResultSchema` builds the
+  // shape `HiveResult<InferOutput<MOut>>` describes, and this restates that in the type system
+  // rather than making the caller infer it back out of a nested `t.discriminatedUnion`.
+  const output = hiveResultSchema(def.member.output) as HiveOutput<MOut>;
+  return action<TInput, HiveOutput<MOut>>({
+    input: def.input,
+    output,
+    policy: def.policy,
+    ...(def.mcp === undefined ? {} : { mcp: def.mcp }),
+    handle: (args) => run(def, args),
+  });
+}
+
+async function run<
+  TInput extends StandardSchemaV1,
+  MIn extends StandardSchemaV1,
+  MOut extends AnySchema,
+>(
+  def: HiveDef<TInput, MIn, MOut>,
+  args: { readonly input: InferOutput<TInput>; readonly ctx: Ctx },
+): Promise<HiveResult<InferOutput<MOut>>> {
+  const name = actionName(def.member);
+  const inputs = await def.split({ input: args.input, ctx: args.ctx });
+  if (inputs.length === 0) throw new HiveEmptyError({ member: name });
+
+  const floor = def.minMembers ?? DEFAULT_MIN_MEMBERS;
+  // A split below the floor still runs every input it produced — dropping one would be silent
+  // data loss — it just stops paying for a pool to do it.
+  const width =
+    inputs.length < floor
+      ? 1
+      : Math.max(1, Math.min(def.concurrency ?? DEFAULT_CONCURRENCY, inputs.length));
+
+  return withSpan('ai.hive', async (span) => {
+    span.setAttributes({
+      'hive.member': name,
+      'hive.members': inputs.length,
+      'hive.concurrency': width,
+      'hive.on_member_error': def.onMemberError,
+    });
+    const ledger = (currentBudget() ?? new BudgetLedger({ limits: {} })).derive(limitsOf(def));
+    const result = await withBudget(ledger, () =>
+      runPool<InferInput<MIn>, InferOutput<MOut>>({
+        inputs,
+        width,
+        ctx: args.ctx,
+        onMemberError: def.onMemberError,
+        member: (payload) => def.member(payload),
+      }),
+    );
+    // The caller went away DURING the fan-out. Distinct from `onMemberError: 'abort'`, which is a
+    // completed run that stopped early and has a partial harvest worth returning: here there is
+    // nobody left to hand it to, so unwind the way every other abort in this package does.
+    throwIfAborted(args.ctx);
+    const report = await ledger.report();
+    const counts = tally(result);
+    span.setAttributes({ ...counts, 'hive.tokens': report.requestTokens });
+    return {
+      members: result,
+      ok: counts['hive.ok'],
+      failed: counts['hive.failed'],
+      skipped: counts['hive.skipped'],
+      tokens: report.requestTokens,
+      cost: report.cost,
+    };
+  });
+}
+
+function tally<O>(members: readonly HiveMember<O>[]): {
+  'hive.ok': number;
+  'hive.failed': number;
+  'hive.skipped': number;
+} {
+  return {
+    'hive.ok': members.filter((one) => one.status === 'ok').length,
+    'hive.failed': members.filter((one) => one.status === 'failed').length,
+    'hive.skipped': members.filter((one) => one.status === 'skipped').length,
+  };
+}
+
+function limitsOf<
+  TInput extends StandardSchemaV1,
+  MIn extends StandardSchemaV1,
+  MOut extends AnySchema,
+>(def: HiveDef<TInput, MIn, MOut>): BudgetLimits {
+  const budget = def.budget;
+  return {
+    ...(budget?.tokensIn === undefined ? {} : { tokensIn: budget.tokensIn }),
+    ...(budget?.costPerCall === undefined ? {} : { costPerCall: budget.costPerCall }),
+    // The ledger's `request` scope accumulates across every call made under it, which for a hive
+    // under `withBudget` is every member's every turn.
+    ...(budget?.tokensPerRun === undefined ? {} : { request: budget.tokensPerRun }),
+  };
+}

package/src/index.ts

@@ -4,8 +4,12 @@
 /** 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, AgentVarsArgs } from './agent';
+export type { AgentBudget, AgentDef, AgentTurn, AgentVarsArgs } from './agent';
 export { agent } from './agent';
+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 {
   BudgetLedgerInput,
   BudgetLimits,
@@ -87,17 +91,16 @@ export {
   promptsWithoutEvals,
   resetEvals,
 } from './evals';
+export type { AiFetch } from './fetch-seam';
 export type { CreateGatewayInput, Gateway, GatewayCache, RetryPolicy } from './gateway';
 export { backoffMs, cacheKeyFor, createGateway, DEFAULT_RETRY, isRetryable } from './gateway';
-export type {
-  LlmAction,
-  LlmBudget,
-  LlmCache,
-  LlmDef,
-  LlmSemanticCache,
-  LlmVarsArgs,
-} from './llm';
+export type { HiveDef, HiveSplitArgs } from './hive';
+export { hive } from './hive';
+export { HiveEmptyError } from './hive-errors';
+export type { HiveMember, HiveMemberError, HiveOutput, HiveResult } from './hive-result';
+export type { LlmAction, LlmBudget, LlmDef, LlmVarsArgs } from './llm';
 export { llm } from './llm';
+export type { LlmCache, LlmScopeArgs, LlmSemanticCache } from './llm-cache';
 export type { LlmStreamChunk } from './llm-stream';
 export type { Effort, ModelId, ModelReasoning, ModelSpec, ThinkingMode } from './models';
 export {
@@ -188,6 +191,7 @@ export {
   aiGateway,
   aiRedactor,
   configureAi,
+  MAX_SEMANTIC_CACHE_SCOPES,
   resetAiRuntime,
   semanticCacheFor,
 } from './runtime';
@@ -201,13 +205,14 @@ export {
   numericTolerance,
 } from './scorers';
 export type {
+  AgentTool,
   JsonSchema,
   LlmTool,
   LlmToolCall,
   LlmToolResult,
   ProjectableAction,
 } from './tools';
-export { runLlmToolCall, toLlmTool, toLlmTools } from './tools';
+export { asProjectableAction, runLlmToolCall, toLlmTool, toLlmTools } from './tools';
 export type {
   HybridSearchInput,
   MemoryVectorStoreInput,

package/src/llm-cache.ts

@@ -0,0 +1,111 @@
+/**
+ * The semantic cache half of `llm()`: what a declaration may partition on, and the store one
+ * declaration reaches. Split from `llm.ts` so that file stays the model call itself.
+ *
+ * A scope is a separate cache INSTANCE, never a filter over a shared one, and the instance key
+ * carries the prompt VERSION as well — which is what makes "editing a prompt requires a version
+ * bump" invalidate the cache: a bumped version reaches a different store, so an old answer cannot
+ * survive a prompt edit no matter how similar the text.
+ */
+
+import type { Ctx } from '@ultimat3/core';
+import { parseDuration } from '@ultimat3/time';
+import { embedOne, fnv1a } from './embeddings';
+import { aiEmbedder, semanticCacheFor } from './runtime';
+
+/** What a `scope` may decide from. The same pair `vars()` receives, and for the same reason. */
+export interface LlmScopeArgs<TParsed> {
+  readonly input: TParsed;
+  readonly ctx: Ctx;
+}
+
+export interface LlmSemanticCache<TParsed> {
+  /** Cosine floor. Below ~0.9 unrelated prompts collide and the cache answers the wrong one. */
+  readonly threshold?: number;
+  /** Entry lifetime as a duration string — `'7d'`, `'12h'`. `@ultimat3/time` owns the grammar. */
+  readonly ttl?: string;
+  /**
+   * Partition key. Each scope is a separate cache instance, never a filter over a shared one:
+   * cosine similarity has no notion of a tenant, so a shared cache answers one tenant with
+   * another's data — by construction, since `lookup` is a nearest neighbour with no predicate.
+   *
+   * **Omitting it is safe.** The default is the narrowest key the ctx can supply — the actor,
+   * its kind and its org — which is `@ultimat3/query`'s `readAuthority` rule applied here: a
+   * declaration that says nothing gets the narrowest partition, which is always correct, and
+   * WIDENING is a written statement about what the answers are. It defaulted to `'global'`, so a
+   * `cache: { semantic: { ttl: '1h' } }` put every tenant in one store.
+   *
+   * **Breaking: it receives `{ input, ctx }`, not the bare `input`.** Taking `input` alone meant
+   * the partition could only be chosen from a value the caller sends, which is the one thing a
+   * partition may never be chosen by. `vars()` on the same declaration already takes the pair.
+   */
+  readonly scope?: (args: LlmScopeArgs<TParsed>) => string;
+}
+
+export interface LlmCache<TParsed> {
+  readonly semantic: LlmSemanticCache<TParsed>;
+  // `05-caching.md` also declares `invalidates: [tag.post]` here. It is deliberately absent
+  // until `@ultimat3/cache`'s fan-out can reach something that is not a `CacheTier`: storing
+  // tags that the ONE invalidation path never visits would read as wired and silently not be.
+  // Today the invalidation story is the prompt version (a bump reaches a different store) and
+  // `ttl`.
+}
+
+export interface PromptCache {
+  lookup(): Promise<unknown>;
+  remember(value: unknown): Promise<void>;
+}
+
+/**
+ * The partition a declaration that named none gets: the narrowest key this call can prove, which
+ * is the actor itself. Verbatim the shape `@ultimat3/query`'s `actorAuthority` builds, for the
+ * same reason it is JSON rather than a joined string — an actor id is app data and may carry any
+ * separator, and a value that can spell a boundary can spell somebody else's.
+ *
+ * `ctx.actor` is never absent (`createContext` defaults it to `anonymousActor()`), so every
+ * anonymous caller shares one partition — which is what the anonymous actor already means
+ * everywhere else in the framework.
+ */
+function actorScope(ctx: Ctx): string {
+  return JSON.stringify([ctx.actor.kind, ctx.actor.id, ctx.actor.orgId ?? null]);
+}
+
+/**
+ * The semantic cache for one declaration, or `undefined` when none was declared. The instance
+ * is partitioned by prompt VERSION as well as scope, which is what makes "editing a prompt
+ * requires a version bump" invalidate the cache: a bumped version reaches a different store,
+ * so an old answer cannot survive a prompt edit no matter how similar the text.
+ */
+export interface OpenCacheArgs<TParsed> {
+  readonly cache: LlmCache<TParsed> | undefined;
+  /** Identity and content hash of the prompt artifact — the version half of the partition. */
+  readonly prompt: { readonly ref: string; readonly hash: string };
+  readonly input: TParsed;
+  readonly ctx: Ctx;
+  /** The rendered, redacted prompt text: what is embedded and what the entry is keyed on. */
+  readonly rendered: string;
+}
+
+export async function openCache<TParsed>(
+  args: OpenCacheArgs<TParsed>,
+): Promise<PromptCache | undefined> {
+  const semantic = args.cache?.semantic;
+  if (semantic === undefined) return undefined;
+  const scope = semantic.scope?.({ input: args.input, ctx: args.ctx }) ?? actorScope(args.ctx);
+  const store = semanticCacheFor(`${args.prompt.ref}#${args.prompt.hash}::${scope}`);
+  const embedding = Array.from(await embedOne(aiEmbedder(), args.rendered));
+  const ttlMs = semantic.ttl === undefined ? undefined : parseDuration(semantic.ttl);
+  return {
+    async lookup(): Promise<unknown> {
+      return (await store.lookup(embedding, semantic.threshold))?.value;
+    },
+    remember(value: unknown): Promise<void> {
+      return store.remember(
+        `${args.prompt.hash}:${fnv1a(args.rendered).toString(16)}`,
+        embedding,
+        value,
+        ttlMs === undefined ? {} : { ttlMs },
+      );
+    },
+  };
+}

package/src/llm.ts

@@ -28,10 +28,8 @@ import { withSpan } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { InferInput, InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
 import { formatIssues, toMcpInputSchema, validateAsync } from '@ultimat3/schema';
-import { parseDuration } from '@ultimat3/time';
 import type { BudgetLimits } from './budget';
 import { BudgetLedger, currentBudget, withBudget } from './budget';
-import { embedOne, fnv1a } from './embeddings';
 import {
   LlmOutputInvalidError,
   LlmRefusedError,
@@ -39,6 +37,8 @@ import {
   LlmTruncatedError,
 } from './errors';
 import type { Gateway } from './gateway';
+import type { LlmCache } from './llm-cache';
+import { openCache } from './llm-cache';
 import type { LlmSink, LlmStreamChunk } from './llm-stream';
 import { currentLlmSink, llmStream, streamOneTurn, withLlmSink } from './llm-stream';
 import type { ModelId } from './models';
@@ -46,7 +46,7 @@ import { DEFAULT_MODEL, moreCapableThan } from './models';
 import type { Prompt, PromptVars } from './prompt';
 import type { AiMessage, GenerateRequest, GenerateResult } from './provider';
 import { assertNoSecrets } from './redaction';
-import { aiEmbedder, aiGateway, aiRedactor, semanticCacheFor } from './runtime';
+import { aiGateway, aiRedactor } from './runtime';
 import type { LlmTool } from './tools';
 
 /**
@@ -65,27 +65,6 @@ const ATTEMPTS = 2;
  */
 const DEFAULT_MAX_TOKENS = 4_096;
 
-export interface LlmSemanticCache<TParsed> {
-  /** Cosine floor. Below ~0.9 unrelated prompts collide and the cache answers the wrong one. */
-  readonly threshold?: number;
-  /** Entry lifetime as a duration string — `'7d'`, `'12h'`. `@ultimat3/time` owns the grammar. */
-  readonly ttl?: string;
-  /**
-   * Partition key, from the parsed input. Each scope is a separate cache: cosine similarity
-   * has no notion of a tenant, so a shared cache answers one tenant with another's data.
-   */
-  readonly scope?: (input: TParsed) => string;
-}
-
-export interface LlmCache<TParsed> {
-  readonly semantic: LlmSemanticCache<TParsed>;
-  // `05-caching.md` also declares `invalidates: [tag.post]` here. It is deliberately absent
-  // until `@ultimat3/cache`'s fan-out can reach something that is not a `CacheTier`: storing
-  // tags that the ONE invalidation path never visits would read as wired and silently not be.
-  // Today the invalidation story is the prompt version (a bump reaches a different store) and
-  // `ttl`.
-}
-
 /** Per-call ceilings, checked before the provider is reached. Never truncates — refuses. */
 export interface LlmBudget {
   /** Prompt tokens. */
@@ -235,7 +214,13 @@ async function generate<
     // A cached answer is still data of unknown provenance, so it goes through the schema like
     // any other. One that no longer fits — the schema moved under it — is a miss, not a
     // failure: the model can produce a fresh answer, and refusing would be worse than paying.
-    const cache = await openCache(def, args.input, rendered);
+    const cache = await openCache({
+      cache: def.cache,
+      prompt: { ref: prompt.ref, hash: prompt.hash },
+      input: args.input,
+      ctx: args.ctx,
+      rendered,
+    });
     const hit = await accept(def.output, await cache?.lookup());
     span.setAttribute('llm.cache.hit', hit !== undefined);
     if (hit !== undefined) return hit.value;
@@ -250,6 +235,10 @@ async function generate<
       maxTokens: def.maxTokens ?? DEFAULT_MAX_TOKENS,
       ...(prompt.effort === undefined ? {} : { effort: prompt.effort }),
       ...(prompt.thinking === undefined ? {} : { thinking: prompt.thinking }),
+      // The caller's own signal, forwarded to the transport exactly as `agent()` does — and
+      // inherited by `streamedAnswer` from this same `base`. Without it a disconnected caller left
+      // the provider call in flight, billed and unread, and the repair turn bought a SECOND one.
+      signal: args.ctx.signal,
     };
     const request: GenerateRequest = { ...base, tools: [respond] };
 
@@ -447,44 +436,3 @@ function parseJsonish(text: string): unknown {
     return undefined;
   }
 }
-
-interface PromptCache {
-  lookup(): Promise<unknown>;
-  remember(value: unknown): Promise<void>;
-}
-
-/**
- * The semantic cache for one declaration, or `undefined` when none was declared. The instance
- * is partitioned by prompt VERSION as well as scope, which is what makes "editing a prompt
- * requires a version bump" invalidate the cache: a bumped version reaches a different store,
- * so an old answer cannot survive a prompt edit no matter how similar the text.
- */
-async function openCache<
-  TInput extends StandardSchemaV1,
-  TOutput extends StandardSchemaV1,
-  V extends PromptVars,
->(
-  def: LlmDef<TInput, TOutput, V>,
-  input: InferOutput<TInput>,
-  rendered: string,
-): Promise<PromptCache | undefined> {
-  const semantic = def.cache?.semantic;
-  if (semantic === undefined) return undefined;
-  const scope = semantic.scope?.(input) ?? 'global';
-  const store = semanticCacheFor(`${def.prompt.ref}#${def.prompt.hash}::${scope}`);
-  const embedding = Array.from(await embedOne(aiEmbedder(), rendered));
-  const ttlMs = semantic.ttl === undefined ? undefined : parseDuration(semantic.ttl);
-  return {
-    async lookup(): Promise<unknown> {
-      return (await store.lookup(embedding, semantic.threshold))?.value;
-    },
-    remember(value: unknown): Promise<void> {
-      return store.remember(
-        `${def.prompt.hash}:${fnv1a(rendered).toString(16)}`,
-        embedding,
-        value,
-        ttlMs === undefined ? {} : { ttlMs },
-      );
-    },
-  };
-}