jat-feedback 2.0.1 → 3.0.0

package/README.md

@@ -6,7 +6,7 @@ Reports are stored in your Supabase database. The JAT ingest daemon polls for ne
 
 ```
 User clicks "Report Bug" → Widget captures context → POST /api/feedback/report
-  → Supabase feedback_reports table → JAT ingest daemon → JAT task created
+  → Supabase project_tasks table → JAT ingest daemon → JAT task created
 ```
 
 ## Install
@@ -128,6 +128,138 @@ ANTHROPIC_API_KEY=sk-ant-...
 
 The Agent tab appears automatically when `agent-proxy` is set. Without it, only the feedback form and history tabs are shown.
 
+### 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.
+
+#### `registerTools()` API Reference
+
+```typescript
+interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>; // JSON Schema object
+  handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+
+const widget = document.querySelector('jat-feedback');
+widget.registerTools(tools: ToolDefinition[]): void
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `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. |
+
+**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
+
+#### Example: Global Tools in SvelteKit
+
+Register tools in your root `+layout.svelte` so they're available on every page. For page-specific tools, call `registerTools()` again in that page's layout or component — tools accumulate across calls.
+
+```svelte
+<script lang="ts">
+  import { page } from "$app/stores"
+  import { onMount } from "svelte"
+
+  onMount(() => {
+    const widget = document.querySelector("jat-feedback")
+    if (!widget?.registerTools) return
+
+    widget.registerTools([
+      {
+        name: "get_current_user",
+        description: "Get the currently authenticated user profile",
+        parameters: { type: "object", properties: {} },
+        handler: async () => {
+          const session = $page.data.session
+          if (!session?.user) return { authenticated: false }
+          const u = session.user
+          return {
+            authenticated: true,
+            id: u.id,
+            email: u.email,
+            name: u.user_metadata?.full_name ?? null,
+          }
+        },
+      },
+      {
+        name: "get_current_route",
+        description: "Get the current page URL, pathname, and route parameters",
+        parameters: { type: "object", properties: {} },
+        handler: async () => ({
+          pathname: $page.url.pathname,
+          params: $page.params,
+          search: Object.fromEntries($page.url.searchParams),
+        }),
+      },
+      {
+        name: "get_page_data",
+        description: "Get data exposed by the current page's load function",
+        parameters: { type: "object", properties: {} },
+        handler: async () => {
+          const { supabase, session, ...rest } = $page.data
+          return rest
+        },
+      },
+    ])
+  })
+</script>
+```
+
+#### Example: Page-Specific Tools
+
+Add tools that only make sense on a specific page:
+
+```svelte
+<!-- src/routes/admin/reports/+page.svelte -->
+<script lang="ts">
+  import { onMount } from "svelte"
+
+  onMount(() => {
+    const widget = document.querySelector("jat-feedback")
+    if (!widget?.registerTools) return
+
+    widget.registerTools([
+      {
+        name: "update_report_status",
+        description: "Update a feedback report status",
+        parameters: {
+          type: "object",
+          properties: {
+            report_id: { type: "string" },
+            status: { type: "string", enum: ["open", "in_progress", "resolved"] },
+          },
+          required: ["report_id", "status"],
+        },
+        handler: async (args) => {
+          const { error } = await supabase
+            .from("project_tasks")
+            .update({ status: args.status })
+            .eq("id", args.report_id)
+          if (error) throw new Error(error.message)
+          return { success: true }
+        },
+      },
+    ])
+  })
+</script>
+```
+
+#### 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
+
 ### Error Handling
 
 The widget handles proxy errors gracefully:
@@ -438,7 +570,7 @@ export const POST: RequestHandler = async ({ request, locals }) => {
     const reporter = body.metadata?.reporter || {};
 
     const { data: row, error: insertError } = await supabase
-      .from('feedback_reports')
+      .from('project_tasks')
       .insert({
         title: body.title.trim(),
         description: body.description?.trim() || '',
@@ -479,18 +611,21 @@ export const POST: RequestHandler = async ({ request, locals }) => {
 
 ### Step 3: Run the Supabase Migration
 
-The `feedback_reports` table schema is included in this package. Copy it into your migrations folder and push:
+The `project_tasks` table schema is included in this package. Copy it into your migrations folder and push:
 
 ```bash
-# Copy the migration (rename to match your timestamp convention)
-cp node_modules/jat-feedback/supabase/migrations/1.0.0_feedback_reports.sql \
-   supabase/migrations/$(date +%Y%m%d%H%M%S)_feedback_reports.sql
+# Copy ALL migrations (rename to match your timestamp convention)
+for f in node_modules/jat-feedback/supabase/migrations/*.sql; do
+  base=$(basename "$f" .sql)
+  cp "$f" "supabase/migrations/$(date +%Y%m%d%H%M%S)_feedback_${base}.sql"
+  sleep 1  # ensure unique timestamps
+done
 
 # Push to Supabase
 supabase db push
 ```
 
-**When upgrading jat-feedback:** check `node_modules/jat-feedback/supabase/migrations/` for new versioned files (e.g. `1.1.0_*.sql`) and copy+apply any you haven't run yet.
+**When upgrading jat-feedback:** check `node_modules/jat-feedback/supabase/migrations/` for new versioned files and copy+apply any you haven't run yet. The `3.0.0_rename_to_project_tasks.sql` migration renames `feedback_reports` to `project_tasks`.
 
 ### Step 4: Wire User Context
 
@@ -555,7 +690,7 @@ Add this entry to the `sources` array.
     "priority": 2,
     "labels": ["widget", "feedback"]
   },
-  "table": "feedback_reports",
+  "table": "project_tasks",
   "statusColumn": "status",
   "statusNew": "submitted",
   "taskIdColumn": "jat_task_id",
@@ -586,7 +721,7 @@ Add this entry to the `sources` array.
   },
   "projectUrl": "https://YOUR_SUPABASE_PROJECT_ID.supabase.co",
   "secretName": "YOUR_PROJECT-supabase-service-role",
-  "table": "feedback_reports",
+  "table": "project_tasks",
   "statusColumn": "status",
   "statusNew": "submitted",
   "taskIdColumn": "jat_task_id",
@@ -617,7 +752,7 @@ Add this entry to the `sources` array.
       "in_progress": "in_progress",
       "closed": "completed"
     },
-    "referenceTable": "feedback_reports",
+    "referenceTable": "project_tasks",
     "referenceIdFrom": "item_id"
   },
   "actions": [
@@ -634,7 +769,7 @@ Add this entry to the `sources` array.
       "label": "View in Supabase",
       "description": "Open the original feedback report in Supabase dashboard",
       "type": "link",
-      "urlTemplate": "{projectUrl}/project/default/editor/feedback_reports?filter=id%3Deq.{referenceId}",
+      "urlTemplate": "{projectUrl}/project/default/editor/project_tasks?filter=id%3Deq.{referenceId}",
       "icon": "external-link"
     }
   ]
@@ -649,7 +784,7 @@ The ingest daemon picks up config changes automatically (no restart needed).
 
 ### Step 6: Deploy the JAT Webhook Edge Function (for callbacks)
 
-The `jat-webhook` Supabase Edge Function receives status-change callbacks from JAT and updates your `feedback_reports` rows. It's included in this package — copy it into your project and deploy it.
+The `jat-webhook` Supabase Edge Function receives status-change callbacks from JAT and updates your `project_tasks` rows. It's included in this package — copy it into your project and deploy it.
 
 ```bash
 # Copy the function into your project
@@ -657,11 +792,19 @@ mkdir -p supabase/functions/jat-webhook
 cp node_modules/jat-feedback/supabase/functions/jat-webhook/index.ts \
    supabase/functions/jat-webhook/index.ts
 
-# Deploy to Supabase
-supabase functions deploy jat-webhook
+# Deploy to Supabase (--no-verify-jwt required for service role key auth)
+supabase functions deploy jat-webhook --no-verify-jwt
 ```
 
-The function uses `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` — both are injected automatically by Supabase, no extra configuration needed.
+The function uses `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` — both are injected automatically by Supabase.
+
+**If callbacks fail with "Invalid authorization":** Newer Supabase projects use an `sb_secret_` format for the runtime `SUPABASE_SERVICE_ROLE_KEY`, which doesn't match the JWT service role key that JAT sends. Set a custom secret:
+
+```bash
+supabase secrets set JAT_WEBHOOK_SECRET="eyJhbG..."  # paste your JWT service role key from API settings
+```
+
+The function checks `JAT_WEBHOOK_SECRET` first, falling back to `SUPABASE_SERVICE_ROLE_KEY`.
 
 **Skip this step** if you don't need bidirectional status sync (i.e., you only want JAT to ingest reports, not push status back to Supabase).
 
@@ -677,7 +820,7 @@ jat ingest status
 # → Should list your project's feedback source
 
 # Submit a test report via the widget, then check:
-# 1. Row appears in feedback_reports table
+# 1. Row appears in project_tasks table
 # 2. JAT task gets created after next poll cycle (pollInterval seconds)
 ```
 
@@ -702,14 +845,22 @@ jat ingest status
 
 ## Column Reference
 
-The `feedback_reports` table columns used by the pipeline:
-
-| Column | Type | Purpose |
-|--------|------|---------|
-| `status` | TEXT | Lifecycle: `submitted` → `in_progress` → `completed` → `accepted` \| `rejected` |
-| `jat_task_id` | TEXT | JAT task ID written back after ingest (e.g., `myapp-abc`) |
-| `rejection_reason` | TEXT | User-provided reason when rejecting a completed report |
-| `dev_notes` | TEXT | Developer notes pushed back via callback |
+The `project_tasks` table columns used by the pipeline:
+
+| Column | Type | Since | Purpose |
+|--------|------|-------|---------|
+| `status` | TEXT | 1.0.0 | Lifecycle: `submitted` → `in_progress` → `completed` → `accepted` \| `rejected` |
+| `jat_task_id` | TEXT | 1.0.0 | JAT task ID written back after ingest (e.g., `myapp-abc`) |
+| `rejection_reason` | TEXT | 1.0.0 | User-provided reason when rejecting a completed report |
+| `dev_notes` | TEXT | 1.0.0 | Developer notes pushed back via callback |
+| `source_type` | TEXT | 3.0.0 | Original `type` column renamed — `bug`, `enhancement`, `other` |
+| `source` | TEXT | 3.0.0 | Where the item came from: `feedback`, `jat`, `manual` |
+| `issue_type` | TEXT | 3.0.0 | Classification: `bug`, `feature`, `task`, `epic` |
+| `assignee` | TEXT | 3.0.0 | Assigned agent or person |
+| `due_date` | TIMESTAMPTZ | 3.0.0 | Due date for the task |
+| `labels` | TEXT[] | 3.0.0 | Flexible categorization labels |
+| `parent_id` | UUID | 3.0.0 | Self-referential parent for hierarchical tasks |
+| `updated_at` | TIMESTAMPTZ | 3.0.0 | Auto-updated timestamp |
 
 ## Upgrading
 
@@ -746,7 +897,7 @@ supabase db push
 cp node_modules/jat-feedback/supabase/functions/jat-webhook/index.ts \
    supabase/functions/jat-webhook/index.ts
 
-supabase functions deploy jat-webhook
+supabase functions deploy jat-webhook --no-verify-jwt
 ```
 
 ## Versioning