@dudousxd/nestjs-agent 1.7.0 → 1.9.0

package/dist/index.cjs

@@ -40,6 +40,7 @@ __export(index_exports, {
   HeaderActorResolver: () => HeaderActorResolver,
   InProcessTokenStreamSink: () => InProcessTokenStreamSink,
   InlineAgentRunner: () => InlineAgentRunner,
+  LedgerQuotaProvider: () => LedgerQuotaProvider,
   LedgerQuotaStore: () => LedgerQuotaStore,
   MemoriesController: () => MemoriesController,
   MessagesController: () => MessagesController,
@@ -56,6 +57,7 @@ __export(index_exports, {
   declaredSkillProvider: () => declaredSkillProvider,
   delegateToolName: () => delegateToolName,
   provideAgentTool: () => provideAgentTool,
+  provideAgentTools: () => provideAgentTools,
   readAgentMetadata: () => readAgentMetadata,
   readAiToolMetadata: () => readAiToolMetadata,
   readSkillMetadata: () => readSkillMetadata,
@@ -66,7 +68,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/agent.module.ts
-var import_nestjs_agent_core22 = require("@dudousxd/nestjs-agent-core");
+var import_nestjs_agent_core23 = require("@dudousxd/nestjs-agent-core");
 var import_common19 = require("@nestjs/common");
 var import_core4 = require("@nestjs/core");
 
@@ -392,13 +394,68 @@ var AgentService = class {
   quota;
   staging;
   models;
-  constructor(runner, store, deps, quota, staging, models) {
+  quotaProvider;
+  options;
+  constructor(runner, store, deps, quota, staging, models, quotaProvider, options) {
     this.runner = runner;
     this.store = store;
     this.deps = deps;
     this.quota = quota;
     this.staging = staging;
     this.models = models;
+    this.quotaProvider = quotaProvider;
+    this.options = options;
+  }
+  /**
+  * The actor's budget across windows (`GET <base>/quota`) — the bound {@link QuotaProvider}'s
+  * report. Without one (a service built outside the module), a day window from the ledger.
+  */
+  async quotaReport(actor) {
+    if (this.quotaProvider !== void 0) {
+      return this.quotaProvider.report({
+        actor
+      });
+    }
+    const today = await this.quotaToday(actor.id);
+    return {
+      windows: [
+        {
+          period: "day",
+          usedTokens: today.usedTokens,
+          ...today.limitTokens !== null ? {
+            limitTokens: today.limitTokens
+          } : {},
+          usedUsd: today.costUsd
+        }
+      ],
+      ...today.withinLimit ? {} : {
+        blocked: {
+          period: "day"
+        }
+      }
+    };
+  }
+  /**
+  * Refuse a turn the actor's budget no longer covers — only when the host configured one
+  * (`quotaProvider` or `quotaLimits`): the default report is informational, and the daily token
+  * quota the loop enforces keeps working as it always has.
+  */
+  async assertWithinQuota(actor) {
+    const gated = this.options?.quotaProvider !== void 0 || this.options?.quotaLimits !== void 0;
+    if (!gated || this.quotaProvider === void 0) {
+      return;
+    }
+    const { blocked } = await this.quotaProvider.report({
+      actor
+    });
+    if (blocked !== void 0) {
+      throw new import_common2.HttpException({
+        statusCode: import_common2.HttpStatus.TOO_MANY_REQUESTS,
+        code: "quota_exceeded",
+        period: blocked.period,
+        message: blocked.reason ?? `The ${blocked.period === "day" ? "daily" : "monthly"} quota is used up`
+      }, import_common2.HttpStatus.TOO_MANY_REQUESTS);
+    }
   }
   /**
   * The models `actor` may pick for `agent` (`GET <base>/models`). An empty catalog when none is
@@ -455,6 +512,7 @@ var AgentService = class {
     return (await this.store.getThread(threadId))?.model ?? null;
   }
   async chat(params) {
+    await this.assertWithinQuota(params.actor);
     const agentName = await this.resolveAgentName(params.agentName, params.threadId);
     const model = await this.resolveModel(params.actor, agentName, params.model, params.threadId);
     const attachments = await this.resolveAttachments(params.actor, params.attachments ?? []);
@@ -996,6 +1054,10 @@ AgentService = _ts_decorate2([
   _ts_param2(4, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_ATTACHMENT_STAGING)),
   _ts_param2(5, (0, import_common2.Optional)()),
   _ts_param2(5, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_MODEL_CATALOG)),
+  _ts_param2(6, (0, import_common2.Optional)()),
+  _ts_param2(6, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_QUOTA_PROVIDER)),
+  _ts_param2(7, (0, import_common2.Optional)()),
+  _ts_param2(7, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_OPTIONS)),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof AgentRunner === "undefined" ? Object : AgentRunner,
@@ -1003,7 +1065,9 @@ AgentService = _ts_decorate2([
     typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
     Object,
     typeof AttachmentStagingStore === "undefined" ? Object : AttachmentStagingStore,
-    typeof ModelCatalog === "undefined" ? Object : ModelCatalog
+    typeof ModelCatalog === "undefined" ? Object : ModelCatalog,
+    typeof QuotaProvider === "undefined" ? Object : QuotaProvider,
+    typeof Pick === "undefined" ? Object : Pick
   ])
 ], AgentService);
 
@@ -1850,11 +1914,28 @@ var QuotaController = class {
     this.agent = agent;
     this.actorResolver = actorResolver;
   }
+  /**
+  * The caller's budget across windows — `{ windows: [{ period, usedTokens, limitTokens?, usedUsd,
+  * limitUsd?, resetsAt? }], blocked?: { period, reason? } }` — from the bound `QuotaProvider`.
+  */
+  async report(req) {
+    const actor = await this.actorResolver.resolve(req);
+    return this.agent.quotaReport(actor);
+  }
   async today(req) {
     const actor = await this.actorResolver.resolve(req);
     return this.agent.quotaToday(actor.id);
   }
 };
+_ts_decorate10([
+  (0, import_common10.Get)(),
+  _ts_param9(0, (0, import_common10.Req)()),
+  _ts_metadata10("design:type", Function),
+  _ts_metadata10("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request
+  ]),
+  _ts_metadata10("design:returntype", Promise)
+], QuotaController.prototype, "report", null);
 _ts_decorate10([
   (0, import_common10.Get)("today"),
   _ts_param9(0, (0, import_common10.Req)()),
@@ -2677,6 +2758,14 @@ function provideAgentTool(factoryOrTool, inject) {
   };
 }
 __name(provideAgentTool, "provideAgentTool");
+function provideAgentTools(factory, inject) {
+  return {
+    provide: /* @__PURE__ */ Symbol("nestjs-agent:functional-tool-list"),
+    useFactory: /* @__PURE__ */ __name(async (...deps) => (await factory(...deps)).map(brand), "useFactory"),
+    inject: inject ?? []
+  };
+}
+__name(provideAgentTools, "provideAgentTools");
 
 // src/discovery/ai-tool-discovery.service.ts
 function _ts_decorate16(decorators, target, key, desc) {
@@ -2728,6 +2817,14 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
       if (instance === null || instance === void 0 || typeof instance !== "object") {
         continue;
       }
+      if (Array.isArray(instance) && instance.length > 0 && instance.every((each) => typeof each === "object" && each !== null && isBrandedFunctionalTool(each))) {
+        for (const tool of instance) {
+          if (this.registerFunctionalTool(tool)) {
+            functional += 1;
+          }
+        }
+        continue;
+      }
       if (isBrandedFunctionalTool(instance)) {
         if (this.registerFunctionalTool(instance)) {
           functional += 1;
@@ -2775,6 +2872,9 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
         } : {},
         ...typeof handler.canUse === "function" ? {
           canUse: /* @__PURE__ */ __name((actor) => instance.canUse(actor), "canUse")
+        } : {},
+        ...typeof handler.describe === "function" ? {
+          describe: /* @__PURE__ */ __name((scope) => instance.describe(scope), "describe")
         } : {}
       });
       count += 1;
@@ -3023,6 +3123,69 @@ var InProcessTokenStreamSink = class {
   }
 };
 
+// src/ledger-quota-provider.ts
+var import_nestjs_agent_core20 = require("@dudousxd/nestjs-agent-core");
+var LedgerQuotaProvider = class {
+  static {
+    __name(this, "LedgerQuotaProvider");
+  }
+  store;
+  quota;
+  limits;
+  constructor(store, quota, limits = {}) {
+    this.store = store;
+    this.quota = quota;
+    this.limits = limits;
+  }
+  async report(query) {
+    const now = query.now ?? /* @__PURE__ */ new Date();
+    const actorRef = query.actor.id;
+    const windows = [
+      await this.dayWindow(actorRef, now)
+    ];
+    if (this.store.usageBetween !== void 0) {
+      const range = (0, import_nestjs_agent_core20.quotaPeriodRange)("month", now);
+      const used = await this.store.usageBetween(actorRef, range.fromDay, range.toDay);
+      windows.push(this.window("month", used.usedTokens, used.costUsd, range.resetsAt));
+    }
+    const blocked = (0, import_nestjs_agent_core20.exhaustedWindow)(windows);
+    return {
+      windows,
+      ...blocked !== void 0 ? {
+        blocked
+      } : {}
+    };
+  }
+  async dayWindow(actorRef, now) {
+    const range = (0, import_nestjs_agent_core20.quotaPeriodRange)("day", now);
+    const { usedTokens, costUsd } = await this.store.quotaToday(actorRef, range.fromDay);
+    if (this.quota === void 0) {
+      return this.window("day", usedTokens, costUsd, range.resetsAt);
+    }
+    const state = await this.quota.check(actorRef, range.fromDay);
+    const window = this.window("day", state.usedTokens, costUsd, range.resetsAt);
+    if (window.limitTokens === void 0) {
+      window.limitTokens = state.limitTokens;
+    }
+    return window;
+  }
+  window(period, usedTokens, usedUsd, resetsAt) {
+    const limits = this.limits[period] ?? {};
+    return {
+      period,
+      usedTokens,
+      ...limits.tokens !== void 0 ? {
+        limitTokens: limits.tokens
+      } : {},
+      usedUsd,
+      ...limits.usd !== void 0 ? {
+        limitUsd: limits.usd
+      } : {},
+      resetsAt
+    };
+  }
+};
+
 // src/ledger-quota-store.ts
 var LedgerQuotaStore = class {
   static {
@@ -3047,7 +3210,7 @@ var LedgerQuotaStore = class {
 };
 
 // src/runner/inline-agent-runner.ts
-var import_nestjs_agent_core20 = require("@dudousxd/nestjs-agent-core");
+var import_nestjs_agent_core21 = require("@dudousxd/nestjs-agent-core");
 var import_common18 = require("@nestjs/common");
 function _ts_decorate18(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -3110,18 +3273,18 @@ var InlineAgentRunner = class _InlineAgentRunner {
         ] : []
       ]
     });
-    void (0, import_nestjs_agent_core20.runAgentLoop)({
+    void (0, import_nestjs_agent_core21.runAgentLoop)({
       ...deps,
       day
     }, input, hooks).then(() => this.store.setActiveStream(input.threadId, null)).catch(async (error) => {
-      if (error instanceof import_nestjs_agent_core20.RunCancelledError) {
+      if (error instanceof import_nestjs_agent_core21.RunCancelledError) {
         await this.settleCancelled(runId, input.threadId, deps);
         return;
       }
       const message = error instanceof Error ? error.message : String(error);
-      const code = (0, import_nestjs_agent_core20.agentFailureCode)(error);
+      const code = (0, import_nestjs_agent_core21.agentFailureCode)(error);
       this.logger.error(`agent run ${runId} failed (${code}): ${message}`);
-      (0, import_nestjs_agent_core20.publishAgentRunFailed)({
+      (0, import_nestjs_agent_core21.publishAgentRunFailed)({
         runId,
         code,
         message
@@ -3170,7 +3333,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
     for (const [key, waiter] of this.pending) {
       if (key.startsWith(`${runId}:`)) {
         this.pending.delete(key);
-        waiter.reject(new import_nestjs_agent_core20.RunCancelledError());
+        waiter.reject(new import_nestjs_agent_core21.RunCancelledError());
       }
     }
     await Promise.resolve();
@@ -3185,7 +3348,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
     this.logger.log(`agent run ${runId} cancelled`);
     await this.store.setActiveStream(threadId, null);
     const writer = await deps.sink.open(runId);
-    await writer.write((0, import_nestjs_agent_core20.encodeStreamEvent)({
+    await writer.write((0, import_nestjs_agent_core21.encodeStreamEvent)({
       kind: "cancelled"
     }));
     await writer.end();
@@ -3246,7 +3409,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       awaitApproval: /* @__PURE__ */ __name((call, _ctx, opts) => this.parkApproval(runId, call.id, opts?.timeoutMs), "awaitApproval"),
       awaitAnswers: /* @__PURE__ */ __name((request) => this.park(runId, request.id), "awaitAnswers"),
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
-      parallel: import_nestjs_agent_core20.settleAll,
+      parallel: import_nestjs_agent_core21.settleAll,
       cancelled: /* @__PURE__ */ __name(async () => this.cancelled.has(runId), "cancelled"),
       runAgent: /* @__PURE__ */ __name((agentName, task) => this.runNested({
         agentName,
@@ -3297,7 +3460,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       awaitApproval: /* @__PURE__ */ __name((call, _ctx, opts) => this.parkApproval(runId, call.id, opts?.timeoutMs), "awaitApproval"),
       awaitAnswers: /* @__PURE__ */ __name((request) => this.park(runId, request.id), "awaitAnswers"),
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
-      parallel: import_nestjs_agent_core20.settleAll,
+      parallel: import_nestjs_agent_core21.settleAll,
       cancelled: /* @__PURE__ */ __name(async () => this.cancelled.has(runId), "cancelled"),
       runAgent: /* @__PURE__ */ __name((childName, childTask) => this.runNested({
         agentName: childName,
@@ -3330,7 +3493,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
         }
       }), "startAgent")
     };
-    void (0, import_nestjs_agent_core20.runAgentLoop)({
+    void (0, import_nestjs_agent_core21.runAgentLoop)({
       ...deps,
       day
     }, {
@@ -3344,13 +3507,13 @@ var InlineAgentRunner = class _InlineAgentRunner {
       parentRunId,
       deliverTo
     }, hooks).catch(async (error) => {
-      const cancelled = error instanceof import_nestjs_agent_core20.RunCancelledError;
+      const cancelled = error instanceof import_nestjs_agent_core21.RunCancelledError;
       const message = error instanceof Error ? error.message : String(error);
       if (!cancelled) {
         this.logger.error(`detached agent run ${runId} failed: ${message}`);
-        (0, import_nestjs_agent_core20.publishAgentRunFailed)({
+        (0, import_nestjs_agent_core21.publishAgentRunFailed)({
           runId,
-          code: (0, import_nestjs_agent_core20.agentFailureCode)(error),
+          code: (0, import_nestjs_agent_core21.agentFailureCode)(error),
           message
         });
       }
@@ -3358,11 +3521,11 @@ var InlineAgentRunner = class _InlineAgentRunner {
         runId,
         status: cancelled ? "cancelled" : "failed",
         ...cancelled ? {} : {
-          errorCode: (0, import_nestjs_agent_core20.agentFailureCode)(error),
+          errorCode: (0, import_nestjs_agent_core21.agentFailureCode)(error),
           errorMessage: message
         }
       });
-      await (0, import_nestjs_agent_core20.settleUnsettledDelegation)({
+      await (0, import_nestjs_agent_core21.settleUnsettledDelegation)({
         store: this.store,
         delivery: deliverTo,
         agent: agentName,
@@ -3401,7 +3564,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       awaitApproval: /* @__PURE__ */ __name((call, _ctx, opts) => this.parkApproval(runId, call.id, opts?.timeoutMs), "awaitApproval"),
       awaitAnswers: /* @__PURE__ */ __name((request) => this.park(runId, request.id), "awaitAnswers"),
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
-      parallel: import_nestjs_agent_core20.settleAll,
+      parallel: import_nestjs_agent_core21.settleAll,
       // A child stops when it is cancelled OR when the run a human is actually watching is: the
       // canceller names the top-level run, which is the only id that ever left the server.
       cancelled: /* @__PURE__ */ __name(async () => this.cancelled.has(runId) || this.cancelled.has(sinkRunId), "cancelled"),
@@ -3436,7 +3599,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       }), "startAgent")
     };
     try {
-      return await (0, import_nestjs_agent_core20.runAgentLoop)({
+      return await (0, import_nestjs_agent_core21.runAgentLoop)({
         ...deps,
         day
       }, {
@@ -3457,8 +3620,8 @@ var InlineAgentRunner = class _InlineAgentRunner {
 };
 InlineAgentRunner = _ts_decorate18([
   (0, import_common18.Injectable)(),
-  _ts_param17(0, (0, import_common18.Inject)(import_nestjs_agent_core20.AGENT_DEPS_FACTORY)),
-  _ts_param17(1, (0, import_common18.Inject)(import_nestjs_agent_core20.AGENT_STORE)),
+  _ts_param17(0, (0, import_common18.Inject)(import_nestjs_agent_core21.AGENT_DEPS_FACTORY)),
+  _ts_param17(1, (0, import_common18.Inject)(import_nestjs_agent_core21.AGENT_STORE)),
   _ts_metadata18("design:type", Function),
   _ts_metadata18("design:paramtypes", [
     typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
@@ -3467,7 +3630,7 @@ InlineAgentRunner = _ts_decorate18([
 ], InlineAgentRunner);
 
 // src/skills-config.ts
-var import_nestjs_agent_core21 = require("@dudousxd/nestjs-agent-core");
+var import_nestjs_agent_core22 = require("@dudousxd/nestjs-agent-core");
 function declaredSkillProvider(declared) {
   return {
     list: /* @__PURE__ */ __name(({ scopes }) => declared.filter((skill) => scopes.includes(skill.scope)).map(({ name, description, scope }) => ({
@@ -3493,7 +3656,7 @@ function resolveSkillsConfig(options, declared) {
     declaredSkillProvider(declared)
   ];
   return {
-    provider: providers.length === 1 ? providers[0] : (0, import_nestjs_agent_core21.compositeSkillProvider)(providers),
+    provider: providers.length === 1 ? providers[0] : (0, import_nestjs_agent_core22.compositeSkillProvider)(providers),
     ...options.scopes !== void 0 ? {
       scopes: options.scopes
     } : {},
@@ -3523,94 +3686,103 @@ var DEFAULT_PATH = "agent";
 function sharedProviders(durable, includeStore) {
   const providers = [
     {
-      provide: import_nestjs_agent_core22.AGENT_TOOL_REGISTRY,
-      useFactory: /* @__PURE__ */ __name(() => new import_nestjs_agent_core22.ToolRegistry(), "useFactory")
+      provide: import_nestjs_agent_core23.AGENT_TOOL_REGISTRY,
+      useFactory: /* @__PURE__ */ __name(() => new import_nestjs_agent_core23.ToolRegistry(), "useFactory")
     },
     // Starts empty; AgentDiscoveryService populates it from `@Agent`-decorated providers at boot.
     {
-      provide: import_nestjs_agent_core22.AGENT_REGISTRY,
-      useFactory: /* @__PURE__ */ __name(() => new import_nestjs_agent_core22.AgentRegistry(), "useFactory")
+      provide: import_nestjs_agent_core23.AGENT_REGISTRY,
+      useFactory: /* @__PURE__ */ __name(() => new import_nestjs_agent_core23.AgentRegistry(), "useFactory")
     },
     // A shared, mutable list AgentDiscoveryService fills with `@SystemPromptContributor()` methods.
     {
-      provide: import_nestjs_agent_core22.AGENT_PROMPT_CONTRIBUTORS,
+      provide: import_nestjs_agent_core23.AGENT_PROMPT_CONTRIBUTORS,
       useFactory: /* @__PURE__ */ __name(() => [], "useFactory")
     },
     // Likewise for `@Skill`-decorated providers — filled by SkillDiscoveryService at onModuleInit,
     // read lazily by the AGENT_SKILLS provider below (which DI builds before discovery has run).
     {
-      provide: import_nestjs_agent_core22.AGENT_SKILL_SOURCES,
+      provide: import_nestjs_agent_core23.AGENT_SKILL_SOURCES,
       useFactory: /* @__PURE__ */ __name(() => [], "useFactory")
     },
     {
       // One resolution, shared by the loop's deps and the listing endpoint: a second one would
       // drift, and a user would be offered a skill the agent cannot reach. `undefined` when the
       // host configured none — which is what keeps the turn's checkpoint sequence unchanged.
-      provide: import_nestjs_agent_core22.AGENT_SKILLS,
+      provide: import_nestjs_agent_core23.AGENT_SKILLS,
       useFactory: /* @__PURE__ */ __name((options, declared) => resolveSkillsConfig(options.skills, declared), "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS,
-        import_nestjs_agent_core22.AGENT_SKILL_SOURCES
+        import_nestjs_agent_core23.AGENT_OPTIONS,
+        import_nestjs_agent_core23.AGENT_SKILL_SOURCES
       ]
     },
     {
       // One resolution, shared by the loop's deps and the read-back endpoint: a person has to be
       // shown what the model was shown, and two resolutions would eventually disagree about that.
-      provide: import_nestjs_agent_core22.AGENT_MEMORY,
+      provide: import_nestjs_agent_core23.AGENT_MEMORY,
       useFactory: /* @__PURE__ */ __name((options) => options.memory, "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS
+        import_nestjs_agent_core23.AGENT_OPTIONS
       ]
     },
     {
-      provide: import_nestjs_agent_core22.AGENT_SINK,
+      provide: import_nestjs_agent_core23.AGENT_SINK,
       useFactory: /* @__PURE__ */ __name((options) => options.sink ?? new InProcessTokenStreamSink(), "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS
+        import_nestjs_agent_core23.AGENT_OPTIONS
       ]
     },
     {
-      provide: import_nestjs_agent_core22.AGENT_ROLES_POLICY,
-      useFactory: /* @__PURE__ */ __name((options) => options.rolesPolicy ?? new import_nestjs_agent_core22.DefaultRolesPolicy(options.defaultRoles), "useFactory"),
+      provide: import_nestjs_agent_core23.AGENT_ROLES_POLICY,
+      useFactory: /* @__PURE__ */ __name((options) => options.rolesPolicy ?? new import_nestjs_agent_core23.DefaultRolesPolicy(options.defaultRoles), "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS
+        import_nestjs_agent_core23.AGENT_OPTIONS
       ]
     },
     {
-      provide: import_nestjs_agent_core22.AGENT_ACTOR_RESOLVER,
+      provide: import_nestjs_agent_core23.AGENT_ACTOR_RESOLVER,
       useFactory: /* @__PURE__ */ __name((options) => options.actorResolver, "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS
+        import_nestjs_agent_core23.AGENT_OPTIONS
       ]
     },
     {
-      provide: import_nestjs_agent_core22.AGENT_MODEL,
+      provide: import_nestjs_agent_core23.AGENT_MODEL,
       useFactory: /* @__PURE__ */ __name((o) => o.model, "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS
+        import_nestjs_agent_core23.AGENT_OPTIONS
       ]
     },
     {
       // An explicit `quota` wins; otherwise `quotaLimitTokens` binds the built-in ledger-backed
       // store; otherwise quotas are off (undefined). The ledger store reads the same usage rows
       // the loop already writes, so enforcement needs no extra shared state across replicas.
-      provide: import_nestjs_agent_core22.AGENT_QUOTA_STORE,
+      provide: import_nestjs_agent_core23.AGENT_QUOTA_STORE,
       useFactory: /* @__PURE__ */ __name((o, store) => o.quota ?? (o.quotaLimitTokens !== void 0 ? new LedgerQuotaStore(store, o.quotaLimitTokens) : void 0), "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS,
-        import_nestjs_agent_core22.AGENT_STORE
+        import_nestjs_agent_core23.AGENT_OPTIONS,
+        import_nestjs_agent_core23.AGENT_STORE
+      ]
+    },
+    {
+      provide: import_nestjs_agent_core23.AGENT_QUOTA_PROVIDER,
+      useFactory: /* @__PURE__ */ __name((o, store, quota) => o.quotaProvider ?? new LedgerQuotaProvider(store, quota, o.quotaLimits), "useFactory"),
+      inject: [
+        import_nestjs_agent_core23.AGENT_OPTIONS,
+        import_nestjs_agent_core23.AGENT_STORE,
+        import_nestjs_agent_core23.AGENT_QUOTA_STORE
       ]
     },
     {
-      provide: import_nestjs_agent_core22.AGENT_MODEL_CATALOG,
+      provide: import_nestjs_agent_core23.AGENT_MODEL_CATALOG,
       useFactory: /* @__PURE__ */ __name((o) => o.models, "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS
+        import_nestjs_agent_core23.AGENT_OPTIONS
       ]
     },
     AgentDepsFactory2,
     {
-      provide: import_nestjs_agent_core22.AGENT_DEPS_FACTORY,
+      provide: import_nestjs_agent_core23.AGENT_DEPS_FACTORY,
       useExisting: AgentDepsFactory2
     },
     // Populates the registry + contributors (onModuleInit) BEFORE AiToolDiscoveryService synthesizes
@@ -3624,22 +3796,22 @@ function sharedProviders(durable, includeStore) {
     // through AgentService.signalToolCall, which reaches whichever AGENT_RUNNER is bound above.
     AgentApprovalPortAdapter,
     {
-      provide: import_nestjs_agent_core22.AGENT_APPROVAL_PORT,
+      provide: import_nestjs_agent_core23.AGENT_APPROVAL_PORT,
       useExisting: AgentApprovalPortAdapter
     }
   ];
   if (includeStore) {
     providers.push({
-      provide: import_nestjs_agent_core22.AGENT_STORE,
+      provide: import_nestjs_agent_core23.AGENT_STORE,
       useFactory: /* @__PURE__ */ __name((o) => o.store, "useFactory"),
       inject: [
-        import_nestjs_agent_core22.AGENT_OPTIONS
+        import_nestjs_agent_core23.AGENT_OPTIONS
       ]
     });
   }
   if (durable) {
     providers.push({
-      provide: import_nestjs_agent_core22.AGENT_RUNNER,
+      provide: import_nestjs_agent_core23.AGENT_RUNNER,
       useFactory: /* @__PURE__ */ __name((durableRunner) => {
         if (durableRunner === void 0) {
           throw new Error("AgentModule.forRoot({ durable: true }) requires importing AgentDurableModule from '@dudousxd/nestjs-agent/durable' (alongside a configured DurableModule). It was not found.");
@@ -3648,14 +3820,14 @@ function sharedProviders(durable, includeStore) {
       }, "useFactory"),
       inject: [
         {
-          token: import_nestjs_agent_core22.AGENT_DURABLE_RUNNER,
+          token: import_nestjs_agent_core23.AGENT_DURABLE_RUNNER,
           optional: true
         }
       ]
     });
   } else {
     providers.push({
-      provide: import_nestjs_agent_core22.AGENT_RUNNER,
+      provide: import_nestjs_agent_core23.AGENT_RUNNER,
       useExisting: InlineAgentRunner
     });
   }
@@ -3664,26 +3836,27 @@ function sharedProviders(durable, includeStore) {
 __name(sharedProviders, "sharedProviders");
 function exportsFor(includeStore) {
   return [
-    import_nestjs_agent_core22.AGENT_OPTIONS,
-    import_nestjs_agent_core22.AGENT_TOOL_REGISTRY,
-    import_nestjs_agent_core22.AGENT_REGISTRY,
-    import_nestjs_agent_core22.AGENT_SINK,
-    import_nestjs_agent_core22.AGENT_ROLES_POLICY,
-    import_nestjs_agent_core22.AGENT_ACTOR_RESOLVER,
-    import_nestjs_agent_core22.AGENT_MODEL,
+    import_nestjs_agent_core23.AGENT_OPTIONS,
+    import_nestjs_agent_core23.AGENT_TOOL_REGISTRY,
+    import_nestjs_agent_core23.AGENT_REGISTRY,
+    import_nestjs_agent_core23.AGENT_SINK,
+    import_nestjs_agent_core23.AGENT_ROLES_POLICY,
+    import_nestjs_agent_core23.AGENT_ACTOR_RESOLVER,
+    import_nestjs_agent_core23.AGENT_MODEL,
     ...includeStore ? [
-      import_nestjs_agent_core22.AGENT_STORE
+      import_nestjs_agent_core23.AGENT_STORE
     ] : [],
-    import_nestjs_agent_core22.AGENT_QUOTA_STORE,
-    import_nestjs_agent_core22.AGENT_MODEL_CATALOG,
-    import_nestjs_agent_core22.AGENT_PROMPT_CONTRIBUTORS,
-    import_nestjs_agent_core22.AGENT_SKILLS,
-    import_nestjs_agent_core22.AGENT_MEMORY,
-    import_nestjs_agent_core22.AGENT_DEPS_FACTORY,
+    import_nestjs_agent_core23.AGENT_QUOTA_STORE,
+    import_nestjs_agent_core23.AGENT_MODEL_CATALOG,
+    import_nestjs_agent_core23.AGENT_QUOTA_PROVIDER,
+    import_nestjs_agent_core23.AGENT_PROMPT_CONTRIBUTORS,
+    import_nestjs_agent_core23.AGENT_SKILLS,
+    import_nestjs_agent_core23.AGENT_MEMORY,
+    import_nestjs_agent_core23.AGENT_DEPS_FACTORY,
     AgentDepsFactory2,
     AgentService,
     InlineAgentRunner,
-    import_nestjs_agent_core22.AGENT_APPROVAL_PORT
+    import_nestjs_agent_core23.AGENT_APPROVAL_PORT
   ];
 }
 __name(exportsFor, "exportsFor");
@@ -3755,7 +3928,7 @@ var AgentModule = class _AgentModule {
       controllers: controllersForSurface(options.surface, options.attachments?.upload === true),
       providers: [
         {
-          provide: import_nestjs_agent_core22.AGENT_OPTIONS,
+          provide: import_nestjs_agent_core23.AGENT_OPTIONS,
           useValue: options
         },
         ...sharedProviders(options.durable ?? false, includeStore),
@@ -3779,7 +3952,7 @@ var AgentModule = class _AgentModule {
       controllers: controllersForSurface(options.surface, options.attachmentsUpload === true),
       providers: [
         {
-          provide: import_nestjs_agent_core22.AGENT_OPTIONS,
+          provide: import_nestjs_agent_core23.AGENT_OPTIONS,
           // Stamp the STATIC wiring flags onto the factory result: `durable`/`surface` are
           // authoritative on the async config object (they decided the actual wiring above), and
           // the durable module reads `durable` back off AGENT_OPTIONS. `surface` isn't read back by
@@ -3858,6 +4031,7 @@ __reExport(index_exports, require("@dudousxd/nestjs-agent-core"), module.exports
   HeaderActorResolver,
   InProcessTokenStreamSink,
   InlineAgentRunner,
+  LedgerQuotaProvider,
   LedgerQuotaStore,
   MemoriesController,
   MessagesController,
@@ -3874,6 +4048,7 @@ __reExport(index_exports, require("@dudousxd/nestjs-agent-core"), module.exports
   declaredSkillProvider,
   delegateToolName,
   provideAgentTool,
+  provideAgentTools,
   readAgentMetadata,
   readAiToolMetadata,
   readSkillMetadata,