@dudousxd/nestjs-agent 1.19.2 → 1.20.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-CKZkjlMK.cjs';
-export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, j as QueueSettleOutcome, k as QueuedTurn, l as QueuedTurnStarter, m as QuotaLimits, n as QuotaWindowLimits, o as delegateToolName, p as provideAgentTool, q as provideAgentTools, u as utcDay } from './chat-queue.service-CKZkjlMK.cjs';
-import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-C0hr7dqx.cjs';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, j as QueueSettleOutcome, k as QueuedTurn, l as QueuedTurnStarter, m as QuotaLimits, n as QuotaWindowLimits, o as delegateToolName, p as provideAgentTool, q as provideAgentTools, u as utcDay } from './chat-queue.service-C0hr7dqx.cjs';
+import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -45,6 +45,12 @@ interface ChatParams {
     message: string;
     threadId?: string;
     agentName?: string;
+    /**
+     * Run this turn under one of the agent's personas (`@Agent({ personas })`), and pin it on the
+     * thread so later sends that name none keep it. Refused (400 `persona_not_found`) unless the agent
+     * declares it. Omitted → the thread's pinned persona, else the agent's `defaultPersona`, else none.
+     */
+    personaId?: string;
     /**
      * Files attached to this message (image/PDF) for a vision-capable model, named by the `mediaId`
      * the upload returned. Only the id is read: the url, content type and name are resolved from the
@@ -293,6 +299,13 @@ declare class AgentService {
      * dropping the field.
      */
     updateThread(actor: Actor, threadId: string, patch: UpdateThreadInput): Promise<void>;
+    /**
+     * The persona this send runs under — see {@link AgentDepsFactory.resolvePersona}. The thread's
+     * pinned persona is read only when the send names none AND the agent has personas to pick from.
+     */
+    private resolvePersona;
+    /** Pin `persona` on the thread when it is not already — a no-op on a store that cannot. */
+    private pinThreadPersona;
     private validateTitle;
     /**
      * Agent-selection precedence for a `chat()` call with no explicit `agentName`: the thread's own
@@ -492,6 +505,19 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     }): Promise<void>;
 }
 
+/**
+ * A store that can answer a thread's pinned persona on its own, without materializing the thread —
+ * probed structurally, like `ThreadDefaultAgentReader`.
+ */
+interface ThreadPersonaReader {
+    personaForThread(threadId: string): Promise<string | null>;
+}
+/**
+ * The thread's pinned persona: one column when the store projects it ({@link ThreadPersonaReader}),
+ * else through the full read.
+ */
+declare function threadPersona(store: AgentStore, threadId: string): Promise<string | null>;
+
 /**
  * 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
@@ -744,6 +770,20 @@ interface AgentOptions {
      * module-wide setting.
      */
     ask?: boolean;
+    /**
+     * Named variants of THIS agent — a prompt and, optionally, a narrower tool allow-list — that a
+     * caller picks per send (`POST <base>/chat { persona }`) and that pin onto the thread. Everything
+     * else (model, access rules, handoffs, history) stays this agent's; a variant that needs those to
+     * differ is another `@Agent`.
+     *
+     * A persona's `systemPrompt` is static data. For a prompt built from injected services, leave it
+     * out and branch on `ctx.persona` in this class's `@SystemPrompt()` method instead.
+     *
+     * Omit → no personas, and nothing about a turn changes.
+     */
+    personas?: Persona[];
+    /** The persona a send runs under when neither it nor its thread names one. Omit → none. */
+    defaultPersona?: string;
 }
 declare const AGENT_METADATA: unique symbol;
 /** Marks a provider class as an agent. See {@link AgentOptions}. */
