@xopcai/xopc 0.0.234 → 0.0.238

package/dist/src/execution-environments/subject.js

@@ -0,0 +1,12 @@
+import { isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
+import "../storage/sqlite/index.js";
+import { ExecutionEnvironmentStore } from "./store.js";
+//#region src/execution-environments/subject.ts
+function getExecutionEnvironmentForSession(sessionKey) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const store = new ExecutionEnvironmentStore();
+	const binding = store.resolveBinding(sessionKey);
+	return binding ? store.get(binding.environmentId) : void 0;
+}
+//#endregion
+export { getExecutionEnvironmentForSession };

package/dist/src/execution-environments/types.d.ts

@@ -0,0 +1,74 @@
+export declare const EXECUTION_ENVIRONMENT_KINDS: readonly ["local_checkout", "managed_worktree"];
+export type ExecutionEnvironmentKind = (typeof EXECUTION_ENVIRONMENT_KINDS)[number];
+export declare const EXECUTION_ENVIRONMENT_STATUSES: readonly ["requested", "provisioning", "ready", "degraded", "deleting", "deleted", "error"];
+export type ExecutionEnvironmentStatus = (typeof EXECUTION_ENVIRONMENT_STATUSES)[number];
+export interface ExecutionEnvironment {
+    id: string;
+    projectId?: string;
+    kind: ExecutionEnvironmentKind;
+    status: ExecutionEnvironmentStatus;
+    rootPath: string;
+    repositoryRoot?: string;
+    gitCommonDir?: string;
+    baseRef?: string;
+    baseSha?: string;
+    branchRef?: string;
+    version: number;
+    lastError?: string;
+    createdAt: number;
+    updatedAt: number;
+    lastUsedAt?: number;
+    deletedAt?: number;
+}
+export interface ExecutionEnvironmentBinding {
+    id: string;
+    sessionKey: string;
+    environmentId: string;
+    createdAt: number;
+    releasedAt?: number;
+}
+export interface ExecutionEnvironmentEvent {
+    id: string;
+    environmentId: string;
+    fromStatus?: ExecutionEnvironmentStatus;
+    toStatus: ExecutionEnvironmentStatus;
+    reason: string;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+}
+export interface CreateExecutionEnvironmentInput {
+    id?: string;
+    projectId?: string;
+    kind: ExecutionEnvironmentKind;
+    rootPath: string;
+    repositoryRoot?: string;
+    gitCommonDir?: string;
+    baseRef?: string;
+    baseSha?: string;
+    branchRef?: string;
+}
+export interface ExecutionEnvironmentListQuery {
+    projectId?: string;
+    status?: ExecutionEnvironmentStatus;
+    includeDeleted?: boolean;
+    limit?: number;
+}
+export interface BindExecutionEnvironmentInput {
+    sessionKey: string;
+    environmentId: string;
+}
+export interface TransitionExecutionEnvironmentInput {
+    environmentId: string;
+    toStatus: ExecutionEnvironmentStatus;
+    expectedVersion: number;
+    reason: string;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare class ExecutionEnvironmentConflictError extends Error {
+    constructor(message: string);
+}
+export declare class ExecutionEnvironmentNotFoundError extends Error {
+    constructor(environmentId: string);
+}
+export declare function canTransitionExecutionEnvironment(fromStatus: ExecutionEnvironmentStatus, toStatus: ExecutionEnvironmentStatus): boolean;

package/dist/src/execution-environments/types.js

@@ -0,0 +1,54 @@
+//#region src/execution-environments/types.ts
+const EXECUTION_ENVIRONMENT_KINDS = ["local_checkout", "managed_worktree"];
+const EXECUTION_ENVIRONMENT_STATUSES = [
+	"requested",
+	"provisioning",
+	"ready",
+	"degraded",
+	"deleting",
+	"deleted",
+	"error"
+];
+var ExecutionEnvironmentConflictError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ExecutionEnvironmentConflictError";
+	}
+};
+var ExecutionEnvironmentNotFoundError = class extends Error {
+	constructor(environmentId) {
+		super(`Execution environment not found: ${environmentId}`);
+		this.name = "ExecutionEnvironmentNotFoundError";
+	}
+};
+const STATUS_TRANSITIONS = {
+	requested: [
+		"provisioning",
+		"deleting",
+		"error"
+	],
+	provisioning: [
+		"ready",
+		"degraded",
+		"deleting",
+		"error"
+	],
+	ready: [
+		"degraded",
+		"deleting",
+		"error"
+	],
+	degraded: [
+		"provisioning",
+		"deleting",
+		"error"
+	],
+	deleting: ["deleted", "error"],
+	deleted: [],
+	error: ["provisioning", "deleting"]
+};
+function canTransitionExecutionEnvironment(fromStatus, toStatus) {
+	return STATUS_TRANSITIONS[fromStatus].includes(toStatus);
+}
+//#endregion
+export { EXECUTION_ENVIRONMENT_KINDS, EXECUTION_ENVIRONMENT_STATUSES, ExecutionEnvironmentConflictError, ExecutionEnvironmentNotFoundError, canTransitionExecutionEnvironment };

