@castari/sdk 0.0.7 → 0.1.1

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

@@ -1,5 +1,6 @@
 export * from './types';
 const DEFAULT_LOCAL_URL = 'http://localhost:3000';
+const DEFAULT_PLATFORM_URL = 'https://castari-api-12511-04c55b73-g4p2s9om.onporter.run';
 export class CastariClient {
     ws;
     options;
@@ -126,7 +127,7 @@ export class CastariClient {
         if (!this.resolvedClientId) {
             throw new Error('CASTARI_CLIENT_ID is required when connecting via the Castari Platform');
         }
-        const platformUrl = this.options.platformUrl || process.env.CASTARI_PLATFORM_URL || 'http://localhost:3000';
+        const platformUrl = this.options.platformUrl || process.env.CASTARI_PLATFORM_URL || DEFAULT_PLATFORM_URL;
         if (this.options.debug) {
             console.log(`🚀 Requesting sandbox from ${platformUrl}...`);
         }
@@ -190,7 +191,7 @@ export class CastariClient {
             this.ws.close();
         }
         if (this.sandboxId) {
-            const platformUrl = this.options.platformUrl || process.env.CASTARI_PLATFORM_URL || 'http://localhost:3000';
+            const platformUrl = this.options.platformUrl || process.env.CASTARI_PLATFORM_URL || DEFAULT_PLATFORM_URL;
             try {
                 const clientId = this.resolvedClientId || this.options.clientId || process.env.CASTARI_CLIENT_ID;
                 const apiKey = this.resolvedPlatformApiKey || this.options.platformApiKey || process.env.CASTARI_API_KEY;

package/package.json

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