pi-sessions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thurstonsand
+
+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

@@ -0,0 +1,173 @@
+# pi-sessions
+
+`pi-sessions` turns your old Pi sessions into something you can actually reuse. It gives you search, follow-up Q&A, deliberate handoffs into new child sessions, automatic session titles, and a local index that keeps future sessions searchable.
+
+## Screenshots
+
+### Session lookup
+
+![session picker](images/session_picker.png)
+
+### Handoffs
+
+![handoff preview](images/handoff.png)
+
+### Ask about old sessions
+
+![session_search tool](images/session_search.png)
+
+![session_ask tool](images/session_ask.png)
+
+## Install
+
+**From npm** (recommended):
+
+```bash
+pi install npm:pi-sessions
+```
+
+If you want to run directly from a local clone while developing:
+
+```bash
+pi -e /absolute/path/to/pi-sessions
+```
+
+## Quick start
+
+1. Install the package.
+2. Open Pi and run `/session-index`.
+3. Press `r` to build the index for all your prior sessions.
+4. Try the main flows:
+
+```text
+What session did I implement the db layer?
+```
+
+```text
+/handoff i want to implement the frontend component now
+```
+
+## Features
+
+| Extension          | Surface                               | What it does                                            |
+| ------------------ | ------------------------------------- | ------------------------------------------------------- |
+| Session Search     | `session_search` pi tool              | Search through old sessions                             |
+| Session Ask        | `session_ask` pi tool                 | Ask questions about old sessions                        |
+| Session Handoff    | `/handoff`, session picker shortcut   | Start a focused new session; alternative to compaction  |
+| Session Picker     | `Alt+O`                               | Reference old sessions in your prompt                   |
+| Session Index      | `/session-index` slash command        | Shows index status and rebuilds the local session index |
+| Session Auto Title | in background, `/title` slash command | Give sessions titles                                    |
+
+## Session Handoff
+
+`/handoff <goal>` starts a focused new session. Give pi a goal, and it will generate a prompt for you to review before kicking it off.
+
+Flow:
+
+- run `/handoff <goal>`
+- review the generated prompt preview
+- optionally edit the prompt to make any adjustments
+- start the new session
+
+If you do nothing, the preview autostarts after a short countdown.
+
+## Session picker
+
+Directly reference prior sessions by looking them up by contents.
+
+- shortcut: `Alt+O`
+- press `Tab` to switch between current folder and all sessions
+- type to filter results
+- press `Enter` to insert a session id into your prompt
+
+### Handoff setting
+
+If you want to override the shortcut, put this in your `~/.pi/agent/settings.json`:
+
+```json
+{
+  "sessions": {
+    "handoff": {
+      "pickerShortcut": "alt+p"
+    }
+  }
+}
+```
+
+## Session Index
+
+By default, `pi-sessions` will start indexing all conversations moving forward. If you want to backfill all prior conversations:
+
+- run `/session-index`
+- hit `r` to (re)index everything
+
+this is idempotent, so if you run into any issues, or disable pi-sessions for a while, feel free to re-index to see if that resolves anything.
+
+By default the index lives at:
+
+```text
+~/.pi/agent/pi-sessions/index.sqlite
+```
+
+but you can change the location in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "sessions": {
+    "index": {
+      "dir": "~/.pi/agent/pi-sessions"
+    }
+  }
+}
+```
+
+## Session Auto Title
+
+The auto-title extension keeps your session list readable by:
+
+- Setting a title based on initial prompt
+- Reevaluating the title every 4 turns to see if it should be updated
+
+To manage existing titles, run `/title`, where you can:
+
+- Regenerate a title for the current session
+- Generate titles for all sessions in the folder
+- Generate titles for all sessions across pi
+
+![session title window](images/session-title.png)
+
+Note that generating titles for all sessions can take some time, and will hit your configured model with the full contents of all sessions.
+
+Behavior notes:
+
+- automatic retitles run every few turns
+- if you manually rename a session with `/name`, automatic retitling pauses for that session
+- Regenerate the title for the current session to resume automatic retitling
+- if unconfigured, it will attempt to use these models in order, first one that is available:
+  - `google/gemini-flash-lite-latest`
+  - `anthropic/claude-haiku-4-5`
+  - `openai/gpt-5.4-mini`
+- your currently configured model
+
+To change auto-titling settings, edit `~/.pi/agent/settings.json`:
+
+```json
+{
+  "sessions": {
+    "autoTitle": {
+      "refreshTurns": 4,
+      "model": "anthropic/claude-haiku-4-5"
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run check
+npm test
+```
+
+For an end-to-end manual flow, see [SMOKE.md](./SMOKE.md).

package/extensions/session-ask.ts

@@ -0,0 +1,297 @@
+import { complete, type Message } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, Theme } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { type RenderedSessionTree, renderSessionTreeMarkdown } from "./session-search/extract.js";
+import {
+  getIndexStatus,
+  getSessionById,
+  INDEX_SCHEMA_VERSION,
+  openIndexDatabase,
+  type SessionLineageRow,
+} from "./shared/session-index/index.js";
+import { formatSessionTitleOrShortId, isExactSessionId } from "./shared/session-ui.js";
+import { loadSettings } from "./shared/settings.js";
+
+const SESSION_ASK_SYSTEM_PROMPT = `You are analyzing a Pi coding session transcript. The transcript includes the entire session tree, including abandoned branches and summaries.
+
+Answer the user's question using only the session contents. Be specific and concise. Include exact file paths, decisions, and outcomes when present. If the answer is not in the session, say so clearly.`;
+
+const COLLAPSED_ANSWER_PREVIEW_ROWS = 6;
+
+interface SessionAskToolParams {
+  session: string;
+  question: string;
+}
+
+interface SessionAskToolDetails {
+  cancelled?: boolean | undefined;
+  error?: boolean | undefined;
+  answer?: string | undefined;
+  question?: string | undefined;
+  sessionId?: string | undefined;
+  sessionName?: string | undefined;
+  sessionPath?: string | undefined;
+}
+
+interface TextContentBlock {
+  type: "text";
+  text: string;
+}
+
+export default function sessionAskExtension(pi: ExtensionAPI): void {
+  const settings = loadSettings();
+
+  pi.registerTool({
+    name: "session_ask",
+    label: "Session Ask",
+    description: "Interrogate a Pi session",
+    promptSnippet:
+      "Use when you have a session id and want to recall information, decisions, reasoning, etc from it",
+    promptGuidelines: ["Prefer focused follow-up questions over broad recap requests"],
+    parameters: Type.Object({
+      session: Type.String({
+        description: "Bare UUID for the session",
+      }),
+      question: Type.String({
+        description: "What to extract, verify, or explain from that session",
+      }),
+    }),
+    async execute(_toolCallId, params: SessionAskToolParams, signal, onUpdate, ctx) {
+      const sessionId = params.session.trim();
+      if (!sessionId) {
+        return errorResult("session_ask requires a session id.", { error: true });
+      }
+
+      const question = params.question.trim();
+      if (!question) {
+        return errorResult("session_ask requires a question.", { error: true, sessionId });
+      }
+
+      const resolvedTarget = resolveSessionAskTarget(sessionId, settings.index.path);
+      if (!resolvedTarget.resolved) {
+        return errorResult(resolvedTarget.error ?? "Unable to resolve session id.", {
+          error: true,
+          sessionId,
+          question,
+        });
+      }
+
+      if (!ctx.model) {
+        return errorResult("No active model is available for session_ask.", { error: true });
+      }
+
+      const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+      if (!auth.ok || !auth.apiKey) {
+        return errorResult(`No API key is available for ${ctx.model.provider}/${ctx.model.id}.`, {
+          error: true,
+        });
+      }
+
+      const progressDetails: SessionAskToolDetails = {
+        question,
+        sessionId: resolvedTarget.resolved.sessionId,
+        sessionName: resolvedTarget.resolved.sessionName,
+        sessionPath: resolvedTarget.resolved.sessionPath,
+      };
+      onUpdate?.({
+        content: [{ type: "text", text: "Reading session..." }],
+        details: progressDetails,
+      });
+
+      let rendered: RenderedSessionTree;
+      try {
+        rendered = renderSessionTreeMarkdown(resolvedTarget.resolved.sessionPath);
+      } catch (error) {
+        return errorResult(formatSessionAskLoadError(resolvedTarget.resolved.sessionPath, error), {
+          error: true,
+          sessionId,
+          sessionPath: resolvedTarget.resolved.sessionPath,
+          question,
+        });
+      }
+
+      const loadedDetails: SessionAskToolDetails = {
+        question,
+        sessionId: rendered.sessionId,
+        sessionName: rendered.sessionName,
+        sessionPath: resolvedTarget.resolved.sessionPath,
+      };
+      onUpdate?.({
+        content: [
+          {
+            type: "text",
+            text: formatSessionAskHeader(rendered.sessionId, rendered.sessionName, question),
+          },
+        ],
+        details: loadedDetails,
+      });
+
+      const userMessage: Message = {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: [`## Session`, rendered.markdown, "", "## Question", question].join("\n"),
+          },
+        ],
+        timestamp: Date.now(),
+      };
+
+      const response = await complete(
+        ctx.model,
+        { systemPrompt: SESSION_ASK_SYSTEM_PROMPT, messages: [userMessage] },
+        signal
+          ? {
+              apiKey: auth.apiKey,
+              ...(auth.headers ? { headers: auth.headers } : {}),
+              signal,
+            }
+          : {
+              apiKey: auth.apiKey,
+              ...(auth.headers ? { headers: auth.headers } : {}),
+            },
+      );
+
+      if (response.stopReason === "aborted") {
+        return errorResult("Session ask was cancelled.", { cancelled: true });
+      }
+
+      const answer = collectTextBlocks(response.content).join("\n").trim();
+
+      const details: SessionAskToolDetails = {
+        answer,
+        sessionId: resolvedTarget.resolved.sessionId,
+        sessionName: resolvedTarget.resolved.sessionName,
+        sessionPath: resolvedTarget.resolved.sessionPath,
+        question,
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              formatSessionAskHeader(rendered.sessionId, rendered.sessionName, question),
+              answer || "No answer generated.",
+            ].join("\n\n"),
+          },
+        ],
+        details,
+      };
+    },
+    renderResult(result, { expanded, isPartial }, theme) {
+      const details = result.details as SessionAskToolDetails | undefined;
+      const content = result.content[0];
+      if (content?.type !== "text") {
+        return new Text(theme.fg("error", "No session output"), 0, 0);
+      }
+
+      if (isPartial) {
+        const lines = [theme.bold(theme.fg("warning", "Reading session..."))];
+        if (details?.sessionId || details?.sessionName) {
+          const identity = formatSessionTitleOrShortId(details.sessionName, details.sessionId);
+          lines.push(`title: ${theme.fg("accent", identity)}`);
+        }
+        if (details?.question) {
+          lines.push(theme.fg("muted", `prompt: ${details.question}`));
+        }
+        return new Text(lines.join("\n"), 0, 0);
+      }
+
+      if (details?.cancelled) {
+        return new Text(theme.fg("warning", content.text), 0, 0);
+      }
+
+      if (details?.error) {
+        return new Text(theme.fg("error", content.text), 0, 0);
+      }
+
+      const answer = (details?.answer ?? "").trim() || "No answer generated.";
+      const identity = formatSessionTitleOrShortId(details?.sessionName, details?.sessionId);
+      const lines = [`title: ${theme.bold(identity)}`];
+      if (details?.question) {
+        lines.push(theme.fg("muted", `prompt: ${details.question}`));
+        lines.push("");
+      }
+      lines.push(...formatSessionAskAnswerPreview(answer, expanded, theme));
+      return new Text(lines.join("\n"), 0, 0);
+    },
+  });
+}
+
+function resolveSessionAskTarget(
+  sessionId: string,
+  indexPath: string,
+): {
+  resolved?: SessionLineageRow | undefined;
+  error?: string | undefined;
+} {
+  if (!isExactSessionId(sessionId)) {
+    return {
+      error:
+        "session_ask requires an exact session UUID. Use autocomplete or session_search to find it.",
+    };
+  }
+
+  const status = getIndexStatus(indexPath);
+  if (!status.exists || status.schemaVersion !== INDEX_SCHEMA_VERSION) {
+    return {
+      error: `Session index missing or incompatible at ${indexPath}. Run /session-index and press r to rebuild it.`,
+    };
+  }
+
+  const db = openIndexDatabase(status.dbPath, { create: false });
+  try {
+    const row = getSessionById(db, sessionId);
+    if (!row) {
+      return { error: `No indexed session found for id: ${sessionId}` };
+    }
+
+    return { resolved: row };
+  } finally {
+    db.close();
+  }
+}
+
+function collectTextBlocks(content: Array<{ type: string; text?: string }>): string[] {
+  return content.filter(isTextContentBlock).map((block) => block.text);
+}
+
+function formatSessionAskHeader(sessionId: string, sessionName: string, question: string): string {
+  return [
+    `session: ${sessionId}`,
+    `title: ${sessionName || "[unnamed]"}`,
+    `question: ${question}`,
+  ].join("\n");
+}
+
+function errorResult(
+  text: string,
+  details: SessionAskToolDetails,
+): { content: Array<{ type: "text"; text: string }>; details: SessionAskToolDetails } {
+  return {
+    content: [{ type: "text", text }],
+    details,
+  };
+}
+
+function formatSessionAskAnswerPreview(answer: string, expanded: boolean, theme: Theme): string[] {
+  const lines = answer.split(/\r?\n/);
+  if (expanded || lines.length <= COLLAPSED_ANSWER_PREVIEW_ROWS) {
+    return lines;
+  }
+
+  return [...lines.slice(0, COLLAPSED_ANSWER_PREVIEW_ROWS), theme.fg("dim", "...")];
+}
+
+function formatSessionAskLoadError(sessionPath: string, error: unknown): string {
+  if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+    return `Session file not found: ${sessionPath}`;
+  }
+
+  return `Unable to load session file: ${sessionPath}`;
+}
+
+function isTextContentBlock(content: { type: string; text?: string }): content is TextContentBlock {
+  return content.type === "text" && typeof content.text === "string";
+}

