@tpsdev-ai/agent 0.5.4 → 0.7.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 (64) hide show
  1. package/dist/bin.js +47 -2
  2. package/dist/bin.js.map +1 -1
  3. package/dist/config.d.ts +2 -1
  4. package/dist/config.d.ts.map +1 -1
  5. package/dist/config.js +8 -0
  6. package/dist/config.js.map +1 -1
  7. package/dist/index.d.ts +4 -0
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +4 -0
  10. package/dist/index.js.map +1 -1
  11. package/dist/io/flair.d.ts +53 -0
  12. package/dist/io/flair.d.ts.map +1 -0
  13. package/dist/io/flair.js +157 -0
  14. package/dist/io/flair.js.map +1 -0
  15. package/dist/io/mail.d.ts +39 -2
  16. package/dist/io/mail.d.ts.map +1 -1
  17. package/dist/io/mail.js +303 -15
  18. package/dist/io/mail.js.map +1 -1
  19. package/dist/lib/signEnvelope.d.ts +67 -0
  20. package/dist/lib/signEnvelope.d.ts.map +1 -0
  21. package/dist/lib/signEnvelope.js +244 -0
  22. package/dist/lib/signEnvelope.js.map +1 -0
  23. package/dist/llm/provider.d.ts +19 -1
  24. package/dist/llm/provider.d.ts.map +1 -1
  25. package/dist/llm/provider.js +362 -18
  26. package/dist/llm/provider.js.map +1 -1
  27. package/dist/runtime/agent.d.ts +2 -0
  28. package/dist/runtime/agent.d.ts.map +1 -1
  29. package/dist/runtime/agent.js +53 -3
  30. package/dist/runtime/agent.js.map +1 -1
  31. package/dist/runtime/event-loop.d.ts +36 -5
  32. package/dist/runtime/event-loop.d.ts.map +1 -1
  33. package/dist/runtime/event-loop.js +235 -32
  34. package/dist/runtime/event-loop.js.map +1 -1
  35. package/dist/runtime/types.d.ts +16 -1
  36. package/dist/runtime/types.d.ts.map +1 -1
  37. package/dist/telemetry/events.d.ts +57 -0
  38. package/dist/telemetry/events.d.ts.map +1 -0
  39. package/dist/telemetry/events.js +37 -0
  40. package/dist/telemetry/events.js.map +1 -0
  41. package/dist/tools/edit.d.ts.map +1 -1
  42. package/dist/tools/edit.js +94 -16
  43. package/dist/tools/edit.js.map +1 -1
  44. package/package.json +10 -2
  45. package/src/bin.ts +56 -3
  46. package/src/config.ts +10 -1
  47. package/src/index.ts +8 -0
  48. package/src/io/flair.ts +197 -0
  49. package/src/io/mail.ts +341 -19
  50. package/src/lib/signEnvelope.ts +332 -0
  51. package/src/llm/provider.ts +391 -17
  52. package/src/runtime/agent.ts +58 -3
  53. package/src/runtime/event-loop.ts +233 -15
  54. package/src/runtime/types.ts +20 -1
  55. package/src/telemetry/events.ts +101 -0
  56. package/src/tools/edit.ts +108 -17
  57. package/test/bin-launch-id.test.ts +104 -0
  58. package/test/core-loop.test.ts +240 -0
  59. package/test/events.test.ts +33 -0
  60. package/test/flair-context.test.ts +102 -0
  61. package/test/governance.test.ts +103 -2
  62. package/test/io.test.ts +13 -14
  63. package/test/mail-promote-guard.test.ts +325 -0
  64. package/test/provider.test.ts +43 -0
package/src/io/mail.ts CHANGED
@@ -1,10 +1,61 @@
1
- import { existsSync, mkdirSync, readdirSync, renameSync, readFileSync } from "node:fs";
1
+ import { existsSync, mkdirSync, readdirSync, renameSync, readFileSync, writeFileSync } from "node:fs";
2
2
  import { join } from "node:path";
3
+ import type { EventLogger } from "../telemetry/events.js";
4
+ import { sanitizeError } from "../telemetry/events.js";
5
+ import { verifyEnvelope, type FlairClient } from "../lib/signEnvelope.js";
3
6
 
4
7
  export interface MailMessage {
5
8
  filename: string;
6
9
  body: string;
7
10
  receivedAt: Date;
11
+ /** Trust/routing headers from bridge envelope */
12
+ headers: Record<string, string>;
13
+ /** Sender agent ID */
14
+ from: string;
15
+ }
16
+
17
+ /**
18
+ * The mailbox reject classes this path can emit. It uses the SHARED class NAMES
19
+ * (`invalid`, `unresolvable-principal`, `wrong-recipient`) so a dlq sidecar it
20
+ * writes is readable by the shared tooling. It is NOT the full shared class set:
21
+ * this path emits only TERMINAL classes — an outage is refused, not
22
+ * dead-lettered (the record stays in `new/`), so no retryable class is written
23
+ * here.
24
+ */
25
+ type MailboxRejectClass = "invalid" | "unresolvable-principal" | "wrong-recipient";
26
+
27
+ type VerifyOutcome =
28
+ | { pass: true }
29
+ | { pass: false; class: MailboxRejectClass; reason: string; from?: string };
30
+
31
+ /**
32
+ * The stable reason string `verifyEnvelope` returns when an agent-kind chain
33
+ * entry or `envelope.from` cannot be resolved from the LOCAL Flair. An ABSENT
34
+ * principal is a topology condition, not a forgery verdict, so it is labelled
35
+ * `unresolvable-principal` rather than `invalid`. Duplicated from the shared
36
+ * promotion boundary because `@tpsdev-ai/agent` cannot import `packages/cli`
37
+ * (the dependency runs the other way: cli → agent).
38
+ */
39
+ const UNRESOLVABLE_PRINCIPAL_REASON_RE = /^agent (.+) not found in Flair$/;
40
+
41
+ /**
42
+ * Write the dlq sidecar for a TERMINAL rejection.
43
+ *
44
+ * It mirrors the shared mail convention's FORMAT — file name `<record>.reason`
45
+ * and a first line `class: <class>`, the shape the shared re-drive's
46
+ * `readReasonSidecar` parses — and reuses the shared class NAMES. It does NOT
47
+ * reproduce the shared reject boundary: only the terminal classes above are
48
+ * emitted, and a retryable outcome (Flair unreachable) writes NO sidecar at all
49
+ * (the record is left in `new/`). So it is "format + the terminal class names
50
+ * this path emits", not the full boundary. (This path previously wrote
51
+ * `${file}.reject` with a bare reason, which no shared reader scans.)
52
+ */
53
+ function writeRejectSidecar(dlqDir: string, filename: string, cls: MailboxRejectClass, reason: string): void {
54
+ writeFileSync(
55
+ join(dlqDir, `${filename}.reason`),
56
+ `class: ${cls}\nPromote rejected at ${new Date().toISOString()}\nReason: ${reason}\n`,
57
+ "utf-8",
58
+ );
8
59
  }
9
60
 
10
61
  /**
@@ -15,31 +66,154 @@ export interface MailMessage {
15
66
  export class MailClient {
16
67
  private inboxNew: string;
17
68
  private inboxCur: string;
69
+ private inboxDlq: string;
18
70
  private outboxNew: string;
71
+ /** One-shot guard so a misconfigured (verifier-less) mailbox warns once, not per poll. */
72
+ private warnedNoVerifier = false;
19
73
 
