@prometheus-ai/agent 0.5.3 → 0.5.8

package/src/session/session-context.ts

@@ -0,0 +1,352 @@
+import type { AgentMessage } from "@prometheus-ai/agent-core";
+import type { ProviderPayload, ServiceTier } from "@prometheus-ai/ai";
+import * as snapcompact from "@prometheus-ai/snapcompact";
+import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage } from "./messages";
+import { type CompactionEntry, EPHEMERAL_MODEL_CHANGE_ROLE, type SessionEntry } from "./session-entries";
+
+export interface SessionContext {
+	messages: AgentMessage[];
+	thinkingLevel?: string;
+	serviceTier?: ServiceTier;
+	/** Model roles: { default: "provider/modelId", small: "provider/modelId", ... } */
+	models: Record<string, string>;
+	/** Names of TTSR rules that have been injected this session */
+	injectedTtsrRules: string[];
+	/** MCP tool names selected through discovery for this session branch. */
+	selectedMCPToolNames: string[];
+	/** Whether this branch contains an explicit persisted MCP selection entry. */
+	hasPersistedMCPToolSelection: boolean;
+	/** Active mode (e.g. "plan") or "none" if no special mode is active */
+	mode: string;
+	/** Mode-specific data from the last mode_change entry */
+	modeData?: Record<string, unknown>;
+}
+
+/** Lists session model strings to try when restoring, in fallback order. */
+export function getRestorableSessionModels(
+	models: Readonly<Record<string, string>>,
+	lastModelChangeRole: string | undefined,
+): string[] {
+	const defaultModel = models.default;
+	if (
+		!lastModelChangeRole ||
+		lastModelChangeRole === "default" ||
+		lastModelChangeRole === EPHEMERAL_MODEL_CHANGE_ROLE
+	) {
+		return defaultModel ? [defaultModel] : [];
+	}
+
+	const roleModel = models[lastModelChangeRole];
+	if (!roleModel) return defaultModel ? [defaultModel] : [];
+	if (!defaultModel || roleModel === defaultModel) return [roleModel];
+	return [roleModel, defaultModel];
+}
+
+export function getLatestCompactionEntry(entries: SessionEntry[]): CompactionEntry | null {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		if (entries[i].type === "compaction") {
+			return entries[i] as CompactionEntry;
+		}
+	}
+	return null;
+}
+
+export interface BuildSessionContextOptions {
+	/**
+	 * Build the full-history display transcript instead of the LLM context:
+	 * every path entry in chronological order, with each compaction emitted
+	 * inline as a `compactionSummary` message at the position it fired rather
+	 * than replacing the history before it. Display-only — never send the
+	 * result to a provider.
+	 */
+	transcript?: boolean;
+}
+
+/**
+ * Build the session context from entries using tree traversal.
+ * If leafId is provided, walks from that entry to root.
+ * Handles compaction and branch summaries along the path.
+ */
+export function buildSessionContext(
+	entries: SessionEntry[],
+	leafId?: string | null,
+	byId?: Map<string, SessionEntry>,
+	options?: BuildSessionContextOptions,
+): SessionContext {
+	// Build uuid index if not available
+	if (!byId) {
+		byId = new Map<string, SessionEntry>();
+		for (const entry of entries) {
+			byId.set(entry.id, entry);
+		}
+	}
+
+	// Find leaf
+	let leaf: SessionEntry | undefined;
+	if (leafId === null) {
+		// Explicitly null - return no messages (navigated to before first entry)
+		return {
+			messages: [],
+			thinkingLevel: "off",
+			serviceTier: undefined,
+			models: {},
+			injectedTtsrRules: [],
+			selectedMCPToolNames: [],
+			hasPersistedMCPToolSelection: false,
+			mode: "none",
+		};
+	}
+	if (leafId) {
+		leaf = byId.get(leafId);
+	}
+	if (!leaf) {
+		// Fallback to last entry (when leafId is undefined)
+		leaf = entries[entries.length - 1];
+	}
+
+	if (!leaf) {
+		return {
+			messages: [],
+			thinkingLevel: "off",
+			serviceTier: undefined,
+			models: {},
+			injectedTtsrRules: [],
+			selectedMCPToolNames: [],
+			hasPersistedMCPToolSelection: false,
+			mode: "none",
+		};
+	}
+
+	// Walk from leaf to root, collecting path
+	const path: SessionEntry[] = [];
+	let current: SessionEntry | undefined = leaf;
+	while (current) {
+		path.unshift(current);
+		current = current.parentId ? byId.get(current.parentId) : undefined;
+	}
+
+	// Extract settings and find compaction
+	let thinkingLevel: string | undefined = "off";
+	let serviceTier: ServiceTier | undefined;
+	const models: Record<string, string> = {};
+	let compaction: CompactionEntry | null = null;
+	const injectedTtsrRulesSet = new Set<string>();
+	let selectedMCPToolNames: string[] = [];
+	let hasPersistedMCPToolSelection = false;
+	let mode = "none";
+	let modeData: Record<string, unknown> | undefined;
+	// Track whether an explicit `model_change` with role="default" has been
+	// seen on this path. Once a user (or the agent itself) records an
+	// explicit default, later assistant-message inference must NOT overwrite
+	// it: temporary fallbacks (retry fallback, context promotion) and
+	// server-side model downgrades both produce assistant messages tagged
+	// with the wrong model id, which previously clobbered the user's pick on
+	// resume (issue #849).
+	let hasExplicitDefaultModel = false;
+
+	for (const entry of path) {
+		if (entry.type === "thinking_level_change") {
+			thinkingLevel = entry.thinkingLevel ?? "off";
+		} else if (entry.type === "model_change") {
+			// New format: { model: "provider/id", role?: string }
+			if (entry.model) {
+				const role = entry.role ?? "default";
+				models[role] = entry.model;
+				if (role === "default") {
+					hasExplicitDefaultModel = true;
+				}
+			}
+		} else if (entry.type === "service_tier_change") {
+			serviceTier = entry.serviceTier ?? undefined;
+		} else if (entry.type === "message" && entry.message.role === "assistant") {
+			// Legacy fallback: infer default model from assistant messages only
+			// when no explicit `model_change` (role=default) entry has been
+			// recorded yet. Newer sessions always record an explicit default
+			// model_change at the start of the conversation, so this branch is
+			// only used to keep pre-model_change sessions working.
+			if (!hasExplicitDefaultModel) {
+				models.default = `${entry.message.provider}/${entry.message.model}`;
+			}
+		} else if (entry.type === "compaction") {
+			compaction = entry;
+		} else if (entry.type === "ttsr_injection") {
+			// Collect injected TTSR rule names
+			for (const ruleName of entry.injectedRules) {
+				injectedTtsrRulesSet.add(ruleName);
+			}
+		} else if (entry.type === "mcp_tool_selection") {
+			selectedMCPToolNames = [...entry.selectedToolNames];
+			hasPersistedMCPToolSelection = true;
+		} else if (entry.type === "mode_change") {
+			mode = entry.mode;
+			modeData = entry.data;
+		}
+	}
+
+	const injectedTtsrRules = Array.from(injectedTtsrRulesSet);
+
+	// Build messages and collect corresponding entries
+	// When there's a compaction, we need to:
+	// 1. Emit summary first (entry = compaction)
+	// 2. Emit kept messages (from firstKeptEntryId up to compaction)
+	// 3. Emit messages after compaction
+	const messages: AgentMessage[] = [];
+
+	const appendMessage = (entry: SessionEntry) => {
+		if (entry.type === "message") {
+			messages.push(entry.message);
+		} else if (entry.type === "custom_message") {
+			messages.push(
+				createCustomMessage(
+					entry.customType,
+					entry.content,
+					entry.display,
+					entry.details,
+					entry.timestamp,
+					entry.attribution,
+				),
+			);
+		} else if (entry.type === "branch_summary" && entry.summary) {
+			messages.push(createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp));
+		}
+	};
+
+	if (options?.transcript) {
+		// Display transcript: every entry in chronological order. Compactions do
+		// not erase prior history here — each renders inline (as a divider in the
+		// TUI) at the point it fired, with any snapcompact frames re-attached so
+		// the component can report them.
+		for (const entry of path) {
+			if (entry.type === "compaction") {
+				const snapcompactArchive = snapcompact.getPreservedArchive(entry.preserveData);
+				messages.push(
+					createCompactionSummaryMessage(
+						entry.summary,
+						entry.tokensBefore,
+						entry.timestamp,
+						entry.shortSummary,
+						undefined,
+						snapcompactArchive ? snapcompact.images(snapcompactArchive) : undefined,
+					),
+				);
+			} else {
+				appendMessage(entry);
+			}
+		}
+	} else if (compaction) {
+		const providerPayload: ProviderPayload | undefined = (() => {
+			const candidate = compaction.preserveData?.openaiRemoteCompaction;
+			if (!candidate || typeof candidate !== "object") return undefined;
+			const remote = candidate as { provider?: unknown; replacementHistory?: unknown };
+			if (typeof remote.provider !== "string" || remote.provider.length === 0) return undefined;
+			if (!Array.isArray(remote.replacementHistory)) return undefined;
+			return {
+				type: "openaiResponsesHistory",
+				provider: remote.provider,
+				items: remote.replacementHistory as Array<Record<string, unknown>>,
+			};
+		})();
+		const remoteReplacementHistory = providerPayload?.items;
+
+		// Emit summary first; re-attach any archived snapcompact frames so the
+		// model can keep reading the archived history after every context rebuild.
+		const snapcompactArchive = snapcompact.getPreservedArchive(compaction.preserveData);
+		messages.push(
+			createCompactionSummaryMessage(
+				compaction.summary,
+				compaction.tokensBefore,
+				compaction.timestamp,
+				compaction.shortSummary,
+				providerPayload,
+				snapcompactArchive ? snapcompact.images(snapcompactArchive) : undefined,
+			),
+		);
+
+		// Find compaction index in path
+		const compactionIdx = path.findIndex(e => e.type === "compaction" && e.id === compaction.id);
+
+		if (!remoteReplacementHistory) {
+			// Emit kept messages (before compaction, starting from firstKeptEntryId)
+			let foundFirstKept = false;
+			for (let i = 0; i < compactionIdx; i++) {
+				const entry = path[i];
+				if (entry.id === compaction.firstKeptEntryId) {
+					foundFirstKept = true;
+				}
+				if (foundFirstKept) {
+					appendMessage(entry);
+				}
+			}
+		}
+
+		// Emit messages after compaction
+		for (let i = compactionIdx + 1; i < path.length; i++) {
+			const entry = path[i];
+			appendMessage(entry);
+		}
+	} else {
+		// No compaction - emit all messages, handle branch summaries and custom messages
+		for (const entry of path) {
+			appendMessage(entry);
+		}
+	}
+
+	// Strip dangling tool_use blocks — a tool_use with no matching tool_result on the
+	// resolved leaf→root path — from ANY assistant turn, not just the trailing one.
+	// This happens whenever the leaf (or a branch point) lands such that an assistant
+	// turn's tool results are off the selected path: its result children live on a
+	// sibling branch, or it is the leaf itself (results are children below it). Left
+	// in place, `transformMessages` fabricates one synthetic "aborted"/"No result
+	// provided" result per dangling call, which render as phantom failed calls and
+	// re-inject the failed batch into the model's
+	// context — the rewind/restore loop.
+	//
+	// Stripping is necessary but not sufficient: a *modified* assistant turn that still
+	// carries signed `thinking`/`redacted_thinking` is rejected by Anthropic — "thinking
+	// blocks in the latest assistant message cannot be modified", and signed thinking
+	// replayed out of its original turn shape can also fail signature validation (this
+	// bites the handoff/branch-summary request). So when we rewrite a turn we also
+	// neutralize its protected reasoning: drop `redactedThinking` (encrypted, no
+	// plaintext to keep) and clear `thinking` signatures so the provider encoder
+	// downgrades them to plain text (verified accepted by the live API), preserving the
+	// visible reasoning while removing the immutability/invalid-signature hazard. Drop a
+	// turn left with no content. (Live turns never qualify: their results are persisted
+	// on the same path before any context rebuild.)
+	const pairedToolResultIds = new Set<string>();
+	for (const message of messages) {
+		if (message.role === "toolResult") pairedToolResultIds.add(message.toolCallId);
+	}
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const message = messages[i];
+		if (message.role !== "assistant") continue;
+		const hasDangling = message.content.some(
+			block => block.type === "toolCall" && !pairedToolResultIds.has(block.id),
+		);
+		if (!hasDangling) continue;
+		const normalized = message.content
+			.filter(
+				block =>
+					!(block.type === "toolCall" && !pairedToolResultIds.has(block.id)) && block.type !== "redactedThinking",
+			)
+			.map(block =>
+				block.type === "thinking" && block.thinkingSignature ? { ...block, thinkingSignature: undefined } : block,
+			);
+		if (normalized.length === 0) {
+			messages.splice(i, 1);
+		} else {
+			messages[i] = { ...message, content: normalized };
+		}
+	}
+
+	return {
+		messages,
+		thinkingLevel,
+		serviceTier,
+		models,
+		injectedTtsrRules,
+		selectedMCPToolNames,
+		hasPersistedMCPToolSelection,
+		mode,
+		modeData,
+	};
+}

package/src/session/session-dump-format.ts

@@ -4,6 +4,8 @@
 import type { AgentMessage, ThinkingLevel } from "@prometheus-ai/agent-core";
 import { INTENT_FIELD } from "@prometheus-ai/agent-core";
 import type { AssistantMessage, Model } from "@prometheus-ai/ai";
+import { isZodSchema, zodToWireSchema } from "@prometheus-ai/ai/utils/schema";
+import { getVisibleThinkingText } from "../utils/thinking-display";
 import {
 	type BashExecutionMessage,
 	type BranchSummaryMessage,
@@ -47,6 +49,12 @@ function stripTypeBoxFields(obj: unknown): unknown {
 	return obj;
 }
 
+/** Resolve tool parameters to a plain JSON Schema object for dump output. */
+function toolParametersToJsonSchema(parameters: unknown): unknown {
+	if (isZodSchema(parameters)) return zodToWireSchema(parameters);
+	return stripTypeBoxFields(parameters);
+}
+
 /** Serialize an object as XML parameter elements, one per key. */
 function formatArgsAsXml(args: Record<string, unknown>, indent = "\t"): string {
 	const parts: string[] = [];
@@ -89,7 +97,7 @@ export function formatSessionDumpText(options: FormatSessionDumpTextOptions): st
 		for (const tool of tools) {
 			lines.push(`<tool name="${tool.name}">`);
 			lines.push(tool.description);
-			const parametersClean = stripTypeBoxFields(tool.parameters);
+			const parametersClean = toolParametersToJsonSchema(tool.parameters);
 			lines.push(`\nParameters:\n${formatArgsAsXml(parametersClean as Record<string, unknown>)}`);
 			lines.push("<" + "/tool>\n");
 		}
@@ -119,9 +127,10 @@ export function formatSessionDumpText(options: FormatSessionDumpTextOptions): st
 				if (c.type === "text") {
 					lines.push(c.text);
 				} else if (c.type === "thinking") {
-					if (c.thinking.trim().length === 0) continue;
+					const thinking = getVisibleThinkingText(c);
+					if (thinking.length === 0) continue;
 					lines.push("<thinking>");
-					lines.push(c.thinking);
+					lines.push(thinking);
 					lines.push("</thinking>\n");
 				} else if (c.type === "toolCall") {
 					lines.push(`<invoke name="${c.name}">`);

package/src/session/session-entries.ts

@@ -0,0 +1,194 @@
+import type { AgentMessage } from "@prometheus-ai/agent-core";
+import type { ImageContent, MessageAttribution, ServiceTier, TextContent } from "@prometheus-ai/ai";
+
+export const CURRENT_SESSION_VERSION = 3;
+
+export const EPHEMERAL_MODEL_CHANGE_ROLE = "fallback";
+
+export interface SessionHeader {
+	type: "session";
+	version?: number; // v1 sessions don't have this
+	id: string;
+	title?: string; // Auto-generated title from first message
+	titleSource?: "auto" | "user";
+	timestamp: string;
+	cwd: string;
+	parentSession?: string;
+}
+
+export interface NewSessionOptions {
+	parentSession?: string;
+	/** Skip flushing the current session and delete it instead of saving. */
+	drop?: boolean;
+}
+
+export interface SessionEntryBase {
+	type: string;
+	id: string;
+	parentId: string | null;
+	timestamp: string;
+}
+
+export interface SessionMessageEntry extends SessionEntryBase {
+	type: "message";
+	message: AgentMessage;
+}
+
+export interface ThinkingLevelChangeEntry extends SessionEntryBase {
+	type: "thinking_level_change";
+	thinkingLevel?: string | null;
+}
+
+export interface ModelChangeEntry extends SessionEntryBase {
+	type: "model_change";
+	/** Model in "provider/modelId" format */
+	model: string;
+	/** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
+	role?: string;
+}
+
+export interface ServiceTierChangeEntry extends SessionEntryBase {
+	type: "service_tier_change";
+	serviceTier: ServiceTier | null;
+}
+
+export interface CompactionEntry<T = unknown> extends SessionEntryBase {
+	type: "compaction";
+	summary: string;
+	shortSummary?: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+	details?: T;
+	/** Hook-provided data to persist across compaction */
+	preserveData?: Record<string, unknown>;
+	/** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
+	fromExtension?: boolean;
+}
+
+export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
+	type: "branch_summary";
+	fromId: string;
+	summary: string;
+	/** Extension-specific data (not sent to LLM) */
+	details?: T;
+	/** True if generated by an extension, false if pi-generated */
+	fromExtension?: boolean;
+}
+
+/**
+ * Custom entry for extensions to store extension-specific data in the session.
+ * Use customType to identify your extension's entries.
+ *
+ * Purpose: Persist extension state across session reloads. On reload, extensions can
+ * scan entries for their customType and reconstruct internal state.
+ *
+ * Does NOT participate in LLM context (ignored by buildSessionContext).
+ * For injecting content into context, see CustomMessageEntry.
+ */
+export interface CustomEntry<T = unknown> extends SessionEntryBase {
+	type: "custom";
+	customType: string;
+	data?: T;
+}
+
+/** Label entry for user-defined bookmarks/markers on entries. */
+export interface LabelEntry extends SessionEntryBase {
+	type: "label";
+	targetId: string;
+	label: string | undefined;
+}
+
+/** TTSR injection entry - tracks which time-traveling rules have been injected this session. */
+export interface TtsrInjectionEntry extends SessionEntryBase {
+	type: "ttsr_injection";
+	/** Names of rules that were injected */
+	injectedRules: string[];
+}
+
+/** Persisted MCP discovery selection state for a session branch. */
+export interface MCPToolSelectionEntry extends SessionEntryBase {
+	type: "mcp_tool_selection";
+	/** MCP tool names selected for visibility in discovery mode. */
+	selectedToolNames: string[];
+}
+
+/** Session init entry - captures initial context for subagent sessions (debugging/replay). */
+export interface SessionInitEntry extends SessionEntryBase {
+	type: "session_init";
+	/** Full system prompt sent to the model */
+	systemPrompt: string;
+	/** Initial task/user message */
+	task: string;
+	/** Tools available to the agent */
+	tools: string[];
+	/** Output schema if structured output was requested */
+	outputSchema?: unknown;
+}
+
+/** Mode change entry - tracks agent mode transitions (e.g. plan mode). */
+export interface ModeChangeEntry extends SessionEntryBase {
+	type: "mode_change";
+	/** Current mode name, or "none" when exiting a mode */
+	mode: string;
+	/** Optional mode-specific data (e.g. plan file path) */
+	data?: Record<string, unknown>;
+}
+
+/**
+ * Custom message entry for extensions to inject messages into LLM context.
+ * Use customType to identify your extension's entries.
+ *
+ * Unlike CustomEntry, this DOES participate in LLM context.
+ * The content participates in LLM context through convertToLlm().
+ * Use details for extension-specific metadata (not sent to LLM).
+ *
+ * display controls TUI rendering:
+ * - false: hidden entirely
+ * - true: rendered with distinct styling (different from user messages)
+ */
+export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
+	type: "custom_message";
+	customType: string;
+	content: string | (TextContent | ImageContent)[];
+	details?: T;
+	display: boolean;
+	/** Who initiated this message for billing/attribution semantics. */
+	attribution?: MessageAttribution;
+}
+
+/** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
+export type SessionEntry =
+	| SessionMessageEntry
+	| ThinkingLevelChangeEntry
+	| ModelChangeEntry
+	| ServiceTierChangeEntry
+	| CompactionEntry
+	| BranchSummaryEntry
+	| CustomEntry
+	| CustomMessageEntry
+	| LabelEntry
+	| TtsrInjectionEntry
+	| MCPToolSelectionEntry
+	| SessionInitEntry
+	| ModeChangeEntry;
+
+/** Raw file entry (includes header) */
+export type FileEntry = SessionHeader | SessionEntry;
+
+/** Tree node for getTree() - defensive copy of session structure */
+export interface SessionTreeNode {
+	entry: SessionEntry;
+	children: SessionTreeNode[];
+	/** Resolved label for this entry, if any */
+	label?: string;
+}
+
+export interface UsageStatistics {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	premiumRequests: number;
+	cost: number;
+}