Files
pipelines/android
alan e843aa08a8 Restructure the Runs area and add collapsible sticky sections
Four related UI changes, all requested after using the app on a phone.

- Graph pinch zoom is now anchored to the gesture centroid. The handler dropped
  the centroid and the canvas scaled about the content origin, so a pinch slid
  the graph away from the fingers. zoomAbout() keeps the content point under the
  fingers fixed, applies the pan and then clampOffset, with unit tests proving
  the centroid point is unchanged and the scale and bounds are respected.
- Pipeline detail and run detail now use a LazyColumn of collapsible sections
  (shared Sections.kt header, rotating chevron, animateContentSize) whose titles
  stick to the top while their content scrolls beneath, with per-section state
  remembered and exposed to accessibility. Steps and session evidence stay lazy
  list items instead of nested scrollables.
- The Runs list is rebuilt: the raw result preview is gone, failures show a
  two-line diagnostic in the error colour, each run has a colour-coded status
  chip with a matching icon per state (RunStatus.kt, core Material icons - no new
  dependency), the usage aggregates render as a metrics block with a formatted
  average instead of a run-on line of seconds, and runs are grouped by day under
  sticky date headers.
- Run detail steps are a timeline: a status dot joined to the next step, the
  stage and visit number, an outcome chip and the duration, with input, output,
  transcript, file changes and notifications behind a per-step 'Show details'.
- One centralised type hierarchy (Typography.kt) for screen title, section
  header, card title, subtitle, body and monospace data, applied across the list,
  the cards and both detail screens.

Verified: :app:assembleDebug and :app:testDebugUnitTest succeed offline with 53
tests and 0 failures (new FormatTest, RunStatusTest and RunGroupingTest;
WorkflowGraphTest 23 to 27), and the app was driven on the emulator with
screenshots of the runs list states, the sticky date header, the steps timeline,
an expanded step, a collapsed section and the sticky section header.
2026-10-15 03:46:06 +01:00
..

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:

cd android
gradle wrapper --gradle-version 8.9

Until then, build with a locally installed Gradle:

cd android
gradle :app:assembleDebug

