dsh-autorestart 0.6.1 → 0.6.2

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/lifecycle.js

@@ -262,10 +262,12 @@ export function selectGoalDisarms(busyAgents, { getGoal, disarmedGoals, parkedGo
  *   forceRestartWhenBusy?: boolean,
  * }} [options]
  * @returns {{
- *   action: 'none'|'wait'|'warn'|'restart'|'force-restart'|'give-up',
+ *   action: 'none'|'wait'|'warn'|'long-wait'|'restart'|'force-restart'|'give-up',
  *   reason: string,
  *   log?: string,
  *   markSoftWarned?: boolean,
+ *   blockedBy?: { sessionId: string|null, reason: string }[],
+ *   waitingSince?: number,
  * }}
  */
 export function restartDecision(
@@ -325,11 +327,19 @@ export function restartDecision(
   }
 
   // Hard deadline reached while a conversation is still running.
+  //
+  // From here on the plugin does NOT pretend that "everything is fine, we are
+  // just waiting a little longer": the wait has become a LONG wait, and the
+  // caller (index.js) has to make it VISIBLE — in the log and in the state
+  // payload — while KEEPING the user's restart request alive. The request is
+  // never silently dropped.
   if (policy === 'wait') {
     return {
-      action: 'warn',
+      action: 'long-wait',
       reason: 'hard-deadline-policy-wait',
       log: 'defer policy wait: still busy after hard deadline',
+      blockedBy: busy,
+      waitingSince: requestedAt,
     };
   }
   // The hard deadline only forces a restart when the operator explicitly opted in
@@ -340,11 +350,14 @@ export function restartDecision(
     return { action: 'force-restart', reason: 'hard-deadline-force-restart' };
   }
   // forceRestartWhenBusy is disabled (the default): the restart keeps waiting
-  // until the idle gate is quiet again, and it never gives up.
+  // until the idle gate is quiet again, and it never gives up. The result says
+  // so explicitly — a long wait, with the sessions that hold it.
   return {
-    action: 'warn',
+    action: 'long-wait',
     reason: 'hard-deadline-waiting-for-conversations',
     log: 'dsh-autorestart: hard deadline reached but conversations are still running; forceRestartWhenBusy is disabled, so the restart keeps waiting',
+    blockedBy: busy,
+    waitingSince: requestedAt,
   };
 }
 

package/lib/queued.js

@@ -0,0 +1,146 @@
+/**
+ * dsh-autorestart — the upper bound of a QUEUED inbox message.
+ *
+ * THE DEFECT THIS MODULE FIXES
+ *
+ * A queued message (an inbox entry that nobody has claimed yet) used to block
+ * the restart FOR EVER. The idle gate counted "this session has a queued
+ * message" as "this session is busy", and the hard deadline only WARNED, so a
+ * session that never ran its turn (the real case: a fresh, empty conversation
+ * in the UI with one unclaimed message in its inbox) kept the pending restart
+ * pending until the user gave up.
+ *
+ * THE POLICY
+ *
+ *   - a message that is claimed inside the grace window keeps blocking the
+ *     restart (that is the normal case: the agent picks it up in a second);
+ *   - a message that is still unclaimed after the grace window is STUCK: it
+ *     stops blocking the restart and is named in the log, so the user can see
+ *     WHICH session holds the queue;
+ *   - a message that is being worked on (the session is `running`) always
+ *     blocks, under EVERY grace setting. This module only ever judges queued
+ *     work — it never relaxes the rule that a live turn is never interrupted.
+ *
+ * The tracker knows nothing about the host: it is a map of session id to the
+ * moment the session was FIRST seen with a queued message, so it can be unit
+ * tested with a fake clock.
+ *
+ * ESM only, Node builtins only. No DSH / npm imports.
+ */
+
+/** The default upper bound of a queued message: one minute. */
+export const DEFAULT_QUEUED_GRACE_MS = 60000
+
+/** @param {unknown} value */
+function isFiniteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+}
+
+/**
+ * Normalise a grace window.
+ *
+ * A negative or non-numeric value falls back to the default; `0` is a LEGAL
+ * value — it switches the protection off and restores the old behaviour (a
+ * queued message blocks the restart for ever).
+ *
+ * @param {unknown} value
+ * @returns {number} milliseconds, never negative
+ */
+export function normalizeQueuedGraceMs(value) {
+  if (!isFiniteNumber(value) || value < 0) return DEFAULT_QUEUED_GRACE_MS
+  return Math.trunc(value)
+}
+
+/**
+ * Create the tracker.
+ *
+ * @param {{ now?: () => number }} [options] the clock (injectable for tests)
+ * @returns {{
+ *   observe: (agentId: string, queued: boolean, graceMs?: number) => { blocking: boolean, firstSeenAt: number|null, ageMs: number, becameStale: boolean },
+ *   forget: (agentId: string) => boolean,
+ *   size: () => number,
+ *   ids: () => string[],
+ * }}
+ */
+export function createQueuedTracker({ now = () => Date.now() } = {}) {
+  /** @type {Map<string, { firstSeenAt: number, stale: boolean }>} */
+  const records = new Map()
+
+  /** The current time of the injected clock (never throws). */
+  const clock = () => {
+    try {
+      const value = now()
+      return isFiniteNumber(value) ? value : 0
+    } catch {
+      return 0
+    }
+  }
+
+  /**
+   * Observe one session.
+   *
+   * @param {string} agentId the session id
+   * @param {boolean} queued does the session have an unclaimed message?
+   * @param {number} [graceMs] the upper bound (0 = no upper bound)
+   * @returns {{ blocking: boolean, firstSeenAt: number|null, ageMs: number, becameStale: boolean }}
+   */
+  const observe = (agentId, queued, graceMs) => {
+    const id = agentId == null ? '' : String(agentId)
+    if (id === '') return { blocking: false, firstSeenAt: null, ageMs: 0, becameStale: false }
+
+    // The session has no queued work any more: its record is dropped, so a
+    // NEW queue starts counting from zero.
+    if (queued !== true) {
+      records.delete(id)
+      return { blocking: false, firstSeenAt: null, ageMs: 0, becameStale: false }
+    }
+
+    const at = clock()
+    let record = records.get(id)
+    if (record === undefined) {
+      record = { firstSeenAt: at, stale: false }
+      records.set(id, record)
+    }
+    const ageMs = Math.max(0, at - record.firstSeenAt)
+    const grace = normalizeQueuedGraceMs(graceMs)
+
+    // The protection is off (grace 0): a queued message blocks the restart for
+    // ever — exactly the behaviour before this module existed.
+    if (grace === 0) {
+      return { blocking: true, firstSeenAt: record.firstSeenAt, ageMs, becameStale: false }
+    }
+
+    // Still inside the grace window: the agent may claim the message any
+    // moment, so the restart keeps waiting for it.
+    if (ageMs < grace) {
+      return { blocking: true, firstSeenAt: record.firstSeenAt, ageMs, becameStale: false }
+    }
+
+    // The message is STUCK: it stops blocking the restart. `becameStale` is
+    // true only on the tick where it turned stale, so the caller can log it
+    // exactly once.
+    const becameStale = record.stale !== true
+    record.stale = true
+    return { blocking: false, firstSeenAt: record.firstSeenAt, ageMs, becameStale }
+  }
+
+  /**
+   * Drop the record of one session (it is running, or it is gone).
+   *
+   * @param {string} agentId
+   * @returns {boolean} whether a record was dropped
+   */
+  const forget = (agentId) => {
+    const id = agentId == null ? '' : String(agentId)
+    if (id === '') return false
+    return records.delete(id)
+  }
+
+  /** How many sessions are tracked right now. */
+  const size = () => records.size
+
+  /** The ids of the tracked sessions. */
+  const ids = () => Array.from(records.keys())
+
+  return { observe, forget, size, ids }
+}

