@dudousxd/nestjs-agent-core 0.31.0 → 0.32.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
-import { M as ModelMessage, c as ToolDefinition, d as ToolCallRequest, e as MessageUsage, f as AgentUiComponent, A as Actor, g as AiToolCtx, h as AgentStreamEvent, i as ThreadSummary, j as ThreadDetail, S as StoredMessage, k as ToolResult, l as MessageAttachment, m as MessageFeedback, n as ToolCallStatus, U as UsagePurpose, T as ToolSpec, Q as QuotaState, o as AgentRunInput, H as HumanReply, p as ToolKind, q as ToolCallApproval, a as ToolHandler, r as HistoryPolicy, P as PageContext, s as AgentDefinition, t as AgentDelegation, D as DetachedDelivery, u as ToolDescribeScope, v as PromptBuilder, w as PromptContributor, x as ToolTransientRetrySetting, y as AgentIntake, z as Decision, E as ElicitationRequest, L as LlmStepEnvelope, B as ToolStepEnvelope } from './tool-B0J4Fjyd.cjs';
-export { C as ALL_AGENTS, F as ASK_TOOL_DESCRIPTION, G as ASK_TOOL_NAME, I as AgentApprovalRequest, J as AgentApprovalSettlement, K as AgentAttachmentConfig, N as AgentCatalogEntry, O as AgentClientConfig, R as AgentHistoryWindow, V as AskToolInput, W as DEFAULT_INTAKE_PREAMBLE, X as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Y as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, Z as ELICITATION_INPUT_TYPES, _ as ElicitationInput, $ as ElicitationInputType, a0 as ElicitationOption, a1 as ElicitationOutcome, a2 as ElicitationQuestion, a3 as ElicitationReply, a4 as ElicitationResult, a5 as HistoryPolicyContext, a6 as HistorySelection, a7 as HistorySummary, a8 as InvokeWithTransientRetryOptions, a9 as MAX_ASK_QUESTIONS, aa as MessageFeedbackValue, ab as MessageRole, ac as PromptContext, ad as QuotaView, ae as ToolCallApprovalStatus, af as ToolCatalogEntry, ag as ToolConfirmation, ah as ToolDescription, b as ToolPresentation, ai as ToolPresentationTone, aj as ToolResultField, ak as ToolResultView, al as ToolStepCtx, am as ToolTransientRetryNumbers, an as ToolTransientRetryOptions, ao as askInputSchema, ap as askToolDefinition, aq as decodeStreamEvent, ar as encodeStreamEvent, as as invokeWithTransientRetry, at as isTransientToolError, au as isTypedQuestion, av as normalizeElicitationReply, aw as questionOptions, ax as readElicitationInput, ay as readElicitationQuestions, az as renderElicitationAnswers, aA as resolveElicitation, aB as resolveToolTransientRetryNumbers, aC as settleElicitation, aD as validateElicitationAnswer, aE as validateElicitationValue } from './tool-B0J4Fjyd.cjs';
+import { M as ModelMessage, c as ToolDefinition, d as ToolCallRequest, e as MessageUsage, f as AgentUiComponent, A as Actor, g as AiToolCtx, h as AgentStreamEvent, T as ToolSpec, Q as QuotaState, i as AgentRunInput, H as HumanReply, j as MessageAttachment, k as ToolKind, l as ToolCallStatus, m as ToolCallApproval, a as ToolHandler, n as HistoryPolicy, P as PageContext, o as AgentDefinition, p as AgentDelegation, q as AgentStore, D as DetachedDelivery, r as ToolDescribeScope, s as PromptBuilder, t as PromptContributor, u as ToolTransientRetrySetting, v as AgentIntake, w as Decision, E as ElicitationRequest, L as LlmStepEnvelope, x as ToolStepEnvelope, C as ChatQueueStore, y as CreateThreadInput, z as ThreadSummary, B as ThreadDetail, F as ToolCallApprovalState, U as UpdateThreadInput, R as RecordRunStartInput, G as EnqueueMessageInput, I as QueuedMessage, J as QueuedMessagePatch, K as QueuePause, N as AppendMessageInput, S as StoredMessage, O as ToolResult, V as MessageFeedback, W as RecordToolCallInput, X as UpdateToolCallInput, Y as RecordUsageInput } from './tool-BhhzEI40.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 AskToolInput, a7 as ChatQueueState, a8 as DEFAULT_INTAKE_PREAMBLE, a9 as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, aa as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, ab as ELICITATION_INPUT_TYPES, ac as ElicitationInput, ad as ElicitationInputType, ae as ElicitationOption, af as ElicitationOutcome, ag as ElicitationQuestion, ah as ElicitationReply, ai as ElicitationResult, aj as HistoryPolicyContext, ak as HistorySelection, al as HistorySummary, am as InvokeWithTransientRetryOptions, an as MAX_ASK_QUESTIONS, ao as MessageFeedbackValue, ap as MessageRole, aq as PromptContext, ar as QueuePauseReason, as as QueuedMessageView, at as QuotaView, au as RecordRunEndInput, av as ThreadTurnPage, aw as ThreadTurnQuery, ax as ThreadTurnReader, ay as ToolCallApprovalStatus, az as ToolCatalogEntry, aA as ToolConfirmation, aB as ToolDescription, b as ToolPresentation, aC as ToolPresentationTone, aD as ToolResultField, aE as ToolResultView, aF as ToolStepCtx, aG as ToolTransientRetryNumbers, aH as ToolTransientRetryOptions, aI as UsagePurpose, aJ as askInputSchema, aK as askToolDefinition, aL as decodeStreamEvent, aM as encodeStreamEvent, aN as invokeWithTransientRetry, aO as isChatQueueStore, aP as isTransientToolError, aQ as isTypedQuestion, aR as normalizeElicitationReply, aS as questionOptions, aT as queuedMessageView, aU as readElicitationInput, aV as readElicitationQuestions, aW as releaseThreadRun, aX as renderElicitationAnswers, aY as resolveElicitation, aZ as resolveToolTransientRetryNumbers, a_ as settleElicitation, a$ as validateElicitationAnswer, b0 as validateElicitationValue } from './tool-BhhzEI40.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-DdnRmmlq.cjs';
-export { D as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, b as IncrementalGating, c as OutputRejectedError, d as OutputVerdict, e as ProcessorFailedError } from './processors-DdnRmmlq.cjs';
+import { O as OutputProcessor, P as ProcessorContext, I as InputProcessor, a as ProcessedPrompt, M as ModelAnswer } from './processors-DQJ5sWw7.cjs';
+export { D as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, b as IncrementalGating, c as OutputRejectedError, d as OutputVerdict, e as ProcessorFailedError } from './processors-DQJ5sWw7.cjs';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
 /**
@@ -352,332 +352,6 @@ declare function createUiCollector(toolCallId: string, write?: (event: AgentStre
 /** Merge component lists: first-seen order, the last props for each id. */
 declare function mergeUi(...lists: readonly (readonly AgentUiComponent[] | undefined)[]): AgentUiComponent[];
 
