@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
@@ -0,0 +1,769 @@
1
+ /** Real loop/mailbox tests for settlement retries and verifiable committed recovery. */
2
+
3
+ import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
4
+ import { spawn } from "node:child_process";
5
+ import { createHash, randomUUID } from "node:crypto";
6
+ import {
7
+ existsSync, linkSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync,
8
+ } from "node:fs";
9
+ import { tmpdir } from "node:os";
10
+ import { join } from "node:path";
11
+ import { fileURLToPath } from "node:url";
12
+ import * as ed from "@noble/ed25519";
13
+ import { type DeliverNextResult, type MailDelivery, MailClient } from "../src/io/mail.js";
14
+ import { AgentRuntime } from "../src/runtime/agent.js";
15
+ import { MemoryStore } from "../src/io/memory.js";
16
+ import { ProviderManager } from "../src/llm/provider.js";
17
+ import { FlairContextProvider } from "../src/io/flair.js";
18
+ import { EventLoop, type MailDeliverySource } from "../src/runtime/event-loop.js";
19
+ import { DELIVERY_PRESENTATION_TTL_MS, mailboxReplayStore } from "../src/lib/mailbox-policy.js";
20
+ import { signEnvelope, type FlairClient } from "../src/lib/signEnvelope.js";
21
+
22
+ const AGENT = "agent-a";
23
+ const FROM = "agent-b";
24
+ const SEED = Buffer.alloc(32, 0x61);
25
+ const CHILD = fileURLToPath(new URL("./helpers/event-loop-child.mjs", import.meta.url));
26
+
27
+ let mailDir: string;
28
+ let root: string;
29
+ let workspace: string;
30
+
31
+ const cur = (file: string) => join(root, "cur", file);
32
+ const fresh = (file: string) => join(root, "new", file);
33
+ const intentPath = (file: string) => join(root, `.placement-${createHash("sha256").update(file).digest("hex")}.json`);
34
+ const intentPhase = (file: string) => mailboxReplayStore(root).placementPhase(file);
35
+ const intentJson = (file: string) => JSON.parse(readFileSync(intentPath(file), "utf8"));
36
+ const jsonFiles = (dir: string) => (existsSync(dir) ? readdirSync(dir).filter((n) => n.endsWith(".json")).sort() : []);
37
+ const newFiles = () => jsonFiles(join(root, "new"));
38
+ const curFiles = () => jsonFiles(join(root, "cur"));
39
+ const delivered = (result: DeliverNextResult): MailDelivery => {
40
+ if (result.status !== "delivered") throw new Error(`expected a delivery, got ${JSON.stringify(result)}`);
41
+ return result.delivery;
42
+ };
43
+
44
+ /** How many consumed-ledger lines carry `id`. */
45
+ function ledgerIds(id: string): number {
46
+ const path = join(root, "consumed.jsonl");
47
+ if (!existsSync(path)) return 0;
48
+ return readFileSync(path, "utf8").split("\n").filter((line) => line && JSON.parse(line).id === id).length;
49
+ }
50
+
51
+ function verifier(): FlairClient {
52
+ return { async getAgent(name: string) { return name === FROM ? { publicKey: Buffer.from(ed.getPublicKey(SEED)) } : null; } };
53
+ }
54
+ const client = () => new MailClient(mailDir, undefined, AGENT, verifier());
55
+
56
+ beforeEach(() => {
57
+ mailDir = mkdtempSync(join(tmpdir(), "mail-loop-delivery-"));
58
+ root = join(mailDir, AGENT);
59
+ workspace = join(mailDir, "ws");
60
+ mkdirSync(join(root, "new"), { recursive: true });
61
+ mkdirSync(join(root, "cur"), { recursive: true });
62
+ mkdirSync(workspace, { recursive: true });
63
+ });
64
+
65
+ afterEach(() => rmSync(mailDir, { recursive: true, force: true }));
66
+
67
+ /** Write one signed record to `path`. */
68
+ function signedRecord(path: string, messageId: string, body = "loop-body"): void {
69
+ const timestamp = new Date().toISOString();
70
+ const envelope = signEnvelope(
71
+ {
72
+ v: 1, from: FROM, to: AGENT, body, messageId, timestamp,
73
+ delegationChain: [
74
+ { agent: "system", kind: "human", timestamp, rationale: "originates", signature: null },
75
+ { agent: FROM, kind: "agent", timestamp, rationale: "sends", signature: null },
76
+ ],
77
+ },
78
+ { [FROM]: SEED },
79
+ );
80
+ writeFileSync(path, JSON.stringify({ from: FROM, body: JSON.stringify(envelope) }));
81
+ }
82
+
83
+ const plant = (file: string, messageId: string, body = "loop-body") => signedRecord(fresh(file), messageId, body);
84
+
85
+ interface Seen { id: string; presentation: number; }
86
+
87
+ /**
88
+ * Run the real EventLoop against `c` and record every delivery. The loop runs
89
+ * until `stopAfter` deliveries have been handed over, or a delivery names
90
+ * `stopOnId`, whichever comes first.
91
+ */
92
+ async function runLoop(
93
+ c: MailClient,
94
+ opts: { provider: { complete: (req: unknown) => Promise<unknown> }; maxToolTurns?: number; stopAfter?: number; stopOnId?: string },
95
+ ): Promise<Seen[]> {
96
+ const seen: Seen[] = [];
97
+ const config = {
98
+ agentId: AGENT, name: "loop-test", mailDir, memoryPath: join(workspace, "mem.jsonl"), workspace,
99
+ llm: { provider: "test", model: "test-model" }, contextWindowTokens: 8000,
100
+ maxToolTurns: opts.maxToolTurns ?? 50,
101
+ };
102
+ const loop = new EventLoop({
103
+ config: config as never,
104
+ memory: { append: async () => {} } as never,
105
+ context: {} as never,
106
+ provider: opts.provider as never,
107
+ tools: { list: () => [], execute: async () => ({ content: "ok" }) } as never,
108
+ }, 1);
109
+ const stopAfter = opts.stopAfter ?? Number.POSITIVE_INFINITY;
110
+ let handovers = 0;
111
+ const source: MailDeliverySource = {
112
+ async deliverNext() {
113
+ const result = await c.deliverNext();
114
+ if (result.status === "delivered") {
115
+ const id = result.delivery.message.verifiedEnvelope?.messageId ?? "?";
116
+ seen.push({ id, presentation: result.delivery.presentation });
117
+ if (++handovers >= stopAfter || id === opts.stopOnId) void loop.stop();
118
+ }
119
+ return result;
120
+ },
121
+ completeDelivery: (delivery) => c.completeDelivery(delivery),
122
+ releaseDelivery: (delivery) => c.releaseDelivery(delivery),
123
+ };
124
+ await loop.runDeliveries(source);
125
+ return seen;
126
+ }
127
+
128
+ /** A provider whose handler returns a normal completion. */
129
+ const completingProvider = { async complete() { return { content: "done", toolCalls: undefined, inputTokens: 1, outputTokens: 1 }; } };
130
+ /** A provider whose handler always requests a tool call, so the turn limit is reached. */
131
+ const toolCallingProvider = { async complete() { return { content: "", toolCalls: [{ id: "t1", name: "noop", input: {} }], inputTokens: 1, outputTokens: 1 }; } };
132
+ /** Requests a tool call for a body containing `poison-body`. */
133
+ const poisonAwareProvider = {
134
+ async complete(req: unknown) {
135
+ const text = JSON.stringify((req as { messages?: unknown }).messages ?? "");
136
+ return text.includes("poison-body")
137
+ ? { content: "", toolCalls: [{ id: "t1", name: "noop", input: {} }], inputTokens: 1, outputTokens: 1 }
138
+ : { content: "done", toolCalls: undefined, inputTokens: 1, outputTokens: 1 };
139
+ },
140
+ };
141
+
142
+ interface KillRun { signal: NodeJS.Signals | null; reached: boolean; stderr: string; }
143
+
144
+ /** Run the loop in a child; SIGKILL it once its handler writes the marker. */
145
+ function runChildAndKill(timeoutMs = 30_000): Promise<KillRun> {
146
+ const marker = join(mailDir, "child-in-handler");
147
+ const child = spawn(process.execPath, [CHILD, mailDir, AGENT], {
148
+ env: {
149
+ HOME: mailDir,
150
+ PATH: process.env.PATH,
151
+ TPS_FROM: FROM,
152
+ TPS_SEED: SEED.toString("base64"),
153
+ TPS_MARKER: marker,
154
+ TPS_WORKSPACE: workspace,
155
+ },
156
+ stdio: ["ignore", "pipe", "pipe"],
157
+ });
158
+ return new Promise<KillRun>((resolve, reject) => {
159
+ let stderr = "";
160
+ let settled = false;
161
+ child.stderr.on("data", (d) => { stderr += d.toString(); });
162
+ const poll = setInterval(() => {
163
+ if (!existsSync(marker)) return;
164
+ clearInterval(poll);
165
+ child.kill("SIGKILL");
166
+ }, 15);
167
+ const deadline = setTimeout(() => {
168
+ if (settled) return;
169
+ settled = true; clearInterval(poll); clearTimeout(deadline);
170
+ child.kill("SIGKILL");
171
+ reject(new Error(`child never reached the handler (stderr: ${stderr})`));
172
+ }, timeoutMs);
173
+ child.once("error", (e) => { if (!settled) { settled = true; clearInterval(poll); clearTimeout(deadline); reject(e); } });
174
+ child.once("exit", (_code, signal) => {
175
+ if (settled) return;
176
+ settled = true; clearInterval(poll); clearTimeout(deadline);
177
+ resolve({ signal, reached: existsSync(marker), stderr });
178
+ });
179
+ });
180
+ }
181
+
182
+ describe("a committed delivery killed mid-handler is re-presented when verification succeeds", () => {
183
+ test("first delivery, killed while in_progress: re-presented once, later mail handled", async () => {
184
+ plant("m1.json", "kill-first");
185
+ plant("m2.json", "later");
186
+
187
+ const run = await runChildAndKill();
188
+ expect(run.reached, `child never reached the handler; stderr=${run.stderr}`).toBe(true);
189
+ expect(run.signal).toBe("SIGKILL");
190
+ expect(intentPhase("m1.json")).toBe("in_progress");
191
+ expect(newFiles()).toEqual(["m2.json"]);
192
+ expect(curFiles()).toEqual(["m1.json"]);
193
+
194
+ const seen = await runLoop(client(), { provider: completingProvider, stopAfter: 2 });
195
+ expect(seen).toEqual([{ id: "kill-first", presentation: 2 }, { id: "later", presentation: 1 }]);
196
+ expect(newFiles()).toEqual([]);
197
+ expect(intentPhase("m1.json")).toBeNull();
198
+ expect(intentPhase("m2.json")).toBeNull();
199
+ });
200
+
201
+ test("recovery, killed while in_progress: re-presented once, later mail handled", async () => {
202
+ plant("m1.json", "kill-recovered");
203
+ linkSync(fresh("m1.json"), cur("m1.json"));
204
+ unlinkSync(fresh("m1.json"));
205
+ mailboxReplayStore(root).beginPlacement("kill-recovered", "m1.json", cur("m1.json"));
206
+ plant("m2.json", "later");
207
+
208
+ const run = await runChildAndKill();
209
+ expect(run.reached, `child never reached the handler; stderr=${run.stderr}`).toBe(true);
210
+ expect(run.signal).toBe("SIGKILL");
211
+ expect(intentPhase("m1.json")).toBe("in_progress");
212
+ expect(newFiles()).toEqual(["m2.json"]);
213
+
214
+ const seen = await runLoop(client(), { provider: completingProvider, stopAfter: 2 });
215
+ expect(seen).toEqual([{ id: "kill-recovered", presentation: 2 }, { id: "later", presentation: 1 }]);
216
+ expect(newFiles()).toEqual([]);
217
+ expect(intentPhase("m1.json")).toBeNull();
218
+ });
219
+ });
220
+
221
+ describe("a stop finalizes a returned delivery when completion succeeds", () => {
222
+ test("durably finalized mail is not re-presented; later mail is handled next", async () => {
223
+ plant("m1.json", "first");
224
+ plant("m2.json", "second");
225
+ plant("m3.json", "third");
226
+
227
+ const first = await runLoop(client(), { provider: completingProvider, stopAfter: 1 });
228
+ expect(first).toEqual([{ id: "first", presentation: 1 }]);
229
+ expect(newFiles()).toEqual(["m2.json", "m3.json"]);
230
+ expect(curFiles()).toEqual(["m1.json"]);
231
+ expect(intentPhase("m1.json")).toBeNull();
232
+
233
+ const next = await runLoop(client(), { provider: completingProvider, stopAfter: 2 });
234
+ expect(next).toEqual([{ id: "second", presentation: 1 }, { id: "third", presentation: 1 }]);
235
+ expect(newFiles()).toEqual([]);
236
+ expect(intentPhase("m1.json")).toBeNull();
237
+ });
238
+ });
239
+
240
+ describe("a turn-limit return is not completion", () => {
241
+ test("the intent stays in_progress and the message is re-presented on the next check", async () => {
242
+ plant("m1.json", "turn-limited");
243
+
244
+ const first = await runLoop(client(), { provider: toolCallingProvider, maxToolTurns: 0, stopAfter: 1 });
245
+ expect(first).toEqual([{ id: "turn-limited", presentation: 1 }]);
246
+ const intent = intentJson("m1.json");
247
+ expect(intent.phase).toBe("in_progress");
248
+ expect(intent.claim).toBeUndefined();
249
+ expect(curFiles()).toEqual(["m1.json"]);
250
+
251
+ const again = await runLoop(client(), { provider: toolCallingProvider, maxToolTurns: 0, stopAfter: 1 });
252
+ expect(again).toEqual([{ id: "turn-limited", presentation: 2 }]);
253
+ expect(intentJson("m1.json").phase).toBe("in_progress");
254
+ });
255
+ });
256
+
257
+ describe("the liveness bound quarantines repeated non-completion", () => {
258
+ test("five presentations then the intent is failed with its log line, and other mail keeps flowing", async () => {
259
+ plant("m1.json", "poison", "poison-body");
260
+ plant("m2.json", "healthy", "healthy-body");
261
+
262
+ const warnings: string[] = [];
263
+ const warn = spyOn(console, "warn").mockImplementation((...args: unknown[]) => { warnings.push(args.join(" ")); });
264
+ let seen: Seen[] = [];
265
+ try {
266
+ seen = await runLoop(client(), { provider: poisonAwareProvider, maxToolTurns: 0, stopOnId: "healthy" });
267
+ } finally {
268
+ warn.mockRestore();
269
+ }
270
+
271
+ expect(seen.filter((d) => d.id === "poison").map((d) => d.presentation)).toEqual([1, 2, 3, 4, 5]);
272
+ expect(seen.filter((d) => d.id === "healthy")).toEqual([{ id: "healthy", presentation: 1 }]);
273
+ expect(intentPhase("m1.json")).toBe("failed");
274
+ expect(warnings.some((w) => w.includes("poison") && w.includes("presentation bound"))).toBe(true);
275
+ expect(intentPhase("m2.json")).toBeNull();
276
+ });
277
+ });
278
+
279
+ describe("a re-presented message is never committed twice", () => {
280
+ test("a non-completion then a re-presentation leaves one cur/ record and one consumed ID", async () => {
281
+ plant("m1.json", "once-only");
282
+ await runLoop(client(), { provider: toolCallingProvider, maxToolTurns: 0, stopAfter: 1 });
283
+
284
+ expect(curFiles()).toEqual(["m1.json"]);
285
+ expect(newFiles()).toEqual([]);
286
+ expect(ledgerIds("once-only")).toBe(1);
287
+ const identity = intentJson("m1.json").identity;
288
+ const bytes = readFileSync(cur("m1.json"));
289
+
290
+ const c = client();
291
+ const m = delivered(await c.deliverNext());
292
+ expect(m.presentation).toBe(2);
293
+ expect(curFiles()).toEqual(["m1.json"]);
294
+ expect(newFiles()).toEqual([]);
295
+ expect(ledgerIds("once-only")).toBe(1);
296
+ expect(intentJson("m1.json").identity).toEqual(identity);
297
+ expect(readFileSync(cur("m1.json")).equals(bytes)).toBe(true);
298
+ expect(await c.completeDelivery(m)).toEqual({ status: "completed" });
299
+ });
300
+ });
301
+
302
+ for (const operation of ["completeDelivery", "releaseDelivery"] as const) {
303
+ test(`${operation} retries the same deferred delivery before later mail`, async () => {
304
+ plant("m1.json", "retry", "poison-body");
305
+ plant("m2.json", "later", "healthy-body");
306
+ const c = client();
307
+ const original = c[operation].bind(c);
308
+ let attempts = 0;
309
+ let held: MailDelivery | undefined;
310
+ const next = c.deliverNext.bind(c);
311
+ const nextSpy = spyOn(c, "deliverNext").mockImplementation(async () => {
312
+ expect(held).toBeUndefined();
313
+ return next();
314
+ });
315
+ const claimDir = join(root, ".mail-lock.claim");
316
+ const savedMailbox = `${root}.saved`;
317
+ const provider = {
318
+ async complete(req: unknown) {
319
+ if (attempts === 0) {
320
+ if (operation === "completeDelivery") mkdirSync(claimDir);
321
+ else {
322
+ renameSync(root, savedMailbox);
323
+ writeFileSync(root, "not a directory");
324
+ }
325
+ }
326
+ return poisonAwareProvider.complete(req);
327
+ },
328
+ };
329
+ const observe = (delivery: MailDelivery, result: { status: string; reason?: string }) => {
330
+ if (delivery.message.verifiedEnvelope?.messageId !== "retry" || attempts >= 2) return;
331
+ attempts++;
332
+ if (attempts === 1) {
333
+ expect(result).toMatchObject({ status: "deferred", reason: operation === "completeDelivery" ? "lock-busy" : "storage-error" });
334
+ held = delivery;
335
+ if (operation === "completeDelivery") rmSync(claimDir, { recursive: true });
336
+ else {
337
+ rmSync(root);
338
+ renameSync(savedMailbox, root);
339
+ }
340
+ expect(intentJson("m1.json").claim).toBeDefined();
341
+ } else {
342
+ expect(delivery).toBe(held);
343
+ expect(result.status).toBe(operation === "completeDelivery" ? "completed" : "released");
344
+ held = undefined;
345
+ }
346
+ };
347
+ const settlementSpy = operation === "completeDelivery"
348
+ ? spyOn(c, "completeDelivery").mockImplementation(async (delivery) => {
349
+ const result = await (original as MailClient["completeDelivery"])(delivery);
350
+ observe(delivery, result);
351
+ return result;
352
+ })
353
+ : spyOn(c, "releaseDelivery").mockImplementation((delivery) => {
354
+ const result = (original as MailClient["releaseDelivery"])(delivery);
355
+ observe(delivery, result);
356
+ return result;
357
+ });
358
+ try {
359
+ const seen = await runLoop(c, {
360
+ provider: operation === "completeDelivery" ? {
361
+ async complete(req) { await provider.complete(req); return completingProvider.complete(); },
362
+ } : provider,
363
+ maxToolTurns: 0, stopOnId: "later",
364
+ });
365
+ expect(attempts).toBe(2);
366
+ expect(seen.at(-1)).toEqual({ id: "later", presentation: 1 });
367
+ expect(intentPhase("m2.json")).toBeNull();
368
+ expect(held).toBeUndefined();
369
+ } finally {
370
+ settlementSpy.mockRestore();
371
+ nextSpy.mockRestore();
372
+ }
373
+ }, 15_000);
374
+
375
+ test(`${operation} quarantines an overdue deferred claim once the mailbox lock and storage are available`, async () => {
376
+ plant("m1.json", "overdue");
377
+ plant("m2.json", "later");
378
+ const c = client();
379
+ const claimDir = join(root, ".mail-lock.claim");
380
+ let attempts = 0;
381
+ const original = c[operation].bind(c);
382
+ const expire = () => {
383
+ attempts++;
384
+ if (attempts !== 1) return;
385
+ const intent = intentJson("m1.json");
386
+ intent.firstPresentedAt = new Date(Date.now() - DELIVERY_PRESENTATION_TTL_MS - 1_000).toISOString();
387
+ writeFileSync(intentPath("m1.json"), JSON.stringify(intent));
388
+ mkdirSync(claimDir);
389
+ };
390
+ const observe = (result: { status: string }) => {
391
+ if (attempts === 1) {
392
+ expect(result.status).toBe("deferred");
393
+ rmSync(claimDir, { recursive: true });
394
+ } else if (attempts === 2) expect(result.status).toBe("quarantined");
395
+ };
396
+ const settlementSpy = operation === "completeDelivery"
397
+ ? spyOn(c, "completeDelivery").mockImplementation(async (delivery) => {
398
+ expire();
399
+ const result = await (original as MailClient["completeDelivery"])(delivery);
400
+ observe(result); return result;
401
+ })
402
+ : spyOn(c, "releaseDelivery").mockImplementation((delivery) => {
403
+ expire();
404
+ const result = (original as MailClient["releaseDelivery"])(delivery);
405
+ observe(result); return result;
406
+ });
407
+ try {
408
+ const seen = await runLoop(c, {
409
+ provider: operation === "completeDelivery" ? completingProvider : toolCallingProvider,
410
+ maxToolTurns: 0, stopOnId: "later",
411
+ });
412
+ expect(seen).toEqual([{ id: "overdue", presentation: 1 }, { id: "later", presentation: 1 }]);
413
+ expect(intentPhase("m1.json")).toBe("failed");
414
+ expect(intentJson("m1.json").claim).toBeUndefined();
415
+ expect(existsSync(cur("m1.json"))).toBe(true);
416
+ } finally { settlementSpy.mockRestore(); }
417
+ }, 15_000);
418
+ }
419
+
420
+ for (const signal of ["SIGINT", "SIGTERM"] as const) {
421
+ for (const refusal of ["identity", "stale"] as const) {
422
+ test(`AgentRuntime.start logs ${refusal} refusal and keeps the intent pending after ${signal}`, async () => {
423
+ plant("m1.json", `${refusal}-refusal`);
424
+ plant("m2.json", "later");
425
+ let enter!: () => void;
426
+ const entered = new Promise<void>((resolve) => { enter = resolve; });
427
+ let finish!: () => void;
428
+ const finishing = new Promise<void>((resolve) => { finish = resolve; });
429
+ const lookup = spyOn(FlairContextProvider.prototype, "getAgent").mockImplementation(async () => ({ publicKey: Buffer.from(ed.getPublicKey(SEED)).toString("base64") }) as never);
430
+ const provider = spyOn(ProviderManager.prototype, "complete").mockImplementation(async () => {
431
+ if (refusal === "identity") {
432
+ writeFileSync(cur("m1.json"), `${readFileSync(cur("m1.json"), "utf8")} `);
433
+ } else {
434
+ const intent = intentJson("m1.json");
435
+ intent.claim.token = randomUUID();
436
+ intent.claim.moduleNonce = randomUUID();
437
+ writeFileSync(intentPath("m1.json"), JSON.stringify(intent));
438
+ }
439
+ enter(); await finishing;
440
+ return completingProvider.complete();
441
+ });
442
+ const memoryPath = join(workspace, "memory.jsonl");
443
+ const pidPath = join(workspace, ".tps-agent.pid");
444
+ const runtime = new AgentRuntime({
445
+ agentId: AGENT, name: `${refusal}-refusal-test`, mailDir, workspace, memoryPath,
446
+ llm: { provider: "openai", model: "test", apiKey: "test" },
447
+ });
448
+ const seen: string[] = [];
449
+ const next = MailClient.prototype.deliverNext;
450
+ const nextSpy = spyOn(MailClient.prototype, "deliverNext").mockImplementation(async function() {
451
+ const result = await next.call(this);
452
+ if (result.status === "delivered") seen.push(result.delivery.message.verifiedEnvelope!.messageId);
453
+ return result;
454
+ });
455
+ const complete = MailClient.prototype.completeDelivery;
456
+ const settlementSpy = spyOn(MailClient.prototype, "completeDelivery").mockImplementation(async function(delivery) {
457
+ expect(existsSync(pidPath)).toBe(true);
458
+ const before = readFileSync(intentPath("m1.json"), "utf8");
459
+ const result = await complete.call(this, delivery);
460
+ expect(result).toMatchObject({ status: "refused", reason: refusal });
461
+ expect(readFileSync(intentPath("m1.json"), "utf8")).toBe(before);
462
+ return result;
463
+ });
464
+ let loopReturned = false;
465
+ const run = EventLoop.prototype.runDeliveries;
466
+ const loopSpy = spyOn(EventLoop.prototype, "runDeliveries").mockImplementation(async function(source) {
467
+ await run.call(this, source);
468
+ expect(existsSync(pidPath)).toBe(true);
469
+ loopReturned = true;
470
+ });
471
+ const start = runtime.start();
472
+ void start.catch(() => {});
473
+ try {
474
+ await entered;
475
+ const pending = readFileSync(intentPath("m1.json"), "utf8");
476
+ process.emit(signal);
477
+ expect(loopReturned).toBe(false);
478
+ expect(existsSync(pidPath)).toBe(true);
479
+ finish();
480
+ await start;
481
+ expect(settlementSpy).toHaveBeenCalledTimes(1);
482
+ expect(loopReturned).toBe(true);
483
+ expect(existsSync(pidPath)).toBe(false);
484
+ expect(readFileSync(memoryPath, "utf8").trim().split("\n").map((line) => JSON.parse(line))).toContainEqual({
485
+ type: "error", ts: expect.any(String), data: `delivery settlement refused: ${refusal}`,
486
+ });
487
+ expect(readFileSync(intentPath("m1.json"), "utf8")).toBe(pending);
488
+ expect(intentPhase("m1.json")).toBe("in_progress");
489
+ expect(intentJson("m1.json").claim).toBeDefined();
490
+ expect(nextSpy).toHaveBeenCalledTimes(1);
491
+ expect(seen).toEqual([`${refusal}-refusal`]);
492
+ expect(await client().deliverNext()).toMatchObject({ status: "deferred", reason: refusal === "identity" ? "record-changed" : "active" });
493
+ expect(seen).toEqual([`${refusal}-refusal`]);
494
+ expect(newFiles()).toEqual(["m2.json"]);
495
+ expect(curFiles()).toEqual(["m1.json"]);
496
+ } finally {
497
+ finish();
498
+ await runtime.stop();
499
+ await start.catch(() => {});
500
+ loopSpy.mockRestore(); settlementSpy.mockRestore(); nextSpy.mockRestore();
501
+ provider.mockRestore(); lookup.mockRestore();
502
+ }
503
+ }, 15_000);
504
+ }
505
+
506
+ test(`AgentRuntime.start attempts release after memory writes fail during ${signal} before removing its PID file`, async () => {
507
+ plant("m1.json", "memory-failure");
508
+ plant("m2.json", "later");
509
+ let enter!: () => void;
510
+ const entered = new Promise<void>((resolve) => { enter = resolve; });
511
+ let finish!: () => void;
512
+ const finishing = new Promise<void>((resolve) => { finish = resolve; });
513
+ const lookup = spyOn(FlairContextProvider.prototype, "getAgent").mockImplementation(async () => ({ publicKey: Buffer.from(ed.getPublicKey(SEED)).toString("base64") }) as never);
514
+ const provider = spyOn(ProviderManager.prototype, "complete").mockImplementation(async () => {
515
+ enter(); await finishing;
516
+ return completingProvider.complete();
517
+ });
518
+ const memoryPath = join(workspace, "memory.jsonl");
519
+ const pidPath = join(workspace, ".tps-agent.pid");
520
+ const runtime = new AgentRuntime({
521
+ agentId: AGENT, name: "memory-failure-test", mailDir, workspace, memoryPath,
522
+ llm: { provider: "openai", model: "test", apiKey: "test" },
523
+ });
524
+ const append = MemoryStore.prototype.append;
525
+ const failedWrites: string[] = [];
526
+ const memorySpy = spyOn(MemoryStore.prototype, "append").mockImplementation(function(event) {
527
+ try { return append.call(this, event); }
528
+ catch (error) { failedWrites.push(event.type); throw error; }
529
+ });
530
+ const errorLog = spyOn(console, "error").mockImplementation(() => {});
531
+ let released = false;
532
+ const release = MailClient.prototype.releaseDelivery;
533
+ const settlementSpy = spyOn(MailClient.prototype, "releaseDelivery").mockImplementation(function(delivery) {
534
+ expect(existsSync(pidPath)).toBe(true);
535
+ expect(intentJson("m1.json").claim).toBeDefined();
536
+ const result = release.call(this, delivery);
537
+ expect(result.status).toBe("released");
538
+ expect(intentJson("m1.json").claim).toBeUndefined();
539
+ released = true;
540
+ return result;
541
+ });
542
+ const start = runtime.start();
543
+ void start.catch(() => {});
544
+ try {
545
+ await entered;
546
+ expect(intentJson("m1.json").claim).toBeDefined();
547
+ expect(existsSync(memoryPath)).toBe(true);
548
+ renameSync(memoryPath, `${memoryPath}.saved`);
549
+ mkdirSync(memoryPath);
550
+ process.emit(signal);
551
+ expect(existsSync(pidPath)).toBe(true);
552
+ finish();
553
+ await start;
554
+ expect(failedWrites).toEqual(["assistant", "error"]);
555
+ expect(errorLog).toHaveBeenCalledWith(expect.stringContaining("Failed to record event-loop error"), expect.any(String));
556
+ expect(released).toBe(true);
557
+ expect(existsSync(pidPath)).toBe(false);
558
+ expect(intentJson("m1.json").claim).toBeUndefined();
559
+ expect(newFiles()).toEqual(["m2.json"]);
560
+ } finally {
561
+ finish();
562
+ await runtime.stop();
563
+ await start.catch(() => {});
564
+ settlementSpy.mockRestore(); memorySpy.mockRestore(); errorLog.mockRestore();
565
+ provider.mockRestore(); lookup.mockRestore();
566
+ }
567
+ }, 15_000);
568
+
569
+ for (const completed of [true, false]) {
570
+ test(`AgentRuntime.start retries deferred ${completed ? "finalize" : "release"} after ${signal} before removing its PID file`, async () => {
571
+ plant("m1.json", "in-flight");
572
+ plant("m2.json", "later");
573
+ let enter!: () => void;
574
+ const entered = new Promise<void>((resolve) => { enter = resolve; });
575
+ let finish!: () => void;
576
+ const finishing = new Promise<void>((resolve) => { finish = resolve; });
577
+ const lookup = spyOn(FlairContextProvider.prototype, "getAgent").mockImplementation(async () => ({ publicKey: Buffer.from(ed.getPublicKey(SEED)).toString("base64") }) as never);
578
+ const provider = spyOn(ProviderManager.prototype, "complete").mockImplementation(async () => {
579
+ enter(); await finishing;
580
+ return completed ? completingProvider.complete() : toolCallingProvider.complete();
581
+ });
582
+ const runtime = new AgentRuntime({
583
+ agentId: AGENT, name: "signal-test", mailDir, workspace,
584
+ memoryPath: join(workspace, "memory.jsonl"), maxToolTurns: 0,
585
+ llm: { provider: "openai", model: "test", apiKey: "test" },
586
+ });
587
+ let returned = false;
588
+ const start = runtime.start().then(() => { returned = true; });
589
+ const pidPath = join(workspace, ".tps-agent.pid");
590
+ const claimDir = join(root, ".mail-lock.claim");
591
+ const original = MailClient.prototype[completed ? "completeDelivery" : "releaseDelivery"];
592
+ let deferred!: () => void;
593
+ const deferring = new Promise<void>((resolve) => { deferred = resolve; });
594
+ const settlementSpy = completed
595
+ ? spyOn(MailClient.prototype, "completeDelivery").mockImplementation(async function(delivery) {
596
+ const result = await (original as MailClient["completeDelivery"]).call(this, delivery);
597
+ if (result.status === "deferred") deferred();
598
+ return result;
599
+ })
600
+ : spyOn(MailClient.prototype, "releaseDelivery").mockImplementation(function(delivery) {
601
+ const result = (original as MailClient["releaseDelivery"]).call(this, delivery);
602
+ if (result.status === "deferred") deferred();
603
+ return result;
604
+ });
605
+ try {
606
+ await entered;
607
+ process.emit(signal);
608
+ await new Promise((resolve) => setTimeout(resolve, 10));
609
+ expect(returned).toBe(false);
610
+ expect(existsSync(pidPath)).toBe(true);
611
+ mkdirSync(claimDir);
612
+ finish();
613
+ await deferring;
614
+ expect(returned).toBe(false);
615
+ expect(existsSync(pidPath)).toBe(true);
616
+ expect(intentJson("m1.json").claim).toBeDefined();
617
+ rmSync(claimDir, { recursive: true });
618
+ await start;
619
+ expect(existsSync(pidPath)).toBe(false);
620
+ expect(newFiles()).toEqual(["m2.json"]);
621
+ expect(completed ? intentPhase("m1.json") : intentJson("m1.json").claim).toBe(completed ? null : undefined);
622
+ } finally {
623
+ finish();
624
+ rmSync(claimDir, { recursive: true, force: true });
625
+ await runtime.stop();
626
+ await start;
627
+ settlementSpy.mockRestore(); provider.mockRestore(); lookup.mockRestore();
628
+ }
629
+ }, 15_000);
630
+ }
631
+ }
632
+
633
+ test("a settlement refusal whose durable record fails still logs the refusal reason", async () => {
634
+ plant("m1.json", "identity-refusal");
635
+ const c = client();
636
+ const memoryPath = join(workspace, "memory.jsonl");
637
+ const memory = new MemoryStore(memoryPath);
638
+ const config = {
639
+ agentId: AGENT, name: "refusal-log", mailDir, memoryPath, workspace,
640
+ llm: { provider: "test", model: "test-model" }, contextWindowTokens: 8000, maxToolTurns: 50,
641
+ };
642
+ const provider = {
643
+ async complete() {
644
+ // Break the committed cur/ record's identity so the settlement is refused.
645
+ writeFileSync(cur("m1.json"), `${readFileSync(cur("m1.json"), "utf8")} `);
646
+ return completingProvider.complete();
647
+ },
648
+ };
649
+ const loop = new EventLoop({
650
+ config: config as never,
651
+ memory,
652
+ context: {} as never,
653
+ provider: provider as never,
654
+ tools: { list: () => [], execute: async () => ({ content: "ok" }) } as never,
655
+ }, 1);
656
+ const errorLog = spyOn(console, "error").mockImplementation(() => {});
657
+ const complete = c.completeDelivery.bind(c);
658
+ const settlementSpy = spyOn(c, "completeDelivery").mockImplementation(async (delivery) => {
659
+ // The real memory file becomes unwritable (a directory) before the refusal is recorded.
660
+ renameSync(memoryPath, `${memoryPath}.saved`);
661
+ mkdirSync(memoryPath);
662
+ const result = await complete(delivery);
663
+ expect(result).toMatchObject({ status: "refused", reason: "identity" });
664
+ return result;
665
+ });
666
+ const source: MailDeliverySource = {
667
+ async deliverNext() {
668
+ const result = await c.deliverNext();
669
+ if (result.status === "delivered") void loop.stop();
670
+ return result;
671
+ },
672
+ completeDelivery: (delivery) => c.completeDelivery(delivery),
673
+ releaseDelivery: (delivery) => c.releaseDelivery(delivery),
674
+ };
675
+ try {
676
+ await loop.runDeliveries(source);
677
+ const refusal = errorLog.mock.calls.find((call) => String(call[0]).includes("delivery settlement refused: identity"));
678
+ expect(refusal).toBeDefined();
679
+ expect(String(refusal?.[1]).length).toBeGreaterThan(0);
680
+ expect(intentPhase("m1.json")).toBe("in_progress");
681
+ } finally {
682
+ settlementSpy.mockRestore();
683
+ errorLog.mockRestore();
684
+ }
685
+ }, 15_000);
686
+
687
+ /** The loop config a settlement test drives; the memory mock records every appended event. */
688
+ function settlementLoop(events: Array<{ data?: unknown }>, provider: unknown, pollMs = 1): EventLoop {
689
+ const config = {
690
+ agentId: AGENT, name: "settlement-bound", mailDir, memoryPath: join(workspace, "mem.jsonl"), workspace,
691
+ llm: { provider: "test", model: "test-model" }, contextWindowTokens: 8000, maxToolTurns: 50,
692
+ };
693
+ return new EventLoop({
694
+ config: config as never,
695
+ memory: { append: async (event: unknown) => { events.push(event as { data?: unknown }); } } as never,
696
+ context: {} as never,
697
+ provider: provider as never,
698
+ tools: { list: () => [], execute: async () => ({ content: "ok" }) } as never,
699
+ }, pollMs);
700
+ }
701
+
702
+ test("a deferred settlement that never clears is abandoned after a stop and recorded", async () => {
703
+ plant("m1.json", "never-clears");
704
+ const c = client();
705
+ let calls = 0;
706
+ const complete = spyOn(c, "completeDelivery").mockImplementation(async () => {
707
+ calls++;
708
+ return { status: "deferred", reason: "storage-error", detail: "permanent storage failure" };
709
+ });
710
+ const events: Array<{ data?: unknown }> = [];
711
+ const loop = settlementLoop(events, completingProvider);
712
+ const source: MailDeliverySource = {
713
+ async deliverNext() {
714
+ const result = await c.deliverNext();
715
+ if (result.status === "delivered") void loop.stop();
716
+ return result;
717
+ },
718
+ completeDelivery: (delivery) => c.completeDelivery(delivery),
719
+ releaseDelivery: (delivery) => c.releaseDelivery(delivery),
720
+ };
721
+ let timer: ReturnType<typeof setTimeout> | undefined;
722
+ try {
723
+ await Promise.race([
724
+ loop.runDeliveries(source),
725
+ new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error("runDeliveries did not return within 5s")), 5_000); }),
726
+ ]);
727
+ } finally {
728
+ clearTimeout(timer);
729
+ complete.mockRestore();
730
+ }
731
+ expect(calls).toBe(20);
732
+ expect(events.some((event) => String(event.data).includes("deferred past the shutdown bound"))).toBe(true);
733
+ }, 10_000);
734
+
735
+ test("a stop during settlement retries still settles when the deferral clears before the bound", async () => {
736
+ plant("m1.json", "clears-in-time");
737
+ const c = client();
738
+ const real = c.completeDelivery.bind(c);
739
+ let attempts = 0;
740
+ const complete = spyOn(c, "completeDelivery").mockImplementation(async (delivery) => {
741
+ attempts++;
742
+ if (attempts <= 3) return { status: "deferred", reason: "lock-busy", detail: "mailbox lock busy; retry" };
743
+ return real(delivery);
744
+ });
745
+ const events: Array<{ data?: unknown }> = [];
746
+ const loop = settlementLoop(events, completingProvider);
747
+ const source: MailDeliverySource = {
748
+ async deliverNext() {
749
+ const result = await c.deliverNext();
750
+ if (result.status === "delivered") void loop.stop();
751
+ return result;
752
+ },
753
+ completeDelivery: (delivery) => c.completeDelivery(delivery),
754
+ releaseDelivery: (delivery) => c.releaseDelivery(delivery),
755
+ };
756
+ let timer: ReturnType<typeof setTimeout> | undefined;
757
+ try {
758
+ await Promise.race([
759
+ loop.runDeliveries(source),
760
+ new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error("runDeliveries did not return within 5s")), 5_000); }),
761
+ ]);
762
+ } finally {
763
+ clearTimeout(timer);
764
+ complete.mockRestore();
765
+ }
766
+ expect(attempts).toBe(4);
767
+ expect(intentPhase("m1.json")).toBeNull();
768
+ expect(events.some((event) => String(event.data).includes("shutdown bound"))).toBe(false);
769
+ }, 10_000);