palmier 0.8.1 → 0.8.4

package/src/commands/run.ts

@@ -13,10 +13,6 @@ import { publishHostEvent } from "../events.js";
 import type { HostConfig, ParsedTask, TaskRunningState, RequiredPermission } from "../types.js";
 import type { NatsConnection } from "nats";
 
-/**
- * Shared context for agent invocation retry loops.
- * Passed around to avoid threading many individual parameters.
- */
 interface InvocationContext {
   agent: AgentTool;
   task: ParsedTask;
@@ -35,11 +31,9 @@ interface InvocationResult {
 }
 
 /**
- * Invoke the agent CLI with a continuation loop for permissions and user input.
- *
- * Both standard and command-triggered execution use this.
- * The `invokeTask` is the ParsedTask whose prompt is passed to the agent
- * (for command-triggered mode this is the per-line augmented task).
+ * Invoke the agent CLI in a continuation loop to handle permission requests.
+ * `invokeTask` is the ParsedTask whose prompt is passed to the agent (in
+ * command-triggered mode this is the per-line augmented task).
  */
 async function invokeAgentWithRetries(
   ctx: InvocationContext,
@@ -47,7 +41,6 @@ async function invokeAgentWithRetries(
 ): Promise<InvocationResult> {
   // eslint-disable-next-line no-constant-condition
   while (true) {
-    // Stream agent output to TASKRUN.md in real-time, throttled to 500ms
     const writer = beginStreamingMessage(ctx.taskDir, ctx.runId, Date.now());
     let lineBuf = "";
     let notifyPending = false;
@@ -89,12 +82,10 @@ async function invokeAgentWithRetries(
     const reportFiles = parseReportFiles(result.output);
     const requiredPermissions = parsePermissions(result.output);
 
-    // Flush remaining buffered content
     if (lineBuf && !lineBuf.startsWith("[PALMIER")) {
       writer.write(lineBuf);
     }
 
-    // Include permission requests in the assistant message
     if (requiredPermissions.length > 0) {
       const permLines = requiredPermissions.map((p) => `- **${p.name}** ${p.description}`).join("\n");
       writer.write(`\n\n**Permissions requested:**\n${permLines}\n`);
@@ -112,7 +103,6 @@ async function invokeAgentWithRetries(
       });
     }
 
-    // Permission handling — agent requested permissions
     if (requiredPermissions.length > 0) {
       const response = await requestPermission(ctx.config, ctx.task, ctx.taskDir, requiredPermissions);
 
@@ -146,27 +136,20 @@ async function invokeAgentWithRetries(
         ctx.transientPermissions = [...ctx.transientPermissions, ...newPerms];
       }
 
-      // If the agent actually failed, retry with the new permissions
+      // Retry with the new permissions if the agent failed.
       if (outcome === "failed") {
         continue;
       }
     }
 
-    // Normal completion (success or terminal failure)
     return { outcome };
   }
 }
 
-/**
- * Strip [PALMIER_*] marker lines from agent output.
- */
 export function stripPalmierMarkers(output: string): string {
   return output.split("\n").filter((l) => !l.startsWith("[PALMIER")).join("\n").trim();
 }
 
-/**
- * Append a conversation message to the RESULT file and notify connected clients.
- */
 async function appendAndNotify(
   ctx: InvocationContext,
   msg: Parameters<typeof appendRunMessage>[2],
@@ -175,9 +158,7 @@ async function appendAndNotify(
   await publishHostEvent(ctx.nc, ctx.config.hostId, ctx.taskId, { event_type: "result-updated", run_id: ctx.runId });
 }
 
-/**
- * Find the latest run dir that has no status messages yet (just created by the RPC handler).
- */
+/** The latest run dir with no status messages yet — freshly created by the RPC handler. */
 function findLatestPendingRunId(taskDir: string): string | null {
   const dirs = fs.readdirSync(taskDir)
     .filter((f) => /^\d+$/.test(f) && fs.existsSync(path.join(taskDir, f, "TASKRUN.md")))
@@ -190,8 +171,8 @@ function findLatestPendingRunId(taskDir: string): string | null {
 }
 
 /**
- * If the RPC handler already wrote "aborted" to status.json (e.g. via task.abort),
- * respect that instead of overwriting with the process's own outcome.
+ * If the RPC handler already wrote "aborted" (via task.abort), respect that
+ * instead of overwriting with the process's own outcome.
  */
 function resolveOutcome(taskDir: string, outcome: TaskRunningState): TaskRunningState {
   const current = readTaskStatus(taskDir);
@@ -199,9 +180,6 @@ function resolveOutcome(taskDir: string, outcome: TaskRunningState): TaskRunning
   return outcome;
 }
 
-/**
- * Execute a task by ID.
- */
 export async function runCommand(taskId: string): Promise<void> {
   const config = loadConfig();
   const taskDir = getTaskDir(config.projectRoot, taskId);
@@ -211,7 +189,6 @@ export async function runCommand(taskId: string): Promise<void> {
   let nc: NatsConnection | undefined;
   const taskName = task.frontmatter.name;
 
-  // Use existing run dir if just created by RPC, otherwise create a new one
   const existingRunId = findLatestPendingRunId(taskDir);
   const runId = existingRunId ?? createRunDir(taskDir, taskName, Date.now(), task.frontmatter.agent);
   if (!existingRunId) {
@@ -231,7 +208,6 @@ export async function runCommand(taskId: string): Promise<void> {
     appendRunMessage(taskDir, runId, { role: "status", time: Date.now(), content: "", type: "started" });
     await publishHostEvent(nc, config.hostId, taskId, { event_type: "result-updated", run_id: runId });
 
-    // If requires_confirmation, notify clients and wait
     if (task.frontmatter.requires_confirmation) {
       const confirmed = await requestConfirmation(config, task, taskDir);
       const confirmPrompt = `**Task Confirmation**\n\nRun task "${taskName || task.frontmatter.user_prompt}"?`;
@@ -252,7 +228,6 @@ export async function runCommand(taskId: string): Promise<void> {
       await publishHostEvent(nc, config.hostId, taskId, { event_type: "result-updated", run_id: runId });
     }
 
-    // Shared invocation context
     const guiEnv = getPlatform().getGuiEnv();
     const agent = getAgent(task.frontmatter.agent);
     const ctx: InvocationContext = {
@@ -261,7 +236,6 @@ export async function runCommand(taskId: string): Promise<void> {
     };
 
     if (task.frontmatter.command) {
-      // Command-triggered mode
       const result = await runCommandTriggeredMode(ctx);
       const outcome = resolveOutcome(taskDir, result.outcome);
       appendRunMessage(taskDir, runId, { role: "status", time: Date.now(), content: "", type: outcome });
@@ -269,14 +243,12 @@ export async function runCommand(taskId: string): Promise<void> {
       console.log(`Task ${taskId} completed (command-triggered).`);
     } else if (task.frontmatter.schedule_type === "on_new_notification"
                || task.frontmatter.schedule_type === "on_new_sms") {
-      // Event-triggered mode (driven by NATS pub/sub of device notifications/SMS)
       const result = await runEventTriggeredMode(ctx);
       const outcome = resolveOutcome(taskDir, result.outcome);
       appendRunMessage(taskDir, runId, { role: "status", time: Date.now(), content: "", type: outcome });
       await publishTaskEvent(nc, config, taskDir, taskId, outcome, taskName, runId);
       console.log(`Task ${taskId} completed (event-triggered).`);
     } else {
-      // Standard execution — add user prompt as first message
       await appendAndNotify(ctx, {
         role: "user",
         time: Date.now(),
@@ -312,11 +284,9 @@ const MAX_LOG_ENTRIES = 1000;
 const MAX_LINE_LENGTH = 200_000;
 
 /**
- * Command-triggered execution mode.
- *
- * Spawns a long-running shell command and, for each line of stdout,
- * invokes the agent CLI with the user's prompt augmented by that line.
- * Processes lines sequentially with a bounded queue.
+ * Spawn a long-running shell command and invoke the agent CLI once per stdout
+ * line, with the user's prompt augmented by that line. Sequential with a
+ * bounded queue.
  */
 async function runCommandTriggeredMode(
   ctx: InvocationContext,
@@ -346,7 +316,6 @@ async function runCommandTriggeredMode(
     const entry = `[${new Date().toISOString()}] (${outcome}) input: ${line}\n${agentOutput}\n---\n`;
     fs.appendFileSync(logPath, entry, "utf-8");
 
-    // Trim log if too large (keep last MAX_LOG_ENTRIES entries)
     try {
       const content = fs.readFileSync(logPath, "utf-8");
       const entries = content.split("\n---\n").filter(Boolean);
@@ -380,7 +349,7 @@ async function runCommandTriggeredMode(
     }
     appendLog(line, "", result.outcome);
 
-    // Append monitoring status so the UI shows the task is waiting for more input
+    // Signal "waiting for more input" in the UI.
     appendRunMessage(ctx.taskDir, ctx.runId, { role: "status", time: Date.now(), content: "", type: "monitoring" });
     await publishHostEvent(ctx.nc, ctx.config.hostId, ctx.taskId, { event_type: "result-updated", run_id: ctx.runId });
   }
@@ -422,7 +391,6 @@ async function runCommandTriggeredMode(
     process.stderr.write(d);
   });
 
-  // Wait for command to exit
   const exitCode = await new Promise<number | null>((resolve) => {
     child.on("close", (code: number | null) => {
       commandExited = true;
@@ -438,7 +406,6 @@ async function runCommandTriggeredMode(
     });
   });
 
-  // Wait for any remaining queued lines to finish processing
   if (lineQueue.length > 0 || processing) {
     await new Promise<void>((resolve) => {
       resolveWhenDone = resolve;
@@ -464,13 +431,10 @@ async function runCommandTriggeredMode(
 }
 
 /**
- * Event-triggered execution mode.
- *
- * Drains the daemon-owned per-task event queue via the local /task-event/pop
- * HTTP endpoint, invoking the agent once per event with the payload spliced
- * into the user prompt. The run process itself holds no NATS subscription;
- * the daemon handles that and atomically clears the active flag when we see
- * an empty pop, so it can fire up a fresh run on the next incoming event.
+ * Drain the daemon-owned per-task event queue via /task-event/pop, invoking
+ * the agent once per event. The run process holds no NATS subscription — the
+ * daemon owns that and atomically clears the active flag on empty pop so it
+ * can fire a fresh run on the next incoming event.
  */
 async function runEventTriggeredMode(
   ctx: InvocationContext,
@@ -590,10 +554,6 @@ async function requestConfirmation(
   return confirmed;
 }
 
-/**
- * Extract report file names from agent output.
- * Looks for lines matching: [PALMIER_REPORT] <filename>
- */
 const ALLOWED_REPORT_EXT = [".md", ".txt", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"];
 
 export function parseReportFiles(output: string): string[] {
@@ -602,7 +562,7 @@ export function parseReportFiles(output: string): string[] {
   let match;
   while ((match = regex.exec(output)) !== null) {
     const name = match[1].trim();
-    // Skip placeholder examples echoed from the prompt (e.g. "<filename>")
+    // Skip placeholder examples echoed from the prompt (e.g. "<filename>").
     if (!name || name.startsWith("<")) continue;
     const ext = name.lastIndexOf(".") >= 0 ? name.slice(name.lastIndexOf(".")).toLowerCase() : "";
     if (!ALLOWED_REPORT_EXT.includes(ext)) continue;
@@ -611,17 +571,13 @@ export function parseReportFiles(output: string): string[] {
   return files;
 }
 
-/**
- * Extract required permissions from agent output.
- * Looks for lines matching: [PALMIER_PERMISSION] <tool> | <description>
- */
 export function parsePermissions(output: string): RequiredPermission[] {
   const regex = new RegExp(`^\\${TASK_PERMISSION_PREFIX}\\s+(.+)$`, "gm");
   const perms: RequiredPermission[] = [];
   let match;
   while ((match = regex.exec(output)) !== null) {
     const raw = match[1].trim();
-    // Skip placeholder examples echoed from the prompt (e.g. "<tool_name> | <description>")
+    // Skip placeholder examples echoed from the prompt (e.g. "<tool_name> | <description>").
     if (raw.startsWith("<")) continue;
     const sep = raw.indexOf("|");
     if (sep !== -1) {
@@ -633,10 +589,7 @@ export function parsePermissions(output: string): RequiredPermission[] {
   return perms;
 }
 
-/**
- * Parse the agent's output for success/failure markers.
- * Falls back to "finished" if no marker is found.
- */
+/** Falls back to "finished" if no success/failure marker is found. */
 export function parseTaskOutcome(output: string): TaskRunningState {
   const lastChunk = output.slice(-500);
   const regex = new RegExp(`^\\${TASK_FAILURE_MARKER}$|^\\${TASK_SUCCESS_MARKER}$`, "gm");

package/src/commands/serve.ts

@@ -21,11 +21,8 @@ const POLL_INTERVAL_MS = 30_000;
 const DAEMON_PID_FILE = path.join(CONFIG_DIR, "daemon.pid");
 
 /**
- * Scan all tasks for any stuck in "started" state whose process is no longer alive.
- * Uses the system scheduler (Task Scheduler / systemd) as the authoritative source.
- *
- * Since run.ts creates the RESULT file and history entry at start, we just need to
- * finalize the existing RESULT file, append a failed status entry, and broadcast.
+ * Reconcile tasks stuck in "started" whose process is no longer alive.
+ * The system scheduler (Task Scheduler / systemd) is the authoritative source.
  */
 async function checkStaleTasks(
   config: HostConfig,
@@ -46,14 +43,12 @@ async function checkStaleTasks(
     const status = readTaskStatus(taskDir);
     if (!status || status.running_state !== "started") continue;
 
-    // Ask the system scheduler if the task is still running
     if (platform.isTaskRunning(taskId)) continue;
 
     console.log(`[monitor] Task ${taskId} process exited unexpectedly, marking as failed.`);
     const endTime = Date.now();
     writeTaskStatus(taskDir, { running_state: "failed", time_stamp: endTime });
 
-    // Find the latest run directory (created by run.ts at start)
     const runId = fs.readdirSync(taskDir)
       .filter((f) => /^\d+$/.test(f) && fs.existsSync(path.join(taskDir, f, "TASKRUN.md")))
       .sort()
@@ -71,7 +66,7 @@ async function checkStaleTasks(
     let taskName = taskId;
     try {
       taskName = parseTaskFile(taskDir).frontmatter.name || taskId;
-    } catch { /* use taskId as fallback */ }
+    } catch { /* fallback to taskId */ }
 
     await publishHostEvent(nc, config.hostId, taskId, {
       event_type: "running-state",
@@ -81,18 +76,14 @@ async function checkStaleTasks(
   }
 }
 
-/**
- * Start the persistent RPC handler (NATS + HTTP).
- */
 export async function serveCommand(): Promise<void> {
   const config = loadConfig();
 
-  // Write PID so `palmier restart` can find us regardless of how we were started
+  // PID file lets `palmier restart` find us regardless of how we were started
   fs.writeFileSync(DAEMON_PID_FILE, String(process.pid), "utf-8");
 
   console.log("Starting...");
 
-  // Re-detect agents on every daemon start
   const agents = await detectAgents();
   config.agents = agents;
   saveConfig(config);
@@ -106,10 +97,9 @@ export async function serveCommand(): Promise<void> {
     console.warn(`[nats] Connection failed (server mode unavailable): ${err}`);
   }
 
-  // Reconcile any tasks stuck from before daemon started
   await checkStaleTasks(config, nc);
 
-  // Ensure all tasks have their scheduler entries (recovery after init/reinstall)
+  // Reinstall scheduler entries for all tasks (recovery after init/reinstall)
   const platform = getPlatform();
   const allTasks = listTasks(config.projectRoot);
   for (const task of allTasks) {
@@ -120,7 +110,6 @@ export async function serveCommand(): Promise<void> {
     }
   }
 
-  // Poll for crashed tasks every 30 seconds
   setInterval(() => {
     checkStaleTasks(config, nc).catch((err) => {
       console.error("[monitor] Error checking stale tasks:", err);
@@ -130,18 +119,29 @@ export async function serveCommand(): Promise<void> {
   const handleRpc = createRpcHandler(config, nc);
   const httpPort = config.httpPort ?? 7256;
 
-  // Start NATS transport (loops forever, fire-and-forget)
   if (nc) {
     startNatsTransport(config, handleRpc, nc);
 
-    // Subscribe to device notifications and SMS from Android
     const sc = StringCodec();
 
-    // Dispatch a raw event payload to every task whose schedule matches.
-    function dispatchDeviceEvent(scheduleType: "on_new_notification" | "on_new_sms", payload: string): void {
+    // Match phone numbers regardless of formatting; letters preserved for shortcodes.
+    function normalizeSender(raw: string): string {
+      return raw.replace(/[\s\-()+]/g, "").toLowerCase();
+    }
+
+    function dispatchDeviceEvent(scheduleType: "on_new_notification" | "on_new_sms", payload: string, parsed?: unknown): void {
       for (const task of listTasks(config.projectRoot)) {
         if (task.frontmatter.schedule_type !== scheduleType) continue;
         if (!task.frontmatter.schedule_enabled) continue;
+        if (scheduleType === "on_new_notification" && task.frontmatter.schedule_values && task.frontmatter.schedule_values.length > 0) {
+          const pkg = (parsed as { packageName?: string } | undefined)?.packageName;
+          if (!pkg || !task.frontmatter.schedule_values.includes(pkg)) continue;
+        }
+        if (scheduleType === "on_new_sms" && task.frontmatter.schedule_values && task.frontmatter.schedule_values.length > 0) {
+          const sender = (parsed as { sender?: string } | undefined)?.sender;
+          const normalizedSender = sender ? normalizeSender(sender) : "";
+          if (!normalizedSender || !task.frontmatter.schedule_values.some((s) => normalizeSender(s) === normalizedSender)) continue;
+        }
         const { shouldStart } = enqueueEvent(task.frontmatter.id, payload);
         if (shouldStart) {
           platform.startTask(task.frontmatter.id).catch((err) => {
@@ -155,13 +155,14 @@ export async function serveCommand(): Promise<void> {
     (async () => {
       for await (const msg of notifSub) {
         const raw = sc.decode(msg.data);
+        let parsed: unknown;
         try {
-          const data = JSON.parse(raw);
-          addNotification({ ...data, receivedAt: Date.now() });
+          parsed = JSON.parse(raw);
+          addNotification({ ...(parsed as object), receivedAt: Date.now() } as Parameters<typeof addNotification>[0]);
         } catch (err) {
           console.error("[nats] Failed to parse device notification:", err);
         }
-        dispatchDeviceEvent("on_new_notification", raw);
+        dispatchDeviceEvent("on_new_notification", raw, parsed);
       }
     })();
 
@@ -169,17 +170,17 @@ export async function serveCommand(): Promise<void> {
     (async () => {
       for await (const msg of smsSub) {
         const raw = sc.decode(msg.data);
+        let parsed: unknown;
         try {
-          const data = JSON.parse(raw);
-          addSmsMessage({ ...data, receivedAt: Date.now() });
+          parsed = JSON.parse(raw);
+          addSmsMessage({ ...(parsed as object), receivedAt: Date.now() } as Parameters<typeof addSmsMessage>[0]);
         } catch (err) {
           console.error("[nats] Failed to parse device SMS:", err);
         }
-        dispatchDeviceEvent("on_new_sms", raw);
+        dispatchDeviceEvent("on_new_sms", raw, parsed);
       }
     })();
   }
 
-  // Start HTTP transport (loops forever)
   await startHttpTransport(config, handleRpc, httpPort, nc);
 }

package/src/config.ts

@@ -6,10 +6,6 @@ import type { HostConfig } from "./types.js";
 const CONFIG_DIR = path.join(homedir(), ".config", "palmier");
 const CONFIG_FILE = path.join(CONFIG_DIR, "host.json");
 
-/**
- * Load host configuration from ~/.config/palmier/host.json.
- * Throws if the file is missing or invalid.
- */
 export function loadConfig(): HostConfig {
   if (!fs.existsSync(CONFIG_FILE)) {
     throw new Error(
@@ -32,10 +28,6 @@ export function loadConfig(): HostConfig {
   return config;
 }
 
-/**
- * Persist host configuration to ~/.config/palmier/host.json.
- * Creates parent directories if needed.
- */
 export function saveConfig(config: HostConfig): void {
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
   fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");

package/src/device-capabilities.ts

@@ -12,10 +12,11 @@ export interface RegisteredDevice {
 export type DeviceCapability =
   | "location"
   | "notifications"
-  | "sms"
+  | "sms-read"
+  | "sms-send"
   | "contacts"
   | "calendar"
-  | "alert"
+  | "alarm"
   | "battery"
   | "send-email"
   | "dnd";

package/src/event-queues.ts

@@ -1,18 +1,12 @@
 /**
- * Per-task in-memory event queues for event-triggered schedules
- * (schedule_type: "on_new_notification" | "on_new_sms").
- *
+ * Per-task in-memory event queues for on_new_notification / on_new_sms schedules.
  * The daemon owns the NATS subscription and populates these queues; the
- * `palmier run` process drains them via the localhost /task-event/pop HTTP
- * endpoint. `activeRuns` tracks whether a run process is currently draining,
- * so we don't race a fresh startTask with a teardown-phase run.
+ * `palmier run` process drains via /task-event/pop.
  *
- * Lifecycle invariants:
- *   - activeRuns is cleared atomically inside popEvent when the queue is
- *     drained. At that point the calling run has already finished its last
- *     agent invocation and is only tearing down.
- *   - enqueueEvent returns shouldStart=true only if the task transitioned
- *     from idle (no active run) to active — callers must then startTask.
+ * Invariants:
+ *   - popEvent clears activeRuns atomically when the queue empties, so a
+ *     fresh startTask cannot race the tearing-down run.
+ *   - enqueueEvent returns shouldStart=true only on the idle→active edge.
  */
 
 const MAX_QUEUE_SIZE = 100;
@@ -20,10 +14,6 @@ const MAX_QUEUE_SIZE = 100;
 const queues = new Map<string, string[]>();
 const activeRuns = new Set<string>();
 
-/**
- * Queue a raw (JSON-string) event payload for a task. Returns whether the
- * caller should now start the run process.
- */
 export function enqueueEvent(taskId: string, payload: string): { shouldStart: boolean } {
   const queue = queues.get(taskId) ?? [];
   if (queue.length >= MAX_QUEUE_SIZE) queue.shift();
@@ -35,11 +25,6 @@ export function enqueueEvent(taskId: string, payload: string): { shouldStart: bo
   return { shouldStart: true };
 }
 
-/**
- * Pop the oldest queued event for a task. Returns `{ event }` when one is
- * available (keeps the task marked active), or `{ empty: true }` after
- * clearing the active flag atomically.
- */
 export function popEvent(taskId: string): { event: string } | { empty: true } {
   const queue = queues.get(taskId);
   if (queue && queue.length > 0) {

package/src/events.ts

@@ -3,12 +3,6 @@ import { loadConfig } from "./config.js";
 
 const sc = StringCodec();
 
-/**
- * Broadcast an event to connected clients via NATS and HTTP SSE.
- *
- * - NATS: publishes to `host-event.{hostId}.{taskId}`
- * - HTTP: POSTs to the serve daemon's `/event` endpoint
- */
 export async function publishHostEvent(
   nc: NatsConnection | undefined,
   hostId: string,
@@ -31,7 +25,5 @@ export async function publishHostEvent(
       body: JSON.stringify({ task_id: taskId, ...payload }),
     });
     console.log(`[http] host-event: ${taskId} →`, payload);
-  } catch {
-    // Serve HTTP may not be ready yet — ignore
-  }
+  } catch { /* serve HTTP may not be ready yet */ }
 }

package/src/index.ts

@@ -101,7 +101,6 @@ program
     await uninstallCommand();
   });
 
-// No subcommand → default to serve
 if (process.argv.length <= 2) {
   process.argv.push("serve");
 }

package/src/mcp-handler.ts

@@ -15,14 +15,13 @@ export interface McpResponse {
   stream?: boolean;
 }
 
-// Resource subscriptions: sessionId → Set of resource URIs
+/** sessionId → subscribed resource URIs */
 const resourceSubscriptions = new Map<string, Set<string>>();
 
 export function getResourceSubscriptions(): Map<string, Set<string>> {
   return resourceSubscriptions;
 }
 
-// Session-to-agent name map with 24h TTL
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
 const sessionAgents = new Map<string, { agentName: string; expiresAt: number }>();
 

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));
@@ -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;
 }