@aigne/afs-sandbox 1.11.0-beta.6

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/README.md

@@ -0,0 +1,489 @@
+# @aigne/afs-sandbox
+
+AFS Sandbox Provider - A secure JavaScript execution environment for LLM-generated code.
+
+## Overview
+
+The AFS Sandbox Provider transforms AFS from a storage abstraction layer into a **semantic-level virtual machine for LLMs**. It enables a powerful development loop:
+
+```
+LLM generates JS → Sandbox executes → Results/errors flow back → LLM self-debugs → Stabilize as tool
+```
+
+This provider uses [QuickJS](https://bellard.org/quickjs/) (via WebAssembly) to execute JavaScript in a completely isolated environment with controlled capabilities.
+
+## Installation
+
+```bash
+pnpm add @aigne/afs-sandbox
+```
+
+## Quick Start
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSSandbox } from "@aigne/afs-sandbox";
+
+// Create and mount the sandbox
+const afs = new AFS();
+const sandbox = new AFSSandbox({ name: "sandbox" });
+afs.mount(sandbox);
+
+// Write a script
+await afs.write("/modules/sandbox/scripts/greet.js", {
+  content: `
+    afs.log("info", "Hello from sandbox!");
+    return "Hello, " + args.name;
+  `
+});
+
+// Execute the script
+const result = await afs.exec("/modules/sandbox/@exec/greet", { name: "World" });
+// result.data = { success: true, result: "Hello, World", logs: [...] }
+```
+
+## Features
+
+### Secure Isolation
+
+- **No Node.js globals**: `process`, `require`, `Buffer`, `__dirname` are not available
+- **No network access**: `fetch`, `XMLHttpRequest`, `WebSocket` are blocked
+- **Memory limits**: Configurable memory ceiling (default 128MB)
+- **Timeout protection**: Configurable execution timeout (default 5000ms)
+- **Path traversal protection**: Encoded paths and `..` sequences are blocked
+
+### Capability-Based API
+
+Scripts have access to a controlled `afs` object with whitelisted capabilities:
+
+```javascript
+// Logging
+afs.log("info", "Processing data...");
+afs.log("error", "Something went wrong");
+
+// Read from AFS (requires mount with AFS root)
+const content = afs.read("/modules/fs/config.json");
+
+// Write to AFS (requires write capability enabled)
+afs.write("/modules/data/output.json", JSON.stringify(result));
+
+// List directory contents
+const entries = afs.list("/modules/fs/src");
+```
+
+### Script Storage & Versioning
+
+Scripts are stored at `/scripts/{name}.js` with automatic metadata and version tracking:
+
+**Metadata:**
+- `createdAt` - Creation timestamp
+- `updatedAt` - Last modification timestamp
+- `lastRun` - Last execution timestamp
+- `runCount` - Total execution count
+
+**Version History:**
+- Last 5 versions automatically preserved
+- Access via `/@history/{name}` path
+- Rollback support via `/@actions/rollback`
+
+### Execution Context & History
+
+Track executions with context information:
+
+```typescript
+const result = await afs.exec("/modules/sandbox/@exec/script", args, {
+  context: {
+    userId: "user-123",
+    sessionId: "session-456"
+  }
+});
+```
+
+Execution history is stored per-script with:
+- Execution ID, timestamp, duration
+- Success/failure status
+- Sanitized arguments (sensitive fields redacted)
+
+### Script Templates
+
+Create scripts from built-in templates:
+
+```typescript
+// List available templates
+const templates = await afs.list("/modules/sandbox/@templates");
+
+// Create script from template
+await afs.exec("/modules/sandbox/@actions/create-from-template", {
+  template: "data-transform",
+  name: "my-transformer",
+  variables: {
+    inputField: "rawData",
+    outputField: "processedData"
+  }
+});
+```
+
+**Built-in Templates:**
+- `basic` - Simple script template
+- `data-transform` - Transform input data to output format
+- `validation` - Input validation with error collection
+- `aggregation` - Aggregate multiple values
+
+### Script Promotion (Script → Action)
+
+Promote tested scripts to formal actions:
+
+```typescript
+// Promote a script to an action
+await afs.exec("/modules/sandbox/@actions/promote", {
+  script: "calculator",
+  name: "calculate",
+  description: "Perform arithmetic calculations",
+  inputSchema: {
+    type: "object",
+    properties: {
+      a: { type: "number" },
+      b: { type: "number" },
+      op: { type: "string", enum: ["add", "sub", "mul", "div"] }
+    }
+  }
+});
+
+// Execute the promoted action
+const result = await afs.exec("/modules/sandbox/@actions/calculate", {
+  a: 10, b: 5, op: "mul"
+});
+```
+
+### Audit Logging
+
+Track all sandbox operations for security and debugging:
+
+```typescript
+const sandbox = new AFSSandbox({
+  audit: {
+    enabled: true,
+    onEvent: (event) => console.log(event),
+    maxEntries: 1000
+  }
+});
+
+// Read audit log
+const auditLog = await afs.read("/modules/sandbox/@audit");
+```
+
+**Event Types:**
+- `execution` - Script executions
+- `capability` - Capability usage (read/write/list)
+- `security` - Security-related events (denied access)
+- `script_write` - Script creation/modification
+- `script_delete` - Script deletion
+- `action_promote` - Script promotion to action
+
+### Rate Limiting
+
+Protect against abuse with configurable rate limits:
+
+```typescript
+const sandbox = new AFSSandbox({
+  rateLimit: {
+    maxExecutionsPerMinute: 100,        // Global limit
+    maxExecutionsPerMinutePerUser: 20,  // Per-user limit
+    maxExecutionsPerMinutePerScript: 30 // Per-script limit
+  }
+});
+```
+
+### Execution Metrics
+
+Monitor sandbox performance:
+
+```typescript
+// Global metrics
+const metrics = await afs.read("/modules/sandbox/@metrics");
+// { totalExecutions, successCount, failureCount, timeoutCount, averageDuration }
+
+// Per-script metrics
+const scriptMetrics = await afs.read("/modules/sandbox/@metrics/my-script");
+```
+
+## Configuration
+
+```typescript
+interface AFSSandboxOptions {
+  name?: string;           // Module name (default: "sandbox")
+  description?: string;    // Module description
+  accessMode?: "readonly" | "readwrite";  // Access mode (default: "readwrite")
+
+  runtime?: {
+    timeout?: number;      // Execution timeout in ms (default: 5000)
+    memoryLimit?: number;  // Memory limit in MB (default: 128)
+  };
+
+  capabilities?: {
+    afs?: {
+      read?: boolean;      // Enable afs.read() (default: true)
+      write?: boolean;     // Enable afs.write() (default: false)
+      allowPaths?: string[];  // Allowed path patterns
+      denyPaths?: string[];   // Denied path patterns
+    };
+  };
+
+  audit?: {
+    enabled: boolean;      // Enable audit logging
+    onEvent?: (event) => void;  // Callback for audit events
+    maxEntries?: number;   // Max entries to keep (default: 1000)
+  };
+
+  rateLimit?: {
+    maxExecutionsPerMinute?: number;
+    maxExecutionsPerMinutePerUser?: number;
+    maxExecutionsPerMinutePerScript?: number;
+  };
+}
+```
+
+## Path Structure
+
+```
+/modules/sandbox/
+├── /scripts/                    # Script storage
+│   └── {name}.js               # Script content
+├── /@exec/{name}               # Execute stored script
+├── /@history/{name}            # Script version history
+├── /@actions/
+│   ├── run                     # Run inline code
+│   ├── validate                # Syntax validation
+│   ├── rollback                # Rollback to previous version
+│   ├── promote                 # Promote script to action
+│   ├── create-from-template    # Create script from template
+│   └── {promoted-action}       # User-promoted actions
+├── /@templates                 # List available templates
+│   └── {name}                  # Template details
+├── /@metrics                   # Global execution metrics
+│   └── {script}                # Per-script metrics
+└── /@audit                     # Audit log
+```
+
+## Execution Result
+
+All executions return a structured result:
+
+```typescript
+interface ExecutionResult {
+  success: boolean;
+  result?: unknown;        // Return value (if success)
+  error?: string;          // Error message (if failed)
+  stack?: string;          // Stack trace (if failed)
+  logs: LogEntry[];        // All log entries
+  duration: number;        // Execution time in ms
+  timedOut?: boolean;      // True if execution timed out
+}
+
+interface LogEntry {
+  level: "debug" | "info" | "warn" | "error";
+  message: string;
+  timestamp: number;
+}
+```
+
+## Implementation Status
+
+### Phase 1: POC (Complete) ✅
+
+Core execution loop validated with 47 tests.
+
+| KPI | Status |
+|-----|--------|
+| Basic execution | ✅ `return 2 + 2` → `{ success: true, result: 4 }` |
+| AFS read capability | ✅ `afs.read('/path')` works |
+| Error propagation | ✅ Full error messages with line numbers |
+| Timeout handling | ✅ Infinite loops timeout correctly |
+| Security isolation | ✅ No access to Node.js globals |
+
+### Phase 2: MVP (Complete) ✅
+
+Internal team usable with 54 additional tests (101 total).
+
+| Feature | Status |
+|---------|--------|
+| afs.write() capability | ✅ Write to allowed paths |
+| Script version history | ✅ Last 5 versions preserved |
+| Execution context | ✅ userId, sessionId tracking |
+| Execution history | ✅ Per-script history with redaction |
+| Rollback support | ✅ Restore previous versions |
+
+### Phase 3: Beta (Complete) ✅
+
+Production-ready with 55 additional tests (156 total).
+
+| Feature | Status |
+|---------|--------|
+| Script Promote Workflow | ✅ Promote scripts to formal actions |
+| Script Templates | ✅ 4 built-in templates |
+| Audit Logging | ✅ 6 event types tracked |
+| Rate Limiting | ✅ Global, per-user, per-script |
+| Execution Metrics | ✅ Global and per-script tracking |
+
+### Phase 4+: Future Vision
+
+- Agent Tool Marketplace
+- Multi-agent orchestration
+- Alternative runtimes (Deno)
+- Full async/await support (see Limitations below)
+
+## Known Limitations
+
+### Async/Await Support (Deferred)
+
+**Current State:** Capability calls (`afs.read()`, `afs.write()`, `afs.list()`) work synchronously within scripts. The sandbox does not support full async/await patterns.
+
+| Works | Does Not Work |
+|-------|---------------|
+| `const data = afs.read(path);` | `const data = await afs.read(path);` (across multiple statements) |
+| Single-statement operations | Complex Promise chains |
+| Synchronous data processing | `setTimeout`/`setInterval` |
+
+**Technical Reason:** QuickJS (WebAssembly) executes JavaScript synchronously. While we set up Promise infrastructure for capability calls, the runtime cannot pause execution to wait for external async operations. Implementing full async/await would require:
+
+1. Custom Promise polling mechanism
+2. Careful handle management to avoid memory leaks
+3. Significant changes to the execution model
+
+**Attempted Solution:** We tried implementing async support but encountered QuickJS handle leaks (`list_empty(&rt->gc_obj_list)` assertion failure) when Promises weren't properly resolved before context disposal.
+
+**Future Path:** Phase 4 may introduce Deno runtime as an alternative backend with native async support.
+
+### Other Limitations
+
+- **No ES modules**: `import`/`export` syntax not supported
+- **No top-level await**: Use synchronous patterns
+- **Limited standard library**: Only core JavaScript, no Node.js APIs
+- **Memory ceiling**: Hard limit of configurable MB (default 128MB)
+
+## Design Documents
+
+- **Design Philosophy**: [`/intent/designs/afs-as-llm-runtime.md`](../../intent/designs/afs-as-llm-runtime.md)
+- **Implementation Plan**: [`/intent/plans/sandbox-implementation.md`](../../intent/plans/sandbox-implementation.md)
+
+## Technical Details
+
+### Why QuickJS?
+
+| Option | Pros | Cons |
+|--------|------|------|
+| `isolated-vm` | V8 compatible, fast | Native bindings, doesn't work with Bun |
+| `quickjs-emscripten` | WebAssembly, works everywhere | Slightly slower, sync-only execution |
+| `vm2` | Easy to use | Security vulnerabilities, deprecated |
+
+We chose `quickjs-emscripten` for its universal compatibility (Node.js, Bun, browsers) and strong isolation guarantees.
+
+## Examples
+
+### Simple Calculator
+
+```typescript
+await afs.write("/modules/sandbox/scripts/calc.js", {
+  content: `
+    const { a, b, op } = args;
+    switch(op) {
+      case 'add': return a + b;
+      case 'sub': return a - b;
+      case 'mul': return a * b;
+      case 'div': return b !== 0 ? a / b : 'Division by zero';
+      default: return 'Unknown operation';
+    }
+  `
+});
+
+const result = await afs.exec("/modules/sandbox/@exec/calc", {
+  a: 10, b: 5, op: "mul"
+});
+// result.data.result = 50
+```
+
+### Data Processing with Logging
+
+```typescript
+await afs.write("/modules/sandbox/scripts/process.js", {
+  content: `
+    afs.log("info", "Starting processing...");
+
+    const items = args.items || [];
+    const processed = items.map(item => {
+      afs.log("debug", "Processing: " + JSON.stringify(item));
+      return { ...item, processed: true };
+    });
+
+    afs.log("info", "Completed: " + processed.length + " items");
+    return processed;
+  `
+});
+
+const result = await afs.exec("/modules/sandbox/@exec/process", {
+  items: [{ id: 1 }, { id: 2 }]
+});
+```
+
+### Promote Script to Action
+
+```typescript
+// 1. Develop and test a script
+await afs.write("/modules/sandbox/scripts/greet.js", {
+  content: `return "Hello, " + (args.name || "World") + "!";`
+});
+
+// Test it
+const test = await afs.exec("/modules/sandbox/@exec/greet", { name: "Alice" });
+// test.data.result = "Hello, Alice!"
+
+// 2. Promote to a formal action
+await afs.exec("/modules/sandbox/@actions/promote", {
+  script: "greet",
+  name: "greet-user",
+  description: "Greet a user by name"
+});
+
+// 3. Use the promoted action
+const result = await afs.exec("/modules/sandbox/@actions/greet-user", { name: "Bob" });
+// result.data.result = "Hello, Bob!"
+```
+
+### Error Handling for LLM Debug Loop
+
+```typescript
+// LLM writes code with a bug
+await afs.write("/modules/sandbox/scripts/buggy.js", {
+  content: `
+    const data = JSON.parse(args.json);
+    return data.value.nested.property;  // Bug: doesn't handle missing properties
+  `
+});
+
+// Execute and get error
+const result = await afs.exec("/modules/sandbox/@exec/buggy", {
+  json: '{"value": {}}'
+});
+// result.data = {
+//   success: false,
+//   error: "Cannot read properties of undefined (reading 'property')",
+// }
+
+// LLM sees error, fixes the code
+await afs.write("/modules/sandbox/scripts/buggy.js", {
+  content: `
+    const data = JSON.parse(args.json);
+    return data?.value?.nested?.property ?? 'default';
+  `
+});
+
+// Now it works
+const fixed = await afs.exec("/modules/sandbox/@exec/buggy", {
+  json: '{"value": {}}'
+});
+// fixed.data.result = 'default'
+```
+
+## License
+
+UNLICENSED - Internal use only