@dudousxd/nestjs-agent-core 0.38.0 → 0.39.0

package/dist/{processors-D5110pit.d.ts → processors-6p9nrqEi.d.cts}

@@ -1,4 +1,4 @@
-import { M as ModelMessage, a as Actor, d as ToolCallRequest } from './stream-events-CgWqAI-1.js';
+import { M as ModelMessage, a as Actor, d as ToolCallRequest } from './stream-events-CbVEowYb.cjs';
 
 /**
  * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites
@@ -23,6 +23,8 @@ interface ProcessorContext {
     actor: Actor;
     /** The agent running this turn. Undefined → the default agent. */
     agentName?: string;
+    /** The persona the turn runs under, when it runs under one. */
+    persona?: string;
     /** 0-based model step within the run — the same index the `llm:<step>` checkpoint carries. */
     step: number;
 }

package/dist/{processors-C0snQzZJ.d.cts → processors-Bp5XmF6V.d.ts}

@@ -1,4 +1,4 @@
-import { M as ModelMessage, a as Actor, d as ToolCallRequest } from './stream-events-CgWqAI-1.cjs';
+import { M as ModelMessage, a as Actor, d as ToolCallRequest } from './stream-events-CbVEowYb.js';
 
 /**
  * The two seams that see a turn's traffic to and from the model: an {@link InputProcessor} rewrites
@@ -23,6 +23,8 @@ interface ProcessorContext {
     actor: Actor;
     /** The agent running this turn. Undefined → the default agent. */
     agentName?: string;
+    /** The persona the turn runs under, when it runs under one. */
+    persona?: string;
     /** 0-based model step within the run — the same index the `llm:<step>` checkpoint carries. */
     step: number;
 }

package/dist/{stream-events-CgWqAI-1.d.cts → stream-events-CbVEowYb.d.cts}

@@ -115,6 +115,8 @@ interface CreateThreadInput {
      * included).
      */
     id?: string;
