dsh-hooks 0.2.1

package/lib/events.js

@@ -0,0 +1,213 @@
+/** Per-session turn start timestamps for duration reporting. */
+const turnStarts = new Map();
+function sessionKey(session) {
+    return String(session.id);
+}
+/** Best-effort access to a session's event log (test fakes may omit it). */
+function sessionEvents(session) {
+    return Array.isArray(session.events) ? session.events : [];
+}
+/** Concatenate the text blocks of a message's content, or undefined. */
+function textOfBlocks(content) {
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = [];
+    for (const block of content) {
+        if (block && block.type === 'text' && typeof block.text === 'string')
+            parts.push(block.text);
+    }
+    const text = parts.join('\n\n').trim();
+    return text || undefined;
+}
+/** Terminal-safe single line for a title: strip control/escape sequences. */
+function oneLineTitle(input) {
+    return String(input)
+        .replace(/\u001B(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007]*(?:\u0007|\u001B\\))/g, '')
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * 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 function sessionTitle(session) {
+    const events = sessionEvents(session);
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.type !== 'session/title')
+            continue;
+        const title = oneLineTitle(event.data?.title);
+        if (title)
+            return title.slice(0, 60);
+    }
+    for (const event of events) {
+        if (event.type !== 'user/message')
+            continue;
+        if (event.data.source.kind !== 'user')
+            continue;
+        const text = textOfBlocks(event.data.content);
+        if (!text)
+            continue;
+        const title = oneLineTitle(text);
+        if (title)
+            return title.slice(0, 60);
+    }
+    return 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 function turnContent(session, turn) {
+    let out;
+    for (const event of sessionEvents(session)) {
+        if (event.type !== 'assistant/message')
+            continue;
+        if (event.data.turn !== turn)
+            continue;
+        const text = textOfBlocks(event.data.message.content);
+        if (text)
+            out = text;
+    }
+    return out === undefined ? undefined : out.slice(0, 4000);
+}
+export function rememberTurnStart(session) {
+    turnStarts.set(sessionKey(session), Date.now());
+}
+function takeDuration(session) {
+    const key = sessionKey(session);
+    const started = turnStarts.get(key);
+    turnStarts.delete(key);
+    return started === undefined ? undefined : Date.now() - started;
+}
+export function clearTurnTracking(session) {
+    turnStarts.delete(sessionKey(session));
+}
+/** Does a declared hook match this event (type + optional `when` filter)? */
+export function hookMatches(spec, event, reasonKind) {
+    if (spec.on !== event)
+        return false;
+    if (spec.when === undefined)
+        return true;
+    // v1 `when` semantics: only `turn/end` carries a reason to filter on.
+    if (event !== 'turn/end')
+        return true;
+    return spec.when === reasonKind;
+}
+export function turnEndContext(session, turn, reason) {
+    const kind = typeof reason === 'string' ? reason : reason.kind;
+    let error;
+    if (typeof reason === 'object' && reason !== null && kind === 'error') {
+        const failure = reason.error;
+        if (typeof failure?.message === 'string')
+            error = failure.message;
+    }
+    return {
+        event: 'turn/end',
+        sessionId: sessionKey(session),
+        sessionName: sessionTitle(session),
+        cwd: session.header.cwd,
+        turn,
+        reason: kind,
+        durationMs: takeDuration(session),
+        error,
+        content: turnContent(session, turn),
+        timestamp: new Date().toISOString(),
+    };
+}
+export function turnStartContext(session, turn) {
+    return {
+        event: 'turn/start',
+        sessionId: sessionKey(session),
+        sessionName: sessionTitle(session),
+        cwd: session.header.cwd,
+        turn,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function approvalContext(session, data) {
+    return {
+        event: 'approval/asked',
+        sessionId: sessionKey(session),
+        sessionName: sessionTitle(session),
+        cwd: session.header.cwd,
+        tool: data.toolName,
+        callId: data.callId,
+        reason: data.reason,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function agentCreatedContext(agent) {
+    return {
+        event: 'agent/created',
+        sessionId: String(agent.id),
+        timestamp: new Date().toISOString(),
+    };
+}
+export function agentDisposedContext(agent) {
+    return {
+        event: 'agent/disposed',
+        sessionId: String(agent.id),
+        timestamp: new Date().toISOString(),
+    };
+}
+export function agentErrorContext(agent, turn, error) {
+    return {
+        event: 'agent/error',
+        sessionId: String(agent.id),
+        turn,
+        error: errorText(error),
+        timestamp: new Date().toISOString(),
+    };
+}
+export function agentStatusContext(agent, status) {
+    return {
+        event: 'agent/status',
+        sessionId: String(agent.id),
+        status: statusText(status),
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Classify a session event into a hook context, or undefined when unmapped. */
+export function classifySessionEvent(session, event) {
+    switch (event.type) {
+        case 'turn/start':
+            rememberTurnStart(session);
+            return turnStartContext(session, event.data.turn);
+        case 'turn/end':
+            return turnEndContext(session, event.data.turn, event.data.reason);
+        case 'approval/asked':
+            return approvalContext(session, event.data);
+        default:
+            return undefined;
+    }
+}
+/** Best-effort error text from an arbitrary thrown value. */
+export function errorText(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return String(error);
+    }
+}
+/** Best-effort status text from an agent status payload. */
+export function statusText(status) {
+    if (typeof status === 'string')
+        return status;
+    if (typeof status === 'object' && status !== null && 'kind' in status) {
+        const kind = status.kind;
+        if (typeof kind === 'string')
+            return kind;
+    }
+    return String(status);
+}

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '@deepseek-ai/cordis';
+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 { Config };
+export declare function apply(ctx: Context, config?: Config): void;
+export declare const _internals: {
+    clearTurnTracking: typeof clearTurnTracking;
+};

package/lib/index.js

@@ -0,0 +1,56 @@
+import './types.js';
+import { Config } from './config.js';
+import { agentCreatedContext, agentDisposedContext, agentErrorContext, agentStatusContext, classifySessionEvent, clearTurnTracking, hookMatches, } from './events.js';
+import { createHookRunner } from './runner.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 function apply(ctx, config = {}) {
+    const hooks = config.hooks ?? [];
+    const runner = createHookRunner((line) => ctx.logger?.info(line));
+    const runMatching = (ctxValue, reasonKind) => {
+        for (const hook of hooks) {
+            if (!hookMatches(hook, ctxValue.event, reasonKind))
+                continue;
+            runner.run(hook, ctxValue);
+        }
+    };
+    // Durable session firehose: turn boundaries and approval requests.
+    ctx.on('session/event', (session, event) => {
+        const classified = classifySessionEvent(session, event);
+        if (classified === undefined)
+            return;
+        const reasonKind = extractReasonKind(event);
+        runMatching(classified, reasonKind);
+    });
+    // Agent lifecycle events.
+    ctx.on('agent/created', (payload) => {
+        runMatching(agentCreatedContext(payload.agent));
+    });
+    ctx.on('agent/disposed', (payload) => {
+        runMatching(agentDisposedContext(payload.agent));
+    });
+    ctx.on('agent/error', (payload) => {
+        runMatching(agentErrorContext(payload.agent, payload.turn, payload.error));
+    });
+    ctx.on('agent/status', (payload) => {
+        runMatching(agentStatusContext(payload.agent, payload.status));
+    });
+    ctx.effect(() => () => {
+        runner.dispose();
+    });
+}
+/** Extract the `turn/end` reason kind from a session event, when present. */
+function extractReasonKind(event) {
+    if (typeof event !== 'object' || event === null)
+        return undefined;
+    const e = event;
+    if (e.type !== 'turn/end')
+        return undefined;
+    return typeof e.data?.reason?.kind === 'string' ? e.data.reason.kind : undefined;
+}
+// Referenced only for tree-shaking clarity of the module contract; clearTurnTracking
+// is exported for tests that need deterministic duration bookkeeping.
+export const _internals = { clearTurnTracking };

package/lib/runner.d.ts

@@ -0,0 +1,29 @@
+import { type ChildProcess } from 'node:child_process';
+import type { HookContext } from './context.js';
+import type { HookSpec } from './config.js';
+export interface RunOutcome {
+    ok: boolean;
+    reason: 'ran' | 'timeout' | 'spawn-failed' | 'skipped';
+    detail?: string;
+}
+/** Track in-flight hook runs so a missing parent never outlives teardown. */
+export interface HookRunner {
+    run(spec: HookSpec, ctx: HookContext): RunOutcome;
+    dispose(): void;
+}
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * 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
+ * (e.g. `node notify-feishu.mjs`), so kill the whole tree first. The direct
+ * kill stays as the fallback (and the only path off Windows).
+ */
+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.
+ */
+export declare function createHookRunner(log?: (line: string) => void): HookRunner;

package/lib/runner.js

@@ -0,0 +1,70 @@
+import { spawn } from 'node:child_process';
+import { eventLabel, renderTemplate, toEnv } from './context.js';
+export const DEFAULT_TIMEOUT_MS = 10000;
+/**
+ * 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
+ * (e.g. `node notify-feishu.mjs`), so kill the whole tree first. The direct
+ * kill stays as the fallback (and the only path off Windows).
+ */
+export function terminate(child) {
+    if (process.platform === 'win32' && child.pid !== undefined) {
+        try {
+            spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' }).unref();
+        }
+        catch {
+            // taskkill unavailable — fall through to the direct kill below.
+        }
+    }
+    child.kill();
+}
+/**
+ * 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.
+ */
+export function createHookRunner(log = console.log) {
+    const children = new Set();
+    function run(spec, ctx) {
+        const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const env = toEnv(ctx);
+        const command = renderTemplate(spec.run, ctx);
+        log(`[dsh-hooks] 触发 ${eventLabel(ctx)} → ${command}`);
+        let child;
+        try {
+            child = spawn(command, {
+                shell: true,
+                env: { ...process.env, ...env },
+                stdio: 'ignore',
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            console.warn(`[dsh-hooks] spawn 失败 (${eventLabel(ctx)}): ${detail}`);
+            return { ok: false, reason: 'spawn-failed', detail };
+        }
+        children.add(child);
+        const timer = setTimeout(() => {
+            terminate(child);
+            console.warn(`[dsh-hooks] 超时（${timeoutMs}ms），已终止：${eventLabel(ctx)}`);
+        }, timeoutMs);
+        // Never hold the process open for a hook.
+        child.unref();
+        child.on('error', (error) => {
+            console.warn(`[dsh-hooks] 执行出错 (${eventLabel(ctx)}): ${error.message}`);
+        });
+        child.on('close', () => {
+            clearTimeout(timer);
+            children.delete(child);
+        });
+        return { ok: true, reason: 'ran' };
+    }
+    function dispose() {
+        for (const child of children)
+            terminate(child);
+        children.clear();
+    }
+    return { run, dispose };
+}

package/lib/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Event declarations for the `agent/*` lifecycle events emitted by
+ * `@deepseek-ai/dsh-agent`. This plugin does not hard-depend on dsh-agent:
+ * the payload shapes are structural and declared here so `ctx.on` calls
+ * type-check against the harness Events map without pulling the agent
+ * package into the dependency graph.
+ */
+export interface AgentLike {
+    id: unknown;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'agent/created'(this: {
+            id: unknown;
+        }, payload: {
+            agent: AgentLike;
+        }): void;
+        'agent/disposed'(this: {
+            id: unknown;
+        }, payload: {
+            agent: AgentLike;
+        }): void;
+        'agent/error'(this: {
+            id: unknown;
+        }, payload: {
+            agent: AgentLike;
+            turn?: number;
+            step?: number;
+            error?: unknown;
+        }): void;
+        'agent/status'(this: {
+            id: unknown;
+        }, payload: {
+            agent: AgentLike;
+            status?: unknown;
+        }): void;
+    }
+}

package/lib/types.js

@@ -0,0 +1,8 @@
+/**
+ * Event declarations for the `agent/*` lifecycle events emitted by
+ * `@deepseek-ai/dsh-agent`. This plugin does not hard-depend on dsh-agent:
+ * the payload shapes are structural and declared here so `ctx.on` calls
+ * type-check against the harness Events map without pulling the agent
+ * package into the dependency graph.
+ */
+export {};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "dsh-hooks",
+  "version": "0.2.1",
+  "packageManager": "pnpm@11.21.0",
+  "description": "Config-driven lifecycle hooks plugin for DeepSeek Harness: declare event -> command hooks in cordis.patch.yml, no plugin code required.",
+  "author": "PeterBon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeterBon/dsh-hooks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeterBon/dsh-hooks/issues"
+  },
+  "homepage": "https://github.com/PeterBon/dsh-hooks#readme",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek",
+    "deepseek-harness",
+    "hooks",
+    "automation",
+    "lifecycle",
+    "notification"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "bin": {
+    "dsh-hooks": "./bin/dsh-hooks.mjs"
+  },
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "bin",
+    "cordis.patch.yml",
+    "examples",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run typecheck && pnpm run typecheck:test && pnpm run test && pnpm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^22.10.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.73.0",
+    "qrcode": "^1.5.4",
+    "yaml": "^2.9.0"
+  }
+}