20
- constructor(public readonly mailDir: string) {
21
- this.inboxNew = join(mailDir, "inbox", "new");
22
- this.inboxCur = join(mailDir, "inbox", "cur");
23
- this.outboxNew = join(mailDir, "outbox", "new");
24
- // Ensure directories exist
25
- for (const dir of [this.inboxNew, this.inboxCur, this.outboxNew]) {
74
+ constructor(
75
+ public readonly mailDir: string,
76
+ private readonly events?: EventLogger,
77
+ private readonly agentId = "unknown",
78
+ private readonly flairClient?: FlairClient,
79
+ ) {
80
+ this.inboxNew = join(mailDir, agentId, "new");
81
+ this.inboxCur = join(mailDir, agentId, "cur");
82
+ this.inboxDlq = join(mailDir, agentId, "dlq");
83
+ this.outboxNew = join(mailDir, agentId, "outbox");
84
+ for (const dir of [this.inboxNew, this.inboxCur, this.inboxDlq, this.outboxNew]) {
26
85
  mkdirSync(dir, { recursive: true });
27
86
  }
28
87
  }
29
88
 
30
- /** Return all messages in inbox/new and move them to inbox/cur. */
89
+ /**
90
+ * Return all messages in inbox/new and move them to inbox/cur/.
91
+ *
92
+ * Verification is MANDATORY — a record is promoted ONLY after its signed
93
+ * envelope verifies against the local Flair. There is no unverified path:
94
+ * - NO verifier configured → refuse; the record stays in new/ (an absent
95
+ * client must never mean "promote without verifying");
96
+ * - the verifier THROWS (Flair unreachable) → refuse; the record stays in
97
+ * new/ for a later check (a throw must never mean "pass");
98
+ * - the verifier REJECTS → dead-letter to dlq/ with a `.reason` sidecar.
99
+ * Unverified input must never reach the tool-holding model.
100
+ */
31
101
  async checkNewMail(): Promise<MailMessage[]> {
32
102
  if (!existsSync(this.inboxNew)) return [];
33
103
 
34
104
  const files = readdirSync(this.inboxNew).filter((f) => !f.startsWith(".") && !f.includes("/") && !f.includes("\\"));
35
105
  const messages: MailMessage[] = [];
36
106
 
107
+ // No verifier → NOTHING is promotable. Refuse (never rename into cur/) and
108
+ // leave the records in new/ so a later check with a verifier — or the
109
+ // shared promote() path — can process them.
110
+ if (!this.flairClient) {
111
+ if (files.length === 0) return [];
112
+ this.events?.emit({
113
+ type: "mail.receive",
114
+ agent: this.agentId,
115
+ status: "rejected",
116
+ from: "unknown",
117
+ durationMs: 0,
118
+ error: "no verifier configured — refusing to promote unverified mail",
119
+ });
120
+ if (!this.warnedNoVerifier) {
121
+ this.warnedNoVerifier = true;
122
+ console.error(
123
+ `[MailClient] no Flair verifier configured for "${this.agentId}": refusing to promote ` +
124
+ `${files.length} unverified message(s) from new/. Unverified input must never reach the ` +
125
+ `model — configure flair (url + key) or promote through the shared promote() lifecycle.`,
126
+ );
127
+ }
128
+ return [];
129
+ }
130
+
37
131
  for (const file of files) {
132
+ const started = Date.now();
38
133
  const srcPath = join(this.inboxNew, file);
39
- const dstPath = join(this.inboxCur, file);
40
- const body = readFileSync(srcPath, "utf-8");
41
- renameSync(srcPath, dstPath);
42
- messages.push({ filename: file, body, receivedAt: new Date() });
134
+
135
+ let body: string;
136
+ try {
137
+ body = readFileSync(srcPath, "utf-8");
138
+ } catch (err) {
139
+ this.events?.emit({
140
+ type: "mail.receive",
141
+ agent: this.agentId,
142
+ status: "error",
143
+ from: "unknown",
144
+ durationMs: Date.now() - started,
145
+ error: sanitizeError(err),
146
+ });
147
+ continue; // leave in new/ — a later check retries
148
+ }
149
+
150
+ // Verify. A THROW is a refusal, not a pass: leave the record in new/ for a
151
+ // later check (a Flair outage self-heals) and never promote it.
152
+ let verifyResult: VerifyOutcome;
153
+ try {
154
+ verifyResult = await this.verifyMailBody(body);
155
+ } catch (err) {
156
+ const detail = sanitizeError(err);
157
+ this.events?.emit({
158
+ type: "mail.receive",
159
+ agent: this.agentId,
160
+ status: "error",
161
+ from: "unknown",
162
+ durationMs: Date.now() - started,
163
+ error: detail,
164
+ });
165
+ console.error(`[MailClient] verification could not run for ${file} — NOT promoting: ${detail}`);
166
+ continue; // leave in new/
167
+ }
168
+
169
+ if (!verifyResult.pass) {
170
+ const dlqPath = join(this.inboxDlq, file);
171
+ try {
172
+ if (srcPath !== dlqPath) renameSync(srcPath, dlqPath);
173
+ writeRejectSidecar(this.inboxDlq, file, verifyResult.class, verifyResult.reason);
174
+ } catch (err) {
175
+ console.error(`[MailClient] failed to dead-letter ${file}: ${sanitizeError(err)}`);
176
+ }
177
+ this.events?.emit({
178
+ type: "mail.receive",
179
+ agent: this.agentId,
180
+ status: "rejected",
181
+ from: verifyResult.from ?? "unknown",
182
+ durationMs: Date.now() - started,
183
+ error: verifyResult.reason,
184
+ });
185
+ continue;
186
+ }
187
+
188
+ // Promote to cur/ — verified, and addressed to this mailbox.
189
+ try {
190
+ const dstPath = join(this.inboxCur, file);
191
+ renameSync(srcPath, dstPath);
192
+ let headers: Record<string, string> = {};
193
+ let from = "unknown";
194
+ try {
195
+ const parsed = JSON.parse(body);
196
+ headers = parsed.headers ?? {};
197
+ from = parsed.from ?? "unknown";
198
+ } catch {}
199
+ messages.push({ filename: file, body, receivedAt: new Date(), headers, from });
200
+ this.events?.emit({
201
+ type: "mail.receive",
202
+ agent: this.agentId,
203
+ status: "ok",
204
+ from,
205
+ durationMs: Date.now() - started,
206
+ });
207
+ } catch (err) {
208
+ this.events?.emit({
209
+ type: "mail.receive",
210
+ agent: this.agentId,
211
+ status: "error",
212
+ from: "unknown",
213
+ durationMs: Date.now() - started,
214
+ error: sanitizeError(err),
215
+ });
216
+ }
43
217
  }
44
218
 
45
219
  return messages;
@@ -47,12 +221,160 @@ export class MailClient {
47
221
 
48
222
  /** Write a message to outbox/new for relay delivery. */
49
223
  async sendMail(to: string, body: string): Promise<void> {
50
- const { writeFileSync } = await import("node:fs");
51
- const filename = `${Date.now()}-${Math.random().toString(36).slice(2)}.json`;
52
- writeFileSync(
53
- join(this.outboxNew, filename),
54
- JSON.stringify({ to, body, sentAt: new Date().toISOString() }, null, 2),
55
- "utf-8"
56
- );
224
+ const started = Date.now();
225
+ try {
226
+ const { writeFileSync } = await import("node:fs");
227
+ const filename = `${Date.now()}-${Math.random().toString(36).slice(2)}.json`;
228
+ writeFileSync(
229
+ join(this.outboxNew, filename),
230
+ JSON.stringify({ to, body, sentAt: new Date().toISOString() }, null, 2),
231
+ "utf-8"
232
+ );
233
+ this.events?.emit({
234
+ type: "mail.send",
235
+ agent: this.agentId,
236
+ to,
237
+ status: "ok",
238
+ durationMs: Date.now() - started,
239
+ });
240
+ } catch (err) {
241
+ this.events?.emit({
242
+ type: "mail.send",
243
+ agent: this.agentId,
244
+ to,
245
+ status: "error",
246
+ durationMs: Date.now() - started,
247
+ error: sanitizeError(err),
248
+ });
249
+ throw err;
250
+ }
251
+ }
252
+
253
+ /** Deliver all messages in outbox to recipient inboxes (local relay). */
254
+ deliverOutbox(): void {
255
+ if (!existsSync(this.outboxNew)) return;
256
+ const files = readdirSync(this.outboxNew).filter(f => !f.startsWith("."));
257
+ for (const file of files) {
258
+ const srcPath = join(this.outboxNew, file);
259
+ try {
260
+ const raw = readFileSync(srcPath, "utf-8");
261
+ const msg = JSON.parse(raw) as { to: string; body: string; sentAt: string };
262
+ if (!msg.to || !/^[a-zA-Z0-9_-]{1,64}$/.test(msg.to)) {
263
+ continue; // skip invalid recipients
264
+ }
265
+ const recipientInbox = join(this.mailDir, msg.to, "new");
266
+ mkdirSync(recipientInbox, { recursive: true });
267
+ const destFile = `${msg.sentAt.replace(/[:.]/g, "-")}-${file}`;
268
+ renameSync(srcPath, join(recipientInbox, destFile));
269
+ } catch {
270
+ // Leave in outbox on error
271
+ }
272
+ }
273
+ }
274
+
275
+ /**
276
+ * Verify a mail body against the v1 signed envelope spec AND this mailbox's
277
+ * policy: signature, wrapper→envelope `from` binding, recipient binding
278
+ * (`envelope.to` must be this mailbox's agent), and `messageId`/`timestamp`
279
+ * shape. These are the checks the shared `promote()` applies, so this path
280
+ * cannot present mail the shared path would reject.
281
+ *
282
+ * Returns a terminal `{ pass: false, class, reason }` on a deterministic
283
+ * rejection. Called ONLY when a verifier is configured; a THROW (Flair
284
+ * unreachable) is a refusal the caller acts on, never a pass.
285
+ */
286
+ private async verifyMailBody(body: string): Promise<VerifyOutcome> {
287
+ const client = this.flairClient!;
288
+
289
+ // 1. Parse the mail file as JSON
290
+ let mailMsg: { from?: string; body: string };
291
+ try {
292
+ mailMsg = JSON.parse(body);
293
+ } catch {
294
+ return { pass: false, class: "invalid", reason: "json parse error: invalid JSON" };
295
+ }
296
+
297
+ if (!mailMsg.body || typeof mailMsg.body !== "string") {
298
+ return { pass: false, class: "invalid", reason: "json parse error: missing body field" };
299
+ }
300
+
301
+ // 2. Parse the body field as an envelope
302
+ let envelope: unknown;
303
+ try {
304
+ envelope = JSON.parse(mailMsg.body);
305
+ } catch {
306
+ return { pass: false, class: "invalid", reason: "json parse error: invalid envelope body", from: mailMsg.from };
307
+ }
308
+
309
+ if (envelope == null || typeof envelope !== "object" || Array.isArray(envelope)) {
310
+ return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
311
+ }
312
+
313
+ const env = envelope as Record<string, unknown>;
314
+ if (
315
+ typeof env.v !== "number" ||
316
+ !Array.isArray(env.delegationChain) ||
317
+ typeof env.signature !== "string"
318
+ ) {
319
+ return { pass: false, class: "invalid", reason: "unsigned envelope (v1 required)", from: mailMsg.from };
320
+ }
321
+
322
+ // 3. Verify the signature. A THROW here (Flair unreachable) is NOT a pass —
323
+ // it propagates to checkNewMail(), which refuses to promote and leaves
324
+ // the record in new/ for a later check. The verifier adapter throws on an
325
+ // outage, so an outage is RETRYABLE rather than a terminal "not found".
326
+ const vr = await verifyEnvelope(env as any, client);
327
+ if (!vr.ok) {
328
+ const cls: MailboxRejectClass = UNRESOLVABLE_PRINCIPAL_REASON_RE.test(vr.reason)
329
+ ? "unresolvable-principal"
330
+ : "invalid";
331
+ return { pass: false, class: cls, reason: vr.reason, from: mailMsg.from };
332
+ }
333
+
334
+ // 4. The wrapper `from` is what consumers route by, and it is unverified; a
335
+ // wrapper/envelope mismatch is itself a reject.
336
+ if (mailMsg.from !== env.from) {
337
+ return {
338
+ pass: false,
339
+ class: "invalid",
340
+ reason: `wrapper/envelope from mismatch (wrapper.from=${String(mailMsg.from)}, envelope.from=${String(env.from)})`,
341
+ from: mailMsg.from,
342
+ };
343
+ }
344
+
345
+ // 5. Recipient binding. A signature is NOT recipient-bound, so a correctly
346
+ // signed envelope addressed to another principal must not be presented
347
+ // here (deliverOutbox writes into any recipient's new/).
348
+ if (env.to !== this.agentId) {
349
+ return {
350
+ pass: false,
351
+ class: "wrong-recipient",
352
+ reason: `wrong-recipient (envelope.to=${String(env.to)}, mailbox=${this.agentId})`,
353
+ from: mailMsg.from,
354
+ };
355
+ }
356
+
357
+ // 6. `messageId` shape.
358
+ if (typeof env.messageId !== "string" || env.messageId.trim() === "") {
359
+ return {
360
+ pass: false,
361
+ class: "invalid",
362
+ reason: `invalid messageId (must be a non-empty string, got ${JSON.stringify(env.messageId)})`,
363
+ from: mailMsg.from,
364
+ };
365
+ }
366
+
367
+ // 7. `timestamp` shape — a malformed/absent timestamp must not be silently
368
+ // accepted (the shared path rejects it too).
369
+ if (typeof env.timestamp !== "string" || Number.isNaN(Date.parse(env.timestamp))) {
370
+ return {
371
+ pass: false,
372
+ class: "invalid",
373
+ reason: `invalid timestamp (must be an ISO-8601 string, got ${JSON.stringify(env.timestamp)})`,
374
+ from: mailMsg.from,
375
+ };
376
+ }
377
+
378
+ return { pass: true };
57
379
  }
58
380
  }