@xopcai/xopc 0.0.321 → 0.0.323

package/dist/src/local-apps/service.js

@@ -11,11 +11,14 @@ import { slugifyProjectName } from "../projects/project-store.js";
 import { CapabilityError } from "../capabilities/runtime/errors.js";
 import { DomainOutboxDispatcher } from "../infra/domain-outbox-dispatcher.js";
 import { validateLocalAppCapabilityContracts } from "./capabilities/contracts.js";
+import { buildLocalAppFixGuidance } from "./fix-guidance.js";
 import { readLocalAppAcceptanceConfig } from "./acceptance.js";
+import { hashLocalAppDirectory, localAppFileHashes, shouldCopyLocalAppPath } from "./artifact-files.js";
 import { LOCAL_APP_RUNTIME_ENTRY, LOCAL_APP_RUNTIME_SOURCE } from "./runtime-entry.js";
 import { readLocalAppPermissions, scaffoldLocalApp } from "./scaffold.js";
+import { LocalAppSnapshotStore } from "./snapshot-store.js";
 import { withLocalAppReleaseLock } from "./release-lock.js";
-import { basename, join, relative, resolve, sep } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 //#region src/local-apps/service.ts
@@ -25,7 +28,6 @@ init_logger();
 init_transaction();
 init_operation_context();
 const log = createLogger("LocalApps");
-const RELEASE_COPY_EXCLUDED_NAMES = new Set([".git", "node_modules"]);
 const UI_ONLY_PERMISSIONS = new Set([
 	"theme",
 	"storage",
@@ -85,40 +87,6 @@ function removeExtensionActivation(config, extensionId) {
 		}
 	};
 }
-function shouldCopyReleasePath(source) {
-	return !RELEASE_COPY_EXCLUDED_NAMES.has(basename(source));
-}
-function hashDirectory(root) {
-	const hash = createHash("sha256");
-	const visit = (dir) => {
-		const entries = readdirSync(dir, { withFileTypes: true }).filter((entry) => !RELEASE_COPY_EXCLUDED_NAMES.has(entry.name)).toSorted((a, b) => a.name.localeCompare(b.name));
-		for (const entry of entries) {
-			const path = join(dir, entry.name);
-			const rel = relative(root, path);
-			hash.update(rel);
-			if (entry.isDirectory()) visit(path);
-			else if (entry.isFile()) hash.update(readFileSync(path));
-			else throw new Error(`Unsupported release entry: ${rel}`);
-		}
-	};
-	visit(root);
-	return hash.digest("hex");
-}
-function fileHashes(root) {
-	const hashes = /* @__PURE__ */ new Map();
-	const visit = (dir) => {
-		const entries = readdirSync(dir, { withFileTypes: true }).filter((entry) => !RELEASE_COPY_EXCLUDED_NAMES.has(entry.name)).toSorted((a, b) => a.name.localeCompare(b.name));
-		for (const entry of entries) {
-			const path = join(dir, entry.name);
-			const rel = relative(root, path);
-			if (entry.isDirectory()) visit(path);
-			else if (entry.isFile()) hashes.set(rel, createHash("sha256").update(readFileSync(path)).digest("hex"));
-			else throw new Error(`Unsupported release entry: ${rel}`);
-		}
-	};
-	visit(root);
-	return hashes;
-}
 function changedFiles(current, active) {
 	const paths = new Set([...current.keys(), ...active.keys()]);
 	const changes = [];
@@ -169,9 +137,11 @@ function validateLocalAppPackage(root, extensionId) {
 	const html = readFileSync(join(root, manifest.ui.main), "utf8");
 	if (/<script\b(?![^>]*\bsrc=)[^>]*>/i.test(html)) throw new Error("Inline scripts are blocked in local app previews");
 	if (/(?:src|href)\s*=\s*["']https?:\/\//i.test(html)) throw new Error("Remote scripts, styles, and frames are blocked in Phase 1 local apps");
+	const acceptance = readLocalAppAcceptanceConfig(root);
 	return {
 		manifestJson,
-		acceptanceScenarios: readLocalAppAcceptanceConfig(root).scenarios.map((scenario) => ({
+		entryPath: manifest.ui.main,
+		acceptanceScenarios: acceptance.scenarios.map((scenario) => ({
 			id: scenario.id,
 			name: scenario.name,
 			stepCount: scenario.steps.length
@@ -179,9 +149,10 @@ function validateLocalAppPackage(root, extensionId) {
 	};
 }
 var LocalAppService = class {
-	constructor(options, store = new LocalAppStore()) {
+	constructor(options, store = new LocalAppStore(), snapshots = new LocalAppSnapshotStore()) {
 		this.options = options;
 		this.store = store;
+		this.snapshots = snapshots;
 	}
 	recoveryRoot() {
 		return join(resolveStateDir(), "local-apps", "pending-releases");
@@ -208,13 +179,13 @@ var LocalAppService = class {
 				const release = app.activeReleaseId ? this.store.getRelease(id, app.activeReleaseId) : null;
 				if (!release || resolve(release.artifactPath) !== resolve(this.releaseRoot(id), `v${release.version}`)) throw new Error(`Local app recovery release is unavailable: ${id}`);
 				validateLocalAppPackage(release.artifactPath, app.extensionId);
-				if (hashDirectory(release.artifactPath) !== release.sourceHash) throw new Error(`Local app recovery integrity check failed: ${id}`);
+				if (hashLocalAppDirectory(release.artifactPath) !== release.sourceHash) throw new Error(`Local app recovery integrity check failed: ${id}`);
 				const staging = mkdtempSync(join(extensionsDir, ".local-app-recover-"));
 				try {
 					const replacement = join(staging, app.extensionId);
 					cpSync(release.artifactPath, replacement, {
 						recursive: true,
-						filter: shouldCopyReleasePath
+						filter: shouldCopyLocalAppPath
 					});
 					rmSync(target, {
 						recursive: true,
@@ -266,7 +237,7 @@ var LocalAppService = class {
 		if (!app || !token) return null;
 		return {
 			...app,
-			previewUrl: `/api/local-apps/preview/${token}/ui/index.html`,
+			draftPreviewUrl: `/api/local-apps/preview/${token}/draft/ui/index.html`,
 			permissions: readLocalAppPermissions(app.workspaceRoot),
 			releases: this.store.listReleases(id).map(({ artifactPath: _artifactPath, manifestJson: _manifestJson, ...release }) => release),
 			acceptanceRuns: this.store.listAcceptanceRuns(id)
@@ -322,6 +293,16 @@ var LocalAppService = class {
 		});
 	}
 	create(input) {
+		return this.createInternal(input);
+	}
+	createFromPreview(input) {
+		return this.createInternal(input, {
+			markup: input.markup,
+			styles: input.styles,
+			script: input.script
+		});
+	}
+	createInternal(input, uiSource) {
 		const name = requireText(input.name, "App name");
 		const idea = requireText(input.idea, "App idea");
 		const suffix = randomBytes(4).toString("hex");
@@ -329,13 +310,23 @@ var LocalAppService = class {
 		const workspaceRoot = join(this.options.workspaceRoot, "local-apps", extensionId);
 		const previewToken = randomBytes(24).toString("base64url");
 		mkdirSync(workspaceRoot, { recursive: true });
-		scaffoldLocalApp({
-			workspaceRoot,
-			extensionId,
-			name,
-			idea,
-			description: input.description?.trim() || void 0
-		});
+		try {
+			scaffoldLocalApp({
+				workspaceRoot,
+				extensionId,
+				name,
+				idea,
+				description: input.description?.trim() || void 0,
+				uiSource
+			});
+			validateLocalAppPackage(workspaceRoot, extensionId);
+		} catch (error) {
+			rmSync(workspaceRoot, {
+				recursive: true,
+				force: true
+			});
+			throw error;
+		}
 		const project = this.options.projects.create({
 			name,
 			slug: extensionId,
@@ -361,7 +352,7 @@ var LocalAppService = class {
 		});
 		return this.get(app.id);
 	}
-	resolvePreview(previewToken) {
+	resolveDraftPreview(previewToken) {
 		const app = this.store.findByPreviewToken(previewToken);
 		if (!app) return null;
 		return {
@@ -370,34 +361,42 @@ var LocalAppService = class {
 			uiRoot: app.workspaceRoot
 		};
 	}
-	validate(id) {
-		const app = this.store.get(id);
-		if (!app) throw new Error("Local app not found");
+	resolveSnapshotPreview(previewToken, sourceHash) {
+		const app = this.store.findByPreviewToken(previewToken);
+		if (!app) return null;
+		const uiRoot = this.snapshots.packageRoot(app.id, sourceHash);
+		return uiRoot ? {
+			app,
+			previewToken,
+			uiRoot
+		} : null;
+	}
+	validateRoot(app, root, knownSourceHash, checkedAt = Date.now()) {
 		const issues = [];
 		let manifestJson;
 		let acceptanceScenarios = [];
-		let sourceHash;
+		let sourceHash = knownSourceHash;
 		let currentFiles = /* @__PURE__ */ new Map();
 		try {
-			({manifestJson, acceptanceScenarios} = validateLocalAppPackage(app.workspaceRoot, app.extensionId));
-			currentFiles = fileHashes(app.workspaceRoot);
-			sourceHash = hashDirectory(app.workspaceRoot);
+			currentFiles = localAppFileHashes(root);
+			sourceHash ??= hashLocalAppDirectory(root);
+			({manifestJson, acceptanceScenarios} = validateLocalAppPackage(root, app.extensionId));
 		} catch (error) {
 			issues.push({
 				code: "package_validation_failed",
 				severity: "error",
-				message: error instanceof Error ? error.message : String(error)
+				message: (error instanceof Error ? error.message : String(error)).slice(0, 500)
 			});
 		}
 		const activeRelease = app.activeReleaseId ? this.store.getRelease(app.id, app.activeReleaseId) : null;
 		let files = [];
 		if (activeRelease?.artifactPath && existsSync(activeRelease.artifactPath) && currentFiles.size) try {
-			files = changedFiles(currentFiles, fileHashes(activeRelease.artifactPath));
+			files = changedFiles(currentFiles, localAppFileHashes(activeRelease.artifactPath));
 		} catch (error) {
 			issues.push({
 				code: "release_comparison_failed",
 				severity: "warning",
-				message: error instanceof Error ? error.message : String(error)
+				message: (error instanceof Error ? error.message : String(error)).slice(0, 500)
 			});
 		}
 		else if (!activeRelease && currentFiles.size) files = [...currentFiles.keys()].toSorted().map((path) => ({
@@ -408,7 +407,7 @@ var LocalAppService = class {
 		const activePermissions = permissionsFromManifestJson(activeRelease?.manifestJson);
 		return {
 			status: issues.some((issue) => issue.severity === "error") ? "failed" : "healthy",
-			checkedAt: Date.now(),
+			checkedAt,
 			sourceHash,
 			hasDraftChanges: activeRelease ? sourceHash !== activeRelease.sourceHash : true,
 			changedFiles: files.slice(0, 50),
@@ -423,6 +422,49 @@ var LocalAppService = class {
 			issues
 		};
 	}
+	validate(id) {
+		const app = this.store.get(id);
+		if (!app) throw new Error("Local app not found");
+		return this.validateRoot(app, app.workspaceRoot);
+	}
+	materializeSnapshot(id) {
+		const app = this.store.get(id);
+		const token = app ? this.store.getPreviewToken(id) : null;
+		if (!app || !token) throw new Error("Local app not found");
+		const stored = this.snapshots.materialize(app.id, app.workspaceRoot, (packageRoot, sourceHash, createdAt) => {
+			const validation = this.validateRoot(app, packageRoot, sourceHash, createdAt);
+			const packageResult = validation.status === "healthy" ? validateLocalAppPackage(packageRoot, app.extensionId) : null;
+			return {
+				appId: app.id,
+				sourceHash,
+				status: packageResult ? "ready" : "invalid",
+				createdAt,
+				...packageResult ? { entryPath: packageResult.entryPath } : {},
+				validation
+			};
+		});
+		return this.withSnapshotPreviewUrl(stored, token);
+	}
+	getSnapshot(id, sourceHash) {
+		const app = this.store.get(id);
+		const token = app ? this.store.getPreviewToken(id) : null;
+		if (!app || !token) return null;
+		const snapshot = this.snapshots.get(app.id, sourceHash);
+		return snapshot ? this.withSnapshotPreviewUrl(snapshot, token) : null;
+	}
+	withSnapshotPreviewUrl(snapshot, token) {
+		if (snapshot.status !== "ready" || !snapshot.entryPath) return snapshot;
+		const entryPath = snapshot.entryPath.split("/").map(encodeURIComponent).join("/");
+		return {
+			...snapshot,
+			previewUrl: `/api/local-apps/preview/${token}/snapshots/${snapshot.sourceHash}/${entryPath}`
+		};
+	}
+	getFixGuidance(id, input) {
+		const app = this.store.get(id);
+		if (!app) throw new CapabilityError("NOT_FOUND", "Local app not found");
+		return buildLocalAppFixGuidance(app, this.validate(id), input);
+	}
 	recordAcceptance(id, input) {
 		const app = this.store.get(id);
 		if (!app) throw new Error("Local app not found");
@@ -507,7 +549,7 @@ var LocalAppService = class {
 		try {
 			cpSync(input.artifactPath, staged, {
 				recursive: true,
-				filter: shouldCopyReleasePath
+				filter: shouldCopyLocalAppPath
 			});
 			if (existsSync(target)) {
 				renameSync(target, backup);
@@ -559,10 +601,10 @@ var LocalAppService = class {
 		try {
 			cpSync(app.workspaceRoot, stagedArtifact, {
 				recursive: true,
-				filter: shouldCopyReleasePath
+				filter: shouldCopyLocalAppPath
 			});
 			const { manifestJson } = validateLocalAppPackage(stagedArtifact, app.extensionId);
-			const sourceHash = hashDirectory(stagedArtifact);
+			const sourceHash = hashLocalAppDirectory(stagedArtifact);
 			if (this.store.getLatestAcceptanceForSource(app.id, sourceHash)?.status !== "passed") throw new Error("The current draft has not passed automatic acceptance");
 			renameSync(stagedArtifact, artifactPath);
 			artifactCreated = true;
@@ -612,7 +654,7 @@ var LocalAppService = class {
 		const release = this.store.getRelease(id, releaseId);
 		if (!release || !release.artifactPath || !existsSync(release.artifactPath)) throw new Error("Local app release artifact is unavailable");
 		validateLocalAppPackage(release.artifactPath, app.extensionId);
-		if (hashDirectory(release.artifactPath) !== release.sourceHash) throw new Error("Release artifact integrity check failed; rollback was not applied");
+		if (hashLocalAppDirectory(release.artifactPath) !== release.sourceHash) throw new Error("Release artifact integrity check failed; rollback was not applied");
 		await this.activateArtifact({
 			app,
 			artifactPath: release.artifactPath,

package/dist/src/local-apps/snapshot-store.d.ts

@@ -0,0 +1,8 @@
+import { type LocalAppPreviewSnapshot } from '@xopcai/gateway-contract';
+export declare class LocalAppSnapshotStore {
+    private appRoot;
+    private snapshotRoot;
+    get(appId: string, sourceHash: string): LocalAppPreviewSnapshot | null;
+    packageRoot(appId: string, sourceHash: string): string | null;
+    materialize(appId: string, sourceRoot: string, build: (packageRoot: string, sourceHash: string, createdAt: number) => LocalAppPreviewSnapshot): LocalAppPreviewSnapshot;
+}

package/dist/src/local-apps/snapshot-store.js

@@ -0,0 +1,68 @@
+import { resolveStateDir } from "../config/paths-state.js";
+import { LocalAppPreviewSnapshotSchema, LocalAppSourceHashSchema } from "../../packages/gateway-contract/src/local-apps.js";
+import { init_src } from "../../packages/gateway-contract/src/index.js";
+import { init_paths } from "../config/paths.js";
+import { hashLocalAppDirectory, shouldCopyLocalAppPath } from "./artifact-files.js";
+import { join } from "node:path";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+//#region src/local-apps/snapshot-store.ts
+init_src();
+init_paths();
+function assertAppId(appId) {
+	if (!/^[a-zA-Z0-9-]+$/.test(appId)) throw new Error("Invalid local app id");
+}
+var LocalAppSnapshotStore = class {
+	appRoot(appId) {
+		assertAppId(appId);
+		return join(resolveStateDir(), "local-apps", "snapshots", appId);
+	}
+	snapshotRoot(appId, sourceHash) {
+		LocalAppSourceHashSchema.parse(sourceHash);
+		return join(this.appRoot(appId), sourceHash);
+	}
+	get(appId, sourceHash) {
+		const root = this.snapshotRoot(appId, sourceHash);
+		const metadataPath = join(root, "snapshot.json");
+		const packageRoot = join(root, "package");
+		if (!existsSync(metadataPath) || !existsSync(packageRoot)) return null;
+		const snapshot = LocalAppPreviewSnapshotSchema.parse(JSON.parse(readFileSync(metadataPath, "utf8")));
+		if (snapshot.appId !== appId || snapshot.sourceHash !== sourceHash) throw new Error("Local app snapshot metadata does not match its path");
+		return snapshot;
+	}
+	packageRoot(appId, sourceHash) {
+		return this.get(appId, sourceHash)?.status === "ready" ? join(this.snapshotRoot(appId, sourceHash), "package") : null;
+	}
+	materialize(appId, sourceRoot, build) {
+		const appRoot = this.appRoot(appId);
+		mkdirSync(appRoot, { recursive: true });
+		const stagingRoot = mkdtempSync(join(appRoot, ".snapshot-"));
+		const stagedPackage = join(stagingRoot, "package");
+		try {
+			cpSync(sourceRoot, stagedPackage, {
+				recursive: true,
+				filter: shouldCopyLocalAppPath
+			});
+			const sourceHash = hashLocalAppDirectory(stagedPackage);
+			const existing = this.get(appId, sourceHash);
+			if (existing) return existing;
+			const snapshot = LocalAppPreviewSnapshotSchema.parse(build(stagedPackage, sourceHash, Date.now()));
+			writeFileSync(join(stagingRoot, "snapshot.json"), `${JSON.stringify(snapshot)}\n`, { mode: 384 });
+			const target = this.snapshotRoot(appId, sourceHash);
+			try {
+				renameSync(stagingRoot, target);
+			} catch (error) {
+				const raced = this.get(appId, sourceHash);
+				if (raced) return raced;
+				throw error;
+			}
+			return snapshot;
+		} finally {
+			if (existsSync(stagingRoot)) rmSync(stagingRoot, {
+				recursive: true,
+				force: true
+			});
+		}
+	}
+};
+//#endregion
+export { LocalAppSnapshotStore };

package/dist/src/local-apps/types.d.ts

@@ -1,40 +1,7 @@
-export type LocalAppStatus = 'preview_ready' | 'installed' | 'degraded';
-export type LocalAppInstallationState = 'not_installed' | 'installed';
-export type LocalAppReleaseHealth = 'healthy' | 'failed';
-export interface LocalAppRelease {
-    id: string;
-    appId: string;
-    version: number;
-    sourceHash: string;
-    healthStatus: LocalAppReleaseHealth;
-    createdAt: number;
-    activatedAt?: number;
-    isActive: boolean;
-}
-export interface LocalApp {
-    id: string;
-    extensionId: string;
-    projectId: string;
-    name: string;
-    description?: string;
-    idea: string;
-    status: LocalAppStatus;
-    workspaceRoot: string;
-    draftVersion: number;
-    activeVersion?: number;
-    activeReleaseId?: string;
-    installationState: LocalAppInstallationState;
-    enabled: boolean;
-    createdAt: number;
-    updatedAt: number;
-    installedAt?: number;
-}
-export interface LocalAppDetail extends LocalApp {
-    previewUrl: string;
-    permissions: string[];
-    releases: LocalAppRelease[];
-    acceptanceRuns: LocalAppAcceptanceRun[];
-}
+import type { LocalAppAcceptanceInput, LocalAppAcceptanceRun, LocalAppAcceptanceScenarioSummary, LocalAppChangedFile, LocalAppDetail, LocalAppDiagnostic, LocalAppDiagnosticPhase, LocalAppFixGuidance, LocalAppFixGuidanceInput, LocalAppInstallationState, LocalAppRecord, LocalAppRelease, LocalAppReleaseHealth, LocalAppStatus, LocalAppValidationIssue, LocalAppValidationResult } from '@xopcai/gateway-contract';
+export type LocalApp = LocalAppRecord;
+export type RecordLocalAppAcceptanceInput = LocalAppAcceptanceInput;
+export type { LocalAppAcceptanceRun, LocalAppAcceptanceScenarioSummary, LocalAppChangedFile, LocalAppDetail, LocalAppDiagnostic, LocalAppDiagnosticPhase, LocalAppFixGuidance, LocalAppFixGuidanceInput, LocalAppInstallationState, LocalAppRelease, LocalAppReleaseHealth, LocalAppStatus, LocalAppValidationIssue, LocalAppValidationResult, };
 export interface LocalAppUiGrant {
     granted: boolean;
     extensionId: string;
@@ -43,56 +10,6 @@ export interface LocalAppUiGrant {
     permissions: string[];
     grantedAt?: number;
 }
-export interface LocalAppAcceptanceCheck {
-    id: 'document' | 'content' | 'interaction' | 'criteria';
-    status: 'passed' | 'failed' | 'skipped';
-    message: string;
-}
-export interface LocalAppAcceptanceRun {
-    id: string;
-    appId: string;
-    sourceHash: string;
-    status: 'passed' | 'failed';
-    checks: LocalAppAcceptanceCheck[];
-    interactiveCount: number;
-    createdAt: number;
-}
-export interface RecordLocalAppAcceptanceInput {
-    sourceHash: string;
-    status: 'passed' | 'failed';
-    checks: LocalAppAcceptanceCheck[];
-    interactiveCount: number;
-}
-export interface LocalAppValidationIssue {
-    code: string;
-    severity: 'error' | 'warning';
-    message: string;
-}
-export interface LocalAppChangedFile {
-    path: string;
-    status: 'added' | 'modified' | 'deleted';
-}
-export interface LocalAppAcceptanceScenarioSummary {
-    id: string;
-    name: string;
-    stepCount: number;
-}
-export interface LocalAppValidationResult {
-    status: 'healthy' | 'failed';
-    checkedAt: number;
-    sourceHash?: string;
-    hasDraftChanges: boolean;
-    changedFiles: LocalAppChangedFile[];
-    changedFileCount: number;
-    permissions: string[];
-    permissionDelta: {
-        added: string[];
-        removed: string[];
-    };
-    acceptanceScenarioCount: number;
-    acceptanceScenarios: LocalAppAcceptanceScenarioSummary[];
-    issues: LocalAppValidationIssue[];
-}
 export interface CreateLocalAppInput {
     name: string;
     idea: string;

package/dist/src/session/client-history.d.ts

@@ -1,4 +1,4 @@
-import { type TurnOutcome } from '@xopcai/gateway-contract';
+import { type TurnOutcome, type UserTurnDocument } from '@xopcai/gateway-contract';
 import type { Message } from './types.js';
 import type { TranscriptStoredRow } from './session-context-for-llm.js';
 /** Transcript row for TUI and HTTP clients (flattened from persisted session messages). */
@@ -15,6 +15,7 @@ export interface ClientHistoryMessage {
     /** Whitelisted display metadata; never includes source snapshot text. */
     metadata?: {
         sourceContexts?: Array<{
+            refId?: string;
             kind: 'note' | 'task' | 'file' | 'session' | 'browser_tab' | 'browser_page' | 'mcp_resource';
             sourceId: string;
             version: string;
@@ -26,6 +27,7 @@ export interface ClientHistoryMessage {
             documentId?: string;
             fileKind?: 'file' | 'directory';
         }>;
+        userTurnDocument?: UserTurnDocument;
         turnOutcome?: TurnOutcome;
     };
     kind?: 'message' | 'compaction' | 'context' | 'bash' | 'custom' | 'branch';

package/dist/src/session/client-history.js

@@ -1,4 +1,5 @@
 import { parseTurnOutcome } from "../../packages/gateway-contract/src/turn-outcome.js";
+import { isUserTurnDocument } from "../../packages/gateway-contract/src/user-turn-document.js";
 import { init_src } from "../../packages/gateway-contract/src/index.js";
 import { stripRuntimeContextFromUserMessage } from "./user-message-display.js";
 import { buildTranscriptOutline } from "./transcript-outline.js";
@@ -6,13 +7,16 @@ import { buildTranscriptOutline } from "./transcript-outline.js";
 init_src();
 function sourceContextDisplayMetadata(metadata) {
 	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return void 0;
-	const rows = metadata.sourceContexts;
-	if (!Array.isArray(rows)) return void 0;
+	const record = metadata;
+	const rows = record.sourceContexts;
+	const userTurnDocument = isUserTurnDocument(record.userTurnDocument) ? record.userTurnDocument : void 0;
+	if (!Array.isArray(rows)) return userTurnDocument ? { userTurnDocument } : void 0;
 	const sourceContexts = rows.flatMap((value) => {
 		if (!value || typeof value !== "object" || Array.isArray(value)) return [];
 		const row = value;
 		if (row.kind !== "note" && row.kind !== "task" && row.kind !== "file" && row.kind !== "session" && row.kind !== "browser_tab" && row.kind !== "browser_page" && row.kind !== "mcp_resource" || typeof row.sourceId !== "string" || typeof row.version !== "string" || typeof row.title !== "string") return [];
 		return [{
+			...typeof row.refId === "string" ? { refId: row.refId } : {},
 			kind: row.kind,
 			sourceId: row.sourceId,
 			version: row.version,
@@ -25,7 +29,10 @@ function sourceContextDisplayMetadata(metadata) {
 			...row.kind === "file" && (row.fileKind === "file" || row.fileKind === "directory") ? { fileKind: row.fileKind } : {}
 		}];
 	});
-	return sourceContexts.length ? { sourceContexts } : void 0;
+	return sourceContexts.length || userTurnDocument ? {
+		...sourceContexts.length ? { sourceContexts } : {},
+		...userTurnDocument ? { userTurnDocument } : {}
+	} : void 0;
 }
 function flattenMessageContent(content) {
 	if (typeof content === "string") return content;

package/dist/src/session/index.d.ts

@@ -1,7 +1,7 @@
 export { SessionIndex, type SessionIndexConfig } from './manager.js';
 export { onSessionTranscriptUpdate, emitSessionTranscriptUpdate, type SessionTranscriptUpdate, } from './transcript-events.js';
 export { SessionStore } from './store.js';
-export type { SessionStoreOptions, ForkSessionAtTurnOptions, ForkSessionResult, } from './store.js';
+export type { SessionStoreOptions, ForkSessionAtTurnOptions, ForkSessionResult, CreateSessionFromRowsOptions, } from './store.js';
 export { SessionConfigStore, resolveThinkingLevel, resolveReasoningLevel, resolveVerboseLevel } from './config-store.js';
 export { DEFAULT_ACTIVITY_DETAIL_LEVEL, resolveConfiguredActivityDetailDefault, resolveEffectiveThinkingLevel, resolveEffectiveReasoningLevel, } from './thinking-resolve.js';
 export type { SessionAgentConfig } from './config-types.js';

package/dist/src/session/manager.d.ts

@@ -83,6 +83,10 @@ export declare class SessionIndex extends EventEmitter {
         conversationId: string;
         rowCount: number;
     }>;
+    createSessionFromRows(options: import('./store.js').CreateSessionFromRowsOptions): Promise<{
+        conversationId: string;
+        rowCount: number;
+    }>;
     forkSessionRows(sourceKey: string, targetKey: string, options?: {
         throughRow?: number;
     }): Promise<{

package/dist/src/session/manager.js

@@ -165,6 +165,12 @@ var SessionIndex = class extends EventEmitter$1 {
 		if (metadata) this.emit("sessionCreated", metadata);
 		return result;
 	}
+	async createSessionFromRows(options) {
+		const result = await this.store.createSessionFromRows(options);
+		const metadata = await this.store.getMetadata(result.conversationId);
+		if (metadata) this.emit("sessionCreated", metadata);
+		return result;
+	}
 	async forkSessionRows(sourceKey, targetKey, options = {}) {
 		const result = await this.store.forkSessionRows(sourceKey, targetKey, options);
 		const metadata = await this.store.getMetadata(result.conversationId);

package/dist/src/session/session-context-for-llm.d.ts

@@ -17,6 +17,16 @@ export interface XopcTranscriptContextEntry {
     data?: Record<string, unknown>;
     createdAt?: string;
 }
+/** Immutable hidden context captured when an ephemeral side chat becomes a session. */
+export interface XopcTranscriptSideChatOriginEntry {
+    type: 'side_chat_origin';
+    version: 1;
+    parentConversationId: string;
+    parentTranscriptId: string;
+    createdAt: string;
+    contentHash: string;
+    contextMessages: AgentMessage[];
+}
 /** Persisted-only row for replaying local shell executions in clients. */
 export interface XopcTranscriptBashExecutionEntry {
     role: 'bashExecution';
@@ -119,8 +129,9 @@ export interface XopcTranscriptSessionInfoEntry {
     name?: string;
     timestamp?: string | number;
 }
-export type TranscriptStoredRow = AgentMessage | XopcTranscriptContextEntry | XopcTranscriptBashExecutionEntry | XopcTranscriptCustomMessageEntry | XopcTranscriptCustomMessageFileEntry | XopcTranscriptCustomStateEntry | XopcTranscriptBranchSummaryEntry | XopcTranscriptCompactionSummaryEntry | XopcTranscriptCompactionEntry | XopcTranscriptLabelEntry | XopcTranscriptThinkingLevelChangeEntry | XopcTranscriptModelChangeEntry | XopcTranscriptSessionInfoEntry;
+export type TranscriptStoredRow = AgentMessage | XopcTranscriptContextEntry | XopcTranscriptSideChatOriginEntry | XopcTranscriptBashExecutionEntry | XopcTranscriptCustomMessageEntry | XopcTranscriptCustomMessageFileEntry | XopcTranscriptCustomStateEntry | XopcTranscriptBranchSummaryEntry | XopcTranscriptCompactionSummaryEntry | XopcTranscriptCompactionEntry | XopcTranscriptLabelEntry | XopcTranscriptThinkingLevelChangeEntry | XopcTranscriptModelChangeEntry | XopcTranscriptSessionInfoEntry;
 export declare function isTranscriptContextEntry(x: unknown): x is XopcTranscriptContextEntry;
+export declare function isTranscriptSideChatOriginEntry(x: unknown): x is XopcTranscriptSideChatOriginEntry;
 export declare function isTranscriptBashExecutionEntry(x: unknown): x is XopcTranscriptBashExecutionEntry;
 export declare function isTranscriptCustomMessageEntry(x: unknown): x is XopcTranscriptCustomMessageEntry | XopcTranscriptCustomMessageFileEntry;
 export declare function isTranscriptCustomStateEntry(x: unknown): x is XopcTranscriptCustomStateEntry;

package/dist/src/session/session-context-for-llm.js

@@ -6,6 +6,11 @@ function isTranscriptContextEntry(x) {
 	if (!x || typeof x !== "object") return false;
 	return x.kind === "context";
 }
+function isTranscriptSideChatOriginEntry(x) {
+	if (!x || typeof x !== "object") return false;
+	const row = x;
+	return row.type === "side_chat_origin" && row.version === 1 && typeof row.parentConversationId === "string" && typeof row.parentTranscriptId === "string" && typeof row.createdAt === "string" && typeof row.contentHash === "string" && Array.isArray(row.contextMessages) && row.contextMessages.every(isLikelyAgentMessage);
+}
 function isTranscriptBashExecutionEntry(x) {
 	if (!x || typeof x !== "object") return false;
 	return x.role === "bashExecution";
@@ -228,6 +233,10 @@ function sanitizeToolPairs(messages) {
 function transcriptRowsFromJsonArray(arr) {
 	const out = [];
 	for (const x of arr) {
+		if (isTranscriptSideChatOriginEntry(x)) {
+			out.push(x);
+			continue;
+		}
 		if (isTranscriptContextEntry(x)) {
 			out.push(x);
 			continue;
@@ -268,6 +277,11 @@ function transcriptRowsFromJsonArray(arr) {
 function buildSessionContextForLlm(rows) {
 	const out = [];
 	for (const r of rows) {
+		if (isTranscriptSideChatOriginEntry(r)) {
+			out.length = 0;
+			out.push(...r.contextMessages);
+			continue;
+		}
 		if (isTranscriptCompactionEntry(r)) {
 			out.length = 0;
 			out.push(...r.messages);
@@ -315,7 +329,7 @@ function buildSessionDisplayMessages(rows) {
 function mergeLlmMessagesPreservingContextRows(prevRows, llmMessages) {
 	let i = 0;
 	const out = [];
-	for (const r of prevRows) if (isTranscriptContextEntry(r) || isTranscriptBashExecutionEntry(r) || isTranscriptCustomMessageEntry(r) || isTranscriptCustomStateEntry(r) || isTranscriptSummaryMessageEntry(r) || isTranscriptLabelEntry(r) || isTranscriptMetadataEntry(r)) out.push(r);
+	for (const r of prevRows) if (isTranscriptContextEntry(r) || isTranscriptSideChatOriginEntry(r) || isTranscriptBashExecutionEntry(r) || isTranscriptCustomMessageEntry(r) || isTranscriptCustomStateEntry(r) || isTranscriptSummaryMessageEntry(r) || isTranscriptLabelEntry(r) || isTranscriptMetadataEntry(r)) out.push(r);
 	else if (i < llmMessages.length) {
 		out.push(llmMessages[i]);
 		i += 1;
@@ -340,4 +354,4 @@ var init_session_context_for_llm = __esmMin((() => {
 }));
 //#endregion
 init_session_context_for_llm();
-export { buildSessionContextForLlm, buildSessionDisplayMessages, init_session_context_for_llm, isRuntimeOnlyTranscriptMessage, isTranscriptBashExecutionEntry, isTranscriptCompactionEntry, isTranscriptContextEntry, isTranscriptCustomMessageEntry, isTranscriptCustomStateEntry, isTranscriptLabelEntry, isTranscriptMetadataEntry, isTranscriptSummaryMessageEntry, mergeLlmMessagesPreservingContextRows, transcriptRowsFromJsonArray };
+export { buildSessionContextForLlm, buildSessionDisplayMessages, init_session_context_for_llm, isRuntimeOnlyTranscriptMessage, isTranscriptBashExecutionEntry, isTranscriptCompactionEntry, isTranscriptContextEntry, isTranscriptCustomMessageEntry, isTranscriptCustomStateEntry, isTranscriptLabelEntry, isTranscriptMetadataEntry, isTranscriptSideChatOriginEntry, isTranscriptSummaryMessageEntry, mergeLlmMessagesPreservingContextRows, transcriptRowsFromJsonArray };