{"version":3,"file":"branch-summarization.d.ts","sourceRoot":"","sources":["../../../src/harness/compaction/branch-summarization.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype Api,\n\tcontentText,\n\ttype Model,\n\ttype Models,\n\ttype RetryCallbacks,\n\ttype RetryPolicy,\n\ttype Usage,\n} from \"@earendil-works/pi-ai\";\n\nimport type { AgentMessage } from \"../../types.ts\";\nimport type { Context } from \"../context.ts\";\nimport { convertToLlm, createBranchSummaryMessage, createCompactionSummaryMessage } from \"../messages.ts\";\nimport type { Branch, Entry, Session } from \"../session/index.ts\";\nimport { BranchSummaryError, err, ok, type Result } from \"../types.ts\";\nimport {\n\tcompleteSimpleWithRetries,\n\tcreateSummaryRequestOptions,\n\testimateTokens,\n\tSUMMARIZATION_SYSTEM_PROMPT,\n\ttype SummaryRequest,\n} from \"./compaction.ts\";\nimport {\n\tcomputeFileLists,\n\tcreateFileOps,\n\textractFileOpsFromMessage,\n\ttype FileOperations,\n\tformatFileOperations,\n\tserializeConversation,\n} from \"./utils.ts\";\n\n/** Generated branch summary data ready to be persisted as a branch-summary entry. */\nexport interface BranchSummaryResult {\n\tsummary: string;\n\tusage?: Usage;\n\treadFiles: string[];\n\tmodifiedFiles: string[];\n}\n\n/** File-operation details stored on generated branch summary entries. */\nexport interface BranchSummaryDetails {\n\t/** Files read while exploring the summarized branch. */\n\treadFiles: string[];\n\t/** Files modified while exploring the summarized branch. */\n\tmodifiedFiles: string[];\n}\n\nexport type { FileOperations } from \"./utils.ts\";\n\n/** Prepared branch content for summarization. */\nexport interface BranchPreparation {\n\t/** Messages selected for the branch summary. */\n\tmessages: AgentMessage[];\n\t/** File operations extracted from the branch. */\n\tfileOps: FileOperations;\n\t/** Estimated token count for selected messages. */\n\ttotalTokens: number;\n}\n\n/** Entries selected for branch summarization. */\nexport interface CollectEntriesResult {\n\t/** Entries to summarize in chronological order. */\n\tentries: Entry[];\n\t/** Deepest common ancestor between the previous tip and target entry. */\n\tcommonAncestorId: string | null;\n}\n\n/** Options for generating a branch summary. */\nexport interface GenerateBranchSummaryOptions {\n\t/** Provider collection the summarization request goes through; owns auth resolution. */\n\tmodels: Models;\n\t/** Model used for summarization. */\n\tmodel: Model<Api>;\n\t/** Optional instructions appended to or replacing the default prompt. */\n\tcustomInstructions?: string;\n\t/** Replace the default prompt with custom instructions instead of appending them. */\n\treplaceInstructions?: boolean;\n\t/** Tokens reserved for prompt and model output. Defaults to 16384. */\n\treserveTokens?: number;\n\t/** Optional retry policy for transient summarization errors. */\n\tretry?: RetryPolicy;\n\t/** Optional callbacks for retry reporting. */\n\tcallbacks?: RetryCallbacks;\n}\n\n/** Collect entries that should be summarized before navigating to a different session tree entry. */\nexport async function collectEntriesForBranchSummary(\n\tbranch: Pick<Branch, \"findEntries\">,\n\tsession: Pick<Session, \"getEntry\">,\n\toldTipId: string | null,\n\ttargetId: string,\n\tcontext: Context,\n): Promise<CollectEntriesResult> {\n\tif (!oldTipId) {\n\t\treturn { entries: [], commonAncestorId: null };\n\t}\n\tconst oldPath = new Set((await branch.findEntries({ start: oldTipId }, context)).map((entry) => entry.id));\n\tconst targetPath = await branch.findEntries({ start: targetId }, context);\n\tlet commonAncestorId: string | null = null;\n\tfor (const entry of targetPath) {\n\t\tif (oldPath.has(entry.id)) {\n\t\t\tcommonAncestorId = entry.id;\n\t\t\tbreak;\n\t\t}\n\t}\n\tconst entries: Entry[] = [];\n\tlet current: string | null = oldTipId;\n\n\twhile (current && current !== commonAncestorId) {\n\t\tconst entry = await session.getEntry(current, context);\n\t\tif (!entry) throw new Error(`Corrupt session: entry ${current} not found`);\n\t\tentries.push(entry);\n\t\tcurrent = entry.parentId;\n\t}\n\tentries.reverse();\n\n\treturn { entries, commonAncestorId };\n}\nfunction getMessageFromEntry(entry: Entry): AgentMessage | undefined {\n\tswitch (entry.type) {\n\t\tcase \"message\":\n\t\t\tif (entry.message.role === \"toolResult\") return undefined;\n\t\t\treturn entry.message;\n\n\t\tcase \"branch_summary\":\n\t\t\treturn createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);\n\n\t\tcase \"compaction\":\n\t\t\treturn createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp);\n\t\tcase \"custom\":\n\t\t\treturn undefined;\n\t}\n}\n\n/** Prepare branch entries for summarization within an optional token budget. */\nexport function prepareBranchEntries(entries: Entry[], tokenBudget: number = 0): BranchPreparation {\n\tconst messages: AgentMessage[] = [];\n\tconst fileOps = createFileOps();\n\tlet totalTokens = 0;\n\tfor (const entry of entries) {\n\t\tif (\n\t\t\tentry.type !== \"branch_summary\" ||\n\t\t\ttypeof entry.details !== \"object\" ||\n\t\t\tentry.details === null ||\n\t\t\tArray.isArray(entry.details)\n\t\t) {\n\t\t\tcontinue;\n\t\t}\n\t\tif (Array.isArray(entry.details.readFiles)) {\n\t\t\tfor (const path of entry.details.readFiles) {\n\t\t\t\tif (typeof path === \"string\") fileOps.read.add(path);\n\t\t\t}\n\t\t}\n\t\tif (Array.isArray(entry.details.modifiedFiles)) {\n\t\t\tfor (const path of entry.details.modifiedFiles) {\n\t\t\t\tif (typeof path === \"string\") fileOps.edited.add(path);\n\t\t\t}\n\t\t}\n\t}\n\tfor (let i = entries.length - 1; i >= 0; i--) {\n\t\tconst entry = entries[i];\n\t\tconst message = getMessageFromEntry(entry);\n\t\tif (!message) continue;\n\t\textractFileOpsFromMessage(message, fileOps);\n\n\t\tconst tokens = estimateTokens(message);\n\t\tif (tokenBudget > 0 && totalTokens + tokens > tokenBudget) {\n\t\t\tif (entry.type === \"compaction\" || entry.type === \"branch_summary\") {\n\t\t\t\tif (totalTokens < tokenBudget * 0.9) {\n\t\t\t\t\tmessages.unshift(message);\n\t\t\t\t\ttotalTokens += tokens;\n\t\t\t\t}\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\n\t\tmessages.unshift(message);\n\t\ttotalTokens += tokens;\n\t}\n\n\treturn { messages, fileOps, totalTokens };\n}\n\nconst BRANCH_SUMMARY_PREAMBLE = `The user explored a different conversation branch before returning here.\nSummary of that exploration:\n\n`;\n\nconst BRANCH_SUMMARY_PROMPT = `Create a structured summary of this conversation branch for context when returning later.\n\nUse this EXACT format:\n\n## Goal\n[What was the user trying to accomplish in this branch?]\n\n## Constraints & Preferences\n- [Any constraints, preferences, or requirements mentioned]\n- [Or \"(none)\" if none were mentioned]\n\n## Progress\n### Done\n- [x] [Completed tasks/changes]\n\n### In Progress\n- [ ] [Work that was started but not finished]\n\n### Blocked\n- [Issues preventing progress, if any]\n\n## Key Decisions\n- **[Decision]**: [Brief rationale]\n\n## Next Steps\n1. [What should happen next to continue this work]\n\nKeep each section concise. Preserve exact file paths, function names, and error messages.`;\n\n/** Generate a summary for abandoned branch entries. */\nexport function generateBranchSummary(\n\tentries: Entry[],\n\toptions: GenerateBranchSummaryOptions,\n\tcontext: Context,\n): Promise<Result<BranchSummaryResult, BranchSummaryError>> {\n\tconst { models, model, customInstructions, replaceInstructions, reserveTokens = 16384, retry, callbacks } = options;\n\tconst contextWindow = model.contextWindow || 128000;\n\tconst preparation = prepareBranchEntries(entries, contextWindow - reserveTokens);\n\treturn generateBranchSummaryWithRequest(\n\t\tpreparation,\n\t\t{ customInstructions, replaceInstructions },\n\t\t(aiContext, requestOptions, requestContext) =>\n\t\t\tcompleteSimpleWithRetries(models, model, aiContext, requestOptions, retry, callbacks, requestContext),\n\t\tcontext,\n\t);\n}\n\nexport interface PreparedBranchSummaryOptions {\n\tcustomInstructions?: string;\n\treplaceInstructions?: boolean;\n}\n\n/** Generate a prepared branch summary through a caller-owned one-request boundary. */\nexport async function generateBranchSummaryWithRequest(\n\tpreparation: BranchPreparation,\n\toptions: PreparedBranchSummaryOptions,\n\trequest: SummaryRequest,\n\tcontext: Context,\n): Promise<Result<BranchSummaryResult, BranchSummaryError>> {\n\tconst { customInstructions, replaceInstructions } = options;\n\tconst { messages, fileOps } = preparation;\n\tif (messages.length === 0) {\n\t\treturn ok({ summary: \"No content to summarize\", readFiles: [], modifiedFiles: [] });\n\t}\n\tconst llmMessages = convertToLlm(messages);\n\tconst conversationText = serializeConversation(llmMessages);\n\tlet instructions: string;\n\tif (replaceInstructions && customInstructions) {\n\t\tinstructions = customInstructions;\n\t} else if (customInstructions) {\n\t\tinstructions = `${BRANCH_SUMMARY_PROMPT}\\n\\nAdditional focus: ${customInstructions}`;\n\t} else {\n\t\tinstructions = BRANCH_SUMMARY_PROMPT;\n\t}\n\tconst promptText = `<conversation>\\n${conversationText}\\n</conversation>\\n\\n${instructions}`;\n\n\tconst summarizationMessages = [\n\t\t{\n\t\t\trole: \"user\" as const,\n\t\t\tcontent: [{ type: \"text\" as const, text: promptText }],\n\t\t\ttimestamp: Date.now(),\n\t\t},\n\t];\n\tconst response = await request(\n\t\t{ systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages },\n\t\tcreateSummaryRequestOptions({ maxTokens: 2048 }, context),\n\t\tcontext,\n\t);\n\tif (response.stopReason === \"aborted\") {\n\t\treturn err(new BranchSummaryError(\"aborted\", response.errorMessage || \"Branch summary aborted\"));\n\t}\n\tif (response.stopReason === \"error\") {\n\t\treturn err(\n\t\t\tnew BranchSummaryError(\n\t\t\t\t\"summarization_failed\",\n\t\t\t\t`Branch summary failed: ${response.errorMessage || \"Unknown error\"}`,\n\t\t\t),\n\t\t);\n\t}\n\n\tlet summary = contentText(response.content);\n\tsummary = BRANCH_SUMMARY_PREAMBLE + summary;\n\tconst { readFiles, modifiedFiles } = computeFileLists(fileOps);\n\tsummary += formatFileOperations(readFiles, modifiedFiles);\n\n\treturn ok({\n\t\tsummary: summary || \"No summary generated\",\n\t\tusage: response.usage,\n\t\treadFiles,\n\t\tmodifiedFiles,\n\t});\n}\n"]}