@deepseek-ai/dsh-anonymous-user-id 0.0.1-rc.5

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/identity/anonymous-user-id/README.md
+README.md: fb9d8f8046f41aed7c0bc8aa8cede46f9bb8c93b
+README.zh.md: 738289fd6b132e3fd5b6cc5a89dbe8ca1ffb5e42

package/README.md

@@ -0,0 +1,30 @@
+# @deepseek-ai/dsh-anonymous-user-id
+
+English | [中文](README.zh.md)
+
+Shared anonymous identity for session telemetry, direct feedback acknowledgement, and DeepSeek provider requests. `getOrCreateAnonymousUserId()` returns a random UUID v4 scoped to one harness home, persisted as the bare line `$DSH_HOME/.anonymous-user-id` (`~/.dsh/.anonymous-user-id` when `DSH_HOME` is unset). The OpenTelemetry backend reports it as Resource `user.id`; `/feedback` includes the same value in its acknowledgement; and `dsh-llm-deepseek` sends it as `x-deepseek-harness-user-id`, allowing the receiving systems to correlate records without independently generated identities.
+
+The identity is never derived from the hostname, network address, git remote, or another identifying source. Deleting `.anonymous-user-id` resets the identity on the next process launch. Separate harness homes have separate identities.
+
+## Storage contract
+
+Reads and writes are synchronous because both boot-time telemetry construction and direct command execution need one API. The result is memoized per resolved file path for the process lifetime. A first writer uses exclusive creation and a concurrent loser adopts the persisted winner; a corrupt file is replaced. Persistence is best-effort, so an unwritable home still receives a process-local UUID rather than blocking telemetry or feedback.
+
+## Composition
+
+This package is a shared library, not a Cordis plugin. Consumers import `getOrCreateAnonymousUserId()` directly. Its invariant companion is intentionally empty because the package owns no event stream or public mutable relation that can be checked without creating the identity as a side effect. `DSH_TELEMETRY_DISABLED` stops telemetry export only; it does not suppress direct feedback acknowledgement or the DeepSeek provider header.
+
+## Model Experience
+
+None, as the identifier reaches DeepSeek only as model-hidden HTTP transport metadata and never enters the request body, prompt, or model-visible content.
+
+#### KV Cache effect
+
+None; the transport header changes neither tokens nor the model-visible prefix.
+
+## Known Limitations and Deferred Work
+
+- **No recovery after deletion** — loss mints a new anonymous identity by design; recovery would require stable derivation material that weakens anonymity.
+- **Best-effort concurrency** — a reader landing in the narrow interval between a concurrent process's exclusive create and completed write can use a different in-memory UUID for that run; later launches converge on the persisted value.
+- **No cross-home identity** — different `$DSH_HOME` values cannot be correlated.
+- **Configured DeepSeek gateways receive the id** — `dsh-llm-deepseek` sends the stable header to its resolved `baseURL`, including deployment overrides, independently of telemetry sharing mode.

package/README.zh.md

@@ -0,0 +1,30 @@
+# @deepseek-ai/dsh-anonymous-user-id
+
+[English](README.md) | 中文
+
+会话遥测、直接反馈确认与 DeepSeek 提供方请求共用的匿名身份。`getOrCreateAnonymousUserId()` 返回一个限定于单个 harness home 的随机 UUID v4，并以裸行形式持久化到 `$DSH_HOME/.anonymous-user-id`（未设置 `DSH_HOME` 时为 `~/.dsh/.anonymous-user-id`）。OpenTelemetry 后端将其作为 Resource 的 `user.id` 上报；`/feedback` 在确认文本中包含同一个值；`dsh-llm-deepseek` 则通过 `x-deepseek-harness-user-id` 发送该值，使接收系统无需独立生成身份即可关联记录。
+
+该身份绝不从 hostname、网络地址、git remote 或其他可用于识别身份的来源派生。删除 `.anonymous-user-id` 后，下次启动进程时会重置身份。不同 harness home 拥有不同身份。
+
+## 存储约定
+
+读写采用同步方式，因为启动时构造遥测和直接执行命令都需要使用同一个 API。结果在进程生命周期内按解析后的文件路径缓存。首个写入方采用独占创建；并发竞争中失败的一方会采用已持久化的胜出值。损坏的文件会被替换。持久化采用 best-effort，因此即使 home 不可写，系统仍会返回进程本地 UUID，而不会阻塞遥测或反馈。
+
+## 组合
+
+本包是共享库，并非 Cordis 插件。消费方直接导入 `getOrCreateAnonymousUserId()`。其不变式伴生插件刻意留空，因为本包既不拥有事件流，也不拥有任何可以在不触发创建身份这一副作用的情况下检查的公开可变关系。`DSH_TELEMETRY_DISABLED` 只会停止遥测导出，不会禁止直接反馈确认或 DeepSeek 提供方标头。
+
+## 模型体验
+
+无，因为该标识符只会作为模型不可见的 HTTP 传输元数据发送给 DeepSeek，绝不会进入请求正文、提示词或模型可见内容。
+
+#### KV Cache 影响
+
+无；该传输标头既不会改变 token，也不会改变模型可见前缀。
+
+## 已知限制与暂缓工作
+
+- **删除后无法恢复**：身份丢失后会按设计生成新的匿名身份；若要恢复身份，就需要稳定的派生材料，这会削弱匿名性。
+- **Best-effort 并发**：如果读取方恰好落在并发进程完成独占创建但尚未写完的狭窄时间窗内，本次运行可能使用不同的内存 UUID；后续启动会收敛到已持久化的值。
+- **没有跨 home 身份**：不同 `$DSH_HOME` 值之间无法关联。
+- **已配置的 DeepSeek gateway 会收到该 id**：`dsh-llm-deepseek` 会把稳定标头发送至解析后的 `baseURL`（包括部署覆盖），且不受遥测共享模式影响。

