@abide/claude-code 0.5.4

package/bin/cli.ts

@@ -0,0 +1,56 @@
+#!/usr/bin/env bun
+import { CAPABILITY_TOOLS } from '../src/CAPABILITY_TOOLS.ts'
+import { launch } from '../src/launch.ts'
+import type { PermissionMode } from '../src/PermissionMode.ts'
+import { serve } from '../src/serve.ts'
+
+/* Local abide dev server default — mirrors abide's DEFAULT_PORT. The package owns
+its own default so it needs no internal abide import. */
+const DEFAULT_APP_PORT = 3000
+
+const [, , command, ...rest] = process.argv
+
+// Reads `--name=value` or `--name value` from argv.
+function parseFlag(name: string): string | undefined {
+    const prefix = `--${name}=`
+    const match = rest.find((arg) => arg.startsWith(prefix))
+    if (match) {
+        return match.slice(prefix.length)
+    }
+    const index = rest.indexOf(`--${name}`)
+    if (index !== -1 && index + 1 < rest.length) {
+        return rest[index + 1]
+    }
+    return undefined
+}
+
+const url = parseFlag('url') ?? `http://localhost:${DEFAULT_APP_PORT}`
+const mcpToken = parseFlag('mcp-token')
+
+if (command === 'serve') {
+    const port = parseFlag('port')
+    /* Each `--allow <capability>` maps to the one built-in tool it enables, via
+    the closed CAPABILITY_TOOLS vocabulary — an unknown capability resolves to no
+    tool, so the page can never widen this set. */
+    const tools = rest
+        .map((arg, index) =>
+            arg === '--allow'
+                ? CAPABILITY_TOOLS[rest[index + 1] as keyof typeof CAPABILITY_TOOLS]
+                : undefined,
+        )
+        .filter((tool) => tool !== undefined)
+    const server = serve({
+        url,
+        port: port ? Number(port) : undefined,
+        token: parseFlag('token'),
+        mcpToken,
+        tools,
+        // End the process once the page goes away (a reload reconnects within the grace).
+        onIdle: () => process.exit(0),
+    })
+    console.error(`abide assistant bridge on http://127.0.0.1:${server.port} -> ${url}`)
+} else {
+    // Default action: the interactive TUI against the local (or --url) app.
+    const permissionMode = parseFlag('permission-mode') as PermissionMode | undefined
+    await launch({ url, mcpToken, ...(permissionMode ? { permissionMode } : {}) })
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+    "name": "@abide/claude-code",
+    "version": "0.5.4",
+    "type": "module",
+    "description": "Claude Code engine for abide's agent() — drive Claude Code (your own auth, no API key) over your app's MCP surface",
+    "license": "MIT",
+    "author": "Brian Cray",
+    "homepage": "https://github.com/briancray/abide#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/briancray/abide.git",
+        "directory": "packages/claude-code"
+    },
+    "bugs": {
+        "url": "https://github.com/briancray/abide/issues"
+    },
+    "keywords": [
+        "abide",
+        "claude-code",
+        "agent",
+        "mcp",
+        "llm"
+    ],
+    "engines": {
+        "bun": ">=1.3.0"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "exports": {
+        ".": "./src/engine.ts",
+        "./engine": "./src/engine.ts",
+        "./serve": "./src/serve.ts",
+        "./launch": "./src/launch.ts",
+        "./browser/assistant": "./src/browser/assistant.ts"
+    },
+    "bin": {
+        "claude-code": "./bin/cli.ts"
+    },
+    "files": [
+        "src",
+        "bin"
+    ],
+    "peerDependencies": {
+        "@anthropic-ai/claude-agent-sdk": ">=0.3.0",
+        "@abide/abide": ">=0.27.0"
+    },
+    "peerDependenciesMeta": {
+        "@anthropic-ai/claude-agent-sdk": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@anthropic-ai/claude-agent-sdk": "^0.3.168"
+    }
+}

package/src/BRIDGE_PORT.ts

@@ -0,0 +1,4 @@
+/* Fixed loopback port the serve bridge listens on and the browser connects to.
+Fixed rather than scanned so the page can reach a running bridge at a known
+address — presence is just whether the WebSocket opens. */
+export const BRIDGE_PORT = 8787

package/src/CAPABILITY_TOOLS.ts

@@ -0,0 +1,10 @@
+/* Closed set of site-requestable capabilities, each mapped to the Claude Code
+built-in tool it enables. Network-read only — nothing that touches the user's
+shell or filesystem. Dangerous tools (Bash/Write/Edit) are absent by
+construction, so neither the page API nor the serve flag vocabulary can name
+them; the page can only request from this set, and the user still runs the
+visible command to grant it. */
+export const CAPABILITY_TOOLS = {
+    webSearch: 'WebSearch',
+    webFetch: 'WebFetch',
+} as const

package/src/ClaudePermissions.ts

@@ -0,0 +1,11 @@
+import type { PermissionMode } from './PermissionMode.ts'
+
+/* Permission policy for a local-Claude run: the session mode plus allow/ask/deny
+tool-rule lists (same shape as .claude/settings.json's `permissions`). The CLI
+engine maps `defaultMode` to `--permission-mode` and the rules to `--settings`. */
+export type ClaudePermissions = {
+    defaultMode?: PermissionMode
+    allow?: string[]
+    ask?: string[]
+    deny?: string[]
+}

