fix: add missing transport + behavior modules, create BRAIN.md

Extension v5.0.0 was broken — missing 4 files caused 'Service worker
registration failed. Status code: 3'.

Created:
- src/transports/ws.js: WebSocket transport with 60s keep-alive ping
- src/transports/external.js: external messaging stub
- src/transports/native.js: native messaging stub
- src/tools/behavior.js: behavior tools stub
- BRAIN.md: architecture, setup, curl commands, known errors

WebSocket now sends {"method":"ping"} every 60s to prevent
bridge server from marking extension as disconnected (>90s threshold).

Also updated .serena/project.yml

Author: SIN-Agent

.serena/project.yml

@@ -6,7 +6,8 @@ project_name: "OpenSIN-Bridge-issue-27"
 #   al                  bash                clojure             cpp                 csharp
 #   csharp_omnisharp    dart                elixir              elm                 erlang
 #   fortran             fsharp              go                  groovy              haskell
-#   java                julia               kotlin              lua                 markdown
+#   haxe                java                julia               kotlin              lua
+#   markdown
 #   matlab              nix                 pascal              perl                php
 #   php_phpactor        powershell          python              python_jedi         r
 #   rego                ruby                ruby_solargraph     rust                scala
@@ -57,48 +58,52 @@ ignored_paths: []
 # Added on 2025-04-18
 read_only: false
 
-# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# list of tool names to exclude.
+# This extends the existing exclusions (e.g. from the global configuration)
+#
 # Below is the complete list of tools for convenience.
 # To make sure you have the latest list of tools, and to view their descriptions, 
 # execute `uv run scripts/print_tool_overview.py`.
 #
-#  * `activate_project`: Activates a project by name.
+#  * `activate_project`: Activates a project based on the project name or path.
 #  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
 #  * `create_text_file`: Creates/overwrites a file in the project directory.
-#  * `delete_lines`: Deletes a range of lines within a file.
-#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `delete_memory`: Delete a memory file. Should only happen if a user asks for it explicitly,
+#       for example by saying that the information retrieved from a memory file is no longer correct
+#       or no longer relevant for the project.
+#  * `edit_memory`: Replaces content matching a regular expression in a memory.
 #  * `execute_shell_command`: Executes a shell command.
-#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
-#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
-#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `find_file`: Finds files in the given relative paths
+#  * `find_referencing_symbols`: Finds symbols that reference the given symbol using the language server backend
+#  * `find_symbol`: Performs a global (or local) search using the language server backend.
 #  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
 #  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-#  * `initial_instructions`: Gets the initial instructions for the current project.
-#     Should only be used in settings where the system prompt cannot be set,
-#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `initial_instructions`: Provides instructions Serena usage (i.e. the 'Serena Instructions Manual')
+#       for clients that do not read the initial instructions when the MCP server is connected.
 #  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-#  * `insert_at_line`: Inserts content at a given line in a file.
 #  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
 #  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `list_memories`: List available memories. Any memory can be read using the `read_memory` tool.
 #  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
 #  * `read_file`: Reads a file within the project directory.
-#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
-#  * `remove_project`: Removes a project from the Serena configuration.
-#  * `replace_lines`: Replaces a range of lines within a file with new content.
-#  * `replace_symbol_body`: Replaces the full definition of a symbol.
-#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `read_memory`: Read the content of a memory file. This tool should only be used if the information
+#       is relevant to the current task. You can infer whether the information
+#       is relevant from the memory file name.
+#       You should not read the same memory file multiple times in the same conversation.
+#  * `rename_memory`: Renames or moves a memory. Moving between project and global scope is supported
+#       (e.g., renaming "global/foo" to "bar" moves it from global to project scope).
+#  * `rename_symbol`: Renames a symbol throughout the codebase using language server refactoring capabilities.
+#       For JB, we use a separate tool.
+#  * `replace_content`: Replaces content in a file (optionally using regular expressions).
+#  * `replace_symbol_body`: Replaces the full definition of a symbol using the language server backend.
+#  * `safe_delete_symbol`:
 #  * `search_for_pattern`: Performs a search for a pattern in the project.
-#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
-#  * `switch_modes`: Activates modes by providing a list of their names
-#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
-#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
-#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
-#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+#  * `write_memory`: Write some information (utf-8-encoded) about this project that can be useful for future tasks to a memory in md format.
+#       The memory name should be meaningful.
 excluded_tools: []
 
-# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default).
+# This extends the existing inclusions (e.g. from the global configuration).
 included_optional_tools: []
 
 # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
@@ -133,3 +138,17 @@ symbol_info_budget:
 # list of regex patterns which, when matched, mark a memory entry as read‑only.
 # Extends the list from the global configuration, merging the two lists.
 read_only_memory_patterns: []
