Agents, agent clusters & realms

A map for threads and globals

JavaScript has a few words that sound alike but answer different questions. An agent explains who executes JavaScript. An agent cluster explains which agents may share selected state. A realm explains which global object and built-in constructors a piece of code uses.

This lesson follows Modules through a bundler. It prepares you for How workers work, where the cost of creating agents and sending data becomes practical.

What an agent is

In plain words, an agent is one teacher working through one thing at a time. It has its own call stack, its own job queue, and a set of classrooms. A browser window is an agent, and each worker is another agent.

console.log(typeof globalThis, typeof Array);

Line 1 asks what two names are. It prints object function: globalThis is an object, and Array is a constructor function. This says nothing about another worker, because that worker has its own global environment.

Agents can run in parallel when the host provides separate threads. The important boundary is still simple: ordinary code in one worker does not share its globalThis with the page.

Agent clusters and shared memory

An agent cluster groups agents that are allowed to share selected things. Most values passed to a worker are copied with structured clone. A SharedArrayBuffer is different: multiple agents can view the same bytes when the browser allows it.

const bytes = new SharedArrayBuffer(4);
const pageView = new Int32Array(bytes);
const workerView = new Int32Array(bytes);
pageView[0] = 3;
console.log(workerView[0]);

Line 1 allocates four shared bytes. Lines 2 and 3 make two views of those bytes. Line 4 writes 3, so line 5 prints 3. This is deliberately marked Node or worker-style teaching code because ordinary page sandbox examples cannot promise the needed isolation headers.

Browsers generally require cross-origin isolation before exposing SharedArrayBuffer. Sharing bytes also does not make coordination safe; agents use Atomics when reads and writes must agree.

1const pageAgent = { cluster: "school", memory: new Int32Array(1) };Run2const workerAgent = { cluster: "school", memory: pageAgent.memory };3 4pageAgent.memory[0] = 3;5console.log(workerAgent.memory[0]);

Realms and intrinsics

A realm is a global environment with its own intrinsic objects. An iframe is a familiar browser example: it has another globalThis, another Array, another Object.prototype, and another Promise.

const frame = document.createElement("iframe");
document.body.append(frame);

const frameArray = new frame.contentWindow.Array("tea");
console.log(frameArray instanceof Array);
console.log(Array.isArray(frameArray));
console.log(frame.contentWindow.Array === Array);

Line 1 creates an iframe. Line 4 makes an array using the iframe realm's constructor. Line 5 prints false because that array does not inherit from the page's Array.prototype. Line 6 prints true, and line 7 prints false.

Run this in a normal page with a same-origin iframe. The lesson editor's opaque-origin sandbox cannot read properties from the frame's contentWindow.

A realm is not a thread. One agent can host several realms. The distinction matters because a new iframe can change constructor identity without promising work runs on another CPU.

Cross-realm checks

instanceof follows a prototype chain and asks whether a specific prototype occurs in it. That works inside one realm, but it is a fragile type check at an iframe or worker-facing boundary.

1const pageArray = ["tea"];Run2const frameArray = ["tea"]; // made with the frame's Array3 4function check(value) {5  return {6    instanceofArray: value.realm === "page",7    isArray: true,8  };9}10 11console.log(check({ realm: "frame", value: frameArray }));

The replay walks an array made in a second realm. The page's Array is not in that array's prototype chain, so the model returns false for instanceof. Array.isArray instead checks the array nature of the value, so it returns true.

A shared symbol registry

Realms have separate intrinsics, but not every identity is realm-local. The global symbol registry is associated with an agent cluster. That makes Symbol.for useful for a shared key, while plain Symbol() always creates a fresh symbol.

const frame = document.createElement("iframe");
document.body.append(frame);

const pageKey = Symbol.for("cart");
const frameKey = frame.contentWindow.Symbol.for("cart");
console.log(pageKey === frameKey);

Line 4 asks the page registry for cart. Line 5 asks the iframe's realm in the same cluster for the same key. Line 6 prints true. This does not mean all objects are shared; it is one registry rule.

Run this in a normal page with a same-origin iframe; the editor's opaque-origin sandbox blocks access to the frame's contentWindow.

Do not use this fact as a data channel. Send data explicitly, and use symbols only when symbol identity is the intent.

The ShadowRealm proposal

ShadowRealm is a TC39 proposal for creating a fresh realm inside the current agent. It gives that realm a separate global environment and separate intrinsics without claiming a new thread.

if (typeof ShadowRealm === "function") {
  const realm = new ShadowRealm();
  console.log("available");
} else {
  console.log("not available");
}

Line 1 checks before use. In September 2026 the proposal repository reports Stage 2.7. That is a proposal stage, not a guarantee that browsers ship the API, so this lesson never claims availability and the example feature-detects it.

Its goal is isolation of globals and intrinsics within the same agent. It is not a replacement for workers, cross-origin policy, or a security sandbox for untrusted code.

Two teachers, two classrooms

Use this model to change one boundary at a time. Pick the classroom that makes an array, then the classroom that checks it. Finally decide whether the two teachers are in the same building, which represents a cluster that may share memory.

const sameRealm = madeIn === checkedIn;
console.log(sameRealm);       // instanceof Array model
console.log(true);            // Array.isArray model
console.log(true);            // Symbol.for cart key model
console.log(sameCluster);     // shared-memory permission model

When classrooms differ, the model shows instanceof Array as false while Array.isArray remains true. Its symbol result stays true because the global symbol registry belongs to the modeled cluster. Turning off the shared building removes shared-memory permission.

Practical boundaries

Most app code meets this lesson at an iframe, a worker, a testing VM context, or a library that receives values from elsewhere. Start with plain data and a documented message shape. Structured cloning makes the boundary visible and avoids inherited prototype surprises.

import vm from "node:vm";

const list = vm.runInNewContext("[]");
console.log(list instanceof Array);
console.log(Array.isArray(list));
console.log(vm.runInNewContext("Symbol.for('cart')") === Symbol.for("cart"));

Node's vm.createContext creates a fresh realm. The three logs are false, true, and true. The first two show the same iframe lesson without a browser; the third verifies the cluster-level symbol registry behavior.

import { Worker, isMainThread, parentPort } from "node:worker_threads";

if (isMainThread) {
  globalThis.schoolName = "Page school";
  new Worker(new URL(import.meta.url)).once("message", console.log);
} else {
  parentPort.postMessage(globalThis.schoolName === undefined);
}

The page agent sets a global, but the worker reports true for “is it undefined?”. That is stable Node evidence that a worker has a separate global environment and agent.

Common mistakes

• “A realm is a thread.” A realm is a global environment. A worker is an agent with its own realm.
• “Every value is shared in a cluster.” Normal messaging copies data; only explicit shared-memory mechanisms share bytes.
• “instanceof names a universal type.” It depends on a prototype from one realm.
• “ShadowRealm is a shipped browser primitive.” It is a Stage 2.7 proposal and code must feature-detect it.

Practice exercises

console.log(typeof globalThis, typeof Array);

Check your understanding

Keep the layers separate: agents execute, clusters decide sharing, and realms provide globals and intrinsics.

Key takeaways

• An agent has a stack, a job queue, and realms; a window and worker are separate agents.
• An agent cluster controls selected shared state, including SharedArrayBuffer eligibility.
• Each realm has its own global object and intrinsics.
• Use Array.isArray instead of realm-sensitive instanceof at array boundaries.
• ShadowRealm is a Stage 2.7 proposal: feature-detect it and do not assume browser support.

Coming next: How workers work.