raysurfer 0.7.2 → 0.7.3

package/dist/index.js

@@ -0,0 +1,1282 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/errors.ts
+class RaySurferError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RaySurferError";
+  }
+}
+
+class APIError extends RaySurferError {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "APIError";
+    this.statusCode = statusCode;
+  }
+}
+
+class AuthenticationError extends RaySurferError {
+  constructor(message = "Invalid API key") {
+    super(message);
+    this.name = "AuthenticationError";
+  }
+}
+
+class CacheUnavailableError extends RaySurferError {
+  statusCode;
+  constructor(message = "Cache backend is unreachable", statusCode = 503) {
+    super(message);
+    this.name = "CacheUnavailableError";
+    this.statusCode = statusCode;
+  }
+}
+
+class RateLimitError extends RaySurferError {
+  retryAfter;
+  constructor(message = "Rate limit exceeded", retryAfter) {
+    super(message);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+}
+
+class ValidationError extends RaySurferError {
+  field;
+  constructor(message = "Validation failed", field) {
+    super(message);
+    this.name = "ValidationError";
+    this.field = field;
+  }
+}
+
+// src/client.ts
+var VERSION = "0.7.3";
+var DEFAULT_BASE_URL = "https://api.raysurfer.com";
+var MAX_RETRIES = 3;
+var RETRY_BASE_DELAY = 500;
+var RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);
+function normalizeDependencies(rawDeps) {
+  if (!rawDeps)
+    return {};
+  if (Array.isArray(rawDeps)) {
+    const result = {};
+    for (const pkg of rawDeps) {
+      result[pkg] = "";
+    }
+    return result;
+  }
+  return rawDeps;
+}
+
+class RaySurfer {
+  apiKey;
+  baseUrl;
+  timeout;
+  organizationId;
+  workspaceId;
+  snipsDesired;
+  publicSnips;
+  registeredTools;
+  constructor(options = {}) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = options.timeout ?? 60000;
+    this.organizationId = options.organizationId;
+    this.workspaceId = options.workspaceId;
+    this.snipsDesired = options.snipsDesired;
+    this.publicSnips = options.publicSnips;
+    this.registeredTools = new Map;
+  }
+  async request(method, path, body, headersOverride) {
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    if (this.organizationId) {
+      headers["X-Raysurfer-Org-Id"] = this.organizationId;
+    }
+    if (this.workspaceId) {
+      headers["X-Raysurfer-Workspace-Id"] = this.workspaceId;
+    }
+    if (this.snipsDesired) {
+      headers["X-Raysurfer-Snips-Desired"] = this.snipsDesired;
+    }
+    if (this.publicSnips) {
+      headers["X-Raysurfer-Public-Snips"] = "true";
+    }
+    headers["X-Raysurfer-SDK-Version"] = `typescript/${VERSION}`;
+    if (headersOverride) {
+      Object.assign(headers, headersOverride);
+    }
+    let lastError;
+    for (let attempt = 0;attempt <= MAX_RETRIES; attempt++) {
+      const controller = new AbortController;
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+          method,
+          headers,
+          body: body ? JSON.stringify(body) : undefined,
+          signal: controller.signal
+        });
+        if (response.status === 401) {
+          throw new AuthenticationError;
+        }
+        if (RETRYABLE_STATUS_CODES.has(response.status)) {
+          const text = await response.text();
+          if (response.status === 429) {
+            const retryAfterHeader = response.headers.get("Retry-After");
+            const retryAfterMs = retryAfterHeader ? parseFloat(retryAfterHeader) * 1000 : RETRY_BASE_DELAY * 2 ** attempt;
+            if (attempt < MAX_RETRIES) {
+              await new Promise((resolve) => setTimeout(resolve, retryAfterMs));
+              continue;
+            }
+            throw new RateLimitError(text, retryAfterHeader ? parseFloat(retryAfterHeader) : undefined);
+          }
+          if (attempt < MAX_RETRIES) {
+            const delay = RETRY_BASE_DELAY * 2 ** attempt;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+          throw new CacheUnavailableError(text, response.status);
+        }
+        if (!response.ok) {
+          const text = await response.text();
+          throw new APIError(text, response.status);
+        }
+        return await response.json();
+      } catch (error) {
+        if (error instanceof TypeError && attempt < MAX_RETRIES) {
+          lastError = error;
+          const delay = RETRY_BASE_DELAY * 2 ** attempt;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+        throw error;
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+    throw lastError ?? new APIError("Request failed after retries");
+  }
+  workspaceHeaders(workspaceId) {
+    if (!workspaceId)
+      return;
+    return { "X-Raysurfer-Workspace-Id": workspaceId };
+  }
+  async storeCodeBlock(params) {
+    const data = {
+      name: params.name,
+      description: params.description ?? "",
+      source: params.source,
+      entrypoint: params.entrypoint,
+      language: params.language,
+      input_schema: params.inputSchema ?? {},
+      output_schema: params.outputSchema ?? {},
+      language_version: params.languageVersion ?? null,
+      dependencies: params.dependencies ?? {},
+      tags: params.tags ?? [],
+      capabilities: params.capabilities ?? [],
+      example_queries: params.exampleQueries ?? null
+    };
+    const result = await this.request("POST", "/api/store/code-block", data);
+    return {
+      success: result.success,
+      codeBlockId: result.code_block_id,
+      embeddingId: result.embedding_id,
+      message: result.message
+    };
+  }
+  async storeExecution(params) {
+    const io = {
+      input_data: params.inputData,
+      input_hash: "",
+      output_data: params.outputData,
+      output_hash: "",
+      output_type: typeof params.outputData
+    };
+    const data = {
+      code_block_id: params.codeBlockId,
+      triggering_task: params.triggeringTask,
+      io,
+      execution_state: params.executionState ?? "completed",
+      duration_ms: params.durationMs ?? 0,
+      error_message: params.errorMessage ?? null,
+      error_type: params.errorType ?? null,
+      verdict: params.verdict ?? null,
+      review: params.review ?? null
+    };
+    const result = await this.request("POST", "/api/store/execution", data);
+    return {
+      success: result.success,
+      executionId: result.execution_id,
+      patternUpdated: result.pattern_updated,
+      message: result.message
+    };
+  }
+  async uploadNewCodeSnip(taskOrOptions, fileWritten, succeeded, cachedCodeBlocks, useRaysurferAiVoting = true, userVote, executionLogs, runUrl, workspaceId, dependencies, voteSource, voteCount) {
+    let opts;
+    if (typeof taskOrOptions === "object") {
+      opts = taskOrOptions;
+    } else {
+      opts = {
+        task: taskOrOptions,
+        fileWritten,
+        succeeded,
+        cachedCodeBlocks,
+        useRaysurferAiVoting,
+        userVote,
+        executionLogs,
+        runUrl,
+        workspaceId,
+        dependencies,
+        voteSource,
+        voteCount
+      };
+    }
+    if (opts.fileWritten && opts.filesWritten) {
+      throw new Error("Provide either fileWritten or filesWritten, not both.");
+    }
+    const effectiveVoting = opts.autoVote ?? opts.useRaysurferAiVoting ?? true;
+    const normalizedFiles = [];
+    if (opts.fileWritten) {
+      normalizedFiles.push(opts.fileWritten);
+    } else if (opts.filesWritten) {
+      normalizedFiles.push(...opts.filesWritten);
+    }
+    if (normalizedFiles.length === 0) {
+      throw new Error("Missing required file input: provide fileWritten or filesWritten.");
+    }
+    if (normalizedFiles.length > 1) {
+      const responses = [];
+      for (const compatFile of normalizedFiles) {
+        responses.push(await this.uploadNewCodeSnip({
+          ...opts,
+          fileWritten: compatFile,
+          filesWritten: undefined,
+          useRaysurferAiVoting: effectiveVoting,
+          autoVote: undefined
+        }));
+      }
+      return {
+        success: responses.every((response) => response.success),
+        codeBlocksStored: responses.reduce((sum, response) => sum + response.codeBlocksStored, 0),
+        message: `Uploaded ${normalizedFiles.length} files via compatibility path.`
+      };
+    }
+    const [resolvedFile] = normalizedFiles;
+    const data = {
+      task: opts.task,
+      file_written: resolvedFile,
+      succeeded: opts.succeeded,
+      use_raysurfer_ai_voting: effectiveVoting,
+      user_vote: opts.userVote,
+      execution_logs: opts.executionLogs,
+      cached_code_blocks: opts.cachedCodeBlocks && opts.cachedCodeBlocks.length > 0 ? opts.cachedCodeBlocks.map((cb) => ({
+        code_block_id: cb.codeBlockId,
+        filename: cb.filename,
+        description: cb.description
+      })) : undefined,
+      run_url: opts.runUrl,
+      dependencies: opts.dependencies,
+      public: opts.public || undefined,
+      vote_source: opts.voteSource,
+      vote_count: opts.voteCount
+    };
+    const result = await this.request("POST", "/api/store/execution-result", data, this.workspaceHeaders(opts.workspaceId));
+    return {
+      success: result.success,
+      codeBlocksStored: result.code_blocks_stored,
+      message: result.message,
+      snippetName: result.snippet_name ?? null
+    };
+  }
+  uploadNewCodeSnips = this.uploadNewCodeSnip.bind(this);
+  async uploadBulkCodeSnips(promptsOrOptions, filesWritten, logFiles, useRaysurferAiVoting = true, userVotes, workspaceId, voteSource, voteCount) {
+    let opts;
+    if (!Array.isArray(promptsOrOptions)) {
+      opts = promptsOrOptions;
+    } else {
+      opts = {
+        prompts: promptsOrOptions,
+        filesWritten,
+        logFiles,
+        useRaysurferAiVoting,
+        userVotes,
+        workspaceId,
+        voteSource,
+        voteCount
+      };
+    }
+    const normalizedLogs = opts.logFiles?.map((log) => {
+      const content = typeof log.content === "string" ? log.content : Buffer.from(log.content).toString("base64");
+      const encoding = typeof log.content === "string" ? log.encoding ?? "utf-8" : "base64";
+      return {
+        path: log.path,
+        content,
+        encoding,
+        content_type: log.contentType
+      };
+    }) ?? [];
+    const data = {
+      prompts: opts.prompts,
+      files_written: opts.filesWritten,
+      log_files: normalizedLogs.length > 0 ? normalizedLogs : undefined,
+      use_raysurfer_ai_voting: opts.useRaysurferAiVoting ?? true,
+      user_votes: opts.userVotes,
+      vote_source: opts.voteSource,
+      vote_count: opts.voteCount
+    };
+    const result = await this.request("POST", "/api/store/bulk-execution-result", data, this.workspaceHeaders(opts.workspaceId));
+    return {
+      success: result.success,
+      codeBlocksStored: result.code_blocks_stored,
+      votesQueued: result.votes_queued,
+      message: result.message,
+      statusUrl: result.status_url ?? null
+    };
+  }
+  async search(params) {
+    const data = {
+      task: params.task,
+      top_k: params.topK ?? 5,
+      min_verdict_score: params.minVerdictScore ?? 0.3,
+      prefer_complete: params.preferComplete ?? false,
+      input_schema: params.inputSchema ?? null
+    };
+    const result = await this.request("POST", "/api/retrieve/search", data, this.workspaceHeaders(params.workspaceId));
+    return {
+      matches: result.matches.map((m) => {
+        const vectorScore = m.vector_score ?? m.score;
+        const verdictScore = m.verdict_score ?? m.score;
+        return {
+          codeBlock: this.parseCodeBlock(m.code_block),
+          score: m.score,
+          combinedScore: m.score,
+          vectorScore,
+          verdictScore,
+          thumbsUp: m.thumbs_up,
+          thumbsDown: m.thumbs_down,
+          filename: m.filename,
+          language: m.language,
+          entrypoint: m.entrypoint,
+          dependencies: normalizeDependencies(m.dependencies),
+          comments: m.comments ?? []
+        };
+      }),
+      totalFound: result.total_found,
+      cacheHit: result.cache_hit
+    };
+  }
+  async getCodeSnips(params) {
+    const response = await this.search({
+      task: params.task,
+      topK: params.topK ?? 10,
+      minVerdictScore: params.minVerdictScore ?? 0
+    });
+    return {
+      codeBlocks: response.matches.map((m) => ({
+        codeBlock: m.codeBlock,
+        score: m.score,
+        thumbsUp: m.thumbsUp,
+        thumbsDown: m.thumbsDown,
+        recentExecutions: []
+      })),
+      totalFound: response.totalFound
+    };
+  }
+  async retrieveBest(params) {
+    const response = await this.search({
+      task: params.task,
+      topK: params.topK ?? 10,
+      minVerdictScore: params.minVerdictScore ?? 0
+    });
+    let bestMatch = null;
+    let bestScore = 0;
+    const first = response.matches[0];
+    if (first) {
+      bestMatch = {
+        codeBlock: first.codeBlock,
+        score: first.score,
+        thumbsUp: first.thumbsUp,
+        thumbsDown: first.thumbsDown
+      };
+      bestScore = first.score;
+    }
+    const alternativeCandidates = response.matches.slice(1, 4).map((m) => ({
+      codeBlockId: m.codeBlock.id,
+      name: m.codeBlock.name,
+      score: m.score,
+      reason: m.thumbsUp > 0 ? `${m.thumbsUp} thumbs up, ${m.thumbsDown} thumbs down` : "No execution history"
+    }));
+    return {
+      bestMatch,
+      alternativeCandidates,
+      retrievalConfidence: bestMatch ? String(bestScore.toFixed(4)) : "0"
+    };
+  }
+  async getFewShotExamples(task, k = 3) {
+    const data = { task, k };
+    const result = await this.request("POST", "/api/retrieve/few-shot-examples", data);
+    return result.examples.map((ex) => ({
+      task: ex.task,
+      inputSample: ex.input_sample,
+      outputSample: ex.output_sample,
+      codeSnippet: ex.code_snippet
+    }));
+  }
+  async getTaskPatterns(params) {
+    const data = {
+      task: params.task ?? null,
+      code_block_id: params.codeBlockId ?? null,
+      min_thumbs_up: params.minThumbsUp ?? 0,
+      top_k: params.topK ?? 20
+    };
+    const result = await this.request("POST", "/api/retrieve/task-patterns", data);
+    return result.patterns.map((p) => ({
+      taskPattern: p.task_pattern,
+      codeBlockId: p.code_block_id,
+      codeBlockName: p.code_block_name,
+      thumbsUp: p.thumbs_up,
+      thumbsDown: p.thumbs_down,
+      lastThumbsUp: p.last_thumbs_up,
+      lastThumbsDown: p.last_thumbs_down
+    }));
+  }
+  async getCodeFiles(params) {
+    const response = await this.search({
+      task: params.task,
+      topK: params.topK ?? 5,
+      minVerdictScore: params.minVerdictScore ?? 0.3,
+      preferComplete: params.preferComplete ?? true
+    });
+    const files = response.matches.map((m) => ({
+      codeBlockId: m.codeBlock.id,
+      filename: m.filename,
+      source: m.codeBlock.source,
+      entrypoint: m.entrypoint,
+      description: m.codeBlock.description,
+      inputSchema: m.codeBlock.inputSchema,
+      outputSchema: m.codeBlock.outputSchema,
+      language: m.language,
+      dependencies: m.dependencies,
+      score: m.score,
+      thumbsUp: m.thumbsUp,
+      thumbsDown: m.thumbsDown
+    }));
+    const addToLlmPrompt = this.formatLlmPrompt(files, params.cacheDir ?? ".raysurfer_code");
+    return {
+      files,
+      task: params.task,
+      totalFound: response.totalFound,
+      addToLlmPrompt
+    };
+  }
+  formatLlmPrompt(files, cacheDir) {
+    if (files.length === 0)
+      return "";
+    const lines = [
+      `
+
+## IMPORTANT: Pre-validated Code Files Available
+`,
+      "The following validated code has been retrieved from the cache. " + `Use these files directly instead of regenerating code.
+`
+    ];
+    for (const f of files) {
+      if (cacheDir) {
+        const fullPath = `${cacheDir}/${f.filename}`;
+        lines.push(`
+### \`${f.filename}\` → \`${fullPath}\``);
+      } else {
+        lines.push(`
+### \`${f.filename}\``);
+      }
+      lines.push(`- **Description**: ${f.description}`);
+      lines.push(`- **Language**: ${f.language}`);
+      lines.push(`- **Entrypoint**: \`${f.entrypoint}\``);
+      lines.push(`- **Confidence**: ${Math.round(f.score * 100)}%`);
+      const deps = Object.entries(f.dependencies);
+      if (deps.length > 0) {
+        lines.push(`- **Dependencies**: ${deps.map(([k, v]) => `${k}@${v}`).join(", ")}`);
+      }
+    }
+    lines.push(`
+
+**Instructions**:`);
+    lines.push("1. Read the cached file(s) before writing new code");
+    lines.push("2. Use the cached code as your starting point");
+    lines.push("3. Only modify if the task requires specific changes");
+    lines.push(`4. Do not regenerate code that already exists
+`);
+    return lines.join(`
+`);
+  }
+  async autoReview(params) {
+    const response = await this.request("POST", "/api/store/auto-review", {
+      execution_id: params.executionId,
+      triggering_task: params.triggeringTask,
+      execution_state: params.executionState,
+      input_data: params.inputData,
+      output_data: params.outputData,
+      code_block_name: params.codeBlockName,
+      code_block_description: params.codeBlockDescription,
+      error_message: params.errorMessage
+    });
+    return {
+      success: response.success,
+      executionId: response.execution_id,
+      review: {
+        timestamp: response.review.timestamp,
+        verdict: response.review.verdict,
+        reasoning: response.review.reasoning,
+        whatWorked: response.review.what_worked,
+        whatDidntWork: response.review.what_didnt_work,
+        outputWasUseful: response.review.output_was_useful,
+        outputWasCorrect: response.review.output_was_correct,
+        outputWasComplete: response.review.output_was_complete,
+        errorWasAppropriate: response.review.error_was_appropriate,
+        wouldUseAgain: response.review.would_use_again,
+        suggestedImprovements: response.review.suggested_improvements,
+        requiredWorkaround: response.review.required_workaround,
+        workaroundDescription: response.review.workaround_description
+      },
+      message: response.message
+    };
+  }
+  async getExecutions(params = {}) {
+    const response = await this.request("POST", "/api/retrieve/executions", {
+      code_block_id: params.codeBlockId,
+      task: params.task,
+      verdict: params.verdict,
+      limit: params.limit ?? 20
+    });
+    return {
+      executions: response.executions.map((exec) => ({
+        id: exec.id,
+        codeBlockId: exec.code_block_id,
+        timestamp: exec.timestamp,
+        executionState: exec.execution_state,
+        durationMs: exec.duration_ms,
+        errorMessage: exec.error_message,
+        errorType: exec.error_type,
+        io: {
+          inputData: exec.io.input_data,
+          inputHash: exec.io.input_hash,
+          outputData: exec.io.output_data,
+          outputHash: exec.io.output_hash,
+          outputType: exec.io.output_type
+        },
+        triggeringTask: exec.triggering_task,
+        retrievalScore: exec.retrieval_score,
+        verdict: exec.verdict,
+        review: exec.review ? {
+          timestamp: exec.review.timestamp,
+          verdict: exec.review.verdict,
+          reasoning: exec.review.reasoning,
+          whatWorked: exec.review.what_worked,
+          whatDidntWork: exec.review.what_didnt_work,
+          outputWasUseful: exec.review.output_was_useful,
+          outputWasCorrect: exec.review.output_was_correct,
+          outputWasComplete: exec.review.output_was_complete,
+          errorWasAppropriate: exec.review.error_was_appropriate,
+          wouldUseAgain: exec.review.would_use_again,
+          suggestedImprovements: exec.review.suggested_improvements,
+          requiredWorkaround: exec.review.required_workaround,
+          workaroundDescription: exec.review.workaround_description
+        } : null
+      })),
+      totalFound: response.total_found
+    };
+  }
+  async voteCodeSnip(params) {
+    const data = {
+      task: params.task,
+      code_block_id: params.codeBlockId,
+      code_block_name: params.codeBlockName,
+      code_block_description: params.codeBlockDescription,
+      succeeded: params.succeeded
+    };
+    const result = await this.request("POST", "/api/store/cache-usage", data);
+    return {
+      success: result.success,
+      votePending: result.vote_pending,
+      message: result.message
+    };
+  }
+  async browsePublic(params = {}) {
+    const data = {
+      limit: params.limit ?? 20,
+      offset: params.offset ?? 0,
+      sort_by: params.sortBy ?? "upvoted",
+      language: params.language
+    };
+    const result = await this.request("POST", "/api/snippets/public/list", data);
+    return {
+      snippets: result.snippets.map((s) => ({
+        id: s.id,
+        name: s.name,
+        description: s.description,
+        source: s.source,
+        language: s.language,
+        entrypoint: s.entrypoint,
+        thumbsUp: s.thumbs_up,
+        thumbsDown: s.thumbs_down,
+        createdAt: s.created_at,
+        namespace: s.namespace
+      })),
+      total: result.total,
+      hasMore: result.has_more
+    };
+  }
+  async searchPublic(params) {
+    const data = {
+      query: params.query,
+      limit: params.limit ?? 20,
+      language: params.language
+    };
+    const result = await this.request("POST", "/api/snippets/public/search", data);
+    return {
+      snippets: result.snippets.map((s) => ({
+        id: s.id,
+        name: s.name,
+        description: s.description,
+        source: s.source,
+        language: s.language,
+        entrypoint: s.entrypoint,
+        thumbsUp: s.thumbs_up,
+        thumbsDown: s.thumbs_down,
+        createdAt: s.created_at,
+        namespace: s.namespace
+      })),
+      total: result.total,
+      query: result.query
+    };
+  }
+  tool(name, description, parameters, callback) {
+    this.registeredTools.set(name, {
+      definition: { name, description, parameters },
+      callback
+    });
+  }
+  async execute(task, options) {
+    const timeout = options?.timeout ?? 300000;
+    const forceRegenerate = options?.forceRegenerate ?? false;
+    const sessionId = crypto.randomUUID();
+    const wsUrl = `${this.baseUrl.replace(/^http/, "ws")}/api/execute/ws/${sessionId}`;
+    const toolCalls = [];
+    const ws = new WebSocket(wsUrl);
+    const wsReady = new Promise((resolve, reject) => {
+      ws.addEventListener("open", () => resolve());
+      ws.addEventListener("error", (ev) => reject(new Error(`WebSocket connection failed: ${String(ev)}`)));
+    });
+    ws.addEventListener("message", async (event) => {
+      const raw = typeof event.data === "string" ? event.data : String(event.data);
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      if (msg.type === "tool_call" && msg.request_id && msg.tool_name) {
+        const start = Date.now();
+        const registered = this.registeredTools.get(msg.tool_name);
+        const record = {
+          toolName: msg.tool_name,
+          arguments: msg.arguments ?? {},
+          result: null,
+          error: null,
+          durationMs: 0
+        };
+        try {
+          if (!registered) {
+            throw new Error(`Unknown tool: ${msg.tool_name}`);
+          }
+          const callbackResult = registered.callback(msg.arguments ?? {});
+          const result = callbackResult instanceof Promise ? await callbackResult : callbackResult;
+          record.result = result;
+          record.durationMs = Date.now() - start;
+          ws.send(JSON.stringify({
+            type: "tool_result",
+            request_id: msg.request_id,
+            result
+          }));
+        } catch (err) {
+          const errorMsg = err instanceof Error ? err.message : String(err);
+          record.error = errorMsg;
+          record.durationMs = Date.now() - start;
+          ws.send(JSON.stringify({
+            type: "tool_result",
+            request_id: msg.request_id,
+            result: `Error: ${errorMsg}`
+          }));
+        }
+        toolCalls.push(record);
+      }
+    });
+    await wsReady;
+    const tools = Array.from(this.registeredTools.values()).map((t) => t.definition);
+    const response = await this.request("POST", "/api/execute/run", {
+      task,
+      tools,
+      session_id: sessionId,
+      timeout_seconds: timeout / 1000,
+      force_regenerate: forceRegenerate
+    });
+    ws.close();
+    const serverToolCalls = (response.tool_calls ?? []).map((tc) => ({
+      toolName: tc.tool_name,
+      arguments: tc.arguments,
+      result: tc.result,
+      error: tc.error,
+      durationMs: tc.duration_ms
+    }));
+    return {
+      executionId: response.execution_id,
+      result: response.result,
+      exitCode: response.exit_code,
+      durationMs: response.duration_ms,
+      cacheHit: response.cache_hit,
+      codeBlockId: response.code_block_id,
+      error: response.error,
+      toolCalls: serverToolCalls.length > 0 ? serverToolCalls : toolCalls
+    };
+  }
+  async submitExecutionResult(task, fileWritten, succeeded) {
+    return this.uploadNewCodeSnip(task, fileWritten, succeeded);
+  }
+  async retrieve(params) {
+    return this.getCodeSnips(params);
+  }
+  parseCodeBlock(data) {
+    return {
+      id: data.id,
+      name: data.name,
+      description: data.description,
+      source: data.source,
+      entrypoint: data.entrypoint,
+      inputSchema: data.input_schema ?? {},
+      outputSchema: data.output_schema ?? {},
+      language: data.language,
+      languageVersion: data.language_version ?? null,
+      dependencies: normalizeDependencies(data.dependencies),
+      tags: data.tags ?? [],
+      capabilities: data.capabilities ?? [],
+      exampleQueries: data.example_queries ?? null,
+      createdAt: data.created_at ?? null,
+      updatedAt: data.updated_at ?? null
+    };
+  }
+}
+var client_default = RaySurfer;
+// src/sdk-client.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+var DEFAULT_RAYSURFER_URL = "https://api.raysurfer.com";
+var CACHE_DIR = ".raysurfer_code";
+var FILE_MODIFY_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
+var TRACKABLE_EXTENSIONS = new Set([
+  ".py",
+  ".js",
+  ".ts",
+  ".rb",
+  ".go",
+  ".rs",
+  ".java",
+  ".cpp",
+  ".c",
+  ".h",
+  ".pdf",
+  ".docx",
+  ".xlsx",
+  ".csv",
+  ".json",
+  ".yaml",
+  ".yml",
+  ".xml",
+  ".html",
+  ".css",
+  ".md",
+  ".txt",
+  ".sh",
+  ".sql"
+]);
+var BASH_OUTPUT_PATTERNS = [
+  />>\s*([^\s;&|]+)/g,
+  />\s*([^\s;&|]+)/g,
+  /-o\s+([^\s;&|]+)/g,
+  /--output[=\s]+([^\s;&|]+)/g,
+  /savefig\(['"]([^'"]+)['"]\)/g,
+  /to_csv\(['"]([^'"]+)['"]\)/g,
+  /to_excel\(['"]([^'"]+)['"]\)/g,
+  /write\(['"]([^'"]+)['"]\)/g
+];
+var createDebugLogger = (enabled) => ({
+  log: (...args) => enabled && console.log("[raysurfer]", ...args),
+  time: (label) => enabled && console.time(`[raysurfer] ${label}`),
+  timeEnd: (label) => enabled && console.timeEnd(`[raysurfer] ${label}`),
+  table: (data) => enabled && console.table(data),
+  group: (label) => enabled && console.group(`[raysurfer] ${label}`),
+  groupEnd: () => enabled && console.groupEnd()
+});
+function augmentSystemPrompt(systemPrompt, addition) {
+  if (!addition)
+    return systemPrompt;
+  if (typeof systemPrompt === "string")
+    return systemPrompt + addition;
+  if (systemPrompt?.type === "preset") {
+    return { ...systemPrompt, append: (systemPrompt.append ?? "") + addition };
+  }
+  return addition;
+}
+function splitOptions(options) {
+  const { workspaceId, publicSnips, debug, workingDirectory, ...sdkOptions } = options;
+  return {
+    sdkOptions,
+    extras: {
+      workspaceId,
+      publicSnips,
+      debug,
+      workingDirectory
+    }
+  };
+}
+
+class RaysurferQuery {
+  _inner = null;
+  _initPromise = null;
+  _raysurfer = null;
+  _cachedFiles = [];
+  _modifiedFilePaths = new Set;
+  _bashGeneratedFiles = new Set;
+  _executionLogs = [];
+  _taskSucceeded = false;
+  _generatedCodeBlocks = [];
+  _cacheUploadDone = false;
+  _messageCount = 0;
+  _startTime = 0;
+  _promptText;
+  _params;
+  _debug;
+  _cacheEnabled;
+  _workDir;
+  _apiKey;
+  _baseUrl;
+  _extras;
+  _sdkOptions;
+  constructor(params) {
+    this._params = params;
+    const options = params.options ?? {};
+    const { sdkOptions, extras } = splitOptions(options);
+    this._sdkOptions = sdkOptions;
+    this._extras = extras;
+    this._promptText = typeof params.prompt === "string" ? params.prompt : null;
+    const debugEnabled = extras.debug || process.env.RAYSURFER_DEBUG === "true";
+    this._debug = createDebugLogger(debugEnabled);
+    this._apiKey = process.env.RAYSURFER_API_KEY;
+    this._baseUrl = process.env.RAYSURFER_BASE_URL || DEFAULT_RAYSURFER_URL;
+    this._cacheEnabled = !!this._apiKey;
+    if (extras.workingDirectory && !sdkOptions.cwd) {
+      console.warn("[raysurfer] workingDirectory is deprecated, use cwd instead");
+      this._sdkOptions.cwd = extras.workingDirectory;
+    }
+    this._workDir = this._sdkOptions.cwd || process.cwd();
+  }
+  async _initialize() {
+    this._debug.group("Raysurfer Query Started");
+    this._debug.log("Prompt:", this._promptText ?? "<stream>");
+    this._debug.log("Cache enabled:", this._cacheEnabled);
+    this._debug.log("Base URL:", this._baseUrl);
+    if (!this._cacheEnabled) {
+      console.warn("[raysurfer] RAYSURFER_API_KEY not set - caching disabled");
+    }
+    let addToLlmPrompt = "";
+    if (this._cacheEnabled && this._promptText) {
+      this._raysurfer = new RaySurfer({
+        apiKey: this._apiKey,
+        baseUrl: this._baseUrl,
+        workspaceId: this._extras.workspaceId,
+        snipsDesired: this._extras.workspaceId ? "client" : undefined,
+        publicSnips: this._extras.publicSnips
+      });
+      try {
+        this._debug.time("Cache lookup");
+        const cacheDir = join(this._workDir, CACHE_DIR);
+        const response = await this._raysurfer.getCodeFiles({
+          task: this._promptText,
+          topK: 5,
+          minVerdictScore: 0.3,
+          preferComplete: true,
+          cacheDir
+        });
+        this._debug.timeEnd("Cache lookup");
+        this._cachedFiles = response.files;
+        addToLlmPrompt = response.addToLlmPrompt;
+        this._debug.log(`Found ${this._cachedFiles.length} cached files:`);
+        console.log("[raysurfer] Cache hit:", this._cachedFiles.length, "snippets retrieved");
+        if (this._cachedFiles.length > 0) {
+          this._debug.table(this._cachedFiles.map((f) => ({
+            filename: f.filename,
+            score: `${Math.round(f.score * 100)}%`,
+            thumbs: `${f.thumbsUp}/${f.thumbsDown}`,
+            sourceLength: `${f.source.length} chars`
+          })));
+          try {
+            mkdirSync(cacheDir, { recursive: true });
+            for (const file of this._cachedFiles) {
+              const filePath = join(cacheDir, file.filename);
+              writeFileSync(filePath, file.source, "utf-8");
+              this._debug.log(`  → Wrote cached file: ${filePath}`);
+              this._modifiedFilePaths.add(filePath);
+            }
+          } catch (writeErr) {
+            this._debug.log("Failed to write cached files:", writeErr instanceof Error ? writeErr : String(writeErr));
+          }
+        }
+      } catch (error) {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        this._debug.log("Cache lookup failed:", errMsg);
+        console.warn("[raysurfer] Cache unavailable:", errMsg);
+      }
+    }
+    const augmented = augmentSystemPrompt(this._sdkOptions.systemPrompt, addToLlmPrompt);
+    const augmentedOptions = {
+      ...this._sdkOptions,
+      systemPrompt: augmented
+    };
+    this._debug.log("Augmented prompt addition:", addToLlmPrompt.length, "chars");
+    let sdkQueryFn;
+    try {
+      const sdk = await import("@anthropic-ai/claude-agent-sdk");
+      sdkQueryFn = sdk.query;
+    } catch {
+      throw new Error("Could not import @anthropic-ai/claude-agent-sdk. Install it with: npm install @anthropic-ai/claude-agent-sdk");
+    }
+    this._debug.time("Claude API call");
+    this._debug.log("Calling Claude Agent SDK...");
+    this._startTime = Date.now();
+    this._inner = sdkQueryFn({
+      prompt: this._params.prompt,
+      options: augmentedOptions
+    });
+  }
+  async _ensureInit() {
+    if (!this._inner) {
+      if (!this._initPromise) {
+        this._initPromise = this._initialize();
+      }
+      await this._initPromise;
+    }
+    return this._inner;
+  }
+  _extractBashOutputFiles(command) {
+    for (const pattern of BASH_OUTPUT_PATTERNS) {
+      pattern.lastIndex = 0;
+      let match = pattern.exec(command);
+      while (match !== null) {
+        const filePath = match[1];
+        if (filePath && filePath.length > 0) {
+          const ext = filePath.substring(filePath.lastIndexOf(".")).toLowerCase();
+          if (TRACKABLE_EXTENSIONS.has(ext)) {
+            this._bashGeneratedFiles.add(filePath);
+            this._debug.log(`  → Bash output file detected: ${filePath}`);
+          }
+        }
+        match = pattern.exec(command);
+      }
+    }
+  }
+  _trackMessage(message) {
+    this._messageCount++;
+    const msg = message;
+    const elapsed = Date.now() - this._startTime;
+    this._debug.log(`
+═══════════════════════════════════════════════════`);
+    this._debug.log(`Message #${this._messageCount} [${elapsed}ms] type=${msg.type} subtype=${msg.subtype ?? "none"}`);
+    this._debug.log(`═══════════════════════════════════════════════════`);
+    this._debug.log(JSON.stringify(msg, null, 2));
+    if (msg.type === "assistant" && msg.message?.content) {
+      const blocks = msg.message.content;
+      for (const block of blocks) {
+        if (block.type === "tool_use" && block.name && FILE_MODIFY_TOOLS.includes(block.name)) {
+          const filePath = block.input?.file_path ?? block.input?.notebook_path;
+          if (filePath) {
+            this._debug.log(`  → ${block.name} tool detected:`, filePath);
+            this._modifiedFilePaths.add(filePath);
+          }
+        }
+        if (block.type === "tool_use" && block.name === "Bash") {
+          const command = block.input?.command;
+          if (command) {
+            this._extractBashOutputFiles(command);
+          }
+        }
+        if (block.type === "tool_result" && block.content) {
+          this._executionLogs.push(block.content.slice(0, 5000));
+        }
+        if (block.type === "text" && block.text) {
+          const codeMatches = block.text.match(/```(?:typescript|javascript|ts|js)?\n?([\s\S]*?)\n?```/g);
+          if (codeMatches) {
+            for (const match of codeMatches) {
+              const code = match.replace(/```(?:typescript|javascript|ts|js)?\n?/, "").replace(/\n?```$/, "");
+              if (code.trim().length > 50) {
+                this._generatedCodeBlocks.push(code.trim());
+                this._debug.log(`  → Extracted code block (${code.length} chars)`);
+              }
+            }
+          }
+        }
+      }
+    }
+    if (msg.type === "result" && msg.subtype === "success") {
+      this._taskSucceeded = true;
+      this._debug.timeEnd("Claude API call");
+      this._debug.log("Task succeeded!");
+      this._debug.log("  Duration:", msg.duration_ms, "ms");
+      this._debug.log("  Total cost:", msg.total_cost_usd, "USD");
+      this._debug.log("  Turns:", msg.num_turns);
+    }
+    if (msg.type === "result" && msg.subtype !== "success") {
+      this._debug.timeEnd("Claude API call");
+      this._debug.log("Task failed:", msg.subtype);
+    }
+  }
+  async _uploadCache() {
+    if (this._cacheUploadDone)
+      return;
+    this._cacheUploadDone = true;
+    this._debug.log("Total messages streamed:", this._messageCount);
+    this._debug.log("Modified files tracked:", this._modifiedFilePaths.size);
+    this._debug.log("Code blocks extracted:", this._generatedCodeBlocks.length);
+    const filesToCache = [];
+    for (const filePath of this._modifiedFilePaths) {
+      if (filePath.includes(CACHE_DIR)) {
+        this._debug.log("  → Skipping cached file:", filePath);
+        continue;
+      }
+      try {
+        if (existsSync(filePath)) {
+          const content = readFileSync(filePath, "utf-8");
+          if (content.includes("\x00")) {
+            this._debug.log("  → Skipping binary file:", filePath);
+            continue;
+          }
+          filesToCache.push({ path: filePath, content });
+          this._debug.log("  → Will cache file:", filePath, `(${content.length} chars)`);
+        } else {
+          this._debug.log("  → File not found:", filePath);
+        }
+      } catch (err) {
+        this._debug.log("  → Failed to read file:", filePath, err instanceof Error ? err : String(err));
+      }
+    }
+    for (const filePath of this._bashGeneratedFiles) {
+      if (this._modifiedFilePaths.has(filePath))
+        continue;
+      try {
+        if (existsSync(filePath)) {
+          const content = readFileSync(filePath, "utf-8");
+          if (!content.includes("\x00")) {
+            filesToCache.push({ path: filePath, content });
+            this._debug.log("  → Will cache Bash-generated file:", filePath, `(${content.length} chars)`);
+          }
+        }
+      } catch {
+        this._debug.log("  → Failed to read Bash-generated file:", filePath);
+      }
+    }
+    if (this._generatedCodeBlocks.length > 0) {
+      const largestBlock = this._generatedCodeBlocks.reduce((a, b) => a.length > b.length ? a : b);
+      filesToCache.push({
+        path: "generated-code.ts",
+        content: largestBlock
+      });
+      this._debug.log("  → Will cache generated code block:", `(${largestBlock.length} chars)`);
+    }
+    this._debug.log("Total items to cache:", filesToCache.length);
+    if (this._cacheEnabled && this._raysurfer && this._taskSucceeded && this._promptText) {
+      const cachedBlocksForVoting = this._cachedFiles.map((f) => ({
+        codeBlockId: f.codeBlockId,
+        filename: f.filename,
+        description: f.description
+      }));
+      if (filesToCache.length > 0 || cachedBlocksForVoting.length > 0) {
+        try {
+          this._debug.time("Cache upload + voting");
+          const joinedLogs = this._executionLogs.length > 0 ? this._executionLogs.join(`
+---
+`) : undefined;
+          this._debug.log("Uploading", filesToCache.length, "files, voting for", cachedBlocksForVoting.length, "cached blocks,", this._executionLogs.length, "log entries...");
+          for (let i = 0;i < filesToCache.length; i++) {
+            const file = filesToCache[i];
+            await this._raysurfer.uploadNewCodeSnip(this._promptText, file, true, i === 0 && cachedBlocksForVoting.length > 0 ? cachedBlocksForVoting : undefined, true, undefined, joinedLogs);
+          }
+          if (filesToCache.length === 0 && cachedBlocksForVoting.length > 0) {
+            for (const cb of cachedBlocksForVoting) {
+              await this._raysurfer.voteCodeSnip({
+                task: this._promptText,
+                codeBlockId: cb.codeBlockId,
+                codeBlockName: cb.filename,
+                codeBlockDescription: cb.description,
+                succeeded: true
+              });
+            }
+          }
+          this._debug.timeEnd("Cache upload + voting");
+          this._debug.log("Cache upload successful, voting queued on backend");
+          console.log("[raysurfer] Cache upload successful:", filesToCache.length, "files stored");
+        } catch (error) {
+          const errMsg = error instanceof Error ? error.message : String(error);
+          this._debug.log("Cache upload failed:", errMsg);
+          console.warn("[raysurfer] Cache upload failed:", errMsg);
+        }
+      }
+    }
+    this._debug.groupEnd();
+  }
+  async next(...args) {
+    const inner = await this._ensureInit();
+    const result = await inner.next(...args);
+    if (!result.done) {
+      this._trackMessage(result.value);
+    } else {
+      await this._uploadCache();
+    }
+    return result;
+  }
+  async return(value) {
+    if (this._inner) {
+      await this._uploadCache();
+      return this._inner.return(value);
+    }
+    return { done: true, value: undefined };
+  }
+  async throw(e) {
+    if (this._inner)
+      return this._inner.throw(e);
+    throw e;
+  }
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+  async[Symbol.asyncDispose]() {
+    this.close();
+  }
+  async interrupt() {
+    return (await this._ensureInit()).interrupt();
+  }
+  async setPermissionMode(mode) {
+    return (await this._ensureInit()).setPermissionMode(mode);
+  }
+  async setModel(model) {
+    return (await this._ensureInit()).setModel(model);
+  }
+  async setMaxThinkingTokens(maxThinkingTokens) {
+    return (await this._ensureInit()).setMaxThinkingTokens(maxThinkingTokens);
+  }
+  async supportedCommands() {
+    return (await this._ensureInit()).supportedCommands();
+  }
+  async supportedModels() {
+    return (await this._ensureInit()).supportedModels();
+  }
+  async mcpServerStatus() {
+    return (await this._ensureInit()).mcpServerStatus();
+  }
+  async accountInfo() {
+    return (await this._ensureInit()).accountInfo();
+  }
+  async rewindFiles(userMessageId, options) {
+    return (await this._ensureInit()).rewindFiles(userMessageId, options);
+  }
+  async setMcpServers(servers) {
+    return (await this._ensureInit()).setMcpServers(servers);
+  }
+  async streamInput(stream) {
+    return (await this._ensureInit()).streamInput(stream);
+  }
+  close() {
+    if (this._inner)
+      this._inner.close();
+  }
+}
+function query(params) {
+  return new RaysurferQuery(params);
+}
+
+class ClaudeSDKClient {
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  query(prompt) {
+    return query({ prompt, options: this.options });
+  }
+}
+var sdk_client_default = query;
+// src/types.ts
+var ExecutionState;
+((ExecutionState2) => {
+  ExecutionState2["COMPLETED"] = "completed";
+  ExecutionState2["ERRORED"] = "errored";
+  ExecutionState2["TIMED_OUT"] = "timed_out";
+  ExecutionState2["CANCELLED"] = "cancelled";
+})(ExecutionState ||= {});
+var AgentVerdict;
+((AgentVerdict2) => {
+  AgentVerdict2["THUMBS_UP"] = "thumbs_up";
+  AgentVerdict2["THUMBS_DOWN"] = "thumbs_down";
+  AgentVerdict2["PENDING"] = "pending";
+})(AgentVerdict ||= {});
+
+// src/index.ts
+import {
+  AbortError,
+  createSdkMcpServer,
+  EXIT_REASONS,
+  HOOK_EVENTS,
+  tool
+} from "@anthropic-ai/claude-agent-sdk";
+export {
+  tool,
+  sdk_client_default as queryDefault,
+  query,
+  createSdkMcpServer,
+  ValidationError,
+  VERSION,
+  ClaudeSDKClient as RaysurferClient,
+  RaySurferError,
+  client_default as RaySurferDefault,
+  RaySurfer,
+  RateLimitError,
+  HOOK_EVENTS,
+  ExecutionState,
+  EXIT_REASONS,
+  ClaudeSDKClient,
+  CacheUnavailableError,
+  AuthenticationError,
+  AgentVerdict,
+  AbortError,
+  APIError
+};