@castari/sdk 0.1.4 → 0.1.5

package/README.md

@@ -1,6 +1,6 @@
 # @castari/sdk
 
-The SDK for building and connecting to Castari agents.
+The SDK for building and connecting to Castari agents running in secure cloud sandboxes.
 
 ## Installation
 
@@ -70,7 +70,7 @@ const weatherTool = tool({
 
 ### `CastariClient`
 
-A client for connecting to Castari agents.
+A client for connecting to Castari agents running in cloud sandboxes.
 
 ```typescript
 import { CastariClient } from '@castari/sdk/client'
@@ -85,7 +85,9 @@ const client = new CastariClient({
 await client.start()
 
 client.onMessage((msg) => {
-  console.log('Agent:', msg)
+  if (msg.type === 'assistant_message') {
+    console.log('Agent:', msg.data.message)
+  }
 })
 
 client.send({
@@ -101,23 +103,69 @@ await client.stop()
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `snapshot` | `string` | Name of the snapshot to use |
+| `snapshot` | `string` | Name of the deployed snapshot to use |
 | `clientId` | `string` | Your Castari client ID |
 | `platformApiKey` | `string` | Your Castari API key |
 | `anthropicApiKey` | `string` | Your Anthropic API key |
 | `volume` | `string` | (Optional) Volume name for persistent storage |
 | `labels` | `Record<string, string>` | (Optional) Labels for sandbox reuse |
+| `resume` | `string` | (Optional) Session ID to resume a previous conversation |
 | `connectionUrl` | `string` | (Optional) Direct URL for local development |
-| `platformUrl` | `string` | (Optional) Override the platform URL (advanced) |
+| `platformUrl` | `string` | (Optional) Override the platform URL |
+| `useProxy` | `boolean` | (Optional) Use platform proxy. Defaults to `true` |
+| `debug` | `boolean` | (Optional) Enable debug logging |
 
 #### Methods
 
 - `start()` - Creates a sandbox and connects to the agent
 - `stop(options?)` - Disconnects and cleans up
   - `{ delete: false }` - Stop but preserve sandbox for reuse
+  - `{ delete: true }` (default) - Delete the sandbox
 - `send(message)` - Send a message to the agent
 - `onMessage(callback)` - Register a callback for incoming messages
 
+### Message Types
+
+#### Input Messages (client to agent)
+
+```typescript
+// Send a user message
+client.send({
+  type: 'user_message',
+  data: { message: 'Hello!' }
+})
+```
+
+#### Output Messages (agent to client)
+
+```typescript
+client.onMessage((msg) => {
+  switch (msg.type) {
+    case 'connected':
+      // Connection established
+      break
+    case 'assistant_message':
+      // Text response from the agent
+      console.log(msg.data.message)
+      break
+    case 'tool_use':
+      // Agent is using a tool
+      console.log(`Using tool: ${msg.data.name}`)
+      break
+    case 'tool_result':
+      // Tool execution result
+      break
+    case 'done':
+      // Agent finished processing
+      break
+    case 'error':
+      // Error occurred
+      console.error(msg.data.error)
+      break
+  }
+})
+```
+
 ### Sandbox Reuse
 
 Use labels to reuse sandboxes across sessions:
@@ -132,13 +180,43 @@ const client = new CastariClient({
   }
 })
 
-// First call creates, subsequent calls reuse
+// First call creates, subsequent calls reuse the same sandbox
 await client.start()
 
 // Stop but preserve for later
 await client.stop({ delete: false })
 ```
 
+### Session Resumption
+
+Resume a previous conversation:
+
+```typescript
+// Store the session ID from a previous session
+const sessionId = previousSessionId
+
+const client = new CastariClient({
+  snapshot: 'my-agent',
+  resume: sessionId
+})
+
+await client.start()
+// Conversation continues where it left off
+```
+
+### Local Development
+
+Connect directly to a local agent server:
+
+```typescript
+const client = new CastariClient({
+  connectionUrl: 'http://localhost:3000',
+  anthropicApiKey: process.env.ANTHROPIC_API_KEY
+})
+
+await client.start()
+```
+
 ## Environment Variables
 
 | Variable | Description |

package/dist/client.d.ts

@@ -34,15 +34,20 @@ export declare class CastariClient {
     private ws?;
     private options;
     private messageHandlers;
+    private closeHandlers;
     private sandboxId?;
     private resolvedClientId?;
     private resolvedPlatformApiKey?;
     constructor(options?: ClientOptions);
+    /** Check if the WebSocket is currently connected */
+    isConnected(): boolean;
     start(): Promise<void>;
     private setupLocalConnection;
     private setupPlatformConnection;
     private handleMessage;
     onMessage(handler: (message: WSOutputMessage) => void): () => void;
+    /** Register a callback for when the WebSocket connection closes */
+    onClose(handler: (code: number, reason: string) => void): () => void;
     send(message: WSInputMessage): void;
     stop(options?: {
         delete?: boolean;

package/dist/client.js

@@ -5,6 +5,7 @@ export class CastariClient {
     ws;
     options;
     messageHandlers = [];
+    closeHandlers = [];
     sandboxId;
     resolvedClientId;
     resolvedPlatformApiKey;
@@ -13,6 +14,10 @@ export class CastariClient {
             ...options,
         };
     }
+    /** Check if the WebSocket is currently connected */
+    isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
     async start() {
         const anthropicApiKey = this.options.anthropicApiKey || process.env.ANTHROPIC_API_KEY;
         if (!anthropicApiKey) {
@@ -110,9 +115,10 @@ export class CastariClient {
                 console.error('WebSocket error:', error);
                 reject(error);
             };
-            this.ws.onclose = () => {
+            this.ws.onclose = (event) => {
                 if (this.options.debug)
-                    console.log('👋 Disconnected');
+                    console.log(`👋 Disconnected (code=${event.code})`);
+                this.closeHandlers.forEach(handler => handler(event.code, event.reason));
             };
         });
     }
@@ -200,6 +206,13 @@ export class CastariClient {
             this.messageHandlers = this.messageHandlers.filter(h => h !== handler);
         };
     }
+    /** Register a callback for when the WebSocket connection closes */
+    onClose(handler) {
+        this.closeHandlers.push(handler);
+        return () => {
+            this.closeHandlers = this.closeHandlers.filter(h => h !== handler);
+        };
+    }
     send(message) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
             throw new Error('WebSocket is not connected');

package/dist/server.js

@@ -190,6 +190,9 @@ export async function serve(options = {}) {
             return new Response('Not Found', { status: 404 });
         },
         websocket: {
+            // Keep connection alive as long as sandbox is running
+            idleTimeout: 0,
+            sendPings: true,
             open(ws) {
                 activeConnection = ws;
                 // Start processing messages when first connection is made

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@castari/sdk",
-    "version": "0.1.4",
+    "version": "0.1.5",
     "type": "module",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",