@capsule-run/sdk 0.6.4 → 0.7.0

package/README.md

@@ -173,7 +173,7 @@ Every task returns a structured JSON envelope containing both the result and exe
 | `ram` | Memory limit | `string` | unlimited | `"512MB"`, `"2GB"` |
 | `timeout` | Maximum execution time | `string` or `number` | unlimited | `"30s"`, `"5m"` |
 | `maxRetries` | Retry attempts on failure | `number` | `0` | `3` |
-| `allowedFiles` | Folders accessible in the sandbox | `string[]` | `[]` | `["./data", "./output"]` |
+| `allowedFiles` | Folders accessible in the sandbox (with optional access mode) | `(string \| AllowedFile)[]` | `[]` | `["./data"]`, `[{ path: "./data", mode: "ro" }]` |
 | `allowedHosts` | Domains accessible in the sandbox | `string[]` | `["*"]` | `["api.openai.com", "*.anthropic.com"]` |
 | `envVariables` | Environment variables accessible in the sandbox | `string[]` | `[]` | `["API_KEY"]` |
 
@@ -206,25 +206,31 @@ Task-level options always override these defaults.
 
 Tasks can read and write files within directories specified in `allowedFiles`. Any attempt to access files outside these directories is not possible.
 
+> `allowedFiles` supports directory paths only, not individual files.
+
+Each entry can be a plain path (read-write by default) or an `AllowedFile` object with an explicit `mode`: `"read-only"` (or `"ro"`) or `"read-write"` (or `"rw"`).
+
 Common Node.js built-ins are available. Use the standard `fs` module:
 
 ```typescript
 import { task } from "@capsule-run/sdk";
 import fs from "fs/promises";
 
-export const restrictedWriter = task({
-    name: "restricted_writer",
-    allowedFiles: ["./output"]
+export const main = task({
+    name: "main",
+    allowedFiles: [
+        { path: "./data", mode: "read-only" },
+        { path: "./output", mode: "read-write" },
+    ]
 }, async () => {
-    await fs.writeFile("./output/result.txt", "result");
-});
-
-export const main = task({ name: "main", allowedFiles: ["./data"] }, async () => {
-    await restrictedWriter();
-    return await fs.readFile("./data/input.txt", "utf8");
+    const content = await fs.readFile("./data/input.txt", "utf8");
+    await fs.writeFile("./output/result.txt", content);
+    return content;
 });
 ```
 
+Plain strings are still accepted: `allowedFiles: ["./output"]` defaults to read-write.
+
 ### Network Access
 
 Tasks can make HTTP requests to domains specified in `allowedHosts`. By default, all outbound requests are allowed (`[\"*\"]`). Restrict access by providing a whitelist of domains.

package/dist/task.d.ts

@@ -4,6 +4,12 @@
  * Provides the `task` wrapper function for defining Capsule tasks
  * in an idiomatic TypeScript way.
  */
