whale-code 6.5.6 → 6.5.7

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

@@ -0,0 +1,267 @@
+// server-subagent-loop.ts — Core subagent execution loop and helpers
+// Extracted from server-subagent.ts for modularity.
+
+import { randomUUID } from "node:crypto";
+import { LoopDetector, estimateCostUsd, sanitizeError, isRetryableError, addPromptCaching, AGENT_DEFAULTS } 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";
+// ============================================================================
+// 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 = AGENT_DEFAULTS.subagentMaxTokens;
+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 baseMaxTokens = opts.maxOutputTokens ?? SUBAGENT_MAX_OUTPUT_TOKENS;
+  const effectiveMaxTokens = modelAlias === "opus" ? Math.max(16384, baseMaxTokens) : baseMaxTokens;
+  const effectiveTemperature = opts.temperature ?? AGENT_DEFAULTS.subagentTemperature;
+
+  // 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
+    });
+
+    // Apply prompt caching to tools and messages for cache hits on repeated context
+    const {
+      tools: cachedTools,
+      messages: cachedMessages
+    } = addPromptCaching(tools, messages);
+
+    // 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 : effectiveTemperature,
+          // Anthropic requires temp=1 with thinking
+          system,
+          tools: cachedTools,
+          messages: cachedMessages,
+          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: AGENT_DEFAULTS.maxConcurrentTools,
+      batchErrorLimit: AGENT_DEFAULTS.loopBatchErrorLimit
+    });
+    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
+// ============================================================================
+
+export function makeResult(success, output, inputTokens, outputTokens, modelId, toolsUsed, turnCount, cacheReadTokens = 0, cacheCreationTokens = 0) {
+  return {
+    success,
+    output,
+    tokensUsed: {
+      input: inputTokens,
+      output: outputTokens,
+      cacheRead: cacheReadTokens,
+      cacheCreation: cacheCreationTokens
+    },
+    costUsd: estimateCostUsd(inputTokens, outputTokens, modelId, 0, cacheReadTokens, cacheCreationTokens),
+    toolsUsed: [...new Set(toolsUsed)],
+    turnCount,
+    stopReason: "end_turn" // subagent always runs to completion or error
+  };
+}
+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;
+}
+//# sourceMappingURL=server-subagent-loop.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-subagent-loop.js","names":["randomUUID","LoopDetector","estimateCostUsd","sanitizeError","isRetryableError","addPromptCaching","AGENT_DEFAULTS","buildAPIRequest","MODELS","MODEL_MAP","dispatchTools","SUBAGENT_SYSTEM_PROMPT","SUBAGENT_MAX_OUTPUT_TOKENS","subagentMaxTokens","runServerSubagent","opts","anthropic","prompt","model","modelAlias","maxTurns","tools","executeTool","onProgress","clientDisconnected","startedAt","maxDurationMs","storeId","subagentId","slice","modelId","HAIKU","loopDetector","toolsUsed","totalIn","totalOut","cacheCreation","cacheRead","shouldThink","baseMaxTokens","maxOutputTokens","effectiveMaxTokens","Math","max","effectiveTemperature","temperature","subagentTemperature","apiConfig","contextProfile","thinkingEnabled","system","messages","role","content","event","turn","lastText","value","makeResult","Date","now","resetTurn","cachedTools","cachedMessages","response","withSubagentRetry","beta","create","max_tokens","maxTokens","betas","context_management","contextManagement","thinking","err","errMsg","output","usage","input_tokens","output_tokens","cache_creation_input_tokens","cache_read_input_tokens","textBlocks","toolUseBlocks","block","type","push","text","id","name","input","join","length","toolExecutor","toolName","result","toolSuccess","success","JSON","stringify","data","error","results","toolResults","bailOut","bailMessage","maxConcurrent","maxConcurrentTools","batchErrorLimit","loopBatchErrorLimit","inputTokens","outputTokens","turnCount","cacheReadTokens","cacheCreationTokens","tokensUsed","costUsd","Set","stopReason","fn","maxRetries","lastError","attempt","Promise","resolve","setTimeout","pow"],"sources":["../../../src/server/lib/server-subagent-loop.ts"],"sourcesContent":["// server-subagent-loop.ts — Core subagent execution loop and helpers\n// Extracted from server-subagent.ts for modularity.\n\nimport { randomUUID } from \"node:crypto\";\nimport type Anthropic from \"@anthropic-ai/sdk\";\n\nimport {\n  LoopDetector,\n  estimateCostUsd,\n  sanitizeError,\n  isRetryableError,\n  addPromptCaching,\n  AGENT_DEFAULTS,\n} from \"../../shared/agent-core.js\";\nimport { buildAPIRequest } from \"../../shared/api-client.js\";\nimport { MODELS, MODEL_MAP } from \"../../shared/constants.js\";\nimport { dispatchTools } from \"../../shared/tool-dispatch.js\";\nimport type { SubagentResult, RunServerSubagentOptions } from \"./server-subagent.js\";\n\n// ============================================================================\n// SUBAGENT SYSTEM PROMPT\n// ============================================================================\n\nconst 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.\n\nRules:\n- Execute tools as needed to fulfill the request\n- Return factual results — do not add opinions or recommendations\n- If a tool fails, try an alternative approach or report the failure\n- Be concise in your final response\n- Always include store_id in tool calls when it's available in your context`;\n\n// ============================================================================\n// CORE LOOP\n// ============================================================================\n\nconst SUBAGENT_MAX_OUTPUT_TOKENS = AGENT_DEFAULTS.subagentMaxTokens;\n\nexport async function runServerSubagent(opts: RunServerSubagentOptions): Promise<SubagentResult> {\n  const {\n    anthropic,\n    prompt,\n    model: modelAlias,\n    maxTurns,\n    tools,\n    executeTool,\n    onProgress,\n    clientDisconnected,\n    startedAt,\n    maxDurationMs,\n    storeId,\n  } = opts;\n\n  const subagentId = `sub-${randomUUID().slice(0, 8)}`;\n  const modelId = MODEL_MAP[modelAlias] || MODELS.HAIKU;\n  const loopDetector = new LoopDetector();\n  const toolsUsed: string[] = [];\n\n  let totalIn = 0;\n  let totalOut = 0;\n  let cacheCreation = 0;\n  let cacheRead = 0;\n\n  // Enable thinking for capable models; adjust max tokens for Opus\n  const shouldThink = modelAlias === \"opus\" || modelAlias === \"sonnet\";\n  const baseMaxTokens = opts.maxOutputTokens ?? SUBAGENT_MAX_OUTPUT_TOKENS;\n  const effectiveMaxTokens = modelAlias === \"opus\" ? Math.max(16384, baseMaxTokens) : baseMaxTokens;\n  const effectiveTemperature = opts.temperature ?? AGENT_DEFAULTS.subagentTemperature;\n\n  // Context management for subagent: clear at 60K, keep 2, no compaction\n  const apiConfig = buildAPIRequest({\n    model: modelId,\n    contextProfile: \"subagent\",\n    thinkingEnabled: shouldThink,\n    maxOutputTokens: effectiveMaxTokens,\n  });\n\n  const system = storeId\n    ? `${SUBAGENT_SYSTEM_PROMPT}\\n\\nstore_id: ${storeId}`\n    : SUBAGENT_SYSTEM_PROMPT;\n\n  const messages: Anthropic.MessageParam[] = [{ role: \"user\", content: prompt }];\n\n  onProgress?.({ subagentId, event: \"started\", model: modelAlias });\n\n  let turn = 0;\n  let lastText = \"\";\n\n  while (turn < maxTurns) {\n    // Abort checks\n    if (clientDisconnected.value) {\n      return makeResult(false, \"Client disconnected\", totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);\n    }\n    if (Date.now() - startedAt > maxDurationMs) {\n      return makeResult(false, \"Parent request timeout\", totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);\n    }\n\n    turn++;\n    loopDetector.resetTurn();\n\n    onProgress?.({ subagentId, event: \"turn\", turn, maxTurns });\n\n    // Apply prompt caching to tools and messages for cache hits on repeated context\n    const { tools: cachedTools, messages: cachedMessages } = addPromptCaching(\n      tools as any, messages as any,\n    );\n\n    // Non-streaming API call with retry\n    let response: Anthropic.Message;\n    try {\n      response = await withSubagentRetry(async () => {\n        return await anthropic.beta.messages.create({\n          model: modelId,\n          max_tokens: apiConfig.maxTokens,\n          temperature: shouldThink ? 1 : effectiveTemperature,  // Anthropic requires temp=1 with thinking\n          system,\n          tools: cachedTools as any,\n          messages: cachedMessages as any,\n          betas: apiConfig.betas,\n          context_management: apiConfig.contextManagement,\n          ...(apiConfig.thinking ? { thinking: apiConfig.thinking } : {}),\n        } as any) as unknown as Anthropic.Message;\n      });\n    } catch (err) {\n      const errMsg = sanitizeError(err);\n      onProgress?.({ subagentId, event: \"error\", output: errMsg });\n      return makeResult(false, `API error: ${errMsg}`, totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);\n    }\n\n    // Track tokens (including cache for accurate cost)\n    totalIn += response.usage?.input_tokens || 0;\n    totalOut += response.usage?.output_tokens || 0;\n    cacheCreation += (response.usage as any)?.cache_creation_input_tokens ?? 0;\n    cacheRead += (response.usage as any)?.cache_read_input_tokens ?? 0;\n\n    // Extract text and tool_use blocks\n    const textBlocks: string[] = [];\n    const toolUseBlocks: Array<{ id: string; name: string; input: Record<string, unknown> }> = [];\n\n    for (const block of response.content) {\n      if (block.type === \"text\") {\n        textBlocks.push(block.text);\n      } else if (block.type === \"tool_use\") {\n        toolUseBlocks.push({ id: block.id, name: block.name, input: block.input as Record<string, unknown> });\n      }\n    }\n\n    lastText = textBlocks.join(\"\\n\");\n\n    // No tool calls → done\n    if (toolUseBlocks.length === 0) {\n      onProgress?.({ subagentId, event: \"done\", output: lastText });\n      return makeResult(true, lastText, totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);\n    }\n\n    // Execute tools in parallel via dispatchTools\n    const toolExecutor = async (name: string, input: Record<string, unknown>) => {\n      toolsUsed.push(name);\n      onProgress?.({ subagentId, event: \"tool_start\", toolName: name });\n      try {\n        const result = await executeTool(name, input);\n        onProgress?.({ subagentId, event: \"tool_result\", toolName: name, toolSuccess: result.success });\n        return {\n          success: result.success,\n          output: result.success ? JSON.stringify(result.data) : (result.error || \"Unknown error\"),\n        };\n      } catch (err) {\n        const errMsg = sanitizeError(err);\n        onProgress?.({ subagentId, event: \"tool_result\", toolName: name, toolSuccess: false });\n        return { success: false, output: errMsg };\n      }\n    };\n\n    const { results: toolResults, bailOut, bailMessage } = await dispatchTools(\n      toolUseBlocks as any,\n      toolExecutor,\n      { loopDetector, maxConcurrent: AGENT_DEFAULTS.maxConcurrentTools, batchErrorLimit: AGENT_DEFAULTS.loopBatchErrorLimit },\n    );\n\n    if (bailOut) {\n      onProgress?.({ subagentId, event: \"error\", output: bailMessage });\n      return makeResult(false, bailMessage || \"Too many errors\", totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);\n    }\n\n    // Append for next turn\n    messages.push({\n      role: \"assistant\",\n      content: response.content as any,\n    });\n    messages.push({\n      role: \"user\",\n      content: toolResults as any,\n    });\n  }\n\n  // Exhausted max turns\n  onProgress?.({ subagentId, event: \"done\", output: lastText });\n  return makeResult(true, lastText || \"(subagent completed without text response)\", totalIn, totalOut, modelId, toolsUsed, turn, cacheRead, cacheCreation);\n}\n\n// ============================================================================\n// HELPERS\n// ============================================================================\n\nexport function makeResult(\n  success: boolean,\n  output: string,\n  inputTokens: number,\n  outputTokens: number,\n  modelId: string,\n  toolsUsed: string[],\n  turnCount: number,\n  cacheReadTokens = 0,\n  cacheCreationTokens = 0,\n): SubagentResult {\n  return {\n    success,\n    output,\n    tokensUsed: { input: inputTokens, output: outputTokens, cacheRead: cacheReadTokens, cacheCreation: cacheCreationTokens },\n    costUsd: estimateCostUsd(inputTokens, outputTokens, modelId, 0, cacheReadTokens, cacheCreationTokens),\n    toolsUsed: [...new Set(toolsUsed)],\n    turnCount,\n    stopReason: \"end_turn\", // subagent always runs to completion or error\n  };\n}\n\nasync function withSubagentRetry<T>(fn: () => Promise<T>, maxRetries = 2): Promise<T> {\n  let lastError: unknown;\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      return await fn();\n    } catch (err) {\n      lastError = err;\n      if (attempt < maxRetries && isRetryableError(err)) {\n        await new Promise((resolve) => setTimeout(resolve, 1000 * Math.pow(2, attempt)));\n        continue;\n      }\n      throw err;\n    }\n  }\n  throw lastError;\n}\n"],"mappings":"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","ignoreList":[]}

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

