@dudousxd/nestjs-agent 1.7.0 → 1.9.0

package/dist/durable/index.d.cts

@@ -1,6 +1,6 @@
 import { AgentStore, AgentRunInput, AgentLoopResult, LlmStepEnvelope, BufferedModelTurnResult, ToolStepEnvelope, AgentRunner, TokenStreamSink, HumanReply } from '@dudousxd/nestjs-agent-core';
 import { RunGateway, WorkflowCtx } from '@dudousxd/nestjs-durable-core';
-import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-CiC5Va9J.cjs';
+import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-DuTy1UyU.cjs';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 import '@standard-schema/spec';

package/dist/durable/index.d.ts

@@ -1,6 +1,6 @@
 import { AgentStore, AgentRunInput, AgentLoopResult, LlmStepEnvelope, BufferedModelTurnResult, ToolStepEnvelope, AgentRunner, TokenStreamSink, HumanReply } from '@dudousxd/nestjs-agent-core';
 import { RunGateway, WorkflowCtx } from '@dudousxd/nestjs-durable-core';
-import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-CiC5Va9J.js';
+import { A as AgentDepsFactory, a as AgentSurface, b as AgentModuleOptions } from '../agent-deps.factory-DuTy1UyU.js';
 import { WorkflowService } from '@dudousxd/nestjs-durable';
 import { DynamicModule } from '@nestjs/common';
 import '@standard-schema/spec';

package/dist/durable/index.js

