@luxass/pi-personal 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Nørgård
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @luxass/pi-personal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Collects [Pi](https://pi.dev) extensions that are tuned to a single personal workflow rather than general enough to ship on their own.
+
+## Install
+
+```sh
+pi install npm:@luxass/pi-personal
+```
+
+## What it does
+
+The package registers a `session_start` hook. When a session starts, Pi shows a notification confirming the extension loaded.
+
+That is the whole of it today. The package is a home for defaults that suit one workflow, and each addition is meant to be edited in place as that workflow changes rather than configured through settings.

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@luxass/pi-personal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Personal Pi extensions collected in one package, tuned to a single workflow.",
+  "keywords": [
+    "personal",
+    "pi",
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/luxass/pi-extensions",
+    "directory": "packages/personal"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "pi": {
+    "image": "https://raw.githubusercontent.com/luxass/pi-extensions/main/packages/personal/docs/cover.png",
+    "extensions": [
+      "./src/continue-after-compaction.ts",
+      "./src/git-interceptor.ts",
+      "./src/package-manager-interceptor.ts",
+      "./src/worker-configuration-guard.ts",
+      "./src/custom-header.ts",
+      "./src/crow/index.ts"
+    ]
+  },
+  "scripts": {
+    "lint": "oxlint --deny-warnings .",
+    "lint:fix": "oxlint --fix --deny-warnings .",
+    "fmt": "oxfmt .",
+    "fmt:check": "oxfmt --check .",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }

package/src/continue-after-compaction.ts

@@ -0,0 +1,59 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const buildContinuationPrompt = (
+  sessionFile: string | undefined,
+  compactionEntryId: string,
+): string => {
+  const sessionSource =
+    sessionFile === undefined
+      ? "This session is ephemeral, so no persisted session file is available."
+      : [
+          `The persisted session JSONL is ${JSON.stringify(sessionFile)}.`,
+          "Inspect it directly with the read and bash tools.",
+          "Do not launch a nested Pi process or open the session with `pi --session`.",
+        ].join(" ");
+
+  return `Compaction has just completed. Resume the existing task rather than waiting for another user prompt.
+
+${sessionSource}
+The new compaction entry ID is ${JSON.stringify(compactionEntryId)}.
+
+Before continuing:
+
+1. Review the active session branch leading to the compaction entry. Focus first on messages and tool calls immediately before compaction, searching earlier history only as needed. Remember that JSONL append order can include abandoned branches, so follow parentId links rather than blindly treating every entry as active.
+2. Reconstruct the original goal, user constraints, decisions made, files changed, commands and tests run, unresolved issues, and intended next action.
+3. Reconcile the recovered history with the compaction summary and current repository state. Treat the current worktree as authoritative for file state and the original session history as authoritative for user intent.
+4. Briefly state the context you recovered.
+5. Immediately perform the next unfinished step. Do not stop after the recap and do not ask the user to repeat prior context unless the session data is genuinely unavailable or ambiguous.`;
+};
+
+/**
+ * Automatically resumes work after every successful Pi compaction.
+ *
+ * The continuation is deferred by one event-loop turn so manual compaction can
+ * finish reconnecting the agent runtime before a new prompt begins. During an
+ * active automatic-compaction recovery, it is delivered as steering so the
+ * continuation is read before the retried agent performs more work.
+ */
+export default function continueAfterCompaction(pi: ExtensionAPI): void {
+  const pendingTimers = new Set<ReturnType<typeof setTimeout>>();
+
+  pi.on("session_compact", (event, ctx) => {
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    const prompt = buildContinuationPrompt(sessionFile, event.compactionEntry.id);
+
+    const timer = setTimeout(() => {
+      pendingTimers.delete(timer);
+      pi.sendUserMessage(prompt, { deliverAs: "steer" });
+    }, 0);
+
+    pendingTimers.add(timer);
+  });
+
+  pi.on("session_shutdown", () => {
+    for (const timer of pendingTimers) {
+      clearTimeout(timer);
+    }
+    pendingTimers.clear();
+  });
+}

package/src/crow/auto-compact.ts

@@ -0,0 +1,318 @@
+import {
+  type Api,
+  type AssistantMessage,
+  createAssistantMessageEventStream,
+  type Model,
+} from "@earendil-works/pi-ai";
+import { type ExtensionAPI, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+import type { CliproxyCodexStreamSimple, CloseCodexWebSocketSessions } from "./codex-stream.ts";
+
+export const PROACTIVE_COMPACTION_ERROR_PREFIX =
+  "context_length_exceeded: proactive compaction threshold reached";
+
+export interface ProactiveCompactionSettings {
+  enabled: boolean;
+  reserveTokens: number;
+}
+
+export type { CloseCodexWebSocketSessions };
+
+const DEFAULT_COMPACTION_ENABLED = true;
+const DEFAULT_COMPACTION_RESERVE_TOKENS = 16384;
+
+interface CompatibleSettingsManager {
+  reload?: () => Promise<void> | void;
+  reloadFromDisk?: () => Promise<void> | void;
+  getCompactionSettings?: () => { enabled?: unknown; reserveTokens?: unknown };
+  get?: (key: string) => unknown;
+}
+
+function isCompatibleSettingsManager(value: unknown): value is CompatibleSettingsManager {
+  return typeof value === "object" && value !== null;
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    ((typeof value === "object" && value !== null) || typeof value === "function") &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+function normalizeCompactionSettings(
+  enabled: unknown,
+  reserveTokens: unknown,
+): ProactiveCompactionSettings {
+  return {
+    enabled: typeof enabled === "boolean" ? enabled : DEFAULT_COMPACTION_ENABLED,
+    reserveTokens:
+      typeof reserveTokens === "number" && Number.isFinite(reserveTokens) && reserveTokens >= 0
+        ? reserveTokens
+        : DEFAULT_COMPACTION_RESERVE_TOKENS,
+  };
+}
+
+function readCompactionSettings(
+  manager: CompatibleSettingsManager,
+): ProactiveCompactionSettings | undefined {
+  if (typeof manager.getCompactionSettings === "function") {
+    try {
+      const settings = manager.getCompactionSettings();
+      return normalizeCompactionSettings(settings?.enabled, settings?.reserveTokens);
+    } catch {
+      // Fall through to OMP's key-based settings API when available.
+    }
+  }
+  if (typeof manager.get === "function") {
+    try {
+      return normalizeCompactionSettings(
+        manager.get("compaction.enabled"),
+        manager.get("compaction.reserveTokens"),
+      );
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+async function reloadSettings(manager: CompatibleSettingsManager): Promise<void> {
+  if (typeof manager.reload === "function") {
+    try {
+      await manager.reload();
+    } catch {
+      // Keep the last successfully read settings when disk reload fails.
+    }
+    return;
+  }
+  if (typeof manager.reloadFromDisk === "function") {
+    try {
+      await manager.reloadFromDisk();
+    } catch {
+      // Keep the last successfully read settings when disk reload fails.
+    }
+  }
+}
+
+/** Session id used to key pi-ai's reused Codex WebSocket. */
+export function resolveCompactionSessionId(source?: {
+  sessionId?: unknown;
+  sessionManager?: { getSessionId?: () => unknown };
+}): string | undefined {
+  const fromManager = source?.sessionManager?.getSessionId?.();
+  if (typeof fromManager === "string" && fromManager.trim()) {
+    return fromManager;
+  }
+  if (typeof source?.sessionId === "string" && source.sessionId.trim()) {
+    return source.sessionId;
+  }
+  return undefined;
+}
+
+export function shouldScheduleProactiveCompaction(
+  message: AssistantMessage,
+  contextTokens: number,
+  contextWindow: number,
+  settings: ProactiveCompactionSettings,
+): boolean {
+  if (!settings.enabled || message.stopReason !== "toolUse") {
+    return false;
+  }
+  if (!message.content.some((block) => block.type === "toolCall")) {
+    return false;
+  }
+  if (!Number.isFinite(contextTokens) || contextTokens <= 0) {
+    return false;
+  }
+  if (!Number.isFinite(contextWindow) || contextWindow <= 0) {
+    return false;
+  }
+  if (!Number.isFinite(settings.reserveTokens) || settings.reserveTokens < 0) {
+    return false;
+  }
+
+  return contextTokens > contextWindow - settings.reserveTokens;
+}
+
+export function createProactiveCompactionStream(
+  model: Model<Api>,
+  contextTokens: number,
+  threshold: number,
+) {
+  const stream = createAssistantMessageEventStream();
+  const output: AssistantMessage = {
+    role: "assistant",
+    content: [],
+    api: model.api,
+    provider: model.provider,
+    model: model.id,
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    stopReason: "error",
+    errorMessage: `${PROACTIVE_COMPACTION_ERROR_PREFIX} (${contextTokens} > ${threshold})`,
+    timestamp: Date.now(),
+  };
+
+  queueMicrotask(() => {
+    stream.push({ type: "start", partial: output });
+    stream.push({ type: "error", reason: "error", error: output });
+    stream.end();
+  });
+
+  return stream;
+}
+
+export class ProactiveCompactionController {
+  private settingsManager: CompatibleSettingsManager | undefined;
+  private cachedCompactionSettings: ProactiveCompactionSettings | undefined;
+  private pending: { modelKey: string; contextTokens: number; threshold: number } | undefined;
+  private closeWebSocketSessions: CloseCodexWebSocketSessions | undefined;
+
+  constructor(
+    private readonly agentDir: string,
+    private readonly providerId: string,
+    closeWebSocketSessions?: CloseCodexWebSocketSessions,
+  ) {
+    this.closeWebSocketSessions = closeWebSocketSessions;
+  }
+
+  setCloseWebSocketSessions(closeWebSocketSessions: CloseCodexWebSocketSessions): void {
+    this.closeWebSocketSessions = closeWebSocketSessions;
+  }
+
+  register(pi: ExtensionAPI): void {
+    pi.on("session_start", async (_event, ctx) => {
+      this.cachedCompactionSettings = undefined;
+      try {
+        const created: unknown = SettingsManager.create(ctx.cwd, this.agentDir, {
+          projectTrusted: ctx.isProjectTrusted(),
+        });
+        const manager = isPromiseLike(created) ? await created : created;
+        this.settingsManager = isCompatibleSettingsManager(manager) ? manager : undefined;
+        this.cachedCompactionSettings = this.settingsManager
+          ? readCompactionSettings(this.settingsManager)
+          : undefined;
+      } catch {
+        this.settingsManager = undefined;
+      }
+      this.pending = undefined;
+    });
+
+    pi.on("session_shutdown", () => {
+      this.settingsManager = undefined;
+      this.cachedCompactionSettings = undefined;
+      this.pending = undefined;
+    });
+
+    pi.on("session_before_compact", () => {
+      // Compaction summaries use the same provider stream. Clear the synthetic
+      // overflow before pi invokes the summarizer so it cannot abort compaction.
+      this.pending = undefined;
+    });
+
+    pi.on("session_compact", (_event, ctx) => {
+      this.pending = undefined;
+      // CLIProxyAPI binds server-side Codex context to the WebSocket. Compaction
+      // only rewrites the client message list, so reuse would keep cacheRead high
+      // and retrigger proactive compaction on a now-small session.
+      this.resetWebSocketSession(resolveCompactionSessionId(ctx));
+    });
+
+    pi.on("agent_settled", () => {
+      this.pending = undefined;
+    });
+
+    pi.on("turn_end", async (event, ctx) => {
+      const message = event.message;
+      if (message.role !== "assistant" || message.provider !== this.providerId) {
+        return;
+      }
+      if (!ctx.model || ctx.model.provider !== this.providerId || ctx.model.id !== message.model) {
+        return;
+      }
+
+      const settingsManager = this.settingsManager;
+      if (!settingsManager) {
+        return;
+      }
+      await reloadSettings(settingsManager);
+      const refreshedSettings = readCompactionSettings(settingsManager);
+      if (refreshedSettings) {
+        this.cachedCompactionSettings = refreshedSettings;
+      }
+      const settings = refreshedSettings ?? this.cachedCompactionSettings;
+      if (!settings) {
+        return;
+      }
+      const contextTokens = ctx.getContextUsage()?.tokens;
+      if (contextTokens === null || contextTokens === undefined) {
+        return;
+      }
+      if (
+        !shouldScheduleProactiveCompaction(
+          message,
+          contextTokens,
+          ctx.model.contextWindow,
+          settings,
+        )
+      ) {
+        return;
+      }
+
+      this.pending = {
+        modelKey: this.modelKey(ctx.model),
+        contextTokens,
+        threshold: ctx.model.contextWindow - settings.reserveTokens,
+      };
+    });
+  }
+
+  getCompactionSettings(): ProactiveCompactionSettings | undefined {
+    const current = this.settingsManager ? readCompactionSettings(this.settingsManager) : undefined;
+    if (current) {
+      this.cachedCompactionSettings = current;
+    }
+    return current ?? this.cachedCompactionSettings;
+  }
+
+  wrapStreamSimple(streamSimple: CliproxyCodexStreamSimple): CliproxyCodexStreamSimple {
+    return (model, context, options) => {
+      const pending = this.pending;
+      if (!pending || pending.modelKey !== this.modelKey(model)) {
+        return streamSimple(model, context, options);
+      }
+
+      this.pending = undefined;
+      this.resetWebSocketSession(options?.sessionId);
+      return createProactiveCompactionStream(model, pending.contextTokens, pending.threshold);
+    };
+  }
+
+  private resetWebSocketSession(sessionId?: string): void {
+    if (!sessionId || !this.closeWebSocketSessions) {
+      return;
+    }
+    try {
+      this.closeWebSocketSessions(sessionId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      process.stderr.write(
+        `${JSON.stringify({
+          source: "pi-cliproxyapi-provider",
+          level: "warning",
+          message: `Failed to close Codex WebSocket for session ${sessionId}: ${message}`,
+        })}\n`,
+      );
+    }
+  }
+
+  private modelKey(model: Pick<Model<Api>, "provider" | "id">): string {
+    return `${model.provider}/${model.id}`;
+  }
+}