dsh-session-path 0.0.0-stage → 0.1.2

package/lib/session-info.js

@@ -0,0 +1,124 @@
+/**
+ * Resolve everything a caller needs to know about one session: its id, title,
+ * workspace directory and the absolute path of its committed log.
+ *
+ * The workspace directory comes from the live session header when the session is
+ * mounted, and the log path comes from an authoritative directory lookup — never
+ * from a derived guess alone, so a renamed project folder cannot produce a path
+ * that does not exist.
+ *
+ * @module dsh-session-path/session-info
+ */
+
+import { findSessionDirectory, sessionsRoot } from "./paths.js";
+import { readSessionRecords } from "./zstd.js";
+
+/** Longest accepted session id / title / cwd hint (untrusted input from the GUI). */
+const MAX_HINT_CHARS = 4096;
+
+/**
+ * The live session header, when the host's session store has the session.
+ *
+ * @param ctx - host plugin context.
+ * @param sessionId - session id.
+ * @returns the header object, or an empty object.
+ */
+export function liveSessionHeader(ctx, sessionId) {
+	try {
+		const sessions = ctx?.get?.("sessions");
+		const session = typeof sessions?.get === "function" ? sessions.get(sessionId) : undefined;
+		const header = session?.header;
+		return header !== null && typeof header === "object" ? header : {};
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Normalise one untrusted string hint (or an empty string).
+ *
+ * @param value - candidate value.
+ * @returns the trimmed value within the length cap.
+ */
+function hint(value) {
+	return typeof value === "string" && value.length > 0 ? value.slice(0, MAX_HINT_CHARS) : "";
+}
+
+/**
+ * The session's title from its log, taken from the last `session/title` event
+ * inside a bounded prefix of the file.
+ *
+ * @param file - log path.
+ * @param maxBytes - compressed byte budget.
+ * @returns the title, or an empty string.
+ */
+export async function readSessionTitle(file, maxBytes) {
+	let title = "";
+	try {
+		for await (const record of readSessionRecords(file, { maxBytes })) {
+			if (record.type !== "session/title") continue;
+			const next = record.data?.title;
+			if (typeof next === "string" && next.trim().length > 0) title = next.trim();
+		}
+	} catch {
+		/* the title is cosmetic: a damaged log must not fail the whole call */
+	}
+	return title;
+}
+
+/**
+ * The session's own header record from the log (`{ type: "session", cwd, ... }`).
+ *
+ * A cold session — one this process never mounted — has no live header, and the
+ * workspace directory is what a continuation needs most. The header is the first
+ * record of the first frame, so a small byte budget is always enough.
+ *
+ * @param file - log path.
+ * @param maxBytes - compressed byte budget.
+ * @returns the header record, or null.
+ */
+export async function readSessionHeader(file, maxBytes = 262_144) {
+	try {
+		for await (const record of readSessionRecords(file, { maxBytes })) {
+			if (record.type === "session") return record;
+		}
+	} catch {
+		/* fall through: an unknown cwd is reported as empty */
+	}
+	return null;
+}
+
+/**
+ * Everything the tools and the HTTP route need about one session.
+ *
+ * @param ctx - host plugin context.
+ * @param settings - resolved plugin settings.
+ * @param sessionId - the session to resolve.
+ * @param hints - optional GUI-supplied `{ title, cwd }` (cosmetic, unverified).
+ * @returns the resolved session info.
+ */
+export async function resolveSessionInfo(ctx, settings, sessionId, hints = {}) {
+	const id = hint(sessionId);
+	if (id === "") throw new Error("session id is required");
+	const header = liveSessionHeader(ctx, id);
+	const hintedCwd = hint(hints.cwd);
+	const liveCwd = hint(header.cwd);
+	const root = sessionsRoot(ctx);
+	const found = findSessionDirectory(root, id, liveCwd || hintedCwd);
+	const logs = found?.logs ?? [];
+	const logPath = logs[0] ?? "";
+	let cwd = liveCwd || hintedCwd;
+	if (cwd === "" && logPath !== "") cwd = hint((await readSessionHeader(logPath))?.cwd);
+	let title = hint(hints.title);
+	if (title === "" && logPath !== "") title = await readSessionTitle(logPath, settings.titleScanBytes);
+	return {
+		sessionId: id,
+		title,
+		cwd,
+		logPath,
+		dir: found?.dir ?? "",
+		project: found?.project ?? "",
+		root,
+		exists: logPath !== "",
+	};
+}

package/lib/tools.js

@@ -0,0 +1,162 @@
+/**
+ * The two agent-facing tools.
+ *
+ * `session_path` answers "where is this session's log?" (no writes), and
+ * `session_handoff` answers "give me something I can actually read" by writing a
+ * decompressed transcript next to the DSH home. Together they are how one
+ * session hands its context to another.
+ *
+ * @module dsh-session-path/tools
+ */
+
+import { composeCopyText } from "./copy-text.js";
+import { writeHandoff } from "./handoff.js";
+import { resolveSessionInfo } from "./session-info.js";
+
+/**
+ * The session a call targets: the explicit argument, else the calling session.
+ *
+ * @param args - tool arguments.
+ * @param exec - tool execution context.
+ * @returns the session id.
+ */
+function targetSessionId(args, exec) {
+	const explicit = typeof args?.sessionId === "string" ? args.sessionId.trim() : "";
+	if (explicit !== "") return explicit;
+	const own = exec?.agent?.session?.id;
+	if (typeof own === "string" && own !== "") return own;
+	throw new Error("no session id: pass sessionId, or call this from inside a session");
+}
+
+/** Shared `sessionId` parameter description. */
+const SESSION_ID_PARAM = {
+	type: "string",
+	description: "Session id to inspect. Omit to use the session this call runs in (`session-<uuid>` and bare-uuid spellings are both accepted).",
+};
+
+/**
+ * Build both tool specs bound to one plugin instance.
+ *
+ * @param options - `{ ctx, settings }`.
+ * @returns tool specs consumed by the entry point.
+ */
+export function createToolSpecs({ ctx, settings }) {
+	return [
+		{
+			name: "session_path",
+			description:
+				"Resolve a DSH session's on-disk log path and workspace directory. Use when the user asks to copy a session's path, to check where a session is stored, or to hand a session off to another session. Omit sessionId for the current session. Read-only: nothing is written.",
+			parameters: {
+				sessionId: SESSION_ID_PARAM,
+				format: {
+					type: "string",
+					description: 'Copy payload: "path" (bare log path) or "block" (paste-ready handoff block, default).',
+				},
+			},
+			outputSchema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: { type: "boolean", required: true },
+					sessionId: { type: "string", required: true },
+					title: { type: "string", required: true },
+					cwd: { type: "string", required: true },
+					logPath: { type: "string", required: true },
+					dir: { type: "string", required: true },
+					exists: { type: "boolean", required: true },
+					text: { type: "string", required: true },
+				},
+			},
+			presentCall: (args) => ({ card: "generic", title: "session_path", kind: "execute", detail: args?.sessionId ?? "" }),
+			render: (_args, value) =>
+				value.exists
+					? [
+							{ type: "text", text: `会话 ${value.sessionId} 的日志：${value.logPath}` },
+							{ type: "text", text: value.text },
+						]
+					: [{ type: "text", text: `未找到会话 ${value.sessionId} 的日志文件（sessions 根：${value.dir === "" ? "?" : value.dir}）。` }],
+			async execute(args, exec) {
+				const sessionId = targetSessionId(args, exec);
+				const format = args?.format === "path" ? "path" : settings.copyFormat;
+				const info = await resolveSessionInfo(ctx, settings, sessionId, {});
+				return {
+					ok: true,
+					sessionId: info.sessionId,
+					title: info.title,
+					cwd: info.cwd,
+					logPath: info.logPath,
+					dir: info.dir,
+					exists: info.exists,
+					text: composeCopyText(info, format),
+				};
+			},
+		},
+		{
+			name: "session_handoff",
+			description:
+				"Write a readable, decompressed copy of a DSH session (Markdown transcript by default) and return its absolute path. Use to continue another session's work: call this, then `read` the returned file. Omit sessionId for the current session.",
+			parameters: {
+				sessionId: SESSION_ID_PARAM,
+				format: {
+					type: "string",
+					description: 'Output file: "md" (human/agent-readable transcript, default) or "jsonl" (plain decompressed event log).',
+				},
+				maxChars: {
+					type: "integer",
+					description: "Character budget for the written file; the most recent part of the session is kept. Defaults to the plugin setting (200000).",
+				},
+			},
+			outputSchema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					ok: { type: "boolean", required: true },
+					sessionId: { type: "string", required: true },
+					title: { type: "string", required: true },
+					cwd: { type: "string", required: true },
+					logPath: { type: "string", required: true },
+					file: { type: "string", required: true },
+					format: { type: "string", required: true },
+					chars: { type: "integer", required: true },
+					kept: { type: "integer", required: true },
+					truncated: { type: "boolean", required: true },
+				},
+			},
+			presentCall: (args) => ({ card: "generic", title: "session_handoff", kind: "execute", detail: args?.sessionId ?? "" }),
+			render: (_args, value) => {
+				const lines = [
+					`会话记录已写出：${value.file}`,
+					`格式 ${value.format} · ${value.chars} 字符 · ${value.kept} 条${value.truncated ? "（仅最近部分，前文已截断）" : ""}`,
+					`工作目录：${value.cwd === "" ? "(未知)" : value.cwd}`,
+					`原始日志：${value.logPath}`,
+					`下一步：用 read 读取 ${value.file} 即可接续该会话。`,
+				];
+				return [{ type: "text", text: lines.join("\n") }];
+			},
+			async execute(args, exec) {
+				const sessionId = targetSessionId(args, exec);
+				const info = await resolveSessionInfo(ctx, settings, sessionId, {});
+				if (!info.exists) {
+					throw new Error(`no committed log found for session "${info.sessionId}" under ${info.root}; check the session id`);
+				}
+				const format = args?.format === "jsonl" ? "jsonl" : args?.format === "md" ? "md" : settings.handoffFormat;
+				const result = await writeHandoff(ctx, settings, info, {
+					format,
+					maxChars: Number(args?.maxChars) > 0 ? Number(args.maxChars) : undefined,
+				});
+				return {
+					ok: true,
+					sessionId: info.sessionId,
+					title: info.title,
+					cwd: info.cwd,
+					logPath: info.logPath,
+					file: result.file,
+					format: result.format,
+					chars: result.chars,
+					kept: result.kept,
+					truncated: result.truncated,
+				};
+			},
+		},
+	];
+}

package/lib/trust.js

@@ -0,0 +1,81 @@
+/**
+ * The trust fence for this plugin's HTTP route.
+ *
+ * The Web GUI is served on loopback and may also be reached through a LAN bind,
+ * a reverse proxy or a tunnel, so the route accepts a request only when its
+ * `Host` is loopback or an explicitly trusted authority, not a cross-site fetch,
+ * and — when an `Origin` is present — same-host. This mirrors the fence the
+ * shipped Web routes use; a browser cannot forge these headers from another
+ * origin, which is what keeps the route from becoming an open session-path oracle.
+ *
+ * @module dsh-session-path/trust
+ */
+
+/** Case-insensitive header lookup (Node lowercases, fakes may not). */
+function headerOf(headers, name) {
+	const value = headers?.[name];
+	if (typeof value === "string") return value;
+	if (Array.isArray(value) && typeof value[0] === "string") return value[0];
+	return undefined;
+}
+
+/**
+ * Hostname only, from a `Host` header value (IPv6 brackets preserved).
+ *
+ * @param host - the raw header value.
+ * @returns the hostname, or null when unparsable.
+ */
+export function authorityHostname(host) {
+	try {
+		return new URL(`http://${host}`).hostname.toLowerCase();
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Whether a hostname is a loopback spelling.
+ *
+ * @param hostname - lowercased hostname.
+ * @returns true for localhost / 127.0.0.0-8 / ::1.
+ */
+export function isLoopbackHostname(hostname) {
+	if (hostname === "localhost" || hostname === "::1" || hostname === "[::1]") return true;
+	return /^127(?:\.\d{1,3}){3}$/.test(hostname);
+}
+
+/**
+ * Whether `Host` matches one of the runtime's trusted authorities.
+ *
+ * @param host - raw `Host` header value.
+ * @param trustedHosts - authorities from the web runtime (`host` or `host:port`).
+ * @returns true on an exact authority match.
+ */
+export function isTrustedAuthority(host, trustedHosts) {
+	if (!Array.isArray(trustedHosts)) return false;
+	const wanted = host.toLowerCase();
+	return trustedHosts.some((entry) => typeof entry === "string" && entry.toLowerCase() === wanted);
+}
+
+/**
+ * The fence itself.
+ *
+ * @param request - the HTTP request.
+ * @param trustedHosts - authorities from the web runtime.
+ * @returns true when the request may read session paths.
+ */
+export function isTrustedRequest(request, trustedHosts) {
+	const host = headerOf(request?.headers, "host");
+	if (host === undefined) return false;
+	const hostname = authorityHostname(host);
+	if (hostname === null) return false;
+	if (!isLoopbackHostname(hostname) && !isTrustedAuthority(host, trustedHosts)) return false;
+	if (headerOf(request?.headers, "sec-fetch-site") === "cross-site") return false;
+	const origin = headerOf(request?.headers, "origin");
+	if (origin === undefined) return true;
+	try {
+		return new URL(origin).hostname.toLowerCase() === hostname;
+	} catch {
+		return false;
+	}
+}

package/lib/zstd.js

@@ -0,0 +1,201 @@
+/**
+ * Read DSH session logs.
+ *
+ * A committed log is either plain JSONL or a Zstandard container holding **one
+ * independent frame per append batch** — the host flushes each batch as its own
+ * checksummed frame. Node's `zstdDecompressSync` decodes a single frame and
+ * fails on the next frame's magic, so the container must be walked frame by
+ * frame. {@link scanZstdFrames} does that structurally (block payloads are
+ * skipped, never inflated), which keeps memory to one frame at a time and makes
+ * a partially written tail frame harmless.
+ *
+ * @module dsh-session-path/zstd
+ */
+
+import { open } from "node:fs/promises";
+import zlib from "node:zlib";
+
+/** `ZSTD_MAGICNUMBER`, little-endian in the stream. */
+const ZSTD_MAGIC = 0xfd2fb528;
+
+/** How many compressed bytes are pulled from disk per read. */
+const READ_CHUNK_BYTES = 1 << 20;
+
+/**
+ * Packed增量 rows: the host appends text/reasoning/tool-call deltas as these
+ * types. They dominate a log's size and are meaningless to a reader, so parsed
+ * records drop them before they can be materialised.
+ */
+const PACKED_TYPES = new Set(["text-chunks", "reasoning-chunks", "tool-call-chunks", "text-delta", "reasoning-delta"]);
+
+/**
+ * Byte ranges of the complete Zstandard frames at the head of `buffer`.
+ *
+ * Parsing stops at the first byte that is not a frame start (an incomplete tail
+ * frame, a corrupt region, or a skippable frame this plugin does not emit), so
+ * a truncated log yields its intact prefix instead of throwing.
+ *
+ * @param buffer - raw container bytes.
+ * @returns `{ start, end }[]` in stream order.
+ */
+export function scanZstdFrames(buffer) {
+	const frames = [];
+	let offset = 0;
+	while (offset < buffer.length) {
+		const start = offset;
+		if (buffer.length - offset < 4) return frames;
+		if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) return frames;
+		offset += 4;
+		if (offset === buffer.length) return frames;
+		const descriptor = buffer.readUInt8(offset);
+		offset += 1;
+		if ((descriptor & 24) !== 0) return frames; // reserved bits: structurally invalid
+		const contentSizeFlag = descriptor >>> 6;
+		const singleSegment = (descriptor & 32) !== 0;
+		const checksum = (descriptor & 4) !== 0;
+		const dictionaryFlag = descriptor & 3;
+		const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+		const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag;
+		const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+		if (buffer.length - offset < remainingHeaderBytes) return frames;
+		offset += remainingHeaderBytes;
+		for (;;) {
+			if (buffer.length - offset < 3) return frames;
+			const blockHeader = buffer.readUIntLE(offset, 3);
+			offset += 3;
+			const lastBlock = (blockHeader & 1) !== 0;
+			const blockType = (blockHeader >>> 1) & 3;
+			const blockSize = blockHeader >>> 3;
+			if (blockType === 3) return frames; // reserved block type
+			// An RLE block stores one byte regardless of its decompressed size.
+			const payloadBytes = blockType === 1 ? 1 : blockSize;
+			if (buffer.length - offset < payloadBytes) return frames;
+			offset += payloadBytes;
+			if (lastBlock) break;
+		}
+		if (checksum) {
+			if (buffer.length - offset < 4) return frames;
+			offset += 4;
+		}
+		frames.push({ start, end: offset });
+	}
+	return frames;
+}
+
+/**
+ * Parse one log line, dropping blanks, packed deltas and damaged lines.
+ *
+ * @param line - one JSONL line.
+ * @returns the record, or null when it carries no information.
+ */
+export function parseRecordLine(line) {
+	if (line.length === 0) return null;
+	if (line.length > 8 * 1024 * 1024) return null; // giant packed row: skip before JSON.parse
+	try {
+		const record = JSON.parse(line);
+		if (record === null || typeof record !== "object") return null;
+		if (PACKED_TYPES.has(record.type)) return null;
+		return record;
+	} catch {
+		return null; // best-effort replay: one damaged line must not kill the file
+	}
+}
+
+/**
+ * Turn a text slice into records, carrying the unfinished tail line forward.
+ *
+ * @param text - decoded chunk.
+ * @param pending - leftover from the previous chunk.
+ * @returns the new pending buffer.
+ */
+function consumeText(text, pending, out) {
+	const lines = text.split("\n");
+	lines[0] = pending + lines[0];
+	const next = lines.pop() ?? "";
+	for (const line of lines) {
+		const record = parseRecordLine(line);
+		if (record !== null) out.push(record);
+	}
+	return next;
+}
+
+/**
+ * Walk one session log and yield its records.
+ *
+ * The file is read in chunks; complete frames found at the head of the working
+ * buffer are inflated and released immediately, and everything after the last
+ * complete frame stays in a tail buffer for the next chunk. `maxBytes` bounds
+ * the compressed bytes read, which is how callers keep a title probe cheap on a
+ * multi-hundred-megabyte log.
+ *
+ * @param file - `session.vN.jsonl.zstd` or `session.jsonl` path.
+ * @param options - `{ maxBytes?, onFrame? }`.
+ * @yields parsed records in log order.
+ */
+export async function* readSessionRecords(file, options = {}) {
+	const maxBytes = Number(options.maxBytes) > 0 ? Number(options.maxBytes) : Infinity;
+	const onFrame = typeof options.onFrame === "function" ? options.onFrame : null;
+	const handle = await open(file, "r");
+	try {
+		const compressed = file.endsWith(".zstd");
+		let pending = "";
+		let tail = Buffer.alloc(0);
+		let read = 0;
+		for (;;) {
+			const chunk = await handle.read(Buffer.allocUnsafe(READ_CHUNK_BYTES), 0, READ_CHUNK_BYTES, null);
+			if (chunk.bytesRead === 0) break;
+			read += chunk.bytesRead;
+			const slice = chunk.buffer.subarray(0, chunk.bytesRead);
+			const data = tail.length > 0 ? Buffer.concat([tail, slice]) : Buffer.from(slice);
+			tail = Buffer.alloc(0);
+			if (!compressed) {
+				const out = [];
+				pending = consumeText(data.toString("utf8"), pending, out);
+				if (out.length > 0) yield* out;
+			} else {
+				const frames = scanZstdFrames(data);
+				for (const frame of frames) {
+					const plain = inflateFrame(data, frame);
+					if (plain === null) return;
+					onFrame?.(frame.end - frame.start);
+					const out = [];
+					pending = consumeText(plain, pending, out);
+					if (out.length > 0) yield* out;
+				}
+				const consumed = frames.length > 0 ? frames[frames.length - 1].end : 0;
+				tail = Buffer.from(data.subarray(consumed));
+				// A full chunk that still yields no frame means the container is
+				// damaged; stop rather than buffer the rest of the file forever.
+				if (frames.length === 0 && tail.length >= READ_CHUNK_BYTES * 2) return;
+			}
+			if (read >= maxBytes) break;
+		}
+		if (!compressed && pending.length > 0) {
+			const record = parseRecordLine(pending);
+			if (record !== null) yield record;
+		}
+	} finally {
+		await handle.close();
+	}
+}
+
+/**
+ * Inflate one scanned frame, or null when the bytes are damaged.
+ *
+ * @param data - the working buffer.
+ * @param frame - `{ start, end }` from {@link scanZstdFrames}.
+ * @returns decoded UTF-8 text.
+ */
+function inflateFrame(data, frame) {
+	try {
+		return inflate(data.subarray(frame.start, frame.end));
+	} catch {
+		return null;
+	}
+}
+
+/** Decode one complete Zstandard frame (absent on exotic runtimes). */
+function inflate(bytes) {
+	if (typeof zlib.zstdDecompressSync !== "function") throw new Error("zstd is unavailable on this runtime");
+	return zlib.zstdDecompressSync(bytes).toString("utf8");
+}

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "dsh-session-path",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.2",
+  "description": "DeepSeek Harness plugin: copy a session's log path (and an agent-readable handoff) so another session can read it and continue the work.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "session",
+    "session-log",
+    "handoff",
+    "path",
+    "会话",
+    "接续"
+  ],
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/439436269-ctrl/dsh-session-path.git"
+  },
+  "homepage": "https://github.com/439436269-ctrl/dsh-session-path#readme",
+  "bugs": {
+    "url": "https://github.com/439436269-ctrl/dsh-session-path/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-primitives"
+      ],
+      "platform": "web"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.0-rc.2": "compatible"
+      }
+    }
+  },
+  "scripts": {
+    "test": "node test/selftest.mjs"
+  }
 }