@xopcai/xopc 0.0.206 → 0.0.207

package/dist/src/agent/memory/compaction-ledger.js

@@ -0,0 +1,108 @@
+import { HANDOVER_ITEM_KINDS } from "../../session/compaction-types.js";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+//#region src/agent/memory/compaction-ledger.ts
+const RawHandoverItemSchema = z.object({
+	kind: z.enum(HANDOVER_ITEM_KINDS),
+	text: z.string().min(1),
+	status: z.enum([
+		"active",
+		"completed",
+		"superseded"
+	]),
+	sourceSeqs: z.array(z.number().int().positive()).min(1),
+	identifiers: z.array(z.string()).default([])
+}).strict();
+const RawHandoverSchema = z.object({ items: z.array(RawHandoverItemSchema).max(120) }).strict();
+function extractJsonObject(text) {
+	const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
+	if (fenced) return fenced;
+	const start = text.indexOf("{");
+	const end = text.lastIndexOf("}");
+	if (start < 0 || end <= start) throw new Error("Compaction model did not return a JSON object");
+	return text.slice(start, end + 1);
+}
+function itemId(kind, text, seqs) {
+	return createHash("sha256").update(`${kind}\0${text.trim()}\0${[...seqs].sort((a, b) => a - b).join(",")}`).digest("hex").slice(0, 20);
+}
+function parseCompactionHandover(params) {
+	const parsed = RawHandoverSchema.parse(JSON.parse(extractJsonObject(params.text)));
+	const sourceBySeq = new Map(params.allowedSources.map((source) => [source.seq, source]));
+	const items = parsed.items.map((item) => {
+		const seqs = [...new Set(item.sourceSeqs)].sort((a, b) => a - b);
+		const sources = seqs.map((seq) => {
+			const source = sourceBySeq.get(seq);
+			if (!source || seq > params.sourceThroughSeq) throw new Error(`Compaction handover references unavailable source seq ${seq}`);
+			return {
+				entryId: source.entryId,
+				seq
+			};
+		});
+		const text = item.text.trim();
+		return {
+			id: itemId(item.kind, text, seqs),
+			kind: item.kind,
+			text,
+			status: item.status,
+			sources,
+			identifiers: [...new Set(item.identifiers.map((value) => value.trim()).filter(Boolean))]
+		};
+	});
+	return {
+		version: 1,
+		sourceThroughSeq: params.sourceThroughSeq,
+		...params.previousBoundaryId ? { previousBoundaryId: params.previousBoundaryId } : {},
+		items: [...new Map(items.map((item) => [item.id, item])).values()]
+	};
+}
+const SUMMARY_GROUPS = [
+	{
+		heading: "Decisions",
+		kinds: ["objective", "decision"]
+	},
+	{
+		heading: "Pending user asks",
+		kinds: ["pending_user_ask"]
+	},
+	{
+		heading: "Open TODOs",
+		kinds: ["todo", "next_action"]
+	},
+	{
+		heading: "Constraints and rules",
+		kinds: ["constraint"]
+	},
+	{
+		heading: "Tool operations and results",
+		kinds: [
+			"file_change",
+			"tool_outcome",
+			"failure"
+		]
+	},
+	{
+		heading: "Recent state",
+		kinds: ["current_state"]
+	}
+];
+function renderCompactionHandover(handover) {
+	const active = handover.items.filter((item) => item.status === "active");
+	const sections = SUMMARY_GROUPS.map(({ heading, kinds }) => {
+		const items = active.filter((item) => kinds.includes(item.kind));
+		return `## ${heading}\n${items.length > 0 ? items.map((item) => `- ${item.text}`).join("\n") : "None"}`;
+	});
+	const identifiers = [...new Set(active.flatMap((item) => item.identifiers))];
+	sections.splice(4, 0, `## Exact identifiers\n${identifiers.length > 0 ? identifiers.map((value) => `- \`${value}\``).join("\n") : "None"}`);
+	return sections.join("\n\n");
+}
+function handoverForPrompt(handover) {
+	return { items: handover?.items.map((item) => ({
+		kind: item.kind,
+		text: item.text,
+		status: item.status,
+		sourceSeqs: item.sources.map((source) => source.seq),
+		identifiers: item.identifiers
+	})) ?? [] };
+}
+//#endregion
+export { handoverForPrompt, parseCompactionHandover, renderCompactionHandover };

package/dist/src/agent/memory/compaction-serializer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+export declare function serializeMessageForCompaction(message: AgentMessage): string;

package/dist/src/agent/memory/compaction-serializer.js

@@ -0,0 +1,52 @@
+import { readAgentMessageContent } from "./agent-message-access.js";
+//#region src/agent/memory/compaction-serializer.ts
+function safeJson(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+function valueRecord(value) {
+	return value && typeof value === "object" ? value : void 0;
+}
+function serializeContentBlock(block) {
+	const record = valueRecord(block);
+	if (!record) return safeJson(block);
+	const type = String(record.type ?? "unknown");
+	if (type === "text") return String(record.text ?? "");
+	if (type === "toolCall") return [
+		"[Tool call]",
+		`name: ${String(record.name ?? "unknown")}`,
+		`id: ${String(record.id ?? record.toolCallId ?? "unknown")}`,
+		`arguments: ${safeJson(record.arguments ?? record.args ?? {})}`
+	].join("\n");
+	if (type === "image" || type === "audio" || type === "video" || type === "file") {
+		const metadata = { ...record };
+		delete metadata.data;
+		delete metadata.bytes;
+		delete metadata.base64;
+		return `[${type} content]\nmetadata: ${safeJson(metadata)}`;
+	}
+	if (type === "thinking" || type === "reasoning" || type === "reasoning_details") return "[Assistant private reasoning omitted from compaction input]";
+	return `[${type} block]\n${safeJson(record)}`;
+}
+function serializeMessageForCompaction(message) {
+	const record = message;
+	const raw = readAgentMessageContent(message);
+	const content = typeof raw === "string" ? raw : Array.isArray(raw) ? raw.map(serializeContentBlock).filter(Boolean).join("\n\n") : safeJson(raw);
+	const metadata = [];
+	if (message.role === "toolResult") {
+		metadata.push(`tool: ${String(record.toolName ?? "unknown")}`);
+		metadata.push(`toolCallId: ${String(record.toolCallId ?? "unknown")}`);
+		metadata.push(`status: ${record.isError === true ? "error" : "success"}`);
+		if (record.details != null) metadata.push(`details: ${safeJson(record.details)}`);
+	}
+	return [
+		`### ${message.role}`,
+		...metadata,
+		content
+	].filter(Boolean).join("\n");
+}
+//#endregion
+export { serializeMessageForCompaction };

