@capsule-run/cli 0.2.1 → 0.3.0

package/README.md

@@ -0,0 +1,135 @@
+# capsule
+
+**A secure, durable runtime for agentic workflows**
+
+## 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.
+
+Each task runs inside its own WebAssembly sandbox, providing:
+
+- **Isolated execution**: Each task runs isolated from your host system
+- **Resource limits**: Set CPU, memory, and timeout limits per task
+- **Automatic retries**: Handle failures without manual intervention
+- **Lifecycle tracking**: Monitor which tasks are running, completed, or failed
+
+## Installation
+
+```bash
+npm install -g @capsule-run/cli
+npm install @capsule-run/sdk
+```
+
+## Quick Start
+
+Create `hello.ts`:
+
+```typescript
+import { task } from "@capsule-run/sdk";
+
+export const main = task({
+  name: "main",
+  compute: "LOW",
+  ram: "64MB"
+}, (): string => {
+  return "Hello from Capsule!";
+});
+```
+
+Run it:
+
+```bash
+capsule run hello.ts
+```
+
+## How It Works
+
+Simply use a wrapper function to define your tasks:
+
+```typescript
+import { task } from "@capsule-run/sdk";
+
+export const analyzeData = task({
+  name: "analyze_data",
+  compute: "MEDIUM",
+  ram: "512MB",
+  timeout: "30s",
+  maxRetries: 1
+}, (dataset: number[]): object => {
+  // Your code runs safely in a Wasm sandbox
+  return { processed: dataset.length, status: "complete" };
+});
+
+// The "main" task is required as the entrypoint
+export const main = task({
+    name: "main",
+    compute: "HIGH"
+}, () => {
+  return analyzeData([1, 2, 3, 4, 5]);
+});
+```
+
+When you run `capsule run main.ts`, your code is compiled into a WebAssembly module and executed in a dedicated sandbox.
+
+## Documentation
+
+### Task Configuration Options
+
+| Parameter | Description | Type | Default | Example |
+|-----------|-------------|------|---------|---------|
+| `name` | Task identifier | `string` | *required* | `"process_data"` |
+| `compute` | CPU level: `"LOW"`, `"MEDIUM"`, `"HIGH"` | `string` | `"MEDIUM"` | `"HIGH"` |
+| `ram` | Memory limit | `string` | unlimited | `"512MB"`, `"2GB"` |
+| `timeout` | Maximum execution time | `string` or `number` | unlimited | `"30s"`, `"5m"`, `30000` (ms) |
+| `maxRetries` | Retry attempts on failure | `number` | `0` | `3` |
+| `allowedFiles` | Folders accessible in the sandbox | `string[]` | `[]` | `["./data", "./output"]` |
+
+### Compute Levels
+
+- **LOW**: Minimal allocation for lightweight tasks
+- **MEDIUM**: Balanced resources for typical workloads
+- **HIGH**: Maximum fuel for compute-intensive operations
+- **CUSTOM**: Specify exact fuel value (e.g., `compute="1000000"`)
+
+### File Access
+
+The **entry point task** (main) has access to the entire project directory. Sub-tasks have **no filesystem access by default** and must declare `allowedFiles` to access specific paths.
+
+Node.js built-ins like `fs` are not available in the WebAssembly sandbox. Instead, use the `files` API provided by the SDK:
+
+```typescript
+import { task, files } from "@capsule-run/sdk";
+
+export const restrictedWriter = task({
+    name: "restricted_writer",
+    allowedFiles: ["./output"]
+}, async () => {
+    await files.writeText("./output/result.txt", "result");
+});
+
+export const main = task({ name: "main" }, async () => {
+    restrictedWriter();
+    return await files.readText("./data/input.txt");
+});
+```
+
+Available methods:
+- `files.readText(path)` — Read file as string
+- `files.readBytes(path)` — Read file as `Uint8Array`
+- `files.writeText(path, content)` — Write string to file
+- `files.writeBytes(path, data)` — Write bytes to file
+- `files.list(path)` — List directory contents
+- `files.exists(path)` — Check if file exists
+
+## Compatibility
+
+✅ **Supported:**
+- npm packages and ES modules work
+
+⚠️ **Not yet supported:**
+- Node.js built-ins (`fs`, `path`, `os`) are not available in the sandbox
+
+## Links
+
+- [GitHub](https://github.com/mavdol/capsule)
+- [Issues](https://github.com/mavdol/capsule/issues)

package/bin/capsule.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PLATFORMS = {
+  "darwin-arm64": "@capsule-run/cli-darwin-arm64",
+  "darwin-x64": "@capsule-run/cli-darwin-x64",
+  "linux-x64": "@capsule-run/cli-linux-x64",
+  "win32-x64": "@capsule-run/cli-win32-x64",
+};
+
+function getPlatformPackage() {
+  const key = `${process.platform}-${process.arch}`;
+  return PLATFORMS[key];
+}
+
+function findBinary() {
+  const pkg = getPlatformPackage();
+  if (!pkg) {
+    console.error(`Unsupported platform: ${process.platform}-${process.arch}`);
+    process.exit(1);
+  }
+
+  try {
+    const pkgPath = require.resolve(`${pkg}/package.json`);
+    const pkgDir = path.dirname(pkgPath);
+    const binary = process.platform === "win32" ? "capsule.exe" : "capsule";
+    const binaryPath = path.join(pkgDir, binary);
+
+    if (fs.existsSync(binaryPath)) {
+      return binaryPath;
+    }
+  } catch {
+    // Package not found
+  }
+
+  console.error(`Could not find capsule binary for ${process.platform}-${process.arch}`);
+  console.error(`Please ensure @capsule-run/cli is installed correctly.`);
+  process.exit(1);
+}
+
+const result = spawnSync(findBinary(), process.argv.slice(2), { stdio: "inherit" });
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -1,28 +1,37 @@
 {
   "name": "@capsule-run/cli",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Secure WASM runtime to isolate and manage AI agent tasks",
+  "bin": {
+    "capsule": "./bin/capsule.js"
+  },
+  "files": [
+    "bin/"
+  ],
   "keywords": [
     "webassembly",
-    "cli",
     "sandbox",
-    "agent",
+    "agents",
     "isolation",
-    "security",
-    "llm"
+    "llm",
+    "ai"
   ],
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/mavdol/capsule.git"
   },
+  "homepage": "https://github.com/mavdol/capsule",
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@capsule-run/cli-darwin-arm64": "0.2.1",
-    "@capsule-run/cli-darwin-x64": "0.2.1",
-    "@capsule-run/cli-linux-x64": "0.2.1",
-    "@capsule-run/cli-win32-x64": "0.2.1"
+    "@capsule-run/cli-darwin-arm64": "0.3.0",
+    "@capsule-run/cli-darwin-x64": "0.3.0",
+    "@capsule-run/cli-linux-x64": "0.3.0",
+    "@capsule-run/cli-win32-x64": "0.3.0"
   }
 }