@climber47/dsh-step-clock 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 climber47
+
+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

@@ -0,0 +1,84 @@
+# dsh-step-clock
+
+[中文](README.zh.md) | English
+
+A live per-step elapsed-time bar for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) web GUI. It answers one question the built-in turn timer does not: **how long has the step that is running right now been running?**
+
+```
+● 正在执行 bash，已运行 1 分 12 秒    第 12 步   [bash]        1:12
+```
+
+and, once that step finishes, keeps the result on screen:
+
+```
+● 上一步（第 12 步）已完成，用时 3 分 45 秒                    3:45
+```
+
+The bar sits in the composer dock — the strip just above the input box, where the todo and goal bars live — with a second seat below the composer so a tall goal bar cannot push it out of view.
+
+## Why
+
+The harness already shows a turn-level clock at the bottom of the conversation, but it only appears after 15 seconds and it measures the whole turn. When you are watching a long `bash` call you cannot tell whether it started two seconds ago or has been stuck for four minutes, and the turn clock cannot tell you either.
+
+This plugin measures **the current step**, from the instant its activity actually started:
+
+- **Tool steps** are anchored to the tool call's own start time. An in-flight call exists in the live snapshot only while it is in flight, so `0:47` means the call itself has been running 47 seconds — not an estimate derived from the turn.
+- **Thinking steps** fall back to the step boundary, the closest honest anchor for model time.
+- The clock ticks from `0:00` with **no delay threshold**.
+
+## What it says
+
+The bar states the situation in plain language rather than showing a bare number:
+
+| State | Wording |
+| --- | --- |
+| Running a tool | `正在执行 <tool>，已运行 47 秒` |
+| Several tools at once | `正在执行 bash，另有 2 个工具并行，本步已运行 5 秒` |
+| Model streaming | `模型正在思考，本步已耗时 23 秒` |
+| Submitted, no output yet | `已提交，正在等待模型响应，已等待 3 秒` |
+| Finished step | `上一步（第 12 步）已完成，用时 3 分 45 秒` |
+| Nothing running | `空闲，等待下一步` |
+
+Alongside it: the step number, a chip of the running tool names (up to 4, then `+N`, hover for all), and a compact `m:ss` clock at the right edge.
+
+Durations read naturally — `47 秒`, `1 分 12 秒`, `2 分钟`, `1 小时 3 分` — so `0:03` is never ambiguous. The wording is Chinese, matching the language of the session this was built for.
+
+### Why the finished step stays
+
+A step is frequently over in well under a second, so a bar that exists only *during* a step is easy to miss. Holding the last step's duration until the next step replaces it means a slow step — a `bash` call that ran for four minutes, say — can be identified after the fact. The record is kept only when the step's own `start` and `end` timestamps are both present; when they are not, the bar reports itself idle rather than inventing a duration.
+
+## Install
+
+```sh
+dsh plugin --profile web add @climber47/dsh-step-clock
+```
+
+Then restart `dsh web`. The bar appears above the composer during the next running step.
+
+## How it works
+
+A dsh bundle, mounted as one inserted row:
+
+- `package.json` declares `dsh.bundle.patch`, which is what makes the package installable, and `dsh.client` (`platform: web`), which is what serves the browser half.
+- `cordis.patch.yml` inserts the `step-clock` row.
+- `lib/index.js` is the (intentionally empty) host half. A bundle's row resolves the package root, so the package must be importable; this plugin has no host behaviour.
+- `lib/client.js` is the browser half, in the `window.__ModuleLoader__.load({ id, factory })` registration shape a client bundle must have. React is taken from the module loader via `require('react')` rather than bundled.
+- It registers two additive entries — `conversation.input.dock` above the composer and `conversation.composer.dock` below it — both `replaceRisk: none`, so every shipped todo / goal / queue / stats entry is untouched. It owns its stylesheet through `ctx.styles.insert`, disposed with its fiber.
+- The shipped bundle is generated from `src/client/` by `npm run build`, so the readable source and the artifact cannot drift; `npm test` rebuilds and drives the bundle through its real loader contract.
+
+It reads only facts the engine already publishes — the Chat timeline snapshot and the live running-call list — and polls nothing itself.
+
+## Requirements
+
+- dsh `>=0.1.5-rc.1`
+- React 18 (a peer dependency, provided by the harness shell)
+
+## Contributing
+
+`contrib/awesome-dsh-plugin-entry.yml` is the single registry entry this package
+submits to the curated list, kept here so the entry and the code stay in one
+place. It is not part of the npm package.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,78 @@
+# dsh-step-clock
+
+中文 | [English](README.md)
+
+一个给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 网页版用的**单步耗时实时秒表**。它回答内建计时器回答不了的那个问题：**正在跑的这一小步，已经跑了多久？**
+
+```
+● 正在执行 bash，已运行 1 分 12 秒    第 12 步   [bash]        1:12
+```
+
+那一步跑完之后，它会继续把结果留在屏幕上：
+
+```
+● 上一步（第 12 步）已完成，用时 3 分 45 秒                    3:45
+```
+
+状态条位于输入框上方的那一条（和 todo、goal 条同排），并在输入框**下方**另有一处，这样目标条再高也挤不掉它。
+
+## 为什么需要它
+
+Harness 本身已在对话底部显示一个轮次（turn）级时钟，但它**要等 15 秒才出现**，而且计的是**整轮**的时间。当你盯着一个长时间的 `bash` 调用时，你无法判断它是刚开始两秒，还是已经卡了四分钟——那个轮次时钟也回答不了。
+
+本插件计量的是**当前这一小步**，并且从它真正开始活动的时刻起算：
+
+- **工具步骤**锚定在该工具调用自身的开始时间上。运行中的调用只在其运行期间存在于实时快照里，所以 `0:47` 表示**这次调用本身**已跑了 47 秒，而不是从轮次推算出来的估计值。
+- **思考步骤**回退到步骤边界，这是模型耗时最诚实的锚点。
+- 秒表**从 `0:00` 就开始跳，没有任何延迟门槛**。
+
+## 它会说什么
+
+它用直白的中文句子描述当前状况，而不是丢一个光秃秃的数字：
+
+| 状态 | 文案 |
+| --- | --- |
+| 正在执行工具 | `正在执行 <工具名>，已运行 47 秒` |
+| 多个工具并行 | `正在执行 bash，另有 2 个工具并行，本步已运行 5 秒` |
+| 模型流式输出中 | `模型正在思考，本步已耗时 23 秒` |
+| 已提交、还没输出 | `已提交，正在等待模型响应，已等待 3 秒` |
+| 上一步已完成 | `上一步（第 12 步）已完成，用时 3 分 45 秒` |
+| 什么都没跑 | `空闲，等待下一步` |
+
+旁边还有：步号、正在执行的工具名标签（最多 4 个，超出 `+N`，悬停看全部）、以及最右侧一个紧凑的 `m:ss` 数字。
+
+时长按中文习惯换算——`47 秒`、`1 分 12 秒`、`2 分钟`、`1 小时 3 分`——所以`0:03` 不会产生"3 秒还是 3 分钟"的歧义。
+
+### 为什么完成后还要留着
+
+一个步骤经常在一秒内就结束了，只在"运行期间"存在的状态条极易被错过。把上一步的用时留到下一步开始前，你就能**事后**发现某个慢步骤——比如一个跑了四分钟的 `bash`。只有在该步骤自己的 `start` 与 `end` 时间戳**都存在**时才记录；不存在时它会老老实实显示"空闲"，而不是编一个看起来像真的耗时。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @climber47/dsh-step-clock
+```
+
+然后重启 `dsh web`。下一次有步骤运行时，状态条就会出现在输入框上方。
+
+## 实现方式
+
+这是一个 dsh bundle，以单条 insert 行挂载：
+
+- `package.json` 声明 `dsh.bundle.patch`（这是它能被安装的关键）与 `dsh.client`（`platform: web`，这是浏览器半边被加载的关键）。
+- `cordis.patch.yml` 插入 `step-clock` 行。
+- `lib/index.js` 是（有意为空的）宿主半边。bundle 的 insert 行会解析包根，所以包必须可被导入；本插件没有宿主行为。
+- `lib/client.js` 是浏览器半边，采用客户端 bundle 必须的 `window.__ModuleLoader__.load({ id, factory })` 注册形状。React 通过 `require('react')` 从模块加载器取得，不打包进产物。
+- 它注册**两个纯新增**条目——输入框上方的 `conversation.input.dock` 与下方的 `conversation.composer.dock`，两者都是 `replaceRisk: none`，不会动自带的 todo / goal / queue / stats 条目。样式通过 `ctx.styles.insert` 归属自身，随 fiber 一起销毁。
+- 发布的 bundle 由 `npm run build` 从 `src/client/` 生成，因此可读源码与产物不会漂移；`npm test` 会先重新构建，再把 bundle 喂进它真实的加载器契约里跑行为测试。
+
+它只读取引擎**已经发布**的事实——Chat 时间线快照与运行中调用列表——自身不做任何轮询。
+
+## 环境要求
+
+- dsh `>=0.1.5-rc.1`
+- React 18（peer 依赖，由 harness 外壳提供）
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-step-clock bundle patch: inserts its plugin row into the web plugin roster.
+#
+# A single row mounts the package. This plugin has no host behaviour — the
+# browser half (exports "./client") is declared by `dsh.client` in package.json
+# and served from this package's lib/client.js by the client module host.
+- insert:
+    - id: step-clock
+      name: '@climber47/dsh-step-clock'

package/lib/client.js

@@ -0,0 +1,389 @@
+window.__ModuleLoader__.load({
+	id: "@climber47/dsh-step-clock",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		const React = react;
+//#region src/client/styles.js
+/**
+ * @climber47/dsh-step-clock — browser half styles.
+ *
+ * Kept beside the component so the bundle's injected stylesheet has a readable
+ * source. Colours and geometry come from dsh theme tokens and the composer
+ * layout variables, with fallbacks so a missing token degrades instead of
+ * breaking the bar. The `--dsh-composer-*` variables are declared on the
+ * conversation root, which is an ancestor of both dock seats.
+ *
+ * @module @climber47/dsh-step-clock/client/styles
+ */
+
+const CSS = [
+  // The dock row is full viewport width; this wrapper centres a composer-width
+  // column inside it, mirroring the shipped GoalBar dock convention.
+  '.dsh-stepclock-dock{box-sizing:border-box;width:calc(100% - var(--dsh-composer-side-clearance,16px) - var(--dsh-composer-side-clearance,16px) - var(--dsh-composer-dock-inset,8px) - var(--dsh-composer-dock-inset,8px) - var(--dsh-composer-dock-inset,8px) - var(--dsh-composer-dock-inset,8px));margin:0 auto;}',
+  '.dsh-stepclock-root{display:flex;flex-wrap:wrap;align-items:baseline;gap:4px 10px;box-sizing:border-box;width:100%;max-width:calc(var(--dsh-composer-card-max-width,780px) - 4 * var(--dsh-composer-dock-inset,8px));margin:0 auto;padding:6px 12px;border:1px solid var(--dsw-alias-border-l1);border-radius:12px;background:var(--dsw-specific-tip,var(--dsw-alias-bg-layer-2));color:var(--dsw-alias-label-secondary);font-size:13px;line-height:18px;}',
+  // A filled dot marks real activity; a hollow one marks an idle bar.
+  '.dsh-stepclock-dot{flex:none;align-self:center;width:8px;height:8px;border-radius:50%;background:var(--dsw-alias-brand-primary);}',
+  '.dsh-stepclock-dot-idle{flex:none;align-self:center;width:8px;height:8px;border-radius:50%;border:1px solid var(--dsw-alias-border-l2);}',
+  '.dsh-stepclock-say{flex:1 1 auto;min-width:0;color:var(--dsw-alias-label-primary);}',
+  '.dsh-stepclock-where{flex:none;opacity:.6;font-size:12px;}',
+  '.dsh-stepclock-time{flex:none;color:var(--dsw-alias-brand-primary);font-weight:600;font-size:15px;}',
+  '.dsh-stepclock-chip{flex:none;max-width:22em;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;padding:1px 10px;border:1px solid var(--dsw-alias-border-l1);border-radius:999px;background:var(--dsw-alias-bg-layer-1);font-size:12px;line-height:16px;}',
+  '.dsh-stepclock-mono{font-variant-numeric:tabular-nums;font-feature-settings:"tnum";}',
+].join('')
+//#endregion
+//#region src/client/index.js
+/**
+ * @climber47/dsh-step-clock — browser half (readable source).
+ *
+ * The shipped file is `lib/client.js`, which wraps this component in the
+ * `window.__ModuleLoader__.load({ id, factory })` registration shape a dsh
+ * client bundle must have. This file is the same logic kept readable so a
+ * reader can review what the package does without unwrapping the bundle.
+ *
+ * What it does
+ * ------------
+ * Renders one ambient entry in the composer dock while an agent step is
+ * running, in plain language:
+ *
+ *     正在执行 bash，已运行 1 分 12 秒    第 12 步   [bash]        1:12
+ *
+ * and keeps the finished step on screen once it ends:
+ *
+ *     上一步（第 12 步）已完成，用时 3 分 45 秒                    3:45
+ *
+ * Why the second line matters
+ * ---------------------------
+ * A step is often over in under a second, so a bar that only exists *during*
+ * a step is easy to miss entirely. Holding the last step's duration until the
+ * next step replaces it means a slow step can be identified after the fact.
+ * The record is only kept when the step's own `start` and `end` timestamps are
+ * both available; when they are not, the bar says it is idle rather than
+ * inventing a duration.
+ *
+ * It reads the live facts the engine already publishes rather than polling
+ * anything itself:
+ *
+ *   - the open Turn and its open Step, from the Chat timeline snapshot, give
+ *     the step number and the step's start time;
+ *   - `legacy.runningCalls` holds one entry per in-flight Tool call and exists
+ *     only while that call is in flight, so its `time` is the exact moment the
+ *     call started — this is what makes "bash has been running 47s" precise
+ *     instead of an estimate;
+ *   - `legacy.partial` tells whether the model is currently streaming, which
+ *     separates "thinking" from "waiting for the model".
+ *
+ * The clock ticks from 0s with no delay threshold.
+ *
+ * @module @climber47/dsh-step-clock/client
+ */
+
+
+/** Tool names named inline before collapsing the remainder into `+N`. */
+const MAX_NAMES = 4
+
+/**
+ * Last-finished-step records, keyed by session so two open conversations never
+ * clash. Module-level so the record survives re-renders.
+ */
+const RECORDS = new Map()
+
+/** Floor a duration to whole seconds. */
+function secondsOf(ms) {
+  return Math.max(0, Math.floor(ms / 1000))
+}
+
+/**
+ * Natural-language duration: `47 秒` / `1 分 12 秒` / `1 小时 3 分`.
+ * An exact minute drops the redundant `0 秒`; hours imply minutes.
+ * @param ms - duration in milliseconds.
+ * @returns the display string.
+ */
+function humanDuration(ms) {
+  const total = secondsOf(ms)
+  if (total < 60) return total + ' 秒'
+  const minutes = Math.floor(total / 60)
+  if (minutes < 60) {
+    const rest = total % 60
+    return rest === 0 ? minutes + ' 分钟' : minutes + ' 分 ' + rest + ' 秒'
+  }
+  const hours = Math.floor(minutes / 60)
+  const restMinutes = minutes % 60
+  return restMinutes === 0 ? hours + ' 小时' : hours + ' 小时 ' + restMinutes + ' 分'
+}
+
+/**
+ * Compact clock for the right edge: `m:ss`, widening to `h:mm:ss` past an hour.
+ * @param ms - duration in milliseconds.
+ * @returns the display string.
+ */
+function clockOf(ms) {
+  const total = secondsOf(ms)
+  const minutes = Math.floor(total / 60)
+  const seconds = total % 60
+  const pad = function (value) {
+    return (value < 10 ? '0' : '') + value
+  }
+  if (minutes < 60) return minutes + ':' + pad(seconds)
+  return Math.floor(minutes / 60) + ':' + pad(minutes % 60) + ':' + pad(seconds)
+}
+
+/** Newest Turn still open in the loaded timeline, or null. */
+function latestOpenTurn(timeline) {
+  if (timeline === undefined || timeline === null) return null
+  const order = timeline.turnOrder
+  const turns = timeline.turns
+  if (order === undefined || turns === undefined || typeof turns.get !== 'function') return null
+  for (let index = order.length - 1; index >= 0; index -= 1) {
+    const turn = turns.get(order[index])
+    if (turn !== undefined && turn !== null && turn.status === 'open') return turn
+  }
+  return null
+}
+
+/** Newest Step of a Turn, when it is still open. */
+function openStepOf(turn) {
+  const steps = turn.steps
+  if (steps === undefined || steps.length === 0) return null
+  const step = steps[steps.length - 1]
+  if (step === undefined || step === null || step.status !== 'open') return null
+  return step
+}
+
+/** Newest Turn in the loaded timeline whatever its status — the idle record source. */
+function latestTurn(timeline) {
+  if (timeline === undefined || timeline === null) return null
+  const order = timeline.turnOrder
+  const turns = timeline.turns
+  if (order === undefined || turns === undefined || typeof turns.get !== 'function' || order.length === 0) return null
+  return turns.get(order[order.length - 1])
+}
+
+/** Read or create this session's record slot. */
+function recordFor(sessionKey) {
+  const existing = RECORDS.get(sessionKey)
+  if (existing !== undefined) return existing
+  const fresh = { final: null, pending: null, seenTurn: null, seenStep: null }
+  RECORDS.set(sessionKey, fresh)
+  return fresh
+}
+
+/**
+ * The dock entry component.
+ *
+ * Receives only standard slot props: `useChat` selects from the live Chat
+ * snapshot (driving re-render on every engine update) and `timer` supplies a
+ * disposable interval, so nothing here creates a process-wide side effect.
+ */
+function StepClock(props) {
+  const useChat = props.useChat
+  const timer = props.timer
+  const label = props.label === undefined ? '' : props.label
+  const sessionKey = props.sessionId === undefined ? 'default' : String(props.sessionId)
+  // Wall clock, injectable so the duration maths is testable without freezing time.
+  const now = props.now === undefined ? Date.now() : props.now
+  const hold = React.useState(0)
+  const tick = hold[0]
+  const bump = hold[1]
+  const timeline = useChat(function (snapshot) {
+    return snapshot.timeline
+  })
+  const legacy = useChat(function (snapshot) {
+    return snapshot.legacy
+  })
+
+  const turn = latestOpenTurn(timeline)
+  const step = turn === null ? null : openStepOf(turn)
+  const stepNumber = step === null ? 0 : step.step
+  const stepStart =
+    step !== null && step.start !== undefined && step.start !== null && typeof step.start.time === 'number'
+      ? step.start.time
+      : null
+
+  const runningCalls =
+    legacy === undefined || legacy === null || legacy.runningCalls === undefined || legacy.runningCalls === null
+      ? []
+      : legacy.runningCalls
+  const partial = legacy === undefined || legacy === null ? null : legacy.partial
+
+  let firstCallTime = null
+  const names = []
+  let callCount = 0
+  for (let index = 0; index < runningCalls.length; index += 1) {
+    const call = runningCalls[index]
+    if (call === undefined || call === null) continue
+    if (call.step !== stepNumber) continue
+    callCount += 1
+    if (typeof call.time === 'number' && (firstCallTime === null || call.time < firstCallTime)) firstCallTime = call.time
+    if (typeof call.name === 'string' && call.name !== '' && names.indexOf(call.name) < 0) names.push(call.name)
+  }
+
+  const thinking = stepNumber > 0 && partial !== null && partial !== undefined && partial.step === stepNumber
+
+  // A running Tool call is the most precise anchor there is: it starts when the
+  // call is logged and disappears when the result lands. Thinking falls back to
+  // the step boundary, the closest honest anchor for model time.
+  let anchor = firstCallTime
+  if (anchor === null && thinking && stepStart !== null) anchor = stepStart
+  if (anchor === null) anchor = stepStart
+
+  // Always ticking: an active clock needs it, and the idle record has to reveal
+  // itself once its duration is worth reporting.
+  React.useEffect(function () {
+    const dispose = timer.interval(function () {
+      bump(function (value) {
+        return value + 1
+      })
+    }, 500)
+    return function () {
+      if (typeof dispose === 'function') dispose()
+    }
+  }, [])
+
+  const live = turn !== null && step !== null
+
+  // Record the step of any closed Turn.
+  //
+  // Keyed on (turn, step) rather than on the turn alone: the engine reopens a
+  // finished Turn when follow-up work arrives, so a Turn can close more than
+  // once, and a turn-keyed guard would silently stop updating after the first
+  // close. Recording also runs while a Turn is live, which is what lets a
+  // reopened Turn's newly finished step land without waiting for it to close
+  // again.
+  //
+  // Only a step whose own `start` AND `end` are both present is recorded; an
+  // absent pair means the loaded window does not carry the evidence, and the
+  // bar reports itself idle rather than inventing a duration.
+  const record = recordFor(sessionKey)
+  const candidate = latestTurn(timeline)
+  if (candidate !== undefined && candidate !== null) {
+    const steps = candidate.steps
+    const last = steps === undefined || steps === null || steps.length === 0 ? null : steps[steps.length - 1]
+    if (last !== undefined && last !== null && last.status !== 'open') {
+      const began = last.start === undefined || last.start === null ? null : last.start.time
+      const ended = last.end === undefined || last.end === null ? null : last.end.time
+      if (typeof began === 'number' && typeof ended === 'number' && ended >= began) {
+        if (record.seenTurn !== candidate.turn || record.seenStep !== last.step) {
+          record.final = record.pending
+          record.pending = { turn: candidate.turn, step: last.step, ms: ended - began, closedAt: now }
+          record.seenTurn = candidate.turn
+          record.seenStep = last.step
+        }
+      }
+    }
+  }
+
+  let say = ''
+  let where = ''
+  let clock = ''
+  let tone = 'idle'
+  let chips = []
+  const shown = record.pending === null ? record.final : record.pending
+
+  if (live) {
+    tone = 'active'
+    const elapsedMs = anchor === null ? 0 : now - anchor
+    if (callCount > 0) {
+      chips = names.length > MAX_NAMES ? names.slice(0, MAX_NAMES).concat('+' + (names.length - MAX_NAMES)) : names
+      const lead = names.length > 0 ? '正在执行 ' + names[0] : '正在执行工具'
+      say =
+        callCount > 1
+          ? lead + '，另有 ' + (callCount - 1) + ' 个工具并行，本步已运行 ' + humanDuration(elapsedMs)
+          : lead + '，已运行 ' + humanDuration(elapsedMs)
+      where = '第 ' + stepNumber + ' 步'
+    } else if (thinking) {
+      say = '模型正在思考，本步已耗时 ' + humanDuration(elapsedMs)
+      where = '第 ' + stepNumber + ' 步'
+    } else {
+      say = '已提交，正在等待模型响应，已等待 ' + humanDuration(elapsedMs)
+      where = '第 ' + stepNumber + ' 步'
+    }
+    clock = clockOf(elapsedMs)
+  } else if (shown !== null) {
+    // No step is running (yet). Keep reporting the previous step, so the gap
+    // between a Turn closing and the next step starting — and a fresh page load
+    // whose newest Turn is already closed — both stay informative.
+    tone = 'done'
+    say = '上一步（第 ' + shown.step + ' 步）已完成，用时 ' + humanDuration(shown.ms)
+    clock = clockOf(shown.ms)
+  } else {
+    say = '空闲，等待下一步'
+  }
+
+  const children = []
+  children.push(
+    React.createElement('span', {
+      key: 'dot',
+      className: tone === 'idle' ? 'dsh-stepclock-dot-idle' : 'dsh-stepclock-dot',
+    }),
+  )
+  children.push(React.createElement('span', { key: 'say', className: 'dsh-stepclock-say' }, say))
+  if (where !== '') children.push(React.createElement('span', { key: 'where', className: 'dsh-stepclock-where' }, where))
+  if (chips.length > 0) {
+    children.push(
+      React.createElement(
+        'span',
+        { key: 'chips', className: 'dsh-stepclock-chip', title: names.join(' + ') },
+        chips.join(' · '),
+      ),
+    )
+  }
+  if (clock !== '') {
+    children.push(React.createElement('span', { key: 'clock', className: 'dsh-stepclock-time dsh-stepclock-mono' }, clock))
+  }
+
+  return React.createElement(
+    'div',
+    { className: 'dsh-stepclock-dock' },
+    React.createElement(
+      'div',
+      { className: 'dsh-stepclock-root', role: 'status', 'aria-live': 'off', title: label + ' ' + say },
+      children,
+    ),
+  )
+}
+
+/**
+ * Services this plugin waits for before applying.
+ *
+ * Declared rather than assumed: `styles` and `slots` are owned by the renderer
+ * module, and Cordis parks this plugin until they exist instead of calling
+ * `apply` with a half-built context. `timer` supplies the ticking interval.
+ */
+const inject = ['slots', 'styles', 'timer']
+
+/**
+ * Register the dock entry.
+ *
+ * A single additive entry in `conversation.input.dock` (the strip above the
+ * composer, beside the todo / goal / queue bars). `replaceRisk: none`: a fresh
+ * `id` is added beside the shipped entries rather than replacing any of them.
+ */
+function apply(ctx) {
+  ctx.effect(function () {
+    return ctx.styles.insert(CSS)
+  })
+  const mount = function (slot, id, order, label) {
+    ctx.slots.inject(slot, function () {
+      return ctx.slots.register({ name: slot, id: id, order: order }, function (props) {
+        return React.createElement(StepClock, {
+          useChat: props.useChat,
+          timer: ctx.timer,
+          sessionId: props.sessionId,
+          label: label,
+        })
+      })
+    })
+  }
+  mount('conversation.input.dock', 'step-clock', 15, '上')
+}
+//#endregion
+		exports.StepClock = StepClock;
+		exports.CSS = CSS;
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,26 @@
+/**
+ * @climber47/dsh-step-clock — host half.
+ *
+ * This plugin is browser-only: every piece of behaviour is the dock entry in
+ * the client half (`src/client/index.js`, served from `lib/client.js` as the
+ * package's `./client` export and declared through `dsh.client` in
+ * package.json). The host half therefore contributes nothing at runtime.
+ *
+ * It still exists, and is still loaded, because a dsh bundle's inserted row
+ * resolves the package root: a package that could not be imported would not
+ * mount. Both exports below are the empty, valid shape for that contract.
+ *
+ * @module @climber47/dsh-step-clock
+ */
+
+/** No services are required: the host half registers nothing. */
+export const inject = []
+
+/**
+ * Mount the (empty) host half.
+ *
+ * The client half is loaded independently by the client module host, which
+ * scans installed packages for a `dsh.client` declaration; it does not depend
+ * on anything this function does.
+ */
+export function apply() {}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@climber47/dsh-step-clock",
+  "version": "0.1.0",
+  "description": "Live per-step elapsed-time clock for the DeepSeek Harness web GUI: shows which step is running, which tools it is running, and how long it has been going.",
+  "keywords": [
+    "deepseek",
+    "harness",
+    "dsh",
+    "dsh-plugin",
+    "ui"
+  ],
+  "type": "module",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "main": "lib/index.js",
+  "scripts": {
+    "build": "node scripts/build-client.mjs",
+    "test": "node scripts/build-client.mjs && node --test \"tests/**/*.mjs\""
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.1.5-rc.1"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ],
+      "platform": "web"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WsTe47/dsh-step-clock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/WsTe47/dsh-step-clock/issues"
+  },
+  "homepage": "https://github.com/WsTe47/dsh-step-clock#readme",
+  "author": "climber47"
+}

package/src/client/index.js

@@ -0,0 +1,345 @@
+/**
+ * @climber47/dsh-step-clock — browser half (readable source).
+ *
+ * The shipped file is `lib/client.js`, which wraps this component in the
+ * `window.__ModuleLoader__.load({ id, factory })` registration shape a dsh
+ * client bundle must have. This file is the same logic kept readable so a
+ * reader can review what the package does without unwrapping the bundle.
+ *
+ * What it does
+ * ------------
+ * Renders one ambient entry in the composer dock while an agent step is
+ * running, in plain language:
+ *
+ *     正在执行 bash，已运行 1 分 12 秒    第 12 步   [bash]        1:12
+ *
+ * and keeps the finished step on screen once it ends:
+ *
+ *     上一步（第 12 步）已完成，用时 3 分 45 秒                    3:45
+ *
+ * Why the second line matters
+ * ---------------------------
+ * A step is often over in under a second, so a bar that only exists *during*
+ * a step is easy to miss entirely. Holding the last step's duration until the
+ * next step replaces it means a slow step can be identified after the fact.
+ * The record is only kept when the step's own `start` and `end` timestamps are
+ * both available; when they are not, the bar says it is idle rather than
+ * inventing a duration.
+ *
+ * It reads the live facts the engine already publishes rather than polling
+ * anything itself:
+ *
+ *   - the open Turn and its open Step, from the Chat timeline snapshot, give
+ *     the step number and the step's start time;
+ *   - `legacy.runningCalls` holds one entry per in-flight Tool call and exists
+ *     only while that call is in flight, so its `time` is the exact moment the
+ *     call started — this is what makes "bash has been running 47s" precise
+ *     instead of an estimate;
+ *   - `legacy.partial` tells whether the model is currently streaming, which
+ *     separates "thinking" from "waiting for the model".
+ *
+ * The clock ticks from 0s with no delay threshold.
+ *
+ * @module @climber47/dsh-step-clock/client
+ */
+
+import { CSS } from './styles.js'
+
+/** Tool names named inline before collapsing the remainder into `+N`. */
+const MAX_NAMES = 4
+
+/**
+ * Last-finished-step records, keyed by session so two open conversations never
+ * clash. Module-level so the record survives re-renders.
+ */
+const RECORDS = new Map()
+
+/** Floor a duration to whole seconds. */
+function secondsOf(ms) {
+  return Math.max(0, Math.floor(ms / 1000))
+}
+
+/**
+ * Natural-language duration: `47 秒` / `1 分 12 秒` / `1 小时 3 分`.
+ * An exact minute drops the redundant `0 秒`; hours imply minutes.
+ * @param ms - duration in milliseconds.
+ * @returns the display string.
+ */
+function humanDuration(ms) {
+  const total = secondsOf(ms)
+  if (total < 60) return total + ' 秒'
+  const minutes = Math.floor(total / 60)
+  if (minutes < 60) {
+    const rest = total % 60
+    return rest === 0 ? minutes + ' 分钟' : minutes + ' 分 ' + rest + ' 秒'
+  }
+  const hours = Math.floor(minutes / 60)
+  const restMinutes = minutes % 60
+  return restMinutes === 0 ? hours + ' 小时' : hours + ' 小时 ' + restMinutes + ' 分'
+}
+
+/**
+ * Compact clock for the right edge: `m:ss`, widening to `h:mm:ss` past an hour.
+ * @param ms - duration in milliseconds.
+ * @returns the display string.
+ */
+function clockOf(ms) {
+  const total = secondsOf(ms)
+  const minutes = Math.floor(total / 60)
+  const seconds = total % 60
+  const pad = function (value) {
+    return (value < 10 ? '0' : '') + value
+  }
+  if (minutes < 60) return minutes + ':' + pad(seconds)
+  return Math.floor(minutes / 60) + ':' + pad(minutes % 60) + ':' + pad(seconds)
+}
+
+/** Newest Turn still open in the loaded timeline, or null. */
+function latestOpenTurn(timeline) {
+  if (timeline === undefined || timeline === null) return null
+  const order = timeline.turnOrder
+  const turns = timeline.turns
+  if (order === undefined || turns === undefined || typeof turns.get !== 'function') return null
+  for (let index = order.length - 1; index >= 0; index -= 1) {
+    const turn = turns.get(order[index])
+    if (turn !== undefined && turn !== null && turn.status === 'open') return turn
+  }
+  return null
+}
+
+/** Newest Step of a Turn, when it is still open. */
+function openStepOf(turn) {
+  const steps = turn.steps
+  if (steps === undefined || steps.length === 0) return null
+  const step = steps[steps.length - 1]
+  if (step === undefined || step === null || step.status !== 'open') return null
+  return step
+}
+
+/** Newest Turn in the loaded timeline whatever its status — the idle record source. */
+function latestTurn(timeline) {
+  if (timeline === undefined || timeline === null) return null
+  const order = timeline.turnOrder
+  const turns = timeline.turns
+  if (order === undefined || turns === undefined || typeof turns.get !== 'function' || order.length === 0) return null
+  return turns.get(order[order.length - 1])
+}
+
+/** Read or create this session's record slot. */
+function recordFor(sessionKey) {
+  const existing = RECORDS.get(sessionKey)
+  if (existing !== undefined) return existing
+  const fresh = { final: null, pending: null, seenTurn: null, seenStep: null }
+  RECORDS.set(sessionKey, fresh)
+  return fresh
+}
+
+/**
+ * The dock entry component.
+ *
+ * Receives only standard slot props: `useChat` selects from the live Chat
+ * snapshot (driving re-render on every engine update) and `timer` supplies a
+ * disposable interval, so nothing here creates a process-wide side effect.
+ */
+export function StepClock(props) {
+  const useChat = props.useChat
+  const timer = props.timer
+  const label = props.label === undefined ? '' : props.label
+  const sessionKey = props.sessionId === undefined ? 'default' : String(props.sessionId)
+  // Wall clock, injectable so the duration maths is testable without freezing time.
+  const now = props.now === undefined ? Date.now() : props.now
+  const hold = React.useState(0)
+  const tick = hold[0]
+  const bump = hold[1]
+  const timeline = useChat(function (snapshot) {
+    return snapshot.timeline
+  })
+  const legacy = useChat(function (snapshot) {
+    return snapshot.legacy
+  })
+
+  const turn = latestOpenTurn(timeline)
+  const step = turn === null ? null : openStepOf(turn)
+  const stepNumber = step === null ? 0 : step.step
+  const stepStart =
+    step !== null && step.start !== undefined && step.start !== null && typeof step.start.time === 'number'
+      ? step.start.time
+      : null
+
+  const runningCalls =
+    legacy === undefined || legacy === null || legacy.runningCalls === undefined || legacy.runningCalls === null
+      ? []
+      : legacy.runningCalls
+  const partial = legacy === undefined || legacy === null ? null : legacy.partial
+
+  let firstCallTime = null
+  const names = []
+  let callCount = 0
+  for (let index = 0; index < runningCalls.length; index += 1) {
+    const call = runningCalls[index]
+    if (call === undefined || call === null) continue
+    if (call.step !== stepNumber) continue
+    callCount += 1
+    if (typeof call.time === 'number' && (firstCallTime === null || call.time < firstCallTime)) firstCallTime = call.time
+    if (typeof call.name === 'string' && call.name !== '' && names.indexOf(call.name) < 0) names.push(call.name)
+  }
+
+  const thinking = stepNumber > 0 && partial !== null && partial !== undefined && partial.step === stepNumber
+
+  // A running Tool call is the most precise anchor there is: it starts when the
+  // call is logged and disappears when the result lands. Thinking falls back to
+  // the step boundary, the closest honest anchor for model time.
+  let anchor = firstCallTime
+  if (anchor === null && thinking && stepStart !== null) anchor = stepStart
+  if (anchor === null) anchor = stepStart
+
+  // Always ticking: an active clock needs it, and the idle record has to reveal
+  // itself once its duration is worth reporting.
+  React.useEffect(function () {
+    const dispose = timer.interval(function () {
+      bump(function (value) {
+        return value + 1
+      })
+    }, 500)
+    return function () {
+      if (typeof dispose === 'function') dispose()
+    }
+  }, [])
+
+  const live = turn !== null && step !== null
+
+  // Record the step of any closed Turn.
+  //
+  // Keyed on (turn, step) rather than on the turn alone: the engine reopens a
+  // finished Turn when follow-up work arrives, so a Turn can close more than
+  // once, and a turn-keyed guard would silently stop updating after the first
+  // close. Recording also runs while a Turn is live, which is what lets a
+  // reopened Turn's newly finished step land without waiting for it to close
+  // again.
+  //
+  // Only a step whose own `start` AND `end` are both present is recorded; an
+  // absent pair means the loaded window does not carry the evidence, and the
+  // bar reports itself idle rather than inventing a duration.
+  const record = recordFor(sessionKey)
+  const candidate = latestTurn(timeline)
+  if (candidate !== undefined && candidate !== null) {
+    const steps = candidate.steps
+    const last = steps === undefined || steps === null || steps.length === 0 ? null : steps[steps.length - 1]
+    if (last !== undefined && last !== null && last.status !== 'open') {
+      const began = last.start === undefined || last.start === null ? null : last.start.time
+      const ended = last.end === undefined || last.end === null ? null : last.end.time
+      if (typeof began === 'number' && typeof ended === 'number' && ended >= began) {
+        if (record.seenTurn !== candidate.turn || record.seenStep !== last.step) {
+          record.final = record.pending
+          record.pending = { turn: candidate.turn, step: last.step, ms: ended - began, closedAt: now }
+          record.seenTurn = candidate.turn
+          record.seenStep = last.step
+        }
+      }
+    }
+  }
+
+  let say = ''
+  let where = ''
+  let clock = ''
+  let tone = 'idle'
+  let chips = []
+  const shown = record.pending === null ? record.final : record.pending
+
+  if (live) {
+    tone = 'active'
+    const elapsedMs = anchor === null ? 0 : now - anchor
+    if (callCount > 0) {
+      chips = names.length > MAX_NAMES ? names.slice(0, MAX_NAMES).concat('+' + (names.length - MAX_NAMES)) : names
+      const lead = names.length > 0 ? '正在执行 ' + names[0] : '正在执行工具'
+      say =
+        callCount > 1
+          ? lead + '，另有 ' + (callCount - 1) + ' 个工具并行，本步已运行 ' + humanDuration(elapsedMs)
+          : lead + '，已运行 ' + humanDuration(elapsedMs)
+      where = '第 ' + stepNumber + ' 步'
+    } else if (thinking) {
+      say = '模型正在思考，本步已耗时 ' + humanDuration(elapsedMs)
+      where = '第 ' + stepNumber + ' 步'
+    } else {
+      say = '已提交，正在等待模型响应，已等待 ' + humanDuration(elapsedMs)
+      where = '第 ' + stepNumber + ' 步'
+    }
+    clock = clockOf(elapsedMs)
+  } else if (shown !== null) {
+    // No step is running (yet). Keep reporting the previous step, so the gap
+    // between a Turn closing and the next step starting — and a fresh page load
+    // whose newest Turn is already closed — both stay informative.
+    tone = 'done'
+    say = '上一步（第 ' + shown.step + ' 步）已完成，用时 ' + humanDuration(shown.ms)
+    clock = clockOf(shown.ms)
+  } else {
+    say = '空闲，等待下一步'
+  }
+
+  const children = []
+  children.push(
+    React.createElement('span', {
+      key: 'dot',
+      className: tone === 'idle' ? 'dsh-stepclock-dot-idle' : 'dsh-stepclock-dot',
+    }),
+  )
+  children.push(React.createElement('span', { key: 'say', className: 'dsh-stepclock-say' }, say))
+  if (where !== '') children.push(React.createElement('span', { key: 'where', className: 'dsh-stepclock-where' }, where))
+  if (chips.length > 0) {
+    children.push(
+      React.createElement(
+        'span',
+        { key: 'chips', className: 'dsh-stepclock-chip', title: names.join(' + ') },
+        chips.join(' · '),
+      ),
+    )
+  }
+  if (clock !== '') {
+    children.push(React.createElement('span', { key: 'clock', className: 'dsh-stepclock-time dsh-stepclock-mono' }, clock))
+  }
+
+  return React.createElement(
+    'div',
+    { className: 'dsh-stepclock-dock' },
+    React.createElement(
+      'div',
+      { className: 'dsh-stepclock-root', role: 'status', 'aria-live': 'off', title: label + ' ' + say },
+      children,
+    ),
+  )
+}
+
+/**
+ * Services this plugin waits for before applying.
+ *
+ * Declared rather than assumed: `styles` and `slots` are owned by the renderer
+ * module, and Cordis parks this plugin until they exist instead of calling
+ * `apply` with a half-built context. `timer` supplies the ticking interval.
+ */
+export const inject = ['slots', 'styles', 'timer']
+
+/**
+ * Register the dock entry.
+ *
+ * A single additive entry in `conversation.input.dock` (the strip above the
+ * composer, beside the todo / goal / queue bars). `replaceRisk: none`: a fresh
+ * `id` is added beside the shipped entries rather than replacing any of them.
+ */
+export function apply(ctx) {
+  ctx.effect(function () {
+    return ctx.styles.insert(CSS)
+  })
+  const mount = function (slot, id, order, label) {
+    ctx.slots.inject(slot, function () {
+      return ctx.slots.register({ name: slot, id: id, order: order }, function (props) {
+        return React.createElement(StepClock, {
+          useChat: props.useChat,
+          timer: ctx.timer,
+          sessionId: props.sessionId,
+          label: label,
+        })
+      })
+    })
+  }
+  mount('conversation.input.dock', 'step-clock', 15, '上')
+}

package/src/client/styles.js

@@ -0,0 +1,26 @@
+/**
+ * @climber47/dsh-step-clock — browser half styles.
+ *
+ * Kept beside the component so the bundle's injected stylesheet has a readable
+ * source. Colours and geometry come from dsh theme tokens and the composer
+ * layout variables, with fallbacks so a missing token degrades instead of
+ * breaking the bar. The `--dsh-composer-*` variables are declared on the
+ * conversation root, which is an ancestor of both dock seats.
+ *
+ * @module @climber47/dsh-step-clock/client/styles
+ */
+
+export const CSS = [
+  // The dock row is full viewport width; this wrapper centres a composer-width
+  // column inside it, mirroring the shipped GoalBar dock convention.
+  '.dsh-stepclock-dock{box-sizing:border-box;width:calc(100% - var(--dsh-composer-side-clearance,16px) - var(--dsh-composer-side-clearance,16px) - var(--dsh-composer-dock-inset,8px) - var(--dsh-composer-dock-inset,8px) - var(--dsh-composer-dock-inset,8px) - var(--dsh-composer-dock-inset,8px));margin:0 auto;}',
+  '.dsh-stepclock-root{display:flex;flex-wrap:wrap;align-items:baseline;gap:4px 10px;box-sizing:border-box;width:100%;max-width:calc(var(--dsh-composer-card-max-width,780px) - 4 * var(--dsh-composer-dock-inset,8px));margin:0 auto;padding:6px 12px;border:1px solid var(--dsw-alias-border-l1);border-radius:12px;background:var(--dsw-specific-tip,var(--dsw-alias-bg-layer-2));color:var(--dsw-alias-label-secondary);font-size:13px;line-height:18px;}',
+  // A filled dot marks real activity; a hollow one marks an idle bar.
+  '.dsh-stepclock-dot{flex:none;align-self:center;width:8px;height:8px;border-radius:50%;background:var(--dsw-alias-brand-primary);}',
+  '.dsh-stepclock-dot-idle{flex:none;align-self:center;width:8px;height:8px;border-radius:50%;border:1px solid var(--dsw-alias-border-l2);}',
+  '.dsh-stepclock-say{flex:1 1 auto;min-width:0;color:var(--dsw-alias-label-primary);}',
+  '.dsh-stepclock-where{flex:none;opacity:.6;font-size:12px;}',
+  '.dsh-stepclock-time{flex:none;color:var(--dsw-alias-brand-primary);font-weight:600;font-size:15px;}',
+  '.dsh-stepclock-chip{flex:none;max-width:22em;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;padding:1px 10px;border:1px solid var(--dsw-alias-border-l1);border-radius:999px;background:var(--dsw-alias-bg-layer-1);font-size:12px;line-height:16px;}',
+  '.dsh-stepclock-mono{font-variant-numeric:tabular-nums;font-feature-settings:"tnum";}',
+].join('')