@saifymatteo/pi-extensions 0.0.0-stage → 0.1.0

package/packages/pi-prestart-working/README.md

@@ -0,0 +1,25 @@
+# @saifymatteo/pi-prestart-working
+
+## Purpose and registrations
+
+Shows Pi's native "Working" spinner, labelled with the extension currently blocking (e.g. `⠙ Loading hindsight-coding-agents`), while `before_agent_start` hooks run. Pi only raises its working indicator at `turn_start`, so slow handlers otherwise leave the UI silent. No tools, commands, or configuration.
+
+## Compatibility and safety
+
+Patches `ExtensionRunner.prototype.emitBeforeAgentStart` once per process (guarded by a global symbol, so `/reload` does not double-wrap) and relies on the runner's internal `extensions`, `handlers`, and `uiContext` shapes. These are host internals, not a public API: a host release that renames them breaks the patch. The label is the nearest `package.json` name (scope dropped), else the file name. No-op without UI.
+
+Imported host APIs are declared as peer dependencies and supplied by the Pi host. A `*` peer range describes host resolution, not a guarantee of compatibility with every release.
+
+## Running locally
+
+From the repository root:
+
+```sh
+pi -e ./packages/pi-prestart-working
+```
+
+Follow the [root README](../../README.md#isolated-sessions) to avoid loading an existing copy of the extension.
+
+## Status
+
+Part of the [pi-extensions](../../README.md) collection. No personal settings or credentials are included; see [NOTICE.md](NOTICE.md) for licensing and provenance.

package/packages/pi-prestart-working/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@saifymatteo/pi-prestart-working",
+  "version": "0.1.0",
+  "description": "Show a labelled Working spinner while before_agent_start hooks run.",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saifymatteo/pi-extensions.git",
+    "directory": "packages/pi-prestart-working"
+  }
+}

package/packages/pi-prestart-working/src/index.ts

