dsh-hooks 0.2.2 → 0.4.0

package/examples/notify-webhook.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * Generic webhook notification for dsh-hooks — posts the hook context as
+ * one JSON document to any HTTP endpoint. Works with Slack incoming
+ * webhooks, Discord, Lark/DingTalk custom bots, ntfy, Bark, n8n, or any
+ * automation service that accepts a JSON POST.
+ *
+ * Reads the hook context from DSH_HOOK_* environment variables and POSTs
+ * `application/json`. Only present context fields are included, so the
+ * payload shape is stable and small.
+ *
+ * Required environment (set in the dsh process environment, NOT in config):
+ *   DSH_HOOKS_WEBHOOK_URL     target webhook URL
+ * …or pass it as the first flag: --url <url>
+ *
+ * Usage (from a dsh-hooks config):
+ *   - on: 'turn/end'
+ *     when: 'completed'
+ *     run: 'node examples/notify-webhook.mjs --url https://hooks.slack.com/services/T/B/…'
+ *   - on: 'tool/call'
+ *     run: 'node examples/notify-webhook.mjs'
+ *
+ * Optional flags:
+ *   --url <url>        webhook URL (overrides the environment variable)
+ *   --slack            post Slack-style `{ text }` instead of the full
+ *                      context document
+ *   --timeout <ms>     fetch timeout (default 10000)
+ *   -q                 quiet: suppress success output (hooks parse stdout)
+ *
+ * Zero npm dependencies: fetch is global in Node 18+.
+ * The module exports its helpers for testing; it only executes when invoked
+ * directly (node notify-webhook.mjs), not when imported.
+ */
+import { pathToFileURL } from 'node:url'
+
+/** Every DSH_HOOK_* variable this script understands, in payload order. */
+const CONTEXT_VARS = [
+  'DSH_HOOK_EVENT',
+  'DSH_HOOK_TIMESTAMP',
+  'DSH_HOOK_SESSION_ID',
+  'DSH_HOOK_SESSION_NAME',
+  'DSH_HOOK_CWD',
+  'DSH_HOOK_TURN',
+  'DSH_HOOK_STEP',
+  'DSH_HOOK_REASON',
+  'DSH_HOOK_TOOL',
+  'DSH_HOOK_CALL_ID',
+  'DSH_HOOK_TOOL_ARGS',
+  'DSH_HOOK_TOOL_ERROR',
+  'DSH_HOOK_SOURCE',
+  'DSH_HOOK_DURATION_MS',
+  'DSH_HOOK_STATUS',
+  'DSH_HOOK_ERROR',
+  'DSH_HOOK_CONTENT',
+  'DSH_HOOK_USAGE_INPUT_TOKENS',
+  'DSH_HOOK_USAGE_OUTPUT_TOKENS',
+  'DSH_HOOK_USAGE_CACHE_READ_TOKENS',
+  'DSH_HOOK_USAGE_CACHE_WRITE_TOKENS',
+  'DSH_HOOK_USAGE_REASONING_TOKENS',
+]
+
+/** Parse one context env var into a number, or undefined when absent/garbage. */
+function num(value) {
+  if (value === undefined || value === '') return undefined
+  const n = Number(value)
+  return Number.isFinite(n) ? n : undefined
+}
+
+/** Read the raw context: only the variables that are present and non-empty. */
+export function readEnv(env = process.env) {
+  const raw = {}
+  for (const name of CONTEXT_VARS) {
+    const value = env[name]
+    if (value !== undefined && value !== '') raw[name] = value
+  }
+  return raw
+}
+
+/** Group one raw env snapshot into a nested JSON payload. */
+export function buildPayload(raw) {
+  const payload = {}
+  const session = {}
+  if (raw.DSH_HOOK_SESSION_ID) session.id = raw.DSH_HOOK_SESSION_ID
+  if (raw.DSH_HOOK_SESSION_NAME) session.name = raw.DSH_HOOK_SESSION_NAME
+  if (raw.DSH_HOOK_CWD) session.cwd = raw.DSH_HOOK_CWD
+  if (Object.keys(session).length > 0) payload.session = session
+  if (raw.DSH_HOOK_EVENT) payload.event = raw.DSH_HOOK_EVENT
+  if (raw.DSH_HOOK_TIMESTAMP) payload.timestamp = raw.DSH_HOOK_TIMESTAMP
+  const turn = num(raw.DSH_HOOK_TURN)
+  const step = num(raw.DSH_HOOK_STEP)
+  const durationMs = num(raw.DSH_HOOK_DURATION_MS)
+  if (turn !== undefined) payload.turn = turn
+  if (step !== undefined) payload.step = step
+  if (durationMs !== undefined) payload.duration_ms = durationMs
+  if (raw.DSH_HOOK_REASON) payload.reason = raw.DSH_HOOK_REASON
+  if (raw.DSH_HOOK_TOOL) payload.tool = raw.DSH_HOOK_TOOL
+  if (raw.DSH_HOOK_CALL_ID) payload.call_id = raw.DSH_HOOK_CALL_ID
+  if (raw.DSH_HOOK_TOOL_ARGS) payload.tool_args = raw.DSH_HOOK_TOOL_ARGS
+  if (raw.DSH_HOOK_TOOL_ERROR) payload.tool_error = raw.DSH_HOOK_TOOL_ERROR
+  if (raw.DSH_HOOK_SOURCE) payload.source = raw.DSH_HOOK_SOURCE
+  if (raw.DSH_HOOK_STATUS) payload.status = raw.DSH_HOOK_STATUS
+  if (raw.DSH_HOOK_ERROR) payload.error = raw.DSH_HOOK_ERROR
+  if (raw.DSH_HOOK_CONTENT) payload.content = raw.DSH_HOOK_CONTENT
+  const usage = {}
+  const usageInput = num(raw.DSH_HOOK_USAGE_INPUT_TOKENS)
+  const usageOutput = num(raw.DSH_HOOK_USAGE_OUTPUT_TOKENS)
+  const usageCacheRead = num(raw.DSH_HOOK_USAGE_CACHE_READ_TOKENS)
+  const usageCacheWrite = num(raw.DSH_HOOK_USAGE_CACHE_WRITE_TOKENS)
+  const usageReasoning = num(raw.DSH_HOOK_USAGE_REASONING_TOKENS)
+  if (usageInput !== undefined) usage.input_tokens = usageInput
+  if (usageOutput !== undefined) usage.output_tokens = usageOutput
+  if (usageCacheRead !== undefined) usage.cache_read_tokens = usageCacheRead
+  if (usageCacheWrite !== undefined) usage.cache_write_tokens = usageCacheWrite
+  if (usageReasoning !== undefined) usage.reasoning_tokens = usageReasoning
+  if (Object.keys(usage).length > 0) payload.usage = usage
+  return payload
+}
+
+/** One-line summary for Slack-style `{ text }` payloads. */
+export function summarize(payload) {
+  const label = payload.session?.name || payload.session?.id || ''
+  const where = label ? ` · ${label}` : ''
+  switch (payload.event) {
+    case 'turn/end':
+      if (payload.reason === 'completed') return `✅ 任务已完成${where}（回合 #${payload.turn ?? '?'}）`
+      if (payload.error) return `❌ 任务失败${where}: ${payload.error.slice(0, 200)}`
+      return `⏸ 任务${payload.reason ? ` ${payload.reason}` : '结束'}${where}（回合 #${payload.turn ?? '?'}）`
+    case 'tool/call':
+      return `🔧 调用工具 ${payload.tool ?? ''}${where}`
+    case 'tool/result':
+      if (payload.tool_error) return `⚠️ 工具 ${payload.tool ?? ''} 失败${where}: ${payload.tool_error}`
+      return `✅ 工具 ${payload.tool ?? ''} 完成${where}`
+    case 'approval/asked':
+      return `⏳ 需要审批：工具 ${payload.tool ?? ''}${where}`
+    case 'user/message':
+      return `💬 新消息${where}${payload.content ? `：${payload.content.slice(0, 120)}` : ''}`
+    case 'session/title':
+      return `🏷 会话改名${where}: ${payload.session?.name ?? ''}`
+    case 'session/created':
+      return `✨ 会话开始${where}`
+    case 'session/disposed':
+      return `🏁 会话结束${where}`
+    default:
+      return `🔔 DSH ${payload.event ?? '事件'}${where}`
+  }
+}
+
+/** Parse the optional CLI flags. */
+export function parseArgs(args) {
+  const opts = { url: '', slack: false, timeoutMs: 10000, quiet: false }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--url') opts.url = args[++i] ?? ''
+    else if (a === '--slack') opts.slack = true
+    else if (a === '--timeout') {
+      const n = Number(args[++i])
+      if (Number.isFinite(n) && n > 0) opts.timeoutMs = n
+    } else if (a === '-q') opts.quiet = true
+  }
+  return opts
+}
+
+/** POST one JSON body to the webhook with a timeout; one retry on transport failure. */
+export async function postJson(url, body, timeoutMs = 10000) {
+  const attempt = async () => {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), timeoutMs)
+    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) {
+    // One retry for transient transport failures (webhook endpoints often
+    // drop the first request when cold).
+    try {
+      response = await attempt()
+    } catch (retryError) {
+      const cause = retryError instanceof Error ? retryError.message : String(retryError)
+      throw new Error(`webhook 请求失败（重试后仍失败）: ${cause}`)
+    }
+  }
+  if (!response.ok) throw new Error(`webhook 响应 HTTP ${response.status}`)
+}
+
+/** Full pipeline for one hook event. Exported for tests and CLI use. */
+export async function run(env = process.env, args = []) {
+  const opts = parseArgs(args)
+  const url = opts.url || env.DSH_HOOKS_WEBHOOK_URL
+  if (!url) throw new Error('缺少 webhook URL：请设置 DSH_HOOKS_WEBHOOK_URL 或传 --url <url>')
+  const raw = readEnv(env)
+  if (!raw.DSH_HOOK_EVENT) throw new Error('缺少 DSH_HOOK_EVENT（请通过 dsh-hooks 触发，不要直接运行）')
+  const payload = buildPayload(raw)
+  const body = opts.slack ? { text: summarize(payload) } : payload
+  await postJson(url, body, opts.timeoutMs)
+  return body
+}
+
+function isDirectRun() {
+  try {
+    return process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
+  } catch {
+    return false
+  }
+}
+
+if (isDirectRun()) {
+  run(process.env, process.argv.slice(2))
+    .then((body) => {
+      if (!parseArgs(process.argv.slice(2)).quiet) {
+        const text = JSON.stringify(body)
+        console.log(`已发送 webhook: ${text.length > 80 ? text.slice(0, 80) + '…' : text}`)
+      }
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.warn(`[dsh-hooks/notify-webhook] ${error instanceof Error ? error.message : String(error)}`)
+      process.exit(1)
+    })
+}

