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

package/types/common/eventStream.d.ts

@@ -0,0 +1,18 @@
+export interface EventStreamOptions {
+    keepAliveMs?: number;
+    /** What the keep-alive sends; a line starting with `:` is a comment every SSE client discards. */
+    keepAliveChunk?: string;
+}
+export declare class EventStream {
+    #private;
+    static readonly defaultKeepAliveMs = 15000;
+    constructor(onCancel: () => void, { keepAliveMs, keepAliveChunk }?: EventStreamOptions);
+    get open(): boolean;
+    response(headers?: {
+        [key: string]: string;
+    }): Response;
+    write(message: object, id?: string | number): void;
+    comment(text: string): void;
+    retry(ms: number): void;
+    close(): void;
+}

package/types/common/fileUpload.d.ts

@@ -1,11 +1,3 @@
-interface FileUploadSerializedEndpoint {
-    fileUpload?: boolean;
-}
-interface FileUploadSerializedSignal {
-    prefix?: string;
-    endpoint: Record<string, FileUploadSerializedEndpoint>;
-}
-/** Framework-owned file-upload contract shared by client-safe packages. */
 export declare const fileUploadContract: {
     readonly fields: {
         readonly files: "files";
@@ -23,6 +15,9 @@ export interface FileUploadCapability {
     endpointKey: string;
     prefix?: string;
 }
-/** Discovers the upload endpoint marked with `{ fileUpload: true }` from the serialized signal. */
-export declare const resolveFileUploadCapability: (serializedSignal: Record<string, FileUploadSerializedSignal>) => FileUploadCapability | null;
-export {};
+export declare const resolveFileUploadCapability: (serializedSignal: Record<string, {
+    prefix?: string;
+    endpoint: Record<string, {
+        fileUpload?: boolean;
+    }>;
+}>) => FileUploadCapability | null;

package/types/common/index.d.ts

@@ -1,43 +1,44 @@
-export { applyMixins } from "./applyMixins.d.ts";
+export { applyMixins, getAllPropertyDescriptors } from "./applyMixins.d.ts";
 export { authTokenKey, cookieHeaderHasAuthToken, isAuthTokenKey, isOwnAuthToken, legacyAuthTokenKey, readAuthToken, } from "./authToken.d.ts";
-export { capitalize } from "./capitalize.d.ts";
+export { CodeAgentClient, type CodeAgentTransport } from "./CodeAgentClient.d.ts";
+export { CodeTranscript, type CodeTranscriptPart } from "./CodeTranscript.d.ts";
+export { capitalize, lowerlize } from "./capitalize.d.ts";
 export { clamp } from "./clamp.d.ts";
 export { clientAddressFromHeaders, clientPortFromHeaders, forwardedHeaders, normalizeIpAddress, } from "./clientAddress.d.ts";
-export { deepObjectify } from "./deepObjectify.d.ts";
-export type { DynamicRecord } from "./dynamicRecord.d.ts";
+export { type CodeAgentApprovalPolicy, type CodeAgentBuiltinTool, type CodeAgentInteractionMode, type CodeAgentMcpAuthState, type CodeAgentMcpServerRef, type CodeAgentMcpStatus, type CodeAgentModelInfo, type CodeAgentPresetName, type CodeAgentProfile, type CodeAgentProviderInfo, type CodeAgentSubagentBudget, codeAgentDeniedPaths, codeAgentPresets, codeAgentReadOnlyBuiltins, isCodeAgentPresetName, } from "./codeAgentProfile.d.ts";
+export { type CodeAgentAnswer, type CodeAgentApprovalRequest, type CodeAgentCommand, type CodeAgentCommandType, type CodeAgentEffort, type CodeAgentEvent, type CodeAgentEventBody, type CodeAgentEventType, type CodeAgentFrame, type CodeAgentImage, type CodeAgentQuestion, type CodeAgentQuestionOption, type CodeAgentReply, type CodeAgentRequest, type CodeAgentSessionInfo, type CodeAgentStartOptions, type CodeAgentState, type CodeAgentStopReason, type CodeAgentSubagent, type CodeAgentToolOp, type CodeAgentToolOutcome, type CodeAgentToolSummary, codeAgentClip, codeAgentEventLabel, codeAgentEventPersistence, codeAgentLabelChars, codeAgentOutputChars, codeAgentRenderAnswer, codeAgentSessionName, codeAgentShouldPersist, codeAgentWireVersion, isCodeAgentReply, } from "./codeAgentWire.d.ts";
+export { EventStream, type EventStreamOptions } from "./eventStream.d.ts";
 export { type FileUploadCapability, fileUploadContract, resolveFileUploadCapability, } from "./fileUpload.d.ts";
 export { formatNumber } from "./formatNumber.d.ts";
-export { formatPhone } from "./formatPhone.d.ts";
-export { getAllPropertyDescriptors } from "./getAllPropertyDescriptors.d.ts";
 export { type AkanHmrPhase, getAkanHmrPhase, isAkanHmrApplying } from "./hmrPhase.d.ts";
 export { interpolateTranslation } from "./interpolateTranslation.d.ts";
 export { isDayjs } from "./isDayjs.d.ts";
 export { isEmail } from "./isEmail.d.ts";
-export { isPhoneNumber } from "./isPhoneNumber.d.ts";
 export { isQueryEqual } from "./isQueryEqual.d.ts";
+export { isRecord } from "./isRecord.d.ts";
 export { isThenable } from "./isThenable.d.ts";
 export { isValidDate } from "./isValidDate.d.ts";
 export { decodeJwtPayload } from "./jwtDecode.d.ts";
 export { type LogAttrs, type LogAttrValue, type LogFormat, Logger, type LoggerEmitInput, type LoggerSink, type LoggerSinkEntry, type LoggerSinkOptions, type LogLevel, type LogLevelInput, type LogRecord, logFormats, logLevels, logSeverity, } from "./Logger.d.ts";
 export { type AkanI18nConfig, type AkanI18nConfigInput, DEFAULT_AKAN_I18N, parseAkanI18nEnv, resolveAkanI18nConfig, } from "./localeConfig.d.ts";
 export { type LogContextReader, type LogContextSnapshot, type LogFlightRecorder, readLogContext, registerLogContextReader, } from "./logContext.d.ts";
-export { lowerlize } from "./lowerlize.d.ts";
+export { type MarkdownBlock, MarkdownBlocks, type MarkdownItem } from "./markdownBlocks.d.ts";
+export { type MarkdownSpan, MarkdownSpans } from "./markdownSpans.d.ts";
+export { type Align, MarkdownTable, type TableBlock } from "./markdownTable.d.ts";
 export { isMcpDescribableArg, type McpExposureEndpoint, type McpExposureOption, mcpBaseVerbOf, mcpHintsOf, mcpRefusalOf, } from "./mcpExposure.d.ts";
-export { mergeVersion } from "./mergeVersion.d.ts";
-export { objectify } from "./objectify.d.ts";
-export { pathGet } from "./pathGet.d.ts";
-export { pathGetLoose } from "./pathGetLoose.d.ts";
-export { pathSet } from "./pathSet.d.ts";
-export { plainFieldsOf } from "./plainFieldsOf.d.ts";
-export { randomPick } from "./randomPick.d.ts";
-export { randomPicks } from "./randomPicks.d.ts";
+export { deepObjectify, objectify, plainFieldsOf } from "./objectify.d.ts";
+export { pathGet, pathGetLoose, pathSet, toPathSegments } from "./objectPath.d.ts";
+export { formatPhone, isPhoneNumber } from "./phone.d.ts";
+export { randomPick, randomPicks } from "./randomPick.d.ts";
 export { hostFromRequest, isJsonContentType, originFromRequest } from "./requestOrigin.d.ts";
 export { RestClient, type RestClientOptions, type RestRequestOptions } from "./restClient.d.ts";
+export { round } from "./round.d.ts";
 export { assertUniqueRoutePatterns, compareRouteSpecificity, getPageSourceFileViolation, getRouteExports, isRouteSourceFile, isSpecialRouteLeaf, LAYOUT_ROUTE_EXPORTS, matchRoutePattern, normalizeRoutePattern, PAGE_ROUTE_EXPORTS, type ParsedRouteModuleKey, parseRouteModuleKey, RESERVED_ROUTE_CONFIG_EXPORTS, ROOT_LAYOUT_ROUTE_EXPORTS, type RouteModuleKind, routeSegmentToPatternPart, routeSegmentToTreePath, tryParseRouteModuleKey, type ValidatePageSourceFileOptions, type ValidateSubRoutePageKeyOptions, validatePageSourceFile, validateSubRoutePageKey, } from "./routeConvention.d.ts";
 export { sleep } from "./sleep.d.ts";
-export { splitVersion } from "./splitVersion.d.ts";
 export { getBasePathFromPathname, parseBasePaths, parseSubRouteHosts, resolveSubRouteHosts } from "./subRoute.d.ts";
 export { TrustedProxy } from "./TrustedProxy.d.ts";
+export { toError } from "./toError.d.ts";
+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.d.ts";
 export type * from "./types.d.ts";
-export { type WebsocketAuthAckData, type WebsocketAuthRequest, websocketAuthContract, } from "./websocketAuth.d.ts";
-export { type WebsocketBinaryFrame, websocketBinaryFrameContract } from "./websocketBinaryFrame.d.ts";
+export { mergeVersion, splitVersion } from "./version.d.ts";
+export { type WebsocketAuthAckData, type WebsocketAuthRequest, type WebsocketBinaryFrame, type WebsocketHeartbeatAckData, type WebsocketHeartbeatRequest, websocketAuthContract, websocketBinaryFrameContract, websocketHeartbeatContract, } from "./websocketContract.d.ts";

package/types/common/interpolateTranslation.d.ts

@@ -1,7 +1,2 @@
-/**
- * Fills `{name}` placeholders in a translated string.
- *
- * A placeholder whose value is absent is left as written: the author's `{name}` reads as a bug in the UI, while
- * the string "undefined" reads as content, and a partially supplied `data` must not corrupt the rest of the line.
- */
+/** A `{name}` placeholder whose value is absent is left as written, never replaced by "undefined". */
 export declare const interpolateTranslation: (message: string, data: Record<string, unknown> | undefined) => string;

package/types/common/isEmail.d.ts

@@ -1,2 +1 @@
-/** Returns true when the value matches the email format accepted by Akan forms. */
 export declare const isEmail: (email?: string | null) => boolean;

package/types/common/isRecord.d.ts

@@ -0,0 +1 @@
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/types/common/isThenable.d.ts

@@ -1,9 +1 @@
-/**
- * Whether a value is awaitable. Duck-typed rather than `instanceof Promise` so a thenable produced by a
- * different realm or promise implementation still counts — a same-realm check silently misses those.
- *
- * `<Button>` uses this to decide whether a click handler is asynchronous: a handler that returns a
- * thenable gets the pending/success states, a plain one renders as an ordinary button. That makes the
- * distinction impossible to forget, unlike an explicit flag.
- */
 export declare const isThenable: (value: unknown) => value is PromiseLike<unknown>;

package/types/common/logContext.d.ts

@@ -1,5 +1,5 @@
 import type { LogRecord } from "./Logger.d.ts";
-/** A per-request ring the Logger hands every record to; the trace decides at its end whether any of it is shown. */
+/** A per-request ring of every record; the trace decides at its end whether any of it is shown. */
 export interface LogFlightRecorder {
     minSev: number;
     capture(record: LogRecord, written: boolean): void;

package/types/common/markdownBlocks.d.ts

@@ -0,0 +1,32 @@
+import { type TableBlock } from "./markdownTable.d.ts";
+export interface MarkdownItem {
+    depth: number;
+    ordered: boolean;
+    num: number;
+    text: string;
+}
+export type MarkdownBlock = {
+    kind: "code";
+    lang?: string;
+    text: string;
+} | {
+    kind: "heading";
+    level: number;
+    text: string;
+} | {
+    kind: "list";
+    items: MarkdownItem[];
+} | {
+    kind: "quote";
+    text: string;
+} | {
+    kind: "rule";
+} | {
+    kind: "para";
+    text: string;
+} | TableBlock;
+export declare class MarkdownBlocks {
+    #private;
+    static of(source: string): MarkdownBlock[];
+    constructor(source: string);
+}

package/types/common/markdownSpans.d.ts

@@ -0,0 +1,30 @@
+export type MarkdownSpan = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "code";
+    text: string;
+} | {
+    kind: "strong";
+    text: string;
+} | {
+    kind: "em";
+    text: string;
+} | {
+    kind: "del";
+    text: string;
+} | {
+    kind: "link";
+    text: string;
+    href: string;
+}
+/** A link whose href was refused, or an image: rendered as its label, by every host. */
+ | {
+    kind: "plain";
+    text: string;
+};
+export declare class MarkdownSpans {
+    static of(text: string): MarkdownSpan[];
+    static isSafeHref(href: string): boolean;
+    static plain(text: string): string;
+}

package/types/common/markdownTable.d.ts

@@ -0,0 +1,14 @@
+export type Align = "left" | "center" | "right";
+export interface TableBlock {
+    kind: "table";
+    aligns: (Align | null)[];
+    head: string[];
+    rows: string[][];
+}
+export declare class MarkdownTable {
+    #private;
+    static at(lines: string[], at: number): {
+        block: TableBlock;
+        next: number;
+    } | null;
+}

package/types/common/mcpExposure.d.ts

@@ -1,13 +1,3 @@
-/**
- * What MCP says about one endpoint: whether it is published, why it is not, and the hints it carries.
- *
- * Structurally typed like the rest of `common/` so the same rules answer on both sides — the server builds its
- * catalogue from them and the browser API explorer badges an endpoint from them. A second implementation would
- * eventually disagree, and an audit surface that disagrees with the catalogue is worse than none.
- *
- * Every rejection returns the sentence an author reads, at boot in the server log and in the explorer. Fail-closed
- * with no reason leaves an author whose endpoint is missing from the catalogue nowhere to look but the source.
- */
 export interface McpExposureEndpoint {
     type: string;
     returns: {
@@ -27,26 +17,17 @@ export interface McpExposureEndpoint {
     agents?: boolean;
 }
 export interface McpExposureOption {
-    /** The model the endpoint belongs to and the name it is published under: one rule reads the key, not the shape. */
     refName: string;
     key: string;
-    /**
-     * The read-only deployment valve, which is server configuration. The browser explorer cannot know it and so
-     * badges what the code decided; the boot log is where a read-only deployment says what it dropped.
-     */
+    /** The read-only deployment valve: server configuration the browser explorer cannot know. */
     readOnly?: boolean;
 }
-/** `Any` publishes as the empty schema, which tells a model nothing — so it is left out rather than described. */
+/** `Any` publishes as the empty schema, which tells a model nothing, so it is left out. */
 export declare const isMcpDescribableArg: (arg: {
     refName: string;
 }) => boolean;
-/** Which CRUD verb a generated endpoint key is, or `null` when the key is not one of the five. */
 export declare const mcpBaseVerbOf: (refName: string, key: string) => "get" | "create" | "update" | "remove" | null;
-/**
- * The hints a client renders beside a tool. Hints only — clients are told to distrust them, so they inform a UI
- * and never stand in for a guard. `openWorldHint` is always false: every endpoint reaches this app's own
- * database, not the wider internet.
- */
+/** Hints never stand in for a guard; `openWorldHint` is false: every endpoint reaches this app's own database. */
 export declare const mcpHintsOf: (key: string, endpoint: {
     type: string;
 }) => {
@@ -55,5 +36,4 @@ export declare const mcpHintsOf: (key: string, endpoint: {
     idempotentHint: boolean;
     openWorldHint: boolean;
 };
-/** The sentence explaining why this endpoint is not in the catalogue, or `null` when it is. */
 export declare const mcpRefusalOf: (endpoint: McpExposureEndpoint, { refName, key, readOnly }: McpExposureOption) => string | null;

package/types/common/objectPath.d.ts

@@ -0,0 +1,10 @@
+type PathSegment = string | number;
+type Indexable = Record<PathSegment, unknown>;
+export declare const isIndexable: (value: unknown) => value is Indexable;
+/** `a.0.b` and `a[0].b` are the same segments, for writes and reads alike. */
+export declare const toPathSegments: (path: string | readonly PathSegment[]) => any[];
+export declare const pathGet: (path: string | (string | number)[], obj: unknown, separator?: string, fallback?: unknown) => unknown;
+export declare const pathSet: <T>(obj: T, path: string | readonly PathSegment[], value: unknown) => T;
+/** Also tries joined prefixes, for keys whose segments contain the separator (an enum value like `gpt-5.6-terra`). */
+export declare const pathGetLoose: (path: string | readonly string[], obj: unknown, separator?: string, fallback?: unknown) => unknown;
+export {};

package/types/common/objectify.d.ts

@@ -1 +1,8 @@
 export declare const objectify: <T extends object>(obj: T, keys?: (keyof T)[]) => Partial<T>;
+export declare const plainFieldsOf: (source: object) => Record<string, unknown>;
+interface DeepObjectifyOption {
+    serializable?: boolean;
+    convertDate?: "string" | "number";
+}
+export declare const deepObjectify: <T = unknown>(obj: T | null | undefined, option?: DeepObjectifyOption) => T;
+export {};

package/types/common/phone.d.ts

@@ -0,0 +1,2 @@
+export declare const isPhoneNumber: (phone?: string | null) => boolean;
+export declare const formatPhone: (value: string) => string;

package/types/common/randomPick.d.ts

@@ -1 +1,2 @@
 export declare const randomPick: <T = unknown>(arr: T[] | readonly T[]) => T;
+export declare const randomPicks: <T>(arr: T[] | readonly T[], count?: number, allowDuplicate?: boolean) => T[];

package/types/common/requestOrigin.d.ts

@@ -1,20 +1,3 @@
-/**
- * The origin a caller actually saw, and whether a body claims to be JSON. Both read only headers and a URL, so
- * they answer the same way for the cache layer, the CSRF gate, and anything else that has to compare origins.
- */
 export declare const originFromRequest: (headers: Headers, url: URL) => string;
-/**
- * The host a caller addressed, which — unlike the scheme — every proxy that rewrites the request still reports.
- * `Host` is set by the browser from the URL it was told to open, so it names *this* deployment even for a
- * request some other page initiated.
- */
 export declare const hostFromRequest: (headers: Headers, url: URL) => string;
-/**
- * Whether a request body may be read as JSON.
- *
- * `Request.json()` parses whatever bytes it holds regardless of this header, and the three content types a
- * cross-site form can send — `text/plain`, `application/x-www-form-urlencoded`, `multipart/form-data` — are
- * exactly the ones a browser sends with **no preflight**. Requiring the JSON type is therefore what puts a
- * preflight in front of every mutation that carries a body.
- */
 export declare const isJsonContentType: (contentType: string | null) => boolean;

package/types/common/restClient.d.ts

@@ -1,10 +1,3 @@
-/**
- * A plain REST client for a service that is not an Akan API: base url, headers, timeout, JSON in and out.
- *
- * Not `akanjs/fetch`'s `HttpClient`, which builds an Akan endpoint's path from its serialized args and restores
- * an `Err` from the response. Two classes of the same name in one package meant an app importing both barrels
- * got a collision, so this one is named for what it is.
- */
 export interface RestClientOptions {
     baseUrl?: string;
     headers?: HeadersInit;

package/types/common/round.d.ts

@@ -0,0 +1 @@
+export declare const round: (value: number, digits?: number) => number;

package/types/common/routeConvention.d.ts

@@ -27,11 +27,7 @@ export interface ValidatePageSourceFileOptions {
     filePath?: string;
 }
 export declare function isRouteSourceFile(filePath: string): boolean;
-/**
- * Why a `page/` file breaks the route convention, or null when it is fine. Null also covers a non-source
- * asset, which `page/` tolerates. `akan sync <lib>` reports these alongside its other layout violations,
- * so the rule stays in one place instead of being restated where it cannot afford to throw.
- */
+/** `null` when the file is fine, including a non-source asset, which `page/` tolerates. */
 export declare function getPageSourceFileViolation(filePath: string): string | null;
 export declare function validatePageSourceFile(filePath: string, options?: ValidatePageSourceFileOptions): boolean;
 export declare function validateSubRoutePageKey(key: string, basePaths: Iterable<string>, options?: ValidateSubRoutePageKeyOptions): void;
@@ -43,6 +39,7 @@ export declare function routeSegmentToPatternPart(segment: string): string;
 export declare function routeSegmentToTreePath(segment: string): string;
 export declare function compareRouteSpecificity(a: string, b: string): number;
 export declare function matchRoutePattern(pattern: string, pathname: string): Record<string, string> | null;
+export declare function matchRoutePrefix(pattern: string, pathname: string): Record<string, string> | null;
 export declare function assertUniqueRoutePatterns(entries: {
     key: string;
     pattern: string;

package/types/common/sleep.d.ts

@@ -1,2 +1 @@
-/** Resolves after the requested delay in milliseconds. */
 export declare const sleep: (ms: number) => Promise<unknown>;

package/types/common/subRoute.d.ts

@@ -1,15 +1,13 @@
 import type { AkanI18nConfig } from "./localeConfig.d.ts";
 export declare const parseBasePaths: (value: string | string[] | Set<string> | undefined | null) => string[];
 /**
- * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A deployment platform
- * renders this value, so a malformed entry is skipped rather than thrown: one bad character must not CrashLoop
- * every pod that received it.
+ * `"soft=a.com,b.com;office=c.com"` -> `{ soft: ["a.com", "b.com"], office: ["c.com"] }`. A malformed entry is
+ * skipped, not thrown: a deployment platform renders this value, and one bad character must not CrashLoop pods.
  */
 export declare const parseSubRouteHosts: (value: string | undefined | null) => Record<string, string[]>;
 /**
- * Unions the env mapping onto the one baked into the build artifact, never replacing it — dropping the env is the
- * rollback path. A basePath the build does not serve is reported back instead of honoured: the route tree is a
- * build output, so accepting one would answer every request under it with a 404 and nothing to explain why.
+ * Unions the env mapping onto the build's own, never replacing it (dropping the env is the rollback path). A basePath
+ * the build does not serve is reported back, not honoured: the route tree is a build output.
  */
 export declare const resolveSubRouteHosts: ({ subRoutes, basePaths, env, }: {
     subRoutes: Record<string, string[]>;

package/types/common/toError.d.ts

@@ -0,0 +1 @@
+export declare const toError: (reason: unknown) => Error;

package/types/common/tunnelWire.d.ts

@@ -0,0 +1,161 @@
+/** `http` and `tcp` payloads are raw binary frames; a `websocket` one prefixes each with a `tunnelWsPayload` byte. */
+export type TunnelStreamKind = "http" | "websocket" | "tcp";
+export type TunnelResetCode = "originUnreachable" | "originTimeout" | "originRefused" | "protocol" | "canceled" | "tooLarge" | "internal";
+/** Pairs, not a record: `set-cookie` repeats, and a record keyed by name keeps only the last one. */
+export type TunnelHeaderList = [string, string][];
+export interface TunnelAgentIdentity {
+    /** The operator's name for this share. */
+    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 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[];
+    urls: string[];
+    /** Idle data sockets to hold; `maxSockets` is the ceiling the pool never grows past. */
+    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 the agent connection it 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;
+    /** The tunnel host the public caller addressed. */
+    hostname: string;
+    /** `http` and `websocket`. */
+    method?: string;
+    /** `http` and `websocket`: path plus query, already percent-encoded. */
+    path?: string;
+    /**
+     * `http` and `websocket`, replayed verbatim: the gateway strips every `forwardedHeaderNames` entry the caller sent
+     * (else Host header injection) and writes `x-forwarded-host` as the tunnel hostname (else CSRF refuses mutations).
+     */
+    headers?: TunnelHeaderList;
+    /** `tcp`: the port on the local origin to dial. */
+    port?: number;
+    /** Whether payload frames follow; 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` a `tcp` one; any other status is the agent declining. */
+    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; its socket is closed rather than returned to the pool. */
+export interface TunnelResetFrame {
+    type: "reset";
+    streamId: string;
+    code: TunnelResetCode;
+    message?: string;
+}
+/** Gateway → agent once both directions ended: the socket is idle again. Only `http` streams are released. */
+export interface TunnelReleaseFrame {
+    type: "release";
+    streamId: string;
+}
+export type TunnelDataFromAgent = TunnelAttachFrame | TunnelHeadFrame | TunnelEndFrame | TunnelResetFrame;
+export type TunnelDataFromGateway = TunnelAttachedFrame | TunnelOpenFrame | TunnelEndFrame | TunnelResetFrame | TunnelReleaseFrame;
+export type TunnelFrame = TunnelControlFromAgent | TunnelControlFromGateway | TunnelDataFromAgent | TunnelDataFromGateway;
+export declare const tunnelWsPayload: {
+    readonly text: 0;
+    readonly binary: 1;
+    /** Remainder is UTF-8 JSON `{ code, reason }` — the inner close, which is not the tunnel socket closing. */
+    readonly close: 2;
+};
+export type TunnelWsPayloadKind = (typeof tunnelWsPayload)[keyof typeof tunnelWsPayload];
+/** Stripped by both ends independently, so neither has to trust the other to have done it. */
+export declare const tunnelHopByHopHeaders: readonly ["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "proxy-connection", "te", "trailer", "transfer-encoding", "upgrade"];
+/**
+ * The only way a refusal reaches the agent, which treats these as final and any other close as a drop to retry: a
+ * refused upgrade arrives as a bare `1006`. Accept the upgrade and close on a later tick, never inside `open`.
+ */
+export declare const tunnelCloseCode: {
+    readonly unauthorized: 4001;
+    readonly unsupportedVersion: 4002;
+    readonly hostnameNotGranted: 4003;
+    readonly unknownSession: 4004;
+    /** A newer session for the same tunnel took over; this one must not reconnect. */
+    readonly superseded: 4005;
+    readonly streamLimit: 4008;
+    readonly goingAway: 4009;
+};
+export type TunnelCloseCode = (typeof tunnelCloseCode)[keyof typeof tunnelCloseCode];
+/** Includes `forwarded`, RFC 7239's single-header spelling of the same claim. */
+export declare const tunnelForwardedHeaders: readonly ["x-real-ip", "x-forwarded-for", "x-forwarded-port", "x-forwarded-host", "x-forwarded-proto", "forwarded"];
+export declare const tunnelWireContract: {
+    readonly version: 1;
+    readonly controlPath: "/_tunnel/control";
+    readonly dataPath: "/_tunnel/data";
+    readonly authScheme: "Bearer";
+    readonly defaultIdleSockets: 4;
+    readonly defaultMaxSockets: 128;
+    readonly defaultHeartbeatMs: 30000;
+    /** What a sender splits an `http` or `tcp` payload to. */
+    readonly chunkBytes: number;
+    /** Floor of every tunnel socket's `maxPayloadLength`: an inner 16 MB message plus its prefix rides one frame. */
+    readonly maxFrameBytes: number;
+    readonly stripForwarded: (headers: Headers) => Headers;
+    readonly forwardedHeaderNames: readonly ["x-real-ip", "x-forwarded-for", "x-forwarded-port", "x-forwarded-host", "x-forwarded-proto", "forwarded"];
+    readonly isHopByHop: (name: string) => boolean;
+    readonly headerList: (headers: Headers) => TunnelHeaderList;
+    readonly headersOf: (list: TunnelHeaderList) => Headers;
+    readonly encodeWsPayload: (kind: TunnelWsPayloadKind, data: Uint8Array) => Uint8Array;
+    readonly decodeWsPayload: (frame: Uint8Array) => {
+        kind: TunnelWsPayloadKind;
+        data: Uint8Array;
+    } | null;
+    readonly parseFrame: (raw: string) => TunnelFrame | null;
+};

package/types/common/types.d.ts

@@ -5,13 +5,9 @@ export interface FetchPolicy<Returns = unknown> {
     onError?: (error: string) => void;
     token?: string;
     partial?: string[];
-    timeout?: number;
-    /**
-     * A `pubsub` subscription only: called after the room has been resubscribed following a dropped connection.
-     *
-     * Whatever was published while the socket was down is gone, and a room cannot say which messages those were, so
-     * a subscriber that has to stay correct reloads here instead of carrying on from a gap it cannot see.
-     */
+    /** Milliseconds, or `false` to wait as long as the runtime will; overrides the endpoint's declared `timeout`. */
+    timeout?: number | false;
+    /** `pubsub` only: called after a resubscribe, since whatever was published while the socket was down is gone. */
     onResync?: () => void;
 }
 export type SnakeCase<S extends string> = S extends `${infer T}_${infer U}` ? `${Lowercase<T>}_${SnakeCase<U>}` : S;
@@ -19,3 +15,7 @@ export type SnakeCaseObj<T> = {
     [K in keyof T as SnakeCase<K & string>]: T[K] extends object ? SnakeCaseObj<T[K]> : T[K];
 };
 export type SnakeMsg<Msg> = SnakeCaseObj<Msg>;
+/** Name-based dispatch over a generated surface: `as DynamicRecord` to index, then cast the read, never `as any`. */
+export type DynamicRecord<Value = unknown> = {
+    [key: string]: Value;
+};

package/types/common/version.d.ts

@@ -0,0 +1,6 @@
+export declare const mergeVersion: (major: number, minor: number, patch: number) => string;
+export declare const splitVersion: (version: string) => {
+    major: string;
+    minor: string;
+    patch: string;
+};

package/types/common/websocketContract.d.ts

@@ -0,0 +1,41 @@
+export interface WebsocketAuthRequest {
+    key: string;
+    data: [string | null];
+}
+export interface WebsocketAuthAckData {
+    type: "auth";
+    revokedRooms: string[];
+}
+export declare const websocketAuthContract: {
+    readonly key: "__auth";
+    readonly makeRequest: (jwt: string | null) => WebsocketAuthRequest;
+    readonly makeAck: (revokedRooms: string[]) => WebsocketAuthAckData;
+    readonly readJwt: (data: unknown) => string | null;
+};
+export interface WebsocketHeartbeatRequest {
+    key: string;
+    data: [];
+}
+export interface WebsocketHeartbeatAckData {
+    type: "pong";
+}
+export declare const websocketHeartbeatContract: {
+    readonly key: "__ping";
+    /** Under the 60s idle timeout nginx and most CDNs ship with. */
+    readonly intervalMs: 45000;
+    /** Without any inbound frame this long, the socket is assumed half-open and reconnected. */
+    readonly silenceMs: number;
+    readonly makeRequest: () => WebsocketHeartbeatRequest;
+    readonly makeAck: () => WebsocketHeartbeatAckData;
+};
+export declare const websocketRoomContract: {
+    readonly idOf: (key: string, args: unknown[]) => string;
+};
+export interface WebsocketBinaryFrame {
+    roomId: string;
+    payload: Uint8Array;
+}
+export declare const websocketBinaryFrameContract: {
+    readonly encode: ({ roomId, payload }: WebsocketBinaryFrame) => Uint8Array;
+    readonly decode: (data: ArrayBuffer | Uint8Array) => WebsocketBinaryFrame | null;
+};