@capsule-run/sdk 0.4.0 → 0.4.2

package/README.md

@@ -42,7 +42,6 @@ Run it:
 capsule run hello.ts
 ```
 
-> [!TIP]
 > Use `--verbose` to display real-time task execution details.
 
 ## How It Works
@@ -71,7 +70,6 @@ export const main = task({
 });
 ```
 
-> [!NOTE]
 > The runtime requires a task named `"main"` as the entry point.
 
 When you run `capsule run main.ts`, your code is compiled into a WebAssembly module and executed in a dedicated sandbox.
@@ -115,6 +113,7 @@ Every task returns a structured JSON envelope containing both the result and exe
 | `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"]` |
+| `envVariables` | Environment variables accessible in the sandbox | `string[]` | `[]` | `["API_KEY"]` |
 
 ### Compute Levels
 
@@ -171,6 +170,27 @@ Available methods:
 - `files.list(path)` — List directory contents
 - `files.exists(path)` — Check if file exists
 
+### Environment Variables
+
+Tasks can access environment variables to read configuration, API keys, or other runtime settings. Use the `env` API provided by the SDK:
+
+```typescript
+import { task, env } from "@capsule-run/sdk";
+
+export const main = task({
+    name: "main",
+    envVariables: ["API_KEY"]
+}, () => {
+    const apiKey = env.get("API_KEY");
+    return { apiKeySet: apiKey !== undefined };
+});
+```
+
+Available methods:
+- `env.get(key)` — Get a specific environment variable (returns `undefined` if not found)
+- `env.has(key)` — Check if an environment variable exists
+- `env.getAll()` — Get all environment variables as an object
+
 ## Compatibility
 
 ✅ **Supported:**

package/dist/app.d.ts

@@ -12,6 +12,7 @@ export interface TaskConfig {
     timeout?: string;
     maxRetries?: number;
     allowedFiles?: string[];
+    envVariables?: string[];
 }
 /**
  * Register a task function by name with its configuration.

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IACzD,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAID;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC5D,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,UAAU,GACjB,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,GAAG,SAAS,CAE3E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAQD;;;;;GAKG;AACH,qBAAa,UAAU;IACrB;;;OAGG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAuC7C;AAED,eAAO,MAAM,OAAO,YAAmB,CAAC"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IACzD,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAID;;GAEG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC5D,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,UAAU,GACjB,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,GAAG,SAAS,CAE3E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAElE;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAQD;;;;;GAKG;AACH,qBAAa,UAAU;IACrB;;;OAGG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAuC7C;AAED,eAAO,MAAM,OAAO,YAAmB,CAAC"}

package/dist/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,MAAM,KAAK,GAA+B,IAAI,GAAG,EAAE,CAAC;AAEpD;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,IAAO,EACP,MAAkB;IAElB,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC;AAQD;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IACrB;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,QAAgB;QACxB,IAAI,CAAC;YACH,MAAM,IAAI,GAAa,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;YAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;YAEjC,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YAEjC,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;gBACrC,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;YAED,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBAChC,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;gBAChD,IAAI,aAAa,EAAE,CAAC;oBAClB,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YAED,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,uDAAuD,YAAY,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3F,CAAC;YAED,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;YAEzC,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC9B,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC;gBACjC,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC,CAAC;YACzD,CAAC;YAED,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,QAAQ,GAAG,CAAC,YAAY,KAAK;gBACjC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,EAAE;gBAClC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACd,MAAM,QAAQ,CAAC;QACjB,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiBH,MAAM,KAAK,GAA+B,IAAI,GAAG,EAAE,CAAC;AAEpD;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,IAAO,EACP,MAAkB;IAElB,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAClC,CAAC;AAQD;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IACrB;;;OAGG;IACH,KAAK,CAAC,GAAG,CAAC,QAAgB;QACxB,IAAI,CAAC;YACH,MAAM,IAAI,GAAa,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;YAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC;YAEjC,IAAI,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;YAEjC,IAAI,CAAC,QAAQ,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;gBACrC,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;YAED,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;gBAChC,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;gBAChD,IAAI,aAAa,EAAE,CAAC;oBAClB,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YAED,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,uDAAuD,YAAY,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3F,CAAC;YAED,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;YAEzC,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;gBAC9B,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC;gBACjC,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC,CAAC;YACzD,CAAC;YAED,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,QAAQ,GAAG,CAAC,YAAY,KAAK;gBACjC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,EAAE;gBAClC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACd,MAAM,QAAQ,CAAC;QACjB,CAAC;IACH,CAAC;CACF;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC"}

package/dist/env.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Capsule Environment API for WASM environment variables access.
+ * Based on wasi:cli/environment@0.2.0
+ */
+/**
+ * Returns all environment variables as an object.
+ * * @returns An object where keys are variable names and values are their values.
+ * @example { "PORT": "8080" }
+ */
+export declare function getAll(): Record<string, string>;
+/**
+ * Get the value of a specific environment variable.
+ * * @param key - The name of the environment variable.
+ * @returns The value of the variable, or undefined if not found.
+ */
+export declare function get(key: string): string | undefined;
+/**
+ * Check if an environment variable exists.
+ * * @param key - The name of the environment variable.
+ */
+export declare function has(key: string): boolean;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAW/C;AAED;;;;GAIG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWnD;AAED;;;GAGG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExC"}

