@abide/abide 0.124.1 → 0.125.0

package/src/server/answerSocket.ts

@@ -26,6 +26,7 @@ import type { FollowedHandler } from './mountHandlers.ts'
 import { sendOrClose } from './muxUpgrade.ts'
 import {
     inOpenScope,
+    RECEIVED_FROM,
     releaseScope,
     type RequestScope,
     scopeFor,
@@ -139,11 +140,11 @@ export class MuxConnection {
             upgrade.url,
         )
         // NO `received`: an upgraded connection has no http idle timeout for 16.23 to set.
-        this.scope = scopeFor(
-            new Request(upgrade, { signal: this.hangUp.signal }),
-            undefined,
-            mux.app,
-        )
+        const request = new Request(upgrade, { signal: this.hangUp.signal })
+        // 22.12 — every frame came from where the upgrade did.
+        if (RECEIVED_FROM.has(upgrade))
+            RECEIVED_FROM.set(request, RECEIVED_FROM.get(upgrade) ?? null)
+        this.scope = scopeFor(request, undefined, mux.app)
         // 22.10 — the headers went out with the upgrade, so nothing a frame writes is carried.
         this.scope.applied = true
     }

package/src/server/answerWorker.ts

@@ -7,7 +7,6 @@
 
 import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
 import { KEEP_HEADER } from '#shared/KEEP_HEADER.ts'
-import { KEEP_OPENED } from '#shared/KEEP_OPENED.ts'
 import { KEPT_HEADER } from '#shared/KEPT_HEADER.ts'
 import { MOUNT, mounted } from '#shared/mount.ts'
 import { NAVIGATION_HEADER } from '#shared/NAVIGATION_HEADER.ts'
@@ -42,7 +41,7 @@ async function dropOurs(keeping) {
 }
 `
 
-// 45.3 through 45.8, 45.13, 45.17 through 45.21, and 45.24.
+// 45.3 through 45.8, 45.13, and 45.17 through 45.26.
 const SAVING = `
 self.addEventListener('install', (event) => {
     event.waitUntil(
@@ -149,31 +148,33 @@ function marked(saved) {
     })
 }
 
-// A page as the worker asks for it, whether a navigation or the worker keeping an open window's:
-// past the browser's cache, as a page kept, and with its redirects left to the page — one followed
-// would be saved under the address it was asked at, holding where it led (RULEBOOK 45.4, 45.21,
-// 45.23).
-function pageRequest(url, headers, keep) {
+// A page no navigation is asking for, as the worker asks for it: past the browser's cache, as a page
+// kept, and with its redirects left unfollowed — one followed would be saved under the address it was
+// asked at, holding where it led (RULEBOOK 45.4, 45.21, 45.23).
+function pageRequest(url, headers) {
     const asking = new Headers(headers)
-    asking.set(KEEP, keep)
+    asking.set(KEEP, '1')
     return new Request(url, { headers: asking, redirect: 'manual', cache: 'no-cache' })
 }
 
-// 45.21 — PAST THE BROWSER'S OWN CACHE, which holds the same answers under the same headers and would
-// hand a revalidation the copy it is replacing. A navigation's request takes no init of its own, so it
-// is asked again by address, its redirects left to the page as a navigation's are — and 45.23, as a
-// page kept, which a script's fetch is not otherwise told from (RULEBOOK 41.29, 41.30), and as the
-// page the navigation opens where opened says it is, which then hydrates from what it seeded.
+// 45.25 — THE NAVIGATION ASKED AS ITSELF: any init rebuilds a navigation's request as a script's
+// fetch, and a proxy in front of the app tells the two apart — one sending a page load to sign-in
+// answers a fetch 401. As itself its mode is navigate, the page that hydrates (RULEBOOK 41.29), its redirects
+// left to the browser. Anything else is asked past the browser's own cache (RULEBOOK 45.21), which
+// holds the same answers under the same headers and would hand a revalidation the copy it is replacing
+// — and a page as one kept, which a script's fetch is not otherwise told from (RULEBOOK 45.23, 41.30).
 async function fromNetwork(event, page, opened) {
     const request = event.request
-    const asked = page
-        ? pageRequest(request.url, request.headers, opened ? OPENED : '1')
-        : new Request(request, { cache: 'no-cache' })
+    const asked = opened
+        ? request
+        : page
+          ? pageRequest(request.url, request.headers)
+          : new Request(request, { cache: 'no-cache' })
     const since = drops
     const response = await fetch(asked)
     // A copy nothing reads is a tee holding every chunk, so one is cloned only to be saved.
     const copy = kept(response) ? response.clone() : undefined
-    event.waitUntil(keep(request, copy, since, response.headers.has(PRINCIPAL)))
+    event.waitUntil(keep(request, response, copy, since))
     return response
 }
 
@@ -181,11 +182,11 @@ async function fromNetwork(event, page, opened) {
 // window's as the worker activates, and an address the router reached.
 function keepPage(url) {
     const since = drops
-    return fetch(pageRequest(url, undefined, '1')).then((response) => {
+    return fetch(pageRequest(url)).then((response) => {
         // Nothing reads this answer, so one 45.3 or 45.4 turns away is let go here.
         const copy = kept(response) ? response : undefined
         if (copy === undefined) response.body?.cancel()
-        return keep(new Request(url), copy, since, response.headers.has(PRINCIPAL))
+        return keep(new Request(url), response, copy, since)
     }, () => {})
 }
 
@@ -273,12 +274,23 @@ function dropSaved() {
 // Saves a copy 45.3 and 45.4 let through where no drop has come since its request was asked — after
 // the drop its own answer makes where that answer rotated the principal — and cancels one where one has.
 // One any caller may be answered is saved whenever it was asked, since no caller's cookies made it.
-async function keep(request, copy, since, rotated) {
-    if (rotated) {
+async function keep(request, response, copy, since) {
+    if (response.headers.has(PRINCIPAL)) {
         await dropSaved()
         since = drops
     }
-    if (copy === undefined) return
+    // 45.26 — AN ANSWER NOT SAVED STILL REPLACES THE COPY: a redirect or a 401 is what the address
+    // answers now, and a copy left standing would answer every load in its stale-while-revalidate
+    // window in its place — a session lapsed behind a sign-in proxy never reaching the sign-in. A
+    // server error is no answer to replace a copy with.
+    if (copy === undefined) {
+        if (response.status >= 500) return
+        await Promise.all([
+            caches.open(SAVED).then((cache) => cache.delete(request)),
+            caches.open(SHARED).then((cache) => cache.delete(request)),
+        ])
+        return
+    }
     const shared = directivesOf(copy).has('public')
     if (!shared && since !== drops) return copy.body?.cancel()
     // An address whose answer went public or private since leaves no copy behind for savedCopy to
@@ -338,7 +350,6 @@ export function answerWorker(manifest: Manifest | undefined): Response {
         script = `${CACHES}const PRINCIPAL = ${JSON.stringify(PRINCIPAL_HEADER)}
 const KEPT = ${JSON.stringify(KEPT_HEADER)}
 const KEEP = ${JSON.stringify(KEEP_HEADER)}
-const OPENED = ${JSON.stringify(KEEP_OPENED)}
 const NAVIGATION = ${JSON.stringify(NAVIGATION_HEADER)}
 const REACHED = ${JSON.stringify(REACHED_MESSAGE)}
 // 45.4 — the types a stream 16.32 frames, which has no end to save.

package/src/server/assistant.ts

@@ -10,35 +10,28 @@
 // another request's scope — `claudeCode` answers one from the bridge's — and the call is still this
 // asker's.
 
+import type {
+    AssistantContent,
+    AssistantEvent,
+    AssistantMessage,
+} from '#shared/AssistantEvent.ts'
+import { IMAGE_TYPES } from '#shared/IMAGE_TYPES.ts'
 import { namedLogger } from '#shared/log.ts'
-import { refuse } from '#shared/refuse.ts'
+import { mounted } from '#shared/mount.ts'
+import { aborted, refuse } from '#shared/refuse.ts'
 
 import { type McpReply, McpSurface } from './generatedSurfaces.ts'
-import { IMAGE_TYPES } from './IMAGE_TYPES.ts'
 import { request, within } from './requestScope.ts'
+import type { Listed } from './surfaceOf.ts'
 
-/** A piece of a turn: words, or an image as base64 with its type. */
-export type AssistantContent =
-    | { type: 'text'; text: string }
-    | { type: 'image'; data: string; mimeType: string }
-
-/** One turn of the transcript a caller sends: its words, or its pieces in order. */
-export type AssistantMessage = {
-    role: 'user' | 'assistant'
-    content: string | AssistantContent[]
-}
-
-/** What a conversation yields, the same from every provider. */
-export type AssistantEvent =
-    | { type: 'text'; text: string }
+/**
+ * An `AssistantEvent` as a `Provider` yields it: a tool call named, and its result in words, with what
+ * `assistant` reads off the app's own surface for both — the handler, and the value — still to come.
+ */
+export type ProviderEvent =
+    | Exclude<AssistantEvent, { type: 'tool' | 'result' }>
     | { type: 'tool'; id: string; name: string }
-    | { type: 'input'; id: 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 = {
@@ -68,11 +61,15 @@ export type Provider = {
         messages: (AssistantMessage & { content: AssistantContent[] })[],
         tools: Toolbox,
         limits: { maxTurns: number; signal: AbortSignal },
-    ): AsyncGenerator<AssistantEvent>
+    ): AsyncGenerator<ProviderEvent>
 }
 
 /** What `assistant` takes beside a provider, the same for every one. */
-export type AssistantOptions = { mcp?: boolean; maxTurns?: number }
+export type AssistantOptions = {
+    mcp?: boolean
+    maxTurns?: number
+    signal?: AbortSignal
+}
 
 const MAX_TURNS = 10
 const ASSISTANT_LOG = namedLogger('abide:assistant')
@@ -118,19 +115,128 @@ export async function* assistant(
                 )
         }
     }
-    const tools = toolboxOver(
-        options.mcp === true ? appSurface() : NO_SURFACE,
-        askerOf(request()),
-    )
-    const signal = request().signal
-    const events = provider.run(turns, tools, {
-        maxTurns: options.maxTurns ?? MAX_TURNS,
+    const surface = options.mcp === true ? appSurface() : NO_SURFACE
+    const tools = toolboxOver(surface, askerOf(request()))
+    // 44.57 — the caller's signal and the request's are one: either ends the conversation.
+    const signal =
+        options.signal === undefined
+            ? request().signal
+            : AbortSignal.any([request().signal, options.signal])
+    const events = endedBy(
+        provider.run(turns, tools, {
+            maxTurns: options.maxTurns ?? MAX_TURNS,
+            signal,
+        }),
         signal,
-    })
-    // 28.7 — a closed namespace runs the provider's stream untouched.
+    )
+    // 28.7 — a closed namespace pays for no line.
     yield* ASSISTANT_LOG.enabled()
-        ? traced(events, messages.length, signal)
-        : events
+        ? traced(read(events, surface), messages.length, signal)
+        : read(events, surface)
+}
+
+/**
+ * `events` until `signal` aborts, then `aborted`. 44.57.
+ *
+ * THE ABORT DOES NOT WAIT FOR THE PROVIDER: one stuck in an await it was handed no signal for — a
+ * bridge that never answers — is asked to return and left to, and the conversation ends now. An
+ * abort read ahead of a throw, as `traced` reads it: a provider that throws as it unwinds was ended
+ * by the abort.
+ */
+async function* endedBy(
+    events: AsyncGenerator<ProviderEvent>,
+    signal: AbortSignal,
+): AsyncGenerator<ProviderEvent> {
+    // A STEP RACES ITS OWN ABORT: one promise pending for the whole conversation would keep a
+    // reaction per event, none freed until it ends.
+    let rejectStep: (reason: unknown) => void = () => {}
+    const stop = (): void => rejectStep(aborted())
+    signal.addEventListener('abort', stop, { once: true })
+    try {
+        for (;;) {
+            if (signal.aborted) throw aborted()
+            const step = await Promise.race([
+                events.next(),
+                new Promise<never>((_, reject) => {
+                    rejectStep = reject
+                }),
+            ])
+            if (step.done === true) return
+            yield step.value
+        }
+    } catch (thrown) {
+        throw signal.aborted ? aborted() : thrown
+    } finally {
+        signal.removeEventListener('abort', stop)
+        // A provider still awaiting returns once that await settles, and nobody waits for it.
+        events.return(undefined).catch(() => {})
+    }
+}
+
+/** A called tool's handler, and whether its answer is a value read as JSON (19.21). */
+type Called = {
+    handler: { method: Listed['method']; address: string } | undefined
+    valued: boolean
+}
+
+const NOT_THE_APPS: Called = { handler: undefined, valued: false }
+
+/**
+ * `events` with each call's handler, and each answer's value, read off `surface`. 44.48, 44.49.
+ *
+ * READ HERE RATHER THAN BY EACH PROVIDER, so a provider the app wrote yields the same events abide's
+ * do (44.2): a provider names the tool as the `Toolbox` lists it (44.50), and the rest is the surface's.
+ */
+async function* read(
+    events: AsyncGenerator<ProviderEvent>,
+    surface: McpSurface,
+): AsyncGenerator<AssistantEvent> {
+    const calls = new Map<string, Called>()
+    for await (const event of events) {
+        if (event.type === 'tool') {
+            const tool = surface.tool(event.name)
+            const called: Called =
+                tool === undefined
+                    ? NOT_THE_APPS
+                    : {
+                          // 16.10 — the address an `Rpc` carries, under the mount.
+                          handler: {
+                              method: tool.method,
+                              address: mounted(tool.address),
+                          },
+                          valued: tool.result !== undefined,
+                      }
+            calls.set(event.id, called)
+            yield {
+                type: 'tool',
+                id: event.id,
+                name: event.name,
+                handler: called.handler,
+            }
+        } else if (event.type === 'result') {
+            const called = calls.get(event.id) ?? NOT_THE_APPS
+            yield {
+                type: 'result',
+                id: event.id,
+                text: event.text,
+                failed: event.failed,
+                handler: called.handler,
+                value:
+                    called.valued && !event.failed
+                        ? valueOf(event.text)
+                        : undefined,
+            }
+        } else yield event
+    }
+}
+
+/** An answer's words as the JSON value they spell, or `undefined` where they spell none. */
+function valueOf(text: string): unknown {
+    try {
+        return JSON.parse(text)
+    } catch {
+        return undefined
+    }
 }
 
 /**

package/src/server/banner.ts

@@ -9,15 +9,16 @@ 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.
+ * `http://` it finds (`addressOf` in the tests). 38.58, 38.136 — the network rows follow it where the
+ * listener binds every interface, which `Bun.serve` given no `hostname` does whatever `url` says, and
+ * are left out where `hostname` names one interface.
  */
 export function banner(
     host: string,
     command: string,
     identity: AppPackage,
     server: Bun.Server<unknown>,
+    hostname: string | undefined,
 ): string {
     const color = useColor()
     const paint = (code: string, text: string): string =>
@@ -29,8 +30,11 @@ export function banner(
             ? ''
             : `  ${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`
+    const everyInterface =
+        hostname === undefined || hostname === '0.0.0.0' || hostname === '::'
+    if (everyInterface)
+        for (const address of networkAddresses())
+            text += `  ${paint('32', '➜')}  ${paint('1', 'Network:')}  ${paint('36', `${server.url.protocol}//${address}:${server.port}/`)}\n`
     return text
 }
 

package/src/server/bridgeRelay.ts

@@ -22,7 +22,7 @@ import { refuse } from '#shared/refuse.ts'
 import { answered } from './answerFailure.ts'
 import { bodyWithin } from './answerRpc.ts'
 import { framed } from './answerValue.ts'
-import type { AssistantEvent } from './assistant.ts'
+import type { ProviderEvent } from './assistant.ts'
 import { Inbox } from './Inbox.ts'
 import { randomToken } from './randomToken.ts'
 import { RESUME_MILLISECONDS } from './RESUME_MILLISECONDS.ts'
@@ -126,7 +126,7 @@ export async function* runTurn({
     /** Never rejects: its failure is a reply too. */
     answer: (method: string, params: unknown) => Promise<unknown>
     signal: AbortSignal
-}): AsyncGenerator<AssistantEvent> {
+}): AsyncGenerator<ProviderEvent> {
     const bridge = BY_KEY.get(pairingKey(caller, signedIn))
     // 44.13, 44.33 — nothing paired by this sign-in is the page's cue to show the command.
     if (bridge === undefined)
@@ -146,7 +146,7 @@ export async function* runTurn({
     signal.addEventListener('abort', cancel)
     try {
         for await (const item of inbox) {
-            if (item.kind === 'event') yield item.event as AssistantEvent
+            if (item.kind === 'event') yield item.event as ProviderEvent
             else if (item.kind === 'mcp')
                 void answer(item.method, item.params).then((reply) => {
                     bridge.frames.push({

package/src/server/callerOf.ts

@@ -46,6 +46,11 @@ export function callerOrMint(): string {
     return callerOf() ?? mintCaller(scope)
 }
 
+/** This request's caller, given rather than read off its cookie, with no cookie written. 42.21. */
+export function presumeCaller(caller: string): void {
+    within('App caller').caller = caller
+}
+
 /**
  * Mints a fresh caller for this request, sets its cookie, and returns it.
  *

package/src/server/claudeCode.ts

@@ -8,17 +8,15 @@
 // directory, settings — is not an option here at all, and its built-in `tools` are a request the visitor
 // grants or does not: the bridge decides (44.15, 44.16, 44.29).
 
+import type {
+    AssistantContent,
+    AssistantMessage,
+} from '#shared/AssistantEvent.ts'
 import { BRIDGE_SCHEME } from '#shared/BRIDGE_SCHEME.ts'
 import { mounted } from '#shared/mount.ts'
 import { refuse } from '#shared/refuse.ts'
 
-import {
-    type AssistantContent,
-    type AssistantMessage,
-    blocksOf,
-    forwardOf,
-    type Provider,
-} from './assistant.ts'
+import { blocksOf, forwardOf, type Provider } from './assistant.ts'
 import { BRIDGE_VERSION } from './BRIDGE_VERSION.ts'
 import { mintCode, pairingStatus, runTurn } from './bridgeRelay.ts'
 import { callerOf } from './callerOf.ts'
@@ -45,12 +43,13 @@ type PairingOptions = Pick<ClaudeCodeConfig, 'tools'>
 
 /**
  * Whether this browser's bridge is connected, and the command and the link that pair one where it is
- * not.
+ * not, with the command that installs the app the link opens.
  */
 export type BridgeStatus = {
     paired: boolean
     command: string | undefined
     link: string | undefined
+    install: string | undefined
 }
 
 /** The visitor's own Claude Code, reached through the bridge paired to their browser. */
@@ -123,17 +122,21 @@ function askingCaller(): string {
 function bridgeCommand(options: PairingOptions = {}): {
     command: string
     link: string
+    install: string
     expires: number
 } {
     const { code, expires } = mintCode(askingCaller(), signedInAs())
     return { ...commandFor(code, options), expires }
 }
 
-/** The command and the link that pair a bridge by `code`, granting `tools`. */
+/**
+ * The command and the link that pair a bridge by `code`, granting `tools`, and the command that
+ * installs the app the link opens — of the release the command runs, 44.56.
+ */
 function commandFor(
     code: string,
     { tools }: PairingOptions,
-): { command: string; link: string } {
+): { command: string; link: string; install: string } {
     const site = `${appOrigin() ?? new URL(request().url).origin}${mounted('')}`
     const granted = tools?.length ? tools.join(',') : undefined
     const query = new URLSearchParams({ site, code, version: BRIDGE_VERSION })
@@ -142,6 +145,7 @@ function commandFor(
     return {
         command: `bunx @abide/bridge@${BRIDGE_VERSION} ${site} ${code}${grant}`,
         link: `${BRIDGE_SCHEME}://pair?${query}`,
+        install: `bunx @abide/bridge@${BRIDGE_VERSION} install`,
     }
 }
 
@@ -159,7 +163,12 @@ async function* bridge(
         request().signal,
     ))
         yield code === undefined
-            ? { paired: true, command: undefined, link: undefined }
+            ? {
+                  paired: true,
+                  command: undefined,
+                  link: undefined,
+                  install: undefined,
+              }
             : { paired: false, ...commandFor(code, options) }
 }
 

package/src/server/commands.ts

@@ -245,10 +245,11 @@ function usage(host: Host, commands: Row[]): string {
             text += `  ${command.padEnd(width)}  ${meaning}\n`
     if (!sourced)
         return `${text}
-  --port     the listen port the app is served on
-  --url      the running app the shell, call, watch, openapi and mcp talk to
-  --method   the method call sends, where the handler answers more than one
-  --version  the version of this executable's app
+  --port      the listen port the app is served on
+  --hostname  the interface it listens on — every one where none is named
+  --url       the running app the shell, call, watch, openapi and mcp talk to
+  --method    the method call sends, where the handler answers more than one
+  --version   the version of this executable's app
 `
     text += `
   --root       the app's source directory, where its pages sit —
@@ -256,6 +257,7 @@ function usage(host: Host, commands: Row[]): string {
   --out        where the build goes, beside the app by default; the file compile and
                bundle write — named after the app, where you stand
   --port       the listen port for dev, start and the shell's app
+  --hostname   the interface they listen on — every one where none is named
   --url        the running app the shell, call, watch, openapi and mcp talk to
   --target     the platform compile builds for — linux-x64, darwin-arm64, windows-x64…
   --platforms  several of them, comma-separated, one executable each
@@ -291,6 +293,8 @@ function parseFlags(argv: string[]) {
             // `PORT` and then falls back to 3000 — `abide dev` scanning on from there, 38.63 — and
             // a default written here would take that away from every host that sets it.
             port: { type: 'string' },
+            // NO DEFAULT EITHER: `Bun.serve` given none binds every interface (38.136).
+            hostname: { type: 'string' },
             url: { type: 'string' },
             method: { type: 'string' },
             target: { type: 'string' },
@@ -321,14 +325,17 @@ async function served(
     process.env.NODE_ENV ??= 'production'
     const booted = await booting(host, app, given)
     if (typeof booted === 'number') return booted
-    const port = given.values.port
-    await booted.listen(port === undefined ? {} : { port: Number(port) })
+    const { port, hostname } = given.values
+    await booted.listen({
+        ...(port === undefined ? {} : { port: Number(port) }),
+        ...(hostname === undefined ? {} : { hostname }),
+    })
     stopOnSignalOrFault(booted)
     const server = LISTENING.server as Bun.Server<unknown>
     return {
         app: booted,
         url: withoutTrailingSlash(server.url.href),
-        heading: banner(host.name, 'start', app.package, server),
+        heading: banner(host.name, 'start', app.package, server, hostname),
     }
 }