@dudousxd/nestjs-agent 0.1.0 → 0.3.0

package/dist/index.js

@@ -2,12 +2,12 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/agent.module.ts
-import { AGENT_ACTOR_RESOLVER as AGENT_ACTOR_RESOLVER5, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY3, AGENT_DURABLE_RUNNER, 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_STORE4, 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_FACTORY3, AGENT_DURABLE_RUNNER, 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_STORE4, AGENT_TOOL_REGISTRY as AGENT_TOOL_REGISTRY3, AgentRegistry as AgentRegistry4, DefaultRolesPolicy, ToolRegistry as ToolRegistry3 } from "@dudousxd/nestjs-agent-core";
 import { Global, Module } 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, 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, AGENT_TOOL_REGISTRY, AgentRegistry as AgentRegistry2, ToolRegistry as ToolRegistry2 } from "@dudousxd/nestjs-agent-core";
 import { AGENT_OPTIONS } from "@dudousxd/nestjs-agent-core";
 import { Inject, Injectable } from "@nestjs/common";
 function _ts_decorate(decorators, target, key, desc) {
@@ -42,8 +42,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;
@@ -51,10 +52,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) {
@@ -72,10 +82,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;
@@ -85,10 +91,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
       } : {},
@@ -133,7 +138,8 @@ AgentDepsFactory2 = _ts_decorate([
   _ts_param(4, Inject(AGENT_ROLES_POLICY)),
   _ts_param(5, Inject(AGENT_TOOL_REGISTRY)),
   _ts_param(6, Inject(AGENT_REGISTRY)),
-  _ts_param(7, Inject(AGENT_QUOTA_STORE)),
+  _ts_param(7, Inject(AGENT_PROMPT_CONTRIBUTORS)),
+  _ts_param(8, Inject(AGENT_QUOTA_STORE)),
   _ts_metadata("design:type", Function),
   _ts_metadata("design:paramtypes", [
     typeof AgentModuleOptions === "undefined" ? Object : AgentModuleOptions,
@@ -143,12 +149,13 @@ AgentDepsFactory2 = _ts_decorate([
     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, AGENT_RUNNER, AGENT_STORE as AGENT_STORE2 } from "@dudousxd/nestjs-agent-core";
+import { AGENT_DEPS_FACTORY, AGENT_QUOTA_STORE as AGENT_QUOTA_STORE2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE2 } from "@dudousxd/nestjs-agent-core";
 import { BadRequestException, ForbiddenException, Inject as Inject2, Injectable as Injectable2, NotFoundException } from "@nestjs/common";
 
 // src/agent-deps.ts
@@ -192,10 +199,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();
@@ -206,13 +215,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,
@@ -222,9 +232,6 @@ var AgentService = class {
       ...params.regenerate === true ? {
         regenerate: true
       } : {},
-      ...persona !== void 0 ? {
-        persona
-      } : {},
       ...params.pageContext !== void 0 ? {
         pageContext: params.pageContext
       } : {}
@@ -258,18 +265,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);
   }
@@ -285,8 +280,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
@@ -337,11 +377,13 @@ AgentService = _ts_decorate2([
   _ts_param2(0, Inject2(AGENT_RUNNER)),
   _ts_param2(1, Inject2(AGENT_STORE2)),
   _ts_param2(2, Inject2(AGENT_DEPS_FACTORY)),
+  _ts_param2(3, Inject2(AGENT_QUOTA_STORE2)),
   _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);
 
@@ -386,14 +428,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);
@@ -550,7 +592,7 @@ QuotaController = _ts_decorate4([
 
 // 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 Inject5, 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 Inject5, Param as Param2, Patch, Post as Post2, Req as Req3 } 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") r = Reflect.decorate(decorators, target, key, desc);
@@ -582,9 +624,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);
@@ -600,6 +639,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([
   Get3(),
@@ -610,12 +670,6 @@ _ts_decorate5([
   ]),
   _ts_metadata5("design:returntype", Promise)
 ], ThreadsController.prototype, "list", null);
-_ts_decorate5([
-  Get3("personas/catalog"),
-  _ts_metadata5("design:type", Function),
-  _ts_metadata5("design:paramtypes", []),
-  _ts_metadata5("design:returntype", void 0)
-], ThreadsController.prototype, "personas", null);
 _ts_decorate5([
   Get3(":id"),
   _ts_param5(0, Req3()),
@@ -651,6 +705,43 @@ _ts_decorate5([
   ]),
   _ts_metadata5("design:returntype", Promise)
 ], ThreadsController.prototype, "fork", null);
+_ts_decorate5([
+  Patch(":id"),
+  _ts_param5(0, Req3()),
+  _ts_param5(1, Param2("id")),
+  _ts_param5(2, Body2()),
+  _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([
+  Post2(":id/promote"),
+  _ts_param5(0, Req3()),
+  _ts_param5(1, Param2("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([
+  Delete(":id/from/:messageId"),
+  _ts_param5(0, Req3()),
+  _ts_param5(1, Param2("id")),
+  _ts_param5(2, Param2("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([
   Controller3("threads"),
   _ts_param5(1, Inject5(AGENT_ACTOR_RESOLVER3)),
@@ -663,7 +754,7 @@ ThreadsController = _ts_decorate5([
 
 // 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 Inject6, Post as Post3, Req as Req4 } from "@nestjs/common";
+import { Body as Body3, Controller as Controller4, Inject as Inject6, Post as Post3, Req as Req4 } from "@nestjs/common";
 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") r = Reflect.decorate(decorators, target, key, desc);
@@ -709,7 +800,7 @@ var ToolCallController = class {
 _ts_decorate6([
   Post3("approve"),
   _ts_param6(0, Req4()),
-  _ts_param6(1, Body2()),
+  _ts_param6(1, Body3()),
   _ts_metadata6("design:type", Function),
   _ts_metadata6("design:paramtypes", [
     typeof Request === "undefined" ? Object : Request,
@@ -720,7 +811,7 @@ _ts_decorate6([
 _ts_decorate6([
   Post3("reject"),
   _ts_param6(0, Req4()),
-  _ts_param6(1, Body2()),
+  _ts_param6(1, Body3()),
   _ts_metadata6("design:type", Function),
   _ts_metadata6("design:paramtypes", [
     typeof Request === "undefined" ? Object : Request,
@@ -738,10 +829,170 @@ ToolCallController = _ts_decorate6([
   ])
 ], 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 Inject7, Injectable as Injectable3, 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 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
+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");
+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 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([
+  Injectable3(),
+  _ts_param7(2, Inject7(AGENT_REGISTRY2)),
+  _ts_param7(3, Inject7(AGENT_PROMPT_CONTRIBUTORS2)),
+  _ts_metadata7("design:type", Function),
+  _ts_metadata7("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 Inject8, Injectable as Injectable4, Logger as Logger2 } from "@nestjs/common";
+import { DiscoveryService as DiscoveryService2 } from "@nestjs/core";
 import { z } from "zod";
 
 // src/decorator/ai-tool.decorator.ts
@@ -789,23 +1040,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");
@@ -814,7 +1065,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;
@@ -872,7 +1123,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)) {
@@ -912,14 +1163,14 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
     return true;
   }
 };
-AiToolDiscoveryService = _ts_decorate7([
-  Injectable3(),
-  _ts_param7(1, Inject7(AGENT_TOOL_REGISTRY2)),
-  _ts_param7(2, Inject7(AGENT_REGISTRY2)),
-  _ts_param7(3, Inject7(AGENT_OPTIONS2)),
-  _ts_metadata7("design:type", Function),
-  _ts_metadata7("design:paramtypes", [
-    typeof DiscoveryService === "undefined" ? Object : DiscoveryService,
+AiToolDiscoveryService = _ts_decorate8([
+  Injectable4(),
+  _ts_param8(1, Inject8(AGENT_TOOL_REGISTRY2)),
+  _ts_param8(2, Inject8(AGENT_REGISTRY3)),
+  _ts_param8(3, Inject8(AGENT_OPTIONS2)),
+  _ts_metadata8("design:type", Function),
+  _ts_metadata8("design:paramtypes", [
+    typeof DiscoveryService2 === "undefined" ? Object : DiscoveryService2,
     typeof ToolRegistry === "undefined" ? Object : ToolRegistry,
     typeof AgentRegistry === "undefined" ? Object : AgentRegistry,
     typeof AgentModuleOptions === "undefined" ? Object : AgentModuleOptions
@@ -1019,31 +1270,31 @@ var LedgerQuotaStore = class {
 
 // src/runner/inline-agent-runner.ts
 import { AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, AGENT_STORE as AGENT_STORE3, QuotaExceededError, publishAgentRunFailed, runAgentLoop } from "@dudousxd/nestjs-agent-core";
-import { Inject as Inject8, Injectable as Injectable4, Logger as Logger2 } from "@nestjs/common";
-function _ts_decorate8(decorators, target, key, desc) {
+import { Inject as Inject9, Injectable as Injectable5, Logger as Logger3 } 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);
   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 Logger2(_InlineAgentRunner.name);
+  logger = new Logger3(_InlineAgentRunner.name);
   pending = /* @__PURE__ */ new Map();
   constructor(factory, store) {
     this.factory = factory;
@@ -1108,7 +1359,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();
@@ -1138,50 +1388,41 @@ var InlineAgentRunner = class _InlineAgentRunner {
     }, hooks);
   }
 };
-InlineAgentRunner = _ts_decorate8([
-  Injectable4(),
-  _ts_param8(0, Inject8(AGENT_DEPS_FACTORY2)),
-  _ts_param8(1, Inject8(AGENT_STORE3)),
-  _ts_metadata8("design:type", Function),
-  _ts_metadata8("design:paramtypes", [
+InlineAgentRunner = _ts_decorate9([
+  Injectable5(),
+  _ts_param9(0, Inject9(AGENT_DEPS_FACTORY2)),
+  _ts_param9(1, Inject9(AGENT_STORE3)),
+  _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: 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,
@@ -1215,7 +1456,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,
@@ -1227,6 +1468,9 @@ function sharedProviders(durable, includeStore) {
       provide: AGENT_DEPS_FACTORY3,
       useExisting: AgentDepsFactory2
     },
+    // Populates the registry + contributors (onModuleInit) BEFORE AiToolDiscoveryService synthesizes
+    // handoff tools (onApplicationBootstrap) reads the registry.
+    AgentDiscoveryService,
     AiToolDiscoveryService,
     InlineAgentRunner,
     AgentService
@@ -1269,7 +1513,7 @@ function exportsFor(includeStore) {
   return [
     AGENT_OPTIONS3,
     AGENT_TOOL_REGISTRY3,
-    AGENT_REGISTRY3,
+    AGENT_REGISTRY4,
     AGENT_SINK2,
     AGENT_ROLES_POLICY2,
     AGENT_ACTOR_RESOLVER5,
@@ -1277,7 +1521,8 @@ function exportsFor(includeStore) {
     ...includeStore ? [
       AGENT_STORE4
     ] : [],
-    AGENT_QUOTA_STORE2,
+    AGENT_QUOTA_STORE3,
+    AGENT_PROMPT_CONTRIBUTORS3,
     AGENT_DEPS_FACTORY3,
     AgentDepsFactory2,
     AgentService,
@@ -1349,28 +1594,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_decorate9([
+AgentModule = _ts_decorate10([
   Global(),
   Module({})
 ], AgentModule);
@@ -1408,9 +1633,12 @@ var HeaderActorResolver = class {
 // src/index.ts
 export * from "@dudousxd/nestjs-agent-core";
 export {
+  AGENT_METADATA,
   AGENT_TOOL_BRAND,
   AI_TOOL_METADATA,
+  Agent,
   AgentDepsFactory2 as AgentDepsFactory,
+  AgentDiscoveryService,
   AgentModule,
   AgentService,
   AiTool,
@@ -1419,8 +1647,13 @@ export {
   InProcessTokenStreamSink,
   InlineAgentRunner,
   LedgerQuotaStore,
+  SYSTEM_PROMPT_CONTRIBUTOR_METADATA,
+  SYSTEM_PROMPT_METADATA,
+  SystemPrompt,
+  SystemPromptContributor,
   delegateToolName,
   provideAgentTool,
+  readAgentMetadata,
   readAiToolMetadata,
   utcDay
 };