@dudousxd/nestjs-agent 1.19.2 → 1.20.0

package/dist/durable/index.js

@@ -3,7 +3,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 
 // src/durable/agent-run.workflow.ts
 import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, AGENT_STORE, RUN_ENDED_BEFORE_TOOL_CALL, RunCancelledError, agentFailureCode, encodeStreamEvent as encodeStreamEvent2, isReplayIntegrityError, publishAgentRunFailed, releaseThreadRun, runAgentLoop, settleAll, settleDeadRun, settleUnsettledDelegation, streamFailure } from "@dudousxd/nestjs-agent-core";
-import { RUN_GATEWAY, Workflow } from "@dudousxd/nestjs-durable";
+import { RUN_GATEWAY, Workflow, WorkflowService } from "@dudousxd/nestjs-durable";
 import { isWorkflowControlFlowSignal } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject2, Injectable as Injectable2, Logger, Optional } from "@nestjs/common";
 
@@ -33,7 +33,7 @@ __name(childSinkWriter, "childSinkWriter");
 var AGENT_CHAT_QUEUE = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:chat-queue");
 
 // src/durable/agent-run.steps.ts
-import { AGENT_DEPS_FACTORY, createFrameBuffer, createUiCollector, encodeStreamEvent, invokeWithTransientRetry, observeTurnFrames, publishAgentToolRetry, stampToolKinds, toolCallContext, traceLlmTurn, traceToolExecution, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput } from "@dudousxd/nestjs-agent-core";
+import { AGENT_DEPS_FACTORY, createFrameBuffer, createUiCollector, encodeStreamEvent, intersectAllowLists, invokeWithTransientRetry, observeTurnFrames, publishAgentToolRetry, stampToolKinds, toolCallContext, traceLlmTurn, traceToolExecution, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput } from "@dudousxd/nestjs-agent-core";
 import { Step } from "@dudousxd/nestjs-durable";
 import { Inject, Injectable } from "@nestjs/common";
 
