@saifymatteo/pi-extensions 0.1.3 → 0.1.5

package/packages/pi-session-retention/src/index.ts

@@ -121,6 +121,9 @@ async function trashSearchText(trash: string, batch: TrashBatch): Promise<{ sear
 export default function sessionRetention(pi: ExtensionAPI, options: { guard?: () => Promise<void>; now?: () => number } = {}) {
 	const now = options.now ?? Date.now;
 	let started = false;
+	let pendingAutomatic = false;
+	let automaticTimer: ReturnType<typeof setTimeout> | undefined;
+	let automatic: Promise<void> | undefined;
 	let maintaining = false;
 	let lifecycle = new AbortController();
 	let operation: Promise<unknown> | undefined;
@@ -159,10 +162,18 @@ export default function sessionRetention(pi: ExtensionAPI, options: { guard?: ()
 	};
 	pi.on("session_before_switch", preventSwitch);
 	pi.on("session_before_fork", preventSwitch);
+	function cancelAutomatic() {
+		pendingAutomatic = false;
+		if (automaticTimer !== undefined) clearTimeout(automaticTimer);
+		automaticTimer = undefined;
+	}
 	pi.on("session_shutdown", async (_event, ctx) => {
+		cancelAutomatic();
 		status(ctx, undefined);
 		lifecycle.abort();
 		closeDialog?.();
+		// Drain the background handler as well as file work before replacing its context.
+		await automatic?.catch(() => {});
 		// Never release a lock while a file operation can still be using it.
 		await operation?.catch(() => {});
 		started = false;
@@ -199,7 +210,13 @@ export default function sessionRetention(pi: ExtensionAPI, options: { guard?: ()
 			].join("\n");
 			if (previewOnly) { status(ctx, "Session cleanup: preview — no changes"); await ctx.ui.confirm("Preview only — nothing will be changed", summary, { signal }); return; }
 			if (!state.approved || state.paused) {
-				if (!manual && !count && !expired.length) { state.lastRun = time; await saveState(paths.trash, state); return; }
+				if (!manual) {
+					// Background discovery must not replace the editor with an approval dialog.
+					if (count || expired.length) ctx.ui.notify("Session cleanup is available. Run /session-cleanup to review and enable daily automatic cleanup.", "info");
+					state.lastRun = time;
+					await saveState(paths.trash, state);
+					return;
+				}
 				status(ctx, "Session cleanup: awaiting approval…");
 				const approved = await ctx.ui.confirm("Enable daily session cleanup?", `${summary}\n\nApprove this cleanup and future automatic cleanup at startup (at most daily)?`, { signal });
 				signal.throwIfAborted();
@@ -228,13 +245,33 @@ export default function sessionRetention(pi: ExtensionAPI, options: { guard?: ()
 		});
 	}
 
-	pi.on("session_start", async (_event, ctx) => {
+	function scheduleAutomatic(ctx: ExtensionContext) {
+		if (!pendingAutomatic || automaticTimer !== undefined || automatic || maintaining) return;
+		const signal = lifecycle.signal;
+		if (signal.aborted) return;
+		// Yield before starting maintenance; startup never awaits this task.
+		automaticTimer = setTimeout(() => {
+			automaticTimer = undefined;
+			if (signal.aborted || !pendingAutomatic || !ctx.isIdle() || maintaining) return;
+			pendingAutomatic = false;
+			automatic = cleanup(ctx, false)
+				.catch((error) => {
+					if (!signal.aborted) {
+						try { ctx.ui.notify(message(error), "warning"); } catch { /* UI failures must not reject a detached task. */ }
+					}
+				})
+				.finally(() => { automatic = undefined; });
+		}, 0);
+		automaticTimer.unref();
+	}
+	pi.on("session_start", (_event, ctx) => {
 		if (lifecycle.signal.aborted) lifecycle = new AbortController();
 		if (started || ctx.mode !== "tui" || !ctx.sessionManager.getSessionFile()) return;
 		started = true;
-		const signal = lifecycle.signal;
-		try { await cleanup(ctx, false); } catch (error) { if (!signal.aborted) ctx.ui.notify(message(error), "warning"); }
+		pendingAutomatic = true;
+		scheduleAutomatic(ctx);
 	});
+	pi.on("agent_settled", (_event, ctx) => { scheduleAutomatic(ctx); });
 
 	pi.registerCommand("session-cleanup", {
 		description: "Clean inactive session families [preview|pause]",
@@ -250,6 +287,7 @@ export default function sessionRetention(pi: ExtensionAPI, options: { guard?: ()
 			const signal = lifecycle.signal;
 			const action = args.trim();
 			if (!["", "preview", "pause"].includes(action)) return ctx.ui.notify("Usage: /session-cleanup [preview|pause]", "info");
+			cancelAutomatic();
 			try {
 				if (action === "pause") {
 					const paths = storePaths(ctx);
@@ -265,6 +303,7 @@ export default function sessionRetention(pi: ExtensionAPI, options: { guard?: ()
 		description: "Search Trash by names, first prompts, IDs or paths; restore a whole family",
 		handler: async (args, ctx) => {
 			if (ctx.mode !== "tui") return ctx.ui.notify("Session Trash requires interactive mode.", "warning");
+			cancelAutomatic();
 			const signal = lifecycle.signal;
 			try {
 				await ctx.waitForIdle();

package/packages/pi-session-retention/test/startup.test.mjs

@@ -0,0 +1,229 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile, readFile, access, rm, realpath, utimes } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setImmediate } from 'node:timers/promises';
+import { loadExtension } from '../../../test/load-extension.mjs';
+import * as core from '../src/core.ts';
+
+const deferred = () => {
+  let resolve;
+  const promise = new Promise(done => { resolve = done; });
+  return { promise, resolve };
+};
+
+async function harness(t, { old = false, state, holdScan = false, scanError = false } = {}) {
+  const dir = await mkdtemp(join(await realpath(tmpdir()), 'pi-retention-startup-'));
+  const root = join(dir, 'sessions');
+  const file = join(root, 'session.jsonl');
+  const now = Date.now();
+  const stamp = old ? now - core.RETENTION_MS - 60_000 : now;
+  await mkdir(root);
+  await writeFile(file, JSON.stringify({ type: 'session', id: 'fixture', timestamp: new Date(stamp).toISOString() }) + '\n');
+  await utimes(file, new Date(stamp), new Date(stamp));
+  const entered = deferred(), release = deferred(), finished = deferred(), notified = deferred();
+  const timers = new Map(), hooks = {}, commands = {}, notifications = [], confirmations = [];
+  let scans = 0, probes = 0, nextTimer = 0;
+  const extension = loadExtension(new URL('../src/index.ts', import.meta.url), {
+    './core.ts': {
+      ...core,
+      RetentionStore: class extends core.RetentionStore {
+        async scan(options) {
+          scans++;
+          entered.resolve();
+          if (holdScan) await release.promise;
+          if (scanError) throw new Error('fixture scan failed');
+          return super.scan(options);
+        }
+      },
+    },
+  }, {
+    performance,
+    setTimeout: callback => { const id = { id: ++nextTimer, unref() {} }; timers.set(id, callback); return id; },
+    clearTimeout: id => { timers.delete(id); },
+  });
+  extension.default({
+    on: (name, handler) => { hooks[name] = handler; },
+    registerCommand: (name, command) => { commands[name] = command; },
+  }, { now: () => now, guard: async () => { probes++; } });
+  const ctx = {
+    mode: 'tui',
+    idle: true,
+    isIdle() { return this.idle; },
+    sessionManager: { getSessionDir: () => root, getCwd: () => dir, getSessionFile: () => join(root, 'active.jsonl') },
+    waitForIdle: async () => {},
+    ui: {
+      custom: async () => undefined,
+      setStatus: (_key, text) => { if (text === undefined) finished.resolve(); },
+      notify: (text, level) => { notifications.push({ text, level }); notified.resolve(); },
+      confirm: async (...args) => { confirmations.push(args); return true; },
+    },
+  };
+  const { trash } = extension.storePaths(ctx);
+  if (state) {
+    await mkdir(trash, { recursive: true });
+    await writeFile(join(trash, 'settings.json'), JSON.stringify({ approved: true, paused: false, lastRun: 0, ...state }));
+  }
+  t.after(async () => {
+    release.resolve();
+    await hooks.session_shutdown({}, ctx);
+    await rm(dir, { recursive: true, force: true });
+  });
+  return {
+    ctx, hooks, commands, timers, notifications, confirmations, file, trash, now, entered, release, finished, notified,
+    get scans() { return scans; },
+    get probes() { return probes; },
+    runTimer() {
+      assert.equal(timers.size, 1);
+      const [id, callback] = timers.entries().next().value;
+      timers.delete(id);
+      callback();
+    },
+  };
+}
+
+test('startup returns before scanning; shutdown drains background work before releasing its lock', async t => {
+  const h = await harness(t, { holdScan: true });
+  assert.equal(h.hooks.session_start({}, h.ctx), undefined);
+  assert.equal(h.scans, 0);
+  assert.equal(h.timers.size, 1);
+  h.hooks.session_start({}, h.ctx);
+  assert.equal(h.timers.size, 1);
+  h.runTimer();
+  await h.entered.promise;
+  assert.equal(h.hooks.session_before_switch({}, h.ctx).cancel, true);
+  assert.equal(h.hooks.session_before_fork({}, h.ctx).cancel, true);
+  let stopped = false;
+  const shutdown = h.hooks.session_shutdown({}, h.ctx).then(() => { stopped = true; });
+  await Promise.resolve();
+  assert.equal(stopped, false);
+  await access(join(h.trash, '.maintenance.lock'));
+  h.release.resolve();
+  await shutdown;
+  await assert.rejects(access(join(h.trash, '.maintenance.lock')), { code: 'ENOENT' });
+  assert.equal(h.notifications.some(item => item.level === 'warning' && /aborted/i.test(item.text)), false);
+});
+
+test('busy startup defers until agent_settled and never schedules duplicate scans', async t => {
+  const h = await harness(t);
+  h.ctx.idle = false;
+  h.hooks.session_start({}, h.ctx);
+  h.runTimer();
+  assert.equal(h.scans, 0);
+  assert.equal(h.timers.size, 0);
+  h.ctx.idle = true;
+  h.hooks.agent_settled({}, h.ctx);
+  h.hooks.agent_settled({}, h.ctx);
+  h.runTimer();
+  await h.finished.promise;
+  assert.equal(h.scans, 1);
+  h.hooks.agent_settled({}, h.ctx);
+  assert.equal(h.timers.size, 0);
+});
+
+test('automatic discovery notifies instead of opening approval; explicit cleanup can approve', async t => {
+  const h = await harness(t, { old: true });
+  h.hooks.session_start({}, h.ctx);
+  h.runTimer();
+  await h.finished.promise;
+  assert.equal(h.confirmations.length, 0);
+  assert.ok(h.notifications.some(item => /\/session-cleanup/.test(item.text)));
+  await access(h.file);
+  assert.equal(h.probes, 0);
+  const state = JSON.parse(await readFile(join(h.trash, 'settings.json'), 'utf8'));
+  assert.equal(state.approved, false);
+  assert.equal(state.lastRun, h.now);
+  await h.commands['session-cleanup'].handler('', h.ctx);
+  assert.equal(h.confirmations.length, 1);
+  assert.deepEqual(h.notifications.filter(item => item.level === 'error'), []);
+  assert.ok(h.probes > 0);
+  await assert.rejects(access(h.file), { code: 'ENOENT' });
+});
+
+test('previously approved automatic cleanup still moves eligible sessions without a dialog', async t => {
+  const h = await harness(t, { old: true, state: {} });
+  h.hooks.session_start({}, h.ctx);
+  h.runTimer();
+  await h.finished.promise;
+  assert.equal(h.confirmations.length, 0);
+  assert.deepEqual(h.notifications.filter(item => item.level === 'warning'), []);
+  assert.ok(h.probes > 0);
+  await assert.rejects(access(h.file), { code: 'ENOENT' });
+});
+
+test('daily and paused settings still skip scans in the background', async t => {
+  for (const state of [{ lastRun: Date.now() }, { paused: true }]) {
+    await t.test(JSON.stringify(state), async t => {
+      const h = await harness(t, { state });
+      h.hooks.session_start({}, h.ctx);
+      h.runTimer();
+      await h.finished.promise;
+      assert.equal(h.scans, 0);
+      assert.equal(h.probes, 0);
+    });
+  }
+});
+
+test('shutdown cancels queued maintenance and a new session can schedule again', async t => {
+  const h = await harness(t);
+  h.hooks.session_start({}, h.ctx);
+  await h.hooks.session_shutdown({}, h.ctx);
+  assert.equal(h.timers.size, 0);
+  assert.equal(h.scans, 0);
+  h.hooks.session_start({}, h.ctx);
+  h.runTimer();
+  await h.entered.promise;
+  await h.hooks.session_shutdown({}, h.ctx);
+  assert.equal(h.scans, 1);
+});
+
+test('explicit maintenance cancels queued automatic work', async t => {
+  for (const [command, args] of [['session-cleanup', 'pause'], ['session-trash', '']]) {
+    await t.test(command, async t => {
+      const h = await harness(t);
+      h.hooks.session_start({}, h.ctx);
+      await h.commands[command].handler(args, h.ctx);
+      assert.equal(h.timers.size, 0);
+      h.hooks.agent_settled({}, h.ctx);
+      assert.equal(h.timers.size, 0);
+      assert.equal(h.scans, 0);
+      assert.deepEqual(h.notifications.filter(item => item.level === 'error'), []);
+    });
+  }
+});
+
+test('non-TUI modes and sessions without a file schedule no maintenance', async t => {
+  const h = await harness(t);
+  for (const mode of ['print', 'json', 'rpc']) {
+    h.ctx.mode = mode;
+    h.hooks.session_start({}, h.ctx);
+    assert.equal(h.timers.size, 0);
+  }
+  h.ctx.mode = 'tui';
+  h.ctx.sessionManager.getSessionFile = () => undefined;
+  h.hooks.session_start({}, h.ctx);
+  assert.equal(h.timers.size, 0);
+});
+
+test('background failures are reported and release the maintenance lock', async t => {
+  const h = await harness(t, { scanError: true });
+  h.hooks.session_start({}, h.ctx);
+  h.runTimer();
+  await h.notified.promise;
+  await h.hooks.session_shutdown({}, h.ctx);
+  assert.ok(h.notifications.some(item => /fixture scan failed/.test(item.text)));
+  await assert.rejects(access(join(h.trash, '.maintenance.lock')), { code: 'ENOENT' });
+});
+
+test('a failed UI notification cannot cause an unhandled background rejection', async t => {
+  const h = await harness(t, { scanError: true });
+  const notify = h.ctx.ui.notify;
+  h.ctx.ui.notify = (...args) => { notify(...args); throw new Error('fixture UI failed'); };
+  h.hooks.session_start({}, h.ctx);
+  h.runTimer();
+  await h.notified.promise;
+  // Give detached promise rejections a turn to surface in the test runner.
+  await setImmediate();
+  await assert.rejects(access(join(h.trash, '.maintenance.lock')), { code: 'ENOENT' });
+});

package/packages/pi-skill-usage-log/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Release notes are recorded from 0.1.3 onward.
+
+## [Unreleased]
+
+## [0.1.4]
+
+### Added
+
+- Include package release notes in Pi 1.5.0's Extension Updates.
+
+## [0.1.3]
+
+### Fixed
+
+- Classify the package as an extension in the Pi package gallery.
+- Show the package screenshot as its gallery preview.

package/packages/pi-skill-usage-log/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-skill-usage-log",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
@@ -10,6 +10,7 @@
   "files": [
     "src",
     "README.md",
+    "CHANGELOG.md",
     "NOTICE.md",
     "LICENSE"
   ],

package/packages/pi-tool-usage-log/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Release notes are recorded from 0.1.3 onward.
+
+## [Unreleased]
+
+## [0.1.4]
+
+### Added
+
+- Include package release notes in Pi 1.5.0's Extension Updates.
+
+## [0.1.3]
+
+### Fixed
+
+- Classify the package as an extension in the Pi package gallery.
+- Show the package screenshot as its gallery preview.

package/packages/pi-tool-usage-log/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-tool-usage-log",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
@@ -10,6 +10,7 @@
   "files": [
     "src",
     "README.md",
+    "CHANGELOG.md",
     "NOTICE.md",
     "LICENSE"
   ],

package/packages/pi-tts/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Release notes are recorded from 0.1.3 onward.
+
+## [Unreleased]
+
+## [0.1.4]
+
+### Added
+
+- Include package release notes in Pi 1.5.0's Extension Updates.
+
+## [0.1.3]
+
+### Fixed
+
+- Classify the package as an extension in the Pi package gallery.
+- Show the package screenshot as its gallery preview.

package/packages/pi-tts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-tts",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
@@ -11,6 +11,7 @@
     "src",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "NOTICE.md",
     "LICENSE"
   ],

package/packages/pi-user-image-previews/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Release notes are recorded from 0.1.3 onward.
+
+## [Unreleased]
+
+## [0.1.4]
+
+### Added
+
+- Include package release notes in Pi 1.5.0's Extension Updates.
+
+## [0.1.3]
+
+### Fixed
+
+- Classify the package as an extension in the Pi package gallery.
+- Show the package screenshot as its gallery preview.

package/packages/pi-user-image-previews/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-user-image-previews",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Adds collapsible UI-only previews for newly submitted image attachments.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -11,6 +11,7 @@
   "files": [
     "src",
     "README.md",
+    "CHANGELOG.md",
     "NOTICE.md",
     "LICENSE"
   ],

package/packages/pi-vision/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Release notes are recorded from 0.1.3 onward.
+
+## [Unreleased]
+
+## [0.1.4]
+
+### Added
+
+- Include package release notes in Pi 1.5.0's Extension Updates.
+
+## [0.1.3]
+
+### Fixed
+
+- Classify the package as both an extension and a skill package in the Pi package gallery.
+- Show the package screenshot as its gallery preview.

package/packages/pi-vision/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-vision",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
@@ -12,6 +12,7 @@
     "src",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "NOTICE.md",
     "LICENSE",
     "skills"

package/packages/pi-wait/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Release notes are recorded from 0.1.3 onward.
+
+## [Unreleased]
+
+## [0.1.4]
+
+### Added
+
+- Include package release notes in Pi 1.5.0's Extension Updates.
+
+## [0.1.3]
+
+### Fixed
+
+- Classify the package as an extension in the Pi package gallery.
+- Show the package screenshot as its gallery preview.

package/packages/pi-wait/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-wait",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
@@ -11,6 +11,7 @@
     "src",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "NOTICE.md",
     "LICENSE"
   ],

package/packages/pi-zvec/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+Release notes are recorded from 0.1.3 onward.
+
+## [Unreleased]
+
+## [0.1.5]
+
+### Added
+
+- Include package release notes in Pi 1.5.0's Extension Updates.
+
+## [0.1.4]
+
+### Fixed
+
+- Defer CLI checks, configuration, and index initialization until after session startup to avoid blocking Pi.
+- Cancel stale initialization when the active session changes.
+
+## [0.1.3]
+
+### Fixed
+
+- Classify the package as an extension in the Pi package gallery.
+- Show the package screenshot as its gallery preview.

package/packages/pi-zvec/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saifymatteo/pi-zvec",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "license": "AGPL-3.0-only",
   "type": "module",
   "keywords": [
@@ -11,6 +11,7 @@
     "src",
     "examples",
     "README.md",
+    "CHANGELOG.md",
     "NOTICE.md",
     "LICENSE"
   ],