pi-sessions 0.1.0

package/extensions/session-auto-title.ts

@@ -0,0 +1,209 @@
+import type { Api, Model } from "@mariozechner/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+  SessionStartEvent,
+  TurnEndEvent,
+} from "@mariozechner/pi-coding-agent";
+import {
+  createSessionAutoTitleCommandHandler,
+  getRetitleArgumentCompletions,
+  type RetitleCommandInvocation,
+  type RetitleCommandOutcome,
+} from "./session-auto-title/command.js";
+import {
+  createSessionAutoTitleController,
+  formatAutoTitleFailureSummary,
+  type SessionAutoTitleController,
+} from "./session-auto-title/controller.js";
+import { resolveAutoTitleModel } from "./session-auto-title/model.js";
+import {
+  buildRetitleScopeScan,
+  notifyBulkRetitleResult,
+  persistAutoTitleState,
+  runBulkRetitle,
+  runRetitlePlan,
+} from "./session-auto-title/retitle.js";
+import { showRetitleWizard } from "./session-auto-title/wizard.js";
+import { loadSettings } from "./shared/settings.js";
+
+export {
+  createSessionAutoTitleCommandHandler,
+  getRetitleArgumentCompletions,
+  parseRetitleCommand,
+  TITLE_USAGE,
+} from "./session-auto-title/command.js";
+
+interface TitleRunState {
+  controller: SessionAutoTitleController;
+  getSessionEpoch: () => number;
+  setInFlight: (work: Promise<void>) => void;
+  clearInFlight: () => void;
+}
+
+export default function sessionAutoTitleExtension(pi: ExtensionAPI): void {
+  const settings = loadSettings();
+  const controller = createSessionAutoTitleController(settings.autoTitle);
+  let sessionEpoch = 0;
+  let titleWorkInFlight: Promise<void> | undefined;
+  let resolvedModel: Model<Api> | undefined;
+
+  pi.registerCommand("title", {
+    description: "Generate titles for this session, this folder, or all of Pi",
+    getArgumentCompletions: getRetitleArgumentCompletions,
+    handler: createSessionAutoTitleCommandHandler(
+      async (invocation, ctx): Promise<RetitleCommandOutcome> => {
+        if (titleWorkInFlight) {
+          await titleWorkInFlight;
+        }
+
+        const model = resolvedModel ?? resolveAutoTitleModel(ctx, settings.autoTitle.model)?.model;
+        return handleTitleInvocation(
+          pi,
+          {
+            controller,
+            getSessionEpoch: () => sessionEpoch,
+            setInFlight: (work) => {
+              titleWorkInFlight = work;
+            },
+            clearInFlight: () => {
+              titleWorkInFlight = undefined;
+            },
+          },
+          ctx,
+          model,
+          invocation,
+        );
+      },
+    ),
+  });
+
+  pi.on("session_start", async (_event: SessionStartEvent, ctx: ExtensionContext) => {
+    sessionEpoch += 1;
+    resolvedModel = resolveAutoTitleModel(ctx, settings.autoTitle.model)?.model;
+    persistAutoTitleState(pi, controller.handleSessionStart(ctx));
+  });
+
+  pi.on("turn_end", async (_event: TurnEndEvent, ctx: ExtensionContext) => {
+    const result = controller.handleTurnEnd(ctx);
+    persistAutoTitleState(pi, result.persistedState);
+
+    if (!result.plan || titleWorkInFlight) {
+      return;
+    }
+
+    titleWorkInFlight = runRetitlePlan({
+      pi,
+      controller,
+      ctx,
+      model: resolvedModel,
+      isManual: false,
+      existingPlan: result.plan,
+      getSessionEpoch: () => sessionEpoch,
+      notifyOnSuccess: false,
+    })
+      .then((outcome) => {
+        if (outcome.ok) {
+          return;
+        }
+
+        const shouldNotify = controller.handleTitleFailed(ctx, outcome.failure);
+        if (shouldNotify && ctx.hasUI) {
+          ctx.ui.notify(
+            `Auto-title failed: ${formatAutoTitleFailureSummary(outcome.failure)}. Open /title for details.`,
+            "warning",
+          );
+        }
+      })
+      .catch(() => {})
+      .finally(() => {
+        titleWorkInFlight = undefined;
+      });
+  });
+
+  pi.on("session_shutdown", async () => {
+    sessionEpoch += 1;
+    controller.handleSessionShutdown();
+    titleWorkInFlight = undefined;
+    resolvedModel = undefined;
+  });
+}
+
+async function handleTitleInvocation(
+  pi: ExtensionAPI,
+  state: TitleRunState,
+  ctx: ExtensionCommandContext,
+  model: Model<Api> | undefined,
+  invocation: RetitleCommandInvocation,
+): Promise<RetitleCommandOutcome> {
+  const retitleOpts = {
+    pi,
+    controller: state.controller,
+    ctx,
+    model,
+    isManual: true,
+    getSessionEpoch: state.getSessionEpoch,
+  };
+
+  const retitleCurrentSession = async (): Promise<RetitleCommandOutcome> => {
+    const result = await runRetitlePlan(retitleOpts);
+    if (result.ok) {
+      return "success";
+    }
+
+    state.controller.handleTitleFailed(ctx, result.failure);
+    return "failed";
+  };
+
+  if (invocation.kind === "open-pane") {
+    if (!ctx.hasUI) {
+      return retitleCurrentSession();
+    }
+
+    return showRetitleWizard(pi, state.controller, ctx, model, state.getSessionEpoch);
+  }
+
+  if (invocation.scope === "this") {
+    return runWithInFlightTracking(state, retitleCurrentSession);
+  }
+
+  if (ctx.hasUI && !invocation.force) {
+    return showRetitleWizard(pi, state.controller, ctx, model, state.getSessionEpoch, {
+      initialInvocation: {
+        scope: invocation.scope,
+        mode: invocation.mode ?? "backfill",
+      },
+    });
+  }
+
+  const scan = await buildRetitleScopeScan(ctx, invocation.scope);
+  const mode = invocation.mode ?? "backfill";
+  return runWithInFlightTracking(state, async () => {
+    const result = await runBulkRetitle(
+      pi,
+      state.controller,
+      ctx,
+      model,
+      scan,
+      mode,
+      state.getSessionEpoch,
+    );
+    notifyBulkRetitleResult(ctx, scan, mode, result);
+    return "success";
+  });
+}
+
+async function runWithInFlightTracking(
+  state: TitleRunState,
+  work: () => Promise<RetitleCommandOutcome>,
+): Promise<RetitleCommandOutcome> {
+  const outcomePromise = work().catch(() => "failed" as const);
+  state.setInFlight(outcomePromise.then(() => {}));
+
+  try {
+    return await outcomePromise;
+  } finally {
+    state.clearInFlight();
+  }
+}