package/src/PermissionMode.ts

@@ -0,0 +1,4 @@
+/* Session permission mode — the values Claude Code's `--permission-mode` accepts.
+Mirrors the SDK's PermissionMode without importing it, so the CLI-driven faces
+(serve/launch) don't pull @anthropic-ai/claude-agent-sdk. */
+export type PermissionMode = 'default' | 'acceptEdits' | 'plan' | 'dontAsk' | 'bypassPermissions'

package/src/StreamMessage.ts

@@ -0,0 +1,12 @@
+/* The subset of Claude message shapes both engines read. The SDK's query()
+stream and the CLI's `--output-format stream-json` lines carry the same schema,
+so one mapper (framesFromMessages) serves both. Loosely typed — only the fields
+the mapping touches; each engine casts its raw source to this at the boundary. */
+export type StreamMessage =
+    | { type: 'stream_event'; event: { type: string; delta?: { type: string; text?: string } } }
+    | {
+          type: 'assistant'
+          message: { content: Array<{ type: string; id?: string; name?: string; input?: unknown }> }
+      }
+    | { type: 'user'; message: { content: unknown } }
+    | { type: 'result'; subtype: string }

package/src/VERSION.ts

@@ -0,0 +1,6 @@
+import packageJson from '../package.json' with { type: 'json' }
+
+/* This package's own version, inlined into the bundle. The browser `command` pins
+`bunx @abide/claude-code@VERSION` to it so a stale global bunx cache can't start a
+bridge mismatched with the @abide/claude-code the app actually ships. */
+export const VERSION = packageJson.version

package/src/appMcpServer.ts

@@ -0,0 +1,19 @@
+/* The single MCP server entry wiring Claude Code to a abide app's machine
+surface. Plain data — no SDK types — so it serializes equally into the engine's
+query() options and the `claude --mcp-config` JSON the TUI launcher writes. The
+registration KEY (the prefix) is chosen by the caller via mcpServerNameForApp;
+this only describes the transport. */
+export function appMcpServer(origin: string, mcpToken?: string) {
+    return {
+        type: 'http' as const,
+        url: `${origin}/__abide/mcp`,
+        ...(mcpToken ? { headers: { Authorization: `Bearer ${mcpToken}` } } : {}),
+        /* Force the app's verbs into the turn-1 prompt. Without this the SDK
+        defers MCP tools behind tool search, so the model never sees them upfront
+        and reports it only has its built-ins. This app's MCP surface is the whole
+        point of the assistant, so it must always load — and the flag blocks
+        startup until the server connects (5s cap), surfacing a dead endpoint
+        instead of silently yielding an empty toolset. */
+        alwaysLoad: true,
+    }
+}

package/src/appMcpServers.ts

@@ -0,0 +1,15 @@
+import { appMcpServer } from './appMcpServer.ts'
+import { mcpServerNameForApp } from './mcpServerNameForApp.ts'
+
+/* The app's MCP server map, keyed under its discovered `mcp__<name>__*` prefix.
+The "discover the name, then key the transport under it" pair is the actual
+contract every face shares — the engine spreads this map into query options, the
+TUI launcher stringifies it into `--mcp-config` — so it lives here once and the
+prefix can't drift between the headless and interactive paths. */
+export async function appMcpServers(
+    origin: string,
+    mcpToken?: string,
+): Promise<Record<string, ReturnType<typeof appMcpServer>>> {
+    const name = await mcpServerNameForApp(origin, mcpToken)
+    return { [name]: appMcpServer(origin, mcpToken) }
+}

package/src/browser/assistant.ts

