@tpsdev-ai/agent 0.8.0 → 0.9.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/bun.lock +27 -15
  2. package/dist/bin.js +4 -3
  3. package/dist/bin.js.map +1 -1
  4. package/dist/config.d.ts +8 -1
  5. package/dist/config.d.ts.map +1 -1
  6. package/dist/config.js +38 -3
  7. package/dist/config.js.map +1 -1
  8. package/dist/home.d.ts +3 -0
  9. package/dist/home.d.ts.map +1 -0
  10. package/dist/home.js +18 -0
  11. package/dist/home.js.map +1 -0
  12. package/dist/index.d.ts +16 -3
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +12 -1
  15. package/dist/index.js.map +1 -1
  16. package/dist/io/flair.d.ts +1 -10
  17. package/dist/io/flair.d.ts.map +1 -1
  18. package/dist/io/flair.js +29 -28
  19. package/dist/io/flair.js.map +1 -1
  20. package/dist/io/mail.d.ts +184 -30
  21. package/dist/io/mail.d.ts.map +1 -1
  22. package/dist/io/mail.js +944 -185
  23. package/dist/io/mail.js.map +1 -1
  24. package/dist/lib/agent-keys.d.ts +106 -0
  25. package/dist/lib/agent-keys.d.ts.map +1 -0
  26. package/dist/lib/agent-keys.js +298 -0
  27. package/dist/lib/agent-keys.js.map +1 -0
  28. package/dist/lib/bridge-identity.d.ts +10 -0
  29. package/dist/lib/bridge-identity.d.ts.map +1 -0
  30. package/dist/lib/bridge-identity.js +56 -0
  31. package/dist/lib/bridge-identity.js.map +1 -0
  32. package/dist/lib/mail-lock-namespace.d.ts +19 -0
  33. package/dist/lib/mail-lock-namespace.d.ts.map +1 -0
  34. package/dist/lib/mail-lock-namespace.js +58 -0
  35. package/dist/lib/mail-lock-namespace.js.map +1 -0
  36. package/dist/lib/mail-lock.d.ts +81 -0
  37. package/dist/lib/mail-lock.d.ts.map +1 -0
  38. package/dist/lib/mail-lock.js +319 -0
  39. package/dist/lib/mail-lock.js.map +1 -0
  40. package/dist/lib/mailbox-filename.d.ts +2 -0
  41. package/dist/lib/mailbox-filename.d.ts.map +1 -0
  42. package/dist/lib/mailbox-filename.js +4 -0
  43. package/dist/lib/mailbox-filename.js.map +1 -0
  44. package/dist/lib/mailbox-policy.d.ts +245 -0
  45. package/dist/lib/mailbox-policy.d.ts.map +1 -0
  46. package/dist/lib/mailbox-policy.js +949 -0
  47. package/dist/lib/mailbox-policy.js.map +1 -0
  48. package/dist/lib/public-key.d.ts +6 -0
  49. package/dist/lib/public-key.d.ts.map +1 -0
  50. package/dist/lib/public-key.js +45 -0
  51. package/dist/lib/public-key.js.map +1 -0
  52. package/dist/lib/registry-key.d.ts +2 -0
  53. package/dist/lib/registry-key.d.ts.map +1 -0
  54. package/dist/lib/registry-key.js +10 -0
  55. package/dist/lib/registry-key.js.map +1 -0
  56. package/dist/lib/relay-lock.d.ts +7 -0
  57. package/dist/lib/relay-lock.d.ts.map +1 -0
  58. package/dist/lib/relay-lock.js +19 -0
  59. package/dist/lib/relay-lock.js.map +1 -0
  60. package/dist/lib/signEnvelope.d.ts +2 -0
  61. package/dist/lib/signEnvelope.d.ts.map +1 -1
  62. package/dist/lib/signEnvelope.js.map +1 -1
  63. package/dist/lib/signing-key.d.ts +2 -0
  64. package/dist/lib/signing-key.d.ts.map +1 -0
  65. package/dist/lib/signing-key.js +9 -0
  66. package/dist/lib/signing-key.js.map +1 -0
  67. package/dist/lib/topic-recipient.d.ts +2 -0
  68. package/dist/lib/topic-recipient.d.ts.map +1 -0
  69. package/dist/lib/topic-recipient.js +2 -0
  70. package/dist/lib/topic-recipient.js.map +1 -0
  71. package/dist/llm/provider.d.ts.map +1 -1
  72. package/dist/llm/provider.js +9 -7
  73. package/dist/llm/provider.js.map +1 -1
  74. package/dist/runtime/agent.d.ts.map +1 -1
  75. package/dist/runtime/agent.js +32 -25
  76. package/dist/runtime/agent.js.map +1 -1
  77. package/dist/runtime/event-loop.d.ts +21 -2
  78. package/dist/runtime/event-loop.d.ts.map +1 -1
  79. package/dist/runtime/event-loop.js +199 -54
  80. package/dist/runtime/event-loop.js.map +1 -1
  81. package/dist/runtime/types.d.ts +11 -0
  82. package/dist/runtime/types.d.ts.map +1 -1
  83. package/dist/runtime/types.js +13 -1
  84. package/dist/runtime/types.js.map +1 -1
  85. package/package.json +2 -3
  86. package/src/bin.ts +4 -3
  87. package/src/config.ts +46 -3
  88. package/src/home.ts +18 -0
  89. package/src/index.ts +33 -2
  90. package/src/io/flair.ts +23 -28
  91. package/src/io/mail.ts +1007 -200
  92. package/src/lib/agent-keys.ts +308 -0
  93. package/src/lib/bridge-identity.ts +49 -0
  94. package/src/lib/mail-lock-namespace.ts +64 -0
  95. package/src/lib/mail-lock.ts +337 -0
  96. package/src/lib/mailbox-filename.ts +3 -0
  97. package/src/lib/mailbox-policy.ts +1085 -0
  98. package/src/lib/public-key.ts +49 -0
  99. package/src/lib/registry-key.ts +8 -0
  100. package/src/lib/relay-lock.ts +20 -0
  101. package/src/lib/signEnvelope.ts +2 -0
  102. package/src/lib/signing-key.ts +8 -0
  103. package/src/lib/topic-recipient.ts +1 -0
  104. package/src/llm/provider.ts +9 -7
  105. package/src/runtime/agent.ts +30 -27
  106. package/src/runtime/event-loop.ts +221 -68
  107. package/src/runtime/types.ts +14 -0
  108. package/test/config.test.ts +85 -2
  109. package/test/core-loop.test.ts +6 -4
  110. package/test/governance.test.ts +4 -1
  111. package/test/helpers/event-loop-child.mjs +50 -0
  112. package/test/helpers/mail-delivery-worker.mjs +16 -0
  113. package/test/helpers/mail-kill-child.mjs +104 -0
  114. package/test/helpers/signed-relay-record.ts +31 -0
  115. package/test/home-per-call.test.ts +72 -0
  116. package/test/io.test.ts +81 -14
  117. package/test/mail-client-lock-namespace.test.ts +155 -0
  118. package/test/mail-client-repoint-root.test.ts +368 -0
  119. package/test/mail-delivery-at-least-once.test.ts +1238 -0
  120. package/test/mail-event-loop-delivery.test.ts +769 -0
  121. package/test/mail-intent-phases.test.ts +304 -0
  122. package/test/mail-interrupted-recovery.test.ts +393 -0
  123. package/test/mail-lock-pid-state.test.ts +238 -0
  124. package/test/mail-lock.test.ts +96 -0
  125. package/test/mail-partial-flair.test.ts +102 -0
  126. package/test/mail-placement-replay.test.ts +116 -0
  127. package/test/mail-promote-guard.test.ts +305 -21
  128. package/test/mail-relay-reservation.test.ts +60 -0
  129. package/test/mailbox-filename.test.ts +16 -0
  130. package/test/public-key.test.ts +108 -0
  131. package/test/runtime-key-encoding.test.ts +105 -0
  132. package/test/runtime-pending-key.test.ts +117 -0
  133. package/test/security/mail-trust.test.ts +406 -109
package/dist/io/mail.js CHANGED
@@ -1,16 +1,69 @@
1
- import { existsSync, mkdirSync, readdirSync, renameSync, readFileSync, writeFileSync } from "node:fs";
1
+ import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, renameSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
2
+ import { isMailboxMessageFile } from "../lib/mailbox-filename.js";
2
3
  import { join } from "node:path";
