@xopcai/xopc 0.0.320 → 0.0.323

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/config-coordinator.js

@@ -1,7 +1,7 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { getModelRegistry } from "../../providers/model-registry.js";
 import { loadConfig, saveConfig } from "../../config/loader.js";
+import { getModelRegistry } from "../../providers/model-registry.js";
 import { init_providers } from "../../providers/index.js";
 import { disposeAllSessionMcpRuntimes } from "../../agent/mcp/bundle-mcp-runtime.js";
 import { reloadImageGenerationProviders } from "../../agent/image/generation/provider-registry.js";

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

@@ -18,17 +18,17 @@ import { getSessionConfig } from "../storage/sqlite/config-repository.js";
 import "../storage/sqlite/index.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { init_agent_scope, listAgentEntries, normalizeAgentId, resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agent/agent-scope.js";
+import { init_agent_session_key, resolveAgentMainConversationId } from "../routing/agent-session-key.js";
+import { init_session_key, resolveConversationId, sanitizeSegment } from "../routing/session-key.js";
+import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
+import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths, resolveConfigPath, resolveExtensionsDir } from "../config/paths.js";
-import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { areExtensionsGloballyDisabled } from "../extensions/discover-extensions.js";
 import { buildExtensionMetadataSnapshot } from "../extensions/extension-metadata-snapshot.js";
 import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, init_channel_catalog_service } from "../channels/catalog/channel-catalog-service.js";
 import { loadConfig, saveConfig } from "../config/loader.js";
-import { init_agent_session_key, resolveAgentMainConversationId } from "../routing/agent-session-key.js";
-import { init_session_key, resolveConversationId, sanitizeSegment } from "../routing/session-key.js";
-import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
+import { prewarmModelRegistry } from "../providers/model-registry.js";
 import { init_providers, providers_exports } from "../providers/index.js";
-import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { TaskConversationRepository } from "../tasks/task-conversation-repository.js";
 import { getEmbeddedExecutionSession } from "../agent/embedded/execution-context.js";
 import { disposeAllSessionMcpRuntimes } from "../agent/mcp/bundle-mcp-runtime.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>;

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

@@ -70,6 +70,7 @@ var EphemeralSideChatManager = class {
 		const metadata = await this.options.getParentMetadata(parentConversationId);
 		if (!metadata || !metadata.transcriptId) throw new SideChatError("Parent session not found", "PARENT_NOT_FOUND");
 		const parentMessages = await this.options.loadParentMessages(parentConversationId);
+		const parentConfig = await this.options.getParentConfig?.(parentConversationId) ?? null;
 		if (this.stopped) throw new SideChatError("Gateway is stopping", "CAPACITY_REACHED");
 		let selections;
 		try {
@@ -110,7 +111,9 @@ var EphemeralSideChatManager = class {
 				createdAt
 			}),
 			config,
-			runtime
+			runtime,
+			parentMetadata: structuredClone(metadata),
+			parentConfig: structuredClone(parentConfig)
 		};
 		this.entries.set(id, entry);
 		return this.toView(entry);
@@ -127,6 +130,29 @@ var EphemeralSideChatManager = class {
 		entry.messageCount = messages.length;
 		return structuredClone(messages);
 	}
