gemi 0.157.0 → 0.160.1

package/dist/ai/usageMeter.d.ts

@@ -1,11 +1,112 @@
-import type { Usage } from "./types";
+import type { Usage as UsageType } from "./types";
+/**
+ * Usage metering by async context (#1005), with costs (#1021).
+ *
+ * An eval, or a bill, wants to know what a piece of work cost, and the model
+ * calls it made are often deep in app code: a tool that runs a builder that
+ * calls `generate`, a compaction summary, an image. Threading a counter
+ * through all of that is the plumbing every caller would forget, so the calls
+ * report themselves instead: each model call's `finish` frame (an agent step,
+ * `generate`, an image generation or edit) is recorded on every meter open in
+ * the async context it ran in.
+ *
+ * Recorded per provider call, never per run: a run's `usage` already includes
+ * its sub-runs and its tools' `generate` calls, so metering runs would count
+ * those twice. That is also why a run's cost has to be metered rather than
+ * worked out from `result.usage` afterwards: that sum mixes models, and each
+ * call is priced here, when it is recorded, at its own model's prices.
+ */
+/** USD per million tokens. `cachedInput` defaults to `input`. */
+export type ModelPrice = {
+    input: number;
+    output: number;
+    cachedInput?: number;
+    /** For image tokens (`Usage.imageInputTokens` / `imageOutputTokens`);
+     *  they're priced as text when these are absent. */
+    imageInput?: number;
+    imageOutput?: number;
+};
+/**
+ * What a model call costs.
+ *
+ * A table: USD per million tokens by model id, where a key also prices the ids
+ * it is a prefix of (`gpt-5.4` prices `gpt-5.4-2026-03-05`) and the longest
+ * key wins. Or a function, answering the cost in whatever unit the app counts
+ * in (USD micros, credits), and `undefined` for a model it doesn't price.
+ *
+ * Every cost a meter holds is in this unit, `add`ed ones included, so an app
+ * that prices with a function in micros adds micros.
+ */
+export type UsagePricing = Record<string, ModelPrice> | ((model: string, usage: UsageType) => number | undefined);
+/** One row of `UsageTotals.byModel` or `byLabel`. */
+export type UsageLine = {
+    /** Tokens. Zero for a label that only had costs `add`ed. */
+    usage: UsageType;
+    cost: number;
+    /** Model calls, plus `add`s for a label. */
+    count: number;
+};
+/** What a meter has counted so far. */
+export type UsageTotals = {
+    /** Every model call, summed. */
+    usage: UsageType;
+    /** The priced model calls and every `add`ed cost. */
+    cost: number;
+    /** By the model the provider reported (or was asked for). */
+    byModel: Record<string, UsageLine>;
+    /**
+     * By label: what was `add`ed under it, and the model calls made inside a
+     * meter opened with that `label` (the innermost label wins). Calls outside
+     * any labelled meter are in the totals and `byModel`, not here.
+     */
+    byLabel: Record<string, UsageLine>;
+    /** Models called that the pricing doesn't price; their calls cost 0. */
+    unpriced: string[];
+};
+/** An open meter: what `Usage.meter` hands its function, and `ctx.meter`. */
+export interface UsageMeter {
+    readonly label: string | undefined;
+    /**
+     * Adds a cost that isn't a model call gemi made (a browser session, an
+     * external API) under `label`, to this meter and every meter around it.
+     * In the pricing's unit. A no-op once the meter's scope has settled.
+     */
+    add(label: string, cost: number): void;
+    /** What it has counted so far. A copy. */
+    totals(): UsageTotals;
+}
+/** What `Usage.meter` measured: the function's value and the totals. */
+export type MeteredUsage<T> = UsageTotals & {
+    value: T;
+};
+export type UsageMeterOptions = {
+    /** Attributes every call inside to this label, here and in enclosing meters. */
+    label?: string;
+    /** Overrides the enclosing meter's pricing, or `Usage.configure`'s, for this one. */
+    pricing?: UsagePricing;
+};
+/**
+ * Opens a meter nested in whatever meters are open here, without running
+ * anything yet: an agent run opens its own with this, runs its loop in it
+ * (`run`) and closes it when the loop settles. `Usage.meter` is the outside.
+ */
+export declare function openMeter(options?: UsageMeterOptions): {
+    meter: UsageMeter;
+    run: <T>(fn: () => T) => T;
+    close: () => void;
+};
+declare function meter<T>(fn: (meter: UsageMeter) => T | Promise<T>, options?: UsageMeterOptions): Promise<MeteredUsage<T>>;
+/** Called by the model call sites with each `finish` frame's usage. */
+export declare function recordUsage(model: string, usage: UsageType | undefined): void;
+/** One model call's cost under `pricing`; `undefined` when it isn't priced. */
+export declare function priceUsage(pricing: UsagePricing | undefined, model: string, usage: UsageType): number | undefined;
 /** What `measureUsage` measured. */
 export type MeasuredUsage<T> = {
     value: T;
     /** Every model call made inside `fn`, summed. */
-    usage: Usage;
+    usage: UsageType;
     /** The same, by the model the provider reported (or was asked for). */
-    byModel: Record<string, Usage>;
+    byModel: Record<string, UsageType>;
 };
 /**
  * Runs `fn` and sums the usage of every model call made inside it, however
@@ -15,9 +116,51 @@ export type MeasuredUsage<T> = {
  *     const { value, usage, byModel } = await measureUsage(() => agent.stream(params).result());
  *
  * Work `fn` started and did not wait for (a background summary, say) counts
- * only if it finishes before `fn` does.
+ * only if it finishes before `fn` does. `Usage.meter` is the same with costs.
  */
 export declare function measureUsage<T>(fn: () => T | Promise<T>): Promise<MeasuredUsage<T>>;
