palmier 0.8.1 → 0.8.3

package/CLAUDE.md

@@ -7,3 +7,16 @@ Always read `README.md` first before starting any task.
 ## Documentation
 
 When making architectural changes, update `README.md` to reflect the new state.
+
+## Code comments
+
+Default: write no comments. Well-named identifiers already explain WHAT.
+
+Only add a comment when the WHY is non-obvious and would confuse a future reader without it — a hidden constraint, a subtle invariant, a workaround for a specific bug, or behavior that would surprise someone reading the code cold.
+
+Keep comments timeless:
+- Don't reference callers, task names, PRs, issue numbers, or "used by X". That context belongs in commit messages and PR descriptions, and rots as the codebase evolves.
+- Don't narrate the current change ("added for the Y flow", "removed ...").
+- Don't restate type signatures or function names in prose.
+
+When a comment earns its place, keep it short — one or two lines is almost always enough. If a block of code needs a paragraph to explain, consider whether the code itself should be clearer.

package/README.md

@@ -34,7 +34,7 @@ It runs on your machine as a background daemon and connects to a mobile-friendly
 
 ## How It Works
 
-Palmier runs as a background daemon (systemd on Linux, Task Scheduler on Windows). It invokes your agent CLIs directly, schedules tasks via native OS timers, and exposes an API that the PWA connects to — either directly over HTTP or remotely through a relay server. Agents can interact with the user's mobile device during execution — requesting input, sending push notifications, reading SMS/notifications, managing contacts and calendar, setting alarms, and more.
+Palmier runs as a background daemon (systemd on Linux, Task Scheduler on Windows). It invokes your agent CLIs directly, schedules tasks via native OS timers, and exposes an API that the PWA connects to — either directly over HTTP or remotely through a relay server. Agents can interact with the user's mobile device during execution — requesting input, sending push notifications and full-screen alarms, reading SMS/notifications, managing contacts and calendar, and more.
 
 ### MCP Server
 
@@ -48,21 +48,21 @@ Palmier exposes an [MCP](https://modelcontextprotocol.io) server at `http://loca
 | `notify` | Send a push notification to the user's device | None |
 | `request-input` | Request input from the user (blocks until response) | None |
 | `request-confirmation` | Request confirmation from the user (blocks until response) | None |
-| `device-geolocation` | Get GPS location of the user's mobile device | Location Access |
-| `read-contacts` | Read the contact list from the user's device | Contacts Access |
-| `create-contact` | Create a new contact on the user's device | Contacts Access |
-| `read-calendar` | Read calendar events (with time range filter) | Calendar Access |
-| `create-calendar-event` | Create a calendar event on the user's device | Calendar Access |
-| `send-sms-message` | Send an SMS message from the user's device | SMS Access |
-| `set-alarm` | Set an alarm on the user's device | None |
+| `device-geolocation` | Get GPS location of the user's mobile device | Get Location |
+| `read-contacts` | Read the contact list from the user's device | Manage Contacts |
+| `create-contact` | Create a new contact on the user's device | Manage Contacts |
+| `read-calendar` | Read calendar events (with time range filter) | Manage Calendar |
+| `create-calendar-event` | Create a calendar event on the user's device | Manage Calendar |
+| `send-sms-message` | Send an SMS message from the user's device | Send SMS |
+| `send-alarm` | Trigger a full-screen alarm popup with ringtone on the user's device (pierces DND) | Trigger Alarms |
 | `read-battery` | Get battery level and charging status | None |
-| `set-ringer-mode` | Set ringer mode (normal/vibrate/silent) | Do Not Disturb Control |
+| `set-ringer-mode` | Set ringer mode (normal/vibrate/silent) | Set Ringer Mode |
 
 **Available resources:**
 | Resource | URI | Permission | Description |
 |----------|-----|------------|-------------|
-| Device Notifications | `notifications://device` | Notification Access | Recent notifications from the user's Android device |
-| Device SMS | `sms-messages://device` | SMS Access | Recent SMS messages from the user's Android device |
+| Device Notifications | `notifications://device` | Read Notifications | Recent notifications from the user's Android device |
+| Device SMS | `sms-messages://device` | Read SMS | Recent SMS messages from the user's Android device |
 
 Resources support MCP subscriptions — clients can subscribe via `resources/subscribe` and receive real-time `notifications/resources/updated` events via the streamable HTTP transport when the resource changes.
 

package/dist/agents/agent.d.ts

@@ -7,10 +7,6 @@ export interface CommandLine {
     /** Additional environment variables to set for the spawned process. */
     env?: Record<string, string>;
 }
-/**
- * Interface that each agent tool must implement.
- * Abstracts how plans are generated and tasks are executed across different AI agents.
- */
 export interface AgentTool {
     /** Return the command and args for a short, non-interactive prompt (e.g. generating a task name). */
     getPromptCommandLine(prompt: string): CommandLine;

package/dist/agents/claude.js

@@ -20,7 +20,7 @@ export class ClaudeAgent {
         }
         if (followupPrompt) {
             args.push("-c");
-        } // continue mode for followups
+        }
         return { command: "claude", args, stdin: prompt };
     }
     async init() {

package/dist/agents/codex.js

@@ -20,8 +20,8 @@ export class CodexAgent {
         }
         if (followupPrompt) {
             args.push("resume", "--last");
-        } // continue mode for followups
-        args.push("-"); // read prompt from stdin
+        }
+        args.push("-");
         return { command: "codex", args, stdin: prompt };
     }
     async init() {

package/dist/agents/cursor.js

@@ -16,7 +16,7 @@ export class Cursor {
         }
         if (followupPrompt) {
             args.push("--continue");
-        } // continue mode for followups
+        }
         args.push("-p", prompt);
         return { command: "cursor", args };
     }

