@aigne/afs-sandbox 1.11.0-beta.6 → 1.11.0-beta.8

package/README.md

@@ -38,7 +38,7 @@ await afs.write("/modules/sandbox/scripts/greet.js", {
 });
 
 // Execute the script
-const result = await afs.exec("/modules/sandbox/@exec/greet", { name: "World" });
+const result = await afs.exec("/modules/sandbox/scripts/greet.js", { name: "World" });
 // result.data = { success: true, result: "Hello, World", logs: [...] }
 ```
 
@@ -83,15 +83,15 @@ Scripts are stored at `/scripts/{name}.js` with automatic metadata and version t
 
 **Version History:**
 - Last 5 versions automatically preserved
-- Access via `/@history/{name}` path
-- Rollback support via `/@actions/rollback`
+- Access via `/scripts/{name}.js/@history`
+- Rollback support via `/.actions/rollback`
 
 ### Execution Context & History
 
 Track executions with context information:
 
 ```typescript
-const result = await afs.exec("/modules/sandbox/@exec/script", args, {
+const result = await afs.exec("/modules/sandbox/scripts/script.js", args, {
   context: {
     userId: "user-123",
     sessionId: "session-456"
@@ -110,10 +110,10 @@ Create scripts from built-in templates:
 
 ```typescript
 // List available templates
-const templates = await afs.list("/modules/sandbox/@templates");
+const templates = await afs.list("/modules/sandbox/templates");
 
 // Create script from template
-await afs.exec("/modules/sandbox/@actions/create-from-template", {
+await afs.exec("/modules/sandbox/.actions/create-from-template", {
   template: "data-transform",
   name: "my-transformer",
   variables: {
@@ -135,7 +135,7 @@ Promote tested scripts to formal actions:
 
 ```typescript
 // Promote a script to an action
-await afs.exec("/modules/sandbox/@actions/promote", {
+await afs.exec("/modules/sandbox/.actions/promote", {
   script: "calculator",
   name: "calculate",
   description: "Perform arithmetic calculations",
@@ -150,7 +150,7 @@ await afs.exec("/modules/sandbox/@actions/promote", {
 });
 
 // Execute the promoted action
-const result = await afs.exec("/modules/sandbox/@actions/calculate", {
+const result = await afs.exec("/modules/sandbox/.actions/calculate", {
   a: 10, b: 5, op: "mul"
 });
 ```
@@ -169,7 +169,7 @@ const sandbox = new AFSSandbox({
 });
 
 // Read audit log
-const auditLog = await afs.read("/modules/sandbox/@audit");
+const auditLog = await afs.read("/modules/sandbox/audit");
 ```
 
 **Event Types:**
@@ -200,11 +200,11 @@ Monitor sandbox performance:
 
 ```typescript
 // Global metrics
-const metrics = await afs.read("/modules/sandbox/@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");
+const scriptMetrics = await afs.read("/modules/sandbox/metrics/scripts/my-script");
 ```
 
 ## Configuration
@@ -246,23 +246,27 @@ interface AFSSandboxOptions {
 ## 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
+/
+├── scripts/                         # Script storage
+│   └── {name}.js                    # Script file (executable via exec)
+│       ├── .meta                    # Script metadata
+│       ├── .actions/
+│       │   └── exec                 # Execute the script
+│       ├── @history                 # Version history
+│       │   └── {version}            # Specific version content
+│       └── @execHistory             # Execution history
+├── templates/                       # Script templates
+│   └── {name}                       # Template details
+├── metrics/                         # Global execution metrics
+│   └── scripts/{name}               # Per-script metrics
+├── audit/                           # Audit log
+└── .actions/                        # Root-level 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
 ```
 
 ## Execution Result
@@ -287,51 +291,6 @@ interface LogEntry {
 }
 ```
 
-## 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)
@@ -344,15 +303,11 @@ Production-ready with 55 additional tests (156 total).
 | 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:
+**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.
 
-1. Custom Promise polling mechanism
-2. Careful handle management to avoid memory leaks
-3. Significant changes to the execution model
+### In-Memory Storage
 
-**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.
+All scripts, versions, execution history, metrics, and audit logs are stored in memory. Data is lost when the process exits. For persistent storage, consider pairing with an external persistence layer.
 
 ### Other Limitations
 
@@ -361,11 +316,6 @@ Production-ready with 55 additional tests (156 total).
 - **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?
@@ -396,7 +346,7 @@ await afs.write("/modules/sandbox/scripts/calc.js", {
   `
 });
 
-const result = await afs.exec("/modules/sandbox/@exec/calc", {
+const result = await afs.exec("/modules/sandbox/scripts/calc.js", {
   a: 10, b: 5, op: "mul"
 });
 // result.data.result = 50
@@ -420,7 +370,7 @@ await afs.write("/modules/sandbox/scripts/process.js", {
   `
 });
 
-const result = await afs.exec("/modules/sandbox/@exec/process", {
+const result = await afs.exec("/modules/sandbox/scripts/process.js", {
   items: [{ id: 1 }, { id: 2 }]
 });
 ```
@@ -434,18 +384,18 @@ await afs.write("/modules/sandbox/scripts/greet.js", {
 });
 
 // Test it
-const test = await afs.exec("/modules/sandbox/@exec/greet", { name: "Alice" });
+const test = await afs.exec("/modules/sandbox/scripts/greet.js", { name: "Alice" });
 // test.data.result = "Hello, Alice!"
 
 // 2. Promote to a formal action
-await afs.exec("/modules/sandbox/@actions/promote", {
+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" });
+const result = await afs.exec("/modules/sandbox/.actions/greet-user", { name: "Bob" });
 // result.data.result = "Hello, Bob!"
 ```
 
@@ -461,7 +411,7 @@ await afs.write("/modules/sandbox/scripts/buggy.js", {
 });
 
 // Execute and get error
-const result = await afs.exec("/modules/sandbox/@exec/buggy", {
+const result = await afs.exec("/modules/sandbox/scripts/buggy.js", {
   json: '{"value": {}}'
 });
 // result.data = {
@@ -478,7 +428,7 @@ await afs.write("/modules/sandbox/scripts/buggy.js", {
 });
 
 // Now it works
-const fixed = await afs.exec("/modules/sandbox/@exec/buggy", {
+const fixed = await afs.exec("/modules/sandbox/scripts/buggy.js", {
   json: '{"value": {}}'
 });
 // fixed.data.result = 'default'