@abide/abide 0.46.0 → 0.47.0

package/src/lib/mcp/mcpTools.ts

@@ -0,0 +1,187 @@
+import { dispatchRpcInProcess } from '../server/rpc/dispatchRpcInProcess.ts'
+import { rpcRegistry } from '../server/rpc/rpcRegistry.ts'
+import type { RpcRegistryEntry } from '../server/rpc/types/RpcRegistryEntry.ts'
+import { socketOperations } from '../server/sockets/socketOperations.ts'
+import { socketRegistry } from '../server/sockets/socketRegistry.ts'
+import type { SocketOperation } from '../server/sockets/types/SocketOperation.ts'
+import type { SocketRegistryEntry } from '../server/sockets/types/SocketRegistryEntry.ts'
+import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
+import { forwardHeaders } from '../shared/forwardHeaders.ts'
+import { jsonSchemaForSchema } from '../shared/jsonSchemaForSchema.ts'
+import { messageFromError } from '../shared/messageFromError.ts'
+import { annotationsForMethod } from './annotationsForMethod.ts'
+import { toolResultFromResponse } from './toolResultFromResponse.ts'
+import type { ToolDescriptor } from './types/ToolDescriptor.ts'
+import type { ToolResult } from './types/ToolResult.ts'
+
+/*
+One MCP-exposed tool, resolved from the live registries: an rpc, or one of a
+socket's operations. The ref carries the tool's identity (name) plus the
+registry entry it projects from; the descriptor and the dispatch below are two
+renderings of the same ref, so tools/list and tools/call can't disagree on
+which tools exist or what they're called.
+*/
+type McpToolRef =
+    | { kind: 'rpc'; name: string; entry: RpcRegistryEntry }
+    | { kind: 'socket'; name: string; entry: SocketRegistryEntry; operation: SocketOperation }
+
+/*
+Enumerates the MCP tool namespace — the single decision of which tools exist.
+RPCs with clients.mcp=true become one tool named after the export's URL
+(folder segments joined with `-`; reads auto-expose while mutating rpcs
+require an explicit clients.mcp — see resolveClientFlags). Sockets with
+clients.mcp=true contribute a `<base>-tail` read tool and, when clientPublish
+is set, a `<base>-publish` tool (existence + naming live in socketOperations).
+RPCs enumerate first, so on a name collision the rpc tool wins.
+*/
+function mcpToolRefs(): McpToolRef[] {
+    const refs: McpToolRef[] = []
+    for (const entry of rpcRegistry.values()) {
+        if (!entry.clients.mcp) {
+            continue
+        }
+        refs.push({ kind: 'rpc', name: commandNameForUrl(entry.remote.url), entry })
+    }
+    for (const entry of socketRegistry.values()) {
+        if (!entry.clients.mcp) {
+            continue
+        }
+        for (const operation of socketOperations(entry)) {
+            refs.push({ kind: 'socket', name: operation.name, entry, operation })
+        }
+    }
+    return refs
+}
+
+/*
+The advertised face of one tool. An rpc tool's description favours the
+schema's top-level description (the vendor's JSON Schema conversion carries
+`.describe(...)` through), falling back to `method url` so the tool is still
+labelled when the schema has none; the HTTP method feeds the annotations
+(readOnlyHint / destructiveHint / idempotentHint) so a model can tell a read
+from a write.
+*/
+function describeTool(ref: McpToolRef): ToolDescriptor {
+    if (ref.kind === 'rpc') {
+        const inputSchema = jsonSchemaForSchema(ref.entry.inputSchema)
+        const tool: ToolDescriptor = {
+            name: ref.name,
+            description:
+                (inputSchema.description as string | undefined) ??
+                `${ref.entry.remote.method} ${ref.entry.remote.url}`,
+            inputSchema,
+            annotations: annotationsForMethod(ref.entry.remote.method),
+        }
+        if (ref.entry.outputSchema) {
+            tool.outputSchema = jsonSchemaForSchema(ref.entry.outputSchema)
+        }
+        return tool
+    }
+    const payloadSchema = jsonSchemaForSchema(ref.entry.schema)
+    if (ref.operation.kind === 'tail') {
+        return {
+            name: ref.name,
+            description: `Read recent messages from the "${ref.operation.socketName}" socket`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    count: { type: 'number', description: 'max recent messages to return' },
+                },
+            },
+            outputSchema: {
+                type: 'object',
+                properties: { frames: { type: 'array', items: payloadSchema } },
+            },
+            annotations: { readOnlyHint: true, destructiveHint: false },
+        }
+    }
+    return {
+        name: ref.name,
+        description: `Publish a message to the "${ref.operation.socketName}" socket`,
+        inputSchema: payloadSchema,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+    }
+}
+
+function textResult(text: string, isError = false): ToolResult {
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) }
+}
+
+/*
+Dispatches an rpc tool by synthesizing a Request (with forwarded auth headers
+from `inbound`) and piping it through rpc.fetch inside the request scope — the
+same seam the HTTP router crosses, so validation, the handler, and the
+request-scoped helpers (per-call cache(), cookies(), request()) behave
+identically. A handler throw is caught by the scope and framed as an isError
+tool result (via the 500 response) rather than escaping. The response
+(buffered or streaming) is framed by toolResultFromResponse.
+*/
+async function callRpcTool(
+    entry: RpcRegistryEntry,
+    args: Record<string, unknown> | undefined,
+    inbound: Request,
+): Promise<ToolResult> {
+    const response = await dispatchRpcInProcess({
+        remote: entry.remote,
+        args,
+        baseUrl: `${new URL(inbound.url).origin}/`,
+        headers: forwardHeaders(inbound.headers),
+    })
+    return toolResultFromResponse(response)
+}
+
+/*
+Dispatches a socket tool. tail returns the retained tail (request/response
+can't hold a live subscription); publish validates against the socket schema
+and fans out.
+*/
+function callSocketTool(
+    entry: SocketRegistryEntry,
+    operation: SocketOperation,
+    args: Record<string, unknown> | undefined,
+): Promise<ToolResult> | ToolResult {
+    if (operation.kind === 'tail') {
+        const count = typeof args?.count === 'number' ? args.count : undefined
+        const frames = entry.snapshotTail(count)
+        return {
+            content: [{ type: 'text', text: frames.map((f) => JSON.stringify(f)).join('\n') }],
+            structuredContent: { frames },
+        }
+    }
+    try {
+        // broadcast() validates the payload against the socket schema and throws on failure.
+        entry.socket.broadcast(args)
+    } catch (error) {
+        return textResult(messageFromError(error), true)
+    }
+    return textResult('ok')
+}
+
+/*
+The MCP tool surface: what tools/list advertises and what tools/call runs.
+Both faces render from mcpToolRefs — the tool namespace is decided once, so
+everything advertised is callable and everything callable is advertised.
+list() is the only face that builds descriptors (schema projection is
+per-call work dispatch never pays). Read at call time (not cached) so rpcs
+constructed after boot show up, matching the other registry projections.
+*/
+export const mcpTools = {
+    list(): ToolDescriptor[] {
+        return mcpToolRefs().map(describeTool)
+    },
+    async call(
+        toolName: string,
+        args: Record<string, unknown> | undefined,
+        inbound: Request,
+    ): Promise<ToolResult> {
+        for (const ref of mcpToolRefs()) {
+            if (ref.name !== toolName) {
+                continue
+            }
+            return ref.kind === 'rpc'
+                ? callRpcTool(ref.entry, args, inbound)
+                : callSocketTool(ref.entry, ref.operation, args)
+        }
+        throw new Error(`unknown tool: ${toolName}`)
+    },
+}