package/extensions/session-auto-title/command.ts

@@ -0,0 +1,109 @@
+import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { AutocompleteItem } from "@mariozechner/pi-tui";
+
+export const TITLE_USAGE = "Usage: /title [this|folder|pi] [-f]";
+
+export type RetitleScope = "this" | "folder" | "global";
+export type RetitleMode = "backfill" | "all";
+
+export type RetitleCommandInvocation =
+  | { kind: "open-pane" }
+  | {
+      kind: "run";
+      scope: RetitleScope;
+      mode?: RetitleMode;
+      force?: boolean;
+    };
+
+export type RetitleCommandParseResult =
+  | RetitleCommandInvocation
+  | {
+      kind: "error";
+      message: string;
+    };
+
+export type RetitleCommandOutcome = "success" | "cancelled" | "failed";
+
+const VALID_TOKENS = new Set(["this", "folder", "pi", "-f"]);
+
+const ARGUMENT_COMPLETIONS: AutocompleteItem[] = [
+  {
+    value: "this",
+    label: "this",
+    description: "Retitle the current session immediately",
+  },
+  {
+    value: "folder",
+    label: "folder",
+    description: "Backfill untitled sessions in this folder; add -f to skip confirmation",
+  },
+  {
+    value: "pi",
+    label: "pi",
+    description: "Backfill untitled sessions across all of Pi; add -f to skip confirmation",
+  },
+];
+
+export function createSessionAutoTitleCommandHandler(
+  execute: (
+    invocation: RetitleCommandInvocation,
+    ctx: ExtensionCommandContext,
+  ) => Promise<RetitleCommandOutcome>,
+): (args: string, ctx: ExtensionCommandContext) => Promise<void> {
+  return async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
+    const parsed = parseRetitleCommand(args, ctx.hasUI);
+    if (parsed.kind === "error") {
+      ctx.ui.notify(parsed.message, "error");
+      return;
+    }
+
+    if (parsed.kind === "run") {
+      await ctx.waitForIdle();
+    }
+
+    const outcome = await execute(parsed, ctx);
+    if (outcome === "failed") {
+      ctx.ui.notify("Session retitle failed.", "error");
+    }
+  };
+}
+
+export function getRetitleArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+  const normalizedPrefix = argumentPrefix.trimStart().toLowerCase();
+  const filtered = ARGUMENT_COMPLETIONS.filter((item) =>
+    item.value.toLowerCase().startsWith(normalizedPrefix),
+  );
+  return filtered.length > 0 ? filtered : null;
+}
+
+export function parseRetitleCommand(args: string, hasUI: boolean): RetitleCommandParseResult {
+  const trimmedArgs = args.trim();
+  if (!trimmedArgs) {
+    return hasUI ? { kind: "open-pane" } : { kind: "run", scope: "this" };
+  }
+
+  const tokens = trimmedArgs.split(/\s+/);
+  const tokenSet = new Set(tokens);
+  if (tokenSet.size !== tokens.length || tokens.some((t) => !VALID_TOKENS.has(t))) {
+    return { kind: "error", message: TITLE_USAGE };
+  }
+
+  if (tokenSet.has("this")) {
+    if (tokenSet.size !== 1) {
+      return { kind: "error", message: TITLE_USAGE };
+    }
+    return { kind: "run", scope: "this" };
+  }
+
+  const scopeCount = Number(tokenSet.has("folder")) + Number(tokenSet.has("pi"));
+  if (scopeCount !== 1) {
+    return { kind: "error", message: TITLE_USAGE };
+  }
+
+  return {
+    kind: "run",
+    scope: tokenSet.has("pi") ? "global" : "folder",
+    mode: "backfill",
+    ...(tokenSet.has("-f") && { force: true }),
+  };
+}