Build, test and install

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 stage nodes laid out in one row in declaration order, with #failure/#success terminals sharing a lower row and arrows entering their top borders (an error -> #failure route leaves its source's bottom); labelled outcome edges (error* marks the implicit fallback), loops and branches, pan/zoom, and run highlighting (executed routes highlighted, others dimmed) plus a screen-reader description. Edges are drawn as axis-aligned orthogonal polylines like the TUI (routePoints computes the path once per layout and stores it on EdgeLayout.points), and each arrowhead points along its route's final segment rather than the from-to chord. Pinch zoom is anchored to the gesture centroid: the pure zoomAbout keeps the content point under the fingers fixed (clamped to MIN_SCALE/MAX_SCALE) and the existing pan clamp is applied afterwards, so the content no longer slides away from the fingers.
  • One shared graph-panel height (collapsedGraphHeight/expandedGraphHeight) replaces the former 360.dp and 340.dp literals, so both detail screens render the graph at the same size: about 58% of the window height floored at a height that still fits a 4-stage graph with its terminal row. The graph's TopEnd control cluster pairs "Fit graph to view" with an expand/collapse toggle that grows the panel to about the full window height; the expanded state is stored in rememberSaveable and the panel refits on resize. Because the panel lives inside each screen's verticalScroll column, growing it only extends it below the fold, so expanding also requests BringIntoViewRequester to scroll the taller panel back into the visible viewport instead of leaving the graph centred off-screen.
  • Dark-first Material 3 theme with an app-owned colour scheme (no dynamic/ wallpaper colour): the dark scheme is the default and the window background and system bars are dark so launching shows no light flash; a complete light scheme is retained for when it is explicitly requested.
  • Consistent Material 3 top app bars on Pipelines, Runs and Settings (and the existing back/refresh/start/cancel/retry bars on the detail screens).
  • Both detail screens render a single LazyColumn whose sections ("Versions", "Workflow graph", "Source" on a pipeline; "Run graph", "Input", "Output", "Session evidence", "Steps" on a run) are collapsible via a shared SectionHeader: tapping a header toggles it, an animated chevron rotates with the state, the header sticks to the top of the list while its content scrolls under an opaque background, and the state is exposed to accessibility ("Steps, expanded"). Expanded state is rememberSaveable, per section and per screen, defaulting to expanded. Real lists (versions, steps, session evidence) are items of the one outer list, so nothing nests a scrollable.
  • Steps render as a timeline in run detail: a leading status glyph connected to the next step by an outcome-coloured line, the stage with its sequence/visit number, an outcome chip and the duration, with every retained piece of evidence (input, output, transcript, file changes, notifications, control evidence) behind a collapsible, collapsed-by-default detail in monospace.
  • The runs list is grouped by day (Today/Yesterday/date, newest first) under sticky headers, with the usage aggregates as a metrics block (total, average via formatDuration, and colour-coded succeeded/failed/canceled/interrupted/ active counts). Each card shows the pipeline name with a version chip, a colour-coded status chip with a distinct icon per state (running/queued/succeeded/failed/canceled/interrupted/active/unknown), a meta row (run id, start time, duration) and the diagnostic only when non-blank, clamped to two lines. The raw resultPreview is no longer printed, and progress is shown honestly (completed visits + current stage, with an indeterminate indicator while executing; no invented total).
  • One centralised type scale (ui/theme/Typography.kt, passed to MaterialTheme and exposed as named roles) defines the screen/app-bar title, section header, card title, subtitle/meta, body and monospace data, applied on the list and both detail screens.
  • 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; 53 unit tests, 0 failures (protocol model, graph semantics, server URL, workflow-graph layout including the terminal row, bottom exits, back edges, orthogonal routing/axis alignment, arrowhead direction, the shared panel height and the new zoomAbout anchor/clamp cases, plus duration formatting, run-state mapping and run day-grouping). Re-run with --rerun-tasks to confirm.
  • The debug APK was installed and driven on the Pixel_Fold_API_36 emulator (Android 16, adb shell cmd uimode night yes) against a live server at ws://10.0.2.2:8080/connect with workspace /Users/alan/repos/pipelines. Settings, pipeline list (all 9 pipelines), pipeline detail, the workflow graph, run history and run detail were captured to captures/ and captures/style_pass/ (both git-ignored) and reviewed.
  • adb logcat for the app package contained no FATAL EXCEPTION, Compose or other runtime exception during the sweep.
  • The orthogonal-edge / resizable-panel pass was verified the same way: a baseline APK was built from the pre-change tree and installed, then the new build was installed and driven to the 4-stage pipeline-detail graph and a run-detail graph with the executed route highlighted. captures/graph_pass/ (git-ignored) holds pipeline_detail_before/after and run_detail_before/after pairs plus a panned state and the expanded panel after tapping the toggle (pipeline_detail_expanded_after, run_detail_panned_after, run_detail_expanded_after). A review of that pass found the expanded panel scrolled below the fold (blank) and the PNGs prefixed by an adb stderr warning, so the expand now scrolls the panel into view and the after-captures were re-taken with a display id (adb exec-out screencap -p -d <display-id>) so no warning leaks into the files. adb logcat showed no FATAL EXCEPTION and no app/Compose exception during the sweep.

Known limitations of that run: pinch-zoom could not be driven through adb (single-touch pan only) and one portrait Fold viewport was used. A follow-up pass fitted the graph to its viewport on first layout, clamped panning so the content cannot leave the view, added a "Fit graph to view" action, connected on launch when a server URL is already saved, and made the completed/recorded visit wording and the outcome-label contrast consistent. The fitted graph still sits slightly above the box's vertical centre, because the layout box includes padding that is not drawn. A later style pass made the theme dark-first (app-owned scheme; the launch window/bar colours match it) and moved the #failure/#success terminals to a lower row beneath the stage row; before/after captures for the theme, graph and app bar/style are under captures/style_pass/ (*_before.png are the pre-change baseline referenced by the task, *_after.png are the new build).

The Runs-area pass (centroid zoom, collapsible sticky sections, runs list, steps timeline, type hierarchy) was verified the same way on the Pixel_Fold_API_36 emulator (dark mode, adb shell cmd uimode night yes) against the live server: the debug APK was installed, the list/detail/step flows were driven with adb shell input and uiautomator dump, and captures were written to captures/runs_pass/ (git-ignored): runs_list_top, runs_list_scrolled_sticky (a 13 Oct 2026 header pinned under the app bar), runs_list_states, runs_card_interrupted, run_detail_top, run_detail_graph_collapsed, run_detail_steps, run_detail_step_expanded, run_detail_sticky_section (a Steps, expanded header pinned mid-list), pipeline_detail_sections, pipeline_detail_section_collapsed, pipeline_graph_panned and pipeline_graph_fit. adb logcat for the app package contained no FATAL EXCEPTION or Compose/other runtime exception during the sweep. As before, adb cannot synthesise a two-finger pinch, so the centroid-anchored zoom is verified primarily by the zoomAbout unit tests and the on-device graph was exercised with pan + "Fit graph to view" only.