akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/signal/mcp/pagePrompt.ts

@@ -1,15 +1,13 @@
 import type { McpPromptArgument } from "./mcpProtocol";
 
-/** One `page().prompt(name, description)` as the catalogue lists it, with the route it was declared on. */
 export interface PagePromptEntry {
   name: string;
   description: string;
   arguments: McpPromptArgument[];
-  /** The matched route pattern (`/:lang/project/:projectId`), which is also what names the screen to a model. */
+  /** The matched route pattern, e.g. `/:lang/project/:projectId`. */
   pattern: string;
 }
 
-/** One `fetch.*` query the page made while its body ran, with the answer it received. */
 export interface PagePromptRecord {
   key: string;
   args: Record<string, unknown>;
@@ -29,16 +27,12 @@ export interface PagePromptRunInput {
   name: string;
   /** `prompts/get` sends a flat string map; the page's own declaration types each value. */
   arguments: Record<string, string>;
-  /** The caller's request headers the page run should carry — the bearer token above all. */
   headers: [string, string][];
-  /** The locale segment the synthetic URL starts with; the route needs one whether or not the page reads it. */
+  /** The synthetic URL's locale segment, which the route needs whether or not the page reads it. */
   language?: string;
 }
 
-/**
- * Where page prompts come from. Pages live in the RSC worker, a process apart from the one that serves `/mcp`,
- * so the MCP router speaks to them through this rather than by importing route modules of its own.
- */
+/** Pages live in the RSC worker, a process apart from the one serving `/mcp`, so the router reaches them through this. */
 export interface PagePromptSource {
   list(): Promise<PagePromptEntry[]>;
   run(input: PagePromptRunInput): Promise<PagePromptRun>;

package/signal/middleware.ts

@@ -1,9 +1,7 @@
 import type { BackendEnv, Cls, PromiseOrObject } from "akanjs/base";
 import { Logger } from "akanjs/common";
-import { type CacheAdaptor, CacheAdaptorRole } from "akanjs/service";
-import dayjs from "dayjs";
+import { Exception } from "./exception";
 import type { SignalContext } from "./signalContext";
-import { traceCache } from "./trace";
 
 export interface Middleware<Env extends BackendEnv = BackendEnv> {
   use(env: Env): PromiseOrObject<(context: SignalContext, next: () => Promise<unknown>) => PromiseOrObject<unknown>>;
@@ -26,7 +24,7 @@ export class Logging extends middleware("logging") {
   override async use() {
     return async (context: SignalContext, next: () => Promise<unknown>) => {
       const start = Date.now();
-
+      
       const debug = Logger.shouldLog("debug");
       if (debug) context.adaptor.logger.debug(`Before ${context.endpointInfo.type}-${context.key} / ${start}`);
       try {
@@ -46,71 +44,23 @@ export class Logging extends middleware("logging") {
   }
 }
 
-export class Cache extends middleware("cache") {
-  override async use() {
-    return async (context: SignalContext, next: () => Promise<unknown>) => {
-      const cache = context.getAdaptor(CacheAdaptorRole) as unknown as CacheAdaptor;
-      const topic = "cache";
-      const key = `${context.key}:${JSON.stringify(context.args)}`;
-
-      const cached = await cache.get<string>(topic, key);
-      if (cached) {
-        context.adaptor.logger.debug(`Cache hit ${context.key}`);
-        try {
-          const parsed = JSON.parse(cached);
-          traceCache(true);
-          return parsed;
-        } catch (parseError) {
-          context.adaptor.logger.warn(`Cache parse error ${context.key}: ${String(parseError)}`);
-          await cache.delete(topic, key);
-        }
-      }
-      traceCache(false);
-
-      const result = await next();
-
-      context.adaptor.logger.debug(`Caching result type ${context.key}: ${typeof result} / ${Array.isArray(result)}`);
-
-      const serialized = JSON.stringify(result);
-      await cache.set(topic, key, serialized, { expireAt: dayjs().add(60, "second") });
-
-      return result;
-    };
-  }
-}
-
 export class Timeout extends middleware("timeout") {
   override async use() {
     return async (context: SignalContext, next: () => Promise<unknown>) => {
-      const timeout = context.endpointInfo.signalOption.timeout ?? 5000;
-      return Promise.race([
-        next(),
-        new Promise((_, reject) => setTimeout(() => reject(new Error(`Request timeout after ${timeout}ms`)), timeout)),
-      ]);
-    };
-  }
-}
-
-export class Retry extends middleware("retry") {
-  override async use() {
-    return async (context: SignalContext, next: () => Promise<unknown>) => {
-      const maxRetries = 3;
-      let lastError: Error | null = null;
-
-      for (let attempt = 0; attempt < maxRetries; attempt++) {
-        try {
-          return await next();
-        } catch (error) {
-          lastError = error instanceof Error ? error : new Error(String(error));
-          console.warn(`[${context.key}] Retry ${attempt + 1}/${maxRetries}:`, lastError.message);
-
-          if (attempt < maxRetries - 1) {
-            
-            await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 100));
-          }
-        }
+      const timeout = context.endpointInfo.signalOption.timeout;
+      if (!timeout || !Number.isFinite(timeout) || timeout <= 0) return await next();
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        return await Promise.race([
+          next(),
+          
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Exception(504, "base.error.gatewayTimeout")), timeout);
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
       }
-      throw lastError;
     };
   }
 }

package/signal/openapi/openapi.ts

@@ -31,10 +31,6 @@ export interface OpenApiDocument {
   };
 }
 
-/**
- * Every endpoint type this app answers over HTTP, which is what an API contract has to list. The websocket types
- * (`pubsub`, `message`) have no HTTP surface to describe and are absent for that reason rather than by omission.
- */
 const httpMethods = {
   query: "get",
   mutation: "post",

package/signal/schema/JsonSchemaBuilder.ts

@@ -5,60 +5,45 @@ import type { SerializedArg, SerializedReturns } from "../types";
 export type JsonSchema = Record<string, unknown>;
 
 export interface JsonSchemaBuilderOptions {
-  /**
-   * Where a model `$ref` points. OpenAPI collects every model under `components/schemas`, while MCP requires each
-   * tool schema to resolve on its own and so embeds its models in a per-schema `$defs`.
-   */
+  /** Default `#/components/schemas/` (OpenAPI); MCP embeds each tool's models in a per-schema `$defs`. */
   refPrefix?: string;
-  /**
-   * How a nullable schema is spelled. `anyOf` with a null branch is the OpenAPI habit and the default; `type` merges
-   * `"null"` into a schema that has one plain `type` (and lists `null` in its `enum`, which would otherwise still
-   * refuse it) — the shorter form a listing that is re-sent to every agent is paid for by the byte.
-   */
+  /** `anyOf` (default) adds a null branch; `type` merges `"null"` into a plain `type` (and its `enum`), shorter. */
   nullable?: "anyOf" | "type";
+  /** `wire` (default) is the HTTP body shape; `agent` uses a primitive's `agent.schema` when it declares one. */
+  face?: JsonSchemaFace;
 }
 
+export type JsonSchemaFace = "wire" | "agent";
+
 export type JsonSchemaRelations = "inline" | "id" | "named";
 
 export interface JsonSchemaModelOptions {
   /**
-   * Drops `hidden`, `secret`, and `visual` fields. `SignalContext.resolveReturn` strips the first two from every
-   * response, so naming them describes a value the caller can never read — and on a model like `user` the names
-   * are themselves the leak: `password`, `accountId`, `phone` published as readable properties of the model. This
-   * is the one place a field the framework blocks on every value path is still visible, so it is scoped to schemas
-   * that describe a *response*. A request body is a different shape and legitimately carries all three.
-   *
-   * `visual` is dropped here because it is dropped from the payload an AI caller receives, and a schema that
-   * promises a field the value omits is worse than one that never named it: a non-optional visual field would be
-   * listed `required` and a validating client would refuse the whole result.
+   * Response schemas only: drops `hidden`/`secret` (stripped from every response, and on `user` the names alone
+   * leak) and `visual` (stripped for AI callers, so listing it `required` would make a client refuse the result).
    */
   readable?: boolean;
   /**
-   * How a field holding another database model is described. `inline` follows the `$ref`, which is right where
-   * schemas share a component section. `id` is what a request body carries: `serialize` sends a relation as its id,
-   * so a schema showing the whole related object asks the caller for a shape the server never reads. `named` is for
-   * a response: the nested document becomes `{ type: "object" }` carrying its model name, so the returned model
-   * keeps every field of its own and stops dragging its relations' closures into each copy. An embedded scalar has
-   * no tool of its own and stays inline under either.
+   * A database-model field: `inline` (default) follows the `$ref`, `id` is what a request body carries, `named` is
+   * `{ type: "object" }` with the model name. An embedded scalar always stays inline.
    */
   relations?: JsonSchemaRelations;
-  /**
-   * Whether an id carries the 24-hex `pattern`. Kept on a top-level argument, where it is read once; dropped inside
-   * a per-tool `$defs`, where it would repeat on every id field of every copy.
-   */
+  /** Whether an id carries the 24-hex `pattern` (default `true`). */
   idPattern?: boolean;
 }
 
-/**
- * Turns serialized signal metadata and Akan constants into JSON Schema (2020-12 by default, which is also what
- * OpenAPI 3.1 uses). One builder per output dialect target — `new` it at the call site, it holds no shared state.
- */
 export class JsonSchemaBuilder {
   readonly #refPrefix: string;
   readonly #nullableForm: "anyOf" | "type";
-  constructor({ refPrefix = "#/components/schemas/", nullable = "anyOf" }: JsonSchemaBuilderOptions = {}) {
+  readonly #face: JsonSchemaFace;
+  constructor({
+    refPrefix = "#/components/schemas/",
+    nullable = "anyOf",
+    face = "wire",
+  }: JsonSchemaBuilderOptions = {}) {
     this.#refPrefix = refPrefix;
     this.#nullableForm = nullable;
+    this.#face = face;
   }
 
   arg(arg: SerializedArg): JsonSchema {
@@ -101,7 +86,6 @@ export class JsonSchemaBuilder {
     };
   }
 
-  /** Every registered model, keyed by schema name. Callers narrow this with `referencedSchemas`. */
   allModelSchemas(options: JsonSchemaModelOptions = {}): Record<string, JsonSchema> {
     const schemas: Record<string, JsonSchema> = {};
     for (const [, database] of ConstantRegistry.database.entries()) {
@@ -115,14 +99,7 @@ export class JsonSchemaBuilder {
     return schemas;
   }
 
-  /**
-   * The models `seed` references, plus everything those transitively reference, sorted by name.
-   *
-   * `allSchemas` is derived from the registry, so a caller that narrows many seeds against the same registry —
-   * MCP builds one per tool schema and one per output schema — passes its own copy rather than rebuilding every
-   * registered model each time. Holding it here instead would make this builder stateful, and the one in
-   * `openapi.ts` lives at module scope for the life of the process.
-   */
+  /** The transitive closure of the models `seed` references, sorted by name. Pass `allSchemas` when narrowing often. */
   referencedSchemas(seed: unknown, allSchemas: Record<string, JsonSchema> = this.allModelSchemas()) {
     const referencedNames = this.collectRefNames(seed);
     const pending = [...referencedNames];
@@ -170,14 +147,17 @@ export class JsonSchemaBuilder {
   }
 
   #ref(refName: string, modelType?: ConstantType): JsonSchema {
-    if (!modelType) return JsonSchemaBuilder.primitive(refName);
+    if (!modelType) return JsonSchemaBuilder.primitive(refName, { face: this.#face });
     const modelRef = ConstantRegistry.getModelRef(refName, modelType);
     return { $ref: `${this.#refPrefix}${ConstantRegistry.getModelName(modelRef as Cls)}` };
   }
 
   #modelRef(modelRef: Cls, { relations = "inline", idPattern = true }: JsonSchemaModelOptions = {}): JsonSchema {
     if (PrimitiveRegistry.has(modelRef))
-      return JsonSchemaBuilder.primitive(PrimitiveRegistry.getName(modelRef as typeof PrimitiveScalar), { idPattern });
+      return JsonSchemaBuilder.primitive(PrimitiveRegistry.getName(modelRef as typeof PrimitiveScalar), {
+        idPattern,
+        face: this.#face,
+      });
     if (relations !== "inline" && !ConstantRegistry.isScalar(modelRef as ConstantCls)) {
       if (relations === "id") return JsonSchemaBuilder.primitive("ID", { idPattern });
       return { type: "object", description: ConstantRegistry.getModelName(modelRef) };
@@ -210,7 +190,13 @@ export class JsonSchemaBuilder {
     return JsonSchemaBuilder.#inlineEnum([...enumRef.values]);
   }
 
-  static primitive(refName: string, { idPattern = true }: Pick<JsonSchemaModelOptions, "idPattern"> = {}): JsonSchema {
+  static primitive(
+    refName: string,
+    { idPattern = true, face = "wire" }: Pick<JsonSchemaModelOptions, "idPattern"> & { face?: JsonSchemaFace } = {},
+  ): JsonSchema {
+    const scalar = PrimitiveRegistry.hasName(refName) ? PrimitiveRegistry.get(refName) : null;
+    const declared = (face === "agent" ? scalar?.agent?.schema : undefined) ?? scalar?.jsonSchema;
+    if (declared) return { ...declared };
     switch (refName) {
       case "Boolean":
         return { type: "boolean" };
@@ -248,7 +234,7 @@ export class JsonSchemaBuilder {
 
   #nullable(schema: JsonSchema, nullable: boolean): JsonSchema {
     if (!nullable) return schema;
-
+    
     if (this.#nullableForm === "type" && typeof schema.type === "string" && !("$ref" in schema)) {
       const merged = { ...schema, type: [schema.type, "null"] };
       return Array.isArray(schema.enum) ? { ...merged, enum: [...schema.enum, null] } : merged;

package/signal/serializer/fetch.serializer.ts

@@ -18,7 +18,7 @@ import type {
   SliceCls,
   SliceInfo,
 } from "akanjs/signal";
-import { refusesAgents } from "../guard";
+import { type GuardCls, refusesAgents } from "../guard";
 
 export class FetchSerializer {
   static logger = new Logger("FetchSerializer");
@@ -61,15 +61,18 @@ export class FetchSerializer {
     };
   }
 
-  static #serializeEndpoint(endpointInfo: EndpointInfo): SerializedEndpoint {
+  static #serializeEndpoint(key: string, endpointInfo: EndpointInfo, defaultPrefix?: string): SerializedEndpoint {
     const guards = endpointInfo.signalOption.guards?.map((g) => g.name);
+    const { path, name, prefix, globalPrefix } = endpointInfo.signalOption;
     return {
       type: endpointInfo.type,
       args: endpointInfo.args.map(FetchSerializer.#serializeArg),
       returns: FetchSerializer.#serializeReturns(endpointInfo),
-      ...(endpointInfo.signalOption.path ? { path: endpointInfo.signalOption.path } : {}),
+      ...(path || name || prefix !== undefined ? { path: endpointInfo.getRoutePath(key, defaultPrefix) } : {}),
+      ...(globalPrefix === false ? { globalPrefix } : {}),
       ...(endpointInfo.signalOption.method ? { method: endpointInfo.signalOption.method } : {}),
       ...(endpointInfo.signalOption.fileUpload ? { fileUpload: true } : {}),
+      ...(endpointInfo.signalOption.timeout ? { timeout: endpointInfo.signalOption.timeout } : {}),
       ...(guards?.length ? { guards } : {}),
       ...(endpointInfo.signalOption.mcp === false ? { mcp: false as const } : {}),
       ...(refusesAgents(endpointInfo.signalOption.guards) ? { agents: false as const } : {}),
@@ -89,11 +92,7 @@ export class FetchSerializer {
       ...(argInfo.ref ? { ref: argInfo.ref } : {}),
     };
   }
-  /**
-   * The model's filter surface, which is what the root slice takes instead of a raw query. A client cannot
-   * offer a filter it cannot name, nor fill args it cannot type — so both travel, unlike the query map that
-   * used to stay server-side.
-   */
+  
   static #serializeFilter(sliceCls: SliceCls): SerializedFilter | undefined {
     const filterMeta = getFilterMeta(sliceCls.srv.db.filter, { allowEmpty: true });
     if (!filterMeta) return undefined;
@@ -126,47 +125,56 @@ export class FetchSerializer {
 
   static serializeDatabaseSignal(sliceCls: SliceCls, endpointCls: EndpointCls): SerializedSignal {
     const sliceMeta = sliceCls[SLICE_META] as { [key: string]: SliceInfo };
-    const endpointMeta = endpointCls[ENDPOINT_META] as { [key: string]: EndpointInfo };
     const prefix = sliceCls.srv.cnst?.refName;
     const slice: { [key: string]: SerializedSlice } = {};
     for (const [key, sliceInfo] of Object.entries(sliceMeta)) {
       slice[key] = FetchSerializer.#serializeSlice(sliceInfo);
     }
-    const endpoint: { [key: string]: SerializedEndpoint } = {};
-    for (const [key, endpointInfo] of Object.entries(endpointMeta)) {
-      endpoint[key] = FetchSerializer.#serializeEndpoint(endpointInfo);
-    }
     const filter = FetchSerializer.#serializeFilter(sliceCls);
-
+    
     const queryKeyArg = slice[""]?.args.find((arg) => arg.name === "queryKey");
     if (queryKeyArg && filter) queryKeyArg.oneOf = Object.keys(filter.filter);
     return {
       ...(prefix ? { prefix } : {}),
       ...(Object.keys(slice).length ? { slice } : {}),
       ...(filter ? { filter } : {}),
-      ...(sliceCls.getGuards.filter((g) => g.name !== "None").length
-        ? { getGuards: sliceCls.getGuards.map((g) => g.name) }
-        : {}),
-      ...(sliceCls.cruGuards.filter((g) => g.name !== "None").length
-        ? { cruGuards: sliceCls.cruGuards.map((g) => g.name) }
-        : {}),
-
-      ...(sliceCls.createGuards !== sliceCls.cruGuards && sliceCls.createGuards.filter((g) => g.name !== "None").length
-        ? { createGuards: sliceCls.createGuards.map((g) => g.name) }
-        : {}),
-      ...(sliceCls.updateGuards !== sliceCls.cruGuards && sliceCls.updateGuards.filter((g) => g.name !== "None").length
-        ? { updateGuards: sliceCls.updateGuards.map((g) => g.name) }
-        : {}),
-      ...(sliceCls.removeGuards !== sliceCls.cruGuards && sliceCls.removeGuards.filter((g) => g.name !== "None").length
-        ? { removeGuards: sliceCls.removeGuards.map((g) => g.name) }
-        : {}),
+      ...FetchSerializer.#guardNames("getGuards", sliceCls.getGuards),
+      ...FetchSerializer.#guardNames("cruGuards", sliceCls.cruGuards),
+      
+      ...FetchSerializer.#guardNames(
+        "createGuards",
+        sliceCls.createGuards,
+        sliceCls.createGuards !== sliceCls.cruGuards,
+      ),
+      ...FetchSerializer.#guardNames(
+        "updateGuards",
+        sliceCls.updateGuards,
+        sliceCls.updateGuards !== sliceCls.cruGuards,
+      ),
+      ...FetchSerializer.#guardNames(
+        "removeGuards",
+        sliceCls.removeGuards,
+        sliceCls.removeGuards !== sliceCls.cruGuards,
+      ),
       ...FetchSerializer.#serializeSliceMcp(sliceCls),
       ...FetchSerializer.#serializeSliceAgents(sliceCls),
-      endpoint,
+      endpoint: FetchSerializer.#serializeEndpoints(endpointCls),
     };
   }
 
-  /** The generated verbs a person-only guard protects, shaped like `mcp` so the client stamps both the same way. */
+  static #guardNames<Key extends string>(key: Key, guards: GuardCls[], emit = true) {
+    if (!emit || !guards.some((guard) => guard.name !== "None")) return {};
+    return { [key]: guards.map((guard) => guard.name) } as { [K in Key]: string[] };
+  }
+
+  static #serializeEndpoints(endpointCls: EndpointCls) {
+    const endpoint: { [key: string]: SerializedEndpoint } = {};
+    const defaultPrefix = endpointCls.srv.cnst?.refName;
+    for (const [key, endpointInfo] of Object.entries(endpointCls[ENDPOINT_META] as { [key: string]: EndpointInfo }))
+      endpoint[key] = FetchSerializer.#serializeEndpoint(key, endpointInfo, defaultPrefix);
+    return endpoint;
+  }
+
   static #serializeSliceAgents(sliceCls: SliceCls): { agents?: SerializedSignalMcp } {
     const agents: SerializedSignalMcp = {
       ...(refusesAgents(sliceCls.getGuards) ? { get: false as const } : {}),
@@ -177,7 +185,6 @@ export class FetchSerializer {
     return Object.keys(agents).length ? { agents } : {};
   }
 
-  /** Only the verbs kept off the shelf travel: `true` is the default, so emitting it would grow every payload. */
   static #serializeSliceMcp(sliceCls: SliceCls): { mcp?: SerializedSignalMcp } {
     const mcp = Object.fromEntries(
       Object.entries(sliceCls.mcp ?? {})
@@ -188,20 +195,10 @@ export class FetchSerializer {
   }
 
   static serializeServiceSignal(endpointCls: EndpointCls): SerializedSignal {
-    const endpointMeta = endpointCls[ENDPOINT_META] as { [key: string]: EndpointInfo };
-    const endpoint: { [key: string]: SerializedEndpoint } = {};
-    for (const [key, endpointInfo] of Object.entries(endpointMeta)) {
-      endpoint[key] = FetchSerializer.#serializeEndpoint(endpointInfo);
-    }
-    return { endpoint };
+    return { endpoint: FetchSerializer.#serializeEndpoints(endpointCls) };
   }
 
-  /**
-   * A container that never finished initializing has empty registries rather than none, so a caller reaching a
-   * devtools or MCP route before boot completed gets an empty catalogue. Destructuring the registry used to
-   * throw before the loop, which surfaced as `Cannot destructure property 'endpointCls' from null` on a route
-   * whose honest answer is "nothing is registered yet".
-   */
+  /** A container that has not finished booting answers an empty catalogue rather than throwing. */
   static serializeRegistry(live: LiveRegistry | null | undefined): {
     signal: { [key: string]: SerializedSignal };
   } {

package/signal/serverSignal.ts

@@ -56,25 +56,23 @@ export type ServerSignalCls<EnpCls = unknown, IntCls = unknown> = AdaptorCls<
 > &
   ServerSignalClsStatics;
 
-/** Composes endpoint and internal classes into a server-side signal class. */
 export const serverSignal = <EnpCls, IntCls>(
   endpointRef: EnpCls,
   internalRef: IntCls,
 ): ServerSignalCls<EnpCls, IntCls> => {
   const refName = (endpointRef as unknown as EndpointCls).refName.slice(0, -8);
   return class ServerSignal extends adapt(`${refName}Signal`, ({ plug }) => ({
-    
     queue: plug(QueueAdaptorRole),
   })) {
     static readonly [ENDPOINT_META] = Object.fromEntries(
-      Object.entries((endpointRef as unknown as EndpointCls)[ENDPOINT_META])
-        .filter(([key, endpointInfo]) => endpointInfo.type === "pubsub")
-        .map(([key, value]) => [key, value]),
+      Object.entries((endpointRef as unknown as EndpointCls)[ENDPOINT_META]).filter(
+        ([, endpointInfo]) => endpointInfo.type === "pubsub",
+      ),
     );
     static readonly [INTERNAL_META] = Object.fromEntries(
-      Object.entries((internalRef as unknown as InternalCls)[INTERNAL_META])
-        .filter(([key, internalInfo]) => internalInfo.type === "process")
-        .map(([key, value]) => [key, value]),
+      Object.entries((internalRef as unknown as InternalCls)[INTERNAL_META]).filter(
+        ([, internalInfo]) => internalInfo.type === "process",
+      ),
     );
   } as unknown as ServerSignalCls<EnpCls, IntCls>;
 };