@abide/abide 0.57.1 → 0.100.0

package/src/server/assistant.ts

@@ -0,0 +1,163 @@
+// SECTION 45 — A CONVERSATION WITH A MODEL, piped through a handler the app wrote. `assistant` is what
+// every provider shares: the transcript's check, the app's MCP tools as a `Toolbox`, and the turn cap.
+// A `Provider` runs the conversation — `claudeApi` by looping over the Messages API itself,
+// `claudeCode` by handing it to a Claude Code on the visitor's own machine — and yields the one
+// `AssistantEvent` stream either way (45.2).
+//
+// THE TOOLS ARE THE APP'S OWN MCP SURFACE (45.6), called in process through the app answering this
+// request and carrying the asker's credentials (45.7), so a tool does what the person asking could do
+// and nothing more. Both are CAPTURED when the conversation starts: a provider may call a tool from
+// another request's scope — `claudeCode` answers one from the bridge's — and the call is still this
+// asker's.
+
+import { refuse } from '#shared/refuse.ts'
+import { type McpReply, McpSurface } from './generatedSurfaces.ts'
+import { request, within } from './requestScope.ts'
+
+/** One turn of the transcript a caller sends. */
+export type AssistantMessage = { role: 'user' | 'assistant'; content: string }
+
+/** What a conversation yields, the same from every provider. */
+export type AssistantEvent =
+    | { type: 'text'; text: string }
+    | { type: 'tool'; id: string; name: string; input: unknown }
+    | { type: 'result'; id: string; text: string; failed: boolean }
+    | {
+          type: 'done'
+          stop: string
+          usage: { input: number; output: number }
+      }
+
+/** A tool as the app's MCP surface lists it. */
+export type ToolDefinition = {
+    name: string
+    description: string
+    inputSchema: unknown
+}
+
+/** The app's MCP tools, called as the asker. */
+export type Toolbox = {
+    list: ToolDefinition[]
+    call(
+        name: string,
+        input: unknown,
+    ): Promise<{ text: string; failed: boolean }>
+}
+
+/** What runs a conversation: a model's API, or something that runs its own loop. */
+export type Provider = {
+    run(
+        messages: AssistantMessage[],
+        tools: Toolbox,
+        limits: { maxTurns: number; signal: AbortSignal },
+    ): AsyncGenerator<AssistantEvent>
+}
+
+/** What `assistant` takes beside a provider, the same for every one. */
+export type AssistantOptions = { mcp?: boolean; maxTurns?: number }
+
+const MAX_TURNS = 10
+// 45.7 — the caller's credentials, and nothing else of their request.
+const CARRIED_HEADERS = ['cookie', 'authorization']
+
+/** A conversation over `messages`, run by `provider`, as the events it produces. */
+export async function* assistant(
+    messages: AssistantMessage[],
+    provider: Provider,
+    options: AssistantOptions = {},
+): AsyncGenerator<AssistantEvent> {
+    // 45.3 — a transcript a model can answer ends on the asker's turn.
+    if (messages.at(-1)?.role !== 'user')
+        throw refuse(
+            400,
+            'The transcript has to end on a user turn for the assistant to answer it. RULEBOOK 45.3.',
+        )
+    const tools = toolboxOver(
+        options.mcp === true ? appSurface() : NO_SURFACE,
+        askerOf(request()),
+    )
+    yield* provider.run(messages, tools, {
+        maxTurns: options.maxTurns ?? MAX_TURNS,
+        signal: request().signal,
+    })
+}
+
+/** Where an MCP request is answered, as JSON-RPC's `result` or `error`. */
+type McpForward = (method: string, params: unknown) => Promise<McpReply>
+
+// WHAT A `Toolbox` FORWARDS AN MCP REQUEST TO, for a provider that speaks MCP itself (`claudeCode`):
+// the app's own surface, verbatim, rather than a second server rebuilt over `list` and `call`. Beside
+// the type rather than on it, since a `Toolbox` is public and this is not.
+const FORWARDS = new WeakMap<Toolbox, McpForward>()
+
+/** Where `tools` sends an MCP request whole. 45.17. */
+export function forwardOf(tools: Toolbox): McpForward {
+    const forward = FORWARDS.get(tools)
+    if (forward === undefined)
+        throw new Error(
+            'abide: an MCP request is answered from the Toolbox `assistant` built, and this one it did not.',
+        )
+    return forward
+}
+
+// Without `mcp` there is no surface to forward to, so this is the protocol over nothing — and
+// nothing is published, so nothing is ever called.
+const NO_SURFACE = new McpSurface(
+    new Map(),
+    async () => new Response(null, { status: 404 }),
+)
+
+/** The MCP surface of the app answering this request. 45.6, 45.8. */
+function appSurface(): McpSurface {
+    // 42.12 — the app answering this request, captured: a later call may come from another's scope.
+    const app = within('assistant').app
+    if (app === undefined)
+        throw new Error(
+            'abide: assistant tools are the app’s MCP surface, and no app is answering this request. RULEBOOK 45.6.',
+        )
+    // 45.8, 20.7 — asking for tools over a closed surface is a mistake to name.
+    if (!app.mcp.opened)
+        throw new Error(
+            'abide: assistant was asked for tools, and ABIDE_MCP has not opened the MCP surface. RULEBOOK 45.8.',
+        )
+    return app.mcp
+}
+
+/** The asking request as a tool call is made: its credentials, and nothing else of it. 45.7. */
+function askerOf(asked: Request): Request {
+    const carried: Record<string, string> = {}
+    for (const name of CARRIED_HEADERS) {
+        const value = asked.headers.get(name)
+        if (value !== null) carried[name] = value
+    }
+    return new Request(asked.url, { headers: carried })
+}
+
+/** `surface` as a `Toolbox`, every call made as `asker`. 45.6, 45.7. */
+function toolboxOver(surface: McpSurface, asker: Request): Toolbox {
+    const tools: Toolbox = {
+        list: surface.list(),
+        async call(name, input) {
+            // A refusal or a missing tool is a failed result the model reads, never a thrown one.
+            try {
+                return await surface.call(name, input, asker)
+            } catch (thrown) {
+                return {
+                    text:
+                        thrown instanceof Error
+                            ? thrown.message
+                            : String(thrown),
+                    failed: true,
+                }
+            }
+        },
+    }
+    FORWARDS.set(tools, (method, params) =>
+        surface.answer(
+            method,
+            params as Record<string, unknown> | undefined,
+            asker,
+        ),
+    )
+    return tools
+}

