@dudousxd/nestjs-agent 1.11.0 → 1.12.0

package/README.md

@@ -142,9 +142,13 @@ With nothing bound to `AGENT_ATTACHMENT_STAGING` there is no way to tell whose m
 turn carrying attachments is refused with `501`. Text-only turns are unaffected. At most 10
 attachments per turn.
 
-The optional `POST /agent/attachments` upload route (`attachments: { upload: true }`) aborts a body
-larger than `HARD_MAX_ATTACHMENT_BYTES` (32 MiB) while it streams; `attachments.maxBytes` narrows
-that ceiling at request time and cannot raise it.
+`POST /agent/attachments` (multipart, live whenever a staging store is bound — `501` otherwise)
+aborts a body larger than `HARD_MAX_ATTACHMENT_BYTES` (32 MiB) while it streams; the configured
+`maxBytes` narrows that ceiling at request time and cannot raise it. The limits come from ONE place:
+the staging store's own `describe()` when it declares them (`AgentMediaAttachmentsModule` does),
+else `AgentModule`'s `attachments: { maxBytes, allowedContentTypes }`, else 20 MiB and the default
+types. `GET /agent/config` serves them — with the upload mode (`multipart` or `resumable`) and the
+per-message cap — so a client never repeats them.
 
 ### Sweeping attachments nobody sent
 
@@ -170,8 +174,7 @@ regenerating a turn does — deletes messages and frees their media again. If ei
 missing the call raises `501` rather than reporting everything as collectable.
 
 `GET /agent/attachments` returns the caller's own staged files as metadata (no urls — those are
-minted per turn by `resolve`), bounded to `ATTACHMENT_PAGE_SIZE`, and rides the same
-`attachments: { upload: true }` flag. It takes no `threadId` filter: a thread's attachments already
+minted per turn by `resolve`), bounded to `ATTACHMENT_PAGE_SIZE`. It takes no `threadId` filter: a thread's attachments already
 ride on its messages in `GET /agent/threads/:id`.
 
 ### Attachments on nestjs-media (`@dudousxd/nestjs-agent/media`)
