@deepseek-ai/dsh-hook-protocol 0.2.0-rc.1 → 0.2.1-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.i18n.yaml +10 -10
  2. package/README.md +4 -5
  3. package/README.zh.md +4 -5
  4. package/package.json +7 -14
  5. package/lib/invariant.js +0 -97
  6. package/lib/types/invariant.d.ts +0 -13
package/README.i18n.yaml CHANGED
@@ -30,20 +30,20 @@
30
30
  en: 08b3960150e9c5e2
31
31
  zh: 6bb2f236d697de01
32
32
  /deepseek-ai-dsh-hook-protocol/understand-the-implementation/processing-pipeline:
33
- en: 5672f4151de0b50a
34
- zh: d8fdc68d806e0d7b
33
+ en: b25d80f19b551f1a
34
+ zh: 9c6602f008d89bce
35
35
  /deepseek-ai-dsh-hook-protocol/understand-the-implementation/hook-session-events:
36
- en: ad77f468168fcbff
37
- zh: 897bc6880fe76e1b
36
+ en: f01ab4ab98f052b3
37
+ zh: 1da25fa50378bd19
38
38
  /deepseek-ai-dsh-hook-protocol/understand-the-implementation/design-philosophy:
39
- en: ccf3eacdd2219631
40
- zh: 0732935a47a17c9d
39
+ en: 7f9239eaea5a945c
40
+ zh: 9ba6a2ea955d4934
41
41
  /deepseek-ai-dsh-hook-protocol/understand-the-implementation/source-map:
42
- en: d613d9bd98d499fb
43
- zh: afe2939d7df250ea
42
+ en: aa4983adf89ea45c
43
+ zh: cc83b0ede5ff156c
44
44
  /deepseek-ai-dsh-hook-protocol/further-exploration:
45
- en: d93c5107a12af16c
46
- zh: 89da3abc953a4c6b
45
+ en: 65a937c4c5f221d5
46
+ zh: 3b9d6485493dfb8d
47
47
  /deepseek-ai-dsh-hook-protocol/model-experience:
48
48
  en: 53d2f59435a4a88f
49
49
  zh: 79c8fc2849b20718
package/README.md CHANGED
@@ -60,20 +60,20 @@ This section explains the design decisions behind the library and points at the
60
60
 
61
61
  ### Processing pipeline
62
62
 
63
- The library is a chain of single-purpose steps, one function each: validate the matcher pattern, run the command through the `dsh-shell` executor, decode the outcome, merge every matched hook's outcome into one most-restrictive result, and record the durable `hook/*` event pair. The matcher's `mode` parameter is the single axis the dialects differ on — `claude-code` interprets a pattern as literal alternatives or a regex, `codex` always as an unanchored regex. Every step degrades to a contained outcome instead of throwing, so a hook can never crash the calling turn: an invalid regex is a non-match, an executor rejection becomes a `HookOutput` with no exit code, exit 2 blocks with stderr as the reason, and every other failure stays non-blocking. Merging applies `deny > ask > allow` precedence, keeps the first `continue: false` stop sticky, and accumulates context in hook order. Detached runs are tracked so `fiber.dispose()` reaches quiescence, and the invariant companion rejects `hook/*` records outside an open turn. The steps live in [`src/matcher.ts`](src/matcher.ts), [`src/runner.ts`](src/runner.ts), [`src/codec.ts`](src/codec.ts), [`src/merge.ts`](src/merge.ts), [`src/events.ts`](src/events.ts), [`src/detached.ts`](src/detached.ts), and [`src/invariant.ts`](src/invariant.ts).
63
+ The library is a chain of single-purpose steps, one function each: validate the matcher pattern, run the command through the `dsh-shell` executor, decode the outcome, merge every matched hook's outcome into one most-restrictive result, and record the durable `hook/*` event pair. The matcher's `mode` parameter is the single axis the dialects differ on — `claude-code` interprets a pattern as literal alternatives or a regex, `codex` always as an unanchored regex. Every step degrades to a contained outcome instead of throwing, so a hook can never crash the calling turn: an invalid regex is a non-match, an executor rejection becomes a `HookOutput` with no exit code, exit 2 blocks with stderr as the reason, and every other failure stays non-blocking. Merging applies `deny > ask > allow` precedence, keeps the first `continue: false` stop sticky, and accumulates context in hook order. Detached runs are tracked so `fiber.dispose()` reaches quiescence. The steps live in [`src/matcher.ts`](src/matcher.ts), [`src/runner.ts`](src/runner.ts), [`src/codec.ts`](src/codec.ts), [`src/merge.ts`](src/merge.ts), [`src/events.ts`](src/events.ts), and [`src/detached.ts`](src/detached.ts).
64
64
 
