Quest-APKs direkt im Office-Browser installieren und starten

README.md

@@ -9,6 +9,10 @@
 
 # 🏢 Agent Office
 
+APKs für entfernte Tester: **☰ → APK** bietet getrennte Quest-Development- und signierte Store-Builds. Beide Varianten haben ihren eigenen neuesten erfolgreichen Download hinter dem Office-Login, auch über den bestehenden HTTPS-Tunnel. [Einrichtung und Bedienung](docs/dev-apk.md).
+
+Direkt auf die Quest installieren: Im APK-Fenster **Quest verbinden** wählen. Chrome oder Edge verbindet sich per USB mit der Quest am Rechner des jeweiligen Testers. Die neueste Dev-/Store-APK oder eine ausgewählte Datei lässt sich mit Fortschrittsanzeige installieren und anschließend starten. [Browser-Installation](docs/quest-browser-install.md).
+
 **A 3D office your team shares with its coding agents.**
 
 Sit **Claude Code**, **Codex**, **OpenCode**, **Grok**, **Muse**, **DeepSeek Harness** and **Cursor** workers at desks, watch each one's terminal on the laptop in front of it,

docs/code-layout.md

@@ -1,5 +1,7 @@
 # Code layout
 
+The APK dialog mounts its extensions through `src/client/ui/dev-apk/extensions.ts`. Browser-to-Quest installation lives in `src/client/ui/quest-install/`: source streaming, bounded APK manifest parsing, USB adapter, installation lifecycle and UI stay separate. It requires no server-side ADB endpoint and does not add device state to the shared office store.
+
 Back to the [README](../README.md).
 
 Where the code lives, and where a new feature's pieces go. The office used to grow by adding to the middle of a few big files: the server's message switch, the page's key handler, its frame loop and its store. Each of those is a registry now, and a feature is a folder of its own plus one line in each list it joins. If a change has you editing the middle of `main.ts`, `server.ts`, the store or `protocol.ts`, it probably belongs somewhere else.

docs/dev-apk.md

