akanjs 3.0.0-beta.1 → 3.0.0-beta.11

package/common/index.ts

@@ -17,6 +17,7 @@ export {
 } from "./clientAddress";
 export { deepObjectify } from "./deepObjectify";
 export type { DynamicRecord } from "./dynamicRecord";
+export { EventStream, type EventStreamOptions } from "./eventStream";
 export {
   type FileUploadCapability,
   fileUploadContract,
@@ -111,6 +112,38 @@ export { sleep } from "./sleep";
 export { splitVersion } from "./splitVersion";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute";
 export { TrustedProxy } from "./TrustedProxy";
+export { toPathSegments } from "./toPathSegments";
+export {
+  type TunnelAgentIdentity,
+  type TunnelAttachedFrame,
+  type TunnelAttachFrame,
+  type TunnelByeFrame,
+  type TunnelCloseCode,
+  type TunnelControlFromAgent,
+  type TunnelControlFromGateway,
+  type TunnelDataFromAgent,
+  type TunnelDataFromGateway,
+  type TunnelDemandFrame,
+  type TunnelEndFrame,
+  type TunnelFrame,
+  type TunnelHeaderList,
+  type TunnelHeadFrame,
+  type TunnelHelloFrame,
+  type TunnelOpenFrame,
+  type TunnelPingFrame,
+  type TunnelPongFrame,
+  type TunnelReadyFrame,
+  type TunnelReleaseFrame,
+  type TunnelResetCode,
+  type TunnelResetFrame,
+  type TunnelStreamKind,
+  type TunnelWsPayloadKind,
+  tunnelCloseCode,
+  tunnelForwardedHeaders,
+  tunnelHopByHopHeaders,
+  tunnelWireContract,
+  tunnelWsPayload,
+} from "./tunnelWire";
 export type * from "./types";
 export {
   type WebsocketAuthAckData,
@@ -118,3 +151,8 @@ export {
   websocketAuthContract,
 } from "./websocketAuth";
 export { type WebsocketBinaryFrame, websocketBinaryFrameContract } from "./websocketBinaryFrame";
+export {
+  type WebsocketHeartbeatAckData,
+  type WebsocketHeartbeatRequest,
+  websocketHeartbeatContract,
+} from "./websocketHeartbeat";

package/common/pathGet.ts

@@ -1,13 +1,23 @@
+import { toPathSegments } from "./toPathSegments";
+
 type Indexable = Record<string | number, unknown>;
+type PathSegment = string | number;
 
 const isIndexable = (value: unknown): value is Indexable => Object(value) === value;
 
+const readChild = (container: Indexable, key: PathSegment) =>
+  container instanceof Map ? (container as Map<PathSegment, unknown>).get(key) : container[key];
+
 export const pathGet = (
   path: string | (string | number)[],
   obj: unknown,
   separator = ".",
   fallback: unknown = null,
 ): unknown => {
-  const properties = Array.isArray(path) ? path : path.split(separator);
-  return properties.reduce((prev, curr) => (isIndexable(prev) ? (prev[curr] ?? fallback) : fallback), obj);
+
+  const properties = separator === "." ? toPathSegments(path) : Array.isArray(path) ? [...path] : path.split(separator);
+  return properties.reduce<unknown>(
+    (prev, curr) => (isIndexable(prev) ? (readChild(prev, curr) ?? fallback) : fallback),
+    obj,
+  );
 };

package/common/pathSet.ts

@@ -1,10 +1,9 @@
+import { toPathSegments } from "./toPathSegments";
+
 type MutableIndexable = Record<string | number, unknown>;
 type PathSegment = string | number;
 type Container = MutableIndexable | Map<PathSegment, unknown>;
 
-const toPathSegments = (path: string | readonly PathSegment[]) =>
-  Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];
-
 const readChild = (container: Container, key: PathSegment) =>
   container instanceof Map ? container.get(key) : container[key];
 

package/common/toPathSegments.ts

@@ -0,0 +1,10 @@
+type PathSegment = string | number;
+
+/**
+ * The one definition of what a dotted path's segments are, so a path that writes and a path that reads cannot
+ * disagree about it. `a.0.b` and `a[0].b` are the same three segments — the bracket form is what a form field
+ * hands `writeOn<Model>`, and a read of the same path has to accept the same spelling or the agent can write
+ * somewhere it cannot read back.
+ */
+export const toPathSegments = (path: string | readonly PathSegment[]) =>
+  Array.isArray(path) ? [...path] : path.toString().match(/[^.[\]]+/g) || [];

package/common/tunnelWire.ts

@@ -0,0 +1,355 @@
+import { forwardedHeaders } from "./clientAddress";
+
+/**
+ * The wire between a tunnel agent (inside the `akan` CLI, on a private machine) and the tunnel gateway (public,
+ * in the cluster). It is the only thing the two sides share, so it lives here rather than in either of them.
+ *
+ * **Shape: one control socket plus a pool of data sockets, one stream per data socket.** No multiplexing and no
+ * hand-written flow control — the runtime already does per-socket flow control, and a single multiplexed socket
+ * would have to re-implement windowing to keep one large download from starving every other stream. The cost is
+ * a socket per concurrent stream, which pooling amortizes.
+ *
+ * **Framing is the WebSocket frame type.** A text frame is always one JSON control message of this module; a
+ * binary frame is always payload. Nothing else needs a header, a length prefix, or a stream id on the hot path,
+ * because a data socket carries exactly one stream at a time.
+ *
+ * Every socket is dialled by the agent — the gateway can never reach in. That is the whole reason a tunnel needs
+ * no public IP, no inbound port, and no NAT traversal.
+ */
+
+/**
+ * `http` and `tcp` bodies are raw binary frames; a `websocket` stream prefixes each one — see `tunnelWsPayload`.
+ *
+ * `tcp` describes the **provider** side only: an agent dialling a local port. What opens a `tcp` stream in the
+ * first place — a local listener somewhere else that a person points `ssh` at — is undefined in version 1, and
+ * naming that role is a version 1 addition rather than a breaking change.
+ */
+export type TunnelStreamKind = "http" | "websocket" | "tcp";
+
+export type TunnelResetCode =
+  | "originUnreachable"
+  | "originTimeout"
+  | "originRefused"
+  | "protocol"
+  | "canceled"
+  | "tooLarge"
+  | "internal";
+
+/**
+ * Pairs rather than a record: `set-cookie` legitimately repeats, and a record keyed by name keeps only the last
+ * one — which silently drops every session cookie but one on a sign-in response.
+ */
+export type TunnelHeaderList = [string, string][];
+
+export interface TunnelAgentIdentity {
+  /** What the operator called this share, for the gateway's log and the control plane's UI. */
+  name: string;
+  version: string;
+  platform: string;
+}
+
+export interface TunnelHelloFrame {
+  type: "hello";
+  version: number;
+  /** What the agent intends to serve. The gateway answers with what the token actually grants. */
+  hostnames: string[];
+  agent: TunnelAgentIdentity;
+}
+
+export interface TunnelReadyFrame {
+  type: "ready";
+  version: number;
+  sessionId: string;
+  /** Authoritative — the agent serves these and nothing else, whatever it asked for. */
+  hostnames: string[];
+  /** The public URLs, already assembled, so the CLI prints what the gateway believes rather than guessing. */
+  urls: string[];
+  /** How many idle data sockets to hold, and the ceiling past which the agent refuses to grow the pool. */
+  idle: number;
+  maxSockets: number;
+  heartbeatMs: number;
+  /** Epoch ms, when the control plane put a TTL on this share. */
+  expiresAt?: number;
+}
+
+export interface TunnelPingFrame {
+  type: "ping";
+  at: number;
+}
+
+export interface TunnelPongFrame {
+  type: "pong";
+  at: number;
+}
+
+/** The gateway noticed the idle pool running short; the agent grows it to `idle`, capped by `maxSockets`. */
+export interface TunnelDemandFrame {
+  type: "demand";
+  idle: number;
+}
+
+/** A graceful goodbye from either side, so the peer stops reconnecting instead of treating it as a drop. */
+export interface TunnelByeFrame {
+  type: "bye";
+  reason?: string;
+}
+
+export type TunnelControlFromAgent = TunnelHelloFrame | TunnelPingFrame | TunnelPongFrame | TunnelByeFrame;
+export type TunnelControlFromGateway =
+  | TunnelReadyFrame
+  | TunnelPingFrame
+  | TunnelPongFrame
+  | TunnelDemandFrame
+  | TunnelByeFrame;
+
+/** First frame on a data socket. The session id names which agent connection this socket belongs to. */
+export interface TunnelAttachFrame {
+  type: "attach";
+  version: number;
+  sessionId: string;
+}
+
+/** The socket joined the idle pool. Until this arrives the agent must not count it toward `idle`. */
+export interface TunnelAttachedFrame {
+  type: "attached";
+}
+
+export interface TunnelOpenFrame {
+  type: "open";
+  streamId: string;
+  kind: TunnelStreamKind;
+  /** Which tunnel host the public caller addressed, for an agent serving more than one. */
+  hostname: string;
+  /** `http` and `websocket`. */
+  method?: string;
+  /** `http` and `websocket`: path plus query, already percent-encoded. */
+  path?: string;
+  /**
+   * `http` and `websocket`. The agent replays this list verbatim, so the gateway owes it two things.
+   *
+   * **Strip every name in `forwardedHeaderNames` from what the public caller sent, then write its own.** Not
+   * append — `hostFromRequest` reads `x-forwarded-host?.split(",")[0]`, so a caller-supplied value placed ahead
+   * of the gateway's wins, and the app computes its own origin from a host the caller chose. That is Host header
+   * injection: every absolute URL the app builds — a redirect, a password-reset link, an OAuth callback — points
+   * at the attacker's host.
+   *
+   * **Write `x-forwarded-host` as the tunnel hostname.** It is what `hostFromRequest` reads, so the app behind
+   * the tunnel resolves its own origin as the public URL and `CrossSiteGuard` compares the host the browser
+   * actually addressed. Leave it off and every mutation from a tunnelled page is refused.
+   *
+   * Hop-by-hop names are stripped by both ends independently (`isHopByHop`); these cannot be, because only the
+   * gateway knows who the public caller was.
+   */
+  headers?: TunnelHeaderList;
+  /** `tcp`: the port on the local origin to dial. */
+  port?: number;
+  /** Whether payload frames follow this one. Absent or false means the request is complete as sent. */
+  body?: boolean;
+}
+
+export interface TunnelHeadFrame {
+  type: "head";
+  streamId: string;
+  /**
+   * `101` accepts a `websocket` open and `200` accepts a `tcp` one; any other status is the agent declining, and
+   * the gateway answers the public caller with it rather than upgrading.
+   */
+  status: number;
+  statusText?: string;
+  headers: TunnelHeaderList;
+  body?: boolean;
+}
+
+/** No more payload in the direction this was sent. Each direction ends independently. */
+export interface TunnelEndFrame {
+  type: "end";
+  streamId: string;
+}
+
+/** The stream failed. The socket is not reusable after one and is closed rather than returned to the pool. */
+export interface TunnelResetFrame {
+  type: "reset";
+  streamId: string;
+  code: TunnelResetCode;
+  message?: string;
+}
+
+/**
+ * Gateway → agent, after both directions have ended: the socket is idle again.
+ *
+ * Only `http` streams are released. A `websocket` or `tcp` stream owns its socket for its whole life and the
+ * socket closes with it — resynchronizing a raw byte stream back to an idle pool buys nothing and is a place
+ * for a desync to hide.
+ */
+export interface TunnelReleaseFrame {
+  type: "release";
+  streamId: string;
+}
+
+/**
+ * A payload frame carries no stream id — a data socket holds one stream at a time, which is what keeps the hot
+ * path free of a header. Three invariants are what make that safe, and an optimization that breaks any one of
+ * them desynchronizes the socket silently:
+ *
+ * 1. Neither side sends a payload frame after its own `end` for that stream.
+ * 2. `release` goes out only once *both* directions have ended.
+ * 3. A JSON frame naming a `streamId` other than the current one is dropped — that is what the id is for.
+ */
+export type TunnelDataFromAgent = TunnelAttachFrame | TunnelHeadFrame | TunnelEndFrame | TunnelResetFrame;
+export type TunnelDataFromGateway =
+  | TunnelAttachedFrame
+  | TunnelOpenFrame
+  | TunnelEndFrame
+  | TunnelResetFrame
+  | TunnelReleaseFrame;
+
+export type TunnelFrame =
+  | TunnelControlFromAgent
+  | TunnelControlFromGateway
+  | TunnelDataFromAgent
+  | TunnelDataFromGateway;
+
+/**
+ * A tunnelled WebSocket's own text/binary distinction cannot ride the tunnel socket's, which is already spoken
+ * for by the control/payload split — so a `websocket` stream prefixes every payload frame with one byte. `http`
+ * and `tcp` payload frames carry no prefix; their bytes are a stream with nothing to distinguish.
+ */
+export const tunnelWsPayload = {
+  text: 0,
+  binary: 1,
+  /** Remainder is UTF-8 JSON `{ code, reason }` — the inner close, which is not the tunnel socket closing. */
+  close: 2,
+} as const;
+
+export type TunnelWsPayloadKind = (typeof tunnelWsPayload)[keyof typeof tunnelWsPayload];
+
+/**
+ * Hop-by-hop headers, which describe one connection and are meaningless on the next. The gateway strips them
+ * from what it forwards and the agent strips them from what it sends back, so neither end has to trust the other
+ * to have done it.
+ */
+export const tunnelHopByHopHeaders = [
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "proxy-connection",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade",
+] as const;
+
+/**
+ * Close codes, and the **only** way a refusal reaches the agent. The 4000 range is the application range every
+ * WebSocket implementation passes through verbatim; an HTTP status does not survive the upgrade, because a
+ * refused upgrade reaches the client as a bare `1006` with no code and no reason. The agent treats these codes
+ * as final and every other close as a dropped link to retry — so a gateway that answers `401` at the upgrade
+ * instead of accepting it and closing with `unauthorized` makes an agent retry a revoked token forever.
+ *
+ * **Accept the upgrade, then close on a later tick.** Closing inside the socket's own `open` handler races the
+ * handshake the runtime is still finishing, and the client sees `1006` again with the code discarded.
+ */
+export const tunnelCloseCode = {
+  unauthorized: 4001,
+  unsupportedVersion: 4002,
+  hostnameNotGranted: 4003,
+  unknownSession: 4004,
+  /** A newer session for the same tunnel took over; this one must not reconnect. */
+  superseded: 4005,
+  streamLimit: 4008,
+  goingAway: 4009,
+} as const;
+
+export type TunnelCloseCode = (typeof tunnelCloseCode)[keyof typeof tunnelCloseCode];
+
+/**
+ * Headers naming the original caller. The gateway deletes these from what arrived before writing its own — see
+ * `TunnelOpenFrame.headers`. `forwarded` is RFC 7239's single-header form of the same claim, and omitting it
+ * would leave one spelling of the injection open.
+ */
+export const tunnelForwardedHeaders = [...forwardedHeaders, "forwarded"] as const;
+
+const hopByHop = new Set<string>(tunnelHopByHopHeaders);
+
+export const tunnelWireContract = {
+  version: 1,
+  controlPath: "/_tunnel/control",
+  dataPath: "/_tunnel/data",
+  /**
+   * Both upgrades carry `Authorization: Bearer <connectorToken>` and nothing else — no code in the path, no
+   * query, no second header. Keeping the URL bare is what keeps the tunnel's identity out of every access log
+   * between here and the gateway, so the token is also the *only* thing the gateway can resolve a tunnel from:
+   * it owns a `token -> { code, hostnames }` lookup, and the agent never names which tunnel it is.
+   */
+  authScheme: "Bearer",
+  defaultIdleSockets: 4,
+  defaultMaxSockets: 128,
+  defaultHeartbeatMs: 30_000,
+
+  /** What a sender splits an `http` or `tcp` payload to. A boundary means nothing in a byte stream. */
+  chunkBytes: 64 * 1024,
+  /**
+   * What both ends must accept — `maxPayloadLength` on every tunnel socket is set to at least this.
+   *
+   * It clears 16 MB because an inner websocket message is a **message**: splitting it loses the boundary the
+   * receiver needs, so it rides as one frame, and `akanApp` lets an app's own sockets carry 16 MB. The default
+   * `maxPayloadLength` is 16 MB, which the largest legal inner message plus its one-byte prefix exceeds by
+   * exactly the amount that makes a 100 MB upload fail on the frame that carries its last kilobyte.
+   */
+  maxFrameBytes: 16 * 1024 * 1024 + 4096,
+
+  /** Deletes every `forwardedHeaderNames` entry, so the gateway writes its own onto a clean slate. */
+  stripForwarded: (headers: Headers): Headers => {
+    for (const name of tunnelForwardedHeaders) headers.delete(name);
+    return headers;
+  },
+
+  forwardedHeaderNames: tunnelForwardedHeaders,
+
+  isHopByHop: (name: string): boolean => hopByHop.has(name.toLowerCase()),
+
+  /** `Headers.forEach` combines repeats into one comma-joined value — except `set-cookie`, which it yields one
+   * at a time. That exception is what makes this lossless. */
+  headerList: (headers: Headers): TunnelHeaderList => {
+    const list: TunnelHeaderList = [];
+    headers.forEach((value, name) => {
+      if (!hopByHop.has(name.toLowerCase())) list.push([name, value]);
+    });
+    return list;
+  },
+
+  headersOf: (list: TunnelHeaderList): Headers => {
+    const headers = new Headers();
+    for (const [name, value] of list) {
+      if (!hopByHop.has(name.toLowerCase())) headers.append(name, value);
+    }
+    return headers;
+  },
+
+  encodeWsPayload: (kind: TunnelWsPayloadKind, data: Uint8Array): Uint8Array => {
+    const framed = new Uint8Array(data.byteLength + 1);
+    framed[0] = kind;
+    framed.set(data, 1);
+    return framed;
+  },
+
+  decodeWsPayload: (frame: Uint8Array): { kind: TunnelWsPayloadKind; data: Uint8Array } | null => {
+    if (!frame.byteLength) return null;
+    const kind = frame[0] as TunnelWsPayloadKind;
+    if (kind !== tunnelWsPayload.text && kind !== tunnelWsPayload.binary && kind !== tunnelWsPayload.close) return null;
+    return { kind, data: frame.subarray(1) };
+  },
+
+  /** A frame that does not parse is a protocol error, never something to guess at — hence `null`, not a throw. */
+  parseFrame: (raw: string): TunnelFrame | null => {
+    try {
+      const frame = JSON.parse(raw) as TunnelFrame;
+      return frame && typeof frame === "object" && typeof (frame as { type?: unknown }).type === "string"
+        ? frame
+        : null;
+    } catch {
+      return null;
+    }
+  },
+} as const;

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/common/websocketHeartbeat.ts

@@ -0,0 +1,27 @@
+export interface WebsocketHeartbeatRequest {
+  key: string;
+  data: [];
+}
+
+export interface WebsocketHeartbeatAckData {
+  type: "pong";
+}
+
+/**
+ * Framework-owned websocket keep-alive. A browser cannot send a protocol-level ping frame — `WebSocket` exposes
+ * no API for one — so a socket that nobody publishes to carries no bytes at all, and every intermediary with an
+ * idle timeout (nginx `proxy_read_timeout` 60s, most CDNs, a tunnel gateway) reaps it. The server's own
+ * `idleTimeout` is 0, so this exists for what sits between.
+ *
+ * The ack matters as much as the ping: a half-open socket still accepts `send()` without error, so inbound
+ * traffic is the only evidence the peer is still there.
+ */
+export const websocketHeartbeatContract = {
+  key: "__ping",
+  /** Under the 60s idle timeout nginx and most CDNs ship with. */
+  intervalMs: 45_000,
+  /** How long without any inbound frame before the socket is assumed half-open and reconnected. */
+  silenceMs: 45_000 * 3,
+  makeRequest: (): WebsocketHeartbeatRequest => ({ key: "__ping", data: [] }),
+  makeAck: (): WebsocketHeartbeatAckData => ({ type: "pong" }),
+} as const;

package/dictionary/agentTurn.dictionary.ts

@@ -19,11 +19,15 @@ export const agentTurnDictionary = scalarDictionary(["en", "ko"])
       "클라이언트가 실행할 툴 호출 목록 ({ id, name, args })",
     ]),
     stop: t(["Stop", "종료 사유"]).desc([
-      "Why the turn ended — end, or toolUse when tool results are awaited",
-      "턴이 끝난 이유 — end 또는 툴 결과를 기다리는 toolUse",
+      "Why the turn ended — end, toolUse when tool results are awaited, or length when the provider cut it off",
+      "턴이 끝난 이유 — end, 툴 결과를 기다리는 toolUse, 프로바이더가 잘라낸 length",
     ]),
   }))
   .enum<AgentStop>("agentStop", (t) => ({
     end: t(["End", "종료"]).desc(["The final answer", "최종 응답"]),
     toolUse: t(["Tool Use", "툴 사용"]).desc(["The model awaits tool results", "모델이 툴 결과를 기다린다"]),
+    length: t(["Length", "길이 초과"]).desc([
+      "The provider's answer ceiling cut the turn off, so it is incomplete",
+      "프로바이더의 응답 상한에 걸려 턴이 잘렸다. 미완성이다",
+    ]),
   }));

