dsh-hooks 0.11.0 → 0.13.0

package/lib/tail.js

@@ -0,0 +1,154 @@
+/**
+ * Incremental reader for the hook history JSONL log, behind
+ * `dsh-hooks tail`. It follows the same rules as the history sink — complete
+ * lines only, a shrinking file means rotation/truncation and resets the
+ * offset, a broken line never throws — but it is strictly read-only and keeps
+ * no ring buffer: it hands each new batch to the caller.
+ *
+ * The reader tracks a byte offset plus the trailing fragment of the last read
+ * (a line can be observed mid-write). Decoding happens per chunk, exactly like
+ * the sink does, so a multibyte character split across two reads can cost one
+ * malformed line at worst — never a crash.
+ */
+import { closeSync, existsSync, openSync, readSync, statSync } from 'node:fs';
+/** Bytes of the file tail read for the initial backfill. */
+export const TAIL_BACKFILL_BYTES = 64 * 1024;
+/** Does a record pass every configured filter? */
+export function matchesTailFilter(record, filter) {
+    if (filter.event !== undefined && record.event !== filter.event)
+        return false;
+    if (filter.outcome !== undefined && record.outcome !== filter.outcome)
+        return false;
+    if (filter.hook !== undefined && !record.command.includes(filter.hook))
+        return false;
+    return true;
+}
+/** Local `HH:MM:SS` stamp for a record's epoch-ms timestamp. */
+function clockTime(ts) {
+    const date = new Date(ts);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+/** One human-readable line, aligned with the Web GUI's history timeline. */
+export function formatTailRecord(record) {
+    const parts = [clockTime(record.ts), record.event, record.command, record.outcome];
+    if (record.durationMs !== undefined)
+        parts.push(`${record.durationMs}ms`);
+    if (record.exitCode !== undefined && record.exitCode !== 0)
+        parts.push(`exit=${record.exitCode}`);
+    if (record.sessionName || record.sessionId)
+        parts.push(record.sessionName ?? String(record.sessionId));
+    let line = parts.join('  ');
+    if (record.error)
+        line += `\n    ${record.error.replace(/\s+/g, ' ').slice(0, 300)}`;
+    return line;
+}
+/** Parse one JSONL line into a record, or undefined when it is unreadable. */
+function parseRecord(line) {
+    try {
+        const entry = JSON.parse(line);
+        if (typeof entry !== 'object' || entry === null || typeof entry.ts !== 'number')
+            return undefined;
+        return entry;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class HistoryTailer {
+    file;
+    #offset = 0;
+    #pending = '';
+    constructor(file) {
+        this.file = file;
+    }
+    /** Bytes already consumed (the next read starts here). */
+    get offset() {
+        return this.#offset;
+    }
+    /** Read `[start, end)` as text (best-effort: returns '' when unreadable). */
+    #read(start, end) {
+        const length = end - start;
+        if (length <= 0)
+            return '';
+        const fd = openSync(this.file, 'r');
+        try {
+            const chunk = Buffer.allocUnsafe(length);
+            let total = 0;
+            while (total < length) {
+                const read = readSync(fd, chunk, total, length - total, start + total);
+                if (read <= 0)
+                    break;
+                total += read;
+            }
+            return chunk.subarray(0, total).toString('utf8');
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /**
+     * 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 = 10, maxBytes = TAIL_BACKFILL_BYTES) {
+        if (!existsSync(this.file))
+            return [];
+        const size = statSync(this.file).size;
+        if (size === 0) {
+            this.#offset = 0;
+            this.#pending = '';
+            return [];
+        }
+        const start = Math.max(0, size - Math.max(0, maxBytes));
+        const text = this.#read(start, size);
+        this.#offset = size;
+        this.#pending = '';
+        let lines = text.split('\n');
+        // Reading from the middle of the file starts mid-line: drop that fragment.
+        if (start > 0)
+            lines = lines.slice(1);
+        const records = [];
+        for (const line of lines) {
+            if (line === '')
+                continue;
+            const record = parseRecord(line);
+            if (record !== undefined)
+                records.push(record);
+        }
+        return limit > 0 ? records.slice(-limit) : records;
+    }
+    /**
+     * 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() {
+        const batch = { records: [], lines: [], reset: false };
+        if (!existsSync(this.file))
+            return batch;
+        const size = statSync(this.file).size;
+        if (size < this.#offset) {
+            this.#offset = 0;
+            this.#pending = '';
+            batch.reset = true;
+        }
+        if (size === this.#offset)
+            return batch;
+        const text = this.#pending + this.#read(this.#offset, size);
+        this.#offset = size;
+        const parts = text.split('\n');
+        this.#pending = parts.pop() ?? '';
+        for (const line of parts) {
+            if (line === '')
+                continue;
+            batch.lines.push(line);
+            const record = parseRecord(line);
+            if (record !== undefined)
+                batch.records.push(record);
+        }
+        return batch;
+    }
+}

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.13.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"
   }