@dudousxd/nestjs-agent 1.14.0 → 1.15.0

package/README.md

@@ -302,6 +302,25 @@ as long as ids only increase — see *Numbering a stream you rebuild* in the pro
 `Last-Event-ID` header) skips what a reconnecting client already has; the React transport uses it to
 continue a message after a network drop. See docs/stream-protocol.md.
 
+### Sending while a turn is running (the message queue)
+
+`POST /agent/chat` on a thread that already has a turn running no longer starts a second one: the
+message is queued on the thread (persisted — it survives restarts) and the answer is `202 { queued:
+true, messageId, position, queue }`. When the running turn completes, the next queued message
+starts under its own id, and the settling turn's stream says so in a final `queue` frame
+(`started: { messageId, runId }`). `mode: 'interrupt'` cancels the running turn and runs the message
+next; `mode: 'queue'` always queues. A failed turn or a Stop pauses the queue (`POST
+/agent/threads/:id/queue/resume` lifts it); an exhausted quota pauses it as the next message starts.
+`GET`/`DELETE /agent/threads/:id/queue`, `PATCH`/`DELETE /agent/queue/:messageId` list, clear,
+edit, move and remove what is waiting.
+
+Both runners and both SQL stores support it (`ChatQueueStore`; the stores add an
+`agent_queued_message` table and an `agent_thread.queue_pause` column on boot). Admission is a
+compare-and-set on the thread's active run, so exactly one turn runs per thread across pods, and a
+durable drain is journaled — it never starts a queued message twice. `AgentService.chat()` stays a
+start-or-refuse call for in-process callers (`409 run_active` on a busy thread); `send()` is the
+queueing one. Policy and wire contract: *Message queue* in docs/stream-protocol.md.
+
 ### Message feedback
 
 `POST /agent/messages/:id/feedback` `{ value: 'up' | 'down' | null, comment? }` rates a message in