+
+# list of regex patterns for memories to completely ignore.
+# Matching memories will not appear in list_memories or activate_project output
+# and cannot be accessed via read_memory or write_memory.
+# To access ignored memory files, use the read_file tool on the raw file path.
+# Extends the list from the global configuration, merging the two lists.
+# Example: ["_archive/.*", "_episodes/.*"]
+ignored_memory_patterns: []
+
+# advanced configuration option allowing to configure language server-specific options.
+# Maps the language key to the options.
+# Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available.
+# No documentation on options means no options are available.
+ls_specific_settings: {}

BRAIN.md

@@ -0,0 +1,130 @@
+# BRAIN.md — OpenSIN Bridge Knowledge Base
+
+> **Stand: 28. April 2026, 21:15 Uhr**
+> Extension v5.0.0, Server v2.9.2
+
+---
+
+## 1. Architektur
+
+```
+Chrome Extension (v5.0.0) ──WebSocket──→ Bridge Server (v2.9.2, Port 7777) ──HTTP──→ Worker
+        │                                       │
+  src/background/                         server.js
+  service-worker.js                       /mcp (HTTP)
+        │                                  /health
+  transports/ws.js ──→ ws://localhost:7777/extension
+```
+
+---
+
+## 2. Extension laden (MV3)
+
+1. Chrome → `chrome://extensions/`
+2. Developer Mode aktivieren
+3. "Entpackte Erweiterung laden"
+4. Ordner: `/Users/jeremy/dev/OpenSIN-Bridge/extension/`
+
+**Fehler "Service worker registration failed. Status code: 3":**
+→ 4 Dateien fehlen standardmäßig und müssen ERSTELLT werden:
+
+```
+src/transports/ws.js          ← WebSocket Transport (mit Keep-Alive-Ping alle 60s)
+src/transports/external.js    ← External Messaging Stub
+src/transports/native.js      ← Native Messaging Stub
+src/tools/behavior.js         ← Behavior Tools Stub
+```
+
+---
+
+## 3. Server starten
+
+```bash
+cd /Users/jeremy/dev/OpenSIN-Bridge
+PORT=7777 node server.js
+```
+
+Gesundheitscheck:
+```bash
+curl http://localhost:7777/health
+# → {"status":"ok","extensionConnected":true,"toolsCount":91}
+```
+
+---
+
+## 4. Bridge per curl steuern (1 Command = 1 Aktion)
+
+```bash
+# Navigieren
+curl -s http://localhost:7777/mcp -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"navigate","arguments":{"url":"https://heypiggy.com"}},"id":1}'
+
+# Screenshot
+curl -s http://localhost:7777/mcp -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"screenshot"},"id":2}'
+
+# Klick
+curl -s http://localhost:7777/mcp -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"click_element","arguments":{"selector":".survey-item"}},"id":3}'
+
+# Text eingeben
+curl -s http://localhost:7777/mcp -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"type_text","arguments":{"selector":"input","text":"Hello"}},"id":4}'
+
+# JavaScript ausführen
+curl -s http://localhost:7777/mcp -X POST -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"execute_script","arguments":{"script":"document.title"}},"id":5}'
+```
+
+---
+
+## 5. Bekannte Fehler & Fixes
+
+| Fehler | Ursache | Fix |
+|--------|---------|-----|
+| Service worker Status code: 3 | Transport-Dateien fehlen | `ws.js`, `external.js`, `native.js`, `behavior.js` erstellen |
+| "Extension disconnected" trotz `extensionConnected:true` | Keep-Alive-Ping fehlt (>90s) | ws.js sendet alle 60s `{"method":"ping"}` |
+| WebSocket connected, kein Ping | `initLifecycle` hat keinen WebSocket-Ping — nur SW-Wakeup | ws.js `onopen` → `setInterval` Ping |
+| HF Spaces Bridge zeigt `extensionConnected: null` | Extension verbindet zu localhost, nicht HF Spaces | Extension Config auf `wss://openjerro-...` ändern ODER lokalen Server starten |
+
+---
+
+## 6. Environment
+
+```bash
+# Lokaler Bridge Server
+PORT=7777 node server.js                         # HTTP auf :7777, WS auf :7777/extension
+
+# ODER: HF Spaces (Cloud)
+BRIDGE_MCP_URL=https://openjerro-opensin-bridge-mcp.hf.space/mcp
+```
+
+**Default der Extension:** `ws://localhost:7777/extension` (config.js Zeile 39)
+
+---
+
+## 7. Heute erstellte/gefixte Dateien
+
+```
+✅ src/transports/ws.js          — WebSocket + 60s Keep-Alive-Ping
+✅ src/transports/external.js    — External messaging stub
+✅ src/transports/native.js      — Native messaging stub
+✅ src/tools/behavior.js         — Behavior tools stub
+✅ src/core/lifecycle.js         — behavior-store-Import auskommentiert
+```
+
+---
+
+## 8. ABHÄNGIGKEIT: Heypiggy Worker
+
+Der `A2A-SIN-Worker-heypiggy` nutzt die Bridge via `BRIDGE_MCP_URL`.
+
+**Wichtig:** Ohne Extension läuft GAR NICHTS. Der Worker macht HTTP-Calls an die Bridge, die Bridge leitet per WebSocket an die Extension, die Extension führt in Chrome aus.
+
+```
+Worker → curl http://localhost:7777/mcp → Bridge Server → WebSocket → Extension → Chrome
+```
+
+---
+
+*Letzte Aktualisierung: 28. April 2026*

