@adonis-agora/agent 0.25.1 → 0.25.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @adonis-agora/agent
 
+## 0.25.2
+
+### Patch Changes
+
+- [#79](https://github.com/DavideCarvalho/adonis-agora-agent/pull/79) [`88018eb`](https://github.com/DavideCarvalho/adonis-agora-agent/commit/88018ebfeef32be65c464b075d692b62a369d3fd) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Fix `node ace configure @adonis-agora/agent`, which was broken in every published version.
+
+  The configure codemod runs each stub through Tempura, which compiles the stub **body** into a JavaScript
+  template literal. A bare backtick in the body closes that literal; a bare `${` opens an interpolation.
+  All four published stubs were full of both, in ordinary JSDoc prose — `` `lucid` ``, `` `model` ``,
+  `` `${documentId}#<n>` `` — so every one of them threw at render time.
+
+  `configure` therefore aborted on the very first stub, _after_ `updateRcFile` had already succeeded. The
+  result was worse than nothing happening: `adonisrc.ts` came out referencing the agent and dashboard
+  providers while `config/agent.ts` was never written, leaving an app that could not boot.
+
+  Both constructs are now backslash-escaped in the stub bodies (`` \` ``, `\${`). This is a render-time
+  concern only — the generated files are **byte-identical** to what the stubs always intended, backticked
+  prose and all, which was verified against the pre-fix sources.
+
+  The reason no gate caught this: every stub harness here rendered by stripping the `{{{ }}}` header with a
+  regex and using the remainder, which is not what the generator does. A gate that renders differently from
+  the generator is not testing the generator. All of them now render through the real engine
+  (`app.stubs.create().build().prepare()`), and a new `stub-render.spec.ts` asserts that every stub
+  `configure.ts` publishes actually renders — including the two config stubs, which no test had touched.
+
+  Users on an earlier version who ran `configure` and saw it fail should re-run it after upgrading; if
+  `adonisrc.ts` already lists the providers, the codemod is idempotent and only the missing files are written.
+
 ## 0.25.1
 
 ### Patch Changes

package/dist/src/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.25.1";
+export declare const VERSION = "0.25.2";
 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.1';
+export const VERSION = '0.25.2';
 export * from './types.js';
 export * from './spi/tool.js';
 export * from './base-tool.js';

package/dist/stubs/config/agent.stub

@@ -7,17 +7,17 @@ import { defineConfig, stores, AuthActorResolver } from '@adonis-agora/agent'
 // import { openai } from '@ai-sdk/openai'
 
 /**
- * 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
+ * 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.
  *
- * Publish the tables with `node ace migration:run` after configuring.
+ * Publish the tables with \`node ace migration:run\` after configuring.
  */
 export default defineConfig({
   /**
-   * The LLM provider. Wrap the Vercel AI SDK via `aiSdkModel(...)` (from `@adonis-agora/agent/ai-sdk`)
-   * or supply any `ModelProvider`. A lazy thunk keeps the provider SDK peer imported only at boot:
+   * The LLM provider. Wrap the Vercel AI SDK via \`aiSdkModel(...)\` (from \`@adonis-agora/agent/ai-sdk\`)
+   * or supply any \`ModelProvider\`. A lazy thunk keeps the provider SDK peer imported only at boot:
    *
    *   model: () => aiSdkModel({ model: openai('gpt-4o-mini') }),
    */
@@ -40,7 +40,7 @@ export default defineConfig({
   // maxSteps: 8,              // cap on model↔tool iterations per turn
 
   // Governance console — served automatically at <path>/dashboard (default /agent/dashboard), no
-  // separate install. It only mounts once `governanceAuthorize` is set (every panel but Quota reads
+  // separate install. It only mounts once \`governanceAuthorize\` is set (every panel but Quota reads
   // the cross-actor governance routes, which need that gate too — see the docs). Toggle it off,
   // relocate it, or add an extra gate on top of governanceAuthorize:
   // dashboard: { enabled: true, path: '/agent/dashboard', authorize: (actor) => actor.roles?.includes('ADMIN') ?? false },
@@ -48,7 +48,7 @@ export default defineConfig({
 
   // Multimodal uploads — mounts POST /agent/attachments, which stages a file into a model-fetchable
   // MessageAttachment the client sends back with its next chat message. Bind your own store (presign
-  // S3/GCS or wrap your media pipeline); `attachmentStores.memory()` inlines bytes as a data: URL.
+  // S3/GCS or wrap your media pipeline); \`attachmentStores.memory()\` inlines bytes as a data: URL.
   // attachmentStaging: attachmentStores.memory(),
   // attachmentMaxBytes: 20 * 1024 * 1024,
   // attachmentAllowedContentTypes: ['image/png', 'image/jpeg', 'application/pdf'],

package/dist/stubs/config/mcp.stub

@@ -6,10 +6,10 @@ import { defineMcpConfig, authKitAuth } from '@adonis-agora/agent/mcp'
 
 /**
  * Configuration for the MCP (Model Context Protocol) endpoint. The provider exposes the agent's tool
- * registry over Streamable HTTP: `tools/list` mirrors the tools the acting actor may call and
- * `tools/call` runs them through the same role-checked registry the agent loop uses.
+ * registry over Streamable HTTP: \`tools/list\` mirrors the tools the acting actor may call and
+ * \`tools/call\` runs them through the same role-checked registry the agent loop uses.
  *
- * Requires `@adonis-agora/agent`'s agent provider (which owns the ToolRegistry singleton) to be
+ * Requires \`@adonis-agora/agent\`'s agent provider (which owns the ToolRegistry singleton) to be
  * registered. Register the MCP provider in adonisrc.ts:
  *
  *   providers: [
@@ -17,8 +17,8 @@ import { defineMcpConfig, authKitAuth } from '@adonis-agora/agent/mcp'
  *     () => import('@adonis-agora/agent/mcp_provider'),
  *   ]
  *
- * The endpoint mounts at `/mcp`. When `auth` exposes OAuth metadata (authKitAuth), MCP clients discover
- * the login flow at `/.well-known/oauth-protected-resource/mcp`.
+ * The endpoint mounts at \`/mcp\`. When \`auth\` exposes OAuth metadata (authKitAuth), MCP clients discover
+ * the login flow at \`/.well-known/oauth-protected-resource/mcp\`.
  */
 export default defineMcpConfig({
   name: 'Agent MCP Server',

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

@@ -6,22 +6,22 @@ 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 `<=>`/`<->`/`<#>`
+ * 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 — Postgres only. Delete this file if you do not use
  * pgvector RAG.
  *
- * Like the agent tables migration, this DELEGATES rather than copying DDL: `PgVectorStore` owns the
+ * 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.
+ * 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
+ * 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.
+ *   - \`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

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

@@ -6,36 +6,36 @@ import db from '@adonisjs/lucid/services/db'
 import { createAgentTables, dropAgentTables } from '@adonis-agora/agent'
 
 /**
- * The six tables for the @adonis-agora/agent `lucid` store: threads, messages, tool calls, token
+ * 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
+ * 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,
+ * 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
+ * \`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.
+ * 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
+ * \`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
+ * \`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.
+ * 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 {
   /**
-   * REQUIRED, not a preference. The DDL below runs on a connection the `Database` manager checks out
+   * 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
+   * 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.
+   * anyway, and re-running an interrupted \`createAgentTables\` is a no-op.
    */
   static disableTransactions = true
 

package/package.json

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