@deepseek-ai/dsh-client-connection 0.1.3-alpha.2 → 0.1.5-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/connection/README.md
-README.md: 4273c523039ddbc7b0644250800425c555c4c067
-README.zh.md: b416659b38a9f63d25842f7926a19eb78842e505
+README.md: 865c894403d2177e15085d0616289cf8950b555d
+README.zh.md: 3d299a4be7b3490298554982eed6d99fbba9718c

package/README.md

@@ -25,7 +25,7 @@ The package carries browser-to-Host Remote calls, exact Fetch responses, and con
 <a id="use-this-package"></a>
 ## Use this package
 
-The browser uses HTTP POST for Remote unary calls. API Gateway owns the `/api/remote.mux` WebSocket and its logical streams; in-process compositions provide equivalent Remote streams through `connection.rpc.open` without opening a WebSocket. The Host half owns the sole `/api` route, Fetch bridge, browser authentication, Host/Origin checks, and exact `GET`/`HEAD`/`POST` route registry. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by [`dsh-client-file-upload`](../file-upload/README.md).
+The browser uses HTTP POST for Remote unary calls. API Gateway owns the `/api/remote.mux` WebSocket and its logical streams; shell-owned compositions provide equivalent Remote streams through `connection.rpc.open` without opening a WebSocket. The Host half always provides the carrier-neutral RPC and exact `GET`/`HEAD`/`POST` route registries. When a Web carrier is present it also owns the sole `/api` route, Fetch bridge, browser authentication, and Host/Origin checks; a shell-owned carrier dispatches the shared Fetch handler directly. Each exact route declares buffered or streaming request-body handling before the bridge reads any bytes. Typert Gateway claims generated Remote endpoints, feature packages register non-JSON responses such as Session-log downloads and raw file uploads, and unclaimed requests return 404. Loopback hostname classification remains package-internal to the browser-facing Client state. Browser raw-body transfer is provided by [`dsh-client-file-upload`](../file-upload/README.md).
 
 -----
 

package/README.zh.md

@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-浏览器通过 HTTP POST 执行 Remote 一元调用。API Gateway 自己拥有 `/api/remote.mux` WebSocket 及其逻辑流。进程内组合通过 `connection.rpc.open` 提供等价的 Remote 流，不打开 WebSocket。Host half 拥有唯一 `/api` route、Fetch bridge、浏览器认证、Host/Origin 校验与精确 `GET`/`HEAD`/`POST` 路由注册表。每条精确路由会在 bridge 读取任何字节前声明缓冲或流式请求体处理方式。Typert Gateway 认领生成的 Remote endpoint，功能包注册 Session 日志下载、原始文件上传等非 JSON 响应，未认领的请求返回 404。Loopback hostname 判定只供浏览器侧当前页面状态使用，留在包内。浏览器原始请求体传输由 [`dsh-client-file-upload`](../file-upload/README.zh.md) 提供。
+浏览器通过 HTTP POST 执行 Remote 一元调用；API Gateway 自己拥有 `/api/remote.mux` WebSocket 及其逻辑流。由 shell 持有的组合通过 `connection.rpc.open` 提供等价的 Remote 流，不打开 WebSocket。Host half 始终提供与载体无关的 RPC 注册表和精确 `GET`/`HEAD`/`POST` 路由注册表。存在 Web 载体时，它还持有唯一 `/api` route、Fetch bridge、浏览器认证与 Host/Origin 校验；由 shell 持有的载体则直接分派共享 Fetch handler。每条精确路由会在 bridge 读取任何字节前声明缓冲或流式请求体处理方式。Typert Gateway 认领生成的 Remote endpoint，功能包注册 Session 日志下载、原始文件上传等非 JSON 响应，未认领的请求返回 404。Loopback hostname 判定只供浏览器侧当前页面状态使用，留在包内。浏览器原始请求体传输由 [`dsh-client-file-upload`](../file-upload/README.zh.md) 提供。
 
 -----
 

package/lib/client.js