@@ -0,0 +1,316 @@
+import type { AgentFrame, NeutralMessage } from '@abide/abide/server/agent'
+import { createSubscriber } from '@abide/abide/shared/createSubscriber'
+import { BRIDGE_PORT } from '../BRIDGE_PORT.ts'
+import type { CAPABILITY_TOOLS } from '../CAPABILITY_TOOLS.ts'
+import { VERSION } from '../VERSION.ts'
+
+/* Site-requestable capabilities — the closed vocabulary from CAPABILITY_TOOLS.
+The page can request from this set; it can never name a shell/fs tool. */
+type AssistantCapability = keyof typeof CAPABILITY_TOOLS
+
+/* The accumulated assistant turn — text-so-far plus the tools it has touched.
+`ask()` yields this (not raw deltas) so abide's subscribe() can surface the
+whole snapshot as its `latest`, which a delta stream couldn't. */
+type AssistantReply = {
+    text: string
+    tools: { id: string; name: string; ok?: boolean }[]
+    done: boolean
+}
+
+const EMPTY_REPLY: AssistantReply = { text: '', tools: [], done: false }
+
+/* The shape subscribe() reads: an AsyncIterable carrying a stable `name` (the
+registry/dedupe key). Declared structurally so the package needn't depend on
+abide's internal Subscribable type. */
+type Subscribable<T> = AsyncIterable<T> & { name: string }
+
+/* Fold one frame into the running snapshot, returning a NEW object each call so
+subscribe()'s reactive read always sees a changed value. */
+function applyFrame(reply: AssistantReply, frame: AgentFrame): AssistantReply {
+    if (frame.type === 'text') {
+        return { ...reply, text: reply.text + frame.delta }
+    }
+    if (frame.type === 'tool_use') {
+        return { ...reply, tools: [...reply.tools, { id: frame.id, name: frame.name }] }
+    }
+    if (frame.type === 'tool_result') {
+        return {
+            ...reply,
+            tools: reply.tools.map((tool) =>
+                tool.id === frame.id ? { ...tool, ok: frame.ok } : tool,
+            ),
+        }
+    }
+    return { ...reply, done: true }
+}
+
+/* What the UI should do about the assistant. A host (a abide bundle) injects a
+handshake into the URL fragment to say it manages the bridge — `<port>.<token>`
+when it's running, or `unavailable` when it manages one but `claude` isn't
+installed. Absent = a plain browser, where the user starts the bridge via `command`. */
+type AssistantStatus = 'ready' | 'starting' | 'manual' | 'unavailable'
+
+type BundleHandshake = { managed: boolean; unavailable: boolean; port?: number; token?: string }
+
+function bundleHandshake(): BundleHandshake {
+    const hash = typeof location === 'undefined' ? '' : location.hash
+    const match = hash.match(/abide-assistant=([^&]+)/)
+    if (!match) {
+        return { managed: false, unavailable: false }
+    }
+    // the group always captures when the regex matches; ?? '' keeps the index
+    // access defined under a consumer's noUncheckedIndexedAccess
+    const value = decodeURIComponent(match[1] ?? '')
+    if (value === 'unavailable') {
+        return { managed: true, unavailable: true }
+    }
+    const [port, token] = value.split('.')
+    return { managed: true, unavailable: false, port: Number(port), token }
+}
+
+type AssistantConfig = {
+    // The abide site whose MCP the local agent drives. Defaults to location.origin.
+    url?: string
+    port?: number
+    // Browser↔bridge secret; sent on the handshake, rendered into `command`.
+    token?: string
+    /* Behavioral instruction sent per-chat over the socket — shapes output within
+    granted tools, never expands them, so it's safe from the page (not in `command`). */
+    systemPrompt?: string
+    // Capability REQUEST surfaced in `command` for the user to grant by running it.
+    capabilities?: AssistantCapability[]
+}
+
+type AssistantHandle = {
+    // Reactive: true while the loopback socket is open and serving.
+    readonly available: boolean
+    /* What the UI should do: 'ready' (show chat), 'starting' (a host is bringing
+    the bridge up), 'manual' (browser — show `command`), 'unavailable' (a host
+    manages the bridge but `claude` isn't installed — show an install hint). */
+    readonly status: AssistantStatus
+    // The copy-paste `serve` command — only in 'manual' mode; undefined when a host manages the bridge.
+    readonly command: string | undefined
+    /* The assistant's reply to `messages`, as a Subscribable of accumulating
+    snapshots: `subscribe(assistant.ask(messages))` drives the turn reactively.
+    Keyed by messages+bridge, so re-renders share one run and the LLM doesn't
+    re-fire until the conversation actually changes. */
+    ask(messages: NeutralMessage[]): Subscribable<AssistantReply>
+}
+
+/* One WebSocket per bridge address, shared across handles/components. Presence is
+the connection being open; chat turns are multiplexed over it, id-tagged so a
+turn yields only its own frames. */
+type Connection = {
+    readonly connected: boolean
+    // createSubscriber tap: reading it in a reactive scope opens the socket; last reader closes it.
+    track: () => void
+    send(messages: NeutralMessage[], systemPrompt?: string): AsyncIterable<AgentFrame>
+}
+
+const connections = new Map<string, Connection>()
+
+function createConnection(url: string): Connection {
+    let socket: WebSocket | undefined
+    let connected = false
+    let nextId = 0
+    // createSubscriber's start/stop fire once, so presence is a boolean, not a count.
+    let watched = false
+    let update: (() => void) | undefined
+    // Resolves when the current socket opens; one per open(), awaited by send() before it writes.
+    let opened: Promise<void> | undefined
+    // id -> deliver a frame, or undefined to signal the stream ended because the socket dropped.
+    const inflight = new Map<number, (frame: AgentFrame | undefined) => void>()
+
+    // The socket stays alive while a presence reader watches OR a turn is in flight.
+    function closeIfIdle() {
+        if (!watched && inflight.size === 0) {
+            socket?.close()
+            socket = undefined
+        }
+    }
+
+    function open() {
+        const ws = new WebSocket(url)
+        socket = ws
+        let onOpen: () => void
+        opened = new Promise((resolve) => {
+            onOpen = resolve
+        })
+        ws.onopen = () => {
+            connected = true
+            update?.()
+            onOpen()
+        }
+        ws.onmessage = (event) => {
+            const { id, frame } = JSON.parse(event.data as string) as {
+                id: number
+                frame: AgentFrame
+            }
+            inflight.get(id)?.(frame)
+        }
+        ws.onclose = () => {
+            connected = false
+            update?.()
+            // End every in-flight stream; reconnect only while a presence reader is watching.
+            inflight.forEach((deliver) => {
+                deliver(undefined)
+            })
+            inflight.clear()
+            if (watched) {
+                setTimeout(() => {
+                    if (watched) {
+                        open()
+                    }
+                }, 1000)
+            }
+        }
+    }
+
+    function ensureOpen(): Promise<void> {
+        if (!socket) {
+            open()
+        }
+        return connected ? Promise.resolve() : (opened ?? Promise.resolve())
+    }
+
+    const track = createSubscriber((u) => {
+        update = u
+        watched = true
+        ensureOpen()
+        return () => {
+            watched = false
+            update = undefined
+            closeIfIdle()
+        }
+    })
+
+    return {
+        get connected() {
+            return connected
+        },
+        track,
+        async *send(messages, systemPrompt) {
+            const id = nextId++
+            const queue: (AgentFrame | undefined)[] = []
+            let wake: (() => void) | undefined
+            inflight.set(id, (frame) => {
+                queue.push(frame)
+                wake?.()
+            })
+            try {
+                await ensureOpen()
+                socket?.send(JSON.stringify({ id, messages, systemPrompt }))
+                for (;;) {
+                    while (queue.length > 0) {
+                        const frame = queue.shift()
+                        // undefined = socket dropped; a `done` frame = clean end of this turn.
+                        if (frame === undefined) {
+                            return
+                        }
+                        yield frame
+                        if (frame.type === 'done') {
+                            return
+                        }
+                    }
+                    await new Promise<void>((resolve) => {
+                        wake = resolve
+                    })
+                    wake = undefined
+                }
+            } finally {
+                inflight.delete(id)
+                closeIfIdle()
+            }
+        },
+    }
+}
+
+function getConnection(url: string): Connection {
+    const cached = connections.get(url)
+    if (cached) {
+        return cached
+    }
+    const connection = createConnection(url)
+    connections.set(url, connection)
+    return connection
+}
+
+function siteOrigin(url?: string): string {
+    if (url) {
+        return url
+    }
+    return typeof location === 'undefined' ? '' : location.origin
+}
+
+/*
+Browser-side handle to a local Claude Code assistant bridge over a loopback
+WebSocket: reactive presence, a chat stream, and the copy-paste command that
+starts the bridge. `capabilities` and `systemPrompt` are the site's REQUEST
+surface — they never grant local power (tools/permissions live with `serve`, on
+the user's machine). Render the assistant only when `available`; otherwise show
+`command` as the first-run hint.
+*/
+export function assistant(config: AssistantConfig = {}): AssistantHandle {
+    const host = bundleHandshake()
+    const origin = siteOrigin(config.url)
+    // A managed host's injected port/token win as defaults; explicit config still overrides.
+    const port = config.port ?? host.port ?? BRIDGE_PORT
+    const token = config.token ?? host.token
+    const wsUrl = `ws://127.0.0.1:${port}${token ? `?token=${token}` : ''}`
+
+    // True only when a bridge is actually reachable — never when a managed host reports it can't run one.
+    function isAvailable(): boolean {
+        if (typeof window === 'undefined' || host.unavailable) {
+            return false
+        }
+        const connection = getConnection(wsUrl)
+        connection.track()
+        return connection.connected
+    }
+
+    return {
+        get available() {
+            return isAvailable()
+        },
+        get status() {
+            if (host.unavailable) {
+                return 'unavailable'
+            }
+            if (isAvailable()) {
+                return 'ready'
+            }
+            // A managed host is bringing the bridge up; a plain browser needs the user to.
+            return host.managed ? 'starting' : 'manual'
+        },
+        get command() {
+            // A host manages the bridge — nothing for the user to run.
+            if (host.managed) {
+                return undefined
+            }
+            // Pin to this bundle's version so a stale global bunx cache can't run a mismatched bridge.
+            const parts = [`bunx @abide/claude-code@${VERSION} serve --url ${origin}`]
+            if (port !== BRIDGE_PORT) {
+                parts.push(`--port ${port}`)
+            }
+            if (config.token) {
+                parts.push(`--token ${config.token}`)
+            }
+            for (const capability of config.capabilities ?? []) {
+                parts.push(`--allow ${capability}`)
+            }
+            return parts.join(' ')
+        },
+        ask(messages: NeutralMessage[]): Subscribable<AssistantReply> {
+            const frames = getConnection(wsUrl).send(messages, config.systemPrompt)
+            async function* snapshots() {
+                let reply = EMPTY_REPLY
+                for await (const frame of frames) {
+                    reply = applyFrame(reply, frame)
+                    yield reply
+                }
+            }
+            // name = bridge + conversation: same messages dedupe to one run across readers/re-renders.
+            return Object.assign(snapshots(), { name: `${wsUrl} ${JSON.stringify(messages)}` })
+        },
+    }
+}