+export interface AllowedFile {
+    /** Path to the directory, e.g., "./data" */
+    path: string;
+    /** Access mode: "read-only" / "ro" or "read-write" / "rw" (default) */
+    mode?: "read-only" | "read-write" | "ro" | "rw";
+}
 export interface TaskOptions {
     /** Task name (required) */
     name: string;
@@ -19,8 +25,8 @@ export interface TaskOptions {
     timeout?: string | number;
     /** Maximum number of retries */
     maxRetries?: number;
-    /** Files/folders accessible in the sandbox, e.g., ["./data"] */
-    allowedFiles?: string[];
+    /** Files/folders accessible in the sandbox, e.g., ["./data"] or [{ path: "./data", mode: "ro" }] */
+    allowedFiles?: (string | AllowedFile)[];
     /** Allowed hosts for HTTP requests */
     allowedHosts?: string[];
     /** Environment variables available from your .env file for the task */

package/dist/task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7C,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,UAAU,UAAU,CAAC,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;IACV,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtD,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,UAAU,aAAa;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACzB;AAID,KAAK,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAC/C,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GACtB,UAAU,CAAC,CAAC,CAAC,CAAC;AA+ClB,wBAAgB,IAAI,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,OAAO,EAC/C,OAAO,EAAE,WAAW,EACpB,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAC9B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,cAAc,CAAC,OAAO,CAAC,CA+D7C"}
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,IAAI,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,IAAI,GAAG,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,WAAW;IAC1B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7C,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oGAAoG;IACpG,YAAY,CAAC,EAAE,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC;IACxC,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,UAAU,UAAU,CAAC,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,CAAC,CAAC;IACV,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtD,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,UAAU,aAAa;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACzB;AAID,KAAK,cAAc,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAC/C,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GACtB,UAAU,CAAC,CAAC,CAAC,CAAC;AAiElB,wBAAgB,IAAI,CAAC,KAAK,SAAS,GAAG,EAAE,EAAE,OAAO,EAC/C,OAAO,EAAE,WAAW,EACpB,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAC9B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,cAAc,CAAC,OAAO,CAAC,CA+D7C"}

package/dist/task.js

@@ -50,6 +50,22 @@ function normalizeTimeout(timeout) {
     }
     return timeout;
 }
+function normalizeAllowedFile(entry) {
+    if (typeof entry === "string")
+        return entry;
+    switch (entry.mode) {
+        case undefined:
+        case "rw":
+        case "read-write":
+            return entry.path;
+        case "ro":
+        case "read-only":
+            return `${entry.path}:ro`;
+        default:
+            throw new Error(`Invalid allowed_files mode '${entry.mode}' for path '${entry.path}'. ` +
+                `Use 'read-only' or 'read-write'.`);
+    }
+}
 export function task(options, fn) {
     const taskName = options.name;
     let compute = options.compute?.toString().toUpperCase() ?? "MEDIUM";
@@ -60,7 +76,7 @@ export function task(options, fn) {
         ram: options.ram,
         timeout: normalizeTimeout(options.timeout),
         maxRetries: options.maxRetries,
-        allowedFiles: options.allowedFiles,
+        allowedFiles: options.allowedFiles?.map(normalizeAllowedFile),
         allowedHosts,
         envVariables: options.envVariables,
     };

package/dist/task.js.map

@@ -1 +1 @@
-{"version":3,"file":"task.js","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AA6CpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,OAAyB;IACjD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,GAAG,OAAO,IAAI,CAAC;IACxB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,IAAI,CAClB,OAAoB,EACpB,EAA+B;IAE/B,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9B,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,WAAW,EAAE,IAAI,QAAQ,CAAC;IACpE,IAAI,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,CAAC,GAAG,CAAC,CAAC;IAEjD,MAAM,UAAU,GAAe;QAC7B,IAAI,EAAE,QAAQ;QACd,OAAO;QACP,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1C,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,YAAY;QACZ,YAAY,EAAE,OAAO,CAAC,YAAY;KACnC,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,GAAG,IAAW,EAA2B,EAAE;QAC1D,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;YAE3B,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC9B,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBAC7B,OAAO,EAAE,IAAI;oBACb,MAAM,EAAE,KAAK;oBACb,KAAK,EAAE,IAAI;oBACX,SAAS,EAAE;wBACT,SAAS,EAAE,QAAQ;wBACnB,WAAW,EAAE,CAAC;wBACd,OAAO,EAAE,CAAC;wBACV,aAAa,EAAE,CAAC;qBACjB;iBACF,CAAC,CAA4B,CAAC;YACjC,CAAC;YAED,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,MAAM;gBACN,KAAK,EAAE,IAAI;gBACX,SAAS,EAAE;oBACT,SAAS,EAAE,QAAQ;oBACnB,WAAW,EAAE,CAAC;oBACd,OAAO,EAAE,CAAC;oBACV,aAAa,EAAE,CAAC;iBACjB;aACyB,CAAC;QAC/B,CAAC;QAED,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QAExD,IAAI,CAAC;YACH,MAAM,MAAM,GAAiC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACpE,OAAO,MAAiC,CAAC;QAC3C,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,WAAW,EAAE,CAAC;gBAC7B,OAAO,UAAgD,CAAC;YAC1D,CAAC;YACD,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC,CAAC;IAEF,YAAY,CAAC,QAAQ,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IAEvC,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../src/task.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capsule-run/sdk",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Capsule JavaScript SDK - run AI agent tasks in secure WASM sandboxes",
   "type": "module",
   "main": "./dist/index.js",

package/src/task.ts

@@ -8,6 +8,13 @@
 import { registerTask, type TaskConfig } from "./app.js";
 import { isWasmMode, callHost } from "./hostApi.js";
 
+export interface AllowedFile {
+  /** Path to the directory, e.g., "./data" */
+  path: string;
+  /** Access mode: "read-only" / "ro" or "read-write" / "rw" (default) */
+  mode?: "read-only" | "read-write" | "ro" | "rw";
+}
+
 export interface TaskOptions {
   /** Task name (required) */
   name: string;
@@ -23,8 +30,8 @@ export interface TaskOptions {
   timeout?: string | number;
   /** Maximum number of retries */
   maxRetries?: number;
-  /** Files/folders accessible in the sandbox, e.g., ["./data"] */
-  allowedFiles?: string[];
+  /** Files/folders accessible in the sandbox, e.g., ["./data"] or [{ path: "./data", mode: "ro" }] */
+  allowedFiles?: (string | AllowedFile)[];
   /** Allowed hosts for HTTP requests */
   allowedHosts?: string[];
   /** Environment variables available from your .env file for the task */
@@ -96,6 +103,24 @@ function normalizeTimeout(timeout?: string | number): string | undefined {
   return timeout;
 }
 
+function normalizeAllowedFile(entry: string | AllowedFile): string {
+  if (typeof entry === "string") return entry;
+  switch (entry.mode) {
+    case undefined:
+    case "rw":
+    case "read-write":
+      return entry.path;
+    case "ro":
+    case "read-only":
+      return `${entry.path}:ro`;
+    default:
+      throw new Error(
+        `Invalid allowed_files mode '${(entry as any).mode}' for path '${entry.path}'. ` +
+        `Use 'read-only' or 'read-write'.`
+      );
+  }
+}
+
 export function task<TArgs extends any[], TReturn>(
   options: TaskOptions,
   fn: (...args: TArgs) => TReturn
@@ -110,7 +135,7 @@ export function task<TArgs extends any[], TReturn>(
     ram: options.ram,
     timeout: normalizeTimeout(options.timeout),
     maxRetries: options.maxRetries,
-    allowedFiles: options.allowedFiles,
+    allowedFiles: options.allowedFiles?.map(normalizeAllowedFile),
     allowedHosts,
     envVariables: options.envVariables,
   };