Skip to main content
The kernel package provides the execution runtime, elicitation engine, and tools proxy that power Toolshed’s sandboxed script execution.

​
Runtime interface

interface Runtime {
  execute(script: string): Promise<ExecutionResult>;
  availableTools(): string[];
  dispose(): Promise<void>;
}

​
ExecutionResult

interface ExecutionResult {
  success: boolean;
  value?: unknown;          // Return value from the script
  error?: string;           // Error message if failed
  calls: Array<{            // Tool calls made during execution
    path: string;
    args: Record<string, unknown>;
  }>;
  logs?: Array<{            // Console output
    level: string;
    message: string;
  }>;
  paused?: {                // Present when a destructive tool needs approval
    executionId: string;
    toolPath: string;
    message: string;
    args?: Record<string, unknown>;
  };
}

​
Runtime implementations

​
RuntimeLocal

In-process execution using new Function(). No isolation — suitable only for local development with trusted scripts.

​
RuntimeVercel

Production runtime using Vercel Sandbox (Firecracker microVMs). Provides full isolation with configurable resources. 
interface VercelRuntimeConfig extends RuntimeConfig {
  teamId: string;
  projectId: string;
  token: string;
  snapshotId?: string;
  timeoutMs?: number;     // default: 300000 (5 min)
  vcpus?: number;         // default: 2
  networkPolicy?: NetworkPolicy;
}

​
createRuntime(options)

Factory function that creates and configures a runtime: 
import { createRuntime } from "@toolshed/kernel";

const runtime = createRuntime({
  tools: allTools,
  role: userRole,       // Tools are filtered by role
  invoke: toolInvoker,
  searchTools: searchFn,
  describeTools: describeFn,
  elicitation: engine,
  runtime: "local",     // or "vercel"
});

​
ElicitationEngine

See the Elicitation Guide for usage details.

​
buildProxy(tools, invoke, searchTools?, describeTools?)

Builds the recursive ES Proxy that provides the tools.* namespace inside sandbox scripts.
  • tools.github.issues.list(args) invokes tool path github.issues.list
  • tools.search({ query, limit? }) searches the catalog
  • tools.describe.tool({ path }) gets a tool’s full definition
  • Enumeration is blocked — agents must use tools.search() to discover tools