Skip to content

Plugins: a service can run scripts its agents write (zeron.eval), with an "eval" permission - #1366

Closed
hoangvu12 wants to merge 1 commit into
zeronsh:zeron/zgxfrom
hoangvu12:plugin-eval
Closed

hoangvu12 wants to merge 1 commit into
zeronsh:zeron/zgxfrom
hoangvu12:plugin-eval

Conversation

@hoangvu12

@hoangvu12 hoangvu12 commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Agents that drive a plugin often send code, not single calls. A design agent sends "draw these 40 shapes" as a short script, the way pen.dev's execute or Figma plugin code work. A plugin's service can't run it: loadstring is removed there. The window has loadstring, but windows pause while Zeron is hidden, so the work has to happen in the service. Today the only option is to invent a JSON op list.

Now a service that asks for "eval" can run a script it was given:

-- zeron-plugin.json: "permissions": ["service", "tools", "eval"]
local ok, result = zeron.eval(args.script, { name = "agent", env = api, budget_ms = 1000 })
  • The script sees only env as its globals: no zeron, require, getfenv/setfenv, debug, print, and no Luau libraries unless the plugin passes them in. What it sets goes into a fresh table that reads through to env, so the next script doesn't see it. The environment is set when the chunk loads, so there's no setfenv afterwards.
  • A syntax error, error() or runtime error comes back as false, "agent:3: ...".
  • Past budget_ms it returns false, "agent: the script ran past its time budget (1000 ms)" and the service keeps serving. Once over budget, every safepoint raises the error, so a pcall the plugin handed in can't keep the script alive. The call's own 2 s budget still applies.
  • The script runs to its end in one go. It can't await, and one script can't start another.
  • Text only, no bytecode (same as the service's require), 1 MB at most. Running out of memory ends the service, as any call does.
  • Without the permission, zeron.eval raises zeron.eval needs the "eval" permission. "eval" without a service makes the manifest broken. The Allow sheet says "Run scripts its agents write: In its background service, with only what the plugin gives them. They can't do more than the plugin can."

Security: the script can only call what the plugin puts in env, and those functions already run under the plugin's own permissions. So eval adds no new power, only code the person didn't see when they allowed the plugin. That's why it's a separate permission the Allow sheet names, and not on by default.

Documented in apps/zgx/docs/plugins.md (permission table, the service call table, and a short "Running agents' scripts" section). English and Simplified Chinese strings are in place.

Testing

Six new tests in zeron-engine:

  • a_script_sees_only_what_its_given: zeron, ui, require, getfenv, setfenv, debug, loadstring, _G, print, os are nil inside. String methods still work. A global it sets doesn't reach env.
  • a_scripts_errors_say_where: syntax error agent:2:, nil index agent:3:, error() agent:2: no such screen. Bytecode is refused.
  • a_runaway_script_stops_at_its_budget_and_the_service_goes_on: while true do end and a pcall-wrapped loop both stop at 50 ms, then the next script and the next call answer.
  • eval_needs_its_permission
  • a_hundred_line_script_runs_in_a_few_milliseconds: 100 lines, 98 calls into env. Compile and run took 1.0 to 1.7 ms in a debug build.
  • plugins_manifest_broken_rules: "eval" without a service is broken.

cargo test -p zeron-engine --lib plugins::service::vm: 14 passed. cargo test -p zeron-engine --lib plugins::: everything passes except plugins_templates_bad_and_taken_ids_are_refused, which fails because of a stray %TEMP%\x on my machine (same as #1363). On Windows I had to stub two libc::getrusage test helpers locally (chat_persistence.rs, source_control.rs) to compile the engine's lib tests. Those stubs aren't in this PR. cargo clippy -p zeron-engine --tests reports nothing new.

I didn't build zgx, so i18n_tests and the Allow sheet weren't run. The Luau change there is three lines in screens/plugins/words.luau.

For maintainers

  • Should eval be in OUTSIDE_SANDBOX (always asked, even for your own plugins)? I left it out because the script can't do more than the plugin can.
  • I didn't mention zeron.eval in the SDK's zeron.luau header. That file is copied byte for byte into 16 bundled plugins, so I left that to you.
  • Is 1000 ms the right default budget?

Autofix with [code]smith
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

@hoangvu12

Copy link
Copy Markdown
Contributor Author

Folded into #1392, which combines our plugin pull requests into one for review. This change is its commit 3b78c67.

@hoangvu12 hoangvu12 closed this Nov 12, 2026
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