@adonis-agora/agent 0.25.2 → 0.25.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @adonis-agora/agent
 
+## 0.25.3
+
+### Patch Changes
+
+- [#82](https://github.com/DavideCarvalho/adonis-agora-agent/pull/82) [`59be4e9`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/59be4e9943b47d79ce5f006c1d24b9b39e052f84) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Add TanStack Intent agent skills. Both packages now ship a `skills/` directory
+  (five skills under @adonis-agora/agent: setup, tools, governance, personas &
+  multi-agent delegation, offline testing; one under @adonis-agora/agent-dashboard:
+  the governance console client) that coding agents can load as structured,
+  verified documentation. The directories are included in each package's `files`
+  allowlist, and `@tanstack/intent` is added as a devDependency so CI can enforce
+  skill validity via `intent validate`.
+
 ## 0.25.2
 
 ### Patch Changes

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.25.2";
+export declare const VERSION = "0.25.3";
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/src/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.25.2';
+export const VERSION = '0.25.3';
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -112,7 +112,8 @@
   "files": [
     "dist/",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "skills"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -184,6 +185,7 @@
     "@adonisjs/core": "7.4.0",
     "@adonisjs/lucid": "22.4.2",
     "@qdrant/js-client-rest": "1.19.0",
+    "@tanstack/intent": "^0.3.2",
     "@types/node": "22.20.1",
     "@types/react": "19.2.18",
     "ai": "7.0.59",
@@ -208,6 +210,7 @@
     "governance",
     "ai-sdk",
     "durable",
+    "tanstack-intent",
     "agora"
   ],
   "scripts": {

package/skills/agent-governance/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: agent-governance
+description: >-
+  Lock down @adonis-agora/agent: the ActorResolver identity seam (AuthActorResolver over
+  ctx.auth.user with toActor mapper, HeaderActorResolver x-actor-id/x-actor-role behind a
+  gateway, UnconfiguredActorResolver throwing default), DefaultToolAuthorizer role
+  intersection with the offered-tools + invoke-time double check, object-level ownership
+  via evaluateOwnership (404 for unknown ids), governanceAuthorize mounting semantics for
+  /agent/governance/* (404 without it) and the dashboard mount refusals,
+  evaluateGovernanceGate fail-closed behavior, and GET /agent/approvals/mine exemption.
+  Use for "tool forbidden", "governance routes 404", "dashboard won't mount", "IDOR /
+  cross-actor access", "swap roles for ability checks".
+metadata:
+  type: core
+  library: "@adonis-agora/agent"
+  library_version: "0.25.2"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/governance/authorization.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/governance/dashboard.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/governance-gate.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/ownership.ts"
+---
+
+# Governance: identity, authorization, ownership
+
+Authorization in `@adonis-agora/agent` is fail-closed at three layers: **who is calling**
+(an `ActorResolver` that never fabricates an identity), **what they may do** (a
+`RolesPolicy` checked twice — before the model sees a tool and again at invoke time),
+and **which records they may address** (object-level ownership on every run/thread route).
+
+## Setup
+
+Wire identity once; everything downstream keys off it:
+
+```ts
+// config/agent.ts
+import { defineConfig, AuthActorResolver } from '@adonis-agora/agent'
+
+export default defineConfig({
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+  // Reads ctx.auth.user (populated by @adonisjs/auth). Throws when unauthenticated —
+  // no identity is ever invented. Map non-standard user shapes with toActor.
+  actorResolver: new AuthActorResolver({
+    toActor: (user) => ({
+      id: String(user.id),
+      roles: user.roleNames,     // e.g. pulled from a relation
+      tenantRef: user.tenantId,
+    }),
+  }),
+  defaultRoles: ['STAFF'],       // roles a tool requires when it declares none
+})
+```
+
+## Core patterns
+
+### Pattern 1 — swap role checks for ability checks
+
+`roles` and `ability` share one seam. The default policy intersects roles; an
+ability-aware policy (the `@adonis-agora/authz` Bouncer adapter, `authzToolAuthorizer`)
+consults each tool's `ability` instead — tenant-scoped and fail-closed. Swap only the
+binding; tools keep both annotations:
+
+```ts
+// config/agent.ts
+import { defineConfig } from '@adonis-agora/agent'
+import { authzToolAuthorizer } from '@adonis-agora/agent/authz'
+
+export default defineConfig({
+  // ...
+  authorizer: authzToolAuthorizer, // alias: rolesPolicy — one seam, both filter layers follow
+})
+```
+
+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.
+
+Source: `packages/adonis/docs/governance/authorization.mdx` ("Ability-aware
+authorization"), `packages/adonis/src/authorizer.ts`.
+
+### Pattern 2 — mount the governance read-model with `governanceAuthorize`
+
+The cross-actor `/agent/governance/*` read routes exist ONLY when a gate is configured.
+Omit it and every one of those paths answers 404 — by design, so an ungated read-model of
+every actor's spend/threads/approvals can never be served by accident:
+
+```ts
+// config/agent.ts — typically an ADMIN check; runs AFTER the actor resolves.
+export default defineConfig({
+  // ...
+  governanceAuthorize: (actor, _ctx) => actor.roles?.includes('ADMIN') ?? false,
+})
+```
+
+`evaluateGovernanceGate` applies it fail-closed: falsy → 403, thrown → 403 (message shown
+only outside production). The SAME predicate feeds object-level ownership's `privileged`
+flag, and the dashboard console refuses to mount without it.
+
+Source: `packages/adonis/docs/governance/authorization.mdx` ("Governance route
+authorization"), `packages/adonis/src/governance-gate.ts`.
+
+### Pattern 3 — unit-test your gates router-free
+
+Both decision cores are exported pure functions, so you can test them without booting an
+app:
+
+```ts
+import { evaluateOwnership, evaluateGovernanceGate } from '@adonis-agora/agent'
+
+evaluateOwnership('u_1', 'u_1', false) // → { ok: true,  status: 200 }  owner
+evaluateOwnership('u_2', 'u_1', false) // → { ok: false, status: 403 }  not owner
+evaluateOwnership('u_2', null, false)  // → { ok: false, status: 404 }  unknown id
+evaluateOwnership('u_2', 'u_1', true)  // → { ok: true,  status: 200 }  privileged
+
+const verdict = await evaluateGovernanceGate(actor, ctx, config.governanceAuthorize, !app.inProduction)
+if (!verdict.ok) return ctx.response.status(verdict.status).json({ error: verdict.error })
+```
+
+Unknown ids deliberately reply 404, never 403, so a response never confirms to a caller
+that an id they don't own exists.
+
+Source: `packages/adonis/docs/governance/authorization.mdx` ("Object-level ownership"),
+`packages/adonis/src/ownership.ts`.
+
+## Common mistakes
+
+### CRITICAL — assuming `HeaderActorResolver` is production-safe
+
+```ts
+// Wrong — anyone can send x-actor-id: u_admin and become admin unless a gateway strips these.
+actorResolver: new HeaderActorResolver()
+```
+
+```ts
+// Correct — read a VERIFIED principal in production; headers are for dev/gateway use only.
+actorResolver: new AuthActorResolver()
+```
+
+Mechanism: `HeaderActorResolver` trusts client-sent `x-actor-id` / `x-actor-role` /
+`x-tenant-ref`; it is safe only behind a gateway that strips and re-sets them from an
+authenticated principal. It does throw when `x-actor-id` is missing, but any caller who
+sets the header IS that actor.
+Source: `packages/adonis/src/actor-resolver.ts` (`HeaderActorResolver` security note),
+`packages/adonis/docs/governance/authorization.mdx`.
+
+### HIGH — expecting `/agent/governance/*` to exist after configuring only `governanceQueries`
+
+```ts
+// Wrong — read-model resolves, but no gate → the 11 governance routes are NEVER mounted (all 404).
+export default defineConfig({ store: 'lucid', stores: { lucid: stores.lucid() } })
+```
+
+```ts
+// Correct — set the gate to mount them (gated); or explicitly opt into open reads.
+export default defineConfig({
+  ...,
+  governanceAuthorize: (actor) => actor.roles?.includes('ADMIN') ?? false,
+  // governanceAuthorize: () => true, // deliberate legacy behaviour: ANY authenticated actor reads
+})
+```
+
+Mechanism: mounting is conditional on the gate because the data is cross-actor; a boot
+warning names both ways forward when the read-model resolved without a gate. Note
+`GET /agent/approvals/mine` is exempt — always mounted when the read-model resolves, and
+always scoped to the calling actor.
+Source: `packages/adonis/src/define_config.ts` (`AgentConfig.governanceAuthorize`),
+`packages/adonis/docs/streaming-and-http.mdx` ("Five optional surfaces").
+
+### HIGH — treating `dashboard.authorize` as the dashboard's data gate
+
+```ts
+// Wrong — authorize gates only the SPA shell; panels still 403/404 without governanceAuthorize.
+dashboard: { enabled: true, authorize: (actor) => actor.roles?.includes('ADMIN') ?? false }
+```
+
+```ts
+// Correct — one predicate shape on BOTH knobs: shell gate + data gate.
+governanceAuthorize: (actor) => actor.roles?.includes('ADMIN') ?? false,
+dashboard: { enabled: true, authorize: (actor) => actor.roles?.includes('ADMIN') ?? false },
+```
+
+Mechanism: the console is a pure consumer of `/agent/governance/*`; `authorize` decides
+who may load the shell while `governanceAuthorize` decides whether the console mounts at
+all and whether its data routes answer. With no gate the provider logs a boot warning and
+refuses to mount rather than serve seven dead panels.
+Source: `packages/adonis/src/dashboard/define_config.ts` (`decideDashboardMount`,
+`NO_GOVERNANCE_GATE_WARNING`).
+
+### MEDIUM — giving a per-agent resolver a different identity than the global one
+
+```ts
+// Wrong — webhook agents resolve actor 'body:svc-1'; the global resolver would say 'user_9'.
+agents: [{ name: 'webhook', actorResolver: new BodyActorResolver() }]
+```
+
+```ts
+// Correct — a per-agent resolver must yield an id the GLOBAL resolver could also produce.
+agents: [
+  {
+    name: 'webhook',
+    actorResolver: new AuthActorResolver({ toActor: mapServicePrincipal }), // same id space
+  },
+]
+```
+
+Mechanism: the override applies ONLY to `POST /agent/chat`; stream re-attach, cancel,
+approve/reject, threads, quota, and all governance routes resolve the GLOBAL resolver —
+a mismatched `actor.id` means the caller starts a run it cannot stream, cancel, or
+approve (ownership compares ids).
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` ("The override applies
+to POST /agent/chat only").
+
+### MEDIUM — designing a client around a thrown gate's message
+
+```ts
+// Wrong — reading error.message from a 403 to branch UI logic; prod never carries it.
+if (err.message.includes('missing tenant')) showTenantPicker()
+```
+
+```ts
+// Correct — treat 403 as opaque; debug details exist only outside production.
+if (err.status === 403) showForbidden() // body is exactly { "error": "forbidden" } in prod
+```
+
+Mechanism: `evaluateGovernanceGate` passes the thrown message through only when `debug`
+is true (the provider passes `!app.inProduction`); in production the body is the generic
+string, because authorization predicates routinely throw with sensitive detail.
+Source: `packages/adonis/src/governance-gate.ts`, `packages/adonis/docs/governance/authorization.mdx`
+("A thrown message never reaches production clients").
+
+See also: `agent-setup/SKILL.md` — wiring `AuthActorResolver` at setup time;
+`agent-console-client/SKILL.md` — how the console consumes these gated routes.

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

@@ -0,0 +1,220 @@
+---
+name: agent-personas-agents
+description: >-
+  Shape @adonis-agora/agent behavior per request: personas (Persona { id, label,
+  systemPrompt string | PromptBuilder, allowedTools }, defaultPersona, the
+  /agent/threads/personas/catalog route), named agents (agents: AgentDefinition[] with
+  tools/maxSteps/actorResolver overrides), delegatesTo multi-agent delegation via
+  synthesized ask_<target> agent-kind tools and DelegateEdge { agent, roles, ability },
+  HITL approval flow over POST /agent/tool-call/approve|reject with pending_approval
+  status, maxSteps budgeting, and PromptContext/basePrompt composition. Use for
+  "persona picker", "orchestrator delegates to specialists", "ask_researcher denied",
+  "action tool hangs waiting for approval", "prompt builder".
+metadata:
+  type: core
+  library: "@adonis-agora/agent"
+  library_version: "0.25.2"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/authoring/personas-and-agents.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/streaming-and-http.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/types.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/agent-loop.ts"
+---
+
+# Personas, named agents & delegation
+
+The default setup is one agent. Two features extend it: **personas** reshape a single
+agent per request (prompt + optional tool allow-list), and **named agents** with
+`delegatesTo` turn one assistant into a small team that hands work around through
+synthesized `ask_<target>` tools.
+
+## Setup
+
+Personas on the implicit default agent; the caller selects one via `POST /agent/chat`'s
+`persona` field, and it pins to the thread:
+
+```ts
+// config/agent.ts
+export default defineConfig({
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+  store: 'lucid',
+  stores: { lucid: stores.lucid() },
+  actorResolver: new AuthActorResolver(),
+  defaultAgent: {
+    systemPrompt: 'You are the assistant for our store.',
+    defaultPersona: 'shopper',
+    personas: [
+      {
+        id: 'shopper',
+        label: 'Shopping assistant',
+        systemPrompt: 'Help the customer find and track products. Be concise.',
+        allowedTools: ['getOrder', 'searchProducts'],
+      },
+      {
+        id: 'support',
+        label: 'Support agent',
+        systemPrompt: 'Help resolve issues. You may issue refunds with approval.',
+        allowedTools: ['getOrder', 'issueRefund'],
+      },
+    ],
+  },
+})
+```
+
+A persona's `systemPrompt` resolves WITH the agent's base prompt available as
+`basePrompt`, so it can wrap rather than discard; it may be a `PromptBuilder`
+(`(ctx: PromptContext) => string | Promise<string>`) composed from actor/persona/
+pageContext. Render a picker from `GET /agent/threads/personas/catalog`.
+
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx`.
+
+## Core patterns
+
+### Pattern 1 — orchestrator delegating to named specialists
+
+Each `delegatesTo` edge auto-registers an `agent`-kind tool named `ask_<target>`
+(non-alphanumerics become underscores) whose input is `{ task }`. You never write its
+handler — the loop runs the target and feeds the answer back:
+
+```ts
+// config/agent.ts
+export default defineConfig({
+  // ...
+  defaultAgent: {
+    name: 'orchestrator',
+    systemPrompt: 'You coordinate specialists. Delegate work, then summarize.',
+    delegatesTo: [
+      { agent: 'researcher', roles: ['ANALYST', 'ADMIN'] },   // role-based gate
+      { agent: 'billing', ability: 'agent.delegate.billing' }, // ability-based gate (authz)
+    ],
+  },
+  agents: [
+    { name: 'researcher', systemPrompt: 'You research questions using read tools.', tools: ['searchDocs'] },
+    { name: 'billing', systemPrompt: 'You handle billing. Refunds require approval.', tools: ['getInvoice', 'issueRefund'] },
+  ],
+})
+```
+
+When the target has a flat-string base prompt, it is appended to the delegate tool's
+generated description so the orchestrator's model knows what the specialist is for.
+
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` ("Multi-agent
+delegation", "How a delegate tool is named").
+
+### Pattern 2 — approving a paused `action` tool (HITL)
+
+An `action` call records `pending_approval` and suspends the run; the client reads the
+pending `toolCallId` from thread detail, then decides. The decision is scoped to one
+`(runId, toolCallId)` pair, so one run can never approve another's call:
+
+```bash
+curl http://localhost:3333/agent/tool-call/approve \
+  -H 'content-type: application/json' \
+  -d '{"runId":"<runId>","toolCallId":"<toolCallId>"}'
+
+curl http://localhost:3333/agent/tool-call/reject \
+  -H 'content-type: application/json' \
+  -d '{"runId":"<runId>","toolCallId":"<toolCallId>","reason":"not this account"}'
+```
+
+On reject, the reason is fed back to the model and the turn continues. A UI can also poll
+`GET /agent/approvals/mine` — the calling actor's own pending approvals.
+
+Source: `packages/adonis/docs/streaming-and-http.mdx` ("Human-in-the-loop").
+
+### Pattern 3 — cap runaway loops with `maxSteps`
+
+`maxSteps` bounds model↔tool iterations per turn (default 8). Give a shallow specialist a
+smaller budget than the orchestrator:
+
+```ts
+agents: [
+  { name: 'summarizer', systemPrompt: 'Summarize in one pass.', maxSteps: 2 },
+]
+```
+
+Source: `packages/adonis/src/types.ts` (`AgentDefinition.maxSteps`),
+`packages/adonis/src/agent-loop.ts` (`const maxSteps = deps.maxSteps ?? 8`).
+
+## Common mistakes
+
+### HIGH — bare-string `delegatesTo` edges under non-admin callers or authz
+
+```ts
+// Wrong — declares NO roles and NO ability.
+delegatesTo: ['researcher']
+```
+
+```ts
+// Correct — say who may delegate.
+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 is ADMIN-only, and under the authz
+Bouncer adapter a spec without `ability` is denied outright — the edge becomes uncalled
+for everyone but admins.
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` ("Authorizing a
+delegation"), `packages/adonis/src/types.ts` (`DelegateEdge`).
+
+### MEDIUM — debugging "the orchestrator ignored the specialist" as a prompt problem
+
+```ts
+// Symptom — the model apologizes and answers alone; no visible error anywhere.
+// The delegation was DENIED and recorded failed:
+//   { toolName: 'ask_researcher', status: 'failed', error: 'Tool "ask_researcher" is not allowed...' }
+```
+
+```ts
+// Correct move — check the tool-call feed (governance read-model / dashboard Tool calls panel).
+// A denied delegation persists as failed — never auto_executed — and the error text goes back
+// to the model as a tool result, which it paraphrases away silently.
+```
+
+Mechanism: the loop re-applies all three gates before delegating (offered-tools check,
+role check, input validation); on denial it records the call `failed`, skips
+`agent.delegated`, and pushes `{ output: null, error }` into the transcript — so the run
+completes normally while the delegation quietly never happened.
+Source: `packages/adonis/src/agent-loop.ts` (agent-kind branch), `packages/adonis/docs/
+authoring/personas-and-agents.mdx` ("A denied delegation is recorded, not retried").
+
+### MEDIUM — expecting a delegated sub-agent's action tools to wait for a human
+
+```ts
+// Wrong assumption — nested researcher asks for approval; the run should pause.
+defaultAgent: { delegatesTo: [{ agent: 'researcher' }] }
+agents: [{ name: 'researcher', tools: ['issueRefund' /* action */] }]
+```
+
+```ts
+// Correct — keep human-approval actions on the TOP-LEVEL agent only.
+agents: [
+  { name: 'researcher', tools: ['searchDocs', 'getInvoice'] }, // read tools only
+]
+```
+
+Mechanism: under the inline runner a sub-agent runs as a nested in-process loop with no
+human attached, so its `action` tools are AUTO-DECLINED rather than left hanging; under
+the durable runner the same delegation maps to a tracked child workflow instead.
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` (final paragraph).
+
+### LOW — using wall-clock time or randomness inside a PromptBuilder
+
+```ts
+// Wrong — non-deterministic prompt; a durable replay recomputes a DIFFERENT prompt.
+const builder: PromptBuilder = async (ctx) => `${ctx.basePrompt}\nNow: ${new Date().toISOString()}`
+```
+
+```ts
+// Correct — derive from stable inputs (actor/persona/pageContext) resolved once per turn.
+const builder: PromptBuilder = (ctx) => `${ctx.basePrompt}\nAssist ${ctx.actor.id} in ${ctx.actor.tenantRef ?? 'the org'}.`
+```
+
+Mechanism: the loop resolves the effective system prompt exactly once per turn from
+stable context; injecting entropy breaks replay determinism under the durable runner.
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` (replay-safety note),
+`packages/adonis/src/agent-loop.ts` (`resolveSystemPrompt`).
+
+See also: `agent-governance/SKILL.md` — the policy behind `roles`/`ability` gates;
+`agent-testing/SKILL.md` — scripting multi-turn runs offline.

package/skills/agent-setup/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: agent-setup
+description: >-
+  Set up @adonis-agora/agent in an AdonisJS app: node ace configure @adonis-agora/agent,
+  defineConfig in config/agent.ts (model via aiSdkModel from @adonis-agora/agent/ai-sdk,
+  stores.lucid()/stores.memory(), quotas.ledger/quotas.memory, pricingStores +
+  seedModelPrices + estimateCost, tokenSinks.redis multi-replica SSE sink,
+  AuthActorResolver identity seam), auto-created agent tables vs the published migration,
+  the cost fold (null vs $0.00), and route mounting under config path. Use for "set up
+  the agent", "config/agent.ts", "agent tables / migration", "costUsd is null or zero",
+  "quota not enforced", "401 on every agent route".
+metadata:
+  type: core
+  library: "@adonis-agora/agent"
+  library_version: "0.25.2"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/getting-started.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/config-reference.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/define_config.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/stores/factory.ts"
+---
+
+# 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.
+
+## Setup
+
+Install and let the configure hook wire everything:
+
+```bash
+pnpm add @adonis-agora/agent
+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:
+
+```bash
+pnpm add ai zod @ai-sdk/openai
+```
+
+```ts
+// config/agent.ts
+import { defineConfig, stores, AuthActorResolver } from '@adonis-agora/agent'
+import { aiSdkModel } from '@adonis-agora/agent/ai-sdk'
+import { openai } from '@ai-sdk/openai'
+
+export default defineConfig({
+  // A lazy thunk keeps the provider SDK peer imported only at boot.
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+
+  store: 'lucid',
+  stores: {
+    memory: stores.memory(), // single-process; tests and scratch apps
+    lucid: stores.lucid(),   // persists to SQL via @adonisjs/lucid
+  },
+
+  // Identity seam — fail-closed. Without a resolver every request throws → 401.
+  actorResolver: new AuthActorResolver(),
+
+  defaultAgent: {
+    systemPrompt: 'You are a helpful assistant for our app.',
+  },
+})
+```
+
+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):
+
+```bash
+node ace migration:run
+```
+
+You can skip it: the Lucid store provisions its own tables on first use
+(`autoCreateTables` defaults to true), and the published migration delegates to the same
+`createAgentTables` helper, so the two schemas can never drift.
+
+Source: `packages/adonis/docs/getting-started.mdx`,
+`packages/adonis/docs/stores/lucid.mdx`.
+
+## Core patterns
+
+### Pattern 1 — enforce a daily spend budget with `quotas.ledger`
+
+Quotas are **opt-in**: omitting `quota` disables budgeting entirely (fail-open).
+Configuring one makes the gate fail-closed — `check()` runs before the first model call
+and over-budget turns throw `QuotaExceededError` before any tokens are spent.
+
+```ts
+import { defineConfig, quotas } from '@adonis-agora/agent'
+
+export default defineConfig({
+  // ...
+  quota: quotas.ledger({ limitTokens: 1_000_000 }), // enforced off the persisted usage ledger
+})
+```
+
+`quotas.memory({ limitTokens })` is the single-process variant for tests. The `day`
+(`YYYY-MM-DD`, UTC) is stamped once by the runner, so day-bucketing stays deterministic
+under durable replay.
+
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx`.
+
+### Pattern 2 — price turns with a `pricingStore` + `seedModelPrices`
+
+With a Lucid main store, pricing mirrors the same connection automatically (table
+auto-created) — no extra config. Cost per turn resolves in order: provider-reported
+(a gateway) wins, else an estimate from the current price rows fetched once per run,
+else `null` — never a fabricated `0`. Seed prices once (e.g. from an Ace command):
+
+```ts
+import db from '@adonisjs/lucid/services/db'
+import { seedModelPrices, LucidPricingStore } from '@adonis-agora/agent'
+
+const pricing = new LucidPricingStore(db.connection())
+await seedModelPrices(pricing, [
+  {
+    modelId: 'gpt-4o-mini',
+    inputPricePer1m: 0.15,
+    outputPricePer1m: 0.6,
+    cacheWritePricePer1m: 0.19, // optional — falls back to the input rate
+    cacheReadPricePer1m: 0.015, // optional — falls back to the input rate
+  },
+])
+```
+
+Cache tokens are subsets of `inputTokens`, subtracted before the input rate applies.
+Rollups (`spendByModel`/`spendByActor`) are sums, so an unpriced row contributes `$0.00`
+even though the ledger row keeps `cost_usd: null` — if a total looks implausibly low,
+check the pricing table first.
+
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx`,
+`packages/adonis/src/spi/pricing-store.ts` (`seedModelPrices`, `estimateCost`).
+
+### Pattern 3 — multi-replica SSE with `tokenSinks.redis`
+
+The default sink buffers each run's stream in process memory, which is single-replica: a
+run started on pod A can only be re-attached on pod A. Switching sinks keeps the whole
+SSE envelope identical.
+
+```ts
+import { defineConfig, tokenSinks } from '@adonis-agora/agent'
+
+export default defineConfig({
+  // ...
+  sink: tokenSinks.redis({ ttlSeconds: 3600 }), // replay keys self-expire (default 1h)
+})
+```
+
+Requires `@adonisjs/redis` installed and configured unless you pass `client:` (a
+bring-your-own `RedisStreamClient`). Pair with `durable: true` for cross-instance resume.
+
+Source: `packages/adonis/src/stores/factory.ts` (`tokenSinks`),
+`packages/adonis/docs/streaming-and-http.mdx` ("Single-replica by default" callout).
+
+## Common mistakes
+
+### HIGH — omitting `actorResolver` and shipping 401s everywhere
+
+```ts
+// Wrong — UnconfiguredActorResolver THROWS on every request; all routes answer 401.
+export default defineConfig({ model: () => aiSdkModel(openai('gpt-4o-mini')) })
+```
+
+```ts
+// Correct — read the authenticated principal; no identity is ever fabricated.
+import { AuthActorResolver } from '@adonis-agora/agent'
+export default defineConfig({
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+  actorResolver: new AuthActorResolver(),
+})
+```
+
+Mechanism: the provider installs `UnconfiguredActorResolver` by default, whose
+`resolve()` unconditionally throws rather than invent a caller — the route replies 401
+before the model ever runs.
+Source: `packages/adonis/src/actor-resolver.ts` (`UnconfiguredActorResolver`),
+`packages/adonis/docs/governance/authorization.mdx` ("No resolver, no service").
+
+### MEDIUM — expecting quota enforcement after configuring only a store
+
+```ts
+// Wrong — no `quota` key means budgets are DISABLED (fail-open), even with a ledger full of usage.
+export default defineConfig({ model, store: 'lucid', stores: { lucid: stores.lucid() } })
+```
+
+```ts
+// Correct — opt in; the check then runs fail-closed before the first model call.
+export default defineConfig({
+  ...,
+  quota: quotas.ledger({ limitTokens: 500_000 }),
+})
+```
+
+Mechanism: the loop skips both `check` and `bump` entirely when `deps.quota` is
+undefined — there is no implicit limit.
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx` ("Quota is opt-in, and off
+means open"), `packages/adonis/src/agent-loop.ts` (`if (deps.quota !== undefined)`).
+
+### HIGH — incrementing counters in a custom QuotaStore's `bump`
+
+```ts
+// Wrong — double-counts every turn when paired with the persisted usage ledger.
+const store: QuotaStore = {
+  async check(actorRef, day) { /* read my counter */ },
+  async bump(actorRef, day, tokens) { await redis.incrBy(key, tokens) },
+}
+```
+
+```ts
+// Correct — a ledger-backed store leaves bump empty: recordUsage already wrote the tokens.
+class LedgerQuota implements QuotaStore {
+  async check(actorRef: string, day: string) { /* sum agent_token_usage */ }
+  async bump(): Promise<void> {} // deliberate no-op — the ledger is the source of truth
+}
+```
+
+Mechanism: `store.recordUsage(...)` has already persisted each turn's tokens;
+`quotas.ledger.check` reads that ledger, so adding again in `bump` counts each turn twice.
+Only a store keeping its OWN tally (`quotas.memory`, a bespoke Redis counter) should add.
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx` ("`bump` is a notification,
+not necessarily an increment"), `packages/adonis/src/stores/ledger-quota.ts`.
+
+### MEDIUM — reading `$0.00` rollups as "this model is free"
+
+```ts
+// Wrong — no prices seeded: usage rows persist costUsd null, but spendByModel sums them as 0.
+await client.spendByModel({ fromDay: '2026-01-01', toDay: '2026-01-31' })
+```
+
+```ts
+// Correct — seed current prices so estimates fold into costUsd.
+await seedModelPrices(pricingStore, [{ modelId: 'gpt-4o-mini', inputPricePer1m: 0.15, outputPricePer1m: 0.6 }])
+```
+
+Mechanism: an unpriced turn is deliberately `null` ("unknown") in the ledger, but SUM
+rollups cannot preserve null — every unpriced row adds `$0.00`, which reads exactly like
+a free model. Per-run/per-usage rows keep their nulls.
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx` ("`null` in the ledger,
+`0` in the rollups").
+
+### MEDIUM — replacing the allowed attachment content types instead of extending
+
+```ts
+// Wrong — REPLACES the default list: png/jpeg/pdf/csv now get 415.
+attachmentAllowedContentTypes: ['application/json']
+```
+
+```ts
+// Types match EXACTLY (no wildcards); spread the defaults you still want.
+attachmentAllowedContentTypes: [
+  'image/png', 'image/jpeg', 'image/gif', 'image/webp',
+  'application/pdf', 'text/plain', 'text/csv',
+  'text/markdown', // your addition
+],
+```
+
+Mechanism: passing `attachmentAllowedContentTypes` replaces the default list rather than
+merging, and matching is exact — no `text/*` prefix rule — so anything absent is rejected
+with 415.
+Source: `packages/adonis/src/define_config.ts` (`AgentConfig.attachmentAllowedContentTypes`).
+
+See also: `agent-tools/SKILL.md` — registering tools the model can actually call;
+`agent-governance/SKILL.md` — what `AuthActorResolver` feeds into.

package/skills/agent-testing/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: agent-testing
+description: >-
+  Test @adonis-agora/agent offline: FakeModelProvider with a pure FakeScript
+  (args, turnIndex) and echoScript, the in-memory SPI doubles from
+  @adonis-agora/agent/testing (InMemoryAgentStore, InMemoryTokenStreamSink.subscribe,
+  InMemoryQuotaStore, InMemoryPricingStore, InMemoryGovernanceQueries,
+  InMemoryActorDirectory, InMemoryAttachmentStagingStore, FakeEmbeddingProvider,
+  FakeReranker, inMemoryRetriever), driving runAgentLoop directly with the
+  step/awaitApproval/openSink hooks seam, or AgentDepsFactory + InlineAgentRunner, and
+  asserting on typed StreamFrames. Use for "test the agent without an API key",
+  "script a tool-call turn", "assert streamed text", "HITL approve in tests".
+metadata:
+  type: core
+  library: "@adonis-agora/agent"
+  library_version: "0.25.2"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/testing.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/testing/index.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/testing/fake-model-provider.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/agent-loop.ts"
+---
+
+# Testing @adonis-agora/agent offline
+
+Everything the agent depends on is a seam, so a test can run a full turn — model call,
+tool execution, governance, cost accounting — with **no API key and no database**. The
+in-memory doubles implement the SAME SPIs as the production adapters, so a green test
+exercises the real loop code paths.
+
+## Setup
+
+A minimal turn through the full loop, straight from the testing kit:
+
+```ts
+import {
+  runAgentLoop,
+  ToolRegistry,
+  DefaultRolesPolicy,
+} from '@adonis-agora/agent'
+import {
+  FakeModelProvider,
+  echoScript,
+  InMemoryAgentStore,
+  InMemoryTokenStreamSink,
+} from '@adonis-agora/agent/testing'
+
+const sink = new InMemoryTokenStreamSink()
+const { text } = await runAgentLoop(
+  {
+    model: new FakeModelProvider(echoScript('hi there')),
+    store: new InMemoryAgentStore(),
+    registry: new ToolRegistry(),
+    rolesPolicy: new DefaultRolesPolicy(),
+    day: '2026-07-21',
+    systemPrompt: 'You are a helpful assistant.',
+  },
+  { threadId: 'thread-1', actor: { id: 'user-1', roles: ['USER'] }, userText: 'hi' },
+  {
+    runId: crypto.randomUUID(),
+    openSink: () => sink.open('run-1'),
+    awaitApproval: async () => 'approve',
+    step: (_name, fn) => fn(),
+  },
+)
+```
+
+`hooks.step(name, fn)` is the checkpoint seam: inline it just calls `fn`; the durable
+runner memoizes each named step. `hooks.awaitApproval` is where a HITL decision comes
+from — return `{ approved: true }` (or a bare `'approve'`) to auto-approve in tests.
+
+Source: `packages/adonis/README.md` ("Framework-agnostic core"),
+`packages/adonis/src/agent-loop.ts` (`AgentLoopHooks`).
+
+## Core patterns
+
+### Pattern 1 — script a tool-call round-trip
+
+`FakeModelProvider` takes a script — a pure function of `(args, turnIndex)`. `turnIndex`
+counts assistant turns already in history, so there is no internal counter to reset:
+
+```ts
+import { FakeModelProvider } from '@adonis-agora/agent/testing'
+
+const model = new FakeModelProvider((args, turnIndex) => {
+  if (turnIndex === 0) {
+    // first turn: ask to call a tool
+    return { text: 'Let me check that.', toolCall: { name: 'getWeather', input: { city: 'Lisbon' } } }
+  }
+  // second turn: finish with the tool result in hand
+  return { text: 'It is 21°C in Lisbon.' }
+})
+```
+
+A scripted turn may also report `costUsd`, exactly as a gateway provider would, to
+exercise the cost fold.
+
+Source: `packages/adonis/docs/testing.mdx` ("The fake model"),
+`packages/adonis/src/testing/fake-model-provider.ts`.
+
+### Pattern 2 — run through the runner like production does
+
+`AgentDepsFactory` + `InlineAgentRunner` is the same composition the provider builds at
+boot, so the test covers run lifecycle persistence, not just the loop:
+
+```ts
+import {
+  AgentDepsFactory,
+  AgentRegistry,
+  ToolRegistry,
+  DefaultToolAuthorizer,
+  InlineAgentRunner,
+} from '@adonis-agora/agent'
+import {
+  FakeModelProvider,
+  echoScript,
+  InMemoryAgentStore,
+  InMemoryTokenStreamSink,
+} from '@adonis-agora/agent/testing'
+
+const store = new InMemoryAgentStore()
+const sink = new InMemoryTokenStreamSink()
+const registry = new ToolRegistry()
+const agents = new AgentRegistry()
+agents.register({ name: 'default' })
+
+const factory = new AgentDepsFactory({
+  model: new FakeModelProvider(echoScript('hello')),
+  store,
+  sink,
+  rolesPolicy: new DefaultToolAuthorizer(['ADMIN']),
+  registry,
+  agents,
+})
+
+const runner = new InlineAgentRunner(factory, store)
+const { runId } = await runner.start({
+  threadId: (await store.createThread({ actor: { id: 'u1', roles: ['ADMIN'] }, persona: 'default' })).id,
+  actor: { id: 'u1', roles: ['ADMIN'] },
+  userText: 'hi',
+})
+
+let text = ''
+for await (const frame of sink.subscribe(runId)) {
+  if (frame.t === 'text') text += frame.v
+}
+```
+
+Source: `packages/adonis/docs/testing.mdx` ("A minimal turn in a test").
+
+### Pattern 3 — assert on typed `StreamFrame`s, not bytes
+
+`sink.subscribe(runId)` yields discriminated frames — `{ t: 'text', v }` and
+`{ t: 'component', name, data }` — so one loop can assert prose and Generative-UI
+emissions separately. The SSE wire encoding happens later, in the provider's route
+handler; a test never sees it:
+
+```ts
+const components: { name: string; data: unknown }[] = []
+for await (const frame of sink.subscribe(runId)) {
+  if (frame.t === 'text') text += frame.v
+  if (frame.t === 'component') components.push({ name: frame.name, data: frame.data })
+}
+```
+
+Source: `packages/adonis/docs/testing.mdx` ("Because the fakes are behavioral twins"
+note), `packages/adonis/src/in-process-sink.ts`.
+
+## Common mistakes
+
+### MEDIUM — keeping mutable state in a FakeModelProvider script
+
+```ts
+// Wrong — a closure counter: the script is no longer a pure function of its inputs.
+let calls = 0
+const model = new FakeModelProvider(() => (calls++ === 0 ? { text: 'call tool' } : { text: 'done' }))
+```
+
+```ts
+// Correct — derive the turn from turnIndex (assistant turns already in history).
+const model = new FakeModelProvider((_args, turnIndex) =>
+  turnIndex === 0 ? { text: 'call tool' } : { text: 'done' },
+)
+```
+
+Mechanism: `turnIndex` is computed from the message history each call
+(`messages.filter(m => m.role === 'assistant').length`), so history-derived scripts stay
+deterministic and replay-safe; a closure counter diverges the moment a run is retried or
+replayed.
+Source: `packages/adonis/src/testing/fake-model-provider.ts` (`turnIndex` derivation).
+
+### MEDIUM — registering a tool the test actor's roles cannot reach, then asserting it ran
+
+```ts
+// Wrong — DefaultRolesPolicy(['ADMIN']) + actor roles: ['USER'] → the tool is never OFFERED.
+registry.register({ name: 'get_weather', kind: 'read', description: '', inputSchema: zodSchema }, handler)
+const { text } = await runAgentLoop({ ..., rolesPolicy: new DefaultRolesPolicy() },
+  { actor: { id: 'u1', roles: ['USER'] }, ... }, hooks)
+```
+
+```ts
+// Correct — align the actor's roles with the tool spec (or the policy's defaults).
+await runAgentLoop({ ..., rolesPolicy: new DefaultRolesPolicy() },
+  { actor: { id: 'u1', roles: ['ADMIN'] }, ... }, hooks)
+```
+
+Mechanism: the offered-tools filter drops role-forbidden tools BEFORE the model turn, so
+the fake model's `toolCall` for a hidden tool fails with `ToolForbiddenError` at invoke —
+the loop never auto-executes what was never offered.
+Source: `packages/adonis/src/tool-registry.ts` (`definitionsFor`, `invoke`),
+`packages/adonis/docs/governance/authorization.mdx` ("The double check").
+
+### LOW — asserting on the in-memory sink's frames as if they were SSE text
+
+```ts
+// Wrong — frames are typed objects, not an SSE byte stream.
+const raw = await res.text() // 'data: {"delta":"..."}\n\n'
+expect(raw).toContain('delta')
+```
+
+```ts
+// Correct — narrow on t and assert the payload.
+for await (const frame of sink.subscribe(runId)) {
+  if (frame.t === 'text') expect(frame.v).toBeDefined()
+}
+```
+
+Mechanism: `InMemoryTokenStreamSink.subscribe` yields `StreamFrame` objects; the SSE
+envelope (`event: meta` / `data: {"delta":...}` / `event: done`) is produced by the
+provider's route handler via `frameToSse`, a layer tests never cross.
+Source: `packages/adonis/docs/testing.mdx` (StreamFrame note),
+`packages/adonis/src/sse.ts` (`frameToSse`).
+
+See also: `agent-tools/SKILL.md` — registering real tools into the test registry;
+`agent-setup/SKILL.md` — why `day` is a required, runner-stamped loop dep.

package/skills/agent-tools/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: agent-tools
+description: >-
+  Author and register governed tools for @adonis-agora/agent: @AiTool decorated classes,
+  BaseTool/ReadTool/ActionTool static-tool subclasses, defineTool functional tools,
+  discovery from app/agent_tools via the .adonisjs/agent/tools.js barrel (toolsHook with
+  source/importAlias/output) vs the runtime scan fallback, Standard Schema inputs
+  (Zod/Valibot/ArkType), AiToolCtx actor scoping, constructor DI (@inject, lazy + cached),
+  roles/ability fail-closed gating under defaultRoles, and the dataTool governed read-only
+  SQL satellite. Use for "write a tool", "my tool is never called", "tool forbidden",
+  "agent_tools barrel not generating", or "let the agent query the database".
+metadata:
+  type: core
+  library: "@adonis-agora/agent"
+  library_version: "0.25.2"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/authoring/tools.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/authoring/data-satellite.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/ai-tool-ref.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/tool-discovery.ts"
+---
+
+# Writing governed tools for @adonis-agora/agent
+
+A tool is a named capability with a typed input schema; the model decides *when* to call
+it, the loop decides *whether it may* (role gate) and *how* (auto-execute vs human
+approval). `read` auto-executes, `action` pauses for HITL approval. There are two ways to
+author one — a class or a function — and both register the same way.
+
+## Setup
+
+Create `app/agent_tools/get_weather.ts`. The Assembler init hook registered by
+`node ace configure @adonis-agora/agent` generates the `.adonisjs/agent/tools.js` barrel
+at build/dev time, and the provider registers every export at boot:
+
+```ts
+// app/agent_tools/get_weather.ts
+import { z } from 'zod'
+import { ReadTool } from '@adonis-agora/agent'
+import type { AiToolCtx } from '@adonis-agora/agent'
+
+const input = z.object({ city: z.string() })
+type Input = z.infer<typeof input>
+
+export default class GetWeather extends ReadTool<Input, { tempC: number }> {
+  // No `kind` — the base pins 'read'. Type-checks bare, no satisfies needed.
+  static tool = {
+    name: 'get_weather',
+    description: 'Current weather for a city.',
+    input,
+    roles: ['MEMBER'], // omit → config.defaultRoles (['ADMIN'] by default)
+  }
+
+  async execute({ city }: Input, _ctx: AiToolCtx) {
+    return { tempC: 21 }
+  }
+}
+```
+
+Prefer a function? `defineTool(options, execute)` returns a branded `{ spec, handler }`
+discovery picks up identically — or pass it straight to `defineConfig({ tools: [...] })`.
+
+## Core patterns
+
+### Pattern 1 — mutating tools as `ActionTool` (HITL approval)
+
+`kind: 'action'` records the call `pending_approval` and suspends the run until a client
+posts approve/reject to `/agent/tool-call/approve|reject`. Dependencies come from the IoC
+container — declare them in the constructor with `@inject()`:
+
+```ts
+// app/agent_tools/purge_cache.ts
+import { inject } from '@adonisjs/core'
+import { z } from 'zod'
+import { ActionTool } from '@adonis-agora/agent'
+import type { AiToolCtx } from '@adonis-agora/agent'
+
+const input = z.object({ key: z.string() })
+type Input = z.infer<typeof input>
+
+@inject()
+export default class PurgeCache extends ActionTool<Input, { purged: string }> {
+  constructor(private readonly cache: CacheService) {
+    super()
+  }
+
+  static tool = {
+    name: 'purge_cache',
+    description: 'Purge one cache key.',
+    input,
+    ability: 'cache.purge', // consumed by an ability-aware RolesPolicy (authz adapter)
+  }
+
+  async execute({ key }: Input, _ctx: AiToolCtx) {
+    await this.cache.forget(key)
+    return { purged: key }
+  }
+}
+```
+
+Class tools resolve lazily through the container on first invocation, then cached — so a
+constructor needing a peer service fails nothing at boot.
+
+Source: `packages/adonis/docs/authoring/tools.mdx` ("Constructor DI").
+
+### Pattern 2 — let the agent query SQL with `dataTool` (fail-closed)
+
+`dataTool` validates a single SELECT, enforces a REQUIRED role→group→table allow-list
+(there is no allow-all), rewrites in an optional tenant scope, injects LIMIT, and
+truncates oversized results before they hit the model's context:
+
+```ts
+// config/agent.ts
+import { defineConfig, dataTool } from '@adonis-agora/agent'
+import db from '@adonisjs/lucid/services/db'
+
+export default defineConfig({
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+  tools: [
+    dataTool({
+      db: db.connection('readonly'),          // point at a read-only replica
+      tableAccess: {                          // REQUIRED — fail-closed, no implicit allow-all
+        roleGroups: { MEMBER: ['sales'], ADMIN: ['sales', 'ops'] },
+        tablesByGroup: { sales: ['orders', 'products'], ops: ['audit_log'] },
+      },
+      tenant: { tenantColumn: 'tenant_id', scopedTables: ['orders'] },
+      maxRows: 100,                           // LIMIT injected when the query has none
+    }),
+  ],
+})
+```
+
+The model sees a tool named `executeSql` taking `{ sql: string }`. Two governance layers
+stack: `roles`/`ability` gate whether the tool may be called at all; `tableAccess` +
+`tenant` gate what a permitted call may read.
+
+Source: `packages/adonis/docs/authoring/data-satellite.mdx`.
+
+### Pattern 3 — move the scan directory with `toolsHook`
+
+To keep tools in a shared package or differently-named directory, call the hook factory
+yourself in `adonisrc.ts`:
+
+```ts
+// adonisrc.ts
+import { defineConfig } from '@adonisjs/core'
+import { toolsHook } from '@adonis-agora/agent/hooks/tools'
+
+export default defineConfig({
+  hooks: {
+    init: [
+      async () => ({
+        default: toolsHook({ source: 'app/ai/tools', importAlias: '#ai_tools' }),
+      }),
+    ],
+  },
+})
+```
+
+Change `source` and `importAlias` together; leave `output` alone (default
+`.adonisjs/agent/tools.ts`) — moving the output makes the provider silently fall back to
+the runtime scan you were replacing.
+
+Source: `packages/adonis/docs/authoring/tools.mdx` ("Configuring the generator"),
+`packages/adonis/src/hooks/tools.ts` (`ToolsHookOptions`).
+
+## Common mistakes
+
+### CRITICAL — shipping tools without `roles` and calling them unreachable
+
+```ts
+// Wrong — no roles → inherits defaultRoles ['ADMIN']; MEMBER actors never see this tool.
+static tool = { name: 'get_order', description: '...', input }
+```
+
+```ts
+// Correct — declare who may invoke.
+static tool = { name: 'get_order', description: '...', input, roles: ['MEMBER'] }
+```
+
+Mechanism: `definitionsFor` filters the offered tool list through the role gate BEFORE
+each model turn, so a tool the actor cannot invoke is never described to the model — it
+cannot call what it was never shown. This is why "the model didn't call my tool" is
+usually an authorization default, not a prompt problem.
+Source: `packages/adonis/docs/authoring/tools.mdx` (fail-closed callout),
+`packages/adonis/src/tool-registry.ts` (`DefaultRolesPolicy.can`).
+
+### HIGH — trusting an id from the model's arguments instead of `ctx.actor`
+
+```ts
+// Wrong — the MODEL chose this customerId; any caller can read anyone's orders.
+async execute({ customerId }: Input) {
+  return Order.query().where('customer_id', customerId)
+}
+```
+
+```ts
+// Correct — scope to the acting identity the resolver authenticated.
+async execute(_input: Input, ctx: AiToolCtx) {
+  return Order.query().where('customer_ref', ctx.actor.id)
+}
+```
+
+Mechanism: tool arguments are untrusted model output; identity is single-sourced on
+`ctx.actor` (`id`, `roles`, `tenantRef`) populated from the server-side actor resolver.
+Source: `packages/adonis/docs/authoring/tools.mdx` ("The tool context"),
+`packages/adonis/src/spi/tool.ts`.
+
+### MEDIUM — renaming the generated barrel's output path
+
+```ts
+// Wrong — the provider imports .adonisjs/agent/tools.js; elsewhere = silently ignored.
+toolsHook({ source: 'app/ai/tools', importAlias: '#ai_tools', output: '.adonisjs/mytools.ts' })
+```
+
+```ts
+// Correct — change source + importAlias together; leave output at its default.
+toolsHook({ source: 'app/ai/tools', importAlias: '#ai_tools' })
+```
+
+Mechanism: the provider imports the compiled barrel from the fixed
+`.adonisjs/agent/tools.js`; a moved file is absent there, so boot falls back to scanning
+`app/agent_tools` — which no longer holds your tools — and the agent runs with none of
+them, logging only a quiet fallback.
+Source: `packages/adonis/docs/authoring/tools.mdx` ("Point `output` elsewhere…"),
+`packages/adonis/src/hooks/tools.ts` (`GENERATED_TOOLS_OUTPUT`).
+
+### MEDIUM — debugging "zero tools" after adding one that throws on import
+
+```ts
+// Wrong assumption — a throwing tool file aborts discovery, so NOTHING registers.
+// app/agent_tools/broken.ts references a service whose `app` is undefined during boot.
+```
+
+```ts
+// Correct mental model — the bad file is skipped loudly; every OTHER tool still registers.
+// Fix the import error surfaced in the logs; the rest of agent_tools keeps working meanwhile.
+```
+
+Mechanism: `discoverTools` wraps each dynamic import in its own try/catch, logs the
+failure, and continues — so the symptom is one missing tool (the model narrating calls it
+was never given), not a dead registry.
+Source: `packages/adonis/src/tool-discovery.ts` (`discoverTools` import try/catch and log
+message).
+
+### LOW — declaring `kind` on a ReadTool/ActionTool subclass
+
+```ts
+// Wrong — the base already pins kind; the literal widens and fights the inherited static type.
+export default class CloseTicket extends ActionTool<Input, Row> {
+  static tool = { name: 'close_ticket', kind: 'action', description: '...', input }
+}
+```
+
+```ts
+// Correct — truly bare static; the base carries kind.
+export default class CloseTicket extends ActionTool<Input, Row> {
+  static tool = { name: 'close_ticket', description: '...', input }
+}
+```
+
+Mechanism: `ReadTool`/`ActionTool` pin `static readonly kind`; redeclaring it adds a union
+field the inherited `static tool?: BaseToolOptions` doesn't contextualize, so the literal's
+`kind: string` widens and type-checking degrades instead of failing.
+Source: `packages/adonis/src/base-tool.ts` (`BaseToolOptions`, kind-specific bases),
+`packages/adonis/docs/authoring/tools.mdx` ("truly bare").
+
+See also: `agent-governance/SKILL.md` — swapping `rolesPolicy` for ability checks;
+`agent-personas-agents/SKILL.md` — narrowing tools per persona/agent.