@cohortapp/agent-sdk 2.18.36 → 2.19.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 (39) hide show
  1. package/bin/maestro.mjs +3 -0
  2. package/docs/guides/billing-console-keys.md +16 -3
  3. package/docs/runbooks/cadence-requeue-storm-recovery.md +186 -0
  4. package/lib/assurance/first-reply.mjs +47 -2
  5. package/lib/assurance/notice-plane.mjs +218 -0
  6. package/lib/assurance/notice-voice.mjs +35 -2
  7. package/lib/assurance/operator-plane-store.mjs +164 -0
  8. package/lib/assurance/operator-plane.mjs +689 -0
  9. package/lib/budget-escalate.mjs +42 -4
  10. package/lib/budget-guard.mjs +24 -1
  11. package/lib/cadence-bus.mjs +359 -46
  12. package/lib/cli/attention.mjs +300 -0
  13. package/lib/cli/seat-auth.mjs +86 -6
  14. package/lib/comms/machine-status.mjs +377 -0
  15. package/lib/comms/send-gate.mjs +309 -2
  16. package/lib/org/awareness.mjs +15 -2
  17. package/lib/org/clause-match.mjs +470 -0
  18. package/lib/org/client.mjs +27 -1
  19. package/lib/org/escalation-chain.mjs +134 -0
  20. package/lib/org/first-run.mjs +263 -0
  21. package/lib/org/genesis-contract.mjs +271 -0
  22. package/lib/org/governance-runtime.mjs +409 -0
  23. package/lib/org/governance-store.mjs +238 -0
  24. package/lib/org/governance.mjs +326 -0
  25. package/lib/org/mesh.mjs +135 -0
  26. package/lib/org/protocol.checksum +1 -1
  27. package/lib/org/protocol.mjs +6 -0
  28. package/lib/org/tool-surface.mjs +28 -0
  29. package/lib/setup/enroll-from-cohort.mjs +11 -0
  30. package/lib/telemetry/alerts.mjs +12 -0
  31. package/lib/telemetry/collect.mjs +237 -1
  32. package/package.json +1 -1
  33. package/scripts/ci/check-durable-write-seam.mjs +3 -3
  34. package/scripts/daemon/agent-daemon.mjs +41 -2
  35. package/scripts/daemon/assurance.mjs +852 -49
  36. package/scripts/daemon/cadence-consumer.mjs +182 -9
  37. package/scripts/daemon/context-compiler.mjs +25 -0
  38. package/scripts/daemon/deliver.mjs +172 -2
  39. package/scripts/fleet/closing-sweep.mjs +266 -0
