dsh-hooks 0.11.0 → 0.12.0

package/README.md

@@ -107,6 +107,7 @@ Every hook field:
 | `agent/error` | The agent loop reports an error | error text |
 | `agent/status` | Agent status transition | status |
 | `hook/failed` | A hook fails consecutively past `failedAlertThreshold` (default 3; synthetic, emitted from the outcome stream) | failing hook summary, consecutive failure count |
+| `usage/daily` | The first event after the local calendar day rolls over (synthetic, no timers): reports the token usage of the day that just ended | covered day, turns that day, contributing sessions, day's token totals |
 
 The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `error`, …). Hooks for other events run unconditionally.
 
@@ -134,11 +135,11 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `DSH_HOOK_STATUS` | agent status (`agent/status`) |
 | `DSH_HOOK_ERROR` | error text (`agent/error`, and the failure message on `turn/end` error) |
 | `DSH_HOOK_CONTENT` | event content snapshot: turn assistant text, tool result text, user message text, turn-initiating message text (turn/start) |
-| `DSH_HOOK_USAGE_INPUT_TOKENS` | aggregated input tokens of the turn (turn/end, summed across steps) |
-| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | aggregated output tokens of the turn |
-| `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_USAGE_INPUT_TOKENS` | input token total (turn/end: this turn, summed across steps; usage/daily: the whole day) |
+| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | output token total (same scoping) |
+| `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | cache-read tokens when reported (same scoping) |
+| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | cache-write tokens when reported (same scoping) |
+| `DSH_HOOK_USAGE_REASONING_TOKENS` | reasoning tokens when reported (same scoping) |
 | `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_PARENT_SESSION_ID` | parent session id (subagent lineage; absent for top-level sessions) |
 | `DSH_HOOK_SUBAGENT` | `1` when the session is a subagent child, `0` otherwise |
@@ -151,6 +152,9 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `DSH_HOOK_TREE_DURATION_MS` | parent turn/end → tree settle duration, ms (`tree/settled`) |
 | `DSH_HOOK_FAILED_HOOK` | identity summary of the hook that failed consecutively (`hook/failed`) |
 | `DSH_HOOK_FAILURES` | consecutive failure count when the alert fired (`hook/failed`) |
+| `DSH_HOOK_USAGE_DAY` | local calendar day the token totals cover, `YYYY-MM-DD` (`usage/daily`) |
+| `DSH_HOOK_USAGE_TURNS` | turns with reported accounting that day (`usage/daily`) |
+| `DSH_HOOK_USAGE_SESSIONS` | distinct sessions that contributed usage that day (`usage/daily`) |
 | `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'`.
@@ -184,6 +188,26 @@ For the simpler "notify only once the whole tree settles" pattern, the synthetic
 
 Settled-but-idle continuable children do not count as running, so they don't keep suppressing the notification. The settle watch is event-driven and best-effort: it survives until the plugin restarts, and a failed re-check drops the watch silently (no late notification).
 
+### usage/daily: the cross-day token report
+
+`turn/end` answers "what did this turn cost". For a per-day view, use the synthetic `usage/daily` event: the plugin accumulates every reported `turn/end` usage in memory per **local calendar day** (subagent sessions included — same account), and when the day rolls over it emits one report for the day that just ended, on the next event that arrives. Detection is purely event-driven: no timers, no scheduled tasks.
+
+```yaml
+- on: 'usage/daily'
+  match: { usageInputTokens: '>0' }     # optional: skip days without usage
+  run: 'node examples/log-usage.mjs'    # or notify: { channel: 'webhook', url: '…' }
+```
+
+`DSH_HOOK_USAGE_DAY` is the day the report covers (`YYYY-MM-DD`); `DSH_HOOK_USAGE_TURNS` / `DSH_HOOK_USAGE_SESSIONS` are that day's counted turns and contributing sessions; the token details reuse the `turn/end` variable names (`usageInputTokens` / `usageOutputTokens` / `usageCacheReadTokens` / `usageCacheWriteTokens` / `usageReasoningTokens`) with day scope instead of turn scope.
+
+Three boundaries by design, not bugs:
+
+- **In-memory**: a plugin-process restart drops the day in progress (the new process starts a fresh day at zero); reports already emitted are unaffected.
+- **Event-driven, not timed**: a day is reported when the next event arrives, so after a quiet midnight the report waits for the next event; a day with no reported turn usage is never reported (an empty report is noise).
+- **Zero cost when unused**: with no `usage/daily` hook declared, no accumulation and no day check happen at all.
+
+`dsh-hooks dry-run usage/daily` simulates a report for "yesterday" with non-zero tokens, so match filters and the command can be verified first.
+
 ### Numeric match comparisons
 
 Numeric context fields (`turn`, `step`, `durationMs`, `toolDurationMs`, `usage*`, `runningSubagents`, …) support real comparisons instead of regex hacks:

