akanjs 3.0.0-beta.9 → 3.0.1

package/types/signal/CrossSiteGuard.d.ts

@@ -1,44 +1,25 @@
 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;
-    /** iOS ships `capacitor://localhost`, Android `http://localhost`, older shells `ionic://localhost`. */
-    static readonly nativeOrigins: readonly ["capacitor://localhost", "ionic://localhost", "http://localhost"];
+    /** The native shell serves the page from `app://localhost` on iOS, macOS and Linux, `https://app.localhost` on
+     * Android and Windows; both WebViews send exactly that as `Origin`. */
+    static readonly nativeOrigins: readonly ["app://localhost", "https://app.localhost"];
     /** Applied at boot from the mounting app's `option.ts`; the native shells stay allowed unless disabled. */
     static configure({ allowedOrigins, enabled }: CrossSiteOption): void;
+    static option(): Required<CrossSiteOption>;
     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;
+    /** The origin a cross-origin caller may read answers from: an allowlisted one, never the serving host's neighbours. */
+    static corsOrigin(req: Request): string | null;
+    static preflight(req: Request, methods: string[]): Response;
+    static withCors(req: Request, res: Response): Response;
 }

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 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<MergeEndpointMetas<LibEndpoints>, ReturnType<Builder>>>;
 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,19 +52,13 @@ 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>;
     getPath(key: string): string;
