palmier 0.6.5 → 0.6.7

package/palmier-server/pwa/src/service-worker.ts

@@ -33,14 +33,15 @@ self.addEventListener("push", (event) => {
   // Silent dismiss: close matching notification without showing a new one
   if (type === "confirm-dismiss" || type === "permission-dismiss" || type === "input-dismiss") {
     const data = payload.data ?? payload;
-    const taskId = (data as Record<string, unknown>).task_id;
     const dataHostId = (data as Record<string, unknown>).host_id;
+    const requestId = (data as Record<string, unknown>).session_id;
+    const taskId = (data as Record<string, unknown>).task_id; // permission-dismiss still uses task_id
     event.waitUntil(
       self.registration.getNotifications().then((notifications) => {
         for (const n of notifications) {
-          if (n.data?.task_id === taskId && n.data?.host_id === dataHostId) {
-            n.close();
-          }
+          if (n.data?.host_id !== dataHostId) continue;
+          if (requestId && n.data?.session_id === requestId) { n.close(); continue; }
+          if (taskId && n.data?.task_id === taskId) { n.close(); } // permission only
         }
       })
     );
@@ -85,7 +86,7 @@ self.addEventListener("notificationclick", (event) => {
   const data = notification.data ?? {};
   const action = event.action;
 
-  if (action && data.type === "confirm" && data.task_id && data.host_id) {
+  if (action && data.type === "confirm" && data.session_id && data.host_id) {
     const response = action === "confirm" ? "confirmed" : "aborted";
 
     event.waitUntil(
@@ -93,8 +94,7 @@ self.addEventListener("notificationclick", (event) => {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
-          type: data.type,
-          task_id: data.task_id,
+          session_id: data.session_id,
           host_id: data.host_id,
           response,
         }),

package/palmier-server/server/.env.example

@@ -14,3 +14,7 @@ NATS_TOKEN=
 VAPID_PUBLIC_KEY=
 VAPID_PRIVATE_KEY=
 VAPID_MAILTO=mailto:admin@example.com
+
+# Firebase Admin SDK (for FCM push to Android devices)
+# Download from: Firebase Console → Project Settings → Service accounts → Generate new private key
+GOOGLE_APPLICATION_CREDENTIALS=./palmier-firebase-adminsdk.json

package/palmier-server/server/package.json

@@ -12,6 +12,7 @@
     "cors": "^2.8.5",
     "dotenv": "^16.4.7",
     "express": "^4.21.2",
+    "firebase-admin": "^13.8.0",
     "helmet": "^8.0.0",
     "jsonwebtoken": "^9.0.2",
     "nats": "^2.29.1",

package/palmier-server/server/src/db.ts

@@ -27,6 +27,16 @@ export async function initDb(): Promise<void> {
           UNIQUE(host_id, endpoint)
       );
     `);
+    await client.query(`
+      CREATE TABLE IF NOT EXISTS fcm_tokens (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          host_id UUID NOT NULL REFERENCES hosts(id) ON DELETE CASCADE,
+          fcm_token TEXT NOT NULL,
+          device_label VARCHAR(255),
+          updated_at TIMESTAMPTZ DEFAULT NOW(),
+          UNIQUE(host_id, fcm_token)
+      );
+    `);
     console.log("Database tables initialized.");
   } finally {
     client.release();

package/palmier-server/server/src/fcm.ts

@@ -0,0 +1,74 @@
+import admin from "firebase-admin";
+import { pool } from "./db.js";
+
+let initialized = false;
+
+function ensureInitialized(): boolean {
+  if (initialized) return true;
+
+  if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+    console.warn("GOOGLE_APPLICATION_CREDENTIALS not set. FCM will not work.");
+    return false;
+  }
+
+  admin.initializeApp({
+    credential: admin.credential.applicationDefault(),
+  });
+  initialized = true;
+  return true;
+}
+
+export async function sendFcmToClients(
+  hostId: string,
+  data: Record<string, string>
+): Promise<void> {
+  if (!ensureInitialized()) {
+    console.warn("[FCM] Not initialized, skipping message for host", hostId);
+    return;
+  }
+
+  const result = await pool.query(
+    "SELECT fcm_token FROM fcm_tokens WHERE host_id = $1",
+    [hostId]
+  );
+
+  if (result.rows.length === 0) {
+    console.warn(`[FCM] No FCM tokens registered for host ${hostId}`);
+    return;
+  }
+
+  const sendPromises = result.rows.map(async (row) => {
+    try {
+      await admin.messaging().send({
+        token: row.fcm_token,
+        data,
+      });
+    } catch (err: any) {
+      if (
+        err.code === "messaging/registration-token-not-registered" ||
+        err.code === "messaging/invalid-registration-token"
+      ) {
+        await pool.query(
+          "DELETE FROM fcm_tokens WHERE host_id = $1 AND fcm_token = $2",
+          [hostId, row.fcm_token]
+        );
+        console.log(`[FCM] Removed stale token for host ${hostId}`);
+      } else {
+        console.error(`[FCM] Failed to send to token:`, err.message);
+      }
+    }
+  });
+
+  await Promise.allSettled(sendPromises);
+}
+
+export async function sendFcmToDevice(
+  fcmToken: string,
+  data: Record<string, string>
+): Promise<void> {
+  if (!ensureInitialized()) {
+    throw new Error("FCM not initialized");
+  }
+
+  await admin.messaging().send({ token: fcmToken, data });
+}

package/palmier-server/server/src/index.ts

@@ -5,12 +5,13 @@ import express from "express";
 import helmet from "helmet";
 import { pool, initDb } from "./db.js";
 import { connectNats, getNatsConnection } from "./nats.js";
-import { sendPushToHost } from "./push.js";
-
 import { StringCodec } from "nats";
 
 import hostsRoutes from "./routes/hosts.js";
 import pushRoutes from "./routes/push.js";
+import fcmRoutes from "./routes/fcm.js";
+import { notifyClients } from "./notify.js";
+import { sendFcmToClients, sendFcmToDevice } from "./fcm.js";
 
 const PORT = parseInt(process.env.PORT || "3000", 10);
 
@@ -42,28 +43,34 @@ async function main(): Promise<void> {
             running_state?: string;
             name?: string;
             run_id?: string;
+            session_id?: string;
+            description?: string;
+            agent_name?: string;
             required_permissions?: Array<{ name: string; description: string }>;
-            input_descriptions?: string[];
+            input_questions?: string[];
             result_file?: string;
           };
 
           if (data.event_type === "confirm-request") {
-            await sendPushToHost(hostId, {
+            await notifyClients(hostId, {
               type: "confirm",
-              task_id: taskId,
+              title: "Confirmation Required",
+              body: data.description || "A task requires confirmation to run.",
               host_id: hostId,
+              session_id: data.session_id,
+              agent_name: data.agent_name,
             });
           } else if (data.event_type === "confirm-resolved") {
-            await sendPushToHost(hostId, {
+            await notifyClients(hostId, {
               type: "confirm-dismiss",
-              task_id: taskId,
               host_id: hostId,
+              session_id: data.session_id,
             });
           } else if (data.event_type === "permission-request") {
             const taskLabel = data.name
               ? data.name.length > 60 ? data.name.slice(0, 60) + "…" : data.name
               : "A task";
-            await sendPushToHost(hostId, {
+            await notifyClients(hostId, {
               type: "permission",
               title: "Permission Required",
               body: `${taskLabel} needs additional permissions to continue.`,
@@ -71,27 +78,25 @@ async function main(): Promise<void> {
               host_id: hostId,
             });
           } else if (data.event_type === "permission-resolved") {
-            await sendPushToHost(hostId, {
+            await notifyClients(hostId, {
               type: "permission-dismiss",
               task_id: taskId,
               host_id: hostId,
             });
           } else if (data.event_type === "input-request") {
-            const taskLabel = data.name
-              ? data.name.length > 60 ? data.name.slice(0, 60) + "…" : data.name
-              : "A task";
-            await sendPushToHost(hostId, {
+            await notifyClients(hostId, {
               type: "input",
               title: "Input Required",
-              body: `${taskLabel} needs your input to continue.`,
-              task_id: taskId,
+              body: "A task needs your input to continue.",
               host_id: hostId,
+              session_id: data.session_id,
+              agent_name: data.agent_name,
             });
           } else if (data.event_type === "input-resolved") {
-            await sendPushToHost(hostId, {
+            await notifyClients(hostId, {
               type: "input-dismiss",
-              task_id: taskId,
               host_id: hostId,
+              session_id: data.session_id,
             });
           } else if (data.event_type === "report-generated" || (data.event_type === "running-state" && data.running_state === "failed")) {
             const label = data.name;
@@ -100,7 +105,7 @@ async function main(): Promise<void> {
               : "Task";
             const isFailure = data.running_state === "failed";
             const body = isFailure ? `${taskLabel} — failed` : `${taskLabel} — report ready`;
-            await sendPushToHost(hostId, {
+            await notifyClients(hostId, {
               type: isFailure ? "fail" : "complete",
               title: "Palmier",
               body,
@@ -132,7 +137,8 @@ async function main(): Promise<void> {
             hostId: string;
             title: string;
             body: string;
-            task_id?: string;
+            session_id?: string;
+            agent_name?: string;
           };
 
           // Validate hostId in subject matches payload
@@ -144,12 +150,17 @@ async function main(): Promise<void> {
             continue;
           }
 
+          // If no agent_name, session_id is a taskId — include as task_id for deep-linking
+          const isTask = data.session_id && !data.agent_name;
+
           console.log(`[Push] Sending notification for host ${data.hostId}`);
-          await sendPushToHost(data.hostId, {
+          await notifyClients(data.hostId, {
             type: "notification",
+            host_id: data.hostId,
             title: data.title,
             body: data.body,
-            ...(data.task_id ? { task_id: data.task_id } : {}),
+            ...(isTask ? { task_id: data.session_id } : {}),
+            agent_name: data.agent_name,
           });
 
           if (msg.reply) {
@@ -167,19 +178,88 @@ async function main(): Promise<void> {
     }
   })();
 
+  // Subscribe to FCM geolocation requests from hosts
+  (async () => {
+    try {
+      const conn = await getNatsConnection();
+      const sub = conn.subscribe("host.*.fcm.geolocation");
+      console.log("Listening for FCM geolocation requests");
+
+      for await (const msg of sub) {
+        try {
+          const data = JSON.parse(sc.decode(msg.data)) as {
+            hostId: string;
+            requestId: string;
+            fcmToken?: string;
+          };
+
+          const subjectHostId = msg.subject.split(".")[1];
+          if (data.hostId !== subjectHostId) {
+            if (msg.reply) {
+              msg.respond(sc.encode(JSON.stringify({ error: "hostId mismatch" })));
+            }
+            continue;
+          }
+
+          const fcmPayload = {
+            type: "geolocation-request",
+            requestId: data.requestId,
+            hostId: data.hostId,
+          };
+
+          console.log(`[FCM] Sending geolocation request for host ${data.hostId}`);
+          if (data.fcmToken) {
+            await sendFcmToDevice(data.fcmToken, fcmPayload);
+          } else {
+            await sendFcmToClients(data.hostId, fcmPayload);
+          }
+
+          if (msg.reply) {
+            msg.respond(sc.encode(JSON.stringify({ ok: true })));
+          }
+        } catch (err) {
+          console.error("[FCM] Error handling geolocation request:", err);
+          if (msg.reply) {
+            msg.respond(sc.encode(JSON.stringify({ error: String(err) })));
+          }
+        }
+      }
+    } catch (err) {
+      console.error("Failed to subscribe to FCM geolocation requests:", err);
+    }
+  })();
+
   // Create Express app
   const app = express();
 
   app.use(
     helmet({
       contentSecurityPolicy: false,
+      crossOriginResourcePolicy: false,
     })
   );
+
+  // CORS for Capacitor Android app (requests from capacitor://localhost)
+  app.use((req, res, next) => {
+    const origin = req.headers.origin;
+    if (origin && (origin.startsWith("capacitor://") || origin === "https://localhost" || origin.startsWith("http://localhost"))) {
+      res.setHeader("Access-Control-Allow-Origin", origin);
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, PATCH, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+    }
+    if (req.method === "OPTIONS") {
+      res.sendStatus(204);
+      return;
+    }
+    next();
+  });
+
   app.use(express.json());
 
   // Mount routes
   app.use("/api/hosts", hostsRoutes);
   app.use("/api/push", pushRoutes);
+  app.use("/api/fcm", fcmRoutes);
 
   // Public NATS config endpoint (used by PWA for pairing)
   app.get("/api/config", (_req, res) => {

package/palmier-server/server/src/notify.ts

@@ -0,0 +1,34 @@
+import { sendPushToClients } from "./push.js";
+import { sendFcmToClients } from "./fcm.js";
+
+export interface NotificationPayload {
+  type: string;
+  host_id: string;
+  title?: string;
+  body?: string;
+  task_id?: string;
+  session_id?: string;
+  run_id?: string;
+  result_file?: string;
+  agent_name?: string;
+}
+
+function stringifyPayload(payload: NotificationPayload): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(payload)) {
+    if (value !== undefined && value !== null) {
+      result[key] = String(value);
+    }
+  }
+  return result;
+}
+
+export async function notifyClients(
+  hostId: string,
+  payload: NotificationPayload
+): Promise<void> {
+  await Promise.allSettled([
+    sendPushToClients(hostId, payload),
+    sendFcmToClients(hostId, stringifyPayload(payload)),
+  ]);
+}

package/palmier-server/server/src/push.ts

@@ -19,7 +19,7 @@ function ensureConfigured(): void {
   configured = true;
 }
 
-export async function sendPushToHost(
+export async function sendPushToClients(
   hostId: string,
   payload: object | string
 ): Promise<void> {

package/palmier-server/server/src/routes/fcm.ts

@@ -0,0 +1,64 @@
+import { Router, Request, Response } from "express";
+import type { Router as RouterType } from "express";
+import { pool } from "../db.js";
+import { getNatsConnection } from "../nats.js";
+import { StringCodec } from "nats";
+
+const router: RouterType = Router();
+
+// POST /api/fcm/register - Register or refresh an FCM token for a host
+router.post("/register", async (req: Request, res: Response) => {
+  try {
+    const { hostId, fcmToken, deviceLabel } = req.body;
+
+    if (!hostId || !fcmToken) {
+      res.status(400).json({ error: "hostId and fcmToken are required" });
+      return;
+    }
+
+    await pool.query(
+      `INSERT INTO fcm_tokens (host_id, fcm_token, device_label, updated_at)
+       VALUES ($1, $2, $3, NOW())
+       ON CONFLICT (host_id, fcm_token)
+       DO UPDATE SET device_label = EXCLUDED.device_label, updated_at = NOW()`,
+      [hostId, fcmToken, deviceLabel || null]
+    );
+
+    res.status(201).json({ message: "FCM token registered" });
+  } catch (err) {
+    console.error("FCM register error:", err);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+// POST /api/fcm/geolocation-response - Receive location from Android device, forward via NATS
+router.post("/geolocation-response", async (req: Request, res: Response) => {
+  try {
+    const { requestId, hostId, latitude, longitude, accuracy, timestamp, error } = req.body;
+
+    if (!requestId || !hostId) {
+      res.status(400).json({ error: "requestId and hostId are required" });
+      return;
+    }
+
+    const conn = await getNatsConnection();
+    const sc = StringCodec();
+    const subject = `host.${hostId}.geolocation.${requestId}`;
+
+    if (error) {
+      conn.publish(subject, sc.encode(JSON.stringify({ error })));
+    } else {
+      conn.publish(
+        subject,
+        sc.encode(JSON.stringify({ latitude, longitude, accuracy, timestamp }))
+      );
+    }
+
+    res.json({ message: "Location forwarded" });
+  } catch (err) {
+    console.error("FCM geolocation-response error:", err);
+    res.status(500).json({ error: "Internal server error" });
+  }
+});
+
+export default router;

package/palmier-server/server/src/routes/push.ts

@@ -66,14 +66,15 @@ router.get("/vapid-key", (_req, res: Response) => {
   res.json({ publicKey });
 });
 
-// POST /api/push/respond - Respond to a pending confirmation via NATS request-reply
+// POST /api/push/respond - Respond to a pending request via NATS request-reply
 router.post("/respond", async (req: Request, res: Response) => {
   try {
-    const { task_id, host_id, response } = req.body;
+    const { task_id, session_id, host_id, response } = req.body;
+    const id = session_id || task_id;
 
-    if (!task_id || !host_id || !response) {
+    if (!id || !host_id || !response) {
       res.status(400).json({
-        error: "task_id, host_id, and response are required",
+        error: "host_id, response, and session_id (or task_id for permissions) are required",
       });
       return;
     }
@@ -81,7 +82,7 @@ router.post("/respond", async (req: Request, res: Response) => {
     const conn = await getNatsConnection();
     const sc = StringCodec();
     const subject = `host.${host_id}.rpc.task.user_input`;
-    const payload = sc.encode(JSON.stringify({ id: task_id, value: [response] }));
+    const payload = sc.encode(JSON.stringify({ id, value: [response] }));
 
     const reply = await conn.request(subject, payload, { timeout: 5000 });
     const result = JSON.parse(sc.decode(reply.data));

package/palmier-server/spec.md

@@ -12,9 +12,11 @@ The host supports **Linux** (systemd) and **Windows** (Task Scheduler for both d
 
 ### 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.
+* **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`, `/device-geolocation`) are used by agents and the `palmier run` process for interactive flows via held HTTP connections. `/request-input` and `/notify` are task-independent (no `taskId` required) — input requests use an internal `requestId` for routing. `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.
+* **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. 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 and `FusedLocationProviderClient` for GPS access. When a geolocation request arrives via FCM, a foreground service briefly starts to fetch the GPS fix and POST the result back to the Web Server. 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.
 

package/src/agents/agent-instructions.md

@@ -18,18 +18,40 @@ If the task fails because a tool was denied or you lack the required permissions
 
 ## HTTP Endpoints
 
-The following HTTP endpoints are available at http://localhost:{{PORT}} during task execution. Use curl to call them.
+The following HTTP endpoints are available at http://localhost:{{PORT}} during task execution. Use curl to call them. All endpoints require `taskId` in the request body.
 
-**Requesting user input** — When you need information from the user (credentials, answers to questions, preferences, clarifications, etc.), do not guess, fail, or prompt via stdout, even in a non-interactive environment. Instead, POST to `/request-input` with:
+**`POST /request-input`** — Request input from the user. The request blocks until the user responds.
 ```json
-{"taskId":"{{TASK_ID}}","descriptions":["question 1","question 2"]}
+{"taskId": "{{TASK_ID}}", "description": "optional context", "questions": ["question 1", "question 2"]}
 ```
-The request blocks until the user responds. Response: `{"values":["answer1","answer2"]}` on success, or `{"aborted":true}` if the user declines.
+- `taskId` (required, string): The current task ID.
+- `questions` (required, string array): Questions to present to the user.
+- `description` (optional, string): Context or heading for the input request.
+- Response: `{"values": ["answer1", "answer2"]}` on success, or `{"aborted": true}` if the user declines.
+- When you need information from the user (credentials, answers to questions, preferences, clarifications, etc.), do not guess, fail, or prompt via stdout, even in a non-interactive environment. Use this endpoint instead.
 
-**Sending push notifications** — To notify the user, POST to `/notify` with:
+**`POST /request-confirmation`** — Request confirmation from the user. The request blocks until the user confirms or aborts.
 ```json
-{"taskId":"{{TASK_ID}}","title":"...","body":"..."}
+{"taskId": "{{TASK_ID}}", "description": "What the user is confirming"}
 ```
+- `taskId` (required, string): The current task ID.
+- `description` (required, string): What the user is confirming.
+- Response: `{"confirmed": true}` or `{"confirmed": false}`.
+
+**`POST /device-geolocation`** — Get the GPS location of the user's mobile device. Blocks until the device responds (up to 30 seconds).
+```json
+{"taskId": "{{TASK_ID}}"}
+```
+- `taskId` (required, string): The current task ID.
+- Response: `{"latitude": ..., "longitude": ..., "accuracy": ..., "timestamp": ...}` on success, or `{"error": "..."}` on failure.
+
+**`POST /notify`** — Send a push notification to the user's device.
+```json
+{"taskId": "{{TASK_ID}}", "title": "...", "body": "..."}
+```
+- `taskId` (required, string): The current task ID.
+- `title` (required, string): Notification title.
+- `body` (required, string): Notification body.
 
 ---
 

package/src/agents/agent.ts

@@ -15,6 +15,7 @@ import { Cursor } from "./cursor.js";
 import { Kiro } from "./kiro.js";
 import { Cline } from "./cline.js";
 import { Qoder } from "./qoder.js";
+import { Hermes } from "./hermes.js";
 
 export interface CommandLine {
   command: string;
@@ -65,6 +66,7 @@ const agentRegistry: Record<string, AgentTool> = {
   kiro: new Kiro(),
   cline: new Cline(),
   qoder: new Qoder(),
+  hermes: new Hermes(),
 };
 
 const agentLabels: Record<string, string> = {
@@ -81,9 +83,10 @@ const agentLabels: Record<string, string> = {
   deepagents: "Deep Agents CLI",
   aider: "Aider",
   cursor: "Cursor CLI",
-  kiro: "Kiro",
-  cline: "Cline",
-  qoder: "Qoder",
+  kiro: "Kiro CLI",
+  cline: "Cline CLI",
+  qoder: "Qoder CLI",
+  hermes: "Hermes Agent",
 };
 
 export interface DetectedAgent {

package/src/agents/hermes.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 Hermes implements AgentTool {
+  supportsPermissions = false;
+  getPlanGenerationCommandLine(prompt: string): CommandLine {
+    return {
+      command: "hermes",
+      args: ["chat", "-q", 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 = ["chat"];
+
+    if (yolo) {
+      args.push("--trust-all-tools");
+    }
+    if (followupPrompt) {args.push("--continue");} // continue mode for followups
+    args.push("-q", prompt);
+
+    return { command: "hermes", args};
+  }
+
+  async init(): Promise<boolean> {
+    try {
+      execSync("hermes --version", { stdio: "ignore", shell: SHELL });
+    } catch {
+      return false;
+    }
+    return true;
+  }
+}

package/src/commands/plan-generation.md

@@ -16,6 +16,7 @@ task_name: <concise label, 3-6 words>
 - If the task produces formatted output (report, email, summary, etc.), specify the structure, sections, and tone.
 - When a step requires user input, simply state what information is needed from the user. Do **not** specify how to obtain it — the agent has its own tool for requesting user input.
 - Preserve relative time expressions (e.g., "today", "yesterday", "last week") exactly as written — do **not** resolve them to specific dates. The plan may be executed on a different day than it was generated.
+- If the task involves opening a web browser or application, include a final step to close it before finishing.
 
 ## Task Description