palmier 0.6.0 → 0.6.2

package/palmier-server/spec.md

@@ -0,0 +1,415 @@
+# 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) and **Windows** (Task Scheduler for both daemon and task triggers). macOS support (launchd) is planned. OS-specific details in this spec use Linux examples unless noted otherwise; the `PlatformService` abstraction handles cross-platform differences.
+
+### 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 a local HTTP server (bound to `127.0.0.1` by default, or `0.0.0.0` if LAN mode is enabled) alongside the NATS transport. Localhost-only HTTP endpoints (`/notify`, `/request-input`, `/request-confirmation`, `/request-permission`) are used by agents and the `palmier run` process for interactive flows via held HTTP connections. `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 `getPlanGenerationCommandLine()`, `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). 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. Co-located with the NATS server on the same machine.
+
+* **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.
+
+## 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 whether to enable LAN access and which HTTP port to use (default 9966).
+3. Shows a summary of task storage directory, local access URL, LAN URL (if enabled), detected agents, and any existing tasks to recover. Asks for confirmation before proceeding.
+4. Registers with the Palmier server via `POST <url>/api/hosts/register` — server returns `{ hostId, natsUrl, natsWsUrl, natsToken }`.
+5. Saves config to `~/.config/palmier/host.json` (includes `httpPort`, `lanEnabled`, NATS credentials).
+6. Installs a systemd user service (Linux) or Task Scheduler entry (Windows) and auto-enters pair mode.
+
+The daemon automatically recovers existing tasks by reinstalling their system timers on startup.
+
+The `serve` daemon always starts an HTTP server on the configured port. Three access modes are available:
+
+**Local mode** (always available):
+- HTTP server binds to `127.0.0.1:<port>`. 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.
+
+**LAN mode** (enabled during init):
+- HTTP server binds to `0.0.0.0:<port>`, making the PWA accessible from the local network at `http://<host-ip>:<port>`. Non-localhost access requires pairing via a pairing code. Push notifications are not available.
+
+**Server mode** (NATS cloud relay, always on):
+- Communication is relayed through the Palmier cloud server via NATS. PWA is accessed at `https://app.palmier.me`. Enables push notifications and remote access.
+
+### 2.2 Device Pairing
+
+Local access (`http://localhost:<port>`) requires no pairing — the PWA auto-connects with a placeholder host ID.
+
+For LAN and server mode, `palmier pair` generates a 6-character pairing code from the charset `ABCDEFGHJKMNPQRSTUVWXYZ23456789` (excludes ambiguous O/0/I/1/L) and listens on both transports in parallel:
+
+**Server mode (NATS):**
+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 }`.
+
+**LAN mode (HTTP):**
+1. Host registers the code with the serve daemon via `POST /pair-register`.
+2. User opens `http://<host-ip>:<port>` and enters the code. No host address field is shown since the request is same-origin.
+3. PWA posts `POST /pair` with `{ code }` to the same origin. Host responds with `{ hostId, clientToken, directUrl }`.
+
+In both cases, 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.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.
+
+**Host RPC endpoints** (request-reply, subject: `host.<host_id>.rpc.<method>`):
+
+| Method | Params | Description |
+|---|---|---|
+| `task.list` | *(none)* | List all tasks with frontmatter, body, created_at, and current status. Returns `agents` array of detected CLIs, `host_platform`, and `version`. |
+| `task.get` | `id` | Get a single task with frontmatter, body, and current status. |
+| `task.create` | `user_prompt`, `agent`, `triggers?`, `triggers_enabled?`, `requires_confirmation?`, `yolo_mode?`, `foreground_mode?`, `command?` | Create a new task with auto-generated plan and name (130s timeout), install system timers if triggers present. If `command` is set, creates a command-triggered task (plan generation is skipped). |
+| `task.update` | `id`, `user_prompt?`, `agent?`, `triggers?`, `triggers_enabled?`, `requires_confirmation?`, `yolo_mode?`, `foreground_mode?`, `command?` | Update an existing task. Regenerates plan if `user_prompt` or `agent` changed, or if no plan exists yet (130s timeout). If `command` is set, plan is cleared. Reinstall timers as needed |
+| `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. |
+
+### 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 (frontmatter + body)
+    ├── 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"
+triggers:
+  - type: "cron"
+    value: "0 9 * * 1"
+  - type: "once"
+    value: "2026-03-20T15:00:00Z"
+triggers_enabled: true
+requires_confirmation: true
+---
+[Detailed execution plan generated by the non-interactive generation step]
+```
+
+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`. Plan generation is skipped for command-triggered tasks.
+
+#### Trigger Lifecycle
+
+* **`triggers_enabled`:** Controls whether systemd timers are installed for the task's triggers. 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 Triggers" checkbox only appears in the UI when the task has at least one trigger.
+* **`cron` triggers:** Persist indefinitely. The systemd timer remains active until the task is deleted or triggers are disabled.
+* **`once` triggers:** After firing, the trigger is removed from the `TASK.md` frontmatter and its corresponding systemd timer/service files are cleaned up. The task itself 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).
+
+### 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.<activeHostId>.>` 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 triggers are 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 "once" trigger 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 NATS credentials from `GET /api/config` (returns `{ natsWsUrl, natsToken }`) and connects to NATS via WebSocket.
+
+3. PWA sends a `task.list` request to `host.<host_id>.rpc.task.list` using NATS request-reply, including the `clientToken` in the payload.
+
+4. If the host responds, it returns `{ tasks: [...] }` — an array of **flat task objects** (frontmatter fields spread to the top level, plus `body`) and displays the task list. If the request fails with NATS 503 ("no responders"), the PWA shows an empty task list — 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. PWA discovers pending confirmations from the `task.list` RPC response — tasks with a pending confirmation, permission, or input request are shown as interactive modals. 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 Task Creation & Update
+
+1. User clicks the "Describe your new task..." placeholder in the task list view, which opens the task form directly.
+
+2. User enters a prompt, selects an agent, configures triggers (UI translates human-readable times to cron formats) and confirmation settings, and clicks "Create" (or "Update" for existing tasks).
+
+3. PWA sends `task.create` (or `task.update`) via NATS request-reply to Host (130s timeout). The host generates the execution plan and task name by running the configured agent CLI in non-interactive mode (e.g., `claude -p "Generate execution plan for: [prompt]"`), then creates the task with the generated plan as its body. The PWA renders the plan markdown as rich formatted text (headings, tables, lists, code blocks) using `react-markdown` with `remark-gfm` for GFM support.
+
+4. For updates: if the user changes the `user_prompt` or `agent`, the plan is regenerated. If neither changed, the existing plan is preserved. Existing tasks with a plan show a clickable "Execution Plan" link to view the plan; this link disappears when the user edits the prompt or changes the agent.
+
+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. The `triggers` field defaults to `[]` if omitted or undefined.
+
+6. Host creates/updates the `tasks/<task-id>/TASK.md` file and returns the **full flat task object** (all frontmatter fields plus `body` at the top level). The PWA uses this response directly to update the UI.
+
+7. **OS Integration:** Host translates triggers 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.3 On-Demand Execution
+
+Any task that is not currently running can be executed immediately:
+
+* **PWA:** 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).
+* **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.4 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 plan (body from `TASK.md` or `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 triggers**: cron/once triggers start `palmier run` on schedule, 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) or `systemctl --user stop` (Linux) kills the entire 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" }`.
+
+## 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, natsToken }`. Rate-limited by IP. |
+| `GET`  | `/api/config` | Returns NATS WebSocket credentials for the PWA: `{ natsWsUrl, natsToken }`. |
+| `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. |
+| `GET`  | `/health` | Health check. |

package/src/agents/agent-instructions.md

@@ -28,7 +28,7 @@ The request blocks until the user responds. Response: `{"values":["answer1","ans
 
 **Sending push notifications** — To notify the user, POST to `/notify` with:
 ```json
-{"title":"...","body":"..."}
+{"taskId":"{{TASK_ID}}","title":"...","body":"..."}
 ```
 
 ---

package/src/agents/agent.ts

@@ -2,16 +2,25 @@ import type { ParsedTask, RequiredPermission } from "../types.js";
 import { ClaudeAgent } from "./claude.js";
 import { GeminiAgent } from "./gemini.js";
 import { CodexAgent } from "./codex.js";
+import { DroidAgent } from "./droid.js";
 import { OpenClawAgent } from "./openclaw.js";
 import { CopilotAgent } from "./copilot.js";
 import { QwenAgent } from "./qwen.js";
 import { KimiAgent } from "./kimi.js";
+import { GooseAgent } from "./goose.js";
+import { OpenCodeAgent } from "./opencode.js";
+import { DeepAgents } from "./deepagents.js";
+import { Aider } from "./aider.js";
+import { OpenHands } from "./openhands.js";
+import { Cursor } from "./cursor.js";
 
 export interface CommandLine {
   command: string;
   args: string[];
   /** If provided, the string is written to the process's stdin and then the pipe is closed. */
   stdin?: string;
+  /** Additional environment variables to set for the spawned process. */
+  env?: Record<string, string>;
 }
 
 /**
@@ -45,16 +54,30 @@ const agentRegistry: Record<string, AgentTool> = {
   copilot: new CopilotAgent(),
   qwen: new QwenAgent(),
   kimi: new KimiAgent(),
+  droid: new DroidAgent(),
+  goose: new GooseAgent(),
+  opencode: new OpenCodeAgent(),
+  deepagents: new DeepAgents(),
+  aider: new Aider(),
+  openhands: new OpenHands(),
+  cursor: new Cursor(),
 };
 
 const agentLabels: Record<string, string> = {
   claude: "Claude Code",
   gemini: "Gemini CLI",
   codex: "Codex CLI",
+  droid: "Droid CLI",
   openclaw: "OpenClaw",
   copilot: "Copilot CLI",
   qwen: "Qwen Code",
   kimi: "Kimi Code",
+  goose: "Goose CLI",
+  opencode: "OpenCode",
+  deepagents: "Deep Agents CLI",
+  aider: "Aider",
+  openhands: "OpenHands",
+  cursor: "Cursor CLI",
 };
 
 export interface DetectedAgent {

package/src/agents/aider.ts

@@ -0,0 +1,37 @@
+import type { ParsedTask, RequiredPermission } from "../types.js";
+import { execSync } from "child_process";
+import type { AgentTool, CommandLine } from "./agent.js";
+import { getAgentInstructions } from "./shared-prompt.js";
+import { SHELL } from "../platform/index.js";
+
+export class Aider implements AgentTool {
+  supportsPermissions = false;
+  getPlanGenerationCommandLine(prompt: string): CommandLine {
+    return {
+      command: "aider",
+      args: ["--message", prompt],
+    };
+  }
+
+  getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
+    const yolo = extraPermissions === "yolo";
+    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const args = [];
+
+    if (yolo) {
+      args.push("--yes-always");
+    }
+    args.push("--message", prompt);
+
+    return { command: "aider", args};
+  }
+
+  async init(): Promise<boolean> {
+    try {
+      execSync("aider --version", { stdio: "ignore", shell: SHELL });
+    } catch {
+      return false;
+    }
+    return true;
+  }
+}

package/src/agents/cursor.ts

@@ -0,0 +1,38 @@
+import type { ParsedTask, RequiredPermission } from "../types.js";
+import { execSync } from "child_process";
+import type { AgentTool, CommandLine } from "./agent.js";
+import { getAgentInstructions } from "./shared-prompt.js";
+import { SHELL } from "../platform/index.js";
+
+export class Cursor implements AgentTool {
+  supportsPermissions = false;
+  getPlanGenerationCommandLine(prompt: string): CommandLine {
+    return {
+      command: "cursor",
+      args: ["-p", prompt],
+    };
+  }
+
+  getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
+    const yolo = extraPermissions === "yolo";
+    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const args = [];
+
+    if (yolo) {
+      args.push("--force");
+    }
+    if (followupPrompt) {args.push("--continue");} // continue mode for followups
+    args.push("-p", prompt);
+
+    return { command: "cursor", args};
+  }
+
+  async init(): Promise<boolean> {
+    try {
+      execSync("cursor --version", { stdio: "ignore", shell: SHELL });
+    } catch {
+      return false;
+    }
+    return true;
+  }
+}

package/src/agents/deepagents.ts

@@ -0,0 +1,38 @@
+import type { ParsedTask, RequiredPermission } from "../types.js";
+import { execSync } from "child_process";
+import type { AgentTool, CommandLine } from "./agent.js";
+import { getAgentInstructions } from "./shared-prompt.js";
+import { SHELL } from "../platform/index.js";
+
+export class DeepAgents implements AgentTool {
+  supportsPermissions = false;
+  getPlanGenerationCommandLine(prompt: string): CommandLine {
+    return {
+      command: "deepagents",
+      args: ["--non-interactive", prompt],
+    };
+  }
+
+  getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
+    const yolo = extraPermissions === "yolo";
+    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const args = [];
+
+    if (yolo) {
+      args.push("--auto-approve");
+    }
+    if (followupPrompt) {args.push("--resume");} // continue mode for followups
+    args.push("--non-interactive", prompt);
+
+    return { command: "deepagents", args};
+  }
+
+  async init(): Promise<boolean> {
+    try {
+      execSync("deepagents --version", { stdio: "ignore", shell: SHELL });
+    } catch {
+      return false;
+    }
+    return true;
+  }
+}

package/src/agents/droid.ts

@@ -0,0 +1,37 @@
+import type { ParsedTask, RequiredPermission } from "../types.js";
+import { execSync } from "child_process";
+import type { AgentTool, CommandLine } from "./agent.js";
+import { getAgentInstructions } from "./shared-prompt.js";
+import { SHELL } from "../platform/index.js";
+
+export class DroidAgent implements AgentTool {
+  supportsPermissions = false;
+  getPlanGenerationCommandLine(prompt: string): CommandLine {
+    return {
+      command: "droid",
+      args: ["exec", prompt],
+    };
+  }
+
+  getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
+    const yolo = extraPermissions === "yolo";
+    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const args = ["exec", "--session-id", task.frontmatter.id];
+
+    if (yolo) {
+      args.push("--skip-permissions-unsafe");
+    }
+    args.push(prompt);
+
+    return { command: "droid", args};
+  }
+
+  async init(): Promise<boolean> {
+    try {
+      execSync("droid --version", { stdio: "ignore", shell: SHELL });
+    } catch {
+      return false;
+    }
+    return true;
+  }
+}