@adonis-agora/agent 0.61.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # @adonis-agora/agent
 
+## 0.63.0
+
+### Minor Changes
+
+- [#314](https://github.com/DavideCarvalho/adonis-agora-agent/pull/314) [`ab09bbd`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/ab09bbdc9093fc07442b69a46d0560e582e2c89b) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Fixes to generative UI, the React AG-UI client and `AuthActorResolver`:
+  
+  - **GenUI text:** a `fallbackText` that returns an empty string renders nothing: a bare `Stack`, or a `Card` without a title, sent a JSON block of its props (`{}`) to text channels. In a tree, a layout's children still render.
+  - **GenUI tools:** outside tree mode, layout components (`children: true`, like `Stack` and `Card`) get no `ui__show_*` tool, and the generic show tool (`showTool`) no longer offers them. They could only push an empty container. **Behavior change:** compose layouts with `mode: 'tree'`.
+  - **`Chart` text:** the fallback draws every series instead of only the first. A bar chart gets one bar per series at each point, all on one scale. A line chart gets a sparkline per series (first → last, min/max) and the points as a table.
+  - **React over AG-UI (`agUiBackend()` / `agUiChatStream`):**
+    - Files the composer uploaded are now sent with the turn, as media parts by `file` handle (`{ type: 'file', provider: 'agora', value: <mediaId> }`). Before, they were dropped.
+    - Regenerate now sends `forwardedProps.regenerate`, so the answer is regenerated. Before, the question was posted again as a new turn.
+    - Question sets (`agora.elicitation`) render as the normal question block.
+    - Per-step usage, cost and model (`agora.step-usage`) reach `step-finish`.
+    - A tool call keeps its kind (`read`/`action`).
+    - An interrupt the stream already carried as an approval or a question set no longer also renders as `AgUiInterrupt`.
+    - After an approval or a question set the chat shows, the rest of the run streams into the same message. The AG-UI run ends on the interrupt, but the stream now ends without `done`, and the transport re-attaches to the parked run on `GET <path>/chat/:runId/stream?after=`. Before, a decision made through the native `tool-call` routes ran the rest of the run with nothing listening.
+    - The re-attach cursor is the run's own sequence number (from the producer's SSE `id:`). The re-framed frames no longer carry an `id:` that counts them, which matched nothing on the native route. A producer that writes no `id:` is not re-attached to.
+    - A text decision on a proposal (`agora.action-proposal-decision`) produces the same transient `data-proposal-decision` part as a native text decision.
+    - `ChatStreamRequest.files` describes the send's staged uploads, and `content(body, files)` receives them.
+  - **AG-UI producer (`agUiAdapter()`):**
+    - Accepts a `file` handle with `provider: 'agora'` that names an upload it staged. The upload is resolved for the caller, as the native `attachments` refs are (`403` when it is not theirs).
+    - Reads `forwardedProps.regenerate`.
+    - `TOOL_CALL_START` carries `metadata['agora.toolKind']`, `agora.elicitation` carries the call `id`, and `agora.step-usage` carries the step's `model`.
+    - Each event of the run carries an SSE `id:`: the run's own sequence number, as on the native stream, so `chat/:runId/stream?after=<id>` continues where the AG-UI run ended. `agUiSse(event, id?)` writes it, and `agUiEvents` keeps it in a new `cursor` option.
+  - **`AuthActorResolver`:** the agent routes run no auth middleware, so `ctx.auth.user` was never set and every request was refused with `401`. When no guard has tried the request yet, the resolver now calls `ctx.auth.check()` itself; with the new `guards` option it calls `checkUsing(guards)` instead. Neither throws for an anonymous request, and the resolver still answers `401` when there is no user. `resolve()` is now async.
+
+- [#313](https://github.com/DavideCarvalho/adonis-agora-agent/pull/313) [`6479996`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/6479996ab621edce7726275b5db9878c951b7d9f) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Text channels: `@adonis-agora/agent/channels`'s `channels.handle(adapter, { actor, thread, onThreadCreated?, pageContext?, store?, … })` is a webhook route handler that verifies the request (`401` otherwise), parses it, dedupes by the provider's message id, answers `200` at once and runs the turn in the background (`handler.drain()` awaits it). The turn is sent with text-only capabilities; text decisions are answered with their reply; the reply (prose and component `fallbackText`, in order) is converted to the channel's markdown (`toChannelMarkdown`: WhatsApp, Telegram MarkdownV2, none) and split at its length limit on paragraph/line/sentence boundaries (`splitMessage`). Media (images, voice notes, video, documents) is downloaded through the adapter within the attachment store's limits, staged with the new `AgentService.stageAttachment(actor, file)` and attached to the turn; what cannot be attached is answered with `texts.mediaRefused`. A question set (`ask`, intakes) is sent as text one question at a time with numbered options, and the next messages answer it (`parseChannelAnswer`; `skip` keeps the defaults; unanswered after `questionTimeoutMs` it is skipped). A proposal the turn left pending is sent with Confirm/Cancel buttons whose press decides it (`via` = the adapter's name), or with a text instruction in the configured `actionProposalText` vocabulary; an approved proposal's outcome is relayed after the turn (`outcomeTimeoutMs`), and `actionProposalWorker: { onSettled: channels.onSettled }` relays outcomes that settle later through the adapter registered under the turn's recorded `pageContext.channel` — each outcome once. In blocking mode the handler sends what it has and says the approval must happen in the app. Built-in adapters: `evolutionApi({ url, instance, apiKey, webhookToken })` (Evolution API v2 `messages.upsert`; `sendText`, opt-in `sendButtons` with a text fallback; media from inline base64, `mediaUrl` or `getBase64FromMediaMessage`), `whatsappCloud({ phoneNumberId, accessToken, appSecret, verifyToken })` (`X-Hub-Signature-256`, `hub.challenge`, interactive reply buttons, Graph media download) and `telegram({ botToken, secretToken })` (secret-token header, MarkdownV2 with a plain-text retry, inline keyboards, `answerCallbackQuery`, `getFile`); any `ChannelAdapter` works. The channel's state (`ChannelStore`: message ids, questions in progress, relayed outcomes) defaults to `lucidChannelStore()` — the new `agent_channel_state` table, created by `createAgentTables`, the published migration or on first use — when the agent store is Lucid, else memory; `redisChannelStore(redis)` and custom stores plug in. `AgentService` also gains `actionApprovalMode()`, `actionProposalVocabulary()`, `attachmentLimits()` and `lucidDatabase()`.
+
+## 0.62.0
+
+### Minor Changes
+
+- [#303](https://github.com/DavideCarvalho/adonis-agora-agent/pull/303) [`ee0a5c6`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/ee0a5c66f424f22deb4e1d904c64cb5e6701ae07) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Expose registered agents to personal agents (ChatGPT, Meta AI, a user's own assistant) over A2A 1.0 HTTP+JSON, following PACT (https://openpactprotocol.org). Register `@adonis-agora/agent/a2a_provider` and add `config/a2a.ts` (`defineA2aConfig`, from `@adonis-agora/agent/a2a`).
+  
+  - Per agent: an Agent Card, a synchronous `message:send`, and the task routes as PACT fixes them. Served as server middleware ahead of the router, so authentication happens before the body is read.
+  - `authKitPersonalAgents()` authenticates with `@adonis-agora/authkit-server` 0.76+ personal agents: the agent's signed JWT and, when the user delegated, the delegation token. A delegated turn runs as the user's account, with each delegated scope as a `scope:<id>` role.
+  - Conversations: `contextId` is bound to one agent and one (personal agent, user), and to the account once a delegated turn ran in it. A repeated `messageId` returns the stored reply. Conversation state lives in two tables created on first use (`store: 'lucid'`), or in memory.
+  - `action` calls that park for approval are approved when the delegation grants one of the tool's roles, and rejected otherwise (`actions: 'reject'` rejects all of them). Independent proposals (`actionApprovalMode: 'independent'`) are decided the same way once the run ends, and the turn waits for an approved one to execute before answering; the reply carries what it did as a data part (`{ action: { tool, status, summary, result } }`). Question sets are skipped.
+  - Step-up: a personal agent is offered the tools behind scopes it was not delegated but cannot run them. Calling one, or `request_permission`, makes the reply a `TASK_STATE_AUTH_REQUIRED` step-up with a consent link. `RolesPolicy` gains an optional `canOffer` (what the model is offered), separate from `can` (what runs).
+  - Replies under delegation carry a signed receipt listing the tools that ran under a delegated scope.
+  - `actor` maps the caller to the app's own actor (e.g. a profile instead of the account); turns carry `pageContext.channel = 'a2a'`.
+  - `service` plugs in an app's own runtime (an `A2aTurnService` adapter) instead of the agent provider's `AgentService`.
+  
+  **Security:** the agent provider now wraps the configured authorizer with `personalAgentGate`. An actor with the `personal_agent` role reaches only tools that declare one of its roles; tools with no `roles` are out of its reach. Its memory and skill scopes resolve to none, so it never reads or writes what the assistant remembers about the user. Nothing changes for any other actor.
+  - A `config/a2a.ts` that exports `undefined` (the surface flagged off) mounts nothing and logs nothing.
+
+- [#306](https://github.com/DavideCarvalho/adonis-agora-agent/pull/306) [`2796edd`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/2796edd4b9f998b84cbc12cea779c21cfbe22c77) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Proposal and presentation hooks, and AG-UI fidelity:
+  
+  - **Text decisions are English by default** (`yes`, `confirm`, `approve`, `ok`, `no`, `cancel`, `reject`, `deny`, `always in this conversation`), and so are the replies. **Behavior change:** Portuguese commands (`sim`, `confirmar`, `cancelar`, …) and replies were the default; pass `actionProposalText: ptBrActionProposalText` to keep them. The new `actionProposalText: { vocabulary, replies }` config replaces the word lists and the reply texts for any other language. A command naming an `#ID` that is not a proposal of the thread (`sim #abc`) is now an ordinary message for the model instead of a `404`.
+  - **`actionProposalWorker.onSettled(proposal)`**: called when a proposal's execution settles, so another channel (a WhatsApp bridge) gets the outcome pushed instead of polling. A throwing listener is logged and does not fail the worker.
+  - **`onPresentationError(error, { toolName, toolCallId?, runId?, threadId? })`**: now wired for turns and proposal executions. Default: a warning on the app logger (was `console.warn`).
+  - **No genui catalog + `uiCapabilities`**: `ctx.emitUi` no longer throws. A component the client declares is drawn; any other one degrades to its `fallbackText` (or is left out when it has none).
+  - **AG-UI**: `agora.ui` carries `fallbackText` and `componentVersions`; `agora.approval-requested` carries the proposal `target` (and `confirmation`); a proposal's interrupt has `metadata['agora.target']` and resuming it decides the proposal through the proposal service (it used to hit the parked-call approve and fail with `400`).
+  - **AG-UI event rename**: the proposal-decision custom event is now `agora.action-proposal-decision`, like every other `agora.*` event. The old `aviary.action-proposal-decision` is no longer sent — move listeners to the new name.
+  - `AgentService.chat` lost an unreachable proposal-decision branch (`chat` never decides by text; `send` does).
+
+- [#300](https://github.com/DavideCarvalho/adonis-agora-agent/pull/300) [`6db8d70`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/6db8d70189bb36ba6c4e4f77b585050da8f712d2) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Support result presentation on functional tools and `@AiTool` classes through the existing journaled UI stream. Add the inferred object form of `defineTool`, preserve raw domain results, and report presentation failures separately so successful actions are not retried because rendering failed. Export Agora-owned optional React static HTML, paginated PNG and PDF renderers and Playwright capture adapter.
+  
+  Remove cross-ecosystem peers: Agora owns its GenUI contracts, React adapters, AG-UI codec, and resumable upload client. All entries build and publish independently of Aviary; compatible wire protocols remain supported.
+
+- [#307](https://github.com/DavideCarvalho/adonis-agora-agent/pull/307) [`f3b8aa4`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/f3b8aa496d0b84f52811defd38b1f42ebcd5bf86) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Requires `@adonis-agora/durable` 0.43.3 or later (peer `>=0.43.3 <1.0.0`). Earlier versions could run one durable run twice at once in a process — a resume landing while the run was still executing — so a tool step could run twice after a very fast approval. 0.43.3 serializes a run's executions per process; the OpenCode durable engine relies on it instead of guarding its steps itself.
+
+- [#304](https://github.com/DavideCarvalho/adonis-agora-agent/pull/304) [`5d263b0`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/5d263b0742d8f726c9a40561d2559d2032d16092) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - MCP server and OAuth, with `@adonis-agora/authkit-server`'s `mcp: true`:
+  
+  - The MCP server registers its URL with AuthKit at boot, so `claude mcp add <url>` logs users in with no URL in AuthKit's config.
+  - `authKitAuth()` only accepts a token issued **for this server** (its RFC 8707 audience must be the endpoint's URL), as the MCP authorization spec requires. A token for another resource, or with no audience, is refused with `401`. **Behavior change:** clients that do not send `resource` need `authKitAuth({ audience: 'any' })`.
+  - `McpAuth.verify(token, context?)` gets `{ resource }`; `anyOf()` passes it on.
+  - Tool calls over MCP carry a `toolCallId` and an `idempotencyKey` per `tools/call` (tools that need one to write, ran refused before) and `pageContext.channel = 'mcp'`.
+  - `middleware` in `config/mcp.ts`: route middleware for the MCP endpoint (a rate limiter, say); it runs before the bearer check.
+  - `stateless: true` in `config/mcp.ts`: every `POST` gets its own transport (no in-memory sessions), for more than one instance behind a load balancer; `GET`/`DELETE` answer `405`.
+  - `actions` in `config/mcp.ts` (`'refuse'` by default, or `'execute'`): the provider never passed it to the server, so action tools could not be exposed through `config/mcp.ts`.
+  - `instructions` in `config/mcp.ts`: sent to the client in the `initialize` result.
+  - `endpoints` in `config/mcp.ts`: more MCP servers in the same app, each a protected resource of its own (path, registry, auth, sessions, RFC 9728 metadata, OAuth registration), inheriting the top-level settings.
+  - `tools/list` carries MCP `annotations` (`readOnlyHint` from the tool's kind by default); `describeTool` sets the `title` and the annotations per tool.
+  - In stateless mode, `GET`/`DELETE` authenticate first (`401` with the login challenge), then answer `405`.
+  - The RFC 9728 metadata route is named (`mcp.oauth_protected_resource`; `metadataRouteName` per endpoint).
+  - Generative-UI tools (`ui__show_*`, `ui__render` — any tool whose result is shown elsewhere) are no longer exposed over MCP: there is no screen there, and the model got nothing back.
+
+- [#307](https://github.com/DavideCarvalho/adonis-agora-agent/pull/307) [`f3b8aa4`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/f3b8aa496d0b84f52811defd38b1f42ebcd5bf86) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Engines: `defineConfig({ engine })` runs turns on something other than the library's loop — the routes, stream protocol, store, approvals, questions and queue stay the library's. `model` is optional under an engine, and `durable: true` is refused at boot unless the engine is durable itself. `@adonis-agora/agent/opencode`'s `openCode({ host })` runs turns on OpenCode 2 sessions, and `@adonis-agora/agent/opencode/durable`'s `openCodeDurable({ host })` checkpoints each step as the `agora.agent.opencode.run` workflow (decisions are durable signals; a parked turn survives restarts and catches up on what OpenCode asked meanwhile). OpenCode's events become the native frames and store rows (steps with usage, text, reasoning, nested code-mode calls, permissions as approval cards, forms as elicitations, cancel as `session.interrupt`); the agent's prompt and persona, `approvalPolicy`, skills, memory and regenerate reach the session; the app's tools are served to it over an internal MCP endpoint (`POST <path>/opencode/mcp`: signed per-actor tokens, calls only from a session running a turn of that actor, actions only against an approval the turn granted, `remember` at the actor's scope, `ctx.emitUi` into the turn). `AgentRunInput.hostContext` (and `ChatParams.hostContext`) carries the host's own JSON about a send through the queue (new nullable `host_context` column, healed on boot; never on the wire view) and the durable journal to the engine's host hooks: `onAsk`, `onUi`, `beforeSettle` and `onSettled`. `AgentRunner.runIdFor` lets a runner name its runs; `ToolCallRequest.parentId` records a call made inside another.
+
+### Patch Changes
+
+- [#306](https://github.com/DavideCarvalho/adonis-agora-agent/pull/306) [`2796edd`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/2796edd4b9f998b84cbc12cea779c21cfbe22c77) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Fixes from a docs audit:
+  
+  - `@AiTool` / `static tool` classes keep their `replacementKey` (it only worked with `defineTool`).
+  - `POST <path>/chat` answers malformed `uiCapabilities` with `400 invalid_ui_capabilities` instead of a `500`.
+  - A refused proposal decision over AG-UI (text or resume) answers its status (`403`/`404`) instead of a `500`.
+  - `UiCapabilities` / `validateUiCapabilities` have one definition; both the root and `/genui` entries still export them.
+  - Corrected stale comments (`genui` needs no extra peer, the default authorizer and actor resolver are not fail-closed, the migrations `configure` publishes) and removed a committed `.orig` file.
+
 ## 0.61.0
 
 ### Minor Changes

package/README.md

@@ -17,6 +17,13 @@ The package is two things layered on top of each other:
 `read` tools auto-execute, `action` tools gate on human approval (HITL), and `agent` tools delegate
 to another named agent.
 
+## Component registries and server rendering
+
+Tools support a `present` hook in both functional and decorated class forms. Register custom components per app, share React renderers between web screens and static exports, and generate paginated PNG/PDF tables and charts for your own delivery adapters.
+
+See the [component rendering guide](./docs/authoring/component-rendering.mdx) for complete examples, schemas, text fallbacks, and capture configuration.
+
+
 ## Install
 
 ```sh
@@ -43,7 +50,7 @@ else is an **optional peer**, imported lazily only when configured:
 | `@adonis-agora/telescope` (`^0.4.0`) | the Telescope watcher extension (`@adonis-agora/agent/telescope`) |
 | `@qdrant/js-client-rest` (`^1.11.0`) | `retrievers.qdrant({...})` |
 | `node-sql-parser` (`^5.3.0`) | the governed `dataTool` (`@adonis-agora/agent/data`) |
-| `react` (`^18` / `^19`) + `@dudousxd/nestjs-agent-react` (`>=0.28`, with `@ai-sdk/react` and `ai`) | `AgentProvider` / `useAgentChat` (`@adonis-agora/agent/react`) |
+| `react` (`^18` / `^19`), `@ai-sdk/react` and `ai` | `AgentProvider` / `useAgentChat` (`@adonis-agora/agent/react`) |
 
 ## Configure
 
@@ -83,7 +90,7 @@ message queue, approvals, attachments, threads), with the session cookie and shi
 already wired:
 
 ```tsx
-// npm i @dudousxd/nestjs-agent-react @ai-sdk/react ai
+// npm i @ai-sdk/react ai
 import { AgentProvider, useAgentChat } from '@adonis-agora/agent/react'
 
 export default function ChatPage() {
@@ -109,9 +116,8 @@ function Chat() {
 }
 ```
 
-The hooks are [`@dudousxd/nestjs-agent-react`](https://www.npmjs.com/package/@dudousxd/nestjs-agent-react)
-re-exported (an optional peer): this package speaks the same wire contract as `@dudousxd/nestjs-agent`,
-so one React client serves both. Without React, the framework-free stream client:
+The hooks ship inside Agora. Its protocol remains compatible with Aviary, but installation and
+releases are independent. Without React, use the framework-free stream client:
 
 ```ts
 import { createAgentChatClient } from '@adonis-agora/agent/client'
@@ -204,8 +210,7 @@ blocked tool result is withheld and the turn goes on; a blocked answer or tool c
 `OutputRejectedError`. `guardrails.wrapTool(name, handler)` restores placeholders into a tool's
 arguments and runs the `tool_args` rules on them. The output processor declares `incremental`, so the
 answer keeps streaming. The detectors (`detectPii` with Luhn/CPF/CNPJ/IBAN checks, `detectSecrets`,
-`scoreInjection`, `scoreToolText`) and `scan` work on their own. Same code as
-`@dudousxd/nestjs-agent-core/guardrails`, which also carries the raw OpenAI/Anthropic stream guard.
+`scoreInjection`, `scoreToolText`) and `scan` work on their own. The guardrail implementation ships locally in Agora; it does not require an Aviary core package.
 
 ### Framework-agnostic core (no AdonisJS)
 

package/dist/configure.d.ts

@@ -13,11 +13,13 @@ import type Configure from '@adonisjs/core/commands/configure';
  *    runtime scan when the barrel is absent);
  * 4. publishes `config/agent.ts`;
  * 5. publishes `config/mcp.ts` (the MCP endpoint config; the MCP provider is separate);
- * 6. publishes the Lucid migration for the six agent tables (run `node ace migration:run`; delete it
- *    if you only use the in-memory store). It delegates to `createAgentTables`, so it is idempotent
- *    and safe to run against a database the library already auto-created;
- * 7. publishes the pgvector migration for the RAG chunk table (Postgres + pgvector only; delete it
- *    unless you use `retrievers.pgvector({...})`).
+ * 6. publishes the Lucid migrations for the agent tables — the base tables plus the two forward-only
+ *    action-proposal upgrades (run `node ace migration:run`; delete them if you only use the
+ *    in-memory store). They delegate to `createAgentTables`, so they are idempotent and safe to run
+ *    against a database the library already auto-created;
+ * 7. publishes the Postgres migrations for the RAG chunk table (pgvector; delete it unless you use
+ *    `retrievers.pgvector({...})`) and the document-tree tables (delete it unless you use
+ *    `PgDocumentTreeStore`).
  */
 export declare function configure(command: Configure): Promise<void>;
 //# sourceMappingURL=configure.d.ts.map

package/dist/configure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAyBjD"}
+{"version":3,"file":"configure.d.ts","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,mCAAmC,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,SAAS,iBAyBjD"}

package/dist/configure.js

@@ -13,11 +13,13 @@ import { stubsRoot } from './stubs/main.js';
  *    runtime scan when the barrel is absent);
  * 4. publishes `config/agent.ts`;
  * 5. publishes `config/mcp.ts` (the MCP endpoint config; the MCP provider is separate);
- * 6. publishes the Lucid migration for the six agent tables (run `node ace migration:run`; delete it
- *    if you only use the in-memory store). It delegates to `createAgentTables`, so it is idempotent
- *    and safe to run against a database the library already auto-created;
- * 7. publishes the pgvector migration for the RAG chunk table (Postgres + pgvector only; delete it
- *    unless you use `retrievers.pgvector({...})`).
+ * 6. publishes the Lucid migrations for the agent tables — the base tables plus the two forward-only
+ *    action-proposal upgrades (run `node ace migration:run`; delete them if you only use the
+ *    in-memory store). They delegate to `createAgentTables`, so they are idempotent and safe to run
+ *    against a database the library already auto-created;
+ * 7. publishes the Postgres migrations for the RAG chunk table (pgvector; delete it unless you use
+ *    `retrievers.pgvector({...})`) and the document-tree tables (delete it unless you use
+ *    `PgDocumentTreeStore`).
  */
 export async function configure(command) {
     const codemods = await command.createCodemods();

package/dist/configure.js.map

@@ -1 +1 @@
-{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,oCAAoC,CAAC,CAAC;QACzD,MAAM,CAAC,WAAW,CAAC,wCAAwC,CAAC,CAAC;QAC7D,mGAAmG;QACnG,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC;IACjE,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAC/D,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,8CAA8C,EAAE,EAAE,CAAC,CAAC;IAC5F,MAAM,QAAQ,CAAC,aAAa,CAC1B,SAAS,EACT,wDAAwD,EACxD,EAAE,CACH,CAAC;IACF,MAAM,QAAQ,CAAC,aAAa,CAC1B,SAAS,EACT,sDAAsD,EACtD,EAAE,CACH,CAAC;IACF,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,kDAAkD,EAAE,EAAE,CAAC,CAAC;IAChG,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,iDAAiD,EAAE,EAAE,CAAC,CAAC;AACjG,CAAC"}
+{"version":3,"file":"configure.js","sourceRoot":"","sources":["../configure.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAkB;IAChD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAEhD,MAAM,QAAQ,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,EAAE;QACrC,MAAM,CAAC,WAAW,CAAC,oCAAoC,CAAC,CAAC;QACzD,MAAM,CAAC,WAAW,CAAC,wCAAwC,CAAC,CAAC;QAC7D,mGAAmG;QACnG,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;IACrE,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,mBAAmB,EAAE,EAAE,CAAC,CAAC;IACjE,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAC/D,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,8CAA8C,EAAE,EAAE,CAAC,CAAC;IAC5F,MAAM,QAAQ,CAAC,aAAa,CAC1B,SAAS,EACT,wDAAwD,EACxD,EAAE,CACH,CAAC;IACF,MAAM,QAAQ,CAAC,aAAa,CAC1B,SAAS,EACT,sDAAsD,EACtD,EAAE,CACH,CAAC;IACF,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,kDAAkD,EAAE,EAAE,CAAC,CAAC;IAChG,MAAM,QAAQ,CAAC,aAAa,CAAC,SAAS,EAAE,iDAAiD,EAAE,EAAE,CAAC,CAAC;AACjG,CAAC"}

package/dist/providers/a2a_provider.d.ts

@@ -0,0 +1,14 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+export default class A2aProvider {
+    #private;
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    boot(): Promise<void>;
+    /**
+     * Register `request_permission` in every process — a queue or durable worker that replays a turn
+     * which called it needs the tool as much as the web process that started it.
+     */
+    ready(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=a2a_provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a2a_provider.d.ts","sourceRoot":"","sources":["../../providers/a2a_provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAyC/D,MAAM,CAAC,OAAO,OAAO,WAAW;;IAClB,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAA7C,YAAsB,GAAG,EAAE,kBAAkB,EAAI;IAE3C,IAAI,kBA2BT;IAED;;;OAGG;IACG,KAAK,kBASV;IAEK,QAAQ,kBAEb;CAiEF"}

package/dist/providers/a2a_provider.js

@@ -0,0 +1,136 @@
+import { resolveA2aAuth } from '../src/a2a/auth.js';
+import { createA2aHandler } from '../src/a2a/handler.js';
+import { registerRequestPermissionTool } from '../src/a2a/permission-tool.js';
+import { setA2aHandler } from '../src/a2a/runtime.js';
+import { ensureA2aTables, InMemoryA2aStore, LucidA2aStore, } from '../src/a2a/store.js';
+import { AgentService } from '../src/agent-service.js';
+import { ToolRegistry } from '../src/tool-registry.js';
+/**
+ * Exposes registered agents to personal agents over A2A 1.0 (HTTP+JSON) — the transport of PACT.
+ * Reads `config/a2a.ts` and answers, for each configured agent:
+ *
+ * - `GET /{path}/{agent}/.well-known/agent-card.json` — the Agent Card (public).
+ * - `POST /{path}/{agent}/message:send` — a synchronous turn (identity, and delegation when sent).
+ * - `GET /{path}/{agent}/tasks`, `GET …/tasks/{id}`, `POST …/tasks/{id}:cancel` — as PACT §2.2 fixes.
+ *
+ * Mounted as SERVER middleware, ahead of the router: A2A requests never reach the bodyparser,
+ * session or CSRF (see `src/a2a/server_middleware.ts`). Everything is resolved on the first A2A
+ * request, so this provider can sit anywhere in `adonisrc.ts`.
+ */
+function normalizePath(path) {
+    return (path ?? 'a2a').replace(/^\/+|\/+$/g, '');
+}
+/**
+ * The A2A config, or `undefined` when the surface is off. A `config/a2a.ts` whose default export
+ * is `undefined` (feature-flagged off) reaches the config store as its module namespace
+ * (`{ default: undefined }`), not as `undefined`.
+ */
+function a2aConfigOf(app) {
+    const config = app.config.get('a2a', undefined);
+    return config && typeof config === 'object' && config.agents && config.auth ? config : undefined;
+}
+export default class A2aProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    async boot() {
+        const config = a2aConfigOf(this.app);
+        if (!config)
+            return;
+        const server = await this.app.container.make('server');
+        server.use([() => import('../src/a2a/server_middleware.js')]);
+        // Only A2A traffic ever touches the A2A runtime: a broken auth driver or database must not
+        // turn every route of the app into a 500.
+        const prefix = `/${normalizePath(config.path)}/`;
+        const isA2a = (url) => url.startsWith(prefix) ||
+            (config.rootCard !== undefined && url === '/.well-known/agent-card.json');
+        // Built on the first A2A request: the agent provider binds `AgentService` in its own boot, and
+        // the auth driver may need a fully booted app. A failed build is retried on the next one.
+        let built = null;
+        setA2aHandler(async (ctx) => {
+            if (!isA2a((ctx.request.url() ?? '').split('?')[0] ?? ''))
+                return false;
+            if (built === null) {
+                built = this.#build(config);
+                built.catch(() => {
+                    built = null;
+                });
+            }
+            return (await built)(ctx);
+        });
+    }
+    /**
+     * Register `request_permission` in every process — a queue or durable worker that replays a turn
+     * which called it needs the tool as much as the web process that started it.
+     */
+    async ready() {
+        const config = a2aConfigOf(this.app);
+        if (!config)
+            return;
+        try {
+            await this.#registerPermissionTool(config);
+        }
+        catch (error) {
+            const logger = await this.app.container.make('logger');
+            logger.warn({ err: error }, 'a2a: could not register request_permission yet');
+        }
+    }
+    async shutdown() {
+        setA2aHandler(null);
+    }
+    #permissionToolRegistered = false;
+    async #registerPermissionTool(config) {
+        // With its own runtime the app registers `request_permission` where ITS tools live
+        // (`registerRequestPermissionTool`) — the shared registry may be another surface's.
+        if (this.#permissionToolRegistered || config.service !== undefined)
+            return;
+        const auth = await resolveA2aAuth(config.auth, { app: this.app });
+        const scopes = await auth.delegableScopes();
+        if (Object.keys(scopes).length > 0) {
+            registerRequestPermissionTool(await this.app.container.make(ToolRegistry), scopes);
+        }
+        this.#permissionToolRegistered = true;
+    }
+    async #build(config) {
+        const registry = await this.app.container.make(ToolRegistry);
+        const service = config.service === undefined
+            ? await this.app.container.make(AgentService)
+            : typeof config.service === 'function'
+                ? await config.service({ app: this.app })
+                : config.service;
+        const auth = await resolveA2aAuth(config.auth, { app: this.app });
+        await this.#registerPermissionTool(config);
+        const brands = new Map(Object.entries(config.agents).map(([id, agent]) => [
+            id,
+            { id, agentName: agent.agent ?? id, card: agent.card },
+        ]));
+        return createA2aHandler({
+            path: normalizePath(config.path),
+            ...(config.baseUrl !== undefined ? { baseUrl: config.baseUrl } : {}),
+            brands,
+            ...(config.rootCard !== undefined ? { rootCardBrand: config.rootCard } : {}),
+            auth,
+            store: await this.#store(config),
+            service,
+            registry,
+            actions: config.actions ?? 'approve-delegated',
+            timeoutMs: config.timeoutMs ?? 120_000,
+            maxBodyBytes: config.maxBodyBytes ?? 1024 * 1024,
+            ...(config.roles !== undefined ? { roles: config.roles } : {}),
+            ...(config.actor !== undefined ? { actor: config.actor } : {}),
+        });
+    }
+    async #store(config) {
+        const store = config.store ?? 'lucid';
+        if (typeof store === 'object')
+            return store;
+        if (store === 'memory')
+            return new InMemoryA2aStore();
+        const db = (await this.app.container.make('lucid.db'));
+        const connection = db.connection(config.connection);
+        await ensureA2aTables(connection);
+        return new LucidA2aStore(connection);
+    }
+}
+//# sourceMappingURL=a2a_provider.js.map

package/dist/providers/a2a_provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a_provider.js","sourceRoot":"","sources":["../../providers/a2a_provider.ts"],"names":[],"mappings":"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"}

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;AA2M/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;;IASpB,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAA7C,YAAsB,GAAG,EAAE,kBAAkB,EAAI;IAEjD,QAAQ,SAcP;IAEK,IAAI,kBA+NT;IAED;;;;;;;;;;;;;;OAcG;IACG,KAAK,kBAiBV;IAEK,QAAQ,kBAYb;CA8lDF"}
+{"version":3,"file":"agent_provider.d.ts","sourceRoot":"","sources":["../../providers/agent_provider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAoM/D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;;IAWpB,SAAS,CAAC,GAAG,EAAE,kBAAkB;IAA7C,YAAsB,GAAG,EAAE,kBAAkB,EAAI;IAEjD,QAAQ,SAcP;IAEK,IAAI,kBA+PT;IAED;;;;;;;;;;;;;;OAcG;IACG,KAAK,kBAiBV;IAEK,QAAQ,kBAcb;CAooDF"}

package/dist/providers/agent_provider.js

@@ -1,7 +1,10 @@
 import { pathToFileURL } from 'node:url';
+import { personalAgentGate, personalAgentScopes } from '../src/a2a/gate.js';
 import { assertIndependentActionRuntime } from '../src/action-proposal-runtime.js';
 import { ActionProposalService, ActionProposalServiceError, } from '../src/action-proposal-service.js';
 import { validateActionProposalListQuery } from '../src/action-proposal-transitions.js';
+import { DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, } from '../src/attachment-limits.js';
+import { assertRunnable, engineOnlyModel } from '../src/engine.js';
 import { ActionProposalExecutor, ActionProposalWorker, AgentDepsFactory, AgentGenui, AgentRegistry, AgentService, AgentSseEncoder, ALL_AGENTS, AnonymousActorResolver, AttachmentInventoryError, AttachmentRefusedError, ChatQueueError, ChatQueueService, DefaultToolAuthorizer, discoverTools, evaluateGovernanceGate, evaluateOwnership, governanceQueries as governanceQueriesFactories, HumanReplyMismatchError, InlineAgentRunner, InProcessTokenStreamSink, isQuotaProvider, LedgerQuotaProvider, lucidStoreConnection, ModelNotAllowedError, memoryForgetVerdict, offerMemories, offerSkills, PersonaNotFoundError, parseStreamCursor, pricingStores, QuotaBlockedError, REQUESTER_APPROVER, RegenerateNeedsThreadError, RunNotActiveError, registerDelegateTools, registerFunctionalTool, registerToolsFromBarrel, resolveActorResolver, resolvePersonaAlias, ToolRegistry, toApprovalPolicy, toModelCatalog, UnknownAgentError, withActorLabel, withActorLabels, } from '../src/index.js';
 import { McpToolImporter } from '../src/mcp-client/index.js';
 import { setTelescopeGovernanceQueries } from '../src/telescope/governance-registry.js';
@@ -77,18 +80,6 @@ function attachmentRefs(claimed) {
     }
     return refs;
 }
-/** Default per-file size cap when the attachment store declares none (20 MiB). */
-const DEFAULT_MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
-/** Default allowlist: what multimodal model providers commonly accept as native image/file parts. */
-const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES = [
-    'image/png',
-    'image/jpeg',
-    'image/gif',
-    'image/webp',
-    'application/pdf',
-    'text/plain',
-    'text/csv',
-];
 /**
  * Wires `@adonis-agora/agent` into the AdonisJS application from `config/agent.ts`:
  *
@@ -122,6 +113,8 @@ export default class AgentProvider {
     #mcpTools = null;
     /** Whatever was built at boot that may own a schema: the store, the pricing store, the read-model. */
     #schemaOwners = [];
+    /** The engine running the turns instead of the loop (`engine` in the config), when there is one. */
+    #engine;
     constructor(app) {
         this.app = app;
     }
@@ -195,7 +188,14 @@ export default class AgentProvider {
             this.app.container.bindValue(AgentGenui, new AgentGenui(setup.catalog, setup.resolveCatalog));
         }
         // ── Runtime graph ──
-        const model = await this.#resolveModel(config);
+        // An engine (`engine` in the config) runs the turns instead of the loop: `model` is optional
+        // then, and `durable: true` (the LOOP's durable runner) is refused unless the engine is durable.
+        const engine = typeof config.engine === 'function' ? await config.engine() : config.engine;
+        assertRunnable({ model: config.model, engine, durable: config.durable });
+        this.#engine = engine;
+        const model = config.model === undefined && engine !== undefined
+            ? engineOnlyModel(engine)
+            : await this.#resolveModel(config);
         const store = await this.#resolveStore(config);
         const sink = await this.#resolveSink(config);
         // One budget: `{ limits }` over the usage ledger, or a `QuotaProvider` of your own — reported by
@@ -230,7 +230,9 @@ export default class AgentProvider {
         this.#sink = sink;
         this.#actorDirectory = actorDirectory;
         this.#schemaOwners = [store, pricingStore, governance, sink];
+        const onPresentationError = config.onPresentationError ?? (await this.#logPresentationErrors());
         const factory = new AgentDepsFactory({
+            ...(onPresentationError !== undefined ? { onPresentationError } : {}),
             model,
             store,
             sink,
@@ -253,8 +255,13 @@ export default class AgentProvider {
                 ? { toolTransientRetry: config.toolTransientRetry }
                 : {}),
             ...(config.historyWindow !== undefined ? { historyWindow: config.historyWindow } : {}),
-            ...(config.skills !== undefined ? { skills: config.skills } : {}),
-            ...(config.memory !== undefined ? { memory: config.memory } : {}),
+            // Personal agents (A2A) resolve no memory or skill scope — see `personalAgentScopes`.
+            ...(config.skills !== undefined
+                ? { skills: { ...config.skills, scopes: personalAgentScopes(config.skills.scopes) } }
+                : {}),
+            ...(config.memory !== undefined
+                ? { memory: { ...config.memory, scopes: personalAgentScopes(config.memory.scopes) } }
+                : {}),
             ...(config.inputProcessors !== undefined ? { inputProcessors: config.inputProcessors } : {}),
             ...(config.outputProcessors !== undefined
                 ? { outputProcessors: config.outputProcessors }
@@ -292,6 +299,7 @@ export default class AgentProvider {
                     return {
                         registry: deps.registry,
                         rolesPolicy: deps.rolesPolicy,
+                        ...(onPresentationError !== undefined ? { onPresentationError } : {}),
                         ...(resolveUiCatalog !== undefined ? { resolveUiCatalog } : {}),
                         ...(persona !== undefined ? { persona } : {}),
                         ...(allowedTools !== undefined ? { allowedTools } : {}),
@@ -308,17 +316,29 @@ export default class AgentProvider {
         }
         if (this.#actionProposalWorker)
             this.app.container.bindValue(ActionProposalWorker, this.#actionProposalWorker);
-        const runner = config.durable === true
-            ? ((await this.#resolveDurableRunner(factory, store, queue, sink)) ??
-                new InlineAgentRunner(factory, store, queue))
-            : new InlineAgentRunner(factory, store, queue);
+        const runner = engine !== undefined
+            ? await engine.createRunner({
+                factory,
+                store,
+                sink,
+                registry,
+                queue,
+                make: (binding) => this.app.container.make(binding),
+                ...this.#appKey(),
+            })
+            : config.durable === true
+                ? ((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,
             ...(config.backgroundActorResolver !== undefined
                 ? { backgroundActorResolver: config.backgroundActorResolver }
                 : {}),
             ...(config.actionApprovalMode === 'independent'
-                ? { actionProposals: new ActionProposalService(store, factory.forAgent().approvalPolicy) }
+                ? {
+                    actionProposals: new ActionProposalService(store, factory.forAgent().approvalPolicy, config.actionProposalText),
+                }
                 : {}),
             // No `models` → the catalog the model provider carries (`aiSdkModels`), else none.
             ...(config.models !== undefined
@@ -368,6 +388,8 @@ export default class AgentProvider {
         this.#actionProposalWorker?.start();
     }
     async shutdown() {
+        await this.#engine?.shutdown?.();
+        this.#engine = undefined;
         await this.#actionProposalWorker?.stop();
         this.#actionProposalWorker = null;
         // The Lucid store shares the app's `db` (it owns no connection to close); the in-process sink
@@ -399,6 +421,14 @@ export default class AgentProvider {
         await importer.start();
     }
     // ── resolution helpers ────────────────────────────────────────────────────
+    /** The app's `APP_KEY` (a `Secret` in `config/app.ts`), for an engine that signs something. */
+    #appKey() {
+        const raw = this.app.config.get('app.appKey', undefined);
+        const released = typeof raw?.release === 'function'
+            ? raw.release()
+            : raw;
+        return typeof released === 'string' && released.length > 0 ? { appKey: released } : {};
+    }
     async #resolveModel(config) {
         const model = config.model;
         if (typeof model === 'function') {
@@ -493,7 +523,9 @@ export default class AgentProvider {
         return typeof staging === 'function' ? staging({ app: this.app, agentStore }) : staging;
     }
     #resolveAuthorizer(config, defaultRoles) {
-        return (config.authorizer ??
+        // Whatever the app configured, personal agents (A2A) reach only tools that name them — see
+        // `personalAgentGate`. A no-op for every other actor.
+        return personalAgentGate(config.authorizer ??
             config.rolesPolicy ??
             new DefaultToolAuthorizer(defaultRoles, { emptyRoles: config.emptyRoles ?? 'allow' }));
     }
@@ -586,6 +618,17 @@ export default class AgentProvider {
             if (mode === null) {
                 return ctx.response.badRequest({ message: "mode must be 'auto', 'queue' or 'interrupt'" });
             }
+            let uiCapabilities;
+            try {
+                if (body.uiCapabilities !== undefined)
+                    uiCapabilities = validateUiCapabilities(body.uiCapabilities);
+            }
+            catch {
+                return ctx.response.badRequest({
+                    message: 'uiCapabilities must be valid UI capabilities',
+                    code: 'invalid_ui_capabilities',
+                });
+            }
             let started;
             try {
                 started = await service.send({
@@ -602,9 +645,7 @@ export default class AgentProvider {
                         ? { personaId: body.persona }
                         : {}),
                     ...(body.pageContext !== undefined ? { pageContext: body.pageContext } : {}),
-                    ...(body.uiCapabilities !== undefined
-                        ? { uiCapabilities: validateUiCapabilities(body.uiCapabilities) }
-                        : {}),
+                    ...(uiCapabilities !== undefined ? { uiCapabilities } : {}),
                     ...(refs.length > 0 ? { attachments: refs } : {}),
                 });
             }
@@ -683,7 +724,9 @@ export default class AgentProvider {
         // 3b. Protocol adapters (`adapters` in the config): other wire protocols over the same runs —
         // e.g. `agUiAdapter()` mounts `POST <path>/ag-ui`. Each gets the checks these routes use, so an
         // adapter cannot be more permissive than the native routes by forgetting one.
-        for (const adapter of config.adapters ?? []) {
+        // An engine's own routes (the MCP endpoint OpenCode reaches the app's tools through) mount the
+        // same way, after the configured adapters.
+        for (const adapter of [...(config.adapters ?? []), ...(this.#engine?.adapters?.() ?? [])]) {
             await adapter.mount({
                 service,
                 defaultAgentName,
@@ -1771,6 +1814,15 @@ export default class AgentProvider {
         const owner = await service.threadOwner(threadId);
         return this.#assertOwner(ctx, actor, owner, 'thread', governanceAuthorize);
     }
+    /** The default `onPresentationError`: a warning on the app's logger (none bound → `undefined`). */
+    async #logPresentationErrors() {
+        if (!this.app.container.hasBinding('logger'))
+            return undefined;
+        const logger = await this.app.container.make('logger');
+        return (error, details) => {
+            logger.warn({ err: error, ...details }, 'Tool presentation failed after successful execution');
+        };
+    }
     #conflictOnMismatch(ctx, error) {
         // The run the decision was for has ended: nothing is waiting for it (`409 run_not_active`).
         if (error instanceof RunNotActiveError) {
@@ -1787,6 +1839,10 @@ export default class AgentProvider {
      * `POST <path>/chat` does. `false` for an error that is none of those (the caller rethrows).
      */
     #refuseSend(ctx, error) {
+        if (error instanceof ActionProposalServiceError) {
+            ctx.response.status(error.status).json({ message: error.message });
+            return true;
+        }
         if (error instanceof AttachmentRefusedError) {
             ctx.response.status(error.status).json({ message: error.message });
             return true;