@dudousxd/nestjs-agent 1.9.0 → 1.11.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 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 { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-BRTBu0lV.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-BRTBu0lV.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';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
@@ -367,19 +367,27 @@ declare class AttachmentsController implements OnModuleInit {
 
 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 +428,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 +460,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
@@ -946,4 +962,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, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, 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, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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 { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-BRTBu0lV.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-BRTBu0lV.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';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
@@ -367,19 +367,27 @@ declare class AttachmentsController implements OnModuleInit {
 
 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 +428,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 +460,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
@@ -946,4 +962,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, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, 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, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };