@capsule-run/cli 0.6.2 → 0.6.4

package/README.md

@@ -4,7 +4,7 @@
 
 ## Overview
 
-Capsule is a runtime for coordinating AI agent tasks in isolated environments. It is designed to handle long-running workflows, large-scale processing, autonomous decision-making securely, or even multi-agent systems.
+Capsule is a runtime for coordinating AI agent tasks in isolated environments. It is designed to handle untrusted code execution, long-running workflows, large-scale processing, or even multi-agent systems.
 
 Each task runs inside its own WebAssembly sandbox, providing:
 
@@ -13,6 +13,8 @@ Each task runs inside its own WebAssembly sandbox, providing:
 - **Automatic retries**: Handle failures without manual intervention
 - **Lifecycle tracking**: Monitor which tasks are running, completed, or failed
 
+This enables safe task-level execution of untrusted code within AI agent systems.
+
 ## Installation
 
 ```bash
@@ -44,6 +46,36 @@ capsule run hello.ts
 
 > Use `--verbose` to display real-time task execution details.
 
+## Production
+
+Running source code directly (like `.ts`) evaluates and compiles your file at runtime. While great for development, this compilation step adds a few seconds of latency. For use cases where sub-second latency is critical, you should build your tasks ahead of time.
+
+```bash
+# Generates an optimized hello.wasm file
+capsule build hello.ts --export
+
+# Execute the compiled artifact directly
+capsule exec hello.wasm
+```
+
+> [!NOTE]
+> Or from your existing code:
+>
+> ```typescript
+> import { run } from '@capsule-run/sdk/runner';
+>
+> const result = await run({
+>   file: './hello.wasm', // or `hello.ts`
+>   args: []
+> });
+>
+> console.log(`Task completed: ${result.result}`);
+> ```
+>
+> See [Integrate Into an Existing Project](#integrate-into-an-existing-project) for details.
+
+Executing a `.wasm` file bypasses the compiler completely, reducing initialization time to milliseconds while using a natively optimized (`.cwasm`) format behind the scenes.
+
 ## Integrate Into an Existing Project
 
 The `run()` function lets you execute tasks programmatically from your application code, no CLI needed.
@@ -54,7 +86,7 @@ The `run()` function lets you execute tasks programmatically from your applicati
 import { run } from '@capsule-run/sdk/runner';
 
 const result = await run({
-  file: './capsule.ts',
+  file: './capsule.ts', // or `capsule.wasm`
   args: ['code to execute']
 });
 ```
@@ -122,7 +154,7 @@ Every task returns a structured JSON envelope containing both the result and exe
 
 **Response fields:**
 - `success` — Boolean indicating whether the task completed successfully
-- `result` — The actual return value from your task (json, string, null on failure etc..)
+- `result` — The actual return value from your task (json, string, null on failure etc.)
 - `error` — Error details if the task failed (`{ error_type: string, message: string }`)
 - `execution` — Performance metrics:
   - `task_name` — Name of the executed task
@@ -231,11 +263,13 @@ export const main = task({
 
 ✅ **Supported:**
 - npm packages and ES modules
-- Common Node.js built-ins. If you have any trouble with a built-in do not hesitate to open an issue.
+- Common Node.js built-ins. If you have any trouble with a built-in, do not hesitate to open an issue.
 
-⚠️ **Not supported:**
+⚠️ **Not supported (inside the sandbox):**
 - Native Node.js addons (C++ bindings)
 
+> These limitations only apply to the task file executed in the sandbox. Your host code using `run()` runs in a normal Node.js environment with no restrictions. (see [Integrate Into an Existing Project](#integrate-into-an-existing-project))
+
 ## Links
 
 - [GitHub](https://github.com/mavdol/capsule)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capsule-run/cli",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Secure WASM runtime to isolate and manage AI agent tasks",
   "bin": {
     "capsule": "./bin/capsule.js"
@@ -29,9 +29,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@capsule-run/cli-darwin-arm64": "0.6.2",
-    "@capsule-run/cli-darwin-x64": "0.6.2",
-    "@capsule-run/cli-linux-x64": "0.6.2",
-    "@capsule-run/cli-win32-x64": "0.6.2"
+    "@capsule-run/cli-darwin-arm64": "0.6.4",
+    "@capsule-run/cli-darwin-x64": "0.6.4",
+    "@capsule-run/cli-linux-x64": "0.6.4",
+    "@capsule-run/cli-win32-x64": "0.6.4"
   }
 }