dsh-activity-pane 0.1.0

package/src/host.mjs

@@ -0,0 +1,207 @@
+// dsh-activity-pane 宿主侧：完成确认与错误提醒状态（R-01-002/AC-03、AC-05、AC-10～AC-13、R-01-010/AC-06，C-030、C-043）。
+//
+// 职责：
+//   1. 订阅 `session/event` 的 `turn/end`，把事件顶层 `time` 登记为会话的 `lastTurnEnd`，
+//      并登记回合结束原因 `lastTurnEndKind`（取 `data.reason.kind`，缺失/非法归一
+//      `'unknown'`）与 error 回合的错误信息 `lastTurnEndError`（截断至 ERROR_NOTE_MAX）；
+//   2. `POST /dsh-activity-pane/api/ack` 写回 `ackedAt`；
+//   3. `GET /dsh-activity-pane/api/acks` 全量快照；`GET /dsh-activity-pane/api/acks/stream` SSE 推送
+//      （连接即发全量、变更即广播）。
+//
+// 持久化：storageDomain 声明式 domain 表 `acks`（sessionId → { lastTurnEnd, lastTurnEndKind,
+// lastTurnEndError, ackedAt }）。
+// 设计约束（C-030）：不写会话日志、不依赖 sessionProjections、不引入客户端轮询；
+// 完成提醒成立 = 主会话 && 非 running && 无阻塞等待 && 非委托周期 && lastTurnEnd > ackedAt，
+// 错误提醒成立 = 主会话 && 非 running && 无阻塞等待 && 非委托周期 && lastTurnEndKind === 'error'
+// （不消费 ack 游标，C-043），判定在客户端纯函数完成，本侧只维护持久事实与广播。
+
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+import { z } from 'zod'
+import { truncateErrorNote } from './core.mjs'
+
+export const name = 'dsh-activity-pane'
+export const inject = ['storageDomain', 'webServer']
+
+const API_PATH = '/dsh-activity-pane/api'
+
+/** 每会话完成/错误登记：lastTurnEnd 最后回合结束时刻（事件 time，毫秒）、
+ *  lastTurnEndKind 回合结束原因（completed/blocked/max-tokens/aborted/error/unknown）、
+ *  lastTurnEndError error 回合的错误信息（截断，非 error 回合为 null）、ackedAt 确认时刻。
+ *  字段全部可选/可空：容纳升级前仅含 { lastTurnEnd, ackedAt } 的旧记录——
+ *  dsh-storage-domain 打开时对每条记录做 valueSchema.parse，缺失必填键会以 invalid-record
+ *  使整个 domain 打开失败、登记与确认写回永久挂起（C-043 Spec 轴审核发现）；写入侧恒写全字段。 */
+const ackRecord = z.object({
+	lastTurnEnd: z.number().nullable().optional(),
+	lastTurnEndKind: z.string().nullable().optional(),
+	lastTurnEndError: z.string().nullable().optional(),
+	ackedAt: z.number().nullable().optional(),
+})
+
+const domainSpec = defineDomain({
+	name: 'dsh_activity_pane',
+	version: 1,
+	global: { schema: z.object({}), initial: {} },
+	tables: {
+		acks: domainTable(ackRecord),
+	},
+})
+
+/** 从请求流读取 JSON body；空 body 返回 null。 */
+function readJsonBody(req) {
+	return new Promise((resolve) => {
+		const chunks = []
+		req.on('data', (chunk) => chunks.push(chunk))
+		req.on('end', () => {
+			if (chunks.length === 0) return resolve(null)
+			try {
+				resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+			} catch {
+				resolve(null)
+			}
+		})
+		req.on('error', () => resolve(null))
+	})
+}
+
+export function apply(ctx) {
+	// domain 就绪 Promise：路由与事件登记都先等它（storageDomain.open 是异步的）。
+	let resolveDomain = null
+	const domainReady = new Promise((resolve) => {
+		resolveDomain = resolve
+	})
+	let acks = null // KvTable: sessionId -> { lastTurnEnd, lastTurnEndKind, lastTurnEndError, ackedAt }
+	/** SSE 连接集合：广播时逐个写 `event: state`。 */
+	const streamClients = new Set()
+
+	ctx.inject(['storageDomain'], async (domainCtx) => {
+		const domain = await domainCtx.storageDomain.open(domainSpec)
+		ctx.effect(() => () => domain.close(), 'dsh-activity-pane: domainClose')
+		acks = domain.table('acks')
+		resolveDomain()
+	})
+
+	/** 全量快照：{ [sessionId]: { lastTurnEnd, lastTurnEndKind, lastTurnEndError, ackedAt } }。
+ *  acks 未就绪时返回空对象。旧记录缺新字段时按 null/undefined 下发（客户端判定恒安全）。 */
+	function snapshot() {
+		const out = {}
+		if (acks === null) return out
+		for (const [id, record] of acks.entries()) out[id] = record
+		return out
+	}
+
+	/** 向全部 SSE 连接广播当前全量状态；写失败（连接已断）的连接直接移除。 */
+	function broadcast() {
+		const data = `event: state\ndata: ${JSON.stringify(snapshot())}\n\n`
+		for (const res of streamClients) {
+			try {
+				res.write(data)
+			} catch {
+				streamClients.delete(res)
+			}
+		}
+	}
+
+	// turn/end 登记（R-01-002/AC-03、AC-11～AC-13、C-043）：事件按会话序提交，get+put 无竞态；
+	// 保留既有 ackedAt（回合更替不清确认游标），lastTurnEnd 前移即让旧提醒失效、新提醒成立；
+	// 同回合登记结束原因与错误信息（错误提醒的持久事实来源）。
+	ctx.on('session/event', async (session, event) => {
+		if (event?.type !== 'turn/end') return
+		const time = Number(event.time)
+		if (!Number.isFinite(time)) return
+		const id = String(session?.id ?? '')
+		if (id === '') return
+		try {
+			await domainReady
+			const reason = event.data && typeof event.data === 'object' && event.data.reason && typeof event.data.reason === 'object'
+				? event.data.reason
+				: null
+			const kind = typeof reason?.kind === 'string' ? reason.kind : 'unknown'
+			// 错误信息契约仅为字符串（agent-loop 的 LlmError failure.message）；非字符串不展示，
+			// 避免界面出现 "[object Object]"（C-043 复审收紧）。
+			const errorMessage = kind === 'error' && typeof reason?.error?.message === 'string' ? reason.error.message : ''
+			const current = acks.get(id)
+			await acks.put(id, {
+				lastTurnEnd: time,
+				lastTurnEndKind: kind,
+				lastTurnEndError: kind === 'error' && errorMessage !== '' ? truncateErrorNote(errorMessage) : null,
+				ackedAt: current?.ackedAt ?? null,
+			})
+			broadcast()
+		} catch (error) {
+			ctx.logger?.warn?.(`dsh-activity-pane: turn/end 登记失败（${id}）: ${String(error)}`)
+		}
+	})
+
+	// HTTP API（前缀挂载，handler 内按子路径分发）。
+	ctx.webServer.register({
+		path: API_PATH,
+		handler(req, res) {
+			const url = new URL(req.url || '/', 'http://dsh-activity-pane')
+			const route = url.pathname.slice(API_PATH.length)
+			const method = req.method || 'GET'
+			if (route === '/acks' && method === 'GET') {
+				res.writeHead(200, { 'Content-Type': 'application/json' })
+				res.end(JSON.stringify(snapshot()))
+				return
+			}
+			if (route === '/acks/stream' && method === 'GET') {
+				// SSE：连接即发全量快照，此后每次变更广播；浏览器 EventSource 自动重连，
+				// 重连时再收一次全量，状态必然收敛（R-01-002/AC-12）。
+				res.writeHead(200, {
+					'Content-Type': 'text/event-stream',
+					'Cache-Control': 'no-cache',
+					Connection: 'keep-alive',
+				})
+				const hello = `event: state\ndata: ${JSON.stringify(snapshot())}\n\n`
+				res.write(hello)
+				streamClients.add(res)
+				const remove = () => streamClients.delete(res)
+				req.on('close', remove)
+				res.on('close', remove)
+				return
+			}
+			if (route === '/ack' && method === 'POST') {
+				readJsonBody(req).then(async (body) => {
+					const sessionId = body !== null && typeof body?.sessionId === 'string' ? body.sessionId : ''
+					if (sessionId === '') {
+						res.writeHead(400, { 'Content-Type': 'application/json' })
+						res.end(JSON.stringify({ ok: false, error: 'sessionId 缺失或非法' }))
+						return
+					}
+					try {
+						await domainReady
+						const current = acks.get(sessionId)
+						// 确认写回只动 ackedAt：保留回合结束时刻、结束原因与错误信息（C-043）。
+						await acks.put(sessionId, {
+							lastTurnEnd: current?.lastTurnEnd ?? null,
+							lastTurnEndKind: current?.lastTurnEndKind ?? null,
+							lastTurnEndError: current?.lastTurnEndError ?? null,
+							ackedAt: Date.now(),
+						})
+						broadcast()
+						res.writeHead(200, { 'Content-Type': 'application/json' })
+						res.end(JSON.stringify({ ok: true }))
+					} catch (error) {
+						res.writeHead(500, { 'Content-Type': 'application/json' })
+						res.end(JSON.stringify({ ok: false, error: String(error) }))
+					}
+				})
+				return
+			}
+			res.writeHead(404, { 'Content-Type': 'application/json' })
+			res.end(JSON.stringify({ ok: false, error: 'not found' }))
+		},
+	})
+
+	// 卸载：关闭全部 SSE 连接；domain 由 ctx.effect 关闭。
+	return () => {
+		for (const res of streamClients) {
+			try {
+				res.end()
+			} catch {
+				/* 连接已断 */
+			}
+		}
+		streamClients.clear()
+	}
+}

