@dudousxd/nestjs-agent 1.10.0 → 1.12.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-DuTy1UyU.cjs';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QuotaLimits, i as QuotaWindowLimits, j as delegateToolName, p as provideAgentTool, k as provideAgentTools, u as utcDay } from './agent-deps.factory-DuTy1UyU.cjs';
-import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
+import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-pqv_qTmJ.cjs';
+export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QuotaLimits, i as QuotaWindowLimits, j as delegateToolName, p as provideAgentTool, k as provideAgentTools, u as utcDay } from './agent-deps.factory-pqv_qTmJ.cjs';
+import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AgentApprovalPort, ActorResolver, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -56,12 +56,11 @@ declare class AgentService {
     private readonly runner;
     private readonly store;
     private readonly deps;
-    private readonly quota;
     private readonly staging?;
     private readonly models?;
     private readonly quotaProvider?;
     private readonly options?;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quotaProvider" | "quotaLimits"> | undefined);
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined);
     /**
      * The actor's budget across windows (`GET <base>/quota`) — the bound {@link QuotaProvider}'s
      * report. Without one (a service built outside the module), a day window from the ledger.
@@ -69,8 +68,7 @@ declare class AgentService {
     quotaReport(actor: Actor): Promise<QuotaReport>;
     /**
      * Refuse a turn the actor's budget no longer covers — only when the host configured one
-     * (`quotaProvider` or `quotaLimits`): the default report is informational, and the daily token
-     * quota the loop enforces keeps working as it always has.
+     * (`quota`): the default report is informational.
      */
     private assertWithinQuota;
     /**
@@ -182,6 +180,13 @@ declare class AgentService {
     private threadDefaultAgent;
     private toSummaryView;
     private toDetailView;
+    /**
+     * Re-mint each replayed attachment's url from the staging store, by `mediaId`: the url persisted
+     * with the message was minted for THAT turn (a presigned url with an expiry), so an old turn would
+     * otherwise show a dead link. The store's own access check applies — an attachment it will not
+     * resolve for this actor keeps the url it was stored with.
+     */
+    private freshAttachmentUrls;
     promoteThread(actor: Actor, threadId: string): Promise<void>;
     /**
      * Drop a message and everything after it — the "edit and resend" / "delete from here" primitive.
@@ -233,12 +238,6 @@ declare class AgentService {
      * otherwise render identically — as a clean file list, and as a sweep that collects nothing.
      */
     private attachmentInventory;
-    /**
-     * The day's usage for the badge: tokens + summed USD cost from the store, and the configured
-     * limit from the quota store (null → unlimited). `withinLimit` comes from the quota store so it
-     * can never drift from what enforcement uses.
-     */
-    quotaToday(actorRef: string): Promise<QuotaView>;
     /**
      * Authorization seam for thread-scoped endpoints: the caller must own the thread. A missing
      * thread is a 404; someone else's thread is a 403 — one actor never touches another's thread.
@@ -313,8 +312,6 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     }): Promise<void>;
 }
 
-/** Default per-file size cap when `AgentModuleOptions.attachments.maxBytes` is omitted (20 MiB). */
-declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
 /**
  * How many entries `GET /agent/attachments` returns. Fixed rather than caller-supplied: this route
  * exists so a composer can show the files someone has uploaded, and a host that needs real paging
@@ -322,13 +319,8 @@ declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
  */
 declare const ATTACHMENT_PAGE_SIZE = 50;
 /**
- * Default allowlist: what multimodal model providers commonly accept as native image/file parts.
- */
-declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
-/**
- * Optional `POST /agent/attachments` upload surface — mounted only when `AgentModuleOptions
- * .attachments.upload` (or the async config's `attachmentsUpload`) is `true` (see `agent.module.ts`).
- * Multipart single file field `'file'`, buffered in memory (no disk write — `FileInterceptor`'s
+ * `POST <base>/attachments` — the multipart upload route, live whenever an
+ * `AGENT_ATTACHMENT_STAGING` provider is bound (`501` otherwise). Multipart single file field `'file'`, buffered in memory (no disk write — `FileInterceptor`'s
  * default storage) up to {@link HARD_MAX_ATTACHMENT_BYTES}, then validated against the configured
  * size cap + content-type allowlist and handed to the bound {@link AttachmentStagingStore} to
  * persist and turn into a model-fetchable URL. Both size gates answer `413`: the ceiling aborts the
@@ -339,19 +331,12 @@ declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
  * host deleting bytes, so it stays an in-process call (`AgentService.collectableAttachments`)
  * rather than something reachable with a session cookie.
  */
