dsh-hooks 0.10.0 → 0.12.0

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 字段正则过滤、stdin JSON 输入、opt-in 重试、内置 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);
@@ -112,42 +113,113 @@ export function apply(ctx, config = {}) {
     }
     const runMatching = (ctxValue, reasonKind) => {
         hooks.forEach((hook, index) => {
+            // enabled: false keeps the declaration but silences dispatch entirely —
+            // skipped hooks are never failure-streak candidates.
+            if (hook.enabled === false)
+                return;
             if (!hookMatches(hook, ctxValue.event, reasonKind))
                 return;
             if (!matchFilters(hook.match, ctxValue))
                 return;
-            // Attribute every outcome record to this hook identity so the failure
-            // streak below sees the full run/notify lifecycle (retries included).
-            const track = (record) => {
-                history.record(record);
-                const failed = record.outcome === 'spawn-failed' ||
-                    record.outcome === 'exit-nonzero' ||
-                    record.outcome === 'timeout' ||
-                    record.outcome === 'send-failed';
-                if (failed) {
-                    const count = (failures.get(index) ?? 0) + 1;
-                    failures.set(index, count);
-                    if (count >= failureThreshold && !alerted.has(index)) {
-                        alerted.add(index);
-                        runMatching(hookFailedContext(ctxValue, hookFailureSummary(hook), count));
-                    }
+            const debounceMs = hook.debounceMs ?? 0;
+            if (debounceMs > 0) {
+                // Trailing-edge merge: triggers inside the window collapse into one
+                // execution carrying the latest context. Dropped triggers stay silent
+                // so high-frequency events cannot flood the log/history.
+                const pending = debounceTimers.get(index);
+                if (pending !== undefined) {
+                    pending.ctx = ctxValue;
                     return;
                 }
-                if (record.outcome === 'exit-0' || record.outcome === 'sent') {
-                    failures.delete(index);
-                    alerted.delete(index);
-                }
-            };
-            if (hook.notify) {
-                void fireNotify(hook.notify, ctxValue, track);
+                const timer = setTimeout(() => {
+                    const armed = debounceTimers.get(index);
+                    debounceTimers.delete(index);
+                    if (armed !== undefined)
+                        dispatchHook(hook, index, armed.ctx);
+                }, debounceMs);
+                timer.unref?.();
+                debounceTimers.set(index, { timer, ctx: ctxValue });
                 return;
             }
-            if (hook.run) {
-                runner.run(hook, ctxValue, track);
+            dispatchHook(hook, index, ctxValue);
+        });
+    };
+    /**
+     * Dispatch one matched, enabled hook (run or notify). Outcome records are
+     * attributed to the hook index so the failure streak sees the full
+     * run/notify lifecycle (retries included).
+     */
+    const dispatchHook = (hook, index, ctxValue) => {
+        const track = (record) => {
+            history.record(record);
+            const failed = record.outcome === 'spawn-failed' ||
+                record.outcome === 'exit-nonzero' ||
+                record.outcome === 'timeout' ||
+                record.outcome === 'send-failed';
+            if (failed) {
+                const count = (failures.get(index) ?? 0) + 1;
+                failures.set(index, count);
+                if (count >= failureThreshold && !alerted.has(index)) {
+                    alerted.add(index);
+                    runMatching(hookFailedContext(ctxValue, hookFailureSummary(hook), count));
+                }
                 return;
             }
-            console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(ctxValue)}`);
-        });
+            if (record.outcome === 'exit-0' || record.outcome === 'sent') {
+                failures.delete(index);
+                alerted.delete(index);
+            }
+        };
+        if (hook.notify) {
+            void fireNotify(hook.notify, ctxValue, track);
+            return;
+        }
+        if (hook.run) {
+            const limiter = hook.maxConcurrent !== undefined && hook.maxConcurrent > 0
+                ? { id: `hook:${index}`, max: hook.maxConcurrent }
+                : undefined;
+            runner.run(hook, ctxValue, track, limiter);
+            return;
+        }
+        console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(ctxValue)}`);
+    };
+    // 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
+    // the turn's first direct user message is classified (its text attached as
+    // `content`), or the turn ends without one (continuation/goal rounds) —
+    // then it fires without content.
+    const hasTurnStartHooks = hooks.some((hook) => hook.on === 'turn/start' && hook.enabled !== false);
+    const pendingTurnStarts = new Map();
+    /** Dispatch a deferred turn/start, optionally attaching the initiating text. */
+    const flushTurnStart = (sessionId, content) => {
+        const pending = pendingTurnStarts.get(sessionId);
+        if (pending === undefined)
+            return;
+        pendingTurnStarts.delete(sessionId);
+        const ctxValue = content === undefined ? pending.ctx : { ...pending.ctx, content: content.slice(0, 2000) };
+        runMatching(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
@@ -228,10 +300,43 @@ export function apply(ctx, config = {}) {
         if (classified === undefined)
             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);
+                return;
+            }
+            // A new turn claims the session: flush a previous unclaimed turn/start
+            // (empty/rejected turn) without content, then arm the new one.
+            flushTurnStart(sessionId);
+            pendingTurnStarts.set(sessionId, { ctx: classified });
+            return;
+        }
+        if (classified.event === 'user/message') {
+            // The turn's first direct user message completes the deferred turn/start
+            // with the initiating text attached; synthetic messages (agent/plugin
+            // sources) do not complete it.
+            const pending = pendingTurnStarts.get(sessionId);
+            if (pending !== undefined && classified.source === 'user') {
+                pendingTurnStarts.delete(sessionId);
+                const text = classified.content;
+                runMatching(text === undefined ? pending.ctx : { ...pending.ctx, content: text.slice(0, 2000) });
+            }
+            runMatching(classified, reasonKind);
+            return;
+        }
         if (classified.event !== 'turn/end') {
             runMatching(classified, reasonKind);
             return;
         }
+        // The turn produced no direct user message (continuation round): dispatch
+        // the deferred turn/start without content, then the turn/end flow.
+        flushTurnStart(sessionId);
         // 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.
@@ -245,6 +350,8 @@ export function apply(ctx, config = {}) {
     });
     ctx.on('session/disposed', (session) => {
         watchedTrees.delete(String(session.id));
+        // A disposed session never completes its deferred turn/start — drop it.
+        pendingTurnStarts.delete(String(session.id));
         runMatching(sessionDisposedContext(session));
         // A child session leaving the store is also settle-relevant activity.
         void refreshWatchedTrees().catch((error) => {
@@ -275,7 +382,12 @@ export function apply(ctx, config = {}) {
     });
     ctx.effect(() => () => {
         runner.dispose();
+        for (const entry of debounceTimers.values())
+            clearTimeout(entry.timer);
+        debounceTimers.clear();
+        pendingTurnStarts.clear();
         watchedTrees.clear();
+        usageDays.reset();
     });
 }
 /** Extract the `turn/end` reason kind from a session event, when present. */

package/lib/patch-config.d.ts

@@ -13,6 +13,10 @@ export interface HookWireSpec {
     timeoutMs?: number;
     retries?: number;
     retryDelayMs?: number;
+    enabled?: boolean;
+    cwd?: 'session' | string;
+    maxConcurrent?: number;
+    debounceMs?: number;
 }
 /** Parse a patch list; throws a user-facing error on malformed YAML. */
 export declare function parsePatchText(text: string): unknown[];

package/lib/patch-config.js

@@ -7,6 +7,7 @@
  * so a save applies without a restart.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
 import YAML from 'yaml';
 import { HOOK_EVENTS, TURN_END_REASONS } from './config.js';
 /** Parse a patch list; throws a user-facing error on malformed YAML. */
@@ -55,12 +56,15 @@ export function validateHookWire(hooks) {
         if (hasNotify && hook.notify.channel !== 'webhook' && hook.notify.channel !== 'desktop') {
             return `${label}：无效通知渠道 ${hook.notify.channel}`;
         }
-        for (const key of ['timeoutMs', 'retries', 'retryDelayMs']) {
+        for (const key of ['timeoutMs', 'retries', 'retryDelayMs', 'maxConcurrent', 'debounceMs']) {
             const value = hook[key];
             if (value !== undefined && (!Number.isFinite(value) || value < 0)) {
                 return `${label}：${key} 必须是非负数字`;
             }
         }
+        if (hook.cwd !== undefined && hook.cwd !== '' && hook.cwd !== 'session' && !isAbsolute(hook.cwd)) {
+            return `${label}：cwd 必须是 session 或绝对路径（收到 ${hook.cwd}）`;
+        }
     }
     return null;
 }

package/lib/runner.d.ts

@@ -9,7 +9,7 @@ export interface RunOutcome {
 }
 /** Track in-flight hook runs so a missing parent never outlives teardown. */
 export interface HookRunner {
-    run(spec: HookSpec, ctx: HookContext, recordOverride?: RunRecord): RunOutcome;
+    run(spec: HookSpec, ctx: HookContext, recordOverride?: RunRecord, limiter?: RunLimiter): RunOutcome;
     /** Live counters for the web-panel diagnostics. */
     stats(): HookRunnerStats;
     dispose(): void;
@@ -21,6 +21,15 @@ export interface HookRunnerStats {
     pendingRetries: number;
 }
 export type RunRecord = (record: Omit<HookRunRecord, 'ts'>) => void;
+/**
+ * Per-hook concurrency gate: runs carrying the same `id` share one cap.
+ * Accepted runs occupy a slot until the logical run reaches a terminal
+ * outcome (retries keep the slot), so a retrying hook still counts.
+ */
+export interface RunLimiter {
+    id: string;
+    max: number;
+}
 export declare const DEFAULT_TIMEOUT_MS = 10000;
 export declare const DEFAULT_RETRY_DELAY_MS = 500;
 /**
@@ -38,5 +47,7 @@ export declare function terminate(child: ChildProcess): void;
  * templating by the user. `input: 'stdin'` additionally writes the full
  * context as one JSON document to stdin, and `retries` re-spawns commands
  * whose exit code is non-zero (with exponential backoff, in the background).
+ * `cwd` moves the spawn into the session/project directory, and an optional
+ * `limiter` caps concurrent runs per identity.
  */
 export declare function createHookRunner(log?: (line: string) => void, record?: RunRecord): HookRunner;

package/lib/runner.js

@@ -26,6 +26,18 @@ export function terminate(child) {
     }
     child.kill();
 }
+/**
+ * Resolve the spawn working directory for a hook: `cwd: 'session'` runs in
+ * the session's cwd (falling back to the plugin process when unknown); any
+ * other configured value is used verbatim (documented as an absolute path).
+ */
+function resolveCwd(spec, ctx) {
+    if (spec.cwd === undefined)
+        return undefined;
+    if (spec.cwd === 'session')
+        return ctx.cwd ?? process.cwd();
+    return spec.cwd;
+}
 /**
  * Fire-and-forget command runner. Emissions are irreversible side effects:
  * failures only warn, never block the agent loop. Context travels through
@@ -34,11 +46,24 @@ export function terminate(child) {
  * templating by the user. `input: 'stdin'` additionally writes the full
  * context as one JSON document to stdin, and `retries` re-spawns commands
  * whose exit code is non-zero (with exponential backoff, in the background).
+ * `cwd` moves the spawn into the session/project directory, and an optional
+ * `limiter` caps concurrent runs per identity.
  */
 export function createHookRunner(log = console.log, record) {
     const children = new Set();
     const pendingRetries = new Set();
-    function spawnOnce(spec, ctx, attempt, recordOverride) {
+    /** Live logical-run counts per limiter id (retries keep their slot). */
+    const inFlightById = new Map();
+    function releaseSlot(limiter) {
+        if (limiter === undefined)
+            return;
+        const count = (inFlightById.get(limiter.id) ?? 0) - 1;
+        if (count <= 0)
+            inFlightById.delete(limiter.id);
+        else
+            inFlightById.set(limiter.id, count);
+    }
+    function spawnOnce(spec, ctx, attempt, recordOverride, done) {
         if (!spec.run)
             return { ok: false, reason: 'skipped', detail: 'no run command' };
         // Per-run override replaces the shared sink for this logical run so
@@ -62,6 +87,7 @@ export function createHookRunner(log = console.log, record) {
         try {
             child = spawn(command, {
                 shell: true,
+                cwd: resolveCwd(spec, ctx),
                 env: { ...process.env, ...env },
                 stdio: [useStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
             });
@@ -70,6 +96,7 @@ export function createHookRunner(log = console.log, record) {
             const detail = error instanceof Error ? error.message : String(error);
             console.warn(`[dsh-hooks] spawn 失败 (${eventLabel(ctx)}): ${detail}`);
             rec?.({ ...base, outcome: 'spawn-failed', error: detail });
+            done?.();
             return { ok: false, reason: 'spawn-failed', detail };
         }
         const startedAt = Date.now();
@@ -112,6 +139,7 @@ export function createHookRunner(log = console.log, record) {
                 if (!timedOut && code !== null) {
                     rec?.({ ...base, outcome: 'exit-0', exitCode: 0, durationMs: Date.now() - startedAt });
                 }
+                done?.();
                 return;
             }
             if (attempt < retries) {
@@ -119,7 +147,7 @@ export function createHookRunner(log = console.log, record) {
                 log(`[dsh-hooks] hook 退出码 ${code}，${delay}ms 后重试（${attempt + 1}/${retries}）：${eventLabel(ctx)}`);
                 const retryTimer = setTimeout(() => {
                     pendingRetries.delete(retryTimer);
-                    spawnOnce(spec, ctx, attempt + 1, recordOverride);
+                    spawnOnce(spec, ctx, attempt + 1, recordOverride, done);
                 }, delay);
                 retryTimer.unref?.();
                 pendingRetries.add(retryTimer);
@@ -129,13 +157,23 @@ export function createHookRunner(log = console.log, record) {
             const detail = tail === '' ? '' : `，stderr：${tail.slice(-400)}`;
             console.warn(`[dsh-hooks] hook 退出码 ${code} (${eventLabel(ctx)})${detail}`);
             rec?.({ ...base, outcome: 'exit-nonzero', exitCode: code, durationMs: Date.now() - startedAt, error: tail.slice(-400) || undefined });
+            done?.();
         });
         return { ok: true, reason: 'ran' };
     }
-    function run(spec, ctx, recordOverride) {
+    function run(spec, ctx, recordOverride, limiter) {
         if (!spec.run)
             return { ok: false, reason: 'skipped', detail: 'no run command' };
-        return spawnOnce(spec, ctx, 0, recordOverride);
+        if (limiter !== undefined) {
+            const inFlight = inFlightById.get(limiter.id) ?? 0;
+            if (inFlight >= limiter.max) {
+                const detail = `maxConcurrent 达到上限（${limiter.max}），本次触发被丢弃`;
+                recordOverride?.({ kind: 'run', event: ctx.event, command: spec.run, sessionId: ctx.sessionId, sessionName: ctx.sessionName, outcome: 'skipped', error: detail });
+                return { ok: false, reason: 'skipped', detail };
+            }
+            inFlightById.set(limiter.id, inFlight + 1);
+        }
+        return spawnOnce(spec, ctx, 0, recordOverride, () => releaseSlot(limiter));
     }
     function dispose() {
         for (const timer of pendingRetries)

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;
@@ -63,6 +63,10 @@ export declare function describeHooks(hooks: readonly HookSpec[]): {
     timeoutMs: number | undefined;
     retries: number | undefined;
     retryDelayMs: number | undefined;
+    enabled: boolean | undefined;
+    cwd: string | undefined;
+    maxConcurrent: number | undefined;
+    debounceMs: number | undefined;
 }[];
 /** Create the /dsh-hooks route handler (exported for tests). */
 export declare function createHookHandler(options: HookRoutesOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/lib/server.js

@@ -55,6 +55,21 @@ async function readJsonBody(req) {
         return null;
     }
 }
+/** Render a match value for the panel: regex source or comparison string. */
+function matchText(value) {
+    if (value instanceof RegExp)
+        return value.source;
+    // Normalize single-op objects to the equivalent string syntax so the
+    // editor round-trip keeps comparison semantics; multi-op stays JSON.
+    const ops = Object.entries(value);
+    if (ops.length === 1) {
+        const [op, n] = ops[0];
+        const symbol = { gt: '>', gte: '>=', lt: '<', lte: '<=', eq: '=' }[op];
+        if (symbol !== undefined && typeof n === 'number')
+            return `${symbol}${n}`;
+    }
+    return JSON.stringify(value);
+}
 /** Sanitized per-hook description for the settings panel (regex sources, no RegExp objects). */
 export function describeHooks(hooks) {
     return hooks.map((hook, i) => ({
@@ -63,7 +78,7 @@ export function describeHooks(hooks) {
         when: hook.when,
         match: hook.match === undefined
             ? undefined
-            : Object.fromEntries(Object.entries(hook.match).map(([field, re]) => [field, re.source])),
+            : Object.fromEntries(Object.entries(hook.match).map(([field, re]) => [field, matchText(re)])),
         run: hook.run,
         notify: hook.notify === undefined || hook.notify === null
             ? undefined
@@ -72,6 +87,10 @@ export function describeHooks(hooks) {
         timeoutMs: hook.timeoutMs,
         retries: hook.retries,
         retryDelayMs: hook.retryDelayMs,
+        enabled: hook.enabled,
+        cwd: hook.cwd,
+        maxConcurrent: hook.maxConcurrent,
+        debounceMs: hook.debounceMs,
     }));
 }
 const FAILED_OUTCOMES = new Set(['exit-nonzero', 'timeout', 'spawn-failed', 'send-failed']);

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);
+    }
+}