pi-sessions 0.1.0

package/extensions/session-handoff/refs.ts

@@ -0,0 +1,151 @@
+import path from "node:path";
+import { parseSessionFile } from "../session-search/extract.js";
+import {
+  getIndexStatus,
+  getSessionById,
+  INDEX_SCHEMA_VERSION,
+  openIndexDatabase,
+  type SessionLineageRow,
+  type SessionOrigin,
+} from "../shared/session-index/index.js";
+
+const HANDOFF_REF_PREFIX = "@handoff/";
+const SESSION_REFERENCE_HELP =
+  "Expected an absolute session path, a raw session id, or @handoff/<full-session-id>.";
+
+export type SessionReferenceKind = "path" | "session_id" | "handoff_ref";
+
+export interface ResolvedSessionReference {
+  input: string;
+  kind: SessionReferenceKind;
+  canonicalRef: string;
+  sessionId: string;
+  sessionPath: string;
+  sessionName: string;
+  parentSessionPath?: string | undefined;
+  parentSessionId?: string | undefined;
+  sessionOrigin?: SessionOrigin | undefined;
+}
+
+export interface SessionReferenceResolution {
+  resolved?: ResolvedSessionReference | undefined;
+  error?: string | undefined;
+}
+
+export function formatHandoffRef(sessionId: string): string {
+  return `${HANDOFF_REF_PREFIX}${sessionId}`;
+}
+
+export function isHandoffRef(value: string): boolean {
+  return value.startsWith(HANDOFF_REF_PREFIX);
+}
+
+export function resolveSessionReference(
+  reference: string,
+  options: { indexPath: string },
+): SessionReferenceResolution {
+  const trimmed = reference.trim();
+  if (!trimmed) {
+    return { error: `Missing session reference. ${SESSION_REFERENCE_HELP}` };
+  }
+
+  if (path.isAbsolute(trimmed)) {
+    return resolveAbsoluteSessionPath(trimmed);
+  }
+
+  if (isHandoffRef(trimmed)) {
+    return resolveIndexedReference(
+      trimmed,
+      trimmed.slice(HANDOFF_REF_PREFIX.length),
+      "handoff_ref",
+      options,
+    );
+  }
+
+  return resolveIndexedReference(trimmed, trimmed, "session_id", options);
+}
+
+function resolveAbsoluteSessionPath(sessionPath: string): SessionReferenceResolution {
+  try {
+    const parsed = parseSessionFile(sessionPath);
+    if (!parsed) {
+      return { error: `Unable to parse session file: ${sessionPath}` };
+    }
+
+    return {
+      resolved: {
+        input: sessionPath,
+        kind: "path",
+        canonicalRef: formatHandoffRef(parsed.header.id),
+        sessionId: parsed.header.id,
+        sessionPath,
+        sessionName: parsed.sessionName,
+        parentSessionPath: normalizeOptionalString(parsed.header.parentSession),
+      },
+    };
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return { error: `Session file not found: ${sessionPath}` };
+    }
+
+    return { error: `Unable to load session file: ${sessionPath}` };
+  }
+}
+
+function resolveIndexedReference(
+  input: string,
+  rawValue: string,
+  kind: SessionReferenceKind,
+  options: { indexPath: string },
+): SessionReferenceResolution {
+  const value = rawValue.trim();
+  if (!value) {
+    return { error: `Invalid session reference: ${input}. ${SESSION_REFERENCE_HELP}` };
+  }
+
+  const status = getIndexStatus(options.indexPath);
+  if (!status.exists || status.schemaVersion !== INDEX_SCHEMA_VERSION) {
+    return {
+      error: `Session reference resolution requires a current index at ${status.dbPath}. Run /session-index and press r to rebuild it.`,
+    };
+  }
+
+  const db = openIndexDatabase(status.dbPath, { create: false });
+  try {
+    const exactMatch = getSessionById(db, value);
+    if (exactMatch) {
+      return { resolved: buildResolvedReference(input, kind, exactMatch) };
+    }
+
+    return { error: `No session found for reference: ${input}. ${SESSION_REFERENCE_HELP}` };
+  } finally {
+    db.close();
+  }
+}
+
+function buildResolvedReference(
+  input: string,
+  kind: SessionReferenceKind,
+  session: SessionLineageRow,
+): ResolvedSessionReference {
+  return {
+    input,
+    kind,
+    canonicalRef: formatHandoffRef(session.sessionId),
+    sessionId: session.sessionId,
+    sessionPath: session.sessionPath,
+    sessionName: session.sessionName,
+    parentSessionPath: session.parentSessionPath,
+    parentSessionId: session.parentSessionId,
+    sessionOrigin: session.sessionOrigin,
+  };
+}
+
+function normalizeOptionalString(value: string | undefined): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}

