@zerotal/ai 1.5.0

package/src/monitor.ts

@@ -0,0 +1,179 @@
+/**
+ * The AI section contributed to `@zerotal/monitor`.
+ *
+ * The panel is *described*, not rendered — the monitor owns the shell and this
+ * package owns the knowledge of what is worth watching about a model call. The
+ * host interface is declared locally so this package has no dependency on the
+ * monitor at all: an app without it simply never resolves the binding.
+ */
+import type { Application } from "@zerotal/core";
+import { modelStats, recentGenerations, refusalRate } from "./stats.ts";
+import { spentToday } from "./spend.ts";
+import type { AiConfigShape } from "./types.ts";
+
+/** The monitor's write surface, redeclared to avoid a dependency. */
+interface MonitorHost {
+  enabled(id: string): boolean;
+  section(section: {
+    id: string;
+    label: string;
+    group?: string;
+    icon?: string;
+    sort?: number;
+    resolve(range: string): unknown;
+  }): void;
+}
+
+/** A chat bubble with a spark inside — generation, not messaging. */
+const ICON =
+  `<svg class="w-5 h-5 shrink-0" viewBox="0 0 20 20" fill="none" stroke="currentColor" ` +
+  `stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">` +
+  `<path d="M17 11.5a4 4 0 0 1-4 4H8l-4 3v-3H4a4 4 0 0 1-4-4v-5a4 4 0 0 1 4-4h9a4 4 0 0 1 4 4z" ` +
+  `transform="translate(1.5 0.5)"/>` +
+  `<path d="M10 5.5l1 2.5 2.5 1-2.5 1-1 2.5-1-2.5L6.5 9 9 8z"/></svg>`;
+
+/**
+ * Register the AI section, if the monitor is installed and the app left it on.
+ *
+ * @internal
+ */
+export function installAiMonitor(app: Application, config: AiConfigShape): void {
+  const monitor = app.container.tryMake("monitor.panel" as never) as MonitorHost | undefined;
+  if (!monitor?.enabled("ai")) return;
+
+  monitor.section({
+    id: "ai",
+    label: "AI",
+    group: "Integrations",
+    icon: ICON,
+    resolve: () => resolveSection(config),
+  });
+}
+
+/** The section's content. Reads only what the package already recorded. */
+function resolveSection(config: AiConfigShape): unknown {
+  const models = modelStats();
+  const recent = recentGenerations(30);
+
+  const calls = models.reduce((total, m) => total + m.calls, 0);
+  const outputTokens = models.reduce((total, m) => total + m.outputTokens, 0);
+  const inputTokens = models.reduce((total, m) => total + m.inputTokens, 0);
+  const cacheReadTokens = models.reduce((total, m) => total + m.cacheReadTokens, 0);
+  const refusals = refusalRate();
+  const spent = spentToday();
+
+  const stats = [
+    { label: "Generations", value: calls, detail: `${models.length} model(s) in the buffer` },
+    {
+      label: "Spend today",
+      value: `$${spent.toFixed(4)}`,
+      detail:
+        config.limits.perDayUsd > 0
+          ? `of $${config.limits.perDayUsd.toFixed(2)} ceiling`
+          : "estimated at list prices · no ceiling set",
+      ...(config.limits.perDayUsd > 0
+        ? { percent: Math.min(100, (spent / config.limits.perDayUsd) * 100) }
+        : {}),
+      tone: ceilingTone(spent, config.limits.perDayUsd),
+    },
+    {
+      label: "Tokens",
+      value: `${format(inputTokens)} in / ${format(outputTokens)} out`,
+      detail:
+        cacheReadTokens > 0
+          ? `${format(cacheReadTokens)} served from cache`
+          : "no cache reads recorded",
+    },
+    {
+      label: "Refusal rate",
+      value: `${(refusals * 100).toFixed(1)}%`,
+      detail: "provider declined the request",
+      tone: refusals > 0.05 ? "warn" : "default",
+    },
+  ];
+
+  return {
+    stats,
+    tables: [
+      {
+        title: "By model",
+        columns: [
+          { key: "model", label: "Model", mono: true },
+          { key: "calls", label: "Calls", align: "end" },
+          {
+            key: "inputTokens",
+            label: "In",
+            align: "end",
+            format: (v: unknown) => format(Number(v)),
+          },
+          {
+            key: "outputTokens",
+            label: "Out",
+            align: "end",
+            format: (v: unknown) => format(Number(v)),
+          },
+          {
+            key: "costUsd",
+            label: "Cost",
+            align: "end",
+            format: (v: unknown) => (Number(v) > 0 ? `$${Number(v).toFixed(4)}` : "—"),
+          },
+          { key: "p50", label: "p50", align: "end", format: (v: unknown) => `${String(v)} ms` },
+          { key: "p95", label: "p95", align: "end", format: (v: unknown) => `${String(v)} ms` },
+          {
+            key: "failures",
+            label: "Failed",
+            align: "end",
+            tone: (v: unknown) => (Number(v) > 0 ? "bad" : null),
+          },
+          {
+            key: "refusals",
+            label: "Refused",
+            align: "end",
+            tone: (v: unknown) => (Number(v) > 0 ? "warn" : null),
+          },
+        ],
+        rows: models,
+        empty: "No generations recorded yet.",
+      },
+      {
+        title: "Recent generations",
+        columns: [
+          { key: "operation", label: "Op" },
+          { key: "model", label: "Model", mono: true },
+          { key: "preview", label: "Prompt" },
+          {
+            key: "durationMs",
+            label: "Time",
+            align: "end",
+            format: (v: unknown) => `${Math.round(Number(v))} ms`,
+          },
+          {
+            key: "ok",
+            label: "Result",
+            format: (_v: unknown, row: Record<string, unknown>) =>
+              row["refused"] ? "refused" : row["ok"] ? "ok" : "failed",
+            tone: (_v: unknown, row: Record<string, unknown>) =>
+              row["refused"] ? "warn" : row["ok"] ? "good" : "bad",
+          },
+        ],
+        rows: recent,
+        empty: "No generations recorded yet.",
+      },
+    ],
+  };
+}
+
+function ceilingTone(spent: number, ceiling: number): "default" | "warn" | "bad" {
+  if (ceiling <= 0) return "default";
+  const share = spent / ceiling;
+  if (share >= 1) return "bad";
+  return share >= 0.8 ? "warn" : "default";
+}
+
+/** Thousands separators, but short: 12.3k rather than 12,345. */
+function format(tokens: number): string {
+  if (tokens < 1000) return String(tokens);
+  if (tokens < 1_000_000) return `${(tokens / 1000).toFixed(1)}k`;
+  return `${(tokens / 1_000_000).toFixed(2)}M`;
+}

