Breeze Helper

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