package/dist/{agent-deps.factory-DkWvoWbD.d.cts → chat-queue.service-Bqq00NN1.d.cts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason, Actor } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -513,4 +513,133 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, LedgerQuotaProvider as L, type QuotaLimits as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QuotaWindowLimits as i, delegateToolName as j, provideAgentTools as k, provideAgentTool as p, utcDay as u };
+/** How the run that held a thread ended. */
+type QueueSettleOutcome = 'completed' | 'failed' | 'cancelled';
+/** The next queued message a settling run handed the thread to — the caller starts it. */
+interface QueuedTurn {
+    /** The run id the thread is already claimed for: the queued message's own id. */
+    runId: string;
+    input: AgentRunInput;
+    messageId: string;
+}
+/**
+ * What {@link ChatQueueService.plan} decided. Plain data, so a durable workflow can journal it in a
+ * `localStep` and start `next` itself (`ctx.startChild`) — replay-safe, and never twice.
+ */
+interface QueuePlan {
+    next?: QueuedTurn;
+    /** The `queue` frame to write into the settling run's stream, before its terminal. */
+    frame?: AgentStreamEvent;
+}
+/** Starts a run under a pre-claimed id — a runner's own `start`, bound. */
+type QueuedTurnStarter = (input: AgentRunInput, runId: string) => Promise<unknown>;
+/**
+ * The thread-level message queue: messages a person sends while a turn is running wait here, and
+ * the next one starts as soon as the running turn settles.
+ *
+ * Everything that decides WHICH run holds a thread goes through the store's compare-and-set
+ * admission (`claimActiveStream` / `releaseActiveStream`), so two processes that both try to start
+ * the next turn — a settling run on a worker and a send on an API pod — cannot both win. The next
+ * run's id is the queued message's own id, which makes every step here idempotent: a retried claim
+ * for the same message succeeds again, and a durable start under the same id is a no-op.
+ *
+ * Policy, per outcome of the run that held the thread:
+ *  - `completed` → the head starts.
+ *  - `failed`    → the queue pauses (`run_failed`), keeping every message.
+ *  - `cancelled` → the queue pauses (`cancelled`), unless the head was queued by an interrupt — the
+ *                  cancel was made for it, so it starts.
+ * A paused queue starts nothing until it is resumed. A head whose actor is over quota pauses it
+ * (`quota_exceeded`) instead of starting.
+ */
+declare class ChatQueueService {
+    private readonly store;
+    private readonly sink;
+    private readonly quotaProvider?;
+    private readonly options?;
+    private readonly staging?;
+    private readonly logger;
+    /**
+     * Runs this process claimed a thread for and has not handed to a runner yet. A holder in here is
+     * alive whatever the runner says — it simply has not registered the run yet.
+     */
+    private readonly starting;
+    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined);
+    /** Whether the bound store can hold a queue. Without one, a busy thread is not queued. */
+    get supported(): boolean;
+    /** The bound store as a queue store, or a 501 naming what is missing. */
+    queueStore(): AgentStore & ChatQueueStore;
+    state(threadId: string): Promise<ChatQueueState>;
+    /**
+     * Whether `holder` is still running. A run this process is about to start is; otherwise the
+     * runner decides, and a runner that cannot tell says yes.
+     */
+    isAlive(holder: string, runner: AgentRunner): Promise<boolean>;
+    /**
+     * The run holding `threadId`, or `null` when it is free — a holder the runner reports dead counts
+     * as free, and is returned as `stale` so the caller can claim over it.
+     */
+    holder(threadId: string, runner: AgentRunner): Promise<{
+        live: string | null;
+        stale: string | null;
+    }>;
+    /**
+     * Decide what follows a TOP-LEVEL run that is settling on `threadId`, and move the thread there:
+     * hand it to the next queued message (claimed and popped here, started by the caller), or pause
+     * the queue, or release the thread. Call it BEFORE the run's terminal frame, so a client reading
+     * the stream learns what comes next from the `queue` frame, and so the thread is already free
+     * when the client sees the run end.
+     *
+     * A no-op returning `{}` on a store without a queue.
+     */
+    plan(args: {
+        threadId: string;
+        /** The run that is settling; `null` when the thread is idle (a kick). */
+        runId: string | null;
+        outcome: QueueSettleOutcome;
+        error?: string;
+    }): Promise<QueuePlan>;
+    /**
+     * {@link plan}, then start what it picked with `start`. What an in-process settle (the inline
+     * runner, a durable cancel issued outside a workflow) calls; answers the frame to write.
+     */
+    handoff(args: {
+        threadId: string;
+        runId: string;
+        outcome: QueueSettleOutcome;
+        error?: string;
+    }, start: QueuedTurnStarter): Promise<AgentStreamEvent | undefined>;
+    /**
+     * Start the head of an IDLE thread's queue — after a send queued behind a run that turned out to
+     * be gone, after a resume, after a stale holder. Does nothing while a live run holds the thread
+     * (its settle drains) or while the queue is paused. Answers the started run's id, if any.
+     */
+    kick(threadId: string, runner: AgentRunner): Promise<string | undefined>;
+    /**
+     * Start a turn the thread is already claimed for. On failure the message goes back to the head of
+     * the queue, the queue pauses (`start_failed`), and the claim is released — nothing is lost and
+     * nothing is left holding the thread.
+     */
+    launch(threadId: string, next: QueuedTurn, start: QueuedTurnStarter): Promise<boolean>;
+    /** Put a turn that never started back at the head of its queue, paused, and free the thread. */
+    restore(threadId: string, next: QueuedTurn, reason: QueuePauseReason, message: string): Promise<void>;
+    /** A `queue` frame with the thread's current state. */
+    pausedFrame(threadId: string): Promise<AgentStreamEvent>;
+    /**
+     * Tell whoever is watching the thread that its queue changed: a `queue` frame into the stream of
+     * the run holding it. Best-effort — a thread nobody is streaming has no one to tell, and the next
+     * read of the thread carries the queue anyway.
+     */
+    publish(threadId: string): Promise<ChatQueueState>;
+    private write;
+    /** Why `actor` may not start a turn now (the quota message), or `null`. */
+    quotaBlock(actor: Actor): Promise<string | null>;
+    /**
+     * The turn a queued message starts: everything it was queued with, today's date, and its
+     * attachments' urls minted afresh — the ones stored at enqueue time may have expired while it
+     * waited. An attachment the staging store no longer resolves keeps its stored url.
+     */
+    private inputFor;
+    private freshAttachments;
+}
+
+export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QueueSettleOutcome as i, type QueuedTurn as j, type QueuedTurnStarter as k, type QuotaLimits as l, type QuotaWindowLimits as m, delegateToolName as n, provideAgentTools as o, provideAgentTool as p, utcDay as u };

