@zfdx123/dsh-hooks-ordering 1.0.1

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@zfdx123/dsh-hooks-ordering",
+  "version": "1.0.1",
+  "description": "钩子排序：为 Cordis 的 waterfall / serial 钩子提供确定性的 before/after 排序，让互相独立的插件能声明彼此的先后关系（拓扑排序、环检测、可配置控制集与设置页）。",
+  "keywords": [
+    "cordis",
+    "plugin",
+    "hooks",
+    "ordering",
+    "waterfall",
+    "serial",
+    "deepseek-harness",
+    "dsh",
+    "topological-sort"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/zfdx123/dsh-atelier/tree/main/packages/dsh-hooks-ordering#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zfdx123/dsh-atelier.git",
+    "directory": "packages/dsh-hooks-ordering"
+  },
+  "bugs": {
+    "url": "https://github.com/zfdx123/dsh-atelier/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./topo-sort": {
+      "types": "./lib/topo-sort.d.ts",
+      "default": "./lib/topo-sort.js"
+    },
+    "./waterfall": {
+      "types": "./lib/waterfall.d.ts",
+      "default": "./lib/waterfall.js"
+    },
+    "./dag": {
+      "types": "./lib/dag.d.ts",
+      "default": "./lib/dag.js"
+    },
+    "./serial": {
+      "types": "./lib/serial.d.ts",
+      "default": "./lib/serial.js"
+    },
+    "./client": "./client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": "^0.1.6-alpha.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-settings": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@types/node": "^22.20.1",
+    "@vitest/coverage-v8": "^3.2.4",
+    "oxlint": "^1.0.0",
+    "tsdown": "^0.15.6",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint src test client.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "tsdown",
+    "prepublishOnly": "tsdown"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "packageManager": "pnpm@10.10.0",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}

package/src/dag.ts

@@ -0,0 +1,92 @@
+/**
+ * JSON rendering of the `before`/`after` constraint graph across controlled
+ * hook phases. Pure and dependency-free: the output is a function of the input
+ * sections alone. Deliberately NOT a topological sort — a cycle is represented
+ * faithfully rather than throwing, because the graph is most useful precisely
+ * when the constraints conflict and `topoSort` would fail.
+ * @module dsh-hooks-ordering/dag
+ */
+
+import type { Orderable } from './topo-sort.ts'
+
+/** One `(hook, phase)` slice of the constraint graph to render. */
+export interface DagSection {
+  /** The controlled hook event name. */
+  readonly hook: string
+  /** The phase within the hook (e.g. `front`/`back`). */
+  readonly phase: string
+  /** The participants and their `before`/`after` constraints. */
+  readonly entries: readonly Orderable[]
+}
+
+/** A directed ordering relation: `from` runs before `to`. */
+export interface DagEdge {
+  /** The participant that runs first. */
+  readonly from: string
+  /** The participant that runs after `from`. */
+  readonly to: string
+}
+
+/** The constraint graph of one `(hook, phase)` slice. */
+export interface DagSectionGraph {
+  /** The controlled hook event name. */
+  readonly hook: string
+  /** The phase within the hook. */
+  readonly phase: string
+  /** Every participant name, including ones with no constraint edges. */
+  readonly nodes: readonly string[]
+  /** The ordering relations; `from` runs before `to`. Deduplicated. */
+  readonly edges: readonly DagEdge[]
+}
+
+/** The whole constraint graph: one entry per controlled `(hook, phase)`. */
+export interface Dag {
+  readonly sections: readonly DagSectionGraph[]
+}
+
+/**
+ * Build the constraint graph of the given sections as a plain object suitable
+ * for `JSON.stringify`.
+ *
+ * Each section becomes a {@link DagSectionGraph}: `nodes` lists every entry
+ * name (constraint-free entries included), and `edges` carries the ordering
+ * relations. An edge `from -> to` reads "from runs before to": an entry's
+ * `before` target yields `{ from: entry, to: target }`, and its `after` source
+ * yields `{ from: source, to: entry }`. A reference whose peer is absent from
+ * the section imposes no edge — mirroring {@link topoSort}'s unknown-target
+ * no-op — and a relation stated from both ends (e.g. `A.before: ['B']` and
+ * `B.after: ['A']`) appears once.
+ *
+ * @param sections - the `(hook, phase)` slices to render, in output order.
+ * @returns the graph object; an empty input yields `{ sections: [] }`.
+ */
+export function buildDag(sections: readonly DagSection[]): Dag {
+  return {
+    sections: sections.map((section) => {
+      const present = new Set(section.entries.map((entry) => entry.name))
+      // Collect edges keyed by "from->to" to drop the same relation stated from
+      // both ends, preserving first-seen order.
+      const seen = new Set<string>()
+      const edges: DagEdge[] = []
+      const addEdge = (from: string, to: string): void => {
+        // Unknown endpoint: the referenced peer is not in this section, so
+        // there is no relation to record; a self-reference is likewise a no-op.
+        if (!present.has(from) || !present.has(to) || from === to) return
+        const key = `${from} -> ${to}`
+        if (seen.has(key)) return
+        seen.add(key)
+        edges.push({ from, to })
+      }
+      for (const entry of section.entries) {
+        for (const target of entry.before ?? []) addEdge(entry.name, target)
+        for (const source of entry.after ?? []) addEdge(source, entry.name)
+      }
+      return {
+        hook: section.hook,
+        phase: section.phase,
+        nodes: section.entries.map((entry) => entry.name),
+        edges,
+      }
+    }),
+  }
+}

