dsh-pause-resume 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 regrevia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# dsh-pause-resume
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One button in the DeepSeek Harness session header. It stops what is running, writes a small plan to
+disk, and after a restart the same button puts that work back.
+
+* ⏸ — work is running. Press to stop it.
+* ▶ — work is stopped, or a previous process died mid-turn. Press to restore it.
+* ⏸ dimmed — nothing to stop and nothing to restore.
+
+The glyph is the only status. There is no counter, no panel and no toast, because a status badge next
+to the button would be a second source of truth for the same fact. A red dot is added only when the
+last press left something for a person to look at.
+
+## What it restores
+
+| Work | Pause | Restore |
+| --- | --- | --- |
+| A session with an unfinished turn | turn cancelled, session recorded | session mounted, then one visible continuation message |
+| A goal that was armed | paused with the revision it had | `goals.resume` with that exact revision; the goal driver continues on its own |
+| A session that only carried that goal | recorded, nothing stopped | mounted; the resumed goal takes over |
+| A running background job | killed and recorded | recorded only: a job is a live process, not replayable |
+| A session that ended normally | untouched | untouched, and never recorded in the first place |
+| A terminal / finished session | untouched | untouched |
+| A schedule | untouched | untouched |
+
+Schedules are not paused: the schedule service has no disable operation, only delete, and deleting a
+person's schedule to pause it is not a trade this plugin makes. A schedule that fires while paused
+starts a turn; the button then shows ⏸ again, truthfully.
+
+## How resume works
+
+A restore is not a claim that work continued. It is three honest steps per item:
+
+1. **Mount.** A stopped session is mounted through the Harness resume path, which preserves its agent
+   preset. If it is already mounted, that step is skipped.
+2. **Continue, only where the press actually cancelled a turn.** The continuation is one ordinary
+   user message sent through `sessionController.prompt`, with a request id derived from the plan and
+   the session. The id makes a repeated restore idempotent, and the message is visible in the
+   transcript, so the person can see exactly what was resumed.
+3. **Re-arm a goal** with the revision it had when paused. The revision is the person's veto: if the
+   goal changed while paused, it is not ours to resume and the item is `skipped`.
+
+Every finished item is journaled before the plan is archived, so a crash in the middle of a restore
+continues with the remainder instead of restoring the same session twice. A failure leaves the plan
+and the journal on disk: the next press retries only the failed item.
+
+## Crash, not just a press
+
+A press writes a snapshot. A crash writes nothing, so the plugin keeps a heartbeat instead:
+`running.json` holds the sessions whose turn is open right now and the id of the process that wrote
+it. A new process finds the previous process's record and offers ▶ with no press needed.
+
+A crash record is deliberately weaker than a press: it proves a turn was open, not whether the person
+wanted it continued. So restore mounts those sessions and lists them in the outcome; it does not
+type a continuation message on their behalf. Sessions that ended normally never enter the file.
+
+The same process reloading the plugin (hot reload) sees its own id and knows there is nothing to
+restore. A `pausing` plan found on disk means the press itself was interrupted: those sessions are
+mounted but never continued, and the button carries a dot until a person presses restore.
+
+## Installing
+
+```bash
+plugin_manager install_bundle dsh-pause-resume
+```
+
+or install the bundle from the Harness plugin manager with the package name. The plugin needs no
+configuration and holds no credentials. `allowRemote` exists for a Harness reached from another
+machine; local-only is the default.
+
+## Guarantees and limits
+
+* **Exclusive.** The phase lives on the Host and is written before any work starts, so two windows,
+  a double press and a tool call cannot overlap. The second caller is told `busy`.
+* **Durable before destructive.** No turn is cancelled until the plan is on disk. A failed write means
+  nothing was stopped.
+* **Idempotent.** A restore journals every finished item; the continuation request id is derived from
+  the plan, so a retry cannot post the same message twice.
+* **Honest.** Unreadable state never reports `paused`. A session deleted by hand, a goal changed by
+  hand, a session already running: each is skipped and named in the outcome.
+* **No hidden takeover.** There is no public API to detach an agent, so the pause guarantee is
+  "turns cancelled, goals paused, jobs killed" — not "the process is frozen". A goal continues because
+  the Harness has a mechanism for that; a plain session continues through one visible user message.
+* **No third-party plugin state.** A plugin's in-process state belongs to that plugin's mount.
+* **Local by default.** The routes require a same-origin request and a plugin header. Remote use must
+  be opted into and still cannot skip the header.
+
+## Files
+
+All state lives under `$DSH_HOME/pause-resume/`:
+
+| File | Purpose |
+| --- | --- |
+| `snapshot.json` | the work a press stopped, `pausing` or `paused` |
+| `journal/<planId>.jsonl` | restore items already finished |
+| `restores/<planId>.json` | the archived plan, kept as a record of the last restore |
+| `last-restore.json` | summary of the last restore |
+| `running.json` | sessions with an open turn, for crash residue |
+
+Every write is a unique temp file, `fsync`, `rename`, then a directory `fsync`. State is never inside
+the package.
+
+## Development
+
+```bash
+npm test
+npm run audit
+```
+
+`lib/engine.js` performs no I/O, `lib/snapshot.js` persists, `lib/probe.js` holds every Harness service
+contract (agent identity, goal revision, per-owner jobs, continuation prompts), and `index.js` only
+wires them to the web routes. All of them are testable without a Harness: `test/apply.test.mjs` mounts
+the plugin against a fake registry.
+
+MIT.
+
+---
+
+一行说明：会话头一个按钮，⏸ 停掉正在跑的回合、目标与后台任务；重启后同一个按钮变 ▶，把上次的工作
+接回来。正常结束的会话不记录、不恢复；崩溃靠心跳文件识别，但只挂载不代发消息；日程不会被动
+（该服务只有删除，没有停用），后台命令只记录不重跑。