@@ -0,0 +1,106 @@
+/**
+ * Session Types — shared types for the unified session architecture.
+ *
+ * Types only (no runtime logic) to avoid circular dependencies.
+ * SessionManager, sessions-handlers, and CLI session-client all import from here.
+ */
+import type Anthropic from "@anthropic-ai/sdk";
+import type { SenderContext } from "../handlers/nodes-utils.js";
+export type SessionSurface = "cli" | "whale_chat" | "channel" | "workflow" | "api";
+export type SessionRunner = "server" | "node";
+export type SessionStatus = "active" | "paused" | "completed" | "cancelled" | "error";
+export interface Session {
+    id: string;
+    store_id: string;
+    agent_id: string;
+    conversation_id: string;
+    surface: SessionSurface;
+    runner: SessionRunner;
+    status: SessionStatus;
+    user_id?: string;
+    customer_id?: string;
+    sender_context?: SenderContext;
+    turn_count: number;
+    cost_usd: number;
+    cost_budget_usd: number;
+    task?: SessionTask;
+    created_at: string;
+    updated_at: string;
+    metadata: Record<string, unknown>;
+}
+export interface SessionTask {
+    description: string;
+    node_id?: string;
+    started_at: string;
+    progress?: string;
+}
+export interface CreateSessionOpts {
+    storeId: string;
+    agentId: string;
+    surface: SessionSurface;
+    userId?: string;
+    userEmail?: string | null;
+    conversationId?: string;
+    senderContext?: SenderContext;
+    message?: string;
+}
+export interface ExecuteTurnOpts {
+    message: string;
+    attachments?: Array<{
+        type: string;
+        media_type: string;
+        data: string;
+    }>;
+    conversationHistory?: Anthropic.MessageParam[];
+    context?: Record<string, unknown>;
+    streaming: boolean;
+    onText?: (text: string) => void;
+    onToolStart?: (name: string, input?: unknown) => void;
+    onToolResult?: (name: string, success: boolean, result?: unknown) => void;
+    onToolProgress?: (name: string, progress: unknown) => void;
+    onSubagentProgress?: (event: unknown) => void;
+    clientDisconnected?: {
+        value: boolean;
+    };
+    maxTurns?: number;
+    maxDurationMs?: number;
+    source?: string;
+}
+export interface TurnResult {
+    finalText: string;
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheCreation: number;
+    };
+    costUsd: number;
+    turnCount: number;
+    toolsUsed: string[];
+    toolCallCount: number;
+    stopReason?: string;
+    loopDetectorStats?: {
+        totalErrors: number;
+        failedStrategies: number;
+        consecutiveFailedTurns: number;
+    };
+    turns?: Array<{
+        turn: number;
+        inputTokens: number;
+        outputTokens: number;
+        cacheRead: number;
+        cacheCreation: number;
+        toolsUsed: string[];
+        costUsd: number;
+    }>;
+}
+export interface TaskAssignment {
+    session_id: string;
+    agent_id: string;
+    description: string;
+    tools?: string[];
+    system_prompt?: string;
+    history?: Anthropic.MessageParam[];
+    max_turns?: number;
+    max_cost_usd?: number;
+}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-types.js.map

package/dist/server/lib/session-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-types.js","names":[],"sources":["../../../src/server/lib/session-types.ts"],"sourcesContent":["/**\n * Session Types — shared types for the unified session architecture.\n *\n * Types only (no runtime logic) to avoid circular dependencies.\n * SessionManager, sessions-handlers, and CLI session-client all import from here.\n */\n\nimport type Anthropic from \"@anthropic-ai/sdk\";\nimport type { SenderContext } from \"../handlers/nodes-utils.js\";\n\n// ============================================================================\n// SESSION CORE TYPES\n// ============================================================================\n\nexport type SessionSurface = \"cli\" | \"whale_chat\" | \"channel\" | \"workflow\" | \"api\";\nexport type SessionRunner = \"server\" | \"node\";\nexport type SessionStatus = \"active\" | \"paused\" | \"completed\" | \"cancelled\" | \"error\";\n\nexport interface Session {\n  id: string;               // = ai_conversations.id\n  store_id: string;\n  agent_id: string;\n  conversation_id: string;  // same as id\n  surface: SessionSurface;\n  runner: SessionRunner;\n  status: SessionStatus;\n  user_id?: string;\n  customer_id?: string;\n  sender_context?: SenderContext;\n  turn_count: number;\n  cost_usd: number;\n  cost_budget_usd: number;\n  task?: SessionTask;\n  created_at: string;\n  updated_at: string;\n  metadata: Record<string, unknown>;\n}\n\nexport interface SessionTask {\n  description: string;\n  node_id?: string;\n  started_at: string;\n  progress?: string;\n}\n\n// ============================================================================\n// SESSION OPERATIONS\n// ============================================================================\n\nexport interface CreateSessionOpts {\n  storeId: string;\n  agentId: string;\n  surface: SessionSurface;\n  userId?: string;\n  userEmail?: string | null;\n  conversationId?: string;       // resume existing\n  senderContext?: SenderContext;  // channel identity\n  message?: string;              // for title generation\n}\n\nexport interface ExecuteTurnOpts {\n  message: string;\n  attachments?: Array<{ type: string; media_type: string; data: string }>;\n  conversationHistory?: Anthropic.MessageParam[];  // client-provided (CLI/WhaleChat)\n  context?: Record<string, unknown>;               // client context object\n  streaming: boolean;\n  onText?: (text: string) => void;\n  onToolStart?: (name: string, input?: unknown) => void;\n  onToolResult?: (name: string, success: boolean, result?: unknown) => void;\n  onToolProgress?: (name: string, progress: unknown) => void;\n  onSubagentProgress?: (event: unknown) => void;\n  clientDisconnected?: { value: boolean };\n  maxTurns?: number;\n  maxDurationMs?: number;\n  source?: string;                                 // e.g. \"whale_chat\", \"channel_agent\"\n}\n\n// ============================================================================\n// TURN RESULT\n// ============================================================================\n\nexport interface TurnResult {\n  finalText: string;\n  tokens: {\n    input: number;\n    output: number;\n    cacheRead: number;\n    cacheCreation: number;\n  };\n  costUsd: number;\n  turnCount: number;\n  toolsUsed: string[];\n  toolCallCount: number;\n  stopReason?: string;\n  loopDetectorStats?: {\n    totalErrors: number;\n    failedStrategies: number;\n    consecutiveFailedTurns: number;\n  };\n  turns?: Array<{\n    turn: number;\n    inputTokens: number;\n    outputTokens: number;\n    cacheRead: number;\n    cacheCreation: number;\n    toolsUsed: string[];\n    costUsd: number;\n  }>;\n}\n\n// ============================================================================\n// TASK ASSIGNMENT (Node runner)\n// ============================================================================\n\nexport interface TaskAssignment {\n  session_id: string;\n  agent_id: string;\n  description: string;\n  tools?: string[];\n  system_prompt?: string;\n  history?: Anthropic.MessageParam[];\n  max_turns?: number;\n  max_cost_usd?: number;\n}\n"],"mappings":"","ignoreList":[]}