package/src/claudeCliArgs.ts

@@ -0,0 +1,41 @@
+import type { ClaudePermissions } from './ClaudePermissions.ts'
+
+/*
+The one mapping from the package's MCP + permission contract to `claude` CLI
+flags, shared by both binary-spawning faces (cliEngine headless, launch
+interactive) so the isolation triple and the permission grammar can't drift
+between them: `--mcp-config` wires the app server, `--strict-mcp-config` +
+`--setting-sources ''` isolate from the host's ambient servers and settings,
+`--permission-mode` carries the session mode and `--settings` the
+allow/ask/deny rules. `headless` pairs bypassPermissions with the explicit
+`--dangerously-skip-permissions` opt-in the print mode requires; the
+interactive TUI omits it so claude can confirm the bypass with the user.
+*/
+export function claudeCliArgs({
+    servers,
+    permissions,
+    headless,
+}: {
+    servers: Record<string, unknown>
+    permissions?: ClaudePermissions
+    headless: boolean
+}): string[] {
+    const args = [
+        '--mcp-config',
+        JSON.stringify({ mcpServers: servers }),
+        '--strict-mcp-config',
+        '--setting-sources',
+        '',
+    ]
+    const { defaultMode, ...rules } = permissions ?? {}
+    if (defaultMode) {
+        args.push('--permission-mode', defaultMode)
+    }
+    if (headless && defaultMode === 'bypassPermissions') {
+        args.push('--dangerously-skip-permissions')
+    }
+    if (Object.keys(rules).length) {
+        args.push('--settings', JSON.stringify({ permissions: rules }))
+    }
+    return args
+}

