@deepseek-ai/dsh-persona 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/preset/persona/README.md
+README.md: 742141e65fa8d50b89e6b74e6d21aa8c5bfe98cd
+README.zh.md: add106adb5b81e45d8c6929a9a0f98b5c0072a01

package/README.md

@@ -0,0 +1,40 @@
+# dsh-persona
+
+English | [中文](README.zh.md)
+
+The agent persona as a composable row. It can either shadow the deployment persona or own the complete system prompt.
+
+[`dsh-system-prompt`](../../core/system-prompt/README.md) owns the deployment persona as its own config and registers that section unconditionally, so a process has exactly one. An [agent preset](../agent-presets/README.md) cannot mount the prompt registry itself — without a row of its own, a preset could change an agent's tools but never its identity. This package is that row.
+
+## Scope-only
+
+Mounting this row outside an agent scope collides with the registry's own `deployment:persona` registration and fails loud. That is not a limitation to work around: the deployment persona already has an owner, and the whole point of this row is to shadow it for one agent. Mount it inside a preset composition, where the preset mount supplies the agent scope.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `text` | required | Persona prose rendered as the `deployment:persona` section |
+| `complete` | `false` | Restore this persona after assembly as the only system-prompt section |
+
+`text` is a template, like any prompt section: complete `{{…}}` groups resolve strictly against registered prompt variables when the prompt renders, not when it assembles. Empty text still occupies the slot, so it shadows the deployment persona away entirely and then disappears at render. With `complete: true`, assembly still resolves contexts, tools, variables, and cooperative listeners, then the prompt registry restores this exact persona as the sole section; no identity, tool guidance, or listener can append prompt text.
+
+## Model Experience
+
+### The persona section
+
+#### What the model sees
+
+The `deployment:persona` section at order 0, immediately after the harness identity opener, carrying exactly this row's configured `text` with prompt variables resolved. For an agent whose preset mounts this row, it replaces whatever persona the deployment configured. In complete mode, the model sees only this rendered section as its system prompt.
+
+#### Token effect
+
+Fixed for a given preset: the persona's own tokens on every request that agent makes, and none for any other agent. Empty text contributes nothing. Complete mode removes every other system-prompt token for that agent.
+
+#### KV Cache effect
+
+Prefix-stable for the life of an agent — the row mounts once, before the agent is published and therefore before its first request, and its text never changes while the agent runs. Two agents on different presets establish different prefixes from this section onward; neither can invalidate the other's reuse.
+
+## Known Limitations and Deferred Work
+
+- **No global mount** — the prompt registry owns the unscoped persona slot, so this row is usable only from a scoped composition. A deployment-wide persona change belongs in the `system-prompt` row's own config.

package/README.zh.md

@@ -0,0 +1,40 @@
+# dsh-persona
+
+[English](README.md) | 中文
+
+把 agent（智能体）人设做成一个可组装的行：它既可以遮蔽部署级人设，也可以拥有完整系统提示词。
+
+[`dsh-system-prompt`](../../core/system-prompt/README.md) 以自身配置持有部署级人设，并且无条件注册该段落，因此一个进程只有一份。[agent preset](../agent-presets/README.md) 无法自行挂载提示词注册表——若没有属于自己的行，preset 能改变 agent 的工具，却永远改不了它的身份。本包就是那一行。
+
+## 仅限 scope 内使用
+
+在 agent scope 之外挂载本行，会与注册表自身的 `deployment:persona` 注册相撞并明确报错。这不是需要绕开的限制：部署级人设已经有归属，而本行存在的意义正是为某一个 agent 遮蔽它。请把它挂在 preset 组装内部，由 preset 的挂载过程提供 agent scope。
+
+## 配置
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `text` | 必填 | 作为 `deployment:persona` 段落渲染的人设文本 |
+| `complete` | `false` | 组装后将此人设恢复为唯一的系统提示词段落 |
+
+`text` 与任何提示词段落一样是模板：完整的 `{{…}}` 组在提示词**渲染**时（而非组装时）严格解析为已注册的提示词变量。空文本同样占据该槽位，因此会把部署级人设整个遮蔽掉，然后在渲染时消失。启用 `complete: true` 时，组装仍会解析上下文、工具、变量和协作式监听器，之后提示词注册表将这份确切人设恢复为唯一段落；身份、工具引导或监听器都无法追加提示词文本。
+
+## Model Experience
+
+### 人设段落
+
+#### What the model sees
+
+位于 order 0 的 `deployment:persona` 段落，紧随 harness 身份开场白之后，携带本行配置的 `text`，其中的提示词变量已解析。对于其 preset 挂载了本行的 agent，它会替换部署所配置的任何人设。在完整模式下，模型只会看到这个渲染后的段落作为系统提示词。
+
+#### Token effect
+
+对给定 preset 而言是固定的：该 agent 的每次请求都携带人设自身的 token，其他 agent 一个都不带。空文本不贡献任何 token。完整模式会移除该 agent 的其他所有系统提示词 token。
+
+#### KV Cache effect
+
+在一个 agent 的整个生命周期内保持前缀稳定——本行只挂载一次，发生在 agent 发布之前、因而也在它的首个请求之前，且在 agent 运行期间文本不再改变。两个使用不同 preset 的 agent 从该段落起建立各自不同的前缀，谁都无法让对方失去缓存复用。
+
+## Known Limitations and Deferred Work
+
+- **不支持全局挂载** —— 提示词注册表拥有未加 scope 的人设槽位，因此本行只能从带 scope 的组装中使用。要改变部署级人设，应在 `system-prompt` 行自身的配置中修改。

