@zerotal/ai 1.5.0

package/src/agentLoop.ts

@@ -0,0 +1,151 @@
+import { FrameworkEvents } from "@zerotal/core";
+import { AiAgentLimitError, AiCancelledError } from "./errors.ts";
+import { AiToolCalled } from "./events.ts";
+import { runTool } from "./tool.ts";
+import type { AgentOptions, AiDriver } from "./drivers/AiDriver.ts";
+import { normalizeMessages } from "./drivers/AiDriver.ts";
+import type { AiAgentResult, AiAgentStep, AiMessage, AiRequest, AiUsage } from "./types.ts";
+
+/**
+ * The tool-calling loop, written once and shared by every driver.
+ *
+ * A driver may supply its own `agent()` when the provider runs tools server-side,
+ * but none of the built-in three do — they all run *this*, which is the point:
+ * an abstraction whose second implementation reuses none of the first is not an
+ * abstraction, it is two clients sharing a type. Everything a provider actually
+ * differs on lives in `text()`.
+ *
+ * Two ceilings bound the loop, because a model deciding when to stop is not a
+ * termination proof:
+ *
+ * - **`maxSteps`** caps tool-calling round trips.
+ * - **`maxResumes`** caps `pause_turn` restarts — see below, this one bites.
+ *
+ * @internal
+ */
+export async function runAgentLoop(
+  driver: AiDriver,
+  request: AiRequest,
+  options: AgentOptions,
+): Promise<AiAgentResult> {
+  const tools = request.tools ?? [];
+  const byName = new Map(tools.map((tool) => [tool.name, tool]));
+
+  const messages: AiMessage[] = [...normalizeMessages(request)];
+  const steps: AiAgentStep[] = [];
+  const usage: AiUsage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+  };
+
+  let step = 0;
+  let resumes = 0;
+  let model = driver.model;
+
+  // `prompt` was folded into `messages` above; leaving it set would make the
+  // first turn arrive twice on every iteration.
+  const { prompt: _prompt, ...base } = request;
+
+  for (;;) {
+    if (options.signal.aborted) throw new AiCancelledError();
+
+    const response = await driver.text({ ...base, messages, tools, signal: options.signal });
+
+    model = response.model;
+    accumulate(usage, response.usage);
+    messages.push(response.assistantTurn);
+
+    // A paused turn is *not* an error and *not* a completion — it is the
+    // provider saying "ask me again". Left unhandled it reads as a finished
+    // answer, so the user sees a silently truncated response with no warning
+    // anywhere. Push the turn back and re-request.
+    if (response.stopReason === "pause_turn") {
+      if (++resumes > options.maxResumes) {
+        throw new AiAgentLimitError(
+          `The provider paused the turn ${resumes} times, over the ceiling of ${options.maxResumes}. ` +
+            `Raise agent.maxResumes in config/ai.ts if the work genuinely needs it.`,
+          { resumes, maxResumes: options.maxResumes },
+        );
+      }
+      continue;
+    }
+
+    if (response.stopReason !== "tool_use" || response.toolCalls.length === 0) {
+      return { text: response.text, model, usage, steps, stopReason: response.stopReason };
+    }
+
+    if (step >= options.maxSteps) {
+      throw new AiAgentLimitError(
+        `The agent made ${step} tool-calling round trips without finishing, hitting the ceiling of ` +
+          `${options.maxSteps}. Raise agent.maxSteps in config/ai.ts, or narrow the task.`,
+        { steps: step, maxSteps: options.maxSteps },
+      );
+    }
+    step++;
+
+    // Every call in one assistant turn is answered in one user turn. Splitting
+    // them across turns is accepted by the API and quietly teaches the model to
+    // stop asking for parallel calls.
+    const results = await Promise.all(
+      response.toolCalls.map(async (call) => {
+        const startedAt = performance.now();
+        const tool = byName.get(call.name);
+
+        if (!tool) {
+          // Not a crash: naming the mistake back to the model is how it recovers.
+          const known = [...byName.keys()].join(", ") || "none";
+          return {
+            id: call.id,
+            content: `No tool named '${call.name}' is available. Available tools: ${known}.`,
+            isError: true,
+            step,
+            call,
+            durationMs: performance.now() - startedAt,
+          };
+        }
+
+        const outcome = await runTool(tool, call.input, { signal: options.signal, step });
+        const durationMs = performance.now() - startedAt;
+
+        FrameworkEvents.emit(
+          new AiToolCalled(
+            driver.name,
+            call.name,
+            step,
+            durationMs,
+            !outcome.isError,
+            outcome.isError ? outcome.content : undefined,
+          ),
+        );
+
+        return { id: call.id, ...outcome, step, call, durationMs };
+      }),
+    );
+
+    for (const result of results) {
+      steps.push({
+        step: result.step,
+        call: result.call,
+        result: result.content,
+        isError: result.isError,
+        durationMs: result.durationMs,
+      });
+    }
+
+    messages.push({
+      role: "user",
+      content: "",
+      toolResults: results.map((r) => ({ id: r.id, content: r.content, isError: r.isError })),
+    });
+  }
+}
+
+/** Sum a response's usage into the running total. */
+function accumulate(total: AiUsage, next: AiUsage): void {
+  total.inputTokens += next.inputTokens;
+  total.outputTokens += next.outputTokens;
+  total.cacheReadTokens += next.cacheReadTokens;
+  total.cacheWriteTokens += next.cacheWriteTokens;
+}

package/src/commands/AiSpendCommand.ts

@@ -0,0 +1,58 @@
+import type { Application } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { AiManager } from "../AiManager.ts";
+import { modelStats } from "../stats.ts";
+import { spentToday } from "../spend.ts";
+
+/**
+ * `zt ai:spend` — what this process has spent today, by model.
+ *
+ * Deliberately process-scoped, and says so: the ledger is in-memory, so N
+ * workers hold N of these. It answers "what is *this* process doing" during
+ * development and incident response; the provider's dashboard remains the
+ * authority on the bill.
+ *
+ * @internal
+ */
+export class AiSpendCommand extends Command {
+  static commandName = "ai:spend";
+  static description = "Show this process's AI token spend today, by model";
+  static needsApp = true;
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    if (!app) {
+      this.error("Application not available.");
+      return;
+    }
+
+    const ai = app.container.makeSync("ai") as AiManager;
+    const models = modelStats();
+    const spent = spentToday();
+
+    this.line(`Spend today (this process): $${spent.toFixed(4)}`);
+    if (ai.config.limits.perDayUsd > 0) {
+      const share = ((spent / ai.config.limits.perDayUsd) * 100).toFixed(1);
+      this.line(`Ceiling: $${ai.config.limits.perDayUsd.toFixed(2)} (${share}% used)`);
+    }
+
+    if (models.length === 0) {
+      this.line("");
+      this.line("No generations recorded in this process yet.");
+      return;
+    }
+
+    this.line("");
+    for (const model of models) {
+      const cost = model.costUsd > 0 ? `$${model.costUsd.toFixed(4)}` : "unpriced";
+      this.line(
+        `  ${model.model.padEnd(24)} ${String(model.calls).padStart(5)} calls  ` +
+          `${String(model.inputTokens).padStart(8)} in  ` +
+          `${String(model.outputTokens).padStart(8)} out  ${cost}`,
+      );
+    }
+
+    this.line("");
+    this.line("Estimated from public list prices — an account with negotiated rates pays less.");
+  }
+}

package/src/commands/AiTestCommand.ts

@@ -0,0 +1,61 @@
+import type { Application, ArgDef } from "@zerotal/core";
+import { Command } from "@zerotal/core";
+import type { AiManager } from "../AiManager.ts";
+
+/**
+ * `zt ai:test [driver]` — reach the provider once and print what came back.
+ *
+ * AI configuration fails in ways unit tests cannot reach: a key with no access
+ * to the model, a model id that 404s because someone appended a date suffix, a
+ * gateway that rewrites the base URL. This exercises the whole path and prints
+ * the resolved model — which is the value people most often assume rather than
+ * check.
+ *
+ * @internal
+ */
+export class AiTestCommand extends Command {
+  static commandName = "ai:test";
+  static description = "Verify AI credentials and print the resolved model";
+  static needsApp = true;
+
+  static args: ArgDef[] = [{ name: "driver", required: false }];
+
+  async run(): Promise<void> {
+    const app = this.app as Application | undefined;
+    if (!app) {
+      this.error("Application not available.");
+      return;
+    }
+
+    const ai = app.container.makeSync("ai") as AiManager;
+    const requested = this.args["driver"];
+    const names = requested ? [requested] : ai.drivers();
+
+    if (names.length === 0) {
+      this.error("No AI drivers are configured. Add one under drivers in config/ai.ts.");
+      return;
+    }
+
+    let failed = false;
+
+    for (const name of names) {
+      this.line(`${name}: contacting the provider…`);
+      const status = await ai.verify(name);
+
+      if (status.ok) {
+        this.info(`${name}: ok · model ${status.model} · ${status.detail}`);
+      } else {
+        failed = true;
+        this.error(`${name}: failed · model ${status.model} · ${status.detail}`);
+      }
+    }
+
+    if (!failed) {
+      this.line("");
+      this.line(`Default driver: ${ai.config.default}`);
+      if (ai.config.limits.perDayUsd > 0) {
+        this.line(`Daily spend ceiling: $${ai.config.limits.perDayUsd.toFixed(2)}`);
+      }
+    }
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,2 @@
+export { AiTestCommand } from "./AiTestCommand.ts";
+export { AiSpendCommand } from "./AiSpendCommand.ts";

package/src/config.ts

@@ -0,0 +1,293 @@
+import { deepMerge } from "@zerotal/core";
+import { AiConfigError } from "./errors.ts";
+import type {
+  AiConfigShape,
+  AnthropicConfigShape,
+  EmbeddingsConfigShape,
+  OllamaConfigShape,
+  OpenAiConfigShape,
+} from "./types.ts";
+import { modelRejectsSampling } from "./pricing.ts";
+
+/**
+ * Recursively-optional view of the config, so callers override only what they
+ * care about.
+ *
+ * `NonNullable` before the `extends object` test is load-bearing: every driver
+ * block is already optional, so `AnthropicConfigShape | undefined` does not
+ * extend `object` and the recursion would stop one level too early — leaving
+ * `{ drivers: { anthropic: { apiKey } } }`, the single most common thing anyone
+ * writes in `config/ai.ts`, a type error.
+ */
+type DeepPartial<T> = {
+  [K in keyof T]?: NonNullable<T[K]> extends object ? DeepPartial<NonNullable<T[K]>> : T[K];
+};
+
+/**
+ * What {@link AiConfig} accepts — every key optional, all the way down. The
+ * same type the factory's parameter is written as, exported under a name
+ * consumers can reach for.
+ *
+ * Exported because a real `config/ai.ts` often builds its driver map
+ * conditionally ("Anthropic when the key is set, Ollama otherwise"), and the
+ * intermediate variable needs a type that is not the fully-resolved shape.
+ *
+ * @example
+ * const drivers: NonNullable<AiConfigInput["drivers"]> = { ollama: { model } };
+ * if (key) drivers.anthropic = { apiKey: key };
+ * export default AiConfig({ default: key ? "anthropic" : "ollama", drivers });
+ */
+export type AiConfigInput = DeepPartial<AiConfigShape>;
+
+/**
+ * Everything that is not a driver block.
+ *
+ * No driver appears here on purpose: `deepMerge` would then materialise that
+ * driver for every app, and an app that only talks to Ollama would boot into
+ * "drivers.anthropic.apiKey is empty" for a provider it never asked for.
+ * Per-driver defaults are filled in by {@link applyDriverDefaults}, which runs
+ * only over the blocks the app actually declared.
+ */
+const defaults: AiConfigShape = {
+  default: "anthropic",
+  drivers: {},
+  embeddings: {
+    default: "openai",
+    drivers: {},
+  },
+  limits: {
+    perRequestUsd: 0,
+    perDayUsd: 0,
+  },
+  redact: true,
+  agent: {
+    lock: true,
+    // Not "how long the agent might run" — that is unanswerable. It is how long
+    // after a crash before another run may take over, and the loop refreshes it.
+    lockTtl: 120,
+    maxSteps: 25,
+    maxResumes: 5,
+  },
+};
+
+/**
+ * Create a typed AI configuration object with defaults.
+ *
+ * @example
+ * import { AiConfig } from '@zerotal/ai';
+ *
+ * export default AiConfig({
+ *   default: 'anthropic',
+ *   drivers: {
+ *     anthropic: { apiKey: Bun.env['ANTHROPIC_API_KEY'] ?? '' },
+ *     ollama:    { model: 'llama3.2', baseUrl: 'http://127.0.0.1:11434' },
+ *   },
+ *   embeddings: {
+ *     default: 'openai',
+ *     drivers: {
+ *       openai: { apiKey: Bun.env['OPENAI_API_KEY'] ?? '', model: 'text-embedding-3-small' },
+ *     },
+ *   },
+ *   limits: { perRequestUsd: 0.5, perDayUsd: 25 },
+ * });
+ */
+export function AiConfig(options: DeepPartial<AiConfigShape> = {}): AiConfigShape {
+  const config = deepMerge(defaults, options as Partial<AiConfigShape>);
+  applyDriverDefaults(config);
+  validateAiConfig(config);
+  return config;
+}
+
+/**
+ * Fill in the per-driver defaults for drivers the app actually declared.
+ *
+ * They cannot live in `defaults` above: `deepMerge` would then materialise an
+ * `openai` block for every app, and a config where every driver looks present
+ * cannot tell "configured" from "left at its defaults".
+ *
+ * @internal
+ */
+function applyDriverDefaults(config: AiConfigShape): void {
+  const { drivers, embeddings } = config;
+
+  if (drivers.anthropic) {
+    const given = drivers.anthropic as Partial<AnthropicConfigShape>;
+    drivers.anthropic = {
+      apiKey: given.apiKey ?? "",
+      // Exact model id, no date suffix. Never construct one.
+      model: given.model ?? "claude-opus-5",
+      // max_tokens caps thinking *plus* response text, and thinking is on by
+      // default on this model — a budget sized for the answer alone truncates.
+      maxTokens: given.maxTokens ?? 16000,
+      // Streaming has no HTTP-timeout ceiling to respect, so give it room.
+      streamMaxTokens: given.streamMaxTokens ?? 64000,
+      effort: given.effort ?? "high",
+      fallbacks: given.fallbacks ?? true,
+      cacheSystem: given.cacheSystem ?? true,
+      timeout: given.timeout ?? 600_000,
+      ...(given.baseUrl !== undefined ? { baseUrl: given.baseUrl } : {}),
+      ...(given.temperature !== undefined ? { temperature: given.temperature } : {}),
+    };
+  }
+
+  if (drivers.openai) {
+    const given = drivers.openai as Partial<OpenAiConfigShape>;
+    drivers.openai = {
+      apiKey: given.apiKey ?? "",
+      model: given.model ?? "gpt-4o-mini",
+      maxTokens: given.maxTokens ?? 16000,
+      baseUrl: given.baseUrl ?? "https://api.openai.com/v1",
+      timeout: given.timeout ?? 600_000,
+    };
+  }
+
+  if (drivers.ollama) {
+    const given = drivers.ollama as Partial<OllamaConfigShape>;
+    drivers.ollama = {
+      model: given.model ?? "llama3.2",
+      baseUrl: given.baseUrl ?? "http://127.0.0.1:11434",
+      timeout: given.timeout ?? 600_000,
+    };
+  }
+
+  if (embeddings.drivers.openai) {
+    const given = embeddings.drivers.openai as Partial<EmbeddingsConfigShape["drivers"]["openai"]>;
+    embeddings.drivers.openai = {
+      apiKey: given?.apiKey ?? "",
+      model: given?.model ?? "text-embedding-3-small",
+      baseUrl: given?.baseUrl ?? "https://api.openai.com/v1",
+      timeout: given?.timeout ?? 120_000,
+    };
+  }
+
+  if (embeddings.drivers.ollama) {
+    const given = embeddings.drivers.ollama as Partial<EmbeddingsConfigShape["drivers"]["ollama"]>;
+    embeddings.drivers.ollama = {
+      model: given?.model ?? "nomic-embed-text",
+      baseUrl: given?.baseUrl ?? "http://127.0.0.1:11434",
+      timeout: given?.timeout ?? 120_000,
+    };
+  }
+}
+
+/**
+ * The zero-config fallback: an Anthropic driver built from `ANTHROPIC_API_KEY`.
+ *
+ * Used when an app registers {@link AiProvider} without a `config/ai.ts`, which
+ * is the "installed it, exported the key, want to try it" path. With no key set
+ * it produces an empty driver list, so {@link validateAiConfig} raises the
+ * actionable error at boot rather than letting the first prompt fail.
+ *
+ * @example
+ * // bootstrap/providers.ts registers AiProvider; no config file needed:
+ * //   ANTHROPIC_API_KEY=sk-ant-… bun zt serve
+ */
+export function AiConfigFromEnv(): AiConfigShape {
+  const apiKey = Bun.env["ANTHROPIC_API_KEY"] ?? "";
+  return AiConfig(apiKey ? { drivers: { anthropic: { apiKey } } } : {});
+}
+
+/**
+ * Check the config for combinations that would only fail at generation time.
+ *
+ * A default driver with no block, or an API key left empty in production, is a
+ * deployment mistake — and the cheapest place to notice one is at boot, naming
+ * the key, rather than on the first user's first prompt.
+ *
+ * @throws {AiConfigError} on the first inconsistency found.
+ *
+ * @internal
+ */
+export function validateAiConfig(config: AiConfigShape): void {
+  const { drivers, embeddings, limits, agent } = config;
+
+  const configured = Object.keys(drivers).filter(
+    (name) => drivers[name as keyof typeof drivers] !== undefined,
+  );
+
+  if (configured.length === 0) {
+    throw new AiConfigError(
+      "No AI drivers are configured. Add at least one under drivers in config/ai.ts.",
+    );
+  }
+
+  if (!configured.includes(config.default)) {
+    throw new AiConfigError(
+      `default is '${config.default}' but that driver has no block. Configured: ${configured.join(", ")}.`,
+      { default: config.default, configured },
+    );
+  }
+
+  if (drivers.anthropic) {
+    const a = drivers.anthropic;
+    if (!a.apiKey) {
+      throw new AiConfigError(
+        "drivers.anthropic.apiKey is empty. Set ANTHROPIC_API_KEY, or remove the anthropic block.",
+      );
+    }
+    if (/-\d{8}$/.test(a.model)) {
+      throw new AiConfigError(
+        `drivers.anthropic.model '${a.model}' carries a date suffix. Use the exact alias — e.g. 'claude-opus-5'.`,
+        { model: a.model },
+      );
+    }
+    if (a.streamMaxTokens < a.maxTokens) {
+      throw new AiConfigError(
+        "drivers.anthropic.streamMaxTokens is below maxTokens. Streaming exists to lift the ceiling, not lower it.",
+        { maxTokens: a.maxTokens, streamMaxTokens: a.streamMaxTokens },
+      );
+    }
+    if (a.temperature !== undefined && modelRejectsSampling(a.model)) {
+      // A warning rather than a throw: the driver drops it and the request still
+      // succeeds. Throwing would break an app whose config merely carries a
+      // leftover from a model that accepted it.
+      console.warn(
+        `[Zerotal/ai] drivers.anthropic.temperature is set, but ${a.model} rejects temperature/top_p/top_k ` +
+          `with a 400. The driver drops it. Use effort ('low' … 'max') to trade thoroughness for cost instead.`,
+      );
+    }
+  }
+
+  if (drivers.openai && !drivers.openai.apiKey) {
+    throw new AiConfigError(
+      "drivers.openai.apiKey is empty. Set OPENAI_API_KEY, or remove the openai block.",
+    );
+  }
+
+  const embedDrivers = Object.keys(embeddings.drivers).filter(
+    (name) => embeddings.drivers[name as keyof typeof embeddings.drivers] !== undefined,
+  );
+  if (embedDrivers.length > 0 && !embedDrivers.includes(embeddings.default)) {
+    throw new AiConfigError(
+      `embeddings.default is '${embeddings.default}' but that driver has no block. Configured: ${embedDrivers.join(", ")}.`,
+      { default: embeddings.default, configured: embedDrivers },
+    );
+  }
+  if (embeddings.drivers.openai && !embeddings.drivers.openai.apiKey) {
+    throw new AiConfigError("embeddings.drivers.openai.apiKey is empty. Set OPENAI_API_KEY.");
+  }
+
+  if (limits.perRequestUsd < 0 || limits.perDayUsd < 0) {
+    throw new AiConfigError("limits must not be negative. Use 0 to disable a ceiling.");
+  }
+  if (limits.perDayUsd > 0 && limits.perRequestUsd > limits.perDayUsd) {
+    throw new AiConfigError(
+      "limits.perRequestUsd exceeds limits.perDayUsd — the per-request ceiling could never be reached.",
+      { ...limits },
+    );
+  }
+
+  if (agent.maxSteps < 1) {
+    throw new AiConfigError("agent.maxSteps must be at least 1.");
+  }
+  if (agent.lockTtl < 1) {
+    throw new AiConfigError("agent.lockTtl must be at least 1 second.");
+  }
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    ai: AiConfigShape;
+  }
+}

package/src/drivers/AiDriver.ts

@@ -0,0 +1,104 @@
+import type { SchemaInput } from "../schema.ts";
+import type {
+  AiAgentResult,
+  AiMessage,
+  AiObjectResponse,
+  AiRequest,
+  AiResponse,
+  AiStreamChunk,
+} from "../types.ts";
+
+/** What the agent loop needs from the caller, beyond the request itself. */
+export interface AgentOptions {
+  /** Hard ceiling on tool-calling round trips. */
+  maxSteps: number;
+  /** Hard ceiling on `pause_turn` resumes. */
+  maxResumes: number;
+  /**
+   * Aborted when the caller cancels *or* when the loop's lock is lost.
+   *
+   * Distinct from `request.signal`: a lost lock means another process may now be
+   * doing the same work, and continuing would double it.
+   */
+  signal: AbortSignal;
+}
+
+/**
+ * What every AI provider implements.
+ *
+ * Deliberately small. A driver translates this vocabulary to one provider's wire
+ * format and back; spend ceilings, redaction, telemetry, and the agent lock all
+ * live above it in the manager, so a second driver costs a translation layer and
+ * nothing else.
+ */
+export interface AiDriver {
+  /** The driver's registered name — `anthropic`, `openai`, `ollama`, or custom. */
+  readonly name: string;
+  /** The configured default model. A request may override it. */
+  readonly model: string;
+
+  /** One non-streaming generation. */
+  text(request: AiRequest): Promise<AiResponse>;
+
+  /** One streaming generation. The final chunk is always `{ type: "done" }`. */
+  stream(request: AiRequest): AsyncIterable<AiStreamChunk>;
+
+  /** One generation constrained to a schema, parsed and re-checked. */
+  object<T>(request: AiRequest, schema: SchemaInput): Promise<AiObjectResponse<T>>;
+
+  /**
+   * Run the tool-calling loop to completion.
+   *
+   * Optional, and normally left unimplemented: the shared loop in `agentLoop.ts`
+   * drives any driver through {@link text}, so all three built-in drivers run
+   * the *same* loop — which is the only way "the abstraction is real" is a claim
+   * rather than a hope. Implement this only for a provider that executes tools
+   * server-side and so cannot be driven turn by turn.
+   */
+  agent?(request: AiRequest, options: AgentOptions): Promise<AiAgentResult>;
+
+  /**
+   * Count the tokens this request would consume, using the provider's own
+   * tokenizer. Never an estimate from another vendor's tokenizer — the spend
+   * panel is built on this number.
+   */
+  countTokens(request: AiRequest): Promise<number>;
+
+  /** Reach the provider once and report what came back. Backs `zt ai:test`. */
+  verify(): Promise<DriverStatus>;
+}
+
+/** What `zt ai:test` prints for one driver. */
+export interface DriverStatus {
+  ok: boolean;
+  /** The model the driver resolved — the thing people most often get wrong. */
+  model: string;
+  /** One line: the provider's reply, or its complaint. */
+  detail: string;
+}
+
+/**
+ * Turn `prompt` / `messages` into the single list drivers work from.
+ *
+ * @internal
+ */
+export function normalizeMessages(request: AiRequest): AiMessage[] {
+  if (request.messages?.length) return request.messages;
+  if (request.prompt !== undefined) return [{ role: "user", content: request.prompt }];
+  return [];
+}
+
+/**
+ * A short, redaction-safe label for telemetry: the last user turn, truncated by
+ * the caller's redaction setting.
+ *
+ * @internal
+ */
+export function promptText(request: AiRequest): string {
+  const messages = normalizeMessages(request);
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i]!;
+    if (message.role === "user" && message.content) return message.content;
+  }
+  return request.system ?? "";
+}