dsh-session-manager 0.4.4 → 0.4.7

package/lib/compat/dsh-adapter.js

@@ -0,0 +1,200 @@
+/** Compatibility boundary for DSH services used by dsh-session-manager.
+ *
+ * DSH service names are the supported seam. Concrete implementations
+ * expose optional surfaces that changed during the 0.1.x line; keep all
+ * probes here so route code can fail closed and diagnostics may
+ * explain what this build actually provides.
+ *
+ * @module dsh-session-manager/compat/dsh-adapter
+ */
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/** Pull one service out of the Cordis ctx, tolerating direct property fallbacks. */
+function getService(ctx, name) {
+  try {
+    const value = typeof ctx?.get === "function" ? ctx.get(name) : undefined;
+    if (value !== undefined) return value;
+  } catch { /* fall through to the legacy direct property */ }
+  return ctx && ctx[name];
+}
+
+/** Read one package's version from its package.json if resolvable from this plugin. */
+function packageVersion(name) {
+  try {
+    const manifest = require(name + "/package.json");
+    return typeof manifest?.version === "string" ? manifest.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Locate the dsh-cli installation by scanning process.argv for an
+ * `apps/cli/` segment and reading its package.json (or the workspace root).
+ * Falls back silently when the host is not the dsh CLI (e.g. a test harness).
+ */
+function versionFromArgv() {
+  // process.argv on Windows mixes single backslashes, escaped double backslashes,
+  // and forward slashes depending on how the host launched the binary. Match
+  // "/apps/cli/" by normalizing any of those separators to a single "/" first,
+  // then fall back to checking the parent of bin.js (covers dist bundles that
+  // relocate the bin path under lib/bin.js).
+  for (const arg of process.argv) {
+    const normalized = String(arg).replaceAll("\\\\", "/").replaceAll("\\", "/");
+    let at = normalized.indexOf("/apps/cli/");
+    if (at < 0) {
+      // dist/ build: bin.js sits under apps/cli/lib/ rather than directly
+      // under apps/cli/, so anchor on the bin file basename instead.
+      const binIdx = normalized.lastIndexOf("/bin.");
+      if (binIdx >= 0) at = normalized.indexOf("/apps/cli/", binIdx);
+    }
+    if (at < 0) continue;
+    const root = normalized.slice(0, at);
+    for (const file of [join(root, "apps", "cli", "package.json"), join(root, "package.json")]) {
+      try {
+        const manifest = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof manifest.version === "string") return manifest.version;
+      } catch { /* try the next candidate */ }
+    }
+  }
+  return undefined;
+}
+
+/** Normalize a persistence list item from both snapshot (header field) and raw header shapes. **/
+export function normalizeSessionHeader(value) {
+  if (value === undefined || value === null) return undefined;
+  const header = value?.header && typeof value.header === "object" ? value.header : value;
+  return header && typeof header.id === "string" ? header : undefined;
+}
+
+
+export function normalizeSessionHeaders(values) {
+  if (!Array.isArray(values)) return [];
+  const out = [];
+  for (const value of values) {
+    const header = normalizeSessionHeader(value);
+    if (header !== undefined) out.push(header);
+  }
+  return out;
+}
+
+/**
+ * Build the adapter. Exposes the public DSH surfaces this plugin needs and a
+ * `capabilities()` snapshot for diagnostics.
+ */
+export function createDshAdapter(ctx) {
+  const adapter = {
+    get workspaceRegistry() { return getService(ctx, "workspaceRegistry"); },
+    get sessions() { return getService(ctx, "sessions"); },
+    get agents() { return getService(ctx, "agents"); },
+    get persistence() { return getService(ctx, "sessionPersistence"); },
+    get agentPresets() { return getService(ctx, "agentPresets"); },
+    get projectionCache() { return getService(ctx, "sessionProjectionCache"); },
+    get homePath() { return getService(ctx, "dshHomePath"); },
+
+    getSession(id) {
+      try { return adapter.sessions && adapter.sessions.get && adapter.sessions.get(id); } catch { return undefined; }
+    },
+    getAgent(id) {
+      try { return adapter.agents && adapter.agents.get && adapter.agents.get(id); } catch { return undefined; }
+    },
+    getSessionEvents(session) {
+      if (Array.isArray(session && session.events)) return session.events;
+      return [];
+    },
+    normalizeSessionHeader,
+    normalizeSessionHeaders,
+    async listSessionHeaders() {
+      const persistence = adapter.persistence;
+      if (!persistence || typeof persistence.list !== "function") return [];
+      return normalizeSessionHeaders(await persistence.list());
+    },
+    capabilities() {
+      const persistence = adapter.persistence;
+      const registry = adapter.workspaceRegistry;
+      const sessions = adapter.sessions;
+      let workspaces = [];
+      try { workspaces = registry && typeof registry.list === "function" ? registry.list() : []; } catch { /* diagnostic only */ }
+      let sampleSession;
+      try { sampleSession = sessions && sessions.list && sessions.list() && sessions.list()[0]; } catch { /* diagnostic only */ }
+      return {
+        sessionList: !!(persistence && typeof persistence.list === "function"),
+        sessionStat: !!(persistence && typeof persistence.stat === "function"),
+        sessionHandleOpen: !!(persistence && typeof persistence.open === "function"),
+        persistenceLocate: !!(persistence && typeof persistence.locate === "function"),
+        persistenceResolveLog: !!(persistence && typeof persistence.resolveLog === "function"),
+        workspaceList: !!(registry && typeof registry.list === "function"),
+        workspaceAttach: !!(workspaces[0] && typeof workspaces[0].attachSession === "function"),
+        workspaceDetach: !!(workspaces[0] && typeof workspaces[0].detachSession === "function"),
+        sessionStore: !!(sessions && typeof sessions.get === "function"),
+        liveSessionEvents: !!(sampleSession && Array.isArray(sampleSession.events)),
+      };
+    },
+    dshVersion() {
+      return process.env.DSH_VERSION
+        || packageVersion("@deepseek-ai/dsh")
+        || packageVersion("@deepseek-ai/dsh-cli")
+        || versionFromArgv()
+        || "unknown";
+    },    async openSessionRead(id) {
+      const persistence = adapter.persistence;
+      if (!persistence || typeof persistence.open !== "function") {
+        throw new Error("dsh-session-manager: SessionPersistence.open is unavailable; the read path will fall back to disk");
+      }
+      return await persistence.open(id, "read");
+    },
+    async statSession(id) {
+      const persistence = adapter.persistence;
+      if (!persistence || typeof persistence.stat !== "function") return undefined;
+      return await persistence.stat(id);
+    },
+    async resolveSessionPath(id) {
+      const persistence = adapter.persistence;
+      if (!persistence) return undefined;
+      if (typeof persistence.resolveLog === "function") {
+        try { return await persistence.resolveLog(id); } catch { return undefined; }
+      }
+      if (typeof persistence.locate === "function") {
+        const header = { id: id };
+        try {
+          const located = persistence.locate(header);
+          return located && located.path;
+        } catch { return undefined; }
+      }
+      return undefined;
+    },
+    async listSessionSnapshots() {
+      const persistence = adapter.persistence;
+      if (!persistence || typeof persistence.list !== "function") return [];
+      try { return await persistence.list(); } catch { return []; }
+    },
+    workspaceEntityFor(workspaceId) {
+      const registry = adapter.workspaceRegistry;
+      if (!registry || typeof registry.get !== "function") return undefined;
+      try { return registry.get(workspaceId); } catch { return undefined; }
+    },
+    workspaceList() {
+      const registry = adapter.workspaceRegistry;
+      if (!registry || typeof registry.list !== "function") return [];
+      try { return registry.list(); } catch { return []; }
+    },
+    async readSessionEvents(id, max) {
+      const handle = await adapter.openSessionRead(id);
+      try {
+        return await handle.read(0, typeof max === "number" ? max : 1024);
+      } finally {
+        if (typeof handle.close === "function") {
+          try { await handle.close(); } catch { /* best-effort */ }
+        }
+      }
+    },
+    pluginVersion() {
+      return packageVersion("dsh-session-manager") || "unknown";
+    },
+  };
+  return adapter;
+}

package/lib/compat/zstd-frames.js

@@ -0,0 +1,93 @@
+/** Strict, generation-safe Zstandard concatenated-frame helpers.
+ *
+ * DSH session artifacts are concatenated checksummed Zstandard frames (one
+ * frame per durable batch), so the multi-frame boundary must be computed
+ * from the frame header itself, not from a magic-byte scan. This is a
+ * direct port of DSH's frame scanner and shares its layout contract:
+ *
+ *   - Each frame begins with the 4-byte LE magic 0xfd2fb528.
+ *   - Reserved bits in the frame-header descriptor byte must be zero.
+ *   - Each block carries a 3-byte LE header; reserved block type 0x3 fails.
+ *   - Optional 4-byte frame checksum is appended after the last block.
+ *
+ * @module dsh-session-manager/compat/zstd-frames
+ */
+import { zstdDecompress } from "node:zlib";
+import { promisify } from "node:util";
+
+const zstdDecompressAsync = promisify(zstdDecompress);
+const ZSTD_MAGIC = 0xfd2fb528;
+
+/** Locate complete Zstandard frames; an incomplete final frame is returned
+ * separately as `tornStart` and can be ignored by read-only paths.
+ */
+export function scanZstdFrames(buffer, maxFrames = Number.POSITIVE_INFINITY) {
+  const frames = [];
+  let offset = 0;
+  while (offset < buffer.length) {
+    const start = offset;
+    if (buffer.length - offset < 4) return { frames, tornStart: start };
+    if (buffer.readUint32LE(offset) != ZSTD_MAGIC) {
+      throw new Error(`corrupt Zstandard session log: invalid frame magic at byte ${offset}`);
+    }
+    offset += 4;
+    if (offset === buffer.length) return { frames, tornStart: start };
+    const descriptor = buffer.readUint8(offset++);
+    if ((descriptor & 0x18) !== 0) {
+      throw new Error(`corrupt Zstandard session log: reserved frame-header bit at byte ${offset - 1}`);
+    }
+    const contentSizeFlag = descriptor >>>6;
+    const singleSegment = (descriptor & 0x20) !== 0;
+    const checksum = (descriptor & 0x04) !== 0;
+    const dictionaryFlag = descriptor & 0x03;
+    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, tornStart: start };
+    offset += remainingHeaderBytes;
+    for(;;) {
+      if (buffer.length - offset < 3) return { frames, tornStart: start };
+      const blockHeader = buffer.readUIntLE(offset, 3);
+      offset += 3;
+      const lastBlock = (blockHeader & 1) !== 0;
+      const blockType = (blockHeader >>> 1) & 0x03;
+      const blockSize = blockHeader >>> 3;
+      if (blockType === 0x03) {
+        throw new Error(`corrupt Zstandard session log: reserved block type at byte ${offset - 3}`);
+      }
+      const payloadBytes = blockType === 0x01 ? 1 : blockSize;
+      if (buffer.length - offset < payloadBytes) return { frames, tornStart: start };
+      offset += payloadBytes;
+      if (lastBlock) break;
+    }
+    if (checksum) {
+      if (buffer.length - offset < 4) return { frames, tornStart: start };
+      offset += 4;
+    }
+    frames.push({ start, end: offset });
+    if (frames.length === maxFrames) return { frames };
+  }
+  return { frames };
+}
+
+export async function decompressZstdFrame(frame) {
+  return zstdDecompressAsync(frame);
+}
+
+export async function decompressAllZstdFrames(buffer) {
+  const scan = scanZstdFrames(buffer);
+  if (scan.frames.length === 0) {
+    throw new Error("empty or header-less Zstandard session log");
+  }
+  const decoded = [];
+  for (const frame of scan.frames) {
+    decoded.push(await decompressZstdFrame(buffer.subarray(frame.start, frame.end)));
+  }
+  return {
+    content: Buffer.concat(decoded),
+    frameCount: decoded.length,
+    torn: scan.tornStart !== undefined,
+  };
+}