just-bash 2.13.1 → 2.15.0-executor.0

package/dist/commands/js-exec/executor-adapter.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Adapter for using js-exec as a CodeExecutor runtime for @executor/sdk.
+ *
+ * This module exports a Promise-based executor that can be wrapped with
+ * Effect.tryPromise() to satisfy the CodeExecutor interface.
+ *
+ * Usage with @executor/sdk:
+ *
+ * ```ts
+ * import { createJustBashCodeExecutor } from 'just-bash/executor';
+ * import { createExecutor } from '@executor/sdk';
+ * import type { CodeExecutor } from '@executor/sdk';
+ * import * as Effect from 'effect/Effect';
+ *
+ * const jb = createJustBashCodeExecutor();
+ *
+ * const codeExecutor: CodeExecutor = {
+ *   execute: (code, toolInvoker) =>
+ *     Effect.tryPromise(() =>
+ *       jb.execute(code, (path, args) =>
+ *         Effect.runPromise(toolInvoker.invoke({ path, args }))
+ *       )
+ *     ),
+ * };
+ *
+ * const executor = await createExecutor({
+ *   runtime: codeExecutor,
+ *   tools: { ... },
+ * });
+ * ```
+ */
+import type { IFileSystem } from "../../fs/interface.js";
+import type { SecureFetch } from "../../network/index.js";
+import { type ExecutorResult } from "./js-exec.js";
+export interface JustBashExecutorOptions {
+    /** Virtual filesystem for code to access. Defaults to an empty InMemoryFs. */
+    fs?: IFileSystem;
+    /** Working directory inside the sandbox. Defaults to /home/user. */
+    cwd?: string;
+    /** Environment variables available to code. Defaults to empty. */
+    env?: Record<string, string>;
+    /** Network fetch function. Defaults to undefined (no network). */
+    fetch?: SecureFetch;
+}
+export interface JustBashCodeExecutor {
+    /**
+     * Execute code with tool invocation support.
+     *
+     * @param code - JavaScript code to execute. Can use `await` and `return`.
+     *   Tools are available as `tools.namespace.method(args)`.
+     * @param invokeTool - Callback to handle tool invocations.
+     *   Receives (path, args) and should return the tool result.
+     * @returns ExecutorResult with result, error, and captured logs.
+     */
+    execute(code: string, invokeTool: (path: string, args: unknown) => Promise<unknown>): Promise<ExecutorResult>;
+}
+/**
+ * Create a js-exec based code executor for use with @executor/sdk.
+ *
+ * The executor runs JavaScript code in a QuickJS sandbox with:
+ * - A `tools` proxy for invoking registered tools
+ * - Console output captured to `logs` array
+ * - Return value captured in `result`
+ * - Full Node.js-compatible module system (fs, path, etc.)
+ */
+export declare function createJustBashCodeExecutor(options?: JustBashExecutorOptions): JustBashCodeExecutor;

package/dist/commands/js-exec/js-exec.d.ts

@@ -6,6 +6,24 @@
  *
  * This command is Node.js only (uses worker_threads).
  */
-import type { Command } from "../../types.js";
+import type { Command, CommandContext } from "../../types.js";
+/**
+ * Result from executing code in executor mode.
+ * Compatible with @executor/sdk's ExecuteResult shape.
+ */
+export interface ExecutorResult {
+    result: unknown;
+    error?: string;
+    logs?: string[];
+}
+/**
+ * Execute JavaScript code in executor mode with tool invocation support.
+ * Used as the runtime for @executor/sdk's CodeExecutor interface.
+ *
+ * - Console output is captured to `logs` instead of stdout/stderr
+ * - Tool calls via `tools.x.y(args)` are routed through `invokeTool`
+ * - The return value of the code is captured in `result`
+ */
+export declare function executeForExecutor(code: string, ctx: CommandContext, invokeTool: (path: string, argsJson: string) => Promise<string>): Promise<ExecutorResult>;
 export declare const jsExecCommand: Command;
 export declare const nodeStubCommand: Command;

