dsh-ssh-hub 0.0.0-stage → 0.2.0

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 (133) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +271 -2
  3. package/cordis.patch.yml +16 -0
  4. package/icon.svg +3 -0
  5. package/lib/client.js +13975 -0
  6. package/lib/index.js +6908 -0
  7. package/lib/types/activity/history.d.ts +50 -0
  8. package/lib/types/alerting/notify.d.ts +89 -0
  9. package/lib/types/alerting/prompt-summary.d.ts +28 -0
  10. package/lib/types/alerting/rules.d.ts +135 -0
  11. package/lib/types/alerting/tools.d.ts +30 -0
  12. package/lib/types/audit/audit-log.d.ts +84 -0
  13. package/lib/types/audit/recorder.d.ts +50 -0
  14. package/lib/types/client/api.d.ts +222 -0
  15. package/lib/types/client/index.d.ts +45 -0
  16. package/lib/types/client/locales.d.ts +319 -0
  17. package/lib/types/client/native-panel.d.ts +70 -0
  18. package/lib/types/client/panel/ClusterTab.d.ts +7 -0
  19. package/lib/types/client/panel/DeployTab.d.ts +10 -0
  20. package/lib/types/client/panel/FleetTab.d.ts +10 -0
  21. package/lib/types/client/panel/HostFormDialog.d.ts +12 -0
  22. package/lib/types/client/panel/HostsTab.d.ts +25 -0
  23. package/lib/types/client/panel/LogsTab.d.ts +10 -0
  24. package/lib/types/client/panel/SshPanel.d.ts +14 -0
  25. package/lib/types/client/panel/TerminalTab.d.ts +27 -0
  26. package/lib/types/client/panel/TransferTab.d.ts +7 -0
  27. package/lib/types/client/panel/TunnelEditDialog.d.ts +15 -0
  28. package/lib/types/client/panel/TunnelsTab.d.ts +27 -0
  29. package/lib/types/client/panel/controller.d.ts +253 -0
  30. package/lib/types/client/panel/helpers.d.ts +45 -0
  31. package/lib/types/client/panel/tabs.d.ts +62 -0
  32. package/lib/types/client/panel/xterm.css.d.ts +2 -0
  33. package/lib/types/client/settings-binding.d.ts +71 -0
  34. package/lib/types/deploy/orchestrator.d.ts +158 -0
  35. package/lib/types/deploy/tools.d.ts +14 -0
  36. package/lib/types/dsh-home.d.ts +16 -0
  37. package/lib/types/engine/cluster.d.ts +19 -0
  38. package/lib/types/engine/connection-pool.d.ts +183 -0
  39. package/lib/types/engine/proxy-command.d.ts +36 -0
  40. package/lib/types/engine/pty.d.ts +32 -0
  41. package/lib/types/engine/sftp.d.ts +20 -0
  42. package/lib/types/engine/terminal-sessions.d.ts +67 -0
  43. package/lib/types/engine/tunnel-discovery.d.ts +89 -0
  44. package/lib/types/engine/tunnel-remarks.d.ts +49 -0
  45. package/lib/types/engine/tunnel.d.ts +76 -0
  46. package/lib/types/engine.d.ts +103 -0
  47. package/lib/types/http.d.ts +59 -0
  48. package/lib/types/index.d.ts +128 -0
  49. package/lib/types/inspect/checks.d.ts +118 -0
  50. package/lib/types/inspect/inspection.d.ts +111 -0
  51. package/lib/types/inspect/tools.d.ts +50 -0
  52. package/lib/types/logs/search.d.ts +131 -0
  53. package/lib/types/logs/tools.d.ts +6 -0
  54. package/lib/types/loopback.d.ts +64 -0
  55. package/lib/types/monitor/loop.d.ts +133 -0
  56. package/lib/types/monitor/metrics.d.ts +151 -0
  57. package/lib/types/mount-once.d.ts +55 -0
  58. package/lib/types/protocol.d.ts +524 -0
  59. package/lib/types/routes.d.ts +82 -0
  60. package/lib/types/security/known-hosts.d.ts +153 -0
  61. package/lib/types/security/master-secret.d.ts +157 -0
  62. package/lib/types/security/redact.d.ts +44 -0
  63. package/lib/types/security/secrets.d.ts +70 -0
  64. package/lib/types/ssh-config.d.ts +42 -0
  65. package/lib/types/store.d.ts +183 -0
  66. package/lib/types/tool-surface.d.ts +72 -0
  67. package/lib/types/tools.d.ts +56 -0
  68. package/locale/en.json +6 -0
  69. package/locale/zh.json +6 -0
  70. package/package.json +126 -6
  71. package/src/activity/history.ts +117 -0
  72. package/src/alerting/notify.ts +212 -0
  73. package/src/alerting/prompt-summary.ts +71 -0
  74. package/src/alerting/rules.ts +281 -0
  75. package/src/alerting/tools.ts +263 -0
  76. package/src/audit/audit-log.ts +199 -0
  77. package/src/audit/recorder.ts +73 -0
  78. package/src/client/api.ts +782 -0
  79. package/src/client/css-modules.d.ts +5 -0
  80. package/src/client/index.ts +150 -0
  81. package/src/client/locales.ts +654 -0
  82. package/src/client/native-panel.tsx +141 -0
  83. package/src/client/panel/ClusterTab.tsx +141 -0
  84. package/src/client/panel/DeployTab.tsx +314 -0
  85. package/src/client/panel/FleetTab.tsx +494 -0
  86. package/src/client/panel/HostFormDialog.tsx +289 -0
  87. package/src/client/panel/HostsTab.tsx +395 -0
  88. package/src/client/panel/LogsTab.tsx +208 -0
  89. package/src/client/panel/SshPanel.tsx +105 -0
  90. package/src/client/panel/TerminalTab.tsx +550 -0
  91. package/src/client/panel/TransferTab.tsx +238 -0
  92. package/src/client/panel/TunnelEditDialog.tsx +174 -0
  93. package/src/client/panel/TunnelsTab.tsx +328 -0
  94. package/src/client/panel/controller.ts +507 -0
  95. package/src/client/panel/helpers.ts +84 -0
  96. package/src/client/panel/panel.module.css +1734 -0
  97. package/src/client/panel/tabs.ts +52 -0
  98. package/src/client/panel/xterm.css.ts +2 -0
  99. package/src/client/settings-binding.ts +184 -0
  100. package/src/deploy/orchestrator.ts +326 -0
  101. package/src/deploy/tools.ts +225 -0
  102. package/src/dsh-home.ts +42 -0
  103. package/src/engine/cluster.ts +60 -0
  104. package/src/engine/connection-pool.ts +721 -0
  105. package/src/engine/proxy-command.ts +248 -0
  106. package/src/engine/pty.ts +78 -0
  107. package/src/engine/sftp.ts +229 -0
  108. package/src/engine/terminal-sessions.ts +280 -0
  109. package/src/engine/tunnel-discovery.ts +353 -0
  110. package/src/engine/tunnel-remarks.ts +120 -0
  111. package/src/engine/tunnel.ts +300 -0
  112. package/src/engine.ts +195 -0
  113. package/src/http.ts +127 -0
  114. package/src/index.ts +690 -0
  115. package/src/inspect/checks.ts +251 -0
  116. package/src/inspect/inspection.ts +321 -0
  117. package/src/inspect/tools.ts +366 -0
  118. package/src/logs/search.ts +251 -0
  119. package/src/logs/tools.ts +160 -0
  120. package/src/loopback.ts +119 -0
  121. package/src/monitor/loop.ts +265 -0
  122. package/src/monitor/metrics.ts +333 -0
  123. package/src/mount-once.ts +142 -0
  124. package/src/protocol.ts +534 -0
  125. package/src/routes.ts +998 -0
  126. package/src/security/known-hosts.ts +342 -0
  127. package/src/security/master-secret.ts +334 -0
  128. package/src/security/redact.ts +119 -0
  129. package/src/security/secrets.ts +152 -0
  130. package/src/ssh-config.ts +182 -0
  131. package/src/store.ts +757 -0
  132. package/src/tool-surface.ts +96 -0
  133. package/src/tools.ts +550 -0
