palmier 0.9.6 → 0.9.8

package/palmier-server/spec.md

@@ -1,533 +0,0 @@
-# Project Palmier: Architecture & Implementation Plan
-
-Palmier is a platform enabling end-users to remotely schedule, manage, and execute autonomous tasks on their host machines via a Progressive Web App (PWA). It acts as a secure, distributed bridge between a user's mobile device/browser and a local host daemon running on their hardware.
-
-## 1. System Architecture & Components
-
-The system relies on a publish-subscribe model utilizing NATS to bypass firewall restrictions and enable real-time, bi-directional communication. All infrastructure runs on a single VPS (DigitalOcean), with automated CI/CD via GitHub Actions.
-
-### 1.1 Platform Support
-
-The host supports **Linux** (systemd), **macOS** (launchd user LaunchAgent), and **Windows** (Task Scheduler for both daemon and task triggers). OS-specific details in this spec use Linux examples unless noted otherwise; the `PlatformService` abstraction handles cross-platform differences. macOS LaunchAgents run only while the user is logged into the GUI session — there is no user-level equivalent of Linux's `loginctl enable-linger`, so scheduled tasks stay dormant after reboot until the user logs in.
-
-### 1.2 Components
-
-* **Host Binary (Node.js):** Runs persistently on the user's host machine as a NATS + HTTP RPC handler. Manages file system operations (task CRUD), OS-level scheduling (systemd), and task generation. Provides a CLI with commands: `palmier init` (provisioning), `palmier pair` (generate pairing code for device pairing), `palmier clients` (manage client tokens), `palmier run <task-id>` (executes a task via the configured agent tool), `palmier uninstall` (stop daemon and remove all scheduled tasks), and `palmier serve` (persistent RPC handler, default command). The `serve` process always starts an HTTP server bound to `0.0.0.0` alongside the NATS transport. The web UI, `/pair`, and `/events` are gated to loopback callers; `/rpc/<method>` (bearer-auth) and `/health` (public) are reachable from the LAN to support the Capacitor app's auto-LAN mode. Exposes a localhost-only MCP server at `/mcp` (streamable HTTP transport) with tools: `notify`, `request-input`, `request-confirmation`, `device-geolocation`, `read-contacts`, `create-contact`, `read-calendar`, `create-calendar-event`, `send-sms-message`, `send-alarm`, `read-battery`, `set-ringer-mode`; and resources: `notifications://device` (device notifications), `sms-messages://device` (SMS messages). Tools and resources are auto-generated as REST endpoints from shared registries (`ToolDefinition[]`, `ResourceDefinition[]`) — zero duplication. Tool REST endpoints are POST with `taskId` query param; resource REST endpoints are GET. `/request-permission` remains a separate endpoint (not part of the MCP registries). MCP resources support subscriptions — clients call `resources/subscribe` and the server holds the POST response open as an SSE stream, pushing `notifications/resources/updated` notifications when the resource data changes. MCP sessions track agent names from `initialize` clientInfo for logging and UI display. `palmier run` is a short-lived process invoked by systemd. Task execution is abstracted through an `AgentTool` interface (`src/agents/agent.ts`) so different AI CLI tools can be supported — each agent implements `getPromptCommandLine()`, `getTaskRunCommandLine()`, and `init()`. The task's `agent` field (e.g., `"claude"`) selects which agent is used.
-
-* **Web Server (Node.js):** Serves the PWA assets (React) via `app.palmier.me` (Cloudflare proxied), manages Web Push VAPID keys, and provides host registration. Uses **PostgreSQL** for persistent storage (host registrations, push subscriptions, FCM tokens). Connects to NATS via TCP to subscribe to `host-event.>` for sending push notifications (confirmations, dismissals, completion/failure). For `POST /api/push/respond` (confirmation responses via push notification action buttons), the Web Server forwards the response to the host via the `task.user_input` NATS RPC. Subscribes to `host.*.push.send` NATS subjects to relay push notification requests from the host CLI. Subscribes to `host.*.fcm.geolocation` to relay device geolocation requests via FCM. Subscribes to `host.*.fcm.contacts`, `host.*.fcm.calendar`, `host.*.fcm.sms`, `host.*.fcm.alarm`, `host.*.fcm.battery`, and `host.*.fcm.ringer` to relay device capability requests via FCM. Provides HTTP endpoints for Android to post responses back (`/api/device/contacts-response`, `/api/device/calendar-response`, `/api/device/sms-response`, `/api/device/alarm-response`, `/api/device/battery-response`, `/api/device/ringer-response`). Co-located with the NATS server on the same machine.
-
-* **Android App (Capacitor):** Native Android wrapper for the PWA. Provides FCM push messaging for receiving data messages in the background, `FusedLocationProviderClient` for GPS access, `NotificationListenerService` for capturing device notifications, `BroadcastReceiver` for incoming SMS, and handlers for contacts, calendar, alarms, battery, and ringer mode. All device tools work while the app is in the background via FCM data messages. When a request arrives via FCM, the appropriate handler executes the action and POSTs the result back to the Web Server. Device capabilities and their permissions:
-  - **Notifications**: `NotificationListenerService` — requires notification listener access (system settings toggle)
-  - **SMS Read**: `SmsBroadcastReceiver` — requires `RECEIVE_SMS` runtime permission
-  - **SMS Send**: `SmsHandler` — requires `SEND_SMS` runtime permission
-  - **Contacts**: `ContactsHandler` — requires `READ_CONTACTS` + `WRITE_CONTACTS` runtime permissions
-  - **Calendar**: `CalendarHandler` — requires `READ_CALENDAR` + `WRITE_CALENDAR` runtime permissions
-  - **Geolocation**: `GeolocationForegroundService` — requires `ACCESS_FINE_LOCATION` runtime permission
-  - **Alarm**: `AlarmHandler` + `AlarmActivity` — triggers a full-screen alarm popup with looping ringtone; requires `USE_FULL_SCREEN_INTENT` (Android 14+ requires user grant in settings)
-  - **Battery**: `BatteryHandler` — no permission required
-  - **Ringer mode**: `RingerHandler` — requires Do Not Disturb access (system settings toggle)
-
-  The notification listener excludes Palmier's own task notifications (channel `palmier_tasks`) and the default SMS app's notifications (to avoid duplicates with the SMS resource). Each capability can be toggled on/off from the drawer when the device is the host's **linked device** (the one device the host talks to for device capabilities); toggles are backed by SharedPreferences flags that handlers check before executing. See the `palmier-android` repo.
-
-* **PWA (React):** The user-facing frontend, primarily targeting mobile devices. Connects to the NATS server via **WebSockets** at `nats.palmier.me` (DNS only, not Cloudflare proxied, to avoid interference with persistent connections). No user accounts — paired hosts are stored in localStorage.
-
-* **NATS Server:** The central message broker. Runs in Docker on the same machine as the Web Server.
-
-### 1.3 Security & Authentication
-
-* **NATS authentication:** The NATS server uses **token-based authentication** with a single shared token. Subject scoping (e.g., `host.<host_id>.>`) is enforced at the application layer.
-
-* **Client tokens:** Each PWA device paired with a host receives a unique client token, generated and stored on the host. Client tokens are included in every RPC request and validated by the host before processing. Tokens do not expire and can be revoked via the `palmier clients` CLI.
-
-* **Pairing:** Devices pair with hosts using a 6-character alphanumeric pairing code. The code serves as a routing key — the PWA sends the code to NATS subject `pair.<CODE>` or to the host's HTTP `POST /pair` endpoint. The host validates the code and returns a client token. Codes expire after 5 minutes or first successful use.
-
-* **Future migration:** Token-based auth can be migrated to full **JWT/NKey Authentication** for finer-grained access control and dynamic credential issuance without restarting the NATS server.
-
-### 1.4 Repository Structure
-
-The project is split across two repositories:
-
-* **`palmier`**: The host binary. A standalone Node.js CLI that runs on the user's machine.
-* **`palmier-server`**: Contains both the Web Server (`server/`) and the PWA (`pwa/`, built with Vite + React). Uses **pnpm** for package management with a pnpm workspace.
-* **`palmier-android`**: Capacitor-based Android wrapper that loads the PWA from `app.palmier.me` in a WebView and exposes native device capabilities via a custom plugin.
-
-### 1.5 Android Implementation Details
-
-The Android app is a thin native shell over the remotely-hosted PWA. The design decisions below are non-obvious enough that changing them silently would break assumptions the rest of the system makes.
-
-**Remote-first WebView.** `capacitor.config.json` sets `server.url` to `https://app.palmier.me`; the WebView fetches the PWA from the cloud on every launch. This means PWA updates ship instantly with no APK rebuild, and release builds run `npx cap sync` only (no PWA build step). Consequences:
-
-- **Server mode only.** LAN and Local modes are browser-only. The WebView blocks cleartext `http://<host-ip>:<port>` requests as mixed content, so LAN users must open the PWA from Chrome/Safari directly.
-- **Offline fallback.** When `app.palmier.me` is unreachable, the WebView loads `www/offline.html` (configured via `server.errorPath`), which auto-reloads when connectivity returns.
-- **PWA ships ahead of the APK.** The PWA may reference capabilities or native methods that the installed APK doesn't implement yet. `Device.getCapabilityStatus()` only returns capabilities the APK knows about, so the PWA naturally hides toggles it can't fulfill. Calls to `setCapabilityEnabled` for unknown capabilities resolve with `{ enabled: false, reason: "unsupported" }` rather than throwing.
-
-**Unified `Device` Capacitor plugin.** A single plugin (`DevicePlugin.kt`) exposes the entire native surface — FCM token, capability gating (with internal permission orchestration), installed-app enumeration, deep-link events. Methods: `getFcmToken`, `getCapabilityStatus`, `setCapabilityEnabled({capability, enabled})`, `getInstalledApps`, `addListener("deepLink", ...)`. Capabilities: `sms-read`, `sms-send`, `send-email`, `notifications`, `contacts`, `calendar`, `location`, `dnd`, `alarm`.
-
-**Capability kill-switch (`CapabilityState`).** Local whitelist persisted as a JSON-array string under `enabledCapabilities` in `CapacitorStorage` SharedPreferences. Native receivers (`SmsBroadcastReceiver`, `DeviceNotificationListenerService`) and all FCM handlers consult `CapabilityState.isEnabled` before acting — a second line of defense beyond the server-side linked-device check. The plugin owns reads and writes through `setCapabilityEnabled` (writes only after permission grant) and prunes the set on every app resume so any permission revoked in system Settings auto-flips the corresponding toggle off. Battery is the one capability without a kill-switch — it's always allowed.
-
-**FCM token flow.** The PWA reads the current token on demand via `Device.getFcmToken()`; no cached copy in SharedPreferences. `PalmierFirebaseMessagingService.onNewToken` still re-registers with the relay server itself (using the stored `hostId`) because background token refreshes can fire while the PWA isn't running.
-
-**Deep links.** FCM notification taps pass a host-scoped relative path (e.g. `/hosts/:hostId/runs/:taskId/:runId`) via an `Intent` extra named `deepLink`. Including the host in the path ensures the PWA switches to the originating host even if the user was viewing a different one when the notification arrived. `MainActivity.handleDeepLink` forwards the path to `DevicePlugin.emitDeepLink`, which emits a `deepLink` event the PWA's router handles client-side. If the plugin isn't ready yet (intent arrives before `onPostCreate`), `MainActivity` buffers the path and flushes in `onPostCreate`. No external `intent-filter` is registered — Android 11+ `<queries>` entries are declared so `hasEmailClient` and installed-app enumeration work without `QUERY_ALL_PACKAGES`.
-
-**Notification listener filtering and debounce.** `DeviceNotificationListenerService` drops notifications from (a) Palmier's own `palmier_tasks` channel to avoid feedback loops and (b) the default SMS app (SMS is captured separately via `SmsBroadcastReceiver`, which arrives before the SMS app's notification). Empty-title+body notifications are skipped. A 2-second debounce per `packageName:title` key dedupes rapid updates; the debounce map is LRU-capped at 200 entries.
-
-**SMS capture.** Multi-part SMS arrives as multiple PDUs in a single `SMS_RECEIVED` broadcast. `SmsBroadcastReceiver` groups parts by `displayOriginatingAddress` and concatenates bodies before relaying, otherwise long messages would arrive as fragments.
-
-**Alarm capability.** `AlarmHandler` posts a `CATEGORY_ALARM` notification on the DND-bypassing `palmier_alarms` channel with a full-screen intent targeting `AlarmActivity`. `AlarmActivity` extends `AppCompatActivity`, shows over the lock screen (`setShowWhenLocked`/`setTurnScreenOn` on O_MR1+, legacy window flags below), and plays the default alarm ringtone on the alarm audio stream via `RingtoneManager`. Requires `USE_FULL_SCREEN_INTENT`; Android 14+ requires the user to grant it in per-app settings.
-
-**Email capability.** FCM `send-email` messages post a "Pending email" notification whose tap launches `EmailActivity` — a translucent `Activity` (not `AppCompatActivity`, so `Theme.Translucent` applies) that builds a `mailto:` URI and starts the email app with `ACTION_SENDTO`. The activity auto-finishes on result, returning the user to the previous screen. `setCapabilityEnabled("send-email", true)` checks for an installed `mailto:` resolver before granting; if none exists it returns `{ enabled: false, reason: "no-email-client" }` so the PWA can prompt the user to install one.
-
-**Location capability.** `GeolocationForegroundService` briefly starts as a foreground service (`FOREGROUND_SERVICE_TYPE_LOCATION` on U+) and uses `FusedLocationProviderClient.getCurrentLocation(PRIORITY_HIGH_ACCURACY)` for a single fix before stopping itself. Requires both `ACCESS_FINE_LOCATION` and `ACCESS_BACKGROUND_LOCATION` on Q+; the plugin requests them sequentially.
-
-**Releases.** GitHub Actions builds a signed APK and creates a release when a `v*` tag is pushed. The workflow runs `npm ci && npx cap sync` — no PWA build step since the WebView loads remotely.
-
-## 2. Host Provisioning & Device Pairing
-
-### 2.1 Host Provisioning
-
-Each host machine is provisioned via `palmier init`, an interactive wizard that registers the host with the Palmier server.
-
-`palmier init` is an interactive wizard that:
-
-1. Detects installed agent CLIs.
-2. Asks which HTTP port to use (default 7256).
-3. Detects the OS default network interface (used as the source for the host's LAN URL in `host.info` responses).
-4. Shows a summary of task storage directory, local access URL, detected agents, and any existing tasks to recover. Asks for confirmation before proceeding.
-5. Registers with the Palmier server via `POST <url>/api/hosts/register` — server returns `{ hostId, natsUrl, natsWsUrl, natsJwt, natsNkeySeed }`.
-6. Saves config to `~/.config/palmier/host.json` (includes `httpPort`, `defaultInterface`, NATS credentials).
-7. Installs a systemd user service (Linux), user LaunchAgent (macOS), or Task Scheduler entry (Windows) and auto-enters pair mode.
-
-The daemon automatically recovers existing tasks by reinstalling their system timers on startup.
-
-`defaultInterface` is captured once at `init` time. On each `host.info` RPC, the host re-reads the current IPv4 of that interface (`getInterfaceIpv4(config.defaultInterface)`) so DHCP-assigned IP changes on the same adapter propagate to clients without a re-pair. Users should re-run `palmier init` if they physically switch adapters (e.g., Ethernet ↔ WiFi, adding a new tethered interface).
-
-The `serve` daemon always starts an HTTP server bound to `0.0.0.0:<port>`. Two access modes are available:
-
-**Local mode** (always available, loopback only):
-- The PWA is accessible at `http://localhost:<port>` without pairing or internet. The PWA is bundled with the host package. The serve daemon injects `window.__PALMIER_SERVE__=true` into the HTML; the PWA detects this and auto-connects. Web UI assets, `/pair`, and `/events` are gated to loopback callers (`127.0.0.1`/`::1`); non-loopback requests get 404.
-
-**Server mode** (NATS cloud relay):
-- Communication is relayed through the Palmier cloud server via NATS. PWA is accessed at `https://app.palmier.me`. Enables push notifications and remote access.
-
-**Auto-LAN** (transparent perf optimization on top of Server mode):
-- The host's HTTP server exposes `/rpc/<method>` (bearer-auth) and `/health` (public) on all interfaces, so other devices on the LAN can reach them. The native Capacitor app probes `${lanUrl}/health` (URL captured at pair time) and routes RPC over direct HTTP when reachable, falling back to NATS otherwise. Events stay on NATS regardless. Browser PWAs cannot use this path due to Private Network Access / mixed-content rules.
-
-### 2.2 Device Pairing
-
-Local access (`http://localhost:<port>`) requires no pairing — the PWA auto-connects with a placeholder host ID.
-
-For server-mode pairing, `palmier pair` generates a 6-character pairing code from the charset `ABCDEFGHJKMNPQRSTUVWXYZ23456789` (excludes ambiguous O/0/I/1/L) and listens on both NATS (relay) and HTTP (loopback only) in parallel:
-
-**Server pairing (NATS, primary path):**
-1. Host subscribes to `pair.<CODE>` on NATS with a 5-minute timeout.
-2. User enters the code in the PWA at `https://app.palmier.me`.
-3. Host validates the code, generates a client token via `addClient()`, and responds with `{ hostId, clientToken, directUrl, hostName }`. `directUrl` is the host's LAN URL (`http://<lan-ip>:<port>`) — stored on the device as `lanUrl` and probed by the native app for auto-LAN.
-
-**Local pairing (HTTP, loopback only):**
-1. Host registers the code with the serve daemon via `POST /pair-register` (loopback-gated).
-2. User opens `http://localhost:<port>` on the host machine and enters the code.
-3. PWA posts `POST /pair` (loopback-gated) with `{ code }` and gets the same payload as above. The PWA treats `directUrl = window.location.origin` (loopback), and stores nothing as `lanUrl`.
-
-The PWA stores the paired host in localStorage and navigates to the dashboard. Codes expire after 5 minutes or first successful use.
-
-### 2.3 Client Management
-
-Client tokens are stored on the host in `~/.config/palmier/clients.json`. Each token is a 32-byte hex string.
-
-* `palmier clients list` — shows tokens (truncated), labels, creation dates
-* `palmier clients revoke <token>` — removes a client token
-* `palmier clients revoke-all` — clears all clients
-
-If no clients exist, the host skips client validation (backward compatibility for unpaired hosts).
-
-### 2.3.1 Linked Device
-
-Each host tracks a single **linked device** — the one paired device responsible for answering device capability requests (SMS, contacts, calendar, location, alarm, ringer, email, battery). The host stores only `{ clientToken, fcmToken }` in `~/.config/palmier/linked-device.json`; it has no knowledge of which capabilities are actually enabled on the device. That set lives in Android SharedPreferences on the linked device itself and is consulted by the FCM handlers as a local kill-switch.
-
-- **Opt-in at pair time.** The PWA shows a "Link the host to this device" checkbox during pairing (native only, default on). If checked, the pair flow continues to a setup step that calls `device.link` with the FCM token. On the very first host pair (when the device has no other paired hosts), that step also shows a one-time "Device Capabilities" screen with all toggles default OFF; the user opts into each one, and Finish writes the set to SharedPreferences. On subsequent host pairs the capability screen is skipped — the device-wide enabled set is host-agnostic and set once.
-- **Reassignment.** Any paired device can take over as the linked device from the drawer's "Link the host to this device" button. This displaces the previous linked device (its drawer toggles go dark).
-- **Loss.** If the linked device is unpaired (via `clients.revoke_self` or CLI `palmier clients revoke`), `linked-device.json` is cleared and capability tools return "No linked device configured" until the user picks a new one.
-- **Routing.** MCP capability tools look up the linked device once per invocation and publish FCM to its token (via `host.<host_id>.fcm.<capability>` relayed by the server). Non-linked devices aren't woken and don't receive capability FCMs.
-
-Battery reads don't have a Settings toggle — capability is always on — but still route to the linked device (which is where the Android handler runs).
-
-### 2.4 NATS Communication
-
-All communication is scoped per host. **Request-reply** is used for RPC-style calls (task CRUD, status queries) — the PWA publishes a request and receives a response on an auto-generated inbox, eliminating the need for separate response subjects.
-
-The **RPC method is derived from the NATS subject**, not the message body. The host subscribes to `host.<host_id>.rpc.>` and extracts the method by splitting the subject at `rpc.` (e.g., `...rpc.task.create` → `task.create`). The message body contains the request parameters as JSON, including the `clientToken` field for authentication.
-
-**Auto-LAN (native Capacitor app only).** When the device probes the host's LAN URL successfully, it routes the same RPC methods over direct HTTP (`POST <lanUrl>/rpc/<method>` with `Authorization: Bearer <clientToken>`) instead of through NATS. Identical request/response payloads, lower latency. Browser PWA always uses NATS. Events (`host-event.*`) always flow through NATS regardless of mode.
-
-**Host RPC endpoints** (request-reply, subject: `host.<host_id>.rpc.<method>`):
-
-| Method | Params | Description |
-|---|---|---|
-| `host.info` | *(none)* | Bootstrap metadata fetched once per connection. Returns `{ agents, version, host_platform, linked_client_token, pending_prompts, lan_url }`. `linked_client_token` is the clientToken of the device currently linked to the host (or `null`); device capability requests route to that device's FCM token. `pending_prompts` is an array of prompts already waiting when the PWA reconnects (each `{ key, type, params?, meta? }`), so modals can render without replaying events. |
-| `device.link` | `fcmToken` | Mark the calling client as the host's linked device. Stores `{ clientToken, fcmToken }` in `~/.config/palmier/linked-device.json` and replaces any existing linked device. Device capability tools (`device-geolocation`, `read-contacts`, `send-sms-message`, etc.) route FCM to this device. |
-| `device.unlink` | *(none)* | Clear the linked device if the caller is currently linked. No-op otherwise. |
-| `clients.revoke_self` | *(none)* | Revoke the calling client's token. Also clears the linked device when the caller was the linked one. Called by the PWA when the user unpairs the currently-active host. |
-| `task.list` | *(none)* | List all tasks with frontmatter, created_at, and current status. |
-| `task.get` | `id` | Get a single task with frontmatter and current status. |
-| `task.create` | `user_prompt`, `agent`, `schedule_type?`, `schedule_values?`, `schedule_enabled?`, `requires_confirmation?`, `yolo_mode?`, `foreground_mode?`, `command?` | Create a new task with auto-generated name (30s timeout for prompts > 50 chars), install system timers if a schedule is present. |
-| `task.update` | `id`, `user_prompt?`, `agent?`, `schedule_type?`, `schedule_values?`, `schedule_enabled?`, `requires_confirmation?`, `yolo_mode?`, `foreground_mode?`, `command?` | Update an existing task. Regenerates name if `user_prompt` or `agent` changed. Reinstall timers as needed. Pass `null` for `schedule_type` or `schedule_values` to clear them. |
-| `task.delete` | `id` | Delete a task and its systemd timers |
-| `task.run` | `id` | Start a task via system scheduler (`systemctl --user start` / `schtasks /run`) |
-| `task.abort` | `id` | Stop a running task via system scheduler (`systemctl --user stop` / `schtasks /end`) |
-| `task.user_input` | `id`, `value` | Respond to a pending request (confirmation, permission, or input). Resolves an in-memory pending request held by the serve daemon's HTTP endpoint. |
-| `task.status` | `id` | Read current status from `status.json`, enriched with pending request state from in-memory registry |
-| `task.result` | `id`, `run_id` | Read a run's TASKRUN.md conversational messages and metadata. Returns `{ messages: ConversationMessage[], task_name, agent, running_state, start_time, end_time }`. |
-| `task.followup` | `id`, `run_id`, `message` | Send a follow-up message to an existing run. Appends user message + started status, invokes agent inline, appends result. |
-| `task.stop_followup` | `id`, `run_id` | Stop an active follow-up. Kills the agent child process and appends a stopped status. |
-| `task.reports` | `id`, `run_id`, `report_files` | Read one or more report files from the run directory. Supports `.md`, `.txt`, and image files (`.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`). Text files return `{ file, content }`, images return `{ file, data_url }` (base64). |
-| `task.logs` | `id` | Read recent journalctl logs for the task's systemd service |
-| `taskrun.list` | `offset?`, `limit?`, `task_id?` | Read paginated run history from `history.jsonl` (default limit: 10). Optional `task_id` filter. Returns `{ entries, total }` where each entry is enriched with TASKRUN.md metadata. |
-| `taskrun.delete` | `task_id`, `run_id` | Delete a run and its directory. |
-
-All RPC requests include a `clientToken` field in the JSON payload. The host validates the token before processing the request.
-
-**Host CLI → Web Server** (request-reply):
-
-| Subject | Payload | Description |
-|---|---|---|
-| `host.<host_id>.push.send` | `{ hostId, title, body }` | Send push notification to all paired devices (15s timeout) |
-
-**Pub/Sub** (fire-and-forget, published by `palmier run`):
-
-| Subject | Payload | Subscriber | Description |
-|---|---|---|---|
-| `host-event.<host_id>.<task_id>` | `{ event_type, ... }` | PWA, Web Server | Unified event subject. `event_type` is one of `"running-state"`, `"confirm-request"`, `"confirm-resolved"`, `"permission-request"`, `"permission-resolved"`, or `"report-generated"`. Payloads: running-state includes `{ running_state, name? }`, confirm-request includes `{ host_id }`, confirm-resolved includes `{ host_id, status }`, report-generated includes `{ name?, run_id, report_files }`. Same payload shape is used for both NATS and HTTP SSE. |
-| `host.<host_id>.device.notifications` | `{ id, packageName, appName, title, text, timestamp }` | Host | Device notification from Android. Published by Web Server when it receives `POST /api/device/notifications` from the Android app. Host stores in bounded in-memory collection and exposes via MCP resource. |
-| `host.<host_id>.device.sms` | `{ id, sender, body, timestamp }` | Host | Incoming SMS from Android. Published by Web Server when it receives `POST /api/device/sms` from the Android app. Host stores in bounded in-memory collection and exposes via MCP resource. |
-
-### 2.5 Push Subscription Management
-
-Push notification subscriptions are stored in PostgreSQL, keyed by host ID and device endpoint. A host may have multiple paired devices (e.g., phone + tablet). All push notifications for a host are delivered to **all registered devices** for that host.
-
-## 3. Data Model: The Task Directory
-
-All tasks are stored locally on the Host machine under a `tasks/` directory relative to the project root (the directory where `palmier init` was run).
-
-### Structure
-
-```text
-history.jsonl              # Project-level run history index (append-only JSONL: { task_id, run_id })
-tasks/
-└── <task-id>/
-    ├── TASK.md                    # Current task definition (YAML frontmatter)
-    ├── status.json                # Latest execution status (running_state, time_stamp, pid)
-    └── <timestamp>/              # Run directory (one per run, isolated per agent session)
-        ├── TASKRUN.md            # Conversational thread (frontmatter + message entries)
-        └── ...                   # Agent session files, reports, artifacts
-```
-
-### `TASKRUN.md` Format
-
-TASKRUN files use a conversational format with YAML frontmatter and HTML comment delimiters separating messages:
-
-```markdown
----
-task_name: My Task
-agent: claude
----
-
-<!-- palmier:message role="status" time="1712282400000" type="started" -->
-
-<!-- palmier:message role="user" time="1712282400100" -->
-
-Run the audit and generate a report.
-
-<!-- palmier:message role="assistant" time="1712282430000" attachments="report.md" -->
-
-Audit complete. Generated report.
-
-<!-- palmier:message role="status" time="1712282450000" type="finished" -->
-```
-
-**Frontmatter** contains `task_name` and `agent` (snapshotted at run creation time). Timing and state are derived from status messages:
-- **running_state**: derived from the last status message. `"started"` with no prior terminal = task running. `"started"` with prior terminal = follow-up running (`"followup"`). Terminal types: `"finished"`, `"failed"`, `"aborted"`, `"stopped"`.
-- **start_time**: `time` of the first `type="started"` status message
-- **end_time**: `time` of the last terminal status message
-
-**Message delimiter:** `<!-- palmier:message role="{role}" time="{ms}" [type="{type}"] [attachments="{files}"] -->`
-
-- **role**: `"assistant"` (agent output), `"user"` (user input/permissions/confirmations), or `"status"` (lifecycle events)
-- **time**: Unix timestamp in milliseconds
-- **type** (optional): `"input"`, `"permission"`, `"confirmation"`, `"started"`, `"finished"`, `"failed"`, `"aborted"`, `"stopped"`
-- **attachments** (optional): comma-separated report filenames
-
-Messages are appended incrementally during execution.
-
-### `TASK.md` Schema
-
-```yaml
----
-id: "uuid-v4"
-user_prompt: "Run a system audit and summarize large files..."
-agent: "claude"
-schedule_type: "crons"
-schedule_values:
-  - "0 9 * * 1"
-schedule_enabled: true
-requires_confirmation: true
----
-```
-
-`schedule_type` is one of:
-
-* `"crons"` — `schedule_values` holds cron expressions.
-* `"specific_times"` — `schedule_values` holds local datetime strings (e.g. `"2026-04-20T09:00"`).
-* `"on_new_notification"` — fires once per new Android notification relayed over NATS. Optional `schedule_values` holds a single-entry packageName filter; empty/unset matches any app.
-* `"on_new_sms"` — fires once per new SMS relayed over NATS. Optional `schedule_values` holds a single-entry sender filter (phone number or alphanumeric shortcode); compared after normalizing away spaces, dashes, parens, plus sign, and case. Empty/unset matches any sender.
-
-For `crons` / `specific_times` the schedule is installed as an OS timer (systemd / Task Scheduler). For the `on_new_*` types the `palmier run` process subscribes directly to the corresponding NATS subject (`host.<hostId>.device.notifications` or `...device.sms`), drains events through a bounded FIFO queue, and invokes the agent once per event with the event payload spliced into the user prompt (mirroring command-triggered mode). These event-driven tasks are not started on save — they launch via `task.run` (the PWA auto-runs them on create, matching command-triggered UX).
-
-The `name` field is auto-generated by spawning the configured agent CLI with a short prompt (for prompts > 50 chars). For shorter prompts, the `user_prompt` is used directly as the name.
-
-The `agent` field stores the agent name (e.g., `"claude"`, `"codex"`). The corresponding `AgentTool` implementation is responsible for constructing the full command and arguments at execution time.
-
-The optional `command` field stores a shell command for command-triggered tasks. When set, the task runs in command-triggered mode: the command is spawned with `shell: true`, and each line of its stdout triggers a separate agent invocation with `user_prompt + "\n\nProcess this input:\n" + line`.
-
-#### Schedule Lifecycle
-
-* **`schedule_enabled`:** Controls whether systemd timers are installed for the task's schedule. When `false`, all timers are removed; when toggled back to `true`, timers are reinstalled. Defaults to `true`. The task can still be run manually via "Run Now" regardless of this setting. The "Enable Schedule" checkbox only appears in the UI when the task has a schedule.
-* **`crons` schedules:** Persist indefinitely. The systemd timer remains active until the task is deleted or the schedule is disabled.
-* **`specific_times` schedules:** After a value fires, it is removed from `schedule_values` and its corresponding systemd timer/service files are cleaned up. Once all values have fired the schedule is cleared, and the task remains in the `tasks/` directory as a manual task (can still be executed on-demand via the PWA or CLI, but will not fire automatically again).
-* **`on_new_notification` / `on_new_sms` schedules:** No OS timers are installed. Instead, the serve daemon subscribes to the matching NATS subject (`host.<host_id>.device.notifications` / `.sms`), maintains a per-task in-memory FIFO queue (max 100 entries; overflow drops the oldest), and spawns `palmier run <id>` via the OS scheduler when the task transitions from idle to active (tracked by an `active_run` flag flipped atomically on the empty-pop). The run process drains the queue by calling `POST /task-event/pop?taskId=<id>` on the localhost daemon: each non-empty response is spliced into the user prompt (`user_prompt + "\n\nProcess this new notification:\n" + <raw JSON payload>` or `...new SMS...`) and invoked through the standard agent retry loop. When the endpoint returns `{ empty: true }` the active flag is cleared and the run exits; the next incoming NATS event will start a fresh run. These tasks are never auto-run on save — they launch only in response to NATS events. Requires server mode (NATS).
-
-### Task Events
-
-Task lifecycle status is persisted to a `status.json` file in the task directory on the host. The file contains `{ running_state, time_stamp, pid }` and is used primarily for crash detection. Interactive request flows (confirmation, permission, input) are handled via held HTTP connections on the serve daemon's in-memory pending request registry. The `running_state` is one of:
-
-* **`started`** — task execution has begun (set immediately, before confirmation if applicable).
-* **`finished`** — task completed successfully.
-* **`aborted`** — task was aborted by the user (confirmation denied or manual abort via RPC).
-* **`failed`** — task execution failed (the command exited with a non-zero code).
-
-`palmier run` writes `status.json` and publishes a notification on `host-event.<host_id>.<task_id>` (payload: `{ event_type: "running-state", running_state }`) via NATS and HTTP SSE. The `time_stamp` field is UTC time in milliseconds since epoch (`Date.now()`).
-
-The `task.list` RPC includes each task's current status (read from `status.json`). The `task.status` RPC returns the status for a single task.
-
-The PWA receives initial statuses from `task.list` on load. It subscribes to `host-event.<hostId>.>` for live updates; on each notification it parses the `event_type` field and calls the host's `task.status` RPC to fetch the current status. Task cards display the `user_prompt` as the title (truncated to 2 lines) and a status indicator: a marching dots animation when running (`started`), a red dot for errors (`aborted` or `failed`), a gray dot when the schedule is disabled or absent, and a green dot when idle (no entry or `finished`). When the last run was successful (`finished`), a "View Result" button loads the task's result file in a popup dialog. The `specific_times` date/time picker only allows selecting future dates and times.
-
-The Web Server subscribes to `host-event.>` and sends push notifications based on `event_type`: confirmation pushes for `confirm-request`, dismiss pushes for `confirm-resolved`, permission pushes for `permission-request`, dismiss pushes for `permission-resolved`, and report-ready/failure pushes for `report-generated` events.
-
-### Logs
-
-Task execution logs are managed by systemd's journal. Each task's systemd service unit is tagged with the task ID, allowing logs to be queried with:
-
-```bash
-journalctl --user -u palmier-task-<task-id>.service
-```
-
-The host exposes a `task.logs` RPC handler that runs this query and returns recent log lines to the PWA.
-
-## 4. UI & Task Management Flow
-
-The PWA (React) provides a responsive CRUD interface.
-
-The PWA connects to **one host at a time**. A host menu (hamburger drawer) lets the user switch between paired hosts. All hosts are selectable regardless of online status — the PWA does not probe or display host connectivity in the picker.
-
-### 4.1 Initialization
-
-1. PWA loads. If no hosts are paired, it shows an empty state with a "Pair Host" button.
-
-2. If hosts are paired, PWA fetches host-scoped NATS credentials from `GET /api/nats-credentials/<hostId>` (returns `{ natsWsUrl, natsJwt, natsNkeySeed }`) and connects to NATS via WebSocket using JWT auth. The credentials are scoped to the paired host's subjects only.
-
-3. PWA sends a `host.info` request using NATS request-reply, including the `clientToken` in the payload. The response carries bootstrap metadata (`agents`, `host_platform`, `version`, `linked_client_token`) and `pending_prompts` — any prompts already open on the host when the PWA connected. The Dashboard consumes this once per connection; both tabs read from it.
-
-4. PWA lands on the Sessions tab and fetches run history via `taskrun.list`. `task.list` is not called at startup — it fires lazily the first time the user opens the Tasks tab. If either RPC fails with NATS 503 ("no responders"), the PWA shows an empty state — this is not treated as an error.
-
-5. PWA registers the service worker and subscribes the browser for Web Push notifications (via `pushManager.subscribe` with the server's VAPID public key). The push subscription is sent to `POST /api/push/subscribe` with the `hostId` so the server can relay notifications to the device.
-
-6. Initial pending-prompt discovery uses `host.info.pending_prompts`: each entry is `{ key, type, params?, meta? }` where `meta` carries the display context (`session_id`, `session_name`, `description`, `input_questions`) needed to render the modal cold. The PWA seeds its modal state maps from this array. After connection, live arrivals come through the NATS event subscription. The PWA responds by calling the `task.user_input` RPC on the host, which resolves the in-memory pending request held by the serve daemon. The `run` process (blocked on an HTTP call to the serve daemon) receives the response and proceeds or exits accordingly.
-
-### 4.2 UI Layout: Sessions & Tasks Tabs
-
-All authenticated views are scoped under `/hosts/:hostId/` so the URL is the source of truth for "which host am I looking at":
-
-- `/hosts/:hostId` — Sessions tab (default)
-- `/hosts/:hostId/tasks` — Tasks tab
-- `/hosts/:hostId/runs/:taskId` — latest run for a task
-- `/hosts/:hostId/runs/:taskId/:runId` — specific run
-- `/hosts/:hostId/pair/setup` — capability setup right after pairing (native only)
-- `/pair` — enter a pairing code
-- `/` — redirects to `/hosts/<firstPairedHostId>`, or to `/pair` if no hosts are paired. No "last visited" state is persisted; the URL is the source of truth for the active host.
-
-Unknown or stale `:hostId` values redirect back to `/`. This lets notification deep links (`/hosts/:hostId/runs/...`) switch the active host automatically instead of opening a run against whatever host happens to be selected.
-
-The PWA has two tabs: **Sessions** (default) and **Tasks** (secondary). Sessions is the primary workflow — it lists all run history across tasks (a "session" is a single run) and includes a session composer at the top of the list.
-
-* **Session composer:** An inline textarea with an agent picker, a yolo-mode toggle, and a round play button. Entering text and clicking play dispatches `task.run_oneoff`, starting an immediate unsaved session. The composer never opens a dialog; typing is direct. When the textarea has content, navigating away (tab switch, host switch, browser reload, clicking a session row) triggers a confirmation dialog so the draft isn't lost silently.
-* **Tasks tab:** Lists saved tasks (scheduled or reusable). A floating round `+` button in the bottom-right of the screen opens the task form, which is used only to create/edit saved or scheduled tasks — it has no Run button (run one-offs via the session composer instead). The form's primary action is "Save" (no schedule) or "Schedule" (when a schedule is configured).
-
-Bootstrap data (agents, host version, host platform, linked device) is fetched once per connection at the Dashboard level via `host.info` — independent of which tab is active. `task.list` is called lazily on the Tasks tab mount; `taskrun.list` is called lazily on the Sessions tab mount. Neither list RPC carries bootstrap metadata.
-
-Dashboard owns the always-on NATS event subscription and renders pending `confirm-request` / `permission-request` / `input-request` modals via React portal, so prompts surface regardless of which tab is active. Initial pending prompts (those already open when the PWA connects) are seeded from `host.info`'s `pending_prompts` field — each entry carries the display context (`session_name`, `description`, `input_questions`) needed to render the modal cold, since the task list is no longer available at bootstrap. `session_name` is a unified label: agent name for confirm/input, task name for permission.
-
-### 4.3 Task Creation & Update
-
-1. User taps the floating `+` button on the Tasks tab, which opens the task form.
-
-2. User enters a prompt, selects an agent, configures the schedule (UI translates human-readable times to cron expressions or ISO datetime strings) and confirmation settings, and clicks "Save" (no schedule) or "Schedule" (with a schedule).
-
-3. PWA sends `task.create` (or `task.update`) via NATS request-reply to Host (45s timeout). For prompts > 50 chars, the host generates a concise task name by running the configured agent CLI in non-interactive mode (e.g., `claude -p "Generate a concise 3-6 word name for this task..."`). For shorter prompts, the prompt is used directly as the name.
-
-4. For updates: if the user changes the `user_prompt` or `agent`, the name is regenerated. If neither changed, the existing name is preserved. Existing tasks with granted permissions show a clickable "Granted Permissions" link to view them.
-
-5. PWA sends `task.create` (or `task.update` with `id`) with the task fields as the message body. The `id` field is **not sent on create** — the host generates a UUID. `schedule_type` and `schedule_values` are omitted when the task has no schedule. For `on_new_notification` / `on_new_sms` types, `schedule_values` is sent only when a filter is configured (single packageName for notifications, single sender for SMS).
-
-6. Host creates/updates the `tasks/<task-id>/TASK.md` file and returns the **full flat task object** (all frontmatter fields at the top level). The PWA uses this response directly to update the UI.
-
-7. **OS Integration:** Host translates the schedule into a systemd user timer (`~/.config/systemd/user/palmier-task-<task-id>.timer` and `.service`). The `.service` runs `palmier run <task-id>`, which executes the task as a background process. Host runs `systemctl --user daemon-reload` and enables the timer.
-
-### 4.4 On-Demand Execution
-
-Any task that is not currently running can be executed immediately:
-
-* **PWA (saved task):** A "Run Now" button is shown on each task card when the task is not already running. Clicking it sends a `task.run` request via NATS request-reply to the Host, which starts execution via the system scheduler (`systemctl --user start` on Linux, `schtasks /run` on Windows).
-* **PWA (one-off session):** The session composer on the Sessions tab sends `task.run_oneoff` with `{ user_prompt, agent, yolo_mode }`. The host creates an ephemeral task, runs it, and returns `{ task_id, run_id }`; the PWA navigates to the run detail view.
-* **CLI:** `palmier run <task-id>` executes the task directly (outside the system scheduler).
-
-Both paths follow the same execution loop described in §5.2 (including confirmation checks if configured). The system scheduler prevents concurrent runs of the same task — if the service/task is already active, the start command is a no-op.
-
-### 4.5 Task Deletion
-
-1. PWA sends `task.delete` via NATS request-reply.
-
-2. Host runs `systemctl --user stop palmier-task-<task-id>.timer`, disables it, deletes the systemd files, removes the `tasks/<task-id>` directory, and runs `daemon-reload`.
-
-## 5. Task Execution & Host Interaction
-
-### 5.1 Execution Architecture
-
-Task execution is handled by `palmier run <task-id>`, a short-lived process that resolves the task's `agent` field to an `AgentTool` implementation, which constructs the full command line. The `agent` field defaults to `"claude"`. Each execution is its own process — systemd manages its lifecycle via the `.service` unit.
-
-The persistent host process monitors running tasks via a **crash detection polling loop**: every 30 seconds, it scans all tasks with `running_state: "started"` and queries the system scheduler (`systemctl --user is-active` on Linux, `schtasks /query` on Windows) to check if the task process is still alive. If the scheduler reports the task is no longer running but `status.json` still says `"started"`, the daemon marks it as failed, writes a RESULT file, appends to history, and broadcasts the failure event. This also runs once at daemon startup to reconcile any tasks that crashed while the daemon was offline. Real-time task events are broadcast via a shared events module (`events.ts`) that publishes to NATS pub/sub and the serve daemon's HTTP SSE endpoint.
-
-### 5.2 The Execution Loop
-
-When `palmier run <task-id>` executes (triggered by a systemd timer, `systemctl start` from the host's `task.run` RPC handler, or direct CLI invocation):
-
-1. **Confirmation Check:**
-
-   * Reads `TASK.md`. If `requires_confirmation: true`:
-
-   * `palmier run` publishes a `started` event on `host-event.<host_id>.<task_id>`, then POSTs to the serve daemon's `/request-confirmation` HTTP endpoint. This registers an in-memory pending request and publishes a `confirm-request` event via NATS and SSE. The Web Server subscribes to `host-event.>` and sends a push notification.
-
-   * The user responds either via the PWA (which calls the `task.user_input` RPC on the host) or via the push notification action buttons (Service Worker calls `POST /api/push/respond`, Web Server forwards to the `task.user_input` RPC). Both paths resolve the in-memory pending request on the serve daemon.
-
-   * The `/request-confirmation` HTTP response returns to `palmier run` with `{ confirmed: true/false }`. If confirmed, it proceeds. If aborted, it publishes an `aborted` event and exits.
-
-2. **Launching the Task Process:**
-
-   * `palmier run` resolves the task's `agent` field to an `AgentTool` implementation and calls `getTaskRunCommandLine(task)` to obtain the command and arguments. The process is spawned directly (without a shell). stdin is closed (equivalent to `< /dev/null`) to prevent tools from hanging on an open pipe. The working directory is the project root (from `host.json`). The environment variable `PALMIER_TASK_ID=<task-id>` is set for identification.
-
-   * The spawned process inherits the default physical GUI session environment (`DISPLAY=:0`, `XDG_RUNTIME_DIR=/run/user/<uid>`) so that commands requiring a graphical display (e.g., headed browsers) run within the user's desktop session. `PALMIER_HTTP_PORT` is also set so agents can call the serve daemon's HTTP endpoints.
-
-   * The agent implementation is responsible for constructing the appropriate arguments (e.g., `--allowedTools` flags for Claude based on the task's permissions). The task's `user_prompt` is included in the arguments by the agent.
-
-3. **Completion:**
-
-   * When the child process exits successfully, `palmier run` publishes a `finished` event on `host-event` and persists it to `status.json`. If the process exits with a non-zero code, it publishes a `failed` event instead. If report files were generated, `palmier run` also publishes a `report-generated` event; the Web Server sends a push notification when it receives this event.
-
-### 5.3 Command-Triggered Execution
-
-When a task has a `command` field set, `palmier run` enters command-triggered mode after the confirmation check:
-
-1. **Spawn the command** using `shell: true` (allowing pipes, redirects, etc.) with stdout piped. stdin is closed. stderr is forwarded to the palmier process's stderr.
-
-2. **Read stdout line by line** using Node's `readline` interface. Empty lines are skipped.
-
-3. **For each line**, invoke the agent CLI:
-   * Build a per-line prompt: `user_prompt + "\n\nProcess this input:\n" + <line>` + the standard task outcome suffix.
-   * Call `agent.getTaskRunCommandLine()` with the augmented prompt.
-   * Spawn the agent via `spawnCommand()` and collect output.
-   * The standard permission/input retry loop applies: if the agent requests permissions or user input, line processing pauses, the user is prompted, and the invocation retries once resolved. Granted permissions accumulate across lines within the same run.
-
-4. **Sequential processing with bounded queue**: lines are processed one at a time. If lines arrive faster than agent invocations complete, they queue up to a max of 100 entries. Overflow drops the oldest unprocessed line.
-
-5. **On command exit or signal**: each agent invocation is written as a conversation entry in the RESULT file. Per-line agent outputs are also logged to `command-output.log` in the task directory.
-
-6. **Composable with schedules**: the configured schedule starts `palmier run` at the scheduled time, which spawns the command. The command runs until it exits or the task is aborted.
-
-### 5.4 Failsafes & Constraints
-
-* **Crash Detection:** The `palmier serve` daemon polls every 30 seconds, querying the system scheduler to detect tasks whose process exited without updating `status.json`. Detected crashes append a failed status entry to the existing RESULT file and broadcast the failure. This also runs at daemon startup to catch crashes that occurred while the daemon was offline.
-
-* **Process Tracking:** Each `palmier run` process writes its PID to `status.json`. On abort, `taskkill /pid <pid> /f /t` (Windows), `systemctl --user stop` (Linux), or `launchctl kill SIGTERM gui/$UID/<label>` (macOS, with a PID-based SIGTERM fallback) kills the process tree. On Windows, tasks use S4U LogonType in Task Scheduler to run without visible console windows.
-
-* **No Remote Timeout:** If a confirmation request is sent to the user's devices and the user does not respond, the task continues to wait indefinitely. The user can always respond via the PWA. There is no automatic deny-on-timeout.
-
-* **Confirmation Cleanup:** If `palmier run` is killed during a pending confirmation, the in-memory pending request on the serve daemon is orphaned. This is harmless — the `task.user_input` RPC will return `"not pending"` since the pending entry is removed when the HTTP connection closes.
-
-* **No Execution Time Limit:** Tasks may be long-running by design. There is no global execution timeout.
-
-## 6. Agent HTTP Endpoints
-
-The serve daemon exposes localhost-only HTTP endpoints that agents call during task execution. The port and task ID are baked into the agent's system prompt via template variables (`{{PORT}}`, `{{TASK_ID}}`).
-
-### 6.1 Endpoints
-
-* **`POST /notify`** — Sends a push notification to all paired devices. Body: `{ title, body }`. The serve daemon forwards to NATS `host.<host_id>.push.send`; the Web Server delivers via Web Push. Requires server mode.
-
-* **`POST /request-input`** — Requests input from the user during task execution. Body: `{ taskId, descriptions }`. The connection is held open until the user responds via the PWA (`task.user_input` RPC). Returns `{ values: [...] }` on success or `{ aborted: true }` if declined.
-
-* **`POST /request-confirmation`** — Requests task confirmation. Body: `{ taskId, taskName }`. Called by `palmier run` (not agents). Returns `{ confirmed: boolean }`.
-
-* **`POST /request-permission`** — Requests permission grants. Body: `{ taskId, taskName, permissions }`. Called by `palmier run` (not agents). Returns `{ response: "granted" | "granted_all" | "aborted" }`.
-
-* **`POST /task-event/pop?taskId=<id>`** — Drains one queued event for an event-triggered task. Called by `palmier run` (not agents). Atomically: if the task's in-memory FIFO queue is non-empty, returns `{ event: "<raw JSON payload>" }` and keeps `active_run = true`; if empty, clears `active_run` and returns `{ empty: true }`. Used only for `schedule_type: "on_new_notification" | "on_new_sms"` tasks.
-
-### 6.2 Resource Endpoints
-
-Resource REST endpoints are auto-generated from the `ResourceDefinition[]` registry in `mcp-tools.ts`. Each resource exposes a GET endpoint at its `restPath`. These are also available via the MCP protocol (`resources/list`, `resources/read`).
-
-* **`GET /notifications`** — Returns recent notifications from the user's Android device as a JSON array. Each notification contains `{ id, packageName, appName, title, text, timestamp, receivedAt }`. The host maintains a bounded in-memory collection (last 50 notifications) fed by NATS subscription to `host.<host_id>.device.notifications`.
-
-* **`GET /sms-messages`** — Returns recent SMS messages from the user's Android device as a JSON array. Each message contains `{ id, sender, body, timestamp, receivedAt }`. The host maintains a bounded in-memory collection (last 50 messages) fed by NATS subscription to `host.<host_id>.device.sms`.
-
-## 7. Database Schema (PostgreSQL)
-
-```sql
--- Host registrations
-CREATE TABLE hosts (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    name VARCHAR(255),
-    created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Push notification subscriptions (Web Push)
-CREATE TABLE push_subscriptions (
-    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-    host_id UUID NOT NULL REFERENCES hosts(id) ON DELETE CASCADE,
-    endpoint TEXT NOT NULL,
-    p256dh TEXT NOT NULL,
-    auth TEXT NOT NULL,
-    created_at TIMESTAMPTZ DEFAULT NOW(),
-    UNIQUE(host_id, endpoint)
-);
-```
-
-## 8. Web Server API Endpoints
-
-All endpoints are served over HTTPS. No user authentication is required — the server is stateless with respect to user identity.
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/api/hosts/register` | Register a new host. Returns `{ hostId, natsUrl, natsWsUrl, natsJwt, natsNkeySeed }` with host-scoped NATS credentials. |
-| `GET`  | `/api/config` | Returns pairing-only NATS credentials: `{ natsWsUrl, natsJwt, natsNkeySeed }`. JWT can only publish to `pair.*`. |
-| `GET`  | `/api/nats-credentials/:hostId` | Returns host-scoped NATS credentials for PWA: `{ natsWsUrl, natsJwt, natsNkeySeed }`. JWT scoped to one host's RPC + events. |
-| `POST` | `/api/push/subscribe` | Register a push subscription. Body: `{ hostId, endpoint, keys: { p256dh, auth } }`. |
-| `DELETE` | `/api/push/subscribe` | Unregister a push subscription. Body: `{ hostId, endpoint }`. |
-| `GET`  | `/api/push/vapid-key` | Returns the server's VAPID public key for push subscription. |
-| `POST` | `/api/push/respond` | Called by Service Worker to relay user responses to task confirmations. Body: `{ type, task_id, host_id, response }`. Web Server forwards the response to the host via the `host.<host_id>.rpc.task.user_input` NATS RPC. |
-| `POST` | `/api/device/notifications` | Relay a device notification from Android to the host. Body: `{ hostId, notification: { id, packageName, appName, title, text, timestamp } }`. Publishes to NATS `host.<hostId>.device.notifications`. |
-| `POST` | `/api/device/sms` | Relay an incoming SMS from Android to the host. Body: `{ hostId, sms: { id, sender, body, timestamp } }`. Publishes to NATS `host.<hostId>.device.sms`. |
-| `POST` | `/api/device/contacts-response` | Relay contacts response from Android to the host. Body: `{ requestId, hostId, result }`. Publishes to NATS `host.<hostId>.contacts.<requestId>`. |
-| `POST` | `/api/device/calendar-response` | Relay calendar response from Android to the host. Body: `{ requestId, hostId, result }`. Publishes to NATS `host.<hostId>.calendar.<requestId>`. |
-| `POST` | `/api/device/sms-response` | Relay SMS send response from Android to the host. Body: `{ requestId, hostId, result }`. Publishes to NATS `host.<hostId>.sms.<requestId>`. |
-| `POST` | `/api/device/alarm-response` | Relay alarm response from Android to the host. Body: `{ requestId, hostId, result }`. Publishes to NATS `host.<hostId>.alarm.<requestId>`. |
-| `POST` | `/api/device/battery-response` | Relay battery response from Android to the host. Body: `{ requestId, hostId, result }`. Publishes to NATS `host.<hostId>.battery.<requestId>`. |
-| `POST` | `/api/device/ringer-response` | Relay ringer mode response from Android to the host. Body: `{ requestId, hostId, result }`. Publishes to NATS `host.<hostId>.ringer.<requestId>`. |
-| `GET`  | `/health` | Health check. |

package/src/agents/agent-instructions.md

@@ -1,28 +0,0 @@
-You are an AI agent executing a task on behalf of the user. Follow these instructions carefully.
-
-## Reporting Output
-
-If you generate report or output files, print each file path on its own line using this exact format:
-[PALMIER_REPORT] <filename>
-
-## Completion
-
-When you are done, output exactly one of these markers as the very last line (no other text on the same line):
-[PALMIER_TASK_SUCCESS]
-[PALMIER_TASK_FAILURE]
-
-## Permissions
-
-Whenever a tool you are trying to use is denied or you lack the required permissions, print each required permission on its own line using this exact format:
-[PALMIER_PERMISSION] <tool_name> | <description>
-
-## HTTP Endpoints
-
-{{ENDPOINT_DOCS}}
-
-The task to execute follows below:
-
----
-
-{{TASK_DESCRIPTION}}
-