package/README.zh.md

@@ -107,6 +107,7 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `agent/error` | Agent 循环报错 | 错误文本 |
 | `agent/status` | Agent 状态切换 | 状态 |
 | `hook/failed` | 同一 hook 连续失败达到 `failedAlertThreshold`（默认 3；合成事件，从结果流发射） | 失败 hook 摘要、连续失败次数 |
+| `usage/daily` | 本地日历日翻篇后的下一个事件（合成事件，无定时器）：报告刚结束那一天的 token 用量 | 覆盖日期、当日回合数、贡献会话数、当日 token 明细 |
 
 `turn/end` 的 `when` 匹配结束原因（`completed`、`error`…）；其他事件的 hook 无条件执行。
 
@@ -134,11 +135,11 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_STATUS` | Agent 状态（agent/status） |
 | `DSH_HOOK_ERROR` | 错误文本（agent/error，以及 turn/end 出错时的失败详情） |
 | `DSH_HOOK_CONTENT` | 事件内容快照：回合最后助手文本、工具结果文本、用户消息文本、回合触发消息文本（turn/start） |
-| `DSH_HOOK_USAGE_INPUT_TOKENS` | 本回合输入 token 总量（turn/end，逐 step 聚合） |
-| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | 本回合输出 token 总量 |
-| `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | 本回合缓存读 token（有上报时） |
-| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | 本回合缓存写 token（有上报时） |
-| `DSH_HOOK_USAGE_REASONING_TOKENS` | 本回合思考 token（有上报时） |
+| `DSH_HOOK_USAGE_INPUT_TOKENS` | 输入 token 总量（turn/end 为本回合、逐 step 聚合；usage/daily 为当日聚合） |
+| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | 输出 token 总量（同上） |
+| `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_PARENT_SESSION_ID` | 父会话 id（子代理谱系；顶层会话无此变量） |
 | `DSH_HOOK_SUBAGENT` | 会话为子代理时为 `1`，否则 `0` |
