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

package/types/service/predefinedAdaptor/websocket.adaptor.d.ts

@@ -1,42 +1,41 @@
-import type { BaseEnv, Cls } from "akanjs/base";
-import { ProtobufCompressor } from "./compress.adaptor";
 export interface WsSocketData {
     socketId?: string;
     createdAt?: number;
 }
 export type WsRedisEventHandler = (roomId: string, data: unknown) => void;
+/** A committed write to a model that live slices route, as text every server of the app turns back into documents. */
+export interface LiveChange {
+    refName: string;
+    next: string;
+    /** Absent on a create. */
+    previous?: string;
+}
+export type LiveChangeHandler = (change: LiveChange) => void;
+export interface WebsocketPublishOption {
+    /** Only the newest frame for the room matters, so an undelivered older one may be dropped for it. */
+    coalesce?: boolean;
+}
 export interface WebsocketAdaptor {
-    /** Publish data to a room across all server instances */
-    publish(roomId: string, data: unknown): void;
-    /** Register an event handler for incoming cross-server messages */
+    /** Across every server instance. */
+    publish(roomId: string, data: unknown, option?: WebsocketPublishOption): void;
     setEventHandler(handler: WsRedisEventHandler): void;
-    /** Unregister the event handler */
     clearEventHandler(): void;
-    /**
-     * Called after the cross-server channel has been down and come back, if this transport can lose one.
-     *
-     * A dropped subscription is the one message loss nothing else notices: the client's own socket stays open the
-     * whole time, so it has no reason to suspect its list is behind. A transport with no channel to lose — the
-     * single-node one, which delivers through the gateway's own IPC — leaves this out.
-     */
+    /** After a lost cross-server channel returns — a loss the still-open client socket never notices. Optional. */
     onRecovered?(handler: () => void): void;
-    /** Register endpoint return type info for protobuf encoding */
-    registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void;
-    /** Register a socket joining a room (tracked in Redis for cross-server awareness) */
+    /** To every other server of the app: the writer only knows its own rooms, and a batch process holds none. */
+    publishChange?(change: LiveChange): void;
+    onChange?(handler: LiveChangeHandler): void;
     joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
-    /** Remove a socket from a room */
     leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
-    /** Remove a socket from all rooms and clean up its Redis state */
     leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
-    /** Register a socket connection on this server */
     registerSocket(ws: Bun.ServerWebSocket<unknown>, meta?: Record<string, string>): Promise<void>;
-    /** Unregister a socket connection */
     unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
 }
 declare const WebSocketRedisAdaptor_base: import("..").AdaptorCls<{}, {
-    redis: import("..").InjectInfo<"plug", import("ioredis").default, never, never>;
-    compressor: import("..").InjectInfo<"plug", ProtobufCompressor, never, never>;
-    serverId: import("..").InjectInfo<"env", string, BaseEnv, never>;
+    channelPrefix: import("..").InjectInfo<"plug", string, never, never>;
+    serverId: import("..").InjectInfo<"env", string, {
+        [key: string]: any;
+    }, never>;
     publisher: import("..").InjectInfo<"plug", import("ioredis").default, never, never>;
     subscriber: import("..").InjectInfo<"plug", import("ioredis").default, never, never>;
 }>;
@@ -44,15 +43,16 @@ export declare class WebSocketRedisAdaptor extends WebSocketRedisAdaptor_base im
     #private;
     onInit(): Promise<void>;
     onDestroy(): Promise<void>;
-    publish(roomId: string, data: unknown): void;
+    publish(roomId: string, data: unknown, { coalesce }?: WebsocketPublishOption): void;
+    publishChange(change: LiveChange): void;
+    onChange(handler: LiveChangeHandler): void;
     setEventHandler(handler: WsRedisEventHandler): void;
     clearEventHandler(): void;
     onRecovered(handler: () => void): void;
