akanjs 3.0.0-beta.9 → 3.0.1

package/signal/agentTurnStream.ts

@@ -1,63 +1,65 @@
-import type { AgentWireToolCall } from "akanjs/service";
+import { EventStream } from "akanjs/common";
+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 class AgentTurnStream {
   static wants(request: Bun.BunRequest): boolean {
     return !!request.headers.get("accept")?.includes("text/event-stream");
   }
 
-  /**
-   * 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.
-   */
-  static failure(error: unknown): { message: string; data?: Record<string, string | number> } {
+  /** 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 };
+  } {
     const message = error instanceof Error ? error.message : String(error);
-    const data = (error as { data?: unknown } | null)?.data;
-    return data && typeof data === "object" && !Array.isArray(data)
-      ? { message, data: data as Record<string, string | number> }
-      : { message };
+    const raw = (error as { data?: unknown } | null)?.data;
+    const data =
+      raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, string | number>) : null;
+    
+    const overflow =
+      message === "agent.error.contextOverflow" ? (typeof data?.limit === "number" ? { limit: data.limit } : {}) : null;
+    return { message, ...(data ? { data } : {}), ...(overflow ? { overflow } : {}) };
+  }
+
+  static response(run: RunTurn): Response {
+    
+    const stream = new EventStream(() => undefined);
+    void AgentTurnStream.#deliver(stream, run);
+    return stream.response();
   }
 
-  static response(run: (onDelta: (delta: string) => void) => Promise<StreamedTurn>): Response {
-    const encoder = new TextEncoder();
-    const stream = new ReadableStream<Uint8Array>({
-      async start(controller) {
-        const send = (event: object) => controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
-        try {
-          let streamed = 0;
-          const turn = await run((delta) => {
-            if (!delta) return;
-            streamed += delta.length;
-            send({ type: "text", delta });
-          });
-          
-          if (!streamed && turn.text) send({ type: "text", delta: turn.text });
-          const toolCalls = turn.toolCalls ?? [];
-          for (const call of toolCalls) send({ type: "toolCall", id: call.id, name: call.name, args: call.args });
-          
-          const stop =
-            turn.stop === "length" ? "length" : turn.stop === "toolUse" || toolCalls.length ? "toolUse" : "end";
-          send({ type: "done", stop });
-        } catch (error) {
-          
-          send({ type: "error", ...AgentTurnStream.failure(error) });
-        } finally {
-          controller.close();
-        }
-      },
-    });
-    return new Response(stream, {
-      headers: { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" },
-    });
+  static async #deliver(stream: EventStream, run: RunTurn) {
+    try {
+      let streamed = 0;
+      const turn = await run((delta) => {
+        if (!delta) return;
+        streamed += delta.length;
+        stream.write({ type: "text", delta });
+      });
+      
+      if (!streamed && turn.text) stream.write({ type: "text", delta: turn.text });
+      const toolCalls = turn.toolCalls ?? [];
+      for (const call of toolCalls) stream.write({ type: "toolCall", id: call.id, name: call.name, args: call.args });
+      const stop = turn.stop === "length" ? "length" : turn.stop === "toolUse" || toolCalls.length ? "toolUse" : "end";
+      const usage = turn.usage ? { input: turn.usage.inputTokens, output: turn.usage.outputTokens } : null;
+      const limits = turn.limits && (turn.limits.window || turn.limits.output) ? turn.limits : null;
+      stream.write({ type: "done", stop, ...(usage ? { usage } : {}), ...(limits ? { limits } : {}) });
+    } catch (error) {
+      
+      stream.write({ type: "error", ...AgentTurnStream.failure(error) });
+    } finally {
+      stream.close();
+    }
   }
 }

package/signal/endpoint.ts

@@ -1,6 +1,6 @@
 import type { Assign } from "akanjs/base";
 import { ENDPOINT_DICT_SHAPE, ENDPOINT_META } from "akanjs/base";
-import { applyMixins } from "akanjs/common";
+import { applyMixins, Logger } from "akanjs/common";
 import { type Adaptor, type AdaptorCls, dangerouslyAdapt, type ServiceModel } from "akanjs/service";
 import { buildEndpoint, type EndpInfoArgNames, type EndpointBuilder, type EndpointInfo } from "./endpointInfo";
 import type { SrvRefName } from "./types";
@@ -33,7 +33,16 @@ type MergeEndpointMetas<EndpClses extends readonly EndpointCls[], Acc = unknown>
   ? MergeEndpointMetas<Rest, Assign<Acc, EndpointMetaOf<First>>>
   : Acc;
 
-/** Builds a typed endpoint adaptor from a service module and endpoint builder. */
+const warnQueryBodyArgs = (refName: string, endpoints: { [key: string]: EndpointInfo }) => {
+  for (const [key, info] of Object.entries(endpoints))
+    if (info.type === "query")
+      for (const arg of info.args)
+        if (arg.type === "body")
+          Logger.warn(
+            `${refName}.${key}: fetch sends a query as GET, so its body argument "${arg.name}" never arrives over HTTP — declare it with .search() or make the endpoint a mutation`,
+          );
+};
+
 export function endpoint<
   SrvModule extends ServiceModel,
   Builder extends EndpointBuilder<SrvModule>,
@@ -44,7 +53,7 @@ export function endpoint<
   ...libEndpoints: LibEndpoints
 ): EndpointCls<
   SrvModule,
-  LibEndpoints extends readonly [] ? ReturnType<Builder> : Assign<ReturnType<Builder>, MergeEndpointMetas<LibEndpoints>>
+  LibEndpoints extends readonly [] ? ReturnType<Builder> : Assign<MergeEndpointMetas<LibEndpoints>, ReturnType<Builder>>
 > {
   const srvKeys = [
     ...new Set([
@@ -52,17 +61,23 @@ export function endpoint<
       ...libEndpoints.flatMap((libEndpoint) => Object.keys(libEndpoint.srv.srvMap)),
     ]),
   ];
+  const ownEndpointMeta = builder(buildEndpoint);
   const endpointCls = class Endpoint extends dangerouslyAdapt(`${srv.srv.refName}Endpoint`, ({ service }) => ({
     ...Object.fromEntries(srvKeys.map((srvRefName) => [srvRefName, service()])),
   })) {
     static baseName = srv.srv.refName;
     static srv = srv;
-    static [ENDPOINT_META] = builder(buildEndpoint);
+    static [ENDPOINT_META] = Object.assign(
+      {},
+      ...libEndpoints.map((libEndpoint) => libEndpoint[ENDPOINT_META]),
+      ownEndpointMeta,
+    );
   };
-  libEndpoints.forEach((libEndpoint) => {
-    Object.assign(endpointCls[ENDPOINT_META], libEndpoint[ENDPOINT_META]);
-    Object.assign(endpointCls.srv.srvMap, libEndpoint.srv.srvMap);
-  });
+  warnQueryBodyArgs(srv.srv.refName, ownEndpointMeta);
+  Object.assign(
+    srv.srvMap,
+    Object.assign({}, ...libEndpoints.map((libEndpoint) => libEndpoint.srv.srvMap), srv.srvMap),
+  );
   applyMixins(endpointCls, [...libEndpoints]);
   return endpointCls as any; 
 }

package/signal/endpointCache.ts

@@ -0,0 +1,59 @@
+import { type CacheAdaptor, CacheAdaptorRole } from "akanjs/service";
+import dayjs from "dayjs";
+import type { SignalContext } from "./signalContext";
+import { traceCache } from "./trace";
+
+export class EndpointCache {
+  static #topic = "cache";
+  static #refused = new Set<string>();
+
+  static async through(context: SignalContext, run: () => Promise<unknown>) {
+    const ttl = context.endpointInfo.signalOption.cache;
+    if (!ttl || !Number.isFinite(ttl) || ttl <= 0) return await run();
+    if (!EndpointCache.#cacheable(context)) return await run();
+    const cache = context.getAdaptor(CacheAdaptorRole) as unknown as CacheAdaptor;
+    const key = `${context.key}:${JSON.stringify(context.args)}`;
+    const cached = await EndpointCache.#read(context, cache, key);
+    if (cached !== undefined) {
+      traceCache(true);
+      return cached;
+    }
+    traceCache(false);
+    const result = await run();
+    await EndpointCache.#write(context, cache, key, result, ttl);
+    return result;
+  }
+  static #cacheable(context: SignalContext) {
+    if (context.endpointInfo.type === "query" && context.endpointInfo.internalArgs.length === 0) return true;
+    if (EndpointCache.#refused.has(context.key)) return false;
+    EndpointCache.#refused.add(context.key);
+    const reason =
+      context.endpointInfo.type === "query"
+        ? "it takes an internal argument, so its answer is the caller's and not a shared one"
+        : `a ${context.endpointInfo.type} is never cached`;
+    context.adaptor.logger.warn(`"${context.key}" declares \`cache\` and cannot take one: ${reason}.`);
+    return false;
+  }
+  
+  static async #read(context: SignalContext, cache: CacheAdaptor, key: string) {
+    try {
+      const cached = await cache.get<string>(EndpointCache.#topic, key);
+      if (cached == null) return undefined;
+      return JSON.parse(cached) as unknown;
+    } catch (error) {
+      context.adaptor.logger.warn(`Cache read failed for ${context.key}: ${String(error)}`);
+      await cache.delete(EndpointCache.#topic, key).catch(() => undefined);
+      return undefined;
+    }
+  }
+  static async #write(context: SignalContext, cache: CacheAdaptor, key: string, result: unknown, ttl: number) {
+    const serialized = JSON.stringify(result);
+    
+    if (serialized === undefined) return;
+    try {
+      await cache.set(EndpointCache.#topic, key, serialized, { expireAt: dayjs().add(ttl, "millisecond") });
+    } catch (error) {
+      context.adaptor.logger.warn(`Cache write failed for ${context.key}: ${String(error)}`);
+    }
+  }
+}

package/signal/endpointInfo.ts

@@ -107,16 +107,20 @@ export class EndpointInfo<
     this.returns = EndpointInfo.getReturnInfo(returnRef, signalOption);
     this.signalOption = signalOption;
   }
+  #addArg(type: ArgType, name: string, arg: ConstantFieldTypeInput, option?: EndpointArgProps<boolean>) {
+    if (this.execFn) throw new Error("Query function is already set");
+    if (type !== "body" && type !== "search" && this.args.at(-1)?.option?.nullable)
+      throw new Error("Last argument is nullable");
+    this.argNames.push(name);
+    this.args.push(EndpointInfo.getArgInfo(type, name, arg, option));
+  }
   param<
     ArgName extends string,
     Arg extends ParamFieldType,
     _ClientArg = FieldToValue<Arg>,
     _ServerArg = DocumentModel<_ClientArg>,
   >(name: string, arg: Arg, option?: Omit<EndpointArgProps, "nullable">) {
-    if (this.execFn) throw new Error("Query function is already set");
-    else if (this.args.at(-1)?.option?.nullable) throw new Error("Last argument is nullable");
-    this.argNames.push(name);
-    this.args.push(EndpointInfo.getArgInfo("param", name, arg, option));
+    this.#addArg("param", name, arg, option);
     return this as unknown as EndpointInfo<
       ReqType,
       Srvs,
@@ -139,9 +143,7 @@ export class EndpointInfo<
     _ClientArg = UploadableClientArg<PurifiedModel<_ArgType>>,
     _ServerArg = DocumentModel<_ArgType>,
   >(name: ArgName, arg: Arg, option?: EndpointArgProps<Optional>) {
-    if (this.execFn) throw new Error("Query function is already set");
-    this.argNames.push(name);
-    this.args.push(EndpointInfo.getArgInfo("body", name, arg, option));
+    this.#addArg("body", name, arg, option);
     return this as unknown as EndpointInfo<
       ReqType,
       Srvs,
@@ -163,10 +165,7 @@ export class EndpointInfo<
     _ClientArg = PurifiedModel<_ArgType>,
     _ServerArg = DocumentModel<_ArgType>,
   >(name: string, arg: Arg, option?: Omit<EndpointArgProps, "nullable">) {
-    if (this.execFn) throw new Error("Query function is already set");
-    else if (this.args.at(-1)?.option?.nullable) throw new Error("Last argument is nullable");
-    this.argNames.push(name);
-    this.args.push(EndpointInfo.getArgInfo("room", name, arg, option));
+    this.#addArg("room", name, arg, option);
     return this as unknown as EndpointInfo<
       ReqType,
       Srvs,
@@ -189,10 +188,7 @@ export class EndpointInfo<
     _ClientArg = PurifiedModel<_ArgType>,
     _ServerArg = DocumentModel<_ArgType>,
   >(name: string, arg: Arg, option?: EndpointArgProps<Optional>) {
-    if (this.execFn) throw new Error("Query function is already set");
-    else if (this.args.at(-1)?.option?.nullable) throw new Error("Last argument is nullable");
-    this.argNames.push(name);
-    this.args.push(EndpointInfo.getArgInfo("msg", name, arg, option));
+    this.#addArg("msg", name, arg, option);
     return this as unknown as EndpointInfo<
       ReqType,
       Srvs,
@@ -214,9 +210,7 @@ export class EndpointInfo<
     _ClientArg = PurifiedModel<_ArgType>,
     _ServerArg = DocumentModel<_ArgType>,
   >(name: string, arg: Arg, option?: Omit<EndpointArgProps, "nullable">) {
-    if (this.execFn) throw new Error("Query function is already set");
-    this.argNames.push(name);
-    this.args.push(EndpointInfo.getArgInfo("search", name, arg, { ...option, nullable: true }));
+    this.#addArg("search", name, arg, { ...option, nullable: true });
     return this as unknown as EndpointInfo<
       ReqType,
       Srvs,
@@ -274,15 +268,7 @@ export class EndpointInfo<
       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>>[]) {
     for (const arg of args) {
       this.argNames.push(arg.name);
@@ -339,6 +325,19 @@ export class EndpointInfo<
         ...this.args.filter((arg) => arg.type === "param").map((arg) => `:${arg.name}`),
       ].join("/")}`;
   }
+
+  /** 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) {
+    return `${EndpointInfo.resolveServicePrefix(this.signalOption.prefix, defaultPrefix)}${this.getPath(key)}`;
+  }
+
+  static resolveServicePrefix(prefix: false | string | undefined, defaultPrefix?: string): string {
+    if (prefix === false || prefix === "") return "";
+    const resolved = prefix ?? defaultPrefix;
+    if (!resolved) return "";
+    const trimmed = resolved.trim().replace(/^\/+|\/+$/g, "");
+    return trimmed ? `/${trimmed}` : "";
+  }
 }
 
 export type BuildEndpoint<SrvModule extends ServiceModel = ServiceModel> = {

package/signal/exception.ts

@@ -1,31 +1,5 @@
-/**
- * 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;
 }
@@ -86,12 +60,7 @@ export class Exception extends Error {
   };
 }
 
-/**
- * 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/signal/guard.ts

@@ -6,32 +6,21 @@ export interface Guard {
 }
 
 /**
- * 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 const refusesAgents = (guards: readonly GuardCls[] | undefined): boolean =>
   !!guards?.some((GuardCls) => GuardCls.agents === false);
 
-/** Creates a named guard base class for signal access checks. */
+/** Starts as `scope = "account"`, the side that errs hidden. */
 export const guard = <T extends string>(name: T): GuardCls<T> => {
   return class Guard {
     static name = name;
@@ -42,12 +31,6 @@ export const guard = <T extends string>(name: T): GuardCls<T> => {
   };
 };
 
-/**
- * Guards read everything from the context they are handed and are already required to be side-effect free and
- * safe to re-run — `SignalResolver.revalidateWsRooms` re-runs them outside of any request — so one instance per
- * class serves every call instead of one per guard per request. Built on first use, not at registration: a guard
- * may be declared long before the container it reads from is up.
- */
 const instances = new WeakMap<GuardCls, Guard>();
 export const guardOf = (GuardCls: GuardCls): Guard => {
   const cached = instances.get(GuardCls);

package/signal/guards.ts

@@ -19,12 +19,8 @@ export class None implements Guard {
 }
 
 /**
- * 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 class AgentRelayAccess implements Guard {
   
@@ -40,10 +36,6 @@ export class AgentRelayAccess implements Guard {
     return !!AgentRelayAccess.#guards.length;
   }
 
-  /**
-   * 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 {
     return AgentRelayAccess.#guards.some((GuardCls) => GuardCls.scope === "resource") ? "resource" : "account";
   }

package/signal/index.ts

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

package/signal/internal.ts

@@ -7,7 +7,7 @@ import {
   type QueueAdaptor,
   QueueAdaptorRole,
   type ScheduleAdaptor,
-  Scheduler,
+  ScheduleAdaptorRole,
   type ServiceModel,
 } from "akanjs/service";
 import { type BuildInternal, buildInternal, type InternalBuilder, type InternalInfo } from "./internalInfo";
@@ -22,16 +22,12 @@ export type InternalCls<
   SrvModule extends ServiceModel = ServiceModel,
   InternalInfoMap extends { [key: string]: InternalInfo } = { [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 function internal<
   SrvModule extends ServiceModel,
   InternalInfoMap extends ReturnType<InternalBuilder<SrvModule>>,
@@ -49,17 +45,21 @@ export function internal<
     ]),
   ];
   const internalCls = class Internal extends dangerouslyAdapt(`${refName}Internal`, ({ plug, service }) => ({
-    schedule: plug(Scheduler),
+    schedule: plug(ScheduleAdaptorRole),
     queue: plug(QueueAdaptorRole),
     ...Object.fromEntries(srvKeys.map((srvRefName) => [srvRefName, service()])),
   })) {
     static srv = srv;
-    static [INTERNAL_META] = internalBuilder(buildInternal as any);
+    static [INTERNAL_META] = Object.assign(
+      {},
+      ...libInternals.map((libInternal) => libInternal[INTERNAL_META]),
+      internalBuilder(buildInternal as any),
+    );
   };
-  libInternals.forEach((libInternal) => {
-    Object.assign(internalCls[INTERNAL_META], libInternal[INTERNAL_META]);
-    Object.assign(internalCls.srv.srvMap, libInternal.srv.srvMap);
-  });
+  Object.assign(
+    srv.srvMap,
+    Object.assign({}, ...libInternals.map((libInternal) => libInternal.srv.srvMap), srv.srvMap),
+  );
   applyMixins(internalCls, libInternals);
   return internalCls as any; 
 }

package/signal/internalArg.ts

@@ -6,14 +6,12 @@ export interface InternalArg<ArgType = unknown> {
 }
 export type InternalArgCls<ArgType = unknown> = Cls<InternalArg<ArgType>>;
 
-/** Injects the current Bun request into an endpoint/internal handler. */
 export class Req implements InternalArg {
   getArg(context: SignalContext): Bun.BunRequest {
     const httpContext = context.getHttpContext();
     return httpContext.req;
   }
 }
-/** Injects the current mutable response context into an endpoint/internal handler. */
 export class Res implements InternalArg {
   getArg(context: SignalContext) {
     const httpContext = context.getHttpContext();
@@ -21,13 +19,14 @@ export class Res implements InternalArg {
   }
 }
 
-/**
- * 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 class CallerAccount implements InternalArg<unknown> {
+  getArg(context: SignalContext): unknown {
+    return context.get("account") ?? null;
+  }
+}
+
+/** The caller's IP as the nearest proxy recorded it (see `SignalContext.getClientIp`), `null` when unknown. */
 export class Ip implements InternalArg<string | null> {
   getArg(context: SignalContext): string | null {
     return context.getClientIp();
@@ -35,10 +34,8 @@ export class Ip implements InternalArg<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 class Ws implements InternalArg {
   getArg(context: SignalContext) {

package/signal/internalInfo.ts

@@ -72,7 +72,7 @@ export class InternalInfo<
     if (this.execFn) throw new Error("Query function is already set");
     this.internalArgs.push({
       argRef,
-      option: { ...option, ...(this.type === "resolveField" ? { nullable: true } : {}) }, //? for resolveField, nullable is true by default
+      option: { ...option, ...(this.type === "resolveField" ? { nullable: true } : {}) },
     });
     return this as unknown as InternalInfo<
       ReqType,