akanjs 3.0.0-alpha.7 → 3.0.0-alpha.71

package/types/server/di/utils.d.ts

@@ -15,6 +15,22 @@ export declare const normalizeServiceRefName: (refName: string) => string;
 export declare const normalizeSignalRefName: (refName: string) => string;
 export declare const normalizeAdaptorRefName: (refName: string) => string;
 export declare const getModuleDependencyRefNames: (mod: DatabaseModule | ServiceModule) => Set<string>;
+/**
+ * The modules a cascade edge forces this one to be mounted with: a `removeRef` target and a monomorphic
+ * `removeWith` owner both fail `CascadeRunner.seal` when they are absent, so they are boot dependencies the
+ * inject graph cannot see. A polymorphic owner list is exempt — it spans optional modules by design.
+ */
+export declare const getModuleCascadeRefNames: (mod: DatabaseModule | ServiceModule) => Set<string>;
+export interface Registration {
+    key: string;
+    /** What claimed the key, phrased for a boot error: `predefined adaptor "storage"`, `lib "shared"`. */
+    owner: string;
+}
+/**
+ * A key registered twice is silently last-write-wins everywhere downstream — an app that meant to add a second
+ * adaptor gets one, and the other's `onInit` never runs. Refuse the boot instead, naming both claimants.
+ */
+export declare const assertUniqueRegistrations: (kind: string, registrations: Registration[]) => void;
 /**
  * Run every task in parallel and, if any rejects, throw a single
  * `AggregateError` that enumerates every failing label + cause. This replaces

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

@@ -0,0 +1,5 @@
+/**
+ * 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/logging/childOutputReader.d.ts

@@ -0,0 +1,40 @@
+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;
+}
+export interface ChildRecordInput {
+    type: ChildOutputType;
+    text: string;
+    name: string;
+    role: string | null;
+    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

@@ -0,0 +1,18 @@
+import type { LogHub, LogHubEntry } from "./logHub.d.ts";
+import type { RotatingLogWriter } from "./rotatingLogWriter.d.ts";
+export interface HubFileSinkOptions {
+    minSev: number;
+    /** `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 processKey({ record }: LogHubEntry): string;
+    close(): void;
+}

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

@@ -0,0 +1,60 @@
+import type { LogHub, LogHubCoverage, LogHubEntry } from "./logHub.d.ts";
+import { type LogQuery } from "./logQuery.d.ts";
+export type LogControlRequest = {
+    cmd: "subscribe";
+    query?: Record<string, unknown>;
+    replay?: number;
+} | {
+    cmd: "unsubscribe";
+    id: string;
+} | {
+    cmd: "history";
+    query?: Record<string, unknown>;
+} | {
+    cmd: "coverage";
+};
+export type LogControlResponse = {
+    type: "subscribed";
+    id: string;
+    query: LogQuery;
+    coverage: LogHubCoverage;
+} | {
+    type: "unsubscribed";
+    id: string;
+} | {
+    type: "record";
+    id?: string;
+    seq: number;
+    record: LogHubEntry["record"];
+} | {
+    type: "history";
+    entries: LogHubEntry[];
+    coverage: LogHubCoverage;
+} | {
+    type: "coverage";
+    coverage: LogHubCoverage;
+} | {
+    type: "dropped";
+    count: number;
+} | {
+    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";
+    static readonly maxPendingBytes: number;
+    static readonly maxInboxBytes: number;
+    static pathIn(runtimeDir: string): string;
+    readonly path: string;
+    constructor(hub: LogHub, runtimeDir: string);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}

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

@@ -0,0 +1,37 @@
+import { type LogRecord } from "akanjs/common";
+import type { AkanIpcMessage } from "akanjs/service";
+export interface LogForwarderOptions {
+    flushMs?: number;
+    maxRecords?: number;
+    maxBytes?: number;
+    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. */
+    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;
+}

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

@@ -0,0 +1,70 @@
+import { type LogRecord } from "akanjs/common";
+import { type LogQuery } from "./logQuery.d.ts";
+export interface LogHubEntry {
+    /** Assigned here, in arrival order. `record.at` comes from several clocks and is not monotonic across children. */
+    seq: number;
+    record: LogRecord;
+}
+export interface LogHubCoverage {
+    count: number;
+    oldestSeq: number | null;
+    newestSeq: number | null;
+    from: number | null;
+    to: number | null;
+}
+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;
+    static readonly defaultMaxBytes: number;
+    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;
+    ingest(record: LogRecord): LogHubEntry | null;
+    ingestMany(records: LogRecord[]): void;
+    subscribe(query: LogQuery, sink: (entry: LogHubEntry) => void): {
+        id: string;
+        unsubscribe: () => void;
+    };
+    unsubscribe(id: string): 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: {
+            from: number;
+            to: number;
+            missed: number;
+        } | null;
+    };
+    close(): void;
+    static estimateBytes(record: LogRecord): number;
+}

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

@@ -0,0 +1,31 @@
+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. */
+export interface LogQuery {
+    minSev?: number;
+    text?: string;
+    name?: string[];
+    endpoint?: string[];
+    origin?: string[];
+    traceId?: string;
+    child?: number[];
+    role?: string[];
+    stream?: ("stdout" | "stderr")[];
+    since?: number;
+    limit?: number;
+}
+export declare class LogQueryMatcher {
+    #private;
+    readonly query: LogQuery;
+    constructor(query: LogQuery);
+    matches(record: LogRecord): boolean;
+    /** `*` 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.
+     */
+    static parse(input: URLSearchParams | Record<string, unknown>, now?: number): LogQuery;
+}

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

