@xopcai/xopc 0.0.285 → 0.0.291

package/dist/src/agent/embedded/run-turn.js

@@ -1,7 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { getClarificationResumeInput, isClarificationSuspended } from "../../storage/sqlite/clarification-wait-repository.js";
-import { getConnectionResumeInput, isConnectionSuspended } from "../../storage/sqlite/connection-wait-repository.js";
+import { getClarification, getClarificationResumeInput, isClarificationSuspended } from "../../storage/sqlite/clarification-wait-repository.js";
+import { getConnectionResumeInput, init_connection_wait_repository, isConnectionSuspended } from "../../storage/sqlite/connection-wait-repository.js";
+import { isComputerControlActive, stopComputerControl } from "../../computer/control-guard.js";
 import { EmbeddedRunConflictError, abortEmbeddedRun, acquireEmbeddedRunLease, queueEmbeddedSteer } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
 import { isContextOverflowError } from "../orchestration/context-overflow.js";
@@ -14,12 +15,15 @@ import { wrapStreamFnForXopcExtensions } from "./xopc-stream-bridge.js";
 import { acquireEmbeddedSessionRunner, evictEmbeddedSessionRunner } from "./session-runner.js";
 import { projectContextForModel } from "../memory/context-budget.js";
 import { createSqliteTranscriptRuntime } from "./transcript-runtime.js";
+import { ContextRecoveryError, assessContext, recoverContext } from "../memory/context-recovery.js";
+import { resolveCompactionPolicy } from "../memory/compaction-policy.js";
 import { buildPromptCacheSnapshot, observePromptCacheSnapshot } from "../../providers/prompt-cache-observability.js";
 import { isPromptCacheExpired, recordPromptCacheTouch } from "../../providers/prompt-cache-lifecycle.js";
 import { markTurnToolResult } from "../memory/turn-provenance.js";
 import { RepositoryInstructions } from "../coding/repository-instructions.js";
 import { RunVerification } from "../coding/run-verification.js";
 //#region src/agent/embedded/run-turn.ts
+init_connection_wait_repository();
 init_logger();
 const log = createLogger("EmbeddedRun");
 const LOG_PREVIEW_MAX_CHARS = 300;
@@ -86,7 +90,7 @@ async function maybeRecoverContextOverflow(params) {
 	if (!errorMessage || !isContextOverflowError(errorMessage)) return false;
 	const messages = stripTrailingErrorAssistantMessages(params.agent.state.messages);
 	log.warn({
-		sessionKey: params.sessionKey,
+		conversationId: params.conversationId,
 		errorMessage,
 		messageCount: messages.length
 	}, "Provider rejected the context window; compacting and retrying the same turn");
@@ -94,28 +98,52 @@ async function maybeRecoverContextOverflow(params) {
 		type: "compaction",
 		status: "started"
 	});
-	const result = await params.transcriptRuntime.compact(messages, params.model, "Preserve the current pending user request verbatim and retain every fact needed to answer it.", true, { signal: params.abortSignal });
-	if (!result.compacted) throw new Error(`Context overflow recovery could not find a safe compaction range: ${errorMessage}`);
-	params.agent.state.messages = await params.transcriptRuntime.loadMessages();
+	const summaryModel = params.policy.model ? (await import("../../providers/index.js")).resolveModel(params.policy.model) : params.model;
+	const recovered = await recoverContext({
+		conversationId: params.conversationId,
+		transcript: params.transcriptRuntime,
+		policy: params.policy,
+		budget: {
+			contextWindow: params.model.contextWindow ?? 128e3,
+			systemPrompt: params.agent.state.systemPrompt,
+			tools: params.agent.state.tools,
+			reserveTokens: params.policy.reserveTokens,
+			triggerThreshold: params.policy.triggerThreshold,
+			minToolResultKeepChars: params.policy.minToolResultKeepChars
+		},
+		summaryModel,
+		fallbackModels: summaryModel === params.model ? [] : [params.model],
+		signal: params.abortSignal,
+		providerRejected: true,
+		preserveLastUser: true
+	}).catch((error) => {
+		params.onEvent?.({
+			type: "compaction",
+			status: "skipped"
+		});
+		throw error;
+	});
+	params.agent.state.messages = stripTrailingErrorAssistantMessages(recovered.messages);
 	params.abortSignal?.throwIfAborted();
 	params.onEvent?.({
 		type: "compaction",
 		status: "completed",
-		tokensBefore: result.tokensBefore,
-		tokensAfter: result.tokensAfter,
-		summary: result.summary.length > 200 ? `${result.summary.slice(0, 200)}…` : result.summary
+		tokensBefore: recovered.result?.tokensBefore,
+		tokensAfter: recovered.result?.tokensAfter,
+		summary: recovered.result?.summary.slice(0, 200)
 	});
 	await params.agent.continue();
 	await params.agent.waitForIdle();
 	return true;
 }
 async function runXopcEmbeddedTurn(params) {
-	const { sessionKey, runId, userMessage, model, tools, systemPrompt, thinkingLevel, workspaceDir, sessionStore, onEvent } = params;
+	const { conversationId, runId, userMessage, model, tools, systemPrompt, thinkingLevel, workspaceDir, sessionStore, onEvent } = params;
 	const timeoutMs = params.timeoutMs || resolveAgentTurnTimeoutMs();
 	const resolvedModel = requireEmbeddedModel(model, params.modelRef);
 	const promptCachePolicy = resolvePromptCachePolicy(params.promptCachePolicy);
+	const compactionPolicy = params.compactionPolicy ?? resolveCompactionPolicy();
 	const transcriptRuntime = params.transcriptRuntime ?? (sessionStore ? await createSqliteTranscriptRuntime({
-		sessionKey,
+		conversationId,
 		sessionStore
 	}) : void 0);
 	if (!transcriptRuntime) throw new Error("Embedded run requires a transcript runtime");
@@ -125,15 +153,15 @@ async function runXopcEmbeddedTurn(params) {
 	let runLease;
 	try {
 		runLease = acquireEmbeddedRunLease({
-			sessionKey,
-			sessionId: transcriptRuntime.sessionId,
+			conversationId,
+			transcriptId: transcriptRuntime.transcriptId,
 			runId
 		});
 		const instructions = await RepositoryInstructions.open(workspaceDir);
 		const rootInstructions = await instructions.load(".", true);
 		runner = await acquireEmbeddedSessionRunner({
 			runtimeId: transcriptRuntime.runtimeId,
-			sessionId: transcriptRuntime.sessionId,
+			transcriptId: transcriptRuntime.transcriptId,
 			workspaceDir,
 			model: resolvedModel,
 			modelRef: params.modelRef,
@@ -152,6 +180,7 @@ async function runXopcEmbeddedTurn(params) {
 				errorMessage: "aborted"
 			};
 		}
+		session.agent.state.messages = stripTrailingErrorAssistantMessages(await transcriptRuntime.loadMessages());
 		runner.piSm.setActiveTurnId?.(runId);
 		const streamFnWithXopcExtensions = wrapStreamFnForXopcExtensions(session.agent.streamFunction, params.promptCachePolicy);
 		const loggingStreamFn = (streamModel, context, options) => {
@@ -176,8 +205,10 @@ async function runXopcEmbeddedTurn(params) {
 				contextWindow: streamModel.contextWindow ?? 128e3,
 				systemPrompt: effectiveContext.systemPrompt,
 				tools: effectiveContext.tools,
+				reserveTokens: compactionPolicy.reserveTokens,
+				minToolResultKeepChars: compactionPolicy.minToolResultKeepChars,
 				canCompact: false,
-				reason: isPromptCacheExpired(sessionKey, streamModel, promptCachePolicy) ? "cache_expired" : "normal"
+				reason: isPromptCacheExpired(conversationId, streamModel, promptCachePolicy) ? "cache_expired" : "normal"
 			});
 			if (projection.prunedToolResults > 0 || projection.prunedImages > 0) {
 				effectiveContext = {
@@ -185,7 +216,7 @@ async function runXopcEmbeddedTurn(params) {
 					messages: projection.messages
 				};
 				log.warn({
-					sessionKey,
+					conversationId,
 					runId,
 					prunedToolResults: projection.prunedToolResults,
 					prunedImages: projection.prunedImages,
@@ -193,15 +224,28 @@ async function runXopcEmbeddedTurn(params) {
 					hardLimitTokens: projection.evaluation.hardLimitTokens
 				}, "Projected a smaller provider context");
 			}
+			const assessed = assessContext({
+				messages: effectiveContext.messages,
+				contextWindow: streamModel.contextWindow ?? 128e3,
+				systemPrompt: effectiveContext.systemPrompt,
+				tools: effectiveContext.tools,
+				reserveTokens: compactionPolicy.reserveTokens,
+				minToolResultKeepChars: compactionPolicy.minToolResultKeepChars
+			}, compactionPolicy.maxActiveTranscriptBytes);
+			if (!assessed.fits) throw new ContextRecoveryError("unrecoverable", `Context budget exceeded before provider request (${assessed.evaluation.estimatedTokens}/${assessed.evaluation.hardLimitTokens} tokens)`);
+			effectiveContext = {
+				...effectiveContext,
+				messages: assessed.messages
+			};
 			const promptCacheSnapshot = buildPromptCacheSnapshot({
 				model: streamModel,
 				systemPrompt: effectiveContext.systemPrompt,
 				tools: effectiveContext.tools,
 				reasoning: options?.reasoning
 			});
-			const promptCacheChanges = observePromptCacheSnapshot(sessionKey, promptCacheSnapshot);
+			const promptCacheChanges = observePromptCacheSnapshot(conversationId, promptCacheSnapshot);
 			log.debug({
-				sessionKey,
+				conversationId,
 				runId,
 				reusedRunner: reused,
 				modelRef: `${streamModel.provider}/${streamModel.id}`,
@@ -231,7 +275,7 @@ async function runXopcEmbeddedTurn(params) {
 		runner.piSm.appendCustomEntry("coding_run_started", {
 			runId,
 			workspace: workspaceDir,
-			required: params.verifyChanges ?? sessionKey.startsWith("agent:coder:"),
+			required: params.verifyChanges ?? false,
 			...await verification.summary()
 		});
 		let policyStopped = false;
@@ -239,6 +283,13 @@ async function runXopcEmbeddedTurn(params) {
 		let clarificationStopped = false;
 		params.turnPolicy?.reset();
 		session.agent.beforeToolCall = async (context, signal) => {
+			const resume = getClarificationResumeInput(conversationId, runId);
+			const wait = resume?.payload?.waitId ? getClarification(resume.payload.waitId) : void 0;
+			if (wait?.approvalKey?.startsWith("computer:") && wait.answer !== "已在桌面端处理，继续") await stopComputerControl(conversationId);
+			if (isComputerControlActive(conversationId) && !["computer_use", "clarify"].includes(context.toolCall.name)) return {
+				block: true,
+				reason: "A desktop-control lease is active. Only computer_use and clarification are admitted until it is released. Never use shell, browser or raw MCP to bypass a desktop refusal."
+			};
 			if (connectionStopped) return {
 				block: true,
 				reason: "Waiting for the user to connect an app.",
@@ -265,8 +316,8 @@ async function runXopcEmbeddedTurn(params) {
 			return decision;
 		};
 		session.agent.afterToolCall = async (context) => {
-			connectionStopped ||= isConnectionSuspended(sessionKey, runId);
-			clarificationStopped ||= isClarificationSuspended(sessionKey, runId);
+			connectionStopped ||= isConnectionSuspended(conversationId, runId);
+			clarificationStopped ||= isClarificationSuspended(conversationId, runId);
 			const scoped = context.toolCall.name === "read_file" ? await instructions.forTool(context.toolCall.name, context.args) : "";
 			const checked = await verification.afterTool(context);
 			if (scoped) checked.result.content.unshift({
@@ -284,8 +335,8 @@ async function runXopcEmbeddedTurn(params) {
 			return policyStopped || connectionStopped || clarificationStopped;
 		};
 		unsubscribe = subscribeEmbeddedSessionEvents(session, (event) => {
-			if (event.type === "message_end" && event.message.role === "assistant") recordPromptCacheTouch(sessionKey, resolvedModel, event.message.usage);
-			if (event.type === "tool_execution_end") markTurnToolResult(sessionKey, runId, event.toolName);
+			if (event.type === "message_end" && event.message.role === "assistant") recordPromptCacheTouch(conversationId, resolvedModel, event.message.usage);
+			if (event.type === "tool_execution_end") markTurnToolResult(conversationId, runId, event.toolName);
 			onEvent?.({
 				...event,
 				runId
@@ -297,8 +348,8 @@ async function runXopcEmbeddedTurn(params) {
 		runAbortSignal.addEventListener("abort", abortListener, { once: true });
 		try {
 			await runAgentTurnWithTimeout(session.agent, async () => {
-				const connectionResume = getConnectionResumeInput(sessionKey, runId);
-				const clarificationResume = getClarificationResumeInput(sessionKey, runId);
+				const connectionResume = getConnectionResumeInput(conversationId, runId);
+				const clarificationResume = getClarificationResumeInput(conversationId, runId);
 				if (connectionResume) await session.sendCustomMessage({
 					customType: "connection_resume",
 					content: connectionResume.content,
@@ -316,23 +367,24 @@ async function runXopcEmbeddedTurn(params) {
 					await session.prompt(text, images.length > 0 ? { images } : void 0);
 				}
 				await session.agent.waitForIdle();
-				clarificationStopped ||= isClarificationSuspended(sessionKey, runId);
+				clarificationStopped ||= isClarificationSuspended(conversationId, runId);
 				if (connectionStopped || clarificationStopped) return;
 				await maybeRetryTurnAfterTransientLlmFailure(session.agent, {
-					sessionKey,
+					conversationId,
 					log,
 					signal: runAbortSignal
 				});
 				await maybeRecoverContextOverflow({
 					agent: session.agent,
 					model: resolvedModel,
-					sessionKey,
+					conversationId,
 					transcriptRuntime,
+					policy: compactionPolicy,
 					abortSignal: runAbortSignal,
 					onEvent
 				});
 				const pending = await verification.pendingContext();
-				if ((params.verifyChanges ?? sessionKey.startsWith("agent:coder:")) && pending && !policyStopped && !runAbortSignal.aborted && !isAssistantTurnFailed(session.agent) && !isAssistantTurnAborted(session.agent)) {
+				if ((params.verifyChanges ?? false) && pending && !policyStopped && !runAbortSignal.aborted && !isAssistantTurnFailed(session.agent) && !isAssistantTurnAborted(session.agent)) {
 					await session.sendCustomMessage({
 						customType: "coding_verification",
 						content: pending,
@@ -343,16 +395,16 @@ async function runXopcEmbeddedTurn(params) {
 			}, timeoutMs);
 			if (connectionStopped) runner.piSm.appendCustomEntry("connection_required", {
 				runId,
-				sessionKey
+				conversationId
 			});
 			if (clarificationStopped) runner.piSm.appendCustomEntry("clarification_required", {
 				runId,
-				sessionKey
+				conversationId
 			});
 			runner.piSm.appendCustomEntry("coding_verification", {
 				runId,
 				workspace: workspaceDir,
-				required: params.verifyChanges ?? sessionKey.startsWith("agent:coder:"),
+				required: params.verifyChanges ?? false,
 				...await verification.summary()
 			});
 			if (runAbortSignal.aborted) return {
@@ -385,7 +437,7 @@ async function runXopcEmbeddedTurn(params) {
 		if (err instanceof EmbeddedRunConflictError) {
 			const em = err.message;
 			log.warn({
-				sessionKey,
+				conversationId,
 				runId,
 				activeRunId: err.activeRunId
 			}, `Embedded run rejected: ${em}`);
@@ -404,7 +456,7 @@ async function runXopcEmbeddedTurn(params) {
 		const em = err instanceof Error ? err.message : String(err);
 		log.error({
 			err,
-			sessionKey,
+			conversationId,
 			runId
 		}, `Embedded run failed: ${em}`);
 		onEvent?.({

package/dist/src/agent/embedded/runs.d.ts

@@ -1,7 +1,7 @@
 import type { AgentSession } from '@earendil-works/pi-coding-agent';
 export type EmbeddedRunIdentity = {
-    sessionKey: string;
-    sessionId: string;
+    conversationId: string;
+    transcriptId: string;
     runId: string;
 };
 export type EmbeddedRunHandle = EmbeddedRunIdentity & {
@@ -9,9 +9,9 @@ export type EmbeddedRunHandle = EmbeddedRunIdentity & {
     abort: () => Promise<void>;
 };
 export declare class EmbeddedRunConflictError extends Error {
-    readonly sessionKey: string;
+    readonly conversationId: string;
     readonly activeRunId: string;
-    constructor(sessionKey: string, activeRunId: string);
+    constructor(conversationId: string, activeRunId: string);
 }
 export type EmbeddedRunLease = {
     signal: AbortSignal;
@@ -20,14 +20,14 @@ export type EmbeddedRunLease = {
 };
 /** Owns one process-local execution lease per session while leaving steer/abort on the control plane. */
 export declare class EmbeddedRunRegistry {
-    private readonly bySessionKey;
+    private readonly byConversationId;
     acquire(identity: EmbeddedRunIdentity): EmbeddedRunLease;
-    getBySessionKey(sessionKey: string): EmbeddedRunHandle | undefined;
-    abortBySessionKey(sessionKey: string): Promise<boolean>;
-    steerBySessionKey(sessionKey: string, text: string): Promise<boolean>;
+    getByConversationId(conversationId: string): EmbeddedRunHandle | undefined;
+    abortByConversationId(conversationId: string): Promise<boolean>;
+    steerByConversationId(conversationId: string, text: string): Promise<boolean>;
     size(): number;
 }
 export declare function acquireEmbeddedRunLease(identity: EmbeddedRunIdentity): EmbeddedRunLease;
-export declare function getEmbeddedRunBySessionKey(sessionKey: string): EmbeddedRunHandle | undefined;
-export declare function abortEmbeddedRun(sessionKey: string): Promise<boolean>;
-export declare function queueEmbeddedSteer(sessionKey: string, text: string): Promise<boolean>;
+export declare function getEmbeddedRunByConversationId(conversationId: string): EmbeddedRunHandle | undefined;
+export declare function abortEmbeddedRun(conversationId: string): Promise<boolean>;
+export declare function queueEmbeddedSteer(conversationId: string, text: string): Promise<boolean>;

package/dist/src/agent/embedded/runs.js

@@ -1,23 +1,23 @@
 //#region src/agent/embedded/runs.ts
 var EmbeddedRunConflictError = class extends Error {
-	constructor(sessionKey, activeRunId) {
-		super(`Session '${sessionKey}' already has active embedded run '${activeRunId}'`);
-		this.sessionKey = sessionKey;
+	constructor(conversationId, activeRunId) {
+		super(`Session '${conversationId}' already has active embedded run '${activeRunId}'`);
+		this.conversationId = conversationId;
 		this.activeRunId = activeRunId;
 		this.name = "EmbeddedRunConflictError";
 	}
 };
 /** Owns one process-local execution lease per session while leaving steer/abort on the control plane. */
 var EmbeddedRunRegistry = class {
-	bySessionKey = /* @__PURE__ */ new Map();
+	byConversationId = /* @__PURE__ */ new Map();
 	acquire(identity) {
-		const active = this.bySessionKey.get(identity.sessionKey);
-		if (active) throw new EmbeddedRunConflictError(identity.sessionKey, active.runId);
+		const active = this.byConversationId.get(identity.conversationId);
+		if (active) throw new EmbeddedRunConflictError(identity.conversationId, active.runId);
 		const entry = {
 			...identity,
 			abortController: new AbortController()
 		};
-		this.bySessionKey.set(identity.sessionKey, entry);
+		this.byConversationId.set(identity.conversationId, entry);
 		return {
 			signal: entry.abortController.signal,
 			attach: async (session, abort) => {
@@ -29,42 +29,42 @@ var EmbeddedRunRegistry = class {
 				if (entry.abortController.signal.aborted) await abort();
 			},
 			release: () => {
-				if (this.bySessionKey.get(identity.sessionKey) === entry) this.bySessionKey.delete(identity.sessionKey);
+				if (this.byConversationId.get(identity.conversationId) === entry) this.byConversationId.delete(identity.conversationId);
 			}
 		};
 	}
-	getBySessionKey(sessionKey) {
-		return this.bySessionKey.get(sessionKey)?.handle;
+	getByConversationId(conversationId) {
+		return this.byConversationId.get(conversationId)?.handle;
 	}
-	async abortBySessionKey(sessionKey) {
-		const entry = this.bySessionKey.get(sessionKey);
+	async abortByConversationId(conversationId) {
+		const entry = this.byConversationId.get(conversationId);
 		if (!entry) return false;
 		entry.abortController.abort(/* @__PURE__ */ new Error("Embedded run aborted"));
 		if (entry.handle) await entry.handle.abort();
 		return true;
 	}
-	async steerBySessionKey(sessionKey, text) {
-		const handle = this.getBySessionKey(sessionKey);
+	async steerByConversationId(conversationId, text) {
+		const handle = this.getByConversationId(conversationId);
 		if (!handle) return false;
 		await handle.session.steer(text);
 		return true;
 	}
 	size() {
-		return this.bySessionKey.size;
+		return this.byConversationId.size;
 	}
 };
 const embeddedRunRegistry = new EmbeddedRunRegistry();
 function acquireEmbeddedRunLease(identity) {
 	return embeddedRunRegistry.acquire(identity);
 }
-function getEmbeddedRunBySessionKey(sessionKey) {
-	return embeddedRunRegistry.getBySessionKey(sessionKey);
+function getEmbeddedRunByConversationId(conversationId) {
+	return embeddedRunRegistry.getByConversationId(conversationId);
 }
-function abortEmbeddedRun(sessionKey) {
-	return embeddedRunRegistry.abortBySessionKey(sessionKey);
+function abortEmbeddedRun(conversationId) {
+	return embeddedRunRegistry.abortByConversationId(conversationId);
 }
-function queueEmbeddedSteer(sessionKey, text) {
-	return embeddedRunRegistry.steerBySessionKey(sessionKey, text);
+function queueEmbeddedSteer(conversationId, text) {
+	return embeddedRunRegistry.steerByConversationId(conversationId, text);
 }
 //#endregion
-export { EmbeddedRunConflictError, EmbeddedRunRegistry, abortEmbeddedRun, acquireEmbeddedRunLease, getEmbeddedRunBySessionKey, queueEmbeddedSteer };
+export { EmbeddedRunConflictError, EmbeddedRunRegistry, abortEmbeddedRun, acquireEmbeddedRunLease, getEmbeddedRunByConversationId, queueEmbeddedSteer };

package/dist/src/agent/embedded/session-runner.d.ts

@@ -5,7 +5,7 @@ import type { Model, Api } from '@earendil-works/pi-ai';
 import { type GuardedPiTranscriptManager } from './session-tool-result-guard.js';
 import type { EmbeddedTranscriptRuntime } from './transcript-runtime.js';
 export type EmbeddedRunnerFingerprintInput = {
-    sessionId: string;
+    transcriptId: string;
     workspaceDir: string;
     modelRef: string;
     toolNames: readonly string[];
@@ -16,7 +16,7 @@ export type EmbeddedRunnerFingerprintInput = {
 export declare function buildEmbeddedRunnerFingerprint(input: EmbeddedRunnerFingerprintInput): string;
 export type AcquireEmbeddedSessionRunnerParams = {
     runtimeId: string;
-    sessionId: string;
+    transcriptId: string;
     workspaceDir: string;
     model: Model<Api>;
     modelRef: string;

package/dist/src/agent/embedded/session-runner.js

@@ -19,7 +19,7 @@ function providerCredentialRevision(providerId) {
 function buildEmbeddedRunnerFingerprint(input) {
 	const tools = [...input.toolNames].sort().join("\0");
 	return createHash("sha256").update([
-		input.sessionId,
+		input.transcriptId,
 		input.workspaceDir,
 		input.modelRef,
 		tools,
@@ -88,7 +88,7 @@ var EmbeddedSessionRunnerPool = class {
 	async acquire(params) {
 		this.stats.acquires += 1;
 		const fingerprint = buildEmbeddedRunnerFingerprint({
-			sessionId: params.sessionId,
+			transcriptId: params.transcriptId,
 			workspaceDir: params.workspaceDir,
 			modelRef: params.modelRef,
 			toolNames: params.tools.map((t) => t.name),
@@ -157,10 +157,10 @@ var EmbeddedSessionRunnerPool = class {
 		}, "Embedded session runner evicted");
 	}
 	async createPooledRunner(params) {
-		const { runtimeId, sessionId, workspaceDir, model, thinkingLevel, tools, systemPrompt } = params;
+		const { runtimeId, transcriptId, workspaceDir, model, thinkingLevel, tools, systemPrompt } = params;
 		const settingsManager = createEmbeddedSettingsManager(workspaceDir);
 		const piSm = guardSessionManager(params.transcriptRuntime.openSessionManager(workspaceDir), {
-			sessionKey: params.transcriptRuntime.persistent ? runtimeId : void 0,
+			conversationId: params.transcriptRuntime.persistent ? runtimeId : void 0,
 			contextWindowTokens: model.contextWindow ?? 128e3,
 			transformMessageForPersistence: params.transcriptRuntime.persistent ? (message) => transformUserMessageForPersistence(runtimeId, message) : void 0
 		});
@@ -192,7 +192,7 @@ var EmbeddedSessionRunnerPool = class {
 		return {
 			runtimeId,
 			fingerprint: buildEmbeddedRunnerFingerprint({
-				sessionId,
+				transcriptId,
 				workspaceDir,
 				modelRef: params.modelRef,
 				toolNames,

package/dist/src/agent/embedded/session-tool-result-guard.d.ts

@@ -29,7 +29,7 @@ export type BeforeMessageWriteHookResult = {
 } | undefined;
 export interface ToolResultGuardOptions {
     /** Optional session key for transcript update broadcasts. */
-    sessionKey?: string;
+    conversationId?: string;
     /** Optional transform applied to any message before persistence. */
     transformMessageForPersistence?: (message: AgentMessage) => AgentMessage;
     /**
@@ -86,7 +86,7 @@ export declare function installSessionToolResultGuard(sessionManager: SessionMan
  */
 export declare function guardSessionManager(sessionManager: SessionManager, opts?: {
     agentId?: string;
-    sessionKey?: string;
+    conversationId?: string;
     config?: Config;
     contextWindowTokens?: number;
     allowSyntheticToolResults?: boolean;

package/dist/src/agent/embedded/session-tool-result-guard.js

@@ -31,7 +31,7 @@ function installSessionToolResultGuard(sessionManager, opts = {}) {
 function guardSessionManager(sessionManager, opts) {
 	if (typeof sessionManager.flushPendingToolResults === "function") return sessionManager;
 	const result = installSessionToolResultGuard(sessionManager, {
-		sessionKey: opts?.sessionKey,
+		conversationId: opts?.conversationId,
 		transformMessageForPersistence: opts?.transformMessageForPersistence,
 		allowSyntheticToolResults: opts?.allowSyntheticToolResults,
 		missingToolResultText: opts?.missingToolResultText,
@@ -81,7 +81,7 @@ function sanitizePersistedSessionDetail(value) {
 	const src = value;
 	const out = {};
 	for (const key of [
-		"sessionId",
+		"transcriptId",
 		"status",
 		"pid",
 		"startedAt",
@@ -110,7 +110,7 @@ function buildPersistedDetailsFallback(src, originalSize, sanitizedBytes) {
 		fallback.originalDetailKeys = firstEnumerableOwnKeys(src, 40);
 		for (const key of [
 			"status",
-			"sessionId",
+			"transcriptId",
 			"pid",
 			"exitCode",
 			"exitSignal",
@@ -151,7 +151,7 @@ function sanitizeToolResultDetailsForPersistence(details) {
 	};
 	for (const key of [
 		"status",
-		"sessionId",
+		"transcriptId",
 		"pid",
 		"startedAt",
 		"endedAt",
@@ -365,8 +365,8 @@ var ToolResultGuard = class {
 			if (!persisted) return;
 			const finalToolResult = capToolResultForPersistence(persisted, this.maxToolResultChars);
 			const result = this.originalAppend(finalToolResult);
-			if (this.opts.sessionKey) emitSessionTranscriptUpdate({
-				sessionKey: this.opts.sessionKey,
+			if (this.opts.conversationId) emitSessionTranscriptUpdate({
+				conversationId: this.opts.conversationId,
 				message: finalToolResult,
 				messageId: typeof result === "string" ? result : void 0
 			});
@@ -379,8 +379,8 @@ var ToolResultGuard = class {
 		const finalMessage = this.applyBeforeWriteHook(this.withActiveTurnId(this.persistMessage(nextMessage)));
 		if (!finalMessage) return;
 		const result = this.originalAppend(finalMessage);
-		if (this.opts.sessionKey) emitSessionTranscriptUpdate({
-			sessionKey: this.opts.sessionKey,
+		if (this.opts.conversationId) emitSessionTranscriptUpdate({
+			conversationId: this.opts.conversationId,
 			message: finalMessage,
 			messageId: typeof result === "string" ? result : void 0
 		});

package/dist/src/agent/embedded/sqlite-hydrating-session-manager.d.ts

@@ -4,7 +4,7 @@ import { SessionManager } from '@earendil-works/pi-coding-agent';
  * File persistence is disabled; writes flow through the tool-result guard into SQLite.
  */
 export declare function openSqliteHydratingSessionManager(params: {
-    sessionKey: string;
-    sessionId: string;
+    conversationId: string;
+    transcriptId: string;
     cwd: string;
 }): SessionManager;

package/dist/src/agent/embedded/sqlite-hydrating-session-manager.js

@@ -12,17 +12,17 @@ import { SessionManager } from "@earendil-works/pi-coding-agent";
 */
 function openSqliteHydratingSessionManager(params) {
 	requireXopcDatabase();
-	ensureSessionRecord(params.sessionKey, params.cwd);
-	const rows = loadTranscriptRowsForSession(params.sessionKey);
+	ensureSessionRecord(params.conversationId, params.cwd);
+	const rows = loadTranscriptRowsForSession(params.conversationId);
 	const sm = SessionManager.inMemory(params.cwd);
 	const entries = storedRowsToFileEntries({
-		sessionId: params.sessionId,
+		transcriptId: params.transcriptId,
 		cwd: params.cwd,
 		rows
 	});
 	const internal = sm;
 	internal.fileEntries = entries;
-	internal.sessionId = params.sessionId;
+	internal.sessionId = params.transcriptId;
 	internal.flushed = true;
 	internal._buildIndex();
 	repairAssistantUsageInSessionManager(sm);

package/dist/src/agent/embedded/transcript-runtime.d.ts

@@ -5,20 +5,20 @@ import { type CompactionExecutionOptions, type CompactionResult } from '../memor
 import type { SessionStore } from '../../session/store.js';
 export interface EmbeddedTranscriptRuntime {
     readonly runtimeId: string;
-    readonly sessionId: string;
+    readonly transcriptId: string;
     readonly persistent: boolean;
     openSessionManager(cwd: string): SessionManager;
     loadMessages(): Promise<AgentMessage[]>;
     compact(messages: AgentMessage[], model: Model<Api>, instructions?: string, force?: boolean, options?: CompactionExecutionOptions): Promise<CompactionResult>;
 }
 export declare function createSqliteTranscriptRuntime(params: {
-    sessionKey: string;
+    conversationId: string;
     sessionStore: SessionStore;
 }): Promise<EmbeddedTranscriptRuntime>;
 export declare class InMemoryTranscriptRuntime implements EmbeddedTranscriptRuntime {
     readonly persistent = false;
     readonly runtimeId: string;
-    readonly sessionId: string;
+    readonly transcriptId: string;
     private readonly sessionManager;
     private readonly compactor;
     private readonly compactionRows;
@@ -32,5 +32,6 @@ export declare class InMemoryTranscriptRuntime implements EmbeddedTranscriptRunt
     loadMessages(): Promise<AgentMessage[]>;
     captureBaseline(): void;
     loadConversationMessages(): AgentMessage[];
+    private sourceEntries;
     compact(_messages: AgentMessage[], model: Model<Api>, instructions?: string, force?: boolean, options?: CompactionExecutionOptions): Promise<CompactionResult>;
 }