dsh-hooks 0.7.0 → 0.8.0

package/README.md

@@ -119,9 +119,21 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | aggregated cache-read tokens, when reported |
 | `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | aggregated cache-write tokens, when reported |
 | `DSH_HOOK_USAGE_REASONING_TOKENS` | aggregated reasoning tokens, when reported |
+| `DSH_HOOK_RUNNING_SUBAGENTS` | live subagents still running under this session (turn/end; `0` = none — lets a hook tell "work handed off to background subagents" apart from "the turn finished for real") |
 | `DSH_HOOK_TIMESTAMP` | ISO timestamp |
 
 - `{{var}}` placeholders inside `run` are substituted from the same context, e.g. `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`.
+- `turn/end` hooks are dispatched after the running-subagent count resolves, i.e. one async hop later than other events — an immediately following event from the same session (e.g. the next `turn/start`) may dispatch first.
+
+A common use for `DSH_HOOK_RUNNING_SUBAGENTS` is suppressing the end-of-turn notification while background subagents are still working and only notifying once a turn settles with nothing left running. Note the parent session emits `turn/end` exactly once (with the count > 0); the "everything settled" signal arrives as `turn/end` on the last child session, whose count is `0`:
+
+```yaml
+- on: 'turn/end'
+  match: { runningSubagents: '^0$' }  # anchor the regex: bare '0' also matches '10'
+  run: 'node examples/notify-webhook.mjs'
+```
+
+Settled-but-idle continuable children do not count as running, so they don't keep suppressing the notification.
 
 ## Generic webhook example
 

package/README.zh.md

@@ -119,9 +119,21 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | 本回合缓存读 token（有上报时） |
 | `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | 本回合缓存写 token（有上报时） |
 | `DSH_HOOK_USAGE_REASONING_TOKENS` | 本回合思考 token（有上报时） |
+| `DSH_HOOK_RUNNING_SUBAGENTS` | 本会话下仍在运行的存活子代理数（turn/end；`0` = 无——让 hook 能区分「工作已交给后台子代理」与「回合真正结束」） |
 | `DSH_HOOK_TIMESTAMP` | ISO 时间戳 |
 
 - `run` 里的 `{{变量}}` 占位符会从同一上下文替换，例如 `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`。
+- `turn/end` 的 hook 在运行中子代理计数解析完成后才派发，比其他事件晚一个异步跳——同会话紧随其后的事件（如下一轮 `turn/start`）可能先执行。
+
+`DSH_HOOK_RUNNING_SUBAGENTS` 的典型用法：后台子代理还在运行时抑制回合结束通知，只在本会话回合真正落定时才通知。注意父会话只会收到一次 `turn/end`（此时计数 > 0）；「全部落定」的信号由最后一个子会话自己的 `turn/end`（计数为 `0`）送达：
+
+```yaml
+- on: 'turn/end'
+  match: { runningSubagents: '^0$' }  # 正则要锚定：裸 '0' 也会匹配 '10'
+  run: 'node examples/notify-webhook.mjs'
+```
+
+已落定但闲置（idle）的 continuable 子代理不计入运行中，不会一直压住通知。
 
 ## 执行历史
 

package/lib/context.d.ts

@@ -36,6 +36,12 @@ export interface HookContext {
     usageCacheReadTokens?: number;
     usageCacheWriteTokens?: number;
     usageReasoningTokens?: number;
+    /**
+     * Number of live subagents still running under this session at `turn/end`
+     * (0 = none). Always present on `turn/end`; the plugin fills the real count
+     * from the agents/subagents services when they are available.
+     */
+    runningSubagents?: number;
     timestamp: string;
 }
 export declare function toEnv(ctx: HookContext): Record<string, string>;

package/lib/context.js

@@ -45,6 +45,8 @@ export function toEnv(ctx) {
         env.DSH_HOOK_USAGE_CACHE_WRITE_TOKENS = String(ctx.usageCacheWriteTokens);
     if (ctx.usageReasoningTokens !== undefined)
         env.DSH_HOOK_USAGE_REASONING_TOKENS = String(ctx.usageReasoningTokens);
+    if (ctx.runningSubagents !== undefined)
+        env.DSH_HOOK_RUNNING_SUBAGENTS = String(ctx.runningSubagents);
     return env;
 }
 /** Render `{{DSH_HOOK_*}}` placeholders from the context map. */