package/src/cliEngine.ts

@@ -0,0 +1,94 @@
+import type { AgentEngine } from '@abide/abide/server/agent'
+import { appMcpServers } from './appMcpServers.ts'
+import type { ClaudePermissions } from './ClaudePermissions.ts'
+import { claudeCliArgs } from './claudeCliArgs.ts'
+import { framesFromMessages } from './framesFromMessages.ts'
+import { promptFromMessages } from './promptFromMessages.ts'
+import type { StreamMessage } from './StreamMessage.ts'
+
+type CliEngineConfig = {
+    permissions?: ClaudePermissions
+    /* Built-in tools the model may use, on top of the app's verbs. `[]` restricts
+    it to only `mcp__<app>__*` (no shell/fs); omit to keep Claude's default set. */
+    tools?: string[]
+    mcpToken?: string
+    systemPrompt?: string
+    abortController?: AbortController
+}
+
+// Splits claude's stdout (JSONL stream-json) into parsed messages.
+async function* readStreamJson(stdout: ReadableStream<Uint8Array>): AsyncIterable<StreamMessage> {
+    const reader = stdout.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    for (;;) {
+        const { value, done } = await reader.read()
+        if (done) {
+            break
+        }
+        buffer += decoder.decode(value, { stream: true })
+        let newline = buffer.indexOf('\n')
+        while (newline !== -1) {
+            const line = buffer.slice(0, newline).trim()
+            buffer = buffer.slice(newline + 1)
+            if (line) {
+                yield JSON.parse(line) as StreamMessage
+            }
+            newline = buffer.indexOf('\n')
+        }
+    }
+}
+
+/*
+A local-Claude engine: drives the user's installed `claude` binary headlessly
+(`-p --output-format stream-json`) over the app's MCP, instead of the bundled SDK.
+This is what keeps the serve bridge light — `bunx @abide/claude-code` needs only
+Bun and the `claude` already on PATH, not @anthropic-ai/claude-agent-sdk. It maps
+the same MCP contract (appMcpServers) and isolation (`--strict-mcp-config`,
+`--setting-sources ''`) to CLI flags, and aborts — killing the child — when the
+consumer stops iterating or the caller's controller fires.
+*/
+export function cliEngine(config: CliEngineConfig = {}): AgentEngine {
+    return async function* ({ messages, origin }) {
+        const servers = await appMcpServers(origin, config.mcpToken)
+        const serverName = Object.keys(servers)[0]
+        const controller = config.abortController ?? new AbortController()
+
+        const args = [
+            '-p',
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            '--include-partial-messages',
+            ...claudeCliArgs({ servers, permissions: config.permissions, headless: true }),
+        ]
+        /* tools `[]` (the serve default) → allow only the app's mcp tools; a list
+        adds those built-ins; undefined keeps Claude's default toolset. */
+        if (config.tools) {
+            args.push('--allowedTools', ...config.tools, `mcp__${serverName}`)
+        }
+        if (config.systemPrompt) {
+            args.push('--append-system-prompt', config.systemPrompt)
+        }
+
+        const child = Bun.spawn({
+            cmd: ['claude', ...args],
+            stdin: 'pipe',
+            stdout: 'pipe',
+            stderr: 'inherit',
+        })
+        // Abort (e.g. serve's socket close) kills the spawned claude with the page.
+        const onAbort = () => child.kill()
+        controller.signal.addEventListener('abort', onAbort)
+        // Await the write (it returns a Promise when backpressured) before closing,
+        // so a prompt larger than the pipe buffer isn't truncated.
+        await child.stdin.write(promptFromMessages(messages))
+        await child.stdin.end()
+        try {
+            yield* framesFromMessages(readStreamJson(child.stdout))
+        } finally {
+            controller.signal.removeEventListener('abort', onAbort)
+            child.kill()
+        }
+    }
+}

package/src/engine.ts

