@cohortapp/agent-sdk 2.18.37 → 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.
package/bin/maestro.mjs CHANGED
@@ -3941,6 +3941,7 @@ switch (command) {
3941
3941
  case "board": await (await import("../lib/cli/board.mjs")).boardCmd(args); break;
3942
3942
  case "design": await (await import("../lib/cli/design.mjs")).designCmd(args); break;
3943
3943
  case "skills": process.exitCode = await (await import("../lib/cli/skills.mjs")).skillsCmd(args); break;
3944
+ case "attention": process.exitCode = await (await import("../lib/cli/attention.mjs")).attentionCmd(args); break;
3944
3945
  case "run": process.exitCode = await (await import("../lib/engine/cli.mjs")).runFromProcess(args); break;
3945
3946
  case "init":
3946
3947
  case "update-init":
@@ -3972,6 +3973,8 @@ Usage:
3972
3973
  npx @cohortapp/agent-sdk seat-auth [--row|--fleet] Which Claude billing rail this seat is on (G4) — variable NAMES only, never a value
3973
3974
  npx @cohortapp/agent-sdk session <cmd> Front-door session: status|attach|start|stop|restart|spawn|peers|handoffs|ack
3974
3975
  npx @cohortapp/agent-sdk board mine|track|claim|complete Your work across every board (maestro board --help)
3976
+ npx @cohortapp/agent-sdk attention list|clusters|show Dead asks in the operator plane, grouped (maestro attention --help)
3977
+ npx @cohortapp/agent-sdk skills list|show|approve Pending auto-authored skills, and the approval gate
3975
3978
  npx @cohortapp/agent-sdk design sync [--out <dir>] Pull the brand foundation → DESIGN.md + PRODUCT.md
3976
3979
  npx @cohortapp/agent-sdk run -p "<prompt>" [flags] Cohort Engine, headless (cohort run --help)
3977
3980
 
@@ -105,9 +105,22 @@ only doctor still sees it.
105
105
 
106
106
  ### The fleet inventory
107
107
 
108
- A seat's environment lives on the seat's own machine. There is no remote
109
- inventory mechanism and this tooling does not invent one. So the fleet report is
110
- a **template plus paste-able rows**: run `maestro seat-auth --fleet` once (it
108
+ **Start from the beat, not from a tour.** Every seat's presence beat now carries
109
+ its verdict as `machine.seatAuth = { rail, compliant }`, from the first SDK
110
+ release that carries this change onward (it landed after 2.18.37; the release
111
+ line is the SDK owner's, so read `machine.sdkVersion` rather than trusting a
112
+ number written here). "Which seats are still on subscription OAuth" is therefore
113
+ a query against the fleet view, not sixteen SSH sessions — use it to pick the
114
+ seats worth visiting. Two limits to know. The beat carries the rail and a
115
+ boolean and **nothing** that could identify a credential: not the values, not a
116
+ mask, not a key id or its last four, not even the variable names. And a seat on
117
+ an older SDK sends no `seatAuth` field at all, which is "unknown", not "clean".
118
+ The same beat carries `machine.engine`, so an `engine: cohort` seat reading
119
+ `neither` is correct, not broken.
120
+
121
+ The rest of a seat's environment lives on the seat's own machine, and the
122
+ Console-side facts live in the Console. So the fleet report is still a
123
+ **template plus paste-able rows**: run `maestro seat-auth --fleet` once (it
111
124
  pre-fills one row per member from the org directory), then on each machine run
112
125
  `maestro seat-auth --row` and paste the line over that seat's row. The measured
113
126
  columns — seat, agent id, machine, verdict, which variable names are present,
@@ -467,10 +467,15 @@ export default {
467
467
  * arriving from a seat that has not upgraded yet must still be recognised long
468
468
  * after the local composer that produced it has changed.
469
469
  */
470
+ /** `assurance.composeSilentSuccess`'s head. FROZEN LITERAL, see above. */
471
+ const SILENT_SUCCESS_HEAD = /^finished this but didn'?t get a reply out to you\s*[—–-]\s*my fault\b/i;
472
+ /** `assurance.composeRefusedSend`'s head. FROZEN LITERAL, see above. */
473
+ const REFUSED_SEND_HEAD = /^couldn'?t get this out to you\s*[—–-]\s*the send was blocked\b/i;
474
+
470
475
  const STATUS_NOTICE_PATTERNS = Object.freeze([
471
476
  // composeSilentSuccess — the recovery notice, with or without an excerpt.
472
477
  // The excerpt is unbounded prose, so this anchors on the head alone.
473
- /^finished this but didn'?t get a reply out to you\s*[—–-]\s*my fault\b/i,
478
+ SILENT_SUCCESS_HEAD,
474
479
  // composeInterrupted.
475
480
  /^heads up\s*[—–-]\s*my session on this was interrupted\b/i,
476
481
  // notice-voice's generated failure/progress lines, which name the topic:
@@ -485,9 +490,33 @@ const STATUS_NOTICE_PATTERNS = Object.freeze([
485
490
  // precisely when an emitted notice was not recognisable to the seat receiving
486
491
  // it: the gate missed, the notice was dispatched as an ask, and the answering
487
492
  // seat's own rescue fired back.
488
- /^couldn'?t get this out to you\s*[\u2014\u2013-]\s*the send was blocked\b/i,
493
+ REFUSED_SEND_HEAD,
489
494
  ]);
490
495
 
496
+ /**
497
+ * Does this body OPEN as one of the two assurance rescue notices \u2014 the
498
+ * silent-success or the send-refused wrapper \u2014 whatever follows the head?
499
+ *
500
+ * THE OUTBOUND BACKSTOP for the late-reply fallback. Those two composers wrap a
501
+ * session's own end-of-turn text in a sentence that apologises for it, and the
502
+ * end-of-turn text is the session's report to the process that spawned it: its
503
+ * file paths, its queue ids, its "a concurrent session". `settleSession` no
504
+ * longer sends either wrapper to anyone (the text is held in the operator
505
+ * plane); `deliver()` refuses any body this returns true for, so a stale caller
506
+ * or a branch added later cannot put the wrapper back in a conversation.
507
+ *
508
+ * The OPENING paragraph only, on purpose: a real reply that quotes the phrase
509
+ * further down is not the wrapper.
510
+ *
511
+ * @param {unknown} body
512
+ * @returns {boolean}
513
+ */
514
+ export function opensAsRescueNotice(body) {
515
+ const head = normaliseLine(String(body == null ? "" : body).trim().split(/\n\s*\n/, 1)[0]);
516
+ if (!head) return false;
517
+ return SILENT_SUCCESS_HEAD.test(head) || REFUSED_SEND_HEAD.test(head);
518
+ }
519
+
491
520
  /**
492
521
  * Is this body a seat narrating its own work, rather than asking for any?
493
522
  *
@@ -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
+ };