dsh-session-path 0.0.0-stage → 0.1.2

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");
+}

package/lib/handoff.js

@@ -0,0 +1,219 @@
+/**
+ * Turn a session log into a readable handoff file.
+ *
+ * The raw log is a compressed event stream: another agent can find it but cannot
+ * `read` it. This module renders the parts a continuation actually needs —
+ * user messages, assistant text, and the tool calls between them — and writes
+ * either a Markdown transcript or the decompressed JSONL, keeping the **tail**
+ * of the session when the character budget bites (the most recent turns are what
+ * a continuation must see).
+ *
+ * @module dsh-session-path/handoff
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { readSessionRecords } from "./zstd.js";
+import { dshHome } from "./paths.js";
+
+/** Longest tool-call rendering kept per call. */
+const TOOL_ARG_CHARS = 240;
+/** Longest single message kept verbatim. */
+const MESSAGE_CHARS = 20_000;
+
+/**
+ * Join the text blocks of one message.
+ *
+ * @param content - message content array.
+ * @returns the concatenated text.
+ */
+function messageText(content) {
+	if (!Array.isArray(content)) return "";
+	const parts = [];
+	for (const block of content) {
+		if (block === null || typeof block !== "object") continue;
+		if (block.type !== "text" || typeof block.text !== "string") continue;
+		parts.push(block.text);
+	}
+	return parts.join("\n").trim();
+}
+
+/**
+ * One short line for a tool call, so the transcript records what was run.
+ *
+ * @param record - a `tool/call` record.
+ * @returns the rendered line.
+ */
+function toolLine(record) {
+	const name = typeof record.data?.name === "string" ? record.data.name : "tool";
+	const raw = typeof record.data?.arguments === "string" ? record.data.arguments : "";
+	const args = raw.length > TOOL_ARG_CHARS ? `${raw.slice(0, TOOL_ARG_CHARS)}…` : raw;
+	return `- \`${name}\` ${args}`.trimEnd();
+}
+
+/**
+ * Render one record as a transcript entry, or null when it is not user-visible.
+ *
+ * @param record - a parsed log record.
+ * @returns `{ role, text }` or null.
+ */
+function toEntry(record) {
+	switch (record.type) {
+		case "user/message": {
+			const text = messageText(record.data?.content);
+			const kind = record.data?.source?.kind;
+			if (text === "") return null;
+			// Plugin injections are host bookkeeping, not something the user said.
+			if (typeof kind === "string" && kind !== "user") return { role: "context", text };
+			return { role: "user", text };
+		}
+		case "assistant/message": {
+			const text = messageText(record.data?.message?.content);
+			return text === "" ? null : { role: "assistant", text };
+		}
+		case "tool/call":
+			return { role: "tool", text: toolLine(record) };
+		default:
+			return null;
+	}
+}
+
+/** Markdown heading per entry role. */
+const HEADING = { user: "## 用户", assistant: "## 助手", tool: "## 工具调用", context: "## 上下文注入" };
+
+/**
+ * Render the transcript, keeping the most recent entries within `maxChars`.
+ *
+ * @param entries - transcript entries in log order.
+ * @param maxChars - character budget for the entry bodies.
+ * @returns `{ body, kept, truncated }`.
+ */
+export function renderEntries(entries, maxChars) {
+	const kept = [];
+	let used = 0;
+	let truncated = false;
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const entry = entries[index];
+		const text = entry.text.length > MESSAGE_CHARS ? `${entry.text.slice(0, MESSAGE_CHARS)}\n…（本条已截断）` : entry.text;
+		const size = text.length + HEADING[entry.role].length + 4;
+		if (kept.length > 0 && used + size > maxChars) {
+			truncated = true;
+			break;
+		}
+		kept.push({ ...entry, text });
+		used += size;
+	}
+	kept.reverse();
+	const body = kept.map((entry) => `${HEADING[entry.role]}\n\n${entry.text}`).join("\n\n");
+	return { body, kept: kept.length, truncated };
+}
+
+/**
+ * Markdown handoff: a header block plus the tail of the transcript.
+ *
+ * @param info - resolved session info.
+ * @param entries - transcript entries.
+ * @param maxChars - character budget.
+ * @returns `{ text, kept, truncated }`.
+ */
+export function renderMarkdown(info, entries, maxChars) {
+	const { body, kept, truncated } = renderEntries(entries, maxChars);
+	const header = [
+		"# 会话接续记录",
+		"",
+		`- 会话 ID：${info.sessionId}`,
+		`- 标题：${info.title === "" ? "(无标题)" : info.title}`,
+		`- 工作目录：${info.cwd === "" ? "(未知)" : info.cwd}`,
+		`- 会话日志：${info.logPath === "" ? "(未找到)" : info.logPath}`,
+		`- 导出时间：${new Date().toISOString()}`,
+		`- 导出条目：${kept}${truncated ? "（仅保留最近部分，前文已截断）" : ""}`,
+		"",
+		"---",
+		"",
+	];
+	return { text: `${header.join("\n")}${body}\n`, kept, truncated };
+}
+
+/**
+ * JSONL handoff: one header line plus the decompressed records.
+ *
+ * @param info - resolved session info.
+ * @param records - parsed records in log order.
+ * @param maxChars - character budget.
+ * @returns `{ text, kept, truncated }`.
+ */
+export function renderJsonl(info, records, maxChars) {
+	const header = {
+		type: "session/handoff",
+		sessionId: info.sessionId,
+		title: info.title,
+		cwd: info.cwd,
+		logPath: info.logPath,
+		exportedAt: new Date().toISOString(),
+	};
+	const lines = [JSON.stringify(header)];
+	let used = lines[0].length;
+	let kept = 0;
+	for (const record of records) {
+		const line = JSON.stringify(record);
+		if (used + line.length > maxChars) break;
+		lines.push(line);
+		used += line.length + 1;
+		kept += 1;
+	}
+	return { text: `${lines.join("\n")}\n`, kept, truncated: kept < records.length };
+}
+
+/**
+ * Where handoff files live: the configured directory, else `$DSH_HOME/session-handoff`.
+ *
+ * @param ctx - host plugin context.
+ * @param settings - resolved plugin settings.
+ * @returns the absolute directory.
+ */
+export function handoffDirectory(ctx, settings) {
+	return settings.handoffDir !== "" ? settings.handoffDir : join(dshHome(ctx), "session-handoff");
+}
+
+/**
+ * Build one handoff file for a session and return where it landed.
+ *
+ * @param ctx - host plugin context.
+ * @param settings - resolved plugin settings.
+ * @param info - resolved session info.
+ * @param options - `{ format?, maxChars? }`.
+ * @returns `{ file, chars, kept, truncated, format }`.
+ */
+export async function writeHandoff(ctx, settings, info, options = {}) {
+	const format = options.format === "jsonl" ? "jsonl" : settings.handoffFormat;
+	const maxChars = Number(options.maxChars) > 0 ? Math.floor(Number(options.maxChars)) : settings.maxHandoffChars;
+	if (info.logPath === "") throw new Error(`no committed log found for session "${info.sessionId}"`);
+	const directory = handoffDirectory(ctx, settings);
+	await mkdir(directory, { recursive: true });
+	let text;
+	let kept;
+	let truncated;
+	if (format === "jsonl") {
+		const records = [];
+		for await (const record of readSessionRecords(info.logPath)) records.push(record);
+		const rendered = renderJsonl(info, records, maxChars);
+		text = rendered.text;
+		kept = rendered.kept;
+		truncated = rendered.truncated;
+	} else {
+		const entries = [];
+		for await (const record of readSessionRecords(info.logPath)) {
+			const entry = toEntry(record);
+			if (entry !== null) entries.push(entry);
+		}
+		const rendered = renderMarkdown(info, entries, maxChars);
+		text = rendered.text;
+		kept = rendered.kept;
+		truncated = rendered.truncated;
+	}
+	const safeId = info.sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+	const file = join(directory, `${safeId}.${format === "jsonl" ? "jsonl" : "md"}`);
+	await writeFile(file, text, "utf8");
+	return { file, chars: text.length, kept, truncated, format };
+}