package/extensions/session-handoff/extract.ts

@@ -0,0 +1,278 @@
+import {
+  type AssistantMessage,
+  complete,
+  type Message,
+  type TextContent,
+  type ThinkingContent,
+  type Tool,
+  type ToolCall,
+} from "@mariozechner/pi-ai";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import {
+  buildSessionContext,
+  convertToLlm,
+  serializeConversation,
+} from "@mariozechner/pi-coding-agent";
+import { type Static, Type } from "@sinclair/typebox";
+import { parseTypeBoxValue } from "../shared/typebox.js";
+
+const MAX_RELEVANT_FILES = 12;
+const MAX_OPEN_QUESTIONS = 8;
+
+const HANDOFF_SYSTEM_PROMPT = `You extract context for a deliberate session handoff.
+
+You must call create_handoff_context exactly once.
+
+Rules:
+- Extract only context that is relevant to the next task.
+- Keep the summary compact and concrete.
+- Prefer workspace-relative file paths when possible.
+- nextTask must be the concrete next action for the new session.
+- openQuestions should contain only unresolved items that materially affect the next task.
+- If there are no meaningful open questions, omit openQuestions entirely.
+- Do not write the final handoff prompt yourself.`;
+
+const HANDOFF_EXTRACTION_PARAMETERS = Type.Object({
+  summary: Type.String({
+    description: "Only the context relevant to the next task.",
+  }),
+  relevantFiles: Type.Array(Type.String(), {
+    description: "Relevant workspace-relative file paths when possible.",
+  }),
+  nextTask: Type.String({
+    description: "The concrete next task for the new session.",
+  }),
+  openQuestions: Type.Optional(
+    Type.Array(Type.String(), {
+      description: "Open questions that matter to the next task. Omit when there are none.",
+    }),
+  ),
+});
+
+const HANDOFF_EXTRACTION_TOOL: Tool<typeof HANDOFF_EXTRACTION_PARAMETERS> = {
+  name: "create_handoff_context",
+  description: "Extract the structured handoff context for the next session.",
+  parameters: HANDOFF_EXTRACTION_PARAMETERS,
+};
+
+type RequiredHandoffExtractionArgs = Static<typeof REQUIRED_HANDOFF_EXTRACTION_PARAMETERS>;
+
+const REQUIRED_HANDOFF_EXTRACTION_PARAMETERS = Type.Object({
+  summary: HANDOFF_EXTRACTION_PARAMETERS.properties.summary,
+  nextTask: HANDOFF_EXTRACTION_PARAMETERS.properties.nextTask,
+});
+
+export interface HandoffContext {
+  summary: string;
+  relevantFiles: string[];
+  nextTask: string;
+  openQuestions: string[];
+}
+
+export interface HandoffDraftResult {
+  draft: string;
+  context: HandoffContext;
+  sessionId: string;
+  sessionPath?: string | undefined;
+}
+
+export async function generateHandoffDraft(
+  ctx: ExtensionContext,
+  goal: string,
+  signal?: AbortSignal,
+): Promise<HandoffDraftResult | undefined> {
+  if (!ctx.model) {
+    throw new Error("No model is available for handoff.");
+  }
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+  if (!auth.ok || !auth.apiKey) {
+    throw new Error(`No API key is available for ${ctx.model.provider}/${ctx.model.id}.`);
+  }
+
+  const sessionContext = buildSessionContext(
+    ctx.sessionManager.getEntries(),
+    ctx.sessionManager.getLeafId(),
+  );
+  if (sessionContext.messages.length === 0) {
+    throw new Error("No conversation is available to hand off.");
+  }
+
+  const conversationText = serializeConversation(convertToLlm(sessionContext.messages));
+  const userMessage: Message = {
+    role: "user",
+    content: [
+      {
+        type: "text",
+        text: buildExtractionPrompt(conversationText, goal),
+      },
+    ],
+    timestamp: Date.now(),
+  };
+
+  const response = await complete(
+    ctx.model,
+    {
+      systemPrompt: HANDOFF_SYSTEM_PROMPT,
+      messages: [userMessage],
+      tools: [HANDOFF_EXTRACTION_TOOL],
+    },
+    signal
+      ? {
+          apiKey: auth.apiKey,
+          ...(auth.headers ? { headers: auth.headers } : {}),
+          signal,
+          toolChoice: "any",
+        }
+      : {
+          apiKey: auth.apiKey,
+          ...(auth.headers ? { headers: auth.headers } : {}),
+          toolChoice: "any",
+        },
+  );
+
+  if (response.stopReason === "aborted") {
+    return undefined;
+  }
+
+  if (response.stopReason === "error") {
+    throw new Error(response.errorMessage ?? "Handoff generation failed.");
+  }
+
+  const handoffContext = extractHandoffContext(response, goal);
+  if (!handoffContext) {
+    throw new Error("Handoff extraction did not return structured context.");
+  }
+
+  const sessionId = ctx.sessionManager.getSessionId();
+  const sessionPath = ctx.sessionManager.getSessionFile();
+
+  return {
+    draft: assembleHandoffDraft(sessionId, sessionPath, handoffContext, goal),
+    context: handoffContext,
+    sessionId,
+    sessionPath,
+  };
+}
+
+export function buildExtractionPrompt(conversationText: string, goal: string): string {
+  return [
+    "## Conversation",
+    conversationText,
+    "",
+    "## Goal",
+    goal,
+    "",
+    "Call create_handoff_context exactly once.",
+  ].join("\n");
+}
+
+export function assembleHandoffDraft(
+  sessionId: string,
+  sessionPath: string | undefined,
+  handoffContext: HandoffContext,
+  goal: string,
+): string {
+  const sections = [buildContinuityLine(sessionId, sessionPath)];
+  const nextTask = handoffContext.nextTask.trim() || goal.trim();
+
+  if (nextTask) {
+    sections.push(["## Task", nextTask].join("\n"));
+  }
+
+  if (handoffContext.relevantFiles.length > 0) {
+    sections.push(
+      [
+        "## Relevant Files",
+        ...handoffContext.relevantFiles.map((filePath) => `- ${filePath}`),
+      ].join("\n"),
+    );
+  }
+
+  if (handoffContext.summary) {
+    sections.push(["## Context", handoffContext.summary].join("\n"));
+  }
+
+  if (handoffContext.openQuestions.length > 0) {
+    sections.push(
+      [
+        "## Open Questions",
+        ...handoffContext.openQuestions.map((question) => `- ${question}`),
+      ].join("\n"),
+    );
+  }
+
+  return sections.join("\n\n").trim();
+}
+
+export function extractHandoffContext(
+  response: AssistantMessage,
+  goal: string,
+): HandoffContext | undefined {
+  const toolCall = response.content.find(isCreateHandoffContextToolCall);
+  if (!toolCall) {
+    return undefined;
+  }
+
+  let requiredArguments: RequiredHandoffExtractionArgs;
+  try {
+    requiredArguments = parseTypeBoxValue(
+      REQUIRED_HANDOFF_EXTRACTION_PARAMETERS,
+      toolCall.arguments,
+      "Invalid create_handoff_context arguments",
+    );
+  } catch {
+    return undefined;
+  }
+
+  const summary = normalizeText(requiredArguments.summary);
+  const relevantFiles = normalizeStringArray(toolCall.arguments.relevantFiles, MAX_RELEVANT_FILES);
+  const nextTask = normalizeText(requiredArguments.nextTask) || goal.trim();
+  const openQuestions = normalizeStringArray(toolCall.arguments.openQuestions, MAX_OPEN_QUESTIONS);
+
+  if (!summary || !nextTask) {
+    return undefined;
+  }
+
+  return {
+    summary,
+    relevantFiles,
+    nextTask,
+    openQuestions,
+  };
+}
+
+function buildContinuityLine(sessionId: string, _sessionPath: string | undefined): string {
+  return `Continuing work from session ${sessionId}. When you lack specific information you can use session_ask.`;
+}
+
+function normalizeStringArray(value: unknown, limit: number): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const uniqueValues = new Set<string>();
+  for (const item of value) {
+    const normalized = normalizeText(item);
+    if (!normalized) {
+      continue;
+    }
+
+    uniqueValues.add(normalized);
+    if (uniqueValues.size >= limit) {
+      break;
+    }
+  }
+
+  return [...uniqueValues];
+}
+
+function normalizeText(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function isCreateHandoffContextToolCall(
+  content: TextContent | ThinkingContent | ToolCall,
+): content is ToolCall {
+  return content.type === "toolCall" && content.name === "create_handoff_context";
+}

package/extensions/session-handoff/metadata.ts

@@ -0,0 +1,96 @@
+import { randomUUID } from "node:crypto";
+import type { CustomEntry, SessionEntry } from "@mariozechner/pi-coding-agent";
+import { type Static, Type } from "@sinclair/typebox";
+import { safeParseTypeBoxValue } from "../shared/typebox.js";
+
+export const HANDOFF_METADATA_CUSTOM_TYPE = "pi-sessions.handoff";
+export const PENDING_SEND_CONSUMED_CUSTOM_TYPE = "pi-sessions.pending-send-consumed";
+
+export const HANDOFF_SESSION_METADATA_SCHEMA = Type.Object({
+  origin: Type.Literal("handoff"),
+  goal: Type.String(),
+  nextTask: Type.String(),
+  initial_prompt: Type.String(),
+  initial_prompt_nonce: Type.String(),
+});
+
+export const PENDING_SEND_CONSUMED_ENTRY_SCHEMA = Type.Object({
+  nonce: Type.String(),
+});
+
+export type HandoffSessionMetadata = Static<typeof HANDOFF_SESSION_METADATA_SCHEMA>;
+export type PendingSendConsumedEntryData = Static<typeof PENDING_SEND_CONSUMED_ENTRY_SCHEMA>;
+
+export function createHandoffSessionMetadata(
+  goal: string,
+  nextTask: string,
+  initialPrompt: string,
+): HandoffSessionMetadata {
+  const normalizedGoal = goal.trim();
+  const normalizedNextTask = nextTask.trim() || normalizedGoal;
+  const normalizedInitialPrompt = initialPrompt.trim();
+
+  return {
+    origin: "handoff",
+    goal: normalizedGoal,
+    nextTask: normalizedNextTask,
+    initial_prompt: normalizedInitialPrompt,
+    initial_prompt_nonce: randomUUID(),
+  };
+}
+
+export function createPendingSendConsumedEntry(nonce: string): PendingSendConsumedEntryData {
+  return { nonce };
+}
+
+export function parsePendingSendConsumedEntry(
+  value: unknown,
+): PendingSendConsumedEntryData | undefined {
+  return safeParseTypeBoxValue(PENDING_SEND_CONSUMED_ENTRY_SCHEMA, value);
+}
+
+export function parseHandoffSessionMetadata(value: unknown): HandoffSessionMetadata | undefined {
+  return safeParseTypeBoxValue(HANDOFF_SESSION_METADATA_SCHEMA, value);
+}
+
+export function getPendingInitialPromptFromEntries(
+  entries: readonly SessionEntry[],
+): HandoffSessionMetadata | undefined {
+  const consumed = new Set<string>();
+  let pending: HandoffSessionMetadata | undefined;
+
+  for (const entry of entries) {
+    if (entry.type !== "custom") {
+      continue;
+    }
+
+    const customEntry = entry as CustomEntry;
+    if (customEntry.customType === PENDING_SEND_CONSUMED_CUSTOM_TYPE) {
+      const consumedEntry = parsePendingSendConsumedEntry(customEntry.data);
+      if (consumedEntry) {
+        consumed.add(consumedEntry.nonce);
+        if (pending?.initial_prompt_nonce === consumedEntry.nonce) {
+          pending = undefined;
+        }
+      }
+      continue;
+    }
+
+    if (customEntry.customType !== HANDOFF_METADATA_CUSTOM_TYPE) {
+      continue;
+    }
+
+    const metadata = parseHandoffSessionMetadata(customEntry.data);
+    if (!metadata) {
+      continue;
+    }
+
+    if (consumed.has(metadata.initial_prompt_nonce)) {
+      continue;
+    }
+
+    pending = metadata;
+  }
+
+  return pending;
+}