-declare class AttachmentsController implements OnModuleInit {
+declare class AttachmentsController {
     private readonly options;
     private readonly actorResolver;
     private readonly agents;
     private readonly staging;
     constructor(options: AgentModuleOptions, actorResolver: ActorResolver, agents: AgentService, staging: AttachmentStagingStore | undefined);
-    /**
-     * `attachments.upload: true` is what mounts this controller at all (see `agent.module.ts`), so by
-     * the time an instance exists the host clearly intends uploads to work. Fail boot loudly rather
-     * than mounting a controller that would 501 on every single request because nobody bound
-     * `AGENT_ATTACHMENT_STAGING`.
-     */
-    onModuleInit(): void;
     /**
      * The caller's own staged files, newest first — the one question `GET /agent/threads/:id` cannot
      * answer, since an upload that was never sent belongs to no thread.
@@ -365,21 +350,52 @@ declare class AttachmentsController implements OnModuleInit {
     upload(req: Request, file: Express.Multer.File | undefined): Promise<MessageAttachment>;
 }
 
+/** Default per-file size cap (20 MiB). */
+declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/** Default allowlist: what multimodal model providers commonly accept as native image/file parts. */
+declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
+/** How many attachments one message may name. */
+declare const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+/** The attachment rules in force — `AgentAttachmentConfig`, as `GET <base>/config` serves it. */
+type AttachmentLimits = AgentAttachmentConfig;
+/**
+ * One source for attachment limits: the staging store's own `describe()` when it declares them
+ * (`AgentMediaAttachmentsModule` does), else `AgentModule`'s `attachments` option, else the defaults.
+ */
+declare function attachmentLimits(options: Pick<AgentModuleOptions, 'attachments'> | undefined, staging: AttachmentStagingStore | undefined): AttachmentLimits;
+
+declare class ConfigController {
+    private readonly options;
+    private readonly actorResolver;
+    private readonly staging;
+    private readonly models;
+    constructor(options: AgentModuleOptions, actorResolver: ActorResolver, staging: AttachmentStagingStore | undefined, models: ModelCatalog | undefined);
+    config(req: Request): Promise<AgentClientConfig>;
+}
+
 declare const AI_TOOL_METADATA: unique symbol;
 interface AiToolOptions {
-    name: string;
     /**
-     * `read` auto-executes; `action` requires HITL approval. (Core's `ToolKind` also has `agent`
-     * for delegation, but that kind is synthesized from `delegatesTo` — never authored here.)
+     * What the model calls it. Omit → the class name, camelCased, with a trailing `Tool` dropped
+     * (`GetWeatherTool` → `getWeather`).
      */
-    kind: 'read' | 'action';
+    name?: string;
+    /**
+     * `read` (the default) auto-executes; `action` requires HITL approval. (Core's `ToolKind` also
+     * has `agent` for delegation, but that kind is synthesized from `delegatesTo` — never authored
+     * here.)
+     */
+    kind?: 'read' | 'action';
     description: string;
     /**
      * Input schema as a [Standard Schema](https://standardschema.dev) — Zod, Valibot, or ArkType.
      * Validated before the handler runs.
      */
     input: StandardSchemaV1;
-    /** Roles allowed to invoke. Omit to inherit the module's default roles. */
+    /**
+     * Roles allowed to invoke. Omit → the module's `defaultRoles`, which by default restrict nobody:
+     * any resolved actor — an anonymous visitor included, when no `actorResolver` is configured.
+     */
     roles?: string[];
     /**
      * Whether this tool exists in this deployment. `false` — or a predicate returning `false`, which
@@ -420,13 +436,21 @@ interface AiToolOptions {
      */
     terminal?: boolean;
 }
+/** {@link AiToolOptions} with the defaults applied — what discovery reads. */
+interface ResolvedAiToolOptions extends AiToolOptions {
+    name: string;
+    kind: 'read' | 'action';
+}
+/** `GetWeatherTool` → `getWeather`; `SQLQueryTool` → `sqlQuery`. */
+declare function toolNameFromClass(className: string): string;
 /**
  * Marks a provider class as an AI tool. The class must implement `execute(input, ctx)`.
  * `AiToolDiscoveryService` registers every `@AiTool` provider into the `ToolRegistry` at boot.
+ * Only `description` and `input` are required:
  *
  * ```ts
- * @AiTool({ name: 'getWeather', kind: 'read', description: '...', input: z.object({ city: z.string() }) })
- * class GetWeatherTool implements ToolHandler<{ city: string }> {
+ * @AiTool({ description: 'Current weather for a city', input: z.object({ city: z.string() }) })
+ * class GetWeatherTool implements ToolHandler<{ city: string }> { // name: getWeather, kind: read
  *   async execute(input, ctx) { return { tempC: 21 }; }
  * }
  * ```
@@ -444,7 +468,7 @@ interface AiToolOptions {
  * ```
  */
 declare function AiTool(options: AiToolOptions): ClassDecorator;
-declare function readAiToolMetadata(target: object): AiToolOptions | undefined;
+declare function readAiToolMetadata(target: object): ResolvedAiToolOptions | undefined;
 
 /**
  * Declares a class as an agent. The class is discovered at boot (via `DiscoveryService`) and
@@ -915,21 +939,6 @@ declare class InProcessTokenStreamSink implements TokenStreamSink {
     close(runId: string): void;
 }
 
-/**
- * A production {@link QuotaStore} backed by the persisted usage ledger. `check` reads the actor's
- * tokens-so-far for the day straight from {@link AgentStore.quotaToday} and compares it to a fixed
- * daily limit; `bump` is a deliberate no-op because the loop's `recordUsage` already writes every
- * turn's tokens to that same ledger. One source of truth — so enforcement and what the dashboard
- * reports can never drift, and it works across replicas with no extra shared state.
- */
-declare class LedgerQuotaStore implements QuotaStore {
-    private readonly store;
-    private readonly limitTokens;
-    constructor(store: AgentStore, limitTokens: number);
-    check(actorRef: string, day: string): Promise<QuotaState>;
-    bump(_actorRef: string, _day: string, _tokens: number): Promise<void>;
-}
-
 /**
  * A development / gateway {@link ActorResolver} that trusts request headers:
  * `x-actor-id` (required), `x-actor-role` (comma-separated → `roles`), `x-tenant-ref`.
@@ -946,4 +955,77 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, MessagesController, ModelsController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };
+interface AnonymousActorOptions {
+    /** The cookie holding the browser's anonymous token. Default `agent_anon`. */
+    cookieName?: string;
+    /** How long a browser keeps its identity (and so its threads). Default 365 days. */
+    maxAgeDays?: number;
+    /**
+     * `SameSite` of the cookie. Default `'lax'` — sent on same-site requests, not on cross-site
+     * POSTs. A SPA on another SITE than the API needs `'none'` (which forces `Secure`) plus
+     * `credentials: 'include'` on the client.
+     */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /**
+     * `Secure` flag. Default `'auto'`: set when the request arrived over HTTPS (`req.secure`, or an
+     * `x-forwarded-proto: https` from a proxy).
+     */
+    secure?: boolean | 'auto';
+    /** Cookie path. Default `/`. */
+    path?: string;
+    /** Roles every anonymous actor carries. Default `['anonymous']`. */
+    roles?: string[];
+}
+/**
+ * The zero-config identity: every browser is its own anonymous actor, so a login-less chat still
+ * keeps each visitor's threads, quota and attachments apart from everyone else's.
+ *
+ * On a browser's first request the resolver mints 32 random bytes and sets them as an `HttpOnly`
+ * cookie (`SameSite=Lax`, `Secure` over HTTPS). The actor id is a SHA-256 digest of that token —
+ * `anon:<digest>` — never the token itself, so an id that surfaces anywhere (a thread row, a log, an
+ * approval's `decidedBy`) cannot be replayed as the cookie.
+ *
+ * Why a server-minted cookie and not an id the client makes up and sends in a header: an
+ * `HttpOnly` cookie is out of reach of page scripts (an XSS cannot lift it), the server — not the
+ * client — decides the value, and it needs no client code at all. There is no signing secret to
+ * configure: the token is unguessable on its own, and the digest works the same on every pod and
+ * after a restart.
+ *
+ * Anonymous identities are per browser, not per person: clearing cookies starts over, and there is
+ * nothing to recover them with. Require login with an `ActorResolver` that reads your session —
+ * `requestUserActorResolver()` for `req.user` (Passport / cookie-session apps).
+ */
+declare class AnonymousActorResolver implements ActorResolver {
+    private readonly options;
+    private readonly cookieName;
+    private readonly roles;
+    constructor(options?: AnonymousActorOptions);
+    resolve(request: unknown): Actor;
+    private setCookie;
+}
+
+/** Turns whatever your auth put on `req.user` into the agent's {@link Actor}. */
+type RequestUserMapper<TUser = Record<string, unknown>> = (user: TUser, req: unknown) => Actor | Promise<Actor>;
+/**
+ * The default mapping: `id` from `id` / `sub` / `_id` / `userId`, `roles` from `roles` (an array)
+ * or `role` (a string), `tenantRef` from `tenantRef` / `tenantId` / `orgId`.
+ */
+declare function defaultRequestUserMapper(user: Record<string, unknown>): Actor;
+/**
+ * Authenticated mode in one line, for apps whose auth already puts the principal on `req.user` —
+ * Passport strategies, `express-session` / cookie-session middleware, a Nest guard that assigns it:
+ *
+ * ```ts
+ * AgentModule.forRoot({ model, actorResolver: requestUserActorResolver() })
+ * ```
+ *
+ * A request without `req.user` is refused with `401` — the agent never invents a caller. Pass a
+ * mapper when your user object is shaped differently:
+ *
+ * ```ts
+ * requestUserActorResolver((user: SessionUser) => ({ id: user.uuid, roles: user.permissions }))
+ * ```
+ */
+declare function requestUserActorResolver<TUser = Record<string, unknown>>(map?: RequestUserMapper<TUser>): ActorResolver;
+
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, type RequestUserMapper, type ResolvedAiToolOptions, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-DuTy1UyU.js';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QuotaLimits, i as QuotaWindowLimits, j as delegateToolName, p as provideAgentTool, k as provideAgentTools, u as utcDay } from './agent-deps.factory-DuTy1UyU.js';
-import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
+import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-pqv_qTmJ.js';
+export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QuotaLimits, i as QuotaWindowLimits, j as delegateToolName, p as provideAgentTool, k as provideAgentTools, u as utcDay } from './agent-deps.factory-pqv_qTmJ.js';
+import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AgentApprovalPort, ActorResolver, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -56,12 +56,11 @@ declare class AgentService {
     private readonly runner;
     private readonly store;
     private readonly deps;
-    private readonly quota;
     private readonly staging?;
     private readonly models?;
     private readonly quotaProvider?;
     private readonly options?;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quotaProvider" | "quotaLimits"> | undefined);
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined);
     /**
      * The actor's budget across windows (`GET <base>/quota`) — the bound {@link QuotaProvider}'s
      * report. Without one (a service built outside the module), a day window from the ledger.
@@ -69,8 +68,7 @@ declare class AgentService {
     quotaReport(actor: Actor): Promise<QuotaReport>;
     /**
      * Refuse a turn the actor's budget no longer covers — only when the host configured one
-     * (`quotaProvider` or `quotaLimits`): the default report is informational, and the daily token
-     * quota the loop enforces keeps working as it always has.
+     * (`quota`): the default report is informational.
      */
     private assertWithinQuota;
     /**
@@ -182,6 +180,13 @@ declare class AgentService {
     private threadDefaultAgent;
     private toSummaryView;
     private toDetailView;
+    /**
+     * Re-mint each replayed attachment's url from the staging store, by `mediaId`: the url persisted
+     * with the message was minted for THAT turn (a presigned url with an expiry), so an old turn would
+     * otherwise show a dead link. The store's own access check applies — an attachment it will not
+     * resolve for this actor keeps the url it was stored with.
+     */
+    private freshAttachmentUrls;
     promoteThread(actor: Actor, threadId: string): Promise<void>;
     /**
      * Drop a message and everything after it — the "edit and resend" / "delete from here" primitive.
@@ -233,12 +238,6 @@ declare class AgentService {
      * otherwise render identically — as a clean file list, and as a sweep that collects nothing.
      */
     private attachmentInventory;
