feat: executor tool invocation for js-exec

Add `executor` option to `BashOptions` that makes a `tools` proxy available
to JavaScript code running in js-exec. Tool calls are synchronous from the
QuickJS sandbox's perspective — they block via SharedArrayBuffer/Atomics
while the host resolves them asynchronously.

Natively integrates with `@executor/sdk` — the `setup` callback receives
the SDK instance for adding OpenAPI, GraphQL, and MCP sources that
auto-discover tools.

## Native SDK integration (OpenAPI, GraphQL, MCP)

```ts
import { Bash } from "just-bash";

const bash = new Bash({
  executor: {
    setup: async (sdk) => {
      // SDK auto-discovers tools from the OpenAPI spec
      await sdk.sources.add({
        kind: "openapi",
        endpoint: "https://petstore3.swagger.io/api/v3",
        specUrl: "https://petstore3.swagger.io/api/v3/openapi.json",
        name: "petstore",
      });

      // GraphQL: introspects the schema
      await sdk.sources.add({
        kind: "graphql",
        endpoint: "https://countries.trevorblades.com/graphql",
        name: "countries",
      });

      // MCP: connects to a Model Context Protocol server
      await sdk.sources.add({
        kind: "mcp",
        endpoint: "https://mcp.example.com/sse",
        name: "internal",
        transport: "sse",
      });
    },
  },
});

// Code runs in QuickJS sandbox — SDK handles HTTP, auth, validation
await bash.exec(`js-exec -c '
  const pets = await tools.petstore.findPetsByStatus({ status: "available" });
  const country = await tools.countries.country({ code: "US" });
  const docs = await tools.internal.searchDocs({ query: "deploy" });
  console.log(pets.length, "pets,", country.name, ",", docs.hits.length, "docs");
'`);
```

## With tool approval

```ts
const bash = new Bash({
  executor: {
    tools: {
      "db.deleteUser": {
        description: "Delete a user from the database",
        execute: async (args) => {
          await db.query("DELETE FROM users WHERE id = $1", [args.id]);
          return { deleted: true };
        },
      },
    },
    setup: async (sdk) => {
      await sdk.sources.add({
        kind: "openapi",
        endpoint: "https://api.stripe.com/v1",
        specUrl: "https://raw.githubusercontent.com/.../stripe-openapi.json",
        name: "stripe",
        auth: { kind: "bearer", token: process.env.STRIPE_SECRET_KEY },
      });
    },
    // SDK passes approval requests through this callback
    onToolApproval: async (request) => {
      // Auto-approve reads, require confirmation for writes/deletes
      if (request.operationKind === "read") return { approved: true };
      const ok = await promptUser(
        `Allow ${request.toolPath} (${request.operationKind})?`
      );
      return ok ? { approved: true } : { approved: false, reason: "denied" };
    },
  },
});
```

## Inline tools (no SDK needed)

```ts
const bash = new Bash({
  executor: {
    tools: {
      "math.add": {
        description: "Add two numbers",
        execute: (args) => ({ sum: args.a + args.b }),
      },
      "db.query": {
        execute: async (args) => {
          const rows = await pg.query(args.sql);
          return { rows };
        },
      },
    },
  },
});