@@ -151,6 +152,9 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_TREE_DURATION_MS` | 父回合结束 → 树落定的耗时（毫秒，`tree/settled`） |
 | `DSH_HOOK_FAILED_HOOK` | 连续失败的 hook 身份摘要（`hook/failed`） |
 | `DSH_HOOK_FAILURES` | 告警触发时的连续失败次数（`hook/failed`） |
+| `DSH_HOOK_USAGE_DAY` | 报告覆盖的本地日历日 `YYYY-MM-DD`（`usage/daily`） |
+| `DSH_HOOK_USAGE_TURNS` | 当日计入的回合数（`usage/daily`） |
+| `DSH_HOOK_USAGE_SESSIONS` | 当日贡献用量的会话数（`usage/daily`） |
 | `DSH_HOOK_TIMESTAMP` | ISO 时间戳 |
 
 - `run` 里的 `{{变量}}` 占位符会从同一上下文替换，例如 `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`。
@@ -185,6 +189,26 @@ config:
 
 已落定但闲置（idle）的 continuable 子代理不计入运行中，不会一直压住通知。落定监视是事件驱动且 best-effort 的：插件重启后监视集合丢失；重查失败会静默放弃该监视（不会补发迟到的通知）。
 
+### usage/daily：跨日 token 日报
+
+`turn/end` 只回答「这个回合花了多少」。要按天看成本，用合成事件 `usage/daily`：插件在内存里按**本地日历日**累计每个 `turn/end` 上报的 token（子代理会话的回合一并计入——同一个账号），日期翻篇后对下一个到达的事件发射一次日报，报告刚结束的那一天。检测纯事件驱动、无定时器、无定时任务。
+
+```yaml
+- on: 'usage/daily'
+  match: { usageInputTokens: '>0' }     # 可选：跳过没有用量的日子
+  run: 'node examples/log-usage.mjs'    # 或 notify: { channel: 'webhook', url: '…' }
+```
+
+`DSH_HOOK_USAGE_DAY` 是报告覆盖的日期（`YYYY-MM-DD`）；`DSH_HOOK_USAGE_TURNS` / `DSH_HOOK_USAGE_SESSIONS` 是当日计入的回合数与贡献会话数；token 明细沿用 `turn/end` 的 `DSH_HOOK_USAGE_*` 变量名（`usageInputTokens` / `usageOutputTokens` / `usageCacheReadTokens` / `usageCacheWriteTokens` / `usageReasoningTokens`），语义变为「该日聚合」。
+
+三条边界（按设计，不是 bug）：
+
+- **内存累计**：插件进程重启会丢掉进行中那一天的累计（重启后从新的一天、从零开始）；已发出的日报不受影响。
+- **事件驱动而非定时**：一天的用量要等下一个事件到达才报告，所以跨夜后若一直没动静，日报会推迟到下一次有事件时补发；那一天从未有回合上报用量则不发射（空日报是噪声）。
+- **零开销**：没有声明任何 `usage/daily` hook 时，插件完全不做累计与跨日检测。
+
+`dsh-hooks dry-run usage/daily` 用「昨天」和非零 token 模拟一次日报，可先验证 match 与命令。
+
 ### match 数值比较
 
 对数字字段（`turn`、`step`、`durationMs`、`toolDurationMs`、`usage*`、`runningSubagents`…）可以直接写数值比较，不用绕正则：

package/lib/client.js

@@ -200,18 +200,22 @@ window.__ModuleLoader__.load({
 		const EVENTS = [
 			"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"
+			"agent/status",
+			"hook/failed",
+			"usage/daily"
 		];
 		const TURN_END_REASONS = [
 			"completed",

package/lib/config.d.ts

@@ -1,5 +1,5 @@
 /** Hookable event kinds. v1 is emit-only: no waterfall/interception events. */
-export declare const HOOK_EVENTS: readonly ['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'];
+export declare const HOOK_EVENTS: readonly ['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'];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** `turn/end` reason kinds (from @deepseek-ai/dsh-session TurnEndReasonMap). */
 export declare const TURN_END_REASONS: readonly ['completed', 'error', 'aborted', 'blocked', 'max-tokens', 'interrupted'];

package/lib/config.js

@@ -18,6 +18,7 @@ export const HOOK_EVENTS = [
     'agent/error',
     'agent/status',
     'hook/failed',
+    'usage/daily',
 ];
 /** `turn/end` reason kinds (from @deepseek-ai/dsh-session TurnEndReasonMap). */
 export const TURN_END_REASONS = [
@@ -34,7 +35,7 @@ export const TURN_END_REASONS = [
 // declaration self-contained.
 export const Config = Schema.object({
     hooks: Schema.array(Schema.object({
-        on: Schema.union([...HOOK_EVENTS]).description('触发事件：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'),
+        on: Schema.union([...HOOK_EVENTS]).description('触发事件：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'),
         when: Schema.union([...TURN_END_REASONS]).description('可选过滤：对 turn/end 匹配结束原因（completed/error/aborted/blocked/max-tokens/interrupted）；其他事件忽略该字段'),
         match: Schema.dict(Schema.union([
             Schema.regExp(),

package/lib/context.d.ts

@@ -35,7 +35,7 @@ export interface HookContext {
      * pairing tool/call was never seen, e.g. after a plugin restart).
      */
     toolDurationMs?: number;
-    /** Aggregated token usage of the turn (turn/end), when reported. */
+    /** Aggregated token usage of the turn (turn/end), or of the day (usage/daily). */
     usageInputTokens?: number;
     usageOutputTokens?: number;
     usageCacheReadTokens?: number;
@@ -69,6 +69,15 @@ export interface HookContext {
     hookFailedHook?: string;
     /** Consecutive failure count when the alert fired (hook/failed). */
     hookFailures?: number;
+    /**
+     * Local calendar day (`YYYY-MM-DD`) the token totals below cover
+     * (usage/daily only; turn/end carries a single turn, not a day).
+     */
+    usageDay?: string;
+    /** Turns with reported accounting that day (usage/daily). */
+    usageTurns?: number;
+    /** Distinct sessions that contributed usage that day (usage/daily). */
+    usageSessions?: number;
     timestamp: string;
 }
 export declare function toEnv(ctx: HookContext): Record<string, string>;

package/lib/context.js

@@ -71,6 +71,12 @@ export function toEnv(ctx) {
         env.DSH_HOOK_FAILED_HOOK = ctx.hookFailedHook;
     if (ctx.hookFailures !== undefined)
         env.DSH_HOOK_FAILURES = String(ctx.hookFailures);
+    if (ctx.usageDay !== undefined)
+        env.DSH_HOOK_USAGE_DAY = ctx.usageDay;
+    if (ctx.usageTurns !== undefined)
+        env.DSH_HOOK_USAGE_TURNS = String(ctx.usageTurns);
+    if (ctx.usageSessions !== undefined)
+        env.DSH_HOOK_USAGE_SESSIONS = String(ctx.usageSessions);
     return env;
 }
 /** Render `{{DSH_HOOK_*}}` placeholders from the context map. */

package/lib/dry-run.js

@@ -9,6 +9,7 @@ import { join } from 'node:path';
 import YAML from 'yaml';
 import { Config } from './config.js';
 import { matchFilters } from './events.js';
+import { localDayKey } from './usage.js';
 import { createHookRunner } from './runner.js';
 import { fireNotify } from './notify.js';
 /** Profile patch file for a profile name. */
@@ -48,7 +49,7 @@ export function loadHooks(profile, paths = {}) {
 }
 /** 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 +60,21 @@ export function mockContext(event, overrides = {}) {
         callId: 'dry-run-call',
         content: 'dry-run 模拟内容',
         timestamp: new Date().toISOString(),
-        ...overrides,
     };
+    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) {

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\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 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 dry-run <event>` 可模拟事件验证配置。用户提到「hooks / 钩子 / 生命周期 / 通知配置」时即指本插件，请据此协作。';
 export function apply(ctx, config = {}) {
     const hooks = config.hooks ?? [];
     const history = createHistorySink(config.history ?? undefined);
@@ -184,6 +185,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 +301,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 +387,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/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/usage.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Daily token accounting behind the synthetic `usage/daily` event.
+ *
+ * The contract is deliberately modest: accumulate in memory, detect the local
+ * calendar-day rollover from ordinary event traffic (no timers, no scheduled
+ * tasks), and report the day that just ended. Two consequences are documented
+ * in the READMEs: a plugin-process restart drops the in-flight day, and a day
+ * followed by no further events is reported at the next event rather than at
+ * midnight.
+ */
+import type { HookContext } from './context.js';
+/** Structural token accounting (disjoint counts; cache fields optional). */
+export interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+}
+/** One finished day's aggregate, as carried by `usage/daily`. */
+export interface DailyUsageTotals extends UsageTotals {
+    /** Local calendar day the totals cover (`YYYY-MM-DD`). */
+    day: string;
+    /** Turns that reported accounting and contributed to the totals. */
+    turns: number;
+    /** Distinct sessions that contributed usage that day. */
+    sessions: number;
+}
+/** A finished day handed to the caller when the calendar day rolled over. */
+export interface DailyUsageRollover {
+    day: string;
+    totals: DailyUsageTotals;
+}
+/** One observation fed to the accumulator (a `turn/end` that reported usage). */
+export interface UsageObservation {
+    totals: UsageTotals;
+    sessionId?: string;
+}
+/**
+ * Local calendar day key (`YYYY-MM-DD`). Local — not UTC — because a daily
+ * report should follow the machine's day boundary the way the user reads
+ * costs; `toISOString` would put the boundary in the wrong place.
+ */
+export declare function localDayKey(date?: Date): string;
+/**
+ * Read the turn usage already flattened onto a hook context (the same numbers
+ * a `turn/end` hook sees, so a `usage/daily` report and the per-turn variables
+ * always agree). Returns undefined when the turn reported no accounting.
+ */
+export declare function usageTotalsFromContext(ctx: HookContext): UsageTotals | undefined;
+/**
+ * In-memory daily usage bucket behind the synthetic `usage/daily` event.
+ *
+ * `observe` is the single entry point: it rolls the calendar day over first
+ * (returning the finished day's report exactly once), then records the
+ * observation into the new day. Rolling over *before* recording is what keeps
+ * a turn ending just after midnight out of the previous day's totals.
+ */
+export declare class DailyUsageAccumulator {
+    #private;
+    /** The day currently accumulated; `undefined` before the first observation. */
+    get day(): string | undefined;
+    /**
+     * Roll the day over if needed, then record one observation.
+     *
+     * Returns the finished day's totals when this call crossed a day boundary
+     * and that day had reported usage — `undefined` on an ordinary call, on the
+     * first observation of a process (nothing accumulated yet), and for a day
+     * without usage (an empty report is noise, not a report).
+     */
+    observe(observation?: UsageObservation, now?: Date): DailyUsageRollover | undefined;
+    /**
+     * Detect a calendar-day rollover without recording anything, so the first
+     * event after midnight can report the day that just ended.
+     */
+    rollover(now?: Date): DailyUsageRollover | undefined;
+    /** Drop all state (plugin dispose). */
+    reset(): void;
+}

