@abide/abide 0.106.0 → 0.107.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @abide/abide
 
+## 0.107.0
+
+### Minor Changes
+
+- bd2a74f: Breaking: an assistant announces a tool call as the model starts writing it, and a site may ask the visitor's Claude Code for built-in tools ([`c959804`](https://github.com/briancray/abide/commit/c959804fd19c3e99fe439f3f1120f1ef13f42ff8))
+
+### Patch Changes
+
+- bd2a74f: a bind:element callback is handed a connected node whose blocks and components have built, and bind:element on a component is a build error ([`e15fbee`](https://github.com/briancray/abide/commit/e15fbee6f7c780dab2105ca245dd79dbb4a2e317))
+
 ## 0.106.0
 
 ### Minor Changes

package/docs/REGISTRY.md

@@ -321,9 +321,9 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | --- | --- | --- | --- |
 | `assistant` | `(messages: AssistantMessage[], provider: Provider, options?: AssistantOptions) => AsyncGenerator<AssistantEvent>` | A conversation with a model, as the events it produces. | 44.1, 44.2, 44.3, 44.4, 44.21 |
 | `AssistantMessage` | `{ role: 'user' \| 'assistant'; content: string }` | One turn of the transcript a caller sends. | 44.3, 44.4 |
-| `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 } }` | What a conversation produces: text, a tool call, its result, and the end. | 44.2, 44.11 |
+| `AssistantEvent` | `{ type: 'text'; text: string } \| { 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 } }` | What a conversation produces: text, a tool call as it starts, its input once written, its result, and the end. | 44.2, 44.11, 44.29 |
 | `AssistantOptions` | `{ mcp?: boolean; maxTurns?: number }` | What `assistant` takes beside a provider. | 44.6, 44.8, 44.11 |
-| `Provider` | `{ run(messages: AssistantMessage[], tools: Toolbox, limits: { maxTurns: number; signal: AbortSignal }): AsyncGenerator<AssistantEvent> }` | What runs a conversation. | 44.2 |
+| `Provider` | `{ run(messages: AssistantMessage[], tools: Toolbox, limits: { maxTurns: number; signal: AbortSignal }): AsyncGenerator<AssistantEvent> }` | What runs a conversation. | 44.2, 44.29 |
 | `Toolbox` | `{ list: ToolDefinition[]; call(name: string, input: unknown): Promise<{ text: string; failed: boolean }> }` | The app's MCP tools, called as the asker. | 44.6, 44.7 |
 | `ToolDefinition` | `{ name: string; description: string; inputSchema: unknown; annotations: { readOnlyHint: boolean; destructiveHint: boolean; idempotentHint: boolean }; outputSchema: unknown }` | A tool as the app's MCP surface lists it. | 20.14, 20.16, 44.6 |
 
@@ -339,7 +339,7 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | 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, 44.13, 44.17, 44.18, 44.19, 44.24, 44.25, 44.28 |
-| `ClaudeCodeConfig` | `{ model?: string; fallbackModel?: string; systemPrompt?: string; appendSystemPrompt?: string; effort?: 'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' }` | The Claude Code options a site may set for a turn. | 44.16 |
+| `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.30 |
 | `claudeCode.bridgeCommand` | `() => { command: string; expires: number }` | The command that pairs a bridge with this browser. | 44.14 |
 | `claudeCode.bridge` | `() => AsyncGenerator<BridgeStatus>` | This browser's pairing, as it changes. | 44.20, 44.22 |
 | `BridgeStatus` | `{ paired: boolean; command: string \| undefined }` | Whether a bridge is paired, and the command that pairs one where none is. | 44.20 |
@@ -537,7 +537,7 @@ type Gated<Gate, Accepted> = [Schema<Accepted>] extends [Gate] ? never : Failed<
 | `bind:open` | The same, on a `<details>`. | 32.7 |
 | `bind:group` | Radio or checkbox membership. | 32.8 |
 | `bind:value={{get, set}}` | Two-way bind over an explicit accessor pair, on an element or a component. | 32.5, 32.6 |
-| `bind:element={Reactive<Element> \| ((element: Element) => void \| Disposer)}` | A node reference. | 32.9, 32.38, 32.66 |
+| `bind:element={Reactive<Element> \| ((element: Element) => void \| Disposer)}` | A node reference. | 32.9, 32.38, 32.66, 32.68, 32.69 |
 | `class:name={cond}` | Toggles a class. | 32.10 |
 | `style:prop={value}` | Sets one style property. | 32.10, 32.19 |
 | `{...expr}` | Spreads props or attributes. | 32.11, 32.37, 33.12, 33.13 |

package/docs/RULEBOOK.md

@@ -1959,6 +1959,12 @@ markup.
 32.67 A `{#for}` MUST keep the row and the nodes of a key it keeps when that key's item is a
 different value, and MUST update the row's bindings that read the item in place.
 
+32.68 A `bind:element` value MUST be handed its element after a region's build has put that element
+in the region, and after every block and component inside the element has built, so a callback
+reading layout, querying its descendants or calling `focus()` acts on a connected, whole node.
+
+32.69 `bind:element` on a component MUST be a build error.
+
 # 33. Props
 
 33.1 `props` MUST be callable from a `<script>` block only, and calling it from a `<script module>`
@@ -3060,10 +3066,13 @@ and MUST refuse 409 where none is paired.
 44.14 A code `claudeCode.bridgeCommand` mints MUST pair one bridge with the browser that asked for
 it, once, and MUST NOT pair once it has expired.
 
-44.15 A bridge MUST run Claude Code with its built-in tools off, no setting source read and no MCP
-server but the bridge's own, in an empty directory removed when the run ends.
+44.15 A bridge MUST run Claude Code with no MCP server but the bridge's own, in an empty directory
+removed when the run ends, and with no built-in tool and no setting source the visitor did not pass
+it after `--`.
 
-44.16 A bridge MUST take from the site no Claude Code option `ClaudeCodeConfig` does not name.
+44.16 A bridge MUST lay each option a site sets but `tools` (44.30) on as Claude Code's flag of that
+name, MUST fail a turn whose config sets any option `ClaudeCodeConfig` does not name, and MUST lay
+an option the visitor passed after `--` over the site's.
 
 44.17 An MCP request a bridge's Claude Code makes MUST be answered from the `Toolbox` of the turn it
 was made in.
@@ -3098,3 +3107,10 @@ the stream is open.
 
 44.28 A bridge whose stream from `/__abide/bridge` carries no line for 45 seconds MUST end it and
 redial it as 44.25 says.
+
+44.29 A `Provider` MUST yield a tool call's `tool` event when the model starts writing the call,
+and its `input` event, with the same `id`, once the call is written.
+
+44.30 A built-in tool MUST be available to a turn only where the site's `tools` names it and the
+visitor's `--tools` does, MUST be approved without asking unless the visitor passed `--allowedTools`,
+and the bridge MUST say once each tool the site asked for that the visitor did not grant.

package/docs/abide.md

@@ -5253,8 +5253,11 @@ const events = reactive(() =>
 {#for event of events}
     {#if event.type === 'tool'}
         <li><span>tool call</span>
+            <p class="font-mono text-chrome">{event.name}</p></li>
+    {:else if event.type === 'input'}
+        <li><span>with input</span>
             <p class="font-mono text-chrome">
-                {event.name} {JSON.stringify(event.input)}
+                {JSON.stringify(event.input)}
             </p></li>
     {:else if event.type === 'result'}
         <li><span>your handler answered</span>
@@ -5286,7 +5289,8 @@ const recorded: Provider = {
         )
         const name = tool?.name ?? ''
         const input = { name: 'Ada' }
-        yield { type: 'tool', id: 'toolu_1', name, input }
+        yield { type: 'tool', id: 'toolu_1', name }
+        yield { type: 'input', id: 'toolu_1', input }
         const answered = await tools.call(name, input)
         yield { type: 'result', id: 'toolu_1', ...answered }
         yield { type: 'text', text: 'Ada Lovelace is at Analytical Engines.' }
@@ -5343,7 +5347,7 @@ test('the model calls the CRM search, through the app', async () => {
 | --- | --- |
 | `AssistantMessage` | One turn of the transcript, `{ role, content }`. The last is the user's. |
 | `AssistantOptions` | `mcp` to offer the tools, and `maxTurns`, 10 by default, to cap the model's turns in one call. |
-| `AssistantEvent` | What the page reads: `text`, `tool`, `result`, then `done` with the stop reason and token usage. The same events from every provider. |
+| `AssistantEvent` | What the page reads: `text`, `tool` as a call starts, `input` once it is written, `result`, then `done` with the stop reason and token usage. The same events from every provider. |
 | `Provider` | What runs the conversation: one method, `run`. Write one for another model, or a recording for a test. |
 | `Toolbox` | What a provider is handed: `list` of the tools, and `call` to run one as the asker. |
 | `ToolDefinition` | One tool in `list`: its name, description and input schema. |
@@ -5620,7 +5624,13 @@ test('unpaired: asking is refused, the bridge shows a command', async () => {
 })
 ```
 
-`claudeCode` sends the conversation to Claude Code on the asker's machine, on their own sign-in and plan. Its config, `ClaudeCodeConfig`, is Claude Code's own option names: `model`, `fallbackModel`, `systemPrompt`, `appendSystemPrompt` and `effort`. Its tools, permissions and directory are not the site's to set.
+`claudeCode` sends the conversation to Claude Code on the asker's machine, on their own sign-in and plan. Its config, `ClaudeCodeConfig`, is Claude Code's own option names, each passed as its flag: `model`, `fallbackModel`, `systemPrompt`, `appendSystemPrompt`, `effort`, `maxBudgetUsd`, `betas` and `disallowedTools`. Permissions, directories and settings are not the site's to set.
+
+`tools` asks for Claude Code's built-in tools, and the visitor decides. A tool runs only where they granted it after the command's `--`, and the bridge tells them about any it was asked for and not given. Anything else after `--` goes to Claude Code as written, and overrides what the site set.
+
+```
+bunx @abide/bridge <site> <code> -- --tools WebSearch,WebFetch
+```
 
 The visitor pairs once per visit by running a command, which dials out to the site. Asking with nothing paired is refused 409.
 
@@ -7699,7 +7709,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `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 } }` | What a conversation produces: text, a tool call, its result, and the end. | [44.2](/rulebook#44.2), [44.11](/rulebook#44.11) |
+| `AssistantEvent` | `{ type: 'text'; text: string } \| { 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 } }` | What a conversation produces: text, a tool call as it starts, its input once written, its result, and the end. | [44.2](/rulebook#44.2), [44.11](/rulebook#44.11), [44.29](/rulebook#44.29) |
 
 ## Taught in
 
@@ -7735,7 +7745,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `Provider` | `{ run(messages: AssistantMessage[], tools: Toolbox, limits: { maxTurns: number; signal: AbortSignal }): AsyncGenerator<AssistantEvent> }` | What runs a conversation. | [44.2](/rulebook#44.2) |
+| `Provider` | `{ run(messages: AssistantMessage[], tools: Toolbox, limits: { maxTurns: number; signal: AbortSignal }): AsyncGenerator<AssistantEvent> }` | What runs a conversation. | [44.2](/rulebook#44.2), [44.29](/rulebook#44.29) |
 
 ## Taught in
 
@@ -7846,7 +7856,7 @@ Generated surfaces: what is written in place rather than imported.
 
 | Name | Signature | Meaning | Rules |
 | --- | --- | --- | --- |
-| `ClaudeCodeConfig` | `{ model?: string; fallbackModel?: string; systemPrompt?: string; appendSystemPrompt?: string; effort?: 'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max' }` | The Claude Code options a site may set for a turn. | [44.16](/rulebook#44.16) |
+| `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](/rulebook#44.16), [44.30](/rulebook#44.30) |
 
 ## Taught in
 
@@ -8607,7 +8617,7 @@ Generated surfaces: what is written in place rather than imported.
 | `bind:open` | The same, on a `<details>`. | [32.7](/rulebook#32.7) |
 | `bind:group` | Radio or checkbox membership. | [32.8](/rulebook#32.8) |
 | `bind:value={{get, set}}` | Two-way bind over an explicit accessor pair, on an element or a component. | [32.5](/rulebook#32.5), [32.6](/rulebook#32.6) |
-| `bind:element={Reactive<Element> \| ((element: Element) => void \| Disposer)}` | A node reference. | [32.9](/rulebook#32.9), [32.38](/rulebook#32.38), [32.66](/rulebook#32.66) |
+| `bind:element={Reactive<Element> \| ((element: Element) => void \| Disposer)}` | A node reference. | [32.9](/rulebook#32.9), [32.38](/rulebook#32.38), [32.66](/rulebook#32.66), [32.68](/rulebook#32.68), [32.69](/rulebook#32.69) |
 | `class:name={cond}` | Toggles a class. | [32.10](/rulebook#32.10) |
 | `style:prop={value}` | Sets one style property. | [32.10](/rulebook#32.10), [32.19](/rulebook#32.19) |
 | `{...expr}` | Spreads props or attributes. | [32.11](/rulebook#32.11), [32.37](/rulebook#32.37), [33.12](/rulebook#33.12), [33.13](/rulebook#33.13) |

package/package.json

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

package/src/compiler/classifyTemplate.ts

@@ -464,13 +464,15 @@ export function isParserOwned(lowerTag: string): boolean {
 /**
  * The key a component's attribute passes a prop under, or `undefined` where it is no prop.
  *
- * 32.6, 32.10 — a `bind:` handing over a `Reactive` keys the name after it, and any other `:` name
- * — `class:`, `style:`, a `bind:` with nothing bound — is an element's own. The build writes the
+ * 32.6, 32.10, 32.69 — a `bind:` handing over a `Reactive` keys the name after it, and any other
+ * `:` name — `class:`, `style:`, `bind:element`, a `bind:` with nothing bound — is an element's own.
+ * Read as a prop, `bind:element` was one named `element` the child never declared, and the
+ * callback never ran. The build writes the
  * props record by this and the checker projects it by this, so a tag is held to what it sends.
  */
 export function propKeyOf(attribute: Attribute): string | undefined {
     if (attribute.lowerName.startsWith('bind:'))
-        return attribute.expression
+        return attribute.expression && !isElementBind(attribute.lowerName)
             ? attribute.name.slice('bind:'.length)
             : undefined
     return attribute.name.includes(':') ? undefined : attribute.name

package/src/compiler/emitClient.ts

@@ -558,9 +558,11 @@ function emitRegion(sink: Cursor, region: RegionEmission): RegionEmission {
 
     for (const line of walkTo(positions, live, lowering)) chain.push(line)
 
-    // THE UNITS, in the order a page always installed them — text, listeners, attributes, the node
-    // handed over, then the regions. The walk does not depend on it; a `bind:element` callback has
-    // always run with every other binding already in place, and that is kept.
+    // THE UNITS — text, listeners, attributes, the regions, then the node handed over. The walk
+    // does not depend on the order.
+    // 32.68 — A `bind:element` CALLBACK RUNS LAST, so the node it is handed is whole: a child
+    // component, an arm or a list inside it has built, and `form.querySelector('input')` finds an
+    // `<input>` an `<Input>` makes.
     // 32.67 — A ROW'S ITEM WATCHES FIRST, one after another, which is how its scope finds them
     // (`Scope.itemWatch`).
     const items: string[] = []
@@ -597,7 +599,6 @@ function emitRegion(sink: Cursor, region: RegionEmission): RegionEmission {
     for (const unit of texts) lines.push(unit)
     for (const unit of handlers) lines.push(unit)
     for (const unit of attributes) lines.push(unit)
-    for (const unit of elements) lines.push(unit)
 
     // 32.67 — WHAT A ROW'S REGIONS AND COMPONENTS BIND reads the row's item through its cell: the
     // row's `update` reaches its own top level and no further.
@@ -613,6 +614,7 @@ function emitRegion(sink: Cursor, region: RegionEmission): RegionEmission {
                 else emitInvocation(at, holder, region)
             }
         }
+        for (const unit of elements) lines.push(unit)
         // 32.43 — A REGION THAT MOUNTS NOTHING INVOKES NOTHING, so what it declares is reached
         // from nowhere and is not declared: a row declaring a component it never invokes stays a
         // row whose mount is the shared empty one.

package/src/compiler/invocationProps.ts

@@ -31,7 +31,7 @@ export function invocationProps(
         const key = propKeyOf(attribute)
         if (key === undefined)
             throw new Error(
-                `abide: ${attribute.name} on <${node.tag}> is not a prop a component takes — \`bind:\` hands over the \`Reactive\` in its braces (RULEBOOK 32.6), and \`class:\` and \`style:\` set an element's own class and style. RULEBOOK 32.10.`,
+                `abide: ${attribute.name} on <${node.tag}> is not a prop a component takes — \`bind:\` hands over the \`Reactive\` in its braces (RULEBOOK 32.6), \`class:\` and \`style:\` set an element's own class and style (RULEBOOK 32.10), and \`bind:element\` hands over an element — put it on one inside <${node.tag}>, or pass the callback as a prop (RULEBOOK 32.69).`,
             )
         // A STATIC PROP IS STILL AN ACCESSOR. One shape per prop whatever the call site spelled
         // (33.10), so the child reads every key the same way and a literal is not a second case.

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.2.0'
+export const BRIDGE_VERSION = '0.3.0'

package/src/server/assistant.ts

@@ -20,7 +20,8 @@ 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: 'tool'; id: string; name: string }
+    | { type: 'input'; id: string; input: unknown }
     | { type: 'result'; id: string; text: string; failed: boolean }
     | {
           type: 'done'

package/src/server/claudeApi.ts

@@ -118,10 +118,19 @@ export function claudeApi(config: ClaudeApiConfig): Provider {
                         case 'message_start':
                             usage.input += inputOf(event.message.usage)
                             break
-                        case 'content_block_start':
-                            blocks[event.index] = event.content_block
+                        case 'content_block_start': {
+                            const block = event.content_block
+                            blocks[event.index] = block
                             partials[event.index] = ''
+                            // 44.29 — announced as the model starts writing it.
+                            if (block.type === 'tool_use')
+                                yield {
+                                    type: 'tool',
+                                    id: block.id as string,
+                                    name: block.name as string,
+                                }
                             break
+                        }
                         case 'content_block_delta': {
                             const block = blocks[event.index] as Block
                             const delta = event.delta
@@ -152,9 +161,8 @@ export function claudeApi(config: ClaudeApiConfig): Provider {
                             }
                             called.push(block)
                             yield {
-                                type: 'tool',
+                                type: 'input',
                                 id: block.id as string,
-                                name: block.name as string,
                                 input: block.input,
                             }
                             break

package/src/server/claudeCode.ts

@@ -3,9 +3,10 @@
 // turn and answer the MCP requests it makes from the `Toolbox` — in this request's scope, as this
 // asker (44.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 (44.15, 44.16).
+// CONFIGURED BY CLAUDE CODE'S OWN OPTION NAMES, which the bridge lays on as their flags, and only the ones
+// that shape the answer. What would give a site power over the visitor's machine — permissions,
+// 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.30).
 
 import { mounted } from '#shared/mount.ts'
 import { refuse } from '#shared/refuse.ts'
@@ -28,13 +29,17 @@ 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. */
+/** The Claude Code options a site may set for a turn, and the built-in tools it asks the visitor for. */
 export type ClaudeCodeConfig = {
     model?: string
     fallbackModel?: string
     systemPrompt?: string
     appendSystemPrompt?: string
     effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max'
+    maxBudgetUsd?: number
+    betas?: string[]
+    disallowedTools?: string[]
+    tools?: string[]
 }
 
 /** Whether this browser's bridge is connected, and the command that pairs one where it is not. */

package/src/ui/bindElement.ts

@@ -21,6 +21,10 @@ import { holdWhileLeaving } from './leave.ts'
  * form is where teardown is decided, and its `Disposer` is the whole of it.
  *
  * 32.38 — A `Disposer` HANDING BACK A THENABLE IS AN EXIT: the element's nodes stay until it settles.
+ *
+ * 32.68 — THE NODE IS CONNECTED AND WHOLE, and nothing here makes it so: this runs from a region's
+ * MOUNT, which every caller (`ArmRegion`, `TryRegion`, `makeRow`) calls after `build`'s nodes are
+ * inserted, and last in it, after the blocks and components inside the node (`emitRegion`).
  */
 export function bindElement(
     element: Element,