@abide/abide 0.28.0

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

@@ -0,0 +1,337 @@
+import type { ServerWebSocket } from 'bun'
+import { abideLog } from '../../shared/abideLog.ts'
+import { memoizeByKey } from '../../shared/memoizeByKey.ts'
+import { error } from '../error.ts'
+import { json } from '../json.ts'
+import { sse } from '../sse.ts'
+import { lookupSocket } from './lookupSocket.ts'
+import type { SocketClientFrame } from './types/SocketClientFrame.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+import type { SocketRoutes } from './types/SocketRoutes.ts'
+import type { SocketServerFrame } from './types/SocketServerFrame.ts'
+
+// Reused across every inbound binary frame rather than allocated per message.
+const textDecoder = new TextDecoder()
+
+/* Socket REST-face spans (CLI/MCP tail + publish), opt-in via DEBUG=abide:sockets. */
+const socketsLog = abideLog.channel('abide:sockets')
+
+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>
+}
+
+/*
+Per-connection state: which sockets this ws is currently subscribed to
+(at the Bun-topic level), and which `sub` ids map to which socket. One
+ws can hold multiple subs against the same socket (e.g. one seeded
+from the retained tail, one live-only); the Bun-topic subscription is reference-counted
+so we only `ws.unsubscribe` when the last local sub drops.
+*/
+type ConnectionState = {
+    subToSocket: Map<string, string>
+    socketSubs: Map<string, Set<string>>
+}
+
+/*
+Bridges the framework's socket registry to a single ws per client. All
+sockets multiplex over `/__abide/sockets`. Steady-state fan-out rides
+Bun's native `server.publish('socket:<name>', frame)` so the dispatcher
+is only on the path for sub/unsub bookkeeping and client-initiated pub
+validation; the published `msg` frames go from publisher to subscribers
+without touching JS per frame.
+
+`sub` opens a subscription: the requested slice of the retained tail
+is replayed directly to this ws, then the ws is added to the Bun
+topic. `unsub` drops the local sub and unsubscribes the ws from
+the Bun topic if no other local subs remain. `pub` validates the
+socket's `allowClientPublish` policy and calls `socket.publish` —
+which fans out to in-process iterators and republishes through Bun
+to other connected clients.
+
+Module-level lookups are cached per socket name: loading a socket
+module triggers its `defineSocket` call, which inserts into the
+registry. After that the dispatcher just reads the registry.
+*/
+export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher {
+    const connections = new WeakMap<ServerWebSocket<unknown>, ConnectionState>()
+
+    const ensureLoaded = memoizeByKey((name): Promise<void> | undefined => {
+        const loader = sockets[name]
+        return loader ? loader().then(() => undefined) : undefined
+    })
+
+    /*
+    Loads a socket module on first use and reads its registry entry — the
+    one statement of the load/lookup failure semantics (a throwing module is
+    logged here and stays cached as failed by ensureLoaded). Each face maps
+    the failure kind to its own rendering: sub emits err+end frames, pub
+    drops silently, rest answers with HTTP errors.
+    */
+    async function resolveEntry(
+        name: string,
+    ): Promise<
+        | { entry: SocketRegistryEntry }
+        | { failure: 'unregistered' | 'load-failed' | 'no-export'; message: string }
+    > {
+        const loader = ensureLoaded(name)
+        if (!loader) {
+            return { failure: 'unregistered', message: `[abide] no socket registered at ${name}` }
+        }
+        try {
+            await loader
+        } catch (loadError) {
+            abideLog.error(loadError)
+            return {
+                failure: 'load-failed',
+                message: loadError instanceof Error ? loadError.message : String(loadError),
+            }
+        }
+        const entry = lookupSocket(name)
+        if (!entry) {
+            return {
+                failure: 'no-export',
+                message: `[abide] socket module at ${name} did not register a Socket export`,
+            }
+        }
+        return { entry }
+    }
+
+    function send(ws: ServerWebSocket<unknown>, frame: SocketServerFrame): void {
+        if (ws.readyState !== WebSocket.OPEN) {
+            return
+        }
+        ws.send(JSON.stringify(frame))
+    }
+
+    function addSub(state: ConnectionState, name: string, sub: string): boolean {
+        state.subToSocket.set(sub, name)
+        let subs = state.socketSubs.get(name)
+        if (!subs) {
+            subs = new Set()
+            state.socketSubs.set(name, subs)
+        }
+        const wasEmpty = subs.size === 0
+        subs.add(sub)
+        return wasEmpty
+    }
+
+    function removeSub(state: ConnectionState, sub: string): string | undefined {
+        const name = state.subToSocket.get(sub)
+        if (!name) {
+            return undefined
+        }
+        state.subToSocket.delete(sub)
+        const subs = state.socketSubs.get(name)
+        if (!subs) {
+            return undefined
+        }
+        subs.delete(sub)
+        if (subs.size === 0) {
+            state.socketSubs.delete(name)
+            return name
+        }
+        return undefined
+    }
+
+    async function handleSub(
+        ws: ServerWebSocket<unknown>,
+        state: ConnectionState,
+        frame: Extract<SocketClientFrame, { type: 'sub' }>,
+    ): Promise<void> {
+        // Reject this sub: emit the error then the terminal end frame for its id.
+        function fail(message: string): void {
+            send(ws, { type: 'err', sub: frame.sub, message })
+            send(ws, { type: 'end', sub: frame.sub })
+        }
+        const resolution = await resolveEntry(frame.socket)
+        if ('failure' in resolution) {
+            return fail(resolution.message)
+        }
+        const { entry } = resolution
+        const isFirstLocalSub = addSub(state, frame.socket, frame.sub)
+        if (isFirstLocalSub) {
+            ws.subscribe(`socket:${frame.socket}`)
+        }
+        /*
+        Replay rides one per-sub `replay` frame (sent even when empty), not
+        socket-keyed msg frames: the batch demarcates replay from live for
+        the reader, and the per-sub address keeps this sub's replay out of
+        sibling subs on the same socket. Live messages flow through the Bun
+        topic the ws just joined; a frame published between the join and
+        this snapshot can appear in both, so user payloads should carry an
+        id/timestamp when ordering matters.
+
+        `replay === undefined` means the whole retained tail (`.tail()`
+        no-arg); a number is clamped to the buffer length so the client
+        can ask for "as many as available, up to N" — `0` (bare
+        `for await`) replays nothing.
+        */
+        send(ws, { type: 'replay', sub: frame.sub, messages: entry.snapshotTail(frame.replay) })
+    }
+
+    function handleUnsub(
+        ws: ServerWebSocket<unknown>,
+        state: ConnectionState,
+        frame: Extract<SocketClientFrame, { type: 'unsub' }>,
+    ): void {
+        const emptied = removeSub(state, frame.sub)
+        if (emptied) {
+            ws.unsubscribe(`socket:${emptied}`)
+        }
+        send(ws, { type: 'end', sub: frame.sub })
+    }
+
+    async function handlePub(
+        ws: ServerWebSocket<unknown>,
+        frame: Extract<SocketClientFrame, { type: 'pub' }>,
+    ): Promise<void> {
+        const resolution = await resolveEntry(frame.socket)
+        if ('failure' in resolution) {
+            return
+        }
+        const { entry } = resolution
+        if (!entry.allowClientPublish) {
+            /*
+            Silent drop: the publish is rejected because the topic
+            wasn't declared `{ clientPublish: true }`. Surfacing this as
+            an error per-publish would tempt apps to attempt-then-handle
+            instead of routing through an HTTP route for auth. Log it
+            once per process at debug level (out of scope here) if
+            visibility is needed.
+            */
+            return
+        }
+        /*
+        publish() runs the topic's optional Standard Schema synchronously
+        and throws on failure (see defineSocket.validateSync). The
+        dispatcher invokes us via `void handlePub(...)`, so an unhandled
+        throw would surface as an unhandled promise rejection on every
+        malformed client frame. Catch + log so a buggy client can't take
+        the process down.
+        */
+        try {
+            entry.socket.publish(frame.message)
+        } catch (error) {
+            abideLog.error(error)
+        }
+        /*
+        ws parameter retained for future per-ws auth context (cookies on
+        upgrade) the canPublish hook would consult.
+        */
+        void ws
+    }
+
+    /*
+    HTTP face of the sockets hub at `/__abide/sockets/<name>`, for the CLI
+    and MCP (which can't speak the ws multiplex protocol):
+
+      GET  text/event-stream → live SSE stream; `?tail=N` seeds with the
+           last N retained frames before tailing live (default 0 = live only).
+      GET  otherwise         → JSON array of the retained tail
+           (`?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> {
+        return socketsLog.trace(`socket-rest ${name}`, () => restImpl(req, name))
+    }
+
+    async function restImpl(req: Request, name: string): Promise<Response> {
+        const resolution = await resolveEntry(name)
+        if ('failure' in resolution) {
+            return resolution.failure === 'load-failed'
+                ? error(500, 'socket failed to load')
+                : error(404)
+        }
+        const { entry } = resolution
+        const tailParam = new URL(req.url).searchParams.get('tail')
+        const parsedTail = tailParam !== null ? Number(tailParam) : undefined
+        // A non-numeric ?tail= yields NaN; treat it as absent rather than letting
+        // snapshotTail(NaN)/slice(NaN) leak the whole retained buffer.
+        const count =
+            parsedTail !== undefined && Number.isFinite(parsedTail) ? parsedTail : 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(entry.snapshotTail(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() })
+        },
+
+        message(ws, data) {
+            const state = connections.get(ws)
+            if (!state) {
+                return
+            }
+            const text = typeof data === 'string' ? data : textDecoder.decode(data)
+            let frame: SocketClientFrame
+            try {
+                frame = JSON.parse(text) as SocketClientFrame
+            } catch {
+                return
+            }
+            // JSON.parse succeeds on `null`/`42`/`true`; ignore anything that isn't a frame object.
+            if (typeof frame !== 'object' || frame === null) {
+                return
+            }
+            if (frame.type === 'sub') {
+                void handleSub(ws, state, frame)
+                return
+            }
+            if (frame.type === 'unsub') {
+                handleUnsub(ws, state, frame)
+                return
+            }
+            if (frame.type === 'pub') {
+                void handlePub(ws, frame)
+                return
+            }
+        },
+
+        close(ws) {
+            const state = connections.get(ws)
+            if (!state) {
+                return
+            }
+            connections.delete(ws)
+            for (const name of state.socketSubs.keys()) {
+                ws.unsubscribe(`socket:${name}`)
+            }
+        },
+    }
+}

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

@@ -0,0 +1,179 @@
+import { createPushIterator } from '../../shared/createPushIterator.ts'
+import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
+import { socketTapSlot } from '../../shared/socketTapSlot.ts'
+import type { TailHooks } from '../../shared/types/TailHooks.ts'
+import { getActiveServer } from '../runtime/getActiveServer.ts'
+import { registerSocket } from './registerSocket.ts'
+import type { Socket } from './types/Socket.ts'
+import type { SocketOptions } from './types/SocketOptions.ts'
+
+/*
+Server-side construction of a Socket. The bundler rewrites every
+`export const NAME = socket(opts)` inside `src/server/sockets/<file>.ts` into
+`__abideDefineSocket__("<name>", opts)` so the file path becomes the
+socket's identity. Each subscriber gets its own queue + notifier, the
+optional retained tail is shared, and outbound fan-out rides Bun's
+native `server.publish` so connected ws clients are notified by the
+runtime in C rather than per-client iteration in JS.
+
+The Socket itself is the AsyncIterable: `for await (const m of chat)`
+is the live stream — no replay. `chat.tail(count)` opens a subscription
+seeded with the last `count` retained frames (no-arg = the whole
+retained tail, clamped to the declared `tail` size). When `ttl` is set,
+retained frames older than `ttl` ms are evicted lazily on every
+read/append — no timer runs in the background. `chat.publish(m)` is isomorphic —
+called server-side it both notifies in-process iterators and broadcasts
+to remote subscribers; called client-side (via socketProxy) it sends a
+`pub` frame the dispatcher validates and forwards.
+*/
+// @readme plumbing
+export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<T> {
+    const retention = opts.tail ?? 0
+    const ttl = opts.ttl
+    const schema = opts.schema
+    /*
+    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>()
+    const topic = `socket:${name}`
+
+    /*
+    Retained frames are stored with an expiry timestamp. When `ttl` is set,
+    every read/append starts by dropping leading entries whose expiry has
+    passed — entries are appended in order so the expired prefix is
+    contiguous. No timer/setInterval is needed: expiry is lazy.
+    */
+    function pruneExpired(now: number): void {
+        if (ttl === undefined) {
+            return
+        }
+        let drop = 0
+        for (const entry of buffer) {
+            if (entry.expiresAt !== undefined && entry.expiresAt <= now) {
+                drop++
+            } else {
+                break
+            }
+        }
+        if (drop > 0) {
+            buffer.splice(0, drop)
+        }
+    }
+
+    /*
+    Active server is set once per process during createServer's boot,
+    immediately after Bun.serve resolves, and never reassigned. Resolve
+    it lazily on the first publish then keep the reference so subsequent
+    publishes skip the per-call getter.
+    */
+    let cachedServer: ReturnType<typeof getActiveServer>
+    /*
+    When a schema is attached, publish() validates synchronously and
+    throws on bad payloads. Standard Schema's validate() is generally
+    async — but for the synchronous server-side publish path we treat
+    a Promise return as a programming error (publish must be sync to
+    preserve in-process notify ordering). Schemas that need async
+    refinement should pre-validate at the call site instead.
+    */
+    function validateSync(message: T): T {
+        if (!schema) {
+            return message
+        }
+        const result = schema['~standard'].validate(message)
+        if (result instanceof Promise) {
+            throw new Error(
+                `[abide] socket "${name}" schema returned a Promise — sockets require sync validation`,
+            )
+        }
+        if (result.issues) {
+            throw new Error(
+                `[abide] socket "${name}" publish payload failed validation: ${JSON.stringify(result.issues)}`,
+            )
+        }
+        return result.value as T
+    }
+    function publish(message: T): void {
+        const validated = validateSync(message)
+        if (retention > 0) {
+            const now = Date.now()
+            pruneExpired(now)
+            buffer.push({ value: validated, expiresAt: ttl === undefined ? undefined : now + ttl })
+            if (buffer.length > retention) {
+                buffer.shift()
+            }
+        }
+        for (const notify of subscribers) {
+            notify(validated)
+        }
+        // Observe the fanned-out frame (inspector); no-op when unobserved.
+        socketTapSlot.tap?.({ socket: name, message: validated })
+        if (cachedServer === undefined) {
+            cachedServer = getActiveServer()
+        }
+        const server = cachedServer
+        if (server) {
+            server.publish(topic, JSON.stringify({ type: 'msg', socket: name, message: validated }))
+        }
+    }
+
+    /*
+    replay === 'all' replays the whole retained tail (`.tail()` no-arg);
+    a number replays the last min(count, buffer.length) items — `0` is
+    live-only, the bare `for await` behavior. `hooks.replayed` is queued
+    in-band after the replayed frames so a window reader commits its seed
+    atomically, strictly before any live frame.
+    */
+    function iterate(replay: number | 'all', hooks?: TailHooks): AsyncIterable<T> {
+        return {
+            [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
+                let subscriber: ((message: T) => void) | undefined
+                const iter = createPushIterator<T>(() => {
+                    if (subscriber) {
+                        subscribers.delete(subscriber)
+                    }
+                })
+                pruneExpired(Date.now())
+                const replayCount =
+                    replay === 'all' ? buffer.length : Math.min(replay, buffer.length)
+                if (replayCount > 0) {
+                    const start = buffer.length - replayCount
+                    for (let index = start; index < buffer.length; index++) {
+                        iter.push((buffer[index] as BufferEntry).value)
+                    }
+                }
+                if (hooks?.replayed) {
+                    iter.control(hooks.replayed)
+                }
+                subscriber = (message: T) => iter.push(message)
+                subscribers.add(subscriber)
+                return iter
+            },
+        }
+    }
+
+    const self: Socket<T> = {
+        name,
+        clients,
+        publish,
+        tail: (count?: number, hooks?: TailHooks) => iterate(count ?? 'all', hooks),
+        [Symbol.asyncIterator]: () => iterate(0)[Symbol.asyncIterator](),
+    }
+    registerSocket({
+        socket: self as Socket<unknown>,
+        allowClientPublish: opts.clientPublish ?? false,
+        schema,
+        clients,
+        snapshotTail: (count?: number) => {
+            pruneExpired(Date.now())
+            const start = count === undefined ? 0 : Math.max(0, buffer.length - count)
+            return buffer.slice(start).map((entry) => entry.value)
+        },
+    })
+    return self
+}

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

@@ -0,0 +1,6 @@
+import { socketRegistry } from './socketRegistry.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+export function lookupSocket(name: string): SocketRegistryEntry | undefined {
+    return socketRegistry.get(name)
+}

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

