dsh-attention-router

Author: jetpan (npm) ↔ jerentpan-lab (GitHub) | npm package | GitHub repo | install from GitHub: dsh plugin --profile web add github:jerentpan-lab/dsh-attention-router

Stop agents from over-notifying. Classify every event into one of three tiers and route it:

tier	meaning	action
alert	fault, failure, data loss, rollback trigger	deliver now
decide	requires a human decision (approval, deletion, production change)	queue for review
inform	completed work, records, metrics	log only (silent)

This is the "attention is the bottleneck" pattern: agents should only interrupt a human for alerts and decisions, not for every completed step.

Install

dsh plugin --profile web add dsh-attention-router

Tools

• notify_classify — classify text, return { tier, matched, action, notify }
• notify_policy — show current policy and rule counts

Config (0.2.0)

{
  "rules": { "alert": ["lookup failure"], "decide": ["approve this"] },
  "rulesFile": "~/.dsh/attention-rules.json",
  "rulesFileWatch": true,
  "policy": { "notifyInform": false },
  "fallbackTier": "decide",
  "dedupe": { "cooldownMs": 60000, "stateFile": "~/.dsh/attention-dedupe.json", "maxEntries": 1000 }
}

• rulesFile: external JSON rules ({alert?: string[], decide?: string[], inform?: string[]}); missing file falls back to defaults with a warning; rulesFileWatch: true hot-reloads on change.
• dedupe.stateFile: persists cooldown state across restarts (atomic write; corrupt state is quarantined with a warning).
• Unknown keys, unknown tiers and invalid values throw a readable ConfigError.
• Example: config.example.json. Run npm run verify for tests + pack-content/size/safety checks.

Demo

node examples/demo.mjs

Bench

node bench/bench.mjs writes bench/RESULTS.md (this host: 1000 classify p50 ≈ 19.8ms, 10000 ≈ 184.9ms).

Troubleshooting (error table)

Symptom	Cause	Fix
ConfigError ... unknown key	typo/unsupported config key	use keys from config.example.json
ConfigError ... rules.<tier>	tier not alert/decide/inform	fix tier name
ConfigError ... dedupe.cooldownMs	negative/NaN number	use a finite number >= 0
rulesFile not found warning	external rules path missing	keep defaults or fix path
rulesFile: invalid JSON	malformed rule file	validate JSON
dedupe state unreadable warning	state file corrupt	it is ignored; delete it to reset
rule conflict warning	same literal in multiple tiers	keep the pattern in one tier only

Verify

npm run verify   # unit tests + npm pack content/size/safety checks

License

MIT