@@ -0,0 +1,35 @@
+import type { LogHub, LogHubEntry } from "./logHub.d.ts";
+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;
+        level: import("../../common.d.ts").LogLevel | null;
+        sev: number;
+        name: string;
+        context: string;
+        message: string;
+        stream: "stdout" | "stderr";
+        pid: number | null;
+        replicaIdx: number | null;
+        role: string | null;
+        origin: string | null;
+        traceId: string | null;
+        endpoint: string | null;
+        attrs?: import("../../common.d.ts").LogAttrs;
+        seq: number;
+    };
+    static line(entry: LogHubEntry): string;
+    close(): void;
+}

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

@@ -0,0 +1,20 @@
+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";
+    static readonly retryMs = 2000;
+    static readonly heartbeatMs = 15000;
+    constructor(hub: () => LogHub | null, token: string);
+    /** Without a token the route is not registered at all, rather than mounted to answer "forbidden". */
+    static fromEnv(hub: () => LogHub | null): LogStreamRoute | null;
+    handle(req: Request): Response;
+}

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

@@ -0,0 +1,42 @@
+import { type LogControlResponse } from "./logControlSocket.d.ts";
+import type { LogHubCoverage, LogHubEntry } from "./logHub.d.ts";
+export interface LogTailHandlers {
+    onRecord: (entry: LogHubEntry) => void;
+    onEvent?: (response: LogControlResponse) => void;
+    onClose?: () => void;
+}
+/** Says the app is not running at all, as opposed to a request that failed once connected. */
+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;
+    static connect(socketPath: string, handlers: LogTailHandlers): Promise<LogTailClient>;
+    static describeCoverage(coverage: LogHubCoverage, now?: number): string;
+    static formatDuration(ms: number): string;
+    private constructor();
+    get closed(): boolean;
+    subscribe(query: Record<string, unknown>, { replay }?: {
+        replay?: number;
+    }): Promise<{
+        type: "subscribed";
+        id: string;
+        query: import("./logQuery.d.ts").LogQuery;
+        coverage: LogHubCoverage;
+    }>;
+    unsubscribe(id: string): Promise<void>;
+    history(query: Record<string, unknown>): Promise<{
+        type: "history";
+        entries: LogHubEntry[];
+        coverage: LogHubCoverage;
+    }>;
+    coverage(): Promise<LogHubCoverage>;
+    close(): void;
+}

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

@@ -0,0 +1,62 @@
+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. */
+    authorizationServers?: string[];
+    /** Scopes every call must carry. 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;
+}
+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 {
+    status: 401 | 403;
+    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;
+    unauthorized(req: Request, failure?: McpAuthFailure): Response;
+    /**
+     * Refuses a bearer token that is already provably unusable, before the signal pipeline sees it.
+     *
+     * 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): Response | null;
+    /**
+     * The public origin, 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.
+     *
+     * `McpRouter` compares an `Origin` header against this too — the same proxy that makes `req.url` wrong for the
+     * metadata document makes it wrong for a same-origin check, and there the cost is a flat 403.
+     *
+     * `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. `AKAN_MCP_RESOURCE` pins the identifier for a
+     * deployment that cannot make the guarantee.
+     */
+    static origin(req: Request): string;
+}
+export {};

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

@@ -0,0 +1,61 @@
+import { type BackendEnv } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import type { InjectRegistry, LiveRegistry } from "akanjs/service";
+import { type McpExposedEndpoint, type McpToolResult, type PromptMessage } 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.
+ */
+export declare class McpPromptError extends Error {
+    readonly code: number;
+    constructor(message: string, code: number);
+}
+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>;
+    /**
+     * A prompt is user-chosen, not model-chosen, so a failure has nowhere to go but the JSON-RPC error — there is
+     * no `isError` result the model could read and recover from. Errors propagate to the router unchanged.
+     *
+     * The messages arrive already normalized: `SignalContext` does that for every `prompt`, so this route and the
+     * plain HTTP one return the same shape.
+     */
+    prompt(exposed: McpExposedEndpoint, args: Record<string, unknown>, req: Request): Promise<PromptMessage[]>;
+    /**
+     * 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[]>;
+}
+export {};

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

@@ -0,0 +1,17 @@
+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.
+ */
+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

@@ -0,0 +1,44 @@
+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/McpRouter.d.ts

@@ -0,0 +1,65 @@
+import { type BackendEnv } from "akanjs/base";
+import { Logger } from "akanjs/common";
+import type { InjectRegistry, LiveRegistry } from "akanjs/service";
+import type { MiddlewareCls } from "../../signal/middleware.d.ts";
+import type { HttpRoutes } from "../types.d.ts";
+import { type McpAuthOption } from "./McpAuth.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;
+    auth?: McpAuthOption;
+}
+/**
+ * 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/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./McpAuth.d.ts";
+export * from "./McpDispatcher.d.ts";
+export * from "./McpEventStream.d.ts";
+export * from "./McpExecutionContext.d.ts";
+export * from "./McpRouter.d.ts";

package/types/server/mcp.d.ts

@@ -0,0 +1 @@
+export * from "./mcp/index.d.ts";