@deepseek-ai/dsh-api-workspace-controller 0.1.2-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/api/workspace-controller/README.md
+README.md: d1ce90d09662f1e39d2da5f7fe1b8276f6ad6150
+README.zh.md: e0b7109275464ddb4c9430e15d52dcb9632314a2

package/README.md

@@ -0,0 +1,56 @@
+---
+description: "Host and Client workspace control: mutate workspace navigation and follow its complete projection."
+kind: "package-reference"
+---
+# Workspace Controller
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`@deepseek-ai/dsh-api-workspace-controller` owns the Host `ctx.workspaceController` service and the generated Client `ctx.remote.workspace` namespace. Its Remote methods create, rename, remove, and reorder Workspaces, reorder Sessions within a Workspace, archive Sessions from Workspace navigation, and follow the complete Workspace projection. Use it through API Gateway when a Client must change or follow Workspace navigation. The package also owns `ctx.directoryPickerController` and the generated `ctx.remote.directoryPicker` namespace, because the directory-picking seam it carries is abstract and never a Loader entry of its own.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The Host controller serializes mutations whose correctness depends on current registry state and throws `RemoteError` with a stable `workspace/*` or `directory-picker/*` code for expected failures. Its `follow()` stream synchronously attaches to durable Workspace changes, emits one complete baseline first, then emits ordered `upsert`, `remove`, `order`, and `archived` increments. A reconnect starts another generation with a replacement baseline, so consumers do not depend on receiving every increment while disconnected.
+
+The Client entry provides `ClientWorkspaceModel` and `createWorkspaceStateStream()`. The model owns Workspace rows, registry order, archived Session ids, unary mutation echoes, and stream/unary race resolution. A newer Host row wins by `updatedAt`; a committed stream order outranks an older unary response; a removed Workspace id cannot be resurrected by delayed data. The package exposes framework-neutral snapshots and subscriptions, leaving navigation policy and React hooks to the UI owner.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as Workspace organization is browser and Host control state and registers no prompt, tool, or session event.
+
+#### KV Cache effect
+
+No direct effect; Workspace mutations do not alter model requests.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- `follow()` replaces the whole projection after reconnect and has no durable cursor or incremental catch-up protocol.
+- Process-local deletion markers prevent delayed data from reviving a removed Workspace only for the lifetime of the Client model.
+
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,56 @@
+---
+description: "Host 与 Client 工作区控制：修改工作区导航并跟随其完整投影。"
+kind: "package-reference"
+---
+# Workspace Controller
+
+[English](README.md) | 中文
+
+## 概述
+
+`@deepseek-ai/dsh-api-workspace-controller` 拥有 Host 的 `ctx.workspaceController` 服务和生成的 Client `ctx.remote.workspace` namespace。它的 Remote 方法负责创建、重命名、移除和重排 Workspace，在 Workspace 内重排 Session，从 Workspace 导航中归档 Session，以及跟随完整的 Workspace 投影。当 Client 必须修改或跟随 Workspace 导航时，请通过 API Gateway 使用它。本包同时拥有 `ctx.directoryPickerController` 与生成的 `ctx.remote.directoryPicker` namespace，因为它承载的选目录 seam 是抽象的，自身从不作为 Loader entry。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+Host 控制器会串行执行正确性取决于当前 registry 状态的变更，并为预期失败抛出带稳定 `workspace/*` 或 `directory-picker/*` 码的 `RemoteError`。它的 `follow()` 流会同步订阅持久 Workspace 变更，先发出一份完整 baseline，再按顺序发出 `upsert`、`remove`、`order` 和 `archived` 增量。重连会以替换 baseline 开始新一代，因此消费方不依赖收到断线期间的每个增量。
+
+Client 入口提供 `ClientWorkspaceModel` 和 `createWorkspaceStateStream()`。该模型拥有 Workspace 行、registry 顺序、已归档 Session id、一元变更回声，以及流与一元调用的竞态处理。较新的 Host 行按 `updatedAt` 获胜；已提交的流顺序优先于较旧的一元响应；已经移除的 Workspace id 不会被延迟数据复活。该包公开与框架无关的快照和订阅，把导航策略与 React hook 留给 UI owner。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为 Workspace 组织属于浏览器与 Host 控制状态，并且不注册提示词、工具或会话事件。
+
+#### KV Cache 影响
+
+无直接影响；Workspace 变更不会改变模型请求。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- `follow()` 在重连后替换完整投影，不提供持久 cursor 或增量追赶协议。
+- 进程本地删除标记只会在 Client 模型生命周期内阻止延迟数据复活已移除的 Workspace。
+
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/client.js

