raysurfer 0.2.0

package/dist/sdk-client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * RaysurferClient - Drop-in enhancement for Claude Agent SDK with code block caching.
+ *
+ * This client wraps the Claude Agent SDK query function to:
+ * 1. Pre-fetch relevant code blocks from the Raysurfer backend
+ * 2. Download them as files to a sandbox directory
+ * 3. Inject file contents into the system prompt
+ * 4. Let the agent use standard Bash tool to execute
+ * 5. After task completion, store generated code back to the cache
+ */
+import type { CodeFile } from "./types";
+/** Options for RaysurferClient */
+export interface RaysurferAgentOptions {
+    raysurferApiKey?: string;
+    raysurferBaseUrl?: string;
+    prefetchCount?: number;
+    minVerdictScore?: number;
+    preferComplete?: boolean;
+    sandboxDir?: string;
+    cleanupSandbox?: boolean;
+    cleanupOnError?: boolean;
+    model?: string;
+    workingDirectory?: string;
+    systemPrompt?: string;
+    permissionMode?: "default" | "acceptEdits" | "plan" | "bypassPermissions";
+    maxBudgetUsd?: number;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    maxTurns?: number;
+    env?: Record<string, string>;
+}
+/**
+ * RaysurferClient - wraps Claude Agent SDK with code block caching
+ *
+ * Usage:
+ * ```typescript
+ * const client = new RaysurferClient({
+ *   raysurferApiKey: "rs_...",
+ *   model: "claude-sonnet-4-5",
+ *   systemPrompt: "You are a helpful assistant.",
+ * });
+ *
+ * for await (const message of client.query("Fetch data from the GitHub API")) {
+ *   console.log(message);
+ * }
+ * ```
+ */
+export declare class RaysurferClient {
+    private options;
+    private raysurfer;
+    private prefetchedFiles;
+    private currentQuery;
+    private generatedFiles;
+    private taskSucceeded;
+    constructor(options?: RaysurferAgentOptions);
+    /**
+     * Query Claude with pre-fetched code files from Raysurfer.
+     *
+     * This method:
+     * 1. Pre-fetches relevant code files from Raysurfer backend
+     * 2. Downloads files to sandbox directory
+     * 3. Injects file contents into system prompt
+     * 4. Delegates to Claude Agent SDK
+     * 5. Stores generated code back to cache on success
+     */
+    query(prompt: string): AsyncGenerator<unknown>;
+    /** Get the list of pre-fetched code files */
+    get files(): CodeFile[];
+    /** Get the sandbox directory path */
+    get sandbox(): string;
+    /** Manually clean up the sandbox directory */
+    cleanup(): Promise<void>;
+    private prefetchCodeFiles;
+    private downloadFilesToSandbox;
+    private buildSystemPrompt;
+    private formatCodeSnippets;
+    private storeGeneratedCode;
+    private cleanupSandbox;
+}
+export default RaysurferClient;
+//# sourceMappingURL=sdk-client.d.ts.map

