@dudousxd/nestjs-agent 1.10.0 → 1.12.0

package/dist/{agent-deps.factory-DuTy1UyU.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
@@ -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. */