+    /** The persona the thread's turns run under when a send names none. See {@link ThreadSummary.persona}. */
+    persona?: string;
 }
 interface AppendMessageInput {
     threadId: string;
@@ -122,6 +124,8 @@ interface AppendMessageInput {
     content: string;
     /** Which agent produced this message (assistant messages) — provenance. */
     agentName?: string;
+    /** The persona the turn ran under. See {@link StoredMessage.persona}. */
+    persona?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
     /** Files the user attached to this message (image/PDF). Persisted verbatim. */
@@ -191,6 +195,8 @@ interface UpdateThreadInput {
     defaultAgent?: string | null;
     /** `null` unpins the thread's model (turns run on the provider default). */
     model?: string | null;
+    /** `null` clears the thread's persona (sends fall back to the agent's default persona). */
+    persona?: string | null;
 }
 interface RecordUsageInput {
     threadId: string;
@@ -421,6 +427,11 @@ interface AgentStore {
      * would be pinned for ever with nothing pointing at them. Answering from the surviving message
      * rows on every call is the only form of this that stays true after a truncation.
      *
+     * A message WAITING IN A THREAD'S QUEUE ({@link import('./chat-queue.js').ChatQueueStore}) counts
+     * too: it has been sent, it just has not run yet, and the turn it is waiting to start will read
+     * its attachments — a sweep that collected them would fail that turn. That holds for a paused
+     * queue as well. Removing the message, or editing its attachments away, frees them again.
+     *
      * Scoped to one actor, like every other read on this surface: media referenced only by ANOTHER
      * actor's thread is reported unreferenced here, so this can never be turned into a probe for what
      * exists in someone else's conversation. A host pairs it with its own per-actor inventory, so the
@@ -485,6 +496,8 @@ interface QueuedMessage {
     content: string;
     attachments?: MessageAttachment[];
     agentName?: string;
+    /** The persona the send resolved (explicit, the thread's, or the agent's default) — what it starts under. */
+    persona?: string;
     model?: string;
     pageContext?: PageContext;
     /**
@@ -501,6 +514,7 @@ interface QueuedMessageView {
     content: string;
     attachments?: MessageAttachment[];
     agentName?: string;
+    persona?: string;
     model?: string;
     interrupt?: boolean;
     createdAt: string;
@@ -521,6 +535,7 @@ interface EnqueueMessageInput {
     content: string;
     attachments?: MessageAttachment[];
     agentName?: string;
+    persona?: string;
     model?: string;
     pageContext?: PageContext;
     interrupt?: boolean;
@@ -1134,6 +1149,70 @@ interface PromptContext {
     /** The selected agent's name. */
     agentName: string;
     pageContext?: PageContext;
+    /**
+     * The persona this turn runs under, when it runs under one — so an agent's own `@SystemPrompt`
+     * (or a contributor) can vary by persona without the persona carrying a prompt of its own.
+     */
+    persona?: PersonaRef;
+    /**
+     * The agent's own resolved base prompt. Set only while a persona's {@link Persona.systemPrompt} is
+     * being resolved, so a persona builder can wrap the base rather than discard it.
+     */
+    basePrompt?: string;
+}
+/**
+ * A named variant of ONE agent: its own prompt and, optionally, a narrower tool allow-list. The
+ * caller picks one per send (`POST <base>/chat { persona }`); everything else — the agent's model,
+ * its access rules, its handoffs, its history — stays the agent's. A variant that needs any of those
+ * to differ is a different `@Agent`, not a persona.
+ */
+interface Persona {
+    /** Unique within its agent — what a send names and what a message records. */
+    id: string;
+    /** What a picker shows. */
+    label: string;
+    /** One line about what the persona is for, for a picker. */
+    description?: string;
+    /**
+     * The persona's prompt. A flat string STANDS IN FOR the agent's base prompt; a
+     * {@link PromptBuilder} is handed that base as `ctx.basePrompt`, so it can wrap it instead. The
+     * cross-agent contributors still follow either way. Omit → the agent's base prompt, unchanged
+     * (which can itself read `ctx.persona`).
+     */
+    systemPrompt?: string | PromptBuilder;
+    /**
+     * Only these tool names are offered — and only these may be invoked — under this persona. Layered
+     * AFTER the agent's own allow-list, `enabled`, the roles policy and `canUse`: it narrows, never
+     * widens. Omit → whatever the agent offers.
+     */
+    allowedTools?: string[];
+    /**
+     * Agent names this persona answers for: a send, a queued message or a thread that names one of
+     * them runs as THIS agent under THIS persona. For an app that turns separate agents into personas
+     * of one — the threads, messages and in-flight runs that recorded the old agent name keep
+     * resolving, with no data migration.
+     */
+    aliases?: string[];
+}
+/** What a prompt builder and a tool see of the turn's persona. */
+interface PersonaRef {
+    id: string;
+    label: string;
+}
+/**
+ * A persona as a turn RESOLVED it, journaled in the `persona:resolve` checkpoint — so every replay
+ * of the run uses this, and not whatever the persona's configuration says by the time it resumes.
+ */
+interface TurnPersona extends PersonaRef {
+    allowedTools?: string[];
+    /** The persona's prompt, resolved (with the base prompt it wraps). Absent → the base prompt. */
+    prompt?: string;
+}
+/** One persona as `GET <base>/agents` lists it — what a persona picker renders. */
+interface PersonaCatalogEntry {
+    id: string;
+    label: string;
+    description?: string;
 }
 /**
  * An agent's base system prompt. Return a string (optionally async) built from the turn's context —
@@ -1161,6 +1240,13 @@ interface AgentRunInput {
     day?: string;
     /** Which named agent runs this turn. Omitted → the default/single agent. */
     agentName?: string;
+    /**
+     * The persona of {@link agentName} this turn runs under (a {@link Persona.id}). Resolved by the
+     * service from the send, the thread and the agent's default BEFORE the run starts, so it is part
+     * of the run's own input; the loop resolves its definition once, in the `persona:resolve`
+     * checkpoint. Omitted → no persona, and no checkpoint spent on one.
+     */
+    persona?: string;
     /**
      * How many agent→agent delegations deep this run already is (0 for a top-level turn). The runner
      * increments it for each child run; the loop refuses to delegate past its depth ceiling.
@@ -1268,6 +1354,10 @@ interface AgentDefinition {
      * Whether this agent is offered the built-in `ask` tool. Undefined → the module-wide setting.
      */
     ask?: boolean;
+    /** Named variants of this agent — see {@link Persona}. Undefined → none. */
+    personas?: Persona[];
+    /** The persona a send runs under when neither it nor its thread names one. Undefined → none. */
+    defaultPersona?: string;
 }
 /**
  * The read-model the `GET agents` endpoint returns to a client — the safe public subset of an
@@ -1283,6 +1373,10 @@ interface AgentCatalogEntry {
      * so before a chat starts. `GET <base>/models?agent=` reports the same lock as `locked`.
      */
     lockedModel?: string;
+    /** The agent's personas, for a persona picker. Omitted when it declares none. */
+    personas?: PersonaCatalogEntry[];
+    /** The persona a send runs under when it names none. Omitted when the agent has no default. */
+    defaultPersona?: string;
 }
 interface ThreadSummary {
     id: string;
@@ -1309,6 +1403,12 @@ interface ThreadSummary {
      * it; the REST read-model normalizes that to `null`.
      */
     model?: string | null;
+    /**
+     * The persona this thread's turns run under when a send names none — the last one a send on it
+     * named, or `PATCH <base>/threads/:id { persona }`. `null` → the agent's default. Undefined for a
+     * store that does not persist it; the REST read-model normalizes that to `null`.
+     */
+    persona?: string | null;
 }
 interface StoredMessage {
     id: string;
@@ -1316,6 +1416,8 @@ interface StoredMessage {
     content: string;
     /** Which agent produced this message (assistant messages) — provenance for replay / UI / telescope. */
     agentName?: string;
+    /** The persona the turn that wrote this message ran under; absent when it ran under none. */
+    persona?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
     /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
@@ -1426,6 +1528,11 @@ interface LlmStepEnvelope {
     bufferOutput?: boolean;
     /** The turn's selected model ({@link AgentRunInput.model}), for the worker's provider call. */
     model?: string;
+    /**
+     * The allow-list of the persona the turn resolved (`persona:resolve`), which the serving worker
+     * intersects with the agent's own. Absent → no persona narrowing, as before personas existed.
+     */
+    personaAllowedTools?: string[];
 }
 /**
  * The serializable subset of `AiToolCtx` — everything except `host` (re-attached handler-side
@@ -1437,6 +1544,8 @@ interface ToolStepCtx {
     runId: string;
     requestId: string;
     agentName?: string;
+    /** The persona the turn runs under ({@link AiToolCtx.persona}). */
+    persona?: string;
     pageContext?: PageContext;
 }
 /** Serializable input for a dispatched tool-execution step. */
@@ -1444,6 +1553,11 @@ interface ToolStepEnvelope {
     toolName: string;
     input: unknown;
     ctx: ToolStepCtx;
+    /**
+     * The only tool names this call may invoke — the turn's persona allow-list (intersected with the
+     * agent's). Checked by `ToolRegistry.invoke` on the worker. Absent → no such check.
+     */
+    allowedTools?: string[];
     /** Applied INSIDE the handler (`withToolTimeout`) — never as a durable step `timeoutMs`. */
     timeoutMs?: number;
     /**
@@ -1952,4 +2066,4 @@ type AgentStreamErrorCode = 'quota_exceeded' | 'output_rejected' | 'structured_o
 /** A model call ended without producing anything. */
  | 'model_no_output' | 'run_failed';
 
-export { type AgentApprovalSettlement as $, type AgentStreamEvent as A, type QueuedMessage as B, type ChatQueueStore as C, type DetachedDelivery as D, type ElicitationRequest as E, type QueuedMessagePatch as F, type QueuePause as G, type HumanReply as H, type AppendMessageInput as I, type ToolResult as J, type MessageFeedback as K, type LlmStepEnvelope as L, type ModelMessage as M, type RecordToolCallInput as N, type ToolCallOutcome as O, type PageContext as P, type QuotaState as Q, type RecordRunStartInput as R, type StoredMessage as S, type ToolSpec as T, type UpdateThreadInput as U, type UpdateToolCallInput as V, type RecordUsageInput as W, ALL_AGENTS as X, ASK_TOOL_DESCRIPTION as Y, ASK_TOOL_NAME as Z, type AgentApprovalRequest as _, type Actor as a, settleDanglingToolCalls as a$, type AgentAttachmentConfig as a0, type AgentCatalogEntry as a1, type AgentClientConfig as a2, type AgentHistoryWindow as a3, type AgentStreamErrorCode as a4, type AskToolInput as a5, type ChatQueueState as a6, DEFAULT_INTAKE_PREAMBLE as a7, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as a8, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as a9, type ToolConfirmation as aA, type ToolPresentationTone as aB, type ToolResultField as aC, type ToolResultView as aD, type ToolStepCtx as aE, type ToolTransientRetryNumbers as aF, type ToolTransientRetryOptions as aG, UNFINISHED_TOOL_CALL as aH, type UsagePurpose as aI, askInputSchema as aJ, askToolDefinition as aK, danglingToolCallIds as aL, decodeStreamEvent as aM, encodeStreamEvent as aN, invokeWithTransientRetry as aO, isChatQueueStore as aP, isTransientToolError as aQ, isTypedQuestion as aR, normalizeElicitationReply as aS, questionOptions as aT, queuedMessageView as aU, readElicitationInput as aV, readElicitationQuestions as aW, releaseThreadRun as aX, renderElicitationAnswers as aY, resolveElicitation as aZ, resolveToolTransientRetryNumbers as a_, ELICITATION_INPUT_TYPES as aa, type ElicitationInput as ab, type ElicitationInputType as ac, type ElicitationOption as ad, type ElicitationOutcome as ae, type ElicitationQuestion as af, type ElicitationReply as ag, type ElicitationResult as ah, type HistoryPolicyContext as ai, type HistorySelection as aj, type HistorySummary as ak, type InvokeWithTransientRetryOptions as al, MAX_ASK_QUESTIONS as am, type MessageFeedbackValue as an, type MessageRole as ao, type PromptContext as ap, type QueuePauseReason as aq, type QueuedMessageView as ar, type QuotaView as as, RUN_ENDED_BEFORE_TOOL_CALL as at, type RecordRunEndInput as au, type ThreadTurnPage as av, type ThreadTurnQuery as aw, type ThreadTurnReader as ax, type ToolCallApprovalStatus as ay, type ToolCatalogEntry as az, type ToolPresentation as b, settleElicitation as b0, validateElicitationAnswer as b1, validateElicitationValue as b2, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AgentRunInput as g, type MessageAttachment as h, type ToolKind as i, type ToolCallStatus as j, type ToolCallApproval as k, type HistoryPolicy as l, type AgentDefinition as m, type AgentStore as n, type AgentDelegation as o, type PromptBuilder as p, type PromptContributor as q, type ToolTransientRetrySetting as r, type AgentIntake as s, type Decision as t, type ToolStepEnvelope as u, type CreateThreadInput as v, type ThreadSummary as w, type ThreadDetail as x, type ToolCallApprovalState as y, type EnqueueMessageInput as z };
+export { ASK_TOOL_NAME as $, type AgentStreamEvent as A, type ToolCallApprovalState as B, type ChatQueueStore as C, type DetachedDelivery as D, type ElicitationRequest as E, type EnqueueMessageInput as F, type QueuedMessage as G, type HumanReply as H, type QueuedMessagePatch as I, type QueuePause as J, type AppendMessageInput as K, type LlmStepEnvelope as L, type ModelMessage as M, type ToolResult as N, type MessageFeedback as O, type Persona as P, type QuotaState as Q, type RecordRunStartInput as R, type StoredMessage as S, type ToolSpec as T, type UpdateThreadInput as U, type RecordToolCallInput as V, type ToolCallOutcome as W, type UpdateToolCallInput as X, type RecordUsageInput as Y, ALL_AGENTS as Z, ASK_TOOL_DESCRIPTION as _, type Actor as a, releaseThreadRun as a$, type AgentApprovalRequest as a0, type AgentApprovalSettlement as a1, type AgentAttachmentConfig as a2, type AgentCatalogEntry as a3, type AgentClientConfig as a4, type AgentHistoryWindow as a5, type AgentStreamErrorCode as a6, type AskToolInput as a7, type ChatQueueState as a8, DEFAULT_INTAKE_PREAMBLE as a9, type ThreadTurnReader as aA, type ToolCallApprovalStatus as aB, type ToolCatalogEntry as aC, type ToolConfirmation as aD, type ToolPresentationTone as aE, type ToolResultField as aF, type ToolResultView as aG, type ToolStepCtx as aH, type ToolTransientRetryNumbers as aI, type ToolTransientRetryOptions as aJ, type TurnPersona as aK, UNFINISHED_TOOL_CALL as aL, type UsagePurpose as aM, askInputSchema as aN, askToolDefinition as aO, danglingToolCallIds as aP, decodeStreamEvent as aQ, encodeStreamEvent as aR, invokeWithTransientRetry as aS, isChatQueueStore as aT, isTransientToolError as aU, isTypedQuestion as aV, normalizeElicitationReply as aW, questionOptions as aX, queuedMessageView as aY, readElicitationInput as aZ, readElicitationQuestions as a_, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as aa, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as ab, ELICITATION_INPUT_TYPES as ac, type ElicitationInput as ad, type ElicitationInputType as ae, type ElicitationOption as af, type ElicitationOutcome as ag, type ElicitationQuestion as ah, type ElicitationReply as ai, type ElicitationResult as aj, type HistoryPolicyContext as ak, type HistorySelection as al, type HistorySummary as am, type InvokeWithTransientRetryOptions as an, MAX_ASK_QUESTIONS as ao, type MessageFeedbackValue as ap, type MessageRole as aq, type PersonaRef as ar, type PromptContext as as, type QueuePauseReason as at, type QueuedMessageView as au, type QuotaView as av, RUN_ENDED_BEFORE_TOOL_CALL as aw, type RecordRunEndInput as ax, type ThreadTurnPage as ay, type ThreadTurnQuery as az, type ToolPresentation as b, renderElicitationAnswers as b0, resolveElicitation as b1, resolveToolTransientRetryNumbers as b2, settleDanglingToolCalls as b3, settleElicitation as b4, validateElicitationAnswer as b5, validateElicitationValue as b6, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AgentRunInput as g, type MessageAttachment as h, type ToolKind as i, type ToolCallStatus as j, type ToolCallApproval as k, type AgentDefinition as l, type PersonaCatalogEntry as m, type HistoryPolicy as n, type PageContext as o, type AgentStore as p, type AgentDelegation as q, type PromptBuilder as r, type PromptContributor as s, type ToolTransientRetrySetting as t, type AgentIntake as u, type Decision as v, type ToolStepEnvelope as w, type CreateThreadInput as x, type ThreadSummary as y, type ThreadDetail as z };

package/dist/{stream-events-CgWqAI-1.d.ts → stream-events-CbVEowYb.d.ts}

@@ -115,6 +115,8 @@ interface CreateThreadInput {
      * included).
      */
     id?: string;
+    /** The persona the thread's turns run under when a send names none. See {@link ThreadSummary.persona}. */
+    persona?: string;
 }
 interface AppendMessageInput {
     threadId: string;
@@ -122,6 +124,8 @@ interface AppendMessageInput {
     content: string;
     /** Which agent produced this message (assistant messages) — provenance. */
     agentName?: string;
+    /** The persona the turn ran under. See {@link StoredMessage.persona}. */
+    persona?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
     /** Files the user attached to this message (image/PDF). Persisted verbatim. */
@@ -191,6 +195,8 @@ interface UpdateThreadInput {
     defaultAgent?: string | null;
     /** `null` unpins the thread's model (turns run on the provider default). */
     model?: string | null;
+    /** `null` clears the thread's persona (sends fall back to the agent's default persona). */
+    persona?: string | null;
 }
 interface RecordUsageInput {
     threadId: string;
@@ -421,6 +427,11 @@ interface AgentStore {
      * would be pinned for ever with nothing pointing at them. Answering from the surviving message
      * rows on every call is the only form of this that stays true after a truncation.
      *
+     * A message WAITING IN A THREAD'S QUEUE ({@link import('./chat-queue.js').ChatQueueStore}) counts
+     * too: it has been sent, it just has not run yet, and the turn it is waiting to start will read
+     * its attachments — a sweep that collected them would fail that turn. That holds for a paused
+     * queue as well. Removing the message, or editing its attachments away, frees them again.
+     *
      * Scoped to one actor, like every other read on this surface: media referenced only by ANOTHER
      * actor's thread is reported unreferenced here, so this can never be turned into a probe for what
      * exists in someone else's conversation. A host pairs it with its own per-actor inventory, so the
@@ -485,6 +496,8 @@ interface QueuedMessage {
     content: string;
     attachments?: MessageAttachment[];
     agentName?: string;
+    /** The persona the send resolved (explicit, the thread's, or the agent's default) — what it starts under. */
+    persona?: string;
     model?: string;
     pageContext?: PageContext;
     /**
@@ -501,6 +514,7 @@ interface QueuedMessageView {
     content: string;
     attachments?: MessageAttachment[];
     agentName?: string;
+    persona?: string;
     model?: string;
     interrupt?: boolean;
     createdAt: string;
@@ -521,6 +535,7 @@ interface EnqueueMessageInput {
     content: string;
     attachments?: MessageAttachment[];
     agentName?: string;
+    persona?: string;
     model?: string;
     pageContext?: PageContext;
     interrupt?: boolean;
@@ -1134,6 +1149,70 @@ interface PromptContext {
     /** The selected agent's name. */
     agentName: string;
     pageContext?: PageContext;
+    /**
+     * The persona this turn runs under, when it runs under one — so an agent's own `@SystemPrompt`
+     * (or a contributor) can vary by persona without the persona carrying a prompt of its own.
+     */
+    persona?: PersonaRef;
+    /**
+     * The agent's own resolved base prompt. Set only while a persona's {@link Persona.systemPrompt} is
+     * being resolved, so a persona builder can wrap the base rather than discard it.
+     */
+    basePrompt?: string;
+}
+/**
+ * A named variant of ONE agent: its own prompt and, optionally, a narrower tool allow-list. The
+ * caller picks one per send (`POST <base>/chat { persona }`); everything else — the agent's model,
+ * its access rules, its handoffs, its history — stays the agent's. A variant that needs any of those
+ * to differ is a different `@Agent`, not a persona.
+ */
+interface Persona {
+    /** Unique within its agent — what a send names and what a message records. */
+    id: string;
+    /** What a picker shows. */
+    label: string;
+    /** One line about what the persona is for, for a picker. */
+    description?: string;
+    /**
+     * The persona's prompt. A flat string STANDS IN FOR the agent's base prompt; a
+     * {@link PromptBuilder} is handed that base as `ctx.basePrompt`, so it can wrap it instead. The
+     * cross-agent contributors still follow either way. Omit → the agent's base prompt, unchanged
+     * (which can itself read `ctx.persona`).
+     */
+    systemPrompt?: string | PromptBuilder;
+    /**
+     * Only these tool names are offered — and only these may be invoked — under this persona. Layered
+     * AFTER the agent's own allow-list, `enabled`, the roles policy and `canUse`: it narrows, never
+     * widens. Omit → whatever the agent offers.
+     */
+    allowedTools?: string[];
+    /**
+     * Agent names this persona answers for: a send, a queued message or a thread that names one of
+     * them runs as THIS agent under THIS persona. For an app that turns separate agents into personas
+     * of one — the threads, messages and in-flight runs that recorded the old agent name keep
+     * resolving, with no data migration.
+     */
+    aliases?: string[];
+}
+/** What a prompt builder and a tool see of the turn's persona. */
+interface PersonaRef {
+    id: string;
+    label: string;
+}
+/**
+ * A persona as a turn RESOLVED it, journaled in the `persona:resolve` checkpoint — so every replay
+ * of the run uses this, and not whatever the persona's configuration says by the time it resumes.
+ */
+interface TurnPersona extends PersonaRef {
+    allowedTools?: string[];
+    /** The persona's prompt, resolved (with the base prompt it wraps). Absent → the base prompt. */
+    prompt?: string;
+}
+/** One persona as `GET <base>/agents` lists it — what a persona picker renders. */
+interface PersonaCatalogEntry {
+    id: string;
+    label: string;
+    description?: string;
 }
 /**
  * An agent's base system prompt. Return a string (optionally async) built from the turn's context —
@@ -1161,6 +1240,13 @@ interface AgentRunInput {
     day?: string;
     /** Which named agent runs this turn. Omitted → the default/single agent. */
     agentName?: string;
+    /**
+     * The persona of {@link agentName} this turn runs under (a {@link Persona.id}). Resolved by the
+     * service from the send, the thread and the agent's default BEFORE the run starts, so it is part
+     * of the run's own input; the loop resolves its definition once, in the `persona:resolve`
+     * checkpoint. Omitted → no persona, and no checkpoint spent on one.
+     */
+    persona?: string;
     /**
      * How many agent→agent delegations deep this run already is (0 for a top-level turn). The runner
      * increments it for each child run; the loop refuses to delegate past its depth ceiling.
@@ -1268,6 +1354,10 @@ interface AgentDefinition {
      * Whether this agent is offered the built-in `ask` tool. Undefined → the module-wide setting.
      */
     ask?: boolean;
+    /** Named variants of this agent — see {@link Persona}. Undefined → none. */
+    personas?: Persona[];
+    /** The persona a send runs under when neither it nor its thread names one. Undefined → none. */
+    defaultPersona?: string;
 }
 /**
  * The read-model the `GET agents` endpoint returns to a client — the safe public subset of an
@@ -1283,6 +1373,10 @@ interface AgentCatalogEntry {
      * so before a chat starts. `GET <base>/models?agent=` reports the same lock as `locked`.
      */
     lockedModel?: string;
+    /** The agent's personas, for a persona picker. Omitted when it declares none. */
+    personas?: PersonaCatalogEntry[];
+    /** The persona a send runs under when it names none. Omitted when the agent has no default. */
+    defaultPersona?: string;
 }
 interface ThreadSummary {
     id: string;
@@ -1309,6 +1403,12 @@ interface ThreadSummary {
      * it; the REST read-model normalizes that to `null`.
      */
     model?: string | null;
+    /**
+     * The persona this thread's turns run under when a send names none — the last one a send on it
+     * named, or `PATCH <base>/threads/:id { persona }`. `null` → the agent's default. Undefined for a
+     * store that does not persist it; the REST read-model normalizes that to `null`.
+     */
+    persona?: string | null;
 }
 interface StoredMessage {
     id: string;
@@ -1316,6 +1416,8 @@ interface StoredMessage {
     content: string;
     /** Which agent produced this message (assistant messages) — provenance for replay / UI / telescope. */
     agentName?: string;
+    /** The persona the turn that wrote this message ran under; absent when it ran under none. */
+    persona?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
     /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
@@ -1426,6 +1528,11 @@ interface LlmStepEnvelope {
     bufferOutput?: boolean;
     /** The turn's selected model ({@link AgentRunInput.model}), for the worker's provider call. */
     model?: string;
+    /**
+     * The allow-list of the persona the turn resolved (`persona:resolve`), which the serving worker
+     * intersects with the agent's own. Absent → no persona narrowing, as before personas existed.
+     */
+    personaAllowedTools?: string[];
 }
 /**
  * The serializable subset of `AiToolCtx` — everything except `host` (re-attached handler-side
@@ -1437,6 +1544,8 @@ interface ToolStepCtx {
     runId: string;
     requestId: string;
     agentName?: string;
+    /** The persona the turn runs under ({@link AiToolCtx.persona}). */
+    persona?: string;
     pageContext?: PageContext;
 }
 /** Serializable input for a dispatched tool-execution step. */
@@ -1444,6 +1553,11 @@ interface ToolStepEnvelope {
     toolName: string;
     input: unknown;
     ctx: ToolStepCtx;
+    /**
+     * The only tool names this call may invoke — the turn's persona allow-list (intersected with the
+     * agent's). Checked by `ToolRegistry.invoke` on the worker. Absent → no such check.
+     */
+    allowedTools?: string[];
     /** Applied INSIDE the handler (`withToolTimeout`) — never as a durable step `timeoutMs`. */
     timeoutMs?: number;
     /**
@@ -1952,4 +2066,4 @@ type AgentStreamErrorCode = 'quota_exceeded' | 'output_rejected' | 'structured_o
 /** A model call ended without producing anything. */
  | 'model_no_output' | 'run_failed';
 
-export { type AgentApprovalSettlement as $, type AgentStreamEvent as A, type QueuedMessage as B, type ChatQueueStore as C, type DetachedDelivery as D, type ElicitationRequest as E, type QueuedMessagePatch as F, type QueuePause as G, type HumanReply as H, type AppendMessageInput as I, type ToolResult as J, type MessageFeedback as K, type LlmStepEnvelope as L, type ModelMessage as M, type RecordToolCallInput as N, type ToolCallOutcome as O, type PageContext as P, type QuotaState as Q, type RecordRunStartInput as R, type StoredMessage as S, type ToolSpec as T, type UpdateThreadInput as U, type UpdateToolCallInput as V, type RecordUsageInput as W, ALL_AGENTS as X, ASK_TOOL_DESCRIPTION as Y, ASK_TOOL_NAME as Z, type AgentApprovalRequest as _, type Actor as a, settleDanglingToolCalls as a$, type AgentAttachmentConfig as a0, type AgentCatalogEntry as a1, type AgentClientConfig as a2, type AgentHistoryWindow as a3, type AgentStreamErrorCode as a4, type AskToolInput as a5, type ChatQueueState as a6, DEFAULT_INTAKE_PREAMBLE as a7, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as a8, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as a9, type ToolConfirmation as aA, type ToolPresentationTone as aB, type ToolResultField as aC, type ToolResultView as aD, type ToolStepCtx as aE, type ToolTransientRetryNumbers as aF, type ToolTransientRetryOptions as aG, UNFINISHED_TOOL_CALL as aH, type UsagePurpose as aI, askInputSchema as aJ, askToolDefinition as aK, danglingToolCallIds as aL, decodeStreamEvent as aM, encodeStreamEvent as aN, invokeWithTransientRetry as aO, isChatQueueStore as aP, isTransientToolError as aQ, isTypedQuestion as aR, normalizeElicitationReply as aS, questionOptions as aT, queuedMessageView as aU, readElicitationInput as aV, readElicitationQuestions as aW, releaseThreadRun as aX, renderElicitationAnswers as aY, resolveElicitation as aZ, resolveToolTransientRetryNumbers as a_, ELICITATION_INPUT_TYPES as aa, type ElicitationInput as ab, type ElicitationInputType as ac, type ElicitationOption as ad, type ElicitationOutcome as ae, type ElicitationQuestion as af, type ElicitationReply as ag, type ElicitationResult as ah, type HistoryPolicyContext as ai, type HistorySelection as aj, type HistorySummary as ak, type InvokeWithTransientRetryOptions as al, MAX_ASK_QUESTIONS as am, type MessageFeedbackValue as an, type MessageRole as ao, type PromptContext as ap, type QueuePauseReason as aq, type QueuedMessageView as ar, type QuotaView as as, RUN_ENDED_BEFORE_TOOL_CALL as at, type RecordRunEndInput as au, type ThreadTurnPage as av, type ThreadTurnQuery as aw, type ThreadTurnReader as ax, type ToolCallApprovalStatus as ay, type ToolCatalogEntry as az, type ToolPresentation as b, settleElicitation as b0, validateElicitationAnswer as b1, validateElicitationValue as b2, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AgentRunInput as g, type MessageAttachment as h, type ToolKind as i, type ToolCallStatus as j, type ToolCallApproval as k, type HistoryPolicy as l, type AgentDefinition as m, type AgentStore as n, type AgentDelegation as o, type PromptBuilder as p, type PromptContributor as q, type ToolTransientRetrySetting as r, type AgentIntake as s, type Decision as t, type ToolStepEnvelope as u, type CreateThreadInput as v, type ThreadSummary as w, type ThreadDetail as x, type ToolCallApprovalState as y, type EnqueueMessageInput as z };
+export { ASK_TOOL_NAME as $, type AgentStreamEvent as A, type ToolCallApprovalState as B, type ChatQueueStore as C, type DetachedDelivery as D, type ElicitationRequest as E, type EnqueueMessageInput as F, type QueuedMessage as G, type HumanReply as H, type QueuedMessagePatch as I, type QueuePause as J, type AppendMessageInput as K, type LlmStepEnvelope as L, type ModelMessage as M, type ToolResult as N, type MessageFeedback as O, type Persona as P, type QuotaState as Q, type RecordRunStartInput as R, type StoredMessage as S, type ToolSpec as T, type UpdateThreadInput as U, type RecordToolCallInput as V, type ToolCallOutcome as W, type UpdateToolCallInput as X, type RecordUsageInput as Y, ALL_AGENTS as Z, ASK_TOOL_DESCRIPTION as _, type Actor as a, releaseThreadRun as a$, type AgentApprovalRequest as a0, type AgentApprovalSettlement as a1, type AgentAttachmentConfig as a2, type AgentCatalogEntry as a3, type AgentClientConfig as a4, type AgentHistoryWindow as a5, type AgentStreamErrorCode as a6, type AskToolInput as a7, type ChatQueueState as a8, DEFAULT_INTAKE_PREAMBLE as a9, type ThreadTurnReader as aA, type ToolCallApprovalStatus as aB, type ToolCatalogEntry as aC, type ToolConfirmation as aD, type ToolPresentationTone as aE, type ToolResultField as aF, type ToolResultView as aG, type ToolStepCtx as aH, type ToolTransientRetryNumbers as aI, type ToolTransientRetryOptions as aJ, type TurnPersona as aK, UNFINISHED_TOOL_CALL as aL, type UsagePurpose as aM, askInputSchema as aN, askToolDefinition as aO, danglingToolCallIds as aP, decodeStreamEvent as aQ, encodeStreamEvent as aR, invokeWithTransientRetry as aS, isChatQueueStore as aT, isTransientToolError as aU, isTypedQuestion as aV, normalizeElicitationReply as aW, questionOptions as aX, queuedMessageView as aY, readElicitationInput as aZ, readElicitationQuestions as a_, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as aa, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as ab, ELICITATION_INPUT_TYPES as ac, type ElicitationInput as ad, type ElicitationInputType as ae, type ElicitationOption as af, type ElicitationOutcome as ag, type ElicitationQuestion as ah, type ElicitationReply as ai, type ElicitationResult as aj, type HistoryPolicyContext as ak, type HistorySelection as al, type HistorySummary as am, type InvokeWithTransientRetryOptions as an, MAX_ASK_QUESTIONS as ao, type MessageFeedbackValue as ap, type MessageRole as aq, type PersonaRef as ar, type PromptContext as as, type QueuePauseReason as at, type QueuedMessageView as au, type QuotaView as av, RUN_ENDED_BEFORE_TOOL_CALL as aw, type RecordRunEndInput as ax, type ThreadTurnPage as ay, type ThreadTurnQuery as az, type ToolPresentation as b, renderElicitationAnswers as b0, resolveElicitation as b1, resolveToolTransientRetryNumbers as b2, settleDanglingToolCalls as b3, settleElicitation as b4, validateElicitationAnswer as b5, validateElicitationValue as b6, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AgentRunInput as g, type MessageAttachment as h, type ToolKind as i, type ToolCallStatus as j, type ToolCallApproval as k, type AgentDefinition as l, type PersonaCatalogEntry as m, type HistoryPolicy as n, type PageContext as o, type AgentStore as p, type AgentDelegation as q, type PromptBuilder as r, type PromptContributor as s, type ToolTransientRetrySetting as t, type AgentIntake as u, type Decision as v, type ToolStepEnvelope as w, type CreateThreadInput as x, type ThreadSummary as y, type ThreadDetail as z };

package/dist/{tool-DuJ-_qXM.d.cts → tool-DZYLEKnl.d.cts}

@@ -1,5 +1,5 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { a as Actor, P as PageContext } from './stream-events-CgWqAI-1.cjs';
+import { a as Actor, o as PageContext } from './stream-events-CbVEowYb.cjs';
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -34,6 +34,8 @@ interface AiToolCtx {
     idempotencyKey?: string;
     /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
     agentName?: string;
+    /** The persona of {@link agentName} the turn runs under, when it runs under one. */
+    persona?: string;
     pageContext?: PageContext;
     /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
     host?: unknown;

package/dist/{tool-DklsS3JX.d.ts → tool-_iq4xRyk.d.ts}

@@ -1,5 +1,5 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { a as Actor, P as PageContext } from './stream-events-CgWqAI-1.js';
+import { a as Actor, o as PageContext } from './stream-events-CbVEowYb.js';
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -34,6 +34,8 @@ interface AiToolCtx {
     idempotencyKey?: string;
     /** The name of the agent running this turn — provenance a tool can scope on (e.g. capability sets). */
     agentName?: string;
+    /** The persona of {@link agentName} the turn runs under, when it runs under one. */
+    persona?: string;
     pageContext?: PageContext;
     /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
     host?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-agent-core",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",