raysurfer 0.6.2 → 0.7.0

package/README.md

@@ -3,8 +3,10 @@
 [Website](https://raysurfer.com) · [Docs](https://docs.raysurfer.com) · [Dashboard](https://raysurfer.com/dashboard/api-keys)
 
 <!-- Old: LLM output caching for AI agents. Retrieve proven code instead of regenerating it. -->
-Code reputation layer for AI agents. Let agents re-use generated
-code vs running 30 serial tools or generating code per execution.
+<!-- Old: Code reputation layer for AI agents. Let agents re-use generated code vs running 30 serial tools or generating code per execution. -->
+AI Maintained Skills for Vertical Agents. Re-use verified code
+from prior runs rather than serial tool calls or generating code
+per execution.
 
 ## Installation
 
@@ -353,6 +355,62 @@ const client = new ClaudeSDKClient({ publicSnips: true });
 const rs = new RaySurfer({ apiKey: "...", publicSnips: true });
 ```
 
+## Programmatic Tool Calling
+
+Register local tools and let the server generate + execute code
+that calls them:
+
+```typescript
+import { RaySurfer } from "raysurfer";
+
+const rs = new RaySurfer({ apiKey: "your_api_key" });
+
+rs.tool("add", "Add two numbers together", { a: "integer", b: "integer" },
+  async (args) => String(Number(args.a) + Number(args.b))
+);
+
+rs.tool("multiply", "Multiply two numbers together", { a: "integer", b: "integer" },
+  async (args) => String(Number(args.a) * Number(args.b))
+);
+
+const result = await rs.execute(
+  "Add 5 and 3, then multiply the result by 2"
+);
+console.log(result.result);     // "16"
+console.log(result.toolCalls);  // [{toolName: 'add', ...}, ...]
+console.log(result.cacheHit);   // true on subsequent runs
+```
+
+### How It Works
+
+1. SDK connects a WebSocket to the server for tool call routing
+2. Server generates Python code (or reuses reference code from a
+   similar prior run)
+3. Code runs in a sandboxed environment — tool calls are routed
+   back to your local functions via WebSocket
+4. Results are returned with full tool call history
+
+### Execute Options
+
+```typescript
+const result = await rs.execute("Your task description", {
+  timeout: 300000,        // Max time in ms (default 300000)
+  forceRegenerate: false, // Skip cache (default false)
+});
+```
+
+### ExecuteResult Fields
+
+| Field         | Type               | Description                      |
+| ------------- | ------------------ | -------------------------------- |
+| `executionId` | `string`           | Unique execution identifier      |
+| `result`      | `string \| null`   | Stdout output from the script    |
+| `exitCode`    | `number`           | Process exit code (0 = success)  |
+| `durationMs`  | `number`           | Total execution time             |
+| `cacheHit`    | `boolean`          | Whether reference code was found |
+| `error`       | `string \| null`   | Error message if exitCode != 0   |
+| `toolCalls`   | `ToolCallRecord[]` | All tool calls made              |
+
 ## License
 
 MIT

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "raysurfer",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "_description_old": "Semantic code caching for LLM agents",
-  "description": "Code reputation layer for AI agents",
+  "_description_old2": "Code reputation layer for AI agents",
+  "description": "AI maintained skills for vertical agents",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",