@dudousxd/nestjs-agent 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -22,9 +22,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AGENT_METADATA: () => AGENT_METADATA,
   AGENT_TOOL_BRAND: () => AGENT_TOOL_BRAND,
   AI_TOOL_METADATA: () => AI_TOOL_METADATA,
+  Agent: () => Agent,
   AgentDepsFactory: () => AgentDepsFactory2,
+  AgentDiscoveryService: () => AgentDiscoveryService,
   AgentModule: () => AgentModule,
   AgentService: () => AgentService,
   AiTool: () => AiTool,
@@ -33,17 +36,22 @@ __export(index_exports, {
   InProcessTokenStreamSink: () => InProcessTokenStreamSink,
   InlineAgentRunner: () => InlineAgentRunner,
   LedgerQuotaStore: () => LedgerQuotaStore,
+  SYSTEM_PROMPT_CONTRIBUTOR_METADATA: () => SYSTEM_PROMPT_CONTRIBUTOR_METADATA,
+  SYSTEM_PROMPT_METADATA: () => SYSTEM_PROMPT_METADATA,
+  SystemPrompt: () => SystemPrompt,
+  SystemPromptContributor: () => SystemPromptContributor,
   delegateToolName: () => delegateToolName,
   provideAgentTool: () => provideAgentTool,
+  readAgentMetadata: () => readAgentMetadata,
   readAiToolMetadata: () => readAiToolMetadata,
   utcDay: () => utcDay
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/agent.module.ts
-var import_nestjs_agent_core11 = require("@dudousxd/nestjs-agent-core");
-var import_common9 = require("@nestjs/common");
-var import_core2 = require("@nestjs/core");
+var import_nestjs_agent_core12 = require("@dudousxd/nestjs-agent-core");
+var import_common10 = require("@nestjs/common");
+var import_core3 = require("@nestjs/core");
 
 // src/agent-deps.factory.ts
 var import_nestjs_agent_core = require("@dudousxd/nestjs-agent-core");
@@ -81,8 +89,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;
@@ -90,10 +99,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) {
@@ -111,10 +129,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;
@@ -124,10 +138,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
       } : {},
@@ -172,7 +185,8 @@ AgentDepsFactory2 = _ts_decorate([
   _ts_param(4, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_ROLES_POLICY)),
   _ts_param(5, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_TOOL_REGISTRY)),
   _ts_param(6, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_REGISTRY)),
-  _ts_param(7, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_QUOTA_STORE)),
+  _ts_param(7, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_PROMPT_CONTRIBUTORS)),
+  _ts_param(8, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_QUOTA_STORE)),
   _ts_metadata("design:type", Function),
   _ts_metadata("design:paramtypes", [
     typeof AgentModuleOptions === "undefined" ? Object : AgentModuleOptions,
@@ -182,6 +196,7 @@ AgentDepsFactory2 = _ts_decorate([
     typeof RolesPolicy === "undefined" ? Object : RolesPolicy,
     typeof import_nestjs_agent_core.ToolRegistry === "undefined" ? Object : import_nestjs_agent_core.ToolRegistry,
     typeof import_nestjs_agent_core.AgentRegistry === "undefined" ? Object : import_nestjs_agent_core.AgentRegistry,
+    Array,
     Object
   ])
 ], AgentDepsFactory2);
@@ -231,10 +246,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();
@@ -245,13 +262,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,
@@ -261,9 +279,6 @@ var AgentService = class {
       ...params.regenerate === true ? {
         regenerate: true
       } : {},
-      ...persona !== void 0 ? {
-        persona
-      } : {},
       ...params.pageContext !== void 0 ? {
         pageContext: params.pageContext
       } : {}
@@ -297,18 +312,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);
   }
@@ -324,8 +327,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 import_common2.BadRequestException("title must not be empty");
+    }
+    if (trimmed.length > 200) {
+      throw new import_common2.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
@@ -376,11 +424,13 @@ AgentService = _ts_decorate2([
   _ts_param2(0, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_RUNNER)),
   _ts_param2(1, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_STORE)),
   _ts_param2(2, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_DEPS_FACTORY)),
+  _ts_param2(3, (0, import_common2.Inject)(import_nestjs_agent_core3.AGENT_QUOTA_STORE)),
   _ts_metadata2("design:type", Function),
   _ts_metadata2("design:paramtypes", [
     typeof AgentRunner === "undefined" ? Object : AgentRunner,
     typeof AgentStore === "undefined" ? Object : AgentStore,
-    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory
+    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
+    Object
   ])
 ], AgentService);
 
