whale-code 6.4.0

package/dist/server/lib/otel.d.ts

@@ -0,0 +1,38 @@
+/**
+ * lib/otel.ts — OpenTelemetry SDK setup for workflow engine observability
+ *
+ * Phase 3.3: Adds distributed tracing spans for step execution, tool calls, LLM calls.
+ * Exports to any OTLP-compatible collector (Jaeger, Grafana Tempo, Honeycomb, etc.)
+ *
+ * Configuration:
+ *   OTEL_EXPORTER_OTLP_ENDPOINT — Collector endpoint (e.g., http://localhost:4318)
+ *   OTEL_SERVICE_NAME — Service name (default: "whale-workflow-engine")
+ *   OTEL_ENABLED — Set to "true" to enable (disabled by default)
+ *
+ * Backward compatible: If OTEL is not enabled, all functions are no-ops.
+ */
+export interface SpanContext {
+    end: (attrs?: Record<string, unknown>) => void;
+    setError: (err: Error | string) => void;
+    setAttribute: (key: string, value: string | number | boolean) => void;
+    addEvent: (name: string, attrs?: Record<string, unknown>) => void;
+}
+/**
+ * Initialize OpenTelemetry SDK. Call once at startup.
+ * No-op if OTEL_ENABLED !== "true".
+ */
+export declare function initOtel(): Promise<void>;
+/**
+ * Graceful shutdown — flush pending spans.
+ */
+export declare function shutdownOtel(): Promise<void>;
+/**
+ * Start a new span for tracking an operation.
+ * Returns a SpanContext that wraps the OTEL span API.
+ * If OTEL is disabled, returns a no-op.
+ */
+export declare function startSpan(name: string, attributes?: Record<string, string | number | boolean>): SpanContext;
+/**
+ * Convenience: wrap an async function in a span.
+ */
+export declare function withSpan<T>(name: string, attributes: Record<string, string | number | boolean>, fn: (span: SpanContext) => Promise<T>): Promise<T>;

package/dist/server/lib/otel.js