package/lib/client.js

@@ -0,0 +1,365 @@
+window.__ModuleLoader__.load({
+	id: "dsh-hooks",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let react = require("react");
+		let react_jsx_runtime = require("react/jsx-runtime");
+		//#region src/client/api.ts
+		async function getJson(path, fetchFn) {
+			try {
+				const response = await fetchFn(path, { headers: { accept: "application/json" } });
+				if (!response.ok) {
+					console.warn(`[dsh-hooks-ui] GET ${path} → HTTP ${response.status}`);
+					return null;
+				}
+				const envelope = await response.json();
+				if (!envelope.ok) {
+					console.warn(`[dsh-hooks-ui] GET ${path} → ${envelope.error?.message ?? "unknown error"}`);
+					return null;
+				}
+				return envelope.value ?? null;
+			} catch (error) {
+				console.warn(`[dsh-hooks-ui] GET ${path} failed: ${error instanceof Error ? error.message : String(error)}`);
+				return null;
+			}
+		}
+		async function fetchStatus(fetchFn = fetch) {
+			return getJson("/dsh-hooks/status", fetchFn);
+		}
+		async function fetchHistory(n = 50, fetchFn = fetch) {
+			return getJson(`/dsh-hooks/history?n=${Math.max(1, Math.min(500, Math.floor(n)))}`, fetchFn);
+		}
+		async function postTest(body, fetchFn = fetch) {
+			try {
+				const response = await fetchFn("/dsh-hooks/test", {
+					method: "POST",
+					headers: {
+						"content-type": "application/json",
+						accept: "application/json"
+					},
+					body: JSON.stringify(body)
+				});
+				const envelope = await response.json();
+				if (!response.ok || !envelope.ok) {
+					console.warn(`[dsh-hooks-ui] POST /dsh-hooks/test → ${envelope.error?.message ?? `HTTP ${response.status}`}`);
+					return null;
+				}
+				return envelope.value ?? null;
+			} catch (error) {
+				console.warn(`[dsh-hooks-ui] POST /dsh-hooks/test failed: ${error instanceof Error ? error.message : String(error)}`);
+				return null;
+			}
+		}
+		/** `HH:MM:SS` local time for a timestamp. */
+		function formatTime(ts) {
+			const date = new Date(ts);
+			const p = (value) => String(value).padStart(2, "0");
+			return `${p(date.getHours())}:${p(date.getMinutes())}:${p(date.getSeconds())}`;
+		}
+		/** Chinese outcome labels. */
+		const OUTCOME_LABELS = {
+			spawned: "已启动",
+			"spawn-failed": "启动失败",
+			timeout: "超时",
+			"exit-0": "成功",
+			"exit-nonzero": "失败",
+			sent: "已发送",
+			"send-failed": "发送失败"
+		};
+		function outcomeLabel(outcome) {
+			return OUTCOME_LABELS[outcome] ?? outcome;
+		}
+		const OUTCOME_TONES = {
+			"exit-0": "ok",
+			sent: "ok",
+			"exit-nonzero": "bad",
+			"spawn-failed": "bad",
+			"send-failed": "bad",
+			timeout: "warn",
+			spawned: "neutral"
+		};
+		function outcomeTone(outcome) {
+			return OUTCOME_TONES[outcome] ?? "neutral";
+		}
+		//#endregion
+		//#region src/client/settings-card.tsx
+		/**
+		* The dsh-hooks settings card: status badges, execution-history timeline,
+		* and a manual event tester — all served by the core plugin's /dsh-hooks/*
+		* routes. Degrades gracefully: fetch failures show an inline notice, never
+		* a crash. Registered into the shell's `web-ui.plugin.item` slot.
+		*/
+		const EVENTS = [
+			"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"
+		];
+		/** Settings-slot component; the shell's slot machinery supplies the props. */
+		function HooksSettingsCard(_props) {
+			const [status, setStatus] = (0, react.useState)(null);
+			const [history, setHistory] = (0, react.useState)(null);
+			const [loadError, setLoadError] = (0, react.useState)(false);
+			const [event, setEvent] = (0, react.useState)("turn/end");
+			const [reason, setReason] = (0, react.useState)("completed");
+			const [tool, setTool] = (0, react.useState)("");
+			const [testResult, setTestResult] = (0, react.useState)(null);
+			const refresh = (0, react.useCallback)(async () => {
+				const [statusInfo, records] = await Promise.all([fetchStatus(), fetchHistory(30)]);
+				setStatus(statusInfo);
+				setHistory(records);
+				setLoadError(statusInfo === null && records === null);
+			}, []);
+			(0, react.useEffect)(() => {
+				refresh();
+				const timer = setInterval(() => void refresh(), 5e3);
+				return () => clearInterval(timer);
+			}, [refresh]);
+			const runTest = async (execute) => {
+				const result = await postTest({
+					event,
+					reason: event === "turn/end" && reason !== "" ? reason : void 0,
+					tool: tool !== "" ? tool : void 0,
+					execute
+				});
+				setTestResult(result);
+				if (execute) refresh();
+			};
+			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: "dh-card",
+				children: [
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "dh-card-head",
+						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "dh-card-title",
+							children: "dsh-hooks"
+						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							className: "dh-badges",
+							children: status !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+									className: "dh-badge",
+									children: ["v", status.version]
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+									className: "dh-badge",
+									children: [status.hookCount, " hooks"]
+								}),
+								/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+									className: "dh-badge",
+									children: [status.historyCount, " 记录"]
+								})
+							] })
+						})]
+					}),
+					loadError && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "dh-error-banner",
+						children: "无法访问 /dsh-hooks/* 路由：请确认 dsh-hooks 核心插件已安装且 dsh web 已重启。"
+					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
+						className: "dh-section-title",
+						children: "执行历史（最近 30 条）"
+					}), history === null || history.length === 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "dh-empty",
+						children: history === null ? "加载中…" : "暂无记录"
+					}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+						className: "dh-timeline",
+						children: [...history].reverse().map((record, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+							className: "dh-record",
+							children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: "dh-record-main",
+								children: [
+									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+										className: "dh-record-top",
+										children: [
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: "dh-record-time",
+												children: formatTime(record.ts)
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: "dh-record-event",
+												children: record.event
+											}),
+											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+												className: `dh-outcome ${outcomeClass(record.outcome)}`,
+												children: outcomeLabel(record.outcome)
+											})
+										]
+									}),
+									/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										className: "dh-record-command",
+										title: record.command,
+										children: record.command
+									}),
+									record.error !== void 0 && record.error !== "" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+										className: "dh-record-error",
+										children: record.error.slice(0, 200)
+									})
+								]
+							})
+						}, `${record.ts}-${index}`))
+					})] }),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("h3", {
+						className: "dh-section-title",
+						children: "手动测试"
+					}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+						className: "dh-test-form",
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: "dh-test-row",
+								children: [
+									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+										className: "dh-field",
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+											className: "dh-field-label",
+											children: "事件"
+										}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("select", {
+											className: "dh-select",
+											value: event,
+											onChange: (e) => setEvent(e.target.value),
+											children: EVENTS.map((name) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("option", {
+												value: name,
+												children: name
+											}, name))
+										})]
+									}),
+									event === "turn/end" && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+										className: "dh-field",
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+											className: "dh-field-label",
+											children: "reason"
+										}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+											className: "dh-input",
+											value: reason,
+											onChange: (e) => setReason(e.target.value),
+											placeholder: "completed"
+										})]
+									}),
+									/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
+										className: "dh-field",
+										children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+											className: "dh-field-label",
+											children: "tool（可选）"
+										}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+											className: "dh-input",
+											value: tool,
+											onChange: (e) => setTool(e.target.value),
+											placeholder: "pwsh"
+										})]
+									})
+								]
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: "dh-buttons",
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									className: "dh-button",
+									onClick: () => void runTest(false),
+									children: "模拟（看匹配）"
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									className: "dh-button dh-button-primary",
+									onClick: () => void runTest(true),
+									children: "执行（真实触发）"
+								})]
+							}),
+							testResult !== null && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: "dh-test-results",
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									className: "dh-test-line",
+									children: [
+										testResult.event,
+										"：",
+										testResult.matched,
+										"/",
+										testResult.total,
+										" 个 hook 触发",
+										testResult.executed ? "（已执行）" : ""
+									]
+								}, "head"), testResult.lines.map((line) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+									className: `dh-test-line ${line.matched ? "dh-test-line-match" : "dh-test-line-skip"}`,
+									children: [
+										line.matched ? "✅" : "⏭",
+										" [",
+										line.index,
+										"] ",
+										line.summary,
+										!line.matched && line.why !== "" ? ` —— ${line.why}` : ""
+									]
+								}, line.index))]
+							})
+						]
+					})] })
+				]
+			});
+		}
+		function outcomeClass(outcome) {
+			switch (outcomeTone(outcome)) {
+				case "ok": return "dh-outcome-ok";
+				case "bad": return "dh-outcome-bad";
+				case "warn": return "dh-outcome-warn";
+				default: return "dh-outcome-neutral";
+			}
+		}
+		//#endregion
+		//#region src/client/settings-card.module.css?inline
+		var settings_card_module_default = ":root {\n  --dsh-hooks-border: #80849038;\n  --dsh-hooks-muted: #767c85;\n  --dsh-hooks-accent: #4d8df7;\n  --dsh-hooks-ok: #3fb56b;\n  --dsh-hooks-bad: #e5534b;\n  --dsh-hooks-warn: #d9a13c;\n}\n\n.dh-card {\n  flex-direction: column;\n  gap: 14px;\n  padding: 12px 4px;\n  font-size: 13px;\n  line-height: 1.5;\n  display: flex;\n}\n\n.dh-card-head {\n  align-items: center;\n  gap: 10px;\n  display: flex;\n}\n\n.dh-card-title {\n  font-size: 14px;\n  font-weight: 600;\n}\n\n.dh-badges {\n  gap: 6px;\n  display: flex;\n}\n\n.dh-badge {\n  color: var(--dsh-hooks-muted);\n  white-space: nowrap;\n  background: #80849029;\n  border-radius: 9px;\n  padding: 1px 7px;\n  font-size: 11px;\n}\n\n.dh-section-title {\n  color: var(--dsh-hooks-muted);\n  text-transform: uppercase;\n  letter-spacing: .04em;\n  margin: 0 0 8px;\n  font-size: 12px;\n  font-weight: 600;\n}\n\n.dh-timeline {\n  flex-direction: column;\n  gap: 6px;\n  display: flex;\n}\n\n.dh-record {\n  border: 1px solid var(--dsh-hooks-border);\n  border-radius: 6px;\n  gap: 8px;\n  padding: 7px 9px;\n  display: flex;\n}\n\n.dh-record-main {\n  flex: 1;\n  min-width: 0;\n}\n\n.dh-record-top {\n  align-items: baseline;\n  gap: 6px;\n  display: flex;\n}\n\n.dh-record-time {\n  color: var(--dsh-hooks-muted);\n  white-space: nowrap;\n  font-size: 11px;\n}\n\n.dh-record-event {\n  white-space: nowrap;\n  text-overflow: ellipsis;\n  font-weight: 600;\n  overflow: hidden;\n}\n\n.dh-record-command {\n  color: var(--dsh-hooks-muted);\n  white-space: nowrap;\n  text-overflow: ellipsis;\n  text-align: left;\n  direction: rtl;\n  font-size: 12px;\n  overflow: hidden;\n}\n\n.dh-outcome {\n  white-space: nowrap;\n  border-radius: 9px;\n  align-self: flex-start;\n  padding: 1px 7px;\n  font-size: 11px;\n}\n\n.dh-outcome-ok {\n  color: var(--dsh-hooks-ok);\n  background: #3fb56b29;\n}\n\n.dh-outcome-bad {\n  color: var(--dsh-hooks-bad);\n  background: #e5534b29;\n}\n\n.dh-outcome-warn {\n  color: var(--dsh-hooks-warn);\n  background: #d9a13c29;\n}\n\n.dh-outcome-neutral {\n  color: var(--dsh-hooks-muted);\n  background: #80849029;\n}\n\n.dh-record-error {\n  color: var(--dsh-hooks-bad);\n  white-space: pre-wrap;\n  word-break: break-all;\n  margin-top: 4px;\n  font-size: 11px;\n}\n\n.dh-empty {\n  color: var(--dsh-hooks-muted);\n  padding: 6px 2px;\n  font-size: 12px;\n}\n\n.dh-test-form {\n  flex-direction: column;\n  gap: 8px;\n  display: flex;\n}\n\n.dh-test-row {\n  gap: 8px;\n  display: flex;\n}\n\n.dh-field {\n  flex-direction: column;\n  flex: 1;\n  gap: 3px;\n  min-width: 0;\n  display: flex;\n}\n\n.dh-field-label {\n  color: var(--dsh-hooks-muted);\n  font-size: 11px;\n}\n\n.dh-input, .dh-select {\n  border: 1px solid var(--dsh-hooks-border);\n  color: inherit;\n  box-sizing: border-box;\n  background: #8084901f;\n  border-radius: 5px;\n  outline: none;\n  width: 100%;\n  padding: 5px 8px;\n  font-size: 12px;\n}\n\n.dh-input:focus, .dh-select:focus {\n  border-color: var(--dsh-hooks-accent);\n}\n\n.dh-buttons {\n  gap: 8px;\n  display: flex;\n}\n\n.dh-button {\n  border: 1px solid var(--dsh-hooks-border);\n  color: inherit;\n  cursor: pointer;\n  background: #8084901f;\n  border-radius: 5px;\n  padding: 5px 12px;\n  font-size: 12px;\n}\n\n.dh-button:hover {\n  background: #80849038;\n}\n\n.dh-button-primary {\n  background: var(--dsh-hooks-accent);\n  border-color: var(--dsh-hooks-accent);\n  color: #fff;\n}\n\n.dh-button-primary:hover {\n  background: #3c7de8;\n}\n\n.dh-test-results {\n  flex-direction: column;\n  gap: 4px;\n  display: flex;\n}\n\n.dh-test-line {\n  word-break: break-all;\n  border-radius: 5px;\n  padding: 4px 8px;\n  font-size: 12px;\n}\n\n.dh-test-line-match {\n  color: var(--dsh-hooks-ok);\n  background: #3fb56b24;\n}\n\n.dh-test-line-skip {\n  color: var(--dsh-hooks-muted);\n  background: #8084901a;\n}\n\n.dh-error-banner {\n  color: var(--dsh-hooks-bad);\n  background: #e5534b1f;\n  border: 1px solid #e5534b66;\n  border-radius: 6px;\n  padding: 8px 10px;\n  font-size: 12px;\n}\n";
+		//#endregion
+		//#region src/client/index.ts
+		const name = "dsh-hooks";
+		/** Required services: the slot registry must be up before this plugin applies. */
+		const inject = ["slots"];
+		const STYLE_ID = "dsh-hooks-ui-style";
+		/** Single-application guard: first apply wins; later calls become no-ops. */
+		let applied = false;
+		function apply(ctx) {
+			if (typeof document === "undefined") return;
+			if (applied) return;
+			applied = true;
+			injectCardStyle();
+			try {
+				ctx.slots.inject("settings.section", () => {
+					const unregister = ctx.slots.register({
+						name: "settings.section",
+						id: "dsh-hooks",
+						order: 100,
+						label: "Hooks"
+					}, HooksSettingsCard);
+					return () => {
+						unregister();
+					};
+				});
+			} catch (error) {
+				console.error("[dsh-hooks-ui] slot registration failed:", error);
+			}
+			ctx.effect(() => () => {
+				applied = false;
+				document.getElementById(STYLE_ID)?.remove();
+			}, "dsh-hooks-ui: card");
+		}
+		/** Inject the card stylesheet once (bundled as a string via .css?inline). */
+		function injectCardStyle() {
+			if (document.getElementById(STYLE_ID) !== null) return;
+			const style = document.createElement("style");
+			style.id = STYLE_ID;
+			style.textContent = settings_card_module_default;
+			document.head.appendChild(style);
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.name = name;
+		return module.exports;
+	}
+});

