@briancray/belte 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.3.1",
+    "version": "0.4.0",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",

package/src/bundleApp.ts

@@ -4,6 +4,7 @@ import { ensureWebviewLib } from './lib/bundle/ensureWebviewLib.ts'
 import { infoPlist } from './lib/bundle/infoPlist.ts'
 import { pngToIcns } from './lib/bundle/pngToIcns.ts'
 import { serverBinaryFilename } from './lib/bundle/serverBinaryFilename.ts'
+import { signMacApp } from './lib/bundle/signMacApp.ts'
 import { webviewLibName } from './lib/bundle/webviewLibName.ts'
 import { detectTarget } from './lib/shared/detectTarget.ts'
 import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
@@ -17,8 +18,9 @@ const WORKER_ENTRY = new URL('./controlServerWorker.ts', import.meta.url).pathna
 
 /*
 Assembles a movable, self-contained app bundle for the host platform —
-no signing, no cross-compilation. Three pieces travel together so the app
-runs on another machine of the same OS with nothing installed:
+no cross-compilation, and on macOS an ad-hoc seal so it launches on other
+Macs (signMacApp). Three pieces travel together so the app runs on another
+machine of the same OS with nothing installed:
 
   - the standalone server binary (`compile()`, assets embedded)
   - the launcher binary (appEntry — spawns the server, opens the webview)
@@ -106,6 +108,14 @@ export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}):
             `${bundleRoot}/Contents/Info.plist`,
             infoPlist({ name: programName, version, icon: hasIcon ? 'icon' : undefined }),
         )
+
+        // Seal the finished bundle so it launches on other Macs — must run last,
+        // after every binary, the lib, and Info.plist are in place.
+        await signMacApp(bundleRoot, [
+            `${libDir}/${webviewLibName()}`,
+            `${binDir}/${serverBinaryFilename()}`,
+            launcherPath,
+        ])
     }
 
     log.success(`bundled app: ${bundleRoot} (target: ${target})`)

package/src/discoveryEntry.ts

@@ -2,7 +2,10 @@
 import { rpc } from './_virtual/rpc.ts'
 // @ts-expect-error virtual module resolved by belteResolverPlugin
 import { sockets } from './_virtual/sockets.ts'
+import type { CliManifestEntry } from './lib/cli/types/CliManifestEntry.ts'
 import { verbRegistry } from './lib/server/rpc/verbRegistry.ts'
+import { socketOperations } from './lib/server/sockets/socketOperations.ts'
+import { socketRegistry } from './lib/server/sockets/socketRegistry.ts'
 import { commandNameForUrl } from './lib/shared/commandNameForUrl.ts'
 import { jsonSchemaForSchema } from './lib/shared/jsonSchemaForSchema.ts'
 
@@ -18,17 +21,61 @@ await Promise.all([
     ...Object.values(sockets).map((loader) => (loader as () => Promise<unknown>)()),
 ])
 
-const manifest = Object.fromEntries(
-    Array.from(verbRegistry.values())
-        .filter((entry) => entry.clients.cli)
-        .map((entry) => [
-            commandNameForUrl(entry.remote.url),
-            {
-                method: entry.remote.method,
-                url: entry.remote.url,
-                jsonSchema: jsonSchemaForSchema(entry.schema, entry.jsonSchema),
+const manifest: Record<string, CliManifestEntry> = {}
+
+for (const entry of verbRegistry.values()) {
+    if (!entry.clients.cli) {
+        continue
+    }
+    manifest[commandNameForUrl(entry.remote.url)] = {
+        method: entry.remote.method,
+        url: entry.remote.url,
+        jsonSchema: jsonSchemaForSchema(entry.inputSchema, entry.inputJsonSchema),
+    }
+}
+
+/*
+Sockets advertised to the CLI become commands against the socket's HTTP
+face (see socketOperations): `<base>-tail` streams live (GET +
+text/event-stream, with an optional --tail N to replay recent history
+first) and, when clientPublish is set, `<base>-publish` sends the args bag
+as a message (POST).
+*/
+for (const entry of socketRegistry.values()) {
+    if (!entry.clients.cli) {
+        continue
+    }
+    for (const operation of socketOperations(entry)) {
+        if (operation.kind === 'tail') {
+            manifest[operation.name] = {
+                method: operation.method,
+                url: operation.restUrl,
+                accept: 'text/event-stream',
+                jsonSchema: {
+                    type: 'object',
+                    description: `tail the "${operation.socketName}" socket`,
+                    properties: {
+                        tail: {
+                            type: 'number',
+                            description: 'replay last N messages before tailing live',
+                        },
+                    },
+                },
+            }
+            continue
+        }
+        const payloadSchema = jsonSchemaForSchema(entry.schema, entry.jsonSchema)
+        manifest[operation.name] = {
+            method: operation.method,
+            url: operation.restUrl,
+            jsonSchema: {
+                ...payloadSchema,
+                description:
+                    (payloadSchema.description as string | undefined) ??
+                    `publish a message to the "${operation.socketName}" socket`,
             },
-        ]),
-)
+        }
+    }
+}
 
 process.stdout.write(JSON.stringify(manifest))

