palmier 0.7.2 → 0.7.3

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, fetching GPS location, and reading device notifications.
+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.
 
 ### MCP Server
 
@@ -43,19 +43,30 @@ Palmier exposes an [MCP](https://modelcontextprotocol.io) server at `http://loca
 **MCP server URL:** `http://localhost:<port>/mcp`
 
 **Available tools:**
-| Tool | Description |
-|------|-------------|
-| `notify` | Send a push notification to the user's device |
-| `request-input` | Request input from the user (blocks until response) |
-| `request-confirmation` | Request confirmation from the user (blocks until response) |
-| `device-geolocation` | Get GPS location of the user's mobile device |
+| Tool | Description | Permission |
+|------|-------------|------------|
+| `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` | Send an SMS message from the user's device | SMS Access |
+| `set-alarm` | Set an alarm on the user's device | None |
+| `read-battery` | Get battery level and charging status | None |
+| `set-ringer-mode` | Set ringer mode (normal/vibrate/silent) | Do Not Disturb Control |
 
 **Available resources:**
 | Resource | URI | REST | Description |
 |----------|-----|------|-------------|
 | Device Notifications | `notifications://device` | `GET /notifications` | Recent notifications from the user's Android device |
+| Device SMS | `sms://device` | `GET /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. The Android app requires notification listener access to be enabled in system settings.
+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.
+
+All device tools work while the Palmier Android app is in the background — they communicate via FCM data messages which wake the app's service even when it's not in the foreground. Permissions listed above must be granted via toggles in the Android app's settings menu.
 
 ```
 ┌──────────────┐         HTTP          ┌──────────────────┐

package/dist/commands/serve.js

@@ -13,6 +13,7 @@ import { saveConfig } from "../config.js";
 import { CONFIG_DIR } from "../config.js";
 import { StringCodec } from "nats";
 import { addNotification } from "../notification-store.js";
+import { addSmsMessage } from "../sms-store.js";
 const POLL_INTERVAL_MS = 30_000;
 const DAEMON_PID_FILE = path.join(CONFIG_DIR, "daemon.pid");
 /**
@@ -116,7 +117,7 @@ export async function serveCommand() {
     // Start NATS transport (loops forever, fire-and-forget)
     if (nc) {
         startNatsTransport(config, handleRpc, nc);
-        // Subscribe to device notifications from Android
+        // Subscribe to device notifications and SMS from Android
         const sc = StringCodec();
         const notifSub = nc.subscribe(`host.${config.hostId}.device.notifications`);
         (async () => {
@@ -130,6 +131,18 @@ export async function serveCommand() {
                 }
             }
         })();
+        const smsSub = nc.subscribe(`host.${config.hostId}.device.sms`);
+        (async () => {
+            for await (const msg of smsSub) {
+                try {
+                    const data = JSON.parse(sc.decode(msg.data));
+                    addSmsMessage({ ...data, receivedAt: Date.now() });
+                }
+                catch (err) {
+                    console.error("[nats] Failed to parse device SMS:", err);
+                }
+            }
+        })();
     }
     // Start HTTP transport (loops forever)
     await startHttpTransport(config, handleRpc, httpPort, nc);

package/dist/mcp-handler.js

@@ -127,12 +127,15 @@ export async function handleMcpRequest(body, sessionId, ctx) {
             if (!resource) {
                 return { body: rpcError(id, -32602, `Unknown resource: ${uri}`) };
             }
+            console.log(`${logPrefix} resources/read ${uri}`);
+            const content = resource.read();
+            console.log(`${logPrefix} resources/read ${uri} done: ${JSON.stringify(content).slice(0, 200)}`);
             return {
                 body: rpcResult(id, {
                     contents: [{
                             uri: resource.uri,
                             mimeType: resource.mimeType,
-                            text: JSON.stringify(resource.read()),
+                            text: JSON.stringify(content),
                         }],
                 }),
             };

package/dist/mcp-tools.js

@@ -2,6 +2,7 @@ import { StringCodec } from "nats";
 import { registerPending } from "./pending-requests.js";
 import { getLocationDevice } from "./location-device.js";
 import { getNotifications } from "./notification-store.js";
+import { getSmsMessages } from "./sms-store.js";
 export class ToolError extends Error {
     statusCode;
     constructor(message, statusCode = 500) {
@@ -171,7 +172,385 @@ const deviceGeolocationTool = {
         return locationData;
     },
 };
-export const agentTools = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool];
+const readContactsTool = {
+    name: "read-contacts",
+    description: [
+        "Read the contact list from the user's mobile device.",
+        "Blocks until the device responds (up to 30 seconds).",
+        'Response: `{"contacts": [{"id": ..., "name": ..., "phone": ...}]}` on success, or `{"error": "..."}` on failure.',
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+    async handler(_args, ctx) {
+        if (!ctx.nc)
+            throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const sc = StringCodec();
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.contacts`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, action: "read" })), { timeout: 5_000 });
+        const ack = JSON.parse(sc.decode(ackReply.data));
+        if (ack.error)
+            throw new ToolError(ack.error, 502);
+        const responsePromise = new Promise((resolve, reject) => {
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.contacts.${ctx.sessionId}`, { max: 1 });
+            const timer = setTimeout(() => {
+                sub.unsubscribe();
+                reject(new ToolError("Device did not respond within 30 seconds", 504));
+            }, 30_000);
+            (async () => {
+                for await (const msg of sub) {
+                    clearTimeout(timer);
+                    resolve(sc.decode(msg.data));
+                }
+            })();
+        });
+        const result = JSON.parse(await responsePromise);
+        if (result.error)
+            return { error: result.error };
+        return result;
+    },
+};
+const createContactTool = {
+    name: "create-contact",
+    description: [
+        "Create a new contact on the user's mobile device.",
+        "Blocks until the device responds (up to 30 seconds).",
+        'Response: `{"ok": true}` on success, or `{"error": "..."}` on failure.',
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "Contact display name" },
+            phone: { type: "string", description: "Phone number" },
+            email: { type: "string", description: "Email address" },
+        },
+        required: ["name"],
+    },
+    async handler(args, ctx) {
+        if (!ctx.nc)
+            throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const { name, phone, email } = args;
+        if (!name)
+            throw new ToolError("name is required", 400);
+        const sc = StringCodec();
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.contacts`, sc.encode(JSON.stringify({
+            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            action: "create", name, phone, email,
+        })), { timeout: 5_000 });
+        const ack = JSON.parse(sc.decode(ackReply.data));
+        if (ack.error)
+            throw new ToolError(ack.error, 502);
+        const responsePromise = new Promise((resolve, reject) => {
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.contacts.${ctx.sessionId}`, { max: 1 });
+            const timer = setTimeout(() => {
+                sub.unsubscribe();
+                reject(new ToolError("Device did not respond within 30 seconds", 504));
+            }, 30_000);
+            (async () => {
+                for await (const msg of sub) {
+                    clearTimeout(timer);
+                    resolve(sc.decode(msg.data));
+                }
+            })();
+        });
+        const result = JSON.parse(await responsePromise);
+        if (result.error)
+            return { error: result.error };
+        return result;
+    },
+};
+const readCalendarTool = {
+    name: "read-calendar",
+    description: [
+        "Read calendar events from the user's mobile device.",
+        "Blocks until the device responds (up to 30 seconds).",
+        "Pass startDate and endDate as Unix timestamps in milliseconds. Defaults to next 7 days.",
+        'Response: `{"events": [{"id": ..., "title": ..., "startTime": ..., "endTime": ..., "location": ..., "description": ..., "allDay": ..., "calendar": ...}]}` on success.',
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {
+            startDate: { type: "number", description: "Start of range (Unix ms). Defaults to now." },
+            endDate: { type: "number", description: "End of range (Unix ms). Defaults to 7 days from start." },
+        },
+    },
+    async handler(args, ctx) {
+        if (!ctx.nc)
+            throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const { startDate, endDate } = args;
+        const sc = StringCodec();
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.calendar`, sc.encode(JSON.stringify({
+            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            action: "read",
+            ...(startDate ? { startDate: String(startDate) } : {}),
+            ...(endDate ? { endDate: String(endDate) } : {}),
+        })), { timeout: 5_000 });
+        const ack = JSON.parse(sc.decode(ackReply.data));
+        if (ack.error)
+            throw new ToolError(ack.error, 502);
+        const responsePromise = new Promise((resolve, reject) => {
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.calendar.${ctx.sessionId}`, { max: 1 });
+            const timer = setTimeout(() => {
+                sub.unsubscribe();
+                reject(new ToolError("Device did not respond within 30 seconds", 504));
+            }, 30_000);
+            (async () => {
+                for await (const msg of sub) {
+                    clearTimeout(timer);
+                    resolve(sc.decode(msg.data));
+                }
+            })();
+        });
+        const result = JSON.parse(await responsePromise);
+        if (result.error)
+            return { error: result.error };
+        return result;
+    },
+};
+const createCalendarEventTool = {
+    name: "create-calendar-event",
+    description: [
+        "Create a calendar event on the user's mobile device.",
+        "Blocks until the device responds (up to 30 seconds).",
+        'Response: `{"ok": true}` on success, or `{"error": "..."}` on failure.',
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {
+            title: { type: "string", description: "Event title" },
+            startTime: { type: "number", description: "Start time (Unix ms)" },
+            endTime: { type: "number", description: "End time (Unix ms)" },
+            location: { type: "string", description: "Event location" },
+            description: { type: "string", description: "Event description" },
+        },
+        required: ["title", "startTime", "endTime"],
+    },
+    async handler(args, ctx) {
+        if (!ctx.nc)
+            throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const { title, startTime, endTime, location, description } = args;
+        if (!title || !startTime || !endTime)
+            throw new ToolError("title, startTime, and endTime are required", 400);
+        const sc = StringCodec();
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.calendar`, sc.encode(JSON.stringify({
+            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            action: "create",
+            title, startTime: String(startTime), endTime: String(endTime),
+            ...(location ? { location } : {}),
+            ...(description ? { description } : {}),
+        })), { timeout: 5_000 });
+        const ack = JSON.parse(sc.decode(ackReply.data));
+        if (ack.error)
+            throw new ToolError(ack.error, 502);
+        const responsePromise = new Promise((resolve, reject) => {
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.calendar.${ctx.sessionId}`, { max: 1 });
+            const timer = setTimeout(() => {
+                sub.unsubscribe();
+                reject(new ToolError("Device did not respond within 30 seconds", 504));
+            }, 30_000);
+            (async () => {
+                for await (const msg of sub) {
+                    clearTimeout(timer);
+                    resolve(sc.decode(msg.data));
+                }
+            })();
+        });
+        const result = JSON.parse(await responsePromise);
+        if (result.error)
+            return { error: result.error };
+        return result;
+    },
+};
+const sendSmsTool = {
+    name: "send-sms",
+    description: [
+        "Send an SMS message from the user's mobile device.",
+        "Blocks until the device responds (up to 30 seconds).",
+        'Response: `{"ok": true}` on success, or `{"error": "..."}` on failure.',
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {
+            to: { type: "string", description: "Recipient phone number" },
+            body: { type: "string", description: "Message text" },
+        },
+        required: ["to", "body"],
+    },
+    async handler(args, ctx) {
+        if (!ctx.nc)
+            throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const { to, body } = args;
+        if (!to || !body)
+            throw new ToolError("to and body are required", 400);
+        const sc = StringCodec();
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.sms`, sc.encode(JSON.stringify({
+            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            action: "send", to, body,
+        })), { timeout: 5_000 });
+        const ack = JSON.parse(sc.decode(ackReply.data));
+        if (ack.error)
+            throw new ToolError(ack.error, 502);
+        const responsePromise = new Promise((resolve, reject) => {
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.sms.${ctx.sessionId}`, { max: 1 });
+            const timer = setTimeout(() => {
+                sub.unsubscribe();
+                reject(new ToolError("Device did not respond within 30 seconds", 504));
+            }, 30_000);
+            (async () => {
+                for await (const msg of sub) {
+                    clearTimeout(timer);
+                    resolve(sc.decode(msg.data));
+                }
+            })();
+        });
+        const result = JSON.parse(await responsePromise);
+        if (result.error)
+            return { error: result.error };
+        return result;
+    },
+};
+const setAlarmTool = {
+    name: "set-alarm",
+    description: [
+        "Set an alarm on the user's mobile device.",
+        "Blocks until the device responds (up to 30 seconds).",
+        'Response: `{"ok": true}` on success, or `{"error": "..."}` on failure.',
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {
+            hour: { type: "number", description: "Hour (0-23)" },
+            minutes: { type: "number", description: "Minutes (0-59)" },
+            label: { type: "string", description: "Alarm label" },
+            days: {
+                type: "array",
+                items: { type: "number" },
+                description: "Recurring days (1=Sun, 2=Mon, ..., 7=Sat). Omit for one-time.",
+            },
+        },
+        required: ["hour", "minutes"],
+    },
+    async handler(args, ctx) {
+        if (!ctx.nc)
+            throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const { hour, minutes, label, days } = args;
+        if (hour == null || minutes == null)
+            throw new ToolError("hour and minutes are required", 400);
+        const sc = StringCodec();
+        const payload = {
+            hostId: ctx.config.hostId, requestId: ctx.sessionId,
+            action: "set", hour: String(hour), minutes: String(minutes),
+        };
+        if (label)
+            payload.label = label;
+        if (days?.length)
+            payload.days = days.join(",");
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.alarm`, sc.encode(JSON.stringify(payload)), { timeout: 5_000 });
+        const ack = JSON.parse(sc.decode(ackReply.data));
+        if (ack.error)
+            throw new ToolError(ack.error, 502);
+        const responsePromise = new Promise((resolve, reject) => {
+            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));
+            }, 30_000);
+            (async () => {
+                for await (const msg of sub) {
+                    clearTimeout(timer);
+                    resolve(sc.decode(msg.data));
+                }
+            })();
+        });
+        const result = JSON.parse(await responsePromise);
+        if (result.error)
+            return { error: result.error };
+        return result;
+    },
+};
+const readBatteryTool = {
+    name: "read-battery",
+    description: [
+        "Get the battery level and charging status of the user's mobile device.",
+        "Blocks until the device responds (up to 30 seconds).",
+        'Response: `{"level": 85, "charging": true}` on success, or `{"error": "..."}` on failure.',
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+    async handler(_args, ctx) {
+        if (!ctx.nc)
+            throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const sc = StringCodec();
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.battery`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId })), { timeout: 5_000 });
+        const ack = JSON.parse(sc.decode(ackReply.data));
+        if (ack.error)
+            throw new ToolError(ack.error, 502);
+        const responsePromise = new Promise((resolve, reject) => {
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.battery.${ctx.sessionId}`, { max: 1 });
+            const timer = setTimeout(() => {
+                sub.unsubscribe();
+                reject(new ToolError("Device did not respond within 30 seconds", 504));
+            }, 30_000);
+            (async () => {
+                for await (const msg of sub) {
+                    clearTimeout(timer);
+                    resolve(sc.decode(msg.data));
+                }
+            })();
+        });
+        const result = JSON.parse(await responsePromise);
+        if (result.error)
+            return { error: result.error };
+        return result;
+    },
+};
+const setRingerModeTool = {
+    name: "set-ringer-mode",
+    description: [
+        "Set the phone's ringer mode. Requires Do Not Disturb access on the device.",
+        "Blocks until the device responds (up to 30 seconds).",
+        'Response: `{"ok": true, "mode": "silent"}` on success, or `{"error": "..."}` on failure.',
+    ],
+    inputSchema: {
+        type: "object",
+        properties: {
+            mode: { type: "string", description: "Ringer mode: 'normal', 'vibrate', or 'silent'" },
+        },
+        required: ["mode"],
+    },
+    async handler(args, ctx) {
+        if (!ctx.nc)
+            throw new ToolError("Not connected to server (NATS unavailable)", 503);
+        const { mode } = args;
+        if (!["normal", "vibrate", "silent"].includes(mode))
+            throw new ToolError("mode must be 'normal', 'vibrate', or 'silent'", 400);
+        const sc = StringCodec();
+        const ackReply = await ctx.nc.request(`host.${ctx.config.hostId}.fcm.ringer`, sc.encode(JSON.stringify({ hostId: ctx.config.hostId, requestId: ctx.sessionId, mode })), { timeout: 5_000 });
+        const ack = JSON.parse(sc.decode(ackReply.data));
+        if (ack.error)
+            throw new ToolError(ack.error, 502);
+        const responsePromise = new Promise((resolve, reject) => {
+            const sub = ctx.nc.subscribe(`host.${ctx.config.hostId}.ringer.${ctx.sessionId}`, { max: 1 });
+            const timer = setTimeout(() => {
+                sub.unsubscribe();
+                reject(new ToolError("Device did not respond within 30 seconds", 504));
+            }, 30_000);
+            (async () => {
+                for await (const msg of sub) {
+                    clearTimeout(timer);
+                    resolve(sc.decode(msg.data));
+                }
+            })();
+        });
+        const result = JSON.parse(await responsePromise);
+        if (result.error)
+            return { error: result.error };
+        return result;
+    },
+};
+export const agentTools = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool, readContactsTool, createContactTool, readCalendarTool, createCalendarEventTool, sendSmsTool, setAlarmTool, readBatteryTool, setRingerModeTool];
 export const agentToolMap = new Map(agentTools.map((t) => [t.name, t]));
 const deviceNotificationsResource = {
     uri: "notifications://device",
@@ -184,7 +563,18 @@ const deviceNotificationsResource = {
     restPath: "/notifications",
     read: getNotifications,
 };
-export const agentResources = [deviceNotificationsResource];
+const deviceSmsResource = {
+    uri: "sms://device",
+    name: "Device SMS",
+    description: [
+        "Get recent SMS messages from the user's Android device.",
+        "Response: JSON array of message objects with `id`, `sender`, `body`, `timestamp`.",
+    ],
+    mimeType: "application/json",
+    restPath: "/sms",
+    read: getSmsMessages,
+};
+export const agentResources = [deviceNotificationsResource, deviceSmsResource];
 export const agentResourceMap = new Map(agentResources.map((r) => [r.uri, r]));
 /**
  * Generate the HTTP Endpoints markdown section for agent-instructions.md from the tool registry.
@@ -229,7 +619,7 @@ export function generateEndpointDocs(port, taskId, tools = agentTools, resources
     }
     for (const resource of resources) {
         const [header, ...details] = resource.description;
-        lines.push(`**\`GET ${baseUrl}${resource.restPath}\`** — ${header}`);
+        lines.push(`**\`GET ${baseUrl}${resource.restPath}?taskId=${taskId}\`** — ${header}`);
         for (const detail of details) {
             lines.push(`- ${detail}`);
         }