@@ -0,0 +1,66 @@
+# APK bauen und herunterladen
+
+Im Office: **☰ → APK**. Über **Dev-APK** oder **Store-APK** wählst du die Variante. Jede hat ihren eigenen Build-Button, letzten erfolgreichen Download und teilbaren Link. Bestehende Pins bleiben gültig. Der Eintrag lässt sich oben anheften. Er gehört zum gesamten Projekt, nicht zu einem einzelnen Playtest. Der Tester braucht zuhause kein Unity.
+
+## Ablauf
+
+1. Ein freigeschalteter Nutzer drückt **Dev-APK bauen** oder **Store-APK bauen**. Der Server startet `Tools/Build-Quest.ps1 -Development` beziehungsweise `-Store` auf dem Build-PC. Store nutzt den vorhandenen Release-Ablauf einschließlich Signierung und Versionsnummer. Der Button veröffentlicht nichts bei Meta.
+2. Läuft bereits ein Unity-Build oder Test, wartet der Auftrag auf denselben globalen Build-Platz. Status und Protokoll sind sichtbar. Ein zweiter Office-Build wird währenddessen abgelehnt.
+3. Der konfigurierte Branch wird frisch abgerufen und auf einen Commit festgelegt. Der gemeinsame Arbeitscheckout wird weder zurückgesetzt noch umgeschaltet. Gebaut wird im vorbereiteten Build-Ordner.
+4. Erst nach erfolgreichem Build, vollständiger Kopie und SHA-256-Berechnung wird der Download veröffentlicht. Ein Fehlschlag lässt die letzte erfolgreiche APK unverändert.
+5. **APK herunterladen** lädt genau die angezeigte Version. **Download-Link kopieren** liefert einen dauerhaften Link auf die neueste erfolgreiche APK. Der Empfänger benötigt seinen Office-Login.
+
+Der eigene Hintergrundprozess läuft auch bei geschlossenem Browser oder Office-Neustart weiter. Stirbt er, wird der Auftrag als unterbrochen angezeigt. Ein möglicherweise noch laufendes Unity wird nicht beendet; der nächste Build wartet weiterhin auf den gemeinsamen Mutex.
+
+## Einrichtung auf dem Windows-Build-PC
+
+Im Office-Datenordner (`<Office-Home>/.agent-office`, passend zu `--home`) die Datei `dev-apk.json` anlegen. Die Konfiguration wird bei jedem Aufruf neu gelesen und ausschließlich auf dem Server bearbeitet. Browser können keine Befehle, Ordner oder Branches vorgeben.
+
+```json
+{
+  "projects": [{
+    "repo": "KajoVanBuyten/zombie-reality-breach",
+    "sourceDir": "E:/source/Unity/zombie-reality-breach",
+    "buildDir": "E:/source/Unity/zrb-build",
+    "ref": "origin/main",
+    "apkName": "ZombieRealityBreach-dev.apk",
+    "storeApkName": "ZombieRealityBreach.apk",
+    "launcher": "C:/Users/gp/KaMaStudios/tools/unity-hidden.ps1",
+    "builders": []
+  }]
+}
+```
+
+Voraussetzungen: Node, Git, Windows PowerShell, Unity/Android und der funktionierende ZRB-Build-Ablauf inklusive `Tools/BuildLock.ps1`. `sourceDir` ist ein vertrauenswürdiger Projektcheckout mit den erforderlichen Assets; `buildDir` ist ausschließlich ein wegwerfbarer Build-Checkout, niemals ein Arbeitscheckout. Der Office-Prozess muss Zugriff darauf haben. Der vorhandene Build-Ablauf kopiert seine Ausgabe nach `sourceDir/Builds/Quest`; die Download-Kopie wird noch unter demselben Build-Mutex erstellt.
+
+Für Store muss `storeApkName` den vom Build-Script erzeugten Release-Dateinamen angeben; er muss sich vom Dev-Dateinamen unterscheiden. Fehlt das Feld, bleibt Dev nutzbar und Store-Bauen deaktiviert. Die Release-Signierung bleibt ausschließlich auf dem Build-PC in der vom Spiel verwendeten Signing-Konfiguration. Keine Schlüssel oder Passwörter in die Office-Konfiguration eintragen. Die ZRB-Release-Versionsnummer kommt derzeit aus `yyMMddHH`; mehrere Builds innerhalb derselben Stunde erhalten dieselbe Nummer und sind daher nicht automatisch aufeinanderfolgende Meta-Uploads.
+
+Admins und Nutzer des gemeinsamen Office-Passworts dürfen Builds starten. Für weitere Co-Devs deren **Office-Konto-ID** in `builders` eintragen. Alle angemeldeten Office-Nutzer dürfen herunterladen. Keine Issues oder Worker/Queue-Einträge werden erzeugt.
+
+Der Branch ist in der Oberfläche sichtbar. Für XR-Playtest-Werkzeuge muss der gewählte Stand den Spiel-PR #361 enthalten. Ein Development-Build fügt keine noch nicht integrierten Änderungen hinzu.
+
+## Tunnel und Downloads
+
+Die APK liegt unter derselben Office-Adresse: beispielsweise `https://studios.zombierealitybreach.com/api/dev-apk/download?floor=<Etagen-ID>`. Der vorhandene HTTPS-/SSH-Tunnel transportiert den authentifizierten HTTP-Download. Kein zusätzlicher Port oder lokaler `agent-office tunnel`-Helfer ist nötig.
+
+Die vorhandenen API-Pfade und der Datenordner behalten zur Kompatibilität ihren Namen `dev-apk`. Für Store an Status-, Build- und Download-URL `&kind=store` anhängen. Ohne `kind` oder mit `kind=development` gilt weiterhin Dev, auch für ältere Jobs und Links. Eine Store-Anfrage liefert niemals ersatzweise die Dev-APK.
+
+GET/HEAD, Dateigröße, ETag, Range und If-Range ermöglichen fortsetzbare Downloads. Dateien werden gestreamt. Versionierte Links bleiben während neuer Builds unverändert; If-Range verhindert beim Fortsetzen des „neueste“-Links das Vermischen verschiedener Versionen.
+
+Der Proxy muss Cookies und Range-Header weiterleiten, die API darf nicht öffentlich gecacht werden. `X-Accel-Buffering: no` wird gesendet. Bei nginx gegebenenfalls `proxy_buffering off` und ausreichend langen `proxy_read_timeout` für den Download-Pfad konfigurieren. `client_max_body_size` begrenzt Uploads, nicht diese Downloads. Build-PC und Tunnel müssen online bleiben.
+
+## Installation beim Tester
+
+Im APK-Fenster **Quest verbinden** wählen, das USB-Gerät auswählen und USB-Debugging im Headset bestätigen. Anschließend die neueste Dev-/Store-APK oder eine zuvor heruntergeladene Datei installieren. **Spiel starten** wird nach bestätigter Installation freigeschaltet. Das funktioniert am Rechner des Testers auch über das entfernte Office. Voraussetzungen und Fehlerhilfe: [Auf Quest installieren](quest-browser-install.md).
+
+Alternativ bleibt die Installation mit **Meta Quest Developer Hub** oder `adb install -r <Datei.apk>` möglich. Unity ist nicht nötig. Der Quest-Browser selbst installiert eine heruntergeladene APK nicht automatisch.
+
+Bei anderer Signatur als der Store-Version kann Android das Update ablehnen. Nicht automatisch deinstallieren: Lokale Spieldaten könnten verloren gehen.
+
+Meta verlangt auch für Alpha/Beta/RC die Release-Verpackungsregeln. Für unsere debuggable Dev-APK nutzen wir Sideloading; signierte Release-Builds können über Meta-Testkanäle verteilt werden. Quellen: [Release-Kanäle](https://developers.meta.com/horizon/resources/publish-release-channels/) und [Manifest-Regeln](https://developers.meta.com/horizon/resources/publish-mobile-manifest/).
+
+## Speicherung und Prüfung
+
+Unter `<Office-Datenordner>/dev-apk/` liegen Aufträge, Protokolle und APKs. Pro Variante bleiben die letzten drei erfolgreichen APKs erhalten. Store-Veröffentlichungen löschen keine Dev-APKs und umgekehrt. Ältere APK-Dateien werden nach erfolgreicher Veröffentlichung entfernt; Metadaten und Logs bleiben bestehen. Partielle oder fehlgeschlagene Builds ersetzen niemals den neuesten erfolgreichen Download.
+
+Prüfung: `npm run typecheck`, `npm test`, `npm run build`; gezielt `node --import tsx --test tests/dev-apk.test.ts tests/size.test.ts`; Browser-Abnahme `node --import tsx tests/dev-apk-browser.mjs`. HTTP-/Browser-Tests mit Testdateien sind getrennt von echten Unity-Builds, öffentlichen Tunnel-Downloads und Headset-Installation zu berichten.

docs/quest-browser-install.md

@@ -0,0 +1,36 @@
+# APK aus dem Office auf die Quest installieren
+
+**☰ → APK → Auf Quest installieren** verbindet den Browser mit der Quest am eigenen Rechner. Auch wenn das Office bei einem Kollegen läuft, wird das lokal angeschlossene Headset verwendet. Unity, ein Office-Server oder ein Tunnel-Helfer sind beim Tester nicht erforderlich.
+
+## Ablauf
+
+1. Office in Chrome oder Edge auf dem Rechner öffnen, über HTTPS oder bei lokalem Betrieb über localhost. Im Office anmelden.
+2. Quest-Entwicklermodus aktivieren, das eingeschaltete Headset mit einem USB-Datenkabel anschließen. Unter Windows kann der Meta-ADB-Treiber erforderlich sein.
+3. **Quest verbinden** drücken, das Gerät im Browser auswählen und **USB-Debugging zulassen** im Headset bestätigen. Diese Freigaben sind notwendig; die Website kann sie nicht automatisch erteilen.
+4. Oben **Dev-APK** oder **Store-APK** wählen und den passenden Installationsbutton drücken. Es wird genau der angezeigte erfolgreiche Build übertragen. Alternativ **APK-Datei auswählen** und danach **Ausgewählte APK installieren** drücken.
+5. Während Übertragung, Prüfung und Installation USB verbunden lassen. Erst nach Androids Erfolgsbestätigung wird **Spiel starten** freigegeben.
+
+Für die neueste Office-APK ist kein vorheriger Download nötig. Der vorhandene HTTPS-Tunnel transportiert die APK zum Browser; USB führt vom Rechner des Testers zu dessen Quest. Der Office-Server erhält keine ADB-Verbindung zum entfernten Headset. Der ADB-Verbindungsschlüssel bleibt im Browserprofil auf diesem Rechner.
+
+## Fehler und Abbruch
+
+- Firefox und Safari bieten den benötigten WebUSB-Zugriff nicht. Bei fehlender Unterstützung bleibt der Download nutzbar und die Installation deaktiviert.
+- Bei belegter USB-Verbindung SideQuest, Meta Quest Developer Hub und andere ADB-Verbindungen schließen. Ein im Hintergrund laufender ADB-Server muss gegebenenfalls ebenfalls beendet werden. Treiber und Datenkabel prüfen.
+- Bei unterschiedlicher App-Signatur bleibt die vorhandene Installation erhalten. Eine passend signierte APK verwenden. Die Funktion deinstalliert keine App und löscht keine Spieldaten, um einen Signaturkonflikt zu umgehen.
+- Versions-Downgrades werden nicht erzwungen. Speicherfehler, fehlende Anmeldung, unterbrochene Downloads und abgezogene Kabel erscheinen als Fehler, ohne Startfreigabe.
+- **Abbrechen**, **✕** oder **Esc** bricht den laufenden Vorgang ab. ✕ und Esc schließen das Fenster unmittelbar und geben die Maussteuerung zurück. Falls Android bereits mit der Installation begonnen hat, kann es diese trotzdem abschließen: den App-Stand im Headset prüfen.
+- **Trennen** gibt die USB-Verbindung frei. Beim Schließen wird nach dem Abbruch die Verbindung ebenfalls geschlossen. Erneutes Öffnen erfordert erneutes Verbinden.
+
+## Umfang und technische Grenzen
+
+Unterstützt werden einzelne APK-Dateien bis knapp 4 GiB mit binärem Android-Manifest, kein ZIP64 und keine APKS-/Split-Pakete. Paketname und Startaktivität werden aus APK und Gerät ermittelt; es ist kein Paketname fest einprogrammiert. Manifest und ZIP-Verzeichnis werden begrenzt gelesen, die APK selbst in kleinen Blöcken übertragen.
+
+Office-Dateien werden ausschließlich über die authentifizierte Download-Route derselben Office-Adresse mit fester Build-ID geladen. Nach der Übertragung wird deren SHA-256 auf dem Gerät geprüft. Bei lokal ausgewählten Dateien gibt es keine unabhängige Office-Prüfsumme; Android prüft die APK bei der Installation. Die temporäre Datei hat pro Versuch einen eigenen Namen und wird anschließend nach Möglichkeit entfernt. Es wird kein beliebiger ADB-Befehlseingang bereitgestellt.
+
+Ein Reverse Proxy darf WebUSB nicht durch `Permissions-Policy: usb=()` verbieten. Für die APK gelten dieselben Range-/Download-Voraussetzungen wie beim [APK-Download](dev-apk.md).
+
+## Prüfung
+
+`npm run typecheck`, `npm test`, `npm run build`. Gezielte Regressionen: `node --import tsx --test tests/quest-install.test.ts`. Browser-Abnahme: `node --import tsx tests/quest-install-browser.mjs`.
+
+Die Browser-Abnahme verwendet die echte Oberfläche, APK-Auswertung und Installationssteuerung mit simuliertem USB-Gerät. Sie prüft Auswahl, Benutzerinteraktion, Fortschritt, Startfreigabe, Fehler, Abbruch und Schließen. Ein echter Quest-Installationslauf und die USB-/Treiberkombination des entfernten Testers sind gesonderte Hardware-Prüfungen.

package.json

@@ -31,6 +31,11 @@
     "@lydell/node-pty": "^1.2.0-beta.15",
     "@xterm/addon-serialize": "^0.14.0",
     "@xterm/headless": "^6.0.0",
+    "@yume-chan/adb": "2.6.4",
+    "@yume-chan/adb-credential-web": "2.1.0",
+    "@yume-chan/adb-daemon-webusb": "2.3.2",
+    "@yume-chan/stream-extra": "2.6.1",
+    "fflate": "0.8.3",
     "selfsigned": "^5.5.0",
     "ws": "^8.21.3"
   },