package/dictionary/base.dictionary.ts

@@ -81,6 +81,11 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
     agentAttach: ["Attach a file", "파일 첨부"],
     agentAttachRemove: ["Remove attachment", "첨부 제거"],
     agentAttachReading: ["Reading…", "읽는 중…"],
+    agentReferenceRemove: ["Remove reference", "참조 제거"],
+    agentReferenceFailed: [
+      "{label} could not be read, so the agent has only its name.",
+      "{label}을(를) 읽지 못해 이름만 전달됩니다.",
+    ],
     agentAttachTooLarge: ["{name} is too large to attach.", "{name}은(는) 용량이 너무 커서 첨부할 수 없습니다."],
     agentAttachUnsupported: ["{name} cannot be attached here.", "{name}은(는) 여기에 첨부할 수 없습니다."],
     agentAttachDuplicate: ["{name} is already attached.", "{name}은(는) 이미 첨부되어 있습니다."],

package/fetch/agentTurn.ts

@@ -1,7 +1,7 @@
 import { Any, enumOf } from "akanjs/base";
 import { ConstantRegistry, via } from "akanjs/constant";
 
-export class AgentStop extends enumOf("agentStop", ["end", "toolUse"] as const) {}
+export class AgentStop extends enumOf("agentStop", ["end", "toolUse", "length"] as const) {}
 
 export class AgentTurn extends via((field) => ({
   text: field(String, { default: "" }), // the assistant's words; empty when the turn is only tool calls

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(/\/$/, "");
   }