Breeze Helper Reference

Lightweight Tauri v2 desktop app providing an AI chat assistant, device info, and tool approval interface. Runs in the system tray, spawned by the Go agent on Windows as a SYSTEM process in the user's session.

Architecture Overview

apps/helper/
  src/
    App.tsx                    # Main UI (chat, device info, history, approval popup)
    main.tsx                   # React entry point
    stores/chatStore.ts        # Zustand state (auth, messages, SSE streaming, approvals)
    styles.css                 # Dark-theme styling
  src-tauri/
    src/lib.rs                 # Rust backend (~776 lines): config, HTTP client, tray, streaming
    tauri.conf.json            # App config (380×600 frameless, tray icon, CSP)
    Cargo.toml                 # Rust deps (tauri v2, reqwest, tokio, serde_yaml)
    build.rs                   # Tauri build script
  vite.config.ts               # Frontend build
  package.json                 # React + Zustand + react-markdown

Tauri Commands (Rust → Frontend)

Registered in lib.rs via generate_handler![]:

helper_fetch — Key Design

The central HTTP proxy command. All frontend API calls go through this.

• SSRF protection: Validates request URL starts with configured api_url
• Auth injection: Always sets Authorization: Bearer <token>, prevents frontend override
• mTLS: Builds reqwest::Client with Identity::from_pem if cert+key present in secrets.yaml
• Streaming: When stream: true, spawns tokio task that emits helper-fetch-stream Tauri events as StreamChunkEvent { stream_id, chunk, done, error }
• Non-stream: Returns full body inline in HelperFetchResponse

Config Files

All in the agent config directory (same as agent.yaml):

Config Paths

HelperConfig Fields

show_tray_icon: true         # Draw the tray icon at all (#3202). Independent of
                             # the three menu-item flags below: with this false
                             # the helper still serves chat, remote-access
                             # consent and PAM dialogs, it just has no tray.
                             # Missing key => TRUE everywhere in the chain.
show_open_portal: true       # Show "Open Breeze Portal" in tray menu
show_device_info: true       # Show "Device Info" in tray menu
show_request_support: true   # Show "Request Support" in tray menu
portal_url: ""               # URL for portal (falls back to api_url)
device_name: ""              # Display name
device_status: ""            # Current status
last_checkin: ""             # Last check-in timestamp

Config reloads every 60s; tray menu rebuilds on change.

Frontend (React + Zustand)

Views (in App.tsx)

1. Connection states — connecting, error, disconnected (with retry)
2. UsernamePrompt — one-time name entry (persists to localStorage, falls back to OS username)
3. SessionHistory — list past conversations, load by ID
4. DeviceInfoView — hostname, OS, status, agent version (from GET /devices/by-agent/:agentId)
5. Chat — messages, markdown rendering, tool indicators, thinking dots, approval popup

Chat Store (chatStore.ts)

State: connectionState, agentConfig, sessionId, messages, isStreaming, pendingApproval, sessions, username

Key methods:

• initialize() — loads agent config via Tauri invoke (or VITE_* env vars for dev)
• sendMessage(content) — creates session if needed, POSTs via SSE stream
• loadSessions() / loadSession(id) — session history
• approveExecution(executionId, approved) — tool approval
• clearMessages() — closes session, resets state

HTTP Layer (Tauri vs Dev)

Two helper functions abstract Tauri invoke vs native fetch:

• helperRequest(config, url, options) — non-streaming requests
• helperStreamRequest(config, url, options, onChunk, onDone) — SSE streaming

In Tauri: calls helper_fetch (Rust mTLS client). In browser dev: uses native fetch() with VITE_API_URL / VITE_AGENT_TOKEN / VITE_AGENT_ID.

Stream listener race fix: Event listener registered BEFORE helper_fetch invoke to avoid missing chunks when proxy buffers the full response.

SSE Event Processing

processSSELines() handles: message_start, content_delta, tool_use_start, tool_result, message_end, approval_required, error, done. Plan events (plan_approval_required, etc.) are received but not yet rendered.

Helper Chat API Routes

