@graph8/sdk 0.308.1 → 0.357.0

package/blocks/workbench/block.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "../block.schema.json",
+  "id": "workbench",
+  "title": "Workbench (Clay-style)",
+  "summary": "A spreadsheet of records whose columns are filled by recipes: AI prompts, provider waterfalls and formulas. Priced runs, polled to the end, results sent to a list.",
+  "features": [
+    "workbench list with create and delete, and a grid with selectable rows and editable cells",
+    "add rows by typing or pasting a spreadsheet; locked rows from a search import show masked cells",
+    "column recipes: AI prompt with {{column}} placeholders, enrichment waterfall presets, formulas, plain columns, target-field mapping",
+    "runs are quoted for free, confirmed with the exact credits, started with the quote as the cap and followed to a final receipt",
+    "unlock locked rows (1 credit each), send rows to a list, delete rows"
+  ],
+  "dependsOn": [
+    "enrichment",
+    "lists"
+  ],
+  "operations": [
+    "add_workbench_column_workbench_tables__table_id__columns_post",
+    "add_workbench_row_workbench_tables__table_id__rows_post",
+    "bulk_delete_workbench_rows_workbench_tables__table_id__rows_bulk_delete_post",
+    "create_workbench_formula_columns_workbench_tables__table_id__formula_columns_post",
+    "create_workbench_table_workbench_tables_post",
+    "delete_workbench_table_workbench_tables__table_id__delete",
+    "estimate_workbench_scraper_credits_workbench_scraper_credit_estimate_get",
+    "export_workbench_table_workbench_tables__table_id__export_post",
+    "get_workbench_analytics_workbench_tables__table_id__analytics_get",
+    "get_workbench_history_workbench_tables__table_id__history_get",
+    "get_workbench_scraper_run_workbench_tables__table_id__scraper_runs__run_id__get",
+    "get_workbench_table_workbench_tables__table_id__get",
+    "import_workbench_from_search_workbench_tables__table_id__import_search_post",
+    "list_enrichment_providers_enrichment_providers_get",
+    "list_workbench_columns_workbench_tables__table_id__columns_get",
+    "list_workbench_rows_workbench_tables__table_id__rows_get",
+    "list_workbench_tables_workbench_tables_get",
+    "list_workbench_target_fields_workbench_target_fields_get",
+    "map_workbench_column_workbench_tables__table_id__columns__column_id__mapping_put",
+    "paste_import_workbench_rows_workbench_tables__table_id__import_paste_post",
+    "preview_workbench_search_import_workbench_tables__table_id__import_search_preview_post",
+    "quote_workbench_ai_run_workbench_tables__table_id__ai_validate_credits_post",
+    "quote_workbench_unlock_workbench_tables__table_id__unlock_quote_post",
+    "quote_workbench_waterfall_run_workbench_tables__table_id__waterfall_configs__column_id__validate_credits_post",
+    "run_workbench_column_ai_workbench_tables__table_id__columns__col_id__ai_run_post",
+    "run_workbench_default_ai_workbench_tables__table_id__ai_run_post",
+    "run_workbench_scraper_workbench_tables__table_id__scraper_runs_post",
+    "run_workbench_waterfall_workbench_tables__table_id__waterfall_configs__column_id__run_post",
+    "save_workbench_column_ai_config_workbench_tables__table_id__columns__col_id__ai_config_put",
+    "save_workbench_waterfall_workbench_tables__table_id__waterfall_configs_post",
+    "unlock_workbench_rows_workbench_tables__table_id__unlock_rows_post",
+    "update_workbench_row_workbench_tables__table_id__rows__row_id__patch"
+  ],
+  "components": [
+    {
+      "name": "WorkbenchTableList",
+      "file": "components/workbench-table-list.tsx",
+      "purpose": "The workspace's workbenches with search, create (people or companies) and delete; opening one hands it to onOpen, or (no onOpen) shows it in a WorkbenchGrid.",
+      "operations": [
+        "list_workbench_tables_workbench_tables_get",
+        "create_workbench_table_workbench_tables_post",
+        "delete_workbench_table_workbench_tables__table_id__delete"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "destructive"
+      ]
+    },
+    {
+      "name": "WorkbenchGrid",
+      "file": "components/workbench-grid.tsx",
+      "purpose": "The table itself: rows by columns, selection, double-click cell edit, run buttons on recipe columns, and the panels for adding rows, columns and acting on the selection.",
+      "operations": [
+        "get_workbench_table_workbench_tables__table_id__get",
+        "list_workbench_columns_workbench_tables__table_id__columns_get",
+        "list_workbench_rows_workbench_tables__table_id__rows_get",
+        "update_workbench_row_workbench_tables__table_id__rows__row_id__patch"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "WorkbenchAddRows",
+      "file": "components/workbench-add-rows.tsx",
+      "purpose": "Add one row typed into the table's columns, or paste many rows from a spreadsheet (the header line creates columns).",
+      "operations": [
+        "add_workbench_row_workbench_tables__table_id__rows_post",
+        "paste_import_workbench_rows_workbench_tables__table_id__import_paste_post"
+      ],
+      "tiers": [
+        "write"
+      ]
+    },
+    {
+      "name": "ColumnRecipeEditor",
+      "file": "components/column-recipe-editor.tsx",
+      "purpose": "Add a column and say how it is filled: AI prompt, enrichment waterfall preset, formula or plain data; map your columns to graph8 target fields. Saving never spends credits.",
+      "operations": [
+        "add_workbench_column_workbench_tables__table_id__columns_post",
+        "save_workbench_column_ai_config_workbench_tables__table_id__columns__col_id__ai_config_put",
+        "save_workbench_waterfall_workbench_tables__table_id__waterfall_configs_post",
+        "create_workbench_formula_columns_workbench_tables__table_id__formula_columns_post",
+        "list_workbench_target_fields_workbench_target_fields_get",
+        "map_workbench_column_workbench_tables__table_id__columns__column_id__mapping_put",
+        "list_enrichment_providers_enrichment_providers_get"
+      ],
+      "tiers": [
+        "read",
+        "write"
+      ]
+    },
+    {
+      "name": "RunProgress",
+      "file": "components/run-progress.tsx",
+      "purpose": "Run an AI or waterfall column over some or all rows: free quote, ConfirmSpendDialog with the exact credits, start with the quote as the cap, poll the history receipt to a final state.",
+      "operations": [
+        "quote_workbench_ai_run_workbench_tables__table_id__ai_validate_credits_post",
+        "quote_workbench_waterfall_run_workbench_tables__table_id__waterfall_configs__column_id__validate_credits_post",
+        "run_workbench_column_ai_workbench_tables__table_id__columns__col_id__ai_run_post",
+        "run_workbench_default_ai_workbench_tables__table_id__ai_run_post",
+        "run_workbench_waterfall_workbench_tables__table_id__waterfall_configs__column_id__run_post",
+        "get_workbench_history_workbench_tables__table_id__history_get",
+        "get_workbench_analytics_workbench_tables__table_id__analytics_get"
+      ],
+      "tiers": [
+        "read",
+        "billable"
+      ]
+    },
+    {
+      "name": "WorkbenchRowActions",
+      "file": "components/workbench-row-actions.tsx",
+      "purpose": "Act on the selected rows: quote then unlock locked rows (1 credit each), send rows to a list, delete rows (confirmed).",
+      "operations": [
+        "quote_workbench_unlock_workbench_tables__table_id__unlock_quote_post",
+        "unlock_workbench_rows_workbench_tables__table_id__unlock_rows_post",
+        "export_workbench_table_workbench_tables__table_id__export_post",
+        "bulk_delete_workbench_rows_workbench_tables__table_id__rows_bulk_delete_post"
+      ],
+      "tiers": [
+        "read",
+        "write",
+        "billable",
+        "destructive"
+      ]
+    }
+  ],
+  "hooks": [
+    {
+      "name": "useWorkbenchTable",
+      "file": "hooks/use-workbench-table.ts",
+      "purpose": "A table and its columns, with one refetch for both.",
+      "operations": [
+        "get_workbench_table_workbench_tables__table_id__get",
+        "list_workbench_columns_workbench_tables__table_id__columns_get"
+      ]
+    }
+  ],
+  "lib": [
+    {
+      "file": "lib/workbench-types.ts",
+      "purpose": "Table, column, row, quote and receipt shapes; cellValue, isLocked, toMachineName, parsePasted and the run-receipt matching helpers."
+    },
+    {
+      "file": "lib/waterfall-presets.ts",
+      "purpose": "Waterfall presets (work email, mobile phone, LinkedIn URL, company phone) copied from graph8's own templates, and buildWaterfallConfig for the save body."
+    }
+  ],
+  "recipes": [
+    {
+      "file": "recipes/build-enriched-table.ts",
+      "title": "Build a workbench: rows in, an AI column, a quote, a run, the results",
+      "when": "Starting a table from a pasted list. Create the table, paste rows, add an AI column (free), QUOTE the run (free), get a human to approve the price, run with the quote's numbers as the cap, poll the history receipt, read the rows. A run without row_ids runs every row and the quote prices exactly that."
+    },
+    {
+      "file": "recipes/waterfall-column.ts",
+      "title": "Add an enrichment waterfall column, price it, run it",
+      "when": "Finding work emails or phones for people in a table. Map columns to graph8 targets first, save the waterfall (free, never runs), quote, approve, run. Providers on graph8's key spend credits; providers on your own key do not."
+    },
+    {
+      "file": "recipes/import-from-search.ts",
+      "title": "Import people from a prospect search, unlock the ones you want, send them to a list",
+      "when": "Filling a workbench from graph8's people index. The preview is free; the import is billable and lands locked rows with masked emails and phones. Quote the unlock, approve, unlock (1 credit per row), then export the rows to a list."
+    },
+    {
+      "file": "recipes/scrape-into-table.ts",
+      "title": "Scrape the web into a table with the built-in scraper",
+      "when": "Collecting companies or people from a description. The scraper charges per result and auto_enrich adds enrichment of each on top: get the free credit estimate, approve it, run with it as the cap, poll the run."
+    }
+  ],
+  "prerequisites": [
+    {
+      "id": "enrichment-and-lists-installed",
+      "where": "app",
+      "description": "The enrichment and lists blocks are installed (the CLI does it): the waterfall presets read the provider catalog and rows are sent to lists with the list picker.",
+      "verify": "components/g8/enrichment/ and components/g8/lists/ exist."
+    },
+    {
+      "id": "proxy-allowlist",
+      "where": "app",
+      "description": "allowedPrefixes in the /api/g8 route includes `workbench`, `enrichment` and `lists`.",
+      "verify": "GET /api/g8/workbench/tables returns 200 when signed in."
+    },
+    {
+      "id": "provider-keys",
+      "where": "api",
+      "description": "Waterfall steps on providers that graph8 does not fund need the workspace's own API key saved in graph8 settings (Integrations). There is no API to add provider keys.",
+      "verify": "GET /enrichment/providers shows byok_configured true for the provider."
+    },
+    {
+      "id": "credits",
+      "where": "api",
+      "description": "The workspace has credits for AI columns, graph8-funded providers, scraping and unlocking rows. The quotes show the live balance and a shortfall; a run without enough credits is refused.",
+      "verify": "A quote answers can_run true."
+    }
+  ],
+  "scopes": [
+    "enrichment:read",
+    "lists:delete",
+    "lists:read",
+    "lists:run",
+    "lists:write"
+  ],
+  "defaults": [
+    {
+      "decision": "Rows a run covers",
+      "default": "The selected rows; with no selection, every row (the quote and the confirmation say so)",
+      "askHuman": false
+    },
+    {
+      "decision": "Who approves a run's price",
+      "default": "The person at the confirmation dialog; never an automatic approval of the quote",
+      "askHuman": true
+    },
+    {
+      "decision": "Waterfall auto-update on new rows",
+      "default": "Off: saving a waterfall never starts spending on new rows",
+      "askHuman": false
+    },
+    {
+      "decision": "Waterfall providers and order",
+      "default": "The preset's order (for work email: apollo, leadmagic, prospeo, hunter, dropcontact), each on your own key if configured, else graph8's",
+      "askHuman": false
+    },
+    {
+      "decision": "AI column web research",
+      "default": "Off (content generation); the person can tick web research per column",
+      "askHuman": false
+    },
+    {
+      "decision": "Where finished rows go",
+      "default": "A list picked or created in the row actions panel",
+      "askHuman": false
+    }
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  }
+}

