@dudousxd/nestjs-agent-core 0.31.0 → 0.33.0

package/dist/{tool-B0J4Fjyd.d.cts → tool-CMTuoJ2v.d.cts}

@@ -263,102 +263,6 @@ interface AgentIntake {
 }
 declare const DEFAULT_INTAKE_PREAMBLE = "A few questions before I start. I have pre-picked what I would choose, so confirming is enough.";
 
-/**
- * The ceiling on how much of a thread rides into a turn. Without one, `runAgentLoop` maps EVERY
- * message the store returns into the model's messages, so a long-lived thread grows until the
- * provider rejects the request — and every turn before that one pays for the whole transcript.
- * `@dudousxd/nestjs-agent-core` ships `windowHistory` as the built-in; anything satisfying this SPI
- * works. Wire it as `AgentLoopDeps.historyPolicy`, or via `AgentModule.forRoot({ history })` /
- * `@Agent({ history })`.
- */
-
-/** Whose history this is — enough for a policy to size the window per agent or per actor. */
-interface HistoryPolicyContext {
-    threadId: string;
-    actor: Actor;
-    /** The agent running this turn. Undefined → the default agent. */
-    agentName?: string;
-}
-/** How a policy split the thread: what rides into the turn, and what the ceiling left out. */
-interface HistorySelection {
-    /** Sent to the model, oldest-first. */
-    keep: ModelMessage[];
-    /** Left out, oldest-first. Folded into a leading summary when the policy implements `summarize`. */
-    drop: ModelMessage[];
-}
-/** A stand-in for the messages a window left out, plus what producing it cost. */
-interface HistorySummary {
-    /** Prose the loop folds into the window as a leading `system` message. */
-    text: string;
-    /**
-     * What the summarizer spent, when it called a model. Recorded as a `history_summary` usage row, so
-     * a ceiling on context cost cannot itself become spend nothing accounts for. Omit for a summarizer
-     * that calls no model (a rollup of tool names, a digest the app already stored).
-     */
-    usage?: MessageUsage;
-    /** Accounting label for the model that produced it; falls back to `AgentLoopDeps.modelId`. */
-    modelId?: string;
-}
-interface HistoryPolicy {
-    /**
-     * The most messages {@link select} can ever keep, where the ceiling can be stated as a row count.
-     *
-     * A hint the loop hands to the store, which then reads that many of the thread's newest rows
-     * rather than its whole transcript (see `ThreadTurnReader`). Declaring it is a PROMISE about
-     * `select`: that it keeps at most this many messages, and that they are the NEWEST ones — so a
-     * window of this size is indistinguishable, to `select`, from the full transcript. A policy that
-     * can keep more than this, or can keep something older than the newest `maxMessages`, must omit it
-     * rather than select over rows the store was never asked for.
-     *
-     * Omit where the ceiling is not a row count at all — a token budget alone cannot name one, since
-     * one message can be four tokens or forty thousand. Omitting costs only the bound on the READ; the
-     * prompt is identical either way.
-     */
-    readonly maxMessages?: number;
-    /**
-     * Decide what the model sees.
-     *
-     * MUST be a pure function of `messages`. The loop calls it INSIDE the `load:thread` checkpoint and
-     * records its result there, so the ceiling bounds the journal as well as the prompt: what the
-     * checkpoint holds is the selection rather than the store's whole `ThreadDetail`, on a payload
-     * every replay re-reads. It still adds no position of its own — a policy cannot change the name or
-     * position of a single existing checkpoint.
-     *
-     * Read a clock, a feature flag or a database here and the resumed run windows differently from the
-     * one that suspended: the model gets a different prompt, and any step whose existence depends on
-     * the split lands at a position the history has no room for. Anything non-deterministic belongs in
-     * {@link summarize}, which has a checkpoint of its own.
-     *
-     * The newest message must always be in `keep` — dropping it leaves the turn with nothing to answer.
-     */
-    select(messages: ModelMessage[], ctx: HistoryPolicyContext): HistorySelection;
-    /**
-     * Fold the dropped messages into prose the model reads in their place, prepended to the window as
-     * a `system` message. Optional — without it, dropped messages are simply gone, and `load:thread`
-     * does not record them either: a summarizer is the only thing that ever reads them back.
-     *
-     * Runs inside the loop's `history:summarize` checkpoint, so it may call a model or hit the
-     * network: the first attempt's result is journaled and every replay reads it back instead of
-     * re-summarizing. It runs once per RUN (not per model step), and only when `select` actually
-     * dropped something.
-     */
-    summarize?(dropped: ModelMessage[], ctx: HistoryPolicyContext): Promise<HistorySummary>;
-}
-/**
- * The window an agent asks for declaratively — `AgentModule.forRoot({ history })` and
- * `@Agent({ history })`. Plain data, so it can live in a decorator's metadata; the NestJS layer
- * turns it into a `windowHistory` policy. A consumer needing anything the window can't express
- * supplies a {@link HistoryPolicy} instead.
- */
-interface AgentHistoryWindow {
-    /** Keep at most this many of the newest messages. */
-    maxMessages?: number;
-    /** Keep the newest messages whose estimated tokens fit this budget. */
-    maxTokens?: number;
-    /** Fold what the window left out into a leading summary — one extra model call per run. */
-    summarize?: boolean;
-}
-
 /**
  * The structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
  *
@@ -578,6 +482,22 @@ type AgentStreamEvent = {
  */
  | {
     kind: 'cancelled';
+}
+/**
+ * The thread's message queue changed — a snapshot of the whole queue, never a delta, so a client
+ * that missed one frame is corrected by the next. Written into the stream of the run that is
+ * holding the thread: when someone queues, edits, reorders or removes a waiting message, and, just
+ * before this run's own terminal frame, with what happens next — `started` names the queued
+ * message that became the next turn and that turn's run id (attach to it with
+ * `GET <base>/chat/:runId/stream`), `queue.paused` says why nothing starts.
+ */
+ | {
+    kind: 'queue';
+    queue: ChatQueueState;
+    started?: {
+        messageId: string;
+        runId: string;
+    };
 };
 /** Encode one event as an NDJSON line (`{...}\n`) for {@link SinkWriter.write}. */
 declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