@@ -72,7 +72,14 @@ var AgentRunSteps = class {
     const tools = withMemoryTool({
       tools: withSkillTool({
         tools: withAskTool({
-          tools: await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList),
+          tools: await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList, {
+            ...input.threadId !== void 0 ? {
+              threadId: input.threadId
+            } : {},
+            ...input.agentName !== void 0 ? {
+              agentName: input.agentName
+            } : {}
+          }),
           ask: deps.ask
         }),
         enabled: deps.skills !== void 0
@@ -793,7 +800,7 @@ AgentDurableModule = _ts_decorate4([
 ], AgentDurableModule);
 
 // src/agent.module.ts
-import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER11, AGENT_APPROVAL_PORT, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY7, AGENT_DURABLE_RUNNER as AGENT_DURABLE_RUNNER2, AGENT_MEMORY as AGENT_MEMORY3, AGENT_MODEL as AGENT_MODEL2, AGENT_MODEL_CATALOG as AGENT_MODEL_CATALOG2, AGENT_OPTIONS as AGENT_OPTIONS4, AGENT_PROMPT_CONTRIBUTORS as AGENT_PROMPT_CONTRIBUTORS3, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE3, AGENT_REGISTRY as AGENT_REGISTRY6, AGENT_ROLES_POLICY as AGENT_ROLES_POLICY2, AGENT_RUNNER as AGENT_RUNNER2, AGENT_SINK as AGENT_SINK3, AGENT_SKILLS as AGENT_SKILLS3, AGENT_SKILL_SOURCES as AGENT_SKILL_SOURCES2, AGENT_STORE as AGENT_STORE6, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry6, DefaultRolesPolicy, ToolRegistry as ToolRegistry3 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER11, AGENT_APPROVAL_PORT, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY7, AGENT_DURABLE_RUNNER as AGENT_DURABLE_RUNNER2, AGENT_MEMORY as AGENT_MEMORY3, AGENT_MODEL as AGENT_MODEL2, AGENT_MODEL_CATALOG as AGENT_MODEL_CATALOG2, AGENT_OPTIONS as AGENT_OPTIONS5, AGENT_PROMPT_CONTRIBUTORS as AGENT_PROMPT_CONTRIBUTORS3, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER2, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE3, AGENT_REGISTRY as AGENT_REGISTRY6, AGENT_ROLES_POLICY as AGENT_ROLES_POLICY2, AGENT_RUNNER as AGENT_RUNNER2, AGENT_SINK as AGENT_SINK3, AGENT_SKILLS as AGENT_SKILLS3, AGENT_SKILL_SOURCES as AGENT_SKILL_SOURCES2, AGENT_STORE as AGENT_STORE6, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry6, DefaultRolesPolicy, ToolRegistry as ToolRegistry3 } from "@dudousxd/nestjs-agent-core";
 import { Global as Global2, Module as Module2 } from "@nestjs/common";
 import { DiscoveryModule, RouterModule } from "@nestjs/core";
 
@@ -1063,8 +1070,8 @@ AgentDepsFactory2 = _ts_decorate5([
 ], AgentDepsFactory2);
 
 // src/agent.service.ts
-import { AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY3, AGENT_MODEL_CATALOG, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE4, REQUESTER_APPROVER, findCatalogModel, mayDecideApproval, readElicitationQuestions, validateElicitationAnswer } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException, ForbiddenException, GoneException, Inject as Inject5, Injectable as Injectable5, NotFoundException, NotImplementedException, Optional as Optional3 } from "@nestjs/common";
+import { AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY3, AGENT_MODEL_CATALOG, AGENT_OPTIONS as AGENT_OPTIONS2, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE4, REQUESTER_APPROVER, findCatalogModel, mayDecideApproval, readElicitationQuestions, validateElicitationAnswer } from "@dudousxd/nestjs-agent-core";
+import { BadRequestException, ForbiddenException, GoneException, HttpException, HttpStatus, Inject as Inject5, Injectable as Injectable5, NotFoundException, NotImplementedException, Optional as Optional3 } from "@nestjs/common";
 function _ts_decorate6(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -1101,13 +1108,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 HttpException({
+        statusCode: HttpStatus.TOO_MANY_REQUESTS,
+        code: "quota_exceeded",
+        period: blocked.period,
+        message: blocked.reason ?? `The ${blocked.period === "day" ? "daily" : "monthly"} quota is used up`
+      }, HttpStatus.TOO_MANY_REQUESTS);
+    }
   }
   /**
   * The models `actor` may pick for `agent` (`GET <base>/models`). An empty catalog when none is
@@ -1164,6 +1226,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 ?? []);
@@ -1705,6 +1768,10 @@ AgentService = _ts_decorate6([
   _ts_param5(4, Inject5(AGENT_ATTACHMENT_STAGING)),
   _ts_param5(5, Optional3()),
   _ts_param5(5, Inject5(AGENT_MODEL_CATALOG)),
+  _ts_param5(6, Optional3()),
+  _ts_param5(6, Inject5(AGENT_QUOTA_PROVIDER)),
+  _ts_param5(7, Optional3()),
+  _ts_param5(7, Inject5(AGENT_OPTIONS2)),
   _ts_metadata5("design:type", Function),
   _ts_metadata5("design:paramtypes", [
     typeof AgentRunner === "undefined" ? Object : AgentRunner,
@@ -1712,7 +1779,9 @@ AgentService = _ts_decorate6([
     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);
 
@@ -1851,7 +1920,7 @@ AgentsController = _ts_decorate8([
 ], AgentsController);
 
 // src/controller/attachments.controller.ts
-import { AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING2, AGENT_OPTIONS as AGENT_OPTIONS2 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING2, AGENT_OPTIONS as AGENT_OPTIONS3 } from "@dudousxd/nestjs-agent-core";
 import { BadRequestException as BadRequestException2, Controller as Controller2, Get as Get2, Inject as Inject7, NotImplementedException as NotImplementedException2, Optional as Optional4, PayloadTooLargeException, Post, Req, UnsupportedMediaTypeException, UploadedFile, UseInterceptors } from "@nestjs/common";
 import { FileInterceptor } from "@nestjs/platform-express";
 function _ts_decorate9(decorators, target, key, desc) {
@@ -1984,7 +2053,7 @@ _ts_decorate9([
 ], AttachmentsController.prototype, "upload", null);
 AttachmentsController = _ts_decorate9([
   Controller2("attachments"),
-  _ts_param7(0, Inject7(AGENT_OPTIONS2)),
+  _ts_param7(0, Inject7(AGENT_OPTIONS3)),
   _ts_param7(1, Inject7(AGENT_ACTOR_RESOLVER)),
   _ts_param7(3, Optional4()),
   _ts_param7(3, Inject7(AGENT_ATTACHMENT_STAGING2)),
@@ -2559,11 +2628,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_decorate14([
+  Get6(),
+  _ts_param12(0, Req6()),
+  _ts_metadata13("design:type", Function),
+  _ts_metadata13("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request
+  ]),
+  _ts_metadata13("design:returntype", Promise)
+], QuotaController.prototype, "report", null);
 _ts_decorate14([
   Get6("today"),
   _ts_param12(0, Req6()),
@@ -3320,7 +3406,7 @@ AgentDiscoveryService = _ts_decorate19([
 ], AgentDiscoveryService);
 
 // src/discovery/ai-tool-discovery.service.ts
-import { AGENT_OPTIONS as AGENT_OPTIONS3, AGENT_REGISTRY as AGENT_REGISTRY5, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY2, normalizeDelegation as normalizeDelegation2 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_OPTIONS as AGENT_OPTIONS4, AGENT_REGISTRY as AGENT_REGISTRY5, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY2, normalizeDelegation as normalizeDelegation2 } from "@dudousxd/nestjs-agent-core";
 import { Inject as Inject18, Injectable as Injectable8, Logger as Logger3 } from "@nestjs/common";
 import { DiscoveryService as DiscoveryService2 } from "@nestjs/core";
 import { z } from "zod";
@@ -3390,6 +3476,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;
@@ -3437,6 +3531,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;
@@ -3503,7 +3600,7 @@ AiToolDiscoveryService = _ts_decorate20([
   Injectable8(),
   _ts_param18(1, Inject18(AGENT_TOOL_REGISTRY2)),
   _ts_param18(2, Inject18(AGENT_REGISTRY5)),
-  _ts_param18(3, Inject18(AGENT_OPTIONS3)),
+  _ts_param18(3, Inject18(AGENT_OPTIONS4)),
   _ts_metadata19("design:type", Function),
   _ts_metadata19("design:paramtypes", [
     typeof DiscoveryService2 === "undefined" ? Object : DiscoveryService2,
@@ -3611,6 +3708,69 @@ SkillDiscoveryService = _ts_decorate21([
   ])
 ], SkillDiscoveryService);
 
+// src/ledger-quota-provider.ts
+import { exhaustedWindow, quotaPeriodRange } from "@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 = 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 = exhaustedWindow(windows);
+    return {
+      windows,
+      ...blocked !== void 0 ? {
+        blocked
+      } : {}
+    };
+  }
+  async dayWindow(actorRef, now) {
+    const range = 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 {
@@ -4137,7 +4297,7 @@ function sharedProviders(durable, includeStore) {
       provide: AGENT_SKILLS3,
       useFactory: /* @__PURE__ */ __name((options, declared) => resolveSkillsConfig(options.skills, declared), "useFactory"),
       inject: [
-        AGENT_OPTIONS4,
+        AGENT_OPTIONS5,
         AGENT_SKILL_SOURCES2
       ]
     },