package/lib/index.js

@@ -0,0 +1,63 @@
+/**
+ * dsh-session-path — host half.
+ *
+ * Answers one question: *where does this DSH session live on disk, and how can
+ * another session read it?* Two tools (`session_path`, `session_handoff`), one
+ * read-only HTTP route for the header button, and a short system-prompt guide.
+ *
+ * The module only wires things together: configuration lives in `./config.js`,
+ * path discovery in `./paths.js`, log decoding in `./zstd.js`, rendering in
+ * `./handoff.js`, tool contracts in `./tools.js`, the route in `./route.js`.
+ *
+ * @module dsh-session-path
+ */
+
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+import { Config, resolveConfig } from "./config.js";
+import { guideText } from "./prompt.js";
+import { registerResolveRoute } from "./route.js";
+import { createToolSpecs } from "./tools.js";
+
+export const name = "session-path";
+
+export const inject = ["tools", "systemPrompt", "webServer"];
+
+export { Config };
+
+/**
+ * Mount the plugin.
+ *
+ * @param ctx - host plugin context.
+ * @param config - loader config (defaults are re-resolved here).
+ */
+export function apply(ctx, config) {
+	const settings = resolveConfig(config);
+	if (!settings.enabled) return;
+
+	if (settings.promptEnabled) {
+		ctx.systemPrompt.section({
+			name: "session-path:guide",
+			order: settings.promptOrder,
+			text: () => guideText(settings),
+		});
+	}
+
+	ctx.effect(() => registerResolveRoute(ctx, settings), "dsh-session-path: resolve route");
+
+	for (const spec of createToolSpecs({ ctx, settings })) {
+		ctx.tools.register(
+			defineTool({
+				name: spec.name,
+				description: spec.description,
+				parameters: spec.parameters,
+				output: {
+					schema: spec.outputSchema,
+					render: spec.render,
+				},
+				...(spec.presentCall ? { presentCall: spec.presentCall } : {}),
+				execute: spec.execute,
+			}),
+		);
+	}
+}

