@deepseek-ai/dsh-agent-preset-registry 0.1.7-alpha.1

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/preset/agent-preset-registry/README.md
+README.md: 7a1ee3e733fc54194515dbf093e53af0c9698e40
+README.zh.md: 11206a3f9237cbca237220a81fd98ec5eea1083e

package/README.md

@@ -0,0 +1,107 @@
+---
+description: "Choose an Agent’s tools, prompt sections and skills through declarative presets. One process can run several compositions. Failed definitions remain visible, while existing Agents retain the composition they already use."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-agent-preset-registry
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Choose an Agent’s tools, prompt sections and skills through declarative presets. One process can run several compositions. Failed definitions remain visible, while existing Agents retain the composition they already use.
+
+## 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
+
+### Minimal configuration
+
+```yaml
+- id: agent-preset-registry
+  name: '@deepseek-ai/dsh-agent-preset-registry'
+  config:
+    default: standard
+- id: preset-standard
+  name: '@deepseek-ai/dsh-agent-preset'
+  config:
+    id: standard
+    plugins: []
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `default` | required | Preset ID used when none is requested |
+
+The Web definitions come from the `dsh-web-app` bundle. Definitions are ordinary plugin rows; the registry neither scans directories nor accepts preset paths. The `selectedDefault` and `modeSelectionEnabled` volatile fields of the `agent-preset-registry` entry retain the user default and the chooser visibility; hiding the chooser uses the deployment `default`.
+
+The registry writes no declarations. A new preset or an override of a shipped one is a bundle patch: an `insert` of a `@deepseek-ai/dsh-agent-preset` row, or a patch keyed by that row’s id, installed into the profile with `plugin_manager`; Creator mode authors such bundles in conversation.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+Each declaration eagerly creates a registry-owned scope and an in-memory Loader tree. Updating or removing a declaration retires its previous revision. Agents, children and temporary historical reads retain references; releasing the final reference disposes the retired tree. Plugin registrations inherit the preset scope, and the Agent scope’s parent link controls visibility. The Host continues to share the Agent loop.
+
+Activation auditing checks imports, missing services and globally leaked services. Import failures, activation failures and leaks reject the mount. A row waiting for a Host service stays mounted, and every read and binding re-audits it after the Host Loader tree settles, so startup order does not decide the outcome. Failure prevents new bindings to that definition. Session logs retain the preset ID and blank-session selections; recovery after restart uses the current definition of that ID and rejects a missing definition.
+
+| File | Responsibility |
+|---|---|
+| [index.ts](src/index.ts) | Registration, revisions and Agent bindings |
+| [mount.ts](src/mount.ts) | Scoped plugin trees and activation auditing |
+
+</details>
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Scope](../../core/scope/README.md) — Registration isolation.
+- [Agent](../../core/agent/README.md) — Session runtime.
+- [Cordis](../../../docs/cordis-primer.md) — Plugin configuration and lifecycle.
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Preset selection
+
+#### What the model sees
+
+Nothing directly: the selected preset’s `plugins` own the model-visible tools and prompt sections.
+
+#### Token effect
+
+None from this package; each mounted `plugins` row declares its own tools and sections.
+
+#### KV Cache effect
+
+Existing Agents retain their plugins and prompts. New Agents build their prefixes from the current definition.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- Presets are not security sandboxes: YAML and plugins can execute Host code. A user override replaces the complete child list and does not automatically merge future changes to the builtin list. Old revision implementations are not retained across process restarts.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** The companion checks services leaked globally after activation and Agents addressing a model without joining a configured preset.

package/README.zh.md

@@ -0,0 +1,107 @@
+---
+description: "通过声明式 preset 选择 Agent 的工具、提示词和技能。同一进程可以运行多种组合。配置失败会显示在列表中；现有 Agent 保留已经使用的组合。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-agent-preset-registry
+
+[English](README.md) | 中文
+
+## 概述
+
+通过声明式 preset 选择 Agent 的工具、提示词和技能。同一进程可以运行多种组合。配置失败会显示在列表中；现有 Agent 保留已经使用的组合。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [延伸阅读](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与待办](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用此包
+
+### 最小配置
+
+```yaml
+- id: agent-preset-registry
+  name: '@deepseek-ai/dsh-agent-preset-registry'
+  config:
+    default: standard
+- id: preset-standard
+  name: '@deepseek-ai/dsh-agent-preset'
+  config:
+    id: standard
+    plugins: []
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `default` | 必填 | 未显式指定时使用的 preset ID |
+
+Web 内置定义来自 `dsh-web-app` bundle。定义使用普通插件行；注册表不扫描目录，也不接受 preset 路径。`agent-preset-registry` 条目的 volatile 字段 `selectedDefault` 与 `modeSelectionEnabled` 保留用户默认值和选择器可见性；隐藏选择器时使用部署 `default`。
+
+注册表不写入任何声明。新建 preset 或覆盖内置 preset 都是 bundle 补丁：插入一行 `@deepseek-ai/dsh-agent-preset`，或按该行 id 写覆盖补丁，再用 `plugin_manager` 安装到 profile；创造模式在对话中编写这类 bundle。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节 — 点击展开</summary>
+
+每个声明在启动时创建注册表拥有的 scope 和内存 Loader 树。更新或移除声明会让旧代际退役；Agent、子 Agent 和临时历史读取各自持有引用，最后一个引用释放后才销毁插件树。插件注册继承 preset scope，Agent scope 的父链接决定可见性；Agent loop 仍由宿主共享。
+
+激活审计检查导入失败、缺失服务和向全局泄漏的服务。导入失败、激活失败和泄漏会拒绝挂载。等待 Host 服务的行保持挂载，每次读取和绑定都在 Host Loader 树结算后重新审计，因此启动顺序不决定结果。失败只禁用该定义的新绑定。会话日志保存 preset ID 和空白会话的切换记录；重启恢复使用该 ID 的当前定义，缺失时拒绝恢复。
+
+| 文件 | 职责 |
+|---|---|
+| [index.ts](src/index.ts) | 注册、代际与 Agent 绑定 |
+| [mount.ts](src/mount.ts) | 隔离插件树与激活审计 |
+
+</details>
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [Scope](../../core/scope/README.zh.md) — 注册隔离。
+- [Agent](../../core/agent/README.zh.md) — 会话运行时。
+- [Cordis](../../../docs/cordis-primer.zh.md) — 插件配置与生命周期。
+
+<a id="model-experience"></a>
+## 模型体验
+
+### Preset 选择
+
+#### 模型看到的内容
+
+没有直接内容：所选 preset 的 `plugins` 拥有模型可见的工具和提示词片段。
+
+#### Token 影响
+
+本包自身没有；每个挂载的 `plugins` 行声明自己的工具和片段。
+
+#### KV Cache effect
+
+已有 Agent 保留插件和提示词。新 Agent 从当前定义构建前缀。
+
+## 已知限制与待办
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- preset 不是安全沙箱：YAML 及插件可以执行 Host 代码。用户覆盖替换完整子插件列表，不自动合并内置列表的未来更新。进程退出后不保存旧代际的插件实现。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文 — 点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变量：** companion 检查挂载后泄漏到全局的服务，以及模型请求前尚未绑定 preset 的 Agent。