whale-code 6.4.0

package/dist/server/lib/server-subagent.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Server Subagent — enables Opus to delegate tool execution to Haiku/Sonnet.
+ *
+ * The parent agent loop injects all dependencies; this module has zero imports
+ * from index.ts (avoids circular deps) and is fully testable in isolation.
+ */
+import type Anthropic from "@anthropic-ai/sdk";
+import type { SupabaseClient } from "@supabase/supabase-js";
+export interface SubagentResult {
+    success: boolean;
+    output: string;
+    tokensUsed: {
+        input: number;
+        output: number;
+    };
+    costUsd: number;
+    toolsUsed: string[];
+    turnCount: number;
+}
+export interface SubagentProgressEvent {
+    subagentId: string;
+    event: "started" | "tool_start" | "tool_result" | "turn" | "done" | "error";
+    model?: string;
+    toolName?: string;
+    toolSuccess?: boolean;
+    turn?: number;
+    maxTurns?: number;
+    output?: string;
+}
+export type SubagentProgressCallback = (event: SubagentProgressEvent) => void;
+export interface RunServerSubagentOptions {
+    anthropic: Anthropic;
+    supabase: SupabaseClient;
+    storeId: string | undefined;
+    prompt: string;
+    model: "haiku" | "sonnet" | "opus";
+    maxTurns: number;
+    tools: Array<{
+        name: string;
+        description: string;
+        input_schema: Record<string, unknown>;
+    }>;
+    executeTool: (toolName: string, args: Record<string, unknown>) => Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: string;
+    }>;
+    onProgress?: SubagentProgressCallback;
+    clientDisconnected: {
+        value: boolean;
+    };
+    startedAt: number;
+    maxDurationMs: number;
+}
+export declare const DELEGATE_TASK_TOOL_DEF: {
+    name: string;
+    description: string;
+    input_schema: {
+        type: "object";
+        properties: {
+            prompt: {
+                type: string;
+                description: string;
+            };
+            model: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            max_turns: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function runServerSubagent(opts: RunServerSubagentOptions): Promise<SubagentResult>;

package/dist/server/lib/server-subagent.js

@@ -0,0 +1,203 @@
+/**
+ * Server Subagent — enables Opus to delegate tool execution to Haiku/Sonnet.
+ *
+ * The parent agent loop injects all dependencies; this module has zero imports
+ * from index.ts (avoids circular deps) and is fully testable in isolation.
+ */
+import { randomUUID } from "node:crypto";
+import { LoopDetector, estimateCostUsd, sanitizeError, isRetryableError, } from "../../shared/agent-core.js";
+import { buildAPIRequest } from "../../shared/api-client.js";
+import { MODELS, MODEL_MAP } from "../../shared/constants.js";
+import { dispatchTools } from "../../shared/tool-dispatch.js";
+// ============================================================================
+// TOOL DEFINITION — exposed to parent Opus agent
+// ============================================================================
+export const DELEGATE_TASK_TOOL_DEF = {
+    name: "delegate_task",
+    description: "Delegate a focused task to a faster sub-agent. Use for: data lookups, " +
+        "multi-step tool chains, analytics queries, inventory checks, customer lookups. " +
+        "Do NOT delegate decisions requiring your judgment or creative writing.",
+    input_schema: {
+        type: "object",
+        properties: {
+            prompt: {
+                type: "string",
+                description: "Clear instruction for the sub-agent. Include all context needed.",
+            },
+            model: {
+                type: "string",
+                enum: ["haiku", "sonnet", "opus"],
+                description: "haiku (fast/$1) for simple lookups. sonnet ($3) for multi-step chains. opus ($5) for complex reasoning. Default: haiku.",
+            },
+            max_turns: {
+                type: "number",
+                description: "Max agentic turns (1-12). Default: 6.",
+            },
+        },
+        required: ["prompt"],
+    },
+};
+// ============================================================================
+// SUBAGENT SYSTEM PROMPT
+// ============================================================================
+const SUBAGENT_SYSTEM_PROMPT = `You are a focused tool executor. Your job is to complete the delegated task using the available tools, then return a clear summary of the results.
+
+Rules:
+- Execute tools as needed to fulfill the request
+- Return factual results — do not add opinions or recommendations
+- If a tool fails, try an alternative approach or report the failure
+- Be concise in your final response
+- Always include store_id in tool calls when it's available in your context`;
+// ============================================================================
+// CORE LOOP
+// ============================================================================
+const SUBAGENT_MAX_OUTPUT_TOKENS = 8192;
+export async function runServerSubagent(opts) {
+    const { anthropic, prompt, model: modelAlias, maxTurns, tools, executeTool, onProgress, clientDisconnected, startedAt, maxDurationMs, storeId, } = opts;
+    const subagentId = `sub-${randomUUID().slice(0, 8)}`;
+    const modelId = MODEL_MAP[modelAlias] || MODELS.HAIKU;
+    const loopDetector = new LoopDetector();
+    const toolsUsed = [];
+    let totalIn = 0;
+    let totalOut = 0;
+    let cacheCreation = 0;
+    let cacheRead = 0;
+    // Enable thinking for capable models; adjust max tokens for Opus
+    const shouldThink = modelAlias === "opus" || modelAlias === "sonnet";
+    const effectiveMaxTokens = modelAlias === "opus" ? 16384 : SUBAGENT_MAX_OUTPUT_TOKENS;
+    // Context management for subagent: clear at 60K, keep 2, no compaction
+    const apiConfig = buildAPIRequest({
+        model: modelId,
+        contextProfile: "subagent",
+        thinkingEnabled: shouldThink,
+        maxOutputTokens: effectiveMaxTokens,
+    });
+    const system = storeId
+        ? `${SUBAGENT_SYSTEM_PROMPT}\n\nstore_id: ${storeId}`
+        : SUBAGENT_SYSTEM_PROMPT;
+    const messages = [{ role: "user", content: prompt }];
+    onProgress?.({ subagentId, event: "started", model: modelAlias });
+    let turn = 0;
+    let lastText = "";
+    while (turn < maxTurns) {
+        // Abort checks
+        if (clientDisconnected.value) {
+            return makeResult(false, "Client disconnected", totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);
+        }
+        if (Date.now() - startedAt > maxDurationMs) {
+            return makeResult(false, "Parent request timeout", totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);
+        }
+        turn++;
+        loopDetector.resetTurn();
+        onProgress?.({ subagentId, event: "turn", turn, maxTurns });
+        // Non-streaming API call with retry
+        let response;
+        try {
+            response = await withSubagentRetry(async () => {
+                return await anthropic.beta.messages.create({
+                    model: modelId,
+                    max_tokens: apiConfig.maxTokens,
+                    temperature: shouldThink ? 1 : 0.3, // Anthropic requires temp=1 with thinking
+                    system,
+                    tools: tools,
+                    messages: messages,
+                    betas: apiConfig.betas,
+                    context_management: apiConfig.contextManagement,
+                    ...(apiConfig.thinking ? { thinking: apiConfig.thinking } : {}),
+                });
+            });
+        }
+        catch (err) {
+            const errMsg = sanitizeError(err);
+            onProgress?.({ subagentId, event: "error", output: errMsg });
+            return makeResult(false, `API error: ${errMsg}`, totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);
+        }
+        // Track tokens (including cache for accurate cost)
+        totalIn += response.usage?.input_tokens || 0;
+        totalOut += response.usage?.output_tokens || 0;
+        cacheCreation += response.usage?.cache_creation_input_tokens ?? 0;
+        cacheRead += response.usage?.cache_read_input_tokens ?? 0;
+        // Extract text and tool_use blocks
+        const textBlocks = [];
+        const toolUseBlocks = [];
+        for (const block of response.content) {
+            if (block.type === "text") {
+                textBlocks.push(block.text);
+            }
+            else if (block.type === "tool_use") {
+                toolUseBlocks.push({ id: block.id, name: block.name, input: block.input });
+            }
+        }
+        lastText = textBlocks.join("\n");
+        // No tool calls → done
+        if (toolUseBlocks.length === 0) {
+            onProgress?.({ subagentId, event: "done", output: lastText });
+            return makeResult(true, lastText, totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);
+        }
+        // Execute tools in parallel via dispatchTools
+        const toolExecutor = async (name, input) => {
+            toolsUsed.push(name);
+            onProgress?.({ subagentId, event: "tool_start", toolName: name });
+            try {
+                const result = await executeTool(name, input);
+                onProgress?.({ subagentId, event: "tool_result", toolName: name, toolSuccess: result.success });
+                return {
+                    success: result.success,
+                    output: result.success ? JSON.stringify(result.data) : (result.error || "Unknown error"),
+                };
+            }
+            catch (err) {
+                const errMsg = sanitizeError(err);
+                onProgress?.({ subagentId, event: "tool_result", toolName: name, toolSuccess: false });
+                return { success: false, output: errMsg };
+            }
+        };
+        const { results: toolResults, bailOut, bailMessage } = await dispatchTools(toolUseBlocks, toolExecutor, { loopDetector, maxConcurrent: 3 });
+        if (bailOut) {
+            onProgress?.({ subagentId, event: "error", output: bailMessage });
+            return makeResult(false, bailMessage || "Too many errors", totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);
+        }
+        // Append for next turn
+        messages.push({
+            role: "assistant",
+            content: response.content,
+        });
+        messages.push({
+            role: "user",
+            content: toolResults,
+        });
+    }
+    // Exhausted max turns
+    onProgress?.({ subagentId, event: "done", output: lastText });
+    return makeResult(true, lastText || "(subagent completed without text response)", totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);
+}
+// ============================================================================
+// HELPERS
+// ============================================================================
+function makeResult(success, output, inputTokens, outputTokens, modelId, toolsUsed, turnCount, cacheReadTokens = 0, cacheCreationTokens = 0) {
+    return {
+        success,
+        output,
+        tokensUsed: { input: inputTokens, output: outputTokens },
+        costUsd: estimateCostUsd(inputTokens, outputTokens, modelId, 0, cacheReadTokens, cacheCreationTokens),
+        toolsUsed: [...new Set(toolsUsed)],
+        turnCount,
+    };
+}
+async function withSubagentRetry(fn, maxRetries = 2) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < maxRetries && isRetryableError(err)) {
+                await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt)));
+                continue;
+            }
+            throw err;
+        }
+    }
+    throw lastError;
+}