package/lib/paths.js

@@ -0,0 +1,154 @@
+/**
+ * Locate a session's on-disk home.
+ *
+ * DSH stores one directory per session under `$DSH_HOME/sessions/<project>/`,
+ * where `<project>` is derived from the workspace cwd and the session directory
+ * is either the bare session id or `session-<id>` (the naming changed across
+ * releases). Each session directory holds one committed log per generation:
+ * `session[.vN].jsonl[.zstd]`.
+ *
+ * Both the derived-project fast path and a full scan are provided: the scan is
+ * authoritative and never edits anything, it only enumerates directories.
+ *
+ * @module dsh-session-path/paths
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Canonical committed artifacts only: backups, temp files and aliases are not logs. */
+const LOG_FILE = /^session(?:\.v([1-9]\d*))?\.jsonl(\.zstd)?$/;
+
+/**
+ * `$DSH_HOME`, resolved from the host service, the environment, then `~/.dsh`.
+ *
+ * @param ctx - host plugin context (may be a bare object in tests).
+ * @returns the absolute DSH home path.
+ */
+export function dshHome(ctx) {
+	const service = ctx?.get?.("dshHomePath");
+	if (typeof service === "function") {
+		try {
+			const resolved = service();
+			if (typeof resolved === "string" && resolved.length > 0) return resolved;
+		} catch {
+			/* fall through to the environment */
+		}
+	}
+	const fromEnv = process.env.DSH_HOME;
+	if (typeof fromEnv === "string" && fromEnv.length > 0) return fromEnv;
+	return join(homedir(), ".dsh");
+}
+
+/**
+ * The sessions root: `$DSH_HOME/sessions`.
+ *
+ * @param ctx - host plugin context.
+ * @returns the absolute sessions root.
+ */
+export function sessionsRoot(ctx) {
+	return join(dshHome(ctx), "sessions");
+}
+
+/**
+ * Parse a log file name into its generation, or null when it is not a log.
+ *
+ * @param name - base name of the candidate file.
+ * @returns `{ version, compressed }` or null.
+ */
+export function logGeneration(name) {
+	const match = LOG_FILE.exec(name);
+	if (match === null) return null;
+	const version = Number(match[1] ?? 0);
+	return Number.isSafeInteger(version) ? { version, compressed: Boolean(match[2]) } : null;
+}
+
+/**
+ * Committed logs of one session directory, newest generation first.
+ *
+ * Numeric generations order numerically (`v10` beats `v3`), and a compressed
+ * artifact wins over a plain one of the same generation.
+ *
+ * @param directory - session directory.
+ * @returns absolute log paths, best candidate first.
+ */
+export function listSessionLogs(directory) {
+	let names;
+	try {
+		names = readdirSync(directory);
+	} catch {
+		return [];
+	}
+	return names
+		.map((name) => ({ name, generation: logGeneration(name) }))
+		.filter((entry) => entry.generation !== null)
+		.sort((a, b) => b.generation.version - a.generation.version || Number(b.generation.compressed) - Number(a.generation.compressed))
+		.map((entry) => join(directory, entry.name));
+}
+
+/**
+ * The directory name DSH derives from a workspace path.
+ *
+ * Mirrors the host's project-directory rule: separators become `-`, and the
+ * result is fenced by `-` / `--`. This is a fast path only — {@link findSessionDirectory}
+ * falls back to a full scan when the guess misses.
+ *
+ * @param cwd - the session's workspace directory.
+ * @returns the derived project directory name.
+ */
+export function projectDirectoryName(cwd) {
+	return `-${String(cwd).replace(/[\\/]/g, "-")}--`;
+}
+
+/**
+ * Both spellings a session directory may use, longest-lived first.
+ *
+ * @param sessionId - the session id as DSH reports it.
+ * @returns candidate directory names.
+ */
+export function sessionDirectoryNames(sessionId) {
+	const id = String(sessionId);
+	const bare = id.startsWith("session-") ? id.slice("session-".length) : id;
+	return [...new Set([id, bare, `session-${bare}`])];
+}
+
+/**
+ * Find one session's directory under the sessions root.
+ *
+ * @param root - sessions root.
+ * @param sessionId - session id (with or without the `session-` prefix).
+ * @param cwd - optional workspace directory used for the derived fast path.
+ * @returns `{ dir, project, logs }`, or null when nothing matches.
+ */
+export function findSessionDirectory(root, sessionId, cwd) {
+	const names = sessionDirectoryNames(sessionId);
+	const projects = [];
+	if (typeof cwd === "string" && cwd.length > 0) projects.push(projectDirectoryName(cwd));
+	let candidates = [];
+	try {
+		candidates = readdirSync(root);
+	} catch {
+		return null;
+	}
+	for (const project of candidates) {
+		if (!projects.includes(project)) projects.push(project);
+	}
+	let emptyMatch = null;
+	for (const project of projects) {
+		for (const name of names) {
+			const dir = join(root, project, name);
+			let stats;
+			try {
+				stats = statSync(dir);
+			} catch {
+				continue;
+			}
+			if (!stats.isDirectory()) continue;
+			const logs = listSessionLogs(dir);
+			if (logs.length > 0) return { dir, project, logs };
+			emptyMatch ??= { dir, project, logs: [] };
+		}
+	}
+	return emptyMatch;
+}

package/lib/prompt.js

@@ -0,0 +1,26 @@
+/**
+ * The system-prompt contribution.
+ *
+ * Kept short on purpose: it only has to tell the model that a session's context
+ * is reachable from disk and which tool to use, so that "接着另一个会话继续"
+ * becomes a two-step operation instead of a dead end.
+ *
+ * @module dsh-session-path/prompt
+ */
+
+/**
+ * Guide text for the current settings.
+ *
+ * @param settings - resolved plugin settings.
+ * @returns the prompt section body.
+ */
+export function guideText(settings) {
+	return [
+		"## 会话路径与接续（dsh-session-path）",
+		"",
+		"- 每个 DSH 会话的原始日志在 `$DSH_HOME/sessions/<工作区>/<会话目录>/session[.vN].jsonl[.zstd]`；`.zstd` 是多帧 Zstandard 容器，直接 read 会失败。",
+		"- 要接着另一个会话继续干活：先调用 `session_handoff`（传 `sessionId`，省略则取当前会话）拿到解压后的可读文件路径，再用 read 读取它。",
+		"- 只是想知道/复制会话路径时用 `session_path`（只读，不落盘）。",
+		`- 交接文件默认写到 \`${settings.handoffDir === "" ? "$DSH_HOME/session-handoff" : settings.handoffDir}\`，格式 \`${settings.handoffFormat}\`，字符预算 ${settings.maxHandoffChars}（保留最近的部分）。`,
+	].join("\n");
+}

package/lib/route.js

@@ -0,0 +1,88 @@
+/**
+ * The one HTTP route the browser half needs: resolve a session id into its log
+ * path and a paste-ready copy payload.
+ *
+ * Registration rides the injected fiber, so unloading the plugin withdraws the
+ * route. The route is read-only — it never writes a handoff file (that is the
+ * `session_handoff` tool's job, so file creation stays a deliberate agent act).
+ *
+ * @module dsh-session-path/route
+ */
+
+import { composeCopyText } from "./copy-text.js";
+import { resolveSessionInfo } from "./session-info.js";
+import { isTrustedRequest } from "./trust.js";
+
+/** Exact path served by this plugin. */
+export const RESOLVE_ROUTE = "/api/dsh-session-path/resolve";
+
+/**
+ * Write one JSON envelope.
+ *
+ * @param res - HTTP response.
+ * @param status - status code.
+ * @param body - JSON-serialisable body.
+ */
+function writeJson(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+	res.end(JSON.stringify(body));
+}
+
+/**
+ * Register the resolve route.
+ *
+ * @param ctx - host plugin context.
+ * @param settings - resolved plugin settings.
+ * @returns a disposer (no-op when the host has no web server).
+ */
+export function registerResolveRoute(ctx, settings) {
+	const server = ctx.get("webServer");
+	if (server === undefined || typeof server.register !== "function") return () => {};
+	const trustedHosts = ctx.get("webRuntime")?.trustedHosts ?? [];
+	return server.register({
+		kind: "exact",
+		path: RESOLVE_ROUTE,
+		handler: async (req, res) => {
+			if (!isTrustedRequest(req, trustedHosts)) {
+				writeJson(res, 403, { ok: false, error: { code: "forbidden", message: "forbidden" } });
+				return;
+			}
+			let params;
+			try {
+				params = new URL(req.url ?? RESOLVE_ROUTE, "http://localhost").searchParams;
+			} catch {
+				writeJson(res, 400, { ok: false, error: { code: "bad-request", message: "malformed request url" } });
+				return;
+			}
+			const sessionId = params.get("sessionId") ?? "";
+			if (sessionId === "") {
+				writeJson(res, 400, { ok: false, error: { code: "bad-request", message: "sessionId is required" } });
+				return;
+			}
+			try {
+				const info = await resolveSessionInfo(ctx, settings, sessionId, {
+					title: params.get("title") ?? "",
+					cwd: params.get("cwd") ?? "",
+				});
+				writeJson(res, 200, {
+					ok: true,
+					value: {
+						sessionId: info.sessionId,
+						title: info.title,
+						cwd: info.cwd,
+						logPath: info.logPath,
+						dir: info.dir,
+						exists: info.exists,
+						copyFormat: settings.copyFormat,
+						text: composeCopyText(info, settings.copyFormat),
+					},
+				});
+			} catch (error) {
+				writeJson(res, 500, {
+					ok: false,
+					error: { code: "internal", message: error instanceof Error ? error.message : String(error) },
+				});
+			}
+		},
+	});
+}