@executor-js/codemode-core

@executor-js/codemode-core

Core primitives for "code mode" — the pattern where an LLM writes TypeScript/JavaScript that calls into a pre-registered set of tools, executed in a sandbox. This package provides the shared type surface (Tool, SandboxToolInvoker, CodeExecutor), JSON Schema helpers, and error types used by every runtime that implements the contract.

Most callers depend on this transitively through @executor-js/execution and a sandbox runtime like @executor-js/runtime-quickjs. Install directly when you're authoring a new runtime.

Install

bun add @executor-js/codemode-core
# or
npm install @executor-js/codemode-core

Usage

Implement a runtime that satisfies CodeExecutor:

import type { CodeExecutor, ExecuteResult, SandboxToolInvoker } from "@executor-js/codemode-core";
import { Effect } from "effect";

export const makeMyRuntime = (): CodeExecutor => ({
  execute: (code: string, invoker: SandboxToolInvoker) =>
    Effect.gen(function* () {
      // Spin up your sandbox, expose `invoker` as `tools.<path>(...)`, run
      // the code, collect logs, and return an ExecuteResult.
      void code;
      void invoker;
      const result: ExecuteResult = { result: undefined, logs: [] };
      return result;
    }),
});

The runtime is passed a SandboxToolInvoker that bridges sandbox-side tool calls back to the executor. The sandbox-visible API is whatever you decide — @executor-js/runtime-quickjs exposes a tools proxy object; a runtime targeting Cloudflare Workers might use something else.

Status

Pre-1.0. APIs may still change between beta releases. Part of the executor monorepo.

License

MIT