# Dispatch Update: Live Activities & Real-Time Task Tracking

## 1. Overview & Motivation

Building on the original Dispatch notification relay, this update introduces real-time task tracking via iOS Live Activities (ActivityKit) and Dynamic Island. While standard notifications inform users after a long-running job finishes or fails, Live Activities track ongoing operations—such as multi-gigabyte ISO downloads, deep learning model training epochs, video transcodes, or database backups—as they occur across remote servers.

## 2. Updated Architecture & Scope

This update extends Dispatch across the CLI, Linux HTTP server, and iOS client:

1. **ActivityKit Integration & Dedicated Activities UI**:
   - The iOS app introduces an **Activities** tab with active and finished task monitors.
   - Tasks display progress bars, current throughput/status (e.g., `Downloading at 18.4 MB/s (68%)`, `Epoch 92/100 • Loss: 0.041`), originating machine tags (`xerxes`, `shodan`), and custom symbols.
   - Live Activities appear on the iOS Lock Screen and Dynamic Island with compact and expanded presentations.

2. **Push-to-Start & Token Lifecycle Management**:
   - The iOS client registers push-to-start tokens via `POST /v1/activity-tokens`.
   - When a machine starts a task (`dispatch --live-activity`), the server broadcasts the start push to registered devices.
   - The server maintains a token queue: progress updates submitted before the device finishes registering its per-activity APNs token are queued and flushed immediately upon token arrival.

3. **Interactive Actions & Remote Cancellation**:
   - Activities can declare remote action endpoints (e.g., `cancelURL`).
   - Users can trigger actions directly from the Live Activity card or Dynamic Island (e.g., "Cancel Task"), sending authenticated callbacks to abort runaway processes on the originating host.

4. **CLI Task Tracking (`dispatch progress`)**:
   - Sending machines can initiate a live task and stream sequential progress updates:
     ```bash
     dispatch start --name "Debian 13 Trixie ISO" --symbol "arrow.down.circle.fill"
     dispatch progress --id <TASK_ID> --percent 68 --status "Downloading at 18.4 MB/s (68%)"
     dispatch end --id <TASK_ID> --status "Completed"
     ```
   - Meaningful exit codes and error propagation allow seamless integration into shell scripts, rTorrent event handlers, systemd units, and CI/CD pipelines.

## 3. HTTP API Additions

### `POST /v1/activity-tokens`
Registers or updates push-to-start and activity-specific APNs tokens for the authenticated device.
```json
{
  "deviceToken": "...",
  "pushToStartToken": "...",
  "activityTokens": {
    "<activityId>": "<activityAPNsToken>"
  }
}
```

### `POST /v1/activities/start`
Starts a new Live Activity across enrolled devices.
```json
{
  "activityId": "TEST-RTORRENT-01",
  "taskName": "Debian 13 Trixie ISO",
  "systemImage": "arrow.down.circle.fill",
  "cancelURL": "https://actions.shodan.trioptimum.co/cancel",
  "initialProgress": 0.0,
  "status": "Starting download..."
}
```

### `POST /v1/activities/{id}/update`
Pushes real-time progress updates. If the activity APNs token has not yet synced from the device, the update is buffered on the server and delivered as soon as the token registers.
```json
{
  "progress": 0.68,
  "status": "Downloading at 18.4 MB/s (68%)"
}
```

### `POST /v1/activities/{id}/end`
Terminates the Live Activity with a final state.
```json
{
  "progress": 1.0,
  "status": "Finished"
}
```

## 4. UI & Interaction Design

- **Activities Tab**: Displays ongoing tasks with progress bar gauges, live metrics, and originating machine indicators (`xerxes`, `shodan`). Supports leading and trailing swipe gestures to dismiss or cancel tasks.
- **Dynamic Island & Lock Screen**: Displays a compact glyph and progress percentage when collapsed, expanding into full control layout with "Cancel" and real-time status text upon long-press.