@dudousxd/nestjs-agent 0.3.2 → 0.4.0

package/dist/{agent-deps.factory-DpVkZYCy.d.cts → agent-deps.factory-BM_RB6br.d.cts}

@@ -1,5 +1,5 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Retriever, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
-import { Provider, FactoryProvider, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Retriever, AgentPricingStore, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
 interface AgentDeps {
@@ -25,6 +25,8 @@ interface AgentDeps {
     retriever?: Retriever;
     /** Passages inject-mode retrieval requests. Undefined → loop default (5). */
     retrievalTopK?: number;
+    /** Bound `AGENT_PRICING_STORE`, when a module (e.g. a store's) provides one. Undefined → no pricing. */
+    pricingStore?: AgentPricingStore;
 }
 declare function utcDay(date?: Date): string;
 
@@ -49,6 +51,26 @@ interface FunctionalTool {
 declare function provideAgentTool(tool: FunctionalTool): Provider;
 declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): Provider;
 
+/**
+ * `AgentModuleOptions.attachments` — bounds and content-type allowlist for the optional
+ * `POST /agent/attachments` upload controller (see `attachments.upload`).
+ */
+interface AgentAttachmentsOptions {
+    /** Per-file size cap. Defaults to 20 MiB. */
+    maxBytes?: number;
+    /**
+     * Allowed multipart content types. Defaults to what multimodal model providers commonly accept:
+     * `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;
+}
 interface AgentModuleOptions {
     /** The LLM provider (e.g. a Vercel AI SDK wrapper). Required. */
     model: ModelProvider;
@@ -125,6 +147,17 @@ interface AgentModuleOptions {
      * `@Agent` is registered). Agents themselves are declared as `@Agent`-decorated providers, not here.
      */
     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
+     * 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. */
+    attachments?: AgentAttachmentsOptions;
 }
 interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
@@ -140,6 +173,33 @@ 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
+     * enhancers bound to them) are wired at module build time, before any async factory has run. If a
+     * guard needs async-resolved config (e.g. a secret from a `ConfigService`), have the guard inject
+     * that service via DI (see `imports`/`inject` above) rather than trying to thread it through
+     * `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;
 }
 
 /** The synthesized `agent`-kind tool name an orchestrator uses to hand off to `target`. */
@@ -155,7 +215,8 @@ declare class AgentDepsFactory {
     private readonly agents;
     private readonly promptContributors;
     private readonly quota;
-    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined);
+    private readonly pricingStore;
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined, pricingStore: AgentPricingStore | undefined);
     /**
      * The agent a turn uses when the caller names none: the explicit `defaultAgent` option, else the
      * sole registered `@Agent` when there is exactly one, else `'default'` (a bare assistant).
@@ -167,4 +228,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, type AgentModuleOptions as a, type AgentModuleAsyncOptions as b, AGENT_TOOL_BRAND as c, type AgentDeps as d, delegateToolName as e, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, type AgentModuleOptions as a, type AgentModuleAsyncOptions as b, AGENT_TOOL_BRAND as c, type AgentAttachmentsOptions as d, type AgentDeps as e, delegateToolName as f, provideAgentTool as p, utcDay as u };

package/dist/{agent-deps.factory-DpVkZYCy.d.ts → agent-deps.factory-BM_RB6br.d.ts}

@@ -1,5 +1,5 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Retriever, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
-import { Provider, FactoryProvider, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Retriever, AgentPricingStore, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
 interface AgentDeps {
@@ -25,6 +25,8 @@ interface AgentDeps {
     retriever?: Retriever;
     /** Passages inject-mode retrieval requests. Undefined → loop default (5). */
     retrievalTopK?: number;
+    /** Bound `AGENT_PRICING_STORE`, when a module (e.g. a store's) provides one. Undefined → no pricing. */
+    pricingStore?: AgentPricingStore;
 }
 declare function utcDay(date?: Date): string;
 
@@ -49,6 +51,26 @@ interface FunctionalTool {
 declare function provideAgentTool(tool: FunctionalTool): Provider;
 declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): Provider;
 
+/**
+ * `AgentModuleOptions.attachments` — bounds and content-type allowlist for the optional
+ * `POST /agent/attachments` upload controller (see `attachments.upload`).
+ */
+interface AgentAttachmentsOptions {
+    /** Per-file size cap. Defaults to 20 MiB. */
+    maxBytes?: number;
+    /**
+     * Allowed multipart content types. Defaults to what multimodal model providers commonly accept:
+     * `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;
+}
 interface AgentModuleOptions {
     /** The LLM provider (e.g. a Vercel AI SDK wrapper). Required. */
     model: ModelProvider;
@@ -125,6 +147,17 @@ interface AgentModuleOptions {
      * `@Agent` is registered). Agents themselves are declared as `@Agent`-decorated providers, not here.
      */
     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
+     * 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. */
+    attachments?: AgentAttachmentsOptions;
 }
 interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
@@ -140,6 +173,33 @@ 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
+     * enhancers bound to them) are wired at module build time, before any async factory has run. If a
+     * guard needs async-resolved config (e.g. a secret from a `ConfigService`), have the guard inject
+     * that service via DI (see `imports`/`inject` above) rather than trying to thread it through
+     * `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;
 }
 
 /** The synthesized `agent`-kind tool name an orchestrator uses to hand off to `target`. */
@@ -155,7 +215,8 @@ declare class AgentDepsFactory {
     private readonly agents;
     private readonly promptContributors;
     private readonly quota;
-    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined);
+    private readonly pricingStore;
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined, pricingStore: AgentPricingStore | undefined);
     /**
      * The agent a turn uses when the caller names none: the explicit `defaultAgent` option, else the
      * sole registered `@Agent` when there is exactly one, else `'default'` (a bare assistant).
@@ -167,4 +228,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, type AgentModuleOptions as a, type AgentModuleAsyncOptions as b, AGENT_TOOL_BRAND as c, type AgentDeps as d, delegateToolName as e, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, type AgentModuleOptions as a, type AgentModuleAsyncOptions as b, AGENT_TOOL_BRAND as c, type AgentAttachmentsOptions as d, type AgentDeps as e, delegateToolName as f, provideAgentTool as p, utcDay as u };