package/src/server/banner.ts

@@ -0,0 +1,43 @@
+import { networkInterfaces } from 'node:os' // bun exposes no network interface list of its own
+import { useColor } from '#shared/log.ts'
+import { paint as painted } from '#shared/paint.ts'
+import type { AppPackage } from './config.ts'
+
+/**
+ * What `start` and `dev` print once the app is listening: the app, and every address it answers at.
+ *
+ * THE LOCAL ADDRESS IS THE FIRST URL PRINTED, because a harness reading the output takes the first
+ * `http://` it finds (`addressOf` in the tests). The network rows follow it unconditionally: neither
+ * `listen` nor `serveDev` names a hostname, and `Bun.serve` given none binds every interface —
+ * whatever `url` says.
+ */
+export function banner(
+    host: string,
+    command: string,
+    identity: AppPackage,
+    server: Bun.Server<unknown>,
+): string {
+    const color = useColor()
+    const paint = (code: string, text: string): string =>
+        painted(color, code, text)
+    const local = server.url.href
+    const title = `${paint('1;36', host)} ${paint('1', command)}`
+    const named =
+        identity.name === undefined
+            ? ''
+            : `  ${paint('2', `${identity.name}${identity.version === undefined ? '' : ` ${identity.version}`}`)}`
+    let text = `\n  ${title}${named}\n\n  ${paint('32', '➜')}  ${paint('1', 'Local:')}    ${paint('36', local)}\n`
+    for (const address of networkAddresses())
+        text += `  ${paint('32', '➜')}  ${paint('1', 'Network:')}  ${paint('36', `${server.url.protocol}//${address}:${server.port}/`)}\n`
+    return text
+}
+
+/** This machine's external IPv4 addresses. */
+function networkAddresses(): string[] {
+    const addresses: string[] = []
+    for (const entries of Object.values(networkInterfaces()))
+        for (const entry of entries ?? [])
+            if (entry.family === 'IPv4' && !entry.internal)
+                addresses.push(entry.address)
+    return addresses
+}

package/src/server/bridgeRelay.ts

@@ -0,0 +1,249 @@
+// 45.13 — THE RELAY BETWEEN A PAGE AND THE CLAUDE CODE ON ITS VISITOR'S MACHINE. A browser cannot reach
+// a process on its own machine from an https page — Safari refuses it as mixed content, and Chrome
+// asks a local-network permission of every site — so the bridge dials OUT, to this address:
+//
+//   GET  /__abide/bridge?code=…   the pairing, answered by a server-sent stream of what the bridge is
+//                                 to do: the token it posts with, each turn, each tool reply, a cancel.
+//   POST /__abide/bridge          what the bridge reports, one frame per line: a turn's events, the
+//                                 MCP requests its Claude Code made, the turn's end or failure.
+//
+// A PAIRING IS TO A BROWSER — the `abide-caller` its page carries (26.5) — for as long as the bridge's
+// stream is open. HELD IN THIS PROCESS: an app served by several needs a visitor's requests to reach
+// the one its bridge dialled.
+
+import { refuse } from '#shared/refuse.ts'
+import { answered } from './answerFailure.ts'
+import { raiseTimeout } from './answerRpc.ts'
+import { framed } from './answerValue.ts'
+import { config } from './config.ts'
+import { Inbox } from './Inbox.ts'
+import { randomToken } from './randomToken.ts'
+
+/**
+ * What a turn hears from the bridge, in the order the bridge posted it: an event, an MCP request, the
+ * end, or a failure. ONE SHAPE for all four, every field set, since one is built per streamed chunk.
+ */
+export type TurnItem = {
+    kind: 'event' | 'mcp' | 'end' | 'fail'
+    event: unknown
+    id: number
+    method: string
+    params: unknown
+    message: string
+}
+
+/** One paired bridge: what it is sent, and the turns it is answering. */
+export type Bridge = {
+    caller: string
+    token: string
+    frames: Inbox<unknown>
+    turns: Map<string, Inbox<TurnItem>>
+    // Whether a page has watched this pairing: only a watched bridge is sent away when it goes idle.
+    watched: boolean
+    idle: ReturnType<typeof setTimeout> | undefined
+}
+
+/** How long a pairing code stands unused. */
+const CODE_LIFETIME = 10 * 60_000
+// How long a bridge outlives the last page watching it, so a reload does not end it.
+const IDLE_GRACE = 30_000
+
+const CODES = new Map<string, { caller: string; expires: number }>()
+const BY_CALLER = new Map<string, Bridge>()
+const BY_TOKEN = new Map<string, Bridge>()
+const WATCHERS = new Map<string, Set<() => void>>()
+
+/** Whether `ABIDE_BRIDGE` has opened the relay. 45.19. */
+export function bridgeOpened(): boolean {
+    return (config.peek()?.ABIDE_BRIDGE as unknown) === true
+}
+
+/** A single-use pairing code for `caller`, and when it stops standing. 45.14. */
+export function mintCode(caller: string): { code: string; expires: number } {
+    const now = Date.now()
+    for (const [code, pairing] of CODES)
+        if (pairing.expires <= now) CODES.delete(code)
+    const code = randomToken(12, 'base64url')
+    const expires = now + CODE_LIFETIME
+    CODES.set(code, { caller, expires })
+    return { code, expires }
+}
+
+/** The bridge paired to `caller`, if its stream is open. */
+export function pairedBridge(caller: string): Bridge | undefined {
+    return BY_CALLER.get(caller)
+}
+
+/** Registers `wake` to run whenever `caller`'s pairing changes; the returned function undoes it. */
+export function watchPairing(caller: string, wake: () => void): () => void {
+    let watchers = WATCHERS.get(caller)
+    if (watchers === undefined) {
+        watchers = new Set()
+        WATCHERS.set(caller, watchers)
+    }
+    watchers.add(wake)
+    const bridge = BY_CALLER.get(caller)
+    if (bridge !== undefined) {
+        bridge.watched = true
+        if (bridge.idle !== undefined) clearTimeout(bridge.idle)
+        bridge.idle = undefined
+    }
+    return () => {
+        watchers.delete(wake)
+        if (watchers.size > 0) return
+        WATCHERS.delete(caller)
+        armIdle(caller)
+    }
+}
+
+/** A new turn on `bridge`, the inbox its events arrive in, and the undo that closes it. */
+export function openTurn(bridge: Bridge): {
+    id: string
+    inbox: Inbox<TurnItem>
+    close: () => void
+} {
+    const id = randomToken(9, 'base64url')
+    const inbox = new Inbox<TurnItem>()
+    bridge.turns.set(id, inbox)
+    return {
+        id,
+        inbox,
+        close: () => {
+            bridge.turns.delete(id)
+            if (!WATCHERS.has(bridge.caller)) armIdle(bridge.caller)
+        },
+    }
+}
+
+// 45.22 — A BRIDGE A PAGE WATCHED, THAT NO PAGE WATCHES NOW AND THAT IS ANSWERING NO TURN, is sent
+// away once the grace runs.
+function armIdle(caller: string): void {
+    const bridge = BY_CALLER.get(caller)
+    if (
+        bridge === undefined ||
+        !bridge.watched ||
+        bridge.turns.size > 0 ||
+        bridge.idle !== undefined
+    )
+        return
+    bridge.idle = setTimeout(() => {
+        bridge.frames.push({ type: 'bye' })
+        dropBridge(bridge)
+    }, IDLE_GRACE)
+}
+
+function wakeWatchers(caller: string): void {
+    for (const wake of WATCHERS.get(caller) ?? []) wake()
+}
+
+function item(
+    kind: TurnItem['kind'],
+    fields: {
+        event?: unknown
+        id?: number
+        method?: string
+        params?: unknown
+        message?: string
+    },
+): TurnItem {
+    return {
+        kind,
+        event: fields.event,
+        id: fields.id ?? 0,
+        method: fields.method ?? '',
+        params: fields.params,
+        message: fields.message ?? '',
+    }
+}
+
+function dropBridge(bridge: Bridge): void {
+    if (BY_CALLER.get(bridge.caller) === bridge) BY_CALLER.delete(bridge.caller)
+    BY_TOKEN.delete(bridge.token)
+    if (bridge.idle !== undefined) clearTimeout(bridge.idle)
+    bridge.idle = undefined
+    for (const turn of bridge.turns.values()) {
+        turn.push(
+            item('fail', { message: 'the Claude Code bridge disconnected' }),
+        )
+        turn.close()
+    }
+    bridge.turns.clear()
+    bridge.frames.close()
+    wakeWatchers(bridge.caller)
+}
+
+/** Answers `/__abide/bridge`, or `undefined` where `ABIDE_BRIDGE` is closed. 45.19. */
+export async function answerBridge(request: Request): Promise<unknown> {
+    if (!bridgeOpened()) return undefined
+    if (request.method === 'GET') return pair(request)
+    if (request.method === 'POST') return relay(request)
+    return new Response(null, { status: 405, headers: { allow: 'GET, POST' } })
+}
+
+function pair(request: Request): Response {
+    const code = new URL(request.url).searchParams.get('code') ?? ''
+    const pairing = CODES.get(code)
+    // 45.14 — a code pairs once.
+    CODES.delete(code)
+    if (pairing === undefined || pairing.expires <= Date.now())
+        return answered(
+            refuse(
+                403,
+                'This pairing code was not issued here, or it has been used, or it has expired.',
+            ),
+        )
+    const standing = BY_CALLER.get(pairing.caller)
+    if (standing !== undefined) {
+        standing.frames.push({ type: 'bye' })
+        dropBridge(standing)
+    }
+    const bridge: Bridge = {
+        caller: pairing.caller,
+        token: randomToken(24, 'base64url'),
+        frames: new Inbox(),
+        turns: new Map(),
+        watched: WATCHERS.has(pairing.caller),
+        idle: undefined,
+    }
+    BY_CALLER.set(bridge.caller, bridge)
+    BY_TOKEN.set(bridge.token, bridge)
+    bridge.frames.push({ type: 'paired', token: bridge.token })
+    // 16.57 — a pairing stays open for as long as the bridge holds it.
+    raiseTimeout(Number.POSITIVE_INFINITY)
+    request.signal.addEventListener('abort', () => dropBridge(bridge))
+    wakeWatchers(bridge.caller)
+    return framed(
+        bridge.frames[Symbol.asyncIterator](),
+        'sse',
+        new Headers(),
+        200,
+    )
+}
+
+type BridgeReport = {
+    type: 'event' | 'mcp' | 'end' | 'fail'
+    turn: string
+    event?: unknown
+    id?: number
+    method?: string
+    params?: unknown
+    message?: string
+}
+
+async function relay(request: Request): Promise<Response> {
+    const token = (request.headers.get('authorization') ?? '').replace(
+        /^Bearer /,
+        '',
+    )
+    const bridge = BY_TOKEN.get(token)
+    if (bridge === undefined)
+        return answered(refuse(401, 'No bridge is paired with this token.'))
+    for (const line of (await request.text()).split('\n')) {
+        if (line === '') continue
+        const report = JSON.parse(line) as BridgeReport
+        const turn = bridge.turns.get(report.turn)
+        if (turn === undefined) continue
+        turn.push(item(report.type, report))
+    }
+    return new Response(null, { status: 204 })
+}

package/src/server/buildDirectory.ts

@@ -0,0 +1,10 @@
+import { dirname } from 'node:path' // bun exposes no path helpers of its own
+
+/**
+ * Where an app's build goes: `.abide` in the directory above its source root.
+ *
+ * BESIDE THE APP RATHER THAN BESIDE THE SHELL: an app's build belongs to the app.
+ */
+export function buildDirectory(root: string): string {
+    return `${dirname(root)}/.abide`
+}

package/src/server/callerOf.ts

@@ -0,0 +1,60 @@
+import { cookies } from '#shared/cookies.ts'
+import { randomToken } from './randomToken.ts'
+import {
+    currentRequestScope,
+    type RequestScope,
+    within,
+} from './requestScope.ts'
+
+// 26.5 AND 26.19 — WHICH BROWSER, as against who is using it: read off the `abide-caller` cookie, or
+// minted where there is none. What the seed buffer is keyed by (41.18), and what `principal.caller`
+// reads.
+//
+// MINTED ON A PAGE ALONE. A page is where a browser starts, and the one answer a later call has to be
+// matched back to; a machine calling a handler directly has no render to be matched to and is not
+// handed a cookie it never asked for.
+
+// 26.19.
+const CALLER_COOKIE = 'abide-caller'
+
+/**
+ * `principal.caller` as it stands in this request, or `undefined`; never minted.
+ *
+ * 41.18 — a caller rotated by a `principal.clear` earlier in it (26.7, 26.9) is the one a seed is
+ * matched by, not the cookie the request arrived with — or a render made for the signed-in caller
+ * answers the signed-out one.
+ */
+export function callerOf(): string | undefined {
+    const scope = currentRequestScope()
+    if (scope === undefined) return undefined
+    if (scope.caller !== undefined) return scope.caller
+    const header = scope.request?.headers.get('cookie') ?? null
+    if (header === null) return undefined
+    const given = new Bun.CookieMap(header).get(CALLER_COOKIE) ?? undefined
+    scope.caller = given
+    return given
+}
+
+/**
+ * This request's caller, minting one where the request has none.
+ *
+ * 26.5, 26.6 — READ OFF ITS OWN COOKIE OR MINTED, and untouched by a sign-in.
+ */
+export function callerOrMint(): string {
+    const scope = within('principal.caller')
+    return callerOf() ?? mintCaller(scope)
+}
+
+/**
+ * Mints a fresh caller for this request, sets its cookie, and returns it.
+ *
+ * Written through the request's jar as 26.12 writes the principal cookie: out of reach of the
+ * page's own script, sent on a navigation from elsewhere, and only over https in production.
+ */
+export function mintCaller(scope: RequestScope): string {
+    const caller = randomToken(16, 'base64url')
+    // 22.10 — minted once the headers are out, it is this scope's alone: there is no answer to set it on.
+    if (!scope.applied) cookies().set(CALLER_COOKIE, caller, { httpOnly: true })
+    scope.caller = caller
+    return caller
+}