@@ -425,14 +475,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);
@@ -621,9 +671,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);
@@ -639,6 +686,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_decorate5([
   (0, import_common5.Get)(),
@@ -649,12 +717,6 @@ _ts_decorate5([
   ]),
   _ts_metadata5("design:returntype", Promise)
 ], ThreadsController.prototype, "list", null);
-_ts_decorate5([
-  (0, import_common5.Get)("personas/catalog"),
-  _ts_metadata5("design:type", Function),
-  _ts_metadata5("design:paramtypes", []),
-  _ts_metadata5("design:returntype", void 0)
-], ThreadsController.prototype, "personas", null);
 _ts_decorate5([
   (0, import_common5.Get)(":id"),
   _ts_param5(0, (0, import_common5.Req)()),
@@ -690,6 +752,43 @@ _ts_decorate5([
   ]),
   _ts_metadata5("design:returntype", Promise)
 ], ThreadsController.prototype, "fork", null);
+_ts_decorate5([
+  (0, import_common5.Patch)(":id"),
+  _ts_param5(0, (0, import_common5.Req)()),
+  _ts_param5(1, (0, import_common5.Param)("id")),
+  _ts_param5(2, (0, import_common5.Body)()),
+  _ts_metadata5("design:type", Function),
+  _ts_metadata5("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String,
+    typeof RenameThreadBody === "undefined" ? Object : RenameThreadBody
+  ]),
+  _ts_metadata5("design:returntype", Promise)
+], ThreadsController.prototype, "rename", null);
+_ts_decorate5([
+  (0, import_common5.Post)(":id/promote"),
+  _ts_param5(0, (0, import_common5.Req)()),
+  _ts_param5(1, (0, import_common5.Param)("id")),
+  _ts_metadata5("design:type", Function),
+  _ts_metadata5("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String
+  ]),
+  _ts_metadata5("design:returntype", Promise)
+], ThreadsController.prototype, "promote", null);
+_ts_decorate5([
+  (0, import_common5.Delete)(":id/from/:messageId"),
+  _ts_param5(0, (0, import_common5.Req)()),
+  _ts_param5(1, (0, import_common5.Param)("id")),
+  _ts_param5(2, (0, import_common5.Param)("messageId")),
+  _ts_metadata5("design:type", Function),
+  _ts_metadata5("design:paramtypes", [
+    typeof Request === "undefined" ? Object : Request,
+    String,
+    String
+  ]),
+  _ts_metadata5("design:returntype", Promise)
+], ThreadsController.prototype, "truncateFrom", null);
 ThreadsController = _ts_decorate5([
   (0, import_common5.Controller)("threads"),
   _ts_param5(1, (0, import_common5.Inject)(import_nestjs_agent_core6.AGENT_ACTOR_RESOLVER)),
@@ -777,14 +876,174 @@ ToolCallController = _ts_decorate6([
   ])
 ], ToolCallController);
 
-// src/discovery/ai-tool-discovery.service.ts
+// src/discovery/agent-discovery.service.ts
 var import_nestjs_agent_core8 = require("@dudousxd/nestjs-agent-core");
 var import_common7 = require("@nestjs/common");
 var import_core = require("@nestjs/core");