package/lib/config.d.ts

@@ -1,10 +1,23 @@
 /** Hookable event kinds. v1 is emit-only: no waterfall/interception events. */
-export declare const HOOK_EVENTS: readonly ["turn/start", "turn/end", "approval/asked", "agent/created", "agent/disposed", "agent/error", "agent/status"];
+export declare const HOOK_EVENTS: readonly ['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'];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** `turn/end` reason kinds (from @deepseek-ai/dsh-session TurnEndReasonMap). */
-export declare const TURN_END_REASONS: readonly ["completed", "error", "aborted", "blocked", "max-tokens", "interrupted"];
+export declare const TURN_END_REASONS: readonly ['completed', 'error', 'aborted', 'blocked', 'max-tokens', 'interrupted'];
 export type TurnEndReasonKind = (typeof TURN_END_REASONS)[number];
-/** One declared hook: a matching event runs `run` through the platform shell. */
+/**
+ * Built-in notification: send the hook context through a channel declared
+ * in config, no external script required. Mutually exclusive with `run` —
+ * a hook declares exactly one of the two.
+ */
+export interface NotifySpec {
+    /** Channel to send through. */
+    channel: 'webhook' | 'desktop';
+    /** webhook: the target URL (falls back to the `DSH_HOOKS_WEBHOOK_URL` env var). */
+    url?: string;
+    /** webhook: post a Slack-style `{ text }` one-line summary instead of the full context document. */
+    slack?: boolean;
+}
+/** One declared hook: a matching event runs `run` (or sends `notify`). */
 export interface HookSpec {
     /** Event that triggers the hook. */
     on: HookEvent;
@@ -13,13 +26,48 @@ export interface HookSpec {
      * (`completed`, `error`, …). Ignored for other events.
      */
     when?: TurnEndReasonKind;
-    /** Command to spawn through the platform shell. */
-    run: string;
+    /**
+     * Optional field → regex filters: every declared regex must match the
+     * context's field value for the hook to run. Fields are `HookContext`
+     * keys (`tool`, `sessionName`, `sessionId`, `error`, `source`, `cwd`,
+     * `content`, …); a field absent from the context never matches.
+     */
+    match?: Record<string, RegExp>;
+    /**
+     * Command to spawn through the platform shell. Exactly one of `run` and
+     * `notify` must be declared.
+     */
+    run?: string;
+    /** Built-in notification channel. Exactly one of `run` and `notify` must be declared. */
+    notify?: NotifySpec | null;
+    /**
+     * How the context reaches the command. `env` (default) passes the
+     * `DSH_HOOK_*` variables only; `stdin` additionally writes the full
+     * context as one JSON document to the command's stdin.
+     */
+    input?: 'env' | 'stdin';
     /** Per-hook timeout in milliseconds. Defaults to 10000. */
     timeoutMs?: number;
+    /**
+     * Retry count for non-zero exit codes (default 0: fire-and-forget,
+     * never retried). Spawn failures and timeouts are never retried.
+     */
+    retries?: number;
+    /** Base delay between retries in milliseconds; doubles per attempt. Defaults to 500. */
+    retryDelayMs?: number;
+}
+/** Execution-history settings: in-memory ring buffer + optional JSONL log. */
+export interface HistoryConfig {
+    /** Persist records to disk. Defaults to true. */
+    enabled?: boolean;
+    /** JSONL file path. Defaults to ~/.dsh/dsh-hooks/history.jsonl (0600). */
+    path?: string;
+    /** In-memory ring buffer size. Defaults to 500. */
+    max?: number;
 }
 export interface Config {
     hooks?: HookSpec[];
+    history?: HistoryConfig | null;
 }
 export declare const Config: {
     (data?: Config | null): Config;