package/src/lib/mcp/renderPrompt.ts

@@ -0,0 +1,25 @@
+import { promptRegistry } from '../server/prompts/promptRegistry.ts'
+import type { PromptMessage } from './types/PromptMessage.ts'
+
+/*
+Renders a prompt: looks it up, interpolates the caller's args, and returns its
+optional description plus the message(s) that seed a conversation. A markdown
+prompt is a single user turn whose text is the interpolated template. Throws on
+an unknown prompt name. The one place prompt rendering lives — dispatchMcpRequest
+wraps this in the prompts/get wire shape, the agent loop reads the messages plain.
+*/
+export function renderPrompt(
+    name: string,
+    args?: Record<string, unknown>,
+): { description?: string; messages: PromptMessage[] } {
+    const entry = promptRegistry.get(name)
+    if (!entry) {
+        throw new Error(`unknown prompt: ${name}`)
+    }
+    return {
+        ...(entry.prompt.description ? { description: entry.prompt.description } : {}),
+        messages: [
+            { role: 'user', text: entry.prompt.render((args ?? {}) as Record<string, string>) },
+        ],
+    }
+}

package/src/lib/mcp/types/McpSurface.ts

@@ -0,0 +1,15 @@
+import type { McpResourceContents } from './McpResourceContents.ts'
+import type { McpResourceDescriptor } from './McpResourceDescriptor.ts'
+import type { PromptDescriptor } from './PromptDescriptor.ts'
+import type { PromptMessage } from './PromptMessage.ts'
+import type { ToolDescriptor } from './ToolDescriptor.ts'
+import type { ToolResult } from './ToolResult.ts'
+
+export type McpSurface = {
+    tools: ToolDescriptor[]
+    call(name: string, args: Record<string, unknown> | undefined): Promise<ToolResult>
+    prompts: PromptDescriptor[]
+    getPrompt(name: string, args?: Record<string, unknown>): PromptMessage[]
+    listResources(): Promise<McpResourceDescriptor[]>
+    readResource(uri: string): Promise<McpResourceContents | undefined>
+}