@@ -0,0 +1,415 @@
+window.__ModuleLoader__.load({
+	id: "@deepseek-ai/dsh-api-workspace-controller",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let _deepseek_ai_dsh_api_gateway_client = require("@deepseek-ai/dsh-api-gateway/client");
+		let _deepseek_ai_dsh_client_store = require("@deepseek-ai/dsh-client-store");
+		let _deepseek_ai_cordis = require("@deepseek-ai/cordis");
+		//#region lib/types/client/model.js
+		/** Client-side Workspace state model shared by Remote transport and UI projection. */
+		/**
+		* Owns the Client Workspace projection, mutation echoes, and stream/unary race resolution.
+		*/
+		var ClientWorkspaceModel = class {
+			remote;
+			items = [];
+			archivedSessionIds = [];
+			state = "loading";
+			phase = "pending";
+			error = null;
+			/** Latest local reorder request; only its unary echo may install order. */
+			orderRequestGeneration = 0;
+			/** Increments on stream orders so a later remote commit outranks an older unary echo. */
+			orderFrameGeneration = 0;
+			/** Last complete order accepted from a baseline, increment, or current unary echo. */
+			committedOrder = [];
+			/** Host Workspace ids are never reused, so delayed data cannot resurrect a removed row. */
+			removedIds = /* @__PURE__ */ new Set();
+			listeners = /* @__PURE__ */ new Set();
+			snapshotCache;
+			snapshotDirty = false;
+			notificationPending = false;
+			notificationScheduled = false;
+			notificationGeneration = 0;
+			/** @param remote - generated Workspace Remote namespace. */
+			constructor(remote) {
+				this.remote = remote;
+				this.snapshotCache = this.buildSnapshot();
+			}
+			/**
+			* Create or resolve a Workspace and merge the unary result immediately.
+			* @param input - existing absolute path to adopt.
+			* @returns generated Remote result.
+			*/
+			async create(input) {
+				const result = await this.remote.create(input);
+				if (result.ok) this.upsert(result.value.workspace);
+				return result;
+			}
+			/**
+			* Rename a Workspace and merge the unary result immediately.
+			* @param workspaceId - target Workspace.
+			* @param title - new display title.
+			* @returns generated Remote result.
+			*/
+			async rename(workspaceId, title) {
+				const result = await this.remote.rename({
+					workspaceId,
+					title
+				});
+				if (result.ok) this.upsert(result.value.workspace);
+				return result;
+			}
+			/**
+			* Delete a Workspace and remove it from the local projection immediately.
+			* @param workspaceId - target Workspace.
+			* @returns generated Remote result.
+			*/
+			async delete(workspaceId) {
+				const result = await this.remote.delete({ workspaceId });
+				if (result.ok) this.remove(workspaceId, true);
+				return result;
+			}
+			/**
+			* Optimistically move a Workspace and reconcile the returned complete order.
+			* @param workspaceId - Workspace to move.
+			* @param beforeWorkspaceId - anchor Workspace; omitted appends.
+			* @returns generated Remote result.
+			*/
+			async insertBefore(workspaceId, beforeWorkspaceId) {
+				const requestGeneration = ++this.orderRequestGeneration;
+				const frameGeneration = this.orderFrameGeneration;
+				const localOrder = this.items.map((workspace) => workspace.workspaceId);
+				this.installOrder(insertIdBefore(localOrder, workspaceId, beforeWorkspaceId));
+				const result = await this.remote.insertBefore({
+					workspaceId,
+					...beforeWorkspaceId === void 0 ? {} : { beforeWorkspaceId }
+				});
+				if (requestGeneration === this.orderRequestGeneration && frameGeneration === this.orderFrameGeneration) this.installOrder(result.ok ? result.value.workspaceIds : this.committedOrder, result.ok);
+				return result;
+			}
+			/**
+			* Move a Session within its Workspace and merge the returned row.
+			* @param workspaceId - owning Workspace.
+			* @param sessionId - accounted Session to move.
+			* @param beforeSessionId - accounted anchor; omitted appends.
+			* @returns generated Remote result.
+			*/
+			async insertSessionBefore(workspaceId, sessionId, beforeSessionId) {
+				const result = await this.remote.insertSessionBefore({
+					workspaceId,
+					sessionId,
+					...beforeSessionId === void 0 ? {} : { beforeSessionId }
+				});
+				if (result.ok) this.upsert(result.value.workspace);
+				return result;
+			}
+			/**
+			* Archive one Session and install the returned complete archive set.
+			* @param sessionId - Session to archive.
+			* @returns generated Remote result.
+			*/
+			async archiveSession(sessionId) {
+				const result = await this.remote.archiveSession({ sessionId });
+				if (result.ok) this.installArchived(result.value.archivedSessionIds);
+				return result;
+			}
+			/**
+			* Replace the projection from one complete stream-generation baseline.
+			* @param baseline - complete Workspace and archive projection.
+			*/
+			replaceBaseline(baseline) {
+				this.orderFrameGeneration++;
+				this.installViews(baseline.items);
+				this.installArchived(baseline.archivedSessionIds);
+				this.state = "idle";
+				this.phase = "ready";
+				this.error = null;
+				this.invalidate();
+			}
+			/** Merge one decoded Workspace upsert from the current follow generation. */
+			upsertView(workspace) {
+				this.upsert(workspace);
+			}
+			/** Apply one decoded Workspace removal from the current follow generation. */
+			removeView(workspaceId) {
+				this.remove(workspaceId);
+			}
+			/** Replace Host-confirmed order from the current follow generation. */
+			replaceOrder(workspaceIds) {
+				this.orderFrameGeneration++;
+				this.installOrder(workspaceIds, true);
+			}
+			/**
+			* Replace the archived Session set from the current follow generation.
+			* @param archivedSessionIds - complete Host-confirmed archive set.
+			*/
+			replaceArchived(archivedSessionIds) {
+				this.installArchived(archivedSessionIds);
+			}
+			/** Keep the last complete projection visible while a lost carrier reconnects. */
+			handleCarrierFailure() {
+				this.state = "loading";
+				this.error = null;
+				this.invalidate();
+			}
+			/**
+			* Publish a non-retryable stream or protocol failure.
+			* @param error - terminal stream failure.
+			*/
+			handleStreamFailure(error) {
+				if (!(0, _deepseek_ai_dsh_api_gateway_client.isRemoteFailure)(error)) throw error;
+				this.state = "error";
+				this.error = error;
+				this.invalidate();
+			}
+			/**
+			* Subscribe to Workspace state invalidation.
+			* @param listener - invalidation callback.
+			* @returns unsubscribe function.
+			*/
+			subscribe(listener) {
+				this.listeners.add(listener);
+				return () => {
+					this.listeners.delete(listener);
+				};
+			}
+			/**
+			* Read the cached state, rebuilding it first when necessary.
+			* @returns the current stable Workspace list snapshot.
+			*/
+			getSnapshot() {
+				this.refreshSnapshot();
+				return this.snapshotCache;
+			}
+			buildSnapshot() {
+				return {
+					items: this.items,
+					archivedSessionIds: this.archivedSessionIds,
+					state: this.state,
+					phase: this.phase,
+					error: this.error
+				};
+			}
+			installArchived(archivedSessionIds) {
+				if (archivedSessionIds.length === this.archivedSessionIds.length && archivedSessionIds.every((id, index) => id === this.archivedSessionIds[index])) return;
+				this.archivedSessionIds = [...archivedSessionIds];
+				this.invalidate();
+			}
+			installOrder(workspaceIds, committed = false) {
+				if (committed) this.committedOrder = [...workspaceIds];
+				const rank = new Map(workspaceIds.map((id, index) => [id, index]));
+				const items = [...this.items].sort((left, right) => (rank.get(left.workspaceId) ?? Number.MAX_SAFE_INTEGER) - (rank.get(right.workspaceId) ?? Number.MAX_SAFE_INTEGER));
+				if (items.every((item, index) => item === this.items[index])) return;
+				this.items = items;
+				this.invalidate();
+			}
+			upsert(view) {
+				if (this.removedIds.has(view.workspaceId)) return;
+				const index = this.items.findIndex((item) => item.workspaceId === view.workspaceId);
+				const installed = this.items[index];
+				if (installed !== void 0 && Date.parse(view.updatedAt) < Date.parse(installed.updatedAt)) return;
+				if (!this.committedOrder.includes(view.workspaceId)) this.committedOrder = [view.workspaceId, ...this.committedOrder];
+				this.items = index === -1 ? [view, ...this.items] : this.items.map((item, position) => position === index ? view : item);
+				this.invalidate();
+			}
+			remove(workspaceId, immediate = false) {
+				this.removedIds.add(workspaceId);
+				this.committedOrder = this.committedOrder.filter((id) => id !== workspaceId);
+				const items = this.items.filter((item) => item.workspaceId !== workspaceId);
+				if (items.length === this.items.length) {
+					if (immediate) this.invalidate(true);
+					return;
+				}
+				this.items = items;
+				this.invalidate(immediate);
+			}
+			installViews(views) {
+				const installed = /* @__PURE__ */ new Map();
+				for (const view of views) if (!this.removedIds.has(view.workspaceId)) installed.set(view.workspaceId, view);
+				this.items = [...installed.values()];
+				this.committedOrder = views.map((view) => view.workspaceId);
+			}
+			invalidate(immediate = false) {
+				this.snapshotDirty = true;
+				this.notificationPending = true;
+				if (immediate) {
+					this.notificationGeneration++;
+					this.notificationScheduled = false;
+					this.flush();
+					return;
+				}
+				if (this.notificationScheduled) return;
+				this.notificationScheduled = true;
+				const generation = ++this.notificationGeneration;
+				queueMicrotask(() => {
+					if (generation !== this.notificationGeneration) return;
+					this.notificationScheduled = false;
+					this.flush();
+				});
+			}
+			flush() {
+				if (!this.notificationPending || this.listeners.size === 0) return;
+				this.notificationPending = false;
+				this.refreshSnapshot();
+				(0, _deepseek_ai_dsh_client_store.notifySubscribers)(this.listeners, "[workspace-controller]");
+			}
+			refreshSnapshot() {
+				if (!this.snapshotDirty) return;
+				this.snapshotDirty = false;
+				this.snapshotCache = this.buildSnapshot();
+			}
+		};
+		function insertIdBefore(ids, id, beforeId) {
+			if (!ids.includes(id) || beforeId !== void 0 && !ids.includes(beforeId) || beforeId === id) return [...ids];
+			const without = ids.filter((candidate) => candidate !== id);
+			const at = beforeId === void 0 ? without.length : without.indexOf(beforeId);
+			return [
+				...without.slice(0, at),
+				id,
+				...without.slice(at)
+			];
+		}
+		//#endregion
+		//#region lib/types/client/service.js
+		/** React-free Client Workspace service and command facade. */
+		/** Structured create failure for callers that distinguish Host business errors. */
+		var WorkspaceCreateError = class extends Error {
+			rpcError;
+			name = "WorkspaceCreateError";
+			/** @param rpcError - Host business or folded carrier failure. */
+			constructor(rpcError) {
+				super(`workspace create failed: ${rpcError.code}: ${rpcError.message}`);
+				this.rpcError = rpcError;
+			}
+		};
+		/** Owns the bare Workspace snapshot and Workspace-only commands. */
+		var WorkspaceController = class extends _deepseek_ai_cordis.Service {
+			model;
+			list;
+			/**
+			* @param ctx - Client root Context.
+			* @param model - Remote-backed Workspace state model.
+			*/
+			constructor(ctx, model) {
+				super(ctx, "workspaces");
+				this.model = model;
+				this.list = model;
+			}
+			async create(input) {
+				const result = await this.model.create(input);
+				if (!result.ok) throw new WorkspaceCreateError(result.error);
+				return result.value.workspace;
+			}
+			async rename(workspaceId, title) {
+				const result = await this.model.rename(workspaceId, title);
+				if (!result.ok) throw commandError("rename", result.error);
+				return result.value.workspace;
+			}
+			async delete(workspaceId) {
+				const result = await this.model.delete(workspaceId);
+				if (!result.ok) throw commandError("delete", result.error);
+			}
+			async insertBefore(workspaceId, beforeWorkspaceId) {
+				const result = await this.model.insertBefore(workspaceId, beforeWorkspaceId);
+				if (!result.ok) throw commandError("reorder", result.error);
+			}
+			async archiveSession(sessionId) {
+				const result = await this.model.archiveSession(sessionId);
+				if (!result.ok) throw commandError("session archive", result.error);
+			}
+			async insertSessionBefore(workspaceId, sessionId, beforeSessionId) {
+				const result = await this.model.insertSessionBefore(workspaceId, sessionId, beforeSessionId);
+				if (!result.ok) throw commandError("move", result.error);
+				return result.value.workspace;
+			}
+		};
+		function commandError(operation, failure) {
+			return /* @__PURE__ */ new Error(`workspace ${operation} failed: ${failure.code}: ${failure.message}`);
+		}
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Workspace-specific adapter for the Gateway-owned snapshot stream lifecycle. */
+		/** Required Client Remote services. */
+		const inject = ["remote", "remote.workspace"];
+		/**
+		* Install Client Workspace state, commands, and reconnecting follow control.
+		* @param ctx - Client root Context.
+		*/
+		function apply(ctx) {
+			const model = new ClientWorkspaceModel(ctx.remote.workspace);
+			new WorkspaceController(ctx, model);
+			const control = createWorkspaceStateStream(ctx.remote, {
+				accept: model,
+				carrierFailed: () => {
+					model.handleCarrierFailure();
+				},
+				failed: (error) => {
+					model.handleStreamFailure(error);
+				}
+			});
+			control.start();
+			ctx.effect(() => async () => {
+				await control.dispose();
+			}, "workspace-controller.client.control");
+		}
+		/**
+		* Create the reconnecting Workspace state stream.
+		* @param remote - Client Remote face carrying the Workspace namespace and the stream factory.
+		* @param options - Workspace state destinations.
+		* @returns an unstarted stream owned by the Client Workspace runtime.
+		*/
+		function createWorkspaceStateStream(remote, options) {
+			return new _deepseek_ai_dsh_api_gateway_client.RemoteSnapshotStream(remote.$stream({
+				name: "Workspace state stream",
+				open: (signal) => remote.workspace.follow(signal),
+				ended: (accepted) => accepted ? new _deepseek_ai_dsh_api_gateway_client.RemoteStreamCarrierError("Workspace state stream ended without a terminal result") : /* @__PURE__ */ new Error("Workspace state stream ended before its opening snapshot"),
+				...options.carrierFailed === void 0 ? {} : { carrierFailed: options.carrierFailed }
+			}), {
+				name: "Workspace state stream",
+				isSnapshot: (frame) => frame.type === "baseline",
+				replace: (frame) => {
+					options.accept.replaceBaseline(frame.value);
+				},
+				update: (frame) => {
+					acceptIncrement(options.accept, frame);
+				},
+				failed: options.failed
+			});
+		}
+		function acceptIncrement(accept, frame) {
+			switch (frame.type) {
+				case "upsert":
+					accept.upsertView(frame.workspace);
+					return;
+				case "remove":
+					accept.removeView(frame.workspaceId);
+					return;
+				case "order":
+					accept.replaceOrder(frame.workspaceIds);
+					return;
+				case "archived":
+					accept.replaceArchived(frame.archivedSessionIds);
+					return;
+				/* v8 ignore next -- the generated Remote codec validates this closed union */
+				default: return assertNever(frame);
+			}
+		}
+		/* v8 ignore next 3 -- closed-union backstop after generated Remote validation */
+		function assertNever(value) {
+			throw new Error(`unreachable Workspace increment: ${JSON.stringify(value)}`);
+		}
+		//#endregion
+		exports.ClientWorkspaceModel = ClientWorkspaceModel;
+		exports.WorkspaceController = WorkspaceController;
+		exports.WorkspaceCreateError = WorkspaceCreateError;
+		exports.apply = apply;
+		exports.createWorkspaceStateStream = createWorkspaceStateStream;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map