@abide/abide 0.28.0

package/src/lib/cli/runSession.ts

@@ -0,0 +1,108 @@
+import { clearLastConnection } from '../shared/clearLastConnection.ts'
+import { connectToServer } from './connectToServer.ts'
+import { dispatchCommand } from './dispatchCommand.ts'
+import { printSessionHelp } from './printSessionHelp.ts'
+import { printSessionStatus } from './printSessionStatus.ts'
+import { printTrimmed } from './printTrimmed.ts'
+import { startLocalInstance } from './startLocalInstance.ts'
+import { tokenizeLine } from './tokenizeLine.ts'
+import type { CliManifest } from './types/CliManifest.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Interactive session (REPL). The banner is printed once by the caller; this prints
+the status line, then loops reading stdin lines via Bun's async-iterable console:
+  - bare words   → dispatch the RPC against the current target
+  - /connect <url>, /start, /disconnect, /help, /clear, /exit → meta commands
+The session owns the current target's child (a local instance) and reaps it when
+the connection is swapped or the loop ends — including on SIGINT.
+*/
+export async function runSession({
+    programName,
+    manifest,
+    footer,
+    target,
+}: {
+    programName: string
+    manifest: CliManifest
+    footer: string
+    target: CliTarget | undefined
+}): Promise<number> {
+    let current = target
+    // Reap any local instance on Ctrl+C — the closure reads the latest `current`.
+    // Named + removed on exit so repeated sessions in one process don't accumulate listeners.
+    const onSigint = () => {
+        current?.child?.kill()
+        process.exit(0)
+    }
+    process.on('SIGINT', onSigint)
+
+    // Swap the active connection: reap the previous local instance (only one runs
+    // at a time), adopt the next target, and reprint the status line.
+    async function swap(next: CliTarget | undefined): Promise<void> {
+        current?.child?.kill()
+        current = next
+        await printSessionStatus(current)
+    }
+
+    await printSessionStatus(current)
+    const promptText = `${programName}> `
+    process.stdout.write(promptText)
+
+    for await (const line of console) {
+        const tokens = tokenizeLine(line.trim())
+        const head = tokens[0]
+        if (head === undefined) {
+            process.stdout.write(promptText)
+            continue
+        }
+        if (head === '/exit' || head === '/quit') {
+            break
+        }
+        if (head === '/clear') {
+            console.clear()
+        } else if (head === '/help') {
+            printSessionHelp(programName, manifest, tokens[1])
+        } else if (head === '/connect') {
+            const url = tokens[1]
+            if (!url) {
+                console.error('/connect requires a url')
+            } else {
+                const next = await connectToServer(programName, url)
+                if (next) {
+                    await swap(next)
+                }
+            }
+        } else if (head === '/start') {
+            try {
+                await swap(await startLocalInstance(programName))
+            } catch (error) {
+                console.error(
+                    `could not start local instance: ${error instanceof Error ? error.message : String(error)}`,
+                )
+            }
+        } else if (head === '/disconnect') {
+            await clearLastConnection(programName)
+            await swap(undefined)
+        } else if (head.startsWith('/')) {
+            console.error(`unknown command "${head}" — /help for the list`)
+        } else if (!current) {
+            console.error('not connected — /connect <url> or /start')
+        } else {
+            await dispatchCommand({
+                programName,
+                manifest,
+                command: head,
+                argvTail: tokens.slice(1),
+                url: current.url,
+                token: current.token,
+            })
+        }
+        process.stdout.write(promptText)
+    }
+
+    process.removeListener('SIGINT', onSigint)
+    current?.child?.kill()
+    printTrimmed(footer)
+    return 0
+}

package/src/lib/cli/startLocalInstance.ts

@@ -0,0 +1,14 @@
+import { spawnEmbeddedServer } from '../bundle/spawnEmbeddedServer.ts'
+import { writeLastConnection } from '../shared/writeLastConnection.ts'
+import type { CliTarget } from './types/CliTarget.ts'
+
+/*
+Boots a local (embedded) instance for this session and records the intent so the
+next bare run resumes a local instance. The caller owns the returned child and
+reaps it on disconnect/exit. Throws if the server crashes before binding.
+*/
+export async function startLocalInstance(programName: string): Promise<CliTarget> {
+    const { url, child } = await spawnEmbeddedServer({ programName })
+    await writeLastConnection(programName, { kind: 'embedded' })
+    return { url, child }
+}

package/src/lib/cli/tokenizeLine.ts