65
65
  ### `hook/*` session events
66
66
 
67
67
  The `hook/invoked` and `hook/result` events are declaration-merged into `SessionEventMap` as log-only records: like `compaction/*`, they are not surface events and carry no `surfaceOp`. A `hook/result` pairs with its `hook/invoked` by `handlerId`, and `appendHookResult` owns the decision rule. Payloads and per-event JSDoc live in the generated [persistence log event catalog](../../../docs/persistence-catalog.md).
68
68
 
69
- Invocation and result records must sit inside an open turn: `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that relation by construction, while `SessionStart` runs before turn 1 and gets no `hook/*` record — its injected context is delivered instead. The invariant companion registers on `ctx.invariants` and rejects `hook/*` events appended outside an open turn, a result without a matching invoked, an unknown dialect, or a non-finite duration.
69
+ Invocation and result records must sit inside an open turn: `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` satisfy that relation by construction, while `SessionStart` runs before turn 1 and gets no `hook/*` record — its injected context is delivered instead.
70
70
 
71
71
  ### Design philosophy
72
72
 
73
73
  - **One axis of difference collapsed into `mode`.** The dialects differ only in how a matcher pattern is interpreted, so the matcher takes the mode as a parameter instead of duplicating the engine.
74
74
  - **The executor owns process control.** Commands run through the `dsh-shell` executor rather than a bespoke spawn: the executor already provides the scrubbed-but-overridable environment, process-group cancellation, and timeout the protocol needs.
75
75
  - **Never throw into the loop.** Every failure mode — malformed JSON, an invalid regex, an executor rejection — degrades to a contained outcome or a non-match, so a hook can never crash the calling turn.
76
- - **Log-only, turn-enclosed events.** The `hook/*` records are durable evidence of what ran and what it decided; they are not surface events, and the invariant companion rejects them outside an open turn.
76
+ - **Log-only, turn-enclosed events.** The `hook/*` records are durable evidence of what ran and what it decided; they are not surface events.
77
77
 
78
78
  The [hook-protocol-lib Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-protocol-lib.md) records the shared-versus-per-dialect split and the alternatives considered.
79
79
 
@@ -89,7 +89,6 @@ The [hook-protocol-lib Agent Note](../../../.agents/notes/archived/feature/2026-
89
89
  | [`src/events.ts`](src/events.ts) | `hook/*` event declaration, append helpers, stderr summary |
90
90
  | [`src/detached.ts`](src/detached.ts) | Detached-run quiescence tracking |
91
91
  | [`src/types.ts`](src/types.ts) | `HookOutput`, `MatcherGroup`, `CommandHook`, and the `hook/*` payload types |
92
- | [`src/invariant.ts`](src/invariant.ts) | Invariant companion: pairing, turn enclosure, dialect, and duration checks |
93
92
 
94
93
  </details>
95
94
 
@@ -103,7 +102,7 @@ Read these pages when the package-level contract is not enough. They move from t
103
102
  - [Hooks group map](../README.md) — the sibling group page and its package table.
104
103
  - [Hook protocol library Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-protocol-lib.md) — why the protocol core is shared and what each bridge owns.
105
104
  - [Hook bridges Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-bridges.md) — how the two bridges use these primitives.
106
- - [Interception extension-points Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.md) — the typed-Decision surface the bridges map onto.
105
+ - [Interception extension-points reference](../../../docs/tool-execution-pipeline.md) — the typed-Decision surface the bridges map onto.
107
106
  - [Generated persistence log event catalog](../../../docs/persistence-catalog.md) — the `hook/*` event payloads and per-event JSDoc.
108
107
 
109
108
  -----
package/README.zh.md CHANGED
@@ -60,20 +60,20 @@ kind: "package-library"
60
60
 
61
61
  ### 处理流水线
62
62
 
63
- 本库是一串单一用途的步骤，每个步骤一个函数：校验 matcher pattern、通过 `dsh-shell` 执行器运行命令、解码结果、把每个匹配 hook 的结果合并为最严格的一个结果，并记录持久的 `hook/*` 事件对。matcher 的 `mode` 参数是两个方言唯一的差异轴——`claude-code` 把 pattern 解释为字面量备选或正则，`codex` 始终解释为未锚定正则。每个步骤都会降级为受控结果而不是抛异常，因此钩子永远不会使调用轮次崩溃：无效正则是运行时的不匹配，执行器拒绝会变成没有退出码的 `HookOutput`，退出码 2 以 stderr 作为原因阻塞，其他失败均不阻塞。合并应用 `deny > ask > allow` 优先级，保持首个 `continue: false` 停止的粘性，并按 hook 顺序累积上下文。脱离运行会被跟踪，因此 `fiber.dispose()` 能达到完全停稳；不变式伴生插件会拒绝位于尚未结束的轮次之外的 `hook/*` 记录。这些步骤位于 [`src/matcher.ts`](src/matcher.ts)、[`src/runner.ts`](src/runner.ts)、[`src/codec.ts`](src/codec.ts)、[`src/merge.ts`](src/merge.ts)、[`src/events.ts`](src/events.ts)、[`src/detached.ts`](src/detached.ts) 与 [`src/invariant.ts`](src/invariant.ts)。
63
+ 本库是一串单一用途的步骤，每个步骤一个函数：校验 matcher pattern、通过 `dsh-shell` 执行器运行命令、解码结果、把每个匹配 hook 的结果合并为最严格的一个结果，并记录持久的 `hook/*` 事件对。matcher 的 `mode` 参数是两个方言唯一的差异轴——`claude-code` 把 pattern 解释为字面量备选或正则，`codex` 始终解释为未锚定正则。每个步骤都会降级为受控结果而不是抛异常，因此钩子永远不会使调用轮次崩溃：无效正则是运行时的不匹配，执行器拒绝会变成没有退出码的 `HookOutput`，退出码 2 以 stderr 作为原因阻塞，其他失败均不阻塞。合并应用 `deny > ask > allow` 优先级，保持首个 `continue: false` 停止的粘性，并按 hook 顺序累积上下文。脱离运行会被跟踪，因此 `fiber.dispose()` 能达到完全停稳。这些步骤位于 [`src/matcher.ts`](src/matcher.ts)、[`src/runner.ts`](src/runner.ts)、[`src/codec.ts`](src/codec.ts)、[`src/merge.ts`](src/merge.ts)、[`src/events.ts`](src/events.ts) 与 [`src/detached.ts`](src/detached.ts)。
64
64
 
65
65
  ### `hook/*` 会话事件
66
66
 
67
67
  `hook/invoked` 与 `hook/result` 事件通过 declaration merging 合并进 `SessionEventMap`，作为仅日志记录：与 `compaction/*` 相同，它们不是 surface 事件，也不携带 `surfaceOp`。`hook/result` 按 `handlerId` 与其 `hook/invoked` 配对，决策规则由 `appendHookResult` 负责。载荷与逐事件 JSDoc 位于生成的[持久化日志事件目录](../../../docs/persistence-catalog.zh.md)中。
68
68
 
69
- 调用与结果记录必须位于尚未结束的轮次内：`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足该关系，而 `SessionStart` 在轮次 1 之前运行、没有 `hook/*` 记录——改为投递其注入的上下文。不变式伴生插件注册到 `ctx.invariants`，拒绝在尚未结束的轮次之外追加的 `hook/*` 事件、没有匹配 invoked 的结果、未知方言或非有限时长。
69
+ 调用与结果记录必须位于尚未结束的轮次内：`UserPromptSubmit`、`PreToolUse`、`PostToolUse` 与 `Stop` 按构造满足该关系，而 `SessionStart` 在轮次 1 之前运行、没有 `hook/*` 记录——改为投递其注入的上下文。
70
70
 
71
71
  ### 设计理念
72
72
 
73
73
  - **把唯一差异轴收拢进 `mode`。** 两个方言只在 matcher pattern 的解读方式上不同，因此 matcher 把 mode 作为参数，而不是复制引擎。
74
74
  - **执行器拥有进程控制。** 命令通过 `dsh-shell` 执行器运行，而非自建 spawn：执行器已经提供了协议所需的已清理但可覆盖的环境、进程组取消与超时。
75
75
  - **绝不向循环抛异常。** 每种失败模式——格式错误的 JSON、无效正则、执行器拒绝——都会降级为受控的结果或不匹配，因此钩子永远不能使调用轮次崩溃。
76
- - **仅日志、轮次内的事件。** `hook/*` 记录是「运行了什么、决定了什么」的持久证据；它们不是 surface 事件，不变式伴生插件会拒绝尚未结束的轮次之外的记录。
76
+ - **仅日志、轮次内的事件。** `hook/*` 记录是「运行了什么、决定了什么」的持久证据；它们不是 surface 事件。
77
77
 
78
78
  [hook-protocol-lib Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-protocol-lib.md) 记录了共享与逐方言的划分以及备选方案。
79
79
 
@@ -89,7 +89,6 @@ kind: "package-library"
89
89
  | [`src/events.ts`](src/events.ts) | `hook/*` 事件声明、追加辅助函数、stderr 摘要 |
90
90
  | [`src/detached.ts`](src/detached.ts) | 脱离运行的完全停稳跟踪 |
91
91
  | [`src/types.ts`](src/types.ts) | `HookOutput`、`MatcherGroup`、`CommandHook` 与 `hook/*` 载荷类型 |
92
- | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件：配对、轮次包裹、方言与时长检查 |
93
92
 
94
93
  </details>
95
94
 
@@ -103,7 +102,7 @@ kind: "package-library"
103
102
  - [hooks 组地图](../README.zh.md)——同级组页面及其包表。
104
103
  - [hook-protocol-lib Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-protocol-lib.md)——协议核心为何共享、各桥接负责什么。
105
104
  - [钩子桥接 Agent Note](../../../.agents/notes/archived/feature/2026-06-30-hook-bridges.md)——两个桥接如何使用这些原语。
106
- - [拦截扩展点 Agent Note](../../../.agents/notes/implemented/feature/2026-06-30-interception-extension-points.zh.md)——桥接所映射的类型化 Decision 接口面。
105
+ - [拦截扩展点 参考](../../../docs/tool-execution-pipeline.zh.md)——桥接所映射的类型化 Decision 接口面。
107
106
  - [生成的持久化日志事件目录](../../../docs/persistence-catalog.zh.md)——`hook/*` 事件载荷与逐事件 JSDoc。
108
107
 
109
108
  -----
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@deepseek-ai/dsh-hook-protocol",
3
3
  "description": "Shared Claude Code / Codex hook wire protocol: matcher engine, stdin/exit-code/stdout codec, multi-hook merge, and hook/* session events",
4
- "version": "0.2.0-rc.1",
4
+ "version": "0.2.1-alpha.1",
5
5
  "publishConfig": {
6
6
  "access": "public"
7
7
  },
@@ -18,29 +18,22 @@
18
18
  "types": "./lib/types/index.d.ts",
19
19
  "default": "./lib/index.js"
20
20
  },
21
- "./invariant": {
22
- "types": "./lib/types/invariant.d.ts",
23
- "default": "./lib/invariant.js"
24
- },
25
21
  "./src/*": "./src/*",
26
22
  "./package.json": "./package.json"
27
23
  },
28
24
  "files": [
29
25
  "lib/index.js",
30
- "lib/invariant.js",
31
26
  "lib/types/**/*.d.ts"
