akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/service/serviceModule.ts

@@ -1,15 +1,18 @@
-import type { MergeAllKeyOfObjects, PromiseOrObject, UnCls } from "akanjs/base";
+import type { MergeAllKeyOfObjects, UnCls } from "akanjs/base";
 import { capitalize, lowerlize } from "akanjs/common";
 import type { ConstantModel, QueryOf } from "akanjs/constant";
-import type {
-  CRUDEventType,
-  DatabaseModel,
-  DataInputOf,
-  Doc,
-  FindQueryOption,
-  ListQueryOption,
-  SaveEventType,
-  UpdateChain,
+import {
+  type DatabaseModel,
+  type DataInputOf,
+  type Doc,
+  documentQueryHelper,
+  type FilterInfo,
+  type FindQueryOption,
+  type ListQueryOption,
+  type SaveEventListener,
+  type SaveEventType,
+  splitFilterArgs,
+  type UpdateChain,
 } from "akanjs/document";
 import type { ServiceCls } from "./serve";
 import type { DatabaseService } from "./types";
@@ -114,18 +117,10 @@ export class ServiceModel<
       async _postRemove(this: DatabaseService, doc: Doc) {
         return doc;
       },
-      listenPre(
-        this: DatabaseService,
-        type: SaveEventType,
-        listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>,
-      ) {
+      listenPre(this: DatabaseService, type: SaveEventType, listener: SaveEventListener<Doc>) {
         return this.__databaseModel.listenPre(type, listener);
       },
-      listenPost(
-        this: DatabaseService,
-        type: SaveEventType,
-        listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>,
-      ) {
+      listenPost(this: DatabaseService, type: SaveEventType, listener: SaveEventListener<Doc>) {
         return this.__databaseModel.listenPost(type, listener);
       },
       async __create(this: DatabaseService, data: DataInputOf) {
@@ -156,78 +151,65 @@ export class ServiceModel<
     };
     return dbServiceMethods;
   }
-  static getFilterServiceMethods(queryKey: string, queryFn: (...args: any[]) => QueryOf<any>) {
-    const capitalizedQueryKey = capitalize(queryKey);
-    const getQueryDataFromKey = (queryKey: string, args: any): { query: any; queryOption: any } => {
-      const lastArg = args.at(-1);
-      const hasQueryOption =
-        lastArg &&
-        typeof lastArg === "object" &&
-        (typeof lastArg.select === "object" ||
-          typeof lastArg.skip === "number" ||
-          typeof lastArg.limit === "number" ||
-          typeof lastArg.sort === "string");
-      const query = queryFn(...(hasQueryOption ? args.slice(0, -1) : args));
-      const queryOption = hasQueryOption ? lastArg : {};
-      return { query, queryOption };
+  static getFilterServiceMethods(queryKey: string, filterInfo: FilterInfo) {
+    const queryFn = filterInfo.queryFn;
+    if (!queryFn) throw new Error(`No query function for key: ${queryKey}`);
+    const queryOf = (args: any): QueryOf<any> =>
+      queryFn(...splitFilterArgs(filterInfo, args).queryArgs, documentQueryHelper);
+    const dataOf = (args: any) => {
+      const { queryArgs, queryOption } = splitFilterArgs(filterInfo, args);
+      return { query: queryFn(...queryArgs, documentQueryHelper), queryOption };
     };
-    const filterServiceMethods = {
-      [`list${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query, queryOption } = getQueryDataFromKey(queryKey, args);
+    const key = capitalize(queryKey);
+    return {
+      [`list${key}`]: async function (this: DatabaseService, ...args: any) {
+        const { query, queryOption } = dataOf(args);
         return this.__list(query, queryOption);
       },
-      [`listIds${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query, queryOption } = getQueryDataFromKey(queryKey, args);
+      [`listIds${key}`]: async function (this: DatabaseService, ...args: any) {
+        const { query, queryOption } = dataOf(args);
         return this.__listIds(query, queryOption);
       },
-      [`find${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query, queryOption } = getQueryDataFromKey(queryKey, args);
+      [`find${key}`]: async function (this: DatabaseService, ...args: any) {
+        const { query, queryOption } = dataOf(args);
         return this.__find(query, queryOption);
       },
-      [`findId${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query, queryOption } = getQueryDataFromKey(queryKey, args);
+      [`findId${key}`]: async function (this: DatabaseService, ...args: any) {
+        const { query, queryOption } = dataOf(args);
         return this.__findId(query, queryOption);
       },
-      [`pick${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query, queryOption } = getQueryDataFromKey(queryKey, args);
+      [`pick${key}`]: async function (this: DatabaseService, ...args: any) {
+        const { query, queryOption } = dataOf(args);
         return this.__pick(query, queryOption);
       },
-      [`pickId${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query, queryOption } = getQueryDataFromKey(queryKey, args);
+      [`pickId${key}`]: async function (this: DatabaseService, ...args: any) {
+        const { query, queryOption } = dataOf(args);
         return this.__pickId(query, queryOption);
       },
-      [`exists${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query } = getQueryDataFromKey(queryKey, args);
-        return this.__exists(query);
+      [`exists${key}`]: async function (this: DatabaseService, ...args: any) {
+        return this.__exists(queryOf(args));
       },
-      [`count${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query } = getQueryDataFromKey(queryKey, args);
-        return this.__count(query);
+      [`count${key}`]: async function (this: DatabaseService, ...args: any) {
+        return this.__count(queryOf(args));
       },
-      [`insight${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query } = getQueryDataFromKey(queryKey, args);
-        return this.__insight(query);
+      [`insight${key}`]: async function (this: DatabaseService, ...args: any) {
+        return this.__insight(queryOf(args));
       },
-      [`query${capitalizedQueryKey}`]: function (this: DatabaseService, ...args: any) {
-        return queryFn(...args);
+      [`query${key}`]: (...args: any) => queryOf(args),
+      [`remove${key}`]: async function (this: DatabaseService, ...args: any) {
+        return this.__removeMany(queryOf(args));
       },
-      [`remove${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query } = getQueryDataFromKey(queryKey, args);
-        return this.__removeMany(query);
+      [`removeOne${key}`]: async function (this: DatabaseService, ...args: any) {
+        return this.__removeOne(queryOf(args));
       },
-      [`removeOne${capitalizedQueryKey}`]: async function (this: DatabaseService, ...args: any) {
-        const { query } = getQueryDataFromKey(queryKey, args);
-        return this.__removeOne(query);
-      },
-      [`update${capitalizedQueryKey}`]: function (this: DatabaseService, ...args: any): UpdateChain {
-        const { query } = getQueryDataFromKey(queryKey, args);
+      [`update${key}`]: function (this: DatabaseService, ...args: any): UpdateChain {
+        const query = queryOf(args);
         return { set: (update) => this.__updateMany(query, update) };
       },
-      [`updateOne${capitalizedQueryKey}`]: function (this: DatabaseService, ...args: any): UpdateChain {
-        const { query } = getQueryDataFromKey(queryKey, args);
+      [`updateOne${key}`]: function (this: DatabaseService, ...args: any): UpdateChain {
+        const query = queryOf(args);
         return { set: (update) => this.__updateOne(query, update) };
       },
     };
-    return filterServiceMethods;
   }
 }

package/service/toolNames.ts

@@ -3,30 +3,16 @@ import type { AgentWireMessage, AgentWireToolCall, LlmTurnRequest } from "./pred
 const wireSafe = /^[A-Za-z0-9_-]+$/;
 
 /**
- * Renames a turn's tools onto what a provider's function-calling wire accepts, and reads the answer back.
- *
- * A zone publishes its tools scope-prefixed — `videoProjectDraft.createVideoProject` — which is legal for MCP,
- * where `.` is an allowed character and the scope join. Every OpenAI-compatible and Anthropic function schema is
- * narrower: `[A-Za-z0-9_-]`, at most 64 characters. A provider that validates answers 400; DeepSeek does not, and
- * what happened instead was worse to debug — the model normalized the illegal name itself, called the bare
- * `createVideoProject`, and the browser answered `Unknown tool`, spending a turn on a tool that was published all
- * along.
- *
- * Renamed here rather than in each adaptor for the reason `AgentService.explained` gives: every adaptor would
- * otherwise have to remember, and forgetting is silent. A name the wire already accepts is left alone, so the
- * root agent's request is byte-for-byte what it was.
+ * OpenAI-dialect and Anthropic function names are `[A-Za-z0-9_-]{1,64}` while a zone scopes tools with `.`; DeepSeek
+ * does not refuse an illegal name but calls a normalized one that the browser does not know.
  */
 export class ToolNames {
-  /** Both dialects reject a longer name, and neither says so in terms of the tool you wrote. */
   static readonly limit = 64;
 
   readonly #toWire = new Map<string, string>();
   readonly #toSurface = new Map<string, string>();
 
-  /**
-   * Every name the request carries, not just the published ones: the transcript holds calls to tools that have
-   * since left the screen, and one of those reaching the wire unrenamed is the same failure a turn later.
-   */
+  /** The transcript's names too: a call to a tool that has since left the screen still reaches the wire. */
   static of(request: LlmTurnRequest): ToolNames {
     return new ToolNames([
       ...request.tools.map((tool) => tool.name),
@@ -38,7 +24,7 @@ export class ToolNames {
     const all = [...new Set(names)];
     
     const taken = new Set(all.filter((name) => ToolNames.#fits(name)));
-
+    
     for (const name of all.filter((candidate) => !ToolNames.#fits(candidate)).sort((a, b) => (a < b ? -1 : 1))) {
       const wire = ToolNames.#unique(ToolNames.#fold(name), taken);
       taken.add(wire);
@@ -55,10 +41,7 @@ export class ToolNames {
     return this.#toWire.get(name) ?? name;
   }
 
-  /**
-   * Unknown stays as it came. A model that invented a name is answered by the surface's own `Unknown tool`, which
-   * lands in the transcript as a tool result it can correct from — guessing which tool it meant would run one.
-   */
+  /** An invented name stays as it came for the surface's `Unknown tool`: guessing the intended tool would run one. */
   surface(name: string) {
     return this.#toSurface.get(name) ?? name;
   }

package/service/types.ts

@@ -2,7 +2,6 @@ import type { Cls, MergeAllTypes, PromiseOrObject } from "akanjs/base";
 import type { Logger } from "akanjs/common";
 import type { QueryOf } from "akanjs/constant";
 import type {
-  CRUDEventType,
   DatabaseModel,
   DataInputOf,
   DocumentUpdateInput,
@@ -11,6 +10,7 @@ import type {
   GetDocObject,
   ListQueryOption,
   QueryMethodPart,
+  SaveEventListener,
   SaveEventType,
   UpdateResult,
 } from "akanjs/document";
@@ -128,14 +128,8 @@ export type DatabaseService<
   __libsPostUpdate: (doc: Doc) => Promise<Doc>;
   __libsPreRemove: (id: string) => Promise<void>;
   __libsPostRemove: (doc: Doc) => Promise<Doc>;
-  listenPre: (
-    type: SaveEventType,
-    listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>,
-  ) => () => void;
-  listenPost: (
-    type: SaveEventType,
-    listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>,
-  ) => () => void;
+  listenPre: (type: SaveEventType, listener: SaveEventListener<Doc>) => () => void;
+  listenPost: (type: SaveEventType, listener: SaveEventListener<Doc>) => () => void;
 } & { [key in `${T}Model`]: Model } & {
   [K in `get${_CapitalizedRefName}`]: (id: string) => Promise<Doc>;
 } & {

package/signal/CrossSiteGuard.ts

@@ -2,34 +2,12 @@ import { hostFromRequest, isJsonContentType, Logger } from "akanjs/common";
 import { Exception } from "./exception";
 
 export interface CrossSiteOption {
-  /**
-   * Origins allowed to drive a mutation besides the one serving the request. The native shells are here by
-   * default because a Capacitor webview is a real caller whose origin is never the serve domain.
-   */
+  /** Besides the serving origin; the native shell origins are always allowed. */
   allowedOrigins?: string[];
-  /** Turns the whole gate off. For a deployment whose API is reached only by non-browser callers. */
+  /** `false` turns the gate off, for an API reached only by non-browser callers. */
   enabled?: boolean;
 }
 
-/**
- * Refuses a state-changing request a browser made from somewhere else.
- *
- * The framework authenticates with a `SameSite=None` cookie, which a browser attaches to **every** cross-site
- * request, and `Request.json()` reads a body whatever content type it claims. Without this, any page on the
- * internet could POST a form at a mutation and have it run as whoever was signed in — the response is unreadable
- * without CORS headers, but the write already landed.
- *
- * Two independent gates, because neither covers the other:
- *
- * - **Content type.** Demanding `application/json` puts a CORS preflight in front of every JSON mutation, and
- *   the preflight fails because nothing here answers one. This is what closes the hole for the common case.
- * - **Origin.** A file upload is `multipart/form-data`, which is preflight-free by spec and cannot be made to
- *   require JSON, so the only thing left to check is who sent it. Also covers a mutation with no body at all.
- *
- * A request with no `Origin` header is allowed: browsers set it on every POST, so its absence means a
- * non-browser caller (a server, a CLI, a test), which has no ambient credential to be abused. A literal
- * `Origin: null` is refused — that is the opaque origin a sandboxed frame or a `data:` document sends.
- */
 export class CrossSiteGuard {
   static readonly logger = new Logger("CrossSiteGuard");
   /** iOS ships `capacitor://localhost`, Android `http://localhost`, older shells `ionic://localhost`. */
@@ -48,10 +26,7 @@ export class CrossSiteGuard {
     CrossSiteGuard.#allowed = new Set(CrossSiteGuard.nativeOrigins);
   }
 
-  /**
-   * The body gate. Called only where a JSON body is about to be read, so an upload mutation — whose content type
-   * is multipart by construction — reaches `assertOrigin` and nothing else.
-   */
+  /** Call only where a JSON body is read: a multipart upload relies on `assertOrigin` alone. */
   static assertJsonBody(contentType: string | null) {
     if (!CrossSiteGuard.#enabled) return;
     if (isJsonContentType(contentType)) return;
@@ -64,27 +39,17 @@ export class CrossSiteGuard {
     if (origin === null) return;
     if (origin !== "null" && (CrossSiteGuard.#isSameSite(origin, req, url) || CrossSiteGuard.#allowed.has(origin)))
       return;
-
+    
     CrossSiteGuard.logger.warn(
       `Refused "${key}" from cross-site origin ${origin} (request host ${hostFromRequest(req.headers, url)})`,
     );
     throw new Exception.Forbidden("This request was not permitted.");
   }
 
-  /**
-   * Host, not full origin — the same comparison `McpRouter` makes, for the same reason.
-   *
-   * The host is what the browser wrote from the URL it was told to open, so a page on another site POSTing here
-   * still arrives with *our* host and its own `Origin`: comparing hosts refuses every cross-site caller. The
-   * scheme is the one part of the origin a proxy routinely loses — a TLS-terminating edge (a Cloudflare tunnel,
-   * an ingress without `x-forwarded-proto`) dials us over plain HTTP, so an `https://` caller would be measured
-   * against a computed `http://` self and refused on every mutation. What that costs is a page served over
-   * plaintext on our own host, which is an attacker who already holds the name.
-   */
   static #isSameSite(origin: string, req: Request, url: URL): boolean {
     try {
       const { protocol, host } = new URL(origin);
-
+      
       return host === new URL(`${protocol}//${hostFromRequest(req.headers, url)}`).host;
     } catch {
       return false;

package/signal/SignalFailure.ts

@@ -1,21 +1,9 @@
-/**
- * The one shape an unexpected failure takes on the wire, for both transports.
- *
- * An `Exception` says what it means to say and travels as it is. Everything else — a SQL error, an adaptor
- * throwing, a framework `throw new Error` — is an internal detail: a stack names server file paths and the
- * framework's own structure, and a driver message quotes the statement and sometimes its values. That is the
- * same reason a guard's refusal is generalized to `You are not permitted to perform this action.`, so a 500 is
- * generalized for it too. `endpoint.logger.error` already recorded the stack, so nothing is lost.
- */
+
 export class SignalFailure {
   static readonly message = "Internal Server Error";
   static #detailed: boolean | null = null;
 
-  /**
-   * Whether this process may describe its own failures. Production is the deployed build — the same test
-   * `WebRouter` applies, so `akan start` under `NODE_ENV=production` still says what broke. `AKAN_ERROR_DETAIL=1`
-   * puts the detail back for a deployed build somebody is debugging.
-   */
+  /** Off in a deployed build (the `WebRouter` test) unless `AKAN_ERROR_DETAIL=1`. */
   static get detailed(): boolean {
     SignalFailure.#detailed ??=
       process.env.AKAN_ERROR_DETAIL === "1" ||
@@ -27,7 +15,6 @@ export class SignalFailure {
     SignalFailure.#detailed = null;
   }
 
-  /** The 500 payload: the real message and stack in dev, one sentence in production. */
   static body<Extra extends Record<string, unknown> = Record<string, never>>(
     error: unknown,
     extra: Extra = {} as Extra,

package/signal/agent/AgentCatalogue.ts

@@ -2,32 +2,27 @@ import { mcpBaseVerbOf } from "akanjs/common";
 import { FetchClient } from "akanjs/fetch";
 import type { SerializedEndpoint, SerializedSignal, SerializedSlice } from "../types";
 
-/** Where an endpoint came from, which is what decides where an audience's opt-in for it can be written. */
 export type AgentOrigin = "base" | "slice" | "endpoint";
 
-/** Which generated CRUD verb a `base` candidate is. Its opt-in lives on the signal, not on the endpoint. */
 export type AgentBaseVerb = NonNullable<ReturnType<typeof mcpBaseVerbOf>>;
 
-/** One endpoint a signal registry holds, before any audience has decided anything about it. */
 export interface AgentCandidate {
   refName: string;
   key: string;
   endpoint: SerializedEndpoint;
   origin: AgentOrigin;
-  /** The signal it belongs to. A generated verb carries no option of its own, so its opt-in is written here. */
+  /** Where a generated verb's opt-in is written, since it carries no option of its own. */
   signal: SerializedSignal;
-  /** The slice this key was generated from, where the opt-in for a `slice` candidate is written. */
+  /** Where a `slice` candidate's opt-in is written. */
   slice?: SerializedSlice;
   baseVerb?: AgentBaseVerb;
 }
 
-/** An opt-in a catalogue did not honour, with the reason it did not. */
 export interface AgentRefusal {
   key: string;
   reason: string;
 }
 
-/** A published entry carrying no description its author wrote, and what to write so that it does. */
 export interface AgentUndescribed {
   key: string;
   reason: string;
@@ -38,24 +33,9 @@ export interface AgentCatalogueOptions {
   excludeSignals?: string[];
 }
 
-/**
- * The half of an agent catalogue that does not depend on who is asking.
- *
- * Enumerating what a signal registry holds, keeping that order stable, holding one name per entry, and resolving
- * the words a module wrote in its dictionary are the same work for every audience — an external MCP client, an
- * in-page agent driving the store, a transport that does not exist yet. What differs is only which option admits
- * an endpoint and what shape it is published in, and both of those stay with the audience that decides them.
- *
- * Separated while exactly one audience existed. The cost then is moving code between two files; the cost later is
- * telling two audiences apart inside one class that never expected a second.
- */
+/** The audience-independent half of a catalogue: enumeration, stable order, one name per entry, dictionary text. */
 export class AgentCatalogue {
-  /**
-   * Everything a registry holds, in an order that does not move between boots: clients cache a catalogue, and an
-   * LLM prompt cache keys on its exact text, so an order that depends on object iteration is a cache that misses.
-   *
-   * Every endpoint is listed, including ones no audience will take. Deciding is the caller's half.
-   */
+  /** Sorted, because clients cache a catalogue and an LLM prompt cache keys on its exact text. */
   static candidates(
     serializedSignal: Record<string, SerializedSignal>,
     { excludeSignals = ["base"] }: { excludeSignals?: string[] } = {},
@@ -78,39 +58,22 @@ export class AgentCatalogue {
     return candidates.sort((a, b) => a.refName.localeCompare(b.refName) || a.key.localeCompare(b.key));
   }
 
-  /**
-   * What opted in and was refused anyway. Collected rather than merely dropped so a server can say so at boot:
-   * the rejections an audience makes are fail-closed by design, and an author whose deliberate opt-in vanished
-   * from the catalogue otherwise has nowhere to look but the framework source.
-   */
   readonly refusals: AgentRefusal[] = [];
 
   readonly #options: AgentCatalogueOptions;
   readonly #claimed = new Set<string>();
-  /** Keyed so an entry read twice — once as a tool and again as a template — is reported once. */
+  
   readonly #undescribedByKey = new Map<string, string>();
 
   constructor(options: AgentCatalogueOptions = {}) {
     this.#options = options;
   }
 
-  /**
-   * What is published with no description of its own. Description is the one field a model picks an entry by, so
-   * one without it is a broken entry rather than an untidy one — and a source scanner cannot answer this: it
-   * reads files, where an opt-in is visible only as a literal in a builder call and where the model `.desc()`
-   * every generated entry borrows is not written as a description of the entry at all.
-   */
   get undescribed(): AgentUndescribed[] {
     return [...this.#undescribedByKey].map(([key, reason]) => ({ key, reason }));
   }
 
-  /**
-   * Takes the name for this entry, or refuses it because something else already holds it.
-   *
-   * A name must be unique within a catalogue, across every kind of entry it publishes. Keys are globally unique
-   * by construction, so a collision means two signals disagree — the first in candidate order keeps it, which is
-   * what makes the catalogue the same on the next boot either way.
-   */
+  /** The first claimant in candidate order keeps a colliding name, so the catalogue is the same every boot. */
   claim(key: string): boolean {
     if (this.#claimed.has(key)) {
       this.refuse(key, "another endpoint is already published under this name.");
@@ -131,18 +94,9 @@ export class AgentCatalogue {
   }
 
   /**
-   * Every entry the framework generates borrows the model's own words, because none of them has any of its own.
-   *
-   * `slice()` generates the root slice under the empty key and `baseSliceDictionary` fills its text, so
-   * `<model>List` and `<model>Insight` publish as "Slice List - Universal" whatever the dictionary says. The five
-   * base CRUD entries are no better off: `getBaseSignalDictionary` writes "Get Banner" as both title and
-   * description, and both are assigned last, so a module author has nowhere to write over either one.
-   *
-   * That matters more here than anywhere else — description is the one field a model picks an entry by, and "Get
-   * Banner" says nothing about what a Banner is. So the model's `.desc()` is appended rather than substituted:
-   * on `removeBanner` a bare model description would read as if the tool returned one. And when the model has no
-   * `.desc()` either, the entry is recorded as undescribed — its only possible text is missing, and that is the
-   * one thing a source scanner cannot see.
+   * Generated entries borrow the model's words: the root slice's placeholder text and the base CRUD "Get X" are
+   * assigned last, where no author can write over them. On CRUD the model `.desc()` is appended, not substituted,
+   * so `removeX` does not read as returning one.
    */
   entryTexts(refName: string, key: string) {
     const borrowed = `its only text is the model's own, and \`${refName}\` has no \`.desc()\` to lend it.`;

package/signal/agent.signal.ts

@@ -1,26 +1,28 @@
 import { Any } from "akanjs/base";
 import type { AgentWireContext, AgentWireMessage, AgentWireTool, LlmTurnRequest } from "akanjs/service";
 import { srv } from "akanjs/service";
+import { AgentMeter } from "./agentMeter";
 import { AgentTurn } from "./agentTurn";
 import { AgentTurnStream } from "./agentTurnStream";
 import { endpoint } from "./endpoint";
 import { AgentRelayAccess } from "./guards";
 import { internal } from "./internal";
-import { Req } from "./internalArg";
+import { CallerAccount, Req } from "./internalArg";
 import { serverSignal } from "./serverSignal";
 import { SignalRegistry } from "./signalRegistry";
 
 export class AgentInternal extends internal(srv.agent, () => ({})) {}
 
 export class AgentEndpoint extends endpoint(srv.agent, ({ mutation }) => ({
-
+  
   runAgentTurn: mutation(AgentTurn, { guards: [AgentRelayAccess] })
     .body("messages", [Any])
     .body("tools", [Any])
     .body("context", [Any])
     .body("instructions", String, { nullable: true })
     .with(Req)
-    .exec(async function (messages, tools, context, instructions, request) {
+    .with(CallerAccount, { nullable: true })
+    .exec(async function (messages, tools, context, instructions, request, account) {
       const turn: LlmTurnRequest = {
         messages: messages as unknown as AgentWireMessage[],
         tools: tools as unknown as AgentWireTool[],
@@ -28,9 +30,10 @@ export class AgentEndpoint extends endpoint(srv.agent, ({ mutation }) => ({
         ...(instructions ? { instructions } : {}),
       };
       if (AgentTurnStream.wants(request as Bun.BunRequest))
-        
-        return AgentTurnStream.response((onDelta) => this.agentService.runTurn(turn, onDelta)) as unknown as AgentTurn;
-      return await this.agentService.runTurn(turn);
+        return AgentTurnStream.response((onDelta) =>
+          AgentMeter.run(account, () => this.agentService.runTurn(turn, onDelta)),
+        ) as unknown as AgentTurn;
+      return await AgentMeter.run(account, () => this.agentService.runTurn(turn));
     }),
 })) {}
 

package/signal/agentMeter.ts

@@ -0,0 +1,45 @@
+import type { PromiseOrObject } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import { Err } from "akanjs/dictionary";
+import type { LlmUsage } from "akanjs/service";
+
+export interface AgentUsageReport {
+  account: unknown;
+  model: string | null;
+  usage: LlmUsage;
+}
+
+export interface AgentQuotaCheck {
+  account: unknown;
+}
+
+export type AgentUsageHook = (report: AgentUsageReport) => PromiseOrObject<void>;
+export type AgentQuotaHook = (check: AgentQuotaCheck) => PromiseOrObject<boolean>;
+
+/** `account` is whatever the app's account middleware put on the call; the framework has no account model. */
+export class AgentMeter {
+  static #usage: AgentUsageHook | null = null;
+  static #quota: AgentQuotaHook | null = null;
+  static #logger = new Logger("AgentMeter");
+
+  static use({ usage, quota }: { usage?: AgentUsageHook | null; quota?: AgentQuotaHook | null }) {
+    if (usage !== undefined) AgentMeter.#usage = usage;
+    if (quota !== undefined) AgentMeter.#quota = quota;
+  }
+
+  static async run<T extends { usage?: LlmUsage; model?: string }>(account: unknown, turn: () => Promise<T>) {
+    if (AgentMeter.#quota && !(await AgentMeter.#quota({ account }))) throw new Err("agent.error.quotaExceeded");
+    const result = await turn();
+    const hook = AgentMeter.#usage;
+    
+    if (hook && result.usage)
+      void Promise.resolve()
+        .then(() => hook({ account, model: result.model ?? null, usage: result.usage as LlmUsage }))
+        .catch((error: unknown) =>
+          AgentMeter.#logger.error(
+            `agent usage hook failed: ${error instanceof Error ? error.message : String(error)}`,
+          ),
+        );
+    return result;
+  }
+}