@adonis-agora/agent 0.52.0 → 0.53.0

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

@@ -58,7 +58,26 @@ export declare class ToolRegistry {
  */
 export declare class DefaultRolesPolicy implements RolesPolicy {
     private readonly defaultRoles;
-    constructor(defaultRoles?: string[]);
+    private readonly emptyRoles;
+    constructor(defaultRoles?: string[], options?: RolesPolicyOptions);
     can(actor: Actor, tool: ToolSpec): boolean;
 }
+/**
+ * What an empty roles list means to {@link DefaultRolesPolicy}: `'allow'` (the default) — no
+ * restriction; `'deny'` — nobody.
+ */
+export type EmptyRoles = 'allow' | 'deny';
+export interface RolesPolicyOptions {
+    /** What an empty roles list means. Default `'allow'`. */
+    emptyRoles?: EmptyRoles;
+}
+/**
+ * The closed gate — {@link DefaultRolesPolicy} with `emptyRoles: 'deny'`: the actor needs a role the
+ * tool declares (else one of the default roles). A tool with no `roles` and no default roles, or with
+ * an explicitly empty list, reaches nobody. For apps where an empty list means "no one" — a computed
+ * `roles` that can come out empty, a multi-tenant MCP surface.
+ */
+export declare class ClosedRolesPolicy extends DefaultRolesPolicy {
+    constructor(defaultRoles?: string[]);
+}
 //# sourceMappingURL=tool-registry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAElE,qEAAqE;AACrE,qBAAa,kBAAmB,SAAQ,KAAK;aACf,QAAQ,EAAE,MAAM;IAA5C,YAA4B,QAAQ,EAAE,MAAM,EAG3C;CACF;AAED,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,KAAK;aACd,QAAQ,EAAE,MAAM;IAA5C,YAA4B,QAAQ,EAAE,MAAM,EAG3C;CACF;AAED,uEAAuE;AACvE,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,SAAS,gBAAgB,CAAC,KAAK,EAAE;IAF3D,YACkB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,gBAAgB,CAAC,KAAK,EAAE,EAM1D;CACF;AAOD;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAEnD;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhC;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAEvC;IAED,QAAQ,IAAI,QAAQ,EAAE,CAErB;IAED,wFAAwF;IAClF,cAAc,CAClB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,MAAM,EAAE,EACvB,KAAK,GAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAM,GAC3C,OAAO,CAAC,cAAc,EAAE,CAAC,CAgB3B;IAED;;;;OAIG;IACG,YAAY,CAChB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAGrB;IAED,yFAAyF;IACnF,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,OAAO,CAAC,CAiBlB;CACF;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAAzC,YAA6B,YAAY,GAAE,MAAM,EAAO,EAAI;IAE5D,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAIzC;CACF"}
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE/E,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAElE,qEAAqE;AACrE,qBAAa,kBAAmB,SAAQ,KAAK;aACf,QAAQ,EAAE,MAAM;IAA5C,YAA4B,QAAQ,EAAE,MAAM,EAG3C;CACF;AAED,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,KAAK;aACd,QAAQ,EAAE,MAAM;IAA5C,YAA4B,QAAQ,EAAE,MAAM,EAG3C;CACF;AAED,uEAAuE;AACvE,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,SAAS,gBAAgB,CAAC,KAAK,EAAE;IAF3D,YACkB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,gBAAgB,CAAC,KAAK,EAAE,EAM1D;CACF;AAOD;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAEpD,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAEnD;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhC;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAEvC;IAED,QAAQ,IAAI,QAAQ,EAAE,CAErB;IAED,wFAAwF;IAClF,cAAc,CAClB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,MAAM,EAAE,EACvB,KAAK,GAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAM,GAC3C,OAAO,CAAC,cAAc,EAAE,CAAC,CAgB3B;IAED;;;;OAIG;IACG,YAAY,CAChB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAGrB;IAED,yFAAyF;IACnF,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,OAAO,CAAC,CAiBlB;CACF;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IAIlD,OAAO,CAAC,QAAQ,CAAC,YAAY;IAH/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC,YACmB,YAAY,GAAE,MAAM,EAAO,EAC5C,OAAO,GAAE,kBAAuB,EAGjC;IAED,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAIzC;CACF;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1C,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;IACvD,YAAY,YAAY,GAAE,MAAM,EAAO,EAEtC;CACF"}

package/dist/src/tool-registry.js

@@ -111,14 +111,27 @@ export class ToolRegistry {
  */
 export class DefaultRolesPolicy {
     defaultRoles;
-    constructor(defaultRoles = []) {
+    emptyRoles;
+    constructor(defaultRoles = [], options = {}) {
         this.defaultRoles = defaultRoles;
+        this.emptyRoles = options.emptyRoles ?? 'allow';
     }
     can(actor, tool) {
         const allowed = tool.roles ?? this.defaultRoles;
         if (allowed.length === 0)
-            return true;
+            return this.emptyRoles === 'allow';
         return (actor.roles ?? []).some((role) => allowed.includes(role));
     }
 }
+/**
+ * The closed gate — {@link DefaultRolesPolicy} with `emptyRoles: 'deny'`: the actor needs a role the
+ * tool declares (else one of the default roles). A tool with no `roles` and no default roles, or with
+ * an explicitly empty list, reaches nobody. For apps where an empty list means "no one" — a computed
+ * `roles` that can come out empty, a multi-tenant MCP surface.
+ */
+export class ClosedRolesPolicy extends DefaultRolesPolicy {
+    constructor(defaultRoles = []) {
+        super(defaultRoles, { emptyRoles: 'deny' });
+    }
+}
 //# sourceMappingURL=tool-registry.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../../src/tool-registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,qEAAqE;AACrE,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACf,QAAQ;IAApC,YAA4B,QAAgB;QAC1C,KAAK,CAAC,SAAS,QAAQ,gCAAgC,CAAC,CAAC;wBAD/B,QAAQ;QAElC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACd,QAAQ;IAApC,YAA4B,QAAgB;QAC1C,KAAK,CAAC,SAAS,QAAQ,qBAAqB,CAAC,CAAC;wBADpB,QAAQ;QAElC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAE5B,QAAQ;IACR,MAAM;IAFxB,YACkB,QAAgB,EAChB,MAAyC;QAEzD,KAAK,CACH,2BAA2B,QAAQ,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3F,CAAC;wBALc,QAAQ;sBACR,MAAM;QAKtB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAOD;;;;;;GAMG;AACH,MAAM,OAAO,YAAY;IACN,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IAEpD,QAAQ,CAAC,IAAc,EAAE,OAAoB;QAC3C,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,IAAI,CAAC,IAAY;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACtC,CAAC;IAED,QAAQ;QACN,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/D,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,cAAc,CAClB,KAAY,EACZ,MAAmB,EACnB,YAAuB,EACvB,KAAK,GAAqC,EAAE;QAE5C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;QACrE,OAAO,OAAO,CAAC,GAAG,CAChB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;YACrD,sFAAsF;YACtF,MAAM,QAAQ,GACZ,OAAO,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;YAC5F,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,QAAQ,EAAE,WAAW,IAAI,IAAI,CAAC,WAAW;gBACtD,WAAW,EAAE,QAAQ,EAAE,WAAW,IAAI,IAAI,CAAC,WAAW;aACvD,CAAC;QACJ,CAAC,CAAC,CACH,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,YAAY,CAChB,KAAY,EACZ,MAAmB,EACnB,YAAuB;QAEvB,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC3E,OAAO,kBAAkB,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACtD,CAAC;IAED,yFAAyF;IACzF,KAAK,CAAC,MAAM,CACV,IAAY,EACZ,KAAc,EACd,GAAc,EACd,MAAmB;QAEnB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC7E,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,qBAAqB,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;QAC3D,CAAC;QACD,iGAAiG;QACjG,gFAAgF;QAChF,MAAM,QAAQ,GACZ,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QAC/F,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC3D,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAkB;IACA,YAAY;IAAzC,YAA6B,YAAY,GAAa,EAAE;4BAA3B,YAAY;IAAkB,CAAC;IAE5D,GAAG,CAAC,KAAY,EAAE,IAAc;QAC9B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC;QAChD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACtC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,CAAC;CACF"}
+{"version":3,"file":"tool-registry.js","sourceRoot":"","sources":["../../src/tool-registry.ts"],"names":[],"mappings":"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"}

package/dist/src/types.d.ts

@@ -1,4 +1,5 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { AgentIntake } from './elicitation.js';
 import type { ActorResolver } from './spi/actor-resolver.js';
 import type { ChatQueueState } from './spi/chat-queue.js';
 import type { AgentUiComponent } from './stream-events.js';
@@ -360,6 +361,21 @@ export interface AgentDefinition {
      * Undefined → {@link import('./agent-loop.js').DEFAULT_MAX_AGENT_APPEARANCES}.
      */
     maxAgentAppearances?: number;
+    /**
+     * Offer the model the built-in `ask` tool, so it can put a question set to the user when it judges
+     * the scope is missing, and wait for the answers (`POST <path>/tool-call/answer`). Off by default.
+     * See `AgentLoopDeps.ask`.
+     *
+     * The run PARKS on the person. Under the inline runner that wait lives in the process that started
+     * the turn, so the answer has to reach the same replica; under the durable runner (`durable: true`)
+     * it is a journaled signal any replica can deliver.
+     */
+    ask?: boolean;
+    /**
+     * A question set this agent asks before it starts working — authored here, not by the model — on
+     * a thread's first turn, or on every turn. See `AgentLoopDeps.intake`. Parks like {@link ask}.
+     */
+    intake?: AgentIntake;
     /**
      * Per-agent {@link ActorResolver} override. When set, this agent resolves the request's actor with
      * its own resolver instead of the module-global `config.actorResolver` — e.g. an agent that reads

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

@@ -39,6 +39,7 @@ export default defineConfig({
 
   // path: 'agent',            // → /agent/chat, /agent/threads, ...
   // defaultRoles: ['ADMIN'],  // roles a tool requires when it declares none (default: none — open)
+  // emptyRoles: 'deny',       // an empty roles list reaches nobody (default: 'allow' — open)
   // maxSteps: 8,              // cap on model↔tool iterations per turn
 
   // Governance console — served automatically at <path>/dashboard (default /agent/dashboard), no

package/dist/stubs/config/mcp.stub

@@ -45,6 +45,11 @@ export default defineMcpConfig({
   // requests are rejected 401.
   // actor: { id: 'mcp', roles: ['ADMIN'] },
 
+  // Roles a tool requires when it declares none (default ['ADMIN']). An empty list is open unless
+  // emptyRoles is 'deny', which makes it reach nobody.
+  // defaultRoles: ['ADMIN'],
+  // emptyRoles: 'deny',
+
   // Restrict the exposed tools to an allow-list by name.
   // allowedTools: ['calcular_estatisticas', 'estatistica_inferencial'],
 })

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

@@ -6,8 +6,9 @@ import db from '@adonisjs/lucid/services/db'
 import { createAgentTables, dropAgentTables } from '@adonis-agora/agent'
 
 /**
- * The seven tables for the @adonis-agora/agent \`lucid\` store: threads, messages, tool calls, token
- * usage, model pricing, the run lifecycle, and the chat message queue — plus their indexes.
+ * The nine 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.
  *
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {

package/skills/agent-governance/SKILL.md

@@ -50,6 +50,7 @@ export default defineConfig({
     }),
   }),
   defaultRoles: ['STAFF'],       // roles a tool requires when it declares none
+  // emptyRoles: 'deny',         // an empty roles list reaches nobody (default 'allow': open since 0.46)
 })
 ```
 

package/skills/agent-setup/SKILL.md

@@ -4,7 +4,7 @@ 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(), quota: { limits }, pricingStores +
-  seedModelPrices + estimateCost, tokenSinks.redis multi-replica SSE sink,
+  seedModelPrices + estimateCost, tokenSinks.redis / tokenSinks.lucid multi-replica SSE sinks,
   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",
@@ -180,7 +180,28 @@ 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.
 
+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
+(`pollIntervalMs`, default 250) and streamed text is coalesced into one row per
+`flushMs` (default 50), so it is slower and it loads the database — prefer Redis when
+it is there. Rows lapse `ttlSeconds` after a run's last write (`purgeExpired()`).
+
+```ts
+export default defineConfig({
+  // ...
+  durable: true,                 // approvals and questions park on a durable signal
+  sink: tokenSinks.lucid(),      // any replica serves and resumes any run's stream
+  defaultAgent: { ask: true },   // offer the model the built-in `ask` tool
+})
+```
+
+`ask` / `intake` are per-agent (`defaultAgent`, `agents[]`). Under the inline runner a
+parked question can only be answered on the replica that started the turn; several
+replicas need `durable: true`.
+
 Source: `packages/adonis/src/stores/factory.ts` (`tokenSinks`),
+`packages/adonis/src/lucid-token-stream-sink.ts`,
+`packages/adonis/docs/sql-streaming.mdx`,
 `packages/adonis/docs/streaming-and-http.mdx` ("Single-replica by default" callout).
 
 ### Pattern 4 — a React chat with `@adonis-agora/agent/react`

package/skills/agent-tools/SKILL.md

@@ -19,6 +19,7 @@ sources:
   - "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"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/confirmed-tool.ts"
 ---
 
 # Writing governed tools for @adonis-agora/agent
@@ -165,6 +166,40 @@ the runtime scan you were replacing.
 Source: `packages/adonis/docs/authoring/tools.mdx` ("Configuring the generator"),
 `packages/adonis/src/hooks/tools.ts` (`ToolsHookOptions`).
 
+### Pattern 4 — a write reachable over MCP: `defineConfirmedTool`
+
+An `action` never reaches an MCP client (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.
+
+```ts
+import { defineConfirmedTool, LucidConfirmTokenStore } from '@adonis-agora/agent'
+
+export const refundOrder = defineConfirmedTool(
+  {
+    name: 'refund_order',
+    description: 'Refund an order. Returns a preview first; confirm to commit.',
+    input: z.object({ orderId: z.string() }), // confirm / confirmToken are added for you
+    roles: ['ADMIN'],
+    secret: () => env.get('APP_KEY').release(), // required, no default
+    store: new LucidConfirmTokenStore(db), // without it the token is NOT single use
+  },
+  {
+    prepare: async ({ orderId }, ctx) => loadRefundableOrder(orderId, ctx.actor), // throw to refuse
+    preview: (order) => ({ summary: `Refund ${order.total}?`, data: order }), // writes nothing
+    commit: async (order) => ({ summary: 'Refunded.', data: await refund(order) }),
+  },
+)
+```
+
+`prepare` runs on the preview and again on the confirmation — put every rule the commit
+relies on there. The token is bound to tool + `ctx.actor.id` + `ctx.actor.tenantRef` +
+arguments and expires (`ttlMs`, default 15 min).
+
+Source: `packages/adonis/docs/mcp.mdx` ("Writes with a human gate"),
+`packages/adonis/src/confirmed-tool.ts`.
+
 ## Common mistakes
 
 ### CRITICAL — shipping a privileged tool without `roles`
@@ -182,7 +217,8 @@ 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. An `action` still parks on approval — but by default the
+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
 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`).