@stackmemoryai/stackmemory 1.0.0 → 1.2.0

package/dist/src/integrations/claude-code/subagent-client.js

@@ -3,11 +3,21 @@ import { dirname as __pathDirname } from 'path';
 const __filename = __fileURLToPath(import.meta.url);
 const __dirname = __pathDirname(__filename);
 import { logger } from "../../core/monitoring/logger.js";
+import { STRUCTURED_RESPONSE_SUFFIX } from "../../orchestrators/multimodal/constants.js";
 import { exec } from "child_process";
 import { promisify } from "util";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import { isFeatureEnabled } from "../../core/config/feature-flags.js";
+import {
+  getOptimalProvider
+} from "../../core/models/model-router.js";
+import { scoreComplexity } from "../../core/models/complexity-scorer.js";
+import {
+  createProvider
+} from "../../core/extensions/provider-adapter.js";
+import { AnthropicBatchClient } from "../anthropic/batch-client.js";
 const execAsync = promisify(exec);
 class ClaudeCodeSubagentClient {
   tempDir;
@@ -25,8 +35,9 @@ class ClaudeCodeSubagentClient {
     });
   }
   /**
-   * Execute a subagent task using Claude Code's Task tool
-   * This will spawn a new Claude instance with specific instructions
+   * Execute a subagent task.
+   * When multiProvider is enabled, routes cheap tasks to external providers.
+   * Falls back to Claude Code CLI path when disabled or for complex tasks.
    */
   async executeSubagent(request) {
     const startTime = Date.now();
@@ -39,6 +50,107 @@ class ClaudeCodeSubagentClient {
     if (this.mockMode) {
       return this.getMockResponse(request, startTime, subagentId);
     }
+    if (isFeatureEnabled("multiProvider")) {
+      const taskType = request.type;
+      const complexity = scoreComplexity(request.task, request.context);
+      const optimal = getOptimalProvider(taskType, void 0, {
+        task: request.task,
+        context: request.context
+      });
+      logger.debug("Complexity-based routing", {
+        subagentId,
+        taskType,
+        complexity: complexity.tier,
+        score: complexity.score,
+        signals: complexity.signals,
+        routed: optimal.provider
+      });
+      if (optimal.provider !== "anthropic" && optimal.provider !== "anthropic-batch") {
+        return this.executeDirectAPI(request, optimal, startTime, subagentId);
+      }
+      if (optimal.provider === "anthropic-batch") {
+        return this.executeBatch(request, startTime, subagentId);
+      }
+    }
+    return this.executeSubagentViaCLI(request, startTime, subagentId);
+  }
+  /**
+   * Execute via external provider (Cerebras, DeepInfra, etc.) using OpenAI-compatible API
+   */
+  async executeDirectAPI(request, optimal, startTime, subagentId) {
+    try {
+      const apiKey = process.env[optimal.apiKeyEnv] || "";
+      if (!apiKey) {
+        logger.warn(
+          `No API key for ${optimal.provider}, falling back to Claude`
+        );
+        return this.executeSubagentViaCLI(request, startTime, subagentId);
+      }
+      const adapter = createProvider(optimal.provider, {
+        apiKey,
+        baseUrl: optimal.baseUrl
+      });
+      const prompt = this.buildSubagentPrompt(request);
+      const result = await adapter.complete(
+        [{ role: "user", content: prompt }],
+        { model: optimal.model, maxTokens: 4096 }
+      );
+      const text = result.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = { rawOutput: text };
+      }
+      return {
+        success: true,
+        result: parsed,
+        output: text,
+        duration: Date.now() - startTime,
+        subagentType: request.type,
+        tokens: result.usage.inputTokens + result.usage.outputTokens
+      };
+    } catch (error) {
+      logger.warn(`Direct API failed for ${optimal.provider}, falling back`, {
+        error: error.message
+      });
+      return this.executeSubagentViaCLI(request, startTime, subagentId);
+    }
+  }
+  /**
+   * Execute via Anthropic Batch API (async, 50% discount)
+   */
+  async executeBatch(request, startTime, subagentId) {
+    try {
+      const batchClient = new AnthropicBatchClient();
+      const prompt = this.buildSubagentPrompt(request);
+      const batchReq = {
+        custom_id: subagentId,
+        params: {
+          model: "claude-sonnet-4-5-20250929",
+          max_tokens: 4096,
+          messages: [{ role: "user", content: prompt }]
+        }
+      };
+      const batchId = await batchClient.submit([batchReq], request.type);
+      return {
+        success: true,
+        result: { batchId, status: "submitted", custom_id: subagentId },
+        output: `Batch submitted: ${batchId}`,
+        duration: Date.now() - startTime,
+        subagentType: request.type
+      };
+    } catch (error) {
+      logger.warn("Batch submit failed, falling back to sync", {
+        error: error.message
+      });
+      return this.executeSubagentViaCLI(request, startTime, subagentId);
+    }
+  }
+  /**
+   * Original CLI-based subagent execution (unchanged behavior)
+   */
+  async executeSubagentViaCLI(request, startTime, subagentId) {
     try {
       const prompt = this.buildSubagentPrompt(request);
       const contextFile = path.join(this.tempDir, `${subagentId}-context.json`);
@@ -47,14 +159,19 @@ class ClaudeCodeSubagentClient {
         JSON.stringify(request.context, null, 2)
       );
       const resultFile = path.join(this.tempDir, `${subagentId}-result.json`);
-      const taskCommand = this.buildTaskCommand(request, prompt, contextFile, resultFile);
+      const taskCommand = this.buildTaskCommand(
+        request,
+        prompt,
+        contextFile,
+        resultFile
+      );
       const result = await this.executeTaskTool(taskCommand, request.timeout);
       let subagentResult = {};
       if (fs.existsSync(resultFile)) {
         const resultContent = await fs.promises.readFile(resultFile, "utf-8");
         try {
           subagentResult = JSON.parse(resultContent);
-        } catch (e) {
+        } catch {
           subagentResult = { rawOutput: resultContent };
         }
       }
@@ -68,7 +185,10 @@ class ClaudeCodeSubagentClient {
         tokens: this.estimateTokens(prompt + JSON.stringify(subagentResult))
       };
     } catch (error) {
-      logger.error(`Subagent execution failed: ${request.type}`, { error, subagentId });
+      logger.error(`Subagent CLI execution failed: ${request.type}`, {
+        error,
+        subagentId
+      });
       return {
         success: false,
         result: null,
@@ -224,7 +344,7 @@ class ClaudeCodeSubagentClient {
         
         Output the release plan and commands.`
     };
-    return request.systemPrompt || prompts[request.type] || prompts.planning;
+    return (request.systemPrompt || prompts[request.type] || prompts.planning) + STRUCTURED_RESPONSE_SUFFIX;
   }
   /**
    * Build Task tool command
@@ -292,7 +412,9 @@ echo '{"status": "completed", "type": "${request.type}"}' > "${resultFile}"
    * Get mock response for testing
    */
   async getMockResponse(request, startTime, subagentId) {
-    await new Promise((resolve) => setTimeout(resolve, Math.random() * 20 + 10));
+    await new Promise(
+      (resolve) => setTimeout(resolve, Math.random() * 20 + 10)
+    );
     const mockResponses = {
       planning: {
         tasks: [
@@ -357,10 +479,7 @@ function greetUser(name: string): string {
   }
   return \`Hello, \${name}!\`;
 }`,
-        changes_made: [
-          "Added JSDoc documentation",
-          "Improved error message"
-        ]
+        changes_made: ["Added JSDoc documentation", "Improved error message"]
       },
       context: {
         relevant_files: ["src/greet.ts", "test/greet.test.ts"],
@@ -415,7 +534,9 @@ function greetUser(name: string): string {
    */
   async mockTaskToolExecution(request) {
     const startTime = Date.now();
-    await new Promise((resolve) => setTimeout(resolve, 1e3 + Math.random() * 2e3));
+    await new Promise(
+      (resolve) => setTimeout(resolve, 1e3 + Math.random() * 2e3)
+    );
     const mockResponses = {
       planning: {
         tasks: [

package/dist/src/integrations/graphiti/client.js

@@ -0,0 +1,115 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { DEFAULT_GRAPHITI_CONFIG } from "./config.js";
+class GraphitiClientError extends Error {
+  constructor(message, code, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = "GraphitiClientError";
+  }
+}
+class GraphitiClient {
+  endpoint;
+  timeout;
+  maxRetries;
+  namespace;
+  constructor(config = {}) {
+    const merged = { ...DEFAULT_GRAPHITI_CONFIG, ...config };
+    this.endpoint = merged.endpoint.replace(/\/$/, "");
+    this.timeout = merged.timeoutMs;
+    this.maxRetries = merged.maxRetries;
+    this.namespace = merged.projectNamespace || "default";
+  }
+  async request(path, options = {}) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const res = await fetch(`${this.endpoint}${path}`, {
+          ...options,
+          signal: controller.signal,
+          headers: {
+            "Content-Type": "application/json",
+            ...options.headers || {}
+          }
+        });
+        clearTimeout(timeoutId);
+        if (!res.ok) {
+          const msg = await res.text().catch(() => res.statusText);
+          throw new GraphitiClientError(
+            `Request failed: ${msg}`,
+            "HTTP_ERROR",
+            res.status
+          );
+        }
+        return await res.json();
+      } catch (err) {
+        lastError = err;
+        if (err instanceof GraphitiClientError) throw err;
+        if (err.name === "AbortError") {
+          throw new GraphitiClientError("Request timeout", "TIMEOUT");
+        }
+        if (attempt < this.maxRetries) {
+          await new Promise((r) => setTimeout(r, Math.pow(2, attempt) * 100));
+          continue;
+        }
+      }
+    }
+    clearTimeout(timeoutId);
+    throw new GraphitiClientError(
+      lastError?.message || "Network error",
+      "NETWORK_ERROR"
+    );
+  }
+  // Episodes
+  async upsertEpisode(episode) {
+    const payload = { ...episode, namespace: this.namespace };
+    const res = await this.request(`/episodes`, {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+    return res;
+  }
+  // Entities
+  async upsertEntities(entities) {
+    const payload = { entities, namespace: this.namespace };
+    return this.request(`/entities:batchUpsert`, {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+  }
+  // Relations
+  async upsertRelations(edges) {
+    const payload = { edges, namespace: this.namespace };
+    return this.request(`/relations:batchUpsert`, {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+  }
+  // Temporal query + hybrid retrieval
+  async queryTemporal(query) {
+    const payload = { ...query, namespace: this.namespace };
+    return this.request(`/query/temporal`, {
+      method: "POST",
+      body: JSON.stringify(payload)
+    });
+  }
+  // Health/status
+  async getStatus() {
+    try {
+      return await this.request(
+        `/status?namespace=${encodeURIComponent(this.namespace)}`
+      );
+    } catch {
+      return { connected: false };
+    }
+  }
+}
+export {
+  GraphitiClient,
+  GraphitiClientError
+};

package/dist/src/integrations/graphiti/config.js

@@ -0,0 +1,17 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+const DEFAULT_GRAPHITI_CONFIG = {
+  enabled: !!process.env.GRAPHITI_ENDPOINT,
+  endpoint: process.env.GRAPHITI_ENDPOINT?.replace(/\/$/, "") || "http://localhost:8080",
+  backend: process.env.GRAPHITI_BACKEND || "neo4j",
+  projectNamespace: process.env.STACKMEMORY_PROJECT_ID || "default",
+  timeoutMs: 5e3,
+  maxRetries: 2,
+  maxTokens: 1600,
+  maxHops: 2
+};
+export {
+  DEFAULT_GRAPHITI_CONFIG
+};

package/dist/src/integrations/graphiti/types.js

@@ -0,0 +1,4 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);

package/dist/src/integrations/mcp/handlers/index.js

@@ -15,6 +15,9 @@ import {
 import {
   DiscoveryHandlers
 } from "./discovery-handlers.js";
+import {
+  ProviderHandlers
+} from "./provider-handlers.js";
 import {
   ContextHandlers as ContextHandlers2
 } from "./context-handlers.js";
@@ -23,11 +26,13 @@ import {
   LinearHandlers as LinearHandlers2
 } from "./linear-handlers.js";
 import { TraceHandlers as TraceHandlers2 } from "./trace-handlers.js";
+import { ProviderHandlers as ProviderHandlers2 } from "./provider-handlers.js";
 class MCPHandlerFactory {
   contextHandlers;
   taskHandlers;
   linearHandlers;
   traceHandlers;
+  providerHandlers;
   constructor(deps) {
     this.contextHandlers = new ContextHandlers2({
       frameManager: deps.frameManager
@@ -45,6 +50,7 @@ class MCPHandlerFactory {
       traceDetector: deps.traceDetector,
       browserMCP: deps.browserMCP
     });
+    this.providerHandlers = new ProviderHandlers2();
   }
   /**
    * Get handler for a specific tool
@@ -111,6 +117,19 @@ class MCPHandlerFactory {
         return this.traceHandlers.handleStopBrowserDebug.bind(
           this.traceHandlers
         );
+      // Provider handlers
+      case "delegate_to_model":
+        return this.providerHandlers.handleDelegateToModel.bind(
+          this.providerHandlers
+        );
+      case "batch_submit":
+        return this.providerHandlers.handleBatchSubmit.bind(
+          this.providerHandlers
+        );
+      case "batch_check":
+        return this.providerHandlers.handleBatchCheck.bind(
+          this.providerHandlers
+        );
       default:
         throw new Error(`Unknown tool: ${toolName}`);
     }
@@ -144,7 +163,11 @@ class MCPHandlerFactory {
       "start_browser_debug",
       "take_screenshot",
       "execute_script",
-      "stop_browser_debug"
+      "stop_browser_debug",
+      // Provider tools (conditionally active)
+      "delegate_to_model",
+      "batch_submit",
+      "batch_check"
     ];
   }
   /**
@@ -159,6 +182,7 @@ export {
   DiscoveryHandlers,
   LinearHandlers,
   MCPHandlerFactory,
+  ProviderHandlers,
   TaskHandlers,
   TraceHandlers
 };

package/dist/src/integrations/mcp/handlers/provider-handlers.js

@@ -0,0 +1,227 @@
+import { fileURLToPath as __fileURLToPath } from 'url';
+import { dirname as __pathDirname } from 'path';
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);
+import { logger } from "../../../core/monitoring/logger.js";
+import { isFeatureEnabled } from "../../../core/config/feature-flags.js";
+import {
+  createProvider
+} from "../../../core/extensions/provider-adapter.js";
+import {
+  getOptimalProvider
+} from "../../../core/models/model-router.js";
+import { scoreComplexity } from "../../../core/models/complexity-scorer.js";
+import {
+  AnthropicBatchClient
+} from "../../anthropic/batch-client.js";
+function errorResponse(err) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(err, null, 2) }]
+  };
+}
+function classifyApiError(error, provider) {
+  const msg = error.message || String(error);
+  const status = error.status || (msg.match(/(\d{3})/)?.[1] ? parseInt(msg.match(/(\d{3})/)[1]) : void 0);
+  if (status === 429) {
+    return {
+      errorType: "rate_limit",
+      message: msg,
+      recommendation: `Rate limited by ${provider}. Retry after a delay or switch to a different provider.`,
+      provider
+    };
+  }
+  if (status && status >= 500) {
+    return {
+      errorType: "server_error",
+      message: msg,
+      recommendation: `${provider} returned a server error. Try a different provider or retry later.`,
+      provider
+    };
+  }
+  return {
+    errorType: "api_error",
+    message: msg,
+    recommendation: `API call to ${provider} failed. Check the model name, API key, and base URL.`,
+    provider
+  };
+}
+class ProviderHandlers {
+  batchClient;
+  constructor(_deps) {
+  }
+  getBatchClient() {
+    if (!this.batchClient) {
+      this.batchClient = new AnthropicBatchClient();
+    }
+    return this.batchClient;
+  }
+  /**
+   * delegate_to_model — route a prompt to a specific provider+model
+   */
+  async handleDelegateToModel(args) {
+    if (!isFeatureEnabled("multiProvider")) {
+      return errorResponse({
+        errorType: "feature_disabled",
+        message: "Multi-provider routing is disabled.",
+        recommendation: "Set STACKMEMORY_MULTI_PROVIDER=true to enable multi-provider routing."
+      });
+    }
+    const taskType = args.taskType || "default";
+    const preference = args.provider;
+    const complexity = scoreComplexity(args.prompt);
+    const optimal = getOptimalProvider(taskType, preference, {
+      task: args.prompt
+    });
+    logger.info("delegate_to_model routing", {
+      taskType,
+      complexity: complexity.tier,
+      score: complexity.score,
+      provider: optimal.provider
+    });
+    const providerModel = args.model || optimal.model;
+    const apiKey = process.env[optimal.apiKeyEnv] || "";
+    if (!apiKey) {
+      return errorResponse({
+        errorType: "missing_api_key",
+        message: `No API key found for ${optimal.provider} (env: ${optimal.apiKeyEnv})`,
+        recommendation: `Set the ${optimal.apiKeyEnv} environment variable or choose a different provider.`,
+        provider: optimal.provider
+      });
+    }
+    try {
+      const adapter = createProvider(optimal.provider, {
+        apiKey,
+        baseUrl: optimal.baseUrl
+      });
+      const messages = [{ role: "user", content: args.prompt }];
+      const result = await adapter.complete(messages, {
+        model: providerModel,
+        maxTokens: args.maxTokens || 4096,
+        temperature: args.temperature,
+        system: args.system
+      });
+      const text = result.content.filter((c) => c.type === "text").map((c) => c.text).join("");
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                provider: optimal.provider,
+                model: providerModel,
+                response: text,
+                usage: result.usage
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (error) {
+      logger.error("delegate_to_model failed", { error: error.message });
+      return errorResponse(classifyApiError(error, optimal.provider));
+    }
+  }
+  /**
+   * batch_submit — submit prompts to Anthropic Batch API
+   */
+  async handleBatchSubmit(args) {
+    if (!isFeatureEnabled("multiProvider")) {
+      return errorResponse({
+        errorType: "feature_disabled",
+        message: "Multi-provider routing is disabled.",
+        recommendation: "Set STACKMEMORY_MULTI_PROVIDER=true to enable multi-provider routing."
+      });
+    }
+    try {
+      const batchClient = this.getBatchClient();
+      const requests = args.prompts.map((p) => ({
+        custom_id: p.id,
+        params: {
+          model: p.model || "claude-sonnet-4-5-20250929",
+          max_tokens: p.maxTokens || 4096,
+          messages: [{ role: "user", content: p.prompt }],
+          system: p.system
+        }
+      }));
+      const batchId = await batchClient.submit(requests, args.description);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                batchId,
+                status: "submitted",
+                requestCount: requests.length
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (error) {
+      return errorResponse({
+        errorType: "batch_error",
+        message: error.message,
+        recommendation: "Check ANTHROPIC_API_KEY and batch request format."
+      });
+    }
+  }
+  /**
+   * batch_check — poll status / retrieve results
+   */
+  async handleBatchCheck(args) {
+    if (!isFeatureEnabled("multiProvider")) {
+      return errorResponse({
+        errorType: "feature_disabled",
+        message: "Multi-provider routing is disabled.",
+        recommendation: "Set STACKMEMORY_MULTI_PROVIDER=true to enable multi-provider routing."
+      });
+    }
+    try {
+      const batchClient = this.getBatchClient();
+      const job = await batchClient.poll(args.batchId);
+      if (args.retrieve && job.processing_status === "ended") {
+        const results = await batchClient.retrieve(args.batchId);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ job, results }, null, 2)
+            }
+          ]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                batchId: args.batchId,
+                status: job.processing_status,
+                counts: job.request_counts,
+                createdAt: job.created_at,
+                endedAt: job.ended_at
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (error) {
+      return errorResponse({
+        errorType: "batch_error",
+        message: error.message,
+        recommendation: "Check the batchId is valid and ANTHROPIC_API_KEY is set."
+      });
+    }
+  }
+}
+export {
+  ProviderHandlers
+};