@xopcai/xopc 0.0.195 → 0.0.197

package/dist/src/gateway/hono/routes/understanding-sources.js

@@ -1,7 +1,7 @@
 import { deleteUnderstanding, listUnderstandingEvidence, listUnderstandings } from "../../../storage/sqlite/user-context-repository.js";
 import { getConnectorAccount } from "../../../storage/sqlite/connector-account-repository.js";
 import "../../../storage/sqlite/index.js";
-import { getUnderstandingSourceGrant, listUnderstandingSourceGrants, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus } from "../../../user-context/sources/repository.js";
+import { deleteUserFocus, getUnderstandingSourceGrant, listUnderstandingSourceGrants, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus } from "../../../user-context/sources/repository.js";
 import { getWorkDiscoveryService } from "./work-discovery.js";
 import { listUnderstandingSourceDefinitions } from "../../../user-context/sources/catalog.js";
 //#region src/gateway/hono/routes/understanding-sources.ts
@@ -199,6 +199,10 @@ function registerUnderstandingSourceRoutes(authenticated, deps) {
 			error: "Focus not found"
 		}, 404);
 	});
+	authenticated.delete("/api/understanding/focuses/:focusId", limited, (c) => deleteUserFocus(c.req.param("focusId")) ? c.json({ ok: true }) : c.json({
+		ok: false,
+		error: "Focus not found"
+	}, 404));
 }
 //#endregion
 export { registerUnderstandingSourceRoutes };

package/dist/src/gateway/service/agent-runner.d.ts

