yaak-mountain-loop/packages/plugin-sandbox/README.md

The Yaak plugin sandbox

A QuickJS interpreter, a small set of globals, and one function that calls the host. That is the whole runtime. Everything else a plugin does — read a request, send one, store a token, ask the user something — is a message the host chose to answer.

This document is the contract. It is written to be implementable twice: once here, in wasm, for the browser, and once in Rust with rquickjs, for the desktop and the CLI. If the two hosts disagree about anything below, that is a bug in whichever one drifted, not a platform difference to work around. The promise to plugin authors is that there is one sandbox and it behaves the same everywhere; a promise like that is only worth making if it is enforceable, which is why the browser runs QuickJS rather than the Worker's own JavaScript engine.

The engine

quickjs-ng, and only quickjs-ng.

There is no real choice: rquickjs — the Rust binding the desktop host will use — vendors quickjs-ng as a git submodule and offers no alternative. Picking Bellard's upstream for the browser would mean the two hosts run different engines, which is exactly the thing this design exists to prevent.

	Version	Notes
Browser (this package)	quickjs-ng 0.12.1	via @jitl/quickjs-ng-wasmfile-release-sync 0.32.0
Desktop (planned)	quickjs-ng 0.15.1	via rquickjs 0.12.2

The version skew is a known gap, and closing it is slice-2 work. Three minor versions is small — the differences are bug fixes and Temporal progress, not semantics anything here depends on — but "identical everywhere" is not a claim that survives being approximate indefinitely. Whoever builds the Rust host should pin both sides to the same tag and add a test that asserts the version string matches.

Why the sync build, not ASYNCIFY

quickjs-emscripten ships an ASYNCIFY variant that lets guest code call an async host function synchronously. We use the plain sync build instead:

• ASYNCIFY is about twice the wasm size (1.08 MB vs 529 KB) and, measured, 2.2x slower.
• It can only suspend for one host call at a time. A runtime that runs several plugins would have to hold one wasm instance per in-flight call.
• We do not need it. The guest gets real await anyway: a host function returns a QuickJS deferred promise, the host resolves it, and the host drains the job queue. ctx.store.get(...) is an ordinary await inside a plugin.

The only thing lost is a host call that looks synchronous to the guest, and no Yaak plugin wants one — the whole ctx API has been async since it existed.

What exists inside the sandbox

QuickJS gives you the language and nothing else. Everything below is either installed by src/guest/globals.ts or absent. Both hosts must install exactly this list.

From the engine

Object, Array, Function, String, Number, Boolean, Symbol, Math, JSON, Date, RegExp, Error and subclasses, Map, Set, WeakMap, WeakSet, WeakRef, Promise, Proxy, Reflect, BigInt, ArrayBuffer, SharedArrayBuffer, DataView, all TypedArrays, globalThis, queueMicrotask, performance.

Language level is ES2023 plus most of ES2024 — Object.groupBy, Array.prototype.at, String.prototype.replaceAll, async generators, private fields, ??= all work.

Installed by the runtime

Global	Notes
console	.log/.info/.warn/.error/.debug/.trace. Arguments are formatted to a string inside the sandbox, so only strings cross out — a cycle or an exotic prototype is the guest's problem, not the host's.
setTimeout / clearTimeout	The host holds the real timer; QuickJS has no clock to wake on. A sandbox torn down mid-wait takes its pending timers with it.
TextEncoder / TextDecoder	UTF-8 only. Pure JavaScript, in-sandbox — a bridge would cost a copy each way. Lone surrogates encode to U+FFFD, matching the standard.
btoa / atob	Latin-1, same narrow contract as the browser's.

Deliberately absent

fetch, XMLHttpRequest, WebSocket, crypto, structuredClone, URL, URLSearchParams, setInterval, require, module, process, Buffer, std, os, and every Node built-in.

