@cohortapp/agent-sdk 2.18.36 → 2.18.37
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/docs/runbooks/cadence-requeue-storm-recovery.md +186 -0
- package/lib/assurance/first-reply.mjs +16 -0
- package/lib/assurance/notice-plane.mjs +218 -0
- package/lib/assurance/notice-voice.mjs +35 -2
- package/lib/budget-escalate.mjs +42 -4
- package/lib/cadence-bus.mjs +359 -46
- package/lib/comms/machine-status.mjs +377 -0
- package/package.json +1 -1
- package/scripts/ci/check-durable-write-seam.mjs +3 -3
- package/scripts/daemon/assurance.mjs +391 -15
- package/scripts/daemon/cadence-consumer.mjs +165 -9
- package/scripts/daemon/deliver.mjs +104 -0
|
@@ -98,6 +98,20 @@ import {
|
|
|
98
98
|
noticeRejection,
|
|
99
99
|
fallbackNotice,
|
|
100
100
|
} from "../../lib/assurance/notice-voice.mjs";
|
|
101
|
+
// WHERE A NOTICE GOES — and the answer is never "to a person". This is the
|
|
102
|
+
// decision the wording iterations kept skipping; `notice-plane.mjs` carries the
|
|
103
|
+
// argument and the table, and the table's default for an unregistered notice is
|
|
104
|
+
// the operator plane, so a new notice kind is silent to people until someone
|
|
105
|
+
// deliberately says otherwise under that header.
|
|
106
|
+
import { noticePlane, mayReachHuman, NOTICE_PLANE } from "../../lib/assurance/notice-plane.mjs";
|
|
107
|
+
// The SHAPE of a machine narrating itself, as ONE shared vocabulary with TWO
|
|
108
|
+
// thresholds. This file asks the inbound question ("is this peer's message a
|
|
109
|
+
// notice?") and needs only the predicate, because it has already established the
|
|
110
|
+
// sender is a seat; `deliver.mjs` asks the outbound one ("may this body leave?")
|
|
111
|
+
// and needs the apparatus subject too, because it does not know who wrote it.
|
|
112
|
+
// Both read the same lists, so a phrase added for one is live for both. The
|
|
113
|
+
// difference in thresholds is argued at `hasStatusPredicate`.
|
|
114
|
+
import { hasStatusPredicate } from "../../lib/comms/machine-status.mjs";
|
|
101
115
|
import { isRetiredFirstReply, firstReplyShape, REACTIONS, statesNoReplyOwed } from "../../lib/assurance/first-reply.mjs";
|
|
102
116
|
// The unit of acknowledgement is the CONVERSATION, not the message: four
|
|
103
117
|
// messages in a row earn ONE first response that was written with all four in
|
|
@@ -507,7 +521,13 @@ export function looksLikePeerOutcomeNotice(item) {
|
|
|
507
521
|
if (REQUEST_MARKER.test(content)) return false;
|
|
508
522
|
if (IMPERATIVE_OPENER.test(content)) return false;
|
|
509
523
|
if (!/\b(i|my|i'?ve|i'?m)\b/i.test(content)) return false;
|
|
510
|
-
|
|
524
|
+
// ONE VOCABULARY, SHARED WITH THE OUTBOUND REFUSAL. This predicate list used
|
|
525
|
+
// to be a literal here, duplicating the one the outbound screen needs. The two
|
|
526
|
+
// now read `lib/comms/machine-status.mjs`, so the shape this seat REFUSES TO
|
|
527
|
+
// SEND and the shape it REFUSES TO ACK are the same shape by construction —
|
|
528
|
+
// the `narratorPatterns` convention: emitter and recogniser are edited
|
|
529
|
+
// together or not at all. A phrase added for one is live for both.
|
|
530
|
+
return hasStatusPredicate(content);
|
|
511
531
|
}
|
|
512
532
|
|
|
513
533
|
/**
|
|
@@ -596,10 +616,18 @@ export function narratorPatterns() {
|
|
|
596
616
|
// rest — if this gate cannot recognise it, a peer's refusal notice arrives
|
|
597
617
|
// as an ordinary ask, earns an ack and spawns a session behind it, which is
|
|
598
618
|
// the loop that produced 142 of 188 notices on 2026-09-30.
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
619
|
+
// BOTH CAUSE SHAPES, because the cause clause is now a MAPPED phrase and an
|
|
620
|
+
// unmapped code yields no clause at all. A pattern derived only from the
|
|
621
|
+
// clause-bearing shape has a mandatory `\(…\)` in it and silently stops
|
|
622
|
+
// matching every refusal whose code this tree does not know — which is the
|
|
623
|
+
// half the self-echo gate most needs, since an unknown code is what an older
|
|
624
|
+
// or newer peer emits.
|
|
625
|
+
...[true, false].flatMap((permanent) =>
|
|
626
|
+
[undefined, CAUSE].flatMap((finalText) =>
|
|
627
|
+
[CAUSE, ""].map((causePhrase) =>
|
|
628
|
+
composeRefusedSend({}, { why: { code: CAUSE, permanent }, finalText, causePhrase })),
|
|
629
|
+
),
|
|
630
|
+
),
|
|
603
631
|
];
|
|
604
632
|
// GLOBAL, not first-occurrence. `String.prototype.replace` with a string
|
|
605
633
|
// pattern substitutes once, so a template carrying the sentinel twice — a
|
|
@@ -1247,6 +1275,27 @@ export async function generateFailureNotice(rec, o = {}, opts = {}) {
|
|
|
1247
1275
|
|
|
1248
1276
|
const run = typeof opts.runImpl === "function" ? opts.runImpl : runAckModel;
|
|
1249
1277
|
const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : NOTICE_GEN_TIMEOUT_MS;
|
|
1278
|
+
// NOBODY READS THIS, SO DO NOT PAY A MODEL TO WRITE IT.
|
|
1279
|
+
//
|
|
1280
|
+
// Every notice kind is operator-plane (`lib/assurance/notice-plane.mjs`), so
|
|
1281
|
+
// the destination of this text is a log line and a journal row — and a model
|
|
1282
|
+
// spawn to make a log line read nicely is a cold `claude --print` per dead
|
|
1283
|
+
// obligation per sweep, bounded at NOTICE_GEN_TIMEOUT_MS, for prose no person
|
|
1284
|
+
// will see. The deterministic sentence is the right artifact for the operator
|
|
1285
|
+
// plane and always was.
|
|
1286
|
+
//
|
|
1287
|
+
// `degraded` is FALSE: nothing is broken, this is the design. The counter
|
|
1288
|
+
// records the real reason so the `notice.generation_failed` rates stay
|
|
1289
|
+
// meaningful rather than being swamped by a path that was never going to run.
|
|
1290
|
+
//
|
|
1291
|
+
// The test seam still overrides, so `notice-emission.test.mjs` can keep
|
|
1292
|
+
// exercising the generator's guards (`claimsSuccess`, `inventsFacts`, the
|
|
1293
|
+
// register) against a stub — those guards remain the defence for any future
|
|
1294
|
+
// caller that is genuinely human-facing.
|
|
1295
|
+
if (typeof opts.runImpl !== "function" && !mayReachHuman(kind)) {
|
|
1296
|
+
counters.bump("notice.generation_skipped", { notice: kind, reason: "operator-plane" });
|
|
1297
|
+
return { text: degradedText(), generated: false, degraded: false, cause, plane: NOTICE_PLANE.OPERATOR };
|
|
1298
|
+
}
|
|
1250
1299
|
if (typeof opts.runImpl !== "function" && !noticeGenEnabled()) {
|
|
1251
1300
|
counters.bump("notice.generation_skipped", { notice: kind, reason: "disabled" });
|
|
1252
1301
|
return { text: degradedText(), generated: false, degraded: true, cause };
|
|
@@ -1272,7 +1321,7 @@ export async function generateFailureNotice(rec, o = {}, opts = {}) {
|
|
|
1272
1321
|
const verdict = noticeRejection(raw, { source: noticeSource(promptArgs) });
|
|
1273
1322
|
if (verdict.ok) return { text: verdict.text, generated: true, degraded: false, cause };
|
|
1274
1323
|
counters.bump("notice.generation_failed", { cause: `unusable:${verdict.reason}`, notice: kind });
|
|
1275
|
-
console.warn(`[assurance] ${kind} notice generation produced nothing usable [${verdict.reason}] —
|
|
1324
|
+
console.warn(`[assurance] ${kind} notice generation produced nothing usable [${verdict.reason}] — falling back to the plain sentence (a dead ask is never left unrecorded)`);
|
|
1276
1325
|
return { text: degradedText(), generated: false, degraded: true, cause, rejected: verdict.reason };
|
|
1277
1326
|
} catch (err) {
|
|
1278
1327
|
const msg = String((err && err.message) || "");
|
|
@@ -1280,7 +1329,7 @@ export async function generateFailureNotice(rec, o = {}, opts = {}) {
|
|
|
1280
1329
|
: /spawn error|ENOENT|EACCES/i.test(msg) ? "spawn_failed"
|
|
1281
1330
|
: "error";
|
|
1282
1331
|
counters.bump("notice.generation_failed", { cause: why, notice: kind });
|
|
1283
|
-
console.warn(`[assurance] ${kind} notice generation failed (${msg}) —
|
|
1332
|
+
console.warn(`[assurance] ${kind} notice generation failed (${msg}) — falling back to the plain sentence [cause:${why}]`);
|
|
1284
1333
|
return { text: degradedText(), generated: false, degraded: true, cause };
|
|
1285
1334
|
}
|
|
1286
1335
|
}
|
|
@@ -1314,6 +1363,69 @@ export function composeSilentSuccess(rec, o = {}) {
|
|
|
1314
1363
|
return `${head} I don't have a clean result to show you, though. Want me to run it again?`;
|
|
1315
1364
|
}
|
|
1316
1365
|
|
|
1366
|
+
/**
|
|
1367
|
+
* A machine send-block code → the one clause a PERSON can do something with.
|
|
1368
|
+
*
|
|
1369
|
+
* ── WHY A TABLE AND NOT THE RAW REASON ──────────────────────────────────────
|
|
1370
|
+
*
|
|
1371
|
+
* The previous version interpolated `why.reason` — the no-send receipt's own
|
|
1372
|
+
* `frame.error` string — straight into a body a human reads. Two things are
|
|
1373
|
+
* wrong with that, and the second one only became visible once this branch
|
|
1374
|
+
* landed:
|
|
1375
|
+
*
|
|
1376
|
+
* 1. It is machine noise. "FORBIDDEN_SCOPE: blocked by send-gate" is the
|
|
1377
|
+
* exact register this subsystem keeps being told to stop writing in.
|
|
1378
|
+
* 2. THE GATES' OWN REFUSAL MESSAGES ARE NOW AMONG THOSE REASONS. `deliver`
|
|
1379
|
+
* records `code:"FORBIDDEN_SCOPE", error:'machine-status kind "failure"
|
|
1380
|
+
* may not be delivered to a conversation — route it to the operator
|
|
1381
|
+
* plane'`, and `noteNoSend` writes that verbatim into the receipt this
|
|
1382
|
+
* composer reads. So the fix for broken machine messages could compose a
|
|
1383
|
+
* broken machine message that quoted the gate which stopped it.
|
|
1384
|
+
*
|
|
1385
|
+
* The raw string is not lost and an operator never has to guess: it is in the
|
|
1386
|
+
* no-send receipt, in the `needs-attention` row and in the notice journal, which
|
|
1387
|
+
* is where it is read. The person gets what it means for them.
|
|
1388
|
+
*
|
|
1389
|
+
* THE DEFAULT IS NO CLAUSE AT ALL, not a fallback to the raw text. That is the
|
|
1390
|
+
* structural half: an unmapped or newly-invented code cannot reach a person as
|
|
1391
|
+
* machine prose, because this function has no path that returns `why.reason`.
|
|
1392
|
+
* Add a row here when a new code starts appearing in receipts.
|
|
1393
|
+
*
|
|
1394
|
+
* @type {Readonly<Record<string,string>>}
|
|
1395
|
+
*/
|
|
1396
|
+
export const SEND_BLOCK_PHRASES = Object.freeze({
|
|
1397
|
+
FORBIDDEN_SCOPE: "I don't have permission to post there",
|
|
1398
|
+
HOOK_BLOCKED: "the wording got stopped by our own outbound rules",
|
|
1399
|
+
BANNED_PHRASE: "the wording got stopped by our own outbound rules",
|
|
1400
|
+
FORBIDDEN: "I don't have permission to post there",
|
|
1401
|
+
403: "I don't have permission to post there",
|
|
1402
|
+
NOT_A_MEMBER: "I'm not in that conversation",
|
|
1403
|
+
CHANNEL_NOT_FOUND: "that conversation wasn't reachable from here",
|
|
1404
|
+
404: "that conversation wasn't reachable from here",
|
|
1405
|
+
UNAUTHORIZED: "my access to that workspace wasn't accepted",
|
|
1406
|
+
401: "my access to that workspace wasn't accepted",
|
|
1407
|
+
RATE_LIMITED: "the channel was rate-limiting me",
|
|
1408
|
+
429: "the channel was rate-limiting me",
|
|
1409
|
+
NETWORK: "the network dropped on the way out",
|
|
1410
|
+
ETIMEDOUT: "the network dropped on the way out",
|
|
1411
|
+
ECONNRESET: "the network dropped on the way out",
|
|
1412
|
+
});
|
|
1413
|
+
|
|
1414
|
+
/**
|
|
1415
|
+
* The human-facing cause clause for a blocked send, or "" when there isn't one.
|
|
1416
|
+
*
|
|
1417
|
+
* @param {object} why a `noSendFor` verdict (`{code, reason, permanent, …}`)
|
|
1418
|
+
* @returns {string} a phrase, never a machine string, possibly empty
|
|
1419
|
+
*/
|
|
1420
|
+
export function humanSendBlockPhrase(why = {}) {
|
|
1421
|
+
const code = why && why.code != null ? String(why.code).trim() : "";
|
|
1422
|
+
if (!code) return "";
|
|
1423
|
+
const key = code.toUpperCase();
|
|
1424
|
+
if (Object.prototype.hasOwnProperty.call(SEND_BLOCK_PHRASES, key)) return SEND_BLOCK_PHRASES[key];
|
|
1425
|
+
if (Object.prototype.hasOwnProperty.call(SEND_BLOCK_PHRASES, code)) return SEND_BLOCK_PHRASES[code];
|
|
1426
|
+
return "";
|
|
1427
|
+
}
|
|
1428
|
+
|
|
1317
1429
|
/**
|
|
1318
1430
|
* The case `composeSilentSuccess` was apologising for by mistake: a send that
|
|
1319
1431
|
* WAS attempted and was STOPPED, with a recorded cause.
|
|
@@ -1347,11 +1459,14 @@ export function composeSilentSuccess(rec, o = {}) {
|
|
|
1347
1459
|
*/
|
|
1348
1460
|
export function composeRefusedSend(rec, o = {}) {
|
|
1349
1461
|
const why = o.why || {};
|
|
1350
|
-
|
|
1351
|
-
|
|
1352
|
-
//
|
|
1353
|
-
//
|
|
1354
|
-
|
|
1462
|
+
// `o.causePhrase` is a PATTERN SEAM, not an escape hatch for a caller. The
|
|
1463
|
+
// cause slot is a MAPPED phrase now, and `narratorPatterns` has to derive a
|
|
1464
|
+
// template carrying its regex sentinel in that slot — otherwise the self-echo
|
|
1465
|
+
// gate stops recognising this seat's own refusal notices, a peer's refusal
|
|
1466
|
+
// arrives as an ordinary ask, and the 142-of-188 loop restarts. Nothing on the
|
|
1467
|
+
// delivery path passes it; `assurance-no-send-gate.test.mjs` pins that no raw
|
|
1468
|
+
// receipt string can reach the body through `why`.
|
|
1469
|
+
const cause = typeof o.causePhrase === "string" ? o.causePhrase : humanSendBlockPhrase(why);
|
|
1355
1470
|
const head = `Couldn't get this out to you — the send was blocked${cause ? ` (${cause})` : ""}.`;
|
|
1356
1471
|
// Never promise a retry this path does not perform. The silent-success branch
|
|
1357
1472
|
// has no retry loop — that lives in the failure branch — so a permanent cause
|
|
@@ -1582,7 +1697,13 @@ export const NOTICE = Object.freeze({
|
|
|
1582
1697
|
FAILURE_RETRYING: "failure:retrying",
|
|
1583
1698
|
FAILURE_FINAL: "failure:final",
|
|
1584
1699
|
INTERRUPTED: "interrupted",
|
|
1700
|
+
// The two answer-or-nothing ids. Both of these have a HUMAN shape (the one
|
|
1701
|
+
// that carries the session's result text, delivered as a `reply`) and an
|
|
1702
|
+
// OPERATOR shape (the same composer with no result text, which is a template
|
|
1703
|
+
// about this machine's own run). Only the operator shape reaches here, and
|
|
1704
|
+
// `notice-plane.NOTICE_PLANES` declares it operator like all the rest.
|
|
1585
1705
|
SILENT_SUCCESS: "silent-success",
|
|
1706
|
+
SEND_REFUSED: "send-refused",
|
|
1586
1707
|
});
|
|
1587
1708
|
|
|
1588
1709
|
/**
|
|
@@ -1650,9 +1771,129 @@ export function markNoticeSaid(rec, notice, now) {
|
|
|
1650
1771
|
* @param {function} [o.roomNoticeImpl] test seam for the room-scoped dedupe
|
|
1651
1772
|
* @returns {Promise<{sent:boolean, reason:string}>}
|
|
1652
1773
|
*/
|
|
1774
|
+
/**
|
|
1775
|
+
* THE OPERATOR SINK — where a machine's status about itself actually goes.
|
|
1776
|
+
*
|
|
1777
|
+
* This replaces the send, it does not accompany it. The three things an operator
|
|
1778
|
+
* needs are all written here or beside it:
|
|
1779
|
+
*
|
|
1780
|
+
* THE ROW `escalate` writes `needs-attention/<key>.json` on every one of
|
|
1781
|
+
* these failures, carrying the key, the sender, the cause, the
|
|
1782
|
+
* trace id and the session id — strictly more than the DM ever
|
|
1783
|
+
* said. That is unchanged and is written by the caller.
|
|
1784
|
+
* THE JOURNAL this function appends one line per (obligation, notice) to
|
|
1785
|
+
* `state/obligations/notice-journal.jsonl`, so the sequence of
|
|
1786
|
+
* what a seat decided about a dead ask is readable in order
|
|
1787
|
+
* rather than reconstructed from a row that only holds the last
|
|
1788
|
+
* state. Append-only, one line, no prose a model wrote.
|
|
1789
|
+
* THE COUNTER `assurance.notice_to_operator`, broken out by notice and
|
|
1790
|
+
* reason, so the volume is a number on a health surface instead
|
|
1791
|
+
* of a thing a person notices in their DMs.
|
|
1792
|
+
*
|
|
1793
|
+
* ONCE-ONLY, DURABLY, AND IT IS THE LATCH THAT ALREADY EXISTED.
|
|
1794
|
+
* `noticeAlreadySaid` / `markNoticeSaid` are keyed on
|
|
1795
|
+
* (channel, obligationKey, notice) and INHERITED across a retry that reopens the
|
|
1796
|
+
* same key (`openAndAcknowledge`), so one dead ask yields one journal line
|
|
1797
|
+
* however many sweeps, retries and daemon restarts touch it. Checking it here
|
|
1798
|
+
* rather than only on the human path is what makes "the same thing twice" a
|
|
1799
|
+
* property of the sink too — the owner received the same sentence twice eleven
|
|
1800
|
+
* minutes apart, and a sink that appends twice would have reproduced that defect
|
|
1801
|
+
* in the log it replaced the DM with.
|
|
1802
|
+
*
|
|
1803
|
+
* THE TEXT IS KEPT, deliberately. It is the deterministic sentence (no model is
|
|
1804
|
+
* spawned for an operator line — see `generateFailureNotice`), and it is the
|
|
1805
|
+
* most readable one-line statement of what happened that this code can produce.
|
|
1806
|
+
* An operator reading the journal wants it. A person in a conversation does not,
|
|
1807
|
+
* which is the entire distinction this module draws.
|
|
1808
|
+
*
|
|
1809
|
+
* Never throws: a sink that can fail the sweep is worse than a sink that loses a
|
|
1810
|
+
* line, and the escalation row is written independently by the caller.
|
|
1811
|
+
*
|
|
1812
|
+
* @param {object} o {rec, notice, text, now, reason}
|
|
1813
|
+
* @returns {{sent:false, reason:string, plane:string, journalled:boolean}}
|
|
1814
|
+
*/
|
|
1815
|
+
function recordOperatorNotice(o = {}) {
|
|
1816
|
+
const { rec, notice, text, now } = o;
|
|
1817
|
+
const already = noticeAlreadySaid(rec, notice);
|
|
1818
|
+
if (!already) {
|
|
1819
|
+
markNoticeSaid(rec, notice, now);
|
|
1820
|
+
// THE SINK PERSISTS ITS OWN LATCH. `markNoticeSaid` mutates `rec` and
|
|
1821
|
+
// documents that the caller writes it — which was true of the failure branch
|
|
1822
|
+
// (`writeRecord` immediately after `sayOutcomeNotice`) and NOT of the paths
|
|
1823
|
+
// that go straight to `closeObligation`, because `closeObligation` re-reads
|
|
1824
|
+
// the record from disk and the in-memory mark is lost. The once-only property
|
|
1825
|
+
// is this function's guarantee, so this function makes it durable rather than
|
|
1826
|
+
// depending on what each caller happens to do next.
|
|
1827
|
+
try { writeRecord(rec); } catch { /* best-effort: a lost latch is one extra row, not a lost debt */ }
|
|
1828
|
+
}
|
|
1829
|
+
counters.bump("assurance.notice_to_operator", {
|
|
1830
|
+
notice,
|
|
1831
|
+
reason: o.reason || "declared-operator",
|
|
1832
|
+
repeat: already ? "suppressed" : "first",
|
|
1833
|
+
});
|
|
1834
|
+
if (already) {
|
|
1835
|
+
return { sent: false, reason: "operator-plane-already-recorded", plane: NOTICE_PLANE.OPERATOR, journalled: false };
|
|
1836
|
+
}
|
|
1837
|
+
let journalled = false;
|
|
1838
|
+
try {
|
|
1839
|
+
const line = JSON.stringify({
|
|
1840
|
+
at: new Date(Number.isFinite(now) ? now : Date.now()).toISOString(),
|
|
1841
|
+
notice,
|
|
1842
|
+
key: rec && rec.key,
|
|
1843
|
+
service: rec && rec.service,
|
|
1844
|
+
channel: rec && rec.channel,
|
|
1845
|
+
sender: (rec && rec.sender) || null,
|
|
1846
|
+
cause: (rec && rec.lastError) || null,
|
|
1847
|
+
attempts: (rec && rec.attempts) || 0,
|
|
1848
|
+
sessionId: (rec && rec.sessionId) || null,
|
|
1849
|
+
traceId: (rec && rec.traceId) || null,
|
|
1850
|
+
// The plane, on every row, so a reader of the journal never has to wonder
|
|
1851
|
+
// whether this one also went to a person. None of them do.
|
|
1852
|
+
plane: NOTICE_PLANE.OPERATOR,
|
|
1853
|
+
requesterTold: false,
|
|
1854
|
+
statusLine: typeof text === "string" ? text.slice(0, 400) : null,
|
|
1855
|
+
});
|
|
1856
|
+
appendFileSync(join(obligationDir(), "notice-journal.jsonl"), `${line}\n`);
|
|
1857
|
+
journalled = true;
|
|
1858
|
+
} catch (err) {
|
|
1859
|
+
console.error(`[assurance] could not journal ${notice} for ${rec && rec.key}: ${err && err.message}`);
|
|
1860
|
+
}
|
|
1861
|
+
console.log(`[assurance] ${notice} for ${rec && rec.key} → operator plane (${o.reason || "declared-operator"}); no conversation was told. Cause: ${(rec && rec.lastError) || "unknown"}`);
|
|
1862
|
+
return { sent: false, reason: "operator-plane", plane: NOTICE_PLANE.OPERATOR, journalled };
|
|
1863
|
+
}
|
|
1864
|
+
|
|
1653
1865
|
async function sayOutcomeNotice(o) {
|
|
1654
1866
|
const { rec, notice, text, item, kind, now } = o;
|
|
1655
1867
|
|
|
1868
|
+
// ── THE PLANE DECISION, BEFORE EVERYTHING ELSE ───────────────────────────
|
|
1869
|
+
//
|
|
1870
|
+
// This is the question this subsystem never asked, and the reason the owner
|
|
1871
|
+
// received a new variant after each of three fixes. Everything below this
|
|
1872
|
+
// point — two dedupes, a document-surface test, a room claim — is about HOW
|
|
1873
|
+
// MANY copies of a message a person gets and WHAT WORDS it wears. The answer
|
|
1874
|
+
// is that they get none: status about this machine's own apparatus is not a
|
|
1875
|
+
// message to a person. The argument, the measured costs, and the narrow case
|
|
1876
|
+
// that does NOT survive are in `lib/assurance/notice-plane.mjs`. Read that
|
|
1877
|
+
// before changing this line.
|
|
1878
|
+
//
|
|
1879
|
+
// WHY HERE AND NOT ONLY AT THE TRANSPORT. `deliver()` refuses these kinds too,
|
|
1880
|
+
// and that is the backstop for a caller nobody has written yet. But a refusal
|
|
1881
|
+
// at the transport produces the DEBRIS of an attempted send: a no-send
|
|
1882
|
+
// receipt, a `{sent:false}` the caller reads as "the room heard nothing", and
|
|
1883
|
+
// an escalation row whose `requesterWasTold:false` is right by accident.
|
|
1884
|
+
// Deciding here writes the operator plane a deliberate record instead.
|
|
1885
|
+
//
|
|
1886
|
+
// WHY IT IS ABOVE THE DOCUMENT TEST. The document test is a SURFACE test, and
|
|
1887
|
+
// it was the last iteration of the old axis — withhold on one more surface. It
|
|
1888
|
+
// is kept below rather than deleted because it answers a different question
|
|
1889
|
+
// and would be the only guard still standing if anyone ever registers a
|
|
1890
|
+
// human-facing notice in `NOTICE_PLANES`. For every notice that exists today,
|
|
1891
|
+
// this block returns first.
|
|
1892
|
+
const plane = noticePlane(notice);
|
|
1893
|
+
if (!plane.human) {
|
|
1894
|
+
return recordOperatorNotice({ rec, notice, text, now, reason: plane.reason });
|
|
1895
|
+
}
|
|
1896
|
+
|
|
1656
1897
|
// ── NO OUTCOME NOTICE REACHES A DOCUMENT, AT THE CHOKEPOINT ───────────────
|
|
1657
1898
|
//
|
|
1658
1899
|
// 2.18.30 put this test in `settleSession`, which covered the failed,
|
|
@@ -2157,7 +2398,37 @@ export async function settleSession(a = {}) {
|
|
|
2157
2398
|
// shared room when nobody asked, and this is not narration — it is the
|
|
2158
2399
|
// one line that says a message this seat owed was stopped, plus its cause.
|
|
2159
2400
|
// Withholding it is how a blocked send lane stays invisible for days.
|
|
2401
|
+
//
|
|
2402
|
+
// ── BUT ONLY WHEN IT CARRIES THE ANSWER ────────────────────────────────
|
|
2403
|
+
//
|
|
2404
|
+
// That paragraph is true of the FAULT, not of the sentence. The fault has
|
|
2405
|
+
// to reach somebody; nothing says that somebody is the person in the
|
|
2406
|
+
// conversation. With the session's result text this message hands them the
|
|
2407
|
+
// work AND explains why it arrived late — a reply. Without it, all that is
|
|
2408
|
+
// left is "Couldn't get this out to you — the send was blocked (…). That
|
|
2409
|
+
// won't clear on its own": a template about this machine's own plumbing,
|
|
2410
|
+
// nothing the reader can do, and unactionable by the very reasoning in
|
|
2411
|
+
// `notice-plane.mjs` that silenced the failure notices. So the split is by
|
|
2412
|
+
// WHAT THE BODY CARRIES, not by which composer produced it — and the
|
|
2413
|
+
// operator sink gets strictly more than the sentence did, including the
|
|
2414
|
+
// raw code that no longer goes to a person.
|
|
2160
2415
|
const finalText = safeResultText(a.stdout);
|
|
2416
|
+
if (!finalText) {
|
|
2417
|
+
const res = await sayOutcomeNotice({
|
|
2418
|
+
rec, notice: NOTICE.SEND_REFUSED, text: composeRefusedSend(rec, { why }),
|
|
2419
|
+
item, kind: "notice", idempotencySuffix: `refused-${rec.attempts || 0}`, now, send,
|
|
2420
|
+
roomNoticeImpl: a.deps && a.deps.roomNoticeImpl,
|
|
2421
|
+
});
|
|
2422
|
+
rec.lastError = `send refused: ${why.code || "no code"}${why.reason ? ` — ${String(why.reason).slice(0, 200)}` : ""}`;
|
|
2423
|
+
escalate(rec, { failure: { label: rec.lastError }, now, told: false });
|
|
2424
|
+
closeObligation(a.key, {
|
|
2425
|
+
outcome: "undeliverable",
|
|
2426
|
+
now,
|
|
2427
|
+
note: `send refused (${why.code || "no code"}${why.surface ? ` on ${why.surface}` : ""}) and the session produced no result text; recorded in the operator plane, no conversation told`,
|
|
2428
|
+
});
|
|
2429
|
+
counters.bump("assurance.no_send_refused", { service: rec.service, code: why.code || "none", plane: "operator" });
|
|
2430
|
+
return { spoke: false, text: null, verdict: "send-refused", willRetry: false, noSend: why, plane: res.plane };
|
|
2431
|
+
}
|
|
2161
2432
|
const text = composeRefusedSend(rec, { why, finalText });
|
|
2162
2433
|
const res = await send(item, text, {
|
|
2163
2434
|
kind: "reply",
|
|
@@ -2170,7 +2441,7 @@ export async function settleSession(a = {}) {
|
|
|
2170
2441
|
now,
|
|
2171
2442
|
note: `send refused (${why.code || "no code"}${why.surface ? ` on ${why.surface}` : ""}); ${res && res.sent ? "cause reported to the room" : `cause also undeliverable: ${res && res.error}`}`,
|
|
2172
2443
|
});
|
|
2173
|
-
counters.bump("assurance.no_send_refused", { service: rec.service, code: why.code || "none" });
|
|
2444
|
+
counters.bump("assurance.no_send_refused", { service: rec.service, code: why.code || "none", plane: "human" });
|
|
2174
2445
|
return { spoke: !!(res && res.sent), text, verdict: "send-refused", willRetry: false, noSend: why };
|
|
2175
2446
|
}
|
|
2176
2447
|
|
|
@@ -2225,6 +2496,49 @@ export async function settleSession(a = {}) {
|
|
|
2225
2496
|
return { spoke: false, text: null, verdict: "silent-success", willRetry: false };
|
|
2226
2497
|
}
|
|
2227
2498
|
|
|
2499
|
+
// ── NO RESULT TEXT IS NOT AN ANSWER, SO IT IS NOT A REPLY ───────────────
|
|
2500
|
+
//
|
|
2501
|
+
// `composeSilentSuccess` has two shapes and only one of them is a reply.
|
|
2502
|
+
// WITH the session's result text it hands the asker the work their session
|
|
2503
|
+
// produced but never sent — that is the entire reason this rescue exists,
|
|
2504
|
+
// and it must go out. WITHOUT it, the whole message is:
|
|
2505
|
+
//
|
|
2506
|
+
// Finished this but didn't get a reply out to you — my fault. I don't
|
|
2507
|
+
// have a clean result to show you, though. Want me to run it again?
|
|
2508
|
+
//
|
|
2509
|
+
// which is "my session finished, you got nothing, shall I try again" — a
|
|
2510
|
+
// template about this machine's own run with no work product in it, i.e.
|
|
2511
|
+
// precisely the category the owner complained about twice. This repo's own
|
|
2512
|
+
// canonical recogniser agrees: `first-reply.isAgentStatusNotice` returns
|
|
2513
|
+
// true for it, and `STATUS_NOTICE_PATTERNS` lists its head as a frozen
|
|
2514
|
+
// literal of the status-notice family.
|
|
2515
|
+
//
|
|
2516
|
+
// WHY IT SURVIVED THE FIRST PASS OF THIS FIX, which is worth recording
|
|
2517
|
+
// because it is the same shape as every earlier miss: it is delivered with
|
|
2518
|
+
// `kind:"reply"`, so the origin gate (keyed on `kind`) never sees it, and it
|
|
2519
|
+
// names no apparatus noun, so the shape gate does not either. Both gates are
|
|
2520
|
+
// about machine STATUS and this is machine status wearing a reply's kind.
|
|
2521
|
+
// The first pass then PINNED it as a reply that must go out, on the reading
|
|
2522
|
+
// that `composeSilentSuccess` "carries the answer" — true of one of its two
|
|
2523
|
+
// shapes. The split is by what the body carries, never by which function
|
|
2524
|
+
// composed it.
|
|
2525
|
+
if (!finalText) {
|
|
2526
|
+
const res = await sayOutcomeNotice({
|
|
2527
|
+
rec, notice: NOTICE.SILENT_SUCCESS, text: composeSilentSuccess(rec, {}),
|
|
2528
|
+
item, kind: "notice", idempotencySuffix: `rescue-${rec.attempts || 0}`, now, send,
|
|
2529
|
+
roomNoticeImpl: a.deps && a.deps.roomNoticeImpl,
|
|
2530
|
+
});
|
|
2531
|
+
rec.lastError = rec.lastError || "session exited 0, sent nothing, produced no result text";
|
|
2532
|
+
escalate(rec, { failure: { label: "session exited 0 with no result text and nothing sent" }, now, told: false });
|
|
2533
|
+
closeObligation(a.key, {
|
|
2534
|
+
outcome: "undeliverable",
|
|
2535
|
+
now,
|
|
2536
|
+
note: "session exited 0 without speaking and produced no result text; recorded in the operator plane, no conversation told",
|
|
2537
|
+
});
|
|
2538
|
+
counters.bump("assurance.silent_success_to_operator", { service: rec.service });
|
|
2539
|
+
return { spoke: false, text: null, verdict: "silent-success", willRetry: false, plane: res.plane };
|
|
2540
|
+
}
|
|
2541
|
+
|
|
2228
2542
|
const text = composeSilentSuccess(rec, { finalText });
|
|
2229
2543
|
const res = await send(item, text, {
|
|
2230
2544
|
kind: "reply",
|
|
@@ -2971,9 +3285,63 @@ async function _sweepObligations(a = {}) {
|
|
|
2971
3285
|
}
|
|
2972
3286
|
|
|
2973
3287
|
pruneObligations({ now });
|
|
3288
|
+
pruneNoticeJournal({ now });
|
|
2974
3289
|
return stats;
|
|
2975
3290
|
}
|
|
2976
3291
|
|
|
3292
|
+
/**
|
|
3293
|
+
* Trim the operator notice journal to the retention window.
|
|
3294
|
+
*
|
|
3295
|
+
* WHY THIS EXISTS AND WHY IT IS A REWRITE RATHER THAN A DELETE. The journal
|
|
3296
|
+
* replaced a message, so it had better not have the defect the message had: it
|
|
3297
|
+
* is append-only, one line per dead ask, deliberately NOT coalesced (an operator
|
|
3298
|
+
* who sees one row of twenty has been told nineteen lies by omission). That
|
|
3299
|
+
* makes it the only file in this subsystem that grows without bound, on every
|
|
3300
|
+
* seat, forever — and `pruneReceipts` and `pruneObligations` both exist because
|
|
3301
|
+
* an untrimmed log is the next thing someone deletes wholesale. A log nobody
|
|
3302
|
+
* reads and nobody trims gets truncated by a stranger.
|
|
3303
|
+
*
|
|
3304
|
+
* Retention is the OBLIGATION window (`CLOSED_RETENTION_MS`), not the receipts'
|
|
3305
|
+
* seven days: a journal line is about a debt, and once the debt itself has left
|
|
3306
|
+
* the ledger the line has nothing to join to.
|
|
3307
|
+
*
|
|
3308
|
+
* Rewrites in place, atomically, and never throws. A journal that can fail the
|
|
3309
|
+
* sweep is worse than a journal that keeps a few stale lines.
|
|
3310
|
+
*
|
|
3311
|
+
* @param {object} [o] `{now}`
|
|
3312
|
+
* @returns {number} lines dropped
|
|
3313
|
+
*/
|
|
3314
|
+
export function pruneNoticeJournal(o = {}) {
|
|
3315
|
+
const now = Number.isFinite(o.now) ? o.now : Date.now();
|
|
3316
|
+
const p = join(obligationDir(), "notice-journal.jsonl");
|
|
3317
|
+
let raw;
|
|
3318
|
+
try { raw = readFileSync(p, "utf-8"); }
|
|
3319
|
+
catch { return 0; } // absent is the normal case on a seat that has had no failures
|
|
3320
|
+
const lines = raw.split("\n").filter((l) => l.trim());
|
|
3321
|
+
const keep = [];
|
|
3322
|
+
let dropped = 0;
|
|
3323
|
+
for (const line of lines) {
|
|
3324
|
+
let at = NaN;
|
|
3325
|
+
try { at = Date.parse(JSON.parse(line).at); } catch { at = NaN; }
|
|
3326
|
+
// A line whose stamp cannot be read is dropped, not kept forever: it is a
|
|
3327
|
+
// corrupt row in a file whose only purpose is chronology.
|
|
3328
|
+
if (!Number.isFinite(at)) { dropped++; continue; }
|
|
3329
|
+
if (now - at >= CLOSED_RETENTION_MS) { dropped++; continue; }
|
|
3330
|
+
keep.push(line);
|
|
3331
|
+
}
|
|
3332
|
+
if (!dropped) return 0;
|
|
3333
|
+
try {
|
|
3334
|
+
if (!keep.length) { unlinkSync(p); return dropped; }
|
|
3335
|
+
const tmp = `${p}.tmp`;
|
|
3336
|
+
writeFileSync(tmp, `${keep.join("\n")}\n`);
|
|
3337
|
+
renameSync(tmp, p);
|
|
3338
|
+
} catch (err) {
|
|
3339
|
+
console.error(`[assurance] could not prune the notice journal: ${err && err.message}`);
|
|
3340
|
+
return 0;
|
|
3341
|
+
}
|
|
3342
|
+
return dropped;
|
|
3343
|
+
}
|
|
3344
|
+
|
|
2977
3345
|
/** Delete discharged debts past retention. Open debts are NEVER pruned — an
|
|
2978
3346
|
* obligation may only leave the ledger by being discharged. */
|
|
2979
3347
|
export function pruneObligations(o = {}) {
|
|
@@ -2995,16 +3363,21 @@ export function pruneObligations(o = {}) {
|
|
|
2995
3363
|
return removed;
|
|
2996
3364
|
}
|
|
2997
3365
|
|
|
2998
|
-
/** Test seam: wipe the ledger — obligations, escalations
|
|
3366
|
+
/** Test seam: wipe the ledger — obligations, escalations, the room budget AND
|
|
3367
|
+
* the operator notice journal.
|
|
2999
3368
|
* The room budget lives in the same directory and is part of the same state:
|
|
3000
3369
|
* a reset that leaves it behind makes the next test's first interim depend on
|
|
3001
|
-
* which tests ran before it.
|
|
3370
|
+
* which tests ran before it. The notice journal is append-only and keyed by
|
|
3371
|
+
* obligation, and every test in a file typically settles the SAME item, so a
|
|
3372
|
+
* reset that leaves it behind makes "exactly one row" depend on which tests ran
|
|
3373
|
+
* first — the same hazard, in the file that replaced the message. */
|
|
3002
3374
|
export function _resetObligations() {
|
|
3003
3375
|
_sweepInFlight = false; // a test that threw mid-sweep must not disable the next one
|
|
3004
3376
|
for (const rec of listObligations()) {
|
|
3005
3377
|
try { unlinkSync(pathFor(rec.key)); } catch { /* */ }
|
|
3006
3378
|
}
|
|
3007
3379
|
try { unlinkSync(roomBudgetPath(AGENT_REPO_DIR)); } catch { /* absent is the normal case */ }
|
|
3380
|
+
try { unlinkSync(join(obligationDir(), "notice-journal.jsonl")); } catch { /* absent is the normal case */ }
|
|
3008
3381
|
try {
|
|
3009
3382
|
const dir = join(obligationDir(), "needs-attention");
|
|
3010
3383
|
for (const f of readdirSync(dir)) { try { unlinkSync(join(dir, f)); } catch { /* */ } }
|
|
@@ -3012,6 +3385,7 @@ export function _resetObligations() {
|
|
|
3012
3385
|
}
|
|
3013
3386
|
|
|
3014
3387
|
export default {
|
|
3388
|
+
pruneNoticeJournal,
|
|
3015
3389
|
shouldAcknowledge,
|
|
3016
3390
|
senderLooksLikeAgentSeat,
|
|
3017
3391
|
looksLikePeerAckShape,
|
|
@@ -3025,6 +3399,8 @@ export default {
|
|
|
3025
3399
|
_buildAckUserPromptForTest: buildAckUserPrompt,
|
|
3026
3400
|
composeSilentSuccess,
|
|
3027
3401
|
composeRefusedSend,
|
|
3402
|
+
SEND_BLOCK_PHRASES,
|
|
3403
|
+
humanSendBlockPhrase,
|
|
3028
3404
|
composeInterrupted,
|
|
3029
3405
|
looksLikePeerOutcomeNotice,
|
|
3030
3406
|
classifyFailure,
|