@dudousxd/nestjs-agent 1.19.2 → 1.20.0

package/dist/index.cjs

@@ -74,6 +74,7 @@ __export(index_exports, {
   requestUserActorResolver: () => requestUserActorResolver,
   resolveSkillsConfig: () => resolveSkillsConfig,
   skillScope: () => skillScope,
+  threadPersona: () => threadPersona,
   toolNameFromClass: () => toolNameFromClass,
   utcDay: () => utcDay
 });
@@ -185,8 +186,64 @@ var AgentDepsFactory2 = class {
       ...delegated
     ];
   }
+  /**
+  * 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) {
+    if (this.agents.has(name)) {
+      return {
+        agentName: name
+      };
+    }
+    const alias = (0, import_nestjs_agent_core.resolvePersonaAlias)(this.agents.list(), name);
+    return alias === void 0 ? {
+      agentName: name
+    } : {
+      agentName: alias.agent,
+      persona: alias.persona
+    };
+  }
+  /** `agentName`'s personas as a picker reads them. Empty when it declares none. */
+  personaCatalog(agentName) {
+    return (this.agents.get(agentName)?.personas ?? []).map(import_nestjs_agent_core.personaCatalogEntry);
+  }
+  /** The persona `agentName` runs under when nothing names one. Undefined → none. */
+  defaultPersona(agentName) {
+    return this.agents.get(agentName)?.defaultPersona;
+  }
+  /**
+  * 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) {
+    const definition = this.agents.get(args.agentName);
+    if (args.requested !== void 0) {
+      if ((0, import_nestjs_agent_core.findPersona)(definition, args.requested) === void 0) {
+        throw new import_common.BadRequestException({
+          statusCode: 400,
+          code: "persona_not_found",
+          message: `agent "${args.agentName}" has no persona "${args.requested}"`
+        });
+      }
+      return args.requested;
+    }
+    const pinned = args.threadPersona ?? void 0;
+    if (pinned !== void 0 && (0, import_nestjs_agent_core.findPersona)(definition, pinned) !== void 0) {
+      return pinned;
+    }
+    return definition?.defaultPersona;
+  }
   forAgent(agentName) {
     const name = agentName ?? this.defaultAgentName();
+    if (agentName !== void 0 && !this.agents.has(agentName)) {
+      const alias = (0, import_nestjs_agent_core.resolvePersonaAlias)(this.agents.list(), agentName);
+      const persona = alias === void 0 ? void 0 : (0, import_nestjs_agent_core.findPersona)(this.agents.get(alias.agent), alias.persona);
+      if (alias !== void 0 && persona !== void 0) {
+        return this.withPersona(this.forAgent(alias.agent), persona);
+      }
+    }
     const definition = this.agents.get(name);
     const toolAllowList = this.effectiveTools(definition);
     const followUpsCount = this.followUpsCount();
@@ -251,6 +308,9 @@ var AgentDepsFactory2 = class {
       ...toolAllowList !== void 0 ? {
         toolAllowList
       } : {},
+      ...definition?.personas !== void 0 ? {
+        personas: definition.personas
+      } : {},
       ...this.options.toolTimeoutMs !== void 0 ? {
         toolTimeoutMs: this.options.toolTimeoutMs
       } : {},
@@ -269,6 +329,45 @@ var AgentDepsFactory2 = class {
     };
   }
   /**
+  * 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.
+  */
+  withPersona(deps, persona) {
+    const base = deps.systemPrompt;
+    const ref = {
+      id: persona.id,
+      label: persona.label
+    };
+    const resolve = /* @__PURE__ */ __name(async (prompt, ctx) => typeof prompt === "function" ? prompt(ctx) : prompt, "resolve");
+    const own = persona.systemPrompt;
+    const systemPrompt = /* @__PURE__ */ __name(async (ctx) => {
+      const scoped = {
+        ...ctx,
+        persona: ref
+      };
+      if (own === void 0) {
+        return resolve(base, scoped);
+      }
+      const basePrompt = typeof own === "function" ? await resolve(base, scoped) : void 0;
+      return resolve(own, {
+        ...scoped,
+        ...basePrompt !== void 0 ? {
+          basePrompt
+        } : {}
+      });
+    }, "systemPrompt");
+    const toolAllowList = (0, import_nestjs_agent_core.intersectAllowLists)(deps.toolAllowList, persona.allowedTools);
+    return {
+      ...deps,
+      systemPrompt,
+      ...toolAllowList !== void 0 ? {
+        toolAllowList
+      } : {}
+    };
+  }
+  /**
   * 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
   * `history` window. Undefined → unbounded, the behaviour of a module that configures none.
@@ -371,6 +470,18 @@ __name(childSinkWriter, "childSinkWriter");
 // src/queue/chat-queue.service.ts
 var import_nestjs_agent_core3 = require("@dudousxd/nestjs-agent-core");
 var import_common2 = require("@nestjs/common");
+
+// src/thread-persona.ts
+async function threadPersona(store, threadId) {
+  const projecting = store;
+  if (typeof projecting.personaForThread === "function") {
+    return projecting.personaForThread(threadId);
+  }
+  return (await store.getThread(threadId))?.persona ?? null;
+}
+__name(threadPersona, "threadPersona");
+
+// src/queue/chat-queue.service.ts
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -407,18 +518,20 @@ var ChatQueueService = class _ChatQueueService {
   quotaProvider;
   options;
   staging;
+  deps;
   logger = new import_common2.Logger(_ChatQueueService.name);
   /**
   * 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.
   */
   starting = /* @__PURE__ */ new Set();
