@capsule-run/sdk 0.5.2 → 0.6.1

package/README.md

@@ -20,7 +20,7 @@ npm install -g @capsule-run/cli
 npm install @capsule-run/sdk
 ```
 
-## Quick Start
+## Getting started
 
 Create `hello.ts`:
 
@@ -44,6 +44,35 @@ capsule run hello.ts
 
 > Use `--verbose` to display real-time task execution details.
 
+## Integrate Into an Existing Project
+
+The `run()` function lets you execute tasks programmatically from your application code, no CLI needed.
+
+> You need `@capsule-run/cli` in your dependencies to use the `runner` functions in TypeScript.
+
+```typescript
+import { run } from '@capsule-run/sdk/runner';
+
+const result = await run({
+  file: './capsule.ts',
+  args: ['code to execute']
+});
+```
+
+Create `capsule.ts`:
+
+```typescript
+import { task } from "@capsule-run/sdk";
+
+export const main = task({
+  name: "main",
+  compute: "LOW",
+  ram: "64MB"
+}, (code: string): string => {
+  return eval(code);
+});
+```
+
 ## How It Works
 
 Simply use a wrapper function to define your tasks:
@@ -113,6 +142,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"]` |
+| `allowedHosts` | Domains accessible in the sandbox | `string[]` | `["*"]` | `["api.openai.com", "*.anthropic.com"]` |
 | `envVariables` | Environment variables accessible in the sandbox | `string[]` | `[]` | `["API_KEY"]` |
 
 ### Compute Levels
