dsh-live-trace 0.1.0

package/lib/paths.js

@@ -0,0 +1,66 @@
+/**
+ * Path resolution shared by the Host plugin and the standalone viewer.
+ *
+ * Both halves must agree on where the plugin publishes its sockets and its
+ * server registry, so resolution lives here rather than in either half.
+ *
+ * @module dsh-live-trace/paths
+ */
+
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/** Environment variable that overrides the DeepSeek Harness home. */
+export const DSH_HOME_ENV = 'DSH_HOME'
+
+/**
+ * Environment variable that overrides the runtime directory.
+ *
+ * The plugin writes its sockets and server registry here and the viewer reads
+ * them from here. Setting it on both sides lets a test, a sandboxed shell, or a
+ * second Harness home keep its live-trace state isolated without touching
+ * `$DSH_HOME`.
+ */
+export const RUNTIME_DIR_ENV = 'DSH_LIVE_TRACE_DIR'
+
+/** Expand `~`, `~/`, and `~\` against the operating-system home. */
+export function expandHomePath(path) {
+  if (path === '~') return homedir()
+  if (path.startsWith('~/') || path.startsWith('~\\')) return join(homedir(), path.slice(2))
+  return path
+}
+
+/**
+ * Resolve the Harness home with the same precedence the Harness itself uses:
+ * `$DSH_HOME`, then `~/.dsh`. A blank override counts as unset.
+ */
+export function resolveDshHome(env = process.env) {
+  const configured = env[DSH_HOME_ENV]
+  if (typeof configured === 'string' && configured.trim().length > 0) {
+    return resolve(expandHomePath(configured.trim()))
+  }
+  return join(homedir(), '.dsh')
+}
+
+/**
+ * Resolve the directory holding live-trace runtime state.
+ * @param {Record<string, string | undefined>} [env]
+ * @returns {string} absolute runtime directory (not necessarily created yet).
+ */
+export function resolveRuntimeDir(env = process.env) {
+  const configured = env[RUNTIME_DIR_ENV]
+  if (typeof configured === 'string' && configured.trim().length > 0) {
+    return resolve(expandHomePath(configured.trim()))
+  }
+  return join(resolveDshHome(env), 'live-trace')
+}
+
+/** Subdirectory holding one socket file per running Harness process. */
+export function socketsDir(runtimeDir) {
+  return join(runtimeDir, 'sockets')
+}
+
+/** Subdirectory holding one server-registry JSON record per running Harness process. */
+export function serversDir(runtimeDir) {
+  return join(runtimeDir, 'servers')
+}

package/lib/protocol.js

