Skip to content

core

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

core

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
__tests__
__tests__
 
 
etc
etc
 
 
src
src
 
 
test-support
test-support
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 
tsdown.config.ts
tsdown.config.ts
 
 

README.md

@execbox/core

Provider, schema, and MCP adapter contracts for execbox. Use it to resolve host tools into callable guest namespaces before running code with an executor such as @execbox/quickjs.

npm version License Docs

Use @execbox/core When

  • you want to expose host capabilities to guest code through explicit tool providers
  • you want one execution contract across inline and worker-hosted QuickJS
  • you want to wrap MCP servers or clients into callable namespaces

Pair It With an Executor

@execbox/core defines the provider and tool boundary. Guest execution happens in an executor package.

Package Start here when
@execbox/quickjs You want the default path with inline or worker-hosted QuickJS.

Install

Most users start with QuickJS:

npm install @execbox/core @execbox/quickjs

Provider Boundary

Providers are explicit capability grants. resolveProvider() validates the namespace, normalizes tool schemas, creates guest-safe tool names, wraps tool execution with schema checks, and keeps original-to-safe name maps for callers that need to explain MCP or generated tool names.

Tool inputs and results should be JSON-compatible data. Keep host-only values such as clients, handles, secrets, and tenant routing inside the tool implementation.

Runtime Implementer Surface

Most application code can skip this section.

Application code should usually import from @execbox/core or @execbox/core/mcp. The @execbox/core/protocol and @execbox/core/runtime subpaths exist for execbox-owned runtime packages. @execbox/core/protocol carries the worker-hosted QuickJS message contract, while @execbox/core/runtime contains the manifest dispatcher, runtime option defaults, timeout helpers, log formatting, code normalization, and error normalization used to keep runtime implementations aligned.

Smallest Working Usage

import { resolveProvider } from "@execbox/core";
import { QuickJsExecutor } from "@execbox/quickjs";

const provider = resolveProvider({
  name: "tools",
  tools: {
    greet: {
      inputSchema: {
        type: "object",
        required: ["name"],
        properties: {
          name: { type: "string" },
        },
      },
      execute: async (input) => ({
        message: `Hello, ${(input as { name: string }).name}!`,
      }),
    },
  },
});

const executor = new QuickJsExecutor();
const result = await executor.execute(`await tools.greet({ name: "World" })`, [
  provider,
]);

console.log(result);

MCP Support

Use @execbox/core/mcp when you want MCP on either side of the provider boundary:

  • wrap an upstream MCP server or client into a provider with createMcpToolProvider() or openMcpToolProvider()
  • expose execbox code execution back out through an MCP server with codeMcpServer()
  • preserve raw MCP CallToolResult envelopes so guest code can inspect structuredContent first and fall back to content

Operational Notes

  • Providers are the capability boundary. If guest code can call a tool, it can exercise that authority.
  • Execbox gives you JSON-only tool/result boundaries, schema validation, bounded logs, and timeout-aware execution controls.
  • Hard isolation depends on the executor and deployment boundary you choose, not on @execbox/core by itself.

Read Next