@infomity/remogent 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# Remogent
+
+<p align="center">
+  <strong>Zero-Recurring-Cost Android Remote AI Agent & Terminal Client</strong><br>
+  <em>Drive Gemini CLI, Claude Code CLI and Codex CLI directly from your phone over secure, pinned-TLS transport.</em>
+</p>
+
+<p align="center">
+  <img src="docs/screenshots/01-new-chat.png" alt="Remogent new chat screen with agent, folder and permission-mode chips" width="190">
+  <img src="docs/screenshots/02-sessions.png" alt="Remogent drawer listing chat sessions across Claude Code, Gemini CLI and Codex CLI" width="190">
+  <img src="docs/screenshots/03-chat.png" alt="Remogent chat showing a Bash tool card and Claude Code's reply" width="190">
+  <img src="docs/screenshots/04-approval.png" alt="Remogent tool approval sheet with diff preview and Deny, Allow once and For session buttons" width="190">
+</p>
+
+---
+
+## Overview
+
+**Remogent** enables software engineers to monitor, prompt, and approve actions from **Gemini CLI**, **Claude Code CLI** and **Codex CLI** from their Android phone without paying monthly cloud relay fees. 
+
+Designed following the **Infomity Studio** ([infomity.github.io](https://infomity.github.io/)) aesthetic, Remogent features Obsidian Luxury Dark & Clean Studio Light palettes, subtle engineering grid backgrounds, frosted glass surfaces, and custom status capsules with pulsing live indicators.
+
+### Core Pillars
+- **$0.00 Infrastructure Cost**: Direct peer-to-peer transport over local Wi-Fi, Tailscale, WireGuard, or Cloudflare tunnels. No intermediary cloud servers, no subscriptions.
+- **Three AI Engines**: First-class support for **Gemini CLI** (stdio JSON-RPC 2.0 ACP protocol), **Claude Code CLI** (bidirectional stream-json protocol) and **Codex CLI** (`codex app-server` JSON-RPC).
+- **Interactive Tool Approvals**: Destructive operations (`Bash`, file edits, network calls) trigger an audible/haptic approval bottom sheet on your phone with granular control: `Deny`, `Allow Once`, or `Allow for Session`.
+- **Biometric Guard**: Gate tool authorizations and sensitive executions behind on-device biometric fingerprint / face authentication.
+- **Hardware-Backed Keystore Storage**: Host pairing tokens and TLS credentials encrypted on-device via Android Jetpack Security (`MasterKey` + `EncryptedSharedPreferences`).
+- **Cryptographic Pinned TLS**: Every connection verifies the host's 64-character SHA-256 certificate fingerprint, eliminating MITM risks without requiring public CA certificates.
+- **Gap-Free Session Resync**: Transcripts use strict gap-free sequence ordering (`seq`). Disconnecting and reconnecting immediately replays unread deltas and pending permissions.
+
+---
+
+## Architecture
+
+<p align="center">
+  <img src="docs/architecture.png" alt="Remogent architecture: Android app with pinned-TLS WebSocket client connected directly to the PC host companion, which drives Gemini CLI, Claude Code CLI and a PTY shell" width="100%">
+</p>
+
+<sub>Diagram source: [`docs/architecture.mmd`](docs/architecture.mmd) (Mermaid) &middot; vector version: [`docs/architecture.svg`](docs/architecture.svg) &middot; re-render with `docs\render_architecture.cmd`.</sub>
+
+---
+
+## Setup & Operation
+
+### 1. Host Companion Setup (PC)
+
+**Prerequisites:** Node.js >= 20.x, and at least one of `gemini`, `claude` or `codex` installed (found automatically, no PATH editing needed).
+
+```bash
+# Clone the repository
+git clone https://github.com/infomity/Remogent.git
+cd Remogent/companion
+
+# One command: install dependencies, build, check the machine (doctor), then start the host
+# now AND at every sign-in and show the pairing QR
+npm run setup
+```
+
+`doctor` finds the Claude Code, Gemini and Codex CLIs by itself (PATH, then the native installer, npm -g, Volta, pnpm, nvm, Homebrew, scoop), so you never edit PATH, and tells you exactly what to install if something is missing. Run it any time with `npm run doctor`. `install` (the last step of `setup`) registers an autostart service that runs as your user (it needs your `claude` / `gemini` / `codex` logins), starts at sign-in and restarts if it crashes: Task Scheduler on Windows, launchd on macOS, `systemd --user` on Linux. After pairing, the host is simply there; no terminal to keep open. Related commands:
+
+```bash
+node dist/index.js pair       # show the pairing QR again (new phone, or you closed the setup window)
+node dist/index.js status     # autostart state + whether the host answers (log: ~/.remogent/daemon.log)
+node dist/index.js uninstall  # stop and remove the autostart registration
+node dist/index.js start --port 9876 --show-url   # optional: run in the foreground instead (Ctrl+C stops it)
+```
+
+`npm run pair` is the same as `node dist/index.js pair`. It prints the QR, waits for the phone to connect, then closes itself (`--no-wait` keeps it open, `--timeout MIN` changes the 5-minute limit, `--show-url` also prints the `remogent://` link, `--host IP` overrides the address in the code). The code contains your pairing secret, so do not share a screenshot of it.
+
+The daemon will:
+1. Load or generate a persistent self-signed TLS certificate and random bearer token at `~/.remogent/identity.json`.
+2. Advertise service on the local network via mDNS (`_remogent._tcp`).
+3. Run hidden in the background, so it prints nothing itself. The pairing QR is shown at the end of `setup` / `install`, and any time later by `pair`. The code encodes a link like:
+   ```text
+   remogent://pair?host=192.168.x.y&port=9876&token=...&fp=...&name=my-pc&alt=100.x.y.z
+   ```
+   `alt` (optional, comma separated, up to 4) lists the PC's other usable addresses, such as a second LAN or Tailscale. The app tries `host` first and falls back to these when it does not answer, and tries the one that worked first on reconnects until the app is restarted. Pass `--host IP` to `install` / `pair` to pin a single address and omit `alt`.
+
+To rotate the authentication secret at any time:
+```bash
+node dist/index.js install --rotate   # re-registers the service with a new secret; re-pair the phone afterwards
+```
+
+Chats survive daemon restarts: transcripts are saved to `~/.remogent/sessions.json` (owner-only file, newest ~2 MiB per chat, 14 days / 100 chats). Claude Code and Codex chats resume with their full context on the next prompt; Gemini chats come back as read-only history. Pending approvals and "Allow for session" grants are never restored. To keep nothing on disk, start with `--no-persist`.
+
+---
+
+### 2. Android App Installation & Pairing
+
+**Prerequisites:** Android 8.0+ (API 26+), Android Studio with JDK 17.
+
+```bash
+cd android_app
+./gradlew assembleDebug
+```
+The compiled debug APK will be generated at:
+```
+android_app/app/build/outputs/apk/debug/app-debug.apk
+```
+
+To install directly to a connected device:
+```bash
+./gradlew installDebug
+```
+
+#### Pairing Steps:
+0. For the first pairing, put the phone and the PC on the **same Wi-Fi network** (the QR's main address is the PC's local one). To also use the phone away from home, set up Tailscale first: see [Using Remogent away from home](#using-remogent-away-from-home-tailscale-free) below.
+1. On the PC, make sure the QR is on screen: it is printed at the end of `npm run setup`, or run `npm run pair` in `companion/` to show it again.
+2. Open **Remogent** on your Android device, open the drawer, expand the host card and tap **Pair new host**.
+3. Tap **SCAN QR CODE** and point the camera at the QR (or paste the `remogent://pair?...` link, which `pair --show-url` prints).
+4. The app verifies the 64-character SHA-256 fingerprint, stores the credentials in the Android Keystore and connects. The `pair` window then closes itself.
+5. The status indicator changes to **LIVE** with an emerald pulsing live dot.
+
+#### Using Remogent away from home (Tailscale, free)
+
+At home the phone talks to the PC over Wi-Fi. To keep working on mobile data or another network without any paid relay, add [Tailscale](https://tailscale.com/) (free personal plan; your traffic stays peer-to-peer and Remogent's pinned TLS still applies):
+
+1. Install Tailscale on the **PC** and on the **phone** and sign both in to the same Tailscale account.
+2. On the PC run `npm run pair` (or `node dist/index.js pair`). With Tailscale up, the QR automatically carries the PC's Tailscale address as a backup (`alt=100.x.y.z`); `npm run doctor` lists the addresses it will use.
+3. Scan it in the app as in the steps above. Already paired before installing Tailscale? Just scan the new QR once; the app keeps one profile for the PC and adds the backup address to it.
+
+That is all. The app tries the Wi-Fi address first and, if it does not answer within about 5 seconds, switches to the Tailscale one by itself, so turning Wi-Fi off or leaving home needs no action. After the app is restarted it tries the last address that worked first. The drawer's host card shows which address is connected right now (for example `192.168.x.y` at home, `100.x.y.z` over Tailscale).
+
+Keep Tailscale running on the phone (Android may close VPN apps aggressively under battery saving; exempt it if the fallback never kicks in).
+
+#### If pairing or connecting fails
+- **Cannot connect away from home:** the phone needs Tailscale running and signed in to the same account as the PC, and the QR must have been made while Tailscale was up on the PC (`npm run doctor` should list a `100.x.y.z ... on Tailscale` candidate). If you installed Tailscale after pairing, run `npm run pair` and scan again.
+- **Same network:** without Tailscale, the phone and PC must be on the same Wi-Fi (or reachable through WireGuard). `npm run doctor` shows the address the QR will use and the other candidates; pass `--host IP` to `pair` or `install` to pin one address (no backup is added then).
+- **Scan works but the app cannot connect:** the Windows Firewall is the usual cause. `install` now tries to add an inbound rule for the host port (private networks, local subnet and Tailscale only). That needs administrator rights, so if it prints a firewall warning (or `npm run doctor` does), run `node dist/index.js firewall --elevate` and accept the Windows prompt. `uninstall` removes the rule again.
+- **Port 9876 is taken:** `install` picks the next free port by itself and stores it with the host identity, so every later command (`pair`, `status`, `doctor`, `start`) uses it. Phones paired on the old port must scan the QR once more. `--port N` forces a port.
+- **USB instead of Wi-Fi:** with a cable and USB debugging on, `adb reverse tcp:9876 tcp:9876` lets the phone reach the host as `127.0.0.1`.
+- **QR is gone or the host was rotated:** run `npm run pair` again (after `install --rotate`, re-pair every phone).
+
+---
+
+### 3. Running an AI Session
+
+1. In the active host card, tap **NEW AI SESSION**.
+2. Select your desired engine:
+   - **Gemini CLI** (stdio ACP JSON-RPC)
+   - **Claude Code CLI** (stdio stream-json)
+   - **Codex CLI** (stdio `codex app-server`; sign in once with `codex login`)
+3. Set the working directory (e.g. `.` or an absolute project path).
+4. Choose the permission mode:
+   - `Ask` (Default): Every mutating shell command or file edit prompts for your confirmation.
+   - `Auto (YOLO)`: Automatically approves commands (Gemini `yolo` / Claude `bypassPermissions` / Codex no sandbox, never ask).
+   - `Plan Only`: Read-only execution mode.
+5. Tap **START SESSION**.
+6. Prompt the agent in real time, inspect reasoning in collapsible thought bubbles, and monitor tool outputs.
+
+---
+
+## Testing & Verification
+
+### Companion Daemon Verification
+```bash
+cd companion
+npm run typecheck
+npm run build
+node scripts/smoke.mjs          # Auth, TLS fingerprint & ping checks
+node scripts/sessions-test.mjs   # Protocol v1 session management tests
+node scripts/persistence-test.mjs # Save/restore/resume, mid-turn crash, corrupt store (offline)
+node scripts/claude-persist-live.mjs # OPT-IN: real claude --resume across a daemon restart (2 model calls)
+```
+
+### Android App Verification
+```bash
+cd android_app
+./gradlew testDebugUnitTest     # URI parser (incl. backup addresses), protocol & transcript tests
+./gradlew assembleDebug         # Full APK compilation and packaging
+```
+
+---
+
+## Security Model
+
+1. **Strict Certificate Pinning:** The Android client pins the SHA-256 fingerprint of the host's DER certificate. Untrusted or modified certificates are instantly rejected.
+2. **Bearer Authentication:** All WebSocket upgrade requests require an authentic 32-byte cryptographically secure random token (`Authorization: Bearer <token>`). Unauthenticated requests are rejected before reaching the WebSocket handler.
+3. **Hardware Storage:** Token secrets and server fingerprints are stored inside Android Keystore (`MasterKey` with AES-256-GCM and AES-256-SIV).
+4. **Biometric Safeguard:** Optional fingerprint/face unlock required prior to authorizing destructive commands on the host machine.
+5. **No Cloud Relays:** All communication is strictly peer-to-peer. Zero telemetry, zero analytics.
+
+---
+
+## Support
+
+Remogent is free and open-source, with no ads, no subscriptions and no cloud relay. If it helps your work, you can support ongoing development on [Patreon](https://www.patreon.com/Infomity). The Android app has the same button at the bottom of **Settings**.
+
+---
+
+## Privacy
+
+Remogent collects no data and runs no servers. Read the [Privacy Policy](https://infomity.github.io/remogent/privacy/) ([summary and Play Data safety answers](docs/PRIVACY_POLICY.md)); the app links to it from **Settings -> About Remogent**.
+
+---
+
+## License
+
+Apache-2.0. Built by the **Infomity Studio** team.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.