package/locale/en.json

@@ -18,17 +18,21 @@
   },
   "settings": {
     "nav": "Auto-restart & shut down",
+    "groups": {
+      "restart": "Restart settings",
+      "shutdown": "Shutdown settings"
+    },
     "seconds": {
-      "label": "Countdown seconds",
+      "label": "Shutdown countdown seconds",
       "immediate": "No countdown (switch off right away)",
       "value": "{n} seconds",
-      "hint": "After the button: wait for every conversation to be done, count down this many seconds and switch off. \"No countdown\" switches off as soon as the conversations are done."
+      "hint": "Once every conversation is done, this countdown is shown on screen (pick \"Never mind, keep it on\" to cancel); the machine goes off when it reaches zero. Raise it when you want more time to write."
     },
-    "grace": {
-      "label": "Wait a few more seconds after the work is done",
-      "immediate": "Do not wait (restart/switch off right away)",
+    "restartGrace": {
+      "label": "Wait before the restart",
+      "immediate": "Do not wait (restart right away)",
       "value": "{n} seconds",
-      "hint": "After the last conversation finished, wait this long before the host is really restarted or switched off — this plugin only sees the DSH conversations, not the work other plugins queue with a timer. If a conversation starts working again while waiting, the timer starts over."
+      "hint": "A restart has no countdown: the host restarts as soon as the conversations are done. Raise this if you rely on a memory or summary plugin that writes its notes after the conversation ended (default 0 seconds)."
     },
     "backup": {
       "label": "Backup before a restart",

package/locale/zh.json

@@ -18,17 +18,21 @@
   },
   "settings": {
     "nav": "自动重启与关机",
+    "groups": {
+      "restart": "重启相关设置",
+      "shutdown": "关机相关设置"
+    },
     "seconds": {
-      "label": "倒计时秒数",
+      "label": "关机倒数秒数",
       "immediate": "不倒数（立即关机）",
       "value": "{n} 秒",
-      "hint": "按下按钮后，等所有会话收工，再倒数这么多秒才关机；「不倒数」表示会话一收工就关机。"
+      "hint": "所有会话收工后，屏幕上会显示这段倒数（可点「不关了」取消），数完才关机；想要更多落盘时间就把倒数调大。"
     },
-    "grace": {
-      "label": "收工后再等几秒（给记忆/总结类插件留时间）",
-      "immediate": "不等（立即重启/关机）",
+    "restartGrace": {
+      "label": "重启前等待",
+      "immediate": "不等（立即重启）",
       "value": "{n} 秒",
-      "hint": "最后一个会话收工后，再等这么久才真正重启或关机——我们只看得见 DSH 的会话，看不见别的插件用定时器排队的活。等待期间如果又有会话开始干活，会重新计时。"
+      "hint": "重启没有倒数环节，会话一收工就会立刻重启；如果你装了“会话结束后才写”的记忆/总结类插件，把这里调大（默认 0 秒）。"
     },
     "backup": {
       "label": "重启前备份",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-autorestart",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "description": "DeepSeek Harness plugin: restart without losing work. Waits until every conversation is idle, restarts the host, then automatically resumes the interrupted sessions. AI-generated, not human-reviewed: use with caution.",
   "license": "MIT",