@@ -0,0 +1,51 @@
+/*
+Splits a session input line into argv tokens, honouring single and double quotes
+so values with spaces survive (e.g. `post --title "hello world"`). Quotes group;
+a backslash escapes the next character (outside single quotes). Unterminated
+quotes consume to end of line. Pure; no shell features beyond quoting — no
+globbing, no variable expansion.
+*/
+export function tokenizeLine(line: string): string[] {
+    const tokens: string[] = []
+    let current = ''
+    let hasToken = false
+    let quote: '"' | "'" | undefined
+    for (let index = 0; index < line.length; index++) {
+        const char = line[index]
+        if (char === '\\' && quote !== "'") {
+            const next = line[++index]
+            if (next !== undefined) {
+                current += next
+                hasToken = true
+            }
+            continue
+        }
+        if (quote) {
+            if (char === quote) {
+                quote = undefined
+            } else {
+                current += char
+            }
+            continue
+        }
+        if (char === '"' || char === "'") {
+            quote = char
+            hasToken = true
+            continue
+        }
+        if (char === ' ' || char === '\t') {
+            if (hasToken) {
+                tokens.push(current)
+                current = ''
+                hasToken = false
+            }
+            continue
+        }
+        current += char
+        hasToken = true
+    }
+    if (hasToken) {
+        tokens.push(current)
+    }
+    return tokens
+}

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

@@ -0,0 +1,9 @@
+import type { CliManifestEntry } from './CliManifestEntry.ts'
+
+/*
+Map from rpc export-name (e.g. "getReport") to its manifest entry. Built
+by the bundler from the same verbRegistry MCP consumes; entries are
+emitted only for rpcs with `clients.cli: true`. The CLI binary and any
+programmatic createClient caller read this to dispatch calls.
+*/
+export type CliManifest = Record<string, CliManifestEntry>

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

@@ -0,0 +1,17 @@
+import type { HttpVerb } from '../../shared/types/HttpVerb.ts'
+
+/*
+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). Covers
+both rpcs and socket commands — a socket `tail` is a GET against
+`/__abide/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/cli/types/CliTarget.ts

@@ -0,0 +1,13 @@
+/*
+A resolved CLI connection: the server URL plus an optional bearer token, and the
+child process when this is a locally-spawned instance — the session owns that
+child and reaps it on disconnect/exit.
+*/
+export type CliTarget = {
+    url: string
+    token?: string
+    child?: ReturnType<typeof Bun.spawn>
+    // The app's name from its identity probe, when already fetched while resolving
+    // the target — lets the status line print it without re-probing.
+    name?: string
+}

package/src/lib/mcp/annotationsForMethod.ts

@@ -0,0 +1,29 @@
+import type { HttpVerb } from '../shared/types/HttpVerb.ts'
+
+/*
+Maps an HTTP verb to MCP tool annotations so a model can tell a read from
+a write before calling. Abide 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/createMcpResourceServer.ts

@@ -0,0 +1,102 @@
+// node:fs existsSync — cheap sync presence check, mirrors createPublicAssetServer
+import { existsSync } from 'node:fs'
+import { Glob } from 'bun'
+import { mimeForExtension } from '../server/runtime/mimeForExtension.ts'
+import type { Assets } from '../server/runtime/types/Assets.ts'
+import type { McpResourceContents } from './types/McpResourceContents.ts'
+import type { McpResourceDescriptor } from './types/McpResourceDescriptor.ts'
+import type { McpResourceServer } from './types/McpResourceServer.ts'
+
+/*
+The abide:// URI namespace for file-based resources. A resource's URI is this
+prefix followed by its path relative to src/mcp/resources.
+*/
+const URI_PREFIX = 'abide://resources/'
+
+/*
+MIME essences returned inline as UTF-8 `text` in resources/read; everything
+else is returned as a base64 `blob`. The essence is taken before any `;charset`
+parameter that Bun.file().type appends.
+*/
+function isTextMime(mime: string): boolean {
+    // split() always yields a first element; the '' default exists for noUncheckedIndexedAccess in consumer tsconfigs.
+    const essence = (mime.split(';')[0] ?? '').trim()
+    return (
+        essence.startsWith('text/') ||
+        essence === 'application/json' ||
+        essence === 'application/xml' ||
+        essence === 'image/svg+xml' ||
+        essence.endsWith('+json') ||
+        essence.endsWith('+xml')
+    )
+}
+
+function descriptorFor(relativePath: string): McpResourceDescriptor {
+    return {
+        uri: `${URI_PREFIX}${relativePath}`,
+        name: relativePath,
+        mimeType: mimeForExtension(relativePath),
+    }
+}
+
+function contentsFor(relativePath: string, bytes: Uint8Array): McpResourceContents {
+    const mimeType = mimeForExtension(relativePath)
+    const uri = `${URI_PREFIX}${relativePath}`
+    if (isTextMime(mimeType)) {
+        return { uri, mimeType, text: new TextDecoder().decode(bytes) }
+    }
+    return { uri, mimeType, blob: bytes.toBase64() }
+}
+
+/*
+Serves files under src/mcp/resources as MCP resources. Two sources, picked at
+construction (mirrors createPublicAssetServer):
+  - `mcpResources` (standalone compile): a map of relative-path → gzip bytes
+    embedded into the binary.
+  - `resourcesDir` on disk (dev + `abide start`): files read straight from
+    `${cwd}/src/mcp/resources`.
+*/
+export function createMcpResourceServer({
+    resourcesDir,
+    mcpResources,
+}: {
+    resourcesDir: string
+    mcpResources?: Assets
+}): McpResourceServer {
+    return {
+        async list(): Promise<McpResourceDescriptor[]> {
+            if (mcpResources) {
+                return Object.keys(mcpResources).map(descriptorFor)
+            }
+            if (!existsSync(resourcesDir)) {
+                return []
+            }
+            const files = await Array.fromAsync(
+                new Glob('**/*').scan({ cwd: resourcesDir, onlyFiles: true }),
+            )
+            return files.map(descriptorFor)
+        },
+        async read(uri: string): Promise<McpResourceContents | undefined> {
+            if (!uri.startsWith(URI_PREFIX)) {
+                return undefined
+            }
+            const relativePath = uri.slice(URI_PREFIX.length)
+            // reject `..` traversal in the requested uri before any disk read
+            if (relativePath.split('/').includes('..')) {
+                return undefined
+            }
+            if (mcpResources) {
+                const compressed = mcpResources[relativePath]
+                if (!compressed) {
+                    return undefined
+                }
+                return contentsFor(relativePath, Bun.gunzipSync(compressed))
+            }
+            const file = Bun.file(`${resourcesDir}/${relativePath}`)
+            if (!(await file.exists())) {
+                return undefined
+            }
+            return contentsFor(relativePath, await file.bytes())
+        },
+    }
+}

