@xopcai/xopc 0.0.284 → 0.0.286

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

@@ -9,7 +9,7 @@ var FileReferenceRegistry = class {
 		const ref = {
 			id,
 			absolutePath: input.absolutePath,
-			sessionKey: input.sessionKey?.trim() || void 0,
+			conversationId: input.conversationId?.trim() || void 0,
 			scope: input.scope,
 			locationKind: input.locationKind,
 			capabilities: [...new Set(input.capabilities)],

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

@@ -8,9 +8,9 @@ const services = /* @__PURE__ */ new WeakMap();
 function getGatewayFileSpaceService(service) {
 	const existing = services.get(service);
 	if (existing) return existing;
-	const created = new FileSpaceService(() => service.currentConfig, service.projects, (sessionKey) => service.sessions.getEffectiveWorkspacePath(sessionKey), () => listSessionWorkspaceOverrides().map(({ sessionKey, workingDirectoryOverride }) => ({
-		sessionKey,
-		root: effectiveWorkspacePathForSession(service.currentConfig, sessionKey, { workingDirectoryOverride }, getProjectForSession(sessionKey))
+	const created = new FileSpaceService(() => service.currentConfig, service.projects, (conversationId) => service.sessions.getEffectiveWorkspacePath(conversationId), () => listSessionWorkspaceOverrides().map(({ conversationId, workingDirectoryOverride }) => ({
+		conversationId,
+		root: effectiveWorkspacePathForSession(service.currentConfig, conversationId, { workingDirectoryOverride }, getProjectForSession(conversationId))
 	})));
 	services.set(service, created);
 	return created;

package/dist/src/gateway/gateway-workflow-host.types.d.ts

@@ -3,7 +3,7 @@ import type { EndpointToolRuntime } from '../endpoint-tools/index.js';
 import type { MessageBus } from '../infra/bus/index.js';
 import type { SessionStore } from '../session/store.js';
 export interface GatewayWorkflowAgentSurface {
-    getModelForSession(sessionKey: string): string;
+    getModelForSession(conversationId: string): string;
 }
 /** Minimal gateway surface for workflow run + session bridge (breaks circular imports). */
 export interface GatewayWorkflowHost {

package/dist/src/gateway/heartbeat/check-store.d.ts

@@ -0,0 +1,18 @@
+import type { MessageBus } from '../../infra/bus/index.js';
+export interface HeartbeatCheck {
+    id: string;
+    startedAt: string;
+    completedAt: string | null;
+    status: string;
+    detail: string | null;
+    content: string | null;
+    deliveryStatus: string;
+    target: string | null;
+    chatId: string | null;
+}
+export declare function beginHeartbeatCheck(workspace: string): string;
+export declare function completeHeartbeatCheck(id: string, status: string, detail?: string, content?: string, target?: string, chatId?: string): void;
+export declare function recentHeartbeatChecks(workspace: string): HeartbeatCheck[];
+export declare function recoverHeartbeatChecks(workspace: string): void;
+/** Claim before publishing: an ambiguous bus handoff is never blindly replayed. */
+export declare function deliverHeartbeatChecks(workspace: string, bus: Pick<MessageBus, 'publishOutbound'>, target?: string, chatId?: string): Promise<void>;

package/dist/src/gateway/heartbeat/check-store.js

@@ -0,0 +1,74 @@
+import { getSqliteDatabase, init_transaction, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { proactiveChecksAllowed, proactivePreferences, quietHoursEnd } from "../../proactive/policy/service.js";
+import { reserveWorkspaceAttention } from "../../proactive/inbox/digest.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/gateway/heartbeat/check-store.ts
+init_transaction();
+function beginHeartbeatCheck(workspace) {
+	const id = randomUUID();
+	const now = /* @__PURE__ */ new Date();
+	const db = getSqliteDatabase();
+	db.prepare("DELETE FROM heartbeat_checks WHERE workspace_id = ? AND started_at < ?").run(workspace, (/* @__PURE__ */ new Date(now.getTime() - 30 * 864e5)).toISOString());
+	db.prepare("INSERT INTO heartbeat_checks(id, workspace_id, started_at, status, expires_at) VALUES (?, ?, ?, ?, ?)").run(id, workspace, now.toISOString(), "running", new Date(now.getTime() + 864e5).toISOString());
+	return id;
+}
+function completeHeartbeatCheck(id, status, detail, content, target, chatId) {
+	runSqliteWriteTransaction((db) => {
+		const row = db.prepare("SELECT workspace_id FROM heartbeat_checks WHERE id = ?").get(id);
+		const fingerprint = content ? createHash("sha256").update(JSON.stringify([
+			target,
+			chatId,
+			content.trim()
+		])).digest("hex") : null;
+		const delivery = fingerprint && db.prepare(`SELECT 1 FROM heartbeat_checks WHERE workspace_id = ? AND fingerprint = ?
+      AND delivery_status IN ('pending', 'sending', 'queued', 'unknown') AND expires_at > ? AND id <> ?`).get(row.workspace_id, fingerprint, (/* @__PURE__ */ new Date()).toISOString(), id) ? "duplicate" : status === "prepared" ? target && chatId ? "pending" : "no_target" : "none";
+		db.prepare(`UPDATE heartbeat_checks SET status = ?, detail = ?, content = ?, target = ?, chat_id = ?, fingerprint = ?,
+      delivery_status = ?, completed_at = ?, next_attempt_at = ? WHERE id = ? AND status = 'running'`).run(status, detail?.slice(0, 500) ?? null, content?.slice(0, 2e4) ?? null, target ?? null, chatId ?? null, fingerprint, delivery, (/* @__PURE__ */ new Date()).toISOString(), (/* @__PURE__ */ new Date()).toISOString(), id);
+	});
+}
+function recentHeartbeatChecks(workspace) {
+	return getSqliteDatabase().prepare(`SELECT id, started_at AS startedAt, completed_at AS completedAt, status, detail, content,
+    delivery_status AS deliveryStatus, target, chat_id AS chatId FROM heartbeat_checks WHERE workspace_id = ? ORDER BY started_at DESC, rowid DESC LIMIT 10`).all(workspace);
+}
+function recoverHeartbeatChecks(workspace) {
+	const db = getSqliteDatabase();
+	db.prepare("UPDATE heartbeat_checks SET delivery_status = 'unknown', detail = 'Delivery interrupted; verify before sending again' WHERE workspace_id = ? AND delivery_status = 'sending'").run(workspace);
+	db.prepare("UPDATE heartbeat_checks SET status = 'interrupted', completed_at = ? WHERE workspace_id = ? AND status = 'running'").run((/* @__PURE__ */ new Date()).toISOString(), workspace);
+}
+/** Claim before publishing: an ambiguous bus handoff is never blindly replayed. */
+async function deliverHeartbeatChecks(workspace, bus, target, chatId) {
+	const claim = runSqliteWriteTransaction((db) => {
+		const now = /* @__PURE__ */ new Date();
+		db.prepare("UPDATE heartbeat_checks SET delivery_status = 'expired' WHERE workspace_id = ? AND delivery_status = 'pending' AND expires_at <= ?").run(workspace, now.toISOString());
+		const row = db.prepare("SELECT * FROM heartbeat_checks WHERE workspace_id = ? AND delivery_status = 'pending' AND next_attempt_at <= ? ORDER BY started_at LIMIT 1").get(workspace, now.toISOString());
+		if (!row) return null;
+		if (row.target !== target || row.chat_id !== chatId) {
+			db.prepare("UPDATE heartbeat_checks SET delivery_status = 'cancelled', detail = 'Delivery target changed' WHERE id = ?").run(row.id);
+			return null;
+		}
+		const preferences = proactivePreferences(workspace);
+		if (!proactiveChecksAllowed(preferences, now) || preferences.notificationsMuted || preferences.level === "quiet") return null;
+		const quietEnd = quietHoursEnd(preferences, now);
+		if (quietEnd) {
+			db.prepare("UPDATE heartbeat_checks SET next_attempt_at = ? WHERE id = ?").run(quietEnd.toISOString(), row.id);
+			return null;
+		}
+		if (!reserveWorkspaceAttention(workspace, `heartbeat:${row.id}`, now)) return null;
+		db.prepare("UPDATE heartbeat_checks SET delivery_status = 'sending' WHERE id = ? AND delivery_status = 'pending'").run(row.id);
+		return row;
+	});
+	if (!claim) return;
+	try {
+		await bus.publishOutbound({
+			channel: claim.target,
+			chat_id: claim.chat_id,
+			content: claim.content,
+			type: "message"
+		});
+		getSqliteDatabase().prepare("UPDATE heartbeat_checks SET delivery_status = 'queued' WHERE id = ? AND delivery_status = 'sending'").run(claim.id);
+	} catch {
+		getSqliteDatabase().prepare("UPDATE heartbeat_checks SET delivery_status = 'unknown', detail = 'Outbound handoff failed; verify before sending again' WHERE id = ?").run(claim.id);
+	}
+}
+//#endregion
+export { beginHeartbeatCheck, completeHeartbeatCheck, deliverHeartbeatChecks, recentHeartbeatChecks, recoverHeartbeatChecks };

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

@@ -24,13 +24,16 @@ export interface HeartbeatServiceDeps {
     sessionStore: SessionStore;
     /** Current app config (for HEARTBEAT.md path under the default agent `profile/` directory). */
     getConfig: () => Config;
+    getWorkspace: () => string;
 }
 export declare class HeartbeatService {
     private deps;
     private intervalId;
     private wake;
-    private lastHeartbeatText;
-    private lastHeartbeatAt;
+    private nextCheckAt;
+    private deliveryTimer;
+    private delivering;
+    private recovered;
     private runnerConfig;
     constructor(deps: HeartbeatServiceDeps);
     start(config: HeartbeatRunnerConfig): void;
@@ -41,6 +44,12 @@ export declare class HeartbeatService {
     stop(): void;
     updateConfig(config: Config): void;
     isRunning(): boolean;
+    status(): {
+        enabled: boolean;
+        checksAllowed: boolean;
+        nextCheckAt: string;
+        recent: import("./check-store.js").HeartbeatCheck[];
+    };
+    private drainDeliveries;
     private runHeartbeatOnce;
-    private isDuplicate;
 }

package/dist/src/gateway/heartbeat/service.js

@@ -1,13 +1,19 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope.js";
+import { createConversation, init_conversation_repository, resolveRoutedConversation } from "../../storage/sqlite/conversation-repository.js";
 import { shouldSilence, stripHeartbeatToken } from "../../heartbeat/tokens.js";
+import { proactiveChecksAllowed, proactivePreferences } from "../../proactive/policy/service.js";
 import { isWithinActiveHours } from "../../heartbeat/active-hours.js";
 import { isHeartbeatContentEmpty } from "../../heartbeat/content-check.js";
 import { appendCronEventLines } from "../../heartbeat/event-prompt.js";
 import { createHeartbeatWake } from "../../heartbeat/wake.js";
+import { beginHeartbeatCheck, completeHeartbeatCheck, deliverHeartbeatChecks, recentHeartbeatChecks, recoverHeartbeatChecks } from "./check-store.js";
 import { resolveHeartbeatMdPath } from "../workspace-heartbeat-path.js";
 import { readFile } from "fs/promises";
 //#region src/gateway/heartbeat/service.ts
+init_conversation_repository();
+init_agent_scope();
 init_logger();
 const log = createLogger("HeartbeatService");
 const DEFAULT_PROMPT = "Read HEARTBEAT.md if it exists. Follow it strictly. If nothing needs attention, reply HEARTBEAT_OK.";
@@ -31,22 +37,41 @@ function heartbeatRunnerConfigFromConfig(cfg) {
 var HeartbeatService = class {
 	intervalId = null;
 	wake;
-	lastHeartbeatText = "";
-	lastHeartbeatAt = 0;
+	nextCheckAt = null;
+	deliveryTimer = null;
+	delivering = false;
+	recovered = false;
 	runnerConfig = null;
 	constructor(deps) {
 		this.deps = deps;
-		this.wake = createHeartbeatWake((reasons) => this.runHeartbeatOnce(reasons));
+		this.wake = createHeartbeatWake(async (reasons) => {
+			try {
+				await this.runHeartbeatOnce(reasons);
+			} catch (err) {
+				log.error({ err }, "Heartbeat check failed unexpectedly");
+			}
+		});
 	}
 	start(config) {
+		if (this.runnerConfig) this.stop();
 		if (!config.enabled) {
 			log.info("Heartbeat disabled");
 			this.runnerConfig = null;
 			return;
 		}
 		this.runnerConfig = config;
+		if (!this.recovered) {
+			recoverHeartbeatChecks(this.deps.getWorkspace());
+			this.recovered = true;
+		}
+		this.deliveryTimer = setInterval(() => {
+			this.drainDeliveries().catch((err) => log.warn({ err }, "Heartbeat delivery check failed"));
+		}, 1e4);
+		this.deliveryTimer.unref?.();
+		this.nextCheckAt = new Date(Date.now() + config.intervalMs).toISOString();
 		log.info({ intervalMs: config.intervalMs }, "Heartbeat timer started (interval wake)");
 		this.intervalId = setInterval(() => {
+			this.nextCheckAt = new Date(Date.now() + config.intervalMs).toISOString();
 			this.wake.request({ reason: "interval" });
 		}, config.intervalMs);
 		this.intervalId.unref?.();
@@ -56,6 +81,9 @@ var HeartbeatService = class {
 		this.wake.request({ reason: opts?.reason ?? "manual" });
 	}
 	stop() {
+		if (this.deliveryTimer) clearInterval(this.deliveryTimer);
+		this.deliveryTimer = null;
+		this.nextCheckAt = null;
 		if (this.intervalId) {
 			clearInterval(this.intervalId);
 			this.intervalId = null;
@@ -73,6 +101,24 @@ var HeartbeatService = class {
 	isRunning() {
 		return this.intervalId !== null;
 	}
+	status() {
+		const preferences = proactivePreferences(this.deps.getWorkspace());
+		return {
+			enabled: Boolean(this.runnerConfig?.enabled),
+			checksAllowed: proactiveChecksAllowed(preferences),
+			nextCheckAt: proactiveChecksAllowed(preferences) ? this.nextCheckAt : null,
+			recent: recentHeartbeatChecks(this.deps.getWorkspace())
+		};
+	}
+	async drainDeliveries() {
+		if (this.delivering || !this.runnerConfig?.enabled) return;
+		this.delivering = true;
+		try {
+			await deliverHeartbeatChecks(this.deps.getWorkspace(), this.deps.messageBus, this.runnerConfig.target?.trim(), this.runnerConfig.targetChatId?.trim());
+		} finally {
+			this.delivering = false;
+		}
+	}
 	async runHeartbeatOnce(reasons) {
 		const reasonSummary = [...new Set(reasons)].join(", ") || "unknown";
 		const cfg = this.runnerConfig;
@@ -80,50 +126,58 @@ var HeartbeatService = class {
 			log.debug({ reasons: reasonSummary }, "Heartbeat: skip (disabled)");
 			return;
 		}
+		if (!proactiveChecksAllowed(proactivePreferences(this.deps.getWorkspace()))) return;
 		if (cfg.activeHours && !isWithinActiveHours(cfg.activeHours)) {
 			log.debug({ reasons: reasonSummary }, "Heartbeat: skip (outside active hours)");
 			return;
 		}
+		const checkId = beginHeartbeatCheck(this.deps.getWorkspace());
 		const heartbeatPath = resolveHeartbeatMdPath(this.deps.getConfig());
 		if (!heartbeatPath) {
-			log.debug({ reasons: reasonSummary }, "Heartbeat: skip (no HEARTBEAT path)");
+			completeHeartbeatCheck(checkId, "blocked", "No workspace checklist path");
 			return;
 		}
 		let heartbeatContent;
 		try {
 			const raw = await readFile(heartbeatPath, "utf-8");
 			if (isHeartbeatContentEmpty(raw)) {
-				log.debug({
-					path: heartbeatPath,
-					reasons: reasonSummary
-				}, "Heartbeat: skip (HEARTBEAT.md empty)");
+				completeHeartbeatCheck(checkId, "empty_checklist");
 				return;
 			}
 			heartbeatContent = raw.trim();
 		} catch {
-			log.debug({
-				path: heartbeatPath,
-				reasons: reasonSummary
-			}, "Heartbeat: HEARTBEAT.md missing; continuing");
+			completeHeartbeatCheck(checkId, "blocked", "Checklist could not be read");
+			return;
 		}
-		const sessionKey = cfg.isolatedSession ? `heartbeat:isolated:${Date.now()}` : "heartbeat:main";
+		const agentId = resolveDefaultAgentId(this.deps.getConfig());
+		const conversationId = cfg.isolatedSession ? createConversation({
+			agentId,
+			sourceChannel: "heartbeat",
+			sessionType: "heartbeat"
+		}).key : resolveRoutedConversation({
+			agentId,
+			source: "heartbeat",
+			peerKind: "direct",
+			peerId: "main"
+		}, { sessionType: "heartbeat" });
 		let basePrompt = (cfg.prompt?.trim() || DEFAULT_PROMPT).trim();
 		if (heartbeatContent) basePrompt = `${basePrompt}\n\n---\nHEARTBEAT.md:\n${heartbeatContent}\n---`;
 		basePrompt = appendCronEventLines(basePrompt, reasons);
+		basePrompt += "\nReturn notifications in your final response. Do not send messages, media or voice directly; delivery follows the user notification policy.";
 		const prompt = `${basePrompt}\n\nCurrent time: ${(/* @__PURE__ */ new Date()).toISOString()}`;
 		const ackMax = cfg.ackMaxChars ?? 300;
 		log.debug({
-			sessionKey,
+			conversationId,
 			reasons: reasonSummary
 		}, "Heartbeat: invoking agent");
-		if (sessionKey === "heartbeat:main") try {
-			await this.deps.sessionStore.saveMessages(sessionKey, [], { metadata: {
+		if (!cfg.isolatedSession) try {
+			await this.deps.sessionStore.saveMessages(conversationId, [], { metadata: {
 				sourceChannel: "heartbeat",
 				sourceChatId: "main",
 				sessionType: "heartbeat",
 				customData: { heartbeatTarget: "main" },
 				routing: {
-					agentId: "main",
+					agentId,
 					source: "heartbeat",
 					accountId: "default",
 					peerKind: "direct",
@@ -133,24 +187,31 @@ var HeartbeatService = class {
 		} catch (err) {
 			log.warn({
 				err,
-				sessionKey
+				conversationId
 			}, "Heartbeat: failed to reset main session transcript");
 		}
 		let reply;
 		try {
-			reply = await this.deps.agentService.turnDispatcher.processDirect(prompt, sessionKey, {
+			reply = await this.deps.agentService.turnDispatcher.processDirect(prompt, conversationId, {
 				type: "system",
 				source: "heartbeat"
 			});
 		} catch (error) {
+			completeHeartbeatCheck(checkId, "failed", "Agent check failed; see gateway logs");
 			log.error({ err: error }, "Heartbeat: agent call failed");
 			return;
 		}
+		if (cfg !== this.runnerConfig || !proactiveChecksAllowed(proactivePreferences(this.deps.getWorkspace()))) {
+			completeHeartbeatCheck(checkId, "cancelled", "Checks paused or configuration changed");
+			return;
+		}
 		if (!reply?.trim()) {
+			completeHeartbeatCheck(checkId, "no_change");
 			log.debug({ reasons: reasonSummary }, "Heartbeat: skip (empty model reply)");
 			return;
 		}
 		if (shouldSilence(reply, ackMax)) {
+			completeHeartbeatCheck(checkId, "no_change");
 			log.info({
 				ackMax,
 				replyChars: reply.length,
@@ -159,38 +220,8 @@ var HeartbeatService = class {
 			return;
 		}
 		const { stripped } = stripHeartbeatToken(reply);
-		const finalText = stripped || reply.trim();
-		if (this.isDuplicate(finalText)) {
-			log.info({
-				finalTextChars: finalText.length,
-				reasons: reasonSummary
-			}, "Heartbeat: not sent — duplicate within 24h");
-			return;
-		}
-		const target = cfg.target?.trim();
-		const targetChatId = cfg.targetChatId?.trim();
-		if (Boolean(target && targetChatId)) {
-			await this.deps.messageBus.publishOutbound({
-				channel: target,
-				chat_id: targetChatId,
-				content: finalText,
-				type: "message"
-			});
-			log.info({
-				reasons: reasonSummary,
-				channel: target,
-				chatId: targetChatId,
-				contentChars: finalText.length
-			}, "Heartbeat: sent — outbound queued");
-		} else log.info({
-			reasons: reasonSummary,
-			finalTextChars: finalText.length
-		}, "Heartbeat: not sent — no delivery target (set gateway.heartbeat.target + targetChatId)");
-		this.lastHeartbeatText = finalText;
-		this.lastHeartbeatAt = Date.now();
-	}
-	isDuplicate(text) {
-		return text.trim() === this.lastHeartbeatText.trim() && Date.now() - this.lastHeartbeatAt < 1440 * 60 * 1e3;
+		completeHeartbeatCheck(checkId, "prepared", void 0, stripped || reply.trim(), cfg.target?.trim(), cfg.targetChatId?.trim());
+		await this.drainDeliveries();
 	}
 };
 //#endregion

package/dist/src/gateway/hono/middleware/log-context.d.ts

@@ -1,5 +1,5 @@
 /**
  * Binds request (and optional session) correlation into AsyncLocalStorage so
- * all pino logs in the request inherit requestId / sessionId without a child logger.
+ * all pino logs in the request inherit requestId / transcriptId without a child logger.
  */
 export declare function logContextMiddleware(): import("hono/dist/types/types.js").MiddlewareHandler<any, string, {}, Response>;

package/dist/src/gateway/hono/middleware/log-context.js

@@ -7,17 +7,17 @@ import { createMiddleware } from "hono/factory";
 init_context();
 /**
 * Binds request (and optional session) correlation into AsyncLocalStorage so
-* all pino logs in the request inherit requestId / sessionId without a child logger.
+* all pino logs in the request inherit requestId / transcriptId without a child logger.
 */
 function logContextMiddleware() {
 	return createMiddleware(async (c, next) => {
 		const headerRequestId = c.req.header("x-request-id")?.trim();
 		const requestId = headerRequestId && headerRequestId.length > 0 ? headerRequestId : randomUUID();
-		const sessionHeader = c.req.header("x-session-id")?.trim();
+		const sessionHeader = c.req.header("x-transcript-id")?.trim();
 		c.header("X-Request-Id", requestId);
 		return runWithLogContext({
 			requestId,
-			...sessionHeader ? { sessionId: sessionHeader } : {}
+			...sessionHeader ? { transcriptId: sessionHeader } : {}
 		}, async () => {
 			await runWithActivityContext({ source: {
 				kind: "gateway_api",

package/dist/src/gateway/hono/routes/agent-stream.js

@@ -20,28 +20,28 @@ function registerAgentStreamRoutes(authenticated, deps) {
 			payload: result
 		});
 	});
-	authenticated.get("/api/sessions/:sessionKey/input-state", (c) => {
-		const sessionKey = (c.req.param("sessionKey") ?? "").trim();
-		if (!sessionKey) return c.json({
+	authenticated.get("/api/sessions/:conversationId/input-state", (c) => {
+		const conversationId = (c.req.param("conversationId") ?? "").trim();
+		if (!conversationId) return c.json({
 			ok: false,
 			error: {
 				code: "BAD_REQUEST",
-				message: "Missing sessionKey"
+				message: "Missing conversationId"
 			}
 		}, 400);
 		return c.json({
 			ok: true,
-			payload: service.getSessionInputState(sessionKey)
+			payload: service.getSessionInputState(conversationId)
 		});
 	});
-	authenticated.post("/api/sessions/:sessionKey/inputs", chatRateLimitMiddleware, async (c) => {
-		return submitSessionInput(c, deps, (c.req.param("sessionKey") ?? "").trim());
+	authenticated.post("/api/sessions/:conversationId/inputs", chatRateLimitMiddleware, async (c) => {
+		return submitSessionInput(c, deps, (c.req.param("conversationId") ?? "").trim());
 	});
-	authenticated.post("/api/sessions/:sessionKey/turns/:turnId/replace", chatRateLimitMiddleware, async (c) => {
-		return replaceLatestSessionTurn(c, deps, (c.req.param("sessionKey") ?? "").trim(), (c.req.param("turnId") ?? "").trim());
+	authenticated.post("/api/sessions/:conversationId/turns/:turnId/replace", chatRateLimitMiddleware, async (c) => {
+		return replaceLatestSessionTurn(c, deps, (c.req.param("conversationId") ?? "").trim(), (c.req.param("turnId") ?? "").trim());
 	});
-	authenticated.patch("/api/sessions/:sessionKey/inputs/:inputId", chatRateLimitMiddleware, async (c) => {
-		const sessionKey = (c.req.param("sessionKey") ?? "").trim();
+	authenticated.patch("/api/sessions/:conversationId/inputs/:inputId", chatRateLimitMiddleware, async (c) => {
+		const conversationId = (c.req.param("conversationId") ?? "").trim();
 		const inputId = c.req.param("inputId")?.trim() ?? "";
 		const body = await c.req.json().catch(() => null);
 		if (!body || typeof body.version !== "number") return c.json({
@@ -78,7 +78,7 @@ function registerAgentStreamRoutes(authenticated, deps) {
 				message: attachmentError
 			}
 		}, 400);
-		const result = await service.updateSessionInput(sessionKey, inputId, {
+		const result = await service.updateSessionInput(conversationId, inputId, {
 			version: body.version,
 			content: typeof body.content === "string" ? body.content : void 0,
 			attachments,
@@ -98,8 +98,8 @@ function registerAgentStreamRoutes(authenticated, deps) {
 			payload: result.state
 		}, 409);
 	});
-	authenticated.delete("/api/sessions/:sessionKey/inputs/:inputId", chatRateLimitMiddleware, (c) => {
-		const sessionKey = (c.req.param("sessionKey") ?? "").trim();
+	authenticated.delete("/api/sessions/:conversationId/inputs/:inputId", chatRateLimitMiddleware, (c) => {
+		const conversationId = (c.req.param("conversationId") ?? "").trim();
 		const inputId = c.req.param("inputId")?.trim() ?? "";
 		const version = Number(c.req.query("version"));
 		if (!Number.isFinite(version)) return c.json({
@@ -109,7 +109,7 @@ function registerAgentStreamRoutes(authenticated, deps) {
 				message: "Missing version"
 			}
 		}, 400);
-		const result = service.removeSessionInput(sessionKey, inputId, version);
+		const result = service.removeSessionInput(conversationId, inputId, version);
 		return result.ok ? c.json({
 			ok: true,
 			payload: result.state
@@ -122,16 +122,16 @@ function registerAgentStreamRoutes(authenticated, deps) {
 			payload: result.state
 		}, 409);
 	});
-	authenticated.get("/api/sessions/:sessionKey/clarification", (c) => {
-		const sessionKey = (c.req.param("sessionKey") ?? "").trim();
-		if (!sessionKey) return c.json({
+	authenticated.get("/api/sessions/:conversationId/clarification", (c) => {
+		const conversationId = (c.req.param("conversationId") ?? "").trim();
+		if (!conversationId) return c.json({
 			ok: false,
 			error: {
 				code: "BAD_REQUEST",
-				message: "Missing sessionKey"
+				message: "Missing conversationId"
 			}
 		}, 400);
-		const snapshot = service.getClarificationState(sessionKey);
+		const snapshot = service.getClarificationState(conversationId);
 		if (!snapshot) return c.json({
 			ok: false,
 			error: {

package/dist/src/gateway/hono/routes/browser-session.js

@@ -6,7 +6,7 @@ function registerBrowserSessionRoutes(app, deps) {
 	app.get("/api/browser-session", (c) => {
 		c.header("Cache-Control", "no-store");
 		const principal = getGatewayPrincipal(c);
-		return c.json({ sessionKey: principal.principalId });
+		return c.json({ conversationId: principal.principalId });
 	});
 	app.post("/api/browser-session", deps.strictRateLimitMiddleware, (c) => {
 		const principal = getGatewayPrincipal(c);
@@ -24,7 +24,7 @@ function registerBrowserSessionRoutes(app, deps) {
 		}
 		writeBrowserSessionCookie(c, session.token, session.expiresAt);
 		c.header("Cache-Control", "no-store");
-		return c.json({ sessionKey: `browser:${session.sessionId}` });
+		return c.json({ conversationId: `browser:${session.sessionId}` });
 	});
 	app.delete("/api/browser-session", (c) => {
 		if (!browserCookieRequestAllowed(c)) return c.json({ error: "Forbidden" }, 403);