@dudousxd/nestjs-agent 1.19.2 → 1.20.0

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) => {
@@ -282,12 +291,60 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
   store;
   runs;
   queue;
+  workflows;
   logger = new import_common2.Logger(_AgentRunWorkflow.name);
-  constructor(factory, store, runs, queue) {
+  constructor(factory, store, runs, queue, workflows) {
     this.factory = factory;
     this.store = store;
     this.runs = runs;
     this.queue = queue;
+    this.workflows = workflows;
+  }
+  /**
+  * Start a detached delegation as a TOP-LEVEL run, under an id derived from this run and the call.
+  *
+  * Not `ctx.startChild`, because the runtime treats a `spawn:` child as part of its parent: a Stop
+  * on the parent cascades to every run it spawned. A detached run is exactly the one the person did
+  * NOT ask to stop — they stopped the turn they were watching, and the work it handed off is meant
+  * to outlive that turn (it is meant to outlive it finishing, after all). Cascaded, it died parked
+  * on its approval, where its body never runs again, so nothing settled the delegation and the card
+  * said "started" for ever. The agent-level edge stays: the child's input still carries
+  * `parentRunId`, which is what the run rows record.
+  *
+  * Journaled as one `detach:<toolCallId>` localStep whose body runs outside the ambient workflow
+  * ctx (so the start goes to the engine and writes no position in this run). Its recorded result
+  * keeps a replay from starting it again, and a body re-run after a crash between the start and
+  * the checkpoint asks for the same id, which the runtime answers with the run it already has.
+  * The child is stamped with this run's namespace, as `ctx.startChild` would have stamped it, so an
+  * operator re-driving a tenant's turn does not move its delegate off that tenant's workers.
+  */
+  startDetached(ctx, toolCallId2, childInput) {
+    return stepOf(ctx)(`detach:${toolCallId2}`, async () => {
+      const workflows = this.workflows;
+      if (workflows === void 0) {
+        throw new Error("A detached delegation needs WorkflowService (DurableModule) to start its run, and none is bound.");
+      }
+      const childRunId = `${ctx.runId}.detached.${toolCallId2}`;
+      const namespace = await this.namespaceOf(ctx.runId);
+      try {
+        await workflows.start(_AgentRunWorkflow, childInput, childRunId, namespace !== void 0 ? {
+          namespace
+        } : void 0);
+      } catch (error) {
+        if (!(0, import_nestjs_durable_core2.isWorkflowControlFlowSignal)(error)) {
+          throw error;
+        }
+      }
+      return childRunId;
+    });
+  }
+  /** The namespace this run is stamped with, where the runtime can say. */
+  async namespaceOf(runId) {
+    try {
+      return (await this.runs?.getRunDetail(runId))?.run.namespace;
+    } catch {
+      return void 0;
+    }
   }
   /**
   * Move the thread past this settling turn — to the next queued message, started here as a
@@ -488,6 +545,10 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       //     OWN runId, and that is what `runForToolCall` answers with.
       //   - `deliverTo` instead. The parent's tool result is a receipt, so the answer needs an
       //     address of its own, and by the time it exists nobody is holding one.
+      //   - no runtime parent. A Stop on this turn must not reach the work it handed off, so the
+      //     run is started on its own (`startDetached`), not as a `spawn:` child. A run that
+      //     journaled the `spawn:` before this release replays it: `ctx.patched` answers false at a
+      //     position that already holds one.
       startAgent: /* @__PURE__ */ __name(async ({ agentName, task, toolCallId: toolCallId2 }) => {
         const subThreadId = await stepOf(ctx)(`subthread:${agentName}`, async () => {
           const thread = await this.store.createThread({
@@ -496,7 +557,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
           });
           return thread.id;
         });
-        const childRunId = await ctx.startChild(_AgentRunWorkflow, {
+        const childInput = {
           agentName,
           threadId: subThreadId,
           actor: input.actor,
@@ -509,9 +570,14 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
             threadId: input.threadId,
             toolCallId: toolCallId2
           }
-        });
+        };
+        if (!await ctx.patched("agent:detached-unlinked")) {
+          return {
+            runId: await ctx.startChild(_AgentRunWorkflow, childInput)
+          };
+        }
         return {
-          runId: childRunId
+          runId: await this.startDetached(ctx, toolCallId2, childInput)
         };
       }, "startAgent"),
       // The two long steps as engine-dispatched `ctx.step`s, so a turn isn't pinned to this
@@ -624,12 +690,14 @@ AgentRunWorkflow = _ts_decorate2([
   _ts_param2(2, (0, import_common2.Inject)(import_nestjs_durable2.RUN_GATEWAY)),
   _ts_param2(3, (0, import_common2.Optional)()),
   _ts_param2(3, (0, import_common2.Inject)(AGENT_CHAT_QUEUE)),
+  _ts_param2(4, (0, import_common2.Optional)()),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
     typeof AgentStore === "undefined" ? Object : AgentStore,
     typeof RunGateway === "undefined" ? Object : RunGateway,
-    typeof ChatQueueService === "undefined" ? Object : ChatQueueService
+    typeof ChatQueueService === "undefined" ? Object : ChatQueueService,
+    typeof import_nestjs_durable2.WorkflowService === "undefined" ? Object : import_nestjs_durable2.WorkflowService
   ])
 ], AgentRunWorkflow);
 function isSignalTimeout(error) {
@@ -750,6 +818,20 @@ function isThreadTurn(input) {
   return typeof input === "object" && input !== null && input.sinkRunId === void 0 && input.deliverTo === void 0;
 }
 __name(isThreadTurn, "isThreadTurn");
+function deliveryOf(input) {
+  if (typeof input !== "object" || input === null) {
+    return void 0;
+  }
+  const { deliverTo, agentName } = input;
+  if (typeof deliverTo !== "object" || deliverTo === null || typeof deliverTo.threadId !== "string" || typeof deliverTo.toolCallId !== "string") {
+    return void 0;
+  }
+  return {
+    delivery: deliverTo,
+    agent: typeof agentName === "string" ? agentName : "default"
+  };
+}
+__name(deliveryOf, "deliveryOf");
 var DurableAgentRunner = class _DurableAgentRunner {
   static {
     __name(this, "DurableAgentRunner");
@@ -829,11 +911,16 @@ var DurableAgentRunner = class _DurableAgentRunner {
   */
   async cancel(runId) {
     this.logger.log(`cancelling agent run ${runId}`);
-    const input = await this.inputOf(runId);
+    const detail = await this.detailOf(runId);
+    const input = detail?.run.input;
     const threadId = threadOfRun(input);
     await this.runs.cancel(runId, {
       compensate: true
     });
+    await this.settleCancelledDelegation(runId, input);
+    for (const childId of detail?.children ?? []) {
+      await this.settleCascadedDetached(childId);
+    }
     const writer = await this.sink.open(runId);
     if (threadId !== void 0) {
       if (this.queue?.supported === true && isThreadTurn(input)) {
@@ -864,7 +951,57 @@ var DurableAgentRunner = class _DurableAgentRunner {
     });
   }
   /**
-  * The input a run was started with (which thread it was streaming), or `undefined` where the gateway cannot say.
+  * Settle the delegation a DETACHED run was started for, once it has been stopped. A run parked on
+  * a human never runs its body again — the runtime settles it from outside — so the body's own
+  * `deliver:detached:unsettled` is not reached, and without this the card in the calling thread says
+  * "started" for ever. Settles once (see `settleUnsettledDelegation`), so a body that did observe
+  * the Stop and a run that had already answered are both left as they are. A no-op for any run
+  * that does not deliver into another thread.
+  */
+  async settleCancelledDelegation(runId, input) {
+    const target = deliveryOf(input);
+    if (target === void 0) {
+      return;
+    }
+    try {
+      await (0, import_nestjs_agent_core4.settleUnsettledDelegation)({
+        store: this.store,
+        delivery: target.delivery,
+        agent: target.agent,
+        runId,
+        status: "cancelled"
+      });
+    } catch (error) {
+      this.logger.error(`could not settle the delegation of cancelled run ${runId}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  /**
+  * A detached child the runtime cancelled along with its parent (a `spawn:` journaled before
+  * detached runs were started on their own): end it the way a Stop on its own id would have.
+  */
+  async settleCascadedDetached(childId) {
+    const child = await this.detailOf(childId);
+    const status = child?.run.status;
+    if (child === void 0 || deliveryOf(child.run.input) === void 0 || status !== "cancelled" && status !== "cancelling") {
+      return;
+    }
+    const subThreadId = threadOfRun(child.run.input);
+    if (subThreadId !== void 0) {
+      await (0, import_nestjs_agent_core4.releaseThreadRun)(this.store, subThreadId, childId);
+    }
+    await this.settleCancelledDelegation(childId, child.run.input);
+    const writer = await this.sink.open(childId);
+    await writer.write((0, import_nestjs_agent_core4.encodeStreamEvent)({
+      kind: "cancelled"
+    }));
+    await writer.end();
+    await this.store.recordRunEnd?.({
+      runId: childId,
+      status: "cancelled"
+    });
+  }
+  /**
+  * What the runtime recorded for a run — the input it was started with (which thread it was streaming), its status and the runs it spawned — or `undefined` where the gateway cannot say.
   *
   * A read failure answers `undefined` instead of propagating, the same posture `AgentRunWorkflow`
   * takes for its own cancel observation: failing to ask is not an answer worth failing a cancel
@@ -873,9 +1010,9 @@ var DurableAgentRunner = class _DurableAgentRunner {
   * with a subscriber holding a stream that never settles, from the one call whose entire job is to
   * make a run stop.
   */
-  async inputOf(runId) {
+  async detailOf(runId) {
     try {
-      return (await this.runs.getRunDetail(runId))?.run.input;
+      return await this.runs.getRunDetail(runId) ?? void 0;
     } catch {
       return void 0;
     }
@@ -1090,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();
@@ -1156,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
       } : {},
@@ -1174,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.
@@ -1254,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") {
@@ -1290,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() {
@@ -1599,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
@@ -1618,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") {
@@ -1645,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) {
@@ -1905,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;
@@ -1920,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,
@@ -1932,6 +2227,9 @@ var AgentService = class {
       userText: params.message,
       day: utcDay(),
       agentName,
+      ...persona !== void 0 ? {
+        persona
+      } : {},
       ...params.regenerate === true ? {
         regenerate: true
       } : {},
@@ -2018,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
       } : {},
@@ -2412,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
@@ -2431,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) {
@@ -2479,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
     };
   }
@@ -2880,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([
@@ -3156,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
       } : {},
@@ -4155,6 +4505,9 @@ var ThreadsController = class {
       } : {},
       ..."model" in body ? {
         model: body.model ?? null
+      } : {},
+      ..."persona" in body ? {
+        persona: body.persona ?? null
       } : {}
     });
     return {
@@ -4650,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) {
@@ -4693,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.