@heixui/dsh-session-suite 0.0.0-stage → 0.3.0

package/cordis.patch.yml

@@ -0,0 +1,77 @@
+# dsh-session-suite — session checkpoints, rewind, delete, share, and long-term memory.
+#
+# One row: the Host half registers the authenticated Fetch route, turns the
+# per-turn workspace snapshots, and runs the long-term memory engine; the Client
+# half adds the sidebar rows, the message actions, and the settings pages.
+- insert:
+    - id: session-suite
+      name: dsh-session-suite
+      config:
+        # ---------- session snapshots ----------
+        # Automatic checkpoints kept per session (locked ones do not count).
+        keep: 10
+        # Capture a workspace checkpoint when each turn finishes.
+        autoCheckpoint: true
+        # Files larger than this are skipped.
+        maxFileBytes: 2097152
+        # Hard cap on tracked files per checkpoint.
+        maxFiles: 4000
+        # How often expired undo bundles are swept.
+        sweepIntervalMs: 300000
+        # Extra ignore patterns on top of the built-in list.
+        ignore: []
+
+        # ---------- output hygiene ----------
+        # Strip the four internal step tags from streamed text/reasoning before
+        # they can reach the assistant message, the transcript, share exports,
+        # or a later replayed request. Host-side `llm/stream` filter; set false
+        # to pass model output through untouched.
+        stripStepTags: true
+
+        # ---------- long-term memory ----------
+        # Turn the whole memory engine on or off.
+        longTermMemory: true
+        # Model chain used for implicit extraction (one cheap call per turn).
+        # Tried in order until one answers; a 429 or an unreachable provider just
+        # moves on to the next entry. All of these are free tiers.
+        memoryModels:
+          - provider: agnes
+            model: agnes-3.0-flash
+          - provider: agnes-backup
+            model: agnes-3.0-flash
+          - provider: zhipu
+            model: glm-4.7-flash
+          - provider: siliconflow
+            model: Qwen/Qwen2.5-7B-Instruct
+        # How many memories one recall may inject into the prompt. This is a
+        # ceiling, not a quota: a weak question injects fewer, because filling
+        # the budget would claim six memories are relevant when the evidence
+        # says otherwise.
+        recallLimit: 6
+        # How many of the most important memories ride along regardless of the
+        # question. Without a resident layer, an ordinary follow-up like "继续"
+        # shares no vocabulary with any memory and a strict relevance filter
+        # would inject nothing at all, which reads as the feature being broken.
+        residentLimit: 2
+        # Use the general-purpose Chinese word list as a third retrieval route.
+        # It fixes character-bigram over-matching across word boundaries; the
+        # ablation in tools/ablate-word-route.mjs shows it raises MRR without
+        # lowering recall@5. Set false to run the two lexical routes alone.
+        wordRoute: true
+        # BM25 term-frequency saturation and length normalisation, and the RRF
+        # smoothing constant. Defaults are the customary ones; lower bm25K1
+        # saturates repeated terms sooner, bm25B 0 disables length normalisation.
+        bm25K1: 1.5
+        bm25B: 0.75
+        rrfK: 60
+        # Similarity above which a new memory reinforces an existing one.
+        duplicateSimilarity: 0.82
+        # Similarity above which two memories may join one cluster.
+        clusterSimilarity: 0.5
+        # Cluster size that triggers compression into one summary.
+        clusterMinSize: 2
+        # Number of same-tag memories that triggers a rule-type abstraction.
+        ruleMinSize: 3
+        # Images inlined into a shared page, and the per-image ceiling.
+        imageBudget: 12
+        imageMaxBytes: 3145728

package/icon.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Session suite">
+  <defs>
+    <linearGradient id="suiteBg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#1f4fd8"/>
+      <stop offset="100%" stop-color="#4f8cff"/>
+    </linearGradient>
+  </defs>
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="url(#suiteBg)"/>
+  <g fill="none" stroke="#ffffff" stroke-linecap="round" stroke-width="3.4">
+    <path d="M45.5 32a13.5 13.5 0 1 1-4.2-9.8"/>
+    <path d="M42.6 15.4v7.9h-7.9"/>
+  </g>
+  <circle cx="32" cy="32" r="3.4" fill="#ffffff"/>
+  <g fill="#ffffff" opacity="0.55">
+    <circle cx="16.5" cy="47.5" r="2.1"/>
+    <circle cx="23.5" cy="51" r="2.1"/>
+    <circle cx="31" cy="52.5" r="2.1"/>
+  </g>
+</svg>