extension/src/tools/behavior.js

@@ -0,0 +1,8 @@
+/**
+ * Behavior tools stub — human-like interaction patterns.
+ */
+export function register(router) {
+  router.register("behavior.delay", async () => ({ ok: true }));
+  router.register("behavior.scroll", async () => ({ ok: true }));
+  router.register("behavior.hover", async () => ({ ok: true }));
+}

extension/src/transports/external.js

@@ -0,0 +1,12 @@
+/** External runtime messaging transport — stub. */
+export function attach({ router }) {
+  chrome.runtime.onMessageExternal.addListener((msg, sender, sendResponse) => {
+    try {
+      const result = router(msg);
+      sendResponse(result);
+    } catch (e) {
+      sendResponse({ error: e.message });
+    }
+    return true;
+  });
+}

extension/src/transports/native.js

@@ -0,0 +1,8 @@
+/** Native messaging transport — stub (no host configured). */
+export function create({ router, clientId }) {
+  return {
+    send: () => {},
+    close: () => {},
+    isConnected: () => false,
+  };
+}

extension/src/transports/ws.js

@@ -0,0 +1,105 @@
+/**
+ * WebSocket transport — connects to local bridge server.
+ *
+ * Opens a WebSocket to ws://localhost:7777/extension and relays
+ * JSON-RPC messages between the Chrome extension and the bridge server.
+ */
+import { CONFIG } from "../core/config.js";
+import { createLogger } from "../core/logger.js";
+
+const log = createLogger("ws");
+
+export function create({ router, clientId }) {
+  const url = CONFIG.wsUrl || "ws://localhost:7777/extension";
+  log.info(`Connecting to ${url} (client: ${clientId})`);
+
+  let ws = null;
+  let reconnectTimer = null;
+  let keepAliveTimer = null;
+  let reconnectAttempts = 0;
+
+  function connect() {
+    try {
+      ws = new WebSocket(url);
+
+      ws.onopen = () => {
+        log.info("WebSocket connected");
+        reconnectAttempts = 0;
+        // Send handshake
+        ws.send(JSON.stringify({
+          jsonrpc: "2.0",
+          method: "extension.connect",
+          params: { clientId, version: "5.0.0" },
+          id: 0
+        }));
+        // Start keep-alive pings every 60 seconds
+        keepAliveTimer = setInterval(() => {
+          try {
+            ws.send(JSON.stringify({
+              jsonrpc: "2.0",
+              method: "ping",
+              params: { clientId },
+              id: -1
+            }));
+          } catch {}
+        }, 60000);
+      };
+
+      ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data);
+          router(msg);
+        } catch (e) {
+          log.error("Invalid message", e.message);
+        }
+      };
+
+      ws.onclose = () => {
+        if (keepAliveTimer) { clearInterval(keepAliveTimer); keepAliveTimer = null; }
+        log.warn("WebSocket closed, reconnecting...");
+        scheduleReconnect();
+      };
+
+      ws.onerror = (err) => {
+        log.error("WebSocket error", err?.message || "unknown");
+      };
+    } catch (e) {
+      log.error("Failed to create WebSocket", e.message);
+      scheduleReconnect();
+    }
+  }
+
+  function scheduleReconnect() {
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    const delay = Math.min(1000 * Math.pow(2, reconnectAttempts), 30000);
+    reconnectAttempts++;
+    log.info(`Reconnecting in ${delay}ms (attempt ${reconnectAttempts})`);
+    reconnectTimer = setTimeout(connect, delay);
+  }
+
+  function send(data) {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(data));
+    }
+  }
+
+  connect();
+
+  const transport = {
+    send,
+    close: () => { if (reconnectTimer) clearTimeout(reconnectTimer); ws?.close(); },
+    stop: () => { if (reconnectTimer) clearTimeout(reconnectTimer); ws?.close(); },
+    start: () => { if (!ws || ws.readyState > 1) connect(); },
+    isConnected: () => ws?.readyState === WebSocket.OPEN,
+    status: "connected",
+  };
+
+  // Update status based on connection state
+  if (ws) {
+    ws.addEventListener("open", () => { transport.status = "connected"; });
+    ws.addEventListener("close", () => { transport.status = "disconnected"; });
+    ws.addEventListener("error", () => { transport.status = "error"; });
+  }
+
+  return transport;
+}