@adonis-agora/agent 0.45.0 → 0.47.0

package/skills/agent-setup/SKILL.md

@@ -3,7 +3,7 @@ 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 +
+  stores.lucid()/stores.memory(), quota: { limits }, 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
@@ -63,7 +63,8 @@ export default defineConfig({
     lucid: stores.lucid(),   // persists to SQL via @adonisjs/lucid
   },
 
-  // Identity seam — fail-closed. Without a resolver every request throws → 401.
+  // Identity. Omitted → endpoints PUBLIC, one anonymous actor per browser (HttpOnly cookie).
+  // This line requires login instead (ctx.auth.user; 401 without).
   actorResolver: new AuthActorResolver(),
 
   defaultAgent: {
@@ -89,24 +90,22 @@ Source: `packages/adonis/docs/getting-started.mdx`,
 
 ## Core patterns
 
-### Pattern 1 — enforce a daily spend budget with `quotas.ledger`
+### Pattern 1 — set a budget with `quota: { limits }`
 
-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.
+Budgets are **opt-in**: omitting `quota` means usage is reported (`GET /agent/quota`) but
+never enforced. With limits, a send while a window is exhausted is refused with `429`
+`{ code: 'quota_exceeded', period }` before the turn starts — no tokens 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
+  quota: { limits: { day: { tokens: 200_000 }, month: { usd: 20 } } },
 })
 ```
 
-`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.
+Spend (`usd`) is the provider-reported cost the ledger recorded. A budget of your own is a
+`QuotaProvider` (`report({ actor })`) passed as `quota`. `quotas.ledger` / `quotas.memory`,
+`LedgerQuotaStore` and `GET /agent/quota/today` were removed in 0.46.
 
 Source: `packages/adonis/docs/governance/quota-and-cost.mdx`.
 
@@ -181,15 +180,17 @@ Source: `packages/adonis/src/stores/factory.ts` (`tokenSinks`),
 
 ## Common mistakes
 
-### HIGH — omitting `actorResolver` and shipping 401s everywhere
+### HIGH — omitting `actorResolver` in an app that has logins
 
 ```ts
-// Wrong — UnconfiguredActorResolver THROWS on every request; all routes answer 401.
+// Wrong for an app with users — no resolver means the endpoints are PUBLIC: every browser
+// is its own anonymous actor (anon:<sha256 of an HttpOnly cookie>), and your users'
+// threads are not tied to their accounts.
 export default defineConfig({ model: () => aiSdkModel(openai('gpt-4o-mini')) })
 ```
 
 ```ts
-// Correct — read the authenticated principal; no identity is ever fabricated.
+// Correct — one line requires login (reads ctx.auth.user; 401 without).
 import { AuthActorResolver } from '@adonis-agora/agent'
 export default defineConfig({
   model: () => aiSdkModel(openai('gpt-4o-mini')),
@@ -197,55 +198,27 @@ export default defineConfig({
 })
 ```
 
-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)`).
+Mechanism: with no resolver the provider installs `AnonymousActorResolver` and logs a boot
+notice that the endpoints are public. Right for a free public chat (set a `quota` there);
+wrong for an app whose users log in.
+Source: `packages/adonis/src/anonymous-actor-resolver.ts`,
+`packages/adonis/docs/governance/authorization.mdx` ("No resolver: the endpoints are public").
 
-### HIGH — incrementing counters in a custom QuotaStore's `bump`
+### MEDIUM — shipping a public (anonymous) chat without a budget
 
 ```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) },
-}
+// Wrong — no actorResolver (public) and no quota: model spend is unbounded.
+export default defineConfig({ model })
 ```
 
 ```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
-}
+// Correct — limits apply per actor, i.e. per browser in anonymous mode.
+export default defineConfig({ model, quota: { limits: { day: { tokens: 50_000 } } } })
 ```
 
-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`.
+Mechanism: without `quota`, `GET /agent/quota` reports usage off the ledger but nothing
+gates a send. With it, the chat route checks the report before starting the turn.
+Source: `packages/adonis/docs/governance/quota-and-cost.mdx` ("Budgets").
 
 ### MEDIUM — reading `$0.00` rollups as "this model is free"
 
@@ -265,26 +238,23 @@ 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
+### HIGH — sending attachment objects instead of `{ mediaId }` refs
 
 ```ts
-// Wrong — REPLACES the default list: png/jpeg/pdf/csv now get 415.
-attachmentAllowedContentTypes: ['application/json']
+// Wrong — 400: a send names uploads by id only; a url from the client is never trusted.
+{ message, attachments: [{ mediaId, url, contentType, name }] }
 ```
 
 ```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
-],
+// Correct — the configured store (attachments: attachmentStores.media()) resolves the url.
+{ message, attachments: [{ mediaId }] }
 ```
 
-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`).
+Mechanism: the chat route refuses any key besides `mediaId`, then resolves each id through
+`AttachmentStagingStore.resolve({ mediaId, actor })` (`403` for another actor's upload).
+Limits come from the store (`attachmentStores.media({ maxBytes, allowedContentTypes })`);
+`allowedContentTypes` replaces the default list and matches exactly.
+Source: `packages/adonis/docs/authoring/attachments.mdx`.
 
 See also: `agent-tools/SKILL.md` — registering tools the model can actually call;
 `agent-governance/SKILL.md` — what `AuthActorResolver` feeds into.

package/skills/agent-tools/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   discovery from app/agent_tools via the .adonisjs/agent/tools.js barrel (toolsHook with
   source/importAlias/output) vs the runtime scan fallback, Standard Schema inputs
   (Zod/Valibot/ArkType), AiToolCtx actor scoping, constructor DI (@inject, lazy + cached),
-  roles/ability fail-closed gating under defaultRoles, and the dataTool governed read-only
+  roles/ability gating under defaultRoles (open by default), and the dataTool governed read-only
   SQL satellite. Use for "write a tool", "my tool is never called", "tool forbidden",
   "agent_tools barrel not generating", or "let the agent query the database".
 metadata:
@@ -167,23 +167,24 @@ Source: `packages/adonis/docs/authoring/tools.mdx` ("Configuring the generator")
 
 ## Common mistakes
 
-### CRITICAL — shipping tools without `roles` and calling them unreachable
+### CRITICAL — shipping a privileged tool without `roles`
 
 ```ts