@@ -163,6 +193,24 @@ export const main = task({ name: "main", allowedFiles: ["./data"] }, async () =>
 });
 ```
 
+### 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.
+
+> Wildcards are supported: `*.example.com` matches all subdomains of `example.com`.
+
+```typescript
+import { task } from "@capsule-run/sdk";
+
+export const main = task({
+    name: "main",
+    allowedHosts: ["api.openai.com", "*.anthropic.com"]
+}, async () => {
+    const response = await fetch("https://api.openai.com/v1/models");
+    return response.json();
+});
+```
+
 ### Environment Variables
 
 Tasks can access environment variables to read configuration, API keys, or other runtime settings. Use the standard `process.env`:

package/dist/app.d.ts

@@ -12,6 +12,7 @@ export interface TaskConfig {
     timeout?: string;
     maxRetries?: number;
     allowedFiles?: string[];
+    allowedHosts?: string[];
     envVariables?: string[];
 }
 /**

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;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"}
+{"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;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;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"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkBH,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/run.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Capsule SDK - SDK Runner
+ *
+ * Provides the `run` function for running Capsule tasks
+ * from third party applications.
+ */
+export interface RunnerOptions {
+    file: string;
+    args?: string[];
+    cwd?: string;
+    capsulePath?: string;
+}
+export interface RunnerResult {
+    success: boolean;
+    result: string | number | boolean | object | null;
+    error: {
+        error_type: string;
+        message: string;
+    } | null;
+    execution: {
+        task_name: string;
+        duration_ms: number;
+        retries: number;
+        fuel_consumed: number;
+    };
+}
+/**
+ * Run a Capsule task from a third-party application
+ *
+ * @param options - Runner options
+ * @returns Promise with the runner result
+ */
+export declare function run(options: RunnerOptions): Promise<RunnerResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAClD,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACtD,SAAS,EAAE;QACT,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAYD;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CA0CjE"}

package/dist/run.js

@@ -0,0 +1,60 @@
+/**
+ * Capsule SDK - SDK Runner
+ *
+ * Provides the `run` function for running Capsule tasks
+ * from third party applications.
+ */
+import { execFile } from 'child_process';
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+/**
+ * Get the appropriate capsule command for the current platform
+ */
+function getCapsuleCommand(capsulePath) {
+    if (process.platform === 'win32' && !capsulePath.endsWith('.cmd')) {
+        return `${capsulePath}.cmd`;
+    }
+    return capsulePath;
+}
+/**
+ * Run a Capsule task from a third-party application
+ *
+ * @param options - Runner options
+ * @returns Promise with the runner result
+ */
+export function run(options) {
+    const { file, args = [], cwd, capsulePath = 'capsule' } = options;
+    const command = getCapsuleCommand(capsulePath);
+    const resolvedFile = resolve(cwd || process.cwd(), file);
+    if (!existsSync(resolvedFile)) {
+        return Promise.reject(new Error(`File not found: ${resolvedFile}`));
+    }
+    return new Promise((resolve, reject) => {
+        const cmdArgs = ['run', resolvedFile, '--json', ...args];
+        let executable = command;
+        let executionArgs = cmdArgs;
+        if (process.platform === 'win32') {
+            executable = process.env.comspec || 'cmd.exe';
+            executionArgs = ['/d', '/s', '/c', command, ...cmdArgs];
+        }
+        execFile(executable, executionArgs, { cwd, encoding: 'utf-8' }, (error, stdout, stderr) => {
+            if (error && !stdout) {
+                if (error.code === 'ENOENT') {
+                    reject(new Error(`Capsule CLI not found. Use 'npm install -g @capsule-run/cli' to install it.`));
+                    return;
+                }
+                reject(new Error(stderr || error.message));
+                return;
+            }
+            try {
+                const lines = stdout.trim().split('\n');
+                const jsonLine = lines[lines.length - 1];
+                resolve(JSON.parse(jsonLine));
+            }
+            catch {
+                reject(new Error(`Failed to parse Capsule output: ${stdout}`));
+            }
+        });
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAqBhC;;GAEG;AACH,SAAS,iBAAiB,CAAC,WAAmB;IAC5C,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAClE,OAAO,GAAG,WAAW,MAAM,CAAC;IAC9B,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,GAAG,CAAC,OAAsB;IACxC,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,GAAG,EAAE,WAAW,GAAG,SAAS,EAAE,GAAG,OAAO,CAAC;IAClE,MAAM,OAAO,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAE/C,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;IAEzD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,YAAY,EAAE,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,CAAC;QAEzD,IAAI,UAAU,GAAG,OAAO,CAAC;QACzB,IAAI,aAAa,GAAG,OAAO,CAAC;QAE5B,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;YACjC,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,SAAS,CAAC;YAC9C,aAAa,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC;QAC1D,CAAC;QAED,QAAQ,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxF,IAAI,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;gBACrB,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACvD,MAAM,CAAC,IAAI,KAAK,CACd,6EAA6E,CAC9E,CAAC,CAAC;oBACH,OAAO;gBACT,CAAC;gBACD,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC3C,OAAO;YACT,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACxC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBACzC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,IAAI,KAAK,CAAC,mCAAmC,MAAM,EAAE,CAAC,CAAC,CAAC;YACjE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/task.d.ts

@@ -21,6 +21,8 @@ export interface TaskOptions {
     maxRetries?: number;
     /** Files/folders accessible in the sandbox, e.g., ["./data"] */
     allowedFiles?: string[];
+    /** Allowed hosts for HTTP requests */
+    allowedHosts?: string[];
     /** Environment variables available from your .env file for the task */
     envVariables?: string[];
 }

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,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"}
+{"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,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,CA+D7C"}

package/dist/task.js

@@ -53,6 +53,7 @@ function normalizeTimeout(timeout) {
 export function task(options, fn) {
     const taskName = options.name;
     let compute = options.compute?.toString().toUpperCase() ?? "MEDIUM";
+    let allowedHosts = options.allowedHosts ?? ["*"];
     const taskConfig = {
         name: taskName,
         compute,
@@ -60,6 +61,7 @@ export function task(options, fn) {
         timeout: normalizeTimeout(options.timeout),
         maxRetries: options.maxRetries,
         allowedFiles: options.allowedFiles,
+        allowedHosts,
         envVariables: options.envVariables,
     };
     const wrapper = (...args) => {

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;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"}
+{"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capsule-run/sdk",
-  "version": "0.5.2",
+  "version": "0.6.1",
   "description": "Capsule JavaScript SDK - run AI agent tasks in secure WASM sandboxes",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,6 +15,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./runner": {
+      "types": "./dist/run.d.ts",
+      "import": "./dist/run.js"
+    },
     "./capsule/app.js": {
       "types": "./dist/app.d.ts",
       "import": "./dist/app.js"
@@ -48,6 +52,7 @@
   },
   "devDependencies": {
     "@types/events": "^3.0.3",
+    "@types/node": "^25.2.3",
     "@types/path-browserify": "^1.0.3",
     "@types/readable-stream": "^4.0.18"
   },

package/src/app.ts

@@ -14,6 +14,7 @@ export interface TaskConfig {
   timeout?: string;
   maxRetries?: number;
   allowedFiles?: string[];
+  allowedHosts?: string[];
   envVariables?: string[];
 }
 

package/src/index.ts

@@ -22,3 +22,4 @@ export { default as path } from "./polyfills/path.js";
 export { default as os } from "./polyfills/os.js";
 export { default as process } from "./polyfills/process.js";
 
+

package/src/run.ts

@@ -0,0 +1,89 @@
+/**
+ * Capsule SDK - SDK Runner
+ *
+ * Provides the `run` function for running Capsule tasks
+ * from third party applications.
+ */
+
+import { execFile } from 'child_process';
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+
+export interface RunnerOptions {
+  file: string;
+  args?: string[];
+  cwd?: string;
+  capsulePath?: string;
+}
+
+export interface RunnerResult {
+  success: boolean;
+  result: string | number | boolean | object | null;
+  error: { error_type: string; message: string } | null;
+  execution: {
+    task_name: string;
+    duration_ms: number;
+    retries: number;
+    fuel_consumed: number;
+  };
+}
+
+/**
+ * Get the appropriate capsule command for the current platform
+ */
+function getCapsuleCommand(capsulePath: string): string {
+  if (process.platform === 'win32' && !capsulePath.endsWith('.cmd')) {
+    return `${capsulePath}.cmd`;
+  }
+  return capsulePath;
+}
+
+/**
+ * Run a Capsule task from a third-party application
+ *
+ * @param options - Runner options
+ * @returns Promise with the runner result
+ */
+export function run(options: RunnerOptions): Promise<RunnerResult> {
+  const { file, args = [], cwd, capsulePath = 'capsule' } = options;
+  const command = getCapsuleCommand(capsulePath);
+
+  const resolvedFile = resolve(cwd || process.cwd(), file);
+
+  if (!existsSync(resolvedFile)) {
+    return Promise.reject(new Error(`File not found: ${resolvedFile}`));
+  }
+
+  return new Promise((resolve, reject) => {
+    const cmdArgs = ['run', resolvedFile, '--json', ...args];
+
+    let executable = command;
+    let executionArgs = cmdArgs;
+
+    if (process.platform === 'win32') {
+      executable = process.env.comspec || 'cmd.exe';
+      executionArgs = ['/d', '/s', '/c', command, ...cmdArgs];
+    }
+
+    execFile(executable, executionArgs, { cwd, encoding: 'utf-8' }, (error, stdout, stderr) => {
+      if (error && !stdout) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+          reject(new Error(
+            `Capsule CLI not found. Use 'npm install -g @capsule-run/cli' to install it.`
+          ));
+          return;
+        }
+        reject(new Error(stderr || error.message));
+        return;
+      }
+
+      try {
+        const lines = stdout.trim().split('\n');
+        const jsonLine = lines[lines.length - 1];
+        resolve(JSON.parse(jsonLine));
+      } catch {
+        reject(new Error(`Failed to parse Capsule output: ${stdout}`));
+      }
+    });
+  });
+}

package/src/task.ts

@@ -25,6 +25,8 @@ export interface TaskOptions {
   maxRetries?: number;
   /** Files/folders accessible in the sandbox, e.g., ["./data"] */
   allowedFiles?: string[];
+  /** Allowed hosts for HTTP requests */
+  allowedHosts?: string[];
   /** Environment variables available from your .env file for the task */
   envVariables?: string[];
 }
@@ -100,6 +102,7 @@ export function task<TArgs extends any[], TReturn>(
 ): (...args: TArgs) => TaskReturnType<TReturn> {
   const taskName = options.name;
   let compute = options.compute?.toString().toUpperCase() ?? "MEDIUM";
+  let allowedHosts = options.allowedHosts ?? ["*"];
 
   const taskConfig: TaskConfig = {
     name: taskName,
@@ -108,6 +111,7 @@ export function task<TArgs extends any[], TReturn>(
     timeout: normalizeTimeout(options.timeout),
     maxRetries: options.maxRetries,
     allowedFiles: options.allowedFiles,
+    allowedHosts,
     envVariables: options.envVariables,
   };