@@ -49,6 +49,7 @@ export declare class GatewayAgentRunner {
     private readonly clarifyBridge;
     /** Maps webchat session key → active `runId` for `clarify` tool routing. */
     private readonly activeWebchatRunBySession;
+    private readonly externalStreamBySession;
     readonly inputs: SessionInputCoordinator;
     constructor(opts: GatewayAgentRunnerOptions);
     /** True when a webchat agent run is currently in-flight for `sessionKey`. */
@@ -57,6 +58,9 @@ export declare class GatewayAgentRunner {
     getClarifyBridge(): ClarifyBridge;
     /** Called from `GatewayService.stop()` so the bridge gets cleaned up. */
     disposeClarifyBridge(): void;
+    registerExternalWebchatRun(sessionKey: string, runId: string, publish: (event: ClarifyStreamEvent) => void): void;
+    unregisterExternalWebchatRun(sessionKey: string, runId: string): void;
+    cancelClarificationForRun(runId: string): void;
     runAgent(message: string, channel: string, chatId: string, origin: TurnOrigin, attachments?: UserTurnAttachment[], thinking?: string, runOptions?: {
         signal?: AbortSignal;
         runId?: string;

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

@@ -16,6 +16,7 @@ var GatewayAgentRunner = class {
 	clarifyBridge = new ClarifyBridge();
 	/** Maps webchat session key → active `runId` for `clarify` tool routing. */
 	activeWebchatRunBySession = /* @__PURE__ */ new Map();
+	externalStreamBySession = /* @__PURE__ */ new Map();
 	inputs;
 	constructor(opts) {
 		this.opts = opts;
@@ -63,6 +64,19 @@ var GatewayAgentRunner = class {
 	disposeClarifyBridge() {
 		this.clarifyBridge.dispose();
 	}
+	registerExternalWebchatRun(sessionKey, runId, publish) {
+		this.activeWebchatRunBySession.set(sessionKey, runId);
+		this.externalStreamBySession.set(sessionKey, publish);
+	}
+	unregisterExternalWebchatRun(sessionKey, runId) {
+		if (this.activeWebchatRunBySession.get(sessionKey) === runId) {
+			this.activeWebchatRunBySession.delete(sessionKey);
+			this.externalStreamBySession.delete(sessionKey);
+		}
+	}
+	cancelClarificationForRun(runId) {
+		this.clarifyBridge.cancelForRun(runId);
+	}
 	async *runAgent(message, channel, chatId, origin, attachments, thinking, runOptions) {
 		const trackedRunId = runOptions?.runId;
 		if (trackedRunId) {
@@ -184,7 +198,7 @@ var GatewayAgentRunner = class {
 	async requestClarification(opts) {
 		const { sessionKey, request, publishStreamFor } = opts;
 		const runId = this.activeWebchatRunBySession.get(sessionKey);
-		const publishStream = runId ? publishStreamFor(runId) : void 0;
+		const publishStream = this.externalStreamBySession.get(sessionKey) ?? (runId ? publishStreamFor(runId) : void 0);
 		const deliver = ((await this.opts.sessionIndex.getSessionMetadata(sessionKey).catch(() => null))?.routing)?.source === "telegram" ? async (ctx) => {
 			await this.deliverTelegramClarify(ctx);
 		} : void 0;

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

@@ -9,9 +9,9 @@ import { TaskRunCoordinator } from "../../tasks/task-run-coordinator.js";
 import { formatAgentRunErrorForClient } from "../../agent/client-error-format.js";
 import { prependEnvelopeTimestamp } from "../../channels/envelope-timestamp.js";
 import "../chat-limits.js";
+import { ChatStreamMapper } from "../chat-stream/mapper.js";
 import { resolveWebchatSessionKey } from "../resolve-webchat-session-key.js";
 import { recordExplicitRelationshipFollowUp } from "../../user-context/relationship-continuity.js";
-import { ChatStreamMapper } from "../chat-stream/mapper.js";
 import { coalesceThinkingDeltas } from "../chat-stream/thinking-delta-coalescer.js";
 import crypto from "crypto";
 //#region src/gateway/service/run-gateway-agent.ts

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

@@ -6,6 +6,7 @@ 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 type { Config } from '../config/schema.js';
 import { type ResolvedGatewayAuth } from './auth.js';
 import { ModelCatalogSyncService } from '../providers/model-catalog-sync-service.js';
@@ -79,6 +80,9 @@ export declare class GatewayService {
      * `activeWebchatRunBySession` + `runAbortControllers` maps.
      */
     readonly agentRunner: GatewayAgentRunner;
+    /** Process-local, non-persistent side conversations forked from durable sessions. */
+    readonly sideChats: EphemeralSideChatManager;
+    readonly sideChatRuns: SideChatRunService;
     /**
      * Session CRUD / search / compaction / tag-archive-pin / stats — the gateway
      * REST surface for sessions. Routes should depend on this narrow service

package/dist/src/gateway/service.js

@@ -44,6 +44,7 @@ import { SessionIndex } from "../session/manager.js";
 import "../session/index.js";
 import { ExtensionLoader } from "../extensions/loader.js";
 import "../extensions/index.js";
+import { getEmbeddedExecutionSession } from "../agent/embedded/execution-context.js";
 import { MessageBus, MessageBusShutdownError } from "../infra/bus/queue.js";
 import "../infra/bus/index.js";
 import { AgentService } from "../agent/service.js";
@@ -77,6 +78,9 @@ import { WorkflowRunService } from "../workflows/service/workflow-run-service.js
 import { WorkflowSessionBridge } from "../workflows/service/workflow-session-bridge.js";
 import { HeartbeatService, heartbeatRunnerConfigFromConfig } from "./heartbeat/service.js";
 import "./heartbeat/index.js";
+import { EphemeralSideChatManager } from "./side-chat/manager.js";
+import { SideChatRunService } from "./side-chat/run-service.js";
+import "./side-chat/index.js";
 import { stopTailscaleExposure } from "./tailscale-lifecycle.js";
 import { getExposureManager } from "../remote-access/exposure-manager.js";
 import { assertGatewayAuthNotKnownWeak } from "./security/known-weak-secrets.js";
@@ -190,6 +194,9 @@ var GatewayService = class {
 	* `activeWebchatRunBySession` + `runAbortControllers` maps.
 	*/
 	agentRunner;
+	/** Process-local, non-persistent side conversations forked from durable sessions. */
+	sideChats;
+	sideChatRuns;
 	/**
 	* Session CRUD / search / compaction / tag-archive-pin / stats — the gateway
 	* REST surface for sessions. Routes should depend on this narrow service
@@ -363,6 +370,21 @@ var GatewayService = class {
 			},
 			completeRealtimeTopic: (topic) => this.realtime.completeTopic(topic)
 		});
+		let sideChatRuns;
+		this.sideChats = new EphemeralSideChatManager({
+			getParentMetadata: (sessionKey) => this.sessionIndex.getSessionMetadata(sessionKey),
+			loadParentMessages: (sessionKey) => this.sessionIndex.getStore().load(sessionKey),
+			getDefaultModelRef: (sessionKey) => this.ensureAgentService().getModelForSession(sessionKey),
+			getWorkspacePath: (metadata) => metadata.cwd || this.currentWorkspacePath,
+			onBeforeDispose: (sideChatId, clientInstanceId) => sideChatRuns?.abort(sideChatId, clientInstanceId).then(() => void 0)
+		});
+		this.sideChatRuns = sideChatRuns = new SideChatRunService({
+			manager: this.sideChats,
+			getAgentService: () => this.ensureAgentService(),
+			agentRunner: this.agentRunner,
+			publishRealtime: (topic, event, data) => this.realtime.broker.publish(topic, event, data),
+			completeRealtimeTopic: (topic) => this.realtime.completeTopic(topic)
+		});
 		this.sessions = new GatewaySessionsApi({
 			sessionIndex: this.sessionIndex,
 			getAgentService: () => this.ensureAgentService(),
@@ -452,13 +474,16 @@ var GatewayService = class {
 				}
 				return null;
 			},
-			gatewayClarify: { requestClarification: (sessionKey, request) => this.agentRunner.requestClarification({
-				sessionKey,
-				request,
-				publishStreamFor: (_runId) => (event) => {
-					this._agentService.turnDispatcher.enqueueWebchatStreamEvent(sessionKey, event);
-				}
-			}) }
+			gatewayClarify: { requestClarification: (sessionKey, request) => {
+				const executionSessionKey = getEmbeddedExecutionSession() ?? sessionKey;
+				return this.agentRunner.requestClarification({
+					sessionKey: executionSessionKey,
+					request,
+					publishStreamFor: (_runId) => (event) => {
+						this._agentService.turnDispatcher.enqueueWebchatStreamEvent(executionSessionKey, event);
+					}
+				});
+			} }
 		});
 		this._agentService.setChannelManager(this.channelManager);
 		this.channelManager.setSessionModelHooks({
@@ -988,6 +1013,7 @@ var GatewayService = class {
 		log.debug("Stopping gateway service...");
 		this.readiness.markStarting();
 		this.endpointTools.close();
+		await this.sideChats.disposeAll();
 		this.realtime.close();
 		await this.proactiveWorker.stop();
 		await this.discussionWorker.stop();

package/dist/src/gateway/side-chat/context-snapshot.d.ts

@@ -0,0 +1,11 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { SideChatContextSnapshot, SideChatSelection } from './types.js';
+export declare function validateSideChatSelections(value: unknown): SideChatSelection[];
+export declare function createSideChatContextSnapshot(params: {
+    parentSessionKey: string;
+    parentSessionId: string;
+    parentMessages: readonly AgentMessage[];
+    selections: readonly SideChatSelection[];
+    createdAt: string;
+}): SideChatContextSnapshot;
+export declare function formatSideChatSelections(selections: readonly SideChatSelection[]): string | null;

package/dist/src/gateway/side-chat/context-snapshot.js

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+//#region src/gateway/side-chat/context-snapshot.ts
+const MAX_SELECTIONS = 20;
+const MAX_SELECTION_CHARS = 32e3;
+const MAX_TOTAL_SELECTION_CHARS = 128e3;
+function selectionText(selection) {
+	switch (selection.type) {
+		case "message": return selection.content;
+		case "text": return selection.text;
+		case "file-range": return selection.text;
+		case "diff": return selection.diff;
+	}
+}
+function validateSideChatSelections(value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) throw new Error("selections must be an array");
+	if (value.length > MAX_SELECTIONS) throw new Error(`selections cannot exceed ${MAX_SELECTIONS} items`);
+	let totalChars = 0;
+	const selections = value.map((candidate, index) => {
+		if (!candidate || typeof candidate !== "object") throw new Error(`selection ${index} must be an object`);
+		const selection = candidate;
+		const id = typeof selection.id === "string" ? selection.id.trim() : "";
+		const type = selection.type;
+		if (!id) throw new Error(`selection ${index} requires id`);
+		let normalized;
+		if (type === "message") normalized = {
+			id,
+			type,
+			messageId: requiredString(selection.messageId, `selection ${index} messageId`),
+			role: requiredString(selection.role, `selection ${index} role`),
+			content: requiredString(selection.content, `selection ${index} content`),
+			label: optionalString(selection.label)
+		};
+		else if (type === "text") normalized = {
+			id,
+			type,
+			text: requiredString(selection.text, `selection ${index} text`),
+			sourceMessageId: optionalString(selection.sourceMessageId),
+			label: optionalString(selection.label)
+		};
+		else if (type === "file-range") {
+			const startLine = positiveInteger(selection.startLine, `selection ${index} startLine`);
+			const endLine = positiveInteger(selection.endLine, `selection ${index} endLine`);
+			if (endLine < startLine) throw new Error(`selection ${index} endLine must be >= startLine`);
+			normalized = {
+				id,
+				type,
+				path: requiredString(selection.path, `selection ${index} path`),
+				startLine,
+				endLine,
+				text: requiredString(selection.text, `selection ${index} text`),
+				contentHash: optionalString(selection.contentHash),
+				label: optionalString(selection.label)
+			};
+		} else if (type === "diff") normalized = {
+			id,
+			type,
+			diff: requiredString(selection.diff, `selection ${index} diff`),
+			path: optionalString(selection.path),
+			label: optionalString(selection.label)
+		};
+		else throw new Error(`selection ${index} has unsupported type`);
+		const chars = selectionText(normalized).length;
+		if (chars > MAX_SELECTION_CHARS) throw new Error(`selection ${index} exceeds ${MAX_SELECTION_CHARS} characters`);
+		totalChars += chars;
+		return normalized;
+	});
+	if (totalChars > MAX_TOTAL_SELECTION_CHARS) throw new Error(`selection content exceeds ${MAX_TOTAL_SELECTION_CHARS} characters`);
+	return selections;
+}
+function createSideChatContextSnapshot(params) {
+	const selections = structuredClone(params.selections);
+	const digest = createHash("sha256").update(JSON.stringify({
+		messages: params.parentMessages,
+		selections
+	})).digest("hex");
+	return {
+		parentSessionKey: params.parentSessionKey,
+		parentSessionId: params.parentSessionId,
+		parentMessageCount: params.parentMessages.length,
+		createdAt: params.createdAt,
+		selections,
+		contentHash: digest
+	};
+}
+function formatSideChatSelections(selections) {
+	if (selections.length === 0) return null;
+	return `The user attached the following immutable context snapshot to this side chat:\n\n${selections.map((selection, index) => {
+		const title = selection.label || `${selection.type} ${index + 1}`;
+		if (selection.type === "file-range") return `### ${title}\nSource: ${selection.path}:${selection.startLine}-${selection.endLine}\n\n${selection.text}`;
+		if (selection.type === "message") return `### ${title}\nSource message: ${selection.messageId} (${selection.role})\n\n${selection.content}`;
+		if (selection.type === "diff") return `### ${title}${selection.path ? `\nSource: ${selection.path}` : ""}\n\n${selection.diff}`;
+		return `### ${title}${selection.sourceMessageId ? `\nSource message: ${selection.sourceMessageId}` : ""}\n\n${selection.text}`;
+	}).join("\n\n")}`;
+}
+function requiredString(value, label) {
+	if (typeof value !== "string" || !value.trim()) throw new Error(`${label} is required`);
+	return value;
+}
+function optionalString(value) {
+	return typeof value === "string" && value.trim() ? value : void 0;
+}
+function positiveInteger(value, label) {
+	if (!Number.isInteger(value) || Number(value) < 1) throw new Error(`${label} must be a positive integer`);
+	return Number(value);
+}
+//#endregion
+export { createSideChatContextSnapshot, formatSideChatSelections, validateSideChatSelections };

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

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

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

@@ -0,0 +1,4 @@
+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 };

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

@@ -0,0 +1,45 @@
+import type { AgentMessage, ThinkingLevel } from '@earendil-works/pi-agent-core';
+import { InMemoryTranscriptRuntime } from '../../agent/embedded/transcript-runtime.js';
+import type { SessionMetadata } from '../../session/types.js';
+import type { CreateSideChatInput, SideChatConfig, SideChatStatus, SideChatView } from './types.js';
+export declare class SideChatError extends Error {
+    readonly code: 'INVALID_REQUEST' | 'NOT_FOUND' | 'LIMIT_REACHED' | 'CONFLICT';
+    constructor(message: string, code: 'INVALID_REQUEST' | 'NOT_FOUND' | 'LIMIT_REACHED' | 'CONFLICT');
+}
+export interface EphemeralSideChatManagerOptions {
+    getParentMetadata: (sessionKey: string) => Promise<SessionMetadata | null>;
+    loadParentMessages: (sessionKey: string) => Promise<AgentMessage[]>;
+    getDefaultModelRef: (sessionKey: string) => string;
+    getWorkspacePath: (metadata: SessionMetadata) => string;
+    idleTtlMs?: number;
+    maxPerClient?: number;
+    maxTotal?: number;
+    now?: () => number;
+    startSweepTimer?: boolean;
+    onBeforeDispose?: (sideChatId: string, clientInstanceId: string) => void | Promise<void>;
+}
+export declare class EphemeralSideChatManager {
+    private readonly options;
+    private readonly entries;
+    private readonly now;
+    private readonly idleTtlMs;
+    private readonly maxPerClient;
+    private readonly maxTotal;
+    private readonly sweepTimer;
+    constructor(options: EphemeralSideChatManagerOptions);
+    create(input: CreateSideChatInput): Promise<SideChatView>;
+    get(id: string, clientInstanceId: string): SideChatView;
+    getRuntime(id: string, clientInstanceId: string): InMemoryTranscriptRuntime;
+    getMessages(id: string, clientInstanceId: string): AgentMessage[];
+    updateConfig(id: string, clientInstanceId: string, patch: Partial<SideChatConfig>): SideChatView;
+    heartbeat(id: string, clientInstanceId: string): SideChatView;
+    setStatus(id: string, clientInstanceId: string, status: SideChatStatus): SideChatView;
+    dispose(id: string, clientInstanceId: string): Promise<boolean>;
+    disposeClient(clientInstanceId: string): Promise<number>;
+    sweepExpired(at?: number): Promise<number>;
+    disposeAll(): Promise<void>;
+    private requireEntry;
+    private touchEntry;
+    private runBeforeDispose;
+}
+export declare function parseThinkingLevel(value: unknown): ThinkingLevel | undefined;

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

@@ -0,0 +1,198 @@
+import { createLogger } from "../../utils/logger/index.js";
+import { init_logger } from "../../utils/logger.js";
+import { evictEmbeddedSessionRunner } from "../../agent/embedded/session-runner.js";
+import { InMemoryTranscriptRuntime } from "../../agent/embedded/transcript-runtime.js";
+import { createSideChatContextSnapshot, formatSideChatSelections, validateSideChatSelections } from "./context-snapshot.js";
+import { randomUUID } from "node:crypto";
+//#region src/gateway/side-chat/manager.ts
+init_logger();
+const DEFAULT_IDLE_TTL_MS = 1800 * 1e3;
+const DEFAULT_MAX_PER_CLIENT = 5;
+const DEFAULT_MAX_TOTAL = 50;
+const log = createLogger("Gateway:SideChat");
+var SideChatError = class extends Error {
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+	}
+};
+var EphemeralSideChatManager = class {
+	entries = /* @__PURE__ */ new Map();
+	now;
+	idleTtlMs;
+	maxPerClient;
+	maxTotal;
+	sweepTimer;
+	constructor(options) {
+		this.options = options;
+		this.now = options.now ?? Date.now;
+		this.idleTtlMs = options.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+		this.maxPerClient = options.maxPerClient ?? DEFAULT_MAX_PER_CLIENT;
+		this.maxTotal = options.maxTotal ?? DEFAULT_MAX_TOTAL;
+		this.sweepTimer = options.startSweepTimer === false ? null : setInterval(() => {
+			this.sweepExpired().catch((err) => {
+				log.warn({
+					err,
+					phase: "side_chat_sweep"
+				}, "Side chat expiry sweep failed");
+			});
+		}, Math.min(this.idleTtlMs, 6e4));
+		this.sweepTimer?.unref();
+	}
+	async create(input) {
+		const parentSessionKey = input.parentSessionKey.trim();
+		const clientInstanceId = input.clientInstanceId.trim();
+		if (!parentSessionKey || !clientInstanceId) throw new SideChatError("parentSessionKey and clientInstanceId are required", "INVALID_REQUEST");
+		if (this.entries.size >= this.maxTotal) throw new SideChatError("The side chat capacity has been reached", "LIMIT_REACHED");
+		if ([...this.entries.values()].filter((entry) => entry.clientInstanceId === clientInstanceId).length >= this.maxPerClient) throw new SideChatError(`A client can have at most ${this.maxPerClient} side chats`, "LIMIT_REACHED");
+		const metadata = await this.options.getParentMetadata(parentSessionKey);
+		if (!metadata || !metadata.sessionId) throw new SideChatError("Parent session not found", "NOT_FOUND");
+		const parentMessages = await this.options.loadParentMessages(parentSessionKey);
+		let selections;
+		try {
+			selections = validateSideChatSelections(input.selections);
+		} catch (error) {
+			throw new SideChatError(error instanceof Error ? error.message : "Invalid selections", "INVALID_REQUEST");
+		}
+		const now = this.now();
+		const createdAt = new Date(now).toISOString();
+		const id = randomUUID();
+		const runtime = new InMemoryTranscriptRuntime({
+			runtimeId: `${parentSessionKey}:side-chat:${id}`,
+			cwd: this.options.getWorkspacePath(metadata),
+			initialMessages: structuredClone(parentMessages)
+		});
+		const selectionContext = formatSideChatSelections(selections);
+		if (selectionContext) runtime.openSessionManager(this.options.getWorkspacePath(metadata)).appendCustomMessageEntry("side-chat-selection", selectionContext, false);
+		runtime.captureBaseline();
+		const config = {
+			modelRef: normalizeOptionalString(input.config?.modelRef) || this.options.getDefaultModelRef(parentSessionKey),
+			thinkingLevel: input.config?.thinkingLevel
+		};
+		const entry = {
+			id,
+			parentSessionKey,
+			clientInstanceId,
+			status: "idle",
+			createdAt,
+			lastActiveAt: createdAt,
+			expiresAt: new Date(now + this.idleTtlMs).toISOString(),
+			messageCount: 0,
+			context: createSideChatContextSnapshot({
+				parentSessionKey,
+				parentSessionId: metadata.sessionId,
+				parentMessages,
+				selections,
+				createdAt
+			}),
+			config,
+			runtime
+		};
+		this.entries.set(id, entry);
+		return toView(entry);
+	}
+	get(id, clientInstanceId) {
+		return toView(this.requireEntry(id, clientInstanceId));
+	}
+	getRuntime(id, clientInstanceId) {
+		return this.requireEntry(id, clientInstanceId).runtime;
+	}
+	getMessages(id, clientInstanceId) {
+		const entry = this.requireEntry(id, clientInstanceId);
+		const messages = entry.runtime.loadConversationMessages();
+		entry.messageCount = messages.length;
+		return structuredClone(messages);
+	}
+	updateConfig(id, clientInstanceId, patch) {
+		const entry = this.requireEntry(id, clientInstanceId);
+		if (entry.status === "running") throw new SideChatError("Cannot change config while a run is active", "CONFLICT");
+		const modelRef = patch.modelRef === void 0 ? entry.config.modelRef : normalizeOptionalString(patch.modelRef);
+		if (!modelRef) throw new SideChatError("modelRef cannot be empty", "INVALID_REQUEST");
+		entry.config = {
+			modelRef,
+			thinkingLevel: patch.thinkingLevel === void 0 ? entry.config.thinkingLevel : patch.thinkingLevel
+		};
+		this.touchEntry(entry);
+		return toView(entry);
+	}
+	heartbeat(id, clientInstanceId) {
+		const entry = this.requireEntry(id, clientInstanceId);
+		this.touchEntry(entry);
+		return toView(entry);
+	}
+	setStatus(id, clientInstanceId, status) {
+		const entry = this.requireEntry(id, clientInstanceId);
+		entry.status = status;
+		this.touchEntry(entry);
+		return toView(entry);
+	}
+	async dispose(id, clientInstanceId) {
+		const entry = this.entries.get(id);
+		if (!entry || entry.clientInstanceId !== clientInstanceId) return false;
+		entry.status = "closing";
+		await this.runBeforeDispose(id, clientInstanceId);
+		this.entries.delete(id);
+		await evictEmbeddedSessionRunner(entry.runtime.runtimeId, "side_chat_dispose");
+		return true;
+	}
+	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)));
+		return ids.length;
+	}
+	async sweepExpired(at = this.now()) {
+		const expired = [...this.entries.values()].filter((entry) => Date.parse(entry.expiresAt) <= at);
+		await Promise.all(expired.map((entry) => this.dispose(entry.id, entry.clientInstanceId)));
+		return expired.length;
+	}
+	async disposeAll() {
+		if (this.sweepTimer) clearInterval(this.sweepTimer);
+		const entries = [...this.entries.values()];
+		await Promise.all(entries.map((entry) => this.runBeforeDispose(entry.id, entry.clientInstanceId)));
+		this.entries.clear();
+		await Promise.all(entries.map((entry) => evictEmbeddedSessionRunner(entry.runtime.runtimeId, "side_chat_shutdown")));
+	}
+	requireEntry(id, clientInstanceId) {
+		const entry = this.entries.get(id);
+		if (!entry || entry.clientInstanceId !== clientInstanceId) throw new SideChatError("Side chat not found", "NOT_FOUND");
+		return entry;
+	}
+	touchEntry(entry) {
+		const now = this.now();
+		entry.lastActiveAt = new Date(now).toISOString();
+		entry.expiresAt = new Date(now + this.idleTtlMs).toISOString();
+	}
+	async runBeforeDispose(id, clientInstanceId) {
+		try {
+			await this.options.onBeforeDispose?.(id, clientInstanceId);
+		} catch (err) {
+			log.warn({
+				err,
+				sideChatId: id,
+				phase: "side_chat_abort"
+			}, "Side chat run cleanup failed");
+		}
+	}
+};
+function toView(entry) {
+	const { runtime: _runtime, ...view } = entry;
+	return structuredClone(view);
+}
+function normalizeOptionalString(value) {
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function parseThinkingLevel(value) {
+	if (value === void 0 || value === null || value === "") return void 0;
+	if (typeof value !== "string" || !new Set([
+		"off",
+		"minimal",
+		"low",
+		"medium",
+		"high",
+		"xhigh",
+		"max"
+	]).has(value)) throw new SideChatError("Invalid thinkingLevel", "INVALID_REQUEST");
+	return value;
+}
+//#endregion
+export { EphemeralSideChatManager, SideChatError, parseThinkingLevel };

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

@@ -0,0 +1,22 @@
+import type { AgentService } from '../../agent/service.js';
+import type { GatewayAgentRunner } from '../service/agent-runner.js';
+import { type EphemeralSideChatManager } from './manager.js';
+export interface SideChatRunServiceOptions {
+    manager: EphemeralSideChatManager;
+    getAgentService: () => AgentService;
+    agentRunner: GatewayAgentRunner;
+    publishRealtime: (topic: string, event: string, data: unknown) => void;
+    completeRealtimeTopic: (topic: string) => void;
+}
+export declare class SideChatRunService {
+    private readonly options;
+    private readonly activeBySideChat;
+    constructor(options: SideChatRunServiceOptions);
+    submit(sideChatId: string, clientInstanceId: string, content: string): {
+        runId: string;
+    };
+    abort(sideChatId: string, clientInstanceId: string, runId?: string): Promise<boolean>;
+    dispose(sideChatId: string, clientInstanceId: string): Promise<boolean>;
+    submitClarification(sideChatId: string, clientInstanceId: string, requestId: string, answer: string): boolean;
+    private execute;
+}