@deepseek-ai/dsh-web-app 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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/bundle/web-app/README.md
+README.md: b6fa225f5e0a0a079605a4fb9064b79287ab21cd
+README.zh.md: 68af959719b9bd146eddd143aa9d98400e65fa68

package/README.md

@@ -0,0 +1,26 @@
+# `@deepseek-ai/dsh-web-app`
+
+English | [中文](README.zh.md)
+
+The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, trustedHosts}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, enables the optional HMR row before client-module discovery so the first development graph contains its reload receiver, samples bind-dependent LAN trust once, provides it as `webRuntime` to the browser-trust fence and client roster, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner, registers the harness-source and web-surface prompt sections plus the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true, after its Loader tree settles so a sibling failure cannot announce a dead app. This bundle also owns the app command line: the ordinary `web-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), parses `--host`, `--port`, `--dev`, repeatable `--trusted-host`, and the app's `--help`, then provides `webStartup`. Flag-configured rows inject that service and read it directly from lazy config, so nothing binds a port before argument resolution and `dsh --profile web --help` starts no server. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
+
+## Model Experience
+
+### Harness-source and Web-surface context
+
+#### What the model sees
+
+When `surfaceContext` is true, the `harness:source` section identifies the on-disk Harness implementation without claiming it is the working directory, and the `app:web-surface` global section (order −98) orients the model to the GUI: the canonical local URL, the "this page" referent, the HMR/rebuild update contract for the active mode, and the instruction not to start replacement servers. `DSH_WEB_URL` and `DSH_WEB_MODE` additionally appear in the managed bash environment with their descriptions, resolved per invocation from the live server. When it is false, neither section nor the variables are registered.
+
+#### Token effect
+
+One source line and one prompt paragraph per session plus two managed-environment variable lines; constant per process.
+
+#### KV Cache effect
+
+The prompt section sits near the system prompt's head and is stable for the life of the process (port and mode are boot facts), so it does not invalidate the cache across turns.
+
+## Known Limitations and Deferred Work
+
+- **The frontend dist must be built** — `require.resolve` of the dist fails loud at activation with a build hint; there is no source-serving fallback.
+- **`lanAddresses` is a boot-time snapshot** — interface changes after boot are not re-advertised; the printed LAN URL always matches the configured trust fence.

package/README.zh.md

@@ -0,0 +1,26 @@
+# `@deepseek-ai/dsh-web-app`
+
+[English](README.md) | 中文
+
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, trustedHosts}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，在客户端模块发现前启用可选的 HMR 行，确保首份开发模式图中包含它的重载接收端，只采样一次依赖 bind 的 LAN 信任信息并将其作为 `webRuntime` 提供给浏览器信任栅栏和客户端名录，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 Harness 源码与 Web 表层提示词段落，以及 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时等自身的 Loader 配置树结算后再打印 `dsh web:` URL 行，避免兄弟行失败时公告一个已失效的应用。本组合包还持有应用命令行：普通 `web-startup` 提供方（[`src/startup.ts`](src/startup.ts)）注入 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)），解析 `--host`、`--port`、`--dev`、可重复的 `--trusted-host` 以及应用自己的 `--help`，再提供 `webStartup`。由 flag 配置的行会注入该服务，并在惰性配置中直接读取它，因此参数解析完成前不会有任何东西绑定端口，`dsh --profile web --help` 也不会启动服务器。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
+
+## 模型体验
+
+### Harness 源码与 Web 表层上下文
+
+#### 模型看到的内容
+
+当 `surfaceContext` 为 true 时，`harness:source` 段落标明磁盘上的 Harness 实现，但不会声称它就是工作目录；全局段落 `app:web-surface`（顺序 −98）则向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新约定，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。当它为 false 时，这两个段落和这些变量都不会注册。
+
+#### Token 影响
+
+每个会话一行源码说明和一段提示词，外加两行受管环境变量；每个进程内保持恒定。
+
+#### KV Cache 影响
+
+该提示词段落位于系统提示词靠前位置，且在进程整个生命周期内稳定（端口与模式是启动期事实），因此不会使跨轮次缓存失效。
+
+## 已知限制与延期工作
+
+- **前端 dist 必须已构建**：对 dist 的 `require.resolve` 在激活时明确报错并给出构建提示；没有从源码直接服务的回退路径。
+- **`lanAddresses` 是启动期快照**：启动后的网卡变化不会重新公告；打印的 LAN URL 始终与配置的信任栅栏一致。

package/cordis.patch.yml

@@ -0,0 +1,369 @@
+# The dsh-web-app bundle patch: the browser surface over the dsh-base layer.
+# Applied after dsh-base's insert; rows here override base rows by id, with
+# the profile's own cordis.patch.yml and any --patch overlays still to come.
+#
+# A patch replaces the targeted row's whole `config`, so each row below
+# restates every key it owns.
+#
+# The web-startup plugin injects `cmdlineArgs` and provides `webStartup` as an
+# ordinary Cordis service. Rows configured from flags inject that service, so
+# Loader resolves their expressions only after it exists. The web runtime then
+# provides bind-dependent `webRuntime` values to the trust fence and client
+# roster. `dsh --profile web --help` provides neither service, so no server binds.
+
+# ── surface-specific values the base deliberately omits ─────────────────────
+
+- id: system-prompt
+  config:
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+
+# TODO: Re-enable shared HMR for Web after its reload lifecycle is tested.
+- id: hmr
+  disabled: true
+
+# Web content search runs on an ephemeral in-memory index. The service
+# activates at boot, while first-search defers the node:sqlite import and
+# in-memory handle so Node 22 startup stays quiet until content search
+# actually uses SQLite. That search then reconciles this boot's sources.
+- id: session-query-sqlite
+  config:
+    path: ':memory:'
+    openAt: first-search
+
+- id: tools
+  config:
+    # TEMPORARY workaround: DSH_TOOLS_MODE (native|code|both) opts a whole dsh
+    # process into Code Mode while per-session tool-mode selection is being
+    # designed; unset keeps the schema default (native). Remove the env seam
+    # once the web UI owns the choice per session.
+    mode: !!js process.env.DSH_TOOLS_MODE
+
+# ── web-only host rows, the transport layer, and the browser roster ─────────
+
+# `dsh.client` rows are the browser roster the modules node half scans into
+# window.__DSH_BOOT__; the modules row is simultaneously a host row.
+- insert:
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker'
+
+    - id: storage
+      name: '@deepseek-ai/dsh-storage'
+
+    - id: storage-json
+      name: '@deepseek-ai/dsh-storage-json'
+      config:
+        root: !!js dshHomePath('storages')
+
+    - id: storage-domain
+      name: '@deepseek-ai/dsh-storage-domain'
+      config:
+        backend: json
+
+    - id: workspace
+      name: '@deepseek-ai/dsh-workspace'
+
+    - id: session-projection-cache
+      name: '@deepseek-ai/dsh-session-projection-cache'
+      config:
+        writeEveryEvents: 200
+        writeIntervalMs: 5000
+
+    # Resolve bind host, SSH launch, and display once at boot, then mount the
+    # matching dual-face directory picker. Mount -native or -browse directly in
+    # an overlay to pin the interaction.
+    - id: directory-picker
+      name: '@deepseek-ai/dsh-host-directory-picker-auto'
+
+    # The API gateway: the transport-agnostic dispatch face every client shape
+    # shares. The base layer's agent-default-model service owns the default model.
+    - id: api-gateway
+      name: '@deepseek-ai/dsh-host-apiproxy'
+
+    # Ordinary provider for the parsed Web flags. Its plugin-level injection
+    # waits for cmdlineArgs; no launcher metadata or special row kind is needed.
+    - id: web-startup
+      name: '@deepseek-ai/dsh-web-app/startup'
+
+    # ── layer 2: transport/service ──────────────────────────────────────────────
+
+    # Plain route-registration carrier; host and port come from the app's
+    # webStartup provider, with these deployment fallbacks. The dist is served by
+    # the web-runtime row below through the fallback seat.
+    - id: webserver
+      name: '@deepseek-ai/dsh-host-webserver'
+      inject: [webStartup]
+      config:
+        host: !!js ctx.webStartup.host ?? '127.0.0.1'
+        port: !!js ctx.webStartup.port ?? 3080
+
+    # Web glue owned by this bundle: resolves the built frontend dist (an
+    # assembly fact of dsh-web-app, never user config), mounts the
+    # frontend-static fallback owner, registers the web-surface prompt
+    # section and bash runtime variables, and prints the URL line. The webStartup
+    # provider supplies invocation-only values; after the server binds, this row
+    # samples LAN trust once and provides `webRuntime`. A complete agent-preset
+    # persona suppresses the prompt section for that agent while retaining
+    # these host-owned shell variables.
+    - id: web-runtime
+      name: '@deepseek-ai/dsh-web-app'
+      inject: [webStartup]
+      config:
+        mode: !!js ctx.webStartup.mode
+        printUrl: true
+        surfaceContext: true
+        trustedHosts: !!js ctx.webStartup.trustedHosts
+
+    # The client-plugin reload chain: a dev-only row this bundle ships off,
+    # which the runtime row turns on before client discovery. It is a row rather
+    # than a child of web-runtime because its node half is a client-side package,
+    # which a host-side bundle cannot import.
+    - id: client-hmr
+      name: '@deepseek-ai/dsh-client-hmr'
+      inject: [webStartup]
+      disabled: true
+
+    # ── browser plugin roster (dsh.client rows; node halves are layer-2 hosts) ──
+
+    # Dual-face: this waits for the runtime row to decide whether HMR belongs
+    # in the first graph. The node half then scans this tree, composes
+    # window.__DSH_BOOT__, and serves /plugins/<id>/client.js; the browser half
+    # is the module table the shell kernel constructs before cordis exists
+    # (adopted as a plugin entry by the kernel, never fetched).
+    - id: modules
+      name: '@deepseek-ai/dsh-client-modules'
+      inject: [webRuntime]
+
+    # Owns both ends of the web transport: node half binds the gateway to the
+    # webserver under /api; browser half is the fetch/SSE client.
+    - id: connection
+      name: '@deepseek-ai/dsh-client-connection'
+      inject: [webRuntime]
+      config:
+        # LAN literals derived from the active bind plus --trusted-host extras.
+        # A deployment adding authorities keeps this expression and concatenates
+        # its literals, for example: ['app.internal', ...ctx.webRuntime.trustedHosts].
+        trustedHosts: !!js ctx.webRuntime.trustedHosts
+
+    - id: api-remotes
+      name: '@deepseek-ai/dsh-api-remotes'
+
+    - id: client-runtime
+      name: '@deepseek-ai/dsh-client-runtime'
+
+    - id: ui-theme
+      name: '@deepseek-ai/dsh-client-ui-theme'
+
+    - id: locale
+      name: '@deepseek-ai/dsh-client-locale'
+
+    - id: ui-layout
+      name: '@deepseek-ai/dsh-client-ui-layout'
+
+    - id: ui-sidebar
+      name: '@deepseek-ai/dsh-client-ui-sidebar'
+
+    - id: ui-settings
+      name: '@deepseek-ai/dsh-client-ui-settings'
+
+    - id: ui-settings-general
+      name: '@deepseek-ai/dsh-client-ui-settings-general'
+
+    - id: ui-models
+      name: '@deepseek-ai/dsh-client-ui-models'
+
+    - id: ui-conversation
+      name: '@deepseek-ai/dsh-client-ui-conversation'
+
+    # Tool call tree, generic fallback, and keyed business Tool views.
+    - id: ui-tool
+      name: '@deepseek-ai/dsh-client-ui-tool'
+
+    # Turn tail: the produced-files row under each closing assistant message.
+    # Remove this entry to turn the surface off; the tail hole renders empty.
+    - id: ui-deliverables
+      name: '@deepseek-ai/dsh-client-ui-deliverables'
+
+
+    - id: ui-workspace
+      name: '@deepseek-ai/dsh-client-ui-workspace'
+
+    # Input triggers: the '/' | '@' pipeline (ui-slash), the command surface over
+    # it (ui-command), and the two reference sources (ui-skill / ui-subagent).
+    - id: ui-slash
+      name: '@deepseek-ai/dsh-client-ui-slash'
+
+    - id: ui-command
+      name: '@deepseek-ai/dsh-client-ui-command'
+
+    - id: ui-skill
+      name: '@deepseek-ai/dsh-client-ui-skill'
+
+    - id: ui-subagent
+      name: '@deepseek-ai/dsh-client-ui-subagent'
+
+    # Goal surface: GoalBar in the input dock over the goal session projection.
+    - id: ui-goal
+      name: '@deepseek-ai/dsh-client-ui-goal'
+
+    # Model selection: the /model popupSelect + composer seat over session.models.
+    - id: ui-model
+      name: '@deepseek-ai/dsh-client-ui-model'
+
+    - id: ui-permission
+      name: '@deepseek-ai/dsh-client-ui-permission'
+
+    # The agent-preset row in General settings: the default preset for
+    # sessions created later. Absent a roster it renders nothing.
+    - id: ui-agent-preset
+      name: '@deepseek-ai/dsh-client-ui-agent-preset'
+
+    # Plan control: the composer plan seat over the plan projection + /plan channel.
+    - id: ui-plan
+      name: '@deepseek-ai/dsh-client-ui-plan'
+
+    - id: ui-question
+      name: '@deepseek-ai/dsh-client-ui-question'
+
+    - id: ui-trajectory
+      name: '@deepseek-ai/dsh-client-ui-trajectory'
+
+# ── the agent plane moves behind agent presets ─────────────────────────────
+#
+# Every row below composes what ONE agent contributes to the host registries:
+# its tools, its prompt sections, its delegation backends. The base keeps them
+# for the TUI, which is single-session and composes its agent process-wide; the
+# Web surface disables them here and lets each session mount a preset instead.
+#
+# Disabling rather than deleting is deliberate: the base is shared, and a row
+# absent from a surface overlay would silently reappear the day someone reorders
+# the composition.
+
+# `bash-env` STAYS in the host plane: `apps/cli/src/web.ts` injects it to
+# publish `DSH_WEB_URL`/`DSH_WEB_MODE`, and a host row that injects a service is
+# the criterion for host-plane ownership — injection resolves before any session
+# exists, so there is no agent to key by. Behind a preset realm those variables
+# would never reach the model's shell at all.
+
+- id: tool-bash
+  disabled: true
+
+# The background-task REGISTRY stays on the host plane; only the model-facing
+# `task_*` controls move. Its producers — `tool-bash` here, `tool-pty` and a
+# non-continuable `tool-subagent` elsewhere — are preset rows that resolve it
+# with `ctx.get`, and an entry-local realm around the registry is invisible to
+# every sibling row outside that realm, so `run_in_background` answered
+# "background tasks unavailable" while the controls sat in the catalog. That is
+# the `goals` criterion read from inside the preset: a Service a row outside its
+# realm READS belongs to the plane both can see. The registry is keyed by owning
+# agent, so one host instance serves every session exactly as before presets.
+
+- id: tool-tasks
+  disabled: true
+
+- id: tool-fs
+  disabled: true
+
+- id: tool-fs-search
+  disabled: true
+
+- id: tool-str-replace-editor
+  disabled: true
+
+# The `skill` REGISTRY stays in the host plane. It is host+per-scope layered
+# (the tools-registry shape): deployment-level providers — repository plugins,
+# a host skill-local row — register into its global layer, while a preset's
+# `skill-local` registers into that preset's layer, and each agent reads the
+# merged catalog its scope chain selects. Only the per-agent rows move behind
+# presets: the base host `skill-local` row is disabled here (presets own local
+# discovery), and `tool-skill` is what a preset mounts to give its agent the
+# catalog and loader at all.
+
+- id: skill-local
+  disabled: true
+
+- id: tool-skill
+  disabled: true
+
+# The goal SERVICE, its session driver, and the `/goal` command STAY on the
+# host plane; only the model-facing tool moves. The Gateway serves the goal
+# domain as Remote endpoints, and a Remote method picks its receiver Service
+# from a generated descriptor — it resolves `goals` on the host, so a
+# per-session realm would answer `service-unavailable` for every browser call.
+# That is the `bash-env` criterion read from the other side: injection is not
+# the only host relationship a Service can have. The registry is keyed by
+# session, so one host instance serves every session exactly as before presets.
+
+- id: tool-goal
+  disabled: true
+
+- id: plan-mode
+  disabled: true
+
+- id: token-meter
+  disabled: true
+
+- id: compact-basic
+  disabled: true
+
+- id: command-compact
+  disabled: true
+
+- id: tool-result-prune
+  disabled: true
+
+# The subagent registry and its backends STAY in the host plane. `subagents` is
+# a process singleton with a cross-session query surface (`listChildren`,
+# `followup`) that the host api-proxy serves to the browser, and a provider
+# registers under a globally unique name, so a per-session copy would both
+# starve that host row and collide on the second session. What a preset
+# chooses is which delegation TOOLS its agent sees, below.
+
+- id: tool-subagent-control
+  disabled: true
+
+- id: tool-subagent-list-agents
+  disabled: true
+
+- id: tool-subagent
+  disabled: true
+
+- id: tool-subagent-fork
+  disabled: true
+
+# `tool-subagent-report` is host-plane for the same reason as the registry, not
+# because a preset may not want it: it registers a CONTINUABLE SETUP on that
+# singleton rather than a tool this agent calls, and the setup list is not
+# scope-aware — one copy per mounted preset means every child gets `report`
+# registered once per live session, which throws on the second.
+
+- id: workflow-workerthread
+  disabled: true
+
+- id: tool-workflow
+  disabled: true
+
+- id: tool-ralph
+  disabled: true
+
+- id: workspace-context
+  disabled: true
+
+- id: tool-todo
+  disabled: true
+
+- id: tool-web
+  disabled: true
+
+# The preset roster. `config/agent-presets/` ships with the deployment and is
+# read-only (its entries carry `system` trust);
+# `$DSH_HOME/.agent-presets` is where a person — or an agent — authors their own, and
+# carries the same trust as shell access because a preset IS a composition.
+# `roots` is an assembly fact, not user config: the shipped preset directory
+# ships beside this file, so AppCLIEntry resolves it and patches it in — the
+# same treatment `distIndex` gets on the webserver row.
+- insert:
+    - id: agent-presets
+      name: '@deepseek-ai/dsh-agent-presets'
+      config:
+        default: standard

package/lib/index.js

@@ -0,0 +1,131 @@
+import { createRequire } from "node:module";
+import { networkInterfaces } from "node:os";
+import { fileURLToPath } from "node:url";
+import z from "@deepseek-ai/schemastery";
+import { addHarnessSourceSection } from "@deepseek-ai/dsh-app-boot";
+import { enableRow } from "@deepseek-ai/dsh-cmdline";
+import * as FrontendStatic from "@deepseek-ai/dsh-frontend-static";
+//#region lib/types/index.js
+/**
+* @deepseek-ai/dsh-web-app — the browser-surface bundle's runtime glue plugin
+* plus the bundle patch (`cordis.patch.yml`, declared by the `dsh.bundle.patch`
+* manifest field). The plugin owns the browser-surface glue: it resolves
+* the built frontend dist (workspace knowledge of this bundle, never user
+* config), mounts the `frontend-static` fallback owner over it, registers the
+* harness-source and web-surface prompt sections, the bash-visible web runtime
+* variables, and the URL line. App command-line values arrive through the
+* `webStartup` service expressions in the bundle patch.
+* @module @deepseek-ai/dsh-web-app
+*/
+/** Stable Cordis plugin name. */
+const name = "web-app";
+/** This dsh installation's root, from either this package's source or built entry. */
+const SOURCE_ROOT = fileURLToPath(new URL("../../../..", import.meta.url));
+const HMR_ROW_ID = "client-hmr";
+/** Runtime service that releases Web rows after bind-dependent values resolve. */
+const WEB_RUNTIME_SERVICE = "webRuntime";
+/** Services required before the web runtime can mount. */
+const inject = ["httpServer"];
+const Config = z.object({
+	mode: z.union([z.const("production"), z.const("development")]).default("production"),
+	printUrl: z.boolean().default(true),
+	surfaceContext: z.boolean().default(true),
+	trustedHosts: z.array(String).default([])
+});
+/** Environment variable naming the canonical local URL of this Web GUI. */
+const DSH_WEB_URL = "DSH_WEB_URL";
+/** Environment variable naming the Web runtime mode. */
+const DSH_WEB_MODE = "DSH_WEB_MODE";
+const LOOPBACK_HOST = "127.0.0.1";
+/** The webserver schema's all-interfaces bind literal. */
+const ALL_INTERFACES_HOST = "0.0.0.0";
+/**
+* Resolve one LAN-trust snapshot from the active server bind.
+*
+* Derived entries are port-less IP literals: DNS rebinding needs an
+* attacker-controlled name, while an IP-literal Host is safe on any port and
+* an OS-assigned port is unknowable before bind.
+* @param bindHost - the active webserver bind host.
+* @param extra - explicit `--trusted-host` values, in argument order.
+* @returns the LAN display addresses and invocation-derived fence authorities.
+*/
+function resolveLanTrust(bindHost, extra) {
+	const lanAddresses = bindHost === ALL_INTERFACES_HOST ? Object.values(networkInterfaces()).flat().filter((iface) => iface !== void 0 && iface.family === "IPv4" && !iface.internal).map((iface) => iface.address) : [];
+	return {
+		lanAddresses,
+		trustedHosts: [...lanAddresses, ...extra]
+	};
+}
+/** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */
+function webSurfacePrompt(webUrl, mode) {
+	const updateContract = mode === "development" ? "This Web process was launched with `dsh web --dev`, so its client-plugin HMR receiver is active. No-refresh updates occur only when `pnpm run dev:web` is also running from this same checkout to rebuild client-plugin bundles; verify that watcher before promising automatic updates. Client-plugin changes then reload automatically, while apps/web shell and other plain-package changes still require a rebuild and page refresh. " : "This Web process was launched without `--dev`, so HMR is inactive: rebuild the affected Web artifacts and verify this existing URL after a page refresh. If the user wants no-refresh client-plugin updates, explain that this GUI must be restarted with `dsh web --dev` and `pnpm run dev:web` must also run from this same checkout; do not present either command alone as sufficient. ";
+	return `You are interacting with the user through the DeepSeek Harness Web GUI at ${webUrl}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. ` + updateContract + "Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.";
+}
+/** Resolve the canonical loopback URL from the active Web server. */
+function localWebUrl(ctx) {
+	const port = ctx.get("httpServer")?.port;
+	if (port === void 0) throw new Error("web-app: httpServer service missing while resolving Web runtime");
+	return `http://${LOOPBACK_HOST}:${String(port)}`;
+}
+/** Dist location is workspace knowledge of this bundle: resolved through the frontend package exports, not configured. */
+function resolveDistIndex() {
+	const require = createRequire(import.meta.url);
+	try {
+		return require.resolve("@deepseek-ai/dsh-frontend/dist/index.html");
+	} catch {
+		/* v8 ignore next 2 -- reachable only on a checkout without a built dist; the test tree builds it */
+		throw new Error("web-app: frontend dist not built; run pnpm run build from the repository root first");
+	}
+}
+/** Test hook: hosts with no built frontend dist substitute the resolver; production never touches this. */
+const internals = { resolveDistIndex };
+/**
+* Mount the Web runtime: dist serving, surface prompt, bash runtime
+* variables, and the URL line.
+* @param ctx - plugin context carrying the httpServer service.
+* @param config - validated {@link Config}.
+* @returns nothing once the invocation's client roster and runtime contributions are registered.
+*/
+async function apply(ctx, config) {
+	if (config.mode === "development") await enableRow(ctx, HMR_ROW_ID);
+	const runtime = resolveLanTrust(ctx.httpServer.host, config.trustedHosts);
+	ctx.provide(WEB_RUNTIME_SERVICE, runtime);
+	ctx.plugin(FrontendStatic, { distIndex: internals.resolveDistIndex() });
+	if (config.surfaceContext) {
+		ctx.inject(["systemPrompt"], (promptCtx) => {
+			addHarnessSourceSection(promptCtx, SOURCE_ROOT);
+			promptCtx.systemPrompt.section({
+				name: "app:web-surface",
+				order: -98,
+				text: () => webSurfacePrompt(localWebUrl(promptCtx), config.mode)
+			});
+		});
+		ctx.inject(["bashEnv"], (runtimeCtx) => {
+			runtimeCtx.bashEnv.register({
+				name: "web-runtime",
+				variables: {
+					[DSH_WEB_URL]: { description: "Canonical local URL of the DeepSeek Harness Web GUI serving this session." },
+					[DSH_WEB_MODE]: { description: "Web runtime mode: production, or development when the client-plugin HMR receiver is active." }
+				},
+				resolve: () => ({
+					[DSH_WEB_URL]: localWebUrl(runtimeCtx),
+					[DSH_WEB_MODE]: config.mode
+				})
+			});
+		});
+	}
+	if (config.printUrl) {
+		const printUrl = () => {
+			const lanCandidate = runtime.lanAddresses[0];
+			const port = ctx.httpServer.port;
+			console.log(`dsh web: ${localWebUrl(ctx)}${lanCandidate === void 0 ? "" : ` (LAN: http://${lanCandidate}:${String(port)})`}`);
+		};
+		const settled = ctx.get("loader")?.await();
+		if (settled === void 0) printUrl();
+		else settled.then(() => {
+			if (ctx.get("httpServer") !== void 0) printUrl();
+		}, () => {});
+	}
+}
+//#endregion
+export { Config, apply, inject, internals, name, resolveLanTrust };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-web-app`.
+* @module @deepseek-ai/dsh-web-app/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-web-app";
+/** Cordis companion plugin name. */
+const name = "web-app-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: every contribution (frontend-static child plugin,
+* prompt section, bashEnv registration) is registry-disposed with the fiber,
+* and each owning registry's package carries that relation's invariant; the
+* package holds no mutable state of its own to audit.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/startup.js

@@ -0,0 +1,55 @@
+import { parseCmdline } from "@deepseek-ai/dsh-cmdline";
+import { Command } from "commander";
+//#region lib/types/startup.js
+/**
+* The web app's command-line provider: it parses the `dsh --profile web` flag
+* family (`--host`, `--port`, `--dev`, `--trusted-host`) and its `--help`
+* text, then provides the immutable values as {@link WEB_STARTUP_SERVICE}.
+* Ordinary rows inject that service before reading it from lazy config.
+* @module @deepseek-ai/dsh-web-app/startup
+*/
+/** Stable Cordis plugin name. */
+const name = "web-startup";
+/** Services required before the flags can be resolved. */
+const inject = ["cmdlineArgs"];
+/** Service provided by this ordinary plugin and injected by flag-configured rows. */
+const WEB_STARTUP_SERVICE = "webStartup";
+/**
+* This app's command: its flags, its description, and its help text.
+* @returns a fresh program, so one process can parse more than once (tests).
+*/
+function webCommand() {
+	return new Command().name("dsh --profile web").description("Serve the DeepSeek Harness browser UI.").helpOption("-h, --help", "show this help").option("--host <host>", "bind host; pass 0.0.0.0 to reach it from another machine").option("--port <port>", "listen port; pass 0 to let the OS pick a free one").option("--dev", "mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)").option("--trusted-host <authority...>", "extra authority the /api browser-trust fence accepts (host or host:port; repeatable)").addHelpText("after", `
+Examples:
+  dsh --profile web                          serve on the composed host and port
+  dsh --profile web --port 8080              serve on another port
+  dsh --profile web --host 0.0.0.0           reach it from another machine on the LAN
+  dsh --profile web --dev                    mount the client-plugin HMR receiver
+`);
+}
+/**
+* Turn the parsed flags into the value injected rows read.
+* @param program - the parsed web command.
+* @returns this invocation's immutable Web options.
+*/
+function planWebStartup(program) {
+	const options = program.opts();
+	if (options.port !== void 0 && !/^\d+$/.test(options.port)) program.error(`error: --port must be a number, got ${JSON.stringify(options.port)}`);
+	return {
+		...options.host !== void 0 && { host: options.host },
+		...options.port !== void 0 && { port: Number(options.port) },
+		mode: options.dev === true ? "development" : "production",
+		trustedHosts: options.trustedHost ?? []
+	};
+}
+/**
+* Parse and provide the Web invocation as an ordinary Cordis service.
+* @param ctx - plugin context carrying the command line.
+* @returns nothing once values are provided, or when the command requested exit.
+*/
+function apply(ctx) {
+	const values = parseCmdline(ctx, webCommand(), planWebStartup);
+	if (values !== void 0) ctx.provide(WEB_STARTUP_SERVICE, values);
+}
+//#endregion
+export { WEB_STARTUP_SERVICE, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @deepseek-ai/dsh-web-app — the browser-surface bundle's runtime glue plugin
+ * plus the bundle patch (`cordis.patch.yml`, declared by the `dsh.bundle.patch`
+ * manifest field). The plugin owns the browser-surface glue: it resolves
+ * the built frontend dist (workspace knowledge of this bundle, never user
+ * config), mounts the `frontend-static` fallback owner over it, registers the
+ * harness-source and web-surface prompt sections, the bash-visible web runtime
+ * variables, and the URL line. App command-line values arrive through the
+ * `webStartup` service expressions in the bundle patch.
+ * @module @deepseek-ai/dsh-web-app
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable Cordis plugin name. */
+export declare const name = "web-app";
+/** Services required before the web runtime can mount. */
+export declare const inject: string[];
+/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
+export type WebMode = 'production' | 'development';
+/** Plugin config: composed deployment settings plus per-invocation command-line values. */
+export interface Config {
+    /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
+    mode: WebMode;
+    /** Print the URL line on activation; a non-interactive layer can turn it off. */
+    printUrl: boolean;
+    /**
+     * Register the model-visible surface context (the `app:web-surface` prompt
+     * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
+     * non-interactive layer can turn it off when its user is not in the GUI, so the
+     * orientation text would be false.
+     */
+    surfaceContext: boolean;
+    /** Explicit `--trusted-host` authorities from this invocation. */
+    trustedHosts: string[];
+}
+export declare const Config: z<Config>;
+/** Bind-dependent Web values shared by the trust fence and URL display. */
+export interface WebRuntimeValues {
+    /** LAN IPv4 literals sampled once when the server binds all interfaces. */
+    lanAddresses: string[];
+    /** LAN literals followed by explicit invocation authorities. */
+    trustedHosts: string[];
+}
+/**
+ * Resolve one LAN-trust snapshot from the active server bind.
+ *
+ * Derived entries are port-less IP literals: DNS rebinding needs an
+ * attacker-controlled name, while an IP-literal Host is safe on any port and
+ * an OS-assigned port is unknowable before bind.
+ * @param bindHost - the active webserver bind host.
+ * @param extra - explicit `--trusted-host` values, in argument order.
+ * @returns the LAN display addresses and invocation-derived fence authorities.
+ */
+export declare function resolveLanTrust(bindHost: string, extra: readonly string[]): WebRuntimeValues;
+/** Test hook: hosts with no built frontend dist substitute the resolver; production never touches this. */
+export declare const internals: {
+    resolveDistIndex: () => string;
+};
+/**
+ * Mount the Web runtime: dist serving, surface prompt, bash runtime
+ * variables, and the URL line.
+ * @param ctx - plugin context carrying the httpServer service.
+ * @param config - validated {@link Config}.
+ * @returns nothing once the invocation's client roster and runtime contributions are registered.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-web-app`.
+ * @module @deepseek-ai/dsh-web-app/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "web-app-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/startup.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The web app's command-line provider: it parses the `dsh --profile web` flag
+ * family (`--host`, `--port`, `--dev`, `--trusted-host`) and its `--help`
+ * text, then provides the immutable values as {@link WEB_STARTUP_SERVICE}.
+ * Ordinary rows inject that service before reading it from lazy config.
+ * @module @deepseek-ai/dsh-web-app/startup
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "web-startup";
+/** Services required before the flags can be resolved. */
+export declare const inject: string[];
+/** Service provided by this ordinary plugin and injected by flag-configured rows. */
+export declare const WEB_STARTUP_SERVICE = "webStartup";
+/** What the web rows read from {@link WEB_STARTUP_SERVICE}. */
+export interface WebStartupValues {
+    /** `--host`, absent when the invocation did not name one. */
+    host?: string;
+    /** `--port`, absent when the invocation did not name one. */
+    port?: number;
+    /** Web runtime mode; `--dev` selects development, which also mounts the client-plugin reload chain. */
+    mode: 'production' | 'development';
+    /** Explicit `--trusted-host` authorities, in argument order. */
+    trustedHosts: string[];
+}
+/**
+ * Parse and provide the Web invocation as an ordinary Cordis service.
+ * @param ctx - plugin context carrying the command line.
+ * @returns nothing once values are provided, or when the command requested exit.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=startup.d.ts.map

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@deepseek-ai/dsh-web-app",
+  "description": "The dsh browser-surface bundle: the web patch layer over dsh-base plus the runtime glue plugin (frontend dist serving, web-surface prompt, bash runtime variables, URL line)",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/bundle/web-app"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./startup": {
+      "types": "./lib/types/startup.d.ts",
+      "default": "./lib/startup.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/startup.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "@deepseek-ai/dsh-app-boot": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-connection": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent-presets": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-hmr": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-modules": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-agent-preset": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-command": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-deliverables": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-goal": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-model": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-models": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-layout": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-permission": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-plan": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-question": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-skill": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-general": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slash": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-theme": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-tool": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-trajectory": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-workspace": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-cmdline": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-code-runtime-worker": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-frontend": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-frontend-static": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-host-apiproxy": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-host-directory-picker-auto": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-host-directory-picker-browse": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-host-directory-picker-native": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-projection-cache": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-storage-json": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-workspace": "^0.0.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash-env": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-bash-env": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}