@dudousxd/nestjs-agent 1.10.0 → 1.12.0

package/README.md

@@ -18,28 +18,47 @@ pnpm add @dudousxd/nestjs-agent @dudousxd/nestjs-agent-core
 
 ## Use
 
+The whole server — a public chat with one tool:
+
 ```ts
-import { AgentModule, AiTool, HeaderActorResolver, type ToolHandler } from '@dudousxd/nestjs-agent';
+import { AgentModule, AiTool } from '@dudousxd/nestjs-agent';
+import { aiSdkModel } from '@dudousxd/nestjs-agent-ai-sdk';
+import { openai } from '@ai-sdk/openai';
 import { z } from 'zod';
 
-@AiTool({ name: 'getWeather', kind: 'read', description: 'Current weather.', input: z.object({ city: z.string() }) })
-export class GetWeatherTool implements ToolHandler<{ city: string }> {
-  async execute(input: { city: string }) { return { tempC: 21 }; }
+@AiTool({ description: 'Current weather for a city', input: z.object({ city: z.string() }) })
+export class GetWeatherTool {            // name: getWeather, kind: read
+  async execute({ city }: { city: string }) { return { city, tempC: 21 }; }
 }
 
 @Module({
-  imports: [AgentModule.forRoot({
-    model, store, actorResolver: new HeaderActorResolver(),
-    defaultAgent: { systemPrompt: '…', modelId: 'claude-sonnet-4-6' },
-  })],
+  imports: [AgentModule.forRoot({ model: aiSdkModel(openai('gpt-5-mini')) })],
   providers: [GetWeatherTool],
 })
 export class AppModule {}
 ```
 
-The module mounts SSE + REST endpoints under `/agent` (`POST /agent/chat`, tool-call approve/reject,
-threads, quota). Add `durable: true` + `AgentDurableModule` for the durable runner;
-`AgentModule.forFeature([…])` for multi-agent orchestration.
+The module mounts SSE + REST endpoints under `/agent` (`POST /agent/chat`, threads, tool-call
+approve/reject, quota, models, tools). Everything but `model` defaults, and each default is one
+option away:
+
+| Default | Change it with |
+|---|---|
+| In-memory store (boot warning: not for production) | `store`, or import a store module (`MikroOrmAgentStoreModule.forFeature()`) — found automatically |
+| Public endpoints; each browser its own anonymous actor (HttpOnly cookie) | `actorResolver: requestUserActorResolver()` (reads `req.user`), or your own |
+| Every tool callable by any resolved actor | `@AiTool({ roles })`, `defaultRoles`, or a `rolesPolicy` |
+| `'You are a helpful assistant.'` | `systemPrompt: 'You are …'` or `({ actor }) => …`; `@Agent` classes for personas |
+| `@AiTool` name = class name minus `Tool`, camelCased; kind `read` | `@AiTool({ name, kind: 'action' })` |
+
+**Anonymous mode, and what it means.** With no `actorResolver`, anyone who can reach the API can
+chat, and each browser gets its own identity: a random token in an `HttpOnly`, `SameSite=Lax`
+cookie (`Secure` over HTTPS), the actor id a SHA-256 digest of it. Threads, quota and attachments
+are scoped by that id, so visitors never see each other's conversations; clearing cookies starts
+over. `action` tools still park on approval — but the approver is the requester, so for an anonymous
+visitor approval is a confirmation step, not an authorization: gate a consequential tool with
+`roles` (which anonymous actors do not hold). Without a quota, a public deployment's model spend is
+unbounded — set `quota` limits (they apply per anonymous id) before going public. Requiring login
+is one line: `actorResolver: requestUserActorResolver()`.
 
 ### How a chat talks about a tool
 
@@ -123,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
 