package/dist/env.js

@@ -0,0 +1,61 @@
+/**
+ * Capsule Environment API for WASM environment variables access.
+ * Based on wasi:cli/environment@0.2.0
+ */
+/**
+ * Internal helper to safely get the WASI environment bindings.
+ */
+function getEnvBindings() {
+    try {
+        const env = globalThis['wasi:cli/environment'];
+        if (env && typeof env.getEnvironment === 'function') {
+            return env;
+        }
+    }
+    catch { }
+    return null;
+}
+/**
+ * Returns all environment variables as an object.
+ * * @returns An object where keys are variable names and values are their values.
+ * @example { "PORT": "8080" }
+ */
+export function getAll() {
+    const bindings = getEnvBindings();
+    if (!bindings)
+        return {};
+    try {
+        const envList = bindings.getEnvironment();
+        return Object.fromEntries(envList);
+    }
+    catch (e) {
+        console.error("Failed to fetch environment variables:", e);
+        return {};
+    }
+}
+/**
+ * Get the value of a specific environment variable.
+ * * @param key - The name of the environment variable.
+ * @returns The value of the variable, or undefined if not found.
+ */
+export function get(key) {
+    const bindings = getEnvBindings();
+    if (!bindings)
+        return undefined;
+    try {
+        const envList = bindings.getEnvironment();
+        const entry = envList.find(([k]) => k === key);
+        return entry ? entry[1] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Check if an environment variable exists.
+ * * @param key - The name of the environment variable.
+ */
+export function has(key) {
+    return get(key) !== undefined;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;GAEG;AACH,SAAS,cAAc;IACrB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,UAAU,CAAC,sBAAsB,CAAC,CAAC;QAC/C,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,UAAU,EAAE,CAAC;YACpD,OAAO,GAAG,CAAC;QACb,CAAC;IACH,CAAC;IAAC,MAAM,CAAC,CAAA,CAAC;IACV,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,MAAM;IACpB,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAC;IAClC,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC;QAC1C,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,wCAAwC,EAAE,CAAC,CAAC,CAAC;QAC3D,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,GAAG,CAAC,GAAW;IAC7B,MAAM,QAAQ,GAAG,cAAc,EAAE,CAAC;IAClC,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAEhC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,QAAQ,CAAC,cAAc,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;QAC/C,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,GAAG,CAAC,GAAW;IAC7B,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;AAChC,CAAC"}

package/dist/index.d.ts

@@ -16,5 +16,6 @@
 export { task, type TaskOptions } from "./task.js";
 export { TaskRunner, exports, type TaskConfig } from "./app.js";
 export * as files from "./files.js";
+export * as env from "./env.js";
 export { isWasmMode } from "./hostApi.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -16,5 +16,6 @@
 export { task } from "./task.js";
 export { TaskRunner, exports } from "./app.js";
 export * as files from "./files.js";
+export * as env from "./env.js";
 export { isWasmMode } from "./hostApi.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAmB,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAoB,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAmB,MAAM,UAAU,CAAC;AAChE,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/task.d.ts

@@ -21,6 +21,22 @@ export interface TaskOptions {
     maxRetries?: number;
     /** Files/folders accessible in the sandbox, e.g., ["./data"] */
     allowedFiles?: string[];
+    /** Environment variables available from your .env file for the task */
+    envVariables?: string[];
 }
-export declare function task<TArgs extends any[], TReturn>(options: TaskOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
+interface TaskResult<T> {
+    success: boolean;
+    result: T;
+    error: string | null;
+    execution: TaskExecution;
+}
+interface TaskExecution {
+    task_name: string;
+    duration_ms: number;
+    retries: number;
+    fuel_consumed: number;
+}
+type TaskReturnType<T> = T extends Promise<infer U> ? Promise<TaskResult<U>> : TaskResult<T>;
+export declare function task<TArgs extends any[], TReturn>(options: TaskOptions, fn: (...args: TArgs) => TReturn): (...args: TArgs) => TaskReturnType<TReturn>;
+export {};
 //# sourceMappingURL=task.d.ts.map

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;CACzB;AAoDD,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,OAAO,CAqC7B"}
+{"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,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,MAAM,GAAG,IAAI,CAAC;IACrB,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,CA6D7C"}

package/dist/task.js

@@ -60,17 +60,39 @@ export function task(options, fn) {
         timeout: normalizeTimeout(options.timeout),
         maxRetries: options.maxRetries,
         allowedFiles: options.allowedFiles,
+        envVariables: options.envVariables,
     };
     const wrapper = (...args) => {
         if (!isWasmMode()) {
-            return fn(...args);
+            const result = fn(...args);
+            if (result instanceof Promise) {
+                return result.then((value) => ({
+                    success: true,
+                    result: value,
+                    error: null,
+                    execution: {
+                        task_name: taskName,
+                        duration_ms: 0,
+                        retries: 0,
+                        fuel_consumed: 0,
+                    },
+                }));
+            }
+            return {
+                success: true,
+                result,
+                error: null,
+                execution: {
+                    task_name: taskName,
+                    duration_ms: 0,
+                    retries: 0,
+                    fuel_consumed: 0,
+                },
+            };
         }
         const resultJson = callHost(taskName, args, taskConfig);
         try {
             const result = JSON.parse(resultJson);
-            if (result.error) {
-                throw new Error(`Task ${taskName} failed: ${result.error}`);
-            }
             return result;
         }
         catch (e) {

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;AA0BpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;IAEpE,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;KACnC,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,GAAG,IAAW,EAAW,EAAE;QAC1C,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC;YAClB,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACrB,CAAC;QAED,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;QAExD,IAAI,CAAC;YACH,MAAM,MAAM,GAAe,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YAClD,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,QAAQ,QAAQ,YAAY,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;YAC9D,CAAC;YACD,OAAO,MAAiB,CAAC;QAC3B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,WAAW,EAAE,CAAC;gBAC7B,OAAO,UAAgC,CAAC;YAC1C,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":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AA2CpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;IAEpE,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,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"}

package/package.json

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

package/src/app.ts

@@ -14,6 +14,7 @@ export interface TaskConfig {
   timeout?: string;
   maxRetries?: number;
   allowedFiles?: string[];
+  envVariables?: string[];
 }
 
 const TASKS: Map<string, TaskInfo<any>> = new Map();

package/src/env.ts

@@ -0,0 +1,67 @@
+/**
+ * Capsule Environment API for WASM environment variables access.
+ * Based on wasi:cli/environment@0.2.0
+ */
+
+declare const globalThis: {
+  'wasi:cli/environment': {
+    getEnvironment(): [string, string][];
+  };
+};
+
+/**
+ * Internal helper to safely get the WASI environment bindings.
+ */
+function getEnvBindings() {
+  try {
+    const env = globalThis['wasi:cli/environment'];
+    if (env && typeof env.getEnvironment === 'function') {
+      return env;
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * Returns all environment variables as an object.
+ * * @returns An object where keys are variable names and values are their values.
+ * @example { "PORT": "8080" }
+ */
+export function getAll(): Record<string, string> {
+  const bindings = getEnvBindings();
+  if (!bindings) return {};
+
+  try {
+    const envList = bindings.getEnvironment();
+    return Object.fromEntries(envList);
+  } catch (e) {
+    console.error("Failed to fetch environment variables:", e);
+    return {};
+  }
+}
+
+/**
+ * Get the value of a specific environment variable.
+ * * @param key - The name of the environment variable.
+ * @returns The value of the variable, or undefined if not found.
+ */
+export function get(key: string): string | undefined {
+  const bindings = getEnvBindings();
+  if (!bindings) return undefined;
+
+  try {
+    const envList = bindings.getEnvironment();
+    const entry = envList.find(([k]) => k === key);
+    return entry ? entry[1] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Check if an environment variable exists.
+ * * @param key - The name of the environment variable.
+ */
+export function has(key: string): boolean {
+  return get(key) !== undefined;
+}

package/src/index.ts

@@ -17,5 +17,6 @@
 export { task, type TaskOptions } from "./task.js";
 export { TaskRunner, exports, type TaskConfig } from "./app.js";
 export * as files from "./files.js";
+export * as env from "./env.js";
 export { isWasmMode } from "./hostApi.js";
 

package/src/task.ts

@@ -25,13 +25,30 @@ export interface TaskOptions {
   maxRetries?: number;
   /** Files/folders accessible in the sandbox, e.g., ["./data"] */
   allowedFiles?: string[];
+  /** Environment variables available from your .env file for the task */
+  envVariables?: string[];
 }
 
-interface TaskResult {
-  result?: any;
-  error?: string;
+interface TaskResult<T> {
+  success: boolean;
+  result: T;
+  error: string | null;
+  execution: TaskExecution;
 }
 
+interface TaskExecution {
+    task_name: string;
+    duration_ms: number;
+    retries: number;
+    fuel_consumed: number;
+}
+
+type Awaited<T> = T extends Promise<infer U> ? U : T;
+
+type TaskReturnType<T> = T extends Promise<infer U>
+  ? Promise<TaskResult<U>>
+  : TaskResult<T>;
+
 /**
  * Define a Capsule task with configuration.
  *
@@ -80,7 +97,7 @@ function normalizeTimeout(timeout?: string | number): string | undefined {
 export function task<TArgs extends any[], TReturn>(
   options: TaskOptions,
   fn: (...args: TArgs) => TReturn
-): (...args: TArgs) => TReturn {
+): (...args: TArgs) => TaskReturnType<TReturn> {
   const taskName = options.name;
   let compute = options.compute?.toString().toUpperCase() ?? "MEDIUM";
 
@@ -91,24 +108,48 @@ export function task<TArgs extends any[], TReturn>(
     timeout: normalizeTimeout(options.timeout),
     maxRetries: options.maxRetries,
     allowedFiles: options.allowedFiles,
+    envVariables: options.envVariables,
   };
 
-  const wrapper = (...args: TArgs): TReturn => {
+  const wrapper = (...args: TArgs): TaskReturnType<TReturn> => {
     if (!isWasmMode()) {
-      return fn(...args);
+      const result = fn(...args);
+
+      if (result instanceof Promise) {
+        return result.then((value) => ({
+          success: true,
+          result: value,
+          error: null,
+          execution: {
+            task_name: taskName,
+            duration_ms: 0,
+            retries: 0,
+            fuel_consumed: 0,
+          },
+        })) as TaskReturnType<TReturn>;
+      }
+
+      return {
+        success: true,
+        result,
+        error: null,
+        execution: {
+          task_name: taskName,
+          duration_ms: 0,
+          retries: 0,
+          fuel_consumed: 0,
+        },
+      } as TaskReturnType<TReturn>;
     }
 
     const resultJson = callHost(taskName, args, taskConfig);
 
     try {
-      const result: TaskResult = JSON.parse(resultJson);
-      if (result.error) {
-        throw new Error(`Task ${taskName} failed: ${result.error}`);
-      }
-      return result as TReturn;
+      const result: TaskResult<Awaited<TReturn>> = JSON.parse(resultJson);
+      return result as TaskReturnType<TReturn>;
     } catch (e) {
       if (e instanceof SyntaxError) {
-        return resultJson as unknown as TReturn;
+        return resultJson as unknown as TaskReturnType<TReturn>;
       }
       throw e;
     }