package/dist/agents/deepagents.js

@@ -16,7 +16,7 @@ export class DeepAgents {
         }
         if (followupPrompt) {
             args.push("--resume");
-        } // continue mode for followups
+        }
         args.push("--non-interactive", prompt);
         return { command: "deepagents", args };
     }

package/dist/agents/gemini.js

@@ -21,8 +21,9 @@ export class GeminiAgent {
         }
         if (followupPrompt) {
             args.push("--resume");
-        } // continue mode for followups
-        args.push("--prompt", "-"); // read prompt from stdin to avoid command line length limits
+        }
+        // Read prompt from stdin to avoid command-line length limits.
+        args.push("--prompt", "-");
         return { command: "gemini", args, stdin: prompt };
     }
     async init() {

package/dist/agents/goose.js

@@ -13,7 +13,7 @@ export class GooseAgent {
         const args = ["run"];
         if (followupPrompt) {
             args.push("--resume");
-        } // continue mode for followups
+        }
         args.push("--text", prompt);
         return { command: "goose", args, ...(yolo ? { env: { GOOSE_MODE: "auto" } } : {}) };
     }

package/dist/agents/hermes.js

@@ -16,7 +16,7 @@ export class Hermes {
         }
         if (followupPrompt) {
             args.push("--continue");
-        } // continue mode for followups
+        }
         args.push("-q", prompt);
         return { command: "hermes", args };
     }

package/dist/agents/kiro.js

@@ -16,7 +16,7 @@ export class Kiro {
         }
         if (followupPrompt) {
             args.push("--resume");
-        } // continue mode for followups
+        }
         args.push("--no-interactive", prompt);
         return { command: "kiro-cli", args };
     }

package/dist/agents/opencode.js

@@ -16,7 +16,7 @@ export class OpenCodeAgent {
         }
         if (followupPrompt) {
             args.push("--continue");
-        } // continue mode for followups
+        }
         args.push(prompt);
         return { command: "opencode", args };
     }

package/dist/agents/qoder.js

@@ -16,7 +16,7 @@ export class Qoder {
         }
         if (followupPrompt) {
             args.push("-c");
-        } // continue mode for followups
+        }
         args.push("-p", prompt);
         return { command: "qodercli", args };
     }

package/dist/agents/shared-prompt.d.ts

@@ -1,7 +1,4 @@
 import type { ParsedTask } from "../types.js";
-/**
- * Build the full agent prompt: instructions + endpoint docs + task description.
- */
 export declare function getAgentInstructions(task: ParsedTask, skipPermissions?: boolean): string;
 export declare const TASK_SUCCESS_MARKER = "[PALMIER_TASK_SUCCESS]";
 export declare const TASK_FAILURE_MARKER = "[PALMIER_TASK_FAILURE]";

package/dist/agents/shared-prompt.js

@@ -5,9 +5,6 @@ import { loadConfig } from "../config.js";
 import { generateEndpointDocs } from "../mcp-tools.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_INSTRUCTIONS_TEMPLATE = fs.readFileSync(path.join(__dirname, "agent-instructions.md"), "utf-8");