package/src/dsh.ts

@@ -0,0 +1,181 @@
+/**
+ * The DeepSeek-Harness layer: a dsh plugin that mounts the ordering services
+ * and takes control of the real dsh hooks that multiple independent packages
+ * contribute to, so a profile can opt into deterministic ordering with one row.
+ *
+ * dsh (deepseek-harness) ships waterfall hooks such as `agent/pre-step`
+ * (subscribed by a dozen+ independent packages), `tools/post-execute`,
+ * `llm/stream`, and `system-prompt/assemble`, plus the serial hook
+ * `agent/turn-stopping`. Their relative listener order is load-bearing yet
+ * today decided only by binary `prepend` and registration timing. This plugin
+ * controls those hooks up front; controlling an empty hook is a transparent
+ * pass-through, so nothing changes until participants register with
+ * `before`/`after`.
+ *
+ * @module dsh-hooks-ordering/dsh
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import HookOrdering from './waterfall.ts'
+import { SerialHookOrdering } from './serial.ts'
+import { type HooksOrderingSettings, resolveSettings } from './settings.ts'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'hooks-ordering'
+
+/**
+ * `settings` is a **hard** dependency, and it has to be declared rather than
+ * probed.
+ *
+ * cordis activates a plugin as soon as the services it declares exist, and
+ * `ctx.get('settings')` reads the service store *without* creating that
+ * requirement. Without this line the dsh layer loads in the first wave — before
+ * the host has provided `settings` — the probe returns `undefined`, and the
+ * settings namespace is never registered. Silently: no form, no error.
+ *
+ * Declaring it makes cordis wait, which also lands this plugin's prepended
+ * brackets later in the boot, exactly where the ordering guarantee wants them.
+ *
+ * This entry targets dsh only — the hook names below are dsh's, and dsh always
+ * provides `settings`, so the dependency costs nothing here. `/waterfall` and
+ * `/serial` are the entries that carry no host-service requirement.
+ */
+export const inject = ['settings']
+
+/**
+ * The dsh waterfall hooks this plugin controls by default — the ones multiple
+ * independent packages contribute to, where relative order matters. Controlling
+ * a hook with no registered participants is a no-op pass-through.
+ *
+ * Every name here was checked against the events dsh actually declares: each is
+ * a `@mode waterfall` event in the installed build, and each is dispatched with
+ * `await`, so the caller already handles a Promise and the bracket's async
+ * phases cannot change the hook's return type. `tools/code-dispatch-log` used
+ * to sit in this list and no dsh package declares it at all — controlling a
+ * name nothing dispatches "succeeds" and then does nothing forever, which is
+ * exactly the dead configuration this list must not carry.
+ *
+ * The other admission rule is {@link DEFAULT_SYNC_RETURN_HOOKS}: a hook whose
+ * value the caller consumes without awaiting cannot carry ordered participants,
+ * so controlling it by default would install a bracket nothing may ever
+ * register into — the same dead configuration by a different route.
+ */
+export const DEFAULT_WATERFALL_HOOKS: readonly string[] = [
+  'agent/pre-step',
+  'agent/request',
+  'agent/request-error',
+  'system-prompt/assemble',
+  'tools/pre-execute',
+  'tools/execute',
+  'tools/post-execute',
+  'fs/write-intent',
+  'fs/edit-intent',
+  'approval/request',
+]
+
+/**
+ * dsh hooks whose dispatch return value is consumed by the caller without
+ * awaiting, and which therefore cannot carry ordered participants. Verified
+ * against the installed build:
+ *
+ * - `llm/stream` — `dsh-llm` dispatches it as
+ *   `return this.ctx.waterfall(this, "llm/stream", options, …)` (no await), and
+ *   `dsh-session-title-llm` iterates the result with
+ *   `for await (const chunk of ctx.llm.stream(options))`. A Promise there throws
+ *   "not async iterable". It is a genuine multi-contributor hook (dsh-agent-loop,
+ *   dsh-llm's own invariant, dsh-session-checkpoint-policy, dsh-session-title),
+ *   so it is a real loss — but ordering it requires dsh to await the dispatch,
+ *   not a plugin-side workaround.
+ * - `session-telemetry/record` — `dsh-session-telemetry` returns the record
+ *   straight out of the waterfall and hands it to the backend, so a Promise
+ *   would be emitted as a record: silent corruption, no error anywhere.
+ * - `compaction/summary-error` — `dsh-compaction-basic` dispatches it as
+ *   `recover: (…) => this.ctx.waterfall(this, "compaction/summary-error", …, () => false)`
+ *   (no await) and consumes the boolean synchronously in
+ *   `if (!dependencies.recover(error, agent, prepared.shadowedSeqs, signal)) throw error`.
+ *   A Promise is always truthy, so `!recover(…)` is always false and every
+ *   summarizer failure is swallowed instead of rethrown — the compaction then
+ *   proceeds as if recovery had succeeded.
+ *
+ * Override per profile with `syncReturnHooks` once the host awaits one of them.
+ */
+export const DEFAULT_SYNC_RETURN_HOOKS: readonly string[] = [
+  'llm/stream',
+  'session-telemetry/record',
+  'compaction/summary-error',
+]
+
+/** The dsh serial hook controlled by default. */
+export const DEFAULT_SERIAL_HOOKS: readonly string[] = ['agent/turn-stopping']
+
+/** Plugin config. */
+export interface Config {
+  /**
+   * Waterfall hooks to control. Defaults to {@link DEFAULT_WATERFALL_HOOKS}.
+   * Pass `[]` to disable the waterfall service entirely.
+   */
+  hooks?: readonly string[]
+  /**
+   * Serial hooks to control. Defaults to {@link DEFAULT_SERIAL_HOOKS}.
+   * Pass `[]` to disable the serial service entirely.
+   */
+  serialHooks?: readonly string[]
+  /**
+   * Hooks whose return value the host consumes without awaiting, and which must
+   * therefore refuse participants. Defaults to {@link DEFAULT_SYNC_RETURN_HOOKS}.
+   * Pass `[]` — or a set without a given hook — to opt in to ordering it, once
+   * the host awaits that dispatch.
+   */
+  syncReturnHooks?: readonly string[]
+  /** When set, the constraint DAG (JSON) is logged to this file on every change. */
+  log?: string
+}
+
+/**
+ * Mount {@link HookOrdering} and/or {@link SerialHookOrdering} and control the
+ * configured hooks once the services are active.
+ *
+ * `config` may be `null`, and that is the ordinary case rather than an edge
+ * case: a loader row whose `config:` key is followed only by comments parses as
+ * YAML null, and a default parameter covers `undefined` but not `null`. This
+ * package's own `cordis.patch.yml` is written exactly that way — every option
+ * commented out — so a null config must mean "all defaults", not a crash.
+ *
+ * The row is the *composition* layer of the settings namespace: the Settings
+ * page edits a user layer over it, and a namespace the user has not touched
+ * resolves back to this row (or to the built-in defaults). Without a settings
+ * provider — plain Cordis — the row is the whole answer.
+ *
+ * @param ctx - the Cordis context.
+ * @param config - which hooks to control and an optional DAG `log` file; null means all defaults.
+ */
+export function apply(ctx: Context, config: Config | null = {}): void {
+  const row = config ?? {}
+  const base: HooksOrderingSettings = {
+    hooks: row.hooks ?? DEFAULT_WATERFALL_HOOKS,
+    serialHooks: row.serialHooks ?? DEFAULT_SERIAL_HOOKS,
+    log: row.log ?? '',
+  }
+  const { hooks, serialHooks, log } = resolveSettings(ctx, base) ?? base
+  const serviceConfig = log === '' ? {} : { log }
+  // Not part of the settings namespace: the sync-return list describes the
+  // HOST's dispatch, not a user preference, so it is composition (row) only.
+  const syncReturnHooks = row.syncReturnHooks ?? DEFAULT_SYNC_RETURN_HOOKS
+
+  const deps: string[] = []
+  if (hooks.length > 0) {
+    ctx.plugin(HookOrdering, { ...serviceConfig, syncReturnHooks })
+    deps.push('hooksOrdering')
+  }
+  if (serialHooks.length > 0) {
+    ctx.plugin(SerialHookOrdering, serviceConfig)
+    deps.push('serialHooksOrdering')
+  }
+  if (deps.length === 0) return
+
+  // The services activate asynchronously; control the hooks once they exist.
+  ctx.inject(deps, (ready) => {
+    for (const hook of hooks) ready.hooksOrdering.control(hook)
+    for (const hook of serialHooks) ready.serialHooksOrdering.control(hook)
+  })
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * `dsh-hooks-ordering` — deterministic before/after ordering for Cordis
+ * hooks whose participants are contributed by independent, mutually-unaware
+ * plugins.
+ *
+ * This is the public barrel: it re-exports the whole surface and nothing else.
+ * The implementations live in focused modules:
+ *
+ * - `./topo-sort` — the pure, zero-dependency stable topological sort.
+ * - `./dag` — JSON rendering of the constraint graph.
+ * - `./service-base` — coordinator machinery shared by both services.
+ * - `./waterfall` — {@link HookOrdering}, for `waterfall` hooks (the default export).
+ * - `./serial` — {@link SerialHookOrdering}, for `serial` hooks.
+ * - `./dsh` — the DeepSeek-Harness layer (separate entry point).
+ *
+ * @module dsh-hooks-ordering
+ */
+
+// Pure ordering algebra.
+export { DuplicateNameError, type Orderable, OrderingCycleError, topoSort } from './topo-sort.ts'
+
+// Constraint-graph rendering.
+export { type Dag, type DagEdge, type DagSection, type DagSectionGraph, buildDag } from './dag.ts'
+
+// Shared service machinery.
+export { HookControlError, type HookOrderingLogConfig, type Phase } from './service-base.ts'
+
+// Waterfall service.
+export { type HookEntry, type HookOrderingConfig, HookOrdering } from './waterfall.ts'
+
+// Serial service.
+export { type SerialHookEntry, type SerialHookOrderingConfig, SerialHookOrdering } from './serial.ts'
+
+// NOTE: the root entry deliberately has NO default export.
+//
+// dsh's loader normalizes an imported module with `exports.default ?? exports`
+// and only then applies it. A default export that is not the plugin therefore
+// HIJACKS the row: naming this package in `cordis.patch.yml` mounted the
+// default (`HookOrdering`) as the plugin, so the waterfall service showed up
+// while `apply` never ran — no serial service, no settings namespace, no
+// controlled hook, and no error anywhere.
+//
+// The root entry IS the dsh plugin; the library surface lives on the subpaths.
+// `HookOrdering` is still exported by name here, and `/waterfall` still carries
+// it as its default.
+export {
+  apply,
+  type Config,
+  DEFAULT_SERIAL_HOOKS,
+  DEFAULT_SYNC_RETURN_HOOKS,
+  DEFAULT_WATERFALL_HOOKS,
+  inject,
+  name,
+} from './dsh.ts'

package/src/serial.ts

@@ -0,0 +1,108 @@
+/**
+ * `SerialHookOrdering` — the serial-dispatch twin of {@link HookOrdering}.
+ *
+ * Cordis `serial` dispatch awaits listeners in registration order until one
+ * *bails* (returns a value that is not `null`/`false`/`undefined`); the bail
+ * value becomes the dispatch result and the remaining listeners never run.
+ * There is no `next()` continuation, so unlike waterfall there is no onion to
+ * wrap. This service instead brackets the hook with TWO coordinator listeners:
+ *
+ * - a `prepend`ed **front** coordinator that runs its participants ahead of
+ *   every native listener; a bail there short-circuits the whole dispatch.
+ * - an appended **back** coordinator that runs its participants best-effort
+ *   last (see the limits below).
+ *
+ * Participants register into the coordinator (not the raw hook) with
+ * `before`/`after` names and are run in a stable topological order.
+ *
+ * @module dsh-hooks-ordering/serial
+ */
+
+import { type Context, isBailed } from '@deepseek-ai/cordis'
+import { HookOrderingBase, type HookOrderingLogConfig, type Phase } from './service-base.ts'
+import { type Orderable, topoSort } from './topo-sort.ts'
+
+/**
+ * One ordered participant in a controlled serial hook phase. Unlike the
+ * waterfall entry, `run` may RETURN a value: a bail value (anything but
+ * `null`/`false`/`undefined`) short-circuits the serial dispatch.
+ * @typeParam A - the hook's payload argument tuple.
+ */
+export interface SerialHookEntry<A extends readonly unknown[] = readonly unknown[]> extends Orderable {
+  /** Run this participant with the hook payload. A bail return stops the chain. */
+  readonly run: (...args: A) => unknown | Promise<unknown>
+}
+
+/** Configuration for the {@link SerialHookOrdering} service. */
+export type SerialHookOrderingConfig = HookOrderingLogConfig
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    serialHooksOrdering: SerialHookOrdering
+  }
+}
+
+/**
+ * Coordinator service registered at `ctx.serialHooksOrdering`. Controls any
+ * number of serial hooks; each owns a prepended front coordinator, an appended
+ * back coordinator, and two ordered participant lists.
+ */
+export class SerialHookOrdering extends HookOrderingBase<SerialHookEntry> {
+  /**
+   * @param ctx - the Cordis context to register the service in.
+   * @param config - optional `log` file for the constraint DAG (JSON); `null` means defaults.
+   */
+  constructor(ctx: Context, config: SerialHookOrderingConfig | null = {}) {
+    super(ctx, 'serialHooksOrdering', config)
+  }
+
+  /**
+   * Install the two coordinator listeners. The front one is prepended so it
+   * runs ahead of the native chain; the back one is appended so it runs after
+   * the listeners present at control time. Both are effects on this service's
+   * fiber; the returned disposer removes both.
+   */
+  protected install(hook: string, front: SerialHookEntry[], back: SerialHookEntry[]): () => void {
+    const frontCoordinator = (...args: unknown[]): Promise<unknown> => runSerialPhase(front, args)
+    const backCoordinator = (...args: unknown[]): Promise<unknown> => runSerialPhase(back, args)
+    const removeFront = this.ctx.on(hook as never, frontCoordinator as never, { prepend: true })
+    const removeBack = this.ctx.on(hook as never, backCoordinator as never, { prepend: false })
+    return () => {
+      removeFront()
+      removeBack()
+    }
+  }
+
+  /**
+   * Register a participant into a controlled hook phase.
+   *
+   * @param hook - the controlled serial event name.
+   * @param phase - `front` to run ahead of the native chain, `back` best-effort last.
+   * @param entry - the participant; its `run` may return a bail value to short-circuit.
+   * @returns a disposer that unregisters this participant.
+   * @throws {HookControlError} when the hook has not been {@link control}led.
+   */
+  register<A extends readonly unknown[] = readonly unknown[]>(
+    hook: string,
+    phase: Phase,
+    entry: SerialHookEntry<A>,
+  ): () => void {
+    return this.registerEntry(hook, phase, entry as unknown as SerialHookEntry)
+  }
+}
+
+/**
+ * Run one phase's participants in stable topological order, awaiting each,
+ * until one bails.
+ * @param entries - the phase's registered participants.
+ * @param payload - the hook payload passed to each `run` callback.
+ * @returns the first bail value, or `undefined` if no participant bailed (so
+ * the serial dispatch continues to the next listener).
+ */
+async function runSerialPhase(entries: readonly SerialHookEntry[], payload: readonly unknown[]): Promise<unknown> {
+  for (const entry of topoSort(entries)) {
+    const result = await entry.run(...payload)
+    if (isBailed(result)) return result
+  }
+  return undefined
+}