package/index.js

@@ -0,0 +1,211 @@
+/**
+ * dsh-session-suite — Host half.
+ *
+ * Registers, for the desktop/web profile:
+ *
+ * - incremental workspace checkpoints captured at the start of every turn;
+ * - the rollback operation (conversation prefix + files + memory, with an undo
+ *   bundle that expires after ten minutes);
+ * - permanent session deletion (log, projection cache, checkpoints, memory);
+ * - session sharing as Markdown / text / JSON;
+ * - a per-session memory ledger that participates in rollback;
+ * - the authenticated Fetch route the browser half talks to.
+ *
+ * The module intentionally depends on `node:` builtins only: a bundle installed
+ * into a profile is resolved from the profile, not from the DSH installation,
+ * so importing @deepseek-ai runtime packages would not resolve.
+ */
+
+import os from 'node:os'
+import path from 'node:path'
+import { API_PATH, createRoute } from './lib/api.js'
+import { CheckpointStore } from './lib/checkpoints.js'
+import { MemoryLedger } from './lib/memory.js'
+import { installMemory } from './lib/memory-host.js'
+import { SessionSuiteService } from './lib/service.js'
+import { stripStepTagsFromStream } from './lib/step-tag-filter.js'
+
+export const name = 'session-suite'
+
+/** The HTTP carrier is the only hard requirement; the rest degrade gracefully. */
+export const inject = ['connection']
+
+/**
+ * @param {any} ctx plugin context
+ * @param {any} [config] row config from cordis.patch.yml
+ */
+export function apply(ctx, config = {}) {
+  const log = (message, error) => {
+    if (error) ctx.logger?.warn?.(`[session-suite] ${message}`, error)
+    else ctx.logger?.info?.(`[session-suite] ${message}`)
+  }
+  const home = process.env.DSH_HOME ?? path.join(os.homedir(), '.dsh')
+  const root = path.join(home, 'storages', 'dsh-session-suite')
+  const store = new CheckpointStore({
+    root,
+    log,
+    ignores: Array.isArray(config.ignore) ? config.ignore.filter(item => typeof item === 'string') : [],
+  })
+  const memory = new MemoryLedger({ root })
+  const service = new SessionSuiteService({ ctx, root, store, memory, log, config })
+
+  // The HTTP route comes first and unconditionally: session delete, share, and
+  // rewind must keep working even if an optional integration below fails.
+  ctx.effect(
+    () => ctx.connection.fetch.register(createRoute(service, { log })),
+    'session-suite: http route',
+  )
+  log(`http route ready at ${API_PATH}`)
+
+  // Output hygiene: models occasionally emit the four internal step tags
+  // (`<发>` / `<执行>` / `<好>` / `<现在>`, U+003C + word + U+003E) as a long run
+  // inside an ordinary assistant reply. Left alone they land in the durable
+  // assistant message, the live transcript, share exports, and every later
+  // request that replays history. The `llm/stream` waterfall is the one layer
+  // that covers all of those at once: the filter removes the tags from token
+  // deltas and from the terminal block text the assembler persists. It is
+  // config-gated (`stripStepTags: false` disables it) and never rewrites any
+  // other angle-bracket text. A failure here is reported and skipped rather
+  // than taking the bundle down.
+  if (config.stripStepTags !== false) {
+    try {
+      ctx.effect(
+        () =>
+          ctx.on('llm/stream', (options, next) => {
+            const stream = next()
+            if (
+              stream === null ||
+              stream === undefined ||
+              typeof stream[Symbol.asyncIterator] !== 'function'
+            ) {
+              return stream
+            }
+            return stripStepTagsFromStream(stream)
+          }),
+        'session-suite: step tag filter',
+      )
+      log('step tag filter ready')
+    } catch (error) {
+      log('step tag filter could not be installed; continuing without it', error)
+    }
+  }
+
+  // Long-term memory: recall into the prompt, explicit writes, implicit
+  // suggestions, the `memory` tool, and its management surface. A failure here
+  // is reported and skipped rather than taking the whole bundle down.
+  if (config.longTermMemory !== false) {
+    try {
+      const installed = installMemory({ ctx, root, config, log })
+      service.longTerm = installed.engine
+      log('long-term memory engine ready')
+    } catch (error) {
+      log('long-term memory failed to install; continuing without it', error)
+    }
+  }
+
+  // One automatic checkpoint per turn, taken when the turn finishes: a snapshot
+  // then represents "the workspace after turn N", which is exactly the state a
+  // rewind to turn N must restore.
+  if (config.autoCheckpoint !== false) {
+    ctx.effect(
+      () =>
+        ctx.on('session/event', (session, event) => {
+          if (!event || (event.type !== 'turn/end' && event.type !== 'turn/start')) return
+          // Subagent children are not conversations a user can open. Capturing
+          // their workspace state produces snapshot directories nobody can
+          // reach from the panel — the list already hides them — and costs a
+          // full tree walk on every one of their turns.
+          if (session?.header?.origin === 'subagent' || session?.origin === 'subagent') return
+          const sessionId = session?.id
+          if (typeof sessionId !== 'string') return
+          const cwd = resolveCwd(ctx, session)
+          if (!cwd) return
+          const limits = {
+            keep: numberOr(config.keep, 10),
+            maxFileBytes: numberOr(config.maxFileBytes, undefined),
+            maxFiles: numberOr(config.maxFiles, undefined),
+          }
+          if (event.type === 'turn/end') {
+            const turn = typeof event.data?.turn === 'number' ? event.data.turn : undefined
+            void store
+              .capture({
+                sessionId,
+                cwd,
+                seq: typeof event.seq === 'number' ? event.seq : undefined,
+                turn,
+                phase: 'end',
+                kind: 'auto',
+                label: `after turn ${turn ?? '?'}`,
+                limits,
+              })
+              .catch(error => log(`automatic checkpoint failed for ${sessionId}`, error))
+            return
+          }
+          // Baseline: the state this session started from, captured before the
+          // first turn touches anything. Rewinding to the very first prompt needs
+          // it, and it is taken once per session.
+          const startTurn = typeof event.data?.turn === 'number' ? event.data.turn : 1
+          void store
+            .list(sessionId)
+            .then(list => {
+              if (list.length > 0) return undefined
+              return store.capture({
+                sessionId,
+                cwd,
+                seq: typeof event.seq === 'number' ? event.seq : undefined,
+                turn: startTurn - 1,
+                phase: 'end',
+                kind: 'auto',
+                label: 'baseline',
+                limits,
+              })
+            })
+            .catch(error => log(`baseline checkpoint failed for ${sessionId}`, error))
+        }),
+      'session-suite: turn checkpoints',
+    )
+  }
+
+  // Expired undo bundles and the per-session budget are swept on a slow timer.
+  const sweepMs = numberOr(config.sweepIntervalMs, 5 * 60 * 1000)
+  if (sweepMs > 0) {
+    ctx.effect(() => {
+      const timer = setInterval(() => {
+        void service.sweep().catch(error => log('sweep failed', error))
+      }, sweepMs)
+      timer.unref?.()
+      return () => clearInterval(timer)
+    }, 'session-suite: sweep timer')
+  }
+
+  // A cold start should not leave expired bundles behind.
+  void service.sweep().catch(error => log('initial sweep failed', error))
+}
+
+/**
+ * @param {any} ctx plugin context
+ * @param {any} session live session
+ * @returns {string | undefined} workspace directory
+ */
+function resolveCwd(ctx, session) {
+  const workingDirectory = ctx.get('workingDirectory')
+  if (workingDirectory?.get) {
+    try {
+      const value = workingDirectory.get(session)
+      if (typeof value === 'string' && value.length > 0) return value
+    } catch {
+      // fall through to the session header
+    }
+  }
+  const meta = session?.meta ?? session?.header
+  return typeof meta?.cwd === 'string' ? meta.cwd : undefined
+}
+
+/**
+ * @param {unknown} value candidate
+ * @param {number | undefined} fallback default
+ * @returns {number | undefined} number
+ */
+function numberOr(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback
+}