-    registerEndpoint(key: string, returnRef: Cls, arrDepth: number): void;
     joinRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
     leaveRoom(ws: Bun.ServerWebSocket<unknown>, room: string): Promise<void>;
     leaveAllRooms(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
-    registerSocket(ws: Bun.ServerWebSocket<unknown>, meta?: Record<string, string>): Promise<void>;
+    registerSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
     unregisterSocket(ws: Bun.ServerWebSocket<unknown>): Promise<void>;
 }
 export {};

package/types/service/serviceModule.d.ts

@@ -1,6 +1,6 @@
-import type { MergeAllKeyOfObjects, PromiseOrObject, UnCls } from "akanjs/base";
+import type { MergeAllKeyOfObjects, UnCls } from "akanjs/base";
 import type { ConstantModel, QueryOf } from "akanjs/constant";
-import type { CRUDEventType, DatabaseModel, DataInputOf, Doc, FindQueryOption, ListQueryOption, SaveEventType } from "akanjs/document";
+import { type DatabaseModel, type DataInputOf, type Doc, type FilterInfo, type FindQueryOption, type ListQueryOption, type SaveEventListener, type SaveEventType } from "akanjs/document";
 import type { ServiceCls } from "./serve.d.ts";
 import type { DatabaseService } from "./types.d.ts";
 export declare class ServiceModel<Srv extends ServiceCls = ServiceCls, CnstModel extends ConstantModel = any, DbModel extends DatabaseModel = any, SrvMap extends {
@@ -19,7 +19,7 @@ export declare class ServiceModel<Srv extends ServiceCls = ServiceCls, CnstModel
     static from<Srv extends ServiceCls>(srv: Srv): ServiceModel<Srv, never, never, { [K in `${Uncapitalize<Srv["refName"]>}Service`]: UnCls<Srv>; }>;
     with<SrvModules extends ServiceModel[]>(...srvs: SrvModules): ServiceModel<Srv, CnstModel, DbModel, SrvMap & MergeAllKeyOfObjects<SrvModules, "srvMap">>;
     static getDefaultDbServiceMethods(className: string): {
-        [x: string]: ((this: DatabaseService, query: QueryOf<any>, queryOption?: ListQueryOption) => Promise<any>) | ((this: DatabaseService, query: QueryOf<any>, queryOption?: FindQueryOption) => Promise<any>) | ((this: DatabaseService, id: string, data: Partial<Doc>) => Promise<Partial<Doc>>) | ((this: DatabaseService, type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>) => any) | ((this: DatabaseService, id: string, data: DataInputOf) => Promise<any>);
+        [x: string]: ((this: DatabaseService, query: QueryOf<any>, queryOption?: ListQueryOption) => Promise<any>) | ((this: DatabaseService, query: QueryOf<any>, queryOption?: FindQueryOption) => Promise<any>) | ((this: DatabaseService, id: string, data: Partial<Doc>) => Promise<Partial<Doc>>) | ((this: DatabaseService, type: SaveEventType, listener: SaveEventListener<Doc>) => any) | ((this: DatabaseService, id: string, data: DataInputOf) => Promise<any>);
         __get(this: DatabaseService, id: string): Promise<any>;
         __load(this: DatabaseService, id?: string): Promise<any>;
         __loadMany(this: DatabaseService, ids: string[]): Promise<any>;
@@ -38,13 +38,13 @@ export declare class ServiceModel<Srv extends ServiceCls = ServiceCls, CnstModel
         _postUpdate(this: DatabaseService, doc: Doc): Promise<Doc>;
         _preRemove(this: DatabaseService, id: string): Promise<void>;
         _postRemove(this: DatabaseService, doc: Doc): Promise<Doc>;
-        listenPre(this: DatabaseService, type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>): any;
-        listenPost(this: DatabaseService, type: SaveEventType, listener: (doc: Doc, type: CRUDEventType, previous?: Doc) => PromiseOrObject<void>): any;
+        listenPre(this: DatabaseService, type: SaveEventType, listener: SaveEventListener<Doc>): any;
+        listenPost(this: DatabaseService, type: SaveEventType, listener: SaveEventListener<Doc>): any;
         __create(this: DatabaseService, data: DataInputOf): Promise<any>;
         __update(this: DatabaseService, id: string, data: DataInputOf): Promise<any>;
         __remove(this: DatabaseService, id: string): Promise<Doc>;
     };
-    static getFilterServiceMethods(queryKey: string, queryFn: (...args: any[]) => QueryOf<any>): {
-        [x: string]: (this: DatabaseService, ...args: any) => any;
+    static getFilterServiceMethods(queryKey: string, filterInfo: FilterInfo): {
+        [x: string]: (...args: any) => any;
     };
 }

package/types/service/toolNames.d.ts

@@ -1,34 +1,17 @@
 import type { AgentWireToolCall, LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
 /**
- * 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 declare class ToolNames {
     #private;
-    /** Both dialects reject a longer name, and neither says so in terms of the tool you wrote. */
     static readonly limit = 64;
-    /**
-     * 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;
     constructor(names: Iterable<string>);
     get renamed(): boolean;
     wire(name: string): string;
-    /**
-     * 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): string;
     encode(request: LlmTurnRequest): LlmTurnRequest;
     decode(calls: AgentWireToolCall[]): AgentWireToolCall[];

package/types/service/types.d.ts

@@ -1,7 +1,7 @@
 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, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventType, UpdateResult } from "akanjs/document";
+import type { DatabaseModel, DataInputOf, DocumentUpdateInput, FilterInstance, FindQueryOption, GetDocObject, ListQueryOption, QueryMethodPart, SaveEventListener, SaveEventType, UpdateResult } from "akanjs/document";
 type ServiceMixinOmitKey = "onInit" | "onDestroy" | "_libsOnInit" | "_libsOnDestroy" | "_preCreate" | "_postCreate" | "_preUpdate" | "_postUpdate" | "_preRemove" | "_postRemove" | "_libsPreCreate" | "_libsPostCreate" | "_libsPreUpdate" | "_libsPostUpdate" | "_libsPreRemove" | "_libsPostRemove";
 type DatabaseQueryMethods<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery> = QueryMethodPart<Query, Sort, Obj, Doc, Insight, FindQueryOption, ListQueryOption, DocQuery>;
 type DocumentLike = {
@@ -56,8 +56,8 @@ export type DatabaseService<T extends string = string, Input = any, Doc = any, O
     __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;
 } & {

package/types/signal/CrossSiteGuard.d.ts

@@ -1,32 +1,10 @@
 import { Logger } from "akanjs/common";
 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 declare class CrossSiteGuard {
     #private;
     static readonly logger: Logger;
@@ -35,10 +13,7 @@ export declare class CrossSiteGuard {
     /** Applied at boot from the mounting app's `option.ts`; the native shells stay allowed unless disabled. */
     static configure({ allowedOrigins, enabled }: CrossSiteOption): void;
     static reset(): void;
-    /**
-     * 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): void;
     static assertOrigin(req: Request, url: URL, key: string): void;
 }

package/types/signal/SignalFailure.d.ts

@@ -1,23 +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 declare class SignalFailure {
     #private;
     static readonly message = "Internal Server Error";
-    /**
-     * 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;
     static reset(): void;
-    /** 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): Extra & {
         error: string;
         statusCode: number;

package/types/signal/agent/AgentCatalogue.d.ts

@@ -1,27 +1,22 @@
 import { mcpBaseVerbOf } from "akanjs/common";
 import type { SerializedEndpoint, SerializedSignal, SerializedSlice } from "../types.d.ts";
-/** 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;
@@ -30,49 +25,17 @@ export interface AgentCatalogueOptions {
     resolveDescription?: (key: string) => string | undefined;
     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 declare class AgentCatalogue {
     #private;
-    /**
-     * 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 }?: {
         excludeSignals?: string[];
     }): AgentCandidate[];
-    /**
-     * 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[];
     constructor(options?: AgentCatalogueOptions);
-    /**
-     * 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[];
-    /**
-     * 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;
     refuse(key: string, reason: string): void;
     texts(titleKey: string, descKey?: string): {
@@ -80,18 +43,9 @@ export declare class AgentCatalogue {
         title?: string | undefined;
     };
     /**
-     * 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): {
         description?: string | undefined;

package/types/signal/agent.signal.d.ts

@@ -9,7 +9,10 @@ declare const AgentEndpoint_base: import("./endpoint.d.ts").EndpointCls<import("
 }>, {
     runAgentTurn: import("./endpointInfo.d.ts").EndpointInfo<"mutation", {
         agentService: import("akanjs/service").AgentService;
-    }, ["messages", "tools", "context", "instructions"], [arg: unknown[], arg: unknown[], arg: unknown[], arg?: string | null | undefined], [arg: Bun.BunRequest<string>], [arg: unknown[], arg: unknown[], arg: unknown[], arg: string | undefined], typeof AgentTurn, AgentTurn, Promise<AgentTurn | {
+    }, ["messages", "tools", "context", "instructions"], [arg: unknown[], arg: unknown[], arg: unknown[], arg?: string | null | undefined], [arg: Bun.BunRequest<string>, arg: {} | null], [arg: unknown[], arg: unknown[], arg: unknown[], arg: string | undefined], typeof AgentTurn, AgentTurn, Promise<AgentTurn | {
+        limits?: import("akanjs/service").LlmLimits | undefined;
+        model?: string | undefined;
+        usage?: import("akanjs/service").LlmUsage | undefined;
         text: string;
         toolCalls: import("akanjs/service").AgentWireToolCall[];
         stop: "length" | "end" | "toolUse";

package/types/signal/agentMeter.d.ts

@@ -0,0 +1,24 @@
+import type { PromiseOrObject } from "akanjs/base";
+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 declare class AgentMeter {
+    #private;
+    static use({ usage, quota }: {
+        usage?: AgentUsageHook | null;
+        quota?: AgentQuotaHook | null;
+    }): void;
+    static run<T extends {
+        usage?: LlmUsage;
+        model?: string;
+    }>(account: unknown, turn: () => Promise<T>): Promise<T>;
+}

package/types/signal/agentTurnStream.d.ts

@@ -1,24 +1,23 @@
-import type { AgentWireToolCall } from "akanjs/service";
+import type { AgentWireToolCall, LlmLimits, LlmUsage } from "akanjs/service";
 interface StreamedTurn {
     text?: string;
     toolCalls?: AgentWireToolCall[];
     stop?: "end" | "toolUse" | "length";
+    usage?: LlmUsage;
+    limits?: LlmLimits;
 }
-/**
- * The streaming half of the agent turn wire (use-agentic WIRE.md): the same endpoint answers `text/event-stream`
- * when the request asks for it, one RunnerEvent JSON per SSE `data:` line, ending with `done`. The signal layer
- * passes a raw `Response` through untouched, which is what lets one mutation serve both shapes.
- */
+type RunTurn = (onDelta: (delta: string) => void) => Promise<StreamedTurn>;
 export declare class AgentTurnStream {
+    #private;
     static wants(request: Bun.BunRequest): boolean;
-    /**
-     * A domain `Err` carries its dictionary key as the message and the values its text interpolates as `data`, so
-     * both travel: the key alone would reach the chat as `agent.error.…` with its placeholders unfilled.
-     */
+    /** A domain `Err`'s `data` travels with its key, or the chat could not fill the text's placeholders. */
     static failure(error: unknown): {
         message: string;
         data?: Record<string, string | number>;
+        overflow?: {
+            limit?: number;
+        };
     };
-    static response(run: (onDelta: (delta: string) => void) => Promise<StreamedTurn>): Response;
+    static response(run: RunTurn): Response;
 }
 export {};

package/types/signal/endpoint.d.ts

@@ -29,7 +29,6 @@ type MergeEndpointMetas<EndpClses extends readonly EndpointCls[], Acc = unknown>
     infer First extends EndpointCls,
     ...infer Rest extends readonly EndpointCls[]
 ] ? MergeEndpointMetas<Rest, Assign<Acc, EndpointMetaOf<First>>> : Acc;
-/** Builds a typed endpoint adaptor from a service module and endpoint builder. */
 export declare function endpoint<SrvModule extends ServiceModel, Builder extends EndpointBuilder<SrvModule>, LibEndpoints extends readonly EndpointCls[]>(srv: SrvModule, builder: Builder, ...libEndpoints: LibEndpoints): EndpointCls<SrvModule, LibEndpoints extends readonly [] ? ReturnType<Builder> : Assign<ReturnType<Builder>, MergeEndpointMetas<LibEndpoints>>>;
 export declare function sliceEndpoint<SrvModule extends ServiceModel, Builder extends EndpointBuilder<SrvModule>>(srv: SrvModule, builder: Builder): EndpointCls<SrvModule, ReturnType<Builder>>;
 export {};

package/types/signal/endpointCache.d.ts

@@ -0,0 +1,5 @@
+import type { SignalContext } from "./signalContext.d.ts";
+export declare class EndpointCache {
+    #private;
+    static through(context: SignalContext, run: () => Promise<unknown>): Promise<unknown>;
+}

package/types/signal/endpointInfo.d.ts

@@ -34,6 +34,7 @@ export declare class EndpointInfo<ReqType extends EndpointType = EndpointType, S
 } = {
     [key: string]: any;
 }, ArgNames extends string[] = any, Args extends any[] = any, InternalArgs extends any[] = any, ServerArgs extends any[] = any, Returns extends ConstantFieldTypeInput = ConstantFieldTypeInput, ClientReturns = never, ServerReturns = never, Nullable extends boolean = boolean> {
+    #private;
     readonly type: ReqType;
     readonly argNames: ArgNames;
     readonly args: ArgInfo<EndpointArgProps<boolean>>[];
@@ -51,15 +52,6 @@ export declare class EndpointInfo<ReqType extends EndpointType = EndpointType, S
     search<ArgName extends string, ExplicitType = unknown, Arg extends ConstantFieldTypeInput = PlainTypeToFieldType<ExplicitType>, _ArgType = unknown extends ExplicitType ? FieldToValue<Arg> : ExplicitType, _ClientArg = PurifiedModel<_ArgType>, _ServerArg = DocumentModel<_ArgType>>(name: string, arg: Arg, option?: Omit<EndpointArgProps, "nullable">): EndpointInfo<ReqType, Srvs, [...ArgNames, ArgName], [...Args, arg?: _ClientArg | null], InternalArgs, [...ServerArgs, arg: _ServerArg | undefined], Returns, ClientReturns, ServerReturns, Nullable>;
     _addArgs(args: ArgInfo<EndpointArgProps<boolean>>[]): this;
     with<ArgType, Optional extends boolean = false>(argRef: InternalArgCls<ArgType>, option?: InternalArgProps<Optional>): EndpointInfo<ReqType, Srvs, ArgNames, Args, [...InternalArgs, arg: NonNullable<ArgType> | (Optional extends true ? null : never)], ServerArgs, Returns, ClientReturns, ServerReturns, Nullable>;
-    /**
-     * Retypes a slice's own arguments as this room's arguments, keeping each one's nullability.
-     *
-     * Not `_addArgs`, which would route a `search` argument back to `.search()`. And not `.room()` per argument:
-     * that refuses a nullable argument in anything but the last position, which is the right rule for a URL and a
-     * meaningless one for a room — the arguments travel as a positional array with explicit nulls, so a missing one
-     * is unambiguous. Nullability is preserved because dropping it would make an absent optional argument fail to
-     * deserialize on the way in.
-     */
     _addRoomArgs(args: ArgInfo<EndpointArgProps<boolean>>[]): this;
     _addInternalArgs(args: InternalArgInfo<boolean>[]): this;
     exec<ExecFn extends (this: Srvs, ...args: [...ServerArgs, ...InternalArgs]) => ReqType extends "pubsub" ? Promise<void> | void : PromiseOrObject<DocumentModel<FieldToValue<Returns>> | (Nullable extends true ? null | undefined : never)>>(execFn: ExecFn): EndpointInfo<ReqType, Srvs, ArgNames, Args, InternalArgs, ServerArgs, Returns, FieldToValue<Returns>, ReturnType<ExecFn>, Nullable>;

package/types/signal/exception.d.ts

@@ -1,31 +1,3 @@
-/**
- * The three ways this framework throws, and which one to reach for.
- *
- * - **`Exception`** (here) — a request-level answer with a status code. It travels to the caller as it is:
- *   `{ error, statusCode, path, timestamp }`, with the message intact. Reach for it when the caller did
- *   something the endpoint can name — a filter that does not exist, an argument that will not parse, a guard's
- *   refusal. The message is read by whoever called, so it may not say anything the caller may not know.
- *
- * - **`Err`** (`akanjs/dictionary`, `new Err("<module>.error.<key>")`) — the same thing for a **domain** rule,
- *   with the sentence in the module's dictionary in every language. Everything a *user* reads is one of these;
- *   `Exception` carries English prose and belongs to the protocol rather than to the product.
- *
- * - **`Error`** — a bug, an invariant the code holds and something broke, or a misconfiguration a developer has
- *   to fix. It never reaches a caller: `SignalFailure` generalizes anything without a status code to
- *   `Internal Server Error` and logs the stack, because a stack names server paths and a driver message quotes
- *   the statement. Most of the 379 `throw new Error` in this package are boot-time refusals, which is right —
- *   nobody is holding the connection.
- *
- * The test for the first two is whether a caller can act on it. The test for the third is whether *this repo*
- * has to change for the throw to stop happening.
- */
-/**
- * The shape of every `Exception.<Status>` shorthand below.
- *
- * The annotation is not decoration: a `static X = class extends Exception {}` has to be serialized into the
- * `.d.ts` as a structural type, and that type contains `Exception`, whose statics contain it again — declaration
- * emit gives up with TS7056 and `akn build-package akanjs` fails. Naming the type breaks the cycle.
- */
 export interface StatusException {
     new (message?: string, details?: unknown): Exception;
 }
@@ -48,12 +20,7 @@ export declare class Exception extends Error {
     static UnsupportedMediaType: StatusException;
     static Error: StatusException;
 }
-/**
- * What a transport forwards to the caller instead of generalizing: a status code and a payload the value can
- * write itself. An `Exception` is one; so is a dictionary `Err`; so is a failure `restoreRemoteError` rebuilt
- * from another process, which is what lets a server hop rethrow a remote `Err` and have it travel as that
- * `Err`. Anything else is this repo's own bug and becomes `SignalFailure`'s 500.
- */
+/** Forwarded to the caller instead of generalized: an `Exception`, a dictionary `Err`, or a restored remote one. */
 export interface ExceptionLike {
     statusCode: number;
     toJSON: () => object;

package/types/signal/guard.d.ts

@@ -4,28 +4,17 @@ export interface Guard {
     canPass(context: SignalContext): PromiseOrObject<boolean>;
 }
 /**
- * What a guard needs in order to answer. `account` reads the caller and nothing else, so it can be evaluated
- * with no arguments — which is what lets a catalogue hide what the caller certainly cannot use. `resource` needs
- * the call's arguments and fails closed without them, so evaluating one early would erase legitimate entries.
- *
- * Required, with no default. Exposure is decided by a guard rather than by an opt-in, so an unmarked guard would
- * silently take the `resource` path and list its endpoint to every caller — the whole guarded surface's names,
- * refused only at call time. There is no safe guess here, so the author states it.
+ * `account` reads only the caller, so a listing may evaluate it with no arguments; `resource` needs the call's
+ * arguments and fails closed without them. Required on a hand-written guard: unmarked, every listing would show it.
  */
 export type GuardScope = "account" | "resource";
-/**
- * A guard that admits no model — one that refuses every MCP call and every call on an agent's token — says so with
- * `static agents = false`. The MCP catalogue then refuses every endpoint it guards outright, the way `mcp: false`
- * does, instead of publishing an entry that every agent would only ever be refused. Optional, unlike `scope`: the
- * default (agents may pass, subject to the verdict) is the one almost every guard means.
- */
+/** `static agents = false` marks a guard that admits no model: the MCP catalogue refuses every endpoint it guards. */
 export type GuardCls<Name extends string = string> = Cls<Guard, {
     readonly name: Name;
     readonly scope: GuardScope;
     readonly agents?: boolean;
 }>;
-/** Whether any guard in the list admits no agent at all — the fact the serializer stamps on an endpoint as `agents: false`. */
 export declare const refusesAgents: (guards: readonly GuardCls[] | undefined) => boolean;
-/** Creates a named guard base class for signal access checks. */
+/** Starts as `scope = "account"`, the side that errs hidden. */
 export declare const guard: <T extends string>(name: T) => GuardCls<T>;
 export declare const guardOf: (GuardCls: GuardCls) => Guard;

package/types/signal/guards.d.ts

@@ -11,22 +11,14 @@ export declare class None implements Guard {
     canPass(context: SignalContext): boolean;
 }
 /**
- * Gate for the `runAgentTurn` relay. Every tool runs in the caller's own browser session, so the LLM key is the
- * one thing this endpoint spends — ungated, any visitor can bill the app's provider through fetch alone.
- *
- * The framework has no account model to gate on, so with no guard registered it refuses every call — the same
- * answer `None` gives. An app names its own at boot, e.g. `AgentRelayAccess.use(Every)`, usually through
- * `option.setAgentAccess(...)`. Several are ANDed, as an endpoint's own `guards` array is.
+ * Gates the `runAgentTurn` relay, which spends the app's LLM key. Refuses every call until the app registers guards
+ * (`option.setAgentAccess(...)`); several are ANDed.
  */
 export declare class AgentRelayAccess implements Guard {
     #private;
     static name: string;
     static use(guards: GuardCls | GuardCls[] | null): void;
     static get hasPolicy(): boolean;
-    /**
-     * Whatever the registered guards need, since this one only forwards to them. With none registered it reads the
-     * caller and nothing else — the refusal is unconditional — so a listing may still evaluate it argument-free.
-     */
     static get scope(): GuardScope;
     canPass(context: SignalContext): Promise<boolean>;
 }

package/types/signal/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./agent.d.ts";
 export * from "./agent.signal";
+export * from "./agentMeter.d.ts";
 export * from "./agentTurn.d.ts";
 export * from "./agentTurnStream.d.ts";
 export * from "./base.signal";

package/types/signal/internal.d.ts

@@ -11,13 +11,9 @@ export type InternalCls<SrvModule extends ServiceModel = ServiceModel, InternalI
 } = {
     [key: string]: InternalInfo;
 }> = AdaptorCls & {
-    /**
-     * The adaptor name, which `dangerouslyAdapt` suffixes — and which the DI container keys `live.internal` by.
-     * It used to be declared as the bare service name, so every typed read of it disagreed with the value.
-     */
+    /** The suffixed adaptor name the DI container keys `live.internal` by. */
     refName: `${SrvRefName<SrvModule>}Internal`;
     srv: SrvModule;
     [INTERNAL_META]: InternalInfoMap;
 };
-/** Builds an internal adaptor for schedules, queues, processes, and server-only jobs. */
 export declare function internal<SrvModule extends ServiceModel, InternalInfoMap extends ReturnType<InternalBuilder<SrvModule>>, LibInternals extends InternalCls[]>(srv: SrvModule, internalBuilder: (builder: BuildInternal<SrvModule>) => InternalInfoMap, ...libInternals: LibInternals): InternalCls<SrvModule, MergeAllKeyOfObjects<LibInternals, typeof INTERNAL_META> & InternalInfoMap>;