package/lib/index.js

@@ -0,0 +1,42 @@
+import z from "@deepseek-ai/schemastery";
+import { PERSONA_ORDER, PERSONA_SECTION } from "@deepseek-ai/dsh-system-prompt";
+//#region lib/types/index.js
+/**
+* A per-agent persona as a composable row.
+*
+* `dsh-system-prompt` owns the global persona as its own config, and registers
+* that section unconditionally — so this row is **scope-only**. Mounted inside
+* an agent preset it shadows the deployment persona for that one session,
+* exactly like the per-child persona `dsh-subagent` installs; mounted globally
+* it collides with the registry's own registration and fails loud.
+*
+* That constraint is the reason the row exists. An agent preset cannot mount
+* the prompt registry itself, so without a row of its own a preset could
+* change an agent's tools but never its identity.
+* @module @deepseek-ai/dsh-persona
+*/
+/** Cordis plugin name. */
+const name = "persona";
+/** The prompt registry this row contributes to. */
+const inject = ["systemPrompt"];
+/** Runtime schema for the persona row. */
+const Config = z.object({
+	text: z.string().required(),
+	complete: z.boolean().default(false)
+});
+/**
+* Register the persona section for the mounting context's scope.
+* @param ctx - an agent scope context; an unscoped context collides with the
+* prompt registry's own persona registration and rejects.
+* @param config - the persona text and complete-prompt policy.
+*/
+function apply(ctx, config) {
+	ctx.effect(() => ctx.systemPrompt.section({
+		name: PERSONA_SECTION,
+		order: PERSONA_ORDER,
+		text: config.text,
+		...config.complete ? { complete: true } : {}
+	}), "persona.section()");
+}
+//#endregion
+export { Config, PERSONA_ORDER, PERSONA_SECTION, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-persona`.
+* @module @deepseek-ai/dsh-persona/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-persona";
+/** Cordis companion plugin name. */
+const name = "persona-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this row owns no event stream or mutable runtime data — it registers one
+* prompt section and the prompt registry owns identity, complete-prompt enforcement, shadowing,
+* and disposal.
+*/
+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/types/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A per-agent persona as a composable row.
+ *
+ * `dsh-system-prompt` owns the global persona as its own config, and registers
+ * that section unconditionally — so this row is **scope-only**. Mounted inside
+ * an agent preset it shadows the deployment persona for that one session,
+ * exactly like the per-child persona `dsh-subagent` installs; mounted globally
+ * it collides with the registry's own registration and fails loud.
+ *
+ * That constraint is the reason the row exists. An agent preset cannot mount
+ * the prompt registry itself, so without a row of its own a preset could
+ * change an agent's tools but never its identity.
+ * @module @deepseek-ai/dsh-persona
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { PERSONA_ORDER, PERSONA_SECTION } from '@deepseek-ai/dsh-system-prompt';
+export { PERSONA_ORDER, PERSONA_SECTION };
+/** Cordis plugin name. */
+export declare const name = "persona";
+/** The prompt registry this row contributes to. */
+export declare const inject: string[];
+/** Plugin config: the persona text this composition contributes. */
+export interface Config {
+    /**
+     * Persona prose rendered as the `deployment:persona` section. A template:
+     * complete `{{…}}` groups interpolate strictly against registered prompt
+     * variables. Empty text drops the section at render, matching the registry.
+     */
+    text: string;
+    /** Make this persona the complete system prompt, suppressing every other section. */
+    complete?: boolean;
+}
+/** Runtime schema for the persona row. */
+export declare const Config: z<Config>;
+/**
+ * Register the persona section for the mounting context's scope.
+ * @param ctx - an agent scope context; an unscoped context collides with the
+ * prompt registry's own persona registration and rejects.
+ * @param config - the persona text and complete-prompt policy.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-persona`.
+ * @module @deepseek-ai/dsh-persona/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "persona-invariant";
+/** Service required before the companion can reserve package ownership. */
+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/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@deepseek-ai/dsh-persona",
+  "description": "Composition-authored deployment persona section for the DeepSeek Harness",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/preset/persona"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-scope": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1"
+  }
+}