@@ -0,0 +1,91 @@
+import type { AgentEngine } from '@abide/abide/server/agent'
+import type { Options, Settings } from '@anthropic-ai/claude-agent-sdk'
+import { query } from '@anthropic-ai/claude-agent-sdk'
+import { appMcpServers } from './appMcpServers.ts'
+import { framesFromMessages } from './framesFromMessages.ts'
+import { promptFromMessages } from './promptFromMessages.ts'
+import type { StreamMessage } from './StreamMessage.ts'
+
+/*
+The SDK-backed Claude Code engine for abide's `agent()`. `engine(config)` returns
+an AgentEngine that drives the @anthropic-ai/claude-agent-sdk headless, pointed at
+the app's own MCP endpoint, and relays its event stream as AgentFrames.
+
+  // src/server/rpc/chat.ts
+  import { agent } from '@abide/abide/server/agent'
+  import { jsonl } from '@abide/abide/server/jsonl'
+  import { engine } from '@abide/claude-code'
+  const chatEngine = engine({ permissions: { defaultMode: 'bypassPermissions' } })
+  export const chat = POST(({ messages }) => jsonl(agent(chatEngine, messages)), { inputSchema })
+
+Use this for a deployed server running Claude Code on its own auth, where there's
+no interactive `claude` on PATH — it requires the @anthropic-ai/claude-agent-sdk
+peer (which bundles its own runtime). For a local assistant against the user's
+installed `claude` (the serve bridge / TUI), the cliEngine drives the binary
+directly and needs no SDK.
+
+Auth rides whatever Claude Code is logged in with. Permission is decided
+server-side via `permissions` — the same `defaultMode` + allow/ask/deny block as
+.claude/settings.json — governing how Claude Code treats its own built-ins.
+*/
+type ClaudeCodeConfig = {
+    // Permission policy, forwarded to the SDK as inline settings + permissionMode.
+    permissions?: Settings['permissions']
+    // Built-in tools the model may see, or `[]` to drop them so only mcp__<app>__* remains.
+    tools?: Options['tools']
+    // Bearer for the app's /__abide/mcp endpoint, if it's gated by app.handle/authorize.
+    mcpToken?: string
+    // Cancels the run early; the engine also aborts when the consumer stops iterating.
+    abortController?: AbortController
+    // Escape hatch for any other SDK option; spread first so engine-owned keys win.
+    options?: Partial<Options>
+}
+
+export function engine(config: ClaudeCodeConfig = {}): AgentEngine {
+    /* Split the settings-shaped permission block: `defaultMode` is the session
+    mode (a top-level SDK option, the only thing the bypass guard checks) while the
+    allow/ask/deny rules ride in `settings.permissions`. */
+    const { defaultMode, ...permissionRules } = config.permissions ?? {}
+    return async function* ({ messages, origin }) {
+        const prompt = promptFromMessages(messages)
+        // The app's MCP server, keyed under its discovered `mcp__<name>__*` prefix.
+        const appServers = await appMcpServers(origin, config.mcpToken)
+        // Aborted in the finally so the SDK stops and kills its Claude process when
+        // the consumer stops iterating; a caller controller can cancel from outside.
+        const controller = config.abortController ?? new AbortController()
+
+        const stream = query({
+            prompt,
+            options: {
+                // No skills by default — a site-inline agent shouldn't surface the host's workflows.
+                skills: [],
+                // Caller extras first; every engine-owned key below overrides them.
+                ...config.options,
+                mcpServers: { ...config.options?.mcpServers, ...appServers },
+                /* Isolate from the deploy host's ambient settings and MCP servers
+                (project .mcp.json, user settings, plugins, cloud connectors) — they'd
+                otherwise merge into and could widen this policy. */
+                settingSources: [],
+                strictMcpConfig: true,
+                // Always stream token deltas (as stream_event) so text arrives live.
+                includePartialMessages: true,
+                abortController: controller,
+                ...(config.tools ? { tools: config.tools } : {}),
+                ...(Object.keys(permissionRules).length
+                    ? { settings: { permissions: permissionRules } }
+                    : {}),
+                ...(defaultMode ? { permissionMode: defaultMode } : {}),
+                // The SDK requires this explicit opt-in alongside bypassPermissions.
+                ...(defaultMode === 'bypassPermissions'
+                    ? { allowDangerouslySkipPermissions: true }
+                    : {}),
+            },
+        })
+
+        try {
+            yield* framesFromMessages(stream as AsyncIterable<StreamMessage>)
+        } finally {
+            controller.abort()
+        }
+    }
+}

package/src/framesFromMessages.ts

@@ -0,0 +1,54 @@
+import type { AgentFrame } from '@abide/abide/server/agent'
+import type { StreamMessage } from './StreamMessage.ts'
+
+/*
+Maps a Claude message stream to abide AgentFrames. Shared by both engines — the
+SDK's query() stream and the CLI's stream-json lines have the same schema, so the
+discrimination lives here once. Text is emitted from `stream_event` deltas (live
+tokens); the complete `assistant` message repeats that text in full, so it's kept
+only for its fully-formed tool_use blocks (partial tool inputs mid-stream aren't
+valid JSON yet). Tool outcomes return as tool_result blocks on a user turn —
+`ok: !is_error` surfaces a blocked/denied tool the same as a failed one.
+*/
+export async function* framesFromMessages(
+    messages: AsyncIterable<StreamMessage>,
+): AsyncIterable<AgentFrame> {
+    // tool_use id → name, so a tool_result (which carries only the id) can name its call.
+    const toolNames = new Map<string, string>()
+    for await (const message of messages) {
+        if (message.type === 'stream_event') {
+            const { event } = message
+            if (
+                event.type === 'content_block_delta' &&
+                event.delta?.type === 'text_delta' &&
+                event.delta.text
+            ) {
+                yield { type: 'text', delta: event.delta.text }
+            }
+        } else if (message.type === 'assistant') {
+            for (const block of message.message.content) {
+                if (block.type === 'tool_use' && block.id && block.name) {
+                    toolNames.set(block.id, block.name)
+                    yield { type: 'tool_use', id: block.id, name: block.name, input: block.input }
+                }
+            }
+        } else if (message.type === 'user') {
+            const { content } = message.message
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type === 'tool_result') {
+                        yield {
+                            type: 'tool_result',
+                            id: block.tool_use_id,
+                            name: toolNames.get(block.tool_use_id) ?? '',
+                            ok: !block.is_error,
+                        }
+                    }
+                }
+            }
+        } else if (message.type === 'result') {
+            // `success` is a clean finish; every error subtype is an abnormal stop.
+            yield { type: 'done', stop: message.subtype === 'success' ? 'end' : 'error' }
+        }
+    }
+}

