shariq-pi-extensions 0.3.1 → 0.3.3

package/README.md

@@ -73,9 +73,9 @@ Runtime files use Pi's active agent directory rather than a fixed home or checko
 
 ```bash
 mise install --locked
-mise exec --locked -- npm ci
-mise exec --locked -- npm run validate
-mise exec --locked -- npm run pack:inspect
+mise exec --locked -- bun install
+mise exec --locked -- bun run validate
+mise exec --locked -- bun run pack:inspect
 ```
 
 See [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for repository workflow and release checks, and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for package boundaries.

package/docs/DEVELOPMENT.md

@@ -8,11 +8,11 @@ Last verified: 2026-09-04
 - Pi matching the pinned development dependency version
 - platform build support required by `@lydell/node-pty`
 
-Install the exact Node toolchain and dependencies:
+Install the exact toolchain and dependencies:
 
 ```bash
 mise install --locked
-mise exec --locked -- npm ci
+mise exec --locked -- bun install
 ```
 
 ## Validation
@@ -20,8 +20,8 @@ mise exec --locked -- npm ci
 Validate the complete suite and inspect the package payload:
 
 ```bash
-mise exec --locked -- npm run validate
-mise exec --locked -- npm pack --dry-run
+mise exec --locked -- bun run validate
+mise exec --locked -- bun run pack:inspect
 ```
 
 The root validation checks TypeScript, runtime tests, declared extension and skill entrypoints, and forbidden runtime files. Inspect the package file list before committing. It must not contain credentials, `.env`, first-party caches, databases, sessions, logs, or `node_modules`.
@@ -74,8 +74,8 @@ gh repo view shariqriazz/shariq-pi-extensions --json visibility,url
 Before publishing a new npm version:
 
 1. Update `package.json#version` using semantic versioning.
-2. Run `mise exec --locked -- npm ci` and `mise exec --locked -- npm run validate`.
-3. Inspect `mise exec --locked -- npm run pack:inspect` for secrets, runtime state, and accidental files.
+2. Run `mise exec --locked -- bun install` and `mise exec --locked -- bun run validate`.
+3. Inspect `mise exec --locked -- bun run pack:inspect` for secrets, runtime state, and accidental files.
 4. Run the `Publish npm package` workflow. npm trusted publishing authenticates it through GitHub OIDC and records provenance without a long-lived token.
 5. Verify the registry version and install it with `pi install npm:shariq-pi-extensions`.
 

package/extensions/background-terminals/src/manager.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { spawn as spawnPty, type IDisposable, type IPty } from "@lydell/node-pty";
+import { spawnUniversalPty, type UniversalPty } from "./pty.ts";
 import { OutputBuffer } from "./output-buffer.ts";
 import type {
   StartTerminalOptions,
@@ -37,11 +37,11 @@ interface MutableSnapshot {
 
 interface Entry {
   readonly snapshot: MutableSnapshot;
-  readonly pty: IPty;
+  readonly pty: UniversalPty;
   readonly output: OutputBuffer;
   readonly spill: fs.WriteStream;
-  readonly dataSubscription: IDisposable;
-  readonly exitSubscription: IDisposable;
+  readonly dataSubscription: { dispose(): void };
+  readonly exitSubscription: { dispose(): void };
   readonly settled: Promise<TerminalSnapshot>;
   resolveSettled(snapshot: TerminalSnapshot): void;
   killRequested: boolean;
@@ -202,7 +202,7 @@ export class TerminalManager {
       let spillBytes = 0;
       let spillTruncated = false;
       let pausedForSpill = false;
-      let pty: IPty | undefined;
+      let pty: UniversalPty | undefined;
       let snapshot: MutableSnapshot | undefined;
       const markSpillTruncated = () => {
         if (spillTruncated) return;
@@ -223,7 +223,7 @@ export class TerminalManager {
         if (payload.length < bytes.length || spillBytes >= this.maxFullLogBytes) markSpillTruncated();
         if (!accepted && pty && !pausedForSpill) {
           pausedForSpill = true;
-          pty.pause();
+          pty.pause?.();
         }
       });
       output.spillPath = spillPath;
@@ -231,7 +231,7 @@ export class TerminalManager {
         if (!pausedForSpill) return;
         pausedForSpill = false;
         try {
-          pty?.resume();
+          pty?.resume?.();
         } catch {
           // Exit may have won the drain race.
         }
@@ -242,7 +242,7 @@ export class TerminalManager {
         if (pausedForSpill) {
           pausedForSpill = false;
           try {
-            pty?.resume();
+            pty?.resume?.();
           } catch {
             // Exit may have won the error race.
           }
@@ -253,8 +253,9 @@ export class TerminalManager {
 
       const shell = shellInvocation(options.command);
       try {
-        pty = spawnPty(shell.file, shell.args, {
-          name: "xterm-256color",
+        pty = spawnUniversalPty({
+          file: shell.file,
+          args: shell.args,
           cols,
           rows,
           cwd: options.cwd,

package/extensions/background-terminals/src/pty.ts

@@ -0,0 +1,165 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn as spawnNodePty, type IDisposable, type IPty } from "@lydell/node-pty";
+
+export interface UniversalPty {
+  readonly pid: number;
+  onData(listener: (chunk: string) => void): { dispose(): void };
+  onExit(listener: (event: { exitCode: number; signal?: number }) => void): { dispose(): void };
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  pause?(): void;
+  resume?(): void;
+  kill(signal?: string): void;
+}
+
+export interface SpawnUniversalPtyOptions {
+  file: string;
+  args: string[];
+  cols: number;
+  rows: number;
+  cwd: string;
+  env: Record<string, string | undefined>;
+}
+
+declare const Bun: any;
+
+class BunPtyAdapter implements UniversalPty {
+  readonly pid: number;
+  private readonly proc: any;
+  private readonly dataListeners = new Set<(chunk: string) => void>();
+  private readonly exitListeners = new Set<(event: { exitCode: number; signal?: number }) => void>();
+  private exited = false;
+
+  constructor(options: SpawnUniversalPtyOptions) {
+    const cmd = [options.file, ...options.args];
+    this.proc = Bun.spawn(cmd, {
+      cwd: options.cwd,
+      env: options.env,
+      terminal: {
+        cols: options.cols,
+        rows: options.rows,
+        data: (_term: unknown, chunk: Uint8Array | string) => {
+          const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+          for (const listener of this.dataListeners) {
+            try {
+              listener(text);
+            } catch {
+              // Ignore listener errors
+            }
+          }
+        },
+      },
+    });
+
+    this.pid = this.proc.pid;
+
+    void this.proc.exited.then((exitCode: number) => {
+      if (this.exited) return;
+      this.exited = true;
+      const signal = this.proc.signalCode
+        ? typeof this.proc.signalCode === "number"
+          ? this.proc.signalCode
+          : undefined
+        : undefined;
+      for (const listener of this.exitListeners) {
+        try {
+          listener({ exitCode: typeof exitCode === "number" ? exitCode : 0, signal });
+        } catch {
+          // Ignore listener errors
+        }
+      }
+    });
+  }
+
+  onData(listener: (chunk: string) => void) {
+    this.dataListeners.add(listener);
+    return {
+      dispose: () => {
+        this.dataListeners.delete(listener);
+      },
+    };
+  }
+
+  onExit(listener: (event: { exitCode: number; signal?: number }) => void) {
+    this.exitListeners.add(listener);
+    return {
+      dispose: () => {
+        this.exitListeners.delete(listener);
+      },
+    };
+  }
+
+  write(data: string): void {
+    try {
+      this.proc.terminal.write(data);
+    } catch {
+      // Best-effort write
+    }
+  }
+
+  resize(cols: number, rows: number): void {
+    try {
+      this.proc.terminal.resize(cols, rows);
+    } catch {
+      // Best-effort resize
+    }
+  }
+
+  kill(signal?: string): void {
+    try {
+      this.proc.kill(signal ?? "SIGTERM");
+    } catch {
+      // Best-effort kill
+    }
+  }
+}
+
+class NodePtyAdapter implements UniversalPty {
+  readonly pid: number;
+  private readonly pty: IPty;
+
+  constructor(pty: IPty) {
+    this.pty = pty;
+    this.pid = pty.pid;
+  }
+
+  onData(listener: (chunk: string) => void) {
+    return this.pty.onData(listener);
+  }
+
+  onExit(listener: (event: { exitCode: number; signal?: number }) => void) {
+    return this.pty.onExit(listener);
+  }
+
+  write(data: string): void {
+    this.pty.write(data);
+  }
+
+  resize(cols: number, rows: number): void {
+    this.pty.resize(cols, rows);
+  }
+
+  kill(signal?: string): void {
+    this.pty.kill(signal);
+  }
+}
+
+export function isBunRuntime(): boolean {
+  return typeof Bun !== "undefined" && typeof Bun.spawn === "function";
+}
+
+export function spawnUniversalPty(options: SpawnUniversalPtyOptions): UniversalPty {
+  if (isBunRuntime()) {
+    return new BunPtyAdapter(options);
+  }
+
+  const pty = spawnNodePty(options.file, options.args, {
+    name: "xterm-256color",
+    cols: options.cols,
+    rows: options.rows,
+    cwd: options.cwd,
+    env: options.env as Record<string, string>,
+  });
+  return new NodePtyAdapter(pty);
+}

package/extensions/smart-compaction/engine.ts

@@ -50,6 +50,7 @@ export interface SmartCompactionDetails {
   serializedCharacters: number;
   summaryCharacters: number;
   attemptCount: number;
+  retainedIdentifiersAppended?: number;
   durationMs: number;
   timestamp: number;
 }
@@ -328,7 +329,9 @@ const REQUIRED_SECTION_PATTERNS = [
   /## 6\.\s+Resume Anchor/i,
 ];
 
-export function validateSummaryOutput(response: AssistantMessage, protectedFacts: readonly string[] = []): string {
+export const RETAINED_IDENTIFIERS_HEADING = "### Retained Identifiers";
+
+export function extractSummaryText(response: AssistantMessage): string {
   if (response.stopReason !== "stop") {
     const errorDetails = response.errorMessage ? `: ${response.errorMessage}` : "";
     throw new Error(`Compaction model did not complete successfully (stopReason="${response.stopReason}"${errorDetails}).`);
@@ -350,13 +353,38 @@ export function validateSummaryOutput(response: AssistantMessage, protectedFacts
     throw new Error("Compaction model returned an empty summary.");
   }
 
+  return rawSummaryText;
+}
+
+export function getDroppedProtectedFacts(summaryText: string, protectedFacts: readonly string[] = []): string[] {
+  return protectedFacts.filter((fact) => fact && !summaryText.includes(fact));
+}
+
+export function withRetainedIdentifiers(summaryText: string, droppedFacts: readonly string[]): string {
+  // Protected facts are single-line opaque identifiers (hashes, UUIDs, clean
+  // URLs, IPs), so reproducing them on their own bullet lines is verbatim-safe.
+  const lines = [summaryText.trimEnd(), "", RETAINED_IDENTIFIERS_HEADING];
+  for (const fact of droppedFacts) {
+    const clean = String(fact).trim();
+    if (clean) lines.push(`- ${clean}`);
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function validateSummaryText(summaryText: string, protectedFacts: readonly string[] = []): string {
+  const rawSummaryText = summaryText.trim();
+
+  if (!rawSummaryText) {
+    throw new Error("Compaction model returned an empty summary.");
+  }
+
   // Verify all 6 required sections exist
   for (const pattern of REQUIRED_SECTION_PATTERNS) {
     if (!pattern.test(rawSummaryText)) {
       throw new Error(`Compaction summary is incomplete: missing required section matching ${pattern.source}`);
     }
   }
-  const missingFacts = protectedFacts.filter((fact) => !rawSummaryText.includes(fact));
+  const missingFacts = getDroppedProtectedFacts(rawSummaryText, protectedFacts);
   if (missingFacts.length > 0) {
     throw new Error(`Compaction summary dropped protected facts: ${missingFacts.slice(0, 3).join(" | ")}`);
   }
@@ -364,6 +392,29 @@ export function validateSummaryOutput(response: AssistantMessage, protectedFacts
   return rawSummaryText;
 }
 
+export function validateSummaryOutput(response: AssistantMessage, protectedFacts: readonly string[] = []): string {
+  return validateSummaryText(extractSummaryText(response), protectedFacts);
+}
+
+/**
+ * Return the summary text when it is structurally sound (extractable with all
+ * required sections) regardless of dropped protected facts. Identifier-only
+ * defects can be repaired deterministically with {@link withRetainedIdentifiers};
+ * structural defects cannot, so those return undefined.
+ */
+export function extractRepairableSummary(response: AssistantMessage): string | undefined {
+  let text: string;
+  try {
+    text = extractSummaryText(response);
+  } catch {
+    return undefined;
+  }
+  for (const pattern of REQUIRED_SECTION_PATTERNS) {
+    if (!pattern.test(text)) return undefined;
+  }
+  return text;
+}
+
 export function computeCompactionTokenCeiling(
   model: Model<Api>,
   config: SmartCompactionConfig,
@@ -529,6 +580,8 @@ export async function runSmartCompaction(
 
   let lastError: Error | undefined;
   let finalSummaryText = "";
+  let repairCandidate: string | undefined;
+  let retainedIdentifiersAppended = 0;
   let accumulatedUsage: Usage | undefined;
   let attemptCount = 0;
   let activeModel = primaryModel;
@@ -572,7 +625,16 @@ export async function runSmartCompaction(
       if (response.usage) {
         accumulatedUsage = combineCompactionUsage(accumulatedUsage, response.usage);
       }
-      finalSummaryText = validateSummaryOutput(response, protectedFacts);
+      try {
+        finalSummaryText = validateSummaryOutput(response, protectedFacts);
+      } catch (validationError) {
+        // Structurally sound summaries that only drop protected facts are
+        // kept as deterministic-repair candidates; structural defects cannot
+        // be repaired, so those leave no candidate behind.
+        const repairable = extractRepairableSummary(response);
+        if (repairable !== undefined) repairCandidate = repairable;
+        throw validationError;
+      }
       lastError = undefined;
       break; // Success!
     } catch (err) {
@@ -586,6 +648,23 @@ export async function runSmartCompaction(
     }
   }
 
+  if ((lastError || !finalSummaryText) && repairCandidate !== undefined) {
+    // Every stage produced a structurally sound summary but the model
+    // deterministically refused to repeat low-signal identifiers. Restore
+    // them verbatim instead of failing the whole compaction.
+    const stillMissing = getDroppedProtectedFacts(repairCandidate, protectedFacts);
+    try {
+      finalSummaryText = validateSummaryText(
+        withRetainedIdentifiers(repairCandidate, stillMissing),
+        protectedFacts,
+      );
+      lastError = undefined;
+      retainedIdentifiersAppended = stillMissing.length;
+    } catch {
+      // Repair rejected; fall through to the original failure below.
+    }
+  }
+
   if (lastError || !finalSummaryText) {
     throw lastError ?? new Error("All smart compaction retry stages failed.");
   }
@@ -643,6 +722,7 @@ export async function runSmartCompaction(
     serializedCharacters: conversationText.length,
     summaryCharacters: finalSummary.length,
     attemptCount,
+    retainedIdentifiersAppended: retainedIdentifiersAppended > 0 ? retainedIdentifiersAppended : undefined,
     durationMs: Date.now() - startedAt,
     timestamp: Date.now(),
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",
@@ -62,12 +62,12 @@
     "check": "tsc --noEmit -p tsconfig.json",
     "test": "node scripts/run-tests.mjs",
     "validate:package": "node scripts/validate-package.mjs",
-    "validate": "npm run check && npm test && npm run validate:package",
+    "validate": "bun run check && node scripts/run-tests.mjs && bun run validate:package",
     "pack:inspect": "npm pack --dry-run",
-    "prepublishOnly": "npm run validate"
+    "prepublishOnly": "bun run validate"
   },
   "dependencies": {
-    "@lydell/node-pty": "1.1.0",
+    "@lydell/node-pty": "^1.1.0",
     "effect": "4.0.0-beta.98"
   },
   "peerDependencies": {
@@ -95,12 +95,12 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.84.2",
-    "@earendil-works/pi-ai": "0.84.2",
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@earendil-works/pi-tui": "0.84.2",
-    "@types/node": "^26.1.2",
-    "typebox": "1.3.7",
+    "@earendil-works/pi-agent-core": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
+    "@types/node": "^26.4.1",
+    "typebox": "^1.3.27",
     "typescript": "^7.0.2"
   },
   "allowScripts": {