whale-code 6.4.0

package/dist/server/validation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Zod input validation for server tool dispatch.
+ *
+ * Only mutation actions are validated — reads (find, get, list, summary, etc.)
+ * pass through without schema checks. This prevents malformed AI tool calls
+ * from crashing handlers with TypeErrors on unchecked `as` casts.
+ */
+export type ValidationResult = {
+    valid: true;
+    data: Record<string, unknown>;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validate tool args before dispatch to handler.
+ *
+ * Returns `{ valid: true, data }` with parsed (coerced) data on success,
+ * or `{ valid: false, error }` with a human-readable message on failure.
+ *
+ * If no schema is registered for the (tool, action) pair, returns passthrough
+ * with `{ valid: true, data: args }` — no validation, no blocking.
+ */
+export declare function validateToolArgs(toolName: string, args: Record<string, unknown>): ValidationResult;

package/dist/server/validation.js

@@ -0,0 +1,301 @@
+/**
+ * Zod input validation for server tool dispatch.
+ *
+ * Only mutation actions are validated — reads (find, get, list, summary, etc.)
+ * pass through without schema checks. This prevents malformed AI tool calls
+ * from crashing handlers with TypeErrors on unchecked `as` casts.
+ */
+import { z } from "zod";
+// ============================================================================
+// SHARED PRIMITIVES
+// ============================================================================
+const uuid = z.string().uuid();
+const positiveNumber = z.number().positive();
+const nonNegativeNumber = z.number().min(0);
+// ============================================================================
+// INVENTORY MUTATIONS
+// ============================================================================
+const inventoryAdjustSchema = z.object({
+    action: z.literal("adjust"),
+    product_id: uuid,
+    location_id: uuid,
+    adjustment: z.number(),
+    reason: z.string().optional(),
+});
+const inventorySetSchema = z.object({
+    action: z.literal("set"),
+    product_id: uuid,
+    location_id: uuid,
+    quantity: nonNegativeNumber,
+});
+const inventoryTransferSchema = z.object({
+    action: z.literal("transfer"),
+    product_id: uuid,
+    from_location_id: uuid,
+    to_location_id: uuid,
+    quantity: positiveNumber,
+});
+const inventoryBulkSetSchema = z.object({
+    action: z.literal("bulk_set"),
+    items: z.array(z.object({
+        product_id: uuid,
+        location_id: uuid,
+        quantity: nonNegativeNumber,
+    })).min(1),
+});
+const inventoryBulkAdjustSchema = z.object({
+    action: z.literal("bulk_adjust"),
+    items: z.array(z.object({
+        product_id: uuid,
+        location_id: uuid,
+        adjustment: z.number(),
+    })).min(1),
+});
+const inventoryBulkClearSchema = z.object({
+    action: z.literal("bulk_clear"),
+    location_id: uuid,
+});
+// ============================================================================
+// SUPPLY CHAIN — PURCHASE ORDERS
+// ============================================================================
+const poCreateSchema = z.object({
+    action: z.literal("create"),
+    supplier_id: uuid,
+    location_id: uuid,
+    items: z.array(z.object({
+        product_id: uuid,
+        quantity: positiveNumber,
+        unit_price: nonNegativeNumber.optional(),
+        unit_cost: nonNegativeNumber.optional(),
+    })).min(1).optional(),
+    notes: z.string().optional(),
+    expected_delivery_date: z.string().optional(),
+    po_type: z.string().optional(),
+});
+const poAddItemsSchema = z.object({
+    action: z.literal("add_items"),
+    purchase_order_id: uuid,
+    items: z.array(z.object({
+        product_id: uuid,
+        quantity: positiveNumber,
+        unit_price: nonNegativeNumber.optional(),
+        unit_cost: nonNegativeNumber.optional(),
+    })).min(1),
+});
+const poApproveSchema = z.object({
+    action: z.literal("approve"),
+    purchase_order_id: uuid,
+});
+const poReceiveSchema = z.object({
+    action: z.literal("receive"),
+    purchase_order_id: uuid,
+});
+const poCancelSchema = z.object({
+    action: z.literal("cancel"),
+    purchase_order_id: uuid,
+});
+// ============================================================================
+// SUPPLY CHAIN — TRANSFERS
+// ============================================================================
+const transferCreateSchema = z.object({
+    action: z.literal("create"),
+    from_location_id: uuid.optional(),
+    source_location_id: uuid.optional(),
+    to_location_id: uuid.optional(),
+    destination_location_id: uuid.optional(),
+    items: z.array(z.object({
+        product_id: uuid,
+        quantity: positiveNumber,
+    })).min(1).optional(),
+    notes: z.string().optional(),
+}).refine((d) => d.from_location_id || d.source_location_id, { message: "from_location_id or source_location_id is required", path: ["from_location_id"] }).refine((d) => d.to_location_id || d.destination_location_id, { message: "to_location_id or destination_location_id is required", path: ["to_location_id"] });
+const transferApproveSchema = z.object({
+    action: z.literal("approve"),
+    transfer_id: uuid,
+});
+const transferShipSchema = z.object({
+    action: z.union([z.literal("ship"), z.literal("mark_in_transit")]),
+    transfer_id: uuid,
+});
+const transferReceiveSchema = z.object({
+    action: z.union([z.literal("receive"), z.literal("complete")]),
+    transfer_id: uuid,
+});
+const transferCancelSchema = z.object({
+    action: z.literal("cancel"),
+    transfer_id: uuid,
+});
+// ============================================================================
+// CUSTOMERS
+// ============================================================================
+const customerCreateSchema = z.object({
+    action: z.literal("create"),
+    first_name: z.string().min(1),
+    last_name: z.string().min(1),
+    email: z.string().email().optional(),
+    phone: z.string().optional(),
+    date_of_birth: z.string().optional(),
+    email_consent: z.boolean().optional(),
+    sms_consent: z.boolean().optional(),
+    street_address: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional(),
+    postal_code: z.string().optional(),
+    drivers_license_number: z.string().optional(),
+    medical_card_number: z.string().optional(),
+    medical_card_expiry: z.string().optional(),
+});
+const customerUpdateSchema = z.object({
+    action: z.literal("update"),
+    customer_id: uuid,
+    first_name: z.string().min(1).optional(),
+    last_name: z.string().min(1).optional(),
+    email: z.string().email().optional(),
+    phone: z.string().optional(),
+    date_of_birth: z.string().optional(),
+    status: z.string().optional(),
+    email_consent: z.boolean().optional(),
+    sms_consent: z.boolean().optional(),
+    push_consent: z.boolean().optional(),
+    loyalty_points: z.number().optional(),
+    loyalty_tier: z.string().optional(),
+    street_address: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional(),
+    postal_code: z.string().optional(),
+    drivers_license_number: z.string().optional(),
+    id_verified: z.boolean().optional(),
+    medical_card_number: z.string().optional(),
+    medical_card_expiry: z.string().optional(),
+    is_wholesale_approved: z.boolean().optional(),
+    wholesale_tier: z.string().optional(),
+    wholesale_business_name: z.string().optional(),
+    wholesale_license_number: z.string().optional(),
+    wholesale_tax_id: z.string().optional(),
+});
+const customerMergeSchema = z.object({
+    action: z.literal("merge"),
+    primary_customer_id: uuid,
+    secondary_customer_id: uuid,
+});
+const productMergeSchema = z.object({
+    action: z.literal("merge"),
+    primary_product_id: uuid,
+    secondary_product_id: uuid,
+});
+const productSchemas = {
+    merge: productMergeSchema,
+};
+const inventorySchemas = {
+    adjust: inventoryAdjustSchema,
+    set: inventorySetSchema,
+    transfer: inventoryTransferSchema,
+    bulk_set: inventoryBulkSetSchema,
+    bulk_adjust: inventoryBulkAdjustSchema,
+    bulk_clear: inventoryBulkClearSchema,
+};
+const purchaseOrderSchemas = {
+    create: poCreateSchema,
+    add_items: poAddItemsSchema,
+    approve: poApproveSchema,
+    mark_ordered: poApproveSchema,
+    receive: poReceiveSchema,
+    cancel: poCancelSchema,
+};
+const transferSchemas = {
+    create: transferCreateSchema,
+    approve: transferApproveSchema,
+    ship: transferShipSchema,
+    mark_in_transit: transferShipSchema,
+    receive: transferReceiveSchema,
+    complete: transferReceiveSchema,
+    cancel: transferCancelSchema,
+};
+const customerSchemas = {
+    create: customerCreateSchema,
+    update: customerUpdateSchema,
+    merge: customerMergeSchema,
+};
+/**
+ * Top-level registry keyed by tool name.
+ * Only tools with mutation actions are listed.
+ * Read-only tools (analytics, orders.find, etc.) are intentionally absent — passthrough.
+ */
+const toolSchemaRegistry = {
+    products: productSchemas,
+    inventory: inventorySchemas,
+    purchase_orders: purchaseOrderSchemas,
+    transfers: transferSchemas,
+    customers: customerSchemas,
+};
+// ============================================================================
+// SUPPLY_CHAIN META-TOOL RESOLUTION
+// ============================================================================
+/**
+ * The "supply_chain" tool dispatches by action prefix:
+ *   po_create → purchase_orders / create
+ *   transfer_create → transfers / create
+ *
+ * This helper resolves supply_chain actions to the underlying tool + action.
+ */
+function resolveSupplyChainAction(action) {
+    if (action.startsWith("po_"))
+        return { tool: "purchase_orders", action: action.slice(3) };
+    if (action.startsWith("transfer_"))
+        return { tool: "transfers", action: action.slice(9) };
+    return null;
+}
+/**
+ * Validate tool args before dispatch to handler.
+ *
+ * Returns `{ valid: true, data }` with parsed (coerced) data on success,
+ * or `{ valid: false, error }` with a human-readable message on failure.
+ *
+ * If no schema is registered for the (tool, action) pair, returns passthrough
+ * with `{ valid: true, data: args }` — no validation, no blocking.
+ */
+export function validateToolArgs(toolName, args) {
+    const action = args.action;
+    if (!action) {
+        // No action param = passthrough (some tools don't use action)
+        return { valid: true, data: args };
+    }
+    let schemaMap;
+    if (toolName === "supply_chain") {
+        const resolved = resolveSupplyChainAction(action);
+        if (resolved) {
+            schemaMap = toolSchemaRegistry[resolved.tool];
+            // Look up by the resolved action (e.g. "create" not "po_create")
+            const schema = schemaMap?.[resolved.action];
+            if (!schema)
+                return { valid: true, data: args };
+            // For supply_chain, we validate using the inner action name
+            // Rebuild args with the inner action for schema parsing
+            const innerArgs = { ...args, action: resolved.action };
+            return runSchema(schema, innerArgs, args);
+        }
+        // Unknown supply_chain action (e.g. find_suppliers) — passthrough
+        return { valid: true, data: args };
+    }
+    schemaMap = toolSchemaRegistry[toolName];
+    if (!schemaMap)
+        return { valid: true, data: args };
+    const schema = schemaMap[action];
+    if (!schema)
+        return { valid: true, data: args };
+    return runSchema(schema, args, args);
+}
+/**
+ * Parse args against schema. On success, merge parsed data back onto original
+ * args so extra fields (not in schema) are preserved for the handler.
+ */
+function runSchema(schema, parseTarget, originalArgs) {
+    const result = schema.safeParse(parseTarget);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`);
+        return { valid: false, error: `Validation failed: ${issues.join(", ")}` };
+    }
+    // Merge parsed data back with original args so extra passthrough fields survive
+    const parsed = result.data;
+    return { valid: true, data: { ...originalArgs, ...parsed } };
+}

package/dist/server/worker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * worker.ts — Standalone workflow worker process
+ *
+ * Phase 3.2: Separates workflow step execution from the HTTP server.
+ * Deploy as a separate Fly.io process group so long-running agent conversations
+ * on the web process don't compete with step execution.
+ *
+ * Both processes use claim_step_for_run RPC with FOR UPDATE SKIP LOCKED —
+ * no double-claiming even if both web + worker run simultaneously.
+ *
+ * Usage:
+ *   node dist/server/worker.js
+ *
+ * Fly.io config:
+ *   [processes]
+ *     web = "node dist/server/index.js"
+ *     worker = "node dist/server/worker.js"
+ */
+export {};

package/dist/server/worker.js

@@ -0,0 +1,201 @@
+/**
+ * worker.ts — Standalone workflow worker process
+ *
+ * Phase 3.2: Separates workflow step execution from the HTTP server.
+ * Deploy as a separate Fly.io process group so long-running agent conversations
+ * on the web process don't compete with step execution.
+ *
+ * Both processes use claim_step_for_run RPC with FOR UPDATE SKIP LOCKED —
+ * no double-claiming even if both web + worker run simultaneously.
+ *
+ * Usage:
+ *   node dist/server/worker.js
+ *
+ * Fly.io config:
+ *   [processes]
+ *     web = "node dist/server/index.js"
+ *     worker = "node dist/server/worker.js"
+ */
+import pg from "pg";
+import { createClient } from "@supabase/supabase-js";
+import { processWorkflowSteps, processWaitingSteps, initWorkerPool, shutdownPool, processScheduleTriggers, enforceWorkflowTimeouts, processEventTriggers, cleanupOrphanedSteps, processDlqRetries, setToolExecutor, } from "./handlers/workflows.js";
+import { executeTool, loadTools } from "./tool-router.js";
+import { createLogger } from "./lib/logger.js";
+const log = createLogger("worker");
+// ============================================================================
+// CONFIG
+// ============================================================================
+const SUPABASE_URL = process.env.SUPABASE_URL || "";
+const SUPABASE_SERVICE_ROLE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY || "";
+const DATABASE_URL = process.env.DATABASE_URL || "";
+const BASE_INTERVAL_MS = 15_000; // Safety net interval (NOTIFY is the fast path)
+const MAX_INTERVAL_MS = 60_000;
+if (!SUPABASE_URL || !SUPABASE_SERVICE_ROLE_KEY) {
+    log.fatal("SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are required");
+    process.exit(1);
+}
+// ============================================================================
+// SUPABASE CLIENT
+// ============================================================================
+const supabase = createClient(SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, {
+    auth: { persistSession: false, autoRefreshToken: false },
+});
+// ============================================================================
+// WORKER LOOP
+// ============================================================================
+let running = false;
+let notifyProcessing = false;
+let consecutiveErrors = 0;
+let currentInterval = BASE_INTERVAL_MS;
+let intervalHandle;
+async function workerTick() {
+    if (running || notifyProcessing)
+        return;
+    running = true;
+    try {
+        const [stepResult, waitingResolved] = await Promise.all([
+            processWorkflowSteps(supabase, 10),
+            processWaitingSteps(supabase),
+            Promise.resolve(supabase.rpc("expire_pending_waitpoints")).then(() => { }).catch((e) => log.warn({ err: e.message }, "expire_pending_waitpoints failed")),
+        ]);
+        const [scheduled, timedOut, eventsProcessed, orphansCleaned, dlqRetried] = await Promise.all([
+            processScheduleTriggers(supabase).catch((e) => { log.warn({ err: e.message }, "schedule trigger failed"); return 0; }),
+            enforceWorkflowTimeouts(supabase).catch((e) => { log.warn({ err: e.message }, "timeout enforcement failed"); return 0; }),
+            processEventTriggers(supabase).catch((e) => { log.warn({ err: e.message }, "event trigger failed"); return 0; }),
+            cleanupOrphanedSteps(supabase).catch((e) => { log.warn({ err: e.message }, "orphan cleanup failed"); return 0; }),
+            processDlqRetries(supabase).catch((e) => { log.warn({ err: e.message }, "DLQ retry failed"); return 0; }),
+        ]);
+        if (stepResult.processed > 0 || waitingResolved > 0 || scheduled > 0 || timedOut > 0 || eventsProcessed > 0 || orphansCleaned > 0 || dlqRetried > 0) {
+            log.info({
+                processed: stepResult.processed, errors: stepResult.errors,
+                reclaimed: stepResult.reclaimed || 0, waiting: waitingResolved,
+                scheduled, timedOut, events: eventsProcessed, orphans: orphansCleaned, dlqRetries: dlqRetried,
+            }, "worker tick");
+        }
+        // Reset backoff on success
+        if (consecutiveErrors > 0) {
+            consecutiveErrors = 0;
+            if (currentInterval !== BASE_INTERVAL_MS) {
+                currentInterval = BASE_INTERVAL_MS;
+                clearInterval(intervalHandle);
+                intervalHandle = setInterval(workerTick, currentInterval);
+                log.info({ intervalMs: currentInterval }, "interval reset after recovery");
+            }
+        }
+    }
+    catch (err) {
+        consecutiveErrors++;
+        log.error({ err: err.message, consecutiveErrors }, "worker error");
+        if (consecutiveErrors >= 3) {
+            const newInterval = Math.min(BASE_INTERVAL_MS * Math.pow(2, consecutiveErrors - 2), MAX_INTERVAL_MS);
+            if (newInterval !== currentInterval) {
+                currentInterval = newInterval;
+                clearInterval(intervalHandle);
+                intervalHandle = setInterval(workerTick, currentInterval);
+                log.warn({ intervalMs: currentInterval, consecutiveErrors }, "interval increased due to errors");
+            }
+        }
+    }
+    finally {
+        running = false;
+    }
+}
+// ============================================================================
+// NOTIFY LISTENER (fast path)
+// ============================================================================
+let pgClient = null;
+async function setupPgListen() {
+    if (!DATABASE_URL) {
+        log.warn("no DATABASE_URL — NOTIFY-driven execution disabled, polling only");
+        return;
+    }
+    try {
+        const cleanUrl = DATABASE_URL.replace(/[?&]sslmode=[^&]*/g, "").replace(/\?$/, "");
+        pgClient = new pg.Client({ connectionString: cleanUrl, ssl: { rejectUnauthorized: false } });
+        await pgClient.connect();
+        await pgClient.query("LISTEN workflow_step_pending");
+        // P1 FIX: Debounce NOTIFY to prevent thundering herd when many steps
+        // become pending simultaneously (e.g., for_each expansion).
+        let notifyTimer = null;
+        let notifyPending = 0;
+        pgClient.on("notification", (msg) => {
+            if (msg.channel === "workflow_step_pending") {
+                notifyPending++;
+                if (!notifyTimer) {
+                    notifyTimer = setTimeout(() => {
+                        const batch = Math.min(notifyPending, 10);
+                        notifyPending = 0;
+                        notifyTimer = null;
+                        if (notifyProcessing || running)
+                            return; // Skip if already processing
+                        notifyProcessing = true;
+                        processWorkflowSteps(supabase, batch)
+                            .catch((err) => {
+                            log.error({ err: err.message }, "NOTIFY step processing failed");
+                        })
+                            .finally(() => { notifyProcessing = false; });
+                    }, 50); // 50ms debounce — still fast, but batches concurrent notifications
+                }
+            }
+        });
+        pgClient.on("error", (err) => {
+            log.error({ err: err.message }, "pg-listen connection error");
+            pgClient = null;
+            setTimeout(() => setupPgListen(), 5000);
+        });
+        log.info("pg LISTEN active on workflow_step_pending");
+    }
+    catch (err) {
+        log.error({ err: err.message }, "pg-listen failed");
+        pgClient = null;
+        setTimeout(() => setupPgListen(), 5000);
+    }
+}
+// ============================================================================
+// STARTUP + SHUTDOWN
+// ============================================================================
+async function start() {
+    log.info("starting workflow worker process");
+    // Wire tool executor for workflow steps that need tool calls
+    setToolExecutor((sb, toolName, args, storeId, traceId) => executeTool(sb, toolName, args, storeId, traceId));
+    // Load tools registry
+    await loadTools(supabase);
+    // Initialize code worker pool
+    try {
+        initWorkerPool();
+        log.info("worker pool initialized");
+    }
+    catch (err) {
+        log.error({ err: err.message }, "worker pool init failed");
+    }
+    // Start NOTIFY listener
+    await setupPgListen();
+    // Start polling loop (safety net)
+    intervalHandle = setInterval(workerTick, currentInterval);
+    log.info({ intervalMs: currentInterval }, "worker loop started");
+    // Run first tick immediately
+    workerTick();
+}
+function shutdown(signal) {
+    log.info({ signal }, "worker shutting down");
+    clearInterval(intervalHandle);
+    try {
+        shutdownPool();
+    }
+    catch { /* ignore */ }
+    if (pgClient) {
+        pgClient.end().catch(() => { });
+        pgClient = null;
+    }
+    // Give in-flight work 10s to finish
+    setTimeout(() => process.exit(0), 10_000).unref();
+}
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("unhandledRejection", (reason) => {
+    log.error({ err: reason }, "unhandled rejection in worker");
+});
+start().catch((err) => {
+    log.fatal({ err: err.message }, "worker failed to start");
+    process.exit(1);
+});

package/dist/setup.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * SwagManager MCP — Interactive Setup
+ *
+ * Detects installed MCP-compatible CLIs and writes config for each.
+ * Usage: npx swagmanager-mcp setup
+ */
+export declare function runSetup(): Promise<void>;