akanjs 3.0.0-beta.9 → 3.0.0

package/types/server/hmr/wsHub.d.ts

@@ -1,7 +1,15 @@
-import type { BuildPhase } from "../artifact.d.ts";
+import type { BuildPhase, HmrTrace } from "../artifact.d.ts";
+export type ChangeKind = "code" | "css" | "config" | "ignore";
+export interface ChangeBatch {
+    files: string[];
+    kinds: Set<Exclude<ChangeKind, "ignore">>;
+    trace?: HmrTrace;
+}
+export type HmrClientKind = "ssr" | "csr";
 export interface HmrWsData {
     kind: "akan-hmr";
     openedAt: number;
+    client?: HmrClientKind;
 }
 export type HmrMessage = {
     type: "hello";
@@ -10,21 +18,37 @@ export type HmrMessage = {
         cssUrl: string;
         cssRelPath: string;
     }>;
+    csrGeneration?: number;
+    ssrGeneration?: number;
+    ssrEpoch?: number;
+    /** The phases failing now, each sent right after: a tab drops an error it holds for any other. */
+    failingPhases?: string[];
 } | {
     type: "reload";
     buildId: number;
 } | {
-    type: "rsc-refresh";
-    buildId: number;
-    generation?: number;
-    changedFiles?: string[];
-    routeIds?: string[];
+    type: "csr-update";
+    generation: number;
+    url?: string;
+    changedIds?: string[];
+    reload?: boolean;
+    reason?: string;
+    trace?: HmrTrace;
 } | {
-    type: "client-refresh";
+    type: "ssr-update";
+    generation: number;
+    url?: string;
+    changedIds?: string[];
+    reload?: boolean;
+    reason?: string;
+    trace?: HmrTrace;
+} | {
+    type: "rsc-refresh";
     buildId: number;
     generation?: number;
     changedFiles?: string[];
     routeIds?: string[];
+    trace?: HmrTrace;
 } | {
     type: "css-update";
     cssAssets?: Record<string, {
@@ -51,12 +75,13 @@ export type HmrMessage = {
     message: string;
 };
 export declare const HMR_WS_TOPIC = "__akan_hmr";
+export declare const HMR_CSR_WS_TOPIC = "__akan_hmr_csr";
 export declare class HmrWsHub {
     #private;
-    get size(): number;
     setPublisher(publish: (topic: string, payload: string) => void): void;
     attach(ws: Bun.ServerWebSocket<HmrWsData>): void;
     detach(ws: Bun.ServerWebSocket<HmrWsData>): void;
     broadcast(msg: HmrMessage): void;
     handleMessage(message: string): void;
 }
+export declare const isSyncNavigationEnabled: () => boolean;

package/types/server/index.d.ts

@@ -6,7 +6,8 @@ export * from "./artifact.d.ts";
 export * from "./console.d.ts";
 export * from "./decorators.d.ts";
 export * from "./devtools.d.ts";
-export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch.d.ts";
+export type { ChangeBatch, ChangeKind } from "./hmr/wsHub.d.ts";
+export * from "./nativeFile.d.ts";
 export * from "./oauth.d.ts";
 export * from "./processMetricsCollector.d.ts";
 export * from "./proxy.d.ts";

package/types/server/lifecycle/orphanGroup.d.ts

@@ -0,0 +1,7 @@
+export declare class OrphanGroup {
+    #private;
+    static exit(code: number, { leads, graceMs }?: {
+        leads?: boolean | undefined;
+        graceMs?: number | undefined;
+    }): void;
+}

package/types/server/lifecycle/portInUse.d.ts

@@ -1,5 +1,2 @@
-/**
- * Detects "address already in use" listen failures across the shapes Bun throws them in
- * (`code: "EADDRINUSE"` on newer versions, message-only on older ones).
- */
+/** Bun reports EADDRINUSE as `code` on newer versions and only in the message on older ones; both count. */
 export declare const isPortInUseError: (error: unknown) => boolean;

package/types/server/lifecycle/runtimeDir.d.ts

@@ -1,5 +1 @@
-/**
- * Where a replica keeps its child sockets and rotating logs. Both the gateway and a solo server resolve it,
- * and they must land on the same directory: switching between the two modes must not move the log file.
- */
 export declare const resolveRuntimeDir: (runtimeDir?: string) => string;

package/types/server/lifecycle/shutdownManager.d.ts

@@ -1,14 +1,5 @@
 import type { Logger } from "akanjs/common";
 export declare class ShutdownManager {
     #private;
-    /**
-     * Registers process-level handlers that drive `onShutdown` on:
-     *   - SIGTERM / SIGINT (graceful stop → exit(0) on success, exit(1) on error)
-     *   - uncaughtException (best-effort stop → exit(1))
-     *   - unhandledRejection (logged at error, process kept alive; see `#isFatalUnhandledRejection`)
-     *
-     * Kept separate from `AkanServer` so the server class doesn't have to know about
-     * Node-level process events, and so tests can opt out by not calling it.
-     */
     static register(logger: Logger, onShutdown: () => Promise<void>): void;
 }

package/types/server/logging/childOutputReader.d.ts

@@ -1,9 +1,7 @@
 import { type LogRecord } from "akanjs/common";
 export type ChildOutputType = "stdout" | "stderr";
 export interface ChildOutputReaderOptions {
-    /** A complete stdout line, newline included. */
     onLine: (line: string) => void;
-    /** A stderr block of newline-terminated lines; one stack trace arrives as one block. */
     onBlock: (lines: string[]) => void;
     blockMaxLines?: number;
     blockIdleMs?: number;
@@ -16,24 +14,14 @@ export interface ChildRecordInput {
     replicaIdx: number | null;
     pid: number | null;
 }
-/**
- * Splits a child process's stdout and stderr into lines. stderr is block-buffered — a runtime writes a stack
- * trace in many small writes and a reader wants it whole — and a block closes on a blank line, at
- * `blockMaxLines`, after `blockIdleMs` of silence, or when the stream ends.
- */
 export declare class ChildOutputReader {
     #private;
     static readonly defaultBlockMaxLines = 64;
     static readonly defaultBlockIdleMs = 50;
     constructor({ onLine, onBlock, blockMaxLines, blockIdleMs }: ChildOutputReaderOptions);
-    /**
-     * Wraps what a child wrote past its Logger — a `console.*` call, a runtime error, a crash — as a record of the
-     * process that read it, so an ndjson stdout stays one JSON line per event even for the line that killed a child.
-     */
     static toRecord({ type, text, name, role, replicaIdx, pid }: ChildRecordInput): LogRecord;
     pipe(stream: ReadableStream<Uint8Array> | null | undefined, type: ChildOutputType): Promise<void>;
     write(type: ChildOutputType, text: string): void;
-    /** Ends the stream's partial line and, for stderr, the block it belongs to. */
     flush(type: ChildOutputType): void;
     flushBlock(): void;
     close(): void;

package/types/server/logging/hubFileSink.d.ts

@@ -5,14 +5,10 @@ export interface HubFileSinkOptions {
     /** `ndjson-only` writes the file as JSON lines too; plain `ndjson` keeps the text file a human reads. */
     json: boolean;
 }
-/**
- * The rotating log file fed from the hub instead of from this process's own Logger. In an ndjson deployment a
- * child writes no text line the owner could relay, so the file is written from the records that reached the
- * hub — every process in one place, keyed the way the text-mode files were.
- */
 export declare class HubFileSink {
     #private;
     constructor(hub: LogHub, writer: RotatingLogWriter, { minSev, json }: HubFileSinkOptions);
+    static attach(writer: RotatingLogWriter, hub: LogHub | null, label: string): () => void;
     static processKey({ record }: LogHubEntry): string;
     close(): void;
 }

package/types/server/logging/logControlSocket.d.ts

@@ -1,3 +1,4 @@
+import { Logger } from "akanjs/common";
 import type { LogHub, LogHubCoverage, LogHubEntry } from "./logHub.d.ts";
 import { type LogQuery } from "./logQuery.d.ts";
 export type LogControlRequest = {
@@ -40,13 +41,6 @@ export type LogControlResponse = {
     type: "error";
     message: string;
 };
-/**
- * A unix domain socket in the runtime directory, `0600`, speaking NDJSON both ways. Filesystem permission is
- * the whole authentication: no TCP port is opened. `akan logs` and the console's `.tail` are its clients.
- *
- * Nothing in here logs per delivered record — a subscriber asking for everything would otherwise receive the
- * line about its own delivery, forever.
- */
 export declare class LogControlSocket {
     #private;
     static readonly fileName = "akan-control.sock";
@@ -55,6 +49,7 @@ export declare class LogControlSocket {
     static pathIn(runtimeDir: string): string;
     readonly path: string;
     constructor(hub: LogHub, runtimeDir: string);
+    static open(hub: LogHub, runtimeDir: string, logger: Logger): Promise<LogControlSocket | null>;
     start(): Promise<void>;
     stop(): Promise<void>;
 }

package/types/server/logging/logForwarder.d.ts

@@ -7,31 +7,19 @@ export interface LogForwarderOptions {
     maxQueue?: number;
     maxMessageChars?: number;
 }
-/**
- * The child side of the log channel: a Logger sink that batches records over IPC to whoever owns the hub.
- * Installed only while the owner has asked for a level (`log.level`), so a process nobody is watching sends
- * nothing; `AKAN_LOG_STREAM=1` keeps it on regardless.
- */
 export declare class LogForwarder {
     #private;
     static readonly defaultFlushMs = 20;
     static readonly defaultMaxRecords = 64;
-    /**
-     * Bun IPC loses a message outright when the sender exits soon after and the payload is large — measured from
-     * 16KB for one long string — and a small message queued behind it dies with it. Batches stay well under that.
-     */
     static readonly defaultMaxBytes: number;
     static readonly defaultMaxQueue = 1000;
     static readonly defaultMaxMessageChars: number;
-    constructor(send: (message: AkanIpcMessage) => void, options?: LogForwarderOptions);
-    /** The severity floor in force, or `null` when nothing is forwarded. */
+    constructor(send: (message: AkanIpcMessage, onSent?: () => void) => void, options?: LogForwarderOptions);
     get minSev(): number | null;
     get active(): boolean;
-    get dropped(): number;
     setMinSev(minSev: number | null): void;
-    /** Enqueues a record this process produced or relays for one below it; dropped when nobody is listening. */
     push(record: LogRecord): void;
     pushMany(records: LogRecord[]): void;
-    flush(): void;
-    close(): void;
+    flush(onSent?: () => void): void;
+    close(): Promise<void>;
 }

package/types/server/logging/logHub.d.ts

@@ -15,15 +15,9 @@ export interface LogHubCoverage {
 export interface LogHubOptions {
     maxRecords?: number;
     maxBytes?: number;
-    /** Identical `(name, level, message)` lines allowed per second before the rest collapse into one count. */
     suppressPerSecond?: number;
     now?: () => number;
 }
-/**
- * The process-wide journal: every record of every process this one fronts, in one sequence, with a bounded
- * ring behind it and live subscribers in front. Owned by the gateway, or by the solo replica when nothing is
- * in front of it.
- */
 export declare class LogHub {
     #private;
     static readonly defaultMaxRecords = 2000;
@@ -31,15 +25,8 @@ export declare class LogHub {
     static readonly defaultSuppressPerSecond = 20;
     static readonly suppressWindowMs = 1000;
     constructor({ maxRecords, maxBytes, suppressPerSecond, now }?: LogHubOptions);
-    static fromEnv(): LogHub;
-    /**
-     * The process's one hub, fed by this process's Logger from the moment it is asked for — at construction of the
-     * entrypoint rather than at listen, so a boot line is neither lost nor, in ndjson mode, written as text. In
-     * ndjson mode it also turns this process's console off and owns the stdout writer, the stream's only author.
-     */
     static attach(): LogHub;
     get closed(): boolean;
-    /** The lowest severity any subscriber wants, or `null` with no subscriber — what a child's forwarder is told. */
     get floor(): number | null;
     get size(): number;
     get seq(): number;
@@ -50,13 +37,12 @@ export declare class LogHub {
         unsubscribe: () => void;
     };
     unsubscribe(id: string): void;
-    onFloorChange(listener: (minSev: number | null) => void): () => void;
+    onFloorChange(listener: (minSev: number | null) => void): void;
     coverage(): LogHubCoverage;
     history(query: LogQuery): {
         entries: LogHubEntry[];
         coverage: LogHubCoverage;
     };
-    /** Everything after `seq`, and the gap when the ring has already evicted part of that range. */
     since(seq: number): {
         entries: LogHubEntry[];
         gap: {

package/types/server/logging/logQuery.d.ts

@@ -1,5 +1,5 @@
 import { type LogRecord } from "akanjs/common";
-/** Fields AND together; a list inside a field is an OR. One shape serves live tail, history and the SSE query string. */
+/** Fields AND together; a list inside a field is an OR. */
 export interface LogQuery {
     minSev?: number;
     text?: string;
@@ -18,14 +18,11 @@ export declare class LogQueryMatcher {
     readonly query: LogQuery;
     constructor(query: LogQuery);
     matches(record: LogRecord): boolean;
-    /** `*` is the only wildcard: `mutation:*`, `*:userList`. Everything else is literal. */
+    /** `*` is the only wildcard (`mutation:*`, `*:userList`); everything else is literal. */
     static compileGlob(pattern: string): RegExp;
     /** A duration such as `5m` / `30s` / `2h` / `1d`, or an absolute epoch-ms number. */
     static parseSince(value: string, now?: number): number | undefined;
     static parseMinSev(value: string | undefined): number | undefined;
-    /**
-     * Reads a query off `URLSearchParams` or a parsed JSON object. Lists accept repeated keys and comma-separated
-     * values; `level=warn` is sugar for `minSev`; `since` accepts a duration.
-     */
+    /** Lists take repeated keys or comma-separated values; `level` is sugar for `minSev`; `since` takes a duration. */
     static parse(input: URLSearchParams | Record<string, unknown>, now?: number): LogQuery;
 }

package/types/server/logging/logStdoutWriter.d.ts

@@ -3,15 +3,9 @@ export interface LogStdoutWriterOptions {
     minSev: number;
     write?: (line: string) => void;
 }
-/**
- * The container's stdout in an ndjson deployment: one JSON record per line for everything the hub sees at or
- * above the stdout level, from this process and every one it fronts. It is the only writer — `Logger.consoleOutput`
- * is off in every server process — so a collector's parser is `json` and nothing else.
- */
 export declare class LogStdoutWriter {
     #private;
     constructor(hub: LogHub, { minSev, write }: LogStdoutWriterOptions);
-    /** `seq` rides along: `at` comes from several clocks, so it is what orders records from different processes. */
     static json(entry: LogHubEntry): {
         at: number;
         elapsedMs: number;

package/types/server/logging/logStreamRoute.d.ts

@@ -1,13 +1,4 @@
 import type { LogHub } from "./logHub.d.ts";
-/**
- * `GET /_akan/app/logs?level=warn&endpoint=mutation:*` — the hub as a `text/event-stream`, for a monitor watching
- * one process from outside the pod. Every event carries the hub `seq` as its `id:`, so a client that reconnects
- * with `Last-Event-ID` gets what it missed while the ring still holds it, and an explicit gap event when it does
- * not — never a silent skip a monitor would read as a quiet interval.
- *
- * The route exists only when `AKAN_LOG_STREAM_TOKEN` is set, and answers only a matching bearer token. It logs
- * nothing itself: a stream that logged its own subscriptions at the level it delivers would feed on itself.
- */
 export declare class LogStreamRoute {
     #private;
     static readonly path = "/_akan/app/logs";

package/types/server/logging/logTailClient.d.ts

@@ -10,11 +10,6 @@ export declare class LogControlUnavailableError extends Error {
     readonly socketPath: string;
     constructor(socketPath: string, cause: unknown);
 }
-/**
- * The client half of `LogControlSocket`: `akan logs` and the console's `.tail` both speak through it. Records
- * stream to `onRecord`; every other line answers the oldest request still waiting, in order, because the
- * socket answers in order.
- */
 export declare class LogTailClient {
     #private;
     static socketPath(runtimeDir: string): string;

package/types/server/mcp/McpAuth.d.ts

@@ -1,25 +1,16 @@
 import type { PromiseOrObject } from "akanjs/base";
 import type { HttpRoutes } from "../types.d.ts";
 export interface McpAuthOption {
-    /**
-     * Where a client may obtain a token, published in the metadata document for it to discover. Naming one also
-     * makes a credential mandatory: an MCP client begins its OAuth flow only on a 401, so a server that let an
-     * anonymous `initialize` succeed would leave it connected to the anonymous shelf and never asking.
-     */
+    /** Naming any makes a credential mandatory: an MCP client starts its OAuth flow only on a 401. */
     authorizationServers?: string[];
-    /** Scopes every call must carry. Declaring any turns `insufficient_scope` enforcement on. */
+    /** Declaring any turns `insufficient_scope` enforcement on. */
     scopes?: string[];
     /** Overrides the resource identifier when the public URL differs from what the request reports. */
     resource?: string;
-    /**
-     * Verifies a bearer token's signature and returns its claims, or `null` for one this server did not mint. The
-     * framework holds no signing key, so the module that issues tokens supplies this through `option.setMcp`; without
-     * it the claims are read unverified and a forged token degrades to an anonymous caller instead of being refused.
-     */
+    /** Claims, or `null` to refuse. Unset: claims are read unverified, so a forged token degrades to anonymous. */
     verify?: (token: string) => PromiseOrObject<Record<string, unknown> | null>;
 }
 export interface McpAuthProps extends McpAuthOption {
-    /** Path the MCP endpoint is mounted at. Its absolute URL is this server's OAuth resource identifier. */
     path: string;
 }
 interface McpAuthFailure {
@@ -27,75 +18,16 @@ interface McpAuthFailure {
     error: "invalid_token" | "insufficient_scope";
     description: string;
 }
-/**
- * The OAuth 2.1 protected-resource half of the MCP authorization spec: the RFC 9728 metadata document, the
- * `WWW-Authenticate` challenge that points at it, and the token checks that can be made without an issuer.
- *
- * The authorization server itself is a separate project. What lives here is what a resource server owes a
- * client regardless of who mints the tokens, so wiring one up later needs no change on this side.
- */
 export declare class McpAuth {
     #private;
     static readonly wellKnownPath = "/.well-known/oauth-protected-resource";
     constructor(props: McpAuthProps);
-    /**
-     * Both spellings of the metadata path. RFC 9728 inserts the resource's path into the well-known URL, and MCP
-     * clients try that form first and the bare one second; serving only one leaves half the clients at a 404.
-     */
     createRoutes(): HttpRoutes;
-    /**
-     * A request that carried no credential at all gets a challenge with no `error` code — RFC 6750 §3.1 reserves
-     * the code for a credential that was presented and found wanting — so a client reads it as "authenticate",
-     * not as "your token is bad".
-     */
     unauthorized(req: Request, failure?: McpAuthFailure): Response;
-    /**
-     * Refuses a bearer token that is already provably unusable, before the signal pipeline sees it.
-     *
-     * With a `verify` hook the token is checked end to end and one that fails is refused outright. Without one the
-     * claims are read **without verifying the signature**, which is sound only because every branch below can deny
-     * and none can grant: a forged token still has to pass the app's own middleware afterwards, so the worst a
-     * crafted payload achieves is refusing itself. What this buys is the failure mode it removes — an expired or
-     * foreign token otherwise degrades to an anonymous caller, and the agent is told a tool does not exist rather
-     * than that it needs to authenticate.
-     */
     reject(req: Request): Promise<Response | null>;
-    /**
-     * The 401 a credential-less request gets once an authorization server is named. A server naming none keeps
-     * anonymous access, which is what a public catalogue wants; the public tools of a server naming one are still
-     * reachable, with the token the challenge sends the client off to obtain.
-     */
     challengeAnonymous(req: Request): Response | null;
-    /**
-     * The origin this server is known by. A configured `resource` settles it — that URL is what an authorization
-     * server issued `aud` for, so nothing a request says can be more authoritative — and only a server with none
-     * falls back to what the request reports. Every place that names the server to a client reads this: the
-     * resource identifier, the `resource_metadata` URL in the challenge, and `McpRouter`'s same-origin check.
-     */
     publicOrigin(req: Request): string;
-    /**
-     * The public origin as the request reports it, not the one the request arrived on. Behind a proxy `req.url`
-     * names the internal host the proxy dialed, and publishing that as the resource identifier is not cosmetic: an
-     * authorization server issues `aud` for the URL the *client* used, so every correctly-issued token would then
-     * fail the audience check.
-     *
-     * `x-forwarded-host` is a request header, so this is exactly as trustworthy as the edge that overwrites it, and
-     * a deployment whose edge merely appends leaves both the same-origin comparison and the audience a token is
-     * checked against to the caller. A browser cannot reach it — a custom header is not on a preflight, and the
-     * `OPTIONS` is judged on the real host — but a direct caller can. That is why `publicOrigin` prefers a
-     * configured `resource` (`AKAN_MCP_RESOURCE`, or what `libs/shared` derives from its issuer) and reads this only
-     * for a server that pinned nothing.
-     */
     static origin(req: Request): string;
-    /**
-     * Who a rate limit counts. A bearer token is one caller however many connections it opens: its session id,
-     * failing that its token id or subject, failing that the token itself hashed — an opaque token has nothing else.
-     * With no token the caller is the address a proxy recorded, and callers with no recorded address share one
-     * bucket, which is the right shape for a server that nothing fronts and that admits anonymous calls.
-     *
-     * Read unverified on purpose: this runs after `reject`, so a token that reaches it has already passed whatever
-     * verification the server has, and a key needs no more than that.
-     */
     static callerKey(req: Request): string;
 }
 export {};

package/types/server/mcp/McpDispatcher.d.ts

@@ -3,45 +3,22 @@ import { Logger } from "akanjs/common";
 import type { InjectRegistry, LiveRegistry } from "akanjs/service";
 import { type McpExposedEndpoint, type McpToolResult } from "../../signal/mcp.d.ts";
 import type { MiddlewareCls } from "../../signal/middleware.d.ts";
-/** Raised when the caller presented no credential at all, so the client should be told to authenticate. */
 export declare class McpAuthRequiredError extends Error {
 }
-/**
- * A prompt failure whose message has already been through `#message` and is safe to put on the wire.
- *
- * It carries its JSON-RPC code because a prompt has no `isError` result to put a refusal in, so the code is the
- * only place left to say whose fault it was. Without it a mistyped argument reads as `-32603 internal error`,
- * while the *missing*-argument check `prompts/get` does itself answers `-32602` — the same mistake, two codes.
- */
 interface McpDispatcherProps {
     registry: InjectRegistry;
     env: BackendEnv;
     live: LiveRegistry;
     middleware: Map<string, MiddlewareCls>;
-    /** The one language error text is resolved in, matching the catalogue the client was handed. */
     language?: string;
-    /**
-     * Whether a structured result also ships as serialized JSON in the text block. `true` by default, which is what
-     * the spec asks for; `false` halves what every model-returning tool costs.
-     */
     legacyTextBlock?: boolean;
 }
-/** Executes one MCP tool call or resource read through the ordinary signal pipeline. */
 export declare class McpDispatcher {
     #private;
     static readonly logger: Logger;
-    /** What the text block says when the serialized duplicate is off. Read by a model, so English. */
     static readonly structuredNote = "The result is in this call's structuredContent.";
     constructor(props: McpDispatcherProps);
     call(exposed: McpExposedEndpoint, args: Record<string, unknown>, req: Request): Promise<McpToolResult>;
-    /**
-     * Drops catalogue entries whose account-scoped guards refuse this caller — an anonymous agent should not be
-     * offered a shelf of admin tools it can only fail at. Entries with no such guard are kept and stopped at call
-     * time instead, so the listing is a UX filter and never the access decision.
-     *
-     * The context is deliberately not `init()`-ed: parsing arguments that a listing does not have would throw,
-     * and a resource guard reached here reads `undefined` and fails closed, which is the behaviour we want.
-     */
     filterForAccount<T extends {
         name: string;
     }>(items: T[], req: Request): Promise<T[]>;

package/types/server/mcp/McpEventStream.d.ts

@@ -1,16 +1,5 @@
-import { EventStream } from "../routing/eventStream.d.ts";
-/**
- * One `text/event-stream` response carrying the notifications a single request produced, ending with that
- * request's own result.
- *
- * This is the only channel a server has for pushing anything: `2026-07-28` removed the GET stream, session
- * resumption and server-initiated requests, so nothing may be sent that is not related to a request in flight.
- * Closing the stream is also how the client cancels — `notifications/cancelled` is stdio-only — which is why
- * `cancel` is a constructor argument rather than something a caller could forget to wire. No event carries an
- * `id:`, since there is nothing a reconnecting client could resume.
- */
+import { EventStream } from "akanjs/common";
 export declare class McpEventStream extends EventStream {
-    /** Below any common proxy idle timeout, so a slow tool does not have its connection reaped mid-work. */
     static readonly keepAliveMs = 15000;
     constructor(onCancel: () => void);
     write(message: object): void;

package/types/server/mcp/McpExecutionContext.d.ts

@@ -1,44 +1,11 @@
 import type { EndpointInfo } from "../../signal/endpointInfo.d.ts";
 import { HttpExecutionContext } from "../../signal/signalContext.d.ts";
-/**
- * An argument the caller can fix, carrying a 400 so the dispatcher reports it as a tool error rather than as a
- * server failure. Everything that rejects an argument — the nullable check, `ID._parse`, a scalar's own
- * validator — throws a bare `Error`, and a bare `Error` is indistinguishable from a crash.
- */
 export declare class McpArgumentError extends Error {
     readonly statusCode = 400;
 }
-/**
- * Runs an endpoint for an MCP call while staying an HTTP context.
- *
- * MCP arrives over HTTP and the whole authorization stack reads the request through this context —
- * `AccountMiddleware` resolves the bearer token off `getHttpContext().req`, and `Self`/`Me` and every guard read
- * what it left there. A transport of its own would not adapt that stack, it would bypass it.
- */
 export declare class McpExecutionContext extends HttpExecutionContext {
     #private;
     constructor(req: Request, args: Record<string, unknown>);
-    /**
-     * MCP passes one flat named object, so `param`/`search`/`body` all resolve by name from the same place. An
-     * absent value becomes `null` to match what a missing query string yields, letting `deserialize` apply the
-     * same nullability rules an HTTP call gets.
-     *
-     * A name nobody declared is the caller's mistake and is reported as one. `additionalProperties: false` travels
-     * in the published schema, but this server does not validate against it and plenty of clients do not either —
-     * so reading only the declared names dropped the rest in silence: `{ category, status }` on a slice that takes
-     * only `category` came back as a successful, unfiltered list, which a model reads as the filter having applied.
-     *
-     * "Declared" means what the *published schema* declares, which is why an `Any` argument counts as absent here.
-     * It is deliberately left out of that schema — the empty schema tells a model nothing — and the root list's raw
-     * `query` descriptor is the one that matters: read as sent, an agent could hand any model exposed through
-     * `mcp: { list: true }` an arbitrary query, which is precisely the narrowing a named filter slice exists to make
-     * deliberate. `additionalProperties: false` was never going to stop that on its own.
-     */
     getArgs(endpointInfo: EndpointInfo): Promise<unknown[]>;
-    /**
-     * Returns the serialized value rather than a `Response`, so the router can put it straight into a JSON-RPC
-     * result. The `Response` in the signature is the base class's; `WebSocketExecutionContext` widens it the same
-     * way, and `SignalContext` only ever hands this value back to its caller.
-     */
     makeResponse(result: unknown, endpointInfo: EndpointInfo): Response;
 }

package/types/server/mcp/McpRateLimiter.d.ts

@@ -1,8 +1,14 @@
+import { type Dayjs } from "akanjs/base";
+export interface McpSharedCounter {
+    incr(topic: string, key: string, by?: number, option?: {
+        expireAt?: Dayjs;
+    }): Promise<number>;
+}
 export interface McpRateLimitOption {
-    /** Calls one caller may make per window. `0` turns the counter off. */
+    /** Per caller per window; `0` turns the counter off. */
     calls?: number;
     windowMs?: number;
-    /** Calls one caller may have running at the same time. `0` turns the cap off. */
+    /** Per caller at once; `0` turns the cap off. */
     concurrent?: number;
 }
 export type McpRateLimitVerdict = {
@@ -13,15 +19,6 @@ export type McpRateLimitVerdict = {
     reason: "calls" | "concurrent";
     retryAfterMs: number;
 };
-/**
- * Per-caller budget for the MCP methods that execute an endpoint.
- *
- * Two limits because they stop two different loops. A fixed window of `calls` stops a model that re-reads a list
- * slice as fast as the client lets it; a cap on `concurrent` calls stops one that fans out a ten-second query in
- * parallel, which the window alone would admit until the window filled. Counted in this process only — a
- * deployment with N replicas grants N budgets — and keyed by the caller the router derives, so a reset is a
- * restart and nothing else.
- */
 export declare class McpRateLimiter {
     #private;
     static readonly defaults: {
@@ -32,7 +29,7 @@ export declare class McpRateLimiter {
     readonly calls: number;
     readonly windowMs: number;
     readonly concurrent: number;
-    constructor({ calls, windowMs, concurrent, }?: McpRateLimitOption);
-    acquire(key: string, now?: number): McpRateLimitVerdict;
+    constructor({ calls, windowMs, concurrent, }?: McpRateLimitOption, shared?: McpSharedCounter | null);
+    acquire(key: string, now?: number): Promise<McpRateLimitVerdict>;
     describe(): string;
 }