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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -38,7 +38,7 @@ await afs.write("/modules/sandbox/scripts/greet.js", {
38
38
  });
39
39
 
40
40
  // Execute the script
41
- const result = await afs.exec("/modules/sandbox/@exec/greet", { name: "World" });
41
+ const result = await afs.exec("/modules/sandbox/scripts/greet.js", { name: "World" });
42
42
  // result.data = { success: true, result: "Hello, World", logs: [...] }
43
43
  ```
44
44
 
@@ -83,15 +83,15 @@ Scripts are stored at `/scripts/{name}.js` with automatic metadata and version t
83
83
 
84
84
  **Version History:**
85
85
  - Last 5 versions automatically preserved
86
- - Access via `/@history/{name}` path
87
- - Rollback support via `/@actions/rollback`
86
+ - Access via `/scripts/{name}.js/@history`
87
+ - Rollback support via `/.actions/rollback`
88
88
 
89
89
  ### Execution Context & History
90
90
 
91
91
  Track executions with context information:
92
92
 
93
93
  ```typescript
94
- const result = await afs.exec("/modules/sandbox/@exec/script", args, {
94
+ const result = await afs.exec("/modules/sandbox/scripts/script.js", args, {
95
95
  context: {
96
96
  userId: "user-123",
97
97
  sessionId: "session-456"
@@ -110,10 +110,10 @@ Create scripts from built-in templates:
110
110
 
111
111
  ```typescript
112
112
  // List available templates
113
- const templates = await afs.list("/modules/sandbox/@templates");
113
+ const templates = await afs.list("/modules/sandbox/templates");
114
114
 
115
115
  // Create script from template
116
- await afs.exec("/modules/sandbox/@actions/create-from-template", {
116
+ await afs.exec("/modules/sandbox/.actions/create-from-template", {
117
117
  template: "data-transform",
118
118
  name: "my-transformer",
119
119
  variables: {
@@ -135,7 +135,7 @@ Promote tested scripts to formal actions:
135
135
 
136
136
  ```typescript
137
137
  // Promote a script to an action
138
- await afs.exec("/modules/sandbox/@actions/promote", {
138
+ await afs.exec("/modules/sandbox/.actions/promote", {
139
139
  script: "calculator",
140
140
  name: "calculate",
141
141
  description: "Perform arithmetic calculations",
@@ -150,7 +150,7 @@ await afs.exec("/modules/sandbox/@actions/promote", {
150
150
  });
151
151
 
152
152
  // Execute the promoted action
153
- const result = await afs.exec("/modules/sandbox/@actions/calculate", {
153
+ const result = await afs.exec("/modules/sandbox/.actions/calculate", {
154
154
  a: 10, b: 5, op: "mul"
155
155
  });
156
156
  ```
@@ -169,7 +169,7 @@ const sandbox = new AFSSandbox({
169
169
  });
170
170
 
171
171
  // Read audit log
172
- const auditLog = await afs.read("/modules/sandbox/@audit");
172
+ const auditLog = await afs.read("/modules/sandbox/audit");
173
173
  ```
174
174
 
175
175
  **Event Types:**
@@ -200,11 +200,11 @@ Monitor sandbox performance:
200
200
 
201
201
  ```typescript
202
202
  // Global metrics
203
- const metrics = await afs.read("/modules/sandbox/@metrics");
203
+ const metrics = await afs.read("/modules/sandbox/metrics");
204
204
  // { totalExecutions, successCount, failureCount, timeoutCount, averageDuration }
205
205
 
206
206
  // Per-script metrics
207
- const scriptMetrics = await afs.read("/modules/sandbox/@metrics/my-script");
207
+ const scriptMetrics = await afs.read("/modules/sandbox/metrics/scripts/my-script");
208
208
  ```
209
209
 
210
210
  ## Configuration
@@ -246,23 +246,27 @@ interface AFSSandboxOptions {
246
246
  ## Path Structure
247
247
 
248
248
  ```
249
- /modules/sandbox/
250
- ├── /scripts/ # Script storage
251
- │ └── {name}.js # Script content
252
- ├── /@exec/{name} # Execute stored script
253
- ├── /@history/{name} # Script version history
254
- ├── /@actions/
255
- ├── run # Run inline code
256
- ├── validate # Syntax validation
257
- ├── rollback # Rollback to previous version
258
- ├── promote # Promote script to action
259
- ├── create-from-template # Create script from template
260
- │ └── {promoted-action} # User-promoted actions
261
- ├── /@templates # List available templates
262
- │ └── {name} # Template details
263
- ├── /@metrics # Global execution metrics
264
- │ └── {script} # Per-script metrics
265
- └── /@audit # Audit log
249
+ /
250
+ ├── scripts/ # Script storage
251
+ │ └── {name}.js # Script file (executable via exec)
252
+ ├── .meta # Script metadata
253
+ ├── .actions/
254
+ │ │ └── exec # Execute the script
255
+ ├── @history # Version history
256
+ └── {version} # Specific version content
257
+ └── @execHistory # Execution history
258
+ ├── templates/ # Script templates
259
+ └── {name} # Template details
260
+ ├── metrics/ # Global execution metrics
261
+ │ └── scripts/{name} # Per-script metrics
262
+ ├── audit/ # Audit log
263
+ └── .actions/ # Root-level actions
264
+ ├── run # Run inline code
265
+ ├── validate # Syntax validation
266
+ ├── rollback # Rollback to previous version
267
+ ├── promote # Promote script to action
268
+ ├── create-from-template # Create script from template
269
+ └── {promoted-action} # User-promoted actions
266
270
  ```
267
271
 
268
272
  ## Execution Result
@@ -287,51 +291,6 @@ interface LogEntry {
287
291
  }
288
292
  ```
289
293
 
290
- ## Implementation Status
291
-
292
- ### Phase 1: POC (Complete) ✅
293
-
294
- Core execution loop validated with 47 tests.
295
-
296
- | KPI | Status |
297
- |-----|--------|
298
- | Basic execution | ✅ `return 2 + 2` → `{ success: true, result: 4 }` |
299
- | AFS read capability | ✅ `afs.read('/path')` works |
300
- | Error propagation | ✅ Full error messages with line numbers |
301
- | Timeout handling | ✅ Infinite loops timeout correctly |
302
- | Security isolation | ✅ No access to Node.js globals |
303
-
304
- ### Phase 2: MVP (Complete) ✅
305
-
306
- Internal team usable with 54 additional tests (101 total).
307
-
308
- | Feature | Status |
309
- |---------|--------|
310
- | afs.write() capability | ✅ Write to allowed paths |
311
- | Script version history | ✅ Last 5 versions preserved |
312
- | Execution context | ✅ userId, sessionId tracking |
313
- | Execution history | ✅ Per-script history with redaction |
314
- | Rollback support | ✅ Restore previous versions |
315
-
316
- ### Phase 3: Beta (Complete) ✅
317
-
318
- Production-ready with 55 additional tests (156 total).
319
-
320
- | Feature | Status |
321
- |---------|--------|
322
- | Script Promote Workflow | ✅ Promote scripts to formal actions |
323
- | Script Templates | ✅ 4 built-in templates |
324
- | Audit Logging | ✅ 6 event types tracked |
325
- | Rate Limiting | ✅ Global, per-user, per-script |
326
- | Execution Metrics | ✅ Global and per-script tracking |
327
-
328
- ### Phase 4+: Future Vision
329
-
330
- - Agent Tool Marketplace
331
- - Multi-agent orchestration
332
- - Alternative runtimes (Deno)
333
- - Full async/await support (see Limitations below)
334
-
335
294
  ## Known Limitations
336
295
 
337
296
  ### Async/Await Support (Deferred)
@@ -344,15 +303,11 @@ Production-ready with 55 additional tests (156 total).
344
303
  | Single-statement operations | Complex Promise chains |
345
304
  | Synchronous data processing | `setTimeout`/`setInterval` |
346
305
 
347
- **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:
306
+ **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.
348
307
 
349
- 1. Custom Promise polling mechanism
350
- 2. Careful handle management to avoid memory leaks
351
- 3. Significant changes to the execution model
308
+ ### In-Memory Storage
352
309
 
353
- **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.
354
-
355
- **Future Path:** Phase 4 may introduce Deno runtime as an alternative backend with native async support.
310
+ 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.
356
311
 
357
312
  ### Other Limitations
358
313
 
@@ -361,11 +316,6 @@ Production-ready with 55 additional tests (156 total).
361
316
  - **Limited standard library**: Only core JavaScript, no Node.js APIs
362
317
  - **Memory ceiling**: Hard limit of configurable MB (default 128MB)
363
318
 
364
- ## Design Documents
365
-
366
- - **Design Philosophy**: [`/intent/designs/afs-as-llm-runtime.md`](../../intent/designs/afs-as-llm-runtime.md)
367
- - **Implementation Plan**: [`/intent/plans/sandbox-implementation.md`](../../intent/plans/sandbox-implementation.md)
368
-
369
319
  ## Technical Details
370
320
 
371
321
  ### Why QuickJS?
@@ -396,7 +346,7 @@ await afs.write("/modules/sandbox/scripts/calc.js", {
396
346
  `
397
347
  });
398
348
 
399
- const result = await afs.exec("/modules/sandbox/@exec/calc", {
349
+ const result = await afs.exec("/modules/sandbox/scripts/calc.js", {
400
350
  a: 10, b: 5, op: "mul"
401
351
  });
402
352
  // result.data.result = 50
@@ -420,7 +370,7 @@ await afs.write("/modules/sandbox/scripts/process.js", {
420
370
  `
421
371
  });
422
372
 
423
- const result = await afs.exec("/modules/sandbox/@exec/process", {
373
+ const result = await afs.exec("/modules/sandbox/scripts/process.js", {
424
374
  items: [{ id: 1 }, { id: 2 }]
425
375
  });
426
376
  ```
@@ -434,18 +384,18 @@ await afs.write("/modules/sandbox/scripts/greet.js", {
434
384
  });
435
385
 
436
386
  // Test it
437
- const test = await afs.exec("/modules/sandbox/@exec/greet", { name: "Alice" });
387
+ const test = await afs.exec("/modules/sandbox/scripts/greet.js", { name: "Alice" });
438
388
  // test.data.result = "Hello, Alice!"
439
389
 
440
390
  // 2. Promote to a formal action
441
- await afs.exec("/modules/sandbox/@actions/promote", {
391
+ await afs.exec("/modules/sandbox/.actions/promote", {
442
392
  script: "greet",
443
393
  name: "greet-user",
444
394
  description: "Greet a user by name"
445
395
  });
446
396
 
447
397
  // 3. Use the promoted action
448
- const result = await afs.exec("/modules/sandbox/@actions/greet-user", { name: "Bob" });
398
+ const result = await afs.exec("/modules/sandbox/.actions/greet-user", { name: "Bob" });
449
399
  // result.data.result = "Hello, Bob!"
450
400
  ```
451
401
 
@@ -461,7 +411,7 @@ await afs.write("/modules/sandbox/scripts/buggy.js", {
461
411
  });
462
412
 
463
413
  // Execute and get error
464
- const result = await afs.exec("/modules/sandbox/@exec/buggy", {
414
+ const result = await afs.exec("/modules/sandbox/scripts/buggy.js", {
465
415
  json: '{"value": {}}'
466
416
  });
467
417
  // result.data = {
@@ -478,7 +428,7 @@ await afs.write("/modules/sandbox/scripts/buggy.js", {
478
428
  });
479
429
 
480
430
  // Now it works
481
- const fixed = await afs.exec("/modules/sandbox/@exec/buggy", {
431
+ const fixed = await afs.exec("/modules/sandbox/scripts/buggy.js", {
482
432
  json: '{"value": {}}'
483
433
  });
484
434
  // fixed.data.result = 'default'
package/dist/index.d.mts CHANGED
@@ -1,5 +1,6 @@
1
+ import { AFSAccessMode, AFSDeleteResult, AFSEntry, AFSExecResult, AFSExplainResult, AFSListResult, AFSModuleLoadParams, AFSRoot, AFSStatResult, AFSWriteEntryPayload, AFSWriteResult } from "@aigne/afs";
2
+ import { AFSBaseProvider, RouteContext } from "@aigne/afs/provider";
1
3
  import { z } from "zod";
2
- import { AFSAccessMode, AFSExecOptions, AFSExecResult, AFSListOptions, AFSListResult, AFSModule, AFSModuleLoadParams, AFSReadOptions, AFSReadResult, AFSRoot, AFSWriteEntryPayload, AFSWriteOptions, AFSWriteResult } from "@aigne/afs";
3
4
 
4
5
  //#region src/types.d.ts
5
6
  /**
@@ -190,11 +191,18 @@ interface AFSSandboxOptions {
190
191
  * AFS Sandbox Provider
191
192
  *
192
193
  * Provides a sandboxed JavaScript execution environment for LLM-generated code.
193
- * Scripts are stored at `/scripts/{name}.js` and executed via `exec()`.
194
+ * Scripts are stored at `/scripts/{name}.js` and executed directly via exec().
194
195
  *
195
- * The sandbox provides a controlled `afs` object with capabilities:
196
- * - `afs.log(level, message)` - Logging
197
- * - `afs.read(path)` - Read from AFS
196
+ * Structure:
197
+ * - `/` - root directory
198
+ * - `/scripts` - stored scripts directory
199
+ * - `/scripts/{name}.js` - individual script files (executable)
200
+ * - `/templates` - script templates
201
+ * - `/templates/{name}` - individual templates
202
+ * - `/metrics` - execution metrics
203
+ * - `/audit` - audit log
204
+ * - `/.actions` - root-level actions (run, validate, promote, create-from-template)
205
+ * - `/scripts/{name}.js/.actions` - script-level actions (exec, history, exec-history)
198
206
  *
199
207
  * @example
200
208
  * ```typescript
@@ -210,11 +218,11 @@ interface AFSSandboxOptions {
210
218
  * });
211
219
  *
212
220
  * // Execute the script
213
- * const result = await afs.exec("/modules/sandbox/@exec/greet", { name: "World" });
221
+ * const result = await afs.exec("/modules/sandbox/scripts/greet.js", { name: "World" });
214
222
  * // result.data = { success: true, result: "Hello, World", logs: [...] }
215
223
  * ```
216
224
  */
217
- declare class AFSSandbox implements AFSModule {
225
+ declare class AFSSandbox extends AFSBaseProvider {
218
226
  readonly name: string;
219
227
  readonly description?: string;
220
228
  readonly accessMode: AFSAccessMode;
@@ -364,69 +372,309 @@ declare class AFSSandbox implements AFSModule {
364
372
  * Loads a module instance from configuration
365
373
  */
366
374
  static load({
367
- parsed
368
- }: AFSModuleLoadParams): Promise<AFSSandbox>;
375
+ config
376
+ }?: AFSModuleLoadParams): Promise<AFSSandbox>;
369
377
  /**
370
378
  * Called when the module is mounted to AFS
371
379
  */
372
380
  onMount(afs: AFSRoot): void;
373
381
  /**
374
- * Normalize a path to remove leading/trailing slashes
382
+ * List root directory children
375
383
  */
376
- private normalizePath;
384
+ listRoot(_ctx: RouteContext): Promise<AFSListResult>;
377
385
  /**
378
- * Log an audit event
386
+ * List all scripts
379
387
  */
380
- private logAudit;
388
+ listScripts(_ctx: RouteContext): Promise<AFSListResult>;
381
389
  /**
382
- * Check if execution is rate limited
390
+ * List script children (@history, @execHistory)
383
391
  */
384
- private checkRateLimit;
392
+ listScript(ctx: RouteContext<{
393
+ scriptName: string;
394
+ }>): Promise<AFSListResult>;
385
395
  /**
386
- * Record execution for rate limiting
396
+ * List @history children (leaf node)
387
397
  */
388
- private recordExecution;
398
+ listScriptHistory(ctx: RouteContext<{
399
+ scriptName: string;
400
+ }>): Promise<AFSListResult>;
389
401
  /**
390
- * Update execution metrics
402
+ * List @execHistory children (leaf node)
391
403
  */
392
- private updateMetrics;
404
+ listScriptExecHistoryEntries(ctx: RouteContext<{
405
+ scriptName: string;
406
+ }>): Promise<AFSListResult>;
393
407
  /**
394
- * Validate action name
408
+ * List all templates
395
409
  */
396
- private isValidActionName;
410
+ listTemplates(_ctx: RouteContext): Promise<AFSListResult>;
397
411
  /**
398
- * Apply template variables to content
412
+ * List template children (leaf node)
399
413
  */
400
- private applyTemplate;
414
+ listTemplate(ctx: RouteContext<{
415
+ templateName: string;
416
+ }>): Promise<AFSListResult>;
417
+ /**
418
+ * List metrics children
419
+ */
420
+ listMetrics(_ctx: RouteContext): Promise<AFSListResult>;
421
+ /**
422
+ * List per-script metrics
423
+ */
424
+ listScriptMetrics(_ctx: RouteContext): Promise<AFSListResult>;
425
+ /**
426
+ * List audit children (leaf node)
427
+ */
428
+ listAudit(_ctx: RouteContext): Promise<AFSListResult>;
429
+ /**
430
+ * List root-level actions
431
+ */
432
+ listRootActions(_ctx: RouteContext): Promise<AFSListResult>;
433
+ /**
434
+ * List script-level actions
435
+ */
436
+ listScriptActions(ctx: RouteContext<{
437
+ scriptName: string;
438
+ }>): Promise<AFSListResult>;
439
+ /**
440
+ * Read root entry
441
+ */
442
+ readRoot(_ctx: RouteContext): Promise<AFSEntry>;
443
+ /**
444
+ * Read scripts directory
445
+ */
446
+ readScriptsDir(_ctx: RouteContext): Promise<AFSEntry>;
447
+ /**
448
+ * Read a specific script
449
+ */
450
+ readScript(ctx: RouteContext<{
451
+ scriptName: string;
452
+ }>): Promise<AFSEntry>;
453
+ /**
454
+ * Read version history for a script
455
+ */
456
+ readScriptHistory(ctx: RouteContext<{
457
+ scriptName: string;
458
+ }>): Promise<AFSEntry>;
459
+ /**
460
+ * Read a specific version
461
+ */
462
+ readScriptVersion(ctx: RouteContext<{
463
+ scriptName: string;
464
+ version: string;
465
+ }>): Promise<AFSEntry>;
466
+ /**
467
+ * Read execution history for a script
468
+ */
469
+ readScriptExecHistory(ctx: RouteContext<{
470
+ scriptName: string;
471
+ }>): Promise<AFSEntry>;
472
+ /**
473
+ * Read templates directory
474
+ */
475
+ readTemplatesDir(_ctx: RouteContext): Promise<AFSEntry>;
476
+ /**
477
+ * Read a specific template
478
+ */
479
+ readTemplate(ctx: RouteContext<{
480
+ templateName: string;
481
+ }>): Promise<AFSEntry>;
482
+ /**
483
+ * Read metrics
484
+ */
485
+ readMetrics(_ctx: RouteContext): Promise<AFSEntry>;
486
+ /**
487
+ * Read per-script metrics
488
+ */
489
+ readScriptMetrics(ctx: RouteContext<{
490
+ scriptName: string;
491
+ }>): Promise<AFSEntry>;
492
+ /**
493
+ * Read audit log
494
+ */
495
+ readAudit(_ctx: RouteContext): Promise<AFSEntry>;
496
+ /**
497
+ * Root metadata
498
+ */
499
+ readRootMeta(_ctx: RouteContext): Promise<AFSEntry>;
500
+ /**
501
+ * Scripts directory metadata
502
+ */
503
+ readScriptsMeta(_ctx: RouteContext): Promise<AFSEntry>;
504
+ /**
505
+ * Script metadata
506
+ */
507
+ readScriptMeta(ctx: RouteContext<{
508
+ scriptName: string;
509
+ }>): Promise<AFSEntry>;
510
+ /**
511
+ * @history metadata
512
+ */
513
+ readScriptHistoryMeta(ctx: RouteContext<{
514
+ scriptName: string;
515
+ }>): Promise<AFSEntry>;
516
+ /**
517
+ * @execHistory metadata
518
+ */
519
+ readScriptExecHistoryMeta(ctx: RouteContext<{
520
+ scriptName: string;
521
+ }>): Promise<AFSEntry>;
522
+ /**
523
+ * Templates directory metadata
524
+ */
525
+ readTemplatesMeta(_ctx: RouteContext): Promise<AFSEntry>;
526
+ /**
527
+ * Template metadata
528
+ */
529
+ readTemplateMeta(ctx: RouteContext<{
530
+ templateName: string;
531
+ }>): Promise<AFSEntry>;
532
+ /**
533
+ * Metrics metadata
534
+ */
535
+ readMetricsMeta(_ctx: RouteContext): Promise<AFSEntry>;
401
536
  /**
402
- * Parse a path into its components
537
+ * Audit metadata
403
538
  */
404
- private parsePath;
539
+ readAuditMeta(_ctx: RouteContext): Promise<AFSEntry>;
540
+ /**
541
+ * Write (create or update) a script
542
+ */
543
+ writeScript(ctx: RouteContext<{
544
+ scriptName: string;
545
+ }>, entry: AFSWriteEntryPayload): Promise<AFSWriteResult>;
546
+ /**
547
+ * Reject writes to @history paths
548
+ */
549
+ writeScriptHistory(_ctx: RouteContext<{
550
+ scriptName: string;
551
+ version: string;
552
+ }>, _entry: AFSWriteEntryPayload): Promise<AFSWriteResult>;
553
+ /**
554
+ * Delete a stored script
555
+ */
556
+ deleteScript(ctx: RouteContext<{
557
+ scriptName: string;
558
+ }>): Promise<AFSDeleteResult>;
559
+ /**
560
+ * Catch-all delete handler for unsupported paths
561
+ */
562
+ deleteCatchAll(ctx: RouteContext<{
563
+ path: string;
564
+ }>): Promise<AFSDeleteResult>;
565
+ /**
566
+ * Execute a stored script directly
567
+ */
568
+ execScript(ctx: RouteContext<{
569
+ scriptName: string;
570
+ }>, args: Record<string, unknown>): Promise<AFSExecResult>;
571
+ /**
572
+ * Execute a stored script directly via exec("/scripts/:name")
573
+ */
574
+ execScriptDirect(ctx: RouteContext<{
575
+ scriptName: string;
576
+ }>, args: Record<string, unknown>): Promise<AFSExecResult>;
577
+ /**
578
+ * Execute root-level actions (run, validate, promote, create-from-template, promoted actions)
579
+ */
580
+ execRootAction(ctx: RouteContext<{
581
+ action: string;
582
+ }>, args: Record<string, unknown>): Promise<AFSExecResult>;
583
+ /**
584
+ * Stat root → sandbox overview
585
+ */
586
+ statRoot(_ctx: RouteContext): Promise<AFSStatResult>;
587
+ /**
588
+ * Stat scripts directory
589
+ */
590
+ statScriptsDir(_ctx: RouteContext): Promise<AFSStatResult>;
591
+ /**
592
+ * Stat a specific script → runCount, lastRun, versionCount
593
+ */
594
+ statScript(ctx: RouteContext<{
595
+ scriptName: string;
596
+ }>): Promise<AFSStatResult>;
597
+ /**
598
+ * Stat templates directory
599
+ */
600
+ statTemplatesDir(_ctx: RouteContext): Promise<AFSStatResult>;
601
+ /**
602
+ * Stat a specific template
603
+ */
604
+ statTemplate(ctx: RouteContext<{
605
+ templateName: string;
606
+ }>): Promise<AFSStatResult>;
607
+ /**
608
+ * Stat metrics directory
609
+ */
610
+ statMetricsDir(_ctx: RouteContext): Promise<AFSStatResult>;
611
+ /**
612
+ * Stat audit directory
613
+ */
614
+ statAuditDir(_ctx: RouteContext): Promise<AFSStatResult>;
615
+ /**
616
+ * Explain root → sandbox overview with security limits, templates, metrics
617
+ */
618
+ explainRoot(_ctx: RouteContext): Promise<AFSExplainResult>;
619
+ /**
620
+ * Explain a specific script → run count, code summary
621
+ */
622
+ explainScript(ctx: RouteContext<{
623
+ scriptName: string;
624
+ }>): Promise<AFSExplainResult>;
625
+ /**
626
+ * Read /.meta/.capabilities → capabilities manifest with action catalog
627
+ */
628
+ readCapabilities(_ctx: RouteContext): Promise<AFSEntry>;
405
629
  /**
406
630
  * Build AFSEntry for a stored script
407
631
  */
408
632
  private buildScriptEntry;
409
633
  /**
410
- * List entries at a path
634
+ * Build scripts directory entry
411
635
  */
412
- list(path: string, _options?: AFSListOptions): Promise<AFSListResult>;
636
+ private buildScriptsDirectoryEntry;
413
637
  /**
414
- * Read a script or action
638
+ * Build templates directory entry
415
639
  */
416
- read(path: string, _options?: AFSReadOptions): Promise<AFSReadResult>;
640
+ private buildTemplatesDirectoryEntry;
417
641
  /**
418
- * Write (create or update) a script
642
+ * Build metrics directory entry
643
+ */
644
+ private buildMetricsDirectoryEntry;
645
+ /**
646
+ * Build audit directory entry
647
+ */
648
+ private buildAuditDirectoryEntry;
649
+ /**
650
+ * Log an audit event
651
+ */
652
+ private logAudit;
653
+ /**
654
+ * Check if execution is rate limited
419
655
  */
420
- write(path: string, entry: AFSWriteEntryPayload, _options?: AFSWriteOptions): Promise<AFSWriteResult>;
656
+ private checkRateLimit;
657
+ /**
658
+ * Record execution for rate limiting
659
+ */
660
+ private recordExecution;
421
661
  /**
422
- * Execute a script or action
662
+ * Update execution metrics
423
663
  */
424
- exec(path: string, args: Record<string, unknown>, options: AFSExecOptions): Promise<AFSExecResult>;
664
+ private updateMetrics;
665
+ /**
666
+ * Validate action name
667
+ */
668
+ private isValidActionName;
669
+ /**
670
+ * Apply template variables to content
671
+ */
672
+ private applyTemplate;
425
673
  /**
426
- * Execute a built-in action
674
+ * Execute a built-in or promoted action
427
675
  */
428
676
  private executeAction;
429
677
  }
430
678
  //#endregion
431
- export { AFSSandbox, type AFSSandboxOptions, type AuditConfig, type AuditEvent, type AuditEventType, type ExecutionMetrics, type ExecutionResult, type LogEntry, type LogLevel, type PromotedAction, type RateLimitConfig, type ScriptTemplate };
679
+ export { AFSSandbox, AFSSandbox as default, type AFSSandboxOptions, type AuditConfig, type AuditEvent, type AuditEventType, type ExecutionMetrics, type ExecutionResult, type LogEntry, type LogLevel, type PromotedAction, type RateLimitConfig, type ScriptTemplate };
432
680
  //# sourceMappingURL=index.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/index.ts"],"mappings":"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"}
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/index.ts"],"mappings":"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"}