@xopcai/xopc 0.0.196 → 0.0.199

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

@@ -1,10 +1,12 @@
 import { DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, resolveLiveToolResultMaxChars, truncateToolResultMessage } from "./tool-result-truncation.js";
 import { getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard } from "./session-tool-result-guard.js";
+import { acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, isEmbeddedSessionRunnerEnabled, resetEmbeddedSessionRunnerForTest } from "./session-runner.js";
+import { abortEmbeddedRun, getEmbeddedRunBySessionKey, queueEmbeddedSteer, registerEmbeddedRun } from "./runs.js";
 import { repairAssistantUsageInSessionManager } from "./session-manager-init.js";
 import { openSqliteHydratingSessionManager } from "./sqlite-hydrating-session-manager.js";
-import { acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, isEmbeddedSessionRunnerEnabled, resetEmbeddedSessionRunnerForTest, resolveEmbeddedTranscriptInputs } from "./session-runner.js";
-import { abortEmbeddedRun, getEmbeddedRunBySessionKey, queueEmbeddedSteer, registerEmbeddedRun } from "./runs.js";
+import { InMemoryTranscriptRuntime, createSqliteTranscriptRuntime } from "./transcript-runtime.js";
 import { runXopcEmbeddedTurn } from "./run-turn.js";
+import { getEmbeddedExecutionSession, runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { runEmbeddedTurnForSession } from "./run-for-session.js";
 import { CURRENT_SESSION_VERSION, PiTranscriptManager } from "./pi-transcript.js";
-export { CURRENT_SESSION_VERSION, DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, PiTranscriptManager, abortEmbeddedRun, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedRunBySessionKey, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard, isEmbeddedSessionRunnerEnabled, openSqliteHydratingSessionManager, queueEmbeddedSteer, registerEmbeddedRun, repairAssistantUsageInSessionManager, resetEmbeddedSessionRunnerForTest, resolveEmbeddedTranscriptInputs, resolveLiveToolResultMaxChars, runEmbeddedTurnForSession, runXopcEmbeddedTurn, truncateToolResultMessage };
+export { CURRENT_SESSION_VERSION, DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, InMemoryTranscriptRuntime, PiTranscriptManager, abortEmbeddedRun, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, createSqliteTranscriptRuntime, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedExecutionSession, getEmbeddedRunBySessionKey, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard, isEmbeddedSessionRunnerEnabled, openSqliteHydratingSessionManager, queueEmbeddedSteer, registerEmbeddedRun, repairAssistantUsageInSessionManager, resetEmbeddedSessionRunnerForTest, resolveLiveToolResultMaxChars, runEmbeddedTurnForSession, runWithEmbeddedExecutionSession, runXopcEmbeddedTurn, truncateToolResultMessage };

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

@@ -2,13 +2,14 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
 import { wrapStreamFnForXopcExtensions } from "./xopc-stream-bridge.js";
-import { acquireEmbeddedSessionRunner, resolveEmbeddedTranscriptInputs } from "./session-runner.js";
+import { acquireEmbeddedSessionRunner } from "./session-runner.js";
 import { getAssistantTurnErrorMessage, isAssistantTurnAborted, isAssistantTurnFailed, maybeRetryTurnAfterTransientLlmFailure, stripTrailingErrorAssistantMessages } from "../orchestration/llm-turn-retry.js";
 import { pruneToolResultsToFit } from "../memory/context-budget.js";
 import { abortEmbeddedRun, queueEmbeddedSteer, registerEmbeddedRun, unregisterEmbeddedRun } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
 import { detectToolLoops } from "../orchestration/loop-guard.js";
 import { tryApplySessionTranscriptHygiene } from "../transcript/transcript-hygiene.js";
+import { createSqliteTranscriptRuntime } from "./transcript-runtime.js";
 import { isContextOverflowError } from "../orchestration/context-overflow.js";
 //#region src/agent/embedded/run-turn.ts
 init_logger();
@@ -79,9 +80,9 @@ async function maybeRecoverContextOverflow(params) {
 		type: "compaction",
 		status: "started"
 	});
-	const result = await params.sessionStore.compact(params.sessionKey, messages, params.model, "Preserve the current pending user request verbatim and retain every fact needed to answer it.", true);
+	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);
 	if (!result.compacted) throw new Error(`Context overflow recovery could not find a safe compaction range: ${errorMessage}`);
-	params.agent.state.messages = await params.sessionStore.load(params.sessionKey);
+	params.agent.state.messages = await params.transcriptRuntime.loadMessages();
 	params.onEvent?.({
 		type: "compaction",
 		status: "completed",
@@ -97,19 +98,24 @@ async function runXopcEmbeddedTurn(params) {
 	const { sessionKey, runId, userMessage, model, tools, systemPrompt, thinkingLevel, workspaceDir, sessionStore, onEvent } = params;
 	const timeoutMs = params.timeoutMs || resolveAgentTurnTimeoutMs();
 	const resolvedModel = requireEmbeddedModel(model, params.modelRef);
-	const transcript = await resolveEmbeddedTranscriptInputs(sessionStore, sessionKey);
+	const transcriptRuntime = params.transcriptRuntime ?? (sessionStore ? await createSqliteTranscriptRuntime({
+		sessionKey,
+		sessionStore
+	}) : void 0);
+	if (!transcriptRuntime) throw new Error("Embedded run requires a transcript runtime");
 	let runner;
 	let unsubscribe;
 	try {
 		runner = await acquireEmbeddedSessionRunner({
-			sessionKey,
-			sessionId: transcript.sessionId,
+			runtimeId: transcriptRuntime.runtimeId,
+			sessionId: transcriptRuntime.sessionId,
 			workspaceDir,
 			model: resolvedModel,
 			modelRef: params.modelRef,
 			tools,
 			systemPrompt,
-			thinkingLevel: thinkingLevel ?? "medium"
+			thinkingLevel: thinkingLevel ?? "medium",
+			transcriptRuntime
 		});
 		const { session, reused } = runner;
 		runner.piSm.setActiveTurnId?.(runId);
@@ -187,7 +193,7 @@ async function runXopcEmbeddedTurn(params) {
 		});
 		const handle = {
 			sessionKey,
-			sessionId: transcript.sessionId,
+			sessionId: transcriptRuntime.sessionId,
 			runId,
 			session,
 			abort: async () => {
@@ -225,7 +231,7 @@ async function runXopcEmbeddedTurn(params) {
 					agent: session.agent,
 					model: resolvedModel,
 					sessionKey,
-					sessionStore,
+					transcriptRuntime,
 					onEvent
 				});
 			}, timeoutMs);

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

@@ -3,6 +3,7 @@ import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 import { type AgentSession } from '@earendil-works/pi-coding-agent';
 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;
     workspaceDir: string;
@@ -14,7 +15,7 @@ export type EmbeddedRunnerFingerprintInput = {
 };
 export declare function buildEmbeddedRunnerFingerprint(input: EmbeddedRunnerFingerprintInput): string;
 export type AcquireEmbeddedSessionRunnerParams = {
-    sessionKey: string;
+    runtimeId: string;
     sessionId: string;
     workspaceDir: string;
     model: Model<Api>;
@@ -22,6 +23,7 @@ export type AcquireEmbeddedSessionRunnerParams = {
     tools: AgentTool[];
     systemPrompt: string;
     thinkingLevel: ThinkingLevel;
+    transcriptRuntime: EmbeddedTranscriptRuntime;
 };
 export type AcquiredEmbeddedSessionRunner = {
     session: AgentSession;
@@ -45,9 +47,7 @@ export interface EmbeddedSessionRunnerPoolOptions {
     getIdleTtlMs?: () => number;
 }
 /**
- * Owns the per-session pool of pi `AgentSession` runners. The class is the supported,
- * injectable owner; {@link defaultEmbeddedSessionRunnerPool} keeps the historic
- * module-level free functions working until every caller is migrated to DI.
+ * Owns the per-runtime pool of pi `AgentSession` runners.
  */
 export declare class EmbeddedSessionRunnerPool {
     private readonly pool;
@@ -57,7 +57,7 @@ export declare class EmbeddedSessionRunnerPool {
     constructor(opts?: EmbeddedSessionRunnerPoolOptions);
     getStats(): Readonly<EmbeddedSessionRunnerPoolStats>;
     resetForTest(): void;
-    evict(sessionKey: string, reason?: string): void;
+    evict(runtimeId: string, reason?: string): void;
     evictAll(reason?: string): void;
     acquire(params: AcquireEmbeddedSessionRunnerParams): Promise<AcquiredEmbeddedSessionRunner>;
     private clearIdleTimer;
@@ -68,11 +68,6 @@ export declare class EmbeddedSessionRunnerPool {
 export declare const defaultEmbeddedSessionRunnerPool: EmbeddedSessionRunnerPool;
 export declare function getEmbeddedSessionRunnerStats(): Readonly<EmbeddedSessionRunnerPoolStats>;
 export declare function resetEmbeddedSessionRunnerForTest(): void;
-export declare function evictEmbeddedSessionRunner(sessionKey: string, reason?: string): void;
+export declare function evictEmbeddedSessionRunner(runtimeId: string, reason?: string): void;
 export declare function evictAllEmbeddedSessionRunners(reason?: string): void;
 export declare function acquireEmbeddedSessionRunner(params: AcquireEmbeddedSessionRunnerParams): Promise<AcquiredEmbeddedSessionRunner>;
-/** Resolve session identity used by embedded runner acquire and turn execution. */
-export declare function resolveEmbeddedTranscriptInputs(sessionStore: import('../../session/store.js').SessionStore, sessionKey: string): Promise<{
-    sessionId: string;
-    sessionKey: string;
-}>;

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

@@ -2,7 +2,6 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { guardSessionManager } from "./session-tool-result-guard.js";
 import { transformUserMessageForPersistence } from "../inbound/attachment-pipeline.js";
-import { openSqliteHydratingSessionManager } from "./sqlite-hydrating-session-manager.js";
 import { createEmbeddedModelRuntime, resolveEmbeddedProviderApiKeySync } from "./model-runtime.js";
 import { wrapStreamFnForXopcExtensions } from "./xopc-stream-bridge.js";
 import { xopcToolsToDefinitions } from "./xopc-tools-bridge.js";
@@ -46,9 +45,7 @@ function createEmbeddedSettingsManager(cwd) {
 	return sm;
 }
 /**
-* Owns the per-session pool of pi `AgentSession` runners. The class is the supported,
-* injectable owner; {@link defaultEmbeddedSessionRunnerPool} keeps the historic
-* module-level free functions working until every caller is migrated to DI.
+* Owns the per-runtime pool of pi `AgentSession` runners.
 */
 var EmbeddedSessionRunnerPool = class {
 	pool = /* @__PURE__ */ new Map();
@@ -80,13 +77,13 @@ var EmbeddedSessionRunnerPool = class {
 			evictions: 0
 		};
 	}
-	evict(sessionKey, reason = "explicit") {
-		const entry = this.pool.get(sessionKey);
+	evict(runtimeId, reason = "explicit") {
+		const entry = this.pool.get(runtimeId);
 		if (!entry) return;
-		this.disposePooledRunner(sessionKey, entry, reason);
+		this.disposePooledRunner(runtimeId, entry, reason);
 	}
 	evictAll(reason = "dispose_all") {
-		for (const sessionKey of [...this.pool.keys()]) this.evict(sessionKey, reason);
+		for (const runtimeId of [...this.pool.keys()]) this.evict(runtimeId, reason);
 	}
 	async acquire(params) {
 		this.stats.acquires += 1;
@@ -100,7 +97,7 @@ var EmbeddedSessionRunnerPool = class {
 			credentialRevision: providerCredentialRevision(params.model.provider)
 		});
 		const reuseEnabled = this.isEnabledFn();
-		const existing = this.pool.get(params.sessionKey);
+		const existing = this.pool.get(params.runtimeId);
 		let entry;
 		let reused = false;
 		if (reuseEnabled && existing && existing.fingerprint === fingerprint) {
@@ -111,13 +108,13 @@ var EmbeddedSessionRunnerPool = class {
 			this.stats.reuses += 1;
 			applySystemPromptOverrideToSession(entry.session, params.systemPrompt);
 			entry.session.agent.streamFunction = entry.baseStreamFn;
-			log.debug({ sessionKey: params.sessionKey }, "Reusing pooled embedded session runner");
+			log.debug({ runtimeId: params.runtimeId }, "Reusing pooled embedded session runner");
 		} else {
-			if (existing) this.disposePooledRunner(params.sessionKey, existing, "fingerprint_mismatch");
+			if (existing) this.disposePooledRunner(params.runtimeId, existing, "fingerprint_mismatch");
 			entry = await this.createPooledRunner(params);
-			this.pool.set(params.sessionKey, entry);
+			this.pool.set(params.runtimeId, entry);
 			this.stats.creates += 1;
-			log.debug({ sessionKey: params.sessionKey }, "Created embedded session runner");
+			log.debug({ runtimeId: params.runtimeId }, "Created embedded session runner");
 		}
 		return {
 			session: entry.session,
@@ -125,11 +122,11 @@ var EmbeddedSessionRunnerPool = class {
 			reused,
 			release: () => {
 				if (!this.isEnabledFn()) {
-					this.disposePooledRunner(params.sessionKey, entry, "runner_disabled");
+					this.disposePooledRunner(params.runtimeId, entry, "runner_disabled");
 					return;
 				}
 				entry.lastUsedAt = Date.now();
-				this.scheduleIdleEviction(params.sessionKey, entry);
+				this.scheduleIdleEviction(params.runtimeId, entry);
 			}
 		};
 	}
@@ -139,37 +136,33 @@ var EmbeddedSessionRunnerPool = class {
 			entry.idleTimer = null;
 		}
 	}
-	scheduleIdleEviction(sessionKey, entry) {
+	scheduleIdleEviction(runtimeId, entry) {
 		this.clearIdleTimer(entry);
 		const ttlMs = this.getIdleTtlMsFn();
 		entry.idleTimer = setTimeout(() => {
-			if (this.pool.get(sessionKey) === entry) this.disposePooledRunner(sessionKey, entry, "idle_ttl");
+			if (this.pool.get(runtimeId) === entry) this.disposePooledRunner(runtimeId, entry, "idle_ttl");
 		}, ttlMs);
 		entry.idleTimer.unref?.();
 	}
-	disposePooledRunner(sessionKey, entry, reason) {
+	disposePooledRunner(runtimeId, entry, reason) {
 		this.clearIdleTimer(entry);
-		this.pool.delete(sessionKey);
+		this.pool.delete(runtimeId);
 		this.stats.evictions += 1;
 		try {
 			entry.piSm.flushPendingToolResults?.();
 		} catch {}
 		log.debug({
-			sessionKey,
+			runtimeId,
 			reason
 		}, "Embedded session runner evicted");
 	}
 	async createPooledRunner(params) {
-		const { sessionKey, sessionId, workspaceDir, model, thinkingLevel, tools, systemPrompt } = params;
+		const { runtimeId, sessionId, workspaceDir, model, thinkingLevel, tools, systemPrompt } = params;
 		const settingsManager = createEmbeddedSettingsManager(workspaceDir);
-		const piSm = guardSessionManager(openSqliteHydratingSessionManager({
-			sessionKey,
-			sessionId,
-			cwd: workspaceDir
-		}), {
-			sessionKey,
+		const piSm = guardSessionManager(params.transcriptRuntime.openSessionManager(workspaceDir), {
+			sessionKey: params.transcriptRuntime.persistent ? runtimeId : void 0,
 			contextWindowTokens: model.contextWindow ?? 128e3,
-			transformMessageForPersistence: (message) => transformUserMessageForPersistence(sessionKey, message)
+			transformMessageForPersistence: params.transcriptRuntime.persistent ? (message) => transformUserMessageForPersistence(runtimeId, message) : void 0
 		});
 		const toolDefs = xopcToolsToDefinitions(tools);
 		const toolNames = tools.map((t) => t.name);
@@ -197,7 +190,7 @@ var EmbeddedSessionRunnerPool = class {
 		const baseStreamFn = wrapStreamFnForXopcExtensions(session.agent.streamFunction);
 		session.agent.streamFunction = baseStreamFn;
 		return {
-			sessionKey,
+			runtimeId,
 			fingerprint: buildEmbeddedRunnerFingerprint({
 				sessionId,
 				workspaceDir,
@@ -223,8 +216,8 @@ function getEmbeddedSessionRunnerStats() {
 function resetEmbeddedSessionRunnerForTest() {
 	defaultEmbeddedSessionRunnerPool.resetForTest();
 }
-function evictEmbeddedSessionRunner(sessionKey, reason = "explicit") {
-	defaultEmbeddedSessionRunnerPool.evict(sessionKey, reason);
+function evictEmbeddedSessionRunner(runtimeId, reason = "explicit") {
+	defaultEmbeddedSessionRunnerPool.evict(runtimeId, reason);
 }
 function evictAllEmbeddedSessionRunners(reason = "dispose_all") {
 	defaultEmbeddedSessionRunnerPool.evictAll(reason);
@@ -232,9 +225,5 @@ function evictAllEmbeddedSessionRunners(reason = "dispose_all") {
 function acquireEmbeddedSessionRunner(params) {
 	return defaultEmbeddedSessionRunnerPool.acquire(params);
 }
-/** Resolve session identity used by embedded runner acquire and turn execution. */
-async function resolveEmbeddedTranscriptInputs(sessionStore, sessionKey) {
-	return sessionStore.resolveTranscriptPath(sessionKey);
-}
 //#endregion
-export { EmbeddedSessionRunnerPool, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, defaultEmbeddedSessionRunnerPool, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, isEmbeddedSessionRunnerEnabled, resetEmbeddedSessionRunnerForTest, resolveEmbeddedTranscriptInputs };
+export { EmbeddedSessionRunnerPool, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, defaultEmbeddedSessionRunnerPool, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, isEmbeddedSessionRunnerEnabled, resetEmbeddedSessionRunnerForTest };

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

@@ -0,0 +1,35 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+import type { Api, Model } from '@earendil-works/pi-ai';
+import { type CompactionExecutionOptions, type CompactionResult } from '../memory/compaction.js';
+import type { SessionStore } from '../../session/store.js';
+export interface EmbeddedTranscriptRuntime {
+    readonly runtimeId: string;
+    readonly sessionId: 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;
+    sessionStore: SessionStore;
+}): Promise<EmbeddedTranscriptRuntime>;
+export declare class InMemoryTranscriptRuntime implements EmbeddedTranscriptRuntime {
+    readonly persistent = false;
+    readonly runtimeId: string;
+    readonly sessionId: string;
+    private readonly sessionManager;
+    private readonly compactor;
+    private baselineEntryCount;
+    constructor(params: {
+        runtimeId: string;
+        cwd: string;
+        initialMessages?: readonly AgentMessage[];
+    });
+    openSessionManager(_cwd: string): SessionManager;
+    loadMessages(): Promise<AgentMessage[]>;
+    captureBaseline(): void;
+    loadConversationMessages(): AgentMessage[];
+    compact(messages: AgentMessage[], model: Model<Api>, instructions?: string, force?: boolean, options?: CompactionExecutionOptions): Promise<CompactionResult>;
+}

package/dist/src/agent/embedded/transcript-runtime.js

@@ -0,0 +1,66 @@
+import { SessionCompactor } from "../memory/compaction.js";
+import { openSqliteHydratingSessionManager } from "./sqlite-hydrating-session-manager.js";
+import crypto from "node:crypto";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+//#region src/agent/embedded/transcript-runtime.ts
+async function createSqliteTranscriptRuntime(params) {
+	const identity = await params.sessionStore.resolveTranscriptPath(params.sessionKey);
+	return {
+		runtimeId: params.sessionKey,
+		sessionId: identity.sessionId,
+		persistent: true,
+		openSessionManager: (cwd) => openSqliteHydratingSessionManager({
+			sessionKey: params.sessionKey,
+			sessionId: identity.sessionId,
+			cwd
+		}),
+		loadMessages: () => params.sessionStore.load(params.sessionKey),
+		compact: (messages, model, instructions, force, options) => params.sessionStore.compact(params.sessionKey, messages, model, instructions, force, options)
+	};
+}
+var InMemoryTranscriptRuntime = class {
+	persistent = false;
+	runtimeId;
+	sessionId;
+	sessionManager;
+	compactor = new SessionCompactor();
+	baselineEntryCount = 0;
+	constructor(params) {
+		this.runtimeId = params.runtimeId;
+		this.sessionId = crypto.randomUUID();
+		this.sessionManager = SessionManager.inMemory(params.cwd, { id: this.sessionId });
+		for (const message of params.initialMessages ?? []) if (message.role === "compactionSummary") this.sessionManager.appendCustomMessageEntry("side-chat-parent-compaction", `The parent conversation was compacted into this summary:\n\n${message.summary}`, false);
+		else if (message.role === "branchSummary") this.sessionManager.appendCustomMessageEntry("side-chat-parent-branch", `The parent conversation includes this branch summary:\n\n${message.summary}`, false);
+		else this.sessionManager.appendMessage(message);
+		this.captureBaseline();
+	}
+	openSessionManager(_cwd) {
+		return this.sessionManager;
+	}
+	async loadMessages() {
+		return [...this.sessionManager.buildSessionContext().messages];
+	}
+	captureBaseline() {
+		this.baselineEntryCount = this.sessionManager.getBranch().length;
+	}
+	loadConversationMessages() {
+		return this.sessionManager.getBranch().slice(this.baselineEntryCount).flatMap((entry) => entry.type === "message" ? [entry.message] : []);
+	}
+	async compact(messages, model, instructions, force, options) {
+		const result = await this.compactor.compact(messages, model, instructions, force, options);
+		if (!result.compacted) return result;
+		const firstKept = this.sessionManager.getBranch().filter((entry) => entry.type === "message")[result.firstKeptIndex];
+		if (!firstKept) return {
+			...result,
+			compacted: false
+		};
+		this.sessionManager.appendCompaction(result.summary, firstKept.id, result.tokensBefore, {
+			plannerVersion: result.plannerVersion,
+			summaryModelRef: result.summaryModelRef,
+			qualityAudit: result.qualityAudit
+		});
+		return result;
+	}
+};
+//#endregion
+export { InMemoryTranscriptRuntime, createSqliteTranscriptRuntime };

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

@@ -1,6 +1,7 @@
 import type { AgentMessage, AgentToolResult, ThinkingLevel } from '@earendil-works/pi-agent-core';
 import type { AssistantMessageEvent, Model, Api, CacheRetention, ImageContent } from '@earendil-works/pi-ai';
 import type { SessionStore } from '../../session/store.js';
+import type { EmbeddedTranscriptRuntime } from './transcript-runtime.js';
 export type EmbeddedStreamEvent = {
     type: 'agent_start';
     runId?: string;
@@ -93,7 +94,8 @@ export type RunXopcEmbeddedTurnParams = {
     thinkingLevel?: ThinkingLevel;
     cacheRetention?: CacheRetention;
     workspaceDir: string;
-    sessionStore: SessionStore;
+    sessionStore?: SessionStore;
+    transcriptRuntime?: EmbeddedTranscriptRuntime;
     timeoutMs: number;
     abortSignal?: AbortSignal;
     onEvent?: (event: EmbeddedStreamEvent) => void;

package/dist/src/agent/service.d.ts

@@ -1,7 +1,10 @@
+import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 import type { MessageBus } from '../infra/bus/index.js';
 import { type Config } from '../config/schema.js';
 import type { ChannelManager } from '../channels/manager.js';
 import { SessionStore } from '../session/index.js';
+import type { EmbeddedStreamEvent, RunXopcEmbeddedTurnResult } from './embedded/types.js';
+import type { EmbeddedTranscriptRuntime } from './embedded/transcript-runtime.js';
 import { OutboundCoordinator } from './messaging/index.js';
 import { TurnDispatcher } from './inbound/turn-dispatcher.js';
 import { SessionConfigService, SessionHydrator, SessionInspector } from './session/index.js';
@@ -114,6 +117,18 @@ export declare class AgentService {
     refreshUserProfileContext(): void;
     getMemoryManager(): import("./memory/manager.js").MemoryManager;
     getModelForSession(sessionKey: string): string;
+    /** Run a full tool-capable turn against a caller-owned, non-persistent transcript. */
+    runEphemeralTurn(params: {
+        executionSessionKey: string;
+        parentSessionKey: string;
+        runId: string;
+        content: string;
+        modelRef: string;
+        thinkingLevel?: ThinkingLevel;
+        transcriptRuntime: EmbeddedTranscriptRuntime;
+        abortSignal?: AbortSignal;
+        onEvent?: (event: EmbeddedStreamEvent) => void;
+    }): Promise<RunXopcEmbeddedTurnResult>;
     switchModelForSession(sessionKey: string, modelId: string): Promise<boolean>;
     /**
      * Clears per-session model override so the next turn uses the configured agent default

package/dist/src/agent/service.js

@@ -6,9 +6,11 @@ import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
 import { extractProfileAgentId } from "../config/agent-profile.js";
+import { init_providers, resolveModel } from "../providers/index.js";
 import { extractTextContent } from "./context/workspace.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
 import { getProjectForSession } from "../projects/workspace.js";
+import { resolveAgentTurnTimeoutMs } from "./orchestration/run-agent-turn-with-timeout.js";
 import { resolveResponseLanguageForSession } from "./prompt/response-language.js";
 import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "./skills/workspace-skills-dir.js";
 import { removeSkillsLockEntry } from "./skills/hub-lock.js";
@@ -42,6 +44,8 @@ import "./middleware/index.js";
 import { TurnDiffTracker } from "./coding/turn-diff-tracker.js";
 import { LifecycleManager } from "./lifecycle/manager.js";
 import "./lifecycle/index.js";
+import { runXopcEmbeddedTurn } from "./embedded/run-turn.js";
+import { runWithEmbeddedExecutionSession } from "./embedded/execution-context.js";
 import { MessageRouter } from "./messaging/message-router.js";
 import { CommandHandler } from "./messaging/command-handler.js";
 import { StreamManager } from "./messaging/stream-manager.js";
@@ -68,6 +72,7 @@ import { readFile } from "node:fs/promises";
 init_schema();
 init_logger();
 init_agent_scope();
+init_providers();
 const log = createLogger("AgentService");
 function assistantMessageText(message) {
 	const content = message.content;
@@ -231,6 +236,7 @@ var AgentService = class {
 			getNotesService: config.getNotesService,
 			getProjectService: config.getProjectService,
 			getLocalAppService: config.getLocalAppService,
+			dispatchTaskEvents: config.dispatchTaskEvents,
 			dispatchTaskRuns: config.dispatchTaskRuns,
 			getWorkflowRunService: config.getWorkflowRunService,
 			onSkillsUpdated: config.onSkillsUpdated,
@@ -563,6 +569,31 @@ var AgentService = class {
 	getModelForSession(sessionKey) {
 		return this.modelManager.getModelForSession(sessionKey);
 	}
+	/** Run a full tool-capable turn against a caller-owned, non-persistent transcript. */
+	async runEphemeralTurn(params) {
+		const agent = this.agentManager.getOrCreateAgent(params.parentSessionKey);
+		const workspaceDir = this.agentManager.getResolvedWorkspaceForSession(params.parentSessionKey);
+		const model = resolveModel(params.modelRef);
+		return runWithEmbeddedExecutionSession(params.executionSessionKey, () => runXopcEmbeddedTurn({
+			sessionKey: params.executionSessionKey,
+			runId: params.runId,
+			userMessage: {
+				role: "user",
+				content: params.content,
+				timestamp: Date.now()
+			},
+			model,
+			modelRef: params.modelRef,
+			tools: agent.state.tools,
+			systemPrompt: agent.state.systemPrompt ?? "",
+			thinkingLevel: params.thinkingLevel ?? agent.state.thinkingLevel,
+			workspaceDir,
+			transcriptRuntime: params.transcriptRuntime,
+			timeoutMs: resolveAgentTurnTimeoutMs(this.effectiveAppConfig(), params.parentSessionKey),
+			abortSignal: params.abortSignal,
+			onEvent: params.onEvent
+		}));
+	}
 	async switchModelForSession(sessionKey, modelId) {
 		if (!await this.modelManager.switchModelForSession(sessionKey, modelId)) return false;
 		await this.sessionConfigStore.update(sessionKey, { modelOverride: modelId });

package/dist/src/agent/service.types.d.ts

@@ -33,6 +33,7 @@ export interface AgentServiceConfig {
     getNotesService?: () => NotesService | undefined;
     getProjectService?: () => ProjectService | undefined;
     getLocalAppService?: () => LocalAppService | undefined;
+    dispatchTaskEvents?: () => void;
     dispatchTaskRuns?: () => void;
     /**
      * Gateway: reuse the gateway `SessionManager` store so web API and agent share one index + files.

package/dist/src/agent/tools/factory.d.ts

@@ -57,6 +57,8 @@ export interface ToolFactoryDeps {
     getNotesService?: () => NotesService | undefined;
     getProjectService?: () => ProjectService | undefined;
     getLocalAppService?: () => LocalAppService | undefined;
+    /** Gateway: publishes durable Task change notifications. */
+    dispatchTaskEvents?: () => void;
     /** Gateway: queues Task execution for xopc_use task start/resume/verify actions. */
     dispatchTaskRuns?: () => void;
     /** Gateway: starts persisted workflow runs (dedicated chat session per run). */

package/dist/src/agent/tools/factory.js

@@ -305,7 +305,7 @@ var AgentToolsFactory = class {
 			})] : [],
 			...this.deps.getAutomationService ? [createAutomationTool({ getAutomationService: this.deps.getAutomationService })] : [],
 			...browserEnabled && this.deps.getBrowserRecipeService ? [createBrowserRecipeTool({ getBrowserRecipeService: this.deps.getBrowserRecipeService })] : [],
-			...this.deps.getAutomationService || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.dispatchTaskRuns ? [createXopcUseTool({
+			...this.deps.getAutomationService || this.deps.getProjectService || this.deps.getNotesService || this.deps.getLocalAppService || this.deps.dispatchTaskEvents || this.deps.dispatchTaskRuns ? [createXopcUseTool({
 				getConfig: () => this.deps.getConfig?.(),
 				getCurrentAgentId: () => options.agentId,
 				getCurrentSessionKey: () => this.deps.getCurrentContext()?.sessionKey,
@@ -313,6 +313,7 @@ var AgentToolsFactory = class {
 				getNotesService: this.deps.getNotesService,
 				getProjectService: this.deps.getProjectService,
 				getLocalAppService: this.deps.getLocalAppService,
+				dispatchTaskEvents: this.deps.dispatchTaskEvents,
 				dispatchTaskRuns: this.deps.dispatchTaskRuns
 			})] : [],
 			...browserEnabled ? [createBrowserUseTool({

package/dist/src/agent/tools/xopc-use-tool.d.ts

@@ -26,6 +26,7 @@ export interface XopcUseToolDeps {
     getNotesService?: () => NotesService | undefined;
     getProjectService?: () => ProjectService | undefined;
     getLocalAppService?: () => LocalAppService | undefined;
+    dispatchTaskEvents?: () => void;
     dispatchTaskRuns?: () => void;
 }
 type XopcUseDetails = {