dsh-autorestart 0.2.1 → 0.3.0

package/lib/lifecycle.js

@@ -28,6 +28,11 @@ function isFiniteNumber(value) {
 function isDoneEntry(entry) {
   if (!isObject(entry)) return true;
   if (entry.done === true) return true;
+  // A handed-off session and an over-limit session are BOTH out of the
+  // automatic resume path for good: replaying that conversation can only fail
+  // with the same "context window exceeds limit" error.
+  if (isObject(entry.handoff)) return true;
+  if (isObject(entry.contextOverflow) && entry.contextOverflow.over === true) return true;
   const phase = isObject(entry.goal) && typeof entry.goal.phase === 'string' ? entry.goal.phase : null;
   return phase === 'done' || phase === 'complete' || phase === 'completed';
 }
@@ -120,6 +125,122 @@ export function restartGate(state, { busyAgents = [], lastActivityAt = 0, now =
   return { allow: true, reason: 'quiet', blockedBy: [], quietForMs };
 }
 
+/**
+ * Why a session still keeps the restart waiting. `goal-active` is the only
+ * reason that can be cleared by DISARMING the goal (`ctx.goals.disarm`, which
+ * leaves the durable goal `active` but stops the round driver); every other
+ * reason is only REPORTED, because disarming would be wrong or useless:
+ *  - `goal-paused`   — somebody paused it (the model may not resume it),
+ *  - `goal-blocked` / `goal-complete` / `goal-not-active` — not running work,
+ *  - `goal-disarmed` — no continuation authority left to take away,
+ *  - `goal-exhausted` — the round budget is spent, so it can never be resumed,
+ *  - `goal-no-agent` — the session has no live agent to disarm through.
+ *  - `goal-parked`   — LEGACY: the old "this plugin already handled it" reason.
+ *    It is never produced any more: the live goal state decides, not a record.
+ */
+export const GOAL_BLOCK_REASONS = {
+  ACTIVE: 'goal-active',
+  PARKED: 'goal-parked',
+  EXHAUSTED: 'goal-exhausted',
+  PAUSED: 'goal-paused',
+  BLOCKED: 'goal-blocked',
+  COMPLETE: 'goal-complete',
+  DISARMED: 'goal-disarmed',
+  NOT_ACTIVE: 'goal-not-active',
+  NO_AGENT: 'goal-no-agent',
+};
+
+/**
+ * Decide which busy sessions must have their goal DISARMED before a pending
+ * restart can proceed.
+ *
+ * The decision is taken on the LIVE goal view and on nothing else. A goal may
+ * be disarmed ONLY when ALL of these hold:
+ *  - the goal exists,
+ *  - its phase is `active`,
+ *  - its activation is `armed`,
+ *  - `roundsStarted < maxGoalRounds` (a goal whose round budget is spent can
+ *    never be resumed, so disarming it would strand the work).
+ *
+ * The checkpoint records (`disarmedGoals` / `parkedGoals`) are REPORTING ONLY:
+ * they never veto the decision. A goal that was resumed — and is therefore
+ * armed again — must be disarmable a second time, otherwise the restart waits
+ * for a goal nobody can disarm any more (the exact deadlock this feature
+ * exists to remove). The `disarmedGoals` / `parkedGoals` options are still
+ * accepted for backwards compatibility, but they are not consulted.
+ *
+ * Disarming is safe because it only removes process-local continuation
+ * authority: the durable goal stays `active`, the round that is running right
+ * now still finishes normally, and `ctx.goals.resume(...)` re-arms it after the
+ * restart.
+ *
+ * @param {{ sessionId: string, reason?: string }[]} busyAgents
+ * @param {{
+ *   getGoal?: (sessionId: string) => object|undefined,
+ *   disarmedGoals?: object,
+ *   parkedGoals?: object,
+ * }} [options]
+ * @returns {{
+ *   disarms: { sessionId: string, goalId: string|null, revision: number|null, reason: string }[],
+ *   reported: { sessionId: string, goalId: string|null, reason: string }[],
+ * }}
+ */
+export function selectGoalDisarms(busyAgents, { getGoal, disarmedGoals, parkedGoals } = {}) {
+  const disarms = [];
+  const reported = [];
+  const list = Array.isArray(busyAgents) ? busyAgents : [];
+  // The records are reporting material only: they must never veto a disarm.
+  void disarmedGoals;
+  void parkedGoals;
+  for (const entry of list) {
+    if (!isObject(entry)) continue;
+    const sessionId = entry.sessionId == null ? '' : String(entry.sessionId);
+    if (!sessionId) continue;
+    let goal;
+    try {
+      goal = typeof getGoal === 'function' ? getGoal(sessionId) : undefined;
+    } catch {
+      goal = undefined;
+    }
+    if (!isObject(goal)) continue;
+    const goalId = goal.id == null ? null : String(goal.id);
+    // The LIVE goal decides. A checkpoint record (this plugin disarmed the goal
+    // earlier, or the previous pause-based build parked it) is reporting material
+    // only: it must never veto a disarm, or a goal that was resumed (and is armed
+    // again) could never be disarmed a second time and the restart would wait for
+    // it forever.
+    const phase = typeof goal.phase === 'string' ? goal.phase : '';
+    if (phase !== 'active') {
+      const reason = phase === 'paused'
+        ? GOAL_BLOCK_REASONS.PAUSED
+        : phase === 'blocked'
+          ? GOAL_BLOCK_REASONS.BLOCKED
+          : phase === 'complete'
+            ? GOAL_BLOCK_REASONS.COMPLETE
+            : GOAL_BLOCK_REASONS.NOT_ACTIVE;
+      reported.push({ sessionId, goalId, reason });
+      continue;
+    }
+    if (goal.activation !== 'armed') {
+      reported.push({ sessionId, goalId, reason: GOAL_BLOCK_REASONS.DISARMED });
+      continue;
+    }
+    const roundsStarted = isFiniteNumber(goal.roundsStarted) ? goal.roundsStarted : 0;
+    const maxGoalRounds = isFiniteNumber(goal.maxGoalRounds) ? goal.maxGoalRounds : Infinity;
+    if (roundsStarted >= maxGoalRounds) {
+      reported.push({ sessionId, goalId, reason: GOAL_BLOCK_REASONS.EXHAUSTED });
+      continue;
+    }
+    disarms.push({
+      sessionId,
+      goalId,
+      revision: isFiniteNumber(goal.revision) ? goal.revision : null,
+      reason: GOAL_BLOCK_REASONS.ACTIVE,
+    });
+  }
+  return { disarms, reported };
+}
+
 /**
  * The idle-aware restart policy. Call this on a poll timer (e.g. `deferPollMs`)
  * while `state.restart` exists.
@@ -301,6 +422,272 @@ export function continuationPrompt(
   ].join('\n');
 }
 
+/**
+ * Default character budget of the conversation tail a handoff carries.
+ */
+export const HANDOFF_DEFAULT_MAX_CHARS = 20000;
+
+/** Tokens/characters of a message body, flattened to one plain-text line. */
+function flattenText(value) {
+  if (typeof value !== 'string') return '';
+  return value.replace(/\s+/g, ' ').trim();
+}
+
+/** The tool name of one content block, or a generic label. */
+function toolNameOf(block) {
+  const candidates = [block.name, block.toolName, block.tool, block.id];
+  if (isObject(block.data)) candidates.push(block.data.name, block.data.toolName);
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim() !== '') return candidate.trim();
+  }
+  return 'unknown-tool';
+}
+
+/**
+ * Render one conversation message as plain-text lines. A text block becomes
+ * `role: text`; a tool call / tool result becomes one short line with the tool
+ * name only (tool payloads are never carried).
+ *
+ * @param {unknown} message
+ * @returns {string[]}
+ */
+export function renderMessageLines(message) {
+  if (!isObject(message)) return [];
+  const role = typeof message.role === 'string' && message.role !== '' ? message.role : 'message';
+  const out = [];
+  const pushText = (text) => {
+    const line = flattenText(text);
+    if (line !== '') out.push(`${role}: ${line}`);
+  };
+  const content = message.content;
+  if (typeof content === 'string') {
+    pushText(content);
+    return out;
+  }
+  if (!Array.isArray(content)) return out;
+  for (const block of content) {
+    if (typeof block === 'string') {
+      pushText(block);
+      continue;
+    }
+    if (!isObject(block)) continue;
+    const type = typeof block.type === 'string' ? block.type : '';
+    if (type.includes('tool')) {
+      const label = type.includes('result') ? 'tool result' : 'tool call';
+      out.push(`${label}: ${toolNameOf(block)}`);
+      continue;
+    }
+    if (typeof block.text === 'string') pushText(block.text);
+  }
+  return out;
+}
+
+/**
+ * The tail of a conversation, newest message first, bounded by a character
+ * budget. Rendering stops as soon as adding the next line would exceed the
+ * budget; one oversized single line is truncated so a handoff always carries
+ * something.
+ *
+ * @param {unknown} messages
+ * @param {{ budget?: number }} [options]
+ * @returns {{ lines: string[], chars: number }} `lines` are oldest first
+ */
+export function handoffTail(messages, { budget = HANDOFF_DEFAULT_MAX_CHARS } = {}) {
+  const list = Array.isArray(messages) ? messages : [];
+  const limit = isFiniteNumber(budget) && budget > 0 ? Math.trunc(budget) : HANDOFF_DEFAULT_MAX_CHARS;
+  const picked = [];
+  let chars = 0;
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    const lines = renderMessageLines(list[i]);
+    for (let j = lines.length - 1; j >= 0; j -= 1) {
+      const line = lines[j];
+      const cost = line.length + 1;
+      if (chars + cost > limit) {
+        if (chars === 0 && limit > 16) {
+          const truncated = `${line.slice(0, limit - 1)}…`;
+          picked.push(truncated);
+          chars = truncated.length;
+        }
+        return { lines: picked.reverse(), chars };
+      }
+      picked.push(line);
+      chars += cost;
+    }
+  }
+  return { lines: picked.reverse(), chars };
+}
+
+/**
+ * Compose the text a handoff carries into the fresh session, in this order:
+ * (i) the goal objective, (ii) the recorded handoff context / reasons (most
+ * recent first), (iii) the bounded tail of the earlier conversation (oldest
+ * first), after one line saying this is a trimmed continuation and one line
+ * naming the old session id.
+ *
+ * @param {{
+ *   sessionId?: string|null,
+ *   objective?: string|null,
+ *   goalLabel?: string|null,
+ *   reasons?: string[]|null,
+ *   messages?: unknown,
+ *   maxChars?: number,
+ * }} [options]
+ * @returns {{ text: string, carriedChars: number, tailChars: number, tailLines: number }}
+ */
+export function composeHandoff({
+  sessionId = null,
+  objective = null,
+  goalLabel = null,
+  reasons = null,
+  messages = [],
+  maxChars = HANDOFF_DEFAULT_MAX_CHARS,
+} = {}) {
+  const budget = isFiniteNumber(maxChars) && maxChars > 0 ? Math.trunc(maxChars) : HANDOFF_DEFAULT_MAX_CHARS;
+  const oldId = sessionId == null || sessionId === '' ? '(unknown)' : String(sessionId);
+  const tail = handoffTail(messages, { budget });
+  const lines = [
+    '<continuum_handoff>',
+    'This is a trimmed continuation of an earlier session whose earlier content could not be carried because it exceeded the model context window.',
+    `Old session id: ${oldId}`,
+  ];
+
+  // (i) the goal objective
+  const goalText = flattenText(objective);
+  if (goalText !== '') lines.push(`Goal objective: ${goalText}`);
+  else if (flattenText(goalLabel) !== '') lines.push(`Goal objective: (not recorded) — recorded goal ${flattenText(goalLabel)}`);
+  else lines.push('Goal objective: (no goal recorded)');
+
+  // (ii) the recorded handoff context of that session, most recent first
+  const recorded = Array.isArray(reasons)
+    ? reasons.filter((reason) => typeof reason === 'string' && flattenText(reason) !== '').map(flattenText)
+    : [];
+  if (recorded.length > 0) {
+    lines.push('Recorded checkpoint context of that session (most recent first):');
+    for (const reason of recorded.slice().reverse()) lines.push(`- ${reason}`);
+  } else {
+    lines.push('Recorded checkpoint context of that session: (none recorded)');
+  }
+
+  // (iii) the bounded tail of the conversation, oldest first
+  if (tail.lines.length > 0) {
+    lines.push(`Trimmed tail of the earlier conversation (${tail.lines.length} line(s), ${tail.chars} character(s), oldest first):`);
+    for (const line of tail.lines) lines.push(line);
+  } else {
+    lines.push('Trimmed tail of the earlier conversation: (not available)');
+  }
+
+  lines.push('Continue the work from here: this handoff is the only context carried over from the earlier session.');
+  lines.push('</continuum_handoff>');
+  const text = lines.join('\n');
+  return { text, carriedChars: text.length, tailChars: tail.chars, tailLines: tail.lines.length };
+}
+
+/** A phrase that identifies a failure caused by an oversized context. */
+const CONTEXT_WINDOW_PATTERN = /context[ _-]?(?:window|length)|context_length_exceeded|maximum context/i;
+
+/** A phrase that identifies an exceeded limit next to {@link CONTEXT_WINDOW_PATTERN}. */
+const EXCEED_PATTERN = /exceed|overflow|too (?:long|large|many)|over the limit|maximum/i;
+
+/** The joined text of one message (used for overflow evidence). */
+function messageTextOf(message) {
+  if (!isObject(message)) return '';
+  const parts = [];
+  if (typeof message.content === 'string') parts.push(message.content);
+  else if (Array.isArray(message.content)) {
+    for (const block of message.content) {
+      if (typeof block === 'string') parts.push(block);
+      else if (isObject(block) && typeof block.text === 'string') parts.push(block.text);
+    }
+  }
+  if (typeof message.text === 'string') parts.push(message.text);
+  return parts.join(' ');
+}
+
+/** The failure text of one event-ish object (shallow, never throws). */
+function eventTextOf(event) {
+  if (!isObject(event)) return '';
+  const parts = [];
+  for (const key of ['message', 'error', 'reason', 'text']) {
+    const value = event[key];
+    if (typeof value === 'string') parts.push(value);
+    else if (isObject(value) && typeof value.message === 'string') parts.push(value.message);
+  }
+  if (isObject(event.data)) {
+    for (const key of ['message', 'error', 'text']) {
+      const value = event.data[key];
+      if (typeof value === 'string') parts.push(value);
+      else if (isObject(value) && typeof value.message === 'string') parts.push(value.message);
+    }
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Decide whether a session is over the model context window.
+ *
+ * Evidence, in this order:
+ *  1. the newest assistant message's `usage.inputTokens` versus the session's
+ *     `contextWindow`: overflow when the used tokens EXCEED the window;
+ *  2. a recent message / event whose text says the context window was exceeded.
+ *
+ * When the numbers are unknown, the verdict is NOT overflow: an unknown window
+ * must never block the normal resume path.
+ *
+ * @param {{ messages?: unknown, contextWindow?: number|null, events?: unknown }} [options]
+ * @returns {{ over: boolean, inputTokens: number|null, contextWindow: number|null, detail: string|null }}
+ */
+export function contextOverflow({ messages = [], contextWindow = null, events = [] } = {}) {
+  const list = Array.isArray(messages) ? messages : [];
+  let inputTokens = null;
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    const message = list[i];
+    if (!isObject(message)) continue;
+    const usage = message.usage;
+    if (!isObject(usage)) continue;
+    for (const key of ['inputTokens', 'promptTokens', 'input_tokens']) {
+      if (isFiniteNumber(usage[key]) && usage[key] >= 0) {
+        inputTokens = usage[key];
+        break;
+      }
+    }
+    if (inputTokens !== null) break;
+  }
+  const window = isFiniteNumber(contextWindow) && contextWindow > 0 ? contextWindow : null;
+
+  let failure = '';
+  const scan = (text) => {
+    if (failure !== '' || typeof text !== 'string' || text === '') return;
+    if (CONTEXT_WINDOW_PATTERN.test(text) && EXCEED_PATTERN.test(text)) failure = flattenText(text).slice(0, 200);
+  };
+  for (let i = list.length - 1; i >= 0 && failure === ''; i -= 1) scan(messageTextOf(list[i]));
+  const eventList = Array.isArray(events) ? events.slice(-20) : [];
+  for (let i = eventList.length - 1; i >= 0 && failure === ''; i -= 1) scan(eventTextOf(eventList[i]));
+
+  const numbers = inputTokens !== null && window !== null
+    ? ` (used ${inputTokens} of ${window} tokens)`
+    : inputTokens !== null
+      ? ` (used ${inputTokens} tokens; window unknown)`
+      : '';
+
+  if (failure !== '') {
+    return { over: true, inputTokens, contextWindow: window, detail: `a recent turn failed with a context-window error${numbers}: ${failure}` };
+  }
+  if (inputTokens !== null && window !== null && inputTokens > window) {
+    return {
+      over: true,
+      inputTokens,
+      contextWindow: window,
+      detail: `the last request used ${inputTokens} tokens, which exceeds the model context window of ${window}`,
+    };
+  }
+  return {
+    over: false,
+    inputTokens,
+    contextWindow: window,
+    detail: inputTokens !== null && window !== null ? `used ${inputTokens} of ${window} tokens` : null,
+  };
+}
+
 /**
  * One-line human-readable summary for logs and the health endpoint.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-autorestart",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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",
@@ -34,7 +34,10 @@
     "cordis.patch.yml",
     "locale/*.json",
     "icon.svg",
-    "README.md"
+    "assets/*.png",
+    "screenshots.json",
+    "README.md",
+    "README.zh.md"
   ],
   "dsh": {
     "bundle": {

package/screenshots.json

@@ -0,0 +1,5 @@
+[
+  "assets/screenshot-1.png",
+  "assets/screenshot-2.png",
+  "assets/screenshot-3.png"
+]