akanjs 3.0.0-beta.4 → 3.0.0-beta.6

package/common/types.ts

@@ -5,7 +5,11 @@ export interface FetchPolicy<Returns = unknown> {
   onError?: (error: string) => void;
   token?: string;
   partial?: string[];
-  timeout?: number;
+  /**
+   * Milliseconds before this call is abandoned, `false` to wait as long as the runtime will. Overrides the
+   * endpoint's declared `timeout`, which overrides the client's own default.
+   */
+  timeout?: number | false;
   /**
    * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
    *

package/fetch/client/fetchClient.ts

@@ -173,6 +173,13 @@ export class FetchClient {
         }
       : signal;
   }
+  /**
+   * The budget for every call that neither names one nor is served by an endpoint declaring one. `false` waits
+   * as long as the runtime will, which is the browser's own limit — minutes.
+   */
+  setTimeout(timeout?: number | false) {
+    this.http.setTimeout(timeout);
+  }
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
     this.http.setErrorConstructor(ErrorCls);
@@ -316,8 +323,9 @@ export class FetchClient {
           const url = FetchClient.makeHttpUrl(key, endpoint, prefix, argMap);
           const headers = this.#makeAuthHeaders(option);
           const baseUrl = option?.origin;
+          const timeout = option?.timeout ?? endpoint.timeout;
 
-          const requestQuery = () => this.http.get(url, { headers, baseUrl });
+          const requestQuery = () => this.http.get(url, { headers, baseUrl, timeout });
 
           const claim = baseUrl
             ? { value: requestQuery(), owned: true }
@@ -339,6 +347,7 @@ export class FetchClient {
           const response = await this.http.send(endpoint.method ?? "POST", url, body, {
             headers: this.#makeAuthHeaders(option),
             baseUrl: option?.origin,
+            timeout: option?.timeout ?? endpoint.timeout,
           });
           const parsedReturn = parseReturn(response, { crystalize: option?.crystalize ?? true });
           return parsedReturn;
@@ -827,7 +836,15 @@ export class FetchClient {
       connect = false,
       base,
       Err,
-    }: { origin?: string; connect?: boolean; base?: FetchProxy; Err?: ErrorConstructor } = {},
+      timeout,
+    }: {
+      origin?: string;
+      connect?: boolean;
+      base?: FetchProxy;
+      Err?: ErrorConstructor;
+      /** This app's own default request budget, for calls no endpoint and no caller gave one. */
+      timeout?: number | false;
+    } = {},
   ): {
     sig: ClientSignalMap<SigType>;
     fetch: SigType["fetch"];
@@ -838,6 +855,7 @@ export class FetchClient {
     const proxy =
       shared ??
       FetchClient.#makeProxy<unknown, Record<string, SliceMeta>>(new FetchClient(origin, {}, serializedSignal, Err));
+    if (timeout !== undefined) proxy.instance.setTimeout(timeout);
     if (connect) proxy.instance.connect();
     const sig = {} as any;
     Object.entries(serializedSignal).forEach(([refName, serializedSignal]) => {

package/fetch/client/httpClient.ts

@@ -49,6 +49,10 @@ export class HttpClient {
   setErrorConstructor(ErrorCls?: ErrorConstructor) {
     this.ErrorCls = ErrorCls;
   }
+  /** The budget every call that names none takes. `false` waits as long as the runtime will. */
+  setTimeout(timeout?: number | false) {
+    this.#timeout = timeout;
+  }
   #resolveBaseUrl(baseUrl?: string) {
     return (baseUrl ?? this.baseUrl).replace(/\/$/, "");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.6",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/di/diLifecycle.ts

@@ -17,7 +17,7 @@ import { agentTurnConstant, agentTurnDocument } from "../../signal/agentTurn";
 import { Base, BaseEndpoint, BaseInternal } from "../../signal/base.signal";
 import type { Endpoint } from "../../signal/endpoint";
 import type { Internal } from "../../signal/internal";
-import { Logging, type MiddlewareCls } from "../../signal/middleware";
+import { Cache, Logging, type MiddlewareCls, Timeout } from "../../signal/middleware";
 import type { ServerSignal, ServerSignalCls } from "../../signal/serverSignal";
 import { SignalRegistry } from "../../signal/signalRegistry";
 import type { AkanLib, DatabaseModule, ScalarModule, ServiceModule } from "../akanLib";
@@ -126,6 +126,10 @@ export class DiLifecycle {
       : null;
     if (frameworkAgent) this.#service.set("agent", frameworkAgent);
     this.#middleware.set(Logging.refName, Logging);
+
+    this.#middleware.set(Timeout.refName, Timeout);
+
+    this.#middleware.set(Cache.refName, Cache);
     const defaultOption = createDefaultAkanOption();
     defaultOption.getMiddlewares().forEach((middleware) => {
       this.#middleware.set(middleware.refName, middleware);

package/service/predefinedAdaptor/anthropicLlm.ts

@@ -297,9 +297,15 @@ export class AnthropicLlm
     return source.type === "base64" ? { ...source, media_type: mimeType } : source;
   }
 
+  /**
+   * Bytes beat an address when a host sent both: it already paid for them on the way in, and the address it also
+   * sent is the one it renders — which the default storage backend serves on a path only the app can resolve.
+   * Picking that costs a confident answer about a picture nothing fetched; picking the bytes costs one hop that
+   * already carries them. A URL the provider really can reach travels alone.
+   */
   static sourceOf(attachment: AgentWireAttachment): AnthropicSource | null {
-    if (attachment.url) return { type: "url", url: attachment.url };
     if (attachment.data) return { type: "base64", media_type: attachment.mimeType, data: attachment.data };
+    if (attachment.url) return { type: "url", url: attachment.url };
     return null;
   }
 

package/service/predefinedAdaptor/openaiDialect.ts

@@ -122,7 +122,7 @@ export class OpenaiDialect {
    * Text attachments are labelled into the message, because a model handed two unlabelled documents can no longer
    * cite either one. Images become their own parts only when the provider said it reads them; the dialect carries
    * one as a `data:` URL, which is the same encoding whether the bytes were inlined or already addressable, so
-   * both carriers take one branch.
+   * both carriers take one branch — the inlined bytes first, for the reason named at the branch.
    */
   static userContent(message: AgentWireMessage, accepts?: LlmAccepts): string | OpenaiContentPart[] {
     const attachments = message.attachments ?? [];
@@ -144,7 +144,8 @@ export class OpenaiDialect {
             );
             return [];
           }
-          const url = attachment.url ?? (attachment.data ? `data:${mimeType};base64,${attachment.data}` : "");
+
+          const url = attachment.data ? `data:${mimeType};base64,${attachment.data}` : (attachment.url ?? "");
           return url ? [{ type: "image_url" as const, image_url: { url } }] : [];
         });
     const text = [message.text, ...blocks, ...notes].filter(Boolean).join("\n\n");

package/signal/middleware.ts

@@ -2,6 +2,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";
 
@@ -46,71 +47,105 @@ export class Logging extends middleware("logging") {
   }
 }
 
+/**
+ * Serves an endpoint's own answer back for as long as its declared `cache` allows, and stands aside for every
+ * endpoint that declared none — this is registered by default, so a TTL of its own would put a stale window on
+ * every call in the app.
+ *
+ * A cached answer is **shared**, which is why only a `query` taking no internal argument can carry one: internal
+ * arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them answers per caller
+ * and one entry would be one caller's answer handed to the next. Guards are re-run on every hit regardless —
+ * shared is not public, and `next()`, which is what runs them, is exactly what a hit skips.
+ */
 export class Cache extends middleware("cache") {
+  static #topic = "cache";
+  static #refused = new Set<string>();
+
   override async use() {
     return async (context: SignalContext, next: () => Promise<unknown>) => {
+      const ttl = context.endpointInfo.signalOption.cache;
+      if (!ttl || !Number.isFinite(ttl) || ttl <= 0) return await next();
+      if (!Cache.#cacheable(context)) return await next();
       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);
-        }
+      const cached = await Cache.#read(context, cache, key);
+      if (cached !== undefined) {
+        await context.checkGuards();
+        traceCache(true);
+        return cached;
       }
       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") });
-
+      await Cache.#write(context, cache, key, result, ttl);
       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)),
-      ]);
-    };
+  /**
+   * The handler's inputs are its declared arguments and its internal arguments, so an endpoint with none of the
+   * latter answers the same thing to everyone who may read it — which is the only answer a shared entry can hold.
+   * A `cache` declared anywhere else is named once rather than silently ignored.
+   */
+  static #cacheable(context: SignalContext) {
+    if (context.endpointInfo.type === "query" && context.endpointInfo.internalArgs.length === 0) return true;
+    if (Cache.#refused.has(context.key)) return false;
+    Cache.#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;
+  }
+  /** A cache backend that is down must not take the endpoint down with it: the call runs uncached instead. */
+  static async #read(context: SignalContext, cache: CacheAdaptor, key: string) {
+    try {
+      const cached = await cache.get<string>(Cache.#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(Cache.#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(Cache.#topic, key, serialized, { expireAt: dayjs().add(ttl, "millisecond") });
+    } catch (error) {
+      context.adaptor.logger.warn(`Cache write failed for ${context.key}: ${String(error)}`);
+    }
   }
 }
 
-export class Retry extends middleware("retry") {
+/**
+ * Bounds an endpoint that declared a `timeout`, and nothing else — this is registered by default, so a default
+ * of its own would put a deadline on every endpoint in the app that nobody asked for.
+ *
+ * XXX losing the race does not cancel the work: `next()` keeps running with nobody holding its result, so a
+ * handler that writes is still going to write. The deadline answers the caller; it does not undo the call.
+ */
+export class Timeout extends middleware("timeout") {
   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);
+      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(),
 
-          if (attempt < maxRetries - 1) {
-            
-            await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 100));
-          }
-        }
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Exception(504, "base.error.gatewayTimeout")), timeout);
+          }),
+        ]);
+      } finally {
+        
+        clearTimeout(timer);
       }
