@briancray/belte 0.1.0 → 0.2.0

package/src/lib/mcp/dispatchMcpRequest.ts

@@ -1,5 +1,6 @@
 import { promptRegistry } from '../server/prompts/promptRegistry.ts'
-import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+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 { buildRpcRequest } from '../shared/buildRpcRequest.ts'
@@ -28,47 +29,57 @@ function jsonRpcOk(id: string | number | null, result: unknown): JsonRpcResponse
     return { jsonrpc: '2.0', id, result }
 }
 
+type ToolDescriptor = {
+    name: string
+    description: string
+    inputSchema: Record<string, unknown>
+}
+
+type PromptDescriptor = {
+    name: string
+    description?: string
+    arguments: Array<{ name: string; description?: string; required: boolean }>
+}
+
 /*
 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.
 */
-function buildTools(): Array<{
-    name: string
-    description: string
-    inputSchema: Record<string, unknown>
-}> {
-    const tools: Array<{
-        name: string
-        description: string
-        inputSchema: Record<string, unknown>
-    }> = []
+function buildTools(): ToolDescriptor[] {
+    const tools: ToolDescriptor[] = []
     for (const entry of verbRegistry.values()) {
         if (!entry.clients.mcp) {
             continue
         }
+        /*
+        Tool description favours the schema's top-level description (the
+        vendor's JSON Schema conversion carries `.describe(...)` through),
+        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({
             name: commandNameForUrl(entry.remote.url),
-            description: `${entry.remote.method} ${entry.remote.url}`,
-            inputSchema: jsonSchemaForSchema(entry.schema, entry.jsonSchema),
+            description:
+                (inputSchema.description as string | undefined) ??
+                `${entry.remote.method} ${entry.remote.url}`,
+            inputSchema,
         })
     }
     return tools
 }
 
 /*
-MCP prompts derived from src/mcp/prompts. Arguments come from the
-prompt's schema (top-level properties + required flags); the model fills
-them in and the framework validates + renders on prompts/get.
+MCP prompts derived from src/mcp/prompts. Arguments come from the JSON
+Schema the resolver built from each prompt's frontmatter `arguments` list
+(top-level properties + required flags); the model fills them in and the
+framework interpolates them into the body on prompts/get.
 */
-function buildPrompts(): Array<{
-    name: string
-    description?: string
-    arguments: Array<{ name: string; description?: string; required: boolean }>
-}> {
+function buildPrompts(): PromptDescriptor[] {
     return Array.from(promptRegistry.values()).map((entry) => {
-        const jsonSchema = jsonSchemaForSchema(entry.schema, entry.jsonSchema)
+        const jsonSchema = entry.jsonSchema ?? {}
         const properties = (jsonSchema.properties ?? {}) as Record<string, { description?: string }>
         const required = new Set((jsonSchema.required as string[] | undefined) ?? [])
         return {
@@ -94,20 +105,11 @@ async function callTool(
     args: Record<string, unknown> | undefined,
     inbound: Request,
 ): Promise<Record<string, unknown>> {
-    let found: ReturnType<(typeof verbRegistry)['get']> | undefined
-    for (const entry of verbRegistry.values()) {
-        if (!entry.clients.mcp) {
-            continue
-        }
-        if (commandNameForUrl(entry.remote.url) === toolName) {
-            found = entry
-            break
-        }
-    }
-    if (!found) {
+    const entry = findVerbByCommandName(toolName)
+    if (!entry?.clients.mcp) {
         throw new Error(`unknown tool: ${toolName}`)
     }
-    const response = await runRpc(found.remote.method, found.remote.url, args, inbound)
+    const response = await dispatchVerb(entry, args, inbound)
     if (!response.ok) {
         return {
             content: [
@@ -119,7 +121,7 @@ async function callTool(
             isError: true,
         }
     }
-    const body = await decodeResponse(response.clone())
+    const body = await decodeResponse(response)
     return {
         content: [
             {
@@ -131,66 +133,44 @@ async function callTool(
 }
 
 /*
-Synthesizes the rpc Request and dispatches through verb.fetch, forwarding
-the inbound MCP request's auth headers so session/bearer middleware keeps
-working. Shared by tool calls (non-GET) and resource reads (GET).
+Synthesizes the rpc Request from a resolved registry entry and dispatches
+through verb.fetch — the same code path the HTTP router uses — forwarding the
+inbound MCP request's auth headers so session/bearer middleware keeps working.
 */
-function runRpc(
-    method: HttpVerb,
-    url: string,
+function dispatchVerb(
+    entry: VerbRegistryEntry,
     args: Record<string, unknown> | undefined,
     inbound: Request,
 ): Promise<Response> {
     const inboundUrl = new URL(inbound.url)
     const baseUrl = `${inboundUrl.protocol}//${inboundUrl.host}/`
     const request = buildRpcRequest({
-        method,
-        url,
+        method: entry.remote.method,
+        url: entry.remote.url,
         args,
         baseUrl,
         headers: forwardHeaders(inbound.headers),
     })
-    const entry = verbRegistry.get(url)
-    if (entry && entry.remote.method === method) {
-        return entry.remote.fetch(request)
-    }
-    throw new Error(`unknown rpc: ${method} ${url}`)
+    return entry.remote.fetch(request)
 }
 
 /*
-Validates prompt arguments against the prompt's schema (when present),
-renders the messages, and maps them to the MCP prompts/get wire shape.
-A bare string render result becomes a single user message.
+Interpolates the caller's arguments into the prompt body and wraps the
+result in the MCP prompts/get wire shape — a markdown prompt is a single
+user message whose text is the rendered template.
 */
-async function getPrompt(
+function getPrompt(
     name: string,
     args: Record<string, unknown> | undefined,
-): Promise<Record<string, unknown>> {
+): Record<string, unknown> {
     const entry = promptRegistry.get(name)
     if (!entry) {
         throw new Error(`unknown prompt: ${name}`)
     }
-    let value: unknown = args ?? {}
-    if (entry.schema) {
-        const result = await entry.schema['~standard'].validate(value)
-        if (result.issues) {
-            throw new Error(
-                `prompt "${name}" arguments failed validation: ${JSON.stringify(result.issues)}`,
-            )
-        }
-        value = result.value
-    }
-    const rendered = await entry.prompt.render(value as Record<string, string>)
-    const messages =
-        typeof rendered === 'string'
-            ? [{ role: 'user', content: { type: 'text', text: rendered } }]
-            : rendered.map((message) => ({
-                  role: message.role,
-                  content: { type: 'text', text: message.text },
-              }))
+    const rendered = entry.prompt.render((args ?? {}) as Record<string, string>)
     return {
         ...(entry.prompt.description ? { description: entry.prompt.description } : {}),
-        messages,
+        messages: [{ role: 'user', content: { type: 'text', text: rendered } }],
     }
 }
 
@@ -277,7 +257,7 @@ export async function dispatchMcpRequest(
                 if (!params?.name) {
                     return jsonRpcError(id, -32602, 'Missing prompt name')
                 }
-                return jsonRpcOk(id, await getPrompt(params.name, params.arguments))
+                return jsonRpcOk(id, getPrompt(params.name, params.arguments))
             }
             default:
                 return jsonRpcError(id, -32601, `Method not found: ${envelope.method}`)

package/src/lib/server/AppModule.ts

@@ -7,10 +7,10 @@ function that runs on SIGINT/SIGTERM. handle is single-middleware with
 next so user code can mutate the response or branch on the URL.
 
 WebSockets are not exposed here — belte's only native WebSocket
-surface is the sockets hub (see `belte/sockets`), multiplexed onto a
+surface is the sockets hub (see `belte/server/socket`), multiplexed onto a
 single framework-owned connection per client at `/__belte/sockets`.
 Inside request scopes, the live Bun.Server is reachable via the
-exported `server` proxy from `belte/server`; `init` receives it
+exported `server()` function from `belte/server`; `init` receives it
 explicitly because it runs outside a request.
 */
 export type AppModule = {

package/src/lib/server/cli/handleCliDownload.ts

@@ -1,4 +1,3 @@
-import { existsSync, statSync } from 'node:fs'
 import { NO_STORE } from '../../shared/cacheControlValues.ts'
 import { log } from '../../shared/log.ts'
 import { normalizeTarget } from '../../shared/normalizeTarget.ts'
@@ -55,8 +54,9 @@ async function computeBinary(
     didn't run `belte cli` again. Other source paths (project lib,
     transitive imports) fall back to manual rebuild.
     */
-    if (existsSync(binaryPath)) {
-        const binaryMtime = statSync(binaryPath).mtimeMs
+    const binaryFile = Bun.file(binaryPath)
+    if (await binaryFile.exists()) {
+        const binaryMtime = (await binaryFile.stat()).mtimeMs
         const sourceMtime = await maxSourceMtime(cwd)
         if (binaryMtime >= sourceMtime) {
             return binaryPath
@@ -71,9 +71,8 @@ async function computeBinary(
         await buildCli({
             cwd,
             platforms: [normalizeTarget(platform)],
-            thin: true,
         })
-        return existsSync(binaryPath) ? binaryPath : undefined
+        return (await binaryFile.exists()) ? binaryPath : undefined
     } catch (error) {
         log.error(error)
         return undefined

package/src/lib/server/cli/handleCliInstall.ts

@@ -1,6 +1,17 @@
 import { NO_STORE } from '../../shared/cacheControlValues.ts'
 import { installScript } from './installScript.ts'
 
+/*
+The request host is reflected verbatim into a shell script the user pipes
+to `sh`, so it's constrained to the strict authority charset: letters,
+digits, `.`, `-`, `_`, `:` (port + IPv6 separators), and IPv6 `[` `]`
+brackets. That set excludes every character that could break out of the
+interpolated `URL="…"` line in installScript (`"`, `$`, backtick, `\`,
+whitespace), neutralising shell injection via a crafted Host header
+regardless of how lenient the upstream URL parser is.
+*/
+const SAFE_HOST = /^[A-Za-z0-9._:[\]-]+$/
+
 /*
 Handles GET /__belte/cli — returns the platform-detecting shell script.
 Authoritative URL for the tarball is derived from the inbound request
@@ -9,6 +20,12 @@ on). Program name is the bundler-emitted `belte:cli-name` value.
 */
 export function handleCliInstall(request: Request, programName: string): Response {
     const url = new URL(request.url)
+    if (!SAFE_HOST.test(url.host)) {
+        return new Response('Bad Request', {
+            status: 400,
+            headers: { 'Cache-Control': NO_STORE },
+        })
+    }
     const appUrl = `${url.protocol}//${url.host}`
     const script = installScript(appUrl, programName)
     return new Response(script, {

package/src/lib/server/error.ts

@@ -1,5 +1,6 @@
 import { NO_STORE } from '../shared/cacheControlValues.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
 
 /*
 Plain-text error Response — clearer than constructing a Response by
@@ -11,7 +12,9 @@ returns the message, no parsing).
 
 `message` defaults to the status's standard reason phrase when
 omitted (e.g. `error(404)` body = 'Not Found'). The body is
-text/plain so intermediaries don't try to render or sniff it.
+text/plain so intermediaries don't try to render or sniff it. A final
+`ResponseInit` adds headers (e.g. `Retry-After` on a 429); the positional
+`status` always wins over any `init.status`.
 
 To short-circuit a handler instead of returning, `throw new Error(...)`
 or `throw new HttpError(error(...))` — the framework's `app.handleError`
@@ -19,6 +22,13 @@ hook catches thrown errors. This helper deliberately returns a Response
 rather than throwing one so a single `return error(...)` is the
 expected pattern, with the same control flow as `return json(...)`.
 */
+
+/*
+Standard reason phrases for the statuses error() is realistically called
+with. Maintained explicitly because Bun's `Response` does not populate
+`statusText` from the status code, so there's no platform table to read.
+Unlisted codes fall back to `HTTP <status>`.
+*/
 const STATUS_TEXT: Record<number, string> = {
     400: 'Bad Request',
     401: 'Unauthorized',
@@ -44,13 +54,17 @@ the union of branches in a handler narrow to whatever the success
 branch carries (`TypedResponse<{user}> | TypedResponse<never>` → Return
 = {user}).
 */
-export function error(status: number, message?: string): TypedResponse<never> {
+export function error(status: number, message?: string, init?: ResponseInit): TypedResponse<never> {
     const body = message ?? STATUS_TEXT[status] ?? `HTTP ${status}`
-    return new Response(body, {
-        status,
-        headers: {
-            'Content-Type': 'text/plain; charset=utf-8',
-            'Cache-Control': NO_STORE,
-        },
-    }) as TypedResponse<never>
+    return new Response(
+        body,
+        withResponseDefaults(
+            init,
+            {
+                'Content-Type': 'text/plain; charset=utf-8',
+                'Cache-Control': NO_STORE,
+            },
+            status,
+        ),
+    ) as TypedResponse<never>
 }

package/src/lib/server/json.ts

@@ -1,5 +1,6 @@
 import { NO_STORE } from '../shared/cacheControlValues.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
 
 /*
 JSON Response with rpc-friendly defaults — same shape as
@@ -20,9 +21,8 @@ For non-default cache policy pass `init.headers`; explicit
 `cache-control` wins over the default.
 */
 export function json<T>(data: T, init?: ResponseInit): TypedResponse<T> {
-    const headers = new Headers(init?.headers)
-    if (!headers.has('cache-control')) {
-        headers.set('cache-control', NO_STORE)
-    }
-    return Response.json(data, { ...init, headers }) as TypedResponse<T>
+    return Response.json(
+        data,
+        withResponseDefaults(init, { 'Cache-Control': NO_STORE }),
+    ) as TypedResponse<T>
 }

package/src/lib/server/jsonl.ts

@@ -24,17 +24,22 @@ message crosses the wire.
 import { NO_STORE } from '../shared/cacheControlValues.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
 import { streamFromIterator } from './runtime/streamFromIterator.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
 
-export function jsonl<Frame>(iterable: AsyncIterable<Frame>): TypedResponse<Frame> {
+export function jsonl<Frame>(
+    iterable: AsyncIterable<Frame>,
+    init?: ResponseInit,
+): TypedResponse<Frame> {
     const body = streamFromIterator(iterable, {
         encodeFrame: (value) => `${JSON.stringify(value)}\n`,
         encodeError: (message) => `${JSON.stringify({ $error: message })}\n`,
     })
-    return new Response(body, {
-        headers: {
+    return new Response(
+        body,
+        withResponseDefaults(init, {
             'Content-Type': 'application/jsonl; charset=utf-8',
             'Cache-Control': NO_STORE,
             'X-Content-Type-Options': 'nosniff',
-        },
-    }) as TypedResponse<Frame>
+        }),
+    ) as TypedResponse<Frame>
 }

package/src/lib/server/prompts/definePrompt.ts

@@ -3,11 +3,11 @@ import type { Prompt } from './types/Prompt.ts'
 import type { PromptOptions } from './types/PromptOptions.ts'
 
 /*
-Builds a Prompt from a name + options. The bundler rewrites every
-`export const NAME = prompt(opts)` inside `src/server/prompts/<file>.ts`
-into `__belteDefinePrompt__("<name>", opts)` so the file path becomes the
-prompt's identity. Registers itself so the MCP dispatcher can enumerate
-and render it.
+Builds a Prompt from a name + options. The resolver plugin parses every
+`src/mcp/prompts/<file>.md` and generates a module that calls
+`definePrompt("<name>", { description, jsonSchema, render })`, so the file
+path becomes the prompt's identity. Registers itself so the MCP dispatcher
+can enumerate and render it.
 */
 export function definePrompt(name: string, opts: PromptOptions): Prompt {
     const self: Prompt = {
@@ -15,6 +15,6 @@ export function definePrompt(name: string, opts: PromptOptions): Prompt {
         description: opts.description,
         render: opts.render,
     }
-    registerPrompt({ prompt: self, schema: opts.schema, jsonSchema: opts.jsonSchema })
+    registerPrompt({ prompt: self, jsonSchema: opts.jsonSchema })
     return self
 }

package/src/lib/server/prompts/renderPromptTemplate.ts

@@ -0,0 +1,16 @@
+// `{{name}}` placeholder, surrounding whitespace tolerated, names are
+// word chars or hyphens to match valid MCP argument identifiers.
+const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g
+
+/*
+Renders a markdown prompt body by substituting each `{{name}}` placeholder
+with the matching argument value. Missing arguments collapse to an empty
+string — MCP only enforces `required` at the client, so an optional
+argument the model omits should simply vanish from the text. Called by the
+render closure the resolver plugin generates for every `.md` prompt.
+*/
+export function renderPromptTemplate(template: string, args: Record<string, string>): string {
+    return template.replace(PLACEHOLDER, (_match, key: string) =>
+        args[key] === undefined ? '' : String(args[key]),
+    )
+}

package/src/lib/server/prompts/types/Prompt.ts

@@ -1,14 +1,13 @@
-import type { PromptMessage } from './PromptMessage.ts'
-
 /*
-An MCP prompt declared once with `prompt(opts)` inside a file under
-`src/server/prompts/`. The bundler stamps in the `name` from the file
-path; `render(args)` produces the messages returned by `prompts/get`.
-Prompts are MCP-only — there is no client-side counterpart, so the
-shape carries no ClientFlags.
+An MCP prompt declared by a markdown file under `src/mcp/prompts/`. The
+resolver plugin parses the file's frontmatter + body and generates a call
+to definePrompt, stamping in the `name` from the file path; `render(args)`
+interpolates the body's `{{name}}` placeholders into the single user
+message returned by `prompts/get`. Prompts are MCP-only — there is no
+client-side counterpart, so the shape carries no ClientFlags.
 */
-export type Prompt<Args = Record<string, string>> = {
+export type Prompt = {
     readonly name: string
     readonly description: string | undefined
-    render(args: Args): PromptMessage[] | string | Promise<PromptMessage[] | string>
+    render(args: Record<string, string>): string
 }

package/src/lib/server/prompts/types/PromptOptions.ts

@@ -1,17 +1,12 @@
-import type { StandardSchemaV1 } from '../../rpc/types/StandardSchemaV1.ts'
-import type { PromptMessage } from './PromptMessage.ts'
-
 /*
-Server-side options passed when declaring a prompt via `prompt(opts)`.
-MCP prompts are read-only templates: `render(args)` turns the caller's
-arguments into one or more chat messages. The optional Standard Schema
-both validates incoming arguments and supplies the argument list MCP
-advertises in `prompts/list` (top-level properties + required array).
-All of this is server-only — prompts are never imported by client code.
+Options definePrompt receives for one markdown prompt. The resolver plugin
+generates this object from the file: `description` + `jsonSchema` come from
+the frontmatter (the schema built from the `arguments` list), and `render`
+closes over the parsed body. All of this is server-only — prompts are never
+imported by client code.
 */
-export type PromptOptions<Args = Record<string, string>> = {
+export type PromptOptions = {
     description?: string
-    schema?: StandardSchemaV1
     jsonSchema?: Record<string, unknown>
-    render: (args: Args) => PromptMessage[] | string | Promise<PromptMessage[] | string>
+    render: (args: Record<string, string>) => string
 }

package/src/lib/server/prompts/types/PromptRegistryEntry.ts

@@ -1,15 +1,13 @@
-import type { StandardSchemaV1 } from '../../rpc/types/StandardSchemaV1.ts'
 import type { Prompt } from './Prompt.ts'
 
 /*
 Per-prompt registry record. The MCP dispatcher enumerates this to build
-`prompts/list` (description + arguments from the schema) and to dispatch
-`prompts/get` (validate args against the schema, then render). Schema +
-jsonSchema stay off the public Prompt shape so the render closure isn't
+`prompts/list` (description + arguments from the JSON Schema) and to
+dispatch `prompts/get` (render the body with the caller's arguments).
+jsonSchema stays off the public Prompt shape so the render closure isn't
 burdened with metadata it never reads.
 */
 export type PromptRegistryEntry = {
     prompt: Prompt
-    schema: StandardSchemaV1 | undefined
     jsonSchema: Record<string, unknown> | undefined
 }

package/src/lib/server/prompts/types/PromptRoutes.ts

@@ -2,9 +2,9 @@ import type { Prompt } from './Prompt.ts'
 
 /*
 Manifest of prompt-name → module loader. Produced by the resolver plugin
-from each `.ts` under src/server/prompts/. Each module has exactly one
-named export, a Prompt whose `.name` was stamped in by the bundler
-rewrite. The registry loader imports every module once so the MCP
-dispatcher can enumerate the full prompt surface.
+from each `.md` under src/mcp/prompts/. Each markdown file is transformed
+into a module that registers one Prompt (its `.name` stamped in by the
+generated definePrompt call) on import. The registry loader imports every
+module once so the MCP dispatcher can enumerate the full prompt surface.
 */
 export type PromptRoutes = Record<string, () => Promise<Record<string, Prompt>>>

package/src/lib/server/redirect.ts

@@ -14,9 +14,13 @@ Status guidance:
 - 303 — "after a POST, GET this" (forces GET on the follow-up)
 - 307 — temporary, preserve method
 - 308 — permanent, preserve method
+
+A final `ResponseInit` adds headers (e.g. a `Set-Cookie` on the redirect);
+the positional `status` always wins over any `init.status`.
 */
 import { NO_STORE } from '../shared/cacheControlValues.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
+import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
 
 type RedirectStatus = 301 | 302 | 303 | 307 | 308
 
@@ -26,12 +30,13 @@ the wire response is a 3xx with no body the caller resolves to, so it
 must not pollute the inferred `Return` of a route that conditionally
 redirects vs returns json.
 */
-export function redirect(url: string, status: RedirectStatus = 302): TypedResponse<never> {
-    return new Response(null, {
-        status,
-        headers: {
-            Location: url,
-            'Cache-Control': NO_STORE,
-        },
-    }) as TypedResponse<never>
+export function redirect(
+    url: string,
+    status: RedirectStatus = 302,
+    init?: ResponseInit,
+): TypedResponse<never> {
+    return new Response(
+        null,
+        withResponseDefaults(init, { Location: url, 'Cache-Control': NO_STORE }, status),
+    ) as TypedResponse<never>
 }

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

@@ -77,9 +77,10 @@ export function defineVerb<Args, Return>(
 
     /*
     `getRequest` is unused on the server path — handlers receive parsed
-    `args` directly. createRemoteFunction passes a thunk so the client
-    side can lazily synthesize its Request without forcing the server
-    to allocate one per SSR call.
+    `args` directly and reach the inbound Request via `request()`.
+    createRemoteFunction passes a thunk so the client side can lazily
+    synthesize its Request without forcing the server to allocate one per
+    SSR call.
     */
     function invoke(args: Args | undefined): Promise<Response> {
         return schema ? validateThenHandle(args) : runHandler(args)

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

@@ -0,0 +1,18 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import type { VerbRegistryEntry } from './types/VerbRegistryEntry.ts'
+import { verbRegistry } from './verbRegistry.ts'
+
+/*
+Finds the registered verb whose URL maps to a given command name (folder
+segments joined with `-`, per commandNameForUrl). The CLI client proxy and
+the MCP tool dispatcher both key off this name, so the scan lives here once
+rather than being re-implemented — and reused — at each call site.
+*/
+export function findVerbByCommandName(name: string): VerbRegistryEntry | undefined {
+    for (const entry of verbRegistry.values()) {
+        if (commandNameForUrl(entry.remote.url) === name) {
+            return entry
+        }
+    }
+    return undefined
+}

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

@@ -19,7 +19,7 @@ stored entry — the decode just happens on the way out for callers of
 SSE / JSONL handlers yield each frame; non-streaming handlers yield the
 decoded body once then complete. The result is a Subscribable, so it
 can be passed to subscribe() and shared across reactive consumers.
-For sustained broadcast / pub-sub use the `belte/sockets` primitive —
+For sustained broadcast / pub-sub use the `belte/server/socket` primitive —
 HTTP rpc isn't the place for long-lived multi-publisher subscriptions.
 `.fetch(req)` is the framework's request-dispatch entry point — used by
 the router to invoke the handler from an incoming HTTP request, not

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

@@ -16,6 +16,10 @@ verb helper can infer `Return` automatically — no need to annotate
 `GET<Args, Return>` when the handler returns one of the respond helpers.
 A bare `new Response(...)` is still acceptable: the brand is optional, so
 untagged Responses simply fall back to `Return = unknown`.
+
+Handlers that need the inbound Request (headers, `request.signal`, …) read
+it via `request()` from `belte/server` rather than a handler parameter, so
+the signature stays a single parsed-`args` bag.
 */
 export type RemoteHandler<Args, Return> = (
     args: Args,

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

@@ -0,0 +1,8 @@
+/*
+Whether the client advertised zstd in Accept-Encoding. Both static-asset
+servers (the `/_app/` chunk server and the public/ server) gate their
+pre-compressed responses on this, so the check lives in one place.
+*/
+export function acceptsZstd(req: Request): boolean {
+    return (req.headers.get('accept-encoding') ?? '').toLowerCase().includes('zstd')
+}

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

@@ -41,8 +41,10 @@ export function buildOpenApiSpec(info: {
         const url = entry.remote.url
         const method = entry.remote.method
         const jsonSchema = jsonSchemaForSchema(entry.schema, entry.jsonSchema)
+        const description = jsonSchema.description as string | undefined
         const operation: Record<string, unknown> = {
             operationId: commandNameForUrl(url),
+            ...(description ? { description } : {}),
             responses: { '200': { description: 'OK' } },
         }
         if (BODY_METHODS.has(method)) {