package/lib/usage.js

@@ -0,0 +1,110 @@
+/**
+ * Local calendar day key (`YYYY-MM-DD`). Local — not UTC — because a daily
+ * report should follow the machine's day boundary the way the user reads
+ * costs; `toISOString` would put the boundary in the wrong place.
+ */
+export function localDayKey(date = new Date()) {
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${date.getFullYear()}-${month}-${day}`;
+}
+/**
+ * Read the turn usage already flattened onto a hook context (the same numbers
+ * a `turn/end` hook sees, so a `usage/daily` report and the per-turn variables
+ * always agree). Returns undefined when the turn reported no accounting.
+ */
+export function usageTotalsFromContext(ctx) {
+    if (ctx.usageInputTokens === undefined && ctx.usageOutputTokens === undefined)
+        return undefined;
+    return {
+        inputTokens: ctx.usageInputTokens ?? 0,
+        outputTokens: ctx.usageOutputTokens ?? 0,
+        ...(ctx.usageCacheReadTokens !== undefined ? { cacheReadTokens: ctx.usageCacheReadTokens } : {}),
+        ...(ctx.usageCacheWriteTokens !== undefined ? { cacheWriteTokens: ctx.usageCacheWriteTokens } : {}),
+        ...(ctx.usageReasoningTokens !== undefined ? { reasoningTokens: ctx.usageReasoningTokens } : {}),
+    };
+}
+/**
+ * In-memory daily usage bucket behind the synthetic `usage/daily` event.
+ *
+ * `observe` is the single entry point: it rolls the calendar day over first
+ * (returning the finished day's report exactly once), then records the
+ * observation into the new day. Rolling over *before* recording is what keeps
+ * a turn ending just after midnight out of the previous day's totals.
+ */
+export class DailyUsageAccumulator {
+    #day;
+    #bucket;
+    /** The day currently accumulated; `undefined` before the first observation. */
+    get day() {
+        return this.#day;
+    }
+    /**
+     * Roll the day over if needed, then record one observation.
+     *
+     * Returns the finished day's totals when this call crossed a day boundary
+     * and that day had reported usage — `undefined` on an ordinary call, on the
+     * first observation of a process (nothing accumulated yet), and for a day
+     * without usage (an empty report is noise, not a report).
+     */
+    observe(observation, now = new Date()) {
+        const finished = this.rollover(now);
+        if (observation !== undefined)
+            this.#record(observation);
+        return finished;
+    }
+    /**
+     * Detect a calendar-day rollover without recording anything, so the first
+     * event after midnight can report the day that just ended.
+     */
+    rollover(now = new Date()) {
+        const today = localDayKey(now);
+        if (this.#day === undefined) {
+            this.#day = today;
+            return undefined;
+        }
+        if (this.#day === today)
+            return undefined;
+        const bucket = this.#bucket;
+        const day = this.#day;
+        this.#day = today;
+        this.#bucket = undefined;
+        if (bucket === undefined)
+            return undefined;
+        return {
+            day,
+            totals: {
+                day,
+                inputTokens: bucket.inputTokens,
+                outputTokens: bucket.outputTokens,
+                ...(bucket.cacheReadTokens !== undefined ? { cacheReadTokens: bucket.cacheReadTokens } : {}),
+                ...(bucket.cacheWriteTokens !== undefined ? { cacheWriteTokens: bucket.cacheWriteTokens } : {}),
+                ...(bucket.reasoningTokens !== undefined ? { reasoningTokens: bucket.reasoningTokens } : {}),
+                turns: bucket.turns,
+                sessions: bucket.sessions.size,
+            },
+        };
+    }
+    /** Drop all state (plugin dispose). */
+    reset() {
+        this.#day = undefined;
+        this.#bucket = undefined;
+    }
+    #record(observation) {
+        const bucket = (this.#bucket ??= { inputTokens: 0, outputTokens: 0, turns: 0, sessions: new Set() });
+        bucket.inputTokens += observation.totals.inputTokens;
+        bucket.outputTokens += observation.totals.outputTokens;
+        if (observation.totals.cacheReadTokens !== undefined) {
+            bucket.cacheReadTokens = (bucket.cacheReadTokens ?? 0) + observation.totals.cacheReadTokens;
+        }
+        if (observation.totals.cacheWriteTokens !== undefined) {
+            bucket.cacheWriteTokens = (bucket.cacheWriteTokens ?? 0) + observation.totals.cacheWriteTokens;
+        }
+        if (observation.totals.reasoningTokens !== undefined) {
+            bucket.reasoningTokens = (bucket.reasoningTokens ?? 0) + observation.totals.reasoningTokens;
+        }
+        bucket.turns += 1;
+        if (observation.sessionId !== undefined)
+            bucket.sessions.add(observation.sessionId);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hooks",
-  "version": "0.11.0",
+  "version": "0.12.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",
@@ -68,7 +68,7 @@
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "react": "^18.2.0"
   },
   "devDependencies": {
@@ -77,9 +77,9 @@
     "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.8",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.8",
-    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "@tsdown/css": "^0.22.14",
-    "@types/node": "^26.3.0",
+    "@types/node": "^26.4.1",
     "@types/react": "~18.3.1",
     "@types/react-dom": "^18.3.5",
     "react": "^18.3.1",
@@ -89,7 +89,7 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@larksuiteoapi/node-sdk": "^1.73.0",
+    "@larksuiteoapi/node-sdk": "^1.73.1",
     "qrcode": "^1.5.4",
     "yaml": "^2.9.0"
   }