dsh-hooks 0.2.1

package/examples/notify-feishu.mjs

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+/**
+ * Feishu card notification for dsh-hooks — Card JSON 2.0 with a single
+ * markdown body component: colored header, time/dir/session meta lines, and
+ * the turn content rendered with full markdown (headings, tables, images).
+ * Truncation lengths follow the feishu-notify conventions.
+ *
+ * Reads the hook context from DSH_HOOK_* environment variables and posts an
+ * interactive card through the Feishu app API (im/v1/messages). Works without
+ * a group custom bot — any user/chat the app bot can reach is a valid target.
+ *
+ * Required environment (set in the dsh process environment, NOT in config):
+ *   DSH_HOOKS_FEISHU_APP_ID      Feishu open platform app id (cli_...)
+ *   DSH_HOOKS_FEISHU_APP_SECRET  Feishu open platform app secret
+ *   DSH_HOOKS_FEISHU_TO          Target open_id / chat_id to notify
+ *
+ * Usage (from a dsh-hooks config):
+ *   - on: 'turn/end'
+ *     when: 'completed'
+ *     run: 'node examples/notify-feishu.mjs'
+ *   - on: 'approval/asked'
+ *     run: 'node examples/notify-feishu.mjs --approval'
+ *
+ * Optional flags:
+ *   --text                 send plain text instead of a card
+ *   --header <color>       card header color (default depends on event)
+ *   --title <title>        card title (default depends on event)
+ *   --note <note>          extra meta line at the bottom
+ *   -q                     quiet: suppress success output (hooks parse stdout)
+ *
+ * Card body: `turn/end` shows the turn's final assistant text directly
+ * (failure detail first when the turn errored); other events carry their
+ * own one-line summaries.
+ *
+ * Zero npm dependencies: fetch is global in Node 18+.
+ * The module exports its helpers for testing; it only executes when invoked
+ * directly (node notify-feishu.mjs), not when imported.
+ */
+import { pathToFileURL } from 'node:url'
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Default config file written by `dsh-hooks feishu-setup` (feishu-notify parity). */
+export const DEFAULT_CONFIG_PATH = join(homedir(), '.dsh', 'dsh-hooks', 'feishu-config.json')
+
+/** Common Feishu API error codes with Chinese hints (feishu-notify parity). */
+const ERROR_HINTS = {
+  99991663: '应用缺少发送消息权限，请在开放平台「权限管理」开通 im:message:send_as_bot（以应用身份发消息）并发布新版本',
+  99991667: '目标用户不在应用的可用范围内，请在管理后台「应用 → 可用范围」中添加该用户',
+  99991668: '应用未发布或被停用，请在开放平台发布应用新版本',
+  99991669: '应用凭证无效，请检查 app_id / app_secret',
+  10003: 'app_secret 不正确',
+  230002: '机器人不在该群聊中，请先把机器人拉入群聊',
+}
+
+/** Card header colors (feishu-notify parity). */
+const CARD_HEADERS = new Set([
+  'blue', 'wathet', 'turquoise', 'green', 'yellow', 'orange',
+  'red', 'carmine', 'violet', 'purple', 'indigo', 'grey',
+])
+
+let tokenCache = new Map() // appId -> { value, expireAt }; tenant tokens are per-app
+
+export function readEnv(env = process.env) {
+  return {
+    appId: env.DSH_HOOKS_FEISHU_APP_ID,
+    appSecret: env.DSH_HOOKS_FEISHU_APP_SECRET,
+    to: env.DSH_HOOKS_FEISHU_TO,
+    event: env.DSH_HOOK_EVENT ?? '',
+    sessionId: env.DSH_HOOK_SESSION_ID ?? '',
+    sessionName: env.DSH_HOOK_SESSION_NAME ?? '',
+    cwd: env.DSH_HOOK_CWD ?? '',
+    turn: env.DSH_HOOK_TURN ?? '',
+    reason: env.DSH_HOOK_REASON ?? '',
+    tool: env.DSH_HOOK_TOOL ?? '',
+    callId: env.DSH_HOOK_CALL_ID ?? '',
+    durationMs: env.DSH_HOOK_DURATION_MS ?? '',
+    status: env.DSH_HOOK_STATUS ?? '',
+    error: env.DSH_HOOK_ERROR ?? '',
+    content: env.DSH_HOOK_CONTENT ?? '',
+    timestamp: env.DSH_HOOK_TIMESTAMP ?? '',
+  }
+}
+
+/**
+ * Load credentials from the local feishu-config.json (written by
+ * `dsh-hooks feishu-setup`) and fill any missing credential fields —
+ * environment variables always win. Also picks up `result_max_chars`,
+ * the content truncation length (default 300); invalid values fall back.
+ * Returns a merged context.
+ */
+export function mergeConfig(ctx, configPath = DEFAULT_CONFIG_PATH) {
+  if (!existsSync(configPath)) return ctx
+  let file
+  try {
+    file = JSON.parse(readFileSync(configPath, 'utf8'))
+  } catch {
+    return ctx
+  }
+  if (typeof file !== 'object' || file === null) return ctx
+  const fromFile =
+    Number.isFinite(file.result_max_chars) && file.result_max_chars > 0
+      ? Math.floor(file.result_max_chars)
+      : undefined
+  return {
+    ...ctx,
+    appId: ctx.appId || file.app_id || '',
+    appSecret: ctx.appSecret || file.app_secret || '',
+    to: ctx.to || file.target_id || '',
+    // target_type=chat_id targets need a different receive_id_type; the
+    // default pipeline posts to open_id, so a chat_id target must be sent
+    // with receive_id_type=chat_id. readTargetType surfaces that choice.
+    receiveIdType: ctx.to ? 'open_id' : file.target_type === 'chat_id' ? 'chat_id' : 'open_id',
+    resultMaxChars: ctx.resultMaxChars ?? fromFile,
+  }
+}
+
+/**
+ * Clean and truncate text for the card body: normalize newlines, strip
+ * trailing whitespace, collapse blank lines, and cut at a line boundary
+ * near the limit with an ellipsis (feishu-notify truncateText parity).
+ */
+export function truncateText(text, max) {
+  const t = String(text)
+    .replace(/\r\n/g, '\n')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+  if (!t) return null
+  if (t.length <= max) return t
+  const cut = t.slice(0, max)
+  const lastNl = cut.lastIndexOf('\n')
+  return (lastNl > max / 2 ? cut.slice(0, lastNl) : cut) + '…'
+}
+
+/** `2026/8/13 00:28:12` style timestamps (feishu-notify parity). */
+export function fmtTime(d) {
+  const p = (n) => String(n).padStart(2, '0')
+  return `${d.getFullYear()}/${d.getMonth() + 1}/${d.getDate()} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
+}
+
+export function formatDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return String(ms)
+  const seconds = Math.round(ms / 1000)
+  if (seconds < 60) return `${seconds} 秒`
+  const minutes = Math.floor(seconds / 60)
+  const rest = seconds % 60
+  return rest === 0 ? `${minutes} 分钟` : `${minutes} 分 ${rest} 秒`
+}
+
+/** Per-event card presentation (feishu-notify style: colored header + title). */
+export function eventPresentation(ctx) {
+  const { event, reason } = ctx
+  switch (event) {
+    case 'turn/end':
+      if (reason === 'completed') return { header: 'green', title: '✅ 任务已完成' }
+      if (reason === 'aborted' || reason === 'interrupted' || reason === 'blocked') {
+        return { header: 'orange', title: '⏸ 任务中断' }
+      }
+      return { header: 'red', title: '❌ 任务失败' }
+    case 'approval/asked':
+      return { header: 'orange', title: '⏳ 需要审批' }
+    case 'agent/error':
+      return { header: 'red', title: '⚠️ Agent 出错' }
+    case 'agent/status':
+      return { header: 'blue', title: '🤖 Agent 状态' }
+    case 'turn/start':
+      return { header: 'blue', title: '▶️ 任务开始' }
+    case 'agent/created':
+      return { header: 'green', title: '✨ 会话已创建' }
+    case 'agent/disposed':
+      return { header: 'grey', title: '🏁 会话已结束' }
+    default:
+      return { header: 'blue', title: '🔔 DSH 通知' }
+  }
+}
+
+/** Body text for the event, respecting feishu-notify truncation lengths. */
+export function buildBody(ctx) {
+  const { event, reason, tool, error, status, sessionId, content, turn } = ctx
+  const resultMaxChars = ctx.resultMaxChars ?? 300
+  const lines = []
+  if (event === 'turn/end') {
+    // The turn's own words are the story: show the final assistant text
+    // directly, with the failure detail first when the turn errored.
+    if (error) lines.push(`详情：${truncateText(error, 200) ?? error}`)
+    if (content) lines.push(truncateText(content, resultMaxChars) ?? content)
+  } else if (event === 'approval/asked') {
+    lines.push('有一个操作等你批准')
+    if (tool) lines.push(`工具：${tool}`)
+    if (reason) lines.push(`原因：${truncateText(reason, 200) ?? reason}`)
+  } else if (event === 'agent/error') {
+    lines.push('Agent 循环报告了错误')
+    if (error) lines.push(`详情：${truncateText(error, 200) ?? error}`)
+  } else if (event === 'agent/status') {
+    lines.push(`状态：${status || '未知'}`)
+  } else if (event === 'turn/start') {
+    lines.push(`开始回合：#${turn ?? ''}`)
+  } else {
+    if (sessionId) lines.push(`会话：${sessionId}`)
+  }
+  const body = lines.join('\n')
+  // Overall body cap: the truncated 内容/详情 lines stay intact
+  // (feishu-notify caps the result text itself, not the whole card).
+  return truncateText(body, 1200) ?? body
+}
+
+/**
+ * Card JSON 2.0: a single `markdown` body component carries the meta lines
+ * plus an hr-separated body, so the turn's content renders with full
+ * markdown (headings, tables, images, code blocks). The colored header
+ * template is preserved.
+ */
+export function buildCard(ctx, { header, title, note, body, now = new Date() } = {}) {
+  const metaLines = [`🕐 ${fmtTime(now)}`]
+  if (ctx.cwd) metaLines.push(`📁 ${truncateText(ctx.cwd, 200) ?? ctx.cwd}`)
+  if (ctx.sessionName || ctx.sessionId) {
+    metaLines.push(`🗒 会话 ${truncateText(ctx.sessionName || ctx.sessionId, 80) ?? (ctx.sessionName || ctx.sessionId)}`)
+  }
+  if (note) metaLines.push(`📝 ${note}`)
+  // CommonMark: two trailing spaces make a hard line break, so the meta
+  // lines stack compactly instead of collapsing into one line. The blank
+  // line before `---` keeps it a thematic break — directly after text it
+  // would be parsed as a setext heading underline and disappear.
+  const meta = metaLines.join('  \n')
+  const content = body ? `${meta}\n\n---\n\n${body}` : meta
+  return {
+    schema: '2.0',
+    header: { template: header, title: { tag: 'plain_text', content: title } },
+    body: { elements: [{ tag: 'markdown', content }] },
+  }
+}
+
+/**
+ * Read one Feishu API response body. A non-2xx status fails first (surfacing
+ * the API's own message when it answered JSON); a 2xx body that is not JSON
+ * fails with a parse error instead of a confusing TypeError.
+ */
+async function readApiBody(response) {
+  if (!response.ok) {
+    let apiMsg = ''
+    try {
+      const body = await response.json()
+      if (body && typeof body.msg === 'string' && body.msg) apiMsg = ` msg=${body.msg}`
+    } catch {
+      // Non-JSON error page (proxy/HTML) — the status alone is the message.
+    }
+    throw new Error(`飞书接口 HTTP ${response.status}${apiMsg}`)
+  }
+  try {
+    return await response.json()
+  } catch {
+    throw new Error('飞书接口返回了无法解析的响应')
+  }
+}
+
+/** POST to the Feishu API with network-failure translation. */
+async function postApi(url, init) {
+  let response
+  try {
+    response = await fetch(url, init)
+  } catch (error) {
+    throw new Error(`飞书接口请求失败: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  return readApiBody(response)
+}
+
+export async function getToken(appId, appSecret, now = Date.now()) {
+  const cached = tokenCache.get(appId)
+  if (cached && now < cached.expireAt) return cached.value
+  const body = await postApi('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ app_id: appId, app_secret: appSecret }),
+  })
+  if (body.code !== 0) {
+    const hint = ERROR_HINTS[body.code]
+    throw new Error(`飞书接口错误 code=${body.code} msg=${body.msg}${hint ? `\n  → ${hint}` : ''}`)
+  }
+  const entry = {
+    value: body.tenant_access_token,
+    expireAt: now + (body.expire - 300) * 1000, // 提前 5 分钟过期
+  }
+  tokenCache.set(appId, entry)
+  return entry.value
+}
+
+export async function sendCard(token, to, card, receiveIdType = 'open_id') {
+  const body = await postApi(`https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=${encodeURIComponent(receiveIdType)}`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({
+      receive_id: to,
+      msg_type: 'interactive',
+      content: JSON.stringify(card),
+    }),
+  })
+  if (body.code !== 0) {
+    const hint = ERROR_HINTS[body.code]
+    throw new Error(`飞书接口错误 code=${body.code} msg=${body.msg}${hint ? `\n  → ${hint}` : ''}`)
+  }
+}
+
+export async function sendText(token, to, text, receiveIdType = 'open_id') {
+  const body = await postApi(`https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=${encodeURIComponent(receiveIdType)}`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      authorization: `Bearer ${token}`,
+    },
+    body: JSON.stringify({
+      receive_id: to,
+      msg_type: 'text',
+      content: JSON.stringify({ text }),
+    }),
+  })
+  if (body.code !== 0) {
+    const hint = ERROR_HINTS[body.code]
+    throw new Error(`飞书接口错误 code=${body.code} msg=${body.msg}${hint ? `\n  → ${hint}` : ''}`)
+  }
+}
+
+/** Parse the optional CLI flags; positional args join into a body override. */
+export function parseArgs(args) {
+  const opts = { textMode: false, header: '', title: '', note: '', quiet: false, bodyParts: [] }
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--text') opts.textMode = true
+    else if (a === '--header') opts.header = args[++i]
+    else if (a === '--title') opts.title = args[++i]
+    else if (a === '--note') opts.note = args[++i]
+    else if (a === '--approval') { /* approval events already build their own body */ }
+    else if (a === '-q') opts.quiet = true
+    else opts.bodyParts.push(a)
+  }
+  opts.body = opts.bodyParts.join(' ').trim()
+  return opts
+}
+
+/** Full pipeline for one hook event. Exported for tests and CLI use. */
+export async function run(ctx, args = [], configPath = DEFAULT_CONFIG_PATH) {
+  const merged = mergeConfig(ctx, configPath)
+  if (!merged.appId || !merged.appSecret) throw new Error('缺少 DSH_HOOKS_FEISHU_APP_ID / DSH_HOOKS_FEISHU_APP_SECRET')
+  if (!merged.to) throw new Error('缺少 DSH_HOOKS_FEISHU_TO（接收者 open_id 或 chat_id）')
+  if (!merged.event) throw new Error('缺少 DSH_HOOK_EVENT（请通过 dsh-hooks 触发，不要直接运行）')
+  const opts = parseArgs(args)
+  const presentation = eventPresentation(merged)
+  const header = opts.header || presentation.header
+  const title = opts.title || presentation.title
+  if (!CARD_HEADERS.has(header)) {
+    throw new Error(`无效的卡片配色: ${header}，可选: ${[...CARD_HEADERS].join(', ')}`)
+  }
+  const token = await getToken(merged.appId, merged.appSecret)
+  const receiveIdType = merged.receiveIdType ?? 'open_id'
+  if (opts.textMode) {
+    const text = opts.body || buildBody(merged)
+    await sendText(token, merged.to, text, receiveIdType)
+    return { kind: 'text', text }
+  }
+  const card = buildCard(merged, {
+    header,
+    title,
+    note: opts.note || undefined,
+    body: opts.body || buildBody(merged),
+  })
+  await sendCard(token, merged.to, card, receiveIdType)
+  return { kind: 'card', card }
+}
+
+function isDirectRun() {
+  try {
+    return process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href
+  } catch {
+    return false
+  }
+}
+
+if (isDirectRun()) {
+  run(readEnv(), process.argv.slice(2))
+    .then((result) => {
+      if (!parseArgs(process.argv.slice(2)).quiet) {
+        if (result.kind === 'card') console.log(`已发送卡片: ${result.card.header.title.content}`)
+        else console.log(`已发送文本: ${result.text.length > 50 ? result.text.slice(0, 50) + '…' : result.text}`)
+      }
+      process.exit(0)
+    })
+    .catch((error) => {
+      console.warn(`[dsh-hooks/notify-feishu] ${error instanceof Error ? error.message : String(error)}`)
+      process.exit(1)
+    })
+}

package/lib/config.d.ts

@@ -0,0 +1,29 @@
+/** 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 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 type TurnEndReasonKind = (typeof TURN_END_REASONS)[number];
+/** One declared hook: a matching event runs `run` through the platform shell. */
+export interface HookSpec {
+    /** Event that triggers the hook. */
+    on: HookEvent;
+    /**
+     * Optional filter. For `turn/end` it matches the reason kind
+     * (`completed`, `error`, …). Ignored for other events.
+     */
+    when?: TurnEndReasonKind;
+    /** Command to spawn through the platform shell. */
+    run: string;
+    /** Per-hook timeout in milliseconds. Defaults to 10000. */
+    timeoutMs?: number;
+}
+export interface Config {
+    hooks?: HookSpec[];
+}
+export declare const Config: {
+    (data?: Config | null): Config;
+    meta: {
+        description?: string | Record<string, string>;
+    };
+};

package/lib/config.js

@@ -0,0 +1,34 @@
+import Schema from '@deepseek-ai/schemastery';
+/** Hookable event kinds. v1 is emit-only: no waterfall/interception events. */
+export const HOOK_EVENTS = [
+    'turn/start',
+    'turn/end',
+    'approval/asked',
+    'agent/created',
+    'agent/disposed',
+    'agent/error',
+    'agent/status',
+];
+/** `turn/end` reason kinds (from @deepseek-ai/dsh-session TurnEndReasonMap). */
+export const TURN_END_REASONS = [
+    'completed',
+    'error',
+    'aborted',
+    'blocked',
+    'max-tokens',
+    'interrupted',
+];
+// Explicit structural annotation: the inferred Schema type names the
+// cosmokit transitive dependency, which is not portable across pnpm
+// installations. Annotating with the schemastery callable shape keeps the
+// declaration self-contained.
+export const Config = Schema.object({
+    hooks: Schema.array(Schema.object({
+        on: Schema.union([...HOOK_EVENTS]).description('触发事件：turn/start | turn/end | approval/asked | agent/created | agent/disposed | agent/error | agent/status'),
+        when: Schema.union([...TURN_END_REASONS]).description('可选过滤：对 turn/end 匹配结束原因（completed/error/aborted/blocked/max-tokens/interrupted）；其他事件忽略该字段'),
+        run: Schema.string().required().description('触发时通过系统 shell 执行的命令'),
+        timeoutMs: Schema.number().default(10000).description('单次执行超时（毫秒）'),
+    }).description('一个事件 → 命令的 hook 声明'))
+        .default([])
+        .description('事件触发时执行的外部命令列表；按声明顺序触发'),
+}).description('dsh-hooks 配置：声明式生命周期 hooks');

package/lib/context.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Hook execution context: a flat string map rendered into environment
+ * variables and `{{var}}` placeholders. Never carries non-string values —
+ * the runner owns serialization boundaries.
+ */
+export interface HookContext {
+    event: string;
+    sessionId?: string;
+    /**
+     * Readable session title (the latest `session/title` log event, or a
+     * first-prompt fallback), when the session log offers one.
+     */
+    sessionName?: string;
+    /** Absolute working directory of the session, when known. */
+    cwd?: string;
+    turn?: number;
+    reason?: string;
+    tool?: string;
+    callId?: string;
+    durationMs?: number;
+    status?: string;
+    error?: string;
+    /** Turn content snapshot, e.g. the turn's final assistant text. */
+    content?: string;
+    timestamp: string;
+}
+export declare function toEnv(ctx: HookContext): Record<string, string>;
+/** Render `{{DSH_HOOK_*}}` placeholders from the context map. */
+export declare function renderTemplate(template: string, ctx: HookContext): string;
+/** Human-readable label for an event, used in runner logs. */
+export declare function eventLabel(ctx: HookContext): string;

package/lib/context.js

@@ -0,0 +1,48 @@
+/**
+ * Hook execution context: a flat string map rendered into environment
+ * variables and `{{var}}` placeholders. Never carries non-string values —
+ * the runner owns serialization boundaries.
+ */
+export function toEnv(ctx) {
+    const env = { DSH_HOOK_EVENT: ctx.event, DSH_HOOK_TIMESTAMP: ctx.timestamp };
+    if (ctx.sessionId !== undefined)
+        env.DSH_HOOK_SESSION_ID = ctx.sessionId;
+    if (ctx.sessionName !== undefined)
+        env.DSH_HOOK_SESSION_NAME = ctx.sessionName;
+    if (ctx.cwd !== undefined)
+        env.DSH_HOOK_CWD = ctx.cwd;
+    if (ctx.turn !== undefined)
+        env.DSH_HOOK_TURN = String(ctx.turn);
+    if (ctx.reason !== undefined)
+        env.DSH_HOOK_REASON = ctx.reason;
+    if (ctx.tool !== undefined)
+        env.DSH_HOOK_TOOL = ctx.tool;
+    if (ctx.callId !== undefined)
+        env.DSH_HOOK_CALL_ID = ctx.callId;
+    if (ctx.durationMs !== undefined)
+        env.DSH_HOOK_DURATION_MS = String(ctx.durationMs);
+    if (ctx.status !== undefined)
+        env.DSH_HOOK_STATUS = ctx.status;
+    if (ctx.error !== undefined)
+        env.DSH_HOOK_ERROR = ctx.error;
+    if (ctx.content !== undefined)
+        env.DSH_HOOK_CONTENT = ctx.content;
+    return env;
+}
+/** Render `{{DSH_HOOK_*}}` placeholders from the context map. */
+export function renderTemplate(template, ctx) {
+    const env = toEnv(ctx);
+    return template.replace(/\{\{(\w+)\}\}/g, (whole, key) => Object.prototype.hasOwnProperty.call(env, key) ? env[key] : whole);
+}
+/** Human-readable label for an event, used in runner logs. */
+export function eventLabel(ctx) {
+    const session = ctx.sessionId ? ` · 会话 ${ctx.sessionName ?? ctx.sessionId}` : '';
+    const extra = ctx.reason !== undefined
+        ? ` · ${ctx.reason}`
+        : ctx.tool !== undefined
+            ? ` · 工具 ${ctx.tool}`
+            : ctx.status !== undefined
+                ? ` · ${ctx.status}`
+                : '';
+    return `${ctx.event}${extra}${session}`;
+}

package/lib/events.d.ts

@@ -0,0 +1,64 @@
+import type { Session, SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session';
+import type { HookContext } from './context.js';
+import type { HookSpec, TurnEndReasonKind } from './config.js';
+import type { AgentLike } from './types.js';
+/** `approval/asked` payload (merge-extensible, declared by dsh-user-approval). */
+export interface ApprovalAskedData {
+    id: string;
+    toolName: string;
+    callId?: string;
+    reason?: string;
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        'approval/asked': ApprovalAskedData;
+    }
+}
+/** Agent lifecycle payloads (structural; emitted by dsh-agent's AgentService). */
+export interface AgentCreatedPayload {
+    agent: AgentLike;
+}
+export interface AgentDisposedPayload {
+    agent: AgentLike;
+}
+export interface AgentErrorPayload {
+    agent: AgentLike;
+    turn?: number;
+    step?: number;
+    error?: unknown;
+}
+export interface AgentStatusPayload {
+    agent: AgentLike;
+    status?: unknown;
+}
+/**
+ * Readable session title for notification cards. Mirrors the harness
+ * session-title conventions without depending on the title service:
+ * prefer the latest `session/title` log event (explicit rename, LLM title, or
+ * deterministic fallback), otherwise derive one from the first direct human
+ * prompt, as `dsh-session-title`'s fallback does.
+ */
+export declare function sessionTitle(session: Session): string | undefined;
+/**
+ * The turn's final assistant text, from the last `assistant/message` of that
+ * turn. Capped so the environment snapshot stays small — card builders apply
+ * their own display truncation.
+ */
+export declare function turnContent(session: Session, turn: number): string | 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;
+export declare function turnEndContext(session: Session, turn: number, reason: TurnEndReason | string): HookContext;
+export declare function turnStartContext(session: Session, turn: number): HookContext;
+export declare function approvalContext(session: Session, data: ApprovalAskedData): HookContext;
+export declare function agentCreatedContext(agent: AgentLike): HookContext;
+export declare function agentDisposedContext(agent: AgentLike): HookContext;
+export declare function agentErrorContext(agent: AgentLike, turn: number | undefined, error: unknown): HookContext;
+export declare function agentStatusContext(agent: AgentLike, status: unknown): HookContext;
+/** Classify a session event into a hook context, or undefined when unmapped. */
+export declare function classifySessionEvent(session: Session, event: SessionEvent): HookContext | undefined;
+/** Best-effort error text from an arbitrary thrown value. */
+export declare function errorText(error: unknown): string;
+/** Best-effort status text from an agent status payload. */
+export declare function statusText(status: unknown): string;