@dudousxd/nestjs-agent 1.14.0 → 1.16.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-DkWvoWbD.cjs';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QuotaLimits, i as QuotaWindowLimits, j as delegateToolName, p as provideAgentTool, k as provideAgentTools, u as utcDay } from './agent-deps.factory-DkWvoWbD.cjs';
-import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AgentApprovalPort, ActorResolver, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentSkillsOptions } from './chat-queue.service-Bqq00NN1.cjs';
+export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, i as QueueSettleOutcome, j as QueuedTurn, k as QueuedTurnStarter, l as QuotaLimits, m as QuotaWindowLimits, n as delegateToolName, p as provideAgentTool, o as provideAgentTools, u as utcDay } from './chat-queue.service-Bqq00NN1.cjs';
+import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AgentApprovalPort, ActorResolver, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -12,6 +12,34 @@ declare class AgentModule {
     static forRootAsync(options: AgentModuleAsyncOptions): DynamicModule;
 }
 
+/**
+ * What a send does when its thread already has a turn running:
+ *  - `'auto'` (default) — run now when the thread is idle, else wait in the thread's queue.
+ *  - `'queue'` — always wait in the queue, behind whatever is already waiting (it still starts at
+ *    once when nothing is running and nothing is ahead of it).
+ *  - `'interrupt'` — cancel the running turn and run this one next, ahead of the queue.
+ */
+type ChatSendMode = 'auto' | 'queue' | 'interrupt';
+/** A send that is waiting in its thread's queue instead of running. */
+interface QueuedSend {
+    threadId: string;
+    queued: true;
+    /** The queued message's id — also the run id it will start under. */
+    messageId: string;
+    /** 0-based place in the queue at the time it was queued (`0` → next). */
+    position: number;
+    queue: ChatQueueState;
+    /** The turn it started under, when it started straight away (an idle thread). */
+    runId?: string;
+    /** The run an interrupt cancelled to make room for it. */
+    interrupting?: string;
+}
+/** What {@link AgentService.send} did: started a turn, or queued the message. */
+type ChatSendResult = {
+    runId: string;
+    threadId: string;
+    queued?: undefined;
+} | QueuedSend;
 interface ChatParams {
     actor: Actor;
     message: string;
@@ -36,6 +64,8 @@ interface ChatParams {
      * the thread list until the caller promotes it. Ignored when `threadId` is set.
      */
     transient?: boolean;
+    /** What to do when the thread already has a turn running — see {@link ChatSendMode}. */
+    mode?: ChatSendMode;
 }
 /**
  * A store that can answer a thread's default agent on its own, without materializing the thread.
@@ -60,7 +90,12 @@ declare class AgentService {
     private readonly models?;
     private readonly quotaProvider?;
     private readonly options?;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined);
+    private readonly queue?;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, queue?: ChatQueueService | undefined);
+    /** The queue service when the bound store can hold a queue, else `undefined`. */
+    private queueing;
+    /** The queue service, or a 501 naming what is missing. */
+    private requireQueue;
     /**
      * The actor's budget across windows (`GET <base>/quota`) — the bound {@link QuotaProvider}'s
      * report. Without one (a service built outside the module), a day window from the ledger.
@@ -89,10 +124,66 @@ declare class AgentService {
      */
     private resolveModel;
     private threadModel;
+    /**
+     * Start a turn — for in-process callers that need a run id back. A send that would have to wait
+     * (its thread already has a turn running) is refused with `409` instead; {@link send} is the form
+     * that queues it.
+     */
     chat(params: ChatParams): Promise<{
         runId: string;
         threadId: string;
     }>;
+    /**
+     * Send a message: start a turn, or — when its thread already has one running — queue the message
+     * to run after it (see {@link ChatSendMode}). What `POST <base>/chat` calls.
+     */
+    send(params: ChatParams): Promise<ChatSendResult>;
+    /**
+     * Start a turn the thread is already claimed for, under the claimed id. A runner that minted an
+     * id of its own anyway gets the thread re-pointed at it; one that fails to start frees the thread.
+     */
+    private startClaimed;
+    /** Put a send in its thread's queue, then drain it if the thread turned out to be free. */
+    private enqueue;
+    /** `GET <base>/threads/:id/queue` — the thread's waiting messages and whether it drains. */
+    getQueue(actor: Actor, threadId: string): Promise<ChatQueueState>;
+    /**
+     * `PATCH <base>/queue/:messageId` — change a waiting message's text and/or attachments, and/or move
+     * it to `position` in the queue. Answers the thread's queue.
+     */
+    updateQueuedMessage(actor: Actor, messageId: string, patch: {
+        message?: string;
+        attachments?: AttachmentRef[] | null;
+        position?: number;
+    }): Promise<ChatQueueState>;
+    /** `DELETE <base>/queue/:messageId` — drop a waiting message. Answers the thread's queue. */
+    removeQueuedMessage(actor: Actor, messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/queue/:messageId/interrupt` — run a message that is already waiting NOW: it moves
+     * to the head of its queue marked as an interrupt, any pause is lifted, and the running turn is
+     * cancelled (its settle starts this message — the same path a `mode: 'interrupt'` send takes).
+     * With nothing running, the message starts at once.
+     *
+     * One request, and the message never leaves the queue: a client that removed it and sent it again
+     * would lose it if the second call failed, and would run it twice if another tab's drain started
+     * it in between. Answers the queue, plus `interrupting` (the run that was cancelled) or `runId`
+     * (the run this message started).
+     */
+    interruptQueuedMessage(actor: Actor, messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
+    /** `DELETE <base>/threads/:id/queue` — drop every waiting message (and any pause). */
+    clearQueue(actor: Actor, threadId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/threads/:id/queue/resume` — lift a pause and start the head when nothing is
+     * running. Answers the queue, and the run the head started under, if it did.
+     */
+    resumeQueue(actor: Actor, threadId: string): Promise<ChatQueueState & {
+        runId?: string;
+    }>;
+    /** The thread a queued message waits on, once the caller is shown to own it. */
+    private assertOwnsQueuedMessage;
     /**
      * Rebuild this turn's attachments from the staging store, keyed by the ids the caller claimed.
      * The model provider fetches {@link MessageAttachment.url} verbatim, so that url is only ever
@@ -866,6 +957,7 @@ declare function resolveSkillsConfig(options: AgentSkillsOptions | undefined, de
 declare class InlineAgentRunner implements AgentRunner {
     private readonly factory;
     private readonly store;
+    private readonly queue?;
     private readonly logger;
     private readonly pending;
     /**
@@ -874,8 +966,15 @@ declare class InlineAgentRunner implements AgentRunner {
      * running it. A cancelled id is dropped once the run settles, so the set tracks live runs only.
      */
     private readonly cancelled;
-    constructor(factory: AgentDepsFactory, store: AgentStore);
-    start(input: AgentRunInput): Promise<{
+    /** Top-level runs this process is running now — what {@link isRunActive} answers from. */
+    private readonly live;
+    constructor(factory: AgentDepsFactory, store: AgentStore, queue?: ChatQueueService | undefined);
+    /**
+     * In-process, so exact: a run this process is not running is not running anywhere — the process
+     * that was running it is gone (a restart), and a thread it still holds is a stale claim.
+     */
+    isRunActive(runId: string): Promise<boolean>;
+    start(input: AgentRunInput, options?: AgentRunStartOptions): Promise<{
         runId: string;
     }>;
     signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
@@ -901,6 +1000,15 @@ declare class InlineAgentRunner implements AgentRunner {
      * streams does not retry this one.
      */
     private settleCancelled;
+    /**
+     * Move the thread past a settling TOP-LEVEL run — to the next queued message, which starts here,
+     * or to a paused/empty queue — and write the resulting `queue` frame into this run's stream. A
+     * no-op without a queue-capable store, and for a run that is not a thread's own turn.
+     *
+     * Never throws: the run is settling either way, and a queue that could not be advanced is picked
+     * up by the next send or resume on the thread.
+     */
+    private settleQueue;
     /**
      * Park a run on a human, keyed by run + tool call. One map for approvals and for question-set
      * answers alike: both wait on the same key, and `signal` cannot tell (or need to tell) which
@@ -933,6 +1041,43 @@ declare class InlineAgentRunner implements AgentRunner {
     private runNested;
 }
 
+interface UpdateQueuedMessageBody {
+    /** The new text. */
+    message?: unknown;
+    /** `[{ mediaId }]` refs replacing the message's attachments; `null` or `[]` drops them. */
+    attachments?: unknown;
+    /** Move the message to this 0-based place in the queue. */
+    position?: unknown;
+}
+/**
+ * The thread message queue: messages sent while a turn was running, waiting to run after it. Every
+ * route is ownership-gated like the thread routes, and answers the thread's queue as it now stands
+ * (`{ items, paused }`). A change is also announced to whoever is streaming the thread, as a `queue`
+ * frame in the running turn's stream.
+ */
+declare class QueueController {
+    private readonly agent;
+    private readonly actorResolver;
+    constructor(agent: AgentService, actorResolver: ActorResolver);
+    list(req: Request, id: string): Promise<ChatQueueState>;
+    clear(req: Request, id: string): Promise<ChatQueueState>;
+    /** Lift a pause; the head starts when nothing is running. Carries `runId` when it started. */
+    resume(req: Request, id: string): Promise<ChatQueueState & {
+        runId?: string;
+    }>;
+    update(req: Request, messageId: string, body: UpdateQueuedMessageBody): Promise<ChatQueueState>;
+    /**
+     * Run a waiting message now: it moves to the head as an interrupt and the running turn is
+     * cancelled for it. Carries `interrupting` (the cancelled run), or `runId` when nothing was
+     * running and it started at once.
+     */
+    interrupt(req: Request, messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
+    remove(req: Request, messageId: string): Promise<ChatQueueState>;
+}
+
 /**
  * The default `TokenStreamSink`: buffers chunks per run in-process so a reconnecting subscriber
  * replays everything so far, then follows live.
@@ -1040,4 +1185,4 @@ declare function defaultRequestUserMapper(user: Record<string, unknown>): Actor;
  */
 declare function requestUserActorResolver<TUser = Record<string, unknown>>(map?: RequestUserMapper<TUser>): ActorResolver;
 
-export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, type RequestUserMapper, type ResolvedAiToolOptions, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-DkWvoWbD.js';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QuotaLimits, i as QuotaWindowLimits, j as delegateToolName, p as provideAgentTool, k as provideAgentTools, u as utcDay } from './agent-deps.factory-DkWvoWbD.js';
-import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AgentApprovalPort, ActorResolver, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentSkillsOptions } from './chat-queue.service-Bqq00NN1.js';
+export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, i as QueueSettleOutcome, j as QueuedTurn, k as QueuedTurnStarter, l as QuotaLimits, m as QuotaWindowLimits, n as delegateToolName, p as provideAgentTool, o as provideAgentTools, u as utcDay } from './chat-queue.service-Bqq00NN1.js';
+import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AgentApprovalPort, ActorResolver, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -12,6 +12,34 @@ declare class AgentModule {
     static forRootAsync(options: AgentModuleAsyncOptions): DynamicModule;
 }
 
+/**
+ * What a send does when its thread already has a turn running:
+ *  - `'auto'` (default) — run now when the thread is idle, else wait in the thread's queue.
+ *  - `'queue'` — always wait in the queue, behind whatever is already waiting (it still starts at
+ *    once when nothing is running and nothing is ahead of it).
+ *  - `'interrupt'` — cancel the running turn and run this one next, ahead of the queue.
+ */
+type ChatSendMode = 'auto' | 'queue' | 'interrupt';
+/** A send that is waiting in its thread's queue instead of running. */
+interface QueuedSend {
+    threadId: string;
+    queued: true;
+    /** The queued message's id — also the run id it will start under. */
+    messageId: string;
+    /** 0-based place in the queue at the time it was queued (`0` → next). */
+    position: number;
+    queue: ChatQueueState;
+    /** The turn it started under, when it started straight away (an idle thread). */
+    runId?: string;
+    /** The run an interrupt cancelled to make room for it. */
+    interrupting?: string;
+}
+/** What {@link AgentService.send} did: started a turn, or queued the message. */
+type ChatSendResult = {
+    runId: string;
+    threadId: string;
+    queued?: undefined;
+} | QueuedSend;
 interface ChatParams {
     actor: Actor;
     message: string;
@@ -36,6 +64,8 @@ interface ChatParams {
      * the thread list until the caller promotes it. Ignored when `threadId` is set.
      */
     transient?: boolean;
+    /** What to do when the thread already has a turn running — see {@link ChatSendMode}. */
+    mode?: ChatSendMode;
 }
 /**
  * A store that can answer a thread's default agent on its own, without materializing the thread.
@@ -60,7 +90,12 @@ declare class AgentService {
     private readonly models?;
     private readonly quotaProvider?;
     private readonly options?;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined);
+    private readonly queue?;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, queue?: ChatQueueService | undefined);
+    /** The queue service when the bound store can hold a queue, else `undefined`. */
+    private queueing;
+    /** The queue service, or a 501 naming what is missing. */
+    private requireQueue;
     /**
      * The actor's budget across windows (`GET <base>/quota`) — the bound {@link QuotaProvider}'s
      * report. Without one (a service built outside the module), a day window from the ledger.
@@ -89,10 +124,66 @@ declare class AgentService {
      */
     private resolveModel;
     private threadModel;
+    /**
+     * Start a turn — for in-process callers that need a run id back. A send that would have to wait
+     * (its thread already has a turn running) is refused with `409` instead; {@link send} is the form
+     * that queues it.
+     */
     chat(params: ChatParams): Promise<{
         runId: string;
         threadId: string;
     }>;
+    /**
+     * Send a message: start a turn, or — when its thread already has one running — queue the message
+     * to run after it (see {@link ChatSendMode}). What `POST <base>/chat` calls.
+     */
+    send(params: ChatParams): Promise<ChatSendResult>;
+    /**
+     * Start a turn the thread is already claimed for, under the claimed id. A runner that minted an
+     * id of its own anyway gets the thread re-pointed at it; one that fails to start frees the thread.
+     */
+    private startClaimed;
+    /** Put a send in its thread's queue, then drain it if the thread turned out to be free. */
+    private enqueue;
+    /** `GET <base>/threads/:id/queue` — the thread's waiting messages and whether it drains. */
+    getQueue(actor: Actor, threadId: string): Promise<ChatQueueState>;
+    /**
+     * `PATCH <base>/queue/:messageId` — change a waiting message's text and/or attachments, and/or move
+     * it to `position` in the queue. Answers the thread's queue.
+     */
+    updateQueuedMessage(actor: Actor, messageId: string, patch: {
+        message?: string;
+        attachments?: AttachmentRef[] | null;
+        position?: number;
+    }): Promise<ChatQueueState>;
+    /** `DELETE <base>/queue/:messageId` — drop a waiting message. Answers the thread's queue. */
+    removeQueuedMessage(actor: Actor, messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/queue/:messageId/interrupt` — run a message that is already waiting NOW: it moves
+     * to the head of its queue marked as an interrupt, any pause is lifted, and the running turn is
+     * cancelled (its settle starts this message — the same path a `mode: 'interrupt'` send takes).
+     * With nothing running, the message starts at once.
+     *
+     * One request, and the message never leaves the queue: a client that removed it and sent it again
+     * would lose it if the second call failed, and would run it twice if another tab's drain started
+     * it in between. Answers the queue, plus `interrupting` (the run that was cancelled) or `runId`
+     * (the run this message started).
+     */
+    interruptQueuedMessage(actor: Actor, messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
+    /** `DELETE <base>/threads/:id/queue` — drop every waiting message (and any pause). */
+    clearQueue(actor: Actor, threadId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/threads/:id/queue/resume` — lift a pause and start the head when nothing is
+     * running. Answers the queue, and the run the head started under, if it did.
+     */
+    resumeQueue(actor: Actor, threadId: string): Promise<ChatQueueState & {
+        runId?: string;
+    }>;
+    /** The thread a queued message waits on, once the caller is shown to own it. */
+    private assertOwnsQueuedMessage;
     /**
      * Rebuild this turn's attachments from the staging store, keyed by the ids the caller claimed.
      * The model provider fetches {@link MessageAttachment.url} verbatim, so that url is only ever
@@ -866,6 +957,7 @@ declare function resolveSkillsConfig(options: AgentSkillsOptions | undefined, de
 declare class InlineAgentRunner implements AgentRunner {
     private readonly factory;
     private readonly store;
+    private readonly queue?;
     private readonly logger;
     private readonly pending;
     /**
@@ -874,8 +966,15 @@ declare class InlineAgentRunner implements AgentRunner {
      * running it. A cancelled id is dropped once the run settles, so the set tracks live runs only.
      */
     private readonly cancelled;
-    constructor(factory: AgentDepsFactory, store: AgentStore);
-    start(input: AgentRunInput): Promise<{
+    /** Top-level runs this process is running now — what {@link isRunActive} answers from. */
+    private readonly live;
+    constructor(factory: AgentDepsFactory, store: AgentStore, queue?: ChatQueueService | undefined);
+    /**
+     * In-process, so exact: a run this process is not running is not running anywhere — the process
+     * that was running it is gone (a restart), and a thread it still holds is a stale claim.
+     */
+    isRunActive(runId: string): Promise<boolean>;
+    start(input: AgentRunInput, options?: AgentRunStartOptions): Promise<{
         runId: string;
     }>;
     signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
@@ -901,6 +1000,15 @@ declare class InlineAgentRunner implements AgentRunner {
      * streams does not retry this one.
      */
     private settleCancelled;
+    /**
+     * Move the thread past a settling TOP-LEVEL run — to the next queued message, which starts here,
+     * or to a paused/empty queue — and write the resulting `queue` frame into this run's stream. A
+     * no-op without a queue-capable store, and for a run that is not a thread's own turn.
+     *
+     * Never throws: the run is settling either way, and a queue that could not be advanced is picked
+     * up by the next send or resume on the thread.
+     */
+    private settleQueue;
     /**
      * Park a run on a human, keyed by run + tool call. One map for approvals and for question-set
      * answers alike: both wait on the same key, and `signal` cannot tell (or need to tell) which
@@ -933,6 +1041,43 @@ declare class InlineAgentRunner implements AgentRunner {
     private runNested;
 }
 
+interface UpdateQueuedMessageBody {
+    /** The new text. */
+    message?: unknown;
+    /** `[{ mediaId }]` refs replacing the message's attachments; `null` or `[]` drops them. */
+    attachments?: unknown;
+    /** Move the message to this 0-based place in the queue. */
+    position?: unknown;
+}
+/**
+ * The thread message queue: messages sent while a turn was running, waiting to run after it. Every
+ * route is ownership-gated like the thread routes, and answers the thread's queue as it now stands
+ * (`{ items, paused }`). A change is also announced to whoever is streaming the thread, as a `queue`
+ * frame in the running turn's stream.
+ */
+declare class QueueController {
+    private readonly agent;
+    private readonly actorResolver;
+    constructor(agent: AgentService, actorResolver: ActorResolver);
+    list(req: Request, id: string): Promise<ChatQueueState>;
+    clear(req: Request, id: string): Promise<ChatQueueState>;
+    /** Lift a pause; the head starts when nothing is running. Carries `runId` when it started. */
+    resume(req: Request, id: string): Promise<ChatQueueState & {
+        runId?: string;
+    }>;
+    update(req: Request, messageId: string, body: UpdateQueuedMessageBody): Promise<ChatQueueState>;
+    /**
+     * Run a waiting message now: it moves to the head as an interrupt and the running turn is
+     * cancelled for it. Carries `interrupting` (the cancelled run), or `runId` when nothing was
+     * running and it started at once.
+     */
+    interrupt(req: Request, messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
+    remove(req: Request, messageId: string): Promise<ChatQueueState>;
+}
+
 /**
  * The default `TokenStreamSink`: buffers chunks per run in-process so a reconnecting subscriber
  * replays everything so far, then follows live.
@@ -1040,4 +1185,4 @@ declare function defaultRequestUserMapper(user: Record<string, unknown>): Actor;
  */
 declare function requestUserActorResolver<TUser = Record<string, unknown>>(map?: RequestUserMapper<TUser>): ActorResolver;
 
-export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, type RequestUserMapper, type ResolvedAiToolOptions, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };