@abide/abide 0.58.0 → 0.101.0

package/src/server/claudeApi.ts

@@ -0,0 +1,224 @@
+// 45.9 — THE MESSAGES API AS A `Provider`, configured the way Anthropic documents it: the request
+// body's own fields, snake_case, beside the client's `apiKey` and `baseURL`. abide owns `messages`
+// and `stream`; every other field is laid on the body as written, and the `tools` written there —
+// a server tool like web search — are sent beside the app's own.
+//
+// Every block of an assistant turn goes back as it came — a `thinking` block with its signature
+// included, which a turn continuing after a tool call is refused without.
+
+import { framedStream, framingPrefix } from '#shared/framing.ts'
+import { refuse } from '#shared/refuse.ts'
+import type { AssistantEvent, Provider } from './assistant.ts'
+
+/** A Messages API request body, less what abide writes, with the client's key and origin. */
+export type ClaudeApiConfig = {
+    apiKey: string
+    baseURL?: string
+    model: string
+    max_tokens: number
+    system?: string | unknown[]
+    tools?: unknown[]
+    messages?: never
+    stream?: never
+    [field: string]: unknown
+}
+
+const API_URL = 'https://api.anthropic.com'
+const API_VERSION = '2023-06-01'
+
+type Usage = {
+    input_tokens?: number
+    cache_creation_input_tokens?: number
+    cache_read_input_tokens?: number
+    output_tokens?: number
+}
+
+/** A content block as the Messages API streams it, its fields filled in by the deltas that follow. */
+type Block = {
+    type: string
+    id?: string
+    name?: string
+    input?: unknown
+    text?: string
+    thinking?: string
+    signature?: string
+}
+
+type ApiEvent = {
+    type: string
+    index: number
+    message: { usage: Usage }
+    content_block: Block
+    // Each field is present on the delta whose `type` names it.
+    delta: {
+        type: string
+        text: string
+        partial_json: string
+        thinking: string
+        signature: string
+        stop_reason: string | null
+    }
+    usage: Usage | undefined
+    error: { message: string }
+}
+
+/** The Messages API, streamed, looping while Claude asks for tools. */
+export function claudeApi(config: ClaudeApiConfig): Provider {
+    // 45.10 — the key is the app's to hand over, and nothing reads one from the environment.
+    if (typeof config.apiKey !== 'string' || config.apiKey === '')
+        throw new Error(
+            'abide: claudeApi was handed no apiKey. RULEBOOK 45.10.',
+        )
+    const { apiKey, baseURL, tools: ownTools, ...body } = config
+    return {
+        async *run(messages, tools, { maxTurns, signal }) {
+            const offered: unknown[] = [...(ownTools ?? [])]
+            for (const tool of tools.list)
+                offered.push({
+                    name: tool.name,
+                    description: tool.description,
+                    input_schema: tool.inputSchema,
+                })
+            const history: { role: string; content: unknown }[] = []
+            for (const message of messages)
+                history.push({ role: message.role, content: message.content })
+            const usage = { input: 0, output: 0 }
+            for (let turn = 1; ; turn++) {
+                const answered = await fetch(
+                    `${baseURL ?? API_URL}/v1/messages`,
+                    {
+                        method: 'POST',
+                        signal,
+                        headers: {
+                            'content-type': 'application/json',
+                            'x-api-key': apiKey,
+                            'anthropic-version': API_VERSION,
+                        },
+                        body: JSON.stringify({
+                            ...body,
+                            ...(offered.length === 0 ? {} : { tools: offered }),
+                            stream: true,
+                            messages: history,
+                        }),
+                    },
+                )
+                // 45.21 — the API's own failure, answered before the first event where it comes first.
+                if (!answered.ok || answered.body === null)
+                    throw refuse(
+                        502,
+                        `The Claude API answered ${answered.status}: ${await answered.text()}`,
+                    )
+                const blocks: Block[] = []
+                const partials: string[] = []
+                const called: Block[] = []
+                let stop = 'end_turn'
+                for await (const chunk of framedStream(
+                    answered.body,
+                    framingPrefix('text/event-stream') as string,
+                )) {
+                    const event = chunk as ApiEvent
+                    switch (event.type) {
+                        case 'message_start':
+                            usage.input += inputOf(event.message.usage)
+                            break
+                        case 'content_block_start':
+                            blocks[event.index] = event.content_block
+                            partials[event.index] = ''
+                            break
+                        case 'content_block_delta': {
+                            const block = blocks[event.index] as Block
+                            const delta = event.delta
+                            if (delta.type === 'text_delta') {
+                                block.text = (block.text ?? '') + delta.text
+                                yield { type: 'text', text: delta.text }
+                            } else if (delta.type === 'input_json_delta')
+                                partials[event.index] =
+                                    partials[event.index] + delta.partial_json
+                            else if (delta.type === 'thinking_delta')
+                                block.thinking =
+                                    (block.thinking ?? '') + delta.thinking
+                            else if (delta.type === 'signature_delta')
+                                block.signature = delta.signature
+                            break
+                        }
+                        case 'content_block_stop': {
+                            const block = blocks[event.index] as Block
+                            if (block.type !== 'tool_use') break
+                            const partial = partials[event.index] as string
+                            // Cut short at `max_tokens`, a call's input is not JSON — and that turn did
+                            // not stop for `tool_use`, so it is never run (45.9).
+                            try {
+                                block.input =
+                                    partial === '' ? {} : JSON.parse(partial)
+                            } catch {
+                                block.input = partial
+                            }
+                            called.push(block)
+                            yield {
+                                type: 'tool',
+                                id: block.id as string,
+                                name: block.name as string,
+                                input: block.input,
+                            }
+                            break
+                        }
+                        case 'message_delta':
+                            stop = event.delta.stop_reason ?? stop
+                            // Cumulative for the message, so taken once, at its end.
+                            usage.output += event.usage?.output_tokens ?? 0
+                            break
+                        case 'error':
+                            // 45.21.
+                            throw refuse(
+                                502,
+                                `The Claude API failed: ${event.error.message}`,
+                            )
+                    }
+                }
+                history.push({ role: 'assistant', content: blocks })
+                if (stop !== 'tool_use' || turn >= maxTurns) {
+                    yield {
+                        type: 'done',
+                        stop: stop === 'tool_use' ? 'max_turns' : stop,
+                        usage,
+                    }
+                    return
+                }
+                const results = await Promise.all(
+                    called.map(
+                        async (
+                            block,
+                        ): Promise<AssistantEvent & { type: 'result' }> => ({
+                            type: 'result',
+                            id: block.id as string,
+                            ...(await tools.call(
+                                block.name as string,
+                                block.input,
+                            )),
+                        }),
+                    ),
+                )
+                const content: unknown[] = []
+                for (const result of results) {
+                    yield result
+                    content.push({
+                        type: 'tool_result',
+                        tool_use_id: result.id,
+                        content: result.text,
+                        is_error: result.failed,
+                    })
+                }
+                // 45.12 — every result of one turn in one message.
+                history.push({ role: 'user', content })
+            }
+        },
+    }
+}
+
+function inputOf(usage: Usage | undefined): number {
+    return (
+        (usage?.input_tokens ?? 0) +
+        (usage?.cache_creation_input_tokens ?? 0) +
+        (usage?.cache_read_input_tokens ?? 0)
+    )
+}

package/src/server/claudeCode.ts

@@ -0,0 +1,187 @@
+// 45.13 — THE CLAUDE CODE ON THE VISITOR'S OWN MACHINE AS A `Provider`, reached through the bridge they
+// paired (`bridgeRelay.ts`). Claude Code runs its own loop there; what this side does is hand it the
+// turn and answer the MCP requests it makes from the `Toolbox` — in this request's scope, as this
+// asker (45.7) — so its tools are the site's and nothing of the visitor's machine is one.
+//
+// CONFIGURED BY CLAUDE CODE'S OWN OPTION NAMES, and only the ones that shape the answer. What would give
+// a site power over the visitor's machine — its own tools, permissions, directory, settings — is not an
+// option here at all: the bridge decides it (45.15, 45.16).
+
+import { mounted } from '#shared/mount.ts'
+import { refuse } from '#shared/refuse.ts'
+import {
+    type AssistantEvent,
+    type AssistantMessage,
+    forwardOf,
+    type Provider,
+} from './assistant.ts'
+import { BRIDGE_VERSION } from './BRIDGE_VERSION.ts'
+import {
+    bridgeOpened,
+    mintCode,
+    openTurn,
+    pairedBridge,
+    watchPairing,
+} from './bridgeRelay.ts'
+import { callerOf } from './callerOf.ts'
+import { appOrigin } from './config.ts'
+import { mcpFailure } from './generatedSurfaces.ts'
+import { Inbox } from './Inbox.ts'
+import { request } from './requestScope.ts'
+
+/** The Claude Code options a site may set for a turn. */
+export type ClaudeCodeConfig = {
+    model?: string
+    fallbackModel?: string
+    systemPrompt?: string
+    appendSystemPrompt?: string
+    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+}
+
+/** Whether this browser's bridge is connected, and the command that pairs one where it is not. */
+export type BridgeStatus = { paired: boolean; command: string | undefined }
+
+/** The visitor's own Claude Code, reached through the bridge paired to their browser. */
+function claudeCodeProvider(config: ClaudeCodeConfig = {}): Provider {
+    return {
+        async *run(messages, tools, { maxTurns, signal }) {
+            const bridge = pairedBridge(askingCaller())
+            // 45.13 — nothing paired is the page's cue to show the command.
+            if (bridge === undefined)
+                throw refuse(
+                    409,
+                    'No Claude Code is paired with this browser. claudeCode.bridgeCommand() is the command that pairs one.',
+                )
+            const turn = openTurn(bridge)
+            bridge.frames.push({
+                type: 'turn',
+                id: turn.id,
+                prompt: foldedPrompt(messages),
+                config,
+                maxTurns,
+            })
+            // 45.18 — a caller hanging up ends the run on the bridge.
+            const cancel = (): void => {
+                bridge.frames.push({ type: 'cancel', turn: turn.id })
+            }
+            signal.addEventListener('abort', cancel)
+            try {
+                for await (const item of turn.inbox) {
+                    if (item.kind === 'event')
+                        yield item.event as AssistantEvent
+                    else if (item.kind === 'mcp')
+                        // 45.17 — answered by the app's own MCP surface, through the turn's `Toolbox`.
+                        void forwardOf(tools)(item.method, item.params)
+                            .catch((thrown: unknown) =>
+                                mcpFailure(-32603, String(thrown)),
+                            )
+                            .then((reply) => {
+                                bridge.frames.push({
+                                    type: 'reply',
+                                    turn: turn.id,
+                                    id: item.id,
+                                    reply,
+                                })
+                            })
+                    else if (item.kind === 'end') return
+                    // 45.21.
+                    else
+                        throw refuse(502, `Claude Code failed: ${item.message}`)
+                }
+            } finally {
+                signal.removeEventListener('abort', cancel)
+                turn.close()
+            }
+        },
+    }
+}
+
+/** The transcript as the one message Claude Code is sent: earlier turns folded above the last. 45.5. */
+function foldedPrompt(messages: AssistantMessage[]): string {
+    const last = (messages.at(-1) as AssistantMessage).content
+    if (messages.length === 1) return last
+    let earlier = ''
+    for (let index = 0; index < messages.length - 1; index++) {
+        const message = messages[index] as AssistantMessage
+        earlier += `<${message.role}>\n${message.content}\n</${message.role}>\n`
+    }
+    return `<conversation>\n${earlier}</conversation>\n\n${last}`
+}
+
+/** The browser asking, which a pairing is to. 45.13. */
+function askingCaller(): string {
+    // 45.19 — the relay is closed until `ABIDE_BRIDGE` opens it, and using it closed is a mistake to name.
+    if (!bridgeOpened())
+        throw new Error(
+            'abide: claudeCode reaches a visitor’s Claude Code through the bridge relay, and ABIDE_BRIDGE has not opened it. RULEBOOK 45.19.',
+        )
+    const caller = callerOf()
+    if (caller === undefined)
+        throw refuse(
+            400,
+            'A Claude Code bridge pairs with a browser, and this request carries none: it has to come from a page.',
+        )
+    return caller
+}
+
+/** The command that pairs a bridge with this browser, and when its code stops standing. 45.14. */
+function bridgeCommand(): { command: string; expires: number } {
+    const { code, expires } = mintCode(askingCaller())
+    const site = `${appOrigin() ?? new URL(request().url).origin}${mounted('')}`
+    return {
+        command: `bunx @abide/bridge@${BRIDGE_VERSION} ${site} ${code}`,
+        expires,
+    }
+}
+
+/**
+ * This browser's pairing as it changes: unpaired with the command to run, then paired the moment a
+ * bridge connects, and unpaired again if it goes. 45.20.
+ */
+async function* bridge(): AsyncGenerator<BridgeStatus> {
+    const caller = askingCaller()
+    const signal = request().signal
+    // A change landing while the loop was not waiting — paused at its `yield` — stays queued, so it
+    // looks again; a look that finds nothing new yields nothing.
+    const changes = new Inbox<undefined>()
+    const waiting = changes[Symbol.asyncIterator]()
+    const rouse = (): void => changes.push(undefined)
+    const unwatch = watchPairing(caller, rouse)
+    signal.addEventListener('abort', rouse)
+    let pairing: { command: string; expires: number } | undefined
+    let said = ''
+    try {
+        while (!signal.aborted) {
+            const paired = pairedBridge(caller) !== undefined
+            if (
+                !paired &&
+                (pairing === undefined || pairing.expires <= Date.now())
+            )
+                pairing = bridgeCommand()
+            const status: BridgeStatus = {
+                paired,
+                command: paired ? undefined : pairing?.command,
+            }
+            const saying = `${status.paired} ${status.command}`
+            if (saying !== said) {
+                said = saying
+                yield status
+            }
+            // A code that expires while nothing is paired is replaced with a fresh one.
+            const renew = paired
+                ? undefined
+                : setTimeout(rouse, (pairing?.expires ?? 0) - Date.now())
+            await waiting.next()
+            clearTimeout(renew)
+        }
+    } finally {
+        signal.removeEventListener('abort', rouse)
+        unwatch()
+    }
+}
+
+/** The visitor's own Claude Code as a provider, with the pairing that reaches it. */
+export const claudeCode: typeof claudeCodeProvider & {
+    bridge: typeof bridge
+    bridgeCommand: typeof bridgeCommand
+} = Object.assign(claudeCodeProvider, { bridge, bridgeCommand })

package/src/server/clientBuildOptions.ts

@@ -0,0 +1,49 @@
+import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
+import { CLIENT_ENTRY } from './CLIENT_BUILD.ts'
+
+/**
+ * The `Bun.build` options for the client bundle both lanes build.
+ *
+ * `abide build` builds it to disk and `abide dev` in memory. 30.8 says dev resolves an address the
+ * way the built app does, so what decides resolution is written once here and each lane adds only
+ * where the output goes and how it is named.
+ */
+export function clientBuildOptions(
+    entryDirectory: string,
+    plugins: Bun.BunPlugin[],
+    publicAddresses: string[],
+) {
+    return {
+        entrypoints: [`${entryDirectory}/${CLIENT_ENTRY}.ts`] as string[],
+        // 16.28, 16.29 — a handler module is its wrapper here, and the rest of `server/` refuses.
+        plugins,
+        target: 'browser',
+        format: 'esm',
+        splitting: true,
+        metafile: true,
+        // 36.15 — a stylesheet's `url('/fonts/…')` is the public file's address, not a path here,
+        // and `Bun.build` reads a leading `/` as a path on this disk and fails on it not being
+        // there. The list is the files that exist rather than every `/…`: a URL naming nothing the
+        // app serves is still worth a build error.
+        external: publicAddresses,
+    } as const
+}
+
+// From the bundle's own directory up to the app's root: `../../` below `/__abide/client`.
+const UP_TO_ROOT = '../'.repeat(CLIENT_ADDRESS.split('/').length - 1)
+
+/**
+ * A built stylesheet with every root-absolute `url()` written relative to the bundle's directory.
+ *
+ * 16.10, 36.15 — THE SAME MECHANISM AS THE HANDLER WRAPPERS: the address is written relative to
+ * where the bundle is served and the browser resolves it against the sheet, so one build serves
+ * at the root and below a mount. What survives the build as `url(/…)` is a public file's address
+ * (the `external` list above), and the browser would resolve it against the origin. `//` is
+ * another host's.
+ */
+export function stylesheetUnderMount(css: string): string {
+    return css.replace(
+        /url\((["']?)\/(?!\/)/g,
+        (_whole, quote: string) => `url(${quote}${UP_TO_ROOT}`,
+    )
+}

package/src/server/coerceArgs.ts

@@ -0,0 +1,110 @@
+// 19.7 — A `GET` OR `DELETE`'s TEXT ARGS, COERCED FROM THE TYPE THE `JsonSchema` DECLARES, before
+// anything validates them. A URL carries text, so `?id=42` is `'42'` until the schema says the member
+// is a number. Coercion is the pipeline's and not the schema's (19.6): the schema is handed what this
+// made of the text, and refuses what would not coerce.
+//
+// Read off a `Schema` built by `jsonSchema`, where the document is exposed; a schema with no document
+// has declared no types, and its args stay the text they arrived as.
+
+import { numberFromText } from '#shared/numberFromText.ts'
+import { type Gated, gateOf } from '#shared/reactive/argsContract.ts'
+import { bareName } from '#shared/rpcRequest.ts'
+
+export type Document = {
+    type?: string | string[]
+    properties?: Record<string, Document>
+    items?: Document
+}
+
+/** The document a handler's `args` schema declares, or `undefined`. */
+export function argsDocumentOf(handler: Gated<unknown>): Document | undefined {
+    const gate = gateOf(handler) as
+        | { '~standard'?: { jsonSchema?: { input?: () => unknown } } }
+        | undefined
+    const document = gate?.['~standard']?.jsonSchema?.input?.()
+    return document !== null && typeof document === 'object'
+        ? (document as Document)
+        : undefined
+}
+
+/**
+ * Name and value pairs as args: a name given more than once is a list, one given once its text.
+ *
+ * 16.18 — a query's and a form's members, and 38.62 — `abide call`'s `name=value` words, alike.
+ */
+export function collapsed(
+    entries: URLSearchParams | FormData,
+): Record<string, string | string[]> {
+    const args: Record<string, string | string[]> = {}
+    for (const name of new Set(entries.keys())) {
+        const values = entries.getAll(name) as string[]
+        args[name] = values.length === 1 ? (values[0] as string) : values
+    }
+    return args
+}
+
+/**
+ * The text args, each member coerced to the type `document` declares.
+ *
+ * `query` is the raw `?…` the args were read from: `URLSearchParams` reads `rpcRequest`'s empty
+ * list, a bare name, as `''` — the same as `tags=`, the list `['']` — so a declared array tells the
+ * two apart there. A text member keeps the `''`.
+ */
+export function coerceArgs(
+    args: Record<string, string | string[]> | undefined,
+    document: Document | undefined,
+    query: string,
+): unknown {
+    if (args === undefined || document?.properties === undefined) return args
+    const coerced: Record<string, unknown> = {}
+    for (const [name, text] of Object.entries(args)) {
+        const member = document.properties[name]
+        if (member === undefined) coerced[name] = text
+        else if (
+            text === '' &&
+            typesOf(member).includes('array') &&
+            `&${query.slice(1)}&`.includes(`&${bareName(name)}&`)
+        )
+            coerced[name] = []
+        else coerced[name] = coerceMember(text, member)
+    }
+    return coerced
+}
+
+function typesOf(member: Document): string[] {
+    if (member.type === undefined) return []
+    return Array.isArray(member.type) ? member.type : [member.type]
+}
+
+function coerceMember(text: string | string[], member: Document): unknown {
+    const types = typesOf(member)
+    // A list is its member repeated, and one given once still answers a declared array.
+    if (types.includes('array')) {
+        const items = Array.isArray(text) ? text : [text]
+        const item = member.items
+        return item === undefined
+            ? items
+            : items.map((each) => coerceScalar(each, item))
+    }
+    if (Array.isArray(text)) return text
+    return coerceScalar(text, member)
+}
+
+/**
+ * The text as the first declared type it reads as, in the order the schema lists them.
+ *
+ * Text that reads as none stays text, for the schema to refuse.
+ */
+function coerceScalar(text: string, member: Document): unknown {
+    for (const type of typesOf(member)) {
+        if (type === 'string') return text
+        if (type === 'number' || type === 'integer') {
+            const number = numberFromText(text)
+            if (number !== undefined) return number
+        }
+        if (type === 'boolean' && (text === 'true' || text === 'false'))
+            return text === 'true'
+        if (type === 'null' && text === 'null') return null
+    }
+    return text
+}