package/dist/server/lib/session-checkpoint.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Session Checkpoint Manager — Phase 4.2
+ *
+ * Periodically saves conversation state to Supabase so that server restarts
+ * don't lose in-progress conversations.  Checkpoints are written every 5 turns
+ * (fire-and-forget to avoid blocking the agent loop) and can be loaded to
+ * resume an interrupted conversation.
+ */
+import type { SupabaseClient } from "@supabase/supabase-js";
+export interface Checkpoint {
+    conversation_id: string;
+    turn: number;
+    messages: string;
+    tokens_used: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheCreation: number;
+    };
+    cost_so_far: number;
+    tools_used: string[];
+    created_at: string;
+}
+/**
+ * Upsert a checkpoint row for the given conversation.
+ *
+ * Only actually writes when `turn % CHECKPOINT_INTERVAL === 0` so callers can
+ * invoke this every turn without worrying about write frequency.
+ *
+ * The write is fire-and-forget — errors are logged but never thrown so the
+ * agent loop is never blocked.
+ */
+export declare function saveCheckpoint(supabase: SupabaseClient, conversationId: string, turn: number, messages: unknown[], tokensSoFar: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheCreation: number;
+}, costSoFar: number, toolsUsed: string[]): Promise<void>;
+/**
+ * Load the most recent checkpoint for a conversation.
+ * Returns null if no checkpoint exists or the table hasn't been created yet.
+ */
+export declare function loadCheckpoint(supabase: SupabaseClient, conversationId: string): Promise<Checkpoint | null>;
+/**
+ * Find conversations that were in_progress before the given server start time
+ * and mark them as resumable.  Returns the count of conversations marked.
+ *
+ * This should be called once during server startup to flag any conversations
+ * that were abandoned when the previous server instance went down.
+ */
+export declare function markOrphaned(supabase: SupabaseClient, serverStartTime: Date): Promise<number>;

