stagent 0.9.5 → 0.10.0

package/src/lib/chat/engine.ts

@@ -21,6 +21,9 @@ import {
   updateConversation,
 } from "@/lib/data/chat";
 import { buildChatContext, type MentionReference } from "./context-builder";
+import { finalizeStreamingMessage } from "./reconcile";
+import { recordTermination } from "./stream-telemetry";
+import { registerChatStream, unregisterChatStream } from "./active-streams";
 import {
   detectEntities,
   extractToolResultEntities,
@@ -250,6 +253,8 @@ export async function* sendMessage(
     status: "streaming",
   });
 
+  registerChatStream(conversationId);
+
   // Create side channel for canUseTool → SSE bridge communication
   const sideChannel = createSideChannel(conversationId);
 
@@ -636,6 +641,13 @@ export async function* sendMessage(
       finishedAt: new Date(),
     });
 
+    recordTermination({
+      reason: "stream.completed",
+      conversationId,
+      messageId: assistantMsg.id,
+      durationMs: Date.now() - startedAt.getTime(),
+    });
+
     yield {
       type: "done",
       messageId: assistantMsg.id,
@@ -647,7 +659,27 @@ export async function* sendMessage(
 
     // Enrich the error with stderr diagnostics when available
     const stderrTail = stderrChunks.join("").trim();
-    const errorMessage = diagnoseProcessError(rawMessage, stderrTail);
+    const rawErrorMessage = diagnoseProcessError(rawMessage, stderrTail);
+    // Truncate at 4KB to prevent multi-MB stderr dumps bloating chat_messages
+    const errorMessage =
+      rawErrorMessage.length > 4096
+        ? rawErrorMessage.slice(0, 4096) + "... (truncated)"
+        : rawErrorMessage;
+
+    // Telemetry: record BEFORE the yield below. If this code is reached
+    // via iterator abandonment (consumer broke the for-await and the
+    // generator's own yield throws GeneratorReturn), control would skip
+    // past any post-yield statement. Recording up front guarantees the
+    // event lands in the ring buffer regardless of whether the yield
+    // completes or aborts. Matches the same invariant we rely on for
+    // the success-path recordTermination before the done yield.
+    recordTermination({
+      reason: signal?.aborted ? "stream.aborted.signal" : "stream.finalized.error",
+      conversationId,
+      messageId: assistantMsg.id,
+      durationMs: Date.now() - startedAt.getTime(),
+      error: errorMessage.slice(0, 500),
+    });
 
     if (fullText && fullText.length > 50) {
       // Substantial content was already streamed — complete gracefully with warning
@@ -674,10 +706,14 @@ export async function* sendMessage(
 
       yield { type: "done", messageId: assistantMsg.id, quickAccess: [] };
     } else {
-      // No meaningful content — show as error
+      // No meaningful content — show as error. Fallback chain ensures we
+      // never write an empty string even if both fullText and errorMessage
+      // happen to be blank.
       await updateMessageContent(
         assistantMsg.id,
-        fullText || errorMessage
+        fullText ||
+          errorMessage ||
+          "(Response failed — no error detail available.)"
       );
       await updateMessageStatus(assistantMsg.id, "error");
 
@@ -698,6 +734,17 @@ export async function* sendMessage(
       yield { type: "error", message: errorMessage };
     }
   } finally {
+    // Safety net: guarantee the placeholder row never remains in
+    // status='streaming' after the generator exits. Catches code paths that
+    // bypass the catch block — most notably async iterator abandonment, where
+    // a consumer `break`ing out of a `for await` loop triggers the generator's
+    // return() method and jumps straight here, skipping catch entirely.
+    try {
+      await finalizeStreamingMessage(assistantMsg.id, fullText);
+    } catch (finalizeErr) {
+      console.error("[chat] finalize safety net failed:", finalizeErr);
+    }
+    unregisterChatStream(conversationId);
     cleanupConversation(conversationId);
   }
 }

package/src/lib/chat/reconcile.ts

@@ -0,0 +1,117 @@
+import { db } from "@/lib/db";
+import { chatMessages } from "@/lib/db/schema";
+import { and, eq, lt } from "drizzle-orm";
+import { recordTermination } from "./stream-telemetry";
+
+const INTERRUPTED_FALLBACK =
+  "(Response interrupted. Please try again.)";
+
+const ORPHAN_FALLBACK =
+  "(Interrupted — this response was not completed. Please retry.)";
+
+/**
+ * Safety-net finalizer called from the chat engine's top-level `finally` block.
+ *
+ * Guarantees the invariant: no `chat_messages` row remains in
+ * `status='streaming'` after `sendMessage()` returns or throws. Catches every
+ * code path the engine's own `catch` block misses — most notably async
+ * iterator abandonment, where a consumer `break`ing out of a `for await` loop
+ * triggers the generator's `return()` method and jumps straight to `finally`,
+ * skipping `catch` entirely.
+ *
+ * No-op if the message is already in a terminal state. Idempotent.
+ *
+ * When the salvage path actually fires (row was still in streaming → now
+ * updated to complete/error), records a `stream.abandoned` telemetry event
+ * so maintainers can see that the engine's own happy/catch paths both
+ * missed the termination. A non-zero count here signals a real gap that
+ * may warrant investigation — e.g., the dev HMR interrupting a stream,
+ * or a consumer break pattern that bypasses the telemetry in both primary
+ * code paths.
+ */
+export async function finalizeStreamingMessage(
+  messageId: string,
+  fullText: string,
+): Promise<void> {
+  const current = db
+    .select()
+    .from(chatMessages)
+    .where(eq(chatMessages.id, messageId))
+    .get();
+
+  if (!current || current.status !== "streaming") {
+    return;
+  }
+
+  const hasContent = fullText && fullText.trim().length > 0;
+  const salvage = hasContent ? fullText : INTERRUPTED_FALLBACK;
+  const nextStatus = hasContent && fullText.length > 50 ? "complete" : "error";
+
+  db.update(chatMessages)
+    .set({ status: nextStatus, content: salvage })
+    .where(eq(chatMessages.id, messageId))
+    .run();
+
+  // Telemetry: this code path means neither stream.completed nor the
+  // engine's catch-block recordTermination fired. Capture the gap so
+  // the diagnostics endpoint can surface it.
+  recordTermination({
+    reason: "stream.abandoned",
+    conversationId: current.conversationId ?? null,
+    messageId,
+    durationMs: current.createdAt
+      ? Date.now() - new Date(current.createdAt).getTime()
+      : null,
+    error: hasContent ? undefined : "no content streamed before abandonment",
+  });
+}
+
+/**
+ * Sweep orphaned chat assistant messages left in `status='streaming'` past a
+ * reasonable cutoff. These rows are produced when the chat engine's finally
+ * block is bypassed (process crash, iterator abandonment under heavy load,
+ * HTTP disconnect before update commits, etc.).
+ *
+ * Safe to call idempotently at chat page load. Uses a 10-minute cutoff — far
+ * longer than any legitimate in-flight streaming response — so in-flight rows
+ * are never clobbered.
+ *
+ * Returns the number of rows swept. Never throws.
+ */
+export async function reconcileStreamingMessages(): Promise<number> {
+  const cutoff = new Date(Date.now() - 10 * 60 * 1000);
+  const orphans = db
+    .select()
+    .from(chatMessages)
+    .where(
+      and(
+        eq(chatMessages.status, "streaming"),
+        lt(chatMessages.createdAt, cutoff),
+      ),
+    )
+    .all();
+
+  for (const row of orphans) {
+    const salvage =
+      row.content && row.content.length > 0 ? row.content : ORPHAN_FALLBACK;
+    db.update(chatMessages)
+      .set({ status: "error", content: salvage })
+      .where(eq(chatMessages.id, row.id))
+      .run();
+
+    // Telemetry: record the orphan sweep so diagnostics can tell how often
+    // the safety net actually fires vs. how often the normal finalize path
+    // catches everything first. If this code ever logs a row, the engine's
+    // `finally` block missed it.
+    recordTermination({
+      reason: "stream.reconciled.stale",
+      conversationId: row.conversationId ?? null,
+      messageId: row.id,
+      durationMs: row.createdAt
+        ? Date.now() - new Date(row.createdAt).getTime()
+        : null,
+    });
+  }
+
+  return orphans.length;
+}

package/src/lib/chat/stagent-tools.ts

@@ -22,6 +22,7 @@ import { handoffTools } from "./tools/handoff-tools";
 import { tableTools } from "./tools/table-tools";
 import { runtimeTools } from "./tools/runtime-tools";
 
+
 // ── Tool server types ────────────────────────────────────────────────
 
 export interface ProviderToolKit {

package/src/lib/chat/stream-telemetry.ts

@@ -0,0 +1,132 @@
+/**
+ * Chat stream termination telemetry.
+ *
+ * Lightweight, in-memory ring buffer that records how SSE chat streams
+ * terminate. Added in response to a sibling-repo bug report claiming
+ * conversations refresh mid-stream — the proposed root cause (Next.js dev
+ * HMR remounting ChatShell) is already mitigated in this repo, so rather
+ * than port a speculative fix, we instrument the termination boundaries
+ * and let real data decide whether a resume protocol is worth building.
+ *
+ * Six server-side reason codes:
+ *   - stream.completed        — normal end-of-generator (success path)
+ *   - stream.aborted.signal   — req.signal fired, engine catch block entered
+ *   - stream.aborted.client   — ReadableStream cancel callback fired
+ *   - stream.finalized.error  — non-abort exception in engine catch block
+ *   - stream.abandoned        — generator return() called by consumer
+ *                               (finally ran but catch was skipped). Covers
+ *                               iterator abandonment — the case where the
+ *                               route's for-await breaks out gracefully and
+ *                               the engine's own happy/catch paths are both
+ *                               bypassed. Recorded from finalizeStreamingMessage
+ *                               when it actually performs a salvage update.
+ *   - stream.reconciled.stale — reconcileStreamingMessages swept an orphan
+ *                               at chat page load (10-min cutoff)
+ *
+ * Three client-side reason codes (logged via console.info with a stable
+ * prefix so tests and grep can find them):
+ *   - client.stream.done        — reader.read() returned done: true
+ *   - client.stream.user-abort  — user clicked Stop / AbortController fired
+ *   - client.stream.reader-error — reader.read() or decode threw
+ *
+ * As of the `chat-session-persistence-provider` feature, the SSE reader
+ * loop runs inside `ChatSessionProvider` (rendered from the root layout),
+ * not inside the route-scoped `ChatShell`. Sidebar navigation no longer
+ * tears down the reader loop, so "client.stream.user-abort" should only
+ * fire when the user explicitly clicks Stop. If it starts firing on plain
+ * view switches again, something has regressed the provider hoisting.
+ * HMR in dev can still reset the provider module — that is expected.
+ *
+ * Read via the dev-only `GET /api/diagnostics/chat-streams` endpoint.
+ * The buffer is process-local — a server restart clears it, which is fine
+ * for dev diagnostics and avoids adding a persistence layer that would
+ * itself need testing.
+ */
+
+export type TerminationReason =
+  | "stream.completed"
+  | "stream.aborted.signal"
+  | "stream.aborted.client"
+  | "stream.finalized.error"
+  | "stream.abandoned"
+  | "stream.reconciled.stale";
+
+export interface TerminationEvent {
+  reason: TerminationReason;
+  conversationId: string | null;
+  messageId: string | null;
+  durationMs: number | null;
+  error?: string;
+  timestamp: number;
+}
+
+/** Ring buffer capacity — ~500 events is ~50KB, negligible for a dev tool. */
+const CAPACITY = 500;
+
+/**
+ * Module-level circular buffer. Newer events overwrite older ones once
+ * capacity is reached. Writes are O(1), reads copy-out in order.
+ *
+ * Next.js dev HMR may re-import this module and reset the buffer — that
+ * is expected behavior and not a bug. The buffer is intentionally not
+ * persisted; its purpose is "what happened in the last N minutes of this
+ * process", not forensic logging.
+ */
+const buffer: TerminationEvent[] = new Array(CAPACITY);
+let writeIndex = 0;
+let writeCount = 0;
+
+export function recordTermination(event: Omit<TerminationEvent, "timestamp">): void {
+  const full: TerminationEvent = { ...event, timestamp: Date.now() };
+  buffer[writeIndex] = full;
+  writeIndex = (writeIndex + 1) % CAPACITY;
+  writeCount++;
+}
+
+/**
+ * Return all recorded events in chronological order (oldest → newest).
+ * Copies out of the ring buffer so callers can't mutate internal state.
+ */
+export function readTerminations(): TerminationEvent[] {
+  const count = Math.min(writeCount, CAPACITY);
+  if (count === 0) return [];
+  const result: TerminationEvent[] = new Array(count);
+  // Start at the oldest slot. When the buffer is full, the oldest is at
+  // writeIndex (the next slot to be overwritten). When not full, it's at 0.
+  const start = writeCount > CAPACITY ? writeIndex : 0;
+  for (let i = 0; i < count; i++) {
+    result[i] = buffer[(start + i) % CAPACITY]!;
+  }
+  return result;
+}
+
+/**
+ * Aggregate event counts by reason code for the last `windowMs` milliseconds.
+ * Pass 0 or omit to get counts across the entire buffer.
+ */
+export function countTerminations(windowMs = 0): Record<TerminationReason, number> {
+  const counts: Record<TerminationReason, number> = {
+    "stream.completed": 0,
+    "stream.aborted.signal": 0,
+    "stream.aborted.client": 0,
+    "stream.finalized.error": 0,
+    "stream.abandoned": 0,
+    "stream.reconciled.stale": 0,
+  };
+  const cutoff = windowMs > 0 ? Date.now() - windowMs : 0;
+  for (const event of readTerminations()) {
+    if (event.timestamp >= cutoff) {
+      counts[event.reason]++;
+    }
+  }
+  return counts;
+}
+
+/**
+ * Reset the buffer. Intended for tests — do not call in production code.
+ */
+export function __resetForTesting(): void {
+  for (let i = 0; i < CAPACITY; i++) buffer[i] = undefined as never;
+  writeIndex = 0;
+  writeCount = 0;
+}

package/src/lib/chat/suggested-prompts.ts

@@ -1,5 +1,5 @@
 import { db } from "@/lib/db";
-import { projects, tasks, workflows, schedules } from "@/lib/db/schema";
+import { projects, tasks, schedules, userTables } from "@/lib/db/schema";
 import { eq, desc } from "drizzle-orm";
 import type { PromptCategory, SuggestedPrompt } from "./types";
 
@@ -40,6 +40,25 @@ async function buildExplorePrompts(): Promise<SuggestedPrompt[]> {
     });
   }
 
+  // Context-sensitive suggestion: if any user tables exist, surface an
+  // enrichment prompt for the most recently updated one. Users commonly have
+  // tables with empty cells waiting to be enriched; even without a column-level
+  // scan, pointing the chat LLM at enrich_table makes the bulk-row fan-out
+  // capability discoverable via suggested prompts rather than only via direct
+  // intent.
+  const recentTable = await db
+    .select({ id: userTables.id, name: userTables.name })
+    .from(userTables)
+    .orderBy(desc(userTables.updatedAt))
+    .limit(1);
+
+  if (recentTable.length > 0) {
+    prompts.push({
+      label: `Enrich "${truncate(recentTable[0].name, 28)}" rows`,
+      prompt: `I'd like to enrich rows in the "${recentTable[0].name}" table (id: ${recentTable[0].id}) using an agent. Ask me which column is missing data, what prompt template to use (reference row fields naturally), and which agent profile is best. Then use enrich_table to kick off the loop workflow.`,
+    });
+  }
+
   // Fill with static fallbacks
   const fallbacks: SuggestedPrompt[] = [
     {
@@ -76,6 +95,14 @@ function buildCreatePrompts(): SuggestedPrompt[] {
       label: "Set up a multi-step workflow",
       prompt: "Help me design a multi-step workflow. I want to define a sequence of tasks with dependencies. Ask me what the workflow should accomplish and suggest a structure.",
     },
+    {
+      label: "Design a drip sequence",
+      prompt: "Help me build a drip workflow with delay steps between sends. Ask me about the cadence (e.g. 3 days between touches), the number of touches, and the content goal for each step. Then use create_workflow with a sequence pattern, interleaving task steps and delay steps (delayDuration format: Nm|Nh|Nd|Nw, bounds 1m..30d). Do not create separate workflows or schedules — a single workflow with inline delay steps is the idiomatic pattern.",
+    },
+    {
+      label: "Enrich a table with an agent",
+      prompt: "I have a table with missing data that I want an agent to fill in. Help me use enrich_table to fan out rows to the agent. Ask me which table, which column is missing, what prompt template to use (the row is available as JSON context — tell the agent to read the relevant fields and return just the value, or NOT_FOUND if none can be determined), and which agent profile is best (sales-researcher, content-creator, data-analyst, etc.). Do not hand-roll a loop workflow — enrich_table already handles the loop, row binding, postAction writeback, and idempotent skip.",
+    },
     {
       label: "Draft a document outline",
       prompt: "Help me create a structured document outline. Ask me about the topic, audience, and purpose, then suggest sections and key points to cover.",

package/src/lib/chat/system-prompt.ts

@@ -21,11 +21,12 @@ export const STAGENT_SYSTEM_PROMPT = `You are Stagent, an AI workspace assistant
 
 ### Workflows
 - list_workflows: List all workflows
-- create_workflow: Create a multi-step workflow with a definition
+- create_workflow: Create a multi-step workflow with a definition. Steps can be task steps (profile + prompt) or **delay steps** (delayDuration like '3d', '2h', '30m', '1w') that pause the workflow before the next step. Delay steps enable time-distributed sequences.
 - get_workflow: Get workflow details and definition
 - update_workflow: Update a draft workflow
 - delete_workflow: Delete a workflow and its children [requires approval]
 - execute_workflow: Start workflow execution [requires approval]
+- resume_workflow: Resume a paused (delayed) workflow immediately instead of waiting for its scheduled resume time [requires approval]
 - get_workflow_status: Get current execution status with step progress
 - find_related_documents: Search the project document pool for documents to attach as workflow context
 
@@ -58,9 +59,30 @@ export const STAGENT_SYSTEM_PROMPT = `You are Stagent, an AI workspace assistant
 - get_usage_summary: Get token and cost statistics over a time period
 - get_settings: Read current configuration (auth method, budgets, runtime)
 
+### Tables
+Structured user data lives in Stagent tables (separate from Stagent's own internal records). Every table tool takes a tableId; use list_tables or search_table to find them first.
+- list_tables: List all user tables in a project
+- get_table_schema: Get a table's columns, types, and metadata
+- query_table: Filter, sort, and paginate rows with operators (eq, neq, gt, gte, lt, lte, contains, starts_with, in, is_empty, is_not_empty)
+- search_table: Full-text search across row cell values
+- aggregate_table: Compute count/sum/avg/min/max over a column with optional group-by
+- add_rows: Insert one or more rows
+- update_row: Update a single row's cell values
+- delete_rows: Delete rows matching a filter [requires approval]
+- create_table: Create a new empty table with specified columns
+- import_document_as_table: Parse an uploaded document into a new table
+- export_table: Export rows as CSV/JSON
+- add_column / update_column / delete_column / reorder_columns: Schema edits
+- list_triggers / create_trigger / update_trigger / delete_trigger: Per-row trigger evaluation
+- get_table_history: Read change history for a table
+- save_as_template: Save a table's shape as a reusable template
+- **enrich_table**: Run an agent task for every row in a table matching a filter, writing results to a target column. Use for bulk research, classification, content generation, or any table-row fan-out pattern. Generates the optimal loop workflow, binds each row as context, skips already-populated rows for idempotency [requires approval]
+
 ## When to Use Which Tools
 - CRUD operations ("create a task", "list workflows", "update the schedule") → Use the appropriate Stagent tool
 - Execution ("run this task", "execute the workflow") → Use execute_task / execute_workflow
+- Time-distributed multi-step sequences ("send email, wait 3 days, follow up", "drip campaign", "onboarding flow") → Use create_workflow with delay steps in a sequence pattern. Do NOT create separate workflows and schedules for each touch — a single workflow with inline delay steps is the idiomatic pattern.
+- Bulk per-row operations ("research every contact", "classify all tickets", "enrich rows missing X", "for each row do Y") → Use enrich_table. Do NOT hand-roll a loop workflow for this — enrich_table already generates the optimal loop, handles row-data binding, wires up the postAction writeback, and skips already-populated rows for idempotency.
 - Approvals ("approve that", "allow it", "deny the request") → Use respond_notification
 - Monitoring ("what's pending?", "any approval requests?") → Use list_notifications
 - Usage ("how much have I spent?", "token usage this week") → Use get_usage_summary
@@ -82,6 +104,9 @@ Be proactive with tools. If the user asks about project status, use list_tasks t
 - If a project context is active, scope operations to it unless the user specifies otherwise.
 - Tools marked [requires approval] will prompt the user before executing.
 - For workflows, valid patterns are: sequence, parallel, checkpoint, planner-executor, swarm, loop.
+- **Delay steps** (sequence pattern only): a step with \`delayDuration\` (format: Nm|Nh|Nd|Nw, bounds 1m..30d) pauses the workflow between task steps. Format examples: "30m", "2h", "3d", "1w". Delay steps must have NO profile or prompt — they are pure waits. Use them for outreach sequences, drip campaigns, cooling periods, staged rollouts. A paused workflow resumes automatically when its scheduled time arrives, or immediately when the user clicks "Resume Now".
+- **enrich_table idempotency:** \`enrich_table\` skips rows where the target column already has a non-empty value. If the user wants to overwrite existing values, explain that force re-enrichment is not supported in v1 — they must manually clear the target column first (e.g. via update_row) before re-running.
+- **create_workflow dedup:** Before calling \`create_workflow\`, call \`list_workflows\` (filtered by the current project) to check whether a similar workflow already exists. If the user asks to "redesign", "redo", or "update" an existing workflow, call \`update_workflow\` on the matching row instead of creating a new one. \`create_workflow\` performs its own near-duplicate check and will return \`{status: "similar-found", matches: [...]}\` instead of inserting when it finds one — when that happens, surface the matches to the user and confirm intent. Only pass \`force: true\` to \`create_workflow\` when the user has explicitly confirmed they want a second workflow alongside a similar one (e.g., "v2", "alternate approach").
 - When a working directory is specified, always create files relative to it. Never assume the git root is the working directory — they may differ in worktree environments.
 
 ## Document Pool Awareness

package/src/lib/chat/tool-catalog.ts

@@ -11,7 +11,6 @@ import {
   Clock,
   Globe,
   Sun,
-  CheckCheck,
   Sparkles,
   Table2,
 } from "lucide-react";
@@ -171,11 +170,13 @@ const STAGENT_TOOLS: ToolCatalogEntry[] = [
   { name: "delete_trigger", description: "Delete a trigger", group: "Tables", paramHint: "tableId, triggerId" },
   { name: "get_table_history", description: "Get row change history for a table", group: "Tables", paramHint: "tableId, limit" },
   { name: "save_as_template", description: "Save a table as a reusable template", group: "Tables", paramHint: "tableId, name, category" },
+  { name: "enrich_table", description: "Bulk-enrich rows by running an agent task per row, writing results to a target column", group: "Tables", paramHint: "tableId, prompt, targetColumn, filter" },
 
   // ── Chat History ──
   { name: "list_conversations", description: "List recent chat conversations", group: "Chat", paramHint: "search, limit" },
   { name: "get_conversation_messages", description: "Get messages from a past conversation", group: "Chat", paramHint: "conversationId, limit" },
   { name: "search_messages", description: "Search across all conversations", group: "Chat", paramHint: "query" },
+
 ];
 
 const BROWSER_TOOLS: ToolCatalogEntry[] = [

package/src/lib/chat/tools/__tests__/enrich-table-tool.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const { mockCreateEnrichmentWorkflow } = vi.hoisted(() => ({
+  mockCreateEnrichmentWorkflow: vi.fn(),
+}));
+
+vi.mock("@/lib/tables/enrichment", () => ({
+  createEnrichmentWorkflow: mockCreateEnrichmentWorkflow,
+}));
+
+// Stub the rest of @/lib/data/tables so importing table-tools doesn't drag in DB.
+vi.mock("@/lib/data/tables", () => ({
+  listTables: vi.fn(),
+  getTable: vi.fn(),
+  createTable: vi.fn(),
+  updateTable: vi.fn(),
+  deleteTable: vi.fn(),
+  listRows: vi.fn(),
+  addRows: vi.fn(),
+  updateRow: vi.fn(),
+  deleteRows: vi.fn(),
+  listTemplates: vi.fn(),
+  cloneFromTemplate: vi.fn(),
+  addColumn: vi.fn(),
+  updateColumn: vi.fn(),
+  deleteColumn: vi.fn(),
+  reorderColumns: vi.fn(),
+}));
+
+vi.mock("@/lib/tables/history", () => ({ getTableHistory: vi.fn() }));
+vi.mock("@/lib/tables/import", () => ({
+  extractStructuredData: vi.fn(),
+  inferColumnTypes: vi.fn(),
+  importRows: vi.fn(),
+  createImportRecord: vi.fn(),
+}));
+
+import { tableTools } from "../table-tools";
+
+function findEnrichTool() {
+  const tools = tableTools({ projectId: "proj_test" });
+  const tool = tools.find((t) => t.name === "enrich_table");
+  if (!tool) throw new Error("enrich_table tool not registered");
+  return tool;
+}
+
+describe("enrich_table tool", () => {
+  beforeEach(() => {
+    mockCreateEnrichmentWorkflow.mockReset();
+  });
+
+  it("is registered in tableTools", () => {
+    const tools = tableTools({ projectId: "proj_test" });
+    const names = tools.map((t) => t.name);
+    expect(names).toContain("enrich_table");
+  });
+
+  it("delegates to createEnrichmentWorkflow with the supplied params", async () => {
+    mockCreateEnrichmentWorkflow.mockResolvedValueOnce({
+      workflowId: "wf_xyz",
+      rowCount: 4,
+    });
+
+    const tool = findEnrichTool();
+    const result = await tool.handler({
+      tableId: "tbl_contacts",
+      prompt: "Find LinkedIn for {{row.name}}",
+      targetColumn: "linkedin",
+      filter: { column: "linkedin", operator: "is_empty" },
+      agentProfile: "sales-researcher",
+    });
+
+    expect(mockCreateEnrichmentWorkflow).toHaveBeenCalledWith(
+      "tbl_contacts",
+      expect.objectContaining({
+        prompt: "Find LinkedIn for {{row.name}}",
+        targetColumn: "linkedin",
+        filter: { column: "linkedin", operator: "is_empty" },
+        agentProfile: "sales-researcher",
+      })
+    );
+
+    expect(result.isError).toBeFalsy();
+    const payload = JSON.parse(result.content[0].text) as {
+      workflowId: string;
+      rowCount: number;
+    };
+    expect(payload.workflowId).toBe("wf_xyz");
+    expect(payload.rowCount).toBe(4);
+  });
+
+  it("falls back to ctx.projectId when projectId is not supplied", async () => {
+    mockCreateEnrichmentWorkflow.mockResolvedValueOnce({
+      workflowId: "wf_a",
+      rowCount: 1,
+    });
+
+    const tool = findEnrichTool();
+    await tool.handler({
+      tableId: "tbl_x",
+      prompt: "x",
+      targetColumn: "linkedin",
+    });
+
+    const callArg = mockCreateEnrichmentWorkflow.mock.calls[0][1] as {
+      projectId?: string;
+    };
+    expect(callArg.projectId).toBe("proj_test");
+  });
+
+  it("returns an error result when createEnrichmentWorkflow throws", async () => {
+    mockCreateEnrichmentWorkflow.mockRejectedValueOnce(
+      new Error("Table tbl_missing not found")
+    );
+
+    const tool = findEnrichTool();
+    const result = await tool.handler({
+      tableId: "tbl_missing",
+      prompt: "x",
+      targetColumn: "linkedin",
+    });
+
+    expect(result.isError).toBe(true);
+    const payload = JSON.parse(result.content[0].text) as { error: string };
+    expect(payload.error).toContain("not found");
+  });
+});