package/src/launch.ts

@@ -0,0 +1,40 @@
+import { appMcpServers } from './appMcpServers.ts'
+import { claudeCliArgs } from './claudeCliArgs.ts'
+import type { PermissionMode } from './PermissionMode.ts'
+
+/*
+Launches the interactive `claude` TUI wired to a abide app's MCP surface. Unlike
+the engine (headless query()), this spawns the real binary — so it touches no SDK
+— and maps the same MCP contract to CLI flags: `--mcp-config` for the app server,
+`--strict-mcp-config` + `--setting-sources ''` to isolate from the host's ambient
+servers and settings, `--permission-mode` for the session policy.
+
+Inherits stdio (it's a TUI) and forwards Ctrl+C so the child tears down cleanly,
+then mirrors its exit code — `never` because the process is replaced.
+*/
+type LaunchConfig = {
+    // The abide app whose MCP the TUI drives (local dev server or a deployed origin).
+    url: string
+    mcpToken?: string
+    permissionMode?: PermissionMode
+}
+
+export async function launch(config: LaunchConfig): Promise<never> {
+    const servers = await appMcpServers(config.url, config.mcpToken)
+    const args = [
+        'claude',
+        ...claudeCliArgs({
+            servers,
+            permissions: config.permissionMode ? { defaultMode: config.permissionMode } : undefined,
+            headless: false,
+        }),
+    ]
+    const child = Bun.spawn({ cmd: args, stdio: ['inherit', 'inherit', 'inherit'] })
+    const forward = (signal: NodeJS.Signals) => {
+        child.kill(signal)
+        setTimeout(() => child.kill('SIGKILL'), 3000).unref()
+    }
+    process.on('SIGINT', () => forward('SIGINT'))
+    process.on('SIGTERM', () => forward('SIGTERM'))
+    process.exit(await child.exited)
+}

package/src/promptFromMessages.ts

@@ -0,0 +1,26 @@
+import type { NeutralMessage } from '@abide/abide/server/agent'
+
+/*
+Claude (SDK or CLI) takes a single prompt and owns assistant/tool turns through
+its own session, which abide doesn't resume here. So prior turns are flattened
+into the prompt as a labelled transcript rather than dropped — the model keeps
+the conversation's context without session state. A lone user turn passes through
+as its bare text. Tool-result turns are internal to the prior run and omitted.
+*/
+export function promptFromMessages(messages: NeutralMessage[]): string {
+    if (messages.length === 1 && messages[0]?.role === 'user') {
+        return messages[0].text
+    }
+    return messages
+        .map((message) => {
+            if (message.role === 'user') {
+                return `User: ${message.text}`
+            }
+            if (message.role === 'assistant' && message.text) {
+                return `Assistant: ${message.text}`
+            }
+            return ''
+        })
+        .filter(Boolean)
+        .join('\n\n')
+}

package/src/sanitizeMcpName.ts