@@ -0,0 +1,281 @@
1
+ /**
2
+ * Alert rule engine.
3
+ *
4
+ * The state machine here is deliberately conservative, because the failure
5
+ * mode of a monitoring tool is a crying wolf, and a crying wolf gets
6
+ * muted — at which point the tool is worthless.
7
+ *
8
+ * Three rules carry that conservatism:
9
+ *
10
+ * 1. **Consecutive rounds.** A breach must persist for N consecutive
11
+ * rounds before it fires. One spike is noise; a trend is a problem.
12
+ * The operator expresses the requirement in seconds ("3 minutes")
13
+ * and the engine converts it using the poll interval.
14
+ *
15
+ * 2. **null freezes the state.** When a probe cannot read a value (the
16
+ * host timed out, the command failed), the alert state is FROZEN, not
17
+ * cleared. A monitoring probe that goes blind must not report
18
+ * "recovered" — that is how a dead machine ends up looking healthy.
19
+ *
20
+ * 3. **Cooldown blocks re-entry, not recovery.** While an alert is
21
+ * cooling down, a continued breach does not re-notify. But when the
22
+ * value comes back under the threshold, the recovery is ALWAYS
23
+ * notified — an operator who was told "disk full" and never told
24
+ * "disk fine" still has a page open.
25
+ */
26
+
27
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
28
+ import { dirname, join } from 'node:path'
29
+ import { dshHome } from '../dsh-home.ts'
30
+ import type { CheckResult } from '../inspect/checks.ts'
31
+
32
+ /** The lifecycle state of one alert. */
33
+ export type AlertState =
34
+ /** Healthy: under the threshold. */
35
+ | 'ok'
36
+ /** Breaching, but not yet for long enough to fire. */
37
+ | 'pending'
38
+ /** Breaching and fired. */
39
+ | 'firing'
40
+ /** The value could not be read; the previous state is held. */
41
+ | 'frozen'
42
+
43
+ /** One alert rule. */
44
+ export interface AlertRule {
45
+ /** Stable identifier. */
46
+ id: string
47
+ /** The check this rule watches. */
48
+ checkId: string
49
+ /** Which hosts it covers (empty means every host). */
50
+ hosts?: string[]
51
+ /** How long the breach must persist before it fires, in seconds. */
52
+ forSeconds: number
53
+ /** How long to wait before re-notifying a continued breach, in seconds. */
54
+ cooldownSeconds: number
55
+ /** Whether the rule is active. */
56
+ enabled: boolean
57
+ }
58
+
59
+ /** The persisted state of one (rule, host) pair. */
60
+ export interface AlertState_ {
61
+ /** The current state. */
62
+ state: AlertState
63
+ /**
64
+ * The state held across a blackout.
65
+ *
66
+ * While the probe is blind the state is 'frozen'; this keeps the
67
+ * pre-blackout state so the recovery that follows it is still reported.
68
+ */
69
+ heldState?: 'pending' | 'firing'
70
+ /** Consecutive breaching rounds so far. */
71
+ consecutiveBreaches: number
72
+ /** When the current breach streak started (epoch ms). */
73
+ breachStartedAt?: number
74
+ /** When the alert last fired (epoch ms). */
75
+ lastFiredAt?: number
76
+ /** The value that last fired it. */
77
+ lastValue?: number | boolean | string | null
78
+ }
79
+
80
+ /** A notification the engine wants to send. */
81
+ export interface AlertNotification {
82
+ /** The rule id. */
83
+ ruleId: string
84
+ /** The host alias. */
85
+ alias: string
86
+ /** 'trigger' for a new breach, 'recover' for a recovery. */
87
+ kind: 'trigger' | 'recover'
88
+ /** The check title. */
89
+ title: string
90
+ /** The value that breached (or returned to normal). */
91
+ value: string
92
+ /** When the event happened. */
93
+ at: number
94
+ }
95
+
96
+ /** The engine's persisted state file. */
97
+ export function alertStatePath(): string {
98
+ return join(dshHome(), 'dsh-ssh-hub', 'alerts.json')
99
+ }
100
+
101
+ /**
102
+ * The alert state machine.
103
+ *
104
+ * One instance per plugin apply. The state survives a restart, so an alert
105
+ * that was firing when DSH stopped is still firing when it comes back.
106
+ */
107
+ export class AlertEngine {
108
+ /** The state file. */
109
+ readonly path: string
110
+ /** The state, keyed by `ruleId|alias`. */
111
+ private states = new Map<string, AlertState_>()
112
+
113
+ constructor(path?: string) {
114
+ this.path = path ?? alertStatePath()
115
+ this.load()
116
+ }
117
+
118
+ /**
119
+ * Evaluate one round of inspection results against the rules.
120
+ *
121
+ * @param rules - the rules to apply.
122
+ * @param results - the round's results.
123
+ * @param pollIntervalMs - the poll interval, used to convert the rule's
124
+ * "for" duration into a number of consecutive rounds.
125
+ * @returns the notifications to send.
126
+ */
127
+ evaluate(rules: AlertRule[], results: CheckResult[], pollIntervalMs: number): AlertNotification[] {
128
+ const notifications: AlertNotification[] = []
129
+ const now = Date.now()
130
+ for (const rule of rules) {
131
+ if (!rule.enabled) continue
132
+ const relevant = results.filter(result =>
133
+ result.checkId === rule.checkId
134
+ && (rule.hosts === undefined || rule.hosts.length === 0 || rule.hosts.includes(result.alias)),
135
+ )
136
+ for (const result of relevant) {
137
+ const notification = this.evaluateOne(rule, result, pollIntervalMs, now)
138
+ if (notification !== undefined) notifications.push(notification)
139
+ }
140
+ }
141
+ this.save()
142
+ return notifications
143
+ }
144
+
145
+ /**
146
+ * Evaluate one result against one rule.
147
+ *
148
+ * @param rule - the rule.
149
+ * @param result - the check result.
150
+ * @param pollIntervalMs - the poll interval.
151
+ * @param now - the current time.
152
+ * @returns a notification when the state changed in a way that must be
153
+ * reported, otherwise undefined.
154
+ */
155
+ private evaluateOne(
156
+ rule: AlertRule,
157
+ result: CheckResult,
158
+ pollIntervalMs: number,
159
+ now: number,
160
+ ): AlertNotification | undefined {
161
+ const key = `${rule.id}|${result.alias}`
162
+ const previous = this.states.get(key)
163
+ const state: AlertState_ = previous ?? {
164
+ state: 'ok',
165
+ consecutiveBreaches: 0,
166
+ }
167
+
168
+ // An unreadable value freezes the state: the previous state is held,
169
+ // and NOTHING is reported. A blind probe must not report a recovery,
170
+ // and must not report a new breach either.
171
+ //
172
+ // The held state is remembered separately: `state` becomes 'frozen' so
173
+ // the operator can see the probe is blind, but the pre-blackout state
174
+ // is kept — otherwise the real recovery that follows the blackout
175
+ // would go unreported and the operator would never learn the machine
176
+ // came back.
177
+ if (result.value === null) {
178
+ if (state.state !== 'frozen' && (state.state === 'firing' || state.state === 'pending')) {
179
+ state.heldState = state.state
180
+ }
181
+ state.state = 'frozen'
182
+ this.states.set(key, state)
183
+ return undefined
184
+ }
185
+
186
+ if (!result.breached) {
187
+ // The value is readable and healthy: a recovery, if we were firing.
188
+ // The held state counts: a blackout between the breach and the
189
+ // recovery must not swallow the recovery notification.
190
+ const wasFiring = state.state === 'firing' || state.heldState === 'firing'
191
+ state.state = 'ok'
192
+ state.heldState = undefined
193
+ state.consecutiveBreaches = 0
194
+ state.breachStartedAt = undefined
195
+ state.lastValue = result.value
196
+ this.states.set(key, state)
197
+ // Recovery is ALWAYS reported - the cooldown never suppresses it.
198
+ if (wasFiring) {
199
+ return {
200
+ ruleId: rule.id,
201
+ alias: result.alias,
202
+ kind: 'recover',
203
+ title: result.checkId,
204
+ value: String(result.value),
205
+ at: now,
206
+ }
207
+ }
208
+ // A pending breach that cleared before firing is not an event.
209
+ return undefined
210
+ }
211
+
212
+ // The value breaches.
213
+ state.consecutiveBreaches += 1
214
+ if (state.breachStartedAt === undefined) state.breachStartedAt = now
215
+ state.lastValue = result.value
216
+
217
+ const requiredRounds = Math.max(1, Math.ceil((rule.forSeconds * 1000) / Math.max(pollIntervalMs, 1)))
218
+ if (state.consecutiveBreaches < requiredRounds) {
219
+ // Still inside the "for" window: pending, not firing.
220
+ state.state = 'pending'
221
+ this.states.set(key, state)
222
+ return undefined
223
+ }
224
+
225
+ const wasFiring = state.state === 'firing'
226
+ state.state = 'firing'
227
+ this.states.set(key, state)
228
+ if (wasFiring) {
229
+ // A continued breach: only re-notify after the cooldown.
230
+ const elapsed = state.lastFiredAt === undefined ? Infinity : now - state.lastFiredAt
231
+ if (elapsed < rule.cooldownSeconds * 1000) return undefined
232
+ }
233
+ state.lastFiredAt = now
234
+ return {
235
+ ruleId: rule.id,
236
+ alias: result.alias,
237
+ kind: 'trigger',
238
+ title: result.checkId,
239
+ value: String(result.value),
240
+ at: now,
241
+ }
242
+ }
243
+
244
+ /**
245
+ * The current state of every (rule, host) pair.
246
+ *
247
+ * @returns the states.
248
+ */
249
+ list(): Array<{ ruleId: string; alias: string } & AlertState_> {
250
+ const result: Array<{ ruleId: string; alias: string } & AlertState_> = []
251
+ for (const [key, state] of this.states) {
252
+ const [ruleId, alias] = key.split('|')
253
+ if (ruleId === undefined || alias === undefined) continue
254
+ result.push({ ruleId, alias, ...state })
255
+ }
256
+ return result
257
+ }
258
+
259
+ /** Load the persisted state. */
260
+ private load(): void {
261
+ if (!existsSync(this.path)) return
262
+ try {
263
+ const parsed = JSON.parse(readFileSync(this.path, 'utf8')) as Record<string, AlertState_>
264
+ if (typeof parsed !== 'object' || parsed === null) return
265
+ for (const [key, state] of Object.entries(parsed)) {
266
+ if (typeof state === 'object' && state !== null) this.states.set(key, state)
267
+ }
268
+ } catch {
269
+ // A corrupt state file must not brick the plugin; start clean.
270
+ }
271
+ }
272
+
273
+ /** Persist the state. */
274
+ private save(): void {
275
+ const dir = dirname(this.path)
276
+ if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 })
277
+ const plain: Record<string, AlertState_> = {}
278
+ for (const [key, state] of this.states) plain[key] = state
279
+ writeFileSync(this.path, JSON.stringify(plain, null, 2), { encoding: 'utf8', mode: 0o600 })
280
+ }
281
+ }
@@ -0,0 +1,263 @@
1
+ /**
2
+ * Agent tools for the alerting layer.
3
+ *
4
+ * Three tools:
5
+ * - `hub_alerts` — the current alert states and the recent events
6
+ * - `hub_alert_rules` — list and update the rules
7
+ * - `hub_alert_test` — send a test notification to the configured channels
8
+ *
9
+ * The test tool matters more than it looks: an operator who configured a
10
+ * webhook and never received a message does not know whether the rule
11
+ * never fired or the channel is broken. One call tells them.
12
+ */
13
+
14
+ import { defineTool } from '@deepseek-ai/dsh-tools'
15
+ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
16
+ import { AlertEngine, type AlertRule } from './rules.ts'
17
+ import { NOTIFY_PRESETS, notifyAll, type NotifyChannel } from './notify.ts'
18
+
19
+ /** One text content block (the only render shape these tools emit). */
20
+ function text(value: string): ContentBlock[] {
21
+ return [{ type: 'text', text: value }]
22
+ }
23
+
24
+ /** The default rule set: the checks whose thresholds matter most. */
25
+ export function defaultRules(): AlertRule[] {
26
+ return [
27
+ { id: 'disk-full', checkId: 'disk-usage', forSeconds: 120, cooldownSeconds: 1800, enabled: true },
28
+ { id: 'memory-pressure', checkId: 'memory-used', forSeconds: 180, cooldownSeconds: 1800, enabled: true },
29
+ { id: 'load-high', checkId: 'load-average', forSeconds: 300, cooldownSeconds: 1800, enabled: true },
30
+ { id: 'inodes-full', checkId: 'disk-inodes', forSeconds: 120, cooldownSeconds: 1800, enabled: true },
31
+ { id: 'sshd-down', checkId: 'sshd-running', forSeconds: 60, cooldownSeconds: 900, enabled: true },
32
+ ]
33
+ }
34
+
35
+ /** The alerts tool: the current state and the recent events. */
36
+ export function hubAlertsTool(engine: AlertEngine, events: AlertEvent[]) {
37
+ return defineTool({
38
+ name: 'hub_alerts',
39
+ description: 'Show the current fleet alert states (which rules are firing, pending, or frozen) and the most recent alert events. A frozen state means the probe could not read the value - the machine may be unreachable, which is different from healthy. Use hub_inspect to refresh the values first.',
40
+ parameters: {
41
+ limit: { type: 'integer', description: 'How many recent events to return (default 20).' },
42
+ },
43
+ output: {
44
+ schema: {
45
+ type: 'object',
46
+ additionalProperties: false,
47
+ properties: {
48
+ ok: { type: 'boolean', required: true },
49
+ states: {
50
+ type: 'array',
51
+ items: {
52
+ type: 'object',
53
+ additionalProperties: false,
54
+ properties: {
55
+ ruleId: { type: 'string', required: true },
56
+ alias: { type: 'string', required: true },
57
+ state: { type: 'string', enum: ['ok', 'pending', 'firing', 'frozen'], required: true },
58
+ consecutiveBreaches: { type: 'integer', required: true },
59
+ lastValue: { type: 'string' },
60
+ },
61
+ },
62
+ required: true,
63
+ },
64
+ events: {
65
+ type: 'array',
66
+ items: {
67
+ type: 'object',
68
+ additionalProperties: false,
69
+ properties: {
70
+ ruleId: { type: 'string', required: true },
71
+ alias: { type: 'string', required: true },
72
+ kind: { type: 'string', enum: ['trigger', 'recover'], required: true },
73
+ value: { type: 'string', required: true },
74
+ at: { type: 'integer', required: true },
75
+ },
76
+ },
77
+ required: true,
78
+ },
79
+ },
80
+ },
81
+ render: (_args, value: { ok: boolean; states: Array<{ ruleId: string; alias: string; state: string; consecutiveBreaches: number }>; events: Array<{ ruleId: string; alias: string; kind: string; value: string }> }) => {
82
+ const firing = value.states.filter(state => state.state === 'firing')
83
+ const frozen = value.states.filter(state => state.state === 'frozen')
84
+ const lines = [
85
+ `告警状态:触发 ${firing.length},冻结(探针失联)${frozen.length},共 ${value.states.length} 条`,
86
+ '',
87
+ ...firing.map(state => `${state.alias} | ${state.ruleId} | 触发中(连续 ${state.consecutiveBreaches} 轮)`),
88
+ ...frozen.map(state => `${state.alias} | ${state.ruleId} | 探针失联,状态已冻结`),
89
+ ]
90
+ if (value.events.length > 0) {
91
+ lines.push('', '最近事件:', ...value.events.map(event => `${event.alias} | ${event.ruleId} | ${event.kind === 'trigger' ? '触发' : '恢复'} | ${event.value}`))
92
+ }
93
+ return text(lines.join('\n'))
94
+ },
95
+ },
96
+ async execute(args) {
97
+ const limit = args.limit ?? 20
98
+ return {
99
+ ok: true,
100
+ states: engine.list().map(state => ({
101
+ ruleId: state.ruleId,
102
+ alias: state.alias,
103
+ state: state.state,
104
+ consecutiveBreaches: state.consecutiveBreaches,
105
+ ...(state.lastValue !== undefined ? { lastValue: String(state.lastValue) } : {}),
106
+ })),
107
+ events: events.slice(-limit).map(event => ({
108
+ ruleId: event.ruleId,
109
+ alias: event.alias,
110
+ kind: event.kind,
111
+ value: event.value,
112
+ at: event.at,
113
+ })),
114
+ }
115
+ },
116
+ })
117
+ }
118
+
119
+ /** The rules tool: list and update the rules. */
120
+ export function hubAlertRulesTool(rules: AlertRule[]) {
121
+ return defineTool({
122
+ name: 'hub_alert_rules',
123
+ description: 'List the fleet alert rules, or enable/disable one, or change how long a breach must persist before it fires. A rule needs the breach to hold for the "for" seconds across consecutive rounds before it fires, so a one-off spike does not page the operator.',
124
+ parameters: {
125
+ action: { type: 'string', enum: ['list', 'set'], required: true },
126
+ id: { type: 'string', description: 'The rule id (required for set).' },
127
+ enabled: { type: 'boolean', description: 'Enable or disable the rule.' },
128
+ forSeconds: { type: 'integer', description: 'How many seconds the breach must persist before the alert fires.' },
129
+ cooldownSeconds: { type: 'integer', description: 'How long to wait before re-notifying a continued breach.' },
130
+ },
131
+ output: {
132
+ schema: {
133
+ type: 'object',
134
+ additionalProperties: false,
135
+ properties: {
136
+ ok: { type: 'boolean', required: true },
137
+ rules: {
138
+ type: 'array',
139
+ items: {
140
+ type: 'object',
141
+ additionalProperties: false,
142
+ properties: {
143
+ id: { type: 'string', required: true },
144
+ checkId: { type: 'string', required: true },
145
+ forSeconds: { type: 'integer', required: true },
146
+ cooldownSeconds: { type: 'integer', required: true },
147
+ enabled: { type: 'boolean', required: true },
148
+ },
149
+ },
150
+ required: true,
151
+ },
152
+ error: { type: 'string' },
153
+ },
154
+ },
155
+ render: (_args, value: { ok: boolean; rules: Array<{ id: string; checkId: string; forSeconds: number; cooldownSeconds: number; enabled: boolean }>; error?: string }) => {
156
+ if (value.error !== undefined) return text(`rule error: ${value.error}`)
157
+ const lines = ['规则 | 检查项 | 持续 | 冷却 | 状态', '--- | --- | --- | --- | ---']
158
+ for (const rule of value.rules) {
159
+ lines.push(`${rule.id} | ${rule.checkId} | ${rule.forSeconds}s | ${rule.cooldownSeconds}s | ${rule.enabled ? '启用' : '停用'}`)
160
+ }
161
+ return text(lines.join('\n'))
162
+ },
163
+ },
164
+ async execute(args) {
165
+ if (args.action === 'list') {
166
+ return { ok: true, rules: rules.map(project) }
167
+ }
168
+ const rule = rules.find(candidate => candidate.id === args.id)
169
+ if (rule === undefined) {
170
+ return { ok: false, rules: rules.map(project), error: `unknown rule '${args.id ?? ''}'` }
171
+ }
172
+ if (args.enabled !== undefined) rule.enabled = args.enabled
173
+ if (args.forSeconds !== undefined) rule.forSeconds = Math.max(0, args.forSeconds)
174
+ if (args.cooldownSeconds !== undefined) rule.cooldownSeconds = Math.max(0, args.cooldownSeconds)
175
+ return { ok: true, rules: rules.map(project) }
176
+ },
177
+ })
178
+ }
179
+
180
+ /** The notification test tool. */
181
+ export function hubAlertTestTool(channels: NotifyChannel[]) {
182
+ return defineTool({
183
+ name: 'hub_alert_test',
184
+ description: 'Send a test notification through the configured alert channels and report the delivery result. Use this to verify a webhook works before relying on it - an operator who never received a message cannot tell a silent rule from a broken channel. Also lists the built-in channel presets.',
185
+ parameters: {},
186
+ output: {
187
+ schema: {
188
+ type: 'object',
189
+ additionalProperties: false,
190
+ properties: {
191
+ ok: { type: 'boolean', required: true },
192
+ outcomes: {
193
+ type: 'array',
194
+ items: {
195
+ type: 'object',
196
+ additionalProperties: false,
197
+ properties: {
198
+ channelId: { type: 'string', required: true },
199
+ ok: { type: 'boolean', required: true },
200
+ status: { type: 'integer' },
201
+ error: { type: 'string' },
202
+ },
203
+ },
204
+ required: true,
205
+ },
206
+ presets: { type: 'array', items: { type: 'string' } },
207
+ message: { type: 'string' },
208
+ },
209
+ },
210
+ render: (_args, value: { ok: boolean; outcomes: Array<{ channelId: string; ok: boolean; status?: number; error?: string }>; presets: string[]; message?: string }) => {
211
+ const lines = [`测试通知已发送(${value.outcomes.length} 个渠道):`]
212
+ for (const outcome of value.outcomes) {
213
+ lines.push(outcome.ok
214
+ ? `${outcome.channelId}: 成功${outcome.status !== undefined ? `(HTTP ${outcome.status})` : ''}`
215
+ : `${outcome.channelId}: 失败 - ${outcome.error ?? '未知错误'}`)
216
+ }
217
+ if (value.outcomes.length === 0) lines.push('(未配置任何通知渠道)')
218
+ lines.push('', `可用预设:${value.presets.join(', ')}`)
219
+ return text(lines.join('\n'))
220
+ },
221
+ },
222
+ async execute() {
223
+ const outcomes = await notifyAll(channels, {
224
+ ruleId: 'test',
225
+ alias: 'test-host',
226
+ kind: 'trigger',
227
+ title: 'test',
228
+ value: '1',
229
+ at: Date.now(),
230
+ }, { message: '这是来自 dsh-ssh-hub 的测试通知(收到即表示通道正常)。' })
231
+ return {
232
+ ok: outcomes.every(outcome => outcome.ok),
233
+ outcomes: outcomes.map(outcome => ({
234
+ channelId: outcome.channelId,
235
+ ok: outcome.ok,
236
+ ...(outcome.status !== undefined ? { status: outcome.status } : {}),
237
+ ...(outcome.error !== undefined ? { error: outcome.error } : {}),
238
+ })),
239
+ presets: NOTIFY_PRESETS.map(preset => preset.id),
240
+ }
241
+ },
242
+ })
243
+ }
244
+
245
+ /** One alert event, as the tools see it. */
246
+ export interface AlertEvent {
247
+ ruleId: string
248
+ alias: string
249
+ kind: 'trigger' | 'recover'
250
+ value: string
251
+ at: number
252
+ }
253
+
254
+ /** Project a rule onto its public shape. */
255
+ function project(rule: AlertRule): { id: string; checkId: string; forSeconds: number; cooldownSeconds: number; enabled: boolean } {
256
+ return {
257
+ id: rule.id,
258
+ checkId: rule.checkId,
259
+ forSeconds: rule.forSeconds,
260
+ cooldownSeconds: rule.cooldownSeconds,
261
+ enabled: rule.enabled,
262
+ }
263
+ }