@abide/abide 0.28.0

package/src/lib/mcp/mcpSurface.ts

@@ -0,0 +1,295 @@
+import { promptRegistry } from '../server/prompts/promptRegistry.ts'
+import { dispatchVerbInProcess } from '../server/rpc/dispatchVerbInProcess.ts'
+import { findVerbByCommandName } from '../server/rpc/findVerbByCommandName.ts'
+import { verbRegistry } from '../server/rpc/verbRegistry.ts'
+import { socketOperations } from '../server/sockets/socketOperations.ts'
+import { socketRegistry } from '../server/sockets/socketRegistry.ts'
+import { abideLog } from '../shared/abideLog.ts'
+import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
+import { forwardHeaders } from '../shared/forwardHeaders.ts'
+import { jsonSchemaForSchema } from '../shared/jsonSchemaForSchema.ts'
+import { annotationsForMethod } from './annotationsForMethod.ts'
+import { getMcpResourceServer } from './mcpResourceServerSlot.ts'
+import { toolResultFromResponse } from './toolResultFromResponse.ts'
+import type { McpResourceContents } from './types/McpResourceContents.ts'
+import type { McpResourceDescriptor } from './types/McpResourceDescriptor.ts'
+
+/*
+The app's MCP surface, projected for in-process consumers. This is the single
+source of truth dispatchMcpRequest (the JSON-RPC-over-HTTP transport) and the
+in-app agent loop (abide/server/agent) both build on — the same tool/prompt/
+resource derivation, so a model reaching the app over HTTP and a model driven
+in-process can't drift on what's exposed.
+
+Internal: there is no package export. The public entry is `agent()`, which
+calls `mcpSurface(request)` to hand an engine the gated tool set.
+*/
+
+export type ToolDescriptor = {
+    name: string
+    description: string
+    inputSchema: Record<string, unknown>
+    outputSchema?: Record<string, unknown>
+    annotations?: Record<string, boolean>
+}
+
+export type PromptDescriptor = {
+    name: string
+    description?: string
+    arguments: Array<{ name: string; description?: string; required: boolean }>
+}
+
+// The MCP tools/call result shape (a text content block plus optional structuredContent).
+export type ToolResult = Record<string, unknown>
+
+// A prompt rendered to plain messages — the user turn(s) that seed a conversation.
+export type PromptMessage = { role: 'user'; text: string }
+
+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>
+}
+
+/*
+Builds the array of MCP tool descriptors.
+
+RPCs: every verb with clients.mcp=true becomes one tool named after the
+export's URL (folder segments joined with `-`). The HTTP verb feeds the
+tool's annotations (readOnlyHint / destructiveHint / idempotentHint) so
+a model can tell a read from a write; reads auto-expose while mutating
+verbs require an explicit clients.mcp (see resolveClientFlags). When the
+verb declares an `outputSchema` it's advertised as the tool outputSchema.
+
+Sockets: every socket with clients.mcp=true contributes a `<base>-tail`
+read tool (recent buffered messages) and, when clientPublish is set, a
+`<base>-publish` tool.
+*/
+export function buildTools(): ToolDescriptor[] {
+    const tools: ToolDescriptor[] = []
+    for (const entry of verbRegistry.values()) {
+        if (!entry.clients.mcp) {
+            continue
+        }
+        /*
+        Tool 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.
+        */
+        const inputSchema = jsonSchemaForSchema(entry.inputSchema)
+        const tool: ToolDescriptor = {
+            name: commandNameForUrl(entry.remote.url),
+            description:
+                (inputSchema.description as string | undefined) ??
+                `${entry.remote.method} ${entry.remote.url}`,
+            inputSchema,
+            annotations: annotationsForMethod(entry.remote.method),
+        }
+        if (entry.outputSchema) {
+            tool.outputSchema = jsonSchemaForSchema(entry.outputSchema)
+        }
+        tools.push(tool)
+    }
+    for (const entry of socketRegistry.values()) {
+        if (!entry.clients.mcp) {
+            continue
+        }
+        const payloadSchema = jsonSchemaForSchema(entry.schema)
+        for (const operation of socketOperations(entry)) {
+            if (operation.kind === 'tail') {
+                tools.push({
+                    name: operation.name,
+                    description: `Read recent messages from the "${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 },
+                })
+                continue
+            }
+            tools.push({
+                name: operation.name,
+                description: `Publish a message to the "${operation.socketName}" socket`,
+                inputSchema: payloadSchema,
+                annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+            })
+        }
+    }
+    return tools
+}
+
+/*
+MCP prompts derived from src/mcp/prompts. Arguments come from the JSON
+Schema the resolver built from each prompt's frontmatter `arguments` list
+(top-level properties + required flags); the model fills them in and the
+framework interpolates them into the body on getPrompt.
+*/
+export function buildPrompts(): PromptDescriptor[] {
+    return Array.from(promptRegistry.values()).map((entry) => {
+        const jsonSchema = entry.jsonSchema ?? {}
+        const properties = (jsonSchema.properties ?? {}) as Record<string, { description?: string }>
+        const required = new Set((jsonSchema.required as string[] | undefined) ?? [])
+        return {
+            name: entry.prompt.name,
+            ...(entry.prompt.description ? { description: entry.prompt.description } : {}),
+            arguments: Object.entries(properties).map(([argName, prop]) => ({
+                name: argName,
+                ...(prop?.description ? { description: prop.description } : {}),
+                required: required.has(argName),
+            })),
+        }
+    })
+}
+
+/* MCP tool-dispatch spans, opt-in via DEBUG=abide:mcp — a model's tool call,
+   wrapping the underlying verb dispatch in the same trace. */
+const mcpLog = abideLog.channel('abide:mcp')
+
+function textResult(text: string, isError = false): ToolResult {
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) }
+}
+
+/*
+Dispatches the socket tail / publish tools by matching the tool name
+against each mcp-exposed socket's operations (socketOperations is the same
+projection tools/list advertised, so the publish op only exists when the
+socket allows it). tail returns the retained tail (request/response
+can't hold a live subscription); publish validates against the socket
+schema and fans out. Returns undefined when the name isn't a known socket
+tool so callTool can fall through to "unknown tool".
+*/
+function callSocketTool(
+    toolName: string,
+    args: Record<string, unknown> | undefined,
+): ToolResult | undefined {
+    for (const entry of socketRegistry.values()) {
+        if (!entry.clients.mcp) {
+            continue
+        }
+        const operation = socketOperations(entry).find((op) => op.name === toolName)
+        if (!operation) {
+            continue
+        }
+        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 {
+            // publish() validates the payload against the socket schema and throws on failure.
+            entry.socket.publish(args)
+        } catch (error) {
+            return textResult(error instanceof Error ? error.message : String(error), true)
+        }
+        return textResult('ok')
+    }
+    return undefined
+}
+
+/*
+Tool dispatch. RPC tools synthesize a Request (with forwarded auth
+headers from `inbound`) and pipe it through verb.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.
+Socket tools (`<base>-tail` / `<base>-publish`) fall through to the socket
+dispatcher.
+*/
+export async function callTool(
+    toolName: string,
+    args: Record<string, unknown> | undefined,
+    inbound: Request,
+): Promise<ToolResult> {
+    const entry = findVerbByCommandName(toolName)
+    if (entry) {
+        /* A verb owns this name. If it isn't mcp-exposed it's still unavailable —
+           don't fall through to a socket op that happens to share the name. */
+        if (!entry.clients.mcp) {
+            throw new Error(`unknown tool: ${toolName}`)
+        }
+        const response = await dispatchVerbInProcess({
+            remote: entry.remote,
+            args,
+            baseUrl: `${new URL(inbound.url).origin}/`,
+            headers: forwardHeaders(inbound.headers),
+        })
+        return toolResultFromResponse(response)
+    }
+    const socketResult = callSocketTool(toolName, args)
+    if (socketResult) {
+        return socketResult
+    }
+    throw new Error(`unknown tool: ${toolName}`)
+}
+
+/*
+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>) },
+        ],
+    }
+}
+
+/*
+Projects the app's MCP surface for an in-process consumer bound to `request`
+— tool calls forward that request's auth headers into the verb handler, so
+the model acts with the caller's identity. Used by `agent()`.
+*/
+export function mcpSurface(request: Request): McpSurface {
+    // Built on first read and memoized: an engine that advertises tools but never
+    // reads prompts (or reaches tools over HTTP, reading neither) skips the unused build.
+    let tools: ToolDescriptor[] | undefined
+    let prompts: PromptDescriptor[] | undefined
+    return {
+        get tools() {
+            tools ??= buildTools()
+            return tools
+        },
+        get prompts() {
+            prompts ??= buildPrompts()
+            return prompts
+        },
+        call: (name, args) => mcpLog.trace(`mcp ${name}`, () => callTool(name, args, request)),
+        /* The conversation-seeding messages, without the wire-shape wrapping. */
+        getPrompt: (name, args) => renderPrompt(name, args).messages,
+        async listResources() {
+            const server = getMcpResourceServer()
+            return server ? server.list() : []
+        },
+        async readResource(uri) {
+            const server = getMcpResourceServer()
+            return server ? server.read(uri) : undefined
+        },
+    }
+}

package/src/lib/mcp/toolResultFromResponse.ts

@@ -0,0 +1,66 @@
+import { decodeResponse } from '../shared/decodeResponse.ts'
+import { isStreamingResponse } from '../shared/isStreamingResponse.ts'
+import { responseErrorText } from '../shared/responseErrorText.ts'
+import { streamResponse } from '../shared/streamResponse.ts'
+
+// Frames a value as MCP text content — strings verbatim, everything else as JSON.
+function asText(value: unknown): string {
+    return typeof value === 'string' ? value : JSON.stringify(value)
+}
+
+/*
+Turns an rpc/socket Response into an MCP `tools/call` result. Always
+carries a `text` content block for backward compatibility; adds
+`structuredContent` (an object, per the MCP spec) so models that
+understand structured output get the typed value instead of a stringified
+blob.
+
+  - non-2xx        → { content:[text], isError:true }
+  - sse/jsonl body → drained frame-by-frame; structuredContent = { frames }.
+                     A mid-stream error surfaces as isError with the
+                     frames collected so far.
+  - object body    → structuredContent = the object.
+  - array/primitive → text only (structuredContent must be an object).
+*/
+export async function toolResultFromResponse(response: Response): Promise<Record<string, unknown>> {
+    if (!response.ok) {
+        return {
+            content: [{ type: 'text', text: await responseErrorText(response) }],
+            isError: true,
+        }
+    }
+
+    if (isStreamingResponse(response)) {
+        const frames: unknown[] = []
+        try {
+            for await (const frame of streamResponse(response)) {
+                frames.push(frame)
+            }
+        } catch (error) {
+            return {
+                content: [
+                    { type: 'text', text: frames.map(asText).join('\n') },
+                    {
+                        type: 'text',
+                        text: `stream error: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                structuredContent: { frames },
+                isError: true,
+            }
+        }
+        return {
+            content: [{ type: 'text', text: frames.map(asText).join('\n') }],
+            structuredContent: { frames },
+        }
+    }
+
+    const body = await decodeResponse(response)
+    const result: Record<string, unknown> = {
+        content: [{ type: 'text', text: asText(body) }],
+    }
+    if (body !== null && typeof body === 'object' && !Array.isArray(body)) {
+        result.structuredContent = body
+    }
+    return result
+}

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

@@ -0,0 +1,12 @@
+/*
+JSON-RPC 2.0 request frame as MCP delivers it over Streamable HTTP. The
+`id` is absent for notifications (which we don't currently receive from
+clients but accept silently). `method` is a string like "tools/list" or
+"resources/read".
+*/
+export type JsonRpcRequest = {
+    jsonrpc: '2.0'
+    id?: string | number
+    method: string
+    params?: Record<string, unknown>
+}

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

@@ -0,0 +1,20 @@
+/*
+JSON-RPC 2.0 response frame. Exactly one of `result` / `error` is set
+per request. The `id` echoes the inbound request id (null when the
+request id was malformed and the error is being returned).
+*/
+export type JsonRpcResponse =
+    | {
+          jsonrpc: '2.0'
+          id: string | number | null
+          result: unknown
+      }
+    | {
+          jsonrpc: '2.0'
+          id: string | number | null
+          error: {
+              code: number
+              message: string
+              data?: unknown
+          }
+      }

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

@@ -0,0 +1,10 @@
+/*
+One entry in an MCP resources/read result. Text-typed resources carry `text`;
+everything else carries base64 `blob` — exactly one is present.
+*/
+export type McpResourceContents = {
+    uri: string
+    mimeType: string
+    text?: string
+    blob?: string
+}

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

@@ -0,0 +1,6 @@
+/* One entry in an MCP resources/list result — a file under src/mcp/resources. */
+export type McpResourceDescriptor = {
+    uri: string
+    name: string
+    mimeType: string
+}

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

@@ -0,0 +1,12 @@
+import type { McpResourceContents } from './McpResourceContents.ts'
+import type { McpResourceDescriptor } from './McpResourceDescriptor.ts'
+
+/*
+Serves the project's src/mcp/resources files to the MCP dispatcher. `list`
+backs resources/list; `read` backs resources/read and resolves to undefined
+for an unknown uri.
+*/
+export type McpResourceServer = {
+    list(): Promise<McpResourceDescriptor[]>
+    read(uri: string): Promise<McpResourceContents | undefined>
+}

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

@@ -0,0 +1,9 @@
+/*
+Public shape returned by createMcpServer. The bun route handler at
+/__abide/mcp delegates inbound requests to `handle(request)`, which
+parses the JSON-RPC envelope, dispatches to tools/resources, and returns
+a Response carrying the JSON-RPC reply.
+*/
+export type McpServer = {
+    handle(request: Request): Promise<Response>
+}

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

@@ -0,0 +1,16 @@
+/*
+User-facing options for createMcpServer. All fields optional — the
+zero-arg call works for any abide project (server info is derived from
+package.json by the bundler when MCP is wired into createServer).
+
+- `name` / `version`: identify the server in the MCP `initialize`
+  response. Defaults come from the project's package.json.
+- `authorize`: optional boundary check. Runs once per MCP request before
+  any tool/resource dispatch. Throw HttpError (or any Error) to reject.
+  Per-tool authorization stays in the underlying verb handler.
+*/
+export type McpServerOptions = {
+    name?: string
+    version?: string
+    authorize?: (request: Request) => Promise<void> | void
+}

package/src/lib/server/AppModule.ts

@@ -0,0 +1,47 @@
+import type { Server } from 'bun'
+
+/*
+Optional hooks exported from src/app.ts. All hooks are optional; defaults
+kick in when an export is missing. init returns an optional cleanup
+function that runs on SIGINT/SIGTERM. handle is single-middleware with
+next so user code can mutate the response or branch on the URL.
+
+WebSockets are not exposed here — abide's only native WebSocket
+surface is the sockets hub (see `abide/server/socket`), multiplexed onto a
+single framework-owned connection per client at `/__abide/sockets`.
+Inside request scopes, the live Bun.Server is reachable via the
+exported `server()` function from `abide/server`; `init` receives it
+explicitly because it runs outside a request.
+*/
+// @readme plumbing
+export type AppModule = {
+    /*
+    Extra inbound header names to forward onto in-process rpc Requests, on
+    top of abide's built-in auth/identity set (cookie, authorization, the
+    x-forwarded-* hints). Names a handler reads during SSR or an MCP call
+    that aren't in the default allowlist — e.g. 'accept-language',
+    'x-request-id', a custom 'x-tenant-id'. Case-insensitive.
+    */
+    forwardHeaders?: string[]
+    init?: (ctx: {
+        server: Server<unknown>
+    }) => void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>
+    handle?: (
+        request: Request,
+        next: (req: Request) => Promise<Response>,
+    ) => Promise<Response> | Response
+    handleError?: (error: unknown, request: Request) => Promise<Response> | Response
+    /*
+    App fields merged into the /__abide/health payload the client `health()`
+    polls — e.g. `{ authenticated: await sessionValid(request) }`. Runs ahead
+    of `handle` (the endpoint must answer without auth — reporting
+    "authenticated: false" requires exactly that), so the request arrives
+    unfiltered: cookies are readable, nothing is guaranteed valid. The
+    payload is public and unauthenticated — never put secrets in it. The
+    framework's identity keys (abide/name/version) win on collision; a
+    thrown hook is logged and the base payload still serves, so an app bug
+    can't masquerade as an unreachable server. Keep it cheap: the client
+    probe times out at 5s.
+    */
+    health?: (request: Request) => unknown | Promise<unknown>
+}

package/src/lib/server/DELETE.ts

@@ -0,0 +1,10 @@
+import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import { unprocessed } from './rpc/unprocessed.ts'
+
+/*
+DELETE verb helper. The bundler rewrites every `export const x = DELETE(fn)` inside
+`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+remoteProxy stub (client target). Calling this directly throws.
+*/
+// @readme rpc
+export const DELETE: VerbHelper = (_fn: any, _opts?: any) => unprocessed('DELETE')

package/src/lib/server/GET.ts

@@ -0,0 +1,10 @@
+import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import { unprocessed } from './rpc/unprocessed.ts'
+
+/*
+GET verb helper. The bundler rewrites every `export const x = GET(fn)` inside
+`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+remoteProxy stub (client target). Calling this directly throws.
+*/
+// @readme rpc
+export const GET: VerbHelper = (_fn: any, _opts?: any) => unprocessed('GET')

package/src/lib/server/HEAD.ts

@@ -0,0 +1,10 @@
+import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import { unprocessed } from './rpc/unprocessed.ts'
+
+/*
+HEAD verb helper. The bundler rewrites every `export const x = HEAD(fn)` inside
+`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+remoteProxy stub (client target). Calling this directly throws.
+*/
+// @readme rpc
+export const HEAD: VerbHelper = (_fn: any, _opts?: any) => unprocessed('HEAD')

package/src/lib/server/PATCH.ts

@@ -0,0 +1,10 @@
+import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import { unprocessed } from './rpc/unprocessed.ts'
+
+/*
+PATCH verb helper. The bundler rewrites every `export const x = PATCH(fn)` inside
+`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+remoteProxy stub (client target). Calling this directly throws.
+*/
+// @readme rpc
+export const PATCH: VerbHelper = (_fn: any, _opts?: any) => unprocessed('PATCH')

package/src/lib/server/POST.ts

@@ -0,0 +1,10 @@
+import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import { unprocessed } from './rpc/unprocessed.ts'
+
+/*
+POST verb helper. The bundler rewrites every `export const x = POST(fn)` inside
+`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+remoteProxy stub (client target). Calling this directly throws.
+*/
+// @readme rpc
+export const POST: VerbHelper = (_fn: any, _opts?: any) => unprocessed('POST')

package/src/lib/server/PUT.ts

@@ -0,0 +1,10 @@
+import type { VerbHelper } from './rpc/types/VerbHelper.ts'
+import { unprocessed } from './rpc/unprocessed.ts'
+
+/*
+PUT verb helper. The bundler rewrites every `export const x = PUT(fn)` inside
+`src/server/rpc/<file>.ts` into a defineVerb call (server target) or a
+remoteProxy stub (client target). Calling this directly throws.
+*/
+// @readme rpc
+export const PUT: VerbHelper = (_fn: any, _opts?: any) => unprocessed('PUT')

package/src/lib/server/agent.ts

@@ -0,0 +1,86 @@
+import type { McpSurface } from '../mcp/mcpSurface.ts'
+import { mcpSurface } from '../mcp/mcpSurface.ts'
+import { request } from './request.ts'
+
+/*
+The in-app agent surface. `agent(engine, messages)` runs a model engine
+against the app's own MCP surface and returns the engine's frame stream —
+it does NOT pick a transport. The handler wraps it in `jsonl()` or `sse()`,
+so consumption is the app's choice, same as any other streaming verb:
+
+  // src/server/rpc/chat.ts
+  import { agent } from '@abide/abide/server/agent'
+  import { jsonl } from '@abide/abide/server/jsonl'
+  import { engine } from '@abide/anthropic'
+
+  const chatEngine = engine({ model: 'claude-opus-4-8', apiKey: config.ANTHROPIC_API_KEY })
+  export const chat = POST(({ messages }) => jsonl(agent(chatEngine, messages)), { inputSchema })
+
+The engine — provider-specific, lives in a `@abide/<provider>` package —
+only sees the surface in and yields frames out, so swapping providers never
+touches the verb or the UI.
+
+Permission is decided server-side, not negotiated at runtime: the surface
+is already gated by each verb's `clients.mcp` declaration plus its own
+per-call handler auth, and any provider built-ins (e.g. Claude Code's bash
+tool) are fenced by static rules in the engine's config.
+*/
+
+// A turn in the conversation, provider-neutral. The engine maps these to its provider's wire shape.
+// @readme agent
+export type NeutralMessage =
+    | { role: 'user'; text: string }
+    | {
+          role: 'assistant'
+          text?: string
+          toolUses?: { id: string; name: string; input: unknown }[]
+      }
+    | { role: 'tool'; results: { id: string; content: string; isError?: boolean }[] }
+
+// What the engine streams out; the handler frames it via jsonl()/sse() for the client.
+export type AgentFrame =
+    | { type: 'text'; delta: string }
+    | { type: 'tool_use'; id: string; name: string; input: unknown }
+    | { type: 'tool_result'; id: string; name: string; ok: boolean }
+    /*
+    `stop` is the reason the engine's loop ended. `error` covers an abnormal
+    stop the model didn't choose — a provider error/limit (e.g. Claude Code's
+    max-turns) or the engine's own tool-loop cap — so a client can tell a cut-off
+    answer from a clean `end`.
+    */
+    | {
+          type: 'done'
+          stop: 'end' | 'tool_use' | 'max_tokens' | 'refusal' | 'error'
+      }
+
+// The app's tool/prompt/resource surface handed to an engine (already gated).
+export type AgentSurface = McpSurface
+
+/*
+A model engine: surface + conversation in, frames out. It owns its own loop
+(a raw-model tool loop, or driving a full agent harness) — core only sees
+the frame stream. `origin` lets engines that reach the MCP endpoint over
+HTTP address this server. Implementations live in `@abide/<provider>`
+packages.
+*/
+export type AgentEngine = (input: {
+    surface: AgentSurface
+    messages: NeutralMessage[]
+    origin: string
+}) => AsyncIterable<AgentFrame>
+
+/*
+Runs an engine against the current request's MCP surface and returns its
+AgentFrame stream. Must be called inside a verb's request scope —
+mcpSurface() forwards the caller's auth into every tool dispatch. The
+handler chooses the transport: `jsonl(agent(engine, messages))` or
+`sse(agent(engine, messages))`.
+*/
+export function agent(engine: AgentEngine, messages: NeutralMessage[]): AsyncIterable<AgentFrame> {
+    const inbound = request()
+    return engine({
+        surface: mcpSurface(inbound),
+        messages,
+        origin: new URL(inbound.url).origin,
+    })
+}