@abide/abide 0.119.0 → 0.120.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @abide/abide
 
+## 0.120.0
+
+### Minor Changes
+
+- 2af648d: a pairing link beside the command — abide-bridge install registers a macOS app that opens it and asks before it pairs (RULEBOOK 44.40-44.43) ([`409d5ac`](https://github.com/briancray/abide/commit/409d5ac7f95338cb3f44a21cc76cd977387eab42))
+
 ## 0.119.0
 
 ### Minor Changes

package/docs/REGISTRY.md

@@ -351,9 +351,9 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | --- | --- | --- | --- |
 | `claudeCode` | `(config?: ClaudeCodeConfig) => Provider` | The visitor's own Claude Code, reached through the bridge paired with their browser, as a provider. | 44.5, 44.13, 44.17, 44.18, 44.19, 44.24, 44.25, 44.27, 44.30, 44.33 |
 | `ClaudeCodeConfig` | `{ model?: string; fallbackModel?: string; systemPrompt?: string; appendSystemPrompt?: string; effort?: 'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'; maxBudgetUsd?: number; betas?: string[]; disallowedTools?: string[]; tools?: string[] }` | The Claude Code options a site may set for a turn, and the built-in tools it asks the visitor for. | 44.16, 44.29 |
-| `claudeCode.bridgeCommand` | `(options?: { tools?: string[] }) => { command: string; expires: number }` | The command that pairs a bridge with this browser, granting the built-in tools it is given. | 44.14, 44.32, 44.33 |
-| `claudeCode.bridge` | `(options?: { tools?: string[] }) => AsyncGenerator<BridgeStatus>` | This browser's pairing, as it changes. | 44.20, 44.22, 44.32, 44.33, 44.34 |
-| `BridgeStatus` | `{ paired: boolean; command: string \| undefined }` | Whether a bridge is paired, and the command that pairs one where none is. | 44.20 |
+| `claudeCode.bridgeCommand` | `(options?: { tools?: string[] }) => { command: string; link: string; expires: number }` | The command and the link that pair a bridge with this browser, granting the built-in tools it is given. | 44.14, 44.32, 44.33, 44.40, 44.41, 44.42, 44.43 |
+| `claudeCode.bridge` | `(options?: { tools?: string[] }) => AsyncGenerator<BridgeStatus>` | This browser's pairing, as it changes. | 44.20, 44.22, 44.32, 44.33, 44.34, 44.40 |
+| `BridgeStatus` | `{ paired: boolean; command: string \| undefined; link: string \| undefined }` | Whether a bridge is paired, and the command and the link that pair one where none is. | 44.20, 44.40 |
 | `/__abide/bridge` | `GET`, `POST` | Where a bridge pairs, and is relayed its turns. | 36.7, 44.14, 44.15, 44.19, 44.23, 44.26, 16.57, 16.78 |
 
 # Ambient values

package/docs/RULEBOOK.md

@@ -3398,6 +3398,19 @@ its type, in its place in its turn.
 44.39 `assistant` MUST hand a `Provider` each turn as its `AssistantContent` pieces, a turn's string
 as one text piece.
 
+44.40 A pairing `claudeCode.bridgeCommand` or `claudeCode.bridge` mints MUST carry, beside its command,
+a link in the `abide-bridge` scheme naming the same site, code, bridge release and built-in tools.
+
+44.41 A bridge MUST open only a link of the `abide-bridge` scheme whose site is https or loopback and
+whose release is a version alone, and MUST run the release it names.
+
+44.42 A bridge opening an `abide-bridge` link MUST ask the visitor before it pairs, every time, naming
+the site, the built-in tools and the bridge release the link asks for.
+
+44.43 `abide-bridge install` MUST write the app that opens links under the visitor's own Application
+Support and register it there, and `abide-bridge uninstall` MUST unregister it and remove all
+install wrote.
+
 # 45. Offline
 
 45.1 Where `ABIDE_OFFLINE` is on, a page `abide build` built MUST register the worker

package/docs/abide.md

@@ -5900,7 +5900,7 @@ Leave `baseURL` out and the request goes to Anthropic. `claudeApi` reads no key
 
 ## `claudeCode` runs on the visitor's own Claude Code
 
-**`claudeCode(config)` — a turn on the reader's own Claude Code** — The assistant on whatever Claude Code is paired with this browser. Ask first and it is refused; connect, run the command in a terminal, and ask again.
+**`claudeCode(config)` — a turn on the reader's own Claude Code** — The assistant on whatever Claude Code is paired with this browser. Ask first and it is refused; connect, run the command in a terminal or open the link, and ask again.
 
 ```abide src/assistant/lib/ClaudeCodeBridge.abide
 <script>
@@ -5935,6 +5935,11 @@ const answer = reactive(() => {
 {:else if pairing.at(-1)}
     <pre class="rounded-md border border-rule bg-raised p-snug
         text-chrome">{pairing.at(-1)?.command}</pre>
+    <div class="row">
+        <a href={pairing.at(-1)?.link}>Open in abide bridge</a>
+        <span class="status">on macOS, after
+            <code>bunx @abide/bridge install</code></span>
+    </div>
 {:else}
     <div class="row">
         <button onclick={() => {
@@ -6010,7 +6015,7 @@ function fromPage(
     })
 }
 
-test('unpaired: asking is refused, the bridge shows a command', async () => {
+test('unpaired: refused, with a command and a link', async () => {
     await using app = await createApp()
     const refused = await app.fetch(
         fromPage('/assistant/askClaudeCode', {
@@ -6031,11 +6036,14 @@ test('unpaired: asking is refused, the bridge shows a command', async () => {
     const reader = (status.body as ReadableStream<Uint8Array>).getReader()
     const first = new TextDecoder().decode((await reader.read()).value)
     watching.abort()
-    const { paired, command } = JSON.parse(first.split('\n')[0] ?? '')
+    const { paired, command, link } = JSON.parse(first.split('\n')[0] ?? '')
     expect(paired).toBe(false)
     expect(command).toMatch(
         /^bunx @abide\/bridge@\S+ http:\/\/crm.invalid \S+$/,
     )
+    expect(new URL(link).searchParams.get('code')).toBe(
+        command.split(' ').at(-1),
+    )
 })
 ```
 
@@ -6051,13 +6059,21 @@ Pass the same `tools` to `claudeCode.bridge` or `claudeCode.bridgeCommand` and t
 
 The visitor pairs once per visit by running a command, which dials out to the site. Asking with nothing paired is refused 409.
 
+On a Mac the visitor can pair with a click instead. Each status carries a `link` beside its command, the same pairing in the `abide-bridge` scheme, and a visitor who has run this once opens it from the page:
+
+```
+bunx @abide/bridge install
+```
+
+That builds a small app under their own Application Support folder, nowhere in Applications, and registers it for the scheme. Opening a link asks them every time, naming the site, the tools and the bridge release it asks for, and then runs that release, as the command would. A link only proves the site minted its code, never that this visitor asked for it, so no answer is kept for a site. `bunx @abide/bridge uninstall` takes it away.
+
 The tools the conversation calls run as the visitor, on the sign-in their ask carried, so a tool reads `principal` as any handler does. The pairing belongs to that sign-in too. If someone else signs in at the same browser, their asks are refused 409 and the status offers them a command of their own, so nobody's turn runs on another member's Claude Code.
 
 | Name | What it does for the CRM |
 | --- | --- |
-| `claudeCode.bridge` | Streams this browser's pairing: unpaired with the command to run, then paired. |
-| `BridgeStatus` | One status in that stream, `{ paired, command }`. |
-| `claudeCode.bridgeCommand` | Mints the command alone, for a page that wants the line without the stream. Its code expires unused after ten minutes. |
+| `claudeCode.bridge` | Streams this browser's pairing: unpaired with the command to run and the link to open, then paired. |
+| `BridgeStatus` | One status in that stream, `{ paired, command, link }`. |
+| `claudeCode.bridgeCommand` | Mints the command and the link alone, for a page that wants them without the stream. Its code expires unused after ten minutes. |
 | `/__abide/bridge` | Where the visitor's bridge connects. It opens the first time a command is minted. |
 
 ## `abide call` runs a handler from the terminal
@@ -8403,8 +8419,8 @@ Generated surfaces: what is written in place rather than imported.
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
 | `claudeCode` | `(config?: ClaudeCodeConfig) => Provider` | The visitor's own Claude Code, reached through the bridge paired with their browser, as a provider. | [44.5](/rulebook#44.5), [44.13](/rulebook#44.13), [44.17](/rulebook#44.17), [44.18](/rulebook#44.18), [44.19](/rulebook#44.19), [44.24](/rulebook#44.24), [44.25](/rulebook#44.25), [44.27](/rulebook#44.27), [44.30](/rulebook#44.30), [44.33](/rulebook#44.33) |
-| `claudeCode.bridgeCommand` | `(options?: { tools?: string[] }) => { command: string; expires: number }` | The command that pairs a bridge with this browser, granting the built-in tools it is given. | [44.14](/rulebook#44.14), [44.32](/rulebook#44.32), [44.33](/rulebook#44.33) |
-| `claudeCode.bridge` | `(options?: { tools?: string[] }) => AsyncGenerator<BridgeStatus>` | This browser's pairing, as it changes. | [44.20](/rulebook#44.20), [44.22](/rulebook#44.22), [44.32](/rulebook#44.32), [44.33](/rulebook#44.33), [44.34](/rulebook#44.34) |
+| `claudeCode.bridgeCommand` | `(options?: { tools?: string[] }) => { command: string; link: string; expires: number }` | The command and the link that pair a bridge with this browser, granting the built-in tools it is given. | [44.14](/rulebook#44.14), [44.32](/rulebook#44.32), [44.33](/rulebook#44.33), [44.40](/rulebook#44.40), [44.41](/rulebook#44.41), [44.42](/rulebook#44.42), [44.43](/rulebook#44.43) |
+| `claudeCode.bridge` | `(options?: { tools?: string[] }) => AsyncGenerator<BridgeStatus>` | This browser's pairing, as it changes. | [44.20](/rulebook#44.20), [44.22](/rulebook#44.22), [44.32](/rulebook#44.32), [44.33](/rulebook#44.33), [44.34](/rulebook#44.34), [44.40](/rulebook#44.40) |
 | `/__abide/bridge` | `GET`, `POST` | Where a bridge pairs, and is relayed its turns. | [36.7](/rulebook#36.7), [44.14](/rulebook#44.14), [44.15](/rulebook#44.15), [44.19](/rulebook#44.19), [44.23](/rulebook#44.23), [44.26](/rulebook#44.26), [16.57](/rulebook#16.57), [16.78](/rulebook#16.78) |
 
 ## Taught in
@@ -8441,7 +8457,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `BridgeStatus` | `{ paired: boolean; command: string \| undefined }` | Whether a bridge is paired, and the command that pairs one where none is. | [44.20](/rulebook#44.20) |
+| `BridgeStatus` | `{ paired: boolean; command: string \| undefined; link: string \| undefined }` | Whether a bridge is paired, and the command and the link that pair one where none is. | [44.20](/rulebook#44.20), [44.40](/rulebook#44.40) |
 
 ## Taught in
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.119.0",
+    "version": "0.120.0",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",

package/src/server/BRIDGE_SCHEME.ts

@@ -0,0 +1,3 @@
+// 44.40 — the scheme a pairing link is written in, which the handler `abide-bridge install` registers
+// opens. The bridge spells it out as `PAIRING_SCHEME`, and a test holds the two equal.
+export const BRIDGE_SCHEME = 'abide-bridge'

package/src/server/BRIDGE_VERSION.ts

@@ -1,3 +1,3 @@
 // The `abide-bridge` release a pairing command names, so a visitor's `bunx` runs the relay this
 // server speaks. `packages/abide/tests/claudeCode.test.ts` holds it to the bridge package's own.
-export const BRIDGE_VERSION = '0.3.5'
+export const BRIDGE_VERSION = '0.4.0'

package/src/server/claudeCode.ts

@@ -19,6 +19,7 @@ import {
     forwardOf,
     type Provider,
 } from './assistant.ts'
+import { BRIDGE_SCHEME } from './BRIDGE_SCHEME.ts'
 import { BRIDGE_VERSION } from './BRIDGE_VERSION.ts'
 import {
     followSignIn,
@@ -50,8 +51,15 @@ export type ClaudeCodeConfig = {
 /** The built-in tools a pairing command grants, as the visitor would after its `--`. 44.32. */
 type PairingOptions = Pick<ClaudeCodeConfig, 'tools'>
 
-/** 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 }
+/**
+ * Whether this browser's bridge is connected, and the command and the link that pair one where it is
+ * not.
+ */
+export type BridgeStatus = {
+    paired: boolean
+    command: string | undefined
+    link: string | undefined
+}
 
 /** The visitor's own Claude Code, reached through the bridge paired to their browser. */
 function claudeCodeProvider(config: ClaudeCodeConfig = {}): Provider {
@@ -149,35 +157,40 @@ function askingCaller(): string {
     return caller
 }
 
+/** One pairing code, as the command a visitor runs and the link they open, and when it stops standing. */
+type Pairing = { command: string; link: string; expires: number }
+
 /**
- * The command that pairs a bridge with this browser, and when its code stops standing. 44.14. The
- * `tools` it is given are written after its `--`, so the visitor running it grants them (44.29, 44.32).
+ * The command and the link that pair a bridge with this browser, and when their code stops standing.
+ * 44.14. The `tools` it is given are written after the command's `--` and in the link, so the visitor
+ * running either grants them (44.29, 44.32, 44.40).
  */
-function bridgeCommand(options: PairingOptions = {}): {
-    command: string
-    expires: number
-} {
+function bridgeCommand(options: PairingOptions = {}): Pairing {
     return commandFor(askingCaller(), signedInAs(), options)
 }
 
-/** The command pairing a bridge with `caller` signed in as `signedIn` (44.33). */
+/** The command and the link pairing a bridge with `caller` signed in as `signedIn` (44.33). */
 function commandFor(
     caller: string,
     signedIn: string,
     { tools }: PairingOptions,
-): { command: string; expires: number } {
+): Pairing {
     const { code, expires } = mintCode(caller, signedIn)
     const site = `${appOrigin() ?? new URL(request().url).origin}${mounted('')}`
-    const grant = tools?.length ? ` -- --tools ${tools.join(',')}` : ''
+    const granted = tools?.length ? tools.join(',') : undefined
+    const query = new URLSearchParams({ site, code, version: BRIDGE_VERSION })
+    if (granted !== undefined) query.set('tools', granted)
+    const grant = granted === undefined ? '' : ` -- --tools ${granted}`
     return {
         command: `bunx @abide/bridge@${BRIDGE_VERSION} ${site} ${code}${grant}`,
+        link: `${BRIDGE_SCHEME}://pair?${query}`,
         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. 44.20.
+ * This browser's pairing as it changes: unpaired with the command to run and the link to open, then
+ * paired the moment a bridge connects, and unpaired again if it goes. 44.20.
  *
  * 44.34 — IT FOLLOWS WHOEVER SIGNS IN AT THE BROWSER, though its own request carries the cookies it
  * opened with: a sign-in or a sign-out made since is the pairing it watches from then on, and the
@@ -203,7 +216,7 @@ async function* bridge(
         rouse()
     }
     signal.addEventListener('abort', rouse)
-    let pairing: { command: string; expires: number } | undefined
+    let pairing: Pairing | undefined
     let said = ''
     try {
         while (!signal.aborted) {
@@ -225,7 +238,9 @@ async function* bridge(
             const status: BridgeStatus = {
                 paired,
                 command: paired ? undefined : pairing?.command,
+                link: paired ? undefined : pairing?.link,
             }
+            // The link is minted with the command, so the command alone tells a new pairing.
             const saying = `${status.paired} ${status.command}`
             if (saying !== said) {
                 said = saying