Skip to content

Plugins: the APIs a design plugin needs, in one pull request - #1392

Open
hoangvu12 wants to merge 26 commits into
zeronsh:zeron/zgxfrom
hoangvu12:plugin-design-apis
Open

hoangvu12 wants to merge 26 commits into
zeronsh:zeron/zgxfrom
hoangvu12:plugin-design-apis

Conversation

@hoangvu12

@hoangvu12 hoangvu12 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

This replaces eight pull requests with one, as asked, so the plugin APIs can be reviewed together. We're building a design tool as a Luau plugin, and each commit adds one thing its service, its windows or its agent needs. Each commit is one of the old pull requests, in the order they build on each other, and its message says which.

Commit Was What it adds
439a369 #1362 A zeron.tool result with an imageContent array reaches the agent as MCP image content
c3634ae #1363 A manifest can ask for more than 64 MB of service memory (limits.memory_mb), shown on the consent sheet
3b78c67 #1366 zeron.eval runs scripts the plugin's agents write, in its service, behind an "eval" permission
3fe0d99 #1367 zeron.measure_text and zeron.load_font in services, measuring as a window's canvas does (zgx-text, no renderer)
629abf0 #1378 A "fonts" permission grants zgx's Capability::Fonts, so a plugin's windows can call ui.load_font
71a7407 #1379 zeron.fetch with binary = true returns a response's bytes whole, in base64
cc9d259 #1380 A service gets zeron.db, the same SQLite file its windows open (new crates/plugin-db)
009c8e3 #1398 zeron.write_file writes into the plugin's Documents folder or a chat's or project's, behind a "files.write" permission
9ff1698 The engine and apps/zgx pinned to one zgx, the combined zgx pull request
c52121b The pins moved to #2110's new head, which adds canvas tiles
58444b4 The pins moved to #2110 rebased on zgx main
3f5058b The pins moved to #2110's new head, which adds ScriptHost::plugin_memory
dd6f102 A plugin window gets the memory its manifest asks for its service (limits.memory_mb), through zgx's ScriptHost::plugin_memory

The old pull requests' descriptions still explain each change in full, with their own testing.

zgx: pinned to zeronsh/zgx main

zeronsh/zgx#2110 merged (e35626b88). The engine's and apps/zgx's pins now point at zeronsh/zgx at that commit (no longer the author's fork), with both lockfiles regenerated (70eee73).

Review fixes (security audit)

On top of the commits above:

Commit Fix
24f79f1 zeron.eval refuses a NaN budget (0/0) instead of panicking in Duration and stopping the service
67d9434 zeron.write_file checks where a path leads before making any folder (a drive-relative C:x or rooted \x is refused; a link out no longer gets folders made at its far end)
b881a1d zeron.db: a call stops after 10 s; a value and a query's rows are capped at 64 MB; a service uses at most 2 of the engine's blocking threads
33b5d2a A service's zeron.load_font of the same bytes again returns the same families; at most 64 fonts and 256 MB per VM
0d7015e MCP imageContent: an image's bytes must match its type (png, jpeg, gif, webp); at most 20 per result; only plugin tools
d1abdbd "files.write" is a risky ask, always asked (OUTSIDE_SANDBOX), its line leading with "Code and settings included: it can create and replace any file in your chats' and projects' folders." Where it may write is unchanged.
acecf1f Two clippy fixes in this PR's lines

