# Pipelines Android client A native Android (Kotlin + Jetpack Compose Material 3) client for an existing Pipelines server. All execution, model credentials, definitions and run history stay on the server; the app only speaks the existing WebSocket protocol. ## Scope and safety - **Trusted LAN/VPN only.** The Pipelines API has **no authentication** and is **not internet-safe**. Do not expose the server to untrusted networks. - **No secrets.** The app stores no credentials, tokens or provider keys and sends no auth headers. Only the server URL and workspace path are persisted as plain, non-secret preferences. - **No hardcoded server.** The server URL and workspace path must be entered explicitly by the user; there is no default/disposable address baked in. - The app does **not** run Docker, execute stages, or reimplement any Go parsing/execution logic. `android/` contains only the client. ## Requirements - JDK 17 (see `compileOptions` / `kotlinOptions.jvmTarget`). - Android SDK with a platform and build-tools matching `compileSdk = 35` (`app/build.gradle.kts`), and `ANDROID_HOME`/`ANDROID_SDK_ROOT` set. - Gradle 8.9+ (AGP 8.7.2, Kotlin 2.0.21). The version numbers above are deliberate defaults chosen without a discovered SDK; adjust `compileSdk`, `targetSdk`, and the versions in `gradle/libs.versions.toml` to whatever is actually installed. If a required SDK/Gradle component is missing, fix the environment rather than downloading untracked artifacts. ### Gradle wrapper `gradle/wrapper/gradle-wrapper.jar` is a generated binary and is intentionally **not committed**. Generate a working wrapper on a machine with Gradle installed: ```sh cd android gradle wrapper --gradle-version 8.9 ``` Until then, build with a locally installed Gradle: ```sh cd android gradle :app:assembleDebug ``` ## Build, test and install ```sh cd android gradle :app:testDebugUnitTest # protocol/URL/graph unit tests gradle :app:assembleDebug # debug APK gradle :app:lintDebug # Android lint # install on a connected device/emulator: gradle :app:installDebug adb shell am start -n net.awan.pipelines/.MainActivity ``` ## Configuration Open the **Settings** tab and enter: - **Server URL** — `ws://HOST:PORT/connect` (LAN/VPN) or `wss://…/connect` (proxy/VPN). A path is optional and defaults to `/connect`, matching the Go server's `GET /connect`. `http(s)`, userinfo and fragments are rejected with a specific message. - **Workspace path** — an **absolute directory that already exists on the execution server**. This is *not* the phone's storage. For Docker, mount the host directory at the same absolute path with the owner's UID/GID so the server can resolve it (see `docs/docker.md` and `compose.yaml`). The field flags a non-absolute path and will not save it, mirroring the repository's start-run guard. Tap **Connect** to open the single shared WebSocket (probed with `ping`, showing the server build). Reconnect uses bounded exponential backoff; **Disconnect** stops it. ## Features - Pipeline list (search/refresh, empty/error/loading states), pipeline details (version list, content hash, source) and the workflow graph. - Workflow graph composable: content-sized nodes, labelled outcome edges (`error*` marks the implicit fallback), `#success`/`#failure` terminals, loops and branches, pan/zoom, and run highlighting (executed routes highlighted, others dimmed) plus a screen-reader description. - Run history with server `usage` aggregates, and run details with steps (status/outcome/diagnostic/session/transcript/file changes/notifications/ control evidence). Session evidence is scoped to the selected run and each record is rendered (sequence/session id/backend/directory/data/diagnostic) on demand via `get_run_evidence`; it is never part of the 1s poll. - A shared connection banner above every screen surfaces a distinct Idle/Connecting/Disconnected state with a Reconnect action (and stays hidden while connected), so a dropped connection is not just a generic request error. - Start run (confirmation dialog; sends `PipelineID`, `Version`, a reused `request_key` ≤128 chars, the configured absolute workspace and `input.prompt`) and cancel run (confirmation; sends the `RunID`, then refreshes). Retry is offered only for terminal failed runs. - A run being polled at a fixed 1s interval is stopped as soon as it is no longer executing. ## Architecture ``` data/protocol kotlinx.serialization models mirroring internal/protocol/* (Message, Graph/Stage, RunDetail/RunStep, UsageStats, …) plus GraphSemantics reproducing internal/tui/graph.go rules. data/transport ServerUrl validation (mirrors internal/client/config.go) and PipelinesClient — one reused WebSocket, serialized requests, client ids matched against replies, unsolicited envelopes dropped, bounded reconnect backoff. data SettingsRepository (non-secret prefs) and PipelinesRepository (typed request builders + per-session graph/detail cache). ui Compose Material 3 screens, one AppViewModel, navigation. ``` ## Verification status Verified on macOS with the host toolchain (JDK 17 from Android Studio, `ANDROID_HOME=/Users/alan/Library/Android/sdk`, Gradle 8.11.1 `--offline`): - `:app:compileDebugKotlin`, `:app:assembleDebug` and `:app:testDebugUnitTest` all succeed; **20 unit tests, 0 failures** (protocol model, graph semantics, server URL, workflow-graph layout). Re-run with `--rerun-tasks` to confirm. - The debug APK was installed and driven on the `Pixel_Fold_API_36` emulator (Android 16) against a live server at `ws://10.0.2.2:8080/connect` with workspace `/Users/alan`. Settings, pipeline list (all 9 pipelines), pipeline detail, the workflow graph, run history, run detail and the disconnected/ reconnect states were captured to `captures/` (git-ignored) and reviewed. - `adb logcat` for the app package contained no `FATAL EXCEPTION`, Compose or other runtime exception during the sweep. Known limitations of that run: pinch-zoom could not be driven through `adb` (single-touch pan only), one portrait Fold viewport was used, and the graph is not fit-to-content on first layout (pan to reach later columns); a panned graph can still draw an edge curve across a neighbouring outcome label.