@abide/abide 0.123.1 → 0.123.3

package/src/server/argsContract.ts

@@ -0,0 +1,209 @@
+// WHAT A CALL'S ARGS ARE BEFORE ITS HANDLER SEES THEM, on a server: the schema a handler's args are
+// read by, out of the sources it has, and the args a call off the wire is answered with — over http
+// (16.2) and a `GET` followed over the socket mux (18.3). Each lane reads the args off its own
+// transport and answers a refusal in its own form; what every way of calling a handler shares, in
+// process too, is `acceptedArgs` (`#shared/reactive/argsContract.ts`), which this ends in.
+//
+// 19.7 — 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. A schema with no document has declared no types, and its
+// args stay the text they arrived as.
+
+import { DERIVED_ARGS } from '#shared/DERIVED_ARGS.ts'
+import { isRecord } from '#shared/isRecord.ts'
+import type { JsonValue } from '#shared/JsonValue.ts'
+import { numberFromText } from '#shared/numberFromText.ts'
+import { bareName } from '#shared/queryText.ts'
+import {
+    acceptedArgs,
+    type Gated,
+    gateOf,
+    type HeldToAnnotation,
+} from '#shared/reactive/argsContract.ts'
+import { refuse } from '#shared/refuse.ts'
+import { validateJson } from '#shared/validateJson.ts'
+
+import type { Mounted } from './answerRpc.ts'
+
+export type Document = {
+    type?: string | string[]
+    properties?: Record<string, Document>
+    items?: Document
+}
+
+// Each handler's document, read once: 19.7, 20.11 — a third-party schema converts itself on every
+// probe. 19.9 — the one its annotation derives is filed here by `derivedArgs`.
+const DOCUMENTS = new WeakMap<object, Document | undefined>()
+
+const NO_PARAMETERS: Record<string, string | string[]> = {}
+
+/**
+ * The document a handler's args are read by: the one its `args` schema declares, or else the one the
+ * build derived off its annotation (`derivedArgs`), or `undefined`.
+ */
+export function argsDocumentOf(handler: Gated<unknown>): Document | undefined {
+    if (DOCUMENTS.has(handler)) return DOCUMENTS.get(handler)
+    const document = declaredDocument(handler)
+    DOCUMENTS.set(handler, document)
+    return document
+}
+
+function declaredDocument(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
+}
+
+/**
+ * Holds `handler`'s args to `schema`, the one the build derived off its annotation, for every call
+ * of it from now on: in process and over the wire (15.8, 19.9).
+ *
+ * What the module a handler is loaded through calls once its handler is built — a handler file's
+ * face and a `<script server>`'s module — so the schema is there wherever the handler can be
+ * called, whether or not an app mounted it. Not where its `args` gate publishes a document of its
+ * own, which holds the args itself (19.7). Args that did not come are held as an empty record: a
+ * schema is only derived where the handler's args are a required record, so a required member
+ * missing is refused, not read off nothing.
+ */
+export function derivedArgs(
+    handler: HeldToAnnotation & Gated<unknown>,
+    schema: JsonValue,
+): void {
+    // Held already, by the module it loaded through, to the schema its row names as well.
+    if (handler[DERIVED_ARGS] !== undefined) return
+    const declared = declaredDocument(handler)
+    DOCUMENTS.set(handler, declared ?? (schema as Document))
+    if (declared === undefined)
+        handler[DERIVED_ARGS] = (args) => validateJson(schema, args ?? {})
+}
+
+/**
+ * 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.61 — `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 args a call over the wire is answered with, out of the args it sent: the parameters its route
+ * matched laid in, the text a URL or a form carried coerced where `query` says the args are text,
+ * then `acceptedArgs`. Throws the refusal where they are not accepted.
+ *
+ * `query` is the raw `?…` the args were read from — `''` for a form, `undefined` for JSON.
+ * 16.65 — the path's parameters, whatever the method. 16.66 — one the query or the body names as well
+ * is refused rather than one of the two chosen. A JSON body's members are typed already, so the
+ * path's text is coerced to the declared types before it joins them (19.7); text args are coerced
+ * with the rest of the text.
+ */
+export function argsFor(
+    handler: Mounted['handler'],
+    sent: unknown,
+    query: string | undefined,
+    parameters: Record<string, string | string[]> = NO_PARAMETERS,
+): unknown {
+    const document = argsDocumentOf(handler)
+    let args = sent
+    let none = true
+    for (const name in parameters) {
+        none = false
+        if (isRecord(sent) && name in sent)
+            throw refuse(
+                400,
+                `The parameter '${name}' is in the path and in the request as well.`,
+            )
+    }
+    if (!none) {
+        const fromPath =
+            query === undefined
+                ? (coerceArgs(parameters, document, '') as Record<
+                      string,
+                      unknown
+                  >)
+                : parameters
+        args = isRecord(sent) ? { ...sent, ...fromPath } : { ...fromPath }
+    }
+    if (query !== undefined)
+        args = coerceArgs(
+            args as Record<string, string | string[]> | undefined,
+            document,
+            query,
+        )
+    return acceptedArgs(handler, args)
+}
+
+/**
+ * The text args, each member coerced to the type `document` declares.
+ *
+ * `URLSearchParams` reads `rpcRequest`'s empty list, a bare name, as `''` — the same as `tags=`, the
+ * list `['']` — so a declared array tells the two apart by `query`. A text member keeps the `''`.
+ */
+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
+}