@@ -0,0 +1,126 @@
+/**
+ * lib/otel.ts — OpenTelemetry SDK setup for workflow engine observability
+ *
+ * Phase 3.3: Adds distributed tracing spans for step execution, tool calls, LLM calls.
+ * Exports to any OTLP-compatible collector (Jaeger, Grafana Tempo, Honeycomb, etc.)
+ *
+ * Configuration:
+ *   OTEL_EXPORTER_OTLP_ENDPOINT — Collector endpoint (e.g., http://localhost:4318)
+ *   OTEL_SERVICE_NAME — Service name (default: "whale-workflow-engine")
+ *   OTEL_ENABLED — Set to "true" to enable (disabled by default)
+ *
+ * Backward compatible: If OTEL is not enabled, all functions are no-ops.
+ */
+const OTEL_ENABLED = process.env.OTEL_ENABLED === "true";
+const OTEL_ENDPOINT = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "";
+const SERVICE_NAME = process.env.OTEL_SERVICE_NAME || "whale-workflow-engine";
+// Lazy-loaded SDK references
+let _tracer = null;
+let _sdk = null;
+/**
+ * Initialize OpenTelemetry SDK. Call once at startup.
+ * No-op if OTEL_ENABLED !== "true".
+ */
+export async function initOtel() {
+    if (!OTEL_ENABLED || !OTEL_ENDPOINT)
+        return;
+    try {
+        // @ts-ignore — optional runtime dependency, gracefully handled by try/catch
+        const { NodeSDK } = await import("@opentelemetry/sdk-node");
+        // @ts-ignore
+        const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+        // @ts-ignore
+        const { Resource } = await import("@opentelemetry/resources");
+        // @ts-ignore
+        const { ATTR_SERVICE_NAME } = await import("@opentelemetry/semantic-conventions");
+        // @ts-ignore
+        const { trace } = await import("@opentelemetry/api");
+        const exporter = new OTLPTraceExporter({ url: `${OTEL_ENDPOINT}/v1/traces` });
+        _sdk = new NodeSDK({
+            resource: new Resource({ [ATTR_SERVICE_NAME]: SERVICE_NAME }),
+            traceExporter: exporter,
+        });
+        _sdk.start();
+        _tracer = trace.getTracer(SERVICE_NAME);
+        console.log(`[otel] initialized — exporting to ${OTEL_ENDPOINT}`);
+    }
+    catch (err) {
+        console.warn("[otel] Failed to initialize (SDK not installed?):", err.message);
+        // Non-fatal — all functions remain no-ops
+    }
+}
+/**
+ * Graceful shutdown — flush pending spans.
+ */
+export async function shutdownOtel() {
+    if (_sdk) {
+        try {
+            await _sdk.shutdown();
+        }
+        catch { /* ignore */ }
+    }
+}
+/** No-op span for when OTEL is disabled */
+const noopSpan = {
+    end: () => { },
+    setError: () => { },
+    setAttribute: () => { },
+    addEvent: () => { },
+};
+/**
+ * Start a new span for tracking an operation.
+ * Returns a SpanContext that wraps the OTEL span API.
+ * If OTEL is disabled, returns a no-op.
+ */
+export function startSpan(name, attributes) {
+    if (!_tracer)
+        return noopSpan;
+    try {
+        const span = _tracer.startSpan(name, {
+            attributes: attributes || {},
+        });
+        return {
+            end: (attrs) => {
+                if (attrs) {
+                    for (const [k, v] of Object.entries(attrs)) {
+                        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+                            span.setAttribute(k, v);
+                        }
+                    }
+                }
+                span.end();
+            },
+            setError: (err) => {
+                span.setStatus({ code: 2 /* ERROR */, message: typeof err === "string" ? err : err.message });
+                if (err instanceof Error) {
+                    span.recordException(err);
+                }
+            },
+            setAttribute: (key, value) => {
+                span.setAttribute(key, value);
+            },
+            addEvent: (eventName, attrs) => {
+                span.addEvent(eventName, attrs);
+            },
+        };
+    }
+    catch {
+        return noopSpan;
+    }
+}
+/**
+ * Convenience: wrap an async function in a span.
+ */
+export async function withSpan(name, attributes, fn) {
+    const span = startSpan(name, attributes);
+    try {
+        const result = await fn(span);
+        span.end();
+        return result;
+    }
+    catch (err) {
+        span.setError(err);
+        span.end();
+        throw err;
+    }
+}

package/dist/server/lib/pg-rate-limiter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * lib/pg-rate-limiter.ts — PostgreSQL-backed rate limiter
+ *
+ * Phase 3.4: Token bucket rate limiting backed by Postgres for cross-process consistency.
+ * Survives deploys and works across multiple Fly.io instances.
+ *
+ * Uses the in-memory limiter as a fast first-pass, then falls back to DB
+ * as the cross-process source of truth.
+ */
+import type { SupabaseClient } from "@supabase/supabase-js";
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    retryAfterSeconds: number;
+}
+/**
+ * Check rate limit using in-memory cache first, then DB for authoritative check.
+ * The in-memory check prevents unnecessary DB round-trips for clearly-allowed requests.
+ */
+export declare function checkRateLimit(supabase: SupabaseClient, key: string, maxTokens?: number, refillRate?: number, // tokens per second
+cost?: number): Promise<RateLimitResult>;

package/dist/server/lib/pg-rate-limiter.js