package/dist/server/lib/session-checkpoint.js

@@ -0,0 +1,145 @@
+/**
+ * Session Checkpoint Manager — Phase 4.2
+ *
+ * Periodically saves conversation state to Supabase so that server restarts
+ * don't lose in-progress conversations.  Checkpoints are written every 5 turns
+ * (fire-and-forget to avoid blocking the agent loop) and can be loaded to
+ * resume an interrupted conversation.
+ */
+/** How often (in turns) to persist a checkpoint. */
+const CHECKPOINT_INTERVAL = 5;
+// ============================================================================
+// SAVE CHECKPOINT
+// ============================================================================
+/**
+ * Upsert a checkpoint row for the given conversation.
+ *
+ * Only actually writes when `turn % CHECKPOINT_INTERVAL === 0` so callers can
+ * invoke this every turn without worrying about write frequency.
+ *
+ * The write is fire-and-forget — errors are logged but never thrown so the
+ * agent loop is never blocked.
+ */
+export async function saveCheckpoint(supabase, conversationId, turn, messages, tokensSoFar, costSoFar, toolsUsed) {
+    // Only checkpoint at the configured interval
+    if (turn % CHECKPOINT_INTERVAL !== 0)
+        return;
+    try {
+        const checkpoint = {
+            conversation_id: conversationId,
+            turn,
+            messages: JSON.stringify(messages),
+            tokens_used: { ...tokensSoFar },
+            cost_so_far: costSoFar,
+            tools_used: [...new Set(toolsUsed)],
+            created_at: new Date().toISOString(),
+        };
+        const { error } = await supabase
+            .from("ai_conversation_checkpoints")
+            .upsert({
+            conversation_id: checkpoint.conversation_id,
+            turn: checkpoint.turn,
+            messages: checkpoint.messages,
+            tokens_used: checkpoint.tokens_used,
+            cost_so_far: checkpoint.cost_so_far,
+            tools_used: checkpoint.tools_used,
+            created_at: checkpoint.created_at,
+        }, { onConflict: "conversation_id" });
+        if (error) {
+            // Table may not exist yet — log once and move on
+            console.warn(`[checkpoint] Save failed for ${conversationId} turn ${turn}: ${error.message}`);
+        }
+        else {
+            console.log(`[checkpoint] Saved conversation ${conversationId} at turn ${turn}`);
+        }
+    }
+    catch (err) {
+        // Graceful degradation — never crash the agent loop
+        console.warn(`[checkpoint] Unexpected error saving ${conversationId}: ${err.message}`);
+    }
+}
+// ============================================================================
+// LOAD CHECKPOINT
+// ============================================================================
+/**
+ * Load the most recent checkpoint for a conversation.
+ * Returns null if no checkpoint exists or the table hasn't been created yet.
+ */
+export async function loadCheckpoint(supabase, conversationId) {
+    try {
+        const { data, error } = await supabase
+            .from("ai_conversation_checkpoints")
+            .select("conversation_id, turn, messages, tokens_used, cost_so_far, tools_used, created_at")
+            .eq("conversation_id", conversationId)
+            .order("turn", { ascending: false })
+            .limit(1)
+            .single();
+        if (error || !data) {
+            if (error && !error.message.includes("0 rows")) {
+                console.warn(`[checkpoint] Load failed for ${conversationId}: ${error.message}`);
+            }
+            return null;
+        }
+        return {
+            conversation_id: data.conversation_id,
+            turn: data.turn,
+            messages: data.messages,
+            tokens_used: data.tokens_used,
+            cost_so_far: data.cost_so_far,
+            tools_used: data.tools_used ?? [],
+            created_at: data.created_at,
+        };
+    }
+    catch (err) {
+        console.warn(`[checkpoint] Unexpected error loading ${conversationId}: ${err.message}`);
+        return null;
+    }
+}
+// ============================================================================
+// MARK ORPHANED CONVERSATIONS
+// ============================================================================
+/**
+ * Find conversations that were in_progress before the given server start time
+ * and mark them as resumable.  Returns the count of conversations marked.
+ *
+ * This should be called once during server startup to flag any conversations
+ * that were abandoned when the previous server instance went down.
+ */
+export async function markOrphaned(supabase, serverStartTime) {
+    try {
+        // Find checkpoints whose created_at is before this server boot AND whose
+        // conversation is still in an "active" / "in_progress" state (no final
+        // assistant message after the checkpoint timestamp).
+        const { data: orphans, error: selectError } = await supabase
+            .from("ai_conversation_checkpoints")
+            .select("conversation_id, turn, created_at")
+            .lt("created_at", serverStartTime.toISOString());
+        if (selectError) {
+            console.warn(`[checkpoint] markOrphaned select failed: ${selectError.message}`);
+            return 0;
+        }
+        if (!orphans || orphans.length === 0)
+            return 0;
+        const orphanIds = orphans.map((o) => o.conversation_id);
+        // Tag conversations as resumable in their metadata
+        const { error: updateError } = await supabase
+            .from("ai_conversations")
+            .update({
+            metadata: {
+                resumable: true,
+                orphaned_at: serverStartTime.toISOString(),
+            },
+        })
+            .in("id", orphanIds);
+        if (updateError) {
+            console.warn(`[checkpoint] markOrphaned update failed: ${updateError.message}`);
+            return 0;
+        }
+        console.log(`[checkpoint] Marked ${orphanIds.length} orphaned conversation(s) as resumable`);
+        return orphanIds.length;
+    }
+    catch (err) {
+        console.warn(`[checkpoint] markOrphaned unexpected error: ${err.message}`);
+        return 0;
+    }
+}

package/dist/server/lib/ssrf-guard.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validate a URL is safe to fetch (not targeting internal/private addresses).
+ * Does basic hostname checks first, then resolves DNS to catch rebinding attacks.
+ *
+ * @returns null if safe, or a string error message if blocked.
+ */
+export declare function validateUrl(urlStr: string): Promise<string | null>;
+/**
+ * Synchronous fast-path check (no DNS resolution).
+ * Use this when you can't await, or for backward compatibility.
+ * For full protection (including DNS rebinding), use validateUrl().
+ */
+export declare function isBlockedUrl(urlStr: string): boolean;