refactor(P060): bridge owns the schemas; client-tools is a thin adapter

The bridge is the single source of truth for the iframe contract: each
operation has a Zod schema (with description) in
embed-bridge/schemas.ts, and IframeBridge methods take z.infer<typeof X>
directly. The bridge implementation is a one-line postMessage pass-
through per method — no key conversion (input shapes mirror the wire's
snake_case payloads).

The client-tools adapter is now just two files:
- schemas.ts: enumerates the LLM tool names exposed to the model.
- tools.ts: maps each tool name to { description, inputSchema } pulled
  verbatim from the bridge schema's `.describe()`. No duplicated text.

Consumers (routes/api/chat.ts and lib/byok/transport.ts) drop ~50 lines
of inline tool registration each; they now just spread LLM_STATIC_TOOLS
into withFinalisationTool. Adding a new LLM-exposed bridge operation:
- one schema in embed-bridge/schemas.ts
- one method on IframeBridge + one impl line in bridge.ts
- one tool entry in client-tools/tools.ts
- one switch arm in client-tools/factory.ts

dispatch.ts is gone (the switch lives in factory.ts directly).

Author: bendersej

copilot/src/components/chat/chat_pane.tsx

@@ -531,7 +531,7 @@ export const ChatPane = ({
     if (activeBridge === null) {
       return
     }
-    void activeBridge.submit({ downloadCopy: false })
+    void activeBridge.submit({ download_copy: false })
   }, [])
 
   const handleDownloadRequested = useCallback((): void => {

copilot/src/lib/byok/transport.ts

@@ -1,18 +1,8 @@
 import { convertToModelMessages, streamText, type UIMessage } from 'ai'
 import { buildSystemPrompt } from '../../server/tools'
 import {
-  DeleteFieldsInput,
-  DeletePagesInput,
-  DetectFieldsInput,
   FINALISATION_ACTION,
-  FocusFieldInput,
-  GetDocumentContentInput,
-  GetFieldsInput,
-  GoToPageInput,
-  MovePageInput,
-  RotatePageInput,
-  SelectToolInput,
-  SetFieldValueInput,
+  LLM_STATIC_TOOLS,
   withFinalisationTool,
 } from '../embed-bridge-adapters/client-tools'
 import { formatStreamError } from '../error-classifier'
@@ -93,58 +83,7 @@ export const runByokStream = async ({ config, init }: RunByokStreamArgs): Promis
     abortSignal: init?.signal ?? undefined,
     maxRetries: 0,
     maxOutputTokens: MAX_OUTPUT_TOKENS,
-    tools: withFinalisationTool({
-      get_fields: {
-        description: 'Lists every fillable field currently on the document.',
-        inputSchema: GetFieldsInput,
-      },
-      get_document_content: {
-        description: 'Extracts the textual content of the document page by page.',
-        inputSchema: GetDocumentContentInput,
-      },
-      detect_fields: {
-        description:
-          'Asks the editor to auto-detect and create missing fields. Call this when get_fields returned 0 fields.',
-        inputSchema: DetectFieldsInput,
-      },
-      delete_fields: {
-        description:
-          'Deletes fields from the document. field_ids targets specific fields by id; page targets a single page (1-indexed); both omitted clears all fields. Destructive — only call when the user explicitly asks to delete fields.',
-        inputSchema: DeleteFieldsInput,
-      },
-      select_tool: {
-        description:
-          'Switches the editor tool (TEXT, BOXED_TEXT, CHECKBOX, SIGNATURE, PICTURE, or null for cursor).',
-        inputSchema: SelectToolInput,
-      },
-      set_field_value: {
-        description: 'Writes a value into a single field. Always focus_field first.',
-        inputSchema: SetFieldValueInput,
-      },
-      focus_field: {
-        description: 'Scrolls to and visually highlights a field.',
-        inputSchema: FocusFieldInput,
-      },
-      go_to_page: {
-        description: 'Scrolls the editor to a given 1-based page.',
-        inputSchema: GoToPageInput,
-      },
-      move_page: {
-        description:
-          'Reorders pages: from_page and to_page are 1-indexed visible page positions. Destructive — only call when the user explicitly asks to reorder a page.',
-        inputSchema: MovePageInput,
-      },
-      delete_pages: {
-        description:
-          'Permanently removes one or more visible pages (1-indexed) and any fields placed on them. Pass pages as a non-empty array. At least one visible page must remain — passing every visible page returns event_not_allowed. Destructive — only call when the user explicitly asks to delete pages.',
-        inputSchema: DeletePagesInput,
-      },
-      rotate_page: {
-        description:
-          'Rotates a visible page (1-indexed) 90° clockwise per call (repeat for 180° / 270°). Destructive — only call when the user explicitly asks to rotate a page.',
-        inputSchema: RotatePageInput,
-      },
-    }),
+    tools: withFinalisationTool(LLM_STATIC_TOOLS),
     onError: ({ error }) => {
       monitoring.error('byok.stream_error', { detail: normalizeError(error) })
     },

copilot/src/lib/embed-bridge-adapters/client-tools/dispatch.ts

@@ -1,7 +1,20 @@
-import type { BridgeResult, IframeBridge } from '../../embed-bridge'
-import { dispatch, type ToolInput } from './dispatch'
+import {
+  type BridgeResult,
+  DeleteFieldsInput,
+  DeletePagesInput,
+  FocusFieldInput,
+  GetDocumentContentInput,
+  GoToInput,
+  type IframeBridge,
+  MovePageInput,
+  RotatePageInput,
+  SelectToolInput,
+  SetFieldValueInput,
+} from '../../embed-bridge'
 import { composeMiddleware, type ToolMiddleware } from './middleware'
-import { type ClientToolName, CLIENT_TOOL_SCHEMAS, isClientToolName } from './schemas'
+import { type ClientToolName, isClientToolName } from './schemas'
+
+export type ToolInput = Record<string, unknown>
 
 export type CreateClientToolsArgs = {
   // The iframe bridge the dispatcher will drive. Usually comes from the React
@@ -20,18 +33,12 @@ export type CreateClientToolsArgs = {
 }
 
 export type ClientTools = {
-  // Zod input schemas keyed by tool name. Spread into streamText({ tools })
-  // alongside descriptions.
-  schemas: typeof CLIENT_TOOL_SCHEMAS
   // System prompt passed into createClientTools, re-exported verbatim for
   // the consumer to pass to their LLM.
   systemPrompt: string
-  // Main entry: middleware stack + bridge dispatch. The caller is expected
-  // to narrow toolName via `isClientToolName` BEFORE calling execute (the
-  // Vercel AI SDK guarantees the LLM only fires registered tools, so the
-  // narrow is a one-line type assertion at the consumer). Pushing the
-  // narrow up means there is no redundant runtime check here, and the
-  // dispatcher stays a pure router with `satisfies never` exhaustiveness.
+  // Main entry. The caller narrows toolName via `isClientToolName` once at
+  // the consumer boundary; the Vercel AI SDK guarantees the LLM only fires
+  // registered tools.
   execute: (toolName: ClientToolName, input: ToolInput) => Promise<BridgeResult<unknown>>
   // Type guard re-export so the consumer can branch on tool names without
   // importing `schemas.ts` separately.
@@ -43,9 +50,48 @@ export const createClientTools = ({
   systemPrompt,
   middleware = [],
 }: CreateClientToolsArgs): ClientTools => {
-  const composed = composeMiddleware(middleware, ({ toolName, input }) => dispatch(bridge, toolName, input))
+  // One arm per tool. Each arm parses the LLM-supplied input via the
+  // bridge schema (single source of truth, lives in
+  // embed-bridge/schemas.ts) and forwards the typed payload to the matching
+  // bridge method. `satisfies never` keeps the switch exhaustive over
+  // ClientToolName at compile time.
+  const composed = composeMiddleware(middleware, async ({ toolName, input }) => {
+    switch (toolName) {
+      case 'get_fields':
+        return bridge.getFields()
+      case 'get_document_content':
+        return bridge.getDocumentContent(GetDocumentContentInput.parse(input))
+      case 'detect_fields':
+        return bridge.detectFields()
+      case 'delete_fields':
+        return bridge.deleteFields(DeleteFieldsInput.parse(input))
+      case 'select_tool':
+        return bridge.selectTool(SelectToolInput.parse(input))
+      case 'set_field_value':
+        return bridge.setFieldValue(SetFieldValueInput.parse(input))
+      case 'focus_field':
+        return bridge.focusField(FocusFieldInput.parse(input))
+      case 'go_to_page':
+        return bridge.goTo(GoToInput.parse(input))
+      case 'move_page':
+        return bridge.movePage(MovePageInput.parse(input))
+      case 'delete_pages':
+        return bridge.deletePages(DeletePagesInput.parse(input))
+      case 'rotate_page':
+        return bridge.rotatePage(RotatePageInput.parse(input))
+      case 'submit':
+        return bridge.submit({ download_copy: false })
+      case 'download':
+        return bridge.download()
+      default:
+        toolName satisfies never
+        return {
+          success: false,
+          error: { code: 'unknown_tool', message: `Unknown tool: ${String(toolName)}` },
+        }
+    }
+  })
   return {
-    schemas: CLIENT_TOOL_SCHEMAS,
     systemPrompt,
     execute: (toolName, input) => composed({ toolName, input }),
     isClientToolName,

copilot/src/lib/embed-bridge-adapters/client-tools/factory.ts

@@ -1,30 +1,19 @@
+import { DownloadInput, SubmitInput } from '../../embed-bridge'
 import { IS_DEMO_MODE } from '../../mode'
-import { DownloadInput, SubmitInput } from './schemas'
 
 // The single AI SDK tool that finalises the filled PDF. Demo mode (the
 // SimplePDF-hosted copilot.simplepdf.com) exposes only `download`, which
 // short-circuits through the host's upsell-aware handler. SimplePDF customer
 // forks expose only `submit`, which fires the SimplePDF SUBMIT iframe event
 // so the filled PDF lands in the customer's BYOS storage + webhook stack.
+// Both descriptions live with the bridge schemas.
 export type FinalisationToolMap =
   | { submit: { description: string; inputSchema: typeof SubmitInput } }
   | { download: { description: string; inputSchema: typeof DownloadInput } }
 
 export const FINALISATION_TOOL: FinalisationToolMap = IS_DEMO_MODE
-  ? {
-      download: {
-        description:
-          'Finalizes the filled PDF and triggers an in-browser download for the user. Use only when the user asks to download.',
-        inputSchema: DownloadInput,
-      },
-    }
-  : {
-      submit: {
-        description:
-          'Finalizes the filled PDF and submits it to the host application (storage, webhook, etc.). Use only when the user asks to submit or finalize.',
-        inputSchema: SubmitInput,
-      },
-    }
+  ? { download: { description: DownloadInput.description ?? '', inputSchema: DownloadInput } }
+  : { submit: { description: SubmitInput.description ?? '', inputSchema: SubmitInput } }
 
 // Merges the mode-appropriate finalisation tool into the caller's static
 // tool map. The constraint `T & { submit?: never; download?: never }`

copilot/src/lib/embed-bridge-adapters/client-tools/finalisation.ts

@@ -1,26 +1,9 @@
-export type { ToolInput } from './dispatch'
-export { dispatch } from './dispatch'
-export type { ClientTools, CreateClientToolsArgs } from './factory'
+export type { ClientTools, CreateClientToolsArgs, ToolInput } from './factory'
 export { createClientTools } from './factory'
 export type { FinalisationAction, FinalisationToolMap } from './finalisation'
 export { FINALISATION_ACTION, FINALISATION_TOOL, withFinalisationTool } from './finalisation'
 export type { MiddlewareContext, ToolMiddleware } from './middleware'
 export { composeMiddleware } from './middleware'
 export type { ClientToolName } from './schemas'
-export {
-  CLIENT_TOOL_SCHEMAS,
-  DeleteFieldsInput,
-  DeletePagesInput,
-  DetectFieldsInput,
-  DownloadInput,
-  FocusFieldInput,
-  GetDocumentContentInput,
-  GetFieldsInput,
-  GoToPageInput,
-  isClientToolName,
-  MovePageInput,
-  RotatePageInput,
-  SelectToolInput,
-  SetFieldValueInput,
-  SubmitInput,
-} from './schemas'
+export { CLIENT_TOOL_NAMES, isClientToolName } from './schemas'
+export { LLM_STATIC_TOOLS } from './tools'

copilot/src/lib/embed-bridge-adapters/client-tools/index.ts

@@ -1,5 +1,5 @@
 import type { BridgeResult } from '../../embed-bridge'
-import type { ToolInput } from './dispatch'
+import type { ToolInput } from './factory'
 import type { ClientToolName } from './schemas'
 
 // Onion-style middleware. Each layer receives a context (tool name + input)