@dudousxd/nestjs-agent-core 0.38.0 → 0.39.0

package/dist/index.d.cts

@@ -1,10 +1,10 @@
-import { M as ModelMessage, c as ToolDefinition, d as ToolCallRequest, e as MessageUsage, f as AgentUiComponent, a as Actor, A as AgentStreamEvent, T as ToolSpec, Q as QuotaState, g as AgentRunInput, H as HumanReply, h as MessageAttachment, i as ToolKind, j as ToolCallStatus, k as ToolCallApproval, l as HistoryPolicy, P as PageContext, m as AgentDefinition, n as AgentStore, o as AgentDelegation, D as DetachedDelivery, p as PromptBuilder, q as PromptContributor, r as ToolTransientRetrySetting, s as AgentIntake, t as Decision, E as ElicitationRequest, L as LlmStepEnvelope, u as ToolStepEnvelope, C as ChatQueueStore, v as CreateThreadInput, w as ThreadSummary, x as ThreadDetail, y as ToolCallApprovalState, U as UpdateThreadInput, R as RecordRunStartInput, z as EnqueueMessageInput, B as QueuedMessage, F as QueuedMessagePatch, G as QueuePause, I as AppendMessageInput, S as StoredMessage, J as ToolResult, K as MessageFeedback, N as RecordToolCallInput, O as ToolCallOutcome, V as UpdateToolCallInput, W as RecordUsageInput } from './stream-events-CgWqAI-1.cjs';
-export { X as ALL_AGENTS, Y as ASK_TOOL_DESCRIPTION, Z as ASK_TOOL_NAME, _ as AgentApprovalRequest, $ as AgentApprovalSettlement, a0 as AgentAttachmentConfig, a1 as AgentCatalogEntry, a2 as AgentClientConfig, a3 as AgentHistoryWindow, a4 as AgentStreamErrorCode, a5 as AskToolInput, a6 as ChatQueueState, a7 as DEFAULT_INTAKE_PREAMBLE, a8 as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, a9 as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, aa as ELICITATION_INPUT_TYPES, ab as ElicitationInput, ac as ElicitationInputType, ad as ElicitationOption, ae as ElicitationOutcome, af as ElicitationQuestion, ag as ElicitationReply, ah as ElicitationResult, ai as HistoryPolicyContext, aj as HistorySelection, ak as HistorySummary, al as InvokeWithTransientRetryOptions, am as MAX_ASK_QUESTIONS, an as MessageFeedbackValue, ao as MessageRole, ap as PromptContext, aq as QueuePauseReason, ar as QueuedMessageView, as as QuotaView, at as RUN_ENDED_BEFORE_TOOL_CALL, au as RecordRunEndInput, av as ThreadTurnPage, aw as ThreadTurnQuery, ax as ThreadTurnReader, ay as ToolCallApprovalStatus, az as ToolCatalogEntry, aA as ToolConfirmation, b as ToolPresentation, aB as ToolPresentationTone, aC as ToolResultField, aD as ToolResultView, aE as ToolStepCtx, aF as ToolTransientRetryNumbers, aG as ToolTransientRetryOptions, aH as UNFINISHED_TOOL_CALL, aI as UsagePurpose, aJ as askInputSchema, aK as askToolDefinition, aL as danglingToolCallIds, aM as decodeStreamEvent, aN as encodeStreamEvent, aO as invokeWithTransientRetry, aP as isChatQueueStore, aQ as isTransientToolError, aR as isTypedQuestion, aS as normalizeElicitationReply, aT as questionOptions, aU as queuedMessageView, aV as readElicitationInput, aW as readElicitationQuestions, aX as releaseThreadRun, aY as renderElicitationAnswers, aZ as resolveElicitation, a_ as resolveToolTransientRetryNumbers, a$ as settleDanglingToolCalls, b0 as settleElicitation, b1 as validateElicitationAnswer, b2 as validateElicitationValue } from './stream-events-CgWqAI-1.cjs';
-import { A as AiToolCtx, T as ToolHandler, a as ToolDescribeScope } from './tool-DuJ-_qXM.cjs';
-export { b as ToolDescription } from './tool-DuJ-_qXM.cjs';
+import { M as ModelMessage, c as ToolDefinition, d as ToolCallRequest, e as MessageUsage, f as AgentUiComponent, a as Actor, A as AgentStreamEvent, T as ToolSpec, Q as QuotaState, g as AgentRunInput, H as HumanReply, h as MessageAttachment, i as ToolKind, j as ToolCallStatus, k as ToolCallApproval, l as AgentDefinition, P as Persona, m as PersonaCatalogEntry, n as HistoryPolicy, o as PageContext, p as AgentStore, q as AgentDelegation, D as DetachedDelivery, r as PromptBuilder, s as PromptContributor, t as ToolTransientRetrySetting, u as AgentIntake, v as Decision, E as ElicitationRequest, L as LlmStepEnvelope, w as ToolStepEnvelope, C as ChatQueueStore, x as CreateThreadInput, y as ThreadSummary, z as ThreadDetail, B as ToolCallApprovalState, U as UpdateThreadInput, R as RecordRunStartInput, F as EnqueueMessageInput, G as QueuedMessage, I as QueuedMessagePatch, J as QueuePause, K as AppendMessageInput, S as StoredMessage, N as ToolResult, O as MessageFeedback, V as RecordToolCallInput, W as ToolCallOutcome, X as UpdateToolCallInput, Y as RecordUsageInput } from './stream-events-CbVEowYb.cjs';
+export { Z as ALL_AGENTS, _ as ASK_TOOL_DESCRIPTION, $ as ASK_TOOL_NAME, a0 as AgentApprovalRequest, a1 as AgentApprovalSettlement, a2 as AgentAttachmentConfig, a3 as AgentCatalogEntry, a4 as AgentClientConfig, a5 as AgentHistoryWindow, a6 as AgentStreamErrorCode, a7 as AskToolInput, a8 as ChatQueueState, a9 as DEFAULT_INTAKE_PREAMBLE, aa as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, ab as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, ac as ELICITATION_INPUT_TYPES, ad as ElicitationInput, ae as ElicitationInputType, af as ElicitationOption, ag as ElicitationOutcome, ah as ElicitationQuestion, ai as ElicitationReply, aj as ElicitationResult, ak as HistoryPolicyContext, al as HistorySelection, am as HistorySummary, an as InvokeWithTransientRetryOptions, ao as MAX_ASK_QUESTIONS, ap as MessageFeedbackValue, aq as MessageRole, ar as PersonaRef, as as PromptContext, at as QueuePauseReason, au as QueuedMessageView, av as QuotaView, aw as RUN_ENDED_BEFORE_TOOL_CALL, ax as RecordRunEndInput, ay as ThreadTurnPage, az as ThreadTurnQuery, aA as ThreadTurnReader, aB as ToolCallApprovalStatus, aC as ToolCatalogEntry, aD as ToolConfirmation, b as ToolPresentation, aE as ToolPresentationTone, aF as ToolResultField, aG as ToolResultView, aH as ToolStepCtx, aI as ToolTransientRetryNumbers, aJ as ToolTransientRetryOptions, aK as TurnPersona, aL as UNFINISHED_TOOL_CALL, aM as UsagePurpose, aN as askInputSchema, aO as askToolDefinition, aP as danglingToolCallIds, aQ as decodeStreamEvent, aR as encodeStreamEvent, aS as invokeWithTransientRetry, aT as isChatQueueStore, aU as isTransientToolError, aV as isTypedQuestion, aW as normalizeElicitationReply, aX as questionOptions, aY as queuedMessageView, aZ as readElicitationInput, a_ as readElicitationQuestions, a$ as releaseThreadRun, b0 as renderElicitationAnswers, b1 as resolveElicitation, b2 as resolveToolTransientRetryNumbers, b3 as settleDanglingToolCalls, b4 as settleElicitation, b5 as validateElicitationAnswer, b6 as validateElicitationValue } from './stream-events-CbVEowYb.cjs';
+import { A as AiToolCtx, T as ToolHandler, a as ToolDescribeScope } from './tool-DZYLEKnl.cjs';
+export { b as ToolDescription } from './tool-DZYLEKnl.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { O as OutputProcessor, P as ProcessorContext, I as InputProcessor, a as ProcessedPrompt, M as ModelAnswer } from './processors-C0snQzZJ.cjs';
-export { D as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, b as IncrementalGating, c as OutputRejectedError, d as OutputVerdict, e as ProcessorFailedError } from './processors-C0snQzZJ.cjs';
+import { O as OutputProcessor, P as ProcessorContext, I as InputProcessor, a as ProcessedPrompt, M as ModelAnswer } from './processors-6p9nrqEi.cjs';
+export { D as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, b as IncrementalGating, c as OutputRejectedError, d as OutputVerdict, e as ProcessorFailedError } from './processors-6p9nrqEi.cjs';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
 /**
@@ -1349,6 +1349,27 @@ declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: Role
  */
 declare function filterToolsByAllowList(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
 
+/**
+ * The narrower of two tool allow-lists. `undefined` is "no restriction", so it yields the other;
+ * two lists yield the names on both, in the order of the first.
+ */
+declare function intersectAllowLists(first: readonly string[] | undefined, second: readonly string[] | undefined): string[] | undefined;
+/** The persona `id` of `definition`, or `undefined` when it declares none by that id. */
+declare function findPersona(definition: Pick<AgentDefinition, 'personas'> | undefined, id: string | undefined): Persona | undefined;
+/** A persona as a picker reads it — never its prompt or its allow-list. */
+declare function personaCatalogEntry(persona: Persona): PersonaCatalogEntry;
+/** Where a former agent name now lives: an agent, and the persona of it the name stands for. */
+interface PersonaAlias {
+    agent: string;
+    persona: string;
+}
+/**
+ * Resolve `name` through the {@link Persona.aliases} of `definitions`: the agent and persona that
+ * answer for it, or `undefined` when no persona claims it. A name that IS a registered agent is
+ * never an alias — the caller checks that first, so a real agent always wins.
+ */
+declare function resolvePersonaAlias(definitions: readonly AgentDefinition[], name: string): PersonaAlias | undefined;
+
 /**
  * The built-in {@link HistoryPolicy}: keep the newest messages that fit a count and/or a token
  * budget, and (optionally) fold the rest into a summary. See `./spi/history-policy.ts` for the seam
@@ -2488,6 +2509,11 @@ declare function detachedUnsettled(args: {
  *
  * Called by the RUNNER, never the loop — a run that crashed or was stopped cannot record its own
  * ending. Skipped entirely when the thread is gone, for the same reason delivery is.
+ *
+ * Settles ONCE: a thread that already holds a message from this run (its answer, or an earlier
+ * settlement) is left alone. A Stop can be settled from two places — the run's own body when it
+ * observes the cancel, and the runner for a run parked where its body never runs again — and a
+ * Stop on a run that already answered must not write "stopped" under its answer.
  */
 declare function settleUnsettledDelegation(args: {
     store: AgentStore;
@@ -2574,7 +2600,15 @@ declare class ToolRegistry {
      * a call can reach here from a replayed durable step or an approval granted before the flag
      * moved, neither of which went through `definitionsFor` again) and re-parses the input via Zod.
      */
-    invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
+    invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy, options?: InvokeOptions): Promise<unknown>;
+}
+/** Per-call narrowing for {@link ToolRegistry.invoke}. */
+interface InvokeOptions {
+    /**
+     * Only these tool names may run — the turn's persona allow-list. Checked after `enabled`, the
+     * roles policy and `canUse`. Undefined → no such check (every caller predating personas).
+     */
+    allowedTools?: readonly string[];
 }
 /**
  * Default gate: a tool that names `roles` is callable by an actor holding one of them; a tool that
@@ -2675,6 +2709,12 @@ interface AgentLoopDeps<TOutput = unknown> {
     host?: unknown;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
+    /**
+     * The agent's personas. Read ONLY when the run names one (`AgentRunInput.persona`), and then only
+     * once, inside the `persona:resolve` checkpoint — so a replay runs under the persona the turn
+     * started with even after this list changed. Undefined → no personas.
+     */
+    personas?: Persona[];
     /**
      * Per-tool execution timeout in ms. A tool that runs longer is aborted and recorded as failed
      * (the model gets the timeout as its result and can adapt) rather than hanging the turn.
@@ -3123,7 +3163,7 @@ interface AgentLoopResult<TOutput = unknown> {
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
  * hooks that make the same loop body either in-process or a replay-safe durable workflow.
  */
-declare function runAgentLoop<TOutput = unknown>(boundDeps: AgentLoopDeps<TOutput>, input: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
+declare function runAgentLoop<TOutput = unknown>(boundDeps: AgentLoopDeps<TOutput>, requested: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
 
 /** Payloads carried on each `aviary:agent:*` channel. */
 interface AgentRunStarted {
@@ -3132,6 +3172,8 @@ interface AgentRunStarted {
     actorId: string;
     /** Which agent is handling the run. */
     agentName?: string;
+    /** The persona of that agent the run is under, when it is under one. */
+    persona?: string;
 }
 interface AgentMessageEvent {
     runId: string;
@@ -3474,6 +3516,8 @@ declare class InMemoryAgentStore implements AgentStore, ChatQueueStore {
      * this scalar has a method to ask for it.
      */
     defaultAgentForThread(threadId: string): Promise<string | null>;
+    /** The thread's persona, projected like {@link defaultAgentForThread}. */
+    personaForThread(threadId: string): Promise<string | null>;
     /** The thread's pinned model, projected like {@link defaultAgentForThread}. */
     modelForThread(threadId: string): Promise<string | null>;
     /**
@@ -3516,7 +3560,8 @@ declare class InMemoryAgentStore implements AgentStore, ChatQueueStore {
     setMessageFeedback(messageId: string, feedback: MessageFeedback | null): Promise<void>;
     truncateFrom(threadId: string, messageId: string): Promise<void>;
     /**
-     * Of `mediaIds`, the ones a surviving message in one of this actor's threads still carries.
+     * Of `mediaIds`, the ones a surviving message — or a message waiting in the queue — in one of
+     * this actor's threads still carries.
      * Re-derived from the messages each call, so a media whose message was truncated away reads as
      * unreferenced again.
      */
@@ -3956,4 +4001,4 @@ declare class SqlTokenStreamSink implements TokenStreamSink {
     private purgeInBackground;
 }
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_CONFIRM_TOKEN_STORE, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStartOptions, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingDescription, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, CONFIRM_JSON_SCHEMA_PROPERTIES, ChatQueueStore, ClosedRolesPolicy, type ConfirmFields, type ConfirmTokenClaim, ConfirmTokenError, type ConfirmTokenStore, type ConfirmTokenSubject, type ConfirmedTool, type ConfirmedToolDone, type ConfirmedToolMessages, type ConfirmedToolOptions, type ConfirmedToolOutcome, type ConfirmedToolPreview, type ConfirmedToolResult, type ConfirmedToolSteps, type CostUsage, CreateThreadInput, type CurrentModelPrice, DEFAULT_CONFIRM_TTL_MS, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type EmptyRoles, EnqueueMessageInput, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernanceMessageRow, type GovernancePage, type GovernancePageQuery, type GovernancePendingApprovalRow, type GovernanceRange, type GovernanceRunDetail, type GovernanceRunRow, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceThreadRow, type GovernanceToolCallRow, type GovernanceUsageInput, type GovernanceUsageRow, HistoryPolicy, HumanReply, InMemoryAgentStore, InMemoryConfirmTokenStore, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogLock, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QueuePause, QueuedMessage, QueuedMessagePatch, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWarning, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, RUN_FAILED_MESSAGE, RUN_NOT_ACTIVE_CODE, RUN_NOT_ACTIVE_MESSAGE, RUN_NO_LONGER_RUNNING, type RecentRunRow, RecordRunStartInput, RecordToolCallInput, RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RolesPolicyOptions, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SCHEMA_EXTENSION, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type SchemaExtension, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettleDeadRunInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, SqlTokenStreamSink, type SqlTokenStreamSinkOptions, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StreamFrameRow, type StreamFrameTable, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, ToolCallApprovalState, ToolCallOutcome, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDescribeScope, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, UpdateThreadInput, UpdateToolCallInput, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, canonicalJson, closeEmptyRoles, compositeSkillProvider, confirmTokenExpiry, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, defineConfirmedTool, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, exposeStreamErrorDetails, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, hashConfirmToken, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, quotaUsedRatio, quotaWarning, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, schemaExtensionOf, seedModelPrices, settleAll, settleDeadRun, settleUnsettledDelegation, signConfirmToken, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, streamFailure, summarizeWithModel, tenantScope, toolCallApprovalFromRow, toolCallContext, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, verifyConfirmToken, windowHistory, withAskTool, withConfirmFields, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_CONFIRM_TOKEN_STORE, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStartOptions, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingDescription, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, CONFIRM_JSON_SCHEMA_PROPERTIES, ChatQueueStore, ClosedRolesPolicy, type ConfirmFields, type ConfirmTokenClaim, ConfirmTokenError, type ConfirmTokenStore, type ConfirmTokenSubject, type ConfirmedTool, type ConfirmedToolDone, type ConfirmedToolMessages, type ConfirmedToolOptions, type ConfirmedToolOutcome, type ConfirmedToolPreview, type ConfirmedToolResult, type ConfirmedToolSteps, type CostUsage, CreateThreadInput, type CurrentModelPrice, DEFAULT_CONFIRM_TTL_MS, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type EmptyRoles, EnqueueMessageInput, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernanceMessageRow, type GovernancePage, type GovernancePageQuery, type GovernancePendingApprovalRow, type GovernanceRange, type GovernanceRunDetail, type GovernanceRunRow, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceThreadRow, type GovernanceToolCallRow, type GovernanceUsageInput, type GovernanceUsageRow, HistoryPolicy, HumanReply, InMemoryAgentStore, InMemoryConfirmTokenStore, type IncrementalGate, InputProcessor, type InvokeOptions, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogLock, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, Persona, type PersonaAlias, PersonaCatalogEntry, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QueuePause, QueuedMessage, QueuedMessagePatch, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWarning, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, RUN_FAILED_MESSAGE, RUN_NOT_ACTIVE_CODE, RUN_NOT_ACTIVE_MESSAGE, RUN_NO_LONGER_RUNNING, type RecentRunRow, RecordRunStartInput, RecordToolCallInput, RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RolesPolicyOptions, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SCHEMA_EXTENSION, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type SchemaExtension, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettleDeadRunInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, SqlTokenStreamSink, type SqlTokenStreamSinkOptions, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StreamFrameRow, type StreamFrameTable, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, ToolCallApprovalState, ToolCallOutcome, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDescribeScope, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, UpdateThreadInput, UpdateToolCallInput, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, canonicalJson, closeEmptyRoles, compositeSkillProvider, confirmTokenExpiry, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, defineConfirmedTool, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, exposeStreamErrorDetails, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, findPersona, gateFollowUps, gateTail, hashConfirmToken, intersectAllowLists, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, personaCatalogEntry, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, quotaUsedRatio, quotaWarning, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolvePersonaAlias, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, schemaExtensionOf, seedModelPrices, settleAll, settleDeadRun, settleUnsettledDelegation, signConfirmToken, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, streamFailure, summarizeWithModel, tenantScope, toolCallApprovalFromRow, toolCallContext, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, verifyConfirmToken, windowHistory, withAskTool, withConfirmFields, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { M as ModelMessage, c as ToolDefinition, d as ToolCallRequest, e as MessageUsage, f as AgentUiComponent, a as Actor, A as AgentStreamEvent, T as ToolSpec, Q as QuotaState, g as AgentRunInput, H as HumanReply, h as MessageAttachment, i as ToolKind, j as ToolCallStatus, k as ToolCallApproval, l as HistoryPolicy, P as PageContext, m as AgentDefinition, n as AgentStore, o as AgentDelegation, D as DetachedDelivery, p as PromptBuilder, q as PromptContributor, r as ToolTransientRetrySetting, s as AgentIntake, t as Decision, E as ElicitationRequest, L as LlmStepEnvelope, u as ToolStepEnvelope, C as ChatQueueStore, v as CreateThreadInput, w as ThreadSummary, x as ThreadDetail, y as ToolCallApprovalState, U as UpdateThreadInput, R as RecordRunStartInput, z as EnqueueMessageInput, B as QueuedMessage, F as QueuedMessagePatch, G as QueuePause, I as AppendMessageInput, S as StoredMessage, J as ToolResult, K as MessageFeedback, N as RecordToolCallInput, O as ToolCallOutcome, V as UpdateToolCallInput, W as RecordUsageInput } from './stream-events-CgWqAI-1.js';
-export { X as ALL_AGENTS, Y as ASK_TOOL_DESCRIPTION, Z as ASK_TOOL_NAME, _ as AgentApprovalRequest, $ as AgentApprovalSettlement, a0 as AgentAttachmentConfig, a1 as AgentCatalogEntry, a2 as AgentClientConfig, a3 as AgentHistoryWindow, a4 as AgentStreamErrorCode, a5 as AskToolInput, a6 as ChatQueueState, a7 as DEFAULT_INTAKE_PREAMBLE, a8 as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, a9 as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, aa as ELICITATION_INPUT_TYPES, ab as ElicitationInput, ac as ElicitationInputType, ad as ElicitationOption, ae as ElicitationOutcome, af as ElicitationQuestion, ag as ElicitationReply, ah as ElicitationResult, ai as HistoryPolicyContext, aj as HistorySelection, ak as HistorySummary, al as InvokeWithTransientRetryOptions, am as MAX_ASK_QUESTIONS, an as MessageFeedbackValue, ao as MessageRole, ap as PromptContext, aq as QueuePauseReason, ar as QueuedMessageView, as as QuotaView, at as RUN_ENDED_BEFORE_TOOL_CALL, au as RecordRunEndInput, av as ThreadTurnPage, aw as ThreadTurnQuery, ax as ThreadTurnReader, ay as ToolCallApprovalStatus, az as ToolCatalogEntry, aA as ToolConfirmation, b as ToolPresentation, aB as ToolPresentationTone, aC as ToolResultField, aD as ToolResultView, aE as ToolStepCtx, aF as ToolTransientRetryNumbers, aG as ToolTransientRetryOptions, aH as UNFINISHED_TOOL_CALL, aI as UsagePurpose, aJ as askInputSchema, aK as askToolDefinition, aL as danglingToolCallIds, aM as decodeStreamEvent, aN as encodeStreamEvent, aO as invokeWithTransientRetry, aP as isChatQueueStore, aQ as isTransientToolError, aR as isTypedQuestion, aS as normalizeElicitationReply, aT as questionOptions, aU as queuedMessageView, aV as readElicitationInput, aW as readElicitationQuestions, aX as releaseThreadRun, aY as renderElicitationAnswers, aZ as resolveElicitation, a_ as resolveToolTransientRetryNumbers, a$ as settleDanglingToolCalls, b0 as settleElicitation, b1 as validateElicitationAnswer, b2 as validateElicitationValue } from './stream-events-CgWqAI-1.js';
-import { A as AiToolCtx, T as ToolHandler, a as ToolDescribeScope } from './tool-DklsS3JX.js';
-export { b as ToolDescription } from './tool-DklsS3JX.js';
+import { M as ModelMessage, c as ToolDefinition, d as ToolCallRequest, e as MessageUsage, f as AgentUiComponent, a as Actor, A as AgentStreamEvent, T as ToolSpec, Q as QuotaState, g as AgentRunInput, H as HumanReply, h as MessageAttachment, i as ToolKind, j as ToolCallStatus, k as ToolCallApproval, l as AgentDefinition, P as Persona, m as PersonaCatalogEntry, n as HistoryPolicy, o as PageContext, p as AgentStore, q as AgentDelegation, D as DetachedDelivery, r as PromptBuilder, s as PromptContributor, t as ToolTransientRetrySetting, u as AgentIntake, v as Decision, E as ElicitationRequest, L as LlmStepEnvelope, w as ToolStepEnvelope, C as ChatQueueStore, x as CreateThreadInput, y as ThreadSummary, z as ThreadDetail, B as ToolCallApprovalState, U as UpdateThreadInput, R as RecordRunStartInput, F as EnqueueMessageInput, G as QueuedMessage, I as QueuedMessagePatch, J as QueuePause, K as AppendMessageInput, S as StoredMessage, N as ToolResult, O as MessageFeedback, V as RecordToolCallInput, W as ToolCallOutcome, X as UpdateToolCallInput, Y as RecordUsageInput } from './stream-events-CbVEowYb.js';
+export { Z as ALL_AGENTS, _ as ASK_TOOL_DESCRIPTION, $ as ASK_TOOL_NAME, a0 as AgentApprovalRequest, a1 as AgentApprovalSettlement, a2 as AgentAttachmentConfig, a3 as AgentCatalogEntry, a4 as AgentClientConfig, a5 as AgentHistoryWindow, a6 as AgentStreamErrorCode, a7 as AskToolInput, a8 as ChatQueueState, a9 as DEFAULT_INTAKE_PREAMBLE, aa as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, ab as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, ac as ELICITATION_INPUT_TYPES, ad as ElicitationInput, ae as ElicitationInputType, af as ElicitationOption, ag as ElicitationOutcome, ah as ElicitationQuestion, ai as ElicitationReply, aj as ElicitationResult, ak as HistoryPolicyContext, al as HistorySelection, am as HistorySummary, an as InvokeWithTransientRetryOptions, ao as MAX_ASK_QUESTIONS, ap as MessageFeedbackValue, aq as MessageRole, ar as PersonaRef, as as PromptContext, at as QueuePauseReason, au as QueuedMessageView, av as QuotaView, aw as RUN_ENDED_BEFORE_TOOL_CALL, ax as RecordRunEndInput, ay as ThreadTurnPage, az as ThreadTurnQuery, aA as ThreadTurnReader, aB as ToolCallApprovalStatus, aC as ToolCatalogEntry, aD as ToolConfirmation, b as ToolPresentation, aE as ToolPresentationTone, aF as ToolResultField, aG as ToolResultView, aH as ToolStepCtx, aI as ToolTransientRetryNumbers, aJ as ToolTransientRetryOptions, aK as TurnPersona, aL as UNFINISHED_TOOL_CALL, aM as UsagePurpose, aN as askInputSchema, aO as askToolDefinition, aP as danglingToolCallIds, aQ as decodeStreamEvent, aR as encodeStreamEvent, aS as invokeWithTransientRetry, aT as isChatQueueStore, aU as isTransientToolError, aV as isTypedQuestion, aW as normalizeElicitationReply, aX as questionOptions, aY as queuedMessageView, aZ as readElicitationInput, a_ as readElicitationQuestions, a$ as releaseThreadRun, b0 as renderElicitationAnswers, b1 as resolveElicitation, b2 as resolveToolTransientRetryNumbers, b3 as settleDanglingToolCalls, b4 as settleElicitation, b5 as validateElicitationAnswer, b6 as validateElicitationValue } from './stream-events-CbVEowYb.js';
+import { A as AiToolCtx, T as ToolHandler, a as ToolDescribeScope } from './tool-_iq4xRyk.js';
+export { b as ToolDescription } from './tool-_iq4xRyk.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { O as OutputProcessor, P as ProcessorContext, I as InputProcessor, a as ProcessedPrompt, M as ModelAnswer } from './processors-D5110pit.js';
-export { D as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, b as IncrementalGating, c as OutputRejectedError, d as OutputVerdict, e as ProcessorFailedError } from './processors-D5110pit.js';
+import { O as OutputProcessor, P as ProcessorContext, I as InputProcessor, a as ProcessedPrompt, M as ModelAnswer } from './processors-Bp5XmF6V.js';
+export { D as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, b as IncrementalGating, c as OutputRejectedError, d as OutputVerdict, e as ProcessorFailedError } from './processors-Bp5XmF6V.js';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
 /**
@@ -1349,6 +1349,27 @@ declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: Role
  */
 declare function filterToolsByAllowList(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
 
+/**
+ * The narrower of two tool allow-lists. `undefined` is "no restriction", so it yields the other;
+ * two lists yield the names on both, in the order of the first.
+ */
+declare function intersectAllowLists(first: readonly string[] | undefined, second: readonly string[] | undefined): string[] | undefined;
+/** The persona `id` of `definition`, or `undefined` when it declares none by that id. */
+declare function findPersona(definition: Pick<AgentDefinition, 'personas'> | undefined, id: string | undefined): Persona | undefined;
+/** A persona as a picker reads it — never its prompt or its allow-list. */
+declare function personaCatalogEntry(persona: Persona): PersonaCatalogEntry;
+/** Where a former agent name now lives: an agent, and the persona of it the name stands for. */
+interface PersonaAlias {
+    agent: string;
+    persona: string;
+}
+/**
+ * Resolve `name` through the {@link Persona.aliases} of `definitions`: the agent and persona that
+ * answer for it, or `undefined` when no persona claims it. A name that IS a registered agent is
+ * never an alias — the caller checks that first, so a real agent always wins.
+ */
+declare function resolvePersonaAlias(definitions: readonly AgentDefinition[], name: string): PersonaAlias | undefined;
+
 /**
  * The built-in {@link HistoryPolicy}: keep the newest messages that fit a count and/or a token
  * budget, and (optionally) fold the rest into a summary. See `./spi/history-policy.ts` for the seam
@@ -2488,6 +2509,11 @@ declare function detachedUnsettled(args: {
  *
  * Called by the RUNNER, never the loop — a run that crashed or was stopped cannot record its own
  * ending. Skipped entirely when the thread is gone, for the same reason delivery is.
+ *
+ * Settles ONCE: a thread that already holds a message from this run (its answer, or an earlier
+ * settlement) is left alone. A Stop can be settled from two places — the run's own body when it
+ * observes the cancel, and the runner for a run parked where its body never runs again — and a
+ * Stop on a run that already answered must not write "stopped" under its answer.
  */
 declare function settleUnsettledDelegation(args: {
     store: AgentStore;
@@ -2574,7 +2600,15 @@ declare class ToolRegistry {
      * a call can reach here from a replayed durable step or an approval granted before the flag
      * moved, neither of which went through `definitionsFor` again) and re-parses the input via Zod.
      */
-    invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
+    invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy, options?: InvokeOptions): Promise<unknown>;
+}
+/** Per-call narrowing for {@link ToolRegistry.invoke}. */
+interface InvokeOptions {
+    /**
+     * Only these tool names may run — the turn's persona allow-list. Checked after `enabled`, the
+     * roles policy and `canUse`. Undefined → no such check (every caller predating personas).
+     */
+    allowedTools?: readonly string[];
 }
 /**
  * Default gate: a tool that names `roles` is callable by an actor holding one of them; a tool that
@@ -2675,6 +2709,12 @@ interface AgentLoopDeps<TOutput = unknown> {
     host?: unknown;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
+    /**
+     * The agent's personas. Read ONLY when the run names one (`AgentRunInput.persona`), and then only
+     * once, inside the `persona:resolve` checkpoint — so a replay runs under the persona the turn
+     * started with even after this list changed. Undefined → no personas.
+     */
+    personas?: Persona[];
     /**
      * Per-tool execution timeout in ms. A tool that runs longer is aborted and recorded as failed
      * (the model gets the timeout as its result and can adapt) rather than hanging the turn.
@@ -3123,7 +3163,7 @@ interface AgentLoopResult<TOutput = unknown> {
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
  * hooks that make the same loop body either in-process or a replay-safe durable workflow.
  */
-declare function runAgentLoop<TOutput = unknown>(boundDeps: AgentLoopDeps<TOutput>, input: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
+declare function runAgentLoop<TOutput = unknown>(boundDeps: AgentLoopDeps<TOutput>, requested: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
 
 /** Payloads carried on each `aviary:agent:*` channel. */
 interface AgentRunStarted {
@@ -3132,6 +3172,8 @@ interface AgentRunStarted {
     actorId: string;
     /** Which agent is handling the run. */
     agentName?: string;
+    /** The persona of that agent the run is under, when it is under one. */
+    persona?: string;
 }
 interface AgentMessageEvent {
     runId: string;
@@ -3474,6 +3516,8 @@ declare class InMemoryAgentStore implements AgentStore, ChatQueueStore {
      * this scalar has a method to ask for it.
      */
     defaultAgentForThread(threadId: string): Promise<string | null>;
+    /** The thread's persona, projected like {@link defaultAgentForThread}. */
+    personaForThread(threadId: string): Promise<string | null>;
     /** The thread's pinned model, projected like {@link defaultAgentForThread}. */
     modelForThread(threadId: string): Promise<string | null>;
     /**
@@ -3516,7 +3560,8 @@ declare class InMemoryAgentStore implements AgentStore, ChatQueueStore {
     setMessageFeedback(messageId: string, feedback: MessageFeedback | null): Promise<void>;
     truncateFrom(threadId: string, messageId: string): Promise<void>;
     /**
-     * Of `mediaIds`, the ones a surviving message in one of this actor's threads still carries.
+     * Of `mediaIds`, the ones a surviving message — or a message waiting in the queue — in one of
+     * this actor's threads still carries.
      * Re-derived from the messages each call, so a media whose message was truncated away reads as
      * unreferenced again.
      */
@@ -3956,4 +4001,4 @@ declare class SqlTokenStreamSink implements TokenStreamSink {
     private purgeInBackground;
 }
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_CONFIRM_TOKEN_STORE, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStartOptions, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingDescription, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, CONFIRM_JSON_SCHEMA_PROPERTIES, ChatQueueStore, ClosedRolesPolicy, type ConfirmFields, type ConfirmTokenClaim, ConfirmTokenError, type ConfirmTokenStore, type ConfirmTokenSubject, type ConfirmedTool, type ConfirmedToolDone, type ConfirmedToolMessages, type ConfirmedToolOptions, type ConfirmedToolOutcome, type ConfirmedToolPreview, type ConfirmedToolResult, type ConfirmedToolSteps, type CostUsage, CreateThreadInput, type CurrentModelPrice, DEFAULT_CONFIRM_TTL_MS, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type EmptyRoles, EnqueueMessageInput, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernanceMessageRow, type GovernancePage, type GovernancePageQuery, type GovernancePendingApprovalRow, type GovernanceRange, type GovernanceRunDetail, type GovernanceRunRow, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceThreadRow, type GovernanceToolCallRow, type GovernanceUsageInput, type GovernanceUsageRow, HistoryPolicy, HumanReply, InMemoryAgentStore, InMemoryConfirmTokenStore, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogLock, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QueuePause, QueuedMessage, QueuedMessagePatch, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWarning, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, RUN_FAILED_MESSAGE, RUN_NOT_ACTIVE_CODE, RUN_NOT_ACTIVE_MESSAGE, RUN_NO_LONGER_RUNNING, type RecentRunRow, RecordRunStartInput, RecordToolCallInput, RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RolesPolicyOptions, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SCHEMA_EXTENSION, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type SchemaExtension, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettleDeadRunInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, SqlTokenStreamSink, type SqlTokenStreamSinkOptions, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StreamFrameRow, type StreamFrameTable, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, ToolCallApprovalState, ToolCallOutcome, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDescribeScope, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, UpdateThreadInput, UpdateToolCallInput, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, canonicalJson, closeEmptyRoles, compositeSkillProvider, confirmTokenExpiry, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, defineConfirmedTool, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, exposeStreamErrorDetails, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, hashConfirmToken, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, quotaUsedRatio, quotaWarning, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, schemaExtensionOf, seedModelPrices, settleAll, settleDeadRun, settleUnsettledDelegation, signConfirmToken, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, streamFailure, summarizeWithModel, tenantScope, toolCallApprovalFromRow, toolCallContext, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, verifyConfirmToken, windowHistory, withAskTool, withConfirmFields, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_CONFIRM_TOKEN_STORE, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStartOptions, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingDescription, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, CONFIRM_JSON_SCHEMA_PROPERTIES, ChatQueueStore, ClosedRolesPolicy, type ConfirmFields, type ConfirmTokenClaim, ConfirmTokenError, type ConfirmTokenStore, type ConfirmTokenSubject, type ConfirmedTool, type ConfirmedToolDone, type ConfirmedToolMessages, type ConfirmedToolOptions, type ConfirmedToolOutcome, type ConfirmedToolPreview, type ConfirmedToolResult, type ConfirmedToolSteps, type CostUsage, CreateThreadInput, type CurrentModelPrice, DEFAULT_CONFIRM_TTL_MS, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type EmptyRoles, EnqueueMessageInput, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernanceMessageRow, type GovernancePage, type GovernancePageQuery, type GovernancePendingApprovalRow, type GovernanceRange, type GovernanceRunDetail, type GovernanceRunRow, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceThreadRow, type GovernanceToolCallRow, type GovernanceUsageInput, type GovernanceUsageRow, HistoryPolicy, HumanReply, InMemoryAgentStore, InMemoryConfirmTokenStore, type IncrementalGate, InputProcessor, type InvokeOptions, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogLock, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, Persona, type PersonaAlias, PersonaCatalogEntry, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QueuePause, QueuedMessage, QueuedMessagePatch, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWarning, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, RUN_FAILED_MESSAGE, RUN_NOT_ACTIVE_CODE, RUN_NOT_ACTIVE_MESSAGE, RUN_NO_LONGER_RUNNING, type RecentRunRow, RecordRunStartInput, RecordToolCallInput, RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RolesPolicyOptions, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SCHEMA_EXTENSION, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type SchemaExtension, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettleDeadRunInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, SqlTokenStreamSink, type SqlTokenStreamSinkOptions, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StreamFrameRow, type StreamFrameTable, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, ToolCallApprovalState, ToolCallOutcome, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDescribeScope, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, UpdateThreadInput, UpdateToolCallInput, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, canonicalJson, closeEmptyRoles, compositeSkillProvider, confirmTokenExpiry, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, defineConfirmedTool, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, exposeStreamErrorDetails, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, findPersona, gateFollowUps, gateTail, hashConfirmToken, intersectAllowLists, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, personaCatalogEntry, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, quotaUsedRatio, quotaWarning, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolvePersonaAlias, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, schemaExtensionOf, seedModelPrices, settleAll, settleDeadRun, settleUnsettledDelegation, signConfirmToken, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, streamFailure, summarizeWithModel, tenantScope, toolCallApprovalFromRow, toolCallContext, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, verifyConfirmToken, windowHistory, withAskTool, withConfirmFields, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };