psadk 1.4.7 → 1.5.0

package/build/module/lib/agent-core/src/harness/compaction/branch-summarization.d.ts

@@ -0,0 +1,52 @@
+import type { Model } from '@earendil-works/pi-ai';
+import type { AgentMessage } from '../../types.ts';
+import type { BranchSummaryResult, Session, SessionTreeEntry } from '../types.ts';
+import { BranchSummaryError, type Result } from '../types.ts';
+import { type FileOperations } from './utils.ts';
+/** File-operation details stored on generated branch summary entries. */
+export interface BranchSummaryDetails {
+    /** Files read while exploring the summarized branch. */
+    readFiles: string[];
+    /** Files modified while exploring the summarized branch. */
+    modifiedFiles: string[];
+}
+export type { FileOperations } from './utils.ts';
+/** Prepared branch content for summarization. */
+export interface BranchPreparation {
+    /** Messages selected for the branch summary. */
+    messages: AgentMessage[];
+    /** File operations extracted from the branch. */
+    fileOps: FileOperations;
+    /** Estimated token count for selected messages. */
+    totalTokens: number;
+}
+/** Entries selected for branch summarization. */
+export interface CollectEntriesResult {
+    /** Entries to summarize in chronological order. */
+    entries: SessionTreeEntry[];
+    /** Deepest common ancestor between the previous leaf and target entry. */
+    commonAncestorId: string | null;
+}
+/** Options for generating a branch summary. */
+export interface GenerateBranchSummaryOptions {
+    /** Model used for summarization. */
+    model: Model<any>;
+    /** API key forwarded to the provider. */
+    apiKey: string;
+    /** Optional request headers forwarded to the provider. */
+    headers?: Record<string, string>;
+    /** Abort signal for the summarization request. */
+    signal: AbortSignal;
+    /** Optional instructions appended to or replacing the default prompt. */
+    customInstructions?: string;
+    /** Replace the default prompt with custom instructions instead of appending them. */
+    replaceInstructions?: boolean;
+    /** Tokens reserved for prompt and model output. Defaults to 16384. */
+    reserveTokens?: number;
+}
+/** Collect entries that should be summarized before navigating to a different session tree entry. */
+export declare function collectEntriesForBranchSummary(session: Session, oldLeafId: string | null, targetId: string): Promise<CollectEntriesResult>;
+/** Prepare branch entries for summarization within an optional token budget. */
+export declare function prepareBranchEntries(entries: SessionTreeEntry[], tokenBudget?: number): BranchPreparation;
+/** Generate a summary for abandoned branch entries. */
+export declare function generateBranchSummary(entries: SessionTreeEntry[], options: GenerateBranchSummaryOptions): Promise<Result<BranchSummaryResult, BranchSummaryError>>;

package/build/module/lib/agent-core/src/harness/compaction/branch-summarization.js

