dsh-hooks 0.11.0 → 0.13.0

package/lib/dry-run.js

@@ -9,6 +9,8 @@ import { join } from 'node:path';
 import YAML from 'yaml';
 import { Config } from './config.js';
 import { matchFilters } from './events.js';
+import { DEFAULT_HISTORY_PATH } from './history.js';
+import { localDayKey } from './usage.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify } from './notify.js';
 /** Profile patch file for a profile name. */
@@ -16,12 +18,10 @@ export function patchFilePath(profile) {
     return join(homedir(), '.dsh', 'profiles', profile, 'cordis.patch.yml');
 }
 /**
- * Load and normalize the dsh-hooks config block from a profile's
- * cordis.patch.yml. Runs the block through the Config schema so match
- * regexes compile and invalid entries fail loudly.
+ * Raw `dsh-hooks` config block from a profile's cordis.patch.yml. Throws on a
+ * missing/unreadable file — callers that must stay lenient catch it.
  */
-export function loadHooks(profile, paths = {}) {
-    const file = paths.patchFile ?? patchFilePath(profile);
+function readConfigBlock(file) {
     if (!existsSync(file))
         throw new Error(`未找到 ${file}（profile 不存在或没有 cordis.patch.yml）`);
     let entries;
@@ -33,22 +33,88 @@ export function loadHooks(profile, paths = {}) {
     }
     if (!Array.isArray(entries))
         throw new Error('cordis.patch.yml 顶层必须是 YAML 数组');
-    let block;
     for (const entry of entries) {
         if (entry !== null && typeof entry === 'object' && entry.id === 'dsh-hooks') {
-            block = entry;
-            break;
+            return entry;
         }
     }
-    if (block === undefined)
-        throw new Error('cordis.patch.yml 中没有 id: dsh-hooks 的配置块');
+    throw new Error('cordis.patch.yml 中没有 id: dsh-hooks 的配置块');
+}
+/**
+ * Load and normalize the dsh-hooks config block from a profile's
+ * cordis.patch.yml. Runs the block through the Config schema so match
+ * regexes compile and invalid entries fail loudly.
+ */
+export function loadHooks(profile, paths = {}) {
+    const file = paths.patchFile ?? patchFilePath(profile);
+    const block = readConfigBlock(file);
     const rawHooks = block.config?.hooks;
     const config = Config({ hooks: (Array.isArray(rawHooks) ? rawHooks : []) });
     return { hooks: config.hooks ?? [], source: file };
 }
+/**
+ * Resolve the JSONL path a profile's dsh-hooks config writes history to
+ * (`config.history.path`, else the plugin default). Deliberately lenient:
+ * `tail` must keep working while the config file is missing or mid-edit.
+ */
+export function loadHistoryPath(profile, paths = {}) {
+    const file = paths.patchFile ?? patchFilePath(profile);
+    try {
+        const block = readConfigBlock(file);
+        const configured = block.config?.history?.path;
+        if (typeof configured === 'string' && configured.trim() !== '')
+            return configured;
+    }
+    catch {
+        // Missing/broken config: fall through to the plugin default.
+    }
+    return DEFAULT_HISTORY_PATH;
+}
+/**
+ * Numeric context fields a simulated event may override — the ones a `match`
+ * comparison can meaningfully target. Strings keep their dedicated CLI flag /
+ * tester input (`--tool`, `--session-name`, …) and the mock defaults.
+ */
+export const MOCK_NUMERIC_FIELDS = [
+    'turn',
+    'step',
+    'durationMs',
+    'toolDurationMs',
+    'runningSubagents',
+    'totalSubagents',
+    'treeDurationMs',
+    'usageTurns',
+    'usageSessions',
+    'usageInputTokens',
+    'usageOutputTokens',
+    'usageCacheReadTokens',
+    'usageCacheWriteTokens',
+    'usageReasoningTokens',
+];
+/**
+ * Apply explicit numeric overrides to a simulated context. Values must be
+ * finite numbers; anything else (unknown field, string, NaN) is reported in
+ * `ignored` instead of being silently coerced — a tester must never "pass"
+ * because a filter was fed the wrong type.
+ */
+export function applyMockFields(ctx, fields) {
+    if (fields === undefined)
+        return { ctx, ignored: [] };
+    const next = { ...ctx };
+    const ignored = [];
+    for (const [key, value] of Object.entries(fields)) {
+        if (!MOCK_NUMERIC_FIELDS.includes(key) || typeof value !== 'number' || !Number.isFinite(value)) {
+            ignored.push(key);
+            continue;
+        }
+        ;
+        next[key] = value;
+    }
+    return { ctx: next, ignored };
+}
 /** A synthetic context for the simulated event, overridable per field. */
 export function mockContext(event, overrides = {}) {
-    return {
+    const ctx = {
         event,
         sessionId: 'dry-run',
         sessionName: 'dry-run 会话',
@@ -59,8 +125,27 @@ export function mockContext(event, overrides = {}) {
         callId: 'dry-run-call',
         content: 'dry-run 模拟内容',
         timestamp: new Date().toISOString(),
-        ...overrides,
     };
+    if (event === 'turn/end') {
+        // The real turn/end context ALWAYS carries the live subagent count (0 when
+        // none are running), so the mock must too — otherwise the documented
+        // `match: { runningSubagents: '^0$' }` pattern could never match here.
+        ctx.runningSubagents = 0;
+    }
+    if (event === 'usage/daily') {
+        // A daily report always describes a day that already ended, and the
+        // simulated numbers must be non-zero so `match` filters on them (e.g.
+        // `{ usageInputTokens: '>0' }`) are actually exercisable.
+        ctx.usageDay = localDayKey(new Date(Date.now() - 86_400_000));
+        ctx.usageTurns = 12;
+        ctx.usageSessions = 3;
+        ctx.usageInputTokens = 120_000;
+        ctx.usageOutputTokens = 45_000;
+        ctx.usageCacheReadTokens = 90_000;
+        ctx.usageCacheWriteTokens = 6_000;
+        ctx.usageReasoningTokens = 8_000;
+    }
+    return { ...ctx, ...overrides };
 }
 /** Render a match value (regex source, comparison op, or object form). */
 function matchText(value) {
@@ -111,14 +196,23 @@ export async function runDryRun(options) {
     const print = options.print ?? console.log;
     const { hooks, source } = loadHooks(profile, options.paths);
     const reasonKind = options.reason;
-    const ctx = mockContext(options.event, {
+    const simulated = applyMockFields(mockContext(options.event, {
         reason: reasonKind,
         tool: options.tool,
         sessionName: options.sessionName,
-    });
+    }), options.fields);
+    const ctx = simulated.ctx;
     print('dsh-hooks dry-run');
     print(`配置来源：${source}（${hooks.length} 个 hook）`);
     print(`模拟事件：${options.event}${reasonKind ? `（reason=${reasonKind}）` : ''}`);
+    if (options.fields !== undefined && Object.keys(options.fields).length > 0) {
+        const applied = Object.keys(options.fields).filter((key) => !simulated.ignored.includes(key));
+        if (applied.length > 0)
+            print(`模拟字段：${applied.map((key) => `${key}=${String(options.fields?.[key])}`).join(', ')}`);
+    }
+    if (simulated.ignored.length > 0) {
+        print(`⚠ 已忽略无法模拟的字段：${simulated.ignored.join(', ')}（可用：${MOCK_NUMERIC_FIELDS.join(' / ')}）`);
+    }
     const lines = evaluateHooks(hooks, options.event, ctx, reasonKind);
     for (const line of lines) {
         print(line.matched ? `✅ [${line.index}] ${line.summary}` : `⏭ [${line.index}] ${line.summary} —— ${line.why}`);
@@ -139,7 +233,7 @@ export async function runDryRun(options) {
             }
             else if (hook.notify) {
                 print(`▶ 发送 [${line.index}] notify:${hook.notify.channel}`);
-                await fireNotify(hook.notify, ctx);
+                await fireNotify(hook.notify, ctx, undefined, { retries: hook.retries, retryDelayMs: hook.retryDelayMs });
             }
         }
         print('（run 命令 fire-and-forget：执行结果见 dsh 日志）');

package/lib/events.d.ts

@@ -1,7 +1,9 @@
 import type { Session, SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session';
 import type { HookContext } from './context.js';
 import type { HookSpec, NumericMatch, TurnEndReasonKind } from './config.js';
+import type { DailyUsageTotals, UsageTotals } from './usage.js';
 import type { AgentLike } from './types.js';
+export type { UsageTotals } from './usage.js';
 /** `approval/asked` payload (merge-extensible, declared by dsh-user-approval). */
 export interface ApprovalAskedData {
     id: string;
@@ -65,14 +67,6 @@ export declare function sessionTitle(session: Session): string | undefined;
  * their own display truncation.
  */
 export declare function turnContent(session: Session, turn: number): string | undefined;
-/** Aggregated turn usage for hook contexts (only fields actually reported). */
-export interface UsageTotals {
-    inputTokens: number;
-    outputTokens: number;
-    cacheReadTokens?: number;
-    cacheWriteTokens?: number;
-    reasoningTokens?: number;
-}
 /**
  * Sum the `usage` of every `assistant/message` of a turn. Steps without
  * reported accounting are skipped; returns undefined when no step reported
@@ -128,6 +122,16 @@ export declare function treeSettledContext(session: Session, totalSubagents: num
  * session identity of the event that triggered the failing hook.
  */
 export declare function hookFailedContext(origin: HookContext, hookFailedHook: string, hookFailures: number): HookContext;
+/**
+ * Synthetic `usage/daily` context: the local calendar day that just ended,
+ * with its aggregated token usage. Emitted by index.ts when the day rolls
+ * over (detected from ordinary event traffic — no timers); `origin` supplies
+ * the session identity of the event that triggered the report.
+ *
+ * The token fields reuse the `turn/end` names on purpose: a hook reads the
+ * same variables, with the day's aggregate instead of one turn's.
+ */
+export declare function usageDailyContext(origin: HookContext, totals: DailyUsageTotals): HookContext;
 export declare function agentCreatedContext(agent: AgentLike): HookContext;
 export declare function agentDisposedContext(agent: AgentLike): HookContext;
 export declare function agentErrorContext(agent: AgentLike, turn: number | undefined, error: unknown): HookContext;

package/lib/events.js

@@ -403,6 +403,34 @@ export function hookFailedContext(origin, hookFailedHook, hookFailures) {
         timestamp: new Date().toISOString(),
     };
 }
+/**
+ * Synthetic `usage/daily` context: the local calendar day that just ended,
+ * with its aggregated token usage. Emitted by index.ts when the day rolls
+ * over (detected from ordinary event traffic — no timers); `origin` supplies
+ * the session identity of the event that triggered the report.
+ *
+ * The token fields reuse the `turn/end` names on purpose: a hook reads the
+ * same variables, with the day's aggregate instead of one turn's.
+ */
+export function usageDailyContext(origin, totals) {
+    return {
+        event: 'usage/daily',
+        sessionId: origin.sessionId,
+        sessionName: origin.sessionName,
+        cwd: origin.cwd,
+        usageDay: totals.day,
+        usageTurns: totals.turns,
+        usageSessions: totals.sessions,
+        usageInputTokens: totals.inputTokens,
+        usageOutputTokens: totals.outputTokens,
+        // Only fields some turn actually reported: an absent variable is easier to
+        // reason about (and to match on) than one that is present-but-undefined.
+        ...(totals.cacheReadTokens !== undefined ? { usageCacheReadTokens: totals.cacheReadTokens } : {}),
+        ...(totals.cacheWriteTokens !== undefined ? { usageCacheWriteTokens: totals.cacheWriteTokens } : {}),
+        ...(totals.reasoningTokens !== undefined ? { usageReasoningTokens: totals.reasoningTokens } : {}),
+        timestamp: new Date().toISOString(),
+    };
+}
 export function agentCreatedContext(agent) {
     return {
         event: 'agent/created',

package/lib/index.d.ts

@@ -59,7 +59,7 @@ export { createHistorySink } from './history.js';
  * Model-facing announcement, installed only when the system-prompt service
  * exists (web profile). Tells agents the plugin exists and how to cooperate.
  */
-export declare const DSH_HOOKS_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-hooks \u63D2\u4EF6\uFF08DeepSeek Harness \u914D\u7F6E\u9A71\u52A8\u751F\u547D\u5468\u671F hooks\uFF09\uFF1A\u53EF\u5728 profile \u7684 cordis.patch.yml \u58F0\u660E\u300C\u4E8B\u4EF6 \u2192 \u547D\u4EE4/\u901A\u77E5\u300D\u7684 hook\uFF08turn/start\u3001turn/end\u3001tree/settled\u3001step/end\u3001tool/call\u3001tool/result\u3001user/message\u3001approval/asked\u3001approval/decided\u3001session/title\u3001session/created\u3001session/disposed\u3001agent/created\u3001agent/disposed\u3001agent/error\u3001agent/status\u3001hook/failed \u5171 17 \u7C7B\u4E8B\u4EF6\uFF09\uFF0C\u652F\u6301 when \u539F\u56E0\u8FC7\u6EE4\u3001match \u5B57\u6BB5\u6B63\u5219/\u6570\u503C\u6BD4\u8F83\u8FC7\u6EE4\uFF08\u5982 '>10000'\uFF09\u3001stdin JSON \u8F93\u5165\u3001opt-in \u91CD\u8BD5\u3001\u6267\u884C\u9009\u9879\uFF08enabled \u505C\u7528 / cwd \u5DE5\u4F5C\u76EE\u5F55 / maxConcurrent + debounceMs \u9632\u9AD8\u9891\u98CE\u66B4\uFF09\u3001\u5185\u7F6E webhook/desktop \u901A\u77E5\u6E20\u9053\uFF1B\u6267\u884C\u5386\u53F2\u8BB0\u5F55\u4E8E ~/.dsh/dsh-hooks/history.jsonl\uFF1B`dsh-hooks dry-run <event>` \u53EF\u6A21\u62DF\u4E8B\u4EF6\u9A8C\u8BC1\u914D\u7F6E\u3002\u7528\u6237\u63D0\u5230\u300Chooks / \u94A9\u5B50 / \u751F\u547D\u5468\u671F / \u901A\u77E5\u914D\u7F6E\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
+export declare const DSH_HOOKS_GUIDANCE = "\u672C\u673A\u5DF2\u5B89\u88C5 dsh-hooks \u63D2\u4EF6\uFF08DeepSeek Harness \u914D\u7F6E\u9A71\u52A8\u751F\u547D\u5468\u671F hooks\uFF09\uFF1A\u53EF\u5728 profile \u7684 cordis.patch.yml \u58F0\u660E\u300C\u4E8B\u4EF6 \u2192 \u547D\u4EE4/\u901A\u77E5\u300D\u7684 hook\uFF08turn/start\u3001turn/end\u3001tree/settled\u3001step/end\u3001tool/call\u3001tool/result\u3001user/message\u3001approval/asked\u3001approval/decided\u3001session/title\u3001session/created\u3001session/disposed\u3001agent/created\u3001agent/disposed\u3001agent/error\u3001agent/status\u3001hook/failed\u3001usage/daily \u5171 18 \u7C7B\u4E8B\u4EF6\uFF09\uFF0C\u652F\u6301 when \u539F\u56E0\u8FC7\u6EE4\u3001match \u5B57\u6BB5\u6B63\u5219/\u6570\u503C\u6BD4\u8F83\u8FC7\u6EE4\uFF08\u5982 '>10000'\uFF09\u3001stdin JSON \u8F93\u5165\u3001opt-in \u91CD\u8BD5\u3001\u6267\u884C\u9009\u9879\uFF08enabled \u505C\u7528 / cwd \u5DE5\u4F5C\u76EE\u5F55 / maxConcurrent + debounceMs \u9632\u9AD8\u9891\u98CE\u66B4\uFF09\u3001\u5185\u7F6E webhook/desktop \u901A\u77E5\u6E20\u9053\uFF1B\u6267\u884C\u5386\u53F2\u8BB0\u5F55\u4E8E ~/.dsh/dsh-hooks/history.jsonl\uFF0C`dsh-hooks tail` \u53EF\u5B9E\u65F6\u8DDF\u8E2A\u3001`dsh-hooks dry-run <event>` \u53EF\u6A21\u62DF\u4E8B\u4EF6\uFF08\u542B runningSubagents/usage \u7B49\u6570\u503C\u5B57\u6BB5\uFF09\u9A8C\u8BC1\u914D\u7F6E\u3002\u7528\u6237\u63D0\u5230\u300Chooks / \u94A9\u5B50 / \u751F\u547D\u5468\u671F / \u901A\u77E5\u914D\u7F6E\u300D\u65F6\u5373\u6307\u672C\u63D2\u4EF6\uFF0C\u8BF7\u636E\u6B64\u534F\u4F5C\u3002";
 export declare function apply(ctx: Context, config?: Config): void;
 export declare const _internals: {
     clearTurnTracking: typeof clearTurnTracking;

package/lib/index.js

@@ -1,7 +1,8 @@
 import './types.js';
 import { Config } from './config.js';
-import { agentCreatedContext, agentDisposedContext, agentErrorContext, agentStatusContext, classifySessionEvent, clearTurnTracking, hookFailedContext, hookMatches, matchFilters, sessionCreatedContext, sessionDisposedContext, treeSettledContext, } from './events.js';
+import { agentCreatedContext, agentDisposedContext, agentErrorContext, agentStatusContext, classifySessionEvent, clearTurnTracking, hookFailedContext, hookMatches, matchFilters, sessionCreatedContext, sessionDisposedContext, treeSettledContext, usageDailyContext, } from './events.js';
 import { eventLabel } from './context.js';
+import { DailyUsageAccumulator, usageTotalsFromContext } from './usage.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify } from './notify.js';
 import { createHistorySink } from './history.js';
@@ -73,7 +74,7 @@ export { createHistorySink } from './history.js';
  * Model-facing announcement, installed only when the system-prompt service
  * exists (web profile). Tells agents the plugin exists and how to cooperate.
  */
-export const DSH_HOOKS_GUIDANCE = '本机已安装 dsh-hooks 插件（DeepSeek Harness 配置驱动生命周期 hooks）：可在 profile 的 cordis.patch.yml 声明「事件 → 命令/通知」的 hook（turn/start、turn/end、tree/settled、step/end、tool/call、tool/result、user/message、approval/asked、approval/decided、session/title、session/created、session/disposed、agent/created、agent/disposed、agent/error、agent/status、hook/failed 共 17 类事件），支持 when 原因过滤、match 字段正则/数值比较过滤（如 \'>10000\'）、stdin JSON 输入、opt-in 重试、执行选项（enabled 停用 / cwd 工作目录 / maxConcurrent + debounceMs 防高频风暴）、内置 webhook/desktop 通知渠道；执行历史记录于 ~/.dsh/dsh-hooks/history.jsonl；`dsh-hooks dry-run <event>` 可模拟事件验证配置。用户提到「hooks / 钩子 / 生命周期 / 通知配置」时即指本插件，请据此协作。';
+export const DSH_HOOKS_GUIDANCE = '本机已安装 dsh-hooks 插件（DeepSeek Harness 配置驱动生命周期 hooks）：可在 profile 的 cordis.patch.yml 声明「事件 → 命令/通知」的 hook（turn/start、turn/end、tree/settled、step/end、tool/call、tool/result、user/message、approval/asked、approval/decided、session/title、session/created、session/disposed、agent/created、agent/disposed、agent/error、agent/status、hook/failed、usage/daily 共 18 类事件），支持 when 原因过滤、match 字段正则/数值比较过滤（如 \'>10000\'）、stdin JSON 输入、opt-in 重试、执行选项（enabled 停用 / cwd 工作目录 / maxConcurrent + debounceMs 防高频风暴）、内置 webhook/desktop 通知渠道；执行历史记录于 ~/.dsh/dsh-hooks/history.jsonl，`dsh-hooks tail` 可实时跟踪、`dsh-hooks dry-run <event>` 可模拟事件（含 runningSubagents/usage 等数值字段）验证配置。用户提到「hooks / 钩子 / 生命周期 / 通知配置」时即指本插件，请据此协作。';
 export function apply(ctx, config = {}) {
     const hooks = config.hooks ?? [];
     const history = createHistorySink(config.history ?? undefined);
@@ -170,7 +171,12 @@ export function apply(ctx, config = {}) {
             }
         };
         if (hook.notify) {
-            void fireNotify(hook.notify, ctxValue, track);
+            // Retries ride the same per-hook options as `run` (webhook channel only;
+            // the desktop channel is a local spawn and never retries).
+            void fireNotify(hook.notify, ctxValue, track, {
+                retries: hook.retries,
+                retryDelayMs: hook.retryDelayMs,
+            });
             return;
         }
         if (hook.run) {
@@ -184,6 +190,25 @@ export function apply(ctx, config = {}) {
     };
     // Per-hook debounce state (trailing timers); cleared on dispose.
     const debounceTimers = new Map();
+    // Synthetic usage/daily: an in-memory per-day token bucket. Bookkeeping is
+    // wired only when a usage/daily hook exists — with none declared, no
+    // accumulation and no day check happen at all. The day rollover is detected
+    // from ordinary event traffic (no timers): the first classified event of a
+    // new day reports the day that just ended. Token totals include every
+    // session, subagent turns included — they are billed to the same account.
+    const hasUsageDailyHooks = hooks.some((hook) => hook.on === 'usage/daily' && hook.enabled !== false);
+    const usageDays = new DailyUsageAccumulator();
+    /**
+     * Feed one classified event to the daily bucket and dispatch the finished
+     * day's report when the calendar day rolled over. `origin` supplies the
+     * session identity of the triggering event.
+     */
+    const trackUsageDay = (origin, sessionId) => {
+        const totals = origin.event === 'turn/end' ? usageTotalsFromContext(origin) : undefined;
+        const finished = usageDays.observe(totals === undefined ? undefined : { totals, sessionId });
+        if (finished !== undefined)
+            runMatching(usageDailyContext(origin, finished.totals));
+    };
     // turn/start content: the session log records `turn/start` BEFORE the
     // turn's `user/message`, so the initiating prompt text cannot be read at
     // turn-start time. When turn/start hooks exist, dispatch is deferred until
@@ -281,6 +306,11 @@ export function apply(ctx, config = {}) {
             return;
         const reasonKind = extractReasonKind(event);
         const sessionId = String(session.id);
+        // Day-rollover check runs before any dispatch, so a turn ending just after
+        // midnight is reported against the previous day and then bucketed into the
+        // new one.
+        if (hasUsageDailyHooks)
+            trackUsageDay(classified, sessionId);
         if (classified.event === 'turn/start') {
             if (!hasTurnStartHooks) {
                 runMatching(classified, reasonKind);
@@ -362,6 +392,7 @@ export function apply(ctx, config = {}) {
         debounceTimers.clear();
         pendingTurnStarts.clear();
         watchedTrees.clear();
+        usageDays.reset();
     });
 }
 /** Extract the `turn/end` reason kind from a session event, when present. */

package/lib/notify.d.ts

@@ -6,23 +6,49 @@ export interface NotifyResult {
     error?: string;
 }
 export type NotifyRecord = (record: Omit<HookRunRecord, 'ts'>) => void;
+/**
+ * Retry policy for the built-in notify channels — the same two knobs the
+ * `run` channel takes, resolved from the hook declaration by the caller.
+ */
+export interface NotifyRetryOptions {
+    /** Retries after the first attempt. Defaults to 0 (one attempt, never retried). */
+    retries?: number;
+    /** Base delay between retries in milliseconds; doubles per attempt. Defaults to 500. */
+    retryDelayMs?: number;
+    /** Retry progress lines (defaults to `console.warn`). */
+    log?: (line: string) => void;
+}
 /** Fetch timeout for webhook sends (ms). */
 export declare const NOTIFY_TIMEOUT_MS = 10000;
+/**
+ * HTTP statuses worth retrying: rate limiting, request timeout, and
+ * server-side failures (a cold endpoint answering 502/503 is the classic
+ * case). Any other 4xx means the request itself is wrong — retrying it can
+ * only waste time.
+ */
+export declare function isRetryableStatus(status: number): boolean;
 /** One-line summary for Slack-style and desktop notifications. */
 export declare function summarizeContext(ctx: HookContext): string;
 /** Structured JSON document for the webhook channel (present fields only). */
 export declare function webhookPayload(ctx: HookContext): Record<string, unknown>;
 /**
- * POST the context to a webhook endpoint. One retry on transport failure
- * (webhook endpoints often drop the first request when cold). The URL comes
- * from `spec.url` or the `DSH_HOOKS_WEBHOOK_URL` environment variable.
+ * POST the context to a webhook endpoint, honouring the hook's
+ * `retries` / `retryDelayMs` exactly like the `run` channel: up to
+ * `retries` extra attempts after the first one, with the delay doubling per
+ * attempt. Retryable failures are transport errors (connection reset,
+ * timeout) and HTTP 408/429/5xx. The URL comes from `spec.url` or the
+ * `DSH_HOOKS_WEBHOOK_URL` environment variable.
  */
-export declare function sendWebhook(spec: NotifySpec, ctx: HookContext, env?: NodeJS.ProcessEnv): Promise<NotifyResult>;
+export declare function sendWebhook(spec: NotifySpec, ctx: HookContext, env?: NodeJS.ProcessEnv, retry?: NotifyRetryOptions): Promise<NotifyResult>;
 /**
  * Desktop balloon/toast notification. The summary travels through an
  * environment variable (Windows PowerShell) or argv (macOS/Linux), never
  * through shell-string interpolation.
  */
 export declare function sendDesktop(spec: NotifySpec, ctx: HookContext): Promise<NotifyResult>;
-/** Fire a built-in notification; failures only warn and surface in the result. */
-export declare function fireNotify(spec: NotifySpec, ctx: HookContext, record?: NotifyRecord): Promise<NotifyResult>;
+/**
+ * Fire a built-in notification; failures only warn and surface in the result.
+ * `retry` carries the hook's `retries` / `retryDelayMs` — honoured by the
+ * webhook channel; the desktop channel is a local spawn and never retries.
+ */
+export declare function fireNotify(spec: NotifySpec, ctx: HookContext, record?: NotifyRecord, retry?: NotifyRetryOptions): Promise<NotifyResult>;

package/lib/notify.js

@@ -6,8 +6,25 @@
  */
 import { spawn } from 'node:child_process';
 import { eventLabel } from './context.js';
+import { DEFAULT_RETRY_DELAY_MS } from './runner.js';
 /** Fetch timeout for webhook sends (ms). */
 export const NOTIFY_TIMEOUT_MS = 10000;
+/**
+ * HTTP statuses worth retrying: rate limiting, request timeout, and
+ * server-side failures (a cold endpoint answering 502/503 is the classic
+ * case). Any other 4xx means the request itself is wrong — retrying it can
+ * only waste time.
+ */
+export function isRetryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+/** Sleep without holding the event loop open (retries never outlive the plugin). */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
 /** One-line summary for Slack-style and desktop notifications. */
 export function summarizeContext(ctx) {
     const label = ctx.sessionName || ctx.sessionId || '';
@@ -93,15 +110,21 @@ export function webhookPayload(ctx) {
     return payload;
 }
 /**
- * POST the context to a webhook endpoint. One retry on transport failure
- * (webhook endpoints often drop the first request when cold). The URL comes
- * from `spec.url` or the `DSH_HOOKS_WEBHOOK_URL` environment variable.
+ * POST the context to a webhook endpoint, honouring the hook's
+ * `retries` / `retryDelayMs` exactly like the `run` channel: up to
+ * `retries` extra attempts after the first one, with the delay doubling per
+ * attempt. Retryable failures are transport errors (connection reset,
+ * timeout) and HTTP 408/429/5xx. The URL comes from `spec.url` or the
+ * `DSH_HOOKS_WEBHOOK_URL` environment variable.
  */
-export async function sendWebhook(spec, ctx, env = process.env) {
+export async function sendWebhook(spec, ctx, env = process.env, retry = {}) {
     const url = spec.url || env.DSH_HOOKS_WEBHOOK_URL;
     if (!url)
         return { ok: false, error: '缺少 webhook URL（notify.url 或 DSH_HOOKS_WEBHOOK_URL）' };
     const body = spec.slack ? { text: summarizeContext(ctx) } : webhookPayload(ctx);
+    const retries = Math.max(0, retry.retries ?? 0);
+    const baseDelay = Math.max(0, retry.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS);
+    const log = retry.log ?? ((line) => console.warn(line));
     const attempt = async () => {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), NOTIFY_TIMEOUT_MS);
@@ -117,22 +140,31 @@ export async function sendWebhook(spec, ctx, env = process.env) {
             clearTimeout(timer);
         }
     };
-    let response;
-    try {
-        response = await attempt();
-    }
-    catch (error) {
+    // Attempt loop: `retries` counts the attempts AFTER the first one, so the
+    // total is `1 + retries` — identical to the run channel's semantics.
+    for (let attemptNumber = 0;; attemptNumber++) {
+        let failure;
+        let retryable;
         try {
-            response = await attempt();
+            const response = await attempt();
+            if (response.ok)
+                return { ok: true };
+            failure = `webhook 响应 HTTP ${response.status}`;
+            retryable = isRetryableStatus(response.status);
+        }
+        catch (error) {
+            failure = `webhook 请求失败: ${error instanceof Error ? error.message : String(error)}`;
+            // Transport failures are always worth another attempt.
+            retryable = true;
         }
-        catch (retryError) {
-            const cause = retryError instanceof Error ? retryError.message : String(retryError);
-            return { ok: false, error: `webhook 请求失败（重试后仍失败）: ${cause}` };
+        const attempts = attemptNumber + 1;
+        if (!retryable || attempts > retries) {
+            return { ok: false, error: attempts > 1 ? `${failure}（${attempts} 次尝试后仍失败）` : failure };
         }
+        const delay = baseDelay * 2 ** attemptNumber;
+        log(`[dsh-hooks] 通知发送失败（${failure}），${delay}ms 后重试（${attempts}/${retries}）：${eventLabel(ctx)}`);
+        await sleep(delay);
     }
-    if (!response.ok)
-        return { ok: false, error: `webhook 响应 HTTP ${response.status}` };
-    return { ok: true };
 }
 /**
  * Desktop balloon/toast notification. The summary travels through an
@@ -196,10 +228,14 @@ function runAndWait(argv, env, timeoutMs) {
         });
     });
 }
-/** Fire a built-in notification; failures only warn and surface in the result. */
-export async function fireNotify(spec, ctx, record) {
+/**
+ * Fire a built-in notification; failures only warn and surface in the result.
+ * `retry` carries the hook's `retries` / `retryDelayMs` — honoured by the
+ * webhook channel; the desktop channel is a local spawn and never retries.
+ */
+export async function fireNotify(spec, ctx, record, retry = {}) {
     const startedAt = Date.now();
-    const result = spec.channel === 'webhook' ? await sendWebhook(spec, ctx) : await sendDesktop(spec, ctx);
+    const result = spec.channel === 'webhook' ? await sendWebhook(spec, ctx, process.env, retry) : await sendDesktop(spec, ctx);
     if (!result.ok) {
         console.warn(`[dsh-hooks] 通知发送失败 (${eventLabel(ctx)}): ${result.error}`);
         record?.({

package/lib/server.d.ts

@@ -48,7 +48,7 @@ export interface HookRoutesOptions {
 /** Sanitized per-hook description for the settings panel (regex sources, no RegExp objects). */
 export declare function describeHooks(hooks: readonly HookSpec[]): {
     index: number;
-    on: "agent/created" | "agent/disposed" | "agent/error" | "agent/status" | "approval/asked" | "approval/decided" | "hook/failed" | "session/created" | "session/disposed" | "session/title" | "step/end" | "tool/call" | "tool/result" | "tree/settled" | "turn/end" | "turn/start" | "user/message";
+    on: "agent/created" | "agent/disposed" | "agent/error" | "agent/status" | "approval/asked" | "approval/decided" | "hook/failed" | "session/created" | "session/disposed" | "session/title" | "step/end" | "tool/call" | "tool/result" | "tree/settled" | "turn/end" | "turn/start" | "usage/daily" | "user/message";
     when: "aborted" | "blocked" | "completed" | "error" | "interrupted" | "max-tokens" | undefined;
     match: {
         [k: string]: string;

package/lib/server.js

@@ -1,5 +1,5 @@
 import { createRequire } from 'node:module';
-import { describeHook, evaluateHooks, mockContext, patchFilePath } from './dry-run.js';
+import { applyMockFields, describeHook, evaluateHooks, MOCK_NUMERIC_FIELDS, mockContext, patchFilePath } from './dry-run.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify, summarizeContext } from './notify.js';
 import { FEISHU_SETUP_BUSY } from './feishu-session.js';
@@ -153,11 +153,27 @@ export function createHookHandler(options) {
                 return;
             }
             const reason = typeof body.reason === 'string' && body.reason !== '' ? body.reason : undefined;
-            const ctx = mockContext(event, {
+            const rawFields = body.fields;
+            if (rawFields !== undefined && (typeof rawFields !== 'object' || rawFields === null || Array.isArray(rawFields))) {
+                json(res, FAIL('bad-request', 'fields 必须是对象（模拟字段 → 数字）'), 400);
+                return;
+            }
+            const simulated = applyMockFields(mockContext(event, {
                 reason,
                 tool: typeof body.tool === 'string' ? body.tool : undefined,
                 sessionName: typeof body.sessionName === 'string' ? body.sessionName : undefined,
-            });
+            }), rawFields);
+            if (simulated.ignored.length > 0) {
+                json(res, FAIL('bad-request', `无法模拟的字段：${simulated.ignored.join(', ')}（可用：${MOCK_NUMERIC_FIELDS.join(' / ')}）`), 400);
+                return;
+            }
+            const ctx = simulated.ctx;
+            // Echo every numeric field the simulated context actually carries (mock
+            // defaults + explicit overrides) so the panel can show what was matched.
+            const fields = Object.fromEntries(MOCK_NUMERIC_FIELDS.filter((key) => ctx[key] !== undefined).map((key) => [
+                key,
+                ctx[key],
+            ]));
             const lines = evaluateHooks(hooks, event, ctx, reason);
             const matchedHooks = lines.filter((line) => line.matched);
             const execute = body.execute === true;
@@ -168,12 +184,13 @@ export function createHookHandler(options) {
                     if (hook.run)
                         runner.run(hook, ctx);
                     else if (hook.notify)
-                        void fireNotify(hook.notify, ctx);
+                        void fireNotify(hook.notify, ctx, undefined, { retries: hook.retries, retryDelayMs: hook.retryDelayMs });
                 }
             }
             json(res, OK({
                 event,
                 reason,
+                fields,
                 executed: execute,
                 total: hooks.length,
                 matched: matchedHooks.length,

package/lib/tail.d.ts

@@ -0,0 +1,44 @@
+import type { HookRunRecord } from './history.js';
+/** Bytes of the file tail read for the initial backfill. */
+export declare const TAIL_BACKFILL_BYTES: number;
+export interface TailBatch {
+    /** Parsed records of the complete lines in this batch, in file order. */
+    records: HookRunRecord[];
+    /** The same lines verbatim, for `--json` passthrough. */
+    lines: string[];
+    /** The file shrank (rotation/truncation) and reading restarted from 0. */
+    reset: boolean;
+}
+/** Optional filters for `tail` (all are AND-ed; unset means "no filter"). */
+export interface TailFilter {
+    /** Exact event name (`turn/end`, …). */
+    event?: string;
+    /** Exact outcome (`exit-nonzero`, `send-failed`, …). */
+    outcome?: string;
+    /** Substring of the hook identity (the rendered command / `notify:<channel>`). */
+    hook?: string;
+}
+/** Does a record pass every configured filter? */
+export declare function matchesTailFilter(record: HookRunRecord, filter: TailFilter): boolean;
+/** One human-readable line, aligned with the Web GUI's history timeline. */
+export declare function formatTailRecord(record: HookRunRecord): string;
+export declare class HistoryTailer {
+    #private;
+    readonly file: string;
+    constructor(file: string);
+    /** Bytes already consumed (the next read starts here). */
+    get offset(): number;
+    /**
+     * The last `limit` records (`limit <= 0` = all of them), read from at most
+     * `maxBytes` of the file tail so a large log is never slurped just to print
+     * a few lines. Leaves the reader positioned at EOF, so the following
+     * {@link readNew} only reports what is appended afterwards.
+     */
+    backfill(limit?: number, maxBytes?: number): HookRunRecord[];
+    /**
+     * Complete lines appended since the previous call. A file that shrank since
+     * then was rotated/truncated: reading restarts from 0 and `reset` is set so
+     * the caller can say so out loud.
+     */
+    readNew(): TailBatch;
+}