package/lib/events.js

@@ -185,6 +185,9 @@ export function turnEndContext(session, turn, reason) {
         usageCacheReadTokens: usage?.cacheReadTokens,
         usageCacheWriteTokens: usage?.cacheWriteTokens,
         usageReasoningTokens: usage?.reasoningTokens,
+        // Default until index.ts fills the live count from the agents/subagents
+        // services (0 = no subagent running under this session).
+        runningSubagents: 0,
     };
 }
 export function turnStartContext(session, turn) {

package/lib/index.d.ts

@@ -3,6 +3,42 @@ import './types.js';
 import { Config } from './config.js';
 import { clearTurnTracking } from './events.js';
 export declare const name = "dsh-hooks";
+/** Minimal structural contract of the optional `agents` service. */
+interface AgentsLike {
+    get(id: string): {
+        id: string;
+        status: string;
+    } | undefined;
+    list(): Array<{
+        id: string;
+        status: string;
+    }>;
+    isOwnedBy(id: string, owner: {
+        id: string;
+    }): boolean;
+}
+/** Minimal structural contract of the optional `subagents` service. */
+interface SubagentsLike {
+    listDescendants(rootSessionId: string): Promise<Array<{
+        id?: string;
+    }>>;
+}
+/**
+ * Count live agents still running in one session's descendant subagent tree.
+ *
+ * Lineage comes from the durable session tree (`subagents.listDescendants`,
+ * driven by the session header `parentSession`): a subagent's runtime owner
+ * in the agents registry is the subagent manager's host-level scope, not the
+ * parent agent, so ownership chains (`agents.isOwnedBy`) cannot find children.
+ * Only agents whose live status is `running` count — a settled/idle
+ * continuable child no longer suppresses the turn/end notification. Returns 0
+ * when the session has no live agent or the services are unavailable.
+ *
+ * The live-registry scan is strictly a fallback for when listing is
+ * unavailable (service absent or listing threw): a successful empty listing
+ * stays empty, so ordinary subagent-free turns don't pay an O(registry) scan.
+ */
+export declare function countRunningSubagents(agents: AgentsLike, subagents: SubagentsLike | undefined, sessionId: string | undefined): Promise<number>;
 export declare const inject: readonly ['sessions'];
 export { Config };
 export { hookMatches, matchFilters } from './events.js';
@@ -15,4 +51,5 @@ export declare const DSH_HOOKS_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-ho
 export declare function apply(ctx: Context, config?: Config): void;
 export declare const _internals: {
     clearTurnTracking: typeof clearTurnTracking;
+    countRunningSubagents: typeof countRunningSubagents;
 };

package/lib/index.js

@@ -8,6 +8,54 @@ import { createHistorySink } from './history.js';
 import { createFeishuSetupManager } from './feishu-session.js';
 import { registerHookRoutes } from './server.js';
 export const name = 'dsh-hooks';
+/**
+ * Count live agents still running in one session's descendant subagent tree.
+ *
+ * Lineage comes from the durable session tree (`subagents.listDescendants`,
+ * driven by the session header `parentSession`): a subagent's runtime owner
+ * in the agents registry is the subagent manager's host-level scope, not the
+ * parent agent, so ownership chains (`agents.isOwnedBy`) cannot find children.
+ * Only agents whose live status is `running` count — a settled/idle
+ * continuable child no longer suppresses the turn/end notification. Returns 0
+ * when the session has no live agent or the services are unavailable.
+ *
+ * The live-registry scan is strictly a fallback for when listing is
+ * unavailable (service absent or listing threw): a successful empty listing
+ * stays empty, so ordinary subagent-free turns don't pay an O(registry) scan.
+ */
+export async function countRunningSubagents(agents, subagents, sessionId) {
+    if (sessionId === undefined || agents.get(sessionId) === undefined)
+        return 0;
+    let ids = [];
+    let listed = false;
+    if (subagents !== undefined) {
+        try {
+            ids = (await subagents.listDescendants(sessionId))
+                .map((row) => row.id)
+                .filter((id) => typeof id === 'string' && id !== sessionId);
+            listed = true;
+        }
+        catch {
+            // listing unavailable — fall back to the live-registry child scan below
+        }
+    }
+    if (!listed) {
+        const owner = agents.get(sessionId);
+        if (owner === undefined)
+            return 0;
+        ids = agents
+            .list()
+            .filter((candidate) => candidate !== owner && agents.isOwnedBy(candidate.id, owner))
+            .map((candidate) => candidate.id);
+    }
+    let count = 0;
+    for (const id of ids) {
+        const agent = agents.get(id);
+        if (agent !== undefined && agent.status === 'running')
+            count++;
+    }
+    return count;
+}
 // Dependency on the session service: `session/event` only exists once a
 // SessionStore is composed, and this plugin consumes the durable firehose.
 export const inject = ['sessions'];
@@ -59,6 +107,32 @@ export function apply(ctx, config = {}) {
             console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(ctxValue)}`);
         }
     };
+    // turn/end: fill the live running-subagent count before dispatching hooks,
+    // so a hook can tell "work handed off to still-running subagents" apart from
+    // "the turn finished for real". The services are read lazily at event time —
+    // at plugin apply time the agents/subagents rows may not be composed yet.
+    let warnedAgentsUnavailable = false;
+    const matchAfterSubagentCount = async (ctxValue, reasonKind) => {
+        const agents = ctx.get('agents', false);
+        if (agents === undefined) {
+            // Warn once, not on every turn/end: profiles without the agents service
+            // would otherwise spam the log on each turn boundary.
+            if (!warnedAgentsUnavailable) {
+                warnedAgentsUnavailable = true;
+                ctx.logger?.warn?.('[dsh-hooks] agents service unavailable at turn/end — runningSubagents stays 0');
+            }
+        }
+        else {
+            const subagents = ctx.get('subagents', false);
+            try {
+                ctxValue.runningSubagents = await countRunningSubagents(agents, subagents, ctxValue.sessionId);
+            }
+            catch (error) {
+                ctx.logger?.warn?.('[dsh-hooks] failed to count running subagents: %s', String(error));
+            }
+        }
+        runMatching(ctxValue, reasonKind);
+    };
     // Durable session firehose: turn boundaries, steps, tool calls, messages,
     // titles, and approval requests.
     ctx.on('session/event', (session, event) => {
@@ -66,7 +140,16 @@ export function apply(ctx, config = {}) {
         if (classified === undefined)
             return;
         const reasonKind = extractReasonKind(event);
-        runMatching(classified, reasonKind);
+        if (classified.event !== 'turn/end') {
+            runMatching(classified, reasonKind);
+            return;
+        }
+        // Dispatch is deferred past the async count; guard the fire-and-forget
+        // promise so a synchronous throw inside dispatch surfaces as a log line
+        // instead of an unhandled rejection.
+        void matchAfterSubagentCount(classified, reasonKind).catch((error) => {
+            ctx.logger?.warn?.('[dsh-hooks] turn/end dispatch failed: %s', String(error));
+        });
     });
     // Session lifecycle (published by the session store, not the firehose).
     ctx.on('session/created', (session) => {
@@ -101,6 +184,6 @@ function extractReasonKind(event) {
         return undefined;
     return typeof e.data?.reason?.kind === 'string' ? e.data.reason.kind : undefined;
 }
-// Referenced only for tree-shaking clarity of the module contract; clearTurnTracking
-// is exported for tests that need deterministic duration bookkeeping.
-export const _internals = { clearTurnTracking };
+// Referenced only for tree-shaking clarity of the module contract; exported
+// for tests that need deterministic bookkeeping.
+export const _internals = { clearTurnTracking, countRunningSubagents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hooks",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "packageManager": "pnpm@11.21.0",
   "description": "Config-driven lifecycle hooks plugin for DeepSeek Harness: declare event -> command hooks in cordis.patch.yml, no plugin code required. Includes a Hooks section in the Web GUI settings (history timeline + manual tester + notify tests + hook editor + Feishu connect).",
   "author": "PeterBon",
@@ -79,7 +79,7 @@
     "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@tsdown/css": "^0.22.14",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.3.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",
     "react": "^18.3.1",