akanjs 3.0.0-beta.9 → 3.0.1

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;
 }

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

@@ -1,6 +1,6 @@
 import { type BackendEnv } from "akanjs/base";
 import { Logger } from "akanjs/common";
-import type { InjectRegistry, LiveRegistry } from "akanjs/service";
+import { type InjectRegistry, type LiveRegistry } from "akanjs/service";
 import { type McpOutputSchemaMode } from "../../signal/mcp.d.ts";
 import type { PagePromptSource } from "../../signal/mcp/pagePrompt.d.ts";
 import type { MiddlewareCls } from "../../signal/middleware.d.ts";
@@ -9,74 +9,28 @@ import { type McpAuthOption } from "./McpAuth.d.ts";
 import { type McpRateLimitOption } from "./McpRateLimiter.d.ts";
 export interface McpRouterProps {
     registry: InjectRegistry;
-    /** Spread into every `SignalContext` this router's dispatcher builds; middleware reads it. */
     env: BackendEnv;
     live: LiveRegistry;
     middleware: Map<string, MiddlewareCls>;
     path?: string;
     version?: string;
-    /** Free-text usage guidance handed to the model alongside the tool list. */
     instructions?: string;
-    /** Extra origins allowed past the DNS-rebinding check, beyond the server's own host. */
     allowedOrigins?: string[];
     readOnly?: boolean;
-    /** Entries per catalogue page. A client that wants the whole list follows `nextCursor` until it stops. */
     pageSize?: number;
-    /**
-     * The one language every title, description and domain error text is resolved in. The catalogue is built once
-     * at boot and cached by clients, so it is a server-wide choice rather than a per-request one: `Accept-Language`
-     * would mean a document per language, re-deriving every tool schema, for a surface a model reads and a human
-     * rarely sees. Defaults to `en`, falling back to the first registered language when the app has no `en`.
-     */
     language?: string;
-    /** Whether a structured result also ships as serialized JSON in the text block. Default `true`. */
     legacyTextBlock?: boolean;
-    /**
-     * Where `prompts/list` and `prompts/get` are answered from: the pages, through the RSC worker. Absent on an
-     * API-only build, which then publishes no prompts at all.
-     */
     pagePrompts?: PagePromptSource;
-    /** Characters of screen data one prompt may attach before its lists are cut; see `PagePromptComposer`. */
     promptBudget?: number;
     outputSchema?: McpOutputSchemaMode;
     auth?: McpAuthOption;
-    /**
-     * Budget per caller for the methods that execute an endpoint (`tools/call`, `resources/read`, `prompts/get`).
-     * On by default at `McpRateLimiter.defaults`; `false` takes it off. Listings are not counted — they are served
-     * from memory and a client polls them.
-     */
     rateLimit?: McpRateLimitOption | false;
 }
-/**
- * Serves the app's signals as one MCP endpoint.
- *
- * Answers both protocol eras from the same stateless handler. `2026-07-28` is stateless by design; the legacy
- * revisions only *offer* sessions — a server may decline to issue `Mcp-Session-Id`, and a client that never
- * receives one neither sends one back nor asks to resume a stream. So the legacy era costs an `initialize` reply
- * and a laxer `_meta` check, not a session store. (Measured against Claude Code 2.1.226, which speaks it.)
- */
 export declare class McpRouter {
     #private;
     static readonly logger: Logger;
-    /** Past this a listing is a meaningful slice of a model's window, which is where it becomes worth saying so. */
     static readonly listingWarnBytes: number;
     constructor(props: McpRouterProps);
     createRoutes(): HttpRoutes;
-    /**
-     * Says once, at boot, what this build actually published — and names every endpoint that was kept out.
-     *
-     * The rejections are fail-closed by design: an endpoint MCP cannot carry, or whose guards do not admit it, is
-     * simply not in the catalogue. That is the right default and the wrong silence, and it matters more now that
-     * exposure follows the guards — nobody wrote an opt-in whose absence would explain a missing tool, so this log
-     * is the only place the answer exists. A refusal turns on a resolved return type and a resolved guard list, so
-     * it reads only from here.
-     *
-     * An entry published with no description rides here for the same reason: the text every generated entry borrows
-     * is a *model* `.desc()`, which no source rule would read as that entry's description. This holds the resolved
-     * catalogue, so it can simply look.
-     *
-     * Called by whatever mounts the router rather than from `createRoutes`, so building a router to answer one
-     * request — which tests and tooling do — does not narrate a catalogue nobody asked about.
-     */
     report(): void;
 }

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

@@ -4,28 +4,16 @@ import { type PromptMessage } from "../../signal/mcp/Msg.d.ts";
 import type { PagePromptEntry, PagePromptRun } from "../../signal/mcp/pagePrompt.d.ts";
 interface PagePromptComposerProps {
     document: McpDocument;
-    /** Characters of attached data one prompt may carry; the largest list is cut first and the cut is said. */
+    /** Characters of attached data one prompt may carry. */
     budget: number;
     /** The tool names this caller may see, so the tools line offers nothing the listing would not. */
     visibleTools: (names: string[]) => Promise<string[]>;
 }
-/**
- * Turns what a page fetched into the messages `prompts/get` answers.
- *
- * The instruction is the page's own description and nothing more: the screen's data rides as embedded resources
- * masked by the model each endpoint declares, and the tools named at the end are the published ones of the same
- * modules — a model that reads a ticket board is told the ticket tools, not all three hundred.
- */
 export declare class PagePromptComposer {
     #private;
     static readonly logger: Logger;
     static readonly defaultBudget = 60000;
     constructor(props: PagePromptComposerProps);
-    /**
-     * A required argument nobody filled in gets one message pointing at the tool that finds the id, not a guess.
-     * A prompt cannot re-run itself, so pre-filled context would never be used; the model finds the id with the
-     * search tool and proceeds with the tools from there.
-     */
     missing(entry: PagePromptEntry, names: string[]): PromptMessage[];
     compose(entry: PagePromptEntry, run: Extract<PagePromptRun, {
         ok: true;