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,50 @@
1
+ /**
2
+ * Activity history for the two surfaces that produce it: deployment runs and
3
+ * cross-host log searches.
4
+ *
5
+ * Both are append-only NDJSON files under the plugin's home, bounded the same
6
+ * way the metric tiers are: a hard cap on retained records, oldest dropped
7
+ * first. The panel reads them as history; nothing in the host half depends on
8
+ * them, so a missing or corrupt file degrades to "no history yet" rather than
9
+ * failing a route.
10
+ *
11
+ * Why persist at all: a deployment or a log search is an operator action with
12
+ * an outcome they need to look at *after* the panel has moved on. Keeping only
13
+ * the in-memory result would lose it on the next panel switch — and this is
14
+ * exactly the kind of record someone asks about a day later.
15
+ */
16
+ /** One of the history files. */
17
+ export type HistoryKind = 'deploys' | 'logs';
18
+ /**
19
+ * Append-only JSON-lines history with a fixed retention window.
20
+ *
21
+ * Every write is a single `appendFileSync` of one line, so a crash mid-write
22
+ * can at worst truncate the newest record; `read()` skips unparsable lines
23
+ * instead of throwing, which keeps one bad line from hiding all the others.
24
+ */
25
+ export declare class ActivityHistory<T> {
26
+ private readonly kind;
27
+ private readonly file;
28
+ /**
29
+ * @param root - the plugin's home directory.
30
+ * @param kind - which history file this instance owns.
31
+ */
32
+ constructor(root: string, kind: HistoryKind);
33
+ /** The file this history writes to. */
34
+ get path(): string;
35
+ /**
36
+ * Append one record, trimming the file when it exceeds the cap.
37
+ * @param record - the record to store.
38
+ */
39
+ append(record: T): void;
40
+ /**
41
+ * Read the newest records first.
42
+ * @param limit - maximum records to return.
43
+ * @returns the records, newest first.
44
+ */
45
+ read(limit?: number): T[];
46
+ /** Drop the oldest records once the file holds more than the cap. */
47
+ private trim;
48
+ /** Forget every record (the panel's "clear history"). */
49
+ clear(): void;
50
+ }
@@ -0,0 +1,89 @@
1
+ /**
2
+ * Outbound notification: a template-driven HTTP sender.
3
+ *
4
+ * A generic HTTP template with named placeholders covers Bark, Telegram,
5
+ * Lark/Feishu and WeCom without the plugin growing a dependency on each of
6
+ * them — the operator supplies the URL and the body shape, and the plugin
7
+ * substitutes the values.
8
+ *
9
+ * The template placeholders are the ones the operator actually reads:
10
+ * `#SERVER.NAME#`, `#SERVER.ALIAS#`, `#RULE.NAME#`, `#RULE.ID#`,
11
+ * `#VALUE#`, `#MESSAGE#`, `#STATE#`, `#TIME#`.
12
+ *
13
+ * An unknown placeholder is left AS IS rather than replaced with an empty
14
+ * string: a typo in a template must be visible, not silently blank.
15
+ */
16
+ import type { AlertNotification } from './rules.ts';
17
+ /** One notification channel. */
18
+ export interface NotifyChannel {
19
+ /** A stable name for the channel. */
20
+ id: string;
21
+ /** The target URL. */
22
+ url: string;
23
+ /** The HTTP method (default POST). */
24
+ method?: string;
25
+ /** The body template, with placeholders. */
26
+ body?: string;
27
+ /** Extra headers. */
28
+ headers?: Record<string, string>;
29
+ /** The content type (default application/json). */
30
+ contentType?: string;
31
+ }
32
+ /** The outcome of one delivery attempt. */
33
+ export interface NotifyOutcome {
34
+ channelId: string;
35
+ ok: boolean;
36
+ /** The HTTP status, when a response arrived. */
37
+ status?: number;
38
+ /** The error message, when the attempt failed. */
39
+ error?: string;
40
+ }
41
+ /**
42
+ * The placeholders a template may use.
43
+ *
44
+ * @param notification - the event to describe.
45
+ * @param extra - additional key/value pairs (a rule title, a value).
46
+ * @returns the placeholder map.
47
+ */
48
+ export declare function placeholders(notification: AlertNotification, extra?: Record<string, string>): Record<string, string>;
49
+ /**
50
+ * Substitute the placeholders in a template.
51
+ *
52
+ * @param template - the template text.
53
+ * @param values - the placeholder values.
54
+ * @returns the substituted text; unknown placeholders are left as they are.
55
+ */
56
+ export declare function renderTemplate(template: string, values: Record<string, string>): string;
57
+ /**
58
+ * The built-in channel presets.
59
+ *
60
+ * Each preset is a starting point, not a fixed format: the operator can
61
+ * edit the URL and body to match their deployment.
62
+ */
63
+ export declare const NOTIFY_PRESETS: ReadonlyArray<{
64
+ id: string;
65
+ title: string;
66
+ channel: NotifyChannel;
67
+ }>;
68
+ /**
69
+ * Send one notification to one channel.
70
+ *
71
+ * The fetch is deliberately fire-and-forget from the caller's point of
72
+ * view: a failing notification channel must not stop the inspection loop,
73
+ * but its failure IS reported so a broken channel is visible.
74
+ *
75
+ * @param channel - the channel to send to.
76
+ * @param notification - the event.
77
+ * @param extra - extra placeholder values.
78
+ * @returns the delivery outcome.
79
+ */
80
+ export declare function notify(channel: NotifyChannel, notification: AlertNotification, extra?: Record<string, string>): Promise<NotifyOutcome>;
81
+ /**
82
+ * Send one notification to every channel.
83
+ *
84
+ * @param channels - the channels.
85
+ * @param notification - the event.
86
+ * @param extra - extra placeholder values.
87
+ * @returns one outcome per channel.
88
+ */
89
+ export declare function notifyAll(channels: NotifyChannel[], notification: AlertNotification, extra?: Record<string, string>): Promise<NotifyOutcome[]>;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * The alert summary the agent sees in its own prompt.
3
+ *
4
+ * A monitoring loop whose only output is a webhook is invisible to the agent
5
+ * working in this session: it can list hosts and run commands, but it has no
6
+ * way to know the fleet is already on fire unless it thinks to ask. This
7
+ * renders the current alert state into the plugin's prompt section, so a
8
+ * conversation that touches the fleet starts from the same picture the
9
+ * operator has.
10
+ *
11
+ * Deliberately quiet:
12
+ * - nothing firing, and the loop armed → one short line saying so;
13
+ * - nothing firing, loop NOT armed → a line that says the silence means
14
+ * nothing, because "no alerts" and "nothing is checking" are opposite
15
+ * facts that look identical in an empty list;
16
+ * - firing → the rule, the host and the value, newest first, bounded so a
17
+ * fleet-wide outage cannot flood the prompt.
18
+ */
19
+ import type { AlertEngine } from './rules.ts';
20
+ import type { Monitor } from '../monitor/loop.ts';
21
+ /**
22
+ * Render the live alert state for the system prompt.
23
+ *
24
+ * @param alerts - the alert engine holding the per-rule state.
25
+ * @param monitor - the loop, consulted only to say whether the state is being advanced.
26
+ * @returns the summary text, or an empty string when there is nothing to say.
27
+ */
28
+ export declare function renderAlertSummary(alerts: AlertEngine, monitor: Monitor): string;
@@ -0,0 +1,135 @@
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
+ import type { CheckResult } from '../inspect/checks.ts';
27
+ /** The lifecycle state of one alert. */
28
+ export type AlertState =
29
+ /** Healthy: under the threshold. */
30
+ 'ok'
31
+ /** Breaching, but not yet for long enough to fire. */
32
+ | 'pending'
33
+ /** Breaching and fired. */
34
+ | 'firing'
35
+ /** The value could not be read; the previous state is held. */
36
+ | 'frozen';
37
+ /** One alert rule. */
38
+ export interface AlertRule {
39
+ /** Stable identifier. */
40
+ id: string;
41
+ /** The check this rule watches. */
42
+ checkId: string;
43
+ /** Which hosts it covers (empty means every host). */
44
+ hosts?: string[];
45
+ /** How long the breach must persist before it fires, in seconds. */
46
+ forSeconds: number;
47
+ /** How long to wait before re-notifying a continued breach, in seconds. */
48
+ cooldownSeconds: number;
49
+ /** Whether the rule is active. */
50
+ enabled: boolean;
51
+ }
52
+ /** The persisted state of one (rule, host) pair. */
53
+ export interface AlertState_ {
54
+ /** The current state. */
55
+ state: AlertState;
56
+ /**
57
+ * The state held across a blackout.
58
+ *
59
+ * While the probe is blind the state is 'frozen'; this keeps the
60
+ * pre-blackout state so the recovery that follows it is still reported.
61
+ */
62
+ heldState?: 'pending' | 'firing';
63
+ /** Consecutive breaching rounds so far. */
64
+ consecutiveBreaches: number;
65
+ /** When the current breach streak started (epoch ms). */
66
+ breachStartedAt?: number;
67
+ /** When the alert last fired (epoch ms). */
68
+ lastFiredAt?: number;
69
+ /** The value that last fired it. */
70
+ lastValue?: number | boolean | string | null;
71
+ }
72
+ /** A notification the engine wants to send. */
73
+ export interface AlertNotification {
74
+ /** The rule id. */
75
+ ruleId: string;
76
+ /** The host alias. */
77
+ alias: string;
78
+ /** 'trigger' for a new breach, 'recover' for a recovery. */
79
+ kind: 'trigger' | 'recover';
80
+ /** The check title. */
81
+ title: string;
82
+ /** The value that breached (or returned to normal). */
83
+ value: string;
84
+ /** When the event happened. */
85
+ at: number;
86
+ }
87
+ /** The engine's persisted state file. */
88
+ export declare function alertStatePath(): string;
89
+ /**
90
+ * The alert state machine.
91
+ *
92
+ * One instance per plugin apply. The state survives a restart, so an alert
93
+ * that was firing when DSH stopped is still firing when it comes back.
94
+ */
95
+ export declare class AlertEngine {
96
+ /** The state file. */
97
+ readonly path: string;
98
+ /** The state, keyed by `ruleId|alias`. */
99
+ private states;
100
+ constructor(path?: string);
101
+ /**
102
+ * Evaluate one round of inspection results against the rules.
103
+ *
104
+ * @param rules - the rules to apply.
105
+ * @param results - the round's results.
106
+ * @param pollIntervalMs - the poll interval, used to convert the rule's
107
+ * "for" duration into a number of consecutive rounds.
108
+ * @returns the notifications to send.
109
+ */
110
+ evaluate(rules: AlertRule[], results: CheckResult[], pollIntervalMs: number): AlertNotification[];
111
+ /**
112
+ * Evaluate one result against one rule.
113
+ *
114
+ * @param rule - the rule.
115
+ * @param result - the check result.
116
+ * @param pollIntervalMs - the poll interval.
117
+ * @param now - the current time.
118
+ * @returns a notification when the state changed in a way that must be
119
+ * reported, otherwise undefined.
120
+ */
121
+ private evaluateOne;
122
+ /**
123
+ * The current state of every (rule, host) pair.
124
+ *
125
+ * @returns the states.
126
+ */
127
+ list(): Array<{
128
+ ruleId: string;
129
+ alias: string;
130
+ } & AlertState_>;
131
+ /** Load the persisted state. */
132
+ private load;
133
+ /** Persist the state. */
134
+ private save;
135
+ }
@@ -0,0 +1,30 @@
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
+ import { AlertEngine, type AlertRule } from './rules.ts';
14
+ import { type NotifyChannel } from './notify.ts';
15
+ /** The default rule set: the checks whose thresholds matter most. */
16
+ export declare function defaultRules(): AlertRule[];
17
+ /** The alerts tool: the current state and the recent events. */
18
+ export declare function hubAlertsTool(engine: AlertEngine, events: AlertEvent[]): import("@deepseek-ai/dsh-tools").ToolDefinition;
19
+ /** The rules tool: list and update the rules. */
20
+ export declare function hubAlertRulesTool(rules: AlertRule[]): import("@deepseek-ai/dsh-tools").ToolDefinition;
21
+ /** The notification test tool. */
22
+ export declare function hubAlertTestTool(channels: NotifyChannel[]): import("@deepseek-ai/dsh-tools").ToolDefinition;
23
+ /** One alert event, as the tools see it. */
24
+ export interface AlertEvent {
25
+ ruleId: string;
26
+ alias: string;
27
+ kind: 'trigger' | 'recover';
28
+ value: string;
29
+ at: number;
30
+ }
@@ -0,0 +1,84 @@
1
+ /**
2
+ * Operation audit log.
3
+ *
4
+ * Every consequential action (exec, cluster, transfer, tunnel, deploy,
5
+ * credential change) is recorded: what happened, against which hosts, with
6
+ * which outcome, and who triggered it.
7
+ *
8
+ * The log is append-only JSON Lines — one record per line — so it can be
9
+ * tailed, grepped and shipped without a database. It lives beside the
10
+ * host store under `$DSH_HOME`, owner-readable only.
11
+ *
12
+ * Two rules the log must never break:
13
+ * 1. No secret ever reaches it. Commands are recorded, but a command that
14
+ * embeds a password is redacted before it is written.
15
+ * 2. A record is written AFTER the outcome is known, so the log says what
16
+ * happened rather than what was attempted.
17
+ */
18
+ /** What kind of action was performed. */
19
+ export type AuditAction = 'host.create' | 'host.update' | 'host.delete' | 'host.test' | 'exec' | 'cluster' | 'upload' | 'download' | 'tunnel.start' | 'tunnel.stop' | 'tunnel.update' | 'deploy' | 'rollback' | 'inspect.run' | 'credential.rotate' | 'security.policy';
20
+ /** How the action was triggered. */
21
+ export type AuditActor = 'user' | 'agent' | 'system';
22
+ /** One audit record. */
23
+ export interface AuditRecord {
24
+ /** Epoch milliseconds. */
25
+ ts: number;
26
+ /** What happened. */
27
+ action: AuditAction;
28
+ /** Who triggered it. */
29
+ actor: AuditActor;
30
+ /** The hosts the action touched. */
31
+ targets: string[];
32
+ /** Whether it succeeded. */
33
+ ok: boolean;
34
+ /** A short, human-readable summary (never contains secrets). */
35
+ summary: string;
36
+ /** Free-form details: exit codes, durations, counts. */
37
+ detail?: Record<string, unknown>;
38
+ }
39
+ /** The audit log file path. */
40
+ export declare function auditLogPath(): string;
41
+ /**
42
+ * Redact secrets from a string before it is recorded.
43
+ *
44
+ * @param text - the text to redact.
45
+ * @returns the redacted text.
46
+ */
47
+ export declare function redact(text: string): string;
48
+ /**
49
+ * The audit log writer.
50
+ *
51
+ * Writes are best-effort: a failure to audit must not fail the operation
52
+ * the user asked for (an unwritable log directory should not block a
53
+ * deployment), but the failure is reported so it is not silent.
54
+ */
55
+ export declare class AuditLog {
56
+ /** The file this log writes to. */
57
+ readonly path: string;
58
+ /** The last write error, if any. */
59
+ lastError: string | undefined;
60
+ constructor(path?: string);
61
+ /**
62
+ * Append one record.
63
+ *
64
+ * @param record - the record to write.
65
+ */
66
+ append(record: AuditRecord): void;
67
+ /**
68
+ * Read the most recent records, newest last.
69
+ *
70
+ * @param limit - the maximum number of records to return.
71
+ * @returns the records, oldest first.
72
+ */
73
+ read(limit?: number): AuditRecord[];
74
+ }
75
+ /**
76
+ * A short, stable summary of an exec/cluster outcome.
77
+ *
78
+ * @param alias - the host alias.
79
+ * @param command - the command (redacted by the writer).
80
+ * @param exitCode - the remote exit code.
81
+ * @param durationMs - how long it took.
82
+ * @returns the summary text.
83
+ */
84
+ export declare function execSummary(alias: string, command: string, exitCode: number | null, durationMs: number): string;
@@ -0,0 +1,50 @@
1
+ /**
2
+ * Audit recording for the fleet tools.
3
+ *
4
+ * The audit log answers "who changed this machine, when, and what did they
5
+ * run". That answer is only complete if EVERY mutating operation is
6
+ * recorded — a log that covers some operations is worse than no log,
7
+ * because the operator trusts the gaps to mean "nothing happened".
8
+ *
9
+ * So the recorder wraps the mutating tools at the point where they are
10
+ * registered, and the read-only tools are deliberately not recorded: an
11
+ * audit log full of `ssh_list` calls buries the entries that matter.
12
+ */
13
+ import type { AuditAction, AuditActor, AuditLog } from './audit-log.ts';
14
+ /** The outcome of a tool call, as the recorder sees it. */
15
+ export interface CallOutcome {
16
+ /** Whether the call succeeded. */
17
+ ok: boolean;
18
+ /** The hosts the call touched. */
19
+ targets?: string[];
20
+ /** A short summary (secrets are redacted on write). */
21
+ summary?: string;
22
+ /** Extra structured detail. */
23
+ detail?: Record<string, unknown>;
24
+ }
25
+ /**
26
+ * A recorder bound to one audit log and one actor.
27
+ *
28
+ * The actor matters: an operator running a command from the panel and an
29
+ * agent running the same command are different actors, and an audit trail
30
+ * that cannot tell them apart does not answer "who did this".
31
+ */
32
+ export declare class AuditRecorder {
33
+ /** The log to write to. */
34
+ private readonly log;
35
+ /** Who is performing the actions. */
36
+ private readonly actor;
37
+ constructor(log: AuditLog | undefined, actor?: AuditActor);
38
+ /**
39
+ * Record one action.
40
+ *
41
+ * A missing log means auditing is disabled, which is a configuration
42
+ * choice — the call is then a no-op, not an error.
43
+ *
44
+ * @param action - what happened.
45
+ * @param outcome - the outcome of the call.
46
+ */
47
+ record(action: AuditAction, outcome: CallOutcome): void;
48
+ /** Whether this recorder writes anything. */
49
+ get enabled(): boolean;
50
+ }