package/blocks/workbench/components/column-recipe-editor.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+/**
+ * ColumnRecipeEditor: add a column to a workbench table and say how it is filled. Five tabs:
+ *   AI         a prompt that can use other columns as {{column_name}}; fills the column per row
+ *   Enrichment a provider waterfall (try provider A, then B...) for work email, phone or LinkedIn URL
+ *   Formula    a formula that derives a column from the others
+ *   Column     a plain data column
+ *   Map        tell graph8 which of YOUR columns is the first name, website... (waterfall steps read those)
+ *
+ * SDK operations, in order (per tab):
+ *   AI:         addWorkbenchColumn POST .../columns {name, display_name}   -> { id }
+ *               saveWorkbenchColumnAiConfig PUT .../columns/{col_id}/ai-config { prompt, usecase }
+ *   Enrichment: listEnrichmentProviders GET /enrichment/providers (read; own key vs graph8's key)
+ *               saveWorkbenchWaterfall POST .../waterfall/configs { config }   (write: saving never runs or charges anything)
+ *   Formula:    createWorkbenchFormulaColumns POST .../formula-columns { formula, output_columns }
+ *   Column:     addWorkbenchColumn
+ *   Map:        listWorkbenchTargetFields GET /workbench/target-fields?entity_type, mapWorkbenchColumn PUT .../columns/{id}/mapping { mapping_target }
+ * Nothing here spends credits: running the recipe is RunProgress (quote, confirm, run). The waterfall is saved with
+ * auto_update off so it does not start spending on new rows by itself.
+ */
+
+import { useRef, useState } from "react";
+import { Button, Input, Label, Textarea } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useG8Query } from "@/g8/hooks/use-g8-query";
+import { g8Get, g8Post, g8Put } from "@/g8/lib/g8-client";
+import { useProviders } from "@/g8/enrichment/hooks/use-providers";
+import { WATERFALL_PRESETS, buildWaterfallConfig, requiredTargets } from "../lib/waterfall-presets";
+import { pageItems, toMachineName } from "../lib/workbench-types";
+import type { WorkbenchColumn } from "../lib/workbench-types";
+
+export interface ColumnRecipeEditorProps {
+  tableId: string;
+  columns: WorkbenchColumn[];
+  /** The table's record kind; decides which target fields the Map tab offers. Default "contact". */
+  entityType?: "contact" | "company";
+  /** Called after a column was created or mapped so the grid can reload its columns. */
+  onSaved?: () => void;
+  className?: string;
+}
+
+type Tab = "ai" | "enrichment" | "formula" | "column" | "map";
+const TABS: Array<{ id: Tab; label: string }> = [
+  { id: "ai", label: "AI" },
+  { id: "enrichment", label: "Enrichment" },
+  { id: "formula", label: "Formula" },
+  { id: "column", label: "Column" },
+  { id: "map", label: "Map columns" },
+];
+const newId = () => globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+export function ColumnRecipeEditor({ tableId, columns, entityType = "contact", onSaved, className }: ColumnRecipeEditorProps) {
+  const [tab, setTab] = useState<Tab>("ai");
+  const [name, setName] = useState("");
+  const [prompt, setPrompt] = useState("");
+  const [research, setResearch] = useState(false);
+  const [presetId, setPresetId] = useState(WATERFALL_PRESETS[0].id);
+  const [skipped, setSkipped] = useState<string[]>([]);
+  const [formula, setFormula] = useState("");
+  const [notice, setNotice] = useState<string | null>(null);
+  const catalog = useProviders(tab === "enrichment");
+  const targets = useG8Query(async (signal) => pageItems<{ field: string; label: string }>((await g8Get("/workbench/target-fields", { entity_type: entityType }, { signal })).data), [entityType], { enabled: tab === "map" });
+
+  const preset = WATERFALL_PRESETS.find((p) => p.id === presetId)!;
+  const steps = preset.steps.filter((s) => !skipped.includes(s.provider));
+  const machine = toMachineName(name);
+  const done = (message: string) => { setNotice(message); setName(""); setPrompt(""); setFormula(""); onSaved?.(); };
+  const mapped = new Set(columns.map((c) => c.mapping_target).filter(Boolean));
+  const unmapped = requiredTargets(steps).filter((t) => !mapped.has(t));
+
+  // Retry-safe: the column made by step 1 is remembered, so a retry after step 2 failed does not create it twice (409).
+  const created = useRef<{ key: string; id: number } | null>(null);
+  const addAi = useG8Mutation(async () => {
+    const key = `${tableId}:${machine}`;
+    if (created.current?.key !== key) {
+      const col = await g8Post<{ id: number }>(`/workbench/tables/${tableId}/columns`, { name: machine, display_name: name.trim(), data_type: "text" });
+      created.current = { key, id: col.data.id };
+    }
+    await g8Put(`/workbench/tables/${tableId}/columns/${created.current.id}/ai-config`, { prompt: prompt.trim(), usecase: research ? "web-research" : "content_generation" });
+  }, { onSuccess: () => { created.current = null; done("AI column saved. Nothing has run yet."); } });
+  const addPlain = useG8Mutation(() => g8Post(`/workbench/tables/${tableId}/columns`, { name: machine, display_name: name.trim(), data_type: "text" }), { onSuccess: () => done("Column added.") });
+  const addFormula = useG8Mutation(
+    () => g8Post(`/workbench/tables/${tableId}/formula-columns`, { formula: formula.trim(), output_columns: [{ name: machine, display_name: name.trim() }] }),
+    { onSuccess: () => done("Formula column added.") },
+  );
+  const addWaterfall = useG8Mutation(
+    () => g8Post(`/workbench/tables/${tableId}/waterfall/configs`, buildWaterfallConfig(name.trim() || preset.columnName, steps, catalog.providers, newId)),
+    { onSuccess: () => done("Enrichment column saved. Nothing has run yet.") },
+  );
+  const map = useG8Mutation((v: { id: number; target: string | null }) => g8Put(`/workbench/tables/${tableId}/columns/${v.id}/mapping`, { mapping_target: v.target }), { onSuccess: () => onSaved?.() });
+
+  const nameField = (
+    <div className="flex flex-col gap-1">
+      <Label htmlFor="wb-col-name">Column name</Label>
+      <Input id="wb-col-name" value={name} onChange={(e) => setName(e.target.value)} placeholder={tab === "enrichment" ? preset.columnName : "Company summary"} />
+    </div>
+  );
+
+  return (
+    <div className={`flex flex-col gap-3 rounded-md border p-3 ${className ?? ""}`}>
+      <div role="tablist" aria-label="Column recipe" className="flex flex-wrap gap-2">
+        {TABS.map((t) => <Button key={t.id} role="tab" aria-selected={tab === t.id} size="sm" variant={tab === t.id ? "default" : "outline"} onClick={() => { setTab(t.id); setNotice(null); }}>{t.label}</Button>)}
+      </div>
+
+      {tab === "ai" ? (
+        <div className="flex flex-col gap-2">
+          {nameField}
+          <Label htmlFor="wb-ai-prompt">Prompt</Label>
+          <Textarea id="wb-ai-prompt" rows={5} value={prompt} onChange={(e) => setPrompt(e.target.value)} placeholder="Write a one-line summary of {{company_name}} ({{company_domain}})." />
+          <div className="flex flex-wrap gap-1" aria-label="Insert a column">
+            {columns.slice(0, 12).map((c) => <Button key={c.id} size="sm" variant="ghost" onClick={() => setPrompt(`${prompt}{{${c.name}}}`)}>{`{{${c.name}}}`}</Button>)}
+          </div>
+          <label className="flex items-center gap-2 text-sm"><input type="checkbox" checked={research} onChange={(e) => setResearch(e.target.checked)} /> Let the AI search the web (slower, costs more per row)</label>
+          {addAi.error ? <ApiError error={addAi.error} title="Could not save the AI column" /> : null}
+          <div><Button size="sm" loading={addAi.loading} disabled={!machine || !prompt.trim()} onClick={() => void addAi.mutate(undefined)}>Save AI column</Button></div>
+        </div>
+      ) : null}
+
+      {tab === "enrichment" ? (
+        <div className="flex flex-col gap-2">
+          <Label htmlFor="wb-preset">What to find</Label>
+          <select id="wb-preset" className="h-9 rounded-md border bg-background px-2" value={presetId} onChange={(e) => { setPresetId(e.target.value); setSkipped([]); }}>
+            {WATERFALL_PRESETS.map((p) => <option key={p.id} value={p.id}>{p.label}</option>)}
+          </select>
+          {nameField}
+          <fieldset className="flex flex-col gap-1"><legend className="mb-1 text-sm font-medium">Providers, tried in this order</legend>
+            {preset.steps.map((s, i) => {
+              const info = catalog.providers.find((p) => p.provider === s.provider);
+              return (
+                <label key={s.provider} className="flex items-center gap-2 text-sm">
+                  <input type="checkbox" aria-label={`Use ${s.provider}`} checked={!skipped.includes(s.provider)} onChange={() => setSkipped(skipped.includes(s.provider) ? skipped.filter((x) => x !== s.provider) : [...skipped, s.provider])} />
+                  <span className="w-6 text-muted-foreground">{i + 1}.</span><span className="font-medium">{s.provider}</span>
+                  <span className="text-xs text-muted-foreground">{info?.byok_configured ? "your key" : info?.system_funded ? "graph8 key, uses credits when run" : "needs your key"}</span>
+                </label>
+              );
+            })}
+          </fieldset>
+          {unmapped.length ? <p role="alert" className="text-sm text-amber-700">Not mapped yet: {unmapped.join(", ")}. Use the Map columns tab, or the steps that need them find nothing.</p> : null}
+          {addWaterfall.error ? <ApiError error={addWaterfall.error} title="Could not save the enrichment column" /> : null}
+          <div><Button size="sm" loading={addWaterfall.loading} disabled={steps.length === 0} onClick={() => void addWaterfall.mutate(undefined)}>Save enrichment column</Button></div>
+        </div>
+      ) : null}
+
+      {tab === "formula" ? (
+        <div className="flex flex-col gap-2">
+          {nameField}
+          <Label htmlFor="wb-formula">Formula</Label>
+          <Textarea id="wb-formula" rows={3} value={formula} onChange={(e) => setFormula(e.target.value)} placeholder="{{first_name}} {{last_name}}" />
+          {addFormula.error ? <ApiError error={addFormula.error} title="Could not add the formula column" /> : null}
+          <div><Button size="sm" loading={addFormula.loading} disabled={!machine || !formula.trim()} onClick={() => void addFormula.mutate(undefined)}>Add formula column</Button></div>
+        </div>
+      ) : null}
+
+      {tab === "column" ? (
+        <div className="flex flex-col gap-2">
+          {nameField}
+          {addPlain.error ? <ApiError error={addPlain.error} title="Could not add the column" /> : null}
+          <div><Button size="sm" loading={addPlain.loading} disabled={!machine} onClick={() => void addPlain.mutate(undefined)}>Add column</Button></div>
+        </div>
+      ) : null}
+
+      {tab === "map" ? (
+        <div className="flex flex-col gap-2">
+          <p className="text-sm text-muted-foreground">Tell graph8 what each of your columns holds, so enrichment steps know where the first name, last name and website are.</p>
+          {targets.error ? <ApiError error={targets.error} title="Could not load the fields" onRetry={() => void targets.refetch()} /> : null}
+          {map.error ? <ApiError error={map.error} title="Could not save the mapping" /> : null}
+          {columns.filter((c) => (c.column_type ?? "data") === "data" && !c.enrichment_type).map((c) => (
+            <label key={c.id} className="flex items-center gap-2 text-sm">
+              <span className="w-40 truncate font-medium">{c.display_name || c.name}</span>
+              <select aria-label={`Map ${c.display_name || c.name}`} className="h-9 rounded-md border bg-background px-2" value={c.mapping_target ?? ""} onChange={(e) => void map.mutate({ id: c.id, target: e.target.value || null })}>
+                <option value="">Not mapped</option>
+                {(targets.data ?? []).map((t) => <option key={t.field} value={t.field}>{t.label}</option>)}
+              </select>
+            </label>
+          ))}
+        </div>
+      ) : null}
+      {notice ? <p role="status" className="text-sm text-muted-foreground">{notice}</p> : null}
+    </div>
+  );
+}