@@ -0,0 +1,86 @@
+/**
+ * lib/pg-rate-limiter.ts — PostgreSQL-backed rate limiter
+ *
+ * Phase 3.4: Token bucket rate limiting backed by Postgres for cross-process consistency.
+ * Survives deploys and works across multiple Fly.io instances.
+ *
+ * Uses the in-memory limiter as a fast first-pass, then falls back to DB
+ * as the cross-process source of truth.
+ */
+// Fast in-memory first-pass cache
+const memoryBuckets = new Map();
+/**
+ * Check rate limit using in-memory cache first, then DB for authoritative check.
+ * The in-memory check prevents unnecessary DB round-trips for clearly-allowed requests.
+ */
+export async function checkRateLimit(supabase, key, maxTokens = 100, refillRate = 1, // tokens per second
+cost = 1) {
+    // Fast path: in-memory check
+    const memResult = checkMemoryLimit(key, maxTokens, refillRate, cost);
+    if (!memResult.allowed) {
+        return memResult; // Definitely rate limited
+    }
+    // Authoritative check via DB RPC
+    try {
+        const { data, error } = await supabase.rpc("check_rate_limit", {
+            p_key: key,
+            p_max_tokens: maxTokens,
+            p_refill_rate: refillRate,
+            p_cost: cost,
+        });
+        if (error) {
+            // DB unavailable — fall back to memory-only
+            return memResult;
+        }
+        const row = Array.isArray(data) ? data[0] : data;
+        if (!row)
+            return memResult;
+        // Sync memory cache with DB state
+        const bucket = memoryBuckets.get(key);
+        if (bucket) {
+            bucket.tokens = Number(row.remaining);
+            bucket.lastRefill = Date.now();
+        }
+        return {
+            allowed: row.allowed,
+            remaining: Number(row.remaining),
+            retryAfterSeconds: Number(row.retry_after_seconds || 0),
+        };
+    }
+    catch {
+        // DB call failed — use memory result
+        return memResult;
+    }
+}
+/**
+ * In-memory only rate limit check (no DB call).
+ * Use this for high-frequency checks where DB latency is unacceptable.
+ */
+function checkMemoryLimit(key, maxTokens, refillRate, cost) {
+    const now = Date.now();
+    let bucket = memoryBuckets.get(key);
+    if (!bucket) {
+        bucket = { tokens: maxTokens, lastRefill: now, maxTokens, refillRate };
+        memoryBuckets.set(key, bucket);
+    }
+    // Refill tokens
+    const elapsed = (now - bucket.lastRefill) / 1000;
+    bucket.tokens = Math.min(bucket.maxTokens, bucket.tokens + elapsed * bucket.refillRate);
+    bucket.lastRefill = now;
+    if (bucket.tokens >= cost) {
+        bucket.tokens -= cost;
+        return { allowed: true, remaining: bucket.tokens, retryAfterSeconds: 0 };
+    }
+    const retryAfter = Math.ceil((cost - bucket.tokens) / bucket.refillRate);
+    return { allowed: false, remaining: bucket.tokens, retryAfterSeconds: retryAfter };
+}
+// Cleanup stale memory buckets every 5 minutes
+setInterval(() => {
+    const now = Date.now();
+    const staleMs = 300_000; // 5 minutes
+    for (const [key, bucket] of memoryBuckets) {
+        if (now - bucket.lastRefill > staleMs) {
+            memoryBuckets.delete(key);
+        }
+    }
+}, 300_000);

package/dist/server/lib/prompt-sanitizer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Prompt Sanitizer — prevents injection attacks in user-provided system prompts
+ * and tool descriptions.
+ *
+ * Detects and strips:
+ * - Prompt injection markers (</system>, <|im_start|>, [INST], <<SYS>>, etc.)
+ * - Role confusion attempts (Human:/Assistant: turn markers)
+ * - Unicode control characters (zero-width spaces, RTL overrides, etc.)
+ * - Excessive length (>50,000 chars)
+ * - Repeated special characters (>100 in a row)
+ *
+ * No external dependencies — regex only.
+ */
+export interface SanitizeResult {
+    sanitized: string;
+    warnings: string[];
+}
+/**
+ * Sanitize a user-provided system prompt to prevent injection attacks.
+ * Returns the cleaned prompt and an array of warnings for anything modified.
+ */
+export declare function sanitizeSystemPrompt(prompt: string): SanitizeResult;
+/**
+ * Validate that system prompt blocks follow Anthropic's expected format.
+ * Each block must be `{ type: "text", text: string }` with optional `cache_control`.
+ */
+export declare function validateSystemPromptStructure(blocks: unknown[]): boolean;
+/**
+ * Sanitize a tool description field to prevent injection via tool definitions.
+ * Same injection pattern detection as system prompts, with a 4096-char cap.
+ */
+export declare function sanitizeToolDescription(desc: string): string;
+/**
+ * Sanitize a system prompt and log any warnings. Use this at integration points
+ * where you want automatic structured logging of modifications.
+ */
+export declare function sanitizeAndLog(prompt: string, source: string, context?: Record<string, unknown>): string;

