dsh-hooks 0.2.2 → 0.4.0

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>;

package/lib/notify.js

@@ -0,0 +1,226 @@
+/**
+ * Built-in notification channels: webhook (HTTP JSON POST) and desktop
+ * (platform-native balloon/toast). Config-driven — a hook declares
+ * `notify: { channel, url?, slack? }` and needs no external script.
+ * Failures only warn, never block the agent loop.
+ */
+import { spawn } from 'node:child_process';
+import { eventLabel } from './context.js';
+/** Fetch timeout for webhook sends (ms). */
+export const NOTIFY_TIMEOUT_MS = 10000;
+/** One-line summary for Slack-style and desktop notifications. */
+export function summarizeContext(ctx) {
+    const label = ctx.sessionName || ctx.sessionId || '';
+    const where = label ? ` · ${label}` : '';
+    switch (ctx.event) {
+        case 'turn/end':
+            if (ctx.reason === 'completed')
+                return `✅ 任务已完成${where}（回合 #${ctx.turn ?? '?'}）`;
+            if (ctx.error)
+                return `❌ 任务失败${where}: ${ctx.error.slice(0, 200)}`;
+            return `⏸ 任务${ctx.reason ? ` ${ctx.reason}` : '结束'}${where}（回合 #${ctx.turn ?? '?'}）`;
+        case 'tool/call':
+            return `🔧 调用工具 ${ctx.tool ?? ''}${where}`;
+        case 'tool/result':
+            if (ctx.toolError)
+                return `⚠️ 工具 ${ctx.tool ?? ''} 失败${where}: ${ctx.toolError}`;
+            return `✅ 工具 ${ctx.tool ?? ''} 完成${where}`;
+        case 'approval/asked':
+            return `⏳ 需要审批：工具 ${ctx.tool ?? ''}${where}`;
+        case 'user/message':
+            return `💬 新消息${where}${ctx.content ? `：${ctx.content.slice(0, 120)}` : ''}`;
+        case 'session/title':
+            return `🏷 会话改名${where}: ${ctx.sessionName ?? ''}`;
+        case 'session/created':
+            return `✨ 会话开始${where}`;
+        case 'session/disposed':
+            return `🏁 会话结束${where}`;
+        case 'agent/error':
+            return `⚠️ Agent 出错${where}${ctx.error ? `: ${ctx.error.slice(0, 200)}` : ''}`;
+        default:
+            return `🔔 DSH ${ctx.event}${where}`;
+    }
+}
+/** Structured JSON document for the webhook channel (present fields only). */
+export function webhookPayload(ctx) {
+    const payload = { event: ctx.event, timestamp: ctx.timestamp };
+    const session = {};
+    if (ctx.sessionId)
+        session.id = ctx.sessionId;
+    if (ctx.sessionName)
+        session.name = ctx.sessionName;
+    if (ctx.cwd)
+        session.cwd = ctx.cwd;
+    if (Object.keys(session).length > 0)
+        payload.session = session;
+    if (ctx.turn !== undefined)
+        payload.turn = ctx.turn;
+    if (ctx.step !== undefined)
+        payload.step = ctx.step;
+    if (ctx.reason !== undefined)
+        payload.reason = ctx.reason;
+    if (ctx.tool !== undefined)
+        payload.tool = ctx.tool;
+    if (ctx.callId !== undefined)
+        payload.call_id = ctx.callId;
+    if (ctx.toolArgs !== undefined)
+        payload.tool_args = ctx.toolArgs;
+    if (ctx.toolError !== undefined)
+        payload.tool_error = ctx.toolError;
+    if (ctx.source !== undefined)
+        payload.source = ctx.source;
+    if (ctx.durationMs !== undefined)
+        payload.duration_ms = ctx.durationMs;
+    if (ctx.status !== undefined)
+        payload.status = ctx.status;
+    if (ctx.error !== undefined)
+        payload.error = ctx.error;
+    if (ctx.content !== undefined)
+        payload.content = ctx.content;
+    const usage = {};
+    if (ctx.usageInputTokens !== undefined)
+        usage.input_tokens = ctx.usageInputTokens;
+    if (ctx.usageOutputTokens !== undefined)
+        usage.output_tokens = ctx.usageOutputTokens;
+    if (ctx.usageCacheReadTokens !== undefined)
+        usage.cache_read_tokens = ctx.usageCacheReadTokens;
+    if (ctx.usageCacheWriteTokens !== undefined)
+        usage.cache_write_tokens = ctx.usageCacheWriteTokens;
+    if (ctx.usageReasoningTokens !== undefined)
+        usage.reasoning_tokens = ctx.usageReasoningTokens;
+    if (Object.keys(usage).length > 0)
+        payload.usage = usage;
+    return payload;
+}
+/**
+ * POST the context to a webhook endpoint. One retry on transport failure
+ * (webhook endpoints often drop the first request when cold). The URL comes
+ * from `spec.url` or the `DSH_HOOKS_WEBHOOK_URL` environment variable.
+ */
+export async function sendWebhook(spec, ctx, env = process.env) {
+    const url = spec.url || env.DSH_HOOKS_WEBHOOK_URL;
+    if (!url)
+        return { ok: false, error: '缺少 webhook URL（notify.url 或 DSH_HOOKS_WEBHOOK_URL）' };
+    const body = spec.slack ? { text: summarizeContext(ctx) } : webhookPayload(ctx);
+    const attempt = async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), NOTIFY_TIMEOUT_MS);
+        try {
+            return await fetch(url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    let response;
+    try {
+        response = await attempt();
+    }
+    catch (error) {
+        try {
+            response = await attempt();
+        }
+        catch (retryError) {
+            const cause = retryError instanceof Error ? retryError.message : String(retryError);
+            return { ok: false, error: `webhook 请求失败（重试后仍失败）: ${cause}` };
+        }
+    }
+    if (!response.ok)
+        return { ok: false, error: `webhook 响应 HTTP ${response.status}` };
+    return { ok: true };
+}
+/**
+ * Desktop balloon/toast notification. The summary travels through an
+ * environment variable (Windows PowerShell) or argv (macOS/Linux), never
+ * through shell-string interpolation.
+ */
+export async function sendDesktop(spec, ctx) {
+    const text = summarizeContext(ctx);
+    const platform = process.platform;
+    try {
+        if (platform === 'win32') {
+            await runAndWait(['powershell', '-NoProfile', '-STA', '-Command', [
+                    'Add-Type -AssemblyName System.Windows.Forms',
+                    '$n = New-Object System.Windows.Forms.NotifyIcon',
+                    '$n.Icon = [System.Drawing.SystemIcons]::Information',
+                    '$n.Visible = $true',
+                    `$n.ShowBalloonTip(8000, 'dsh-hooks', $env:DSH_HOOK_NOTIFY_TEXT, [System.Windows.Forms.ToolTipIcon]::Info)`,
+                    'Start-Sleep -Seconds 9',
+                    '$n.Dispose()',
+                ].join('; ')], { DSH_HOOK_NOTIFY_TEXT: text }, 15000);
+            return { ok: true };
+        }
+        if (platform === 'darwin') {
+            const script = `display notification ${JSON.stringify(text)} with title "dsh-hooks"`;
+            await runAndWait(['osascript', '-e', script], {}, 10000);
+            return { ok: true };
+        }
+        await runAndWait(['notify-send', 'dsh-hooks', text], {}, 10000);
+        return { ok: true };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `桌面通知失败: ${detail}` };
+    }
+}
+/** Spawn one OS command and wait for its exit code (timeout kills it). */
+function runAndWait(argv, env, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(argv[0], argv.slice(1), { stdio: 'ignore', env: { ...process.env, ...env } });
+        }
+        catch (error) {
+            reject(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`命令超时（${timeoutMs}ms）`));
+        }, timeoutMs);
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`退出码 ${code}`));
+        });
+    });
+}
+/** Fire a built-in notification; failures only warn. */
+export async function fireNotify(spec, ctx, record) {
+    const startedAt = Date.now();
+    const result = spec.channel === 'webhook' ? await sendWebhook(spec, ctx) : await sendDesktop(spec, ctx);
+    if (!result.ok) {
+        console.warn(`[dsh-hooks] 通知发送失败 (${eventLabel(ctx)}): ${result.error}`);
+        record?.({
+            kind: 'notify',
+            event: ctx.event,
+            command: `notify:${spec.channel}`,
+            sessionId: ctx.sessionId,
+            sessionName: ctx.sessionName,
+            outcome: 'send-failed',
+            durationMs: Date.now() - startedAt,
+            error: result.error,
+        });
+        return;
+    }
+    record?.({
+        kind: 'notify',
+        event: ctx.event,
+        command: `notify:${spec.channel}`,
+        sessionId: ctx.sessionId,
+        sessionName: ctx.sessionName,
+        outcome: 'sent',
+        durationMs: Date.now() - startedAt,
+    });
+}

package/lib/runner.d.ts

@@ -1,6 +1,7 @@
 import { type ChildProcess } from 'node:child_process';
 import type { HookContext } from './context.js';
 import type { HookSpec } from './config.js';
+import type { HookRunRecord } from './history.js';
 export interface RunOutcome {
     ok: boolean;
     reason: 'ran' | 'timeout' | 'spawn-failed' | 'skipped';
@@ -11,7 +12,9 @@ export interface HookRunner {
     run(spec: HookSpec, ctx: HookContext): RunOutcome;
     dispose(): void;
 }
+export type RunRecord = (record: Omit<HookRunRecord, 'ts'>) => void;
 export declare const DEFAULT_TIMEOUT_MS = 10000;
+export declare const DEFAULT_RETRY_DELAY_MS = 500;
 /**
  * Terminate a spawned hook process. With `shell: true` on Windows the direct
  * child is cmd.exe — killing only the shell orphans the actual hook command
@@ -21,9 +24,11 @@ export declare const DEFAULT_TIMEOUT_MS = 10000;
 export declare function terminate(child: ChildProcess): void;
 /**
  * Fire-and-forget command runner. Emissions are irreversible side effects:
- * failures only warn, never retried, never block the agent loop.
- * Context travels through environment variables (no data interpolation into
- * the shell string); `{{var}}` placeholders are substituted from the same
- * map for explicit templating by the user.
+ * failures only warn, never block the agent loop. Context travels through
+ * environment variables (no data interpolation into the shell string);
+ * `{{var}}` placeholders are substituted from the same map for explicit
+ * 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).
  */
-export declare function createHookRunner(log?: (line: string) => void): HookRunner;
+export declare function createHookRunner(log?: (line: string) => void, record?: RunRecord): HookRunner;

package/lib/runner.js

@@ -1,6 +1,14 @@
 import { spawn } from 'node:child_process';
 import { eventLabel, renderTemplate, toEnv } from './context.js';
 export const DEFAULT_TIMEOUT_MS = 10000;
+export const DEFAULT_RETRY_DELAY_MS = 500;
+/**
+ * Per-stream capture cap. The hook's stdout/stderr is only kept for
+ * failure diagnostics, so anything past 64 KiB is drained and dropped
+ * (reading must never stop — a stopped reader would fill the pipe buffer
+ * and wedge the hook process).
+ */
+const MAX_CAPTURE_BYTES = 64 * 1024;
 /**
  * Terminate a spawned hook process. With `shell: true` on Windows the direct
  * child is cmd.exe — killing only the shell orphans the actual hook command
@@ -20,48 +28,116 @@ export function terminate(child) {
 }
 /**
  * Fire-and-forget command runner. Emissions are irreversible side effects:
- * failures only warn, never retried, never block the agent loop.
- * Context travels through environment variables (no data interpolation into
- * the shell string); `{{var}}` placeholders are substituted from the same
- * map for explicit templating by the user.
+ * failures only warn, never block the agent loop. Context travels through
+ * environment variables (no data interpolation into the shell string);
+ * `{{var}}` placeholders are substituted from the same map for explicit
+ * 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).
  */
-export function createHookRunner(log = console.log) {
+export function createHookRunner(log = console.log, record) {
     const children = new Set();
-    function run(spec, ctx) {
+    const pendingRetries = new Set();
+    function spawnOnce(spec, ctx, attempt) {
+        if (!spec.run)
+            return { ok: false, reason: 'skipped', detail: 'no run command' };
         const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const retries = spec.retries ?? 0;
+        const retryDelayMs = spec.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
         const env = toEnv(ctx);
         const command = renderTemplate(spec.run, ctx);
+        const useStdin = spec.input === 'stdin';
+        const base = {
+            kind: 'run',
+            event: ctx.event,
+            command,
+            sessionId: ctx.sessionId,
+            sessionName: ctx.sessionName,
+        };
         log(`[dsh-hooks] 触发 ${eventLabel(ctx)} → ${command}`);
         let child;
         try {
             child = spawn(command, {
                 shell: true,
                 env: { ...process.env, ...env },
-                stdio: 'ignore',
+                stdio: [useStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
             });
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : String(error);
             console.warn(`[dsh-hooks] spawn 失败 (${eventLabel(ctx)}): ${detail}`);
+            record?.({ ...base, outcome: 'spawn-failed', error: detail });
             return { ok: false, reason: 'spawn-failed', detail };
         }
+        const startedAt = Date.now();
+        record?.({ ...base, outcome: 'spawned' });
         children.add(child);
+        let timedOut = false;
         const timer = setTimeout(() => {
+            timedOut = true;
             terminate(child);
             console.warn(`[dsh-hooks] 超时（${timeoutMs}ms），已终止：${eventLabel(ctx)}`);
+            record?.({ ...base, outcome: 'timeout', durationMs: Date.now() - startedAt });
         }, timeoutMs);
         // Never hold the process open for a hook.
         child.unref();
+        if (useStdin && child.stdin) {
+            // The hook may exit before reading stdin (EPIPE on write): the close
+            // handler owns failure reporting, so swallow the stream error.
+            child.stdin.on('error', () => { });
+            child.stdin.write(JSON.stringify(ctx));
+            child.stdin.end();
+        }
+        const captured = { out: '', err: '' };
+        const capture = (target) => (chunk) => {
+            const text = String(chunk);
+            const room = MAX_CAPTURE_BYTES - captured[target].length;
+            if (room > 0)
+                captured[target] += text.slice(0, room);
+        };
+        child.stdout?.on('data', capture('out'));
+        child.stderr?.on('data', capture('err'));
         child.on('error', (error) => {
             console.warn(`[dsh-hooks] 执行出错 (${eventLabel(ctx)}): ${error.message}`);
         });
-        child.on('close', () => {
+        child.on('close', (code) => {
             clearTimeout(timer);
             children.delete(child);
+            // Timeouts and external kills (dispose) never retry; only a command
+            // that actually ran and exited non-zero does.
+            if (timedOut || code === null || code === 0) {
+                if (!timedOut && code !== null) {
+                    record?.({ ...base, outcome: 'exit-0', exitCode: 0, durationMs: Date.now() - startedAt });
+                }
+                return;
+            }
+            if (attempt < retries) {
+                const delay = retryDelayMs * 2 ** attempt;
+                log(`[dsh-hooks] hook 退出码 ${code}，${delay}ms 后重试（${attempt + 1}/${retries}）：${eventLabel(ctx)}`);
+                const retryTimer = setTimeout(() => {
+                    pendingRetries.delete(retryTimer);
+                    spawnOnce(spec, ctx, attempt + 1);
+                }, delay);
+                retryTimer.unref?.();
+                pendingRetries.add(retryTimer);
+                return;
+            }
+            const tail = captured.err.trim();
+            const detail = tail === '' ? '' : `，stderr：${tail.slice(-400)}`;
+            console.warn(`[dsh-hooks] hook 退出码 ${code} (${eventLabel(ctx)})${detail}`);
+            record?.({ ...base, outcome: 'exit-nonzero', exitCode: code, durationMs: Date.now() - startedAt, error: tail.slice(-400) || undefined });
         });
         return { ok: true, reason: 'ran' };
     }
+    function run(spec, ctx) {
+        if (!spec.run)
+            return { ok: false, reason: 'skipped', detail: 'no run command' };
+        return spawnOnce(spec, ctx, 0);
+    }
     function dispose() {
+        for (const timer of pendingRetries)
+            clearTimeout(timer);
+        pendingRetries.clear();
         for (const child of children)
             terminate(child);
         children.clear();

package/lib/server.d.ts

@@ -0,0 +1,32 @@
+/**
+ * /dsh-hooks/* HTTP routes for the web profile: status, execution history,
+ * and a dry-run-style test trigger. Registered only when the shared
+ * webserver service exists (web profile) — CLI/headless environments never
+ * see them. Loopback-only with JSON envelopes; POSTs require an explicit
+ * application/json content-type (CSRF hardening, same posture as
+ * dsh-aionui-panel).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HookSpec } from './config.js';
+import type { HistorySink } from './history.js';
+/** Minimal structural shape of the shared web server (dsh-host-webserver). */
+export interface WebServerLike {
+    register(spec: {
+        kind: 'prefix' | 'exact';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+    }): () => void;
+}
+/** Plugin version, read from package.json (this package ships its own). */
+export declare function pluginVersion(): string;
+/** Loopback fence: never let a LAN client reach /dsh-hooks operations. */
+export declare function isLoopbackRequest(req: IncomingMessage): boolean;
+export interface HookRoutesOptions {
+    hooks: readonly HookSpec[];
+    history: HistorySink;
+    version?: string;
+}
+/** Create the /dsh-hooks route handler (exported for tests). */
+export declare function createHookHandler(options: HookRoutesOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** Register the /dsh-hooks prefix route on the shared web server. */
+export declare function registerHookRoutes(webServer: WebServerLike, options: HookRoutesOptions): () => void;