-    /**
-     * The day's usage for the badge: tokens + summed USD cost from the store, and the configured
-     * limit from the quota store (null → unlimited). `withinLimit` comes from the quota store so it
-     * can never drift from what enforcement uses.
-     */
-    quotaToday(actorRef: string): Promise<QuotaView>;
     /**
      * Authorization seam for thread-scoped endpoints: the caller must own the thread. A missing
      * thread is a 404; someone else's thread is a 403 — one actor never touches another's thread.
@@ -313,8 +312,6 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     }): Promise<void>;
 }
 
-/** Default per-file size cap when `AgentModuleOptions.attachments.maxBytes` is omitted (20 MiB). */
-declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
 /**
  * How many entries `GET /agent/attachments` returns. Fixed rather than caller-supplied: this route
  * exists so a composer can show the files someone has uploaded, and a host that needs real paging
@@ -322,13 +319,8 @@ declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
  */
 declare const ATTACHMENT_PAGE_SIZE = 50;
 /**
- * Default allowlist: what multimodal model providers commonly accept as native image/file parts.
- */
-declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
-/**
- * Optional `POST /agent/attachments` upload surface — mounted only when `AgentModuleOptions
- * .attachments.upload` (or the async config's `attachmentsUpload`) is `true` (see `agent.module.ts`).
- * Multipart single file field `'file'`, buffered in memory (no disk write — `FileInterceptor`'s
+ * `POST <base>/attachments` — the multipart upload route, live whenever an
+ * `AGENT_ATTACHMENT_STAGING` provider is bound (`501` otherwise). Multipart single file field `'file'`, buffered in memory (no disk write — `FileInterceptor`'s
  * default storage) up to {@link HARD_MAX_ATTACHMENT_BYTES}, then validated against the configured
  * size cap + content-type allowlist and handed to the bound {@link AttachmentStagingStore} to
  * persist and turn into a model-fetchable URL. Both size gates answer `413`: the ceiling aborts the
@@ -339,19 +331,12 @@ declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
  * host deleting bytes, so it stays an in-process call (`AgentService.collectableAttachments`)
  * rather than something reachable with a session cookie.
  */
