@adonis-agora/agent 0.60.1 → 0.62.0

package/dist/stubs/database/migrations/add_action_proposal_discovery.stub

@@ -0,0 +1,24 @@
+{{{
+  exports({ to: app.migrationsPath(`${new Date().getTime() + 1}_add_action_proposal_discovery.ts`) })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+import db from '@adonisjs/lucid/services/db'
+import { createAgentTables, LucidAgentStore } from '@adonis-agora/agent'
+
+/** Quiesce old writers before this upgrade; start discovery workers after it finishes. */
+export default class extends BaseSchema {
+  static disableTransactions = true
+
+  async up() {
+    const connection = db.connection(this.db.connectionName)
+    await createAgentTables(connection)
+    const store = new LucidAgentStore(connection, { autoCreateTables: false })
+    while (await store.backfillActionProposalDiscoveryIndex({ limit: 500 })) {
+      // Each batch preserves snapshots and audits; an interrupted upgrade can be resumed.
+    }
+  }
+
+  async down() {
+    throw new Error('Forward-only discovery upgrade: proposal history and work must be preserved')
+  }
+}

package/dist/stubs/database/migrations/add_action_proposal_runtime.stub

@@ -0,0 +1,19 @@
+{{{
+  exports({ to: app.migrationsPath(`${new Date().getTime() + 2}_add_action_proposal_runtime.ts`) })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+import db from '@adonisjs/lucid/services/db'
+import { createAgentTables } from '@adonis-agora/agent'
+
+/** Quiesce old writers before provisioning atomic outcome delivery and capability persistence. */
+export default class extends BaseSchema {
+  static disableTransactions = true
+
+  async up() {
+    await createAgentTables(db.connection(this.db.connectionName))
+  }
+
+  async down() {
+    throw new Error('Forward-only runtime upgrade: proposals, outcomes and history must be preserved')
+  }
+}

package/dist/stubs/database/migrations/create_agent_tables.stub

@@ -6,9 +6,9 @@ import db from '@adonisjs/lucid/services/db'
 import { createAgentTables, dropAgentTables } from '@adonis-agora/agent'
 
 /**
- * The nine tables for the @adonis-agora/agent \`lucid\` store: threads, messages, tool calls, token
+ * The ten tables for the @adonis-agora/agent \`lucid\` store: threads, messages, tool calls, token
  * usage, model pricing, the run lifecycle, the chat message queue, the spent confirm tokens, and the
- * frame buffer of the Lucid token sink (\`tokenSinks.lucid()\`) — plus their indexes.
+ * frame buffer of the Lucid token sink (\`tokenSinks.lucid()\`) — plus independent action proposals and their indexes.
  *
  * This migration DELEGATES to the library instead of reproducing its DDL. The schema belongs to the
  * library: \`LucidAgentStore\`, the pricing store and the governance read-model all decide together what
@@ -20,7 +20,7 @@ import { createAgentTables, dropAgentTables } from '@adonis-agora/agent'
  * existed purely to ALTER in the \`run_id\` columns this one had been written before.
  *
  * \`createAgentTables\` is idempotent (\`CREATE TABLE IF NOT EXISTS\`) and additive-only: it creates what
- * is missing and ALTERs the \`run_id\` columns into a database that predates run tracking. So it is safe
+ * is missing and ALTERs the \`run_id\` columns into a database that predates run tracking, plus approval metadata including resolved confirmation. So it is safe
  * against an empty database, against one the library already auto-created, and against one left over
  * from an older version — which is exactly the set of states a real app is in.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.60.1",
+  "version": "0.62.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",
@@ -76,6 +92,16 @@
       "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 +206,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 +233,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 +302,62 @@
     "zod": {
       "optional": true
     },
-    "@dudousxd/nestjs-agent-core": {
+    "@adonis-agora/media": {
       "optional": true
     },
-    "@dudousxd/nestjs-agent-react": {
+    "@ai-sdk/react": {
       "optional": true
     },
-    "@dudousxd/nestjs-media-client": {
+    "@json-render/react": {
       "optional": true
     },
-    "@adonis-agora/media": {
+    "@streamdown/code": {
+      "optional": true
+    },
+    "@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 +366,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

@@ -26,9 +26,11 @@ sources:
 # 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 +44,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 +78,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 ten 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):
 
 ```bash
 node ace migration:run
@@ -85,8 +89,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 +183,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 +211,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,6 +265,24 @@ token sink any replica serves the resume. The native stream is unchanged.
 
 Source: `packages/adonis/docs/ag-ui.mdx`, `packages/adonis/src/ag-ui/`.
 
+## 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

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,44 @@ 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,
+  }),
+})
+```
+
+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 +274,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 +287,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`