@sayknow-cli/agent-core 0.3.16 → 0.4.0

package/src/compaction/compaction.ts

@@ -29,7 +29,6 @@ import {
 	withOpenAiRemoteCompactionPreserveData,
 } from "./openai";
 import autoHandoffThresholdFocusPrompt from "./prompts/auto-handoff-threshold-focus.md" with { type: "text" };
-import compactionShortSummaryPrompt from "./prompts/compaction-short-summary.md" with { type: "text" };
 import compactionSummaryPrompt from "./prompts/compaction-summary.md" with { type: "text" };
 import compactionTurnPrefixPrompt from "./prompts/compaction-turn-prefix.md" with { type: "text" };
 import compactionUpdateSummaryPrompt from "./prompts/compaction-update-summary.md" with { type: "text" };
@@ -144,6 +143,18 @@ export interface CompactionSettings {
 	remoteEndpoint?: string;
 }
 
+export type RemoteCompactionFallbackHealthEvent =
+	| { kind: "success"; model: string; provider: string }
+	| { kind: "fallback"; model: string; provider: string; error: string };
+
+export interface RemoteCompactionFallbackHealthHooks {
+	recordRemoteCompactionFallback(event: RemoteCompactionFallbackHealthEvent): void;
+}
+
+function isAbortError(error: unknown): boolean {
+	return error instanceof Error && error.name === "AbortError";
+}
+
 export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
 	enabled: true,
 	strategy: "context-full",
@@ -498,7 +509,8 @@ function collectMessageFragments(message: AgentMessage): { fragments: string[];
 	}
 
 	switch (message.role) {
-		case "user": {
+		case "user":
+		case "custom": {
 			const content = (message as { content: string | Array<{ type: string; text?: string }> }).content;
 			if (typeof content === "string") {
 				fragments.push(content);
@@ -698,8 +710,6 @@ export function findCutPoint(
 
 	for (let i = endIndex - 1; i >= startIndex; i--) {
 		const entry = entries[i];
-		if (entry.type !== "message") continue;
-
 		// Estimate this message's size
 		const messageTokens = estimateEntryTokens(entry);
 		accumulatedTokens += messageTokens;
@@ -757,8 +767,6 @@ const SUMMARIZATION_PROMPT = prompt.render(compactionSummaryPrompt);
 
 const UPDATE_SUMMARIZATION_PROMPT = prompt.render(compactionUpdateSummaryPrompt);
 
-const SHORT_SUMMARY_PROMPT = prompt.render(compactionShortSummaryPrompt);
-
 const HANDOFF_DOCUMENT_PROMPT = prompt.render(handoffDocumentPrompt);
 
 export const AUTO_HANDOFF_THRESHOLD_FOCUS = prompt.render(autoHandoffThresholdFocusPrompt);
@@ -784,8 +792,7 @@ export interface SummaryOptions {
 	/**
 	 * Optional telemetry handle. When provided, every LLM call emitted during
 	 * compaction is wrapped in an OTEL chat span tagged with
-	 * `pi.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
-	 * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
+	 * `pi.gen_ai.oneshot.kind` (`compaction_summary` or `compaction_turn_prefix`).
 	 */
 	telemetry?: AgentTelemetry;
 	authCredentialType?: "api_key" | "oauth";
@@ -799,6 +806,8 @@ export interface SummaryOptions {
 	providerSessionState?: Map<string, ProviderSessionState>;
 	/** Hint that websocket transport should be preferred when supported by the provider implementation. */
 	preferWebsockets?: boolean;
+	/** Session-owned health sink for remote-compaction fallback transition logging. */
+	remoteCompactionFallbackHealth?: RemoteCompactionFallbackHealthHooks;
 }
 
 /**
@@ -964,6 +973,12 @@ export interface HandoffOptions {
 	/** Live agent tool list — same purpose. Forced to `toolChoice: "none"`. */
 	tools?: AgentTool<any>[];
 	customInstructions?: string;
+	/**
+	 * Optional user-configured extension appended to the base handoff prompt.
+	 * It SUPPLEMENTS the immutable base (safety/continuity structure); it never
+	 * replaces `HANDOFF_DOCUMENT_PROMPT`.
+	 */
+	promptExtension?: string;
 	convertToLlm?: ConvertToLlm;
 	initiatorOverride?: MessageAttribution;
 	metadata?: Record<string, unknown>;
@@ -984,10 +999,11 @@ export interface HandoffOptions {
 	preferWebsockets?: boolean;
 }
 
-export function renderHandoffPrompt(customInstructions?: string): string {
-	if (!customInstructions) return HANDOFF_DOCUMENT_PROMPT;
+export function renderHandoffPrompt(customInstructions?: string, promptExtension?: string): string {
+	if (!customInstructions && !promptExtension) return HANDOFF_DOCUMENT_PROMPT;
 	return prompt.render(handoffDocumentPrompt, {
 		additionalFocus: customInstructions,
+		promptExtension,
 	});
 }
 
@@ -1003,7 +1019,7 @@ export async function generateHandoff(
 		...llmMessages,
 		{
 			role: "user",
-			content: [{ type: "text", text: renderHandoffPrompt(options.customInstructions) }],
+			content: [{ type: "text", text: renderHandoffPrompt(options.customInstructions, options.promptExtension) }],
 			attribution: "agent",
 			timestamp: Date.now(),
 		},
@@ -1040,66 +1056,11 @@ export async function generateHandoff(
 		.join("\n");
 }
 
-async function generateShortSummary(
-	recentMessages: AgentMessage[],
-	historySummary: string | undefined,
-	model: Model,
-	reserveTokens: number,
-	apiKey: string,
-	signal?: AbortSignal,
-	options?: SummaryOptions,
-): Promise<string> {
-	const maxTokens = Math.min(512, Math.floor(0.2 * reserveTokens));
-	const llmMessages = (options?.convertToLlm ?? convertToLlm)(recentMessages);
-	const conversationText = boundConversationTextForSummary(serializeConversation(llmMessages), model, maxTokens);
-
-	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
-	if (historySummary) {
-		promptText += `<previous-summary>\n${historySummary}\n</previous-summary>\n\n`;
-	}
-	promptText += formatAdditionalContext(options?.extraContext);
-	promptText += SHORT_SUMMARY_PROMPT;
-
-	if (options?.remoteEndpoint) {
-		const remote = await requestRemoteCompaction(
-			options.remoteEndpoint,
-			{
-				systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
-				prompt: promptText,
-			},
-			signal,
-		);
-		return remote.summary;
-	}
-
-	const response = await instrumentedCompleteSimple(
-		model,
-		{
-			systemPrompt: [SUMMARIZATION_SYSTEM_PROMPT],
-			messages: [{ role: "user", content: [{ type: "text", text: promptText }], timestamp: Date.now() }],
-		},
-		{
-			maxTokens,
-			signal,
-			apiKey,
-			reasoning: Effort.High,
-			initiatorOverride: options?.initiatorOverride,
-			metadata: options?.metadata,
-			sessionId: options?.sessionId,
-			providerSessionState: options?.providerSessionState,
-			preferWebsockets: options?.preferWebsockets,
-		},
-		{ telemetry: options?.telemetry, oneshotKind: "compaction_short_summary" },
-	);
-
-	if (response.stopReason === "error") {
-		throw new Error(`Short summary failed: ${response.errorMessage || "Unknown error"}`);
-	}
-
-	return response.content
-		.filter((c): c is { type: "text"; text: string } => c.type === "text")
-		.map(c => c.text)
-		.join("\n");
+/** Derive a display summary locally to avoid a second compaction LLM request. */
+function deriveShortSummary(summary: string): string {
+	const firstParagraph = summary.trim().split(/\n\s*\n/, 1)[0] ?? "";
+	const maxLength = 2_000;
+	return firstParagraph.length <= maxLength ? firstParagraph : `${firstParagraph.slice(0, maxLength - 1)}…`;
 }
 
 // ============================================================================
@@ -1149,6 +1110,11 @@ export interface PrepareCompactionOptions {
 	 * (the confounded raw promptTokens/estimatedTokens quotient is never used).
 	 */
 	tokenCorrectionRatio?: number;
+	/**
+	 * Model context-window size. Windows below 66k retain the legacy fixed
+	 * keepRecentTokens behavior; larger windows scale the keep window to 30%.
+	 */
+	contextWindow?: number;
 }
 
 export function prepareCompaction(
@@ -1179,13 +1145,42 @@ export function prepareCompaction(
 	// counts system+tools+full history while estimatedTokens counted only the
 	// post-boundary slice, so it was confounded and only ever shrank the window.
 	// Here the correction is bidirectional and clamped to [0.5, 2].
-	const keepRecentTokens = settings.keepRecentTokens;
+	const configuredKeepRecentTokens = settings.keepRecentTokens;
+	const contextWindow = options.contextWindow;
+	const thresholdSafeKeepRecentTokens =
+		contextWindow !== undefined && Number.isFinite(contextWindow) && contextWindow > 1
+			? Math.max(
+					1,
+					resolveThresholdTokens(contextWindow, settings) - effectiveReserveTokens(contextWindow, settings, 0),
+				)
+			: configuredKeepRecentTokens;
+	const keepRecentTokens = Math.min(configuredKeepRecentTokens, thresholdSafeKeepRecentTokens);
+	// Preserve the legacy fixed window for smaller models. At 66k and above,
+	// retain up to 30% of the model context, but never enough to leave the
+	// post-compaction prompt immediately above its configured threshold.
+	const scaledKeepRecentTokens =
+		contextWindow !== undefined && Number.isFinite(contextWindow) && contextWindow >= 66_000
+			? Math.min(thresholdSafeKeepRecentTokens, Math.max(keepRecentTokens, Math.floor(contextWindow * 0.3)))
+			: keepRecentTokens;
 	const rawRatio = options.tokenCorrectionRatio;
 	const appliedRatio =
 		rawRatio !== undefined && Number.isFinite(rawRatio) && rawRatio > 0
 			? Math.min(TOKEN_CORRECTION_MAX_RATIO, Math.max(TOKEN_CORRECTION_MIN_RATIO, rawRatio))
 			: 1;
-	const keepRecentTokensCorrected = Math.max(1, Math.round(keepRecentTokens / appliedRatio));
+	// Preserve an explicit keep floor that already covers the whole history: manual
+	// and emergency callers rely on prepareCompaction returning undefined rather
+	// than manufacturing a summary with no useful reduction. Otherwise, a scaled
+	// window that exceeds a short history falls back to the threshold-safe floor.
+	const historyTokens = pathEntries
+		.slice(boundaryStart, boundaryEnd)
+		.reduce((tokens, entry) => tokens + estimateEntryTokens(entry), 0);
+	const effectiveKeepRecentTokens =
+		configuredKeepRecentTokens > historyTokens
+			? configuredKeepRecentTokens
+			: scaledKeepRecentTokens > keepRecentTokens && scaledKeepRecentTokens > historyTokens
+				? keepRecentTokens
+				: scaledKeepRecentTokens;
+	const keepRecentTokensCorrected = Math.max(1, Math.round(effectiveKeepRecentTokens / appliedRatio));
 
 	const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, keepRecentTokensCorrected);
 
@@ -1305,6 +1300,7 @@ export async function compact(
 		sessionId: options?.sessionId,
 		providerSessionState: options?.providerSessionState,
 		preferWebsockets: options?.preferWebsockets,
+		remoteCompactionFallbackHealth: options?.remoteCompactionFallbackHealth,
 	};
 
 	let preserveData = withOpenAiRemoteCompactionPreserveData(previousPreserveData, undefined);
@@ -1331,12 +1327,28 @@ export async function compact(
 					{ authCredentialType: options?.authCredentialType },
 				);
 				preserveData = withOpenAiRemoteCompactionPreserveData(previousPreserveData, remote);
-			} catch (err) {
-				logger.warn("OpenAI remote compaction failed, falling back to local summarization", {
-					error: err instanceof Error ? err.message : String(err),
+				summaryOptions.remoteCompactionFallbackHealth?.recordRemoteCompactionFallback({
+					kind: "success",
 					model: model.id,
 					provider: model.provider,
 				});
+			} catch (err) {
+				if (signal?.aborted || isAbortError(err)) throw err;
+				const error = err instanceof Error ? err.message : String(err);
+				if (summaryOptions.remoteCompactionFallbackHealth) {
+					summaryOptions.remoteCompactionFallbackHealth.recordRemoteCompactionFallback({
+						kind: "fallback",
+						error,
+						model: model.id,
+						provider: model.provider,
+					});
+				} else {
+					logger.warn("OpenAI remote compaction failed, falling back to local summarization", {
+						error,
+						model: model.id,
+						provider: model.provider,
+					});
+				}
 			}
 		}
 	}
@@ -1406,28 +1418,10 @@ export async function compact(
 		summary = "No prior history.";
 	}
 
-	const shortSummary = await generateShortSummary(
-		recentMessages,
-		summary,
-		model,
-		settings.reserveTokens,
-		apiKey,
-		signal,
-		{
-			extraContext: options?.extraContext,
-			remoteEndpoint: summaryOptions.remoteEndpoint,
-			initiatorOverride: summaryOptions.initiatorOverride,
-			metadata: summaryOptions.metadata,
-			telemetry: summaryOptions.telemetry,
-			sessionId: summaryOptions.sessionId,
-			providerSessionState: summaryOptions.providerSessionState,
-			preferWebsockets: summaryOptions.preferWebsockets,
-		},
-	);
-
 	// Compute file lists and append to summary
 	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
 	summary = upsertFileOperations(summary, readFiles, modifiedFiles);
+	const shortSummary = deriveShortSummary(summary);
 
 	if (!firstKeptEntryId) {
 		throw new Error("First kept entry has no ID - session may need migration");

package/src/compaction/entries.ts

@@ -95,6 +95,12 @@ export interface MCPToolSelectionEntry extends SessionEntryBase {
 	selectedToolNames: string[];
 }
 
+export interface DiscoveredBuiltinToolSelectionEntry extends SessionEntryBase {
+	type: "discovered_builtin_tool_selection";
+	/** Discoverable built-in tool names selected for visibility in discovery mode. */
+	selectedToolNames: string[];
+}
+
 export interface SessionInitEntry extends SessionEntryBase {
 	type: "session_init";
 	/** Full system prompt sent to the model */
@@ -115,6 +121,17 @@ export interface ModeChangeEntry extends SessionEntryBase {
 	data?: Record<string, unknown>;
 }
 
+export interface ConfiguredModelChainEntry extends SessionEntryBase {
+	type: "configured_model_chain";
+	role: string;
+	entries: readonly string[];
+	origin: string;
+	identity?: string;
+	explicitHead: boolean;
+	/** Whether this entry removes the configured chain for its role. */
+	cleared?: boolean;
+}
+
 export interface CustomCompactionSessionEntries {}
 
 export type SessionEntry =
@@ -129,8 +146,10 @@ export type SessionEntry =
 	| LabelEntry
 	| TtsrInjectionEntry
 	| MCPToolSelectionEntry
+	| DiscoveredBuiltinToolSelectionEntry
 	| SessionInitEntry
 	| ModeChangeEntry
+	| ConfiguredModelChainEntry
 	| CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
 
 export interface ReadonlySessionManager {

package/src/compaction/openai.ts

@@ -24,6 +24,8 @@ import type { AssistantMessage, Message, Model } from "@sayknow-cli/ai/types";
 import {
 	getOpenAIResponsesHistoryItems,
 	getOpenAIResponsesHistoryPayload,
+	neutralizeReservedControlTokens,
+	neutralizeResponsesInputControlTokens,
 	normalizeResponsesToolCallId,
 } from "@sayknow-cli/ai/utils";
 import { $env, logger } from "@sayknow-cli/utils";
@@ -479,10 +481,12 @@ export async function requestOpenAiRemoteCompaction(
 	const endpoint = resolveOpenAiCompactEndpoint(model, options?.authCredentialType);
 	const request: OpenAiRemoteCompactionRequest = {
 		model: model.id,
-		input: trimOpenAiCompactInput(
-			compactInput,
-			resolveOpenAiCompactInputBudget(model.contextWindow, model.maxTokens),
-			instructions,
+		input: neutralizeResponsesInputControlTokens(
+			trimOpenAiCompactInput(
+				compactInput,
+				resolveOpenAiCompactInputBudget(model.contextWindow, model.maxTokens),
+				instructions,
+			),
 		),
 		instructions,
 	};
@@ -510,18 +514,14 @@ export async function requestOpenAiRemoteCompaction(
 	});
 
 	if (!response.ok) {
-		const errorText = await response.text().catch(() => "");
-		logger.warn("OpenAI remote compaction failed", {
-			endpoint,
-			status: response.status,
-			statusText: response.statusText,
-			errorText,
-		});
 		throw new Error(`Remote compaction failed (${response.status} ${response.statusText})`);
 	}
 
-	const data = (await response.json()) as { output?: unknown[] } | undefined;
-	const rawOutput = data?.output ?? [];
+	const data = (await response.json()) as { output?: unknown } | undefined;
+	if (!Array.isArray(data?.output)) {
+		throw new Error(`Remote compaction response malformed output (outputType=${typeof data?.output})`);
+	}
+	const rawOutput = data.output;
 	const replacementHistory = rawOutput.filter(
 		(item): item is Record<string, unknown> =>
 			!!item && typeof item === "object" && shouldKeepOpenAiCompactOutputItem(item as Record<string, unknown>),
@@ -535,15 +535,9 @@ export async function requestOpenAiRemoteCompaction(
 		const outputTypes = rawOutput.map(item =>
 			typeof item === "object" && item !== null ? (item as Record<string, unknown>).type : typeof item,
 		);
-		logger.warn("Remote compaction response missing compaction item", {
-			endpoint,
-			model: model.id,
-			provider: model.provider,
-			rawOutputLength: rawOutput.length,
-			outputTypes,
-			replacementHistoryLength: replacementHistory.length,
-		});
-		throw new Error("Remote compaction response missing compaction item");
+		throw new Error(
+			`Remote compaction response missing compaction item (rawOutputLength=${rawOutput.length}, outputTypes=${outputTypes.join(",")}, replacementHistoryLength=${replacementHistory.length})`,
+		);
 	}
 	return { provider: model.provider, replacementHistory, compactionItem };
 }
@@ -553,21 +547,21 @@ export async function requestRemoteCompaction(
 	request: RemoteCompactionRequest,
 	signal?: AbortSignal,
 ): Promise<RemoteCompactionResponse> {
+	// The prompt embeds the serialized transcript, which can carry leaked Harmony
+	// control-token markers (e.g. `<|channel|>analysis`) from model output; a
+	// gpt-5.6-backed summarization endpoint rejects those with `Request blocked`.
+	const sanitizedRequest: RemoteCompactionRequest = {
+		systemPrompt: neutralizeReservedControlTokens(request.systemPrompt),
+		prompt: neutralizeReservedControlTokens(request.prompt),
+	};
 	const response = await fetch(endpoint, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
-		body: JSON.stringify(request),
+		body: JSON.stringify(sanitizedRequest),
 		signal,
 	});
 
 	if (!response.ok) {
-		const errorText = await response.text().catch(() => "");
-		logger.warn("Remote compaction failed", {
-			endpoint,
-			status: response.status,
-			statusText: response.statusText,
-			errorText,
-		});
 		throw new Error(`Remote compaction failed (${response.status} ${response.statusText})`);
 	}
 

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

@@ -42,6 +42,13 @@ Use exactly this structure:
 1. [What should happen next]
 </output>
 
+{{#if promptExtension}}
+<instruction>
+Additional handoff guidance (supplements — does not replace — the required structure and critical rules above):
+{{promptExtension}}
+</instruction>
+{{/if}}
+
 {{#if additionalFocus}}
 <instruction>
 Additional focus: {{additionalFocus}}