-interface CreateThreadInput {
-    actor: Actor;
-    transient?: boolean;
-    title?: string;
-}
-interface AppendMessageInput {
-    threadId: string;
-    role: StoredMessage['role'];
-    content: string;
-    /** Which agent produced this message (assistant messages) — provenance. */
-    agentName?: string;
-    toolCalls?: ToolCallRequest[];
-    toolResults?: ToolResult[];
-    /** Files the user attached to this message (image/PDF). Persisted verbatim. */
-    attachments?: MessageAttachment[];
-    followUps?: string[];
-    usage?: MessageUsage;
-    /**
-     * The run (turn) that produced this message. Without it a consumer can only guess which turn a
-     * message belongs to by comparing timestamps against the run's `startedAt`, and that guess breaks
-     * the moment a turn is regenerated — the replaced answer is truncated away, so the times no longer
-     * line up 1:1. Optional so a caller predating this (and a host that appends messages outside a
-     * run) can omit it; the store persists it as `null` when absent.
-     */
-    runId?: string;
-    /** The step's streamed thinking. See {@link StoredMessage.reasoning}. */
-    reasoning?: string;
-    /** Time spent thinking in this step, in ms. See {@link StoredMessage.reasoningMs}. */
-    reasoningMs?: number;
-    /** Components pushed during this step. See {@link StoredMessage.ui}. */
-    ui?: AgentUiComponent[];
-}
-interface RecordToolCallInput {
-    toolCallId: string;
-    messageId: string;
-    toolName: string;
-    toolType: 'read' | 'action';
-    input: unknown;
-    status: ToolCallStatus;
-    /**
-     * The run (turn) this tool call belongs to — enables a governance surface to deep-link a tool
-     * call out to its trace waterfall. Optional so a caller predating this (or a store's own
-     * synthetic tool calls) can omit it; the store persists it as `null` when absent.
-     */
-    runId?: string;
-    /**
-     * Who has to approve this call (`'requester'` or a role), from the turn's `ApprovalPolicy`. Set on
-     * an action call that was put to a person — or approved by a remembered decision — and never
-     * otherwise; persisted as `null` when absent.
-     */
-    approver?: string;
-    /** ISO-8601 instant the approval request lapses. Absent → it never does. */
-    expiresAt?: string;
-}
-interface UpdateToolCallInput {
-    toolCallId: string;
-    status: ToolCallStatus;
-    output?: unknown;
-    error?: string;
-    executionMs?: number;
-    executedByRef?: string;
-    /** The approval asked for later calls of this tool in this thread to run without asking. */
-    remember?: boolean;
-    /** The surface the decision came through. See {@link import('../types.js').Decision.decidedVia}. */
-    decidedVia?: string;
-}
-/** What the approve/reject routes need to know about a call before they signal a decision on it. */
-interface ToolCallApprovalState {
-    status: ToolCallStatus;
-    /** `null` for a call no policy put to anyone (an `ask`, or a row written before approvers existed). */
-    approver: string | null;
-    expiresAt: string | null;
-}
-/** Patch applied by {@link AgentStore.updateThread}. An omitted key leaves that field untouched. */
-interface UpdateThreadInput {
-    title?: string;
-    /** `null` clears the thread's default agent (falls back to the module default). */
-    defaultAgent?: string | null;
-    /** `null` unpins the thread's model (turns run on the provider default). */
-    model?: string | null;
-}
-interface RecordUsageInput {
-    threadId: string;
-    actorRef: string;
-    messageId?: string;
-    modelId: string;
-    purpose: UsagePurpose;
-    usage: MessageUsage;
-    /** Provider-reported actual USD cost for this turn, when known (gateways report it). */
-    costUsd?: number;
-}
-interface RecordRunStartInput {
-    runId: string;
-    threadId: string;
-    actorRef: string;
-    agentName?: string;
-    /**
-     * The run that started this one, for a delegation's child run. The parent->child edge exists in
-     * the durable runtime's own journal, but only there: a governance surface reading run rows alone
-     * cannot roll a delegation's cost up to the turn that asked for it, and a DETACHED child outlives
-     * its parent's turn entirely, so nothing in the transcript pairs them either.
-     *
-     * Optional, and a store that persists nothing for it still works — it loses the tree, not the run.
-     */
-    parentRunId?: string;
-    /** sha256 hex of the run's resolved (pre-RAG) system prompt — identifies the prompt VERSION. */
-    promptHash?: string;
-}
-interface RecordRunEndInput {
-    runId: string;
-    /**
-     * `cancelled` is a THIRD terminal, not a flavour of `failed`: someone asked the run to stop and it
-     * did, which is the control working. A consumer computing a failure rate over these rows has to be
-     * able to leave it out — counting a user pressing Stop as an error pages whoever is on call for
-     * model failures. It carries no `errorCode`/`errorMessage`, since there is nothing to diagnose.
-     */
-    status: 'completed' | 'failed' | 'cancelled';
-    durationMs?: number;
-    errorCode?: string;
-    errorMessage?: string;
-}
-/** Which thread, and how many of its newest messages, {@link ThreadTurnReader.loadThreadForTurn} reads. */
-interface ThreadTurnQuery {
-    threadId: string;
-    /** Omitted reads every message; `0` reads none. */
-    messageLimit?: number;
-}
-/** What a turn reads off a thread — a bounded window, not the transcript. */
-interface ThreadTurnPage {
-    title: string;
-    defaultAgent: string | null;
-    /** Whether the THREAD has ever been answered, not whether {@link messages} holds an answer. */
-    hasAssistantMessage: boolean;
-    /** Oldest first, carrying only the fields a model turn reads. */
-    messages: StoredMessage[];
-}
-/**
- * A store that can hand a turn the WINDOW it is about to send, instead of the thread's transcript.
- *
- * {@link AgentStore.getThread} materializes every message row, every attachment and every tool
- * output a thread ever recorded, and the run then journals what it loaded — so a long thread pays
- * for its whole history on every turn and again on every replay, to send a prompt bounded to its
- * last few messages. This read is bounded by the database (`order by created_at desc limit ?`),
- * projected to the columns a model turn actually reads.
- *
- * `hasAssistantMessage` is answered over the WHOLE thread, never the page: it answers "has this
- * conversation been answered before?" — what a `thread-start` intake asks — and a thread whose window
- * happens to hold only the user's last questions has still been answered. `null` for a thread that is
- * unknown or soft-deleted, matching `getThread`.
- *
- * Probed STRUCTURALLY rather than declared on {@link AgentStore}, the same way `defaultAgentForThread`
- * is: it is an optimization a store either offers or does not, and one that predates it still answers
- * correctly through the full read.
- */
-interface ThreadTurnReader {
-    loadThreadForTurn(query: ThreadTurnQuery): Promise<ThreadTurnPage | null>;
-}
-/** ORM-agnostic persistence. Refs are string ids; adapters may add real relations. */
-interface AgentStore {
-    createThread(input: CreateThreadInput): Promise<ThreadSummary>;
-    getThread(threadId: string): Promise<ThreadDetail | null>;
-    listThreads(actorRef: string, limit?: number): Promise<ThreadSummary[]>;
-    softDeleteThread(threadId: string): Promise<void>;
-    forkThread(threadId: string, fromMessageId: string): Promise<ThreadSummary>;
-    setTitle(threadId: string, title: string): Promise<void>;
-    /**
-     * Promote a transient thread to a persistent one so it shows up in {@link listThreads}. A
-     * transient thread is a scratch conversation the caller has not chosen to keep; "saving" it
-     * clears the flag. Idempotent — promoting an already-persistent thread is a no-op.
-     */
-    promoteThread(threadId: string): Promise<void>;
-    setActiveStream(threadId: string, runId: string | null): Promise<void>;
-    /**
-     * OPTIONAL: rename a thread and/or set its default agent in one write. Absent on a store that
-     * predates this — `setTitle` still covers title-only edits, so nothing else in the lib requires
-     * this method; the REST `PATCH /threads/:id` endpoint responds 501 for a `defaultAgent` change
-     * against a store that lacks it.
-     */
-    updateThread?(threadId: string, patch: UpdateThreadInput): Promise<void>;
-    /**
-     * OPTIONAL: the runId of a currently-running turn on this thread, or `null` if none is running.
-     * Lets a client that reconnects (page refresh) discover a run to reattach to via the existing
-     * `GET /chat/:runId/stream`, instead of only being told about a run right after starting it.
-     * Absent on a store that predates this — thread read/list payloads report `activeRunId: null`.
-     */
-    activeRunForThread?(threadId: string): Promise<string | null>;
-    /**
-     * OPTIONAL: persist the start of a run (turn). Replay-safe: called under a durable localStep.
-     * Absent on a store that predates run recording — reliability metrics degrade to zeros/empty.
-     */
-    recordRunStart?(run: RecordRunStartInput): Promise<void>;
-    /** OPTIONAL: settle a run's outcome. `errorCode`/`errorMessage` only when status is 'failed'. */
-    recordRunEnd?(end: RecordRunEndInput): Promise<void>;
-    /** OPTIONAL: bump the run's llm-step retry counter (dispatched-step attempt > 1). */
-    bumpRunRetries?(runId: string): Promise<void>;
-    /**
-     * The `actorRef` that owns a thread, or `null` if no such thread exists. The authorization seam
-     * for thread-scoped endpoints (detail / delete / fork): the service compares this against the
-     * resolved caller before acting, so one actor can never read or mutate another's thread.
-     */
-    ownerOfThread(threadId: string): Promise<string | null>;
-    /**
-     * The `actorRef` that owns the thread a tool call belongs to, or `null` if the call is unknown.
-     * The authorization seam for HITL approve / reject: the caller must own the run they approve.
-     */
-    ownerOfToolCall(toolCallId: string): Promise<string | null>;
-    /**
-     * The run awaiting a decision on `toolCallId`: the call's OWN `runId` when the row carries one,
-     * else the thread's `activeStreamId`. Both HITL approve/reject and an elicitation answer route
-     * through this, derived server-side from the tool call alone — so a decision reaches the exact run
-     * awaiting it, including a sub-agent's own child run, which the client never sees and could not
-     * name. No client-supplied runId is trusted (or needed).
-     *
-     * The row's own runId comes FIRST because `activeStreamId` names whichever run is streaming the
-     * thread right now, and that is only the same run while a thread holds exactly one. The fallback
-     * is for rows written before tool calls recorded a runId, which have nothing else to answer with.
-     */
-    runForToolCall(toolCallId: string): Promise<string | null>;
-    /**
-     * The `actorRef` that owns the thread currently streaming `runId` (its `activeStreamId`), or
-     * `null` if no thread is streaming it. The authorization seam for `cancel`: the caller must own
-     * the run they abort. Resolvable during the live window (a run cancel only matters while active).
-     */
-    ownerOfActiveStream(runId: string): Promise<string | null>;
-    appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
-    /**
-     * Attach a turn's settled tool RESULTS to a message that was already appended, replacing whatever
-     * it held. A message's tool calls are known when it is written and their outputs are not, but a
-     * thread reader pairs the two off THAT MESSAGE — so an output that only ever reaches the tool-call
-     * table leaves every call on a reopened thread looking like a tool still running.
-     *
-     * Required rather than optional: a store that silently declines this renders a finished turn as a
-     * permanently in-flight one, with nothing logged and nothing to notice. A missing method should
-     * fail to compile instead.
-     */
-    setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
-    /**
-     * Replace the components persisted on an already-appended message (see {@link StoredMessage.ui}).
-     * The loop calls it once per step, after the step's tools ran, with every component the step
-     * showed — the model turn's own `ui` frames first, then what its tools pushed through
-     * `ctx.emitUi`, in call order, deduplicated by `id`. A full replacement, never an append, so a
-     * repeated call writes the same value.
-     *
-     * OPTIONAL: a store without it still streams tool-pushed components live; a reload then shows
-     * only the ones the model turn itself produced.
-     */
-    setMessageUi?(messageId: string, ui: AgentUiComponent[]): Promise<void>;
-    truncateFrom(threadId: string, messageId: string): Promise<void>;
-    /**
-     * OPTIONAL: the thread a message belongs to, or `null` when there is no such message. The
-     * authorization seam for message-scoped routes (feedback): the service resolves the thread's owner
-     * from it. Implement it together with {@link setMessageFeedback}.
-     */
-    threadOfMessage?(messageId: string): Promise<string | null>;
-    /**
-     * OPTIONAL: set (or, with `null`, clear) the rating on a message — see
-     * {@link import('../types.js').StoredMessage.feedback}. Absent → `POST /messages/:id/feedback`
-     * answers `501`.
-     */
-    setMessageFeedback?(messageId: string, feedback: MessageFeedback | null): Promise<void>;
-    recordToolCall(input: RecordToolCallInput): Promise<void>;
-    updateToolCall(input: UpdateToolCallInput): Promise<void>;
-    /**
-     * OPTIONAL: the names of the tools whose approval someone asked to REMEMBER in this thread — an
-     * approved call persisted with `remember: true`. The loop approves a later call of one of them
-     * without asking, inside that call's own `persist:toolcall` checkpoint. Absent → nothing is ever
-     * remembered, and every call asks.
-     */
-    rememberedApprovals?(threadId: string): Promise<string[]>;
-    /**
-     * OPTIONAL: a call's approval state, or `null` when the call is unknown. Read by the approve/reject
-     * routes to enforce the recorded approver and refuse a decision on a request that already
-     * expired. Absent → every call is treated as the requester's, with no expiry (the old behaviour).
-     */
-    toolCallApproval?(toolCallId: string): Promise<ToolCallApprovalState | null>;
-    /**
-     * OPTIONAL: the input a call was recorded with, or `null` when the call is unknown. Read by the
-     * answer route to check a reply against the questions it answers (a typed question's rules, a
-     * `required` one left empty) before it is signalled. Absent → answers are checked for shape only,
-     * and the loop drops what it cannot settle.
-     */
-    toolCallInput?(toolCallId: string): Promise<unknown>;
-    /**
-     * OPTIONAL: of `mediaIds`, the ones a message that still exists — in a thread owned by
-     * `actorRef` — still carries as an attachment. The inverse of
-     * {@link import('./attachment-staging.js').AttachmentStagingStore.list}: the host can enumerate
-     * the media it staged but cannot see a transcript, and this side sees every transcript but never
-     * holds the bytes, so neither can decide alone what is safe to delete.
-     *
-     * DERIVED, not tracked. A reference is not permanent: `truncateFrom` deletes messages — which is
-     * exactly what regenerating a turn does — so media that was referenced becomes unreferenced
-     * again. A flag set when a message is sent would never be unset by that delete, and the bytes
-     * 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.
-     *
-     * 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
-     * candidate ids are already the caller's own.
-     *
-     * Returns each id at most once, in the order asked. Absent on a store that predates this — a
-     * caller must treat the absence as "cannot answer" and collect NOTHING, never as "nothing is
-     * referenced", which would delete every attachment the actor ever sent.
-     */
-    referencedMediaIds?(actorRef: string, mediaIds: readonly string[]): Promise<string[]>;
-    recordUsage(input: RecordUsageInput): Promise<void>;
-    /**
-     * The actor's spend for `day` (UTC): total tokens plus the summed provider-reported USD cost.
-     * `costUsd` is `0` when no turn on that day reported a cost (token-only providers). Feeds both
-     * quota enforcement (via {@link QuotaStore}) and the quota-today view.
-     */
-    quotaToday(actorRef: string, day: string): Promise<{
-        usedTokens: number;
-        costUsd: number;
-    }>;
-    /**
-     * OPTIONAL: the actor's spend over the UTC days `fromDay`..`toDay` (`YYYY-MM-DD`, inclusive) —
-     * {@link quotaToday} over a range. Feeds the monthly window of `GET <base>/quota`; absent → that
-     * window is left out.
-     */
-    usageBetween?(actorRef: string, fromDay: string, toDay: string): Promise<{
-        usedTokens: number;
-        costUsd: number;
-    }>;
-}
-
 /**
  * Decides whether an actor may invoke a tool. The default impl checks the actor's role
  * against `spec.roles` (defaulting to an ADMIN-only set). Apps can plug `nestjs-authz`
@@ -875,10 +549,29 @@ interface Reranker {
  * `start` ENQUEUES and returns immediately with the runId — the live tokens flow on the
  * TokenStreamSink, not through this call.
  */