package/dist/src/agent/memory/compaction-source-planner.d.ts

@@ -0,0 +1,20 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { TranscriptSourceEntry } from '../../storage/sqlite/transcript-repository.js';
+export interface CompactionSourcePlan {
+    sourceEntries: TranscriptSourceEntry[];
+    keptEntries: TranscriptSourceEntry[];
+    keptMessages: AgentMessage[];
+    allMessages: AgentMessage[];
+    sourceThroughSeq: number;
+}
+export declare function planCompactionSource(params: {
+    entries: readonly TranscriptSourceEntry[];
+    minMessagesBeforeCompact: number;
+    recentTurnsPreserve: number;
+    keepRecentTokens: number;
+    force: boolean;
+}): CompactionSourcePlan | null;
+export declare function estimateCompactionSourceTokens(plan: CompactionSourcePlan): {
+    before: number;
+    kept: number;
+};

package/dist/src/agent/memory/compaction-source-planner.js

@@ -0,0 +1,67 @@
+import { buildSessionContextForLlm, isRuntimeOnlyTranscriptMessage, isTranscriptCompactionEntry, isTranscriptContextEntry, isTranscriptCustomMessageEntry, isTranscriptCustomStateEntry, isTranscriptLabelEntry, isTranscriptMetadataEntry, isTranscriptSummaryMessageEntry } from "../../session/session-context-for-llm.js";
+import { estimateMessagesTokens, estimateTextTokens } from "./context-budget.js";
+//#region src/agent/memory/compaction-source-planner.ts
+function isModelSource(entry) {
+	const row = entry.row;
+	return !isTranscriptCompactionEntry(row) && !isTranscriptContextEntry(row) && !isTranscriptCustomStateEntry(row) && !isTranscriptSummaryMessageEntry(row) && !isTranscriptLabelEntry(row) && !isTranscriptMetadataEntry(row) && !isRuntimeOnlyTranscriptMessage(row);
+}
+function isTurnStart(entry) {
+	return entry.row.role === "user" || isTranscriptCustomMessageEntry(entry.row);
+}
+function estimateEntryTokens(entry) {
+	try {
+		return estimateTextTokens(JSON.stringify(entry.row)) + 12;
+	} catch {
+		return 12;
+	}
+}
+function findNthTurnFromEnd(entries, count) {
+	let found = 0;
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		if (!isTurnStart(entries[index])) continue;
+		found += 1;
+		if (found === count) return index;
+	}
+	return 0;
+}
+function findTurnAtOrBefore(entries, start) {
+	for (let index = Math.min(start, entries.length - 1); index >= 0; index -= 1) if (isTurnStart(entries[index])) return index;
+	return 0;
+}
+function findRecentTokenBoundary(entries, keepRecentTokens) {
+	let tokens = 0;
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		tokens += estimateEntryTokens(entries[index]);
+		if (tokens >= keepRecentTokens) return findTurnAtOrBefore(entries, index);
+	}
+	return 0;
+}
+function planCompactionSource(params) {
+	const rawEntries = params.entries.filter(isModelSource);
+	const allMessages = buildSessionContextForLlm(rawEntries.map((entry) => entry.row));
+	if (!params.force && allMessages.length < params.minMessagesBeforeCompact || params.force && allMessages.length < 2) return null;
+	const turnBoundary = findNthTurnFromEnd(rawEntries, params.recentTurnsPreserve);
+	const tokenBoundary = findRecentTokenBoundary(rawEntries, params.keepRecentTokens);
+	let splitAt = Math.min(turnBoundary, tokenBoundary);
+	if (splitAt <= 0 && params.force) splitAt = findNthTurnFromEnd(rawEntries, 1);
+	if (splitAt <= 0) return null;
+	const sourceEntries = rawEntries.slice(0, splitAt);
+	const keptEntries = rawEntries.slice(splitAt);
+	const keptMessages = buildSessionContextForLlm(keptEntries.map((entry) => entry.row));
+	if (sourceEntries.length === 0 || keptMessages.length === 0) return null;
+	return {
+		sourceEntries,
+		keptEntries,
+		keptMessages,
+		allMessages,
+		sourceThroughSeq: sourceEntries.at(-1).seq
+	};
+}
+function estimateCompactionSourceTokens(plan) {
+	return {
+		before: estimateMessagesTokens(plan.allMessages),
+		kept: estimateMessagesTokens(plan.keptMessages)
+	};
+}
+//#endregion
+export { estimateCompactionSourceTokens, planCompactionSource };

