@dudousxd/nestjs-agent 1.7.0 → 1.8.0

package/README.md

@@ -179,6 +179,25 @@ provider's default; the id reaches the provider as `ModelTurnArgs.model` for eve
 A model the catalog does not list as available for that actor and agent is refused with `400` —
 when pinned and again on each turn. `staticModelCatalog(view)` wraps a fixed list.
 
+### Budgets: `GET /agent/quota`
+
+`GET /agent/quota` reports `{ windows: [{ period: 'day' | 'month', usedTokens, limitTokens?,
+usedUsd, limitUsd?, resetsAt? }], blocked? }` from a `QuotaProvider`. The default,
+`LedgerQuotaProvider`, reads the usage ledger (day, plus month when the store has `usageBetween`)
+and only reports. Configure it and it also gates sends — a `blocked` report refuses `POST
+/agent/chat` with `429 { code: 'quota_exceeded', period }` before the turn starts:
+
+```ts
+AgentModule.forRoot({
+  // ceilings on the default ledger provider
+  quotaLimits: { day: { tokens: 200_000 }, month: { usd: 20 } },
+  // …or your own budget, e.g. an AI-gateway spend cap:
+  // quotaProvider: { report: async ({ actor }) => myGatewayBudget(actor.id) },
+});
+```
+
+`GET /agent/quota/today` stays as it was.
+
 ### Who approves an action, and for how long
 
 Every `action` tool call waits on the person chatting by default. `approvalPolicy` changes that per

package/dist/{agent-deps.factory-CiC5Va9J.d.cts → agent-deps.factory-Cus_RqwJ.d.cts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -87,6 +87,36 @@ interface FunctionalTool {
 declare function provideAgentTool(tool: FunctionalTool): Provider;
 declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): Provider;
 
+/** Ceilings for a {@link LedgerQuotaProvider} window. Either, both, or neither. */
+interface QuotaWindowLimits {
+    tokens?: number;
+    usd?: number;
+}
+/** Per-window ceilings: `AgentModule.forRoot({ quotaLimits })`. */
+interface QuotaLimits {
+    day?: QuotaWindowLimits;
+    month?: QuotaWindowLimits;
+}
+/**
+ * The default {@link QuotaProvider}: windows read off the usage ledger the loop already writes.
+ *
+ * - `day` — always; `usedTokens`/limit come from the bound {@link QuotaStore} when there is one (so
+ *   the report matches what the loop enforces), spend from the ledger.
+ * - `month` — when the store implements `usageBetween`.
+ *
+ * `limits` add ceilings per window (tokens and/or USD). A window that reaches one makes the report
+ * `blocked`.
+ */
+declare class LedgerQuotaProvider implements QuotaProvider {
+    private readonly store;
+    private readonly quota?;
+    private readonly limits;
+    constructor(store: AgentStore, quota?: QuotaStore | undefined, limits?: QuotaLimits);
+    report(query: QuotaQuery): Promise<QuotaReport>;
+    private dayWindow;
+    private window;
+}
+
 /**
  * Which half of the module this process mounts — the split that lets an API pod and a WORKER pod
  * each load `AgentModule` without either one doing the other's job:
@@ -205,6 +235,17 @@ interface AgentModuleOptions {
      * `ModelTurnArgs.model`. Omit → an empty catalog, and a request naming a model is refused.
      */
     models?: ModelCatalog;
+    /**
+     * The actor's budget across windows, for `GET <base>/quota` — and, once set, a gate: a send whose
+     * report comes back `blocked` is refused with `429` before the turn starts. Default: a
+     * {@link LedgerQuotaProvider} over the usage ledger (reporting only, unless `quotaLimits` is set).
+     */
+    quotaProvider?: QuotaProvider;
+    /**
+     * Ceilings for the default ledger provider's windows — `{ day?: { tokens?, usd? }, month?: {
+     * tokens?, usd? } }`. Setting it turns the send gate on. Ignored when `quotaProvider` is given.
+     */
+    quotaLimits?: QuotaLimits;
     /**
      * Daily per-actor token budget, enforced against the persisted usage ledger by the built-in
      * `LedgerQuotaStore`. A convenience over wiring a {@link QuotaStore} by hand — set this and quotas
@@ -479,4 +520,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, delegateToolName as i, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, LedgerQuotaProvider as L, type QuotaLimits as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QuotaWindowLimits as i, delegateToolName as j, provideAgentTool as p, utcDay as u };

package/dist/{agent-deps.factory-CiC5Va9J.d.ts → agent-deps.factory-Cus_RqwJ.d.ts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -87,6 +87,36 @@ interface FunctionalTool {
 declare function provideAgentTool(tool: FunctionalTool): Provider;
 declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): Provider;
 
+/** Ceilings for a {@link LedgerQuotaProvider} window. Either, both, or neither. */
+interface QuotaWindowLimits {
+    tokens?: number;
+    usd?: number;
+}
+/** Per-window ceilings: `AgentModule.forRoot({ quotaLimits })`. */
+interface QuotaLimits {
+    day?: QuotaWindowLimits;
+    month?: QuotaWindowLimits;
+}
+/**
+ * The default {@link QuotaProvider}: windows read off the usage ledger the loop already writes.
+ *
+ * - `day` — always; `usedTokens`/limit come from the bound {@link QuotaStore} when there is one (so
+ *   the report matches what the loop enforces), spend from the ledger.
+ * - `month` — when the store implements `usageBetween`.
+ *
+ * `limits` add ceilings per window (tokens and/or USD). A window that reaches one makes the report
+ * `blocked`.
+ */
+declare class LedgerQuotaProvider implements QuotaProvider {
+    private readonly store;
+    private readonly quota?;
+    private readonly limits;
+    constructor(store: AgentStore, quota?: QuotaStore | undefined, limits?: QuotaLimits);
+    report(query: QuotaQuery): Promise<QuotaReport>;
+    private dayWindow;
+    private window;
+}
+
 /**
  * Which half of the module this process mounts — the split that lets an API pod and a WORKER pod
  * each load `AgentModule` without either one doing the other's job:
@@ -205,6 +235,17 @@ interface AgentModuleOptions {
      * `ModelTurnArgs.model`. Omit → an empty catalog, and a request naming a model is refused.
      */
     models?: ModelCatalog;
+    /**
+     * The actor's budget across windows, for `GET <base>/quota` — and, once set, a gate: a send whose
+     * report comes back `blocked` is refused with `429` before the turn starts. Default: a
+     * {@link LedgerQuotaProvider} over the usage ledger (reporting only, unless `quotaLimits` is set).
+     */
+    quotaProvider?: QuotaProvider;
+    /**
+     * Ceilings for the default ledger provider's windows — `{ day?: { tokens?, usd? }, month?: {
+     * tokens?, usd? } }`. Setting it turns the send gate on. Ignored when `quotaProvider` is given.
+     */
+    quotaLimits?: QuotaLimits;
     /**
      * Daily per-actor token budget, enforced against the persisted usage ledger by the built-in
      * `LedgerQuotaStore`. A convenience over wiring a {@link QuotaStore} by hand — set this and quotas
@@ -479,4 +520,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, delegateToolName as i, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, LedgerQuotaProvider as L, type QuotaLimits as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QuotaWindowLimits as i, delegateToolName as j, provideAgentTool as p, utcDay as u };