@x1a0f3n9/dsh-client-ui-cordis 0.1.5-rc.3

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/extensions/ui-cordis/README.md
+README.md: 1cd6d778148d1afdcfc470b20b7e5ac437a21921
+README.zh.md: 2c15d6be3fcbfb4667cbdee7761f8e3716ce5c39

package/README.md

@@ -0,0 +1,130 @@
+---
+description: "Cordis dynamic-plugin browser surfaces for users and maintainers choosing, composing, or debugging the panel, tool cards, and @pluginId input."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-client-ui-cordis
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`dsh-client-ui-cordis` adds a frame-wide control panel, conversation tool cards, and `@pluginId` completion for dynamic Cordis packages in a web client. A person can approve or decline a blocked model request from any session, run, stop, or remove definitions, and inspect their live status. Conversation cards replay recorded calls and results. The package adds no model-visible content or session events, and definitions must be run again after the page reloads.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [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
+
+Compose this package in a web client that also mounts the browser runner and the host runner, and it adds the panel, the tool cards, and the `@` completion. A person then has everything needed to run the lifecycle: approve or decline a model's run request, run, stop, or remove any definition, and watch a package's live state change on the same rows.
+
+### What the panel shows
+
+A `sidebar.footer.action` seat shows a badge counting what runs plus what waits; opening it lists every definition with its run controls. The list is never filtered by session: the current session's rows group first, everyone else's stay listed below. Rows come from the host's current inventory and update whenever an announcement changes what exists. A pending run request whose definition the last read does not cover still gets a row, rendered from the request's own session, label, purpose, and identity. Each row shows two independent facts — what the host runs and what this page has loaded — so a reloaded page offers "load back into this page" before the global stop, while a host-only definition reads plainly running and offers the stop alone. The row also carries this page's last render failure inline, in the same place as a load failure: one is "it never loaded", the other "it loaded and then threw".
+
+### What the tool cards show
+
+The `cordis_define` card is a record: the name and purpose the model wrote, the source it wrote, and whether the definition is running — no switch, no approval, and a pointer to the panel. The `cordis_run` card shows the mode, the plugin, package, and run ids, the outcome, and offers the package's own business view through the `tool.view.cordis` slot when the package registered one. `cordis_stop` and `cordis_undefine` render compact action rows. All cards render from the recorded call and result, so replay shows the same card.
+
+### The @pluginId input source
+
+Typing `@` in the input offers the current session's defined plugins; picking one emits `@pluginId`, which the tool package turns into a pinned reference context for the model.
+
+### Boundaries to plan around
+
+Definitions are process-local: a reloaded page holds nothing until someone runs a package again, and the panel re-reads the inventory on every announcement. Approvals are frame-wide by design, so a person in one tab can approve a run the model asked for while another tab shows the defining session; the first answer wins and the rest converge.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design behind the surfaces; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The surfaces are built on one rule: neither keeps run state in component state, because settling a define call moves its card in the chat flow and remounts it. Facts live in observables owned by whoever can close them — the browser runner owns open requests, orchestration outcomes, this page's live set and its render failures, while this package owns the inventory it read and the announcements it folded. The panel is global because a run request blocks the model and can name a definition belonging to a session nobody is looking at; an approval reachable only inside that session's transcript would be unreachable exactly when it blocks the model.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/client/index.ts`](src/client/index.ts) | Plugin entry: slot registrations, inventory wiring, `@pluginId` source |
+| [`src/client/CordisPanel.tsx`](src/client/CordisPanel.tsx) | The frame-wide panel and its run controls |
+| [`src/client/CordisDefineRow.tsx`](src/client/CordisDefineRow.tsx) | The read-only `cordis_define` card |
+| [`src/client/CordisRunRow.tsx`](src/client/CordisRunRow.tsx) | The `cordis_run` card and its business-view seat |
+| [`src/client/CordisActionRow.tsx`](src/client/CordisActionRow.tsx) | The `cordis_stop` / `cordis_undefine` rows |
+| [`src/client/card-model.ts`](src/client/card-model.ts) | Replay-stable view models derived from frozen call/result slices |
+| [`src/client/inventory.ts`](src/client/inventory.ts) | The single-flight inventory read and its reconnect handling |
+| [`src/client/status.ts`](src/client/status.ts) | The visible status readings over inventory and the page's live set |
+| [`src/client/slots.ts`](src/client/slots.ts) | Injected faces and the package-owned `tool.view.cordis` slot declaration |
+| [`src/client/run-card-index.ts`](src/client/run-card-index.ts) | Per-session index of the latest eligible `cordis_run` card |
+
+### How the panel stays current
+
+Announcements (`cordis/dynamic-package`, `cordis/dynamic-retract`, `cordis/request-run`, `cordis/request-run-resolved`) trigger an inventory re-read instead of a patch-in-place update, because they carry no labels and a definition can appear or disappear between them. Reads are single-flight so several announcements settling at once cannot multiply the call; a connection reset both discards the in-flight read and frees the slot for a fresh one, so a reconnect never publishes the old host's rows.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the surfaces to the face they operate and the tools whose calls they render.
+
+- [Client runner](../cordis-client-runner/README.md) — the browser face the panel reads and calls.
+- [Host runner](../cordis-host-runner/README.md) — the inventory and lifecycle verbs behind the panel.
+- [Tool package](../tool-cordis/README.md) — the model-facing tools whose calls these cards render.
+- [Extensions subsystem](../../../docs/subsystems/extensions.md) — the generated `ctx.dynamicCordisRunner` API and forwarded `cordis/*` events.
+- [Slots subsystem](../../../docs/subsystems/slots.md) — how slot-registered browser UI is owned by its package.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through the run and stop verbs these surfaces drive — the browser-side runner's orchestration for a run, and the host's stop and remove verbs, the same host verbs the model's `cordis_run` and `cordis_stop` tools reach — so whatever a running definition then contributes is the runner's effect, while nothing model-visible originates in this package, which renders logged call and result slices and a host inventory read, adds no prompt content, writes no session event, and deliberately leaves no session-log trace of a person approving, declining, running, or stopping anything.
+
+#### KV Cache effect
+
+None: no prompt input originates here, and answering a run request neither extends nor rewrites the history tail.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where the surfaces need special care. They are current package constraints, not a task backlog.
+
+- **An open panel does not see registry changes that announce nothing** — `cordis_define`, and an undefine of a definition that was not running, change the registry without a dispatch announcement, so a panel left open across one of them keeps its rows until it is closed and opened again. A run request is the exception: it blocks the model, so it both renders its own row and triggers a read.
+- **A request-only row is answerable but not operable** — it offers approve and decline only, because the run and stop controls need the registry row the read has yet to deliver.
+- **A row can disappear for the width of one read** — the activity's orchestrating arm carries the session but deliberately no label, so an approved request whose registry read has not landed leaves no row until it does; in practice the read is triggered when the request arrives.
+- **A render failure is this page's own reading, and it arrives too late for the run receipt** — the panel shows the last crash the runner saw here, so a package that renders fine in this tab shows nothing even while it crashes in another, and the model learns about it by asking (`cordis_inspect_self`) rather than from the call it already made.
+- **A second page's load failure is invisible to the others** — the host settles a dispatch on the first load report, so a page whose browser half failed after another page acknowledged keeps reading as running on the other pages.
+- **Any page may answer any request** — approvals are frame-wide by design, so a person in one tab can approve a run the model asked for while another tab is in front of the defining session; narrowing who may answer is deferred.
+- **A card whose call head left the event window loses its labels** — the define card derives name and purpose from the call arguments, so a session long enough to truncate them leaves the card naming its call id; the panel is unaffected because the host inventory carries the labels.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. A single keyed toolview registration whose disposal is proven by the HMR-safety spec. The one mutable relation this package owns — the per-definition run-state observable — lives in the browser process, out of reach of the host invariant service, and the node half emits no cordis events and holds no cross-plugin state.

package/README.zh.md

@@ -0,0 +1,130 @@
+---
+description: "Cordis 动态插件浏览器面说明，供选择、组合或排查面板、工具卡片与 @pluginId 输入的用户与维护者阅读。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-client-ui-cordis
+
+[English](README.md) | 中文
+
+## 概述
+
+`dsh-client-ui-cordis` 为 web 客户端中的动态 Cordis 包提供框架级控制面板、会话工具卡片与 `@pluginId` 补全。人可以从任意会话批准或拒绝阻塞模型的请求、运行、停止或移除定义，并查看其实时状态。会话卡片会回放已记录的调用与结果。本包不增加模型可见内容或会话事件；页面刷新后，定义必须重新运行。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在同时挂载了浏览器 runner 与 host runner 的 web 客户端中组合本包，它会加上面板、工具卡片与 `@` 补全。人便拥有执行完整生命周期所需的一切：批准或拒绝模型的 run 请求、运行、停止或移除任意定义，并在同一行上看到包的实时状态变化。
+
+### 面板显示什么
+
+一个 `sidebar.footer.action` 席位显示角标，计数在跑数加待确认数；点开后列出每个定义及其运行控件。列表从不按会话过滤：当前会话的行置顶成组，其他会话的行仍在下方列出。行来自 host 的当前清单，并在公告改变「有哪些定义」时更新。上一次读取覆盖不到的待审批 run 请求仍然有行，直接用请求自带的会话、标签、用途与标识渲染。每一行显示两个独立事实——host 在跑什么与本页装载了什么——因此刷新后的页面会先给「装回本页」、再给全局 stop，而纯 host 定义的行如实读作运行中、只给 stop。该行还会把本页最后一次渲染失败就地显示，与装载失败共用同一个位置：一个是「它从来没装上」，另一个是「它装上了、然后抛了」。
+
+### 工具卡片显示什么
+
+`cordis_define` 卡片是一份记录：模型写下的 name 与 purpose、它写的源码，以及该定义是否在跑——没有开关、没有审批，只有一句指向面板的指引。`cordis_run` 卡片显示模式、插件标识、包标识与运行标识、结果，并在包注册了业务视图时经 `tool.view.cordis` slot 提供它。`cordis_stop` 与 `cordis_undefine` 渲染紧凑的动作行。所有卡片都渲染会话记录下的 call 与 result，因此回放显示同一张卡。
+
+### @pluginId 输入源
+
+在输入框里键入 `@` 会给出当前会话已定义的插件；选中一个会输出 `@pluginId`，工具包把它变成一条钉住的引用上下文给模型。
+
+### 需要规划的边界
+
+定义仅存在于进程内：刷新后的页面手上什么都没有，直到有人再次运行某个包；面板在每次公告时重读清单。审批按设计是框架级的，所以某个标签页里的人可以批准模型为另一个标签页正在看的会话所发起的 run；首个应答生效，其余收敛。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释这些界面背后的设计；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+这些界面建立在一个规则之上：两者都不把运行态放进组件 state，因为 define 调用结算时卡片会在聊天流里换位置并重挂。事实活在「谁能关闭它、就归谁」的观察量里——浏览器 runner 拥有开放请求、编排结果、本页的 live set 及其渲染失败，而本包拥有自己读来的清单与折叠过的公告。面板做成全局，是因为 run 请求会阻塞模型、且可能点名一个当前没人在看的会话里的定义；审批入口若只存在于那个会话的对话流里，就会在它正阻塞模型的时候恰好不可达。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/client/index.ts`](src/client/index.ts) | 插件入口：slot 注册、清单接线、`@pluginId` 输入源 |
+| [`src/client/CordisPanel.tsx`](src/client/CordisPanel.tsx) | 全局面板及其运行控件 |
+| [`src/client/CordisDefineRow.tsx`](src/client/CordisDefineRow.tsx) | 只读的 `cordis_define` 卡片 |
+| [`src/client/CordisRunRow.tsx`](src/client/CordisRunRow.tsx) | `cordis_run` 卡片及其业务视图席位 |
+| [`src/client/CordisActionRow.tsx`](src/client/CordisActionRow.tsx) | `cordis_stop`／`cordis_undefine` 行 |
+| [`src/client/card-model.ts`](src/client/card-model.ts) | 从冻结 call/result 切片派生的可回放视图模型 |
+| [`src/client/inventory.ts`](src/client/inventory.ts) | 单飞清单读取及其重连处理 |
+| [`src/client/status.ts`](src/client/status.ts) | 基于清单与本页 live set 的可见状态读数 |
+| [`src/client/slots.ts`](src/client/slots.ts) | 注入面与包自有的 `tool.view.cordis` slot 声明 |
+| [`src/client/run-card-index.ts`](src/client/run-card-index.ts) | 每会话「最新合格 `cordis_run` 卡片」索引 |
+
+### 面板如何保持最新
+
+公告（`cordis/dynamic-package`、`cordis/dynamic-retract`、`cordis/request-run`、`cordis/request-run-resolved`）触发清单重读，而不是就地打补丁——因为公告不携带标签，而定义可能在两次公告之间出现或消失。读取是单飞的，因此多条公告同时结算不会放大调用次数；连接重置既丢弃在途读取、又为新读取腾出位置，所以重连绝不会发布旧 host 的行。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从这些界面逐步进入它们所操作的面，以及其调用被渲染成卡片的工具。
+
+- [Client runner](../cordis-client-runner/README.zh.md)——面板读取并调用的浏览器面。
+- [Host runner](../cordis-host-runner/README.zh.md)——面板背后的清单与生命周期动词。
+- [工具包](../tool-cordis/README.zh.md)——调用被这些卡片渲染的模型侧工具。
+- [extensions 子系统](../../../docs/subsystems/extensions.zh.md)——生成的 `ctx.dynamicCordisRunner` API 与转发的 `cordis/*` 事件。
+- [slots 子系统](../../../docs/subsystems/slots.zh.md)——slot 注册的浏览器 UI 如何归其包所有。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接影响，经由这些界面驱动的 run 与 stop 动词——run 走浏览器侧 runner 的编排，stop 与 remove 走 host 的动词，与模型的 `cordis_run` / `cordis_stop` 工具是同一批 host 动词。因此正在运行的定义随后贡献的任何内容，都是 runner 的效果，而本包不产生任何模型可见输入：它只渲染已落日志的 call 与 result 切片和一次 host 清单读取，不加提示词内容、不写会话事件，并刻意不为「有人批准、拒绝、运行或停止」留下会话日志痕迹。
+
+#### KV Cache 影响
+
+无：没有任何提示词输入源自这里，应答一次 run 请求既不延长也不改写历史尾部。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明这些界面何时需要特别小心。它们是当前包约束，不是任务积压。
+
+- **已展开的面板看不到「不广播任何东西」的注册表变化**——`cordis_define`，以及对一个并未在运行的定义执行 undefine，都会改变注册表却不发出下发公告；因此跨过这类变化时，已展开的面板会保留旧行，直到收起再展开。run 请求是例外：它阻塞模型，所以它既自己渲染出行，也触发一次读取。
+- **只有请求、没有清单的行可应答但不可操作**——它只提供批准与拒绝，因为 run／stop 控件需要那次读取尚未送达的注册表行。
+- **行可能消失一次读取的时长**——活动的 orchestrating 臂带会话但刻意不带标签，因此一个已批准、但注册表读取尚未落地的请求，在读取落地前没有行；实践中读取在请求到达时即已触发。
+- **渲染失败是本页自己的读数，而且它来得太晚、赶不上 run 的回执**——面板显示的是 runner 在本页看到的最后一次崩溃，所以一个在本标签页渲染正常的包，即使正在另一个标签页里崩溃，这里也什么都不显示；模型只能靠主动去问（`cordis_inspect_self`）才知道，而不是从它已经发出的那次调用里得知。
+- **某一页的装载失败对其他页不可见**——host 以首个装载回报结算一次 dispatch，因此在另一页确认之后浏览器半才失败的页面，在其他页上仍会读作运行中。
+- **任何页面都可以应答任何请求**——审批按设计是框架级的，所以某个标签页里的人可以批准模型为另一个标签页正在看的会话所发起的 run；收窄「谁有权应答」延后。
+- **call head 掉出事件窗的卡片会丢掉标签**——define 卡片的 name 与 purpose 取自调用参数，因此会话长到把它们截断时，卡片只能以自己的 call id 自称；面板不受影响，因为 host 清单携带标签。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。插件只注册一个 keyed toolview，其资源释放已由 HMR 安全性测试证明。本包拥有的唯一可变关系，即 per-definition run-state 观察量，只存在于浏览器进程中，Host 不变式服务无法触及；Node 端不发出任何 Cordis 事件，也不持有任何跨插件状态。