Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -1069,6 +1069,33 @@ because breaking it fails silently:
from `PulseLoopApplication`). Ring rows carry no device id, so a later sweep could not split
the two rings' data.

## On-device coach: grounded, no tools, safety first

**Read this before touching `coach/ondevice/` or the `ON_DEVICE` provider.** Design and as-built
notes: `docs/on-device-model-and-mcp-plan.md`, Part 1.

- **No tools and no writes on this provider.** `OnDeviceResponsesClient` never offers the
request's tools and never returns a function call, so no write tool or confirm card can come
from it; `PulseLoopApp`'s flags also turn off web search and live measurements for it. A 1B
model can't run the tool loop; don't wire it in "to see if it works".
- **Safety runs before the model.** `OnDeviceSafety.route` sends crisis, emergency and
medicine/dose questions to fixed replies (CVV 188, SAMU 192, "ask your doctor or pharmacist")
without loading the model. Those replies are written in the router, not through `tr()`: no
voice catalog may rewrite them. New keywords go in both languages, already normalized, with a test.
- **The reply is always a complete `coach_response`.** The client wraps the model's plain text
(`coachResponseJson`) so `parseFinal` accepts it on the first try. Asking the 1B model to write
JSON itself would spend repair rounds of slow generation and still fail.
- **Only the coach chat may use it.** Any other `text.format` (meal estimate, lab report,
summary) is refused: a small model must not read a lab report or estimate a meal.
- **The model is never in git, the APK or the backup.** It is downloaded on request, kept in
`noBackupFilesDir`, and re-downloadable; the data archive must not pick it up. Only the
provider choice (`coach_provider_mode`) rides in `ArchivedSettings`.
- **Every download is SHA-256 checked** against the `.sha256` published beside it on the
pre-release, and is **Wi-Fi only by default** (`setAllowedOverMetered(false)`); mobile data is
the user's explicit choice.
- **Keep `MAX_TOKENS` at the figure the file is proven with** (1280). A prompt past the window
crashes natively, which is why `OnDevicePrompt.fit` measures with the model's own tokenizer.

## Health Connect as the data source: one app, no ring, nothing back

**Read this before touching `health/source/` or the export's exclusions.** Full design:
Expand All @@ -1090,6 +1117,39 @@ and each one fails silently if broken:

It is exclusive with a paired ring: a `DeviceIdentified` turns it off.

## MCP on your network: read-only, paired, private addresses only

**Read this before touching `mcp/` or `ui/screens/McpSettingsUi.kt`.** Threat model:
`docs/mcp-threat-model.md`. Settings › Connected apps › AI tools on your network runs an MCP
server on the phone (port 8765, `POST /mcp`) so the user's own Claude Desktop or Cursor can read
their data. Each rule fails silently if broken:

- **The tools are an explicit allowlist** (`McpCoachTools.ALLOWLIST`), never "whatever the
registry holds with writes off": `ToolRegistry`'s always-on set already contains writes
(`log_meal`, `set_goal`, `log_drink`, `save_food_preference`, `set_drink_plan`) and a
cache-writing network call (`search_food_database`). Add a name only after reading its
implementation; `McpAllowlistTest` fails on a write name and on any coach tool nobody has
classified. Calls run with all three flags off and `coordinator = null`.
- **Never a tool for** API keys, raw packets, diagnostics, lab-report PDFs or the EPDS answers.
`summary` reuses `CoachContextBuilder.build` but drops labs, postpartum, drinks and the goal
plan; keep it that way.
- **Refusal order is part of the design**: `Origin` header → 403, then token → 401, then path and
method, all before a tool runs. Peers outside loopback/private/link-local/100.64/10/ULA are
closed before a byte is read, and nothing binds a public address or a mobile-data interface.
- **Bounds stay**: 4 connections, 15 s, 8 KB head, 256 KB body, no chunked bodies, no JSON-RPC
batches, one tool call at a time.
- **Tokens are shown once and stored as SHA-256 only**, in `mcp_server` preferences. That file,
and the on/off switch in it, are device state and security material: **never add them to
`ArchivedSettings`** — a restore on a new phone must start off with nothing paired.
- **Off by default, foreground while on, never back by itself**: `START_NOT_STICKY`, no boot
receiver, auto-off after the chosen hours (default 8), and stopping for any reason clears the
switch. The notification's tap stops it. Type `dataSync` (Android 15 ends it at its daily
limit through `onTimeout`; keep that override).
- **The `instructions` say it is not a diagnostic tool** and the numbers are estimates — the same
rule the coach follows. Keep them in step with the coach's prompt.
- The protocol, HTTP, address and token code has no Android imports and is JVM-tested; keep new
logic there rather than in the service.

## Every UI string goes through `tr()`, and the English text is the key

**The app speaks English and Brazilian Portuguese (Settings → Language, `ui/i18n/L10n.kt`).** There
Expand Down
5 changes: 5 additions & 0 deletions app/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,11 @@ dependencies {
// stub, which strips the class at compile time. Full guava restores it.
implementation("com.google.guava:guava:33.3.1-android")

// The on-device coach (docs/on-device-model-and-mcp-plan.md, Part 1): MediaPipe LLM Inference
// runs a downloaded Gemma 3 1B `.task` file on the CPU. No permissions; the model itself is
// never in the APK. The same version Cochilo ships; LiteRT-LM waits for the Kotlin bump.
implementation("com.google.mediapipe:tasks-genai:0.10.35")

debugImplementation("androidx.compose.ui:ui-tooling")
debugImplementation("androidx.compose.ui:ui-test-manifest")

Expand Down
10 changes: 10 additions & 0 deletions app/proguard-rules.pro
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,13 @@
-keepclasseswithmembers class com.pulseloop.update.** {
kotlinx.serialization.KSerializer serializer(...);
}

# On-device coach (MediaPipe LLM Inference, docs/on-device-model-and-mcp-plan.md): its classes are
# reached from native code and its options are protobuf messages, so R8 must leave them whole.
-keep class com.google.mediapipe.** { *; }
-dontwarn com.google.mediapipe.**
-keep class com.google.protobuf.** { *; }
-dontwarn com.google.protobuf.**
# AutoValue / annotation-processing references inside MediaPipe that aren't on Android.
-dontwarn javax.lang.model.**
-dontwarn com.google.auto.value.**
10 changes: 10 additions & 0 deletions app/src/main/AndroidManifest.xml
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,9 @@
missing entirely, so every workout start crashed on API 34+. -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_HEALTH" />
<!-- "AI tools on your network" (mcp/McpService): the read-only MCP server runs as a dataSync
foreground service while the user has it on. docs/mcp-threat-model.md -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />

<!-- Self-update: fetch the GitHub release manifest/APK and install it -->
Expand Down Expand Up @@ -160,6 +163,13 @@
android:foregroundServiceType="health"
android:exported="false" />

<!-- Read-only MCP server for paired AI tools on the user's own network. Not exported:
only PulseLoop's settings screen starts it. docs/mcp-threat-model.md -->
<service
android:name=".mcp.McpService"
android:foregroundServiceType="dataSync"
android:exported="false" />

<!-- Home-screen widgets (iOS #44): three Glance app widgets + the shared configure
activity for the two configurable ones. -->
<receiver
Expand Down
Loading
Loading