dsh-agent-lines 0.3.6 → 0.3.7

package/CHANGELOG.en.md

@@ -2,6 +2,14 @@
 
 English | [中文](CHANGELOG.md)
 
+## 0.3.7 (2026-11-09)
+
+- Added line_handoff: structured handoff snapshots (JSON/Markdown), no model call.
+- line_status / line_list now expose lifecycle/title/generation/pending/lastActivityAt/oldSessionId.
+- rebind sends a noReply handoff notice to the new line; replace reuses the onboarding message.
+- list --json can feed an external dashboard; added examples/dashboard notes.
+- Tests 33/33 pass.
+
 ## 0.3.6 (2026-11-09)
 
 - Added line lifecycle: line_retire, line_rebind, line_create replace:true, line_rename.

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 [English](CHANGELOG.en.md) | 中文
 
+## 0.3.7 (2026-11-09)
+
+- 新增 line_handoff：结构化交接快照（JSON/Markdown），不调用模型。
+- line_status / line_list 增加 lifecycle/title/generation/pending/lastActivityAt/oldSessionId。
+- rebind 后给新线发 noReply 交接通知；replace 复用 onboarding 消息。
+- list --json 可直接喂给外部看板；新增 examples/dashboard 说明。
+- 测试 33/33 通过。
+
 ## 0.3.6 (2026-11-09)
 
 - 新增线生命周期：line_retire、line_rebind、line_create replace:true、line_rename。

package/README.en.md

@@ -36,7 +36,7 @@ The script picks the DSH Web profile, installs the plugin, and verifies agent-li
 
 Offline or when npm is unavailable, use the local tarball:
 
-    bash install.sh ./dsh-agent-lines-0.3.6.tgz
+    bash install.sh ./dsh-agent-lines-0.3.7.tgz
 
 After install and restart, it works without a config. When you want a fixed manager/worker setup, paste the "Manager config" block below into the file printed by the installer.
 
@@ -138,6 +138,7 @@ Tools:
 | `line_claim_manager` | Bind this live root Session as manager; requires `allowClaim: true` and `confirm: "bind-manager"`; global, no shell needed |
 | `line_list` | List lines, status, unread counts, current line and role |
 | `line_create` | Manager only: create a line; same label is idempotent; replace:true swaps the label to a fresh Session |
+| `line_handoff` | Manager only: structured handoff snapshot (JSON/Markdown), no model call |
 | `line_retire` | Manager only: soft-retire; reject new sends, keep Session and history |
 | `line_rebind` | Manager only: atomically switch a line to a new live Session, optionally migrating backlog |
 | `line_rename` | Manager only: rename the sidebar title and persist it in lines.db |

package/README.md

@@ -36,7 +36,7 @@ DSH 的 super agent 平替插件。
 
 离线或 npm 不可用时，用本地 tarball：
 
-    bash install.sh ./dsh-agent-lines-0.3.6.tgz
+    bash install.sh ./dsh-agent-lines-0.3.7.tgz
 
 安装并重启后，不写配置也可以直接使用；需要固定管理线/worker 时，再把下面“管理线配置”粘贴到脚本打印的配置文件。
 
@@ -138,6 +138,7 @@ line_create({ label: "ops", role: "运维" })
 | `line_claim_manager` | 把当前 live 根 Session 绑成 manager；需要 `allowClaim: true` 和 `confirm: "bind-manager"`；全局工具，不需要 shell |
 | `line_list` | 列出线、状态、未读数、当前线和 role |
 | `line_create` | 仅管理线：创建新线；同 label 幂等；传 replace:true 可给同 label 换新 Session |
+| `line_handoff` | 仅管理线：生成结构化交接单（JSON/Markdown），不调模型 |
 | `line_retire` | 仅管理线：软下线；拒绝新发送，保留 Session/历史 |
 | `line_rebind` | 仅管理线：把线原子切到新的 live Session，可迁移积压 |
 | `line_rename` | 仅管理线：改侧栏标题，持久化到 lines.db |

package/docs/PROTOCOL.en.md

@@ -103,6 +103,7 @@ The new line is an ordinary DSH Session in the same DSH process; no OS process,
     line_retire({ line, reason? })
     line_rebind({ line, sessionId, migrate?: "queued" | "none", reason? })
     line_create({ label, replace: true, force?, migrate?, title?, reason? })
+    line_handoff({ line, format?: "md" | "json", limit?: number })
     line_rename({ line, title })
 
 - retired: line_send returns LINE_RETIRED; the Session and history are kept.

package/docs/PROTOCOL.md

@@ -95,6 +95,7 @@ line_move_workspace({ line, workspace }) 把已有线 Session 挂到已有工作
     line_retire({ line, reason? })
     line_rebind({ line, sessionId, migrate?: "queued" | "none", reason? })
     line_create({ label, replace: true, force?, migrate?, title?, reason? })
+    line_handoff({ line, format?: "md" | "json", limit?: number })
     line_rename({ line, title })
 
 - retired：line_send 返回 LINE_RETIRED；Session 和消息历史保留。

package/docs/en/index.html

@@ -43,7 +43,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
 <div class="wrap">
 <header>
   <a class="brand" href="../"><span class="mark"></span>dsh-agent-lines</a>
-  <nav><a href="../">中文</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.6">Release</a></nav>
+  <nav><a href="../">中文</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.7">Release</a></nav>
 </header>
 <main>
 <section class="hero" style="border:0;padding-bottom:22px">
@@ -54,7 +54,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
     <div class="install">curl -fsSL https://raw.githubusercontent.com/Lencen/dsh-agent-lines/main/install.sh -o install.sh &amp;&amp; bash install.sh</div>
     <div class="actions">
       <a class="btn primary" href="https://github.com/Lencen/dsh-agent-lines">GitHub repository</a>
-      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.6">Download 0.3.6</a>
+      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.7">Download 0.3.7</a>
     </div>
   </div>
   <div class="shot">
@@ -92,8 +92,8 @@ research (调研), architecture (架构), uiux (UIUX), dev (开发), test (测
 After the team is ready, wait for my first task. Do not start by yourself.</pre>
   <p style="color:var(--muted);font-size:14px">Restart DSH Web after install or update. Technical details, protocol, and limits: <a href="https://github.com/Lencen/dsh-agent-lines">README / architecture</a>. Community plugin, not an official DeepSeek product.</p>
 </section>
-<footer>dsh-agent-lines 0.3.6 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
+<footer>dsh-agent-lines 0.3.7 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
 </main>
 </div>
 </body>
-</html>
+</html>

package/docs/index.html

@@ -43,7 +43,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
 <div class="wrap">
 <header>
   <a class="brand" href="./"><span class="mark"></span>dsh-agent-lines</a>
-  <nav><a href="en/index.html">English</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.6">Release</a></nav>
+  <nav><a href="en/index.html">English</a><a href="https://github.com/Lencen/dsh-agent-lines">GitHub</a><a href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.7">Release</a></nav>
 </header>
 <main>
 <section class="hero" style="border:0;padding-bottom:22px">
@@ -54,7 +54,7 @@ footer{padding:34px 0 48px;color:var(--muted);font-size:12px}
     <div class="install">curl -fsSL https://raw.githubusercontent.com/Lencen/dsh-agent-lines/main/install.sh -o install.sh &amp;&amp; bash install.sh</div>
     <div class="actions">
       <a class="btn primary" href="https://github.com/Lencen/dsh-agent-lines">GitHub 仓库</a>
-      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.6">下载 0.3.6</a>
+      <a class="btn" href="https://github.com/Lencen/dsh-agent-lines/releases/tag/v0.3.7">下载 0.3.7</a>
     </div>
   </div>
   <div class="shot">
@@ -92,8 +92,8 @@ research（调研）、architecture（架构）、uiux（UIUX）、dev（开发
 团队建好后先待命，不要自动开工，等我发第一个任务。</pre>
   <p style="color:var(--muted);font-size:14px">安装或更新后需要重启 DSH Web。技术细节、协议和限制见 <a href="https://github.com/Lencen/dsh-agent-lines">README / 架构文档</a>。社区插件，不是 DeepSeek 官方产品。</p>
 </section>
-<footer>dsh-agent-lines 0.3.6 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
+<footer>dsh-agent-lines 0.3.7 · Apache-2.0 · Community plugin for DeepSeek Harness. Not an official DeepSeek product.</footer>
 </main>
 </div>
 </body>
-</html>
+</html>

package/docs/market-index.json

@@ -50,11 +50,11 @@
         ]
       },
       "dist-tags": {
-        "latest": "0.3.6"
+        "latest": "0.3.7"
       },
       "versions": [
         {
-          "version": "0.3.6",
+          "version": "0.3.7",
           "publishTimestamp": 1793771000,
           "source": {
             "type": "npm"
@@ -66,4 +66,4 @@
       ]
     }
   ]