+/** How {@link AgentRunner.start} starts a run. */
+interface AgentRunStartOptions {
+    /**
+     * Use this id for the run instead of minting one. The chat queue claims the thread for a run
+     * BEFORE starting it (so no second turn can slip in between), which needs the id up front; a
+     * queued message's run id is the message's own id, which also makes a retried start idempotent.
+     * A runner that ignores it still works — the service then re-points the thread at the id it
+     * returned.
+     */
+    runId?: string;
+}
 interface AgentRunner {
-    start(input: AgentRunInput): Promise<{
+    start(input: AgentRunInput, options?: AgentRunStartOptions): Promise<{
         runId: string;
     }>;
+    /**
+     * OPTIONAL: whether `runId` is still running (or parked, or about to start) as far as this runner
+     * can tell. Asked when a thread's admission is held by a run, to tell a live holder from a stale
+     * one a crashed process left behind — a stale holder is replaced instead of queueing behind it
+     * for ever. Answer `true` when unsure: a wrong `false` starts a second turn on the thread. Absent
+     * → every holder is treated as live.
+     */
+    isRunActive?(runId: string): Promise<boolean>;
     /**
      * Deliver a human's reply to a parked tool call — a {@link import('../types.js').Decision} on an
      * action tool, or an `ElicitationReply` answering a question set. One channel for both, because
@@ -3630,8 +3323,11 @@ interface GovernanceRunRow {
     parentRunId?: string;
 }
 /** A fully in-memory `AgentStore` for tests and the offline demo. */
-declare class InMemoryAgentStore implements AgentStore {
+declare class InMemoryAgentStore implements AgentStore, ChatQueueStore {
     private readonly threads;
+    /** Each thread's waiting messages, in run order. */
+    private readonly queues;
+    private readonly pauses;
     private readonly toolCalls;
     private readonly usage;
     private readonly runs;
@@ -3680,6 +3376,20 @@ declare class InMemoryAgentStore implements AgentStore {
     bumpRunRetries(runId: string): Promise<void>;
     promoteThread(threadId: string): Promise<void>;
     setActiveStream(threadId: string, runId: string | null): Promise<void>;
+    claimActiveStream(threadId: string, runId: string, options?: {
+        replacing?: string;
+    }): Promise<boolean>;
+    releaseActiveStream(threadId: string, runId: string): Promise<boolean>;
+    enqueueMessage(input: EnqueueMessageInput): Promise<QueuedMessage>;
+    listQueue(threadId: string): Promise<QueuedMessage[]>;
+    getQueuedMessage(id: string): Promise<QueuedMessage | null>;
+    updateQueuedMessage(id: string, patch: QueuedMessagePatch): Promise<QueuedMessage | null>;
+    moveQueuedMessage(id: string, index: number): Promise<boolean>;
+    removeQueuedMessage(id: string): Promise<boolean>;
+    clearQueue(threadId: string): Promise<number>;
+    queuePause(threadId: string): Promise<QueuePause | null>;
+    setQueuePause(threadId: string, pause: QueuePause | null): Promise<void>;
+    private findQueued;
     appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
     setMessageToolResults(messageId: string, results: ToolResult[]): Promise<void>;
     setMessageUi(messageId: string, ui: AgentUiComponent[]): Promise<void>;
@@ -3744,4 +3454,4 @@ declare class InMemoryAgentStore implements AgentStore {
     private toSummary;
 }
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, 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 AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingDescription, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, 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 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, 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, 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, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, 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, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, 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, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, 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, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, 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, ChatQueueStore, type CostUsage, CreateThreadInput, type CurrentModelPrice, 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, 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, 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, type RecentRunRow, RecordRunStartInput, RecordToolCallInput, RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, 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, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, 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, 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, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createNoopEmitUi, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, 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, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };