dsh-hooks 0.2.2 → 0.3.0

package/lib/events.d.ts

@@ -9,9 +9,23 @@ export interface ApprovalAskedData {
     callId?: string;
     reason?: string;
 }
+/** `session/title` payload (merge-extensible, declared by dsh-session-title). */
+export interface SessionTitleEventData {
+    title: string;
+    messageSeqs: number[];
+    source: {
+        kind: 'fallback';
+    } | {
+        kind: 'provider';
+        provider?: unknown;
+    } | {
+        kind: 'user';
+    };
+}
 declare module '@deepseek-ai/dsh-session/types' {
     interface SessionEventMap {
         'approval/asked': ApprovalAskedData;
+        'session/title': SessionTitleEventData;
     }
 }
 /** Agent lifecycle payloads (structural; emitted by dsh-agent's AgentService). */
@@ -45,12 +59,52 @@ 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
+ * any usage (adapters may omit it entirely).
+ */
+export declare function turnUsage(session: Session, turn: number): UsageTotals | undefined;
 export declare function rememberTurnStart(session: Session): void;
 export declare function clearTurnTracking(session: Session): void;
 /** Does a declared hook match this event (type + optional `when` filter)? */
 export declare function hookMatches(spec: HookSpec, event: string, reasonKind?: TurnEndReasonKind): boolean;
+/**
+ * Apply the optional `match` field → regex filters. Every declared regex
+ * must match its context field (String-coerced); a field the context does
+ * not carry never matches. An empty/absent `match` passes everything.
+ * RegExps come pre-compiled from the config schema; non-RegExp entries are
+ * rejected defensively (never match).
+ */
+export declare function matchFilters(match: Record<string, RegExp> | undefined, ctx: HookContext): boolean;
 export declare function turnEndContext(session: Session, turn: number, reason: TurnEndReason | string): HookContext;
 export declare function turnStartContext(session: Session, turn: number): HookContext;
+export declare function stepEndContext(session: Session, turn: number, step: number): HookContext;
+export declare function toolCallContext(session: Session, turn: number, step: number, callId: unknown, name: unknown, args: unknown): HookContext;
+export declare function toolResultContext(session: Session, turn: number, step: number, callId: unknown, message: {
+    content?: readonly {
+        type?: unknown;
+        text?: unknown;
+    }[];
+}, error: {
+    name?: unknown;
+    code?: unknown;
+} | undefined): HookContext;
+export declare function userMessageContext(session: Session, content: readonly {
+    type?: unknown;
+    text?: unknown;
+}[], source: unknown): HookContext;
+export declare function titleContext(session: Session, title: unknown, source: unknown): HookContext;
+export declare function sessionCreatedContext(session: Session): HookContext;
+export declare function sessionDisposedContext(session: Session): HookContext;
 export declare function approvalContext(session: Session, data: ApprovalAskedData): HookContext;
 export declare function agentCreatedContext(agent: AgentLike): HookContext;
 export declare function agentDisposedContext(agent: AgentLike): HookContext;

package/lib/events.js

@@ -1,8 +1,13 @@
 /** Per-session turn start timestamps for duration reporting. */
 const turnStarts = new Map();
+/** Tool name for an in-flight call, remembered at `tool/call` and consumed at `tool/result`. */
+const callTools = new Map();
 function sessionKey(session) {
     return String(session.id);
 }
+function callKey(session, callId) {
+    return `${sessionKey(session)}\u0000${String(callId)}`;
+}
 /** Best-effort access to a session's event log (test fakes may omit it). */
 function sessionEvents(session) {
     return Array.isArray(session.events) ? session.events : [];
@@ -76,6 +81,36 @@ export function turnContent(session, turn) {
     }
     return out === undefined ? undefined : out.slice(0, 4000);
 }
+/**
+ * Sum the `usage` of every `assistant/message` of a turn. Steps without
+ * reported accounting are skipped; returns undefined when no step reported
+ * any usage (adapters may omit it entirely).
+ */
+export function turnUsage(session, turn) {
+    let totals;
+    for (const event of sessionEvents(session)) {
+        if (event.type !== 'assistant/message')
+            continue;
+        if (event.data.turn !== turn)
+            continue;
+        const usage = event.data.usage;
+        if (typeof usage?.inputTokens !== 'number')
+            continue;
+        totals ??= { inputTokens: 0, outputTokens: 0 };
+        totals.inputTokens += usage.inputTokens;
+        totals.outputTokens += usage.outputTokens;
+        if (typeof usage.cacheReadTokens === 'number') {
+            totals.cacheReadTokens = (totals.cacheReadTokens ?? 0) + usage.cacheReadTokens;
+        }
+        if (typeof usage.cacheWriteTokens === 'number') {
+            totals.cacheWriteTokens = (totals.cacheWriteTokens ?? 0) + usage.cacheWriteTokens;
+        }
+        if (typeof usage.reasoningTokens === 'number') {
+            totals.reasoningTokens = (totals.reasoningTokens ?? 0) + usage.reasoningTokens;
+        }
+    }
+    return totals;
+}
 export function rememberTurnStart(session) {
     turnStarts.set(sessionKey(session), Date.now());
 }
@@ -99,6 +134,36 @@ export function hookMatches(spec, event, reasonKind) {
         return true;
     return spec.when === reasonKind;
 }
+/**
+ * Apply the optional `match` field → regex filters. Every declared regex
+ * must match its context field (String-coerced); a field the context does
+ * not carry never matches. An empty/absent `match` passes everything.
+ * RegExps come pre-compiled from the config schema; non-RegExp entries are
+ * rejected defensively (never match).
+ */
+export function matchFilters(match, ctx) {
+    if (match === undefined)
+        return true;
+    for (const [field, pattern] of Object.entries(match)) {
+        if (!(pattern instanceof RegExp))
+            return false;
+        const value = ctx[field];
+        if (value === undefined)
+            return false;
+        if (!pattern.test(String(value)))
+            return false;
+    }
+    return true;
+}
+function baseContext(session, event) {
+    return {
+        event,
+        sessionId: sessionKey(session),
+        sessionName: sessionTitle(session),
+        cwd: session.header.cwd,
+        timestamp: new Date().toISOString(),
+    };
+}
 export function turnEndContext(session, turn, reason) {
     const kind = typeof reason === 'string' ? reason : reason.kind;
     let error;
@@ -107,39 +172,108 @@ export function turnEndContext(session, turn, reason) {
         if (typeof failure?.message === 'string')
             error = failure.message;
     }
+    const usage = turnUsage(session, turn);
     return {
-        event: 'turn/end',
-        sessionId: sessionKey(session),
-        sessionName: sessionTitle(session),
-        cwd: session.header.cwd,
+        ...baseContext(session, 'turn/end'),
         turn,
         reason: kind,
         durationMs: takeDuration(session),
         error,
         content: turnContent(session, turn),
-        timestamp: new Date().toISOString(),
+        usageInputTokens: usage?.inputTokens,
+        usageOutputTokens: usage?.outputTokens,
+        usageCacheReadTokens: usage?.cacheReadTokens,
+        usageCacheWriteTokens: usage?.cacheWriteTokens,
+        usageReasoningTokens: usage?.reasoningTokens,
     };
 }
 export function turnStartContext(session, turn) {
+    return { ...baseContext(session, 'turn/start'), turn };
+}
+export function stepEndContext(session, turn, step) {
+    return { ...baseContext(session, 'step/end'), turn, step };
+}
+export function toolCallContext(session, turn, step, callId, name, args) {
+    const key = callKey(session, callId);
+    callTools.set(key, typeof name === 'string' ? name : String(name));
+    return {
+        ...baseContext(session, 'tool/call'),
+        turn,
+        step,
+        tool: typeof name === 'string' ? name : String(name),
+        callId: String(callId),
+        toolArgs: typeof args === 'string' ? args.slice(0, 4000) : undefined,
+    };
+}
+export function toolResultContext(session, turn, step, callId, message, error) {
+    const key = callKey(session, callId);
+    const tool = callTools.get(key);
+    if (tool !== undefined)
+        callTools.delete(key);
+    let toolError;
+    if (error !== undefined) {
+        const name = typeof error.name === 'string' ? error.name : undefined;
+        const code = typeof error.code === 'string' ? error.code : undefined;
+        if (name !== undefined || code !== undefined)
+            toolError = [name, code].filter(Boolean).join(': ');
+    }
+    const content = textOfBlocks(message.content);
+    return {
+        ...baseContext(session, 'tool/result'),
+        turn,
+        step,
+        tool,
+        callId: String(callId),
+        toolError,
+        content: content === undefined ? undefined : content.slice(0, 4000),
+    };
+}
+export function userMessageContext(session, content, source) {
+    const kind = typeof source === 'object' && source !== null && 'kind' in source
+        ? String(source.kind)
+        : undefined;
+    const text = textOfBlocks(content);
+    return {
+        ...baseContext(session, 'user/message'),
+        source: kind,
+        content: text === undefined ? undefined : text.slice(0, 4000),
+    };
+}
+export function titleContext(session, title, source) {
+    const kind = typeof source === 'object' && source !== null && 'kind' in source
+        ? String(source.kind)
+        : undefined;
+    const cleaned = title === undefined ? undefined : oneLineTitle(title);
     return {
-        event: 'turn/start',
+        ...baseContext(session, 'session/title'),
+        sessionName: cleaned === undefined || cleaned === '' ? undefined : cleaned.slice(0, 60),
+        source: kind,
+    };
+}
+export function sessionCreatedContext(session) {
+    return {
+        event: 'session/created',
         sessionId: sessionKey(session),
         sessionName: sessionTitle(session),
         cwd: session.header.cwd,
-        turn,
         timestamp: new Date().toISOString(),
     };
 }
-export function approvalContext(session, data) {
+export function sessionDisposedContext(session) {
     return {
-        event: 'approval/asked',
+        event: 'session/disposed',
         sessionId: sessionKey(session),
         sessionName: sessionTitle(session),
         cwd: session.header.cwd,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function approvalContext(session, data) {
+    return {
+        ...baseContext(session, 'approval/asked'),
         tool: data.toolName,
         callId: data.callId,
         reason: data.reason,
-        timestamp: new Date().toISOString(),
     };
 }
 export function agentCreatedContext(agent) {
@@ -181,8 +315,24 @@ export function classifySessionEvent(session, event) {
             return turnStartContext(session, event.data.turn);
         case 'turn/end':
             return turnEndContext(session, event.data.turn, event.data.reason);
+        case 'step/end':
+            return stepEndContext(session, event.data.turn, event.data.step);
+        case 'tool/call':
+            return toolCallContext(session, event.data.turn, event.data.step, event.data.callId, event.data.name, event.data.arguments);
+        case 'tool/result': {
+            // The call id rides the tool-result block (and the tool source), not
+            // the event envelope — resolve it structurally with fallbacks.
+            const block = event.data.message.content[0];
+            const source = event.data.message.source;
+            const callId = block?.toolCallId ?? source?.callId;
+            return toolResultContext(session, event.data.turn, event.data.step, callId, event.data.message.content[0], event.data.error);
+        }
+        case 'user/message':
+            return userMessageContext(session, event.data.content, event.data.source);
         case 'approval/asked':
             return approvalContext(session, event.data);
+        case 'session/title':
+            return titleContext(session, event.data.title, event.data.source);
         default:
             return undefined;
     }

package/lib/history.d.ts

@@ -0,0 +1,34 @@
+/** One recorded hook execution. No secrets: env vars never enter records. */
+export interface HookRunRecord {
+    /** Epoch milliseconds when the record was written. */
+    ts: number;
+    /** `run` (spawned command) or `notify` (built-in channel). */
+    kind: 'run' | 'notify';
+    event: string;
+    /** Rendered command (`run`) or `notify:<channel>` (`notify`). */
+    command: string;
+    sessionId?: string;
+    sessionName?: string;
+    outcome: 'spawned' | 'spawn-failed' | 'timeout' | 'exit-0' | 'exit-nonzero' | 'sent' | 'send-failed';
+    exitCode?: number;
+    durationMs?: number;
+    /** stderr tail or error message. */
+    error?: string;
+}
+export declare const DEFAULT_HISTORY_PATH: string;
+export declare const DEFAULT_HISTORY_MAX = 500;
+export interface HistorySinkOptions {
+    /** Whether to persist records to disk. Defaults to true. */
+    enabled?: boolean;
+    /** JSONL file path. Defaults to ~/.dsh/dsh-hooks/history.jsonl. */
+    path?: string;
+    /** In-memory ring buffer size. Defaults to 500. */
+    max?: number;
+}
+export interface HistorySink {
+    record(record: Omit<HookRunRecord, 'ts'>): void;
+    /** Most recent records, oldest first. */
+    recent(): readonly HookRunRecord[];
+    dispose(): void;
+}
+export declare function createHistorySink(options?: HistorySinkOptions): HistorySink;

package/lib/history.js

@@ -0,0 +1,50 @@
+/**
+ * Hook execution history: an in-memory ring buffer plus a best-effort
+ * JSONL append log under ~/.dsh/dsh-hooks/ (0600, owner-only). History is
+ * strictly best-effort — a failed write never breaks a hook.
+ */
+import { appendFileSync, chmodSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_HISTORY_PATH = join(homedir(), '.dsh', 'dsh-hooks', 'history.jsonl');
+export const DEFAULT_HISTORY_MAX = 500;
+export function createHistorySink(options = {}) {
+    const enabled = options.enabled ?? true;
+    const file = options.path ?? DEFAULT_HISTORY_PATH;
+    const max = options.max ?? DEFAULT_HISTORY_MAX;
+    const buffer = [];
+    let dirReady = false;
+    let chmodded = false;
+    function record(partial) {
+        const entry = { ...partial, ts: Date.now() };
+        buffer.push(entry);
+        if (buffer.length > max)
+            buffer.splice(0, buffer.length - max);
+        if (!enabled)
+            return;
+        try {
+            if (!dirReady) {
+                mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+                dirReady = true;
+            }
+            appendFileSync(file, JSON.stringify(entry) + '\n', 'utf8');
+            if (!chmodded) {
+                try {
+                    chmodSync(file, 0o600);
+                }
+                catch {
+                    // Windows: ACL-based protection; the file lives under the user profile.
+                }
+                chmodded = true;
+            }
+        }
+        catch {
+            // History is best-effort: a failed write never breaks a hook.
+        }
+    }
+    return {
+        record,
+        recent: () => buffer,
+        dispose: () => { },
+    };
+}

package/lib/index.d.ts

@@ -3,8 +3,15 @@ import './types.js';
 import { Config } from './config.js';
 import { clearTurnTracking } from './events.js';
 export declare const name = "dsh-hooks";
-export declare const inject: readonly ["sessions"];
+export declare const inject: readonly ['sessions'];
 export { Config };
+export { hookMatches, matchFilters } from './events.js';
+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\u3001step/end\u3001tool/call\u3001tool/result\u3001user/message\u3001approval/asked\u3001session/title\u3001session/created\u3001session/disposed\u3001agent/created\u3001agent/disposed\u3001agent/error\u3001agent/status \u5171 14 \u7C7B\u4E8B\u4EF6\uFF09\uFF0C\u652F\u6301 when \u539F\u56E0\u8FC7\u6EE4\u3001match \u5B57\u6BB5\u6B63\u5219\u8FC7\u6EE4\u3001stdin JSON \u8F93\u5165\u3001opt-in \u91CD\u8BD5\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,23 +1,57 @@
 import './types.js';
 import { Config } from './config.js';
-import { agentCreatedContext, agentDisposedContext, agentErrorContext, agentStatusContext, classifySessionEvent, clearTurnTracking, hookMatches, } from './events.js';
+import { agentCreatedContext, agentDisposedContext, agentErrorContext, agentStatusContext, classifySessionEvent, clearTurnTracking, hookMatches, matchFilters, sessionCreatedContext, sessionDisposedContext, } from './events.js';
+import { eventLabel } from './context.js';
 import { createHookRunner } from './runner.js';
+import { fireNotify } from './notify.js';
+import { createHistorySink } from './history.js';
+import { registerHookRoutes } from './server.js';
 export const name = 'dsh-hooks';
 // Dependency on the session service: `session/event` only exists once a
 // SessionStore is composed, and this plugin consumes the durable firehose.
 export const inject = ['sessions'];
 export { Config };
+export { hookMatches, matchFilters } from './events.js';
+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、step/end、tool/call、tool/result、user/message、approval/asked、session/title、session/created、session/disposed、agent/created、agent/disposed、agent/error、agent/status 共 14 类事件），支持 when 原因过滤、match 字段正则过滤、stdin JSON 输入、opt-in 重试、内置 webhook/desktop 通知渠道；执行历史记录于 ~/.dsh/dsh-hooks/history.jsonl；`dsh-hooks dry-run <event>` 可模拟事件验证配置。用户提到「hooks / 钩子 / 生命周期 / 通知配置」时即指本插件，请据此协作。';
 export function apply(ctx, config = {}) {
     const hooks = config.hooks ?? [];
-    const runner = createHookRunner((line) => ctx.logger?.info(line));
+    const history = createHistorySink(config.history ?? undefined);
+    const runner = createHookRunner((line) => ctx.logger?.info(line), (record) => history.record(record));
+    // Web-profile extras: /dsh-hooks routes and the agent announcement. Both
+    // services are optional — CLI/headless profiles provide neither, and the
+    // plugin keeps working there untouched.
+    const webServer = ctx.get('webServer', false);
+    if (webServer !== undefined) {
+        ctx.effect(() => registerHookRoutes(webServer, { hooks, history }), 'dsh-hooks: /dsh-hooks routes');
+    }
+    const systemPrompt = ctx.get('systemPrompt', false);
+    if (systemPrompt !== undefined) {
+        ctx.effect(() => systemPrompt.section({ name: 'plugin:dsh-hooks', order: 200, text: DSH_HOOKS_GUIDANCE }), 'dsh-hooks: prompt section');
+    }
     const runMatching = (ctxValue, reasonKind) => {
         for (const hook of hooks) {
             if (!hookMatches(hook, ctxValue.event, reasonKind))
                 continue;
-            runner.run(hook, ctxValue);
+            if (!matchFilters(hook.match, ctxValue))
+                continue;
+            if (hook.notify) {
+                void fireNotify(hook.notify, ctxValue, (record) => history.record(record));
+                continue;
+            }
+            if (hook.run) {
+                runner.run(hook, ctxValue);
+                continue;
+            }
+            console.warn(`[dsh-hooks] hook 既没有 run 也没有 notify，已跳过：${eventLabel(ctxValue)}`);
         }
     };
-    // Durable session firehose: turn boundaries and approval requests.
+    // Durable session firehose: turn boundaries, steps, tool calls, messages,
+    // titles, and approval requests.
     ctx.on('session/event', (session, event) => {
         const classified = classifySessionEvent(session, event);
         if (classified === undefined)
@@ -25,6 +59,13 @@ export function apply(ctx, config = {}) {
         const reasonKind = extractReasonKind(event);
         runMatching(classified, reasonKind);
     });
+    // Session lifecycle (published by the session store, not the firehose).
+    ctx.on('session/created', (session) => {
+        runMatching(sessionCreatedContext(session));
+    });
+    ctx.on('session/disposed', (session) => {
+        runMatching(sessionDisposedContext(session));
+    });
     // Agent lifecycle events.
     ctx.on('agent/created', (payload) => {
         runMatching(agentCreatedContext(payload.agent));

package/lib/notify.d.ts

@@ -0,0 +1,28 @@
+import type { HookContext } from './context.js';
+import type { NotifySpec } from './config.js';
+import type { HookRunRecord } from './history.js';
+export interface NotifyResult {
+    ok: boolean;
+    error?: string;
+}
+export type NotifyRecord = (record: Omit<HookRunRecord, 'ts'>) => void;
+/** Fetch timeout for webhook sends (ms). */
+export declare const NOTIFY_TIMEOUT_MS = 10000;
+/** 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.
+ */
+export declare function sendWebhook(spec: NotifySpec, ctx: HookContext, env?: NodeJS.ProcessEnv): 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. */
+export declare function fireNotify(spec: NotifySpec, ctx: HookContext, record?: NotifyRecord): Promise<void>;