4
+ import { randomUUID } from "node:crypto";
3
5
  import { sanitizeError } from "../telemetry/events.js";
4
- import { verifyEnvelope } from "../lib/signEnvelope.js";
6
+ import { signEnvelope } from "../lib/signEnvelope.js";
7
+ import { PublicKeyFormatError } from "../lib/public-key.js";
8
+ import { agentKeyCandidates, readAgentPrivateKey } from "../lib/agent-keys.js";
9
+ import { tryAcquireRelayMoveLock } from "../lib/relay-lock.js";
10
+ import { canonicalMailboxRoot, canonicalMailRoot } from "../lib/mail-lock-namespace.js";
11
+ import { acquireMailLock, acquireMailLockSync, processIsGone, processStartToken } from "../lib/mail-lock.js";
12
+ import { DELIVERY_PRESENTATION_TTL_MS, PlacementDurabilityError, decideEnvelopeForMailbox, mailboxReplayStore, parseSignedEnvelope, pendingPlacementEntries, placeCurRecord, fileIdentity, matchesFileIdentity, } from "../lib/mailbox-policy.js";
13
+ import { verifiedMailTier } from "../lib/bridge-identity.js";
14
+ const RESOLVED = { status: "resolved" };
15
+ function report(fn) {
16
+ try {
17
+ fn();
18
+ }
19
+ catch { }
20
+ }
21
+ function deferred(reason, detail, file) {
22
+ return { status: "deferred", reason, detail, ...(file === undefined ? {} : { file }) };
23
+ }
5
24
  /**
6
- * The stable reason string `verifyEnvelope` returns when an agent-kind chain
7
- * entry or `envelope.from` cannot be resolved from the LOCAL Flair. An ABSENT
8
- * principal is a topology condition, not a forgery verdict, so it is labelled
9
- * `unresolvable-principal` rather than `invalid`. Duplicated from the shared
10
- * promotion boundary because `@tpsdev-ai/agent` cannot import `packages/cli`
11
- * (the dependency runs the other way: cli → agent).
25
+ * Tokens held by the MailClients of this module copy. Other copies in the same
26
+ * process are treated as live until process exit or lease expiry.
12
27
  */