@@ -151,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`)
@@ -199,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
@@ -254,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.
@@ -286,36 +312,37 @@ bundled stores and `InMemoryAgentStore` have them) — `501` otherwise.
 
 ```ts
 AgentModule.forRoot({
-  model: aiSdkModel('openai/gpt-4o-mini', { resolveModel: (id) => gateway(id) }),
-  models: {
-    list: ({ actor }) => ({
-      default: 'openai/gpt-4o-mini',
-      providers: [
-        {
-          id: 'openai',
-          label: 'OpenAI',
-          models: [
-            { id: 'openai/gpt-4o-mini', label: 'GPT-4o mini', badges: ['fast'], available: true },
-            {
-              id: 'openai/o3',
-              label: 'o3',
-              badges: ['reasoning'],
-              available: actor.roles?.includes('PRO') === true,
-              unavailableReason: 'Pro plan',
-            },
-          ],
-        },
-      ],
-    }),
-  },
+  model: aiSdkModels(
+    {
+      'openai/gpt-4o-mini': { model: 'openai/gpt-4o-mini', label: 'GPT-4o mini', badges: ['fast'] },
+      'openai/o3': { model: 'openai/o3', label: 'o3', badges: ['reasoning'] },
+    },
+    { default: 'openai/gpt-4o-mini' },
+  ),
 });
 ```
 
+`aiSdkModels` (from `@dudousxd/nestjs-agent-ai-sdk`) carries its own catalog, used when `models` is
+omitted. For availability that depends on the caller, pass a `models` catalog of your own next to it:
+
+```ts
+models: {
+  list: ({ actor }) => ({
+    default: 'openai/gpt-4o-mini',
+    providers: [{ id: 'openai', label: 'OpenAI', models: [
+      { id: 'openai/gpt-4o-mini', label: 'GPT-4o mini', available: true },
+      { id: 'openai/o3', label: 'o3', available: actor.roles?.includes('PRO') === true, unavailableReason: 'Pro plan' },
+    ] }],
+  }),
+},
+```
+
 `GET /agent/models?agent=` answers the catalog for the caller (empty without one). A turn runs on
 the send's `model`, else the thread's pinned one (`PATCH /agent/threads/:id { model }`), else the
 provider's default; the id reaches the provider as `ModelTurnArgs.model` for every call of the turn.
 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.
+when pinned and again on each turn — and a provider asked for a model it does not serve fails the
+turn rather than answering on another. `staticModelCatalog(view)` wraps a fixed list.
 
 ### Budgets: `GET /agent/quota`
 
@@ -328,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-DuTy1UyU.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
@@ -219,45 +211,43 @@ interface AgentMemoryOptions {
     maxFactChars?: number;
 }
 interface AgentModuleOptions {
-    /** The LLM provider (e.g. a Vercel AI SDK wrapper). Required. */
+    /**
+     * The LLM provider — `aiSdkModel(openai('gpt-5-mini'))`, or `aiSdkModels({ … })` for a model
+     * picker (its catalog is used when `models` is omitted). The only required option.
+     */
     model: ModelProvider;
     /**
-     * Persistence adapter. Optional — omit it and import a store module (e.g.
-     * `MikroOrmAgentStoreModule.forFeature()`) that binds `AGENT_STORE` globally instead. When
-     * provided here it takes precedence within this module's scope.
+     * The base prompt of the default agent (and of any `@Agent` that declares none) — a string, or a
+     * function of the turn's `{ actor, agentName, pageContext }`. Omit → `'You are a helpful
+     * assistant.'`.
+     */
+    systemPrompt?: string | PromptBuilder;
+    /**
+     * Persistence adapter. Omit it and either import a store module (e.g.
+     * `MikroOrmAgentStoreModule.forFeature()`, which binds `AGENT_STORE` globally — it is found and
+     * used), or run on the built-in in-memory store — fine for a demo, logged at boot as not for
+     * production: threads vanish on restart and are not shared between processes.
      */
     store?: AgentStore;
     /** 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;
     /**
@@ -267,15 +257,20 @@ interface AgentModuleOptions {
      * deciding actor must hold that role. See `ApprovalPolicy`.
      */
     approvalPolicy?: ApprovalPolicy;
-    /** Default roles a tool requires when its `roles` is omitted. Defaults to `['ADMIN']`. */
+    /**
+     * Roles a tool requires when its own `roles` is omitted. Default `[]` — no restriction: every
+     * tool is callable by whoever `actorResolver` resolved (an anonymous visitor included, when none is
+     * configured). `action` tools still park on approval regardless.
+     */
     defaultRoles?: string[];
     /**
-     * Resolves the acting actor for each request (the identity seam). Required — the agent NEVER
-     * fabricates a caller, so this is a compile-time obligation, not an optional with a throwing
-     * placeholder. Read your authenticated principal here (session / JWT / `nestjs-context`), or use
-     * the opt-in `HeaderActorResolver` for demos and header-trusting gateways.
+     * Resolves the acting actor for each request (the identity seam). Omit → the endpoints are public
+     * and every browser is its own anonymous actor (`AnonymousActorResolver`: an `HttpOnly` cookie,
+     * the actor id a digest of it), so visitors never see each other's threads, quota or attachments.
+     * A boot notice says so. Require login with `requestUserActorResolver()` (reads `req.user`), or a
+     * resolver of your own over your session / JWT / `nestjs-context`.
      */
-    actorResolver: ActorResolver;
+    actorResolver?: ActorResolver;
     /** Route prefix the controllers mount under. Defaults to `'agent'` (→ `/agent/chat`, …). */
     path?: string;
     /**
@@ -346,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.
      */
@@ -411,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'`,
@@ -441,17 +436,6 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      * the runner. Requires importing `AgentDurableModule` and a configured `DurableModule`.
      */
     durable?: boolean;
-    /**
-     * Set when `AGENT_STORE` is bound by a globally-imported store module (e.g.
-     * `MikroOrmAgentStoreModule.forFeature()`) instead of returned as `store` from `useFactory`.
-     *
-     * `forRoot` decides this synchronously (`store` present or not), but the async factory resolves
-     * too late to inspect — so by default `forRootAsync` binds `AGENT_STORE` from the factory result,
-     * which would shadow a global store binding with `undefined` when the factory omits `store`. Set
-     * this to `true` to skip the local binding and defer to the global one. Leave it unset (and return
-     * `store` from the factory) when the store is constructed inside the factory.
-     */
-    externalStore?: boolean;
     /**
      * Guard(s) applied uniformly to every controller this module mounts. A STATIC field on the async
      * config object itself — NOT part of what `useFactory` resolves — because controllers (and the
@@ -461,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;
@@ -498,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. */