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,111 @@
1
+ /**
2
+ * Inspection runner and result retention.
3
+ *
4
+ * Runs the built-in checks across a selected set of hosts (reusing the
5
+ * engine's pool, so no extra connections are opened), stores each round as
6
+ * a JSON Lines record, and answers "what changed since last time".
7
+ *
8
+ * The comparison is the point: a raw dump of "disk 71%" says nothing, while
9
+ * "disk 71% (was 42% an hour ago)" says the fleet is filling up. Every round
10
+ * is therefore retained, and the diff is computed from the two newest
11
+ * rounds by default.
12
+ */
13
+ import type { SshEngine } from '../engine.ts';
14
+ import { type Check, type CheckResult } from './checks.ts';
15
+ /**
16
+ * How many hosts one inspection round works on at a time.
17
+ *
18
+ * Chosen to finish a 50-host sweep inside the default 60-second interval while
19
+ * keeping the number of simultaneously open SSH connections in the same range
20
+ * the connection pool already uses for other fan-out (8). Raising it trades
21
+ * sockets for wall clock; lowering it risks a round that outlasts its own
22
+ * timer and reports "上一轮尚未结束" instead of a result.
23
+ */
24
+ export declare const DEFAULT_INSPECT_CONCURRENCY = 8;
25
+ /** One inspection round. */
26
+ export interface InspectionRound {
27
+ /** Epoch milliseconds when the round started. */
28
+ startedAt: number;
29
+ /** How long the round took. */
30
+ durationMs: number;
31
+ /** The hosts covered. */
32
+ targets: string[];
33
+ /** Every check result, flattened. */
34
+ results: CheckResult[];
35
+ }
36
+ /** One host's change between two rounds. */
37
+ export interface HostChange {
38
+ alias: string;
39
+ checkId: string;
40
+ title: string;
41
+ /** The previous display value, or undefined when the check is new. */
42
+ before?: string;
43
+ /** The current display value. */
44
+ after: string;
45
+ /** Whether the breach state changed (and in which direction). */
46
+ stateChange?: 'new-breach' | 'recovered';
47
+ }
48
+ /** The inspection history file. */
49
+ export declare function historyPath(): string;
50
+ /**
51
+ * The inspection runner.
52
+ *
53
+ * One instance per plugin apply. Holds no long-lived state beyond the file
54
+ * path: rounds are written as they complete, so a crash loses at most the
55
+ * round in flight.
56
+ */
57
+ export declare class Inspector {
58
+ /** The history file this inspector appends to. */
59
+ readonly path: string;
60
+ /** How many rounds to keep for comparison and display. */
61
+ readonly maxRounds: number;
62
+ constructor(path?: string, maxRounds?: number);
63
+ /**
64
+ * Run one round of checks.
65
+ *
66
+ * @param engine - the SSH engine (the connection pool is reused).
67
+ * @param targets - the host aliases to inspect.
68
+ * @param checkIds - which checks to run (default: all built-in checks).
69
+ * @param timeoutMs - per-command timeout.
70
+ * @returns the completed round.
71
+ */
72
+ run(engine: SshEngine, targets: string[], checkIds?: string[], timeoutMs?: number, concurrency?: number): Promise<InspectionRound>;
73
+ /**
74
+ * Append one round to the history file.
75
+ *
76
+ * @param round - the round to store.
77
+ */
78
+ append(round: InspectionRound): void;
79
+ /**
80
+ * Called after every round is durably appended.
81
+ *
82
+ * Used by the metric store to derive series from rounds, so the tiers stay
83
+ * current whether the round came from the timer or from a tool call.
84
+ */
85
+ onRound?: (round: InspectionRound) => void;
86
+ /**
87
+ * Read the most recent rounds, oldest first.
88
+ *
89
+ * @param limit - how many rounds to return.
90
+ * @returns the rounds.
91
+ */
92
+ read(limit?: number): InspectionRound[];
93
+ /**
94
+ * Compare the two newest rounds.
95
+ *
96
+ * @returns the changes, newest round against the one before it. An empty
97
+ * array means either fewer than two rounds exist or nothing changed — the
98
+ * caller distinguishes the two by looking at {@link read}.
99
+ */
100
+ diff(): HostChange[];
101
+ }
102
+ /**
103
+ * The checks selected by the given ids.
104
+ *
105
+ * An unknown id throws: silently skipping it would let a typo look like a
106
+ * clean inspection.
107
+ *
108
+ * @param checkIds - the requested ids, or undefined for all.
109
+ * @returns the checks to run.
110
+ */
111
+ export declare function selectChecks(checkIds?: string[]): readonly Check[];
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Agent tools for the inspection layer.
3
+ *
4
+ * Two tools, deliberately split by intent:
5
+ * - `hub_inspect` runs a round of checks and returns the results
6
+ * - `hub_inspect_diff` returns what changed since the previous round
7
+ *
8
+ * The split matters: "check the fleet" and "what changed since I last
9
+ * looked" are different questions, and an agent that has to re-run the
10
+ * whole fleet to answer the second one pays for it in round trips.
11
+ */
12
+ import type { SshEngine } from '../engine.ts';
13
+ import type { Inspector } from './inspection.ts';
14
+ /**
15
+ * Resolve the target hosts for an inspection.
16
+ *
17
+ * At least one selector is required, for the same reason `ssh_cluster`
18
+ * requires one: a fleet tool that silently inspects EVERY host when the
19
+ * selector is empty is a foot-gun, and an inspection is cheap but not free
20
+ * on 50 machines.
21
+ *
22
+ * @param engine - the SSH engine (the host list).
23
+ * @param aliases - explicit aliases.
24
+ * @param environment - an environment label (exact match).
25
+ * @param tags - tags that must ALL be present.
26
+ * @returns the selected aliases.
27
+ */
28
+ export declare function resolveTargets(engine: SshEngine, aliases?: string[], environment?: string, tags?: string[]): string[];
29
+ /** The inspection tool: run a round of checks. */
30
+ export declare function hubInspectTool(engine: SshEngine, inspector: Inspector): import("@deepseek-ai/dsh-tools").ToolDefinition;
31
+ /** The catalogue tool: list the available checks. */
32
+ export declare function hubInspectCatalogTool(): import("@deepseek-ai/dsh-tools").ToolDefinition;
33
+ /** The diff tool: what changed since the previous round. */
34
+ export declare function hubInspectDiffTool(inspector: Inspector): import("@deepseek-ai/dsh-tools").ToolDefinition;
35
+ /**
36
+ * The monitoring-loop tool: is the fleet being watched, and what did the
37
+ * last round see?
38
+ *
39
+ * This is separate from `hub_inspect` on purpose. `hub_inspect` *runs* a
40
+ * round; this reports on the loop that runs rounds on its own. An agent
41
+ * asked "is the fleet being monitored?" must not have to run a round to
42
+ * answer, because running a round changes the thing being asked about.
43
+ *
44
+ * @param monitor - the loop (absent when the plugin mounted without one).
45
+ * @param store - the host store, for the configured target count.
46
+ * @returns the tool definition.
47
+ */
48
+ export declare function hubMonitorTool(monitor: {
49
+ status(): Record<string, unknown>;
50
+ } | undefined): import("@deepseek-ai/dsh-tools").ToolDefinition;
@@ -0,0 +1,131 @@
1
+ /**
2
+ * Cross-host log search.
3
+ *
4
+ * The agentless way to search logs on 50 Linux machines: run a read-only
5
+ * grep over the log files on each host and aggregate the matches. No agent
6
+ * is installed on the remote side, nothing is written, and the whole thing
7
+ * is one SSH round trip per host.
8
+ *
9
+ * Two sources are supported, because a Linux fleet has both:
10
+ * - `journalctl` for the systemd journal
11
+ * - plain files under a log directory (grep over a file set)
12
+ *
13
+ * The search is BOUNDED on purpose: a grep across a fleet can return
14
+ * megabytes, which would flood the model's context. Per-host match counts
15
+ * and a global match cap keep the result readable, and the truncation is
16
+ * reported rather than hidden.
17
+ */
18
+ import type { SshEngine } from '../engine.ts';
19
+ /** Where to search. */
20
+ export type LogSource =
21
+ /** The systemd journal. */
22
+ 'journal'
23
+ /** A set of log files under a directory. */
24
+ | 'files';
25
+ /** A log search request. */
26
+ export interface LogSearchRequest {
27
+ /** The search source. */
28
+ source: LogSource;
29
+ /** The pattern to search for (a grep pattern or a journalctl match). */
30
+ pattern: string;
31
+ /** The log directory, when the source is 'files'. */
32
+ directory?: string;
33
+ /** How many lines to keep per host. */
34
+ maxLinesPerHost?: number;
35
+ /** The systemd unit to filter on, when the source is 'journal'. */
36
+ unit?: string;
37
+ /** The time window start (epoch seconds), when the source is 'journal'. */
38
+ since?: number;
39
+ /** How long the command may take per host. */
40
+ timeoutMs?: number;
41
+ /** How many hosts to search at once. */
42
+ maxWorkers?: number;
43
+ }
44
+ /** One host's search outcome. */
45
+ export interface LogHostResult {
46
+ alias: string;
47
+ ok: boolean;
48
+ /** The matching lines (bounded). */
49
+ lines: string[];
50
+ /** How many matches the host reported in total. */
51
+ totalMatches?: number;
52
+ /** Whether the output was truncated. */
53
+ truncated?: boolean;
54
+ /** The error, when the search failed. */
55
+ error?: string;
56
+ /** How long the search took on this host. */
57
+ durationMs?: number;
58
+ }
59
+ /** The outcome of a fleet-wide search. */
60
+ export interface LogSearchResult {
61
+ ok: boolean;
62
+ /** The hosts that were searched. */
63
+ targets: string[];
64
+ /** The per-host outcomes. */
65
+ results: LogHostResult[];
66
+ /** The total number of matching lines returned. */
67
+ totalLines: number;
68
+ /** Whether any host's output was truncated. */
69
+ truncated: boolean;
70
+ /** How long the whole search took. */
71
+ durationMs: number;
72
+ /** The error, when the search could not run at all. */
73
+ error?: string;
74
+ }
75
+ /**
76
+ * Build the remote command for one search.
77
+ *
78
+ * The pattern is passed as a shell argument, quoted so a pattern with
79
+ * spaces or quotes does not break the command. The pattern itself is a
80
+ * grep pattern — that is the operator's choice, and it runs on their own
81
+ * hosts.
82
+ *
83
+ * @param request - the search request.
84
+ * @returns the command to run on the remote host.
85
+ */
86
+ export declare function buildSearchCommand(request: LogSearchRequest): string;
87
+ /**
88
+ * Quote a value for a POSIX shell.
89
+ *
90
+ * @param value - the value to quote.
91
+ * @returns the quoted value.
92
+ */
93
+ export declare function shellQuote(value: string): string;
94
+ /**
95
+ * Format a "since" timestamp for journalctl.
96
+ *
97
+ * @param epochSeconds - the timestamp in seconds.
98
+ * @returns the journalctl argument.
99
+ */
100
+ export declare function formatSince(epochSeconds: number): string;
101
+ /**
102
+ * Search the logs on many hosts.
103
+ *
104
+ * @param engine - the SSH engine.
105
+ * @param request - the search request.
106
+ * @param targets - the host aliases.
107
+ * @returns the fleet-wide outcome.
108
+ */
109
+ export declare function searchLogs(engine: SshEngine, request: LogSearchRequest, targets: string[]): Promise<LogSearchResult>;
110
+ /**
111
+ * Parse the combined output of a search command.
112
+ *
113
+ * The command prints the matched lines, then the total count on the last
114
+ * line. The count line is numeric only, so it is unambiguous.
115
+ *
116
+ * @param stdout - the command output.
117
+ * @param maxLines - the per-host cap.
118
+ * @returns the lines and the total count.
119
+ */
120
+ export declare function parseSearchOutput(stdout: string, maxLines: number): {
121
+ lines: string[];
122
+ total: number;
123
+ truncated: boolean;
124
+ };
125
+ /**
126
+ * A human-readable rendering of a search outcome.
127
+ *
128
+ * @param result - the search outcome.
129
+ * @returns the report text.
130
+ */
131
+ export declare function renderLogSearch(result: LogSearchResult): string;
@@ -0,0 +1,6 @@
1
+ /**
2
+ * Agent tools for the cross-host log search.
3
+ */
4
+ import type { SshEngine } from '../engine.ts';
5
+ /** The log-search tool. */
6
+ export declare function hubLogSearchTool(engine: SshEngine): import("@deepseek-ai/dsh-tools").ToolDefinition;
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Loopback trust fence shared by the host route families: socket address,
3
+ * Host header, and browser same-origin markers. Packages receive this file as
4
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
5
+ * re-run the sync instead of editing a copy.
6
+ *
7
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
8
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
9
+ * markers (sec-fetch-site and Origin) for the request-level fence.
10
+ *
11
+ * A reverse proxy in front of the host rewrites the Host header to its own
12
+ * upstream literal (a Cloudflare tunnel, frp and an nginx reverse proxy all
13
+ * dial 127.0.0.1:<port>), and the socket the origin sees is the proxy's, which
14
+ * is loopback by construction. Both halves of the fence then hold for a public
15
+ * request. Forwarding headers are the signal that a hop stands in between: a
16
+ * request that carries CF-Connecting-IP or X-Forwarded-For is answered through
17
+ * a proxy and is never treated as a local one (issue #1906).
18
+ *
19
+ * An operator who runs that proxy or tunnel themselves can opt into the
20
+ * narrower case: isForwardedLoopbackRequest describes a forwarded request that
21
+ * still landed on this machine's loopback upstream, and a route family admits
22
+ * it only behind its own default-off switch (issue #1918).
23
+ * @module dsh-web-shared/host/loopback
24
+ */
25
+ import type { IncomingMessage } from 'node:http';
26
+ /** IPv4 127/8 predicate (four decimal octets, first == 127). */
27
+ export declare function isIPv4Loopback(v4: string): boolean;
28
+ /** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
29
+ export declare function isLoopbackAddress(address: string | undefined): boolean;
30
+ /** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
31
+ export declare function isLoopbackHostname(hostname: string): boolean;
32
+ /**
33
+ * Whether a reverse proxy stood between the client and this host: the request
34
+ * carries CF-Connecting-IP or X-Forwarded-For. Either header is stamped by a
35
+ * hop that forwards traffic, so the request did not originate on this machine.
36
+ * @param request - node HTTP request.
37
+ * @returns true when a forwarding header is present.
38
+ */
39
+ export declare function isProxiedRequest(request: IncomingMessage): boolean;
40
+ /**
41
+ * Request-level trust fence: a loopback socket address AND a loopback Host
42
+ * header, plus browser same-origin markers. The socket address is
43
+ * authoritative for a direct connection; a request that carries a forwarding
44
+ * header is refused outright, because a proxy in front of the host makes both
45
+ * the socket address and the Host header describe the proxy rather than the
46
+ * client. X-Forwarded-For is therefore never evidence *for* loopback.
47
+ */
48
+ export declare function isLoopbackRequest(request: IncomingMessage): boolean;
49
+ /**
50
+ * Whether a forwarded request landed on this machine's loopback upstream: a
51
+ * forwarding header (the proxy's own stamp), a loopback socket address (the
52
+ * proxy dials 127.0.0.1:<port>), and a loopback Host header (the proxy rewrote
53
+ * the authority to its upstream literal).
54
+ *
55
+ * This is a fact about the route, not a trust decision. A public request to a
56
+ * tunnel satisfies all three by construction, because the proxy is the client
57
+ * of this process: only a caller that operates the proxy can decide it stands
58
+ * for the browser, which is why every consumer keeps this behind an explicit
59
+ * default-off switch and its own browser markers. isLoopbackRequest is
60
+ * unchanged and still refuses a forwarded request (issue #1906).
61
+ * @param request - node HTTP request.
62
+ * @returns true when a forwarding header, a loopback socket, and a loopback Host all hold.
63
+ */
64
+ export declare function isForwardedLoopbackRequest(request: IncomingMessage): boolean;
@@ -0,0 +1,133 @@
1
+ /**
2
+ * The monitoring loop: inspection on a timer, feeding the alert engine.
3
+ *
4
+ * This is the piece that turns the inspection layer from "an agent can ask
5
+ * for a health check" into "the fleet is watched". Without it, an alert
6
+ * only advances when a human (or an agent) happens to run hub_inspect, so a
7
+ * disk filling up at 03:00 is discovered whenever someone next looks —
8
+ * which is exactly the failure a monitoring tool exists to prevent.
9
+ *
10
+ * The loop is deliberately conservative, because its failure mode is
11
+ * expensive:
12
+ *
13
+ * - **One round at a time.** A round that outlasts the interval does not
14
+ * stack: the next tick is skipped, not queued. Fifty hosts with a slow
15
+ * connection would otherwise pile up overlapping rounds until the pool
16
+ * is exhausted.
17
+ * - **The timer belongs to the plugin's fiber.** `ctx.timer.interval`
18
+ * disposes with the fiber, so disabling the plugin stops the loop
19
+ * instead of leaving an orphan timer probing servers forever.
20
+ * - **A failed round is not a fleet-wide alert.** If every host fails, the
21
+ * cause is almost always the local link or the pool, not fifty machines
22
+ * dying at once. The round is reported as a degraded round, and the
23
+ * alert engine's null-freeze keeps the previous states rather than
24
+ * inventing fifty recoveries.
25
+ */
26
+ import type { SshEngine } from '../engine.ts';
27
+ import type { Inspector, InspectionRound } from '../inspect/inspection.ts';
28
+ import type { AlertEngine, AlertNotification, AlertRule } from '../alerting/rules.ts';
29
+ import type { AlertEvent } from '../alerting/tools.ts';
30
+ /** Where the tick callback gets its timer from (the cordis timer service). */
31
+ export interface TimerHost {
32
+ interval(callback: () => void, delay: number): () => void;
33
+ }
34
+ /** Monitoring loop options. */
35
+ export interface MonitorOptions {
36
+ /** How often to run a round, in milliseconds. */
37
+ intervalMs: number;
38
+ /** The hosts to watch (a fixed set captured at start; re-resolved per round). */
39
+ targets?: () => string[];
40
+ /** Which checks to run (default: all built-in checks). */
41
+ checks?: string[];
42
+ /** Per-command timeout. */
43
+ timeoutMs?: number;
44
+ /** The alert rules. */
45
+ rules: AlertRule[];
46
+ }
47
+ /** A round's outcome as the loop records it. */
48
+ export interface MonitorTick {
49
+ /** Epoch milliseconds when the round started. */
50
+ at: number;
51
+ /** Whether the round actually ran (false when skipped as overlapping). */
52
+ ran: boolean;
53
+ /** How many hosts were inspected. */
54
+ hosts: number;
55
+ /** How many results breached their threshold. */
56
+ breaches: number;
57
+ /** How many probe failures (unreadable values) occurred. */
58
+ blind: number;
59
+ /** The notifications this round produced. */
60
+ notifications: AlertNotification[];
61
+ /** Why the round did not run, when it did not. */
62
+ skippedBecause?: string;
63
+ }
64
+ /**
65
+ * The monitoring loop.
66
+ *
67
+ * Owns no state beyond `running` and the recent ticks: the inspection
68
+ * history and the alert state each have their own store, so a restart of
69
+ * the loop does not lose either.
70
+ */
71
+ export declare class Monitor {
72
+ private readonly engine;
73
+ private readonly inspector;
74
+ private readonly alerts;
75
+ private readonly events;
76
+ private readonly onNotify?;
77
+ private readonly options;
78
+ /** Recent ticks, newest last (bounded). */
79
+ readonly ticks: MonitorTick[];
80
+ /** The interval disposer, while the loop runs. */
81
+ private dispose;
82
+ /** Whether a round is in flight (the overlap guard). */
83
+ private inFlight;
84
+ /** The last round, for the panel to read without re-reading the file. */
85
+ lastRound: InspectionRound | undefined;
86
+ constructor(engine: SshEngine, inspector: Inspector, alerts: AlertEngine, events: AlertEvent[], options: MonitorOptions, onNotify?: (notification: AlertNotification) => void | Promise<void>);
87
+ /** Whether the loop is currently armed. */
88
+ get running(): boolean;
89
+ /**
90
+ * Start the loop.
91
+ *
92
+ * A second start is a no-op rather than a second timer: two timers would
93
+ * double every probe against the fleet.
94
+ *
95
+ * @param timer - the cordis timer service.
96
+ * @returns the disposer that stops the loop.
97
+ */
98
+ start(timer: TimerHost): () => void;
99
+ /** Stop the loop (idempotent). */
100
+ stop(): void;
101
+ /**
102
+ * Run one round now.
103
+ *
104
+ * @returns the round's outcome, or undefined when a round was already in
105
+ * flight (the tick is skipped, not queued).
106
+ */
107
+ tick(): Promise<MonitorTick | undefined>;
108
+ /** Append a tick to the bounded history. */
109
+ private record;
110
+ /**
111
+ * The current state, for the status route and the panel.
112
+ *
113
+ * @returns the loop's health summary.
114
+ */
115
+ status(): {
116
+ running: boolean;
117
+ intervalMs: number;
118
+ lastTick?: MonitorTick;
119
+ nextTickAt?: number;
120
+ hosts: number;
121
+ lastRoundAt?: number;
122
+ };
123
+ }
124
+ /**
125
+ * Render one round as operator-facing text.
126
+ *
127
+ * Used by the status route and the panel's inspection tab, so both show the
128
+ * same thing the agent sees.
129
+ *
130
+ * @param round - the round.
131
+ * @returns the report text.
132
+ */
133
+ export declare function renderRound(round: InspectionRound): string;
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Metric sampling and tiered retention.
3
+ *
4
+ * A fleet operator needs two different things from history, and they pull in
5
+ * opposite directions:
6
+ *
7
+ * - **"What happened at 03:12?"** wants fine resolution, recently.
8
+ * - **"Is this box slowly filling up over months?"** wants a long window,
9
+ * and does not care about per-second detail.
10
+ *
11
+ * Keeping every raw sample forever answers both and costs unbounded disk on
12
+ * the operator's own workstation. Keeping only hourly averages answers the
13
+ * second and makes the first unanswerable. So this keeps three tiers and
14
+ * lets the coarse tiers outlive the fine ones:
15
+ *
16
+ * raw one sample per round, pruned after RAW_WINDOW
17
+ * 1m one sample per minute, pruned after MINUTE_WINDOW
18
+ * 15m one sample per 15 min, pruned after QUARTER_WINDOW
19
+ * 1h one sample per hour, never pruned
20
+ *
21
+ * Each tier is derived from the tier below it by averaging, so a tier never
22
+ * invents a sample that no measurement supports — a bucket with no raw
23
+ * samples produces no aggregated sample at all. That distinction matters:
24
+ * a gap in the graph means "we did not measure", not "the value was zero".
25
+ *
26
+ * Storage is one JSON Lines file per host and tier. JSONL because a partial
27
+ * write loses one line, not the file, and because an operator can read it
28
+ * with `tail` without a tool.
29
+ */
30
+ import type { CheckResult } from '../inspect/checks.ts';
31
+ /** One metric sample. */
32
+ export interface MetricSample {
33
+ /** Epoch milliseconds. */
34
+ at: number;
35
+ /** The metric id (equal to the check id that produced it). */
36
+ metric: string;
37
+ /** The value; null when the probe could not read it. */
38
+ value: number | null;
39
+ }
40
+ /** One aggregated bucket. */
41
+ export interface MetricBucket {
42
+ /** Bucket start, epoch milliseconds. */
43
+ at: number;
44
+ metric: string;
45
+ /** Mean of the raw samples in the bucket; null when every sample was blind. */
46
+ value: number | null;
47
+ /** How many raw samples fed this bucket. */
48
+ samples: number;
49
+ }
50
+ /** A retention tier. */
51
+ export interface Tier {
52
+ /** Tier name, also its directory name. */
53
+ name: 'raw' | '1m' | '15m' | '1h';
54
+ /** Bucket width in milliseconds (0 for raw, which keeps the sample's own `at`). */
55
+ widthMs: number;
56
+ /** How long a bucket survives, in milliseconds; 0 means forever. */
57
+ keepMs: number;
58
+ }
59
+ /**
60
+ * The tiers, coarse to fine windows.
61
+ *
62
+ * The raw window is deliberately short (24h): raw samples are the bulky tier,
63
+ * and anything older is answerable from the 1m tier for a month.
64
+ */
65
+ export declare const TIERS: readonly Tier[];
66
+ /** The metrics store root. */
67
+ export declare function metricsRoot(): string;
68
+ /**
69
+ * The file a (host, tier) pair lives in.
70
+ *
71
+ * @param alias - the host alias.
72
+ * @param tier - the tier name.
73
+ * @param root - store root override (tests).
74
+ * @returns the absolute path.
75
+ */
76
+ export declare function tierPath(alias: string, tier: Tier['name'], root?: string): string;
77
+ /**
78
+ * The metric store: append raw samples, derive coarser tiers, prune.
79
+ *
80
+ * One instance per plugin apply. Every method is synchronous: samples are
81
+ * small and arrive once per inspection round, so a write is microseconds,
82
+ * and making it async would only add a window in which an in-flight round's
83
+ * samples could interleave with a prune.
84
+ */
85
+ export declare class MetricStore {
86
+ private readonly root;
87
+ constructor(root?: string);
88
+ /**
89
+ * Append one round's samples and roll the tiers up.
90
+ *
91
+ * @param alias - the host alias.
92
+ * @param samples - the samples from this round.
93
+ */
94
+ record(alias: string, samples: readonly MetricSample[]): void;
95
+ /** Append entries to one tier file. */
96
+ private appendTier;
97
+ /**
98
+ * Delete every stored series for one alias.
99
+ *
100
+ * Called when a host is removed from the store: its metric history is keyed
101
+ * only by alias, so leaving it behind means a later host that happens to
102
+ * reuse the name inherits a stranger's numbers. That is worse than losing
103
+ * history, because the numbers look plausible.
104
+ *
105
+ * @param alias - the host alias.
106
+ * @returns true when something was removed.
107
+ */
108
+ forget(alias: string): boolean;
109
+ /** Read one tier. */
110
+ readTier(alias: string, tier: Tier | Tier['name']): Array<Record<string, unknown>>;
111
+ /**
112
+ * Derive every coarse tier from the tier below and prune expired buckets.
113
+ *
114
+ * Idempotent: a bucket that already exists is replaced, not duplicated, so
115
+ * running this after every round converges instead of accumulating.
116
+ */
117
+ rollUp(alias: string): void;
118
+ /**
119
+ * Aggregate a finer tier into a coarser one.
120
+ *
121
+ * Buckets are aligned to the width, so a bucket always covers the same
122
+ * wall-clock window regardless of when the round happened.
123
+ */
124
+ private aggregate;
125
+ /** Drop buckets older than the tier's retention window. */
126
+ private prune;
127
+ /**
128
+ * Read a series for display.
129
+ *
130
+ * @param alias - the host.
131
+ * @param tier - which tier to read.
132
+ * @param metric - optional metric filter.
133
+ * @param limit - most recent N buckets (default 120).
134
+ * @returns the series, oldest first.
135
+ */
136
+ series(alias: string, tier: Tier['name'], metric?: string, limit?: number): MetricBucket[];
137
+ }
138
+ /**
139
+ * Extract numeric samples from one inspection round for one host.
140
+ *
141
+ * Only checks with a numeric kind become metrics: a boolean check ("sshd is
142
+ * running") has no meaningful average, and a text check has no series at all.
143
+ * The timestamp comes from the round, because a CheckResult carries no time
144
+ * of its own — every result in a round shares the round's start.
145
+ *
146
+ * @param at - the round's start, epoch milliseconds.
147
+ * @param results - the round's results for that host.
148
+ * @param kindOf - resolves a check id to its kind.
149
+ * @returns the numeric samples.
150
+ */
151
+ export declare function samplesFromRound(at: number, results: readonly CheckResult[], kindOf: (checkId: string) => string | undefined): MetricSample[];