@viloris/vela-host

Desktop Bun host runtime: framed Shell RPC client, process lifecycle, plugin load, and Host-side call bridge on top of @viloris/vela-host-core.

Status: UDS client + Shell spawn + startHostSession + plugin register + Host-side call bridge + Shell→Host reverse call wire (shell.forwardCall / session.reverseCall). L4 composition shells wire preload call via --listen + reverse UDS (hosts/shared/host_rpc); packaging still Phase 2.
Contracts: @viloris/vela-api RPC envelopes.
Shell: hosts/zig-shell (--listen PATH).
Decisions: ADR 0002, ADR 0005.

Role

App / CLI
    │
    ▼
@viloris/vela-host          ← this package (Bun process)
  · spawnShellProcess / ShellClient (UDS frames)
  · startHostSession (lifecycle + multi-window policy)
  · registerPlugins / createDesktopHost
  · handleCallRpc (capability-checked call channel)
    │
    ▼
@viloris/vela-host-core
    │
    │  UDS + length-prefixed JSON
    ▼
hosts/zig-shell             (mock or real L4)

| Owns | Does not own | |------|----------------| | UDS connect + frame codec (TS) | Page / window.vela injection | | Shell process spawn / quit | Pure capability policy (host-core) | | Plugin register(host) load | Toolkit paint / hit routing | | Host-side call → invokeRpc | Real L4 WebView embed | | Shell→Host reverse demux + handler | Plugin marketplace / signing | | Multi-window policy (one Shell process) | |

Usage

Session (preferred)

import { startHostSession } from "@viloris/vela-host";
import { clipboardPlugin } from "@viloris/vela-plugin-clipboard/host";

const session = await startHostSession({
  api: { platform: "linux", sys: { /* inject facades */ } },
  capabilities: {
    default: { permissions: ["clipboard:read"] },
  },
  plugins: [clipboardPlugin],
  multiWindow: { maxWindows: 4, quitOnLastWindowClose: true },
  // shellBinary / VELA_ZIG_SHELL optional in monorepo after zig build
});

console.log(await session.shell.ping());
// → { pong: true, backend: "mock" }

const res = await session.call("clipboard.read");
// Host-local capability-checked VelaRpcResponse

// Same bridge over Shell reverse wire (stand-in for WebView window.vela.call):
const viaShell = await session.reverseCall("clipboard.read");

await session.quit();

Low-level client only

import { ShellClient, createDesktopHost } from "@viloris/vela-host";

const shell = await ShellClient.connect({
  path: "/tmp/vela-shell.sock",
});

const desktop = await createDesktopHost({
  api: { platform: "linux", sys: {} },
  capabilities: { default: { permissions: [] } },
  shell,
});

console.log(await shell.ping());
desktop.close();

Shell side (mock L4):

cd hosts/zig-shell && zig build
./zig-out/bin/vela-shell --listen /tmp/vela-shell.sock
# tests: --once accepts one client session then exits

Multi-window policy

One Host process + one Shell process. Windows are created with session.createWindow → Shell window.create. Host never spawns a Shell per window. Optional maxWindows and quitOnLastWindowClose (default true).

Call bridge + reverse RPC

handleCallRpc / session.call map channel call onto CapabilityHost.invokeRpc (structured deny).

Reverse wire (ADR 0002 D4): Shell may send Host a framed VelaRpcRequest with channel: "call". ShellClient demuxes request vs response frames and dispatches reverse requests to a handler. startHostSession wires that handler to handleCallRpc.

Live page path (composition shells with --listen):

window.vela.call(method, args)
  → preload {type:req, method:"call", args:{method, args}}
  → L4 bridge → HostSession.reverseCall (channel call)
  → Host reverse handler → handleCallRpc
  → preload {type:res, …} via __velaHostDispatch

Host probe path (no WebView):

session.reverseCall(method, args)
  → Host shell.forwardCall
  → Shell Session.reverseCall (channel call)
  → Host reverse handler → handleCallRpc
  → response rebinding back to outer request

Framing

Host detail (not a public app API): u32 little-endian length + UTF-8 JSON body, max 16 MiB. Payload shapes match VelaRpcRequest / VelaRpcResponse in @viloris/vela-api.

Verify

# unit + UDS integration (skips integration if binary missing)
bun test packages/host

# force binary:
cd hosts/zig-shell && zig build
bun test packages/host

Related

• @viloris/vela-host-core — pure call router
• hosts/zig-shell — Zig interop + UDS listen
• Roadmap Phase 2
• Design gaps G-P1-8, G-P1-9