package/dist/sdk-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-client.d.ts","sourceRoot":"","sources":["../src/sdk-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,QAAQ,EAAe,MAAM,SAAS,CAAC;AAIrD,kCAAkC;AAClC,MAAM,WAAW,qBAAqB;IAEpC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IAGzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,MAAM,GAAG,mBAAmB,CAAC;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAYS;IAExB,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,aAAa,CAAS;gBAElB,OAAO,GAAE,qBAA0B;IAkB/C;;;;;;;;;OASG;IACI,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC;IAyFrD,6CAA6C;IAC7C,IAAI,KAAK,IAAI,QAAQ,EAAE,CAEtB;IAED,qCAAqC;IACrC,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,8CAA8C;IACxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAQhB,iBAAiB;YAejB,sBAAsB;IAWpC,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,kBAAkB;YAuBZ,kBAAkB;YAiBlB,cAAc;CAgB7B;AAED,eAAe,eAAe,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * RaySurfer SDK types - mirrors the backend API types
+ */
+/** Technical execution outcome - NOT a quality judgment */
+export declare enum ExecutionState {
+    COMPLETED = "completed",
+    ERRORED = "errored",
+    TIMED_OUT = "timed_out",
+    CANCELLED = "cancelled"
+}
+/** Agent's judgment on whether an execution was useful */
+export declare enum AgentVerdict {
+    THUMBS_UP = "thumbs_up",
+    THUMBS_DOWN = "thumbs_down",
+    PENDING = "pending"
+}
+/** A stored code block with metadata for semantic retrieval */
+export interface CodeBlock {
+    id: string;
+    name: string;
+    description: string;
+    source: string;
+    entrypoint: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    language: string;
+    languageVersion?: string | null;
+    dependencies: string[];
+    tags: string[];
+    capabilities: string[];
+    exampleQueries?: string[] | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+/** Stores the actual input/output data */
+export interface ExecutionIO {
+    inputData: Record<string, unknown>;
+    inputHash?: string;
+    outputData?: unknown;
+    outputHash?: string;
+    outputType?: string;
+}
+/** Agent's assessment of whether an execution was useful */
+export interface AgentReview {
+    timestamp?: string;
+    verdict: AgentVerdict;
+    reasoning: string;
+    whatWorked: string[];
+    whatDidntWork: string[];
+    outputWasUseful: boolean;
+    outputWasCorrect: boolean;
+    outputWasComplete: boolean;
+    errorWasAppropriate?: boolean | null;
+    wouldUseAgain: boolean;
+    suggestedImprovements: string[];
+    requiredWorkaround?: boolean;
+    workaroundDescription?: string | null;
+}
+/** Full execution trace */
+export interface ExecutionRecord {
+    id: string;
+    codeBlockId: string;
+    timestamp?: string;
+    executionState: ExecutionState;
+    durationMs: number;
+    errorMessage?: string | null;
+    errorType?: string | null;
+    io: ExecutionIO;
+    triggeringTask: string;
+    retrievalScore?: number;
+    verdict?: AgentVerdict;
+    review?: AgentReview | null;
+}
+/** The best matching code block with full scoring */
+export interface BestMatch {
+    codeBlock: CodeBlock;
+    combinedScore: number;
+    vectorScore: number;
+    verdictScore: number;
+    errorResilience: number;
+    thumbsUp: number;
+    thumbsDown: number;
+}
+/** An alternative candidate code block */
+export interface AlternativeCandidate {
+    codeBlockId: string;
+    name: string;
+    combinedScore: number;
+    reason: string;
+}
+/** A few-shot example for code generation */
+export interface FewShotExample {
+    task: string;
+    inputSample: Record<string, unknown>;
+    outputSample: unknown;
+    codeSnippet: string;
+}
+/** A proven task->code mapping */
+export interface TaskPattern {
+    taskPattern: string;
+    codeBlockId: string;
+    codeBlockName: string;
+    thumbsUp: number;
+    thumbsDown: number;
+    verdictScore: number;
+    errorResilience: number;
+    lastThumbsUp?: string | null;
+    lastThumbsDown?: string | null;
+}
+/** A file written during agent execution */
+export interface FileWritten {
+    path: string;
+    content: string;
+}
+export interface StoreCodeBlockResponse {
+    success: boolean;
+    codeBlockId: string;
+    embeddingId: string;
+    message: string;
+}
+export interface StoreExecutionResponse {
+    success: boolean;
+    executionId: string;
+    patternUpdated: boolean;
+    message: string;
+}
+export interface CodeBlockMatch {
+    codeBlock: CodeBlock;
+    score: number;
+    verdictScore: number;
+    thumbsUp: number;
+    thumbsDown: number;
+    recentExecutions: ExecutionRecord[];
+}
+export interface RetrieveCodeBlockResponse {
+    codeBlocks: CodeBlockMatch[];
+    totalFound: number;
+}
+export interface RetrieveBestResponse {
+    bestMatch: BestMatch | null;
+    alternativeCandidates: AlternativeCandidate[];
+    retrievalConfidence: string;
+}
+export interface SubmitExecutionResultRequest {
+    task: string;
+    filesWritten: FileWritten[];
+    succeeded: boolean;
+}
+export interface SubmitExecutionResultResponse {
+    success: boolean;
+    codeBlocksStored: number;
+    message: string;
+}
+/** A code file ready to be written to sandbox */
+export interface CodeFile {
+    codeBlockId: string;
+    filename: string;
+    source: string;
+    entrypoint: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    language: string;
+    dependencies: string[];
+    verdictScore: number;
+    thumbsUp: number;
+    thumbsDown: number;
+}
+/** Response with code files for a task */
+export interface GetCodeFilesResponse {
+    files: CodeFile[];
+    task: string;
+    totalFound: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "raysurfer",
+  "version": "0.2.0",
+  "description": "TypeScript SDK for RaySurfer - code block caching and retrieval for AI agents with Claude Agent SDK integration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && bun run build:types",
+    "build:types": "tsc --emitDeclarationOnly --declaration --outDir ./dist",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "code-blocks",
+    "retrieval",
+    "embeddings",
+    "claude",
+    "anthropic",
+    "raysurfer",
+    "caching",
+    "llm"
+  ],
+  "author": "Raymond Xu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/raymondxu/raysurfer-ts"
+  },
+  "homepage": "https://raysurfer.com",
+  "bugs": {
+    "url": "https://github.com/raymondxu/raysurfer-ts/issues"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}