+	beginPromotion(id, clientInstanceId) {
+		const entry = this.requireEntry(id, clientInstanceId);
+		if (entry.status !== "idle") throw new SideChatError("Side chat is busy", "CONFLICT");
+		const conversationRows = entry.runtime.loadConversationRows();
+		if (entry.runtime.loadConversationMessages().length === 0) throw new SideChatError("Side chat has no messages to save", "INVALID_REQUEST");
+		entry.status = "promoting";
+		entry.expiresAt = null;
+		return structuredClone({
+			id: entry.id,
+			parentMetadata: entry.parentMetadata,
+			parentConfig: entry.parentConfig,
+			context: entry.context,
+			config: entry.config,
+			contextMessages: entry.runtime.loadBaselineMessages(),
+			conversationRows
+		});
+	}
+	cancelPromotion(id, clientInstanceId) {
+		const entry = this.requireEntry(id, clientInstanceId);
+		if (entry.status !== "promoting") return;
+		entry.status = "idle";
+		this.touchEntry(entry);
+	}
 	updateConfig(id, clientInstanceId, patch) {
 		const entry = this.requireEntry(id, clientInstanceId);
 		if (entry.status !== "idle") throw new SideChatError("Cannot change config while a run is active", "CONFLICT");
@@ -162,6 +188,14 @@ var EphemeralSideChatManager = class {
 		this.requireEntry(id, clientInstanceId).clarification = clarification;
 	}
 	async dispose(id, clientInstanceId) {
+		const entry = this.entries.get(id);
+		if (entry?.clientInstanceId === clientInstanceId && entry.status === "promoting") throw new SideChatError("Side chat is being saved", "CONFLICT");
+		return this.disposeEntry(id, clientInstanceId);
+	}
+	disposePromoted(id, clientInstanceId) {
+		return this.disposeEntry(id, clientInstanceId);
+	}
+	async disposeEntry(id, clientInstanceId) {
 		const entry = this.entries.get(id);
 		if (!entry) {
 			const pending = this.disposals.get(id);
@@ -187,8 +221,8 @@ var EphemeralSideChatManager = class {
 		return cleanup;
 	}
 	async disposeClient(clientInstanceId) {
-		const ids = [...this.entries.values()].filter((entry) => entry.clientInstanceId === clientInstanceId).map((entry) => entry.id);
-		await Promise.all(ids.map((id) => this.dispose(id, clientInstanceId)));
+		const ids = [...this.entries.values()].filter((entry) => entry.clientInstanceId === clientInstanceId && entry.status !== "promoting").map((entry) => entry.id);
+		await Promise.all(ids.map((id) => this.disposeEntry(id, clientInstanceId)));
 		return ids.length;
 	}
 	async sweepExpired(at = this.now()) {
@@ -201,7 +235,7 @@ var EphemeralSideChatManager = class {
 		if (this.sweepTimer) clearInterval(this.sweepTimer);
 		this.stopped = true;
 		const entries = [...this.entries.values()];
-		await Promise.all(entries.map((entry) => this.dispose(entry.id, entry.clientInstanceId)));
+		await Promise.all(entries.map((entry) => this.disposeEntry(entry.id, entry.clientInstanceId)));
 		await Promise.all([...this.disposals.values()].map((entry) => entry.promise));
 		this.expired.clear();
 	}
@@ -229,7 +263,7 @@ var EphemeralSideChatManager = class {
 			removeAt: this.now() + DEFAULT_IDLE_TTL_MS
 		});
 		this.pruneExpiredRecords(this.now());
-		const cleanup = this.dispose(entry.id, entry.clientInstanceId);
+		const cleanup = this.disposeEntry(entry.id, entry.clientInstanceId);
 		try {
 			this.options.onExpired?.(entry.id, entry.clientInstanceId, reason);
 		} catch (err) {
@@ -245,7 +279,7 @@ var EphemeralSideChatManager = class {
 		while (this.expired.size > MAX_EXPIRED_RECORDS) this.expired.delete(this.expired.keys().next().value);
 	}
 	toView(entry) {
-		const { runtime: _runtime, ...view } = entry;
+		const { runtime: _runtime, parentMetadata: _parentMetadata, parentConfig: _parentConfig, ...view } = entry;
 		return structuredClone({
 			...view,
 			serverNow: new Date(this.now()).toISOString()

package/dist/src/gateway/side-chat/promotion-service.d.ts

@@ -0,0 +1,19 @@
+import type { AgentService } from '../../agent/service.js';
+import type { SessionIndex } from '../../session/manager.js';
+import type { SessionMetadata } from '../../session/types.js';
+import { EphemeralSideChatManager } from './manager.js';
+export interface SideChatPromotionResult {
+    conversationId: string;
+    created: boolean;
+    session: SessionMetadata;
+}
+export interface SideChatPromotionServiceOptions {
+    manager: EphemeralSideChatManager;
+    sessionIndex: SessionIndex;
+    getAgentService: () => AgentService;
+}
+export declare class SideChatPromotionService {
+    private readonly options;
+    constructor(options: SideChatPromotionServiceOptions);
+    promote(sideChatId: string, clientInstanceId: string): Promise<SideChatPromotionResult>;
+}

package/dist/src/gateway/side-chat/promotion-service.js

@@ -0,0 +1,111 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { init_session_context_for_llm, isRuntimeOnlyTranscriptMessage } from "../../session/session-context-for-llm.js";
+import { SideChatError } from "./manager.js";
+//#region src/gateway/side-chat/promotion-service.ts
+init_session_context_for_llm();
+init_logger();
+const log = createLogger("Gateway:SideChatPromotion");
+var SideChatPromotionService = class {
+	constructor(options) {
+		this.options = options;
+	}
+	async promote(sideChatId, clientInstanceId) {
+		const existing = await this.options.sessionIndex.getSessionMetadata(sideChatId);
+		if (existing) {
+			if (existing.customData?.promotedFromSideChatId !== sideChatId) throw new SideChatError("A session already uses this side chat id", "CONFLICT");
+			return {
+				conversationId: sideChatId,
+				created: false,
+				session: existing
+			};
+		}
+		const snapshot = this.options.manager.beginPromotion(sideChatId, clientInstanceId);
+		const parent = snapshot.parentMetadata;
+		const agentId = parent.routing?.agentId?.trim() || parent.agentId;
+		const chatId = `chat_${sideChatId}`;
+		const rows = [{
+			type: "side_chat_origin",
+			version: 1,
+			parentConversationId: snapshot.context.parentConversationId,
+			parentTranscriptId: snapshot.context.parentTranscriptId,
+			createdAt: snapshot.context.createdAt,
+			contentHash: snapshot.context.contentHash,
+			contextMessages: snapshot.contextMessages
+		}, ...snapshot.conversationRows.filter((row) => !isRuntimeOnlyTranscriptMessage(row))];
+		try {
+			await this.options.sessionIndex.createSessionFromRows({
+				targetKey: sideChatId,
+				cwd: parent.cwd || "",
+				metadata: {
+					agentId,
+					sourceChannel: "webchat",
+					sourceChatId: `default:direct:${chatId}`,
+					sessionType: "chat",
+					tags: [...new Set([...parent.tags ?? [], "side-chat"])],
+					projectId: parent.projectId,
+					parentConversationId: snapshot.context.parentConversationId,
+					hiddenFromSessionList: false,
+					routing: {
+						agentId,
+						source: "webchat",
+						accountId: "default",
+						peerKind: "direct",
+						peerId: chatId
+					},
+					customData: {
+						genericNewChatShell: false,
+						promotedFromSideChatId: sideChatId,
+						promotedFromParentTranscriptId: snapshot.context.parentTranscriptId,
+						sideChatContextHash: snapshot.context.contentHash,
+						promotedAt: (/* @__PURE__ */ new Date()).toISOString()
+					}
+				},
+				rows,
+				config: {
+					...snapshot.parentConfig ?? {},
+					modelOverride: snapshot.config.modelRef,
+					thinkingLevel: snapshot.config.thinkingLevel
+				}
+			});
+		} catch (error) {
+			this.options.manager.cancelPromotion(sideChatId, clientInstanceId);
+			throw error;
+		}
+		const firstUserText = snapshot.conversationRows.find((row) => isAgentMessageWithRole(row, "user"));
+		if (firstUserText) try {
+			this.options.getAgentService().enqueueProvisionalSessionTitle(sideChatId, messageText(firstUserText));
+		} catch (err) {
+			log.warn({
+				err,
+				sideChatId,
+				phase: "side_chat_promote_title"
+			}, "Saved side chat but title generation could not start");
+		}
+		await this.options.manager.disposePromoted(sideChatId, clientInstanceId).catch((err) => {
+			log.warn({
+				err,
+				sideChatId,
+				phase: "side_chat_promote_cleanup"
+			}, "Saved side chat but cleanup failed");
+		});
+		const session = await this.options.sessionIndex.getSessionMetadata(sideChatId);
+		if (!session) throw new Error(`Promoted session not found: ${sideChatId}`);
+		return {
+			conversationId: sideChatId,
+			created: true,
+			session
+		};
+	}
+};
+function isAgentMessageWithRole(row, role) {
+	return Boolean(row && typeof row === "object" && row.role === role);
+}
+function messageText(message) {
+	const content = message.content;
+	if (typeof content === "string") return content.trim();
+	if (!Array.isArray(content)) return "";
+	return content.filter((part) => Boolean(part && typeof part === "object" && part.type === "text" && typeof part.text === "string")).map((part) => part.text).join("\n").trim();
+}
+//#endregion
+export { SideChatPromotionService };

package/dist/src/gateway/side-chat/run-service.js

@@ -16,6 +16,7 @@ var SideChatRunService = class {
 		const text = input.content.trim();
 		if (!text && !input.attachments?.length) throw new SideChatError("content or attachments are required", "INVALID_REQUEST");
 		const sideChat = this.options.manager.get(sideChatId, clientInstanceId);
+		if (sideChat.status !== "idle") throw new SideChatError("A side chat run is already active", "CONFLICT");
 		if (this.activeBySideChat.has(sideChatId)) throw new SideChatError("A side chat run is already active", "CONFLICT");
 		const run = {
 			sideChatId,

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

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
-export type SideChatStatus = 'idle' | 'running' | 'waiting-approval' | 'waiting-input' | 'closing';
+export type SideChatStatus = 'idle' | 'running' | 'waiting-approval' | 'waiting-input' | 'promoting' | 'closing';
 export type SideChatSelection = {
     id: string;
     type: 'message';

package/dist/src/local-apps/artifact-files.d.ts

@@ -0,0 +1,3 @@
+export declare function shouldCopyLocalAppPath(path: string): boolean;
+export declare function hashLocalAppDirectory(root: string): string;
+export declare function localAppFileHashes(root: string): Map<string, string>;

package/dist/src/local-apps/artifact-files.js

@@ -0,0 +1,45 @@
+import { basename, join, relative } from "node:path";
+import { readFileSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+//#region src/local-apps/artifact-files.ts
+const EXCLUDED_NAMES = new Set([
+	".git",
+	"node_modules",
+	".DS_Store"
+]);
+function shouldCopyLocalAppPath(path) {
+	return !EXCLUDED_NAMES.has(basename(path));
+}
+function hashLocalAppDirectory(root) {
+	const hash = createHash("sha256");
+	const visit = (dir) => {
+		const entries = readdirSync(dir, { withFileTypes: true }).filter((entry) => !EXCLUDED_NAMES.has(entry.name)).toSorted((a, b) => a.name.localeCompare(b.name));
+		for (const entry of entries) {
+			const path = join(dir, entry.name);
+			const relativePath = relative(root, path);
+			hash.update(relativePath);
+			if (entry.isDirectory()) visit(path);
+			else if (entry.isFile()) hash.update(readFileSync(path));
+			else throw new Error(`Unsupported local app entry: ${relativePath}`);
+		}
+	};
+	visit(root);
+	return hash.digest("hex");
+}
+function localAppFileHashes(root) {
+	const hashes = /* @__PURE__ */ new Map();
+	const visit = (dir) => {
+		const entries = readdirSync(dir, { withFileTypes: true }).filter((entry) => !EXCLUDED_NAMES.has(entry.name)).toSorted((a, b) => a.name.localeCompare(b.name));
+		for (const entry of entries) {
+			const path = join(dir, entry.name);
+			const relativePath = relative(root, path);
+			if (entry.isDirectory()) visit(path);
+			else if (entry.isFile()) hashes.set(relativePath, createHash("sha256").update(readFileSync(path)).digest("hex"));
+			else throw new Error(`Unsupported local app entry: ${relativePath}`);
+		}
+	};
+	visit(root);
+	return hashes;
+}
+//#endregion
+export { hashLocalAppDirectory, localAppFileHashes, shouldCopyLocalAppPath };