package/dist/server/local-agent-gateway-api.d.ts

@@ -0,0 +1,34 @@
+import { type AgentResult } from "./local-agent-gateway-types.js";
+export { getGatewayStats, getRemoteDesktopSessions, getPortalSessions, executeClusterCommand, shutdownGateway, type ClusterCommandArgs, } from "./local-agent-gateway-stats.js";
+export declare function hasLocalAgent(storeId: string): boolean;
+/**
+ * Get info about connected agents for a store.
+ */
+export declare function getAgentInfo(storeId: string): Array<{
+    agent_id: string;
+    platform: string;
+    hostname: string;
+    capabilities: string[];
+    connected_at: string;
+    uptime_seconds: number;
+    node_id: string | null;
+}>;
+/**
+ * Execute a command on the user's local machine via their connected agent.
+ */
+export declare function executeOnLocalAgent(storeId: string, command: string, options?: {
+    session_id?: string;
+    timeout?: number;
+    agent_id?: string;
+}): Promise<AgentResult>;
+/**
+ * Execute a managed tool on the local agent (burp, zap, tshark, etc.)
+ */
+export declare function executeToolOnLocalAgent(storeId: string, tool: string, args: Record<string, unknown>, options?: {
+    timeout?: number;
+    agent_id?: string;
+}): Promise<AgentResult>;
+/**
+ * Request tool discovery from agent.
+ */
+export declare function discoverLocalTools(storeId: string): Promise<AgentResult>;

