[xiaozhou26]

Linked issue

Closes #1238

Backed by K-brain's elevated sandbox mode, Stack-Cairn/K-brain#165 (released in K-brain v0.107.22).

Summary

On native Windows, K-brain starts with the low-integrity sandbox, which cannot cut the network (network_control: false), so Offline sandbox is disabled. Stack-Cairn/K-brain#165 adds an elevated mode (two hidden local accounts plus WFP firewall rules) and POST /v1/sandbox/setup to install it behind a UAC prompt. This PR lets desktop users run that setup from the composer's mode selector instead of a terminal.

• When it shows: capabilities.sandbox_setup == 1, run_sandbox.setup_available == true and network_control is not true. A Set up offline sandbox… item then appears under the disabled Offline sandbox entry, with K-brain's setup_hint as its tooltip. fix(sandbox): require path protection for the sandbox modes #1235's rule still holds: a sandbox with path_protection === false stays unavailable and is never offered setup.
• Confirmation: lists what changes on the machine: two hidden local Windows accounts (one with network, one without), firewall rules that block all network access for the offline account (loopback included), and the Windows administrator prompt. It also says that kn sandbox uninstall undoes everything, and shows K-brain's hint.
• Running: the request waits for the UAC answer. The dialog shows a spinner and "Waiting for administrator approval…" and can't be dismissed meanwhile.
• Results (localized): 200 ready, with Use offline sandbox to switch modes (or "finished, but the self-test still fails" with K-brain's hint if health still lacks network control); 403 declined, nothing changed; 409 another setup is running; 500 failed, with K-brain's message and the uninstall command; 501 unsupported; anything else, including 405 and transport errors, a generic error with the message. Every non-ready result except 501 offers Try again.
• Capability refresh: after every attempt except 501 (K-brain bumps capabilityRevision), the desktop re-reads /v1/health through a shared capability store, so every mounted selector updates. The re-read capability decides ready or incomplete, not the response alone.
• Scope: desktop only, and only for a K-brain on this machine (the managed backend or a loopback URL), since the UAC prompt appears on the machine running K-brain. The WebUI/Gateway adapter never offers it, and its setUpOfflineSandbox returns unsupported. There is no uninstall button; uninstalling is terminal-only, as in K-brain.

Change scope

• Modules: agent-ui (shared selector, dialog, i18n, K-brain health parsing), agent-gui (desktop adapters), agent-gateway/web (WebUI adapter stub), docs
• Key paths:
  • crates/agent-ui/src/lib/kbrain/health.ts: offersRunSandboxSetup()
  • crates/agent-ui/src/lib/kbrain/sandboxSetup.ts (new): maps the HTTP status and body to an outcome
  • crates/agent-ui/src/components/chat/OfflineSandboxSetupDialog.tsx (new): confirm, running and result dialog
  • crates/agent-ui/src/components/chat/CommandSafetyModeSelector.tsx: setup item and dialog wiring
  • crates/agent-ui/src/i18n/translations/{enUSCommon,zhCNCommon}.ts: en-US and zh-CN strings
  • crates/agent-gui/src/agent-ui-adapters/kbrainSettings.ts: setUpKBrainSandbox() (authenticated POST with no timeout)
  • crates/agent-gui/src/agent-ui-adapters/sandboxCapability.ts: shared capability store, refresh, setUpOfflineSandbox(), local-backend check
  • crates/agent-gui/src/lib/kbrain/types.ts: KBrainRunSandboxCapability
  • crates/agent-gateway/web/src/agent-ui-adapters/sandboxCapability.ts: WebUI never offers setup
  • docs/kbrain-permission-modes.md: "Windows: setting up the offline sandbox"

Screenshots / preview

All screenshots come from the real desktop debug app (macOS arm64, tauri dev build), with the sidebar cropped out. The app used temporary HOME/LIVEAGENT_DEV_HOME directories and ran the real K-brain v0.107.22 release binary. Nothing in the screenshots was drawn or edited apart from cropping.

What was injected, and why: the elevated sandbox (UAC, sandbox-user accounts, WFP) exists only on native Windows. On macOS, K-brain reports its macOS sandbox and answers POST /v1/sandbox/setup with 501. To show the Windows flow, a thin loopback proxy sat between the app and the real K-brain and changed exactly two things:

1. GET /v1/health: set capabilities.sandbox_setup to 1 and replaced capabilities.run_sandbox with K-brain's Windows values (low-integrity, network_control: false, setup_available: true, and the reason/setup_hint strings copied from K-brain's internal/sandbox). After a successful setup it reported sandbox-user with network_control: true, and capabilityRevision was bumped per attempt.
2. POST /v1/sandbox/setup: canned K-brain-shaped answers after a short delay that stands in for the UAC prompt: first 403 (code: "declined"), then 200.

Every other request, including the run and settings traffic, went to the real K-brain unchanged.

Selector: setup action under the disabled Offline sandbox	Confirmation dialog

403: approval declined	Waiting for the UAC answer	200: ready

After Use offline sandbox, health was re-read: Offline sandbox is enabled and selected, and the setup action is gone.

Verification

• crates/agent-gui: node --test test/chat/offline-sandbox-setup.test.mjs test/chat/command-safety-mode-selector.test.mjs passes, 15/15. New tests cover:
  • Capability parsing: old K-brain, sandbox_setup ≠ 1, setup_available false, sandbox-user, path_protection: false, remote backend, empty hint.
  • Mapping of every status (200 ready or incomplete, 403, 409, 500, 501, 405, non-JSON).
  • The authenticated POST plus the health re-read that updates a mounted selector, and no re-read after 501.
  • Selector visibility, and confirm → running → ready → onChange("sandboxOffline").
  • Each result's message and retry.
• Full test:gui and test:webui pass. The K-brain backend integration tests were run against the v0.107.22 binary through LIVEAGENT_KBRAIN_BINARY.
• The shared UI, GUI and WebUI TypeScript checks pass, as do pnpm lint, check-mirror and diff hygiene. The i18n parity test passes for both locales.
• Manual run in the native debug app as described above: the declined → retry → ready → use offline sandbox path, with real backend health refreshes.
• Not exercised: a real Windows machine and UAC prompt.

Pre-submit checklist

• A requirement issue is linked (or this is a trivial fix that needs no issue, as explained in the summary).
• Synced with the target branch; no merge conflicts.
• The change is focused, with no unrelated modifications.
• No secrets, tokens, or personal data included.
• Docs are updated for changes affecting user behavior, deployment, or configuration.