@dudousxd/nestjs-agent 1.25.2 → 1.27.0

package/README.md

@@ -418,6 +418,86 @@ AgentModule.forRoot({
 
 In anonymous mode the limits apply per browser (each is its own actor).
 
+### Estimated cost is persisted, and the quota counts it
+
+A provider that reports no cost, such as Bedrock or OpenAI and Anthropic called directly, still gets
+a cost for every turn: its tokens times the model's price row. That estimate is written to the usage
+ledger: `agent_token_usage.cost_usd`, with `cost_source = 'estimate'`. Before this, the estimate
+reached only the stream frame and the message, so the ledger held NULL and the quota's USD windows
+read $0. A cost the provider reports (OpenRouter, the Vercel AI Gateway) is written as before, with
+`cost_source = 'provider'`. That reported figure always wins over an estimate. A turn with neither
+keeps `cost_usd` NULL and `cost_source` NULL.
+
+- **Schema.** `cost_source` is a nullable column that the boot schema heal adds to an existing
+  `agent_token_usage`, with no app migration. Rows written before it existed keep `cost_source`
+  NULL. They only ever held a reported cost.
+- **Frozen at write time.** An estimate uses the price row in effect for that turn. Changing a price
+  later does not rewrite history. A row with NULL `cost_usd` is still estimated at read time by the
+  governance read-model, as before.
+- **Quota.** The USD windows (`limits.day.usd`, `limits.month.usd`) sum every priced row, estimates
+  included. That is the default because otherwise a USD ceiling on a provider that reports no cost
+  would read $0 and never block: the budget would exist but never enforce. To budget on
+  provider-reported (gateway) cost only, set `quota: { limits, countEstimatedCost: false }`.
+  `quotaToday` / `usageBetween` return `{ usedTokens, costUsd, estimatedCostUsd }`, where
+  `costUsd` includes the estimated share.
+- History-summary usage rows are written before the run reads its price list, so they stay
+  unpriced in the ledger. The governance read-model still estimates them.
+
+### Pricing at boot: your own prices, and AWS Bedrock (GovCloud, China)
+
+On bootstrap `AgentModule` gives every configured model (`aiSdkModel` / `aiSdkModels` describe
+theirs) that the bound `AGENT_PRICING_STORE` has no row for a price row, so its turns record a
+`cost_usd`. It never overwrites a row that exists. The sources, in order: `priceCatalog.prices`, the
+built-in GovCloud Bedrock table, then the [models.dev](https://models.dev) list price. A model still
+unpriced gets one boot warning naming it, the reason, and the `priceCatalog.prices` entry that fixes it.
+
+Bedrock reports no cost, so a Bedrock turn is priced off the row for the exact model id the turn
+reports — often an inference-profile ARN. At boot each Bedrock id is normalized: an ARN
+(`arn:aws[-us-gov|-cn]:bedrock:<region>:<account>:(inference-profile|foundation-model|application-inference-profile)/<id>`)
+or a geo-prefixed profile (`us.`, `eu.`, `apac.`, `us-gov.`, `global.`, …) is looked up as the full
+id, then the profile id, then the base foundation-model id, and the row is written under the id the
+model is configured with (an ARN stays an ARN). An ARN is never looked up as an OpenRouter id.
+
+models.dev lists **commercial** Bedrock prices. For a model in **GovCloud** (`aws-us-gov`) or
+**China** (`aws-cn`) they are never seeded. The partition comes from the id (the ARN, or a `us-gov.`
+prefix), else `priceCatalog.region`, else `AWS_REGION` / `AWS_DEFAULT_REGION`. GovCloud models get
+a built-in table instead (`BEDROCK_BUILTIN_PRICES`: common Anthropic models, from the AWS Price List
+for us-gov-west-1). Any other model in those partitions is left unpriced, and the boot warning names
+the partition and the fix.
+
+`priceCatalog.prices` is your own rate card. Each entry seeds a row for its model, and for any
+configured model it matches by normalized id, when that model has **no** row yet (an existing row is
+never overwritten). Entries are checked before the built-in table and models.dev, so they win over
+both. An entry looks like `{ model, input, output, cacheRead?, cacheWrite?, currency?: 'USD', unit?:
+'1M tokens' | '1K tokens' }`. Only USD is accepted, because the ledger records `cost_usd`.
+
+A GovCloud app on Claude Sonnet 4.5 (us-gov-west-1 list price, USD per 1M tokens):
+
+```ts
+AgentModule.forRoot({
+  // …
+  priceCatalog: {
+    region: 'us-gov-west-1',
+    prices: [
+      {
+        // Also prices the ARN a turn reports:
+        // arn:aws-us-gov:bedrock:us-gov-west-1:<account>:inference-profile/us-gov.anthropic.claude-sonnet-4-5-20250929-v1:0
+        model: 'us-gov.anthropic.claude-sonnet-4-5-20250929-v1:0',
+        input: 3.6,
+        output: 18,
+        cacheRead: 0.36,
+        cacheWrite: 4.5,
+      },
+    ],
+  },
+});
+```
+
+Set `modelsDev: false` to keep the app prices and never fetch models.dev.
+
+A row seeded before this existed (an earlier release priced a bare base id at the commercial price)
+is **not** replaced. Correct it with `upsertModelPrice` if you run in GovCloud.
+
 ### Who approves an action, and for how long
 
 Action handlers can implement an optional read-only `preflight(input, ctx, { phase })`. The

package/dist/{chat-queue.service-Crf9uwum.d.cts → chat-queue.service-Cu2nJpXz.d.cts}

@@ -1,4 +1,4 @@
-import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, createFunctionalTool, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, ActionProposal, TextActionProposalConfig, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
+import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, createFunctionalTool, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, ActionProposal, TextActionProposalConfig, PriceCatalogOptions, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
 import { Catalog } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, InjectionToken, Type, FactoryProvider, CanActivate, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
@@ -146,6 +146,13 @@ interface LedgerQuotaOptions {
      * Stamped on every window that has a ceiling. Omit → no warnings.
      */
     warnAt?: number;
+    /**
+     * Whether the USD windows count ESTIMATED cost (tokens × the price row, for a provider that reports
+     * none, e.g. Bedrock, OpenAI or Anthropic direct) as well as provider-reported cost. Default `true`:
+     * a USD ceiling that ignored estimates would read $0 and never block for every such provider, which
+     * is a budget that does not enforce. Set `false` to budget on provider-reported (gateway) cost only.
+     */
+    countEstimatedCost?: boolean;
 }
 /**
  * The default {@link QuotaProvider}: windows read off the usage ledger the loop already writes.
@@ -163,6 +170,8 @@ declare class LedgerQuotaProvider implements QuotaProvider {
     constructor(store: AgentStore, limits?: QuotaLimits, options?: LedgerQuotaOptions);
     report(query: QuotaQuery): Promise<QuotaReport>;
     private dayWindow;
+    /** The window's USD: every priced row, or (with `countEstimatedCost: false`) reported cost only. */
+    private usd;
     private window;
 }
 
@@ -320,6 +329,34 @@ interface AgentModuleOptions {
      * turns instead.
      */
     model?: ModelProvider;
+    /**
+     * Where a configured model with no price row gets one, at boot. On application bootstrap every
+     * model the `model` provider describes (`aiSdkModel` / `aiSdkModels`) that the bound
+     * `AGENT_PRICING_STORE` does not price gets a row — only when it has none, so a price you set is
+     * never overwritten — from, in order: `prices` (your own rate card), the built-in AWS GovCloud
+     * Bedrock table (for a GovCloud model), then the current [models.dev](https://models.dev) list price
+     * (commercial; never used for a GovCloud / China Bedrock model). A model that still has no price, and
+     * whose provider reports no cost (anything but OpenRouter / the Vercel AI Gateway), is named in one
+     * boot warning with the reason and the `prices` entry that fixes it.
+     *
+     * Bedrock ids are normalized: an entry for the base id or the `us-gov.` profile id also prices the
+     * inference-profile ARN a turn reports. The AWS partition comes from the id (ARN, `us-gov.` prefix),
+     * else `region`, else `AWS_REGION` / `AWS_DEFAULT_REGION`.
+     *
+     * ```ts
+     * priceCatalog: {
+     *   region: 'us-gov-west-1',
+     *   prices: [
+     *     { model: 'us-gov.anthropic.claude-sonnet-4-5-20250929-v1:0', input: 3.6, output: 18, cacheRead: 0.36, cacheWrite: 4.5 },
+     *   ],
+     * }
+     * ```
+     *
+     * Omit → models.dev, except under `NODE_ENV=test` (no network from a test suite unless asked).
+     * `{ url, fetch }` points at a mirror; `modelsDev: false` never fetches; `false` turns off every
+     * source but the built-in table (the warning still runs).
+     */
+    priceCatalog?: PriceCatalogOptions | false;
     /**
      * Run turns on something other than this library's loop — e.g. `openCode({ host })`. The engine
      * binds `AGENT_RUNNER`; the routes, store, sink, approvals and queue stay the library's. STATIC
@@ -349,10 +386,16 @@ interface AgentModuleOptions {
      * `429` before the turn starts. Omit → reported (usage off the ledger), never enforced — for a
      * public (anonymous) deployment that means unbounded model spend, so set limits there; they apply
      * per actor, which is per browser in anonymous mode.
+     *
+     * The USD windows sum the ledger's `cost_usd`: provider-reported cost AND the loop's estimate for a
+     * provider that reports none (marked `cost_source = 'estimate'`). `countEstimatedCost: false` counts
+     * reported cost only. The default (`true`) is there because otherwise a USD ceiling on Bedrock /
+     * OpenAI / Anthropic direct would read $0 and never block.
      */
     quota?: {
         limits: QuotaLimits;
         warnAt?: number;
+        countEstimatedCost?: boolean;
     } | QuotaProvider;
     /**
      * Which models a caller may pick — `GET <base>/models`, a send's `model`, a thread's pinned model

package/dist/{chat-queue.service-ZQkqb1Yw.d.ts → chat-queue.service-uD1vR8fs.d.ts}

@@ -1,4 +1,4 @@
-import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, createFunctionalTool, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, ActionProposal, TextActionProposalConfig, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
+import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, createFunctionalTool, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, ActionProposal, TextActionProposalConfig, PriceCatalogOptions, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
 import { Catalog } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, InjectionToken, Type, FactoryProvider, CanActivate, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
@@ -146,6 +146,13 @@ interface LedgerQuotaOptions {
      * Stamped on every window that has a ceiling. Omit → no warnings.
      */
     warnAt?: number;
+    /**
+     * Whether the USD windows count ESTIMATED cost (tokens × the price row, for a provider that reports
+     * none, e.g. Bedrock, OpenAI or Anthropic direct) as well as provider-reported cost. Default `true`:
+     * a USD ceiling that ignored estimates would read $0 and never block for every such provider, which
+     * is a budget that does not enforce. Set `false` to budget on provider-reported (gateway) cost only.
+     */
+    countEstimatedCost?: boolean;
 }
 /**
  * The default {@link QuotaProvider}: windows read off the usage ledger the loop already writes.
@@ -163,6 +170,8 @@ declare class LedgerQuotaProvider implements QuotaProvider {
     constructor(store: AgentStore, limits?: QuotaLimits, options?: LedgerQuotaOptions);
     report(query: QuotaQuery): Promise<QuotaReport>;
     private dayWindow;
+    /** The window's USD: every priced row, or (with `countEstimatedCost: false`) reported cost only. */
+    private usd;
     private window;
 }
 
@@ -320,6 +329,34 @@ interface AgentModuleOptions {
      * turns instead.
      */
     model?: ModelProvider;
+    /**
+     * Where a configured model with no price row gets one, at boot. On application bootstrap every
+     * model the `model` provider describes (`aiSdkModel` / `aiSdkModels`) that the bound
+     * `AGENT_PRICING_STORE` does not price gets a row — only when it has none, so a price you set is
+     * never overwritten — from, in order: `prices` (your own rate card), the built-in AWS GovCloud
+     * Bedrock table (for a GovCloud model), then the current [models.dev](https://models.dev) list price
+     * (commercial; never used for a GovCloud / China Bedrock model). A model that still has no price, and
+     * whose provider reports no cost (anything but OpenRouter / the Vercel AI Gateway), is named in one
+     * boot warning with the reason and the `prices` entry that fixes it.
+     *
+     * Bedrock ids are normalized: an entry for the base id or the `us-gov.` profile id also prices the
+     * inference-profile ARN a turn reports. The AWS partition comes from the id (ARN, `us-gov.` prefix),
+     * else `region`, else `AWS_REGION` / `AWS_DEFAULT_REGION`.
+     *
+     * ```ts
+     * priceCatalog: {
+     *   region: 'us-gov-west-1',
+     *   prices: [
+     *     { model: 'us-gov.anthropic.claude-sonnet-4-5-20250929-v1:0', input: 3.6, output: 18, cacheRead: 0.36, cacheWrite: 4.5 },
+     *   ],
+     * }
+     * ```
+     *
+     * Omit → models.dev, except under `NODE_ENV=test` (no network from a test suite unless asked).
+     * `{ url, fetch }` points at a mirror; `modelsDev: false` never fetches; `false` turns off every
+     * source but the built-in table (the warning still runs).
+     */
+    priceCatalog?: PriceCatalogOptions | false;
     /**
      * Run turns on something other than this library's loop — e.g. `openCode({ host })`. The engine
      * binds `AGENT_RUNNER`; the routes, store, sink, approvals and queue stay the library's. STATIC
@@ -349,10 +386,16 @@ interface AgentModuleOptions {
      * `429` before the turn starts. Omit → reported (usage off the ledger), never enforced — for a
      * public (anonymous) deployment that means unbounded model spend, so set limits there; they apply
      * per actor, which is per browser in anonymous mode.
+     *
+     * The USD windows sum the ledger's `cost_usd`: provider-reported cost AND the loop's estimate for a
+     * provider that reports none (marked `cost_source = 'estimate'`). `countEstimatedCost: false` counts
+     * reported cost only. The default (`true`) is there because otherwise a USD ceiling on Bedrock /
+     * OpenAI / Anthropic direct would read $0 and never block.
      */
     quota?: {
         limits: QuotaLimits;
         warnAt?: number;
+        countEstimatedCost?: boolean;
     } | QuotaProvider;
     /**
      * Which models a caller may pick — `GET <base>/models`, a send's `model`, a thread's pinned model