@dudousxd/nestjs-agent-core 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -89,6 +89,18 @@ interface QuotaState {
     limitTokens: number;
     withinLimit: boolean;
 }
+/**
+ * The read-model the quota-today endpoint returns to a client — a superset of {@link QuotaState}
+ * for rendering a usage badge. `limitTokens` is `null` when no quota is configured (unlimited, so
+ * `withinLimit` is always true); `costUsd` is the day's summed provider-reported USD spend (`0`
+ * when only tokens were reported).
+ */
+interface QuotaView {
+    usedTokens: number;
+    limitTokens: number | null;
+    withinLimit: boolean;
+    costUsd: number;
+}
 /** A human decision on a pending action tool call. */
 interface Decision {
     approved: boolean;
@@ -107,37 +119,35 @@ interface PageContext {
     [key: string]: unknown;
 }
 /**
- * Inputs a {@link PromptBuilder} may use to compose the effective system prompt for a turn.
- * `basePrompt` is the agent's own (already-resolved) base prompt, so a persona builder can wrap
- * or extend it rather than replace it.
+ * Inputs a {@link PromptBuilder} or {@link PromptContributor} may use to compose the system prompt
+ * for a turn. Resolved once per turn from stable inputs (actor / agent / pageContext) so it stays
+ * replay-safe.
  */
 interface PromptContext {
     actor: Actor;
-    persona?: Persona;
+    /** The selected agent's name. */
+    agentName: string;
     pageContext?: PageContext;
-    basePrompt: string;
 }
 /**
- * A dynamic system prompt. Return a string (optionally async) built from the turn's context —
- * e.g. injecting the actor, the current page, or a data-shape description. The loop resolves it
- * once per turn from stable inputs (actor/persona/pageContext), so it stays replay-safe.
+ * An agent's base system prompt. Return a string (optionally async) built from the turn's context —
+ * e.g. injecting the actor, the current page, or a data-shape description. Set on an `@Agent` class
+ * via a `@SystemPrompt()` method (or a flat string).
  */
 type PromptBuilder = (ctx: PromptContext) => string | Promise<string>;
-interface Persona {
-    id: string;
-    label: string;
-    /** A flat prompt, or a {@link PromptBuilder} composed per request from {@link PromptContext}. */
-    systemPrompt: string | PromptBuilder;
-    /** If set, only these tool names are offered (after role filtering). */
-    allowedTools?: string[];
-}
+/**
+ * A cross-agent system-prompt contributor. Returns an ordered section to APPEND to the composed
+ * prompt (after the agent's base), or `null` to contribute nothing this turn — so conditional
+ * sections (base-scope, a mentions legend, schema hints) stay clean when they don't apply.
+ * Registered app-wide via `@SystemPromptContributor()`; the loop runs every contributor in order.
+ */
+type PromptContributor = (ctx: PromptContext) => string | null | Promise<string | null>;
 /** Everything needed to run one agent turn. */
 interface AgentRunInput {
     threadId: string;
     actor: Actor;
     /** The latest user message text. */
     userText: string;
-    persona?: Persona;
     pageContext?: PageContext;
     /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
     day?: string;
@@ -163,10 +173,11 @@ interface AgentRunInput {
     regenerate?: boolean;
 }
 /**
- * A named agent: its prompt, the tools it may use, and its personas. Multiple definitions are
- * registered via `AgentModule.forFeature([...])`; an orchestrator delegates to others through
- * `ctx.runAgent(name, task)`. Model/store/sink/governance are shared from the module unless
- * overridden here.
+ * A named agent: its prompt, the tools it may use, and who it can hand off to. This is the
+ * internal record the loop and `AgentDepsFactory` consume; in an app it is authored as an
+ * `@Agent`-decorated class and populated into the `AgentRegistry` by discovery (name, base prompt
+ * from `@SystemPrompt`, tool allow-list, handoff targets). An orchestrator hands off to others via
+ * `ctx.handoff(OtherAgent)`. Model/store/sink/governance are shared from the module.
  */
 interface AgentDefinition {
     name: string;
@@ -174,17 +185,14 @@ interface AgentDefinition {
     systemPrompt?: string | PromptBuilder;
     /** Allow-list of tool names this agent may use (subset of all registered tools). */
     tools?: string[];
-    /** Names of other agents this agent may delegate to (auto-registered as `agent`-kind tools). */
+    /** Names of other agents this agent may hand off to (auto-registered as `agent`-kind tools). */
     delegatesTo?: string[];
-    personas?: Persona[];
-    defaultPersona?: string;
     modelId?: string;
     maxSteps?: number;
 }
 interface ThreadSummary {
     id: string;
     title: string;
-    persona: string;
     transient: boolean;
     createdAt: string;
     updatedAt: string;
@@ -194,6 +202,8 @@ interface StoredMessage {
     id: string;
     role: MessageRole;
     content: string;
+    /** Which agent produced this message (assistant messages) — provenance for replay / UI / telescope. */
+    agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
     followUps?: string[];
@@ -242,6 +252,8 @@ declare const AGENT_RETRIEVER: unique symbol;
 /** The embedding provider (`EmbeddingProvider`) — text→vector for retrieval + ingestion. */
 declare const AGENT_EMBEDDING_PROVIDER: unique symbol;
 declare const AGENT_DEPS_FACTORY: unique symbol;
+/** App-wide, ordered `@SystemPromptContributor()` functions the loop appends after the agent base. */
+declare const AGENT_PROMPT_CONTRIBUTORS: unique symbol;
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -253,7 +265,8 @@ interface AiToolCtx {
     threadId: string;
     runId: string;
     requestId: string;
-    persona?: Persona;
+    /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
+    agentName?: string;
     pageContext?: PageContext;
     /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
     host?: unknown;
@@ -348,7 +361,6 @@ interface ModelProvider {
 
 interface CreateThreadInput {
     actor: Actor;
-    persona: string;
     transient?: boolean;
     title?: string;
 }
@@ -356,7 +368,8 @@ interface AppendMessageInput {
     threadId: string;
     role: StoredMessage['role'];
     content: string;
-    persona?: string;
+    /** Which agent produced this message (assistant messages) — provenance. */
+    agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
     followUps?: string[];
@@ -396,6 +409,12 @@ interface AgentStore {
     softDeleteThread(threadId: string): Promise<void>;
     forkThread(threadId: string, fromMessageId: string): Promise<ThreadSummary>;
     setTitle(threadId: string, title: string): Promise<void>;
+    /**
+     * Promote a transient thread to a persistent one so it shows up in {@link listThreads}. A
+     * transient thread is a scratch conversation the caller has not chosen to keep; "saving" it
+     * clears the flag. Idempotent — promoting an already-persistent thread is a no-op.
+     */
+    promoteThread(threadId: string): Promise<void>;
     setActiveStream(threadId: string, runId: string | null): Promise<void>;
     /**
      * The `actorRef` that owns a thread, or `null` if no such thread exists. The authorization seam
@@ -427,8 +446,14 @@ interface AgentStore {
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;
     recordUsage(input: RecordUsageInput): Promise<void>;
+    /**
+     * The actor's spend for `day` (UTC): total tokens plus the summed provider-reported USD cost.
+     * `costUsd` is `0` when no turn on that day reported a cost (token-only providers). Feeds both
+     * quota enforcement (via {@link QuotaStore}) and the quota-today view.
+     */
     quotaToday(actorRef: string, day: string): Promise<{
         usedTokens: number;
+        costUsd: number;
     }>;
 }
 
@@ -646,8 +671,8 @@ interface AgentGovernanceQueries {
 
 /** First filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
 declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: RolesPolicy): Promise<ToolSpec[]>;
-/** Second filter layer: if the persona pins an allow-list, keep only those tool names. */
-declare function personaFilterTools(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
+/** Second filter layer: if the agent pins an allow-list, keep only those tool names. */
+declare function filterToolsByAllowList(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
 
 /** Holds the named agent definitions registered via `AgentModule.forFeature([...])`. */
 declare class AgentRegistry {
@@ -687,7 +712,7 @@ declare class ToolRegistry {
     has(name: string): boolean;
     spec(name: string): ToolSpec | undefined;
     allSpecs(): ToolSpec[];
-    /** The tools to offer the model for this actor+persona, after the two filter layers. */
+    /** The tools to offer the model for this actor+agent, after the two filter layers. */
     definitionsFor(actor: Actor, policy: RolesPolicy, allowedTools?: string[]): Promise<ToolDefinition[]>;
     /** Run a tool. Re-checks the role (defense-in-depth) and re-parses the input via Zod. */
     invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
@@ -714,10 +739,16 @@ interface AgentLoopDeps {
     day: string;
     /** The agent's base prompt. A flat string, or a {@link PromptBuilder} resolved per turn. */
     systemPrompt: string | PromptBuilder;
+    /**
+     * Cross-agent system-prompt contributors, applied in order AFTER the agent's base prompt. Each
+     * returns a section to append (or `null` to skip this turn). The app registers them via
+     * `@SystemPromptContributor()`; the loop composes base + contributors into the effective prompt.
+     */
+    promptContributors?: PromptContributor[];
     maxSteps?: number;
     /** Optional host handle threaded to tool ctx (e.g. an ORM EntityManager). */
     host?: unknown;
-    /** Agent-level tool allow-list (intersected with the persona's). Undefined → all tools. */
+    /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
     /**
      * Per-tool execution timeout in ms. A tool that runs longer is aborted and recorded as failed
@@ -777,7 +808,8 @@ interface AgentRunStarted {
     runId: string;
     threadId: string;
     actorId: string;
-    persona?: string;
+    /** Which agent is handling the run. */
+    agentName?: string;
 }
 interface AgentMessageEvent {
     runId: string;
@@ -845,4 +877,4 @@ declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
 
-export { AGENT_ACTOR_RESOLVER, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorResolver, type ActorSpendRow, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type MessageRole, type MessageUsage, type ModelMessage, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type Persona, type PromptBuilder, type PromptContext, QuotaExceededError, type QuotaState, type QuotaStore, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, filterToolsByRole, personaFilterTools, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };
+export { AGENT_ACTOR_RESOLVER, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorResolver, type ActorSpendRow, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type MessageRole, type MessageUsage, type ModelMessage, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };

package/dist/index.d.ts

@@ -89,6 +89,18 @@ interface QuotaState {
     limitTokens: number;
     withinLimit: boolean;
 }
+/**
+ * The read-model the quota-today endpoint returns to a client — a superset of {@link QuotaState}
+ * for rendering a usage badge. `limitTokens` is `null` when no quota is configured (unlimited, so
+ * `withinLimit` is always true); `costUsd` is the day's summed provider-reported USD spend (`0`
+ * when only tokens were reported).
+ */
+interface QuotaView {
+    usedTokens: number;
+    limitTokens: number | null;
+    withinLimit: boolean;
+    costUsd: number;
+}
 /** A human decision on a pending action tool call. */
 interface Decision {
     approved: boolean;
@@ -107,37 +119,35 @@ interface PageContext {
     [key: string]: unknown;
 }
 /**
- * Inputs a {@link PromptBuilder} may use to compose the effective system prompt for a turn.
- * `basePrompt` is the agent's own (already-resolved) base prompt, so a persona builder can wrap
- * or extend it rather than replace it.
+ * Inputs a {@link PromptBuilder} or {@link PromptContributor} may use to compose the system prompt
+ * for a turn. Resolved once per turn from stable inputs (actor / agent / pageContext) so it stays
+ * replay-safe.
  */
 interface PromptContext {
     actor: Actor;
-    persona?: Persona;
+    /** The selected agent's name. */
+    agentName: string;
     pageContext?: PageContext;
-    basePrompt: string;
 }
 /**
- * A dynamic system prompt. Return a string (optionally async) built from the turn's context —
- * e.g. injecting the actor, the current page, or a data-shape description. The loop resolves it
- * once per turn from stable inputs (actor/persona/pageContext), so it stays replay-safe.
+ * An agent's base system prompt. Return a string (optionally async) built from the turn's context —
+ * e.g. injecting the actor, the current page, or a data-shape description. Set on an `@Agent` class
+ * via a `@SystemPrompt()` method (or a flat string).
  */
 type PromptBuilder = (ctx: PromptContext) => string | Promise<string>;
-interface Persona {
-    id: string;
-    label: string;
-    /** A flat prompt, or a {@link PromptBuilder} composed per request from {@link PromptContext}. */
-    systemPrompt: string | PromptBuilder;
-    /** If set, only these tool names are offered (after role filtering). */
-    allowedTools?: string[];
-}
+/**
+ * A cross-agent system-prompt contributor. Returns an ordered section to APPEND to the composed
+ * prompt (after the agent's base), or `null` to contribute nothing this turn — so conditional
+ * sections (base-scope, a mentions legend, schema hints) stay clean when they don't apply.
+ * Registered app-wide via `@SystemPromptContributor()`; the loop runs every contributor in order.
+ */
+type PromptContributor = (ctx: PromptContext) => string | null | Promise<string | null>;
 /** Everything needed to run one agent turn. */
 interface AgentRunInput {
     threadId: string;
     actor: Actor;
     /** The latest user message text. */
     userText: string;
-    persona?: Persona;
     pageContext?: PageContext;
     /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
     day?: string;
@@ -163,10 +173,11 @@ interface AgentRunInput {
     regenerate?: boolean;
 }
 /**
- * A named agent: its prompt, the tools it may use, and its personas. Multiple definitions are
- * registered via `AgentModule.forFeature([...])`; an orchestrator delegates to others through
- * `ctx.runAgent(name, task)`. Model/store/sink/governance are shared from the module unless
- * overridden here.
+ * A named agent: its prompt, the tools it may use, and who it can hand off to. This is the
+ * internal record the loop and `AgentDepsFactory` consume; in an app it is authored as an
+ * `@Agent`-decorated class and populated into the `AgentRegistry` by discovery (name, base prompt
+ * from `@SystemPrompt`, tool allow-list, handoff targets). An orchestrator hands off to others via
+ * `ctx.handoff(OtherAgent)`. Model/store/sink/governance are shared from the module.
  */
 interface AgentDefinition {
     name: string;
@@ -174,17 +185,14 @@ interface AgentDefinition {
     systemPrompt?: string | PromptBuilder;
     /** Allow-list of tool names this agent may use (subset of all registered tools). */
     tools?: string[];
-    /** Names of other agents this agent may delegate to (auto-registered as `agent`-kind tools). */
+    /** Names of other agents this agent may hand off to (auto-registered as `agent`-kind tools). */
     delegatesTo?: string[];
-    personas?: Persona[];
-    defaultPersona?: string;
     modelId?: string;
     maxSteps?: number;
 }
 interface ThreadSummary {
     id: string;
     title: string;
-    persona: string;
     transient: boolean;
     createdAt: string;
     updatedAt: string;
@@ -194,6 +202,8 @@ interface StoredMessage {
     id: string;
     role: MessageRole;
     content: string;
+    /** Which agent produced this message (assistant messages) — provenance for replay / UI / telescope. */
+    agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
     followUps?: string[];
@@ -242,6 +252,8 @@ declare const AGENT_RETRIEVER: unique symbol;
 /** The embedding provider (`EmbeddingProvider`) — text→vector for retrieval + ingestion. */
 declare const AGENT_EMBEDDING_PROVIDER: unique symbol;
 declare const AGENT_DEPS_FACTORY: unique symbol;
+/** App-wide, ordered `@SystemPromptContributor()` functions the loop appends after the agent base. */
+declare const AGENT_PROMPT_CONTRIBUTORS: unique symbol;
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -253,7 +265,8 @@ interface AiToolCtx {
     threadId: string;
     runId: string;
     requestId: string;
-    persona?: Persona;
+    /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
+    agentName?: string;
     pageContext?: PageContext;
     /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
     host?: unknown;
@@ -348,7 +361,6 @@ interface ModelProvider {
 
 interface CreateThreadInput {
     actor: Actor;
-    persona: string;
     transient?: boolean;
     title?: string;
 }
@@ -356,7 +368,8 @@ interface AppendMessageInput {
     threadId: string;
     role: StoredMessage['role'];
     content: string;
-    persona?: string;
+    /** Which agent produced this message (assistant messages) — provenance. */
+    agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
     followUps?: string[];
@@ -396,6 +409,12 @@ interface AgentStore {
     softDeleteThread(threadId: string): Promise<void>;
     forkThread(threadId: string, fromMessageId: string): Promise<ThreadSummary>;
     setTitle(threadId: string, title: string): Promise<void>;
+    /**
+     * Promote a transient thread to a persistent one so it shows up in {@link listThreads}. A
+     * transient thread is a scratch conversation the caller has not chosen to keep; "saving" it
+     * clears the flag. Idempotent — promoting an already-persistent thread is a no-op.
+     */
+    promoteThread(threadId: string): Promise<void>;
     setActiveStream(threadId: string, runId: string | null): Promise<void>;
     /**
      * The `actorRef` that owns a thread, or `null` if no such thread exists. The authorization seam
@@ -427,8 +446,14 @@ interface AgentStore {
     recordToolCall(input: RecordToolCallInput): Promise<void>;
     updateToolCall(input: UpdateToolCallInput): Promise<void>;
     recordUsage(input: RecordUsageInput): Promise<void>;
+    /**
+     * The actor's spend for `day` (UTC): total tokens plus the summed provider-reported USD cost.
+     * `costUsd` is `0` when no turn on that day reported a cost (token-only providers). Feeds both
+     * quota enforcement (via {@link QuotaStore}) and the quota-today view.
+     */
     quotaToday(actorRef: string, day: string): Promise<{
         usedTokens: number;
+        costUsd: number;
     }>;
 }
 
@@ -646,8 +671,8 @@ interface AgentGovernanceQueries {
 
 /** First filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
 declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: RolesPolicy): Promise<ToolSpec[]>;
-/** Second filter layer: if the persona pins an allow-list, keep only those tool names. */
-declare function personaFilterTools(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
+/** Second filter layer: if the agent pins an allow-list, keep only those tool names. */
+declare function filterToolsByAllowList(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
 
 /** Holds the named agent definitions registered via `AgentModule.forFeature([...])`. */
 declare class AgentRegistry {
@@ -687,7 +712,7 @@ declare class ToolRegistry {
     has(name: string): boolean;
     spec(name: string): ToolSpec | undefined;
     allSpecs(): ToolSpec[];
-    /** The tools to offer the model for this actor+persona, after the two filter layers. */
+    /** The tools to offer the model for this actor+agent, after the two filter layers. */
     definitionsFor(actor: Actor, policy: RolesPolicy, allowedTools?: string[]): Promise<ToolDefinition[]>;
     /** Run a tool. Re-checks the role (defense-in-depth) and re-parses the input via Zod. */
     invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
@@ -714,10 +739,16 @@ interface AgentLoopDeps {
     day: string;
     /** The agent's base prompt. A flat string, or a {@link PromptBuilder} resolved per turn. */
     systemPrompt: string | PromptBuilder;
+    /**
+     * Cross-agent system-prompt contributors, applied in order AFTER the agent's base prompt. Each
+     * returns a section to append (or `null` to skip this turn). The app registers them via
+     * `@SystemPromptContributor()`; the loop composes base + contributors into the effective prompt.
+     */
+    promptContributors?: PromptContributor[];
     maxSteps?: number;
     /** Optional host handle threaded to tool ctx (e.g. an ORM EntityManager). */
     host?: unknown;
-    /** Agent-level tool allow-list (intersected with the persona's). Undefined → all tools. */
+    /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
     /**
      * Per-tool execution timeout in ms. A tool that runs longer is aborted and recorded as failed
@@ -777,7 +808,8 @@ interface AgentRunStarted {
     runId: string;
     threadId: string;
     actorId: string;
-    persona?: string;
+    /** Which agent is handling the run. */
+    agentName?: string;
 }
 interface AgentMessageEvent {
     runId: string;
@@ -845,4 +877,4 @@ declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
 
-export { AGENT_ACTOR_RESOLVER, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorResolver, type ActorSpendRow, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type MessageRole, type MessageUsage, type ModelMessage, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type Persona, type PromptBuilder, type PromptContext, QuotaExceededError, type QuotaState, type QuotaStore, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, filterToolsByRole, personaFilterTools, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };
+export { AGENT_ACTOR_RESOLVER, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorResolver, type ActorSpendRow, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type MessageRole, type MessageUsage, type ModelMessage, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };

package/dist/index.js

@@ -18,6 +18,7 @@ var AGENT_PRICING_STORE = Symbol.for("@dudousxd/nestjs-agent:pricing-store");
 var AGENT_RETRIEVER = Symbol.for("@dudousxd/nestjs-agent:retriever");
 var AGENT_EMBEDDING_PROVIDER = Symbol.for("@dudousxd/nestjs-agent:embedding-provider");
 var AGENT_DEPS_FACTORY = Symbol.for("@dudousxd/nestjs-agent:deps-factory");
+var AGENT_PROMPT_CONTRIBUTORS = Symbol.for("@dudousxd/nestjs-agent:prompt-contributors");
 
 // src/spi/token-stream-sink.ts
 var AgentStreamError = class extends Error {
@@ -40,7 +41,7 @@ async function seedModelPrices(store, prices) {
 }
 __name(seedModelPrices, "seedModelPrices");
 
-// src/personas.ts
+// src/tool-filters.ts
 async function filterToolsByRole(tools, actor, policy) {
   const checked = await Promise.all(tools.map(async (tool) => ({
     tool,
@@ -49,14 +50,14 @@ async function filterToolsByRole(tools, actor, policy) {
   return checked.filter((entry) => entry.allowed).map((entry) => entry.tool);
 }
 __name(filterToolsByRole, "filterToolsByRole");
-function personaFilterTools(tools, allowedTools) {
+function filterToolsByAllowList(tools, allowedTools) {
   if (allowedTools === void 0) {
     return tools;
   }
   const allowed = new Set(allowedTools);
   return tools.filter((tool) => allowed.has(tool.name));
 }
-__name(personaFilterTools, "personaFilterTools");
+__name(filterToolsByAllowList, "filterToolsByAllowList");
 
 // src/agent-registry.ts
 var AgentRegistry = class {
@@ -134,11 +135,11 @@ var ToolRegistry = class {
       ...this.entries.values()
     ].map((entry) => entry.spec);
   }
-  /** The tools to offer the model for this actor+persona, after the two filter layers. */
+  /** The tools to offer the model for this actor+agent, after the two filter layers. */
   async definitionsFor(actor, policy, allowedTools) {
     const roleScoped = await filterToolsByRole(this.allSpecs(), actor, policy);
-    const personaScoped = personaFilterTools(roleScoped, allowedTools);
-    return personaScoped.map((spec) => ({
+    const allowScoped = filterToolsByAllowList(roleScoped, allowedTools);
+    return allowScoped.map((spec) => ({
       name: spec.name,
       kind: spec.kind,
       description: spec.description,
@@ -224,17 +225,6 @@ ${items}
 Use the retrieved context above to answer when relevant, and cite sources by their bracket number.`;
 }
 __name(buildContextBlock, "buildContextBlock");
-function intersectAllow(a, b) {
-  if (a === void 0) {
-    return b;
-  }
-  if (b === void 0) {
-    return a;
-  }
-  const second = new Set(b);
-  return a.filter((name) => second.has(name));
-}
-__name(intersectAllow, "intersectAllow");
 var QuotaExceededError = class extends Error {
   static {
     __name(this, "QuotaExceededError");
@@ -250,26 +240,23 @@ async function resolvePrompt(prompt, ctx) {
 }
 __name(resolvePrompt, "resolvePrompt");
 async function resolveSystemPrompt(deps, input) {
-  const base = {
+  const ctx = {
     actor: input.actor,
-    ...input.persona !== void 0 ? {
-      persona: input.persona
-    } : {},
+    agentName: input.agentName ?? "default",
     ...input.pageContext !== void 0 ? {
       pageContext: input.pageContext
     } : {}
   };
-  const basePrompt = await resolvePrompt(deps.systemPrompt, {
-    ...base,
-    basePrompt: ""
-  });
-  if (input.persona === void 0) {
-    return basePrompt;
+  const sections = [
+    await resolvePrompt(deps.systemPrompt, ctx)
+  ];
+  for (const contribute of deps.promptContributors ?? []) {
+    const section = await contribute(ctx);
+    if (section !== null && section.length > 0) {
+      sections.push(section);
+    }
   }
-  return resolvePrompt(input.persona.systemPrompt, {
-    ...base,
-    basePrompt
-  });
+  return sections.join("\n\n");
 }
 __name(resolveSystemPrompt, "resolveSystemPrompt");
 function extractTask(input) {
@@ -347,7 +334,6 @@ async function generateFollowUps(model, messages, count) {
 __name(generateFollowUps, "generateFollowUps");
 async function runAgentLoop(deps, input, hooks) {
   const maxSteps = deps.maxSteps ?? 8;
-  const persona = input.persona;
   let system = await resolveSystemPrompt(deps, input);
   if (deps.quota !== void 0) {
     const quota = deps.quota;
@@ -381,10 +367,7 @@ async function runAgentLoop(deps, input, hooks) {
     await hooks.step("persist:user", () => deps.store.appendMessage({
       threadId: input.threadId,
       role: "user",
-      content: input.userText,
-      ...persona !== void 0 ? {
-        persona: persona.id
-      } : {}
+      content: input.userText
     }));
   }
   const thread = await hooks.step("load:thread", () => deps.store.getThread(input.threadId));
@@ -407,8 +390,8 @@ async function runAgentLoop(deps, input, hooks) {
     runId: hooks.runId,
     threadId: input.threadId,
     actorId: input.actor.id,
-    ...persona !== void 0 ? {
-      persona: persona.id
+    ...input.agentName !== void 0 ? {
+      agentName: input.agentName
     } : {}
   });
   let injectedPassages;
@@ -430,7 +413,7 @@ ${buildContextBlock(passages)}`;
     });
   }
   for (let i = 0; i < maxSteps; i += 1) {
-    const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, intersectAllow(persona?.allowedTools, deps.toolAllowList));
+    const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList);
     const turn = await hooks.step(`llm:${i}`, () => deps.model.runTurn({
       system,
       messages: modelMessages,
@@ -490,8 +473,8 @@ ${buildContextBlock(passages)}`;
       role: "assistant",
       content: turn.text,
       usage: turn.usage,
-      ...persona !== void 0 ? {
-        persona: persona.id
+      ...input.agentName !== void 0 ? {
+        agentName: input.agentName
       } : {},
       ...turn.toolCalls.length > 0 ? {
         toolCalls: turn.toolCalls
@@ -542,8 +525,8 @@ ${buildContextBlock(passages)}`;
         threadId: input.threadId,
         runId: hooks.runId,
         requestId: hooks.runId,
-        ...persona !== void 0 ? {
-          persona
+        ...input.agentName !== void 0 ? {
+          agentName: input.agentName
         } : {},
         ...input.pageContext !== void 0 ? {
           pageContext: input.pageContext
@@ -721,6 +704,7 @@ export {
   AGENT_MODEL,
   AGENT_OPTIONS,
   AGENT_PRICING_STORE,
+  AGENT_PROMPT_CONTRIBUTORS,
   AGENT_QUOTA_STORE,
   AGENT_REGISTRY,
   AGENT_RETRIEVER,
@@ -737,8 +721,8 @@ export {
   ToolInputInvalidError,
   ToolNotFoundError,
   ToolRegistry,
+  filterToolsByAllowList,
   filterToolsByRole,
-  personaFilterTools,
   publishAgentDelegated,
   publishAgentMessage,
   publishAgentQuotaExceeded,