@afokapu/atdd-flow 0.2.2 → 0.3.0

package/README.md

@@ -163,6 +163,39 @@ atdd-flow launch driver.runtime@resolver-os --application tuios --placement reso
 
 Launch selects a model from `models.yaml`, starts that model's executable in the seat's declared worktree, passes `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, records the selected model on the live runtime binding, and asks the agent to read its seat. Other hosts remain correct without an adapter; their operator supplies that prompt.
 
+### Pi-native Desk mail
+
+When Flow launches the `pi` executable, it automatically loads its bundled Pi extension. Pi remains a normal, interactive agent in its host pane, but the extension watches the immutable Desk mail files and wakes Pi internally with `pi.sendMessage()`—not terminal text injection.
+
+The Pi seat records both concepts independently:
+
+```yaml
+runtime:
+  application: herdr # or tuios
+  addresses:
+    herdr: w9:p1
+  model: pi
+  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.
+
+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.
+
+To host Pi in Herdr, create a pane with the durable Desk and seat identity, then start Pi with the extension supplied by the installed Flow package:
+
+```sh
+PI_EXTENSION="$(atdd-flow pi extension-path)"
+herdr pane split --current --direction right --cwd /path/to/worktree --no-focus \
+  --env ATDD_WORKFLOW_ROOT=/path/to/desk \
+  --env ATDD_WORKFLOW_SEAT=driver.runtime@resolver-os
+# Use the pane id returned above.
+herdr agent start pi-runtime --kind pi --pane <pane-id> -- --extension "$PI_EXTENSION"
+atdd-flow --root /path/to/desk attach driver.runtime@resolver-os --application herdr --wake native
+```
+
+Pi receives its identity and startup task from the extension itself. Its normal TUI remains visible and manually usable; incoming Desk mail wakes it through Pi's native message API.
+
 With ATDD Bun, enable the Workflow profile:
 
 ```yaml

package/extensions/pi/index.ts

@@ -0,0 +1,111 @@
+import * as fs from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+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 };
+
+const finalMail = /^M-[^.]+\.yaml$/;
+
+function participants(thread: Thread) {
+  return Array.isArray(thread.participants) && thread.participants.every((entry) => typeof entry === "string")
+    ? thread.participants as string[]
+    : [];
+}
+
+export function addressedTo(mail: Mail, thread: Thread, seat: string) {
+  if (mail.from === seat) return false;
+  if (Array.isArray(mail.to)) return mail.to.includes(seat);
+  return mail.to === "all" && participants(thread).includes(seat);
+}
+
+/**
+ * A Pi-native wake adapter. The Desk remains authoritative: this extension
+ * only observes final immutable mail files and tells Pi where to read them.
+ */
+export default function (pi: ExtensionAPI) {
+  const root = process.env.ATDD_WORKFLOW_ROOT;
+  const seat = process.env.ATDD_WORKFLOW_SEAT;
+  if (!root || !seat) return;
+
+  const threads = join(root, "threads");
+  const delivered = new Set<string>();
+  const pending = new Set<string>();
+  const threadWatchers = new Map<string, fs.FSWatcher>();
+  let threadsWatcher: fs.FSWatcher | undefined;
+
+  const deliver = (threadId: string, fileName: string) => {
+    const key = `${threadId}/${fileName}`;
+    if (delivered.has(key) || pending.has(key)) return;
+    pending.add(key);
+    setTimeout(async () => {
+      try {
+        const folder = join(threads, threadId);
+        const [rawThread, rawMail] = await Promise.all([
+          readFile(join(folder, "thread.yaml"), "utf8"),
+          readFile(join(folder, fileName), "utf8"),
+        ]);
+        const thread = parse(rawThread) as Thread;
+        const mail = parse(rawMail) as Mail;
+        if (!addressedTo(mail, thread, seat)) return;
+        const id = typeof mail.id === "string" ? mail.id : fileName.slice(0, -5);
+        const file = join(folder, fileName);
+        delivered.add(key);
+        pi.sendMessage({
+          customType: "atdd-flow-mail",
+          content: `SYSTEM: new Flow mail ${id}. Read ${file}`,
+          display: true,
+          details: { thread: threadId, message: id, path: file },
+        }, { triggerTurn: true, deliverAs: "followUp" });
+      } catch {
+        // A later filesystem event can retry an atomic-write race.
+      } finally {
+        pending.delete(key);
+      }
+    }, 25);
+  };
+
+  const watchThread = (threadId: string) => {
+    if (threadWatchers.has(threadId)) return;
+    try {
+      const watcher = fs.watch(join(threads, threadId), (_event, file) => {
+        const name = file?.toString();
+        if (name && finalMail.test(name)) deliver(threadId, name);
+      });
+      threadWatchers.set(threadId, watcher);
+    } catch {
+      // A concurrent thread deletion is harmless.
+    }
+  };
+
+  const discoverThreads = async () => {
+    try {
+      for (const entry of await readdir(threads, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name.startsWith("T-")) watchThread(entry.name);
+      }
+    } catch {
+      // The Desk may be created after Pi starts.
+    }
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    await discoverThreads();
+    try { threadsWatcher = fs.watch(threads, () => { void discoverThreads(); }); }
+    catch { /* The startup prompt still makes the missing Desk visible. */ }
+    pi.sendMessage({
+      customType: "atdd-flow-start",
+      content: `SYSTEM: you are ${seat}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`,
+      display: true,
+      details: { seat, root },
+    }, { triggerTurn: true, deliverAs: "followUp" });
+    if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
+  });
+
+  pi.on("session_shutdown", () => {
+    threadsWatcher?.close();
+    for (const watcher of threadWatchers.values()) watcher.close();
+    threadWatchers.clear();
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   "files": [
     "bin",
     "conventions",
+    "extensions",
     "src",
     "README.md",
     "LICENSE"
@@ -42,6 +43,7 @@
     "@afokapu/atdd-bun": "^0.10.44"
   },
   "dependencies": {
-    "@typesafe-ai/sdk": "^0.6.0"
+    "@typesafe-ai/sdk": "^0.6.0",
+    "yaml": "2.9.0"
   }
 }

package/src/adapters.ts

@@ -27,10 +27,11 @@ export function discoverAddress(application: string, environment: Environment =
 export function notificationCommand(application: string, address: string, notice: string, herdrSession?: string): string[] | undefined {
   const commands: Record<string, () => string[] | undefined> = {
     tmux: () => ["tmux", "send-keys", "-t", address, notice, "Enter"],
-    // A Herdr pane id is the canonical runtime address. `pane send-text` is
-    // supported by both standalone Herdr and TUIOS's embedded Herdr server;
-    // `agent send` is not available on every embedded-server version.
-    herdr: () => ["herdr", ...(herdrSession ? ["--session", herdrSession] : []), "pane", "send-text", address, notice],
+    // Herdr resolves the live agent from its stable pane address and submits
+    // an ordered prompt through its agent-control API. Do not fall back to
+    // pane text injection: a Desk message remains durable when an older host
+    // cannot provide agent.prompt.
+    herdr: () => ["herdr", ...(herdrSession ? ["--session", herdrSession] : []), "agent", "prompt", address, notice],
     tuios: () => {
       const separator = address.indexOf("/");
       if (separator < 1 || separator === address.length - 1) return undefined;

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { basename, resolve } from "node:path";
-import { init, initProject, spawn, bind, useApplication, attach, launch, describe, checkpoint, migrate, openSeat } from "./seats";
+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 * as tasks from "./tasks";
 import { required, values, words } from "./core";
@@ -19,8 +19,9 @@ Usage:
   atdd-flow desk migrate
   atdd-flow project init <project>
   atdd-flow spawn <project> <role> <name> [--worktree <path>] [--branch <branch>] [--agent <legacy-executable>]
-  atdd-flow bind <address> [--application <application>] --address <native-address>
-  atdd-flow attach <address> [--application <application>]
+  atdd-flow bind <address> [--application <application>] --address <native-address> [--wake host|native]
+  atdd-flow attach <address> [--application <application>] [--wake host|native]
+  atdd-flow pi extension-path
   atdd-flow launch <address> --application <application> --placement <native-container-address>
   atdd-flow application use <address> <application>
   atdd-flow describe <address> --purpose <one-line responsibility>
@@ -73,6 +74,10 @@ async function main() {
     spawn: () => spawn(root, required(rest[0], "project"), required(rest[1], "role"), required(rest[2], "name"), rest.slice(3)),
     bind: () => bind(root, required(rest[0], "address"), rest.slice(1)),
     attach: () => attach(root, required(rest[0], "address"), rest.slice(1)),
+    pi: async () => {
+      if (rest[0] === "extension-path") return console.log(piExtensionPath());
+      throw new Error("Use `atdd-flow pi extension-path`.");
+    },
     launch: () => launch(root, required(rest[0], "address"), rest.slice(1)),
     application: async () => {
       if (rest[0] === "use") return useApplication(root, required(rest[1], "address"), required(rest[2], "application"));

package/src/core.ts

@@ -47,7 +47,8 @@ export type Project = {
  * are opaque application-owned locators: Workflow records and returns them,
  * while the relevant bridge is responsible for using their native format.
  */
-export type Runtime = { application: string; addresses: Record<string, string>; attached_at?: string; model?: string };
+/** `native` means the agent runtime wakes itself from the durable Desk. */
+export type Runtime = { application: string; addresses: Record<string, string>; attached_at?: string; model?: string; wake?: "host" | "native" };
 export type Seat = {
   schema: string;
   address: string;

package/src/seats.ts

@@ -1,9 +1,9 @@
 import { existsSync } from "node:fs";
 import { mkdir, readdir } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { discoverAddress, launchedAddress, launchCommand, notify } from "./adapters";
 import {
-  type Checkpoint, type Desk, type ModelCandidate, type ModelPortfolio, type Project, type Role, type Seat,
+  type Checkpoint, type Desk, type ModelCandidate, type ModelPortfolio, type Project, type Role, type Runtime, type Seat,
   atomicYaml, canonicalAddress, desk, exists, fill, migrateDesk, modelPortfolio, now, paths, project, readYaml,
   required, run, runOutput, seat, words, yaml,
 } from "./core";
@@ -93,11 +93,14 @@ export async function spawn(root: string, projectName: string, roleName: string,
   console.log(address);
 }
 
-export async function bind(root: string, address: string, args: string[], selectedModel?: string) {
+export async function bind(root: string, address: string, args: string[], selectedModel?: string, wake?: Runtime["wake"]) {
   const resolved = await canonicalAddress(root, address);
   const record = await seat(root, resolved);
   const config = await desk(root);
   const application = words(args, "--application") ?? config.application;
+  const requestedWake = words(args, "--wake");
+  if (requestedWake && requestedWake !== "host" && requestedWake !== "native") throw new Error("Wake must be host or native.");
+  const selectedWake = wake ?? requestedWake as Runtime["wake"] | undefined;
   if (!/^[a-z][a-z0-9_-]*$/.test(application)) throw new Error(`Application must use lowercase letters, numbers, underscores, or hyphens: ${application}`);
   const nativeAddress = required(words(args, "--address"), "--address");
   const addresses = record.runtime?.addresses ?? {};
@@ -107,6 +110,7 @@ export async function bind(root: string, address: string, args: string[], select
     addresses: { ...addresses, [application]: nativeAddress },
     attached_at: now(),
     ...(selectedModel ? { model: selectedModel } : {}),
+    ...(selectedWake ? { wake: selectedWake } : {}),
   };
   await atomicYaml(paths(root).seatFile(resolved), record);
   console.log(`Bound ${resolved} to ${application}:${nativeAddress}`);
@@ -125,7 +129,8 @@ export async function useApplication(root: string, address: string, application:
 export async function attach(root: string, address: string, args: string[]) {
   const application = words(args, "--application") ?? (await desk(root)).application;
   const nativeAddress = discoverAddress(application);
-  await bind(root, address, ["--application", application, "--address", nativeAddress]);
+  const wake = words(args, "--wake");
+  await bind(root, address, ["--application", application, "--address", nativeAddress, ...(wake ? ["--wake", wake] : [])]);
 }
 
 export function availableModelCandidates(config: Desk, portfolio: ModelPortfolio) {
@@ -166,6 +171,11 @@ async function chooseLaunchModel(root: string, config: Desk, record: Seat, portf
 export const launchNotice = (address: string) =>
   `SYSTEM: you are ${address}. Read your durable seat and assigned task with: atdd-flow open ${address}. Use the installed atdd-flow command; never use bunx to replace it or run atdd-flow init against an existing Desk. If your native pane binding differs from the Desk record, report it to the operator or coordinator. Continue assigned in_progress work until it is review-ready or explicitly blocked.`;
 
+/** Pi loads this extension inside its own process, so it can wake without host text injection. */
+export const piExtensionPath = () => join(import.meta.dir, "..", "extensions", "pi", "index.ts");
+export const isPiExecutable = (agent: string) => basename(agent) === "pi";
+export const piLaunchArgs = (agent: string, args: string[]) => isPiExecutable(agent) ? [...args, "--extension", piExtensionPath()] : args;
+
 export async function launch(root: string, address: string, args: string[]) {
   const resolved = await canonicalAddress(root, address);
   const record = await seat(root, resolved);
@@ -187,12 +197,15 @@ export async function launch(root: string, address: string, args: string[]) {
     agent = resolveExecutable(config, legacyAgent);
     selectedModel = legacyAgent;
   }
+  const wake: Runtime["wake"] = isPiExecutable(agent) ? "native" : "host";
+  modelArgs = piLaunchArgs(agent, modelArgs);
   const output = await runOutput(launchCommand({
     application, placement, name: resolved, worktree: record.worktree,
     agent, args: modelArgs, root, seat: resolved,
   }));
   const nativeAddress = launchedAddress(application, placement, output);
-  await bind(root, resolved, ["--application", application, "--address", nativeAddress], selectedModel);
+  await bind(root, resolved, ["--application", application, "--address", nativeAddress], selectedModel, wake);
+  if (wake === "native") return;
   const notice = launchNotice(resolved);
   try { await notify(application, nativeAddress, notice, config.herdr_session); }
   catch (error) { console.warn(`Launch notification for ${resolved} was not delivered: ${(error as Error).message}`); }

package/src/threads.ts

@@ -65,6 +65,7 @@ async function inject(root: string, address: string, message: Message, threadId:
   const target = await seat(root, address);
   const runtime = target.runtime;
   if (!runtime) return;
+  if (runtime.wake === "native") return;
   const nativeAddress = runtime.addresses[runtime.application];
   if (!nativeAddress) return;
   const file = paths(root).message(threadId, message.id);