-/**
- * Build the full agent prompt: instructions + endpoint docs + task description.
- */
 export function getAgentInstructions(task, skipPermissions) {
     const port = loadConfig().httpPort ?? 7256;
     const taskDescription = task.frontmatter.user_prompt;

package/dist/app-registry.d.ts

@@ -0,0 +1,10 @@
+/** Persistent cache of packageName → appName pairs seen via device notifications. */
+export interface AppInfo {
+    packageName: string;
+    appName: string;
+}
+/** Writes only on change so we track the latest label if an app renames itself. */
+export declare function recordApp(packageName: string, appName: string): void;
+export declare function listApps(): AppInfo[];
+export declare function getAppName(packageName: string): string | undefined;
+//# sourceMappingURL=app-registry.d.ts.map

package/dist/app-registry.js

@@ -0,0 +1,44 @@
+import * as fs from "fs";
+import * as path from "path";
+import { CONFIG_DIR } from "./config.js";
+const REGISTRY_FILE = path.join(CONFIG_DIR, "app-registry.json");
+let cache = null;
+function load() {
+    if (cache)
+        return cache;
+    try {
+        if (fs.existsSync(REGISTRY_FILE)) {
+            cache = JSON.parse(fs.readFileSync(REGISTRY_FILE, "utf-8"));
+            return cache;
+        }
+    }
+    catch {
+        // Corrupt file — start fresh rather than fail notifications.
+    }
+    cache = {};
+    return cache;
+}
+function persist(map) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(REGISTRY_FILE, JSON.stringify(map, null, 2), "utf-8");
+}
+/** Writes only on change so we track the latest label if an app renames itself. */
+export function recordApp(packageName, appName) {
+    if (!packageName || !appName)
+        return;
+    const map = load();
+    if (map[packageName] === appName)
+        return;
+    map[packageName] = appName;
+    persist(map);
+}
+export function listApps() {
+    const map = load();
+    return Object.entries(map)
+        .map(([packageName, appName]) => ({ packageName, appName }))
+        .sort((a, b) => a.appName.localeCompare(b.appName));
+}
+export function getAppName(packageName) {
+    return load()[packageName];
+}
+//# sourceMappingURL=app-registry.js.map

package/dist/commands/info.d.ts

@@ -1,5 +1,2 @@
-/**
- * Print host connection info for setting up clients.
- */
 export declare function infoCommand(): Promise<void>;
 //# sourceMappingURL=info.d.ts.map

package/dist/commands/info.js

@@ -1,21 +1,16 @@
 import { loadConfig } from "../config.js";
 import { loadClients } from "../client-store.js";