@@ -0,0 +1,115 @@
+/**
+ * The wire protocol between the Host observer plugin and the standalone
+ * `dsh-live-trace` viewer.
+ *
+ * Transport is newline-delimited JSON over a Unix domain socket. Every record
+ * is a plain JSON object with a `v` (protocol version) and a `kind`. The
+ * viewer treats unknown kinds as forward-compatible noise, and the plugin
+ * ignores unknown client kinds: neither side can break the other by being
+ * newer.
+ *
+ * @module dsh-live-trace/protocol
+ */
+
+/** Protocol version carried on every record in both directions. */
+export const PROTOCOL_VERSION = 1
+
+/** Record kinds the plugin sends to a viewer. */
+export const SERVER_KIND = {
+  /** First record on every connection: server identity, sessions, backlog policy. */
+  HELLO: 'hello',
+  /** The full session list changed (a session was created or disposed). */
+  SESSIONS: 'sessions',
+  /** One normalized trace entry for the selected session. */
+  ENTRY: 'entry',
+  /** Coalesced live streaming text for the selected session. */
+  STREAM: 'stream',
+  /** The live stream for the selected session settled or was abandoned. */
+  STREAM_END: 'stream-end',
+  /** Liveness/status change for the selected session. */
+  STATUS: 'status',
+  /** Cumulative token accounting for the selected session. */
+  USAGE: 'usage',
+  /** The session's aggregated file changes, one entry per touched path. */
+  EDITS: 'edits',
+  /** Periodic keepalive; carries server clock and connection count. */
+  HEARTBEAT: 'heartbeat',
+  /** A protocol-level problem the viewer should surface. */
+  ERROR: 'error'
+}
+
+/** Record kinds a viewer sends to the plugin. */
+export const CLIENT_KIND = {
+  /** Bind to a session id, or to the server's current default when omitted. */
+  SELECT: 'select',
+  /** Ask for the retained backlog of the bound session. */
+  REPLAY: 'replay',
+  /** Application-level ping; the plugin answers with a heartbeat. */
+  PING: 'ping'
+}
+
+/** How many normalized entries a viewer may request in one replay. */
+export const MAX_REPLAY_ENTRIES = 5000
+
+/** Longest single NDJSON line either side will buffer before failing the connection. */
+export const MAX_LINE_BYTES = 8 * 1024 * 1024
+
+/**
+ * Serialize one record as an NDJSON line.
+ * @param {object} record
+ * @returns {string}
+ */
+export function encodeRecord(record) {
+  return `${JSON.stringify(record)}\n`
+}
+
+/**
+ * Build an incremental NDJSON decoder.
+ *
+ * Sockets deliver arbitrary byte splits, so the decoder buffers until it sees a
+ * newline and rejects a single over-long line instead of growing without bound.
+ * @returns {{ push(chunk: string | Buffer): object[], pending(): number }}
+ */
+export function createLineDecoder() {
+  let buffer = ''
+  return {
+    push(chunk) {
+      buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8')
+      const out = []
+      let index = buffer.indexOf('\n')
+      while (index !== -1) {
+        const line = buffer.slice(0, index)
+        buffer = buffer.slice(index + 1)
+        const trimmed = line.endsWith('\r') ? line.slice(0, -1) : line
+        if (trimmed.trim().length > 0) {
+          let parsed
+          try {
+            parsed = JSON.parse(trimmed)
+          } catch {
+            throw new Error(`dsh-live-trace: malformed JSON record (${trimmed.length} bytes)`)
+          }
+          out.push(parsed)
+        }
+        index = buffer.indexOf('\n')
+      }
+      if (buffer.length > MAX_LINE_BYTES) {
+        buffer = ''
+        throw new Error(`dsh-live-trace: record exceeded ${MAX_LINE_BYTES} bytes`)
+      }
+      return out
+    },
+    pending() {
+      return buffer.length
+    }
+  }
+}
+
+/** @returns {boolean} whether a decoded record is one this module understands. */
+export function isKnownRecord(record, kinds) {
+  return (
+    record !== null &&
+    typeof record === 'object' &&
+    typeof record.kind === 'string' &&
+    Object.values(kinds).includes(record.kind)
+  )
+}

package/lib/registry.js

