@briancray/belte 0.3.0 → 0.4.0

package/src/lib/cli/types/CliManifestEntry.ts

@@ -1,12 +1,17 @@
 import type { HttpVerb } from '../../server/rpc/types/HttpVerb.ts'
 
 /*
-Per-RPC manifest entry baked into the standalone CLI binary by the
+Per-command manifest entry baked into the standalone CLI binary by the
 bundler. Carries enough info to make the right HTTP request without
-importing the handler module (which the thin build doesn't ship).
+importing the handler module (which the thin build doesn't ship). Covers
+both rpcs and socket commands — a socket `tail` is a GET against
+`/__belte/sockets/<name>` with `accept: text/event-stream` so the CLI
+streams it live; a socket `publish` is a POST to the same path.
 */
 export type CliManifestEntry = {
     method: HttpVerb
     url: string
     jsonSchema?: Record<string, unknown>
+    // Request Accept header. Socket tail sets text/event-stream to stream live frames.
+    accept?: string
 }

package/src/lib/mcp/annotationsForMethod.ts

@@ -0,0 +1,29 @@
+import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+
+/*
+Maps an HTTP verb to MCP tool annotations so a model can tell a read from
+a write before calling. Belte derives these from the verb the RPC was
+declared with rather than asking the author to repeat the intent:
+  - GET / HEAD  → read-only, non-destructive
+  - POST        → creates; not idempotent, not (necessarily) destructive
+  - PUT         → replaces; idempotent + destructive
+  - PATCH       → modifies; destructive, not idempotent
+  - DELETE      → removes; idempotent + destructive
+The shape matches MCP's ToolAnnotations (readOnlyHint / destructiveHint /
+idempotentHint); fields a verb doesn't imply are left off.
+*/
+export function annotationsForMethod(method: HttpVerb): Record<string, boolean> {
+    switch (method) {
+        case 'GET':
+        case 'HEAD':
+            return { readOnlyHint: true, destructiveHint: false }
+        case 'POST':
+            return { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
+        case 'PUT':
+            return { readOnlyHint: false, destructiveHint: true, idempotentHint: true }
+        case 'PATCH':
+            return { readOnlyHint: false, destructiveHint: true, idempotentHint: false }
+        case 'DELETE':
+            return { readOnlyHint: false, destructiveHint: true, idempotentHint: true }
+    }
+}

package/src/lib/mcp/createMcpServer.ts

@@ -1,3 +1,4 @@
+import { NO_STORE } from '../shared/cacheControlValues.ts'
 import { dispatchMcpRequest, MCP_NO_STORE_HEADERS } from './dispatchMcpRequest.ts'
 import type { McpServer } from './types/McpServer.ts'
 import type { McpServerOptions } from './types/McpServerOptions.ts'
@@ -12,13 +13,14 @@ object whose `handle(request)` is the function the bun route at
 default-constructs it; there is no user-authored server module. Server
 name/version default from package.json.
 
-Tools are derived from every verb with `clients.mcp: true` (auto-on when
-the verb carries a schema) — one tool per rpc regardless of HTTP verb.
-Sockets are not exposed to MCP. Auth inherits from the inbound request —
-bearer / cookie headers
-flow into the synthesized Request that hits each rpc handler. An optional
-`authorize` hook in opts can short-circuit the request before any tool
-dispatches.
+Tools are derived from every verb with `clients.mcp: true` (auto-on for
+read-only verbs that carry a schema; mutating verbs opt in explicitly)
+and from every socket with `clients.mcp: true` (a `<base>-tail` read tool
+plus a `<base>-publish` tool when clientPublish is set). The HTTP verb
+feeds each rpc tool's annotations. Auth inherits from the inbound request
+— bearer / cookie headers flow into the synthesized Request that hits
+each rpc handler. An optional `authorize` hook in opts can short-circuit
+the request before any tool dispatches.
 */
 export function createMcpServer(opts: McpServerOptions = {}): McpServer {
     const serverInfo = {
@@ -30,7 +32,7 @@ export function createMcpServer(opts: McpServerOptions = {}): McpServer {
             if (request.method !== 'POST') {
                 return new Response('Method Not Allowed', {
                     status: 405,
-                    headers: { Allow: 'POST', 'Cache-Control': 'no-store' },
+                    headers: { Allow: 'POST', 'Cache-Control': NO_STORE },
                 })
             }
             const envelope = await dispatchMcpRequest(request, opts, serverInfo)

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