@@ -218,10 +221,14 @@ Each attachment is a media record (`ownerType: 'agent-actor'`, `ownerId: actor.i
 | 3. complete | `POST /agent/attachments/uploads/:mediaId/complete` → `MessageAttachment` | agent — checks the bytes landed at the declared size |
 | drop | `DELETE /agent/attachments/uploads/:mediaId` | agent — aborts the session, deletes bytes + record |
 
-`@dudousxd/nestjs-agent-react/media` drives all three for `useAttachments`. `POST /agent/attachments`
-(the buffered multipart route, `attachments: { upload: true }`) keeps working on the same store — its
-`stage()` writes a media record too — but it is not needed with this module; `GET
-/agent/attachments` lists either kind.
+`@dudousxd/nestjs-agent-react/media` drives all three for `useAttachments`; this is THE upload route
+with this module (`GET /agent/config` answers `upload: 'resumable'`). The buffered multipart `POST
+/agent/attachments` still stages into the same store, but is not the documented path here; `GET
+/agent/attachments` lists either kind. The module's `maxBytes` / `allowedContentTypes` are the only
+limits in force — `AgentModule`'s `attachments` option is ignored while it is imported.
+
+A replayed thread (`GET /agent/threads/:id`) re-mints each attachment's url from the store by
+`mediaId` on every read, so an old turn never shows an expired presigned link.
 
 `resolve` hands the model provider a presigned url when the disk can mint one (`urlExpiresInSeconds`,
 default 7 days), the disk's public `url()` with `visibility: 'public'`, or — on a disk that can do
@@ -273,8 +280,8 @@ export class S3Staging implements AttachmentStagingStore {
 { provide: AGENT_ATTACHMENT_STAGING, useClass: S3Staging }
 ```
 
-Then either set `attachments: { upload: true }` for the built-in `POST /agent/attachments` (which
-calls your `stage`), or upload through your own route and give the React side your own `upload`
+Then the built-in `POST /agent/attachments` calls your `stage` (no flag — binding the store is what
+turns it on), or upload through your own route and give the React side your own `upload`
 (`useAttachments({ upload })` / a backend's `uploadAttachment`) that resolves to a `{ mediaId, … }`
 your `resolve` recognises. `list` is optional and only needed for `GET /agent/attachments` and
 sweeping.
@@ -348,13 +355,13 @@ and only reports. Configure it and it also gates sends — a `blocked` report re
 ```ts
 AgentModule.forRoot({
   // ceilings on the default ledger provider
-  quotaLimits: { day: { tokens: 200_000 }, month: { usd: 20 } },
+  quota: { limits: { 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) },
+  // quota: { report: async ({ actor }) => myGatewayBudget(actor.id) },
 });
 ```
 
-`GET /agent/quota/today` stays as it was.
+In anonymous mode the limits apply per browser (each is its own actor).
 
 ### Who approves an action, and for how long
 

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

@@ -98,7 +98,7 @@ interface QuotaWindowLimits {
     tokens?: number;
     usd?: number;
 }
-/** Per-window ceilings: `AgentModule.forRoot({ quotaLimits })`. */
+/** Per-window ceilings: `AgentModule.forRoot({ quota: { limits } })`. */
 interface QuotaLimits {
     day?: QuotaWindowLimits;
     month?: QuotaWindowLimits;
@@ -106,8 +106,7 @@ interface QuotaLimits {
 /**
  * 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.
+ * - `day` — always.
  * - `month` — when the store implements `usageBetween`.
  *
  * `limits` add ceilings per window (tokens and/or USD). A window that reaches one makes the report
@@ -115,9 +114,8 @@ interface QuotaLimits {
  */
 declare class LedgerQuotaProvider implements QuotaProvider {
     private readonly store;
-    private readonly quota?;
     private readonly limits;
-    constructor(store: AgentStore, quota?: QuotaStore | undefined, limits?: QuotaLimits);
+    constructor(store: AgentStore, limits?: QuotaLimits);
     report(query: QuotaQuery): Promise<QuotaReport>;
     private dayWindow;
     private window;
@@ -144,8 +142,9 @@ declare class LedgerQuotaProvider implements QuotaProvider {
  */
 type AgentSurface = 'http' | 'engine' | 'both';
 /**
- * `AgentModuleOptions.attachments` — bounds and content-type allowlist for the optional
- * `POST /agent/attachments` upload controller (see `attachments.upload`).
+ * `AgentModuleOptions.attachments` — limits for `POST <base>/attachments`, when the bound
+ * `AGENT_ATTACHMENT_STAGING` store does not declare its own (`AgentMediaAttachmentsModule` does, and
+ * then it is the only source). Served to clients by `GET <base>/config`.
  */
 interface AgentAttachmentsOptions {
     /** Per-file size cap. Defaults to 20 MiB. */
@@ -155,13 +154,6 @@ interface AgentAttachmentsOptions {
      * `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `application/pdf`, `text/plain`, `text/csv`.
      */
     allowedContentTypes?: string[];
-    /**
-     * Mount `POST /agent/attachments`. Defaults to `false` — the controller is build-time (static)
-     * wiring, so this can't be inferred from whether `AGENT_ATTACHMENT_STAGING` ends up bound (that's
-     * a DI-time fact); set it explicitly. `true` with no `AGENT_ATTACHMENT_STAGING` provider bound
-     * fails boot loudly instead of silently mounting a controller that 501s on every request.
-     */
-    upload?: boolean;
 }
 /**
  * `AgentModuleOptions.skills` — where a turn's skills come from, and which scopes an actor draws
@@ -240,34 +232,22 @@ interface AgentModuleOptions {
     /** Live token transport. Defaults to a single-process in-memory sink. */
     sink?: TokenStreamSink;
     /**
-     * A {@link QuotaStore} for the daily token budget. Optional — omit (and omit `quotaLimitTokens`)
-     * to disable quotas. Provide this to plug a custom budget; for the common case use the simpler
-     * `quotaLimitTokens` instead, which binds the built-in ledger-backed store.
+     * 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
+     * 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
+     * per actor, which is per browser in anonymous mode.
      */
-    quota?: QuotaStore;
+    quota?: {
+        limits: QuotaLimits;
+    } | QuotaProvider;
     /**
      * Which models a caller may pick — `GET <base>/models`, a send's `model`, a thread's pinned model
-     * (`PATCH <base>/threads/:id { model }`). The picked id reaches the {@link ModelProvider} as
-     * `ModelTurnArgs.model`. Omit → an empty catalog, and a request naming a model is refused.
+     * (`PATCH <base>/threads/:id { model }`). Omit → the catalog the model provider carries
+     * (`aiSdkModels`), else none, 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
-     * turn on with no extra store. Ignored when an explicit `quota` is provided. Omit to disable.
-     */
-    quotaLimitTokens?: number;
     /** Tool authorization gate. Defaults to role-in-`defaultRoles`. */
     rolesPolicy?: RolesPolicy;
     /**
@@ -361,7 +341,7 @@ interface AgentModuleOptions {
     /**
      * A {@link HistoryPolicy} of your own — for a window the built-in can't express (pinning the
      * thread's opening brief, keeping every message that carries a tool result, a budget that varies
-     * by actor). A convenience-vs-custom pair like `quotaLimitTokens`/`quota`: this outranks a
+     * by actor). A convenience-vs-custom pair: this outranks a
      * module-wide `history`, and `@Agent({ history })` outranks both for the agent that declares it.
      * `select` MUST be pure — see the SPI's determinism contract.
      */
@@ -426,14 +406,14 @@ interface AgentModuleOptions {
     defaultAgent?: string;
     /**
      * Guard(s) applied uniformly to EVERY controller this module mounts (chat, threads, tool-call,
-     * quota, agents, and — when `attachments.upload` is set — attachments). Third-party controller
+     * quota, agents, attachments, config, …). Third-party controller
      * classes can't be annotated with `@UseGuards` by consumers, so without this option every route is
      * open beyond whatever `actorResolver` itself enforces. Guard classes are added to this module's
      * `providers` so Nest can DI-instantiate them; if a guard has its own dependencies, make sure they
      * resolve from this module's imports or a global module.
      */
     guards?: Type<CanActivate>[];
-    /** Bounds/allowlist for the optional attachment-upload controller. Omit → 20 MiB, the documented default types, not mounted. */
+    /** Upload limits when the staging store declares none. Omit → 20 MiB and the default types. */
     attachments?: AgentAttachmentsOptions;
     /**
      * Which half of the module this process mounts (see {@link AgentSurface}). Omit → `'both'`,
@@ -465,16 +445,9 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      * `useFactory`. Same default-open caveat as `AgentModuleOptions.guards`.
      */
     guards?: Type<CanActivate>[];
-    /**
-     * Mount `POST /agent/attachments`. Static, build-time control (same reasoning as `durable`/`path`
-     * above) — `useFactory` resolves too late to decide which controllers exist. The resolved
-     * `AgentModuleOptions.attachments` (maxBytes/allowedContentTypes) still applies at request time;
-     * only the yes/no mount decision has to live here.
-     */
-    attachmentsUpload?: boolean;
     /**
      * Which half of the module this process mounts (see {@link AgentSurface}). Same static-wiring
-     * reasoning as `attachmentsUpload`/`durable` above — `useFactory` resolves too late to decide
+     * reasoning as `durable` above — `useFactory` resolves too late to decide
      * which controllers exist. Omit → `'both'`, today's behavior with zero change.
      */
     surface?: AgentSurface;
@@ -502,11 +475,10 @@ declare class AgentDepsFactory {
     private readonly registry;
     private readonly agents;
     private readonly promptContributors;
-    private readonly quota;
     private readonly pricingStore;
     private readonly skills;
     private readonly memory;
-    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined, pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined);
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined);
     /** The turn's memory seam, shared with the read-back endpoint. Undefined → memory is not configured. */
     memoryConfig(): MemoryConfig | undefined;
     /** The turn's skills seam, shared with the listing endpoint. Undefined → skills are not configured. */

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

@@ -98,7 +98,7 @@ interface QuotaWindowLimits {
     tokens?: number;
     usd?: number;
 }
-/** Per-window ceilings: `AgentModule.forRoot({ quotaLimits })`. */
+/** Per-window ceilings: `AgentModule.forRoot({ quota: { limits } })`. */
 interface QuotaLimits {
     day?: QuotaWindowLimits;
     month?: QuotaWindowLimits;
@@ -106,8 +106,7 @@ interface QuotaLimits {
 /**
  * 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.
+ * - `day` — always.
  * - `month` — when the store implements `usageBetween`.
  *
  * `limits` add ceilings per window (tokens and/or USD). A window that reaches one makes the report
@@ -115,9 +114,8 @@ interface QuotaLimits {
  */
 declare class LedgerQuotaProvider implements QuotaProvider {
     private readonly store;
-    private readonly quota?;
     private readonly limits;
-    constructor(store: AgentStore, quota?: QuotaStore | undefined, limits?: QuotaLimits);
+    constructor(store: AgentStore, limits?: QuotaLimits);
     report(query: QuotaQuery): Promise<QuotaReport>;
     private dayWindow;
     private window;
@@ -144,8 +142,9 @@ declare class LedgerQuotaProvider implements QuotaProvider {
  */
 type AgentSurface = 'http' | 'engine' | 'both';
 /**
- * `AgentModuleOptions.attachments` — bounds and content-type allowlist for the optional
- * `POST /agent/attachments` upload controller (see `attachments.upload`).
+ * `AgentModuleOptions.attachments` — limits for `POST <base>/attachments`, when the bound
+ * `AGENT_ATTACHMENT_STAGING` store does not declare its own (`AgentMediaAttachmentsModule` does, and
+ * then it is the only source). Served to clients by `GET <base>/config`.
  */
 interface AgentAttachmentsOptions {
     /** Per-file size cap. Defaults to 20 MiB. */
@@ -155,13 +154,6 @@ interface AgentAttachmentsOptions {
      * `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `application/pdf`, `text/plain`, `text/csv`.
      */
     allowedContentTypes?: string[];
-    /**
-     * Mount `POST /agent/attachments`. Defaults to `false` — the controller is build-time (static)
-     * wiring, so this can't be inferred from whether `AGENT_ATTACHMENT_STAGING` ends up bound (that's
-     * a DI-time fact); set it explicitly. `true` with no `AGENT_ATTACHMENT_STAGING` provider bound
-     * fails boot loudly instead of silently mounting a controller that 501s on every request.
-     */
-    upload?: boolean;
 }
 /**
  * `AgentModuleOptions.skills` — where a turn's skills come from, and which scopes an actor draws
@@ -240,34 +232,22 @@ interface AgentModuleOptions {
     /** Live token transport. Defaults to a single-process in-memory sink. */
     sink?: TokenStreamSink;
     /**
-     * A {@link QuotaStore} for the daily token budget. Optional — omit (and omit `quotaLimitTokens`)
-     * to disable quotas. Provide this to plug a custom budget; for the common case use the simpler
-     * `quotaLimitTokens` instead, which binds the built-in ledger-backed store.
+     * 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
+     * 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
+     * per actor, which is per browser in anonymous mode.
      */
-    quota?: QuotaStore;
+    quota?: {
+        limits: QuotaLimits;
+    } | QuotaProvider;
     /**
      * Which models a caller may pick — `GET <base>/models`, a send's `model`, a thread's pinned model
-     * (`PATCH <base>/threads/:id { model }`). The picked id reaches the {@link ModelProvider} as
-     * `ModelTurnArgs.model`. Omit → an empty catalog, and a request naming a model is refused.
+     * (`PATCH <base>/threads/:id { model }`). Omit → the catalog the model provider carries
+     * (`aiSdkModels`), else none, 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
-     * turn on with no extra store. Ignored when an explicit `quota` is provided. Omit to disable.
-     */
-    quotaLimitTokens?: number;
     /** Tool authorization gate. Defaults to role-in-`defaultRoles`. */
     rolesPolicy?: RolesPolicy;
     /**
@@ -361,7 +341,7 @@ interface AgentModuleOptions {
     /**
      * A {@link HistoryPolicy} of your own — for a window the built-in can't express (pinning the
      * thread's opening brief, keeping every message that carries a tool result, a budget that varies
-     * by actor). A convenience-vs-custom pair like `quotaLimitTokens`/`quota`: this outranks a
+     * by actor). A convenience-vs-custom pair: this outranks a
      * module-wide `history`, and `@Agent({ history })` outranks both for the agent that declares it.
      * `select` MUST be pure — see the SPI's determinism contract.
      */
@@ -426,14 +406,14 @@ interface AgentModuleOptions {
     defaultAgent?: string;
     /**
      * Guard(s) applied uniformly to EVERY controller this module mounts (chat, threads, tool-call,
-     * quota, agents, and — when `attachments.upload` is set — attachments). Third-party controller
+     * quota, agents, attachments, config, …). Third-party controller
      * classes can't be annotated with `@UseGuards` by consumers, so without this option every route is
      * open beyond whatever `actorResolver` itself enforces. Guard classes are added to this module's
      * `providers` so Nest can DI-instantiate them; if a guard has its own dependencies, make sure they
      * resolve from this module's imports or a global module.
      */
     guards?: Type<CanActivate>[];
-    /** Bounds/allowlist for the optional attachment-upload controller. Omit → 20 MiB, the documented default types, not mounted. */
+    /** Upload limits when the staging store declares none. Omit → 20 MiB and the default types. */
     attachments?: AgentAttachmentsOptions;
     /**
      * Which half of the module this process mounts (see {@link AgentSurface}). Omit → `'both'`,
@@ -465,16 +445,9 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      * `useFactory`. Same default-open caveat as `AgentModuleOptions.guards`.
      */
     guards?: Type<CanActivate>[];
-    /**
-     * Mount `POST /agent/attachments`. Static, build-time control (same reasoning as `durable`/`path`
-     * above) — `useFactory` resolves too late to decide which controllers exist. The resolved
-     * `AgentModuleOptions.attachments` (maxBytes/allowedContentTypes) still applies at request time;
-     * only the yes/no mount decision has to live here.
-     */
-    attachmentsUpload?: boolean;
     /**
      * Which half of the module this process mounts (see {@link AgentSurface}). Same static-wiring
-     * reasoning as `attachmentsUpload`/`durable` above — `useFactory` resolves too late to decide
+     * reasoning as `durable` above — `useFactory` resolves too late to decide
      * which controllers exist. Omit → `'both'`, today's behavior with zero change.
      */
     surface?: AgentSurface;
@@ -502,11 +475,10 @@ declare class AgentDepsFactory {
     private readonly registry;
     private readonly agents;
     private readonly promptContributors;
-    private readonly quota;
     private readonly pricingStore;
     private readonly skills;
     private readonly memory;
-    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined, pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined);
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined);
     /** The turn's memory seam, shared with the read-back endpoint. Undefined → memory is not configured. */
     memoryConfig(): MemoryConfig | undefined;
     /** The turn's skills seam, shared with the listing endpoint. Undefined → skills are not configured. */