@@ -0,0 +1,232 @@
+/**
+ * Discovery registry for running Harness processes that host the observer.
+ *
+ * The plugin owns one socket per process, but a viewer starts with no idea
+ * which process or socket to use. Each plugin instance therefore publishes a
+ * small JSON record (its pid, socket path, working directory, and session
+ * list) and refreshes a heartbeat; the viewer scans that directory, drops dead
+ * processes, and picks the best match.
+ *
+ * @module dsh-live-trace/registry
+ */
+
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { PROTOCOL_VERSION } from './protocol.js'
+import { serversDir } from './paths.js'
+
+/** A record older than this (by heartbeat) is treated as abandoned. */
+export const STALE_HEARTBEAT_MS = 60_000
+
+/** Registry records are tiny; anything larger is corruption. */
+const MAX_RECORD_BYTES = 1024 * 1024
+
+/**
+ * @param {string} dir servers directory
+ * @param {number} pid
+ * @returns {string} absolute path of one process's registry record
+ */
+export function serverRecordPath(dir, pid) {
+  return join(dir, `${pid}.json`)
+}
+
+/**
+ * @param {string} dir servers directory
+ * @param {object} record
+ * @returns {string} the path written
+ */
+export function writeServerRecord(dir, record) {
+  mkdirSync(dir, { recursive: true })
+  const target = serverRecordPath(dir, record.pid)
+  const temp = `${target}.${process.pid}.tmp`
+  writeFileSync(temp, `${JSON.stringify({ ...record, v: PROTOCOL_VERSION })}\n`, { mode: 0o600 })
+  renameSync(temp, target)
+  return target
+}
+
+/**
+ * @param {string} dir servers directory
+ * @param {number} pid
+ */
+export function removeServerRecord(dir, pid) {
+  rmSync(serverRecordPath(dir, pid), { force: true })
+}
+
+/**
+ * Remove a registry record only when it still describes `socket`.
+ *
+ * A reloaded plugin generation and a late disposer of the previous generation
+ * share one pid, so an unconditional delete could remove the live generation's
+ * record.
+ *
+ * @param {string} dir servers directory
+ * @param {number} pid
+ * @param {string} socket socket path the caller owns
+ * @returns {boolean} whether a record was removed
+ */
+export function removeServerRecordIfOwner(dir, pid, socket) {
+  const path = serverRecordPath(dir, pid)
+  try {
+    const record = JSON.parse(readFileSync(path, 'utf8'))
+    if (record !== null && typeof record === 'object' && record.socket !== socket) return false
+  } catch {
+    return false
+  }
+  rmSync(path, { force: true })
+  return true
+}
+
+/**
+ * Read every parseable registry record from a directory.
+ * @param {string} dir servers directory
+ * @returns {object[]}
+ */
+export function readServerRecords(dir) {
+  let names
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return []
+  }
+  const records = []
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue
+    const path = join(dir, name)
+    try {
+      const raw = readFileSync(path, 'utf8')
+      if (raw.length > MAX_RECORD_BYTES) continue
+      const parsed = JSON.parse(raw)
+      if (parsed !== null && typeof parsed === 'object' && typeof parsed.pid === 'number') records.push(parsed)
+    } catch {
+      /* a half-written or corrupt record is not a reason to fail discovery */
+    }
+  }
+  return records
+}
+
+/**
+ * @param {number} pid
+ * @returns {boolean} whether the process exists and is signalable by us.
+ */
+export function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // EPERM means the process exists but belongs to another user.
+    return error?.code === 'EPERM'
+  }
+}
+
+/**
+ * Drop records whose process is gone and whose heartbeat has gone stale.
+ *
+ * A fresh heartbeat is trusted unconditionally, because only a live writer can
+ * refresh it. Liveness probing alone is not enough: a viewer running in a
+ * different PID namespace than the Harness — a container, WSL, or a sandboxed
+ * shell — cannot signal the Harness process, and treating that as "dead" would
+ * let a read-only discovery command delete a live server's record.
+ *
+ * @param {string} dir servers directory
+ * @param {{ now?: number, staleMs?: number, removeFiles?: boolean }} [options]
+ * @returns {object[]} the surviving records, newest heartbeat first
+ */
+export function pruneServerRecords(dir, options = {}) {
+  const now = options.now ?? Date.now()
+  const staleMs = options.staleMs ?? STALE_HEARTBEAT_MS
+  const removeFiles = options.removeFiles ?? true
+  const surviving = []
+  for (const record of readServerRecords(dir)) {
+    const heartbeat = typeof record.heartbeat === 'number' ? record.heartbeat : record.startedAt ?? 0
+    const fresh = now - heartbeat <= staleMs
+    if (fresh || isProcessAlive(record.pid)) {
+      surviving.push(record)
+    } else if (removeFiles) {
+      // Best effort: a concurrent viewer on another account may lack permission.
+      try {
+        rmSync(serverRecordPath(dir, record.pid), { force: true })
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  surviving.sort((a, b) => (b.heartbeat ?? b.startedAt ?? 0) - (a.heartbeat ?? a.startedAt ?? 0))
+  return surviving
+}
+
+/**
+ * Choose the Harness process a viewer should attach to.
+ *
+ * Precedence: an explicit socket wins outright; then an explicit pid; then the
+ * record whose serving directory matches `cwd`; then the freshest record.
+ *
+ * @param {object[]} records records from {@link pruneServerRecords}
+ * @param {{ socket?: string, pid?: number, cwd?: string }} [preferences]
+ * @returns {object | undefined}
+ */
+export function selectServerRecord(records, preferences = {}) {
+  if (preferences.socket !== undefined) {
+    const exact = records.find((record) => record.socket === preferences.socket)
+    if (exact !== undefined) return exact
+    // An explicit socket is usable even when no registry record describes it,
+    // which is what `--socket` promises and what a sandboxed run needs.
+    return { pid: -1, socket: preferences.socket, cwd: preferences.cwd, sessions: [], activeSessionId: null }
+  }
+  if (records.length === 0) return undefined
+  if (preferences.pid !== undefined) {
+    return records.find((record) => record.pid === preferences.pid) ?? freshest(records)
+  }
+  if (preferences.cwd !== undefined) {
+    const byCwd = records.find((record) => record.cwd === preferences.cwd)
+    if (byCwd !== undefined) return byCwd
+  }
+  return freshest(records)
+}
+
+/** @returns {object} the record with the newest heartbeat, irrespective of input order. */
+function freshest(records) {
+  return records.reduce((best, record) =>
+    (record.heartbeat ?? record.startedAt ?? 0) > (best.heartbeat ?? best.startedAt ?? 0) ? record : best
+  )
+}
+
+/**
+ * Pick the session a viewer should bind to.
+ *
+ * Precedence: an explicit session id; then the session whose `cwd` matches the
+ * viewer's; then the record's own `activeSessionId`; then the newest session.
+ *
+ * @param {object} record a registry record
+ * @param {{ sessionId?: string, cwd?: string }} [preferences]
+ * @returns {object | undefined}
+ */
+export function selectSession(record, preferences = {}) {
+  const sessions = Array.isArray(record?.sessions) ? record.sessions : []
+  if (preferences.sessionId !== undefined) {
+    return sessions.find((session) => session.id === preferences.sessionId)
+  }
+  if (sessions.length === 0) return undefined
+  if (preferences.cwd !== undefined) {
+    const matches = sessions.filter((session) => session.cwd === preferences.cwd)
+    if (matches.length > 0) return newestSession(matches)
+  }
+  if (typeof record.activeSessionId === 'string') {
+    const active = sessions.find((session) => session.id === record.activeSessionId)
+    if (active !== undefined) return active
+  }
+  return newestSession(sessions)
+}
+
+/** @returns {object} the most recently created session in a list */
+export function newestSession(sessions) {
+  return sessions.reduce((best, session) =>
+    (session.createdAt ?? 0) >= (best.createdAt ?? 0) ? session : best
+  )
+}
+
+/** Convenience wrapper resolving the standard servers directory. */
+export function resolveServersDir(runtimeDir) {
+  return serversDir(runtimeDir)
+}

package/lib/tools.js

@@ -0,0 +1,257 @@
+/**
+ * Pure helpers for the two structured things a trace is most often read for:
+ * the commands the model ran (with their output and exit status) and the files
+ * it changed (with their diffs).
+ *
+ * Nothing here imports the Harness. The shell exit-status marker contract and
+ * the file-diff metadata shape are *mirrored* rather than imported so the
+ * observer keeps working across Harness versions and stays dependency-free; the
+ * mirroring is deliberately tolerant, and an unrecognized shape degrades to
+ * "no structured detail" instead of an error.
+ *
+ * @module dsh-live-trace/tools
+ */
+
+/** Tool names treated as shell commands. */
+const SHELL_TOOLS = new Set([
+  'bash',
+  'sh',
+  'zsh',
+  'shell',
+  'pwsh',
+  'powershell',
+  'cmd',
+  'exec',
+  'terminal',
+  'bash_persistent',
+  'pwsh_persistent'
+])
+
+/** Default cap on retained command output, in lines and characters. */
+export const OUTPUT_LINE_LIMIT = 200
+export const OUTPUT_CHAR_LIMIT = 20_000
+
+/**
+ * @param {unknown} name
+ * @returns {boolean} whether a tool name denotes a shell command
+ */
+export function isShellTool(name) {
+  if (typeof name !== 'string' || name.length === 0) return false
+  const normalized = name.toLowerCase()
+  if (SHELL_TOOLS.has(normalized)) return true
+  // Persistent or namespaced variants such as `local:bash`.
+  const tail = normalized.split(/[:/.]/).pop() ?? normalized
+  return SHELL_TOOLS.has(tail)
+}
+
+/**
+ * Split a rendered shell result into its output body and exit status.
+ *
+ * Mirrors the marker contract the shell tools append: a trailing
+ * `[exit code: N]` or `[killed by signal: X]` on its own final line. Absent
+ * both markers means a clean exit 0.
+ *
+ * @param {string} text
+ * @returns {{ body: string, exitCode?: number, signal?: string }}
+ */
+export function parseExitStatus(text) {
+  if (typeof text !== 'string' || text.length === 0) return { body: '', exitCode: 0 }
+  const signal = /\n\[killed by signal: ([^\]\n]+)\]$/.exec(text)
+  if (signal !== null && signal[1] !== undefined) return { body: text.slice(0, signal.index), signal: signal[1] }
+  const exit = /\n\[exit code: (\d+)\]$/.exec(text)
+  if (exit !== null && exit[1] !== undefined) return { body: text.slice(0, exit.index), exitCode: Number(exit[1]) }
+  return { body: text, exitCode: 0 }
+}
+
+/**
+ * Parse a tool call's raw argument JSON without ever throwing.
+ * @param {unknown} raw
+ * @returns {Record<string, unknown> | undefined}
+ */
+export function parseArguments(raw) {
+  if (raw === null || raw === undefined) return undefined
+  if (typeof raw === 'object' && !Array.isArray(raw)) return /** @type {Record<string, unknown>} */ (raw)
+  if (typeof raw !== 'string' || raw.trim().length === 0) return undefined
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? /** @type {Record<string, unknown>} */ (parsed)
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Structured shell facts for one call, when the tool is a shell tool.
+ *
+ * @param {string} name tool name
+ * @param {unknown} rawArguments the raw arguments JSON string
+ * @returns {{ command: string, description?: string, cwd?: string } | undefined}
+ */
+export function shellCallFrom(name, rawArguments) {
+  if (!isShellTool(name)) return undefined
+  const args = parseArguments(rawArguments)
+  const command = typeof args?.command === 'string' ? args.command : undefined
+  if (command === undefined || command.length === 0) return undefined
+  /** @type {{ command: string, description?: string, cwd?: string }} */
+  const shell = { command }
+  if (typeof args?.description === 'string' && args.description.length > 0) shell.description = args.description
+  if (typeof args?.cwd === 'string' && args.cwd.length > 0) shell.cwd = args.cwd
+  return shell
+}
+
+/**
+ * A file-edit tool's target path, when the call names one.
+ * @param {unknown} rawArguments
+ * @returns {string | undefined}
+ */
+export function filePathFrom(rawArguments) {
+  const args = parseArguments(rawArguments)
+  if (args === undefined) return undefined
+  for (const key of ['file_path', 'path', 'filePath', 'filename']) {
+    const value = args[key]
+    if (typeof value === 'string' && value.length > 0) return value
+  }
+  return undefined
+}
+
+/**
+ * A `write`-style call's file path and content, when the arguments carry both.
+ *
+ * A brand-new file has no prior text, so the tool reports an empty hunk list
+ * and the applied content exists only in the call arguments. Recovering it here
+ * is what lets a create show up as a whole-file addition instead of nothing.
+ *
+ * @param {unknown} rawArguments
+ * @param {string} [filePath]
+ * @returns {{ filePath: string, content: string } | undefined}
+ */
+export function writeCallFrom(rawArguments, filePath) {
+  const args = parseArguments(rawArguments)
+  if (args === undefined) return undefined
+  const content = args.content
+  if (typeof content !== 'string') return undefined
+  const path = filePath ?? (typeof args.file_path === 'string' ? args.file_path : undefined)
+  if (path === undefined || path.length === 0) return undefined
+  return { filePath: path, content }
+}
+
+/**
+ * Narrow opaque `tool/result` metadata into file diffs.
+ *
+ * Mirrors the `{ diffs: [{ path, oldText, newText }], operation? }` payload a
+ * file-writing tool attaches. Malformed metadata yields `undefined` so
+ * presentation falls back instead of throwing during replay.
+ *
+ * @param {unknown} meta
+ * @returns {{ path: string, oldText: string | null, newText: string }[] | undefined}
+ */
+export function narrowFileDiffs(meta) {
+  if (meta === null || typeof meta !== 'object') return undefined
+  const diffs = /** @type {Record<string, unknown>} */ (meta).diffs
+  if (!Array.isArray(diffs) || diffs.length === 0) return undefined
+  const out = []
+  for (const candidate of diffs) {
+    if (candidate === null || typeof candidate !== 'object') continue
+    const record = /** @type {Record<string, unknown>} */ (candidate)
+    if (typeof record.path !== 'string') continue
+    if (typeof record.newText !== 'string') continue
+    const oldText = record.oldText
+    if (oldText !== null && typeof oldText !== 'string') continue
+    out.push({ path: record.path, oldText: oldText ?? null, newText: record.newText })
+  }
+  return out.length > 0 ? out : undefined
+}
+
+/**
+ * The operation a diff payload reports (`create` or `update`).
+ * @param {unknown} meta
+ * @returns {'create' | 'update' | undefined}
+ */
+export function diffOperationFrom(meta) {
+  if (meta === null || typeof meta !== 'object') return undefined
+  const operation = /** @type {Record<string, unknown>} */ (meta).operation
+  return operation === 'create' || operation === 'update' ? operation : undefined
+}
+
+/**
+ * Count the added and removed lines across diff hunks.
+ *
+ * A hunk is a replaced region: `oldText === null` is a pure insertion. The
+ * counts are line-based so they match what a `git diff --numstat` reader
+ * expects.
+ *
+ * @param {{ oldText: string | null, newText: string }[]} hunks
+ * @returns {{ added: number, removed: number }}
+ */
+export function countDiffLines(hunks) {
+  let added = 0
+  let removed = 0
+  for (const hunk of hunks) {
+    if (hunk.newText.length > 0) added += hunk.newText.split('\n').length
+    if (typeof hunk.oldText === 'string' && hunk.oldText.length > 0) {
+      removed += hunk.oldText.split('\n').length
+    }
+  }
+  return { added, removed }
+}
+
+/**
+ * Flatten diff hunks into unified-diff display lines.
+ *
+ * Each hunk becomes a `@@` header followed by its context/removed/added lines,
+ * with a one-line gap marker between non-adjacent hunks so a reader can tell
+ * that content was elided.
+ *
+ * @param {{ path: string, oldText: string | null, newText: string }[]} hunks
+ * @returns {{ kind: 'hunk' | 'context' | 'add' | 'del' | 'gap' | 'meta', text: string }[]}
+ */
+export function diffLines(hunks) {
+  const out = []
+  hunks.forEach((hunk, index) => {
+    if (index > 0) out.push({ kind: 'gap', text: '⋮' })
+    out.push({ kind: 'hunk', text: `@@ ${hunk.path}${hunk.oldText === null ? ' (new file)' : ''}` })
+    if (typeof hunk.oldText === 'string' && hunk.oldText.length > 0) {
+      for (const line of hunk.oldText.split('\n')) out.push({ kind: 'del', text: line })
+    }
+    for (const line of hunk.newText.split('\n')) out.push({ kind: 'add', text: line })
+  })
+  return out
+}
+
+/**
+ * Cap command output for display, reporting what was dropped.
+ *
+ * The tail is kept rather than the head: when a command fails, the interesting
+ * part is almost always the end.
+ *
+ * @param {string} text
+ * @param {{ maxLines?: number, maxChars?: number }} [options]
+ * @returns {{ text: string, lines: number, truncated: boolean, omitted: number }}
+ */
+export function capOutput(text, options = {}) {
+  const maxLines = options.maxLines ?? OUTPUT_LINE_LIMIT
+  const maxChars = options.maxChars ?? OUTPUT_CHAR_LIMIT
+  const source = typeof text === 'string' ? text : ''
+  if (source.length === 0) return { text: '', lines: 0, truncated: false, omitted: 0 }
+  let lines = source.split('\n')
+  let truncated = false
+  let omitted = 0
+  if (lines.length > maxLines) {
+    omitted = lines.length - maxLines
+    lines = lines.slice(lines.length - maxLines)
+    truncated = true
+  }
+  let body = lines.join('\n')
+  if (body.length > maxChars) {
+    const dropped = body.length - maxChars
+    // Count the extra lines folded into the character cut so `omitted` stays honest.
+    const extraLines = body.slice(0, dropped).split('\n').length - 1
+    omitted += extraLines
+    body = body.slice(dropped)
+    lines = body.split('\n')
+    truncated = true
+  }
+  return { text: body, lines: lines.length, truncated, omitted }
+}