@xopcai/xopc 0.0.321 → 0.0.323

package/dist/src/gateway/hono/routes/local-apps.js

@@ -1,56 +1,71 @@
+import { LocalAppSourceHashSchema } from "../../../../packages/gateway-contract/src/local-apps.js";
+import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
+import { parseLocalAppFixGuidanceInput } from "../../../local-apps/fix-guidance.js";
 import { readLocalAppAcceptanceConfig } from "../../../local-apps/acceptance.js";
 import { createProductDispatcher } from "../../../capabilities/runtime/product.js";
 import { extensionAssetMimeType } from "../lib/extension-assets.js";
 import { capabilityHttpContext, capabilityHttpError } from "../../../capabilities/adapters/http.js";
 import { LOCAL_APP_RUNTIME_BRIDGE_HASH, injectLocalAppRuntimeBridge } from "../../../local-apps/preview-runtime-bridge.js";
 import { relative, resolve } from "node:path";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 //#region src/gateway/hono/routes/local-apps.ts
+init_src();
 const LOCAL_APP_PREVIEW_CSP = `default-src 'self'; script-src 'self' 'sha256-${LOCAL_APP_RUNTIME_BRIDGE_HASH}'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'none'; frame-ancestors 'self'; frame-src 'none'; base-uri 'none'; object-src 'none'; form-action 'none'`;
-function registerPublicLocalAppPreviewRoutes(app, service) {
-	app.get("/api/local-apps/preview/:token/*", (c) => {
-		const origin = c.req.header("origin");
-		const cors = { "Access-Control-Allow-Origin": origin === "null" ? "null" : origin || "*" };
-		const preview = service.localApps.resolvePreview(c.req.param("token"));
-		if (!preview) return c.json({ error: "Preview not found" }, 404, cors);
-		const prefix = `/api/local-apps/preview/${preview.previewToken}/`;
-		let assetPath = c.req.path.startsWith(prefix) ? c.req.path.slice(prefix.length) : "";
+function servePreviewAsset(c, preview, prefix, cacheControl) {
+	const origin = c.req.header("origin");
+	const cors = { "Access-Control-Allow-Origin": origin === "null" ? "null" : origin || "*" };
+	let assetPath = c.req.path.startsWith(prefix) ? c.req.path.slice(prefix.length) : "";
+	try {
+		assetPath = decodeURIComponent(assetPath);
+	} catch {
+		return c.json({ error: "Invalid asset path" }, 400, cors);
+	}
+	if (!assetPath || assetPath.includes("..")) return c.json({ error: "Invalid asset path" }, 400, cors);
+	if (!existsSync(preview.uiRoot)) return c.json({ error: "Not found" }, 404, cors);
+	const root = realpathSync(resolve(preview.uiRoot));
+	const unresolvedPath = resolve(root, assetPath);
+	const fullPath = existsSync(unresolvedPath) ? realpathSync(unresolvedPath) : unresolvedPath;
+	const rel = relative(root, fullPath);
+	if (rel.startsWith("..") || rel === "") return c.json({ error: "Path traversal denied" }, 403, cors);
+	if (!existsSync(fullPath) || !statSync(fullPath).isFile()) return c.json({ error: "Not found" }, 404, cors);
+	const mimeType = extensionAssetMimeType(assetPath);
+	const content = readFileSync(fullPath);
+	let textContent = null;
+	if (mimeType.startsWith("text/html")) {
+		let acceptance;
 		try {
-			assetPath = decodeURIComponent(assetPath);
+			acceptance = readLocalAppAcceptanceConfig(preview.uiRoot);
 		} catch {
-			return c.json({ error: "Invalid asset path" }, 400, cors);
+			acceptance = {
+				schemaVersion: 1,
+				scenarios: []
+			};
 		}
-		if (!assetPath || assetPath.includes("..")) return c.json({ error: "Invalid asset path" }, 400, cors);
-		const root = resolve(preview.uiRoot);
-		const fullPath = resolve(root, assetPath);
-		const rel = relative(root, fullPath);
-		if (rel.startsWith("..") || rel === "") return c.json({ error: "Path traversal denied" }, 403, cors);
-		if (!existsSync(fullPath) || !statSync(fullPath).isFile()) return c.json({ error: "Not found" }, 404, cors);
-		const mimeType = extensionAssetMimeType(assetPath);
-		const content = readFileSync(fullPath);
-		let textContent = null;
-		if (mimeType.startsWith("text/html")) {
-			let acceptance;
-			try {
-				acceptance = readLocalAppAcceptanceConfig(preview.uiRoot);
-			} catch {
-				acceptance = {
-					schemaVersion: 1,
-					scenarios: []
-				};
-			}
-			textContent = injectLocalAppRuntimeBridge(content.toString("utf8"), acceptance);
-		} else if (mimeType.startsWith("text/")) textContent = content.toString("utf8");
-		return new Response(textContent ?? new Uint8Array(content), { headers: {
-			"Content-Type": mimeType,
-			"Content-Security-Policy": LOCAL_APP_PREVIEW_CSP,
-			"Cache-Control": "no-store",
-			"X-Content-Type-Options": "nosniff",
-			...cors
-		} });
+		textContent = injectLocalAppRuntimeBridge(content.toString("utf8"), acceptance);
+	} else if (mimeType.startsWith("text/")) textContent = content.toString("utf8");
+	return new Response(textContent ?? new Uint8Array(content), { headers: {
+		"Content-Type": mimeType,
+		"Content-Security-Policy": LOCAL_APP_PREVIEW_CSP,
+		"Cache-Control": cacheControl,
+		"X-Content-Type-Options": "nosniff",
+		...cors
+	} });
+}
+function registerPublicLocalAppPreviewRoutes(app, service) {
+	app.get("/api/local-apps/preview/:token/draft/*", (c) => {
+		const preview = service.localApps.resolveDraftPreview(c.req.param("token"));
+		if (!preview) return c.json({ error: "Preview not found" }, 404);
+		return servePreviewAsset(c, preview, `/api/local-apps/preview/${preview.previewToken}/draft/`, "no-store");
+	});
+	app.get("/api/local-apps/preview/:token/snapshots/:sourceHash/*", (c) => {
+		const sourceHash = LocalAppSourceHashSchema.safeParse(c.req.param("sourceHash"));
+		if (!sourceHash.success) return c.json({ error: "Invalid snapshot hash" }, 400);
+		const preview = service.localApps.resolveSnapshotPreview(c.req.param("token"), sourceHash.data);
+		if (!preview) return c.json({ error: "Preview not found" }, 404);
+		return servePreviewAsset(c, preview, `/api/local-apps/preview/${preview.previewToken}/snapshots/${sourceHash.data}/`, "private, max-age=31536000, immutable");
 	});
 }
 function registerLocalAppsRoutes(app, deps) {
@@ -79,6 +94,12 @@ function registerLocalAppsRoutes(app, deps) {
 			return capabilityHttpError(c, error);
 		}
 	});
+	app.get("/api/local-apps/:id/snapshots/:sourceHash", (c) => {
+		const sourceHash = LocalAppSourceHashSchema.safeParse(c.req.param("sourceHash"));
+		if (!sourceHash.success) return c.json({ error: "Invalid snapshot hash" }, 400);
+		const snapshot = deps.service.localApps.getSnapshot(c.req.param("id"), sourceHash.data);
+		return snapshot ? c.json({ snapshot }) : c.json({ error: "Snapshot not found" }, 404);
+	});
 	app.post("/api/local-apps/:id/validate", async (c) => {
 		try {
 			return c.json(await capabilities.call("xopc.local_apps.validate", { id: c.req.param("id") }, capabilityHttpContext(c)));
@@ -86,6 +107,17 @@ function registerLocalAppsRoutes(app, deps) {
 			return capabilityHttpError(c, error);
 		}
 	});
+	app.post("/api/local-apps/:id/fix-guidance", async (c) => {
+		try {
+			const body = await c.req.json().catch(() => {
+				throw new CapabilityError("INVALID_INPUT", "Invalid JSON body");
+			});
+			const guidance = deps.service.localApps.getFixGuidance(c.req.param("id"), parseLocalAppFixGuidanceInput(body));
+			return c.json({ guidance });
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
+	});
 	app.post("/api/local-apps/:id/acceptance-runs", async (c) => {
 		try {
 			const body = await c.req.json().catch(() => {

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

@@ -1,5 +1,7 @@
 import { isManagedConnectorServer } from "../../../connectors/materialize.js";
+import { AgentPluginStore } from "../../../extensions/agent-plugins/store.js";
 import { canonicalizeConfiguredMcpServer, normalizeConfiguredMcpServers } from "../../../config/mcp-config-normalize.js";
+import { savePluginAuthBinding } from "../../../extensions/agent-plugins/auth.js";
 import { loadMergedBundleMcpConfig } from "../../../agent/mcp/bundle-mcp-config.js";
 import { getWorkspacePath } from "../../../config/workspace-path-helpers.js";
 import { getMcpOAuthManager } from "../../../agent/mcp/oauth/mcp-oauth-manager.js";
@@ -20,12 +22,12 @@ function registerMcpRoutes(authenticated, deps) {
 			cfg
 		});
 		const configured = normalizeConfiguredMcpServers(cfg.mcp?.servers);
-		const oauthManager = getMcpOAuthManager();
-		const servers = await Promise.all(Object.entries(configured).map(async ([id, server]) => ({
+		const servers = await Promise.all(Object.entries(merged.config.mcpServers).map(async ([id, server]) => ({
 			id,
+			plugin: server.xopcPlugin,
 			managed: isManagedConnectorServer(server),
 			connectorId: isManagedConnectorServer(server) ? server.xopcConnector.connectorId : void 0,
-			oauth: await oauthManager.status(id, server)
+			oauth: await getMcpOAuthManager(server).status(id, server)
 		})));
 		return c.json({
 			ok: true,
@@ -76,9 +78,30 @@ function registerMcpRoutes(authenticated, deps) {
 		}, 404);
 		return c.json({
 			ok: true,
-			payload: await getMcpOAuthManager().status(id, server)
+			payload: await getMcpOAuthManager(server).status(id, server)
 		});
 	});
+	authenticated.post("/api/mcp/servers/:id/oauth/callback", deps.strictRateLimitMiddleware, async (c) => {
+		const id = c.req.param("id");
+		const server = resolveServer(id);
+		if (!server) return c.json({
+			ok: false,
+			error: "Unknown MCP server"
+		}, 404);
+		try {
+			const body = await c.req.json();
+			if (typeof body.callbackUrl !== "string" || body.callbackUrl.length > 16384) throw new Error("Expected callbackUrl");
+			return c.json({
+				ok: true,
+				payload: await getMcpOAuthManager(server).submitCallback(id, server, body.callbackUrl)
+			});
+		} catch {
+			return c.json({
+				ok: false,
+				error: "OAuth callback rejected; verify the URL and active authorization session"
+			}, 400);
+		}
+	});
 	authenticated.post("/api/mcp/servers/:id/oauth/start", deps.strictRateLimitMiddleware, async (c) => {
 		const id = c.req.param("id");
 		const server = resolveServer(id);
@@ -87,9 +110,12 @@ function registerMcpRoutes(authenticated, deps) {
 			error: `Unknown MCP server: ${id}`
 		}, 404);
 		try {
-			const payload = await getMcpOAuthManager().start({
+			const origin = server.xopcPlugin;
+			if (origin) await savePluginAuthBinding(new AgentPluginStore(), origin.id, origin.serverName, { mode: "oauth" });
+			const oauthServer = origin ? resolveServer(id) : server;
+			const payload = await getMcpOAuthManager(oauthServer).start({
 				serverId: id,
-				rawServer: server,
+				rawServer: oauthServer,
 				cfg: deps.service.currentConfig
 			});
 			return c.json({
@@ -111,7 +137,7 @@ function registerMcpRoutes(authenticated, deps) {
 			error: `Unknown MCP server: ${id}`
 		}, 404);
 		try {
-			const payload = await getMcpOAuthManager().disconnect(id, server);
+			const payload = await getMcpOAuthManager(server).disconnect(id, server);
 			return c.json({
 				ok: true,
 				payload
@@ -171,20 +197,25 @@ function registerMcpRoutes(authenticated, deps) {
 		const workspaceDir = getWorkspacePath(cfg) || "./workspace";
 		const body = await c.req.json().catch(() => ({}));
 		const inlineServer = body && typeof body === "object" && !Array.isArray(body) && body.server && typeof body.server === "object" ? body.server : void 0;
-		const servers = normalizeConfiguredMcpServers(cfg.mcp?.servers);
+		if (inlineServer && id.startsWith("plugin/")) return c.json({
+			ok: false,
+			error: "Plugin servers must use their installed configuration"
+		}, 400);
 		const mergedServers = loadMergedBundleMcpConfig({
 			workspaceDir,
 			cfg
 		}).config.mcpServers;
-		const knownServer = inlineServer ?? servers[id] ?? mergedServers[id];
+		const knownServer = inlineServer ?? mergedServers[id];
 		if (!knownServer) return c.json({
 			ok: false,
 			error: `Unknown MCP server: ${id}`
 		}, 404);
 		try {
-			const oauth = await getMcpOAuthManager().status(id, knownServer);
-			if (oauth.configured && oauth.status !== "connected") return c.json({
+			const oauth = await getMcpOAuthManager(knownServer).status(id, knownServer);
+			if (oauth.configured && knownServer.xopcAutoAuth !== true && oauth.status !== "connected") return c.json({
 				ok: false,
+				code: "MCP_AUTHORIZATION_REQUIRED",
+				serverId: id,
 				error: oauth.session?.error ?? "MCP server authorization is required"
 			}, 409);
 			const capabilities = await listBundleMcpServerCapabilitiesForGateway({
@@ -198,6 +229,12 @@ function registerMcpRoutes(authenticated, deps) {
 				} : cfg,
 				serverId: id
 			});
+			if (capabilities.error) return c.json({
+				ok: false,
+				code: capabilities.error.code,
+				serverId: id,
+				error: capabilities.error.message
+			}, capabilities.error.code === "MCP_AUTHORIZATION_REQUIRED" ? 409 : 502);
 			return c.json({
 				ok: true,
 				payload: {
@@ -212,16 +249,6 @@ function registerMcpRoutes(authenticated, deps) {
 			}, 500);
 		}
 	});
-	authenticated.post("/api/mcp/approvals/respond", async (c) => {
-		const body = await c.req.json().catch(() => ({}));
-		return c.json({
-			ok: true,
-			payload: {
-				acknowledged: true,
-				body
-			}
-		});
-	});
 }
 //#endregion
 export { registerMcpRoutes };

package/dist/src/gateway/hono/routes/session-input-handler.d.ts

@@ -53,6 +53,7 @@ export declare function submitSessionInput(c: Context, deps: AuthenticatedRouteD
                 };
                 attachments?: import("hono/dist/types/utils/types.js").JSONValue[];
                 contextRefs?: {
+                    refId?: string;
                     kind: import("../../../agent/source-context/types.js").AgentSourceContext["kind"];
                     sourceId: string;
                     version: string;
@@ -65,6 +66,7 @@ export declare function submitSessionInput(c: Context, deps: AuthenticatedRouteD
                     fileKind?: "file" | "directory";
                 }[];
                 contextSnapshots?: {
+                    refId?: string;
                     kind: import("../../../agent/source-context/types.js").SessionSourceBinding["kind"] | "task" | "file" | "session" | "mcp_resource" | "browser_tab" | "browser_page" | "app_context";
                     sourceId: string;
                     version: string;
@@ -189,6 +191,7 @@ export declare function replaceLatestSessionTurn(c: Context, deps: Authenticated
                 };
                 attachments?: import("hono/dist/types/utils/types.js").JSONValue[];
                 contextRefs?: {
+                    refId?: string;
                     kind: import("../../../agent/source-context/types.js").AgentSourceContext["kind"];
                     sourceId: string;
                     version: string;
@@ -201,6 +204,7 @@ export declare function replaceLatestSessionTurn(c: Context, deps: Authenticated
                     fileKind?: "file" | "directory";
                 }[];
                 contextSnapshots?: {
+                    refId?: string;
                     kind: import("../../../agent/source-context/types.js").SessionSourceBinding["kind"] | "task" | "file" | "session" | "mcp_resource" | "browser_tab" | "browser_page" | "app_context";
                     sourceId: string;
                     version: string;

package/dist/src/gateway/hono/routes/session-input-handler.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
+import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packages/gateway-contract/src/user-turn-document.js";
 import { browserPageContextsInputSchema } from "../../../../packages/gateway-contract/src/browser-page-context.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { endpointTurnClaimSchema, init_src as init_src$1 } from "../../../../packages/endpoint-tools-protocol/src/index.js";
@@ -24,6 +25,13 @@ init_providers();
 init_logger();
 const MAX_TURN_CONTEXTS = 5;
 const log = createLogger("Gateway:SessionInput");
+function contextDocumentIsValid(content, refs) {
+	if (!refs) return false;
+	const document = parseUserTurnDocument(content);
+	if (!document) return true;
+	const available = new Set(refs.flatMap((ref) => ref.refId ? [ref.refId] : []));
+	return userTurnDocumentRefIds(document).every((refId) => available.has(refId));
+}
 async function submitSessionInput(c, deps, conversationId, options) {
 	const body = await c.req.json().catch(() => null);
 	if (!body || !conversationId) return c.json({
@@ -51,6 +59,13 @@ async function submitSessionInput(c, deps, conversationId, options) {
 		}
 	}, 400);
 	const content = typeof body.content === "string" ? body.content : "";
+	if (!contextDocumentIsValid(content, contextRefs)) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: "Input contains an unknown context reference"
+		}
+	}, 400);
 	if (options?.taskConversation && isTaskDestructiveCommand(content)) return c.json({
 		ok: false,
 		error: {
@@ -239,6 +254,13 @@ async function replaceLatestSessionTurn(c, deps, conversationId, targetTurnId) {
 		}
 	}, 400);
 	const content = typeof body.content === "string" ? body.content : "";
+	if (!contextDocumentIsValid(content, contextRefs)) return c.json({
+		ok: false,
+		error: {
+			code: "BAD_REQUEST",
+			message: "Input contains an unknown context reference"
+		}
+	}, 400);
 	const contentError = validateWebchatContent(content);
 	if (contentError) return c.json({
 		ok: false,

package/dist/src/gateway/hono/routes/side-chats.js

@@ -157,6 +157,17 @@ function registerSideChatRoutes(authenticated, deps) {
 			return respondSideChatError(c, error);
 		}
 	});
+	authenticated.post("/api/side-chats/:sideChatId/promote", deps.chatRateLimitMiddleware, async (c) => {
+		try {
+			const result = await service.sideChatPromotions.promote(c.req.param("sideChatId"), readClientInstanceId(c));
+			return c.json({
+				ok: true,
+				...result
+			}, result.created ? 201 : 200);
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
 	authenticated.delete("/api/side-chats/:sideChatId", async (c) => {
 		try {
 			return await service.sideChatRuns.dispose(c.req.param("sideChatId"), readClientInstanceId(c)) ? c.json({ ok: true }) : c.json({

package/dist/src/gateway/service/agent-runner.js

@@ -87,7 +87,13 @@ var GatewayAgentRunner = class {
 					});
 				}
 				if (unique.size > MAX_TURN_CONTEXTS) throw new Error(`A message can reference at most ${MAX_TURN_CONTEXTS} sources`);
-				const contexts = await Promise.all([...unique.values()].map((ref) => opts.resolveTurnContext(ref, conversationId)));
+				const contexts = await Promise.all([...unique.values()].map(async (ref) => {
+					const context = await opts.resolveTurnContext(ref, conversationId);
+					return context && ref.refId ? {
+						...context,
+						refId: ref.refId
+					} : context;
+				}));
 				if (contexts.some((context) => context === null)) throw new Error("A referenced source is unavailable or has changed; select it again");
 				return fitSourceContextsToBudget(contexts.filter((context) => context !== null));
 			},

package/dist/src/gateway/service/marketplace-service.d.ts

@@ -52,6 +52,7 @@ export interface SkillSourceInstallResultPayload extends SkillInstallResultPaylo
     contentHash: string;
 }
 export interface ExtensionMarketplacePackageDetailPayload extends MarketplacePackageDetail {
+    format?: 'native-extension' | 'agent-plugin';
     installability: {
         available: boolean;
         reason?: string;

package/dist/src/gateway/service/marketplace-service.js

@@ -2,12 +2,14 @@ import { resolveStateDir } from "../../config/paths-state.js";
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_paths, resolveExtensionsDir } from "../../config/paths.js";
+import { getExtensionLockfileManager } from "../../extensions/lockfile.js";
+import { AgentPluginStore } from "../../extensions/agent-plugins/store.js";
 import { createSkillConfigManager } from "../../agent/skills/config.js";
 import { resolveWorkspaceSkillsDir, resolveWorkspaceSkillsLockPath } from "../../agent/skills/workspace-skills-dir.js";
 import { removeSkillsLockEntry } from "../../agent/skills/hub-lock.js";
 import { deleteManagedSkill, installSkillFromZip, listManagedSkillDirs } from "../../agent/skills/managed-store.js";
 import { normalizeSkillInstallTarget } from "../../agent/skills/install-target.js";
-import { getExtensionLockfileManager } from "../../extensions/lockfile.js";
+import { isAgentPluginArchive, withAgentPluginArchive } from "../../extensions/agent-plugins/sources.js";
 import { existsSync, rmSync } from "node:fs";
 //#region src/gateway/service/marketplace-service.ts
 /**
@@ -206,6 +208,18 @@ var GatewayMarketplaceService = class {
 			const resolved = await resolveExtensionZipDownloadUrl(base, packageName.trim());
 			const buffer = await downloadExtensionStoreZipBuffer(base, resolved.downloadUrl);
 			verifyStoreArtifactSha256(buffer, resolved.sha256);
+			if (isAgentPluginArchive(buffer)) {
+				const plan = withAgentPluginArchive(buffer, (path) => new AgentPluginStore().inspect(path));
+				return {
+					...detail,
+					format: "agent-plugin",
+					manifest: plan.manifest,
+					installability: {
+						available: true,
+						sha256: resolved.sha256
+					}
+				};
+			}
 			const { peekExtensionManifestFromStoreZip, peekExtensionPackageJsonFromStoreZip } = await import("../../extensions/install.js");
 			const manifest = peekExtensionManifestFromStoreZip(buffer);
 			const packageJson = peekExtensionPackageJsonFromStoreZip(buffer);

package/dist/src/gateway/service/session-input-coordinator.js

@@ -24,11 +24,11 @@ function sameAppContext(input, existing) {
 	return isDeepStrictEqual(identity(input.sourceContexts), identity(existing.contextSnapshots));
 }
 function contextRefsMatchFrozenSnapshot(requested, frozen) {
-	const editable = frozen?.filter((ref) => ref.kind === "note" || ref.kind === "task") ?? [];
+	const editable = frozen?.filter((ref) => ref.kind === "note" || ref.kind === "task" || ref.kind === "file" || ref.kind === "session" || ref.kind === "browser_tab" || ref.kind === "mcp_resource") ?? [];
 	if (requested.length !== editable.length) return false;
 	return requested.every((ref, index) => {
 		const snapshot = editable[index];
-		return snapshot?.kind === ref.kind && snapshot.sourceId === ref.sourceId && ref.expectedVersion === snapshot.version;
+		return snapshot?.kind === ref.kind && snapshot.sourceId === ref.sourceId && snapshot.refId === ref.refId && ref.expectedVersion === snapshot.version;
 	});
 }
 var SessionInputCoordinator = class {
@@ -311,7 +311,7 @@ var SessionInputCoordinator = class {
 			const existing = getSessionInputById(conversationId, id);
 			if (!contextRefsMatchFrozenSnapshot(body.contextRefs, existing?.contextRefs)) try {
 				const resolved = await this.deps.prepareContexts(conversationId, body.contextRefs) ?? [];
-				sourceContexts = fitSourceContextsToBudget([...existing?.contextSnapshots?.filter((source) => source.kind !== "note" && source.kind !== "task") ?? [], ...resolved]);
+				sourceContexts = fitSourceContextsToBudget([...existing?.contextSnapshots?.filter((source) => source.kind === "app_context" || source.kind === "browser_page") ?? [], ...resolved]);
 			} catch (err) {
 				log.warn({
 					err,

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

@@ -8,12 +8,13 @@ import { NotesService } from '../notes/index.js';
 import { WorkflowRunService } from '../workflows/service/workflow-run-service.js';
 import { ExtensionLoader } from '../extensions/index.js';
 import { SessionIndex } from '../session/index.js';
-import { EphemeralSideChatManager, SideChatRunService } from './side-chat/index.js';
+import { EphemeralSideChatManager, SideChatPromotionService, SideChatRunService } from './side-chat/index.js';
 import type { Config } from '../config/schema.js';
 import { type ResolvedGatewayAuth } from './auth.js';
 import { ModelCatalogSyncService } from '../providers/model-catalog-sync-service.js';
 import { ProjectService } from '../projects/index.js';
 import { LocalAppService } from '../local-apps/index.js';
+import { ChatPreviewService } from '../chat-previews/index.js';
 import { TaskConversationRepository } from '../tasks/task-conversation-repository.js';
 import { type BrowserAutomationService } from '../browser/automations/index.js';
 import { GatewaySessionsApi } from './service/sessions-api.js';
@@ -86,6 +87,7 @@ export declare class GatewayService {
     /** Process-local, non-persistent side conversations forked from durable sessions. */
     readonly sideChats: EphemeralSideChatManager;
     readonly sideChatRuns: SideChatRunService;
+    readonly sideChatPromotions: SideChatPromotionService;
     /**
      * Session CRUD / search / compaction / tag-archive-pin / stats — the gateway
      * REST surface for sessions. Routes should depend on this narrow service
@@ -107,6 +109,8 @@ export declare class GatewayService {
     readonly discussionSealer: DiscussionSealer;
     /** Local user-created apps, their coder projects, previews, and installs. */
     readonly localApps: LocalAppService;
+    /** Immutable, conversation-scoped UI previews that do not create projects. */
+    readonly chatPreviews: ChatPreviewService;
     get sceneAccess(): SceneAccess | undefined;
     constructor(serviceConfig?: GatewayServiceConfig);
     /** Lazy AgentService — constructed on first use or during `start()`. */

package/dist/src/gateway/service.js

@@ -64,6 +64,8 @@ import { ensureStarterAgentsInitialized } from "../agent/starter-agents.js";
 import { setPairingBroadcastSink } from "../channels/pairing/pairing-events.js";
 import { registerClarificationChannelRuntime } from "./clarify-runtime.js";
 import { ChannelManager } from "../channels/manager.js";
+import { ChatPreviewService } from "../chat-previews/service.js";
+import "../chat-previews/index.js";
 import { getWorkspacePath } from "../config/workspace-path-helpers.js";
 import "../config/index.js";
 import { ManagedComposioEventPoller } from "../connectors/composio-managed-events.js";
@@ -100,6 +102,7 @@ import { WorkflowRunService } from "../workflows/service/workflow-run-service.js
 import { WorkflowSessionBridge } from "../workflows/service/workflow-session-bridge.js";
 import { EphemeralSideChatManager } from "./side-chat/manager.js";
 import { SideChatRunService } from "./side-chat/run-service.js";
+import { SideChatPromotionService } from "./side-chat/promotion-service.js";
 import "./side-chat/index.js";
 import { wireTunnelEventsToGateway } from "../tunnel/gateway-lifecycle.js";
 import { getExposureManager } from "../remote-access/exposure-manager.js";
@@ -301,6 +304,7 @@ var GatewayService = class {
 	/** Process-local, non-persistent side conversations forked from durable sessions. */
 	sideChats;
 	sideChatRuns;
+	sideChatPromotions;
 	/**
 	* Session CRUD / search / compaction / tag-archive-pin / stats — the gateway
 	* REST surface for sessions. Routes should depend on this narrow service
@@ -329,6 +333,8 @@ var GatewayService = class {
 	discussionSealer;
 	/** Local user-created apps, their coder projects, previews, and installs. */
 	localApps;
+	/** Immutable, conversation-scoped UI previews that do not create projects. */
+	chatPreviews;
 	get sceneAccess() {
 		return this.sceneHost ? {
 			services: this.sceneHost.http,
@@ -467,6 +473,7 @@ var GatewayService = class {
 			getExtensionLoader: () => this.extensionLoader,
 			emit: (type, payload) => this.emit(type, payload)
 		});
+		this.chatPreviews = new ChatPreviewService({ localApps: this.localApps });
 		this.agentRunner = new GatewayAgentRunner({
 			validateConnectionResume: async (input) => {
 				for (const source of input.contextSnapshots ?? []) if (source.kind === "app_context") await checkAppContextAccess(source, this.appContextDispatcher(), this.auth);
@@ -529,6 +536,7 @@ var GatewayService = class {
 		let sideChatRuns;
 		this.sideChats = new EphemeralSideChatManager({
 			getParentMetadata: (conversationId) => this.sessionIndex.getSessionMetadata(conversationId),
+			getParentConfig: async (conversationId) => getSessionConfig(conversationId),
 			loadParentMessages: (conversationId) => this.sessionIndex.getStore().load(conversationId),
 			getDefaultModelRef: (conversationId) => this.ensureAgentService().getModelForSession(conversationId),
 			getDefaultThinkingLevel: (conversationId) => this.ensureAgentService().getThinkingLevelForSession(conversationId),
@@ -550,6 +558,11 @@ var GatewayService = class {
 			publishRealtime: (topic, event, data) => this.realtime.broker.publish(topic, event, data),
 			completeRealtimeTopic: (topic) => this.realtime.completeTopic(topic)
 		});
+		this.sideChatPromotions = new SideChatPromotionService({
+			manager: this.sideChats,
+			sessionIndex: this.sessionIndex,
+			getAgentService: () => this.ensureAgentService()
+		});
 		this.sessions = new GatewaySessionsApi({
 			sessionIndex: this.sessionIndex,
 			getAgentService: () => this.ensureAgentService(),
@@ -627,6 +640,7 @@ var GatewayService = class {
 			getProjectService: () => this.projects,
 			getWorkDiscovery: () => this._workDiscovery ?? void 0,
 			getLocalAppService: () => this.localApps,
+			getChatPreviewService: () => this.chatPreviews,
 			dispatchTaskEvents: () => this.dispatchTaskEvents(),
 			dispatchTaskRuns: () => this.dispatchTaskRuns(),
 			getWorkflowRunService: () => this.createWorkflowRunService(),

package/dist/src/gateway/side-chat/index.d.ts

@@ -1,5 +1,7 @@
 export { EphemeralSideChatManager, SideChatError, parseThinkingLevel } from './manager.js';
-export type { EphemeralSideChatManagerOptions } from './manager.js';
+export type { EphemeralSideChatManagerOptions, SideChatPromotionSnapshot } from './manager.js';
 export { validateSideChatSelections } from './context-snapshot.js';
 export { SideChatRunService } from './run-service.js';
+export { SideChatPromotionService } from './promotion-service.js';
+export type { SideChatPromotionResult, SideChatPromotionServiceOptions } from './promotion-service.js';
 export type { CreateSideChatInput, SideChatConfig, SideChatContextSnapshot, SideChatSelection, SideChatStatus, SideChatView, } from './types.js';

package/dist/src/gateway/side-chat/index.js

@@ -1,4 +1,5 @@
 import { validateSideChatSelections } from "./context-snapshot.js";
 import { EphemeralSideChatManager, SideChatError, parseThinkingLevel } from "./manager.js";
 import { SideChatRunService } from "./run-service.js";
-export { EphemeralSideChatManager, SideChatError, SideChatRunService, parseThinkingLevel, validateSideChatSelections };
+import { SideChatPromotionService } from "./promotion-service.js";
+export { EphemeralSideChatManager, SideChatError, SideChatPromotionService, SideChatRunService, parseThinkingLevel, validateSideChatSelections };

package/dist/src/gateway/side-chat/manager.d.ts

@@ -1,7 +1,18 @@
 import type { AgentMessage, ThinkingLevel } from '@earendil-works/pi-agent-core';
 import { InMemoryTranscriptRuntime } from '../../agent/embedded/transcript-runtime.js';
+import type { SessionAgentConfig } from '../../session/config-types.js';
+import type { TranscriptStoredRow } from '../../session/session-context-for-llm.js';
 import type { SessionMetadata } from '../../session/types.js';
 import type { CreateSideChatInput, SideChatConfig, SideChatStatus, SideChatView } from './types.js';
+export interface SideChatPromotionSnapshot {
+    id: string;
+    parentMetadata: SessionMetadata;
+    parentConfig: SessionAgentConfig | null;
+    context: SideChatView['context'];
+    config: SideChatConfig;
+    contextMessages: AgentMessage[];
+    conversationRows: TranscriptStoredRow[];
+}
 export declare class SideChatError extends Error {
     readonly code: 'INVALID_REQUEST' | 'NOT_FOUND' | 'PARENT_NOT_FOUND' | 'LIMIT_REACHED' | 'CAPACITY_REACHED' | 'CONFLICT' | 'EXPIRED';
     readonly reason?: 'idle' | 'waiting';
@@ -9,6 +20,7 @@ export declare class SideChatError extends Error {
 }
 export interface EphemeralSideChatManagerOptions {
     getParentMetadata: (conversationId: string) => Promise<SessionMetadata | null>;
+    getParentConfig?: (conversationId: string) => Promise<SessionAgentConfig | null>;
     loadParentMessages: (conversationId: string) => Promise<AgentMessage[]>;
     getDefaultModelRef: (conversationId: string) => string;
     getDefaultThinkingLevel?: (conversationId: string) => ThinkingLevel;
@@ -39,12 +51,16 @@ export declare class EphemeralSideChatManager {
     get(id: string, clientInstanceId: string): SideChatView;
     getRuntime(id: string, clientInstanceId: string): InMemoryTranscriptRuntime;
     getMessages(id: string, clientInstanceId: string): AgentMessage[];
+    beginPromotion(id: string, clientInstanceId: string): SideChatPromotionSnapshot;
+    cancelPromotion(id: string, clientInstanceId: string): void;
     updateConfig(id: string, clientInstanceId: string, patch: Partial<SideChatConfig>): SideChatView;
     heartbeat(id: string, clientInstanceId: string): SideChatView;
     extend(id: string, clientInstanceId: string): SideChatView;
     setStatus(id: string, clientInstanceId: string, status: SideChatStatus, runId?: string): SideChatView;
     waitForInput(id: string, clientInstanceId: string, clarification: NonNullable<SideChatView['clarification']>, status?: 'waiting-input' | 'waiting-approval'): void;
     dispose(id: string, clientInstanceId: string): Promise<boolean>;
+    disposePromoted(id: string, clientInstanceId: string): Promise<boolean>;
+    private disposeEntry;
     disposeClient(clientInstanceId: string): Promise<number>;
     sweepExpired(at?: number): Promise<number>;
     disposeAll(): Promise<void>;