package/dist/commands/js-exec/worker.d.ts

@@ -21,10 +21,18 @@ export interface JsExecWorkerInput {
     isModule?: boolean;
     stripTypes?: boolean;
     timeoutMs?: number;
+    /** When true, tools proxy is available (console still goes to stdout/stderr) */
+    hasExecutorTools?: boolean;
+    /** When true, runs in full executor mode: tools proxy, log capture, result capture */
+    executorMode?: boolean;
 }
 export interface JsExecWorkerOutput {
     protocolToken?: string;
     success: boolean;
     error?: string;
     defenseStats?: WorkerDefenseStats;
+    /** JSON-serialized return value (executor mode only) */
+    executorResult?: string;
+    /** Captured console logs (executor mode only) */
+    executorLogs?: string[];
 }

package/dist/commands/worker-bridge/bridge-handler.d.ts

@@ -22,13 +22,14 @@ export declare class BridgeHandler {
     private secureFetch;
     private maxOutputSize;
     private exec;
+    private invokeTool;
     private protocol;
     private running;
     private output;
     private outputLimitExceeded;
     private startTime;
     private timeoutMs;
-    constructor(sharedBuffer: SharedArrayBuffer, fs: IFileSystem, cwd: string, commandName: string, secureFetch?: SecureFetch | undefined, maxOutputSize?: number, exec?: ((command: string, options: CommandExecOptions) => Promise<ExecResult>) | undefined);
+    constructor(sharedBuffer: SharedArrayBuffer, fs: IFileSystem, cwd: string, commandName: string, secureFetch?: SecureFetch | undefined, maxOutputSize?: number, exec?: ((command: string, options: CommandExecOptions) => Promise<ExecResult>) | undefined, invokeTool?: ((path: string, argsJson: string) => Promise<string>) | undefined);
     /**
      * Returns remaining milliseconds before the overall execution deadline.
      */
@@ -67,5 +68,6 @@ export declare class BridgeHandler {
     private appendOutputLimitError;
     private handleHttpRequest;
     private handleExecCommand;
+    private handleInvokeTool;
     private setErrorFromException;
 }

package/dist/commands/worker-bridge/protocol.d.ts

@@ -38,6 +38,7 @@ export declare const OpCode: {
     readonly EXIT: 102;
     readonly HTTP_REQUEST: 200;
     readonly EXEC_COMMAND: 300;
+    readonly INVOKE_TOOL: 400;
 };
 export type OpCodeType = (typeof OpCode)[keyof typeof OpCode];
 /** Status codes for synchronization */

package/dist/commands/worker-bridge/sync-backend.d.ts

@@ -77,4 +77,9 @@ export declare class SyncBackend {
         stderr: string;
         exitCode: number;
     };
+    /**
+     * Invoke a tool through the main thread's tool invoker (executor mode).
+     * Returns the JSON-serialized result.
+     */
+    invokeTool(path: string, argsJson: string): string;
 }

package/dist/executor-init.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Executor SDK lazy initialization.
+ * Separated from Bash.ts so the browser bundle never sees these imports.
+ * Only loaded at runtime behind a __BROWSER__ guard.
+ */
+import type { ExecutorConfig, ExecutorSDKHandle } from "./Bash.js";
+export declare function initExecutorSDK(setup: (sdk: ExecutorSDKHandle) => Promise<void>, approval: ExecutorConfig["onToolApproval"] | undefined, fs: import("./fs/interface.js").IFileSystem, getCwd: () => string, getEnv: () => Map<string, string>, getLimits: () => import("./limits.js").ExecutionLimits | undefined): Promise<{
+    sdk: ExecutorSDKHandle;
+    invokeTool: (path: string, argsJson: string) => Promise<string>;
+}>;