package/dist/{agent-deps.factory-DkWvoWbD.d.ts → chat-queue.service-Bqq00NN1.d.ts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason, Actor } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -513,4 +513,133 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, LedgerQuotaProvider as L, type QuotaLimits as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QuotaWindowLimits as i, delegateToolName as j, provideAgentTools as k, provideAgentTool as p, utcDay as u };
+/** How the run that held a thread ended. */
+type QueueSettleOutcome = 'completed' | 'failed' | 'cancelled';
+/** The next queued message a settling run handed the thread to — the caller starts it. */
+interface QueuedTurn {
+    /** The run id the thread is already claimed for: the queued message's own id. */
+    runId: string;
+    input: AgentRunInput;
+    messageId: string;
+}
+/**
+ * What {@link ChatQueueService.plan} decided. Plain data, so a durable workflow can journal it in a
+ * `localStep` and start `next` itself (`ctx.startChild`) — replay-safe, and never twice.
+ */
+interface QueuePlan {
+    next?: QueuedTurn;
+    /** The `queue` frame to write into the settling run's stream, before its terminal. */
+    frame?: AgentStreamEvent;
+}
+/** Starts a run under a pre-claimed id — a runner's own `start`, bound. */
+type QueuedTurnStarter = (input: AgentRunInput, runId: string) => Promise<unknown>;
+/**
+ * The thread-level message queue: messages a person sends while a turn is running wait here, and
+ * the next one starts as soon as the running turn settles.
+ *
+ * Everything that decides WHICH run holds a thread goes through the store's compare-and-set
+ * admission (`claimActiveStream` / `releaseActiveStream`), so two processes that both try to start
+ * the next turn — a settling run on a worker and a send on an API pod — cannot both win. The next
+ * run's id is the queued message's own id, which makes every step here idempotent: a retried claim
+ * for the same message succeeds again, and a durable start under the same id is a no-op.
+ *
+ * Policy, per outcome of the run that held the thread:
+ *  - `completed` → the head starts.
+ *  - `failed`    → the queue pauses (`run_failed`), keeping every message.
+ *  - `cancelled` → the queue pauses (`cancelled`), unless the head was queued by an interrupt — the
+ *                  cancel was made for it, so it starts.
+ * A paused queue starts nothing until it is resumed. A head whose actor is over quota pauses it
+ * (`quota_exceeded`) instead of starting.
+ */
+declare class ChatQueueService {
+    private readonly store;
+    private readonly sink;
+    private readonly quotaProvider?;
+    private readonly options?;
+    private readonly staging?;
+    private readonly logger;
+    /**
+     * Runs this process claimed a thread for and has not handed to a runner yet. A holder in here is
+     * alive whatever the runner says — it simply has not registered the run yet.
+     */
+    private readonly starting;
+    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined);
+    /** Whether the bound store can hold a queue. Without one, a busy thread is not queued. */
+    get supported(): boolean;
+    /** The bound store as a queue store, or a 501 naming what is missing. */
+    queueStore(): AgentStore & ChatQueueStore;
+    state(threadId: string): Promise<ChatQueueState>;
+    /**
+     * Whether `holder` is still running. A run this process is about to start is; otherwise the
+     * runner decides, and a runner that cannot tell says yes.
+     */
+    isAlive(holder: string, runner: AgentRunner): Promise<boolean>;
+    /**
+     * The run holding `threadId`, or `null` when it is free — a holder the runner reports dead counts
+     * as free, and is returned as `stale` so the caller can claim over it.
+     */
+    holder(threadId: string, runner: AgentRunner): Promise<{
+        live: string | null;
+        stale: string | null;
+    }>;
+    /**
+     * Decide what follows a TOP-LEVEL run that is settling on `threadId`, and move the thread there:
+     * hand it to the next queued message (claimed and popped here, started by the caller), or pause
+     * the queue, or release the thread. Call it BEFORE the run's terminal frame, so a client reading
+     * the stream learns what comes next from the `queue` frame, and so the thread is already free
+     * when the client sees the run end.
+     *
+     * A no-op returning `{}` on a store without a queue.
+     */
+    plan(args: {
+        threadId: string;
+        /** The run that is settling; `null` when the thread is idle (a kick). */
+        runId: string | null;
+        outcome: QueueSettleOutcome;
+        error?: string;
+    }): Promise<QueuePlan>;
+    /**
+     * {@link plan}, then start what it picked with `start`. What an in-process settle (the inline
+     * runner, a durable cancel issued outside a workflow) calls; answers the frame to write.
+     */
+    handoff(args: {
+        threadId: string;
+        runId: string;
+        outcome: QueueSettleOutcome;
+        error?: string;
+    }, start: QueuedTurnStarter): Promise<AgentStreamEvent | undefined>;
+    /**
+     * Start the head of an IDLE thread's queue — after a send queued behind a run that turned out to
+     * be gone, after a resume, after a stale holder. Does nothing while a live run holds the thread
+     * (its settle drains) or while the queue is paused. Answers the started run's id, if any.
+     */
+    kick(threadId: string, runner: AgentRunner): Promise<string | undefined>;
+    /**
+     * Start a turn the thread is already claimed for. On failure the message goes back to the head of
+     * the queue, the queue pauses (`start_failed`), and the claim is released — nothing is lost and
+     * nothing is left holding the thread.
+     */
+    launch(threadId: string, next: QueuedTurn, start: QueuedTurnStarter): Promise<boolean>;
+    /** Put a turn that never started back at the head of its queue, paused, and free the thread. */
+    restore(threadId: string, next: QueuedTurn, reason: QueuePauseReason, message: string): Promise<void>;
+    /** A `queue` frame with the thread's current state. */
+    pausedFrame(threadId: string): Promise<AgentStreamEvent>;
+    /**
+     * Tell whoever is watching the thread that its queue changed: a `queue` frame into the stream of
+     * the run holding it. Best-effort — a thread nobody is streaming has no one to tell, and the next
+     * read of the thread carries the queue anyway.
+     */
+    publish(threadId: string): Promise<ChatQueueState>;
+    private write;
+    /** Why `actor` may not start a turn now (the quota message), or `null`. */
+    quotaBlock(actor: Actor): Promise<string | null>;
+    /**
+     * The turn a queued message starts: everything it was queued with, today's date, and its
+     * attachments' urls minted afresh — the ones stored at enqueue time may have expired while it
+     * waited. An attachment the staging store no longer resolves keeps its stored url.
+     */
+    private inputFor;
+    private freshAttachments;
+}
+
+export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QueueSettleOutcome as i, type QueuedTurn as j, type QueuedTurnStarter as k, type QuotaLimits as l, type QuotaWindowLimits as m, delegateToolName as n, provideAgentTools as o, provideAgentTool as p, utcDay as u };