@@ -4147,35 +4307,35 @@ function sharedProviders(durable, includeStore) {
       provide: AGENT_MEMORY3,
       useFactory: /* @__PURE__ */ __name((options) => options.memory, "useFactory"),
       inject: [
-        AGENT_OPTIONS4
+        AGENT_OPTIONS5
       ]
     },
     {
       provide: AGENT_SINK3,
       useFactory: /* @__PURE__ */ __name((options) => options.sink ?? new InProcessTokenStreamSink(), "useFactory"),
       inject: [
-        AGENT_OPTIONS4
+        AGENT_OPTIONS5
       ]
     },
     {
       provide: AGENT_ROLES_POLICY2,
       useFactory: /* @__PURE__ */ __name((options) => options.rolesPolicy ?? new DefaultRolesPolicy(options.defaultRoles), "useFactory"),
       inject: [
-        AGENT_OPTIONS4
+        AGENT_OPTIONS5
       ]
     },
     {
       provide: AGENT_ACTOR_RESOLVER11,
       useFactory: /* @__PURE__ */ __name((options) => options.actorResolver, "useFactory"),
       inject: [
-        AGENT_OPTIONS4
+        AGENT_OPTIONS5
       ]
     },
     {
       provide: AGENT_MODEL2,
       useFactory: /* @__PURE__ */ __name((o) => o.model, "useFactory"),
       inject: [
-        AGENT_OPTIONS4
+        AGENT_OPTIONS5
       ]
     },
     {
@@ -4185,15 +4345,24 @@ function sharedProviders(durable, includeStore) {
       provide: AGENT_QUOTA_STORE3,
       useFactory: /* @__PURE__ */ __name((o, store) => o.quota ?? (o.quotaLimitTokens !== void 0 ? new LedgerQuotaStore(store, o.quotaLimitTokens) : void 0), "useFactory"),
       inject: [
-        AGENT_OPTIONS4,
+        AGENT_OPTIONS5,
         AGENT_STORE6
       ]
     },
+    {
+      provide: AGENT_QUOTA_PROVIDER2,
+      useFactory: /* @__PURE__ */ __name((o, store, quota) => o.quotaProvider ?? new LedgerQuotaProvider(store, quota, o.quotaLimits), "useFactory"),
+      inject: [
+        AGENT_OPTIONS5,
+        AGENT_STORE6,
+        AGENT_QUOTA_STORE3
+      ]
+    },
     {
       provide: AGENT_MODEL_CATALOG2,
       useFactory: /* @__PURE__ */ __name((o) => o.models, "useFactory"),
       inject: [
-        AGENT_OPTIONS4
+        AGENT_OPTIONS5
       ]
     },
     AgentDepsFactory2,
@@ -4221,7 +4390,7 @@ function sharedProviders(durable, includeStore) {
       provide: AGENT_STORE6,
       useFactory: /* @__PURE__ */ __name((o) => o.store, "useFactory"),
       inject: [
-        AGENT_OPTIONS4
+        AGENT_OPTIONS5
       ]
     });
   }