-}
+}

package/examples/dashboard/README.md

@@ -0,0 +1,16 @@
+# Dashboard example
+
+The plugin deliberately does not run an HTTP server. Read the same SQLite queue with:
+
+~~~bash
+dsh-agent-lines --json list
+~~~
+
+Fields: label/title/role/lifecycle/generation/pending/unread/lastActivityAt/lease.
+The Surface feedback dashboard (refresh-dashboard.js) can consume this JSON and keep its own directory scan.
+
+For a handoff snapshot before replacing a line:
+
+~~~text
+line_handoff({ line: "writer", format: "json" })
+~~~

package/examples/market-index.json

@@ -50,11 +50,11 @@
         ]
       },
       "dist-tags": {
-        "latest": "0.3.6"
+        "latest": "0.3.7"
       },
       "versions": [
         {
-          "version": "0.3.6",
+          "version": "0.3.7",
           "publishTimestamp": 1793771000,
           "source": {
             "type": "npm"
@@ -66,4 +66,4 @@
       ]
     }
   ]
-}
+}

package/lib/index.js

@@ -297,7 +297,7 @@ export async function apply(ctx, rawConfig) {
 
   const lineTitle = (def, row) => String((row && row.title) || (def && def.title) || (def && def.role) || (def && def.label) || 'agent line').slice(0, 120)
 
-  const rebindLine = async ({ label, sessionId, actor, reason, migrate = 'queued', force = false }) => {
+  const rebindLine = async ({ label, sessionId, actor, reason, migrate = 'queued', force = false, notify = true }) => {
     if (label === config.createFrom) throw new LineError('LINE_MANAGER_REBIND_UNSUPPORTED', 'The manager line is rebound with line_claim_manager, not line_rebind', { line: label })
     const row = store.getLineRow(config.agentId, label)
     if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${config.agentId}#${label}`)
@@ -332,6 +332,15 @@ export async function apply(ctx, rawConfig) {
       startLoop(def)
       const agent = ctx.agents.get(sessionId)
       if (agent !== undefined) bindAgent(agent)
+      if (notify !== false) {
+        try {
+          store.send({
+            agentId: config.agentId, fromLine: config.createFrom, to: label,
+            text: `[Agent Line] ${label} switched to a fresh Session. old=${row.session_id} new=${sessionId} migrated=${JSON.stringify(updated.counts)}. Read the handoff file before continuing.`,
+            noReply: true, maxReplyDepth: config.maxReplyDepth, maxMessageBytes: config.maxMessageBytes,
+          })
+        } catch (error) { ctx.logger?.warn?.('agent-lines: rebind notification failed: %s', String(error)) }
+      }
       return { line: label, oldSessionId: row.session_id, newSessionId: sessionId, generation: updated.generation, counts: updated.counts }
     } catch (error) {
       try { await stopLoopFor(label) } catch { /* best effort */ }
@@ -397,7 +406,7 @@ export async function apply(ctx, rawConfig) {
     const actualSessionId = created.sessionId
     const result = await rebindLine({
       label: existing.label, sessionId: actualSessionId, actor: (exec && exec.agent && exec.agent.session && exec.agent.session.id) || null,
-      reason: String(args.reason || 'line_create replace'), migrate: args.migrate === 'none' ? 'none' : 'queued', force: args.force === true,
+      reason: String(args.reason || 'line_create replace'), migrate: args.migrate === 'none' ? 'none' : 'queued', force: args.force === true, notify: false,
     })
     const newDef = lineDefs.get(actualSessionId)
     if (newDef !== undefined) {

package/lib/store.js

@@ -410,13 +410,19 @@ export class LineStore {
   /** All lines with unread counts and live lease state. */
   listLines(now = Date.now()) {
     const rows = this.#stmt(`SELECT l.*, (SELECT COUNT(*) FROM messages m
-        WHERE m.to_agent = l.agent_id AND m.to_line = l.label AND m.state IN ('queued', 'claimed', 'delivered')) AS unread
+        WHERE m.to_agent = l.agent_id AND m.to_line = l.label AND m.state IN ('queued', 'claimed', 'delivered')) AS unread,
+        (SELECT COUNT(*) FROM messages m
+          WHERE m.to_agent = l.agent_id AND m.to_line = l.label AND m.state IN ('queued', 'claimed')) AS pending,
+        (SELECT MAX(m.created_at) FROM messages m
+          WHERE m.to_agent = l.agent_id AND m.to_line = l.label) AS last_activity_at
       FROM lines l ORDER BY l.agent_id, l.label`).all()
     return rows.map(row => {
       const lease = this.#stmt('SELECT * FROM leases WHERE line_id = ?').get(row.line_id)
       return {
         ...row,
         unread: Number(row.unread),
+        pending: Number(row.pending ?? 0),
+        lastActivityAt: row.last_activity_at === null ? null : Number(row.last_activity_at),
         lease: lease === undefined ? null : {
           instanceId: lease.instance_id,
           expiresAt: lease.expires_at,
@@ -433,9 +439,13 @@ export class LineStore {
     if (row === undefined) return undefined
     const lease = this.#stmt('SELECT * FROM leases WHERE line_id = ?').get(id)
     const unread = this.#stmt(`SELECT COUNT(*) AS n FROM messages WHERE to_agent = ? AND to_line = ? AND state IN ('queued', 'claimed', 'delivered')`).get(agentId, line)
+    const pending = this.#stmt(`SELECT COUNT(*) AS n FROM messages WHERE to_agent = ? AND to_line = ? AND state IN ('queued', 'claimed')`).get(agentId, line)
+    const activity = this.#stmt('SELECT MAX(created_at) AS n FROM messages WHERE to_agent = ? AND to_line = ?').get(agentId, line)
     return {
       ...row,
       unread: Number(unread.n),
+      pending: Number(pending.n),
+      lastActivityAt: activity.n === null ? null : Number(activity.n),
       lease: lease === undefined ? null : { instanceId: lease.instance_id, expiresAt: lease.expires_at, live: lease.expires_at > now },
     }
   }
@@ -532,6 +542,22 @@ export class LineStore {
     return this.#stmt('SELECT * FROM line_events WHERE line_id = ? AND action = ? ORDER BY created_at DESC LIMIT 1').get(id, action)
   }
 
+  /** Structured handoff snapshot: counts + recent messages + lifecycle events. */
+  handoff({ agentId, line, limit = 20, now = Date.now() }) {
+    const row = this.getLine(agentId, line, now)
+    if (row === undefined) throw new LineError('LINE_NOT_FOUND', `No such line: ${lineId(agentId, line)}`)
+    const recent = this.#stmt(`SELECT * FROM messages WHERE to_agent = ? AND to_line = ? ORDER BY created_at DESC LIMIT ?`).all(agentId, line, limit).reverse()
+    const events = this.lineEvents({ agentId, line, limit: 10 })
+    const lastEvent = events.length ? events[0] : null
+    return {
+      line: line, label: line, role: row.role, title: row.title ?? row.role ?? row.label,
+      sessionId: row.session_id, lifecycle: row.lifecycle ?? 'active', generation: row.generation ?? 1,
+      createdBy: row.created_by, createdAt: row.created_at, counts: this.messageCounts({ agentId, line }),
+      lastActivityAt: row.lastActivityAt, oldSessionId: lastEvent && lastEvent.action === 'rebind' ? lastEvent.old_session_id : null,
+      lastEvent, events, messages: recent,
+    }
+  }
+
   /** Recent lifecycle events for diagnostics. */
   lineEvents({ agentId, line, limit = 20 }) {
     const id = lineId(agentId, line)

package/lib/tools.js

@@ -98,6 +98,9 @@ export function registerStatusTool(ctx, { config, store, lineDefs }) {
         title: line.title ?? line.role ?? line.label,
         lifecycle: line.lifecycle ?? 'active',
         generation: line.generation ?? 1,
+        oldSessionId: store.lastLineEvent({ agentId: line.agent_id, line: line.label, action: 'rebind' })?.old_session_id ?? null,
+        pending: line.pending ?? 0,
+        lastActivityAt: line.lastActivityAt ?? null,
         sessionId: line.session_id,
         createdBy: line.created_by,
         lease: line.lease,
@@ -383,6 +386,56 @@ export function registerToolsForAgent(agent, def, { config, store, lineDefs, cre
       },
     }))
 
+    disposers.push(agent.ctx.tools.register({
+      name: 'line_handoff',
+      description: 'Generate a structured handoff snapshot for a line: current metadata, backlog counts, recent messages, lifecycle events. Does not call a model; write the returned markdown to a file before retire/replace/rebind.',
+      parameters: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          line: { type: 'string', description: 'Existing line label' },
+          format: { type: 'string', enum: ['md', 'json'], description: 'md (default) returns markdown; json returns the snapshot object' },
+          limit: { type: 'number', description: 'Recent messages to include, 1-100 (default 20)' },
+        },
+        required: ['line'],
+      },
+      output: OUTPUT,
+      execute: async (args, exec) => {
+        const caller = currentLine(exec, lineDefs)
+        if (caller.label !== config.createFrom) throw new LineError('LINE_CREATE_FORBIDDEN', `Only ${config.createFrom} may create handoffs`, { caller: caller.label })
+        const limit = limitValue(args.limit, 20, 100)
+        const data = store.handoff({ agentId: config.agentId, line: String(args.line), limit })
+        if (args.format === 'json') return data
+        const lines = [
+          '# 交接单 · ' + data.label,
+          '',
+          '## 1 我是谁',
+          '- 角色: ' + (data.role ?? data.label),
+          '- 当前 label: ' + data.label,
+          '- Session: ' + data.sessionId,
+          '- lifecycle: ' + data.lifecycle + ' (generation ' + data.generation + ')',
+          '',
+          '## 2 积压',
+          '- queued: ' + data.counts.queued,
+          '- claimed: ' + data.counts.claimed,
+          '- delivered: ' + data.counts.delivered,
+          '- acked: ' + data.counts.acked,
+          '- failed/expired: ' + (data.counts.failed + data.counts.expired),
+          '',
+          '## 3 最近消息',
+          ...(data.messages.length === 0 ? ['- 无'] : data.messages.map(m => `- ${new Date(m.created_at).toISOString()} [${m.state}] ${m.from_line} -> ${m.to_line}: ${String(m.body).replace(/\s+/g, ' ').slice(0, 180)}`)),
+          '',
+          '## 4 生命周期',
+          ...(data.events.length === 0 ? ['- 无'] : data.events.map(e => `- ${new Date(e.created_at).toISOString()} ${e.action} ${e.old_session_id ? e.old_session_id + ' -> ' : ''}${e.new_session_id ?? ''}`)),
+          '',
+          '## 5 交接提示',
+          '- 先读本文件，再继续工作。',
+          '- 不要复用旧 Session；它只保留历史。',
+          '- 如有 queued/claimed，新线会继续收到。',
+        ]
+        return { line: data.label, format: 'md', markdown: lines.join('\n'), counts: data.counts, sessionId: data.sessionId, generation: data.generation }
+      },
+    }))
+
     disposers.push(agent.ctx.tools.register({
       name: 'line_move_workspace',
       description: 'Move an existing line Session into a target workspace record so it appears under that workspace in the sidebar. DSH only allows attachment when the Session cwd exactly matches the workspace path; it cannot move a Session to a different directory (use a new line for that).',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agent-lines",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "DSH Agent 的持久、可寻址消息线（社区插件）。",
   "type": "module",
   "license": "Apache-2.0",