package/blocks/workbench/components/run-progress.tsx

@@ -0,0 +1,132 @@
+"use client";
+
+/**
+ * RunProgress: run a recipe column (AI prompt or enrichment waterfall) over the rows of a table, with the price
+ * confirmed first and the run followed to the end. Runs are BILLABLE and an omitted row list means EVERY row.
+ *
+ * SDK operations, in order:
+ *   1. quoteWorkbenchAiRun / quoteWorkbenchWaterfallRun   POST .../ai/validate-credits | .../waterfall/configs/{column_id}/validate-credits
+ *        (read, free)  body { column_id, row_ids? }  -> required_credits, available_credits, estimated_records, quote_id, quote_expires_at
+ *   2. runWorkbenchColumnAi / runWorkbenchDefaultAi / runWorkbenchWaterfall   (billable)
+ *        POST .../columns/{col_id}/ai/run | .../ai/run | .../waterfall/configs/{column_id}/run, 202 { job_id, status: "queued" }
+ *        Goes through ConfirmSpendDialog first with the quote's required_credits. The same number goes back as
+ *        `approved_max_credits` with `quote_expires_at` and `quote_id`; a run whose price grew is refused until re-quoted.
+ *   3. getWorkbenchHistory   GET .../history?limit=10   (read)  polled with useJobPoll (the API has no streams); the run is the
+ *        receipt whose external_ref is the job id (else the newest receipt of that type that was not in the history before the run started), final when its
+ *        status is completed, partial, failed or cancelled.
+ *   4. getWorkbenchAnalytics GET .../analytics          (read)  rows per status while the run is going.
+ */
+
+import { useState } from "react";
+import { Button } from "@graph8/sdk/ui";
+import { ApiError } from "@/g8/components/api-error";
+import { ConfirmSpendDialog } from "@/g8/components/confirm-spend-dialog";
+import { useG8Mutation } from "@/g8/hooks/use-g8-mutation";
+import { useJobPoll } from "@/g8/hooks/use-job-poll";
+import { g8Get, g8Post } from "@/g8/lib/g8-client";
+import { findRunReceipt, isReceiptTerminal, pageItems, runTypes } from "../lib/workbench-types";
+import type { CreditQuote, OperationReceipt, RunTarget, TableAnalytics } from "../lib/workbench-types";
+
+export interface RunProgressProps {
+  tableId: string;
+  target: RunTarget;
+  /** Rows to run. Leave undefined to run every row; the quote and the confirmation then say so. */
+  rowIds?: number[];
+  /** Words for the button and dialog, for example the column's display name. */
+  label?: string;
+  onFinished?: (receipt: OperationReceipt) => void;
+  className?: string;
+}
+
+interface RunSnapshot { receipt?: OperationReceipt; analytics?: TableAnalytics }
+
+function quotePath(tableId: string, target: RunTarget): string {
+  return target.kind === "waterfall"
+    ? `/workbench/tables/${tableId}/waterfall/configs/${target.columnId}/validate-credits`
+    : `/workbench/tables/${tableId}/ai/validate-credits`;
+}
+
+function runPath(tableId: string, target: RunTarget): string {
+  if (target.kind === "waterfall") return `/workbench/tables/${tableId}/waterfall/configs/${target.columnId}/run`;
+  if (target.kind === "ai-column") return `/workbench/tables/${tableId}/columns/${target.columnId}/ai/run`;
+  return `/workbench/tables/${tableId}/ai/run`;
+}
+
+export function RunProgress({ tableId, target, rowIds, label = "this column", onFinished, className }: RunProgressProps) {
+  const [quote, setQuote] = useState<CreditQuote | null>(null);
+  const [job, setJob] = useState<{ id: string; before: string[] } | null>(null);
+  const scope = rowIds?.length ? `${rowIds.length.toLocaleString()} selected rows` : "every row";
+
+  const getQuote = useG8Mutation(
+    async () => {
+      const body = { ...(target.kind === "ai-default" ? {} : { column_id: target.columnId }), ...(rowIds?.length ? { row_ids: rowIds } : {}) };
+      return (await g8Post<CreditQuote>(quotePath(tableId, target), body)).data;
+    },
+    { onSuccess: (q) => setQuote(q) },
+  );
+  const start = useG8Mutation(
+    async (q: CreditQuote) => {
+      // Receipts that exist before the run: whatever appears afterwards, of this type, is this run's (clock-free matching).
+      const before = pageItems<OperationReceipt>((await g8Get(`/workbench/tables/${tableId}/history`, { limit: 50 })).data).map((r) => r.id);
+      const body = {
+        ...(rowIds?.length ? { row_ids: rowIds } : {}),
+        approved_max_credits: q.required_credits,
+        quote_expires_at: q.quote_expires_at,
+        ...(q.quote_id ? { quote_id: q.quote_id } : {}),
+      };
+      return { ...(await g8Post<{ job_id: string }>(runPath(tableId, target), body)).data, before };
+    },
+    { onSuccess: (res) => { setQuote(null); setJob({ id: res.job_id, before: res.before }); } },
+  );
+  const poll = useJobPoll<RunSnapshot>(
+    async (signal) => {
+      const history = await g8Get(`/workbench/tables/${tableId}/history`, { limit: 10 }, { signal });
+      const analytics = await g8Get<TableAnalytics>(`/workbench/tables/${tableId}/analytics`, undefined, { signal }).catch(() => null);
+      return { receipt: findRunReceipt(pageItems<OperationReceipt>(history.data), job!.id, job!.before, runTypes(target)), analytics: analytics?.data };
+    },
+    { enabled: job != null, intervalMs: 2000, maxAttempts: 150, isTerminal: (s) => isReceiptTerminal(s.receipt?.status), onDone: (s) => s.receipt && onFinished?.(s.receipt) },
+  );
+
+  const receipt = poll.status?.receipt;
+  const distribution = poll.status?.analytics?.status_distribution ?? {};
+  const short = quote?.can_run === false;
+
+  if (job) {
+    return (
+      <div className={`flex flex-col gap-2 rounded-md border p-3 ${className ?? ""}`} role="status">
+        <h3 className="text-sm font-semibold">{poll.done ? `Run ${receipt?.status ?? "finished"}` : "Running..."}</h3>
+        <p className="text-sm text-muted-foreground">
+          {receipt ? `${receipt.credits_charged ?? 0} credits charged so far.` : "Queued. The first update can take a few seconds."}
+          {Object.entries(distribution).length ? ` Rows: ${Object.entries(distribution).map(([k, v]) => `${v} ${k}`).join(", ")}.` : ""}
+        </p>
+        {receipt?.error_message ? <p className="text-sm text-destructive">{receipt.error_message}</p> : null}
+        {poll.error ? <ApiError error={poll.error} title="Could not read the run" onRetry={() => poll.start()} /> : null}
+        {!poll.done && !poll.polling && !poll.error ? <p className="text-xs text-muted-foreground">Stopped checking. The run may still be going: check again later.</p> : null}
+        <div className="flex gap-2">
+          {!poll.done ? <Button size="sm" variant="outline" onClick={() => poll.stop()}>Stop watching</Button> : null}
+          {poll.done || !poll.polling ? <Button size="sm" variant="outline" onClick={() => { poll.stop(); setJob(null); }}>Done</Button> : null}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`flex flex-col gap-2 ${className ?? ""}`}>
+      {getQuote.error ? <ApiError error={getQuote.error} title="Could not price the run" onRetry={() => void getQuote.mutate(undefined)} /> : null}
+      {start.error ? <ApiError error={start.error} title="Could not start the run" /> : null}
+      <div><Button size="sm" loading={getQuote.loading} onClick={() => void getQuote.mutate(undefined)}>Run {label} on {scope}</Button></div>
+      <ConfirmSpendDialog
+        open={quote != null}
+        tier="billable"
+        title={`Run ${label} on ${quote?.estimated_records ?? scope}${quote?.estimated_records != null ? " rows" : ""}`}
+        description={short ? `Not enough credits: you need ${quote?.required_credits} and have ${quote?.available_credits}. ${quote?.message ?? ""}` : (quote?.message ?? "The price is the most this run can charge. Rows that already have a value are skipped.")}
+        estimatedCredits={quote?.required_credits}
+        affected={quote?.estimated_records}
+        confirmLabel={short ? "Not enough credits" : "Start run"}
+        confirming={start.loading}
+        onConfirm={() => { if (quote && !short) void start.mutate(quote); }}
+        onCancel={() => setQuote(null)}
+      />
+    </div>
+  );
+}