palmier 0.6.9 → 0.7.2

package/src/mcp-tools.ts

@@ -1,6 +1,7 @@
 import { StringCodec, type NatsConnection } from "nats";
 import { registerPending } from "./pending-requests.js";
 import { getLocationDevice } from "./location-device.js";
+import { getNotifications } from "./notification-store.js";
 import type { HostConfig } from "./types.js";
 
 export class ToolError extends Error {
@@ -205,10 +206,46 @@ const deviceGeolocationTool: ToolDefinition = {
 export const agentTools: ToolDefinition[] = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool];
 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;
+  /** 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;
+}
+
+const deviceNotificationsResource: ResourceDefinition = {
+  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: ResourceDefinition[] = [deviceNotificationsResource];
+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, tools: ToolDefinition[] = agentTools): string {
+export function generateEndpointDocs(
+  port: number,
+  taskId: string,
+  tools: ToolDefinition[] = agentTools,
+  resources: ResourceDefinition[] = agentResources,
+): string {
   const baseUrl = `http://localhost:${port}`;
   const lines: string[] = [
     `The following HTTP endpoints are available during task execution. Use curl to call them.`,
@@ -249,5 +286,14 @@ export function generateEndpointDocs(port: number, taskId: string, tools: ToolDe
     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();
 }

package/src/notification-store.ts

@@ -0,0 +1,30 @@
+export interface DeviceNotification {
+  id: string;
+  packageName: string;
+  appName: string;
+  title: string;
+  text: string;
+  timestamp: number;
+  receivedAt: number;
+}
+
+const MAX_NOTIFICATIONS = 50;
+const notifications: DeviceNotification[] = [];
+const listeners = new Set<() => void>();
+
+export function addNotification(n: DeviceNotification): void {
+  notifications.push(n);
+  if (notifications.length > MAX_NOTIFICATIONS) {
+    notifications.shift();
+  }
+  for (const cb of listeners) cb();
+}
+
+export function getNotifications(): DeviceNotification[] {
+  return [...notifications];
+}
+
+export function onNotificationsChanged(cb: () => void): () => void {
+  listeners.add(cb);
+  return () => { listeners.delete(cb); };
+}

package/src/transports/http-transport.ts

@@ -6,9 +6,10 @@ import { validateClient, addClient } from "../client-store.js";
 import { registerPending } from "../pending-requests.js";
 import * as fs from "node:fs";
 import type { HostConfig, RpcMessage, RequiredPermission } from "../types.js";
-import { agentToolMap, ToolError, type ToolContext } from "../mcp-tools.js";
-import { handleMcpRequest, getAgentName } from "../mcp-handler.js";
+import { agentToolMap, agentResources, ToolError, type ToolContext } from "../mcp-tools.js";
+import { handleMcpRequest, getAgentName, getResourceSubscriptions } from "../mcp-handler.js";
 import { getTaskDir } from "../task.js";
+import { onNotificationsChanged } from "../notification-store.js";
 
 // ── Bundled PWA asset serving ───────────────────────────────────────────
 
@@ -102,9 +103,28 @@ export async function startHttpTransport(
   onReady?: () => void,
 ): Promise<void> {
   const sseClients = new Set<SseClient>();
+  const mcpStreams = new Map<string, http.ServerResponse>();
   const lanEnabled = config.lanEnabled ?? false;
   const bindAddress = lanEnabled ? "0.0.0.0" : "127.0.0.1";
 
+  /** Push notifications/resources/updated to all MCP clients subscribed to the given URI. */
+  function broadcastResourceUpdated(uri: string) {
+    const subs = getResourceSubscriptions();
+    for (const [sessionId, uris] of subs) {
+      if (!uris.has(uri)) continue;
+      const stream = mcpStreams.get(sessionId);
+      if (!stream) continue;
+      stream.write(`data: ${JSON.stringify({
+        jsonrpc: "2.0",
+        method: "notifications/resources/updated",
+        params: { uri },
+      })}\n\n`);
+    }
+  }
+
+  // Wire up resource change listeners
+  onNotificationsChanged(() => broadcastResourceUpdated("notifications://device"));
+
   // If a pairing code is provided, pre-register it
   if (pairingCode) {
     const EXPIRY_MS = 24 * 60 * 60 * 1000;
@@ -182,7 +202,24 @@ export async function startHttpTransport(
         if (result.sessionId) {
           res.setHeader("Mcp-Session-Id", result.sessionId);
         }
-        sendJson(res, 200, result.body);
+        if (result.stream && sessionId) {
+          // Keep response open as SSE stream for server-initiated notifications
+          res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+          });
+          res.write(`data: ${JSON.stringify(result.body)}\n\n`);
+          mcpStreams.set(sessionId, res);
+          const heartbeat = setInterval(() => { res.write(":heartbeat\n\n"); }, 15_000);
+          req.on("close", () => {
+            clearInterval(heartbeat);
+            mcpStreams.delete(sessionId);
+            getResourceSubscriptions().delete(sessionId);
+          });
+        } else {
+          sendJson(res, 200, result.body);
+        }
       } catch (err) {
         sendJson(res, 500, { error: String(err) });
       }
@@ -220,6 +257,15 @@ export async function startHttpTransport(
       return;
     }
 
+    // ── Auto-generated REST endpoints from MCP resource registry ────
+
+    const matchedResource = req.method === "GET" && agentResources.find((r) => r.restPath === pathname);
+    if (matchedResource) {
+      if (!isLocalhost(req)) { sendJson(res, 403, { error: "localhost only" }); return; }
+      sendJson(res, 200, matchedResource.read());
+      return;
+    }
+
     // ── Localhost-only endpoints (no auth) ─────────────────────────────
 
     if (req.method === "POST" && pathname === "/event") {

package/test/agent-instructions.test.ts

@@ -3,7 +3,7 @@ import assert from "node:assert/strict";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
-import { generateEndpointDocs, type ToolDefinition } from "../src/mcp-tools.js";
+import { generateEndpointDocs, type ToolDefinition, type ResourceDefinition } from "../src/mcp-tools.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const templatePath = path.join(__dirname, "..", "src", "agents", "agent-instructions.md");
@@ -48,10 +48,25 @@ const mockTools: ToolDefinition[] = [
   },
 ];
 
+/** Mock resources with a known, stable shape for testing */
+const mockResources: ResourceDefinition[] = [
+  {
+    uri: "mock://data",
+    name: "Mock Data",
+    description: [
+      "Get mock data from the device.",
+      "Response: JSON array of data objects.",
+    ],
+    mimeType: "application/json",
+    restPath: "/mock-data",
+    read: () => [],
+  },
+];
+
 /** Minimal replica of getAgentInstructions that doesn't need host.json */
 function buildInstructions(taskId: string, opts?: { skipPermissions?: boolean }): string {
   let instructions = template
-    .replace(/\{\{ENDPOINT_DOCS\}\}/g, generateEndpointDocs(9966, taskId, mockTools))
+    .replace(/\{\{ENDPOINT_DOCS\}\}/g, generateEndpointDocs(9966, taskId, mockTools, mockResources))
     .replace(/\{\{TASK_DESCRIPTION\}\}/g, "Test task prompt");
   if (opts?.skipPermissions) {
     instructions = instructions.replace(/## Permissions\r?\n[\s\S]*?(?=## |\r?\n---)/m, "");
@@ -104,7 +119,7 @@ describe("getAgentInstructions", () => {
 
 
 describe("generateEndpointDocs", () => {
-  const docs = generateEndpointDocs(9966, "test-id", mockTools);
+  const docs = generateEndpointDocs(9966, "test-id", mockTools, mockResources);
 
   it("matches expected full output", () => {
     const expected = [
@@ -125,6 +140,9 @@ describe("generateEndpointDocs", () => {
       "- `tags` (optional, string array): Filter tags",
       "- Blocks until the device responds.",
       '- Response: `{"data": ...}` on success.',
+      "",
+      "**`GET http://localhost:9966/mock-data`** — Get mock data from the device.",
+      "- Response: JSON array of data objects.",
     ].join("\n");
     assert.equal(docs, expected);
   });
@@ -173,4 +191,19 @@ describe("generateEndpointDocs", () => {
   it("renders multi-line descriptions as bullet points", () => {
     assert.match(docs, /- Blocks until the device responds\./);
   });
+
+  it("generates GET endpoints for all provided resources", () => {
+    for (const resource of mockResources) {
+      assert.match(docs, new RegExp(`GET http://localhost:9966${resource.restPath}`), `Missing endpoint for ${resource.uri}`);
+    }
+  });
+
+  it("includes resource description as bullet points", () => {
+    assert.match(docs, /- Response: JSON array of data objects\./);
+  });
+
+  it("generates no resource endpoints when resources array is empty", () => {
+    const docsNoResources = generateEndpointDocs(9966, "test-id", mockTools, []);
+    assert.doesNotMatch(docsNoResources, /GET http/);
+  });
 });

package/test/notification-store.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+
+// Re-import fresh module state for each test file run
+// Since the store is module-level state, we test the exported functions directly
+import { addNotification, getNotifications, onNotificationsChanged, type DeviceNotification } from "../src/notification-store.js";
+
+function makeNotification(id: string, overrides?: Partial<DeviceNotification>): DeviceNotification {
+  return {
+    id,
+    packageName: "com.example.app",
+    appName: "Example",
+    title: `Title ${id}`,
+    text: `Text ${id}`,
+    timestamp: Date.now(),
+    receivedAt: Date.now(),
+    ...overrides,
+  };
+}
+
+describe("notification-store", () => {
+  it("stores and retrieves notifications", () => {
+    const before = getNotifications().length;
+    addNotification(makeNotification("test-1"));
+    const after = getNotifications();
+    assert.equal(after.length, before + 1);
+    assert.equal(after[after.length - 1].id, "test-1");
+  });
+
+  it("returns a defensive copy", () => {
+    const a = getNotifications();
+    const b = getNotifications();
+    assert.notStrictEqual(a, b);
+  });
+
+  it("evicts oldest when exceeding max", () => {
+    const before = getNotifications().length;
+    // Add enough to exceed 50
+    for (let i = 0; i < 60; i++) {
+      addNotification(makeNotification(`evict-${i}`));
+    }
+    const result = getNotifications();
+    assert.ok(result.length <= 50, `Expected <= 50, got ${result.length}`);
+  });
+
+  it("notifies listeners on add", () => {
+    let called = 0;
+    const unsub = onNotificationsChanged(() => { called++; });
+    addNotification(makeNotification("listener-1"));
+    assert.equal(called, 1);
+    addNotification(makeNotification("listener-2"));
+    assert.equal(called, 2);
+    unsub();
+    addNotification(makeNotification("listener-3"));
+    assert.equal(called, 2); // no longer called after unsubscribe
+  });
+});