@@ -0,0 +1,182 @@
+import { completeSimple } from '@earendil-works/pi-ai';
+import { convertToLlm, createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "../messages.js";
+import { BranchSummaryError, err, ok, SessionError, } from "../types.js";
+import { estimateTokens, SUMMARIZATION_SYSTEM_PROMPT } from "./compaction.js";
+import { computeFileLists, createFileOps, extractFileOpsFromMessage, formatFileOperations, serializeConversation, } from "./utils.js";
+/** Collect entries that should be summarized before navigating to a different session tree entry. */
+export async function collectEntriesForBranchSummary(session, oldLeafId, targetId) {
+    if (!oldLeafId) {
+        return { entries: [], commonAncestorId: null };
+    }
+    const oldPath = new Set((await session.getBranch(oldLeafId)).map((e) => e.id));
+    const targetPath = await session.getBranch(targetId);
+    let commonAncestorId = null;
+    for (let i = targetPath.length - 1; i >= 0; i--) {
+        if (oldPath.has(targetPath[i].id)) {
+            commonAncestorId = targetPath[i].id;
+            break;
+        }
+    }
+    const entries = [];
+    let current = oldLeafId;
+    while (current && current !== commonAncestorId) {
+        const entry = await session.getEntry(current);
+        if (!entry)
+            throw new SessionError('invalid_session', `Entry ${current} not found`);
+        entries.push(entry);
+        current = entry.parentId;
+    }
+    entries.reverse();
+    return { entries, commonAncestorId };
+}
+function getMessageFromEntry(entry) {
+    switch (entry.type) {
+        case 'message':
+            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);
+        case 'branch_summary':
+            return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);
+        case 'compaction':
+            return createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp);
+        case 'thinking_level_change':
+        case 'model_change':
+        case 'active_tools_change':
+        case 'custom':
+        case 'label':
+        case 'session_info':
+        case 'leaf':
+            return undefined;
+    }
+}
+/** Prepare branch entries for summarization within an optional token budget. */
+export function prepareBranchEntries(entries, tokenBudget = 0) {
+    const messages = [];
+    const fileOps = createFileOps();
+    let totalTokens = 0;
+    for (const entry of entries) {
+        if (entry.type === 'branch_summary' && !entry.fromHook && entry.details) {
+            const details = entry.details;
+            if (Array.isArray(details.readFiles)) {
+                for (const f of details.readFiles)
+                    fileOps.read.add(f);
+            }
+            if (Array.isArray(details.modifiedFiles)) {
+                for (const f of details.modifiedFiles) {
+                    fileOps.edited.add(f);
+                }
+            }
+        }
+    }
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        const message = getMessageFromEntry(entry);
+        if (!message)
+            continue;
+        extractFileOpsFromMessage(message, fileOps);
+        const tokens = estimateTokens(message);
+        if (tokenBudget > 0 && totalTokens + tokens > tokenBudget) {
+            if (entry.type === 'compaction' || entry.type === 'branch_summary') {
+                if (totalTokens < tokenBudget * 0.9) {
+                    messages.unshift(message);
+                    totalTokens += tokens;
+                }
+            }
+            break;
+        }
+        messages.unshift(message);
+        totalTokens += tokens;
+    }
+    return { messages, fileOps, totalTokens };
+}
+const BRANCH_SUMMARY_PREAMBLE = `The user explored a different conversation branch before returning here.
+Summary of that exploration:
+
+`;
+const BRANCH_SUMMARY_PROMPT = `Create a structured summary of this conversation branch for context when returning later.
+
+Use this EXACT format:
+
+## Goal
+[What was the user trying to accomplish in this branch?]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned]
+- [Or "(none)" if none were mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes]
+
+### In Progress
+- [ ] [Work that was started but not finished]
+
+### Blocked
+- [Issues preventing progress, if any]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+
+## Next Steps
+1. [What should happen next to continue this work]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`;
+/** Generate a summary for abandoned branch entries. */
+export async function generateBranchSummary(entries, options) {
+    const { model, apiKey, headers, signal, customInstructions, replaceInstructions, reserveTokens = 16384, } = options;
+    const contextWindow = model.contextWindow || 128000;
+    const tokenBudget = contextWindow - reserveTokens;
+    const { messages, fileOps } = prepareBranchEntries(entries, tokenBudget);
+    if (messages.length === 0) {
+        return ok({
+            summary: 'No content to summarize',
+            readFiles: [],
+            modifiedFiles: [],
+        });
+    }
+    const llmMessages = convertToLlm(messages);
+    const conversationText = serializeConversation(llmMessages);
+    let instructions;
+    if (replaceInstructions && customInstructions) {
+        instructions = customInstructions;
+    }
+    else if (customInstructions) {
+        instructions = `${BRANCH_SUMMARY_PROMPT}\n\nAdditional focus: ${customInstructions}`;
+    }
+    else {
+        instructions = BRANCH_SUMMARY_PROMPT;
+    }
+    const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${instructions}`;
+    const summarizationMessages = [
+        {
+            role: 'user',
+            content: [{ type: 'text', text: promptText }],
+            timestamp: Date.now(),
+        },
+    ];
+    const response = await completeSimple(model, {
+        systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+        messages: summarizationMessages,
+    }, { apiKey, headers, signal, maxTokens: 2048 });
+    if (response.stopReason === 'aborted') {
+        return err(new BranchSummaryError('aborted', response.errorMessage || 'Branch summary aborted'));
+    }
+    if (response.stopReason === 'error') {
+        return err(new BranchSummaryError('summarization_failed', `Branch summary failed: ${response.errorMessage || 'Unknown error'}`));
+    }
+    let summary = response.content
+        .filter((c) => c.type === 'text')
+        .map((c) => c.text)
+        .join('\n');
+    summary = BRANCH_SUMMARY_PREAMBLE + summary;
+    const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+    summary += formatFileOperations(readFiles, modifiedFiles);
+    return ok({
+        summary: summary || 'No summary generated',
+        readFiles,
+        modifiedFiles,
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnJhbmNoLXN1bW1hcml6YXRpb24uanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi8uLi8uLi9zcmMvbGliL2FnZW50LWNvcmUvc3JjL2hhcm5lc3MvY29tcGFjdGlvbi9icmFuY2gtc3VtbWFyaXphdGlvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQUUsY0FBYyxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFHdkQsT0FBTyxFQUNMLFlBQVksRUFDWiwwQkFBMEIsRUFDMUIsOEJBQThCLEVBQzlCLG1CQUFtQixHQUNwQixNQUFNLGdCQUFnQixDQUFDO0FBTXhCLE9BQU8sRUFDTCxrQkFBa0IsRUFDbEIsR0FBRyxFQUNILEVBQUUsRUFFRixZQUFZLEdBQ2IsTUFBTSxhQUFhLENBQUM7QUFFckIsT0FBTyxFQUFFLGNBQWMsRUFBRSwyQkFBMkIsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQzlFLE9BQU8sRUFDTCxnQkFBZ0IsRUFDaEIsYUFBYSxFQUNiLHlCQUF5QixFQUV6QixvQkFBb0IsRUFDcEIscUJBQXFCLEdBQ3RCLE1BQU0sWUFBWSxDQUFDO0FBZ0RwQixxR0FBcUc7QUFDckcsTUFBTSxDQUFDLEtBQUssVUFBVSw4QkFBOEIsQ0FDbEQsT0FBZ0IsRUFDaEIsU0FBd0IsRUFDeEIsUUFBZ0I7SUFFaEIsSUFBSSxDQUFDLFNBQVMsRUFBRSxDQUFDO1FBQ2YsT0FBTyxFQUFFLE9BQU8sRUFBRSxFQUFFLEVBQUUsZ0JBQWdCLEVBQUUsSUFBSSxFQUFFLENBQUM7SUFDakQsQ0FBQztJQUNELE1BQU0sT0FBTyxHQUFHLElBQUksR0FBRyxDQUNyQixDQUFDLE1BQU0sT0FBTyxDQUFDLFNBQVMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsRUFBRSxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUN0RCxDQUFDO0lBQ0YsTUFBTSxVQUFVLEdBQUcsTUFBTSxPQUFP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

package/build/module/lib/agent-core/src/harness/compaction/compaction.d.ts

@@ -0,0 +1,94 @@
+import type { Model, Usage } from '@earendil-works/pi-ai';
+import type { AgentMessage, ThinkingLevel } from '../../types.ts';
+import { CompactionError, type Result, type SessionTreeEntry } from '../types.ts';
+import { type FileOperations } from './utils.ts';
+/** File-operation details stored on generated compaction entries. */
+export interface CompactionDetails {
+    /** Files read in the compacted history. */
+    readFiles: string[];
+    /** Files modified in the compacted history. */
+    modifiedFiles: string[];
+}
+/** Generated compaction data ready to be persisted as a compaction entry. */
+export interface CompactionResult<T = unknown> {
+    /** Summary text that replaces compacted history in future context. */
+    summary: string;
+    /** Entry id where retained history starts. */
+    firstKeptEntryId: string;
+    /** Estimated context tokens before compaction. */
+    tokensBefore: number;
+    /** Optional implementation-specific details stored with the compaction entry. */
+    details?: T;
+}
+/** Compaction thresholds and retention settings. */
+export interface CompactionSettings {
+    /** Enable automatic compaction decisions. */
+    enabled: boolean;
+    /** Tokens reserved for summary prompt and output. */
+    reserveTokens: number;
+    /** Approximate recent-context tokens to keep after compaction. */
+    keepRecentTokens: number;
+}
+/** Default compaction settings used by the harness. */
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/** Calculate total context tokens from provider usage. */
+export declare function calculateContextTokens(usage: Usage): number;
+/** Return usage from the last successful assistant message in session entries. */
+export declare function getLastAssistantUsage(entries: SessionTreeEntry[]): Usage | undefined;
+/** Estimated context-token usage for a message list. */
+export interface ContextUsageEstimate {
+    /** Estimated total context tokens. */
+    tokens: number;
+    /** Tokens reported by the most recent assistant usage block. */
+    usageTokens: number;
+    /** Estimated tokens after the most recent assistant usage block. */
+    trailingTokens: number;
+    /** Index of the message that provided usage, or null when none exists. */
+    lastUsageIndex: number | null;
+}
+/** Estimate context tokens for messages using provider usage when available. */
+export declare function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate;
+/** Return whether context usage exceeds the configured compaction threshold. */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/** Estimate token count for one message using a conservative character heuristic. */
+export declare function estimateTokens(message: AgentMessage): number;
+/** Find the user-visible message that starts the turn containing an entry. */
+export declare function findTurnStartIndex(entries: SessionTreeEntry[], entryIndex: number, startIndex: number): number;
+/** Cut point selected for compaction. */
+export interface CutPointResult {
+    /** Index of the first entry retained after compaction. */
+    firstKeptEntryIndex: number;
+    /** Index of the turn-start entry when the cut splits a turn, otherwise -1. */
+    turnStartIndex: number;
+    /** Whether the selected cut point splits an in-progress turn. */
+    isSplitTurn: boolean;
+}
+/** Find the compaction cut point that keeps approximately the requested recent-token budget. */
+export declare function findCutPoint(entries: SessionTreeEntry[], startIndex: number, endIndex: number, keepRecentTokens: number): CutPointResult;
+export declare const SUMMARIZATION_SYSTEM_PROMPT = "You are a context summarization assistant. Your task is to read a conversation between a user and an AI assistant, then produce a structured summary following the exact format specified.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.";
+/** Generate or update a conversation summary for compaction. */
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel): Promise<Result<string, CompactionError>>;
+/** Prepared inputs for a compaction run. */
+export interface CompactionPreparation {
+    /** Entry id where retained history starts. */
+    firstKeptEntryId: string;
+    /** Messages summarized into the history summary. */
+    messagesToSummarize: AgentMessage[];
+    /** Prefix messages summarized separately when compaction splits a turn. */
+    turnPrefixMessages: AgentMessage[];
+    /** Whether compaction splits a turn. */
+    isSplitTurn: boolean;
+    /** Estimated context tokens before compaction. */
+    tokensBefore: number;
+    /** Previous compaction summary used for iterative updates. */
+    previousSummary?: string;
+    /** File operations extracted from summarized history. */
+    fileOps: FileOperations;
+    /** Settings used to prepare compaction. */
+    settings: CompactionSettings;
+}
+/** Prepare session entries for compaction, or return undefined when compaction is not applicable. */
+export declare function prepareCompaction(pathEntries: SessionTreeEntry[], settings: CompactionSettings): Result<CompactionPreparation | undefined, CompactionError>;
+export { serializeConversation } from './utils.ts';
+/** Generate compaction summary data from prepared session history. */
+export declare function compact(preparation: CompactionPreparation, model: Model<any>, apiKey: string, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel): Promise<Result<CompactionResult, CompactionError>>;