@dudousxd/nestjs-agent 1.19.3 → 1.20.0

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;
 }
 

package/dist/durable/index.cjs

@@ -125,14 +125,21 @@ var AgentRunSteps = class {
     const tools = (0, import_nestjs_agent_core.withMemoryTool)({
       tools: (0, import_nestjs_agent_core.withSkillTool)({
         tools: (0, import_nestjs_agent_core.withAskTool)({
-          tools: await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList, {
-            ...input.threadId !== void 0 ? {
-              threadId: input.threadId
-            } : {},
-            ...input.agentName !== void 0 ? {
-              agentName: input.agentName
-            } : {}
-          }),
+          tools: await deps.registry.definitionsFor(
+            input.actor,
+            deps.rolesPolicy,
+            // The persona narrowing the loop journaled in `persona:resolve` rides the envelope:
+            // this worker's own persona config may already say something else.
+            (0, import_nestjs_agent_core.intersectAllowLists)(deps.toolAllowList, input.personaAllowedTools),
+            {
+              ...input.threadId !== void 0 ? {
+                threadId: input.threadId
+              } : {},
+              ...input.agentName !== void 0 ? {
+                agentName: input.agentName
+              } : {}
+            }
+          ),
           ask: deps.ask
         }),
         enabled: deps.skills !== void 0
@@ -205,7 +212,9 @@ var AgentRunSteps = class {
       toolType: input.toolType
     }, () => (0, import_nestjs_agent_core.invokeWithTransientRetry)(() => {
       ui.restart();
-      const invocation = deps.registry.invoke(input.toolName, input.input, ctx, deps.rolesPolicy);
+      const invocation = deps.registry.invoke(input.toolName, input.input, ctx, deps.rolesPolicy, input.allowedTools !== void 0 ? {
+        allowedTools: input.allowedTools
+      } : {});
       return input.timeoutMs !== void 0 ? (0, import_nestjs_agent_core.withToolTimeout)(invocation, input.timeoutMs, input.toolName) : invocation;
     }, transientRetry, {
       onRetry: /* @__PURE__ */ __name((attempt, error) => {
@@ -1218,8 +1227,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_core6.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_core6.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_core6.findPersona)(definition, args.requested) === void 0) {
+        throw new import_common5.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_core6.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_core6.resolvePersonaAlias)(this.agents.list(), agentName);
+      const persona = alias === void 0 ? void 0 : (0, import_nestjs_agent_core6.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();
@@ -1284,6 +1349,9 @@ var AgentDepsFactory2 = class {
       ...toolAllowList !== void 0 ? {
         toolAllowList
       } : {},
+      ...definition?.personas !== void 0 ? {
+        personas: definition.personas
+      } : {},
       ...this.options.toolTimeoutMs !== void 0 ? {
         toolTimeoutMs: this.options.toolTimeoutMs
       } : {},
@@ -1302,6 +1370,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_core6.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.
@@ -1382,6 +1489,18 @@ var import_common8 = require("@nestjs/common");
 // src/queue/chat-queue.service.ts
 var import_nestjs_agent_core8 = require("@dudousxd/nestjs-agent-core");
 var import_common6 = 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_decorate6(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") {
@@ -1418,18 +1537,20 @@ var ChatQueueService2 = class _ChatQueueService {
   quotaProvider;
   options;
   staging;
+  deps;
   logger = new import_common6.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() {
@@ -1727,13 +1848,17 @@ var ChatQueueService2 = 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
@@ -1746,6 +1871,37 @@ var ChatQueueService2 = 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") {
@@ -1773,13 +1929,16 @@ ChatQueueService2 = _ts_decorate6([
   _ts_param5(3, (0, import_common6.Inject)(import_nestjs_agent_core8.AGENT_OPTIONS)),
   _ts_param5(4, (0, import_common6.Optional)()),
   _ts_param5(4, (0, import_common6.Inject)(import_nestjs_agent_core8.AGENT_ATTACHMENT_STAGING)),
+  _ts_param5(5, (0, import_common6.Optional)()),
+  _ts_param5(5, (0, import_common6.Inject)(import_nestjs_agent_core8.AGENT_DEPS_FACTORY)),
   _ts_metadata5("design:type", Function),
   _ts_metadata5("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
   ])
 ], ChatQueueService2);
 function pauseReasonFor(outcome, head) {
@@ -2033,7 +2192,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;
@@ -2048,11 +2209,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,
@@ -2060,6 +2227,9 @@ var AgentService = class {
       userText: params.message,
       day: utcDay(),
       agentName,
+      ...persona !== void 0 ? {
+        persona
+      } : {},
       ...params.regenerate === true ? {
         regenerate: true
       } : {},
@@ -2146,6 +2316,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
       } : {},
@@ -2540,16 +2713,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_common8.NotImplementedException("Setting a thread's defaultAgent or model requires an AgentStore that implements updateThread(); the bound store does not support it.");
+      throw new import_common8.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
@@ -2559,9 +2738,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) {
@@ -2607,6 +2816,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
     };
   }
@@ -3008,13 +3218,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_decorate9([
@@ -3284,6 +3503,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
       } : {},
@@ -4283,6 +4505,9 @@ var ThreadsController = class {
       } : {},
       ..."model" in body ? {
         model: body.model ?? null
+      } : {},
+      ..."persona" in body ? {
+        persona: body.persona ?? null
       } : {}
     });
     return {
@@ -4778,6 +5003,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) {
@@ -4821,10 +5047,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.