package/dist/src/agent/memory/compaction.d.ts

@@ -1,14 +1,19 @@
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import { type Api, type Model } from '@earendil-works/pi-ai/compat';
+import type { CompactionAudit, CompactionHandover } from '../../session/compaction-types.js';
+import type { TranscriptSourceEntry } from '../../storage/sqlite/transcript-repository.js';
 export interface CompactionResult {
     summary: string;
+    messages: AgentMessage[];
     firstKeptIndex: number;
     tokensBefore: number;
     tokensAfter: number;
     compacted: boolean;
-    plannerVersion?: number;
+    plannerVersion?: 3;
     summaryModelRef?: string;
     qualityAudit?: 'passed' | 'disabled';
+    handover?: CompactionHandover;
+    audit?: CompactionAudit;
     compactedUsage?: {
         input: number;
         output: number;
@@ -27,6 +32,7 @@ export interface CompactionConfig {
     summaryTimeoutMs: number;
     summaryRetries: number;
     qualityGuard: boolean;
+    gapAudit: boolean;
     accumulateUsage: boolean;
 }
 export interface CompactionExecutionOptions {
@@ -45,10 +51,10 @@ export declare class SessionCompactor {
     private readonly config;
     constructor(config?: Partial<CompactionConfig>);
     getConfig(): Readonly<CompactionConfig>;
-    compact(messages: AgentMessage[], model: Model<Api>, instructions?: string, force?: boolean, options?: CompactionExecutionOptions): Promise<CompactionResult>;
-    private generateSummary;
-    private callSummaryModels;
-    applyCompaction(messages: AgentMessage[], result: CompactionResult): AgentMessage[];
+    compact(entries: readonly TranscriptSourceEntry[], model: Model<Api>, instructions?: string, force?: boolean, options?: CompactionExecutionOptions): Promise<CompactionResult>;
     estimateTotalTokens(messages: AgentMessage[]): number;
+    private generateHandover;
+    private auditHandover;
+    private callHandoverModels;
 }
 export {};