@@ -0,0 +1,6 @@
+import { socketRegistry } from './socketRegistry.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+export function registerSocket(entry: SocketRegistryEntry): void {
+    socketRegistry.set(entry.socket.name, entry)
+}

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

@@ -0,0 +1,36 @@
+import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
+import { SOCKETS_PATH } from '../../shared/SOCKETS_PATH.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 = `${SOCKETS_PATH}/${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/socketRegistry.ts

@@ -0,0 +1,9 @@
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/*
+Process-wide registry of every Socket declared in the app. defineSocket
+inserts on first construction; the dispatcher reads on every `sub` /
+`pub` frame so it can find the right Socket by name and check the
+opted-in `allowClientPublish` policy.
+*/
+export const socketRegistry = new Map<string, SocketRegistryEntry>()

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

@@ -0,0 +1,23 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { TailHooks } from '../../../shared/types/TailHooks.ts'
+
+/*
+Bidirectional named broadcast primitive. Declared once with `socket<T>()`
+inside a file under `src/server/sockets/`; the same import resolves to a server-side
+fan-out and a client-side ws proxy by build target. Iterating the socket
+is the live stream — no replay. `.tail(count)` opens a subscription seeded
+with the last `count` frames of the retained tail (declared via
+`{ tail: n }`; no-arg = the whole retained tail) before going live — the
+optional Subscribable retention capability the reactive `tail()` consumer
+seeds from. `publish` is isomorphic: server code publishes in-process
+and fans out to remote subscribers; client code sends a `pub` frame the
+dispatcher validates against the topic's `clientPublish` flag. `clients`
+exposes which adapter surfaces (browser / mcp / cli) advertise this
+socket.
+*/
+export interface Socket<T> extends AsyncIterable<T> {
+    readonly name: string
+    readonly clients: ClientFlags
+    publish(message: T): void
+    tail(count?: number, hooks?: TailHooks): AsyncIterable<T>
+}

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