@@ -4252,7 +4421,7 @@ function sharedProviders(durable, includeStore) {
 __name(sharedProviders, "sharedProviders");
 function exportsFor(includeStore) {
   return [
-    AGENT_OPTIONS4,
+    AGENT_OPTIONS5,
     AGENT_TOOL_REGISTRY3,
     AGENT_REGISTRY6,
     AGENT_SINK3,
@@ -4264,6 +4433,7 @@ function exportsFor(includeStore) {
     ] : [],
     AGENT_QUOTA_STORE3,
     AGENT_MODEL_CATALOG2,
+    AGENT_QUOTA_PROVIDER2,
     AGENT_PROMPT_CONTRIBUTORS3,
     AGENT_SKILLS3,
     AGENT_MEMORY3,
@@ -4343,7 +4513,7 @@ var AgentModule = class _AgentModule {
       controllers: controllersForSurface(options.surface, options.attachments?.upload === true),
       providers: [
         {
-          provide: AGENT_OPTIONS4,
+          provide: AGENT_OPTIONS5,
           useValue: options
         },
         ...sharedProviders(options.durable ?? false, includeStore),
@@ -4367,7 +4537,7 @@ var AgentModule = class _AgentModule {
       controllers: controllersForSurface(options.surface, options.attachmentsUpload === true),
       providers: [
         {
-          provide: AGENT_OPTIONS4,
+          provide: AGENT_OPTIONS5,
           // 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