package/extensions/session-auto-title/context.ts

@@ -0,0 +1,41 @@
+import {
+  buildSessionContext,
+  convertToLlm,
+  type SessionEntry,
+  serializeConversation,
+} from "@mariozechner/pi-coding-agent";
+
+export interface AutoTitleContext {
+  cwd: string | undefined;
+  currentTitle: string | undefined;
+  conversationText: string;
+  userTurnCount: number;
+  assistantTurnCount: number;
+}
+
+export function buildAutoTitleContext(
+  entries: SessionEntry[],
+  leafId: string | null,
+  options?: { cwd?: string; currentTitle?: string | undefined },
+): AutoTitleContext {
+  const sessionContext = buildSessionContext(entries, leafId);
+  const conversationText = serializeConversation(convertToLlm(sessionContext.messages));
+
+  let userTurnCount = 0;
+  let assistantTurnCount = 0;
+  for (const message of sessionContext.messages) {
+    if (message.role === "user") {
+      userTurnCount += 1;
+    } else if (message.role === "assistant") {
+      assistantTurnCount += 1;
+    }
+  }
+
+  return {
+    cwd: options?.cwd,
+    currentTitle: options?.currentTitle,
+    conversationText,
+    userTurnCount,
+    assistantTurnCount,
+  };
+}