Two Doors, One Bridge — AgentZero's Wasm Sandbox for Web + Native Plugin Extension

AgentZero Lite just grew a sandbox where the web's flexibility and the native runtime's power live in the same room — separated by a bridge, not by a wall. This is mission M0005 (harness/missions/M0005).

Why this matters — the value story

• A native plugin gives you direct access to the runtime — files, audio, GPU, the LLM gateway. But the iteration loop is slow: edit a class, rebuild, restart, retest. UI is whatever the host framework gives you (in our case WPF), so the visual surface costs more than the logic.

• A web plugin gives you the fastest iteration loop on Earth — change a div, save, reload, done. HTML5/CSS/JS are the most accessible UI stack any developer can hit the ground running with. But the cost is that the web sandbox is too sandboxed: no audio devices, no spawn-a-process, no on-device LLM unless you build a whole HTTP layer to expose them.

The idea — IZeroBrowser as the contract

// Project/ZeroCommon/Browser/IZeroBrowser.cs
public interface IZeroBrowser
{
    string GetAppVersion();
    VoiceProvidersInfo GetVoiceProviders();
    Task<TtsResult> SpeakAsync(string text, CancellationToken ct = default);
    void StopSpeaking();
}

public sealed record VoiceProvidersInfo(string Stt, string Tts, string LlmBackend);
public sealed record TtsResult(bool Ok, string? Provider, int Bytes, string? Format, string? Error);

1. The contract sits in ZeroCommon, not in the WPF host. ZeroCommon is the shared library that has zero WPF or Win32 dependencies — this is a hard rule in the codebase, enforced because future WASM plugins must be able to compile against this contract without dragging in PresentationFramework. Read the rule in CLAUDE.md.

2. The DTOs are records, not anonymous objects. A record is a stable shape across versions; if a future .wasm plugin caches the type and the host adds a field, the cache still resolves. Anonymous types die on every recompile.

// Project/AgentZeroWpf/Services/Browser/WebDevHost.cs
public async Task<TtsResult> SpeakAsync(string text, CancellationToken ct = default)
{
    var v = VoiceSettingsStore.Load();
    var tts = VoiceRuntimeFactory.BuildTts(v);
    if (tts is null)
        return new TtsResult(false, v.TtsProvider, 0, null, "TTS provider is Off");

    var bytes = await tts.SynthesizeAsync(text, ResolveVoiceId(v), ct);
    _playback.Play(bytes, tts.AudioFormat);
    return new TtsResult(true, tts.ProviderName, bytes.Length, tts.AudioFormat, null);
}

The bridge — postMessage RPC over WebView2

1. Virtual host mapping, not embedded resources

webDevView.CoreWebView2.SetVirtualHostNameToFolderMapping(
    "zero.local",
    Path.Combine(AppContext.BaseDirectory, "Wasm"),
    CoreWebView2HostResourceAccessKind.Allow);

webDevView.CoreWebView2.Navigate("https://zero.local/voice-test/index.html");

2. JSON RPC over chrome.webview.postMessage

// JS → host
{ "id": 7, "op": "tts.speak", "args": { "text": "hello" } }

// host → JS
{ "id": 7, "ok": true,
  "result": { "ok": true, "provider": "WindowsTTS", "bytes": 36044, "format": "wav" } }

// Project/AgentZeroWpf/Services/Browser/WebDevBridge.cs
private async Task<object?> DispatchAsync(string? op, JsonElement? args)
{
    return op switch
    {
        "version"        => new { version = _host.GetAppVersion() },
        "voice.providers" => _host.GetVoiceProviders(),
        "tts.speak"      => await _host.SpeakAsync(ReadString(args, "text")),
        "tts.stop"       => Stop(),
        _ => throw new InvalidOperationException($"unknown op '{op}'"),
    };
}

// Wasm/common/zero-bridge.js
window.zero = {
  invoke,
  version:        ()    => invoke('version'),
  voice: {
    providers:    ()    => invoke('voice.providers'),
    speak:        (t)   => invoke('tts.speak', { text: t }),
    stop:         ()    => invoke('tts.stop'),
  },
};

const r = await window.zero.voice.speak("Hello from the WebDev sandbox.");
// r = { ok: true, provider: "WindowsTTS", bytes: 36044, format: "wav" }

Architecture at a glance

flowchart LR
  subgraph WPF[AgentZero Lite — WPF host]
    Settings[Settings panel]
    WebDev[WebDev tab]
    Host[WebDevHost : IZeroBrowser]
    Voice[Voice services<br/>STT / TTS / LlmGateway]
    Settings --> WebDev
    Host -. uses .-> Voice
  end

  subgraph Sandbox[Wasm/ — local web app]
    HTML[voice-test/index.html]
    JS[voice-test.js]
    Bridge[common/zero-bridge.js]
    HTML --> JS
    JS --> Bridge
  end

  WebDev -- WebView2<br/>virtual host mapping --> HTML
  Bridge <-- postMessage<br/>JSON RPC --> Host

The first sandbox — voice-test

Project/AgentZeroWpf/Wasm/
├── README.md
├── common/
│   └── zero-bridge.js       ← JS Promise RPC wrapper (~40 lines)
└── voice-test/              ← one app, one folder
    ├── index.html
    ├── voice-test.css
    └── voice-test.js

Why the contract lives in ZeroCommon

• A future .wasm plugin (compiled C# → WebAssembly via WASI, or Rust binding through wasmtime) can reference only Agent.Common.dll and still be ABI-compatible with whatever AgentZero exposes.

• Unit tests can mock IZeroBrowser and exercise the WebDevBridge dispatch logic without spinning up WebView2.

• If we later swap WebView2 for, say, an embedded Chromium (CefSharp) host, the contract doesn't move — only the bridge does.

Roadmap — from JS today to .wasm plugins tomorrow

Closing

Demo

TECH LINKS

• 𝕏 @webnori

• 📘 Akka Labs (Facebook group)

• 📝 More writings — webnori wiki