| 1 | # A0 Connector Plugin DOX |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | - Own the current Agent Zero connector plugin for HTTP and WebSocket integration. |
| 6 | - Provide remote execution, text-editing freshness, and connector runtime bridges. |
| 7 | |
| 8 | ## Ownership |
| 9 | |
| 10 | - `plugin.yaml` owns plugin metadata and settings scope. |
| 11 | - `api/` owns connector WebSocket and API entry points. |
| 12 | - `helpers/` owns chat context, event bridge, execution config, freshness, version, and WebSocket runtime helpers. |
| 13 | - `tools/`, `prompts/`, `skills/`, `extensions/`, and `webui/` own connector-facing agent and UI contributions. |
| 14 | |
| 15 | ## Local Contracts |
| 16 | |
| 17 | - Preserve session-auth and `auth.handlers` activation assumptions. |
| 18 | - Keep remote tool prompts synchronized with remote tool behavior and disclose |
| 19 | them only from connected CLI metadata: no connected CLI hides all remote tool |
| 20 | prompts, remote file metadata enables `text_editor_remote`, F4-enabled remote |
| 21 | execution metadata enables `code_execution_remote`, and supported enabled |
| 22 | Computer Use that does not need re-arming enables `computer_use_remote`. |
| 23 | - Never re-add a connector prompt that the effective project/profile tool policy |
| 24 | blocks. |
| 25 | - Do not bypass WebSocket authentication or leak connector session data. |
| 26 | - Advertise Launcher gateways additively through HTTP capability |
| 27 | `launcher_gateway` and WebSocket feature `launcher_gateway_control`. Older |
| 28 | ordinary CLI clients retain their existing protocol fields and behavior; do |
| 29 | not provide a partial tools-only fallback when either feature is absent. |
| 30 | - A Launcher `connector_hello` carries a versioned gateway object with kind, |
| 31 | stable ID, host label, and bounded status. Store it per authenticated socket, |
| 32 | remove it on disconnect, and let context-bound CLI sockets retain routing |
| 33 | priority. One unique Launcher gateway may be the global fallback. A duplicate |
| 34 | socket with the same ID replaces stale state; distinct simultaneous IDs fail |
| 35 | closed as Multiple hosts. |
| 36 | - `connector_gateway_control` and `connector_gateway_control_result` cover |
| 37 | master state, complete scope replacement, and Disconnect |
| 38 | (`emergency_disconnect` on the wire). Protected |
| 39 | WebUI mutations require CSRF, await the matching acknowledgement, and return |
| 40 | refreshed status. Apply acknowledged master and scope state to remote file |
| 41 | and execution routing before resolving the control request; the follow-up |
| 42 | `connector_hello` only reconciles metadata. Never let the WebUI select a host |
| 43 | folder or personal browser profile. |
| 44 | - Launcher gateway scopes expose file reading and writing separately. File |
| 45 | writing depends on reading, and Code execution depends on file writing. Keep |
| 46 | older gateway declarations without `file_write` read/write compatible. |
| 47 | - Agent Zero WebUI exposes no Launcher gateway icon, menu, status, or control |
| 48 | bridge. Host access settings, Disconnect/Reconnect, scope changes, and |
| 49 | Computer Use approval belong only to attached or detached A0 Launcher chrome. |
| 50 | Keep the authenticated gateway HTTP/WebSocket protocol available for the |
| 51 | Launcher and connector runtime without adding a Core WebUI surface. |
| 52 | - File operation results may arrive as chunked JSON/base64 |
| 53 | `connector_file_op_result` frames; resolve the pending file operation only |
| 54 | after all chunks for the `op_id` are assembled. |
| 55 | - Host browser status metadata may advertise `available_browsers` entries with browser ids, labels, CDP endpoints, status, and enabled state; keep older CLI payloads without those fields compatible. |
| 56 | - Model preset definitions exposed through v1 are global; project arguments select scope but never create project-owned definitions. Model switcher state reports the effective main, utility, and embedding models and preserves embedding-change notifications. |
| 57 | - The protected v1 `agent_editor` route delegates to the bundled Agent Editor |
| 58 | API and must not define another profile schema or write profile files itself. |
| 59 | - The protected v1 `agents_list` response uses the shared agent presentation |
| 60 | catalog rather than applying connector-specific visibility rules. |
| 61 | - Computer Use receipts describe transport success unless the connector returns explicit effect evidence. Linux target-bound typing requires a verified active/focused `window_id`; window activation uses focus, never a press action on an application or window node. Do not retry an identical failed Computer Use call. |
| 62 | - Accepted WebSocket user-message replay metadata may include attachment basenames only; strip paths, query strings, fragments, and bytes before logging them in `kvps`. |
| 63 | |
| 64 | ## Work Guidance |
| 65 | |
| 66 | - Coordinate connector runtime changes with API, tools, prompts, and WebUI viewer behavior together. |
| 67 | |
| 68 | ## Verification |
| 69 | |
| 70 | - Run connector-specific tests or smoke-test HTTP and `/ws` integration when changing runtime behavior. |
| 71 | - Launcher gateway regression coverage lives in |
| 72 | `tests/test_a0_connector_launcher_gateway.py`. |
| 73 | |
| 74 | ## Child DOX Index |
| 75 | |
| 76 | No child DOX files. |