@castari/sdk 0.0.6 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Castari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,39 +1,147 @@
 # @castari/sdk
 
-The SDK for building Castari agents.
+The SDK for building and connecting to Castari agents.
 
 ## Installation
 
 ```bash
 npm install @castari/sdk
+# or
+bun add @castari/sdk
 ```
 
-## Usage
+## Building Agents
 
-See the [SDK Reference](../../docs/sdk-reference.md) for detailed documentation.
+### `serve(options)`
 
-### Defining an Agent
+Starts the agent server. This should be the entrypoint of your agent.
 
 ```typescript
 import { serve, tool } from '@castari/sdk'
 
-const myTool = tool({ ... })
-
 serve({
   tools: [myTool],
   systemPrompt: 'You are a helpful assistant.'
 })
 ```
 
-### Connecting to an Agent
+#### Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tools` | `Tool[]` | Array of tools exposed by the agent |
+| `systemPrompt` | `string` | The system prompt defining the agent's behavior |
+| `allowedTools` | `string[]` | (Optional) Restrict which tools the agent can use |
+| `port` | `number` | (Optional) Port to listen on. Defaults to `3000` |
+
+By default, agents have access to all system tools (Bash, File Editing, etc.) plus any custom tools you define. Use `allowedTools` to restrict access:
+
+```typescript
+serve({
+  tools: [myCustomTool],
+  allowedTools: ['my_custom_tool', 'Bash'] // Only these tools available
+})
+```
+
+### `tool(definition)`
+
+Defines a custom tool for the agent.
+
+```typescript
+import { tool } from '@castari/sdk'
+
+const weatherTool = tool({
+  name: 'get_weather',
+  description: 'Get the weather for a location',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      location: { type: 'string' }
+    },
+    required: ['location']
+  },
+  handler: async ({ location }) => {
+    return `The weather in ${location} is sunny.`
+  }
+})
+```
+
+## Connecting to Agents
+
+### `CastariClient`
+
+A client for connecting to Castari agents.
 
 ```typescript
 import { CastariClient } from '@castari/sdk/client'
 
 const client = new CastariClient({
   snapshot: 'my-agent',
-  // platformUrl: '...' // Optional
+  platformUrl: process.env.CASTARI_PLATFORM_URL
+})
+
+await client.start()
+
+client.onMessage((msg) => {
+  console.log('Agent:', msg)
+})
+
+client.send({
+  type: 'user_message',
+  data: { message: 'Hello!' }
+})
+
+// When done
+await client.stop()
+```
+
+#### Constructor Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `platformUrl` | `string` | URL of the Castari Platform |
+| `snapshot` | `string` | Name of the snapshot to use |
+| `volume` | `string` | (Optional) Volume name for persistent storage |
+| `connectionUrl` | `string` | (Optional) Direct URL for local development |
+| `labels` | `Record<string, string>` | (Optional) Labels for sandbox reuse |
+
+#### Methods
+
+- `start()` - Creates a sandbox and connects to the agent
+- `stop(options?)` - Disconnects and cleans up
+  - `{ delete: false }` - Stop but preserve sandbox for reuse
+- `send(message)` - Send a message to the agent
+- `onMessage(callback)` - Register a callback for incoming messages
+
+### Sandbox Reuse
+
+Use labels to reuse sandboxes across sessions:
+
+```typescript
+const client = new CastariClient({
+  snapshot: 'my-agent',
+  volume: `user-${userId}`,
+  labels: {
+    userId,
+    app: 'my-app'
+  }
 })
 
+// First call creates, subsequent calls reuse
 await client.start()
+
+// Stop but preserve for later
+await client.stop({ delete: false })
 ```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_API_KEY` | Your Anthropic API key |
+| `CASTARI_PLATFORM_URL` | URL of the Castari Platform |
+| `CASTARI_CLIENT_ID` | Your Castari client ID |
+
+## License
+
+MIT

package/dist/client.js

@@ -40,10 +40,8 @@ export class CastariClient {
         }
         const configHeaders = {
             'Content-Type': 'application/json',
+            ...connection.authHeaders,
         };
-        if (connection.previewToken) {
-            configHeaders['x-daytona-preview-token'] = connection.previewToken;
-        }
         let configResponse = null;
         const maxConfigAttempts = 5;
         for (let attempt = 1; attempt <= maxConfigAttempts; attempt++) {
@@ -80,8 +78,11 @@ export class CastariClient {
         }
         const wsUrlParams = new URLSearchParams();
         wsUrlParams.set('token', connectionToken);
-        if (connection.previewToken) {
-            wsUrlParams.set('preview_token', connection.previewToken);
+        // Add any auth params from platform (for sandbox proxy auth)
+        if (connection.authParams) {
+            for (const [key, value] of Object.entries(connection.authParams)) {
+                wsUrlParams.set(key, value);
+            }
         }
         const wsUrlJoiner = connection.wsUrl.includes('?') ? '&' : '?';
         const wsUrl = `${connection.wsUrl}${wsUrlJoiner}${wsUrlParams.toString()}`;
@@ -148,7 +149,7 @@ export class CastariClient {
             const errorText = await response.text();
             throw new Error(`Failed to start sandbox: ${errorText}`);
         }
-        const { id, url, token } = await response.json();
+        const { id, url, authHeaders, authParams } = await response.json();
         this.sandboxId = id;
         if (this.options.debug) {
             console.log(`✅ Sandbox started: ${id} at ${url}`);
@@ -159,7 +160,8 @@ export class CastariClient {
         return {
             configUrl,
             wsUrl: wsUrlBase,
-            previewToken: token,
+            authHeaders,
+            authParams,
             cleanup: async () => {
                 await this.stop({ delete: true });
             }

package/dist/server.js

@@ -85,7 +85,7 @@ async function processMessages(initialOptions) {
             settingSources: ['local'],
             cwd: workspaceDirectory,
             // Auto-approve tool usage (including file writes) inside the sandbox.
-            // Daytona sandboxes are already isolated, so this keeps DX smooth without interactive prompts.
+            // Sandboxes are already isolated, so this keeps DX smooth without interactive prompts.
             canUseTool: async (_toolName, input) => ({
                 behavior: 'allow',
                 updatedInput: input,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@castari/sdk",
-    "version": "0.0.6",
+    "version": "0.1.0",
     "type": "module",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
@@ -10,7 +10,7 @@
     "files": [
         "dist"
     ],
-    "license": "UNLICENSED",
+    "license": "MIT",
     "publishConfig": {
         "access": "public"
     },