@volter/browser-toolbelt

Optional developer commands for Browser Substrate: an AST shell, Git, GitHub-device authentication, and project sharing. installBrowserToolbelt registers them with an existing BrowserRuntime.

The package is deliberately separate from the kernel and execution engines. A consumer can replace or omit these commands without changing workspace, process, port, or preview behavior.

For GitHub credentials, save the entire GithubDeviceToken with GithubTokenVault.save(token). Use await vault.current(auth) before Git or sharing requests, not a cached load() result: it refreshes expiring device tokens and persists rotation under a browser Web Lock. load() only restores UI state. Legacy non-expiring tokens remain usable. An uncertain refresh fails explicitly without starting another login; see ADR-0030 in the repository.

BrowserShell.run(command, { filesystemPolicy: { writableRoots: ["/workspace"] } }) uses an independent filesystem view for that invocation. Built-in commands and nested shells can read the tree but mutate only permitted paths; an empty list is read-only. External programs must explicitly support this policy or execution is refused. Detached & jobs retain the grant and belong to that invocation's job table; terminating the owning shell cancels them. This does not implement Landlock or confine native operating-system processes.