@adonis-agora/agent 0.23.0 → 0.25.0

package/dist/src/stores/lucid-schema.js

@@ -126,13 +126,88 @@ export function createTableStatements() {
         `CREATE INDEX IF NOT EXISTS "${t.runs}_status_started_idx" ON "${t.runs}" ("status", "started_at")`,
     ];
 }
+/**
+ * The `run_id` correlation columns run tracking added to three pre-existing tables. They are inline in
+ * {@link createTableStatements}, which is all a fresh database needs — but `CREATE TABLE IF NOT EXISTS`
+ * cannot add a column to a table that already exists, so a database provisioned before run tracking
+ * shipped needs them ALTERed in. Deliberately not DB foreign keys (SQLite cannot add a column WITH a
+ * FK constraint), so a row written before run tracking keeps a `null` run_id.
+ */
+const RUN_ID_COLUMNS = [
+    AGENT_TABLES.messages,
+    AGENT_TABLES.toolCalls,
+    AGENT_TABLES.tokenUsage,
+];
+/**
+ * Does `table` already have `column`? Probed with a zero-row `SELECT` rather than `information_schema`
+ * (absent on SQLite) or a `PRAGMA` (SQLite-only): every dialect rejects an unknown column at parse
+ * time, and `WHERE 1 = 0` means no rows are ever read.
+ *
+ * Deliberately NOT "attempt the ALTER and swallow the error": that pattern also swallows a permission
+ * failure, a lock timeout, and a typo, leaving a schema that is still wrong and a migration that
+ * reported success.
+ */
+async function hasColumn(db, table, column) {
+    try {
+        await db.rawQuery(`SELECT "${column}" FROM "${table}" WHERE 1 = 0`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Idempotently provision the six agent tables through Lucid's async raw runner (`CREATE TABLE IF
- * NOT EXISTS`). Works on every Lucid dialect. For an AdonisJS app prefer the published migration
- * (`node ace configure @adonis-agora/agent`); this helper is for standalone use, tests and quick-starts.
+ * NOT EXISTS`), then additively repair a database that predates run tracking by ALTERing in the
+ * `run_id` columns its three older tables are missing.
+ *
+ * Both halves matter, and for different populations. A fresh database gets everything from the
+ * `CREATE TABLE` statements and never reaches a repair branch — which is what makes a non-empty
+ * `repairs` result mean "this schema was out of date", not "boot happened". A database created before
+ * run tracking shipped has all three tables already, so every `CREATE TABLE IF NOT EXISTS` no-ops and
+ * only the repair adds the columns the store now writes on every turn.
+ *
+ * Returns the `<table>.<column>` repairs actually issued, so a caller can report them. Works on every
+ * Lucid dialect. For an AdonisJS app prefer the published migration
+ * (`node ace configure @adonis-agora/agent`); this helper is what that migration calls, and what the
+ * stores call themselves when `autoCreateTables` is on.
  */
 export async function createAgentTables(db) {
-    for (const stmt of createTableStatements()) {
+    const statements = createTableStatements();
+    // Order matters, in three phases rather than one pass. Tables first, then the `run_id` repair, then
+    // indexes — because `createTableStatements` includes `CREATE INDEX ... ON "agent_message" ("run_id")`,
+    // and on a legacy database that index would be issued against a table whose `run_id` the repair has
+    // not added yet. `CREATE INDEX IF NOT EXISTS` does not save it: the guard is on the INDEX existing,
+    // not on the column, so the statement still fails to parse with "no such column: run_id".
+    for (const stmt of statements) {
+        if (stmt.startsWith('CREATE TABLE'))
+            await db.rawQuery(stmt);
+    }
+    const repairs = [];
+    for (const table of RUN_ID_COLUMNS) {
+        if (await hasColumn(db, table, 'run_id'))
+            continue;
+        await db.rawQuery(`ALTER TABLE "${table}" ADD COLUMN "run_id" VARCHAR(255) NULL`);
+        repairs.push(`${table}.run_id`);
+    }
+    for (const stmt of statements) {
+        if (stmt.startsWith('CREATE INDEX'))
+            await db.rawQuery(stmt);
+    }
+    return repairs;
+}
+/**
+ * `DROP TABLE IF EXISTS` for the six agent tables, in reverse dependency order so a dialect that
+ * enforces the `REFERENCES` clauses never refuses a drop for a child that still exists. The mirror of
+ * {@link createAgentTables}, and what the published migration's `down()` calls.
+ */
+export function dropTableStatements() {
+    const t = AGENT_TABLES;
+    return [t.runs, t.tokenUsage, t.toolCalls, t.messages, t.modelPricing, t.threads].map((table) => `DROP TABLE IF EXISTS "${table}"`);
+}
+/** Drop the six agent tables. Destructive and irreversible — this erases every thread and every ledger row. */
+export async function dropAgentTables(db) {
+    for (const stmt of dropTableStatements()) {
         await db.rawQuery(stmt);
     }
 }
@@ -154,7 +229,9 @@ export function ensureAgentTables(db) {
     const key = db;
     let ready = provisioned.get(key);
     if (ready === undefined) {
-        ready = createAgentTables(db).catch((error) => {
+        ready = createAgentTables(db)
+            .then(() => undefined)
+            .catch((error) => {
             provisioned.delete(key);
             throw error;
         });

package/dist/src/stores/lucid-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"lucid-schema.js","sourceRoot":"","sources":["../../../src/stores/lucid-schema.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO,EAAE,cAAc;IACvB,QAAQ,EAAE,eAAe;IACzB,SAAS,EAAE,iBAAiB;IAC5B,UAAU,EAAE,mBAAmB;IAC/B,YAAY,EAAE,qBAAqB;IACnC,IAAI,EAAE,WAAW;CACT,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,CAAC,GAAG,YAAY,CAAC;IACvB,OAAO;QACL,+BAA+B,CAAC,CAAC,OAAO;;;;;;;;;;;;;;MActC;QACF,+BAA+B,CAAC,CAAC,OAAO,2BAA2B,CAAC,CAAC,OAAO,+BAA+B;QAC3G,+BAA+B,CAAC,CAAC,QAAQ;;sDAES,CAAC,CAAC,OAAO;;;;;;;;;;;MAWzD;QACF,+BAA+B,CAAC,CAAC,QAAQ,4BAA4B,CAAC,CAAC,QAAQ,+BAA+B;QAC9G,+BAA+B,CAAC,CAAC,QAAQ,iBAAiB,CAAC,CAAC,QAAQ,cAAc;QAClF,+BAA+B,CAAC,CAAC,SAAS;;uDAES,CAAC,CAAC,QAAQ;;;;;;;;;;;;MAY3D;QACF,+BAA+B,CAAC,CAAC,SAAS,iBAAiB,CAAC,CAAC,SAAS,cAAc;QACpF,+BAA+B,CAAC,CAAC,SAAS,4BAA4B,CAAC,CAAC,SAAS,4BAA4B;QAC7G,+BAA+B,CAAC,CAAC,UAAU;;sDAEO,CAAC,CAAC,OAAO;;;;;;;;;;;;MAYzD;QACF,+BAA+B,CAAC,CAAC,UAAU,2BAA2B,CAAC,CAAC,UAAU,+BAA+B;QACjH,+BAA+B,CAAC,CAAC,UAAU,iBAAiB,CAAC,CAAC,UAAU,cAAc;QACtF,+BAA+B,CAAC,CAAC,YAAY;;;;;;;;;MAS3C;QACF,+BAA+B,CAAC,CAAC,IAAI;;sDAEa,CAAC,CAAC,OAAO;;;;;;;;;;;;;MAazD;QACF,+BAA+B,CAAC,CAAC,IAAI,qBAAqB,CAAC,CAAC,IAAI,kBAAkB;QAClF,+BAA+B,CAAC,CAAC,IAAI,2BAA2B,CAAC,CAAC,IAAI,+BAA+B;QACrG,+BAA+B,CAAC,CAAC,IAAI,4BAA4B,CAAC,CAAC,IAAI,4BAA4B;KACpG,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EAAqB;IAC3D,KAAK,MAAM,IAAI,IAAI,qBAAqB,EAAE,EAAE,CAAC;QAC3C,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,GAAG,IAAI,OAAO,EAAyB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAqB;IACrD,MAAM,GAAG,GAAG,EAAuB,CAAC;IACpC,IAAI,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,KAAK,GAAG,iBAAiB,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAC5C,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"lucid-schema.js","sourceRoot":"","sources":["../../../src/stores/lucid-schema.ts"],"names":[],"mappings":"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"}

package/dist/src/types.d.ts

@@ -31,8 +31,9 @@ export interface ToolSpec {
     roles?: string[];
     /**
      * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
-     * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. Apps that don't use authz ignore it
-     * and rely on `roles` instead — both live on the same SPI, so neither is required.
+     * such as the `@adonis-agora/agent/authz` Bouncer adapter (`authzToolAuthorizer`), which denies
+     * every tool that declares none. Apps that don't use authz ignore it and rely on `roles` instead —
+     * both live on the same SPI, so neither is required.
      */
     ability?: string;
 }
@@ -175,10 +176,39 @@ export interface AgentRunInput {
     agentName?: string;
 }
 /**
- * A named agent: its prompt, the tools it may use, and its personas. Multiple definitions are
- * registered via `AgentModule.forFeature([...])`; an orchestrator delegates to others through
- * `ctx.runAgent(name, task)`. Model/store/sink/governance are shared from the module unless
- * overridden here.
+ * One `agent → agent` delegation edge, with the authorization the synthesized `ask_<target>` tool
+ * carries. The object form exists because delegation goes through the same {@link ToolSpec} gate as
+ * every other tool: a spec with neither `roles` nor `ability` is denied by both shipped authorizers,
+ * so an orchestrator that must actually delegate has to say who may.
+ *
+ * ```ts
+ * // Role-based (the default `DefaultToolAuthorizer`):
+ * { name: 'orchestrator', delegatesTo: [{ agent: 'researcher', roles: ['ANALYST', 'ADMIN'] }] }
+ *
+ * // Ability-based (the `@adonis-agora/agent/authz` Bouncer adapter):
+ * { name: 'orchestrator', delegatesTo: [{ agent: 'researcher', ability: 'agent.delegate' }] }
+ * ```
+ */
+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?: string[];
+    /**
+     * Ability the synthesized delegate tool declares. REQUIRED under an ability-aware authorizer such
+     * as `authzToolAuthorizer`, which denies every tool that declares none — omit it there and the
+     * delegation is denied on every call.
+     */
+    ability?: string;
+}
+/**
+ * A named agent: its prompt, the tools it may use, and its personas. Definitions are registered in
+ * `config/agent.ts` under `agents: [...]`; an orchestrator delegates to the others it names in
+ * {@link AgentDefinition.delegatesTo}, which the factory turns into `ask_<target>` tools. Model,
+ * store, sink and governance are shared from the module config unless overridden here.
  */
 export interface AgentDefinition {
     name: string;
@@ -186,8 +216,18 @@ export interface AgentDefinition {
     systemPrompt?: string | PromptBuilder;
     /** Allow-list of tool names this agent may use (subset of all registered tools). */
     tools?: string[];
-    /** Names of other agents this agent may delegate to (auto-registered as `agent`-kind tools). */
-    delegatesTo?: string[];
+    /**
+     * 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
+     * {@link DelegateEdge} object form to declare the `roles` and/or `ability` the delegate tool
+     * carries.
+     */
+    delegatesTo?: (string | DelegateEdge)[];
     personas?: Persona[];
     defaultPersona?: string;
     modelId?: string;

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/database/migrations/create_agent_rag_chunks.stub

@@ -2,37 +2,42 @@
   exports({ to: app.migrationsPath(`${new Date().getTime()}_create_agent_rag_chunks.ts`) })
 }}}
 import { BaseSchema } from '@adonisjs/lucid/schema'
+import db from '@adonisjs/lucid/services/db'
+import { PgVectorStore } from '@adonis-agora/agent'
 
 /**
  * The pgvector chunk table for the @adonis-agora/agent `retrievers.pgvector({...})` store: one row per
  * embedded chunk (id `${documentId}#<n>`), the chunk text, an optional citation source, a `jsonb`
  * metadata column filtered with `@>`, and the `vector(N)` embedding ranked with the `<=>`/`<->`/`<#>`
- * operators. Requires the pgvector extension (`CREATE EXTENSION vector`) — Postgres only.
+ * operators. Requires the pgvector extension — Postgres only. Delete this file if you do not use
+ * pgvector RAG.
  *
- * Set `DIMENSION` to your embedding model's width (e.g. 1536 for text-embedding-3-small) and `OPCLASS`
- * to the index operator class matching the store's metric: `vector_cosine_ops` (default),
- * `vector_l2_ops`, or `vector_ip_ops`.
+ * Like the agent tables migration, this DELEGATES rather than copying DDL: `PgVectorStore` owns the
+ * column names and the index operator class its own queries depend on, and it exposes the same
+ * provisioning the store runs for itself under `ensureSchema: true`. Every statement is
+ * `IF NOT EXISTS`, so this is safe against a database that already has the table.
+ *
+ * SET THESE to match your retriever config in `config/agent.ts` — they must agree, or the store will
+ * query a table shaped differently from the one this created:
+ *   - `DIMENSION` — your embedding model's width (1536 for text-embedding-3-small).
+ *   - `METRIC` — 'cosine' (default), 'l2', or 'inner'. Picks the index operator class.
+ *   - `TABLE` — only if you overrode `table` on the retriever.
  */
 const TABLE = 'agent_rag_chunks'
 const DIMENSION = 1536
-const OPCLASS = 'vector_cosine_ops'
+const METRIC = 'cosine'
 
 export default class extends BaseSchema {
-  async up() {
-    this.schema.raw('CREATE EXTENSION IF NOT EXISTS vector')
+  /** Same reason as the agent tables migration: the DDL runs on the manager's own pooled connection. */
+  static disableTransactions = true
 
-    this.schema.createTable(TABLE, (table) => {
-      table.text('id').primary()
-      table.text('text').notNullable()
-      table.text('source')
-      table.jsonb('metadata')
-      table.specificType('embedding', `vector(${DIMENSION})`).notNullable()
+  async up() {
+    const store = new PgVectorStore(db.connection(this.db.connectionName), {
+      table: TABLE,
+      dimension: DIMENSION,
+      metric: METRIC,
     })
-
-    // Approximate-nearest-neighbour index for the configured metric. Drop it to fall back to an exact scan.
-    this.schema.raw(
-      `CREATE INDEX IF NOT EXISTS ${TABLE}_embedding_idx ON ${TABLE} USING hnsw (embedding ${OPCLASS})`
-    )
+    await store.ensureSchema()
   }
 
   async down() {

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

@@ -2,112 +2,48 @@
   exports({ to: app.migrationsPath(`${new Date().getTime()}_create_agent_tables.ts`) })
 }}}
 import { BaseSchema } from '@adonisjs/lucid/schema'
+import db from '@adonisjs/lucid/services/db'
+import { createAgentTables, dropAgentTables } from '@adonis-agora/agent'
 
 /**
- * The five tables for the @adonis-agora/agent `lucid` store: threads, messages, tool calls, token
- * usage and model pricing. JSON payloads (tool calls/results, follow-ups, usage, tool input/output)
- * are stored as TEXT — the store (de)serializes them — booleans as INTEGER (0/1), and timestamps as
- * epoch-ms integers, so the schema is portable across SQLite / Postgres / MySQL. The `agent_tool_call`
- * primary key is the model-supplied `toolCallId`, not a generated id.
+ * The six tables for the @adonis-agora/agent `lucid` store: threads, messages, tool calls, token
+ * usage, model pricing, and the run lifecycle — 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
+ * columns they read and write, so a hand-copied snapshot here can only ever be right until the next
+ * release. It was already wrong in two ways. It reproduced `createTable(...)` with no existence guard,
+ * which THROWS on a database where the tables are already there — and they usually are, because
+ * `autoCreateTables` defaults to `true` and any of those three stores provisions the shared schema on
+ * its first use. And it took two files to say what the library says in one: a second additive migration
+ * existed purely to ALTER in the `run_id` columns this one had been written before.
+ *
+ * `createAgentTables` is idempotent (`CREATE TABLE IF NOT EXISTS`) and additive-only: it creates what
+ * is missing and ALTERs the `run_id` columns into a database that predates run tracking. So it is safe
+ * against an empty database, against one the library already auto-created, and against one left over
+ * from an older version — which is exactly the set of states a real app is in.
+ *
+ * `db` (the `Database` manager from `@adonisjs/lucid/services/db`) rather than `this.db`: the manager
+ * checks out its own connection from the pool, which is what keeps the DDL out of the migrator's
+ * transaction (see `disableTransactions` below). `this.db` still supplies the connection NAME, so
+ * `node ace migration:run --connection=x` provisions the tables on connection `x` and not on the default.
  */
 export default class extends BaseSchema {
-  async up() {
-    this.schema.createTable('agent_thread', (table) => {
-      table.string('id').primary()
-      table.string('actor_ref').notNullable()
-      table.string('tenant_ref')
-      table.text('title').notNullable()
-      table.string('persona').notNullable().defaultTo('default')
-      table.integer('transient').notNullable().defaultTo(0)
-      table.bigInteger('pinned_at')
-      table.text('summary')
-      table.integer('summary_message_count').notNullable().defaultTo(0)
-      table.string('active_stream_id')
-      table.bigInteger('created_at').notNullable()
-      table.bigInteger('updated_at').notNullable()
-      table.bigInteger('deleted_at')
-      table.index(['actor_ref', 'updated_at'], 'agent_thread_actor_updated_idx')
-    })
-
-    this.schema.createTable('agent_message', (table) => {
-      table.string('id').primary()
-      table
-        .string('thread_id')
-        .notNullable()
-        .references('id')
-        .inTable('agent_thread')
-        .onDelete('CASCADE')
-      table.string('role').notNullable()
-      table.text('content').notNullable()
-      table.text('tool_calls')
-      table.text('tool_results')
-      table.text('attachments')
-      table.text('follow_ups')
-      table.text('usage')
-      table.string('persona')
-      table.bigInteger('created_at').notNullable()
-      table.index(['thread_id', 'created_at'], 'agent_message_thread_created_idx')
-    })
-
-    this.schema.createTable('agent_tool_call', (table) => {
-      // PK = the model-supplied toolCallId, not a generated id.
-      table.string('id').primary()
-      table
-        .string('message_id')
-        .notNullable()
-        .references('id')
-        .inTable('agent_message')
-        .onDelete('CASCADE')
-      table.string('tool_name').notNullable()
-      table.string('tool_type').notNullable()
-      table.text('input')
-      table.text('output')
-      table.string('status').notNullable()
-      table.string('executed_by_ref')
-      table.integer('execution_ms')
-      table.text('error')
-      table.bigInteger('created_at').notNullable()
-      table.bigInteger('executed_at')
-    })
+  /**
+   * REQUIRED, not a preference. The DDL below runs on a connection the `Database` manager checks out
+   * itself — it is not part of the transaction the migrator would otherwise open for this migration.
+   * With `pool: { max: 1 }` (Adonis's own SQLite guidance) that transaction would hold the only
+   * connection while `createAgentTables` waited for a free one, and the migration would hang until the
+   * acquire timeout. Nothing is lost by opting out: the statements were never inside that transaction
+   * anyway, and re-running an interrupted `createAgentTables` is a no-op.
+   */
+  static disableTransactions = true
 
-    this.schema.createTable('agent_token_usage', (table) => {
-      table.string('id').primary()
-      table
-        .string('thread_id')
-        .notNullable()
-        .references('id')
-        .inTable('agent_thread')
-        .onDelete('CASCADE')
-      table.string('actor_ref').notNullable()
-      table.string('message_id')
-      table.string('model_id').notNullable()
-      table.string('purpose').notNullable()
-      table.integer('input_tokens').notNullable()
-      table.integer('output_tokens').notNullable()
-      table.integer('cache_write_tokens')
-      table.integer('cache_read_tokens')
-      table.double('cost_usd')
-      table.bigInteger('created_at').notNullable()
-      table.index(['actor_ref', 'created_at'], 'agent_token_usage_actor_created_idx')
-    })
-
-    this.schema.createTable('agent_model_pricing', (table) => {
-      table.string('id').primary()
-      table.string('model_id').notNullable()
-      table.double('input_price_per_1m').notNullable()
-      table.double('output_price_per_1m').notNullable()
-      table.double('cache_write_price_per_1m')
-      table.double('cache_read_price_per_1m')
-      table.bigInteger('effective_from').notNullable()
-      table.integer('is_current').notNullable()
-    })
+  async up() {
+    await createAgentTables(db.connection(this.db.connectionName))
   }
 
   async down() {
-    this.schema.dropTableIfExists('agent_model_pricing')
-    this.schema.dropTableIfExists('agent_token_usage')
-    this.schema.dropTableIfExists('agent_tool_call')
-    this.schema.dropTableIfExists('agent_message')
-    this.schema.dropTableIfExists('agent_thread')
+    await dropAgentTables(db.connection(this.db.connectionName))
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/agent",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.",
   "license": "MIT",
   "repository": {
@@ -196,7 +196,7 @@
     "zod": "3.25.76"
   },
   "engines": {
-    "node": "v22.23.2"
+    "node": ">=20.6.0"
   },
   "keywords": [
     "adonisjs",

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

@@ -1,80 +0,0 @@
-{{{
-  exports({ to: app.migrationsPath(`${new Date().getTime()}_create_agent_run_tracking.ts`) })
-}}}
-import { BaseSchema } from '@adonisjs/lucid/schema'
-
-/**
- * Additive migration for @adonis-agora/agent RUN tracking. Adds the `agent_run` table (one row per
- * run/turn lifecycle) plus a nullable `run_id` correlation column on `agent_message`,
- * `agent_tool_call` and `agent_token_usage`. `run_id` is deliberately NOT a DB foreign key (like the
- * reference): it can be `ALTER TABLE ADD COLUMN`-ed portably (SQLite can't add a column WITH a FK
- * constraint) and a row written before this shipped keeps a `null` run_id.
- *
- * Timestamps are epoch-ms integers, booleans INTEGER (0/1) and cost a DOUBLE, matching
- * `create_agent_tables` so the schema stays portable across SQLite / Postgres / MySQL. Safe to run on
- * an existing deployment: it only creates a new table and adds nullable columns.
- */
-export default class extends BaseSchema {
-  async up() {
-    this.schema.createTable('agent_run', (table) => {
-      table.string('id').primary()
-      table
-        .string('thread_id')
-        .notNullable()
-        .references('id')
-        .inTable('agent_thread')
-        .onDelete('CASCADE')
-      table.string('agent_name')
-      table.string('actor_ref').notNullable()
-      table.string('tenant_ref')
-      table.string('status').notNullable()
-      table.bigInteger('started_at').notNullable()
-      table.bigInteger('finished_at')
-      table.integer('step_count').notNullable().defaultTo(0)
-      table.integer('input_tokens').notNullable().defaultTo(0)
-      table.integer('output_tokens').notNullable().defaultTo(0)
-      table.double('cost_usd')
-      table.text('error')
-      table.integer('durable').notNullable().defaultTo(0)
-      table.index(['started_at'], 'agent_run_started_idx')
-      table.index(['actor_ref', 'started_at'], 'agent_run_actor_started_idx')
-      table.index(['status', 'started_at'], 'agent_run_status_started_idx')
-    })
-
-    this.schema.alterTable('agent_message', (table) => {
-      table.string('run_id')
-      table.index(['run_id'], 'agent_message_run_idx')
-    })
-
-    this.schema.alterTable('agent_tool_call', (table) => {
-      table.string('run_id')
-      table.index(['run_id'], 'agent_tool_call_run_idx')
-      table.index(['status', 'created_at'], 'agent_tool_call_status_created_idx')
-    })
-
-    this.schema.alterTable('agent_token_usage', (table) => {
-      table.string('run_id')
-      table.index(['run_id'], 'agent_token_usage_run_idx')
-    })
-  }
-
-  async down() {
-    this.schema.alterTable('agent_token_usage', (table) => {
-      table.dropIndex(['run_id'], 'agent_token_usage_run_idx')
-      table.dropColumn('run_id')
-    })
-
-    this.schema.alterTable('agent_tool_call', (table) => {
-      table.dropIndex(['status', 'created_at'], 'agent_tool_call_status_created_idx')
-      table.dropIndex(['run_id'], 'agent_tool_call_run_idx')
-      table.dropColumn('run_id')
-    })
-
-    this.schema.alterTable('agent_message', (table) => {
-      table.dropIndex(['run_id'], 'agent_message_run_idx')
-      table.dropColumn('run_id')
-    })
-
-    this.schema.dropTableIfExists('agent_run')
-  }
-}