@briancray/belte 0.3.1 → 0.4.0

package/src/lib/mcp/dispatchMcpRequest.ts

@@ -3,13 +3,17 @@ import { findVerbByCommandName } from '../server/rpc/findVerbByCommandName.ts'
 import type { VerbRegistryEntry } from '../server/rpc/types/VerbRegistryEntry.ts'
 import { verbRegistry } from '../server/rpc/verbRegistry.ts'
 import { ensureRegistriesLoaded } from '../server/runtime/registryManifests.ts'
+import { recentHistory } from '../server/sockets/recentHistory.ts'
+import { socketOperations } from '../server/sockets/socketOperations.ts'
+import { socketRegistry } from '../server/sockets/socketRegistry.ts'
 import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
 import { NO_STORE } from '../shared/cacheControlValues.ts'
 import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
-import { decodeResponse } from '../shared/decodeResponse.ts'
 import { forwardHeaders } from '../shared/forwardHeaders.ts'
 import { jsonSchemaForSchema } from '../shared/jsonSchemaForSchema.ts'
+import { annotationsForMethod } from './annotationsForMethod.ts'
 import { getMcpResourceServer } from './mcpResourceServerSlot.ts'
+import { toolResultFromResponse } from './toolResultFromResponse.ts'
 import type { JsonRpcRequest } from './types/JsonRpcRequest.ts'
 import type { JsonRpcResponse } from './types/JsonRpcResponse.ts'
 import type { McpServerOptions } from './types/McpServerOptions.ts'
@@ -33,6 +37,8 @@ type ToolDescriptor = {
     name: string
     description: string
     inputSchema: Record<string, unknown>
+    outputSchema?: Record<string, unknown>
+    annotations?: Record<string, boolean>
 }
 
 type PromptDescriptor = {
@@ -42,10 +48,18 @@ type PromptDescriptor = {
 }
 
 /*
-Builds the array of MCP tool descriptors. Every rpc with clients.mcp=true
-becomes one tool named after the export's URL (folder segments joined
-with `-`), regardless of HTTP verb — GET reads and mutating verbs alike.
-Sockets are never exposed to MCP.
+Builds the array of MCP tool descriptors.
+
+RPCs: every verb with clients.mcp=true becomes one tool named after the
+export's URL (folder segments joined with `-`). The HTTP verb feeds the
+tool's annotations (readOnlyHint / destructiveHint / idempotentHint) so
+a model can tell a read from a write; reads auto-expose while mutating
+verbs require an explicit clients.mcp (see resolveClientFlags). When the
+verb declares an `outputSchema` it's advertised as the tool outputSchema.
+
+Sockets: every socket with clients.mcp=true contributes a `<base>-tail`
+read tool (recent buffered messages) and, when clientPublish is set, a
+`<base>-publish` tool.
 */
 function buildTools(): ToolDescriptor[] {
     const tools: ToolDescriptor[] = []
@@ -59,14 +73,51 @@ function buildTools(): ToolDescriptor[] {
         falling back to `method url` so the tool is still labelled when
         the schema has none.
         */
-        const inputSchema = jsonSchemaForSchema(entry.schema, entry.jsonSchema)
-        tools.push({
+        const inputSchema = jsonSchemaForSchema(entry.inputSchema, entry.inputJsonSchema)
+        const tool: ToolDescriptor = {
             name: commandNameForUrl(entry.remote.url),
             description:
                 (inputSchema.description as string | undefined) ??
                 `${entry.remote.method} ${entry.remote.url}`,
             inputSchema,
-        })
+            annotations: annotationsForMethod(entry.remote.method),
+        }
+        if (entry.outputSchema) {
+            tool.outputSchema = jsonSchemaForSchema(entry.outputSchema, entry.outputJsonSchema)
+        }
+        tools.push(tool)
+    }
+    for (const entry of socketRegistry.values()) {
+        if (!entry.clients.mcp) {
+            continue
+        }
+        const payloadSchema = jsonSchemaForSchema(entry.schema, entry.jsonSchema)
+        for (const operation of socketOperations(entry)) {
+            if (operation.kind === 'tail') {
+                tools.push({
+                    name: operation.name,
+                    description: `Read recent messages from the "${operation.socketName}" socket`,
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            count: { type: 'number', description: 'max recent messages to return' },
+                        },
+                    },
+                    outputSchema: {
+                        type: 'object',
+                        properties: { frames: { type: 'array', items: payloadSchema } },
+                    },
+                    annotations: { readOnlyHint: true, destructiveHint: false },
+                })
+                continue
+            }
+            tools.push({
+                name: operation.name,
+                description: `Publish a message to the "${operation.socketName}" socket`,
+                inputSchema: payloadSchema,
+                annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+            })
+        }
     }
     return tools
 }