-/** Called by the model call sites with each `finish` frame's usage. */
-export declare function recordUsage(model: string, usage: Usage | undefined): void;
+/**
+ * Token usage, and (as a value) the meter that adds it up with costs.
+ *
+ *     Usage.configure({ pricing: { "gpt-5.4": { input: 1.25, output: 10 } } });
+ *     const { value, cost, byModel, byLabel } = await Usage.meter(async (meter) => {
+ *       await review(page);           // every model call inside, however deep
+ *       meter.add("browser", 0.002);  // a cost that isn't a model call
+ *       return "done";
+ *     });
+ */
+export type Usage = UsageType;
+export declare const Usage: {
+    /**
+     * The pricing every meter uses unless it, or a meter around it, has its
+     * own. Read when a call is recorded, so meters already open pick it up.
+     * `{ pricing: undefined }` clears it.
+     */
+    configure(options: {
+        pricing?: UsagePricing;
+    }): void;
+    /**
+     * Runs `fn` with a meter open and answers its value with the totals: every
+     * model call made inside it (agent steps, `generate`, images, sub-runs),
+     * each priced at its own model's prices, and every cost `add`ed. Meters
+     * nest: an inner one's calls and costs also count for the outer ones, and
+     * concurrent meters don't see each other's. Work `fn` started and did not
+     * wait for counts only if it finishes before `fn` does.
+     */
+    meter: typeof meter;
+    /**
+     * Adds a cost to every meter open here (the innermost one and those around
+     * it), under `label`. A no-op outside any meter.
+     */
+    add(label: string, cost: number): void;
+    /**
+     * Records a model call gemi didn't make itself (a vendor SDK called
+     * directly, a usage report from elsewhere) on every meter open here, priced
+     * like any other. A no-op outside any meter.
+     */
+    record(model: string, usage: UsageType): void;
+    /** The innermost meter open here (a tool's is its run's), or `undefined`. */
+    current(): UsageMeter | undefined;
+};
+export {};
 //# sourceMappingURL=usageMeter.d.ts.map

package/dist/ai/usageMeter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usageMeter.d.ts","sourceRoot":"","sources":["../../ai/usageMeter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAqBrC,oCAAoC;AACpC,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC7B,KAAK,EAAE,CAAC,CAAC;IACT,iDAAiD;IACjD,KAAK,EAAE,KAAK,CAAC;IACb,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CASzF;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI,CASzE"}
+{"version":3,"file":"usageMeter.d.ts","sourceRoot":"","sources":["../../ai/usageMeter.ts"],"names":[],"mappings":"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"}

package/dist/app/index.js

@@ -1,4 +1,4 @@
 // @bun
-import{Da as a}from"../chunk-dhq7zv0t.js";import"../chunk-ah2jy1vx.js";import"../chunk-78wht1ph.js";export{a as App};
+import{Da as a}from"../chunk-982x8jps.js";import"../chunk-m4pkbndk.js";import"../chunk-egwz89ze.js";export{a as App};
 
 //# debugId=F6AD769F4DAEBF5D64756E2164756E21