Tested on macOS against the new pin: the engine and the app build (all targets); zeron-engine --lib plugins 266 passed; zeron-mcp --lib 75 passed (16 MB stack: discovery_and_creation_use_the_selected_hosts_catalogs overflows the default stack with and without this PR); zeron-plugin-db 7 passed; zeron-zgx plugins:: 241 passed, 1 failed (zeron_v2_is_in_step_with_the_default, the base's breakage below); zgx lint ui 0 errors; the UI suite 1,359 passed.

CI

CI on zeron/zgx is red for every pull request right now, from three breakages in the base branch, none of them in these files:

The macOS zgx job also fails GPU tests (create_render_pipeline 'shader fill') on #1382, which only touches v2's template files, so those come from the runner, not from a change.

Testing

On Windows, against zeron/zgx at c153906 with the pins above:

  • cargo check --locked: the engine and zeron-zgx with its tests are clean.
  • cargo test -p zeron-engine --lib plugins, with Plugin services can write files into Documents and your projects #1398 and the zgx pin above: 243 passed, 1 failed. The failure, the_sandbox_reads_only_the_plugins_own_files, comes from Windows paths: the test puts a temp folder's path (…\.tmpXXXX) in a Luau string literal, and \. isn't a valid escape. Plugin services can write files into Documents and your projects #1398 doesn't touch that test.
  • cargo test -p zeron-mcp --lib: 74 passed. cargo test -p zeron-plugin-db: 5 passed, 1 ignored.
  • zeron-zgx tests filtered to plugins::grants, consent, locale and i18n: 9, 8, 3 and 4 passed.

Three conflicts came up and all kept both sides: #1398 and #1380 each add an arm (write_file, db) to the same match in crates/engine/src/plugins/service/mod.rs; #1366 and #1363 add consent-sheet strings, manifest checks and service limits in the same places, and #1380 and #1367 each add a row to the same table in apps/zgx/docs/plugins.md.

A plugin tool's answer reached the agent as one JSON text block, so a base64 PNG was a long string the model read as characters. Now a tool result with a top-level `imageContent` array goes out as MCP image content, after the rest of the result as text. Each entry must be a PNG, JPEG, WebP or GIF of at most 5 MB, and images stop before the reply reaches the 8 MB cap; one left out is named in a last text block. Such a result goes without `structuredContent`: Codex shows the model only that (no images) when it is there, and Claude Code shows it in place of the texts.

Was zeronsh#1362.
A plugin service's Luau heap is 64 MB, and a plugin can't ask for more.
A design tool's service runs out at around 40k nodes.

"limits": { "memory_mb": 256 } gives its service that much, 512 at
most. More than 512, or anything that isn't a whole number from 1 to
512, makes the manifest broken rather than clamped, so the Allow sheet
never shows a number that isn't what runs. The consent record carries
memory_mb only when it's asked, so other plugins' digests don't change.
The Allow sheet names the number on the background line. Raising it asks
again, and lowering it doesn't.

A service with nothing in flight and more than half its memory in use
now runs a full collection. Luau collects only as it allocates and never
before failing an allocation, so the garbage of one big call counted
against the next, which then ran out.

Was zeronsh#1363.
A plugin's service had no way to measure text: it runs in the engine,
which linked no text shaping, and only a window's canvas could measure.
Layout that must work while Zeron is hidden (agent tools) couldn't run.

zeron.measure_text(text, opts) shapes with zgx-gpu's TextServices, the
same shaper and font lookup a window's canvas uses, over the system's
fonts and the app's own. zeron.load_font(path) adds a font file from the
plugin's folder, so the service and a window that loads the same file
with ui.load_font measure alike.

Also:
- Plugins: zeron.load_font says when the plugin has no such file
- Plugins: the engine measures text with zgx-text, without zgx's renderer
- Plugins: zeron.load_font takes a font's bytes in base64

Was zeronsh#1367.
No manifest permission granted zgx's Capability::Fonts, so every plugin
window's ui.load_font was refused, and a window couldn't measure in the
fonts its service loads with zeron.load_font. A loaded font reaches
every window's text, Zeron's own included, so the person is asked.

Was zeronsh#1378.
…in base64

A body crossed into Luau as String::from_utf8_lossy, so every byte that
isn't UTF-8 became U+FFFD: a fetched TTF or PNG came back corrupted, and a
plugin had no way to download one. With { binary = true } the body is the
bytes in base64 (Luau gets results as JSON, which carries text only). The
default stays text.

Was zeronsh#1379.
…zeron.write_file)

zeron.write_file(path, data, { base64 }) with a new "files.write"
permission: a relative path lands in ~/Documents/<plugin name>/, a whole
one must be inside one of this device's chats' or projects' folders.
Folders on the way are made; .., links out and links at the file are
refused. Tool calls also carry the chat's folder (call.cwd) when the
plugin has sessions.read, so an agent's export can go where its work is.
…ull request

The plugin APIs above need zgx changes that are one pull request now, zeronsh/zgx#2110: Capability::Fonts and ui.load_font for the "fonts" permission, and the zgx-text crate the engine measures with. The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) are pinned to its head on the author's fork, 6d3a20fd, so a service and its windows measure with the same zgx. Once #2110 merges, the pins go back to zeronsh/zgx.
zeronsh/zgx#2110 gained three commits: a panned or zoomed canvas draws in tiles off the frame, uploaded into one atlas a few a frame. The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) move from 6d3a20fd to its new head on the author's fork, c4c28f65. No zgx manifest changed, so both lockfiles change only the revision.
zeronsh/zgx#2110 was rebased onto zgx main at 5eec93a9, with the same 28 commits. The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) move from c4c28f65 to its new head on the author's fork, 41ffcef3. Both lockfiles take main's new web-time dependency of zgx; apps/zgx's also takes its newer zgx-vte and zgx-alacritty-terminal and dispatch2.
…dow memory

