@adonis-agora/agent 0.44.0 → 0.46.0

package/dist/src/tool-registry.js

@@ -1,4 +1,5 @@
 import { filterToolsByRole, personaFilterTools } from './personas.js';
+import { createNoopEmitUi } from './tool-ui.js';
 /** Thrown when an actor invokes a tool their role is not allowed. */
 export class ToolForbiddenError extends Error {
     toolName;
@@ -61,12 +62,18 @@ export class ToolRegistry {
         return [...this.entries.values()].map((entry) => entry.spec);
     }
     /** The tools to offer the model for this actor+persona, after the two filter layers. */
-    async definitionsFor(actor, policy, allowedTools) {
-        return (await this.visibleSpecs(actor, policy, allowedTools)).map((spec) => ({
-            name: spec.name,
-            kind: spec.kind,
-            description: spec.description,
-            inputSchema: spec.inputSchema,
+    async definitionsFor(actor, policy, allowedTools, scope = {}) {
+        const visible = await this.visibleSpecs(actor, policy, allowedTools);
+        return Promise.all(visible.map(async (spec) => {
+            const handler = this.entries.get(spec.name)?.handler;
+            // After every gate: a tool this actor cannot reach is never asked to describe itself.
+            const override = handler?.describe === undefined ? undefined : await handler.describe({ actor, ...scope });
+            return {
+                name: spec.name,
+                kind: spec.kind,
+                description: override?.description ?? spec.description,
+                inputSchema: override?.inputSchema ?? spec.inputSchema,
+            };
         }));
     }
     /**
@@ -91,17 +98,26 @@ export class ToolRegistry {
         if (validation.issues !== undefined) {
             throw new ToolInputInvalidError(name, validation.issues);
         }
-        return entry.handler.execute(validation.value, ctx);
+        // `emitUi` is part of the context's contract; a caller without a conversation (a test, a script,
+        // a JavaScript host) gets the no-op rather than a tool that crashes calling it.
+        const withEmit = typeof ctx.emitUi === 'function' ? ctx : { ...ctx, emitUi: createNoopEmitUi(ctx.requestId) };
+        return entry.handler.execute(validation.value, withEmit);
     }
 }
-/** Default gate: one of the actor's roles must be in spec.roles (defaulting to ADMIN-only). */
+/**
+ * Default gate: one of the actor's roles must be in `spec.roles` (else the default roles). An empty
+ * list means no restriction — the default: a tool is callable by whoever the actor resolver resolved,
+ * an anonymous visitor included. `action` tools still park on approval regardless.
+ */
 export class DefaultRolesPolicy {
     defaultRoles;
-    constructor(defaultRoles = ['ADMIN']) {
+    constructor(defaultRoles = []) {
         this.defaultRoles = defaultRoles;
     }
     can(actor, tool) {
         const allowed = tool.roles ?? this.defaultRoles;
+        if (allowed.length === 0)
+            return true;
         return (actor.roles ?? []).some((role) => allowed.includes(role));
     }
 }

package/dist/src/tool-registry.js.map

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

package/dist/src/tool-ui.d.ts

@@ -0,0 +1,35 @@
+import type { SinkWriter } from './spi/token-stream-sink.js';
+import type { AiToolCtx } from './spi/tool.js';
+import type { AgentUiComponent } from './stream-events.js';
+/**
+ * What a tool step returns: the output alone when the tool pushed nothing (the bytes a run journaled
+ * before `emitUi` existed), else an envelope carrying the pushes with it.
+ */
+export declare function wrapToolStepOutput(output: unknown, ui: readonly AgentUiComponent[]): unknown;
+/** Read a tool step's result back — an envelope, or a bare output recorded without one. */
+export declare function unwrapToolStepOutput(raw: unknown): {
+    output: unknown;
+    ui: AgentUiComponent[];
+};
+export type EmitUi = AiToolCtx['emitUi'];
+/**
+ * An `emitUi` for a context with no conversation to push into (an MCP call, a handler invoked
+ * directly): it accepts the push and answers an id, so a tool never has to branch on where it runs.
+ */
+export declare function createNoopEmitUi(scope?: string): EmitUi;
+export interface UiCollector {
+    emit: EmitUi;
+    /** Every distinct component pushed, first-seen order, last props per id. */
+    components(): AgentUiComponent[];
+    /** Restart the default id counter — a retried attempt re-pushes under the same ids. */
+    restart(): void;
+}
+/**
+ * The `emitUi` of one tool call. Ids default to `<toolCallId>:ui:<n>`; each push is written to the
+ * run's stream as it happens (a component frame, which both envelopes carry) and kept for the step's
+ * result.
+ */
+export declare function createUiCollector(toolCallId: string, writer?: SinkWriter): UiCollector;
+/** Merge component lists: first-seen order, last props per id. */
+export declare function mergeUi(...lists: readonly (readonly AgentUiComponent[] | undefined)[]): AgentUiComponent[];
+//# sourceMappingURL=tool-ui.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-ui.d.ts","sourceRoot":"","sources":["../../src/tool-ui.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAgB3D;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,gBAAgB,EAAE,GAAG,OAAO,CAM5F;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAU9F;AAED,MAAM,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAEzC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,GAAG,MAAM,CAUvD;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,UAAU,IAAI,gBAAgB,EAAE,CAAC;IACjC,uFAAuF;IACvF,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,CAyCtF;AAED,kEAAkE;AAClE,wBAAgB,OAAO,CACrB,GAAG,KAAK,EAAE,SAAS,CAAC,SAAS,gBAAgB,EAAE,GAAG,SAAS,CAAC,EAAE,GAC7D,gBAAgB,EAAE,CAQpB"}

package/dist/src/tool-ui.js

@@ -0,0 +1,100 @@
+/*
+ * `ctx.emitUi` plumbing, after `tool-ui.ts` in `@dudousxd/nestjs-agent-core`: a collector per tool
+ * call that streams each push and remembers it, and the envelope that carries the pushes on the
+ * tool step's journaled result — so a durable replay neither re-streams nor re-persists them.
+ */
+const TOOL_STEP_UI = '@@adonis-agent/tool-step-ui';
+/**
+ * What a tool step returns: the output alone when the tool pushed nothing (the bytes a run journaled
+ * before `emitUi` existed), else an envelope carrying the pushes with it.
+ */
+export function wrapToolStepOutput(output, ui) {
+    if (ui.length === 0) {
+        return output;
+    }
+    const wrapped = { [TOOL_STEP_UI]: 1, output, ui: [...ui] };
+    return wrapped;
+}
+/** Read a tool step's result back — an envelope, or a bare output recorded without one. */
+export function unwrapToolStepOutput(raw) {
+    if (typeof raw === 'object' &&
+        raw !== null &&
+        raw[TOOL_STEP_UI] === 1) {
+        const wrapped = raw;
+        return { output: wrapped.output, ui: Array.isArray(wrapped.ui) ? wrapped.ui : [] };
+    }
+    return { output: raw, ui: [] };
+}
+/**
+ * An `emitUi` for a context with no conversation to push into (an MCP call, a handler invoked
+ * directly): it accepts the push and answers an id, so a tool never has to branch on where it runs.
+ */
+export function createNoopEmitUi(scope = 'noop') {
+    let next = 0;
+    return async (_component, _props, options = {}) => {
+        if (options.id !== undefined) {
+            return { id: options.id };
+        }
+        const id = `${scope}:ui:${next}`;
+        next += 1;
+        return { id };
+    };
+}
+/**
+ * The `emitUi` of one tool call. Ids default to `<toolCallId>:ui:<n>`; each push is written to the
+ * run's stream as it happens (a component frame, which both envelopes carry) and kept for the step's
+ * result.
+ */
+export function createUiCollector(toolCallId, writer) {
+    const pushed = new Map();
+    let next = 0;
+    const emit = async (component, props, options = {}) => {
+        if (typeof component !== 'string' || component.length === 0) {
+            throw new Error('emitUi: component must be a non-empty string');
+        }
+        if (typeof props !== 'object' || props === null || Array.isArray(props)) {
+            throw new Error('emitUi: props must be a JSON object');
+        }
+        let id = options.id;
+        if (id === undefined) {
+            id = `${toolCallId}:ui:${next}`;
+            next += 1;
+        }
+        const entry = {
+            id,
+            component,
+            // Snapshot: the frame and the persisted value are what the tool pushed at THIS moment.
+            props: JSON.parse(JSON.stringify(props)),
+            ...(options.version !== undefined ? { version: options.version } : {}),
+            toolCallId,
+        };
+        pushed.set(id, entry);
+        await writer?.write({
+            t: 'component',
+            name: component,
+            data: entry.props,
+            id,
+            toolCallId,
+            ...(entry.version !== undefined ? { version: entry.version } : {}),
+        });
+        return { id };
+    };
+    return {
+        emit,
+        components: () => [...pushed.values()],
+        restart: () => {
+            next = 0;
+        },
+    };
+}
+/** Merge component lists: first-seen order, last props per id. */
+export function mergeUi(...lists) {
+    const merged = new Map();
+    for (const list of lists) {
+        for (const component of list ?? []) {
+            merged.set(component.id, component);
+        }
+    }
+    return [...merged.values()];
+}
+//# sourceMappingURL=tool-ui.js.map

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

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

package/dist/src/types.d.ts

@@ -44,7 +44,12 @@ export interface ToolSpec {
     inputSchema: StandardSchemaV1;
     /** For `kind: 'agent'` — the name of the agent to delegate to. */
     targetAgent?: string;
-    /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (e.g. ADMIN-only). */
+    /**
+     * A successful call ENDS the turn: its effect is the answer (it pushed the UI the user reads), so
+     * no further model call narrates it. A failed call does not end it — the model gets to recover.
+     */
+    terminal?: boolean;
+    /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (unrestricted unless `defaultRoles` is set). */
     roles?: string[];
     /**
      * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
@@ -285,8 +290,8 @@ export interface DelegateEdge {
     /** Name of the agent to delegate to — the `target` in `ask_<target>`. */
     agent: string;
     /**
-     * Roles allowed to invoke the synthesized delegate tool. Omitted → the `RolesPolicy` default,
-     * which is ADMIN-only under {@link import('./authorizer.js').DefaultToolAuthorizer}.
+     * Roles allowed to invoke the synthesized delegate tool. Omitted → the `RolesPolicy` default
+     * (`defaultRoles`; unrestricted unless configured, under {@link import('./authorizer.js').DefaultToolAuthorizer}).
      */
     roles?: string[];
     /**
@@ -314,10 +319,10 @@ export interface AgentDefinition {
      * Other agents this agent may delegate to. Each edge is auto-registered as an `agent`-kind tool
      * named `ask_<target>`, which the loop authorizes exactly like any other tool.
      *
-     * A bare string declares the edge with no authorization annotation, which is fail-closed on
-     * purpose: under the default {@link import('./authorizer.js').DefaultToolAuthorizer} a tool with
-     * no `roles` is ADMIN-only, and under the `@adonis-agora/agent/authz` adapter a tool with no
-     * `ability` is denied outright — so under authz a bare edge can never be called. Use the
+     * A bare string declares the edge with no authorization annotation: under the default
+     * {@link import('./authorizer.js').DefaultToolAuthorizer} it takes `defaultRoles` (unrestricted
+     * unless configured), and under the `@adonis-agora/agent/authz` adapter a tool with no `ability`
+     * is denied outright — so under authz a bare edge can never be called. Use the
      * {@link DelegateEdge} object form to declare the `roles` and/or `ability` the delegate tool
      * carries.
      */

package/dist/src/types.d.ts.map

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

package/dist/stubs/config/agent.stub

@@ -1,7 +1,8 @@
 {{{
   exports({ to: app.configPath('agent.ts') })
 }}}
-import { defineConfig, stores, AuthActorResolver } from '@adonis-agora/agent'
+import { defineConfig, stores } from '@adonis-agora/agent'
+// import { AuthActorResolver } from '@adonis-agora/agent'
 // import { attachmentStores } from '@adonis-agora/agent'
 // import { aiSdkModel } from '@adonis-agora/agent/ai-sdk'
 // import { openai } from '@ai-sdk/openai'
@@ -9,8 +10,9 @@ import { defineConfig, stores, AuthActorResolver } from '@adonis-agora/agent'
 /**
  * Configuration for @adonis-agora/agent. Only \`model\` is required. Pick a \`store\` by name from the
  * \`stores\` map (each driver's peer is imported lazily, only when selected); omit \`store\` for the
- * in-memory store. The runner is in-process by default (\`durable\` is deferred). The actor resolver
- * defaults to one that THROWS — the agent never fabricates a caller — so wire a real one.
+ * in-memory store. The runner is in-process by default (\`durable\` is deferred). With no
+ * \`actorResolver\` the endpoints are PUBLIC: every browser is its own anonymous actor (an HttpOnly
+ * cookie). Uncomment the \`actorResolver\` line below to require login.
  *
  * Publish the tables with \`node ace migration:run\` after configuring.
  */
@@ -31,12 +33,12 @@ export default defineConfig({
     lucid: stores.lucid(),
   },
 
-  // Identity seam — reads ctx.auth.user (fail-closed: throws when unauthenticated). Swap for your own
-  // resolver, or HeaderActorResolver behind a trusted gateway.
-  actorResolver: new AuthActorResolver(),
+  // Identity. Omitted → public, one anonymous actor per browser. This line requires login instead
+  // (reads ctx.auth.user; 401 without). Or HeaderActorResolver behind a trusted gateway.
+  // actorResolver: new AuthActorResolver(),
 
   // path: 'agent',            // → /agent/chat, /agent/threads, ...
-  // defaultRoles: ['ADMIN'],  // roles a tool requires when it declares none (fail-closed)
+  // defaultRoles: ['ADMIN'],  // roles a tool requires when it declares none (default: none — open)
   // maxSteps: 8,              // cap on model↔tool iterations per turn
 
   // Governance console — served automatically at <path>/dashboard (default /agent/dashboard), no

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -140,6 +140,16 @@
       "types": "./dist/src/react/index.d.ts",
       "import": "./dist/src/react/index.js",
       "default": "./dist/src/react/index.js"
+    },
+    "./genui": {
+      "types": "./dist/src/genui/index.d.ts",
+      "import": "./dist/src/genui/index.js",
+      "default": "./dist/src/genui/index.js"
+    },
+    "./genui/builtins": {
+      "types": "./dist/src/genui/builtins.d.ts",
+      "import": "./dist/src/genui/builtins.js",
+      "default": "./dist/src/genui/builtins.js"
     }
   },
   "files": [
@@ -163,6 +173,7 @@
     "@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.26.0 <1.0.0",
     "@qdrant/js-client-rest": "^1.11.0",
     "ai": "^7.0.0",
     "node-sql-parser": "^5.3.0",
@@ -208,6 +219,9 @@
     },
     "zod": {
       "optional": true
+    },
+    "@dudousxd/nestjs-agent-core": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -219,6 +233,7 @@
     "@adonisjs/core": "7.5.2",
     "@adonisjs/lucid": "22.4.2",
     "@adonisjs/redis": "11.0.0",
+    "@dudousxd/nestjs-agent-core": "0.26.0",
     "@qdrant/js-client-rest": "1.19.0",
     "@tanstack/intent": "0.4.0",
     "@types/node": "26.6.3",

package/skills/agent-governance/SKILL.md

@@ -3,7 +3,7 @@ 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
+  gateway, AnonymousActorResolver public default — one anonymous actor per browser), 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,
@@ -24,8 +24,9 @@ sources:
 
 # 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
+Authorization in `@adonis-agora/agent` works at three layers: **who is calling**
+(an `ActorResolver` — anonymous per browser when none is configured, `AuthActorResolver` to
+require login), **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).
 

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

@@ -152,9 +152,9 @@ 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.
+carries nothing, so under `DefaultToolAuthorizer` it takes `defaultRoles` (open unless
+configured), 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

@@ -63,7 +63,8 @@ export default defineConfig({
     lucid: stores.lucid(),   // persists to SQL via @adonisjs/lucid
   },
 
-  // Identity seam — fail-closed. Without a resolver every request throws → 401.
+  // Identity. Omitted → endpoints PUBLIC, one anonymous actor per browser (HttpOnly cookie).
+  // This line requires login instead (ctx.auth.user; 401 without).
   actorResolver: new AuthActorResolver(),
 
   defaultAgent: {
@@ -181,15 +182,17 @@ Source: `packages/adonis/src/stores/factory.ts` (`tokenSinks`),
 
 ## Common mistakes
 
-### HIGH — omitting `actorResolver` and shipping 401s everywhere
+### HIGH — omitting `actorResolver` in an app that has logins
 
 ```ts
-// Wrong — UnconfiguredActorResolver THROWS on every request; all routes answer 401.
+// Wrong for an app with users — no resolver means the endpoints are PUBLIC: every browser
+// is its own anonymous actor (anon:<sha256 of an HttpOnly cookie>), and your users'
+// threads are not tied to their accounts.
 export default defineConfig({ model: () => aiSdkModel(openai('gpt-4o-mini')) })
 ```
 
 ```ts
-// Correct — read the authenticated principal; no identity is ever fabricated.
+// Correct — one line requires login (reads ctx.auth.user; 401 without).
 import { AuthActorResolver } from '@adonis-agora/agent'
 export default defineConfig({
   model: () => aiSdkModel(openai('gpt-4o-mini')),
@@ -197,11 +200,11 @@ export default defineConfig({
 })
 ```
 
-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").
+Mechanism: with no resolver the provider installs `AnonymousActorResolver` and logs a boot
+notice that the endpoints are public. Right for a free public chat (set a `quota` there);
+wrong for an app whose users log in.
+Source: `packages/adonis/src/anonymous-actor-resolver.ts`,
+`packages/adonis/docs/governance/authorization.mdx` ("No resolver: the endpoints are public").
 
 ### MEDIUM — expecting quota enforcement after configuring only a store
 

package/skills/agent-tools/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   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
+  roles/ability gating under defaultRoles (open by default), 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:
@@ -167,23 +167,24 @@ Source: `packages/adonis/docs/authoring/tools.mdx` ("Configuring the generator")
 
 ## Common mistakes
 
-### CRITICAL — shipping tools without `roles` and calling them unreachable
+### CRITICAL — shipping a privileged tool without `roles`
 
 ```ts
-// Wrong — no roles → inherits defaultRoles ['ADMIN']; MEMBER actors never see this tool.
-static tool = { name: 'get_order', description: '...', input }
+// Wrong — no roles → inherits defaultRoles, which is [] (open) by default: every actor,
+// an anonymous visitor included, is offered this tool.
+static tool = { name: 'refund_order', kind: 'action', description: '...', input }
 ```
 
 ```ts
-// Correct — declare who may invoke.
-static tool = { name: 'get_order', description: '...', input, roles: ['MEMBER'] }
+// Correct — declare who may invoke (or set defaultRoles: ['ADMIN'] to close every tool by default).
+static tool = { name: 'refund_order', kind: 'action', description: '...', input, roles: ['ADMIN'] }
 ```
 
 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),
+each model turn, and `invoke` re-checks it. A tool with no `roles` takes `defaultRoles`;
+an empty list is no restriction. 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`).
 
 ### HIGH — trusting an id from the model's arguments instead of `ctx.actor`