@dudousxd/nestjs-agent 0.1.0 → 0.3.0

package/dist/durable/index.js

@@ -68,7 +68,6 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
         const subThreadId = await ctx.step(`subthread:${agentName}`, async () => {
           const thread = await this.store.createThread({
             actor: input.actor,
-            persona: "default",
             transient: true
           });
           return thread.id;
@@ -216,12 +215,12 @@ AgentDurableModule = _ts_decorate3([
 ], AgentDurableModule);
 
 // src/agent.module.ts
-import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER5, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY4, AGENT_DURABLE_RUNNER as AGENT_DURABLE_RUNNER2, AGENT_MODEL as AGENT_MODEL2, AGENT_OPTIONS as AGENT_OPTIONS3, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE2, AGENT_REGISTRY as AGENT_REGISTRY3, AGENT_ROLES_POLICY as AGENT_ROLES_POLICY2, AGENT_RUNNER as AGENT_RUNNER2, AGENT_SINK as AGENT_SINK2, AGENT_STORE as AGENT_STORE5, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry3, DefaultRolesPolicy, ToolRegistry as ToolRegistry3 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER5, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY4, AGENT_DURABLE_RUNNER as AGENT_DURABLE_RUNNER2, AGENT_MODEL as AGENT_MODEL2, AGENT_OPTIONS as AGENT_OPTIONS3, AGENT_PROMPT_CONTRIBUTORS as AGENT_PROMPT_CONTRIBUTORS3, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE3, AGENT_REGISTRY as AGENT_REGISTRY4, AGENT_ROLES_POLICY as AGENT_ROLES_POLICY2, AGENT_RUNNER as AGENT_RUNNER2, AGENT_SINK as AGENT_SINK2, AGENT_STORE as AGENT_STORE5, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry4, DefaultRolesPolicy, ToolRegistry as ToolRegistry3 } from "@dudousxd/nestjs-agent-core";
 import { Global as Global2, Module as Module2 } from "@nestjs/common";
 import { DiscoveryModule, RouterModule } from "@nestjs/core";
 
 // src/agent-deps.factory.ts
-import { AGENT_MODEL, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_ROLES_POLICY, AGENT_SINK, AGENT_STORE as AGENT_STORE2, AGENT_TOOL_REGISTRY, AgentRegistry as AgentRegistry2, ToolRegistry as ToolRegistry2 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_MODEL, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_ROLES_POLICY, AGENT_SINK, AGENT_STORE as AGENT_STORE2, AGENT_TOOL_REGISTRY, AgentRegistry as AgentRegistry2, ToolRegistry as ToolRegistry2 } from "@dudousxd/nestjs-agent-core";
 import { AGENT_OPTIONS } from "@dudousxd/nestjs-agent-core";
 import { Inject as Inject2, Injectable as Injectable3 } from "@nestjs/common";
 function _ts_decorate4(decorators, target, key, desc) {
@@ -256,8 +255,9 @@ var AgentDepsFactory2 = class {
   rolesPolicy;
   registry;
   agents;
+  promptContributors;
   quota;
-  constructor(options, model, store, sink, rolesPolicy, registry, agents, quota) {
+  constructor(options, model, store, sink, rolesPolicy, registry, agents, promptContributors, quota) {
     this.options = options;
     this.model = model;
     this.store = store;
@@ -265,10 +265,19 @@ var AgentDepsFactory2 = class {
     this.rolesPolicy = rolesPolicy;
     this.registry = registry;
     this.agents = agents;
+    this.promptContributors = promptContributors;
     this.quota = quota;
   }
+  /**
+  * The agent a turn uses when the caller names none: the explicit `defaultAgent` option, else the
+  * sole registered `@Agent` when there is exactly one, else `'default'` (a bare assistant).
+  */
   defaultAgentName() {
-    return this.options.defaultAgent?.name ?? "default";
+    if (this.options.defaultAgent !== void 0) {
+      return this.options.defaultAgent;
+    }
+    const registered = this.agents.list();
+    return registered.length === 1 ? registered[0]?.name ?? "default" : "default";
   }
   effectiveTools(definition) {
     if (definition === void 0) {
@@ -286,10 +295,6 @@ var AgentDepsFactory2 = class {
   forAgent(agentName) {
     const name = agentName ?? this.defaultAgentName();
     const definition = this.agents.get(name);
-    const personas = /* @__PURE__ */ new Map();
-    for (const persona of definition?.personas ?? []) {
-      personas.set(persona.id, persona);
-    }
     const toolAllowList = this.effectiveTools(definition);
     const followUpsCount = this.followUpsCount();
     const retrieval = this.options.retrieval;
@@ -299,10 +304,9 @@ var AgentDepsFactory2 = class {
       sink: this.sink,
       rolesPolicy: this.rolesPolicy,
       registry: this.registry,
+      promptContributors: this.promptContributors,
       systemPrompt: definition?.systemPrompt ?? "You are a helpful assistant.",
       maxSteps: definition?.maxSteps ?? 8,
-      personas,
-      defaultPersona: definition?.defaultPersona ?? "default",
       ...definition?.modelId !== void 0 ? {
         modelId: definition.modelId
       } : {},
@@ -347,7 +351,8 @@ AgentDepsFactory2 = _ts_decorate4([
   _ts_param2(4, Inject2(AGENT_ROLES_POLICY)),
   _ts_param2(5, Inject2(AGENT_TOOL_REGISTRY)),
   _ts_param2(6, Inject2(AGENT_REGISTRY)),
-  _ts_param2(7, Inject2(AGENT_QUOTA_STORE)),
+  _ts_param2(7, Inject2(AGENT_PROMPT_CONTRIBUTORS)),
+  _ts_param2(8, Inject2(AGENT_QUOTA_STORE)),
   _ts_metadata3("design:type", Function),
   _ts_metadata3("design:paramtypes", [
     typeof AgentModuleOptions === "undefined" ? Object : AgentModuleOptions,
@@ -357,12 +362,13 @@ AgentDepsFactory2 = _ts_decorate4([
     typeof RolesPolicy === "undefined" ? Object : RolesPolicy,
     typeof ToolRegistry2 === "undefined" ? Object : ToolRegistry2,
     typeof AgentRegistry2 === "undefined" ? Object : AgentRegistry2,
+    Array,
     Object
   ])
 ], AgentDepsFactory2);
 
 // src/agent.service.ts
-import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE3 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE3 } from "@dudousxd/nestjs-agent-core";
 import { BadRequestException, ForbiddenException, Inject as Inject3, Injectable as Injectable4, NotFoundException } 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;
@@ -388,10 +394,12 @@ var AgentService = class {
   runner;
   store;
   deps;
-  constructor(runner, store, deps) {
+  quota;
+  constructor(runner, store, deps, quota) {
     this.runner = runner;
     this.store = store;
     this.deps = deps;
+    this.quota = quota;
   }
   async chat(params) {
     const agentName = params.agentName ?? this.deps.defaultAgentName();
@@ -402,13 +410,14 @@ var AgentService = class {
       }
       const created = await this.store.createThread({
         actor: params.actor,
-        persona: params.personaId ?? this.deps.forAgent(agentName).defaultPersona
+        ...params.transient === true ? {
+          transient: true
+        } : {}
       });
       threadId = created.id;
     } else if (params.regenerate === true) {
       await this.assertOwnsThread(params.actor, threadId);
     }
-    const persona = this.resolvePersona(agentName, params.personaId);
     const input = {
       threadId,
       actor: params.actor,
@@ -418,9 +427,6 @@ var AgentService = class {
       ...params.regenerate === true ? {
         regenerate: true
       } : {},
-      ...persona !== void 0 ? {
-        persona
-      } : {},
       ...params.pageContext !== void 0 ? {
         pageContext: params.pageContext
       } : {}
@@ -454,18 +460,6 @@ var AgentService = class {
     await this.assertOwnsActiveStream(actor, runId);
     return this.runner.cancel(runId);
   }
-  resolvePersona(agentName, id) {
-    const deps = this.deps.forAgent(agentName);
-    return deps.personas.get(id ?? deps.defaultPersona);
-  }
-  personaCatalog(agentName) {
-    return [
-      ...this.deps.forAgent(agentName).personas.values()
-    ].map((persona) => ({
-      id: persona.id,
-      label: persona.label
-    }));
-  }
   listThreads(actorRef) {
     return this.store.listThreads(actorRef);
   }
@@ -481,8 +475,53 @@ var AgentService = class {
     await this.assertOwnsThread(actor, threadId);
     return this.store.forkThread(threadId, fromMessageId);
   }
+  async renameThread(actor, threadId, title) {
+    const trimmed = title.trim();
+    if (trimmed.length === 0) {
+      throw new BadRequestException("title must not be empty");
+    }
+    if (trimmed.length > 200) {
+      throw new BadRequestException("title must be at most 200 characters");
+    }
+    await this.assertOwnsThread(actor, threadId);
+    return this.store.setTitle(threadId, trimmed);
+  }
+  async promoteThread(actor, threadId) {
+    await this.assertOwnsThread(actor, threadId);
+    return this.store.promoteThread(threadId);
+  }
+  /**
+  * Drop a message and everything after it — the "edit and resend" / "delete from here" primitive.
+  * The client then sends a fresh turn on the truncated thread. Ownership-gated like the other
+  * thread-scoped mutations.
+  */
+  async truncateThreadFrom(actor, threadId, messageId) {
+    await this.assertOwnsThread(actor, threadId);
+    return this.store.truncateFrom(threadId, messageId);
+  }
+  /**
+  * The day's usage for the badge: tokens + summed USD cost from the store, and the configured
+  * limit from the quota store (null → unlimited). `withinLimit` comes from the quota store so it
+  * can never drift from what enforcement uses.
+  */
   async quotaToday(actorRef) {
-    return this.store.quotaToday(actorRef, utcDay());
+    const day = utcDay();
+    const { usedTokens, costUsd } = await this.store.quotaToday(actorRef, day);
+    if (this.quota === void 0) {
+      return {
+        usedTokens,
+        costUsd,
+        limitTokens: null,
+        withinLimit: true
+      };
+    }
+    const state = await this.quota.check(actorRef, day);
+    return {
+      usedTokens: state.usedTokens,
+      costUsd,
+      limitTokens: state.limitTokens,
+      withinLimit: state.withinLimit
+    };
   }
   /**
   * Authorization seam for thread-scoped endpoints: the caller must own the thread. A missing
@@ -533,11 +572,13 @@ AgentService = _ts_decorate5([
   _ts_param3(0, Inject3(AGENT_RUNNER)),
   _ts_param3(1, Inject3(AGENT_STORE3)),
   _ts_param3(2, Inject3(AGENT_DEPS_FACTORY2)),
+  _ts_param3(3, Inject3(AGENT_QUOTA_STORE2)),
   _ts_metadata4("design:type", Function),
   _ts_metadata4("design:paramtypes", [
     typeof AgentRunner === "undefined" ? Object : AgentRunner,
     typeof AgentStore === "undefined" ? Object : AgentStore,
-    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory
+    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
+    Object
   ])
 ], AgentService);
 
@@ -582,14 +623,14 @@ var ChatController = class {
       ...body.agent !== void 0 ? {
         agentName: body.agent
       } : {},
-      ...body.persona !== void 0 ? {
-        personaId: body.persona
-      } : {},
       ...body.pageContext !== void 0 ? {
         pageContext: body.pageContext
       } : {},
       ...body.regenerate === true ? {
         regenerate: true
+      } : {},
+      ...body.transient === true ? {
+        transient: true
       } : {}
     });
     await this.pipe(res, runId, threadId);
@@ -746,7 +787,7 @@ QuotaController = _ts_decorate7([
 
 // src/controller/threads.controller.ts
 import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER3 } from "@dudousxd/nestjs-agent-core";
-import { Controller as Controller3, Delete, Get as Get3, Inject as Inject6, Param as Param2, Post as Post2, Req as Req3 } from "@nestjs/common";
+import { Body as Body2, Controller as Controller3, Delete, Get as Get3, Inject as Inject6, Param as Param2, Patch, Post as Post2, Req as Req3 } from "@nestjs/common";
 function _ts_decorate8(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") r = Reflect.decorate(decorators, target, key, desc);
@@ -778,9 +819,6 @@ var ThreadsController = class {
     const actor = await this.actorResolver.resolve(req);
     return this.agent.listThreads(actor.id);
   }
-  personas() {
-    return this.agent.personaCatalog();
-  }
   async detail(req, id) {
     const actor = await this.actorResolver.resolve(req);
     return this.agent.getThread(actor, id);
@@ -796,6 +834,27 @@ var ThreadsController = class {
     const actor = await this.actorResolver.resolve(req);
     return this.agent.forkThread(actor, id, messageId);
   }
+  async rename(req, id, body) {
+    const actor = await this.actorResolver.resolve(req);
+    await this.agent.renameThread(actor, id, body.title);
+    return {
+      ok: true
+    };
+  }
+  async promote(req, id) {
+    const actor = await this.actorResolver.resolve(req);
+    await this.agent.promoteThread(actor, id);
+    return {
+      ok: true
+    };
+  }
+  async truncateFrom(req, id, messageId) {
+    const actor = await this.actorResolver.resolve(req);
+    await this.agent.truncateThreadFrom(actor, id, messageId);
+    return {
+      ok: true
+    };
+  }
 };
 _ts_decorate8([
   Get3(),
@@ -806,12 +865,6 @@ _ts_decorate8([
   ]),
   _ts_metadata7("design:returntype", Promise)
 ], ThreadsController.prototype, "list", null);
-_ts_decorate8([
-  Get3("personas/catalog"),
-  _ts_metadata7("design:type", Function),
-  _ts_metadata7("design:paramtypes", []),
-  _ts_metadata7("design:returntype", void 0)
-], ThreadsController.prototype, "personas", null);
 _ts_decorate8([
   Get3(":id"),
   _ts_param6(0, Req3()),
@@ -847,6 +900,43 @@ _ts_decorate8([
   ]),
   _ts_metadata7("design:returntype", Promise)
 ], ThreadsController.prototype, "fork", null);
+_ts_decorate8([
+  Patch(":id"),
+  _ts_param6(0, Req3()),
+  _ts_param6(1, Param2("id")),
+  _ts_param6(2, Body2()),
+  _ts_metadata7("design:type", Function),
+  _ts_metadata7("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String,
+    typeof RenameThreadBody === "undefined" ? Object : RenameThreadBody
+  ]),
+  _ts_metadata7("design:returntype", Promise)
+], ThreadsController.prototype, "rename", null);
+_ts_decorate8([
+  Post2(":id/promote"),
+  _ts_param6(0, Req3()),
+  _ts_param6(1, Param2("id")),
+  _ts_metadata7("design:type", Function),
+  _ts_metadata7("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String
+  ]),
+  _ts_metadata7("design:returntype", Promise)
+], ThreadsController.prototype, "promote", null);
+_ts_decorate8([
+  Delete(":id/from/:messageId"),
+  _ts_param6(0, Req3()),
+  _ts_param6(1, Param2("id")),
+  _ts_param6(2, Param2("messageId")),
+  _ts_metadata7("design:type", Function),
+  _ts_metadata7("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String,
+    String
+  ]),
+  _ts_metadata7("design:returntype", Promise)
+], ThreadsController.prototype, "truncateFrom", null);
 ThreadsController = _ts_decorate8([
   Controller3("threads"),
   _ts_param6(1, Inject6(AGENT_ACTOR_RESOLVER3)),
@@ -859,7 +949,7 @@ ThreadsController = _ts_decorate8([
 
 // src/controller/tool-call.controller.ts
 import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER4 } from "@dudousxd/nestjs-agent-core";
-import { Body as Body2, Controller as Controller4, Inject as Inject7, Post as Post3, Req as Req4 } from "@nestjs/common";
+import { Body as Body3, Controller as Controller4, Inject as Inject7, Post as Post3, Req as Req4 } 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;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -905,7 +995,7 @@ var ToolCallController = class {
 _ts_decorate9([
   Post3("approve"),
   _ts_param7(0, Req4()),
-  _ts_param7(1, Body2()),
+  _ts_param7(1, Body3()),
   _ts_metadata8("design:type", Function),
   _ts_metadata8("design:paramtypes", [
     typeof Request === "undefined" ? Object : Request,
@@ -916,7 +1006,7 @@ _ts_decorate9([
 _ts_decorate9([
   Post3("reject"),
   _ts_param7(0, Req4()),
-  _ts_param7(1, Body2()),
+  _ts_param7(1, Body3()),
   _ts_metadata8("design:type", Function),
   _ts_metadata8("design:paramtypes", [
     typeof Request === "undefined" ? Object : Request,
@@ -934,10 +1024,152 @@ ToolCallController = _ts_decorate9([
   ])
 ], ToolCallController);
 
-// src/discovery/ai-tool-discovery.service.ts
-import { AGENT_OPTIONS as AGENT_OPTIONS2, AGENT_REGISTRY as AGENT_REGISTRY2, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY2 } from "@dudousxd/nestjs-agent-core";
+// src/discovery/agent-discovery.service.ts
+import { AGENT_PROMPT_CONTRIBUTORS as AGENT_PROMPT_CONTRIBUTORS2, AGENT_REGISTRY as AGENT_REGISTRY2, AgentRegistry as AgentRegistry3 } from "@dudousxd/nestjs-agent-core";
 import { Inject as Inject8, Injectable as Injectable5, Logger } from "@nestjs/common";
-import { DiscoveryService } from "@nestjs/core";
+import { DiscoveryService, MetadataScanner } from "@nestjs/core";
+
+// src/decorator/agent.decorator.ts
+import "reflect-metadata";
+var AGENT_METADATA = Symbol.for("@dudousxd/nestjs-agent:agent-metadata");
+function readAgentMetadata(target) {
+  return Reflect.getMetadata(AGENT_METADATA, target);
+}
+__name(readAgentMetadata, "readAgentMetadata");
+
+// src/decorator/system-prompt.decorator.ts
+import "reflect-metadata";
+var SYSTEM_PROMPT_METADATA = Symbol.for("@dudousxd/nestjs-agent:system-prompt");
+var SYSTEM_PROMPT_CONTRIBUTOR_METADATA = Symbol.for("@dudousxd/nestjs-agent:system-prompt-contributor");
+
+// src/discovery/agent-discovery.service.ts
+function _ts_decorate10(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") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate10, "_ts_decorate");
+function _ts_metadata9(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata9, "_ts_metadata");
+function _ts_param8(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param8, "_ts_param");
+var AgentDiscoveryService = class _AgentDiscoveryService {
+  static {
+    __name(this, "AgentDiscoveryService");
+  }
+  discovery;
+  scanner;
+  registry;
+  contributors;
+  logger = new Logger(_AgentDiscoveryService.name);
+  constructor(discovery, scanner, registry, contributors) {
+    this.discovery = discovery;
+    this.scanner = scanner;
+    this.registry = registry;
+    this.contributors = contributors;
+  }
+  onModuleInit() {
+    for (const wrapper of this.discovery.getProviders()) {
+      const instance = wrapper.instance;
+      if (instance === null || typeof instance !== "object") {
+        continue;
+      }
+      const meta = readAgentMetadata(instance.constructor);
+      if (meta !== void 0) {
+        this.registry.register(this.definitionFrom(instance, meta));
+      }
+      this.collectContributors(instance);
+    }
+  }
+  /** Build the internal {@link AgentDefinition} from an `@Agent` instance and its options. */
+  definitionFrom(instance, meta) {
+    const promptMethod = this.methodWith(instance, SYSTEM_PROMPT_METADATA);
+    const systemPrompt = promptMethod !== void 0 ? (ctx) => promptMethod(ctx) : meta.systemPrompt ?? "You are a helpful assistant.";
+    return {
+      name: meta.name,
+      systemPrompt,
+      ...meta.tools !== void 0 ? {
+        tools: meta.tools
+      } : {},
+      ...meta.model !== void 0 ? {
+        modelId: meta.model
+      } : {},
+      ...meta.maxSteps !== void 0 ? {
+        maxSteps: meta.maxSteps
+      } : {},
+      ...meta.handoff !== void 0 ? {
+        delegatesTo: this.handoffNames(meta)
+      } : {}
+    };
+  }
+  /** Resolve each handoff `@Agent` class to its registered name (skipping non-agent classes). */
+  handoffNames(meta) {
+    const names = [];
+    for (const target of meta.handoff ?? []) {
+      const targetMeta = readAgentMetadata(target);
+      if (targetMeta === void 0) {
+        this.logger.warn(`Agent "${meta.name}" hands off to ${target.name}, which is not an @Agent \u2014 skipped.`);
+        continue;
+      }
+      names.push(targetMeta.name);
+    }
+    return names;
+  }
+  /** Push every `@SystemPromptContributor()` method on `instance` (bound) into the contributor list. */
+  collectContributors(instance) {
+    const prototype = Object.getPrototypeOf(instance);
+    for (const name of this.scanner.getAllMethodNames(prototype)) {
+      if (Reflect.getMetadata(SYSTEM_PROMPT_CONTRIBUTOR_METADATA, prototype, name) === true) {
+        const method = this.boundMethod(instance, name);
+        if (method !== void 0) {
+          this.contributors.push((ctx) => method(ctx));
+        }
+      }
+    }
+  }
+  /** The single method on `instance` carrying `metadataKey`, bound to the instance, or undefined. */
+  methodWith(instance, metadataKey) {
+    const prototype = Object.getPrototypeOf(instance);
+    for (const name of this.scanner.getAllMethodNames(prototype)) {
+      if (Reflect.getMetadata(metadataKey, prototype, name) === true) {
+        return this.boundMethod(instance, name);
+      }
+    }
+    return void 0;
+  }
+  /** Bind a named method to its instance, guarding that it is actually a function. */
+  boundMethod(instance, name) {
+    const candidate = instance[name];
+    if (typeof candidate !== "function") {
+      return void 0;
+    }
+    return (ctx) => candidate.call(instance, ctx);
+  }
+};
+AgentDiscoveryService = _ts_decorate10([
+  Injectable5(),
+  _ts_param8(2, Inject8(AGENT_REGISTRY2)),
+  _ts_param8(3, Inject8(AGENT_PROMPT_CONTRIBUTORS2)),
+  _ts_metadata9("design:type", Function),
+  _ts_metadata9("design:paramtypes", [
+    typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
+    typeof MetadataScanner === "undefined" ? Object : MetadataScanner,
+    typeof AgentRegistry3 === "undefined" ? Object : AgentRegistry3,
+    Array
+  ])
+], AgentDiscoveryService);
+
+// src/discovery/ai-tool-discovery.service.ts
+import { AGENT_OPTIONS as AGENT_OPTIONS2, AGENT_REGISTRY as AGENT_REGISTRY3, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY2 } from "@dudousxd/nestjs-agent-core";
+import { Inject as Inject9, Injectable as Injectable6, Logger as Logger2 } from "@nestjs/common";
+import { DiscoveryService as DiscoveryService2 } from "@nestjs/core";
 import { z } from "zod";
 
 // src/decorator/ai-tool.decorator.ts
@@ -956,23 +1188,23 @@ function isBrandedFunctionalTool(value) {
 __name(isBrandedFunctionalTool, "isBrandedFunctionalTool");
 
 // src/discovery/ai-tool-discovery.service.ts
-function _ts_decorate10(decorators, target, key, desc) {
+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") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate10, "_ts_decorate");
-function _ts_metadata9(k, v) {
+__name(_ts_decorate11, "_ts_decorate");
+function _ts_metadata10(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata9, "_ts_metadata");
-function _ts_param8(paramIndex, decorator) {
+__name(_ts_metadata10, "_ts_metadata");
+function _ts_param9(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param8, "_ts_param");
+__name(_ts_param9, "_ts_param");
 var AiToolDiscoveryService = class _AiToolDiscoveryService {
   static {
     __name(this, "AiToolDiscoveryService");
@@ -981,7 +1213,7 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
   registry;
   agents;
   options;
-  logger = new Logger(_AiToolDiscoveryService.name);
+  logger = new Logger2(_AiToolDiscoveryService.name);
   constructor(discovery, registry, agents, options) {
     this.discovery = discovery;
     this.registry = registry;
@@ -1039,7 +1271,7 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
       for (const target of definition.delegatesTo ?? []) {
         const targetDefinition = this.agents.get(target);
         if (targetDefinition === void 0) {
-          throw new Error(`Agent "${definition.name}" delegatesTo "${target}", which is not a registered agent. Register it via AgentModule.forFeature([...]) or fix the name.`);
+          throw new Error(`Agent "${definition.name}" hands off to "${target}", which is not a registered @Agent. Declare it as an @Agent provider or fix the reference.`);
         }
         const name = delegateToolName(target);
         if (this.registry.has(name)) {
@@ -1079,14 +1311,14 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
     return true;
   }
 };
-AiToolDiscoveryService = _ts_decorate10([
-  Injectable5(),
-  _ts_param8(1, Inject8(AGENT_TOOL_REGISTRY2)),
-  _ts_param8(2, Inject8(AGENT_REGISTRY2)),
-  _ts_param8(3, Inject8(AGENT_OPTIONS2)),
-  _ts_metadata9("design:type", Function),
-  _ts_metadata9("design:paramtypes", [
-    typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
+AiToolDiscoveryService = _ts_decorate11([
+  Injectable6(),
+  _ts_param9(1, Inject9(AGENT_TOOL_REGISTRY2)),
+  _ts_param9(2, Inject9(AGENT_REGISTRY3)),
+  _ts_param9(3, Inject9(AGENT_OPTIONS2)),
+  _ts_metadata10("design:type", Function),
+  _ts_metadata10("design:paramtypes", [
+    typeof DiscoveryService2 === "undefined" ? Object : DiscoveryService2,
     typeof ToolRegistry === "undefined" ? Object : ToolRegistry,
     typeof AgentRegistry === "undefined" ? Object : AgentRegistry,
     typeof AgentModuleOptions === "undefined" ? Object : AgentModuleOptions
@@ -1186,31 +1418,31 @@ var LedgerQuotaStore = class {
 
 // src/runner/inline-agent-runner.ts
 import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY3, AGENT_STORE as AGENT_STORE4, QuotaExceededError as QuotaExceededError2, publishAgentRunFailed as publishAgentRunFailed2, runAgentLoop as runAgentLoop2 } from "@dudousxd/nestjs-agent-core";
-import { Inject as Inject9, Injectable as Injectable6, Logger as Logger2 } from "@nestjs/common";
-function _ts_decorate11(decorators, target, key, desc) {
+import { Inject as Inject10, Injectable as Injectable7, Logger as Logger3 } from "@nestjs/common";
+function _ts_decorate12(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") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate11, "_ts_decorate");
-function _ts_metadata10(k, v) {
+__name(_ts_decorate12, "_ts_decorate");
+function _ts_metadata11(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata10, "_ts_metadata");
-function _ts_param9(paramIndex, decorator) {
+__name(_ts_metadata11, "_ts_metadata");
+function _ts_param10(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param9, "_ts_param");
+__name(_ts_param10, "_ts_param");
 var InlineAgentRunner = class _InlineAgentRunner {
   static {
     __name(this, "InlineAgentRunner");
   }
   factory;
   store;
-  logger = new Logger2(_InlineAgentRunner.name);
+  logger = new Logger3(_InlineAgentRunner.name);
   pending = /* @__PURE__ */ new Map();
   constructor(factory, store) {
     this.factory = factory;
@@ -1275,7 +1507,6 @@ var InlineAgentRunner = class _InlineAgentRunner {
   async runNested(agentName, task, actor, day, depth, sinkRunId) {
     const subThread = await this.store.createThread({
       actor,
-      persona: "default",
       transient: true
     });
     const runId = crypto.randomUUID();
@@ -1305,50 +1536,41 @@ var InlineAgentRunner = class _InlineAgentRunner {
     }, hooks);
   }
 };
-InlineAgentRunner = _ts_decorate11([
-  Injectable6(),
-  _ts_param9(0, Inject9(AGENT_DEPS_FACTORY3)),
-  _ts_param9(1, Inject9(AGENT_STORE4)),
-  _ts_metadata10("design:type", Function),
-  _ts_metadata10("design:paramtypes", [
+InlineAgentRunner = _ts_decorate12([
+  Injectable7(),
+  _ts_param10(0, Inject10(AGENT_DEPS_FACTORY3)),
+  _ts_param10(1, Inject10(AGENT_STORE4)),
+  _ts_metadata11("design:type", Function),
+  _ts_metadata11("design:paramtypes", [
     typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
     typeof AgentStore === "undefined" ? Object : AgentStore
   ])
 ], InlineAgentRunner);
 
 // src/agent.module.ts
-function _ts_decorate12(decorators, target, key, desc) {
+function _ts_decorate13(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") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
-__name(_ts_decorate12, "_ts_decorate");
-var FEATURE_INIT = Symbol("nestjs-agent:feature-init");
+__name(_ts_decorate13, "_ts_decorate");
 var DEFAULT_PATH = "agent";
-function defaultDefinition(options) {
-  return {
-    name: "default",
-    ...options.defaultAgent
-  };
-}
-__name(defaultDefinition, "defaultDefinition");
 function sharedProviders(durable, includeStore) {
   const providers = [
     {
       provide: AGENT_TOOL_REGISTRY3,
       useFactory: /* @__PURE__ */ __name(() => new ToolRegistry3(), "useFactory")
     },
+    // Starts empty; AgentDiscoveryService populates it from `@Agent`-decorated providers at boot.
     {
-      provide: AGENT_REGISTRY3,
-      useFactory: /* @__PURE__ */ __name((options) => {
-        const registry = new AgentRegistry3();
-        registry.register(defaultDefinition(options));
-        return registry;
-      }, "useFactory"),
-      inject: [
-        AGENT_OPTIONS3
-      ]
+      provide: AGENT_REGISTRY4,
+      useFactory: /* @__PURE__ */ __name(() => new AgentRegistry4(), "useFactory")
+    },
+    // A shared, mutable list AgentDiscoveryService fills with `@SystemPromptContributor()` methods.
+    {
+      provide: AGENT_PROMPT_CONTRIBUTORS3,
+      useFactory: /* @__PURE__ */ __name(() => [], "useFactory")
     },
     {
       provide: AGENT_SINK2,
@@ -1382,7 +1604,7 @@ function sharedProviders(durable, includeStore) {
       // An explicit `quota` wins; otherwise `quotaLimitTokens` binds the built-in ledger-backed
       // store; otherwise quotas are off (undefined). The ledger store reads the same usage rows
       // the loop already writes, so enforcement needs no extra shared state across replicas.
-      provide: AGENT_QUOTA_STORE2,
+      provide: AGENT_QUOTA_STORE3,
       useFactory: /* @__PURE__ */ __name((o, store) => o.quota ?? (o.quotaLimitTokens !== void 0 ? new LedgerQuotaStore(store, o.quotaLimitTokens) : void 0), "useFactory"),
       inject: [
         AGENT_OPTIONS3,
@@ -1394,6 +1616,9 @@ function sharedProviders(durable, includeStore) {
       provide: AGENT_DEPS_FACTORY4,
       useExisting: AgentDepsFactory2
     },
+    // Populates the registry + contributors (onModuleInit) BEFORE AiToolDiscoveryService synthesizes
+    // handoff tools (onApplicationBootstrap) reads the registry.
+    AgentDiscoveryService,
     AiToolDiscoveryService,
     InlineAgentRunner,
     AgentService
@@ -1436,7 +1661,7 @@ function exportsFor(includeStore) {
   return [
     AGENT_OPTIONS3,
     AGENT_TOOL_REGISTRY3,
-    AGENT_REGISTRY3,
+    AGENT_REGISTRY4,
     AGENT_SINK2,
     AGENT_ROLES_POLICY2,
     AGENT_ACTOR_RESOLVER5,
@@ -1444,7 +1669,8 @@ function exportsFor(includeStore) {
     ...includeStore ? [
       AGENT_STORE5
     ] : [],
-    AGENT_QUOTA_STORE2,
+    AGENT_QUOTA_STORE3,
+    AGENT_PROMPT_CONTRIBUTORS3,
     AGENT_DEPS_FACTORY4,
     AgentDepsFactory2,
     AgentService,
@@ -1516,28 +1742,8 @@ var AgentModule = class _AgentModule {
       exports: exportsFor(true)
     };
   }
-  /** Register additional named agents (an orchestrator + its sub-agents). */
-  static forFeature(definitions) {
-    return {
-      module: _AgentModule,
-      providers: [
-        {
-          provide: FEATURE_INIT,
-          useFactory: /* @__PURE__ */ __name((registry) => {
-            for (const definition of definitions) {
-              registry.register(definition);
-            }
-            return true;
-          }, "useFactory"),
-          inject: [
-            AGENT_REGISTRY3
-          ]
-        }
-      ]
-    };
-  }
 };
-AgentModule = _ts_decorate12([
+AgentModule = _ts_decorate13([
   Global2(),
   Module2({})
 ], AgentModule);