palmier 0.6.9 → 0.7.0

package/README.md

@@ -34,11 +34,11 @@ 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, and fetching GPS location.
+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.
 
 ### MCP Server
 
-Palmier exposes an [MCP](https://modelcontextprotocol.io) server at `http://localhost:<port>/mcp` (streamable HTTP transport). MCP-capable agents can register it to get tool definitions automatically. The same tools are also available as REST endpoints for curl-based agents.
+Palmier exposes an [MCP](https://modelcontextprotocol.io) server at `http://localhost:<port>/mcp` (streamable HTTP transport). MCP-capable agents can register it to get tool and resource definitions automatically. The same tools and resources are also available as REST endpoints for curl-based agents.
 
 **MCP server URL:** `http://localhost:<port>/mcp`
 
@@ -50,6 +50,13 @@ Palmier exposes an [MCP](https://modelcontextprotocol.io) server at `http://loca
 | `request-confirmation` | Request confirmation from the user (blocks until response) |
 | `device-geolocation` | Get GPS location of the user's mobile device |
 
+**Available resources:**
+| Resource | URI | REST | Description |
+|----------|-----|------|-------------|
+| Device Notifications | `notifications://device` | `GET /notifications` | Recent notifications 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.
+
 ```
 ┌──────────────┐         HTTP          ┌──────────────────┐
 │              │◄──────────────────────│                  │

package/dist/commands/serve.js

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

package/dist/mcp-handler.d.ts

@@ -2,7 +2,10 @@ import { type ToolContext } from "./mcp-tools.js";
 export interface McpResponse {
     body: object;
     sessionId?: string;
+    /** If true, the HTTP transport should keep the response open as an SSE stream for server-initiated notifications. */
+    stream?: boolean;
 }
+export declare function getResourceSubscriptions(): Map<string, Set<string>>;
 export declare function getAgentName(sessionId: string): string | undefined;
 export declare function handleMcpRequest(body: string, sessionId: string | undefined, ctx: ToolContext): Promise<McpResponse>;
 //# sourceMappingURL=mcp-handler.d.ts.map

package/dist/mcp-handler.js

@@ -1,5 +1,10 @@
 import { randomUUID } from "crypto";
-import { agentTools, agentToolMap, ToolError } from "./mcp-tools.js";
+import { agentTools, agentToolMap, agentResources, agentResourceMap, ToolError } from "./mcp-tools.js";
+// Resource subscriptions: sessionId → Set of resource URIs
+const resourceSubscriptions = new Map();
+export function getResourceSubscriptions() {
+    return resourceSubscriptions;
+}
 // Session-to-agent name map with 24h TTL
 const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
 const sessionAgents = new Map();
@@ -16,8 +21,10 @@ export function getAgentName(sessionId) {
 function pruneExpiredSessions() {
     const now = Date.now();
     for (const [id, entry] of sessionAgents) {
-        if (now > entry.expiresAt)
+        if (now > entry.expiresAt) {
             sessionAgents.delete(id);
+            resourceSubscriptions.delete(id);
+        }
     }
 }
 function rpcError(id, code, message) {
@@ -57,7 +64,7 @@ export async function handleMcpRequest(body, sessionId, ctx) {
             return {
                 body: rpcResult(id, {
                     protocolVersion: "2025-03-26",
-                    capabilities: { tools: {} },
+                    capabilities: { tools: {}, resources: { subscribe: true } },
                     serverInfo: { name: "palmier", version: "1.0.0" },
                 }),
                 sessionId: newSessionId,
@@ -102,6 +109,55 @@ export async function handleMcpRequest(body, sessionId, ctx) {
                 };
             }
         }
+        case "resources/list": {
+            return {
+                body: rpcResult(id, {
+                    resources: agentResources.map((r) => ({
+                        uri: r.uri,
+                        name: r.name,
+                        description: r.description[0],
+                        mimeType: r.mimeType,
+                    })),
+                }),
+            };
+        }
+        case "resources/read": {
+            const uri = req.params?.uri;
+            const resource = agentResourceMap.get(uri);
+            if (!resource) {
+                return { body: rpcError(id, -32602, `Unknown resource: ${uri}`) };
+            }
+            return {
+                body: rpcResult(id, {
+                    contents: [{
+                            uri: resource.uri,
+                            mimeType: resource.mimeType,
+                            text: JSON.stringify(resource.read()),
+                        }],
+                }),
+            };
+        }
+        case "resources/subscribe": {
+            const uri = req.params?.uri;
+            if (!agentResourceMap.has(uri)) {
+                return { body: rpcError(id, -32602, `Unknown resource: ${uri}`) };
+            }
+            if (!sessionId) {
+                return { body: rpcError(id, -32600, "Session required for subscriptions") };
+            }
+            if (!resourceSubscriptions.has(sessionId)) {
+                resourceSubscriptions.set(sessionId, new Set());
+            }
+            resourceSubscriptions.get(sessionId).add(uri);
+            return { body: rpcResult(id, {}), stream: true };
+        }
+        case "resources/unsubscribe": {
+            const uri = req.params?.uri;
+            if (sessionId) {
+                resourceSubscriptions.get(sessionId)?.delete(uri);
+            }
+            return { body: rpcResult(id, {}) };
+        }
         default:
             console.warn(`${logPrefix} Unknown method: ${req.method}`);
             return { body: rpcError(id, -32601, `Method not found: ${req.method}`) };

package/dist/mcp-tools.d.ts

@@ -20,8 +20,23 @@ export interface ToolDefinition {
 }
 export declare const agentTools: ToolDefinition[];
 export declare const agentToolMap: Map<string, ToolDefinition>;
+export interface ResourceDefinition {
+    /** MCP resource URI (e.g. "notifications://device"). */
+    uri: string;
+    /** Display name. */
+    name: string;
+    /** First line is the summary (used as REST endpoint header). Remaining lines become bullet points in docs. */
+    description: string[];
+    mimeType: string;
+    /** REST endpoint path (e.g. "/notifications"). Served as GET. */
+    restPath: string;
+    /** Return the current resource content. */
+    read: () => unknown;
+}
+export declare const agentResources: ResourceDefinition[];
+export declare const agentResourceMap: Map<string, ResourceDefinition>;
 /**
  * Generate the HTTP Endpoints markdown section for agent-instructions.md from the tool registry.
  */
-export declare function generateEndpointDocs(port: number, taskId: string, tools?: ToolDefinition[]): string;
+export declare function generateEndpointDocs(port: number, taskId: string, tools?: ToolDefinition[], resources?: ResourceDefinition[]): string;
 //# sourceMappingURL=mcp-tools.d.ts.map

package/dist/mcp-tools.js

@@ -1,6 +1,7 @@
 import { StringCodec } from "nats";
 import { registerPending } from "./pending-requests.js";
 import { getLocationDevice } from "./location-device.js";
+import { getNotifications } from "./notification-store.js";
 export class ToolError extends Error {
     statusCode;
     constructor(message, statusCode = 500) {
@@ -172,10 +173,23 @@ const deviceGeolocationTool = {
 };
 export const agentTools = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool];
 export const agentToolMap = new Map(agentTools.map((t) => [t.name, t]));
+const deviceNotificationsResource = {
+    uri: "notifications://device",
+    name: "Device Notifications",
+    description: [
+        "Get recent notifications from the user's Android device.",
+        "Response: JSON array of notification objects with `id`, `packageName`, `appName`, `title`, `text`, `timestamp`.",
+    ],
+    mimeType: "application/json",
+    restPath: "/notifications",
+    read: getNotifications,
+};
+export const agentResources = [deviceNotificationsResource];
+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.
  */
-export function generateEndpointDocs(port, taskId, tools = agentTools) {
+export function generateEndpointDocs(port, taskId, tools = agentTools, resources = agentResources) {
     const baseUrl = `http://localhost:${port}`;
     const lines = [
         `The following HTTP endpoints are available during task execution. Use curl to call them.`,
@@ -213,6 +227,14 @@ export function generateEndpointDocs(port, taskId, tools = agentTools) {
         }
         lines.push("");
     }
+    for (const resource of resources) {
+        const [header, ...details] = resource.description;
+        lines.push(`**\`GET ${baseUrl}${resource.restPath}\`** — ${header}`);
+        for (const detail of details) {
+            lines.push(`- ${detail}`);
+        }
+        lines.push("");
+    }
     return lines.join("\n").trimEnd();
 }
 //# sourceMappingURL=mcp-tools.js.map

package/dist/notification-store.d.ts

@@ -0,0 +1,13 @@
+export interface DeviceNotification {
+    id: string;
+    packageName: string;
+    appName: string;
+    title: string;
+    text: string;
+    timestamp: number;
+    receivedAt: number;
+}
+export declare function addNotification(n: DeviceNotification): void;
+export declare function getNotifications(): DeviceNotification[];
+export declare function onNotificationsChanged(cb: () => void): () => void;
+//# sourceMappingURL=notification-store.d.ts.map

package/dist/notification-store.js

@@ -0,0 +1,19 @@
+const MAX_NOTIFICATIONS = 50;
+const notifications = [];
+const listeners = new Set();
+export function addNotification(n) {
+    notifications.push(n);
+    if (notifications.length > MAX_NOTIFICATIONS) {
+        notifications.shift();
+    }
+    for (const cb of listeners)
+        cb();
+}
+export function getNotifications() {
+    return [...notifications];
+}
+export function onNotificationsChanged(cb) {
+    listeners.add(cb);
+    return () => { listeners.delete(cb); };
+}
+//# sourceMappingURL=notification-store.js.map