package/src/lib/mcp/createMcpServer.ts

@@ -0,0 +1,48 @@
+import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
+import { TEXT_PLAIN } from '../shared/TEXT_PLAIN.ts'
+import { dispatchMcpRequest } from './dispatchMcpRequest.ts'
+import type { McpServer } from './types/McpServer.ts'
+import type { McpServerOptions } from './types/McpServerOptions.ts'
+
+const DEFAULT_NAME = 'abide-app'
+const DEFAULT_VERSION = '0.0.0'
+
+/*
+Constructs an MCP server bound to the project's rpc registry. Returns an
+object whose `handle(request)` is the function the bun route at
+/__abide/mcp invokes. Framework-internal — the abide:mcp virtual
+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 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.
+*/
+// @readme plumbing
+export function createMcpServer(opts: McpServerOptions = {}): McpServer {
+    const serverInfo = {
+        name: opts.name ?? DEFAULT_NAME,
+        version: opts.version ?? DEFAULT_VERSION,
+    }
+    return {
+        async handle(request: Request): Promise<Response> {
+            if (request.method !== 'POST') {
+                return new Response('Method Not Allowed', {
+                    status: 405,
+                    headers: {
+                        Allow: 'POST',
+                        'Content-Type': TEXT_PLAIN,
+                        'Cache-Control': NO_STORE,
+                    },
+                })
+            }
+            const envelope = await dispatchMcpRequest(request, opts, serverInfo)
+            return Response.json(envelope, { headers: { 'Cache-Control': NO_STORE } })
+        },
+    }
+}

package/src/lib/mcp/dispatchMcpRequest.ts

