@gestaltrun/dsh-workspace-bundle 0.0.0-stage → 0.1.0

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,37 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write product/workspace-bundle/README.md
+/:
+  en: 79fcf0fef0b0e5ab
+  zh: 013889272c7c75ed
+/gestaltrun-dsh-workspace-bundle:
+  en: 32d9d61fe0c0c65a
+  zh: baf32db83ff0c674
+/gestaltrun-dsh-workspace-bundle/summary:
+  en: 7e2c6d1fe1029327
+  zh: 80c8ac0e443ab679
+/gestaltrun-dsh-workspace-bundle/table-of-contents:
+  en: 3f8824c773c2099e
+  zh: 3f8824c773c2099e
+/gestaltrun-dsh-workspace-bundle/service-contract:
+  en: a67c34bc435898c2
+  zh: 0bca36e1d7161945
+/gestaltrun-dsh-workspace-bundle/template-digest:
+  en: ace3ca12ffd26d60
+  zh: 6ef8270851901c24
+/gestaltrun-dsh-workspace-bundle/upgrade-and-recovery:
+  en: 3aa7ca69d180616a
+  zh: cac74e4a9f989ae2
+/gestaltrun-dsh-workspace-bundle/agent-configurations:
+  en: c357f675bd39591a
+  zh: b356590dc1644e43
+/gestaltrun-dsh-workspace-bundle/configuration:
+  en: 086761086e09adcb
+  zh: 1158f36ec547fcdd
+/gestaltrun-dsh-workspace-bundle/model-experience:
+  en: 783dcce69a33b4eb
+  zh: 961497005b98fb7d
+/gestaltrun-dsh-workspace-bundle/dev-note:
+  en: 1afd4fbe6deff485
+  zh: 7dbc9737c4de6ad8

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+---
+description: "WorkspaceBundles Service Definition and Provider: packaged templates, stable hidden Workspaces, and whole-tree upgrades."
+kind: "package-plugin"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @gestaltrun/dsh-workspace-bundle
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This package defines the Host-only `WorkspaceBundles` service (`ctx.workspaceBundles`). A product plugin registers a packaged template; `ensure` materializes a stable Workspace with bundle origin, and an upgrade replaces the tree as a whole. Ordinary Workspace views stay empty for that origin. Desktop lists it in `DESKTOP_PLATFORM_PACKAGE_SOURCES`. It publishes with `publishConfig.access` set to `public` and dist-tag `candidate`. It is not a profile bundle and has no cordis patch. The design is in the [customer-service hosting scheme](../../.agents/design/cs-hosting/scheme.zh.md).
+
+## Table of Contents
+
+- [Service contract](#service-contract)
+- [Template digest](#template-digest)
+- [Upgrade and recovery](#upgrade-and-recovery)
+- [Agent configurations](#agent-configurations)
+- [Configuration](#configuration)
+- [Model Experience](#model-experience)
+- [Dev Note](#dev-note)
+
+## Service contract
+
+`register(template)` is an effect: it returns a disposer that forbids later `ensure` and `acquire` for that identity. `ensure({ bundleId, workspaceKey })` verifies the template, writes a staging tree, and registers a Workspace whose `origin` is `{ kind: 'bundle', bundleId, workspaceKey }`. Repeated calls reuse the Workspace id and path. `acquire(workspaceId)` holds a lease that delays upgrade quiesce. `record(identity)` returns the durable product record. `pathOf(identity)` is the absolute materialize directory from `materializeRoot` and the identity segments; it does not require `ensure`.
+
+This is a capability package. It does not declare an installable bundle patch.
+
+## Template digest
+
+The packaged `manifest.json` lists every file's SHA-256 digest and an overall digest of the ordered catalog. Materialize rejects symbolic links, parent-segment paths, missing assets, extra files, and digest mismatch. The immutable copy under `templateCacheRoot` is what recovery verifies when the package source directory is gone.
+
+## Upgrade and recovery
+
+Replacement is staging → `updating` journal → quiesce leases → rename the live root to backup and staging to the stable root → verify → commit. A crash at a swap or commit point recovers a wholly old tree or a wholly new tree; the Workspace id and path do not change. Consumers are barred while the journal is `updating`.
+
+Before replacing an existing tree, the Provider awaits the serial `workspace-bundle/quiesce` event under the durable `updating` barrier. Consumers cancel their activity, await its completion and release leases in that listener. A listener failure leaves the journal for recovery and prevents the swap.
+
+## Agent configurations
+
+`registerAgentConfigSource({ identity, revision, query })` adds an authenticated assignment query for a registered template and returns an async disposer that cancels and joins its work. Startup and configured polling prepare candidates without changing the live tree. `agentConfig(identity)` exposes the applied version, candidate and a fixed failure diagnostic; `refreshAgentConfig(identity)` joins one query and download. `ensure` and `acquire` apply a candidate only when the Workspace has no leases. Consumers must acquire before starting a turn and retain that lease through its end. The existing replacement journal keeps the Workspace id and path stable. This API does not cancel a running turn to apply remote content.
+
+The archive is deterministic gzip JSON with `manifest` and `files`. The manifest has `formatVersion: 1`, `workspaceKind`, full SemVer `version`, `hostAgentConfigApiRange`, and sorted `files` containing `path`, `sizeBytes` and `sha256`. The parallel file array carries matching `path` and canonical `base64`. Gzip metadata contains no timestamp or host identity. Full versions including build metadata, such as `1.0.0+build.42`, identify different packages; build metadata does not change SemVer precedence. The Host Agent configuration API is `1.0.0`. All compressed bytes, file sizes and digests are verified before publishing the candidate tree. Links, traversal, case collisions, reserved names, duplicates and expansion beyond the configured bound are rejected.
+
+Downloaded trees live under `templateCacheRoot/agent-config-versions/{bundleId}/{workspaceKey}/{sha256}/{version}` with read-only files and directories. The committed journal records the full version and package digest, so identical templates in distinct versions remain distinguishable after restart. The source revision changes with its authenticated assignment identity. A revision change cancels and joins the previous query/download, clears uncommitted candidates and queries the new identity; publication and replacement recheck it. The query callback owns credentials; this service sends none to the file server. Downloads require HTTPS, reject redirects, and share the query deadline. An explicit loopback HTTP setting exists only for local fixtures. A failed query, download, digest or compatibility check discards the candidate and keeps the current version. A `builtin` assignment retains an already installed remote version; a fresh installation uses the packaged template. Lower assigned versions are accepted for rollback.
+
+The [manual workflow](../../.github/workflows/release-agent-config.yml) accepts `workspace_kind`, `version` and default-true `dry_run`. The product registration [agent-configs.json](../agent-configs.json) lists each kind's sources. From the repository root, build the consumer assets, then pack:
+
+```sh
+pnpm --dir product --filter @gestaltrun/dsh-cs-hosting run build:cli
+node product/scripts/agent-config.mjs --kind cs-hosting --version 1.0.0+build.42 --out product/dist/agent-config
+```
+
+The workflow uses the existing `desktop-release` environment, Alibaba OIDC role and `DESKTOP_RELEASE_*` OSS variables. It uploads an immutable object with a forbid-overwrite header, verifies metadata afterward and outputs `server-registration.json`: kind, version, SHA-256, size, compatibility range, OSS address and HTTPS download URL. Dry-run produces the same registration plan without accessing OSS. Add release notes and these fields to the server's reviewed agent-configage rules, merge that PR, then run its approved ops-job synchronization. Assignment changes select the next turn's version; assigning an old registered version rolls back. The server owns rule validation and rollout, as [R3a](https://github.com/gestaltrun/gestalt-travel-server/issues/86) specifies.
+
+`recordWorkspaceAgentConfigVersion(session, version)` writes `workspace-bundle/agent-config-version` on the first step using a different version. Its data records kind, full version, previous version, template digest, package digest (null for builtin) and Host Agent configuration API. The event contains no URL or credential. Model prompts remain logged as `system/message`; skills and CLI results remain logged tool results. This required-on-read event needs a Session core that registers its name. An older reader refuses it rather than reconstructing incomplete history.
+
+Known limitations: version caches are retained and need operator-owned disk management; POSIX read-only modes are not a Windows ACL security policy. All affected turns must use leases, so one busy Session can delay a shared Workspace update. This interface updates content only; it does not hot-load Host authorization code or promise new Host commands. The [customer-service consumer](../cs-hosting/README.md#template) uses a released server contract.
+
+## Configuration
+
+The row requires absolute `materializeRoot`, `templateCacheRoot`, and `journalRoot`. `quiesceTimeoutMs` (1000–600000, default 30000) and `recycleTimeoutMs` (0–600000, default 60000) are bounded. Content settings are `agentConfigPollIntervalMs` (1000–86400000, default 300000), `agentConfigRequestTimeoutMs` (100–600000, default 30000), `agentConfigMaxDownloadBytes` (1024–268435456, default 67108864), `agentConfigMaxExpandedBytes` (1024–536870912, default 134217728), and `allowLoopbackAgentConfigHttp` (default false). Missing or relative roots fail plugin load with `WorkspaceBundlesConfigError`.
+
+## Model Experience
+
+The service is Host-only. It does not register model tools. Bundled Workspaces keep ordinary browse, search, and New Session from inheriting them through Workspace origin, not through this package's prompt text.
+
+## Dev Note
+
+Customer-service hosting is the first consumer. The template files live in [`product/cs-hosting/template`](../cs-hosting/template) and record teamwork commit `9e6c536f2`.
+
+No runtime invariant companion is published: the package owns no relationship between independent observations.

package/README.zh.md

@@ -0,0 +1,73 @@
+---
+description: "WorkspaceBundles 服务定义与 Provider：打包模板、稳定隐藏工作区与整树升级。"
+kind: "package-plugin"
+---
+
+# @gestaltrun/dsh-workspace-bundle
+
+[English](README.md) | 中文
+
+## Summary
+
+本包定义 Host-only 的 `WorkspaceBundles` 服务（`ctx.workspaceBundles`）。产品插件注册打包模板；`ensure` 物化带 bundle origin 的稳定工作区，升级则整体替换目录树。普通工作区视图对该 origin 保持为空。Desktop 在 `DESKTOP_PLATFORM_PACKAGE_SOURCES` 中列出它。它以 `publishConfig.access` 为 `public`、dist-tag 为 `candidate` 发布。它不是 profile bundle，也没有 cordis patch。设计见[客服托管方案](../../.agents/design/cs-hosting/scheme.zh.md)。
+
+## Table of Contents
+
+- [Service contract](#service-contract)
+- [Template digest](#template-digest)
+- [Upgrade and recovery](#upgrade-and-recovery)
+- [Agent configurations](#agent-configurations)
+- [Configuration](#configuration)
+- [Model Experience](#model-experience)
+- [Dev Note](#dev-note)
+
+## Service contract
+
+`register(template)` 是 effect：返回的 disposer 禁止之后对该身份 `ensure` 和 `acquire`。`ensure({ bundleId, workspaceKey })` 校验模板、写入 staging 树，并注册 `origin` 为 `{ kind: 'bundle', bundleId, workspaceKey }` 的工作区。重复调用复用同一 Workspace id 与路径。`acquire(workspaceId)` 持有租约，推迟升级静止。`record(identity)` 返回持久产品记录。`pathOf(identity)` 是由 `materializeRoot` 与身份段得到的绝对物化目录，不要求先 `ensure`。
+
+这是能力包，不声明可安装 bundle patch。
+
+## Template digest
+
+打包的 `manifest.json` 列出每个文件的 SHA-256 以及按序目录的整体摘要。物化拒绝符号链接、越界路径、缺失资产、多余文件和摘要不匹配。`templateCacheRoot` 下的不可变副本供包源目录不可用时恢复校验。
+
+## Upgrade and recovery
+
+替换顺序为 staging → `updating` journal → 租约静止 → 将现根改名为 backup、将 staging 改名为稳定根 → 校验 → 提交。交换或提交点崩溃后恢复为完整旧树或完整新树；Workspace id 与路径不变。journal 为 `updating` 时消费者被屏障拦住。
+
+替换已有目录树前，Provider 在持久 `updating` 屏障下等待串行 `workspace-bundle/quiesce` 事件。消费方在监听器中取消活动、等待完成并释放租约。监听器失败时保留 journal 供恢复，并阻止目录替换。
+
+## Agent configurations
+
+`registerAgentConfigSource({ identity, revision, query })` 为已注册模板添加鉴权分配查询，返回取消并等待工作结束的异步 disposer。启动和配置间隔轮询只准备候选，不改变运行目录。`agentConfig(identity)` 提供已应用版本、候选和固定失败诊断；`refreshAgentConfig(identity)` 等待一次查询和下载。`ensure` 和 `acquire` 只在工作区没有租约时应用候选。消费者必须在 turn 开始前获取租约，保持到 turn 结束。现有替换 journal 保持 Workspace id 和路径稳定。此接口不会为了远端Agent 配置更新取消正在运行的 turn。
+
+包格式为确定性 gzip JSON，包含 `manifest` 和 `files`。清单有 `formatVersion: 1`、`workspaceKind`、完整 SemVer `version`、`hostAgentConfigApiRange`，以及按路径排序、包含 `path`、`sizeBytes`、`sha256` 的 `files`。并行文件数组保存对应 `path` 和规范 `base64`。Gzip 元数据不含时间戳或主机身份。包含构建元数据的完整版本（如 `1.0.0+build.42`）区分不同包；构建元数据不参与 SemVer 优先级比较。Host Agent 配置接口为 `1.0.0`。完整压缩字节、文件大小和摘要都通过校验后，才发布候选目录。链接、路径越界、大小写冲突、保留名称、重复文件和解压超限均被拒绝。
+
+下载目录为 `templateCacheRoot/agent-config-versions/{bundleId}/{workspaceKey}/{sha256}/{version}`，文件和版本目录只读。已提交 journal 保存完整版本和包摘要，因此模板字节相同的不同版本在重启后仍可区分。来源代次随鉴权分配身份改变；变更会取消并等待旧查询/下载、清除未提交候选并查询新身份，发布和替换时再次核对。查询回调持有凭据，本服务不向文件服务器发送凭据。下载要求 HTTPS、拒绝跳转，与查询共享超时；只有显式配置的本地 fixture 可用 loopback HTTP。查询、下载、摘要或兼容性失败都会丢弃候选并保留当前版本。`builtin` 分配保留已安装的远端版本；首次安装使用打包模板。允许分配低版本以回退。
+
+[手动工作流](../../.github/workflows/release-agent-config.yml) 接受 `workspace_kind`、`version` 和默认 true 的 `dry_run`。[agent-configs.json](../agent-configs.json) 登记各类来源。在仓库根目录先构建消费者资源，再打包：
+
+```sh
+pnpm --dir product --filter @gestaltrun/dsh-cs-hosting run build:cli
+node product/scripts/agent-config.mjs --kind cs-hosting --version 1.0.0+build.42 --out product/dist/agent-config
+```
+
+工作流沿用 `desktop-release` environment、阿里云 OIDC 角色和 `DESKTOP_RELEASE_*` OSS 变量。上传使用禁止覆盖标记，上传后回读元数据，输出 `server-registration.json`：种类、版本、SHA-256、大小、兼容范围、OSS 地址和 HTTPS 下载地址。Dry-run 生成同样的登记计划，不访问 OSS。将这些字段和发布说明写入 server 的 Agent 配置规则文件，经 PR 审阅合入后执行其经审批的 ops-job 同步任务。修改分配决定下一轮 turn 的版本；分配到已登记的旧版本即可回退。规则校验和灰度由 server 持有，参见 [R3a](https://github.com/gestaltrun/gestalt-travel-server/issues/86)。
+
+`recordWorkspaceAgentConfigVersion(session, version)` 在首次使用一个不同版本的 step 写入 `workspace-bundle/agent-config-version`。数据包含种类、完整版本、前一版本、模板摘要、包摘要（内置版本为 null）和 Host Agent 配置接口。事件不含地址或凭据。模型提示词仍记录为 `system/message`，skills 和 CLI 结果仍记录为工具结果。这个必读事件需要 Session core 登记名称；旧 reader 会拒绝它，不会重建不完整历史。
+
+已知限制：版本缓存保留，需要操作员管理磁盘；POSIX 只读权限不是 Windows ACL 安全策略。所有涉及的 turn 都必须持有租约，因此忙碌的 Session 会延迟共享工作区更新。此接口只更新内容，不热加载 Host 授权代码，也不承诺新增 Host 命令。[客服托管消费者](../cs-hosting/README.zh.md#template) 使用已发布的 server 契约。
+
+## Configuration
+
+该行要求绝对路径 `materializeRoot`、`templateCacheRoot` 和 `journalRoot`。`quiesceTimeoutMs`（1000–600000，默认 30000）和 `recycleTimeoutMs`（0–600000，默认 60000）有上下界。内容配置包括 `agentConfigPollIntervalMs`（1000–86400000，默认 300000）、`agentConfigRequestTimeoutMs`（100–600000，默认 30000）、`agentConfigMaxDownloadBytes`（1024–268435456，默认 67108864）、`agentConfigMaxExpandedBytes`（1024–536870912，默认 134217728）以及 `allowLoopbackAgentConfigHttp`（默认 false）。缺失或相对路径会以 `WorkspaceBundlesConfigError` 使插件加载失败。
+
+## Model Experience
+
+本服务仅 Host 使用，不注册模型工具。内置工作区通过 Workspace origin 从普通浏览、搜索和「新会话」继承中隐藏，而不是靠本包的提示词。
+
+## Dev Note
+
+客服托管是第一个消费者。模板文件在 [`product/cs-hosting/template`](../cs-hosting/template)，来源记录 teamwork 提交 `9e6c536f2`。
+
+不发布运行时不变量配套包：本包不持有独立观察之间的关系。