@@ -849,6 +889,12 @@ declare class AgentDiscoveryService implements OnModuleInit {
     onModuleInit(): void;
     /** Build the internal {@link AgentDefinition} from an `@Agent` instance and its options. */
     private definitionFrom;
+    /**
+     * Refuse to boot on a persona declaration that could only fail later, per request: a default that
+     * names no persona, an id declared twice, an alias two personas claim, or an alias that is a real
+     * agent's name (which would never be reached — a registered agent always wins).
+     */
+    private assertPersonas;
     /**
      * Resolve each handoff entry to an {@link AgentDelegation} — its target's registered name, plus
      * whether that edge detaches (skipping non-agent classes). A bare name is kept for a plain edge
@@ -1288,4 +1334,4 @@ declare class RunNotActiveException extends ConflictException {
     constructor(runId: string);
 }
 
-export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, agUiAdapter, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };
+export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, type ThreadPersonaReader, ToolsController, agUiAdapter, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, threadPersona, toolNameFromClass };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-CKZkjlMK.js';
-export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, j as QueueSettleOutcome, k as QueuedTurn, l as QueuedTurnStarter, m as QuotaLimits, n as QuotaWindowLimits, o as delegateToolName, p as provideAgentTool, q as provideAgentTools, u as utcDay } from './chat-queue.service-CKZkjlMK.js';
-import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-C0hr7dqx.js';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, j as QueueSettleOutcome, k as QueuedTurn, l as QueuedTurnStarter, m as QuotaLimits, n as QuotaWindowLimits, o as delegateToolName, p as provideAgentTool, q as provideAgentTools, u as utcDay } from './chat-queue.service-C0hr7dqx.js';
+import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -45,6 +45,12 @@ interface ChatParams {
     message: string;
     threadId?: string;
     agentName?: string;
+    /**
+     * Run this turn under one of the agent's personas (`@Agent({ personas })`), and pin it on the
+     * thread so later sends that name none keep it. Refused (400 `persona_not_found`) unless the agent
+     * declares it. Omitted → the thread's pinned persona, else the agent's `defaultPersona`, else none.
+     */
+    personaId?: string;
     /**
      * Files attached to this message (image/PDF) for a vision-capable model, named by the `mediaId`
      * the upload returned. Only the id is read: the url, content type and name are resolved from the
@@ -293,6 +299,13 @@ declare class AgentService {
      * dropping the field.
      */
     updateThread(actor: Actor, threadId: string, patch: UpdateThreadInput): Promise<void>;
+    /**
+     * The persona this send runs under — see {@link AgentDepsFactory.resolvePersona}. The thread's
+     * pinned persona is read only when the send names none AND the agent has personas to pick from.
+     */
+    private resolvePersona;
+    /** Pin `persona` on the thread when it is not already — a no-op on a store that cannot. */
+    private pinThreadPersona;
     private validateTitle;
     /**
      * Agent-selection precedence for a `chat()` call with no explicit `agentName`: the thread's own
@@ -492,6 +505,19 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     }): Promise<void>;
 }
 
+/**
+ * A store that can answer a thread's pinned persona on its own, without materializing the thread —
+ * probed structurally, like `ThreadDefaultAgentReader`.
+ */
+interface ThreadPersonaReader {
+    personaForThread(threadId: string): Promise<string | null>;
+}
+/**
+ * The thread's pinned persona: one column when the store projects it ({@link ThreadPersonaReader}),
+ * else through the full read.
+ */
+declare function threadPersona(store: AgentStore, threadId: string): Promise<string | null>;
+
 /**
  * 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
@@ -744,6 +770,20 @@ interface AgentOptions {
      * module-wide setting.
      */
     ask?: boolean;
+    /**
+     * Named variants of THIS agent — a prompt and, optionally, a narrower tool allow-list — that a
+     * caller picks per send (`POST <base>/chat { persona }`) and that pin onto the thread. Everything
+     * else (model, access rules, handoffs, history) stays this agent's; a variant that needs those to
+     * differ is another `@Agent`.
+     *
+     * A persona's `systemPrompt` is static data. For a prompt built from injected services, leave it
+     * out and branch on `ctx.persona` in this class's `@SystemPrompt()` method instead.
+     *
+     * Omit → no personas, and nothing about a turn changes.
+     */
+    personas?: Persona[];
+    /** The persona a send runs under when neither it nor its thread names one. Omit → none. */
+    defaultPersona?: string;
 }
 declare const AGENT_METADATA: unique symbol;
 /** Marks a provider class as an agent. See {@link AgentOptions}. */
@@ -849,6 +889,12 @@ declare class AgentDiscoveryService implements OnModuleInit {
     onModuleInit(): void;
     /** Build the internal {@link AgentDefinition} from an `@Agent` instance and its options. */
     private definitionFrom;
+    /**
+     * Refuse to boot on a persona declaration that could only fail later, per request: a default that
+     * names no persona, an id declared twice, an alias two personas claim, or an alias that is a real
+     * agent's name (which would never be reached — a registered agent always wins).
+     */
+    private assertPersonas;
     /**
      * Resolve each handoff entry to an {@link AgentDelegation} — its target's registered name, plus
      * whether that edge detaches (skipping non-agent classes). A bare name is kept for a plain edge
@@ -1288,4 +1334,4 @@ declare class RunNotActiveException extends ConflictException {
     constructor(runId: string);
 }
 
-export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, agUiAdapter, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };
+export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, type ThreadPersonaReader, ToolsController, agUiAdapter, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, threadPersona, toolNameFromClass };