package/src/server/bridgeRelay.ts

@@ -12,6 +12,9 @@
 // in there when its code was minted (44.33), for as long as the bridge's stream is open, or
 // resumable. HELD IN THIS PROCESS: an app served by several needs a visitor's requests to reach the
 // one its bridge dialed.
+//
+// Every frame on that stream is written here; what the rest of the server sees is a turn run, a
+// pairing's status as it changes, and a pairing code.
 
 import { isFailed } from '#shared/Failed.ts'
 import { refuse } from '#shared/refuse.ts'
@@ -19,14 +22,17 @@ 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 { Inbox } from './Inbox.ts'
 import { randomToken } from './randomToken.ts'
+import { RESUME_MILLISECONDS } from './RESUME_MILLISECONDS.ts'
+import { onSignInChanged } from './signInChanged.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 = {
+type TurnItem = {
     kind: 'event' | 'mcp' | 'end' | 'fail'
     event: unknown
     id: number
@@ -36,7 +42,7 @@ export type TurnItem = {
 }
 
 /** One paired bridge: what it is sent, and the turns it is answering. */
-export type Bridge = {
+type Bridge = {
     /** The browser and the sign-in it is paired to (`pairingKey`). 44.33. */
     key: string
     token: string
@@ -53,8 +59,6 @@ export type Bridge = {
 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
-/** How long a pairing whose stream dropped waits to be resumed. 44.26. */
-export const RESUME_MILLISECONDS = 60_000
 
 const CODES = new Map<string, { key: string; expires: number }>()
 const BY_KEY = new Map<string, Bridge>()
@@ -65,6 +69,13 @@ const FOLLOWERS = new Map<
     Set<(caller: string, signedIn: string) => void>
 >()
 
+// 44.34 — A STATUS STREAM OPENED BEFORE A SIGN-IN carries the cookies it was opened with, so it hears
+// of the new one, or of the caller a sign-out rotated it to (26.9), here rather than off its own
+// request.
+onSignInChanged((caller, now, signedIn) => {
+    for (const follow of FOLLOWERS.get(caller) ?? []) follow(now, signedIn)
+})
+
 /**
  * What a pairing is filed under: the browser, and who was signed in there (`signedInAs`).
  *
@@ -75,7 +86,7 @@ function pairingKey(caller: string, signedIn: string): string {
     return `${caller}\n${signedIn}`
 }
 
-// 44.19 — the relay answers once the app has handed out a pairing command, and never before.
+// 44.19 — the relay answers once the app has handed out a pairing code, and never before.
 let minted = false
 
 /** A single-use pairing code for `caller` signed in as `signedIn`, and when it stops standing. 44.14. */
@@ -93,24 +104,135 @@ export function mintCode(
     return { code, expires }
 }
 
-/** The bridge paired to `caller` signed in as `signedIn`, if its stream is open. 44.33. */
-export function pairedBridge(
-    caller: string,
-    signedIn: string,
-): Bridge | undefined {
-    return BY_KEY.get(pairingKey(caller, signedIn))
+/**
+ * One turn on the bridge paired to `caller` signed in as `signedIn`: sent `prompt` under `config`,
+ * yielding the events its Claude Code reports, each MCP request it makes handed to `answer` and the
+ * reply sent back. 44.13, 44.17, 44.21.
+ */
+export async function* runTurn({
+    caller,
+    signedIn,
+    prompt,
+    config,
+    maxTurns,
+    answer,
+    signal,
+}: {
+    caller: string
+    signedIn: string
+    prompt: unknown[]
+    config: unknown
+    maxTurns: number
+    /** Never rejects: its failure is a reply too. */
+    answer: (method: string, params: unknown) => Promise<unknown>
+    signal: AbortSignal
+}): AsyncGenerator<AssistantEvent> {
+    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)
+        throw refuse(
+            409,
+            'No Claude Code is paired with this browser as the one signed in. claudeCode.bridgeCommand() is the command that pairs one.',
+        )
+    const turn = randomToken(9, 'base64url')
+    const inbox = new Inbox<TurnItem>()
+    bridge.turns.set(turn, inbox)
+    // `bridge.frames` is read at each push: a resumed stream (44.26) replaces it.
+    bridge.frames.push({ type: 'turn', id: turn, prompt, config, maxTurns })
+    // 44.18 — a caller hanging up ends the run on the bridge.
+    const cancel = (): void => {
+        bridge.frames.push({ type: 'cancel', turn })
+    }
+    signal.addEventListener('abort', cancel)
+    try {
+        for await (const item of inbox) {
+            if (item.kind === 'event') yield item.event as AssistantEvent
+            else if (item.kind === 'mcp')
+                void answer(item.method, item.params).then((reply) => {
+                    bridge.frames.push({
+                        type: 'reply',
+                        turn,
+                        id: item.id,
+                        reply,
+                    })
+                })
+            else if (item.kind === 'end') return
+            else throw refuse(502, `Claude Code failed: ${item.message}`)
+        }
+    } finally {
+        signal.removeEventListener('abort', cancel)
+        bridge.turns.delete(turn)
+        if (!WATCHERS.has(bridge.key)) armIdle(bridge.key)
+    }
 }
 
 /**
- * Registers `wake` to run whenever the pairing of `caller` signed in as `signedIn` changes; the
- * returned function undoes it.
+ * The pairing of `caller` signed in as `signedIn` as it changes, until `signal` aborts: the code that
+ * pairs it while unpaired, then `undefined` the moment a bridge connects, and a code again if it goes. A
+ * code that expires while nothing is paired is replaced with a fresh one. 44.20.
+ *
+ * 44.34 — IT FOLLOWS WHOEVER SIGNS IN AT THE BROWSER: a sign-in or a sign-out made since is the
+ * pairing it watches from then on, and the code it offers is that sign-in's.
  */
-export function watchPairing(
+export async function* pairingStatus(
     caller: string,
     signedIn: string,
-    wake: () => void,
-): () => void {
-    const key = pairingKey(caller, signedIn)
+    signal: AbortSignal,
+): AsyncGenerator<string | undefined> {
+    // 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 follow = (now: string, next: string): void => {
+        caller = now
+        signedIn = next
+        rouse()
+    }
+    let watchingKey = ''
+    let unwatch = (): void => {}
+    let unfollow = (): void => {}
+    let pairing: { code: string; expires: number } | undefined
+    // `null` until the first is said; `undefined` says paired.
+    let said: string | undefined | null = null
+    signal.addEventListener('abort', rouse)
+    try {
+        while (!signal.aborted) {
+            const key = pairingKey(caller, signedIn)
+            if (key !== watchingKey) {
+                unwatch()
+                unfollow()
+                unwatch = watchPairing(key, rouse)
+                unfollow = followSignIn(caller, follow)
+                watchingKey = key
+                pairing = undefined
+            }
+            const paired = BY_KEY.has(key)
+            if (
+                !paired &&
+                (pairing === undefined || pairing.expires <= Date.now())
+            )
+                pairing = mintCode(caller, signedIn)
+            const code = paired ? undefined : pairing?.code
+            if (code !== said) {
+                said = code
+                yield code
+            }
+            const renew = paired
+                ? undefined
+                : setTimeout(rouse, (pairing?.expires ?? 0) - Date.now())
+            await waiting.next()
+            clearTimeout(renew)
+        }
+    } finally {
+        signal.removeEventListener('abort', rouse)
+        unwatch()
+        unfollow()
+    }
+}
+
+/** Registers `wake` to run whenever the pairing filed under `key` changes; the returned function undoes it. */
+function watchPairing(key: string, wake: () => void): () => void {
     let watchers = WATCHERS.get(key)
     if (watchers === undefined) {
         watchers = new Set()
@@ -131,22 +253,20 @@ export function watchPairing(
     }
 }
 
-/** 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.key)) armIdle(bridge.key)
-        },
+/** Registers `follow` to hear who signs in at `caller` from here on; the returned function undoes it. */
+function followSignIn(
+    caller: string,
+    follow: (caller: string, signedIn: string) => void,
+): () => void {
+    let followers = FOLLOWERS.get(caller)
+    if (followers === undefined) {
+        followers = new Set()
+        FOLLOWERS.set(caller, followers)
+    }
+    followers.add(follow)
+    return () => {
+        followers.delete(follow)
+        if (followers.size === 0) FOLLOWERS.delete(caller)
     }
 }
 
@@ -171,38 +291,6 @@ function wakeWatchers(key: string): void {
     for (const wake of WATCHERS.get(key) ?? []) wake()
 }
 
-/**
- * Registers `follow` to hear who signs in at `caller` from here on, and the caller a sign-out rotates
- * it to (26.9); the returned function undoes it.
- *
- * 44.34 — A STATUS STREAM OPENED BEFORE A SIGN-IN carries the cookies it was opened with, so it hears
- * of the new one here rather than off its own request.
- */
-export function followSignIn(
-    caller: string,
-    follow: (caller: string, signedIn: string) => void,
-): () => void {
-    let followers = FOLLOWERS.get(caller)
-    if (followers === undefined) {
-        followers = new Set()
-        FOLLOWERS.set(caller, followers)
-    }
-    followers.add(follow)
-    return () => {
-        followers.delete(follow)
-        if (followers.size === 0) FOLLOWERS.delete(caller)
-    }
-}
-
-/** Tells every status stream at `caller` that the browser is `now`, signed in as `signedIn`. 44.34. */
-export function signedInAt(
-    caller: string,
-    now: string,
-    signedIn: string,
-): void {
-    for (const follow of FOLLOWERS.get(caller) ?? []) follow(now, signedIn)
-}
-
 function item(
     kind: TurnItem['kind'],
     fields: {