-/**
- * Print host connection info for setting up clients.
- */
 export async function infoCommand() {
     const config = loadConfig();
     const clients = loadClients();
     console.log(`Host ID:      ${config.hostId}`);
     console.log(`Project root: ${config.projectRoot}`);
-    // Detected agents
     if (config.agents && config.agents.length > 0) {
         console.log(`Agents:       ${config.agents.map((a) => a.label).join(", ")}`);
     }
     else {
         console.log(`Agents:       (none detected — run \`palmier agents\`)`);
     }
-    // Clients
     console.log(`Clients:      ${clients.length} active`);
     if (clients.length === 0) {
         console.log("");

package/dist/commands/init.d.ts

@@ -1,5 +1,2 @@
-/**
- * Interactive wizard to provision this host.
- */
 export declare function initCommand(): Promise<void>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/init.js

@@ -10,9 +10,6 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
 const red = (s) => `\x1b[31m${s}\x1b[0m`;
-/**
- * Interactive wizard to provision this host.
- */
 export async function initCommand() {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
@@ -20,7 +17,6 @@ export async function initCommand() {
         console.log(`\n${bold("=== Palmier Host Setup ===")}\n`);
         console.log(`By continuing, you agree to the ${cyan("Terms of Service")} (https://www.palmier.me/terms)`);
         console.log(`and ${cyan("Privacy Policy")} (https://www.palmier.me/privacy).\n`);
-        // Detect agents first — abort if none found
         console.log("Detecting installed agents...");
         const agents = await detectAgents();
         if (agents.length === 0) {
@@ -31,7 +27,6 @@ export async function initCommand() {
             process.exit(1);
         }
         console.log(`  Found: ${green(agents.map((a) => a.label).join(", "))}\n`);
-        // LAN mode
         const lanAnswer = await ask("Enable LAN access (direct HTTP from local network)? (y/N): ");
         const lanEnabled = lanAnswer.trim().toLowerCase() === "y";
         let httpPort = 7256;
@@ -40,7 +35,6 @@ export async function initCommand() {
         const parsed = parseInt(portAnswer.trim(), 10);
         if (parsed > 0 && parsed < 65536)
             httpPort = parsed;
-        // Display summary and ask for confirmation before making any changes
         console.log(`\n${bold("Setup summary:")}\n`);
         console.log(`  ${dim("Task storage:")}   ${bold(process.cwd())}`);
         console.log(`                  All tasks and execution data will be stored here.\n`);
@@ -52,7 +46,6 @@ export async function initCommand() {
             console.log(`                  Accessible from other devices on your local network. Pairing required.\n`);
         }
         console.log(`  ${dim("Agents:")}         ${agents.map((a) => a.label).join(", ")}\n`);
-        // Check for existing tasks to recover
         const existingTasks = listTasks(process.cwd());
         if (existingTasks.length > 0) {
             console.log(`  ${dim("Recover tasks:")}  ${existingTasks.length} existing task(s) found:`);
@@ -67,7 +60,6 @@ export async function initCommand() {
             rl.close();
             return;
         }
-        // Register with server
         let existingHostId;
         try {
             existingHostId = loadConfig().hostId;
@@ -92,7 +84,6 @@ export async function initCommand() {
                 }
             }
         }
-        // Build and save config
         const config = {
             hostId: registerResponse.hostId,
             projectRoot: process.cwd(),
@@ -107,8 +98,8 @@ export async function initCommand() {
         saveConfig(config);
         console.log(`Config saved to ${dim("~/.config/palmier/host.json")}`);
         getPlatform().installDaemon(config);
-        // Task recovery happens in the daemon (palmier serve) on startup,
-        // since the daemon runs elevated and can create S4U scheduled tasks.
+        // Task recovery runs in the daemon (palmier serve) because that process
+        // is elevated and can create S4U scheduled tasks.
         console.log("\nStarting pairing...");
         rl.close();
         await pairCommand();

package/dist/commands/pair.d.ts

@@ -1,8 +1,5 @@
 export declare const PAIRING_EXPIRY_MS: number;
 export declare function generatePairingCode(): string;
-/**
- * Generate a pairing code and wait for a PWA client to pair.
- * Listens on NATS (server mode) and HTTP (via serve daemon) in parallel.
- */
+/** Listens on NATS (server mode) and HTTP (via serve daemon) in parallel. */
 export declare function pairCommand(): Promise<void>;
 //# sourceMappingURL=pair.d.ts.map

package/dist/commands/pair.js

@@ -18,9 +18,6 @@ function buildPairResponse(config, label) {
         clientToken: client.token,
     };
 }
-/**
- * POST to the running serve daemon and long-poll until paired or expired.
- */
 function httpPairRegister(port, code) {
     const body = JSON.stringify({ code, expiryMs: PAIRING_EXPIRY_MS });
     return new Promise((resolve) => {
@@ -49,10 +46,7 @@ function httpPairRegister(port, code) {
         req.end(body);
     });
 }
-/**
- * Generate a pairing code and wait for a PWA client to pair.
- * Listens on NATS (server mode) and HTTP (via serve daemon) in parallel.
- */
+/** Listens on NATS (server mode) and HTTP (via serve daemon) in parallel. */
 export async function pairCommand() {
     const config = loadConfig();
     const code = generatePairingCode();
@@ -63,14 +57,12 @@ export async function pairCommand() {
         console.log("Paired successfully!");
     }
     const cleanups = [];
-    // Display pairing info
     console.log("");
     console.log("Enter this code in your Palmier app:");
     console.log("");
     console.log(`  ${code}`);
     console.log("");
     console.log("Code expires in 1 minute.");
-    // NATS pairing (server mode)
     const nc = await connectNats(config);
     const sc = StringCodec();
     const subject = `pair.${code}`;
@@ -98,13 +90,11 @@ export async function pairCommand() {
             onPaired();
         }
     })();
-    // HTTP pairing — register with serve daemon's /pair-register endpoint
     (async () => {
         const result = await httpPairRegister(httpPort, code);
         if (result)
             onPaired();
     })();
-    // Wait for pairing or timeout
     const start = Date.now();
     await new Promise((resolve) => {
         const interval = setInterval(() => {
@@ -114,7 +104,6 @@ export async function pairCommand() {
             }
         }, 500);
     });
-    // Cleanup
     for (const cleanup of cleanups) {
         await cleanup();
     }

package/dist/commands/restart.d.ts

@@ -1,5 +1,2 @@
-/**
- * Restart the palmier serve daemon.
- */
 export declare function restartCommand(): Promise<void>;
 //# sourceMappingURL=restart.d.ts.map

package/dist/commands/restart.js

@@ -1,7 +1,4 @@
 import { getPlatform } from "../platform/index.js";
-/**
- * Restart the palmier serve daemon.
- */
 export async function restartCommand() {
     const platform = getPlatform();
     await platform.restartDaemon();

package/dist/commands/run.d.ts

@@ -1,21 +1,8 @@
 import type { TaskRunningState, RequiredPermission } from "../types.js";
-/**
- * Strip [PALMIER_*] marker lines from agent output.
- */
 export declare function stripPalmierMarkers(output: string): string;
-/**
- * Execute a task by ID.
- */
 export declare function runCommand(taskId: string): Promise<void>;
 export declare function parseReportFiles(output: string): string[];
-/**
- * Extract required permissions from agent output.
- * Looks for lines matching: [PALMIER_PERMISSION] <tool> | <description>
- */
 export declare function parsePermissions(output: string): RequiredPermission[];
-/**
- * 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 declare function parseTaskOutcome(output: string): TaskRunningState;
 //# sourceMappingURL=run.d.ts.map