+
+// src/decorator/agent.decorator.ts
+var import_reflect_metadata = require("reflect-metadata");
+var AGENT_METADATA = Symbol.for("@dudousxd/nestjs-agent:agent-metadata");
+function Agent(options) {
+  return (target) => {
+    Reflect.defineMetadata(AGENT_METADATA, options, target);
+  };
+}
+__name(Agent, "Agent");
+function readAgentMetadata(target) {
+  return Reflect.getMetadata(AGENT_METADATA, target);
+}
+__name(readAgentMetadata, "readAgentMetadata");
+
+// src/decorator/system-prompt.decorator.ts
+var import_reflect_metadata2 = require("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");
+function SystemPrompt() {
+  return (target, key) => {
+    Reflect.defineMetadata(SYSTEM_PROMPT_METADATA, true, target, key);
+  };
+}
+__name(SystemPrompt, "SystemPrompt");
+function SystemPromptContributor() {
+  return (target, key) => {
+    Reflect.defineMetadata(SYSTEM_PROMPT_CONTRIBUTOR_METADATA, true, target, key);
+  };
+}
+__name(SystemPromptContributor, "SystemPromptContributor");
+
+// src/discovery/agent-discovery.service.ts
+function _ts_decorate7(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_decorate7, "_ts_decorate");
+function _ts_metadata7(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata7, "_ts_metadata");
+function _ts_param7(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param7, "_ts_param");
+var AgentDiscoveryService = class _AgentDiscoveryService {
+  static {
+    __name(this, "AgentDiscoveryService");
+  }
+  discovery;
+  scanner;
+  registry;
+  contributors;
+  logger = new import_common7.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_decorate7([
+  (0, import_common7.Injectable)(),
+  _ts_param7(2, (0, import_common7.Inject)(import_nestjs_agent_core8.AGENT_REGISTRY)),
+  _ts_param7(3, (0, import_common7.Inject)(import_nestjs_agent_core8.AGENT_PROMPT_CONTRIBUTORS)),
+  _ts_metadata7("design:type", Function),
+  _ts_metadata7("design:paramtypes", [
+    typeof import_core.DiscoveryService === "undefined" ? Object : import_core.DiscoveryService,
+    typeof import_core.MetadataScanner === "undefined" ? Object : import_core.MetadataScanner,
+    typeof import_nestjs_agent_core8.AgentRegistry === "undefined" ? Object : import_nestjs_agent_core8.AgentRegistry,
+    Array
+  ])
+], AgentDiscoveryService);
+
+// src/discovery/ai-tool-discovery.service.ts
+var import_nestjs_agent_core9 = require("@dudousxd/nestjs-agent-core");
+var import_common8 = require("@nestjs/common");
+var import_core2 = require("@nestjs/core");
 var import_zod = require("zod");
 
 // src/decorator/ai-tool.decorator.ts
-var import_reflect_metadata = require("reflect-metadata");
+var import_reflect_metadata3 = require("reflect-metadata");
 var AI_TOOL_METADATA = Symbol("nestjs-agent:ai-tool");
 function AiTool(options) {
   return (target) => {
@@ -828,23 +1087,23 @@ function provideAgentTool(factoryOrTool, inject) {
 __name(provideAgentTool, "provideAgentTool");
 
 // src/discovery/ai-tool-discovery.service.ts
-function _ts_decorate7(decorators, target, key, desc) {
+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);
   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_decorate7, "_ts_decorate");
-function _ts_metadata7(k, v) {
+__name(_ts_decorate8, "_ts_decorate");
+function _ts_metadata8(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata7, "_ts_metadata");
-function _ts_param7(paramIndex, decorator) {
+__name(_ts_metadata8, "_ts_metadata");
+function _ts_param8(paramIndex, decorator) {
   return function(target, key) {
     decorator(target, key, paramIndex);
   };
 }
-__name(_ts_param7, "_ts_param");
+__name(_ts_param8, "_ts_param");
 var AiToolDiscoveryService = class _AiToolDiscoveryService {
   static {
     __name(this, "AiToolDiscoveryService");
@@ -853,7 +1112,7 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
   registry;
   agents;
   options;
-  logger = new import_common7.Logger(_AiToolDiscoveryService.name);
+  logger = new import_common8.Logger(_AiToolDiscoveryService.name);
   constructor(discovery, registry, agents, options) {
     this.discovery = discovery;
     this.registry = registry;
@@ -911,7 +1170,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)) {
@@ -951,14 +1210,14 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
     return true;
   }
 };
-AiToolDiscoveryService = _ts_decorate7([
-  (0, import_common7.Injectable)(),
-  _ts_param7(1, (0, import_common7.Inject)(import_nestjs_agent_core8.AGENT_TOOL_REGISTRY)),
-  _ts_param7(2, (0, import_common7.Inject)(import_nestjs_agent_core8.AGENT_REGISTRY)),
-  _ts_param7(3, (0, import_common7.Inject)(import_nestjs_agent_core8.AGENT_OPTIONS)),
-  _ts_metadata7("design:type", Function),
-  _ts_metadata7("design:paramtypes", [
-    typeof import_core.DiscoveryService === "undefined" ? Object : import_core.DiscoveryService,
+AiToolDiscoveryService = _ts_decorate8([
+  (0, import_common8.Injectable)(),
+  _ts_param8(1, (0, import_common8.Inject)(import_nestjs_agent_core9.AGENT_TOOL_REGISTRY)),
+  _ts_param8(2, (0, import_common8.Inject)(import_nestjs_agent_core9.AGENT_REGISTRY)),
+  _ts_param8(3, (0, import_common8.Inject)(import_nestjs_agent_core9.AGENT_OPTIONS)),
+  _ts_metadata8("design:type", Function),
+  _ts_metadata8("design:paramtypes", [
+    typeof import_core2.DiscoveryService === "undefined" ? Object : import_core2.DiscoveryService,
     typeof ToolRegistry === "undefined" ? Object : ToolRegistry,
     typeof AgentRegistry === "undefined" ? Object : AgentRegistry,
     typeof AgentModuleOptions === "undefined" ? Object : AgentModuleOptions
@@ -966,7 +1225,7 @@ AiToolDiscoveryService = _ts_decorate7([
 ], AiToolDiscoveryService);
 
 // src/in-process-sink.ts
-var import_nestjs_agent_core9 = require("@dudousxd/nestjs-agent-core");
+var import_nestjs_agent_core10 = require("@dudousxd/nestjs-agent-core");
 var InProcessTokenStreamSink = class {
   static {
     __name(this, "InProcessTokenStreamSink");
@@ -1021,7 +1280,7 @@ var InProcessTokenStreamSink = class {
       }
       if (buf.ended) {
         if (buf.failure !== void 0) {
-          throw new import_nestjs_agent_core9.AgentStreamError(buf.failure);
+          throw new import_nestjs_agent_core10.AgentStreamError(buf.failure);
         }
         return;
       }
@@ -1057,32 +1316,32 @@ var LedgerQuotaStore = class {
 };
 
 // src/runner/inline-agent-runner.ts
-var import_nestjs_agent_core10 = require("@dudousxd/nestjs-agent-core");
-var import_common8 = require("@nestjs/common");
-function _ts_decorate8(decorators, target, key, desc) {
+var import_nestjs_agent_core11 = require("@dudousxd/nestjs-agent-core");
+var import_common9 = require("@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);
   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_decorate8, "_ts_decorate");
-function _ts_metadata8(k, v) {
+__name(_ts_decorate9, "_ts_decorate");
+function _ts_metadata9(k, v) {
   if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
-__name(_ts_metadata8, "_ts_metadata");
-function _ts_param8(paramIndex, decorator) {
+__name(_ts_metadata9, "_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 InlineAgentRunner = class _InlineAgentRunner {
   static {
     __name(this, "InlineAgentRunner");
   }
   factory;
   store;
-  logger = new import_common8.Logger(_InlineAgentRunner.name);
+  logger = new import_common9.Logger(_InlineAgentRunner.name);
   pending = /* @__PURE__ */ new Map();
   constructor(factory, store) {
     this.factory = factory;
@@ -1093,14 +1352,14 @@ var InlineAgentRunner = class _InlineAgentRunner {
     const day = input.day ?? utcDay();
     const deps = this.factory.forAgent(input.agentName);
     const hooks = this.topLevelHooks(runId, deps, input.actor, day);
-    void (0, import_nestjs_agent_core10.runAgentLoop)({
+    void (0, import_nestjs_agent_core11.runAgentLoop)({
       ...deps,
       day
     }, input, hooks).catch(async (error) => {
       const message = error instanceof Error ? error.message : String(error);
-      const code = error instanceof import_nestjs_agent_core10.QuotaExceededError ? "quota_exceeded" : "run_failed";
+      const code = error instanceof import_nestjs_agent_core11.QuotaExceededError ? "quota_exceeded" : "run_failed";
       this.logger.error(`agent run ${runId} failed (${code}): ${message}`);
-      (0, import_nestjs_agent_core10.publishAgentRunFailed)({
+      (0, import_nestjs_agent_core11.publishAgentRunFailed)({
         runId,
         code,
         message
@@ -1147,7 +1406,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();
@@ -1163,7 +1421,7 @@ var InlineAgentRunner = class _InlineAgentRunner {
       step: /* @__PURE__ */ __name((_name, fn) => fn(), "step"),
       runAgent: /* @__PURE__ */ __name((childName, childTask) => this.runNested(childName, childTask, actor, day, depth + 1, sinkRunId), "runAgent")
     };
-    return (0, import_nestjs_agent_core10.runAgentLoop)({
+    return (0, import_nestjs_agent_core11.runAgentLoop)({
       ...deps,
       day
     }, {
@@ -1177,111 +1435,105 @@ var InlineAgentRunner = class _InlineAgentRunner {
     }, hooks);
   }
 };
-InlineAgentRunner = _ts_decorate8([
-  (0, import_common8.Injectable)(),
-  _ts_param8(0, (0, import_common8.Inject)(import_nestjs_agent_core10.AGENT_DEPS_FACTORY)),
-  _ts_param8(1, (0, import_common8.Inject)(import_nestjs_agent_core10.AGENT_STORE)),
-  _ts_metadata8("design:type", Function),
-  _ts_metadata8("design:paramtypes", [
+InlineAgentRunner = _ts_decorate9([
+  (0, import_common9.Injectable)(),
+  _ts_param9(0, (0, import_common9.Inject)(import_nestjs_agent_core11.AGENT_DEPS_FACTORY)),
+  _ts_param9(1, (0, import_common9.Inject)(import_nestjs_agent_core11.AGENT_STORE)),
+  _ts_metadata9("design:type", Function),
+  _ts_metadata9("design:paramtypes", [
     typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
     typeof AgentStore === "undefined" ? Object : AgentStore
   ])
 ], InlineAgentRunner);
 
 // src/agent.module.ts
-function _ts_decorate9(decorators, target, key, desc) {
+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_decorate9, "_ts_decorate");
-var FEATURE_INIT = Symbol("nestjs-agent:feature-init");
+__name(_ts_decorate10, "_ts_decorate");
 var DEFAULT_PATH = "agent";
-function defaultDefinition(options) {
-  return {
-    name: "default",
-    ...options.defaultAgent
-  };
-}
-__name(defaultDefinition, "defaultDefinition");
 function sharedProviders(durable, includeStore) {
   const providers = [
     {
-      provide: import_nestjs_agent_core11.AGENT_TOOL_REGISTRY,
-      useFactory: /* @__PURE__ */ __name(() => new import_nestjs_agent_core11.ToolRegistry(), "useFactory")
+      provide: import_nestjs_agent_core12.AGENT_TOOL_REGISTRY,
+      useFactory: /* @__PURE__ */ __name(() => new import_nestjs_agent_core12.ToolRegistry(), "useFactory")
     },
+    // Starts empty; AgentDiscoveryService populates it from `@Agent`-decorated providers at boot.
     {
-      provide: import_nestjs_agent_core11.AGENT_REGISTRY,
-      useFactory: /* @__PURE__ */ __name((options) => {
-        const registry = new import_nestjs_agent_core11.AgentRegistry();
-        registry.register(defaultDefinition(options));
-        return registry;
-      }, "useFactory"),
-      inject: [
-        import_nestjs_agent_core11.AGENT_OPTIONS
-      ]
+      provide: import_nestjs_agent_core12.AGENT_REGISTRY,
+      useFactory: /* @__PURE__ */ __name(() => new import_nestjs_agent_core12.AgentRegistry(), "useFactory")
     },
+    // A shared, mutable list AgentDiscoveryService fills with `@SystemPromptContributor()` methods.
     {
-      provide: import_nestjs_agent_core11.AGENT_SINK,
+      provide: import_nestjs_agent_core12.AGENT_PROMPT_CONTRIBUTORS,
+      useFactory: /* @__PURE__ */ __name(() => [], "useFactory")
+    },
+    {
+      provide: import_nestjs_agent_core12.AGENT_SINK,
       useFactory: /* @__PURE__ */ __name((options) => options.sink ?? new InProcessTokenStreamSink(), "useFactory"),
       inject: [
-        import_nestjs_agent_core11.AGENT_OPTIONS
+        import_nestjs_agent_core12.AGENT_OPTIONS
       ]
     },
     {
-      provide: import_nestjs_agent_core11.AGENT_ROLES_POLICY,
-      useFactory: /* @__PURE__ */ __name((options) => options.rolesPolicy ?? new import_nestjs_agent_core11.DefaultRolesPolicy(options.defaultRoles), "useFactory"),
+      provide: import_nestjs_agent_core12.AGENT_ROLES_POLICY,
+      useFactory: /* @__PURE__ */ __name((options) => options.rolesPolicy ?? new import_nestjs_agent_core12.DefaultRolesPolicy(options.defaultRoles), "useFactory"),
       inject: [
-        import_nestjs_agent_core11.AGENT_OPTIONS
+        import_nestjs_agent_core12.AGENT_OPTIONS
       ]
     },
     {
-      provide: import_nestjs_agent_core11.AGENT_ACTOR_RESOLVER,
+      provide: import_nestjs_agent_core12.AGENT_ACTOR_RESOLVER,
       useFactory: /* @__PURE__ */ __name((options) => options.actorResolver, "useFactory"),
       inject: [
-        import_nestjs_agent_core11.AGENT_OPTIONS
+        import_nestjs_agent_core12.AGENT_OPTIONS
       ]
     },
     {
-      provide: import_nestjs_agent_core11.AGENT_MODEL,
+      provide: import_nestjs_agent_core12.AGENT_MODEL,
       useFactory: /* @__PURE__ */ __name((o) => o.model, "useFactory"),
       inject: [
-        import_nestjs_agent_core11.AGENT_OPTIONS
+        import_nestjs_agent_core12.AGENT_OPTIONS
       ]
     },
     {
       // 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: import_nestjs_agent_core11.AGENT_QUOTA_STORE,
+      provide: import_nestjs_agent_core12.AGENT_QUOTA_STORE,
       useFactory: /* @__PURE__ */ __name((o, store) => o.quota ?? (o.quotaLimitTokens !== void 0 ? new LedgerQuotaStore(store, o.quotaLimitTokens) : void 0), "useFactory"),
       inject: [
-        import_nestjs_agent_core11.AGENT_OPTIONS,
-        import_nestjs_agent_core11.AGENT_STORE
+        import_nestjs_agent_core12.AGENT_OPTIONS,
+        import_nestjs_agent_core12.AGENT_STORE
       ]
     },
     AgentDepsFactory2,
     {
-      provide: import_nestjs_agent_core11.AGENT_DEPS_FACTORY,
+      provide: import_nestjs_agent_core12.AGENT_DEPS_FACTORY,
       useExisting: AgentDepsFactory2
     },
+    // Populates the registry + contributors (onModuleInit) BEFORE AiToolDiscoveryService synthesizes
+    // handoff tools (onApplicationBootstrap) reads the registry.
+    AgentDiscoveryService,
     AiToolDiscoveryService,
     InlineAgentRunner,
     AgentService
   ];
   if (includeStore) {
     providers.push({
-      provide: import_nestjs_agent_core11.AGENT_STORE,
+      provide: import_nestjs_agent_core12.AGENT_STORE,
       useFactory: /* @__PURE__ */ __name((o) => o.store, "useFactory"),
       inject: [
-        import_nestjs_agent_core11.AGENT_OPTIONS
+        import_nestjs_agent_core12.AGENT_OPTIONS
       ]
     });
   }
   if (durable) {
     providers.push({
-      provide: import_nestjs_agent_core11.AGENT_RUNNER,
+      provide: import_nestjs_agent_core12.AGENT_RUNNER,
       useFactory: /* @__PURE__ */ __name((durableRunner) => {
         if (durableRunner === void 0) {
           throw new Error("AgentModule.forRoot({ durable: true }) requires importing AgentDurableModule from '@dudousxd/nestjs-agent/durable' (alongside a configured DurableModule). It was not found.");
@@ -1290,14 +1542,14 @@ function sharedProviders(durable, includeStore) {
       }, "useFactory"),
       inject: [
         {
-          token: import_nestjs_agent_core11.AGENT_DURABLE_RUNNER,
+          token: import_nestjs_agent_core12.AGENT_DURABLE_RUNNER,
           optional: true
         }
       ]
     });
   } else {
     providers.push({
-      provide: import_nestjs_agent_core11.AGENT_RUNNER,
+      provide: import_nestjs_agent_core12.AGENT_RUNNER,
       useExisting: InlineAgentRunner
     });
   }
@@ -1306,18 +1558,19 @@ function sharedProviders(durable, includeStore) {
 __name(sharedProviders, "sharedProviders");
 function exportsFor(includeStore) {
   return [
-    import_nestjs_agent_core11.AGENT_OPTIONS,
-    import_nestjs_agent_core11.AGENT_TOOL_REGISTRY,
-    import_nestjs_agent_core11.AGENT_REGISTRY,
-    import_nestjs_agent_core11.AGENT_SINK,
-    import_nestjs_agent_core11.AGENT_ROLES_POLICY,
-    import_nestjs_agent_core11.AGENT_ACTOR_RESOLVER,
-    import_nestjs_agent_core11.AGENT_MODEL,
+    import_nestjs_agent_core12.AGENT_OPTIONS,
+    import_nestjs_agent_core12.AGENT_TOOL_REGISTRY,
+    import_nestjs_agent_core12.AGENT_REGISTRY,
+    import_nestjs_agent_core12.AGENT_SINK,
+    import_nestjs_agent_core12.AGENT_ROLES_POLICY,
+    import_nestjs_agent_core12.AGENT_ACTOR_RESOLVER,
+    import_nestjs_agent_core12.AGENT_MODEL,
     ...includeStore ? [
-      import_nestjs_agent_core11.AGENT_STORE
+      import_nestjs_agent_core12.AGENT_STORE
     ] : [],
-    import_nestjs_agent_core11.AGENT_QUOTA_STORE,
-    import_nestjs_agent_core11.AGENT_DEPS_FACTORY,
+    import_nestjs_agent_core12.AGENT_QUOTA_STORE,
+    import_nestjs_agent_core12.AGENT_PROMPT_CONTRIBUTORS,
+    import_nestjs_agent_core12.AGENT_DEPS_FACTORY,
     AgentDepsFactory2,
     AgentService,
     InlineAgentRunner
@@ -1331,7 +1584,7 @@ var CONTROLLERS = [
   QuotaController
 ];
 function routerFor(path) {
-  return import_core2.RouterModule.register([
+  return import_core3.RouterModule.register([
     {
       path,
       module: AgentModule
@@ -1350,13 +1603,13 @@ var AgentModule = class _AgentModule {
       module: _AgentModule,
       global: true,
       imports: [
-        import_core2.DiscoveryModule,
+        import_core3.DiscoveryModule,
         routerFor(path)
       ],
       controllers: CONTROLLERS,
       providers: [
         {
-          provide: import_nestjs_agent_core11.AGENT_OPTIONS,
+          provide: import_nestjs_agent_core12.AGENT_OPTIONS,
           useValue: options
         },
         ...sharedProviders(options.durable ?? false, includeStore)
@@ -1370,14 +1623,14 @@ var AgentModule = class _AgentModule {
       module: _AgentModule,
       global: true,
       imports: [
-        import_core2.DiscoveryModule,
+        import_core3.DiscoveryModule,
         routerFor(path),
         ...options.imports ?? []
       ],
       controllers: CONTROLLERS,
       providers: [
         {
-          provide: import_nestjs_agent_core11.AGENT_OPTIONS,
+          provide: import_nestjs_agent_core12.AGENT_OPTIONS,
           useFactory: options.useFactory,
           inject: options.inject ?? []
         },
@@ -1388,30 +1641,10 @@ 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: [
-            import_nestjs_agent_core11.AGENT_REGISTRY
-          ]
-        }
-      ]
-    };
-  }
 };
-AgentModule = _ts_decorate9([
-  (0, import_common9.Global)(),
-  (0, import_common9.Module)({})
+AgentModule = _ts_decorate10([
+  (0, import_common10.Global)(),
+  (0, import_common10.Module)({})
 ], AgentModule);
 
 // src/resolver/header-actor-resolver.ts
@@ -1448,9 +1681,12 @@ var HeaderActorResolver = class {
 __reExport(index_exports, require("@dudousxd/nestjs-agent-core"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AGENT_METADATA,
   AGENT_TOOL_BRAND,
   AI_TOOL_METADATA,
+  Agent,
   AgentDepsFactory,
+  AgentDiscoveryService,
   AgentModule,
   AgentService,
   AiTool,
@@ -1459,8 +1695,13 @@ __reExport(index_exports, require("@dudousxd/nestjs-agent-core"), module.exports
   InProcessTokenStreamSink,
   InlineAgentRunner,
   LedgerQuotaStore,
+  SYSTEM_PROMPT_CONTRIBUTOR_METADATA,
+  SYSTEM_PROMPT_METADATA,
+  SystemPrompt,
+  SystemPromptContributor,
   delegateToolName,
   provideAgentTool,
+  readAgentMetadata,
   readAiToolMetadata,
   utcDay,
   ...require("@dudousxd/nestjs-agent-core")