@@ -0,0 +1,12 @@
+/* Normalizes an app's MCP server name into a token legal in the
+`mcp__<name>__<tool>` prefix. Drops the npm scope's leading `@` but keeps the
+scope for uniqueness (`@acme/shop` -> `acme_shop`); every other non-word run
+collapses to `_`, and edge underscores are trimmed. Deterministic — same input,
+same token — so permission rules authored against the prefix stay valid across
+deploys. */
+export function sanitizeMcpName(name: string): string {
+    return name
+        .replace(/^@/, '')
+        .replace(/[^a-zA-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+}

package/src/serve.ts

@@ -0,0 +1,147 @@
+import type { NeutralMessage } from '@abide/abide/server/agent'
+import { BRIDGE_PORT } from './BRIDGE_PORT.ts'
+import type { ClaudePermissions } from './ClaudePermissions.ts'
+import { cliEngine } from './cliEngine.ts'
+
+/*
+Runs on the USER's machine, on loopback, so a remote abide site's browser can
+drive the user's local Claude Code over its own MCP surface. A separate process
+from any deployed server — apps that don't use this pay nothing. Drives the
+installed `claude` binary (via cliEngine), so it needs only Bun + claude on PATH,
+no @anthropic-ai/claude-agent-sdk.
+
+The page reaches the bridge over a single WebSocket: presence IS the connection
+being open (no polling), and chat frames ride the same socket, id-tagged so
+concurrent turns don't interleave. This is the loopback channel only — Claude
+still talks to the app's MCP over HTTP (the `mcp__<app>__*` server).
+
+The trust boundary: capabilities (`tools`/`permissions`) are chosen HERE, by the
+user starting the bridge — never sent from the page, which could only ever author
+a request, not a grant. Defaults are locked down: `tools: []` exposes only the
+site's `mcp__<app>__*` verbs (no shell/fs) and sidesteps the headless no-TTY
+permission prompt, with prompting left at `default`.
+*/
+type ServeConfig = {
+    // The abide site whose MCP this agent drives, and (by default) the only origin allowed in.
+    url: string
+    port?: number
+    // Origins permitted to reach this bridge. Defaults to [url]; doubles as a DNS-rebind guard.
+    allowOrigins?: string[]
+    // Optional browser↔bridge secret echoed by the page on the handshake; rejects other sites.
+    token?: string
+    // Optional bridge→site MCP bearer, distinct from `token`.
+    mcpToken?: string
+    // Built-in tools the local agent may use, on top of the site's verbs. Default [] — site verbs only.
+    tools?: string[]
+    permissions?: ClaudePermissions
+    /* Called once the last subscriber has been gone for `idleGraceMs` (default
+    30s). The bin passes `() => process.exit(0)` so `bunx serve` ends when the page
+    closes; a reload within the grace reconnects and cancels it. Only armed after
+    the first connection, so the bridge waits indefinitely for the page to first
+    appear. Omit to keep the bridge resident. */
+    onIdle?: () => void
+    idleGraceMs?: number
+}
+
+// One chat turn from the page: `id` correlates the frames streamed back on the shared socket.
+type ChatRequest = { id: number; messages: NeutralMessage[]; systemPrompt?: string }
+
+/* Per-connection state: the abort controllers for this socket's in-flight turns,
+so closing the page can cancel each run — killing its spawned Claude process
+rather than leaving it running on the user's machine. */
+type WsData = { controllers: Set<AbortController> }
+
+export function serve(config: ServeConfig) {
+    const allowOrigins = config.allowOrigins ?? [config.url]
+    // Live socket count + the pending idle-exit timer (armed only once a client has connected).
+    let connections = 0
+    let idleTimer: ReturnType<typeof setTimeout> | undefined
+
+    return Bun.serve<WsData>({
+        // Loopback only — never 0.0.0.0.
+        hostname: '127.0.0.1',
+        port: config.port ?? BRIDGE_PORT,
+        // Origin allow-list + token are checked on the handshake (also the rebind guard);
+        // a passing request is upgraded to the WebSocket, anything else is refused.
+        fetch(request, server) {
+            const origin = request.headers.get('origin') ?? ''
+            if (!allowOrigins.includes(origin)) {
+                return new Response(null, { status: 403 })
+            }
+            if (config.token && new URL(request.url).searchParams.get('token') !== config.token) {
+                return new Response(null, { status: 401 })
+            }
+            if (server.upgrade(request, { data: { controllers: new Set() } })) {
+                return undefined
+            }
+            return new Response('Upgrade required', { status: 426 })
+        },
+        websocket: {
+            open() {
+                connections++
+                // A (re)connection cancels any pending idle exit.
+                if (idleTimer) {
+                    clearTimeout(idleTimer)
+                    idleTimer = undefined
+                }
+            },
+            async message(ws, raw) {
+                let request: ChatRequest
+                try {
+                    request = JSON.parse(String(raw))
+                } catch {
+                    return
+                }
+                /* Per-turn controller, registered so close() can abort this run even
+                while it's idle (between frames) — the readyState check below only
+                fires on the next frame, which a stalled run never produces. */
+                const controller = new AbortController()
+                ws.data.controllers.add(controller)
+                /* Per-message engine so the site's behavioral systemPrompt can vary
+                per turn — it shapes output within the granted tools, never expands
+                them, so it's safe to take from the page. */
+                const runAgent = cliEngine({
+                    tools: config.tools ?? [],
+                    permissions: config.permissions ?? { defaultMode: 'default' },
+                    mcpToken: config.mcpToken,
+                    systemPrompt: request.systemPrompt,
+                    abortController: controller,
+                })
+                // The engine ignores `surface` — it dials the site's MCP via `origin`.
+                const frames = runAgent({
+                    surface: undefined as never,
+                    messages: request.messages,
+                    origin: config.url,
+                })
+                try {
+                    for await (const frame of frames) {
+                        // Stop the run if the page closed the socket mid-stream.
+                        if (ws.readyState !== 1) {
+                            break
+                        }
+                        ws.send(JSON.stringify({ id: request.id, frame }))
+                    }
+                } catch (error) {
+                    // An abort (page closed) is expected; surface only real failures.
+                    if (!controller.signal.aborted) {
+                        console.error(error)
+                    }
+                } finally {
+                    ws.data.controllers.delete(controller)
+                }
+            },
+            // Page gone: abort every in-flight run so its Claude process dies with the socket.
+            close(ws) {
+                ws.data.controllers.forEach((controller) => {
+                    controller.abort()
+                })
+                ws.data.controllers.clear()
+                connections--
+                // Last subscriber gone — arm the idle exit; a reload reconnects within the grace.
+                if (connections === 0 && config.onIdle) {
+                    idleTimer = setTimeout(config.onIdle, config.idleGraceMs ?? 30_000)
+                }
+            },
+        },
+    })
+}