package/src/navigation.mjs

@@ -0,0 +1,91 @@
+/**
+ * 为单张 card 绑定点击/键盘激活，并返回卸载函数。
+ * 事件处理读取 card 当前的 data-session-id，兼容同一 DOM 在渲染中复用。
+ */
+export function bindCardActivation(card, open) {
+	if (typeof card?.addEventListener !== "function" || typeof open !== "function")
+		return () => {};
+	const activate = (event) => {
+		if (event.type === "keydown" && event.key !== "Enter" && event.key !== " ") return;
+		if (event.type !== "click" && event.type !== "keydown") return;
+		const currentCard = event.currentTarget ?? card;
+		const sessionId = currentCard?.dataset?.sessionId;
+		if (typeof sessionId !== "string" || sessionId === "") return;
+		event.preventDefault?.();
+		event.stopPropagation?.();
+		open(sessionId);
+	};
+	card.addEventListener("click", activate);
+	card.addEventListener("keydown", activate);
+	return () => {
+		card.removeEventListener?.("click", activate);
+		card.removeEventListener?.("keydown", activate);
+	};
+}
+
+/**
+ * 判定卡片激活是否转为收起移动端抽屉（R-01-008/AC-06）：移动断点内抽屉打开、
+ * 且激活目标已是当前会话时，激活不再发起切换（避免无意义 open 与重试链），
+ * 改为收起抽屉直达会话。纯函数，无 DOM 假设。
+ */
+export function shouldDismissDrawerOnActivation({ targetId, currentId, mobile, drawerOpen } = {}) {
+	if (mobile !== true || drawerOpen !== true) return false;
+	return typeof targetId === "string" && targetId !== "" && targetId === currentId;
+}
+
+/**
+ * 调用 DSH 原生会话导航；由调用方决定失败后的 refresh/retry 策略。
+ * 不读取 sessions.list，避免用另一份可能已过期的快照拦截跳转。
+ */
+export function openSession(sessions, sessionId) {
+	if (typeof sessions?.open !== "function") return false;
+	try {
+		sessions.open(sessionId);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** 原生会话输入框（dsh-client-ui-conversation composer 的 textarea）。 */
+export const COMPOSER_SELECTOR = "textarea[data-phase]";
+
+/**
+ * 抑制切换会话后原生 composer 的自动聚焦（R-01-005/AC-01 移动端回归）。
+ * dsh-client-ui-conversation 的 composer 在 sessionId 变化的 effect 里
+ * focus 输入框（桌面便于立即输入）；移动视口下该聚焦会弹出软键盘遮挡会话。
+ * open 成功后立即 blur 一次（覆盖 composer 已持焦的情形），并在短暂窗口内
+ * 以捕获阶段 focusin 拦截随后的自动聚焦；窗口外用户主动聚焦不受影响。
+ */
+export function suppressComposerAutofocus(doc, scheduleTimeout = setTimeout, windowMs = 1200) {
+	if (typeof doc?.addEventListener !== "function") return;
+	const blurComposer = (el) => {
+		if (typeof el?.matches === "function" && el.matches(COMPOSER_SELECTOR)) el.blur?.();
+	};
+	blurComposer(doc.activeElement);
+	const onFocusIn = (event) => blurComposer(event?.target);
+	doc.addEventListener("focusin", onFocusIn, true);
+	scheduleTimeout(() => doc.removeEventListener?.("focusin", onFocusIn, true), windowMs);
+}
+
+/**
+ * 为移动端抽屉的透明遮罩绑定点击收起，并返回卸载函数。
+ * 抽屉与浮动开关位于遮罩之上，能到达遮罩的点击必然来自抽屉外部，
+ * 无需 contains 判定。触摸轻点经浏览器 tap→click 合成事件覆盖
+ * （与浮动开关、× 与卡片的既有交互一致，故仅绑 click），
+ * 不额外绑 touch 事件以避免双触发与滑动误收起（R-01-008/AC-03）。
+ */
+export function bindBackdropDismiss(backdrop, dismiss) {
+	if (typeof backdrop?.addEventListener !== "function" || typeof dismiss !== "function")
+		return () => {};
+	const onBackdropClick = (event) => {
+		if (event.type !== "click") return;
+		event.preventDefault?.();
+		event.stopPropagation?.();
+		dismiss();
+	};
+	backdrop.addEventListener("click", onBackdropClick);
+	return () => {
+		backdrop.removeEventListener?.("click", onBackdropClick);
+	};
+}