Skip to content

Push notifications

View as Markdown

When an approval is waiting or a run ends, a user with the app in their pocket should find out. The hub calls your onAttention hook for that; you send the push through your own provider. For Expo Push there is a ready handler.

attention.ts
import type { AttentionEvent, OnAttention } from '@uncage/hub';
export const onAttention: OnAttention = async (e: AttentionEvent, { waitUntil }) => {
// e.kind: 'approval_requested' | 'run_completed' | 'run_failed'
// e.userId, e.sessionId, e.sessionTitle?, e.machineId, e.machineName?, e.runtime?,
// e.approval?: { id, title, category }, e.at (when it happened on the computer)
waitUntil(sendPush(e.userId, `${e.kind}: ${e.sessionTitle ?? e.sessionId}`));
};
declare function sendPush(userId: string, text: string): Promise<void>;

Pass it as createHub({ …, onAttention }). How it behaves:

  • Once per event. It fires after the hub accepted the event, in both sessionStorage modes, once per sessionId:sequence:kind: an agent that resends, or several hub nodes that all see the event, notify once. The dedupe uses the optional store method claimOnce(key, { ttlSec, now }) (implemented by the SQL, Postgres and PGlite stores, claims kept for a day). A custom store without claimOnce gets per-node in-memory dedupe, best effort.
  • Delivery is at most once. If your handler throws or rejects, the error goes to logger.error and the event is not retried.
  • Never blocks ingest. Errors never fail the event. On FaaS platforms the call runs under the request’s waitUntil; ctx.waitUntil hands more work to the same context.
  • Stale events are skipped. An event whose time is older than 10 minutes (an agent backfilling after a reconnect) never notifies. In 'site' mode an approval that the stored snapshot already shows answered is skipped too.
  • Clock note. “Older” compares the event’s time from the computer’s clock with the hub’s clock. Keep both within a few minutes (NTP). A computer whose clock is more than 10 minutes behind never notifies; the hub logs a warning about it, at most once an hour per machine.

A push goes from your hub to Expo, then to Apple or Google, and shows on the lock screen. So by default expoPushNotifier sends no conversation content: only “An approval needs you”, “A run finished” or “A run failed” (with a short “Open the app…” body) and the deep-link data (sessionId, approvalId?, kind). The app loads the details over its own signed-in connection.

includeContent: true is an explicit opt-in to the older, more specific text: the session title and the approval title. Runtimes set the approval title from the tool call, so it often names a shell command or a file path. Each text is one line of at most 180 characters, but it still passes through Expo, Apple or Google, and shows on the lock screen. Turn it on only if your users accept that:

import { expoPushNotifier } from '@uncage/hub';
declare const tokensFor: (userId: string) => Promise<string[]>;
// Default: generic text only ("An approval needs you", "A run finished", "A run failed").
expoPushNotifier({ tokensFor });
// Opt in: the session title and the approval title (often a command or a path) go to the lock screen.
expoPushNotifier({ tokensFor, includeContent: true });
hub.ts
import { expoPushNotifier } from '@uncage/hub';
declare const tokenDb: {
list(userId: string): Promise<string[]>;
remove(token: string): Promise<void>;
};
export const onAttention = expoPushNotifier({
// The user's Expo push tokens, from YOUR database: the hub never stores them.
tokensFor: (userId) => tokenDb.list(userId),
// Expo reported DeviceNotRegistered (app uninstalled): delete the token.
onInvalidToken: (token) => tokenDb.remove(token),
});

It uses only fetch, so it runs anywhere the hub does (it is exported from the Web-standard root). It sends one message per token, in requests of at most 100, with data: { sessionId, approvalId?, kind } so the app can open the right chat.

Option
tokensFor(userId) Required. The user’s Expo push tokens.
accessToken Expo access token when enhanced push security is on.
message(e) { title, body } per event, or null to send nothing. The default is short generic English text without conversation content (defaultPushMessage); localize here.
includeContent true adds the session title and the approval title to the default text (they reach Expo, Apple / Google and the lock screen). Default false. Ignored when you pass message.
onInvalidToken(token) Called for tokens Expo reports as DeviceNotRegistered.
fetch, endpoint Replace fetch or the Expo endpoint (tests).
timeoutMs A request to Expo unanswered after this is aborted and the call rejects (the hub logs it). Default 15000.

It rejects (and the hub logs, with error codes and counts but never tokens) when a request fails or times out, when onInvalidToken throws, or when Expo refused messages for another reason, for example InvalidCredentials. When several sends fail, it rejects with an AggregateError that holds all of them.

The app asks permission, gets its token with expo-notifications (getExpoPushTokenAsync({ projectId })) and sends it to your backend, which stores it per user. examples/connected-demo has POST /api/app/push-token { token } (and DELETE on sign-out), validates the token shape and keeps at most 10 per user (oldest dropped). It also drops tokens not re-registered for 30 days. A token belongs to one user at a time: the latest sign-in on the device wins, so a shared device does not leak notifications to the previous user. Treat tokens as semi-secret. In the demo, set EXPO_PUSH=1 (and optionally EXPO_ACCESS_TOKEN) to switch the hub’s onAttention on.

  • Remote push needs a development build: Expo Go has none on Android since SDK 53.
  • Android: a free Expo account with EAS builds an Android development build; a free Firebase project supplies FCM credentials. Built and unit-tested against a fake Expo endpoint; awaiting device confirmation.
  • iOS: needs a paid Apple Developer account (APNs). Implemented and configurable; not verified on a device.

Unit-test the handler with a fake fetch (the option exists for that) and a hub whose agent emits approval.requested: expect one call, none for the same sequence again, none for events older than ten minutes. The hub’s own tests do exactly this.

See also mount the hub and React Native apps.