dsh-session-path 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.1
+
+- Sidebar session rows: 「复制会话路径」 in the row's `⋯` / right-click menu
+  (`sidebar.workspaces.session.menu.item`, order 500), so any session's path can
+  be copied without opening it; a transient toast confirms the write.
+- Menu rows reuse the host's `MenuItemButton` when available and fall back to a
+  plain `role="menuitem"` button.
+- Self-test: added a client-bundle structure check; container checks now skip
+  gracefully on runtimes without Zstandard (CI-friendly), and the real-log pass
+  is skipped when the machine has no session logs.
+
+## 0.1.0
+
+- First release.
+- Session header action (⧉) copies a paste-ready handoff block: title, session
+  id, workspace directory and the absolute log path.
+- `session_path` tool: read-only path/info lookup for any session.
+- `session_handoff` tool: renders a session log into a readable Markdown
+  transcript (or plain JSONL) and returns its path, keeping the newest part
+  within the configured character budget.
+- Reads DSH's multi-frame Zstandard session logs frame by frame.
+- Read-only HTTP route `/api/dsh-session-path/resolve` behind a loopback /
+  trusted-host fence.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-session-path contributors
+
+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.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# dsh-session-path
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/dsh-session-path)](https://www.npmjs.com/package/dsh-session-path)
+[![ci](https://github.com/439436269-ctrl/dsh-session-path/actions/workflows/ci.yml/badge.svg)](https://github.com/439436269-ctrl/dsh-session-path/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/dsh-session-path)](./LICENSE)
+
+给 DSH 的**会话**加一条「路径」：复制当前会话的日志路径（或一段可直接粘贴的接续指令），
+让另一个会话能读到这段对话并接着往下干。
+
+```
+会话 header 里的 ⧉ 按钮  ──►  剪贴板里的接续块（标题 / 会话 ID / 工作目录 / 日志路径）
+                                        │
+另一个会话  ──►  session_handoff({ sessionId })  ──►  解压后的可读文件  ──►  read 它，继续
+```
+
+## 它解决什么问题
+
+DSH 每个会话的原始记录在 `$DSH_HOME/sessions/<工作区>/<会话目录>/session[.vN].jsonl[.zstd]`。
+这个文件有两个麻烦：
+
+1. 路径不好拿 —— GUI 里没有「复制会话路径」的入口；
+2. 拿到了也不好读 —— `.zstd` 是**多帧** Zstandard 容器（每次追加一个独立 frame），
+   `zcat` 之类只解第一帧，直接 `read` 会失败。
+
+这个插件把两件事都补上：一个按钮复制路径/接续块，一个工具把日志转成可读文件。
+
+## 装法
+
+从 npm 装进某个 profile：
+
+```sh
+dsh plugin --profile desktop add dsh-session-path
+```
+
+本地开发时也可以直接装插件目录（见下面的「开发循环」，注意 `link:` 装法对本插件不可用）：
+
+```sh
+dsh plugin --profile desktop add ./dsh-session-path
+```
+
+或者手工两步（可热载入、不必重启 DSH）：
+
+1. 在 profile 的 `package.json` 里加依赖
+   `"dsh-session-path": "file:<tgz 或目录>"`，然后在 profile 目录跑一次 `pnpm install`；
+2. 在 `~/.dsh/profiles/<profile>/cordis.patch.yml` 里加一行挂载：
+
+```yaml
+- insert:
+    - id: dsh-session-path
+      name: dsh-session-path
+```
+
+> 注意：`insert` 不去重。走用户补丁层就别再往 `dsh.profile.bundles` 里加同一个包，
+> 否则同一 id 插两行、槽位重复注册。
+
+## 用法
+
+### 1. GUI：会话 header 上的 ⧉ 按钮（当前会话）
+
+会话标题栏右侧多一个 ⧉ 按钮，点一下把下面这段放进剪贴板（复制成功变 ✓，失败变 ⚠）：
+
+```
+【接续会话】<标题>
+会话 ID：session-xxxxxxxx-…
+工作目录：/Users/you/project
+会话日志：/Users/you/.dsh/sessions/…/session.v4.jsonl.zstd
+
+提示：日志是 zstd 多帧压缩的 JSONL。在任意 DSH 会话里调用工具
+session_handoff({ sessionId: "session-xxxxxxxx-…" }) 可直接得到解压后的可读记录路径，再 read 它即可接续。
+```
+
+配置 `copyFormat: path` 时只复制裸路径一行。
+
+### 2. GUI：侧栏会话行右键菜单里的「复制会话路径」（任意会话）
+
+侧栏任何一条会话的 `⋯` 菜单 / 右键菜单里，最后一项是**「复制会话路径」**（在「归档会话」下面，
+带一条分隔线）——**不用先打开那个会话**。点击后菜单关闭，顶部弹一条「会话路径已复制」提示。
+
+注册用的是宿主自己的 `list` 槽位 `sidebar.workspaces.session.menu.item`（和「置顶/重命名/分叉/归档」
+同一套机制），`order: 500` 排在归档（400）之后，`separatorBefore` 让本项自成一组。
+
+### 3. 工具：`session_path`
+
+拿路径和会话信息，只读、不落盘。
+
+| 参数 | 说明 |
+|---|---|
+| `sessionId` | 目标会话；省略＝当前会话 |
+| `format` | `path`（裸路径）或 `block`（接续块，默认取插件配置） |
+
+### 4. 工具：`session_handoff`
+
+把会话渲染成**解压后的可读文件**，返回绝对路径 —— 这是「其他会话读取并接续」的正路。
+
+| 参数 | 说明 |
+|---|---|
+| `sessionId` | 目标会话；省略＝当前会话 |
+| `format` | `md`（默认，转录：用户/助手文本 + 工具调用一行摘要）或 `jsonl`（解压后的原始事件流） |
+| `maxChars` | 字符预算；**超出时保留最近的部分**（接续只需要最近上下文），默认取插件配置 |
+
+输出示例：
+
+```
+会话记录已写出：/Users/you/.dsh/session-handoff/session-xxxxxxxx-….md
+格式 md · 18432 字符 · 46 条（仅最近部分，前文已截断）
+工作目录：/Users/you/project
+原始日志：/Users/you/.dsh/sessions/…/session.v4.jsonl.zstd
+下一步：用 read 读取 … 即可接续该会话。
+```
+
+## 配置
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `enabled` | `true` | 关掉则不注册任何工具与路由 |
+| `copyFormat` | `block` | 按钮复制的内容：`block` 接续块 / `path` 裸路径 |
+| `handoffFormat` | `md` | `session_handoff` 的默认格式 |
+| `handoffDir` | `""` | 交接文件目录；空＝`$DSH_HOME/session-handoff` |
+| `maxHandoffChars` | `200000` | 单个交接文件的字符预算 |
+| `titleScanBytes` | `2097152` | 从日志里读标题时的压缩字节预算 |
+| `promptEnabled` | `true` | 是否往 system prompt 里加那段引导 |
+| `promptOrder` | `64` | 该段的排序 |
+
+注意：profile 的 `cordis.patch.yml` 对 `config` 是**整块替换**，只想改一个键也要把想保留的键写全。
+
+## 结构
+
+```
+lib/index.js         入口：装配 settings / systemPrompt / 路由 / 工具
+lib/config.js        schemastery Config + 代码侧默认值
+lib/paths.js         $DSH_HOME、sessions 根、会话目录与日志代际
+lib/zstd.js          多帧 Zstandard 边界扫描 + 逐帧读取
+lib/session-info.js  会话 id → 路径 / cwd / 标题
+lib/handoff.js       转录渲染与交接文件写出
+lib/copy-text.js     剪贴板载荷
+lib/route.js         /api/dsh-session-path/resolve（只读，带信任围栏）
+lib/trust.js         Host / Origin / sec-fetch-site 判定
+lib/tools.js         session_path、session_handoff
+lib/client.js        浏览器半：header ⧉ 按钮 + 侧栏会话行菜单项
+test/selftest.mjs    23 项自检（含真实多帧日志）
+```
+
+## 开发循环（本机实测的坑）
+
+插件的**服务端半边要 import 宿主包**（`@deepseek-ai/dsh-tools`、`@deepseek-ai/schemastery`），
+这决定了它不能用 `link:` 目录依赖 —— `link:` 之后包的真实路径在 profile 之外，
+Node 从真实路径往上找 `node_modules` 找不到宿主包，插件会 `ERR_MODULE_NOT_FOUND`：
+
+```
+$ node -e "import('@deepseek-ai/dsh-tools')"   # 在插件目录里
+dsh-tools FAIL ERR_MODULE_NOT_FOUND
+```
+
+本机其它 `link:` 插件（dsh-piano / dsh-scroll-piano）之所以没事，是因为它们服务端**不 import 任何宿主包**。
+
+所以改代码后要**打包 + 重装**：
+
+```sh
+NODE=~/.dsh/dsh-runtimes/dsh-primary-runtime/dependencies/node/bin/node
+PNPM="/Applications/DeepSeek Harness.app/Contents/Resources/runtime/pnpm/bin/pnpm.mjs"
+cd <本目录> && "$NODE" "$PNPM" pack --pack-destination dist
+cd ~/.dsh/profiles/desktop && "$NODE" "$PNPM" install
+# 再 touch 一下 cordis.patch.yml 触发热载入；客户端半需要刷新页面
+```
+
+> pnpm 对**同路径同版本**的 `file:` 包会跳过重装：改了版本号或 `remove` + `add` 才能确保装进去的是新代码。
+
+## 边界
+
+- 只读：`session_path` 与 HTTP 路由都不写盘；只有 `session_handoff` 写文件，且只写进
+  `handoffDir`（默认 `$DSH_HOME/session-handoff`）。
+- 不解压全文到内存：按 frame 扫描，一次只持有单帧 + 尾部残帧。
+- 路由带信任围栏（仅 loopback / 显式 trusted host，拒绝 cross-site 与跨源 Origin）。
+- 交接文件按字符预算**保留最近部分**：接续场景里尾部上下文才有用。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,15 @@
+# dsh-session-path bundle patch: one host row. `name` MUST equal the package name
+# (the client half resolves `require.resolve('<row-name>/package.json')` to find
+# this package and then its `exports["./client"]` bundle). The row `id` is a
+# purely local identifier and is also the settings-page namespace.
+- insert:
+    - id: dsh-session-path
+      name: dsh-session-path
+      config:
+        enabled: true
+        # "block" copies a paste-ready handoff block (title / id / cwd / log
+        # path); "path" copies the bare log-file path only.
+        copyFormat: block
+        # Format of the file `session_handoff` writes: "md" (readable
+        # transcript) or "jsonl" (plain, decompressed event log).
+        handoffFormat: md

package/lib/client.js

@@ -0,0 +1,324 @@
+/**
+ * dsh-session-path — browser half.
+ *
+ * Two places to copy a session's path:
+ *
+ *  1. the session header's action row (the currently open session), and
+ *  2. the sidebar session row's "..." menu, next to 置顶 / 重命名 / 分叉 / 归档
+ *     — `sidebar.workspaces.session.menu.item`, a `list` slot the host's own
+ *     actions use too, so any session can be copied without opening it.
+ *
+ * Both paths ask the host half for the payload (one source of truth for the
+ * path, the workspace and the copy format) and only own the clipboard write and
+ * its transient feedback.
+ */
+window.__ModuleLoader__.load({
+	id: "dsh-session-path",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		const React = require("react");
+		const h = React.createElement;
+		const { useCallback, useEffect, useRef, useState } = React;
+		// The Module Loader exposes the UI primitives as a baseline external (see
+		// the host's client-plugin docs); a missing copy must not break the slot,
+		// so the menu item falls back to a plain role="menuitem" button.
+		let primitives = null;
+		try {
+			primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+		} catch (error) {
+			console.warn("[dsh-session-path] ui-primitives unavailable, using a plain menu button:", error);
+		}
+		const MenuItemButton = primitives?.MenuItemButton ?? null;
+
+		/** Exact route the host half registers. */
+		const ROUTE = "/api/dsh-session-path/resolve";
+		/** The session header action row. */
+		const SLOT = "conversation.session.header.actions";
+		/** The sidebar session row's "..." menu. */
+		const MENU_SLOT = "sidebar.workspaces.session.menu.item";
+		/** How long the "copied" / "failed" feedback stays. */
+		const FEEDBACK_MS = 1800;
+
+		//#region styles
+		const CSS = [
+			".dshsp_btn{box-sizing:border-box;width:24px;height:24px;flex:none;display:inline-flex;align-items:center;justify-content:center;padding:0;border:none;border-radius:var(--dsw-radius-sm,4px);background:transparent;color:var(--dsw-alias-label-secondary,#8a8f98);cursor:pointer;transition:background .15s ease,color .15s ease}",
+			".dshsp_btn:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(127,127,127,.14));color:var(--dsw-alias-label-primary,#e6e8ee)}",
+			".dshsp_btn:focus-visible{outline:var(--dsw-focus-ring-width,2px) solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary,#5b8def));outline-offset:1px}",
+			".dshsp_btn[data-phase=busy]{opacity:.55;cursor:progress}",
+			".dshsp_btn[data-phase=copied]{color:var(--dsw-alias-state-success-primary,#34a853)}",
+			".dshsp_btn[data-phase=failed]{color:var(--dsw-alias-state-warning-primary,#e0a03a)}",
+			".dshsp_menuItem{box-sizing:border-box;width:100%;display:flex;align-items:center;gap:8px;padding:6px 10px;border:none;background:transparent;color:var(--dsw-alias-label-primary,#e6e8ee);font:inherit;font-size:13px;line-height:20px;text-align:left;cursor:pointer;border-radius:var(--dsw-radius-sm,4px)}",
+			".dshsp_menuItem:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(127,127,127,.14))}",
+			".dshsp_toast{position:fixed;top:14px;left:50%;transform:translateX(-50%);z-index:2147483000;padding:8px 14px;border-radius:8px;background:var(--dsw-alias-bg-elevated,#1f2430);color:var(--dsw-alias-label-primary,#e6e8ee);box-shadow:0 6px 22px rgba(0,0,0,.35);font-size:13px;line-height:18px;pointer-events:none}",
+			".dshsp_toast[data-ok=false]{color:var(--dsw-alias-state-warning-primary,#e0a03a)}",
+		].join("");
+		const tagId = "dsh-session-path/header-action.css";
+		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
+			const tag = document.createElement("style");
+			tag.dataset.plugin = "dsh-session-path";
+			tag.dataset.pluginCss = tagId;
+			tag.textContent = CSS;
+			document.head.appendChild(tag);
+		}
+		//#endregion
+
+		//#region copy
+		/** Put `text` on the clipboard, falling back to the legacy selection path. */
+		async function writeClipboard(text) {
+			try {
+				if (navigator.clipboard !== undefined && typeof navigator.clipboard.writeText === "function") {
+					await navigator.clipboard.writeText(text);
+					return true;
+				}
+			} catch {
+				/* fall through to the legacy path */
+			}
+			const area = document.createElement("textarea");
+			area.value = text;
+			area.setAttribute("readonly", "");
+			area.style.cssText = "position:fixed;top:-1000px;left:-1000px;opacity:0";
+			document.body.appendChild(area);
+			try {
+				area.select();
+				return document.execCommand("copy") === true;
+			} catch {
+				return false;
+			} finally {
+				area.remove();
+			}
+		}
+
+		/**
+		 * Ask the host half for one session's payload and copy it.
+		 * @param sessionId - the session to copy.
+		 * @returns the copied text.
+		 */
+		async function copyFor(sessionId) {
+			const params = new URLSearchParams({ sessionId });
+			const response = await fetch(ROUTE + "?" + params.toString(), { headers: { accept: "application/json" } });
+			const body = await response.json().catch(() => null);
+			if (!response.ok || body === null || body.ok !== true) {
+				throw new Error(body?.error?.message ?? "HTTP " + response.status);
+			}
+			const text = typeof body.value?.text === "string" && body.value.text !== "" ? body.value.text : body.value?.logPath ?? "";
+			if (!(await writeClipboard(text))) throw new Error("clipboard write was refused");
+			return text;
+		}
+
+		/** A short-lived, click-through confirmation banner. */
+		function toast(text, ok) {
+			try {
+				const node = document.createElement("div");
+				node.className = "dshsp_toast";
+				node.dataset.ok = ok ? "true" : "false";
+				node.setAttribute("role", "status");
+				node.textContent = text;
+				document.body.appendChild(node);
+				window.setTimeout(() => node.remove(), FEEDBACK_MS);
+			} catch {
+				/* feedback is best-effort */
+			}
+		}
+		//#endregion
+
+		//#region icons
+		/** Lucide-style outline copy glyph, currentColor, 16px. */
+		function CopyIcon() {
+			return h(
+				"svg",
+				{ width: 16, height: 16, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.7, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true" },
+				h("rect", { x: 9, y: 9, width: 12, height: 12, rx: 2 }),
+				h("path", { d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" }),
+			);
+		}
+
+		/** Check glyph for the copied state. */
+		function CheckIcon() {
+			return h(
+				"svg",
+				{ width: 16, height: 16, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true" },
+				h("path", { d: "M20 6 9 17l-5-5" }),
+			);
+		}
+
+		/** Warning glyph for the failed state. */
+		function WarnIcon() {
+			return h(
+				"svg",
+				{ width: 16, height: 16, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.7, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true" },
+				h("path", { d: "M12 9v4" }),
+				h("path", { d: "M12 17h.01" }),
+				h("path", { d: "M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0Z" }),
+			);
+		}
+		//#endregion
+
+		//#region labels
+		/** Bilingual labels, picked from the document language. */
+		function labels() {
+			const lang = (typeof document !== "undefined" ? document.documentElement.lang : "") || (typeof navigator !== "undefined" ? navigator.language : "") || "";
+			if (/^zh/i.test(lang)) {
+				return {
+					idle: "复制会话路径（供其他会话读取并接续）",
+					busy: "正在解析会话路径…",
+					copied: "已复制会话路径",
+					failed: "复制失败：点开控制台看 [dsh-session-path]",
+					menu: "复制会话路径",
+					copiedToast: "会话路径已复制",
+					failedToast: "复制失败，控制台里搜 [dsh-session-path]",
+				};
+			}
+			return {
+				idle: "Copy session path (for another session to read and continue)",
+				busy: "Resolving the session path…",
+				copied: "Session path copied",
+				failed: "Copy failed — see [dsh-session-path] in the console",
+				menu: "Copy session path",
+				copiedToast: "Session path copied",
+				failedToast: "Copy failed — search [dsh-session-path] in the console",
+			};
+		}
+		//#endregion
+
+		//#region header button
+		/**
+		 * The header button for the open session.
+		 * @param props - slot props; `sessionId` identifies the open session.
+		 */
+		function CopySessionPathButton(props) {
+			const sessionId = typeof props.sessionId === "string" ? props.sessionId : "";
+			const [phase, setPhase] = useState("idle");
+			const timer = useRef(null);
+			const t = labels();
+
+			useEffect(
+				() => () => {
+					if (timer.current !== null) window.clearTimeout(timer.current);
+				},
+				[],
+			);
+
+			const flash = useCallback((next) => {
+				if (timer.current !== null) window.clearTimeout(timer.current);
+				setPhase(next);
+				timer.current = window.setTimeout(() => {
+					timer.current = null;
+					setPhase("idle");
+				}, FEEDBACK_MS);
+			}, []);
+
+			const copy = useCallback(async () => {
+				if (sessionId === "" || phase === "busy") return;
+				setPhase("busy");
+				try {
+					await copyFor(sessionId);
+					flash("copied");
+				} catch (error) {
+					console.warn("[dsh-session-path] copy failed:", error);
+					flash("failed");
+				}
+			}, [sessionId, phase, flash]);
+
+			if (sessionId === "") return null;
+			const title = phase === "copied" ? t.copied : phase === "failed" ? t.failed : phase === "busy" ? t.busy : t.idle;
+			return h(
+				"button",
+				{
+					type: "button",
+					className: "dshsp_btn",
+					"data-phase": phase,
+					"data-dsh-session-path": sessionId,
+					title,
+					"aria-label": title,
+					"aria-live": "polite",
+					disabled: phase === "busy",
+					onClick: copy,
+				},
+				phase === "copied" ? h(CheckIcon) : phase === "failed" ? h(WarnIcon) : h(CopyIcon),
+			);
+		}
+		//#endregion
+
+		//#region sidebar row menu
+		/**
+		 * One row of a sidebar session's "..." menu.
+		 * @param props - slot props; `sessionId` / `displayTitle` describe the row,
+		 *   `useMenuOpenState` is the slot-level hook that dismisses the menu.
+		 */
+		function CopyPathMenuItem(props) {
+			const sessionId = typeof props.sessionId === "string" ? props.sessionId : "";
+			const t = labels();
+			const onSelect = useCallback(() => {
+				try {
+					// Dismiss first: a menu left open while the fetch settles would
+					// swallow the toast behind it.
+					if (typeof props.useMenuOpenState === "function") props.useMenuOpenState()[1](false);
+				} catch {
+					/* a missing hook must not block the copy */
+				}
+				if (sessionId === "") return;
+				void copyFor(sessionId)
+					.then(() => toast(t.copiedToast, true))
+					.catch((error) => {
+						console.warn("[dsh-session-path] copy failed:", error);
+						toast(t.failedToast, false);
+					});
+			}, [props.useMenuOpenState, sessionId, t]);
+
+			if (sessionId === "") return null;
+			if (MenuItemButton !== null) {
+				return h(MenuItemButton, { separatorBefore: true, onSelect, "data-dsh-session-path-menu": sessionId }, t.menu);
+			}
+			return h(
+				"button",
+				{ type: "button", role: "menuitem", className: "dshsp_menuItem", "data-dsh-session-path-menu": sessionId, onClick: onSelect },
+				t.menu,
+			);
+		}
+		//#endregion
+
+		//#region apply
+		const inject = ["slots"];
+
+		/**
+		 * Register both surfaces.
+		 * @param ctx - client root context.
+		 */
+		function apply(ctx) {
+			ctx.slots.inject(SLOT, () =>
+				ctx.slots.register(
+					{
+						name: SLOT,
+						id: "dsh-session-path:copy",
+						order: 20,
+						inject: () => ({}),
+					},
+					CopySessionPathButton,
+				),
+			);
+			// Order 500 lands after the shipped Archive (400); `separatorBefore` on
+			// the item opens our own group.
+			ctx.slots.inject(MENU_SLOT, () =>
+				ctx.slots.register(
+					{
+						name: MENU_SLOT,
+						id: "dsh-session-path:copy-session",
+						order: 500,
+						inject: () => ({}),
+					},
+					CopyPathMenuItem,
+				),
+			);
+		}
+		//#endregion
+
+		exports.apply = apply;
+		exports.inject = inject;
+		/** Test seam: the pure pieces `test/selftest.mjs` can exercise. */
+		exports.__test__ = { ROUTE, SLOT, MENU_SLOT, labels, writeClipboard };
+
+		return module.exports;
+	},
+});

package/lib/config.js

@@ -0,0 +1,88 @@
+/**
+ * Plugin configuration: the schema the host validates against, the code-side
+ * defaults (so a direct `apply()` call works without the loader), and the
+ * normalisation of every string/enum knob.
+ *
+ * The Cordis loader applies `Config` defaults, but `apply` is also reachable
+ * through direct construction (tests, tooling), so this module resolves its own
+ * defaults instead of trusting the caller.
+ *
+ * @module dsh-session-path/config
+ */
+
+import z from "@deepseek-ai/schemastery";
+
+/** Code-side defaults, mirrored by the `Config` schema below. */
+export const DEFAULTS = Object.freeze({
+	enabled: true,
+	copyFormat: "block",
+	handoffFormat: "md",
+	handoffDir: "",
+	maxHandoffChars: 200_000,
+	titleScanBytes: 2_097_152,
+	promptEnabled: true,
+	promptOrder: 64,
+});
+
+export const Config = z.object({
+	/** Master switch; `false` registers no tools and no HTTP route. */
+	enabled: z.boolean().default(DEFAULTS.enabled),
+	/** Clipboard payload shape for the header button: `block` or `path`. */
+	copyFormat: z.string().default(DEFAULTS.copyFormat),
+	/** `session_handoff` output format: `md` (transcript) or `jsonl` (events). */
+	handoffFormat: z.string().default(DEFAULTS.handoffFormat),
+	/** Directory for handoff files; empty means `$DSH_HOME/session-handoff`. */
+	handoffDir: z.string().default(DEFAULTS.handoffDir),
+	/** Character budget for one handoff file (the tail of the session wins). */
+	maxHandoffChars: z.natural().default(DEFAULTS.maxHandoffChars),
+	/** Compressed bytes scanned when the log title must be read from disk. */
+	titleScanBytes: z.natural().default(DEFAULTS.titleScanBytes),
+	/** Whether to contribute the guide section to the system prompt. */
+	promptEnabled: z.boolean().default(DEFAULTS.promptEnabled),
+	/** Ordering of that system-prompt section. */
+	promptOrder: z.natural().default(DEFAULTS.promptOrder),
+});
+
+/**
+ * One of `allowed`, or `fallback` when the value is absent/unknown.
+ *
+ * @param value - raw configured value.
+ * @param allowed - accepted strings.
+ * @param fallback - value used otherwise.
+ * @returns the resolved string.
+ */
+function pick(value, allowed, fallback) {
+	return typeof value === "string" && allowed.includes(value) ? value : fallback;
+}
+
+/**
+ * A positive integer, or `fallback`.
+ *
+ * @param value - raw configured value.
+ * @param fallback - value used otherwise.
+ * @returns the resolved integer.
+ */
+function positiveInteger(value, fallback) {
+	const number = Number(value);
+	return Number.isSafeInteger(number) && number > 0 ? number : fallback;
+}
+
+/**
+ * Resolve user configuration into the plain settings object the plugin uses.
+ *
+ * @param raw - the loader-supplied config (possibly undefined).
+ * @returns resolved settings.
+ */
+export function resolveConfig(raw) {
+	const config = raw === null || typeof raw !== "object" ? {} : raw;
+	return {
+		enabled: config.enabled !== false,
+		copyFormat: pick(config.copyFormat, ["block", "path"], DEFAULTS.copyFormat),
+		handoffFormat: pick(config.handoffFormat, ["md", "jsonl"], DEFAULTS.handoffFormat),
+		handoffDir: typeof config.handoffDir === "string" ? config.handoffDir.trim() : "",
+		maxHandoffChars: positiveInteger(config.maxHandoffChars, DEFAULTS.maxHandoffChars),
+		titleScanBytes: positiveInteger(config.titleScanBytes, DEFAULTS.titleScanBytes),
+		promptEnabled: config.promptEnabled !== false,
+		promptOrder: Number.isSafeInteger(Number(config.promptOrder)) ? Number(config.promptOrder) : DEFAULTS.promptOrder,
+	};
+}

package/lib/copy-text.js

@@ -0,0 +1,28 @@
+/**
+ * Compose the clipboard payload for one session.
+ *
+ * `path` is the bare log-file path; `block` is a paste-ready handoff a user can
+ * drop into any other session, and it names the tool that turns the compressed
+ * log into something the other agent can simply read.
+ *
+ * @module dsh-session-path/copy-text
+ */
+
+/**
+ * Build the copied text for one resolved session.
+ *
+ * @param info - result of `resolveSessionInfo`.
+ * @param format - `path` or `block`.
+ * @returns the clipboard string.
+ */
+export function composeCopyText(info, format) {
+	if (format === "path") return info.logPath;
+	const lines = [];
+	lines.push(`【接续会话】${info.title === "" ? "(无标题)" : info.title}`);
+	lines.push(`会话 ID：${info.sessionId}`);
+	if (info.cwd !== "") lines.push(`工作目录：${info.cwd}`);
+	lines.push(`会话日志：${info.logPath === "" ? "(未找到日志文件)" : info.logPath}`);
+	lines.push("");
+	lines.push(`提示：日志是 zstd 多帧压缩的 JSONL。在任意 DSH 会话里调用工具 session_handoff({ sessionId: "${info.sessionId}" }) 可直接得到解压后的可读记录路径，再 read 它即可接续。`);
+	return lines.join("\n");
+}