palmier 0.8.0 → 0.8.3

package/src/mcp-tools.ts

@@ -462,8 +462,8 @@ const sendSmsTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("sms");
-    if (!device) throw new ToolError("No device has SMS access enabled", 400);
+    const device = getCapabilityDevice("sms-send");
+    if (!device) throw new ToolError("No device has SMS Send enabled", 400);
 
     const { to, body } = args as { to: string; body: string };
     if (!to || !body) throw new ToolError("to and body are required", 400);
@@ -502,10 +502,10 @@ const sendSmsTool: ToolDefinition = {
   },
 };
 
-const sendAlertTool: ToolDefinition = {
-  name: "send-alert",
+const sendAlarmTool: ToolDefinition = {
+  name: "send-alarm",
   description: [
-    "Send an alert to the user's mobile device with an alarm sound and full-screen popup.",
+    "Trigger an alarm on the user's mobile device with an alarm sound and full-screen popup.",
     "Use this to urgently get the user's attention. The device will play an alarm sound and show a full-screen dialog even on the lock screen.",
     "Blocks until the device responds (up to 30 seconds).",
     'Response: `{"ok": true}` on success, or `{"error": "..."}` on failure.',
@@ -513,16 +513,16 @@ const sendAlertTool: ToolDefinition = {
   inputSchema: {
     type: "object",
     properties: {
-      title: { type: "string", description: "Alert title" },
-      description: { type: "string", description: "Alert description/details" },
+      title: { type: "string", description: "Alarm title" },
+      description: { type: "string", description: "Alarm description/details" },
     },
     required: ["title"],
   },
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("alert");
-    if (!device) throw new ToolError("No device has alert access enabled", 400);
+    const device = getCapabilityDevice("alarm");
+    if (!device) throw new ToolError("No device has alarm access enabled", 400);
 
     const { title, description } = args as { title: string; description?: string };
     if (!title) throw new ToolError("title is required", 400);
@@ -536,7 +536,7 @@ const sendAlertTool: ToolDefinition = {
     if (description) payload.description = description;
 
     const ackReply = await ctx.nc.request(
-      `host.${ctx.config.hostId}.fcm.alert`,
+      `host.${ctx.config.hostId}.fcm.alarm`,
       sc.encode(JSON.stringify(payload)),
       { timeout: 5_000 },
     );
@@ -544,7 +544,7 @@ const sendAlertTool: ToolDefinition = {
     if (ack.error) throw new ToolError(ack.error, 502);
 
     const responsePromise = new Promise<string>((resolve, reject) => {
-      const sub = ctx.nc!.subscribe(`host.${ctx.config.hostId}.alert.${ctx.sessionId}`, { max: 1 });
+      const sub = ctx.nc!.subscribe(`host.${ctx.config.hostId}.alarm.${ctx.sessionId}`, { max: 1 });
       const timer = setTimeout(() => {
         sub.unsubscribe();
         reject(new ToolError("Device did not respond within 30 seconds", 504));
@@ -687,8 +687,8 @@ const sendEmailTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("email");
-    if (!device) throw new ToolError("No device has email access enabled", 400);
+    const device = getCapabilityDevice("send-email");
+    if (!device) throw new ToolError("No device has send-email access enabled", 400);
 
     const { to, subject, body, cc, bcc } = args as { to: string; subject?: string; body?: string; cc?: string; bcc?: string };
     if (!to) throw new ToolError("to is required", 400);
@@ -733,11 +733,9 @@ const sendEmailTool: ToolDefinition = {
   },
 };
 
-export const agentTools: ToolDefinition[] = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool, readContactsTool, createContactTool, readCalendarTool, createCalendarEventTool, sendSmsTool, sendEmailTool, sendAlertTool, readBatteryTool, setRingerModeTool];
+export const agentTools: ToolDefinition[] = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool, readContactsTool, createContactTool, readCalendarTool, createCalendarEventTool, sendSmsTool, sendEmailTool, sendAlarmTool, readBatteryTool, setRingerModeTool];
 export const agentToolMap = new Map<string, ToolDefinition>(agentTools.map((t) => [t.name, t]));
 
-// ── MCP Resources ─────────────────────────────────────────────────────
-
 export interface ResourceDefinition {
   /** MCP resource URI (e.g. "notifications://device"). */
   uri: string;
@@ -783,9 +781,6 @@ const deviceSmsResource: ResourceDefinition = {
 export const agentResources: ResourceDefinition[] = [deviceNotificationsResource, deviceSmsResource];
 export const agentResourceMap = new Map<string, ResourceDefinition>(agentResources.map((r) => [r.uri, r]));
 
-/**
- * Generate the HTTP Endpoints markdown section for agent-instructions.md from the tool registry.
- */
 export function generateEndpointDocs(
   port: number,
   taskId: string,
@@ -803,7 +798,6 @@ export function generateEndpointDocs(
     const props = schema.properties ?? {};
     const required = new Set(schema.required ?? []);
 
-    // Build example JSON (body only, no taskId)
     const example: Record<string, unknown> = {};
     for (const [key, prop] of Object.entries(props)) {
       if (prop.type === "array") example[key] = ["..."];

package/src/nats-client.ts

@@ -1,9 +1,6 @@
 import { connect, jwtAuthenticator, type NatsConnection } from "nats";
 import type { HostConfig } from "./types.js";
 
-/**
- * Connect to NATS using the host config's JWT credentials.
- */
 export async function connectNats(config: HostConfig): Promise<NatsConnection> {
   if (!config.natsJwt || !config.natsNkeySeed) {
     throw new Error("NATS JWT credentials not configured. Re-run palmier init.");
@@ -17,6 +14,6 @@ export async function connectNats(config: HostConfig): Promise<NatsConnection> {
     ),
   });
 
-  // Do not log anything as that will pollute stdout for mcp server.
+  // Do not log — it would pollute stdout for the MCP server.
   return nc;
 }

package/src/pending-requests.ts

@@ -22,10 +22,9 @@ export interface PendingRequest {
 const pending = new Map<string, PendingRequest>();
 
 /**
- * Register a pending request keyed by either a sessionId (confirmation / input)
- * or a taskId (permission). The `meta` is surfaced to PWAs that connect after
- * the request was opened, so their modals can render without replaying events.
- * Only one pending request per key at a time.
+ * Key is sessionId for confirmation/input, taskId for permission. Only one
+ * pending request per key at a time. `meta` is surfaced via host.info so a
+ * freshly-connected PWA can render the modal without replaying events.
  */
 export function registerPending(
   key: string,
@@ -42,10 +41,6 @@ export function registerPending(
   });
 }
 
-/**
- * Resolve a pending request with the user's response.
- * Returns true if a pending request was found and resolved.
- */
 export function resolvePending(key: string, value: string[]): boolean {
   const entry = pending.get(key);
   if (!entry) return false;
@@ -54,24 +49,15 @@ export function resolvePending(key: string, value: string[]): boolean {
   return true;
 }
 
-/**
- * Get the current pending request for a key (if any).
- */
 export function getPending(key: string): PendingRequest | undefined {
   return pending.get(key);
 }
 
-/**
- * Remove a pending request without resolving it.
- */
 export function removePending(key: string): void {
   pending.delete(key);
 }
 
-/**
- * List all currently-pending requests, stripped of the unserializable `resolve`
- * callback. Used by `host.info` so the PWA can seed its modal state on connect.
- */
+/** Pending requests stripped of the unserializable `resolve` callback. */
 export function listPending(): Array<{
   key: string;
   type: PendingRequest["type"];

package/src/platform/index.ts

@@ -2,10 +2,7 @@ import type { PlatformService } from "./platform.js";
 import { LinuxPlatform } from "./linux.js";
 import { WindowsPlatform } from "./windows.js";
 
-/**
- * On Windows, execSync needs an explicit shell so .cmd shims resolve correctly.
- * On Unix, undefined lets Node use the default shell.
- */
+/** Windows needs an explicit shell for execSync to resolve .cmd shims. */
 export const SHELL: string | undefined = process.platform === "win32" ? "cmd.exe" : undefined;
 
 let _instance: PlatformService | undefined;

package/src/platform/linux.ts

@@ -22,15 +22,9 @@ function getServiceName(taskId: string): string {
 }
 
 /**
- * Convert a cron expression to a systemd OnCalendar string.
- *
- * Only the 4 cron patterns the PWA UI can produce are supported:
- *   hourly:  "0 * * * *"
- *   daily:   "MM HH * * *"
- *   weekly:  "MM HH * * D"
- *   monthly: "MM HH D * *"
- * Arbitrary cron expressions (ranges, lists, steps beyond hourly) are NOT
- * handled because the UI never generates them.
+ * Only the 4 cron patterns the PWA UI produces are supported:
+ *   hourly "0 * * * *", daily "MM HH * * *", weekly "MM HH * * D", monthly "MM HH D * *".
+ * Arbitrary expressions (ranges, lists, sub-hour steps) are not handled.
  */
 export function cronToOnCalendar(cron: string): string {
   const parts = cron.trim().split(/\s+/);
@@ -40,7 +34,6 @@ export function cronToOnCalendar(cron: string): string {
 
   const [minute, hour, dayOfMonth, , dayOfWeek] = parts;
 
-  // Map cron day-of-week numbers to systemd abbreviated names
   const dowMap: Record<string, string> = {
     "0": "Sun", "1": "Mon", "2": "Tue", "3": "Wed",
     "4": "Thu", "5": "Fri", "6": "Sat", "7": "Sun",
@@ -73,8 +66,8 @@ export class LinuxPlatform implements PlatformService {
     fs.mkdirSync(UNIT_DIR, { recursive: true });
 
     const palmierBin = process.argv[1] || "palmier";
-    // Save the user's shell PATH so restartDaemon can use it later
-    // (the daemon itself runs under systemd with a limited PATH).
+    // Save the user's shell PATH so restartDaemon can reuse it later — under
+    // systemd the daemon itself runs with a limited PATH.
     const userPath = process.env.PATH || "/usr/local/bin:/usr/bin:/bin";
     fs.mkdirSync(path.dirname(PATH_FILE), { recursive: true });
     fs.writeFileSync(PATH_FILE, userPath, "utf-8");
@@ -110,7 +103,7 @@ WantedBy=default.target
       console.error("You may need to start it manually: systemctl --user enable --now palmier.service");
     }
 
-    // Enable lingering so service runs without active login session
+    // Lingering lets the service run without an active login session.
     try {
       execSync(`loginctl enable-linger ${process.env.USER || ""}`, { stdio: "inherit" });
       console.log("Login lingering enabled.");
@@ -127,11 +120,9 @@ WantedBy=default.target
       execSync("systemctl --user disable palmier.service 2>/dev/null", { stdio: "pipe" });
     } catch { /* service may not exist */ }
 
-    // Remove daemon service file
     const servicePath = path.join(UNIT_DIR, "palmier.service");
     try { fs.unlinkSync(servicePath); } catch { /* ignore */ }
 
-    // Remove all task timers and services
     try {
       const files = fs.readdirSync(UNIT_DIR).filter((f) => f.startsWith("palmier-task-"));
       for (const f of files) {
@@ -148,8 +139,8 @@ WantedBy=default.target
   }
 
   async restartDaemon(): Promise<void> {
-    // If called from a user's terminal, save the current PATH for future use.
-    // If called from the daemon (auto-update), read the saved PATH instead.
+    // From a TTY, snapshot the current PATH; from the daemon (auto-update),
+    // reuse whatever was last saved.
     if (process.stdin.isTTY) {
       fs.mkdirSync(path.dirname(PATH_FILE), { recursive: true });
       fs.writeFileSync(PATH_FILE, process.env.PATH || "", "utf-8");
@@ -196,7 +187,6 @@ Environment=PATH=${process.env.PATH || "/usr/local/bin:/usr/bin:/bin"}
     fs.writeFileSync(path.join(UNIT_DIR, serviceName), serviceContent, "utf-8");
     daemonReload();
 
-    // Only create and enable a timer if the schedule exists and is enabled
     if (!task.frontmatter.schedule_enabled) return;
     const scheduleType = task.frontmatter.schedule_type;
     const scheduleValues = task.frontmatter.schedule_values;
@@ -260,7 +250,6 @@ WantedBy=timers.target
   }
 
   isTaskRunning(taskId: string): boolean {
-    // Check systemd first (for scheduled/on-demand runs)
     const serviceName = getServiceName(taskId);
     try {
       const out = execSync(
@@ -271,7 +260,7 @@ WantedBy=timers.target
       if (state === "active" || state === "activating") return true;
     } catch { /* service may not exist */ }
 
-    // Fall back to PID check (for follow-up runs spawned directly)
+    // Follow-up runs are spawned directly, so check PID too.
     try {
       const taskDir = getTaskDir(loadConfig().projectRoot, taskId);
       const status = readTaskStatus(taskDir);

package/src/platform/platform.ts

@@ -1,9 +1,6 @@
 import type { HostConfig, ParsedTask } from "../types.js";
 
-/**
- * Abstracts OS-specific daemon, scheduling, and process management.
- * Linux uses systemd; Windows uses Task Scheduler; macOS will use launchd.
- */
+/** Linux: systemd. Windows: Task Scheduler. macOS: launchd (planned). */
 export interface PlatformService {
   /** Install the main `palmier serve` daemon to start at boot. */
   installDaemon(config: HostConfig): void;

package/src/platform/windows.ts

@@ -33,32 +33,25 @@ export function scheduleValueToXml(scheduleType: "crons" | "specific_times", val
   if (parts.length !== 5) throw new Error(`Invalid cron expression: ${value}`);
   const [minute, hour, dayOfMonth, , dayOfWeek] = parts;
   const st = `${hour.padStart(2, "0")}:${minute.padStart(2, "0")}:00`;
-  // StartBoundary needs a full date; use a past date as the anchor
+  // StartBoundary needs a full date; anchor to a past one.
   const base = `2000-01-01T${st}`;
 
-  // Hourly
   if (hour === "*") {
     return `<TimeTrigger><StartBoundary>${base}</StartBoundary><Repetition><Interval>PT1H</Interval></Repetition></TimeTrigger>`;
   }
 
-  // Weekly
   if (dayOfMonth === "*" && dayOfWeek !== "*") {
     const day = DOW_NAMES[Number(dayOfWeek)] ?? "Monday";
     return `<CalendarTrigger><StartBoundary>${base}</StartBoundary><ScheduleByWeek><DaysOfWeek><${day} /></DaysOfWeek><WeeksInterval>1</WeeksInterval></ScheduleByWeek></CalendarTrigger>`;
   }
 
-  // Monthly
   if (dayOfMonth !== "*" && dayOfWeek === "*") {
     return `<CalendarTrigger><StartBoundary>${base}</StartBoundary><ScheduleByMonth><DaysOfMonth><Day>${dayOfMonth}</Day></DaysOfMonth><Months><January /><February /><March /><April /><May /><June /><July /><August /><September /><October /><November /><December /></Months></ScheduleByMonth></CalendarTrigger>`;
   }
 
-  // Daily
   return `<CalendarTrigger><StartBoundary>${base}</StartBoundary><ScheduleByDay><DaysInterval>1</DaysInterval></ScheduleByDay></CalendarTrigger>`;
 }
 
-/**
- * Build a complete Task Scheduler XML definition.
- */
 export function buildTaskXml(tr: string, triggers: string[], foreground?: boolean): string {
   const [command, ...argParts] = tr.match(/"[^"]*"|[^\s]+/g) ?? [];
   const commandStr = command?.replace(/"/g, "") ?? "";
@@ -98,10 +91,7 @@ export class WindowsPlatform implements PlatformService {
   installDaemon(config: HostConfig): void {
     const script = process.argv[1] || "palmier";
 
-    // Create the Task Scheduler entry for the daemon (BootTrigger starts it at system boot)
     this.ensureDaemonTask(script);
-
-    // Start the daemon now
     this.startDaemonTask();
 
     console.log("\nHost initialization complete!");
@@ -110,12 +100,11 @@ export class WindowsPlatform implements PlatformService {
   uninstallDaemon(): void {
     const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
 
-    // Stop the daemon via Task Scheduler
     try {
       execFileSync("schtasks", ["/end", "/tn", tn], { encoding: "utf-8", windowsHide: true, stdio: "pipe" });
     } catch { /* task may not be running */ }
 
-    // Remove daemon scheduled task (elevated — S4U task requires elevation to delete)
+    // Deleting an S4U task requires elevation.
     try {
       execFileSync("powershell", [
         "-Command", `Start-Process -Verb RunAs -Wait -FilePath schtasks -ArgumentList '/delete /tn "${tn}" /f'`,
@@ -123,7 +112,6 @@ export class WindowsPlatform implements PlatformService {
       console.log("Daemon task removed.");
     } catch { /* task may not exist */ }
 
-    // Remove all Palmier task timers
     try {
       const out = execFileSync("schtasks", ["/query", "/fo", "CSV", "/nh"], { encoding: "utf-8", windowsHide: true, stdio: "pipe" });
       for (const line of out.split("\n")) {
@@ -142,16 +130,14 @@ export class WindowsPlatform implements PlatformService {
   async restartDaemon(): Promise<void> {
     const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
 
-    // Stop the daemon via Task Scheduler
     try {
       execFileSync("schtasks", ["/end", "/tn", tn], { encoding: "utf-8", windowsHide: true, stdio: "pipe" });
     } catch { /* task may not be running */ }
 
-    // Start it again
     this.startDaemonTask();
   }
 
-  /** Create or update the Task Scheduler entry for the daemon (requires elevation for S4U). */
+  /** S4U LogonType requires elevation to create. */
   private ensureDaemonTask(script: string): void {
     const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
     const tr = `"${process.execPath}" "${script}" serve`;
@@ -160,7 +146,7 @@ export class WindowsPlatform implements PlatformService {
     try {
       const bom = Buffer.from([0xFF, 0xFE]);
       fs.writeFileSync(xmlPath, Buffer.concat([bom, Buffer.from(xml, "utf16le")]));
-      // S4U LogonType requires elevation — spawn schtasks via RunAs
+      // S4U requires elevation — spawn schtasks via RunAs.
       const args = `/create /tn "${tn}" /xml "${xmlPath}" /f`;
       execFileSync("powershell", [
         "-Command", `Start-Process -Verb RunAs -Wait -FilePath schtasks -ArgumentList '${args}'`,
@@ -174,7 +160,7 @@ export class WindowsPlatform implements PlatformService {
 
   }
 
-  /** Start the daemon via Task Scheduler (runs outside any session's job object). */
+  /** Starting via Task Scheduler runs the daemon outside any session's job object. */
   private startDaemonTask(): void {
     const tn = `\\Palmier\\${DAEMON_TASK_NAME}`;
     try {
@@ -192,9 +178,8 @@ export class WindowsPlatform implements PlatformService {
     const script = process.argv[1] || "palmier";
     const tr = `"${process.execPath}" "${script}" run ${taskId}`;
 
-    // Build trigger XML elements. Event-based schedule types (on_new_notification,
-    // on_new_sms) carry no values and are driven by the run process, not the OS
-    // scheduler — they intentionally produce only the dummy trigger below.
+    // Event-based schedule types (on_new_notification/on_new_sms) are driven by
+    // the run process, not the OS scheduler — they fall through to the dummy trigger.
     const triggerElements: string[] = [];
     const scheduleType = task.frontmatter.schedule_type;
     const scheduleValues = task.frontmatter.schedule_values;
@@ -208,19 +193,19 @@ export class WindowsPlatform implements PlatformService {
         }
       }
     }
-    // Always include a dummy trigger so startTask (/run) works
+    // Dummy trigger so schtasks /run still works.
     if (triggerElements.length === 0) {
       triggerElements.push(`<TimeTrigger><StartBoundary>2000-01-01T00:00:00</StartBoundary></TimeTrigger>`);
     }
 
-    // Write XML and register via schtasks — gives us full control over
-    // settings like MultipleInstancesPolicy that schtasks flags don't expose.
-    // S4U LogonType ensures no console window (unless foreground_mode is set).
-    // Works without elevation because the daemon (which calls this) runs elevated.
+    // XML registration (vs schtasks flags) gives us access to settings like
+    // MultipleInstancesPolicy. S4U keeps the console hidden unless
+    // foreground_mode is set. Works unelevated because the caller (daemon)
+    // runs elevated.
     const xml = buildTaskXml(tr, triggerElements, task.frontmatter.foreground_mode);
     const xmlPath = path.join(CONFIG_DIR, `task-${taskId}.xml`);
     try {
-      // schtasks /xml requires UTF-16LE with BOM
+      // schtasks /xml requires UTF-16LE with BOM.
       const bom = Buffer.from([0xFF, 0xFE]);
       fs.writeFileSync(xmlPath, Buffer.concat([bom, Buffer.from(xml, "utf16le")]));
       execFileSync("schtasks", [
@@ -239,9 +224,7 @@ export class WindowsPlatform implements PlatformService {
     const tn = schtasksTaskName(taskId);
     try {
       execFileSync("schtasks", ["/delete", "/tn", tn, "/f"], { encoding: "utf-8", windowsHide: true });
-    } catch {
-      // Task might not exist — that's fine
-    }
+    } catch { /* task may not exist */ }
   }
 
   async startTask(taskId: string): Promise<void> {
@@ -255,8 +238,8 @@ export class WindowsPlatform implements PlatformService {
   }
 
   async stopTask(taskId: string): Promise<void> {
-    // Try to kill the entire process tree via the PID recorded in status.json.
-    // schtasks /end only kills the top-level process, leaving agent children orphaned.
+    // schtasks /end leaves agent children orphaned, so kill the process tree
+    // via the PID recorded in status.json first.
     try {
       const taskDir = getTaskDir(loadConfig().projectRoot, taskId);
       const status = readTaskStatus(taskDir);
@@ -265,10 +248,9 @@ export class WindowsPlatform implements PlatformService {
         return;
       }
     } catch {
-      // PID may be stale or config unavailable; fall through to schtasks /end
+      // PID may be stale or config unavailable; fall through to schtasks /end.
     }
 
-    // Fallback: schtasks /end (kills top-level process only)
     const tn = schtasksTaskName(taskId);
     try {
       execFileSync("schtasks", ["/end", "/tn", tn], { encoding: "utf-8", windowsHide: true });
@@ -279,7 +261,6 @@ export class WindowsPlatform implements PlatformService {
   }
 
   isTaskRunning(taskId: string): boolean {
-    // Check Task Scheduler first (for scheduled/on-demand runs)
     const tn = schtasksTaskName(taskId);
     try {
       const out = execFileSync("schtasks", ["/query", "/tn", tn, "/fo", "CSV", "/nh"], {
@@ -289,18 +270,17 @@ export class WindowsPlatform implements PlatformService {
       if (out.includes('"Running"')) return true;
     } catch { /* task may not exist in scheduler */ }
 
-    // Fall back to PID check (for follow-up runs spawned directly, not via schtasks)
+    // Follow-up runs are spawned directly (not via schtasks), so check PID too.
     try {
       const taskDir = getTaskDir(loadConfig().projectRoot, taskId);
       const status = readTaskStatus(taskDir);
       if (status?.pid) {
-        // tasklist exits 0 if the PID is found
         execFileSync("tasklist", ["/fi", `PID eq ${status.pid}`, "/nh"], {
           encoding: "utf-8",
           windowsHide: true,
           stdio: "pipe",
         });
-        // tasklist always exits 0; check if output contains the PID
+        // tasklist always exits 0, so match the output for the PID.
         const out = execFileSync("tasklist", ["/fi", `PID eq ${status.pid}`, "/fo", "CSV", "/nh"], {
           encoding: "utf-8",
           windowsHide: true,
@@ -314,7 +294,6 @@ export class WindowsPlatform implements PlatformService {
   }
 
   getGuiEnv(): Record<string, string> {
-    // Windows GUI is always available — no special env vars needed
     return {};
   }
 }