apps/api/src/routes/helper/index.ts — mounted at /api/v1/helper/*

Auth: Agent bearer token (brz_ prefix) via helperAuth middleware (SHA-256 hash lookup against devices.agentTokenHash). Creates synthetic AuthContext scoped to device's org.

Pre-flight Checks (per message)

1. Session exists and belongs to device
2. Session not expired (24h max age)
3. Turn limit not exceeded
4. Rate limit: 30 msg/60s per device (Redis)
5. Org budget check (fail-closed)
6. Input sanitization

Permission Levels

Configured via helperToolFilter.ts → getHelperAllowedMcpToolNames(level).

Tool Approval Flow

1. AI invokes a restricted tool → approval_required SSE event
2. ToolApprovalPopup renders with description, device badge, parameters
3. 5-minute auto-deny countdown timer
4. User clicks Allow/Deny → POST /chat/sessions/:id/approve/:executionId
5. Hidden input keys filtered from display: deviceId, orgId, siteId, sessionId

Agent IPC Integration

The Go agent spawns Helper in user sessions. Key IPC types from agent/internal/ipc/message.go:

Helper roles: system (SYSTEM token, desktop capture) or user (logged-in user, script execution).

Windows SYSTEM Context

• Agent service (Session 0) spawns Helper via CreateProcessAsUser with SYSTEM token + session ID override
• Helper detects SYSTEM context in lib.rs setup: checks LOCALAPPDATA for "systemprofile"
• Redirects WebView2 data dir to %ProgramData%\Breeze\helper-webview\ to avoid access issues
• get_os_username() falls back to USERNAME env var when whoami returns "SYSTEM"

Tray Menu

Built dynamically from HelperConfig flags:

Left-click on tray icon → show chat window. Right-click → context menu.

Security

• SSRF prevention: helper_fetch validates URL starts with configured API URL
• Auth header protection: Authorization always set by Rust, frontend can't override
• mTLS: Client certificate from secrets.yaml (optional, for Cloudflare mTLS)
• Token hashing: Agent token validated via SHA-256 hash comparison
• Device scoping: All session queries include deviceId filter
• Input sanitization: sanitizeUserMessage() applied to all chat input
• Rate limiting: 30 msg/min per device via Redis sliding window
• Budget enforcement: Org budget checked before every message (fail-closed)

Build & Development

# Dev mode (Vite hot-reload + Tauri)
cd apps/helper && pnpm tauri dev

# Build distributable
cd apps/helper && pnpm tauri build

# Frontend-only dev (without Tauri, needs VITE_* env vars)
cd apps/helper && pnpm dev

Dev env vars (for browser-only development without Tauri):

VITE_API_URL=http://localhost:3001
VITE_AGENT_TOKEN=brz_<token>
VITE_AGENT_ID=<device-uuid>

Bundle Targets

Key Dependencies

Rust: tauri v2, reqwest (mTLS), tokio, serde/serde_yaml, chrono, whoami TypeScript: React 18.3, Zustand 4.5, react-markdown 10, @tauri-apps/api 2.0

Data Flow: Chat Message

1. User types in chat input (App.tsx)
2. chatStore.sendMessage(content)
   → Creates session via POST /helper/chat/sessions (if needed)
   → Adds optimistic user message
   → helperStreamRequest() to POST /helper/chat/sessions/:id/messages
3. In Tauri: helper_fetch (Rust) → mTLS HTTP request → SSE response
   → Rust spawns tokio task → emits helper-fetch-stream events
   → Frontend listener → processSSELines() → Zustand state updates
4. API: helperAuth → runHelperPreFlight → streamingSessionManager
   → Claude API call with org-scoped tools
   → SSE events: message_start → content_delta → tool_use_start → tool_result → done
5. Tool approval (if Tier 3): approval_required event → ToolApprovalPopup
   → User Allow/Deny → POST /approve/:executionId → tool executes or rejects

Logging

Helper logs to helper.log in the config directory (alongside agent.yaml). In SYSTEM service context, stderr isn't connected to anything visible, so log_helper_error() appends timestamped lines to this file.

Gotchas

• WebView2 data dir: On Windows SYSTEM, must redirect to %ProgramData%\Breeze\helper-webview\ or WebView2 init fails
• Stream listener race: Must register Tauri event listener BEFORE invoking helper_fetch — reverse proxies (Caddy) can buffer entire SSE response and deliver at once
• Tray click events: Only match Left + Up — matching all click variants steals focus from context menu on Windows
• 409 on concurrent messages: streamingSessionManager.tryTransitionToProcessing prevents parallel processing; frontend removes optimistic message on 409
• Plan events: plan_approval_required, plan_step_start, etc. received but not rendered yet