@xopcai/xopc 0.0.196 → 0.0.197

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

@@ -0,0 +1,173 @@
+import { validateWebchatContent } from "../../chat-limits.js";
+import { validateSideChatSelections } from "../../side-chat/context-snapshot.js";
+import { SideChatError, parseThinkingLevel } from "../../side-chat/manager.js";
+import "../../side-chat/index.js";
+import { createGatewayRouteLogger, logRouteError } from "../lib/route-logger.js";
+//#region src/gateway/hono/routes/side-chats.ts
+const CLIENT_HEADER = "x-xopc-client-instance-id";
+const log = createGatewayRouteLogger("SideChats");
+function registerSideChatRoutes(authenticated, deps) {
+	const { service } = deps;
+	authenticated.post("/api/sessions/:parentSessionKey/side-chats", deps.chatRateLimitMiddleware, async (c) => {
+		try {
+			const body = await c.req.json().catch(() => ({}));
+			const clientInstanceId = readClientInstanceId(c, body.clientInstanceId);
+			if (body.modelRef !== void 0 && typeof body.modelRef !== "string") throw new SideChatError("modelRef must be a string", "INVALID_REQUEST");
+			const modelRef = typeof body.modelRef === "string" ? body.modelRef : void 0;
+			let selections;
+			try {
+				selections = validateSideChatSelections(body.selections);
+			} catch (error) {
+				throw new SideChatError(error instanceof Error ? error.message : "Invalid selections", "INVALID_REQUEST");
+			}
+			const sideChat = await service.sideChats.create({
+				parentSessionKey: c.req.param("parentSessionKey"),
+				clientInstanceId,
+				selections,
+				config: {
+					modelRef,
+					thinkingLevel: parseThinkingLevel(body.thinkingLevel)
+				}
+			});
+			return c.json({
+				ok: true,
+				sideChat
+			}, 201);
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+	authenticated.get("/api/side-chats/:sideChatId", (c) => {
+		try {
+			const sideChat = service.sideChats.get(c.req.param("sideChatId"), readClientInstanceId(c));
+			return c.json({
+				ok: true,
+				sideChat
+			});
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+	authenticated.get("/api/side-chats/:sideChatId/messages", (c) => {
+		try {
+			const messages = service.sideChats.getMessages(c.req.param("sideChatId"), readClientInstanceId(c));
+			return c.json({
+				ok: true,
+				messages
+			});
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+	authenticated.patch("/api/side-chats/:sideChatId/config", async (c) => {
+		try {
+			const body = await c.req.json().catch(() => ({}));
+			if (body.modelRef !== void 0 && typeof body.modelRef !== "string") throw new SideChatError("modelRef must be a string", "INVALID_REQUEST");
+			const modelRef = typeof body.modelRef === "string" ? body.modelRef : void 0;
+			const sideChat = service.sideChats.updateConfig(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), {
+				modelRef,
+				thinkingLevel: parseThinkingLevel(body.thinkingLevel)
+			});
+			return c.json({
+				ok: true,
+				sideChat
+			});
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+	authenticated.post("/api/side-chats/:sideChatId/heartbeat", (c) => {
+		try {
+			const sideChat = service.sideChats.heartbeat(c.req.param("sideChatId"), readClientInstanceId(c));
+			return c.json({
+				ok: true,
+				sideChat
+			});
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+	authenticated.post("/api/side-chats/:sideChatId/inputs", deps.chatRateLimitMiddleware, async (c) => {
+		try {
+			const body = await c.req.json().catch(() => ({}));
+			const content = typeof body.content === "string" ? body.content : "";
+			const contentError = validateWebchatContent(content);
+			if (contentError) throw new SideChatError(contentError, "INVALID_REQUEST");
+			const result = service.sideChatRuns.submit(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), content);
+			return c.json({
+				ok: true,
+				payload: result
+			}, 202);
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+	authenticated.post("/api/side-chats/:sideChatId/abort", deps.chatRateLimitMiddleware, async (c) => {
+		try {
+			const body = await c.req.json().catch(() => ({}));
+			const aborted = await service.sideChatRuns.abort(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), typeof body.runId === "string" ? body.runId : void 0);
+			return c.json({
+				ok: true,
+				payload: { aborted }
+			});
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+	authenticated.post("/api/side-chats/:sideChatId/clarify/:requestId", deps.chatRateLimitMiddleware, async (c) => {
+		try {
+			const body = await c.req.json().catch(() => ({}));
+			const answer = body.skip === true ? "" : typeof body.answer === "string" ? body.answer.trim() : "";
+			if (body.skip !== true && !answer) throw new SideChatError("answer is required", "INVALID_REQUEST");
+			if (!service.sideChatRuns.submitClarification(c.req.param("sideChatId"), readClientInstanceId(c, body.clientInstanceId), c.req.param("requestId"), answer)) throw new SideChatError("Clarification request not found", "NOT_FOUND");
+			return c.json({ ok: true });
+		} 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({
+				ok: false,
+				error: "Side chat not found",
+				code: "NOT_FOUND"
+			}, 404);
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+	authenticated.delete("/api/side-chats", async (c) => {
+		try {
+			const removed = await service.sideChats.disposeClient(readClientInstanceId(c, c.req.query("clientInstanceId")));
+			return c.json({
+				ok: true,
+				removed
+			});
+		} catch (error) {
+			return respondSideChatError(c, error);
+		}
+	});
+}
+function readClientInstanceId(c, fallback) {
+	const value = c.req.header(CLIENT_HEADER) || (typeof fallback === "string" ? fallback : "");
+	if (!value.trim()) throw new SideChatError("clientInstanceId is required", "INVALID_REQUEST");
+	return value.trim();
+}
+function respondSideChatError(c, error) {
+	if (!(error instanceof SideChatError)) {
+		logRouteError(log, c, error, "Side chat request failed");
+		return c.json({
+			ok: false,
+			error: "Side chat request failed",
+			code: "INTERNAL_ERROR"
+		}, 500);
+	}
+	const status = error.code === "NOT_FOUND" ? 404 : error.code === "CONFLICT" ? 409 : error.code === "LIMIT_REACHED" ? 429 : 400;
+	return c.json({
+		ok: false,
+		error: error.message,
+		code: error.code
+	}, status);
+}
+//#endregion
+export { registerSideChatRoutes };

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;