package/extensions/session-handoff/review.ts

@@ -0,0 +1,268 @@
+import type {
+  ExtensionCommandContext,
+  ExtensionUIContext,
+  Theme,
+} from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@mariozechner/pi-tui";
+
+const PREVIEW_TIMEOUT_MS = 8_000;
+const PREVIEW_BODY_LINE_LIMIT = 16;
+
+type ReviewAction = "accept" | "edit" | "cancel";
+
+interface TimerHandle {
+  stop(): void;
+}
+
+interface PreviewClock {
+  now(): number;
+  setInterval(callback: () => void, delayMs: number): TimerHandle;
+}
+
+const defaultPreviewClock: PreviewClock = {
+  now() {
+    return Date.now();
+  },
+  setInterval(callback, delayMs) {
+    const timer = globalThis.setInterval(callback, delayMs);
+    return {
+      stop() {
+        globalThis.clearInterval(timer);
+      },
+    };
+  },
+};
+
+export interface HandoffPreviewOptions {
+  timeoutMs?: number;
+  clock?: PreviewClock;
+}
+
+export class HandoffPreviewComponent implements Component {
+  private readonly draft: string;
+  private readonly theme: Theme;
+  private readonly onDone: (action: ReviewAction) => void;
+  private readonly requestRender: () => void;
+  private readonly deadlineAt: number;
+  private readonly clock: PreviewClock;
+  private readonly intervalHandle: TimerHandle;
+  private isDone = false;
+  private isTimerActive = true;
+  private scrollOffset = 0;
+  private previewWidth = 80;
+
+  public constructor(
+    draft: string,
+    theme: Theme,
+    requestRender: () => void,
+    onDone: (action: ReviewAction) => void,
+    options: HandoffPreviewOptions = {},
+  ) {
+    this.draft = draft;
+    this.theme = theme;
+    this.requestRender = requestRender;
+    this.onDone = onDone;
+    this.clock = options.clock ?? defaultPreviewClock;
+    this.deadlineAt = this.clock.now() + (options.timeoutMs ?? PREVIEW_TIMEOUT_MS);
+    this.intervalHandle = this.clock.setInterval(() => {
+      if (this.isDone) {
+        return;
+      }
+
+      if (!this.isTimerActive) {
+        return;
+      }
+
+      if (this.clock.now() >= this.deadlineAt) {
+        this.finish("accept");
+        return;
+      }
+
+      this.requestRender();
+    }, 200);
+  }
+
+  public handleInput(data: string): void {
+    if (matchesKey(data, Key.enter)) {
+      this.finish("accept");
+      return;
+    }
+
+    if (matchesKey(data, Key.escape)) {
+      this.finish("cancel");
+      return;
+    }
+
+    if (matchesKey(data, "e")) {
+      this.finish("edit");
+      return;
+    }
+
+    if (matchesKey(data, "j")) {
+      this.disableTimer();
+      this.scrollBy(1);
+      return;
+    }
+
+    if (matchesKey(data, "k")) {
+      this.disableTimer();
+      this.scrollBy(-1);
+    }
+  }
+
+  public render(width: number): string[] {
+    const modalWidth = Math.max(24, width - 4);
+    const promptBoxWidth = Math.max(20, modalWidth - 4);
+    this.previewWidth = Math.max(16, promptBoxWidth - 4);
+
+    const promptLines = renderPromptSection(
+      this.buildPreviewLines(this.previewWidth),
+      promptBoxWidth,
+      this.theme,
+    );
+
+    const contentLines = [
+      this.getTitleLine(),
+      "",
+      this.theme.fg("muted", formatKeymapLine("Enter: start session", "Esc: cancel")),
+      this.theme.fg("muted", formatKeymapLine("e: edit prompt", "j/k: scroll")),
+      "",
+      ...promptLines,
+    ];
+
+    return renderStrongModal(contentLines, width, this.theme);
+  }
+
+  public invalidate(): void {}
+
+  public stop(): void {
+    this.intervalHandle.stop();
+  }
+
+  private buildPreviewLines(width: number): string[] {
+    const wrappedLines = wrapTextWithAnsi(this.draft, Math.max(20, width));
+    const maxOffset = Math.max(0, wrappedLines.length - PREVIEW_BODY_LINE_LIMIT);
+    this.scrollOffset = Math.min(this.scrollOffset, maxOffset);
+
+    return wrappedLines
+      .slice(this.scrollOffset, this.scrollOffset + PREVIEW_BODY_LINE_LIMIT)
+      .map((line) => truncateToWidth(line, width));
+  }
+
+  private finish(action: ReviewAction): void {
+    if (this.isDone) {
+      return;
+    }
+
+    this.isDone = true;
+    this.intervalHandle.stop();
+    this.onDone(action);
+  }
+
+  private scrollBy(delta: number): void {
+    const wrappedLines = wrapTextWithAnsi(this.draft, Math.max(20, this.previewWidth));
+    const maxOffset = Math.max(0, wrappedLines.length - PREVIEW_BODY_LINE_LIMIT);
+    const nextOffset = Math.max(0, Math.min(maxOffset, this.scrollOffset + delta));
+    if (nextOffset !== this.scrollOffset) {
+      this.scrollOffset = nextOffset;
+      this.requestRender();
+    }
+  }
+
+  private disableTimer(): void {
+    if (!this.isTimerActive) {
+      return;
+    }
+
+    this.isTimerActive = false;
+    this.requestRender();
+  }
+
+  private getTitleLine(): string {
+    const title = this.theme.fg("accent", this.theme.bold("Handoff preview"));
+    if (!this.isTimerActive) {
+      return title;
+    }
+
+    return `${title}${this.theme.fg("dim", ` (autostart in ${this.getRemainingSeconds()}s)`)}`;
+  }
+
+  private getRemainingSeconds(): number {
+    const remainingMs = Math.max(0, this.deadlineAt - this.clock.now());
+    return Math.ceil(remainingMs / 1_000);
+  }
+}
+
+export function renderStrongModal(lines: string[], width: number, theme: Theme): string[] {
+  const innerWidth = Math.max(20, width - 4);
+  const fillLine = (text: string) => {
+    const truncated = truncateToWidth(text, innerWidth, "…", true);
+    const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+    return theme.bg("customMessageBg", `  ${truncated}${" ".repeat(padding)}  `);
+  };
+
+  return ["", ...lines, ""].map(fillLine);
+}
+
+function formatKeymapLine(left: string, right: string): string {
+  return `${left.padEnd(27, " ")}${right}`;
+}
+
+function renderPromptSection(lines: string[], width: number, _theme: Theme): string[] {
+  const innerWidth = Math.max(16, width - 4);
+  const line = (left: string, text: string, right: string) => {
+    const truncated = truncateToWidth(text, innerWidth, "…", true);
+    const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+    return `${left} ${truncated}${" ".repeat(padding)} ${right}`;
+  };
+
+  return [
+    `┌${"─".repeat(innerWidth + 2)}┐`,
+    ...lines.map((text) => line("│", text, "│")),
+    `└${"─".repeat(innerWidth + 2)}┘`,
+  ];
+}
+
+export async function reviewHandoffDraft(
+  ctx: ExtensionCommandContext,
+  draft: string,
+): Promise<string | undefined> {
+  const action = await runPreviewGate(ctx.ui, draft);
+  if (action === "cancel") {
+    return undefined;
+  }
+
+  if (action === "accept") {
+    return draft;
+  }
+
+  const editedDraft = await ctx.ui.editor("Edit handoff prompt", draft);
+  if (!editedDraft?.trim()) {
+    return undefined;
+  }
+
+  return editedDraft;
+}
+
+async function runPreviewGate(ui: ExtensionUIContext, draft: string): Promise<ReviewAction> {
+  return ui.custom<ReviewAction>(
+    (tui, theme, _keybindings, done) =>
+      new HandoffPreviewComponent(draft, theme, () => tui.requestRender(), done),
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: "80%",
+        maxHeight: "80%",
+        margin: 2,
+      },
+    },
+  );
+}