@@ -95,10 +146,12 @@ function buildPrompts(): PromptDescriptor[] {
 }
 
 /*
-Tool dispatch. Synthesizes a Request (with forwarded auth headers) and
-pipes it through verb.fetch — the same code path the HTTP router uses, so
-validation + handler + error helpers behave identically. Every rpc is a
-tool regardless of verb.
+Tool dispatch. RPC tools synthesize a Request (with forwarded auth
+headers) and pipe it through verb.fetch — the same code path the HTTP
+router uses, so validation + handler + error helpers behave identically;
+the response (buffered or streaming) is framed by toolResultFromResponse.
+Socket tools (`<base>-tail` / `<base>-publish`) fall through to the
+socket dispatcher.
 */
 async function callTool(
     toolName: string,
@@ -106,30 +159,59 @@ async function callTool(
     inbound: Request,
 ): Promise<Record<string, unknown>> {
     const entry = findVerbByCommandName(toolName)
-    if (!entry?.clients.mcp) {
-        throw new Error(`unknown tool: ${toolName}`)
+    if (entry?.clients.mcp) {
+        const response = await dispatchVerb(entry, args, inbound)
+        return toolResultFromResponse(response)
     }
-    const response = await dispatchVerb(entry, args, inbound)
-    if (!response.ok) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `${response.status} ${response.statusText}: ${await response.text()}`,
-                },
-            ],
-            isError: true,
-        }
+    const socketResult = callSocketTool(toolName, args)
+    if (socketResult) {
+        return socketResult
     }