-      throw lastError;
     };
   }
 }

package/signal/serializer/fetch.serializer.ts

@@ -70,6 +70,7 @@ export class FetchSerializer {
       ...(endpointInfo.signalOption.path ? { path: endpointInfo.signalOption.path } : {}),
       ...(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 } : {}),

package/signal/signalContext.ts

@@ -154,10 +154,17 @@ export class SignalContext<
         throw new Exception.Forbidden(`Access denied by guard: ${GuardCls.name}`);
     }
   }
+  /**
+   * The endpoint's guards, for a middleware that answers a call without executing it — a cache hit skips
+   * `next()`, and `next()` is what would otherwise run them. Side-effect free, like the guards themselves.
+   */
+  async checkGuards() {
+    await this.#checkGuards();
+  }
   /**
    * Re-checks this context's guards outside of a request, for a websocket room that is already
    * subscribed. Only global middlewares run: they carry the account resolution this depends on,
-   * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
+   * while endpoint middlewares (cache/retry) would observe a call that never executes.
    */
   async authorize(): Promise<boolean> {
     try {

package/signal/types.ts

@@ -81,8 +81,26 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
   default?: boolean;
   path?: string;
   serverMode?: "federation" | "batch" | "all";
+  /**
+   * How long this endpoint may take, in milliseconds. It bounds both ends: the `Timeout` middleware — registered
+   * by default — rejects the call with `base.error.gatewayTimeout` once it is spent, and the value is serialized
+   * to the client, where it becomes that call's request budget in place of the client default. Declared nowhere,
+   * neither side imposes one beyond the client's own default.
+   *
+   * Losing the race does not stop the work: the handler runs to completion with nobody holding its result.
+   */
   timeout?: number;
   partial?: _Key[] | readonly _Key[];
+  /**
+   * How long this endpoint's answer may be reused, in milliseconds. The `Cache` middleware — registered by
+   * default — keeps the handler's result under the endpoint's key and its arguments and serves it until it
+   * expires; declared nowhere, nothing is cached.
+   *
+   * **Only a `query` that takes no internal argument may carry one.** Internal arguments are how a call learns
+   * who is asking (`.with(Self)`), so an endpoint that has them answers per caller, and one shared entry would be
+   * one caller's answer handed to the next; such an endpoint is named in the log and left uncached. Guards still
+   * run on every hit — a shared answer is not a public one.
+   */
   cache?: number;
   guards?: GuardCls[];
   middlewares?: MiddlewareCls[];
@@ -180,6 +198,12 @@ export interface SerializedArg {
 export interface SerializedEndpoint extends SerializedSignalOption {
   type: "query" | "mutation" | "pubsub" | "message";
   returns: SerializedReturns;
+  /**
+   * The deadline the endpoint declared, in milliseconds. It travels because the client has to size its own
+   * request budget from it: a call the server is allowed to spend five minutes on is one the browser must not
+   * abandon after the client default.
+   */
+  timeout?: number;
 }
 export interface SerializedFilter {
   /** Every filter query the model declares, by key, with the args each one takes. */

package/types/common/types.d.ts

@@ -5,7 +5,11 @@ export interface FetchPolicy<Returns = unknown> {
     onError?: (error: string) => void;
     token?: string;
     partial?: string[];
-    timeout?: number;
+    /**
+     * Milliseconds before this call is abandoned, `false` to wait as long as the runtime will. Overrides the
+     * endpoint's declared `timeout`, which overrides the client's own default.
+     */
+    timeout?: number | false;
     /**
      * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
      *

package/types/fetch/client/fetchClient.d.ts

@@ -55,6 +55,11 @@ export declare class FetchClient {
     };
     static resetSharedRegistry(): void;
     static resetSharedClient(): void;
+    /**
+     * The budget for every call that neither names one nor is served by an endpoint declaring one. `false` waits
+     * as long as the runtime will, which is the browser's own limit — minutes.
+     */
+    setTimeout(timeout?: number | false): void;
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
     applySignal(serializedSignal: {
         [key: string]: SerializedSignal;
@@ -88,11 +93,13 @@ export declare class FetchClient {
         fetch: any;
     }>(constant: object, serializedSignal: {
         [key: string]: SerializedSignal;
-    }, { origin, connect, base, Err, }?: {
+    }, { origin, connect, base, Err, timeout, }?: {
         origin?: string;
         connect?: boolean;
         base?: FetchProxy;
         Err?: ErrorConstructor;
+        /** This app's own default request budget, for calls no endpoint and no caller gave one. */
+        timeout?: number | false;
     }): {
         sig: ClientSignalMap<SigType>;
         fetch: SigType["fetch"];

package/types/fetch/client/httpClient.d.ts

@@ -15,6 +15,8 @@ export declare class HttpClient {
     private ErrorCls?;
     constructor(baseUrl: string, options?: HttpClientOptions);
     setErrorConstructor(ErrorCls?: ErrorConstructor): void;
+    /** The budget every call that names none takes. `false` waits as long as the runtime will. */
+    setTimeout(timeout?: number | false): void;
     get<Returns = unknown>(url: string, options?: FetchOptions): Promise<Returns>;
     send<Returns = unknown>(method: HttpMutationMethod, url: string, data: FormData | Record<string, unknown>, options?: FetchOptions): Promise<Returns>;
     put<Returns = unknown>(url: string, data: FormData | Record<string, unknown>, options?: FetchOptions): Promise<Returns>;

package/types/service/predefinedAdaptor/anthropicLlm.d.ts

@@ -109,6 +109,12 @@ export declare class AnthropicLlm extends AnthropicLlm_base implements LlmAdapto
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicBlock[];
     /** The block's `media_type` is the essence, not whatever parameters the browser attached to it. */
     static typed(source: AnthropicSource, mimeType: string): AnthropicSource;
+    /**
+     * Bytes beat an address when a host sent both: it already paid for them on the way in, and the address it also
+     * sent is the one it renders — which the default storage backend serves on a path only the app can resolve.
+     * Picking that costs a confident answer about a picture nothing fetched; picking the bytes costs one hop that
+     * already carries them. A URL the provider really can reach travels alone.
+     */
     static sourceOf(attachment: AgentWireAttachment): AnthropicSource | null;
     static turnAnswer(answer: AnthropicAnswer): LlmTurnAnswer;
     /** The ceiling wins over the calls that did arrive — see `OpenaiDialect.stopOf` for why. */

package/types/service/predefinedAdaptor/openaiDialect.d.ts

@@ -77,7 +77,7 @@ export declare class OpenaiDialect {
      * Text attachments are labelled into the message, because a model handed two unlabelled documents can no longer
      * cite either one. Images become their own parts only when the provider said it reads them; the dialect carries
      * one as a `data:` URL, which is the same encoding whether the bytes were inlined or already addressable, so
-     * both carriers take one branch.
+     * both carriers take one branch — the inlined bytes first, for the reason named at the branch.
      */
     static userContent(message: AgentWireMessage, accepts?: LlmAccepts): string | OpenaiContentPart[];
     /**

package/types/signal/middleware.d.ts

@@ -27,8 +27,19 @@ declare const Cache_base: {
     };
     refName: string;
 };
+/**
+ * Serves an endpoint's own answer back for as long as its declared `cache` allows, and stands aside for every
+ * endpoint that declared none — this is registered by default, so a TTL of its own would put a stale window on
+ * every call in the app.
+ *
+ * A cached answer is **shared**, which is why only a `query` taking no internal argument can carry one: internal
+ * arguments are how a call learns who is asking (`.with(Self)`), so an endpoint that has them answers per caller
+ * and one entry would be one caller's answer handed to the next. Guards are re-run on every hit regardless —
+ * shared is not public, and `next()`, which is what runs them, is exactly what a hit skips.
+ */
 export declare class Cache extends Cache_base {
-    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<any>>;
+    #private;
+    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
 }
 declare const Timeout_base: {
     new (): {
@@ -36,16 +47,14 @@ declare const Timeout_base: {
     };
     refName: string;
 };
+/**
+ * Bounds an endpoint that declared a `timeout`, and nothing else — this is registered by default, so a default
+ * of its own would put a deadline on every endpoint in the app that nobody asked for.
+ *
+ * XXX losing the race does not cancel the work: `next()` keeps running with nobody holding its result, so a
+ * handler that writes is still going to write. The deadline answers the caller; it does not undo the call.
+ */
 export declare class Timeout extends Timeout_base {
     use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
 }
-declare const Retry_base: {
-    new (): {
-        use(env: BackendEnv): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
-    };
-    refName: string;
-};
-export declare class Retry extends Retry_base {
-    use(): Promise<(context: SignalContext, next: () => Promise<unknown>) => Promise<unknown>>;
-}
 export {};

package/types/signal/signalContext.d.ts

@@ -56,10 +56,15 @@ export declare class SignalContext<Ctx extends HttpExecutionContext | WebSocketE
     getAdaptor<T extends Adaptor>(adaptorCls: AdaptorCls<T>): T;
     getService<T>(refName: string): T;
     init(): Promise<this>;
+    /**
+     * The endpoint's guards, for a middleware that answers a call without executing it — a cache hit skips
+     * `next()`, and `next()` is what would otherwise run them. Side-effect free, like the guards themselves.
+     */
+    checkGuards(): Promise<void>;
     /**
      * Re-checks this context's guards outside of a request, for a websocket room that is already
      * subscribed. Only global middlewares run: they carry the account resolution this depends on,
-     * while endpoint middlewares (cache/timeout/retry) would observe a call that never executes.
+     * while endpoint middlewares (cache/retry) would observe a call that never executes.
      */
     authorize(): Promise<boolean>;
     /**

package/types/signal/types.d.ts

@@ -69,8 +69,26 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
     default?: boolean;
     path?: string;
     serverMode?: "federation" | "batch" | "all";
+    /**
+     * How long this endpoint may take, in milliseconds. It bounds both ends: the `Timeout` middleware — registered
+     * by default — rejects the call with `base.error.gatewayTimeout` once it is spent, and the value is serialized
+     * to the client, where it becomes that call's request budget in place of the client default. Declared nowhere,
+     * neither side imposes one beyond the client's own default.
+     *
+     * Losing the race does not stop the work: the handler runs to completion with nobody holding its result.
+     */
     timeout?: number;
     partial?: _Key[] | readonly _Key[];
+    /**
+     * How long this endpoint's answer may be reused, in milliseconds. The `Cache` middleware — registered by
+     * default — keeps the handler's result under the endpoint's key and its arguments and serves it until it
+     * expires; declared nowhere, nothing is cached.
+     *
+     * **Only a `query` that takes no internal argument may carry one.** Internal arguments are how a call learns
+     * who is asking (`.with(Self)`), so an endpoint that has them answers per caller, and one shared entry would be
+     * one caller's answer handed to the next; such an endpoint is named in the log and left uncached. Guards still
+     * run on every hit — a shared answer is not a public one.
+     */
     cache?: number;
     guards?: GuardCls[];
     middlewares?: MiddlewareCls[];
@@ -168,6 +186,12 @@ export interface SerializedArg {
 export interface SerializedEndpoint extends SerializedSignalOption {
     type: "query" | "mutation" | "pubsub" | "message";
     returns: SerializedReturns;
+    /**
+     * The deadline the endpoint declared, in milliseconds. It travels because the client has to size its own
+     * request budget from it: a call the server is allowed to spend five minutes on is one the browser must not
+     * abandon after the client default.
+     */
+    timeout?: number;
 }
 export interface SerializedFilter {
     /** Every filter query the model declares, by key, with the args each one takes. */

package/types/ui/Agent/Attach.d.ts

@@ -5,7 +5,7 @@ interface AttachProps {
     onPick: (files: File[]) => void;
 }
 export declare const Attach: ({ className, label, onPick }: AttachProps) => import("react/jsx-runtime").JSX.Element;
-interface ChipsProps {
+export interface ChipsProps {
     className?: string;
     attachments: readonly MessageAttachment[];
     /** Omitted for a sent message: what is already on the wire cannot be taken back. */

package/types/ui/Agent/Chat.d.ts

@@ -72,9 +72,10 @@ export interface ChatProps {
      * the built-in, so it can also replace how an image is prepared.
      *
      * **A `url` is handed to the provider as the address it will fetch**, so answer `data` whenever the provider
-     * cannot reach it. A reader that uploads is the natural place to get this wrong: the default storage backend
-     * serves a path only this app can resolve, and a model handed one answers about a picture it never saw, with
-     * nothing anywhere reporting a failure.
+     * cannot reach it — the default storage backend serves a path only this app can resolve, and a model handed one
+     * answers about a picture it never saw with nothing anywhere reporting a failure. Answering **both** is the
+     * shape for that case: bytes are what the provider is given, and the address is what the chip draws, so an
+     * uploading reader gets a thumbnail without betting the answer on who can reach its storage.
      */
     attach?: AttachReader;
     /**

package/types/ui/Loading/Spin.d.ts

@@ -1,8 +1,24 @@
 import type { ReactNode } from "react";
 export interface SpinProps {
+    className?: string;
+    /**
+     * Replaces the built-in icon. It carries its own color; the rotation is the wrapper's
+     * (`[&>svg]:animate-spin`), so the node needs no `animate-spin` of its own.
+     */
     indicator?: ReactNode;
     isCenter?: boolean;
-    className?: string;
-    size?: "sm" | "md" | "lg";
+    /** A named step, or the pixel size the icon is drawn at. */
+    size?: "sm" | "md" | "lg" | number;
+    /**
+     * What the built-in icon is colored with. `"current"` inherits the surface's own foreground, which is what a
+     * filled surface needs — `text-primary/70` is legible on the app background and vanishes on a `bg-info` badge
+     * or a primary button. Every tone loses to a `text-*` in `className`.
+     */
+    tone?: "primary" | "current" | "muted";
 }
-export declare const Spin: ({ indicator, isCenter, className, size }: SpinProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * The color and the size sit on the wrapper, not on the icon: the icon is drawn at `1em` in `currentColor`, so
+ * both cascade to it — and `className`, which is also the wrapper's, is merged last and therefore wins. On the
+ * icon they would have been unreachable, which is what made every `text-*` and `size-*` a caller passed a no-op.
+ */
+export declare const Spin: ({ className, indicator, isCenter, size, tone }: SpinProps) => import("react/jsx-runtime").JSX.Element;

package/types/ui/index.d.ts

@@ -1,6 +1,7 @@
 export { AgentProvider, type AgentProviderProps, type AgentRunner, AgentSession, type AgentSessionOptions, type ChatMessage, type CompactOptions, type ContextBlock, httpRunner, type MessageAttachment, type PublishedTool, type RunnerEvent, type RunnerRequest, SessionContext, type SessionHistory, type SurfaceView, useAgent, } from "../vendor/use-agentic.d.ts";
 export { Agent } from "./Agent.d.ts";
 export { type ApprovalProps, DefaultApproval } from "./Agent/Approval.d.ts";
+export { Chips as AgentAttachments, type ChipsProps as AgentAttachmentsProps } from "./Agent/Attach.d.ts";
 export { type AgentSessionSetup, agentSessionOf } from "./Agent/agentSessionOf.d.ts";
 export { type AttachLimits, type AttachReader, maxAttachmentBytes, maxMessageAttachmentBytes, maxMessageAttachments, } from "./Agent/attachment.d.ts";
 export { type BubbleProps, DefaultBubble } from "./Agent/Bubble.d.ts";

package/ui/Agent/Attach.tsx

@@ -38,7 +38,7 @@ export const Attach = ({ className, label, onPick }: AttachProps) => {
   );
 };
 
-interface ChipsProps {
+export interface ChipsProps {
   className?: string;
 
   attachments: readonly MessageAttachment[];
@@ -57,11 +57,11 @@ export const Chips = ({ className, attachments, onRemove, removeLabel, pending =
         className="flex items-center gap-1 rounded-field bg-muted px-2 py-0.5 text-xs"
         key={`${attachment.name}-${idx}`}
       >
-        {attachment.data && attachment.mimeType?.startsWith("image/") ? (
+        {(attachment.data || attachment.url) && attachment.mimeType?.startsWith("image/") ? (
           <img
             alt={attachment.name}
             className="size-6 rounded-field object-cover"
-            src={`data:${attachment.mimeType};base64,${attachment.data}`}
+            src={attachment.data ? `data:${attachment.mimeType};base64,${attachment.data}` : attachment.url}
           />
         ) : null}
         <span className="max-w-32 truncate">{attachment.name}</span>

package/ui/Agent/Chat.tsx

@@ -111,9 +111,10 @@ export interface ChatProps {
    * the built-in, so it can also replace how an image is prepared.
    *
    * **A `url` is handed to the provider as the address it will fetch**, so answer `data` whenever the provider
-   * cannot reach it. A reader that uploads is the natural place to get this wrong: the default storage backend
-   * serves a path only this app can resolve, and a model handed one answers about a picture it never saw, with
-   * nothing anywhere reporting a failure.
+   * cannot reach it — the default storage backend serves a path only this app can resolve, and a model handed one
+   * answers about a picture it never saw with nothing anywhere reporting a failure. Answering **both** is the
+   * shape for that case: bytes are what the provider is given, and the address is what the chip draws, so an
+   * uploading reader gets a thumbnail without betting the answer on who can reach its storage.
    */
   attach?: AttachReader;
   /**

package/ui/Agent/sessionHistory.ts

@@ -8,16 +8,19 @@ export type PersistOption = boolean | { storage?: "session" | "local"; key?: str
  * chunk of it, and `AgentSession` swallows a failed save — so persisting the bytes would quietly stop persisting
  * the transcript itself. The name and type stay so a restored conversation still reads as what happened, and a
  * `url` stays because a pointer is not content; the server then tells the model the content is gone rather than
- * letting it answer from the filename.
+ * letting it answer from the filename. A `ref` stays for the same reason and matters more: it is the host's own
+ * handle on the file, so dropping it leaves a restored conversation with nothing but a name and size to guess
+ * from — the guess `ref` exists to retire.
  */
 const withoutContent = (message: ChatMessage): ChatMessage =>
   message.attachments?.length
     ? {
         ...message,
-        attachments: message.attachments.map(({ name, mimeType, url }) => ({
+        attachments: message.attachments.map(({ name, mimeType, url, ref }) => ({
           name,
           mimeType,
           ...(url ? { url } : {}),
+          ...(ref ? { ref } : {}),
         })),
       }
     : message;

package/ui/Loading/Spin.tsx

@@ -3,26 +3,46 @@ import type { ReactNode } from "react";
 import { AiOutlineLoading3Quarters } from "react-icons/ai";
 
 export interface SpinProps {
+  className?: string;
+  /**
+   * Replaces the built-in icon. It carries its own color; the rotation is the wrapper's
+   * (`[&>svg]:animate-spin`), so the node needs no `animate-spin` of its own.
+   */
   indicator?: ReactNode;
   isCenter?: boolean;
-  className?: string;
-  size?: "sm" | "md" | "lg";
+  /** A named step, or the pixel size the icon is drawn at. */
+  size?: "sm" | "md" | "lg" | number;
+  /**
+   * What the built-in icon is colored with. `"current"` inherits the surface's own foreground, which is what a
+   * filled surface needs — `text-primary/70` is legible on the app background and vanishes on a `bg-info` badge
+   * or a primary button. Every tone loses to a `text-*` in `className`.
+   */
+  tone?: "primary" | "current" | "muted";
 }
 
 const sizeClass = { sm: "text-sm", md: "text-xl", lg: "text-3xl" } as const;
+const toneClass = { primary: "text-primary/70", current: "", muted: "text-muted-foreground" } as const;
 
-export const Spin = ({ indicator, isCenter, className, size = "md" }: SpinProps) => (
+/**
+ * The color and the size sit on the wrapper, not on the icon: the icon is drawn at `1em` in `currentColor`, so
+ * both cascade to it — and `className`, which is also the wrapper's, is merged last and therefore wins. On the
+ * icon they would have been unreachable, which is what made every `text-*` and `size-*` a caller passed a no-op.
+ */
+export const Spin = ({ className, indicator, isCenter, size = "md", tone = "primary" }: SpinProps) => (
   <div
     className={cn(
       "inline-block py-1",
+      !indicator && toneClass[tone],
+      typeof size === "string" && sizeClass[size],
       isCenter && "absolute inset-0 flex size-full items-center justify-center py-0",
       className,
     )}
+    style={typeof size === "number" ? { fontSize: size } : undefined}
   >
     {indicator ? (
       <span className="[&>svg]:animate-spin">{indicator}</span>
     ) : (
-      <AiOutlineLoading3Quarters className={cn("animate-spin text-primary/70", sizeClass[size])} />
+      <AiOutlineLoading3Quarters className="animate-spin" />
     )}
   </div>
 );

package/ui/index.ts

@@ -21,6 +21,7 @@ export {
 } from "../vendor/use-agentic";
 export { Agent } from "./Agent";
 export { type ApprovalProps, DefaultApproval } from "./Agent/Approval";
+export { Chips as AgentAttachments, type ChipsProps as AgentAttachmentsProps } from "./Agent/Attach";
 export { type AgentSessionSetup, agentSessionOf } from "./Agent/agentSessionOf";
 export {
   type AttachLimits,

package/vendor/use-agentic/Compaction.ts

@@ -100,7 +100,9 @@ export class Compaction {
   static #line(message: ChatMessage): string {
     const parts: string[] = [];
     if (message.text) parts.push(Compaction.#clip(message.text, 1200));
-    for (const attachment of message.attachments ?? []) parts.push(`[attached ${attachment.name}]`);
+
+    for (const attachment of message.attachments ?? [])
+      parts.push(`[attached ${attachment.name}, content not carried into this summary]`);
     for (const call of message.toolCalls ?? [])
       parts.push(`[called ${call.name} ${Compaction.#clip(JSON.stringify(call.args), 200)}]`);
     for (const result of message.toolResults ?? [])