@adonis-agora/agent 0.25.1 → 0.25.3

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

@@ -0,0 +1,220 @@
+---
+name: agent-personas-agents
+description: >-
+  Shape @adonis-agora/agent behavior per request: personas (Persona { id, label,
+  systemPrompt string | PromptBuilder, allowedTools }, defaultPersona, the
+  /agent/threads/personas/catalog route), named agents (agents: AgentDefinition[] with
+  tools/maxSteps/actorResolver overrides), delegatesTo multi-agent delegation via
+  synthesized ask_<target> agent-kind tools and DelegateEdge { agent, roles, ability },
+  HITL approval flow over POST /agent/tool-call/approve|reject with pending_approval
+  status, maxSteps budgeting, and PromptContext/basePrompt composition. Use for
+  "persona picker", "orchestrator delegates to specialists", "ask_researcher denied",
+  "action tool hangs waiting for approval", "prompt builder".
+metadata:
+  type: core
+  library: "@adonis-agora/agent"
+  library_version: "0.25.2"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/authoring/personas-and-agents.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/streaming-and-http.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/types.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/agent-loop.ts"
+---
+
+# Personas, named agents & delegation
+
+The default setup is one agent. Two features extend it: **personas** reshape a single
+agent per request (prompt + optional tool allow-list), and **named agents** with
+`delegatesTo` turn one assistant into a small team that hands work around through
+synthesized `ask_<target>` tools.
+
+## Setup
+
+Personas on the implicit default agent; the caller selects one via `POST /agent/chat`'s
+`persona` field, and it pins to the thread:
+
+```ts
+// config/agent.ts
+export default defineConfig({
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+  store: 'lucid',
+  stores: { lucid: stores.lucid() },
+  actorResolver: new AuthActorResolver(),
+  defaultAgent: {
+    systemPrompt: 'You are the assistant for our store.',
+    defaultPersona: 'shopper',
+    personas: [
+      {
+        id: 'shopper',
+        label: 'Shopping assistant',
+        systemPrompt: 'Help the customer find and track products. Be concise.',
+        allowedTools: ['getOrder', 'searchProducts'],
+      },
+      {
+        id: 'support',
+        label: 'Support agent',
+        systemPrompt: 'Help resolve issues. You may issue refunds with approval.',
+        allowedTools: ['getOrder', 'issueRefund'],
+      },
+    ],
+  },
+})
+```
+
+A persona's `systemPrompt` resolves WITH the agent's base prompt available as
+`basePrompt`, so it can wrap rather than discard; it may be a `PromptBuilder`
+(`(ctx: PromptContext) => string | Promise<string>`) composed from actor/persona/
+pageContext. Render a picker from `GET /agent/threads/personas/catalog`.
+
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx`.
+
+## Core patterns
+
+### Pattern 1 — orchestrator delegating to named specialists
+
+Each `delegatesTo` edge auto-registers an `agent`-kind tool named `ask_<target>`
+(non-alphanumerics become underscores) whose input is `{ task }`. You never write its
+handler — the loop runs the target and feeds the answer back:
+
+```ts
+// config/agent.ts
+export default defineConfig({
+  // ...
+  defaultAgent: {
+    name: 'orchestrator',
+    systemPrompt: 'You coordinate specialists. Delegate work, then summarize.',
+    delegatesTo: [
+      { agent: 'researcher', roles: ['ANALYST', 'ADMIN'] },   // role-based gate
+      { agent: 'billing', ability: 'agent.delegate.billing' }, // ability-based gate (authz)
+    ],
+  },
+  agents: [
+    { name: 'researcher', systemPrompt: 'You research questions using read tools.', tools: ['searchDocs'] },
+    { name: 'billing', systemPrompt: 'You handle billing. Refunds require approval.', tools: ['getInvoice', 'issueRefund'] },
+  ],
+})
+```
+
+When the target has a flat-string base prompt, it is appended to the delegate tool's
+generated description so the orchestrator's model knows what the specialist is for.
+
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` ("Multi-agent
+delegation", "How a delegate tool is named").
+
+### Pattern 2 — approving a paused `action` tool (HITL)
+
+An `action` call records `pending_approval` and suspends the run; the client reads the
+pending `toolCallId` from thread detail, then decides. The decision is scoped to one
+`(runId, toolCallId)` pair, so one run can never approve another's call:
+
+```bash
+curl http://localhost:3333/agent/tool-call/approve \
+  -H 'content-type: application/json' \
+  -d '{"runId":"<runId>","toolCallId":"<toolCallId>"}'
+
+curl http://localhost:3333/agent/tool-call/reject \
+  -H 'content-type: application/json' \
+  -d '{"runId":"<runId>","toolCallId":"<toolCallId>","reason":"not this account"}'
+```
+
+On reject, the reason is fed back to the model and the turn continues. A UI can also poll
+`GET /agent/approvals/mine` — the calling actor's own pending approvals.
+
+Source: `packages/adonis/docs/streaming-and-http.mdx` ("Human-in-the-loop").
+
+### Pattern 3 — cap runaway loops with `maxSteps`
+
+`maxSteps` bounds model↔tool iterations per turn (default 8). Give a shallow specialist a
+smaller budget than the orchestrator:
+
+```ts
+agents: [
+  { name: 'summarizer', systemPrompt: 'Summarize in one pass.', maxSteps: 2 },
+]
+```
+
+Source: `packages/adonis/src/types.ts` (`AgentDefinition.maxSteps`),
+`packages/adonis/src/agent-loop.ts` (`const maxSteps = deps.maxSteps ?? 8`).
+
+## Common mistakes
+
+### HIGH — bare-string `delegatesTo` edges under non-admin callers or authz
+
+```ts
+// Wrong — declares NO roles and NO ability.
+delegatesTo: ['researcher']
+```
+
+```ts
+// Correct — say who may delegate.
+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.
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` ("Authorizing a
+delegation"), `packages/adonis/src/types.ts` (`DelegateEdge`).
+
+### MEDIUM — debugging "the orchestrator ignored the specialist" as a prompt problem
+
+```ts
+// Symptom — the model apologizes and answers alone; no visible error anywhere.
+// The delegation was DENIED and recorded failed:
+//   { toolName: 'ask_researcher', status: 'failed', error: 'Tool "ask_researcher" is not allowed...' }
+```
+
+```ts
+// Correct move — check the tool-call feed (governance read-model / dashboard Tool calls panel).
+// A denied delegation persists as failed — never auto_executed — and the error text goes back
+// to the model as a tool result, which it paraphrases away silently.
+```
+
+Mechanism: the loop re-applies all three gates before delegating (offered-tools check,
+role check, input validation); on denial it records the call `failed`, skips
+`agent.delegated`, and pushes `{ output: null, error }` into the transcript — so the run
+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
+
+```ts
+// Wrong assumption — nested researcher asks for approval; the run should pause.
+defaultAgent: { delegatesTo: [{ agent: 'researcher' }] }
+agents: [{ name: 'researcher', tools: ['issueRefund' /* action */] }]
+```
+
+```ts
+// Correct — keep human-approval actions on the TOP-LEVEL agent only.
+agents: [
+  { name: 'researcher', tools: ['searchDocs', 'getInvoice'] }, // read tools only
+]
+```
+
+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).
+
+### LOW — using wall-clock time or randomness inside a PromptBuilder
+
+```ts
+// Wrong — non-deterministic prompt; a durable replay recomputes a DIFFERENT prompt.
+const builder: PromptBuilder = async (ctx) => `${ctx.basePrompt}\nNow: ${new Date().toISOString()}`
+```
+
+```ts
+// Correct — derive from stable inputs (actor/persona/pageContext) resolved once per turn.
+const builder: PromptBuilder = (ctx) => `${ctx.basePrompt}\nAssist ${ctx.actor.id} in ${ctx.actor.tenantRef ?? 'the org'}.`
+```
+
+Mechanism: the loop resolves the effective system prompt exactly once per turn from
+stable context; injecting entropy breaks replay determinism under the durable runner.
+Source: `packages/adonis/docs/authoring/personas-and-agents.mdx` (replay-safety note),
+`packages/adonis/src/agent-loop.ts` (`resolveSystemPrompt`).
+
+See also: `agent-governance/SKILL.md` — the policy behind `roles`/`ability` gates;
+`agent-testing/SKILL.md` — scripting multi-turn runs offline.

package/skills/agent-setup/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: agent-setup
+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(), quotas.ledger/quotas.memory, pricingStores +
+  seedModelPrices + estimateCost, tokenSinks.redis multi-replica SSE sink,
+  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",
+  "quota not enforced", "401 on every agent route".
+metadata:
+  type: core
+  library: "@adonis-agora/agent"
+  library_version: "0.25.2"
+  framework: adonisjs
+sources:
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/getting-started.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/docs/config-reference.mdx"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/define_config.ts"
+  - "DavideCarvalho/adonis-agent:packages/adonis/src/stores/factory.ts"
+---
+
+# Setting up @adonis-agora/agent
+
+`@adonis-agora/agent` is a governed AI agent module for AdonisJS: one `defineConfig`
+call in `config/agent.ts` wires a provider-agnostic agent loop, persistence, budgeting,
+and the `/agent/*` HTTP+SSE routes. Only `model` is required — everything else is a
+fail-closed default that this skill walks through.
+
+## Setup
+
+Install and let the configure hook wire everything:
+
+```bash
+pnpm add @adonis-agora/agent
+node ace configure @adonis-agora/agent
+```
+
+`configure` registers `@adonis-agora/agent/agent_provider` and
+`@adonis-agora/agent/dashboard_provider` in `adonisrc.ts`, registers the Assembler init
+hook that generates the typed `app/agent_tools` barrel, publishes `config/agent.ts`,
+`config/mcp.ts`, and two migrations (the agent tables; a Postgres-only pgvector RAG chunk
+table you can delete). Then add the model peer and write your config:
+
+```bash
+pnpm add ai zod @ai-sdk/openai
+```
+
+```ts
+// config/agent.ts
+import { defineConfig, stores, AuthActorResolver } from '@adonis-agora/agent'
+import { aiSdkModel } from '@adonis-agora/agent/ai-sdk'
+import { openai } from '@ai-sdk/openai'
+
+export default defineConfig({
+  // A lazy thunk keeps the provider SDK peer imported only at boot.
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+
+  store: 'lucid',
+  stores: {
+    memory: stores.memory(), // single-process; tests and scratch apps
+    lucid: stores.lucid(),   // persists to SQL via @adonisjs/lucid
+  },
+
+  // Identity seam — fail-closed. Without a resolver every request throws → 401.
+  actorResolver: new AuthActorResolver(),
+
+  defaultAgent: {
+    systemPrompt: 'You are a helpful assistant for our app.',
+  },
+})
+```
+
+Run the migration for the six agent tables (`agent_thread`, `agent_message`,
+`agent_tool_call`, `agent_token_usage`, `agent_model_pricing`, plus the run-lifecycle
+columns):
+
+```bash
+node ace migration:run
+```
+
+You can skip it: the Lucid store provisions its own tables on first use
+(`autoCreateTables` defaults to true), and the published migration delegates to the same
+`createAgentTables` helper, so the two schemas can never drift.
+
+Source: `packages/adonis/docs/getting-started.mdx`,
+`packages/adonis/docs/stores/lucid.mdx`.
+
+## Core patterns
+
+### Pattern 1 — enforce a daily spend budget with `quotas.ledger`
+
+Quotas are **opt-in**: omitting `quota` disables budgeting entirely (fail-open).
+Configuring one makes the gate fail-closed — `check()` runs before the first model call
+and over-budget turns throw `QuotaExceededError` before any tokens are spent.
+
+```ts
+import { defineConfig, quotas } from '@adonis-agora/agent'
+
+export default defineConfig({
+  // ...
+  quota: quotas.ledger({ limitTokens: 1_000_000 }), // enforced off the persisted usage ledger
+})
+```
+
+`quotas.memory({ limitTokens })` is the single-process variant for tests. The `day`
+(`YYYY-MM-DD`, UTC) is stamped once by the runner, so day-bucketing stays deterministic
+under durable replay.
+
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx`.
+
+### Pattern 2 — price turns with a `pricingStore` + `seedModelPrices`
+
+With a Lucid main store, pricing mirrors the same connection automatically (table
+auto-created) — no extra config. Cost per turn resolves in order: provider-reported
+(a gateway) wins, else an estimate from the current price rows fetched once per run,
+else `null` — never a fabricated `0`. Seed prices once (e.g. from an Ace command):
+
+```ts
+import db from '@adonisjs/lucid/services/db'
+import { seedModelPrices, LucidPricingStore } from '@adonis-agora/agent'
+
+const pricing = new LucidPricingStore(db.connection())
+await seedModelPrices(pricing, [
+  {
+    modelId: 'gpt-4o-mini',
+    inputPricePer1m: 0.15,
+    outputPricePer1m: 0.6,
+    cacheWritePricePer1m: 0.19, // optional — falls back to the input rate
+    cacheReadPricePer1m: 0.015, // optional — falls back to the input rate
+  },
+])
+```
+
+Cache tokens are subsets of `inputTokens`, subtracted before the input rate applies.
+Rollups (`spendByModel`/`spendByActor`) are sums, so an unpriced row contributes `$0.00`
+even though the ledger row keeps `cost_usd: null` — if a total looks implausibly low,
+check the pricing table first.
+
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx`,
+`packages/adonis/src/spi/pricing-store.ts` (`seedModelPrices`, `estimateCost`).
+
+### Pattern 3 — multi-replica SSE with `tokenSinks.redis`
+
+The default sink buffers each run's stream in process memory, which is single-replica: a
+run started on pod A can only be re-attached on pod A. Switching sinks keeps the whole
+SSE envelope identical.
+
+```ts
+import { defineConfig, tokenSinks } from '@adonis-agora/agent'
+
+export default defineConfig({
+  // ...
+  sink: tokenSinks.redis({ ttlSeconds: 3600 }), // replay keys self-expire (default 1h)
+})
+```
+
+Requires `@adonisjs/redis` installed and configured unless you pass `client:` (a
+bring-your-own `RedisStreamClient`). Pair with `durable: true` for cross-instance resume.
+
+Source: `packages/adonis/src/stores/factory.ts` (`tokenSinks`),
+`packages/adonis/docs/streaming-and-http.mdx` ("Single-replica by default" callout).
+
+## Common mistakes
+
+### HIGH — omitting `actorResolver` and shipping 401s everywhere
+
+```ts
+// Wrong — UnconfiguredActorResolver THROWS on every request; all routes answer 401.
+export default defineConfig({ model: () => aiSdkModel(openai('gpt-4o-mini')) })
+```
+
+```ts
+// Correct — read the authenticated principal; no identity is ever fabricated.
+import { AuthActorResolver } from '@adonis-agora/agent'
+export default defineConfig({
+  model: () => aiSdkModel(openai('gpt-4o-mini')),
+  actorResolver: new AuthActorResolver(),
+})
+```
+
+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").
+
+### MEDIUM — expecting quota enforcement after configuring only a store
+
+```ts
+// Wrong — no `quota` key means budgets are DISABLED (fail-open), even with a ledger full of usage.
+export default defineConfig({ model, store: 'lucid', stores: { lucid: stores.lucid() } })
+```
+
+```ts
+// Correct — opt in; the check then runs fail-closed before the first model call.
+export default defineConfig({
+  ...,
+  quota: quotas.ledger({ limitTokens: 500_000 }),
+})
+```
+
+Mechanism: the loop skips both `check` and `bump` entirely when `deps.quota` is
+undefined — there is no implicit limit.
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx` ("Quota is opt-in, and off
+means open"), `packages/adonis/src/agent-loop.ts` (`if (deps.quota !== undefined)`).
+
+### HIGH — incrementing counters in a custom QuotaStore's `bump`
+
+```ts
+// Wrong — double-counts every turn when paired with the persisted usage ledger.
+const store: QuotaStore = {
+  async check(actorRef, day) { /* read my counter */ },
+  async bump(actorRef, day, tokens) { await redis.incrBy(key, tokens) },
+}
+```
+
+```ts
+// Correct — a ledger-backed store leaves bump empty: recordUsage already wrote the tokens.
+class LedgerQuota implements QuotaStore {
+  async check(actorRef: string, day: string) { /* sum agent_token_usage */ }
+  async bump(): Promise<void> {} // deliberate no-op — the ledger is the source of truth
+}
+```
+
+Mechanism: `store.recordUsage(...)` has already persisted each turn's tokens;
+`quotas.ledger.check` reads that ledger, so adding again in `bump` counts each turn twice.
+Only a store keeping its OWN tally (`quotas.memory`, a bespoke Redis counter) should add.
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx` ("`bump` is a notification,
+not necessarily an increment"), `packages/adonis/src/stores/ledger-quota.ts`.
+
+### MEDIUM — reading `$0.00` rollups as "this model is free"
+
+```ts
+// Wrong — no prices seeded: usage rows persist costUsd null, but spendByModel sums them as 0.
+await client.spendByModel({ fromDay: '2026-01-01', toDay: '2026-01-31' })
+```
+
+```ts
+// Correct — seed current prices so estimates fold into costUsd.
+await seedModelPrices(pricingStore, [{ modelId: 'gpt-4o-mini', inputPricePer1m: 0.15, outputPricePer1m: 0.6 }])
+```
+
+Mechanism: an unpriced turn is deliberately `null` ("unknown") in the ledger, but SUM
+rollups cannot preserve null — every unpriced row adds `$0.00`, which reads exactly like
+a free model. Per-run/per-usage rows keep their nulls.
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx` ("`null` in the ledger,
+`0` in the rollups").
+
+### MEDIUM — replacing the allowed attachment content types instead of extending
+
+```ts
+// Wrong — REPLACES the default list: png/jpeg/pdf/csv now get 415.
+attachmentAllowedContentTypes: ['application/json']
+```
+
+```ts
+// Types match EXACTLY (no wildcards); spread the defaults you still want.
+attachmentAllowedContentTypes: [
+  'image/png', 'image/jpeg', 'image/gif', 'image/webp',
+  'application/pdf', 'text/plain', 'text/csv',
+  'text/markdown', // your addition
+],
+```
+
+Mechanism: passing `attachmentAllowedContentTypes` replaces the default list rather than
+merging, and matching is exact — no `text/*` prefix rule — so anything absent is rejected
+with 415.
+Source: `packages/adonis/src/define_config.ts` (`AgentConfig.attachmentAllowedContentTypes`).
+
+See also: `agent-tools/SKILL.md` — registering tools the model can actually call;
+`agent-governance/SKILL.md` — what `AuthActorResolver` feeds into.