await bash.exec(`js-exec -c '
  const sum = await tools.math.add({ a: 3, b: 4 });
  console.log(sum.sum);

  const data = await tools.db.query({ sql: "SELECT * FROM users" });
  for (const row of data.rows) console.log(row.name);
'`);
```

## Implementation

- New INVOKE_TOOL (400) opcode in the SharedArrayBuffer bridge protocol
- SyncBackend.invokeTool() — worker-side sync call via Atomics.wait
- BridgeHandler accepts optional invokeTool callback, handles new opcode
- Worker registers __invokeTool native function + tools Proxy when
  hasExecutorTools is set
- Tool invoker threads from BashOptions → Bash → InterpreterOptions →
  InterpreterContext → CommandContext → js-exec → BridgeHandler → worker
- executor.setup lazily initializes @executor/sdk on first exec
  (dynamic import — SDK is only loaded when setup is provided)
- SDK's CodeExecutor runtime delegates to js-exec's executeForExecutor
- Full executor mode (log capture + result capture) available via
  executorMode flag for direct SDK integration

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cramforce

knip.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
-  "entry": ["src/cli/just-bash.ts"],
+  "entry": ["src/cli/just-bash.ts", "src/commands/js-exec/executor-adapter.ts"],
   "project": ["src/**/*.ts"],
   "ignore": [
     "src/**/*.test.ts",
@@ -9,6 +9,7 @@
     "src/security/fuzzing/**"
   ],
   "ignoreBinaries": ["tsx"],
+  "ignoreDependencies": ["@executor/sdk"],
   "rules": {
     "unlisted": "off",
     "unresolved": "off",

package.json

@@ -105,8 +105,10 @@
     "vitest": "^4.0.16"
   },
   "dependencies": {
+    "@executor/sdk": "link:/Users/malteubl/ws/vercel/reproductions/executor/packages/platform/sdk-programmatic",
     "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",

pnpm-lock.yaml

@@ -92,6 +92,77 @@ export interface JavaScriptConfig {
   bootstrap?: string;
 }
 
+/** Tool definition for the executor integration */
+export interface ExecutorToolDef {
+  description?: string;
+  // biome-ignore lint/suspicious/noExplicitAny: matches @executor/sdk SimpleTool signature
+  execute: (...args: any[]) => unknown;
+}
+
+/**
+ * Executor SDK instance type (from @executor/sdk).
+ * Kept as an opaque type to avoid requiring the SDK at import time.
+ */
+export interface ExecutorSDKHandle {
+  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;
+}
+
+/** Executor configuration for js-exec tool invocation */
+export interface ExecutorConfig {
+  /** Tool map: keys are dot-separated paths (e.g. "math.add"), values are tool definitions */
+  tools?: Record<string, ExecutorToolDef>;
+  /**
+   * Async setup function that receives the @executor/sdk instance.
+   * Use this to add OpenAPI, GraphQL, or MCP sources that auto-discover tools.
+   * When provided, js-exec delegates execution to the SDK pipeline
+   * (which handles tool approval, auth flows, and interaction loops).
+   *
+   * Requires @executor/sdk as a dependency.
+   *
+   * @example
+   * ```ts
+   * const bash = new Bash({
+   *   executor: {
+   *     setup: async (sdk) => {
+   *       await sdk.sources.add({ kind: "openapi", endpoint: "https://api.example.com", specUrl: "https://api.example.com/openapi.json", name: "myapi" });
+   *       await sdk.sources.add({ kind: "mcp", endpoint: "https://mcp.example.com/sse", name: "tools" });
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  setup?: (sdk: ExecutorSDKHandle) => Promise<void>;
+  /**
+   * Tool approval callback for the @executor/sdk pipeline.
+   * Called when a tool invocation requires approval.
+   * Defaults to "allow-all" when not provided.
+   */
+  onToolApproval?:
+    | "allow-all"
+    | "deny-all"
+    | ((request: {
+        toolPath: string;
+        sourceId: string;
+        sourceName: string;
+        operationKind: "read" | "write" | "delete" | "execute" | "unknown";
+        args: unknown;
+        reason: string;
+        approvalLabel: string | null;
+      }) => Promise<{ approved: true } | { approved: false; reason?: string }>);
+}
+
 export interface BashOptions {
   files?: InitialFiles;
   env?: Record<string, string>;
@@ -137,6 +208,13 @@ export interface BashOptions {
    * Disabled by default. Can be a boolean or a config object with bootstrap code.
    */
   javascript?: boolean | JavaScriptConfig;
+  /**
+   * Executor configuration for tool invocation in js-exec.
+   * When provided, code running in js-exec has access to a `tools` proxy
+   * (e.g. `tools.math.add({ a: 1, b: 2 })`).
+   * Implicitly enables JavaScript if not already enabled.
+   */
+  executor?: ExecutorConfig;
   /**
    * Optional list of command names to register.
    * If not provided, all built-in commands are available.
@@ -277,6 +355,14 @@ export class Bash {
   private defenseInDepthConfig?: DefenseInDepthConfig | boolean;
   private coverageWriter?: FeatureCoverageWriter;
   private jsBootstrapCode?: string;
+  private executorInvokeTool?: (
+    path: string,
+    argsJson: string,
+  ) => Promise<string>;
+  private executorSetup?: (sdk: ExecutorSDKHandle) => Promise<void>;
+  private executorApproval?: ExecutorConfig["onToolApproval"];
+  private executorSDK?: ExecutorSDKHandle;
+  private executorInitPromise?: Promise<void>;
   // biome-ignore lint/suspicious/noExplicitAny: type-erased plugin storage for untyped API
   private transformPlugins: TransformPlugin<any>[] = [];
 
@@ -450,7 +536,8 @@ export class Bash {
     }
 
     // Register javascript commands only when explicitly enabled
-    if (options.javascript) {
+    // (executor config implicitly enables javascript)
+    if (options.javascript || options.executor) {
       for (const cmd of createJavaScriptCommands()) {
         this.registerCommand(cmd);
       }
@@ -464,6 +551,36 @@ export class Bash {
       }
     }
 
+    // Set up executor tool invoker when executor config is provided
+    if (options.executor?.tools) {
+      const tools = options.executor.tools;
+      this.executorInvokeTool = async (
+        path: string,
+        argsJson: string,
+      ): Promise<string> => {
+        if (!Object.hasOwn(tools, path)) {
+          throw new Error(`Unknown tool: ${path}`);
+        }
+        const tool = tools[path];
+        let args: unknown;
+        try {
+          args = argsJson ? JSON.parse(argsJson) : undefined;
+        } catch {
+          args = undefined;
+        }
+        const result = await tool.execute(args);
+        return result !== undefined ? JSON.stringify(result) : "";
+      };
+    }
+
+    // Store SDK setup function and approval callback for lazy initialization
+    if (options.executor?.setup) {
+      this.executorSetup = options.executor.setup;
+    }
+    if (options.executor?.onToolApproval) {
+      this.executorApproval = options.executor.onToolApproval;
+    }
+
     // Register custom commands (after built-ins so they can override)
     if (options.customCommands) {
       for (const cmd of options.customCommands) {
@@ -523,10 +640,102 @@ export class Bash {
     return result;
   }
 
+  /**
+   * Lazily initialize the @executor/sdk when setup is configured.
+   * Creates the SDK instance, runs the user's setup function, and wires
+   * the SDK's tool invocation into the executorInvokeTool callback.
+   */
+  private async ensureExecutorReady(): Promise<void> {
+    if (!this.executorSetup || this.executorSDK) return;
+
+    // Deduplicate concurrent init calls
+    if (this.executorInitPromise) {
+      await this.executorInitPromise;
+      return;
+    }
+
+    this.executorInitPromise = (async () => {
+      // Dynamic import — @executor/sdk and effect are only needed when setup is used
+      const { createExecutor } = await import("@executor/sdk");
+      const { executeForExecutor } = await import(
+        "./commands/js-exec/js-exec.js"
+      );
+      const EffectMod = await import("effect/Effect");
+
+      const self = this;
+      // biome-ignore lint/suspicious/noExplicitAny: CodeExecutor + ToolInvoker types cross package boundaries; validated at runtime by the SDK
+      const runtime: any = {
+        // biome-ignore lint/suspicious/noExplicitAny: ToolInvoker type from @executor/sdk
+        execute(code: string, toolInvoker: any) {
+          return EffectMod.tryPromise(() => {
+            const ctx = {
+              fs: self.fs,
+              cwd: self.state.cwd,
+              env: self.state.env,
+              stdin: "",
+              limits: self.limits,
+            };
+            const invokeTool = async (
+              path: string,
+              argsJson: string,
+            ): Promise<string> => {
+              let args: unknown;
+              try {
+                args = argsJson ? JSON.parse(argsJson) : undefined;
+              } catch {
+                args = undefined;
+              }
+              const result = await EffectMod.runPromise(
+                toolInvoker.invoke({ path, args }),
+              );
+              return result !== undefined ? JSON.stringify(result) : "";
+            };
+            return executeForExecutor(code, ctx, invokeTool);
+          });
+        },
+      };
+
+      const sdk = await createExecutor({
+        runtime,
+        storage: "memory",
+        onToolApproval: this.executorApproval ?? "allow-all",
+      });
+
+      // Run user setup (add sources, configure policies, etc.)
+      if (this.executorSetup) {
+        await this.executorSetup(sdk as unknown as ExecutorSDKHandle);
+      }
+      this.executorSDK = sdk as unknown as ExecutorSDKHandle;
+
+      // Wire SDK execution as the tool invoker for js-exec
+      this.executorInvokeTool = async (
+        path: string,
+        argsJson: string,
+      ): Promise<string> => {
+        // Route through the SDK's execute to get the tool invoker pipeline.
+        // The SDK creates the tool invoker per-execution, so we run a small
+        // code snippet that invokes the tool and returns the result.
+        const escapedPath = path.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+        const sdkHandle = this.executorSDK;
+        if (!sdkHandle) throw new Error("Executor SDK not initialized");
+        const result = await sdkHandle.execute(
+          `return await tools.${escapedPath}(${argsJson || "{}"})`,
+        );
+        if (result.error) throw new Error(result.error);
+        return result.result !== undefined ? JSON.stringify(result.result) : "";
+      };
+    })();
+
+    await this.executorInitPromise;
+  }
+
   async exec(
     commandLine: string,
     options?: ExecOptions,
   ): Promise<BashExecResult> {
+    // Lazily initialize executor SDK if setup was provided
+    await this.ensureExecutorReady();
+
     if (this.state.callDepth === 0) {
       this.state.commandCount = 0;
     }
@@ -666,6 +875,7 @@ export class Bash {
           coverage: this.coverageWriter,
           requireDefenseContext: defenseBox?.isEnabled() === true,
           jsBootstrapCode: this.jsBootstrapCode,
+          executorInvokeTool: this.executorInvokeTool,
         };
 
         const interpreter = new Interpreter(interpreterOptions, execState);