akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/types/server/akanOption.d.ts

@@ -1,15 +1,43 @@
-import type { BaseEnv, PromiseOrObject } from "akanjs/base";
-import type { MiddlewareCls } from "akanjs/signal";
+import type { BackendEnv, PromiseOrObject } from "akanjs/base";
+import type { Adaptor, AdaptorCls, LlmOption } from "akanjs/service";
+import type { AgentRelayPolicy, MiddlewareCls } from "akanjs/signal";
+import type { McpServerOption } from "./akanServer.d.ts";
 import type { WebProxyRegistration } from "./proxy.d.ts";
-/** App/library server option builder for use objects, signal middleware, and web proxies. */
-export declare class AkanOption<Env extends BaseEnv = BaseEnv> {
+export interface AdaptorOverride {
+    role: AdaptorCls;
+    adaptor: AdaptorCls;
+}
+/**
+ * App/library server option builder: use objects, signal middleware, adaptor overrides, web proxies, and the
+ * server settings an app owns — MCP, the agent relay's access policy, and the LLM the relay speaks to.
+ */
+export declare class AkanOption<Env = unknown> {
     #private;
     constructor();
-    use(fnOrObject: ((env: Env) => Record<string, PromiseOrObject<unknown>>) | Record<string, PromiseOrObject<unknown>>): this;
+    use(fnOrObject: ((env: Env & BackendEnv) => Record<string, PromiseOrObject<unknown>>) | Record<string, PromiseOrObject<unknown>>): this;
     applyMiddleware(...middlewares: MiddlewareCls[]): this;
+    /** Rebinds a predefined adaptor role (e.g. `LlmAdaptorRole`) to the app's own implementation. Last writer wins. */
+    applyAdaptor<T extends Adaptor>(role: AdaptorCls<T>, adaptor: AdaptorCls<T>): this;
     applyWebProxy(...proxies: WebProxyRegistration[]): this;
-    getUses(env: Env): Record<string, PromiseOrObject<unknown>>;
+    /**
+     * MCP server settings for the app mounting this option, merged over the `AKAN_MCP_*` environment and under an
+     * option the server is constructed with. The app's own `option.ts` is the last lib the server reads, so it wins
+     * over every library it depends on.
+     */
+    setMcp(mcp?: boolean | McpServerOption): this;
+    /**
+     * Who may spend the LLM key through the `runAgentTurn` relay — the `AgentRelayAccess` policy, which defaults to
+     * allowing everyone because the framework has no account model to gate on. `null` reopens it.
+     */
+    setAgentAccess(policy: AgentRelayPolicy | null): this;
+    /** Settings for whichever adaptor fills `LlmAdaptorRole`, injected into it as the `llmOption` use. */
+    setLlm(llmOrFn: LlmOption | ((env: Env) => LlmOption)): this;
+    getUses(env: Env & BackendEnv): Record<string, PromiseOrObject<unknown>>;
     getMiddlewares(): MiddlewareCls[];
+    getAdaptorOverrides(): AdaptorOverride[];
     getWebProxies(): WebProxyRegistration[];
+    getMcp(): boolean | McpServerOption | undefined;
+    getAgentAccess(): AgentRelayPolicy | null | undefined;
+    getLlm(env: Env & BackendEnv): LlmOption;
 }
-export declare function createDefaultAkanOption(): AkanOption<BaseEnv>;
+export declare function createDefaultAkanOption(): AkanOption<unknown>;

package/types/server/akanServer.d.ts

@@ -3,6 +3,7 @@ import { Logger } from "akanjs/common";
 import type { Adaptor, AdaptorCls, DatabaseConfig, Service, ServiceCls, SolidConfig } from "akanjs/service";
 import type { ServerSignal, ServerSignalCls } from "akanjs/signal";
 import type { AkanLib, AkanLibProps } from "./akanLib.d.ts";
+import { type McpAuthOption } from "./mcp.d.ts";
 export interface AkanServerProps extends AkanLibProps {
     env?: BaseEnv;
     prefix?: string;
@@ -11,6 +12,43 @@ export interface AkanServerProps extends AkanLibProps {
 }
 export interface AkanServerOptions {
     openapi?: boolean;
+    /** `/mcp` is mounted by default; `false` takes it off, and the object form carries the rest of its settings. */
+    mcp?: boolean | McpServerOption;
+}
+export interface McpServerOption {
+    enabled?: boolean;
+    /**
+     * Drops every mutation from the catalogue whatever its guards allow — for a deployment that must not be able to
+     * write, such as a read replica or a demo. Off by default, and reported per endpoint in the boot log, because a
+     * switch that silently unlists a published endpoint cannot tell its author why it vanished.
+     */
+    readOnly?: boolean;
+    /**
+     * Mount path, `/mcp` by default. The published OAuth resource identifier follows it, so changing it changes
+     * the `aud` a token has to carry.
+     */
+    path?: string;
+    /** Reported as `serverInfo.version`. Defaults to `0.0.0`, the same placeholder the OpenAPI document uses. */
+    version?: string;
+    /**
+     * Free-text usage guidance handed to the model alongside the tool list — the one place to say what this app
+     * is for and which tool to reach for first. Defaults to a bare one-liner naming the app.
+     */
+    instructions?: string;
+    /**
+     * Extra origins allowed past the DNS-rebinding check, beyond the server's own host. Needed only for a
+     * browser-hosted MCP client; native ones send no `Origin` at all.
+     */
+    allowedOrigins?: string[];
+    /** Entries per catalogue page. A client that wants the whole list follows `nextCursor` until it stops. */
+    pageSize?: number;
+    /**
+     * The one language the catalogue and its error text are written in, `en` by default. Server-wide on purpose:
+     * the document is built once at boot and cached by clients, and it is read by a model rather than by a person.
+     */
+    language?: string;
+    /** OAuth resource-server identity: which issuers a client may authenticate with, and the scopes to demand. */
+    auth?: McpAuthOption;
 }
 export interface AkanServerConsoleInfo {
     name: string;
@@ -37,12 +75,17 @@ export declare class AkanServer {
     prefix: string;
     websocketPrefix: string;
     openapi: boolean;
+    mcp: boolean;
+    mcpReadOnly: boolean;
+    mcpAuth: McpAuthOption;
+    mcpOption: Omit<McpServerOption, "enabled" | "readOnly" | "auth">;
     serverMode: "federation" | "batch" | "all";
     shutdownTimeoutMs: number;
-    constructor(name?: string, env?: BaseEnv, serverMode?: "federation" | "batch" | "all", ...libsOrOptions: (AkanLib | AkanServerOptions)[]);
+    constructor(name?: string, env?: {}, serverMode?: "federation" | "batch" | "all", ...libsOrOptions: (AkanLib | AkanServerOptions)[]);
     setPrefix(prefix: string): this;
     setWebsocketPrefix(websocketPrefix: string): this;
     setOpenApi(openapi?: boolean): this;
+    setMcp(mcp?: boolean | McpServerOption): this;
     setDatabaseConfig(database: DatabaseConfig): this;
     setSolidConfig(solid: SolidConfig): this;
     setShutdownTimeout(timeoutMs: number): this;

package/types/server/animatedImage.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `Bun.Image.metadata()` reports only `{ width, height, format }` — there is no frame count — and an
+ * animated GIF decodes to its first frame without erroring. So an optimizer that re-encodes whatever
+ * decodes would silently drop the animation. These readers answer the question from the container bytes
+ * instead, so an animated source can be passed through untouched.
+ */
+export declare const isAnimatedImage: (buffer: Buffer, contentType: string) => boolean;

package/types/server/artifact/routeClientCache.d.ts

@@ -35,6 +35,12 @@ export declare class RouteClientCache {
     #private;
     merged: MergedManifest;
     constructor({ buildRoute, onMerge }: RouteClientCacheOptions);
+    /**
+     * Bumped on every mutation of `merged`, including a delta merge that leaves `generation` where it was. It lets a
+     * consumer memoize work derived from the manifest — merging the runtime manifest over it, say — without having to
+     * copy the manifest to find out whether anything changed. In production nothing after `seed` moves it at all.
+     */
+    get revision(): number;
     seed(manifest: RoutesManifest): void;
     ensure(routeId: string, seeds: string[]): Promise<MergedManifest>;
     snapshot(): MergedManifest;

package/types/server/assetEncoding.d.ts

@@ -0,0 +1,7 @@
+export interface EncodedSidecar {
+    bytes: ArrayBuffer;
+    encoding: string;
+}
+export declare const isCompressibleContentType: (contentType: string) => boolean;
+/** Picks the best precompressed sidecar the caller accepts, or null to serve the file as-is. */
+export declare const resolveEncodedSidecar: (req: Request, filePath: string, contentType: string) => Promise<EncodedSidecar | null>;

package/types/server/devtools/types.d.ts

@@ -137,7 +137,7 @@ export interface ConstantData {
 }
 export type { ArgType, SerializedArg, SerializedReturns };
 export interface EndpointNode {
-    type: "query" | "mutation" | "pubsub" | "message";
+    type: "query" | "mutation" | "pubsub" | "message" | "prompt";
     args: SerializedArg[];
     returns: SerializedReturns;
     path?: string;
@@ -204,7 +204,7 @@ export interface RouteRow {
     signal: string;
     key: string;
     source: "declared" | "crud" | "slice";
-    type: "query" | "mutation" | "message" | "pubsub";
+    type: "query" | "mutation" | "message" | "pubsub" | "prompt";
     transport: "http" | "ws";
     method: "GET" | "POST" | null;
     /** Fully prefixed, `:param` placeholders intact — e.g. `/api/user/:userId`. */

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

@@ -1,5 +1,5 @@
 import type { DatabaseMode } from "akanjs";
-import { type AdaptorCls, BlobStorage, type CacheAdaptor, type CompressAdaptor, ConsoleLogger, type DatabaseAdaptor, JsonCompressor, type LoggingAdaptor, type QueueAdaptor, type ScheduleAdaptor, Scheduler, SolidCache, SolidPubSub, SolidQueue, SqliteDatabase, type StorageAdaptor, type WebsocketAdaptor } from "akanjs/service";
+import { type AdaptorCls, BlobStorage, type CacheAdaptor, type CompressAdaptor, ConsoleLogger, type DatabaseAdaptor, DeepseekLlm, JsonCompressor, type LlmAdaptor, type LoggingAdaptor, type QueueAdaptor, type ScheduleAdaptor, Scheduler, SolidCache, SolidPubSub, SolidQueue, SqliteDatabase, type StorageAdaptor, type WebsocketAdaptor } from "akanjs/service";
 export interface PredefinedAdaptor {
     database: AdaptorCls<DatabaseAdaptor>;
     cache: AdaptorCls<CacheAdaptor>;
@@ -9,6 +9,7 @@ export interface PredefinedAdaptor {
     logging: AdaptorCls<LoggingAdaptor>;
     websocket: AdaptorCls<WebsocketAdaptor>;
     compress: AdaptorCls<CompressAdaptor>;
+    llm: AdaptorCls<LlmAdaptor>;
 }
 export declare const predefinedAdaptorRole: {
     database: AdaptorCls<DatabaseAdaptor>;
@@ -19,6 +20,7 @@ export declare const predefinedAdaptorRole: {
     logging: AdaptorCls<LoggingAdaptor>;
     websocket: AdaptorCls<WebsocketAdaptor>;
     compress: AdaptorCls<CompressAdaptor>;
+    llm: AdaptorCls<LlmAdaptor>;
 };
 export declare const predefinedAdaptor: {
     database: typeof SqliteDatabase;
@@ -29,5 +31,6 @@ export declare const predefinedAdaptor: {
     logging: typeof ConsoleLogger;
     websocket: typeof SolidPubSub;
     compress: typeof JsonCompressor;
+    llm: typeof DeepseekLlm;
 };
 export declare const getPredefinedAdaptor: (mode?: DatabaseMode) => PredefinedAdaptor;

package/types/server/index.d.ts

@@ -9,8 +9,6 @@ export * from "./devtools.d.ts";
 export type { ChangeBatch, ChangeKind } from "./hmr/changeBatch.d.ts";
 export * from "./processMetricsCollector.d.ts";
 export * from "./proxy.d.ts";
-export * from "./routeElementComposer.d.ts";
-export * from "./routeTreeBuilder.d.ts";
 export * from "./sitemap.d.ts";
 export type { SsrManifest, SsrManifestEntry } from "./ssrTypes.d.ts";
 export * from "./types.d.ts";

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,54 @@
+import { type BaseEnv } 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: BaseEnv;
+    live: LiveRegistry;
+    middleware: Map<string, MiddlewareCls>;
+    /** The one language error text is resolved in, matching the catalogue the client was handed. */
+    language?: string;
+}
+/** Executes one MCP tool call or resource read through the ordinary signal pipeline. */
+export declare class McpDispatcher {
+    #private;
+    static readonly logger: Logger;
+    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,18 @@
+/**
+ * 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.
+ */
+export declare class McpEventStream {
+    #private;
+    /** 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);
+    response(): Response;
+    write(message: object): void;
+    close(): 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,60 @@
+import type { BaseEnv } 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;
+    env: BaseEnv;
+    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;
+    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;
+    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";

package/types/server/subRouteIndexDocument.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from "react";
+export interface SubRouteIndexOptions {
+    locale: string;
+    basePaths: string[];
+    subRoutes?: Record<string, string[]>;
+}
+export declare const getSubRouteIndexHref: (locale: string, basePath: string) => string;
+export declare function createSubRouteIndexDocument({ locale, basePaths, subRoutes }: SubRouteIndexOptions): ReactNode;

package/types/server/systemPageDocument.d.ts

@@ -32,6 +32,7 @@ export declare const SYSTEM_PAGE_STATUS_COPY: {
         readonly actionLabel: "Back to safety";
     };
 };
+export declare const SYSTEM_PAGE_STYLE = "\n:root { color-scheme: dark; --akan-primary: #ff493b; --akan-secondary: #2b2e33; --akan-accent: #d1a23b; --akan-foreground: #ffffff; --akan-background: #1a1a1a; --akan-base-200: #2a2a2a; --akan-error: #f02020; }\nbody { margin: 0; min-height: 100vh; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif; background: var(--akan-background); color: var(--akan-foreground); }\na { color: inherit; }\n.akan-system-page { min-height: 100vh; display: grid; place-items: center; padding: 32px 18px; box-sizing: border-box; background: radial-gradient(circle at top left, rgba(255, 73, 59, 0.16), transparent 34%), linear-gradient(135deg, var(--akan-background), #111); }\n.akan-system-card { width: min(720px, 100%); border: 1px solid rgba(255, 255, 255, 0.12); border-radius: 32px; background: linear-gradient(145deg, rgba(42, 42, 42, 0.96), rgba(43, 46, 51, 0.78)); box-shadow: 0 24px 80px rgba(0, 0, 0, 0.36); padding: clamp(28px, 6vw, 56px); }\n.akan-system-status { margin: 0 0 18px; font-weight: 800; font-size: clamp(4rem, 18vw, 8rem); line-height: 0.85; letter-spacing: -0.08em; color: var(--akan-primary); }\n.akan-system-eyebrow { margin: 0 0 10px; color: var(--akan-accent); font-size: 0.78rem; font-weight: 800; letter-spacing: 0.18em; text-transform: uppercase; }\n.akan-system-title { margin: 0; max-width: 12ch; font-size: clamp(2rem, 7vw, 4rem); line-height: 0.95; letter-spacing: -0.055em; color: var(--akan-foreground); }\n.akan-system-description { margin: 22px 0 0; max-width: 56ch; color: rgba(255, 255, 255, 0.76); font-size: 1.05rem; line-height: 1.75; }\n.akan-system-path { margin: 22px 0 0; overflow-wrap: anywhere; border: 1px solid rgba(255, 255, 255, 0.1); border-radius: 16px; background: rgba(26, 26, 26, 0.72); padding: 12px 14px; color: rgba(255, 255, 255, 0.72); font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; font-size: 0.88rem; }\n.akan-system-actions { margin-top: 30px; display: flex; flex-wrap: wrap; gap: 12px; }\n.akan-system-action { display: inline-flex; min-height: 44px; align-items: center; justify-content: center; border: 1px solid var(--akan-primary); border-radius: 999px; background: var(--akan-primary); box-shadow: 0 12px 34px rgba(255, 73, 59, 0.26); color: var(--akan-foreground); padding: 0 18px; font-weight: 800; text-decoration: none; }\n.akan-system-secondary { border: 1px solid rgba(255, 255, 255, 0.12); background: var(--akan-secondary); color: var(--akan-foreground); }\n.akan-system-details { margin-top: 28px; max-height: 260px; overflow: auto; border-radius: 18px; background: rgba(26, 26, 26, 0.82); border: 1px solid rgba(240, 32, 32, 0.22); padding: 16px; color: rgba(255, 255, 255, 0.78); font-size: 0.82rem; line-height: 1.55; white-space: pre-wrap; }\n";
 export declare function createSystemPageDocument(options: SystemPageOptions): ReactNode;
 export declare function getSystemPageErrorDetails(error: unknown): string;
 export declare function getSystemPageHomeHref({ pathname, i18n, basePaths, headerBasePath, }: SystemPageHomeHrefOptions): string;

package/types/server/systemPages.d.ts

@@ -1,8 +1,13 @@
+import { type SubRouteIndexOptions } from "./subRouteIndexDocument.d.ts";
 import { type SystemPageKind, type SystemPageOptions } from "./systemPageDocument.d.ts";
 export interface SystemPageResponseOptions extends SystemPageOptions {
     method?: string;
 }
+export interface SubRouteIndexResponseOptions extends SubRouteIndexOptions {
+    method?: string;
+}
 export { createSystemPageDocument, getSystemPageHomeHref } from "./systemPageDocument.d.ts";
 export declare function createSystemPageResponse(options: SystemPageResponseOptions): Promise<Response>;
+export declare function createSubRouteIndexResponse(options: SubRouteIndexResponseOptions): Promise<Response>;
 export declare function createSystemPageHeaders(): Headers;
 export declare function createSystemPageFallbackText(kind: SystemPageKind): string;

package/types/server/vendor/akanjs-fetch.d.ts

@@ -0,0 +1 @@
+export * from "akanjs/fetch";

package/types/service/agent.service.d.ts

@@ -0,0 +1,12 @@
+import type { LlmTurnRequest } from "./predefinedAdaptor/llm.adaptor";
+declare const AgentService_base: import("./serve.d.ts").ServiceCls<"agent", {}, {
+    llm: import("./injectInfo.d.ts").InjectInfo<"plug", import("./predefinedAdaptor.d.ts").LlmAdaptor, never, never>;
+}>;
+export declare class AgentService extends AgentService_base {
+    runTurn(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<{
+        text: string;
+        toolCalls: import("./predefinedAdaptor.d.ts").AgentWireToolCall[];
+        stop: "end" | "toolUse";
+    }>;
+}
+export {};

package/types/service/base.service.d.ts

@@ -1,4 +1,5 @@
 import type { Base } from "akanjs/signal";
+import { AgentService } from "./agent.service";
 import { ServiceModel } from "./serviceModule.d.ts";
 declare const BaseService_base: import("./serve.d.ts").ServiceCls<"base", {}, {
     onCleanup: import("./injectInfo.d.ts").InjectInfo<"env", (() => Promise<void>) | undefined, {
@@ -13,5 +14,8 @@ export declare const srv: {
     base: ServiceModel<typeof BaseService, any, any, {
         baseService: BaseService;
     }>;
+    agent: ServiceModel<typeof AgentService, any, any, {
+        agentService: AgentService;
+    }>;
 };
 export {};

package/types/service/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./adapt.d.ts";
+export * from "./agent.service";
 export * from "./base.service";
 export * from "./injectInfo.d.ts";
 export * from "./injectInfo.d.ts";

package/types/service/predefinedAdaptor/database.adaptor.d.ts

@@ -61,6 +61,12 @@ export interface DocumentStore {
         matchedCount: number;
         modifiedCount: number;
     }>;
+    removeOneByQuery(query: DocumentQuery): Promise<{
+        acknowledged: boolean;
+        matchedCount: number;
+        modifiedCount: number;
+        upsertedId: string | null;
+    }>;
     bulkWrite(operations: {
         updateOne: {
             filter: DocumentQuery;
@@ -91,7 +97,9 @@ export interface DocumentStore {
     exists(query?: DocumentQuery): Promise<string | null>;
     count(query?: DocumentQuery): Promise<number>;
     insight(query?: DocumentQuery): Promise<any>;
-    hydrate(data: DocumentRecord, originalData?: DocumentRecord): any;
+    hydrate(data: DocumentRecord, originalData?: DocumentRecord, options?: {
+        track?: boolean;
+    }): any;
 }
 export interface SqlResultRows<Row = Record<string, unknown>> {
     rows: Row[];
@@ -314,6 +322,12 @@ export declare class SqlDocumentStore {
         matchedCount: number;
         modifiedCount: number;
     }>;
+    removeOneByQuery(query: DocumentQuery): Promise<{
+        acknowledged: boolean;
+        matchedCount: number;
+        modifiedCount: number;
+        upsertedId: any;
+    }>;
     private compiledUpdate;
     bulkWrite(operations: {
         updateOne: {
@@ -372,7 +386,15 @@ export declare class SqlDocumentStore {
     private decodeNestedValue;
     private normalizeWriteValue;
     private fillScalarDefaults;
-    hydrate(data: DocumentRecord, originalData?: DocumentRecord): any;
+    /**
+     * `track` buys `isModified()` and costs a deep clone of the row, so it is decided per call site rather than
+     * paid everywhere. Only the read paths (`find`, and the projected read behind it) opt out — that clone was 42%
+     * of a list query, and a listed document is never the one a save hook runs on. Everything else keeps it, so an
+     * external caller of `hydrate` sees no change.
+     */
+    hydrate(data: DocumentRecord, originalData?: DocumentRecord, { track }?: {
+        track?: boolean;
+    }): any;
     private runHooks;
     private insertStmt;
     private prepareReadStmt;