@@ -0,0 +1,164 @@
1
+ /**
2
+ * lib/assurance/operator-plane-store.mjs — the operator plane's disk, read-only.
3
+ *
4
+ * The edge half of the reader. `operator-plane.mjs` is pure and decides what the
5
+ * rows MEAN; this file knows only where they are and how to not throw.
6
+ *
7
+ * WHY IT IS A MODULE OF ITS OWN AND NOT PART OF THE CLI. Two callers need the
8
+ * same join: `maestro attention` (a person asking) and `lib/telemetry/collect.mjs`
9
+ * (the presence beat, every 30 s, pushing a summary off the box). If the CLI
10
+ * owned the reading, the beat would grow a second copy of the paths and the two
11
+ * would drift — and a drifted path here does not fail, it reports an empty plane,
12
+ * which is indistinguishable from a healthy one. That is exactly the failure mode
13
+ * this subsystem keeps producing.
14
+ *
15
+ * NEVER THROWS, AND NEVER WRITES. A reader that can crash the presence beat is
16
+ * worse than a reader that reports less, and nothing in the operator plane is
17
+ * this module's to change: `mkdirSync` is deliberately absent, so reading a seat
18
+ * that has never failed does not create the directory it is looking for.
19
+ *
20
+ * @module lib/assurance/operator-plane-store
21
+ */
22
+
23
+ "use strict";
24
+
25
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
26
+ import { join } from "node:path";
27
+
28
+ import {
29
+ OPERATOR_PLANE_RETENTION_MS,
30
+ groupIncidents,
31
+ clusterIncidents,
32
+ summarisePlane,
33
+ } from "./operator-plane.mjs";
34
+
35
+ /** The agent root, by the same precedence `lib/cli/skills.mjs` uses. */
36
+ export function planeRoot(o = {}) {
37
+ return o.agentRoot || process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
38
+ }
39
+
40
+ /** The retention window this seat is actually running, env override included. */
41
+ export function planeWindowMs(env = process.env) {
42
+ const n = Number(env && env.ASSURANCE_RETENTION_MS);
43
+ return Number.isFinite(n) && n > 0 ? n : OPERATOR_PLANE_RETENTION_MS;
44
+ }
45
+
46
+ function obligationsDir(agentRoot) {
47
+ return join(agentRoot, "state", "obligations");
48
+ }
49
+
50
+ function readJson(path) {
51
+ try { return JSON.parse(readFileSync(path, "utf8")); }
52
+ catch { return null; }
53
+ }
54
+
55
+ /**
56
+ * `state/obligations/needs-attention/*.json` — one row per key, overwritten in
57
+ * place, never pruned in production before this change.
58
+ * @param {string} agentRoot
59
+ * @returns {object[]}
60
+ */
61
+ export function readNeedsAttention(agentRoot) {
62
+ const dir = join(obligationsDir(agentRoot), "needs-attention");
63
+ let names = [];
64
+ try { names = readdirSync(dir); } catch { return []; }
65
+ const out = [];
66
+ for (const name of names) {
67
+ if (!name.endsWith(".json")) continue;
68
+ const row = readJson(join(dir, name));
69
+ // A row whose `key` was lost is still evidence that something failed, so it
70
+ // is kept and named by its FILE — which is the sanitised key, and the only
71
+ // handle an operator has for it anyway.
72
+ if (row && typeof row === "object") out.push({ ...row, key: row.key || name.slice(0, -5), _file: name });
73
+ }
74
+ return out;
75
+ }
76
+
77
+ /**
78
+ * `state/obligations/notice-journal.jsonl` — append-only, the only ordered record.
79
+ *
80
+ * A corrupt line is SKIPPED rather than failing the read: this file is appended
81
+ * to by a daemon that may be killed mid-write, and losing one line is not a
82
+ * reason to report an empty plane.
83
+ *
84
+ * @param {string} agentRoot
85
+ * @returns {object[]}
86
+ */
87
+ export function readNoticeJournal(agentRoot) {
88
+ const path = join(obligationsDir(agentRoot), "notice-journal.jsonl");
89
+ let raw = "";
90
+ try { raw = readFileSync(path, "utf8"); } catch { return []; }
91
+ const out = [];
92
+ for (const line of raw.split("\n")) {
93
+ if (!line.trim()) continue;
94
+ try { const row = JSON.parse(line); if (row && typeof row === "object") out.push(row); }
95
+ catch { /* a torn append is one lost line, not an empty plane */ }
96
+ }
97
+ return out;
98
+ }
99
+
100
+ /**
101
+ * `state/obligations/*.json` — the join target, pruned at the retention window.
102
+ * The `needs-attention/` subdirectory and the journal are skipped by extension.
103
+ * @param {string} agentRoot
104
+ * @returns {object[]}
105
+ */
106
+ export function readObligationRecords(agentRoot) {
107
+ const dir = obligationsDir(agentRoot);
108
+ let names = [];
109
+ try { names = readdirSync(dir); } catch { return []; }
110
+ const out = [];
111
+ for (const name of names) {
112
+ if (!name.endsWith(".json")) continue;
113
+ const rec = readJson(join(dir, name));
114
+ if (rec && typeof rec === "object" && rec.key) out.push(rec);
115
+ }
116
+ return out;
117
+ }
118
+
119
+ /**
120
+ * Read all three sinks and hand them to the pure join.
121
+ *
122
+ * `now` is a parameter, not a read: the digest the beat publishes and the screen
123
+ * an operator sees must be able to describe the same instant, and a test must be
124
+ * able to describe any instant at all.
125
+ *
126
+ * @param {object} [o] {agentRoot, now, windowMs, env}
127
+ * @returns {{incidents:object[], clusters:object[], summary:object|null,
128
+ * counts:{rows:number, journal:number, records:number},
129
+ * windowMs:number, now:number, agentRoot:string}}
130
+ */
131
+ export function readOperatorPlane(o = {}) {
132
+ const agentRoot = planeRoot(o);
133
+ const now = Number.isFinite(o.now) ? Number(o.now) : Date.now();
134
+ const windowMs = Number.isFinite(o.windowMs) && o.windowMs > 0 ? Number(o.windowMs) : planeWindowMs(o.env);
135
+ const rows = readNeedsAttention(agentRoot);
136
+ const journal = readNoticeJournal(agentRoot);
137
+ const records = readObligationRecords(agentRoot);
138
+ const grouped = groupIncidents({ rows, journal, records, now, windowMs });
139
+ const clusters = clusterIncidents(grouped.incidents);
140
+ const summary = summarisePlane({
141
+ incidents: grouped.incidents,
142
+ date: new Date(now).toISOString().slice(0, 10),
143
+ });
144
+ return {
145
+ agentRoot,
146
+ now,
147
+ windowMs,
148
+ incidents: grouped.incidents,
149
+ causes: grouped.causes,
150
+ clusters,
151
+ summary,
152
+ counts: { rows: rows.length, journal: journal.length, records: records.length },
153
+ journalPresent: existsSync(join(obligationsDir(agentRoot), "notice-journal.jsonl")),
154
+ };
155
+ }
156
+
157
+ export default {
158
+ planeRoot,
159
+ planeWindowMs,
160
+ readNeedsAttention,
161
+ readNoticeJournal,
162
+ readObligationRecords,
163
+ readOperatorPlane,
164
+ };