@adonis-agora/agent 0.61.0 → 0.63.0

package/dist/src/ui-capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui-capabilities.d.ts","sourceRoot":"","sources":["../../src/ui-capabilities.ts"],"names":[],"mappings":"AACA,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtD;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAuBrE"}
+{"version":3,"file":"ui-capabilities.d.ts","sourceRoot":"","sources":["../../src/ui-capabilities.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,cAAc,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/src/ui-capabilities.js

@@ -1,25 +1,4 @@
-const COMPONENT_NAME = /^[A-Za-z][A-Za-z0-9]{0,63}$/;
-export function validateUiCapabilities(value) {
-    if (!record(value) ||
-        Object.keys(value).some((key) => key !== 'components') ||
-        !Array.isArray(value.components))
-        throw new TypeError('Invalid UI capabilities');
-    const seen = new Set();
-    const components = value.components.map((component) => {
-        if (!record(component) ||
-            Object.keys(component).some((key) => key !== 'name' && key !== 'version') ||
-            typeof component.name !== 'string' ||
-            !COMPONENT_NAME.test(component.name) ||
-            !Number.isSafeInteger(component.version) ||
-            Number(component.version) <= 0 ||
-            seen.has(component.name))
-            throw new TypeError('Invalid UI component capability');
-        seen.add(component.name);
-        return { name: component.name, version: Number(component.version) };
-    });
-    return { components };
-}
-function record(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+// Defined with the rest of generative UI (which must stay import-free for browsers) and re-exported
+// here, so the root entry keeps exporting it.
+export { validateUiCapabilities } from './genui/capabilities.js';
 //# sourceMappingURL=ui-capabilities.js.map

package/dist/src/ui-capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"ui-capabilities.js","sourceRoot":"","sources":["../../src/ui-capabilities.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAMrD,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IACE,CAAC,MAAM,CAAC,KAAK,CAAC;QACd,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,YAAY,CAAC;QACtD,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC;QAEhC,MAAM,IAAI,SAAS,CAAC,yBAAyB,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAkB,EAAE,EAAE;QAC7D,IACE,CAAC,MAAM,CAAC,SAAS,CAAC;YAClB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,SAAS,CAAC;YACzE,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;YAClC,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YACpC,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,OAAO,CAAC;YACxC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;YAC9B,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC;YAExB,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;QACzD,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;IACtE,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,UAAU,EAAE,CAAC;AACxB,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"ui-capabilities.js","sourceRoot":"","sources":["../../src/ui-capabilities.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,8CAA8C;AAC9C,OAAO,EAAuB,sBAAsB,EAAE,MAAM,yBAAyB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -23,6 +23,7 @@
     "ai-sdk",
     "durable",
     "tanstack-intent",
+    "opencode",
     "agora",
     "guardrails"
   ],
@@ -41,6 +42,21 @@
       "import": "./dist/src/ai-sdk/index.js",
       "default": "./dist/src/ai-sdk/index.js"
     },
+    "./a2a": {
+      "types": "./dist/src/a2a/index.d.ts",
+      "import": "./dist/src/a2a/index.js",
+      "default": "./dist/src/a2a/index.js"
+    },
+    "./a2a_provider": {
+      "types": "./dist/providers/a2a_provider.d.ts",
+      "import": "./dist/providers/a2a_provider.js",
+      "default": "./dist/providers/a2a_provider.js"
+    },
+    "./a2a/server_middleware": {
+      "types": "./dist/src/a2a/server_middleware.d.ts",
+      "import": "./dist/src/a2a/server_middleware.js",
+      "default": "./dist/src/a2a/server_middleware.js"
+    },
     "./mcp": {
       "types": "./dist/src/mcp/index.d.ts",
       "import": "./dist/src/mcp/index.js",
@@ -71,11 +87,26 @@
       "import": "./dist/src/ag-ui/index.js",
       "default": "./dist/src/ag-ui/index.js"
     },
+    "./channels": {
+      "types": "./dist/src/channels/index.d.ts",
+      "import": "./dist/src/channels/index.js",
+      "default": "./dist/src/channels/index.js"
+    },
     "./durable": {
       "types": "./dist/src/durable/index.d.ts",
       "import": "./dist/src/durable/index.js",
       "default": "./dist/src/durable/index.js"
     },
+    "./opencode": {
+      "types": "./dist/src/opencode/index.d.ts",
+      "import": "./dist/src/opencode/index.js",
+      "default": "./dist/src/opencode/index.js"
+    },
+    "./opencode/durable": {
+      "types": "./dist/src/opencode/durable/index.d.ts",
+      "import": "./dist/src/opencode/durable/index.js",
+      "default": "./dist/src/opencode/durable/index.js"
+    },
     "./authz": {
       "types": "./dist/src/authz/index.d.ts",
       "import": "./dist/src/authz/index.js",
@@ -180,6 +211,16 @@
       "types": "./dist/src/media/index.d.ts",
       "import": "./dist/src/media/index.js",
       "default": "./dist/src/media/index.js"
+    },
+    "./react/genui/server": {
+      "types": "./dist/src/react/genui/server.d.ts",
+      "import": "./dist/src/react/genui/server.js",
+      "default": "./dist/src/react/genui/server.js"
+    },
+    "./react/genui/server/playwright": {
+      "types": "./dist/src/react/genui/server_playwright.d.ts",
+      "import": "./dist/src/react/genui/server_playwright.js",
+      "default": "./dist/src/react/genui/server_playwright.js"
     }
   },
   "files": [
@@ -197,21 +238,34 @@
   "peerDependencies": {
     "@adonis-agora/authz": ">=0.4.2 <1.0.0",
     "@adonis-agora/diagnostics": ">=0.1.0 <1.0.0",
-    "@adonis-agora/durable": ">=0.8.0 <1.0.0",
+    "@adonis-agora/durable": ">=0.43.3 <1.0.0",
     "@adonis-agora/media": ">=0.18.0 <1.0.0",
     "@adonis-agora/telescope": ">=0.4.0 <1.0.0",
     "@adonisjs/assembler": "^8.4.0",
     "@adonisjs/core": "^7.3.0",
     "@adonisjs/lucid": "^22.4.0",
     "@adonisjs/redis": "^9.2.0 || ^10.0.0 || ^11.0.0",
-    "@dudousxd/nestjs-agent-core": ">=0.35.0 <1.0.0",
-    "@dudousxd/nestjs-agent-react": ">=0.30.0 <1.0.0",
-    "@dudousxd/nestjs-media-client": ">=0.3.0 <1.0.0",
     "@qdrant/js-client-rest": "^1.11.0",
     "ai": "^7.0.0",
     "node-sql-parser": "^5.3.0",
     "react": "^18.0.0 || ^19.0.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "@ai-sdk/react": "^4.0.0",
+    "@json-render/react": ">=0.21.0 <1.0.0",
+    "@streamdown/code": "^1.1.1",
+    "@streamdown/math": "^1.0.2",
+    "@streamdown/mermaid": "^1.0.2",
+    "katex": "^0.16.45",
+    "prism-react-renderer": "^2.4.1",
+    "react-dom": ">=18",
+    "react-markdown": "^10.1.0",
+    "rehype-katex": "^7.0.1",
+    "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "streamdown": "^2.5.0",
+    "unist-util-visit": "^5.1.0",
+    "playwright-core": ">=1.48 <2"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -253,23 +307,62 @@
     "zod": {
       "optional": true
     },
-    "@dudousxd/nestjs-agent-core": {
+    "@adonis-agora/media": {
+      "optional": true
+    },
+    "@ai-sdk/react": {
       "optional": true
     },
-    "@dudousxd/nestjs-agent-react": {
+    "@json-render/react": {
       "optional": true
     },
-    "@dudousxd/nestjs-media-client": {
+    "@streamdown/code": {
       "optional": true
     },
-    "@adonis-agora/media": {
+    "@streamdown/math": {
+      "optional": true
+    },
+    "@streamdown/mermaid": {
+      "optional": true
+    },
+    "katex": {
+      "optional": true
+    },
+    "prism-react-renderer": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "react-markdown": {
+      "optional": true
+    },
+    "rehype-katex": {
+      "optional": true
+    },
+    "rehype-sanitize": {
+      "optional": true
+    },
+    "remark-gfm": {
+      "optional": true
+    },
+    "remark-math": {
+      "optional": true
+    },
+    "streamdown": {
+      "optional": true
+    },
+    "unist-util-visit": {
+      "optional": true
+    },
+    "playwright-core": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@adonis-agora/authz": "0.16.1",
+    "@adonis-agora/authz": "0.18.0",
     "@adonis-agora/diagnostics": "0.2.10",
-    "@adonis-agora/durable": "0.43.1",
+    "@adonis-agora/durable": "0.43.3",
     "@adonis-agora/telescope": "0.21.1",
     "@adonisjs/assembler": "8.5.2",
     "@adonisjs/core": "7.5.2",
@@ -278,37 +371,50 @@
     "@ag-ui/client": "1.0.1",
     "@ag-ui/core": "1.0.1",
     "@ai-sdk/react": "^4.0.125",
-    "@dudousxd/nestjs-agent-core": "0.36.0",
-    "@dudousxd/nestjs-agent-react": "0.31.0",
-    "@dudousxd/nestjs-media-client": "0.3.0",
+    "@opencode/client": "2.0.18",
     "@qdrant/js-client-rest": "1.19.0",
-    "@tanstack/intent": "0.4.0",
+    "@tanstack/intent": "0.5.0",
     "@testcontainers/mysql": "12.2.0",
     "@testcontainers/postgresql": "12.2.0",
     "@testing-library/dom": "10.4.2",
     "@testing-library/react": "16.3.3",
-    "@types/node": "26.6.3",
+    "@types/node": "26.6.4",
     "@types/pg": "8.23.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
     "agent-0-56": "npm:@adonis-agora/agent@0.56.0",
     "agent-0-58": "npm:@adonis-agora/agent@0.58.0",
     "agent-0-59": "npm:@adonis-agora/agent@0.59.0",
-    "ai": "7.0.102",
+    "ai": "7.0.122",
     "ajv": "^8.20.0",
     "better-sqlite3": "13.0.3",
     "jsdom": "30.1.1",
     "luxon": "3.7.2",
-    "mysql2": "3.24.4",
+    "mysql2": "3.24.5",
     "node-sql-parser": "5.4.0",
-    "pg": "8.23.0",
+    "pg": "8.23.1",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "rxjs": "^7.8.1",
     "testcontainers": "12.2.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.2",
-    "zod": "4.6.5"
+    "vitest": "5.0.3",
+    "zod": "4.6.5",
+    "@json-render/core": "0.21.0",
+    "@json-render/react": "0.21.0",
+    "@streamdown/code": "1.1.1",
+    "@streamdown/math": "1.0.3",
+    "@streamdown/mermaid": "1.0.3",
+    "katex": "0.16.45",
+    "playwright-core": "^1.63.0",
+    "prism-react-renderer": "2.4.1",
+    "react-markdown": "10.1.0",
+    "rehype-katex": "7.0.1",
+    "rehype-sanitize": "6.0.0",
+    "remark-gfm": "4.0.1",
+    "remark-math": "6.0.0",
+    "streamdown": "2.6.0",
+    "unist-util-visit": "5.1.0"
   },
   "engines": {
     "node": ">=20.6.0"

package/skills/agent-governance/SKILL.md

@@ -74,12 +74,20 @@ export default defineConfig({
 })
 ```
 
-Because the offered-tools filter AND the invoke-time re-check call the same
-`can(actor, tool)`, swapping the policy changes both layers together — they can never
-disagree about what an actor may reach.
+Because the offered-tools filter calls `canOffer(actor, tool)` when the policy defines
+it (else `can`) and the invoke-time re-check always calls `can(actor, tool)`, swapping
+the policy changes both layers together — they disagree only when a policy defines
+`canOffer` to offer what it will not run (A2A step-up).
+
+The provider wraps whatever policy you configure with `personalAgentGate`: an actor with
+the `personal_agent` role (A2A personal agents) reaches only tools that declare one of its
+roles — a tool with no `roles` is out of its reach even when open by default — and its
+memory and skill scopes resolve to none. Nothing changes for any other actor.
 
 Source: `packages/adonis/docs/governance/authorization.mdx` ("Ability-aware
-authorization"), `packages/adonis/src/authorizer.ts`.
+authorization"), `packages/adonis/src/authorizer.ts`,
+`packages/adonis/src/a2a/gate.ts` (`personalAgentGate`, `personalAgentScopes`),
+`packages/adonis/docs/a2a.mdx` ("What a personal agent can reach").
 
 ### Pattern 2 — mount the governance read-model with `governanceAuthorize`
 

package/skills/agent-personas-agents/SKILL.md

@@ -175,7 +175,8 @@ delegatesTo: [{ agent: 'researcher', roles: ['ANALYST', 'ADMIN'] }]
 
 Mechanism: a delegate tool goes through the SAME gate as every other tool. A bare string
 carries nothing, so under `DefaultToolAuthorizer` it takes `defaultRoles` (open unless
-configured), and under the authz Bouncer adapter a spec without `ability` is denied
+configured — except for A2A personal agents, which reach only tools that declare one of
+their roles), and under the authz Bouncer adapter a spec without `ability` is denied
 outright — the edge becomes uncalled for everyone.
 Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` ("Authorizing a
 delegation"), `packages/adonis/src/types.ts` (`DelegateEdge`).

package/skills/agent-setup/SKILL.md

@@ -21,14 +21,17 @@ sources:
   - "DavideCarvalho/adonis-agent:packages/adonis/src/stores/factory.ts"
   - "DavideCarvalho/adonis-agent:packages/adonis/docs/react.mdx"
   - "DavideCarvalho/adonis-agent:packages/adonis/src/react/index.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/channels.mdx"
 ---
 
 # Setting up @adonis-agora/agent
 
 `@adonis-agora/agent` is a governed AI agent module for AdonisJS: one `defineConfig`
-call in `config/agent.ts` wires a provider-agnostic agent loop, persistence, budgeting,
-and the `/agent/*` HTTP+SSE routes. Only `model` is required — everything else is a
-fail-closed default that this skill walks through.
+call in `config/agent.ts` wires a provider-agnostic agent (the loop by default, or an
+`engine` that runs turns instead), persistence, budgeting,
+and the `/agent/*` HTTP+SSE routes. Either `model` (the loop runs the turns) or
+`engine` (something else does) is required — everything else ships with a default that
+this skill walks through.
 
 ## Setup
 
@@ -42,8 +45,9 @@ node ace configure @adonis-agora/agent
 `configure` registers `@adonis-agora/agent/agent_provider` and
 `@adonis-agora/agent/dashboard_provider` in `adonisrc.ts`, registers the Assembler init
 hook that generates the typed `app/agent_tools` barrel, publishes `config/agent.ts`,
-`config/mcp.ts`, and two migrations (the agent tables; a Postgres-only pgvector RAG chunk
-table you can delete). Then add the model peer and write your config:
+`config/mcp.ts`, and five migrations: three for the agent tables (the base tables plus two
+forward-only action-proposal upgrades) and two Postgres-only ones (the pgvector RAG chunk
+table and the document-tree tables — delete the ones you don't use). Then add the model peer and write your config:
 
 ```bash
 pnpm add ai zod @ai-sdk/openai
@@ -75,9 +79,10 @@ export default defineConfig({
 })
 ```
 
-Run the migration for the six agent tables (`agent_thread`, `agent_message`,
-`agent_tool_call`, `agent_token_usage`, `agent_model_pricing`, plus the run-lifecycle
-columns):
+Run the published migrations for the agent tables (`agent_action_proposal`,
+`agent_thread`, `agent_message`, `agent_tool_call`, `agent_token_usage`,
+`agent_model_pricing`, `agent_run`, `agent_queued_message`, `agent_confirm_token`, plus the
+`agent_stream_frame` buffer and the text channels' `agent_channel_state`):
 
 ```bash
 node ace migration:run
@@ -85,8 +90,8 @@ node ace migration:run
 
 You can skip it: the Lucid store provisions and repairs its own tables as the app starts
 (`autoCreateTables` defaults to true; an ace command or a hand-built store does it on first
-use), so an upgrade that adds a column needs no app migration. The published migration
-delegates to the same `createAgentTables` helper, so the two schemas can never drift.
+use), so an upgrade that adds a column needs no app migration. The published migrations
+delegate to the same `createAgentTables` helper, so the two schemas can never drift.
 Only with `autoCreateTables: false` does an upgrade need a migration that calls
 `createAgentTables` again.
 
@@ -179,6 +184,7 @@ export default defineConfig({
 
 Requires `@adonisjs/redis` installed and configured unless you pass `client:` (a
 bring-your-own `RedisStreamClient`). Pair with `durable: true` for cross-instance resume.
+Under an `engine`, `durable: true` is refused at boot unless the engine is durable itself.
 
 No Redis? `tokenSinks.lucid()` keeps the frames in the app's SQL database instead
 (table `agent_stream_frame`, created with the other agent tables). Subscribers poll
@@ -206,9 +212,9 @@ Source: `packages/adonis/src/stores/factory.ts` (`tokenSinks`),
 
 ### Pattern 4 — a React chat with `@adonis-agora/agent/react`
 
-The React layer is `@dudousxd/nestjs-agent-react` re-exported (an optional peer — install it with
-`@ai-sdk/react` and `ai`), plus an `AgentProvider` that already sends the session cookie and
-shield's CSRF token. No controller, no fetch code:
+Agora owns the React layer inside `@adonis-agora/agent/react`. Install the optional
+`react`, `@ai-sdk/react` and `ai` peers for this entry. `AgentProvider` already sends the
+session cookie and shield's CSRF token. No Aviary package or release is required:
 
 ```tsx
 import { AgentProvider, useAgentChat } from '@adonis-agora/agent/react'
@@ -260,13 +266,66 @@ token sink any replica serves the resume. The native stream is unchanged.
 
 Source: `packages/adonis/docs/ag-ui.mdx`, `packages/adonis/src/ag-ui/`.
 
+### Pattern 6 — answer on WhatsApp / Telegram with `channels.handle()`
+
+```ts
+// start/routes.ts
+import { channels, evolutionApi } from '@adonis-agora/agent/channels'
+
+router.post(
+  '/webhooks/whatsapp',
+  channels.handle(
+    evolutionApi({ url, instance, apiKey, webhookToken }), // or whatsappCloud({…}) / telegram({…})
+    {
+      actor: (message) => actorForPhone(message.from), // null → not answered
+      thread: (actor, message) => threadFor(message.conversation), // null → new thread
+      onThreadCreated: (threadId, actor, message) => saveThread(message.conversation, threadId),
+    },
+  ),
+)
+```
+
+The handler verifies the webhook (token / HMAC / secret header), dedupes by provider message id,
+answers `200` at once and runs the turn in the background (`await handler.drain()` in tests).
+Replies are text-only (components → `fallbackText`), converted to the channel's markdown and split
+at its length limit. Media is downloaded and attached when `attachments` is configured (else the
+person is told why not). `ask` questions go out as numbered text, one at a time; the next messages
+answer them. State (message ids, questions in progress, relayed outcomes) lives in
+`agent_channel_state` via `lucidChannelStore()` when the agent store is Lucid, else memory —
+`store: redisChannelStore(redis)` otherwise on several replicas. Use
+`actionApprovalMode: 'independent'`: pending proposals go out as Confirm/Cancel buttons (or a text
+instruction in the `actionProposalText` vocabulary), and `actionProposalWorker: { onSettled:
+channels.onSettled }` relays outcomes that settle later. In blocking mode the channel can only say
+the approval must happen in the app. Exclude webhook routes from Shield's CSRF check.
+
+Source: `packages/adonis/docs/channels.mdx`, `packages/adonis/src/channels/`.
+
+## Component rendering entries
+
+Agora owns its catalog (`@adonis-agora/agent/genui`), browser rendering
+(`@adonis-agora/agent/react/genui`), AG-UI adapters and resumable upload client
+(`@adonis-agora/agent/react/media`). Protocol compatibility does not require installing
+Aviary packages.
+
+For static HTML, use `createReactComponentRegistry` and `createReactServerRenderer` from
+`@adonis-agora/agent/react/genui/server`; install matching `react` and `react-dom` peers.
+Keep this server entry out of browser bundles: it reads trusted filesystem stylesheets
+and imports ReactDOM's server renderer. HTML does not require a browser or AI SDK.
+PNG/PDF output takes a capture adapter; the optional Playwright implementation lives at
+`@adonis-agora/agent/react/genui/server/playwright` and needs `playwright-core`. A supplied
+browser remains caller-owned. Binary captures are attachments, not durable UI-frame props.
+
+Source: `packages/adonis/docs/authoring/component-rendering.mdx`,
+`packages/adonis/docs/react.mdx`.
+
 ## Common mistakes
 
 ### MEDIUM — restating history to the AG-UI route and expecting it to be read
 
 The route answers the LAST user message of `messages`; the thread's history is the one the server
 stored under `threadId`. Media parts must be inline (`source.type: 'data'`) and need
-`attachments:` configured — a `url` or `file` source is dropped with an `agora.warning`.
+`attachments:` configured — a `url` or a `file` source from another provider is dropped with an `agora.warning`.
+A `file` handle with `provider: 'agora'` naming an upload this agent staged is resolved for the caller instead.
 
 Source: `packages/adonis/docs/ag-ui.mdx`.
 

package/skills/agent-testing/SKILL.md

@@ -167,6 +167,28 @@ for await (const frame of sink.subscribe(runId)) {
 Source: `packages/adonis/docs/testing.mdx` ("Because the fakes are behavioral twins"
 note), `packages/adonis/src/in-process-sink.ts`.
 
+### Pattern 4 — verify presentation, replay and optional rendering locally
+
+Use Agora's own entries in tests; do not install or alias Aviary packages. Exercise
+class presentation through discovery, and functional presentation through `defineTool`
+and `ToolRegistry.invoke`. Verify unchanged domain output, authorization and denied
+preflight, completed preflight without execution, ordered emissions, and a throwing
+`present`/sink/reporter without repeating the domain write. A loop test should replay
+its journaled tool result and assert that presentation is not emitted or persisted twice.
+
+Test custom schema transformations with distinct `props` and `outputProps` through
+static and request-resolved component/show/tree tools; normalized props must remain
+unchanged in rendering and persisted history. For SSR, import
+`@adonis-agora/agent/react/genui/server`, provide trusted CSS/theme, and use a fake capture
+adapter to inspect every paginated row and escaped HTML without a browser. Real
+PNG/PDF tests can use the optional Playwright entry and a host Chromium executable;
+assert byte signatures and page/context cleanup while retaining the supplied browser.
+Keep binary captures out of persisted component frames.
+
+Source: `packages/adonis/test/tool-present.spec.ts`,
+`packages/adonis/test/emit-ui.spec.ts`, `packages/adonis/test/react-server.spec.ts`,
+`packages/adonis/test/react-playwright.browser.spec.ts`.
+
 ## Common mistakes
 
 ### MEDIUM — keeping mutable state in a FakeModelProvider script

package/skills/agent-tools/SKILL.md

@@ -59,7 +59,8 @@ export default class GetWeather extends ReadTool<Input, { tempC: number }> {
 }
 ```
 
-Prefer a function? `defineTool(options, execute)` returns a branded `{ spec, handler }`
+Prefer a function? `defineTool({ name, input, execute, present, ... })` or the existing
+`defineTool(options, execute)` returns a branded `{ spec, handler }`
 discovery picks up identically — or pass it straight to `defineConfig({ tools: [...] })`.
 
 ## Core patterns
@@ -109,8 +110,9 @@ An action's write and the checkpoint that records it are two writes: a worker th
 them re-runs the tool on recovery. Pass `ctx.idempotencyKey` (`<runId>:<toolCallId>`, the same for
 every execution of one call) on as the downstream idempotency key — a provider's
 `Idempotency-Key`, a unique column on the inserted row, the `id` of a workflow the tool starts — so
-the second attempt lands on the first. It is absent outside a turn (MCP, a direct
-`registry.invoke`), so fall back to a key of your own there.
+the second attempt lands on the first. Over MCP the server mints one per `tools/call`
+(alongside `toolCallId` and `pageContext: { channel: 'mcp' }`). It is absent on a direct
+`registry.invoke`, so fall back to a key of your own there.
 
 Source: `packages/adonis/src/spi/tool.ts` (`AiToolCtx.idempotencyKey`).
 
@@ -177,10 +179,12 @@ Source: `packages/adonis/docs/authoring/tools.mdx` ("Configuring the generator")
 
 ### Pattern 4 — a write reachable over MCP: `defineConfirmedTool`
 
-An `action` never reaches an MCP client (no approval channel, and Claude.ai/Desktop have no
+An `action` is off the MCP surface by default (`actions: 'refuse'` in `config/mcp.ts` —
+neither listed nor callable, since there is no approval channel, and Claude.ai/Desktop have no
 elicitation). For a write that must be callable there, put the gate inside the tool: the
 first call previews and returns a signed `confirmToken`; the same arguments plus
-`confirm: true` and the token commit.
+`confirm: true` and the token commit. (`actions: 'execute'` opts out and runs actions when
+called — the MCP client's own confirmation stands in for the loop's approval gate.)
 
 ```ts
 import { defineConfirmedTool, LucidConfirmTokenStore } from '@adonis-agora/agent'
@@ -209,6 +213,47 @@ arguments and expires (`ttlMs`, default 15 min).
 Source: `packages/adonis/docs/mcp.mdx` ("Writes with a human gate"),
 `packages/adonis/src/confirmed-tool.ts`.
 
+### Pattern 5 — present a domain result through the component catalog
+
+Keep `execute` returning domain data. An optional `present(output, ctx)` on a class or
+functional handler returns one component presentation, an array, or `undefined`. The
+registry emits presentations through `ctx.emitUi` and preserves the domain result for
+REST/MCP callers. Denied or failed execution does not present; presentation errors do
+not retry a successful write. Methods keep their receiver, including injected services.
+
+```ts
+import { defineTool } from '@adonis-agora/agent'
+import { table } from '@adonis-agora/agent/genui'
+import { z } from 'zod'
+
+export const listRecords = defineTool({
+  name: 'list_records',
+  description: 'List records visible to the current actor.',
+  input: z.object({ limit: z.number().int().min(1).max(100) }),
+  execute: async ({ limit }, ctx) => recordsFor(ctx.actor, limit),
+  present: async (records) => table({
+    columns: [{ key: 'name', label: 'Name' }],
+    rows: records,
+  }),
+})
+```
+
+`table` and `chart` present the builtin `DataTable` and `Chart` definitions: put them in the
+genui catalog (`BUILTIN_COMPONENTS` from `@adonis-agora/agent/genui/builtins`, or the two
+definitions) and register app renderers under those names. Builtins carry no visuals.
+Use `createComponent` for custom definitions and one `createComponentRegistry` per app
+or tenant. Input `props` may transform; if the transform changes shape or is not
+idempotent, declare `outputProps` to validate the normalized JSON persisted in frames.
+Do not send renderer functions or image/PDF bytes as props. Set `onPresentationError(error,
+{ toolName, toolCallId, runId, threadId })` in `defineConfig` — it is wired for turns
+and proposal executions (the loop/executor fill in the call, run and thread); omit it
+and the provider logs a warning on the app logger. Inside a tool,
+`ctx.onPresentationError` carries the same details. SSR and capture use optional server entries,
+separate from tool execution and browser chat hooks.
+
+Source: `packages/adonis/docs/authoring/component-rendering.mdx`,
+`packages/adonis/src/spi/tool.ts`, `packages/adonis/src/tool-result-presentation.ts`.
+
 ## Feature flags and per-user gates — `enabled`, `isEnabled()`, `canUse(actor)`
 
 ```ts
@@ -232,8 +277,8 @@ Source: `packages/adonis/docs/authoring/tools.mdx`, `packages/adonis/src/tool-fi
 ### CRITICAL — shipping a privileged tool without `roles`
 
 ```ts
-// Wrong — no roles → inherits defaultRoles, which is [] (open) by default: every actor,
-// an anonymous visitor included, is offered this tool.
+// Wrong — no roles → inherits defaultRoles, which is [] (open) by default: every actor
+// except A2A personal agents, an anonymous visitor included, is offered this tool.
 static tool = { name: 'refund_order', kind: 'action', description: '...', input }
 ```
 
@@ -245,10 +290,13 @@ static tool = { name: 'refund_order', kind: 'action', description: '...', input,
 Mechanism: `definitionsFor` filters the offered tool list through the role gate BEFORE
 each model turn, and `invoke` re-checks it. A tool with no `roles` takes `defaultRoles`;
 an empty list is no restriction (since 0.46 — before, it denied everyone; `emptyRoles: 'deny'`
-in the config, or `ClosedRolesPolicy`, keeps it closed). An `action` still parks on approval — but by default the
+in the config, or `ClosedRolesPolicy`, keeps it closed) — except for an actor with the
+`personal_agent` role (A2A personal agents): it reaches only tools that declare one of its
+roles, so a tool with no `roles` is out of its reach even when open by default. An `action` still parks on approval — but by default the
 requester approves, so for a public chat that is only a confirmation.
 Source: `packages/adonis/docs/governance/authorization.mdx`,
-`packages/adonis/src/tool-registry.ts` (`DefaultRolesPolicy.can`).
+`packages/adonis/src/tool-registry.ts` (`DefaultRolesPolicy.can`),
+`packages/adonis/src/a2a/gate.ts` (`personalAgentGate`).
 
 ### HIGH — trusting an id from the model's arguments instead of `ctx.actor`
 

package/dist/src/ag-ui/proposal-decision.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"proposal-decision.d.ts","sourceRoot":"","sources":["../../../src/ag-ui/proposal-decision.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAE3F,qGAAqG;AACrG,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;CAC3B,GAAG,SAAS,EAAE,CAmBd"}

package/dist/src/ag-ui/proposal-decision.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"proposal-decision.js","sourceRoot":"","sources":["../../../src/ag-ui/proposal-decision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAkB,MAAM,mCAAmC,CAAC;AAE3F,qGAAqG;AACrG,MAAM,UAAU,4BAA4B,CAAC,KAK5C;IACC,MAAM,SAAS,GAAG,GAAG,KAAK,CAAC,KAAK,oBAAoB,CAAC;IACrD,OAAO;QACL;YACE,IAAI,EAAE,aAAa;YACnB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,eAAe,EAAE,sBAAsB;SACxC;QACD;YACE,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,iCAAiC;YACvC,KAAK,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,EAAE;SAC9E;QACD,EAAE,IAAI,EAAE,oBAAoB,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE;QAC5D,EAAE,IAAI,EAAE,sBAAsB,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE;QAC9D,EAAE,IAAI,EAAE,kBAAkB,EAAE,SAAS,EAAE;QACvC,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;KACvE,CAAC;AACJ,CAAC"}