-// Wrong — no roles → inherits defaultRoles ['ADMIN']; MEMBER actors never see this tool.
-static tool = { name: 'get_order', description: '...', input }
+// Wrong — no roles → inherits defaultRoles, which is [] (open) by default: every actor,
+// an anonymous visitor included, is offered this tool.
+static tool = { name: 'refund_order', kind: 'action', description: '...', input }
 ```
 
 ```ts
-// Correct — declare who may invoke.
-static tool = { name: 'get_order', description: '...', input, roles: ['MEMBER'] }
+// Correct — declare who may invoke (or set defaultRoles: ['ADMIN'] to close every tool by default).
+static tool = { name: 'refund_order', kind: 'action', description: '...', input, roles: ['ADMIN'] }
 ```
 
 Mechanism: `definitionsFor` filters the offered tool list through the role gate BEFORE
-each model turn, so a tool the actor cannot invoke is never described to the model — it
-cannot call what it was never shown. This is why "the model didn't call my tool" is
-usually an authorization default, not a prompt problem.
-Source: `packages/adonis/docs/authoring/tools.mdx` (fail-closed callout),
+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
+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`).
 
 ### HIGH — trusting an id from the model's arguments instead of `ctx.actor`

package/dist/src/stores/ledger-quota.d.ts

@@ -1,23 +0,0 @@
-import type { AgentStore } from '../spi/agent-store.js';
-import type { QuotaStore } from '../spi/quota-store.js';
-import type { QuotaState } from '../types.js';
-/**
- * A production {@link QuotaStore} backed by the persisted usage ledger (the append-only
- * `agent_token_usage` table the Lucid store writes each turn to). `check` reads the actor's
- * tokens-so-far for the day straight from {@link AgentStore.quotaToday} and compares it to a fixed
- * daily limit; `bump` is a deliberate no-op because the loop's `recordUsage` already writes every
- * turn's tokens to that same ledger. One source of truth — so enforcement and what a usage dashboard
- * reports can never drift, and it works across replicas with no extra shared state.
- *
- * Ledger-agnostic by design: it wraps any {@link AgentStore} (the `lucid` store for production, the
- * in-memory store for tests), so no dedicated quota table is needed — the token-usage ledger IS the
- * ledger. Wire it in `config/agent.ts` via `quota: quotas.ledger({ limitTokens })`.
- */
-export declare class LedgerQuotaStore implements QuotaStore {
-    private readonly store;
-    private readonly limitTokens;
-    constructor(store: AgentStore, limitTokens: number);
-    check(actorRef: string, day: string): Promise<QuotaState>;
-    bump(): Promise<void>;
-}
-//# sourceMappingURL=ledger-quota.d.ts.map

package/dist/src/stores/ledger-quota.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ledger-quota.d.ts","sourceRoot":"","sources":["../../../src/stores/ledger-quota.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IAE/C,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAF9B,YACmB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,EAClC;IAEE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAO9D;IAEK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAE1B;CACF"}

package/dist/src/stores/ledger-quota.js

@@ -1,32 +0,0 @@
-/**
- * A production {@link QuotaStore} backed by the persisted usage ledger (the append-only
- * `agent_token_usage` table the Lucid store writes each turn to). `check` reads the actor's
- * tokens-so-far for the day straight from {@link AgentStore.quotaToday} and compares it to a fixed
- * daily limit; `bump` is a deliberate no-op because the loop's `recordUsage` already writes every
- * turn's tokens to that same ledger. One source of truth — so enforcement and what a usage dashboard
- * reports can never drift, and it works across replicas with no extra shared state.
- *
- * Ledger-agnostic by design: it wraps any {@link AgentStore} (the `lucid` store for production, the
- * in-memory store for tests), so no dedicated quota table is needed — the token-usage ledger IS the
- * ledger. Wire it in `config/agent.ts` via `quota: quotas.ledger({ limitTokens })`.
- */
-export class LedgerQuotaStore {
-    store;
-    limitTokens;
-    constructor(store, limitTokens) {
-        this.store = store;
-        this.limitTokens = limitTokens;
-    }
-    async check(actorRef, day) {
-        const { usedTokens } = await this.store.quotaToday(actorRef, day);
-        return {
-            usedTokens,
-            limitTokens: this.limitTokens,
-            withinLimit: usedTokens < this.limitTokens,
-        };
-    }
-    async bump() {
-        // No-op: the ledger is the source of truth — recordUsage already persisted this turn's tokens.
-    }
-}
-//# sourceMappingURL=ledger-quota.js.map

package/dist/src/stores/ledger-quota.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ledger-quota.js","sourceRoot":"","sources":["../../../src/stores/ledger-quota.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,gBAAgB;IAER,KAAK;IACL,WAAW;IAF9B,YACmB,KAAiB,EACjB,WAAmB;qBADnB,KAAK;2BACL,WAAW;IAC3B,CAAC;IAEJ,KAAK,CAAC,KAAK,CAAC,QAAgB,EAAE,GAAW;QACvC,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QAClE,OAAO;YACL,UAAU;YACV,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,UAAU,GAAG,IAAI,CAAC,WAAW;SAC3C,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI;QACR,+FAA+F;IACjG,CAAC;CACF"}