+    /** The route the server mounts, below the global prefix; the fetch client is handed it to call the same one. */
+    getRoutePath(key: string, defaultPrefix?: string): string;
+    static resolveServicePrefix(prefix: false | string | undefined, defaultPrefix?: string): string;
 }
 export type BuildEndpoint<SrvModule extends ServiceModel = ServiceModel> = {
     query: <Returns extends ConstantFieldTypeInput = ConstantFieldTypeInput, Nullable extends boolean = false>(returnRef: Returns, signalOption?: SignalOption<Returns, Nullable>) => EndpointInfo<"query", SrvMap<SrvModule>, [], [], [], [], Returns, never, never, 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>;

package/types/signal/internalArg.d.ts

@@ -4,11 +4,9 @@ export interface InternalArg<ArgType = unknown> {
     getArg: (context: SignalContext) => PromiseOrObject<ArgType | null>;
 }
 export type InternalArgCls<ArgType = unknown> = Cls<InternalArg<ArgType>>;
-/** Injects the current Bun request into an endpoint/internal handler. */
 export declare class Req implements InternalArg {
     getArg(context: SignalContext): Bun.BunRequest;
 }
-/** Injects the current mutable response context into an endpoint/internal handler. */
 export declare class Res implements InternalArg {
     getArg(context: SignalContext): {
         new (body?: BodyInit | null, init?: ResponseInit): Response;
@@ -18,21 +16,17 @@ export declare class Res implements InternalArg {
         redirect(url: string | URL, status?: number): Response;
     };
 }
-/**
- * Injects the caller's IP, as the nearest proxy recorded it rather than as the socket peer reports it.
- * Behind the federation gateway every peer is the gateway, so an endpoint that reads `remoteAddress` sees
- * `127.0.0.1` for every caller — this reads the forwarded headers first and falls back to the peer only
- * when nothing proxied the call. IPv4 comes back unwrapped from `::ffff:`, so it can address a `udp4`
- * socket. `null` when no proxy recorded one and the transport has no peer.
- */
+/** Whatever the account middleware resolved for this call, or `null` for an anonymous one. */
+export declare class CallerAccount implements InternalArg<unknown> {
+    getArg(context: SignalContext): unknown;
+}
+/** The caller's IP as the nearest proxy recorded it (see `SignalContext.getClientIp`), `null` when unknown. */
 export declare class Ip implements InternalArg<string | null> {
     getArg(context: SignalContext): string | null;
 }
 /**
- * Injects websocket state, this connection's id, and subscription hooks into message/pubsub handlers.
- * `socketId` is the one `AppWsData` minted at the handshake, so a handler never reads `ws.data` to
- * tell two callers apart — and never mints an id of its own, which would not match the room bookkeeping.
- * `on`/`off` register cleanup that runs when the room is unsubscribed or the socket closes.
+ * `socketId` is the one minted at the handshake — never mint your own, it would not match the room bookkeeping.
+ * `on`/`off` register cleanup for unsubscribe or socket close.
  */
 export declare class Ws implements InternalArg {
     getArg(context: SignalContext): {

package/types/signal/mcp/McpDocument.d.ts

@@ -4,18 +4,11 @@ import type { McpResource, McpResourceTemplate, McpTool } from "./mcpProtocol.d.
 export interface McpDocumentOptions {
     resolveDescription?: (key: string) => string | undefined;
     excludeSignals?: string[];
-    /**
-     * Drops every mutation from the catalogue regardless of what it opted into. Off by default: the endpoint's own
-     * an endpoint's guards are the decision, and a second switch that silently unlists a published endpoint gives
-     * its author no way to see why. This is the read-only-deployment valve.
-     */
+    /** Drops every mutation from the catalogue whatever its guards allow. Off by default. */
     readOnly?: boolean;
     /**
-     * How much of a result's shape a tool advertises. `shallow`, the default, publishes the returned model with every
-     * field of its own and names each nested model instead of inlining it: on a fully open catalogue 83% of the bytes
-     * were the same model schemas re-inlined per entry, most of them nested closures. `full` inlines the closure the
-     * way a shared component section would. `none` publishes no `outputSchema` at all — results still ship as
-     * `structuredContent` — for a deployment that would rather spend the bytes per call.
+     * `shallow` (default) names each nested model instead of inlining it, `full` inlines the closure, `none` publishes
+     * no `outputSchema` (results still ship as `structuredContent`).
      */
     outputSchema?: McpOutputSchemaMode;
 }
@@ -25,13 +18,8 @@ export interface McpExposedEndpoint {
     key: string;
     endpoint: SerializedEndpoint;
 }
-/**
- * A candidate this catalogue did not publish. The bookkeeping is audience-independent and lives on
- * `AgentCatalogue`; these are the MCP names for it.
- */
 export type McpRefusal = AgentRefusal;
 export type McpUndescribed = AgentUndescribed;
-/** What one signal contributes to a listing, so a catalogue that grew can say where it grew. */
 export interface McpSignalCost {
     refName: string;
     entries: number;
@@ -41,49 +29,21 @@ export interface McpListingCost {
     bytes: number;
     bySignal: McpSignalCost[];
 }
-/**
- * Turns the serialized signal registry into the three MCP catalogues and answers the lookups `tools/call` and
- * `resources/read` need. Pure: no IO and no DI — the sibling of `createOpenApiDocument`.
- */
 export declare class McpDocument {
     #private;
-    /**
-     * An array cannot be `structuredContent` — the spec types it as an object — so a list result is wrapped under
-     * this key and `outputSchema` is shaped to match. Both halves must agree, which is why they live together.
-     */
+    /** The spec types `structuredContent` as an object, so a list result is wrapped under this key. */
     static readonly listKey = "items";
     readonly tools: McpTool[];
     readonly resourceTemplates: McpResourceTemplate[];
     /** Every readable thing is addressed by a template, so there are no fixed resources to enumerate. */
     readonly resources: McpResource[];
-    /**
-     * Every candidate that was not published, with the sentence saying why — the rejections are fail-closed by
-     * design, and an author whose endpoint is missing otherwise has nowhere to look but the framework source.
-     */
     readonly refusals: McpRefusal[];
-    /** What is published with no description of its own, which is the field a model picks a tool by. */
     readonly undescribed: McpUndescribed[];
     constructor(serializedSignal: Record<string, SerializedSignal>, options?: McpDocumentOptions);
-    /**
-     * Roughly what a `tools/list` costs the caller, and which signals it went to.
-     *
-     * Worth reporting because the number is nobody's intuition: MCP has no shared component section and forbids a
-     * `$ref` across entries, so every entry inlines the schema of every model it mentions — under `outputSchema:
-     * "full"` a plain 21-field model with one named slice ships 12KB across its eight entries, three quarters of it
-     * the same four schemas repeated. A catalogue is re-sent whole to every agent that connects, before its first turn.
-     */
     get listingCost(): McpListingCost;
     findTool(name: string): McpExposedEndpoint | undefined;
-    /**
-     * The uri `resources/read` answers for one call of a tool, or undefined for a tool that has no template. What a
-     * page fetched is attached to a prompt under the address an agent can read it back from.
-     */
     resourceUri(key: string, args: Record<string, unknown>): string | undefined;
-    /**
-     * Resolves a URI only when the endpoint behind it was published as a template. An endpoint that was never
-     * advertised has to fail here rather than fall through to its guards: opting out of MCP means keeping a thing
-     * off the wire entirely, not merely making it refuse.
-     */
+    /** Only a published template resolves: an opted-out endpoint must be unreachable, not merely refused by guards. */
     resolveResource(uri: string): {
         exposed: McpExposedEndpoint;
         args: Record<string, string | string[]>;

package/types/signal/mcp/McpProgress.d.ts

@@ -1,39 +1,26 @@
 export interface McpProgressOption {
-    /** Denominator for the ratio a client renders. Omit when the amount of work is not known up front. */
+    /** Omit when the amount of work is not known up front. */
     total?: number;
-    /** One short line describing the current step. Shown to the user, so keep it prose rather than a status code. */
+    /** Shown to the user, so write prose rather than a status code. */
     message?: string;
 }
 export interface McpProgressReport extends McpProgressOption {
     progress: number;
 }
 /**
- * The progress channel for one streamed MCP call.
- *
- * Reached through `AsyncLocalStorage` rather than a parameter so an endpoint reports progress from wherever the
- * work actually happens — a service, an adapter, a loop several frames down — without every signature between
- * here and there growing a channel argument. Outside a streamed call `report` is a no-op, so the same endpoint
- * code runs unchanged over plain HTTP, a websocket, or a test.
+ * Reached through `AsyncLocalStorage` so any frame of the work can report; outside a streamed call `report` is a
+ * no-op, so the same endpoint runs unchanged over HTTP, a websocket or a test.
  */
 export declare class McpProgress {
     #private;
-    /**
-     * Reports progress for the call running on this stack. Silent when nothing is listening, which is every call
-     * that did not ask for a stream.
-     */
     static report(progress: number, option?: McpProgressOption): void;
-    /** True while the caller is streaming, so an expensive progress message can be skipped when nobody reads it. */
     static get streaming(): boolean;
     static run<T>(channel: McpProgress, exec: () => Promise<T>): Promise<T>;
-    /** Resolves on the first report and never otherwise — a call that reports nothing has nothing to stream. */
+    /** Resolves on the first report, and never for a call that reports nothing. */
     readonly started: Promise<void>;
     constructor();
-    /**
-     * Aborted when the client closes the response stream, which is how cancellation is signalled over this
-     * transport. Long-running work may watch it; the framework cannot force an `exec` already in flight to stop.
-     */
+    /** Aborted when the client closes the response stream; an `exec` already in flight is not forced to stop. */
     get signal(): AbortSignal;
-    /** Yields every report until the call finishes. Buffered ones come out first, so none is lost to a late reader. */
     reports(): AsyncGenerator<McpProgressReport>;
     end(): void;
     abort(): void;