package/extensions/session-handoff.ts

@@ -0,0 +1,203 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  SessionManager,
+} from "@mariozechner/pi-coding-agent";
+import { buildSessionContext } from "@mariozechner/pi-coding-agent";
+import { Key, matchesKey } from "@mariozechner/pi-tui";
+import { generateHandoffDraft, type HandoffDraftResult } from "./session-handoff/extract.js";
+import {
+  createHandoffSessionMetadata,
+  createPendingSendConsumedEntry,
+  getPendingInitialPromptFromEntries,
+  HANDOFF_METADATA_CUSTOM_TYPE,
+  PENDING_SEND_CONSUMED_CUSTOM_TYPE,
+} from "./session-handoff/metadata.js";
+import { openSessionReferencePicker } from "./session-handoff/picker.js";
+import { SESSION_TOKEN_PREFIX } from "./session-handoff/query.js";
+import { renderStrongModal, reviewHandoffDraft } from "./session-handoff/review.js";
+import { loadSettings } from "./shared/settings.js";
+
+export default function sessionHandoffExtension(pi: ExtensionAPI): void {
+  const settings = loadSettings();
+
+  pi.registerCommand("handoff", {
+    description: "Transfer context to a new focused session",
+    handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("handoff requires interactive mode", "error");
+        return;
+      }
+
+      if (!ctx.model) {
+        ctx.ui.notify("No model selected", "error");
+        return;
+      }
+
+      const goal = args.trim();
+      if (!goal) {
+        ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+        return;
+      }
+
+      const sessionContext = buildSessionContext(
+        ctx.sessionManager.getEntries(),
+        ctx.sessionManager.getLeafId(),
+      );
+      if (sessionContext.messages.length === 0) {
+        ctx.ui.notify("No conversation to hand off", "error");
+        return;
+      }
+
+      let generatedDraft: HandoffDraftResult | undefined;
+      try {
+        generatedDraft = await runWithLoader(
+          ctx,
+          "Generating handoff draft...",
+          async (signal: AbortSignal) => generateHandoffDraft(ctx, goal, signal),
+        );
+      } catch (error) {
+        ctx.ui.notify(formatHandoffError(error), "error");
+        return;
+      }
+
+      if (!generatedDraft) {
+        ctx.ui.notify("Cancelled", "info");
+        return;
+      }
+
+      const approvedDraft = await reviewHandoffDraft(ctx, generatedDraft.draft);
+      if (!approvedDraft) {
+        ctx.ui.notify("Cancelled", "info");
+        return;
+      }
+
+      const parentSession = ctx.sessionManager.getSessionFile();
+
+      const handoffMetadata = createHandoffSessionMetadata(
+        goal,
+        generatedDraft.context.nextTask,
+        approvedDraft,
+      );
+      const writeMetadata = async (sm: SessionManager) => {
+        sm.appendCustomEntry(HANDOFF_METADATA_CUSTOM_TYPE, handoffMetadata);
+      };
+      const newSessionResult = parentSession
+        ? await ctx.newSession({ parentSession, setup: writeMetadata })
+        : await ctx.newSession({ setup: writeMetadata });
+
+      if (newSessionResult.cancelled) {
+        ctx.ui.notify("New session cancelled", "info");
+        return;
+      }
+
+      ctx.ui.notify("Handoff started in a new session.", "info");
+    },
+  });
+
+  pi.registerShortcut(settings.handoff.pickerShortcut, {
+    description: "Open the session reference picker",
+    handler: async (ctx) => {
+      if (!ctx.hasUI) {
+        return;
+      }
+
+      const result = await openSessionReferencePicker(
+        ctx,
+        settings.index.path,
+        settings.handoff.pickerShortcut,
+      );
+      if (result.kind !== "insert-session-token") {
+        return;
+      }
+
+      ctx.ui.pasteToEditor(`${SESSION_TOKEN_PREFIX}${result.sessionId}`);
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    const pending = getPendingInitialPromptFromEntries(ctx.sessionManager.getEntries());
+
+    if (!sessionFile || !pending) {
+      return;
+    }
+
+    pi.appendEntry(
+      PENDING_SEND_CONSUMED_CUSTOM_TYPE,
+      createPendingSendConsumedEntry(pending.initial_prompt_nonce),
+    );
+    pi.sendUserMessage(pending.initial_prompt);
+  });
+
+  pi.on("before_agent_start", async () => {
+    return {
+      systemPrompt:
+        "When the user references @session:<uuid>, treat it as a session token. If you call session_ask, pass only the UUID value, not the @session: prefix.",
+    };
+  });
+}
+
+async function runWithLoader<T>(
+  ctx: ExtensionCommandContext,
+  label: string,
+  task: (signal: AbortSignal) => Promise<T>,
+): Promise<T | undefined> {
+  let taskError: unknown;
+
+  const result = await ctx.ui.custom<T | undefined>(
+    (tui, theme, _keybindings, done) => {
+      const abortController = new AbortController();
+
+      task(abortController.signal)
+        .then(done)
+        .catch((error: unknown) => {
+          if (!abortController.signal.aborted) {
+            taskError = error;
+          }
+          done(undefined);
+        });
+
+      return {
+        render(width: number): string[] {
+          return renderStrongModal(
+            [theme.fg("accent", theme.bold(label)), "", theme.fg("muted", "Press Esc to cancel.")],
+            width,
+            theme,
+          );
+        },
+        invalidate(): void {},
+        handleInput(data: string): void {
+          if (matchesKey(data, Key.escape)) {
+            abortController.abort();
+            done(undefined);
+            tui.requestRender();
+          }
+        },
+      };
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        anchor: "center",
+        width: "70%",
+        maxHeight: "40%",
+        margin: 2,
+      },
+    },
+  );
+
+  if (taskError) {
+    throw taskError;
+  }
+
+  return result;
+}
+
+function formatHandoffError(error: unknown): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message;
+  }
+
+  return "Handoff generation failed.";
+}

