@dudousxd/nestjs-agent 1.19.2 → 1.20.0

package/README.md

@@ -156,6 +156,8 @@ per-message cap — so a client never repeats them.
 it leaves media with nothing pointing at it. Two optional methods make that findable — `list` on
 your `AttachmentStagingStore` (you stored the bytes, so only you can enumerate them) and
 `referencedMediaIds` on your `AgentStore` (only it can see which media a live message carries).
+A message waiting in a thread's queue — sent while a turn ran, or into a paused queue — counts as
+live: its files are kept until it runs, is removed, or has its attachments edited away.
 
 ```ts
 // a job the host runs; nothing here is reachable over HTTP

package/dist/{chat-queue.service-CKZkjlMK.d.cts → chat-queue.service-C0hr7dqx.d.cts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason, Actor } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason, Actor } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -24,6 +24,8 @@ interface AgentDeps {
     maxAgentAppearances?: number;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
+    /** The agent's personas (`@Agent({ personas })`) — read by the loop only for a run that names one. */
+    personas?: Persona[];
     /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
     toolTimeoutMs?: number;
     /**
@@ -534,7 +536,36 @@ declare class AgentDepsFactory {
      */
     defaultAgentName(): string;
     private effectiveTools;
+    /**
+     * The agent a name stands for: itself when it is a registered agent (or unknown — the bare
+     * assistant), else the agent whose persona took the name over (`Persona.aliases`) and that persona.
+     */
+    resolveAgent(name: string): {
+        agentName: string;
+        persona?: string;
+    };
+    /** `agentName`'s personas as a picker reads them. Empty when it declares none. */
+    personaCatalog(agentName: string): PersonaCatalogEntry[];
+    /** The persona `agentName` runs under when nothing names one. Undefined → none. */
+    defaultPersona(agentName: string): string | undefined;
+    /**
+     * The persona a turn of `agentName` runs under, most specific first: the one the send names
+     * (refused with `400 persona_not_found` when the agent does not declare it), else the thread's
+     * pinned one when this agent declares it, else the agent's default. Undefined → none.
+     */
+    resolvePersona(args: {
+        agentName: string;
+        requested?: string;
+        threadPersona?: string | null;
+    }): string | undefined;
     forAgent(agentName?: string): AgentDeps;
+    /**
+     * A persona baked into an agent's deps — how a run journaled under an agent name that a persona
+     * has since taken over (`Persona.aliases`) is served. That run names no persona of its own (it
+     * predates them, and its input cannot change), so the persona applies the way the old agent's own
+     * config did: as config, re-read on every replay, with no checkpoint of its own.
+     */
+    private withPersona;
     /**
      * The ceiling on how much of a thread this agent's turns carry, most specific wins: the agent's
      * own `@Agent({ history })`, else a module-wide custom `historyPolicy`, else the module-wide
@@ -591,13 +622,14 @@ declare class ChatQueueService {
     private readonly quotaProvider?;
     private readonly options?;
     private readonly staging?;
+    private readonly deps?;
     private readonly logger;
     /**
      * Runs this process claimed a thread for and has not handed to a runner yet. A holder in here is
      * alive whatever the runner says — it simply has not registered the run yet.
      */
     private readonly starting;
-    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined);
+    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined, deps?: AgentDepsFactory | undefined);
     /** Whether the bound store can hold a queue. Without one, a busy thread is not queued. */
     get supported(): boolean;
     /** The bound store as a queue store, or a 501 naming what is missing. */
@@ -673,6 +705,13 @@ declare class ChatQueueService {
      * waited. An attachment the staging store no longer resolves keeps its stored url.
      */
     private inputFor;
+    /**
+     * The agent and persona a queued message starts as. A message carries the persona its send
+     * resolved; one that carries none — queued before personas existed, or by a host that sets none —
+     * resolves it now, exactly as a send would: an agent name a persona took over, then the thread's
+     * pinned persona, then the agent's default. Never refused here: nobody is waiting on a 400.
+     */
+    private targetFor;
     private freshAttachments;
 }
 

package/dist/{chat-queue.service-CKZkjlMK.d.ts → chat-queue.service-C0hr7dqx.d.ts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason, Actor } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason, Actor } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -24,6 +24,8 @@ interface AgentDeps {
     maxAgentAppearances?: number;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
+    /** The agent's personas (`@Agent({ personas })`) — read by the loop only for a run that names one. */
+    personas?: Persona[];
     /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
     toolTimeoutMs?: number;
     /**
@@ -534,7 +536,36 @@ declare class AgentDepsFactory {
      */
     defaultAgentName(): string;
     private effectiveTools;
+    /**
+     * The agent a name stands for: itself when it is a registered agent (or unknown — the bare
+     * assistant), else the agent whose persona took the name over (`Persona.aliases`) and that persona.
+     */
+    resolveAgent(name: string): {
+        agentName: string;
+        persona?: string;
+    };
+    /** `agentName`'s personas as a picker reads them. Empty when it declares none. */
+    personaCatalog(agentName: string): PersonaCatalogEntry[];
+    /** The persona `agentName` runs under when nothing names one. Undefined → none. */
+    defaultPersona(agentName: string): string | undefined;
+    /**
+     * The persona a turn of `agentName` runs under, most specific first: the one the send names
+     * (refused with `400 persona_not_found` when the agent does not declare it), else the thread's
+     * pinned one when this agent declares it, else the agent's default. Undefined → none.
+     */
+    resolvePersona(args: {
+        agentName: string;
+        requested?: string;
+        threadPersona?: string | null;
+    }): string | undefined;
     forAgent(agentName?: string): AgentDeps;
+    /**
+     * A persona baked into an agent's deps — how a run journaled under an agent name that a persona
+     * has since taken over (`Persona.aliases`) is served. That run names no persona of its own (it
+     * predates them, and its input cannot change), so the persona applies the way the old agent's own
+     * config did: as config, re-read on every replay, with no checkpoint of its own.
+     */
+    private withPersona;
     /**
      * The ceiling on how much of a thread this agent's turns carry, most specific wins: the agent's
      * own `@Agent({ history })`, else a module-wide custom `historyPolicy`, else the module-wide
@@ -591,13 +622,14 @@ declare class ChatQueueService {
     private readonly quotaProvider?;
     private readonly options?;
     private readonly staging?;
+    private readonly deps?;
     private readonly logger;
     /**
      * Runs this process claimed a thread for and has not handed to a runner yet. A holder in here is
      * alive whatever the runner says — it simply has not registered the run yet.
      */
     private readonly starting;
-    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined);
+    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined, deps?: AgentDepsFactory | undefined);
     /** Whether the bound store can hold a queue. Without one, a busy thread is not queued. */
     get supported(): boolean;
     /** The bound store as a queue store, or a 501 naming what is missing. */
@@ -673,6 +705,13 @@ declare class ChatQueueService {
      * waited. An attachment the staging store no longer resolves keeps its stored url.
      */
     private inputFor;
+    /**
+     * The agent and persona a queued message starts as. A message carries the persona its send
+     * resolved; one that carries none — queued before personas existed, or by a host that sets none —
+     * resolves it now, exactly as a send would: an agent name a persona took over, then the thread's
+     * pinned persona, then the agent's default. Never refused here: nobody is waiting on a 400.
+     */
+    private targetFor;
     private freshAttachments;
 }