pi-note 0.34.0 → 0.35.0

package/README.md

@@ -92,12 +92,55 @@ missing/stale revisions fail closed. Resume, reload and `/new` never replay the
 handoff or replace another selection. Pi keeps its normal endpoint/token settings.
 With pi-note 0.33.4+, completing the launched task from the menu, footer or
 **Complete task and exit** exits Pi directly, so Kitty closes its dedicated tab
-(or the standalone window's last tab). Completion never runs Git commands;
-Git configuration and network availability do not affect closing the session.
+(or the standalone window's last tab). Pinote itself never runs Git commands;
+optional local completion hooks can briefly delay closing (see below).
 This ownership survives `/reload`, but not `/new`, resume, fork, tree navigation
 or process restart. Completing a different task or an externally completed task
 does not close Pi; failed/uncertain completion stays open.
 
+### Local completion event (pi-note 0.35.0+)
+
+Trusted sibling extensions can listen on `pi.events` for `pinote:task-completed`:
+
+```ts
+pi.events.on('pinote:task-completed', (event) => {
+  const { taskId, signal, waitUntil } = event as {
+    taskId: number;
+    signal: AbortSignal;
+    waitUntil(work: Promise<unknown>): void;
+  };
+  waitUntil(Promise.resolve().then(() => doLocalWork(taskId, signal))); // Register before any await.
+});
+```
+
+This local event fires exactly once only after this client's acknowledged **Done**
+action clears a valid selected task, across menu, footer and exit/new-session paths.
+`taskId` is the original positive safe-integer task ID, not the cleared selection.
+External completions, notifications, clear-selection actions and failed/stale Done
+attempts do not emit it. Pinote does not submit a model prompt for this event.
+
+Pi's event bus is synchronous fire-and-forget: returning an async handler's promise
+is insufficient. Call `waitUntil` during dispatch; late registrations are ignored.
+Put potentially throwing work inside the registered promise, as above. Exceptions
+thrown by the listener itself before registration are handled by Pi's own logger,
+which may print their raw text; Pinote cannot intercept those bus errors.
+All registered work is awaited outside Pinote's serial queue (so listeners may use
+`pinote:query-current`) before Done returns or a launched session auto-exits.
+Without registered work, completion proceeds immediately. Ordinary Done still
+keeps the conversation open.
+
+There is one fixed **25-second total deadline**, shared by all listeners. The signal
+aborts on session lifetime cancellation, deadline, or hook settlement; listeners
+must honor it and avoid blocking synchronous work. Timers cannot preempt JavaScript
+that blocks the event loop. On runtime teardown, `signal.reason` carries Pi's
+shutdown reason (`quit`, `reload`, `new`, `resume`, or `fork`). A listener with its
+own awaited shutdown handler may finish bounded work on `quit`; other cancellation
+still stops its work. Hook rejection, timeout or cancellation never undo an
+acknowledged completion, invalidate its state, or retry remote writes. Registered
+promise rejections and timeouts produce only a generic warning when UI is available;
+Pinote does not display their error or response text. This is a trusted local extension API, not remote task
+instructions or authorization to run models or external actions.
+
 ### Agent tools and context
 
 The extension registers `pinote_search`, `pinote_get_task`, `pinote_get_current`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-note",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Persistent pinote tasks, Markdown handoffs, and task status for Pi",
   "license": "MIT",
   "type": "module",

package/remote/completion.ts

@@ -0,0 +1,50 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+export interface TaskCompletedEvent {
+  taskId: number;
+  signal: AbortSignal;
+  /** Register during synchronous event dispatch, before the listener's first await. */
+  waitUntil(work: Promise<unknown>): void;
+}
+
+/** Local, best-effort work only; never turn an acknowledged Done into a failed write. */
+export async function taskCompleted(
+  events: Pick<ExtensionAPI['events'], 'emit'>,
+  taskId: number,
+  lifetime: AbortSignal,
+  warn: () => void,
+): Promise<void> {
+  if (lifetime.aborted) return;
+  const controller = new AbortController();
+  const work: Promise<unknown>[] = [];
+  let accepting = true, warned = false;
+  const warning = () => {
+    if (warned) return;
+    warned = true;
+    try { warn(); } catch { /* Diagnostics must not affect completion. */ }
+  };
+  let finish!: () => void;
+  const cancelled = new Promise<void>((resolve) => { finish = resolve; });
+  const cancel = () => { controller.abort(lifetime.reason); finish(); };
+  lifetime.addEventListener('abort', cancel, { once: true });
+  // One deadline covers dispatch and all listeners, not 25 seconds per listener.
+  const timer = setTimeout(() => { warning(); cancel(); }, 25_000);
+  try {
+    try {
+      events.emit('pinote:task-completed', {
+        taskId, signal: controller.signal,
+        waitUntil(promise: Promise<unknown>) {
+          const registered = accepting;
+          const observed = Promise.resolve(promise).catch(() => { if (registered && !controller.signal.aborted) warning(); });
+          if (registered) work.push(observed);
+        },
+      } satisfies TaskCompletedEvent);
+    } catch { warning(); } // Dispatch failures only; Pi itself catches listener exceptions.
+    finally { accepting = false; }
+    if (work.length) await Promise.race([Promise.all(work), cancelled]);
+  } finally {
+    clearTimeout(timer);
+    lifetime.removeEventListener('abort', cancel);
+    controller.abort();
+  }
+}

package/remote/session.ts

@@ -32,6 +32,7 @@ export class RemoteSession {
   view?: NativeView;
   fullscreen = false;
   onChange = () => {};
+  onCompleted?: (taskId: number, signal: AbortSignal) => Promise<void>;
   private config: RemoteConfig;
   private persist: (saved: SavedState) => void;
   private factory: PeerFactory;
@@ -49,8 +50,8 @@ export class RemoteSession {
     this.persist(this.saved);
     await this.refresh(true);
   }
-  async stop(): Promise<void> {
-    this.active = false; this.epoch++; this.lifetime.abort(); this.connection?.abort();
+  async stop(reason?: string): Promise<void> {
+    this.active = false; this.epoch++; this.lifetime.abort(reason); this.connection?.abort();
     clearTimeout(this.refreshTimer); this.refreshTimer = undefined; this.dirty = false; this.refreshing = false;
     const peer = this.peer; this.peer = undefined; this.view = undefined;
     this.queue = Promise.resolve(); this.onChange();
@@ -171,8 +172,10 @@ export class RemoteSession {
       } catch (error) { if (current()) this.failed(error, mutation && attempted); throw new RemoteFailure(mutation && attempted); }
     }, signal);
   }
-  action(view: NativeView, control: NativeControl, value?: NativeControl['value'], allow = () => true): Promise<{ draft?: string; preview?: string }> {
-    return this.serial(async () => {
+  async action(view: NativeView, control: NativeControl, value?: NativeControl['value'], allow = () => true): Promise<{ draft?: string; preview?: string }> {
+    const signal = this.signal;
+    let completedId: number | undefined;
+    const result = await this.serial(async () => {
       const current = this.current(); let attempted = false;
       if (!allow()) throw new RemoteFailure(false, true);
       const latest = this.view?.controls.find((c) => c.id === control.id && c.kind === control.kind);
@@ -180,10 +183,14 @@ export class RemoteSession {
       try {
         const peer = await this.connected(true);
         if (!allow()) throw new RemoteFailure(false, true);
+        const taskId = this.view?.state.selectedId;
         attempted = true;
         const result = await peer.action({ uri: 'pinote://ui', action: control.id, revision: control.revision ?? view.revision, ...(value === undefined ? {} : { value }), _meta: this.meta() }, this.signal);
         if (!current()) throw new RemoteFailure(true);
         this.apply(result.view);
+        if (control.id === 'done' && control.kind === 'action' &&
+            typeof taskId === 'number' && Number.isSafeInteger(taskId) && taskId > 0 &&
+            result.view.state.selectedId == null) completedId = taskId;
         return result;
       } catch (error) {
         if (!attempted && error instanceof RemoteFailure && error.stale) throw error;
@@ -191,5 +198,11 @@ export class RemoteSession {
         throw new RemoteFailure(attempted);
       }
     });
+    // Outside the serial queue: trusted listeners may query this session themselves.
+    // Hook failures cannot invalidate or replay the acknowledged remote mutation.
+    if (completedId !== undefined && !signal.aborted) {
+      try { await this.onCompleted?.(completedId, signal); } catch { /* Best effort only. */ }
+    }
+    return result;
   }
 }

package/remote.ts

@@ -6,6 +6,7 @@ import { registerTools } from './remote/tools.ts';
 import { registerPreview, RemoteUI } from './remote/ui.ts';
 import { registerRemoteExit } from './remote/exit.ts';
 import { editorText } from './remote/protocol.ts';
+import { taskCompleted } from './remote/completion.ts';
 
 // Only an accepted /new (previousSessionFile) may carry this process-local selection.
 // Reload/resume/fork restore branch entries, never this map or a folder-global store.
@@ -46,6 +47,9 @@ export default function pinoteRemote(pi: ExtensionAPI): void {
     try {
       const config = remoteConfig();
       session = new RemoteSession(config, (saved) => pi.appendEntry(ENTRY_TYPE, saved));
+      session.onCompleted = (taskId, signal) => taskCompleted(pi.events, taskId, signal, () => {
+        if (ctx.hasUI) ctx.ui.notify('Pinote: completion hook did not finish successfully. The task completion remains confirmed.', 'warning');
+      });
       launchKey = `${config.scope}:${ctx.sessionManager.getSessionId()}`;
       ui = new RemoteUI(pi, session, ownsLaunch);
       ui.attach(ctx);
@@ -99,7 +103,7 @@ export default function pinoteRemote(pi: ExtensionAPI): void {
       if (transfers.size >= 32) transfers.delete(transfers.keys().next().value!);
       transfers.set(file, saved);
     }
-    ui?.detach(); await session?.stop();
+    ui?.detach(); await session?.stop(event.reason);
   });
   pi.on('before_agent_start', async (event, ctx) => {
     let text: string;