package/extensions/session-hooks.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { createSessionHookController } from "./session-search/hooks.js";
+import { loadSettings } from "./shared/settings.js";
+
+interface SessionStartLifecycleEvent {
+  reason?: "startup" | "reload" | "new" | "resume" | "fork";
+  previousSessionFile?: string;
+}
+
+export default function sessionHooksExtension(pi: ExtensionAPI): void {
+  const settings = loadSettings();
+  const controller = createSessionHookController({ indexPath: settings.index.path });
+
+  pi.on("session_start", async (event, ctx) => {
+    const { reason, previousSessionFile } = event as SessionStartLifecycleEvent;
+    const sessionFile = ctx.sessionManager.getSessionFile();
+
+    switch (reason) {
+      case "new":
+      case "resume":
+        await controller.handleSessionSwitch(previousSessionFile, sessionFile, ctx.cwd);
+        break;
+      case "fork":
+        await controller.handleSessionFork(previousSessionFile, sessionFile, ctx.cwd);
+        break;
+      default:
+        await controller.handleSessionStart(sessionFile, ctx.cwd);
+        break;
+    }
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    controller.handleToolCall(event, ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+
+  pi.on("tool_result", async (event) => {
+    controller.handleToolResult(event);
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    await controller.handleTurnEnd(ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+
+  pi.on("session_tree", async (_event, ctx) => {
+    await controller.handleSessionTree(ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+
+  pi.on("session_compact", async (_event, ctx) => {
+    await controller.handleSessionCompact(ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    await controller.handleSessionShutdown(ctx.sessionManager.getSessionFile(), ctx.cwd);
+  });
+}