package/src/lib/browser/cache.ts

@@ -5,6 +5,7 @@ import { canonicalJson } from '../shared/canonicalJson.ts'
 import { decodeResponse } from '../shared/decodeResponse.ts'
 import { getRemoteMeta } from '../shared/getRemoteMeta.ts'
 import { keyForRemoteCall } from '../shared/keyForRemoteCall.ts'
+import type { CacheEntry } from '../shared/types/CacheEntry.ts'
 import type { CacheOptions } from '../shared/types/CacheOptions.ts'
 
 type AnyRemote<Args, Return> = RemoteFunction<Args, Return> | RawRemoteFunction<Args>
@@ -46,7 +47,7 @@ export function cache<Args>(
 export function cache<Args, Return>(
     fn: AnyRemote<Args, Return>,
     options?: CacheOptions,
-): (args?: Args) => Promise<Return | Response> {
+): (args?: Args) => Promise<Return | Response> | Return {
     /*
     The "raw" variant lacks its own `.raw` sibling; only the decoded
     callable carries one. Tell them apart by that presence and dispatch the
@@ -55,20 +56,42 @@ export function cache<Args, Return>(
     const isRaw = !('raw' in fn)
     const rawFn = isRaw ? (fn as RawRemoteFunction<Args>) : (fn as RemoteFunction<Args, Return>).raw
     return (args) => {
-        const responsePromise = invokeWithCache(rawFn, args, options)
+        const store = activeCacheStore()
+        const key = resolveKey(rawFn, args, options?.key)
+        store.subscribe(key)
+        const existing = store.entries.get(key)
+        /*
+        Snapshot warm path: hydration pre-decoded the SSR body onto the
+        entry, so the decoded variant returns it synchronously — the first
+        {#await} render resolves without a microtask suspension and matches
+        the SSR DOM. Raw callers always take the Response path. After an
+        invalidate the replacement entry carries no value and falls through
+        to the async fetch as before.
+
+        The public overload stays typed Promise<Return> on purpose: a
+        non-thenable is the only thing {#await} can render synchronously, so
+        the sync return is left as an internal optimization rather than
+        widened to `Return | Promise<Return>` (which would leak it into every
+        caller's types). The one cost is that `.then`/`.catch`/`.finally`
+        directly on a warm result throws — consume cache via `await`/`{#await}`,
+        never `.then`. Don't "fix" the type; see memory cache-warm-sync-tradeoff.
+        */
+        if (!isRaw && existing?.value !== undefined) {
+            return existing.value as Return
+        }
+        const responsePromise = invokeWithCache(store, key, existing, rawFn, args, options)
         return isRaw ? responsePromise : (responsePromise.then(decodeResponse) as Promise<Return>)
     }
 }
 
 function invokeWithCache<Args>(
+    store: ReturnType<typeof activeCacheStore>,
+    key: string,
+    existing: CacheEntry | undefined,
     rawFn: RawRemoteFunction<Args>,
     args: Args | undefined,
     options: CacheOptions | undefined,
 ): Promise<Response> {
-    const store = activeCacheStore()
-    const key = resolveKey(rawFn, args, options?.key)
-    store.subscribe(key)
-    const existing = store.entries.get(key)
     if (existing) {
         return shareable(existing.promise)
     }

package/src/lib/browser/startClient.ts

@@ -25,10 +25,11 @@ pass finds the data via cache() without issuing a network round-trip.
 */
 function hydrateCacheFromSnapshot(store: CacheStore, snapshot: CacheSnapshotEntry[]): void {
     for (const entry of snapshot) {
+        const headers = new Headers(entry.headers)
         const response = new Response(entry.body, {
             status: entry.status,
             statusText: entry.statusText,
-            headers: new Headers(entry.headers),
+            headers,
         })
         store.entries.set(entry.key, {
             key: entry.key,
@@ -36,10 +37,32 @@ function hydrateCacheFromSnapshot(store: CacheStore, snapshot: CacheSnapshotEntr
             request: new Request(entry.url, { method: entry.method }),
             ttl: undefined,
             expiresAt: undefined,
+            value: warmValueFromSnapshot(entry.status, headers, entry.body),
         })
     }
 }
 
+/*
+Synchronously decodes a snapshot body so the warm entry reads without a
+microtask hop on first render. Mirrors decodeResponse for the textual cases
+the snapshot ships; non-2xx and 204 yield no warm value and fall back to the
+async path, which throws HttpError / returns undefined exactly as a live call
+would. Binary/xml bodies also skip the warm path and decode asynchronously.
+*/
+function warmValueFromSnapshot(status: number, headers: Headers, body: string): unknown {
+    if (status === 204 || status < 200 || status >= 300) {
+        return undefined
+    }
+    const contentType = (headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.includes('json')) {
+        return JSON.parse(body)
+    }
+    if (contentType.startsWith('text/')) {
+        return body
+    }
+    return undefined
+}
+
 function isInternalLinkEvent(event: MouseEvent): HTMLAnchorElement | undefined {
     if (event.defaultPrevented) {
         return undefined

package/src/lib/bundle/onMenu.ts

@@ -1,25 +1,40 @@
 /*
 Subscribes to bundle menu clicks. Each custom menu item declared in the bundle
-window config dispatches a `belte:menu` CustomEvent into the page when clicked;
-this registers `handler`, called with the item's `emit` name. Returns an
-unsubscribe function, so it drops straight into a Svelte `$effect`:
+window config dispatches a `belte:menu` CustomEvent into the page when clicked.
+Two forms, both returning an unsubscribe so they drop straight into a Svelte
+`$effect`:
 
+    // catch-all — every emit name flows through one handler
     $effect(() =>
         onMenu((name) => {
             if (name === 'reload') location.reload()
         }),
     )
 
+    // filtered — handler fires only for the named item
+    $effect(() => onMenu('reload', () => location.reload()))
+
 Inert during SSR and in a plain browser tab — `$effect` only runs client-side,
 the native menu that fires the event exists only in the bundled desktop app,
 and `window` is guarded so importing the module never assumes a DOM.
 */
-export function onMenu(handler: (name: string) => void): () => void {
+export function onMenu(handler: (name: string) => void): () => void
+export function onMenu(name: string, handler: () => void): () => void
+export function onMenu(
+    nameOrHandler: string | ((name: string) => void),
+    maybeHandler?: () => void,
+): () => void {
     if (typeof window === 'undefined') {
         return () => {}
     }
+    // String first arg = filter to that emit name; otherwise a catch-all handler.
+    const filter = typeof nameOrHandler === 'string' ? nameOrHandler : undefined
+    const handler = typeof nameOrHandler === 'string' ? maybeHandler : nameOrHandler
     function listener(event: Event) {
-        handler((event as CustomEvent<{ name: string }>).detail.name)
+        const name = (event as CustomEvent<{ name: string }>).detail.name
+        if (filter === undefined || filter === name) {
+            handler?.(name)
+        }
     }
     window.addEventListener('belte:menu', listener)
     return () => window.removeEventListener('belte:menu', listener)

package/src/lib/bundle/openWebview.ts

@@ -62,8 +62,15 @@ export async function openWebview({
         webview_destroy: { args: [FFIType.ptr], returns: FFIType.void },
     })
 
-    // The second arg is an optional parent window handle; null means a fresh window.
-    const handle = symbols.webview_create(0, null)
+    /*
+    First arg is the webview's `debug` flag: 1 enables the native inspector
+    (WKWebView's Web Inspector, WebView2 DevTools, WebKitGTK inspector) so a JS
+    error on the loaded page — otherwise silent in a bare bundle window — can be
+    read via right-click → Inspect. Gated behind BELTE_INSPECT so release bundles
+    ship without it. The second arg is an optional parent handle; null = fresh window.
+    */
+    const debug = process.env.BELTE_INSPECT ? 1 : 0
+    const handle = symbols.webview_create(debug, null)
     symbols.webview_set_title(handle, cString(title))
     symbols.webview_set_size(handle, width, height, WEBVIEW_HINT_NONE)
     /*

package/src/lib/bundle/signMacApp.ts

@@ -0,0 +1,35 @@
+import { log } from '../shared/log.ts'
+
+/*
+Ad-hoc code-signs an assembled macOS `.app` so it launches on other Macs.
+
+Apple Silicon mandates a valid code signature for every executable. `bun
+build --compile` emits an ad-hoc, linker-signed binary, but assembling the
+`.app` around it (writing Info.plist, dropping in the lib) leaves the bundle
+unsealed — `codesign --verify` then reports the signature as modified, and a
+copy that picks up a quarantine flag (AirDrop, USB, download) gets silently
+killed by Gatekeeper/AMFI: the icon bounces once and nothing opens.
+
+Re-signing inside-out fixes that. Nested Mach-O code (the webview dylib, the
+embedded server binary, the launcher) is signed first, then the bundle as a
+whole, which seals Resources and binds Info.plist. The identity is `-`,
+ad-hoc: no certificate, no Developer account, no network — as far as signing
+goes without a paid Developer ID. Recipients copying a quarantined bundle
+still need `xattr -cr <app>` once, but the app no longer fails to launch.
+
+Best-effort: if `codesign` is missing or fails, warn and return rather than
+abort the bundle, which is otherwise complete and usable on the build host.
+*/
+export async function signMacApp(bundleRoot: string, innerPaths: string[]): Promise<void> {
+    try {
+        // Inner Mach-O code inside-out, then the bundle, which re-signs the
+        // main executable as part of sealing — order matters for nested seals.
+        for (const path of innerPaths) {
+            await Bun.$`codesign --force --sign - ${path}`.quiet()
+        }
+        await Bun.$`codesign --force --sign - ${bundleRoot}`.quiet()
+    } catch (error) {
+        log.warn(`could not code-sign ${bundleRoot} — it may not launch when copied to another Mac`)
+        log.error(error)
+    }
+}

package/src/lib/cli/createClient.ts

@@ -5,7 +5,21 @@ import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
 import { decodeResponse } from '../shared/decodeResponse.ts'
 import type { CliManifest } from './types/CliManifest.ts'
 
-type AnyApi = Record<string, (args?: unknown) => Promise<unknown>>
+/*
+Each property of the client is a callable: invoking it decodes the body
+(plain call), while `.raw(args)` returns the underlying Response without
+decoding or throwing on non-2xx — the escape hatch the CLI uses to sniff
+the Content-Type and stream sse/jsonl bodies frame-by-frame instead of
+buffering through decodeResponse.
+*/
+type ClientInvoker = ((args?: unknown) => Promise<unknown>) & {
+    raw: (args?: unknown) => Promise<Response>
+}
+
+type AnyApi = Record<string, ClientInvoker>
+
+// A command resolved to its HTTP shape — the manifest/registry lookup result.
+type ResolvedCommand = { method: HttpVerb; url: string; accept?: string }
 
 /*
 Builds a typed proxy over the project's RPCs for use in scripts, tests,
@@ -42,35 +56,56 @@ export function createClient<Api extends AnyApi = AnyApi>(opts?: {
     baked-in source of truth); registry is the in-process fallback for
     use in same-project code where defineVerb has run.
     */
-    function resolve(name: string): { method: HttpVerb; url: string } | undefined {
+    function resolve(name: string): ResolvedCommand | undefined {
         const entry = manifest?.[name]
         if (entry) {
-            return { method: entry.method, url: entry.url }
+            return { method: entry.method, url: entry.url, accept: entry.accept }
         }
         const found = findVerbByCommandName(name)
         return found ? { method: found.remote.method, url: found.remote.url } : undefined
     }
 
     /*
-    Single call path for both modes — only the base URL and how the Request
-    is dispatched differ. Remote mode fetches over the network; in-process
-    mode looks the verb up in the registry and runs verb.fetch (no hop).
+    Single dispatch path for both modes — only the base URL and how the
+    Request is sent differ. Remote mode fetches over the network;
+    in-process mode looks the verb up in the registry and runs verb.fetch
+    (no hop). Returns the raw Response; callers decode or stream it.
     */
-    async function call(
-        method: HttpVerb,
-        path: string,
+    function send(
+        resolved: ResolvedCommand,
         args: unknown,
         baseUrl: string,
         dispatch: (request: Request) => Promise<Response>,
-    ): Promise<unknown> {
+    ): Promise<Response> {
         const headers = new Headers()
         if (token) {
             headers.set('authorization', `Bearer ${token}`)
         }
-        const request = buildRpcRequest({ method, url: path, args, baseUrl, headers })
-        const response = await dispatch(request)
+        if (resolved.accept) {
+            headers.set('accept', resolved.accept)
+        }
+        const request = buildRpcRequest({
+            method: resolved.method,
+            url: resolved.url,
+            args,
+            baseUrl,
+            headers,
+        })
+        return dispatch(request)
+    }
+
+    // Decoding plain-call path: throws on non-2xx, returns the decoded body.
+    async function call(
+        resolved: ResolvedCommand,
+        args: unknown,
+        baseUrl: string,
+        dispatch: (request: Request) => Promise<Response>,
+    ): Promise<unknown> {
+        const response = await send(resolved, args, baseUrl, dispatch)
         if (!response.ok) {
-            throw new Error(`${method} ${path} failed: ${response.status} ${response.statusText}`)
+            throw new Error(
+                `${resolved.method} ${resolved.url} failed: ${response.status} ${response.statusText}`,
+            )
         }
         return decodeResponse(response)
     }
@@ -94,10 +129,24 @@ export function createClient<Api extends AnyApi = AnyApi>(opts?: {
     manifest + registry are fixed for a client's lifetime, so a resolved
     invoker (or its absence) never changes.
     */
-    const invokerCache = new Map<string, ((args?: unknown) => Promise<unknown>) | undefined>()
+    const invokerCache = new Map<string, ClientInvoker | undefined>()
+
+    /*
+    Build a memoised invoker for a resolved command. The plain call and
+    `.raw` share one dispatch — remote mode hits the network, in-process
+    mode runs verb.fetch — so the two can't diverge on URL/headers.
+    */
+    function buildInvoker(resolved: ResolvedCommand): ClientInvoker {
+        const baseUrl = url ?? 'http://localhost/'
+        const dispatch = url ? fetch : inProcessDispatch(resolved.url)
+        const invoker = ((args?: unknown) =>
+            call(resolved, args, baseUrl, dispatch)) as ClientInvoker
+        invoker.raw = (args?: unknown) => send(resolved, args, baseUrl, dispatch)
+        return invoker
+    }
 
     return new Proxy({} as Api, {
-        get(_target, prop): ((args?: unknown) => Promise<unknown>) | undefined {
+        get(_target, prop): ClientInvoker | undefined {
             if (typeof prop !== 'string') {
                 return undefined
             }
@@ -105,18 +154,7 @@ export function createClient<Api extends AnyApi = AnyApi>(opts?: {
                 return invokerCache.get(prop)
             }
             const resolved = resolve(prop)
-            const invoker = resolved
-                ? (args?: unknown) =>
-                      url
-                          ? call(resolved.method, resolved.url, args, url, fetch)
-                          : call(
-                                resolved.method,
-                                resolved.url,
-                                args,
-                                'http://localhost/',
-                                inProcessDispatch(resolved.url),
-                            )
-                : undefined
+            const invoker = resolved ? buildInvoker(resolved) : undefined
             invokerCache.set(prop, invoker)
             return invoker
         },

package/src/lib/cli/runCli.ts

@@ -1,9 +1,24 @@
+import { decodeResponse } from '../shared/decodeResponse.ts'
+import { isStreamingResponse } from '../shared/isStreamingResponse.ts'
+import { responseErrorText } from '../shared/responseErrorText.ts'
+import { streamResponse } from '../shared/streamResponse.ts'
 import { createClient } from './createClient.ts'
 import { loadEnvFromBinaryDir } from './loadEnvFromBinaryDir.ts'
 import { parseArgvForRpc } from './parseArgvForRpc.ts'
 import { printCommandHelp, printTopLevelHelp } from './printHelp.ts'
 import type { CliManifest } from './types/CliManifest.ts'
 
+// String results print verbatim (with a trailing newline); everything else as a JSON line.
+function printValue(value: unknown, pretty: boolean): void {
+    if (typeof value === 'string') {
+        process.stdout.write(value.endsWith('\n') ? value : `${value}\n`)
+        return
+    }
+    if (value !== undefined) {
+        process.stdout.write(`${JSON.stringify(value, null, pretty ? 2 : undefined)}\n`)
+    }
+}
+
 /*
 Top-level CLI driver. Loaded by the standalone binary's entry; expects
 the bundler-emitted manifest plus the raw argv tail. The binary is a
@@ -18,9 +33,10 @@ running server over HTTP and APP_URL must be set. Flow:
   5. Otherwise parse the rest of the argv against the manifest entry's
      JSON Schema and dispatch via createClient against APP_URL.
 
-Streaming responses aren't a thing at this layer yet — every RPC tool
-goes through decodeResponse (text/JSON). Streaming verbs (jsonl/sse)
-will be added when the CLI grows watch/publish subcommands for sockets.
+Streaming responses are handled by sniffing the response Content-Type:
+sse/jsonl bodies (a streaming verb, or a socket `tail` command) are
+printed frame-by-frame as NDJSON to stdout; everything else is decoded
+and pretty-printed once.
 */
 export async function runCli({
     programName,
@@ -74,21 +90,27 @@ export async function runCli({
     const appToken = process.env.APP_TOKEN
     const client = createClient({ url: appUrl, token: appToken, manifest })
 
+    const fn = client[first]
+    if (!fn) {
+        console.error(`${programName}: command "${first}" not in client`)
+        return 1
+    }
     try {
-        const fn = (client as Record<string, (args?: unknown) => Promise<unknown>>)[first]
-        if (!fn) {
-            console.error(`${programName}: command "${first}" not in client`)
-            return 1
-        }
-        const result = await fn(args)
-        if (typeof result === 'string') {
-            process.stdout.write(result)
-            if (!result.endsWith('\n')) {
-                process.stdout.write('\n')
+        const response = await fn.raw(args)
+        if (isStreamingResponse(response)) {
+            /*
+            Stream frame-by-frame to stdout as NDJSON. streamResponse
+            throws a clear HttpError on a non-2xx body, caught below.
+            */
+            for await (const frame of streamResponse(response)) {
+                printValue(frame, false)
             }
-        } else if (result !== undefined) {
-            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`)
+            return 0
+        }
+        if (!response.ok) {
+            throw new Error(await responseErrorText(response))
         }
+        printValue(await decodeResponse(response), true)
         return 0
     } catch (error) {
         console.error(`${programName}: ${error instanceof Error ? error.message : String(error)}`)

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)