package/dist/src/extensions/lockfile.js

@@ -1,7 +1,7 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { init_write_file_atomic, writeTextAtomic } from "../infra/write-file-atomic.js";
 import { init_paths, resolveExtensionsDir, resolveExtensionsLockPath } from "../config/paths.js";
+import { init_write_file_atomic, writeTextAtomic } from "../infra/write-file-atomic.js";
 import { dirname, join } from "path";
 import { existsSync } from "fs";
 import { mkdir, readFile } from "fs/promises";

package/dist/src/files/file-service.d.ts

@@ -15,17 +15,25 @@ export declare class FileServiceError extends Error {
     readonly status: 400 | 403 | 404 | 409;
     constructor(status: 400 | 403 | 404 | 409, message: string);
 }
-export declare function fileResourceFromPath(space: ResolvedFileSpace, absolutePath: string): Promise<FileResource>;
+export declare function fileResourceFromPath(space: ResolvedFileSpace, absolutePath: string, displayPath?: string): Promise<FileResource>;
 export declare class FileSpaceService {
     private readonly getConfig;
     private readonly projects;
     private readonly resolveSessionWorkspace;
+    private readonly listSessionWorkspaces;
     private readonly dynamicSpaces;
     private cache;
-    constructor(getConfig: () => Config, projects: ProjectService, resolveSessionWorkspace: (sessionKey: string) => string);
+    constructor(getConfig: () => Config, projects: ProjectService, resolveSessionWorkspace: (sessionKey: string) => string | Promise<string>, listSessionWorkspaces?: () => Array<{
+        sessionKey: string;
+        root: string;
+    }> | Promise<Array<{
+        sessionKey: string;
+        root: string;
+    }>>);
     private createSpace;
     list(): Promise<ResolvedFileSpace[]>;
     forContext(kind: 'agent' | 'project' | 'session', id: string): Promise<ResolvedFileSpace>;
+    defaultSpace(): Promise<ResolvedFileSpace>;
     get(id: string): Promise<ResolvedFileSpace>;
     resource(id: string): Promise<{
         space: ResolvedFileSpace;

package/dist/src/files/file-service.js

@@ -1,4 +1,4 @@
-import { init_agent_scope, listAgentEntries, resolveAgentWorkspaceDir } from "../agent/agent-scope.js";
+import { init_agent_scope, listAgentEntries, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agent/agent-scope.js";
 import { resolveProjectAgentId } from "../projects/project-agent.js";
 import "../projects/index.js";
 import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
@@ -21,6 +21,7 @@ const TEXT_EXTENSIONS = new Set([
 	"json",
 	"jsx",
 	"md",
+	"markdown",
 	"mjs",
 	"cjs",
 	"svg",
@@ -40,6 +41,7 @@ const MIME_TYPES = {
 	webp: "image/webp",
 	svg: "image/svg+xml",
 	md: "text/markdown",
+	markdown: "text/markdown",
 	txt: "text/plain",
 	json: "application/json",
 	html: "text/html",
@@ -85,7 +87,7 @@ function mimeType(name, directory) {
 	return MIME_TYPES[name.includes(".") ? name.split(".").pop().toLowerCase() : ""] ?? "application/octet-stream";
 }
 function capabilities(name, directory, writable) {
-	if (directory) return writable ? ["upload"] : [];
+	if (directory) return writable ? ["share", "upload"] : ["share"];
 	const extension = name.includes(".") ? name.split(".").pop().toLowerCase() : "";
 	const result = ["download", "share"];
 	if (MIME_TYPES[extension] || TEXT_EXTENSIONS.has(extension)) result.unshift("preview");
@@ -135,11 +137,11 @@ var FileServiceError = class extends Error {
 		this.status = status;
 	}
 };
-async function fileResourceFromPath(space, absolutePath) {
+async function fileResourceFromPath(space, absolutePath, displayPath = absolutePath) {
 	const info = await stat(absolutePath);
 	const revisionInfo = await stat(absolutePath, { bigint: true });
-	const relativePath = relative(await realpath(space.root), absolutePath).split(sep).join("/");
-	const name = basename(absolutePath);
+	const relativePath = relative(await realpath(space.root), displayPath).split(sep).join("/");
+	const name = basename(displayPath);
 	const directory = info.isDirectory();
 	return {
 		id: fileResourceId(space.id, relativePath),
@@ -158,10 +160,11 @@ async function fileResourceFromPath(space, absolutePath) {
 var FileSpaceService = class {
 	dynamicSpaces = /* @__PURE__ */ new Map();
 	cache = null;
-	constructor(getConfig, projects, resolveSessionWorkspace) {
+	constructor(getConfig, projects, resolveSessionWorkspace, listSessionWorkspaces = () => []) {
 		this.getConfig = getConfig;
 		this.projects = projects;
 		this.resolveSessionWorkspace = resolveSessionWorkspace;
+		this.listSessionWorkspaces = listSessionWorkspaces;
 	}
 	async createSpace(root, title, bindings) {
 		const canonicalRoot = await realpath(root).catch(() => null);
@@ -213,6 +216,13 @@ var FileSpaceService = class {
 			offset += page.items.length;
 		}
 		const merged = /* @__PURE__ */ new Map();
+		for (const { sessionKey, root } of await this.listSessionWorkspaces()) {
+			const space = await this.createSpace(root, sessionKey, [{
+				kind: "session",
+				id: sessionKey
+			}]);
+			if (space) spaces.push(space);
+		}
 		for (const space of [...spaces, ...this.dynamicSpaces.values()]) {
 			const existing = merged.get(space.id);
 			if (existing) existing.bindings = [...existing.bindings, ...space.bindings.filter((binding) => !existing.bindings.some((item) => item.kind === binding.kind && item.id === binding.id))];
@@ -245,7 +255,7 @@ var FileSpaceService = class {
 			}
 			title = project?.name ?? id;
 		}
-		if (kind === "session") root = this.resolveSessionWorkspace(id);
+		if (kind === "session") root = await this.resolveSessionWorkspace(id);
 		if (!root) throw new FileServiceError(404, "File space not found");
 		const space = await this.createSpace(root, title, [{
 			kind,
@@ -256,8 +266,16 @@ var FileSpaceService = class {
 		this.cache = null;
 		return space;
 	}
+	defaultSpace() {
+		return this.forContext("agent", resolveDefaultAgentId(this.getConfig()));
+	}
 	async get(id) {
-		const space = (await this.list()).find((item) => item.id === id);
+		const hadCache = this.cache !== null;
+		let space = (await this.list()).find((item) => item.id === id);
+		if (!space && hadCache) {
+			this.cache = null;
+			space = (await this.list()).find((item) => item.id === id);
+		}
 		if (!space) throw new FileServiceError(404, "File space not found");
 		return space;
 	}
@@ -267,7 +285,7 @@ var FileSpaceService = class {
 		const absolutePath = await resolveFilePath(space.root, locator.relativePath);
 		return {
 			space,
-			resource: await fileResourceFromPath(space, absolutePath),
+			resource: await fileResourceFromPath(space, absolutePath, resolve(space.root, locator.relativePath)),
 			absolutePath
 		};
 	}
@@ -280,9 +298,12 @@ var FileSpaceService = class {
 		for await (const entry of dir) {
 			if (SKIPPED_NAMES.has(entry.name)) continue;
 			const target = resolve(directory, entry.name);
-			const linkInfo = await lstat(target).catch(() => null);
-			if (!linkInfo || linkInfo.isSymbolicLink()) continue;
-			entries.push(await fileResourceFromPath(space, target));
+			if (!await lstat(target).catch(() => null)) continue;
+			const canonicalTarget = await resolveFilePath(space.root, target).catch(() => null);
+			if (!canonicalTarget) continue;
+			const info = await stat(canonicalTarget).catch(() => null);
+			if (!info || !info.isFile() && !info.isDirectory()) continue;
+			entries.push(await fileResourceFromPath(space, canonicalTarget, resolve(space.root, path, entry.name)));
 		}
 		return entries.sort((a, b) => a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === "directory" ? -1 : 1);
 	}

package/dist/src/gateway/agent-builtin-tools.d.ts

@@ -247,4 +247,4 @@ export declare const GATEWAY_BUILTIN_TOOLS: readonly [{
         readonly zh: "使用已验证的参数执行选定的外部工具。";
     };
 }];
-export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "todo" | "image" | "clarify" | "dreaming" | "memory_search" | "memory_get" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "web_extract" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "xopc_tool_search" | "xopc_tool_describe" | "xopc_tool_execute" | "send_message" | "send_media" | "read_media" | "create_share" | "session_status" | "tool_manual" | "delegate_task" | "skill_install" | "text_to_speech" | "execute_code" | "create_desktop_pet")[];
+export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "memory_search" | "memory_get" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "clarify" | "dreaming" | "web_extract" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "xopc_tool_search" | "xopc_tool_describe" | "xopc_tool_execute" | "send_message" | "send_media" | "read_media" | "create_share" | "session_status" | "tool_manual" | "delegate_task" | "skill_install" | "text_to_speech" | "execute_code" | "create_desktop_pet")[];

package/dist/src/gateway/agents-admin.js

@@ -1,6 +1,6 @@
 import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveAgentDir, resolveAgentProfileDir, resolveAgentWorkspaceDir, resolveDefaultAgentId, resolveUserPath, validateAgentIdForNewAgent } from "../agent/agent-scope.js";
-import { WORKSPACE_FILES, init_paths } from "../config/paths.js";
 import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
+import { WORKSPACE_FILES, init_paths } from "../config/paths.js";
 import { AGENT_PROFILE_MARKDOWN_SYSTEM_FILES, REQUIRED_AGENT_PROFILE_MARKDOWN_FILE_SET } from "../agent/context/workspace.js";
 import { isPathUnderWorkspace, resolveWorkspaceSafePath } from "./workspace-editor-path.js";
 import { seedAgentProfileMarkdownFiles } from "../agent/context/workspace-seed.js";

package/dist/src/gateway/custom-image-providers.d.ts

@@ -53,8 +53,8 @@ export declare const CustomImageProviderInputSchema: z.ZodObject<{
                     qualities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                         low: "low";
                         high: "high";
-                        auto: "auto";
                         medium: "medium";
+                        auto: "auto";
                     }>>>;
                     formats: z.ZodOptional<z.ZodArray<z.ZodEnum<{
                         png: "png";

package/dist/src/gateway/file-path-classifier.d.ts

@@ -0,0 +1,30 @@
+import type { Config } from '../config/schema.js';
+import type { FileReferenceLocationKind, FileReferenceScope } from './file-reference-registry.js';
+export type { FileReferenceLocationKind };
+export interface FilePathClassifierContext {
+    workspaceRoot: string;
+    profileMarkdownRoot?: string;
+    stateDir: string;
+    skillsDir: string;
+    configFilePath: string;
+    agentsHomeDir: string;
+    agentId: string;
+}
+export declare function buildFilePathClassifierContext(cfg: Config, sessionKeyRaw?: string): FilePathClassifierContext;
+export declare function looksLikeHostAbsolutePath(pathRaw: string): boolean;
+export declare function fileRefSessionKeysMatch(registered?: string, query?: string): boolean;
+export interface ClassifiedFileLocation {
+    scope: FileReferenceScope;
+    locationKind?: FileReferenceLocationKind;
+    manageRoute?: string;
+}
+export declare function classifyFileLocation(absPath: string, ctx: FilePathClassifierContext): ClassifiedFileLocation;
+export interface ResolveFileReferenceCandidateResult {
+    candidate: string | null;
+    invalid: boolean;
+}
+/**
+ * Resolve user path to an absolute candidate (workspace, absolute host, or profile fallback).
+ */
+export declare function resolveFileReferenceCandidate(rawPath: string, workspaceRoot: string, ctx: FilePathClassifierContext): Promise<ResolveFileReferenceCandidateResult>;
+export declare function displayNameForPath(rawPath: string): string;

package/dist/src/gateway/file-path-classifier.js

@@ -0,0 +1,105 @@
+import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
+import { init_agent_scope, resolveAgentProfileDir } from "../agent/agent-scope.js";
+import { extractProfileAgentId } from "../config/agent-profile.js";
+import { init_paths, resolveConfigPath, resolveSkillsDir } from "../config/paths.js";
+import { isBareProfileMarkdownFileName, resolveProfileMarkdownPathIfBareName } from "../agent/tools/tool-paths.js";
+import { isPathUnderWorkspace, resolveWorkspaceSafePath } from "./workspace-editor-path.js";
+import { basename, isAbsolute, resolve } from "node:path";
+import { stat } from "node:fs/promises";
+//#region src/gateway/file-path-classifier.ts
+init_agent_scope();
+init_paths();
+init_paths_state();
+function buildFilePathClassifierContext(cfg, sessionKeyRaw) {
+	const agentId = extractProfileAgentId(sessionKeyRaw, cfg);
+	const stateDir = resolveStateDir();
+	return {
+		workspaceRoot: "",
+		profileMarkdownRoot: resolveAgentProfileDir(cfg, agentId),
+		stateDir,
+		skillsDir: resolveSkillsDir(),
+		configFilePath: resolveConfigPath(),
+		agentsHomeDir: resolve(stateDir, "agents"),
+		agentId
+	};
+}
+function looksLikeHostAbsolutePath(pathRaw) {
+	const p = pathRaw.trim();
+	if (!p) return false;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(p) && !/^[A-Za-z]:[\\/]/.test(p)) return false;
+	return isAbsolute(p) || /^[A-Za-z]:[\\/]/.test(p) || p.startsWith("\\\\");
+}
+function fileRefSessionKeysMatch(registered, query) {
+	return (registered ?? "").trim() === (query ?? "").trim();
+}
+function classifyFileLocation(absPath, ctx) {
+	const p = resolve(absPath);
+	if (isPathUnderWorkspace(resolve(ctx.workspaceRoot), p)) return { scope: "workspace" };
+	if (ctx.profileMarkdownRoot) {
+		if (isPathUnderWorkspace(resolve(ctx.profileMarkdownRoot), p)) return {
+			scope: "agent-profile",
+			locationKind: "agent-profile",
+			manageRoute: `/agents/${encodeURIComponent(ctx.agentId)}`
+		};
+	}
+	if (isPathUnderWorkspace(resolve(ctx.skillsDir), p)) return {
+		scope: "external",
+		locationKind: "xopc-skills",
+		manageRoute: "/skills"
+	};
+	if (isPathUnderWorkspace(resolve(ctx.agentsHomeDir), p)) return {
+		scope: "external",
+		locationKind: "xopc-agents",
+		manageRoute: `/agents/${encodeURIComponent(ctx.agentId)}`
+	};
+	const stateRoot = resolve(ctx.stateDir);
+	if (p === resolve(ctx.configFilePath) || isPathUnderWorkspace(stateRoot, p)) return {
+		scope: "external",
+		locationKind: "xopc-config",
+		manageRoute: "/settings/gateway"
+	};
+	return {
+		scope: "external",
+		locationKind: "host"
+	};
+}
+/**
+* Resolve user path to an absolute candidate (workspace, absolute host, or profile fallback).
+*/
+async function resolveFileReferenceCandidate(rawPath, workspaceRoot, ctx) {
+	const displayRoot = workspaceRoot;
+	ctx = {
+		...ctx,
+		workspaceRoot: displayRoot
+	};
+	if (looksLikeHostAbsolutePath(rawPath)) return {
+		candidate: resolve(rawPath),
+		invalid: false
+	};
+	const wsPath = resolveWorkspaceSafePath(workspaceRoot, rawPath);
+	if (!wsPath) return {
+		candidate: null,
+		invalid: true
+	};
+	try {
+		await stat(wsPath);
+		return {
+			candidate: wsPath,
+			invalid: false
+		};
+	} catch (e) {
+		if (e?.code === "ENOENT" && ctx.profileMarkdownRoot && isBareProfileMarkdownFileName(rawPath)) return {
+			candidate: resolveProfileMarkdownPathIfBareName(rawPath, ctx.profileMarkdownRoot),
+			invalid: false
+		};
+		return {
+			candidate: wsPath,
+			invalid: false
+		};
+	}
+}
+function displayNameForPath(rawPath) {
+	return basename(rawPath.replace(/\\/g, "/")) || rawPath;
+}
+//#endregion
+export { buildFilePathClassifierContext, classifyFileLocation, displayNameForPath, fileRefSessionKeysMatch, looksLikeHostAbsolutePath, resolveFileReferenceCandidate };

package/dist/src/gateway/file-reference-errors.d.ts

@@ -0,0 +1,6 @@
+export type FileReferenceFsError = {
+    code: 'FILE_NOT_FOUND' | 'FILE_ACCESS_DENIED' | 'FILE_ACCESS_FAILED';
+    message: string;
+    status: 404 | 403 | 500;
+};
+export declare function classifyFileReferenceFsError(err: unknown): FileReferenceFsError;

package/dist/src/gateway/file-reference-errors.js

@@ -0,0 +1,21 @@
+//#region src/gateway/file-reference-errors.ts
+function classifyFileReferenceFsError(err) {
+	const code = err?.code;
+	if (code === "ENOENT" || code === "ENOTDIR") return {
+		code: "FILE_NOT_FOUND",
+		message: "File not found",
+		status: 404
+	};
+	if (code === "EACCES" || code === "EPERM") return {
+		code: "FILE_ACCESS_DENIED",
+		message: "Gateway does not have permission to access this file",
+		status: 403
+	};
+	return {
+		code: "FILE_ACCESS_FAILED",
+		message: "Gateway could not access this file",
+		status: 500
+	};
+}
+//#endregion
+export { classifyFileReferenceFsError };

package/dist/src/gateway/file-reference-registry.d.ts

@@ -0,0 +1,34 @@
+export type FileReferenceScope = 'workspace' | 'external' | 'agent-profile' | 'session-artifact' | 'missing' | 'invalid';
+/** Where an off-workspace file lives (UI badge + manage deep link). */
+export type FileReferenceLocationKind = 'agent-profile' | 'xopc-skills' | 'xopc-config' | 'xopc-agents' | 'xopc-sessions' | 'host';
+export type FileReferenceCapability = 'preview' | 'edit' | 'openExternal' | 'revealInFolder' | 'copyPath' | 'importToWorkspace';
+export interface RegisteredFileReference {
+    id: string;
+    absolutePath: string;
+    sessionKey?: string;
+    scope: FileReferenceScope;
+    locationKind?: FileReferenceLocationKind;
+    capabilities: FileReferenceCapability[];
+    expiresAt: number;
+}
+export interface RegisterFileReferenceInput {
+    absolutePath: string;
+    sessionKey?: string;
+    scope: FileReferenceScope;
+    locationKind?: FileReferenceLocationKind;
+    capabilities: FileReferenceCapability[];
+    ttlMs?: number;
+}
+export declare class FileReferenceRegistry {
+    private readonly refs;
+    register(input: RegisterFileReferenceInput): RegisteredFileReference;
+    resolve(id: string): RegisteredFileReference | null;
+    /**
+     * Remove a specific reference (used after a one-shot action like
+     * import-to-workspace completes so the source card can't be re-triggered).
+     * Returns true if the reference existed and was removed.
+     */
+    expireById(id: string): boolean;
+    expire(now?: number): void;
+}
+export declare const fileReferenceRegistry: FileReferenceRegistry;

package/dist/src/gateway/file-reference-registry.js

@@ -0,0 +1,45 @@
+import { randomUUID } from "node:crypto";
+//#region src/gateway/file-reference-registry.ts
+const DEFAULT_TTL_MS = 1800 * 1e3;
+var FileReferenceRegistry = class {
+	refs = /* @__PURE__ */ new Map();
+	register(input) {
+		this.expire();
+		const id = randomUUID();
+		const ref = {
+			id,
+			absolutePath: input.absolutePath,
+			sessionKey: input.sessionKey?.trim() || void 0,
+			scope: input.scope,
+			locationKind: input.locationKind,
+			capabilities: [...new Set(input.capabilities)],
+			expiresAt: Date.now() + (input.ttlMs ?? DEFAULT_TTL_MS)
+		};
+		this.refs.set(id, ref);
+		return ref;
+	}
+	resolve(id) {
+		this.expire();
+		const ref = this.refs.get(id);
+		if (!ref) return null;
+		if (ref.expiresAt <= Date.now()) {
+			this.refs.delete(id);
+			return null;
+		}
+		return ref;
+	}
+	/**
+	* Remove a specific reference (used after a one-shot action like
+	* import-to-workspace completes so the source card can't be re-triggered).
+	* Returns true if the reference existed and was removed.
+	*/
+	expireById(id) {
+		return this.refs.delete(id);
+	}
+	expire(now = Date.now()) {
+		for (const [id, ref] of this.refs) if (ref.expiresAt <= now) this.refs.delete(id);
+	}
+};
+const fileReferenceRegistry = new FileReferenceRegistry();
+//#endregion
+export { FileReferenceRegistry, fileReferenceRegistry };

package/dist/src/gateway/file-space-service.d.ts

@@ -0,0 +1,4 @@
+import { FileSpaceService } from '../files/file-service.js';
+import type { GatewayService } from './service.js';
+/** Share the file registry, including session-specific spaces, across gateway routes. */
+export declare function getGatewayFileSpaceService(service: GatewayService): FileSpaceService;

package/dist/src/gateway/file-space-service.js

@@ -0,0 +1,19 @@
+import { listSessionWorkspaceOverrides } from "../storage/sqlite/config-repository.js";
+import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
+import { getProjectForSession } from "../projects/workspace.js";
+import { FileSpaceService } from "../files/file-service.js";
+//#region src/gateway/file-space-service.ts
+const services = /* @__PURE__ */ new WeakMap();
+/** Share the file registry, including session-specific spaces, across gateway routes. */
+function getGatewayFileSpaceService(service) {
+	const existing = services.get(service);
+	if (existing) return existing;
+	const created = new FileSpaceService(() => service.currentConfig, service.projects, (sessionKey) => service.sessions.getEffectiveWorkspacePath(sessionKey), () => listSessionWorkspaceOverrides().map(({ sessionKey, workingDirectoryOverride }) => ({
+		sessionKey,
+		root: effectiveWorkspacePathForSession(service.currentConfig, sessionKey, { workingDirectoryOverride }, getProjectForSession(sessionKey))
+	})));
+	services.set(service, created);
+	return created;
+}
+//#endregion
+export { getGatewayFileSpaceService };

package/dist/src/gateway/hono/app.js

@@ -21,6 +21,7 @@ import { resetLazyRouteBundlesForTests } from "./routes/lazy-fallback.js";
 import { registerAuthenticatedRoutes } from "./routes/index.js";
 import { prewarmStaticUiCache } from "./lib/static-ui.js";
 import { registerPublicGatewayRoutes } from "./routes/public-gateway.js";
+import { registerPublicHtmlPreviewRoute } from "./routes/html-preview.js";
 import { registerSiteShareMiddleware } from "../../share/site-share-router.js";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
@@ -109,7 +110,7 @@ function createHonoApp(config) {
 	const gatewayConsoleCsp = buildGatewayConsoleCspHeader();
 	app.use(createMiddleware(async (c, next) => {
 		await next();
-		if (isExtensionGatewayUiAssetPath(c.req.path)) return;
+		if (isExtensionGatewayUiAssetPath(c.req.path) || c.req.path === "/api/preview/html" && (c.req.method === "GET" || c.req.method === "HEAD")) return;
 		c.header("X-Frame-Options", "DENY");
 		c.header("X-Content-Type-Options", "nosniff");
 		c.header("Referrer-Policy", "strict-origin-when-cross-origin");
@@ -194,6 +195,7 @@ function createHonoApp(config) {
 		})(c, next);
 	});
 	registerPublicGatewayRoutes(app, service);
+	registerPublicHtmlPreviewRoute(app);
 	registerDeviceAuthPublicRoutes(app);
 	registerPublicExtensionAssetRoutes(app, service);
 	registerPublicLocalAppPreviewRoutes(app, service);