package/client.js

@@ -0,0 +1,264 @@
+window.__ModuleLoader__.load({
+  id: 'dsh-pause-resume', // ui-copy-ignore
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+
+    const zh = /^zh/i.test(navigator.language || '')
+    const COPY = zh
+      ? {
+          pause: '暂停', // ui-copy-ignore
+          resume: '继续', // ui-copy-ignore
+          busy: '正在处理', // ui-copy-ignore
+          error: '上次操作没有完成', // ui-copy-ignore
+          partial: '部分内容未能恢复，可以再按一次', // ui-copy-ignore
+          stopped: '上次暂停的内容还没有恢复', // ui-copy-ignore
+          attention: '有内容需要你处理',
+        }
+      : {
+          pause: 'Pause', // ui-copy-ignore
+          resume: 'Resume', // ui-copy-ignore
+          busy: 'Working', // ui-copy-ignore
+          error: 'The last action did not finish',
+          partial: 'Some items were not restored; press again to retry',
+          stopped: 'Work is still stopped',
+          attention: 'Some items need a look',
+        }
+
+    const HOST_BASE = '/dsh-pause-resume' // ui-copy-ignore
+    const POLL_MS = 2000 // ui-copy-ignore
+    const REQUEST_MS = 30000 // ui-copy-ignore
+
+    /**
+     * The glyph is the whole status, so it may not be guessed from anything the page can see: the
+     * Host owns the phase and this asks for it. Until an answer arrives the button renders the // ui-copy-ignore
+     * settled state (`none`), never a spinner, so a slow Host cannot look like a running press. // ui-copy-ignore
+     */
+    const EMPTY = {
+      phase: 'idle', // ui-copy-ignore
+      action: 'none', // ui-copy-ignore
+      source: null, // ui-copy-ignore
+      complete: null, // ui-copy-ignore
+      outstanding: 0,
+      counts: { sessions: 0, goals: 0, jobs: 0 },
+      live: { sessions: 0, goals: 0, jobs: 0 },
+      attention: 0,
+      error: null, // ui-copy-ignore
+    }
+
+    function withTimeout(promise, ms = REQUEST_MS) {
+      let id = null
+      const timer = new Promise((_resolve, reject) => {
+        id = setTimeout(() => reject(new Error('timeout')), ms) // ui-copy-ignore
+      })
+      return Promise.race([promise, timer]).finally(() => clearTimeout(id))
+    }
+
+    async function readState(signal) {
+      try {
+        const response = await withTimeout(fetch(`${HOST_BASE}/state`, { cache: 'no-store', credentials: 'same-origin', signal })) // ui-copy-ignore
+        if (!response.ok) return null
+        const data = await withTimeout(response.json())
+        return data !== null && typeof data === 'object' ? data : null
+      } catch {
+        return null
+      }
+    }
+
+    async function press(action, signal) {
+      try {
+        const response = await withTimeout(fetch(`${HOST_BASE}/${action}`, {
+          method: 'POST', // ui-copy-ignore
+          credentials: 'same-origin',
+          headers: { 'content-type': 'application/json', 'x-dsh-pause-resume': '1' }, // ui-copy-ignore
+          body: '{}', // ui-copy-ignore
+          signal,
+        }))
+        if (!response.ok) return null
+        const data = await withTimeout(response.json())
+        return data !== null && typeof data === 'object' ? data : null
+      } catch {
+        return null
+      }
+    }
+
+    // One style element for the whole page: the in-place spinner is the only motion, and it is
+    // defined once instead of on every render.
+    const STYLE_ID = 'dsh-pause-resume-style' // ui-copy-ignore
+    function ensureStyle() {
+      try {
+        if (document.getElementById(STYLE_ID) !== null) return
+        const style = document.createElement('style')
+        style.id = STYLE_ID
+        style.textContent = '@keyframes dsh-pr-spin{to{transform:rotate(360deg)}}'
+        document.head.appendChild(style)
+      } catch {}
+    }
+
+    const BUTTON_STYLE = {
+      display: 'inline-flex', // ui-copy-ignore
+      alignItems: 'center',
+      justifyContent: 'center',
+      width: 28, // ui-copy-ignore
+      height: 28, // ui-copy-ignore
+      padding: 0, // ui-copy-ignore
+      border: 'none', // ui-copy-ignore
+      borderRadius: 6,
+      background: 'transparent',
+      color: 'inherit', // ui-copy-ignore
+      cursor: 'pointer', // ui-copy-ignore
+      opacity: 0.75, // ui-copy-ignore
+      position: 'relative', // ui-copy-ignore
+    }
+
+    const DOT_STYLE = {
+      position: 'absolute', // ui-copy-ignore
+      top: 4, // ui-copy-ignore
+      right: 4, // ui-copy-ignore
+      width: 5, // ui-copy-ignore
+      height: 5, // ui-copy-ignore
+      borderRadius: '50%',
+      background: 'var(--dsh-color-danger, #d1242f)',
+    }
+
+    const SPIN_STYLE = { display: 'inline-flex', animation: 'dsh-pr-spin 900ms linear infinite' } // ui-copy-ignore
+
+    function icon(paths, extra) {
+      return h('svg', {
+        width: 16, height: 16, viewBox: '0 0 16 16', fill: 'none',
+        stroke: 'currentColor', strokeWidth: 1.6, strokeLinecap: 'round', strokeLinejoin: 'round',
+        'aria-hidden': true, style: extra,
+      }, paths.map((d) => h('path', { key: d, d })))
+    }
+
+    const PAUSE_GLYPH = icon(['M6 3.5v9', 'M10 3.5v9'])
+    const PLAY_GLYPH = h('svg', {
+      width: 16, height: 16, viewBox: '0 0 16 16', fill: 'currentColor', 'aria-hidden': true,
+    }, h('path', { d: 'M5.2 3.4a.7.7 0 0 0-1.05.6v8a.7.7 0 0 0 1.05.6l6.9-4a.7.7 0 0 0 0-1.2l-6.9-4z' }))
+    const SPIN_GLYPH = icon(['M8 2.5a5.5 5.5 0 1 1-4.3 2.06'], SPIN_STYLE)
+
+    /** The one sentence behind the dot, in the tooltip only: the button itself stays a glyph. */
+    function hintOf(state) {
+      if (state.error === 'restore-partial') return COPY.partial
+      if (state.error !== null && state.error !== undefined) return COPY.error
+      if ((state.attention ?? 0) > 0) return COPY.attention
+      if ((state.outstanding ?? 0) > 0) return COPY.stopped
+      return ''
+    }
+
+    function Button() {
+      const [state, setState] = React.useState(EMPTY)
+      const [hover, setHover] = React.useState(false)
+      const [pressing, setPressing] = React.useState(false)
+      const mounted = React.useRef(true)
+      /** Each answer carries a number: a slow reply may never overwrite a newer one. */
+      const seq = React.useRef(0)
+      const inflight = React.useRef(null)
+
+      const apply = React.useCallback((next) => {
+        if (!mounted.current || next === null) return
+        seq.current += 1
+        setState({ ...EMPTY, ...next })
+      }, [])
+
+      const pull = React.useCallback(async (signal) => {
+        const mine = seq.current
+        const next = await readState(signal)
+        if (!mounted.current || seq.current !== mine) return
+        if (next !== null) apply(next)
+      }, [apply])
+
+      React.useEffect(() => {
+        ensureStyle()
+        mounted.current = true
+        let timer = null
+        let current = null
+        const beat = () => {
+          if (document.visibilityState !== 'visible' || inflight.current !== null) return
+          try {
+            current?.abort()
+          } catch {}
+          current = typeof AbortController === 'function' ? new AbortController() : null
+          void pull(current?.signal)
+        }
+        beat()
+        timer = setInterval(beat, POLL_MS)
+        const onVisible = () => {
+          if (document.visibilityState === 'visible') beat()
+        }
+        document.addEventListener('visibilitychange', onVisible)
+        return () => {
+          mounted.current = false
+          if (timer !== null) clearInterval(timer)
+          try {
+            current?.abort()
+          } catch {}
+          document.removeEventListener('visibilitychange', onVisible)
+        }
+      }, [pull])
+
+      const busy = pressing || state.action === 'busy'
+      const action = state.action === 'pause' || state.action === 'resume' ? state.action : null
+      const disabled = action === null && !busy
+
+      const onClick = async () => {
+        if (busy || action === null || inflight.current !== null) return
+        // One press at a time, in this tab and across tabs: the Host also refuses an overlapping // ui-copy-ignore
+        // press, so a second window's button settles on the same answer instead of starting work.
+        const controller = typeof AbortController === 'function' ? new AbortController() : null
+        inflight.current = controller
+        setPressing(true)
+        try {
+          const answer = await press(action, controller?.signal)
+          const next = answer ?? (await readState())
+          if (mounted.current) {
+            if (next !== null) {
+              seq.current += 1
+              setState({ ...EMPTY, ...next })
+            } else {
+              // The press may still have landed: ask again rather than guessing the phase.
+              void pull(controller?.signal)
+            }
+          }
+        } finally {
+          inflight.current = null
+          if (mounted.current) setPressing(false)
+        }
+      }
+
+      const style = busy || disabled
+        ? { ...BUTTON_STYLE, opacity: 0.4 }
+        : hover
+          ? { ...BUTTON_STYLE, opacity: 1, background: 'var(--dsh-color-surface-hover, rgba(127,127,127,0.14))' }
+          : BUTTON_STYLE
+
+      const glyph = busy ? SPIN_GLYPH : action === 'resume' ? PLAY_GLYPH : PAUSE_GLYPH
+      const label = busy ? COPY.busy : action === 'resume' ? COPY.resume : COPY.pause
+      const hint = hintOf(state)
+
+      return h('button', {
+        type: 'button', // ui-copy-ignore
+        style,
+        onClick,
+        disabled,
+        'aria-label': label,
+        'aria-busy': busy,
+        title: hint === '' ? label : `${label} · ${hint}`,
+        onMouseEnter: () => setHover(true),
+        onMouseLeave: () => setHover(false),
+      }, glyph, hint === '' ? null : h('span', { style: DOT_STYLE, 'aria-hidden': true }))
+    }
+
+    return {
+      inject: ['slots'], // ui-copy-ignore
+      apply(ctx) {
+        ctx.slots.inject('conversation.session.header.utilities', () => ctx.slots.register({
+          name: 'conversation.session.header.utilities',
+          id: 'dsh-pause-resume', // ui-copy-ignore
+          order: 31, // ui-copy-ignore
+          label: () => COPY.pause, // ui-copy-ignore
+        }, Button))
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-pause-resume
+      name: 'dsh-pause-resume'

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" role="img" aria-label="Pause and resume">
+  <rect x="1" y="1" width="22" height="22" rx="6" fill="#1f6feb"/>
+  <rect x="6.5" y="6" width="3.2" height="12" rx="1.2" fill="#ffffff"/>
+  <path d="M13.2 6.6v10.8a.6.6 0 0 0 .92.5l8.06-5.4a.7.7 0 0 0 0-1.16l-8.06-5.4a.6.6 0 0 0-.92.5z" fill="#ffffff" fill-opacity="0.55"/>
+  <path d="M12.3 6.4v11.2a.5.5 0 0 0 .77.42l5.6-5.6a.6.6 0 0 0 0-.85l-5.6-5.6a.5.5 0 0 0-.77.42z" fill="#ffffff"/>
+</svg>