feat(mobile): show agent activity in an Android home screen widget

apps/mobile/app.config.ts

@@ -194,7 +194,15 @@ const widgetsPlugin: NonNullable<ExpoConfig["plugins"]>[number] = [
         name: "AgentActivity",
         displayName: "Agent Activity",
         description: "Shows the current state of active T3 Code agents.",
-        android: null,
+        android: {
+          minWidth: 250,
+          minHeight: 110,
+          targetCellWidth: 4,
+          targetCellHeight: 2,
+          resizeMode: "both",
+          // The embedded layout renders before first launch; publishing replaces it with stored props.
+          initialLayout: "./src/widgets/AgentActivityWidget.android.tsx",
+        },
         ios: {
           supportedFamilies: ["systemSmall", "systemMedium", "accessoryRectangular"],
           // Embeds the layout so the gallery preview and a new widget render

apps/mobile/modules/t3-agent-notifications/android/src/main/java/expo/modules/t3agentnotifications/AgentActivityWidgetSync.kt

@@ -0,0 +1,93 @@
+package expo.modules.t3agentnotifications
+
+import android.content.ComponentName
+import android.content.Context
+import android.content.Intent
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * Repaints the Agent Activity home screen widget from a relay push, so it stays current
+ * while the app is closed. The app's foreground refresh still overwrites these props with
+ * the full snapshot; this only keeps the widget from sitting on "Out of date" in between.
+ */
+internal object AgentActivityWidgetSync {
+  private const val WIDGET = "AgentActivity"
+  private const val WIDGET_STORE = "expo.modules.widgets"
+  private const val PROPS_KEY = "__expo_widgets_${WIDGET}_props"
+  private const val PUSH_AT_KEY = "t3_agent_activity_push_at"
+
+  // Pushes arrive only on changes; match the relay's running-row TTL (and the app's
+  // AGENT_ACTIVITY_ANDROID_WIDGET_STALE_AFTER_MS) instead of flagging quiet agents.
+  private const val STALE_AFTER_MS = 2 * 60 * 60 * 1000L
+  private const val EXPIRY_RECEIVER = "expo.modules.t3widgetexpiry.WidgetExpiryReceiver"
+  private const val EXPIRY_NAME = "expo.modules.t3widgetexpiry.NAME"
+  private const val EXPIRY_DEADLINES = "expo.modules.t3widgetexpiry.DEADLINES"
+
+  fun update(context: Context, data: Map<String, String>, updatedAt: Long) {
+    val store = context.applicationContext.getSharedPreferences(WIDGET_STORE, Context.MODE_PRIVATE)
+    // FCM can deliver out of order; an older push must not replace newer rows.
+    if (updatedAt <= store.getLong(PUSH_AT_KEY, 0)) return
+    val rows = activityRows(data)
+    val path = data["activity_path"].orEmpty()
+    val scheme = context.getSharedPreferences("t3-agent-notifications", Context.MODE_PRIVATE)
+      .getString("scheme", "t3code") ?: "t3code"
+    val updated = iso(updatedAt)
+    val current = JSONArray()
+    val stale = JSONArray()
+    var inFlight = false
+    rows.forEachIndexed { index, row ->
+      val phase = widgetPhase(ActivityPhase.forStatus(row.status))
+      val finished = phase == "completed" || phase == "failed"
+      if (!finished) inFlight = true
+      fun json(phase: String, status: String) = JSONObject()
+        .put("environmentId", "push")
+        .put("threadId", index.toString())
+        .put("projectTitle", row.project)
+        .put("threadTitle", row.title)
+        .put("modelTitle", "")
+        .put("phase", phase)
+        .put("status", status)
+        .put("updatedAt", updated)
+        .put("deepLink", data["activity_row_path_$index"] ?: if (index == 0) path else "")
+      current.put(json(phase, row.status))
+      stale.put(if (finished) json(phase, row.status) else json("stale", "Out of date"))
+    }
+    val staleAt = updatedAt + STALE_AFTER_MS
+    val props = JSONObject()
+      .put("appUrl", "$scheme://")
+      .put("title", data["activity_title"].orEmpty())
+      .put("subtitle", if (rows.isEmpty()) "No active agents" else "")
+      .put("activeCount", data["activity_active_count"]?.toIntOrNull() ?: 0)
+      .put("updatedAt", updated)
+      .put("activities", current)
+    if (inFlight) props.put("stale", JSONObject().put("at", staleAt).put("activities", stale))
+    store.edit().putString(PROPS_KEY, props.toString()).putLong(PUSH_AT_KEY, updatedAt).commit()
+
+    // The expiry receiver repaints now and sets the alarm that swaps in the stale rows.
+    context.sendBroadcast(
+      Intent().setComponent(ComponentName(context.packageName, EXPIRY_RECEIVER))
+        .putExtra(EXPIRY_NAME, WIDGET)
+        .putExtra(EXPIRY_DEADLINES, if (inFlight) longArrayOf(staleAt) else LongArray(0))
+    )
+  }
+
+  private fun widgetPhase(phase: ActivityPhase?) = when (phase) {
+    ActivityPhase.STARTING -> "starting"
+    ActivityPhase.APPROVAL -> "waiting_for_approval"
+    ActivityPhase.INPUT -> "waiting_for_input"
+    ActivityPhase.STALE -> "stale"
+    ActivityPhase.COMPLETED -> "completed"
+    ActivityPhase.FAILED -> "failed"
+    ActivityPhase.RUNNING, null -> "running"
+  }
+
+  private fun iso(millis: Long) =
+    SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", Locale.US)
+      .apply { timeZone = TimeZone.getTimeZone("UTC") }
+      .format(Date(millis))
+}

apps/mobile/modules/t3-agent-notifications/android/src/main/java/expo/modules/t3agentnotifications/AgentNotifications.kt

@@ -124,6 +124,10 @@ object AgentNotifications {
       data["device_id"] == prefs.getString("deviceId", null) &&
       data["user_id"] == prefs.getString("userId", null)
     val fresh = System.currentTimeMillis() - updatedAt in -MAX_MESSAGE_AGE_MS..MAX_MESSAGE_AGE_MS
+    // The widget needs no notification permission, so it updates even when alerts are off.
+    if (registered && fresh) {
+      runCatching { AgentActivityWidgetSync.update(context, data, updatedAt) }
+    }
     if (registered && fresh && NotificationManagerCompat.from(context).areNotificationsEnabled()) {
       channels(context)
       val scheme = prefs.getString("scheme", "t3code") ?: "t3code"

apps/mobile/modules/t3-agent-notifications/android/src/test/java/expo/modules/t3agentnotifications/AgentActivityWidgetSyncTest.kt

@@ -0,0 +1,76 @@
+package expo.modules.t3agentnotifications
+
+import android.content.Context
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.Shadows.shadowOf
+import org.robolectric.annotation.Config
+
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [24, 36], manifest = Config.NONE)
+class AgentActivityWidgetSyncTest : AgentNotificationsFixture() {
+  private fun widgetStore() =
+    context.getSharedPreferences("expo.modules.widgets", Context.MODE_PRIVATE)
+
+  private fun props() =
+    JSONObject(requireNotNull(widgetStore().getString("__expo_widgets_AgentActivity_props", null)))
+
+  private fun push(updatedAt: Long, vararg lines: String) = mapOf(
+    "device_id" to "device",
+    "user_id" to "user",
+    "updated_at" to updatedAt.toString(),
+    "activity_title" to "2 active agents",
+    "activity_active_count" to "2",
+    "activity_path" to "/threads/env/first",
+    "activity_row_path_1" to "/threads/env/second",
+  ) + lines.mapIndexed { index, line -> "activity_line_$index" to line }
+
+  @Test
+  fun pushRepaintsTheWidget() {
+    val now = System.currentTimeMillis()
+
+    AgentNotifications.receive(
+      context,
+      push(now, "Approval\tShip it\tweb", "Working\tRefactor\tapi", "Done\tDocs\tweb")
+    )
+
+    val props = props()
+    assertEquals(2, props.getInt("activeCount"))
+    val rows = props.getJSONArray("activities")
+    assertEquals(
+      listOf("waiting_for_approval", "running", "completed"),
+      (0 until rows.length()).map { rows.getJSONObject(it).getString("phase") }
+    )
+    assertEquals("Refactor", rows.getJSONObject(1).getString("threadTitle"))
+    assertEquals("/threads/env/second", rows.getJSONObject(1).getString("deepLink"))
+    assertEquals("t3code-dev://", props.getString("appUrl"))
+    assertEquals("/threads/env/first", rows.getJSONObject(0).getString("deepLink"))
+    val stale = props.getJSONObject("stale")
+    assertEquals(now + 2 * 60 * 60 * 1000L, stale.getLong("at"))
+    assertEquals(
+      listOf("Out of date", "Out of date", "Done"),
+      (0 until 3).map { stale.getJSONArray("activities").getJSONObject(it).getString("status") }
+    )
+    val broadcast = shadowOf(context).broadcastIntents.last()
+    assertEquals("expo.modules.t3widgetexpiry.WidgetExpiryReceiver", broadcast.component?.className)
+    assertEquals("AgentActivity", broadcast.getStringExtra("expo.modules.t3widgetexpiry.NAME"))
+  }
+
+  @Test
+  fun anOlderPushDoesNotReplaceNewerRows() {
+    val now = System.currentTimeMillis()
+    AgentNotifications.receive(context, push(now, "Done\tNewer\tweb"))
+    AgentNotifications.receive(context, push(now - 1000, "Working\tOlder\tweb"))
+
+    val props = props()
+    assertEquals(
+      "Newer",
+      props.getJSONArray("activities").getJSONObject(0).getString("threadTitle")
+    )
+    assertFalse(props.has("stale"))
+  }
+}

apps/mobile/src/features/agent-awareness/remoteRegistration.test.ts

@@ -1038,6 +1038,21 @@ describe("makeRelayDeviceRegistrationRequest", () => {
       }).pipe(Effect.provide(relay));
     });
 
+    it.effect("repaints the Android widget without touching Live Activities", () =>
+      Effect.gen(function* () {
+        vi.spyOn(Platform, "OS", "get").mockReturnValue("android");
+        const relay = fakeRelay(() => Effect.succeed({ aggregate }));
+        setAgentAwarenessRelayTokenProvider(() => Promise.resolve("clerk-token"), "user-a");
+        widgetMocks.getInstances.mockClear();
+
+        yield* refreshActiveLiveActivityRemoteRegistration().pipe(Effect.provide(relay));
+
+        expect(publishWidgetMock).toHaveBeenLastCalledWith({ kind: "snapshot", aggregate });
+        expect(widgetMocks.getInstances).not.toHaveBeenCalled();
+        expect(widgetMocks.dismissEnded).not.toHaveBeenCalled();
+      }),
+    );
+
     it.effect("keeps the newest rows when an older overlapping read finishes last", () =>
       Effect.gen(function* () {
         const newer = { ...aggregate, activeCount: 2 };

apps/mobile/src/features/agent-awareness/remoteRegistration.ts

@@ -176,6 +176,11 @@ function canRegisterRemoteLiveActivities(): boolean {
   return Platform.OS === "ios";
 }
 
+// The home-screen widget reads the relay snapshot itself, so it needs no Live Activity.
+function canPublishAgentActivityWidget(): boolean {
+  return Platform.OS === "ios" || Platform.OS === "android";
+}
+
 function canRegisterPushNotifications(): boolean {
   return Platform.OS === "ios" || Platform.OS === "android";
 }
@@ -797,7 +802,7 @@ function ensureAppStateListener(): void {
 }
 
 function publishWidget(source: AgentActivityWidgetSource): void {
-  if (!canRegisterRemoteLiveActivities()) {
+  if (!canPublishAgentActivityWidget()) {
     return;
   }
   publishAgentActivityWidget(source).catch((error: unknown) => {
@@ -1008,7 +1013,7 @@ function scheduleActiveLiveActivityRegistrationRetry(): void {
 export const refreshActiveLiveActivityRemoteRegistration = Effect.fn(
   "remoteRegistration.refreshActiveLiveActivityRemoteRegistration",
 )(function* (): Effect.fn.Return<void, never, ManagedRelay.ManagedRelayClient> {
-  if (!canRegisterRemoteLiveActivities() || !relayTokenProvider) {
+  if (!canPublishAgentActivityWidget() || !relayTokenProvider) {
     return;
   }
 
@@ -1039,6 +1044,12 @@ export const refreshActiveLiveActivityRemoteRegistration = Effect.fn(
     return { snapshot };
   });
 
+  // Android has no Live Activity to reconcile; its widget is the whole refresh.
+  if (!canRegisterRemoteLiveActivities()) {
+    yield* refreshWidget;
+    return;
+  }
+
   dismissEndedLocalLiveActivities();
   let activities = yield* Effect.try({
     try: () => getAgentLiveActivities(),