@adonis-agora/agent 0.48.0 → 0.50.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @adonis-agora/agent
 
+## 0.50.0
+
+### Minor Changes
+
+- [#224](https://github.com/DavideCarvalho/adonis-agora-agent/pull/224) [`3ed6b2d`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/3ed6b2dbcdceef26ea7c262edec5cacffb5d6c05) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Message queue — sending while a turn is still running, ported from `@dudousxd/nestjs-agent` (its `docs/stream-protocol.md`, *Message queue*), so `chat.queue` in `@dudousxd/nestjs-agent-react` works against an Adonis server.
+  
+  - **A send on a busy thread is queued, not run concurrently (BREAKING behaviour).** `POST <path>/chat` on a thread whose turn is still running now answers `202 { queued: true, threadId, messageId, position, queue, runId?, interrupting? }` (JSON, no stream) and the message — stored server-side, per thread, FIFO — starts when that turn settles, under its own `messageId` as run id. `mode: 'auto' | 'queue' | 'interrupt'` (`interrupt: true` is the shorthand): `'queue'` always answers `202`, `'interrupt'` queues at the head and cancels the running turn. `regenerate` on a busy thread is `409 run_active`. Before, such a send started a second, concurrent turn on the same thread.
+  - **Drain policy.** Completed → the head starts; failed → the queue pauses (`run_failed`); Stop → pauses (`cancelled`); an interrupt's cancel → its message starts; the head's actor over quota → pauses (`quota_exceeded`). The decision is the settling stream's last event before its terminal: `{ kind: 'queue', queue, started?: { messageId, runId } }`. Every queue change while a turn holds the thread is a `queue` event too.
+  - **Routes.** `GET` / `DELETE <path>/threads/:id/queue`, `POST <path>/threads/:id/queue/resume`, `PATCH` / `DELETE <path>/queue/:messageId` (owner-scoped; `404` unknown, `403` another actor's, `410` already started or removed, `501` on a store without a queue). `GET <path>/threads/:id` carries `queue`.
+  - **One turn per thread.** Admission is a compare-and-set on the thread's active run. New SPI `ChatQueueStore` (`enqueueMessage`, `listQueue`, …, `claimActiveStream`, `releaseActiveStream`, probed by `isChatQueueStore`), implemented by the Lucid store (new table `agent_queued_message`, new column `agent_thread.queue_pause` — both from `createAgentTables`; with `autoCreateTables: false`, add a migration that calls it again) and the in-memory store. `CHAT_QUEUE_STORE_CONTRACT` (`./testing`) checks a store of your own. A store without it keeps the old behaviour.
+  - **`AgentService.send()`** queues; **`AgentService.chat()` stays start-or-refuse** and now throws `ChatQueueError` (`409 run_active`) on a busy thread. `ChatQueueService` (drain/kick/launch/publish) is exported; `getQueue`, `updateQueuedMessage`, `removeQueuedMessage`, `clearQueue`, `resumeQueue` on the service.
+  - **Runners.** `AgentRunner.start(input, { runId? })` and optional `isRunActive(runId)`. Inline: drains before the stream ends; a cancelled loop now actually stops at its next safe point (new `AgentLoopHooks.cancelled`, `RunCancelledError`) instead of running on in the background, and a parked wait is unwound. Durable: the handoff is journaled (`queue:completed` / `queue:failed` behind `ctx.patched('agent:chat-queue')`, then `ctx.startChild` under the message id — a run in flight at upgrade replays the history it has); `cancel` now frees the thread, hands it to the queue and ends the stream with a `cancelled` frame; a thread turn stopped from outside no longer writes its late answer.
+  - **Client.** `@adonis-agora/agent/client` `send` returns `{ queued }` for a `202` (`AgentChatQueued`), takes `mode`; `./react`'s hook follows a queued send that started at once.
+
+## 0.49.0
+
+### Minor Changes
+
+- [#222](https://github.com/DavideCarvalho/adonis-agora-agent/pull/222) [`241bfdc`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/241bfdc298373052435890daa4513597e046377d) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - The chat contract `@dudousxd/nestjs-agent` settled (its `docs/stream-protocol.md`), ported:
+  
+  - **Refusals answer `{ message, code? }` (BREAKING for readers of `error`).** Every refused request on the agent routes (and the dashboard's asset route) answers its status with `{ message, code? }` instead of `{ error }` — `code` where there is a machine-readable reason (`unauthorized`, `model_not_allowed`, `thread_required`, `quota_exceeded`). `@adonis-agora/agent/client` now throws a refused send as `AgentChatHttpError` (`status`, `code`, `body`, and the server's `message` as its own message) instead of a bare `Error('Failed to start agent chat (HTTP n).')`.
+  - **A send's `model` is that turn's only** — never stored on the thread; `PATCH threads/:id { model }` is the only pin (documented and tested; the service already behaved this way).
+  - **Regenerate.** `POST chat { threadId, regenerate: true }` answers the thread's last user message again: `400 thread_required` without a thread, `message` ignored, no user message stored, the answer(s) after it dropped (a new `regenerate:truncate` durable step — normal turns journal exactly what they did), a new run. `AgentRunInput.regenerate` replaces the unused `isRegenerate`; `RegenerateNeedsThreadError` is exported.
+  - **Model lock.** `ModelCatalogView.locked: { model, reason? }` runs every turn of that agent on `locked.model` and refuses a send naming another (`400 model_not_allowed`); `GET agents` entries carry `lockedModel` (`AgentCatalogEntry`). `listAgents(actor)` is now async.
+  - **Quota soft limit and USD-only windows.** `QuotaWindow.usedTokens` is optional; `QuotaWindow.warnAt`, `QuotaReport.warning: { period, ratio, reason? }` (never while blocked), `quotaWarning(windows)`, `quotaUsedRatio(window)`; `quota: { limits, warnAt }` stamps it on the ledger windows (`LedgerQuotaProvider`'s new `options.warnAt`). `exhaustedWindow` reads a missing `usedTokens` as `0`.
+  - **Who answered a question.** `POST tool-call/answer|skip` take `via?` (1–64 characters, `'web'` by default; `400` otherwise); the settled outcome carries `answeredBy` / `answeredVia` (`ElicitationReply.answeredVia`, `ElicitationOutcome.answeredBy|answeredVia`), streamed as the call's `tool-output` and persisted with its result.
+  - **`GET tools?agent=*`** (`ALL_AGENTS`) answers the union across every agent, each tool once, under the same gates; an unknown name is still `404`.
+  - **Frame ids.** `SseEvent.id` (the client parser now keeps the `id:` line). Ids stay strictly increasing within a run; readers must tolerate gaps.
+
 ## 0.48.0
 
 ### Minor Changes

package/dist/providers/agent_provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent_provider.d.ts","sourceRoot":"","sources":["../../providers/agent_provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAkJ/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;;IAMpB,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAA7C,YAAsB,GAAG,EAAE,kBAAkB,EAAI;IAEjD,QAAQ,SAcP;IAEK,IAAI,kBAiJT;IAEK,QAAQ,kBASb;CA6mCF"}
+{"version":3,"file":"agent_provider.d.ts","sourceRoot":"","sources":["../../providers/agent_provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAiL/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;;IAMpB,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAA7C,YAAsB,GAAG,EAAE,kBAAkB,EAAI;IAEjD,QAAQ,SAcP;IAEK,IAAI,kBA+JT;IAEK,QAAQ,kBASb;CAmyCF"}

package/dist/providers/agent_provider.js

@@ -1,7 +1,16 @@
 import { pathToFileURL } from 'node:url';
-import { AgentDepsFactory, AgentGenui, AgentRegistry, AgentService, AgentSseEncoder, AnonymousActorResolver, AttachmentRefusedError, DefaultToolAuthorizer, discoverTools, evaluateGovernanceGate, evaluateOwnership, governanceQueries as governanceQueriesFactories, HumanReplyMismatchError, InlineAgentRunner, InProcessTokenStreamSink, isQuotaProvider, LedgerQuotaProvider, lucidStoreConnection, ModelNotAllowedError, memoryForgetVerdict, offerMemories, parseStreamCursor, pricingStores, QuotaBlockedError, REQUESTER_APPROVER, registerDelegateTools, registerFunctionalTool, registerToolsFromBarrel, resolveActorResolver, ToolRegistry, toApprovalPolicy, toModelCatalog, withActorLabel, withActorLabels, } from '../src/index.js';
+import { AgentDepsFactory, AgentGenui, AgentRegistry, AgentService, AgentSseEncoder, ALL_AGENTS, AnonymousActorResolver, AttachmentRefusedError, ChatQueueError, ChatQueueService, DefaultToolAuthorizer, discoverTools, evaluateGovernanceGate, evaluateOwnership, governanceQueries as governanceQueriesFactories, HumanReplyMismatchError, InlineAgentRunner, InProcessTokenStreamSink, isQuotaProvider, LedgerQuotaProvider, lucidStoreConnection, ModelNotAllowedError, memoryForgetVerdict, offerMemories, parseStreamCursor, pricingStores, QuotaBlockedError, REQUESTER_APPROVER, RegenerateNeedsThreadError, registerDelegateTools, registerFunctionalTool, registerToolsFromBarrel, resolveActorResolver, ToolRegistry, toApprovalPolicy, toModelCatalog, withActorLabel, withActorLabels, } from '../src/index.js';
 import { McpToolImporter } from '../src/mcp-client/index.js';
 import { setTelescopeGovernanceQueries } from '../src/telescope/governance-registry.js';
+/** A send's `mode`, or `null` when it names none of the three. `interrupt: true` is `'interrupt'`. */
+function sendMode(body) {
+    if (body.mode === undefined) {
+        return body.interrupt === true ? 'interrupt' : 'auto';
+    }
+    return body.mode === 'auto' || body.mode === 'queue' || body.mode === 'interrupt'
+        ? body.mode
+        : null;
+}
 /** The catalog a model provider carries (`aiSdkModels(…).catalog`), if it carries one. */
 function catalogOf(model) {
     const catalog = model?.catalog;
@@ -174,7 +183,7 @@ export default class AgentProvider {
             ? undefined
             : isQuotaProvider(config.quota)
                 ? config.quota
-                : new LedgerQuotaProvider(store, undefined, config.quota.limits);
+                : new LedgerQuotaProvider(store, undefined, config.quota.limits, config.quota.warnAt !== undefined ? { warnAt: config.quota.warnAt } : {});
         const pricingStore = await this.#resolvePricing(config);
         // Governance read-model is resolved after pricing so the Lucid read-model prices its rollups
         // against the same live prices the loop's cost fold uses.
@@ -227,11 +236,20 @@ export default class AgentProvider {
         });
         // `durable: true` runs each turn as a replay-safe `@adonis-agora/durable` workflow; it degrades
         // gracefully to the in-process runner when the durable peer isn't installed/configured.
+        // The thread message queue: a send on a thread whose turn is still running waits here and
+        // starts when that turn settles. One instance, shared by the service (which queues) and the
+        // runner (which drains); inert on a store that is not a `ChatQueueStore`.
+        const queue = new ChatQueueService(store, sink, {
+            ...(quotaProvider !== undefined ? { quota: quotaProvider } : {}),
+            ...(attachmentStaging !== undefined ? { attachments: attachmentStaging } : {}),
+            personaFor: (agentName) => service.resolvePersona(agentName),
+        });
         const runner = config.durable === true
-            ? ((await this.#resolveDurableRunner(factory, store)) ??
-                new InlineAgentRunner(factory, store))
-            : new InlineAgentRunner(factory, store);
+            ? ((await this.#resolveDurableRunner(factory, store, queue, sink)) ??
+                new InlineAgentRunner(factory, store, queue))
+            : new InlineAgentRunner(factory, store, queue);
         const service = new AgentService(runner, store, factory, {
+            queue,
             // No `models` → the catalog the model provider carries (`aiSdkModels`), else none.
             ...(config.models !== undefined
                 ? { models: toModelCatalog(config.models) }
@@ -379,14 +397,14 @@ export default class AgentProvider {
      * unresolvable engine, or any wiring error logs a warning and degrades to the in-process runner
      * rather than breaking boot.
      */
-    async #resolveDurableRunner(factory, store) {
+    async #resolveDurableRunner(factory, store, queue, sink) {
         try {
             const durable = await import('@adonis-agora/durable');
             const engine = await this.app.container.make(durable.WorkflowEngine);
             const { DurableAgentRunner, registerAgentWorkflow, setDurableAgentContext } = await import('../src/durable/index.js');
-            setDurableAgentContext({ factory, store });
+            setDurableAgentContext({ factory, store, queue });
             registerAgentWorkflow(engine);
-            return new DurableAgentRunner(engine, store);
+            return new DurableAgentRunner(engine, store, queue, sink);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -441,15 +459,29 @@ export default class AgentProvider {
                 if (!(await this.#assertOwner(ctx, actor, owner, 'thread', governanceAuthorize)))
                     return;
             }
+            const regenerate = body.regenerate === true;
+            if (regenerate && body.threadId === undefined) {
+                return ctx.response.badRequest({
+                    message: 'regenerate requires an existing threadId',
+                    code: 'thread_required',
+                });
+            }
             const refs = attachmentRefs(body.attachments);
             if (typeof refs === 'string') {
-                return ctx.response.badRequest({ error: refs });
+                return ctx.response.badRequest({ message: refs });
+            }
+            const mode = sendMode(body);
+            if (mode === null) {
+                return ctx.response.badRequest({ message: "mode must be 'auto', 'queue' or 'interrupt'" });
             }
             let started;
             try {
-                started = await service.chat({
+                started = await service.send({
                     actor,
-                    message: body.message,
+                    mode,
+                    // A regenerate answers the stored user message; whatever `message` says is ignored.
+                    message: regenerate ? '' : body.message,
+                    ...(regenerate ? { regenerate: true } : {}),
                     ...(typeof body.model === 'string' && body.model.length > 0 ? { model: body.model } : {}),
                     ...(body.threadId !== undefined ? { threadId: body.threadId } : {}),
                     ...(body.agent !== undefined ? { agentName: body.agent } : {}),
@@ -460,10 +492,16 @@ export default class AgentProvider {
             }
             catch (error) {
                 if (error instanceof AttachmentRefusedError) {
-                    return ctx.response.status(error.status).json({ error: error.message });
+                    return ctx.response.status(error.status).json({ message: error.message });
                 }
                 if (error instanceof ModelNotAllowedError) {
-                    return ctx.response.badRequest({ error: error.message });
+                    return ctx.response.badRequest({ message: error.message, code: 'model_not_allowed' });
+                }
+                if (error instanceof RegenerateNeedsThreadError) {
+                    return ctx.response.badRequest({ message: error.message, code: 'thread_required' });
+                }
+                if (error instanceof ChatQueueError) {
+                    return this.#refuseQueue(ctx, error);
                 }
                 if (error instanceof QuotaBlockedError) {
                     return ctx.response.status(429).json({
@@ -474,6 +512,11 @@ export default class AgentProvider {
                 }
                 throw error;
             }
+            if (started.queued === true) {
+                // The thread already has a turn running: the message waits in its queue (`202`, JSON — no
+                // stream). `runId` is there when it started straight away; attach to it with `GET …/stream`.
+                return ctx.response.status(202).json(started);
+            }
             await this.#pipe(ctx, service, started.runId, started.threadId);
         });
         // 2. GET /agent/chat/:runId/stream — re-attach SSE. Authenticated: the actor resolver reads the
@@ -490,7 +533,7 @@ export default class AgentProvider {
             // Nothing buffered under the run — it ended while the client was away, or its buffer went with
             // a restarted process. A 404 reads as "nothing to resume"; subscribing would wait forever.
             if (!(await service.hasStream(runId))) {
-                return ctx.response.notFound({ error: 'Nothing is streaming under that run.' });
+                return ctx.response.notFound({ message: 'Nothing is streaming under that run.' });
             }
             // `?after=<seq>` (or the `Last-Event-ID` a browser EventSource sends on its own) skips the
             // events a reconnecting client already has; `after` wins when both are present.
@@ -524,7 +567,7 @@ export default class AgentProvider {
             const via = decisionVia(body.via);
             if (remember === null || via === null) {
                 return ctx.response.badRequest({
-                    error: `remember must be a boolean and via a string of 1-${MAX_VIA_LENGTH} characters`,
+                    message: `remember must be a boolean and via a string of 1-${MAX_VIA_LENGTH} characters`,
                 });
             }
             const runId = await this.#runOfToolCall(ctx, service, body);
@@ -544,7 +587,7 @@ export default class AgentProvider {
             const via = decisionVia(body.via);
             if (via === null) {
                 return ctx.response.badRequest({
-                    error: `via must be a string of 1-${MAX_VIA_LENGTH} characters`,
+                    message: `via must be a string of 1-${MAX_VIA_LENGTH} characters`,
                 });
             }
             const runId = await this.#runOfToolCall(ctx, service, body);
@@ -563,6 +606,12 @@ export default class AgentProvider {
             if (actor === null)
                 return;
             const body = (ctx.request.body() ?? {});
+            const via = decisionVia(body.via);
+            if (via === null) {
+                return ctx.response.badRequest({
+                    message: `via must be a string of 1-${MAX_VIA_LENGTH} characters`,
+                });
+            }
             const runId = await this.#runOfToolCall(ctx, service, body);
             if (runId === null)
                 return;
@@ -573,7 +622,7 @@ export default class AgentProvider {
             // the person who typed it hears why — rather than signalled and quietly dropped by the loop.
             const problem = await service.answerProblem(body.toolCallId, body.answers ?? {});
             if (problem !== null) {
-                return ctx.response.badRequest({ error: problem });
+                return ctx.response.badRequest({ message: problem });
             }
             try {
                 await service.answer({
@@ -581,6 +630,7 @@ export default class AgentProvider {
                     toolCallId: body.toolCallId,
                     answers: body.answers ?? {},
                     answeredByRef: actor.id,
+                    answeredVia: via,
                 });
             }
             catch (error) {
@@ -595,6 +645,12 @@ export default class AgentProvider {
             if (actor === null)
                 return;
             const body = (ctx.request.body() ?? {});
+            const via = decisionVia(body.via);
+            if (via === null) {
+                return ctx.response.badRequest({
+                    message: `via must be a string of 1-${MAX_VIA_LENGTH} characters`,
+                });
+            }
             const runId = await this.#runOfToolCall(ctx, service, body);
             if (runId === null)
                 return;
@@ -606,6 +662,7 @@ export default class AgentProvider {
                     runId,
                     toolCallId: body.toolCallId,
                     answeredByRef: actor.id,
+                    answeredVia: via,
                 });
             }
             catch (error) {
@@ -630,11 +687,11 @@ export default class AgentProvider {
             const threadId = await service.threadOfMessage(messageId);
             if (threadId === undefined) {
                 return ctx.response.status(501).json({
-                    error: 'Message feedback requires an AgentStore that implements threadOfMessage() and setMessageFeedback().',
+                    message: 'Message feedback requires an AgentStore that implements threadOfMessage() and setMessageFeedback().',
                 });
             }
             if (threadId === null) {
-                return ctx.response.notFound({ error: 'message not found' });
+                return ctx.response.notFound({ message: 'message not found' });
             }
             const owner = await service.threadOwner(threadId);
             if (!(await this.#assertOwner(ctx, actor, owner, 'thread', undefined)))
@@ -645,7 +702,7 @@ export default class AgentProvider {
                 ...(body.comment !== undefined ? { comment: body.comment } : {}),
             });
             if (!result.ok) {
-                return ctx.response.status(result.status).json({ error: result.error });
+                return ctx.response.status(result.status).json({ message: result.error });
             }
             return ctx.response.json({ feedback: result.feedback });
         });
@@ -663,16 +720,23 @@ export default class AgentProvider {
             const actor = await this.#resolveActor(ctx, actorResolver);
             if (actor === null)
                 return;
-            return ctx.response.json(service.listAgents());
+            return ctx.response.json(await service.listAgents(actor));
         });
         // 6b. GET /agent/tools?agent= — the tools this caller can reach through an agent, with how a chat
         // surface should talk about each (`presentation`). The same list the model is offered; nothing the
         // caller passes widens it — `agent` only narrows to that agent's allow-list, and an unknown name is
-        // a 404 rather than the widest answer (no allow-list at all).
+        // a 404 rather than the widest answer (no allow-list at all). `?agent=*` is the union across every
+        // agent: each tool this caller reaches through any of them, once, under the same gates.
         router.get(p('tools'), async (ctx) => {
             const agent = ctx.request.qs().agent;
+            if (agent === ALL_AGENTS) {
+                const actor = await this.#resolveActor(ctx, actorResolver);
+                if (actor === null)
+                    return;
+                return ctx.response.json(await service.toolCatalogForAllAgents(actor));
+            }
             if (agent !== undefined && agent !== defaultAgentName && agents.get(agent) === undefined) {
-                return ctx.response.notFound({ error: `No agent named "${agent}"` });
+                return ctx.response.notFound({ message: `No agent named "${agent}"` });
             }
             const actor = await this.#resolveActor(ctx, resolveActorResolver(actorResolver, agents.get(agent ?? defaultAgentName)));
             if (actor === null)
@@ -712,20 +776,20 @@ export default class AgentProvider {
                 return;
             const body = (ctx.request.body() ?? {});
             if (body.model !== undefined && body.model !== null && typeof body.model !== 'string') {
-                return ctx.response.badRequest({ error: 'model must be a string or null' });
+                return ctx.response.badRequest({ message: 'model must be a string or null' });
             }
             if (body.model !== undefined) {
                 try {
                     const pinned = await service.setThreadModel(actor, threadId, body.model);
                     if (!pinned) {
                         return ctx.response.status(501).json({
-                            error: "Pinning a thread's model requires an AgentStore that implements updateThread().",
+                            message: "Pinning a thread's model requires an AgentStore that implements updateThread().",
                         });
                     }
                 }
                 catch (error) {
                     if (error instanceof ModelNotAllowedError) {
-                        return ctx.response.badRequest({ error: error.message });
+                        return ctx.response.badRequest({ message: error.message });
                     }
                     throw error;
                 }
@@ -733,12 +797,68 @@ export default class AgentProvider {
             if (body.title !== undefined) {
                 const title = typeof body.title === 'string' ? body.title.trim() : '';
                 if (title.length === 0 || title.length > 200) {
-                    return ctx.response.badRequest({ error: 'title must be a string of 1-200 characters' });
+                    return ctx.response.badRequest({ message: 'title must be a string of 1-200 characters' });
                 }
                 await service.renameThread(threadId, title);
             }
             return ctx.response.json({ ok: true });
         });
+        // 8d. The thread message queue — messages sent while a turn was running, waiting to run after
+        // it. Owner-scoped like the thread routes; each answers the queue (`{ items, paused }`) and
+        // publishes it into the stream of the run holding the thread. `501` on a store without a queue.
+        router.get(p('threads/:id/queue'), async (ctx) => {
+            const threadId = await this.#ownedThread(ctx, service, actorResolver, governanceAuthorize);
+            if (threadId === null)
+                return;
+            return this.#queueAnswer(ctx, () => service.getQueue(threadId));
+        });
+        router.delete(p('threads/:id/queue'), async (ctx) => {
+            const threadId = await this.#ownedThread(ctx, service, actorResolver, governanceAuthorize);
+            if (threadId === null)
+                return;
+            return this.#queueAnswer(ctx, () => service.clearQueue(threadId));
+        });
+        router.post(p('threads/:id/queue/resume'), async (ctx) => {
+            const threadId = await this.#ownedThread(ctx, service, actorResolver, governanceAuthorize);
+            if (threadId === null)
+                return;
+            return this.#queueAnswer(ctx, () => service.resumeQueue(threadId));
+        });
+        router.patch(p('queue/:messageId'), async (ctx) => {
+            const actor = await this.#resolveActor(ctx, actorResolver);
+            if (actor === null)
+                return;
+            const messageId = String(ctx.params.messageId);
+            if (!(await this.#ownsQueuedMessage(ctx, service, actor, messageId, governanceAuthorize)))
+                return;
+            const body = (ctx.request.body() ?? {});
+            if (body.message !== undefined && typeof body.message !== 'string') {
+                return ctx.response.badRequest({ message: 'message must be a string' });
+            }
+            if (body.position !== undefined && typeof body.position !== 'number') {
+                return ctx.response.badRequest({ message: 'position must be a non-negative integer' });
+            }
+            const refs = body.attachments === undefined || body.attachments === null
+                ? body.attachments
+                : attachmentRefs(body.attachments);
+            if (typeof refs === 'string') {
+                return ctx.response.badRequest({ message: refs });
+            }
+            return this.#queueAnswer(ctx, () => service.updateQueuedMessage(actor, messageId, {
+                ...(typeof body.message === 'string' ? { message: body.message } : {}),
+                ...(refs !== undefined ? { attachments: refs } : {}),
+                ...(typeof body.position === 'number' ? { position: body.position } : {}),
+            }));
+        });
+        router.delete(p('queue/:messageId'), async (ctx) => {
+            const actor = await this.#resolveActor(ctx, actorResolver);
+            if (actor === null)
+                return;
+            const messageId = String(ctx.params.messageId);
+            if (!(await this.#ownsQueuedMessage(ctx, service, actor, messageId, governanceAuthorize)))
+                return;
+            return this.#queueAnswer(ctx, () => service.removeQueuedMessage(messageId));
+        });
         // 9. DELETE /agent/threads/:id. Authenticated + owner-scoped.
         router.delete(p('threads/:id'), async (ctx) => {
             const actor = await this.#resolveActor(ctx, actorResolver);
@@ -798,16 +918,16 @@ export default class AgentProvider {
             if (actor === null)
                 return;
             if (memory === undefined) {
-                return ctx.response.notFound({ error: 'No memory is configured in this deployment.' });
+                return ctx.response.notFound({ message: 'No memory is configured in this deployment.' });
             }
             const id = String(ctx.params.id);
             const entry = (await everyMemoryOf(actor)).entries.find((candidate) => candidate.id === id);
             if (entry === undefined) {
-                return ctx.response.notFound({ error: `No memory with id "${id}".` });
+                return ctx.response.notFound({ message: `No memory with id "${id}".` });
             }
             const verdict = memoryForgetVerdict({ record: entry, actor });
             if (!verdict.allowed) {
-                return ctx.response.forbidden({ error: verdict.reason });
+                return ctx.response.forbidden({ message: verdict.reason });
             }
             return ctx.response.json({
                 forgotten: await memory.provider.forget({ id: entry.id, ctx: { actor, threadId: '' } }),
@@ -856,19 +976,19 @@ export default class AgentProvider {
                     return;
                 const file = ctx.request.file('file');
                 if (file === null || file.tmpPath === undefined) {
-                    return ctx.response.status(400).json({ error: 'multipart field "file" is required' });
+                    return ctx.response.status(400).json({ message: 'multipart field "file" is required' });
                 }
                 const contentType = file.headers?.['content-type']?.split(';')[0]?.trim() ?? `${file.type}/${file.subtype}`;
                 if (!allowedContentTypes.includes(contentType)) {
                     return ctx.response.status(415).json({
-                        error: `content type "${contentType}" is not allowed (allowed: ${allowedContentTypes.join(', ')})`,
+                        message: `content type "${contentType}" is not allowed (allowed: ${allowedContentTypes.join(', ')})`,
                     });
                 }
                 const sizeBytes = file.size;
                 if (sizeBytes > maxBytes) {
                     return ctx.response
                         .status(413)
-                        .json({ error: `file exceeds the ${maxBytes}-byte limit` });
+                        .json({ message: `file exceeds the ${maxBytes}-byte limit` });
                 }
                 const { readFile } = await import('node:fs/promises');
                 const data = await readFile(file.tmpPath);
@@ -985,7 +1105,7 @@ export default class AgentProvider {
                 if (gov.threadDetail === undefined) {
                     return ctx.response
                         .status(501)
-                        .json({ error: 'this governance adapter does not support thread detail' });
+                        .json({ message: 'this governance adapter does not support thread detail' });
                 }
                 const detail = await withActorLabel(await gov.threadDetail(String(ctx.params.id)), actorDirectory);
                 if (detail === null)
@@ -1101,7 +1221,7 @@ export default class AgentProvider {
                         typeof body.inputPricePer1m !== 'number' ||
                         typeof body.outputPricePer1m !== 'number') {
                         return ctx.response.status(400).json({
-                            error: 'body must be {modelId: string, inputPricePer1m: number, outputPricePer1m: number, cacheWritePricePer1m?: number, cacheReadPricePer1m?: number}',
+                            message: 'body must be {modelId: string, inputPricePer1m: number, outputPricePer1m: number, cacheWritePricePer1m?: number, cacheReadPricePer1m?: number}',
                         });
                     }
                     await pricing.upsertModelPrice({
@@ -1130,7 +1250,7 @@ export default class AgentProvider {
         try {
             const actor = await actorResolver.resolve(ctx);
             if (actor === null || actor === undefined) {
-                ctx.response.status(401).json({ error: 'unauthorized' });
+                ctx.response.status(401).json({ message: 'unauthorized', code: 'unauthorized' });
                 return null;
             }
             return actor;
@@ -1140,9 +1260,10 @@ export default class AgentProvider {
             // in production, every request here is untrusted by definition, so the detail stays server-side
             // (dev/test keeps it, matching `evaluateDashboardGate`/`evaluateGovernanceGate`'s `debug` knob).
             const debug = !this.app.inProduction;
-            ctx.response
-                .status(401)
-                .json({ error: debug && error instanceof Error ? error.message : 'unauthorized' });
+            ctx.response.status(401).json({
+                message: debug && error instanceof Error ? error.message : 'unauthorized',
+                code: 'unauthorized',
+            });
             return null;
         }
     }
@@ -1158,7 +1279,7 @@ export default class AgentProvider {
             return null;
         const verdict = await evaluateGovernanceGate(actor, ctx, governanceAuthorize, !this.app.inProduction);
         if (!verdict.ok) {
-            ctx.response.status(verdict.status).json({ error: verdict.error });
+            ctx.response.status(verdict.status).json({ message: verdict.error });
             return null;
         }
         return actor;
@@ -1180,7 +1301,7 @@ export default class AgentProvider {
         const verdict = evaluateOwnership(actor.id, ownerRef, privileged);
         if (!verdict.ok) {
             const error = verdict.status === 404 ? `${kind} not found` : 'forbidden';
-            ctx.response.status(verdict.status).json({ error });
+            ctx.response.status(verdict.status).json({ message: error });
             return false;
         }
         return true;
@@ -1201,7 +1322,7 @@ export default class AgentProvider {
             return body.runId;
         const runId = typeof body.toolCallId === 'string' ? await service.toolCallRun(body.toolCallId) : null;
         if (runId === null) {
-            ctx.response.notFound({ error: 'Unknown tool call.' });
+            ctx.response.notFound({ message: 'Unknown tool call.' });
             return null;
         }
         return runId;
@@ -1225,11 +1346,11 @@ export default class AgentProvider {
         }
         else {
             if (owner === null) {
-                ctx.response.notFound({ error: 'Unknown run.' });
+                ctx.response.notFound({ message: 'Unknown run.' });
                 return false;
             }
             if (!(await service.mayDecide(actor, { toolCallId, approver, requesterRef: owner }))) {
-                ctx.response.forbidden({ error: `This approval is for ${approver}.` });
+                ctx.response.forbidden({ message: `This approval is for ${approver}.` });
                 return false;
             }
         }
@@ -1239,16 +1360,74 @@ export default class AgentProvider {
                     approval.expiresAt !== null &&
                     Date.parse(approval.expiresAt) <= Date.now()));
         if (lapsed) {
-            ctx.response.gone({ error: `The approval request for tool call ${toolCallId} has expired.` });
+            ctx.response.gone({
+                message: `The approval request for tool call ${toolCallId} has expired.`,
+            });
             return false;
         }
         return true;
     }
+    /** A refused queue request: the error's own status, as `{ message, code? }`. */
+    #refuseQueue(ctx, error) {
+        ctx.response
+            .status(error.status)
+            .json({ message: error.message, ...(error.code !== undefined ? { code: error.code } : {}) });
+    }
+    /** Answer a queue route: the service's result, or the refusal it threw. */
+    async #queueAnswer(ctx, work) {
+        try {
+            ctx.response.json(await work());
+        }
+        catch (error) {
+            if (error instanceof ChatQueueError) {
+                return this.#refuseQueue(ctx, error);
+            }
+            if (error instanceof AttachmentRefusedError) {
+                ctx.response.status(error.status).json({ message: error.message });
+                return;
+            }
+            throw error;
+        }
+    }
+    /** The `:id` thread once the caller is shown to own it; `null` after replying 401/403/404. */
+    async #ownedThread(ctx, service, actorResolver, governanceAuthorize) {
+        const actor = await this.#resolveActor(ctx, actorResolver);
+        if (actor === null)
+            return null;
+        const threadId = String(ctx.params.id);
+        const owner = await service.threadOwner(threadId);
+        return (await this.#assertOwner(ctx, actor, owner, 'thread', governanceAuthorize))
+            ? threadId
+            : null;
+    }
+    /**
+     * Does `actor` own the thread a queued message waits on? Replies `404` for a message that does
+     * not exist (or a store without a queue answers `501`), `403` for another actor's.
+     */
+    async #ownsQueuedMessage(ctx, service, actor, messageId, governanceAuthorize) {
+        let threadId;
+        try {
+            threadId = await service.queuedMessageThread(messageId);
+        }
+        catch (error) {
+            if (error instanceof ChatQueueError) {
+                this.#refuseQueue(ctx, error);
+                return false;
+            }
+            throw error;
+        }
+        if (threadId === null) {
+            ctx.response.notFound({ message: `queued message ${messageId} not found` });
+            return false;
+        }
+        const owner = await service.threadOwner(threadId);
+        return this.#assertOwner(ctx, actor, owner, 'thread', governanceAuthorize);
+    }
     #conflictOnMismatch(ctx, error) {
         if (!(error instanceof HumanReplyMismatchError)) {
             throw error;
         }
-        ctx.response.conflict({ error: error.message });
+        ctx.response.conflict({ message: error.message });
     }
     /**
      * Pipe the run's live token stream to the client as SSE: `event: meta` (runId/threadId), the run's