@dudousxd/nestjs-agent 1.9.0 → 1.11.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
 
@@ -155,6 +174,111 @@ minted per turn by `resolve`), bounded to `ATTACHMENT_PAGE_SIZE`, and rides the
 `attachments: { upload: true }` flag. 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`)
+
+A ready `AGENT_ATTACHMENT_STAGING` backed by [`@dudousxd/nestjs-media`](https://davidecarvalho.github.io/aviary/docs/media),
+with resumable (tus) uploads. `@dudousxd/nestjs-media` is an **optional** peer: only this subpath
+imports it, and nothing on the root entry needs it.
+
+Minimal — next to a `MediaModule` that has `store`, `uploadSessions` and `tus`:
+
+```ts
+@Module({
+  imports: [
+    MediaModule.forRoot({ /* disks, store, uploadSessions, tus */ }),
+    AgentModule.forRoot({ /* … */ }),
+    AgentMediaAttachmentsModule.forRoot(), // ← the whole integration
+  ],
+})
+// main.ts — nestjs-media's own requirement for tus PATCH bodies:
+app.useBodyParser('raw', { type: 'application/offset+octet-stream' });
+```
+
+Everything is overridable when you need it:
+
+```ts
+AgentMediaAttachmentsModule.forRoot({
+  maxBytes: 50 * 1024 * 1024,
+  allowedContentTypes: ['image/png', 'image/jpeg', 'application/pdf'],
+  collection: 'chat-files',
+  canAccess: ({ allowed, actor }) => allowed || actor.roles?.includes('support') === true,
+  resolveUrl: (record) => signMyProxyUrl(record.id), // instead of presign / public / inline
+  indexForRag: true, // see below
+  guards: [SessionGuard],
+});
+```
+
+Each attachment is a media record (`ownerType: 'agent-actor'`, `ownerId: actor.id`, collection
+`agent-attachments`). The upload never goes through the agent:
+
+| Step | Route | Who serves it |
+| --- | --- | --- |
+| 1. open | `POST /agent/attachments/uploads` `{ filename, contentType, size }` → `{ mediaId, uploadId, location }` | agent — validates type/size and opens a tus session the actor owns |
+| 2. bytes | `PATCH <location>` (tus, chunked, resumable) | **nestjs-media** |
+| 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.
+
+`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
+neither, such as local disk in development — the bytes inline as a `data:` url (logged once; that
+url is persisted with the message). `resolveUrl(record, { disk })` takes over entirely. The actor may
+use media they own, and media a message in one of their own threads already carries; anything else
+resolves `null` (`403` on the chat route).
+
+Cleanup: an upload abandoned half-way is already a record, so it shows up in `list` and ages into
+`collectableAttachments`. Delete through the store so the tus session is aborted too:
+
+```ts
+const media = app.get(MediaAttachmentStaging);
+for (const entry of await agents.collectableAttachments(actor, { olderThan })) {
+  await media.remove(entry.mediaId);
+}
+```
+
+`indexForRag: true` announces every ready attachment on `aviary:media:attach` (and its removal on
+`aviary:media:delete`) so `@dudousxd/nestjs-agent-rag-media` indexes it. Off by default — only turn
+it on where retrieval is filtered by owner (`FilteredRetriever` on `ownerType`/`ownerId`), and
+restrict rag-media's `collections` accordingly.
+
+`forRootAsync({ imports, inject, useFactory, path, guards })` takes the same options; `path` must
+match `AgentModule`'s `path` (default `agent`), and `guards` gates the upload routes.
+
+### Bring your own storage
+
+Nothing requires nestjs-media. Bind your own `AttachmentStagingStore` and upload however you like:
+
+```ts
+@Injectable()
+export class S3Staging implements AttachmentStagingStore {
+  async stage({ data, filename, contentType, actor }: StageAttachmentInput) {
+    const mediaId = randomUUID();
+    await this.s3.put(`chat/${actor.id}/${mediaId}`, data, { contentType });
+    await this.db.insert(files).values({ mediaId, owner: actor.id, filename, contentType });
+    return { mediaId, url: '', contentType, name: filename };
+  }
+  async resolve({ mediaId, actor }: ResolveAttachmentInput) {
+    const row = await this.db.query.files.findFirst({ where: eq(files.mediaId, mediaId) });
+    if (!row || row.owner !== actor.id) return null; // unknown and foreign look the same
+    const url = await this.s3.presign(`chat/${actor.id}/${mediaId}`, 3600);
+    return { mediaId, url, contentType: row.contentType, name: row.filename };
+  }
+}
+
+// alongside AgentModule, in a @Global() module (or any module AgentModule can see):
+{ 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`
+(`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.
+
 ### Who may read a run
 
 `GET /agent/chat/:runId/stream` and `POST /agent/chat/:runId/cancel` both resolve the acting actor
@@ -181,36 +305,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`
 

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

@@ -219,12 +219,22 @@ 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. */
@@ -267,15 +277,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;
     /**
@@ -441,17 +456,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

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

@@ -219,12 +219,22 @@ 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. */
@@ -267,15 +277,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;
     /**
@@ -441,17 +456,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

package/dist/durable/index.cjs

@@ -953,7 +953,7 @@ var AgentDepsFactory2 = class {
       } : {},
       registry: this.registry,
       promptContributors: this.promptContributors,
-      systemPrompt: definition?.systemPrompt ?? "You are a helpful assistant.",
+      systemPrompt: definition?.systemPrompt ?? this.options.systemPrompt ?? "You are a helpful assistant.",
       maxSteps: definition?.maxSteps ?? 8,
       ...definition?.maxDelegationDepth !== void 0 ? {
         maxDelegationDepth: definition.maxDelegationDepth
@@ -3822,6 +3822,93 @@ var LedgerQuotaStore = class {
   }
 };
 
+// src/resolver/anonymous-actor-resolver.ts
+var import_node_crypto2 = require("crypto");
+var TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+var MINTED = /* @__PURE__ */ Symbol("nestjs-agent:anonymous-token");
+function readCookie(req, name) {
+  const header = req.headers?.cookie;
+  const raw = Array.isArray(header) ? header.join("; ") : header;
+  if (raw === void 0) return void 0;
+  for (const pair of raw.split(";")) {
+    const index = pair.indexOf("=");
+    if (index === -1) continue;
+    if (pair.slice(0, index).trim() === name) {
+      try {
+        return decodeURIComponent(pair.slice(index + 1).trim());
+      } catch {
+        return void 0;
+      }
+    }
+  }
+  return void 0;
+}
+__name(readCookie, "readCookie");
+function isHttps(req) {
+  if (req.secure === true) return true;
+  const forwarded = req.headers?.["x-forwarded-proto"];
+  const proto = Array.isArray(forwarded) ? forwarded[0] : forwarded;
+  return proto?.split(",")[0]?.trim() === "https";
+}
+__name(isHttps, "isHttps");
+var AnonymousActorResolver = class {
+  static {
+    __name(this, "AnonymousActorResolver");
+  }
+  options;
+  cookieName;
+  roles;
+  constructor(options = {}) {
+    this.options = options;
+    this.cookieName = options.cookieName ?? "agent_anon";
+    this.roles = options.roles ?? [
+      "anonymous"
+    ];
+  }
+  resolve(request) {
+    const req = typeof request === "object" && request !== null ? request : {};
+    let token = req[MINTED] ?? readCookie(req, this.cookieName);
+    if (token === void 0 || !TOKEN_PATTERN.test(token)) {
+      token = (0, import_node_crypto2.randomBytes)(32).toString("base64url");
+      req[MINTED] = token;
+      this.setCookie(req, token);
+    }
+    const digest = (0, import_node_crypto2.createHash)("sha256").update(token).digest("base64url").slice(0, 32);
+    return {
+      id: `anon:${digest}`,
+      roles: [
+        ...this.roles
+      ]
+    };
+  }
+  setCookie(req, token) {
+    const res = req.res;
+    if (res?.setHeader === void 0 || res.headersSent === true) return;
+    const sameSite = this.options.sameSite ?? "lax";
+    const secureOption = this.options.secure ?? "auto";
+    const secure = sameSite === "none" || (secureOption === "auto" ? isHttps(req) : secureOption);
+    const maxAge = Math.round((this.options.maxAgeDays ?? 365) * 24 * 60 * 60);
+    const cookie = [
+      `${this.cookieName}=${token}`,
+      `Path=${this.options.path ?? "/"}`,
+      `Max-Age=${maxAge}`,
+      "HttpOnly",
+      `SameSite=${sameSite === "none" ? "None" : sameSite === "strict" ? "Strict" : "Lax"}`,
+      ...secure ? [
+        "Secure"
+      ] : []
+    ].join("; ");
+    const existing = res.getHeader?.("Set-Cookie");
+    const list = Array.isArray(existing) ? existing.map(String) : existing !== void 0 ? [
+      String(existing)
+    ] : [];
+    res.setHeader("Set-Cookie", [
+      ...list,
+      cookie
+    ]);
+  }
+};
+
 // src/runner/inline-agent-runner.ts
 var import_nestjs_agent_core25 = require("@dudousxd/nestjs-agent-core");
 var import_common22 = require("@nestjs/common");
@@ -4296,7 +4383,51 @@ function _ts_decorate23(decorators, target, key, desc) {
 }
 __name(_ts_decorate23, "_ts_decorate");
 var DEFAULT_PATH = "agent";
-function sharedProviders(durable, includeStore) {
+var logger = new import_common23.Logger("AgentModule");
+function externalStoreWrapper(modules) {
+  for (const module2 of modules.values()) {
+    if (module2.metatype === AgentModule) continue;
+    const wrapper = module2.providers.get(import_nestjs_agent_core27.AGENT_STORE);
+    if (wrapper !== void 0) return wrapper;
+  }
+  return void 0;
+}
+__name(externalStoreWrapper, "externalStoreWrapper");
+function forwardingStore(wrapper) {
+  const target = /* @__PURE__ */ __name(() => {
+    const instance = wrapper.instance;
+    if (instance === void 0 || instance === null) {
+      throw new Error("AgentModule: the AGENT_STORE bound by another module is not ready yet");
+    }
+    return instance;
+  }, "target");
+  return new Proxy({}, {
+    get(_, property) {
+      const store = target();
+      const value = store[property];
+      return typeof value === "function" ? value.bind(store) : value;
+    },
+    has(_, property) {
+      return property in target();
+    }
+  });
+}
+__name(forwardingStore, "forwardingStore");
+function resolveStore(options, modules) {
+  if (options.store !== void 0) return options.store;
+  const external = externalStoreWrapper(modules);
+  if (external !== void 0) return forwardingStore(external);
+  logger.warn("No `store` configured and no store module imported \u2014 using the in-memory store. Threads are lost on restart and not shared between processes: not for production. Pass `store`, or import a store module (e.g. MikroOrmAgentStoreModule.forFeature()).");
+  return new import_nestjs_agent_core27.InMemoryAgentStore();
+}
+__name(resolveStore, "resolveStore");
+function resolveCatalog(options) {
+  if (options.models !== void 0) return options.models;
+  const carried = options.model.catalog;
+  return carried !== void 0 && typeof carried.list === "function" ? carried : void 0;
+}
+__name(resolveCatalog, "resolveCatalog");
+function sharedProviders(durable) {
   const providers = [
     {
       provide: import_nestjs_agent_core27.AGENT_TOOL_REGISTRY,
@@ -4354,7 +4485,11 @@ function sharedProviders(durable, includeStore) {
     },
     {
       provide: import_nestjs_agent_core27.AGENT_ACTOR_RESOLVER,
-      useFactory: /* @__PURE__ */ __name((options) => options.actorResolver, "useFactory"),
+      useFactory: /* @__PURE__ */ __name((options) => {
+        if (options.actorResolver !== void 0) return options.actorResolver;
+        logger.warn("No `actorResolver` configured \u2014 the agent endpoints are PUBLIC: every browser gets its own anonymous identity (an HttpOnly cookie). Set `actorResolver: requestUserActorResolver()` (or your own) to require login.");
+        return new AnonymousActorResolver();
+      }, "useFactory"),
       inject: [
         import_nestjs_agent_core27.AGENT_OPTIONS
       ]
@@ -4388,7 +4523,7 @@ function sharedProviders(durable, includeStore) {
     },
     {
       provide: import_nestjs_agent_core27.AGENT_MODEL_CATALOG,
-      useFactory: /* @__PURE__ */ __name((o) => o.models, "useFactory"),
+      useFactory: /* @__PURE__ */ __name((o) => resolveCatalog(o), "useFactory"),
       inject: [
         import_nestjs_agent_core27.AGENT_OPTIONS
       ]
@@ -4413,15 +4548,14 @@ function sharedProviders(durable, includeStore) {
       useExisting: AgentApprovalPortAdapter
     }
   ];
-  if (includeStore) {
-    providers.push({
-      provide: import_nestjs_agent_core27.AGENT_STORE,
-      useFactory: /* @__PURE__ */ __name((o) => o.store, "useFactory"),
-      inject: [
-        import_nestjs_agent_core27.AGENT_OPTIONS
-      ]
-    });
-  }
+  providers.push({
+    provide: import_nestjs_agent_core27.AGENT_STORE,
+    useFactory: /* @__PURE__ */ __name((o, modules) => resolveStore(o, modules), "useFactory"),
+    inject: [
+      import_nestjs_agent_core27.AGENT_OPTIONS,
+      import_core4.ModulesContainer
+    ]
+  });
   if (durable) {
     providers.push({
       provide: import_nestjs_agent_core27.AGENT_RUNNER,
@@ -4447,7 +4581,7 @@ function sharedProviders(durable, includeStore) {
   return providers;
 }
 __name(sharedProviders, "sharedProviders");
-function exportsFor(includeStore) {
+function exportsFor() {
   return [
     import_nestjs_agent_core27.AGENT_OPTIONS,
     import_nestjs_agent_core27.AGENT_TOOL_REGISTRY,
@@ -4456,9 +4590,7 @@ function exportsFor(includeStore) {
     import_nestjs_agent_core27.AGENT_ROLES_POLICY,
     import_nestjs_agent_core27.AGENT_ACTOR_RESOLVER,
     import_nestjs_agent_core27.AGENT_MODEL,
-    ...includeStore ? [
-      import_nestjs_agent_core27.AGENT_STORE
-    ] : [],
+    import_nestjs_agent_core27.AGENT_STORE,
     import_nestjs_agent_core27.AGENT_QUOTA_STORE,
     import_nestjs_agent_core27.AGENT_MODEL_CATALOG,
     import_nestjs_agent_core27.AGENT_QUOTA_PROVIDER,
@@ -4529,7 +4661,6 @@ var AgentModule = class _AgentModule {
   }
   static forRoot(options) {
     const path = options.path ?? DEFAULT_PATH;
-    const includeStore = options.store !== void 0;
     applyGuards(options.guards);
     return {
       module: _AgentModule,
@@ -4544,15 +4675,14 @@ var AgentModule = class _AgentModule {
           provide: import_nestjs_agent_core27.AGENT_OPTIONS,
           useValue: options
         },
-        ...sharedProviders(options.durable ?? false, includeStore),
+        ...sharedProviders(options.durable ?? false),
         ...guardProviders(options.guards)
       ],
-      exports: exportsFor(includeStore)
+      exports: exportsFor()
     };
   }
   static forRootAsync(options) {
     const path = options.path ?? DEFAULT_PATH;
-    const includeStore = options.externalStore !== true;
     applyGuards(options.guards);
     return {
       module: _AgentModule,
@@ -4579,10 +4709,10 @@ var AgentModule = class _AgentModule {
           }), "useFactory"),
           inject: options.inject ?? []
         },
-        ...sharedProviders(options.durable ?? false, includeStore),
+        ...sharedProviders(options.durable ?? false),
         ...guardProviders(options.guards)
       ],
-      exports: exportsFor(includeStore)
+      exports: exportsFor()
     };
   }
 };