@@ -1354,6 +1354,26 @@ window.__ModuleLoader__.load({
 			});
 		}
 		/**
+		* Create and freeze one identified system-role message holding a rendered
+		* system prompt.
+		* @param text - the complete rendered prompt; `''` records "no system prompt".
+		* @param plugin - the plugin that assembled the prompt.
+		* @returns an immutable system message with a fresh stable identity.
+		*/
+		function createSystemMessage(text, plugin) {
+			return createMessage({
+				role: "system",
+				content: text.length === 0 ? [] : [{
+					type: "text",
+					text
+				}],
+				source: {
+					kind: "plugin",
+					plugin
+				}
+			});
+		}
+		/**
 		* Create and freeze one identified tool-result message.
 		* @param input - call identity, raw result blocks, and outcome.
 		* @returns an immutable user-role tool-result message.
@@ -1671,6 +1691,86 @@ window.__ModuleLoader__.load({
 			return brandNumber(value);
 		}
 		//#endregion
+		//#region ../../core/session/lib/types/known-event-types.js
+		/**
+		* GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
+		* `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
+		* `pnpm run verify-persistence-catalog`, part of `doc-sync`).
+		* @module @deepseek-ai/dsh-session/known-event-types
+		*/
+		/**
+		* Every `SessionEventMap` member declared in this repository — the event
+		* vocabulary this build understands. The persistence read path refuses to
+		* interpret a log containing a type outside this set unless the event
+		* carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
+		* in `./types.ts`): such a log was likely written by a newer harness, and
+		* silently skipping a required event would reconstruct a wrong session.
+		* Downstream (out-of-repo) plugin events are outside this list by
+		* construction. The persisted `SessionEvent.ignorable` marker is the
+		* compatibility mechanism; event-name registration was rejected because
+		* it does not classify omission safety and would make reads
+		* composition-dependent. The rationale is in
+		* `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
+		*/
+		const KNOWN_SESSION_EVENT_TYPES = new Set([
+			"agent-preset/selected",
+			"agent/inbox/spliced",
+			"approval/asked",
+			"approval/decided",
+			"approval/policy",
+			"assistant/attempt",
+			"assistant/message",
+			"command/done",
+			"command/run",
+			"compaction/end",
+			"compaction/prune",
+			"compaction/start",
+			"compaction/summary",
+			"deliverables/presented",
+			"feedback/message-delete",
+			"feedback/message-put",
+			"feedback/record",
+			"goal/change",
+			"hook/invoked",
+			"hook/result",
+			"llm/retry",
+			"llm/retry-started",
+			"model/selection",
+			"permission/preset",
+			"plan/mode",
+			"request/context",
+			"request/header",
+			"sandbox/mode",
+			"schedule/change",
+			"session-log-deepseek/delivery-accepted",
+			"session/end-seed",
+			"session/title",
+			"session/title-llm-request",
+			"step/end",
+			"step/start",
+			"subagent/catalog",
+			"subagent/descriptor",
+			"subagent/model-selection-policy",
+			"system/message",
+			"team/member",
+			"team/message/delivered",
+			"team/message/queued",
+			"team/task",
+			"todo/write",
+			"tool-workflow/agent-end",
+			"tool-workflow/agent-start",
+			"tool-workflow/run-end",
+			"tool-workflow/run-start",
+			"tool/call",
+			"tool/ptc-dispatch",
+			"tool/ptc-dispatch-start",
+			"tool/result",
+			"turn/end",
+			"turn/start",
+			"user/message",
+			"web/deepseek-search-llm-request"
+		]);
+		//#endregion
 		//#region ../../core/session/lib/types/surface.js
 		/**
 		* Surface layer on top of the session event log: an ordered view of events
@@ -1683,6 +1783,7 @@ window.__ModuleLoader__.load({
 		*/
 		/** Runtime counterpart of the message-producing event union. */
 		const SURFACE_EVENT_TYPES = new Set([
+			"system/message",
 			"user/message",
 			"assistant/message",
 			"tool/result"
@@ -1690,7 +1791,7 @@ window.__ModuleLoader__.load({
 		/**
 		* Whether an event type can join the model-visible surface.
 		* @param type - event type to test.
-		* @returns true for one of the three message-producing event types.
+		* @returns true for one of the four message-producing event types.
 		*/
 		function isSurfaceEligibleType(type) {
 			return SURFACE_EVENT_TYPES.has(type);
@@ -1711,6 +1812,7 @@ window.__ModuleLoader__.load({
 		function deriveEventMessage(event) {
 			switch (event.type) {
 				case "user/message": return event.data;
+				case "system/message":
 				case "assistant/message":
 					if (event.data.message.content.length === 0) return null;
 					return event.data.message;
@@ -1732,12 +1834,13 @@ window.__ModuleLoader__.load({
 		/** Whether a runtime value is the exact positional-replacement shape. */
 		function isReplaceOp(value) {
 			const op = value;
-			return Object.keys(op).length === 3 && Object.hasOwn(op, "op") && Object.hasOwn(op, "start") && Object.hasOwn(op, "end") && op["op"] === "replace" && isEventSeq(op["start"]) && isEventSeq(op["end"]);
+			return Object.keys(op).length === 3 && Object.hasOwn(op, "op") && Object.hasOwn(op, "startSeq") && Object.hasOwn(op, "endSeq") && op["op"] === "replace" && isEventSeq(op["startSeq"]) && isEventSeq(op["endSeq"]);
 		}
 		/** Validate event-local surface eligibility and return its operation. */
 		function surfaceOpOf(event) {
 			const raw = event;
 			if (!isSurfaceEligibleType(event.type)) {
+				if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable === true) return;
 				if (raw.surfaceOp !== void 0) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry surfaceOp`);
 				if (raw.sourceEventSeqs !== void 0) throw new Error(`session event "${event.type}" is not surface-eligible and cannot carry sourceEventSeqs`);
 				return;
@@ -1769,13 +1872,26 @@ window.__ModuleLoader__.load({
 			const missing = shadowedSeqs.filter((seq) => !sources.has(seq));
 			if (missing.length > 0) throw new Error(`surface replace: sourceEventSeqs must include every shadowed surface node; missing ${missing.join(", ")}`);
 		}
+		/**
+		* Validate one event's surface metadata without checking membership in a log or surface.
+		* @param event - event whose marker and source sequence values are inspected.
+		* Unknown ignorable records retain opaque metadata and never change the surface.
+		* @returns the validated operation, or undefined for a log-only or unknown ignorable event.
+		* @throws when metadata violates event-local eligibility, marker, or source-sequence rules.
+		*/
+		function validateSurfaceMetadata(event) {
+			const op = surfaceOpOf(event);
+			if (op !== void 0 && op !== "append" && (op.startSeq >= event.seq || op.endSeq >= event.seq)) throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
+			if (op !== void 0) assertProvenance(event, []);
+			return op;
+		}
 		/** Locate one replacement range without mutating the current fold state. */
 		function replacementRange(state, op) {
-			const startIdx = state.nodes.indexOf(op.start);
-			if (startIdx === -1) throw new Error(`surface replace: start seq ${op.start} not found in surface`);
-			const endIdx = state.nodes.indexOf(op.end);
-			if (endIdx === -1) throw new Error(`surface replace: end seq ${op.end} not found in surface`);
-			if (startIdx > endIdx) throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`);
+			const startIdx = state.nodes.indexOf(op.startSeq);
+			if (startIdx === -1) throw new Error(`surface replace: start seq ${op.startSeq} not found in surface`);
+			const endIdx = state.nodes.indexOf(op.endSeq);
+			if (endIdx === -1) throw new Error(`surface replace: end seq ${op.endSeq} not found in surface`);
+			if (startIdx > endIdx) throw new Error(`surface replace: start seq ${op.startSeq} (index ${startIdx}) is after end seq ${op.endSeq} (index ${endIdx})`);
 			return {
 				startIdx,
 				endIdx,
@@ -1827,26 +1943,35 @@ window.__ModuleLoader__.load({
 				if (!isDeepEqualJson(originalRest, replacementRest)) throw new Error("tool/result surface replacement may change only content");
 			}
 		}
+		/**
+		* Protect the system prompt at surface node 0. A replacement covering node 0
+		* while that node is a `system/message` must itself be a `system/message` over
+		* exactly that node; later system nodes carry no protection and a compaction
+		* range may shadow them.
+		*/
+		function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, baseSeq) {
+			if (startIdx !== 0) return;
+			if (events[state.nodes[0] - baseSeq]?.type !== "system/message") return;
+			if (event.type !== "system/message" || shadowedSeqs.length !== 1) throw new Error("surface replace: node 0 holds the system prompt and may be rewritten only by a system/message over exactly that node");
+		}
 		/** Validate one event at its replay boundary and prepare its atomic fold transition. */
 		function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
 			if (event.seq !== expectedSeq) throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
-			const surfaceOp = surfaceOpOf(event);
+			const surfaceOp = validateSurfaceMetadata(event);
 			if (surfaceOp === void 0) return;
-			if (surfaceOp === "append") {
-				assertProvenance(event, []);
-				return {
-					kind: "append",
-					seq: event.seq
-				};
-			}
+			if (surfaceOp === "append") return {
+				kind: "append",
+				seq: event.seq
+			};
 			const range = replacementRange(state, surfaceOp);
 			assertProvenance(event, range.shadowedSeqs);
 			assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
+			assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq);
 			return {
 				kind: "replace",
 				seq: event.seq,
-				start: surfaceOp.start,
-				end: surfaceOp.end,
+				start: surfaceOp.startSeq,
+				end: surfaceOp.endSeq,
 				...range
 			};
 		}
@@ -2263,6 +2388,8 @@ window.__ModuleLoader__.load({
 			});
 			return stream;
 		}
+		/** Rendered system prompt of the fx-alpha history: surface node 0. */
+		const FIXTURE_SYSTEM_PROMPT = "你是 DeepSeek Harness 的 fixture 助手。用简洁的中文回答，并在需要时调用工具。";
 		/** fx-alpha history script: 75 turns (~150+ messages -> 4 pages at PAGE_MESSAGES=50),
 		*  mixing reasoning blocks / tool call+result / context. */
 		function buildAlphaLog() {
@@ -2300,6 +2427,15 @@ window.__ModuleLoader__.load({
 					type: "turn/start",
 					data: { turn }
 				});
+				if (turn === 0) push({
+					type: "system/message",
+					surfaceOp: "append",
+					data: {
+						turn,
+						step: 0,
+						message: createSystemMessage(FIXTURE_SYSTEM_PROMPT, "@deepseek-ai/dsh-system-prompt")
+					}
+				});
 				const userSeq = push({
 					type: "user/message",
 					surfaceOp: "append",
@@ -2572,21 +2708,21 @@ window.__ModuleLoader__.load({
 				});
 				const dispatchPair = (n, name, dispatchArgs, resultText, isError = false) => {
 					push({
-						type: "tool/code-dispatch-start",
+						type: "tool/ptc-dispatch-start",
 						data: {
 							rootCallId: callId,
 							parentCallId: callId,
-							subCallId: `${callId}:code:${n}`,
+							subCallId: `${callId}:ptc:${n}`,
 							name,
 							arguments: dispatchArgs
 						}
 					});
 					push({
-						type: "tool/code-dispatch",
+						type: "tool/ptc-dispatch",
 						data: {
 							rootCallId: callId,
 							parentCallId: callId,
-							subCallId: `${callId}:code:${n}`,
+							subCallId: `${callId}:ptc:${n}`,
 							name,
 							arguments: dispatchArgs,
 							isError,
@@ -2981,19 +3117,30 @@ window.__ModuleLoader__.load({
 				return tokens + densityPrice(JSON.stringify(block)) + BLOCK_OVERHEAD;
 			}, 0);
 		}
-		/** Fixture parallel of token-meter's heuristic context-composition projection. */
+		/**
+		* Fixture parallel of token-meter's heuristic context-composition projection.
+		* The system prompt is the system-role surface node; it prices as text plus
+		* role framing with no block overhead and stays out of the message figure.
+		*/
 		function contextBreakdownOf(log) {
 			const headerEvent = log.findLast((event) => event.type === "request/header");
 			const header = headerEvent === void 0 ? void 0 : headerEvent.data.header;
+			let systemTokens = 0;
 			let messageTokens = 0;
 			for (const seq of foldSurface(log).nodes) {
 				const event = log[seq];
 				if (event === void 0) continue;
 				const message = deriveEventMessage(event);
-				if (message !== null) messageTokens += estimateFixtureContent(message.content) + ROLE_OVERHEAD;
+				if (message === null) continue;
+				if (message.role === "system") {
+					const characters = message.content.reduce((total, block) => total + (block.type === "text" ? block.text.length : JSON.stringify(block).length), 0);
+					systemTokens = Math.ceil(characters / CHARS_PER_TOKEN) + ROLE_OVERHEAD;
+					continue;
+				}
+				messageTokens += estimateFixtureContent(message.content) + ROLE_OVERHEAD;
 			}
 			return {
-				systemTokens: header?.system === void 0 ? 0 : Math.ceil(header.system.length / CHARS_PER_TOKEN) + ROLE_OVERHEAD,
+				systemTokens,
 				toolsTokens: header?.tools === void 0 || header.tools.length === 0 ? 0 : Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD,
 				messageTokens
 			};
@@ -3108,7 +3255,7 @@ window.__ModuleLoader__.load({
 				value: contextPressureOf(log),
 				seq: event.seq
 			});
-			if (type === "request/header" || type === "user/message" || type === "assistant/message" || type === "tool/result") frames.push({
+			if (type === "request/header" || type === "system/message" || type === "user/message" || type === "assistant/message" || type === "tool/result") frames.push({
 				type: "projection",
 				sessionId: id,
 				key: "contextBreakdown",
@@ -3400,6 +3547,7 @@ window.__ModuleLoader__.load({
 				}
 			];
 			const logs = new Map([[sid("fx-alpha"), buildAlphaLog()]]);
+			const goalActivations = /* @__PURE__ */ new Map();
 			const modelSelections = new Map(sessions.map((session) => [session.sessionId, {
 				provider: "deepseek-official",
 				model: "deepseek-v4-flash"
@@ -3818,6 +3966,26 @@ window.__ModuleLoader__.load({
 				});
 				return backscanGoal(log);
 			};
+			/** Update process-local goal activation and publish the forwarded edge. */
+			const setGoalActivation = (id, activation) => {
+				const current = backscanGoal(logOf(id));
+				if (current === null) {
+					if (!goalActivations.delete(id)) return;
+					emitRemote("goal/activation-changed", [{ sessionId: id }]);
+					return;
+				}
+				const previous = goalActivations.get(id);
+				goalActivations.set(id, activation);
+				if (previous === activation) return;
+				emitRemote("goal/activation-changed", [{
+					sessionId: id,
+					goal: {
+						id: current.goal.id,
+						revision: current.goal.revision,
+						activation
+					}
+				}]);
+			};
 			const goalFailure = (message) => ({
 				ok: false,
 				error: {
@@ -3991,21 +4159,25 @@ window.__ModuleLoader__.load({
 						let text;
 						if (objective === "") text = current === null ? "No goal is set. Usage: /goal <objective>" : `Current goal: ${current.goal.objective}`;
 						else if (current !== null && current.goal.phase !== "complete") text = `A goal already exists (${current.goal.objective}). Clear it first.`;
-						else text = `Goal created: ${appendGoalChange(id, {
-							kind: "goal/change",
-							version: 1,
-							operation: "create",
-							goal: {
-								id: `fx-goal-${logOf(id).length}`,
-								revision: 1,
-								objective,
-								phase: "active",
-								maxGoalRounds: 256
-							},
-							roundsStarted: 0,
-							createdAt: Date.now(),
-							updatedAt: Date.now()
-						}).goal.objective}`;
+						else {
+							const created = appendGoalChange(id, {
+								kind: "goal/change",
+								version: 1,
+								operation: "create",
+								goal: {
+									id: `fx-goal-${logOf(id).length}`,
+									revision: 1,
+									objective,
+									phase: "active",
+									maxGoalRounds: 256
+								},
+								roundsStarted: 0,
+								createdAt: Date.now(),
+								updatedAt: Date.now()
+							});
+							setGoalActivation(id, "armed");
+							text = `Goal created: ${created.goal.objective}`;
+						}
 						const result = {
 							kind: "success",
 							text
@@ -4073,12 +4245,12 @@ window.__ModuleLoader__.load({
 					};
 				}
 			};
-			const goalView = (projection) => ({
+			const goalView = (id, projection) => ({
 				...projection.goal,
 				roundsStarted: projection.roundsStarted,
 				createdAt: projection.createdAt,
 				updatedAt: projection.updatedAt,
-				activation: projection.goal.phase === "active" ? "armed" : "disarmed"
+				activation: goalActivations.get(id) ?? (projection.goal.phase === "active" ? "armed" : "disarmed")
 			});
 			/** Canonical fixture implementation of the generated Goal Remote contract. */
 			/** Canonical fixture implementation of the generated reference-discovery Remote contracts. */
@@ -4126,6 +4298,212 @@ window.__ModuleLoader__.load({
 				}
 			};
 			/**
+			* Workspace text reads under `?fixture`.
+			*
+			* The sample content is deliberately more than one shape: the panel's states
+			* (text, oversized, unreadable) are only demonstrable if the fixture can
+			* produce each of them, and a preview that can only ever succeed hides its
+			* own failure rendering.
+			*/
+			const WORKSPACE_FILES_ROOT = "/tmp/fixture";
+			const workspaceFileTree = new Map([
+				["", [
+					{
+						name: ".gitignore",
+						type: "file",
+						size: 24
+					},
+					{
+						name: "dev.sock",
+						type: "other"
+					},
+					{
+						name: "notes",
+						type: "directory"
+					},
+					{
+						name: "package.json",
+						type: "file",
+						size: 512
+					},
+					{
+						name: "README.md",
+						type: "file",
+						size: 640
+					},
+					{
+						name: "src",
+						type: "directory"
+					}
+				]],
+				["notes", [{
+					name: "demo.txt",
+					type: "file",
+					size: 14
+				}, {
+					name: "new-demo.txt",
+					type: "file",
+					size: 14
+				}]],
+				["src", [
+					{
+						name: "config.ts",
+						type: "file",
+						size: 211
+					},
+					{
+						name: "index.ts",
+						type: "file",
+						size: 88
+					},
+					{
+						name: "lib",
+						type: "directory"
+					}
+				]],
+				["src/lib", Array.from({ length: 24 }, (_, index) => ({
+					name: `module-${String(index + 1).padStart(2, "0")}.ts`,
+					type: "file",
+					size: 96 + index
+				}))]
+			]);
+			/** Resolve a `list` argument to its workspace-relative path, or undefined when it leaves the root. */
+			const workspaceFilePath = (path) => {
+				const segments = [];
+				for (const segment of (path.startsWith("/") ? path : `${WORKSPACE_FILES_ROOT}/${path}`).split("/")) {
+					if (segment === "" || segment === ".") continue;
+					if (segment === "..") {
+						segments.pop();
+						continue;
+					}
+					segments.push(segment);
+				}
+				const absolute = `/${segments.join("/")}`;
+				if (absolute !== WORKSPACE_FILES_ROOT && !absolute.startsWith(`${WORKSPACE_FILES_ROOT}/`)) return void 0;
+				return absolute.slice(13);
+			};
+			const WORKSPACE_FILE_PAGE_LINES = 5e3;
+			/**
+			* Sample text for any readable path: a heading plus two lines of copy. The
+			* replayed conversation's `demo` files, and any `huge` path, run past two
+			* default pages so paging can be exercised without a real workspace.
+			*/
+			const workspaceFileLines = (path) => {
+				const head = [
+					`# ${path.slice(path.lastIndexOf("/") + 1)}`,
+					"",
+					"fixture 模式下的示例文本，用于验收侧栏的文本预览。",
+					"真实构建从工作区读取同名文件。"
+				];
+				return path.includes("demo") || path.includes("huge") ? [...head, ...Array.from({ length: 12e3 }, (_, index) => `第 ${index + 5} 行：用于验收分页与滚动的长文本样本。`)] : head;
+			};
+			const workspaceFileRemotes = {
+				list(path) {
+					if (path.length === 0) return {
+						ok: false,
+						error: {
+							code: "gateway/bad-request",
+							message: "path is required",
+							details: {}
+						}
+					};
+					const relative = workspaceFilePath(path);
+					if (relative === void 0) return {
+						ok: false,
+						error: {
+							code: "workspace-file/outside-workspace",
+							message: `${path} is outside the workspace`,
+							details: { path }
+						}
+					};
+					const entries = workspaceFileTree.get(relative);
+					if (entries === void 0) {
+						const cut = relative.lastIndexOf("/");
+						const name = relative.slice(cut + 1);
+						const sibling = workspaceFileTree.get(cut === -1 ? "" : relative.slice(0, cut))?.find((entry) => entry.name === name);
+						if (sibling === void 0) return {
+							ok: false,
+							error: {
+								code: "workspace-file/not-found",
+								message: `no entry at ${path}`,
+								details: { path }
+							}
+						};
+						return {
+							ok: false,
+							error: {
+								code: "workspace-file/not-directory",
+								message: `${path} is a ${sibling.type}`,
+								details: {
+									path,
+									kind: sibling.type === "file" ? "file" : "other"
+								}
+							}
+						};
+					}
+					return {
+						ok: true,
+						value: {
+							path: relative,
+							entries,
+							truncated: relative === "src/lib"
+						}
+					};
+				},
+				read(path, range) {
+					const located = workspaceFileRemotes.stat(path);
+					if (!located.ok) return located;
+					const offset = range.offset ?? 1;
+					const limit = range.limit ?? WORKSPACE_FILE_PAGE_LINES;
+					if (!Number.isInteger(offset) || offset < 1 || !Number.isInteger(limit) || limit < 1 || limit > WORKSPACE_FILE_PAGE_LINES) return {
+						ok: false,
+						error: {
+							code: "gateway/bad-request",
+							message: "offset and limit must be positive integers within the page cap",
+							details: {}
+						}
+					};
+					const lines = workspaceFileLines(path);
+					const page = lines.slice(offset - 1, offset - 1 + limit);
+					return {
+						ok: true,
+						value: {
+							...located.value,
+							offset,
+							text: page.join("\n"),
+							lines: page.length,
+							eof: offset - 1 + limit >= lines.length
+						}
+					};
+				},
+				stat(path) {
+					if (path.length === 0) return {
+						ok: false,
+						error: {
+							code: "gateway/bad-request",
+							message: "path is required",
+							details: {}
+						}
+					};
+					if (path.endsWith(".png") || path.endsWith(".bin")) return {
+						ok: false,
+						error: {
+							code: "workspace-file/not-text",
+							message: `${path} is not UTF-8 text`,
+							details: { path }
+						}
+					};
+					return {
+						ok: true,
+						value: {
+							absolutePath: path.startsWith("/") ? path : `/${path}`,
+							version: "fx-v1",
+							bytes: new TextEncoder().encode(workspaceFileLines(path).join("\n")).byteLength
+						}
+					};
+				}
+			};
+			/**
 			* Canonical fixture implementation of the generated Directory Picker Remote
 			* contract. The pick is deterministic — the keyless lanes drive the full
 			* pick-then-adopt path without an OS chooser — over the same design-mock
@@ -4192,6 +4570,15 @@ window.__ModuleLoader__.load({
 				}
 			};
 			const goalRemotes = {
+				get(id) {
+					const missing = requireGoalSession(id);
+					if (missing !== void 0) return missing;
+					const current = backscanGoal(logOf(id));
+					return {
+						ok: true,
+						value: current === null ? void 0 : goalView(id, current)
+					};
+				},
 				create(id, request) {
 					const missing = requireGoalSession(id);
 					if (missing !== void 0) return missing;
@@ -4213,6 +4600,7 @@ window.__ModuleLoader__.load({
 						createdAt: now,
 						updatedAt: now
 					});
+					setGoalActivation(id, "armed");
 					return {
 						ok: true,
 						value: { ref: {
@@ -4265,6 +4653,7 @@ window.__ModuleLoader__.load({
 						cleared: tombstone,
 						clearedAt: Date.now()
 					});
+					setGoalActivation(id, "disarmed");
 					return {
 						ok: true,
 						value: tombstone
@@ -4289,17 +4678,21 @@ window.__ModuleLoader__.load({
 				const current = resolved.value;
 				const goal = next(current);
 				if (goal === void 0) return goalFailure(`invalid goal transition from "${current.goal.phase}"`);
+				const currentActivation = goalActivations.get(id) ?? (current.goal.phase === "active" ? "armed" : "disarmed");
+				const activation = goal.phase === "active" ? current.goal.phase === "active" ? currentActivation : "armed" : "disarmed";
+				const projection = appendGoalChange(id, {
+					kind: "goal/change",
+					version: 1,
+					operation: goal.phase === current.goal.phase ? "edit" : goal.phase === "paused" ? "pause" : goal.phase === "active" ? "resume" : "complete",
+					goal,
+					roundsStarted: current.roundsStarted,
+					createdAt: current.createdAt,
+					updatedAt: Date.now()
+				});
+				setGoalActivation(id, activation);
 				return {
 					ok: true,
-					value: goalView(appendGoalChange(id, {
-						kind: "goal/change",
-						version: 1,
-						operation: goal.phase === current.goal.phase ? "edit" : goal.phase === "paused" ? "pause" : goal.phase === "active" ? "resume" : "complete",
-						goal,
-						roundsStarted: current.roundsStarted,
-						createdAt: current.createdAt,
-						updatedAt: Date.now()
-					}))
+					value: goalView(id, projection)
 				};
 			}
 			/** Canonical fixture implementation of the generated AgentPresets Remote contract. */
@@ -4441,6 +4834,16 @@ window.__ModuleLoader__.load({
 						}
 					});
 				},
+				/** Disarm the single active goal without a durable phase change. */
+				disarmOnlyGoal() {
+					const active = [...logs.entries()].filter(([, log]) => {
+						return backscanGoal(log)?.goal.phase === "active";
+					});
+					if (active.length !== 1) throw new Error(`fixture: expected one active goal, found ${String(active.length)}`);
+					const [session] = active;
+					if (session === void 0) return;
+					setGoalActivation(session[0], "disarmed");
+				},
 				/** Start an externally paced reasoning stream for the opt-in browser stress lane. */
 				startReasoningChunkStorm(id, chunkCount, chunksPerInterval, intervalMs) {
 					if (!Number.isSafeInteger(chunkCount) || chunkCount < 1) throw new Error("fixture: reasoning chunk count must be a positive safe integer");
@@ -5241,6 +5644,30 @@ window.__ModuleLoader__.load({
 					workspaceConns.delete(conn);
 				}
 			}
+			async function* openWorkspaceFileChanges(signal) {
+				signal.throwIfAborted();
+				const conn = new FxInbox();
+				const breakNow = () => {
+					conn.breakNow();
+				};
+				streamBreakers.add(breakNow);
+				const announce = options.fileChanges ? setTimeout(() => {
+					conn.push({
+						kind: "change",
+						change: {
+							absolutePath: `${WORKSPACE_FILES_ROOT}/notes/demo.txt`,
+							version: "fx-demo-v2"
+						}
+					});
+				}, 1e3) : void 0;
+				try {
+					yield { kind: "ready" };
+					yield* conn.drain(signal);
+				} finally {
+					if (announce !== void 0) clearTimeout(announce);
+					streamBreakers.delete(breakNow);
+				}
+			}
 			async function* openRemoteEvents(signal) {
 				signal.throwIfAborted();
 				const clientId = randomUuid();
@@ -5291,7 +5718,7 @@ window.__ModuleLoader__.load({
 					yield {
 						type: "snapshot",
 						header: {
-							version: 2,
+							version: 3,
 							id: sessionId,
 							createdAt: summary.updatedAt,
 							...summary.cwd === void 0 ? {} : { cwd: summary.cwd },
@@ -5525,6 +5952,7 @@ window.__ModuleLoader__.load({
 						case "directoryPicker/pick": return Promise.resolve(directoryPickerRemotes.pick());
 						case "directoryPicker/list": return Promise.resolve(directoryPickerRemotes.list(args.path));
 						case "directoryPicker/createDirectory": return Promise.resolve(directoryPickerRemotes.createDirectory(args.path ?? "", args.name ?? ""));
+						case "goals/get": return Promise.resolve(goalRemotes.get(sessionId));
 						case "goals/create": return Promise.resolve(goalRemotes.create(sessionId, {
 							objective: request?.objective,
 							...request?.maxGoalRounds === void 0 ? {} : { maxGoalRounds: request.maxGoalRounds }
@@ -5579,6 +6007,9 @@ window.__ModuleLoader__.load({
 							}] });
 						}
 						case "session/openWorkspacePath": return sessionOk({ opened: true });
+						case "workspaceFiles/read": return Promise.resolve(workspaceFileRemotes.read(args.path ?? "", args.range ?? {}));
+						case "workspaceFiles/stat": return Promise.resolve(workspaceFileRemotes.stat(args.path ?? ""));
+						case "workspaceFiles/list": return Promise.resolve(workspaceFileRemotes.list(args.path ?? ""));
 						case "session/canOpenWorkspacePath": return Promise.resolve({
 							ok: true,
 							value: true
@@ -5696,6 +6127,7 @@ window.__ModuleLoader__.load({
 						case "session/control": return openControl(signal);
 						case "session/follow": return openFollow(args.request, signal);
 						case "workspace/follow": return openWorkspace(signal);
+						case "workspaceFiles/changes": return openWorkspaceFileChanges(signal);
 						default: throw new Error(`fixture connection stream endpoint ${JSON.stringify(endpoint)} is unavailable`);
 					}
 				}
@@ -5717,7 +6149,8 @@ window.__ModuleLoader__.load({
 				rejectPrompt: query.get("fixturePrompt") === "reject",
 				failWorkspaceAttach: query.get("fixtureAttach") === "fail",
 				dropSessionCreateResponse: query.get("fixtureSessionCreate") === "drop-response",
-				createFrameOrder: query.get("fixtureFrames") === "workspace-first" ? "workspace-first" : "session-first"
+				createFrameOrder: query.get("fixtureFrames") === "workspace-first" ? "workspace-first" : "session-first",
+				fileChanges: query.get("fixtureFileChanges") === "demo"
 			};
 		}
 		//#endregion

package/lib/index.js

@@ -733,7 +733,7 @@ function assertImageBodyCapacity(ctx, maxRequestBodyBytes) {
 	if (maxRequestBodyBytes < requiredImageBodyBytes) throw new Error(`client-connection maxRequestBodyBytes (${String(maxRequestBodyBytes)}) must be at least ${String(requiredImageBodyBytes)} for the configured aggregate image limit`);
 }
 /** Services required before providing Connection. */
-const inject = ["webServer", "credentials"];
+const inject = ["credentials"];
 const Config = z.object({
 	recovery: ConnectionRecoveryConfigSchema.default({}),
 	trustedHosts: z.array(String).default([]),
@@ -741,9 +741,9 @@ const Config = z.object({
 	maxRequestBodyBytes: z.natural().min(1).default(DEFAULT_MAX_REQUEST_BODY_BYTES)
 });
 /**
-* Mounts the API gateway under the browser transport prefix. Every request on
-* the prefix passes the Host/Origin browser-trust fence and persistent browser
-* authentication before dispatch.
+* Provides carrier-neutral RPC and Fetch registries. When `webServer` is
+* present, the plugin also mounts the `/api` browser transport with Host/Origin
+* checks and persistent browser authentication.
 * @param ctx - Host plugin context.
 * @param config - resolved plugin config (schema defaults applied).
 */
@@ -755,28 +755,31 @@ async function apply(ctx, config) {
 	for (const entry of trustedHosts) assertTrustedAuthority(entry);
 	assertImageBodyCapacity(ctx, maxRequestBodyBytes);
 	const connection = new HostConnectionService(ctx, trustedHosts, await BrowserAuth.create(ctx.root, ctx.credentials, cookieMaxAgeDays));
-	ctx.on("webserver/index-inject", (table) => {
-		table.push({
-			kind: "global",
-			name: "__DSH_CONNECTION_RECOVERY__",
-			value: recovery
+	ctx.inject(["webServer"], (webCtx) => {
+		assertImageBodyCapacity(webCtx, maxRequestBodyBytes);
+		webCtx.on("webserver/index-inject", (table) => {
+			table.push({
+				kind: "global",
+				name: "__DSH_CONNECTION_RECOVERY__",
+				value: recovery
+			});
 		});
-	});
-	const fetchHandler = connection.createSharedFetchHandler(API_PATH);
-	const route = {
-		kind: "prefix",
-		path: API_PATH,
-		handler: async (req, res) => {
-			const rejection = connection.requestRejection(req);
-			if (rejection !== void 0) {
-				res.writeHead(rejection);
-				res.end(rejection === 401 ? "unauthorized" : "forbidden");
-				return;
+		const fetchHandler = connection.createSharedFetchHandler(API_PATH);
+		const route = {
+			kind: "prefix",
+			path: API_PATH,
+			handler: async (req, res) => {
+				const rejection = connection.requestRejection(req);
+				if (rejection !== void 0) {
+					res.writeHead(rejection);
+					res.end(rejection === 401 ? "unauthorized" : "forbidden");
+					return;
+				}
+				await bridge(req, res, fetchHandler, maxRequestBodyBytes);
 			}
-			await bridge(req, res, fetchHandler, maxRequestBodyBytes);
-		}
-	};
-	ctx.effect(() => ctx.webServer.register(route), "client-connection: /api route");
+		};
+		webCtx.effect(() => webCtx.webServer.register(route), "client-connection: /api route");
+	});
 	ctx.inject(["attachments"], (attachmentCtx) => {
 		assertImageBodyCapacity(attachmentCtx, maxRequestBodyBytes);
 	});

package/lib/types/client/fixture.d.ts

@@ -42,6 +42,8 @@ export interface FixtureOptions {
     dropSessionCreateResponse?: boolean;
     /** Order of the two successful create frames. */
     createFrameOrder?: 'session-first' | 'workspace-first';
+    /** Announce one Agent write to `notes/demo.txt` shortly after a `workspaceFiles/changes` stream opens. */
+    fileChanges?: boolean;
 }
 /** Fixture RPC face over one in-memory state graph. */
 export interface FixtureWorld {

package/lib/types/index.d.ts

@@ -31,9 +31,9 @@ export interface ConnectionConfig {
 }
 export declare const Config: z<ConnectionConfig>;
 /**
- * Mounts the API gateway under the browser transport prefix. Every request on
- * the prefix passes the Host/Origin browser-trust fence and persistent browser
- * authentication before dispatch.
+ * Provides carrier-neutral RPC and Fetch registries. When `webServer` is
+ * present, the plugin also mounts the `/api` browser transport with Host/Origin
+ * checks and persistent browser authentication.
  * @param ctx - Host plugin context.
  * @param config - resolved plugin config (schema defaults applied).
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-connection",
   "description": "Authenticated RPC transport, generation lifecycle, and browser fixture",
-  "version": "0.1.3-alpha.2",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -35,7 +35,7 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-credentials": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.5-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "files": [
@@ -48,16 +48,16 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-api-session-controller": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-attachment": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-brand": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-commands": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-host-directory-picker": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tool-todo": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2"
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-brand": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-host-directory-picker": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-commands": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-settings": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tool-todo": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.5-alpha.2"
   }
 }