package/dist/fs/sanitize-error.d.ts

@@ -5,12 +5,15 @@
  * safely be imported in browser bundles.
  */
 /**
- * Sanitize an error message to strip real OS filesystem paths and stack traces.
+ * Sanitize an error message to strip common real OS paths and stack traces.
  *
- * - Replaces common OS path prefixes (/Users/, /home/, /private/, C:\, etc.)
- *   with `<path>` to prevent information leakage about the host filesystem.
- * - Strips stack trace lines (`\n    at ...`).
- * - Preserves error codes (ENOENT, EACCES, etc.) and virtual paths that don't
- *   match known OS prefixes.
+ * Preserves virtual paths that don't match the common host prefixes used by
+ * the default runtime.
  */
 export declare function sanitizeErrorMessage(message: string): string;
+/**
+ * Aggressive sanitizer for host-originated errors such as worker/bootstrap
+ * failures. This also scrubs file:// URLs and additional runtime roots that
+ * are common in hosted environments.
+ */
+export declare function sanitizeHostErrorMessage(message: string): string;

package/dist/interpreter/interpreter.d.ts

@@ -41,6 +41,8 @@ export interface InterpreterOptions {
     requireDefenseContext?: boolean;
     /** Bootstrap JavaScript code for js-exec */
     jsBootstrapCode?: string;
+    /** Tool invoker for executor mode (js-exec) */
+    executorInvokeTool?: (path: string, argsJson: string) => Promise<string>;
 }
 export declare class Interpreter {
     private ctx;

package/dist/interpreter/types.d.ts

@@ -341,4 +341,9 @@ export interface InterpreterContext {
      * Threaded through the context chain instead of shell env.
      */
     jsBootstrapCode?: string;
+    /**
+     * Tool invoker for executor mode (js-exec).
+     * When present, js-exec sets up a `tools` proxy.
+     */
+    executorInvokeTool?: (path: string, argsJson: string) => Promise<string>;
 }

package/dist/network/allow-list.d.ts

@@ -28,8 +28,9 @@ export declare function normalizeAllowListEntry(entry: string): {
  *
  * The matching rules are:
  * 1. Origins must match exactly (case-sensitive for scheme and host)
- * 2. The URL's path must start with the allow-list entry's path
- * 3. If the allow-list entry has no path (or just "/"), all paths are allowed
+ * 2. Path-scoped entries match on path segment boundaries, not raw string prefix
+ * 3. Ambiguous encoded separators (%2f, %5c) are rejected for path-scoped entries
+ * 4. If the allow-list entry has no path (or just "/"), all paths are allowed
  *
  * @param url The URL to check (as a string)
  * @param allowedEntry The allow-list entry to match against

package/dist/network/types.d.ts

@@ -62,8 +62,11 @@ export interface NetworkConfig {
      * - https://api.example.com/v1/users/123
      *
      * But NOT:
+     * - https://api.example.com/v10
+     * - https://api.example.com/v1-admin
      * - https://api.example.com/v2/users
      * - https://api.example.org/v1/users (different origin)
+     * - URLs that rely on ambiguous encoded separators like %2f or %5c
      *
      * Invalid entries (missing scheme, missing host, relative paths) will throw an error.
      */

package/dist/types.d.ts

@@ -182,6 +182,12 @@ export interface CommandContext {
      * user access/injection via environment variables.
      */
     jsBootstrapCode?: string;
+    /**
+     * Tool invoker for executor mode (js-exec).
+     * When present, js-exec sets up a `tools` proxy that routes calls through this.
+     * The function receives (path, argsJson) and returns a JSON result string.
+     */
+    executorInvokeTool?: (path: string, argsJson: string) => Promise<string>;
 }
 export interface Command {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "just-bash",
-  "version": "2.13.1",
+  "version": "2.15.0-executor.0",
   "description": "A simulated bash environment with virtual filesystem",
   "repository": {
     "type": "git",
@@ -44,6 +44,7 @@
     "dist/sandbox/*.d.ts",
     "dist/utils/*.d.ts",
     "vendor/cpython-emscripten/",
+    "vendor/executor/",
     "README.md",
     "dist/AGENTS.md"
   ],
@@ -54,6 +55,38 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "rm -rf dist && tsc && pnpm build:lib && pnpm build:lib:cjs && pnpm build:browser && pnpm build:cli && pnpm build:shell && pnpm build:worker && pnpm build:clean && cp dist/index.d.ts dist/index.d.cts && sed '1,/^-->/d' AGENTS.npm.md > dist/AGENTS.md",
+    "build:clean": "find dist -name '*.test.js' -delete && find dist -name '*.test.d.ts' -delete",
+    "build:worker": "esbuild src/commands/python3/worker.ts --bundle --platform=node --format=esm --outfile=src/commands/python3/worker.js --external:../../../vendor/cpython-emscripten/* && cp src/commands/python3/worker.js dist/commands/python3/worker.js && mkdir -p dist/bin/chunks && cp src/commands/python3/worker.js dist/bin/chunks/worker.js && mkdir -p dist/bundle/chunks && cp src/commands/python3/worker.js dist/bundle/chunks/worker.js && esbuild src/commands/js-exec/worker.ts --bundle --platform=node --format=esm --outfile=src/commands/js-exec/worker.js --external:quickjs-emscripten && cp src/commands/js-exec/worker.js dist/commands/js-exec/worker.js && cp src/commands/js-exec/worker.js dist/bin/chunks/js-exec-worker.js && cp src/commands/js-exec/worker.js dist/bundle/chunks/js-exec-worker.js",
+    "build:lib": "esbuild dist/index.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bundle --chunk-names=chunks/[name]-[hash] --external:diff --external:minimatch --external:sprintf-js --external:turndown --external:sql.js --external:quickjs-emscripten --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs --external:effect --external:@effect/platform --external:@effect/platform-node --external:../vendor/executor/*",
+    "build:lib:cjs": "esbuild dist/index.js --bundle --platform=node --format=cjs --minify --outfile=dist/bundle/index.cjs --external:diff --external:minimatch --external:sprintf-js --external:turndown --external:sql.js --external:quickjs-emscripten --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs --external:effect --external:@effect/platform --external:@effect/platform-node --external:../vendor/executor/*",
+    "build:browser": "esbuild dist/browser.js --bundle --platform=browser --format=esm --minify --outfile=dist/bundle/browser.js --external:diff --external:minimatch --external:sprintf-js --external:turndown --external:node:zlib --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs --define:__BROWSER__=true --alias:node:dns=./src/shims/browser-unsupported.js",
+    "build:cli": "esbuild dist/cli/just-bash.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bin --entry-names=[name] --chunk-names=chunks/[name]-[hash] --banner:js='#!/usr/bin/env node' --external:sql.js --external:quickjs-emscripten --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs --external:effect --external:@effect/platform --external:@effect/platform-node --external:../vendor/executor/*",
+    "build:shell": "esbuild dist/cli/shell.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bin/shell --entry-names=[name] --chunk-names=chunks/[name]-[hash] --banner:js='#!/usr/bin/env node' --external:sql.js --external:quickjs-emscripten --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs",
+    "prepublishOnly": "pnpm validate",
+    "validate": "pnpm lint && pnpm knip && pnpm typecheck &&  pnpm build && pnpm check:worker-sync && pnpm test:run && pnpm test:wasm && pnpm test:dist && pnpm test:examples",
+    "test:examples": "cd examples/cjs-consumer && pnpm install --no-frozen-lockfile && npx tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . && pnpm lint:banned",
+    "check:worker-sync": "node scripts/check-worker-sync.js",
+    "lint:banned": "node scripts/check-banned-patterns.js",
+    "lint:fix": "biome check --write .",
+    "knip": "knip",
+    "test": "vitest",
+    "test:run": "vitest run --exclude src/security/fuzzing/ --exclude src/commands/python3/ --exclude src/commands/sqlite3/ --exclude src/commands/js-exec/ --exclude src/agent-examples/python-scripting.test.ts",
+    "test:dist": "vitest run src/cli/just-bash.bundle.test.ts",
+    "test:unit": "vitest run --config vitest.unit.config.ts",
+    "test:wasm": "vitest run --config vitest.wasm.config.ts",
+    "test:comparison": "vitest run --config vitest.comparison.config.ts",
+    "test:comparison:record": "RECORD_FIXTURES=1 vitest run --config vitest.comparison.config.ts",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:unit": "vitest run --config vitest.unit.config.ts --coverage",
+    "test:fuzz": "vitest run src/security/fuzzing/",
+    "test:fuzz:long": "FUZZ_RUNS=10000 vitest run src/security/fuzzing/",
+    "shell": "npx tsx src/cli/shell.ts",
+    "dev:exec": "npx tsx src/cli/exec.ts"
+  },
   "keywords": [],
   "author": "Malte and Claude",
   "license": "Apache-2.0",
@@ -75,6 +108,7 @@
   "dependencies": {
     "compressjs": "^1.0.3",
     "diff": "^8.0.2",
+    "effect": "^3.21.0",
     "fast-xml-parser": "^5.3.3",
     "file-type": "^21.2.0",
     "ini": "^6.0.0",
@@ -93,36 +127,5 @@
     "@mongodb-js/zstd": "^7.0.0",
     "node-liblzma": "^2.0.3"
   },
-  "packageManager": "pnpm@8.15.9+sha512.499434c9d8fdd1a2794ebf4552b3b25c0a633abcee5bb15e7b5de90f32f47b513aca98cd5cfd001c31f0db454bc3804edccd578501e4ca293a6816166bbd9f81",
-  "scripts": {
-    "build": "rm -rf dist && tsc && pnpm build:lib && pnpm build:lib:cjs && pnpm build:browser && pnpm build:cli && pnpm build:shell && pnpm build:worker && pnpm build:clean && cp dist/index.d.ts dist/index.d.cts && sed '1,/^-->/d' AGENTS.npm.md > dist/AGENTS.md",
-    "build:clean": "find dist -name '*.test.js' -delete && find dist -name '*.test.d.ts' -delete",
-    "build:worker": "esbuild src/commands/python3/worker.ts --bundle --platform=node --format=esm --outfile=src/commands/python3/worker.js --external:../../../vendor/cpython-emscripten/* && cp src/commands/python3/worker.js dist/commands/python3/worker.js && mkdir -p dist/bin/chunks && cp src/commands/python3/worker.js dist/bin/chunks/worker.js && mkdir -p dist/bundle/chunks && cp src/commands/python3/worker.js dist/bundle/chunks/worker.js && esbuild src/commands/js-exec/worker.ts --bundle --platform=node --format=esm --outfile=src/commands/js-exec/worker.js --external:quickjs-emscripten && cp src/commands/js-exec/worker.js dist/commands/js-exec/worker.js && cp src/commands/js-exec/worker.js dist/bin/chunks/js-exec-worker.js && cp src/commands/js-exec/worker.js dist/bundle/chunks/js-exec-worker.js",
-    "build:lib": "esbuild dist/index.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bundle --chunk-names=chunks/[name]-[hash] --external:diff --external:minimatch --external:sprintf-js --external:turndown --external:sql.js --external:quickjs-emscripten --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs",
-    "build:lib:cjs": "esbuild dist/index.js --bundle --platform=node --format=cjs --minify --outfile=dist/bundle/index.cjs --external:diff --external:minimatch --external:sprintf-js --external:turndown --external:sql.js --external:quickjs-emscripten --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs",
-    "build:browser": "esbuild dist/browser.js --bundle --platform=browser --format=esm --minify --outfile=dist/bundle/browser.js --external:diff --external:minimatch --external:sprintf-js --external:turndown --external:node:zlib --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs --define:__BROWSER__=true --alias:node:dns=./src/shims/browser-unsupported.js",
-    "build:cli": "esbuild dist/cli/just-bash.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bin --entry-names=[name] --chunk-names=chunks/[name]-[hash] --banner:js='#!/usr/bin/env node' --external:sql.js --external:quickjs-emscripten --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs",
-    "build:shell": "esbuild dist/cli/shell.js --bundle --splitting --platform=node --format=esm --minify --outdir=dist/bin/shell --entry-names=[name] --chunk-names=chunks/[name]-[hash] --banner:js='#!/usr/bin/env node' --external:sql.js --external:quickjs-emscripten --external:@mongodb-js/zstd --external:node-liblzma --external:compressjs",
-    "validate": "pnpm lint && pnpm knip && pnpm typecheck &&  pnpm build && pnpm check:worker-sync && pnpm test:run && pnpm test:wasm && pnpm test:dist && pnpm test:examples",
-    "test:examples": "cd examples/cjs-consumer && pnpm install --no-frozen-lockfile && npx tsc --noEmit",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check . && pnpm lint:banned",
-    "check:worker-sync": "node scripts/check-worker-sync.js",
-    "lint:banned": "node scripts/check-banned-patterns.js",
-    "lint:fix": "biome check --write .",
-    "knip": "knip",
-    "test": "vitest",
-    "test:run": "vitest run --exclude src/security/fuzzing/ --exclude src/commands/python3/ --exclude src/commands/sqlite3/ --exclude src/commands/js-exec/ --exclude src/agent-examples/python-scripting.test.ts",
-    "test:dist": "vitest run src/cli/just-bash.bundle.test.ts",
-    "test:unit": "vitest run --config vitest.unit.config.ts",
-    "test:wasm": "vitest run --config vitest.wasm.config.ts",
-    "test:comparison": "vitest run --config vitest.comparison.config.ts",
-    "test:comparison:record": "RECORD_FIXTURES=1 vitest run --config vitest.comparison.config.ts",
-    "test:coverage": "vitest run --coverage",
-    "test:coverage:unit": "vitest run --config vitest.unit.config.ts --coverage",
-    "test:fuzz": "vitest run src/security/fuzzing/",
-    "test:fuzz:long": "FUZZ_RUNS=10000 vitest run src/security/fuzzing/",
-    "shell": "npx tsx src/cli/shell.ts",
-    "dev:exec": "npx tsx src/cli/exec.ts"
-  }
-}
+  "packageManager": "pnpm@8.15.9+sha512.499434c9d8fdd1a2794ebf4552b3b25c0a633abcee5bb15e7b5de90f32f47b513aca98cd5cfd001c31f0db454bc3804edccd578501e4ca293a6816166bbd9f81"
+}

package/vendor/executor/executor-sdk-bundle.d.mts

@@ -0,0 +1,18 @@
+/** Vendored @executor/sdk bundle — re-exports createExecutor and types */
+export declare function createExecutor(options: {
+  runtime?: unknown;
+  storage?: unknown;
+  tools?: Record<string, { description?: string; execute: (...args: unknown[]) => unknown }>;
+  onToolApproval?: unknown;
+  onInteraction?: unknown;
+  resolveSecret?: unknown;
+}): Promise<{
+  execute: (code: string) => Promise<{ result: unknown; error?: string; logs?: string[] }>;
+  sources: {
+    add: (input: Record<string, unknown>, options?: Record<string, unknown>) => Promise<unknown>;
+    list: () => Promise<unknown[]>;
+    [key: string]: unknown;
+  };
+  close: () => Promise<void>;
+  [key: string]: unknown;
+}>;