pi-session-cleanup 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.1.0 - 2026-05-04
+
+- Added `/nix quit` for confirmed current-session deletion during graceful Pi shutdown
+- Added `/nix agent [name]` for starting fresh sessions with persisted target-agent metadata
+- Added `/nix` argument completions, explicit help output, and safer compatibility warnings for unsupported Pi builds
+- Documented destructive `/nix` safeguards and added targeted release-readiness coverage for the new session flows
+
 ## 1.0.0 - 2026-03-05
 
 - Renamed extension from its previous package name to `pi-session-cleanup`

package/README.md

@@ -14,6 +14,9 @@ Interactive session cleanup extension for the [Pi coding agent](https://github.c
 - **Scope Filtering** — View only orphaned sessions or all historical sessions
 - **Batch Selection Controls** — Multi-select with Space, select all with `a`, keyboard navigation
 - **Safe Delete Flow** — Excludes the currently active session and uses trash-first deletion with unlink fallback
+- **Fresh Session Shortcut** — `/nix` starts a fresh session and removes the previous session after confirmation
+- **Target Agent Handoff** — `/nix agent [name]` starts a fresh session with persisted active-agent metadata
+- **Quit Cleanup Flow** — `/nix quit` schedules current-session deletion during Pi's graceful shutdown event
 - **Improved Modal UX** — Centered overlay with bordered layout, concise single-line legend, status summary, and automatic icon fallback
 
 ## Installation
@@ -51,6 +54,10 @@ pi install git:github.com/MasuRii/pi-session-cleanup
 | `/session-cleanup current` | — | Opens modal with sessions from the current directory |
 | `/session-cleanup all` | — | Opens modal showing all sessions |
 | `/session-cleanup help` | — | Displays usage help |
+| `/nix` | — | Starts a fresh session after confirmation and deletes the previous session |
+| `/nix quit` | — | Deletes the current session during graceful shutdown and quits Pi |
+| `/nix agent` | `[name]` | Starts a fresh session with a selected or explicitly named target agent |
+| `/nix help` | — | Displays `/nix` usage help |
 
 **Scopes:**
 
@@ -58,6 +65,16 @@ pi install git:github.com/MasuRii/pi-session-cleanup
 - **`current`** — Shows sessions from the current working directory
 - **`all`** — Shows all historical sessions across all directories
 
+### `/nix` Fresh Session Workflow
+
+`/nix` is destructive by design and always asks for confirmation before deleting any session file.
+
+- **`/nix`** starts a new session with the current agent and deletes the previous session only after `ctx.newSession()` succeeds.
+- **`/nix agent [name]`** starts a new session with the selected target agent and writes an `active_agent` session entry so Pi can resume that agent context. Without `[name]`, the command opens an interactive agent picker; with `[name]`, it validates the name before continuing.
+- **`/nix quit`** requires Pi builds that expose `ctx.shutdown()`. It schedules deletion of the current session and performs the delete from the `session_shutdown` event, so the session file is not removed until Pi has begun graceful shutdown.
+
+Target agents are discovered from the nearest project agent folders (`.omp/agents`, `.pi/agents`, `.claude/agents`) plus user agent folders (`~/.omp/agents`, `$PI_CODING_AGENT_DIR/agents`, `~/.claude/agents`). If `pi-agent-router` is installed with custom `agentDiscovery` paths, those paths are reused.
+
 ### Modal Controls
 
 When the session picker modal is open:
@@ -79,8 +96,9 @@ The extension includes multiple safety mechanisms:
 
 1. **Active Session Protection** — The currently active session is never shown in the list and cannot be deleted
 2. **Trash-First Deletion** — Sessions are moved to trash first; only falls back to permanent deletion if trash is unavailable
-3. **Confirmation Required** — The modal requires explicit `Enter` keypress to proceed with deletion
-4. **Escapable** — `Esc` or `q` immediately cancels without any changes
+3. **Confirmation Required** — The modal requires explicit `Enter` keypress to proceed with deletion, and `/nix` commands require `ctx.ui.confirm()` approval
+4. **Graceful Quit Guard** — `/nix quit` refuses to delete anything when the active Pi build does not expose `ctx.shutdown()`
+5. **Escapable** — `Esc` or `q` immediately cancels without any changes
 
 ## Configuration
 

package/package.json

@@ -1,66 +1,66 @@
-{
-  "name": "pi-session-cleanup",
-  "version": "1.0.0",
-  "description": "Pi extension for interactive batch session cleanup and safe deletion.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config/config.example.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
-    "test:clean": "node -e \"require('node:fs').rmSync('.test-dist', { recursive: true, force: true })\"",
-    "pretest": "npm run test:clean",
-    "test": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.test.json && node --test .test-dist/test/*.test.js",
-    "posttest": "npm run test:clean",
-    "check": "npm run lint && npm run test",
-    "package:dry-run": "npm pack --dry-run"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "session",
-    "cleanup",
-    "delete",
-    "pi-coding-agent",
-    "pi-tui",
-    "session-management",
-    "tui",
-    "safe-delete"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.70.5",
-    "@mariozechner/pi-tui": "^0.70.5"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-session-cleanup.git"
-  },
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-session-cleanup/issues"
-  },
-  "homepage": "https://github.com/MasuRii/pi-session-cleanup#readme"
-}
+{
+  "name": "pi-session-cleanup",
+  "version": "1.1.0",
+  "description": "Pi extension for interactive batch session cleanup and safe deletion.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test:clean": "node -e \"require('node:fs').rmSync('.test-dist', { recursive: true, force: true })\"",
+    "pretest": "npm run test:clean",
+    "test": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.test.json && node --test .test-dist/test/*.test.js",
+    "posttest": "npm run test:clean",
+    "check": "npm run lint && npm run test",
+    "package:dry-run": "npm pack --dry-run"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "session",
+    "cleanup",
+    "delete",
+    "pi-coding-agent",
+    "pi-tui",
+    "session-management",
+    "tui",
+    "safe-delete"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.72.0",
+    "@mariozechner/pi-tui": "^0.72.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-session-cleanup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-session-cleanup/issues"
+  },
+  "homepage": "https://github.com/MasuRii/pi-session-cleanup#readme"
+}

package/src/agent-target.ts

@@ -0,0 +1,361 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+
+const DEFAULT_PROJECT_SOURCE_DIRS = [".omp/agents", ".pi/agents", ".claude/agents"];
+const DEFAULT_USER_SOURCE_DIRS = ["{home}/.omp/agents", "{agentDir}/agents", "{home}/.claude/agents"];
+const ROUTER_CONFIG_FILE_NAME = "config.json";
+const ROUTER_EXTENSION_NAME = "pi-agent-router";
+const PI_AGENT_DIR_ENV_VAR = "PI_CODING_AGENT_DIR";
+
+const SESSION_EXTENSION_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+type AgentMode = "primary" | "subagent" | "all";
+
+interface AgentDiscoveryConfig {
+  projectSourceDirs: string[];
+  userSourceDirs: string[];
+}
+
+export interface SelectableAgent {
+  name: string;
+  description: string;
+  mode?: AgentMode;
+}
+
+interface AgentSelectionMenu {
+  labels: string[];
+  valueByLabel: Map<string, string>;
+}
+
+function normalizeStringArray(value: unknown): string[] | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+
+  const normalized = value
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  return normalized.length > 0 ? normalized : null;
+}
+
+function toRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function expandHomeDirectory(configuredDir: string, homeDirectory: string): string {
+  if (configuredDir === "~") {
+    return homeDirectory;
+  }
+
+  if (configuredDir.startsWith("~/") || configuredDir.startsWith("~\\")) {
+    return join(homeDirectory, stripLeadingPathSeparators(configuredDir.slice(1)));
+  }
+
+  return configuredDir;
+}
+
+function resolvePiAgentDir(): string {
+  const configuredDir = process.env[PI_AGENT_DIR_ENV_VAR]?.trim();
+  if (configuredDir) {
+    return expandHomeDirectory(configuredDir, homedir());
+  }
+
+  return join(homedir(), ".pi", "agent");
+}
+
+function resolveRouterConfigCandidates(): string[] {
+  const agentDir = resolvePiAgentDir();
+  const extensionParentDir = dirname(SESSION_EXTENSION_ROOT);
+
+  return [
+    join(extensionParentDir, ROUTER_EXTENSION_NAME, ROUTER_CONFIG_FILE_NAME),
+    join(agentDir, "extensions", ROUTER_EXTENSION_NAME, ROUTER_CONFIG_FILE_NAME),
+  ];
+}
+
+function loadAgentDiscoveryConfig(): AgentDiscoveryConfig {
+  for (const configPath of resolveRouterConfigCandidates()) {
+    try {
+      const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as unknown;
+      const config = toRecord(parsed);
+      const agentDiscovery = toRecord(config?.agentDiscovery);
+      const projectSourceDirs = normalizeStringArray(agentDiscovery?.projectSourceDirs);
+      const userSourceDirs = normalizeStringArray(agentDiscovery?.userSourceDirs);
+
+      return {
+        projectSourceDirs: projectSourceDirs ?? [...DEFAULT_PROJECT_SOURCE_DIRS],
+        userSourceDirs: userSourceDirs ?? [...DEFAULT_USER_SOURCE_DIRS],
+      };
+    } catch {
+      continue;
+    }
+  }
+
+  return {
+    projectSourceDirs: [...DEFAULT_PROJECT_SOURCE_DIRS],
+    userSourceDirs: [...DEFAULT_USER_SOURCE_DIRS],
+  };
+}
+
+function stripLeadingPathSeparators(value: string): string {
+  return value.replace(/^[\\/]+/, "");
+}
+
+function resolveConfiguredUserPath(rawPath: string): string {
+  const trimmed = rawPath.trim();
+  if (!trimmed) {
+    return resolve(resolvePiAgentDir(), "agents");
+  }
+
+  if (trimmed === "~") {
+    return homedir();
+  }
+
+  if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) {
+    return join(homedir(), stripLeadingPathSeparators(trimmed.slice(1)));
+  }
+
+  if (trimmed === "{home}") {
+    return homedir();
+  }
+
+  if (trimmed.startsWith("{home}/") || trimmed.startsWith("{home}\\")) {
+    return join(homedir(), stripLeadingPathSeparators(trimmed.slice("{home}".length)));
+  }
+
+  if (trimmed === "{agentDir}") {
+    return resolvePiAgentDir();
+  }
+
+  if (trimmed.startsWith("{agentDir}/") || trimmed.startsWith("{agentDir}\\")) {
+    return join(resolvePiAgentDir(), stripLeadingPathSeparators(trimmed.slice("{agentDir}".length)));
+  }
+
+  return resolve(trimmed);
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    readdirSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findNearestProjectAgentDirs(cwd: string, projectSourceDirs: readonly string[]): string[] {
+  let currentDir = resolve(cwd);
+
+  while (true) {
+    const candidates = projectSourceDirs
+      .map((sourceDir) => resolve(currentDir, sourceDir))
+      .filter((candidate) => isDirectory(candidate));
+
+    if (candidates.length > 0) {
+      return candidates;
+    }
+
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return [];
+    }
+
+    currentDir = parentDir;
+  }
+}
+
+function parseAgentMode(value: unknown): AgentMode | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "primary" || normalized === "subagent" || normalized === "all") {
+    return normalized;
+  }
+
+  return undefined;
+}
+
+function parseFrontmatter(content: string): Record<string, string> | null {
+  const normalized = content.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return null;
+  }
+
+  const end = normalized.indexOf("\n---", 4);
+  if (end === -1) {
+    return null;
+  }
+
+  const frontmatter: Record<string, string> = {};
+  const lines = normalized.slice(4, end).split("\n");
+
+  for (const line of lines) {
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, separatorIndex).trim();
+    const value = line.slice(separatorIndex + 1).trim().replace(/^['\"]|['\"]$/g, "");
+    if (key) {
+      frontmatter[key] = value;
+    }
+  }
+
+  return frontmatter;
+}
+
+function parseAgentFile(filePath: string): SelectableAgent | null {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const frontmatter = parseFrontmatter(content);
+    if (!frontmatter?.name) {
+      return null;
+    }
+
+    return {
+      name: frontmatter.name,
+      description: frontmatter.description || `Agent ${frontmatter.name}`,
+      mode: parseAgentMode(frontmatter.mode),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function loadAgentsFromDir(dirPath: string): SelectableAgent[] {
+  try {
+    return readdirSync(dirPath)
+      .filter((entry) => entry.endsWith(".md"))
+      .map((entry) => parseAgentFile(join(dirPath, entry)))
+      .filter((agent): agent is SelectableAgent => Boolean(agent));
+  } catch {
+    return [];
+  }
+}
+
+function truncateDescription(description: string, maxLength = 72): string {
+  const normalized = description.trim().replace(/\s+/g, " ");
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+
+  return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+
+function formatModeBadge(agent: SelectableAgent): string {
+  return `[${agent.mode ?? "primary"}]`;
+}
+
+function formatCurrentMarker(currentAgentName: string | null, candidateAgentName: string): string {
+  return currentAgentName === candidateAgentName ? "●" : "○";
+}
+
+function buildAgentSelectionLabel(
+  agent: SelectableAgent,
+  currentAgentName: string | null,
+): string {
+  return [
+    formatCurrentMarker(currentAgentName, agent.name),
+    agent.name,
+    formatModeBadge(agent),
+    "—",
+    truncateDescription(agent.description),
+  ].join(" ");
+}
+
+export function buildAgentSelectionMenu(
+  agents: readonly SelectableAgent[],
+  currentAgentName: string | null,
+): AgentSelectionMenu {
+  const labels: string[] = [];
+  const valueByLabel = new Map<string, string>();
+
+  for (const agent of agents) {
+    const label = buildAgentSelectionLabel(agent, currentAgentName);
+    labels.push(label);
+    valueByLabel.set(label, agent.name);
+  }
+
+  return {
+    labels,
+    valueByLabel,
+  };
+}
+
+export function discoverSelectableAgents(cwd: string): SelectableAgent[] {
+  const config = loadAgentDiscoveryConfig();
+  const projectAgentDirs = findNearestProjectAgentDirs(cwd, config.projectSourceDirs);
+  const userAgentDirs = config.userSourceDirs
+    .map((sourceDir) => resolveConfiguredUserPath(sourceDir))
+    .filter((candidate) => isDirectory(candidate));
+
+  const byName = new Map<string, SelectableAgent>();
+  const precedenceOrder = [
+    ...userAgentDirs.slice().reverse(),
+    ...projectAgentDirs.slice().reverse(),
+  ];
+
+  for (const sourceDir of precedenceOrder) {
+    const agents = loadAgentsFromDir(sourceDir);
+    for (const agent of agents) {
+      byName.set(agent.name, agent);
+    }
+  }
+
+  return [...byName.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+export async function resolveTargetAgentForSessionNix(
+  ctx: ExtensionCommandContext,
+  input: string | undefined,
+  currentAgentName: string | null,
+): Promise<SelectableAgent | null | undefined> {
+  const agents = discoverSelectableAgents(ctx.cwd);
+  if (agents.length === 0) {
+    ctx.ui.notify(
+      "No agents were discovered. Check pi-agent-router agent directories before using /nix agent.",
+      "warning",
+    );
+    return undefined;
+  }
+
+  if (input) {
+    const matchedAgent = agents.find((agent) => agent.name === input);
+    if (!matchedAgent) {
+      const agentNames = agents.map((agent) => agent.name).join(", ");
+      ctx.ui.notify(`Unknown agent: ${input}\nAvailable agents: ${agentNames}`, "warning");
+      return undefined;
+    }
+
+    return matchedAgent;
+  }
+
+  if (!ctx.hasUI) {
+    ctx.ui.notify("/nix agent requires an explicit agent name in non-interactive mode.", "warning");
+    return undefined;
+  }
+
+  const { showAgentTargetPicker } = await import("./tui/agent-target-picker.js");
+  const selectedAgentName = await showAgentTargetPicker(ctx, agents, currentAgentName);
+
+  if (!selectedAgentName) {
+    return null;
+  }
+
+  const selectedAgent = agents.find((agent) => agent.name === selectedAgentName);
+  if (!selectedAgent) {
+    ctx.ui.notify("Unknown agent selection. Please try again.", "warning");
+    return undefined;
+  }
+
+  return selectedAgent;
+}

package/src/index.ts

@@ -5,9 +5,17 @@ import {
   getSessionCleanupArgumentCompletions,
   handleSessionCleanupCommand,
 } from "./session-cleanup-command.js";
-import { handleSessionNixCommand } from "./session-nix-command.js";
+import {
+  getSessionNixArgumentCompletions,
+  handleSessionNixCommand,
+} from "./session-nix-command.js";
+import { flushScheduledSessionDeletionForQuit } from "./session-quit-shutdown.js";
 
 export default function sessionCleanupExtension(pi: ExtensionAPI): void {
+  pi.on("session_shutdown", async (_event, ctx) => {
+    await flushScheduledSessionDeletionForQuit(ctx);
+  });
+
   pi.registerCommand(SESSION_CLEANUP_COMMAND, {
     description:
       "Batch-select previous sessions and delete them with confirmation.",
@@ -19,7 +27,8 @@ export default function sessionCleanupExtension(pi: ExtensionAPI): void {
 
   pi.registerCommand(SESSION_NIX_COMMAND, {
     description:
-      "Start a new session and automatically delete the previous session.",
+      "Start a fresh session, switch to a target agent, or delete the current session and quit Pi.",
+    getArgumentCompletions: getSessionNixArgumentCompletions,
     handler: async (args, ctx) => {
       await handleSessionNixCommand(args, ctx);
     },

package/src/session-agent.ts

@@ -66,6 +66,31 @@ export async function resolveResponsibleAgentName(sessionPath: string): Promise<
   }
 }
 
+export function extractPersistedActiveAgentNameFromEntries(
+  entries: readonly unknown[],
+): string | null | undefined {
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = toRecord(entries[index]);
+    if (!entry || entry.type !== "custom" || entry.customType !== "active_agent") {
+      continue;
+    }
+
+    const data = toRecord(entry.data);
+    const normalizedAgentName = normalizeAgentName(data?.name);
+    if (normalizedAgentName) {
+      return normalizedAgentName;
+    }
+
+    if (data?.name === null) {
+      return null;
+    }
+
+    return null;
+  }
+
+  return undefined;
+}
+
 export async function enrichSessionWithResponsibleAgent(
   session: SessionInfo,
 ): Promise<SessionCleanupSession> {

package/src/session-entry.ts

@@ -0,0 +1,23 @@
+import type { SessionManager } from "@mariozechner/pi-coding-agent";
+
+export interface ActiveAgentSessionEntryData {
+  name: string | null;
+}
+
+type SessionManagerWithCustomEntry = SessionManager & {
+  appendCustomEntry?: (customType: string, data?: unknown) => string;
+};
+
+export function appendActiveAgentSessionEntry(
+  sessionManager: SessionManager,
+  agentName: string | null,
+): void {
+  const writableSessionManager = sessionManager as SessionManagerWithCustomEntry;
+  if (typeof writableSessionManager.appendCustomEntry !== "function") {
+    throw new Error("The current Pi build does not expose sessionManager.appendCustomEntry().");
+  }
+
+  writableSessionManager.appendCustomEntry("active_agent", {
+    name: agentName,
+  } satisfies ActiveAgentSessionEntryData);
+}