raysurfer 0.2.0

package/README.md

@@ -0,0 +1,115 @@
+# RaySurfer TypeScript SDK
+
+TypeScript SDK for RaySurfer - code block caching and retrieval for AI agents with Claude Agent SDK integration.
+
+## Installation
+
+```bash
+npm install raysurfer
+# or
+bun add raysurfer
+```
+
+## Quick Start
+
+### Basic Client (Store/Retrieve Code Blocks)
+
+```typescript
+import { RaySurfer } from "raysurfer";
+
+const client = new RaySurfer({ apiKey: "rs_..." });
+
+// Store a code block
+const result = await client.storeCodeBlock({
+  name: "GitHub User Fetcher",
+  source: "async function fetchUser(username) { ... }",
+  entrypoint: "fetchUser",
+  language: "typescript",
+});
+
+// Retrieve code blocks for a task
+const response = await client.retrieve({ task: "Fetch GitHub user data" });
+for (const match of response.codeBlocks) {
+  console.log(match.codeBlock.name, match.verdictScore);
+}
+```
+
+### Claude Agent SDK Integration
+
+```typescript
+import { RaysurferClient } from "raysurfer";
+
+const client = new RaysurferClient({
+  raysurferApiKey: "rs_...",
+  model: "claude-sonnet-4-5",
+  systemPrompt: "You are a helpful assistant.",
+  allowedTools: ["Read", "Write", "Bash"],
+});
+
+// Pre-fetches code files, downloads to sandbox, injects into prompt
+for await (const message of client.query("Fetch user data from GitHub API")) {
+  if (message.type === "assistant") {
+    console.log(message.content);
+  }
+}
+```
+
+## How It Works
+
+1. **On `query()`**: RaysurferClient calls the backend to get relevant code files
+2. **Downloads to sandbox**: Files are written to `~/.raysurfer/sandbox/`
+3. **Injects into prompt**: Code snippets are added to the system prompt
+4. **Agent executes**: Agent can run the code using the Bash tool within the sandbox
+5. **Caches results**: On success, generated code is stored back to the cache
+
+## RaysurferAgentOptions
+
+```typescript
+interface RaysurferAgentOptions {
+  // Raysurfer-specific
+  raysurferApiKey?: string;
+  raysurferBaseUrl?: string;
+  prefetchCount?: number; // default: 5
+  minVerdictScore?: number; // default: 0.3
+  preferComplete?: boolean; // default: true
+  sandboxDir?: string; // default: ~/.raysurfer/sandbox
+  cleanupSandbox?: boolean; // default: true
+  cleanupOnError?: boolean; // default: false
+
+  // Standard Claude Agent SDK options
+  model?: string; // default: "claude-sonnet-4-5"
+  workingDirectory?: string;
+  systemPrompt?: string;
+  permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions";
+  maxBudgetUsd?: number;
+  allowedTools?: string[];
+  disallowedTools?: string[];
+  maxTurns?: number;
+  env?: Record<string, string>;
+  mcpServers?: Record<string, unknown>;
+}
+```
+
+## API Reference
+
+### RaySurfer Client
+
+```typescript
+const client = new RaySurfer({ apiKey: "rs_..." });
+
+// Store
+await client.storeCodeBlock({ name, source, entrypoint, language, ... });
+await client.storeExecution({ codeBlockId, triggeringTask, inputData, outputData, ... });
+await client.submitExecutionResult(task, filesWritten, succeeded);
+
+// Retrieve
+await client.retrieve({ task, topK, minVerdictScore });
+await client.retrieveBest({ task, topK, minVerdictScore });
+await client.getFewShotExamples(task, k);
+await client.getTaskPatterns({ task, codeBlockId, minThumbsUp, topK });
+await client.getCodeFiles({ task, topK, minVerdictScore, preferComplete });
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,98 @@
+/**
+ * RaySurfer SDK client
+ */
+import type { AgentReview, AgentVerdict, ExecutionState, FewShotExample, FileWritten, GetCodeFilesResponse, RetrieveBestResponse, RetrieveCodeBlockResponse, StoreCodeBlockResponse, StoreExecutionResponse, SubmitExecutionResultResponse, TaskPattern } from "./types";
+export interface RaySurferOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+export interface StoreCodeBlockParams {
+    name: string;
+    source: string;
+    entrypoint: string;
+    language: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    languageVersion?: string;
+    dependencies?: string[];
+    tags?: string[];
+    capabilities?: string[];
+    exampleQueries?: string[];
+}
+export interface StoreExecutionParams {
+    codeBlockId: string;
+    triggeringTask: string;
+    inputData: Record<string, unknown>;
+    outputData: unknown;
+    executionState?: ExecutionState;
+    durationMs?: number;
+    errorMessage?: string;
+    errorType?: string;
+    verdict?: AgentVerdict;
+    review?: AgentReview;
+}
+export interface RetrieveParams {
+    task: string;
+    topK?: number;
+    minVerdictScore?: number;
+}
+export interface GetCodeFilesParams {
+    task: string;
+    topK?: number;
+    minVerdictScore?: number;
+    preferComplete?: boolean;
+}
+export interface GetTaskPatternsParams {
+    task?: string;
+    codeBlockId?: string;
+    minThumbsUp?: number;
+    topK?: number;
+}
+/**
+ * Async client for RaySurfer API
+ */
+export declare class RaySurfer {
+    private apiKey?;
+    private baseUrl;
+    private timeout;
+    constructor(options?: RaySurferOptions);
+    private request;
+    /** Store a new code block */
+    storeCodeBlock(params: StoreCodeBlockParams): Promise<StoreCodeBlockResponse>;
+    /** Store an execution record */
+    storeExecution(params: StoreExecutionParams): Promise<StoreExecutionResponse>;
+    /**
+     * Submit raw execution result - backend handles all processing.
+     *
+     * This is the simplified API for agent integrations. Just send:
+     * - The task that was executed
+     * - Files that were written during execution
+     * - Whether the task succeeded
+     *
+     * Backend handles: entrypoint detection, tag extraction, language detection,
+     * deduplication, quality checks, and storage.
+     */
+    submitExecutionResult(task: string, filesWritten: FileWritten[], succeeded: boolean): Promise<SubmitExecutionResultResponse>;
+    /** Retrieve code blocks by task description (semantic search) */
+    retrieve(params: RetrieveParams): Promise<RetrieveCodeBlockResponse>;
+    /** Get the single best code block for a task using verdict-aware scoring */
+    retrieveBest(params: RetrieveParams): Promise<RetrieveBestResponse>;
+    /** Retrieve few-shot examples for code generation */
+    getFewShotExamples(task: string, k?: number): Promise<FewShotExample[]>;
+    /** Retrieve proven task->code mappings */
+    getTaskPatterns(params: GetTaskPatternsParams): Promise<TaskPattern[]>;
+    /**
+     * Get code files for a task, ready to download to sandbox.
+     *
+     * Returns code blocks with full source code, optimized for:
+     * - High verdict scores (proven to work)
+     * - More complete implementations (prefer longer source)
+     * - Task relevance (semantic similarity)
+     */
+    getCodeFiles(params: GetCodeFilesParams): Promise<GetCodeFilesResponse>;
+    private parseCodeBlock;
+}
+export default RaySurfer;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RaySurfer SDK errors
+ */
+/** Base error for RaySurfer SDK */
+export declare class RaySurferError extends Error {
+    constructor(message: string);
+}
+/** API returned an error response */
+export declare class APIError extends RaySurferError {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/** Authentication failed */
+export declare class AuthenticationError extends RaySurferError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,mCAAmC;AACnC,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,qCAAqC;AACrC,qBAAa,QAAS,SAAQ,cAAc;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;gBAER,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAKjD;AAED,4BAA4B;AAC5B,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,OAAO,GAAE,MAA0B;CAIhD"}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * RaySurfer TypeScript SDK
+ *
+ * Store and retrieve code blocks for AI agents with semantic search
+ * and verdict-aware scoring.
+ *
+ * Includes Claude Agent SDK integration via RaysurferClient.
+ */
+export { RaySurfer, default as RaySurferDefault } from "./client";
+export type { RaySurferOptions, StoreCodeBlockParams, StoreExecutionParams, RetrieveParams, GetCodeFilesParams, GetTaskPatternsParams, } from "./client";
+export { RaysurferClient } from "./sdk-client";
+export type { RaysurferAgentOptions } from "./sdk-client";
+export { ExecutionState, AgentVerdict } from "./types";
+export type { CodeBlock, ExecutionIO, AgentReview, ExecutionRecord, BestMatch, AlternativeCandidate, FewShotExample, TaskPattern, FileWritten, StoreCodeBlockResponse, StoreExecutionResponse, CodeBlockMatch, RetrieveCodeBlockResponse, RetrieveBestResponse, SubmitExecutionResultRequest, SubmitExecutionResultResponse, CodeFile, GetCodeFilesResponse, } from "./types";
+export { RaySurferError, APIError, AuthenticationError } from "./errors";
+export declare const VERSION = "0.2.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,SAAS,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAG1D,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvD,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,eAAe,EACf,SAAS,EACT,oBAAoB,EACpB,cAAc,EACd,WAAW,EACX,WAAW,EACX,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,yBAAyB,EACzB,oBAAoB,EACpB,4BAA4B,EAC5B,6BAA6B,EAC7B,QAAQ,EACR,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEzE,eAAO,MAAM,OAAO,UAAU,CAAC"}