dsh-autorestart 0.6.1 → 0.7.0

package/lib/access.js

@@ -0,0 +1,212 @@
+/**
+ * dsh-autorestart — the instance record: how the running host can be reached.
+ *
+ * TWO facts make this file necessary:
+ *
+ *   1. The web server of the desktop app listens on a RANDOM port (`--port 0`),
+ *      so the port of the PREVIOUS instance is worthless for the next one. The
+ *      port of the new instance is only known to the new instance itself — so
+ *      the new instance has to publish it, and the rollback watcher has to read
+ *      it instead of guessing.
+ *   2. The boot token of `dsh web` is created PER PROCESS. After a restart the
+ *      old access link answers 401, so the user is locked out of their own
+ *      interface until somebody hands them the new link. The new instance knows
+ *      its own link (the host's connection service signs it), so the new
+ *      instance writes it down — into a file only the user can read.
+ *
+ * The record is ONE small JSON file in the state directory:
+ *
+ *   { "bootId": "…", "pid": 1234, "port": 55537, "url": "http://…/?token=…",
+ *     "token": "…", "at": 1730000000000 }
+ *
+ * `bootId` is what tells "the new instance" from "the old one": the plugin
+ * generates a new one on every boot, so a watcher can wait for the change
+ * instead of guessing from a port.
+ *
+ * The file holds a SECRET (the boot token), so it is written with the
+ * restrictive mode 0600. On POSIX that is enforced by the kernel; on Windows
+ * the mode is advisory, so the file inherits the ACL of the (per-user) state
+ * directory — which is why the token is never written anywhere else in
+ * readable form.
+ *
+ * ESM only, Node builtins only. No DSH / npm imports.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** The name of the instance record inside the state directory. */
+export const ACCESS_FILE_NAME = 'access.json';
+
+/** The mode the instance record is written with: readable by its owner only. */
+export const ACCESS_FILE_MODE = 0o600;
+
+/** @param {unknown} value */
+function errorText(value) {
+  if (value && typeof value.message === 'string' && value.message) return value.message;
+  return String(value);
+}
+
+/**
+ * The path of the instance record that belongs to a state directory.
+ *
+ * @param {string} stateDir
+ * @returns {string}
+ */
+export function accessFilePath(stateDir) {
+  return path.join(String(stateDir ?? ''), ACCESS_FILE_NAME);
+}
+
+/**
+ * The access link of the running instance, with its boot token when the host's
+ * connection service can sign one.
+ *
+ * The connection service is optional: a host that does not provide it still
+ * gets the plain origin, so the record is always written.
+ *
+ * @param {{ origin?: string, connection?: any }} options
+ * @returns {{ url: string|null, token: string|null }}
+ */
+export function resolveAccessUrl({ origin = '', connection = null } = {}) {
+  const base = typeof origin === 'string' ? origin.trim().replace(/\/+$/, '') : '';
+  if (base === '') return { url: null, token: null };
+  let url = base + '/';
+  let token = null;
+  try {
+    if (connection && typeof connection.authenticatedUrl === 'function') {
+      const signed = connection.authenticatedUrl(base);
+      if (typeof signed === 'string' && signed.trim() !== '') {
+        url = signed.trim();
+        try {
+          const parsed = new URL(url);
+          token = parsed.searchParams.get('token');
+        } catch {
+          token = null;
+        }
+      }
+    }
+  } catch {
+    // A connection service that throws must not cost us the plain origin.
+    url = base + '/';
+    token = null;
+  }
+  return { url, token };
+}
+
+/**
+ * Write the instance record.
+ *
+ * The write is atomic (a temporary file + a rename), so a reader never sees a
+ * half-written record, and the mode is restricted to the owner.
+ *
+ * @param {{
+ *   stateDir?: string,
+ *   bootId?: string|null,
+ *   pid?: number|null,
+ *   port?: number|null,
+ *   url?: string|null,
+ *   token?: string|null,
+ *   now?: number,
+ * }} [options]
+ * @returns {{ ok: boolean, path: string|null, record: object|null, error: string|null }}
+ */
+export function writeAccessRecord({
+  stateDir = '',
+  bootId = null,
+  pid = null,
+  port = null,
+  url = null,
+  token = null,
+  now = Date.now(),
+} = {}) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') {
+    return { ok: false, path: null, record: null, error: 'writeAccessRecord requires stateDir' };
+  }
+  const file = accessFilePath(dir);
+  const record = {
+    bootId: typeof bootId === 'string' && bootId !== '' ? bootId : null,
+    pid: Number.isFinite(Number(pid)) ? Number(pid) : null,
+    port: Number.isFinite(Number(port)) ? Number(port) : null,
+    url: typeof url === 'string' && url !== '' ? url : null,
+    token: typeof token === 'string' && token !== '' ? token : null,
+    at: Number.isFinite(Number(now)) ? Number(now) : Date.now(),
+  };
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const temporary = file + '.tmp';
+    fs.writeFileSync(temporary, JSON.stringify(record, null, 2) + '\n', {
+      encoding: 'utf8',
+      mode: ACCESS_FILE_MODE,
+    });
+    // `writeFileSync` only applies the mode when it CREATES the file, so the
+    // permission is set explicitly as well (and after the rename, because the
+    // rename keeps the mode of the source anyway).
+    try {
+      fs.chmodSync(temporary, ACCESS_FILE_MODE);
+    } catch {
+      /* the mode is advisory on some platforms */
+    }
+    fs.renameSync(temporary, file);
+    try {
+      fs.chmodSync(file, ACCESS_FILE_MODE);
+    } catch {
+      /* the mode is advisory on some platforms */
+    }
+    return { ok: true, path: file, record, error: null };
+  } catch (error) {
+    return { ok: false, path: file, record, error: 'could not write the instance record: ' + errorText(error) };
+  }
+}
+
+/**
+ * Read the instance record from a file path.
+ *
+ * @param {string} file
+ * @returns {{ ok: boolean, record: object|null, error: string|null }}
+ */
+export function readAccessRecordFile(file) {
+  const target = typeof file === 'string' ? file.trim() : '';
+  if (target === '') return { ok: false, record: null, error: 'readAccessRecordFile requires a path' };
+  try {
+    const text = fs.readFileSync(target, 'utf8');
+    if (text.charCodeAt(0) === 0xfeff) {
+      const parsed = JSON.parse(text.slice(1));
+      return { ok: true, record: parsed && typeof parsed === 'object' ? parsed : null, error: null };
+    }
+    const parsed = JSON.parse(text);
+    return { ok: true, record: parsed && typeof parsed === 'object' ? parsed : null, error: null };
+  } catch (error) {
+    return { ok: false, record: null, error: errorText(error) };
+  }
+}
+
+/**
+ * Read the instance record of a state directory.
+ *
+ * @param {string} stateDir
+ * @returns {{ ok: boolean, record: object|null, error: string|null }}
+ */
+export function readAccessRecord(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return { ok: false, record: null, error: 'readAccessRecord requires stateDir' };
+  return readAccessRecordFile(accessFilePath(dir));
+}
+
+/**
+ * Remove the instance record (used when a restart is armed, so a stale record
+ * of a dead instance is never mistaken for a live one).
+ *
+ * @param {string} stateDir
+ * @returns {boolean} whether a record was removed
+ */
+export function clearAccessRecord(stateDir) {
+  const dir = typeof stateDir === 'string' ? stateDir.trim() : '';
+  if (dir === '') return false;
+  try {
+    fs.rmSync(accessFilePath(dir), { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/lib/activity.js

@@ -0,0 +1,124 @@
+/**
+ * dsh-autorestart — what counts as REAL activity for the quiet window.
+ *
+ * THE DEFECT THIS MODULE FIXES
+ *
+ * The settle window ("the host must stay quiet for N ms before a restart may
+ * fire") used to be reset by EVERY session event. The host emits session
+ * events continuously while the interface polls and synchronises (measured on
+ * the real machine: one every 2-3 seconds), so a window longer than the event
+ * interval could never fill: the restart never fired, no matter how long the
+ * user waited.
+ *
+ * THE POLICY
+ *
+ * A session event counts as activity only when it says that WORK happened: a
+ * message was written, a tool ran, a turn started or ended. Everything else
+ * (a title, a projection update, a context request, a job that settled, a
+ * permission preset) is routine and must NOT reset the window.
+ *
+ * The rule is deliberately one-sided: an event whose type cannot be read is
+ * NOT activity. When in doubt the plugin would rather restart a little early
+ * than never restart at all.
+ *
+ * The hard guarantee does not live here: a conversation that is really
+ * running blocks the restart through `busyAgents()` (the `running` reason),
+ * and that rule is never relaxed. This module only decides what the QUIET
+ * window measures.
+ *
+ * ESM only, Node builtins only. No DSH / npm imports.
+ */
+
+/**
+ * The session event types that mean "work happened".
+ *
+ * The vocabulary is the one of the DSH session service (its known event
+ * types). Only the events that describe a message, a tool, a turn or a
+ * command are listed; the rest (titles, projections, jobs, presets, modes,
+ * schedules, telemetry) are routine.
+ */
+export const WORK_SESSION_EVENT_TYPES = Object.freeze([
+  // A message was written into a conversation.
+  'user/message',
+  'developer/message',
+  'system/message',
+  'assistant/message',
+  'assistant/attempt',
+  // A tool ran.
+  'tool/call',
+  'tool/result',
+  'tool/ptc-dispatch',
+  'tool/ptc-dispatch-start',
+  // A turn or a step started or ended.
+  'turn/start',
+  'turn/end',
+  'step/start',
+  'step/end',
+  // A command ran.
+  'command/run',
+  'command/done',
+  // Work was handed around: an inbox splice, a team message, a workflow run.
+  'agent/inbox/spliced',
+  'team/message/queued',
+  'team/message/delivered',
+  'team/task',
+  'team/member',
+  'tool-workflow/run-start',
+  'tool-workflow/run-end',
+  'tool-workflow/agent-start',
+  'tool-workflow/agent-end',
+  // A hook ran, a compaction ran, the model retried, a goal changed.
+  'hook/invoked',
+  'hook/result',
+  'compaction/start',
+  'compaction/end',
+  'compaction/prune',
+  'compaction/summary',
+  'llm/retry',
+  'llm/retry-started',
+  'goal/change',
+  'approval/asked',
+])
+
+/** The work types as a Set, for a cheap lookup. */
+const WORK_TYPES = new Set(WORK_SESSION_EVENT_TYPES)
+
+/**
+ * The type of one session event, or null when it cannot be read.
+ *
+ * The payload shape differs between the hosts that call this plugin, so the
+ * type is looked for in the places it can be: the payload itself, the nested
+ * event, or the data envelope.
+ *
+ * @param {any} payload the event payload the host delivered
+ * @returns {string|null}
+ */
+export function sessionEventType(payload) {
+  if (payload === null || typeof payload !== 'object') return null
+  const candidates = [
+    payload.type,
+    payload.eventType,
+    payload.event && typeof payload.event === 'object' ? payload.event.type : undefined,
+    payload.data && typeof payload.data === 'object' ? payload.data.type : undefined,
+    payload.data && typeof payload.data === 'object' && payload.data.event && typeof payload.data.event === 'object'
+      ? payload.data.event.type
+      : undefined,
+  ]
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim() !== '') return candidate.trim()
+  }
+  return null
+}
+
+/**
+ * Whether one session event means that real work happened.
+ *
+ * @param {any} payload the event payload the host delivered
+ * @returns {boolean} false for a routine event AND for an event whose type
+ *   cannot be read (the one-sided rule: when in doubt, do not wait)
+ */
+export function isWorkSessionEvent(payload) {
+  const type = sessionEventType(payload)
+  if (type === null) return false
+  return WORK_TYPES.has(type)
+}

package/lib/autostart-advice.js

@@ -0,0 +1,198 @@
+/**
+ * dsh-autorestart — THE "START AT LOGIN" GUIDE OF EVERY PLATFORM.
+ *
+ * A hosted web host can be started in a dozen ways, and "start at login" means
+ * something different on every platform. The plugin therefore hands out ONE
+ * piece of advice per platform, and it always says what the record really is:
+ *
+ *   | platform              | what the plugin does                                      |
+ *   |-----------------------|----------------------------------------------------------|
+ *   | Windows               | a scheduled task (`/SC ONLOGON /RL LIMITED`, no admin); when the machine refuses it, a `.cmd` in the startup folder. The command is a REAL node + supervisor.js — never the app executable. |
+ *   | Linux (not WSL)       | a systemd USER service (`systemctl --user`, no admin) — plus the `loginctl enable-linger` hint, because without the linger it only starts after a login. |
+ *   | WSL with systemd      | the same systemd user unit, plus the linger hint.         |
+ *   | WSL without systemd   | NO "at login" at all: two ways out (turn systemd on inside WSL, or let Windows start the distribution). NEVER Docker/Compose. |
+ *   | container / k8s       | no promise at all: the orchestrator brings it back (compose `restart: always`). |
+ *   | unknown               | nothing is installed and nothing is guessed: the user is told why and asked to choose. |
+ *
+ * The advice is a pure function of its input, so every branch is testable
+ * without a machine.
+ *
+ * ESM only, Node builtins only.
+ */
+
+import { HOST_KINDS } from './host-kind.js'
+
+/** The kinds of the advice (one per platform). */
+export const AUTOSTART_ADVICE_KINDS = Object.freeze({
+  /** Windows: a scheduled task (with the startup folder as the fallback). */
+  WINDOWS: 'windows-task',
+  /** Linux: a systemd user service (+ the linger hint). */
+  LINUX: 'linux-systemd',
+  /** WSL with systemd: the same, and the linger is the missing piece. */
+  WSL_SYSTEMD: 'wsl-systemd',
+  /** WSL without systemd: the user has to pick one of two ways. */
+  WSL_MANUAL: 'wsl-manual',
+  /** A container: the orchestrator decides. */
+  CONTAINER: 'container',
+  /** Nobody can tell: nothing is installed, nothing is guessed. */
+  UNKNOWN: 'unknown',
+})
+
+/** @param {unknown} value */
+function text(value) {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/**
+ * The advice of one platform.
+ *
+ * @param {{
+ *   host?: { kind?: string, suspect?: boolean, distro?: string, evidence?: string },
+ *   platform?: string,
+ *   hasSystemd?: boolean,
+ *   container?: boolean,
+ *   user?: string,
+ *   distro?: string,
+ *   startCommand?: string,
+ *   command?: string,
+ * }} [options]
+ * @returns {{
+ *   kind: string,
+ *   reason: string,
+ *   notes: string[],
+ *   commands: string[],
+ *   options: Array<{ id: string, label: string, command: string, cost: string, recommended: boolean }>,
+ *   canInstall: boolean,
+ * }}
+ */
+export function planAutostartAdvice(options = {}) {
+  const host = options.host && typeof options.host === 'object' ? options.host : {}
+  const platform = text(options.platform) || text(host.platform) || process.platform
+  const kind = text(host.kind)
+  const suspect = host.suspect === true
+  const user = text(options.user) || text(process.env.USER) || text(process.env.LOGNAME) || '你的用户名'
+  const distro = text(options.distro) || text(host.distro) || '你的发行版'
+  const startCommand = text(options.startCommand)
+  const command = text(options.command)
+  const hasSystemd = options.hasSystemd === true
+  const isContainer = options.container === true
+
+  // A host that is only GUESSED to be WSL (the mounted Windows drive is the
+  // only evidence) gets no automatic anything: the plugin says so and leaves
+  // the choice to the user.
+  const suspectNote = suspect
+    ? '没把握：这台机器只是「挂载了 Windows 盘」才被猜成 WSL，插件不会替你改任何系统配置，建议你手动选一条。'
+    : ''
+
+  const linger = 'loginctl enable-linger ' + user
+
+  // (1) A CONTAINER. The orchestrator brings it back — there is no "at login".
+  if (isContainer) {
+    return {
+      kind: AUTOSTART_ADVICE_KINDS.CONTAINER,
+      reason: '容器里没有「开机自启」这回事：由编排器负责（compose 的 restart: always / k8s 的 restartPolicy）。',
+      notes: [
+        '容器里没有「开机自启」这回事：由编排器负责（compose 的 restart: always / k8s 的 restartPolicy）。',
+        '插件不会在容器里装 systemd —— 容器里也没有 systemd 可装。',
+      ],
+      commands: [],
+      options: [],
+      canInstall: false,
+    }
+  }
+
+  // (2) WINDOWS. The scheduled task first, the startup folder as the fallback.
+  if (kind === HOST_KINDS.WINDOWS || platform === 'win32') {
+    return {
+      kind: AUTOSTART_ADVICE_KINDS.WINDOWS,
+      reason: 'Windows 托管端：登录时自启用**计划任务**（/SC ONLOGON /RL LIMITED，不需要管理员）；这台机器若不允许普通用户建计划任务，会自动降级到「启动文件夹」里的一个 .cmd（同样不需要管理员）。注册的命令是**真正的 node + supervisor.js**，不是 DSH 客户端本体。',
+      notes: [
+        '登录时自启：计划任务（/SC ONLOGON /RL LIMITED，零管理员权限）。',
+        '这台机器拒绝计划任务时自动降级为「启动文件夹」里的 .cmd（同样零权限）。',
+        '注册的命令是真正的 node + supervisor.js —— 绝不会用 DSH 客户端本体去跑守护脚本（那会在每次登录时再开一个 DSH）。',
+      ],
+      commands: command === '' ? [] : [command],
+      options: [],
+      canInstall: true,
+    }
+  }
+
+  // (3) WSL. With systemd it is a user unit (+ the linger); without it there
+  // is no "at login" at all — and NEVER a Docker answer.
+  if (kind === HOST_KINDS.WSL) {
+    if (hasSystemd) {
+      return {
+        kind: AUTOSTART_ADVICE_KINDS.WSL_SYSTEMD,
+        reason: 'WSL 里有 systemd：守护装成 systemd 用户单元（登录后自启）。'
+          + '若要「开机自启」（不必先登录），在 WSL 里运行一次：' + linger
+          + (suspectNote !== '' ? suspectNote : ''),
+        notes: [
+          'WSL 里有 systemd：守护装成 systemd 用户单元（登录后自启）。',
+          '若要「开机自启」（不必先登录），在 WSL 里运行一次：' + linger
+            + '（只需一次；linger 让 systemd 在你没登录时也把这个用户的服务拉起来）。',
+        ],
+        commands: [linger],
+        options: [],
+        canInstall: true,
+      }
+    }
+    const systemdOption = {
+      id: 'wsl-systemd-enable',
+      label: '① 在 WSL 内部开启 systemd',
+      command: '在 /etc/wsl.conf 里加上 [boot] systemd=true，然后在 Windows 侧运行 wsl --shutdown 重启子系统',
+      cost: '这是系统配置改动：要改发行版里的 /etc/wsl.conf，并且要重启整个 WSL 子系统（别的发行版和正在跑的进程会一起停）。',
+      recommended: false,
+    }
+    const windowsOption = {
+      id: 'wsl-windows-task',
+      label: '② 在 Windows 侧用计划任务 / 启动文件夹拉起 WSL',
+      command: 'wsl.exe -d ' + distro + ' -e ' + (startCommand !== '' ? startCommand : '<启动命令>'),
+      cost: '需要 Windows 侧操作（新建一条计划任务，或往启动文件夹放一个快捷方式），但更接近真正的开机自启。',
+      recommended: true,
+    }
+    return {
+      kind: AUTOSTART_ADVICE_KINDS.WSL_MANUAL,
+      reason: 'WSL 里没有 systemd：这里没有「登录时自启」这回事。'
+        + '两条路（插件不会替你改任何系统配置）：① 在 WSL 内部开启 systemd；② 在 Windows 侧用计划任务/启动文件夹拉起 WSL（推荐）。'
+        + (suspectNote !== '' ? suspectNote : ''),
+      notes: [
+        'WSL 里没有 systemd：这里没有「登录时自启」这回事，所以插件不装任何东西。',
+        suspectNote !== '' ? suspectNote : '插件不会替你改任何系统配置，两条路都需要你自己动手。',
+        '① 在 WSL 内部开启 systemd —— 这是系统配置改动（改 /etc/wsl.conf + 重启子系统）。',
+        '② 在 Windows 侧用计划任务 / 启动文件夹拉起 WSL（推荐）—— 需要 Windows 侧操作，但更接近真正的开机自启。',
+      ],
+      commands: [windowsOption.command],
+      options: [systemdOption, windowsOption],
+      canInstall: false,
+    }
+  }
+
+  // (4) LINUX (and every other real Linux): a systemd user service, and the
+  // linger that turns "after a login" into "at boot".
+  if (kind === HOST_KINDS.LINUX || platform === 'linux') {
+    return {
+      kind: AUTOSTART_ADVICE_KINDS.LINUX,
+      reason: 'Linux 托管端：用 systemd 用户服务（systemctl --user，不需要管理员）。这是「登录后自启」；若要「开机自启」（不必先登录），运行一次 ' + linger + '。',
+      notes: [
+        'systemd 用户服务：登录后自启（零管理员权限）。',
+        '若要「开机自启」（不必先登录），运行一次：' + linger + '（只需一次；没有 linger 就只是登录后自启）。',
+      ],
+      commands: [linger],
+      options: [],
+      canInstall: true,
+    }
+  }
+
+  // (5) UNKNOWN. Nothing is installed, nothing is guessed.
+  return {
+    kind: AUTOSTART_ADVICE_KINDS.UNKNOWN,
+    reason: '认不出这个宿主是怎么被拉起来的：插件不装任何东西，也不猜命令。请你手动选一条（或告诉插件该怎么拉起它）。',
+    notes: [
+      '认不出这个宿主是怎么被拉起来的：插件不装任何东西，也不猜命令。',
+      '这是「宁可说不知道，也不双开」的保守做法 —— 请你手动选一条。',
+    ],
+    commands: [],
+    options: [],
+    canInstall: false,
+  }
+}