@xopcai/xopc 0.0.346 → 0.0.348

package/dist/src/backup/archive.js

@@ -0,0 +1,322 @@
+import { init_node_sqlite, requireNodeSqlite } from "../infra/node-sqlite.js";
+import { assertDatabaseOffline, init_conversation_backup } from "../storage/sqlite/migrations/conversation-backup.js";
+import { expandWorkspacePathString, init_workspace_path } from "../config/workspace-path.js";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { constants, createReadStream, createWriteStream } from "node:fs";
+import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, scryptSync } from "node:crypto";
+import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { pipeline } from "node:stream/promises";
+import { Transform } from "node:stream";
+//#region src/backup/archive.ts
+init_node_sqlite();
+init_conversation_backup();
+init_workspace_path();
+const FORMAT = "xopc-state-backup";
+const VERSION = 1;
+const OMIT_TOP_LEVEL = new Set([
+	"logs",
+	"cache",
+	"tools"
+]);
+const OMIT_FILES = new Set([
+	"pid",
+	"status.json",
+	"agent.sock",
+	"update.lock"
+]);
+const MAX_MANIFEST_BYTES = 32 * 1024 * 1024;
+function inside(candidate, root) {
+	const rel = relative(root, candidate);
+	return rel === "" || !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function safeRelativePath(value) {
+	if (!value || value.includes("\\") || value.includes("\0") || value.startsWith("/") || /^[A-Za-z]:/.test(value)) throw new Error(`Unsafe backup path: ${value}`);
+	if (value.split("/").some((segment) => !segment || segment === "." || segment === "..")) throw new Error(`Unsafe backup path: ${value}`);
+	return value;
+}
+function deriveKey(passphrase, salt) {
+	if (passphrase.length < 12) throw new Error("Backup passphrase must have at least 12 characters");
+	return scryptSync(passphrase, salt, 32, {
+		N: 32768,
+		r: 8,
+		p: 1,
+		maxmem: 64 * 1024 * 1024
+	});
+}
+function encryptBytes(plain, key) {
+	const nonce = randomBytes(12);
+	const cipher = createCipheriv("aes-256-gcm", key, nonce);
+	return {
+		data: Buffer.concat([cipher.update(plain), cipher.final()]),
+		nonce: nonce.toString("base64"),
+		tag: cipher.getAuthTag().toString("base64")
+	};
+}
+function decryptBytes(ciphertext, key, nonce, tag) {
+	const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(nonce, "base64"));
+	decipher.setAuthTag(Buffer.from(tag, "base64"));
+	return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+async function collectFiles(root) {
+	const files = [];
+	const excluded = [];
+	async function walk(directory, prefix = "") {
+		for (const item of await readdir(directory, { withFileTypes: true })) {
+			const rel = prefix ? `${prefix}/${item.name}` : item.name;
+			if (!prefix && (OMIT_TOP_LEVEL.has(item.name) || OMIT_FILES.has(item.name))) {
+				excluded.push(rel);
+				continue;
+			}
+			if (!prefix && /^xopc\.db(?:-wal|-shm|-journal)?$/.test(item.name)) {
+				if (item.name !== "xopc.db") excluded.push(rel);
+				continue;
+			}
+			const source = join(directory, item.name);
+			if (item.isSymbolicLink()) throw new Error(`Backup contains a symbolic link: ${rel}`);
+			if (item.isDirectory()) await walk(source, rel);
+			else if (item.isFile()) files.push(rel);
+			else throw new Error(`Backup contains an unsupported file type: ${rel}`);
+		}
+	}
+	await walk(root);
+	return {
+		files,
+		excluded
+	};
+}
+async function encryptFile(source, destination, key, path) {
+	const handle = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+	try {
+		const before = await handle.stat();
+		if (!before.isFile()) throw new Error(`Backup entry is not a regular file: ${path}`);
+		const nonce = randomBytes(12);
+		const cipher = createCipheriv("aes-256-gcm", key, nonce);
+		const digest = createHash("sha256");
+		let bytes = 0;
+		const hashStream = new Transform({ transform(chunk, _encoding, callback) {
+			bytes += chunk.length;
+			digest.update(chunk);
+			callback(null, chunk);
+		} });
+		await pipeline(handle.createReadStream({ autoClose: false }), hashStream, cipher, createWriteStream(destination, {
+			flags: "wx",
+			mode: 384
+		}));
+		const after = await handle.stat();
+		const current = await lstat(source);
+		if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || bytes !== before.size || !current.isFile() || before.ino !== current.ino || before.dev !== current.dev) throw new Error(`File changed during backup: ${path}`);
+		return {
+			path,
+			blob: basename(destination),
+			bytes,
+			sha256: digest.digest("hex"),
+			nonce: nonce.toString("base64"),
+			tag: cipher.getAuthTag().toString("base64"),
+			mode: before.mode & 511
+		};
+	} finally {
+		await handle.close();
+	}
+}
+async function readArchive(archivePath, passphrase) {
+	const rawHeader = await readFile(join(archivePath, "header.json"), "utf8");
+	const header = JSON.parse(rawHeader);
+	if (header.format !== FORMAT || header.version !== VERSION) throw new Error("Unsupported backup format");
+	const key = deriveKey(passphrase, Buffer.from(header.salt, "base64"));
+	const encrypted = await readFile(join(archivePath, "manifest.enc"));
+	if (encrypted.length > MAX_MANIFEST_BYTES) throw new Error("Backup manifest is too large");
+	const manifest = JSON.parse(decryptBytes(encrypted, key, header.manifestNonce, header.manifestTag).toString("utf8"));
+	if (manifest.format !== FORMAT || manifest.version !== VERSION || !Array.isArray(manifest.entries)) throw new Error("Invalid backup manifest");
+	const seen = /* @__PURE__ */ new Set();
+	for (const entry of manifest.entries) {
+		safeRelativePath(entry.path);
+		if (!/^[0-9a-f-]{36}\.enc$/.test(entry.blob) || seen.has(entry.path)) throw new Error("Invalid backup entry");
+		if (!Number.isSafeInteger(entry.bytes) || entry.bytes < 0 || !/^[0-9a-f]{64}$/.test(entry.sha256)) throw new Error("Invalid backup entry metadata");
+		seen.add(entry.path);
+	}
+	return {
+		manifest,
+		key
+	};
+}
+async function decryptEntry(archivePath, entry, key, destination) {
+	const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(entry.nonce, "base64"));
+	decipher.setAuthTag(Buffer.from(entry.tag, "base64"));
+	const hash = createHash("sha256");
+	let bytes = 0;
+	const check = new Transform({ transform(chunk, _encoding, callback) {
+		bytes += chunk.length;
+		hash.update(chunk);
+		callback(null, chunk);
+	} });
+	const sink = destination ? createWriteStream(destination, {
+		flags: "wx",
+		mode: 384
+	}) : new Transform({ transform(_chunk, _encoding, callback) {
+		callback();
+	} });
+	await pipeline(createReadStream(join(archivePath, "blobs", entry.blob)), decipher, check, sink);
+	if (bytes !== entry.bytes || hash.digest("hex") !== entry.sha256) throw new Error(`Backup checksum mismatch: ${entry.path}`);
+}
+async function createStateBackup(input) {
+	const root = resolve(input.stateDir);
+	const output = resolve(input.output);
+	if (inside(output, root)) throw new Error("Backup output must be outside the state directory");
+	if (!(await lstat(root)).isDirectory()) throw new Error("State path is not a directory");
+	const databasePath = join(root, "xopc.db");
+	if (!(await lstat(databasePath)).isFile()) throw new Error("State database not found");
+	assertDatabaseOffline(databasePath);
+	const { DatabaseSync, backup } = requireNodeSqlite();
+	const pathDb = new DatabaseSync(databasePath, { readOnly: true });
+	const configuredPaths = [...input.configuredPaths ?? []];
+	const configPath = resolve(input.configPath ?? join(root, "xopc.json"));
+	try {
+		if (inside(configPath, root)) {
+			const config = JSON.parse(await readFile(configPath, "utf8"));
+			if (Array.isArray(config.agents?.list)) configuredPaths.push(...config.agents.list.map((agent) => agent.workspace).filter((path) => typeof path === "string"));
+		}
+		if (pathDb.prepare("SELECT 1 AS present FROM sqlite_master WHERE type='table' AND name='agents'").get()) {
+			const rows = pathDb.prepare("SELECT workspace_override FROM agents WHERE deleted_at IS NULL AND workspace_override IS NOT NULL").all();
+			configuredPaths.push(...rows.map((row) => row.workspace_override));
+		}
+	} finally {
+		pathDb.close();
+	}
+	const external = [...new Set(configuredPaths.map((path) => resolve(expandWorkspacePathString(path))).filter((path) => !inside(path, root)))];
+	if (external.length) throw new Error(`External paths are not included in this backup: ${external.join(", ")}`);
+	const { files, excluded } = await collectFiles(root);
+	const salt = randomBytes(32);
+	const key = deriveKey(input.passphrase, salt);
+	const scratch = await mkdtemp(join(tmpdir(), "xopc-backup-"));
+	let archiveCreated = false;
+	try {
+		await mkdir(output, { mode: 448 });
+		archiveCreated = true;
+		await mkdir(join(output, "blobs"), { mode: 448 });
+		const snapshot = join(scratch, "xopc.db");
+		const source = new DatabaseSync(databasePath, { readOnly: true });
+		try {
+			await backup(source, snapshot);
+		} finally {
+			source.close();
+		}
+		const checked = new DatabaseSync(snapshot, { readOnly: true });
+		let schemaVersion = 0;
+		try {
+			if (checked.prepare("PRAGMA integrity_check").get().integrity_check !== "ok") throw new Error("Database snapshot failed integrity check");
+			schemaVersion = Number(checked.prepare("SELECT value FROM schema_meta WHERE key='schema_version'").get()?.value ?? 0);
+		} finally {
+			checked.close();
+		}
+		const entries = [];
+		for (const rel of ["xopc.db", ...files]) {
+			const sourcePath = rel === "xopc.db" ? snapshot : join(root, rel);
+			const blob = `${randomUUID()}.enc`;
+			entries.push(await encryptFile(sourcePath, join(output, "blobs", blob), key, rel));
+		}
+		const manifest = {
+			format: FORMAT,
+			version: VERSION,
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			schemaVersion,
+			entries,
+			excluded
+		};
+		const sealed = encryptBytes(Buffer.from(JSON.stringify(manifest)), key);
+		if (sealed.data.length > MAX_MANIFEST_BYTES) throw new Error("Backup manifest is too large");
+		await writeFile(join(output, "manifest.enc"), sealed.data, {
+			flag: "wx",
+			mode: 384
+		});
+		const header = {
+			format: FORMAT,
+			version: VERSION,
+			salt: salt.toString("base64"),
+			manifestNonce: sealed.nonce,
+			manifestTag: sealed.tag
+		};
+		await writeFile(join(output, "header.json"), `${JSON.stringify(header)}\n`, {
+			flag: "wx",
+			mode: 384
+		});
+		return manifest;
+	} catch (error) {
+		if (archiveCreated) await rm(output, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	} finally {
+		key.fill(0);
+		await rm(scratch, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function verifyStateBackup(archivePath, passphrase) {
+	const archive = resolve(archivePath);
+	const { manifest, key } = await readArchive(archive, passphrase);
+	const scratch = await mkdtemp(join(tmpdir(), "xopc-backup-verify-"));
+	try {
+		for (const entry of manifest.entries) await decryptEntry(archive, entry, key, entry.path === "xopc.db" ? join(scratch, "xopc.db") : void 0);
+		const { DatabaseSync } = requireNodeSqlite();
+		const db = new DatabaseSync(join(scratch, "xopc.db"), { readOnly: true });
+		try {
+			if (db.prepare("PRAGMA integrity_check").get().integrity_check !== "ok") throw new Error("Backup database failed integrity check");
+		} finally {
+			db.close();
+		}
+		return manifest;
+	} finally {
+		key.fill(0);
+		await rm(scratch, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function restoreStateBackup(input) {
+	const archive = resolve(input.archivePath);
+	const target = resolve(input.target);
+	const { manifest, key } = await readArchive(archive, input.passphrase);
+	const parent = dirname(target);
+	let staging;
+	try {
+		await mkdir(parent, { recursive: true });
+		try {
+			await lstat(target);
+			throw new Error("Restore target already exists; choose a new directory");
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+		staging = await mkdtemp(join(parent, `.xopc-restore-${randomUUID()}-`));
+		for (const entry of manifest.entries) {
+			const destination = join(staging, ...entry.path.split("/"));
+			if (!inside(destination, staging)) throw new Error("Backup path escapes target");
+			await mkdir(dirname(destination), { recursive: true });
+			await decryptEntry(archive, entry, key, destination);
+			await chmod(destination, entry.mode & 511);
+		}
+		const { DatabaseSync } = requireNodeSqlite();
+		const db = new DatabaseSync(join(staging, "xopc.db"), { readOnly: true });
+		try {
+			if (db.prepare("PRAGMA integrity_check").get().integrity_check !== "ok") throw new Error("Restored database failed integrity check");
+		} finally {
+			db.close();
+		}
+		await rename(staging, target);
+		return manifest;
+	} catch (error) {
+		if (staging) await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	} finally {
+		key.fill(0);
+	}
+}
+//#endregion
+export { createStateBackup, restoreStateBackup, verifyStateBackup };

package/dist/src/cli/command-loaders.js

@@ -5,6 +5,7 @@ import { registry } from "./registry.js";
 const REGISTRY_COMMAND_MODULES = {
 	init: () => import("./commands/init.js"),
 	profile: () => import("./commands/profile.js"),
+	backup: () => import("./commands/backup.js"),
 	setup: () => import("./commands/setup.js"),
 	onboard: () => import("./commands/onboard.js"),
 	agent: () => import("./commands/agent.js"),

package/dist/src/cli/command-manifest.js

@@ -35,6 +35,10 @@ const ROOT_HELP_COMMANDS = [
 		name: "profile",
 		description: "Manage xopc state profiles (~/.xopc vs ~/.xopc-<name>)"
 	},
+	{
+		name: "backup",
+		description: "Create, verify, and restore encrypted offline state backups"
+	},
 	{
 		name: "onboard [options]",
 		description: "Interactive setup wizard for xopc (gateway uses schema defaults)"

package/dist/src/cli/commands/backup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/cli/commands/backup.js

@@ -0,0 +1,84 @@
+import { init_paths_state, resolveStateDir } from "../../config/paths-state.js";
+import { init_paths, resolveConfigPath, resolveCredentialsDir } from "../../config/paths.js";
+import { createStateBackup, restoreStateBackup, verifyStateBackup } from "../../backup/archive.js";
+import { formatExamples, register } from "../registry.js";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { lstat, readFile } from "node:fs/promises";
+import { Command } from "commander";
+//#region src/cli/commands/backup.ts
+init_paths();
+init_paths_state();
+async function passphraseFromFile(path) {
+	const source = resolve(path);
+	const details = await lstat(source);
+	if (!details.isFile()) throw new Error("Passphrase path must be a regular file");
+	if (process.platform !== "win32" && (details.mode & 63) !== 0) throw new Error("Passphrase file must be readable only by its owner (chmod 600)");
+	return (await readFile(source, "utf8")).replace(/\r?\n$/, "");
+}
+function reportError(error) {
+	console.error(`Backup failed: ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+}
+function createBackupCommand(ctx) {
+	const command = new Command("backup").description("Create, verify, and restore encrypted offline state backups").addHelpText("after", formatExamples([
+		"xopc backup create --output /secure/xopc-backup --passphrase-file /secure/passphrase",
+		"xopc backup verify /secure/xopc-backup --passphrase-file /secure/passphrase",
+		"xopc backup restore /secure/xopc-backup --target /new/.xopc --passphrase-file /secure/passphrase"
+	]));
+	command.command("create").requiredOption("--output <directory>", "New backup directory outside the state directory").requiredOption("--passphrase-file <path>", "File containing a passphrase of at least 12 characters").action(async (options) => {
+		try {
+			const rel = relative(resolveStateDir(), resolve(options.passphraseFile));
+			if (rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)) throw new Error("Passphrase file must be outside the state directory");
+			const manifest = await createStateBackup({
+				stateDir: resolveStateDir(),
+				output: options.output,
+				passphrase: await passphraseFromFile(options.passphraseFile),
+				configPath: ctx.configPath,
+				configuredPaths: [
+					ctx.configPath || resolveConfigPath(),
+					resolveCredentialsDir(),
+					ctx.workspacePath
+				]
+			});
+			console.log(`Backup created: ${resolve(options.output)} (${manifest.entries.length} files, schema ${manifest.schemaVersion})`);
+			console.log("Backups contain private conversations and credentials. Keep both the archive and passphrase secure.");
+			console.log("This first version covers the state directory and rejects known external workspace, config, and credential paths.");
+		} catch (error) {
+			reportError(error);
+		}
+	});
+	command.command("verify").argument("<directory>", "Backup directory").requiredOption("--passphrase-file <path>", "Passphrase file").action(async (directory, options) => {
+		try {
+			const manifest = await verifyStateBackup(directory, await passphraseFromFile(options.passphraseFile));
+			console.log(`Backup verified: ${manifest.entries.length} files, schema ${manifest.schemaVersion}`);
+		} catch (error) {
+			reportError(error);
+		}
+	});
+	command.command("restore").argument("<directory>", "Backup directory").requiredOption("--target <directory>", "New restore directory; must not exist").requiredOption("--passphrase-file <path>", "Passphrase file").action(async (directory, options) => {
+		try {
+			const manifest = await restoreStateBackup({
+				archivePath: directory,
+				target: options.target,
+				passphrase: await passphraseFromFile(options.passphraseFile)
+			});
+			console.log(`Backup restored: ${resolve(options.target)} (${manifest.entries.length} files)`);
+			console.log("Review external paths and provider/channel authorization before starting the restored Gateway.");
+		} catch (error) {
+			reportError(error);
+		}
+	});
+	return command;
+}
+register({
+	id: "backup",
+	name: "backup",
+	description: "Create, verify, and restore encrypted offline state backups",
+	factory: createBackupCommand,
+	metadata: {
+		category: "maintenance",
+		examples: ["xopc backup create --output /secure/backup --passphrase-file /secure/passphrase"]
+	}
+});
+//#endregion
+export {};

package/dist/src/cli/index.js

@@ -23,10 +23,11 @@ function isExtensionsDevCommand(command) {
 }
 function buildProgram(ctx) {
 	const program = new Command().name("xopc").description(ROOT_COMMAND_DESCRIPTION).version(version).option("--verbose", "Enable verbose logging", false).option("--config <path>", "Config file path").option("--workspace <path>", "Workspace directory");
-	program.hook("preAction", (thisCommand) => {
-		const next = thisCommand.opts();
+	program.hook("preAction", (hookOwner, actionCommand) => {
+		const next = hookOwner.opts();
 		for (const k of Object.keys(parsedOpts)) delete parsedOpts[k];
 		Object.assign(parsedOpts, next);
+		if (actionCommand?.name() === "backup" || actionCommand?.parent?.name() === "backup") return;
 		bootstrapApplicationStateSync(ctx.configPath);
 	});
 	program.hook("postAction", async (_hookOwner, actionCommand) => {

package/dist/src/computer/errors.js

@@ -73,6 +73,7 @@ function computerRecovery(code) {
 		case "COMPUTER_APP_NOT_AUTHORIZED": return "This application has not been authorized in the local Computer Use settings. Tell the user where to configure access. Do not request a chat approval or try another control route.";
 		case "COMPUTER_APP_NOT_RUNNING": return "Open with prepare=true only if the user requested launching the app; otherwise ask them to open it.";
 		case "COMPUTER_WINDOW_REQUIRED": return "No visible target window. If the task permits bringing the app forward, open with prepare=true; otherwise ask the user to show the window. If preparation already failed, require a local state change before retrying.";
+		case "COMPUTER_DRIVER_BRING_TO_FRONT_REFUSED": return "The native driver refused to activate the app window. Ask the user to bring the intended window to the foreground locally, then discover and open it with prepare=false. Do not repeat prepare=true or use another control route.";
 		case "COMPUTER_WINDOW_AMBIGUOUS": return "Choose a returned windowRef only when its title matches the task. Otherwise ask the user using window titles, not IDs.";
 		case "COMPUTER_WINDOW_CHANGED": return "The selected window no longer exists. Discover and open again; never reuse its coordinates.";
 		case "COMPUTER_READ_ONLY": return "This session is read-only. Do not retry an action or reopen in control mode without user authorization.";

package/dist/src/gateway/hono/routes/ai-assist.js

@@ -1,5 +1,5 @@
-import { assistText, streamTextAssist } from "../../../ai-assist/text-assist.js";
 import { createGatewayRouteLogger, logRouteError } from "../lib/route-logger.js";
+import { assistText, streamTextAssist } from "../../../ai-assist/text-assist.js";
 import { stringifySSEData } from "../sse-json.js";
 import { streamSSE } from "hono/streaming";
 //#region src/gateway/hono/routes/ai-assist.ts

package/dist/src/gateway/hono/routes/sessions.js

@@ -422,6 +422,15 @@ function registerSessionsRoutes(authenticated, deps) {
 			pagination: result.pagination
 		});
 	});
+	authenticated.get("/api/sessions/:key/execution-detail", async (c) => {
+		const blocked = ensureGatewayReadyForSessions(c, service, "sessions.history");
+		if (blocked) return blocked;
+		const turnId = c.req.query("turnId")?.trim();
+		if (!turnId || turnId.length > 256) return c.json({ error: "Invalid turn id" }, 400);
+		c.header("Cache-Control", "no-store");
+		const detail = await service.sessions.getExecutionDetail(c.req.param("key"), turnId);
+		return detail ? c.json({ detail }) : c.json({ error: "Execution detail not found" }, 404);
+	});
 	authenticated.get("/api/sessions/:key/history", async (c) => {
 		const blocked = ensureGatewayReadyForSessions(c, service, "sessions.history");
 		if (blocked) return blocked;

package/dist/src/gateway/service/sessions-api.d.ts

@@ -72,11 +72,10 @@ export declare class GatewaySessionsApi {
             hasMore: boolean;
             before?: string;
             nextBeforeCursor?: string;
-            revision
-            /** List conversations whose stored type is workflow-subagent. */
-            ?: number;
+            revision?: number;
         };
     }>;
+    getExecutionDetail(key: string, turnId: string): Promise<import("../../session/execution-detail.js").PublicExecutionDetail>;
     getTimeline(key: string): Promise<import("../../session/transcript-outline.js").SessionTimelineItem[]>;
     getTranscriptWindow(key: string, options: {
         rowNumber: number;

package/dist/src/gateway/service/sessions-api.js

@@ -5,6 +5,7 @@ import { transcriptRowsToClientHistory } from "../../session/client-history.js";
 import "../../agent/mcp/bundle-mcp-tools.js";
 import { collectMediaUrisFromValues, deleteMediaUris } from "../../media/session-references.js";
 import { withModelConfigLock } from "../../session/model-config-lock.js";
+import { publicExecutionDetail } from "../../session/execution-detail.js";
 import { getDistinctSessionChatIds } from "./session-chat-ids.js";
 import { performSessionReset } from "../session-reset-service.js";
 import { randomUUID } from "node:crypto";
@@ -93,6 +94,10 @@ var GatewaySessionsApi = class {
 	getMessagePage(key, options) {
 		return this.opts.sessionIndex.getSessionMessagePage(key, options);
 	}
+	async getExecutionDetail(key, turnId) {
+		if (!await this.opts.sessionIndex.getSessionMetadata(key)) return null;
+		return publicExecutionDetail(transcriptRowsToClientHistory(await this.opts.sessionIndex.getStore().loadTranscriptHistoryRows(key)), turnId);
+	}
 	async getTimeline(key) {
 		if (!await this.opts.sessionIndex.getSessionMetadata(key)) return null;
 		return buildSessionTimeline(await this.opts.sessionIndex.getStore().loadTranscriptHistoryRows(key));

package/dist/src/gateway/session-context-summary.js

@@ -4,7 +4,7 @@ import { getSqliteDatabase, init_transaction } from "../storage/sqlite/transacti
 import { hasGatewayScope, init_gateway_scopes } from "./security/gateway-scopes.js";
 import { TaskRepository, init_task_repository } from "../tasks/task-repository.js";
 import { getSessionMetadata } from "../storage/sqlite/session-read-repository.js";
-import { init_session_repository } from "../storage/sqlite/session-repository.js";
+import { getCurrentTranscriptId, init_session_repository } from "../storage/sqlite/session-repository.js";
 import { getSessionConfig, init_config_repository } from "../storage/sqlite/config-repository.js";
 import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
 import { getExecutionEnvironmentForSession } from "../execution-environments/subject.js";
@@ -24,6 +24,94 @@ init_logger();
 init_gateway_scopes();
 const log = createLogger("SessionContextSummary");
 const SOURCE_LIMIT = 20;
+const RECENT_SOURCE_KINDS = new Set([
+	"note",
+	"file",
+	"session",
+	"browser_tab",
+	"mcp_resource",
+	"browser_page",
+	"app_context"
+]);
+function parseRecentSources(value) {
+	if (!value) return [];
+	let rows;
+	try {
+		rows = JSON.parse(value);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(rows)) return [];
+	return rows.slice(0, SOURCE_LIMIT + 1).flatMap((value) => {
+		if (!value || typeof value !== "object") return [];
+		const row = value;
+		if (!RECENT_SOURCE_KINDS.has(String(row.kind)) || typeof row.sourceId !== "string" || !row.sourceId) return [];
+		return [{
+			kind: row.kind,
+			id: row.sourceId,
+			...typeof row.title === "string" ? { title: row.title.slice(0, 240) } : {},
+			...row.fileKind === "file" || row.fileKind === "directory" ? { fileKind: row.fileKind } : {},
+			origins: [{ kind: "recent" }]
+		}];
+	});
+}
+function parseRecentAttachments(value) {
+	if (!value) return [];
+	let rows;
+	try {
+		rows = JSON.parse(value);
+	} catch {
+		return [];
+	}
+	if (!Array.isArray(rows)) return [];
+	return rows.slice(0, SOURCE_LIMIT + 1).flatMap((value) => {
+		if (!value || typeof value !== "object") return [];
+		const row = value;
+		const id = typeof row.uri === "string" ? row.uri : typeof row.id === "string" ? row.id : void 0;
+		if (!id || !id.startsWith("media://")) return [];
+		return [{
+			kind: "attachment",
+			id,
+			...typeof row.name === "string" ? { title: row.name.slice(0, 240) } : {},
+			origins: [{ kind: "recent" }]
+		}];
+	});
+}
+/** Reads only reference metadata from the latest visible user turn and current queued input. */
+function readRecentSources(conversationId) {
+	const transcriptId = getCurrentTranscriptId(conversationId);
+	if (!transcriptId) return [];
+	const db = getSqliteDatabase();
+	const transcript = db.prepare(`SELECT
+      (SELECT json_group_array(json_object(
+        'kind', json_extract(value, '$.kind'), 'sourceId', json_extract(value, '$.sourceId'),
+        'title', json_extract(value, '$.title'), 'fileKind', json_extract(value, '$.fileKind')
+      )) FROM json_each(json_extract(entry.payload_json, '$.metadata.sourceContexts'))
+        WHERE CAST(key AS INTEGER) < ?) AS refs,
+      (SELECT json_group_array(json_object(
+        'uri', json_extract(value, '$.uri'), 'name', json_extract(value, '$.name')
+      )) FROM json_each(json_extract(entry.payload_json, '$.media'))
+        WHERE CAST(key AS INTEGER) < ?) AS attachments
+    FROM transcript_entries entry
+    WHERE transcript_id = ? AND entry_kind = 'message' AND role = 'user'
+      AND json_extract(payload_json, '$.metadata.hiddenFromClient') IS NOT 1
+    ORDER BY seq DESC LIMIT 1`).get(SOURCE_LIMIT + 1, SOURCE_LIMIT + 1, transcriptId);
+	const latest = db.prepare(`SELECT
+      (SELECT json_group_array(json_object(
+        'kind', json_extract(value, '$.kind'), 'sourceId', json_extract(value, '$.sourceId'),
+        'title', json_extract(value, '$.title'), 'fileKind', json_extract(value, '$.fileKind')
+      )) FROM json_each(input.context_refs_json)
+        WHERE CAST(key AS INTEGER) < ?) AS refs,
+      (SELECT json_group_array(json_object(
+        'uri', json_extract(value, '$.uri'), 'name', json_extract(value, '$.name')
+      )) FROM json_each(input.attachments_json)
+        WHERE CAST(key AS INTEGER) < ?) AS attachments
+    FROM session_inputs input WHERE conversation_id = ? AND expected_transcript_id = ?
+      AND kind = 'message' AND status IN ('queued', 'running', 'injecting', 'interrupted')
+      AND json_extract(origin_json, '$.type') != 'system'
+    ORDER BY created_at_ms DESC LIMIT 1`).get(SOURCE_LIMIT + 1, SOURCE_LIMIT + 1, conversationId, transcriptId) ?? transcript;
+	return latest ? [...parseRecentSources(latest.refs), ...parseRecentAttachments(latest.attachments)] : [];
+}
 async function readEnvironment(config, conversationId, projectId) {
 	const bound = getExecutionEnvironmentForSession(conversationId);
 	const project = projectId ? new ProjectStore().get(projectId) : void 0;
@@ -150,11 +238,31 @@ async function getSessionContextSummary(config, conversationId, scopes) {
 				kind: "note",
 				id: row.note_id,
 				...row.found_id ? { title: row.title ?? void 0 } : { unavailable: true },
-				origins: [...row.from_session ? [{
-					kind: "session",
-					version: source?.version
-				}] : [], ...row.from_task ? [{ kind: "task" }] : []]
+				origins: [...row.from_session ? [{ kind: "session" }] : [], ...row.from_task ? [{ kind: "task" }] : []]
 			}));
+			const sources = new Map(summary.sources.map((source) => [`${source.kind}:${source.id}`, source]));
+			const noteTitle = getSqliteDatabase().prepare(`SELECT substr(title, 1, 240) AS title
+        FROM notes WHERE note_id = ? AND status != 'trashed'`);
+			for (const recent of readRecentSources(conversationId)) {
+				const key = `${recent.kind}:${recent.id}`;
+				const existing = sources.get(key);
+				if (existing) {
+					if (!existing.origins.some((origin) => origin.kind === "recent")) existing.origins.push({ kind: "recent" });
+					continue;
+				}
+				if (recent.kind === "note") {
+					const found = noteTitle.get(recent.id);
+					if (found) recent.title = found.title;
+					else {
+						delete recent.title;
+						recent.unavailable = true;
+					}
+				}
+				sources.set(key, recent);
+			}
+			summary.sourcesHasMore ||= sources.size > SOURCE_LIMIT;
+			const priority = (item) => item.origins.some((origin) => origin.kind === "session") ? 0 : item.origins.some((origin) => origin.kind === "recent") ? 1 : 2;
+			summary.sources = [...sources.values()].sort((a, b) => priority(a) - priority(b)).slice(0, SOURCE_LIMIT);
 		} catch (err) {
 			unavailable("sources", err);
 		}