@ultimat3/ai 1.2.0 → 3.0.0

package/src/gateway.ts

@@ -4,6 +4,7 @@
 // budgeted, and cost-accounted in integer minor units. Everything an app does with a model
 // goes through here, so budgets and accounting cannot be bypassed by a stray fetch.
 
+import { renderThrowable } from '@ultimat3/core';
 import type { Money } from '@ultimat3/money';
 import type { BudgetLimits, BudgetStore } from './budget';
 import { BudgetLedger, currentBudget, estimateSpend, withBudget } from './budget';
@@ -98,10 +99,20 @@ class GatewayImpl implements Gateway {
     // cheap-in-tokens call on an expensive model is still a cost cap the app declared.
     // `record` below replaces the estimate with the provider's real counts.
     const ledger = currentBudget();
-    await ledger?.reserve(estimateSpend(resolved));
-
-    const result = await this.attempt(model, (provider) => provider.generate(resolved));
-    await ledger?.record(result.usage, result.cost);
+    // 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));
+
+    let result: GenerateResult;
+    try {
+      result = await this.attempt(model, (provider) => provider.generate(resolved));
+    } catch (error) {
+      // A call that never landed must not go on holding its reservation.
+      await ledger?.release(reservation);
+      throw error;
+    }
+    await ledger?.record(result.usage, result.cost, reservation);
     // A refusal is not an answer, so it is not cached. Storing one would keep serving a decision
     // the classifier might not make twice, long after the prompt that provoked it was fixed.
     if (result.stopReason !== 'refusal') {
@@ -114,14 +125,26 @@ class GatewayImpl implements Gateway {
     const model = request.model ?? this.config.defaultModel ?? DEFAULT_MODEL;
     const resolved: GenerateRequest = { ...request, model };
     const ledger = currentBudget();
-    await ledger?.reserve(estimateSpend(resolved));
+    const reservation = await ledger?.reserve(estimateSpend(resolved));
 
     // A stream is not retried mid-flight: the consumer has already seen tokens, and
     // replaying from the top would duplicate them. Only the handshake retries.
     const provider = this.providerFor(model);
-    for await (const chunk of provider.stream(resolved)) {
-      if (chunk.type === 'done') await ledger?.record(chunk.result.usage, chunk.result.cost);
-      yield chunk;
+    let settled = false;
+    try {
+      for await (const chunk of provider.stream(resolved)) {
+        if (chunk.type !== 'done') {
+          yield chunk;
+          continue;
+        }
+        settled = true;
+        await ledger?.record(chunk.result.usage, chunk.result.cost, reservation);
+        yield { type: 'done', result: { ...chunk.result, provider: provider.name } };
+      }
+    } finally {
+      // A stream that threw, or that its consumer abandoned, never reached `done` — so nothing
+      // reconciled the reservation and it would hold the ceiling for the rest of the window.
+      if (!settled) await ledger?.release(reservation);
     }
   }
 
@@ -140,8 +163,16 @@ class GatewayImpl implements Gateway {
    * Try every provider that serves `model`, retrying each on a retryable failure with
    * exponential backoff plus full jitter (jitter matters: synchronised retries from N
    * workers reproduce the rate limit they are backing off from).
+   *
+   * Fallback here is across PROVIDERS serving one model, never across models — a silent model
+   * swap changes what answered, what it cost and which eval baseline the answer belongs to. The
+   * provider that did answer is stamped onto the result, so the fallback that DOES exist reaches
+   * the span instead of being invisible.
    */
-  private async attempt<T>(model: ModelId, call: (provider: Provider) => Promise<T>): Promise<T> {
+  private async attempt(
+    model: ModelId,
+    call: (provider: Provider) => Promise<GenerateResult>,
+  ): Promise<GenerateResult> {
     const candidates = this.config.providers.filter((p) => p.models.includes(model));
     const failures: string[] = [];
     if (candidates.length === 0) {
@@ -151,9 +182,13 @@ class GatewayImpl implements Gateway {
     for (const provider of candidates) {
       for (let attempt = 1; attempt <= this.retry.attempts; attempt += 1) {
         try {
-          return await call(provider);
+          return { ...(await call(provider)), provider: provider.name };
         } catch (error) {
-          failures.push(`${provider.name}#${attempt}: ${messageOf(error)}`);
+          // `renderThrowable`, never `error.message` or `String(error)`: this line becomes the
+          // `cause` of `X_AI_PROVIDER_UNAVAILABLE`, and a renderer that throws replaces the coded
+          // refusal with a `TypeError` nothing downstream can catch by code. It bounds the text
+          // too — a provider's 1MB body is not a cause.
+          failures.push(`${provider.name}#${attempt}: ${renderThrowable(error)}`);
           if (!isRetryable(error) || attempt === this.retry.attempts) break;
           await this.sleep(backoffMs(this.retry, attempt));
         }
@@ -175,14 +210,17 @@ export function backoffMs(policy: RetryPolicy, attempt: number): number {
  */
 export function isRetryable(error: unknown): boolean {
   if (typeof error !== 'object' || error === null) return false;
-  const e = error as { status?: unknown; code?: unknown };
-  if (typeof e.status === 'number') return e.status === 429 || e.status >= 500;
-  return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
-}
-
-function messageOf(error: unknown): string {
-  if (error instanceof Error) return error.message;
-  return String(error);
+  // A `Provider` is the APP's object, so the value it rejected with is one the framework did not
+  // build: `e.status` is a getter call and, on a `Proxy`, a trap. A value that fights being read
+  // cannot be SHOWN to be retryable, and this runs inside the catch block that has nothing left
+  // to answer with — so it fails closed rather than raising.
+  try {
+    const e = error as { status?: unknown; code?: unknown };
+    if (typeof e.status === 'number') return e.status === 429 || e.status >= 500;
+    return e.code === 'ETIMEDOUT' || e.code === 'ECONNRESET';
+  } catch {
+    return false;
+  }
 }
 
 /**

package/src/hive-errors.ts

@@ -0,0 +1,30 @@
+// The X_HIVE_* codes, apart from ./errors only because one file has one job and that catalogue is
+// already at its ceiling — the same split `eval-errors.ts` made. The codes, their titles and the
+// single `registerErrorCodes` call stay in ./errors: one owner, one registration, one place a
+// duplicate can surface.
+
+import { UltimateError } from '@ultimat3/core';
+import type { AiErrorCode } from './errors';
+
+const docsFor = (code: AiErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/**
+ * `split` handed back an empty list, so the hive fanned out to nobody and would have reported a
+ * successful run of zero members.
+ *
+ * Refused rather than returned, because the two readings of "0 ok, 0 failed" are "there was
+ * genuinely nothing to do" and "the query behind `split` returned no rows and nobody noticed",
+ * and only the caller can tell them apart. A hive whose empty case is legitimate says so by not
+ * being called: guard the `split` source at the call site, where the emptiness is visible.
+ */
+export class HiveEmptyError extends UltimateError {
+  constructor(input: { member: string }) {
+    super({
+      code: 'X_HIVE_EMPTY',
+      cause: `the hive over "${input.member}" split into 0 members, so no member ran`,
+      fix: `return at least one member input from the hive's split() over "${input.member}", or skip the hive call when the source is empty — a hive reporting 0 ok and 0 failed cannot be told apart from one whose query returned no rows`,
+      docs: docsFor('X_HIVE_EMPTY'),
+      meta: { member: input.member },
+    });
+  }
+}

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,6 +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, 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,
@@ -30,24 +36,24 @@ export {
 } from './embeddings';
 export type { AiErrorCode } from './errors';
 export {
+  AgentMaxTurnsError,
+  AgentToolUnexposedError,
   AI_ERROR_CODES,
   AI_ERROR_TITLES,
   AiBudgetExceededError,
   AiGatewayMissingError,
   AiKeyMissingError,
+  AiModelUnknownError,
   AiPromptRenderError,
+  AiPromptSecretError,
   AiPromptVersionError,
   AiProviderUnavailableError,
   AiRequestInvalidError,
   AiTransportError,
   EmbedderDimMismatchError,
-  EvalBaselineInvalidError,
-  EvalBaselineMissingError,
-  EvalMissingError,
-  EvalRecordingError,
-  EvalThresholdError,
   LlmOutputInvalidError,
   LlmRefusedError,
+  LlmStreamInvalidError,
   LlmTruncatedError,
   VectorDimMismatchError,
   VectorScopeWidenedError,
@@ -63,6 +69,13 @@ export {
   regressionsAgainst,
   writeBaseline,
 } from './eval-baseline';
+export {
+  EvalBaselineInvalidError,
+  EvalBaselineMissingError,
+  EvalMissingError,
+  EvalRecordingError,
+  EvalThresholdError,
+} from './eval-errors';
 export type {
   CaseResult,
   DefineEvalInput,
@@ -80,7 +93,12 @@ export {
 } from './evals';
 export type { CreateGatewayInput, Gateway, GatewayCache, RetryPolicy } from './gateway';
 export { backoffMs, cacheKeyFor, createGateway, DEFAULT_RETRY, isRetryable } from './gateway';
+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,
   LlmCache,
   LlmDef,
@@ -88,8 +106,25 @@ export type {
   LlmVarsArgs,
 } from './llm';
 export { llm } from './llm';
+export type { LlmStreamChunk } from './llm-stream';
 export type { Effort, ModelId, ModelReasoning, ModelSpec, ThinkingMode } from './models';
-export { DEFAULT_MODEL, EFFORTS, MODEL_IDS, MODELS, reasoningBody } from './models';
+export {
+  ANTHROPIC_MODEL_IDS,
+  assertModel,
+  DEFAULT_MODEL,
+  EFFORTS,
+  isModelRegistered,
+  modelIds,
+  modelSpec,
+  moreCapableThan,
+  reasoningBody,
+  registeredModels,
+  registerModel,
+  resetModels,
+} from './models';
+export { OPENAI_MODEL_IDS, registerOpenAiModels } from './openai-models';
+export type { OpenAiProviderInput } from './openai-provider';
+export { openAiProvider } from './openai-provider';
 export type { PgVectorStoreInput } from './pg-vector';
 export { PgVectorStore } from './pg-vector';
 export type {
@@ -118,6 +153,7 @@ export {
   resetPrompts,
 } from './prompt';
 export type {
+  AiContentBlock,
   AiMessage,
   AnthropicProviderInput,
   EchoProviderInput,
@@ -137,6 +173,7 @@ export {
   estimateInputTokens,
   estimateTextTokens,
   estimateTokens,
+  messageText,
   parseMessage,
   requiresStreaming,
   STREAM_ONLY_MAX_TOKENS,
@@ -150,10 +187,18 @@ export type {
   RetrieveInput,
 } from './rag';
 export { assembleContext, chunk, indexDocument, passthroughReranker, retrieve } from './rag';
+export { assertNoSecrets } from './redaction';
 export type { RemoteEmbedderInput } from './remote-embedder';
 export { RemoteEmbedder } from './remote-embedder';
-export type { AiRuntimeInput } from './runtime';
-export { aiEmbedder, aiGateway, configureAi, resetAiRuntime, semanticCacheFor } from './runtime';
+export type { AiRuntimeInput, Redactor } from './runtime';
+export {
+  aiEmbedder,
+  aiGateway,
+  aiRedactor,
+  configureAi,
+  resetAiRuntime,
+  semanticCacheFor,
+} from './runtime';
 export type { Scorer } from './scorers';
 export {
   contains,
@@ -164,13 +209,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,