@nanobpm/urban 0.84.0 → 0.85.0

package/dist/runtime/core/modules/api.d.ts

@@ -13,6 +13,10 @@ export interface ApiBinding {
      *  for free — the UI reads the SAME OpenAPI document the runtime routes + validates from. */
     docs?: boolean | string;
 }
+/** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
+ *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
+ *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
+export declare const API_BASE = "/app/api";
 /**
  * Derive the ABSOLUTE spec + operations-server URLs the Swagger UI page should use, from the docs
  * page's own address (`pageHref`), the mount-root-relative docs path (`docsBase`, e.g.
@@ -97,6 +101,7 @@ export declare class NotImplemented extends Error {
 export declare function defineOperation<Req extends OperationContract = DefaultContract, Res = unknown>(_id: string, handler: OperationHandler<Req, Res>): OperationHandler<Req, Res>;
 /** Resolve an operation delegate from a loaded module: `default` (when a function) else `handler`. */
 export declare function resolveOperationHandler(mod: Record<string, unknown>): OperationHandler | undefined;
+export declare function readApiBinding(manifest: unknown): ApiBinding | undefined;
 /** The Swagger UI route for an app's `api` binding, or `undefined` when there is no api surface
  *  or docs are disabled. Lets other surfaces (e.g. the pages shell's "API docs" badge) link to
  *  the docs without re-deriving the path. */

package/dist/runtime/core/modules/api.js

@@ -19,7 +19,7 @@ import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWi
 /** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
  *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
  *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
-const API_BASE = "/app/api";
+export const API_BASE = "/app/api";
 /** Pinned Swagger UI dist served from a CDN, so the docs UI adds zero bundle/runtime deps to an
  *  Urban app (matching the deps-free spirit of the rest of the surface — validators are standalone,
  *  ADR 0058 Consequences). Pinned (not `latest`) for reproducibility. */
@@ -147,7 +147,7 @@ export function resolveOperationHandler(mod) {
         return mod.handler;
     return undefined;
 }
-function readApiBinding(manifest) {
+export function readApiBinding(manifest) {
     const raw = manifest && typeof manifest === "object" ? Reflect.get(manifest, "api") : undefined;
     if (!raw || typeof raw !== "object")
         return undefined;

package/dist/runtime/core/modules/mcp.d.ts

@@ -0,0 +1,57 @@
+import type { AppApi, RuntimeContext } from "../context.ts";
+import type { HttpRequest } from "../host.ts";
+import { type Route } from "../router.ts";
+export interface McpHandle {
+    readonly name: string;
+    routes: Route[];
+    /** Whether the surface actually answers vs. 404s (config-enabled). The route is always mounted
+     *  for a stable address, so callers deriving an "active surfaces" list must gate on this. */
+    readonly enabled: boolean;
+    describe(): Record<string, unknown>;
+}
+/** Mint a fresh MCP session id, host-agnostically. Prefers the Web Crypto `randomUUID` (a global,
+ *  not `node:crypto`) where present, with a time+random fallback so a host without `crypto` never
+ *  throws — mirroring how core treats Web Crypto as optional (see `mintRootRequestKey`). */
+export declare function newSessionId(): string;
+/** Bound the live-session map to `max` by evicting least-recently-used entries (the `Map`'s leading
+ *  keys, given `touchSession` re-inserts on use), closing each victim best-effort so its transport /
+ *  server releases. This is the categorical fix for the unbounded-growth vector: no client can pin
+ *  more than `max` server/transport pairs, whatever its `initialize` cadence. Exported for a direct
+ *  unit test of the LRU eviction contract. */
+export declare function evictExcessSessions<S>(sessions: Map<string, S>, max: number, close: (session: S) => Promise<void>): Promise<void>;
+/** The resolved MCP access policy for this app. */
+interface McpConfig {
+    /** Whether the MCP surface answers at all. Defaults ON. */
+    readonly enabled: boolean;
+    /** Whether non-loopback callers are allowed. Defaults OFF (loopback-only). */
+    readonly allowRemote: boolean;
+}
+/**
+ * Resolve the MCP access policy from the manifest (`mcp: { enabled?, allowRemote? }`, read
+ * reflectively until the app schema folds the field in — mirroring how `readApiBinding` reads
+ * `api`) and the environment (`URBAN_MCP_ENABLED`, `URBAN_MCP_ALLOW_REMOTE`). The env flags win so
+ * an operator can force the surface off (or open it to a non-loopback bind) without editing the
+ * manifest. Enabled defaults ON and access defaults to loopback-only ("defaults ON for loopback").
+ */
+export declare function readMcpConfig(manifest: unknown, env: (name: string) => string | undefined): McpConfig;
+/** Whether the request targets a loopback host — the best-effort loopback signal available at the
+ *  host seam (which carries no peer address). A missing Host header is treated as loopback (a direct
+ *  local client that sent none). */
+export declare function isLoopbackRequest(req: HttpRequest): boolean;
+/** The `required` keys a tool's `inputSchema` declares but the call omitted. Presence is decided
+ *  solely by {@link isBlankArg} — the single source of truth also used for path args — so a value is
+ *  "provided" unless it is absent (`undefined`/`null`) or a blank/whitespace-only string. A required
+ *  non-string input (e.g. a numeric/boolean/object arg) that is present is therefore accepted, not
+ *  wrongly reported missing. Derived from the schema's own `required` array so declaring a field
+ *  required is enough to have missing (or whitespace-only) calls rejected rather than silently
+ *  substituted with an empty string. */
+export declare function missingRequiredArgs(inputSchema: Record<string, unknown>, args: Record<string, unknown>): string[];
+/**
+ * Mount the runtime-served MCP surface at `/app/mcp` (ADR 0067). Returns a single `*`-method route
+ * (mounted unconditionally, like `/app/agent`); the handler bridges the host request/response seam
+ * to the SDK's Web-Standard Streamable-HTTP transport, maintaining one MCP session per
+ * `mcp-session-id`. The tool projection reuses the SAME OpenAPI enumeration and dispatch path as
+ * `mountApi`, so a tool call is equivalent to the corresponding HTTP call.
+ */
+export declare function mountMcp(ctx: RuntimeContext, app: AppApi, apiRoutes: Route[]): McpHandle;
+export {};