@@ -591,6 +511,567 @@ declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
  */
 declare function decodeStreamEvent(line: string): AgentStreamEvent | null;
 
+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;
+    }>;
+}
+
+/**
+ * Why a thread's queue stopped draining. A paused queue keeps its messages; nothing starts until
+ * someone resumes it (`POST <base>/threads/:id/queue/resume`, `chat.queue.resume()`).
+ *
+ *  - `run_failed`     the turn before it failed — the next message would likely fail the same way,
+ *                     and the person should see the error before more of their messages are spent.
+ *  - `cancelled`      someone pressed Stop. Stop means stop: the queue does not start behind it.
+ *                     An interrupt (`mode: 'interrupt'`) is the exception — its message starts.
+ *  - `quota_exceeded` the next message's actor is over budget; resuming later retries the check.
+ *  - `start_failed`   the next message could not be started (the runner refused it).
+ */
+type QueuePauseReason = 'run_failed' | 'cancelled' | 'quota_exceeded' | 'start_failed';
+interface QueuePause {
+    reason: QueuePauseReason;
+    /** Human-facing detail (the failure, the quota window), when there is one. */
+    message?: string;
+    /** ISO-8601 instant the queue paused. */
+    at: string;
+}
+/**
+ * A message a person sent while a turn was still running on the thread, waiting its turn. It is not
+ * part of the transcript until it starts: the loop appends it as the turn's user message, exactly as
+ * if it had been sent then. Everything a send carries is captured at enqueue time, resolved and
+ * checked there (agent, model, attachments), so a queued message starts with no request around it.
+ */
+interface QueuedMessage {
+    id: string;
+    threadId: string;
+    /** Who queued it. The turn it starts runs as this actor. */
+    actor: Actor;
+    content: string;
+    attachments?: MessageAttachment[];
+    agentName?: string;
+    model?: string;
+    pageContext?: PageContext;
+    /**
+     * Queued by an interrupt (`POST chat { mode: 'interrupt' }`): the running turn was cancelled to
+     * make room for it, so the cancel starts it instead of pausing the queue.
+     */
+    interrupt?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A queued message as the wire shows it — {@link QueuedMessage} without the actor or thread. */
+interface QueuedMessageView {
+    id: string;
+    content: string;
+    attachments?: MessageAttachment[];
+    agentName?: string;
+    model?: string;
+    interrupt?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * A thread's queue: its waiting messages in the order they will run, and whether it is draining.
+ * What `GET <base>/threads/:id/queue` answers, what `ThreadDetail.queue` carries, and what every
+ * `queue` stream frame snapshots.
+ */
+interface ChatQueueState {
+    items: QueuedMessageView[];
+    paused: QueuePause | null;
+}
+interface EnqueueMessageInput {
+    threadId: string;
+    actor: Actor;
+    content: string;
+    attachments?: MessageAttachment[];
+    agentName?: string;
+    model?: string;
+    pageContext?: PageContext;
+    interrupt?: boolean;
+    /** `'tail'` (default) runs it after everything already waiting; `'head'` runs it next. */
+    at?: 'tail' | 'head';
+}
+/**
+ * What a store may change on a waiting message (`PATCH <base>/queue/:messageId` sets the text and
+ * attachments). An omitted key leaves the field as it is.
+ */
+interface QueuedMessagePatch {
+    content?: string;
+    /** `null` drops every attachment. */
+    attachments?: MessageAttachment[] | null;
+    /**
+     * Mark (or unmark) the message as an interrupt — what `POST <base>/queue/:messageId/interrupt`
+     * does to a message that is already waiting, before it cancels the running turn for it.
+     */
+    interrupt?: boolean;
+}
+/**
+ * A store that can hold a thread's queue of waiting messages, and admit ONE run per thread at a time.
+ *
+ * Probed STRUCTURALLY ({@link isChatQueueStore}), like `ThreadTurnReader`: a store that predates it
+ * keeps the old behaviour (a send on a busy thread starts a second, concurrent run). All members or
+ * none — a queue without the admission primitives cannot be drained safely across processes.
+ *
+ * Admission is the thread's `activeStreamId`, compare-and-set:
+ *  - {@link claimActiveStream} sets it to `runId` only when it is free, already `runId` (a retried
+ *    claim is idempotent), or held by `replacing` (a handoff from the run that is settling, or a
+ *    takeover from a holder the runner reports dead). Exactly one of two racing claims wins.
+ *  - {@link releaseActiveStream} clears it only when `runId` still holds it — so a run that settles
+ *    after it handed the thread to the next one cannot clear the next one's claim.
+ */
+interface ChatQueueStore {
+    enqueueMessage(input: EnqueueMessageInput): Promise<QueuedMessage>;
+    /** The thread's waiting messages, in run order (the head first). */
+    listQueue(threadId: string): Promise<QueuedMessage[]>;
+    getQueuedMessage(id: string): Promise<QueuedMessage | null>;
+    /** `null` when there is no such message (it started, or was removed). */
+    updateQueuedMessage(id: string, patch: QueuedMessagePatch): Promise<QueuedMessage | null>;
+    /** Move a message to `index` (clamped) in its thread's run order. `false` when it is gone. */
+    moveQueuedMessage(id: string, index: number): Promise<boolean>;
+    /**
+     * Remove a message. `false` when it was already gone — which is also how a drain learns that the
+     * head it was about to start was deleted under it, so it must be a real conditional delete.
+     */
+    removeQueuedMessage(id: string): Promise<boolean>;
+    /** Remove every waiting message on the thread; answers how many there were. */
+    clearQueue(threadId: string): Promise<number>;
+    queuePause(threadId: string): Promise<QueuePause | null>;
+    setQueuePause(threadId: string, pause: QueuePause | null): Promise<void>;
+    /** The run currently holding the thread, or `null`. */
+    activeRunForThread(threadId: string): Promise<string | null>;
+    claimActiveStream(threadId: string, runId: string, options?: {
+        replacing?: string;
+    }): Promise<boolean>;
+    releaseActiveStream(threadId: string, runId: string): Promise<boolean>;
+}
+/** Whether `store` implements every {@link ChatQueueStore} member. */
+declare function isChatQueueStore(store: AgentStore): store is AgentStore & ChatQueueStore;
+/**
+ * Release the thread `runId` was streaming — conditionally when the store can compare, so a run
+ * that already handed the thread to the next queued turn does not clear that turn's claim; the old
+ * unconditional clear on a store that cannot.
+ */
+declare function releaseThreadRun(store: AgentStore, threadId: string, runId: string): Promise<void>;
+/** The wire view of a queued message. */
+declare function queuedMessageView(message: QueuedMessage): QueuedMessageView;
+
+/**
+ * The ceiling on how much of a thread rides into a turn. Without one, `runAgentLoop` maps EVERY
+ * message the store returns into the model's messages, so a long-lived thread grows until the
+ * provider rejects the request — and every turn before that one pays for the whole transcript.
+ * `@dudousxd/nestjs-agent-core` ships `windowHistory` as the built-in; anything satisfying this SPI
+ * works. Wire it as `AgentLoopDeps.historyPolicy`, or via `AgentModule.forRoot({ history })` /
+ * `@Agent({ history })`.
+ */
+
+/** Whose history this is — enough for a policy to size the window per agent or per actor. */
+interface HistoryPolicyContext {
+    threadId: string;
+    actor: Actor;
+    /** The agent running this turn. Undefined → the default agent. */
+    agentName?: string;
+}
+/** How a policy split the thread: what rides into the turn, and what the ceiling left out. */
+interface HistorySelection {
+    /** Sent to the model, oldest-first. */
+    keep: ModelMessage[];
+    /** Left out, oldest-first. Folded into a leading summary when the policy implements `summarize`. */
+    drop: ModelMessage[];
+}
+/** A stand-in for the messages a window left out, plus what producing it cost. */
+interface HistorySummary {
+    /** Prose the loop folds into the window as a leading `system` message. */
+    text: string;
+    /**
+     * What the summarizer spent, when it called a model. Recorded as a `history_summary` usage row, so
+     * a ceiling on context cost cannot itself become spend nothing accounts for. Omit for a summarizer
+     * that calls no model (a rollup of tool names, a digest the app already stored).
+     */
+    usage?: MessageUsage;
+    /** Accounting label for the model that produced it; falls back to `AgentLoopDeps.modelId`. */
+    modelId?: string;
+}
+interface HistoryPolicy {
+    /**
+     * The most messages {@link select} can ever keep, where the ceiling can be stated as a row count.
+     *
+     * A hint the loop hands to the store, which then reads that many of the thread's newest rows
+     * rather than its whole transcript (see `ThreadTurnReader`). Declaring it is a PROMISE about
+     * `select`: that it keeps at most this many messages, and that they are the NEWEST ones — so a
+     * window of this size is indistinguishable, to `select`, from the full transcript. A policy that
+     * can keep more than this, or can keep something older than the newest `maxMessages`, must omit it
+     * rather than select over rows the store was never asked for.
+     *
+     * Omit where the ceiling is not a row count at all — a token budget alone cannot name one, since
+     * one message can be four tokens or forty thousand. Omitting costs only the bound on the READ; the
+     * prompt is identical either way.
+     */
+    readonly maxMessages?: number;
+    /**
+     * Decide what the model sees.
+     *
+     * MUST be a pure function of `messages`. The loop calls it INSIDE the `load:thread` checkpoint and
+     * records its result there, so the ceiling bounds the journal as well as the prompt: what the
+     * checkpoint holds is the selection rather than the store's whole `ThreadDetail`, on a payload
+     * every replay re-reads. It still adds no position of its own — a policy cannot change the name or
+     * position of a single existing checkpoint.
+     *
+     * Read a clock, a feature flag or a database here and the resumed run windows differently from the
+     * one that suspended: the model gets a different prompt, and any step whose existence depends on
+     * the split lands at a position the history has no room for. Anything non-deterministic belongs in
+     * {@link summarize}, which has a checkpoint of its own.
+     *
+     * The newest message must always be in `keep` — dropping it leaves the turn with nothing to answer.
+     */
+    select(messages: ModelMessage[], ctx: HistoryPolicyContext): HistorySelection;
+    /**
+     * Fold the dropped messages into prose the model reads in their place, prepended to the window as
+     * a `system` message. Optional — without it, dropped messages are simply gone, and `load:thread`
+     * does not record them either: a summarizer is the only thing that ever reads them back.
+     *
+     * Runs inside the loop's `history:summarize` checkpoint, so it may call a model or hit the
+     * network: the first attempt's result is journaled and every replay reads it back instead of
+     * re-summarizing. It runs once per RUN (not per model step), and only when `select` actually
+     * dropped something.
+     */
+    summarize?(dropped: ModelMessage[], ctx: HistoryPolicyContext): Promise<HistorySummary>;
+}
+/**
+ * The window an agent asks for declaratively — `AgentModule.forRoot({ history })` and
+ * `@Agent({ history })`. Plain data, so it can live in a decorator's metadata; the NestJS layer
+ * turns it into a `windowHistory` policy. A consumer needing anything the window can't express
+ * supplies a {@link HistoryPolicy} instead.
+ */
+interface AgentHistoryWindow {
+    /** Keep at most this many of the newest messages. */
+    maxMessages?: number;
+    /** Keep the newest messages whose estimated tokens fit this budget. */
+    maxTokens?: number;
+    /** Fold what the window left out into a leading summary — one extra model call per run. */
+    summarize?: boolean;
+}
+
 /**
  * How a person-facing surface talks about a tool WITHOUT ever naming it. Declared on the server,
  * beside the tool's input schema, because whoever changes the input is the one who has to re-word
@@ -1295,6 +1776,12 @@ interface ToolCallApproval {
 }
 interface ThreadDetail extends ThreadSummary {
     messages: StoredMessage[];
+    /**
+     * Messages sent while a turn was running, waiting to run after it, and whether the queue is
+     * draining. Present when the store supports a queue (`ChatQueueStore`); the REST read-model
+     * omits it otherwise.
+     */
+    queue?: ChatQueueState;
 }
 type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed'
 /** An approval request lapsed before anyone decided; the tool never ran. */
@@ -1485,4 +1972,4 @@ interface ToolDescription {
     inputSchema?: StandardSchemaV1;
 }
 
-export { type ElicitationInputType as $, type Actor as A, type ToolStepEnvelope as B, ALL_AGENTS as C, type DetachedDelivery as D, type ElicitationRequest as E, ASK_TOOL_DESCRIPTION as F, ASK_TOOL_NAME as G, type HumanReply as H, type AgentApprovalRequest as I, type AgentApprovalSettlement as J, type AgentAttachmentConfig as K, type LlmStepEnvelope as L, type ModelMessage as M, type AgentCatalogEntry as N, type AgentClientConfig as O, type PageContext as P, type QuotaState as Q, type AgentHistoryWindow as R, type StoredMessage as S, type ToolSpec as T, type UsagePurpose as U, type AskToolInput as V, DEFAULT_INTAKE_PREAMBLE as W, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as X, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as Y, ELICITATION_INPUT_TYPES as Z, type ElicitationInput as _, type ToolHandler as a, type ElicitationOption as a0, type ElicitationOutcome as a1, type ElicitationQuestion as a2, type ElicitationReply as a3, type ElicitationResult as a4, type HistoryPolicyContext as a5, type HistorySelection as a6, type HistorySummary as a7, type InvokeWithTransientRetryOptions as a8, MAX_ASK_QUESTIONS as a9, resolveElicitation as aA, resolveToolTransientRetryNumbers as aB, settleElicitation as aC, validateElicitationAnswer as aD, validateElicitationValue as aE, type MessageFeedbackValue as aa, type MessageRole as ab, type PromptContext as ac, type QuotaView as ad, type ToolCallApprovalStatus as ae, type ToolCatalogEntry as af, type ToolConfirmation as ag, type ToolDescription as ah, type ToolPresentationTone as ai, type ToolResultField as aj, type ToolResultView as ak, type ToolStepCtx as al, type ToolTransientRetryNumbers as am, type ToolTransientRetryOptions as an, askInputSchema as ao, askToolDefinition as ap, decodeStreamEvent as aq, encodeStreamEvent as ar, invokeWithTransientRetry as as, isTransientToolError as at, isTypedQuestion as au, normalizeElicitationReply as av, questionOptions as aw, readElicitationInput as ax, readElicitationQuestions as ay, renderElicitationAnswers as az, type ToolPresentation as b, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AiToolCtx as g, type AgentStreamEvent as h, type ThreadSummary as i, type ThreadDetail as j, type ToolResult as k, type MessageAttachment as l, type MessageFeedback as m, type ToolCallStatus as n, type AgentRunInput as o, type ToolKind as p, type ToolCallApproval as q, type HistoryPolicy as r, type AgentDefinition as s, type AgentDelegation as t, type ToolDescribeScope as u, type PromptBuilder as v, type PromptContributor as w, type ToolTransientRetrySetting as x, type AgentIntake as y, type Decision as z };
+export { ASK_TOOL_NAME as $, type Actor as A, type ThreadDetail as B, type ChatQueueStore as C, type DetachedDelivery as D, type ElicitationRequest as E, type ToolCallApprovalState as F, type EnqueueMessageInput as G, type HumanReply as H, type QueuedMessage as I, type QueuedMessagePatch as J, type QueuePause as K, type LlmStepEnvelope as L, type ModelMessage as M, type AppendMessageInput as N, type ToolResult as O, type PageContext as P, type QuotaState as Q, type RecordRunStartInput as R, type StoredMessage as S, type ToolSpec as T, type UpdateThreadInput as U, type MessageFeedback as V, type RecordToolCallInput as W, type UpdateToolCallInput as X, type RecordUsageInput as Y, ALL_AGENTS as Z, ASK_TOOL_DESCRIPTION as _, type ToolHandler as a, validateElicitationAnswer as a$, type AgentApprovalRequest as a0, type AgentApprovalSettlement as a1, type AgentAttachmentConfig as a2, type AgentCatalogEntry as a3, type AgentClientConfig as a4, type AgentHistoryWindow as a5, type AskToolInput as a6, type ChatQueueState as a7, DEFAULT_INTAKE_PREAMBLE as a8, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as a9, type ToolConfirmation as aA, type ToolDescription as aB, type ToolPresentationTone as aC, type ToolResultField as aD, type ToolResultView as aE, type ToolStepCtx as aF, type ToolTransientRetryNumbers as aG, type ToolTransientRetryOptions as aH, type UsagePurpose as aI, askInputSchema as aJ, askToolDefinition as aK, decodeStreamEvent as aL, encodeStreamEvent as aM, invokeWithTransientRetry as aN, isChatQueueStore as aO, isTransientToolError as aP, isTypedQuestion as aQ, normalizeElicitationReply as aR, questionOptions as aS, queuedMessageView as aT, readElicitationInput as aU, readElicitationQuestions as aV, releaseThreadRun as aW, renderElicitationAnswers as aX, resolveElicitation as aY, resolveToolTransientRetryNumbers as aZ, settleElicitation as a_, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as aa, ELICITATION_INPUT_TYPES as ab, type ElicitationInput as ac, type ElicitationInputType as ad, type ElicitationOption as ae, type ElicitationOutcome as af, type ElicitationQuestion as ag, type ElicitationReply as ah, type ElicitationResult as ai, type HistoryPolicyContext as aj, type HistorySelection as ak, type HistorySummary as al, type InvokeWithTransientRetryOptions as am, MAX_ASK_QUESTIONS as an, type MessageFeedbackValue as ao, type MessageRole as ap, type PromptContext as aq, type QueuePauseReason as ar, type QueuedMessageView as as, type QuotaView as at, type RecordRunEndInput as au, type ThreadTurnPage as av, type ThreadTurnQuery as aw, type ThreadTurnReader as ax, type ToolCallApprovalStatus as ay, type ToolCatalogEntry as az, type ToolPresentation as b, validateElicitationValue as b0, type ToolDefinition as c, type ToolCallRequest as d, type MessageUsage as e, type AgentUiComponent as f, type AiToolCtx as g, type AgentStreamEvent as h, type AgentRunInput as i, type MessageAttachment as j, type ToolKind as k, type ToolCallStatus as l, type ToolCallApproval as m, type HistoryPolicy as n, type AgentDefinition as o, type AgentDelegation as p, type AgentStore as q, type ToolDescribeScope as r, type PromptBuilder as s, type PromptContributor as t, type ToolTransientRetrySetting as u, type AgentIntake as v, type Decision as w, type ToolStepEnvelope as x, type CreateThreadInput as y, type ThreadSummary as z };