package/src/observability.ts

@@ -0,0 +1,130 @@
+/**
+ * AI → observer bridges. This package emits `AiGenerated` / `AiRefused` /
+ * `AiToolCalled` on core's `FrameworkEvents` bus; this module forwards them to
+ * whichever observer packages happen to be installed.
+ *
+ * Each observer's write surface is resolved from the container by binding key
+ * and typed through a local structural interface, so this package depends on
+ * none of them — installing or removing an observer requires no change here.
+ */
+import { FrameworkEvents } from "@zerotal/core";
+import type { Application } from "@zerotal/core";
+import { AiGenerated, AiRefused, AiToolCalled } from "./events.ts";
+import { recordDelivery } from "./stats.ts";
+
+/** The subset of the monitor store this bridge calls (bound as `monitor.store`). */
+interface MonitorSink {
+  recordEvent(e: {
+    kind: string;
+    label: string;
+    status?: "ok" | "warn" | "bad" | "info";
+    route?: string | null;
+    data?: Record<string, unknown>;
+  }): void;
+}
+
+/** The subset of the logger this bridge calls (bound as `log`). */
+interface LogSink {
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>, error?: unknown): void;
+}
+
+/**
+ * Subscribe the AI events to every installed observer, plus this package's own
+ * counters. Returns a disposer; call it from the provider's `onStopping()`.
+ */
+export function installAiObservability(app: Application): () => void {
+  const unsubs: Array<() => void> = [];
+  const refused = new Set<string>();
+
+  // A refusal is reported as a *failed* generation as well, so the two events
+  // arrive for the same call. Remembering the preview lets the delivery row be
+  // labelled a refusal rather than a generic failure.
+  unsubs.push(
+    FrameworkEvents.on(AiRefused, (e) => {
+      refused.add(e.preview);
+    }),
+  );
+
+  unsubs.push(
+    FrameworkEvents.on(AiGenerated, (e) => {
+      const wasRefusal = !e.ok && refused.delete(e.preview);
+      recordDelivery({
+        at: Date.now(),
+        driver: e.driver,
+        model: e.model,
+        operation: e.operation,
+        inputTokens: e.inputTokens,
+        outputTokens: e.outputTokens,
+        cacheReadTokens: e.cacheReadTokens,
+        durationMs: e.durationMs,
+        costUsd: e.costUsd,
+        ok: e.ok,
+        refused: wasRefusal,
+        preview: e.preview,
+        ...(e.error ? { error: e.error } : {}),
+      });
+    }),
+  );
+
+  const store = app.container.tryMake("monitor.store" as never) as MonitorSink | undefined;
+  if (store) {
+    unsubs.push(
+      FrameworkEvents.on(AiGenerated, (e) =>
+        store.recordEvent({
+          kind: "ai",
+          label: `${e.operation} · ${e.model}`,
+          status: e.ok ? "ok" : "bad",
+          route: e.driver,
+          data: {
+            driver: e.driver,
+            model: e.model,
+            operation: e.operation,
+            inputTokens: e.inputTokens,
+            outputTokens: e.outputTokens,
+            costUsd: Number(e.costUsd.toFixed(6)),
+            ms: Math.round(e.durationMs),
+            detail: e.error ?? e.preview,
+          },
+        }),
+      ),
+      FrameworkEvents.on(AiToolCalled, (e) =>
+        store.recordEvent({
+          kind: "ai.tool",
+          label: e.tool,
+          status: e.ok ? "ok" : "bad",
+          route: e.driver,
+          data: { step: e.step, ms: Math.round(e.durationMs), detail: e.error ?? "" },
+        }),
+      ),
+    );
+  }
+
+  const log = app.container.tryMake("log" as never) as LogSink | undefined;
+  if (log) {
+    unsubs.push(
+      // A refusal is not a bug, so it is a warning rather than an error — but it
+      // is also invisible otherwise, since the HTTP call succeeded.
+      FrameworkEvents.on(AiRefused, (e) =>
+        log.warn("AI request refused by the provider", {
+          driver: e.driver,
+          model: e.model,
+          category: e.category,
+          prompt: e.preview,
+        }),
+      ),
+      FrameworkEvents.on(AiGenerated, (e) => {
+        if (e.ok) return;
+        log.error(
+          "AI generation failed",
+          { driver: e.driver, model: e.model, operation: e.operation, prompt: e.preview },
+          new Error(e.error ?? "unknown error"),
+        );
+      }),
+    );
+  }
+
+  return () => {
+    for (const unsub of unsubs) unsub();
+  };
+}

package/src/pricing.ts

@@ -0,0 +1,90 @@
+/**
+ * Token prices, and what to do about models we have no price for.
+ *
+ * The spend panel and the ceilings both need a number per request, and the only
+ * honest source is a table someone maintains. So: models we know are priced,
+ * models we don't return 0 — and 0 is documented as *unpriced*, never as free.
+ * A ceiling therefore never blocks a request it cannot price, which is the safe
+ * direction to fail for a limit whose job is to catch runaway spend, not to be
+ * the billing system.
+ */
+import type { AiUsage } from "./types.ts";
+
+/** USD per million tokens. */
+export interface ModelPrice {
+  input: number;
+  output: number;
+}
+
+/**
+ * Published list prices, USD per million tokens. Keys are exact model ids.
+ *
+ * Extend it with {@link registerModelPrice} rather than editing this — a fork
+ * of the table drifts the moment a price changes.
+ */
+const PRICES: Record<string, ModelPrice> = {
+  // Anthropic
+  "claude-fable-5": { input: 10, output: 50 },
+  "claude-mythos-5": { input: 10, output: 50 },
+  "claude-opus-5": { input: 5, output: 25 },
+  "claude-opus-4-8": { input: 5, output: 25 },
+  "claude-opus-4-7": { input: 5, output: 25 },
+  "claude-opus-4-6": { input: 5, output: 25 },
+  "claude-sonnet-5": { input: 3, output: 15 },
+  "claude-sonnet-4-6": { input: 3, output: 15 },
+  "claude-haiku-4-5": { input: 1, output: 5 },
+};
+
+/** Cache reads bill at roughly a tenth of input; writes at a 25% premium. */
+const CACHE_READ_MULTIPLIER = 0.1;
+const CACHE_WRITE_MULTIPLIER = 1.25;
+
+/**
+ * Teach the cost estimator about a model it does not know.
+ *
+ * @example
+ * registerModelPrice("gpt-4o-mini", { input: 0.15, output: 0.6 });
+ */
+export function registerModelPrice(model: string, price: ModelPrice): void {
+  PRICES[model] = price;
+}
+
+/** The price for a model, or `undefined` when we have none. */
+export function modelPrice(model: string): ModelPrice | undefined {
+  return PRICES[model];
+}
+
+/**
+ * Estimated USD for one request's usage. Returns 0 for an unpriced model.
+ *
+ * "Estimated" is load-bearing: these are public list prices, and an account
+ * with negotiated rates pays something else.
+ */
+export function estimateCost(model: string, usage: AiUsage): number {
+  const price = PRICES[model];
+  if (!price) return 0;
+
+  const perInputToken = price.input / 1_000_000;
+  const perOutputToken = price.output / 1_000_000;
+
+  return (
+    usage.inputTokens * perInputToken +
+    usage.outputTokens * perOutputToken +
+    usage.cacheReadTokens * perInputToken * CACHE_READ_MULTIPLIER +
+    usage.cacheWriteTokens * perInputToken * CACHE_WRITE_MULTIPLIER
+  );
+}
+
+/**
+ * Whether a Claude model rejects `temperature` / `top_p` / `top_k` with a 400.
+ *
+ * Unknown models answer `true`. The removal has only ever gone one way, and the
+ * two failure modes are not symmetric: guessing "rejects" costs a dropped
+ * parameter the API would have ignored anyway, while guessing "accepts" fails
+ * every single request against a model released after this line was written.
+ */
+export function modelRejectsSampling(model: string): boolean {
+  // Opus 4.6 and Sonnet 4.6 were the last Claude models to accept sampling
+  // parameters; everything before them predates the models this package targets.
+  return !/^claude-(opus|sonnet)-4-6\b/.test(model) && model.startsWith("claude-");
+}