-  constructor(store, sink, quotaProvider, options, staging) {
+  constructor(store, sink, quotaProvider, options, staging, deps) {
     this.store = store;
     this.sink = sink;
     this.quotaProvider = quotaProvider;
     this.options = options;
     this.staging = staging;
+    this.deps = deps;
   }
   /** Whether the bound store can hold a queue. Without one, a busy thread is not queued. */
   get supported() {
@@ -716,13 +829,17 @@ var ChatQueueService = class _ChatQueueService {
   */
   async inputFor(message) {
     const attachments = await this.freshAttachments(message.actor, message.attachments ?? []);
+    const { agentName, persona } = await this.targetFor(message);
     return {
       threadId: message.threadId,
       actor: message.actor,
       userText: message.content,
       day: utcDay(),
-      ...message.agentName !== void 0 ? {
-        agentName: message.agentName
+      ...agentName !== void 0 ? {
+        agentName
+      } : {},
+      ...persona !== void 0 ? {
+        persona
       } : {},
       ...attachments.length > 0 ? {
         attachments
@@ -735,6 +852,37 @@ var ChatQueueService = class _ChatQueueService {
       } : {}
     };
   }
+  /**
+  * 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.
+  */
+  async targetFor(message) {
+    const deps = this.deps;
+    if (message.persona !== void 0 || deps === void 0 || message.agentName === void 0) {
+      return {
+        ...message.agentName !== void 0 ? {
+          agentName: message.agentName
+        } : {},
+        ...message.persona !== void 0 ? {
+          persona: message.persona
+        } : {}
+      };
+    }
+    const target = deps.resolveAgent(message.agentName);
+    const hasPersonas = deps.personaCatalog(target.agentName).length > 0;
+    const persona = target.persona ?? (hasPersonas ? deps.resolvePersona({
+      agentName: target.agentName,
+      threadPersona: await threadPersona(this.store, message.threadId)
+    }) : void 0);
+    return {
+      agentName: target.agentName,
+      ...persona !== void 0 ? {
+        persona
+      } : {}
+    };
+  }
   async freshAttachments(actor, attachments) {
     const staging = this.staging;
     if (attachments.length === 0 || staging === void 0 || typeof staging.resolve !== "function") {
@@ -762,13 +910,16 @@ ChatQueueService = _ts_decorate2([
   _ts_param2(3, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_OPTIONS)),
   _ts_param2(4, (0, import_common2.Optional)()),
   _ts_param2(4, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_ATTACHMENT_STAGING)),
+  _ts_param2(5, (0, import_common2.Optional)()),
+  _ts_param2(5, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_DEPS_FACTORY)),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof AgentStore === "undefined" ? Object : AgentStore,
     typeof TokenStreamSink === "undefined" ? Object : TokenStreamSink,
     typeof QuotaProvider === "undefined" ? Object : QuotaProvider,
     typeof Pick === "undefined" ? Object : Pick,
-    typeof AttachmentStagingStore === "undefined" ? Object : AttachmentStagingStore
+    typeof AttachmentStagingStore === "undefined" ? Object : AttachmentStagingStore,
+    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory
   ])
 ], ChatQueueService);
 function pauseReasonFor(outcome, head) {
@@ -1022,7 +1173,9 @@ var AgentService = class {
   */
   async send(params) {
     await this.assertWithinQuota(params.actor);
-    const agentName = await this.resolveAgentName(params.agentName, params.threadId);
+    const target = this.deps.resolveAgent(await this.resolveAgentName(params.agentName, params.threadId));
+    const agentName = target.agentName;
+    const persona = await this.resolvePersona(agentName, params.personaId ?? target.persona, params.threadId);
     const model = await this.resolveModel(params.actor, agentName, params.model, params.threadId);
     const attachments = await this.resolveAttachments(params.actor, params.attachments ?? []);
     let threadId = params.threadId;
@@ -1037,11 +1190,17 @@ var AgentService = class {
         } : {},
         ...params.newThreadId !== void 0 ? {
           id: params.newThreadId
+        } : {},
+        ...params.personaId !== void 0 ? {
+          persona: params.personaId
         } : {}
       });
       threadId = created.id;
     } else {
       await this.assertOwnsThread(params.actor, threadId);
+      if (params.personaId !== void 0) {
+        await this.pinThreadPersona(threadId, params.personaId);
+      }
     }
     const input = {
       threadId,
@@ -1049,6 +1208,9 @@ var AgentService = class {
       userText: params.message,
       day: utcDay(),
       agentName,
+      ...persona !== void 0 ? {
+        persona
+      } : {},
       ...params.regenerate === true ? {
         regenerate: true
       } : {},
@@ -1135,6 +1297,9 @@ var AgentService = class {
       ...input.agentName !== void 0 ? {
         agentName: input.agentName
       } : {},
+      ...input.persona !== void 0 ? {
+        persona: input.persona
+      } : {},
       ...input.model !== void 0 ? {
         model: input.model
       } : {},
@@ -1529,16 +1694,22 @@ var AgentService = class {
   async updateThread(actor, threadId, patch) {
     const title = patch.title !== void 0 ? this.validateTitle(patch.title) : void 0;
     await this.assertOwnsThread(actor, threadId);
-    if (patch.defaultAgent === void 0 && patch.model === void 0) {
+    if (patch.defaultAgent === void 0 && patch.model === void 0 && patch.persona === void 0) {
       if (title !== void 0) {
         await this.store.setTitle(threadId, title);
       }
       return;
     }
     if (this.store.updateThread === void 0) {
-      throw new import_common4.NotImplementedException("Setting a thread's defaultAgent or model requires an AgentStore that implements updateThread(); the bound store does not support it.");
+      throw new import_common4.NotImplementedException("Setting a thread's defaultAgent, model or persona requires an AgentStore that implements updateThread(); the bound store does not support it.");
     }
     const model = patch.model === void 0 || patch.model === null ? patch.model : await this.assertModelAllowed(actor, patch.defaultAgent ?? await this.resolveAgentName(void 0, threadId), patch.model);
+    if (patch.persona !== void 0 && patch.persona !== null) {
+      this.deps.resolvePersona({
+        agentName: this.deps.resolveAgent(patch.defaultAgent ?? await this.resolveAgentName(void 0, threadId)).agentName,
+        requested: patch.persona
+      });
+    }
     await this.store.updateThread(threadId, {
       ...title !== void 0 ? {
         title
@@ -1548,9 +1719,39 @@ var AgentService = class {
       } : {},
       ...model !== void 0 ? {
         model
+      } : {},
+      ...patch.persona !== void 0 ? {
+        persona: patch.persona
       } : {}
     });
   }
+  /**
+  * 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.
+  */
+  async resolvePersona(agentName, requested, threadId) {
+    const needsThread = requested === void 0 && threadId !== void 0 && this.deps.personaCatalog(agentName).length > 0;
+    return this.deps.resolvePersona({
+      agentName,
+      ...requested !== void 0 ? {
+        requested
+      } : {},
+      ...needsThread ? {
+        threadPersona: await threadPersona(this.store, threadId)
+      } : {}
+    });
+  }
+  /** Pin `persona` on the thread when it is not already — a no-op on a store that cannot. */
+  async pinThreadPersona(threadId, persona) {
+    if (this.store.updateThread === void 0) {
+      return;
+    }
+    if (await threadPersona(this.store, threadId) !== persona) {
+      await this.store.updateThread(threadId, {
+        persona
+      });
+    }
+  }
   validateTitle(title) {
     const trimmed = title.trim();
     if (trimmed.length === 0) {
@@ -1596,6 +1797,7 @@ var AgentService = class {
       ...thread,
       defaultAgent: thread.defaultAgent ?? null,
       model: thread.model ?? null,
+      persona: thread.persona ?? null,
       activeRunId: await this.store.activeRunForThread?.(thread.id) ?? thread.activeRunId ?? null
     };
   }
@@ -1997,13 +2199,22 @@ var AgentsController = class {
   }
   list() {
     const defaultAgentName = this.depsFactory.defaultAgentName();
-    return this.agents.list().map((definition) => ({
-      name: definition.name,
-      description: definition.description ?? "",
-      ...definition.name === defaultAgentName ? {
-        isDefault: true
-      } : {}
-    }));
+    return this.agents.list().map((definition) => {
+      const personas = this.depsFactory.personaCatalog(definition.name);
+      return {
+        name: definition.name,
+        description: definition.description ?? "",
+        ...definition.name === defaultAgentName ? {
+          isDefault: true
+        } : {},
+        ...personas.length > 0 ? {
+          personas
+        } : {},
+        ...definition.defaultPersona !== void 0 ? {
+          defaultPersona: definition.defaultPersona
+        } : {}
+      };
+    });
   }
 };
 _ts_decorate5([
@@ -2273,6 +2484,9 @@ var ChatController = class {
       ...body.agent !== void 0 ? {
         agentName: body.agent
       } : {},
+      ...typeof body.persona === "string" && body.persona.length > 0 ? {
+        personaId: body.persona
+      } : {},
       ...attachments.length > 0 ? {
         attachments
       } : {},
@@ -3272,6 +3486,9 @@ var ThreadsController = class {
       } : {},
       ..."model" in body ? {
         model: body.model ?? null
+      } : {},
+      ..."persona" in body ? {
+        persona: body.persona ?? null
       } : {}
     });
     return {
@@ -3785,6 +4002,7 @@ var AgentDiscoveryService = class _AgentDiscoveryService {
       }
       this.collectContributors(instance);
     }
+    this.assertPersonas(this.registry.list());
   }
   /** Build the internal {@link AgentDefinition} from an `@Agent` instance and its options. */
   definitionFrom(instance, meta) {
@@ -3828,10 +4046,48 @@ var AgentDiscoveryService = class _AgentDiscoveryService {
       } : {},
       ...meta.handoff !== void 0 ? {
         delegatesTo: this.handoffEdges(meta)
+      } : {},
+      ...meta.personas !== void 0 ? {
+        personas: meta.personas
+      } : {},
+      ...meta.defaultPersona !== void 0 ? {
+        defaultPersona: meta.defaultPersona
       } : {}
     };
   }
   /**
+  * 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).
+  */
+  assertPersonas(definitions) {
+    const agentNames = new Set(definitions.map((definition) => definition.name));
+    const aliasOwner = /* @__PURE__ */ new Map();
+    for (const definition of definitions) {
+      const ids = /* @__PURE__ */ new Set();
+      for (const persona of definition.personas ?? []) {
+        if (ids.has(persona.id)) {
+          throw new Error(`Agent "${definition.name}" declares persona "${persona.id}" twice.`);
+        }
+        ids.add(persona.id);
+        for (const alias of persona.aliases ?? []) {
+          const owner = `${definition.name}/${persona.id}`;
+          if (agentNames.has(alias)) {
+            throw new Error(`Persona ${owner} claims the alias "${alias}", which is a registered agent's name.`);
+          }
+          const previous = aliasOwner.get(alias);
+          if (previous !== void 0) {
+            throw new Error(`Personas ${previous} and ${owner} both claim the alias "${alias}".`);
+          }
+          aliasOwner.set(alias, owner);
+        }
+      }
+      if (definition.defaultPersona !== void 0 && !ids.has(definition.defaultPersona)) {
+        throw new Error(`Agent "${definition.name}" names "${definition.defaultPersona}" as its default persona, but declares no persona with that id.`);
+      }
+    }
+  }
+  /**
   * 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
   * rather than an always-object form, so a definition an older host built by hand still reads.
@@ -5425,6 +5681,9 @@ var AgUiRunHandler = class {
       ...forwarded.agent !== void 0 ? {
         agentName: forwarded.agent
       } : {},
+      ...forwarded.persona !== void 0 ? {
+        personaId: forwarded.persona
+      } : {},
       ...forwarded.model !== void 0 ? {
         model: forwarded.model
       } : {},
@@ -5740,6 +5999,7 @@ __reExport(index_exports, require("@dudousxd/nestjs-agent-core"), module.exports
   requestUserActorResolver,
   resolveSkillsConfig,
   skillScope,
+  threadPersona,
   toolNameFromClass,
   utcDay,
   ...require("@dudousxd/nestjs-agent-core")