@briancray/belte 0.3.1 → 0.5.0

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,9 @@ 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 { parsePort } from './parsePort.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
 import { requestContext } from './requestContext.ts'
 import { safeJsonForScript } from './safeJsonForScript.ts'
@@ -58,6 +60,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/'
@@ -101,7 +104,7 @@ export async function createServer({
     distDir = `${process.cwd()}/dist`,
     publicDir = `${process.cwd()}/src/browser/public`,
     resourcesDir = `${process.cwd()}/src/mcp/resources`,
-    port = Number(process.env.PORT ?? 3000),
+    port = parsePort(process.env.PORT) ?? 3000,
 }: {
     pages: Pages
     rpc: RemoteRoutes
@@ -125,16 +128,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 +450,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))
             }
@@ -526,22 +547,37 @@ export async function createServer({
     */
     setActiveServer(server)
 
-    if (app?.init) {
-        const cleanup = await app.init({ server })
+    const cleanup = app?.init ? await app.init({ server }) : undefined
+    /*
+    Close the listener deterministically on shutdown. Always registered (even
+    with no init cleanup) so the socket is released via server.stop rather than
+    left to abrupt process exit — which leaves the port in TIME_WAIT and races
+    a fast restart. A watchdog force-exits if a user cleanup hangs, so a stuck
+    cleanup can't keep the process (and its port) alive.
+    */
+    const shutdown = async () => {
+        server.stop(true)
         if (typeof cleanup === 'function') {
-            const shutdown = async () => {
-                try {
-                    await cleanup()
-                } catch (err) {
-                    log.error(err)
-                }
-                process.exit(0)
+            setTimeout(() => process.exit(0), 3000).unref()
+            try {
+                await cleanup()
+            } catch (err) {
+                log.error(err)
             }
-            process.once('SIGINT', shutdown)
-            process.once('SIGTERM', shutdown)
         }
+        process.exit(0)
     }
+    process.once('SIGINT', shutdown)
+    process.once('SIGTERM', shutdown)
 
     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
 }

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

@@ -0,0 +1,29 @@
+import { Glob } from 'bun'
+
+/*
+Scans `cwd` for files matching `pattern` and returns their request paths as
+a Set, mapping each relative file path to a root-relative URL via `keyFor`.
+Used to snapshot the on-disk asset trees (the `public/` files, the `_app`
+precompressed `.zst` siblings) once at boot so the request path is a Set
+lookup instead of a filesystem stat.
+
+A missing directory makes scan throw ENOENT — swallowed to an empty Set so
+the caller just falls through. This scan-and-catch is also the reliable
+directory existence test: `Bun.file(dir).exists()` returns false for a
+directory, so guarding the scan with it silently yields an empty Set.
+*/
+export async function globToPathSet(
+    cwd: string,
+    pattern: string,
+    keyFor: (file: string) => string,
+    options?: { dot?: boolean },
+): Promise<Set<string>> {
+    try {
+        const files = await Array.fromAsync(
+            new Glob(pattern).scan({ cwd, dot: options?.dot ?? false }),
+        )
+        return new Set(files.map(keyFor))
+    } catch {
+        return new Set()
+    }
+}

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

@@ -0,0 +1,44 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import { log } from '../../shared/log.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+import { socketRegistry } from '../sockets/socketRegistry.ts'
+import { ensureRegistriesLoaded } from './registryManifests.ts'
+
+/*
+Surfaces the otherwise-silent consequence of belte's multimodal-by-default
+rule: a verb or socket with no schema never reaches MCP or the CLI, since
+the schema is what makes those surfaces safe to advertise. Loads the full
+registry, then logs (once at boot, only when `belte` debug logging is on
+so it doesn't force eager imports in production) the routes that stay
+browser-only purely for lack of a schema — so the missing matrix cells
+are visible rather than surprising. Best-effort: enumeration failures are
+swallowed since this is diagnostic only.
+*/
+export async function logBrowserOnlyRoutes(): Promise<void> {
+    try {
+        await ensureRegistriesLoaded()
+    } catch {
+        return
+    }
+    const names: string[] = []
+    for (const entry of verbRegistry.values()) {
+        if (
+            entry.clients.browser &&
+            !entry.clients.mcp &&
+            !entry.clients.cli &&
+            !entry.inputSchema
+        ) {
+            names.push(commandNameForUrl(entry.remote.url))
+        }
+    }
+    for (const entry of socketRegistry.values()) {
+        if (entry.clients.browser && !entry.clients.mcp && !entry.clients.cli && !entry.schema) {
+            names.push(entry.socket.name)
+        }
+    }
+    if (names.length > 0) {
+        log.detail(
+            `browser-only (no schema → not on MCP/CLI): ${names.sort().join(', ')} — add a schema to expose them`,
+        )
+    }
+}

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

@@ -0,0 +1,16 @@
+/*
+Parses a PORT env value into a usable TCP port, returning undefined for
+missing, empty, or out-of-range/non-integer input so the caller can fall back
+to a default. A bare Number() turns '' into 0 (a random kernel-assigned port)
+and 'abc' into NaN, both silently wrong; this rejects them instead.
+*/
+export function parsePort(value: string | undefined): number | undefined {
+    if (value === undefined || value.trim() === '') {
+        return undefined
+    }
+    const port = Number(value)
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        return undefined
+    }
+    return port
+}

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -1,6 +1,10 @@
 import type { ServerWebSocket } from 'bun'
 import { log } from '../../shared/log.ts'
+import { error } from '../error.ts'
+import { json } from '../json.ts'
+import { sse } from '../sse.ts'
 import { lookupSocket } from './lookupSocket.ts'
+import { recentHistory } from './recentHistory.ts'
 import type { SocketClientFrame } from './types/SocketClientFrame.ts'
 import type { SocketRoutes } from './types/SocketRoutes.ts'
 import type { SocketServerFrame } from './types/SocketServerFrame.ts'
@@ -12,6 +16,7 @@ type SocketDispatcher = {
     open(ws: ServerWebSocket<unknown>): void
     message(ws: ServerWebSocket<unknown>, data: string | Buffer): void
     close(ws: ServerWebSocket<unknown>): void
+    rest(req: Request, name: string): Promise<Response>
 }
 
 /*
@@ -154,14 +159,9 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         a number is clamped to the buffer length so the client can ask
         for "as many as available, up to N".
         */
-        const history = entry.snapshotHistory()
-        const replayCount =
-            frame.replay === undefined ? history.length : Math.min(frame.replay, history.length)
-        if (replayCount > 0) {
-            history.slice(history.length - replayCount).forEach((message) => {
-                send(ws, { type: 'msg', socket: frame.socket, message })
-            })
-        }
+        recentHistory(entry, frame.replay).forEach((message) => {
+            send(ws, { type: 'msg', socket: frame.socket, message })
+        })
     }
 
     function handleUnsub(
@@ -225,7 +225,70 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         void ws
     }
 
+    /*
+    HTTP face of the sockets hub at `/__belte/sockets/<name>`, for the CLI
+    and MCP (which can't speak the ws multiplex protocol):
+
+      GET  text/event-stream → live SSE stream; `?tail=N` replays the last
+           N buffered messages before tailing live (default 0 = live only).
+      GET  otherwise         → JSON array of the recent history buffer
+           (`?tail=N` caps it; default all).
+      POST                   → publish the JSON body, gated by the socket's
+           clientPublish policy and validated against its schema.
+
+    Loads the socket module on first hit (same cache the ws path uses) so
+    its defineSocket call populates the registry.
+    */
+    async function rest(req: Request, name: string): Promise<Response> {
+        const loader = ensureLoaded(name)
+        if (!loader) {
+            return error(404)
+        }
+        try {
+            await loader
+        } catch (loadError) {
+            log.error(loadError)
+            return error(500, 'socket failed to load')
+        }
+        const entry = lookupSocket(name)
+        if (!entry) {
+            return error(404)
+        }
+        const tailParam = new URL(req.url).searchParams.get('tail')
+        const count = tailParam !== null ? Number(tailParam) : undefined
+        if (req.method === 'GET' || req.method === 'HEAD') {
+            if ((req.headers.get('accept') ?? '').includes('text/event-stream')) {
+                return sse(entry.socket.tail(count ?? 0))
+            }
+            return json(recentHistory(entry, count))
+        }
+        if (req.method === 'POST') {
+            if (!entry.allowClientPublish) {
+                return error(403, 'publishing not allowed')
+            }
+            let message: unknown
+            try {
+                message = await req.json()
+            } catch {
+                return error(400, 'body must be JSON')
+            }
+            try {
+                // publish() validates against the socket schema and throws on a bad payload.
+                entry.socket.publish(message)
+            } catch (publishError) {
+                return error(
+                    422,
+                    publishError instanceof Error ? publishError.message : String(publishError),
+                )
+            }
+            return json({ ok: true })
+        }
+        return error(405, undefined, { headers: { Allow: 'GET, POST' } })
+    }
+
     return {
+        rest,
+
         open(ws) {
             connections.set(ws, { subToSocket: new Map(), socketSubs: new Map() })
         },

package/src/lib/server/sockets/defineSocket.ts

@@ -29,7 +29,13 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
     const ttl = opts.ttl
     const schema = opts.schema
     const jsonSchema = opts.jsonSchema
-    const clients = resolveClientFlags(opts.clients, schema !== undefined)
+    /*
+    A schema makes the socket's payload safe to advertise to non-browser
+    surfaces, so it flips mcp/cli on by default — exposing the `tail` read
+    tool (and `publish` when clientPublish is set). Explicit `clients` wins.
+    */
+    const hasSchema = schema !== undefined
+    const clients = resolveClientFlags(opts.clients, { mcp: hasSchema, cli: hasSchema })
     type BufferEntry = { value: T; expiresAt: number | undefined }
     const buffer: BufferEntry[] = []
     const subscribers = new Set<(message: T) => void>()

package/src/lib/server/sockets/recentHistory.ts

@@ -0,0 +1,11 @@
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Recent slice of a socket's history buffer: the last `count` messages, or
+the whole buffer when `count` is undefined. Shared by the sockets HTTP
+`rest()` face and the MCP `<base>-tail` tool so the two can't drift.
+*/
+export function recentHistory(entry: SocketRegistryEntry, count: number | undefined): unknown[] {
+    const history = entry.snapshotHistory()
+    return count === undefined ? history : history.slice(Math.max(0, history.length - count))
+}

package/src/lib/server/sockets/socketOperations.ts

@@ -0,0 +1,35 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import type { SocketOperation } from './types/SocketOperation.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Projects a socket registry entry into the operations it exposes to the
+CLI and MCP. Single source for the naming convention (`<base>-tail` /
+`<base>-publish`), the existence rule (tail always; publish only when the
+socket allows client publishing), and each operation's HTTP face — so the
+CLI manifest builder, the MCP tool list, and the MCP tool dispatcher can't
+disagree about which operations a socket has or what they're called.
+*/
+export function socketOperations(entry: SocketRegistryEntry): SocketOperation[] {
+    const base = commandNameForUrl(entry.socket.name)
+    const restUrl = `/__belte/sockets/${entry.socket.name}`
+    const operations: SocketOperation[] = [
+        {
+            kind: 'tail',
+            name: `${base}-tail`,
+            socketName: entry.socket.name,
+            restUrl,
+            method: 'GET',
+        },
+    ]
+    if (entry.allowClientPublish) {
+        operations.push({
+            kind: 'publish',
+            name: `${base}-publish`,
+            socketName: entry.socket.name,
+            restUrl,
+            method: 'POST',
+        })
+    }
+    return operations
+}

package/src/lib/server/sockets/types/SocketOperation.ts

@@ -0,0 +1,22 @@
+import type { HttpVerb } from '../../rpc/types/HttpVerb.ts'
+
+/*
+One operation a socket exposes to the non-browser surfaces. A socket
+always offers a `tail` (read recent / stream live) and, when
+`clientPublish` is set, a `publish` (send a message). This is the shared
+skeleton — name, kind, HTTP face — that the CLI manifest, the MCP tool
+list, and the MCP dispatcher all read instead of re-deriving the naming
+convention and existence rule independently. Each surface dresses it with
+its own presentation (descriptions, input schema, annotations).
+*/
+export type SocketOperation = {
+    kind: 'tail' | 'publish'
+    // Command/tool name: the socket's command-name base plus `-tail` / `-publish`.
+    name: string
+    // Raw socket name, for the HTTP path and human-facing descriptions.
+    socketName: string
+    // HTTP face of the operation: `/__belte/sockets/<name>`.
+    restUrl: string
+    // GET for tail, POST for publish.
+    method: HttpVerb
+}

package/src/lib/server/sse.ts

@@ -24,6 +24,7 @@ EventSource surfaces this via its `error` listener and `subscribe()`
 maps it to the entry's `error` field.
 */
 import { NO_STORE } from '../shared/cacheControlValues.ts'
+import { sseErrorFrame } from '../shared/sseErrorFrame.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
 import { streamFromIterator } from './runtime/streamFromIterator.ts'
 import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
@@ -36,7 +37,7 @@ export function sse<Frame>(
 ): TypedResponse<Frame> {
     const body = streamFromIterator(iterable, {
         encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
-        encodeError: (message) => `event: error\ndata: ${JSON.stringify({ message })}\n\n`,
+        encodeError: (message) => sseErrorFrame.encode(message),
         keepaliveMs: KEEPALIVE_INTERVAL_MS,
         keepalivePayload: ': keepalive\n\n',
     })

package/src/lib/shared/appDataDir.ts

@@ -0,0 +1,22 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/*
+Platform-standard per-user data directory for a bundle, keyed by its program
+name. cwd-independent on purpose: the path derives from `programName`, not the
+process working directory — which the OS `open` command sets to `/`, so anything
+relying on cwd (Bun's `.env` autoload, relative paths) finds nothing inside a
+launched `.app`. This is where a bundle keeps what can't be baked at compile time
+— the user's config, DB, and cache. macOS Application Support, Windows %APPDATA%,
+XDG data home elsewhere. Pure: computes the path, never touches the filesystem.
+*/
+export function appDataDir(programName: string): string {
+    const home = homedir()
+    if (process.platform === 'darwin') {
+        return join(home, 'Library', 'Application Support', programName)
+    }
+    if (process.platform === 'win32') {
+        return join(process.env.APPDATA ?? join(home, 'AppData', 'Roaming'), programName)
+    }
+    return join(process.env.XDG_DATA_HOME ?? join(home, '.local', 'share'), programName)
+}

package/src/lib/shared/buildRpcRequest.ts

@@ -1,4 +1,5 @@
 import type { HttpVerb } from '../server/rpc/types/HttpVerb.ts'
+import { carriesBodyArgs } from './carriesBodyArgs.ts'
 
 /*
 Builds the Request a verb helper uses to invoke its handler. Same shape on
@@ -27,7 +28,7 @@ export function buildRpcRequest({
     headers?: Headers
 }): Request {
     const requestHeaders = headers ?? new Headers()
-    if (method === 'GET' || method === 'DELETE' || method === 'HEAD') {
+    if (!carriesBodyArgs(method)) {
         const target = appendQuery(method, url, args)
         return new Request(new URL(target, baseUrl).href, { method, headers: requestHeaders })
     }