-    const body = await decodeResponse(response)
-    return {
-        content: [
-            {
-                type: 'text',
-                text: typeof body === 'string' ? body : JSON.stringify(body),
-            },
-        ],
+    throw new Error(`unknown tool: ${toolName}`)
+}
+
+function textResult(text: string, isError = false): Record<string, unknown> {
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) }
+}
+
+/*
+Dispatches the socket tail / publish tools by matching the tool name
+against each mcp-exposed socket's operations (socketOperations is the same
+projection tools/list advertised, so the publish op only exists when the
+socket allows it). tail returns the recent history buffer (request/response
+can't hold a live subscription); publish validates against the socket
+schema and fans out. Returns undefined when the name isn't a known socket
+tool so callTool can fall through to "unknown tool".
+*/
+function callSocketTool(
+    toolName: string,
+    args: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+    for (const entry of socketRegistry.values()) {
+        if (!entry.clients.mcp) {
+            continue
+        }
+        const operation = socketOperations(entry).find((op) => op.name === toolName)
+        if (!operation) {
+            continue
+        }
+        if (operation.kind === 'tail') {
+            const count = typeof args?.count === 'number' ? args.count : undefined
+            const frames = recentHistory(entry, count)
+            return {
+                content: [{ type: 'text', text: frames.map((f) => JSON.stringify(f)).join('\n') }],
+                structuredContent: { frames },
+            }
+        }
+        try {
+            // publish() validates the payload against the socket schema and throws on failure.
+            entry.socket.publish(args)
+        } catch (error) {
+            return textResult(error instanceof Error ? error.message : String(error), true)
+        }
+        return textResult('ok')
     }
+    return undefined
 }
 
 /*

package/src/lib/mcp/toolResultFromResponse.ts

@@ -0,0 +1,66 @@
+import { decodeResponse } from '../shared/decodeResponse.ts'
+import { isStreamingResponse } from '../shared/isStreamingResponse.ts'
+import { responseErrorText } from '../shared/responseErrorText.ts'
+import { streamResponse } from '../shared/streamResponse.ts'
+
+// Frames a value as MCP text content — strings verbatim, everything else as JSON.
+function asText(value: unknown): string {
+    return typeof value === 'string' ? value : JSON.stringify(value)
+}
+
+/*
+Turns an rpc/socket Response into an MCP `tools/call` result. Always
+carries a `text` content block for backward compatibility; adds
+`structuredContent` (an object, per the MCP spec) so models that
+understand structured output get the typed value instead of a stringified
+blob.
+
+  - non-2xx        → { content:[text], isError:true }
+  - sse/jsonl body → drained frame-by-frame; structuredContent = { frames }.
+                     A mid-stream error surfaces as isError with the
+                     frames collected so far.
+  - object body    → structuredContent = the object.
+  - array/primitive → text only (structuredContent must be an object).
+*/
+export async function toolResultFromResponse(response: Response): Promise<Record<string, unknown>> {
+    if (!response.ok) {
+        return {
+            content: [{ type: 'text', text: await responseErrorText(response) }],
+            isError: true,
+        }
+    }
+
+    if (isStreamingResponse(response)) {
+        const frames: unknown[] = []
+        try {
+            for await (const frame of streamResponse(response)) {
+                frames.push(frame)
+            }
+        } catch (error) {
+            return {
+                content: [
+                    { type: 'text', text: frames.map(asText).join('\n') },
+                    {
+                        type: 'text',
+                        text: `stream error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                structuredContent: { frames },
+                isError: true,
+            }
+        }
+        return {
+            content: [{ type: 'text', text: frames.map(asText).join('\n') }],
+            structuredContent: { frames },
+        }
+    }
+
+    const body = await decodeResponse(response)
+    const result: Record<string, unknown> = {
+        content: [{ type: 'text', text: asText(body) }],
+    }
+    if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+        result.structuredContent = body
+    }
+    return result
+}

package/src/lib/server/jsonl.ts

@@ -22,6 +22,7 @@ error is logged server-side via the framework's error handler — only the
 message crosses the wire.
 */
 import { NO_STORE } from '../shared/cacheControlValues.ts'
+import { jsonlErrorFrame } from '../shared/jsonlErrorFrame.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
 import { streamFromIterator } from './runtime/streamFromIterator.ts'
 import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
@@ -32,7 +33,7 @@ export function jsonl<Frame>(
 ): TypedResponse<Frame> {
     const body = streamFromIterator(iterable, {
         encodeFrame: (value) => `${JSON.stringify(value)}\n`,
-        encodeError: (message) => `${JSON.stringify({ $error: message })}\n`,
+        encodeError: (message) => jsonlErrorFrame.encode(message),
     })
     return new Response(
         body,

package/src/lib/server/rpc/defineVerb.ts

@@ -1,9 +1,10 @@
 import { buildRpcRequest } from '../../shared/buildRpcRequest.ts'
-import { NO_STORE } from '../../shared/cacheControlValues.ts'
 import { createRemoteFunction } from '../../shared/createRemoteFunction.ts'
 import { forwardHeaders } from '../../shared/forwardHeaders.ts'
+import { isReadOnlyMethod } from '../../shared/isReadOnlyMethod.ts'
 import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
 import type { ClientFlags } from '../../shared/types/ClientFlags.ts'
+import { json } from '../json.ts'
 import { requestContext } from '../runtime/requestContext.ts'
 import { parseArgs } from './parseArgs.ts'
 import { registerVerb } from './registerVerb.ts'
@@ -33,14 +34,30 @@ export function defineVerb<Args, Return>(
     url: string,
     handler: RemoteHandler<Args, Return>,
     opts?: {
-        schema?: StandardSchemaV1
-        jsonSchema?: Record<string, unknown>
+        inputSchema?: StandardSchemaV1
+        inputJsonSchema?: Record<string, unknown>
+        outputSchema?: StandardSchemaV1
+        outputJsonSchema?: Record<string, unknown>
         clients?: Partial<ClientFlags>
     },
 ): RemoteFunction<Args, Return> {
-    const schema = opts?.schema
-    const jsonSchema = opts?.jsonSchema
-    const clients = resolveClientFlags(opts?.clients, schema !== undefined)
+    const inputSchema = opts?.inputSchema
+    const inputJsonSchema = opts?.inputJsonSchema
+    const outputSchema = opts?.outputSchema
+    const outputJsonSchema = opts?.outputJsonSchema
+    /*
+    An input schema makes the handler safe to advertise to non-browser
+    surfaces. CLI flips on for any verb with one (a human/script invokes it
+    deliberately). MCP only auto-exposes read-only verbs (GET/HEAD) — a
+    model shouldn't be able to mutate/delete just because the handler
+    carries a schema, so mutating verbs require an explicit clients.mcp.
+    Explicit `clients` always wins.
+    */
+    const hasSchema = inputSchema !== undefined
+    const clients = resolveClientFlags(opts?.clients, {
+        mcp: hasSchema && isReadOnlyMethod(method),
+        cli: hasSchema,
+    })
 
     function buildRequest(args: Args | undefined): Request {
         const store = requestContext.getStore()
@@ -62,15 +79,9 @@ export function defineVerb<Args, Return>(
     }
 
     async function validateThenHandle(args: Args | undefined): Promise<Response> {
-        const result = await schema!['~standard'].validate(args)
+        const result = await inputSchema!['~standard'].validate(args)
         if (result.issues) {
-            return new Response(JSON.stringify({ issues: result.issues }), {
-                status: 422,
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Cache-Control': NO_STORE,
-                },
-            })
+            return json({ issues: result.issues }, { status: 422 })
         }
         return runHandler(result.value as Args)
     }
@@ -83,7 +94,7 @@ export function defineVerb<Args, Return>(
     SSR call.
     */
     function invoke(args: Args | undefined): Promise<Response> {
-        return schema ? validateThenHandle(args) : runHandler(args)
+        return inputSchema ? validateThenHandle(args) : runHandler(args)
     }
 
     const remote = createRemoteFunction<Args, Return>({
@@ -96,8 +107,10 @@ export function defineVerb<Args, Return>(
     })
     registerVerb({
         remote: remote as RemoteFunction<unknown, unknown>,
-        schema,
-        jsonSchema,
+        inputSchema,
+        inputJsonSchema,
+        outputSchema,
+        outputJsonSchema,
         clients,
     })
     return remote

package/src/lib/server/rpc/parseArgs.ts

@@ -1,3 +1,4 @@
+import { carriesBodyArgs } from '../../shared/carriesBodyArgs.ts'
 import type { HttpVerb } from './types/HttpVerb.ts'
 
 /*
@@ -24,7 +25,7 @@ export async function parseArgs(method: HttpVerb, request: Request): Promise<unk
     const url = hasQuery ? new URL(request.url) : undefined
 
     let body: unknown
-    if (method !== 'GET' && method !== 'DELETE' && method !== 'HEAD') {
+    if (carriesBodyArgs(method)) {
         const contentType = (request.headers.get('content-type') ?? '').toLowerCase()
         if (contentType.includes('application/json')) {
             const text = await request.text()

package/src/lib/server/rpc/types/VerbHelper.ts

@@ -6,11 +6,15 @@ import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
 /*
 Shared signature for every verb helper (GET / POST / …). Three overloads:
 
-  - `Verb(fn, { schema, clients? })` — `Args` infers from
-    `InferInput<Schema>`, the handler receives `InferOutput<Schema>`.
-    Generic order is `<Return, Schema>` so users can override `Return`
-    while letting `Schema` infer from `opts.schema`. `clients` controls
-    which surfaces (browser / mcp / cli) expose this verb.
+  - `Verb(fn, { inputSchema, outputSchema?, clients? })` — `Args` infers
+    from `InferInput<InputSchema>`, the handler receives
+    `InferOutput<InputSchema>`. Generic order is `<Return, InputSchema>` so
+    users can override `Return` while letting `InputSchema` infer from
+    `opts.inputSchema`. `outputSchema` is an optional Standard Schema for
+    the success body — it feeds the OpenAPI 200 response and the MCP tool
+    `outputSchema`. `inputJsonSchema` / `outputJsonSchema` are optional
+    precomputed JSON Schema overrides. `clients` controls which surfaces
+    (browser / mcp / cli) expose this verb.
   - `Verb(fn, { clients })` — schemaless but with explicit client
     targeting (e.g. server-internal RPC with `clients: { browser: false }`).
   - `Verb(fn)` — bare handler. `Args` and `Return` come from the handler
@@ -18,18 +22,22 @@ Shared signature for every verb helper (GET / POST / …). Three overloads:
     `json`/`error`/`redirect`/`jsonl`/`sse`.
 */
 export type VerbHelper = {
-    <Return = unknown, Schema extends StandardSchemaV1 = StandardSchemaV1>(
-        fn: RemoteHandler<StandardSchemaV1.InferOutput<Schema>, Return>,
+    <Return = unknown, InputSchema extends StandardSchemaV1 = StandardSchemaV1>(
+        fn: RemoteHandler<StandardSchemaV1.InferOutput<InputSchema>, Return>,
         opts: {
-            schema: Schema
-            jsonSchema?: Record<string, unknown>
+            inputSchema: InputSchema
+            inputJsonSchema?: Record<string, unknown>
+            outputSchema?: StandardSchemaV1
+            outputJsonSchema?: Record<string, unknown>
             clients?: Partial<ClientFlags>
         },
-    ): RemoteFunction<StandardSchemaV1.InferInput<Schema>, Return>
+    ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, Return>
     <Args = undefined, Return = unknown>(
         fn: RemoteHandler<Args, Return>,
         opts: {
-            jsonSchema?: Record<string, unknown>
+            inputJsonSchema?: Record<string, unknown>
+            outputSchema?: StandardSchemaV1
+            outputJsonSchema?: Record<string, unknown>
             clients: Partial<ClientFlags>
         },
     ): RemoteFunction<Args, Return>

package/src/lib/server/rpc/types/VerbRegistryEntry.ts

@@ -4,14 +4,22 @@ import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
 
 /*
 Per-verb registry record on the server side. MCP and CLI enumerate this
-to discover which RPCs are advertised (clients flags) and what input
-shape they expect (schema). The schema and resolved clients stay off the
-public RemoteFunction shape so the browser-side proxy doesn't need to
-carry server-only state.
+to discover which RPCs are advertised (clients flags) and what shapes
+they expect/return. The schemas and resolved clients stay off the public
+RemoteFunction shape so the browser-side proxy doesn't need to carry
+server-only state.
+
+`inputSchema` validates the argument bag and feeds the MCP tool
+`inputSchema` / OpenAPI parameters; `outputSchema` describes the success
+body and feeds the OpenAPI 200 response + MCP tool `outputSchema`. The
+`*JsonSchema` siblings are optional user-supplied JSON Schema overrides
+(used verbatim when present, otherwise derived from the Standard Schema).
 */
 export type VerbRegistryEntry = {
     remote: RemoteFunction<unknown, unknown>
-    schema: StandardSchemaV1 | undefined
-    jsonSchema: Record<string, unknown> | undefined
+    inputSchema: StandardSchemaV1 | undefined
+    inputJsonSchema: Record<string, unknown> | undefined
+    outputSchema: StandardSchemaV1 | undefined
+    outputJsonSchema: Record<string, unknown> | undefined
     clients: ClientFlags
 }

package/src/lib/server/runtime/buildOpenApiSpec.ts

@@ -1,10 +1,8 @@
+import { carriesBodyArgs } from '../../shared/carriesBodyArgs.ts'
 import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
 import { jsonSchemaForSchema } from '../../shared/jsonSchemaForSchema.ts'
-import type { HttpVerb } from '../rpc/types/HttpVerb.ts'
 import { verbRegistry } from '../rpc/verbRegistry.ts'
 
-const BODY_METHODS = new Set<HttpVerb>(['POST', 'PUT', 'PATCH'])
-
 /*
 Turns a verb's resolved JSON Schema into OpenAPI query parameters — one
 per top-level property, marked required when the schema lists it. Used
@@ -40,14 +38,27 @@ export function buildOpenApiSpec(info: {
     for (const entry of verbRegistry.values()) {
         const url = entry.remote.url
         const method = entry.remote.method
-        const jsonSchema = jsonSchemaForSchema(entry.schema, entry.jsonSchema)
+        const jsonSchema = jsonSchemaForSchema(entry.inputSchema, entry.inputJsonSchema)
         const description = jsonSchema.description as string | undefined
+        /*
+        When the verb declares an `outputSchema`, describe the 200 body
+        with it so external tooling sees the real return shape; otherwise
+        fall back to a bare OK.
+        */
+        const okResponse: Record<string, unknown> = { description: 'OK' }
+        if (entry.outputSchema) {
+            okResponse.content = {
+                'application/json': {
+                    schema: jsonSchemaForSchema(entry.outputSchema, entry.outputJsonSchema),
+                },
+            }
+        }
         const operation: Record<string, unknown> = {
             operationId: commandNameForUrl(url),
             ...(description ? { description } : {}),
-            responses: { '200': { description: 'OK' } },
+            responses: { '200': okResponse },
         }
-        if (BODY_METHODS.has(method)) {
+        if (carriesBodyArgs(method)) {
             operation.requestBody = {
                 content: { 'application/json': { schema: jsonSchema } },
             }

package/src/lib/server/runtime/createPublicAssetServer.ts

@@ -2,6 +2,7 @@ import { PUBLIC_ASSET_CACHE_CONTROL } from '../../shared/cacheControlValues.ts'
 import { acceptsZstd } from './acceptsZstd.ts'
 import { containsTraversal } from './containsTraversal.ts'
 import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
+import { globToPathSet } from './globToPathSet.ts'
 import type { Assets } from './types/Assets.ts'
 
 /*
@@ -11,21 +12,32 @@ sources, picked at construction:
   - `publicAssets` (standalone compile): a map of root path → zstd bytes
     embedded into the binary, mirroring the `_app` asset embed.
   - `publicDir` on disk (dev + `belte start`): files read straight from
-    `${cwd}/src/browser/public`.
+    `${cwd}/src/browser/public`, with the set of paths snapshotted once at
+    boot (see below).
 
 Returns a server fn that resolves to `undefined` when no public file
 matches the request path, so the caller falls through to its own 404 /
 middleware path. The path-traversal guard mirrors serveStaticAsset's
 defence against encoded `..` segments in the raw URL.
+
+Async because disk mode globs `publicDir` once at construction to build a
+Set of the available paths: every page nav and RPC falls through here, so
+a Set lookup beats a filesystem stat per miss. A file added to public/
+after boot needs a server restart to be seen — the same restart a code
+change already triggers under `bun --watch`.
 */
-export function createPublicAssetServer({
+export async function createPublicAssetServer({
     publicDir,
     publicAssets,
 }: {
     publicDir: string
     publicAssets?: Assets
-}): (req: Request, url: URL) => Promise<Response | undefined> {
+}): Promise<(req: Request, url: URL) => Promise<Response | undefined>> {
     const headersFor = createAssetHeaderCache(() => PUBLIC_ASSET_CACHE_CONTROL)
+    // `dot: true` keeps dotfiles (e.g. `.well-known/…`) servable, matching a raw disk stat.
+    const diskPaths = publicAssets
+        ? new Set<string>()
+        : await globToPathSet(publicDir, '**/*', (file) => `/${file}`, { dot: true })
 
     return async function servePublicAsset(req, url) {
         if (containsTraversal(req.url)) {
@@ -43,10 +55,9 @@ export function createPublicAssetServer({
             }
             return new Response(await Bun.zstdDecompress(compressed), { headers: base })
         }
-        const file = Bun.file(publicDir + url.pathname)
-        if (!(await file.exists())) {
+        if (!diskPaths.has(url.pathname)) {
             return undefined
         }
-        return new Response(file, { headers: base })
+        return new Response(Bun.file(publicDir + url.pathname), { headers: base })
     }
 }

package/src/lib/server/runtime/createServer.ts

@@ -1,5 +1,4 @@
 import type { BunRequest, Server } from 'bun'
-import { Glob } from 'bun'
 import type { Component } from 'svelte'
 import { render } from 'svelte/server'
 import App from '../../../App.svelte'
@@ -29,6 +28,8 @@ import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
 import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
+import { globToPathSet } from './globToPathSet.ts'
+import { logBrowserOnlyRoutes } from './logBrowserOnlyRoutes.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
 import { requestContext } from './requestContext.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
@@ -58,6 +59,7 @@ function internalErrorResponse(err: unknown): Response {
 
 const IDENTITY_PATH = '/__belte/identity'
 const SOCKETS_PATH = '/__belte/sockets'
+const SOCKETS_REST_PREFIX = '/__belte/sockets/'
 const MCP_PATH = '/__belte/mcp'
 const CLI_PATH = '/__belte/cli'
 const CLI_DOWNLOAD_PREFIX = '/__belte/cli/'
@@ -125,16 +127,23 @@ export async function createServer({
     setMcpResourceServer(createMcpResourceServer({ resourcesDir, mcpResources }))
     const cliName = cliProgramName ?? 'app'
     const cliCwd = process.cwd()
-    const servePublicAsset = createPublicAssetServer({ publicDir, publicAssets })
+    const servePublicAsset = await createPublicAssetServer({ publicDir, publicAssets })
     const layoutPrefixes = layouts ? normalizeLayoutPrefixes(Object.keys(layouts)) : []
 
-    const diskZstdPaths = new Set<string>(
-        !assets && (await Bun.file(`${distDir}/_app`).exists())
-            ? (await Array.fromAsync(new Glob('**/*.zst').scan({ cwd: `${distDir}/_app` }))).map(
-                  (file) => `/_app/${file.replace(/\.zst$/, '')}`,
-              )
-            : [],
-    )
+    /*
+    Snapshot the precompressed `.zst` siblings the build wrote next to each
+    `_app` asset, keyed by the asset's request path, so a zstd-capable
+    client gets the precompressed bytes without on-the-fly compression. Only
+    in disk mode (`belte start` / dev); the compiled binary serves from the
+    embedded `assets` map instead.
+    */
+    const diskZstdPaths = assets
+        ? new Set<string>()
+        : await globToPathSet(
+              `${distDir}/_app`,
+              '**/*.zst',
+              (file) => `/_app/${file.replace(/\.zst$/, '')}`,
+          )
 
     const rpcModuleCache = new Map<string, Promise<AnyRemoteFunction | undefined>>()
     function loadRpc(url: string): Promise<AnyRemoteFunction | undefined> | undefined {
@@ -440,6 +449,17 @@ export async function createServer({
                 }
                 return new Response('Upgrade failed', { status: 400 })
             }
+            /*
+            HTTP face of a socket (`/__belte/sockets/<name>`) — tail over
+            SSE / JSON and publish — for the CLI and MCP. Runs through
+            dispatchRequest so app.handle auth applies, like the rpc paths.
+            The socket name may contain `/` (nested files), so it's the
+            whole remaining pathname, percent-decoded.
+            */
+            if (url.pathname.startsWith(SOCKETS_REST_PREFIX)) {
+                const name = decodeURIComponent(url.pathname.slice(SOCKETS_REST_PREFIX.length))
+                return dispatchRequest(req, {}, async () => socketDispatcher.rest(req, name))
+            }
             if (url.pathname === MCP_PATH && mcp) {
                 return dispatchRequest(req, {}, async () => mcp.handle(req))
             }
@@ -543,5 +563,13 @@ export async function createServer({
     }
 
     log.success(`ready at http://localhost:${server.port}`)
+    /*
+    Diagnostic only, and only under `belte` debug logging — eager-loads the
+    registry to report routes that are browser-only for lack of a schema,
+    making the opt-in nature of the MCP/CLI surfaces visible.
+    */
+    if (logRequests) {
+        void logBrowserOnlyRoutes()
+    }
     return server
 }