@@ -0,0 +1,86 @@
+/**
+ * Show Pi's native "Working" spinner, labelled with the extension currently
+ * blocking, while before_agent_start hooks run (e.g. "⠙ Loading hindsight-coding-agents").
+ *
+ * Pi only raises its working indicator at turn_start, after every
+ * before_agent_start handler has finished, so slow handlers (Hindsight's memory
+ * recall can take ~20 s) leave the UI silent. Handlers run in extension load
+ * order and live inside Pi's ExtensionRunner, so no event tells an extension
+ * which one is running. This wraps ExtensionRunner.prototype.emitBeforeAgentStart
+ * once per process: each handler is wrapped just long enough for Pi to snapshot
+ * it, and the wrapper names its extension in the working message before it runs.
+ *
+ * The run is already active at that point, so setWorkingVisible(true) shows the
+ * spinner immediately. The patch reads UI from the runner itself, so it survives
+ * /reload without holding a stale extension ctx.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import { ExtensionRunner } from "@earendil-works/pi-coding-agent";
+
+const PATCHED = Symbol.for("settings.prestart-working.patched");
+const EVENT = "before_agent_start";
+
+type Handler = (...args: unknown[]) => unknown;
+type Ext = { path: string; handlers: Map<string, Handler[]> };
+type Runner = {
+	extensions: Ext[];
+	hasUI(): boolean;
+	uiContext: { setWorkingMessage(m?: string): void; setWorkingVisible(v: boolean): void };
+	emitBeforeAgentStart(...args: unknown[]): Promise<unknown>;
+};
+
+const names = new Map<string, string>();
+
+/** Nearest package.json name (scope dropped), else the file name: "hindsight-coding-agents", "zvec". */
+export function extensionLabel(path: string): string {
+	const cached = names.get(path);
+	if (cached) return cached;
+	let label = basename(path, extname(path));
+	if (label === "index" || label === "pi") {
+		for (let dir = dirname(path); dir !== dirname(dir); dir = dirname(dir)) {
+			const pkg = join(dir, "package.json");
+			if (!existsSync(pkg)) continue;
+			try {
+				const name = JSON.parse(readFileSync(pkg, "utf8")).name;
+				if (typeof name === "string") label = name.replace(/^@[^/]+\//, "");
+			} catch {}
+			break;
+		}
+	}
+	names.set(path, label);
+	return label;
+}
+
+export default function () {
+	const proto = (ExtensionRunner as unknown as { prototype: Runner & { [PATCHED]?: true } }).prototype;
+	if (proto[PATCHED]) return;
+	proto[PATCHED] = true;
+	const original = proto.emitBeforeAgentStart;
+
+	proto.emitBeforeAgentStart = function (this: Runner, ...args: unknown[]) {
+		if (!this.hasUI()) return original.apply(this, args);
+		const ui = this.uiContext;
+		const swapped: [Ext, Handler[]][] = [];
+		for (const ext of this.extensions) {
+			const list = ext.handlers.get(EVENT);
+			if (!list?.length) continue;
+			const label = extensionLabel(ext.path);
+			swapped.push([ext, list]);
+			ext.handlers.set(
+				EVENT,
+				list.map((h) => (...a: unknown[]) => {
+					ui.setWorkingMessage(`Loading ${label}`);
+					return h(...a);
+				}),
+			);
+		}
+		ui.setWorkingVisible(true);
+		// Pi snapshots the handler lists synchronously before its first await,
+		// so the originals can go back right away (keeps pi.on() unsubscribe intact).
+		const result = original.apply(this, args);
+		for (const [ext, list] of swapped) ext.handlers.set(EVENT, list);
+		return result.finally(() => ui.setWorkingMessage(undefined));
+	};
+}

package/packages/pi-prestart-working/test/behavior.test.mjs

@@ -0,0 +1,56 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+// Mirrors Pi's ExtensionRunner.emitBeforeAgentStart: snapshot handler lists
+// synchronously, then await each handler in extension order.
+class FakeRunner {
+  log = [];
+  extensions = [];
+  uiContext = {
+    setWorkingMessage: m => this.log.push(`msg:${m ?? '<default>'}`),
+    setWorkingVisible: v => this.log.push(`visible:${v}`),
+  };
+  hasUI() { return true; }
+  async emitBeforeAgentStart() {
+    const snapshot = this.extensions.map(e => (e.handlers.get('before_agent_start') ?? []).slice());
+    for (const handlers of snapshot) for (const h of handlers) await h();
+    return 'result';
+  }
+}
+
+test('labels the spinner with each blocking extension, then restores', async t => {
+  const { default: install, extensionLabel } = loadExtension(new URL('../src/index.ts', import.meta.url), {
+    '@earendil-works/pi-coding-agent': { ExtensionRunner: FakeRunner },
+  });
+  install();
+  install(); // second load (e.g. /reload) must not double-wrap
+
+  const pkgDir = mkdtempSync(join(tmpdir(), 'prestart-'));
+  t.after(() => rmSync(pkgDir, { recursive: true, force: true }));
+  mkdirSync(join(pkgDir, 'dist'));
+  writeFileSync(join(pkgDir, 'package.json'), JSON.stringify({ name: '@vectorize-io/hindsight-coding-agents' }));
+
+  const runner = new FakeRunner();
+  const slow = async () => { runner.log.push('run:hindsight'); };
+  const fast = () => { runner.log.push('run:zvec'); };
+  runner.extensions = [
+    { path: join(pkgDir, 'dist', 'pi.js'), handlers: new Map([['before_agent_start', [slow]]]) },
+    { path: '/x/extensions/zvec.ts', handlers: new Map([['before_agent_start', [fast]]]) },
+    { path: '/x/extensions/other.ts', handlers: new Map() },
+  ];
+
+  assert.equal(await runner.emitBeforeAgentStart(), 'result');
+  assert.deepEqual(runner.log, [
+    'visible:true',
+    'msg:Loading hindsight-coding-agents', 'run:hindsight',
+    'msg:Loading zvec', 'run:zvec',
+    'msg:<default>',
+  ]);
+  // Original handler arrays are back, so pi.on() unsubscribe still finds them.
+  assert.equal(runner.extensions[0].handlers.get('before_agent_start')[0], slow);
+  assert.equal(extensionLabel('/a/b/session-rename.ts'), 'session-rename');
+});