package/src/lib/mcp/types/PromptDescriptor.ts

@@ -0,0 +1,5 @@
+export type PromptDescriptor = {
+    name: string
+    description?: string
+    arguments: Array<{ name: string; description?: string; required: boolean }>
+}

package/src/lib/mcp/types/PromptMessage.ts

@@ -0,0 +1,2 @@
+// A prompt rendered to plain messages — the user turn(s) that seed a conversation.
+export type PromptMessage = { role: 'user'; text: string }

package/src/lib/mcp/types/ToolDescriptor.ts

@@ -0,0 +1,7 @@
+export type ToolDescriptor = {
+    name: string
+    description: string
+    inputSchema: Record<string, unknown>
+    outputSchema?: Record<string, unknown>
+    annotations?: Record<string, boolean>
+}

package/src/lib/mcp/types/ToolResult.ts

@@ -0,0 +1,2 @@
+// The MCP tools/call result shape (a text content block plus optional structuredContent).
+export type ToolResult = Record<string, unknown>

package/src/lib/server/agent.ts

@@ -1,5 +1,5 @@
-import type { McpSurface } from '../mcp/mcpSurface.ts'
 import { mcpSurface } from '../mcp/mcpSurface.ts'
+import type { McpSurface } from '../mcp/types/McpSurface.ts'
 import { request } from './request.ts'
 
 /*

package/src/lib/server/jsonl.ts

@@ -31,7 +31,7 @@ import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
 export function jsonl<Frame>(
     iterable: AsyncIterable<Frame>,
     init?: ResponseInit,
-): TypedResponse<Frame> {
+): TypedResponse<AsyncIterable<Frame>> {
     const body = streamFromIterator(iterable, {
         encodeFrame: (value) => `${JSON.stringify(value)}\n`,
         encodeError: (message) => jsonlErrorFrame.encode(message),
@@ -43,5 +43,5 @@ export function jsonl<Frame>(
             'Cache-Control': NO_STORE,
             'X-Content-Type-Options': 'nosniff',
         }),
-    ) as TypedResponse<Frame>
+    ) as TypedResponse<AsyncIterable<Frame>>
 }

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

@@ -64,6 +64,10 @@ export function defineRpc<Args, Return>(
            parked write drains on `rpc.outbox.retry()` (no auto-drain). Mutating methods
            only. */
         outbox?: boolean