zeronsh/zgx#2110 adds five commits on the same base (main at 5eec93a9): ScriptHost::plugin_memory, zip:add_canvas, ui.render_canvas { file, append }, and two canvas fixes that keep a changed drawing's old raster or tiles shown while its new ones are made off the frame. CanvasText::width is now a bare f32 (f32::INFINITY for one line), which nothing here uses. The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) move from 41ffcef3 to its new head on the author's fork, ce348da5. Neither lockfile changes otherwise.
A plugin's manifest asking `"limits": { "memory_mb": 256 }` had it for its
service alone: its window stayed at zgx's 32 MiB for any plugin, and the
Design plugin's window stopped on a large design ("not enough memory").
Each window loaded now gets what its service does (at most 512 MB, as the
engine checks), by zgx's ScriptHost::plugin_memory; the rest keep the
default. Needs a zgx with that setter (zgx-script `plugin_memory`).
…5fb1

zeronsh/zgx#2110 was rebased onto zgx main at 88f45fb16, with the same 33 commits (and the renderer's parts of them left out of browser builds, as main now builds zgx-script for wasm32). The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) move from ce348da5 to its new head on the author's fork, 9d74a723. apps/zgx's lockfile also takes main's zgx-mlua 0.12.9, zgx-script's web-time, and zgx-gpu's libc, wayland and x11rb dependencies.
…08e3

zeronsh/zgx#2110 was rebased onto zgx main at 7dcf08e3a, with two more commits: a canvas tile waiting for its upload shows the tile it replaced (no blank cells after a change), and its inlining record. The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) move from 9d74a723 to its new head on the author's fork, 521b6158. Both lockfiles change only the source of the zgx packages.
…111f

zeronsh/zgx#2110 was rebased onto zgx main at fabb111fe, with one more commit: main's zgx-dom now draws canvases with Canvas 2D, so it also draws the canvas pictures, shadows and radial and conic gradients the PR adds (the wasm32 build needs them). The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) move from 521b6158 to its new head on the author's fork, b0115608. Both lockfiles change only the source of the zgx packages.
…15bc

zeronsh/zgx#2110 was rebased onto zgx main at ab4515bc4: main's macOS Core Text fallback moves into zgx-text with the rest of the text code, and the platform probe main added lists the two methods the PR adds (add_font, fonts). The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) move from b0115608 to its new head on the author's fork, 3548f5cc. Both lockfiles change only the source of the zgx packages.
…954d

zeronsh/zgx#2110 was rebased onto zgx main at d98f954d3: main's platform probe gained set_clipboard_files, so the probe now lists that and the PR's add_font and fonts. The engine's zgx and zgx-text and every zgx crate apps/zgx takes (its [patch] entries too) move from 3548f5cc to its new head on the author's fork, 24b35872. Both lockfiles change only the source of the zgx packages.
zeronsh Bot and others added 6 commits November 15, 2026 16:45
`budget_ms = 0/0` passes the prelude's number check and stays NaN through
`clamp`; `Duration::from_secs_f64` panicked on it and the service died.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… folder

The folders on the way were made before the check that they stay inside:
a link out of the plugin's folder got folders made at its other end, and
on Windows `\x` or `C:x` (not absolute, so joined to the plugin's
folder) left it for the drive. Those two are refused now, and the deepest
folder already there is checked before any is made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…re 64 MB at most

A service's `WITH RECURSIVE` with no end held the file's connection
forever, and every call behind it parked one of the engine's blocking
threads until none were left for anything else; `randomblob(1e9)` or a
query of every row took the process's memory, outside the service's
limit. Now a call stops at 10 s (its wait on the other process included),
a text or blob and a query's rows together are 64 MB at most, and a
plugin's calls take two of the engine's blocking threads at most, the
rest waiting as tasks. The windows' calls, through the same crate, have
the same limits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s 64 fonts and 256 MB at most

Each `zeron.load_font` added a face, up to 64 MB, outside the service's
memory limit: a loop grew the engine without end. A font's bytes loaded
again now give back the families it has, and a VM's fonts stop at 64 and
256 MB together.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… only a plugin tool's

`imageContent` was checked for its type's name, base64 and size: bytes
that aren't the image they say, or more images than a request takes, made
the model refuse the turn, and the result, kept in the chat, every turn
after. Now an image's first bytes must be its type's, a result passes on
20 at most (the rest named as left out), and a built-in tool's result is
text whatever its keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`files.write` reaches every file in this device's chats' and projects'
folders: code, hooks and settings that agents and tools then run. Its
consent line was calm, with no detail, and installing your own plugin
granted it unasked. It is now outside the sandbox (always asked, as
`messages.send` and `ui.replace` are), and its line is risky, saying
code and settings are included. Where it may write is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
zeronsh Bot and others added 2 commits November 17, 2026 12:24
zeronsh/zgx#2110, merged)

#2110 merged into zgx main as e35626b88, so the pins leave the author's
fork for zeronsh/zgx at that commit, and both lockfiles follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… test opens its store by path

mlua deprecates its String alias for LuaString; clippy also flagged a
needless borrow in a service test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant