dsh-archived 0.3.0

package/lib/host/metadata.js

@@ -0,0 +1,144 @@
+// Read-only metadata about archived sessions.
+//
+// The Settings page must be able to describe a row even when the browser's
+// session store has no summary for it — that is exactly the "index-only
+// residue" case (the archive set names an id whose log is already gone, or
+// whose log is present but not loaded in this client). The projection cache
+// document carries what a row needs: `record.rows.title.val` and
+// `record.identity.{createdAt, cwd, formatVersion}`.
+
+import { readFile, stat } from "node:fs/promises";
+import { legacyAggregateFile, projectionCacheFile } from "./paths.js";
+
+/** Parse one projection-cache document; null when it is missing or unreadable. */
+export async function readCacheDocument(sessionId) {
+  try {
+    const text = await readFile(projectionCacheFile(sessionId), "utf8");
+    const parsed = JSON.parse(text);
+    const record = parsed?.record;
+    if (record === null || typeof record !== "object") return null;
+    const title = record.rows?.title?.val;
+    const identity = record.identity ?? {};
+    return {
+      title: typeof title === "string" && title.length > 0 ? title : null,
+      createdAt: typeof identity.createdAt === "number" ? identity.createdAt : null,
+      cwd: typeof identity.cwd === "string" ? identity.cwd : null,
+      formatVersion: typeof identity.formatVersion === "number" ? identity.formatVersion : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Session ids still present in the pre-per-record aggregate. The domain moved
+ * to one document per session and this file stopped being written (its mtime on
+ * a live machine trails the per-record directory by weeks), so it is reported
+ * and never rewritten: it is host-owned state we only read.
+ *
+ * @returns the id set, or null when the file is absent or unreadable.
+ */
+let legacyCache = { mtimeMs: -1, rows: null };
+export async function legacyAggregateRows() {
+  const file = legacyAggregateFile();
+  try {
+    const info = await stat(file);
+    if (info.mtimeMs === legacyCache.mtimeMs) return legacyCache.rows;
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    const rows = parsed?.tables?.sessions;
+    const ids = rows !== null && typeof rows === "object" ? new Set(Object.keys(rows)) : new Set();
+    legacyCache = { mtimeMs: info.mtimeMs, rows: ids };
+    return ids;
+  } catch {
+    legacyCache = { mtimeMs: -1, rows: null };
+    return null;
+  }
+}
+
+/** Whether the session is running a turn right now. */
+export function isRunning(ctx, sessionId) {
+  try {
+    return ctx.agents?.get?.(sessionId)?.status === "running";
+  } catch {
+    return false;
+  }
+}
+
+/** The subagent lineage of one live agent: itself first, then its ancestors. */
+function lineageOfAgent(ctx, agent) {
+  const chain = [];
+  const seen = new Set();
+  let header = agent?.session?.header;
+  while (header !== undefined && header !== null && !seen.has(header.id)) {
+    chain.push(header.id);
+    seen.add(header.id);
+    if (header.origin !== "subagent" || header.parentSession === undefined) break;
+    const parent = ctx.sessions?.get?.(header.parentSession);
+    if (parent === undefined || parent === null) {
+      chain.push(header.parentSession);
+      break;
+    }
+    header = parent.header;
+  }
+  return chain;
+}
+
+/**
+ * Running subagent descendants of one session. A parent may be deleted while
+ * its children keep working — their parent session would vanish underneath
+ * them — so a delete is refused while any of them is mid-turn.
+ *
+ * @returns ids of running descendants.
+ */
+export function runningDescendants(ctx, sessionId) {
+  const found = [];
+  let agents;
+  try {
+    agents = ctx.agents?.list?.() ?? [];
+  } catch {
+    return found;
+  }
+  for (const agent of agents) {
+    if (agent?.status !== "running") continue;
+    if (agent.id === sessionId) continue;
+    if (lineageOfAgent(ctx, agent).includes(sessionId)) found.push(agent.id);
+  }
+  return found;
+}
+
+/** Ancestor session ids of one session, from the durable header chain. */
+export function ancestorsOf(ctx, sessionId) {
+  const header = ctx.sessions?.get?.(sessionId)?.header;
+  if (header === undefined || header === null) return [];
+  if (header.origin !== "subagent" || header.parentSession === undefined) return [];
+  const chain = [];
+  const seen = new Set([sessionId]);
+  let cursor = header.parentSession;
+  while (cursor !== undefined && cursor !== null && !seen.has(cursor)) {
+    seen.add(cursor);
+    chain.push(cursor);
+    const parent = ctx.sessions?.get?.(cursor);
+    if (parent === undefined || parent === null) break;
+    const parentHeader = parent.header;
+    if (parentHeader?.origin !== "subagent" || parentHeader.parentSession === undefined) break;
+    cursor = parentHeader.parentSession;
+  }
+  return chain;
+}
+
+/** Live subagent children of one session, whether or not they are running. */
+export function liveChildrenOf(ctx, sessionId) {
+  const children = [];
+  let agents;
+  try {
+    agents = ctx.agents?.list?.() ?? [];
+  } catch {
+    return children;
+  }
+  for (const agent of agents) {
+    if (agent?.id === sessionId) continue;
+    const header = agent?.session?.header;
+    if (header?.origin === "subagent" && header.parentSession === sessionId) children.push(agent.id);
+  }
+  return children;
+}

package/lib/host/paths.js

@@ -0,0 +1,117 @@
+// Path derivation for everything one archived session owns on disk.
+//
+// DSH 0.2.0-rc.2 keeps three pieces of per-session state, and a permanent
+// delete has to answer for all three:
+//
+//   1. the artifact directory   $DSH_HOME/sessions/<encoded-workspace>/session-<id>/
+//                               (session.v4.jsonl.zstd + session.lock)
+//   2. the projection cache doc $DSH_HOME/storages/session_projcache/sessions/<id>.json
+//   3. the archive index entry  workspace registry archivedSessionIds
+//
+// Path resolution is inlined instead of importing @deepseek-ai/dsh-home-paths:
+// this plugin is developed out of tree and linked into the profile, so a bare
+// package import would not resolve from its real path. The rule mirrored here
+// is the documented one — $DSH_HOME when non-blank, otherwise ~/.dsh.
+
+import { existsSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+/** Session ids this plugin is willing to touch: the canonical `session-<uuid>`. */
+export const SESSION_ID = /^session-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function dshHome() {
+  const configured = process.env.DSH_HOME;
+  if (typeof configured === "string" && configured.trim() !== "") return resolve(configured.trim());
+  return join(homedir(), ".dsh");
+}
+
+/** Root holding one directory per encoded workspace, each with `session-*` children. */
+export function sessionsRoot() {
+  return join(dshHome(), "sessions");
+}
+
+/** Root holding one projection-cache document per session (the `per-record` json layout). */
+export function projectionCacheDir() {
+  return join(dshHome(), "storages", "session_projcache", "sessions");
+}
+
+export function projectionCacheFile(sessionId) {
+  return join(projectionCacheDir(), sessionId + ".json");
+}
+
+/**
+ * The pre-per-record aggregate of the same domain. It stopped being written
+ * when the domain moved to one document per session (`unit.version: 3`), so it
+ * is host-owned history we only report on, never rewrite.
+ */
+export function legacyAggregateFile() {
+  return join(dshHome(), "storages", "session_projcache.json");
+}
+
+/** The durable workspace registry store; the archive index lives in its `global` block. */
+export function workspaceStoreFile() {
+  return join(dshHome(), "storages", "workspace.json");
+}
+
+/** Deleted-but-recoverable sessions live here, beside the state they came from. */
+export function quarantineRoot() {
+  return join(dshHome(), ".archived-sessions-quarantine");
+}
+
+export function quarantineEntry(sessionId) {
+  return join(quarantineRoot(), sessionId);
+}
+
+/** Where a quarantined session's original artifact directory is parked. */
+export function quarantineArtifactDir(sessionId) {
+  return join(quarantineEntry(sessionId), "session");
+}
+
+/** Where a quarantined session's projection-cache document is parked. */
+export function quarantineCacheFile(sessionId) {
+  return join(quarantineEntry(sessionId), "cache.json");
+}
+
+export function quarantineMetaFile(sessionId) {
+  return join(quarantineEntry(sessionId), "meta.json");
+}
+
+/** Every on-disk artifact directory of one session (normally zero or one). */
+export async function locateArtifacts(sessionId) {
+  const found = [];
+  let workspaces;
+  try {
+    workspaces = await readdir(sessionsRoot(), { withFileTypes: true });
+  } catch {
+    return found;
+  }
+  for (const workspace of workspaces) {
+    if (!workspace.isDirectory()) continue;
+    const candidate = join(sessionsRoot(), workspace.name, sessionId);
+    if (existsSync(candidate)) found.push(candidate);
+  }
+  return found;
+}
+
+/** Recursive byte size of one artifact directory; unreadable entries count as 0. */
+export async function directorySize(path) {
+  let total = 0;
+  let entries;
+  try {
+    entries = await readdir(path, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+  for (const entry of entries) {
+    const child = join(path, entry.name);
+    try {
+      if (entry.isDirectory()) total += await directorySize(child);
+      else if (entry.isFile()) total += (await stat(child)).size;
+    } catch {
+      // A vanished or unreadable child contributes nothing to the estimate.
+    }
+  }
+  return total;
+}

package/lib/host/quarantine.js

@@ -0,0 +1,185 @@
+// Deleted-but-recoverable sessions.
+//
+// "Delete forever" is the only irreversible thing this plugin does, and the one
+// mistake a user cannot undo. So a delete is a move, not an unlink: the
+// artifact directory and the projection-cache document are parked under
+// `$DSH_HOME/.archived-sessions-quarantine/<id>/` together with a `meta.json`
+// describing where they came from. `forever` skips the park and unlinks.
+//
+// The quarantine lives under `$DSH_HOME`, beside `sessions/`, so the move is a
+// same-volume `rename`; the copy fallback only exists for a `DSH_HOME` that
+// spans volumes.
+
+import { constants } from "node:fs";
+import { access, cp, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import {
+  directorySize,
+  projectionCacheFile,
+  quarantineArtifactDir,
+  quarantineCacheFile,
+  quarantineEntry,
+  quarantineMetaFile,
+  quarantineRoot,
+  sessionsRoot,
+} from "./paths.js";
+
+async function exists(path) {
+  try {
+    await access(path, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Move one path, falling back to copy+unlink when the two ends are on different volumes. */
+async function movePath(from, to) {
+  await mkdir(dirname(to), { recursive: true });
+  try {
+    await rename(from, to);
+    return "rename";
+  } catch (error) {
+    if (error?.code !== "EXDEV") throw error;
+    await cp(from, to, { recursive: true, force: true, preserveTimestamps: true });
+    await rm(from, { recursive: true, force: true });
+    return "copy";
+  }
+}
+
+/** Park one session's artifacts + cache document; returns what was moved. */
+export async function quarantineSession(sessionId, { dirs, cacheFile, meta }) {
+  const root = quarantineEntry(sessionId);
+  let bytes = 0;
+  for (const dir of dirs) bytes += await directorySize(dir);
+  // The projection document is state too: a delete that frees it should say so.
+  if (cacheFile !== undefined && (await exists(cacheFile))) {
+    try {
+      bytes += (await stat(cacheFile)).size;
+    } catch {
+      // A vanished document contributes nothing to the estimate.
+    }
+  }
+  await mkdir(root, { recursive: true });
+
+  const moved = { directories: 0, bytes, cache: false };
+  for (const dir of dirs) {
+    await movePath(dir, quarantineArtifactDir(sessionId));
+    moved.directories += 1;
+  }
+  if (cacheFile !== undefined && (await exists(cacheFile))) {
+    await movePath(cacheFile, quarantineCacheFile(sessionId));
+    moved.cache = true;
+  }
+  await writeFile(
+    quarantineMetaFile(sessionId),
+    JSON.stringify({ ...meta, sessionId, bytes, directories: moved.directories, cache: moved.cache }, null, 2),
+    "utf8",
+  );
+  return moved;
+}
+
+/**
+ * The quarantine as the panel sees it. Entries whose payload vanished (a user
+ * cleaned the directory by hand) are dropped rather than reported as broken.
+ */
+export async function listQuarantine() {
+  const entries = [];
+  let children;
+  try {
+    children = await readdir(quarantineRoot(), { withFileTypes: true });
+  } catch {
+    return entries;
+  }
+  for (const child of children) {
+    if (!child.isDirectory()) continue;
+    const sessionId = child.name;
+    let meta = null;
+    try {
+      meta = JSON.parse(await readFile(quarantineMetaFile(sessionId), "utf8"));
+    } catch {
+      meta = null;
+    }
+    const hasArtifact = await exists(quarantineArtifactDir(sessionId));
+    const hasCache = await exists(quarantineCacheFile(sessionId));
+    if (!hasArtifact && !hasCache) continue;
+    entries.push({
+      id: sessionId,
+      deletedAt: typeof meta?.deletedAt === "number" ? meta.deletedAt : null,
+      title: typeof meta?.title === "string" ? meta.title : null,
+      cwd: typeof meta?.cwd === "string" ? meta.cwd : null,
+      workspaceDir: typeof meta?.workspaceDir === "string" ? meta.workspaceDir : null,
+      bytes: typeof meta?.bytes === "number" ? meta.bytes : await directorySize(quarantineArtifactDir(sessionId)),
+    });
+  }
+  entries.sort((a, b) => (b.deletedAt ?? 0) - (a.deletedAt ?? 0));
+  return entries;
+}
+
+export async function quarantineEntryFor(sessionId) {
+  const entries = await listQuarantine();
+  return entries.find((entry) => entry.id === sessionId) ?? null;
+}
+
+/**
+ * Put a quarantined session back where it came from.
+ *
+ * @returns the restored location and whether it could be re-archived. A failed
+ * re-archive is not a failed restore: the session is back on disk and visible
+ * in the ordinary session list, which is strictly better than losing it.
+ */
+export async function restoreSession(ctx, sessionId, entry) {
+  const root = quarantineEntry(sessionId);
+  const artifact = quarantineArtifactDir(sessionId);
+  const cache = quarantineCacheFile(sessionId);
+  const restored = { directories: 0, cache: false, rearchived: false };
+
+  const target = entry.workspaceDir !== null ? join(entry.workspaceDir, sessionId) : null;
+  if (await exists(artifact)) {
+    if (target === null) throw new Error("quarantine metadata has no workspaceDir");
+    await mkdir(dirname(target), { recursive: true });
+    await movePath(artifact, target);
+    restored.directories = 1;
+  }
+  if (await exists(cache)) {
+    await movePath(cache, projectionCacheFile(sessionId));
+    restored.cache = true;
+  }
+  await rm(root, { recursive: true, force: true });
+
+  try {
+    await ctx.workspaceRegistry?.archiveSession?.(sessionId, {});
+    restored.rearchived = true;
+  } catch (error) {
+    ctx.logger?.warn?.(`[dsh-archived] restore ${sessionId}: re-archive failed:`, error);
+  }
+  return restored;
+}
+
+/** Unlink one quarantined session for good. */
+export async function purgeQuarantineEntry(sessionId) {
+  const bytes = await directorySize(quarantineEntry(sessionId));
+  await rm(quarantineEntry(sessionId), { recursive: true, force: true });
+  return bytes;
+}
+
+/** Drop quarantine entries older than `maxAgeMs`; returns the ids dropped. */
+export async function expireQuarantine(maxAgeMs, now = Date.now()) {
+  const dropped = [];
+  for (const entry of await listQuarantine()) {
+    if (entry.deletedAt === null) continue;
+    if (now - entry.deletedAt < maxAgeMs) continue;
+    await purgeQuarantineEntry(entry.id);
+    dropped.push(entry.id);
+  }
+  return dropped;
+}
+
+/** Workspace bucket directory names currently on disk, for orphan reporting. */
+export async function sessionBuckets() {
+  try {
+    return (await readdir(sessionsRoot(), { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}

package/lib/host/trust.js

@@ -0,0 +1,68 @@
+// Request trust for the destructive routes.
+//
+// Loopback, marker-header, same-origin. The routes are destructive, so they
+// refuse anything that is not this browser talking to this server.
+//
+// `Origin` is authoritative when present, but browsers omit it on same-origin
+// GETs — so that case falls back to Fetch Metadata's `sec-fetch-site`, which a
+// cross-site caller cannot forge. A request with neither signal is refused.
+
+export const HEADER = "x-dsh-archived";
+
+export function header(request, key) {
+  const value = request.headers?.[key];
+  return Array.isArray(value) ? value[0] : value;
+}
+
+export function isLoopbackAddress(value) {
+  const address = String(value || "").toLowerCase().replace(/^\[|\]$/g, "");
+  return (
+    address === "localhost" ||
+    address === "localhost." ||
+    address === "::1" ||
+    address.startsWith("127.") ||
+    address.startsWith("::ffff:127.")
+  );
+}
+
+export function isTrustedRequest(request) {
+  if (header(request, HEADER) !== "1") return false;
+  if (!isLoopbackAddress(request.socket?.remoteAddress)) return false;
+  const site = header(request, "sec-fetch-site");
+  if (site !== undefined && site !== "same-origin") return false;
+  const host = header(request, "host");
+  if (!host) return false;
+  const origin = header(request, "origin");
+  if (origin === undefined) return site === "same-origin";
+  try {
+    const url = new URL(origin);
+    return (
+      (url.protocol === "http:" || url.protocol === "https:") &&
+      isLoopbackAddress(url.hostname) &&
+      url.host === host
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function json(response, statusCode, value) {
+  response.writeHead(statusCode, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  response.end(JSON.stringify(value));
+}
+
+/** Short operator-facing cause for a 500 body; these routes are loopback-only. */
+export function failureDetail(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.slice(0, 200);
+}
+
+export async function readJsonBody(request) {
+  const chunks = [];
+  for await (const chunk of request) chunks.push(chunk);
+  if (chunks.length === 0) return {};
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}