package/dist/server/lib/prompt-sanitizer.js

@@ -0,0 +1,177 @@
+/**
+ * Prompt Sanitizer — prevents injection attacks in user-provided system prompts
+ * and tool descriptions.
+ *
+ * Detects and strips:
+ * - Prompt injection markers (</system>, <|im_start|>, [INST], <<SYS>>, etc.)
+ * - Role confusion attempts (Human:/Assistant: turn markers)
+ * - Unicode control characters (zero-width spaces, RTL overrides, etc.)
+ * - Excessive length (>50,000 chars)
+ * - Repeated special characters (>100 in a row)
+ *
+ * No external dependencies — regex only.
+ */
+import { createLogger } from "./logger.js";
+const log = createLogger("prompt-sanitizer");
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+const MAX_SYSTEM_PROMPT_LENGTH = 50_000;
+const MAX_TOOL_DESCRIPTION_LENGTH = 4_096;
+const MAX_REPEATED_CHARS = 100;
+// ============================================================================
+// INJECTION PATTERNS
+// ============================================================================
+/** Patterns that attempt to break out of system prompt context or impersonate roles. */
+const INJECTION_PATTERNS = [
+    // XML/markup-style prompt boundaries
+    { pattern: /<\/system>/gi, label: "</system> tag" },
+    { pattern: /<system>/gi, label: "<system> tag" },
+    { pattern: /<\/assistant>/gi, label: "</assistant> tag" },
+    { pattern: /<\/user>/gi, label: "</user> tag" },
+    { pattern: /<\/human>/gi, label: "</human> tag" },
+    // OpenAI ChatML markers
+    { pattern: /<\|im_start\|>/gi, label: "<|im_start|> marker" },
+    { pattern: /<\|im_end\|>/gi, label: "<|im_end|> marker" },
+    { pattern: /<\|im_sep\|>/gi, label: "<|im_sep|> marker" },
+    { pattern: /<\|endoftext\|>/gi, label: "<|endoftext|> marker" },
+    // Llama/Mistral instruction markers
+    { pattern: /\[INST\]/gi, label: "[INST] marker" },
+    { pattern: /\[\/INST\]/gi, label: "[/INST] marker" },
+    { pattern: /<<SYS>>/gi, label: "<<SYS>> marker" },
+    { pattern: /<<\/SYS>>/gi, label: "<</SYS>> marker" },
+    // Anthropic turn markers (only match when they look like turn boundaries)
+    { pattern: /\n\nHuman:/g, label: "Human: turn marker" },
+    { pattern: /\n\nAssistant:/g, label: "Assistant: turn marker" },
+    { pattern: /^Human:/gm, label: "Human: at line start" },
+    { pattern: /^Assistant:/gm, label: "Assistant: at line start" },
+];
+/**
+ * Unicode control character ranges to strip.
+ * Includes zero-width spaces, joiners, RTL/LTR overrides, and other invisible chars.
+ * Preserves normal whitespace (tab, newline, carriage return, space).
+ */
+const UNICODE_CONTROL_REGEX = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u200B-\u200F\u2028-\u202E\u2060-\u2069\uFEFF\uFFF9-\uFFFB]/g;
+/** Repeated special character pattern (>100 of the same non-alphanumeric char) */
+const REPEATED_SPECIAL_REGEX = /([^\w\s])\1{100,}/g;
+/**
+ * Sanitize a user-provided system prompt to prevent injection attacks.
+ * Returns the cleaned prompt and an array of warnings for anything modified.
+ */
+export function sanitizeSystemPrompt(prompt) {
+    const warnings = [];
+    if (!prompt || typeof prompt !== "string") {
+        return { sanitized: "", warnings: ["Empty or non-string prompt provided"] };
+    }
+    let sanitized = prompt;
+    // 1. Strip Unicode control characters
+    const controlMatches = sanitized.match(UNICODE_CONTROL_REGEX);
+    if (controlMatches) {
+        warnings.push(`Stripped ${controlMatches.length} Unicode control character(s)`);
+        sanitized = sanitized.replace(UNICODE_CONTROL_REGEX, "");
+    }
+    // 2. Detect and strip injection patterns
+    for (const { pattern, label } of INJECTION_PATTERNS) {
+        // Reset lastIndex for global regexes
+        pattern.lastIndex = 0;
+        const matches = sanitized.match(pattern);
+        if (matches) {
+            warnings.push(`Stripped ${matches.length} instance(s) of ${label}`);
+            pattern.lastIndex = 0;
+            sanitized = sanitized.replace(pattern, "");
+        }
+    }
+    // 3. Truncate repeated special characters
+    const repeatedMatches = sanitized.match(REPEATED_SPECIAL_REGEX);
+    if (repeatedMatches) {
+        warnings.push(`Truncated ${repeatedMatches.length} sequence(s) of >100 repeated special characters`);
+        sanitized = sanitized.replace(REPEATED_SPECIAL_REGEX, (match, char) => {
+            return char.repeat(MAX_REPEATED_CHARS);
+        });
+    }
+    // 4. Enforce length limit
+    if (sanitized.length > MAX_SYSTEM_PROMPT_LENGTH) {
+        warnings.push(`Truncated system prompt from ${sanitized.length} to ${MAX_SYSTEM_PROMPT_LENGTH} characters`);
+        sanitized = sanitized.substring(0, MAX_SYSTEM_PROMPT_LENGTH);
+    }
+    return { sanitized, warnings };
+}
+// ============================================================================
+// VALIDATE SYSTEM PROMPT STRUCTURE
+// ============================================================================
+/**
+ * Validate that system prompt blocks follow Anthropic's expected format.
+ * Each block must be `{ type: "text", text: string }` with optional `cache_control`.
+ */
+export function validateSystemPromptStructure(blocks) {
+    if (!Array.isArray(blocks))
+        return false;
+    for (const block of blocks) {
+        if (!block || typeof block !== "object")
+            return false;
+        const b = block;
+        // Must have type: "text"
+        if (b.type !== "text")
+            return false;
+        // Must have text as string
+        if (typeof b.text !== "string")
+            return false;
+        // Only allowed fields: type, text, cache_control
+        const allowedFields = new Set(["type", "text", "cache_control"]);
+        for (const key of Object.keys(b)) {
+            if (!allowedFields.has(key))
+                return false;
+        }
+        // If cache_control present, validate its shape
+        if (b.cache_control !== undefined) {
+            if (!b.cache_control || typeof b.cache_control !== "object")
+                return false;
+            const cc = b.cache_control;
+            if (cc.type !== "ephemeral")
+                return false;
+        }
+    }
+    return true;
+}
+// ============================================================================
+// SANITIZE TOOL DESCRIPTION
+// ============================================================================
+/**
+ * Sanitize a tool description field to prevent injection via tool definitions.
+ * Same injection pattern detection as system prompts, with a 4096-char cap.
+ */
+export function sanitizeToolDescription(desc) {
+    if (!desc || typeof desc !== "string")
+        return "";
+    let sanitized = desc;
+    // Strip Unicode control characters
+    sanitized = sanitized.replace(UNICODE_CONTROL_REGEX, "");
+    // Strip injection patterns
+    for (const { pattern } of INJECTION_PATTERNS) {
+        pattern.lastIndex = 0;
+        sanitized = sanitized.replace(pattern, "");
+    }
+    // Truncate repeated special characters
+    sanitized = sanitized.replace(REPEATED_SPECIAL_REGEX, (match, char) => {
+        return char.repeat(MAX_REPEATED_CHARS);
+    });
+    // Enforce length limit
+    if (sanitized.length > MAX_TOOL_DESCRIPTION_LENGTH) {
+        sanitized = sanitized.substring(0, MAX_TOOL_DESCRIPTION_LENGTH);
+    }
+    return sanitized;
+}
+// ============================================================================
+// CONVENIENCE: SANITIZE AND LOG
+// ============================================================================
+/**
+ * Sanitize a system prompt and log any warnings. Use this at integration points
+ * where you want automatic structured logging of modifications.
+ */
+export function sanitizeAndLog(prompt, source, context) {
+    const { sanitized, warnings } = sanitizeSystemPrompt(prompt);
+    if (warnings.length > 0) {
+        log.warn({ source, warnings, originalLength: prompt.length, sanitizedLength: sanitized.length, ...context }, `System prompt sanitized: ${warnings.length} modification(s)`);
+    }
+    return sanitized;
+}

package/dist/server/lib/provider-capabilities.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Provider Capability Matrix — static feature map for intelligent request routing.
+ *
+ * Each provider declares which features it supports. This enables:
+ * - Pre-flight checks before sending a request to a provider
+ * - Capability-aware failover (don't fail over to a provider that can't handle the request)
+ * - Intelligent routing (pick the best provider for a given request shape)
+ */
+import type { ModelProvider } from "../../shared/constants.js";
+export interface ProviderCapabilities {
+    /** Can process images (vision) */
+    vision: boolean;
+    /** Can process PDF documents natively */
+    pdf: boolean;
+    /** Supports computer_use tool */
+    computerUse: boolean;
+    /** Can execute code natively (e.g. code interpreter) */
+    codeExecution: boolean;
+    /** Supports SSE streaming */
+    streaming: boolean;
+    /** Supports batch processing API */
+    batchApi: boolean;
+    /** Supports source citations */
+    citations: boolean;
+    /** Supports extended thinking / reasoning */
+    thinking: boolean;
+    /** Supports function calling / tool use */
+    toolUse: boolean;
+    /** Supports prompt caching */
+    caching: boolean;
+    /** Supports server-side context management (edits, compaction) */
+    contextManagement: boolean;
+    /** Maximum context window in tokens */
+    maxContextTokens: number;
+    /** Maximum output tokens */
+    maxOutputTokens: number;
+}
+/** Features that can be required for a request (boolean capabilities only) */
+export type CapabilityFeature = {
+    [K in keyof ProviderCapabilities]: ProviderCapabilities[K] extends boolean ? K : never;
+}[keyof ProviderCapabilities];
+/** Request shape used to determine the best provider */
+export interface RequestCapabilityRequirements {
+    hasImages?: boolean;
+    hasPdf?: boolean;
+    needsBatch?: boolean;
+    needsCitations?: boolean;
+    needsComputerUse?: boolean;
+    needsCodeExecution?: boolean;
+    needsThinking?: boolean;
+    needsContextManagement?: boolean;
+    minContextTokens?: number;
+    minOutputTokens?: number;
+}
+/**
+ * Get the full capability set for a provider.
+ * Returns a defensive copy so callers can't mutate the static map.
+ */
+export declare function getCapabilities(provider: ModelProvider): ProviderCapabilities;
+/**
+ * Check if a provider supports a specific boolean feature.
+ */
+export declare function supportsFeature(provider: ModelProvider, feature: CapabilityFeature): boolean;
+/**
+ * Find all providers that support a given boolean feature.
+ * Returns provider names sorted with anthropic first (default preference).
+ */
+export declare function findProvidersWithCapability(feature: CapabilityFeature): ModelProvider[];
+/**
+ * Determine the best provider for a request based on its capability requirements.
+ *
+ * Strategy:
+ * 1. Filter to providers that satisfy ALL required capabilities
+ * 2. Prefer Anthropic as default
+ * 3. Among remaining candidates, prefer the one with the largest context window
+ *
+ * Returns "anthropic" as fallback if no provider matches all requirements
+ * (better to attempt than to hard-fail — the provider will return a clear error).
+ */
+export declare function getBestProviderForRequest(request: RequestCapabilityRequirements, excludeProviders?: Set<string>): ModelProvider;
+/**
+ * Check if a provider can handle a request with the given requirements.
+ * Returns true if all requirements are met.
+ */
+export declare function canProviderHandleRequest(provider: ModelProvider, requirements: RequestCapabilityRequirements): boolean;