package/dist/server/local-agent-gateway-api.js

@@ -0,0 +1,156 @@
+// local-agent-gateway-api.ts — Public API for agent execution and tool discovery
+import { WebSocket } from "ws";
+import { randomUUID } from "node:crypto";
+import { agentPool, pendingRequests, pickAgent, send } from "./local-agent-gateway-types.js";
+
+// Re-export stats, cluster, and shutdown from sub-module
+export { getGatewayStats, getRemoteDesktopSessions, getPortalSessions, executeClusterCommand, shutdownGateway } from "./local-agent-gateway-stats.js";
+export function hasLocalAgent(storeId) {
+  const agents = agentPool.get(storeId.toLowerCase());
+  return !!agents?.some(a => a.ws.readyState === WebSocket.OPEN);
+}
+
+/**
+ * Get info about connected agents for a store.
+ */
+export function getAgentInfo(storeId) {
+  const agents = agentPool.get(storeId.toLowerCase()) || [];
+  return agents.filter(a => a.ws.readyState === WebSocket.OPEN).map(a => ({
+    agent_id: a.agentId,
+    platform: a.platform,
+    hostname: a.hostname,
+    capabilities: a.capabilities,
+    connected_at: a.connectedAt.toISOString(),
+    uptime_seconds: Math.floor((Date.now() - a.connectedAt.getTime()) / 1000),
+    node_id: a.nodeId
+  }));
+}
+
+/**
+ * Execute a command on the user's local machine via their connected agent.
+ */
+export async function executeOnLocalAgent(storeId, command, options = {}) {
+  const agent = pickAgent(storeId, options.agent_id);
+  if (!agent) {
+    return {
+      success: false,
+      error: `No local agent connected for this store. Install and run: whale agent start --key YOUR_API_KEY`
+    };
+  }
+  const requestId = randomUUID();
+  const timeout = Math.min(options.timeout || 30000, 600000);
+  const sent = send(agent.ws, {
+    type: "exec",
+    request_id: requestId,
+    command,
+    session_id: options.session_id,
+    timeout
+  });
+  if (!sent) return {
+    success: false,
+    error: "Agent connection closed"
+  };
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingRequests.delete(requestId);
+      resolve({
+        success: false,
+        error: `Local agent command timed out after ${timeout}ms`
+      });
+    }, timeout + 5000);
+    pendingRequests.set(requestId, {
+      resolve,
+      reject,
+      timer,
+      agentId: agent.agentId
+    });
+  });
+}
+
+/**
+ * Execute a managed tool on the local agent (burp, zap, tshark, etc.)
+ */
+export async function executeToolOnLocalAgent(storeId, tool, args, options = {}) {
+  const agent = pickAgent(storeId, options.agent_id);
+  if (!agent) {
+    return {
+      success: false,
+      error: `No local agent connected. Install: whale agent start --key YOUR_API_KEY`
+    };
+  }
+  if (!agent.capabilities.includes(tool)) {
+    return {
+      success: false,
+      error: `Local agent does not have tool "${tool}" installed. Available: ${agent.capabilities.join(", ") || "none"}`
+    };
+  }
+  const requestId = randomUUID();
+  const timeout = Math.min(options.timeout || 30000, 600000);
+  const sent = send(agent.ws, {
+    type: "tool_exec",
+    request_id: requestId,
+    tool,
+    args,
+    timeout
+  });
+  if (!sent) return {
+    success: false,
+    error: "Agent connection closed"
+  };
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingRequests.delete(requestId);
+      resolve({
+        success: false,
+        error: `Local tool "${tool}" timed out after ${timeout}ms`
+      });
+    }, timeout + 5000);
+    pendingRequests.set(requestId, {
+      resolve,
+      reject,
+      timer,
+      agentId: agent.agentId
+    });
+  });
+}
+
+/**
+ * Request tool discovery from agent.
+ */
+export async function discoverLocalTools(storeId) {
+  const agent = pickAgent(storeId.toLowerCase());
+  if (!agent) {
+    return {
+      success: false,
+      error: `No local agent connected. Install: whale agent start --key YOUR_API_KEY`
+    };
+  }
+  const requestId = randomUUID();
+  const sent = send(agent.ws, {
+    type: "discover",
+    request_id: requestId
+  });
+  if (!sent) return {
+    success: false,
+    error: "Agent connection closed"
+  };
+  return new Promise(resolve => {
+    const timer = setTimeout(() => {
+      pendingRequests.delete(requestId);
+      resolve({
+        success: false,
+        error: "Discovery timed out"
+      });
+    }, 15000);
+    pendingRequests.set(requestId, {
+      resolve,
+      reject: () => resolve({
+        success: false,
+        error: "Discovery failed"
+      }),
+      timer,
+      agentId: agent.agentId
+    });
+  });
+}
+//# sourceMappingURL=local-agent-gateway-api.js.map