13
- const UNRESOLVABLE_PRINCIPAL_REASON_RE = /^agent (.+) not found in Flair$/;
28
+ const activePresentations = new Set();
29
+ const moduleNonce = randomUUID();
30
+ let ownStartToken;
31
+ function ownClaim(token) {
32
+ if (ownStartToken === undefined)
33
+ ownStartToken = processStartToken(process.pid);
34
+ return { token, pid: process.pid, start: ownStartToken, moduleNonce };
35
+ }
36
+ function claimIsLive(claim, firstPresentedAt) {
37
+ if (!claim)
38
+ return false;
39
+ const own = ownClaim(claim.token);
40
+ if (claim.pid === own.pid && claim.start === own.start) {
41
+ if (claim.moduleNonce === moduleNonce)
42
+ return activePresentations.has(claim.token);
43
+ return firstPresentedAt === undefined || Date.now() - Date.parse(firstPresentedAt) <= DELIVERY_PRESENTATION_TTL_MS;
44
+ }
45
+ if (firstPresentedAt !== undefined && Date.now() - Date.parse(firstPresentedAt) > DELIVERY_PRESENTATION_TTL_MS)
46
+ return false;
47
+ return !processIsGone(claim.pid, claim.start);
48
+ }
49
+ function isCliPromotedRecord(record) {
50
+ if (record === null || typeof record !== "object" || Array.isArray(record))
51
+ return false;
52
+ const r = record;
53
+ return typeof r.id === "string" && r.id.length > 0 &&
54
+ typeof r.from === "string" && typeof r.to === "string" && typeof r.body === "string" &&
55
+ typeof r.timestamp === "string" && typeof r.read === "boolean" &&
56
+ typeof r.envelopeId === "string" && r.envelopeId.length > 0 &&
57
+ r.envelope !== null && typeof r.envelope === "object" && !Array.isArray(r.envelope) &&
58
+ parseSignedEnvelope(JSON.stringify(r.envelope)).ok &&
59
+ (r.trustTier === undefined || r.trustTier === "user" || r.trustTier === "internal" || r.trustTier === "external") &&
60
+ typeof r.checkedOutAt === "string" && typeof r.checkedOutBy === "string" &&
61
+ Number.isInteger(r.deliveryAttempts) && r.deliveryAttempts >= 1 &&
62
+ (r.replyToId === undefined || typeof r.replyToId === "string");
63
+ }
64
+ function isMissing(err) {
65
+ return err?.code === "ENOENT";
66
+ }
14
67
  /**
15
68
  * Write the dlq sidecar for a TERMINAL rejection.
16
69
  *
@@ -26,6 +79,38 @@ const UNRESOLVABLE_PRINCIPAL_REASON_RE = /^agent (.+) not found in Flair$/;
26
79
  function writeRejectSidecar(dlqDir, filename, cls, reason) {
27
80
  writeFileSync(join(dlqDir, `${filename}.reason`), `class: ${cls}\nPromote rejected at ${new Date().toISOString()}\nReason: ${reason}\n`, "utf-8");
28
81
  }
82
+ function sameFileIdentity(a, b) {
83
+ const sa = lstatOrAbsent(a);
84
+ const sb = lstatOrAbsent(b);
85
+ return sa !== null && sb !== null && sa.isFile() && sb.isFile()
86
+ && matchesFileIdentity(sa, fileIdentity(sb, readFileSync(b)), readFileSync(a));
87
+ }
88
+ /**
89
+ * cli#617 slice (a): recovery resumes only an intent whose phase resolves to
90
+ * `placing` (phaseOf). One that resolves to any other phase (`in_progress`, or
91
+ * `unknown`: an unsupported value in a recognized field) is never presented or
92
+ * finished. A phase seen in the listing skips the record before its payload
93
+ * is read, and the under-lock recheck catches a phase that changed after the
94
+ * payload was read and verified.
95
+ *
96
+ * This is the BATCH reader (`checkNewMail`), which stays at-most-once until
97
+ * slice (c) wires the per-message delivery API. Slice (b)'s `deliverNext`
98
+ * presents an `in_progress` intent again through its own completion-gated path
99
+ * (`presentPending`), not this one.
100
+ */
101
+ function resumableOnRecovery(phase) {
102
+ return phase === "placing";
103
+ }
104
+ function lstatOrAbsent(path) {
105
+ try {
106
+ return lstatSync(path, { bigint: true });
107
+ }
108
+ catch (err) {
109
+ if (err.code === "ENOENT")
110
+ return null;
111
+ throw err;
112
+ }
113
+ }
29
114
  /**
30
115
  * Maildir-compatible mail client.
31
116
  * Reads from mailDir/inbox/new and moves processed messages to mailDir/inbox/cur.
@@ -35,81 +120,64 @@ export class MailClient {
35
120
  mailDir;
36
121
  events;
37
122
  agentId;
123
+ signingKeyPath;
38
124
  flairClient;
39
- inboxNew;
40
- inboxCur;
41
- inboxDlq;
42
- outboxNew;
43
- /** One-shot guard so a misconfigured (verifier-less) mailbox warns once, not per poll. */
44
- warnedNoVerifier = false;
45
- constructor(mailDir, events, agentId = "unknown", flairClient) {
125
+ /** cli#617 slice (b): the deliveries this client issued, keyed by the delivery object itself. */
126
+ issued = new WeakMap();
127
+ constructor(mailDir, events, agentId = "unknown", flairClient,
128
+ /** Configured Flair signing key, checked against both standard locations. */
129
+ signingKeyPath) {
46
130
  this.mailDir = mailDir;
47
131
  this.events = events;
48
132
  this.agentId = agentId;
49
- this.flairClient = flairClient;
50
- this.inboxNew = join(mailDir, agentId, "new");
51
- this.inboxCur = join(mailDir, agentId, "cur");
52
- this.inboxDlq = join(mailDir, agentId, "dlq");
53
- this.outboxNew = join(mailDir, agentId, "outbox");
54
- for (const dir of [this.inboxNew, this.inboxCur, this.inboxDlq, this.outboxNew]) {
55
- mkdirSync(dir, { recursive: true });
133
+ this.signingKeyPath = signingKeyPath;
134
+ // cli#380: construction without a verifier throws.
135
+ if (!flairClient) {
136
+ throw new Error(`MailClient requires a Flair verifier for "${agentId}": refusing to construct a mailbox that ` +
137
+ `could promote unverified mail (cli#380).`);
56
138
  }
139
+ this.flairClient = flairClient;
140
+ // cli#636: no resolved canonical root is cached at construction.
141
+ this.operationRoots();
57
142
  }
58
143
  /**
59
- * Return all messages in inbox/new and move them to inbox/cur/.
60
- *
61
- * Verification is MANDATORY — a record is promoted ONLY after its signed
62
- * envelope verifies against the local Flair. There is no unverified path:
63
- * - NO verifier configured → refuse; the record stays in new/ (an absent
64
- * client must never mean "promote without verifying");
65
- * - the verifier THROWS (Flair unreachable) → refuse; the record stays in
66
- * new/ for a later check (a throw must never mean "pass");
67
- * - the verifier REJECTS → dead-letter to dlq/ with a `.reason` sidecar.
68
- * Unverified input must never reach the tool-holding model.
144
+ * Resolve `mailDir` and `<mail root>/<agentId>` to canonical path strings;
145
+ * create maildir subdirectories beneath the mailbox string.
69
146
  */
147
+ operationRoots() {
148
+ const mailRoot = canonicalMailRoot(this.mailDir);
149
+ // Create the mailbox with the default mode first (canonicalMailboxRoot
150
+ // would create it 0700); resolving it then creates nothing.
151
+ mkdirSync(join(mailRoot, this.agentId), { recursive: true });
152
+ const mailbox = canonicalMailboxRoot(join(mailRoot, this.agentId));
153
+ for (const dir of ["new", "cur", "dlq", "outbox"])
154
+ mkdirSync(join(mailbox, dir), { recursive: true });
155
+ return { mailRoot, mailbox };
156
+ }
70
157
  async checkNewMail() {
71
- if (!existsSync(this.inboxNew))
72
- return [];
73
- const files = readdirSync(this.inboxNew).filter((f) => !f.startsWith(".") && !f.includes("/") && !f.includes("\\"));
74
158
  const messages = [];
75
- // No verifier → NOTHING is promotable. Refuse (never rename into cur/) and
76
- // leave the records in new/ so a later check with a verifier — or the
77
- // shared promote() path — can process them.
78
- if (!this.flairClient) {
79
- if (files.length === 0)
80
- return [];
81
- this.events?.emit({
82
- type: "mail.receive",
83
- agent: this.agentId,
84
- status: "rejected",
85
- from: "unknown",
86
- durationMs: 0,
87
- error: "no verifier configured — refusing to promote unverified mail",
88
- });
89
- if (!this.warnedNoVerifier) {
90
- this.warnedNoVerifier = true;
91
- console.error(`[MailClient] no Flair verifier configured for "${this.agentId}": refusing to promote ` +
92
- `${files.length} unverified message(s) from new/. Unverified input must never reach the ` +
93
- `model — configure flair (url + key) or promote through the shared promote() lifecycle.`);
94
- }
95
- return [];
96
- }
159
+ const roots = this.operationRoots();
160
+ await this.recoverInterruptedPlacements(messages, roots);
161
+ const inboxNew = join(roots.mailbox, "new");
162
+ if (!existsSync(inboxNew))
163
+ return messages;
164
+ const files = readdirSync(inboxNew).filter(isMailboxMessageFile);
97
165
  for (const file of files) {
98
166
  const started = Date.now();
99
- const srcPath = join(this.inboxNew, file);
167
+ const srcPath = join(inboxNew, file);
100
168
  let body;
101
169
  try {
102
170
  body = readFileSync(srcPath, "utf-8");
103
171
  }
104
172
  catch (err) {
105
- this.events?.emit({
173
+ report(() => this.events?.emit({
106
174
  type: "mail.receive",
107
175
  agent: this.agentId,
108
176
  status: "error",
109
177
  from: "unknown",
110
178
  durationMs: Date.now() - started,
111
179
  error: sanitizeError(err),
112
- });
180
+ }));
113
181
  continue; // leave in new/ — a later check retries
114
182
  }
115
183
  // Verify. A THROW is a refusal, not a pass: leave the record in new/ for a
@@ -120,112 +188,866 @@ export class MailClient {
120
188
  }
121
189
  catch (err) {
122
190
  const detail = sanitizeError(err);
123
- this.events?.emit({
191
+ report(() => this.events?.emit({
124
192
  type: "mail.receive",
125
193
  agent: this.agentId,
126
194
  status: "error",
127
195
  from: "unknown",
128
196
  durationMs: Date.now() - started,
129
197
  error: detail,
130
- });
131
- console.error(`[MailClient] verification could not run for ${file} — NOT promoting: ${detail}`);
198
+ }));
199
+ report(() => console.error(`[MailClient] verification could not run for ${file} — NOT promoting: ${detail}`));
132
200
  continue; // leave in new/
133
201
  }
134
202
  if (!verifyResult.pass) {
135
- const dlqPath = join(this.inboxDlq, file);
136
- try {
137
- if (srcPath !== dlqPath)
138
- renameSync(srcPath, dlqPath);
139
- writeRejectSidecar(this.inboxDlq, file, verifyResult.class, verifyResult.reason);
140
- }
141
- catch (err) {
142
- console.error(`[MailClient] failed to dead-letter ${file}: ${sanitizeError(err)}`);
143
- }
144
- this.events?.emit({
203
+ this.deadLetter(file, srcPath, verifyResult, started, roots);
204
+ continue;
205
+ }
206
+ let trustTier;
207
+ try {
208
+ trustTier = verifiedMailTier(verifyResult.envelope, roots.mailRoot);
209
+ }
210
+ catch (err) {
211
+ const detail = sanitizeError(err);
212
+ report(() => this.events?.emit({
145
213
  type: "mail.receive",
146
214
  agent: this.agentId,
147
- status: "rejected",
148
- from: verifyResult.from ?? "unknown",
215
+ status: "error",
216
+ from: verifyResult.envelope.from,
149
217
  durationMs: Date.now() - started,
150
- error: verifyResult.reason,
151
- });
152
- continue;
218
+ error: detail,
219
+ }));
220
+ report(() => console.error(`[MailClient] trust tier could not be resolved for ${file} — NOT promoting: ${detail}`));
221
+ continue; // leave in new/
153
222
  }
154
- // Promote to cur/ — verified, and addressed to this mailbox.
155
223
  try {
156
- const dstPath = join(this.inboxCur, file);
157
- renameSync(srcPath, dstPath);
158
- let headers = {};
159
- let from = "unknown";
160
- try {
161
- const parsed = JSON.parse(body);
162
- headers = parsed.headers ?? {};
163
- from = parsed.from ?? "unknown";
224
+ const committed = await this.commitToCur(roots, file, srcPath, body, verifyResult.envelope);
225
+ // "live-placement" is returned only to the delivery API (a claim was passed).
226
+ if (committed === "already-delivered" || committed === "live-placement")
227
+ continue;
228
+ if (committed) {
229
+ this.deadLetter(file, srcPath, { ...committed, from: verifyResult.envelope.from }, started, roots);
230
+ continue;
164
231
  }
165
- catch { }
166
- messages.push({ filename: file, body, receivedAt: new Date(), headers, from });
167
- this.events?.emit({
232
+ const from = verifyResult.envelope.from;
233
+ messages.push({
234
+ filename: file, body, receivedAt: new Date(), headers: {}, from,
235
+ verifiedEnvelope: verifyResult.envelope,
236
+ trustTier,
237
+ });
238
+ report(() => this.events?.emit({
168
239
  type: "mail.receive",
169
240
  agent: this.agentId,
170
241
  status: "ok",
171
242
  from,
172
243
  durationMs: Date.now() - started,
173
- });
244
+ }));
174
245
  }
175
246
  catch (err) {
176
- this.events?.emit({
247
+ report(() => this.events?.emit({
177
248
  type: "mail.receive",
178
249
  agent: this.agentId,
179
250
  status: "error",
180
251
  from: "unknown",
181
252
  durationMs: Date.now() - started,
182
253
  error: sanitizeError(err),
183
- });
254
+ }));
184
255
  }
185
256
  }
186
257
  return messages;
187
258
  }
259
+ /**
260
+ * Present verified, unclaimed pending work before committing new mail.
261
+ * Unresolved placing/in_progress work defers deliverNext() commits. The token
262
+ * set covers MailClients of this module copy; claims from other copies in the
263
+ * same process are treated as live until process exit or lease expiry.
264
+ * Retry deferred completion or release on the same hand-over.
265
+ */
266
+ async deliverNext() {
267
+ let roots;
268
+ try {
269
+ roots = this.operationRoots();
270
+ }
271
+ catch (err) {
272
+ this.emitRecoveryError(err);
273
+ return deferred("storage-error", `mailbox roots unavailable: ${sanitizeError(err)}`);
274
+ }
275
+ let pending;
276
+ const listing = await this.lockOrDefer(roots, "pending placements not listed");
277
+ if ("status" in listing)
278
+ return listing;
279
+ try {
280
+ pending = pendingPlacementEntries(roots.mailbox);
281
+ }
282
+ catch (err) {
283
+ this.emitRecoveryError(err);
284
+ return deferred("storage-error", `pending placements unavailable: ${sanitizeError(err)}`);
285
+ }
286
+ finally {
287
+ listing.release();
288
+ }
289
+ pending.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
290
+ let firstDeferral = null;
291
+ for (const { messageId, file, phase } of pending) {
292
+ if (phase === "unknown")
293
+ continue; // another writer's phase: preserved, never presented (slice a)
294
+ let outcome;
295
+ try {
296
+ outcome = await this.presentPending(roots, messageId, file);
297
+ }
298
+ catch (err) {
299
+ this.emitRecoveryError(err);
300
+ outcome = deferred("storage-error", sanitizeError(err), file);
301
+ }
302
+ if (outcome.status === "delivered")
303
+ return outcome;
304
+ if (outcome.status === "deferred")
305
+ firstDeferral ??= outcome;
306
+ }
307
+ if (firstDeferral)
308
+ return firstDeferral;
309
+ return this.commitNextForDelivery(roots);
310
+ }
311
+ /** Finalize only this client's issued claim, with its recorded cur/ file identity, under the mailbox lock. */
312
+ async completeDelivery(delivery) {
313
+ const issued = this.issued.get(delivery);
314
+ if (!issued)
315
+ return { status: "refused", reason: "foreign", detail: "not a delivery this MailClient handed over" };
316
+ if (issued.state === "completed")
317
+ return { status: "already-completed" };
318
+ let roots;
319
+ try {
320
+ roots = this.operationRoots();
321
+ }
322
+ catch (err) {
323
+ this.emitRecoveryError(err);
324
+ return { status: "deferred", reason: "storage-error", detail: `mailbox roots unavailable (${sanitizeError(err)}); delivery not finalized` };
325
+ }
326
+ const lock = await this.lockOrDefer(roots, "delivery not finalized; intent state unknown, retry");
327
+ if ("status" in lock)
328
+ return { status: "deferred", reason: "lock-busy", detail: lock.detail };
329
+ let result;
330
+ try {
331
+ if (this.expireIssuedDelivery(roots.mailbox, issued))
332
+ return { status: "quarantined" };
333
+ result = mailboxReplayStore(roots.mailbox).completePlacement(issued.messageId, issued.file, issued.token);
334
+ }
335
+ catch (err) {
336
+ this.emitRecoveryError(err);
337
+ const detail = err instanceof PlacementDurabilityError
338
+ ? err.message
339
+ : err instanceof Error && err.name === "MalformedPlacementIntentError"
340
+ ? "quarantined placement intent needs repair before a retry can complete"
341
+ : `placement state unavailable (${sanitizeError(err)}); completion state unknown`;
342
+ return { status: "deferred", reason: "storage-error", detail };
343
+ }
344
+ finally {
345
+ lock.release();
346
+ }
347
+ activePresentations.delete(issued.token);
348
+ if (result === "completed") {
349
+ issued.state = "completed";
350
+ return { status: "completed" };
351
+ }
352
+ issued.state = "released";
353
+ if (result === "identity") {
354
+ return { status: "refused", reason: "identity", detail: `cur/${issued.file} recorded identity is absent or mismatched; not finalized` };
355
+ }
356
+ return {
357
+ status: "refused",
358
+ reason: "stale",
359
+ detail: `message ${issued.messageId}: no matching live intent and claim in the currently resolved mailbox`,
360
+ };
361
+ }
362
+ /** Persist matching claim release under the issued mailbox's lock; contention and storage errors defer. */
363
+ releaseDelivery(delivery) {
364
+ const issued = this.issued.get(delivery);
365
+ if (!issued)
366
+ return { status: "refused", reason: "foreign" };
367
+ if (issued.state !== "active")
368
+ return { status: "refused", reason: "stale" };
369
+ try {
370
+ const lock = acquireMailLockSync(issued.mailbox, { timeoutMs: 0 });
371
+ if (!lock)
372
+ return { status: "deferred", reason: "lock-busy", detail: "delivery not released; retry" };
373
+ let released;
374
+ try {
375
+ if (this.expireIssuedDelivery(issued.mailbox, issued))
376
+ return { status: "quarantined" };
377
+ released = mailboxReplayStore(issued.mailbox).releasePlacement(issued.messageId, issued.file, issued.token);
378
+ }
379
+ finally {
380
+ lock.release();
381
+ }
382
+ if (!released)
383
+ return { status: "refused", reason: "stale" };
384
+ issued.state = "released";
385
+ activePresentations.delete(issued.token);
386
+ return { status: "released" };
387
+ }
388
+ catch (err) {
389
+ this.emitRecoveryError(err);
390
+ return { status: "deferred", reason: "storage-error", detail: `release persistence failed (${sanitizeError(err)}); retry` };
391
+ }
392
+ }
393
+ /** Called under the mailbox lock; only this issued claim may hit the deadline. */
394
+ expireIssuedDelivery(mailbox, issued) {
395
+ const replay = mailboxReplayStore(mailbox);
396
+ const state = replay.placementState(issued.file);
397
+ if (state?.claim?.token !== issued.token)
398
+ return false;
399
+ const expiry = replay.expireOverdue(issued.messageId, issued.file, new Date().toISOString());
400
+ if (expiry.status !== "failed")
401
+ return false;
402
+ issued.state = "released";
403
+ activePresentations.delete(issued.token);
404
+ this.logQuarantine(issued.messageId, expiry.presentations, "deadline");
405
+ return true;
406
+ }
407
+ /** Record a hand-over: the token is already held in this module copy; bind it to the delivery object. */
408
+ issue(roots, token, messageId, file, presentation, message) {
409
+ const delivery = Object.freeze({ message, deliveryKey: JSON.stringify([roots.mailbox, messageId]), presentation });
410
+ this.issued.set(delivery, { token, messageId, file, mailbox: roots.mailbox, state: "active" });
411
+ return delivery;
412
+ }
413
+ /**
414
+ * Present one pending placement: inspect it under the lock, re-verify its
415
+ * cur/ copy outside the lock, then re-check and advance under the lock.
416
+ */
417
+ async presentPending(roots, messageId, file) {
418
+ const inspected = await this.inspectPending(roots, messageId, file);
419
+ if (inspected.status !== "read")
420
+ return inspected;
421
+ let outcome;
422
+ try {
423
+ if (inspected.phase === "placing") {
424
+ const classified = await this.classifyPending(inspected.bytes);
425
+ if (classified.kind === "cli")
426
+ return deferred("cli-record", `cur/${file} verifies only as CLI-promoted; awaiting CLI recovery`, file);
427
+ if (classified.kind === "pending-record-invalid" || classified.kind === "pending-record-ambiguous") {
428
+ return this.quarantinePending(roots, messageId, file, inspected.bytes, classified.kind);
429
+ }
430
+ outcome = classified.outcome;
431
+ }
432
+ else {
433
+ outcome = await this.verifyMailBody(inspected.bytes.toString("utf8"));
434
+ }
435
+ }
436
+ catch (err) {
437
+ return deferred("verification-unavailable", `re-verification could not run: ${sanitizeError(err)}`, file);
438
+ }
439
+ if (!outcome.pass)
440
+ return deferred("verification-failed", `the cur/ copy did not re-verify (${outcome.class}): ${outcome.reason}`, file);
441
+ if (outcome.envelope.messageId !== messageId) {
442
+ return deferred("verification-failed", "the cur/ copy's envelope names another message than the intent", file);
443
+ }
444
+ let trustTier;
445
+ try {
446
+ trustTier = verifiedMailTier(outcome.envelope, roots.mailRoot);
447
+ }
448
+ catch (err) {
449
+ return deferred("verification-unavailable", `trust tier unavailable: ${sanitizeError(err)}`, file);
450
+ }
451
+ return this.presentUnderLock(roots, messageId, file, inspected.bytes, outcome.envelope, trustTier);
452
+ }
453
+ async classifyPending(bytes) {
454
+ const body = bytes.toString("utf8");
455
+ const raw = await this.verifyMailBody(body);
456
+ let record;
457
+ try {
458
+ record = JSON.parse(body);
459
+ }
460
+ catch {
461
+ record = null;
462
+ }
463
+ let cli;
464
+ if (isCliPromotedRecord(record)) {
465
+ const env = record.envelope;
466
+ if (record.from === env.from && record.to === env.to && record.body === env.body &&
467
+ record.timestamp === env.timestamp && record.envelopeId === env.messageId && record.replyToId === env.replyToId) {
468
+ cli = await this.verifyMailBody(JSON.stringify({ from: record.from, body: JSON.stringify(env) }));
469
+ }
470
+ }
471
+ if (raw.pass && cli?.pass)
472
+ return { kind: "pending-record-ambiguous" };
473
+ if (raw.pass)
474
+ return { kind: "raw", outcome: raw };
475
+ if (cli?.pass)
476
+ return { kind: "cli" };
477
+ return { kind: "pending-record-invalid" };
478
+ }
479
+ async quarantinePending(roots, messageId, file, bytes, reason) {
480
+ const lock = await this.lockOrDefer(roots, "pending record not quarantined", file);
481
+ if ("status" in lock)
482
+ return lock;
483
+ try {
484
+ const replay = mailboxReplayStore(roots.mailbox);
485
+ const state = replay.placementState(file);
486
+ if (!state || state.messageId !== messageId || state.phase !== "placing")
487
+ return RESOLVED;
488
+ if (!replay.ownsPendingPlacement(messageId, file) || !readFileSync(join(roots.mailbox, "cur", file)).equals(bytes)) {
489
+ return deferred("record-changed", `cur/${file} identity absent or mismatched, or bytes changed; not quarantined`, file);
490
+ }
491
+ mkdirSync(join(roots.mailbox, "dlq"), { recursive: true });
492
+ writeRejectSidecar(join(roots.mailbox, "dlq"), file, "invalid", reason);
493
+ renameSync(join(roots.mailbox, "cur", file), join(roots.mailbox, "dlq", file));
494
+ replay.finishPlacement(messageId, file);
495
+ return deferred(reason, `cur/${file} quarantined: ${reason}; intent cleared`, file);
496
+ }
497
+ finally {
498
+ lock.release();
499
+ }
500
+ }
501
+ async inspectPending(roots, messageId, file) {
502
+ const lock = await this.lockOrDefer(roots, "pending placement not inspected", file);
503
+ if ("status" in lock)
504
+ return lock;
505
+ try {
506
+ const replay = mailboxReplayStore(roots.mailbox);
507
+ const state = replay.placementState(file);
508
+ if (!state || state.messageId !== messageId || state.phase === "failed" || state.phase === "unknown")
509
+ return RESOLVED;
510
+ if (state.phase === "in_progress") {
511
+ if (claimIsLive(state.claim, state.firstPresentedAt)) {
512
+ return deferred("active", `message ${messageId} has an active claim (this module copy holds the token, or another copy/process has an unexpired claim)`, file);
513
+ }
514
+ const expiry = replay.expireOverdue(messageId, file, new Date().toISOString());
515
+ if (expiry.status === "absent")
516
+ return RESOLVED;
517
+ if (expiry.status === "failed") {
518
+ this.logQuarantine(messageId, expiry.presentations, "deadline");
519
+ return RESOLVED;
520
+ }
521
+ }
522
+ const curPath = join(roots.mailbox, "cur", file);
523
+ let bytes;
524
+ try {
525
+ bytes = readFileSync(curPath);
526
+ }
527
+ catch (err) {
528
+ if (!isMissing(err))
529
+ throw err;
530
+ if (state.phase === "placing" && lstatOrAbsent(curPath) === null) {
531
+ replay.finishPlacement(messageId, file);
532
+ return RESOLVED;
533
+ }
534
+ return deferred("record-changed", `cur/${file} is missing for a ${state.phase} intent`, file);
535
+ }
536
+ return { status: "read", bytes, phase: state.phase };
537
+ }
538
+ finally {
539
+ lock.release();
540
+ }
541
+ }
542
+ /**
543
+ * Re-read the intent, its claim, the recorded identity and the raw bytes
544
+ * under the lock (all may have changed during re-verification), then advance
545
+ * the presentation with a new claim and hand the message over. A bound hit
546
+ * writes the terminal `failed` phase and presents nothing.
547
+ */
548
+ async presentUnderLock(roots, messageId, file, bytes, envelope, trustTier) {
549
+ const lock = await this.lockOrDefer(roots, "pending placement not presented", file);
550
+ if ("status" in lock)
551
+ return lock;
552
+ try {
553
+ const replay = mailboxReplayStore(roots.mailbox);
554
+ const state = replay.placementState(file);
555
+ if (!state || state.messageId !== messageId || state.phase === "failed" || state.phase === "unknown")
556
+ return RESOLVED;
557
+ if (state.phase === "in_progress" && claimIsLive(state.claim, state.firstPresentedAt)) {
558
+ return deferred("active", `message ${messageId} has an active claim (this module copy holds the token, or another copy/process has an unexpired claim)`, file);
559
+ }
560
+ if (!replay.ownsPendingPlacement(messageId, file)) {
561
+ return deferred("record-changed", `cur/${file} recorded identity is absent or mismatched`, file);
562
+ }
563
+ let current;
564
+ try {
565
+ current = readFileSync(join(roots.mailbox, "cur", file));
566
+ }
567
+ catch (err) {
568
+ if (isMissing(err))
569
+ return deferred("record-changed", `cur/${file} disappeared during re-verification`, file);
570
+ throw err;
571
+ }
572
+ if (!current.equals(bytes))
573
+ return deferred("record-changed", `cur/${file} changed during re-verification`, file);
574
+ if (!replay.isConsumed(messageId, file))
575
+ replay.recordConsumed(messageId);
576
+ const token = randomUUID();
577
+ const advance = replay.advancePresentation(messageId, file, new Date().toISOString(), ownClaim(token));
578
+ if (advance.status === "absent")
579
+ return RESOLVED;
580
+ if (advance.status === "failed") {
581
+ this.logQuarantine(messageId, advance.presentations, "count");
582
+ return RESOLVED;
583
+ }
584
+ // Hold the token before releasing the lock so another local call defers.
585
+ activePresentations.add(token);
586
+ const message = {
587
+ filename: file,
588
+ body: bytes.toString("utf8"),
589
+ receivedAt: new Date(),
590
+ headers: {},
591
+ from: envelope.from,
592
+ verifiedEnvelope: envelope,
593
+ trustTier,
594
+ };
595
+ return { status: "delivered", delivery: this.issue(roots, token, messageId, file, advance.presentations, message) };
596
+ }
597
+ finally {
598
+ lock.release();
599
+ }
600
+ }
601
+ /**
602
+ * The bound's log line. It is written after the durable `failed` write, so a
603
+ * kill between the two leaves the `failed` intent (the durable record) and
604
+ * no line.
605
+ */
606
+ logQuarantine(messageId, presentations, cause) {
607
+ const why = cause === "deadline"
608
+ ? `the deadline (${DELIVERY_PRESENTATION_TTL_MS / 3_600_000} h after the first presentation) passed`
609
+ : "the presentation bound was reached";
610
+ report(() => console.warn(`[MailClient] placement quarantined for mailbox ${this.agentId}: message ${messageId} not completed ` +
611
+ `after ${presentations} presentation(s); ${why}; failure transition does not delete an existing payload`));
612
+ }
613
+ /**
614
+ * Commit the next verifiable new/ message to cur/ with a live `in_progress`
615
+ * intent. Under the commit lock it re-checks that no `placing` or
616
+ * `in_progress` placement is pending, so a concurrent call cannot add a
617
+ * second message in flight.
618
+ */
619
+ async commitNextForDelivery(roots) {
620
+ let files;
621
+ try {
622
+ files = existsSync(join(roots.mailbox, "new"))
623
+ ? readdirSync(join(roots.mailbox, "new")).filter(isMailboxMessageFile).sort()
624
+ : [];
625
+ }
626
+ catch (err) {
627
+ this.emitRecoveryError(err);
628
+ return deferred("storage-error", `new/ unavailable: ${sanitizeError(err)}`);
629
+ }
630
+ let skipped = null;
631
+ for (const file of files) {
632
+ const started = Date.now();
633
+ const srcPath = join(roots.mailbox, "new", file);
634
+ let body;
635
+ try {
636
+ body = readFileSync(srcPath, "utf-8");
637
+ }
638
+ catch (err) {
639
+ if (!isMissing(err)) {
640
+ this.emitRecoveryError(err);
641
+ skipped ??= { file, detail: `unreadable: ${sanitizeError(err)}` };
642
+ }
643
+ continue;
644
+ }
645
+ let verifyResult;
646
+ try {
647
+ verifyResult = await this.verifyMailBody(body);
648
+ }
649
+ catch (err) {
650
+ this.emitRecoveryError(err); // left in new/ for a later call
651
+ skipped ??= { file, detail: `verification could not run: ${sanitizeError(err)}` };
652
+ continue;
653
+ }
654
+ if (!verifyResult.pass) {
655
+ this.deadLetter(file, srcPath, verifyResult, started, roots);
656
+ continue;
657
+ }
658
+ let trustTier;
659
+ try {
660
+ trustTier = verifiedMailTier(verifyResult.envelope, roots.mailRoot);
661
+ }
662
+ catch (err) {
663
+ this.emitRecoveryError(err);
664
+ skipped ??= { file, detail: `trust tier unavailable: ${sanitizeError(err)}` };
665
+ continue;
666
+ }
667
+ const token = randomUUID();
668
+ // Live before the commit writes the claim (see presentUnderLock).
669
+ activePresentations.add(token);
670
+ let delivered = false;
671
+ try {
672
+ const committed = await this.commitToCur(roots, file, srcPath, body, verifyResult.envelope, ownClaim(token));
673
+ if (committed === "already-delivered")
674
+ continue;
675
+ if (committed === "live-placement") {
676
+ return deferred("new-mail-deferred", "a placement became pending before the commit; nothing committed", file);
677
+ }
678
+ if (committed) {
679
+ this.deadLetter(file, srcPath, { ...committed, from: verifyResult.envelope.from }, started, roots);
680
+ continue;
681
+ }
682
+ const from = verifyResult.envelope.from;
683
+ report(() => this.events?.emit({
684
+ type: "mail.receive", agent: this.agentId, status: "ok", from, durationMs: Date.now() - started,
685
+ }));
686
+ delivered = true;
687
+ const message = {
688
+ filename: file, body, receivedAt: new Date(), headers: {}, from,
689
+ verifiedEnvelope: verifyResult.envelope, trustTier,
690
+ };
691
+ return { status: "delivered", delivery: this.issue(roots, token, verifyResult.envelope.messageId, file, 1, message) };
692
+ }
693
+ catch (err) {
694
+ this.emitRecoveryError(err);
695
+ skipped ??= { file, detail: `delivery attempt failed: ${sanitizeError(err)}` };
696
+ }
697
+ finally {
698
+ if (!delivered)
699
+ activePresentations.delete(token);
700
+ }
701
+ }
702
+ return skipped ? deferred("new-mail-deferred", `new/${skipped.file} ${skipped.detail}`, skipped.file) : { status: "idle" };
703
+ }
704
+ /** The mailbox lock, or a `lock-busy` deferral (contention, or an acquisition that threw). */
705
+ async lockOrDefer(roots, what, file) {
706
+ try {
707
+ return (await acquireMailLock(roots.mailbox)) ?? deferred("lock-busy", `mailbox lock busy; ${what}`, file);
708
+ }
709
+ catch (err) {
710
+ return deferred("lock-busy", `mailbox lock unavailable (${sanitizeError(err)}); ${what}`, file);
711
+ }
712
+ }
713
+ emitRecoveryError(err) {
714
+ report(() => this.events?.emit({
715
+ type: "mail.receive", agent: this.agentId, status: "error", from: "unknown", durationMs: 0, error: sanitizeError(err),
716
+ }));
717
+ }
718
+ /** Commit under the mailbox lock; attempt placement rollback on append failure. */
719
+ async commitToCur(roots, file, srcPath, body, envelope,
720
+ /** cli#617 slice (b): the delivery API's presentation claim; absent for the batch checkNewMail() path. */
721
+ claim) {
722
+ const lock = await acquireMailLock(roots.mailbox);
723
+ if (!lock)
724
+ throw new Error("mailbox lock busy; not promoted");
725
+ let relayLock;
726
+ try {
727
+ relayLock = tryAcquireRelayMoveLock(JSON.parse(body), roots.mailRoot);
728
+ }
729
+ catch (error) {
730
+ lock.release();
731
+ throw error;
732
+ }
733
+ if (!relayLock) {
734
+ lock.release();
735
+ throw new Error("relay acceptance busy; not promoted");
736
+ }
737
+ try {
738
+ if (readFileSync(srcPath, "utf-8") !== body)
739
+ throw new Error("source changed during promotion; not promoted");
740
+ const replay = mailboxReplayStore(roots.mailbox);
741
+ if (replay.hasPendingFile(file))
742
+ throw new Error(`pending placement unresolved: ${file}`);
743
+ if (claim && pendingPlacementEntries(roots.mailbox).some((e) => e.phase === "placing" || e.phase === "in_progress")) {
744
+ return "live-placement";
745
+ }
746
+ const dstPath = join(roots.mailbox, "cur", file);
747
+ if (sameFileIdentity(srcPath, dstPath)) {
748
+ replay.isConsumed(envelope.messageId);
749
+ unlinkSync(srcPath);
750
+ return "already-delivered";
751
+ }
752
+ const consumed = replay.isConsumed(envelope.messageId);
753
+ if (consumed) {
754
+ return { pass: false, class: "replay", reason: `replay (envelope messageId ${envelope.messageId} already consumed)` };
755
+ }
756
+ const sourceFd = openSync(srcPath, constants.O_RDONLY | constants.O_NOFOLLOW);
757
+ try {
758
+ replay.beginPlacement(envelope.messageId, file, sourceFd);
759
+ const placement = placeCurRecord(srcPath, dstPath);
760
+ if (placement.status === "exists") {
761
+ replay.finishPlacement(envelope.messageId, file);
762
+ throw new Error(`destination already exists: ${file}`);
763
+ }
764
+ try {
765
+ unlinkSync(srcPath);
766
+ }
767
+ catch (err) {
768
+ unlinkSync(dstPath);
769
+ replay.finishPlacement(envelope.messageId, file);
770
+ throw err;
771
+ }
772
+ try {
773
+ if (!replay.ownsPendingPlacement(envelope.messageId, file))
774
+ throw new Error("placement identity changed");
775
+ replay.recordConsumed(envelope.messageId);
776
+ }
777
+ catch (err) {
778
+ try {
779
+ renameSync(dstPath, srcPath);
780
+ replay.finishPlacement(envelope.messageId, file);
781
+ }
782
+ catch (rollbackErr) {
783
+ throw new AggregateError([err, rollbackErr], `mail commit failed: ${sanitizeError(err)}; rollback failed: ${sanitizeError(rollbackErr)}`);
784
+ }
785
+ throw err;
786
+ }
787
+ if (claim) {
788
+ const advance = replay.advancePresentation(envelope.messageId, file, new Date().toISOString(), claim);
789
+ if (advance.status !== "presented")
790
+ throw new Error(`placement not advanced after commit: ${advance.status}`);
791
+ }
792
+ else {
793
+ replay.finishPlacement(envelope.messageId, file);
794
+ }
795
+ return null;
796
+ }
797
+ finally {
798
+ closeSync(sourceFd);
799
+ }
800
+ }
801
+ finally {
802
+ relayLock.release();
803
+ lock.release();
804
+ }
805
+ }
806
+ /**
807
+ * Recover verified cur copies matching the intent's recorded identity (cli#600).
808
+ * Verification or lock failure defers recovery. A present mismatched copy,
809
+ * including an older intent without identity, leaves the intent pending and
810
+ * withholds delivery; the new/ scan cannot replace that intent.
811
+ */
812
+ async recoverInterruptedPlacements(messages, roots) {
813
+ const root = roots.mailbox;
814
+ let pending;
815
+ let listing = null;
816
+ try {
817
+ listing = await acquireMailLock(root);
818
+ if (!listing)
819
+ return; // lock unavailable; defer recovery
820
+ pending = pendingPlacementEntries(root);
821
+ }
822
+ catch (err) {
823
+ report(() => this.events?.emit({
824
+ type: "mail.receive",
825
+ agent: this.agentId,
826
+ status: "error",
827
+ from: "unknown",
828
+ durationMs: 0,
829
+ error: sanitizeError(err),
830
+ }));
831
+ return; // a later check retries
832
+ }
833
+ finally {
834
+ listing?.release();
835
+ }
836
+ for (const { messageId, file, phase } of pending) {
837
+ if (!resumableOnRecovery(phase))
838
+ continue;
839
+ const curPath = join(root, "cur", file);
840
+ try {
841
+ let bytes;
842
+ try {
843
+ bytes = readFileSync(curPath);
844
+ }
845
+ catch (err) {
846
+ if (err.code !== "ENOENT")
847
+ throw err;
848
+ // Observed absent; re-check under the lock before finishing the intent.
849
+ await this.finishUnlinkedPlacement(messageId, file, root);
850
+ continue;
851
+ }
852
+ const classified = await this.classifyPending(bytes);
853
+ if (classified.kind === "cli")
854
+ continue;
855
+ if (classified.kind === "pending-record-invalid" || classified.kind === "pending-record-ambiguous") {
856
+ await this.quarantinePending(roots, messageId, file, bytes, classified.kind);
857
+ continue;
858
+ }
859
+ const outcome = classified.outcome;
860
+ const trustTier = verifiedMailTier(outcome.envelope, roots.mailRoot);
861
+ const delivered = await this.completeInterruptedPlacement(messageId, file, root, bytes, outcome.envelope, trustTier);
862
+ if (delivered)
863
+ messages.push(delivered);
864
+ }
865
+ catch (err) {
866
+ report(() => this.events?.emit({
867
+ type: "mail.receive",
868
+ agent: this.agentId,
869
+ status: "error",
870
+ from: "unknown",
871
+ durationMs: 0,
872
+ error: sanitizeError(err),
873
+ }));
874
+ }
875
+ }
876
+ }
877
+ /** Finish a still-pending intent only when cur/ is absent under the lock. */
878
+ async finishUnlinkedPlacement(messageId, file, root) {
879
+ const lock = await acquireMailLock(root);
880
+ if (!lock)
881
+ return;
882
+ try {
883
+ const replay = mailboxReplayStore(root);
884
+ if (!replay.hasPendingPlacement(messageId, file))
885
+ return;
886
+ if (!resumableOnRecovery(replay.placementPhase(file)))
887
+ return;
888
+ if (lstatOrAbsent(join(root, "cur", file)) !== null)
889
+ return;
890
+ replay.finishPlacement(messageId, file);
891
+ }
892
+ finally {
893
+ lock.release();
894
+ }
895
+ }
896
+ /**
897
+ * Re-check the intent, recorded identity and raw bytes under the lock.
898
+ */
899
+ async completeInterruptedPlacement(messageId, file, root, bytes, envelope, trustTier) {
900
+ const lock = await acquireMailLock(root);
901
+ if (!lock)
902
+ throw new Error("mailbox lock busy; interrupted placement recovery deferred");
903
+ try {
904
+ const replay = mailboxReplayStore(root);
905
+ // Match the intent, recorded identity and pre-verification raw bytes.
906
+ if (!replay.hasPendingPlacement(messageId, file))
907
+ return null;
908
+ if (!resumableOnRecovery(replay.placementPhase(file)))
909
+ return null;
910
+ if (envelope.messageId !== messageId)
911
+ return null;
912
+ if (!replay.ownsPendingPlacement(messageId, file))
913
+ return null;
914
+ let current;
915
+ try {
916
+ current = readFileSync(join(root, "cur", file));
917
+ }
918
+ catch (err) {
919
+ if (err.code === "ENOENT")
920
+ return null;
921
+ throw err;
922
+ }
923
+ if (!current.equals(bytes))
924
+ return null;
925
+ if (!replay.isConsumed(messageId, file))
926
+ replay.recordConsumed(messageId);
927
+ replay.finishPlacement(messageId, file);
928
+ return {
929
+ filename: file,
930
+ body: bytes.toString("utf8"),
931
+ receivedAt: new Date(),
932
+ headers: {},
933
+ from: envelope.from,
934
+ verifiedEnvelope: envelope,
935
+ trustTier,
936
+ };
937
+ }
938
+ finally {
939
+ lock.release();
940
+ }
941
+ }
942
+ /** Attempt the dlq/ move and sidecar write, then emit the rejection. */
943
+ deadLetter(file, srcPath, rejected, started, roots) {
944
+ const dlqDir = join(roots.mailbox, "dlq");
945
+ const dlqPath = join(dlqDir, file);
946
+ let relayLock = null;
947
+ try {
948
+ let record;
949
+ try {
950
+ record = JSON.parse(readFileSync(srcPath, "utf-8"));
951
+ }
952
+ catch { }
953
+ relayLock = tryAcquireRelayMoveLock(record, roots.mailRoot);
954
+ if (!relayLock)
955
+ return;
956
+ if (srcPath !== dlqPath)
957
+ renameSync(srcPath, dlqPath);
958
+ writeRejectSidecar(dlqDir, file, rejected.class, rejected.reason);
959
+ }
960
+ catch (err) {
961
+ report(() => console.error(`[MailClient] failed to dead-letter ${file}: ${sanitizeError(err)}`));
962
+ }
963
+ finally {
964
+ relayLock?.release();
965
+ }
966
+ report(() => this.events?.emit({
967
+ type: "mail.receive",
968
+ agent: this.agentId,
969
+ status: "rejected",
970
+ from: rejected.from ?? "unknown",
971
+ durationMs: Date.now() - started,
972
+ error: rejected.reason,
973
+ }));
974
+ }
188
975
  /** Write a message to outbox/new for relay delivery. */
189
976
  async sendMail(to, body) {
190
977
  const started = Date.now();
191
978
  try {
979
+ const { mailbox } = this.operationRoots();
192
980
  const { writeFileSync } = await import("node:fs");
981
+ // Sign the body as this agent — the v1 envelope a promote() reader
982
+ // verifies. signMailBody THROWS when no key exists, so an unsigned body
983
+ // is never written.
984
+ const signed = this.signMailBody(to, body);
193
985
  const filename = `${Date.now()}-${Math.random().toString(36).slice(2)}.json`;
194
- writeFileSync(join(this.outboxNew, filename), JSON.stringify({ to, body, sentAt: new Date().toISOString() }, null, 2), "utf-8");
195
- this.events?.emit({
986
+ writeFileSync(join(mailbox, "outbox", filename), JSON.stringify({ from: this.agentId, to, body: signed, sentAt: new Date().toISOString() }, null, 2), "utf-8");
987
+ report(() => this.events?.emit({
196
988
  type: "mail.send",
197
989
  agent: this.agentId,
198
990
  to,
199
991
  status: "ok",
200
992
  durationMs: Date.now() - started,
201
- });
993
+ }));
202
994
  }
203
995
  catch (err) {
204
- this.events?.emit({
996
+ report(() => this.events?.emit({
205
997
  type: "mail.send",
206
998
  agent: this.agentId,
207
999
  to,
208
1000
  status: "error",
209
1001
  durationMs: Date.now() - started,
210
1002
  error: sanitizeError(err),
211
- });
1003
+ }));
212
1004
  throw err;
213
1005
  }
214
1006
  }
1007
+ /**
1008
+ * Sign `body` as this agent into a v1 signed envelope. Throws a named error
1009
+ * when no signing key exists — the same refusal condition as the CLI path,
1010
+ * so an unsigned body a promote() reader would dead-letter is never written.
1011
+ */
1012
+ signMailBody(to, body) {
1013
+ const seed = readAgentPrivateKey(this.agentId, this.signingKeyPath);
1014
+ if (!seed) {
1015
+ const paths = this.signingKeyPath ? [this.signingKeyPath] : agentKeyCandidates(this.agentId);
1016
+ throw new Error(`no Ed25519 private key for agent "${this.agentId}" — refusing to send unsigned mail. Looked at ${paths.join(", then ")}. Provision the agent's key.`);
1017
+ }
1018
+ const now = new Date().toISOString();
1019
+ const chain = [
1020
+ { agent: "system", kind: "human", timestamp: now, rationale: "agent runtime sendMail", signature: null },
1021
+ { agent: this.agentId, kind: "agent", timestamp: now, rationale: `agent ${this.agentId} sendMail`, signature: null },
1022
+ ];
1023
+ const envelope = {
1024
+ v: 1,
1025
+ from: this.agentId,
1026
+ to,
1027
+ subject: `mail to ${to}`,
1028
+ body,
1029
+ messageId: randomUUID(),
1030
+ timestamp: now,
1031
+ delegationChain: chain,
1032
+ };
1033
+ return JSON.stringify(signEnvelope(envelope, { [this.agentId]: Buffer.from(seed) }));
1034
+ }
215
1035
  /** Deliver all messages in outbox to recipient inboxes (local relay). */
216
1036
  deliverOutbox() {
217
- if (!existsSync(this.outboxNew))
1037
+ const roots = this.operationRoots();
1038
+ const outboxNew = join(roots.mailbox, "outbox");
1039
+ if (!existsSync(outboxNew))
218
1040
  return;
219
- const files = readdirSync(this.outboxNew).filter(f => !f.startsWith("."));
1041
+ const files = readdirSync(outboxNew).filter(f => !f.startsWith("."));
220
1042
  for (const file of files) {
221
- const srcPath = join(this.outboxNew, file);
1043
+ const srcPath = join(outboxNew, file);
222
1044
  try {
223
1045
  const raw = readFileSync(srcPath, "utf-8");
224
1046
  const msg = JSON.parse(raw);
225
1047
  if (!msg.to || !/^[a-zA-Z0-9_-]{1,64}$/.test(msg.to)) {
226
1048
  continue; // skip invalid recipients
227
1049
  }
228
- const recipientInbox = join(this.mailDir, msg.to, "new");
1050
+ const recipientInbox = join(roots.mailRoot, msg.to, "new");
229
1051
  mkdirSync(recipientInbox, { recursive: true });
230
1052
  const destFile = `${msg.sentAt.replace(/[:.]/g, "-")}-${file}`;
231
1053
  renameSync(srcPath, join(recipientInbox, destFile));
@@ -236,98 +1058,35 @@ export class MailClient {
236
1058
  }
237
1059
  }
238
1060
  /**
239
- * Verify a mail body against the v1 signed envelope spec AND this mailbox's
240
- * policy: signature, wrapper→envelope `from` binding, recipient binding
241
- * (`envelope.to` must be this mailbox's agent), and `messageId`/`timestamp`
242
- * shape. These are the checks the shared `promote()` applies, so this path
243
- * cannot present mail the shared path would reject.
244
- *
1061
+ * Parse a mail file and run the shared mailbox policy on its signed envelope.
245
1062
  * Returns a terminal `{ pass: false, class, reason }` on a deterministic
246
- * rejection. Called ONLY when a verifier is configured; a THROW (Flair
247
- * unreachable) is a refusal the caller acts on, never a pass.
1063
+ * rejection; a THROW (Flair unreachable) is a refusal the caller acts on,
1064
+ * never a pass.
248
1065
  */
249
1066
  async verifyMailBody(body) {
250
- const client = this.flairClient;
251
- // 1. Parse the mail file as JSON
252
1067
  let mailMsg;
253
1068
  try {
254
1069
  mailMsg = JSON.parse(body);
1070
+ if (mailMsg === null || typeof mailMsg !== "object" || Array.isArray(mailMsg) || typeof mailMsg.body !== "string") {
1071
+ return { pass: false, class: "invalid", reason: "invalid raw mail wrapper" };
1072
+ }
255
1073
  }
256
1074
  catch {
257
1075
  return { pass: false, class: "invalid", reason: "json parse error: invalid JSON" };
258
1076
  }
259
- if (!mailMsg.body || typeof mailMsg.body !== "string") {
260
- return { pass: false, class: "invalid", reason: "json parse error: missing body field" };
261
- }
262
- // 2. Parse the body field as an envelope
263
- let envelope;
264
- try {
265
- envelope = JSON.parse(mailMsg.body);
266
- }
267
- catch {
268
- return { pass: false, class: "invalid", reason: "json parse error: invalid envelope body", from: mailMsg.from };
269
- }
270
- if (envelope == null || typeof envelope !== "object" || Array.isArray(envelope)) {
271
- return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
272
- }
273
- const env = envelope;
274
- if (typeof env.v !== "number" ||
275
- !Array.isArray(env.delegationChain) ||
276
- typeof env.signature !== "string") {
277
- return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
278
- }
279
- // 3. Verify the signature. A THROW here (Flair unreachable) is NOT a pass —
280
- // it propagates to checkNewMail(), which refuses to promote and leaves
281
- // the record in new/ for a later check. The verifier adapter throws on an
282
- // outage, so an outage is RETRYABLE rather than a terminal "not found".
283
- const vr = await verifyEnvelope(env, client);
284
- if (!vr.ok) {
285
- const cls = UNRESOLVABLE_PRINCIPAL_REASON_RE.test(vr.reason)
286
- ? "unresolvable-principal"
287
- : "invalid";
288
- return { pass: false, class: cls, reason: vr.reason, from: mailMsg.from };
289
- }
290
- // 4. The wrapper `from` is what consumers route by, and it is unverified; a
291
- // wrapper/envelope mismatch is itself a reject.
292
- if (mailMsg.from !== env.from) {
293
- return {
294
- pass: false,
295
- class: "invalid",
296
- reason: `wrapper/envelope from mismatch (wrapper.from=${String(mailMsg.from)}, envelope.from=${String(env.from)})`,
297
- from: mailMsg.from,
298
- };
299
- }
300
- // 5. Recipient binding. A signature is NOT recipient-bound, so a correctly
301
- // signed envelope addressed to another principal must not be presented
302
- // here (deliverOutbox writes into any recipient's new/).
303
- if (env.to !== this.agentId) {
304
- return {
305
- pass: false,
306
- class: "wrong-recipient",
307
- reason: `wrong-recipient (envelope.to=${String(env.to)}, mailbox=${this.agentId})`,
308
- from: mailMsg.from,
309
- };
310
- }
311
- // 6. `messageId` shape.
312
- if (typeof env.messageId !== "string" || env.messageId.trim() === "") {
313
- return {
314
- pass: false,
315
- class: "invalid",
316
- reason: `invalid messageId (must be a non-empty string, got ${JSON.stringify(env.messageId)})`,
317
- from: mailMsg.from,
318
- };
319
- }
320
- // 7. `timestamp` shape — a malformed/absent timestamp must not be silently
321
- // accepted (the shared path rejects it too).
322
- if (typeof env.timestamp !== "string" || Number.isNaN(Date.parse(env.timestamp))) {
323
- return {
324
- pass: false,
325
- class: "invalid",
326
- reason: `invalid timestamp (must be an ISO-8601 string, got ${JSON.stringify(env.timestamp)})`,
327
- from: mailMsg.from,
328
- };
329
- }
330
- return { pass: true };
1077
+ const parsed = parseSignedEnvelope(mailMsg.body);
1078
+ if (!parsed.ok)
1079
+ return { pass: false, class: parsed.class, reason: parsed.reason, from: mailMsg.from };
1080
+ const decision = await decideEnvelopeForMailbox(this.agentId, parsed.envelope, mailMsg.from, this.flairClient)
1081
+ .catch((err) => {
1082
+ if (err instanceof PublicKeyFormatError) {
1083
+ return { ok: false, class: "invalid", reason: `signature verification failed: ${err.message}` };
1084
+ }
1085
+ throw err;
1086
+ });
1087
+ if (!decision.ok)
1088
+ return { pass: false, class: decision.class, reason: decision.reason, from: mailMsg.from };
1089
+ return { pass: true, envelope: decision.envelope };
331
1090
  }
332
1091
  }
333
1092
  //# sourceMappingURL=mail.js.map