package/lib/api.js

@@ -0,0 +1,387 @@
+/**
+ * The HTTP surface of dsh-session-suite.
+ *
+ * Connection mounts this exact Fetch route behind its Host/Origin and
+ * browser-session checks (the same carrier the shipped session-log export
+ * uses), so the browser half never needs a bespoke RPC channel: it posts JSON
+ * to a document-relative `api/session-suite` URL.
+ */
+
+/** Absolute path Connection registers. */
+export const API_PATH = '/api/session-suite'
+
+const MAX_BODY_BYTES = 256 * 1024
+
+/**
+ * @param {import('./service.js').SessionSuiteService} service suite operations
+ * @param {{ log: (message: string, error?: unknown) => void }} deps dependencies
+ * @returns {{ path: string, methods: readonly string[], requestBody: string, fetch: (request: Request) => Promise<Response> }} route
+ */
+export function createRoute(service, deps) {
+  return {
+    path: API_PATH,
+    methods: ['GET', 'POST'],
+    requestBody: 'buffered',
+    fetch: request => handle(service, deps, request),
+  }
+}
+
+/**
+ * @param {import('./service.js').SessionSuiteService} service suite operations
+ * @param {{ log: (message: string, error?: unknown) => void }} deps dependencies
+ * @param {Request} request inbound request
+ * @returns {Promise<Response>} response
+ */
+async function handle(service, deps, request) {
+  try {
+    // `await` is load-bearing, not stylistic. `respond` is async, so returning
+    // its promise without awaiting lets every rejection escape this try/catch:
+    // a service error would surface as an unhandled rejection instead of a 400,
+    // and the client would lose `error.code` — which is what it matches on to
+    // tell "this session is running" apart from a generic failure.
+    if (request.method === 'GET' || request.method === 'HEAD') {
+      const url = new URL(request.url)
+      const action = url.searchParams.get('action') ?? 'ping'
+      return await respond(service, deps, action, paramsOf(url.searchParams))
+    }
+    if (request.method !== 'POST') return json({ ok: false, error: 'method not allowed' }, 405)
+    const body = await readJsonBody(request)
+    const action = typeof body?.action === 'string' ? body.action : 'ping'
+    return await respond(service, deps, action, body ?? {})
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    deps.log(`request failed: ${message}`, error)
+    return json({ ok: false, error: message, code: /** @type {any} */ (error)?.code }, 400)
+  }
+}
+
+/**
+ * @param {import('./service.js').SessionSuiteService} service suite operations
+ * @param {{ log: (message: string, error?: unknown) => void }} deps dependencies
+ * @param {string} action action name
+ * @param {any} input request payload
+ * @returns {Promise<Response>} response
+ */
+async function respond(service, deps, action, input) {
+  switch (action) {
+    case 'ping':
+      return json({ ok: true, data: { ready: true, version: 1 } })
+    case 'list':
+      return json({ ok: true, data: await service.listSessions() })
+    case 'detail':
+      return json({ ok: true, data: await service.detail(requireSession(input)) })
+    case 'capture':
+      return json({ ok: true, data: await service.capture(requireSession(input), { label: input.label, kind: 'manual' }) })
+    case 'restore':
+      return json({ ok: true, data: await service.restoreCheckpoint(requireSession(input), requireCheckpoint(input)) })
+    case 'rollback':
+      return json({
+        ok: true,
+        data: await service.rollback({
+          sessionId: requireSession(input),
+          messageId: typeof input.messageId === 'string' ? input.messageId : undefined,
+          seq: numberOrUndefined(input.seq),
+          turn: numberOrUndefined(input.turn),
+        }),
+      })
+    case 'deleteMessage':
+      return json({
+        ok: true,
+        data: await service.deleteMessage({
+          sessionId: requireSession(input),
+          messageId: requireText(input, 'messageId'),
+        }),
+      })
+    case 'resendTurn.preview':
+      return json({
+        ok: true,
+        data: await service.previewResend({
+          sessionId: requireSession(input),
+          turn: numberOrUndefined(input.turn),
+          messageId: typeof input.messageId === 'string' ? input.messageId : undefined,
+        }),
+      })
+    case 'resendTurn':
+      return json({
+        ok: true,
+        data: await service.resendTurn({
+          sessionId: requireSession(input),
+          turn: numberOrUndefined(input.turn),
+          messageId: typeof input.messageId === 'string' ? input.messageId : undefined,
+          mode: input.mode === 'stage' ? 'stage' : 'retry',
+          text: typeof input.text === 'string' ? input.text : undefined,
+        }),
+      })
+    case 'deleteSegment':
+      return json({
+        ok: true,
+        data: await service.deleteSegment({
+          sessionId: requireSession(input),
+          startSeq: Number(input.startSeq),
+        }),
+      })
+    case 'outline':
+      return json({ ok: true, data: await service.outline(requireSession(input)) })
+    case 'removeCheckpoint':
+      return json({
+        ok: true,
+        data: await service.store.removeCheckpoint(requireSession(input), requireCheckpoint(input)),
+      })
+    case 'setLocked':
+      return json({
+        ok: true,
+        data: await service.store.setLocked(requireSession(input), requireCheckpoint(input), input.locked === true),
+      })
+    case 'undo':
+      return json({ ok: true, data: await service.undo(requireText(input, 'undoId')) })
+    case 'previewDelete':
+      return json({ ok: true, data: await service.previewDelete(requireSession(input)) })
+    case 'deleteSessions':
+      return json({
+        ok: true,
+        data: await service.deleteSessions(
+          Array.isArray(input.sessionIds) ? input.sessionIds : [],
+          { cascade: input.cascade !== false },
+        ),
+      })
+    case 'deleteSession':
+      return json({
+        ok: true,
+        data: await service.deleteSession(requireSession(input), { cascade: input.cascade !== false }),
+      })
+    case 'export': {
+      const ranges = Array.isArray(input.ranges)
+        ? input.ranges
+            .map(range => ({ startSeq: Number(range?.startSeq), endSeq: Number(range?.endSeq) }))
+            .filter(range => Number.isFinite(range.startSeq) && Number.isFinite(range.endSeq))
+        : undefined
+      const exported = await service.share({
+        sessionId: requireSession(input),
+        format:
+          input.format === 'json' || input.format === 'txt' || input.format === 'html' || input.format === 'blocks'
+            ? input.format
+            : 'md',
+        ranges: ranges && ranges.length > 0 ? ranges : undefined,
+        mode: input.mode === 'all' ? 'all' : 'final',
+      })
+      return json({ ok: true, data: exported })
+    }
+    case 'share': {
+      const ranges = Array.isArray(input.ranges)
+        ? input.ranges
+            .map(range => ({ startSeq: Number(range?.startSeq), endSeq: Number(range?.endSeq) }))
+            .filter(range => Number.isFinite(range.startSeq) && Number.isFinite(range.endSeq))
+        : undefined
+      const exported = await service.share({
+        sessionId: requireSession(input),
+        format:
+          input.format === 'json' || input.format === 'txt' || input.format === 'html' || input.format === 'blocks'
+            ? input.format
+            : 'md',
+        ranges: ranges && ranges.length > 0 ? ranges : undefined,
+        mode: input.mode === 'all' ? 'all' : 'final',
+      })
+      const download = input.download === true || input.download === '1' || input.download === 'true'
+      return new Response(exported.body, {
+        status: 200,
+        headers: {
+          'content-type': exported.contentType,
+          'cache-control': 'no-store',
+          ...(download
+            ? { 'content-disposition': `attachment; filename="${escapeFileName(exported.fileName)}"` }
+            : {}),
+        },
+      })
+    }
+    case 'memory.list':
+      return json({ ok: true, data: await service.memory.list(requireSession(input)) })
+    case 'memory.add':
+      return json({
+        ok: true,
+        data: await service.memory.add(requireSession(input), {
+          text: requireText(input, 'text'),
+          tags: input.tags,
+          seq: numberOrUndefined(input.seq),
+          turn: numberOrUndefined(input.turn),
+          source: 'user',
+        }),
+      })
+    case 'memory.update':
+      return json({
+        ok: true,
+        data: await service.memory.update(requireSession(input), requireText(input, 'id'), {
+          text: input.text,
+          tags: input.tags,
+          pinned: input.pinned,
+        }),
+      })
+    case 'memory.remove':
+      return json({ ok: true, data: { removed: await service.memory.remove(requireSession(input), requireText(input, 'id')) } })
+    case 'sweep':
+      await service.sweep()
+      return json({ ok: true, data: { swept: true } })
+    // ------------------------------------------------------- long-term memory
+    case 'longterm.list':
+      return json({
+        ok: true,
+        data: await service.longTerm.list({
+          cwd: workspaceOf(input),
+          scope: scopeOf(input),
+          tag: typeof input.tag === 'string' ? input.tag : undefined,
+          sinceDays: numberOrUndefined(input.sinceDays),
+        }),
+      })
+    case 'longterm.remember':
+      return json({
+        ok: true,
+        data: await service.longTerm.remember({
+          scope: scopeOf(input) === 'global' ? 'global' : 'workspace',
+          cwd: workspaceOf(input),
+          text: requireText(input, 'text'),
+          tags: Array.isArray(input.tags) ? input.tags : undefined,
+          affect: typeof input.affect === 'number' ? input.affect : undefined,
+          source: 'user',
+        }),
+      })
+    case 'longterm.update':
+      return json({
+        ok: true,
+        data: await service.longTerm.update({
+          scope: scopeOf(input),
+          cwd: workspaceOf(input),
+          id: requireText(input, 'id'),
+          patch: {
+            frozen: typeof input.frozen === 'boolean' ? input.frozen : undefined,
+            touch: input.touch === true,
+            text: typeof input.text === 'string' ? input.text : undefined,
+          },
+        }),
+      })
+    case 'longterm.remove':
+      return json({
+        ok: true,
+        data: await service.longTerm.remove({
+          scope: scopeOf(input),
+          cwd: workspaceOf(input),
+          id: typeof input.id === 'string' ? input.id : undefined,
+        }),
+      })
+    case 'longterm.recall':
+      return json({
+        ok: true,
+        data: await service.longTerm.recall({
+          cwd: workspaceOf(input),
+          query: typeof input.query === 'string' ? input.query : '',
+          limit: numberOrUndefined(input.limit),
+          touch: false,
+        }),
+      })
+    case 'longterm.explain':
+      // Answer "which memories would this question pull in, and why were the
+      // rest dropped" without touching anything: `touch: false` keeps the access
+      // counters and decay clocks exactly as they were.
+      return json({
+        ok: true,
+        data: await service.longTerm.select({
+          cwd: workspaceOf(input),
+          query: typeof input.query === 'string' ? input.query : '',
+          limit: numberOrUndefined(input.limit),
+          touch: false,
+        }),
+      })
+    case 'longterm.pending':
+      return json({ ok: true, data: await service.longTerm.pending(workspaceOf(input)) })
+    case 'longterm.settle':
+      return json({
+        ok: true,
+        data: await service.longTerm.settle(requireText(input, 'id'), input.accept === true),
+      })
+    case 'longterm.maintain':
+      return json({ ok: true, data: await service.longTerm.maintain(workspaceOf(input)) })
+    case 'longterm.status':
+      return json({ ok: true, data: await service.longTerm.status() })
+    case 'longterm.workspaces':
+      return json({ ok: true, data: await service.longTerm.workspaces() })
+    case 'longterm.settings':
+      return json(
+        input.patch
+          ? { ok: true, data: await service.longTerm.updateSettings(input.patch) }
+          : { ok: true, data: await service.longTerm.settings() },
+      )
+    case 'longterm.export':
+      return json({ ok: true, data: await service.longTerm.export({ cwd: workspaceOf(input) }) })
+    default:
+      deps.log(`unknown action ${action}`)
+      return json({ ok: false, error: `unknown action: ${action}` }, 400)
+  }
+}
+
+/**
+ * @param {Request} request inbound request
+ * @returns {Promise<any>} parsed JSON body
+ */
+async function readJsonBody(request) {
+  const text = await request.text()
+  if (text.length > MAX_BODY_BYTES) throw new Error('request body is too large')
+  if (!text.trim()) return {}
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new Error('request body is not valid JSON')
+  }
+}
+
+/** @param {URLSearchParams} search query */
+function paramsOf(search) {
+  const out = {}
+  for (const [key, value] of search.entries()) out[key] = value
+  return out
+}
+
+/** @param {any} input payload @returns {string | undefined} workspace directory */
+function workspaceOf(input) {
+  return typeof input?.cwd === 'string' && input.cwd.length > 0 ? input.cwd : undefined
+}
+
+/** @param {any} input payload @returns {'global' | 'workspace' | undefined} memory scope */
+function scopeOf(input) {
+  if (input?.scope === 'global') return 'global'
+  if (input?.scope === 'workspace') return 'workspace'
+  return undefined
+}
+
+/** @param {any} input payload @param {string} field field name @returns {string} value */
+function requireText(input, field) {
+  const value = input?.[field]
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`${field} is required`)
+  return value
+}
+
+/** @param {any} input payload @returns {string} session id */
+function requireSession(input) {
+  return requireText(input, 'sessionId')
+}
+
+/** @param {any} input payload @returns {string} checkpoint id */
+function requireCheckpoint(input) {
+  return requireText(input, 'checkpointId')
+}
+
+/** @param {any} value candidate @returns {number | undefined} number */
+function numberOrUndefined(value) {
+  const number = Number(value)
+  return Number.isFinite(number) ? number : undefined
+}
+
+/** @param {string} name file name @returns {string} header-safe name */
+function escapeFileName(name) {
+  return name.replace(/["\r\n]/g, '_')
+}
+
+/** @param {unknown} payload response body @param {number} [status] status */
+function json(payload, status = 200) {
+  return new Response(JSON.stringify(payload), {
+    status,
+    headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+  })
+}