@@ -97,14 +97,21 @@ var AgentRunSteps = class {
     const tools = withMemoryTool({
       tools: withSkillTool({
         tools: 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.
+            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
@@ -177,7 +184,9 @@ var AgentRunSteps = class {
       toolType: input.toolType
     }, () => 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 ? withToolTimeout(invocation, input.timeoutMs, input.toolName) : invocation;
     }, transientRetry, {
       onRetry: /* @__PURE__ */ __name((attempt, error) => {
@@ -254,12 +263,60 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
   store;
   runs;
   queue;
+  workflows;
   logger = new 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 (!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
@@ -460,6 +517,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({
@@ -468,7 +529,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
           });
           return thread.id;
         });
-        const childRunId = await ctx.startChild(_AgentRunWorkflow, {
+        const childInput = {
           agentName,
           threadId: subThreadId,
           actor: input.actor,
@@ -481,9 +542,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
@@ -596,12 +662,14 @@ AgentRunWorkflow = _ts_decorate2([
   _ts_param2(2, Inject2(RUN_GATEWAY)),
   _ts_param2(3, Optional()),
   _ts_param2(3, Inject2(AGENT_CHAT_QUEUE)),
+  _ts_param2(4, 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 WorkflowService === "undefined" ? Object : WorkflowService
   ])
 ], AgentRunWorkflow);
 function isSignalTimeout(error) {
@@ -611,8 +679,8 @@ __name(isSignalTimeout, "isSignalTimeout");
 
 // src/durable/durable-agent-runner.ts
 import { randomUUID } from "crypto";
-import { AGENT_SINK, AGENT_STORE as AGENT_STORE2, encodeStreamEvent as encodeStreamEvent3, releaseThreadRun as releaseThreadRun2 } from "@dudousxd/nestjs-agent-core";
-import { RUN_GATEWAY as RUN_GATEWAY2, WorkflowService } from "@dudousxd/nestjs-durable";
+import { AGENT_SINK, AGENT_STORE as AGENT_STORE2, encodeStreamEvent as encodeStreamEvent3, releaseThreadRun as releaseThreadRun2, settleUnsettledDelegation as settleUnsettledDelegation2 } from "@dudousxd/nestjs-agent-core";
+import { RUN_GATEWAY as RUN_GATEWAY2, WorkflowService as WorkflowService2 } from "@dudousxd/nestjs-durable";
 import { isWorkflowControlFlowSignal as isWorkflowControlFlowSignal2 } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject3, Injectable as Injectable3, Logger as Logger2, Optional as Optional2 } from "@nestjs/common";
 
@@ -722,6 +790,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");
@@ -801,11 +883,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)) {
@@ -836,7 +923,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 settleUnsettledDelegation2({
+        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 releaseThreadRun2(this.store, subThreadId, childId);
+    }
+    await this.settleCancelledDelegation(childId, child.run.input);
+    const writer = await this.sink.open(childId);
+    await writer.write(encodeStreamEvent3({
+      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
@@ -845,9 +982,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;
     }
@@ -862,7 +999,7 @@ DurableAgentRunner = _ts_decorate3([
   _ts_param3(4, Inject3(AGENT_CHAT_QUEUE)),
   _ts_metadata3("design:type", Function),
   _ts_metadata3("design:paramtypes", [
-    typeof WorkflowService === "undefined" ? Object : WorkflowService,
+    typeof WorkflowService2 === "undefined" ? Object : WorkflowService2,
     typeof RunGateway === "undefined" ? Object : RunGateway,
     typeof AgentStore === "undefined" ? Object : AgentStore,
     typeof TokenStreamSink === "undefined" ? Object : TokenStreamSink,
@@ -957,14 +1094,14 @@ AgentDurableModule = _ts_decorate4([
 ], AgentDurableModule);
 
 // src/agent.module.ts
-import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER13, AGENT_APPROVAL_PORT, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY7, AGENT_DURABLE_RUNNER as AGENT_DURABLE_RUNNER2, AGENT_MEMORY as AGENT_MEMORY3, AGENT_MODEL as AGENT_MODEL2, AGENT_MODEL_CATALOG as AGENT_MODEL_CATALOG3, AGENT_OPTIONS as AGENT_OPTIONS7, AGENT_PROMPT_CONTRIBUTORS as AGENT_PROMPT_CONTRIBUTORS3, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER3, AGENT_REGISTRY as AGENT_REGISTRY6, AGENT_ROLES_POLICY as AGENT_ROLES_POLICY2, AGENT_RUNNER as AGENT_RUNNER2, AGENT_SINK as AGENT_SINK4, AGENT_SKILLS as AGENT_SKILLS3, AGENT_SKILL_SOURCES as AGENT_SKILL_SOURCES2, AGENT_STORE as AGENT_STORE7, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry6, ClosedRolesPolicy, DefaultRolesPolicy, InMemoryAgentStore, ToolRegistry as ToolRegistry3 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER13, AGENT_APPROVAL_PORT, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY8, AGENT_DURABLE_RUNNER as AGENT_DURABLE_RUNNER2, AGENT_MEMORY as AGENT_MEMORY3, AGENT_MODEL as AGENT_MODEL2, AGENT_MODEL_CATALOG as AGENT_MODEL_CATALOG3, AGENT_OPTIONS as AGENT_OPTIONS7, AGENT_PROMPT_CONTRIBUTORS as AGENT_PROMPT_CONTRIBUTORS3, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER3, AGENT_REGISTRY as AGENT_REGISTRY6, AGENT_ROLES_POLICY as AGENT_ROLES_POLICY2, AGENT_RUNNER as AGENT_RUNNER2, AGENT_SINK as AGENT_SINK4, AGENT_SKILLS as AGENT_SKILLS3, AGENT_SKILL_SOURCES as AGENT_SKILL_SOURCES2, AGENT_STORE as AGENT_STORE7, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry6, ClosedRolesPolicy, DefaultRolesPolicy, InMemoryAgentStore, ToolRegistry as ToolRegistry3 } from "@dudousxd/nestjs-agent-core";
 import { Global as Global2, Logger as Logger8, Module as Module2 } from "@nestjs/common";
 import { DiscoveryModule, ModulesContainer, RouterModule } from "@nestjs/core";
 
 // src/agent-deps.factory.ts
-import { AGENT_MEMORY, AGENT_MODEL, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_REGISTRY, AGENT_ROLES_POLICY, AGENT_SINK as AGENT_SINK2, AGENT_SKILLS, AGENT_STORE as AGENT_STORE3, AGENT_TOOL_REGISTRY, AgentRegistry as AgentRegistry2, ToolRegistry as ToolRegistry2, normalizeDelegation, summarizeWithModel, windowHistory } from "@dudousxd/nestjs-agent-core";
+import { AGENT_MEMORY, AGENT_MODEL, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_REGISTRY, AGENT_ROLES_POLICY, AGENT_SINK as AGENT_SINK2, AGENT_SKILLS, AGENT_STORE as AGENT_STORE3, AGENT_TOOL_REGISTRY, AgentRegistry as AgentRegistry2, ToolRegistry as ToolRegistry2, findPersona, intersectAllowLists as intersectAllowLists2, normalizeDelegation, personaCatalogEntry, resolvePersonaAlias, summarizeWithModel, windowHistory } from "@dudousxd/nestjs-agent-core";
 import { AGENT_OPTIONS } from "@dudousxd/nestjs-agent-core";
-import { Inject as Inject4, Injectable as Injectable4, Optional as Optional3 } from "@nestjs/common";
+import { BadRequestException, Inject as Inject4, Injectable as Injectable4, Optional as Optional3 } from "@nestjs/common";
 function _ts_decorate5(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") {
@@ -1062,8 +1199,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 = 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(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 (findPersona(definition, args.requested) === void 0) {
+        throw new 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 && 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 = resolvePersonaAlias(this.agents.list(), agentName);
+      const persona = alias === void 0 ? void 0 : 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();
@@ -1128,6 +1321,9 @@ var AgentDepsFactory2 = class {
       ...toolAllowList !== void 0 ? {
         toolAllowList
       } : {},
+      ...definition?.personas !== void 0 ? {
+        personas: definition.personas
+      } : {},
       ...this.options.toolTimeoutMs !== void 0 ? {
         toolTimeoutMs: this.options.toolTimeoutMs
       } : {},
@@ -1146,6 +1342,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 = intersectAllowLists2(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.
@@ -1220,12 +1455,24 @@ AgentDepsFactory2 = _ts_decorate5([
 ], AgentDepsFactory2);
 
 // src/agent.service.ts
-import { AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING2, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY3, AGENT_MODEL_CATALOG, AGENT_OPTIONS as AGENT_OPTIONS3, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE5, REQUESTER_APPROVER, findCatalogModel, mayDecideApproval, readElicitationQuestions, settleDeadRun as settleDeadRun2, validateElicitationAnswer } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException, ConflictException as ConflictException2, ForbiddenException, GoneException, HttpException, HttpStatus, Inject as Inject6, Injectable as Injectable6, NotFoundException, NotImplementedException as NotImplementedException2, Optional as Optional5 } from "@nestjs/common";
+import { AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING2, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY4, AGENT_MODEL_CATALOG, AGENT_OPTIONS as AGENT_OPTIONS3, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE5, REQUESTER_APPROVER, findCatalogModel, mayDecideApproval, readElicitationQuestions, settleDeadRun as settleDeadRun2, validateElicitationAnswer } from "@dudousxd/nestjs-agent-core";
+import { BadRequestException as BadRequestException2, ConflictException as ConflictException2, ForbiddenException, GoneException, HttpException, HttpStatus, Inject as Inject6, Injectable as Injectable6, NotFoundException, NotImplementedException as NotImplementedException2, Optional as Optional5 } from "@nestjs/common";
 
 // src/queue/chat-queue.service.ts
-import { AGENT_ATTACHMENT_STAGING, AGENT_OPTIONS as AGENT_OPTIONS2, AGENT_QUOTA_PROVIDER, AGENT_SINK as AGENT_SINK3, AGENT_STORE as AGENT_STORE4, encodeStreamEvent as encodeStreamEvent4, isChatQueueStore, queuedMessageView } from "@dudousxd/nestjs-agent-core";
+import { AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY3, AGENT_OPTIONS as AGENT_OPTIONS2, AGENT_QUOTA_PROVIDER, AGENT_SINK as AGENT_SINK3, AGENT_STORE as AGENT_STORE4, encodeStreamEvent as encodeStreamEvent4, isChatQueueStore, queuedMessageView } from "@dudousxd/nestjs-agent-core";
 import { Inject as Inject5, Injectable as Injectable5, Logger as Logger3, NotImplementedException, Optional as Optional4 } from "@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") {
@@ -1262,18 +1509,20 @@ var ChatQueueService2 = class _ChatQueueService {
   quotaProvider;
   options;
   staging;
+  deps;
   logger = new Logger3(_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() {
@@ -1571,13 +1820,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
@@ -1590,6 +1843,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") {
@@ -1617,13 +1901,16 @@ ChatQueueService2 = _ts_decorate6([
   _ts_param5(3, Inject5(AGENT_OPTIONS2)),
   _ts_param5(4, Optional4()),
   _ts_param5(4, Inject5(AGENT_ATTACHMENT_STAGING)),
+  _ts_param5(5, Optional4()),
+  _ts_param5(5, Inject5(AGENT_DEPS_FACTORY3)),
   _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) {
@@ -1795,17 +2082,17 @@ var AgentService = class {
   */
   async assertModelAllowed(actor, agent, model) {
     if (this.models === void 0) {
-      throw new BadRequestException(`model "${model}" cannot be selected: no ModelCatalog is configured (AgentModule.forRoot({ models }))`);
+      throw new BadRequestException2(`model "${model}" cannot be selected: no ModelCatalog is configured (AgentModule.forRoot({ models }))`);
     }
     const entry = findCatalogModel(await this.models.list({
       actor,
       agent
     }), model);
     if (entry === void 0) {
-      throw new BadRequestException(`model "${model}" is not offered`);
+      throw new BadRequestException2(`model "${model}" is not offered`);
     }
     if (!entry.available) {
-      throw new BadRequestException(`model "${model}" is not available${entry.unavailableReason ? `: ${entry.unavailableReason}` : ""}`);
+      throw new BadRequestException2(`model "${model}" is not available${entry.unavailableReason ? `: ${entry.unavailableReason}` : ""}`);
     }
     return entry.id;
   }
@@ -1821,7 +2108,7 @@ var AgentService = class {
     })).locked : void 0;
     if (locked !== void 0) {
       if (requested !== void 0 && requested !== locked.model) {
-        throw new BadRequestException(`model "${requested}" cannot be selected: ${locked.reason ?? `this agent always uses "${locked.model}"`}`);
+        throw new BadRequestException2(`model "${requested}" cannot be selected: ${locked.reason ?? `this agent always uses "${locked.model}"`}`);
       }
       return locked.model;
     }
@@ -1877,13 +2164,15 @@ 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;
     if (threadId === void 0) {
       if (params.regenerate === true) {
-        throw new BadRequestException("regenerate requires an existing threadId");
+        throw new BadRequestException2("regenerate requires an existing threadId");
       }
       const created = await this.store.createThread({
         actor: params.actor,
@@ -1892,11 +2181,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,
@@ -1904,6 +2199,9 @@ var AgentService = class {
       userText: params.message,
       day: utcDay(),
       agentName,
+      ...persona !== void 0 ? {
+        persona
+      } : {},
       ...params.regenerate === true ? {
         regenerate: true
       } : {},
@@ -1990,6 +2288,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
       } : {},
@@ -2042,7 +2343,7 @@ var AgentService = class {
     const store = queue.queueStore();
     const threadId = await this.assertOwnsQueuedMessage(actor, messageId);
     if (patch.message !== void 0 && patch.message.trim().length === 0) {
-      throw new BadRequestException("message must not be empty");
+      throw new BadRequestException2("message must not be empty");
     }
     const attachments = patch.attachments === void 0 || patch.attachments === null ? patch.attachments : await this.resolveAttachments(actor, patch.attachments);
     if (patch.message !== void 0 || attachments !== void 0) {
@@ -2060,7 +2361,7 @@ var AgentService = class {
     }
     if (patch.position !== void 0) {
       if (!Number.isInteger(patch.position) || patch.position < 0) {
-        throw new BadRequestException("position must be a non-negative integer");
+        throw new BadRequestException2("position must be a non-negative integer");
       }
       if (!await store.moveQueuedMessage(messageId, patch.position)) {
         throw new GoneException(`queued message ${messageId} already started or was removed`);
@@ -2384,16 +2685,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 NotImplementedException2("Setting a thread's defaultAgent or model requires an AgentStore that implements updateThread(); the bound store does not support it.");
+      throw new NotImplementedException2("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
@@ -2403,16 +2710,46 @@ 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) {
-      throw new BadRequestException("title must not be empty");
+      throw new BadRequestException2("title must not be empty");
     }
     if (trimmed.length > 200) {
-      throw new BadRequestException("title must be at most 200 characters");
+      throw new BadRequestException2("title must be at most 200 characters");
     }
     return trimmed;
   }
@@ -2451,6 +2788,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
     };
   }
@@ -2515,14 +2853,14 @@ var AgentService = class {
   */
   async setMessageFeedback(actor, messageId, input) {
     if (input.value !== null && input.value !== "up" && input.value !== "down") {
-      throw new BadRequestException("value must be 'up', 'down' or null");
+      throw new BadRequestException2("value must be 'up', 'down' or null");
     }
     if (input.comment !== void 0 && typeof input.comment !== "string") {
-      throw new BadRequestException("comment must be a string");
+      throw new BadRequestException2("comment must be a string");
     }
     const comment = input.comment?.trim();
     if (comment !== void 0 && comment.length > 2e3) {
-      throw new BadRequestException("comment must be at most 2000 characters");
+      throw new BadRequestException2("comment must be at most 2000 characters");
     }
     if (this.store.threadOfMessage === void 0 || this.store.setMessageFeedback === void 0) {
       throw new NotImplementedException2("Message feedback requires an AgentStore that implements threadOfMessage() and setMessageFeedback(); the bound store does not support it.");
@@ -2647,7 +2985,7 @@ var AgentService = class {
       const submitted = Object.hasOwn(answers2, question.id) ? answers2[question.id] : void 0;
       const problem = validateElicitationAnswer(question, submitted ?? question.defaults ?? []);
       if (problem !== null) {
-        throw new BadRequestException(`answers["${question.id}"] ${problem}`);
+        throw new BadRequestException2(`answers["${question.id}"] ${problem}`);
       }
     }
   }
@@ -2721,7 +3059,7 @@ AgentService = _ts_decorate7([
   Injectable6(),
   _ts_param6(0, Inject6(AGENT_RUNNER)),
   _ts_param6(1, Inject6(AGENT_STORE5)),
-  _ts_param6(2, Inject6(AGENT_DEPS_FACTORY3)),
+  _ts_param6(2, Inject6(AGENT_DEPS_FACTORY4)),
   _ts_param6(3, Optional5()),
   _ts_param6(3, Inject6(AGENT_ATTACHMENT_STAGING2)),
   _ts_param6(4, Optional5()),
@@ -2812,7 +3150,7 @@ AgentApprovalPortAdapter = _ts_decorate8([
 ], AgentApprovalPortAdapter);
 
 // src/controller/agents.controller.ts
-import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY4, AGENT_REGISTRY as AGENT_REGISTRY2, AgentRegistry as AgentRegistry3 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY5, AGENT_REGISTRY as AGENT_REGISTRY2, AgentRegistry as AgentRegistry3 } from "@dudousxd/nestjs-agent-core";
 import { Controller, Get, Inject as Inject7 } from "@nestjs/common";
 function _ts_decorate9(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -2852,13 +3190,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([
@@ -2870,7 +3217,7 @@ _ts_decorate9([
 AgentsController = _ts_decorate9([
   Controller("agents"),
   _ts_param7(0, Inject7(AGENT_REGISTRY2)),
-  _ts_param7(1, Inject7(AGENT_DEPS_FACTORY4)),
+  _ts_param7(1, Inject7(AGENT_DEPS_FACTORY5)),
   _ts_metadata8("design:type", Function),
   _ts_metadata8("design:paramtypes", [
     typeof AgentRegistry3 === "undefined" ? Object : AgentRegistry3,
@@ -2880,7 +3227,7 @@ AgentsController = _ts_decorate9([
 
 // src/controller/attachments.controller.ts
 import { AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING3, AGENT_OPTIONS as AGENT_OPTIONS4 } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException as BadRequestException2, Controller as Controller2, Get as Get2, Inject as Inject8, NotImplementedException as NotImplementedException3, Optional as Optional6, PayloadTooLargeException, Post, Req, UnsupportedMediaTypeException, UploadedFile, UseInterceptors } from "@nestjs/common";
+import { BadRequestException as BadRequestException3, Controller as Controller2, Get as Get2, Inject as Inject8, NotImplementedException as NotImplementedException3, Optional as Optional6, PayloadTooLargeException, Post, Req, UnsupportedMediaTypeException, UploadedFile, UseInterceptors } from "@nestjs/common";
 import { FileInterceptor } from "@nestjs/platform-express";
 
 // src/attachment-limits.ts
@@ -2971,7 +3318,7 @@ var AttachmentsController = class {
       throw new NotImplementedException3("Attachment upload is not configured on this server: bind AGENT_ATTACHMENT_STAGING (e.g. import AgentMediaAttachmentsModule).");
     }
     if (file === void 0) {
-      throw new BadRequestException2('multipart field "file" is required');
+      throw new BadRequestException3('multipart field "file" is required');
     }
     const { allowedContentTypes, maxBytes } = attachmentLimits(this.options, this.staging);
     if (!allowedContentTypes.includes(file.mimetype)) {
@@ -3032,7 +3379,7 @@ AttachmentsController = _ts_decorate10([
 
 // src/controller/chat.controller.ts
 import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER2, AgentStreamError as AgentStreamError2, streamFailure as streamFailure2 } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException as BadRequestException3, Body, Controller as Controller3, Get as Get3, Inject as Inject9, Param, Post as Post2, Query, Req as Req2, Res } from "@nestjs/common";
+import { BadRequestException as BadRequestException4, Body, Controller as Controller3, Get as Get3, Inject as Inject9, Param, Post as Post2, Query, Req as Req2, Res } from "@nestjs/common";
 function _ts_decorate11(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") {
@@ -3069,7 +3416,7 @@ function sendMode(body) {
   if (body.mode === "auto" || body.mode === "queue" || body.mode === "interrupt") {
     return body.mode;
   }
-  throw new BadRequestException3("mode must be 'auto', 'queue' or 'interrupt'");
+  throw new BadRequestException4("mode must be 'auto', 'queue' or 'interrupt'");
 }
 __name(sendMode, "sendMode");
 function attachmentRefs(claimed) {
@@ -3077,21 +3424,21 @@ function attachmentRefs(claimed) {
     return [];
   }
   if (!Array.isArray(claimed)) {
-    throw new BadRequestException3("attachments must be an array of { mediaId }");
+    throw new BadRequestException4("attachments must be an array of { mediaId }");
   }
   if (claimed.length > MAX_ATTACHMENTS_PER_MESSAGE) {
-    throw new BadRequestException3(`a message may carry at most ${MAX_ATTACHMENTS_PER_MESSAGE} attachments`);
+    throw new BadRequestException4(`a message may carry at most ${MAX_ATTACHMENTS_PER_MESSAGE} attachments`);
   }
   return claimed.map((entry) => {
     if (typeof entry !== "object" || entry === null || !("mediaId" in entry)) {
-      throw new BadRequestException3("each attachment must be an object with a mediaId");
+      throw new BadRequestException4("each attachment must be an object with a mediaId");
     }
     if (Object.keys(entry).some((key) => key !== "mediaId")) {
-      throw new BadRequestException3("attachments are { mediaId } refs \u2014 send nothing but the id");
+      throw new BadRequestException4("attachments are { mediaId } refs \u2014 send nothing but the id");
     }
     const { mediaId } = entry;
     if (typeof mediaId !== "string" || mediaId.length === 0) {
-      throw new BadRequestException3("each attachment must carry a non-empty string mediaId");
+      throw new BadRequestException4("each attachment must carry a non-empty string mediaId");
     }
     return {
       mediaId
@@ -3128,6 +3475,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
       } : {},
@@ -3754,7 +4104,7 @@ ModelsController = _ts_decorate15([
 
 // src/controller/queue.controller.ts
 import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER7 } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException as BadRequestException4, Body as Body3, Controller as Controller8, Delete as Delete2, Get as Get7, Inject as Inject14, Param as Param4, Patch, Post as Post4, Req as Req7 } from "@nestjs/common";
+import { BadRequestException as BadRequestException5, Body as Body3, Controller as Controller8, Delete as Delete2, Get as Get7, Inject as Inject14, Param as Param4, Patch, Post as Post4, Req as Req7 } from "@nestjs/common";
 function _ts_decorate16(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") {
@@ -3804,10 +4154,10 @@ var QueueController = class {
   async update(req, messageId, body) {
     const actor = await this.actorResolver.resolve(req);
     if (body.message !== void 0 && typeof body.message !== "string") {
-      throw new BadRequestException4("message must be a string");
+      throw new BadRequestException5("message must be a string");
     }
     if (body.position !== void 0 && typeof body.position !== "number") {
-      throw new BadRequestException4("position must be a number");
+      throw new BadRequestException5("position must be a number");
     }
     const attachments = body.attachments === void 0 ? void 0 : body.attachments === null ? null : attachmentRefs(body.attachments);
     return this.agent.updateQueuedMessage(actor, messageId, {
@@ -4127,6 +4477,9 @@ var ThreadsController = class {
       } : {},
       ..."model" in body ? {
         model: body.model ?? null
+      } : {},
+      ..."persona" in body ? {
+        persona: body.persona ?? null
       } : {}
     });
     return {
@@ -4241,7 +4594,7 @@ ThreadsController = _ts_decorate19([
 
 // src/controller/tool-call.controller.ts
 import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER11 } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException as BadRequestException5, Body as Body5, Controller as Controller12, Inject as Inject18, Post as Post6, Req as Req11 } from "@nestjs/common";
+import { BadRequestException as BadRequestException6, Body as Body5, Controller as Controller12, Inject as Inject18, Post as Post6, Req as Req11 } from "@nestjs/common";
 function _ts_decorate20(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") {
@@ -4276,7 +4629,7 @@ var MAX_VIA_LENGTH = 64;
 var DEFAULT_VIA = "web";
 function toolCallId(claimed) {
   if (typeof claimed !== "string" || claimed.length === 0) {
-    throw new BadRequestException5("toolCallId must be a non-empty string");
+    throw new BadRequestException6("toolCallId must be a non-empty string");
   }
   return claimed;
 }
@@ -4286,10 +4639,10 @@ function rejectReason(claimed) {
     return void 0;
   }
   if (typeof claimed !== "string") {
-    throw new BadRequestException5("reason must be a string");
+    throw new BadRequestException6("reason must be a string");
   }
   if (claimed.length > MAX_REJECT_REASON_LENGTH) {
-    throw new BadRequestException5(`reason must be at most ${MAX_REJECT_REASON_LENGTH} characters`);
+    throw new BadRequestException6(`reason must be at most ${MAX_REJECT_REASON_LENGTH} characters`);
   }
   return claimed;
 }
@@ -4299,7 +4652,7 @@ function remember(claimed) {
     return false;
   }
   if (typeof claimed !== "boolean") {
-    throw new BadRequestException5("remember must be a boolean");
+    throw new BadRequestException6("remember must be a boolean");
   }
   return claimed;
 }
@@ -4309,7 +4662,7 @@ function via(claimed) {
     return DEFAULT_VIA;
   }
   if (typeof claimed !== "string" || claimed.length === 0 || claimed.length > MAX_VIA_LENGTH) {
-    throw new BadRequestException5(`via must be a string of 1-${MAX_VIA_LENGTH} characters`);
+    throw new BadRequestException6(`via must be a string of 1-${MAX_VIA_LENGTH} characters`);
   }
   return claimed;
 }
@@ -4319,26 +4672,26 @@ function answers(claimed) {
     return void 0;
   }
   if (typeof claimed !== "object" || claimed === null || Array.isArray(claimed)) {
-    throw new BadRequestException5("answers must be an object of questionId \u2192 chosen values");
+    throw new BadRequestException6("answers must be an object of questionId \u2192 chosen values");
   }
   const entries = Object.entries(claimed);
   if (entries.length > MAX_ANSWERED_QUESTIONS) {
-    throw new BadRequestException5(`answers may cover at most ${MAX_ANSWERED_QUESTIONS} questions`);
+    throw new BadRequestException6(`answers may cover at most ${MAX_ANSWERED_QUESTIONS} questions`);
   }
   const validated = /* @__PURE__ */ Object.create(null);
   for (const [questionId, values] of entries) {
     if (!Array.isArray(values)) {
-      throw new BadRequestException5(`answers["${questionId}"] must be an array of chosen values`);
+      throw new BadRequestException6(`answers["${questionId}"] must be an array of chosen values`);
     }
     if (values.length > MAX_VALUES_PER_QUESTION) {
-      throw new BadRequestException5(`answers["${questionId}"] may carry at most ${MAX_VALUES_PER_QUESTION} values`);
+      throw new BadRequestException6(`answers["${questionId}"] may carry at most ${MAX_VALUES_PER_QUESTION} values`);
     }
     for (const value of values) {
       if (typeof value !== "string") {
-        throw new BadRequestException5(`answers["${questionId}"] must contain only strings`);
+        throw new BadRequestException6(`answers["${questionId}"] must contain only strings`);
       }
       if (value.length > MAX_ANSWER_VALUE_LENGTH) {
-        throw new BadRequestException5(`answers["${questionId}"] values must be at most ${MAX_ANSWER_VALUE_LENGTH} characters`);
+        throw new BadRequestException6(`answers["${questionId}"] values must be at most ${MAX_ANSWER_VALUE_LENGTH} characters`);
       }
     }
     validated[questionId] = values;
@@ -4455,7 +4808,7 @@ ToolCallController = _ts_decorate20([
 ], ToolCallController);
 
 // src/controller/tools.controller.ts
-import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER12, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY5, AGENT_REGISTRY as AGENT_REGISTRY3, ALL_AGENTS, AgentRegistry as AgentRegistry4 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER12, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY6, AGENT_REGISTRY as AGENT_REGISTRY3, ALL_AGENTS, AgentRegistry as AgentRegistry4 } from "@dudousxd/nestjs-agent-core";
 import { Controller as Controller13, Get as Get11, Inject as Inject19, NotFoundException as NotFoundException3, Query as Query5, Req as Req12 } from "@nestjs/common";
 function _ts_decorate21(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -4540,7 +4893,7 @@ _ts_decorate21([
 ToolsController = _ts_decorate21([
   Controller13("tools"),
   _ts_param19(0, Inject19(AGENT_ACTOR_RESOLVER12)),
-  _ts_param19(1, Inject19(AGENT_DEPS_FACTORY5)),
+  _ts_param19(1, Inject19(AGENT_DEPS_FACTORY6)),
   _ts_param19(2, Inject19(AGENT_REGISTRY3)),
   _ts_metadata20("design:type", Function),
   _ts_metadata20("design:paramtypes", [
@@ -4622,6 +4975,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) {
@@ -4665,10 +5019,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.
@@ -5100,7 +5492,7 @@ var LedgerQuotaProvider = class {
 };
 
 // src/runner/inline-agent-runner.ts
-import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY6, AGENT_STORE as AGENT_STORE6, RUN_ENDED_BEFORE_TOOL_CALL as RUN_ENDED_BEFORE_TOOL_CALL2, RunCancelledError as RunCancelledError2, agentFailureCode as agentFailureCode2, encodeStreamEvent as encodeStreamEvent5, publishAgentRunFailed as publishAgentRunFailed2, releaseThreadRun as releaseThreadRun3, runAgentLoop as runAgentLoop2, settleAll as settleAll2, settleUnsettledDelegation as settleUnsettledDelegation2, streamFailure as streamFailure3 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY7, AGENT_STORE as AGENT_STORE6, RUN_ENDED_BEFORE_TOOL_CALL as RUN_ENDED_BEFORE_TOOL_CALL2, RunCancelledError as RunCancelledError2, agentFailureCode as agentFailureCode2, encodeStreamEvent as encodeStreamEvent5, publishAgentRunFailed as publishAgentRunFailed2, releaseThreadRun as releaseThreadRun3, runAgentLoop as runAgentLoop2, settleAll as settleAll2, settleUnsettledDelegation as settleUnsettledDelegation3, streamFailure as streamFailure3 } from "@dudousxd/nestjs-agent-core";
 import { Inject as Inject23, Injectable as Injectable11, Logger as Logger7, Optional as Optional10 } from "@nestjs/common";
 function _ts_decorate25(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -5485,7 +5877,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
         }
       });
       await Promise.resolve(this.store.failUnsettledToolCalls?.(runId, RUN_ENDED_BEFORE_TOOL_CALL2)).catch(() => 0);
-      await settleUnsettledDelegation2({
+      await settleUnsettledDelegation3({
         store: this.store,
         delivery: deliverTo,
         agent: agentName,
@@ -5580,7 +5972,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
 };
 InlineAgentRunner = _ts_decorate25([
   Injectable11(),
-  _ts_param23(0, Inject23(AGENT_DEPS_FACTORY6)),
+  _ts_param23(0, Inject23(AGENT_DEPS_FACTORY7)),
   _ts_param23(1, Inject23(AGENT_STORE6)),
   _ts_param23(2, Optional10()),
   _ts_metadata24("design:type", Function),
@@ -5792,7 +6184,7 @@ function sharedProviders(durable) {
     },
     AgentDepsFactory2,
     {
-      provide: AGENT_DEPS_FACTORY7,
+      provide: AGENT_DEPS_FACTORY8,
       useExisting: AgentDepsFactory2
     },
     // Populates the registry + contributors (onModuleInit) BEFORE AiToolDiscoveryService synthesizes
@@ -5865,7 +6257,7 @@ function exportsFor() {
     AGENT_PROMPT_CONTRIBUTORS3,
     AGENT_SKILLS3,
     AGENT_MEMORY3,
-    AGENT_DEPS_FACTORY7,
+    AGENT_DEPS_FACTORY8,
     AgentDepsFactory2,
     AgentService,
     ChatQueueService2,