package/dist/server/local-agent-gateway-api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-agent-gateway-api.js","names":["WebSocket","randomUUID","agentPool","pendingRequests","pickAgent","send","getGatewayStats","getRemoteDesktopSessions","getPortalSessions","executeClusterCommand","shutdownGateway","hasLocalAgent","storeId","agents","get","toLowerCase","some","a","ws","readyState","OPEN","getAgentInfo","filter","map","agent_id","agentId","platform","hostname","capabilities","connected_at","connectedAt","toISOString","uptime_seconds","Math","floor","Date","now","getTime","node_id","nodeId","executeOnLocalAgent","command","options","agent","success","error","requestId","timeout","min","sent","type","request_id","session_id","Promise","resolve","reject","timer","setTimeout","delete","set","executeToolOnLocalAgent","tool","args","includes","join","discoverLocalTools"],"sources":["../../src/server/local-agent-gateway-api.ts"],"sourcesContent":["// local-agent-gateway-api.ts — Public API for agent execution and tool discovery\nimport { WebSocket } from \"ws\";\nimport { randomUUID } from \"node:crypto\";\nimport {\n  type LocalAgent, type AgentResult,\n  agentPool, pendingRequests,\n  pickAgent, send,\n} from \"./local-agent-gateway-types.js\";\n\n// Re-export stats, cluster, and shutdown from sub-module\nexport {\n  getGatewayStats, getRemoteDesktopSessions, getPortalSessions,\n  executeClusterCommand, shutdownGateway,\n  type ClusterCommandArgs,\n} from \"./local-agent-gateway-stats.js\";\n\nexport function hasLocalAgent(storeId: string): boolean {\n  const agents = agentPool.get(storeId.toLowerCase());\n  return !!agents?.some(a => a.ws.readyState === WebSocket.OPEN);\n}\n\n/**\n * Get info about connected agents for a store.\n */\nexport function getAgentInfo(storeId: string): Array<{\n  agent_id: string;\n  platform: string;\n  hostname: string;\n  capabilities: string[];\n  connected_at: string;\n  uptime_seconds: number;\n  node_id: string | null;\n}> {\n  const agents = agentPool.get(storeId.toLowerCase()) || [];\n  return agents\n    .filter(a => a.ws.readyState === WebSocket.OPEN)\n    .map(a => ({\n      agent_id: a.agentId,\n      platform: a.platform,\n      hostname: a.hostname,\n      capabilities: a.capabilities,\n      connected_at: a.connectedAt.toISOString(),\n      uptime_seconds: Math.floor((Date.now() - a.connectedAt.getTime()) / 1000),\n      node_id: a.nodeId,\n    }));\n}\n\n/**\n * Execute a command on the user's local machine via their connected agent.\n */\nexport async function executeOnLocalAgent(\n  storeId: string,\n  command: string,\n  options: {\n    session_id?: string;\n    timeout?: number;\n    agent_id?: string;\n  } = {},\n): Promise<AgentResult> {\n  const agent = pickAgent(storeId, options.agent_id);\n  if (!agent) {\n    return {\n      success: false,\n      error: `No local agent connected for this store. Install and run: whale agent start --key YOUR_API_KEY`,\n    };\n  }\n\n  const requestId = randomUUID();\n  const timeout = Math.min(options.timeout || 30000, 600000);\n\n  const sent = send(agent.ws, {\n    type: \"exec\",\n    request_id: requestId,\n    command,\n    session_id: options.session_id,\n    timeout,\n  });\n  if (!sent) return { success: false, error: \"Agent connection closed\" };\n\n  return new Promise<AgentResult>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      pendingRequests.delete(requestId);\n      resolve({\n        success: false,\n        error: `Local agent command timed out after ${timeout}ms`,\n      });\n    }, timeout + 5000);\n\n    pendingRequests.set(requestId, { resolve, reject, timer, agentId: agent.agentId });\n  });\n}\n\n/**\n * Execute a managed tool on the local agent (burp, zap, tshark, etc.)\n */\nexport async function executeToolOnLocalAgent(\n  storeId: string,\n  tool: string,\n  args: Record<string, unknown>,\n  options: {\n    timeout?: number;\n    agent_id?: string;\n  } = {},\n): Promise<AgentResult> {\n  const agent = pickAgent(storeId, options.agent_id);\n  if (!agent) {\n    return {\n      success: false,\n      error: `No local agent connected. Install: whale agent start --key YOUR_API_KEY`,\n    };\n  }\n\n  if (!agent.capabilities.includes(tool)) {\n    return {\n      success: false,\n      error: `Local agent does not have tool \"${tool}\" installed. Available: ${agent.capabilities.join(\", \") || \"none\"}`,\n    };\n  }\n\n  const requestId = randomUUID();\n  const timeout = Math.min(options.timeout || 30000, 600000);\n\n  const sent = send(agent.ws, {\n    type: \"tool_exec\",\n    request_id: requestId,\n    tool,\n    args,\n    timeout,\n  });\n  if (!sent) return { success: false, error: \"Agent connection closed\" };\n\n  return new Promise<AgentResult>((resolve, reject) => {\n    const timer = setTimeout(() => {\n      pendingRequests.delete(requestId);\n      resolve({\n        success: false,\n        error: `Local tool \"${tool}\" timed out after ${timeout}ms`,\n      });\n    }, timeout + 5000);\n\n    pendingRequests.set(requestId, { resolve, reject, timer, agentId: agent.agentId });\n  });\n}\n\n/**\n * Request tool discovery from agent.\n */\nexport async function discoverLocalTools(storeId: string): Promise<AgentResult> {\n  const agent = pickAgent(storeId.toLowerCase());\n  if (!agent) {\n    return {\n      success: false,\n      error: `No local agent connected. Install: whale agent start --key YOUR_API_KEY`,\n    };\n  }\n\n  const requestId = randomUUID();\n\n  const sent = send(agent.ws, { type: \"discover\", request_id: requestId });\n  if (!sent) return { success: false, error: \"Agent connection closed\" };\n\n  return new Promise<AgentResult>((resolve) => {\n    const timer = setTimeout(() => {\n      pendingRequests.delete(requestId);\n      resolve({ success: false, error: \"Discovery timed out\" });\n    }, 15000);\n\n    pendingRequests.set(requestId, {\n      resolve,\n      reject: () => resolve({ success: false, error: \"Discovery failed\" }),\n      timer,\n      agentId: agent.agentId,\n    });\n  });\n}\n"],"mappings":"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","ignoreList":[]}

package/dist/server/local-agent-gateway-handler.d.ts

@@ -0,0 +1,3 @@
+import { WebSocket } from "ws";
+import type http from "node:http";
+export declare function handleConnection(ws: WebSocket, _req: http.IncomingMessage): void;