-declare class AttachmentsController implements OnModuleInit {
+declare class AttachmentsController {
     private readonly options;
     private readonly actorResolver;
     private readonly agents;
     private readonly staging;
     constructor(options: AgentModuleOptions, actorResolver: ActorResolver, agents: AgentService, staging: AttachmentStagingStore | undefined);
-    /**
-     * `attachments.upload: true` is what mounts this controller at all (see `agent.module.ts`), so by
-     * the time an instance exists the host clearly intends uploads to work. Fail boot loudly rather
-     * than mounting a controller that would 501 on every single request because nobody bound
-     * `AGENT_ATTACHMENT_STAGING`.
-     */
-    onModuleInit(): void;
     /**
      * The caller's own staged files, newest first — the one question `GET /agent/threads/:id` cannot
      * answer, since an upload that was never sent belongs to no thread.
@@ -365,21 +350,52 @@ declare class AttachmentsController implements OnModuleInit {
     upload(req: Request, file: Express.Multer.File | undefined): Promise<MessageAttachment>;
 }
 
+/** Default per-file size cap (20 MiB). */
+declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/** Default allowlist: what multimodal model providers commonly accept as native image/file parts. */
+declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
+/** How many attachments one message may name. */
+declare const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+/** The attachment rules in force — `AgentAttachmentConfig`, as `GET <base>/config` serves it. */
+type AttachmentLimits = AgentAttachmentConfig;
+/**
+ * One source for attachment limits: the staging store's own `describe()` when it declares them
+ * (`AgentMediaAttachmentsModule` does), else `AgentModule`'s `attachments` option, else the defaults.
+ */
+declare function attachmentLimits(options: Pick<AgentModuleOptions, 'attachments'> | undefined, staging: AttachmentStagingStore | undefined): AttachmentLimits;
+
+declare class ConfigController {
+    private readonly options;
+    private readonly actorResolver;
+    private readonly staging;
+    private readonly models;
+    constructor(options: AgentModuleOptions, actorResolver: ActorResolver, staging: AttachmentStagingStore | undefined, models: ModelCatalog | undefined);
+    config(req: Request): Promise<AgentClientConfig>;
+}
+
 declare const AI_TOOL_METADATA: unique symbol;
 interface AiToolOptions {
-    name: string;
     /**
-     * `read` auto-executes; `action` requires HITL approval. (Core's `ToolKind` also has `agent`
-     * for delegation, but that kind is synthesized from `delegatesTo` — never authored here.)
+     * What the model calls it. Omit → the class name, camelCased, with a trailing `Tool` dropped
+     * (`GetWeatherTool` → `getWeather`).
      */
-    kind: 'read' | 'action';
+    name?: string;
+    /**
+     * `read` (the default) auto-executes; `action` requires HITL approval. (Core's `ToolKind` also
+     * has `agent` for delegation, but that kind is synthesized from `delegatesTo` — never authored
+     * here.)
+     */
+    kind?: 'read' | 'action';
     description: string;
     /**
      * Input schema as a [Standard Schema](https://standardschema.dev) — Zod, Valibot, or ArkType.
      * Validated before the handler runs.
      */
     input: StandardSchemaV1;
-    /** Roles allowed to invoke. Omit to inherit the module's default roles. */
+    /**
+     * Roles allowed to invoke. Omit → the module's `defaultRoles`, which by default restrict nobody:
+     * any resolved actor — an anonymous visitor included, when no `actorResolver` is configured.
+     */
     roles?: string[];
     /**
      * Whether this tool exists in this deployment. `false` — or a predicate returning `false`, which
@@ -420,13 +436,21 @@ interface AiToolOptions {
      */
     terminal?: boolean;
 }
+/** {@link AiToolOptions} with the defaults applied — what discovery reads. */
+interface ResolvedAiToolOptions extends AiToolOptions {
+    name: string;
+    kind: 'read' | 'action';
+}
+/** `GetWeatherTool` → `getWeather`; `SQLQueryTool` → `sqlQuery`. */
+declare function toolNameFromClass(className: string): string;
 /**
  * Marks a provider class as an AI tool. The class must implement `execute(input, ctx)`.
  * `AiToolDiscoveryService` registers every `@AiTool` provider into the `ToolRegistry` at boot.
+ * Only `description` and `input` are required:
  *
  * ```ts
- * @AiTool({ name: 'getWeather', kind: 'read', description: '...', input: z.object({ city: z.string() }) })
- * class GetWeatherTool implements ToolHandler<{ city: string }> {
+ * @AiTool({ description: 'Current weather for a city', input: z.object({ city: z.string() }) })
+ * class GetWeatherTool implements ToolHandler<{ city: string }> { // name: getWeather, kind: read
  *   async execute(input, ctx) { return { tempC: 21 }; }
  * }
  * ```
@@ -444,7 +468,7 @@ interface AiToolOptions {
  * ```
  */
 declare function AiTool(options: AiToolOptions): ClassDecorator;
-declare function readAiToolMetadata(target: object): AiToolOptions | undefined;
+declare function readAiToolMetadata(target: object): ResolvedAiToolOptions | undefined;
 
 /**
  * Declares a class as an agent. The class is discovered at boot (via `DiscoveryService`) and
@@ -915,21 +939,6 @@ declare class InProcessTokenStreamSink implements TokenStreamSink {
     close(runId: string): void;
 }
 
-/**
- * A production {@link QuotaStore} backed by the persisted usage ledger. `check` reads the actor's
- * tokens-so-far for the day straight from {@link AgentStore.quotaToday} and compares it to a fixed
- * daily limit; `bump` is a deliberate no-op because the loop's `recordUsage` already writes every
- * turn's tokens to that same ledger. One source of truth — so enforcement and what the dashboard
- * reports can never drift, and it works across replicas with no extra shared state.
- */
-declare class LedgerQuotaStore implements QuotaStore {
-    private readonly store;
-    private readonly limitTokens;
-    constructor(store: AgentStore, limitTokens: number);
-    check(actorRef: string, day: string): Promise<QuotaState>;
-    bump(_actorRef: string, _day: string, _tokens: number): Promise<void>;
-}
-
 /**
  * A development / gateway {@link ActorResolver} that trusts request headers:
  * `x-actor-id` (required), `x-actor-role` (comma-separated → `roles`), `x-tenant-ref`.
@@ -946,4 +955,77 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, MessagesController, ModelsController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };
+interface AnonymousActorOptions {
+    /** The cookie holding the browser's anonymous token. Default `agent_anon`. */
+    cookieName?: string;
+    /** How long a browser keeps its identity (and so its threads). Default 365 days. */
+    maxAgeDays?: number;
+    /**
+     * `SameSite` of the cookie. Default `'lax'` — sent on same-site requests, not on cross-site
+     * POSTs. A SPA on another SITE than the API needs `'none'` (which forces `Secure`) plus
+     * `credentials: 'include'` on the client.
+     */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /**
+     * `Secure` flag. Default `'auto'`: set when the request arrived over HTTPS (`req.secure`, or an
+     * `x-forwarded-proto: https` from a proxy).
+     */
+    secure?: boolean | 'auto';
+    /** Cookie path. Default `/`. */
+    path?: string;
+    /** Roles every anonymous actor carries. Default `['anonymous']`. */
+    roles?: string[];
+}
+/**
+ * The zero-config identity: every browser is its own anonymous actor, so a login-less chat still
+ * keeps each visitor's threads, quota and attachments apart from everyone else's.
+ *
+ * On a browser's first request the resolver mints 32 random bytes and sets them as an `HttpOnly`
+ * cookie (`SameSite=Lax`, `Secure` over HTTPS). The actor id is a SHA-256 digest of that token —
+ * `anon:<digest>` — never the token itself, so an id that surfaces anywhere (a thread row, a log, an
+ * approval's `decidedBy`) cannot be replayed as the cookie.
+ *
+ * Why a server-minted cookie and not an id the client makes up and sends in a header: an
+ * `HttpOnly` cookie is out of reach of page scripts (an XSS cannot lift it), the server — not the
+ * client — decides the value, and it needs no client code at all. There is no signing secret to
+ * configure: the token is unguessable on its own, and the digest works the same on every pod and
+ * after a restart.
+ *
+ * Anonymous identities are per browser, not per person: clearing cookies starts over, and there is
+ * nothing to recover them with. Require login with an `ActorResolver` that reads your session —
+ * `requestUserActorResolver()` for `req.user` (Passport / cookie-session apps).
+ */
+declare class AnonymousActorResolver implements ActorResolver {
+    private readonly options;
+    private readonly cookieName;
+    private readonly roles;
+    constructor(options?: AnonymousActorOptions);
+    resolve(request: unknown): Actor;
+    private setCookie;
+}
+
+/** Turns whatever your auth put on `req.user` into the agent's {@link Actor}. */
+type RequestUserMapper<TUser = Record<string, unknown>> = (user: TUser, req: unknown) => Actor | Promise<Actor>;
+/**
+ * The default mapping: `id` from `id` / `sub` / `_id` / `userId`, `roles` from `roles` (an array)
+ * or `role` (a string), `tenantRef` from `tenantRef` / `tenantId` / `orgId`.
+ */
+declare function defaultRequestUserMapper(user: Record<string, unknown>): Actor;
+/**
+ * Authenticated mode in one line, for apps whose auth already puts the principal on `req.user` —
+ * Passport strategies, `express-session` / cookie-session middleware, a Nest guard that assigns it:
+ *
+ * ```ts
+ * AgentModule.forRoot({ model, actorResolver: requestUserActorResolver() })
+ * ```
+ *
+ * A request without `req.user` is refused with `401` — the agent never invents a caller. Pass a
+ * mapper when your user object is shaped differently:
+ *
+ * ```ts
+ * requestUserActorResolver((user: SessionUser) => ({ id: user.uuid, roles: user.permissions }))
+ * ```
+ */
+declare function requestUserActorResolver<TUser = Record<string, unknown>>(map?: RequestUserMapper<TUser>): ActorResolver;
+
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, type RequestUserMapper, type ResolvedAiToolOptions, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };