@adonis-agora/agent 0.30.2 → 0.33.0

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

@@ -28,6 +28,15 @@ export declare class ToolInputInvalidError extends Error {
 export declare class ToolRegistry {
     private readonly entries;
     register(spec: ToolSpec, handler: ToolHandler): void;
+    /**
+     * Drop a tool, so it is neither offered to the model nor invocable. Returns whether there was one.
+     *
+     * For a tool whose EXISTENCE is not decided here: an MCP server may stop exporting a tool between
+     * one `tools/list` and the next, and leaving the old spec registered would go on offering the
+     * model a tool whose next call fails on somebody else's machine. Whoever registered a name is
+     * responsible for deciding when it is gone — nothing in the registry itself expires.
+     */
+    unregister(name: string): boolean;
     has(name: string): boolean;
     spec(name: string): ToolSpec | undefined;
     allSpecs(): ToolSpec[];

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,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,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,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,GACtB,OAAO,CAAC,cAAc,EAAE,CAAC,CAS3B;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,CAalB;CACF;AAED,+FAA+F;AAC/F,qBAAa,kBAAmB,YAAW,WAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAAzC,YAA6B,YAAY,GAAE,MAAM,EAAc,EAAI;IAEnE,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAGzC;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,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5D,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,GACtB,OAAO,CAAC,cAAc,EAAE,CAAC,CAS3B;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,CAalB;CACF;AAED,+FAA+F;AAC/F,qBAAa,kBAAmB,YAAW,WAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAAzC,YAA6B,YAAY,GAAE,MAAM,EAAc,EAAI;IAEnE,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAGzC;CACF"}

package/dist/src/tool-registry.js

@@ -40,6 +40,17 @@ export class ToolRegistry {
     register(spec, handler) {
         this.entries.set(spec.name, { spec, handler });
     }
+    /**
+     * Drop a tool, so it is neither offered to the model nor invocable. Returns whether there was one.
+     *
+     * For a tool whose EXISTENCE is not decided here: an MCP server may stop exporting a tool between
+     * one `tools/list` and the next, and leaving the old spec registered would go on offering the
+     * model a tool whose next call fails on somebody else's machine. Whoever registered a name is
+     * responsible for deciding when it is gone — nothing in the registry itself expires.
+     */
+    unregister(name) {
+        return this.entries.delete(name);
+    }
     has(name) {
         return this.entries.has(name);
     }

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/types.d.ts

@@ -7,13 +7,23 @@ export interface Actor {
     roles?: string[];
     tenantRef?: string;
 }
-export type ToolKind = 'read' | 'action' | 'agent';
+export type ToolKind = 'read' | 'action' | 'agent' | 'ask' | 'skill' | 'memory';
 /**
  * Declared shape of a tool.
  *  - `read`   auto-executes.
  *  - `action` never auto-executes — requires HITL approval.
  *  - `agent`  delegates to another named agent (durable: a child workflow; inline: a nested loop),
  *             handled at the loop level — NOT via a handler. Carries `targetAgent`.
+ *  - `ask`    puts a structured question set to the user and parks. Carried by no {@link ToolSpec}:
+ *             `ask` has no handler and is never registered, it is offered to the model straight from
+ *             module config — so the branch that decides whether a call parks on a human can never
+ *             be settled by a process-local registry lookup.
+ *  - `skill`  reads an authored procedure out of the catalog the turn's `skills:catalog` checkpoint
+ *             holds. Registered by nothing, for the same reason `ask` is not, and it spends a read's
+ *             checkpoints exactly — see `skills.ts`.
+ *  - `memory` writes one durable fact about the actor, authorized against the scopes the turn's
+ *             `memory:digest` checkpoint holds. Registered by nothing, and spends a read's
+ *             checkpoints exactly — see `memory.ts`.
  */
 export interface ToolSpec {
     name: string;
@@ -101,7 +111,7 @@ export interface MessageUsage {
  * ledger inteiro, sem filtrar propósito, então registrar aqui é o que faz o gasto de RAG passar a
  * contar contra o teto diário.
  */
-export type UsagePurpose = 'chat' | 'title' | 'follow_ups' | 'summary' | 'embedding';
+export type UsagePurpose = 'chat' | 'title' | 'follow_ups' | 'summary' | 'embedding' | 'structured_output';
 export interface QuotaState {
     usedTokens: number;
     limitTokens: number;
@@ -111,6 +121,8 @@ export interface QuotaState {
 export interface Decision {
     approved: boolean;
     reason?: string;
+    /** Opaque ref of WHO decided, when it wasn't the run's own actor. */
+    executedByRef?: string;
 }
 export type MessageRole = 'user' | 'assistant' | 'system';
 /**
@@ -183,6 +195,27 @@ export interface AgentRunInput {
     day?: string;
     /** Which named agent runs this turn. Omitted → the default/single agent. */
     agentName?: string;
+    /**
+     * The run that started this one (a delegation's parent). Recorded with the run so a governance
+     * surface can roll a delegation's cost up to the turn that asked for it; without it a child run is
+     * a row with nothing pointing at it outside the durable engine's own journal.
+     */
+    parentRunId?: string;
+    /**
+     * How many agent→agent delegations deep this run already is (0 for a top-level turn). The runner
+     * increments it for each child run; the loop refuses to delegate past its depth ceiling.
+     */
+    delegationDepth?: number;
+    /**
+     * The named agents already on this delegation chain, root first — what {@link delegationDepth}
+     * counts, spelled out. The runner appends its own agent's name for each child it starts.
+     *
+     * A count can only say a chain is LONG. This says whether it is going in circles, and how often:
+     * an agent that appears here is one the chain has already passed through, so a delegation back to
+     * it is a cycle by inspection rather than by proxy. A run whose runner supplies none falls back to
+     * the depth ceiling alone.
+     */
+    delegationPath?: readonly string[];
 }
 /**
  * One `agent → agent` delegation edge, with the authorization the synthesized `ask_<target>` tool
@@ -241,6 +274,16 @@ export interface AgentDefinition {
     defaultPersona?: string;
     modelId?: string;
     maxSteps?: number;
+    /**
+     * How many agent→agent delegations deep a chain starting at this agent may go.
+     * Undefined → {@link import('./agent-loop.js').MAX_DELEGATION_DEPTH}.
+     */
+    maxDelegationDepth?: number;
+    /**
+     * How many times one agent may appear on a single delegation chain.
+     * Undefined → {@link import('./agent-loop.js').DEFAULT_MAX_AGENT_APPEARANCES}.
+     */
+    maxAgentAppearances?: number;
     /**
      * 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
@@ -269,6 +312,16 @@ export interface StoredMessage {
     attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
+    /** The persona that was active when the message was written; absent when none was selected. */
+    persona?: string;
+    /**
+     * The run (turn) that wrote this message. Without it a reader can only guess which turn a message
+     * belongs to by comparing timestamps against the run's `startedAt`, and that guess breaks the
+     * moment a turn is regenerated: regeneration truncates the replaced answer and re-answers the
+     * SURVIVING user message without appending a new one, so walking forward by time hands the older
+     * run the replacement's text. Absent on a row written outside a run.
+     */
+    runId?: string;
     createdAt: string;
 }
 export interface ThreadDetail extends ThreadSummary {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.30.2",
+  "version": "0.33.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,11 @@
       "import": "./dist/src/mcp/index.js",
       "default": "./dist/src/mcp/index.js"
     },
+    "./mcp-client": {
+      "types": "./dist/src/mcp-client/index.d.ts",
+      "import": "./dist/src/mcp-client/index.js",
+      "default": "./dist/src/mcp-client/index.js"
+    },
     "./mcp_provider": {
       "types": "./dist/providers/mcp_provider.d.ts",
       "import": "./dist/providers/mcp_provider.js",
@@ -78,6 +83,11 @@
       "import": "./dist/src/stores/lucid.js",
       "default": "./dist/src/stores/lucid.js"
     },
+    "./evals": {
+      "types": "./dist/src/evals/index.d.ts",
+      "import": "./dist/src/evals/index.js",
+      "default": "./dist/src/evals/index.js"
+    },
     "./data": {
       "types": "./dist/src/data/index.d.ts",
       "import": "./dist/src/data/index.js",
@@ -133,7 +143,7 @@
     "ai": "^7.0.0",
     "node-sql-parser": "^5.3.0",
     "react": "^18.0.0 || ^19.0.0",
-    "zod": "^3.23.0 || ^4.0.0"
+    "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -177,25 +187,25 @@
     }
   },
   "devDependencies": {
-    "@adonis-agora/authz": "0.13.2",
-    "@adonis-agora/diagnostics": "0.2.8",
-    "@adonis-agora/durable": "0.34.0",
-    "@adonis-agora/telescope": "0.17.0",
+    "@adonis-agora/authz": "0.13.3",
+    "@adonis-agora/diagnostics": "0.2.9",
+    "@adonis-agora/durable": "0.39.1",
+    "@adonis-agora/telescope": "0.21.0",
     "@adonisjs/assembler": "8.5.1",
     "@adonisjs/core": "7.5.0",
     "@adonisjs/lucid": "22.4.2",
     "@adonisjs/redis": "11.0.0",
     "@qdrant/js-client-rest": "1.19.0",
-    "@tanstack/intent": "^0.4.0",
-    "@types/node": "26.4.1",
+    "@tanstack/intent": "0.4.0",
+    "@types/node": "26.5.0",
     "@types/react": "19.2.18",
-    "ai": "7.0.93",
+    "ai": "7.0.97",
     "better-sqlite3": "13.0.3",
     "luxon": "3.7.2",
     "node-sql-parser": "5.4.0",
     "react": "19.2.8",
     "typescript": "7.0.2",
-    "vitest": "4.1.11",
+    "vitest": "5.0.0",
     "zod": "4.5.4"
   },
   "engines": {

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

@@ -179,25 +179,29 @@ 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
+### MEDIUM — answering a delegated sub-agent's approval against the wrong run
 
 ```ts
-// Wrong assumption — nested researcher asks for approval; the run should pause.
-defaultAgent: { delegatesTo: [{ agent: 'researcher' }] }
-agents: [{ name: 'researcher', tools: ['issueRefund' /* action */] }]
+// Wrong — the nested researcher parked, but this signals the ORCHESTRATOR's run, so the
+// child stays suspended and the delegation never returns.
+const { runId } = await service.chat({ actor, message: 'go', agentName: 'orchestrator' })
+await service.approve(runId, toolCallId)
 ```
 
 ```ts
-// Correct — keep human-approval actions on the TOP-LEVEL agent only.
-agents: [
-  { name: 'researcher', tools: ['searchDocs', 'getInvoice'] }, // read tools only
-]
+// Correct — read the parked run off the frame. It is the CHILD's run, not the stream's.
+for await (const frame of service.subscribe(runId)) {
+  if (frame.t === 'approval') await service.approve(frame.runId, frame.id)
+}
 ```
 
-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).
+Mechanism: a sub-agent's `action` parks on `tool:<childRunId>:<callId>` on both runners. Its
+frames are forwarded into the top-level ancestor's stream (durable `sinkRunId`; the inline
+nested loop mirrors it), so the stream you subscribed to is NOT the run that is parked — and
+the `approval` / `elicitation` frame carries `runId` for exactly that reason. A sub-agent
+whose approvals nobody answers hangs. Source:
+`packages/adonis/docs/durability/durable-runner.mdx` ("Answering a sub-agent"),
+`packages/adonis/src/spi/token-stream-sink.ts` (`StreamFrame`).
 
 ### LOW — using wall-clock time or randomness inside a PromptBuilder