pi-session-cleanup 1.0.0 → 1.1.0

package/src/session-nix-command.ts

@@ -3,10 +3,52 @@ import { basename } from "node:path";
 import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 
 import { SESSION_NIX_COMMAND } from "./constants.js";
+import {
+  resolveTargetAgentForSessionNix,
+  type SelectableAgent,
+} from "./agent-target.js";
+import { extractPersistedActiveAgentNameFromEntries } from "./session-agent.js";
 import { deleteSessionFile } from "./session-delete.js";
+import { appendActiveAgentSessionEntry } from "./session-entry.js";
+import {
+  clearScheduledSessionDeletionForQuit,
+  scheduleSessionDeletionForQuit,
+} from "./session-quit-shutdown.js";
+
+const ARG_COMPLETIONS = [
+  {
+    value: "quit",
+    label: "quit",
+    description: "Delete the current session and quit Pi immediately",
+  },
+  {
+    value: "agent",
+    label: "agent",
+    description: "Start a fresh session with a selected target agent",
+  },
+  {
+    value: "help",
+    label: "help",
+    description: "Show usage",
+  },
+] as const;
+
+type NixMode = "fresh" | "quit" | "agent";
+
+interface ParsedArgs {
+  help: boolean;
+  mode: NixMode;
+  targetAgentName?: string;
+  error?: string;
+}
 
 function usage(): string {
-  return `Usage: /${SESSION_NIX_COMMAND}`;
+  return [
+    `Usage: /${SESSION_NIX_COMMAND}`,
+    `       /${SESSION_NIX_COMMAND} quit`,
+    `       /${SESSION_NIX_COMMAND} agent [name]`,
+    `       /${SESSION_NIX_COMMAND} help`,
+  ].join("\n");
 }
 
 function getSessionLabel(sessionPath: string): string {
@@ -14,7 +56,48 @@ function getSessionLabel(sessionPath: string): string {
   return fileName.length > 0 ? fileName : sessionPath;
 }
 
-function buildConfirmationMessage(previousSessionFile: string | undefined): string {
+function parseArgs(args: string): ParsedArgs {
+  const trimmed = args.trim();
+  if (!trimmed) {
+    return { help: false, mode: "fresh" };
+  }
+
+  const parts = trimmed.split(/\s+/);
+  const command = parts[0]?.toLowerCase();
+  if (!command) {
+    return { help: false, mode: "fresh" };
+  }
+
+  if (command === "help") {
+    return { help: true, mode: "fresh" };
+  }
+
+  if (command === "quit" || command === "exit") {
+    return parts.length === 1
+      ? { help: false, mode: "quit" }
+      : {
+          help: false,
+          mode: "quit",
+          error: `/${SESSION_NIX_COMMAND} quit does not accept additional arguments.`,
+        };
+  }
+
+  if (command === "agent") {
+    return {
+      help: false,
+      mode: "agent",
+      targetAgentName: parts.length > 1 ? parts.slice(1).join(" ") : undefined,
+    };
+  }
+
+  return {
+    help: false,
+    mode: "fresh",
+    error: `Unknown argument: ${trimmed}`,
+  };
+}
+
+function buildFreshConfirmationMessage(previousSessionFile: string | undefined): string {
   if (!previousSessionFile) {
     return "This will start a new session. The current session is not persisted yet, so there is no session file to delete.";
   }
@@ -28,18 +111,153 @@ function buildConfirmationMessage(previousSessionFile: string | undefined): stri
   ].join("\n");
 }
 
+function buildQuitConfirmationMessage(previousSessionFile: string | undefined): string {
+  if (!previousSessionFile) {
+    return "This will quit Pi immediately. The current session is not persisted yet, so there is no session file to delete first.";
+  }
+
+  return [
+    "This will permanently remove the current session and then quit Pi immediately.",
+    "",
+    `Current session: ${getSessionLabel(previousSessionFile)}`,
+    "",
+    "Pi will try moving it to trash first, then permanently delete it if trash is unavailable.",
+  ].join("\n");
+}
+
+function buildAgentConfirmationMessage(
+  previousSessionFile: string | undefined,
+  targetAgent: SelectableAgent,
+): string {
+  if (!previousSessionFile) {
+    return [
+      `This will start a new session with agent '${targetAgent.name}'.`,
+      "",
+      "The current session is not persisted yet, so there is no session file to delete.",
+    ].join("\n");
+  }
+
+  return [
+    `This will start a new session with agent '${targetAgent.name}' and remove the current session from history.`,
+    "",
+    `Current session: ${getSessionLabel(previousSessionFile)}`,
+    `Target agent: ${targetAgent.name}`,
+    "",
+    "Pi will try moving the old session to trash first, then permanently delete it if trash is unavailable.",
+  ].join("\n");
+}
+
+export function getSessionNixArgumentCompletions(
+  argumentPrefix: string,
+): Array<{ value: string; label: string; description?: string }> | null {
+  const normalizedPrefix = argumentPrefix.trim().toLowerCase();
+  if (!normalizedPrefix) {
+    return [...ARG_COMPLETIONS];
+  }
+
+  const matched = ARG_COMPLETIONS.filter((item) => item.value.startsWith(normalizedPrefix));
+  if (matched.length === 0) {
+    return null;
+  }
+
+  return matched.map((item) => ({ ...item }));
+}
+
+async function deletePreviousSessionAfterSwitch(previousSessionFile: string | undefined): Promise<void> {
+  if (!previousSessionFile) {
+    return;
+  }
+
+  try {
+    await deleteSessionFile(previousSessionFile);
+  } catch {
+    // The new session is already active. Avoid surfacing stale-context errors.
+  }
+}
+
+async function startFreshSession(
+  ctx: ExtensionCommandContext,
+  previousSessionFile: string | undefined,
+): Promise<void> {
+  try {
+    const newSessionResult = await ctx.newSession();
+    if (newSessionResult.cancelled) {
+      ctx.ui.notify("New session cancelled.", "info");
+      return;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.ui.notify(`Failed to start a new session: ${message}`, "error");
+    return;
+  }
+
+  await deletePreviousSessionAfterSwitch(previousSessionFile);
+}
+
+async function startAgentTargetSession(
+  ctx: ExtensionCommandContext,
+  previousSessionFile: string | undefined,
+  targetAgent: SelectableAgent,
+): Promise<void> {
+  try {
+    const newSessionResult = await ctx.newSession({
+      setup: async (sessionManager) => {
+        appendActiveAgentSessionEntry(sessionManager, targetAgent.name);
+      },
+    });
+
+    if (newSessionResult.cancelled) {
+      ctx.ui.notify("New session cancelled.", "info");
+      return;
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.ui.notify(`Failed to start a new session for agent '${targetAgent.name}': ${message}`, "error");
+    return;
+  }
+
+  await deletePreviousSessionAfterSwitch(previousSessionFile);
+}
+
+async function requestGracefulQuit(
+  ctx: ExtensionCommandContext,
+  previousSessionFile: string | undefined,
+): Promise<void> {
+  const shutdown = (ctx as ExtensionCommandContext & {
+    shutdown?: () => Promise<void> | void;
+  }).shutdown;
+
+  if (typeof shutdown !== "function") {
+    ctx.ui.notify(
+      "Graceful shutdown is unavailable in this Pi build. Update Pi to use /nix quit safely.",
+      "warning",
+    );
+    return;
+  }
+
+  scheduleSessionDeletionForQuit(previousSessionFile);
+
+  try {
+    await Promise.resolve(shutdown.call(ctx));
+  } catch (error) {
+    clearScheduledSessionDeletionForQuit();
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.ui.notify(`Failed to quit Pi gracefully: ${message}`, "error");
+  }
+}
+
 export async function handleSessionNixCommand(
   args: string,
   ctx: ExtensionCommandContext,
 ): Promise<void> {
-  const normalizedArgs = args.trim();
-  if (normalizedArgs.toLowerCase() === "help") {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
     ctx.ui.notify(usage(), "info");
     return;
   }
 
-  if (normalizedArgs.length > 0) {
-    ctx.ui.notify(`/${SESSION_NIX_COMMAND} does not accept arguments.\n${usage()}`, "warning");
+  if (parsed.error) {
+    ctx.ui.notify(`${parsed.error}\n${usage()}`, "warning");
     return;
   }
 
@@ -49,36 +267,63 @@ export async function handleSessionNixCommand(
   }
 
   const previousSessionFile = ctx.sessionManager.getSessionFile();
-  const confirmed = await ctx.ui.confirm(
-    "Start fresh and delete current session",
-    buildConfirmationMessage(previousSessionFile),
-  );
 
-  if (!confirmed) {
-    ctx.ui.notify(`/${SESSION_NIX_COMMAND} cancelled.`, "info");
+  if (parsed.mode === "fresh") {
+    const confirmed = await ctx.ui.confirm(
+      "Start fresh and delete current session",
+      buildFreshConfirmationMessage(previousSessionFile),
+    );
+
+    if (!confirmed) {
+      ctx.ui.notify(`/${SESSION_NIX_COMMAND} cancelled.`, "info");
+      return;
+    }
+
+    await startFreshSession(ctx, previousSessionFile);
     return;
   }
 
-  try {
-    const newSessionResult = await ctx.newSession();
-    if (newSessionResult.cancelled) {
-      ctx.ui.notify("New session cancelled.", "info");
+  if (parsed.mode === "quit") {
+    const confirmed = await ctx.ui.confirm(
+      "Delete current session and quit Pi",
+      buildQuitConfirmationMessage(previousSessionFile),
+    );
+
+    if (!confirmed) {
+      ctx.ui.notify(`/${SESSION_NIX_COMMAND} quit cancelled.`, "info");
       return;
     }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    ctx.ui.notify(`Failed to start a new session: ${message}`, "error");
+
+    await requestGracefulQuit(ctx, previousSessionFile);
     return;
   }
 
-  // After successful ctx.newSession(), ctx is stale. Do NOT call ctx.ui.notify() below.
-  if (!previousSessionFile) {
+  const currentAgentName =
+    extractPersistedActiveAgentNameFromEntries(ctx.sessionManager.getEntries()) ?? null;
+  const targetAgent = await resolveTargetAgentForSessionNix(
+    ctx,
+    parsed.targetAgentName,
+    currentAgentName,
+  );
+
+  if (targetAgent === null) {
+    ctx.ui.notify(`/${SESSION_NIX_COMMAND} agent cancelled.`, "info");
     return;
   }
 
-  try {
-    await deleteSessionFile(previousSessionFile);
-  } catch {
-    // Deletion failure is non-critical; the session was already replaced.
+  if (!targetAgent) {
+    return;
   }
+
+  const confirmed = await ctx.ui.confirm(
+    `Start a new '${targetAgent.name}' session`,
+    buildAgentConfirmationMessage(previousSessionFile, targetAgent),
+  );
+
+  if (!confirmed) {
+    ctx.ui.notify(`/${SESSION_NIX_COMMAND} agent cancelled.`, "info");
+    return;
+  }
+
+  await startAgentTargetSession(ctx, previousSessionFile, targetAgent);
 }

package/src/session-quit-shutdown.ts

@@ -0,0 +1,40 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { deleteSessionFile } from "./session-delete.js";
+
+let pendingSessionFileForQuitDeletion: string | undefined;
+
+export function scheduleSessionDeletionForQuit(sessionFile: string | undefined): void {
+  pendingSessionFileForQuitDeletion = sessionFile;
+}
+
+export function clearScheduledSessionDeletionForQuit(): void {
+  pendingSessionFileForQuitDeletion = undefined;
+}
+
+export async function flushScheduledSessionDeletionForQuit(
+  ctx: ExtensionContext,
+): Promise<void> {
+  const sessionFile = pendingSessionFileForQuitDeletion;
+  pendingSessionFileForQuitDeletion = undefined;
+
+  if (!sessionFile) {
+    return;
+  }
+
+  try {
+    const deleteResult = await deleteSessionFile(sessionFile);
+    if (!deleteResult.ok) {
+      ctx.ui.notify(
+        `Failed to delete the current session during shutdown: ${deleteResult.error}`,
+        "warning",
+      );
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    ctx.ui.notify(
+      `Failed to delete the current session during shutdown: ${message}`,
+      "warning",
+    );
+  }
+}

package/src/tui/agent-target-picker.ts

@@ -0,0 +1,306 @@
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth, type Component } from "@mariozechner/pi-tui";
+
+import type { SelectableAgent } from "../agent-target.js";
+
+interface ThemeLike {
+  fg?: unknown;
+  bold?: unknown;
+}
+
+interface OverlayOptions {
+  anchor: "center";
+  width: number;
+  maxHeight: number;
+  margin: number;
+}
+
+const TITLE_TEXT = "SELECT TARGET AGENT";
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function fitLine(text: string, width: number): string {
+  return truncateToWidth(text, Math.max(1, width), "…", true);
+}
+
+function formatTheme(theme: ThemeLike, color: string, text: string): string {
+  try {
+    if (typeof theme.fg === "function") {
+      const format = theme.fg as (resolvedColor: string, value: string) => string;
+      return format(color, text);
+    }
+  } catch {
+    // Fall back to plain text.
+  }
+
+  return text;
+}
+
+function formatBold(theme: ThemeLike, text: string): string {
+  try {
+    if (typeof theme.bold === "function") {
+      const format = theme.bold as (value: string) => string;
+      return format(text);
+    }
+  } catch {
+    // Fall back to plain text.
+  }
+
+  return text;
+}
+
+function frameTop(width: number): string {
+  return `╭${"─".repeat(width)}╮`;
+}
+
+function frameDivider(width: number): string {
+  return `├${"─".repeat(width)}┤`;
+}
+
+function frameBottom(width: number): string {
+  return `╰${"─".repeat(width)}╯`;
+}
+
+function frameLine(content: string, width: number): string {
+  const clipped = fitLine(content, width);
+  const padded = clipped.padEnd(width, " ");
+  return `│${padded}│`;
+}
+
+function resolveOverlayOptions(): OverlayOptions {
+  const terminalWidth =
+    typeof process.stdout.columns === "number" && Number.isFinite(process.stdout.columns)
+      ? process.stdout.columns
+      : 120;
+  const terminalHeight =
+    typeof process.stdout.rows === "number" && Number.isFinite(process.stdout.rows)
+      ? process.stdout.rows
+      : 36;
+
+  const margin = 1;
+  const availableWidth = Math.max(24, terminalWidth - margin * 2);
+  const preferredWidth = terminalWidth >= 140 ? 96 : terminalWidth >= 120 ? 88 : 80;
+  const width = Math.max(24, Math.min(preferredWidth, availableWidth));
+
+  const availableHeight = Math.max(10, terminalHeight - margin * 2);
+  const preferredHeight = Math.max(10, Math.floor(terminalHeight * 0.72));
+  const maxHeight = Math.min(preferredHeight, availableHeight);
+
+  return {
+    anchor: "center",
+    width,
+    maxHeight,
+    margin,
+  };
+}
+
+function formatModeBadge(agent: SelectableAgent): string {
+  return `[${agent.mode ?? "primary"}]`;
+}
+
+function buildAgentRow(
+  agent: SelectableAgent,
+  isCurrent: boolean,
+  isSelected: boolean,
+  width: number,
+): string {
+  const prefix = isSelected ? "❯ " : "  ";
+  const currentMarker = isCurrent ? "●" : "○";
+  const leading = `${prefix}${currentMarker} ${agent.name} ${formatModeBadge(agent)} — `;
+  const availableDescriptionWidth = Math.max(1, width - visibleWidth(leading));
+  return `${leading}${fitLine(agent.description, availableDescriptionWidth)}`;
+}
+
+class AgentTargetPicker implements Component {
+  private cursorIndex: number;
+  private scrollOffset = 0;
+  private lastViewportSize = 1;
+
+  constructor(
+    private readonly agents: readonly SelectableAgent[],
+    private readonly currentAgentName: string | null,
+    private readonly theme: ThemeLike,
+    private readonly maxRenderRows: number,
+    private readonly onSelect: (agentName: string | null) => void,
+    private readonly requestRender: () => void,
+  ) {
+    const currentIndex = currentAgentName
+      ? agents.findIndex((agent) => agent.name === currentAgentName)
+      : -1;
+    this.cursorIndex = currentIndex >= 0 ? currentIndex : 0;
+  }
+
+  render(_width: number): string[] {
+    const lines: string[] = [];
+    const frameInnerWidth = resolveOverlayOptions().width - 2;
+    const maxRows = this.resolveMaxRenderRows();
+    const viewportSize = this.resolveViewportSize(maxRows);
+    this.lastViewportSize = viewportSize;
+    this.ensureCursorVisible(viewportSize);
+
+    const start = this.scrollOffset;
+    const end = Math.min(this.agents.length, start + viewportSize);
+    const currentText = this.currentAgentName ?? "none";
+    const statsText = `CURRENT: ${currentText}  VISIBLE: ${this.agents.length === 0 ? "0-0/0" : `${start + 1}-${end}/${this.agents.length}`}`;
+
+    lines.push(frameTop(frameInnerWidth));
+    lines.push(
+      formatTheme(
+        this.theme,
+        "accent",
+        formatBold(this.theme, frameLine(` ${TITLE_TEXT}`, frameInnerWidth)),
+      ),
+    );
+    lines.push(formatTheme(this.theme, "dim", frameLine(` ${statsText}`, frameInnerWidth)));
+    lines.push(frameDivider(frameInnerWidth));
+
+    if (this.agents.length === 0) {
+      lines.push(formatTheme(this.theme, "dim", frameLine(" No agents available.", frameInnerWidth)));
+    } else {
+      for (let index = start; index < end; index += 1) {
+        const agent = this.agents[index];
+        const row = frameLine(
+          buildAgentRow(agent, agent.name === this.currentAgentName, index === this.cursorIndex, frameInnerWidth),
+          frameInnerWidth,
+        );
+        lines.push(
+          index === this.cursorIndex
+            ? formatTheme(this.theme, "accent", formatBold(this.theme, row))
+            : row,
+        );
+      }
+    }
+
+    lines.push(frameDivider(frameInnerWidth));
+    lines.push(formatTheme(this.theme, "dim", frameLine(" ↑/↓/j/k: move  Enter: select  Esc/q: cancel ", frameInnerWidth)));
+    lines.push(frameBottom(frameInnerWidth));
+    return lines;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c") || matchesKey(data, "q")) {
+      this.onSelect(null);
+      return;
+    }
+
+    if (matchesKey(data, "up") || matchesKey(data, "k")) {
+      this.moveCursor(-1);
+      return;
+    }
+
+    if (matchesKey(data, "down") || matchesKey(data, "j")) {
+      this.moveCursor(1);
+      return;
+    }
+
+    if (matchesKey(data, "pageUp")) {
+      this.moveCursor(-Math.max(1, this.lastViewportSize - 1));
+      return;
+    }
+
+    if (matchesKey(data, "pageDown")) {
+      this.moveCursor(Math.max(1, this.lastViewportSize - 1));
+      return;
+    }
+
+    if (matchesKey(data, "home")) {
+      this.cursorIndex = 0;
+      this.ensureCursorVisible(this.lastViewportSize);
+      this.requestRender();
+      return;
+    }
+
+    if (matchesKey(data, "end")) {
+      this.cursorIndex = Math.max(0, this.agents.length - 1);
+      this.ensureCursorVisible(this.lastViewportSize);
+      this.requestRender();
+      return;
+    }
+
+    if (matchesKey(data, "return")) {
+      const agent = this.agents[this.cursorIndex];
+      this.onSelect(agent?.name ?? null);
+    }
+  }
+
+  private moveCursor(delta: number): void {
+    if (this.agents.length === 0) {
+      this.cursorIndex = 0;
+      this.scrollOffset = 0;
+      return;
+    }
+
+    this.cursorIndex = clamp(this.cursorIndex + delta, 0, this.agents.length - 1);
+    this.ensureCursorVisible(this.lastViewportSize);
+    this.requestRender();
+  }
+
+  private resolveMaxRenderRows(): number {
+    const terminalRows =
+      typeof process.stdout.rows === "number" && Number.isFinite(process.stdout.rows) && process.stdout.rows > 0
+        ? Math.floor(process.stdout.rows)
+        : this.maxRenderRows;
+
+    return Math.max(10, Math.min(this.maxRenderRows, terminalRows));
+  }
+
+  private resolveViewportSize(maxRows: number): number {
+    const reservedRows = 6;
+    return Math.max(1, maxRows - reservedRows);
+  }
+
+  private ensureCursorVisible(viewportSize: number): void {
+    if (this.agents.length === 0) {
+      this.cursorIndex = 0;
+      this.scrollOffset = 0;
+      return;
+    }
+
+    this.cursorIndex = clamp(this.cursorIndex, 0, this.agents.length - 1);
+
+    if (this.cursorIndex < this.scrollOffset) {
+      this.scrollOffset = this.cursorIndex;
+    } else if (this.cursorIndex >= this.scrollOffset + viewportSize) {
+      this.scrollOffset = this.cursorIndex - viewportSize + 1;
+    }
+
+    const maxOffset = Math.max(0, this.agents.length - viewportSize);
+    this.scrollOffset = clamp(this.scrollOffset, 0, maxOffset);
+  }
+}
+
+export async function showAgentTargetPicker(
+  ctx: ExtensionCommandContext,
+  agents: readonly SelectableAgent[],
+  currentAgentName: string | null,
+): Promise<string | null> {
+  const overlayOptions = resolveOverlayOptions();
+  let selectedAgentName: string | null = null;
+  let resolved = false;
+
+  await ctx.ui.custom<void>(
+    (tui, theme, _keybindings, done) =>
+      new AgentTargetPicker(
+        agents,
+        currentAgentName,
+        theme,
+        overlayOptions.maxHeight,
+        (agentName) => {
+          resolved = true;
+          selectedAgentName = agentName;
+          done();
+        },
+        () => {
+          tui.requestRender();
+        },
+      ),
+    {
+      overlay: true,
+      overlayOptions,
+    },
+  );
+
+  return resolved ? selectedAgentName : null;
+}