@@ -0,0 +1,19 @@
+/*
+Wire frame the browser sends over the multiplexed socket connection.
+`sub` opens a subscription against `socket`. The optional `replay`
+controls seeding from the retained tail: omitted = the whole retained
+tail (`.tail()` no-arg); a number = at most that many trailing frames,
+clamped server-side to what the topic retains — `0` (bare `for await`)
+is live-only. `unsub` closes one. `pub` publishes a message —
+the dispatcher checks the topic's `clientPublish` flag before fanning
+out.
+
+`sub` is the per-subscription id minted client-side; the server treats
+it as opaque and routes inbound `msg|err|end` frames back to the same
+id so one ws can multiplex many subscriptions to the same or different
+sockets.
+*/
+export type SocketClientFrame =
+    | { type: 'sub'; sub: string; socket: string; replay?: number }
+    | { type: 'unsub'; sub: string }
+    | { type: 'pub'; socket: string; message: unknown }

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

@@ -0,0 +1,22 @@
+import type { HttpVerb } from '../../../shared/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: `/__abide/sockets/<name>`.
+    restUrl: string
+    // GET for tail, POST for publish.
+    method: HttpVerb
+}

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

@@ -0,0 +1,26 @@
+import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
+
+/*
+Server-side options passed when declaring a socket via `socket<T>(opts)`.
+`tail` opts the topic into retention: the socket keeps its last `tail`
+frames so readers that weren't there — late joiners, reconnects, the
+CLI/MCP/SSE read surfaces — can seed from `.tail(count)`. Omitted, the
+socket is a pure live pipe and storage is the consumer's concern (a
+`tail(chat, { last: n })` window fills from live frames only). Per-frame
+TTL (retained frames older than `ttl` ms are evicted before replay), and
+the client-publish gate (off by default — server-only topics ignore pub
+frames coming over the wire). Optional Standard Schema validates payloads on
+publish and gives MCP / CLI a typed payload to describe (projected via the
+schema's own `toJSONSchema()` — wrap with withJsonSchema if its library lacks
+one). `clients` controls which non-browser surfaces (mcp / cli) expose this
+socket; browser is the historical default. All server-only state the bundler
+strips out of the client stub.
+*/
+export type SocketOptions<Schema extends StandardSchemaV1 = StandardSchemaV1> = {
+    tail?: number
+    ttl?: number
+    clientPublish?: boolean
+    schema?: Schema
+    clients?: Partial<ClientFlags>
+}