src/client/features/hud/index.ts

@@ -18,6 +18,7 @@ import { toggleFloorMenu } from '../../ui/floormenu';
 import { openHelp } from '../../ui/hud';
 import { mountHud } from '../../ui/menu';
 import { openServices } from '../../ui/services';
+import { devApkAction } from '../../ui/dev-apk';
 import { openSettings, type SettingsPane } from '../../ui/settings';
 import { needsSigningIn, openSignIns } from '../../ui/signins';
 import { openTeam } from '../../ui/team';
@@ -49,6 +50,7 @@ export function installHud(ctx: Ctx, core: CoreState, parts: HudParts) {
   const noMedia = () => (window.isSecureContext ? undefined : 'Voice and screen sharing need HTTPS or localhost — use a TLS proxy, --self-signed, or an SSH tunnel');
   const hud = mountHud(
     [
+      devApkAction,
       { id: 'issues', icon: '📌', label: 'Issues', section: 'Open', count: () => store.issues.items.filter((i) => i.state === 'OPEN').length, run: () => openBoard('issues', net, actions.boardActions()) },
       { id: 'pulls', icon: '🔀', label: 'Pull requests', section: 'Open', count: () => store.pulls.items.filter((p) => p.state === 'OPEN').length, run: () => openBoard('pulls', net, actions.boardActions()) },
       { id: 'queue', icon: '📋', label: 'Task queue', section: 'Open', count: () => store.queue.tasks.filter((t) => t.status !== 'done').length, title: () => 'Issues and tasks waiting for a worker', run: waiting.showQueue },