@afokapu/atdd-flow 0.3.5 → 0.3.7

package/README.md

@@ -178,7 +178,15 @@ runtime:
   wake: native
 ```
 
-`application` identifies the visible pane. `wake: native` tells Flow not to also send a host prompt; the Pi extension reads `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, observes final `M-*.yaml` files, filters recipients, and queues a follow-up turn that tells Pi which durable file to read. Other agents keep `wake: host` and use their normal host notification adapter.
+`application` identifies the visible pane. `wake: native` tells Flow not to also send a host prompt; the Pi extension reads `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, observes final `M-*.yaml` files, filters recipients, and queues a compact follow-up containing the thread subject, sender, recipients, thread/message IDs, and `atdd-flow message read <message-id>`. It never embeds the message body. Other agents keep `wake: host` and receive the same compact notification through their normal host adapter.
+
+Read one durable message without loading its complete thread:
+
+```sh
+atdd-flow message read M-...
+```
+
+The output includes only the message and its thread ID/subject; Flow rejects missing or ambiguous message IDs.
 
 Pi’s native wake-up is intentionally lightweight: no daemon, duplicate mailbox, or separate extension installation. The extension is shipped inside the Flow package. Its in-memory message-id guard tolerates duplicate filesystem events; the Desk thread files remain the source of truth.
 

package/extensions/pi/index.ts

@@ -4,8 +4,8 @@ import { join } from "node:path";
 import { parse } from "yaml";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-type Thread = { participants?: unknown };
-type Mail = { id?: unknown; from?: unknown; to?: unknown };
+type Thread = { participants?: unknown; subject?: unknown };
+type Mail = { id?: unknown; from?: unknown; to?: unknown; subject?: unknown };
 
 const finalMail = /^M-[^.]+\.yaml$/;
 
@@ -21,6 +21,15 @@ export function addressedTo(mail: Mail, thread: Thread, seat: string) {
   return mail.to === "all" && participants(thread).includes(seat);
 }
 
+/** A compact wake notice; the durable message body is read only on demand. */
+export function mailNotice(threadId: string, mail: Mail) {
+  const id = typeof mail.id === "string" ? mail.id : "unknown";
+  const subject = typeof mail.subject === "string" ? mail.subject : undefined;
+  const from = typeof mail.from === "string" ? mail.from : "unknown";
+  const recipients = mail.to === "all" ? "all" : Array.isArray(mail.to) ? mail.to.join(", ") : "unknown";
+  return `SYSTEM: Flow mail ${id} | thread ${threadId}${subject ? ` (${subject})` : ""} | ${from} → ${recipients}. Read: atdd-flow message read ${id}`;
+}
+
 /**
  * A Pi-native wake adapter. The Desk remains authoritative: this extension
  * only observes final immutable mail files and tells Pi where to read them.
@@ -55,7 +64,7 @@ export default function (pi: ExtensionAPI) {
         delivered.add(key);
         pi.sendMessage({
           customType: "atdd-flow-mail",
-          content: `SYSTEM: new Flow mail ${id}. Read ${file}`,
+          content: mailNotice(threadId, { ...mail, id, subject: typeof thread.subject === "string" ? thread.subject : undefined }),
           display: true,
           details: { thread: threadId, message: id, path: file },
         }, { triggerTurn: true, deliverAs: "followUp" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "bun": ">=1.3.0"
   },
   "devDependencies": {
-    "@afokapu/atdd-bun": "^0.10.44"
+    "@afokapu/atdd-bun": "^0.10.50"
   },
   "dependencies": {
     "@typesafe-ai/sdk": "^0.6.0",

package/src/cli.ts

@@ -2,7 +2,7 @@
 
 import { basename, resolve } from "node:path";
 import { init, initProject, spawn, bind, useApplication, attach, launch, describe, checkpoint, migrate, openSeat, piExtensionPath } from "./seats";
-import { addParticipant, openThread, post, receipt, result, startThread } from "./threads";
+import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
 import { required, values, words } from "./core";
 import { addressBook } from "./address-book";
@@ -41,6 +41,7 @@ Usage:
   atdd-flow thread start --with <address,...> --subject <text> [--task <project/task-id>]
   atdd-flow thread add <thread-id> <address>
   atdd-flow thread open <thread-id>
+  atdd-flow message read <message-id>
   atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--expects-result]
   atdd-flow receipt <thread-id> <message-id> --from <address> [--body <text>]
   atdd-flow result <thread-id> <message-id> --from <address> --body <text>
@@ -113,6 +114,10 @@ async function main() {
       if (subcommand === "open") return openThread(root, required(tail[0], "thread id"));
       throw new Error("Use `atdd-flow thread start|add|open`.");
     },
+    message: async () => {
+      if (rest[0] === "read") return readMessage(root, required(rest[1], "message id"));
+      throw new Error("Use `atdd-flow message read <message-id>`.");
+    },
     post: () => post(root, required(rest[0], "thread id"), rest.slice(1)),
     receipt: () => receipt(root, required(rest[0], "thread id"), required(rest[1], "message id"), rest.slice(2)),
     result: () => result(root, required(rest[0], "thread id"), required(rest[1], "message id"), rest.slice(2)),

package/src/threads.ts

@@ -81,8 +81,10 @@ async function inject(root: string, address: string, message: Message, threadId:
   if (runtime.wake === "native") return;
   const nativeAddress = runtime.addresses[runtime.application];
   if (!nativeAddress) return;
-  const file = paths(root).message(threadId, message.id);
-  const notice = `SYSTEM: new thread mail ${message.id} from ${message.from}. Read ${file}`;
+  const record = await thread(root, threadId);
+  const recipients = message.to === "all" ? "all" : message.to.join(", ");
+  const subject = record.subject.replace(/\s+/g, " ").trim();
+  const notice = `SYSTEM: Flow mail ${message.id} | thread ${threadId} (${subject}) | ${message.from} → ${recipients}. Read: atdd-flow message read ${message.id}`;
   try { await notify(runtime.application, nativeAddress, notice, (await desk(root)).herdr_session); }
   catch (error) { console.warn(`Notification for ${address} was not delivered: ${(error as Error).message}`); }
 }
@@ -132,6 +134,28 @@ export async function openThread(root: string, threadId: string) {
   console.log(Bun.YAML.stringify({ ...record, messages: all }));
 }
 
+/** Reads one durable message without loading or printing its whole thread. */
+export async function readMessage(root: string, messageId: string) {
+  if (!/^M-[A-Za-z0-9_-]+$/.test(messageId)) throw new Error(`Invalid message id: ${messageId}.`);
+  const folders = await readdir(paths(root).threads, { withFileTypes: true });
+  const matches = await Promise.all(folders
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith("T-"))
+    .map(async (entry) => {
+      const file = paths(root).message(entry.name, messageId);
+      try { return { thread: await thread(root, entry.name), message: await readYaml<Message>(file) }; }
+      catch { return undefined; }
+    }));
+  const found = matches.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry));
+  if (!found.length) throw new Error(`Message ${messageId} does not exist in this Desk.`);
+  if (found.length > 1) throw new Error(`Message ${messageId} is ambiguous across threads: ${found.map((entry) => entry.thread.id).join(", ")}.`);
+  const entry = found[0];
+  console.log(Bun.YAML.stringify({
+    schema: "atdd-workflow/message-read/v1",
+    thread: { id: entry.thread.id, subject: entry.thread.subject },
+    message: entry.message,
+  }));
+}
+
 export async function receipt(root: string, threadId: string, messageId: string, args: string[]) {
   const from = await canonicalAddress(root, required(words(args, "--from"), "--from"));
   const target = await replyTarget(root, threadId, messageId, from, false);