32
27
  ],
33
28
  "license": "MIT",
34
29
  "peerDependencies": {
35
- "@deepseek-ai/dsh-shell": "0.2.0-rc.1",
36
- "@deepseek-ai/dsh-invariants": "0.2.0-rc.1",
37
- "@deepseek-ai/dsh-session": "0.2.0-rc.1",
38
- "@deepseek-ai/cordis": "~4.0.4"
30
+ "@deepseek-ai/dsh-shell": "0.2.1-alpha.1",
31
+ "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
32
+ "@deepseek-ai/cordis": "~4.0.5-alpha.1"
39
33
  },
40
34
  "devDependencies": {
41
- "@deepseek-ai/dsh-shell": "0.2.0-rc.1",
42
- "@deepseek-ai/dsh-invariants": "0.2.0-rc.1",
43
- "@deepseek-ai/dsh-session": "0.2.0-rc.1",
44
- "@deepseek-ai/cordis": "~4.0.4"
35
+ "@deepseek-ai/dsh-session": "0.2.1-alpha.1",
36
+ "@deepseek-ai/cordis": "~4.0.5-alpha.1",
37
+ "@deepseek-ai/dsh-shell": "0.2.1-alpha.1"
45
38
  }
46
39
  }
package/lib/invariant.js DELETED
@@ -1,97 +0,0 @@
1
- //#region lib/types/invariant.js
2
- /** Package-owned hook invocation/result stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
3
- const PACKAGE_NAME = "@deepseek-ai/dsh-hook-protocol";
4
- /** Cordis companion plugin name. */
5
- const name = "hook-protocol-invariant";
6
- /** Service required before the companion can reserve package ownership. */
7
- const inject = ["invariants"];
8
- /** Correlation key shared by an invoked/result pair. */
9
- function hookKey(data) {
10
- return `${data.turn}\0${data.point}\0${data.handlerId}`;
11
- }
12
- /** Validate one hook event against committed pending invocations. */
13
- function validateHookEvent(trace, event, fail) {
14
- if (event.type !== "hook/invoked" && event.type !== "hook/result") return void 0;
15
- if (trace.openTurn === null) fail(`${event.type} appended outside any open turn`);
16
- if (event.data.turn !== trace.openTurn) fail(`${event.type} names turn ${event.data.turn} but open turn is ${trace.openTurn}`);
17
- if (event.type === "hook/invoked") {
18
- if (event.data.point.length === 0 || event.data.handlerId.length === 0) fail("hook/invoked point and handlerId must be non-empty");
19
- const dialect = event.data.dialect;
20
- if (dialect !== "claude-code" && dialect !== "codex") fail(`hook/invoked carries unknown dialect ${JSON.stringify(dialect)}`);
21
- return {
22
- key: hookKey(event.data),
23
- delta: 1
24
- };
25
- }
26
- const key = hookKey(event.data);
27
- if ((trace.pending.get(key) ?? 0) === 0) fail(`hook/result has no matching hook/invoked for ${JSON.stringify(event.data.handlerId)}`);
28
- if (!Number.isFinite(event.data.durationMs) || event.data.durationMs < 0) fail("hook/result durationMs must be a non-negative finite number");
29
- return {
30
- key,
31
- delta: -1
32
- };
33
- }
34
- /** Apply one committed hook-pair transition. */
35
- function applyHookTransition(pending, transition) {
36
- const next = (pending.get(transition.key) ?? 0) + transition.delta;
37
- if (next === 0) pending.delete(transition.key);
38
- else pending.set(transition.key, next);
39
- }
40
- /** Install hook invoked/result pairing checks. */
41
- const install = Object.assign((ctx, fail) => {
42
- const traces = /* @__PURE__ */ new WeakMap();
43
- const staged = /* @__PURE__ */ new WeakMap();
44
- const seed = (session) => {
45
- const trace = {
46
- openTurn: null,
47
- pending: /* @__PURE__ */ new Map()
48
- };
49
- traces.set(session, trace);
50
- for (const event of session.snapshotEvents()) {
51
- if (event.type === "turn/start") trace.openTurn = event.data.turn;
52
- else if (event.type === "turn/end") trace.openTurn = null;
53
- const transition = validateHookEvent(trace, event, fail);
54
- if (transition !== void 0) applyHookTransition(trace.pending, transition);
55
- }
56
- return trace;
57
- };
58
- const traceFor = (session) => traces.get(session) ?? seed(session);
59
- for (const session of ctx.sessions.list()) seed(session);
60
- ctx.on("session/created", (session) => {
61
- seed(session);
62
- }, { global: true });
63
- ctx.on("session/event", (session, event) => {
64
- const trace = traceFor(session);
65
- if (event.type === "turn/start") {
66
- trace.openTurn = event.data.turn;
67
- return;
68
- }
69
- if (event.type === "turn/end") {
70
- trace.openTurn = null;
71
- return;
72
- }
73
- if (event.type !== "hook/invoked" && event.type !== "hook/result") return;
74
- const candidate = staged.get(event);
75
- /* v8 ignore next -- internal/dispatch stages every hook invocation/result event */
76
- if (candidate === void 0 || candidate.session !== session) return fail("hook event published without pre-commit validation");
77
- staged.delete(event);
78
- applyHookTransition(trace.pending, candidate.transition);
79
- }, { global: true });
80
- ctx.on("internal/dispatch", (_mode, eventName, args) => {
81
- if (eventName !== "session/event") return;
82
- const [session, event] = args;
83
- const transition = validateHookEvent(traceFor(session), event, fail);
84
- if (transition !== void 0) staged.set(event, {
85
- session,
86
- transition
87
- });
88
- }, { global: true });
89
- }, { inject: ["sessions"] });
90
- /**
91
- * Register the hook-protocol invariant companion.
92
- * @param ctx - Cordis context carrying the invariant service.
93
- * @returns the installed registration's disposer after setup succeeds.
94
- */
95
- const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
96
- //#endregion
97
- export { apply, inject, name };
package/lib/types/invariant.d.ts DELETED
@@ -1,13 +0,0 @@
1
- /** Package-owned hook invocation/result stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
2
- import type { Context } from '@deepseek-ai/cordis';
3
- /** Cordis companion plugin name. */
4
- export declare const name = "hook-protocol-invariant";
5
- /** Service required before the companion can reserve package ownership. */
6
- export declare const inject: string[];
7
- /**
8
- * Register the hook-protocol invariant companion.
9
- * @param ctx - Cordis context carrying the invariant service.
10
- * @returns the installed registration's disposer after setup succeeds.
11
- */
12
- export declare const apply: (ctx: Context) => Promise<() => void>;
13
- //# sourceMappingURL=invariant.d.ts.map