pi-note 0.33.4 → 0.34.0

package/dist-mcp/mcp/events.js

@@ -0,0 +1,150 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+const LIMIT = 256;
+const safe = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+/** One bounded CLI scan per tick, shared by all subscribers; no in-memory replay queue. */
+export function completionEvents(log) {
+    const subscribers = new Set();
+    let timer;
+    let running;
+    let controller;
+    let stopped = false;
+    const reject = (res, status, message) => {
+        res.writeHead(status, { 'Content-Type': 'text/plain' });
+        res.end(`${message}\n`);
+    };
+    const drop = (sub) => {
+        subscribers.delete(sub);
+        if (!subscribers.size) {
+            clearTimeout(timer);
+            timer = undefined;
+            controller?.abort();
+        }
+    };
+    const write = (sub, frame) => {
+        // Disconnect rather than queue unbounded data. Resume from the last persisted ID.
+        if (!sub.res.write(frame)) {
+            drop(sub);
+            sub.res.destroy();
+        }
+    };
+    const checkpoint = (sub, id) => {
+        write(sub, `id: ${id}\nevent: checkpoint\ndata: {}\n\n`);
+        sub.cursor = id;
+    };
+    const read = async (after) => {
+        const { stdout } = await exec(process.env.PINOTE_NOTE_COMMAND || 'note', ['--no-notify', 'events', '--limit', String(LIMIT), ...(after === undefined ? [] : ['--after', String(after)])], { signal: controller.signal, timeout: 10_000, maxBuffer: 256 * 1024 });
+        const page = JSON.parse(stdout);
+        if (!safe(page.cursor) || after !== undefined && page.cursor < after || !Array.isArray(page.events) || page.events.length > LIMIT)
+            throw new Error('Invalid event page');
+        let previous = after ?? 0;
+        for (const event of page.events) {
+            if (!safe(event.id) || event.id <= previous || event.id > page.cursor || !safe(event.task_id) || !event.task_id || typeof event.timestamp !== 'string' || event.timestamp.length > 128 || /[\r\n]/.test(event.timestamp))
+                throw new Error('Invalid completion');
+            previous = event.id;
+        }
+        return page;
+    };
+    const tick = async () => {
+        controller = new AbortController();
+        try {
+            const pending = [...subscribers].filter((sub) => !sub.ready);
+            if (pending.length) {
+                const tail = (await read()).cursor;
+                // New arrivals must not be validated against a tail captured before they joined.
+                for (const sub of pending) {
+                    if (!subscribers.has(sub))
+                        continue;
+                    if (sub.cursor !== undefined && sub.cursor > tail) {
+                        drop(sub);
+                        reject(sub.res, 400, 'Last-Event-ID is ahead of current event history');
+                        continue;
+                    }
+                    sub.res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no' });
+                    sub.ready = true;
+                    checkpoint(sub, sub.cursor ?? tail);
+                }
+            }
+            if (!subscribers.size || stopped)
+                return;
+            const ready = [...subscribers].filter((sub) => sub.ready);
+            if (!ready.length)
+                return;
+            const after = Math.min(...ready.map((sub) => sub.cursor));
+            const page = await read(after);
+            for (const sub of ready) {
+                if (!subscribers.has(sub))
+                    continue;
+                for (const event of page.events) {
+                    if (event.id <= sub.cursor)
+                        continue;
+                    write(sub, `id: ${event.id}\nevent: task.completed\ndata: ${JSON.stringify({ task_id: event.task_id, timestamp: event.timestamp })}\n\n`);
+                    sub.cursor = event.id;
+                    if (!subscribers.has(sub))
+                        break;
+                }
+                if (!subscribers.has(sub))
+                    continue;
+                if (page.cursor > sub.cursor)
+                    checkpoint(sub, page.cursor);
+                if (!subscribers.has(sub))
+                    continue;
+                if (Date.now() - sub.heartbeat >= 15_000) {
+                    write(sub, ': heartbeat\n\n');
+                    sub.heartbeat = Date.now();
+                }
+            }
+        }
+        catch {
+            if (subscribers.size && !stopped)
+                log();
+            for (const sub of subscribers) {
+                if (!sub.res.headersSent)
+                    reject(sub.res, 503, 'Event history unavailable');
+                else
+                    sub.res.end();
+            }
+            subscribers.clear();
+        }
+        finally {
+            controller = undefined;
+        }
+    };
+    const schedule = () => {
+        if (stopped || running || !subscribers.size)
+            return;
+        running = tick().finally(() => {
+            running = undefined;
+            if (!stopped && subscribers.size)
+                timer = setTimeout(() => { timer = undefined; schedule(); }, 1000);
+        });
+    };
+    return {
+        handle(req, res) {
+            if (req.method !== 'GET') {
+                res.setHeader('Allow', 'GET');
+                return reject(res, 405, 'GET required');
+            }
+            const raw = req.headers['last-event-id'];
+            if (raw !== undefined && (typeof raw !== 'string' || !/^[0-9]{1,16}$/.test(raw) || !safe(Number(raw))))
+                return reject(res, 400, 'Last-Event-ID must be a nonnegative safe integer');
+            if (stopped || subscribers.size >= 64)
+                return reject(res, 503, 'Event stream limit reached');
+            const sub = { res, cursor: raw === undefined ? undefined : Number(raw), ready: false, heartbeat: Date.now() };
+            subscribers.add(sub);
+            res.once('close', () => drop(sub));
+            if (!timer)
+                schedule();
+        },
+        async close() {
+            stopped = true;
+            clearTimeout(timer);
+            controller?.abort();
+            for (const sub of subscribers)
+                sub.res.end();
+            subscribers.clear();
+            await running;
+        },
+    };
+}