package/lib/index.js

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+//#region lib/types/index.js
+/**
+* Per-harness-home anonymous user id shared by telemetry and feedback.
+*
+* The id is a random UUID persisted as a bare line in `.anonymous-user-id` inside the
+* harness home resolved by {@link resolveDshHome} (`$DSH_HOME` > `~/.dsh`),
+* and never derived from the hostname, network address, git remote, or any
+* other identifying source. It is scoped to the harness home, not the
+* machine: every process sharing one `$DSH_HOME` reports the same id, and
+* deleting the file mints a fresh identity on the next launch.
+*
+* Reads and writes are synchronous so boot-time and command consumers can
+* use one API. The result is memoized per resolved file path: one process
+* touches the disk once, and a file deleted mid-run keeps the process's id
+* until the next launch.
+*
+* @module @deepseek-ai/dsh-anonymous-user-id
+*/
+/** File inside the harness home storing the id: a bare UUID line, no wrapper format. */
+const ANONYMOUS_USER_ID_FILE_NAME = ".anonymous-user-id";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Process-lifetime memo keyed by resolved file path, so distinct test homes never share an id. */
+const memo = /* @__PURE__ */ new Map();
+/** Read a valid persisted id from the file, or `undefined` when absent/corrupt. */
+function readPersistedId(file) {
+	let text;
+	try {
+		text = readFileSync(file, "utf8");
+	} catch {
+		return;
+	}
+	const value = text.trim();
+	return UUID_PATTERN.test(value) ? value : void 0;
+}
+/**
+* Return the harness home's anonymous user id, creating and persisting one on
+* first use. A concurrent first launch is settled by an exclusive-create
+* write: the loser rereads the winner's id. (A reread landing in the winner's
+* narrow create-to-write window can still yield two per-process ids for that
+* run; the next launch converges on the persisted one.) Persistence is
+* best-effort — a write failure (read-only home) still returns a usable id
+* for the current run so feedback and telemetry are never blocked.
+* @param options - home-location and UUID-generation seams.
+* @returns the stable per-harness-home anonymous user id.
+*/
+function getOrCreateAnonymousUserId(options = {}) {
+	const file = join(resolveDshHome(void 0, options.env ?? process.env), ANONYMOUS_USER_ID_FILE_NAME);
+	const cached = memo.get(file);
+	if (cached !== void 0) return cached;
+	let id = readPersistedId(file);
+	if (id === void 0) {
+		const created = (options.randomUUID ?? randomUUID)();
+		try {
+			mkdirSync(dirname(file), { recursive: true });
+			writeFileSync(file, `${created}\n`, {
+				encoding: "utf8",
+				flag: "wx"
+			});
+			id = created;
+		} catch {
+			id = readPersistedId(file);
+			if (id === void 0) {
+				try {
+					writeFileSync(file, `${created}\n`, "utf8");
+				} catch {}
+				id = created;
+			}
+		}
+	}
+	memo.set(file, id);
+	return id;
+}
+//#endregion
+export { ANONYMOUS_USER_ID_FILE_NAME, getOrCreateAnonymousUserId };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-anonymous-user-id`.
+* @module @deepseek-ai/dsh-anonymous-user-id/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-anonymous-user-id";
+/** Cordis companion plugin name. */
+const name = "anonymous-user-id-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the API owns one private memo and one best-effort
+* file, with no independent event stream or public mutable relation for a
+* companion to compare without creating the identity as a side effect.
+*/
+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,42 @@
+/**
+ * Per-harness-home anonymous user id shared by telemetry and feedback.
+ *
+ * The id is a random UUID persisted as a bare line in `.anonymous-user-id` inside the
+ * harness home resolved by {@link resolveDshHome} (`$DSH_HOME` > `~/.dsh`),
+ * and never derived from the hostname, network address, git remote, or any
+ * other identifying source. It is scoped to the harness home, not the
+ * machine: every process sharing one `$DSH_HOME` reports the same id, and
+ * deleting the file mints a fresh identity on the next launch.
+ *
+ * Reads and writes are synchronous so boot-time and command consumers can
+ * use one API. The result is memoized per resolved file path: one process
+ * touches the disk once, and a file deleted mid-run keeps the process's id
+ * until the next launch.
+ *
+ * @module @deepseek-ai/dsh-anonymous-user-id
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/** A harness-home-scoped anonymous user id (random UUID v4). */
+export type AnonymousUserId = Branded<'AnonymousUserId'>;
+/** File inside the harness home storing the id: a bare UUID line, no wrapper format. */
+export declare const ANONYMOUS_USER_ID_FILE_NAME = ".anonymous-user-id";
+/** Ambient hooks for locating and generating the id; every field has a default. */
+export interface AnonymousUserIdOptions {
+    /** Environment consulted for `DSH_HOME`; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** UUID generator; defaults to `crypto.randomUUID` (test hook). */
+    randomUUID?: () => string;
+}
+/**
+ * Return the harness home's anonymous user id, creating and persisting one on
+ * first use. A concurrent first launch is settled by an exclusive-create
+ * write: the loser rereads the winner's id. (A reread landing in the winner's
+ * narrow create-to-write window can still yield two per-process ids for that
+ * run; the next launch converges on the persisted one.) Persistence is
+ * best-effort — a write failure (read-only home) still returns a usable id
+ * for the current run so feedback and telemetry are never blocked.
+ * @param options - home-location and UUID-generation seams.
+ * @returns the stable per-harness-home anonymous user id.
+ */
+export declare function getOrCreateAnonymousUserId(options?: AnonymousUserIdOptions): AnonymousUserId;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-anonymous-user-id`.
+ * @module @deepseek-ai/dsh-anonymous-user-id/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "anonymous-user-id-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,46 @@
+{
+  "name": "@deepseek-ai/dsh-anonymous-user-id",
+  "description": "Shared anonymous user identity for DeepSeek Harness telemetry and feedback correlation",
+  "version": "0.0.1-rc.5",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/identity/anonymous-user-id"
+  },
+  "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.5",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-home-paths": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.5",
+    "@deepseek-ai/dsh-home-paths": "^0.0.1-rc.5",
+    "@deepseek-ai/cordis": "^4.0.1-rc.4"
+  }
+}