How AI Builder Opens Apps Inside Flowork
When the AI Builder creates an app and needs to test it, it uses the open_app tool. This tool sends a WebSocket message to the main Electron process, which creates a BrowserView tab inside the Flowork main window.
The Flow
1. AI calls{ action: "open_app", app_name: "my-app" }
2. agent_engine.js constructs URL: http://127.0.0.1:5000/local-apps/my-app/
3. Sends wsCommand('open_ai_tab', { tabId, url }) via WebSocket port 5001
4. main.js creates BrowserView, attaches to mainWindow, hooks console capture
5. AI can now use capture_browser, click_element, read_dom, get_console_logs
6. When done: close_app removes BrowserView and restores home view
Key Design Decisions
- BrowserView over BrowserWindow: Apps open inside the Flowork window, visible to the user. No more separate popup windows.
- Proxy pattern: A proxy object wraps BrowserView to provide
.webContentsand.isDestroyed()matching BrowserWindow interface for backwards compatibility. - Console capture:
webContents.on('console-message')feedsFloworkState.consoleLogsfor theget_console_logstool. - Graceful close:
close_ai_tabremoves BrowserView, destroys webContents, clears session, and restores home view automatically.
Anti-Hallucination: FASE 0
The most critical improvement is FASE 0 (KB Research). Before writing any code, the AI MUST: 1.kb_search with keywords from the user's request
2. kb_read on matching articles to get proven architecture and patterns
3. Only then proceed to planning and building
This prevents the AI from hallucinating incorrect patterns when a verified guide already exists in the Knowledge Base.
Knowledge Persistence: FASE 5
After a project is verified working: 1. AI offers to publish viakb_publish
2. Article is auto-generated from project files (manifest, code, etc.)
3. Sensitive data is auto-sanitized before upload
4. Article is published to https://floworkos.com/kb for future sessions
Testing Workflow (FASE 3)
1. open_app -> Opens app inside Flowork main window
2. wait 3s -> Let page fully load
3. capture_browser -> Screenshot the UI
4. get_console_logs -> Check for JS errors
5. click_element / type_text -> Test interactions
6. read_dom -> Verify DOM state
7. close_app -> Cleanup and restore home view