jat-feedback 3.7.1 → 4.0.0

package/README.md

@@ -35,6 +35,8 @@ The package includes the widget bundle, Supabase migration, and edge function
 | `agent-proxy` | No | `''` | URL path for the LLM proxy endpoint (e.g., `'/api/feedback/agent'`). Enables the Agent tab. |
 | `agent-model` | No | `'claude-sonnet-4-6'` | LLM model identifier passed to the proxy endpoint |
 | `agent-context` | No | `''` | Static app context injected into Agent system prompt (describe your app, key pages, nav) |
+| `agent-role` | No | `''` | Role identifier for the current user (e.g. `'dispatcher'`, `'owner'`, `'tech'`). Injected as `[Role: X]` in the system prompt so the LLM can tailor tone, available tools, and safety defaults per role. |
+| `approval-required-tools` | No | `''` | Comma-separated list of tool names that require user approval before executing (e.g. `'reassign_job,delete_user'`). Replaces the default set of four DOM-modifying built-ins. Omit to keep default gating. See [Approval-Required Tools](#approval-required-tools). |
 
 ## Agent Tab: LLM Proxy Endpoint
 
@@ -130,18 +132,34 @@ The Agent tab appears automatically when `agent-proxy` is set. Without it, only
 
 ### Page-Level Tool Registration
 
-Register custom tools that the agent can call during its execution loop. Tools run client-side with full access to your app's state, auth context, and data — the LLM decides when to call them and reasons over the results.
+Register custom tools that the agent can call during its execution loop. Tools come in two flavors — pick the one that fits the data and trust boundary:
+
+- **Client tools** (default) run in the browser with full access to your app's state, auth context, and DOM. Use these for read-only page state (current user, current route, page data) and anything the user is already authenticated to do client-side.
+- **Server tools** forward the call to your proxy at `{agent-proxy}/tool/execute` and execute server-side with your own authenticated context (e.g. SvelteKit `locals.currentOrg`). Use these for cross-tenant lookups, privileged writes, or anything that touches secrets — the widget never sees them.
+
+The LLM doesn't care which kind a tool is — it sees the same name + description + parameters either way. The widget renders results identically.
 
 #### `registerTools()` API Reference
 
 ```typescript
-interface ToolDefinition {
+type ToolDefinition = ClientToolDefinition | ServerToolDefinition;
+
+interface ClientToolDefinition {
   name: string;
   description: string;
-  parameters: Record<string, unknown>; // JSON Schema object
+  parameters: Record<string, unknown>;       // JSON Schema object
+  executor?: 'client';                       // optional, default
   handler: (args: Record<string, unknown>) => Promise<unknown>;
 }
 
+interface ServerToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;       // JSON Schema object
+  executor: 'server';                        // required
+  // No handler — execution happens at {agent-proxy}/tool/execute
+}
+
 const widget = document.querySelector('jat-feedback');
 widget.registerTools(tools: ToolDefinition[]): void
 ```
@@ -151,13 +169,15 @@ widget.registerTools(tools: ToolDefinition[]): void
 | `name` | `string` | Unique tool name (snake_case). The LLM uses this to call the tool. |
 | `description` | `string` | Tells the LLM what the tool does and when to use it. |
 | `parameters` | `object` | JSON Schema describing the tool's arguments. Use `{ type: 'object', properties: {} }` for no-arg tools. |
-| `handler` | `async (args) => any` | Runs client-side when the LLM calls the tool. Receives parsed args, returns any JSON-serializable value. |
+| `executor` | `'client' \| 'server'` | Where the tool runs. Omit (or `'client'`) for browser-side handlers. Set to `'server'` to forward execution to the proxy. |
+| `handler` | `async (args) => any` | **Client tools only.** Runs in the browser when the LLM calls the tool. Receives parsed args, returns any JSON-serializable value. |
 
 **Behavior:**
 - Multiple `registerTools()` calls **accumulate** — tools are added, not replaced
 - Register tools before the user opens the Agent tab (typically in `onMount`)
-- If a handler throws, the error message is returned to the LLM so it can recover gracefully
-- Handlers have full access to the page's DOM, stores, and JS context
+- If a client handler throws, the error message is returned to the LLM so it can recover gracefully
+- Client handlers have full access to the page's DOM, stores, and JS context
+- Server tools require an `agent-proxy` attribute — without it, the widget refuses to call them
 
 #### Example: Global Tools in SvelteKit
 
@@ -252,13 +272,188 @@ Add tools that only make sense on a specific page:
 </script>
 ```
 
+#### Example: Server Tool
+
+Server tools execute on your server with whatever org/auth context your proxy has. Declare them by name + description + parameter schema only — there's no client handler:
+
+```svelte
+<script lang="ts">
+  import { onMount } from "svelte"
+
+  onMount(() => {
+    const widget = document.querySelector("jat-feedback")
+    if (!widget?.registerTools) return
+
+    widget.registerTools([
+      {
+        name: "lookup_customer",
+        description: "Find a customer by email. Returns id, name, plan, and most-recent order.",
+        parameters: {
+          type: "object",
+          properties: { email: { type: "string", format: "email" } },
+          required: ["email"],
+        },
+        executor: "server",
+      },
+      {
+        name: "reassign_job",
+        description: "Reassign a job to a different dispatcher. Destructive — confirm before calling.",
+        parameters: {
+          type: "object",
+          properties: {
+            job_id: { type: "string" },
+            new_assignee_id: { type: "string" },
+          },
+          required: ["job_id", "new_assignee_id"],
+        },
+        executor: "server",
+      },
+    ])
+  })
+</script>
+```
+
+##### Proxy Contract: `POST {agent-proxy}/tool/execute`
+
+The widget POSTs the tool call as JSON; the proxy executes the tool and responds in one of two shapes.
+
+**Request:**
+
+```http
+POST /api/feedback/agent/tool/execute
+Content-Type: application/json
+
+{
+  "tool":  "lookup_customer",
+  "args":  { "email": "ada@example.com" },
+  "model": "claude-sonnet-4-6"
+}
+```
+
+**Response — JSON (single result):**
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{ "result": { "id": "cust_123", "name": "Ada Lovelace", "plan": "pro" } }
+```
+
+Or, on a refused/errored call:
+
+```json
+{ "error": "Customer not found in your organization" }
+```
+
+**Response — SSE (streaming):**
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+
+data: {"type":"chunk","text":"Looking up customer…\n"}
+
+data: {"type":"chunk","text":"Found 1 match.\n"}
+
+data: {"type":"result","value":{"id":"cust_123","name":"Ada Lovelace","plan":"pro"}}
+```
+
+`chunk` events render live as a typing indicator inside the result message. The terminating `result` event delivers the structured value the LLM sees on its next step. An `error` event aborts the call and surfaces a user-facing error.
+
+##### SvelteKit Example: Wiring `/tool/execute`
+
+```ts
+// src/routes/api/feedback/agent/tool/execute/+server.ts
+import { json, error } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+
+const TOOLS: Record<string, (args: any, locals: App.Locals) => Promise<unknown>> = {
+  async lookup_customer(args, locals) {
+    if (!locals.currentOrg) throw error(403, 'no org context');
+    const { data, error: dbErr } = await locals.supabase
+      .from('customers')
+      .select('id, name, plan')
+      .eq('org_id', locals.currentOrg.id)
+      .eq('email', args.email)
+      .maybeSingle();
+    if (dbErr) throw error(500, dbErr.message);
+    if (!data) return { error: 'Customer not found in your organization' };
+    return { result: data };
+  },
+  // …
+};
+
+export const POST: RequestHandler = async ({ request, locals }) => {
+  const { tool, args } = await request.json();
+  const handler = TOOLS[tool];
+  if (!handler) return json({ error: `Unknown tool: ${tool}` });
+  try {
+    const result = await handler(args, locals);
+    return json(result);
+  } catch (err) {
+    return json({ error: err instanceof Error ? err.message : 'Tool failed' });
+  }
+};
+```
+
+For SSE, set `Content-Type: text/event-stream`, return a `ReadableStream`, and emit `data: {…}\n\n` lines per event. Always finish with a `result` event so the LLM sees a structured value.
+
 #### How Tools Work
 
 Tools are integrated into the page-agent's action loop:
 - The LLM sees registered tools alongside built-in browser actions (click, type, scroll, etc.)
 - Each agent step picks one action — either a browser action or a registered tool
 - Tool results feed back to the LLM on the next step automatically
-- If a handler throws, the error message is returned to the LLM so it can recover gracefully
+- If a client handler throws, the error message is returned to the LLM so it can recover gracefully
+- Server tools forward to `{agent-proxy}/tool/execute`; the LLM sees only the final structured value (or `error` message)
+
+### Approval-Required Tools
+
+By default, four DOM-modifying built-ins (`click_element_by_index`, `input_text`, `select_dropdown_option`, `execute_javascript`) require the user to click "Allow" before the agent executes them. v4 makes this set configurable.
+
+**Extend the default set (add your server tools):**
+
+```svelte
+<script>
+  import { onMount } from "svelte"
+
+  onMount(() => {
+    const widget = document.querySelector("jat-feedback")
+    if (!widget?.setApprovalRequiredTools) return
+    // Keep the default four DOM tools AND gate your custom tool
+    widget.setApprovalRequiredTools([
+      "click_element_by_index", "input_text", "select_dropdown_option",
+      "execute_javascript", "reassign_job"
+    ])
+  })
+</script>
+```
+
+**Replace the default set (only gate your tools):**
+
+```html
+<jat-feedback approval-required-tools="reassign_job,delete_user" ...></jat-feedback>
+```
+
+**Per-tool flag (no global list needed):**
+
+```typescript
+widget.registerTools([{
+  name: "delete_user",
+  description: "Permanently delete a user account",
+  parameters: { type: "object", properties: { user_id: { type: "string" } }, required: ["user_id"] },
+  executor: "server",
+  requireApproval: true,   // gates this tool regardless of the global list
+}])
+```
+
+**Disable approval prompts entirely:**
+
+```typescript
+widget.setApprovalRequiredTools([])  // empty list + no per-tool flags = no prompts
+```
+
+The exported `DEFAULT_APPROVAL_REQUIRED_TOOLS` constant lists the four built-in DOM tools — import it if you want to spread them into a custom list programmatically.
 
 ### Error Handling
 
@@ -862,6 +1057,49 @@ The `project_tasks` table columns used by the pipeline:
 | `parent_id` | UUID | 3.0.0 | Self-referential parent for hierarchical tasks |
 | `updated_at` | TIMESTAMPTZ | 3.0.0 | Auto-updated timestamp |
 
+## Upgrading from v3 to v4
+
+v4 promotes `ToolDefinition` from a flat interface to a discriminated union. Existing client tools continue to work at runtime unchanged — this is a TypeScript-types-only breaking change.
+
+### TypeScript: update `ToolDefinition` annotations
+
+```typescript
+// v3 (old)
+import type { ToolDefinition } from "jat-feedback"
+const tools: ToolDefinition[] = [...]
+
+// v4 (new) — same import, type is now ClientToolDefinition | ServerToolDefinition
+import type { ToolDefinition, ClientToolDefinition, ServerToolDefinition } from "jat-feedback"
+
+// If you have generic arrays, use the union type:
+const tools: ToolDefinition[] = [...]          // still works (union exported as ToolDefinition)
+
+// Or be specific:
+const clientTools: ClientToolDefinition[] = [...]
+const serverTools: ServerToolDefinition[] = [...]
+```
+
+**Existing tool objects don't need changes.** A plain `{ name, description, parameters, handler }` object satisfies `ClientToolDefinition` — `executor` defaults to `'client'` when omitted.
+
+### New: add server tools (optional)
+
+If you want tools that execute server-side with your auth context, see the [Server Tool](#example-server-tool) docs. No changes needed if you only use client tools.
+
+### New: configure approval gating (optional)
+
+The default approval behavior (four DOM built-ins) is unchanged. If you register server tools that should also require confirmation, use `requireApproval: true` on the tool definition or `widget.setApprovalRequiredTools([...])`. See [Approval-Required Tools](#approval-required-tools).
+
+### Bump the version
+
+```bash
+# In each consuming project
+npm install jat-feedback@^4.0.0
+```
+
+No schema migrations required for v4 — all changes are widget JS only.
+
+---
+
 ## Upgrading
 
 npm never auto-updates — you need to explicitly upgrade and then handle each type of change manually.