+        /* Handler returns jsonl()/sse(): the bare call returns the Subscribable directly (for
+           isomorphic `for await (… of fn(args))` in server code). Bundler-stamped; the router's
+           wire path (.fetch) is unaffected. */
+        streaming?: boolean
     },
 ): RemoteFunction<Args, Return> {
     /* `outbox: true` is a mutation contract — a read RPC has nothing to durably deliver,
@@ -183,6 +187,7 @@ export function defineRpc<Args, Return>(
         method,
         url,
         clients,
+        streaming: opts?.streaming ?? false,
         crossOrigin: opts?.crossOrigin,
         buildRequest,
         invoke,

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

@@ -1,37 +1,41 @@
 /*
-Inspects the raw request URL (not the parsed pathname) for path-traversal
-patterns. The WHATWG URL parser decodes `%2E%2E` to `..` and then collapses
-dot-segments out of the pathname during normalization, so by the time
-`url.pathname` is observable any encoded traversal has been masked. The
-remaining literal `..` check guards against any future URL-parser quirk
+Inspects the raw request URL's PATH portion (not the parsed pathname) for
+path-traversal patterns. The WHATWG URL parser decodes `%2E%2E` to `..` and
+then collapses dot-segments out of the pathname during normalization, so by
+the time `url.pathname` is observable any encoded traversal has been masked.
+The remaining literal `..` check guards against any future URL-parser quirk
 that lets a normalised path through.
 
+Only the path is scanned — an encoded slash or backslash in a QUERY value
+(`/logo.png?from=%2Fblog`) is legitimate and must not 404 a real asset.
+
 Hot path early-out: if none of the suspect substrings appear in the raw
-URL we never lowercase the whole string nor walk segments.
+path we never lowercase it nor walk segments.
 */
 export function containsTraversal(rawUrl: string): boolean {
-    if (rawUrl.includes('\\')) {
+    const rawPath = rawPathPortion(rawUrl)
+    if (rawPath.includes('\\')) {
         return true
     }
-    if (rawUrl.includes('..') && segmentContainsDotDot(rawUrl)) {
+    if (rawPath.includes('..') && rawPath.split('/').some((segment) => segment === '..')) {
         return true
     }
-    if (rawUrl.indexOf('%') === -1) {
+    if (rawPath.indexOf('%') === -1) {
         return false
     }
-    const lower = rawUrl.toLowerCase()
+    const lower = rawPath.toLowerCase()
     return lower.includes('%2e%2e') || lower.includes('%2f') || lower.includes('%5c')
 }
 
-function segmentContainsDotDot(rawUrl: string): boolean {
+/* The raw path of an absolute request URL: first `/` after the authority up
+   to the query. Requests never carry a fragment, so `?` is the only cutoff. */
+function rawPathPortion(rawUrl: string): string {
     const queryStart = rawUrl.indexOf('?')
     const pathEnd = queryStart === -1 ? rawUrl.length : queryStart
-    const pathStart = rawUrl.indexOf('/', rawUrl.indexOf('://') + 3)
+    const schemeEnd = rawUrl.indexOf('://')
+    const pathStart = rawUrl.indexOf('/', schemeEnd === -1 ? 0 : schemeEnd + 3)
     if (pathStart === -1 || pathStart >= pathEnd) {
-        return false
+        return ''
     }
-    return rawUrl
-        .slice(pathStart, pathEnd)
-        .split('/')
-        .some((segment) => segment === '..')
+    return rawUrl.slice(pathStart, pathEnd)
 }

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

@@ -48,12 +48,16 @@ export async function createAppAssetServer({
         [...diskPaths].filter((path) => path.endsWith('.gz')).map((path) => path.slice(0, -3)),
     )
 
+    // Fresh 404 per call — a Response body is single-use, so it can't be hoisted to a const.
+    const notFound = (): Response =>
+        new Response('Not Found', {
+            status: 404,
+            headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
+        })
+
     return async function serveAppAsset(req, url) {
         if (containsTraversal(req.url)) {
-            return new Response('Not Found', {
-                status: 404,
-                headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-            })
+            return notFound()
         }
         /* Embed map and gzip Set hold decoded filesystem names; url.pathname stays
            percent-encoded — decode so a chunk/asset with a non-ASCII name matches and
@@ -62,10 +66,7 @@ export async function createAppAssetServer({
         try {
             assetPath = decodeURIComponent(url.pathname)
         } catch {
-            return new Response('Not Found', {
-                status: 404,
-                headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-            })
+            return notFound()
         }
         if (assets) {
             const compressed = assets[assetPath]
@@ -73,10 +74,7 @@ export async function createAppAssetServer({
                (request-controlled) pathnames, so building bundles for junk
                `/_app/*` probes would grow it without bound. */
             if (!compressed) {
-                return new Response('Not Found', {
-                    status: 404,
-                    headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-                })
+                return notFound()
             }
             return respondWithEmbeddedAsset(
                 compressed,
@@ -87,10 +85,7 @@ export async function createAppAssetServer({
         /* Miss-check before header work so probes for non-existent chunks can't grow the
            header cache (the embed branch above guards the same way). */
         if (!diskPaths.has(assetPath)) {
-            return new Response('Not Found', {
-                status: 404,
-                headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE },
-            })
+            return notFound()
         }
         const { base: baseHeaders, gzip: gzipHeaders } = headersForAsset(assetPath)
         const diskPath = distDir + assetPath