@@ -0,0 +1,138 @@
+import { ensureRegistriesLoaded } from '../server/runtime/registryManifests.ts'
+import { getMcpResourceServer } from './mcpResourceServerSlot.ts'
+import { buildPrompts, buildTools, callTool, renderPrompt } from './mcpSurface.ts'
+import type { JsonRpcRequest } from './types/JsonRpcRequest.ts'
+import type { JsonRpcResponse } from './types/JsonRpcResponse.ts'
+import type { McpServerOptions } from './types/McpServerOptions.ts'
+
+const PROTOCOL_VERSION = '2025-06-18'
+
+function jsonRpcError(
+    id: string | number | null,
+    code: number,
+    message: string,
+    data?: unknown,
+): JsonRpcResponse {
+    return { jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } }
+}
+
+function jsonRpcOk(id: string | number | null, result: unknown): JsonRpcResponse {
+    return { jsonrpc: '2.0', id, result }
+}
+
+/*
+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. (The in-process agent
+loop reaches the same prompts via mcpSurface().getPrompt, which returns
+plain messages rather than this wire shape.)
+*/
+function getPrompt(
+    name: string,
+    args: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+    const { description, messages } = renderPrompt(name, args)
+    return {
+        ...(description ? { description } : {}),
+        messages: messages.map((message) => ({
+            role: message.role,
+            content: { type: 'text', text: message.text },
+        })),
+    }
+}
+
+/*
+Parses a single JSON-RPC envelope and dispatches by method. Errors
+become JSON-RPC error responses (the HTTP layer always returns 200 with
+an envelope for JSON-RPC over HTTP; transport errors are different). The
+tool/prompt derivation and tool dispatch live in mcpSurface — the same
+projection the in-process agent loop builds on.
+*/
+export async function dispatchMcpRequest(
+    request: Request,
+    opts: McpServerOptions,
+    serverInfo: { name: string; version: string },
+): Promise<JsonRpcResponse> {
+    let envelope: JsonRpcRequest
+    try {
+        envelope = (await request.clone().json()) as JsonRpcRequest
+    } catch {
+        return jsonRpcError(null, -32700, 'Parse error')
+    }
+    const id = envelope.id ?? null
+    if (envelope.jsonrpc !== '2.0' || typeof envelope.method !== 'string') {
+        return jsonRpcError(id, -32600, 'Invalid Request')
+    }
+
+    if (opts.authorize) {
+        try {
+            await opts.authorize(request)
+        } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            return jsonRpcError(id, -32001, message)
+        }
+    }
+
+    try {
+        await ensureRegistriesLoaded()
+        switch (envelope.method) {
+            case 'initialize':
+                return jsonRpcOk(id, {
+                    protocolVersion: PROTOCOL_VERSION,
+                    capabilities: {
+                        tools: { listChanged: false },
+                        prompts: { listChanged: false },
+                        resources: { listChanged: false },
+                    },
+                    serverInfo,
+                })
+            case 'ping':
+                return jsonRpcOk(id, {})
+            case 'tools/list':
+                return jsonRpcOk(id, { tools: buildTools() })
+            case 'tools/call': {
+                const params = envelope.params as
+                    | { name?: string; arguments?: Record<string, unknown> }
+                    | undefined
+                if (!params?.name) {
+                    return jsonRpcError(id, -32602, 'Missing tool name')
+                }
+                return jsonRpcOk(id, await callTool(params.name, params.arguments, request))
+            }
+            case 'resources/list': {
+                const resourceServer = getMcpResourceServer()
+                return jsonRpcOk(id, {
+                    resources: resourceServer ? await resourceServer.list() : [],
+                })
+            }
+            case 'resources/read': {
+                const params = envelope.params as { uri?: string } | undefined
+                if (!params?.uri) {
+                    return jsonRpcError(id, -32602, 'Missing resource uri')
+                }
+                const resourceServer = getMcpResourceServer()
+                const contents = resourceServer ? await resourceServer.read(params.uri) : undefined
+                if (!contents) {
+                    return jsonRpcError(id, -32602, `unknown resource: ${params.uri}`)
+                }
+                return jsonRpcOk(id, { contents: [contents] })
+            }
+            case 'prompts/list':
+                return jsonRpcOk(id, { prompts: buildPrompts() })
+            case 'prompts/get': {
+                const params = envelope.params as
+                    | { name?: string; arguments?: Record<string, unknown> }
+                    | undefined
+                if (!params?.name) {
+                    return jsonRpcError(id, -32602, 'Missing prompt name')
+                }
+                return jsonRpcOk(id, getPrompt(params.name, params.arguments))
+            }
+            default:
+                return jsonRpcError(id, -32601, `Method not found: ${envelope.method}`)
+        }
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        return jsonRpcError(id, -32603, message)
+    }
+}

package/src/lib/mcp/mcpResourceServerSlot.ts

@@ -0,0 +1,18 @@
+import type { McpResourceServer } from './types/McpResourceServer.ts'
+
+/*
+Process-wide slot for the MCP resource server. createServer assigns it at
+boot; dispatchMcpRequest reads it on resources/list + resources/read. Mirrors
+the registryManifests slot — the default MCP server is constructed in the
+abide:mcp virtual with no args, so the resource server (which needs the
+project's resourcesDir + embedded map) is injected out of band.
+*/
+let resourceServer: McpResourceServer | undefined
+
+export function setMcpResourceServer(value: McpResourceServer): void {
+    resourceServer = value
+}
+
+export function getMcpResourceServer(): McpResourceServer | undefined {
+    return resourceServer
+}