@oh-my-pi/pi-coding-agent 15.0.1 → 15.1.0

package/src/prompts/compaction/branch-summary.md

@@ -1,30 +0,0 @@
-You MUST create a structured summary of the conversation branch for context when returning.
-
-You MUST use EXACT format:
-
-## Goal
-
-[What user trying to accomplish in this branch?]
-
-## Constraints & Preferences
-- [Constraints, preferences, requirements mentioned]
-- [(none) if none mentioned]
-
-## Progress
-
-### Done
-- [x] [Completed tasks/changes]
-
-### In Progress
-- [ ] [Work started but not finished]
-
-### Blocked
-- [Issues preventing progress]
-
-## Key Decisions
-- **[Decision]**: [Brief rationale]
-
-## Next Steps
-1. [What should happen next to continue]
-
-Sections MUST be kept concise. You MUST preserve exact file paths, function names, error messages.

package/src/prompts/compaction/compaction-short-summary.md

@@ -1,9 +0,0 @@
-You MUST summarize what was done in this conversation, written like a pull request description.
-
-Rules:
-- MUST be 2-3 sentences max
-- MUST describe the changes made, not the process
-- NEVER mention running tests, builds, or other validation steps
-- NEVER explain what the user asked for
-- MUST write in first person (I added…, I fixed…)
-- NEVER ask questions

package/src/prompts/compaction/compaction-summary-context.md

@@ -1,5 +0,0 @@
-Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. You MUST use this to build on the work that has already been done and NEVER duplicate work. Here is the summary produced by the other language model; you MUST use the information in this summary to assist with your own analysis:
-
-<summary>
-{{summary}}
-</summary>

package/src/prompts/compaction/compaction-summary.md

@@ -1,38 +0,0 @@
-You MUST summarize the conversation above into a structured context checkpoint handoff summary for another LLM to resume task.
-
-IMPORTANT: If conversation ends with unanswered question to user or imperative/request awaiting user response (e.g., "Please run command and paste output"), you MUST preserve that exact question/request.
-
-You MUST use this format (sections can be omitted if not applicable):
-
-## Goal
-[User goals; list multiple if session covers different tasks.]
-
-## Constraints & Preferences
-- [Constraints or requirements mentioned]
-
-## Progress
-
-### Done
-- [x] [Completed tasks/changes]
-
-### In Progress
-- [ ] [Current work]
-
-### Blocked
-- [Issues preventing progress]
-
-## Key Decisions
-- **[Decision]**: [Brief rationale]
-
-## Next Steps
-1. [Ordered list of next actions]
-
-## Critical Context
-- [Important data, pending questions, references]
-
-## Additional Notes
-[Anything else important not covered above]
-
-You MUST output only the structured summary; you NEVER include extra text.
-
-Sections MUST be kept concise. You MUST preserve exact file paths, function names, error messages, and relevant tool outputs or command results. You MUST include repository state changes (branch, uncommitted changes) if mentioned.

package/src/prompts/compaction/compaction-turn-prefix.md

@@ -1,17 +0,0 @@
-This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.
-
-You MUST summarize the prefix to provide context for the retained suffix:
-
-## Original Request
-
-[What did the user ask for in this turn?]
-
-## Early Progress
-- [Key decisions and work done in the prefix]
-
-## Context for Suffix
-- [Information needed to understand the retained recent work]
-
-You MUST output only the structured summary. You NEVER include extra text.
-
-You MUST be concise. You MUST preserve exact file paths, function names, error messages, and relevant tool outputs or command results if they appear. You MUST focus on what's needed to understand the kept suffix.

package/src/prompts/compaction/compaction-update-summary.md

@@ -1,45 +0,0 @@
-You MUST incorporate new messages above into the existing handoff summary in <previous-summary> tags, used by another LLM to resume task.
-RULES:
-- MUST preserve all information from previous summary
-- MUST add new progress, decisions, and context from new messages
-- MUST update Progress: move items from "In Progress" to "Done" when completed
-- MUST update "Next Steps" based on what was accomplished
-- MUST preserve exact file paths, function names, and error messages
-- You MAY remove anything no longer relevant
-
-IMPORTANT: If new messages end with unanswered question or request to user, you MUST add it to Critical Context (replacing any previous pending question if answered).
-
-You MUST use this format (omit sections if not applicable):
-
-## Goal
-[Preserve existing goals; add new ones if task expanded]
-
-## Constraints & Preferences
-- [Preserve existing; add new ones discovered]
-
-## Progress
-
-### Done
-- [x] [Include previously done and newly completed items]
-
-### In Progress
-- [ ] [Current work—update based on progress]
-
-### Blocked
-- [Current blockers—remove if resolved]
-
-## Key Decisions
-- **[Decision]**: [Brief rationale] (preserve all previous, add new)
-
-## Next Steps
-1. [Update based on current state]
-
-## Critical Context
-- [Preserve important context; add new if needed]
-
-## Additional Notes
-[Other important info not fitting above]
-
-You MUST output only the structured summary; you NEVER include extra text.
-
-Sections MUST be kept concise. You MUST preserve relevant tool outputs/command results. You MUST include repository state changes (branch, uncommitted changes) if mentioned.

package/src/prompts/system/auto-handoff-threshold-focus.md

@@ -1 +0,0 @@
-Threshold-triggered maintenance: preserve critical implementation state and immediate next actions.

package/src/prompts/system/file-operations.md

@@ -1,10 +0,0 @@
-{{#if readFiles.length}}
-{{#xml "read-files"}}
-{{join readFiles "\n"}}
-{{/xml}}
-{{/if}}
-{{#if modifiedFiles.length}}
-{{#xml "modified-files"}}
-{{join modifiedFiles "\n"}}
-{{/xml}}
-{{/if}}

package/src/prompts/system/handoff-document.md

@@ -1,49 +0,0 @@
-<critical>
-Write a handoff document for another instance of yourself.
-The handoff MUST be sufficient for seamless continuation without access to this conversation.
-Output ONLY the handoff document. No preamble, no commentary, no wrapper text.
-</critical>
-
-<instruction>
-Capture exact technical state, not abstractions.
-- File paths, symbol names, commands run
-- Test results, observed failures
-- Decisions made
-- Partial work affecting the next step
-</instruction>
-
-<output>
-Use exactly this structure:
-
-## Goal
-[What the user is trying to accomplish]
-
-## Constraints & Preferences
-- [Any constraints, preferences, or requirements mentioned]
-
-## Progress
-### Done
-- [x] [Completed tasks with specifics]
-
-### In Progress
-- [ ] [Current work if any]
-
-### Pending
-- [ ] [Tasks mentioned but not started]
-
-## Key Decisions
-- **[Decision]**: [Rationale]
-
-## Critical Context
-- Code snippets, file paths, function/type names, error messages, data essential to continue
-- Repository state if relevant
-
-## Next Steps
-1. [What should happen next]
-</output>
-
-{{#if additionalFocus}}
-<instruction>
-Additional focus: {{additionalFocus}}
-</instruction>
-{{/if}}

package/src/prompts/system/summarization-system.md

@@ -1,3 +0,0 @@
-Summarize conversations between users and AI coding assistants. Produce structured summaries in the exact specified format.
-
-Do NOT continue the conversation. Do NOT respond to questions in the conversation. Output ONLY the structured summary.

package/src/session/compaction/branch-summarization.ts

@@ -1,324 +0,0 @@
-/**
- * Branch summarization for tree navigation.
- *
- * When navigating to a different point in the session tree, this generates
- * a summary of the branch being left so context isn't lost.
- */
-import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import type { Model } from "@oh-my-pi/pi-ai";
-import { completeSimple } from "@oh-my-pi/pi-ai";
-import { prompt } from "@oh-my-pi/pi-utils";
-import branchSummaryPrompt from "../../prompts/compaction/branch-summary.md" with { type: "text" };
-import branchSummaryPreamble from "../../prompts/compaction/branch-summary-preamble.md" with { type: "text" };
-import {
-	convertToLlm,
-	createBranchSummaryMessage,
-	createCompactionSummaryMessage,
-	createCustomMessage,
-} from "../../session/messages";
-import type { ReadonlySessionManager, SessionEntry } from "../../session/session-manager";
-import { estimateTokens } from "./compaction";
-import {
-	computeFileLists,
-	createFileOps,
-	extractFileOpsFromMessage,
-	type FileOperations,
-	SUMMARIZATION_SYSTEM_PROMPT,
-	serializeConversation,
-	upsertFileOperations,
-} from "./utils";
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface BranchSummaryResult {
-	summary?: string;
-	readFiles?: string[];
-	modifiedFiles?: string[];
-	aborted?: boolean;
-	error?: string;
-}
-
-/** Details stored in BranchSummaryEntry.details for file tracking */
-export interface BranchSummaryDetails {
-	readFiles: string[];
-	modifiedFiles: string[];
-}
-
-export type { FileOperations } from "./utils";
-
-export interface BranchPreparation {
-	/** Messages extracted for summarization, in chronological order */
-	messages: AgentMessage[];
-	/** File operations extracted from tool calls */
-	fileOps: FileOperations;
-	/** Total estimated tokens in messages */
-	totalTokens: number;
-}
-
-export interface CollectEntriesResult {
-	/** Entries to summarize, in chronological order */
-	entries: SessionEntry[];
-	/** Common ancestor between old and new position, if any */
-	commonAncestorId: string | null;
-}
-
-export interface GenerateBranchSummaryOptions {
-	/** Model to use for summarization */
-	model: Model;
-	/** API key for the model */
-	apiKey: string;
-	/** Abort signal for cancellation */
-	signal: AbortSignal;
-	/** Optional custom instructions for summarization */
-	customInstructions?: string;
-	/** Tokens reserved for prompt + LLM response (default 16384) */
-	reserveTokens?: number;
-	/** Optional metadata forwarded to the underlying API request (e.g. user_id for session attribution). */
-	metadata?: Record<string, unknown>;
-}
-
-// ============================================================================
-// Entry Collection
-// ============================================================================
-
-/**
- * Collect entries that should be summarized when navigating from one position to another.
- *
- * Walks from oldLeafId back to the common ancestor with targetId, collecting entries
- * along the way. Does NOT stop at compaction boundaries - those are included and their
- * summaries become context.
- *
- * @param session - Session manager (read-only access)
- * @param oldLeafId - Current position (where we're navigating from)
- * @param targetId - Target position (where we're navigating to)
- * @returns Entries to summarize and the common ancestor
- */
-export function collectEntriesForBranchSummary(
-	session: ReadonlySessionManager,
-	oldLeafId: string | null,
-	targetId: string,
-): CollectEntriesResult {
-	// If no old position, nothing to summarize
-	if (!oldLeafId) {
-		return { entries: [], commonAncestorId: null };
-	}
-
-	// Find common ancestor (deepest node that's on both paths)
-	const oldPath = new Set(session.getBranch(oldLeafId).map(e => e.id));
-	const targetPath = session.getBranch(targetId);
-
-	// targetPath is root-first, so iterate backwards to find deepest common ancestor
-	let commonAncestorId: string | null = null;
-	for (let i = targetPath.length - 1; i >= 0; i--) {
-		if (oldPath.has(targetPath[i].id)) {
-			commonAncestorId = targetPath[i].id;
-			break;
-		}
-	}
-
-	// Collect entries from old leaf back to common ancestor
-	const entries: SessionEntry[] = [];
-	let current: string | null = oldLeafId;
-
-	while (current && current !== commonAncestorId) {
-		const entry = session.getEntry(current);
-		if (!entry) break;
-		entries.push(entry);
-		current = entry.parentId;
-	}
-
-	// Reverse to get chronological order
-	entries.reverse();
-
-	return { entries, commonAncestorId };
-}
-
-// ============================================================================
-// Entry to Message Conversion
-// ============================================================================
-
-/**
- * Extract AgentMessage from a session entry.
- * Similar to getMessageFromEntry in compaction.ts but also handles compaction entries.
- */
-function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
-	switch (entry.type) {
-		case "message":
-			// Skip tool results - context is in assistant's tool call
-			if (entry.message.role === "toolResult") return undefined;
-			return entry.message;
-
-		case "custom_message":
-			return createCustomMessage(
-				entry.customType,
-				entry.content,
-				entry.display,
-				entry.details,
-				entry.timestamp,
-				entry.attribution,
-			);
-
-		case "branch_summary":
-			return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);
-
-		case "compaction":
-			return createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp, entry.shortSummary);
-
-		// These don't contribute to conversation content
-		case "thinking_level_change":
-		case "model_change":
-		case "custom":
-		case "label":
-			return undefined;
-	}
-}
-
-/**
- * Prepare entries for summarization with token budget.
- *
- * Walks entries from NEWEST to OLDEST, adding messages until we hit the token budget.
- * This ensures we keep the most recent context when the branch is too long.
- *
- * Also collects file operations from:
- * - Tool calls in assistant messages
- * - Existing branch_summary entries' details (for cumulative tracking)
- *
- * @param entries - Entries in chronological order
- * @param tokenBudget - Maximum tokens to include (0 = no limit)
- */
-export function prepareBranchEntries(entries: SessionEntry[], tokenBudget: number = 0): BranchPreparation {
-	const messages: AgentMessage[] = [];
-	const fileOps = createFileOps();
-	let totalTokens = 0;
-
-	// First pass: collect file ops from ALL entries (even if they don't fit in token budget)
-	// This ensures we capture cumulative file tracking from nested branch summaries
-	// Only extract from pi-generated summaries (fromExtension !== true), not extension-generated ones
-	for (const entry of entries) {
-		if (entry.type === "branch_summary" && !entry.fromExtension && entry.details) {
-			const details = entry.details as BranchSummaryDetails;
-			if (Array.isArray(details.readFiles)) {
-				for (const f of details.readFiles) fileOps.read.add(f);
-			}
-			if (Array.isArray(details.modifiedFiles)) {
-				// Modified files go into both edited and written for proper deduplication
-				for (const f of details.modifiedFiles) {
-					fileOps.edited.add(f);
-				}
-			}
-		}
-	}
-
-	// Second pass: walk from newest to oldest, adding messages until token budget
-	for (let i = entries.length - 1; i >= 0; i--) {
-		const entry = entries[i];
-		const message = getMessageFromEntry(entry);
-		if (!message) continue;
-
-		// Extract file ops from assistant messages (tool calls)
-		extractFileOpsFromMessage(message, fileOps);
-
-		const tokens = estimateTokens(message);
-
-		// Check budget before adding
-		if (tokenBudget > 0 && totalTokens + tokens > tokenBudget) {
-			// If this is a summary entry, try to fit it anyway as it's important context
-			if (entry.type === "compaction" || entry.type === "branch_summary") {
-				if (totalTokens < tokenBudget * 0.9) {
-					messages.unshift(message);
-					totalTokens += tokens;
-				}
-			}
-			// Stop - we've hit the budget
-			break;
-		}
-
-		messages.unshift(message);
-		totalTokens += tokens;
-	}
-
-	return { messages, fileOps, totalTokens };
-}
-
-// ============================================================================
-// Summary Generation
-// ============================================================================
-
-const BRANCH_SUMMARY_PREAMBLE = prompt.render(branchSummaryPreamble);
-
-const BRANCH_SUMMARY_PROMPT = prompt.render(branchSummaryPrompt);
-
-/**
- * Generate a summary of abandoned branch entries.
- *
- * @param entries - Session entries to summarize (chronological order)
- * @param options - Generation options
- */
-export async function generateBranchSummary(
-	entries: SessionEntry[],
-	options: GenerateBranchSummaryOptions,
-): Promise<BranchSummaryResult> {
-	const { model, apiKey, signal, customInstructions, reserveTokens = 16384, metadata } = options;
-
-	// Token budget = context window minus reserved space for prompt + response
-	const contextWindow = model.contextWindow || 128000;
-	const tokenBudget = contextWindow - reserveTokens;
-
-	const { messages, fileOps } = prepareBranchEntries(entries, tokenBudget);
-
-	if (messages.length === 0) {
-		return { summary: "No content to summarize" };
-	}
-
-	// Transform to LLM-compatible messages, then serialize to text
-	// Serialization prevents the model from treating it as a conversation to continue
-	const llmMessages = convertToLlm(messages);
-	const conversationText = serializeConversation(llmMessages);
-
-	// Build prompt
-	const instructions = customInstructions || BRANCH_SUMMARY_PROMPT;
-	const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${instructions}`;
-
-	const summarizationMessages = [
-		{
-			role: "user" as const,
-			content: [{ type: "text" as const, text: promptText }],
-			timestamp: Date.now(),
-		},
-	];
-
-	// Call LLM for summarization
-	const response = await completeSimple(
-		model,
-		{ systemPrompt: [SUMMARIZATION_SYSTEM_PROMPT], messages: summarizationMessages },
-		{ apiKey, signal, maxTokens: 2048, metadata },
-	);
-
-	// Check if aborted or errored
-	if (response.stopReason === "aborted") {
-		return { aborted: true };
-	}
-	if (response.stopReason === "error") {
-		return { error: response.errorMessage || "Summarization failed" };
-	}
-
-	let summary = response.content
-		.filter((c): c is { type: "text"; text: string } => c.type === "text")
-		.map(c => c.text)
-		.join("\n");
-
-	// Prepend preamble to provide context about the branch summary
-	summary = BRANCH_SUMMARY_PREAMBLE + summary;
-
-	// Compute file lists and append to summary
-	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
-	summary = upsertFileOperations(summary, readFiles, modifiedFiles);
-
-	return {
-		summary: summary || "No summary generated",
-		readFiles,
-		modifiedFiles,
-	};
-}