@dudousxd/nestjs-agent 1.12.0 → 1.13.0

package/README.md

@@ -297,7 +297,8 @@ through `AgentService.subscribeAs(actor, runId)`.
 ### Resuming a dropped stream
 
 Every event frame of `POST /agent/chat` and `GET /agent/chat/:runId/stream` carries an SSE `id:` —
-its 1-based position in the run, the same on every attach. `GET …/stream?after=<n>` (or the
+its 1-based position in the run, the same on every attach (a runner of your own may number with gaps,
+as long as ids only increase — see *Numbering a stream you rebuild* in the protocol doc). `GET …/stream?after=<n>` (or the
 `Last-Event-ID` header) skips what a reconnecting client already has; the React transport uses it to
 continue a message after a network drop. See docs/stream-protocol.md.
 
@@ -346,8 +347,9 @@ turn rather than answering on another. `staticModelCatalog(view)` wraps a fixed
 
 ### Budgets: `GET /agent/quota`
 
-`GET /agent/quota` reports `{ windows: [{ period: 'day' | 'month', usedTokens, limitTokens?,
-usedUsd, limitUsd?, resetsAt? }], blocked? }` from a `QuotaProvider`. The default,
+`GET /agent/quota` reports `{ windows: [{ period: 'day' | 'month', usedTokens?, limitTokens?,
+usedUsd, limitUsd?, resetsAt?, warnAt? }], blocked?, warning? }` from a `QuotaProvider` (a USD-only
+budget leaves `usedTokens` out; `quota: { limits, warnAt: 0.8 }` adds a soft-limit `warning`). 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:

package/dist/{agent-deps.factory-pqv_qTmJ.d.cts → agent-deps.factory-DkWvoWbD.d.cts}

@@ -103,6 +103,14 @@ interface QuotaLimits {
     day?: QuotaWindowLimits;
     month?: QuotaWindowLimits;
 }
+/** {@link LedgerQuotaProvider}'s tuning beyond the ceilings. */
+interface LedgerQuotaOptions {
+    /**
+     * The soft limit: the share of a ceiling (`0..1`) past which the report carries a `warning`.
+     * Stamped on every window that has a ceiling. Omit → no warnings.
+     */
+    warnAt?: number;
+}
 /**
  * The default {@link QuotaProvider}: windows read off the usage ledger the loop already writes.
  *
@@ -115,7 +123,8 @@ interface QuotaLimits {
 declare class LedgerQuotaProvider implements QuotaProvider {
     private readonly store;
     private readonly limits;
-    constructor(store: AgentStore, limits?: QuotaLimits);
+    private readonly options;
+    constructor(store: AgentStore, limits?: QuotaLimits, options?: LedgerQuotaOptions);
     report(query: QuotaQuery): Promise<QuotaReport>;
     private dayWindow;
     private window;
@@ -233,7 +242,8 @@ interface AgentModuleOptions {
     sink?: TokenStreamSink;
     /**
      * The caller's budget. `{ limits: { day?: { tokens?, usd? }, month?: { tokens?, usd? } } }` puts
-     * ceilings on the built-in ledger provider; a {@link QuotaProvider} of your own replaces it. Either
+     * ceilings on the built-in ledger provider, and `warnAt` (`0..1`, e.g. `0.8`) a soft limit past
+     * which the report carries a `warning`; a {@link QuotaProvider} of your own replaces it. Either
      * way `GET <base>/quota` reports it and a send whose report comes back `blocked` is refused with
      * `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
@@ -241,6 +251,7 @@ interface AgentModuleOptions {
      */
     quota?: {
         limits: QuotaLimits;
+        warnAt?: number;
     } | QuotaProvider;
     /**
      * Which models a caller may pick — `GET <base>/models`, a send's `model`, a thread's pinned model

package/dist/{agent-deps.factory-pqv_qTmJ.d.ts → agent-deps.factory-DkWvoWbD.d.ts}

@@ -103,6 +103,14 @@ interface QuotaLimits {
     day?: QuotaWindowLimits;
     month?: QuotaWindowLimits;
 }
+/** {@link LedgerQuotaProvider}'s tuning beyond the ceilings. */
+interface LedgerQuotaOptions {
+    /**
+     * The soft limit: the share of a ceiling (`0..1`) past which the report carries a `warning`.
+     * Stamped on every window that has a ceiling. Omit → no warnings.
+     */
+    warnAt?: number;
+}
 /**
  * The default {@link QuotaProvider}: windows read off the usage ledger the loop already writes.
  *
@@ -115,7 +123,8 @@ interface QuotaLimits {
 declare class LedgerQuotaProvider implements QuotaProvider {
     private readonly store;
     private readonly limits;
-    constructor(store: AgentStore, limits?: QuotaLimits);
+    private readonly options;
+    constructor(store: AgentStore, limits?: QuotaLimits, options?: LedgerQuotaOptions);
     report(query: QuotaQuery): Promise<QuotaReport>;
     private dayWindow;
     private window;
@@ -233,7 +242,8 @@ interface AgentModuleOptions {
     sink?: TokenStreamSink;
     /**
      * The caller's budget. `{ limits: { day?: { tokens?, usd? }, month?: { tokens?, usd? } } }` puts
-     * ceilings on the built-in ledger provider; a {@link QuotaProvider} of your own replaces it. Either
+     * ceilings on the built-in ledger provider, and `warnAt` (`0..1`, e.g. `0.8`) a soft limit past
+     * which the report carries a `warning`; a {@link QuotaProvider} of your own replaces it. Either
      * way `GET <base>/quota` reports it and a send whose report comes back `blocked` is refused with
      * `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
@@ -241,6 +251,7 @@ interface AgentModuleOptions {
      */
     quota?: {
         limits: QuotaLimits;
+        warnAt?: number;
     } | QuotaProvider;
     /**
      * Which models a caller may pick — `GET <base>/models`, a send's `model`, a thread's pinned model

package/dist/durable/index.cjs

@@ -1219,8 +1219,22 @@ var AgentService = class {
     }
     return entry.id;
   }
-  /** The model a turn runs on: the send's own, else the thread's pinned one, else none. */
+  /**
+  * The model a turn runs on: the send's own (that turn only — it is never stored on the thread),
+  * else the thread's pinned one, else none. An agent the catalog locks to one model runs on it
+  * whatever was sent or pinned, and a send naming another model is refused.
+  */
   async resolveModel(actor, agent, requested, threadId) {
+    const locked = this.models !== void 0 ? (await this.models.list({
+      actor,
+      agent
+    })).locked : void 0;
+    if (locked !== void 0) {
+      if (requested !== void 0 && requested !== locked.model) {
+        throw new import_common6.BadRequestException(`model "${requested}" cannot be selected: ${locked.reason ?? `this agent always uses "${locked.model}"`}`);
+      }
+      return locked.model;
+    }
     const model = requested ?? (threadId !== void 0 ? await this.threadModel(threadId) : null);
     if (model === null || model === void 0) {
       return void 0;
@@ -1369,12 +1383,15 @@ var AgentService = class {
   * "the user picked exactly the defaults" persist as the same answers, and no client has to
   * re-send what it was shown.
   */
-  async answer(actor, toolCallId2, answers2 = {}) {
+  async answer(actor, toolCallId2, answers2 = {}, opts = {}) {
     await this.assertOwnsToolCall(actor, toolCallId2);
     await this.assertAnswersFit(toolCallId2, answers2);
     const reply = {
       answers: answers2,
-      answeredByRef: actor.id
+      answeredByRef: actor.id,
+      ...opts.via !== void 0 ? {
+        answeredVia: opts.via
+      } : {}
     };
     return this.signalToolCall(toolCallId2, reply);
   }
@@ -1383,12 +1400,15 @@ var AgentService = class {
   * them: the run records this as a rejection, so a reader auditing what the agent was told can
   * tell a choice the user made from one they refused to make.
   */
-  async skip(actor, toolCallId2) {
+  async skip(actor, toolCallId2, opts = {}) {
     await this.assertOwnsToolCall(actor, toolCallId2);
     const reply = {
       answers: {},
       skipped: true,
-      answeredByRef: actor.id
+      answeredByRef: actor.id,
+      ...opts.via !== void 0 ? {
+        answeredVia: opts.via
+      } : {}
     };
     return this.signalToolCall(toolCallId2, reply);
   }
@@ -3250,7 +3270,9 @@ var ToolCallController = class {
   */
   async answer(req, body) {
     const actor = await this.actorResolver.resolve(req);
-    await this.agent.answer(actor, toolCallId(body.toolCallId), answers(body.answers));
+    await this.agent.answer(actor, toolCallId(body.toolCallId), answers(body.answers), {
+      via: via(body.via)
+    });
     return {
       ok: true
     };
@@ -3258,7 +3280,9 @@ var ToolCallController = class {
   /** Decline to answer and let the agent proceed on the answers it pre-picked. */
   async skip(req, body) {
     const actor = await this.actorResolver.resolve(req);
-    await this.agent.skip(actor, toolCallId(body.toolCallId));
+    await this.agent.skip(actor, toolCallId(body.toolCallId), {
+      via: via(body.via)
+    });
     return {
       ok: true
     };
@@ -3894,9 +3918,11 @@ var LedgerQuotaProvider = class {
   }
   store;
   limits;
-  constructor(store, limits = {}) {
+  options;
+  constructor(store, limits = {}, options = {}) {
     this.store = store;
     this.limits = limits;
+    this.options = options;
   }
   async report(query) {
     const now = query.now ?? /* @__PURE__ */ new Date();
@@ -3910,10 +3936,14 @@ var LedgerQuotaProvider = class {
       windows.push(this.window("month", used.usedTokens, used.costUsd, range.resetsAt));
     }
     const blocked = (0, import_nestjs_agent_core25.exhaustedWindow)(windows);
+    const warning = (0, import_nestjs_agent_core25.quotaWarning)(windows);
     return {
       windows,
       ...blocked !== void 0 ? {
         blocked
+      } : {},
+      ...warning !== void 0 ? {
+        warning
       } : {}
     };
   }
@@ -3934,7 +3964,10 @@ var LedgerQuotaProvider = class {
       ...limits.usd !== void 0 ? {
         limitUsd: limits.usd
       } : {},
-      resetsAt
+      resetsAt,
+      ...this.options.warnAt !== void 0 && (limits.tokens !== void 0 || limits.usd !== void 0) ? {
+        warnAt: this.options.warnAt
+      } : {}
     };
   }
 };
@@ -4539,7 +4572,9 @@ function sharedProviders(durable) {
       // `quota` is either a provider of the host's own or ceilings for the built-in ledger one;
       // omitted, the ledger provider still reports usage, with no ceiling to block on.
       provide: import_nestjs_agent_core28.AGENT_QUOTA_PROVIDER,
-      useFactory: /* @__PURE__ */ __name((o, store) => isQuotaProvider(o.quota) ? o.quota : new LedgerQuotaProvider(store, o.quota?.limits), "useFactory"),
+      useFactory: /* @__PURE__ */ __name((o, store) => isQuotaProvider(o.quota) ? o.quota : new LedgerQuotaProvider(store, o.quota?.limits, o.quota?.warnAt !== void 0 ? {
+        warnAt: o.quota.warnAt
+      } : {}), "useFactory"),
       inject: [
         import_nestjs_agent_core28.AGENT_OPTIONS,
         import_nestjs_agent_core28.AGENT_STORE