package/dist-mcp/mcp/http.js

@@ -7,6 +7,7 @@ import { isIP } from 'node:net';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { createPinoteServer } from "./core.js";
+import { completionEvents } from "./events.js";
 import { pinoteToken } from "../token.js";
 function diagnostic(path, event) {
     const line = `${new Date().toISOString()} Pinote HTTP ${event}\n`;
@@ -37,6 +38,7 @@ export async function startPinoteHttpServer(options = {}) {
     // Fail startup if the configured log is not writable.
     appendFileSync(logPath, '', { mode: 0o600 });
     const log = (event) => diagnostic(logPath, event);
+    const events = completionEvents(() => log('event polling failed'));
     const digest = (value) => createHash('sha256').update(value).digest();
     const expected = digest(`Bearer ${token}`);
     const sessions = new Map();
@@ -66,10 +68,12 @@ export async function startPinoteHttpServer(options = {}) {
                 return reject(res, 403);
             if (req.headers.origin !== undefined && !options.allowedOrigins?.includes(req.headers.origin))
                 return reject(res, 403);
-            if (req.url !== '/mcp')
-                return reject(res, 404);
             if (stopping)
                 return reject(res, 503);
+            if (req.url === '/events')
+                return events.handle(req, res);
+            if (req.url !== '/mcp')
+                return reject(res, 404);
             if (!['GET', 'POST', 'DELETE'].includes(req.method ?? '')) {
                 res.setHeader('Allow', 'GET, POST, DELETE');
                 return reject(res, 405);
@@ -188,6 +192,7 @@ export async function startPinoteHttpServer(options = {}) {
         const closed = new Promise((ok) => listener.close(() => ok()));
         const force = setTimeout(() => listener.closeAllConnections(), 3000);
         try {
+            await events.close();
             await Promise.allSettled([...all].map((session) => session.server.close()));
             await closed;
         }

package/mcp/README.md

@@ -18,6 +18,11 @@ export PINOTE_NOTE_COMMAND="$PWD/.venv/bin/note"
 npm --prefix pi run serve
 ```
 
+After building, production installs may prune development/peer-only packages:
+`npm --prefix pi prune --omit=dev --omit=peer --ignore-scripts`.
+Run `npm --prefix pi run check:runtime` before restarting the service; its required
+terminal-width helpers are runtime dependencies, not development-only packages.
+
 The bearer token is mandatory, including on loopback: use at least 32 random
 non-whitespace characters. Store it in an owner-only regular file (mode `0600`),
 never commit or paste it into a conversation. For a new setup, after creating the
@@ -52,7 +57,7 @@ share. Point every client at the service instead.
 
 The Node listener is plaintext HTTP. **Never expose it directly to the public
 Internet.** Use a private VPN or a trusted HTTPS reverse proxy. The proxy must
-forward `/mcp`, bearer authorization, MCP headers and streaming responses without
+forward `/mcp` and `/events`, bearer authorization, MCP headers and streaming responses without
 buffering, preserve the external Host, and allow long-lived SSE connections.
 
 For example, a local reverse proxy serving `https://notes.example.net/mcp` forwards
@@ -113,8 +118,8 @@ serialize within this daemon and mutations use database/config revisions.
 
 The service bounds request bodies and session counts, and expires idle disconnected
 sessions. Active streams and operations are not expired. Shutdown closes sessions;
-a server restart preserves notes but requires clients to reconnect. No durable SSE
-replay, offline writes or automatic mutation retries are provided. After an
+a server restart preserves notes but requires clients to reconnect. MCP notifications have no durable
+replay; offline writes and automatic mutation retries are not provided. After an
 interrupted write, read fresh state before retrying: it may already have committed.
 
 The native terminal UI protocol and `pinote://agent-context` resource are internal
@@ -135,3 +140,52 @@ npm --prefix pi test
 Tests use temporary data and real HTTP/stdio connections, including authentication,
 shared notes, independent selections, conflicts and reconnects. Visual checks use
 Xvfb and private D-Bus; never point them at personal data.
+
+## Task-completion events
+
+`GET /events` on the same listener requires the same bearer token, Host allowlist
+and Origin policy as `/mcp`; it does not require an MCP session. Only GET is
+accepted (405 otherwise). Use `Accept: text/event-stream` and disable proxy buffering.
+The service requires `note` 0.21.0+ via `PINOTE_NOTE_COMMAND` (or `note` on PATH).
+
+With no `Last-Event-ID`, subscription starts at the current durable history tail,
+not with historical replay. Persist the numeric ID from **both** event types:
+
+```text
+id: 0
+event: checkpoint
+data: {}
+
+id: 3
+event: task.completed
+data: {"task_id":1,"timestamp":"2030-01-02T03:04:05.000000+00:00"}
+
+```
+
+An initial checkpoint is always sent, even at cursor 0. Completion IDs are event
+row IDs, not task IDs. Only committed `done` transitions emit completions, whether
+made by CLI, GUI or Pi. Re-marking done, starting/removing tasks and importing
+archived notes do not. Checkpoints advance past unrelated history; idle streams
+receive heartbeat comments every approximately 15 seconds.
+
+Reconnect with `Last-Event-ID: <persisted ID>` to scan subsequent durable history.
+Delivery is **at-least-once**, not exactly once; consumers should deduplicate by
+event ID. IDs must be nonnegative decimal integers no greater than
+9007199254740991. Malformed or future cursors return 400 with a plain-text error
+before streaming begins; unavailable history returns 503. Database replacement or
+restoring an older backup can invalidate a saved cursor and requires an explicit
+consumer decision to establish a fresh baseline.
+
+At most 64 streams (including pending subscriptions) are allowed; excess streams
+return 503. One shared poller scans at most 256 history rows per roughly one-second
+tick using the CLI, with one additional tail read when accepting new subscribers.
+Catchup therefore has bounded throughput. Slow writers are disconnected rather
+than buffered indefinitely and must reconnect. Poll failures close streams; the
+last disconnect stops polling, and service shutdown aborts the CLI and ends streams.
+
+For local integrations, `note events [--after CURSOR] [--limit N]` returns
+`{"cursor":number,"events":[{"id":number,"task_id":number,"timestamp":string}]}`.
+Without `--after` it returns the current tail and an empty array. With `--after`
+(including 0), it scans up to N rows in ascending order (default 256, range 1–1000),
+includes only completions, and advances the cursor across all scanned rows.
+It is a read-only operation with the same safe cursor range and future-cursor rejection.

package/mcp/events.ts

@@ -0,0 +1,116 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+const exec = promisify(execFile);
+const LIMIT = 256;
+type Page = { cursor: number; events: { id: number; task_id: number; timestamp: string }[] };
+type Subscriber = { res: ServerResponse; cursor: number | undefined; ready: boolean; heartbeat: number };
+const safe = (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/** One bounded CLI scan per tick, shared by all subscribers; no in-memory replay queue. */
+export function completionEvents(log: () => void) {
+  const subscribers = new Set<Subscriber>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let running: Promise<void> | undefined;
+  let controller: AbortController | undefined;
+  let stopped = false;
+  const reject = (res: ServerResponse, status: number, message: string) => {
+    res.writeHead(status, { 'Content-Type': 'text/plain' }); res.end(`${message}\n`);
+  };
+  const drop = (sub: Subscriber) => {
+    subscribers.delete(sub);
+    if (!subscribers.size) { clearTimeout(timer); timer = undefined; controller?.abort(); }
+  };
+  const write = (sub: Subscriber, frame: string) => {
+    // Disconnect rather than queue unbounded data. Resume from the last persisted ID.
+    if (!sub.res.write(frame)) { drop(sub); sub.res.destroy(); }
+  };
+  const checkpoint = (sub: Subscriber, id: number) => {
+    write(sub, `id: ${id}\nevent: checkpoint\ndata: {}\n\n`);
+    sub.cursor = id;
+  };
+  const read = async (after?: number): Promise<Page> => {
+    const { stdout } = await exec(process.env.PINOTE_NOTE_COMMAND || 'note',
+      ['--no-notify', 'events', '--limit', String(LIMIT), ...(after === undefined ? [] : ['--after', String(after)])],
+      { signal: controller!.signal, timeout: 10_000, maxBuffer: 256 * 1024 });
+    const page: Page = JSON.parse(stdout);
+    if (!safe(page.cursor) || after !== undefined && page.cursor < after || !Array.isArray(page.events) || page.events.length > LIMIT) throw new Error('Invalid event page');
+    let previous = after ?? 0;
+    for (const event of page.events) {
+      if (!safe(event.id) || event.id <= previous || event.id > page.cursor || !safe(event.task_id) || !event.task_id || typeof event.timestamp !== 'string' || event.timestamp.length > 128 || /[\r\n]/.test(event.timestamp)) throw new Error('Invalid completion');
+      previous = event.id;
+    }
+    return page;
+  };
+  const tick = async () => {
+    controller = new AbortController();
+    try {
+      const pending = [...subscribers].filter((sub) => !sub.ready);
+      if (pending.length) {
+        const tail = (await read()).cursor;
+        // New arrivals must not be validated against a tail captured before they joined.
+        for (const sub of pending) {
+          if (!subscribers.has(sub)) continue;
+          if (sub.cursor !== undefined && sub.cursor > tail) {
+            drop(sub); reject(sub.res, 400, 'Last-Event-ID is ahead of current event history'); continue;
+          }
+          sub.res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no' });
+          sub.ready = true;
+          checkpoint(sub, sub.cursor ?? tail);
+        }
+      }
+      if (!subscribers.size || stopped) return;
+      const ready = [...subscribers].filter((sub) => sub.ready);
+      if (!ready.length) return;
+      const after = Math.min(...ready.map((sub) => sub.cursor!));
+      const page = await read(after);
+      for (const sub of ready) {
+        if (!subscribers.has(sub)) continue;
+        for (const event of page.events) {
+          if (event.id <= sub.cursor!) continue;
+          write(sub, `id: ${event.id}\nevent: task.completed\ndata: ${JSON.stringify({ task_id: event.task_id, timestamp: event.timestamp })}\n\n`);
+          sub.cursor = event.id;
+          if (!subscribers.has(sub)) break;
+        }
+        if (!subscribers.has(sub)) continue;
+        if (page.cursor > sub.cursor!) checkpoint(sub, page.cursor);
+        if (!subscribers.has(sub)) continue;
+        if (Date.now() - sub.heartbeat >= 15_000) { write(sub, ': heartbeat\n\n'); sub.heartbeat = Date.now(); }
+      }
+    } catch {
+      if (subscribers.size && !stopped) log();
+      for (const sub of subscribers) {
+        if (!sub.res.headersSent) reject(sub.res, 503, 'Event history unavailable'); else sub.res.end();
+      }
+      subscribers.clear();
+    } finally { controller = undefined; }
+  };
+  const schedule = () => {
+    if (stopped || running || !subscribers.size) return;
+    running = tick().finally(() => {
+      running = undefined;
+      if (!stopped && subscribers.size) timer = setTimeout(() => { timer = undefined; schedule(); }, 1000);
+    });
+  };
+  return {
+    handle(req: IncomingMessage, res: ServerResponse) {
+      if (req.method !== 'GET') { res.setHeader('Allow', 'GET'); return reject(res, 405, 'GET required'); }
+      const raw = req.headers['last-event-id'];
+      if (raw !== undefined && (typeof raw !== 'string' || !/^[0-9]{1,16}$/.test(raw) || !safe(Number(raw)))) return reject(res, 400, 'Last-Event-ID must be a nonnegative safe integer');
+      if (stopped || subscribers.size >= 64) return reject(res, 503, 'Event stream limit reached');
+      const sub: Subscriber = { res, cursor: raw === undefined ? undefined : Number(raw), ready: false, heartbeat: Date.now() };
+      subscribers.add(sub);
+      res.once('close', () => drop(sub));
+      if (!timer) schedule();
+    },
+    async close() {
+      stopped = true;
+      clearTimeout(timer);
+      controller?.abort();
+      for (const sub of subscribers) sub.res.end();
+      subscribers.clear();
+      await running;
+    },
+  };
+}

package/mcp/http.ts

@@ -7,6 +7,7 @@ import { isIP } from 'node:net';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { createPinoteServer } from './core.ts';
+import { completionEvents } from './events.ts';
 import { pinoteToken } from '../token.ts';
 
 export interface PinoteHttpOptions {
@@ -48,6 +49,7 @@ export async function startPinoteHttpServer(options: PinoteHttpOptions = {}) {
   // Fail startup if the configured log is not writable.
   appendFileSync(logPath, '', { mode: 0o600 });
   const log = (event: string) => diagnostic(logPath, event);
+  const events = completionEvents(() => log('event polling failed'));
   const digest = (value: string) => createHash('sha256').update(value).digest();
   const expected = digest(`Bearer ${token}`);
   type Session = { transport: StreamableHTTPServerTransport; server: ReturnType<typeof createPinoteServer>; busy: number; streams: number; touched: number };
@@ -74,8 +76,9 @@ export async function startPinoteHttpServer(options: PinoteHttpOptions = {}) {
       }
       if (!allowedHosts.has(req.headers.host ?? '')) return reject(res, 403);
       if (req.headers.origin !== undefined && !options.allowedOrigins?.includes(req.headers.origin)) return reject(res, 403);
-      if (req.url !== '/mcp') return reject(res, 404);
       if (stopping) return reject(res, 503);
+      if (req.url === '/events') return events.handle(req, res);
+      if (req.url !== '/mcp') return reject(res, 404);
       if (!['GET', 'POST', 'DELETE'].includes(req.method ?? '')) { res.setHeader('Allow', 'GET, POST, DELETE'); return reject(res, 405); }
       const id = req.headers['mcp-session-id'];
       if (id !== undefined && (typeof id !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(id))) return reject(res, 400);
@@ -162,6 +165,7 @@ export async function startPinoteHttpServer(options: PinoteHttpOptions = {}) {
     const closed = new Promise<void>((ok) => listener.close(() => ok()));
     const force = setTimeout(() => listener.closeAllConnections(), 3000);
     try {
+      await events.close();
       await Promise.allSettled([...all].map((session) => session.server.close()));
       await closed;
     } finally { clearTimeout(force); log('stopped'); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.33.4",
+  "version": "0.34.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",
@@ -59,6 +59,7 @@
     "prepack": "npm run build:mcp",
     "mcp": "node dist-mcp/mcp/server.js",
     "serve": "node dist-mcp/mcp/http.js",
+    "check:runtime": "node --input-type=module -e \"await import('./dist-mcp/mcp/http.js')\"",
     "check": "tsc --noEmit",
     "test:unit": "node --test --experimental-strip-types tests/*.test.ts",
     "test:load": "node --test --experimental-strip-types test-load.ts test-remote-load.ts",
@@ -71,12 +72,12 @@
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.4.0",
-    "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "22.20.3",
     "typebox": "1.3.7",
     "typescript": "5.9.3"
   },
   "dependencies": {
+    "@earendil-works/pi-tui": "1.4.0",
     "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "^4.6.7"
   }