• Network and storage are absent because they are ctx's job. A plugin that could open its own socket would defeat the point of the sandbox and would not work in a browser anyway.
• setInterval is absent because an interval is a timer that rearms and nothing in a plugin should be polling. Build one from setTimeout, visibly.
• crypto is absent, and this is the one real gap. The decided direction is pure-JavaScript @noble/* inside the sandbox: audited, dependency-free, identical on both hosts, no host API to keep in sync. A yaak.crypto builtin is the escape hatch if a hot path is measured, not before. Concretely, template-function-uuid does not run in the sandbox today because its uuid dependency reaches for node:crypto; that is a slice-2 conversion, not a missing capability.
• URL is absent only because nothing has needed it yet. It is a reasonable future addition; it must be added to both hosts together.

The module contract

A module arrives as source text, not a file — there is no filesystem, and in a browser there could not be one.

It is evaluated as CommonJS, via new Function("module", "exports", "require", source), and must assign module.exports.plugin (or module.exports.default). new Function rather than an ES module is deliberate: the bundle's top-level names cannot collide with the shell's, and the source needs no loader hook.

require exists only to throw, naming the specifier. A bundle that still calls it was not bundled for this target, and saying which module is missing beats an undefined that surfaces ten frames later.

Bundling requirements: CommonJS, no external modules, no Node built-ins, ES2022. scripts/bundle-sandbox-plugins.mjs does this today; what a real yaakcli build --target sandbox needs is listed at the bottom of that file.

The host interface

Four functions, installed on globalThis before any plugin code runs. A Rust host must expose the same four with the same names and shapes.

Function	Direction	Shape
__yaak_call(envelopeJson)	guest → host	Returns a promise of the reply JSON. The one door out.
__yaak_log(level, message)	guest → host	Both strings. Fire and forget.
__yaak_timer_start(id, ms)	guest → host	Host calls __yaak_guest.fireTimer(id) when due.
__yaak_timer_cancel(id)	guest → host

And the guest exposes globalThis.__yaak_guest:

Method	Shape
load(source, pluginRefId)	Evaluate a module. Throws if it exports no plugin.
summary()	What the module contributes, as plain data.
dispatch(envelopeJson)	Returns a promise of the reply payload JSON.
fireTimer(id)

Envelopes

Both directions carry InternalEventPayload from crates/yaak-plugins/src/events.rs, unchanged. That is what makes a plugin unable to tell which runtime it is in.

// dispatch, host → guest
{ "context": { "id": "...", "label": null, "workspaceId": "..." },
  "payload": { "type": "call_template_function_request", "name": "...", "args": { ... } } }

// __yaak_call, guest → host
{ "pluginRefId": "auth-bearer",
  "context": { ... },
  "payload": { "type": "get_key_value_request", "key": "token" } }

pluginRefId rides on outgoing calls because one host handler serves every loaded module, and a plugin's stored state is namespaced by which plugin it is — the same namespacing build_shared_reply does in crates/yaak/src/plugin_events.rs.

A throw inside a plugin becomes {"type":"error_response","error":"..."}, never a crash and never silence: whatever asked gets a message.

The ctx API

Built entirely out of __yaak_call. See src/guest/context.ts — it is the same surface the Node runtime's PluginInstance builds, so it is not repeated here.

What differs is which calls a host answers. The browser host answers a deliberately short list (packages/platform/src/web/plugins.ts) and refuses the rest by name. Refusing by name matters: a plugin that needs something it cannot have should fail with a sentence someone can act on.

Answered in the browser today: get_key_value, set_key_value, delete_key_value, show_toast. Everything else — sends, model reads and writes, prompts, response bodies, window info — refuses. Those are capability decisions, not oversights, and each should be added one at a time.

ctx.window.openUrl throws in every sandbox host: a plugin-opened window is a desktop affordance with no browser equivalent, and handing back a handle whose close() does nothing would be worse.

Isolation and limits

One runtime per worker, one context per module. A context is the isolation boundary — its own globals, its own Object, its own prototypes — so two plugins cannot see or patch each other. Sharing the runtime is deliberate: the engine and its wasm instance are the expensive part; contexts are not.

Limit	Value	Why
Memory	256 MB per runtime	Sized for an importer holding a large document and the objects it parses into.
Stack	2 MB	Deep recursion becomes a guest stack overflow, not a worker crash.
Synchronous execution	60 s	A watchdog for while (true), not a limit on real work.

The watchdog bounds synchronous execution only. A plugin awaiting the host is not looping, so the clock stops for the duration of a host call and restarts when the guest resumes. It is generous because it costs nothing to be: plugins run in their own worker, so one stuck there blocks no database command and no frame. It is sized off the slowest real work measured — GitHub's 12.3 MB OpenAPI description takes about 2.5 s (bench/import.mjs) — with room for a document several times larger before a legitimate import looks like a hang.

Where the sandbox runs, and why not in the database worker

In the browser: a dedicated worker owned by the tab, separate from the SharedWorker that owns the database.

• Plugin work is slow by design, and the database worker answers every tab's commands synchronously. A large import in there would stall every other tab's reads.
• A plugin that never returns can be ended with terminate(). You cannot do that to the worker holding the database.
• The capabilities plugins actually ask for — a prompt, a toast, the active request — belong to a tab, not to a database. Routing through the tab is the shorter path, not a detour.

The cost is that ctx.store goes worker → tab → database worker. It is a message either way, and this is the direction where a stuck plugin costs nothing.

Template rendering is the one flow that runs backwards: rendering happens in the engine, in the database worker, but the functions it calls live here. So the engine is handed a callback that asks the tab, which asks the sandbox. See templateBridge in packages/platform/src/web/worker.ts.

Plugins versus scripts

The shell is not plugin-shaped underneath. load takes source; dispatch takes an event. What a module is — a plugin today, a workspace script later — is decided by the payloads the host sends, not by the runtime.

That matters for one reason. A plugin is installed, so someone consented to it, and a plugin may one day escalate to a full Node runtime by asking. A script arrives inside a workspace — as data, through an import, a git sync, a shared repository — with no consent moment at all. So scripts get this sandbox and only this sandbox, forever, regardless of feature pressure. Any capability added below must be evaluated against the script case, which is the stricter one: "would I want this to run because someone opened a workspace a stranger sent them?"

Expected differences when scripts arrive, none of them built yet:

• A different payload set (run_script_request and friends) — same envelope.
• A tighter host-call allowlist. A script should probably not reach ctx.store at all, and certainly not another plugin's namespace.
• A much shorter watchdog. A pre-request script that runs for a minute is broken; an importer that does is working.

Performance

QuickJS is an interpreter with no JIT. Measured on GitHub's 12.3 MB OpenAPI description (1220 requests imported, identical output in both engines):

	First run	Best of 6
Node (V8)	304 ms	164 ms
QuickJS sandbox	2503 ms	2017 ms

That is 8x on the first run and about 12x once V8 has compiled — well inside the 10–50x folklore, and the first-run number is the one a user waits for because an import happens once. Reproduce with:

node packages/plugin-sandbox/bench/import.mjs <spec.json> 6

Conclusion: importers stay in the sandbox. 2.5 s in a worker, behind a progress state, for the largest public API description that exists, is a fine trade for one runtime everywhere. Revisit if a real document is measured materially worse — the escape hatch is a host builtin for the hot path, not a second runtime.

Boot cost is small: about 80–140 ms to instantiate the wasm and load a plugin, paid once and lazily, so a session that never touches a plugin never pays it. The wasm is 529 KB, next to the 4.3 MB SQLite one.