package/src/provider/AiProvider.ts

@@ -0,0 +1,65 @@
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import type { ConfigManager } from "@zerotal/core/config";
+import { AiManager } from "../AiManager.ts";
+import { AiConfigFromEnv } from "../config.ts";
+import type { AiConfigShape } from "../types.ts";
+import { installAiObservability } from "../observability.ts";
+import { installAiMonitor } from "../monitor.ts";
+import { modelStats, recentGenerations } from "../stats.ts";
+import { spentToday } from "../spend.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    ai: AiManager;
+  }
+}
+
+export class AiProvider extends ServiceProvider {
+  static override provides = ["ai"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker", "test"];
+
+  private _disposeObservability: (() => void) | undefined = undefined;
+
+  override onRegister(): void {
+    this.app.container.singleton("ai", () => {
+      const config = this.app.container.makeSync("config") as ConfigManager;
+      // No eager default: `AiConfig()` validates, and an app *with* a config
+      // file must not pay for — or fail on — a fallback it never uses.
+      const declared = config.get<AiConfigShape | undefined>("ai");
+      return new AiManager(declared ?? AiConfigFromEnv());
+    });
+  }
+
+  override async onBooted(): Promise<void> {
+    const ai = (await this.app.container.make("ai")) as AiManager;
+
+    this._disposeObservability = installAiObservability(this.app);
+    installAiMonitor(this.app, ai.config);
+
+    const runner = this.app.container.tryMake("commands");
+    if (runner) {
+      runner.registerLazy("ai:test", () =>
+        import("../commands/AiTestCommand.ts").then((m) => m.AiTestCommand),
+      );
+      runner.registerLazy("ai:spend", () =>
+        import("../commands/AiSpendCommand.ts").then((m) => m.AiSpendCommand),
+      );
+    }
+  }
+
+  override async onStopping(): Promise<void> {
+    this._disposeObservability?.();
+    this._disposeObservability = undefined;
+  }
+
+  /** What `zt repl` puts on the global scope. */
+  override replContext(): Record<string, unknown> {
+    return {
+      Ai: this.app.container.makeSync("ai"),
+      aiSpentToday: spentToday,
+      aiModelStats: modelStats,
+      aiRecentGenerations: recentGenerations,
+    };
+  }
+}

package/src/redact.ts

@@ -0,0 +1,32 @@
+/**
+ * Prompt redaction for the observability path.
+ *
+ * A prompt is user data. It is also the single most useful thing to put on a
+ * monitor row, which is exactly the tension: the debugging value is real, and
+ * so is the fact that logs outlive the request and get shipped somewhere else.
+ *
+ * The compromise is a *preview*, not the prompt: length and shape survive, the
+ * content does not. With redaction off you get a truncated prompt instead —
+ * still truncated, because a 40 KB system prompt on every monitor row is its
+ * own problem.
+ */
+
+/** Characters of prompt kept when redaction is off. */
+const PREVIEW_LIMIT = 200;
+
+/**
+ * Turn a prompt into something safe to record.
+ *
+ * @param prompt - The raw prompt text.
+ * @param redact - When true (the default from config), emit shape only.
+ *
+ * @example
+ * redactPrompt("Reset the password for ada@example.com", true);
+ * // → "[redacted 38 chars]"
+ * redactPrompt("Reset the password for ada@example.com", false);
+ * // → "Reset the password for ada@example.com"
+ */
+export function redactPrompt(prompt: string, redact: boolean): string {
+  if (redact) return `[redacted ${prompt.length} chars]`;
+  return prompt.length > PREVIEW_LIMIT ? `${prompt.slice(0, PREVIEW_LIMIT)}…` : prompt;
+}